agentic-orchestrator 0.1.4 → 0.1.6

package/spec-files/outstanding/agentic_orchestrator_planning_review_quality_spec.md

@@ -1,25 +1,50 @@
 # Feature Spec: Planning and Review Quality Hardening (AOP)
 
-> **Purpose of this document**: Define implementation-ready delivery for Q1, Q2, Q7, Q8, and Q9: semantic collision detection, feasibility scoring, prompt contract tests, flaky gate intelligence, and generated review briefs.
+> **Purpose of this document**: Provide implementation-ready delivery for Q1, Q2, Q7, Q8, and Q9 with an explicit architectural critique of the prior draft and a corrected execution plan aligned to the current control-plane architecture.
 
-**Version:** 1.0  
-**Date:** 2026-03-03  
-**Status:** Draft  
+**Version:** 2.0  
+**Date:** 2026-03-04  
+**Status:** Draft (Architecture-Corrected)  
 **Roadmap Mapping:** M34-M36
 
 ---
 
-## 0. Standards and Scope
+## 0. Standards and Dependencies
 
-### 0.1 Standards
+### 0.1 Required Standards
 
 All implementation MUST preserve:
-- deterministic plan admission behavior
-- policy/schema governance
-- transport parity for new tools
-- existing collision + lock safety guarantees
+- deterministic tool behavior and normalized error envelopes
+- MCP/in-process transport parity for all new tools
+- policy/schema-governed behavior changes (no hidden defaults)
+- existing lock/collision safety guarantees
+- architecture boundary validation (`validate:architecture`)
 
-### 0.2 Feature Scope
+### 0.2 Required Upstream Inputs
+
+Implementing agents MUST read:
+- `spec-files/outstanding/agentic_orchestrator_quality_adoption_execution_spec.md`
+- `apps/control-plane/src/application/services/plan-service.ts`
+- `apps/control-plane/src/core/collisions.ts`
+- `apps/control-plane/src/application/services/gate-service.ts`
+- `apps/control-plane/src/core/gates.ts`
+- `apps/control-plane/src/application/services/reporting-service.ts`
+- `apps/control-plane/src/supervisor/planning-wave-executor.ts`
+- `apps/control-plane/src/supervisor/build-wave-executor.ts`
+- `apps/control-plane/src/supervisor/qa-wave-executor.ts`
+- `apps/control-plane/src/core/constants.ts`
+- `apps/control-plane/src/core/error-codes.ts`
+- `agentic/orchestrator/defaults/policy.defaults.yaml`
+- `agentic/orchestrator/schemas/policy.schema.json`
+- `agentic/orchestrator/schemas/plan.schema.json`
+- `agentic/orchestrator/schemas/state.schema.json`
+- `agentic/orchestrator/schemas/gates.schema.json`
+- `agentic/orchestrator/tools/catalog.json`
+- `packages/web-dashboard/src/lib/aop-client.ts`
+- `packages/web-dashboard/src/lib/types.ts`
+- `packages/web-dashboard/src/app/page.tsx`
+
+### 0.3 Feature Scope
 
 This spec implements:
 - **Q1** Semantic Collision Engine
@@ -28,60 +53,84 @@ This spec implements:
 - **Q8** Flaky Gate Intelligence + Quarantine Workflow
 - **Q9** Auto-Generated Review Briefs
 
-### 0.3 Out of Scope
-
-- ML-based probabilistic planning heuristics
+Out of scope:
+- ML-based probabilistic heuristics
 - autonomous prompt rewriting
-- automatic flaky-test suppression without accountability metadata
+- silent gate bypasses without policy and audit metadata
 
 ---
 
-## 1. Objectives
+## 1. Architectural Critique of Prior Draft (v1.0)
 
-### 1.1 Must-Have Outcomes
+The prior draft was directionally useful, but not implementation-safe against the current architecture. Key issues:
 
-- detect semantic collisions before expensive build/QA loops
-- prevent low-quality plans from advancing when policy requires score threshold
-- protect planner/builder/qa behavior from prompt regressions
-- reduce gate noise caused by flaky tests
-- provide deterministic, high-signal review briefs for human approval
+1. **Semantic collision data model was underspecified**
+- Problem: Q1 demanded semantic conflicts (OpenAPI/event/db intent) but provided no canonical plan-level fields to compare deterministically.
+- Impact: impossible to implement reliably in `plan.submit` without brittle repo parsing or heuristic guessing.
+- Correction: add explicit `plan.semantic_intent` contract to `plan.schema.json`.
 
-### 1.2 Non-Goals
+2. **Policy changes were not wired to current schema constraints**
+- Problem: root `policy.schema.json` is strict (`additionalProperties: false`). New sections cannot be added by policy text alone.
+- Impact: runtime load fails if sections are added without schema/default updates.
+- Correction: update defaults + full policy schema + init-policy generation paths.
 
-- no change to explicit user merge control semantics
-- no replacement of current gate profiles
-- no dynamic prompt evaluation service
+3. **Tool-surface proposal was incomplete**
+- Problem: adding tools without corresponding updates to constants, kernel handler registration, catalog, RBAC, and behavior metadata causes contract/runtime drift.
+- Impact: `validate:mcp-contracts` and runtime authorization failures.
+- Correction: include full tool lifecycle wiring as normative work.
 
----
+4. **Flaky workflow lacked a mutating governance path**
+- Problem: draft provided read-only flake report but no deterministic mutation interface for quarantine owner/reason/expiry.
+- Impact: “workflow” cannot be executed via orchestrator contracts.
+- Correction: add explicit quarantine upsert/clear contracts and audit metadata.
 
-## 2. Architecture Decisions
+5. **Flaky model lacked deterministic test-level input source**
+- Problem: current gate evidence includes step-level execution, not standardized per-test outcomes.
+- Impact: per-test flaky scoring cannot be computed reliably.
+- Correction: extend gate parser model to optionally ingest structured test results (e.g., junit_xml / vitest_json).
 
-### 2.1 Collision Checks as Layered Validation
+6. **Review brief integration path mismatched actual dashboard architecture**
+- Problem: draft targeted non-existent `packages/web-dashboard/src/components/ReviewPanel.tsx`.
+- Impact: implementation ambiguity and likely dead-end edits.
+- Correction: wire through existing `aop-client.ts`, `types.ts`, and `app/page.tsx`.
 
-Plan admission remains layered:
-1. schema validation
-2. policy validation
-3. path/contract collision checks
-4. **semantic collision checks (new)**
-5. feasibility scoring threshold check (optional)
+7. **Plan feasibility scoring lacked deterministic formula contract**
+- Problem: scoring factors were named but not formally defined.
+- Impact: non-repeatable behavior and test fragility.
+- Correction: define exact component formulas and rounding rules.
 
-### 2.2 Prompt Contracts as CI Artifact
+8. **No rollout/failure-mode safety for quality gates**
+- Problem: missing `report_only` vs `enforce` semantics for early rollout.
+- Impact: high risk of accidental throughput regression.
+- Correction: add explicit enforcement modes with default `report_only`.
 
-Prompt contracts are treated as repository source contracts with test fixtures and invariants. They are verified by deterministic scripts in CI, not by runtime agent heuristics.
+---
 
-### 2.3 Flaky Intelligence is Advisory + Governed
+## 2. Revised Architecture Fit
 
-Flaky classification influences reporting and quarantine workflow but MUST NOT silently bypass required merge gates without explicit policy.
+### 2.1 Existing Runtime Touchpoints
 
-### 2.4 Review Briefs are Deterministic Summaries
+- **Plan admission path**: `PlanService.planSubmit()` is the authoritative hook for Q1/Q2 enforcement.
+- **Collision reporting path**: `ReportingService.collisionsScan()` is the authoritative hook for scan output parity.
+- **Gate execution path**: `GateService.gatesRun()` + `core/gates.ts` is the authoritative hook for flaky intelligence ingestion.
+- **Supervisor quality loop**: planning/build/qa executors remain orchestrators, not policy evaluators.
+- **Review/report path**: `ReportingService` is the authoritative place for review brief APIs.
+- **Dashboard rendering path**: `aop-client.ts` + `page.tsx` is the current UI integration seam.
 
-Review briefs MUST be generated from canonical artifacts only (plan, state, diff, gate evidence, collisions, locks), not free-form model synthesis.
+### 2.2 Boundary Rules (Normative)
+
+- `core/*` MUST remain framework-agnostic pure logic where practical (no service imports).
+- orchestration/policy decisions belong in `application/services/*`.
+- new MCP tools MUST be implemented via kernel handler registration and catalog/schema integration.
+- no feature may bypass policy schema validation.
 
 ---
 
 ## 3. Contracts and Schema Deltas
 
-### 3.1 Policy Extensions
+## 3.1 Policy Extensions
+
+Add to defaults + schema:
 
 ```yaml
 innovation:
@@ -94,373 +143,588 @@ innovation:
 planning:
   feasibility:
     enabled: false
+    enforcement_mode: report_only   # report_only | enforce
     minimum_score: 70
+    minimum_component_score: 0.45
     weights:
       scope_realism: 0.25
       test_sufficiency: 0.25
-      dependency_completeness: 0.2
+      dependency_completeness: 0.20
       contract_risk: 0.15
       lock_contention_risk: 0.15
 
 testing:
   flaky:
     enabled: false
+    window_size: 20
+    min_observations: 6
+    suspect_threshold: 0.45
+    alternation_weight: 0.40
+    failure_rate_weight: 0.60
+    allow_quarantine_for_required_modes: false
     quarantine:
       max_days: 14
       require_owner: true
       require_reason: true
+
+reporting:
+  review_brief:
+    enabled: false
+    generate_on_ready_to_merge: true
+    include_diff_stat: true
+    include_flaky_summary: true
+```
+
+Normative behavior:
+- all flags default `false` (opt-in rollout)
+- `weights` MUST sum to 1.0 exactly after normalization (schema + runtime validation)
+- `enforcement_mode=report_only` logs score metadata but never blocks plan acceptance
+
+## 3.2 Plan Schema Extension (`plan.schema.json`)
+
+Add optional deterministic semantic declarations:
+
+```json
+{
+  "semantic_intent": {
+    "openapi_operations": [
+      {
+        "operation_id": "users_update",
+        "path": "/users/{id}",
+        "method": "PATCH",
+        "change": "modify_response"
+      }
+    ],
+    "event_changes": [
+      {
+        "event_name": "user.updated",
+        "version": "v2",
+        "change": "schema_breaking"
+      }
+    ],
+    "db_intents": [
+      {
+        "entity": "users",
+        "change": "drop_column",
+        "field": "legacy_status"
+      }
+    ]
+  }
+}
 ```
 
-### 3.2 New/Extended Artifacts
+Rules:
+- absence of `semantic_intent` is valid; engine treats as empty intent set
+- deterministic compare uses normalized lowercase for `method` and stable key ordering
+
+## 3.3 State and Artifact Deltas
+
+Add/extend runtime artifacts:
 
 ```text
 .aop/
   analytics/flaky-tests.json
+  runtime/prompt-contract/latest.json
   features/<feature_id>/review_brief.json
-
-agentic/orchestrator/
-  prompt-contract/
-    fixtures/
-    invariants/
-  schemas/review_brief.schema.json
 ```
 
-### 3.3 Tool Surface Additions
+State frontmatter extension (`state.schema.json`):
+- `collisions.semantic` array
+- `planning_quality.feasibility_score` number (0-100)
+- `planning_quality.feasibility_breakdown` object
+- `reporting.review_brief_path` string
 
-- `plan.score` (read-only)
-- `gate.flaky_report_get` (read-only)
-- `report.feature_review_brief` (read-only)
+## 3.4 Tool Surface Changes
 
-`collisions.scan` output schema must be extended for `semantic_conflicts[]`.
+### New Tools
+
+1. `plan.score` (read-only)
+- returns feasibility score + deterministic breakdown + reasons
+
+2. `gate.flaky_report_get` (read-only)
+- returns flaky suspects, quarantine entries, expiry warnings
+
+3. `gate.flaky_quarantine_upsert` (mutating)
+- upsert quarantine entry (`test_key`, `owner`, `reason`, `expires_at`)
+
+4. `gate.flaky_quarantine_clear` (mutating)
+- clear quarantine entry by `test_key`
+
+5. `report.feature_review_brief` (read-only)
+- returns parsed review brief for feature
+
+### Extended Existing Tool Contracts
+
+- `collisions.scan` output adds `semantic_conflicts[]`
+- `report.feature_summary` adds optional `review_brief` and `feasibility`
+
+### Required Wiring for Every New Tool
+
+- `apps/control-plane/src/core/constants.ts` (`TOOLS` constants)
+- `apps/control-plane/src/core/kernel.ts` (handler registration + method wrappers)
+- `apps/control-plane/src/application/tools/tool-metadata.ts` (mutating metadata)
+- `agentic/orchestrator/tools/catalog.json`
+- `agentic/orchestrator/tools/schemas/input/*.json`
+- `agentic/orchestrator/tools/schemas/output/*.json`
+- `agentic/orchestrator/defaults/policy.defaults.yaml` RBAC lists
+- generated `agentic/orchestrator/tools.md`
+
+## 3.5 Error Code Additions
+
+Add to `apps/control-plane/src/core/error-codes.ts`:
+- `semantic_collision_detected`
+- `plan_feasibility_below_threshold`
+- `plan_feasibility_config_invalid`
+- `prompt_contract_invariant_failed`
+- `flaky_quarantine_policy_violation`
+- `flaky_test_result_parse_failed`
+- `review_brief_not_found`
 
 ---
 
-## 4. Detailed Feature Specs
+## 4. Detailed Implementation Plan (Normative)
 
-## 4.1 Q1: Semantic Collision Engine
+## PRQ0: Contract Scaffolding and Policy Wiring
 
-### 4.1.1 Problem
-Two features can avoid path collisions yet conflict semantically (same API operation evolution, incompatible event payloads, conflicting migration intent).
+### Goals
+- land all schema/default/tool scaffolding first to avoid mid-phase drift
 
-### 4.1.2 Design
-Add semantic analyzers executed during `plan.submit` and `collisions.scan` when enabled.
+### File Targets
+- `agentic/orchestrator/defaults/policy.defaults.yaml`
+- `agentic/orchestrator/schemas/policy.schema.json`
+- `agentic/orchestrator/schemas/plan.schema.json`
+- `agentic/orchestrator/schemas/state.schema.json`
+- `agentic/orchestrator/schemas/gates.schema.json`
+- `apps/control-plane/src/core/constants.ts`
+- `apps/control-plane/src/core/error-codes.ts`
+- `agentic/orchestrator/tools/catalog.json`
+- `agentic/orchestrator/tools/schemas/input/*` (new tool schemas)
+- `agentic/orchestrator/tools/schemas/output/*` (new tool schemas)
+- `agentic/orchestrator/tools.md`
+- `apps/control-plane/src/cli/init-command-handler.ts` (full policy template alignment)
 
-### 4.1.3 Analyzer Modules
+### Mandatory Checks
+- `npm run validate:mcp-contracts`
+- `npm run validate:architecture`
 
-- `OpenApiSemanticAnalyzer`
-- `EventSchemaSemanticAnalyzer`
-- `DbIntentSemanticAnalyzer`
+Exit criteria:
+- kernel loads composed policy with new fields
+- no contract-validator drift
 
-### 4.1.4 Output Contract
+---
 
-```json
-{
-  "semantic_conflicts": [
-    {
-      "type": "openapi_operation_conflict",
-      "feature_a": "feature_1",
-      "feature_b": "feature_2",
-      "fingerprint": "sha256:...",
-      "severity": "high",
-      "details": {
-        "path": "/users/{id}",
-        "method": "PATCH"
-      }
-    }
-  ]
-}
-```
+## PRQ1: Q1 Semantic Collision Engine
 
-### 4.1.5 File Targets
+### Design
 
-- `apps/control-plane/src/application/services/semantic-collision-service.ts` (new)
+Implement semantic comparisons as an additive layer over existing syntactic collisions.
+
+### Core algorithm
+
+1. Normalize candidate + accepted plan semantic intents.
+2. Compare candidate against each accepted plan:
+- OpenAPI conflict if same `operation_id` OR same `path+method` and incompatible `change` class.
+- Event conflict if same `event_name` and incompatible `version/change` pair.
+- DB intent conflict if same `entity` and conflicting operations (`drop_column` vs `rename_column`, etc.).
+3. Emit stable sorted conflicts and deterministic fingerprint.
+4. Merge with existing `files/areas/contracts` collision result.
+
+### Implementation Targets
+
+- `apps/control-plane/src/core/semantic-collisions.ts` (new, pure)
 - `apps/control-plane/src/application/services/plan-service.ts`
 - `apps/control-plane/src/application/services/reporting-service.ts`
 - `agentic/orchestrator/tools/schemas/output/collisions.scan.output.schema.json`
+- `apps/control-plane/src/core/kernel.ts` (if helper wrapper needed)
+
+### Behavioral Rules
+
+- semantic collision enforcement follows existing `collision_policy` (`reject`/`block`)
+- blocked queue entry MUST store both syntactic + semantic fingerprints
+- `state.collisions.semantic` MUST be populated on block/reject responses
 
-### 4.1.6 Acceptance Criteria
+### Test Plan
 
-- semantic conflicts produce stable fingerprints and deterministic ordering
-- policy `collision_policy` handling applies to semantic conflicts identically to existing collisions
+- `apps/control-plane/test/semantic-collisions.spec.ts` (new)
+- extend `apps/control-plane/test/plan-service.spec.ts`
+- extend `apps/control-plane/test/collisions.spec.ts`
+- extend transport parity assertions in `apps/control-plane/test/mcp.spec.ts`
+
+Exit criteria:
+- same inputs produce byte-identical `semantic_conflicts` ordering
+- plan blocking/rejection behavior unchanged except added semantic details
 
 ---
 
-## 4.2 Q2: Plan Feasibility Scoring
+## PRQ2: Q2 Plan Feasibility Scoring
 
-### 4.2.1 Problem
-Schema-valid plans can still be operationally poor and drive retries.
+### Design
 
-### 4.2.2 Design
-Add deterministic scoring service and optional threshold gate in plan admission.
+Add deterministic score computation service and optional admission enforcement.
 
-### 4.2.3 Scoring Components
+### Deterministic formula contract
 
-- scope realism: file breadth vs stated summary/criteria
-- test sufficiency: acceptance criteria mapped to gate/test obligations
-- dependency completeness: missing/unsatisfied dependencies
-- contract risk: openapi/events/db impact complexity
-- lock contention risk: likelihood of blocking based on held/pending locks
+`score = round(100 * sum(weight_i * component_i))`
 
-### 4.2.4 Tool Contract (`plan.score`)
+Components (0.0-1.0):
+- `scope_realism`: bounded function of planned file count, allowed-area breadth, and summary specificity.
+- `test_sufficiency`: acceptance criteria count and presence of verification mapping (`gate_profile`, `gate_targets`, `verification_overrides`).
+- `dependency_completeness`: dependency declarations resolvable from index state.
+- `contract_risk`: penalty for high-risk contract surface changes with no matching acceptance criteria/risk notes.
+- `lock_contention_risk`: penalty when required lock resources are currently held and blocked queue depth is high.
 
-```json
-{
-  "feature_id": "my_feature",
-  "score": 78,
-  "breakdown": {
-    "scope_realism": 0.8,
-    "test_sufficiency": 0.7,
-    "dependency_completeness": 0.9,
-    "contract_risk": 0.6,
-    "lock_contention_risk": 0.7
-  },
-  "reasons": [
-    "Acceptance criteria #3 has no mapped verification target"
-  ]
-}
-```
+Normalization rules:
+- all component values clamp to `[0,1]`
+- weights normalize to sum 1.0 at runtime
+- reasons array order is lexical and deterministic
+
+### Enforcement behavior
+
+- if `enabled=false`: no score evaluation in plan admission path
+- if `enabled=true && enforcement_mode=report_only`: score computed and stored, never blocks
+- if `enabled=true && enforcement_mode=enforce`: block when `score < minimum_score` OR any component `< minimum_component_score`
 
-### 4.2.5 File Targets
+### Implementation Targets
 
 - `apps/control-plane/src/application/services/plan-feasibility-service.ts` (new)
 - `apps/control-plane/src/application/services/plan-service.ts`
+- `apps/control-plane/src/application/services/reporting-service.ts`
+- `apps/control-plane/src/core/kernel.ts`
+- `agentic/orchestrator/tools/schemas/input/plan.score.input.schema.json` (new)
 - `agentic/orchestrator/tools/schemas/output/plan.score.output.schema.json` (new)
+- `agentic/orchestrator/tools/schemas/output/plan.submit.output.schema.json` (optional metadata extension)
+
+### Test Plan
 
-### 4.2.6 Acceptance Criteria
+- `apps/control-plane/test/plan-feasibility-service.spec.ts` (new)
+- extend `apps/control-plane/test/plan-service.spec.ts`
+- extend `apps/control-plane/test/mcp.spec.ts` for `plan.score`
 
-- score for same inputs is stable across repeated calls
-- below-threshold plans blocked only when feasibility gate is enabled
+Exit criteria:
+- repeated scoring over identical inputs yields identical score and reasons
+- enforcement only active when explicitly configured
 
 ---
 
-## 4.3 Q7: Prompt Contract Test Harness
+## PRQ3: Q7 Prompt Contract Test Harness
+
+### Design
+
+Treat prompt behavior as deterministic source contract tests in CI.
+
+### Contract model
+
+Fixture set:
+- `agentic/orchestrator/prompt-contract/fixtures/*.json`
 
-### 4.3.1 Problem
-Prompt edits currently risk behavior drift without dedicated regression coverage.
+Invariant set:
+- `agentic/orchestrator/prompt-contract/invariants/*.json`
 
-### 4.3.2 Design
-Fixture + invariant harness validates role outputs against deterministic expectations.
+Harness:
+- `apps/control-plane/scripts/test-prompt-contracts.mjs`
 
-### 4.3.3 Invariant Set (Initial)
+Output artifact:
+- `.aop/runtime/prompt-contract/latest.json`
 
-- planner output must include actionable plan artifacts
-- builder output must not propose forbidden tool usage
-- QA output must contain explicit evidence/test update intent
+### Invariants (minimum)
 
-### 4.3.4 Tooling
+- Planner fixture outputs include either `PLAN_SUBMISSION` or deterministic `REQUEST` rationale.
+- Builder fixture outputs never request forbidden tools.
+- QA fixture outputs include explicit verification/remediation intent.
+- Output objects must satisfy role-specific schema fragments.
 
-- script: `apps/control-plane/scripts/test-prompt-contracts.mjs`
-- repo assets:
-  - `agentic/orchestrator/prompt-contract/fixtures/*`
-  - `agentic/orchestrator/prompt-contract/invariants/*`
-- package script:
-  - `npm run test:prompt-contracts`
+### CI integration
 
-### 4.3.5 CI Contract
+- add script: `test:prompt-contracts`
+- add optional validator wrapper: `validate:prompt-contracts`
+- enforce execution whenever files under:
+  - `agentic/orchestrator/prompts/`
+  - `agentic/orchestrator/prompt-contract/`
+  - `apps/control-plane/src/supervisor/worker-decision-loop.ts`
+  change.
 
-If prompt files under `agentic/orchestrator/prompts/` change, prompt-contract suite MUST run and block merge on failure.
+### Implementation Targets
 
-### 4.3.6 Acceptance Criteria
+- `apps/control-plane/scripts/test-prompt-contracts.mjs` (new)
+- `agentic/orchestrator/prompt-contract/fixtures/*` (new)
+- `agentic/orchestrator/prompt-contract/invariants/*` (new)
+- `package.json` scripts
+- CI workflow file(s) to wire execution
 
-- invariant failures produce explicit diff-like diagnostics
-- prompt harness artifacts persist under `.aop/runtime/prompt-contract/`
+### Test Plan
+
+- `apps/control-plane/test/prompt-contract-harness.spec.ts` (new)
+- failure snapshot tests for invariant diagnostics
+
+Exit criteria:
+- invariant failures provide actionable role + fixture + invariant id diagnostics
+- harness runtime is deterministic and independent of live provider calls
 
 ---
 
-## 4.4 Q8: Flaky Gate Intelligence + Quarantine Workflow
+## PRQ4: Q8 Flaky Gate Intelligence + Quarantine Workflow
+
+### Design
 
-### 4.4.1 Problem
-Flaky failures create noisy retries and reduce confidence in gate results.
+Introduce deterministic flaky scoring over historical test outcomes and governed quarantine controls.
 
-### 4.4.2 Design
-Track per-test stability history and expose deterministic suspect scoring and quarantine governance.
+### Data pipeline
 
-### 4.4.3 Flake Model (Deterministic)
+1. Gate execution emits structured test results (optional parser path):
+- extend `gates.yaml` parser config with `parsers.tests`
+- supported initial parsers: `none`, `junit_xml`, `vitest_json`
+2. `GateService` ingests latest run outcomes after each gate run.
+3. `FlakyGateService` updates `.aop/analytics/flaky-tests.json` with rolling window stats.
+4. Suspect score computed deterministically:
+- `suspect_score = failure_rate_weight * failure_rate + alternation_weight * alternation_rate`
+5. Quarantine controls applied only with explicit metadata and expiry.
 
-Per test key `<framework>:<suite>:<test_name>`:
-- rolling window results
-- failure-rate and alternation index
-- quarantine metadata (`owner`, `reason`, `expires_at`)
+### Quarantine rules
 
-### 4.4.4 Quarantine Rules
+- upsert requires owner/reason/expiry when required by policy
+- expiry > now and <= `max_days`
+- expired entries move to `expired_quarantines[]` and are treated as non-quarantined
+- required gate modes remain blocking unless `allow_quarantine_for_required_modes=true`
 
-- quarantine entry requires owner + reason
-- quarantine expires automatically
-- expired quarantine generates reminder finding/event
-- quarantine cannot silently satisfy required merge gates unless policy explicitly permits
+### Runtime artifact contract
+
+`.aop/analytics/flaky-tests.json`:
+
+```json
+{
+  "version": 1,
+  "updated_at": "2026-03-04T00:00:00Z",
+  "tests": {
+    "vitest:auth.spec.ts:refresh token retries": {
+      "history": ["pass", "fail", "pass", "fail"],
+      "failure_rate": 0.5,
+      "alternation_rate": 1.0,
+      "suspect_score": 0.7,
+      "status": "suspect",
+      "quarantine": {
+        "owner": "alice",
+        "reason": "upstream nondeterministic timeout",
+        "expires_at": "2026-03-10T00:00:00Z"
+      }
+    }
+  }
+}
+```
 
-### 4.4.5 File Targets
+### Implementation Targets
 
 - `apps/control-plane/src/application/services/flaky-gate-service.ts` (new)
 - `apps/control-plane/src/application/services/gate-service.ts`
+- `apps/control-plane/src/core/gates.ts` (test parser extraction)
+- `agentic/orchestrator/schemas/gates.schema.json`
+- `agentic/orchestrator/tools/schemas/input/gate.flaky_report_get.input.schema.json` (new)
 - `agentic/orchestrator/tools/schemas/output/gate.flaky_report_get.output.schema.json` (new)
+- `agentic/orchestrator/tools/schemas/input/gate.flaky_quarantine_upsert.input.schema.json` (new)
+- `agentic/orchestrator/tools/schemas/output/gate.flaky_quarantine_upsert.output.schema.json` (new)
+- `agentic/orchestrator/tools/schemas/input/gate.flaky_quarantine_clear.input.schema.json` (new)
+- `agentic/orchestrator/tools/schemas/output/gate.flaky_quarantine_clear.output.schema.json` (new)
+
+### Test Plan
 
-### 4.4.6 Acceptance Criteria
+- `apps/control-plane/test/flaky-gate-service.spec.ts` (new)
+- extend `apps/control-plane/test/gates.spec.ts` for test parser extraction
+- extend `apps/control-plane/test/supervisor.spec.ts` for retry/quarantine interactions
+- extend `apps/control-plane/test/mcp.spec.ts` for new tools and parity
 
-- flaky suspect list deterministic for same history input
-- quarantine lifecycle enforced by policy constraints
+Exit criteria:
+- suspect list deterministic for identical history
+- quarantine lifecycle enforced with owner/reason/expiry constraints
+- required-gate integrity preserved by default
 
 ---
 
-## 4.5 Q9: Auto-Generated Review Briefs
+## PRQ5: Q9 Auto-Generated Review Briefs
 
-### 4.5.1 Problem
-Human reviewers must manually synthesize plan/diff/evidence context.
+### Design
 
-### 4.5.2 Design
-Generate concise structured review brief artifacts for each reviewable feature.
+Generate deterministic review briefs from canonical runtime artifacts; no free-form model synthesis.
 
-### 4.5.3 Brief Sections
+### Trigger points
 
-- intent and scope summary
-- high-risk paths/contracts
-- gate outcome matrix
-- unresolved risks/questions
-- evidence references
+- automatic generation when feature transitions to `ready_to_merge` after successful `full` gate
+- on-demand regeneration via `report.feature_review_brief` if file missing/stale
 
-### 4.5.4 Artifact Contract
+### Brief sections (fixed order)
 
-```json
-{
-  "feature_id": "my_feature",
-  "intent_summary": "Add idempotent billing retry guard",
-  "high_risk_paths": ["libs/billing/retry.ts"],
-  "contract_changes": {
-    "openapi": false,
-    "events": true,
-    "db": false
-  },
-  "gate_summary": {
-    "fast": "pass",
-    "full": "pass",
-    "merge": "na"
-  },
-  "open_questions": [
-    "Should retry cap be environment-specific?"
-  ],
-  "evidence_refs": [
-    ".aop/features/my_feature/evidence/gates/full-2026-03-03.json"
-  ]
-}
-```
+1. intent summary
+2. scope and touched files
+3. contract and semantic risk summary
+4. feasibility score and rationale
+5. gate matrix + flaky summary
+6. unresolved questions / review prompts
+7. evidence references
 
-### 4.5.5 File Targets
+### Artifact path
+
+- `.aop/features/<feature_id>/review_brief.json`
+
+### Implementation Targets
 
 - `apps/control-plane/src/application/services/review-brief-service.ts` (new)
 - `apps/control-plane/src/application/services/reporting-service.ts`
-- `packages/web-dashboard/src/components/ReviewPanel.tsx`
+- `apps/control-plane/src/application/services/gate-service.ts` (trigger hook)
+- `apps/control-plane/src/core/path-layout.ts` (optional helper: `reviewBriefPath(featureId)`)
 - `agentic/orchestrator/schemas/review_brief.schema.json` (new)
+- `agentic/orchestrator/tools/schemas/input/report.feature_review_brief.input.schema.json` (new)
+- `agentic/orchestrator/tools/schemas/output/report.feature_review_brief.output.schema.json` (new)
+- `packages/web-dashboard/src/lib/types.ts`
+- `packages/web-dashboard/src/lib/aop-client.ts`
+- `packages/web-dashboard/src/app/page.tsx`
+
+### Dashboard integration contract
 
-### 4.5.6 Acceptance Criteria
+- `FeatureDetail` adds optional `review_brief`
+- details pane renders structured brief sections when present
+- fallback message when brief unavailable
 
-- review brief generated for `ready_to_merge` features
-- brief content deterministic and sorted consistently
+### Test Plan
+
+- `apps/control-plane/test/review-brief-service.spec.ts` (new)
+- extend `apps/control-plane/test/services.spec.ts` / `kernel.spec.ts` for trigger behavior
+- extend `apps/control-plane/test/dashboard-api.integration.spec.ts`
+- add UI rendering test under web-dashboard workspace for brief display
+
+Exit criteria:
+- brief generation is deterministic and schema-valid
+- dashboard shows brief without regressions to existing detail panel behavior
 
 ---
 
-## 5. Milestones
+## PRQ6: Hardening, Rollout, and Migration
+
+### Rollout order
 
-### PRQ1: Semantic + Feasibility Admission
+1. Ship PRQ0 contracts and flags off by default.
+2. Enable Q1+Q2 in `report_only` mode in internal environments.
+3. Enable Q7 CI harness as warning for one sprint, then enforce.
+4. Enable Q8 flaky intelligence with quarantine enforcement still strict.
+5. Enable Q9 brief generation and dashboard rendering.
+6. Flip enforcement toggles selectively per repo.
 
-Tasks:
-1. Implement semantic analyzers + schema updates.
-2. Implement feasibility scoring + threshold enforcement.
+### Backfill guidance
 
-Exit gate:
-- conflicting and low-feasibility plans blocked deterministically when enabled.
+- optional one-time job can ingest recent gate evidence files into `flaky-tests.json` history.
+- missing historical test-level data is acceptable; model starts with forward-only data.
 
-### PRQ2: Prompt Contract Reliability
+### Observability requirements
 
-Tasks:
-1. Add fixtures/invariants and harness script.
-2. Wire CI enforcement for prompt changes.
+- emit structured log events for:
+  - feasibility score evaluation
+  - semantic collision detection
+  - flaky suspect/quarantine transitions
+  - review brief generation success/failure
 
-Exit gate:
-- prompt regressions are caught in CI with clear diagnostics.
+---
+
+## 5. Core Tradeoffs
 
-### PRQ3: Flaky Gate Intelligence
+1. **Semantic precision vs planner burden**
+- richer `semantic_intent` improves detection but increases plan authoring complexity.
 
-Tasks:
-1. Add flake analytics persistence and report tool.
-2. Add quarantine governance and expiry checks.
+2. **Early plan quality gates vs throughput**
+- enforcing feasibility reduces churn but can block progress if thresholds are too strict.
 
-Exit gate:
-- flaky signal exposed without weakening mandatory gates by default.
+3. **Flaky noise reduction vs masking regressions**
+- quarantine reduces false alarms but can hide real defects if governance is weak.
 
-### PRQ4: Review Brief Automation
+4. **Strict prompt contracts vs iteration speed**
+- strong invariants prevent regressions but add maintenance overhead when role behavior evolves.
 
-Tasks:
-1. Implement review-brief service and artifact generation.
-2. Add MCP report tool and dashboard integration.
+5. **Comprehensive review briefs vs generation cost**
+- richer summaries help reviewers but add I/O/compute per `ready_to_merge` transition.
 
-Exit gate:
-- reviewers receive deterministic brief before merge approval.
+6. **New tool count vs API surface simplicity**
+- dedicated tools improve explicitness and RBAC isolation but increase contract maintenance load.
 
 ---
 
-## 6. Test Strategy (Normative)
+## 6. Milestones and Implementation Sequence
 
-### 6.1 Unit Tests
+### Milestone A (Week 1)
+- PRQ0 scaffolding complete
+- contract validators green
 
-- each semantic analyzer rule
-- score determinism and weight normalization
-- prompt invariant validators
-- flaky score and quarantine expiry logic
-- brief assembly ordering and content extraction
+### Milestone B (Week 2)
+- Q1 semantic collisions + tests complete
+- Q2 feasibility scoring in `report_only`
 
-### 6.2 Integration Tests
+### Milestone C (Week 3)
+- Q7 prompt contract harness enforced in CI
+- Q8 flaky ingestion and reporting complete
 
-- `plan.submit` blocked by semantic conflict
-- `plan.submit` blocked by low feasibility when enabled
-- prompt-contract harness pass/fail suites
-- flaky report generation from realistic gate histories
-- review brief generation from live feature artifacts
+### Milestone D (Week 4)
+- Q8 quarantine workflow complete
+- Q9 review brief generation + dashboard integration complete
 
-### 6.3 Transport Parity Tests
+### Milestone E (Week 5)
+- full stabilization, parity tests, docs, and rollout playbook
 
-- `plan.score`
-- `gate.flaky_report_get`
-- `report.feature_review_brief`
+---
 
-### 6.4 UI Tests
+## 7. Test Strategy (Normative)
 
-- review panel displays brief sections and evidence links
-- no brief available state handled clearly
+### 7.1 Unit
 
----
+- semantic comparator edge cases and fingerprint determinism
+- feasibility component formulas and normalization
+- prompt invariant evaluator diagnostics
+- flaky suspect score and quarantine expiry behavior
+- review brief assembly sorting and field completeness
 
-## 7. Acceptance Criteria
+### 7.2 Integration
 
-1. Q1/Q2 quality gates work deterministically and are policy-controlled.
-2. Prompt contract harness is operational and CI-gated.
-3. Flaky intelligence improves signal while preserving gate integrity.
-4. Review briefs are generated and consumable in CLI/dashboard flows.
-5. All validation gates pass (`lint`, `typecheck`, `test`, contract/architecture validators).
+- `plan.submit` rejection/block behavior for semantic collisions
+- feasibility enforcement/report-only mode behavior
+- gate-run ingestion of parsed test outcomes
+- quarantine update/clear flow through MCP tools
+- ready-to-merge trigger writes `review_brief.json`
 
----
+### 7.3 Transport Parity
+
+- `plan.score`
+- `gate.flaky_report_get`
+- `gate.flaky_quarantine_upsert`
+- `gate.flaky_quarantine_clear`
+- `report.feature_review_brief`
 
-## 8. Risks and Mitigations
+### 7.4 UI and API
 
-- Risk: semantic analyzers produce false positives.
-  - Mitigation: confidence/severity labels + precise conflict details and opt-in rollout.
+- dashboard detail endpoint includes review brief when present
+- dashboard page renders review brief sections deterministically
+- missing brief state handled gracefully
 
-- Risk: scoring model over-rejects valid plans.
-  - Mitigation: threshold configurable and disabled by default.
+### 7.5 Validation Gates
+
+- `npm run lint`
+- `npm run typecheck`
+- `npm test`
+- `npm run validate:mcp-contracts`
+- `npm run validate:architecture`
+
+---
 
-- Risk: prompt fixtures become stale with runtime evolution.
-  - Mitigation: fixture versioning and required update notes on role contract changes.
+## 8. Acceptance Criteria
 
-- Risk: quarantine becomes an abuse path.
-  - Mitigation: owner/reason/expiry mandatory and surfaced in status/reporting.
+1. Q1/Q2 admission controls are deterministic, policy-controlled, and rollout-safe (`report_only` supported).
+2. Q7 prompt contract harness blocks prompt regressions with actionable diagnostics.
+3. Q8 flaky intelligence produces deterministic suspect scoring and governed quarantine workflows.
+4. Q9 review briefs are generated from canonical artifacts and consumable via MCP + dashboard.
+5. New tool contracts pass schema validation, RBAC checks, and MCP/in-process parity tests.
+6. No regressions in existing lock, collision, and merge safety behavior.
 
 ---
 
 ## 9. Definition of Done
 
-A completed PRQ milestone MUST include:
-- changed file inventory
-- schema/catalog updates
-- new tests and coverage notes
-- verification command summaries
-- `spec-files/progress.md` task closure and next steps
+A completed milestone MUST include:
+- implemented file inventory mapped to the phase above
+- schema/catalog/RBAC/tool-doc updates
+- unit + integration + parity tests
+- validator and test command summaries
+- `spec-files/progress.md` update with completed tasks, residual tasks, and risks