docs(governance): close m7.3 readiness and anti-overclaim chain

Jacobinwwey · Jacobinwwey · commit 15c1fb88b7d0 · 2026-04-16T05:28:34.000-05:00
diff --git a/docs/brainstorms/2026-04-16-mainline-ci-stabilization-and-m7-direction-requirements.md b/docs/brainstorms/2026-04-16-mainline-ci-stabilization-and-m7-direction-requirements.md
@@ -175,6 +175,25 @@ Deliverables:
 - documented mainline preconditions for graphdb/ANN re-entry.
 - explicit non-goal statement preventing branch-only claims from entering mainline progress sections.
 
+#### M7.3 Progress Note (2026-04-16)
+
+- [Done] published bilingual foundation re-entry checklist pages:
+  - `docs/diataxis/en/explanation/foundation-reentry-readiness-checklist.md`
+  - `docs/diataxis/zh/explanation/foundation-reentry-readiness-checklist.md`
+- [Done] landed anti-overclaim language and status taxonomy:
+  - canonical status words: `Planned` / `In Progress` / `Integrated`,
+  - explicit forbidden-claim examples for pre-integration foundation updates.
+- [Done] bound checklist to executable Go/No-Go gates:
+  - `npm test -- src/knowledge.api.contract.test.ts --runInBand`
+  - `npm test -- src/learning/KnowledgeLearningPlatform.test.ts --runInBand`
+  - `npm test -- src/learning/KnowledgeLearningPlatform.persistence.test.ts --runInBand`
+  - `npm run test:agent-workspace:contracts`
+  - `npm run docs:diataxis:check && npm run docs:site:build`
+- [Done] updated docs visibility chain for stable discovery:
+  - `mkdocs.yml` nav entries (EN/ZH),
+  - `docs/diataxis-map.json` mapping,
+  - EN/ZH dashboard and roadmap references.
+
 ## Success Criteria
 
 - CI failure mode that previously blocked the three agent-workspace suites is eliminated on mainline.
diff --git a/docs/diataxis-map.json b/docs/diataxis-map.json
@@ -194,6 +194,18 @@
         "diataxis": "docs/diataxis/zh/explanation/knowledge-mastery-evolution-roadmap.md"
       }
     },
+    {
+      "id": "foundation-reentry-readiness-checklist",
+      "category": "explanation",
+      "en": {
+        "canonical": ["docs/brainstorms/2026-04-16-mainline-ci-stabilization-and-m7-direction-requirements.md", "src/learning/store.ts", "src/learning/KnowledgeLearningPlatform.ts", "src/knowledge.api.contract.test.ts", ".github/workflows/migration-gates.yml"],
+        "diataxis": "docs/diataxis/en/explanation/foundation-reentry-readiness-checklist.md"
+      },
+      "zh": {
+        "canonical": ["docs/brainstorms/2026-04-16-mainline-ci-stabilization-and-m7-direction-requirements.md", "src/learning/store.ts", "src/learning/KnowledgeLearningPlatform.ts", "src/knowledge.api.contract.test.ts", ".github/workflows/migration-gates.yml"],
+        "diataxis": "docs/diataxis/zh/explanation/foundation-reentry-readiness-checklist.md"
+      }
+    },
     {
       "id": "development-progress-dashboard",
       "category": "explanation",
diff --git a/docs/diataxis/en/explanation/development-progress-dashboard.md b/docs/diataxis/en/explanation/development-progress-dashboard.md
@@ -269,6 +269,20 @@ Execution anchor:
 - Verification evidence:
   - `npm test -- src/agent_workspace.runtime.behavior.test.ts --runInBand`
 
+## Latest Mainline Increment (2026-04-16 M7.3 Foundation Re-entry Readiness Lane)
+
+- Added a bilingual foundation re-entry checklist page:
+  - `docs/diataxis/en/explanation/foundation-reentry-readiness-checklist.md`
+  - `docs/diataxis/zh/explanation/foundation-reentry-readiness-checklist.md`
+- Added explicit anti-overclaim status language (`Planned` / `In Progress` / `Integrated`) and forbidden-claim examples for foundation lane updates.
+- Added Go/No-Go gate matrix tied to executable checks:
+  - `npm test -- src/knowledge.api.contract.test.ts --runInBand`
+  - `npm test -- src/learning/KnowledgeLearningPlatform.test.ts --runInBand`
+  - `npm test -- src/learning/KnowledgeLearningPlatform.persistence.test.ts --runInBand`
+  - `npm run test:agent-workspace:contracts`
+  - `npm run docs:diataxis:check && npm run docs:site:build`
+- Updated docs navigation and Diataxis map for stable web visibility.
+
 ## Mainline vs Working-Branch Snapshot (2026-04-14)
 
 | Capability Slice | Working Branch (`feat/learning-multi-tutor-adapter`) | Mainline (`origin/main`) | Integration Status |
@@ -369,6 +383,7 @@ Note: do not list foundation-lane gates as baseline until the corresponding modu
 ## Related Pages
 
 - [Knowledge Mastery Evolution Roadmap](./knowledge-mastery-evolution-roadmap.md)
+- [Foundation Re-entry Readiness Checklist](./foundation-reentry-readiness-checklist.md)
 - [Agent Conversation + Focus Mode Delivery Plan](./agent-conversation-focus-mode-plan.md)
 - [DeepTutor Reuse Assessment](./deeptutor-reuse-assessment.md)
 - [MemOS Reuse Assessment](./memos-reuse-assessment.md)
diff --git a/docs/diataxis/en/explanation/foundation-reentry-readiness-checklist.md b/docs/diataxis/en/explanation/foundation-reentry-readiness-checklist.md
@@ -0,0 +1,85 @@
+# Explanation: Foundation Re-entry Readiness Checklist
+
+This page defines the **Go/No-Go contract** for re-entering the foundation lane (graph persistence depth + retrieval backend depth) after M7 interaction-lane stabilization.
+
+## Objective
+
+Prevent branch-only assumptions from being promoted to mainline facts.
+Foundation work may proceed only when code, tests, CI, and docs all satisfy the same evidence threshold.
+
+## Mainline Baseline (2026-04-16)
+
+- Mainline persistence baseline remains file-backed snapshot storage:
+  - `src/learning/store.ts`
+- Mainline learning/runtime contract currently centers on:
+  - `src/learning/api.ts`
+  - `src/learning/types.ts`
+  - `src/learning/KnowledgeLearningPlatform.ts`
+  - `src/server.ts`
+- Active interaction lane is stable and CI-protected:
+  - `src/agent_workspace.contract.parity.test.ts`
+  - `src/agent_workspace.runtime.behavior.test.ts`
+  - `.github/workflows/migration-gates.yml`
+
+Implication:
+
+- foundation re-entry is allowed,
+- foundation overclaim is not allowed.
+
+## Re-entry Gate Matrix
+
+All gates below must pass before calling foundation lane "active on mainline".
+
+| Gate Class | Required Evidence | Mandatory Check |
+|---|---|---|
+| Contract gate | New/changed foundation capability is represented in `src/learning/types.ts` and `src/learning/api.ts` without undocumented behavior | `npm test -- src/knowledge.api.contract.test.ts --runInBand` |
+| Core behavior gate | Learning core behavior remains valid under foundation change | `npm test -- src/learning/KnowledgeLearningPlatform.test.ts --runInBand` |
+| Persistence safety gate | Snapshot restore/save behavior remains deterministic | `npm test -- src/learning/KnowledgeLearningPlatform.persistence.test.ts --runInBand` |
+| Interaction non-regression gate | L4 interaction lane remains stable after foundation code touches | `npm run test:agent-workspace:contracts` |
+| CI gate | Migration matrix remains green on mainline after merge | `.github/workflows/migration-gates.yml` run status on `main` |
+| Documentation gate | EN/ZH progress dashboard and this checklist updated with exact status language | `npm run docs:diataxis:check && npm run docs:site:build` |
+
+## Non-overclaim Policy
+
+Use these status words consistently:
+
+- `Planned`: no mainline code evidence yet.
+- `In Progress`: mainline code exists but one or more mandatory gates still failing or missing.
+- `Integrated`: all mandatory gates passing on mainline CI.
+
+Forbidden statements before integration:
+
+- "GraphDB lane completed"
+- "Vector backend production-ready"
+- "Foundation closure done"
+
+Allowed statements before integration:
+
+- "Foundation lane design finalized"
+- "Foundation lane prototype exists"
+- "Foundation lane staged for mainline integration"
+
+## Decision Checklist (Operator View)
+
+Mark each as `Yes` before declaring re-entry complete:
+
+1. Mainline diff is scoped to foundation changes and bounded migration impact.
+2. Contract gate and core behavior gate both pass locally.
+3. Persistence safety gate passes locally with no snapshot compatibility regression.
+4. Interaction non-regression gate passes locally.
+5. Docs gate passes locally and EN/ZH pages reflect exact status.
+6. Post-push `Migration Gates` run on `main` is green.
+
+If any answer is `No`, decision is `No-Go`.
+
+## Mandatory Deliverables for M7.3 Closure
+
+- This checklist published in EN/ZH Diataxis explanation pages.
+- Progress dashboards include explicit reference to this checklist.
+- Brainstorm baseline (`2026-04-16 mainline CI stabilization and M7 direction`) includes M7.3 progress note and anti-overclaim guardrails.
+
+## Related Pages
+
+- [Development Progress Dashboard](./development-progress-dashboard.md)
+- [Knowledge Mastery Evolution Roadmap](./knowledge-mastery-evolution-roadmap.md)
+- [Mainline CI Stabilization and M7 Direction Requirements](../../../brainstorms/2026-04-16-mainline-ci-stabilization-and-m7-direction-requirements.md)
diff --git a/docs/diataxis/en/explanation/knowledge-mastery-evolution-roadmap.md b/docs/diataxis/en/explanation/knowledge-mastery-evolution-roadmap.md
@@ -71,8 +71,10 @@ This requires:
 ## Progress Tracking Entry
 
 - [Development Progress Dashboard](./development-progress-dashboard.md)
+- [Foundation Re-entry Readiness Checklist](./foundation-reentry-readiness-checklist.md)
 
 Use this page as the execution view (layer matrix, debug runbook, and priority backlog).
+Use the readiness checklist as the mandatory Go/No-Go gate before marking foundation lane active on mainline.
 
 ## Canonical Plan and Baseline Sources
 
diff --git a/docs/diataxis/zh/explanation/development-progress-dashboard.md b/docs/diataxis/zh/explanation/development-progress-dashboard.md
@@ -269,6 +269,22 @@
 - 验证证据：
   - `npm test -- src/agent_workspace.runtime.behavior.test.ts --runInBand`
 
+## 主线最新增量（2026-04-16 M7.3 Foundation 回归就绪链路）
+
+- 已新增中英双语 Foundation 回归就绪检查清单：
+  - `docs/diataxis/en/explanation/foundation-reentry-readiness-checklist.md`
+  - `docs/diataxis/zh/explanation/foundation-reentry-readiness-checklist.md`
+- 已明确防超前宣称状态词与约束：
+  - 状态词固定为 `Planned` / `In Progress` / `Integrated`，
+  - 明确禁止将分支原型描述为主线已集成事实。
+- 已新增 Go/No-Go 门禁矩阵并绑定可执行检查：
+  - `npm test -- src/knowledge.api.contract.test.ts --runInBand`
+  - `npm test -- src/learning/KnowledgeLearningPlatform.test.ts --runInBand`
+  - `npm test -- src/learning/KnowledgeLearningPlatform.persistence.test.ts --runInBand`
+  - `npm run test:agent-workspace:contracts`
+  - `npm run docs:diataxis:check && npm run docs:site:build`
+- 已同步导航与 Diataxis 映射，保证文档页面稳定可访问。
+
 ## 主线 vs 工作分支快照（2026-04-14）
 
 | 能力切片 | 工作分支（`feat/learning-multi-tutor-adapter`） | 主线（`origin/main`） | 集成状态 |
@@ -369,6 +385,7 @@ npm test -- src/learning/KnowledgeLearningPlatform.persistence.test.ts --runInBa
 ## 关联页面
 
 - [知识彻底掌握演进路线图](./knowledge-mastery-evolution-roadmap.md)
+- [Foundation 回归就绪检查清单](./foundation-reentry-readiness-checklist.md)
 - [Agent 对话 + Focus Mode 交付方案](./agent-conversation-focus-mode-plan.md)
 - [DeepTutor 复用评估](./deeptutor-reuse-assessment.md)
 - [MemOS 复用评估](./memos-reuse-assessment.md)
diff --git a/docs/diataxis/zh/explanation/foundation-reentry-readiness-checklist.md b/docs/diataxis/zh/explanation/foundation-reentry-readiness-checklist.md
@@ -0,0 +1,85 @@
+# 解释：Foundation 回归就绪检查清单
+
+本页定义 M7 交互链路稳定化后，foundation lane（图存储深度 + 检索后端深度）回归时的 **Go/No-Go 契约**。
+
+## 目标
+
+避免把分支假设升级为主线事实。
+只有当代码、测试、CI、文档同时满足同一证据阈值时，foundation lane 才能进入主线“已集成”状态。
+
+## 主线基线现实（2026-04-16）
+
+- 主线持久化基线仍是 file-backed snapshot：
+  - `src/learning/store.ts`
+- 主线学习/运行时契约核心仍是：
+  - `src/learning/api.ts`
+  - `src/learning/types.ts`
+  - `src/learning/KnowledgeLearningPlatform.ts`
+  - `src/server.ts`
+- 当前交互链路已稳定并受 CI 保护：
+  - `src/agent_workspace.contract.parity.test.ts`
+  - `src/agent_workspace.runtime.behavior.test.ts`
+  - `.github/workflows/migration-gates.yml`
+
+结论：
+
+- 可以回归 foundation lane，
+- 不能超前宣称 foundation 已闭环。
+
+## 回归门禁矩阵
+
+以下门禁全部通过后，才能将 foundation lane 标记为“主线已激活”。
+
+| 门禁类别 | 必要证据 | 强制检查 |
+|---|---|---|
+| 契约门禁 | foundation 新增/变更能力必须在 `src/learning/types.ts` 与 `src/learning/api.ts` 中显式表达，且行为文档化 | `npm test -- src/knowledge.api.contract.test.ts --runInBand` |
+| 核心行为门禁 | foundation 变更后学习核心行为保持正确 | `npm test -- src/learning/KnowledgeLearningPlatform.test.ts --runInBand` |
+| 持久化安全门禁 | snapshot 恢复/保存语义保持确定性 | `npm test -- src/learning/KnowledgeLearningPlatform.persistence.test.ts --runInBand` |
+| 交互无回归门禁 | foundation 触点变更后 L4 交互链路仍稳定 | `npm run test:agent-workspace:contracts` |
+| CI 门禁 | 合并后主线 migration 矩阵全绿 | `.github/workflows/migration-gates.yml` 在 `main` 的运行结果 |
+| 文档门禁 | EN/ZH 进度看板与本清单同步更新，状态语言一致 | `npm run docs:diataxis:check && npm run docs:site:build` |
+
+## 防超前宣称策略
+
+状态词统一使用：
+
+- `Planned`：主线尚无代码证据。
+- `In Progress`：主线已有代码，但一个或多个强制门禁仍未通过或缺失。
+- `Integrated`：全部强制门禁通过，且主线 CI 已验证。
+
+以下表述在未集成前禁止出现：
+
+- “GraphDB lane completed”
+- “Vector backend production-ready”
+- “Foundation closure done”
+
+以下表述在未集成前允许出现：
+
+- “Foundation lane design finalized”
+- “Foundation lane prototype exists”
+- “Foundation lane staged for mainline integration”
+
+## 决策检查清单（执行视角）
+
+下列项全部为 `Yes` 才能判定回归完成：
+
+1. 主线差异集中在 foundation 变更，迁移影响边界清晰。
+2. 契约门禁与核心行为门禁本地通过。
+3. 持久化安全门禁本地通过，且无 snapshot 兼容性回归。
+4. 交互无回归门禁本地通过。
+5. 文档门禁本地通过，且 EN/ZH 状态描述一致。
+6. 推送后 `main` 的 `Migration Gates` 全绿。
+
+任一项为 `No`，决策即为 `No-Go`。
+
+## M7.3 必要交付
+
+- 本清单在 Diataxis EN/ZH explanation 双语页面可访问。
+- 进度看板已显式引用本清单。
+- `2026-04-16` 主线方向文档已补 M7.3 进展与防超前宣称规则。
+
+## 关联页面
+
+- [开发进度看板](./development-progress-dashboard.md)
+- [知识彻底掌握演进路线图](./knowledge-mastery-evolution-roadmap.md)
+- [2026-04-16 主线 CI 稳定化与 M7 方向要求](../../../brainstorms/2026-04-16-mainline-ci-stabilization-and-m7-direction-requirements.md)
diff --git a/docs/diataxis/zh/explanation/knowledge-mastery-evolution-roadmap.md b/docs/diataxis/zh/explanation/knowledge-mastery-evolution-roadmap.md
@@ -70,8 +70,10 @@
 ## 进度跟踪入口
 
 - [开发进度看板](./development-progress-dashboard.md)
+- [Foundation 回归就绪检查清单](./foundation-reentry-readiness-checklist.md)
 
 该页面提供执行视角：分层矩阵、调试 Runbook、优先级待办。
+在将 foundation lane 标记为主线激活前，必须先通过该回归就绪清单的 Go/No-Go 门禁。
 
 ## 权威计划与基线来源
 
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -74,6 +74,7 @@ nav:
           - Startup Node Update Acceleration Plan: diataxis/en/explanation/startup-node-update-acceleration-plan.md
           - Knowledge Mastery Evolution Roadmap: diataxis/en/explanation/knowledge-mastery-evolution-roadmap.md
           - Development Progress Dashboard: diataxis/en/explanation/development-progress-dashboard.md
+          - Foundation Re-entry Readiness Checklist: diataxis/en/explanation/foundation-reentry-readiness-checklist.md
           - Agent Conversation + Focus Mode Delivery Plan: diataxis/en/explanation/agent-conversation-focus-mode-plan.md
           - DeepTutor Reuse Assessment: diataxis/en/explanation/deeptutor-reuse-assessment.md
           - MemOS Reuse Assessment: diataxis/en/explanation/memos-reuse-assessment.md
@@ -101,6 +102,7 @@ nav:
           - 启动节点更新提速方案: diataxis/zh/explanation/startup-node-update-acceleration-plan.md
           - 知识彻底掌握演进路线图: diataxis/zh/explanation/knowledge-mastery-evolution-roadmap.md
           - 开发进度看板: diataxis/zh/explanation/development-progress-dashboard.md
+          - Foundation 回归就绪检查清单: diataxis/zh/explanation/foundation-reentry-readiness-checklist.md
           - Agent 对话与 Focus Mode 交付方案: diataxis/zh/explanation/agent-conversation-focus-mode-plan.md
           - DeepTutor 复用评估: diataxis/zh/explanation/deeptutor-reuse-assessment.md
           - MemOS 复用评估: diataxis/zh/explanation/memos-reuse-assessment.md
