feat: expose readiness promotion blockers

Author: Jacobinwwey

docs/brainstorms/2026-04-19-mainline-progress-reconciliation-and-post-m7-direction-requirements.md

@@ -204,6 +204,11 @@ This document re-baselines current mainline truth on 2026-04-19, records what ch
   - readiness now reports `graphBackendIndependent`
   - integrated readiness now requires independent graph-backend evidence in addition to independent vector evidence
   - overall status still remains `in_progress` / `no-go`, because current mainline persistence is still file-backed snapshot-only.
+- The next bounded execution slice after that makes no-go reasons machine-readable:
+  - readiness now reports `promotionBlockers`
+  - current mainline blockers are `graph_backend_not_independent` and `vector_backend_not_independent`
+  - missing query/vector boundary cases now return distinct blocker ids instead of only prose recommendations
+  - overall status still remains `in_progress` / `no-go`.
 - Current expected outcome on `main` remains:
   - status `in_progress`
   - decision `no-go`

docs/diataxis/en/explanation/development-progress-dashboard.md

@@ -297,6 +297,26 @@ Execution anchor:
   - decision stays `no-go`,
   - file snapshots still do not qualify as independent graph backend readiness.
 
+## Latest Mainline Increment (2026-04-20 M8.11 Foundation Promotion-Blocker Evidence)
+
+- Added machine-readable readiness blockers so operator tooling no longer has to parse prose recommendations:
+  - `FoundationReadinessReport.promotionBlockers`
+  - typed blocker ids now distinguish graph, query, vector, docs, store, and verifier failures.
+- Current mainline blocker set is now explicit:
+  - `graph_backend_not_independent`
+  - `vector_backend_not_independent`
+- Missing-boundary fixtures are also distinguishable now:
+  - `query_backend_boundary_missing`
+  - `vector_backend_missing`
+- Runtime/operator visibility stayed aligned:
+  - `scripts/verify-foundation-readiness.js` prints promotion blockers,
+  - markdown readiness reports include a dedicated `Promotion Blockers` section,
+  - `src/frontend/agent_workspace_runtime.js` persists blocker ids in `lastFoundationReadiness` and surfaces them in the toolbar summary.
+- Guardrail remains unchanged on `main`:
+  - status stays `in_progress`,
+  - decision stays `no-go`,
+  - blockers are now explicit evidence, not a status change.
+
 ## Latest Mainline Increment (2026-04-16 M7.2 Runtime Evidence Deepening Lane)
 
 - Expanded runtime behavior coverage in `src/agent_workspace.runtime.behavior.test.ts` for pane lifecycle evidence:

docs/diataxis/en/explanation/foundation-reentry-readiness-checklist.md

@@ -57,6 +57,7 @@ Bundle note:
   - decision `No-Go`
   - rationale: mainline persistence is still `file_snapshot_only`, query-backend and vector-boundary modules are present, but graph-backend independence is absent and the vector adapter is still only `prefilter_only`, so independent graph/ANN evidence is still absent.
 - The readiness payload now makes that distinction explicit:
+  - `promotionBlockers`
   - `graphBackendStatus`
   - `graphBackendSignalKind`
   - `graphBackendIndependent`
@@ -70,6 +71,9 @@ Bundle note:
   - `graphBackendStatus = file_snapshot_only`
   - `graphBackendSignalKind = json_snapshot_file`
   - `graphBackendIndependent = false`
+- Current expected promotion blockers on `main` are:
+  - `graph_backend_not_independent`
+  - `vector_backend_not_independent`
 - Current expected signal semantics on `main` are:
   - `queryBackendScoreSignals = [keyword_matches, title_match_bonus, vector_prefilter_content_bonus, relation_bonus]`
   - `vectorAdapterSignalKind = lexical_token_overlap`

docs/diataxis/zh/explanation/development-progress-dashboard.md

@@ -297,6 +297,26 @@
   - 决策仍为 `no-go`，
   - file snapshot 仍不构成独立 graph backend readiness。
 
+## 主线最新增量（2026-04-20 M8.11 Foundation 晋级阻塞项证据）
+
+- 已新增 machine-readable readiness blockers，执行侧不再需要解析自由文本 recommendation 才能知道 `no-go` 原因：
+  - `FoundationReadinessReport.promotionBlockers`
+  - typed blocker id 现在可区分 graph、query、vector、docs、store、verifier 类失败。
+- 当前主线阻塞集合现在是显式事实：
+  - `graph_backend_not_independent`
+  - `vector_backend_not_independent`
+- 缺失边界的 fixture 现在也能被准确区分：
+  - `query_backend_boundary_missing`
+  - `vector_backend_missing`
+- 运行时/执行侧可见性保持对齐：
+  - `scripts/verify-foundation-readiness.js` 现在输出 promotion blockers，
+  - readiness markdown 报告新增独立 `Promotion Blockers` 小节，
+  - `src/frontend/agent_workspace_runtime.js` 会在 `lastFoundationReadiness` 中保留 blocker ids，并在工具栏摘要里显示。
+- `main` 上的护栏结论保持不变：
+  - 状态仍为 `in_progress`，
+  - 决策仍为 `no-go`，
+  - blocker 只是把阻塞证据显式化，不构成状态升级。
+
 ## 主线最新增量（2026-04-16 M7.2 运行时证据加深链路）
 
 - 已在 `src/agent_workspace.runtime.behavior.test.ts` 扩展 pane 生命周期证据覆盖：

docs/diataxis/zh/explanation/foundation-reentry-readiness-checklist.md

@@ -57,6 +57,7 @@
   - 决策 `No-Go`
   - 原因：主线 persistence 仍是 `file_snapshot_only`，query-backend 与 vector 边界虽已进入主线，但 graph backend 独立性仍缺失，且 vector adapter 仍只是 `prefilter_only`，因此独立 graph/ANN 证据仍未进入主线。
 - readiness 载荷现在也显式区分这层语义：
+  - `promotionBlockers`
   - `graphBackendStatus`
   - `graphBackendSignalKind`
   - `graphBackendIndependent`
@@ -70,6 +71,9 @@
   - `graphBackendStatus = file_snapshot_only`
   - `graphBackendSignalKind = json_snapshot_file`
   - `graphBackendIndependent = false`
+- 当前 `main` 的预期晋级阻塞项为：
+  - `graph_backend_not_independent`
+  - `vector_backend_not_independent`
 - 当前 `main` 的预期信号语义为：
   - `queryBackendScoreSignals = [keyword_matches, title_match_bonus, vector_prefilter_content_bonus, relation_bonus]`
   - `vectorAdapterSignalKind = lexical_token_overlap`

scripts/foundation-readiness-utils.js

@@ -25,6 +25,10 @@ function fileExists(filePath) {
   }
 }
 
+function createPromotionBlocker(blockerId, summary) {
+  return { blockerId, summary };
+}
+
 function resolveVectorAdapterStatus(vectorAdapterSource, vectorAdapterModulePresent) {
   if (!vectorAdapterModulePresent) {
     return 'absent';
@@ -268,6 +272,7 @@ function evaluateFoundationReadiness(options = {}) {
     },
   ];
 
+  const promotionBlockers = [];
   const recommendations = [];
 
   if (!fileBackedStore && !graphBackendIndependent) {
@@ -277,42 +282,96 @@ function evaluateFoundationReadiness(options = {}) {
   }
 
   if (!storeModulePresent) {
+    promotionBlockers.push(
+      createPromotionBlocker(
+        'store_backend_evidence_missing',
+        'Store backend evidence is missing or unreadable.'
+      )
+    );
     recommendations.push(
       'Restore explicit store backend evidence before advancing foundation readiness claims.'
     );
   }
 
   if (!graphBackendIndependent) {
+    promotionBlockers.push(
+      createPromotionBlocker(
+        'graph_backend_not_independent',
+        'Graph backend still resolves to file-backed snapshot semantics.'
+      )
+    );
     recommendations.push(
       'Keep foundation re-entry at no-go while graph persistence remains file-backed snapshot storage without independent graph backend semantics on mainline.'
     );
   }
 
   if (!graphAdapterModulePresent && !vectorAdapterModulePresent) {
+    promotionBlockers.push(
+      createPromotionBlocker(
+        'query_backend_boundary_missing',
+        'Dedicated query backend boundary is absent.'
+      )
+    );
+    promotionBlockers.push(
+      createPromotionBlocker(
+        'vector_backend_missing',
+        'Dedicated vector adapter boundary is absent.'
+      )
+    );
     recommendations.push(
       'Do not claim foundation re-entry integrated while dedicated graph/vector adapter modules remain absent on mainline.'
     );
   } else if (!graphAdapterModulePresent) {
+    promotionBlockers.push(
+      createPromotionBlocker(
+        'query_backend_boundary_missing',
+        'Dedicated query backend boundary is absent.'
+      )
+    );
     recommendations.push(
       'Keep foundation re-entry at no-go while a dedicated query backend boundary is still absent on mainline.'
     );
   } else if (!vectorAdapterModulePresent) {
+    promotionBlockers.push(
+      createPromotionBlocker(
+        'vector_backend_missing',
+        'Dedicated vector adapter boundary is absent.'
+      )
+    );
     recommendations.push(
       'Keep foundation re-entry at no-go while vector adapter independence remains absent on mainline.'
     );
   } else if (!vectorAdapterIndependent) {
+    promotionBlockers.push(
+      createPromotionBlocker(
+        'vector_backend_not_independent',
+        'Vector backend still resolves to lexical prefilter semantics.'
+      )
+    );
     recommendations.push(
       'Keep foundation re-entry at no-go while the vector adapter remains a local prefilter boundary without independent ANN evidence on mainline.'
     );
   }
 
   if (!checklistPagesPresent || !dashboardReferencesPresent) {
+    promotionBlockers.push(
+      createPromotionBlocker(
+        'docs_not_aligned',
+        'EN/ZH checklist and dashboard references are not aligned.'
+      )
+    );
     recommendations.push(
       'Keep EN/ZH checklist and dashboard references aligned before treating foundation work as active on mainline.'
     );
   }
 
   if (!readinessVerifierPresent) {
+    promotionBlockers.push(
+      createPromotionBlocker(
+        'readiness_verifier_missing',
+        'Readiness verifier command is missing from package scripts.'
+      )
+    );
     recommendations.push(
       'Expose a single readiness verifier command so operators can inspect current mainline baseline without scanning docs manually.'
     );
@@ -353,6 +412,7 @@ function evaluateFoundationReadiness(options = {}) {
       readinessVerifierPresent,
     },
     mandatoryChecks,
+    promotionBlockers,
     recommendations,
   };
 }
@@ -400,6 +460,15 @@ function formatFoundationReadinessMarkdown(result, reportPaths) {
     lines.push(`- ${entry.gateId}: \`${entry.command}\``);
   });
 
+  lines.push('', '## Promotion Blockers', '');
+  if (result.promotionBlockers.length === 0) {
+    lines.push('- none');
+  } else {
+    result.promotionBlockers.forEach((entry) => {
+      lines.push(`- ${entry.blockerId}: ${entry.summary}`);
+    });
+  }
+
   lines.push('', '## Recommendations', '');
   result.recommendations.forEach((entry) => {
     lines.push(`- ${entry}`);

scripts/verify-foundation-readiness.js

@@ -53,6 +53,14 @@ function printHumanReport(result, reportPaths) {
   result.mandatoryChecks.forEach((entry) => {
     console.log(`  - ${entry.gateId}: ${entry.command}`);
   });
+  console.log('[Foundation Readiness] Promotion blockers:');
+  if (result.promotionBlockers.length === 0) {
+    console.log('  - none');
+  } else {
+    result.promotionBlockers.forEach((entry) => {
+      console.log(`  - ${entry.blockerId}: ${entry.summary}`);
+    });
+  }
   console.log('[Foundation Readiness] Recommendations:');
   result.recommendations.forEach((entry) => {
     console.log(`  - ${entry}`);

src/agent_workspace.runtime.behavior.test.ts

@@ -1694,7 +1694,18 @@ describe('agent workspace runtime behavior', () => {
                             command: 'npm test -- src/knowledge.api.contract.test.ts --runInBand',
                         },
                     ],
+                    promotionBlockers: [
+                        {
+                            blockerId: 'graph_backend_not_independent',
+                            summary: 'Graph backend still resolves to file-backed snapshot semantics.',
+                        },
+                        {
+                            blockerId: 'vector_backend_not_independent',
+                            summary: 'Vector backend still resolves to lexical prefilter semantics.',
+                        },
+                    ],
                     recommendations: [
+                        'Keep foundation re-entry at no-go while graph persistence remains file-backed snapshot storage without independent graph backend semantics on mainline.',
                         'Keep foundation re-entry at no-go while the vector adapter remains a local prefilter boundary without independent ANN evidence on mainline.',
                     ],
                 },
@@ -1723,6 +1734,8 @@ describe('agent workspace runtime behavior', () => {
         expect(messages.textContent || '').toContain('prefilter_only');
         expect(messages.textContent || '').toContain('local_hybrid');
         expect(messages.textContent || '').toContain('lexical_token_overlap');
+        expect(messages.textContent || '').toContain('graph_backend_not_independent');
+        expect(messages.textContent || '').toContain('vector_backend_not_independent');
 
         const snapshot = runtime.getDiagnosticsSnapshot();
         expect(snapshot.lastFoundationReadiness).toEqual(
@@ -1744,7 +1757,12 @@ describe('agent workspace runtime behavior', () => {
                 vectorAdapterSignalKind: 'lexical_token_overlap',
                 vectorAdapterIndependent: false,
                 vectorAdapterLinkedIntoQueryBackend: true,
-                recommendationsCount: 1,
+                promotionBlockerIds: [
+                    'graph_backend_not_independent',
+                    'vector_backend_not_independent',
+                ],
+                promotionBlockersCount: 2,
+                recommendationsCount: 2,
             })
         );
     });

src/foundation.readiness.contract.test.ts

@@ -33,6 +33,17 @@ type FoundationReadinessResult = {
   packageScripts: {
     readinessVerifierPresent: boolean;
   };
+  promotionBlockers: Array<{
+    blockerId:
+      | 'store_backend_evidence_missing'
+      | 'graph_backend_not_independent'
+      | 'query_backend_boundary_missing'
+      | 'vector_backend_missing'
+      | 'vector_backend_not_independent'
+      | 'docs_not_aligned'
+      | 'readiness_verifier_missing';
+    summary: string;
+  }>;
   recommendations: string[];
 };
 
@@ -133,6 +144,10 @@ describe('foundation readiness contract', () => {
     expect(result.documents.checklistPagesPresent).toBe(true);
     expect(result.documents.dashboardReferencesPresent).toBe(true);
     expect(result.packageScripts.readinessVerifierPresent).toBe(true);
+    expect(result.promotionBlockers.map((entry) => entry.blockerId)).toEqual([
+      'graph_backend_not_independent',
+      'vector_backend_not_independent',
+    ]);
     expect(result.recommendations).toContain(
       'Keep foundation re-entry at no-go while graph persistence remains file-backed snapshot storage without independent graph backend semantics on mainline.'
     );
@@ -200,6 +215,9 @@ describe('foundation readiness contract', () => {
     expect(result.baseline.vectorAdapterLinkedIntoQueryBackend).toBe(false);
     expect(result.documents.checklistPagesPresent).toBe(true);
     expect(result.documents.dashboardReferencesPresent).toBe(true);
+    expect(result.promotionBlockers.map((entry) => entry.blockerId)).toEqual([
+      'graph_backend_not_independent',
+    ]);
     expect(result.recommendations).toContain(
       'Keep foundation re-entry at no-go while graph persistence remains file-backed snapshot storage without independent graph backend semantics on mainline.'
     );
@@ -264,5 +282,54 @@ describe('foundation readiness contract', () => {
     expect(result.baseline.vectorAdapterLinkedIntoQueryBackend).toBe(false);
     expect(result.documents.checklistPagesPresent).toBe(true);
     expect(result.documents.dashboardReferencesPresent).toBe(true);
+    expect(result.promotionBlockers).toEqual([]);
+  });
+
+  test('missing query or vector boundaries produce machine-readable blockers', () => {
+    expect(utils).not.toBeNull();
+    const fakeRepo = temp.child('repo-missing-boundaries');
+
+    temp.file(
+      'repo-missing-boundaries/package.json',
+      JSON.stringify(
+        {
+          scripts: {
+            'verify:foundation:readiness': 'node scripts/verify-foundation-readiness.js',
+          },
+        },
+        null,
+        2
+      )
+    );
+    temp.file(
+      'repo-missing-boundaries/src/learning/store.ts',
+      "export async function loadSnapshot() {}\nexport function createFileBackedKnowledgeGraphStore() {}\nexport const diagnostics = { storeType: 'file' };\n"
+    );
+    temp.file(
+      'repo-missing-boundaries/docs/diataxis/en/explanation/foundation-reentry-readiness-checklist.md',
+      'foundation\n'
+    );
+    temp.file(
+      'repo-missing-boundaries/docs/diataxis/zh/explanation/foundation-reentry-readiness-checklist.md',
+      'foundation\n'
+    );
+    temp.file(
+      'repo-missing-boundaries/docs/diataxis/en/explanation/development-progress-dashboard.md',
+      'foundation-reentry-readiness-checklist\n'
+    );
+    temp.file(
+      'repo-missing-boundaries/docs/diataxis/zh/explanation/development-progress-dashboard.md',
+      'foundation-reentry-readiness-checklist\n'
+    );
+
+    const result = (utils as FoundationReadinessModule).evaluateFoundationReadiness({
+      repoRoot: fakeRepo,
+    });
+
+    expect(result.promotionBlockers.map((entry) => entry.blockerId)).toEqual([
+      'graph_backend_not_independent',
+      'query_backend_boundary_missing',
+      'vector_backend_missing',
+    ]);
   });
 });