# Feature Spec: Quality + Adoption Execution Master Index (AOP)

> **Purpose of this document**: Serve as the orchestration index for split implementation specs covering Q1-Q12. Detailed implementation requirements live in the feature-set specs listed below.

**Version:** 1.3  
**Date:** 2026-03-16  
**Status:** Draft (Audited Against Current Repo State)  
**Roadmap Window:** M33-M38

---

## 1. Why This Split Exists

The original monolithic execution document covered too many orthogonal concerns in one spec. It is now split into focused specs by feature set so future agents can execute with clearer boundaries, lower context cost, and cleaner milestone ownership.

---

## 2. Canonical Split Specs

### 2.1 Observability/Replay (M33a)

- `spec-files/outstanding/agentic_orchestrator_observability_replay_spec.md`

Implements:

- Q3 Deterministic Replay + Time-Travel Debugger

### 2.2 Evidence Integrity + Doctor (M33b)

- `spec-files/outstanding/agentic_orchestrator_evidence_integrity_doctor_spec.md`

Implements:

- Q4 Tamper-Evident Evidence Chain
- Q11 `aop doctor` Readiness + Drift Scanner

### 2.3 Planning/Review Quality Hardening (M34-M36)

- `spec-files/outstanding/agentic_orchestrator_planning_review_quality_spec.md`

Implements:

- Q1 Semantic Collision Engine
- Q2 Plan Feasibility Scoring
- Q7 Prompt Contract Test Harness
- Q8 Flaky Gate Intelligence + Quarantine Workflow
- Q9 Auto-Generated Review Briefs

### 2.4 Enterprise Governance + Secure Dashboard (M37)

- `spec-files/outstanding/agentic_orchestrator_enterprise_governance_dashboard_spec.md`

Implements:

- Q5 Compliance Policy Packs + Control Export
- Q6 Dashboard AuthN/AuthZ + SSO + Audit Federation

### 2.5 Knowledge Retrieval (M38)

- `spec-files/outstanding/agentic_orchestrator_knowledge_canary_spec.md`

Implements:

- Q10 Cross-Feature Knowledge Graph

Tracks decision:

- Q12 Progressive Merge Guardrails (Canary Verification) is deferred in its original form because the reconciler now covers the primary mainline-divergence risk class and the old canary lifecycle conflicts with current merge cleanup semantics.

---

## 3. Feature Outcome Matrix

| ID  | Feature                      | Primary Outcome                                    | Detailed Spec                                                  |
| --- | ---------------------------- | -------------------------------------------------- | -------------------------------------------------------------- |
| Q1  | Semantic Collision Engine    | Fewer hidden integration conflicts before build/QA | `agentic_orchestrator_planning_review_quality_spec.md`         |
| Q2  | Plan Feasibility Scoring     | Early detection of weak plans                      | `agentic_orchestrator_planning_review_quality_spec.md`         |
| Q3  | Replay + Time-Travel         | Faster incident RCA                                | `agentic_orchestrator_observability_replay_spec.md`            |
| Q4  | Tamper-Evident Evidence      | Stronger audit trust                               | `agentic_orchestrator_evidence_integrity_doctor_spec.md`       |
| Q5  | Compliance Packs + Export    | Faster enterprise onboarding                       | `agentic_orchestrator_enterprise_governance_dashboard_spec.md` |
| Q6  | Dashboard Auth + SSO + Audit | Production-safe dashboard operation                | `agentic_orchestrator_enterprise_governance_dashboard_spec.md` |
| Q7  | Prompt Contract Tests        | Prompt regression prevention                       | `agentic_orchestrator_planning_review_quality_spec.md`         |
| Q8  | Flaky Intelligence           | Higher gate signal quality                         | `agentic_orchestrator_planning_review_quality_spec.md`         |
| Q9  | Review Briefs                | Faster/high-quality human review                   | `agentic_orchestrator_planning_review_quality_spec.md`         |
| Q10 | Knowledge Graph              | Better cross-feature reuse                         | `agentic_orchestrator_knowledge_canary_spec.md`                |
| Q11 | `aop doctor`                 | Faster readiness/drift triage                      | `agentic_orchestrator_evidence_integrity_doctor_spec.md`       |
| Q12 | Canary Merge Verification    | Deferred pending proof of merged-head-only need    | Deferred by `agentic_orchestrator_knowledge_canary_spec.md`    |

---

## 4. Current Implementation Snapshot (2026-03-16)

This master index now reflects the repo as it exists today, not the original March 3 planning state.

| Milestone                | Status                                        | Current State                                                                                                                                                                                                                  |
| ------------------------ | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| M33a / Q3                | Implemented                                   | Replay timeline service, policy/schema scaffolding, `replay.timeline_get`, and `aop replay` are in the repo.                                                                                                                   |
| M33b / Q4 + Q11          | Outstanding                                   | `evidence.verify_chain` and `doctor.run` are cataloged but still effectively placeholders; the companion spec remains the implementation source of truth.                                                                      |
| M34-M36 / Q1 Q2 Q7 Q8 Q9 | Outstanding with partial foundations          | Dashboard/status readers already surface `feasibility_score`, `feasibility_breakdown`, `flaky_suspects`, and `review_brief` artifacts if present, but the core services/tools/workflows in the child spec are not implemented. |
| M37 / Q5 Q6              | Outstanding with dashboard foundation present | The web dashboard, action routes, and a pluggable authorization adapter exist, but compliance packs/export, real authn/authz, and dashboard audit federation are not implemented.                                              |
| M38 / Q10                | Outstanding                                   | `knowledge.search` and the retained-history graph are not implemented yet.                                                                                                                                                     |
| Q12                      | Deferred                                      | The original canary design is intentionally deferred; any future replacement should be a narrower merged-head verification step, not the old blocked-after-merge lifecycle.                                                    |

## 5. Cross-Spec Coordination Rules

### 5.1 Shared Constraints (Normative)

All split specs MUST preserve:

- deterministic MCP contract behavior
- explicit user approval for merge promotion
- policy/schema-driven validation
- `.aop/**` runtime artifact ownership
- architecture boundary validation and transport parity tests

### 5.2 Shared Policy Namespace

All new toggles MUST be grouped under:

```yaml
innovation:
  semantic_collisions: false
  plan_feasibility_scoring: false
  replay_debugger: true
  tamper_evident_evidence: false
  compliance_packs: false
  dashboard_auth: false
  prompt_contract_tests: false
  flaky_gate_intelligence: false
  review_briefs: false
  knowledge_graph: false
```

### 5.3 Tool Contract Integration

Any new tool introduced in a child spec MUST include:

- catalog entry
- input/output schemas
- RBAC entry
- tool docs regeneration
- parity tests (`inprocess` vs `mcp`)

---

## 6. Milestone Ordering and Dependencies

### M33a (complete)

From `observability_replay_spec`:

- replay timeline

Dependency rationale:

- provides baseline observability needed to debug and harden later milestones

### M33b (still required)

From `evidence_integrity_doctor_spec`:

- evidence chain verification
- doctor scanner

Dependency rationale:

- strengthens auditability and readiness diagnostics but is no longer a blocker for Q3 itself

### M34-M36

From `planning_review_quality_spec`:

- semantic collisions + feasibility scoring
- prompt contracts
- flaky intelligence
- review briefs

Dependency rationale:

- quality-admission and review optimizations depend on M33 replay artifacts; they may optionally consume evidence-integrity and doctor outputs once M33b lands

### M37

From `enterprise_governance_dashboard_spec`:

- compliance export
- dashboard auth/authz/audit federation

Dependency rationale:

- enterprise controls consume stable evidence/reporting from prior milestones

### M38

From `knowledge_canary_spec`:

- knowledge graph retrieval

Dependency rationale:

- graph quality improves with historical artifacts generated by M33-M37, but implementation must account for the current auto-cleanup path that can remove merged feature artifacts immediately after merge

## 7. Execution Workflow for Future Agents

For each milestone:

1. Read this master index and only the child spec for the milestone in scope.
2. Read the child spec's current-state notes before planning implementation; several specs now contain explicit "implemented vs partial vs outstanding" guidance to prevent duplicate work.
3. Implement file-level targets from that child spec.
4. Add/adjust contract artifacts (catalog/schemas/policy/docs).
5. Add tests per child-spec test plan.
6. Run required gates:
   - `npm run lint`
   - `npm run typecheck`
   - `npm test`
   - `npm run validate:mcp-contracts`
   - `npm run validate:architecture`
7. Update `spec-files/progress.md` with:
   - completed tasks
   - residual next tasks
   - blockers/risk notes

## 8. Success Metrics (Program-Level)

- 30% reduction in failed merges due to late conflict discovery.
- 40% reduction in incident triage time.
- 50% reduction in flaky failure noise within 60 days.
- enterprise security/review onboarding reduced to <2 weeks for pilot rollout.
- 20% faster reviewer approval turnaround.

---

## 9. Definition of Done (Master)

The split initiative is complete only when:

1. Q1-Q12 are delivered via their child specs.
2. all feature flags and schema/tool contracts are integrated and validated.
3. no regressions occur in existing deterministic behavior.
4. `spec-files/progress.md` marks all child-spec milestones complete.
