feat: surface foundation readiness signal semantics

Author: Jacobinwwey

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

@@ -193,6 +193,11 @@ This document re-baselines current mainline truth on 2026-04-19, records what ch
   - readiness now reports `queryBackendDefaultMode`
   - readiness now reports `vectorAdapterLinkedIntoQueryBackend`
   - operator UI and diagnostics snapshots expose the same linkage evidence, while overall status still remains `in_progress` / `no-go`.
+- The next bounded execution slice after that makes current signal semantics explicit without flipping readiness:
+  - readiness now reports `queryBackendScoreSignals`
+  - readiness now reports `vectorAdapterSignalKind`
+  - current mainline truth is now machine-readable as lexical-prefilter semantics rather than an ambiguous "vector" label
+  - overall status still remains `in_progress` / `no-go`, because lexical overlap evidence is still not ANN evidence.
 - Current expected outcome on `main` remains:
   - status `in_progress`
   - decision `no-go`

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

@@ -258,6 +258,23 @@ Execution anchor:
   - failing references: `24405317254`, `24404975285`,
   - recovered run: `24502592419` (`Migration Gates` all green, including runtime/browser/tauri agent-workspace suites).
 
+## Latest Mainline Increment (2026-04-20 M8.9 Foundation Signal-Semantics Evidence)
+
+- Strengthened foundation-readiness evidence without changing the readiness verdict:
+  - `FoundationReadinessReport.baseline` now includes `queryBackendScoreSignals`,
+  - `FoundationReadinessReport.baseline` now includes `vectorAdapterSignalKind`.
+- Mainline readiness payload now makes current retrieval semantics explicit instead of leaving them implied:
+  - query backend scoring currently exposes `keyword_matches`, `title_match_bonus`, `vector_prefilter_content_bonus`, and `relation_bonus`,
+  - vector acceleration currently reports `lexical_token_overlap`, which confirms a lexical prefilter stage rather than embedding-backed ANN retrieval.
+- Operator/runtime inspectability stayed aligned with the typed/report layer:
+  - `scripts/verify-foundation-readiness.js` prints the new signal fields,
+  - `src/frontend/agent_workspace_runtime.js` persists the same fields in `lastFoundationReadiness`,
+  - the toolbar summary now includes both the score-signal list and the vector signal kind.
+- Guardrail remains unchanged on `main`:
+  - status stays `in_progress`,
+  - decision stays `no-go`,
+  - no ANN readiness claim is permitted from lexical-prefilter evidence alone.
+
 ## 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

@@ -58,9 +58,17 @@ Bundle note:
   - rationale: file-backed baseline exists, query-backend and vector-boundary modules are now present, but the vector adapter is still only `prefilter_only`, so independent ANN evidence is still absent.
 - The readiness payload now makes that distinction explicit:
   - `queryBackendDefaultMode`
+  - `queryBackendScoreSignals`
   - `vectorAdapterLinkedIntoQueryBackend`
   - `vectorAdapterStatus`
+  - `vectorAdapterSignalKind`
   - `vectorAdapterIndependent`
+- Current expected signal semantics on `main` are:
+  - `queryBackendScoreSignals = [keyword_matches, title_match_bonus, vector_prefilter_content_bonus, relation_bonus]`
+  - `vectorAdapterSignalKind = lexical_token_overlap`
+- Interpretation rule:
+  - `lexical_token_overlap` is evidence of lexical prefilter scoring only.
+  - It is **not** evidence of embedding-backed ANN readiness.
 
 ## Non-overclaim Policy
 

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

@@ -258,6 +258,23 @@
   - 历史失败参考：`24405317254`、`24404975285`，
   - 修复后运行：`24502592419`（`Migration Gates` 全绿，含 runtime/browser/tauri 三个 agent-workspace 套件）。
 
+## 主线最新增量（2026-04-20 M8.9 Foundation 信号语义证据）
+
+- 在不改变 readiness 结论的前提下，补强了 foundation-readiness 证据面：
+  - `FoundationReadinessReport.baseline` 新增 `queryBackendScoreSignals`，
+  - `FoundationReadinessReport.baseline` 新增 `vectorAdapterSignalKind`。
+- 主线 readiness 载荷现在把当前检索语义显式写出，而不是让执行侧自行猜测：
+  - query backend 当前打分信号为 `keyword_matches`、`title_match_bonus`、`vector_prefilter_content_bonus`、`relation_bonus`，
+  - vector acceleration 当前信号类型为 `lexical_token_overlap`，这只说明“词法预过滤”阶段存在，不等于 embedding/ANN 检索已经落地。
+- 执行侧/运行时可观测性保持与 typed/report 层一致：
+  - `scripts/verify-foundation-readiness.js` 现在输出新信号字段，
+  - `src/frontend/agent_workspace_runtime.js` 会在 `lastFoundationReadiness` 中保留同样字段，
+  - 工具栏摘要消息现在会同时展示打分信号列表与向量信号类型。
+- `main` 上的护栏结论保持不变：
+  - 状态仍为 `in_progress`，
+  - 决策仍为 `no-go`，
+  - 不能把 lexical-prefilter 证据误写成 ANN readiness。
+
 ## 主线最新增量（2026-04-16 M7.2 运行时证据加深链路）
 
 - 已在 `src/agent_workspace.runtime.behavior.test.ts` 扩展 pane 生命周期证据覆盖：

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

@@ -58,9 +58,17 @@
   - 原因：file-backed 基线已存在，query-backend 与 vector 边界都已进入主线，但该 vector adapter 仍只是 `prefilter_only`，独立 ANN 证据仍未进入主线。
 - readiness 载荷现在也显式区分这层语义：
   - `queryBackendDefaultMode`
+  - `queryBackendScoreSignals`
   - `vectorAdapterLinkedIntoQueryBackend`
   - `vectorAdapterStatus`
+  - `vectorAdapterSignalKind`
   - `vectorAdapterIndependent`
+- 当前 `main` 的预期信号语义为：
+  - `queryBackendScoreSignals = [keyword_matches, title_match_bonus, vector_prefilter_content_bonus, relation_bonus]`
+  - `vectorAdapterSignalKind = lexical_token_overlap`
+- 解读规则：
+  - `lexical_token_overlap` 只表示词法预过滤打分存在。
+  - 它**不等于** embedding/ANN readiness 已经成立。
 
 ## 防超前宣称策略
 

scripts/foundation-readiness-utils.js

@@ -51,6 +51,23 @@ function resolveQueryBackendDefaultMode(queryBackendSource, graphAdapterModulePr
   return 'unknown';
 }
 
+function resolveQueryBackendScoreSignals(queryBackendSource, graphAdapterModulePresent) {
+  if (!graphAdapterModulePresent) {
+    return [];
+  }
+
+  const signalChecks = [
+    ['keyword_matches', /\bkeywordMatches\b/],
+    ['title_match_bonus', /\btitleMatchBonus\b/],
+    ['vector_prefilter_content_bonus', /\bcontentMatchBonus\b/],
+    ['relation_bonus', /\brelationBonus\b/],
+  ];
+
+  return signalChecks
+    .filter(([, pattern]) => pattern.test(queryBackendSource))
+    .map(([signal]) => signal);
+}
+
 function resolveVectorAdapterLinkedIntoQueryBackend(queryBackendSource, graphAdapterModulePresent) {
   if (!graphAdapterModulePresent) {
     return false;
@@ -60,6 +77,31 @@ function resolveVectorAdapterLinkedIntoQueryBackend(queryBackendSource, graphAda
     && queryBackendSource.includes('vectorAccelerationAdapter.accelerate');
 }
 
+function resolveVectorAdapterSignalKind(vectorAdapterSource, vectorAdapterModulePresent) {
+  if (!vectorAdapterModulePresent) {
+    return 'absent';
+  }
+
+  if (
+    /lexicalTokenMatches/.test(vectorAdapterSource)
+    || /lexicalTokenScore/.test(vectorAdapterSource)
+  ) {
+    return 'lexical_token_overlap';
+  }
+
+  if (
+    /embedding/i.test(vectorAdapterSource)
+    || /\bann\b/i.test(vectorAdapterSource)
+    || /approximate nearest/i.test(vectorAdapterSource)
+    || /hnsw/i.test(vectorAdapterSource)
+    || /faiss/i.test(vectorAdapterSource)
+  ) {
+    return 'embedding_ann';
+  }
+
+  return 'unknown';
+}
+
 function evaluateFoundationReadiness(options = {}) {
   const repoRoot = options.repoRoot || path.resolve(__dirname, '..');
   const packageJson = readJsonIfExists(path.join(repoRoot, 'package.json'));
@@ -113,8 +155,16 @@ function evaluateFoundationReadiness(options = {}) {
     && storeSource.includes("storeType: 'file'");
   const graphAdapterModulePresent = fileExists(graphAdapterPath);
   const queryBackendDefaultMode = resolveQueryBackendDefaultMode(queryBackendSource, graphAdapterModulePresent);
+  const queryBackendScoreSignals = resolveQueryBackendScoreSignals(
+    queryBackendSource,
+    graphAdapterModulePresent
+  );
   const vectorAdapterModulePresent = fileExists(vectorAdapterPath);
   const vectorAdapterStatus = resolveVectorAdapterStatus(vectorAdapterSource, vectorAdapterModulePresent);
+  const vectorAdapterSignalKind = resolveVectorAdapterSignalKind(
+    vectorAdapterSource,
+    vectorAdapterModulePresent
+  );
   const vectorAdapterIndependent = vectorAdapterStatus === 'independent';
   const vectorAdapterLinkedIntoQueryBackend = resolveVectorAdapterLinkedIntoQueryBackend(
     queryBackendSource,
@@ -222,8 +272,10 @@ function evaluateFoundationReadiness(options = {}) {
       fileBackedStore,
       graphAdapterModulePresent,
       queryBackendDefaultMode,
+      queryBackendScoreSignals,
       vectorAdapterModulePresent,
       vectorAdapterStatus,
+      vectorAdapterSignalKind,
       vectorAdapterIndependent,
       vectorAdapterLinkedIntoQueryBackend,
     },
@@ -255,8 +307,10 @@ function formatFoundationReadinessMarkdown(result, reportPaths) {
     `- File-backed store evidence: ${result.baseline.fileBackedStore ? 'yes' : 'no'}`,
     `- Dedicated graph adapter module present: ${result.baseline.graphAdapterModulePresent ? 'yes' : 'no'}`,
     `- Query backend default mode: ${result.baseline.queryBackendDefaultMode}`,
+    `- Query backend score signals: ${result.baseline.queryBackendScoreSignals.join(', ') || 'none'}`,
     `- Dedicated vector adapter module present: ${result.baseline.vectorAdapterModulePresent ? 'yes' : 'no'}`,
     `- Vector adapter status: ${result.baseline.vectorAdapterStatus}`,
+    `- Vector adapter signal kind: ${result.baseline.vectorAdapterSignalKind}`,
     `- Vector adapter independent: ${result.baseline.vectorAdapterIndependent ? 'yes' : 'no'}`,
     `- Vector adapter linked into query backend: ${result.baseline.vectorAdapterLinkedIntoQueryBackend ? 'yes' : 'no'}`,
     '',

scripts/verify-foundation-readiness.js

@@ -21,10 +21,14 @@ function printHumanReport(result, reportPaths) {
     `[Foundation Readiness] Dedicated graph adapter present: ${result.baseline.graphAdapterModulePresent ? 'yes' : 'no'}`
   );
   console.log(`[Foundation Readiness] Query backend default mode: ${result.baseline.queryBackendDefaultMode}`);
+  console.log(
+    `[Foundation Readiness] Query backend score signals: ${result.baseline.queryBackendScoreSignals.join(', ') || 'none'}`
+  );
   console.log(
     `[Foundation Readiness] Dedicated vector adapter present: ${result.baseline.vectorAdapterModulePresent ? 'yes' : 'no'}`
   );
   console.log(`[Foundation Readiness] Vector adapter status: ${result.baseline.vectorAdapterStatus}`);
+  console.log(`[Foundation Readiness] Vector adapter signal kind: ${result.baseline.vectorAdapterSignalKind}`);
   console.log(
     `[Foundation Readiness] Vector adapter independent: ${result.baseline.vectorAdapterIndependent ? 'yes' : 'no'}`
   );

src/agent_workspace.runtime.behavior.test.ts

@@ -1666,8 +1666,15 @@ describe('agent workspace runtime behavior', () => {
                         fileBackedStore: true,
                         graphAdapterModulePresent: true,
                         queryBackendDefaultMode: 'local_hybrid',
+                        queryBackendScoreSignals: [
+                            'keyword_matches',
+                            'title_match_bonus',
+                            'vector_prefilter_content_bonus',
+                            'relation_bonus',
+                        ],
                         vectorAdapterModulePresent: true,
                         vectorAdapterStatus: 'prefilter_only',
+                        vectorAdapterSignalKind: 'lexical_token_overlap',
                         vectorAdapterIndependent: false,
                         vectorAdapterLinkedIntoQueryBackend: true,
                     },
@@ -1710,6 +1717,7 @@ describe('agent workspace runtime behavior', () => {
         expect(messages.textContent || '').toContain('Foundation readiness');
         expect(messages.textContent || '').toContain('prefilter_only');
         expect(messages.textContent || '').toContain('local_hybrid');
+        expect(messages.textContent || '').toContain('lexical_token_overlap');
 
         const snapshot = runtime.getDiagnosticsSnapshot();
         expect(snapshot.lastFoundationReadiness).toEqual(
@@ -1718,7 +1726,14 @@ describe('agent workspace runtime behavior', () => {
                 decision: 'no-go',
                 storeType: 'file',
                 queryBackendDefaultMode: 'local_hybrid',
+                queryBackendScoreSignals: [
+                    'keyword_matches',
+                    'title_match_bonus',
+                    'vector_prefilter_content_bonus',
+                    'relation_bonus',
+                ],
                 vectorAdapterStatus: 'prefilter_only',
+                vectorAdapterSignalKind: 'lexical_token_overlap',
                 vectorAdapterIndependent: false,
                 vectorAdapterLinkedIntoQueryBackend: true,
                 recommendationsCount: 1,

src/foundation.readiness.contract.test.ts

@@ -16,8 +16,10 @@ type FoundationReadinessResult = {
     fileBackedStore: boolean;
     graphAdapterModulePresent: boolean;
     queryBackendDefaultMode: 'absent' | 'unknown' | 'local_hybrid' | 'keyword_only';
+    queryBackendScoreSignals: string[];
     vectorAdapterModulePresent: boolean;
     vectorAdapterStatus: 'absent' | 'prefilter_only' | 'independent';
+    vectorAdapterSignalKind: 'absent' | 'unknown' | 'lexical_token_overlap' | 'embedding_ann';
     vectorAdapterIndependent: boolean;
     vectorAdapterLinkedIntoQueryBackend: boolean;
   };
@@ -111,8 +113,15 @@ describe('foundation readiness contract', () => {
     expect(result.baseline.fileBackedStore).toBe(true);
     expect(result.baseline.graphAdapterModulePresent).toBe(true);
     expect(result.baseline.queryBackendDefaultMode).toBe('local_hybrid');
+    expect(result.baseline.queryBackendScoreSignals).toEqual([
+      'keyword_matches',
+      'title_match_bonus',
+      'vector_prefilter_content_bonus',
+      'relation_bonus',
+    ]);
     expect(result.baseline.vectorAdapterModulePresent).toBe(true);
     expect(result.baseline.vectorAdapterStatus).toBe('prefilter_only');
+    expect(result.baseline.vectorAdapterSignalKind).toBe('lexical_token_overlap');
     expect(result.baseline.vectorAdapterIndependent).toBe(false);
     expect(result.baseline.vectorAdapterLinkedIntoQueryBackend).toBe(true);
     expect(result.documents.checklistPagesPresent).toBe(true);
@@ -171,8 +180,10 @@ describe('foundation readiness contract', () => {
     expect(result.baseline.fileBackedStore).toBe(true);
     expect(result.baseline.graphAdapterModulePresent).toBe(true);
     expect(result.baseline.queryBackendDefaultMode).toBe('unknown');
+    expect(result.baseline.queryBackendScoreSignals).toEqual([]);
     expect(result.baseline.vectorAdapterModulePresent).toBe(true);
     expect(result.baseline.vectorAdapterStatus).toBe('independent');
+    expect(result.baseline.vectorAdapterSignalKind).toBe('unknown');
     expect(result.baseline.vectorAdapterIndependent).toBe(true);
     expect(result.baseline.vectorAdapterLinkedIntoQueryBackend).toBe(false);
     expect(result.documents.checklistPagesPresent).toBe(true);

src/frontend/agent_workspace_runtime.js

@@ -1434,7 +1434,9 @@
                     decision: '',
                     storeType: '',
                     queryBackendDefaultMode: '',
+                    queryBackendScoreSignals: [],
                     vectorAdapterStatus: '',
+                    vectorAdapterSignalKind: '',
                     vectorAdapterIndependent: false,
                     vectorAdapterLinkedIntoQueryBackend: false,
                     recommendationsCount: 0,
@@ -1463,22 +1465,31 @@
                         decision: trimString(readiness && readiness.decision),
                         storeType: trimString(baseline.storeType),
                         queryBackendDefaultMode: trimString(baseline.queryBackendDefaultMode),
+                        queryBackendScoreSignals: Array.isArray(baseline.queryBackendScoreSignals)
+                            ? baseline.queryBackendScoreSignals.map((entry) => trimString(entry)).filter(Boolean)
+                            : [],
                         vectorAdapterStatus: trimString(baseline.vectorAdapterStatus),
+                        vectorAdapterSignalKind: trimString(baseline.vectorAdapterSignalKind),
                         vectorAdapterIndependent: Boolean(baseline.vectorAdapterIndependent),
                         vectorAdapterLinkedIntoQueryBackend: Boolean(baseline.vectorAdapterLinkedIntoQueryBackend),
                         recommendationsCount,
                     };
+                    const queryBackendScoreSignals = Array.isArray(baseline.queryBackendScoreSignals)
+                        ? baseline.queryBackendScoreSignals.map((entry) => trimString(entry)).filter(Boolean)
+                        : [];
                     appendMessage(
                         'assistant',
                         getI18nText(
                             'agentWorkspace.messages.foundationReadinessLoaded',
-                            `Foundation readiness ${trimString(readiness && readiness.status) || 'unknown'} / ${trimString(readiness && readiness.decision) || 'unknown'} (store ${trimString(baseline.storeType) || 'n/a'}, backend ${trimString(baseline.queryBackendDefaultMode) || 'n/a'}, vector ${trimString(baseline.vectorAdapterStatus) || 'n/a'}, independent ${Boolean(baseline.vectorAdapterIndependent) ? 'yes' : 'no'}, linked ${Boolean(baseline.vectorAdapterLinkedIntoQueryBackend) ? 'yes' : 'no'}).`,
+                            `Foundation readiness ${trimString(readiness && readiness.status) || 'unknown'} / ${trimString(readiness && readiness.decision) || 'unknown'} (store ${trimString(baseline.storeType) || 'n/a'}, 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'}).`,
                             {
                                 status: trimString(readiness && readiness.status) || 'unknown',
                                 decision: trimString(readiness && readiness.decision) || 'unknown',
                                 storeType: trimString(baseline.storeType) || 'n/a',
                                 queryBackendDefaultMode: trimString(baseline.queryBackendDefaultMode) || 'n/a',
+                                queryBackendScoreSignals: queryBackendScoreSignals.join(', ') || 'none',
                                 vectorAdapterStatus: trimString(baseline.vectorAdapterStatus) || 'n/a',
+                                vectorAdapterSignalKind: trimString(baseline.vectorAdapterSignalKind) || 'n/a',
                                 vectorAdapterIndependent: Boolean(baseline.vectorAdapterIndependent) ? 'yes' : 'no',
                                 vectorAdapterLinkedIntoQueryBackend: Boolean(baseline.vectorAdapterLinkedIntoQueryBackend)
                                     ? 'yes'
@@ -1495,7 +1506,9 @@
                         decision: '',
                         storeType: '',
                         queryBackendDefaultMode: '',
+                        queryBackendScoreSignals: [],
                         vectorAdapterStatus: '',
+                        vectorAdapterSignalKind: '',
                         vectorAdapterIndependent: false,
                         vectorAdapterLinkedIntoQueryBackend: false,
                         recommendationsCount: 0,