feat: expose readiness provenance evidence

Jacobinwwey · Jacobinwwey · commit da4f44b94983 · 2026-04-20T22:36:20.000-05:00
diff --git a/docs/brainstorms/2026-04-19-mainline-progress-reconciliation-and-post-m7-direction-requirements.md b/docs/brainstorms/2026-04-19-mainline-progress-reconciliation-and-post-m7-direction-requirements.md
@@ -215,6 +215,11 @@ This document re-baselines current mainline truth on 2026-04-19, records what ch
   - 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`.
+- The next bounded execution slice after that makes repo-evidence fallback machine-readable:
+  - readiness now reports `provenance.repoRootSource`
+  - readiness now reports `provenance.runtimeProjectRootAligned`
+  - hermetic runtime/API paths can now prove they are reading real repo evidence instead of silently implying local runtime-root alignment
+  - overall status still remains `in_progress` / `no-go`.
 - Current expected outcome on `main` remains:
   - status `in_progress`
   - decision `no-go`
diff --git a/docs/diataxis/en/explanation/development-progress-dashboard.md b/docs/diataxis/en/explanation/development-progress-dashboard.md
@@ -297,6 +297,23 @@ Execution anchor:
   - decision stays `no-go`,
   - file snapshots still do not qualify as independent graph backend readiness.
 
+## Latest Mainline Increment (2026-04-20 M8.13 Foundation Readiness Provenance Evidence)
+
+- Added machine-readable provenance so operator tooling can tell whether readiness is reading the runtime project root or falling back to real repo evidence:
+  - `FoundationReadinessReport.provenance.repoRootSource`
+  - `FoundationReadinessReport.provenance.runtimeProjectRootAligned`
+- Current mainline behavior is now explicit under hermetic runtime/test roots:
+  - direct utility/report usage resolves with aligned provenance,
+  - hermetic runtime/API paths can report `runtimeProjectRootAligned = false` while still preserving the same repo-truth readiness result.
+- Runtime/operator visibility stayed aligned:
+  - `scripts/verify-foundation-readiness.js` now prints provenance lines,
+  - markdown readiness reports include a dedicated `Provenance` section,
+  - `src/frontend/agent_workspace_runtime.js` persists provenance in `lastFoundationReadiness` and surfaces `repo-source ... aligned ...` in the toolbar summary.
+- Guardrail remains unchanged on `main`:
+  - status stays `in_progress`,
+  - decision stays `no-go`,
+  - provenance improves auditability only; it does not relax the anti-overclaim boundary.
+
 ## 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:
diff --git a/docs/diataxis/en/explanation/foundation-reentry-readiness-checklist.md b/docs/diataxis/en/explanation/foundation-reentry-readiness-checklist.md
@@ -57,6 +57,8 @@ 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:
+  - `provenance.repoRootSource`
+  - `provenance.runtimeProjectRootAligned`
   - `promotionCriteria`
   - `promotionCriteriaPassed`
   - `promotionCriteriaTotal`
@@ -81,6 +83,9 @@ Bundle note:
   - 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 provenance behavior is:
+  - direct verifier/utility usage reports `runtimeProjectRootAligned = true`
+  - hermetic runtime/API usage may report `runtimeProjectRootAligned = false` while preserving the same repo-truth readiness payload
 - Current expected signal semantics on `main` are:
   - `queryBackendScoreSignals = [keyword_matches, title_match_bonus, vector_prefilter_content_bonus, relation_bonus]`
   - `vectorAdapterSignalKind = lexical_token_overlap`
diff --git a/docs/diataxis/zh/explanation/development-progress-dashboard.md b/docs/diataxis/zh/explanation/development-progress-dashboard.md
@@ -297,6 +297,23 @@
   - 决策仍为 `no-go`，
   - file snapshot 仍不构成独立 graph backend readiness。
 
+## 主线最新增量（2026-04-20 M8.13 Foundation Readiness 来源证据）
+
+- 已新增 machine-readable provenance，执行侧现在可以直接知道 readiness 是读取 runtime project root，还是回退到真实 repo 证据：
+  - `FoundationReadinessReport.provenance.repoRootSource`
+  - `FoundationReadinessReport.provenance.runtimeProjectRootAligned`
+- 当前主线在 hermetic runtime/test root 下的行为现在是显式的：
+  - 直接 utility/report 调用会得到对齐状态，
+  - hermetic runtime/API 路径可以显式报告 `runtimeProjectRootAligned = false`，同时仍保持同一份 repo-truth readiness 结论。
+- 运行时/执行侧可见性保持对齐：
+  - `scripts/verify-foundation-readiness.js` 现在会输出 provenance 行，
+  - readiness markdown 报告新增独立 `Provenance` 小节，
+  - `src/frontend/agent_workspace_runtime.js` 会在 `lastFoundationReadiness` 中保留 provenance，并在工具栏摘要中显示 `repo-source ... aligned ...`。
+- `main` 上的护栏结论保持不变：
+  - 状态仍为 `in_progress`，
+  - 决策仍为 `no-go`，
+  - provenance 只提升可审计性，不会放松 anti-overclaim 边界。
+
 ## 主线最新增量（2026-04-20 M8.12 Foundation 晋级条件矩阵）
 
 - 已新增 machine-readable promotion-criteria matrix，执行侧与 CI 现在可以同时看到覆盖面与 blocker，而不必再从 prose 反推：
diff --git a/docs/diataxis/zh/explanation/foundation-reentry-readiness-checklist.md b/docs/diataxis/zh/explanation/foundation-reentry-readiness-checklist.md
@@ -57,6 +57,8 @@
   - 决策 `No-Go`
   - 原因：主线 persistence 仍是 `file_snapshot_only`，query-backend 与 vector 边界虽已进入主线，但 graph backend 独立性仍缺失，且 vector adapter 仍只是 `prefilter_only`，因此独立 graph/ANN 证据仍未进入主线。
 - readiness 载荷现在也显式区分这层语义：
+  - `provenance.repoRootSource`
+  - `provenance.runtimeProjectRootAligned`
   - `promotionCriteria`
   - `promotionCriteriaPassed`
   - `promotionCriteriaTotal`
@@ -81,6 +83,9 @@
   - 通过 `5/7`
   - 已满足：`store_backend_evidence_present`、`query_backend_boundary_present`、`vector_backend_present`、`docs_aligned`、`readiness_verifier_present`
   - 未满足：`graph_backend_independent`、`vector_backend_independent`
+- 当前预期 provenance 行为为：
+  - 直接 verifier/utility 调用会报告 `runtimeProjectRootAligned = true`
+  - hermetic runtime/API 调用可能报告 `runtimeProjectRootAligned = false`，但 readiness 载荷仍必须保持同一份 repo-truth 结论
 - 当前 `main` 的预期信号语义为：
   - `queryBackendScoreSignals = [keyword_matches, title_match_bonus, vector_prefilter_content_bonus, relation_bonus]`
   - `vectorAdapterSignalKind = lexical_token_overlap`
diff --git a/scripts/foundation-readiness-utils.js b/scripts/foundation-readiness-utils.js
@@ -159,6 +159,10 @@ function resolveVectorAdapterSignalKind(vectorAdapterSource, vectorAdapterModule
 
 function evaluateFoundationReadiness(options = {}) {
   const repoRoot = options.repoRoot || path.resolve(__dirname, '..');
+  const provenance = options.provenance || {
+    repoRootSource: options.repoRoot ? 'explicit' : 'module_root',
+    runtimeProjectRootAligned: true,
+  };
   const packageJson = readJsonIfExists(path.join(repoRoot, 'package.json'));
   const scripts = packageJson.scripts || {};
 
@@ -472,6 +476,7 @@ function evaluateFoundationReadiness(options = {}) {
     packageScripts: {
       readinessVerifierPresent,
     },
+    provenance,
     mandatoryChecks,
     promotionCriteriaPassed,
     promotionCriteriaTotal,
@@ -516,6 +521,11 @@ function formatFoundationReadinessMarkdown(result, reportPaths) {
     '',
     `- Readiness verifier present: ${result.packageScripts.readinessVerifierPresent ? 'yes' : 'no'}`,
     '',
+    '## Provenance',
+    '',
+    `- Repo root source: ${result.provenance.repoRootSource}`,
+    `- Runtime project root aligned: ${result.provenance.runtimeProjectRootAligned ? 'yes' : 'no'}`,
+    '',
     '## Mandatory Checks',
     '',
   ];
diff --git a/scripts/verify-foundation-readiness.js b/scripts/verify-foundation-readiness.js
@@ -49,6 +49,10 @@ function printHumanReport(result, reportPaths) {
   console.log(
     `[Foundation Readiness] Readiness verifier present: ${result.packageScripts.readinessVerifierPresent ? 'yes' : 'no'}`
   );
+  console.log(`[Foundation Readiness] Repo root source: ${result.provenance.repoRootSource}`);
+  console.log(
+    `[Foundation Readiness] Runtime project root aligned: ${result.provenance.runtimeProjectRootAligned ? 'yes' : 'no'}`
+  );
   console.log(
     `[Foundation Readiness] Promotion criteria: ${result.promotionCriteriaPassed}/${result.promotionCriteriaTotal}`
   );
diff --git a/src/agent_workspace.runtime.behavior.test.ts b/src/agent_workspace.runtime.behavior.test.ts
@@ -1688,6 +1688,10 @@ describe('agent workspace runtime behavior', () => {
                     packageScripts: {
                         readinessVerifierPresent: true,
                     },
+                    provenance: {
+                        repoRootSource: 'cwd',
+                        runtimeProjectRootAligned: false,
+                    },
                     promotionCriteriaPassed: 5,
                     promotionCriteriaTotal: 7,
                     promotionCriteria: [
@@ -1773,6 +1777,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('repo-source cwd');
+        expect(messages.textContent || '').toContain('aligned no');
         expect(messages.textContent || '').toContain('graph_backend_not_independent');
         expect(messages.textContent || '').toContain('vector_backend_not_independent');
         expect(messages.textContent || '').toContain('criteria 5/7');
@@ -1797,6 +1803,8 @@ describe('agent workspace runtime behavior', () => {
                 vectorAdapterSignalKind: 'lexical_token_overlap',
                 vectorAdapterIndependent: false,
                 vectorAdapterLinkedIntoQueryBackend: true,
+                repoRootSource: 'cwd',
+                runtimeProjectRootAligned: false,
                 promotionBlockerIds: [
                     'graph_backend_not_independent',
                     'vector_backend_not_independent',
diff --git a/src/foundation.readiness.contract.test.ts b/src/foundation.readiness.contract.test.ts
@@ -33,6 +33,10 @@ type FoundationReadinessResult = {
   packageScripts: {
     readinessVerifierPresent: boolean;
   };
+  provenance: {
+    repoRootSource: 'explicit' | 'project_root_hint' | 'cwd' | 'module_root';
+    runtimeProjectRootAligned: boolean;
+  };
   promotionCriteriaPassed: number;
   promotionCriteriaTotal: number;
   promotionCriteria: Array<{
@@ -158,6 +162,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.provenance).toEqual({
+      repoRootSource: 'explicit',
+      runtimeProjectRootAligned: true,
+    });
     expect(result.promotionCriteriaPassed).toBe(5);
     expect(result.promotionCriteriaTotal).toBe(7);
     expect(result.promotionCriteria.map((entry) => entry.criterionId)).toEqual([
@@ -251,6 +259,10 @@ describe('foundation readiness contract', () => {
     expect(result.baseline.vectorAdapterLinkedIntoQueryBackend).toBe(false);
     expect(result.documents.checklistPagesPresent).toBe(true);
     expect(result.documents.dashboardReferencesPresent).toBe(true);
+    expect(result.provenance).toEqual({
+      repoRootSource: 'explicit',
+      runtimeProjectRootAligned: true,
+    });
     expect(result.promotionCriteriaPassed).toBe(6);
     expect(result.promotionCriteriaTotal).toBe(7);
     expect(
@@ -332,6 +344,10 @@ describe('foundation readiness contract', () => {
     expect(result.baseline.vectorAdapterLinkedIntoQueryBackend).toBe(false);
     expect(result.documents.checklistPagesPresent).toBe(true);
     expect(result.documents.dashboardReferencesPresent).toBe(true);
+    expect(result.provenance).toEqual({
+      repoRootSource: 'explicit',
+      runtimeProjectRootAligned: true,
+    });
     expect(result.promotionCriteriaPassed).toBe(7);
     expect(result.promotionCriteriaTotal).toBe(7);
     expect(result.promotionCriteria.every((entry) => entry.satisfied)).toBe(true);
@@ -379,6 +395,10 @@ describe('foundation readiness contract', () => {
       repoRoot: fakeRepo,
     });
 
+    expect(result.provenance).toEqual({
+      repoRootSource: 'explicit',
+      runtimeProjectRootAligned: true,
+    });
     expect(result.promotionCriteriaPassed).toBe(3);
     expect(result.promotionCriteriaTotal).toBe(7);
     expect(
diff --git a/src/frontend/agent_workspace_runtime.js b/src/frontend/agent_workspace_runtime.js
@@ -1442,6 +1442,8 @@
                     vectorAdapterSignalKind: '',
                     vectorAdapterIndependent: false,
                     vectorAdapterLinkedIntoQueryBackend: false,
+                    repoRootSource: '',
+                    runtimeProjectRootAligned: false,
                     promotionCriteriaPassed: 0,
                     promotionCriteriaTotal: 0,
                     promotionBlockerIds: [],
@@ -1464,6 +1466,9 @@
                     const recommendationsCount = Array.isArray(readiness && readiness.recommendations)
                         ? readiness.recommendations.length
                         : 0;
+                    const provenance = readiness && readiness.provenance && typeof readiness.provenance === 'object'
+                        ? readiness.provenance
+                        : {};
                     const promotionBlockers = Array.isArray(readiness && readiness.promotionBlockers)
                         ? readiness.promotionBlockers
                             .map((entry) => {
@@ -1512,6 +1517,8 @@
                         vectorAdapterSignalKind: trimString(baseline.vectorAdapterSignalKind),
                         vectorAdapterIndependent: Boolean(baseline.vectorAdapterIndependent),
                         vectorAdapterLinkedIntoQueryBackend: Boolean(baseline.vectorAdapterLinkedIntoQueryBackend),
+                        repoRootSource: trimString(provenance.repoRootSource),
+                        runtimeProjectRootAligned: Boolean(provenance.runtimeProjectRootAligned),
                         promotionCriteriaPassed,
                         promotionCriteriaTotal,
                         promotionBlockerIds,
@@ -1525,7 +1532,7 @@
                         'assistant',
                         getI18nText(
                             'agentWorkspace.messages.foundationReadinessLoaded',
-                            `Foundation readiness ${trimString(readiness && readiness.status) || 'unknown'} / ${trimString(readiness && readiness.decision) || 'unknown'} (store ${trimString(baseline.storeType) || 'n/a'}, graph ${trimString(baseline.graphBackendStatus) || 'n/a'}/${trimString(baseline.graphBackendSignalKind) || 'n/a'}, graph-independent ${Boolean(baseline.graphBackendIndependent) ? 'yes' : 'no'}, backend ${trimString(baseline.queryBackendDefaultMode) || 'n/a'}, signals ${queryBackendScoreSignals.join(', ') || 'none'}, vector ${trimString(baseline.vectorAdapterStatus) || 'n/a'}, signal-kind ${trimString(baseline.vectorAdapterSignalKind) || 'n/a'}, independent ${Boolean(baseline.vectorAdapterIndependent) ? 'yes' : 'no'}, linked ${Boolean(baseline.vectorAdapterLinkedIntoQueryBackend) ? 'yes' : 'no'}, criteria ${promotionCriteriaPassed}/${promotionCriteriaTotal}, blockers ${promotionBlockerIds.join(', ') || 'none'}).`,
+                            `Foundation readiness ${trimString(readiness && readiness.status) || 'unknown'} / ${trimString(readiness && readiness.decision) || 'unknown'} (store ${trimString(baseline.storeType) || 'n/a'}, graph ${trimString(baseline.graphBackendStatus) || 'n/a'}/${trimString(baseline.graphBackendSignalKind) || 'n/a'}, graph-independent ${Boolean(baseline.graphBackendIndependent) ? 'yes' : 'no'}, backend ${trimString(baseline.queryBackendDefaultMode) || 'n/a'}, signals ${queryBackendScoreSignals.join(', ') || 'none'}, vector ${trimString(baseline.vectorAdapterStatus) || 'n/a'}, signal-kind ${trimString(baseline.vectorAdapterSignalKind) || 'n/a'}, independent ${Boolean(baseline.vectorAdapterIndependent) ? 'yes' : 'no'}, linked ${Boolean(baseline.vectorAdapterLinkedIntoQueryBackend) ? 'yes' : 'no'}, repo-source ${trimString(provenance.repoRootSource) || 'n/a'}, aligned ${Boolean(provenance.runtimeProjectRootAligned) ? 'yes' : 'no'}, criteria ${promotionCriteriaPassed}/${promotionCriteriaTotal}, blockers ${promotionBlockerIds.join(', ') || 'none'}).`,
                             {
                                 status: trimString(readiness && readiness.status) || 'unknown',
                                 decision: trimString(readiness && readiness.decision) || 'unknown',
@@ -1541,6 +1548,8 @@
                                 vectorAdapterLinkedIntoQueryBackend: Boolean(baseline.vectorAdapterLinkedIntoQueryBackend)
                                     ? 'yes'
                                     : 'no',
+                                repoRootSource: trimString(provenance.repoRootSource) || 'n/a',
+                                runtimeProjectRootAligned: Boolean(provenance.runtimeProjectRootAligned) ? 'yes' : 'no',
                                 promotionCriteriaPassed,
                                 promotionCriteriaTotal,
                                 promotionBlockerIds: promotionBlockerIds.join(', ') || 'none',
@@ -1564,6 +1573,8 @@
                         vectorAdapterSignalKind: '',
                         vectorAdapterIndependent: false,
                         vectorAdapterLinkedIntoQueryBackend: false,
+                        repoRootSource: '',
+                        runtimeProjectRootAligned: false,
                         promotionCriteriaPassed: 0,
                         promotionCriteriaTotal: 0,
                         promotionBlockerIds: [],
diff --git a/src/frontend/locales/en.json b/src/frontend/locales/en.json
@@ -282,7 +282,7 @@
       "learningQualitySnapshotFailed": "Learning quality snapshot request failed.",
       "learningQualitySnapshotLoaded": "Learning quality snapshot loaded (retest {retestPassRatePct}%, recurrence {misconceptionRecurrenceRatePct}%).",
       "foundationReadinessFailed": "Foundation readiness request failed.",
-      "foundationReadinessLoaded": "Foundation readiness {status} / {decision} (store {storeType}, graph {graphBackendStatus}/{graphBackendSignalKind}, graph-independent {graphBackendIndependent}, backend {queryBackendDefaultMode}, signals {queryBackendScoreSignals}, vector {vectorAdapterStatus}, signal-kind {vectorAdapterSignalKind}, independent {vectorAdapterIndependent}, linked {vectorAdapterLinkedIntoQueryBackend}, criteria {promotionCriteriaPassed}/{promotionCriteriaTotal}, blockers {promotionBlockerIds}).",
+      "foundationReadinessLoaded": "Foundation readiness {status} / {decision} (store {storeType}, graph {graphBackendStatus}/{graphBackendSignalKind}, graph-independent {graphBackendIndependent}, backend {queryBackendDefaultMode}, signals {queryBackendScoreSignals}, vector {vectorAdapterStatus}, signal-kind {vectorAdapterSignalKind}, independent {vectorAdapterIndependent}, linked {vectorAdapterLinkedIntoQueryBackend}, repo-source {repoRootSource}, aligned {runtimeProjectRootAligned}, criteria {promotionCriteriaPassed}/{promotionCriteriaTotal}, blockers {promotionBlockerIds}).",
       "memoryPolicyFailed": "Memory snapshot request failed.",
       "memoryPolicyLoaded": "Memory snapshot loaded ({layer}/{operation}): {entriesCount} entries, evicted {evictedCount}, totals session {sessionCount}, unit {unitCount}, long-term {longTermCount}, recommended {recommendedActionsCount} actions."
     }
diff --git a/src/frontend/locales/zh.json b/src/frontend/locales/zh.json
diff --git a/src/learning/KnowledgeLearningPlatform.test.ts b/src/learning/KnowledgeLearningPlatform.test.ts
diff --git a/src/learning/KnowledgeLearningPlatform.ts b/src/learning/KnowledgeLearningPlatform.ts
diff --git a/src/learning/types.ts b/src/learning/types.ts
diff --git a/src/server.migration.test.ts b/src/server.migration.test.ts
