agentic-orchestrator 0.1.6 → 0.1.8

package/spec-files/outstanding/agentic_orchestrator_performance_improvements_spec.md

@@ -38,20 +38,20 @@ All new and modified code MUST follow the testing standards already established
 
 The following issues were identified in the v1.0 spec during architect review against the actual codebase. Each issue is assigned a severity and cross-references the task where it is resolved.
 
-| # | Severity | Issue | Resolution |
-|---|----------|-------|------------|
-| A-1 | **CRITICAL** | **`latest.json` does not exist.** Finding I-5 and PER-T-005/006 claim `gates.ts:430` writes a `latest.json` sentinel. The actual code at line 429–430 writes `latest-${mode}.json` (e.g., `latest-fast.json`). PER-T-005's fix of reading `path.join(evidenceDir, 'latest.json')` would always return null, silently breaking `featureGetContext` for all agent roles. PER-T-006's pruning filter `f !== 'latest.json'` would delete all mode-specific sentinels. | PER-T-005 now writes a canonical `latest.json` in `gates.ts` alongside the per-mode sentinel; PER-T-006 pruning filter excludes `latest-*.json` patterns. |
-| A-2 | **CRITICAL** | **PER-T-003 is a write-ordering behavioral change.** The v1.0 fix eliminates the sequential `for` loop (lines 41–52) and moves `workerDecisionRunner.execute()` into the parallel `executing` map. `workerDecisionRunner.execute()` for the builder role can call PATCH_APPLY, LOCK_ACQUIRE, and PLAN_UPDATE — all writes to shared state. Making these concurrent violates §0.2. | PER-T-003 is redesigned as a **context-capture Map pattern**: the sequential loop is preserved; context is stored in a Map and reused by the parallel executing map, eliminating the duplicate fetch without changing write ordering. |
-| A-3 | **CRITICAL** | **PER-T-003 reused pre-decision context for repair loop.** After `workerDecisionRunner.execute()` applies patches (changing working-tree state) and potentially acquires or releases locks (mutating `state.md`), the captured pre-decision context is stale. The repair loop needs fresh state to give agents accurate `locks.held` data. | PER-T-003 redesign fetches repair context as a fresh call after gate failure, which is the minimal re-fetch (one call per failure, not one per retry). |
-| A-4 | **HIGH** | **Coverage thresholds wrong.** §0.1 specified Lines ≥70%, Branches ≥70%, Functions ≥85%. CLAUDE.md mandates 90% on all metrics. Implementing to v1.0 thresholds would pass spec-level gates but fail CI. | §0.1 corrected to 90% everywhere. |
-| A-5 | **HIGH** | **`normalizeSet` extraction incomplete.** PER-T-013 identified 4 files but the codebase has 7 copies: `reporting-service.ts`, `merge-service.ts`, `feature-lifecycle-service.ts`, `feature-deletion-service.ts`, `kernel.ts`, `lock-service.ts`, `plan-service.ts`. Leaving 3 copies behind is worse than a partial refactor because it creates a false sense of completeness. | PER-T-013 scope expanded to all 7 files. |
-| A-6 | **HIGH** | **§0.2 constraint conflict with PER-T-008.** §0.2 stated "Input/output schemas for all 33 MCP tools remain unchanged." PER-T-008 adds an optional `role` parameter to `feature.get_context`. These directly contradict each other; §4 item 6 tried to paper over this by calling it "backward-compatible." | §0.2 amended to "no breaking changes" with explicit allowance for backward-compatible optional input additions. |
-| A-7 | **HIGH** | **Output schema implicit shape change in PER-T-008.** When `role=builder`, `qa_test_index` in the response payload becomes `{summary}` instead of the full object. The tool's output JSON schema doesn't account for this. Validators would fail at runtime when trying to validate the projected payload against the existing schema. | PER-T-008 adds a note that the existing output schema validates the `full` projection only; partial projections bypass output schema validation and return raw AOP objects. |
-| A-8 | **MEDIUM** | **`QaIndexRecord` type undefined.** PER-T-009 uses `QaIndexRecord` as a type in `projectQaIndex` but this type does not exist in the codebase. No import path is given. | PER-T-009 defines a local `QaIndexSnapshot` interface inline and derives the projection from `AnyRecord`. |
-| A-9 | **MEDIUM** | **Projection table vs implementation inconsistency.** PER-T-008 table shows QA role gets `summary + failed + pending` from `qa_test_index`, but PER-T-009 code returns `{ passed: _omitted, ...rest }` — all fields except `passed`, including `running`, `flaky`, etc. The table and code must agree. | PER-T-009 implementation updated to return only `{ summary, failed, pending }` for QA role, matching the table. |
-| A-10 | **MEDIUM** | **`schema_version` guard requires manual discipline.** PER-T-011 relies on developers remembering to bump `CURRENT_INDEX_SCHEMA_VERSION` when `normalizeIndexShape` changes shape. If forgotten, stale indices never migrate and the performance optimization yields incorrect behavior. | PER-T-011 adds a mandatory developer protocol note with a co-located integration test that detects shape drift. |
-| A-11 | **MEDIUM** | **PER-T-007 leaves planning context fetches sequential.** After pre-filtering with `FEATURE_STATE_GET`, the full context fetches for `planningFeatureIds` remain sequential in a `for` loop. Parallelizing these fetches extends the savings from PER-T-001's parallel-reads principle. | PER-T-007 updated to use `Promise.all` for the planning context fetches; `runPostQaReconciliation` pre-filter is fully specified with concrete code. |
-| A-12 | **LOW** | **`gate-service.spec.ts` does not exist.** PER-T-005 says "add cases to `gate-service.spec.ts` (create if not existing)" — should be explicit. | PER-T-005 updated to say "create `gate-service.spec.ts`." |
+| #    | Severity     | Issue                                                                                                                                                                                                                                                                                                                                                                                                                                                             | Resolution                                                                                                                                                                                                                            |
+| ---- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| A-1  | **CRITICAL** | **`latest.json` does not exist.** Finding I-5 and PER-T-005/006 claim `gates.ts:430` writes a `latest.json` sentinel. The actual code at line 429–430 writes `latest-${mode}.json` (e.g., `latest-fast.json`). PER-T-005's fix of reading `path.join(evidenceDir, 'latest.json')` would always return null, silently breaking `featureGetContext` for all agent roles. PER-T-006's pruning filter `f !== 'latest.json'` would delete all mode-specific sentinels. | PER-T-005 now writes a canonical `latest.json` in `gates.ts` alongside the per-mode sentinel; PER-T-006 pruning filter excludes `latest-*.json` patterns.                                                                             |
+| A-2  | **CRITICAL** | **PER-T-003 is a write-ordering behavioral change.** The v1.0 fix eliminates the sequential `for` loop (lines 41–52) and moves `workerDecisionRunner.execute()` into the parallel `executing` map. `workerDecisionRunner.execute()` for the builder role can call PATCH_APPLY, LOCK_ACQUIRE, and PLAN_UPDATE — all writes to shared state. Making these concurrent violates §0.2.                                                                                 | PER-T-003 is redesigned as a **context-capture Map pattern**: the sequential loop is preserved; context is stored in a Map and reused by the parallel executing map, eliminating the duplicate fetch without changing write ordering. |
+| A-3  | **CRITICAL** | **PER-T-003 reused pre-decision context for repair loop.** After `workerDecisionRunner.execute()` applies patches (changing working-tree state) and potentially acquires or releases locks (mutating `state.md`), the captured pre-decision context is stale. The repair loop needs fresh state to give agents accurate `locks.held` data.                                                                                                                        | PER-T-003 redesign fetches repair context as a fresh call after gate failure, which is the minimal re-fetch (one call per failure, not one per retry).                                                                                |
+| A-4  | **HIGH**     | **Coverage thresholds wrong.** §0.1 specified Lines ≥70%, Branches ≥70%, Functions ≥85%. CLAUDE.md mandates 90% on all metrics. Implementing to v1.0 thresholds would pass spec-level gates but fail CI.                                                                                                                                                                                                                                                          | §0.1 corrected to 90% everywhere.                                                                                                                                                                                                     |
+| A-5  | **HIGH**     | **`normalizeSet` extraction incomplete.** PER-T-013 identified 4 files but the codebase has 7 copies: `reporting-service.ts`, `merge-service.ts`, `feature-lifecycle-service.ts`, `feature-deletion-service.ts`, `kernel.ts`, `lock-service.ts`, `plan-service.ts`. Leaving 3 copies behind is worse than a partial refactor because it creates a false sense of completeness.                                                                                    | PER-T-013 scope expanded to all 7 files.                                                                                                                                                                                              |
+| A-6  | **HIGH**     | **§0.2 constraint conflict with PER-T-008.** §0.2 stated "Input/output schemas for all 33 MCP tools remain unchanged." PER-T-008 adds an optional `role` parameter to `feature.get_context`. These directly contradict each other; §4 item 6 tried to paper over this by calling it "backward-compatible."                                                                                                                                                        | §0.2 amended to "no breaking changes" with explicit allowance for backward-compatible optional input additions.                                                                                                                       |
+| A-7  | **HIGH**     | **Output schema implicit shape change in PER-T-008.** When `role=builder`, `qa_test_index` in the response payload becomes `{summary}` instead of the full object. The tool's output JSON schema doesn't account for this. Validators would fail at runtime when trying to validate the projected payload against the existing schema.                                                                                                                            | PER-T-008 adds a note that the existing output schema validates the `full` projection only; partial projections bypass output schema validation and return raw AOP objects.                                                           |
+| A-8  | **MEDIUM**   | **`QaIndexRecord` type undefined.** PER-T-009 uses `QaIndexRecord` as a type in `projectQaIndex` but this type does not exist in the codebase. No import path is given.                                                                                                                                                                                                                                                                                           | PER-T-009 defines a local `QaIndexSnapshot` interface inline and derives the projection from `AnyRecord`.                                                                                                                             |
+| A-9  | **MEDIUM**   | **Projection table vs implementation inconsistency.** PER-T-008 table shows QA role gets `summary + failed + pending` from `qa_test_index`, but PER-T-009 code returns `{ passed: _omitted, ...rest }` — all fields except `passed`, including `running`, `flaky`, etc. The table and code must agree.                                                                                                                                                            | PER-T-009 implementation updated to return only `{ summary, failed, pending }` for QA role, matching the table.                                                                                                                       |
+| A-10 | **MEDIUM**   | **`schema_version` guard requires manual discipline.** PER-T-011 relies on developers remembering to bump `CURRENT_INDEX_SCHEMA_VERSION` when `normalizeIndexShape` changes shape. If forgotten, stale indices never migrate and the performance optimization yields incorrect behavior.                                                                                                                                                                          | PER-T-011 adds a mandatory developer protocol note with a co-located integration test that detects shape drift.                                                                                                                       |
+| A-11 | **MEDIUM**   | **PER-T-007 leaves planning context fetches sequential.** After pre-filtering with `FEATURE_STATE_GET`, the full context fetches for `planningFeatureIds` remain sequential in a `for` loop. Parallelizing these fetches extends the savings from PER-T-001's parallel-reads principle.                                                                                                                                                                           | PER-T-007 updated to use `Promise.all` for the planning context fetches; `runPostQaReconciliation` pre-filter is fully specified with concrete code.                                                                                  |
+| A-12 | **LOW**      | **`gate-service.spec.ts` does not exist.** PER-T-005 says "add cases to `gate-service.spec.ts` (create if not existing)" — should be explicit.                                                                                                                                                                                                                                                                                                                    | PER-T-005 updated to say "create `gate-service.spec.ts`."                                                                                                                                                                             |
 
 ---
 
@@ -143,6 +143,7 @@ The dashboard loop reads `state.md` and the cost JSON file for each feature one
 On every `featureGetContext` call, `evidenceLatest` lists the entire evidence directory, calls `fs.stat()` on every `.json` file to read mtimes, sorts by mtime, then reads the newest file.
 
 `gates.ts:429–430` already writes a per-mode sentinel file on every gate run:
+
 ```typescript
 const latestPath = path.join(evidenceDirectory, `latest-${mode}.json`);
 await fs.writeFile(latestPath, `${JSON.stringify(evidence, null, 2)}\n`, 'utf8');
@@ -228,12 +229,12 @@ Every gate run appends a new timestamped JSON file to `.aop/features/<id>/eviden
 
 The context bundle returned to every agent role includes the complete QA test index (all test records, including passed), the full gate evidence JSON (verbose stdout/stderr), and the complete state frontmatter (all historical lock, gate, and PR metadata). A feature with 200 tests and 50 gate retry cycles produces a bundle exceeding 80–100 KB — roughly 20,000–25,000 tokens per agent invocation.
 
-| Field | Problem |
-|-------|---------|
-| `qa_test_index` | All test records including passed — agents only need `summary` + `failed` + `pending` |
-| `latest_evidence` | Full verbose gate output — agents need overall result + top failing steps |
-| `state.front_matter` | All historical locks/gates/PR metadata — agents need current status + held locks |
-| `plan` | Full plan when builder/QA roles only need current-phase tasks |
+| Field                | Problem                                                                               |
+| -------------------- | ------------------------------------------------------------------------------------- |
+| `qa_test_index`      | All test records including passed — agents only need `summary` + `failed` + `pending` |
+| `latest_evidence`    | Full verbose gate output — agents need overall result + top failing steps             |
+| `state.front_matter` | All historical locks/gates/PR metadata — agents need current status + held locks      |
+| `plan`               | Full plan when builder/QA roles only need current-phase tasks                         |
 
 ---
 
@@ -263,24 +264,24 @@ See Finding I-8. The structural fix (hoist above the loop) also ensures prompts
 
 ### 2.4 Complete Findings Table
 
-| ID | File | Lines | Severity | Category | Task |
-|----|------|-------|----------|----------|------|
-| I-1 | `feature-lifecycle-service.ts` | 142–146 | HIGH | I/O | PER-T-001 |
-| I-2 | `build-wave-executor.ts` | 42, 95 | HIGH | I/O | PER-T-003 |
-| I-3 | `build-wave-executor.ts`, `qa-wave-executor.ts` | 30–38, 54–62 | HIGH | I/O | PER-T-002 |
-| I-4 | `reporting-service.ts` | 81–108 | MEDIUM | I/O | PER-T-004 |
-| I-5 | `gate-service.ts` | 236–256 | MEDIUM | I/O | PER-T-005 |
-| I-6 | `kernel.ts` | 758 | MEDIUM | CPU | PER-T-011 |
-| I-7 | `reporting-service.ts` | 40–68 | MEDIUM | CPU/I/O | Deferred |
-| I-8 | `qa-wave-executor.ts` | 196 | LOW | I/O | PER-T-014 |
-| M-1 | 7 service/core files | various | LOW | Memory | PER-T-013 |
-| M-2 | `planning-wave-executor.ts` | 298 | LOW | Memory | PER-T-012 |
-| M-3 | `run-coordinator.ts` | 61–62, 272 | MEDIUM | Memory | PER-T-010 |
-| M-4 | `core/gates.ts` | 427–430 | HIGH | Disk | PER-T-006 |
-| C-1 | `feature-lifecycle-service.ts` | 132–158 | HIGH | Context | PER-T-008, PER-T-009 |
-| C-2 | `planning-wave-executor.ts` | 125–133 | MEDIUM | Context | PER-T-007 |
-| C-3 | `planning-wave-executor.ts` | 313 | LOW | Context | Deferred |
-| C-4 | `qa-wave-executor.ts`, `prompt-bundle-loader.ts` | 196, 15–52 | LOW | Context | PER-T-014 |
+| ID  | File                                             | Lines        | Severity | Category | Task                 |
+| --- | ------------------------------------------------ | ------------ | -------- | -------- | -------------------- |
+| I-1 | `feature-lifecycle-service.ts`                   | 142–146      | HIGH     | I/O      | PER-T-001            |
+| I-2 | `build-wave-executor.ts`                         | 42, 95       | HIGH     | I/O      | PER-T-003            |
+| I-3 | `build-wave-executor.ts`, `qa-wave-executor.ts`  | 30–38, 54–62 | HIGH     | I/O      | PER-T-002            |
+| I-4 | `reporting-service.ts`                           | 81–108       | MEDIUM   | I/O      | PER-T-004            |
+| I-5 | `gate-service.ts`                                | 236–256      | MEDIUM   | I/O      | PER-T-005            |
+| I-6 | `kernel.ts`                                      | 758          | MEDIUM   | CPU      | PER-T-011            |
+| I-7 | `reporting-service.ts`                           | 40–68        | MEDIUM   | CPU/I/O  | Deferred             |
+| I-8 | `qa-wave-executor.ts`                            | 196          | LOW      | I/O      | PER-T-014            |
+| M-1 | 7 service/core files                             | various      | LOW      | Memory   | PER-T-013            |
+| M-2 | `planning-wave-executor.ts`                      | 298          | LOW      | Memory   | PER-T-012            |
+| M-3 | `run-coordinator.ts`                             | 61–62, 272   | MEDIUM   | Memory   | PER-T-010            |
+| M-4 | `core/gates.ts`                                  | 427–430      | HIGH     | Disk     | PER-T-006            |
+| C-1 | `feature-lifecycle-service.ts`                   | 132–158      | HIGH     | Context  | PER-T-008, PER-T-009 |
+| C-2 | `planning-wave-executor.ts`                      | 125–133      | MEDIUM   | Context  | PER-T-007            |
+| C-3 | `planning-wave-executor.ts`                      | 313          | LOW      | Context  | Deferred             |
+| C-4 | `qa-wave-executor.ts`, `prompt-bundle-loader.ts` | 196, 15–52   | LOW      | Context  | PER-T-014            |
 
 ---
 
@@ -299,29 +300,33 @@ See Finding I-8. The structural fix (hoist above the loop) also ensures prompts
 **Lines:** 142–146
 
 **Before:**
+
 ```typescript
-const state    = await this.port.featureStateGet(featureId);
-const plan     = await this.port.planGet(featureId);
-const qaIndex  = await this.port.qaTestIndexGet(featureId);
+const state = await this.port.featureStateGet(featureId);
+const plan = await this.port.planGet(featureId);
+const qaIndex = await this.port.qaTestIndexGet(featureId);
 const evidence = await this.port.evidenceLatest(featureId);
 const specText = await fs.readFile(this.port.specPath(featureId), 'utf8').catch(() => '');
 ```
 
 **After:**
+
 ```typescript
 const [state, plan, qaIndex, evidence, specText] = await Promise.all([
   this.port.featureStateGet(featureId),
   this.port.planGet(featureId),
   this.port.qaTestIndexGet(featureId),
   this.port.evidenceLatest(featureId),
-  fs.readFile(this.port.specPath(featureId), 'utf8').catch(() => '')
+  fs.readFile(this.port.specPath(featureId), 'utf8').catch(() => ''),
 ]);
 ```
 
 **Tests to write:** `apps/control-plane/test/feature-lifecycle-service.spec.ts`
+
 - `GIVEN_featureGetContext_WHEN_called_THEN_all_reads_are_parallel` — assert each port method is called exactly once and all are called before any result is consumed.
 
 **Acceptance criteria:**
+
 1. `featureGetContext` returns identical output before and after.
 2. All five port method spies are called; the individual calls are non-ordered.
 3. A single I/O error in any one read propagates as a rejected promise (existing behavior).
@@ -332,16 +337,22 @@ const [state, plan, qaIndex, evidence, specText] = await Promise.all([
 
 **Fixes:** Finding I-3
 **Files:**
+
 - `apps/control-plane/src/supervisor/build-wave-executor.ts` (lines 30–38)
 - `apps/control-plane/src/supervisor/qa-wave-executor.ts` (lines 54–62)
 
 **Before (BuildWaveExecutor):**
+
 ```typescript
 const batch: string[] = [];
 for (const featureId of featureIds) {
-  const state = await this.toolCaller.callTool<FeatureStatePayload>('builder', TOOLS.FEATURE_STATE_GET, {
-    feature_id: featureId
-  });
+  const state = await this.toolCaller.callTool<FeatureStatePayload>(
+    'builder',
+    TOOLS.FEATURE_STATE_GET,
+    {
+      feature_id: featureId,
+    },
+  );
   if (state.data.front_matter.status === STATUS.BUILDING) {
     batch.push(featureId);
   }
@@ -349,13 +360,14 @@ for (const featureId of featureIds) {
 ```
 
 **After (BuildWaveExecutor):**
+
 ```typescript
 const states = await Promise.all(
   featureIds.map((featureId) =>
     this.toolCaller.callTool<FeatureStatePayload>('builder', TOOLS.FEATURE_STATE_GET, {
-      feature_id: featureId
-    })
-  )
+      feature_id: featureId,
+    }),
+  ),
 );
 const batch = featureIds.filter((_, i) => states[i].data.front_matter.status === STATUS.BUILDING);
 ```
@@ -363,10 +375,12 @@ const batch = featureIds.filter((_, i) => states[i].data.front_matter.status ===
 Apply the same transformation to `QaWaveExecutor` substituting role `'qa'` and status `STATUS.QA`.
 
 **Tests to write:** `apps/control-plane/test/batch-operations.spec.ts` (existing — add cases)
+
 - `GIVEN_BuildWaveExecutor_run_WHEN_multiple_features_THEN_state_reads_are_parallel`
 - `GIVEN_QaWaveExecutor_run_WHEN_multiple_features_THEN_state_reads_are_parallel`
 
 **Acceptance criteria:**
+
 1. Identical `batch` array produced before and after (same filter logic, same contents).
 2. All `FEATURE_STATE_GET` calls are issued concurrently (spy call ordering is non-sequential).
 3. `selected` slice behavior (`batch.slice(0, maxParallelGateRuns)`) is unchanged.
@@ -382,6 +396,7 @@ Apply the same transformation to `QaWaveExecutor` substituting role `'qa'` and s
 **Design rationale:** The sequential `for` loop at lines 41–52 MUST remain sequential (§0.2) because `workerDecisionRunner.execute()` can call write-producing tools (PATCH_APPLY, LOCK_ACQUIRE). The duplicate fetch at line 95 is eliminated by capturing each feature's context in a Map during the sequential phase, then looking it up in the parallel phase for the repair loop. The repair-loop context is still re-fetched once per feature on gate failure (not once per retry as it was before) to capture any state changes from the initial decision. This reduces the duplicate from O(retries) to O(1) on the failure path.
 
 **Before:**
+
 ```typescript
 // Sequential loop (lines 41–52): initial worker decision
 for (const featureId of selected) {
@@ -409,27 +424,32 @@ const executing = selected.map(async (featureId) => {
 ```
 
 **After:**
+
 ```typescript
 // Phase 1: Sequential — initial worker decisions (write ordering preserved)
 const preDecisionContextByFeature = new Map<string, unknown>();
 for (const featureId of selected) {
   const context = await this.toolCaller.callTool('builder', TOOLS.FEATURE_GET_CONTEXT, {
-    feature_id: featureId
+    feature_id: featureId,
   });
   preDecisionContextByFeature.set(featureId, context.data);
   await this.workerDecisionRunner.execute({
     role: 'builder',
     featureId,
     contextBundle: context.data,
-    instructions: '...'
+    instructions: '...',
   });
 }
 
 // Phase 2: Parallel — gate runs and repair
 const executing = selected.map(async (featureId) => {
-  const stateForRetry = await this.toolCaller.callTool<FeatureStatePayload>('builder', TOOLS.FEATURE_STATE_GET, {
-    feature_id: featureId
-  });
+  const stateForRetry = await this.toolCaller.callTool<FeatureStatePayload>(
+    'builder',
+    TOOLS.FEATURE_STATE_GET,
+    {
+      feature_id: featureId,
+    },
+  );
   const initialRetryCount = stateForRetry.data.front_matter.gate_retry_count ?? 0;
 
   // ... gate run (unchanged) ...
@@ -440,7 +460,7 @@ const executing = selected.map(async (featureId) => {
     // This is one fetch per failing feature — eliminates the per-retry fetch
     // that occurred in the v1.0 repair loop.
     const repairContext = await this.toolCaller.callTool('builder', TOOLS.FEATURE_GET_CONTEXT, {
-      feature_id: featureId
+      feature_id: featureId,
     });
     let retryCount = initialRetryCount;
     while (this.reactionsService.shouldRetry(featureId, retryCount)) {
@@ -449,7 +469,7 @@ const executing = selected.map(async (featureId) => {
         role: 'builder',
         featureId,
         contextBundle: repairContext.data,
-        instructions: repairPrompt
+        instructions: repairPrompt,
       });
       // ... gate re-run, retryCount increment ...
     }
@@ -461,11 +481,13 @@ await Promise.allSettled(executing);
 **Rationale for still re-fetching on gate failure:** After `workerDecisionRunner.execute()` in Phase 1, the feature may have acquired locks or had patches applied, mutating `state.md`. The repair loop needs `locks.held` to be accurate to avoid incorrect lock-conflict decisions. The re-fetch is gated on `gateOverall === GATE_RESULT.FAIL` — on the fast-path (gate passes), no additional context fetch occurs at all.
 
 **Tests to write:** `apps/control-plane/test/batch-operations.spec.ts`
+
 - `GIVEN_BuildWaveExecutor_gate_passes_WHEN_run_THEN_FEATURE_GET_CONTEXT_called_exactly_once_per_feature`
 - `GIVEN_BuildWaveExecutor_gate_fails_WHEN_run_THEN_FEATURE_GET_CONTEXT_called_twice_per_failing_feature`
 - `GIVEN_BuildWaveExecutor_multiple_retries_WHEN_gate_fails_THEN_repair_context_not_re_fetched_per_retry`
 
 **Acceptance criteria:**
+
 1. When gate passes, `FEATURE_GET_CONTEXT` is called exactly once per feature per `run()` invocation.
 2. When gate fails, `FEATURE_GET_CONTEXT` is called exactly twice per failing feature: once in Phase 1 (pre-decision), once in Phase 2 (repair context) — never per retry.
 3. Sequential write ordering of `workerDecisionRunner.execute()` across features is preserved.
@@ -480,6 +502,7 @@ await Promise.allSettled(executing);
 **Lines:** 81–108
 
 **Before:**
+
 ```typescript
 const features = [];
 for (const featureId of featureIds) {
@@ -494,6 +517,7 @@ for (const featureId of featureIds) {
 ```
 
 **After:**
+
 ```typescript
 const features = (
   await Promise.all(
@@ -504,16 +528,20 @@ const features = (
       }
       const [state, costData] = await Promise.all([
         this.port.readState(featureId),
-        readJson<{ estimated_cost_usd: number; tokens_used: number }>(this.port.featureCostPath(featureId), null)
+        readJson<{ estimated_cost_usd: number; tokens_used: number }>(
+          this.port.featureCostPath(featureId),
+          null,
+        ),
       ]);
       return {
         feature_id: featureId,
         status: state.frontMatter.status,
-        branch: typeof state.frontMatter.worktree_branch === 'string'
-          ? state.frontMatter.worktree_branch
-          : typeof state.frontMatter.branch === 'string'
-            ? state.frontMatter.branch
-            : null,
+        branch:
+          typeof state.frontMatter.worktree_branch === 'string'
+            ? state.frontMatter.worktree_branch
+            : typeof state.frontMatter.branch === 'string'
+              ? state.frontMatter.branch
+              : null,
         locks: readHeldLocks(state.frontMatter),
         gate_profile: state.frontMatter.gate_profile,
         gates: state.frontMatter.gates,
@@ -524,18 +552,20 @@ const features = (
         activity_detected_via: state.frontMatter.activity_detected_via,
         cost: costData
           ? { estimated_cost_usd: costData.estimated_cost_usd, tokens_used: costData.tokens_used }
-          : null
+          : null,
       };
-    })
+    }),
   )
 ).filter((entry): entry is NonNullable<typeof entry> => entry !== null);
 ```
 
 **Tests to write:** `apps/control-plane/test/services.spec.ts` (existing) — add cases:
+
 - `GIVEN_reportDashboard_WHEN_multiple_features_exist_THEN_reads_are_parallel`
 - `GIVEN_reportDashboard_WHEN_state_file_missing_THEN_feature_is_omitted`
 
 **Acceptance criteria:**
+
 1. Returned `features` array contains identical entries in the same order as before.
 2. Features without a state file are omitted from output (unchanged behavior).
 3. `readState` and `readJson` (cost) are called in parallel per feature.
@@ -552,10 +582,12 @@ const features = (
 
 **Fixes:** Finding I-5
 **Files:**
+
 - `apps/control-plane/src/core/gates.ts` (add canonical sentinel write)
 - `apps/control-plane/src/application/services/gate-service.ts` (read sentinel directly)
 
 **Context:** `gates.ts:427–430` currently writes two files per gate run:
+
 - `gate-${mode}-${Date.now()}.json` — the timestamped archive record
 - `latest-${mode}.json` — a per-mode sentinel (e.g., `latest-fast.json`, `latest-full.json`)
 
@@ -564,6 +596,7 @@ const features = (
 **Fix:** Add a third write in `gates.ts` — a canonical `latest.json` — updated after every gate run regardless of mode. This is the single O(1) read target for `evidenceLatest`.
 
 **Change to `gates.ts`** (after line 430):
+
 ```typescript
 // Existing:
 const evidencePath = path.join(evidenceDirectory, `gate-${mode}-${Date.now()}.json`);
@@ -577,6 +610,7 @@ await fs.writeFile(latestPath, `${JSON.stringify(evidence, null, 2)}\n`, 'utf8')
 ```
 
 **Change to `gate-service.ts` `evidenceLatest`** — replace O(N) scan:
+
 ```typescript
 // Before (O(N) stat scan):
 const files = (await fs.readdir(evidenceDir))
@@ -594,12 +628,13 @@ return {
   data: {
     feature_id: featureId,
     latest,
-    path: normalizeRepoPathForState(repoRoot, latestPath)
-  }
+    path: normalizeRepoPathForState(repoRoot, latestPath),
+  },
 };
 ```
 
 **Tests to write:** Create `apps/control-plane/test/gate-service.spec.ts`
+
 - `GIVEN_evidenceLatest_WHEN_latest_json_exists_THEN_returns_its_contents`
 - `GIVEN_evidenceLatest_WHEN_no_evidence_dir_exists_THEN_returns_null`
 - `GIVEN_evidenceLatest_WHEN_latest_json_missing_THEN_returns_null`
@@ -607,6 +642,7 @@ return {
 - `GIVEN_gates_run_WHEN_gate_completes_THEN_latest_json_matches_per_mode_sentinel`
 
 **Acceptance criteria:**
+
 1. `evidenceLatest` reads only `latest.json`; no `readdir` or `stat` calls.
 2. Return shape `{ data: { feature_id, latest, path? } }` is identical to the existing interface.
 3. `gates.ts` writes `latest.json` after every gate run; its content equals the evidence object.
@@ -619,20 +655,23 @@ return {
 
 **Fixes:** Finding M-4
 **Files:**
+
 - `agentic/orchestrator/policy.yaml` — add `evidence_retention_count` field
 - `agentic/orchestrator/defaults/policy.defaults.yaml` — add default value
 - `agentic/orchestrator/schemas/policy.schema.json` — add field to `cleanup` object
 - `apps/control-plane/src/core/gates.ts` — prune after writing new evidence file
 
 **Policy change (`policy.yaml`):**
+
 ```yaml
 cleanup:
   grace_period_seconds: 300
   auto_after_merge: true
-  evidence_retention_count: 10   # NEW: keep the N most recent timestamped evidence files per feature
+  evidence_retention_count: 10 # NEW: keep the N most recent timestamped evidence files per feature
 ```
 
 **Schema change (`schemas/policy.schema.json`):** Add to the `cleanup` object properties:
+
 ```json
 "evidence_retention_count": {
   "type": "integer",
@@ -644,6 +683,7 @@ cleanup:
 ```
 
 **Implementation in `gates.ts`** — after writing all three evidence files, add pruning:
+
 ```typescript
 await pruneEvidenceFiles(evidenceDir, retentionCount);
 
@@ -666,12 +706,14 @@ async function pruneEvidenceFiles(dir: string, keep: number): Promise<void> {
 The `retentionCount` value is read from the policy snapshot, defaulting to `10` if absent.
 
 **Tests to write:** `apps/control-plane/test/incremental-gates.spec.ts` (existing) — add cases:
+
 - `GIVEN_pruneEvidenceFiles_WHEN_archived_count_exceeds_retention_THEN_oldest_are_deleted`
 - `GIVEN_pruneEvidenceFiles_WHEN_archived_count_within_retention_THEN_nothing_deleted`
 - `GIVEN_pruneEvidenceFiles_WHEN_latest_json_present_THEN_it_is_never_pruned`
 - `GIVEN_pruneEvidenceFiles_WHEN_latest_mode_sentinels_present_THEN_they_are_never_pruned`
 
 **Acceptance criteria:**
+
 1. After every gate run, the evidence directory contains at most `evidence_retention_count` timestamped `gate-*.json` files.
 2. `latest.json` is never deleted by pruning.
 3. `latest-${mode}.json` sentinel files (e.g., `latest-fast.json`) are never deleted by pruning.
@@ -694,6 +736,7 @@ The `retentionCount` value is read from the policy snapshot, defaulting to `10`
 **Lines:** 124–153 (`run`) and 156–228 (`runPostQaReconciliation`)
 
 **Before (`run`):**
+
 ```typescript
 async run(featureIds: string[]): Promise<void> {
   for (const featureId of featureIds) {
@@ -710,6 +753,7 @@ async run(featureIds: string[]): Promise<void> {
 ```
 
 **After (`run`):**
+
 ```typescript
 async run(featureIds: string[]): Promise<void> {
   // Phase 1: Batch-fetch lightweight state in parallel to identify planning features
@@ -745,6 +789,7 @@ async run(featureIds: string[]): Promise<void> {
 ```
 
 **Before (`runPostQaReconciliation`):**
+
 ```typescript
 async runPostQaReconciliation(featureIds: string[], iteration: number): Promise<void> {
   for (const featureId of featureIds) {
@@ -762,6 +807,7 @@ async runPostQaReconciliation(featureIds: string[], iteration: number): Promise<
 ```
 
 **After (`runPostQaReconciliation`):**
+
 ```typescript
 async runPostQaReconciliation(featureIds: string[], iteration: number): Promise<void> {
   // Phase 1: Batch-fetch state in parallel to identify post-QA features
@@ -798,6 +844,7 @@ async runPostQaReconciliation(featureIds: string[], iteration: number): Promise<
 ```
 
 **Tests to write:** `apps/control-plane/test/planning-wave-executor.spec.ts` (existing — add cases)
+
 - `GIVEN_run_WHEN_features_not_in_planning_status_THEN_FEATURE_GET_CONTEXT_not_called`
 - `GIVEN_run_WHEN_features_in_planning_THEN_FEATURE_GET_CONTEXT_called_only_for_those`
 - `GIVEN_run_WHEN_multiple_planning_features_THEN_context_fetches_are_parallel`
@@ -805,6 +852,7 @@ async runPostQaReconciliation(featureIds: string[], iteration: number): Promise<
 - `GIVEN_runPostQaReconciliation_WHEN_post_qa_features_exist_THEN_context_fetches_are_parallel`
 
 **Acceptance criteria:**
+
 1. `FEATURE_GET_CONTEXT` is never called for features not in `PLANNING` or `BLOCKED` status (in `run`).
 2. `FEATURE_GET_CONTEXT` is never called for features not in a post-QA status (in `runPostQaReconciliation`).
 3. `FEATURE_STATE_GET` batch calls are issued in parallel.
@@ -817,6 +865,7 @@ async runPostQaReconciliation(featureIds: string[], iteration: number): Promise<
 
 **Fixes:** Finding C-1
 **Files:**
+
 - `apps/control-plane/src/application/services/feature-lifecycle-service.ts`
 - `agentic/orchestrator/tools/schemas/input/feature.get_context.input.schema.json` (add optional `role` field)
 
@@ -838,14 +887,14 @@ Add an optional `role` parameter to the existing `feature.get_context` input sch
 
 **Context projections by role:**
 
-| Field | `full` | `planner` | `builder` | `qa` |
-|-------|--------|-----------|-----------|------|
-| `feature_id` | ✓ | ✓ | ✓ | ✓ |
-| `spec` | full | full | trimmed to 8 KB | trimmed to 4 KB |
-| `state.front_matter` | full | full | `{ status, branch, locks.held, gates, gate_profile }` | `{ status, branch, gates, gate_profile }` |
-| `plan` | full | full | `{ tasks (current phase only), acceptance_criteria }` | `{ acceptance_criteria, risk }` |
-| `qa_test_index` | full | `{ summary }` | `{ summary }` | `{ summary, failed, pending }` (no `passed`) |
-| `latest_evidence` | full | `{ overall, profile }` | `{ overall, profile, failed_steps[0..4] }` | `{ overall, profile, failed_steps[0..9], coverage }` |
+| Field                | `full` | `planner`              | `builder`                                             | `qa`                                                 |
+| -------------------- | ------ | ---------------------- | ----------------------------------------------------- | ---------------------------------------------------- |
+| `feature_id`         | ✓      | ✓                      | ✓                                                     | ✓                                                    |
+| `spec`               | full   | full                   | trimmed to 8 KB                                       | trimmed to 4 KB                                      |
+| `state.front_matter` | full   | full                   | `{ status, branch, locks.held, gates, gate_profile }` | `{ status, branch, gates, gate_profile }`            |
+| `plan`               | full   | full                   | `{ tasks (current phase only), acceptance_criteria }` | `{ acceptance_criteria, risk }`                      |
+| `qa_test_index`      | full   | `{ summary }`          | `{ summary }`                                         | `{ summary, failed, pending }` (no `passed`)         |
+| `latest_evidence`    | full   | `{ overall, profile }` | `{ overall, profile, failed_steps[0..4] }`            | `{ overall, profile, failed_steps[0..9], coverage }` |
 
 **Implementation in `FeatureLifecycleService`:**
 
@@ -886,15 +935,17 @@ const specBudgetByRole: Record<string, number> = {
 ```
 
 Wave executors pass their role when calling context:
+
 ```typescript
 // BuildWaveExecutor
 const context = await this.toolCaller.callTool('builder', TOOLS.FEATURE_GET_CONTEXT, {
   feature_id: featureId,
-  role: 'builder'    // NEW
+  role: 'builder', // NEW
 });
 ```
 
 **Tests to write:** `apps/control-plane/test/feature-lifecycle-service.spec.ts`
+
 - `GIVEN_featureGetContext_with_role_builder_WHEN_called_THEN_qa_index_is_summary_only`
 - `GIVEN_featureGetContext_with_role_qa_WHEN_called_THEN_passed_tests_are_omitted`
 - `GIVEN_featureGetContext_with_role_planner_WHEN_called_THEN_state_is_projected`
@@ -902,6 +953,7 @@ const context = await this.toolCaller.callTool('builder', TOOLS.FEATURE_GET_CONT
 - `GIVEN_featureGetContext_no_role_WHEN_called_THEN_bundle_is_unchanged` (backward compat)
 
 **Acceptance criteria:**
+
 1. `role: 'full'` (and omitting `role`) returns the existing complete bundle — no regression for callers that do not pass a role.
 2. `role: 'builder'` returns `{ summary }` only for `qa_test_index`; `latest_evidence` includes at most 5 `failed_steps`.
 3. `role: 'qa'` returns `{ summary, failed, pending }` for `qa_test_index` (no `passed`); `latest_evidence` includes at most 10 `failed_steps` plus `coverage`.
@@ -930,7 +982,7 @@ interface QaIndexSnapshot {
 
 export function projectQaIndex(
   qaIndex: QaIndexSnapshot,
-  role: 'full' | 'planner' | 'builder' | 'qa'
+  role: 'full' | 'planner' | 'builder' | 'qa',
 ): Partial<QaIndexSnapshot> {
   if (role === 'full') return qaIndex;
   if (role === 'planner' || role === 'builder') return { summary: qaIndex.summary };
@@ -938,13 +990,13 @@ export function projectQaIndex(
   return {
     summary: qaIndex.summary,
     failed: qaIndex.failed,
-    pending: qaIndex.pending
+    pending: qaIndex.pending,
   };
 }
 
 export function projectEvidence(
   evidence: AnyRecord | null,
-  role: 'full' | 'planner' | 'builder' | 'qa'
+  role: 'full' | 'planner' | 'builder' | 'qa',
 ): AnyRecord | null {
   if (!evidence || role === 'full') return evidence;
   if (role === 'planner') return { overall: evidence.overall, profile: evidence.profile };
@@ -956,16 +1008,20 @@ export function projectEvidence(
     overall: evidence.overall,
     profile: evidence.profile,
     failed_steps: failedSteps,
-    ...(role === 'qa' ? { coverage: evidence.coverage } : {})
+    ...(role === 'qa' ? { coverage: evidence.coverage } : {}),
   };
 }
 
-export function projectState(stateData: AnyRecord, role: 'full' | 'planner' | 'builder' | 'qa'): AnyRecord {
+export function projectState(
+  stateData: AnyRecord,
+  role: 'full' | 'planner' | 'builder' | 'qa',
+): AnyRecord {
   if (role === 'full' || role === 'planner') return stateData;
   const fm = stateData.front_matter ?? {};
-  const includedFields: (keyof typeof fm)[] = role === 'builder'
-    ? ['status', 'branch', 'worktree_branch', 'locks', 'gates', 'gate_profile']
-    : ['status', 'branch', 'worktree_branch', 'gates', 'gate_profile'];
+  const includedFields: (keyof typeof fm)[] =
+    role === 'builder'
+      ? ['status', 'branch', 'worktree_branch', 'locks', 'gates', 'gate_profile']
+      : ['status', 'branch', 'worktree_branch', 'gates', 'gate_profile'];
   const projected: AnyRecord = {};
   for (const field of includedFields) {
     if (field in fm) projected[field] = fm[field];
@@ -980,6 +1036,7 @@ export function trimSpec(spec: string, budgetBytes: number): string {
 ```
 
 **Tests to write:** `apps/control-plane/test/feature-lifecycle-service.spec.ts`
+
 - `GIVEN_projectQaIndex_role_qa_WHEN_index_has_passed_tests_THEN_passed_is_omitted`
 - `GIVEN_projectQaIndex_role_qa_WHEN_index_has_running_field_THEN_running_is_omitted`
 - `GIVEN_projectQaIndex_role_full_WHEN_called_THEN_index_is_unchanged`
@@ -1008,24 +1065,26 @@ export function trimSpec(spec: string, budgetBytes: number): string {
 When `closeFeatureCluster(featureId)` is called for a terminal-status feature, the corresponding `statusCache` entry is never deleted. Over a long run processing hundreds of features, the Map accumulates dead entries indefinitely.
 
 **Before:**
+
 ```typescript
 for (const featureId of sortedCurrent) {
   const status = await this.readFeatureStatus(featureId);
   if (status && RunCoordinator.TERMINAL_STATUSES.has(status)) {
     await this.sessionOrchestrator.closeFeatureCluster(featureId);
-    continue;  // cache entry remains
+    continue; // cache entry remains
   }
   survivingActiveFeatureIds.push(featureId);
 }
 ```
 
 **After:**
+
 ```typescript
 for (const featureId of sortedCurrent) {
   const status = await this.readFeatureStatus(featureId);
   if (status && RunCoordinator.TERMINAL_STATUSES.has(status)) {
     await this.sessionOrchestrator.closeFeatureCluster(featureId);
-    this.statusCache.delete(featureId);   // NEW: evict dead entry
+    this.statusCache.delete(featureId); // NEW: evict dead entry
     continue;
   }
   survivingActiveFeatureIds.push(featureId);
@@ -1035,10 +1094,12 @@ for (const featureId of sortedCurrent) {
 Apply the same eviction in the queue-drain loop (lines 193–207) where features popped from `this.state.queue` are found to already be terminal.
 
 **Tests to write:** `apps/control-plane/test/run-coordinator.spec.ts` (existing — add case)
+
 - `GIVEN_rebalanceActiveFeatures_WHEN_feature_reaches_terminal_status_THEN_statusCache_entry_is_evicted`
 - `GIVEN_rebalanceActiveFeatures_WHEN_queue_feature_is_terminal_THEN_statusCache_entry_is_evicted`
 
 **Acceptance criteria:**
+
 1. After `closeFeatureCluster` is called for a terminal feature, `statusCache.has(featureId)` returns `false`.
 2. `notifyStatusTransitions` is unaffected — it reads `statusCache` only for currently active features.
 3. No change to orchestration loop behavior or status transition notification logic.
@@ -1049,12 +1110,14 @@ Apply the same eviction in the queue-drain loop (lines 193–207) where features
 
 **Fixes:** Finding I-6
 **Files:**
+
 - `apps/control-plane/src/core/kernel.ts` (lines 755–763)
 - `agentic/orchestrator/schemas/index.schema.json` (add optional `schema_version` field)
 
 `readIndex` serializes the entire index (20–50 KB) twice on every call just to detect whether schema migration is needed — a cold-path concern paid on every hot-path read.
 
 **Current behavior:**
+
 ```typescript
 const changed = JSON.stringify(existing ?? null) !== JSON.stringify(normalized);
 if (changed) {
@@ -1090,12 +1153,14 @@ async readIndex(): Promise<AnyRecord> {
 **Shape-drift detection test:** Add a test that calls `normalizeIndexShape` with the current `CURRENT_INDEX_SCHEMA_VERSION` and asserts that the output's `schema_version` equals it. If a developer changes `normalizeIndexShape` without bumping the constant, the test will still pass — but if they also change what `normalizeIndexShape` produces (e.g., new field), the test ensures the constant is documented in context. Add a comment in the test: `// If this test fails, increment CURRENT_INDEX_SCHEMA_VERSION in kernel.ts`.
 
 **Tests to write:** `apps/control-plane/test/kernel.spec.ts` (existing — add cases)
+
 - `GIVEN_readIndex_WHEN_schema_version_matches_THEN_normalizeIndexShape_not_called`
 - `GIVEN_readIndex_WHEN_schema_version_absent_THEN_migration_runs_and_writes_file`
 - `GIVEN_readIndex_WHEN_index_is_null_THEN_migration_runs`
 - `GIVEN_normalizeIndexShape_WHEN_called_THEN_schema_version_equals_current_constant` (shape-drift guard)
 
 **Acceptance criteria:**
+
 1. When the on-disk index has the current `schema_version`, `normalizeIndexShape` is not called and no write occurs.
 2. When the field is absent (legacy index), normalization and re-write happen exactly once.
 3. The `schema_version` field is included in `index.schema.json` as an optional integer and validates correctly.
@@ -1113,6 +1178,7 @@ async readIndex(): Promise<AnyRecord> {
 `structuredClone` serializes the entire plan object graph for a mutation that only touches five top-level fields. Since those fields are scalars or wholly replaced arrays, a shallow spread is sufficient and does not risk mutating the original.
 
 **Before:**
+
 ```typescript
 private buildUpdatedPlan(plan: AnyRecord, planVersion: number, decision: ReconciliationDecision): AnyRecord {
   const nextPlan = structuredClone(plan);
@@ -1129,6 +1195,7 @@ private buildUpdatedPlan(plan: AnyRecord, planVersion: number, decision: Reconci
 ```
 
 **After:**
+
 ```typescript
 private buildUpdatedPlan(plan: AnyRecord, planVersion: number, decision: ReconciliationDecision): AnyRecord {
   return {
@@ -1146,10 +1213,12 @@ private buildUpdatedPlan(plan: AnyRecord, planVersion: number, decision: Reconci
 ```
 
 **Tests to write:** `apps/control-plane/test/planning-wave-executor.spec.ts` (existing — add cases)
+
 - `GIVEN_buildUpdatedPlan_WHEN_called_THEN_original_plan_is_not_mutated`
 - `GIVEN_buildUpdatedPlan_WHEN_called_THEN_only_mutated_fields_change`
 
 **Acceptance criteria:**
+
 1. Returned plan object has all fields from the original plan plus the five updated fields.
 2. The original `plan` argument is not mutated.
 3. `structuredClone` is not called.
@@ -1161,6 +1230,7 @@ private buildUpdatedPlan(plan: AnyRecord, planVersion: number, decision: Reconci
 
 **Fixes:** Finding M-1
 **Files:**
+
 - **Create:** `apps/control-plane/src/core/utils.ts`
 - **Refactor** (replace local definition, add import):
   - `apps/control-plane/src/core/kernel.ts`
@@ -1174,6 +1244,7 @@ private buildUpdatedPlan(plan: AnyRecord, planVersion: number, decision: Reconci
 **Note:** The v1.0 spec missed `kernel.ts`, `lock-service.ts`, and `plan-service.ts`. All 7 files must be updated in this task for the extraction to be complete.
 
 Add to `apps/control-plane/src/core/utils.ts`:
+
 ```typescript
 /** Deduplicate and sort a string array. Stable across key order. */
 export function normalizeSet(array: string[]): string[] {
@@ -1182,21 +1253,25 @@ export function normalizeSet(array: string[]): string[] {
 ```
 
 In each of the seven files, remove the local definition and add:
+
 ```typescript
-import { normalizeSet } from '../../core/utils.js';  // adjust relative path per file
+import { normalizeSet } from '../../core/utils.js'; // adjust relative path per file
 ```
 
 For `kernel.ts` the import is:
+
 ```typescript
 import { normalizeSet } from './utils.js';
 ```
 
 **Tests to write:** `apps/control-plane/test/core-utils.spec.ts` (existing — add cases)
+
 - `GIVEN_normalizeSet_WHEN_array_has_duplicates_THEN_deduplicates`
 - `GIVEN_normalizeSet_WHEN_array_is_unsorted_THEN_sorts_lexicographically`
 - `GIVEN_normalizeSet_WHEN_empty_array_THEN_returns_empty`
 
 **Acceptance criteria:**
+
 1. All seven files import from `core/utils.js`; no local `normalizeSet` definitions remain anywhere in the codebase.
 2. Behavior is identical to the seven previous implementations (same Set deduplication, same `localeCompare` sort).
 3. No existing tests fail.
@@ -1213,18 +1288,20 @@ import { normalizeSet } from './utils.js';
 `loadRolePrompts()` is called once per feature inside the QA batch loop. The `PromptBundleLoader` cache makes subsequent calls cheap, but the placement is structurally fragile — cache invalidation silently causes per-feature file I/O.
 
 **Before:**
+
 ```typescript
 for (const featureId of batch.slice(0, maxParallelGateRuns)) {
   // ... gate run logic ...
-  const prompts = await this.promptProvider.loadRolePrompts();   // INSIDE LOOP
+  const prompts = await this.promptProvider.loadRolePrompts(); // INSIDE LOOP
   const newQa = await this.provider.createSession('qa', featureId, prompts.qa);
   // ...
 }
 ```
 
 **After:**
+
 ```typescript
-const prompts = await this.promptProvider.loadRolePrompts();  // OUTSIDE LOOP
+const prompts = await this.promptProvider.loadRolePrompts(); // OUTSIDE LOOP
 
 for (const featureId of batch.slice(0, maxParallelGateRuns)) {
   // ... gate run logic ...
@@ -1234,9 +1311,11 @@ for (const featureId of batch.slice(0, maxParallelGateRuns)) {
 ```
 
 **Tests to write:** `apps/control-plane/test/session-management.spec.ts` (existing — add case)
+
 - `GIVEN_QaWaveExecutor_run_WHEN_multiple_features_in_batch_THEN_loadRolePrompts_called_once`
 
 **Acceptance criteria:**
+
 1. `loadRolePrompts` is called exactly once per `run()` invocation regardless of batch size.
 2. The same `prompts` object is used for all session creations in the batch.
 3. QA session rotation behavior is unchanged.
@@ -1257,37 +1336,37 @@ for (const featureId of batch.slice(0, maxParallelGateRuns)) {
 
 ## 5. Risks and Mitigations
 
-| Risk | Mitigation |
-|------|-----------|
-| `Promise.all` parallelism exposes hidden race conditions in test mocks | Add ordering assertions in tests; use `vi.fn()` with explicit mock return sequences |
-| Context projection silently drops fields agents depend on | Gated behind `role: 'full'` default; add integration test asserting full bundle is unchanged |
-| `schema_version` constant not bumped when shape changes | Developer protocol comment co-located in `kernel.ts`; shape-drift detection test in `kernel.spec.ts` |
-| `structuredClone` removal causes mutation if spread is too shallow | The five mutated fields are scalars or wholly replaced arrays; mutation-guard test confirms |
-| Evidence pruning deletes a file being read concurrently | Pruning occurs after the gate write completes; `fs.unlink` uses `.catch(() => undefined)` |
-| `normalizeSet` extraction breaks an unknown caller | Signature is identical; all seven files updated atomically in this task; `npm run typecheck` catches any missed callers |
-| Repair context re-fetch in PER-T-003 is still an extra call | This is by design: one fetch per failing feature vs one fetch per retry in v1.0; net improvement |
-| `latest.json` write in `gates.ts` fails mid-run | `latest.json` is non-critical metadata; `latest-${mode}.json` sentinel is still written first; `evidenceLatest` falls back to `null` gracefully |
+| Risk                                                                   | Mitigation                                                                                                                                      |
+| ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| `Promise.all` parallelism exposes hidden race conditions in test mocks | Add ordering assertions in tests; use `vi.fn()` with explicit mock return sequences                                                             |
+| Context projection silently drops fields agents depend on              | Gated behind `role: 'full'` default; add integration test asserting full bundle is unchanged                                                    |
+| `schema_version` constant not bumped when shape changes                | Developer protocol comment co-located in `kernel.ts`; shape-drift detection test in `kernel.spec.ts`                                            |
+| `structuredClone` removal causes mutation if spread is too shallow     | The five mutated fields are scalars or wholly replaced arrays; mutation-guard test confirms                                                     |
+| Evidence pruning deletes a file being read concurrently                | Pruning occurs after the gate write completes; `fs.unlink` uses `.catch(() => undefined)`                                                       |
+| `normalizeSet` extraction breaks an unknown caller                     | Signature is identical; all seven files updated atomically in this task; `npm run typecheck` catches any missed callers                         |
+| Repair context re-fetch in PER-T-003 is still an extra call            | This is by design: one fetch per failing feature vs one fetch per retry in v1.0; net improvement                                                |
+| `latest.json` write in `gates.ts` fails mid-run                        | `latest.json` is non-critical metadata; `latest-${mode}.json` sentinel is still written first; `evidenceLatest` falls back to `null` gracefully |
 
 ---
 
 ## 6. Task Backlog
 
-| ID | Milestone | File(s) | Description |
-|----|-----------|---------|-------------|
-| PER-T-001 | PER-M1 | `feature-lifecycle-service.ts` | Parallelize 5 sequential reads in `featureGetContext` |
-| PER-T-002 | PER-M1 | `build-wave-executor.ts`, `qa-wave-executor.ts` | Parallelize status-filter loops |
-| PER-T-003 | PER-M1 | `build-wave-executor.ts` | Context-capture Map pattern; eliminate per-retry duplicate fetch |
-| PER-T-004 | PER-M1 | `reporting-service.ts` | Parallelize `reportDashboard` state+cost reads |
-| PER-T-005 | PER-M2 | `gate-service.ts`, `gates.ts` | Write canonical `latest.json`; read it directly in `evidenceLatest` |
-| PER-T-006 | PER-M2 | `policy.yaml`, `policy.defaults.yaml`, `policy.schema.json`, `gates.ts` | Add `evidence_retention_count` and pruning logic |
-| PER-T-007 | PER-M3 | `planning-wave-executor.ts` | Pre-filter non-planning features; parallelize context fetches |
-| PER-T-008 | PER-M3 | `feature-lifecycle-service.ts`, input schemas | Role-specific context projections |
-| PER-T-009 | PER-M3 | `feature-lifecycle-service.ts` | Extract and test projection helpers |
-| PER-T-010 | PER-M4 | `run-coordinator.ts` | Evict `statusCache` on feature termination |
-| PER-T-011 | PER-M4 | `kernel.ts`, `schemas/index.schema.json` | Replace `JSON.stringify` diff with `schema_version` guard |
-| PER-T-012 | PER-M4 | `planning-wave-executor.ts` | Replace `structuredClone(plan)` with spread |
-| PER-T-013 | PER-M4 | `core/utils.ts` + 7 files | Deduplicate `normalizeSet` into shared utility |
-| PER-T-014 | PER-M4 | `qa-wave-executor.ts` | Move `loadRolePrompts` outside per-feature loop |
+| ID        | Milestone | File(s)                                                                 | Description                                                         |
+| --------- | --------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------- |
+| PER-T-001 | PER-M1    | `feature-lifecycle-service.ts`                                          | Parallelize 5 sequential reads in `featureGetContext`               |
+| PER-T-002 | PER-M1    | `build-wave-executor.ts`, `qa-wave-executor.ts`                         | Parallelize status-filter loops                                     |
+| PER-T-003 | PER-M1    | `build-wave-executor.ts`                                                | Context-capture Map pattern; eliminate per-retry duplicate fetch    |
+| PER-T-004 | PER-M1    | `reporting-service.ts`                                                  | Parallelize `reportDashboard` state+cost reads                      |
+| PER-T-005 | PER-M2    | `gate-service.ts`, `gates.ts`                                           | Write canonical `latest.json`; read it directly in `evidenceLatest` |
+| PER-T-006 | PER-M2    | `policy.yaml`, `policy.defaults.yaml`, `policy.schema.json`, `gates.ts` | Add `evidence_retention_count` and pruning logic                    |
+| PER-T-007 | PER-M3    | `planning-wave-executor.ts`                                             | Pre-filter non-planning features; parallelize context fetches       |
+| PER-T-008 | PER-M3    | `feature-lifecycle-service.ts`, input schemas                           | Role-specific context projections                                   |
+| PER-T-009 | PER-M3    | `feature-lifecycle-service.ts`                                          | Extract and test projection helpers                                 |
+| PER-T-010 | PER-M4    | `run-coordinator.ts`                                                    | Evict `statusCache` on feature termination                          |
+| PER-T-011 | PER-M4    | `kernel.ts`, `schemas/index.schema.json`                                | Replace `JSON.stringify` diff with `schema_version` guard           |
+| PER-T-012 | PER-M4    | `planning-wave-executor.ts`                                             | Replace `structuredClone(plan)` with spread                         |
+| PER-T-013 | PER-M4    | `core/utils.ts` + 7 files                                               | Deduplicate `normalizeSet` into shared utility                      |
+| PER-T-014 | PER-M4    | `qa-wave-executor.ts`                                                   | Move `loadRolePrompts` outside per-feature loop                     |
 
 ---
 
@@ -1350,19 +1429,19 @@ The following 28 ordered steps represent the complete implementation sequence. S
 
 ## 9. Spec Gap Tracker
 
-| Task | Status | Notes |
-|------|--------|-------|
-| PER-T-001: Parallelize 5 reads in `featureGetContext` | ⬜ Pending | |
-| PER-T-002: Parallelize status-filter loops | ⬜ Pending | |
-| PER-T-003: Context-capture Map pattern | ⬜ Pending | Redesigned from v1.0 |
-| PER-T-004: Parallelize `reportDashboard` reads | ⬜ Pending | |
-| PER-T-005: Write + read `latest.json` sentinel | ⬜ Pending | v1.0 had wrong filename |
-| PER-T-006: Evidence retention policy | ⬜ Pending | Pruning filter updated for `latest-*.json` |
-| PER-T-007: Pre-filter + parallel context in `PlanningWaveExecutor` | ⬜ Pending | `runPostQaReconciliation` fully specified |
-| PER-T-008: Role-specific context projections | ⬜ Pending | Output schema note added |
-| PER-T-009: Extract projection helpers | ⬜ Pending | `QaIndexSnapshot` type defined |
-| PER-T-010: Evict `statusCache` on termination | ⬜ Pending | |
-| PER-T-011: `schema_version` guard in `readIndex` | ⬜ Pending | Version-bump protocol added |
-| PER-T-012: Replace `structuredClone` with spread | ⬜ Pending | |
-| PER-T-013: Extract `normalizeSet` (7 files) | ⬜ Pending | Expanded from 4 to 7 files |
-| PER-T-014: Move `loadRolePrompts` out of loop | ⬜ Pending | |
+| Task                                                               | Status     | Notes                                      |
+| ------------------------------------------------------------------ | ---------- | ------------------------------------------ |
+| PER-T-001: Parallelize 5 reads in `featureGetContext`              | ⬜ Pending |                                            |
+| PER-T-002: Parallelize status-filter loops                         | ⬜ Pending |                                            |
+| PER-T-003: Context-capture Map pattern                             | ⬜ Pending | Redesigned from v1.0                       |
+| PER-T-004: Parallelize `reportDashboard` reads                     | ⬜ Pending |                                            |
+| PER-T-005: Write + read `latest.json` sentinel                     | ⬜ Pending | v1.0 had wrong filename                    |
+| PER-T-006: Evidence retention policy                               | ⬜ Pending | Pruning filter updated for `latest-*.json` |
+| PER-T-007: Pre-filter + parallel context in `PlanningWaveExecutor` | ⬜ Pending | `runPostQaReconciliation` fully specified  |
+| PER-T-008: Role-specific context projections                       | ⬜ Pending | Output schema note added                   |
+| PER-T-009: Extract projection helpers                              | ⬜ Pending | `QaIndexSnapshot` type defined             |
+| PER-T-010: Evict `statusCache` on termination                      | ⬜ Pending |                                            |
+| PER-T-011: `schema_version` guard in `readIndex`                   | ⬜ Pending | Version-bump protocol added                |
+| PER-T-012: Replace `structuredClone` with spread                   | ⬜ Pending |                                            |
+| PER-T-013: Extract `normalizeSet` (7 files)                        | ⬜ Pending | Expanded from 4 to 7 files                 |
+| PER-T-014: Move `loadRolePrompts` out of loop                      | ⬜ Pending |                                            |