# Feature Spec: Spec Coverage and Reconciliation Enforcement

> **Purpose of this document**: Define an implementation-ready, platform-agnostic design that closes the gap between `spec.md`, `plan.json`, and post-QA reconciliation by introducing a canonical obligation manifest, planner traceability, and runtime-owned coverage audits.

**Version:** 1.1  
**Date:** 2026-03-16  
**Status:** Draft  
**Roadmap Mapping:** M58

---

## 0. Standards and Dependencies

### 0.1 Required Standards

All implementation MUST preserve:

- deterministic orchestration behavior and normalized error envelopes
- optimistic concurrency semantics for `plan.json`
- lock-safe artifact mutation for `state.md`, `plan.json`, and index artifacts
- MCP/in-process parity for planning behavior
- backward compatibility for existing features that already have persisted plans
- zero hidden prompt-only requirements for execution-critical correctness
- platform-agnostic validation semantics across implementation targets

### 0.2 Required Upstream Inputs

Implementing agents MUST read:

- `apps/control-plane/src/application/services/plan-service.ts`
- `apps/control-plane/src/application/services/feature-lifecycle-service.ts`
- `apps/control-plane/src/core/error-codes.ts`
- `apps/control-plane/src/supervisor/planning-wave-executor.ts`
- `apps/control-plane/src/supervisor/worker-decision-loop.ts`
- `apps/control-plane/src/cli/spec-preparation.ts`
- `apps/control-plane/src/cli/spec-utils.ts`
- `agentic/orchestrator/schemas/plan.schema.json`
- `agentic/orchestrator/prompts/planner.system.md`
- `config/agentic/orchestrator/prompts/planner.system.md`
- `docs/core/DOMAIN-LOGIC.md`
- `docs/core/ARCHITECTURE.md`
- `spec-files/outstanding/agentic_orchestrator_planning_review_quality_spec.md`
- representative specs from multiple implementation styles:
  - `.aop/features/agentic_orchestrator_feature_focus_view_track_b_spec/spec.md`
  - at least one backend/service-oriented spec
  - at least one CLI or infrastructure-oriented spec

### 0.3 Scope

This spec implements:

- a canonical, deterministic obligation inventory for each spec
- explicit planner traceability from obligations to planned files/tests/verification
- hard validation at `plan.submit` and `plan.update`
- post-QA reconciliation that detects missing obligation coverage, not only gate failures
- prompt contract changes that reinforce, but do not solely guarantee, correct planner behavior
- cross-platform fixture coverage proving the model works for TypeScript, Python, Java, and similarly-structured targets
- rollout controls so this can ship safely in `report_only` mode before becoming blocking

Out of scope:

- generic semantic parsing of arbitrary prose
- AST- or symbol-level platform analyzers as a prerequisite for correctness
- ML or embedding-based similarity scoring
- builder/QA behavioral redesign outside the minimum hooks needed for coverage enforcement
- patch gating changes unrelated to plan/spec traceability

### 0.4 Problem Statement

The current system requires the planner prompt to preserve feature intent and reconcile implementation against the plan and spec. That instruction is necessary but insufficient.

Today:

- `plan.schema.json` validates structural correctness but does not require traceability from `spec.md` obligations to plan artifacts.
- `plan.submit` and `plan.update` accept a plan if it is schema-valid and collision-safe, even when concrete deliverables are absent from the plan.
- `postQaReconciliation` currently adds generic edge-case and QA-checkpoint criteria, but it does not deterministically check whether concrete spec obligations were ever planned.

This creates a failure class where:

1. `spec.md` names concrete deliverables.
2. The planner compresses those into a broad summary or incomplete file list.
3. Builder and QA stay within the accepted plan.
4. Gates may pass while original feature intent is still incomplete.
5. The feature merges with scope gaps.

### 0.5 Additional Constraint: Platform Agnosticism

The orchestrator may manage features targeting:

- a TypeScript package
- a Python package
- a Java package
- a shell utility
- infrastructure or config-only changes

The enforcement system MUST NOT depend on knowing platform semantics such as:

- whether a deliverable is a React component
- whether a symbol is a Java class
- whether a Python file contains a function with a specific name

The runtime may validate traceability, planned paths, observed file changes, and gate evidence. It must not require language-specific semantic understanding in order to be correct.

### 0.6 Design Principle

Execution-critical completeness MUST not depend on prompt obedience or free-form prose interpretation alone.

The deterministic boundary must be moved to an explicit obligation contract that the runtime can validate without knowing the implementation platform.

---

## 1. Architectural Critique of the Prior Draft

### 1.1 Prompt Guidance Exists but Is Non-Authoritative

Prompt instructions help, but they do not create a machine-checkable artifact.

### 1.2 Raw-Prose Extraction Is Not a Safe Deterministic Boundary

The prior draft relied on deterministic extraction from headings, inline code, and success criteria. That is deterministic execution of an inferential parser, not a true deterministic contract.

Consequences:

- specs with different phrasing become harder or impossible to validate consistently
- formatting becomes execution-critical
- enforcement quality varies by writing style rather than requirement intent

### 1.3 `spec_coverage` Overloaded Ownership

The prior draft used one planner-authored field to represent:

- system-known obligations
- planner intent and mapping
- runtime coverage status

That conflates:

- source-of-truth requirements
- proposed implementation plan
- observed implementation state

These must be separated.

### 1.4 The Prior Draft Was Still JS/UI-Biased

Examples like `Component: Foo.tsx`, route handlers, tabs, and panels are useful fixtures, but they cannot define the core enforcement model.

If the runtime assumes those structures are normative, the feature becomes platform-coupled and fails the architecture requirement.

### 1.5 Post-QA Reconciliation Lacked a Deterministic Evidence Model

The prior draft asked reconciliation to detect:

- missing obligations
- unimplemented obligations
- untested obligations

but did not define the deterministic evidence sources needed to support those judgments across arbitrary platforms.

### 1.6 Rollout Was Too Aggressive

Making new fields immediately required at the schema level would break planner submissions during migration and would not account for:

- planner sanitizer updates
- old features
- old specs with no structured obligation inventory
- gradual calibration of false positives and false negatives

---

## 2. Revised Target Design

## 2.1 Ownership Model

Split the model into three artifacts:

1. **System-owned spec manifest**
   - canonical list of obligations
   - independent of the planner
2. **Planner-owned plan trace**
   - planner’s mapping from obligations to planned scope
3. **Runtime-owned coverage audit**
   - runtime-observed status during reconciliation

## 2.2 Canonical Source of Truth

The runtime MUST validate against a canonical obligation inventory, not against raw prose directly.

The canonical inventory may be supplied in one of two equivalent forms:

- `spec.manifest.json` sidecar adjacent to `spec.md`
- a structured `Obligation Inventory` block embedded in `spec.md` and materialized into the sidecar during spec preparation

At runtime, only the materialized manifest is authoritative.

## 2.3 Platform-Agnostic Contract Rule

The manifest and plan trace must be expressible without platform-specific semantics.

The core contract uses only:

- stable obligation IDs
- human-readable titles
- generic categories
- planned repository paths
- planned verification references

The validator may reason about:

- path membership
- path existence
- touched files in diffs/checkpoints
- planned test files
- gate evidence
- explicit verification references

The validator must not require:

- AST parsing
- symbol resolution
- framework-specific metadata
- language-specific naming conventions

## 2.4 Optional Adapter Rule

Platform-specific analyzers may be added later as optional evidence adapters.

Examples:

- Java test report adapter
- Python pytest result adapter
- TypeScript symbol inventory adapter

These adapters are advisory unless a future policy explicitly enables them. Core correctness must not depend on them.

## 2.5 Rollout Rule

This feature MUST ship with policy-controlled phases:

- `off`
- `report_only`
- `enforce`

New specs may opt into enforcement earlier than legacy specs, but the default rollout must be safe.

---

## 3. Contracts and Artifacts

## 3.1 New Artifact: `spec.manifest.json`

Location:

- `.aop/features/<feature_id>/spec.manifest.json`

This artifact is system-owned and deterministic.

Example:

```json
{
  "feature_id": "example_feature",
  "manifest_version": 1,
  "obligations": [
    {
      "obligation_id": "OBL-001",
      "title": "Provide collision-risk visualization",
      "category": "artifact",
      "source_ref": "§C",
      "verification_hint": "unit_or_integration"
    },
    {
      "obligation_id": "OBL-002",
      "title": "Expose feature files endpoint",
      "category": "endpoint",
      "source_ref": "§C",
      "verification_hint": "route_contract"
    }
  ]
}
```

### 3.1.1 Required Fields

Each obligation MUST include:

- `obligation_id`
- `title`
- `category`
- `source_ref`

Optional:

- `verification_hint`
- `notes`

### 3.1.2 Allowed `category` Values

Use platform-agnostic values only:

- `artifact`
- `endpoint`
- `workflow`
- `behavior`
- `integration`
- `contract`
- `verification`

Do not use platform-coupled categories like `react_component`, `spring_controller`, or `python_function`.

## 3.2 `plan.json` Extension: `plan_trace`

Add planner-owned field:

```json
{
  "plan_trace": [
    {
      "obligation_id": "OBL-001",
      "disposition": "in_scope",
      "planned_paths": ["packages/web-dashboard/src/components/focus/CollisionRadar.tsx"],
      "planned_test_paths": [
        "packages/web-dashboard/test/components/mission-control-panels.spec.tsx"
      ],
      "planned_verification": ["full:test", "full:typecheck"],
      "notes": "Implemented as an overview-panel artifact."
    }
  ]
}
```

### 3.2.1 Required Fields

Each trace entry MUST include:

- `obligation_id`
- `disposition`
- `planned_paths`
- `notes`

Optional:

- `planned_test_paths`
- `planned_verification`

### 3.2.2 Allowed `disposition` Values

- `in_scope`
- `deferred`
- `out_of_scope`

### 3.2.3 Validation Rules

For `in_scope`:

- `planned_paths.length >= 1`
- at least one `planned_path` MUST appear in `files.create`, `files.modify`, or `files.delete`

For `deferred|out_of_scope`:

- `notes` MUST explain why

## 3.3 Runtime-Owned Artifact: `coverage-audit.json`

Location:

- `.aop/features/<feature_id>/coverage-audit.json`

Purpose:

- record runtime-observed traceability status
- support post-QA reconciliation deterministically

Example:

```json
{
  "feature_id": "example_feature",
  "audit_version": 1,
  "entries": [
    {
      "obligation_id": "OBL-001",
      "trace_status": "mapped",
      "implementation_evidence": {
        "planned_paths_exist": true,
        "planned_paths_touched": true
      },
      "verification_evidence": {
        "planned_test_paths_exist": true,
        "gate_evidence_present": true
      },
      "audit_status": "covered"
    }
  ]
}
```

Allowed `audit_status`:

- `covered`
- `missing_trace`
- `scope_only`
- `verification_missing`
- `evidence_missing`

## 3.4 Policy Additions

Add policy section:

```yaml
planning:
  spec_traceability:
    mode: report_only # off | report_only | enforce
    require_manifest_for_new_specs: true
    allow_legacy_specs_without_manifest: true
    block_on_missing_trace: true
    block_on_verification_missing: false
```

Normative behavior:

- `off`: no manifest/trace enforcement
- `report_only`: compute findings, log them, do not block
- `enforce`: reject plan admission and force reconciliation updates according to policy

## 3.5 Error Codes

Add typed errors:

- `SPEC_MANIFEST_MISSING`
- `SPEC_MANIFEST_INVALID`
- `PLAN_TRACE_MISSING`
- `PLAN_TRACE_INVALID`
- `PLAN_TRACE_INCOMPLETE`

These errors must include:

- `retryable`
- `requires_human`
- deterministic finding lists
- suggested next actions

---

## 4. Manifest Generation and Materialization

## 4.0 Architecture Decision: Separate Inference From Enforcement

Manifest creation from arbitrary `spec.md` is not intrinsically deterministic in the strong architectural sense.

The system may deterministically execute an extraction algorithm, but it cannot deterministically guarantee that the extracted obligations are the true, complete intent of arbitrary prose.

Therefore this feature MUST separate:

1. **bootstrap inference**
   - infer candidate obligations from `spec.md`
   - inherently heuristic / non-authoritative
2. **verified contract**
   - explicit obligation artifact that runtime may enforce against

This distinction is mandatory.

Normative rules:

- do **not** model arbitrary-prose extraction as if it were guaranteed truth
- do **not** let an inferential bootstrap artifact masquerade as an enforceable manifest
- do **not** require a new long-lived `PromptIntakeAgent` for M58
- if future policy allows model-assisted extraction, it remains optional and non-authoritative until promotion

## 4.1 Generation Principle

The user provides only `spec.md`.

From that input, the control plane may generate a **bootstrap manifest proposal**, not an automatically-enforceable contract.

The generation pipeline is intentionally two-stage:

1. **bootstrap proposal generation**
   - the system parses `spec.md`
   - the system infers candidate obligations
   - the output is persisted as a non-authoritative proposal artifact
2. **verification / promotion**
   - the proposal is either:
     - promoted by structured-spec evidence
     - promoted by explicit review/acceptance
     - or retained as bootstrap-only
   - only after promotion does it become enforceable

This keeps user burden low without pretending that arbitrary prose can deterministically yield an authoritative manifest.

## 4.1.1 Actual System Flow

The concrete system flow should be:

1. user provides `spec.md`
2. feature is ingested / canonicalized into `.aop/features/<feature_id>/spec.md`
3. control plane checks for:
   - bootstrap proposal artifact
   - verified manifest artifact
4. if no bootstrap artifact exists, control plane runs proposal generation over `spec.md`
5. generator persists `spec.manifest.bootstrap.json`
6. control plane attempts promotion if policy and evidence allow it
7. planner receives:
   - `spec.md`
   - bootstrap manifest proposal
   - verified manifest, if one exists
8. planner produces `plan.json` including `plan_trace`
9. `PlanService` validates:
   - against `spec.manifest.verified.json` in `enforce` mode
   - against bootstrap proposal only in `report_only` mode, unless policy explicitly allows auto-promotion
10. reconciliation later audits implementation and verification evidence against the same verified manifest when present, or against bootstrap proposal in advisory mode

This is the intended answer to:

- "How do we actually make the manifest in the first place within the system?"

Answer:

- **the control plane makes a bootstrap proposal automatically from `spec.md`, then promotes it only when it becomes trustworthy enough to enforce**

## 4.2 Where Generation Happens

Bootstrap proposal generation MUST occur at the earliest stable artifact boundary after spec ingestion and before plan enforcement.

Preferred insertion points:

- during spec preparation / canonical spec ingestion
- or immediately before the first `plan.submit` for a feature that has no manifest yet

Normative behavior:

- if `spec.manifest.verified.json` already exists, runtime uses it for enforcement
- else if `spec.manifest.bootstrap.json` exists, runtime uses it for advisory/report-only traceability unless policy allows promotion
- else runtime generates `spec.manifest.bootstrap.json` from `spec.md`
- runtime must persist generated artifacts rather than reparsing prose on every decision

Preferred integration points, in order:

1. spec ingestion / feature initialization path
2. first `feature.get_context` call for a feature with missing manifest
3. immediately before first `plan.submit`, as a fallback only

The earlier the bootstrap proposal is generated, the better, because the planner should see the same candidate obligations the runtime will later audit or enforce after promotion.

## 4.2.1 Required Runtime Ownership

The following responsibilities must be explicit in implementation:

- **Spec ingestion / bootstrap layer**
  - ensure `spec.md` exists in canonical feature location
  - trigger bootstrap proposal generation when needed
- **Bootstrap manifest proposal service**
  - produce and persist `spec.manifest.bootstrap.json`
- **Manifest verification / promotion service**
  - decide whether a bootstrap proposal may become `spec.manifest.verified.json`
- **Feature context provider**
  - return `spec`, bootstrap proposal, and verified manifest to the planner
- **Plan validator**
  - validate `plan_trace` against the verified manifest when enforcement applies
- **Reconciliation loop**
  - audit implementation/verification progress against the verified manifest when present, or advisory bootstrap proposal when not

This avoids ambiguity about where the manifest “comes from.”

## 4.3 Bootstrap Proposal Service Responsibilities

Create a deterministic manifest-generation service, for example:

- `apps/control-plane/src/application/services/spec-manifest-proposal-service.ts`

Responsibilities:

- parse `spec.md`
- infer candidate obligations from high-signal spec structures
- normalize candidate obligations into generic categories
- assign stable obligation IDs
- emit confidence metadata and extraction provenance
- persist the materialized `spec.manifest.bootstrap.json`

## 4.3.1 Bootstrap Proposal Interface

The implementation should define a narrow system-owned interface along these lines:

```ts
interface SpecManifestProposalPort {
  proposeFromSpec(input: {
    featureId: string;
    specText: string;
    existingBootstrapManifest?: BootstrapManifest | null;
  }): Promise<BootstrapManifestProposalResult>;
}
```

Where `BootstrapManifestProposalResult` contains:

- `bootstrapManifest`
- `created`
- `updated`
- `generation_mode`
- `findings`

The key architectural point is:

- this is an application service producing a proposal artifact, not an agent session and not an authoritative verifier

## 4.3.2 Manifest Verification Interface

The implementation should also define a distinct promotion interface:

```ts
interface ManifestVerificationPort {
  promoteToVerified(input: {
    featureId: string;
    bootstrapManifest: BootstrapManifest;
    specText: string;
    policyMode: 'off' | 'report_only' | 'enforce';
  }): Promise<ManifestVerificationResult>;
}
```

`ManifestVerificationResult` should include:

- `verifiedManifest` or `null`
- `promoted`
- `promotion_basis`
- `blocking_findings`
- `advisory_findings`

This makes the uncertainty boundary explicit in the API surface.

## 4.3.3 Initial Invocation Sites

The implementation plan should explicitly wire the generator into one of these existing seams:

- feature lifecycle / spec ingestion service
- feature bootstrap path
- context loading path before planner sees the feature

Preferred behavior:

- generate bootstrap proposal once eagerly when the feature is created
- regenerate bootstrap proposal only when `spec.md` changes or the proposal is missing/invalid
- attempt promotion only when policy or explicit workflow requests it

The system should not regenerate bootstrap or verified manifests opportunistically on every planner turn.

## 4.4 Inference Inputs

The generator may infer obligations only from deterministic textual structures already common in repo specs, such as:

- section headings
- subsection headings
- tables
- numbered implementation steps
- endpoint contract sections
- explicit “success criteria” sections
- inline code identifiers inside those structures

It must not rely on:

- implementation-language parsing
- repository ASTs
- framework-specific symbol resolution
- probabilistic embedding similarity

## 4.5 Initial Inference Rules

The initial generator should be intentionally narrow and platform-agnostic.

It SHOULD infer obligations from constructs such as:

- `### Component: \`Foo.tsx\``-> category`artifact`
- `### Pure Function: \`deriveCollisionRisk\``-> category`artifact`
- `### GET /api/...` -> category `endpoint`
- “Success Criteria” rows -> category `verification`
- numbered implementation/migration steps that name concrete deliverables -> category `workflow` or `artifact`

The important constraint is not the label itself; it is that the generator converts platform-flavored phrasing into platform-agnostic manifest categories.

## 4.6 Manifest Shape Additions

To make generation auditable, each manifest obligation SHOULD include:

- `generated_from`
  - source line/section metadata
- `generation_rule`
  - which extractor rule produced it
- `generation_confidence`
  - `high | medium | low`

Example:

```json
{
  "obligation_id": "OBL-002",
  "title": "Expose feature files endpoint",
  "category": "endpoint",
  "source_ref": "§C",
  "verification_hint": "route_contract",
  "generated_from": {
    "heading": "GET /api/features/[id]/files"
  },
  "generation_rule": "endpoint_heading",
  "generation_confidence": "high"
}
```

This metadata is for auditability; the core planner/runtime contract still keys on `obligation_id`.

## 4.7 Stable ID Strategy

Obligation IDs MUST be generated deterministically from normalized source facts, then stabilized once persisted.

Recommended algorithm:

1. derive a normalized fingerprint from:
   - `category`
   - normalized title
   - nearest section reference
2. map that fingerprint to a deterministic ordinal or short hash
3. persist the generated `obligation_id`

If the spec is revised:

- existing IDs should be preserved when normalized source facts still match
- new obligations get new IDs
- removed obligations disappear explicitly from regenerated manifest output

The system must prefer ID stability over cosmetic re-numbering.

## 4.8 Artifact Types and Promotion Modes

The system must distinguish two artifacts:

- `spec.manifest.bootstrap.json`
  - inferred
  - non-authoritative by default
- `spec.manifest.verified.json`
  - authoritative
  - may be used for enforcement

Example bootstrap artifact:

```json
{
  "feature_id": "example_feature",
  "manifest_version": 1,
  "artifact_type": "bootstrap",
  "obligations": []
}
```

Example verified artifact:

```json
{
  "feature_id": "example_feature",
  "manifest_version": 1,
  "artifact_type": "verified",
  "verification_basis": "policy_approved_auto_promotion",
  "obligations": []
}
```

## 4.9 Enforcement Boundary

The runtime MUST NOT enforce directly against arbitrary bootstrap inference unless that inference has been promoted to a verified manifest.

Blocking behavior may apply only when one of the following is true:

- a `spec.manifest.verified.json` exists
- policy explicitly allows auto-promotion of qualifying bootstrap obligations into a verified manifest

Auto-promotion, if allowed, must be gated by policy-defined thresholds such as:

- `generation_confidence = high`
- extractor rule is on the approved list
- no conflicting findings were produced

Bootstrap-only obligations may appear in findings, but they should not hard-block until promotion occurs.

## 4.10 Legacy Spec Rule

Legacy specs without any manifest artifacts may still be onboarded automatically:

- runtime generates a bootstrap proposal from `spec.md`
- planner receives that bootstrap proposal immediately
- plan/reconciliation log findings against it
- blocking behavior remains policy-controlled

This preserves the requirement that users only provide `spec.md`, while still giving the system a materialized artifact to reason about.

## 4.11 Optional Future Extension: Model-Assisted Bootstrap

If a future version wants stronger initial extraction, it may add an optional model-assisted bootstrap pass.

That design would look like:

- deterministic generator runs first
- optional model-assisted extractor proposes supplemental obligations
- system merges only policy-approved, reviewable proposals into a bootstrap manifest

But this is explicitly a future extension.

For M58:

- no `PromptIntakeAgent`
- no mandatory LLM preprocessing role
- bootstrap proposal generation remains system-owned
- verified enforcement remains separate from proposal generation

---

## 5. Plan Admission Validation

## 5.1 Validation Inputs

`PlanService` must validate against:

- `spec.manifest.json`
- `plan.plan_trace`
- `plan.files`
- `plan.acceptance_criteria`
- policy mode

## 5.2 Validation Sequence

1. load and validate manifest
2. load and validate `plan_trace`
3. ensure each manifest obligation has exactly one trace entry
4. ensure each `in_scope` trace maps to planned paths
5. ensure no unknown `obligation_id` appears in `plan_trace`
6. in enforce mode, reject when required traceability is incomplete

## 5.3 Deterministic Rejection Rules

Reject plan in `enforce` mode when:

- manifest is required but missing
- manifest exists but is invalid
- any manifest obligation lacks a trace entry
- any trace entry references an unknown obligation
- any `in_scope` trace has no valid planned path mapping
- planner emits duplicate trace entries for one obligation

Do not reject based on language-specific implementation inference.

## 5.4 Planner-Facing Findings

On rejected submission, append a planner-visible note summarizing:

- total obligations
- in-scope obligations
- deferred/out-of-scope obligations
- missing trace entries
- invalid trace entries

---

## 6. Post-QA Reconciliation Hardening

## 6.0 End-to-End Deterministic Evaluation Model

The implementation must make the following transition explicit:

1. the system inferentially generates `spec.manifest.json` from `spec.md`
2. the planner maps each `obligation_id` into `plan_trace`
3. builder and QA produce deterministic runtime artifacts:
   - updated worktree state
   - checkpoint diffs
   - patch history
   - gate evidence
4. the runtime computes a `coverage-audit.json` by comparing:
   - manifest obligations
   - planner trace
   - observed file/path evidence
   - observed verification evidence
5. the runtime decides whether the feature is:
   - complete enough to stay converged
   - missing traceability only
   - missing implementation work
   - missing verification work
6. if gaps remain, the runtime forces the planner to revise the plan so the builder and QA have explicit next work

This is the core bridge from:

- "the AI gave us a manifest"

to:

- "the system can deterministically measure how much of that manifest is planned, implemented, and verified."

## 6.0.1 Deterministic Status Ladder Per Obligation

Each obligation in `coverage-audit.json` must be reduced to one of the following runtime states:

- `missing_trace`
  - no `plan_trace` entry exists
- `planned_only`
  - trace exists, but no implementation evidence has been observed
- `in_progress`
  - trace exists and some implementation evidence exists, but verification evidence is incomplete
- `verified`
  - trace exists, implementation evidence exists, and required verification evidence exists
- `deferred`
  - planner explicitly marked it deferred
- `out_of_scope`
  - planner explicitly marked it out of scope

These states must be computed from deterministic artifacts only.

## 6.0.2 Deterministic Evidence Inputs

For every `obligation_id`, the audit may use only the following evidence:

- manifest entry
- `plan_trace` entry
- accepted `plan.files`
- current worktree path existence
- touched paths from:
  - checkpoint diffs
  - accepted patches
  - current feature diff
- current gate evidence by mode
- existence of `planned_test_paths`
- freshness/pass-fail status of gate evidence

The audit must not use:

- semantic interpretation of source code
- model self-reporting
- natural-language summary text from the planner/builder

## 6.0.3 Actual Audit Reduction Rules

For `disposition=in_scope`, compute:

1. `trace_valid`
   - true when the trace entry exists and its `planned_paths` are within accepted plan scope
2. `implementation_evidence_present`
   - true when at least one `planned_path` has deterministic implementation evidence
3. `verification_required`
   - true when:
     - manifest `verification_hint` indicates verification is required, or
     - `planned_test_paths` / `planned_verification` are present
4. `verification_evidence_present`
   - true when required verification artifacts exist and relevant gate evidence is fresh enough per policy

Reduction:

- if no trace entry: `missing_trace`
- if trace invalid: `missing_trace`
- if trace valid and no implementation evidence: `planned_only`
- if trace valid and implementation evidence exists but verification is still missing: `in_progress`
- if trace valid and implementation evidence exists and verification evidence exists: `verified`

For `deferred` and `out_of_scope`:

- preserve that status directly in the audit
- do not promote to `verified`

## 6.0.4 How Implementation Evidence Is Computed

Implementation evidence must be path-based and disposition-aware:

- for created paths:
  - file currently exists and path appears in touched-path evidence
- for modified paths:
  - path appears in touched-path evidence
- for deleted paths:
  - path is listed in delete scope and no longer exists in worktree, with touched-path evidence showing deletion

Because this is platform-agnostic, "implementation evidence" means:

- the planned repository artifact changed in the expected way

not:

- the runtime has proven the business logic is semantically correct

## 6.0.5 How Verification Evidence Is Computed

Verification evidence is also platform-agnostic.

It is satisfied only by deterministic artifacts such as:

- `planned_test_paths` exist in the worktree
- relevant gate mode evidence is present, fresh, and passing
- explicitly named verification steps in `planned_verification` have corresponding gate/evidence support

The system is not trying to prove a specific test function ran; it is proving that the planned verification surface now exists and that required gates passed on current-enough evidence.

## 6.0.6 Feature-Level Performance Against the Manifest

The system should compute feature-level rollups from per-obligation audit states:

- `total_obligations`
- `verified_count`
- `in_progress_count`
- `planned_only_count`
- `missing_trace_count`
- `deferred_count`
- `out_of_scope_count`

Derived metrics:

- `traceability_ratio = (verified + in_progress + planned_only + deferred + out_of_scope) / total_obligations`
- `implementation_ratio = (verified + in_progress) / total_in_scope_obligations`
- `verification_ratio = verified / total_verification_required_obligations`

These metrics are for reporting and consistency tracking. Blocking decisions should still use discrete policy rules, not ratios alone.

## 6.1 Deterministic Evidence Sources

Reconciliation may only use platform-agnostic evidence:

- manifest obligations
- accepted `plan_trace`
- planned paths
- checkpoint / patch touched paths
- existence of planned test paths
- gate evidence freshness and status
- explicit verification references in the trace

## 6.2 What Reconciliation May Assert

Reconciliation may deterministically conclude:

- an obligation has no trace
- an `in_scope` obligation has no planned path
- planned paths were never touched
- planned test paths do not exist
- expected verification evidence is absent

Reconciliation may not deterministically conclude:

- a Java class is semantically complete
- a Python function satisfies business logic
- a UI component visually matches intent

Those remain QA and human-review concerns unless future adapters are explicitly enabled.

## 6.3 Coverage Audit Outcomes

Add reconciliation reasons such as:

- `manifest_missing`
- `trace_missing:<n>`
- `trace_invalid:<n>`
- `implementation_evidence_missing:<n>`
- `verification_evidence_missing:<n>`

## 6.4 Update Decision Rule

`planDecision` MUST be `update_required` in `enforce` mode when:

- any obligation lacks a trace
- any required trace is invalid
- any `in_scope` obligation has no path evidence
- policy requires verification evidence and that evidence is missing

In `report_only` mode:

- findings are logged
- `plan.update` is not forced solely by traceability findings

## 6.4.1 Gap Classification

Reconciliation must classify every gap into one of three actionable buckets:

- `planning_gap`
  - the manifest obligation is not represented correctly in `plan_trace`
  - action: planner must revise plan
- `implementation_gap`
  - trace exists, but implementation evidence is missing
  - action: keep or revise plan so builder has explicit work
- `verification_gap`
  - implementation evidence exists, but verification evidence is missing
  - action: keep or revise plan so QA/builder add the missing verification surface

This classification is critical. Without it, the system can detect a gap but still fail to say what should happen next.

## 6.4.2 Forced Gap-Closure Workflow

When reconciliation finds gaps, the runtime must do more than log them.

It must construct a deterministic remediation payload for the planner:

```json
{
  "spec_traceability_audit": {
    "planning_gaps": [],
    "implementation_gaps": [],
    "verification_gaps": [],
    "rollup": {
      "total_obligations": 0,
      "verified_count": 0,
      "in_progress_count": 0,
      "planned_only_count": 0,
      "missing_trace_count": 0
    }
  }
}
```

Planner obligations on receipt:

- for `planning_gap`:
  - add or correct `plan_trace`
  - expand `files` / `allowed_areas` if needed
- for `implementation_gap`:
  - keep the obligation `in_scope`
  - make the implementation work explicit in acceptance criteria, planned paths, or verification steps
- for `verification_gap`:
  - add missing test paths or verification references
  - update acceptance criteria so QA can deterministically verify completion

The planner must not be allowed to resolve a real `implementation_gap` or `verification_gap` merely by relabeling it `out_of_scope` unless policy and spec intent permit that change.

## 6.4.3 Builder and QA Responsibilities After Reconciliation

The system must treat the revised plan as the closure mechanism:

- builder closes `implementation_gap` by producing deterministic path evidence against the revised trace
- QA closes `verification_gap` by producing deterministic verification evidence against the revised trace

This makes the closure loop concrete:

1. manifest defines expected obligations
2. audit identifies exact missing states
3. planner revises plan to encode next required work
4. builder/QA execute against that revision
5. audit recomputes and checks whether the gap is now closed

## 6.5 No-Update Guardrail

`reconciled_no_gaps` is only valid when:

- gate/evidence checks pass
- all required obligations are traced
- all required trace entries are valid
- all required evidence checks configured by policy are satisfied

---

## 7. Planner Prompt Revisions

Update:

- `agentic/orchestrator/prompts/planner.system.md`
- `config/agentic/orchestrator/prompts/planner.system.md`

Add explicit sections:

### 7.1 During Initial Planning

- do not infer obligations from memory; read the materialized manifest or obligation inventory
- trace every obligation ID into `plan_trace`
- broad summaries do not satisfy obligation traceability
- mark items `deferred` or `out_of_scope` explicitly when they are not being implemented

### 7.2 During Reconciliation

- audit current implementation against `plan_trace`
- revise the plan when required obligation traces or evidence are missing
- do not keep the plan unchanged merely because gates are green

### 7.3 Prompt Boundary

Prompt guidance is advisory. Runtime validation remains authoritative.

---

## 8. Implementation Plan

### M58.1 — Add manifest and trace schemas

Update:

- `agentic/orchestrator/schemas/plan.schema.json`
- add new schema for `spec.manifest.json`
- add policy schema/default updates for `planning.spec_traceability`

### M58.2 — Add manifest materialization support

Update/create:

- `apps/control-plane/src/cli/spec-preparation.ts`
- any supporting utilities needed to materialize or validate obligation inventories

### M58.3 — Add `SpecTraceabilityService`

Create:

- `apps/control-plane/src/application/services/spec-traceability-service.ts`

Responsibilities:

- load and validate manifest
- compare manifest to `plan_trace`
- build deterministic coverage audit findings

### M58.4 — Enforce traceability in `PlanService`

Update:

- `apps/control-plane/src/application/services/plan-service.ts`
- `apps/control-plane/src/core/error-codes.ts`

### M58.5 — Update planner-output sanitization

Update:

- `apps/control-plane/src/supervisor/worker-decision-loop.ts`

Reason:

- planner sanitizer must preserve `plan_trace` during rollout

### M58.6 — Add post-QA coverage audit

Update:

- `apps/control-plane/src/supervisor/planning-wave-executor.ts`
- `apps/control-plane/src/application/services/feature-lifecycle-service.ts` if additional context payload is needed

### M58.7 — Strengthen planner prompts

Update:

- `agentic/orchestrator/prompts/planner.system.md`
- `config/agentic/orchestrator/prompts/planner.system.md`

### M58.8 — Add fixtures and tests

Add/extend:

- `apps/control-plane/test/spec-traceability-service.spec.ts`
- `apps/control-plane/test/plan-service.spec.ts`
- reconciliation tests for the planning wave executor
- prompt contract tests
- fixture corpus for TypeScript, Python, Java, CLI/config specs

---

## 9. Testing Plan

## 9.1 Unit Tests

Add:

- manifest validation tests
- trace validation tests
- coverage-audit reduction tests
- policy-mode tests for `off`, `report_only`, `enforce`
- deterministic status-ladder tests covering:
  - `missing_trace`
  - `planned_only`
  - `in_progress`
  - `verified`
  - `deferred`
  - `out_of_scope`

## 9.2 Plan Service Tests

Coverage:

- reject plan missing `plan_trace` in enforce mode
- reject plan with unknown obligation IDs
- reject `in_scope` trace without valid planned path
- accept plan when all manifest obligations are traced
- accept `deferred` and `out_of_scope` dispositions with rationale

## 9.3 Reconciliation Tests

Coverage:

- reconciliation logs findings in `report_only`
- reconciliation forces `plan.update` in `enforce` mode when trace is incomplete
- `reconciled_no_gaps` is not emitted when required traceability gaps remain
- remediation payload classifies gaps into `planning_gap`, `implementation_gap`, and `verification_gap`
- planner revisions are required to encode explicit closure work for each unresolved obligation category

## 9.4 Cross-Platform Fixture Corpus

Add fixtures representing:

- a TypeScript UI spec
- a Python service/library spec
- a Java backend/package spec
- a CLI or config-oriented spec

Each fixture must have:

- `spec.md`
- `spec.manifest.json`
- example `plan.json`
- expected validation outcome

## 9.5 Golden Tests

Manifest and trace validation must run against golden fixtures so that:

- rule changes are explicit
- false positives are visible
- drift across spec-writing styles is measurable

---

## 10. Quality and Consistency Controls

Quality consistency requires more than passing unit tests.

## 10.1 Quality Gates for This Feature

Track these metrics in CI:

- total obligations per fixture
- missing trace count
- invalid trace count
- report-only findings count
- fixture false-positive count
- fixture false-negative count
- obligation status distribution drift across fixtures
- ratio drift for:
  - traceability
  - implementation
  - verification

## 10.2 Change Management

Any change to:

- manifest schema
- trace schema
- validation rules
- bootstrap extractor

must update:

- golden fixtures
- expected findings
- prompt contract tests if planner payload shape changes

## 10.3 Review Standard

No rule may move from `report_only` to `enforce` until:

- cross-platform fixtures are green
- false-positive rate is understood
- at least one real-world legacy spec has been exercised in dry-run mode

## 10.4 Human Override Principle

If a spec lacks a valid manifest and policy allows legacy fallback:

- emit findings
- do not silently fabricate authoritative obligations

The system must prefer an explicit “cannot enforce yet” state over false determinism.

---

## 11. Risks and Mitigations

| Risk                                                | Impact | Mitigation                                                                                            |
| --------------------------------------------------- | ------ | ----------------------------------------------------------------------------------------------------- |
| Manifest authoring adds friction to spec creation   | Medium | Support spec-preparation helpers and bootstrap materialization in `report_only` mode.                 |
| Legacy specs lack structured obligations            | High   | Allow legacy fallback in `report_only`; require manifests only for new or revised specs under policy. |
| Teams want semantic platform validation immediately | Medium | Keep adapters optional and advisory until separately specified and policy-enabled.                    |
| Planner/output drift breaks trace payloads          | Medium | Add prompt contract tests and update planner sanitizer in lockstep.                                   |
| Reconciliation findings become noisy                | Medium | Restrict enforced findings to manifest/trace/path/evidence facts only.                                |

---

## 12. Acceptance Criteria

This feature is complete when all of the following are true:

1. New specs can materialize a canonical `spec.manifest.json` with stable obligation IDs.
2. `plan.json` supports planner-authored `plan_trace` entries keyed by `obligation_id`.
3. `PlanService` can validate manifest-to-trace completeness in `report_only` and `enforce` modes.
4. Validation rules remain platform-agnostic and do not require language-specific semantic analysis.
5. Post-QA reconciliation computes a runtime-owned coverage audit from manifest, trace, path evidence, and gate evidence.
6. In `enforce` mode, missing required traceability forces plan rejection or plan revision as configured by policy.
7. In `report_only` mode, findings are logged without blocking execution.
8. The runtime reduces every obligation deterministically into one of: `missing_trace`, `planned_only`, `in_progress`, `verified`, `deferred`, or `out_of_scope`.
9. Reconciliation emits deterministic remediation payloads that classify unresolved work into `planning_gap`, `implementation_gap`, and `verification_gap`.
10. Cross-platform fixtures for at least TypeScript, Python, and Java style specs pass consistently.
11. Prompt contract tests and planner sanitizer updates preserve the new trace payload shape.
12. `npm run typecheck`, `npm run lint`, and relevant Vitest suites pass.

---

## 13. Explicit Non-Requirements

This spec does not require:

- semantic parsing of every sentence in the spec
- platform-specific AST analyzers
- a new CLI command
- dashboard changes
- embedding-based similarity ranking
- changing builder patch admission rules beyond existing plan/file scope protections

The purpose is narrower and stricter:

- define canonical obligations
- require planner traceability to those obligations
- audit that traceability deterministically and platform-agnostically
- keep runtime enforcement honest about what it can and cannot prove
