knowledge-base-bootstrap

KnowledgeBase 初始化

概述

以目标项目的 cadence/knowledge-base/user-input/base-info.md 为唯一入口。先判定首次初始化、未完成初始化续跑、已完成保护或显式重新初始化，再校验六领域输入并按固定顺序编排领域 Skills。只生成和消费 Manifest Schema 4.0；输入不完整时返回模板和继续入口，不扩大扫描范围。

必读资源

• 执行前完整读取 references/input-contract.md。
• 缺失输入时引用 user-input/ 下的模板，不代替用户填写。
• 使用 assets/input-inventory-template.md 生成输入解析清单。
• 使用 assets/manifest-template.yaml 生成 Manifest。
• 需要核对典型判定时读取 references/demo.md。

固定输入

cadence/knowledge-base/user-input/
├── base-info.md
├── project-scope.md
├── data-model-scope.md
├── configuration-scope.md
├── middleware-scope.md
├── api-scope.md
├── page-scope.md
└── database-ddl.sql（可选）

用户输入和外部配置快照只读，不得覆盖、补写、复制或迁入知识库。

初始化状态不变量门禁

任何续跑、复用、领域调用、完成保护、显式重新初始化清理或 KnowledgeBase 写入前，都必须先只读校验 coverage.initialization。首次初始化尚无 Manifest 时，先在内存中构造符合本节约束的初始化块，六领域适用性确定后再写入；既有 Schema 4.0 Manifest 按以下规则处理：

1. 整个 coverage.initialization 块缺失是唯一兼容分支。不得依据登记或产物推断完成，必须先只读执行当前完整 global-validation，再根据实际验收结果一次性回填完整初始化块；验收和回填前不得续跑、复用领域结果、调用领域 Skill、执行完成保护或修改其他产物。
2. 初始化块存在时，必须同时满足以下全部不变量：
   • status 只能是 in_progress 或 complete；global_validation 只能是 pending、failed 或 passed。
   • completed_stages 是无重复字符串列表，元素只能是 base-info、api、pages、overview、global-validation。列表必须保持固定顺序，是固定阶段序列在跳过不适用领域后的合法前缀或子序列；前置阶段尚未完成或合法跳过时，不得出现后续阶段，global-validation 只能最后出现。
   • skipped_stages 是无重复对象列表，每项只能包含 stage 和 reason 两个键；stage 只能是 api 或 pages，reason 必须为非空字符串。同一阶段不得重复，不得与 completed_stages 重叠；base-info、overview、global-validation 永不可跳过。
   • scope.api.status: 不适用 时，api 必须且只能出现在 skipped_stages，不得出现在 completed_stages；接口适用时不得跳过。pages 按 scope.pages.status 使用同一规则。
   • status: in_progress 时，completed_at 必须为空，global_validation 只能是 pending 或 failed，completed_stages 不得包含 global-validation；已完成和已跳过阶段仍须满足固定顺序。
   • status: complete 当且仅当：base-info、overview、global-validation 已完成，适用的 api、pages 已完成，不适用的 api、pages 已正确跳过，global_validation: passed，completed_at 非空，并且所有实际适用产物、索引、Manifest 登记、服务导航和证据满足对应阶段及 global-validation 完成条件。
3. 初始化块存在但任一字段缺失、类型错误、值非法、重复、重叠、逆序、适用性不一致或完成状态与实际产物矛盾时，视为损坏状态。普通初始化、续跑、复用、领域调用、完成保护和 Update 必须立即停止且不修改任何产物；一次性报告每个异常字段的实际值、违反的不变量、受影响阶段和继续执行风险。不得把损坏状态当作续跑，不得自动补字段、重排、去重、改写状态。
4. 可解析且 schema_version: "4.0" 的 Manifest 存在损坏初始化块时，只有用户明确请求“重新初始化 Schema 4.0”才允许进入独立破坏性授权流程。先报告损坏字段实际值、无法信任现有初始化状态的影响，再列出拟清理的精确路径、人工内容丢失、Git/配置/变更历史基线失效风险和全量重建范围；必须取得用户针对上述精确范围与风险的再次明确授权。授权只允许继续执行清理前门禁，不能立即清理；此例外只绕过 initialization 不变量，不解释、不修复、不迁移损坏字段。Manifest 不可解析、缺少版本或版本不是 4.0 时仍禁止清理。
5. 除第 4 项的破坏性重建例外外，每次阶段状态变化及任何原子写入前重新执行本门禁；只有当前状态合法且待写入的新状态也满足不变量时才可提交。