agentic-orchestrator 0.1.6 → 0.1.8

package/spec-files/completed/agentic_orchestrator_spec.md

@@ -46,18 +46,21 @@
 
 ### 3.1 Processes
 
-**A) MCP Server (inside Docker, bind-mounted repo)**  
+**A) MCP Server (inside Docker, bind-mounted repo)**
+
 - Exposes tools via MCP.
 - Runs git and gate commands inside bind mount.
 - Enforces schemas, policies, locks, collisions, and patch constraints.
 - Writes canonical state and evidence.
 
-**B) Supervisor Runtime (outside MCP, vendor-agnostic)**  
+**B) Supervisor Runtime (outside MCP, vendor-agnostic)**
+
 - Responsible for “spinning up agents” (Orchestrator + workers).
 - Applies role-scoped tool permissions.
 - Runs orchestration algorithm across features and clusters.
 
-**C) Agent Runtime(s) (Claude Code, Codex CLI, etc.)**  
+**C) Agent Runtime(s) (Claude Code, Codex CLI, etc.)**
+
 - Connect to MCP tools.
 - Generate structured artifacts and diffs under Supervisor control.
 
@@ -164,7 +167,7 @@ agentic/
 - Use Ralph Loop by reacting to MCP gate outputs.
 - Orchestrator chooses collision resolution strategy and merge order.
 
-### 5.3 Supervisor Runtime MUST do (enforcement that is *not* MCP)
+### 5.3 Supervisor Runtime MUST do (enforcement that is _not_ MCP)
 
 - Spawn/maintain sessions for orchestrator + workers.
 - Enforce role tool permissions (tool-call firewall).
@@ -181,6 +184,7 @@ agentic/
 ### 6.0 MCP Tool Contract Schemas
 
 In addition to runtime state schemas, the MCP boundary MUST be formalized with:
+
 - `agentic/orchestrator/tools/catalog.json` as the single source of truth for tool metadata and schema references.
 - `agentic/orchestrator/tools/protocol.json` for pinned MCP protocol/SDK/transports.
 - `agentic/orchestrator/tools/errors.schema.json` for normalized error envelopes.
@@ -191,6 +195,7 @@ Contract validation MUST fail CI when protocol pins drift or when `catalog.json`
 ### 6.1 `plan.json` JSON Schema (`plan.schema.json`)
 
 **Required fields**:
+
 - `feature_id` (string, derived from spec filename; pattern `^[a-z0-9_][a-z0-9_-]*$` recommended)
 - `plan_version` (integer, starts at `1`, increments by `+1` on each accepted update)
 - `summary` (string, min 5 chars)
@@ -214,11 +219,13 @@ Contract validation MUST fail CI when protocol pins drift or when `catalog.json`
 - Optional: `revision_reason` (string)
 
 **Verification overrides** (optional):
+
 - `modes.fast.steps` array of gate step overrides (rare; discourage)
 - `modes.full.steps` overrides
-Default behavior is use `gates.yaml`.
+  Default behavior is use `gates.yaml`.
 
 **Plan revision rules**:
+
 - First accepted plan MUST have `plan_version=1` and no `revision_of`.
 - `plan.update` MUST require `expected_plan_version` and reject stale updates.
 - MCP MUST re-run schema, policy, lock, and collision checks for every revision.
@@ -230,6 +237,7 @@ Default behavior is use `gates.yaml`.
 State file is Markdown with YAML front matter. MCP validates the front matter object.
 
 Required fields:
+
 - `feature_id` (string)
 - `version` (integer, monotonic)
 - `branch` (string)
@@ -250,6 +258,7 @@ Required fields:
 Tracks global orchestration status.
 
 Required fields:
+
 - `version` integer (monotonic)
 - `active` array of feature ids
 - `blocked` array
@@ -264,6 +273,7 @@ Required fields:
 YAML is validated by loading and validating against JSON schema equivalent.
 
 Required fields:
+
 - `version` number
 - `profiles` object:
   - profile name → profile object
@@ -278,6 +288,7 @@ Required fields:
   - Optional: `timeout_seconds` number
 
 Optional:
+
 - `parsers.coverage` with:
   - `type`: `none|lcov|junit_xml|jacoco_xml|cobertura_xml|custom`
   - `path` string
@@ -290,6 +301,7 @@ Optional:
 ### 6.5 `policy.yaml` Schema (`policy.schema.json`)
 
 Required fields:
+
 - `version`
 - `commit_policy.allow_commit` boolean
 - `commit_policy.allow_merge` boolean
@@ -333,6 +345,7 @@ Required fields:
 - Optional additional thresholds (coverage, performance, repo-specific gates) beyond the required testing minima above.
 
 Policy interpretation notes:
+
 - `commit_policy.*` controls direct low-level commit tools (`repo.commit`).
 - `merge_policy.*` controls high-level merge promotion (`feature.ready_to_merge`), including the commit created as part of merge promotion.
 - `implementation.workspace` and `testing.*` constrain the orchestrator codebase implementation; they do not remove platform-agnostic support for managed target repositories.
@@ -352,6 +365,7 @@ Policy interpretation notes:
 Repo-level worker prompt configuration.
 
 Required fields:
+
 - `version`
 - `roles` object:
   - `planner.system_prompt_path` (optional)
@@ -365,6 +379,7 @@ Required fields:
   - `role_provider_overrides` object (optional per-role provider/model overrides)
 
 Prompt loading rules:
+
 - If configured prompt path exists, Supervisor MUST load and inject it as the role system prompt.
 - If path is absent or file missing and `missing_prompt_behavior=ignore`, Supervisor uses built-in defaults.
 - Prompt paths MUST be repo-relative and validated with path rules (§6.6).
@@ -375,6 +390,7 @@ Prompt loading rules:
 Per-feature QA execution index used to keep QA agent context small and resumable.
 
 Required fields:
+
 - `feature_id`
 - `version` (integer, monotonic)
 - `source_diff_ref` (string identifying diff snapshot)
@@ -387,6 +403,7 @@ Required fields:
   - optional `evidence_refs` array
 
 Rules:
+
 - MCP MUST update file/hunk entries after every successful `repo.apply_patch`.
 - MCP MUST compute `required_tests` deterministically from configured gate steps and changed paths/hunks so QA sees exact pending test obligations at any time.
 - QA agent MUST update statuses/evidence after each executed test batch.
@@ -398,6 +415,7 @@ Rules:
 ### 7.1 Tool Contract Norms
 
 All tools MUST:
+
 - Accept `actor_type` (`orchestrator|planner|builder|qa|system`) and `actor_id` (string).
 - Return JSON with at least:
   - `ok` boolean
@@ -422,29 +440,38 @@ Authorization MUST be deny-by-default; any disallowed role/tool attempt fails wi
 ### 7.2 Required Tools (V1)
 
 #### Feature lifecycle
-1) `feature.discover_specs()`
+
+1. `feature.discover_specs()`
+
 - Returns list of `{feature_id, spec_path}` under `agentic/features/*/spec.md`.
 
-2) `feature.init(feature_id)`
+2. `feature.init(feature_id)`
+
 - Creates feature folder structure if missing.
 - Creates/ensures branch + worktree (see `repo.ensure_worktree`).
 - Writes `state.md` default with `status=planning`.
 
-3) `feature.get_context(feature_id)`
+3. `feature.get_context(feature_id)`
+
 - Returns: spec.md text, parsed state front matter, plan.json (if exists), latest evidence summary, and current `qa_test_index.json`.
 
-4) `feature.state_get(feature_id)`
+4. `feature.state_get(feature_id)`
+
 - Returns parsed state front matter + raw markdown body.
 
-5) `feature.state_patch(feature_id, expected_version, patch)`
+5. `feature.state_patch(feature_id, expected_version, patch)`
+
 - Restricted: allowed only for `actor_type=system|orchestrator` by policy; typically MCP internal.
 - Validates against schema before writing.
 
-6) `feature.log_append(feature_id, note)`
+6. `feature.log_append(feature_id, note)`
+
 - Appends to `decisions.md` or `state.md` body section; includes `actor` stamp.
 
 #### Plan
-7) `plan.submit(feature_id, plan_json, expected_version?)`
+
+7. `plan.submit(feature_id, plan_json, expected_version?)`
+
 - Validates plan schema.
 - Enforces `policy.yaml` constraints:
   - required fields
@@ -454,9 +481,10 @@ Authorization MUST be deny-by-default; any disallowed role/tool attempt fails wi
 - Persists `plan.json`.
 - Updates `state.md` gates: `plan=pass` and status to `building` if allowed.
 
-8) `plan.get(feature_id)`
+8. `plan.get(feature_id)`
+
+9. `plan.update(feature_id, expected_plan_version, plan_json)`
 
-9) `plan.update(feature_id, expected_plan_version, plan_json)`
 - Requires `plan_json.plan_version = expected_plan_version + 1`.
 - Requires `plan_json.revision_of = expected_plan_version`.
 - Re-runs full validation, lock checks, and collision scan.
@@ -464,12 +492,15 @@ Authorization MUST be deny-by-default; any disallowed role/tool attempt fails wi
 - Existing worktree diffs are retained, but all subsequent `repo.apply_patch` operations MUST validate against the latest accepted plan.
 
 #### Repo/worktree
-10) `repo.ensure_worktree(feature_id)`
+
+10. `repo.ensure_worktree(feature_id)`
+
 - Ensures `.worktrees/<feature_id>` exists and is checked out to `<feature_id>` branch.
 - If branch is newly created, cut it from `policy.worktree.base_branch` at the current head SHA.
 - Must store branch name in state.
 
-11) `repo.apply_patch(feature_id, unified_diff)`
+11. `repo.apply_patch(feature_id, unified_diff)`
+
 - Validates: plan exists (unless policy allows).
 - Parses patch to determine touched paths.
 - Enforces:
@@ -482,22 +513,26 @@ Authorization MUST be deny-by-default; any disallowed role/tool attempt fails wi
 - Returns updated `git status --porcelain` plus list of changed files.
 - Rebuilds or incrementally updates `qa_test_index.json` for changed files/hunks.
 
-12) `repo.status(feature_id)`
-13) `repo.diff(feature_id, options?)`
+12. `repo.status(feature_id)`
+13. `repo.diff(feature_id, options?)`
+
 - Options: `--stat`, `--name-only`, etc.
 
-14) `repo.read_file(feature_id, path)`
-15) `repo.search(feature_id, query)`
+14. `repo.read_file(feature_id, path)`
+15. `repo.search(feature_id, query)`
+
 - Wrapper around `rg` with safe defaults; returns file/line matches.
 
-16) `repo.diff_bundle(feature_id)`
+16. `repo.diff_bundle(feature_id)`
+
 - Returns a “review bundle”:
   - diff stat
   - full diff (or path to stored diff)
   - touched file list
   - last gate summary
 
-17) `feature.ready_to_merge(feature_id, commit_message, merge_strategy, user_approval_token)`
+17. `feature.ready_to_merge(feature_id, commit_message, merge_strategy, user_approval_token)`
+
 - Preconditions:
   - feature status is `ready_to_merge`
   - required `full` + `merge` modes pass (policy-controlled)
@@ -508,14 +543,13 @@ Authorization MUST be deny-by-default; any disallowed role/tool attempt fails wi
   - appends merge evidence (commit SHA, merge SHA, strategy, gate snapshot)
   - releases held locks.
 
-> Low-level git tools MAY exist for debugging but SHOULD be blocked by RBAC for non-system roles:
-18) `repo.commit(feature_id, message)` (internal/optional)
-19) `repo.rebase_onto_main(feature_id)` (internal/optional)
-20) `repo.merge(feature_id)` (internal/optional)
+> Low-level git tools MAY exist for debugging but SHOULD be blocked by RBAC for non-system roles: 18) `repo.commit(feature_id, message)` (internal/optional) 19) `repo.rebase_onto_main(feature_id)` (internal/optional) 20) `repo.merge(feature_id)` (internal/optional)
 
 #### Gates/evidence
-21) `gates.list(profile?)`
-22) `gates.run(feature_id, profile, mode)`
+
+21. `gates.list(profile?)`
+22. `gates.run(feature_id, profile, mode)`
+
 - Loads `gates.yaml`, selects profile and mode.
 - Runs steps sequentially (or optionally parallel if configured, but default sequential for determinism).
 - Captures stdout/stderr per step to `logs/`.
@@ -526,36 +560,46 @@ Authorization MUST be deny-by-default; any disallowed role/tool attempt fails wi
   - overall mode result
   - evidence pointers
 
-23) `evidence.latest(feature_id)`
+23. `evidence.latest(feature_id)`
+
 - Returns last gate run summary with key log excerpt tail.
 
 #### QA context / test index
-24) `qa.test_index_get(feature_id)`
+
+24. `qa.test_index_get(feature_id)`
+
 - Returns parsed `qa_test_index.json`, summary counts by status, and exact pending `required_tests` grouped by file/hunk.
 
-25) `qa.test_index_update(feature_id, expected_version, updates, evidence_refs?)`
+25. `qa.test_index_update(feature_id, expected_version, updates, evidence_refs?)`
+
 - Allowed for `qa|system|orchestrator`.
 - Applies status updates to index entries and increments index version.
 - Requires line-hunk references when marking entries `passed|failed|waived`.
 - MUST be called by QA agent after each test batch.
 
 #### Locks/collisions
-26) `locks.acquire(resource, feature_id, wait_timeout_seconds?)`
+
+26. `locks.acquire(resource, feature_id, wait_timeout_seconds?)`
+
 - Resource names from policy.
 - Stores in `index.json` and feature state.
 - Enforces ownership.
 - MUST create lease metadata (`lease_id`, `expires_at`) and renew while holder is healthy.
 
-27) `locks.release(resource, feature_id)`
+27. `locks.release(resource, feature_id)`
+
+28. `collisions.scan()`
 
-28) `collisions.scan()`
 - Returns global collision matrix based on accepted plans.
 
 #### Reporting (for orchestrator UX)
-29) `report.dashboard()`
+
+29. `report.dashboard()`
+
 - Returns summary of all features: status, blocks, locks, last gates.
 
-30) `report.feature_summary(feature_id)`
+30. `report.feature_summary(feature_id)`
+
 - Returns state summary + diff summary + latest evidence links.
 
 ---
@@ -572,10 +616,12 @@ Authorization MUST be deny-by-default; any disallowed role/tool attempt fails wi
 ### 8.2 Collision Policy
 
 Defined in `policy.yaml`:
+
 - `collision_policy: reject|block`
-Default: `reject` with structured report so orchestrator can revise.
+  Default: `reject` with structured report so orchestrator can revise.
 
 If `collision_policy=block`:
+
 - MCP MUST persist blocked plan requests in `index.json.blocked_queue`.
 - Queue entries MUST include `{feature_id, plan_version, detected_at, collision_fingerprint, required_resources}`.
 - MCP MUST re-evaluate queued entries when relevant locks are released or plans change.
@@ -584,6 +630,7 @@ If `collision_policy=block`:
 ### 8.3 Collision Report Format
 
 On collision, MCP returns:
+
 - collision items
 - owning feature ids
 - normalized path/resource identifiers
@@ -602,17 +649,20 @@ Orchestrator agent decides strategy; Supervisor updates states accordingly.
 ### 9.1 Lock Resources
 
 Configured by `policy.yaml`, recommended defaults:
+
 - `openapi`
 - `events`
 - `db_migrations`
 - optionally: `protected:libs/core`
 
 Contract-to-lock mapping MUST be explicit:
+
 - `contracts.openapi=modify` requires lock `policy.locks.contract_to_resource.openapi` (default `openapi`).
 - `contracts.events=modify` requires lock `policy.locks.contract_to_resource.events` (default `events`).
 - `contracts.db=migration` requires lock `policy.locks.contract_to_resource.db` (default `db_migrations`).
 
 Lease rules:
+
 - Locks are leased, not perpetual.
 - Lease TTL is `policy.locks.lease_ttl_seconds`.
 - Supervisor/MCP heartbeat renews leases.
@@ -647,12 +697,12 @@ Lease rules:
   - reconstruct state from `index.json` + feature states when sessions are unavailable
   - re-drive blocked/retryable operations deterministically
 - Run orchestration loop across features:
-  1) init
-  2) planning wave
-  3) collision arbitration
-  4) build wave
-  5) qa wave
-  6) readiness report (full gates)
+  1. init
+  2. planning wave
+  3. collision arbitration
+  4. build wave
+  5. qa wave
+  6. readiness report (full gates)
 
 ### 10.2 Vendor-Agnostic Worker Interface
 
@@ -669,6 +719,7 @@ Supervisor must treat workers abstractly:
 Supervisor routes outputs to MCP tools and returns results to worker.
 
 Context bundle MUST include:
+
 - current feature state + accepted plan
 - latest evidence summary
 - current diff summary
@@ -677,6 +728,7 @@ Context bundle MUST include:
 ### 10.3 Concurrency
 
 Configurable:
+
 - `max_active_features` default 5
 - `max_parallel_gate_runs` default 2–3 (CPU dependent)
 - `max_iterations_per_phase` default 5–10
@@ -708,17 +760,18 @@ Supervisor proposes transitions; MCP is source of truth and MUST validate transi
 ### 10.6 Crash Recovery and Resume Algorithm
 
 On Supervisor or MCP restart:
-1) Load and validate `index.json` and all active feature `state.md` files.
-2) Reconcile lock leases:
+
+1. Load and validate `index.json` and all active feature `state.md` files.
+2. Reconcile lock leases:
    - if holder heartbeat is fresh, preserve lease
    - if stale, reclaim and mark affected features `blocked` with reason
-3) Reconstruct pending work from:
+3. Reconstruct pending work from:
    - features not terminal (`merged|failed`)
    - queued collisions (`blocked_queue`)
    - gate runs with no terminal evidence record
    - current `qa_test_index.json` entries not in terminal status (`passed|waived`)
-4) Resume orchestration from the earliest incomplete phase per feature.
-5) All tool retries MUST be idempotent and keyed by operation id; duplicate execution must not double-apply patches or merges.
+4. Resume orchestration from the earliest incomplete phase per feature.
+5. All tool retries MUST be idempotent and keyed by operation id; duplicate execution must not double-apply patches or merges.
 
 ### 10.7 Ephemeral QA Session Lifecycle (Context Control)
 
@@ -737,6 +790,7 @@ On Supervisor or MCP restart:
 ## 11. Orchestrator Agent Contract (User-Facing Behavior)
 
 Orchestrator Agent must:
+
 - Discover provided specs from CLI-resolved inputs (`-fi`/`-fl`) or canonical repo discovery and ask user which to run if more than N are present (optional; default pick first N).
 - Report dashboard status periodically (using `report.dashboard`).
 - Decide collision resolution (revise plan, wait, shared prerequisite).
@@ -755,6 +809,7 @@ Orchestrator must never claim gates passed without MCP results.
 ### 12.1 Command Execution
 
 MCP executes `cmd` arrays from `gates.yaml` with:
+
 - `cwd` set to the feature worktree root
 - safe environment with secret scrubbing enabled by default
 - environment variable pass-through restricted to `policy.execution.env_allowlist`
@@ -762,6 +817,7 @@ MCP executes `cmd` arrays from `gates.yaml` with:
 ### 12.2 Parsers / Metrics
 
 Supported parsers (V1):
+
 - `none`
 - `lcov` (line coverage)
 - `junit_xml` (pass/fail + counts)
@@ -773,10 +829,12 @@ If parser type is unrecognized: gate fails with `error=unsupported_parser` unles
 ### 12.3 Threshold Enforcement
 
 If coverage threshold configured in policy or gates:
+
 - MCP must parse coverage and compare.
 - Failure sets `gates.coverage_* = fail`.
 
 For this implementation:
+
 - Minimum blocking thresholds are `line >= 0.90` and `branch >= 0.90`.
 - Target thresholds are `line = 1.00` and `branch = 1.00` (reported as target attainment metrics).
 
@@ -790,9 +848,10 @@ For this implementation:
 ### 12.5 Configuration Precedence (Normative)
 
 For any gate execution parameter, precedence is:
-1) `policy.yaml` hard constraints (cannot be relaxed)
-2) `gates.yaml` selected profile/mode defaults
-3) `plan.json.verification_overrides` (may only narrow scope or tighten thresholds)
+
+1. `policy.yaml` hard constraints (cannot be relaxed)
+2. `gates.yaml` selected profile/mode defaults
+3. `plan.json.verification_overrides` (may only narrow scope or tighten thresholds)
 
 If a lower-priority source attempts to relax a higher-priority constraint, MCP MUST fail with `error=invalid_override_precedence`.
 
@@ -825,6 +884,7 @@ For this implementation, container/runtime environment MUST include Node.js and
 ## 14. Acceptance Criteria (Complete)
 
 A) **Kernel correctness**
+
 - Plan schema validation rejects invalid plans with actionable errors.
 - Plan revisions are versioned and protected by optimistic concurrency.
 - Patch enforcement prevents edits outside plan/allowed areas.
@@ -834,17 +894,20 @@ A) **Kernel correctness**
 - State/index writes are atomic and race-safe under parallel runs.
 
 B) **Parallelism and visibility**
+
 - 5 features can run concurrently with 5 worktrees.
 - User can open `.worktrees/<feature_id>` (for example `.worktrees/my_feature`) locally to review unmerged changes.
 
 C) **Platform-agnostic gates**
+
 - Same MCP works on managed target repositories:
   - Nx repo (nx commands in gates.yaml)
   - Java repo (mvn/gradle commands in gates.yaml)
   - Rust repo (cargo commands in gates.yaml)
-No MCP code changes required.
+    No MCP code changes required.
 
 D) **Orchestrator/cluster architecture**
+
 - User interacts only with Orchestrator Agent.
 - Supervisor spawns worker sessions per feature.
 - Tool-call firewall enforces role tool permissions.
@@ -854,6 +917,7 @@ D) **Orchestrator/cluster architecture**
 - QA worker runs can be closed/restarted while preserving progress via MCP-backed `qa_test_index.json`.
 
 E) **CLI entrypoint contract**
+
 - `aop run -fi <file>` launches exactly one Agent Cluster for that file.
 - `aop run -fl <folder>` launches one Agent Cluster per resolved spec file in the folder.
 - `-fi` and `-fl` mutual exclusion is enforced with deterministic structured errors.
@@ -862,6 +926,7 @@ E) **CLI entrypoint contract**
 - Feature branch/worktree folder names are derived from spec filenames using the `.spec` / `-spec` trimming rules.
 
 F) **Implementation testing standards**
+
 - Orchestrator control-plane implementation (CLI/Supervisor/MCP) is structured as an Nx monorepo.
 - Automated tests for that control-plane implementation are executed with Vitest.
 - Blocking coverage minimum is 90% for both line and branch.
@@ -877,6 +942,7 @@ F) **Implementation testing standards**
 While implementing this spec, the implementing agent MUST maintain `spec-files/progress.md` used only for implementation continuity.
 
 Required `spec-files/progress.md` contents:
+
 - current milestone (`M0..M9`) and current task
 - completed tasks since last update
 - next tasks planned
@@ -885,47 +951,59 @@ Required `spec-files/progress.md` contents:
 - last updated timestamp
 
 Update policy:
+
 - update `spec-files/progress.md` after each meaningful implementation step
 - update `spec-files/progress.md` before ending/closing an agent session for context reset
 - the next agent session MUST start by reading `spec-files/progress.md` before making changes
 
 Scope note:
+
 - `spec-files/progress.md` in this section is an implementation-process artifact only.
 - It MUST NOT be required by, read by, or enforced by the orchestrator runtime (MCP/Supervisor/worker logic).
 
 **M0: Implementation Handoff Tracking (non-runtime)**
+
 - create and maintain `spec-files/progress.md` throughout implementation.
 - keep milestone position and handoff notes current for session-to-session continuity.
 
 **M1: MCP Kernel V1 (single feature)**
+
 - feature.init, plan.submit validation, ensure_worktree, apply_patch enforcement, gates.run, evidence.latest, state updates.
 
 **M2: Worktrees + Parallelism**
+
 - worktree-per-feature, index.json, locks, collisions.
 
 **M3: Supervisor Runtime**
+
 - orchestrator + worker abstractions, role enforcement, orchestration loop, reporting tools.
 
 **M4: Platform-Agnostic Profiles**
+
 - gates.yaml profiles, multi-target gate runs, line/branch coverage parsing.
 
 **M5: Review + Merge Control**
+
 - diff bundles, dashboard summary, explicit user approval flow, `feature.ready_to_merge` commit+merge path.
 
 **M6: Resilience and Recovery**
+
 - lock leases + heartbeat, restart recovery, queued collision unblock processing.
 
 **M7: Prompt + QA Context Management**
+
 - repo-level worker prompt loading via `agents.yaml`.
 - per-feature QA change/test index maintenance and short-lived QA worker resume flow.
 
 **M8: Supervisor CLI Entrypoint**
+
 - implement `aop run` contract with `-fi` and `-fl`.
 - deterministic folder scan + spec ingestion to canonical feature layout.
 - derive `feature_id`/branch/worktree folder names from spec filename stems with `.spec` / `-spec` suffix trimming.
 - startup validation, provider selection resolution, structured errors, and dashboard streaming bootstrap.
 
 **M9: Nx + Vitest Quality Gates**
+
 - scaffold/organize orchestrator implementation as Nx monorepo projects.
 - implement Vitest-based test tasks and coverage artifact generation.
 - enforce 90% line/branch minimums with 100% line/branch target reporting.
@@ -936,18 +1014,18 @@ Scope note:
 
 The following defaults are accepted and normative:
 
-1) Lock operations are owned by `orchestrator|system`; worker roles submit `REQUEST`.
-2) Lock acquisition defaults to blocking/queued with timeout + jittered backoff.
-3) Plan revisions keep existing diffs in worktree; future patch applies are validated against latest accepted plan.
-4) Supervisor proposes state transitions, MCP validates legality and persists canonical state.
-5) `collision_policy=block` uses persistent `blocked_queue` with deterministic ordering.
-6) Precedence is `policy hard constraints > gates profile defaults > plan overrides (tighten-only)`.
-7) Gate timeout default is 600s when unspecified; transient retry default is 1; policy/schema violations are non-retryable.
-8) Review artifacts are unmerged worktree diffs; commit+merge happen only through explicit `feature.ready_to_merge`.
-9) Restart recovery uses lease heartbeats and stale-lease reclamation with deterministic unblock flow.
-10) Secret handling is default-on scrub/redaction with explicit env allowlist.
-11) Orchestrator implementation uses Nx + Vitest with 90% line/branch minimum coverage and 100% line/branch target.
-12) Agent provider/model selection precedence is CLI flags > env vars > `agents.yaml` runtime defaults.
+1. Lock operations are owned by `orchestrator|system`; worker roles submit `REQUEST`.
+2. Lock acquisition defaults to blocking/queued with timeout + jittered backoff.
+3. Plan revisions keep existing diffs in worktree; future patch applies are validated against latest accepted plan.
+4. Supervisor proposes state transitions, MCP validates legality and persists canonical state.
+5. `collision_policy=block` uses persistent `blocked_queue` with deterministic ordering.
+6. Precedence is `policy hard constraints > gates profile defaults > plan overrides (tighten-only)`.
+7. Gate timeout default is 600s when unspecified; transient retry default is 1; policy/schema violations are non-retryable.
+8. Review artifacts are unmerged worktree diffs; commit+merge happen only through explicit `feature.ready_to_merge`.
+9. Restart recovery uses lease heartbeats and stale-lease reclamation with deterministic unblock flow.
+10. Secret handling is default-on scrub/redaction with explicit env allowlist.
+11. Orchestrator implementation uses Nx + Vitest with 90% line/branch minimum coverage and 100% line/branch target.
+12. Agent provider/model selection precedence is CLI flags > env vars > `agents.yaml` runtime defaults.
 
 ---
 
@@ -962,6 +1040,7 @@ aop run [options]
 ```
 
 Required behavior:
+
 - Starts/attaches MCP connectivity.
 - Creates one user-facing Orchestrator session.
 - Resolves input specs (from `-fi`, `-fl`, or default discovery).
@@ -970,6 +1049,7 @@ Required behavior:
 ### 17.2 Input Selection Options
 
 Supported options:
+
 - `-fi <path>`: file input. Treat the referenced file as one feature spec and spin up exactly one Agent Cluster.
 - `-fl <path>`: folder input. Treat all spec files in the folder as feature inputs and spin up one Agent Cluster per resolved file.
 - `--agent-provider <codex|claude|gemini|custom>`: selects agent runtime provider for orchestrator and worker sessions.
@@ -977,6 +1057,7 @@ Supported options:
 - `--provider-config-env <ENV_VAR>`: env var name carrying provider credentials/config reference.
 
 Mutual exclusion and defaults:
+
 - `-fi` and `-fl` are mutually exclusive.
 - If both are provided, CLI MUST fail with `error=invalid_cli_args`.
 - If neither is provided, use canonical discovery (`feature.discover_specs`).
@@ -997,21 +1078,26 @@ aop run -fl ./specfiles
 ### 17.4 Spec Ingestion to Canonical Repo Layout
 
 For inputs outside `agentic/features/*/spec.md`, Supervisor MUST ingest them into canonical layout:
+
 - Derive `feature_id` deterministically from spec filename using this algorithm:
+
 1. Start from filename stem (basename without final extension).
 2. If the stem ends with `.spec`, remove that suffix.
 3. Else if the stem ends with `-spec`, remove that suffix.
 4. Resulting value is `feature_id` and MUST be used as both branch name and worktree folder name.
 5. Resulting `feature_id` MUST match `^[a-z0-9_][a-z0-9_-]*$`.
+
 - Copy source content to `agentic/features/<feature_id>/spec.md`.
 - Record source path and source hash in feature state metadata.
 - If derived `feature_id` is empty or does not meet naming rules, fail with `error=invalid_feature_slug`.
 - If multiple inputs resolve to the same `feature_id`, fail with `error=feature_slug_collision`.
 
 If input path is already canonical (`agentic/features/<feature_id>/spec.md`):
+
 - Use existing `feature_id` from path and do not duplicate content.
 
 Examples:
+
 - `my_feature.spec.md` -> `feature_id=my_feature`, branch `my_feature`, worktree `.worktrees/my_feature`
 - `my_feature-spec.md` -> `feature_id=my_feature`, branch `my_feature`, worktree `.worktrees/my_feature`
 - `my_feature.md` -> `feature_id=my_feature`, branch `my_feature`, worktree `.worktrees/my_feature`
@@ -1032,20 +1118,23 @@ Examples:
 ### 17.7 Agent Provider Selection Contract
 
 Provider selection precedence (highest to lowest):
-1) CLI flags: `--agent-provider`, `--agent-model`, `--provider-config-env`
-2) Environment variables:
+
+1. CLI flags: `--agent-provider`, `--agent-model`, `--provider-config-env`
+2. Environment variables:
    - `AOP_AGENT_PROVIDER`
    - `AOP_AGENT_MODEL`
    - `AOP_PROVIDER_CONFIG_ENV`
-3) `agentic/orchestrator/agents.yaml` `runtime.*` defaults
+3. `agentic/orchestrator/agents.yaml` `runtime.*` defaults
 
 Rules:
+
 - If no provider can be resolved, CLI MUST fail with `error=agent_provider_not_configured`.
 - If provider value is unsupported, CLI MUST fail with `error=unsupported_agent_provider`.
 - If provider requires credentials/config and none is available, CLI MUST fail with `error=provider_auth_missing`.
 - Supervisor MUST record resolved provider/model in run metadata for auditability.
 
 Recommended additional commands (V1.1):
+
 - `aop status` (reads dashboard/status)
 - `aop resume` (resume prior run state)
 - `aop stop` (graceful shutdown)
@@ -1214,12 +1303,12 @@ Recommended additional commands (V1.1):
     "worktree_path": { "type": "string" },
     "status": {
       "type": "string",
-      "enum": ["planning","building","qa","blocked","ready_to_merge","merged","failed"]
+      "enum": ["planning", "building", "qa", "blocked", "ready_to_merge", "merged", "failed"]
     },
     "gate_profile": { "type": "string" },
     "gates": {
       "type": "object",
-      "additionalProperties": { "type": "string", "enum": ["pass","fail","na"] }
+      "additionalProperties": { "type": "string", "enum": ["pass", "fail", "na"] }
     },
     "locks": {
       "type": "object",
@@ -1230,7 +1319,7 @@ Recommended additional commands (V1.1):
     },
     "collisions": {
       "type": "object",
-      "required": ["files","areas","contracts"],
+      "required": ["files", "areas", "contracts"],
       "properties": {
         "files": { "type": "array", "items": { "type": "object" } },
         "areas": { "type": "array", "items": { "type": "object" } },
@@ -1239,7 +1328,12 @@ Recommended additional commands (V1.1):
     },
     "cluster": {
       "type": "object",
-      "required": ["orchestrator_session_id","planner_session_id","builder_session_id","qa_session_id"],
+      "required": [
+        "orchestrator_session_id",
+        "planner_session_id",
+        "builder_session_id",
+        "qa_session_id"
+      ],
       "properties": {
         "orchestrator_session_id": { "type": "string" },
         "planner_session_id": { "type": "string" },
@@ -1249,11 +1343,11 @@ Recommended additional commands (V1.1):
     },
     "role_status": {
       "type": "object",
-      "required": ["planner","builder","qa"],
+      "required": ["planner", "builder", "qa"],
       "properties": {
-        "planner": { "type": "string", "enum": ["ready","running","blocked","done"] },
-        "builder": { "type": "string", "enum": ["ready","running","blocked","done"] },
-        "qa": { "type": "string", "enum": ["ready","running","blocked","done"] }
+        "planner": { "type": "string", "enum": ["ready", "running", "blocked", "done"] },
+        "builder": { "type": "string", "enum": ["ready", "running", "blocked", "done"] },
+        "qa": { "type": "string", "enum": ["ready", "running", "blocked", "done"] }
       }
     },
     "last_updated": { "type": "string" },
@@ -1296,6 +1390,7 @@ All MCP tool failures must return:
 ```
 
 Required error codes (minimum set):
+
 - `forbidden_tool_for_role`
 - `version_conflict`
 - `invalid_status_transition`
@@ -1328,6 +1423,7 @@ Required error codes (minimum set):
 - `provider_auth_missing`
 
 Error details SHOULD include:
+
 - `retryable` boolean
 - `requires_human` boolean
 - `conflicting_feature_ids` (when relevant)