# Feature Spec: Planning and Review Quality Hardening (AOP)

> **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:** 2.1  
**Date:** 2026-03-15  
**Status:** Draft (Audited Against Current Repo State)  
**Roadmap Mapping:** M34-M36

---

## 0. Standards and Dependencies

### 0.1 Required Standards

All implementation MUST preserve:

- 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 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`
- `agentic/orchestrator/defaults/policy.defaults.yaml`
- `packages/web-dashboard/src/lib/aop-client.ts`
- `packages/web-dashboard/src/lib/types.ts`
- `packages/web-dashboard/src/components/detail-panel.tsx`
- `packages/web-dashboard/src/app/analytics/page.tsx`
- `packages/web-dashboard/src/app/api/features/[id]/triage/route.ts`

### 0.3 Feature Scope

This spec 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

Out of scope:

- ML-based probabilistic heuristics
- autonomous prompt rewriting
- silent gate bypasses without policy and audit metadata

### 0.4 Current Project State

This spec remains largely outstanding as of 2026-03-15, but several adjacent foundations now exist and should not be reimplemented from scratch:

- **Q1 is not implemented.** Intentional collision override support exists, but it is not semantic collision analysis and does not satisfy Q1.
- **Q2 is not implemented.** The dashboard/status readers can already display `feasibility_score` and `feasibility_breakdown` if those fields exist, but no scoring service or `plan.score` tool exists.
- **Q7 is not implemented.** There is no prompt-contract harness, fixture set, or CI gate for prompt invariants.
- **Q8 is not implemented.** The dashboard exposes a thin `/api/flaky` artifact reader and flaky-suspect display, but no flaky-governance service, quarantine mutation tools, or parser-backed rolling statistics pipeline exist.
- **Q9 is partially prepared but not implemented.** The dashboard already reads `.aop/features/<id>/review_brief.json` and can render a brief if present, but no review-brief generation service or `report.feature_review_brief` tool exists.

---

## 1. Architectural Critique of Prior Draft (v1.0)

The prior draft was directionally useful, but not implementation-safe against the current architecture. Key issues:

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`.

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.

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.

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).

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`.

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.

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`.

---

## 2. Revised Architecture Fit

### 2.1 Existing Runtime Touchpoints

- **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.

### 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

Add to defaults + schema:

> **Implementation note:** `innovation:`, `planning:`, and `reporting:` are **new top-level keys** that must be added to both `policy.defaults.yaml` and `policy.schema.json` (the root schema has `additionalProperties: false`). The `testing:` section **already exists** in both files with required fields `framework` and `coverage` — `flaky` must be added as an optional sub-key within `testing.properties` in the schema, not as a new top-level key. Do not remove or modify the existing `testing.framework` or `testing.coverage` properties.

```yaml
innovation:
  semantic_collisions: false
  plan_feasibility_scoring: false
  prompt_contract_tests: false
  flaky_gate_intelligence: false
  review_briefs: false

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.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"
      }
    ]
  }
}
```

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
```

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

## 3.4 Tool Surface Changes

### 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`:

> **Note:** `UNSUPPORTED_PARSER` already exists in `error-codes.ts` and is used by the gate runner for unsupported coverage parser types. The new `flaky_test_result_parse_failed` code is distinct — it covers failures when parsing structured test result files (e.g. malformed JUnit XML or vitest JSON) during flaky ingestion. Do **not** reuse `UNSUPPORTED_PARSER` for this purpose.

- `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 Implementation Plan (Normative)

## PRQ0: Contract Scaffolding and Policy Wiring

### Goals

- land all schema/default/tool scaffolding first to avoid mid-phase drift

### 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)

### Mandatory Checks

- `npm run validate:mcp-contracts`
- `npm run validate:architecture`

Exit criteria:

- kernel loads composed policy with new fields
- no contract-validator drift

---

## PRQ1: Q1 Semantic Collision Engine

### Design

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

### Test Plan

- `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

---

## PRQ2: Q2 Plan Feasibility Scoring

### Design

Add deterministic score computation service and optional admission enforcement.

### Deterministic formula contract

`score = round(100 * sum(weight_i * component_i))`

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.

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`

### 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

- `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`

Exit criteria:

- repeated scoring over identical inputs yields identical score and reasons
- enforcement only active when explicitly configured

---

## 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`

Invariant set:

- `agentic/orchestrator/prompt-contract/invariants/*.json`

Harness:

- `apps/control-plane/scripts/test-prompt-contracts.mjs`

Output artifact:

- `.aop/runtime/prompt-contract/latest.json`

### Invariants (minimum)

- 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.

### CI integration

- 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.

### Implementation Targets

- `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

### 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

---

## PRQ4: Q8 Flaky Gate Intelligence + Quarantine Workflow

### Design

Introduce deterministic flaky scoring over historical test outcomes and governed quarantine controls.

### Data pipeline

1. Gate execution emits structured test results (optional parser path):

- extend `gates.yaml` parser config with `parsers.tests`
- **the `parsers` object already exists in gate profiles and is described as coverage configuration** (`additionalProperties: true`); `parsers.tests` is a new sub-key alongside `parsers.coverage` — do not remove or rename the existing coverage key
- update `agentic/orchestrator/schemas/gates.schema.json` to document both `parsers.coverage` (existing) and `parsers.tests` (new) under the `parsers` property
- 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.

### 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`

### 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"
      }
    }
  }
}
```

### 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

- `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

Exit criteria:

- suspect list deterministic for identical history
- quarantine lifecycle enforced with owner/reason/expiry constraints
- required-gate integrity preserved by default

---

## PRQ5: Q9 Auto-Generated Review Briefs

### Design

Generate deterministic review briefs from canonical runtime artifacts; no free-form model synthesis.

### Trigger points

- 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

### Brief sections (fixed order)

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

### 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`
- `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/components/detail-panel.tsx`
- `packages/web-dashboard/src/app/api/features/[id]/triage/route.ts`

### Dashboard integration contract

- `FeatureDetail` adds optional `review_brief`
- details pane renders structured brief sections when present
- fallback message when brief unavailable

### 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

---

## PRQ6: Hardening, Rollout, and Migration

### Rollout order

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.

### Backfill guidance

- 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.

### Observability requirements

- emit structured log events for:
  - feasibility score evaluation
  - semantic collision detection
  - flaky suspect/quarantine transitions
  - review brief generation success/failure

---

## 5. Core Tradeoffs

1. **Semantic precision vs planner burden**

- richer `semantic_intent` improves detection but increases plan authoring complexity.

2. **Early plan quality gates vs throughput**

- enforcing feasibility reduces churn but can block progress if thresholds are too strict.

3. **Flaky noise reduction vs masking regressions**

- quarantine reduces false alarms but can hide real defects if governance is weak.

4. **Strict prompt contracts vs iteration speed**

- strong invariants prevent regressions but add maintenance overhead when role behavior evolves.

5. **Comprehensive review briefs vs generation cost**

- richer summaries help reviewers but add I/O/compute per `ready_to_merge` transition.

6. **New tool count vs API surface simplicity**

- dedicated tools improve explicitness and RBAC isolation but increase contract maintenance load.

---

## 6. Milestones and Implementation Sequence

### Milestone A (Week 1)

- PRQ0 scaffolding complete
- contract validators green

### Milestone B (Week 2)

- Q1 semantic collisions + tests complete
- Q2 feasibility scoring in `report_only`

### Milestone C (Week 3)

- Q7 prompt contract harness enforced in CI
- Q8 flaky ingestion and reporting complete

### Milestone D (Week 4)

- Q8 quarantine workflow complete
- Q9 review brief generation + dashboard integration complete

### Milestone E (Week 5)

- full stabilization, parity tests, docs, and rollout playbook

---

## 7. Test Strategy (Normative)

### 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.2 Integration

- `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`

### 7.4 UI and API

- dashboard detail endpoint includes review brief when present
- dashboard page renders review brief sections deterministically
- missing brief state handled gracefully

### 7.5 Validation Gates

- `npm run lint`
- `npm run typecheck`
- `npm test`
- `npm run validate:mcp-contracts`
- `npm run validate:architecture`

---

## 8. Acceptance Criteria

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 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
