agentic-orchestrator 0.1.28 → 0.2.0

package/spec-files/outstanding/agentic_orchestrator_spec_coverage_and_reconciliation_enforcement_spec.md

@@ -0,0 +1,1411 @@
+# 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