feat: add readiness promotion criteria matrix

Author: Jacobinwwey

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

@@ -209,6 +209,12 @@ This document re-baselines current mainline truth on 2026-04-19, records what ch
   - 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`.
+- The next bounded execution slice after that makes prerequisite coverage machine-readable:
+  - readiness now reports `promotionCriteria`
+  - readiness now reports `promotionCriteriaPassed`
+  - readiness now reports `promotionCriteriaTotal`
+  - current mainline criteria coverage is `5/7`, with graph/vector independence still unsatisfied
+  - 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,25 +297,28 @@ 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:
+## Latest Mainline Increment (2026-04-20 M8.12 Foundation Promotion-Criteria Matrix)
+
+- Added a machine-readable promotion-criteria matrix so operator tooling and CI can see both coverage and blockers without inferring from prose:
+  - `FoundationReadinessReport.promotionCriteria`
+  - `FoundationReadinessReport.promotionCriteriaPassed`
+  - `FoundationReadinessReport.promotionCriteriaTotal`
+- Current mainline readiness coverage is now explicit:
+  - satisfied: `store_backend_evidence_present`, `query_backend_boundary_present`, `vector_backend_present`, `docs_aligned`, `readiness_verifier_present`
+  - unsatisfied: `graph_backend_independent`, `vector_backend_independent`
+  - current count: `5/7`
+- Blocker evidence remains machine-readable and aligned with the criteria matrix:
   - `graph_backend_not_independent`
   - `vector_backend_not_independent`
-- Missing-boundary fixtures are also distinguishable now:
-  - `query_backend_boundary_missing`
-  - `vector_backend_missing`
+  - missing-boundary fixtures still distinguish `query_backend_boundary_missing` and `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.
+  - `scripts/verify-foundation-readiness.js` now prints promotion criteria counts and per-criterion summaries,
+  - markdown readiness reports include a dedicated `Promotion Criteria` section,
+  - `src/frontend/agent_workspace_runtime.js` persists `promotionCriteriaPassed` / `promotionCriteriaTotal` in `lastFoundationReadiness` and surfaces `criteria 5/7` 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.
+  - criteria improve inspectability only; they do not relax the anti-overclaim boundary.
 
 ## Latest Mainline Increment (2026-04-16 M7.2 Runtime Evidence Deepening Lane)
 

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

@@ -57,6 +57,9 @@ 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:
+  - `promotionCriteria`
+  - `promotionCriteriaPassed`
+  - `promotionCriteriaTotal`
   - `promotionBlockers`
   - `graphBackendStatus`
   - `graphBackendSignalKind`
@@ -74,6 +77,10 @@ Bundle note:
 - Current expected promotion blockers on `main` are:
   - `graph_backend_not_independent`
   - `vector_backend_not_independent`
+- Current expected promotion criteria on `main` are:
+  - passed `5/7`
+  - satisfied: `store_backend_evidence_present`, `query_backend_boundary_present`, `vector_backend_present`, `docs_aligned`, `readiness_verifier_present`
+  - unsatisfied: `graph_backend_independent`, `vector_backend_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,25 +297,28 @@
   - 决策仍为 `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 类失败。
-- 当前主线阻塞集合现在是显式事实：
+## 主线最新增量（2026-04-20 M8.12 Foundation 晋级条件矩阵）
+
+- 已新增 machine-readable promotion-criteria matrix，执行侧与 CI 现在可以同时看到覆盖面与 blocker，而不必再从 prose 反推：
+  - `FoundationReadinessReport.promotionCriteria`
+  - `FoundationReadinessReport.promotionCriteriaPassed`
+  - `FoundationReadinessReport.promotionCriteriaTotal`
+- 当前主线 readiness 覆盖率现在是显式事实：
+  - 已满足：`store_backend_evidence_present`、`query_backend_boundary_present`、`vector_backend_present`、`docs_aligned`、`readiness_verifier_present`
+  - 未满足：`graph_backend_independent`、`vector_backend_independent`
+  - 当前计数：`5/7`
+- blocker 证据仍保持 machine-readable，并与 criteria matrix 对齐：
   - `graph_backend_not_independent`
   - `vector_backend_not_independent`
-- 缺失边界的 fixture 现在也能被准确区分：
-  - `query_backend_boundary_missing`
-  - `vector_backend_missing`
+  - 缺失边界 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，并在工具栏摘要里显示。
+  - `scripts/verify-foundation-readiness.js` 现在会输出 promotion criteria 计数与逐项摘要，
+  - readiness markdown 报告新增独立 `Promotion Criteria` 小节，
+  - `src/frontend/agent_workspace_runtime.js` 会在 `lastFoundationReadiness` 中保留 `promotionCriteriaPassed` / `promotionCriteriaTotal`，并在工具栏摘要里显示 `criteria 5/7`。
 - `main` 上的护栏结论保持不变：
   - 状态仍为 `in_progress`，
   - 决策仍为 `no-go`，
-  - blocker 只是把阻塞证据显式化，不构成状态升级。
+  - criteria 只是提升可观测性，不会放松 anti-overclaim 边界。
 
 ## 主线最新增量（2026-04-16 M7.2 运行时证据加深链路）
 

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

@@ -57,6 +57,9 @@
   - 决策 `No-Go`
   - 原因：主线 persistence 仍是 `file_snapshot_only`，query-backend 与 vector 边界虽已进入主线，但 graph backend 独立性仍缺失，且 vector adapter 仍只是 `prefilter_only`，因此独立 graph/ANN 证据仍未进入主线。
 - readiness 载荷现在也显式区分这层语义：
+  - `promotionCriteria`
+  - `promotionCriteriaPassed`
+  - `promotionCriteriaTotal`
   - `promotionBlockers`
   - `graphBackendStatus`
   - `graphBackendSignalKind`
@@ -74,6 +77,10 @@
 - 当前 `main` 的预期晋级阻塞项为：
   - `graph_backend_not_independent`
   - `vector_backend_not_independent`
+- 当前 `main` 的预期晋级条件矩阵为：
+  - 通过 `5/7`
+  - 已满足：`store_backend_evidence_present`、`query_backend_boundary_present`、`vector_backend_present`、`docs_aligned`、`readiness_verifier_present`
+  - 未满足：`graph_backend_independent`、`vector_backend_independent`
 - 当前 `main` 的预期信号语义为：
   - `queryBackendScoreSignals = [keyword_matches, title_match_bonus, vector_prefilter_content_bonus, relation_bonus]`
   - `vectorAdapterSignalKind = lexical_token_overlap`

scripts/foundation-readiness-utils.js

@@ -29,6 +29,10 @@ function createPromotionBlocker(blockerId, summary) {
   return { blockerId, summary };
 }
 
+function createPromotionCriterion(criterionId, satisfied, summary) {
+  return { criterionId, satisfied, summary };
+}
+
 function resolveVectorAdapterStatus(vectorAdapterSource, vectorAdapterModulePresent) {
   if (!vectorAdapterModulePresent) {
     return 'absent';
@@ -228,10 +232,11 @@ function evaluateFoundationReadiness(options = {}) {
   const dashboardReferencesPresent =
     enDashboard.includes('foundation-reentry-readiness-checklist')
     && zhDashboard.includes('foundation-reentry-readiness-checklist');
+  const docsAligned = checklistPagesPresent && dashboardReferencesPresent;
   const readinessVerifierPresent =
     scripts['verify:foundation:readiness'] === 'node scripts/verify-foundation-readiness.js';
 
-  const baselineReady = storeModulePresent && checklistPagesPresent && dashboardReferencesPresent;
+  const baselineReady = storeModulePresent && docsAligned;
 
   let status = 'planned';
   let decision = 'no-go';
@@ -272,6 +277,62 @@ function evaluateFoundationReadiness(options = {}) {
     },
   ];
 
+  const promotionCriteria = [
+    createPromotionCriterion(
+      'store_backend_evidence_present',
+      storeModulePresent,
+      storeModulePresent
+        ? 'Store backend evidence is present in the repository baseline.'
+        : 'Store backend evidence is missing or unreadable.'
+    ),
+    createPromotionCriterion(
+      'graph_backend_independent',
+      graphBackendIndependent,
+      graphBackendIndependent
+        ? 'Graph backend resolves to independent graph semantics.'
+        : 'Graph backend still resolves to file-backed snapshot semantics.'
+    ),
+    createPromotionCriterion(
+      'query_backend_boundary_present',
+      graphAdapterModulePresent,
+      graphAdapterModulePresent
+        ? 'Dedicated query backend boundary is present.'
+        : 'Dedicated query backend boundary is absent.'
+    ),
+    createPromotionCriterion(
+      'vector_backend_present',
+      vectorAdapterModulePresent,
+      vectorAdapterModulePresent
+        ? 'Dedicated vector adapter boundary is present.'
+        : 'Dedicated vector adapter boundary is absent.'
+    ),
+    createPromotionCriterion(
+      'vector_backend_independent',
+      vectorAdapterIndependent,
+      vectorAdapterIndependent
+        ? 'Vector backend resolves to independent ANN semantics.'
+        : vectorAdapterModulePresent
+          ? 'Vector backend still resolves to lexical prefilter semantics.'
+          : 'Vector backend cannot be independent because the adapter boundary is absent.'
+    ),
+    createPromotionCriterion(
+      'docs_aligned',
+      docsAligned,
+      docsAligned
+        ? 'EN/ZH checklist and dashboard references are aligned.'
+        : 'EN/ZH checklist and dashboard references are not aligned.'
+    ),
+    createPromotionCriterion(
+      'readiness_verifier_present',
+      readinessVerifierPresent,
+      readinessVerifierPresent
+        ? 'Readiness verifier command is present in package scripts.'
+        : 'Readiness verifier command is missing from package scripts.'
+    ),
+  ];
+  const promotionCriteriaPassed = promotionCriteria.filter((entry) => entry.satisfied).length;
+  const promotionCriteriaTotal = promotionCriteria.length;
+
   const promotionBlockers = [];
   const recommendations = [];
 
@@ -353,7 +414,7 @@ function evaluateFoundationReadiness(options = {}) {
     );
   }
 
-  if (!checklistPagesPresent || !dashboardReferencesPresent) {
+  if (!docsAligned) {
     promotionBlockers.push(
       createPromotionBlocker(
         'docs_not_aligned',
@@ -412,6 +473,9 @@ function evaluateFoundationReadiness(options = {}) {
       readinessVerifierPresent,
     },
     mandatoryChecks,
+    promotionCriteriaPassed,
+    promotionCriteriaTotal,
+    promotionCriteria,
     promotionBlockers,
     recommendations,
   };
@@ -469,6 +533,12 @@ function formatFoundationReadinessMarkdown(result, reportPaths) {
     });
   }
 
+  lines.push('', '## Promotion Criteria', '');
+  lines.push(`- Passed: ${result.promotionCriteriaPassed}/${result.promotionCriteriaTotal}`);
+  result.promotionCriteria.forEach((entry) => {
+    lines.push(`- ${entry.criterionId}: ${entry.satisfied ? 'yes' : 'no'} (${entry.summary})`);
+  });
+
   lines.push('', '## Recommendations', '');
   result.recommendations.forEach((entry) => {
     lines.push(`- ${entry}`);

scripts/verify-foundation-readiness.js

@@ -49,6 +49,14 @@ function printHumanReport(result, reportPaths) {
   console.log(
     `[Foundation Readiness] Readiness verifier present: ${result.packageScripts.readinessVerifierPresent ? 'yes' : 'no'}`
   );
+  console.log(
+    `[Foundation Readiness] Promotion criteria: ${result.promotionCriteriaPassed}/${result.promotionCriteriaTotal}`
+  );
+  result.promotionCriteria.forEach((entry) => {
+    console.log(
+      `  - ${entry.criterionId}: ${entry.satisfied ? 'yes' : 'no'} (${entry.summary})`
+    );
+  });
   console.log('[Foundation Readiness] Mandatory checks:');
   result.mandatoryChecks.forEach((entry) => {
     console.log(`  - ${entry.gateId}: ${entry.command}`);

src/agent_workspace.runtime.behavior.test.ts

@@ -1688,6 +1688,45 @@ describe('agent workspace runtime behavior', () => {
                     packageScripts: {
                         readinessVerifierPresent: true,
                     },
+                    promotionCriteriaPassed: 5,
+                    promotionCriteriaTotal: 7,
+                    promotionCriteria: [
+                        {
+                            criterionId: 'store_backend_evidence_present',
+                            satisfied: true,
+                            summary: 'Store backend evidence is present in the repository baseline.',
+                        },
+                        {
+                            criterionId: 'graph_backend_independent',
+                            satisfied: false,
+                            summary: 'Graph backend still resolves to file-backed snapshot semantics.',
+                        },
+                        {
+                            criterionId: 'query_backend_boundary_present',
+                            satisfied: true,
+                            summary: 'Dedicated query backend boundary is present.',
+                        },
+                        {
+                            criterionId: 'vector_backend_present',
+                            satisfied: true,
+                            summary: 'Dedicated vector adapter boundary is present.',
+                        },
+                        {
+                            criterionId: 'vector_backend_independent',
+                            satisfied: false,
+                            summary: 'Vector backend still resolves to lexical prefilter semantics.',
+                        },
+                        {
+                            criterionId: 'docs_aligned',
+                            satisfied: true,
+                            summary: 'EN/ZH checklist and dashboard references are aligned.',
+                        },
+                        {
+                            criterionId: 'readiness_verifier_present',
+                            satisfied: true,
+                            summary: 'Readiness verifier command is present in package scripts.',
+                        },
+                    ],
                     mandatoryChecks: [
                         {
                             gateId: 'contract',
@@ -1736,6 +1775,7 @@ describe('agent workspace runtime behavior', () => {
         expect(messages.textContent || '').toContain('lexical_token_overlap');
         expect(messages.textContent || '').toContain('graph_backend_not_independent');
         expect(messages.textContent || '').toContain('vector_backend_not_independent');
+        expect(messages.textContent || '').toContain('criteria 5/7');
 
         const snapshot = runtime.getDiagnosticsSnapshot();
         expect(snapshot.lastFoundationReadiness).toEqual(
@@ -1761,6 +1801,8 @@ describe('agent workspace runtime behavior', () => {
                     'graph_backend_not_independent',
                     'vector_backend_not_independent',
                 ],
+                promotionCriteriaPassed: 5,
+                promotionCriteriaTotal: 7,
                 promotionBlockersCount: 2,
                 recommendationsCount: 2,
             })