frontend-project-context 1.3.0 → 1.6.0

package/docs/USER-AND-AI-OPERATION-MANUAL.md

@@ -0,0 +1,797 @@
+# Frontend Project Context 操作手册
+
+> 适用版本：`frontend-project-context@1.3.1`
+>
+> 适用对象：项目维护者、开发者、使用 Codex / Claude / Cursor / 其他 Coding Agent 的团队，以及集成该 CLI 的 AI Host Agent。
+>
+> 文档定位：本文是从当前产品合同和已发布 CLI 行为整理出的使用手册，不是新的产品真源。如有冲突，按“产品宪法 → `PROJECT_STATE.json` → CLI `--help` 与机器 schema → 本手册”的顺序判断。
+
+## 1. 先理解它是什么
+
+Frontend Project Context 是放在项目与现有 AI 编程工具之间的、模型无关的上下文治理与交换层。
+
+它负责：
+
+- 把项目明确提供的文件、配置、路径和人工决定登记成可追溯来源；
+- 把事实、规则、引用和验证说明收敛为唯一的 `Project Contract`；
+- 按目录、文件或任务生成最小的 `Context Bundle`；
+- 向 AGENTS / Markdown / Ruler 生成受管投影；
+- 检测来源、合同和投影漂移；
+- 把 AI 建议收敛为无权限 `Action Plan`，再生成只读 `Review Bundle`；
+- 为长任务生成分阶段上下文，并校验跨窗口交接工件。
+
+它不负责：
+
+- 调用任何模型 Provider；
+- 充当 Agent Runtime；
+- 规划、执行或自动修复真实开发任务；
+- 修改业务代码；
+- 管理 Git、分支、提交、合并、PR 或发布；
+- 自动安装依赖、访问网络、自动批准或静默解决冲突。
+
+最重要的区分是：**CLI 负责“上下文治理和安全交换”，现有 Coding Agent 才负责“在人类授权下完成开发任务”。**
+
+## 2. 三条底层原则
+
+### 2.1 只有一份长期真源
+
+`.project-context/contract.json` 是项目给 AI 的唯一已批准长期指导。生成的 `AGENTS.md`、Ruler 文件、Context Bundle、Assist Bundle、Action Plan、Review Bundle、Stage Receipt 都不是第二份真源。
+
+### 2.2 默认只读，写入只对当前命令生效
+
+所有命令默认只读。只有当前命令显式带有 `--write` 才允许持久写入。
+
+“上次同意了”、“继续做”、“自己处理”不能自动扩张成新 ID、新路径或新 baseline 的写入权限。
+
+### 2.3 AI 可以准备，人必须判断
+
+AI 可以提取事实、整理文字、去重、建议 scope/override、生成 proposal 或 Action Plan、准备精确 CLI 参数。
+
+人必须对以下对象作出明确决定：
+
+- 哪些 item ID 成为长期规范；
+- 是否接受某个来源的新 digest；
+- 是否修订或废弃某个合同项；
+- 是否写入某个明确投影路径；
+- 是否执行 Review Bundle 中已展示的精确 action；
+- 是否把某个任务决定升格为长期 Project Contract 内容。
+
+## 3. 权威、文件和提交边界
+
+### 3.1 项目内的权威顺序
+
+1. 项目产品宪法或同等最高规范；
+2. 当前项目状态与当前授权；
+3. 人工批准的 `Project Contract`；
+4. 按 scope 编译的 Context Bundle；
+5. 受管投影；
+6. 临时任务说明和对话。
+
+不是每个使用项目都必须拥有本仓库的 `docs/00-PRODUCT-CONSTITUTION.md` 或 `PROJECT_STATE.json`。这两个文件是 Frontend Project Context 自身的治理结构；普通接入项目应登记它自己真实存在的权威来源。
+
+### 3.2 应提交的文件
+
+```text
+.project-context/
+├── contract.json
+├── sources.lock.json
+└── projections.lock.json
+```
+
+这三个 store 应跟随项目提交。团队明确采用的受管投影也应提交。
+
+通常不提交：
+
+- setup/discover/propose 产生的 proposal；
+- Assist Bundle、Action Plan 和 Review Bundle；
+- 临时 Context Bundle；
+- Task Context Plan、Stage Context Bundle、Stage Receipt 和 Integration Review Bundle，除非团队明确将它们作为外部流程证据管理；
+- dashboard HTML、缓存、tarball 和 `node_modules`。
+
+## 4. 安装与团队配置
+
+### 4.1 环境要求
+
+- Node.js 18 或更高版本；
+- 项目根目录可写；
+- 首次安装时由人或外部工具明确授权依赖下载。
+
+### 4.2 推荐安装
+
+固定为项目开发依赖，使本地与 CI 使用同一版本：
+
+```bash
+npm install --save-dev frontend-project-context@1.3.1
+```
+
+建议在 `package.json` 中提供稳定入口：
+
+```json
+{
+  "scripts": {
+    "context:capabilities": "project-context capabilities --project .",
+    "context:setup": "project-context setup --project .",
+    "context:sync": "project-context sync --project .",
+    "context:check": "project-context check --project ."
+  }
+}
+```
+
+试运行：
+
+```bash
+npx project-context --help
+npx project-context capabilities --project . --json
+```
+
+`capabilities` 在项目未初始化时也可用，适合 AI Host 先查询当前包版本、schema、支持的 action kind 和永久边界。
+
+## 5. 首次接入 SOP
+
+### 第 1 步：只读预览初始化结果
+
+```bash
+npx project-context setup \
+  --project . \
+  --id my-project \
+  --name "My Project" \
+  --json
+```
+
+首先阅读输出中的：
+
+- `summary`：候选来源、候选 item 和问题数量；
+- `workUnits`：应按哪些小单元处理；
+- `readTargets`：AI 真正需要继续读的精确文件或 JSON Pointer；
+- `proposal`：保守 discovery 得到的 fact/reference 候选；
+- `artifacts`：使用 `--write` 时将创建的 proposal 路径和动作。
+
+此时项目文件应保持不变。
+
+### 第 2 步：明确同意创建 store 和 proposal
+
+确认项目 ID、名称和 proposal 路径后执行：
+
+```bash
+npx project-context setup \
+  --project . \
+  --id my-project \
+  --name "My Project" \
+  --output .project-context/setup.proposal.json \
+  --write \
+  --json
+```
+
+`setup --write` 只代表允许创建三个 store 和一份 create-only proposal，**不代表批准 proposal，也不代表允许生成 AGENTS/Ruler 投影**。
+
+### 第 3 步：AI 只按 work unit 渐进读取
+
+AI 应：
+
+1. 先读 `summary`、`workUnits` 和 `readTargets`；
+2. 一次只处理一个 work unit；
+3. 只读当前 work unit 指向的文件或 Pointer；
+4. 对大文件先读目录、标题和相关段落；
+5. 需要额外来源时，先说明原因并把它列为 source 候选；
+6. 不以“代码存在”推导出“团队长期 policy”。
+
+### 第 4 步：补充来源和候选合同项
+
+支持的来源类型：
+
+- `file`：文件内容的指纹；
+- `path`：项目内路径及其文件/目录类型，不对目录全量指纹；
+- `json-pointer`：JSON 文件中的精确值；
+- `human-decision`：已经由人确认的决定；
+- `external-reference`：URL 或外部设计系统标识，CLI 不会上网验证。
+
+先预览，再在对象无误后重复同一命令并加 `--write`：
+
+```bash
+npx project-context register \
+  --project . \
+  --id source.package \
+  --kind file \
+  --path package.json
+```
+
+创建合同项 proposal：
+
+```bash
+npx project-context propose \
+  --project . \
+  --id policy.ui-copy \
+  --kind policy \
+  --subject ui.visible-copy \
+  --value required \
+  --statement "使用团队已批准的界面文案规范。" \
+  --sources source.package \
+  --scope path-prefix \
+  --scope-path src \
+  --output .project-context/policy.ui-copy.proposal.json
+```
+
+合同项类型只有：
+
+- `fact`：可验证的当前事实；
+- `policy`：对后续任务有约束力的规则；
+- `reference`：供理解或继续阅读的引用；
+- `validation-description`：如何验证的说明，不是由本工具执行任务命令。
+
+scope 只有：
+
+- `project`：整个项目；
+- `path-prefix`：指定目录及其后代；
+- `file`：单个文件。
+
+### 第 5 步：人工集中审查
+
+AI 必须先展示：
+
+```text
+自动提取事实：ID + value + source
+新增/修订规范：current → proposed + source + scope
+来源变化：old/new digest + 完整 affected item IDs
+废弃项：ID + 依赖 + fallback
+投影：将创建或更新的精确路径
+阻断项：conflict / missing / unreadable / ownership / stale baseline
+```
+
+用户可以用自然语言确认，但必须让对象与范围唯一。例如：
+
+```text
+批准 item policy.ui-copy，批准人记录为 fushan。
+同意接受 source.package 的当前 digest，受影响项仅为 fact.node-version 和 validation.check。
+同意生成 src/AGENTS.md，作用域仅为 src。
+```
+
+以下语句不应被 AI 解读成新的持久写入权限：
+
+```text
+看一下。
+分析一下。
+按之前的办。
+继续。
+应该没问题。
+```
+
+### 第 6 步：批准精确 ID
+
+```bash
+npx project-context approve \
+  --project . \
+  --proposal .project-context/policy.ui-copy.proposal.json \
+  --ids policy.ui-copy \
+  --by YOUR_NAME
+```
+
+先看 preview，确认无误后才加 `--write`。一份 proposal 中未被 `--ids` 点名的 item 不会自动获得批准。
+
+### 第 7 步：生成上下文和投影
+
+为目标路径生成临时上下文：
+
+```bash
+npx project-context context \
+  --project . \
+  --path src \
+  --locale zh-CN
+```
+
+生成 AGENTS 投影：
+
+```bash
+npx project-context publish \
+  --project . \
+  --target agents \
+  --output src/AGENTS.md \
+  --path src
+```
+
+或生成 Ruler 投影：
+
+```bash
+npx project-context publish \
+  --project . \
+  --target ruler \
+  --output .ruler/project-context.md \
+  --path src
+```
+
+同样先预览，然后在人确认精确路径后加 `--write`。
+
+如果根 `AGENTS.md` 由人工或其他工具管理，不要覆盖。可以改为在无冲突的子目录生成受管 `AGENTS.md`，或使用 `.ruler/` 投影。
+
+### 第 8 步：检查并提交
+
+```bash
+npx project-context check --project .
+```
+
+`check` clean 后，提交三个 store 和团队明确采用的受管投影。proposal 通常不提交。
+
+## 6. 日常开发中怎样给 AI 最小上下文
+
+一般任务不需要重新扫描整个仓库。先根据任务的真实修改目标生成 Context Bundle：
+
+```bash
+npx project-context context \
+  --project . \
+  --path src/features/order \
+  --path src/shared/request.ts \
+  --task "修复订单详情中的重复请求，不改变其他页面行为。" \
+  --locale zh-CN
+```
+
+`--task` 是当次临时约束，只会进入这份 bundle，不会写回 Contract，也不会扩大开发权限。
+
+推荐把下面四类信息一起给外部 Coding Agent：
+
+1. 当次任务目标和验收标准；
+2. 实际修改路径；
+3. `context` 生成的 bundle；
+4. 本次单独授予的开发、测试、Git 或网络边界。
+
+完成业务修改后，由外部 Agent、IDE 或 CI 把真实 changed paths 传给 `sync`：
+
+```bash
+npx project-context sync \
+  --project . \
+  --changed-path src/features/order/detail.ts \
+  --changed-path src/shared/request.ts \
+  --json
+```
+
+`sync` 不读 Git，所以 `--changed-path` 必须由宿主显式提供。它不会把 changed path 自动登记为 source。
+
+## 7. 规则和来源变化后的维护 SOP
+
+标准闭环：
+
+```text
+check / sync
+→ 只读审查变化与完整影响集
+→ 人选择接受来源变化、修订或废弃 item
+→ 受影响 item 进入 proposed/pending
+→ 人重新批准精确 ID
+→ 重新发布受管投影
+→ check clean
+```
+
+### 7.1 先一次汇总变化
+
+```bash
+npx project-context sync --project . --json
+```
+
+AI 应先交付变化清单，不应直接写入：
+
+- 哪些 source 是 `changed / missing / unreadable`；
+- 每个 source 的 locked/current digest；
+- 完整 affected item IDs，以及 direct/verification/override 原因；
+- fallback item 和受影响投影；
+- pending item、ownership conflict 和其他 blocker；
+- 需要人判断的唯一问题。
+
+### 7.2 精确审查单个来源
+
+```bash
+npx project-context review-source \
+  --project . \
+  --id source.package \
+  --json
+```
+
+### 7.3 接受来源新 digest
+
+只有人确认 new digest 和完整 affected item IDs 后，才预览：
+
+```bash
+npx project-context accept-source-change \
+  --project . \
+  --id source.package \
+  --expected-digest sha256:NEW_DIGEST \
+  --affected-items fact.node-version validation.check
+```
+
+预览无误后加 `--write`。该操作接受新的 source checkpoint，并撤销受影响 item 的原批准；它不会自动判定规则仍然正确。
+
+### 7.4 修订、废弃或重新批准
+
+修订前必须使用当前 item digest：
+
+```bash
+npx project-context revise \
+  --project . \
+  --id policy.ui-copy \
+  --expected-item-digest sha256:CURRENT_ITEM_DIGEST \
+  --kind policy \
+  --subject ui.visible-copy \
+  --value required \
+  --statement "使用新版团队界面文案规范。" \
+  --sources source.ui-guide \
+  --scope path-prefix \
+  --scope-path src
+```
+
+废弃 item：
+
+```bash
+npx project-context deprecate \
+  --project . \
+  --id policy.ui-copy \
+  --expected-item-digest sha256:CURRENT_ITEM_DIGEST \
+  --by YOUR_NAME \
+  --rationale "该规范已被新规范替代"
+```
+
+重新批准 pending item：
+
+```bash
+npx project-context approve \
+  --project . \
+  --pending \
+  --ids fact.node-version validation.check \
+  --by YOUR_NAME \
+  --rationale "已对照新来源复核"
+```
+
+上述写命令都应先 preview，再针对当前命令加 `--write`。
+
+### 7.5 来源被删除或已永久退役
+
+1. 先 `sync` / `review-source` 确认是 missing 还是真的永久退役；
+2. 先修订或废弃所有仍引用该 source 的 item；
+3. 只有 source 无活跃引用时才执行 `deprecate-source`；
+4. 记录精确 source digest、执行人和 rationale；
+5. 重新 `check`。
+
+不要因为文件暂时不可读就自动退役来源。
+
+### 7.6 失败恢复
+
+任何 accept/revise/deprecate/approve/publish 失败后：
+
+1. 立即停止后续写入；
+2. 重新加载项目；
+3. 重新运行 `sync`；
+4. 基于新 snapshot/baseline 重做审查；
+5. 不重放旧计划，不盲目回滚已成功的显式授权动作。
+
+## 8. AI Action Plan 与 Review Bundle SOP
+
+当外部 AI 需要准备多个治理动作时，优先使用机器协议，而不是让 AI 拼接一段自由 shell。
+
+### 8.1 查询协议能力
+
+```bash
+npx project-context capabilities --project . --json
+```
+
+`1.3.1` 支持八类 Action Plan action：
+
+- `register-source`；
+- `propose-item`；
+- `accept-source-change`；
+- `revise-item`；
+- `deprecate-item`；
+- `deprecate-source`；
+- `request-item-approval`；
+- `publish-projection`。
+
+### 8.2 AI 生成无权限 Action Plan
+
+AI 必须使用 `schemas/action-plan.schema.json`，从最新 `setup` / `sync` Assist Bundle 取得三个当前项目 snapshot，并为每个 action 保留稳定 ID、完整输入和 action-specific baseline。`capabilities` 只用来确认当前 schema 版本、action kind 和边界，不提供项目 snapshot。
+
+Action Plan 中不得包含 Provider 调用、shell、Git、业务代码写入、自动批准或权限提升字段。
+
+### 8.3 只读预检
+
+```bash
+npx project-context preflight \
+  --project . \
+  --plan .project-context/action-plan.json \
+  --json
+```
+
+`preflight` 会验证：
+
+- project ID；
+- Contract / source lock / projection lock 三个 snapshot digest；
+- action 自己的 item/source/projection baseline；
+- 精确影响集和 blocker；
+- 投影路径与 ownership；
+- schema 与未知字段。
+
+输出的 structured invocation 不包含 `--write` 或 `--by`，因此不是可直接执行的批准。
+
+### 8.4 人的集中审查
+
+AI 至少展示：
+
+- Review Bundle 的 snapshot/baseline；
+- 每个 action ID 和 kind；
+- current → proposed；
+- source、item、scope、path 和 projection impact；
+- blocker 和失败封闭结果；
+- 将要执行的结构化 command/args。
+
+人只批准已展示的精确 action ID 和路径。宿主才可以为对应的现有细粒度命令补充 `--by` 和 `--write`。
+
+任何一个写入成功或并发状态变化后，剩余 Review Bundle 默认过期。必须重新 `sync` 和 `preflight`，不得继续重放旧 invocation。
+
+## 9. 多阶段、跨窗口任务 SOP
+
+只在任务确实较长、需要分阶段、换窗口/模型/同事继续，或需要合并前上下文审查时使用。普通单步任务直接使用 `context` 即可。
+
+### 9.1 外部 Host 准备 Task Context Plan
+
+Task Context Plan 必须符合 `schemas/task-context-plan.schema.json`，其中明确：
+
+- project/task identity；
+- goal 与可验收条件；
+- 宿主提供的 branch label 和 base revision label；
+- 当前三个 project snapshots；
+- 用规范 UTF-8 字节和 read-target 数表达的预算；
+- 每个 stage 的 objective、dependsOn、paths 和 acceptance IDs。
+
+Plan 是宿主提供的外部任务工件，不是 Contract，不授予执行权限。
+
+### 9.2 只编译当前显式指定的 stage
+
+首阶段：
+
+```bash
+npx project-context stage-context \
+  --project . \
+  --plan task-context-plan.json \
+  --stage stage-understand \
+  --changed-path src/features/order \
+  --json
+```
+
+后续阶段：
+
+```bash
+npx project-context stage-context \
+  --project . \
+  --plan task-context-plan.json \
+  --stage stage-render \
+  --receipt stage-understand.receipt.json \
+  --receipt-bundle stage-understand.bundle.json \
+  --changed-path src/features/order/detail.ts \
+  --json
+```
+
+CLI 只读验证并编译 bundle，不会读取目标源码正文、Git diff，也不执行开发任务或测试。AI 再按 bundle 的 `readTargets` 渐进读取。
+
+### 9.3 每个 Receipt 必须与其输入 Bundle 成对保留
+
+Stage Receipt 必须符合 `schemas/stage-receipt.schema.json`，并绑定：
+
+- project/task/stage；
+- plan digest；
+- 生成该 receipt 时使用的 Stage Context Bundle digest；
+- completed/blocked 状态；
+- changed paths、acceptance results、verification results、decisions 和 open issues。
+
+Receipt 不代表人已验收功能，不代表 Contract approval，也不能自动解锁下一阶段。
+
+从 `1.3.1` 开始，每个 `--receipt` 必须恰好有一个对应的 `--receipt-bundle`。必须把整条依赖链所需的 receipt/bundle 成对传入。缺失、重复、错配、篡改、过期 baseline、blocked bundle 或不完整传递依赖都必须 blocked。
+
+换窗口时不需要复制整段聊天历史，只需交接：
+
+```text
+Task Context Plan
++ 当前 stage ID
++ 所有有效上游 Stage Receipts
++ 与每份 Receipt 一一对应的 Stage Context Bundles
++ 显式 changed paths
+```
+
+### 9.4 合并前只读审查
+
+```bash
+npx project-context integration-review \
+  --project . \
+  --plan task-context-plan.json \
+  --receipt stage-understand.receipt.json \
+  --receipt-bundle stage-understand.bundle.json \
+  --main-changed-path src/shared/request.ts \
+  --branch-changed-path src/features/order/detail.ts \
+  --json
+```
+
+`integration-review` 只报告上下文层可验证事实，不执行 merge，也不判定 Git 文本冲突、测试是否通过或业务功能是否正确。
+
+任务结束后，只有对未来任务仍然有效的长期事实或规则，才可经 `propose → approve` 进入 Contract。不要把完整聊天、diff、测试日志或所有 receipt 写进长期合同。
+
+## 10. Dashboard 与 CI
+
+### 10.1 本地只读看板
+
+```bash
+npx project-context dashboard --project . > project-context-dashboard.html
+```
+
+Dashboard 是 stdout 生成的自包含离线 HTML，不会自动打开浏览器，不会修改 Contract。HTML 通常不提交。
+
+### 10.2 CI 只读 Gate
+
+最小 CI 使用：
+
+```bash
+npm run context:check
+```
+
+可参考 `examples/project-context-check.yml`。CI 可以自己从 Git/PR 平台取得 changed paths，并传给 `sync --json`，但不应在 CI 中自动 accept、approve、revise、deprecate 或 publish。
+
+## 11. AI 协作注意点
+
+### 11.1 AI 应该做
+
+- 先用 `capabilities`、`context`、`setup`、`sync`、`preflight` 等只读入口建立当前事实；
+- 按 `workUnits` 和 `readTargets` 渐进读取，避免默认加载全仓库；
+- 区分“源文件中的明确事实”和“AI 自己的推断”；
+- 保留 source ID、item ID、scope、provenance、digest 和 baseline；
+- 用 current → proposed 呈现修订；
+- 将真正需要人决定的问题集中询问；
+- 把写入前的精确 ID、路径、影响集、baseline 和命令完整展示给人；
+- 失败后重新 sync/preflight，不重放旧计划；
+- 用户只需自然表达事实，AI 负责结构化、润色、关联来源和准备 proposal。
+
+### 11.2 AI 不应该做
+
+- 未经人确认就执行带 `--write` 的命令；
+- 自行填写人的身份并冒充批准者；
+- 把 proposal、AI 回答、Review Bundle 或 receipt 当成已批准规范；
+- 未展示 exact ID/source/scope/value/impact/baseline 就请求笼统授权；
+- 自动接受 source digest、自动重批、静默解决冲突或覆盖 ownership 变化；
+- 因为文件名、技术栈或单个项目不同就擅自扩大产品内核；
+- 把临时任务限制写回长期 Contract；
+- 把源码、全量 Contract、长聊天、AI 推理、confidence 或无关摘要塞入 Assist Bundle；
+- 把 Frontend Project Context 的“无 Git/无网络/无业务代码写入”边界，误解为外部 Coding Agent 自动获得这些权限。外部 Agent 仍需按当次任务另行获得授权。
+
+### 11.3 单次人工审查清单
+
+在回复“同意”之前，人应能回答：
+
+- [ ] 我看到了所有将被影响的 source/item ID 吗？
+- [ ] 我看到了 current 和 proposed 的差异吗？
+- [ ] 我知道规则将在 project/path-prefix/file 哪个 scope 生效吗？
+- [ ] 我看到了完整 affected IDs、fallback 和 projection paths 吗？
+- [ ] 我看到的 digest/baseline 还是当前的吗？
+- [ ] 这次授权只覆盖已展示的 action 和路径吗？
+- [ ] 命令中是否只有需要持久化的那一步带 `--write` ？
+
+## 12. 常见问题与处理
+
+| 现象 | 原因 | 处理 |
+| --- | --- | --- |
+| 命令显示了结果但文件没变 | 没有 `--write`，只做了 preview | 审查预览后，对同一条命令显式加 `--write` |
+| `source-changed` | 来源内容与上次人工确认 digest 不同 | `sync` → `review-source` → 人确认 → `accept-source-change` → revise/deprecate/reapprove |
+| `source-missing` | 已登记本地来源不存在 | 先判断是移动、暂时缺失还是永久退役；不自动修复 |
+| `projection-ownership-conflict` | 受管投影被人或其他工具修改，或目标本就不属于本工具 | 保留现有文件，人判断合并、换路径或重新建立 ownership；不强制覆盖 |
+| proposal 没有生效 | proposal 仍是 `proposed` | 人审查并用 `approve --ids ... --by ... --write` 批准 |
+| `baseline` / `snapshot` stale | 预检后又发生了写入或并发变化 | 停止旧计划，重新 `sync` / `capabilities` / `preflight` |
+| setup 报 partial state | 三个 store 只存在一部分 | 人工盘点现状，不让工具猜测修复或覆盖 |
+| context/publish 被 conflict 阻断 | scope/override/source/verification 存在不可安全解释的冲突 | 回到 source/item 审查，由人选择 revise/deprecate/override |
+| `largeImpact: true` | 单一来源影响超过 100 个 item | 按 work unit 分批审查；不要假设 AI 已读完所有内容 |
+| receipt/bundle missing、duplicate、mismatch、stale 或 invalid | 跨阶段工件未一一绑定，被篡改或 baseline 过期 | 找回产生 receipt 时的原 bundle，补齐完整依赖链；无法证明时重新编译阶段 |
+
+常用退出码：
+
+- `0`：命令成功，对 `check/sync` 通常表示无需处理的 finding；
+- `1`：存在漂移、pending、普通阻断项或需审查状态；
+- `2`：参数、schema、路径或项目状态无效；
+- `3`：受管投影 ownership conflict；
+- `4`：意外内部错误。
+
+对自动化来说，不要只看 stdout 文本；应同时看退出码和 JSON 中的结构化 status/findings。
+
+## 13. 可直接复制的 AI 协作模板
+
+### 13.1 首次接入
+
+```text
+为当前项目接入 Frontend Project Context。
+
+1. 先运行 capabilities 和 setup 只读预览，不加 --write。
+2. 先只汇报 summary、workUnits、readTargets、proposal 工件路径和 blocker。
+3. 按 work unit 渐进读取，不默认扫描全仓库。
+4. 将候选分为 fact / policy / reference / validation-description，展示 ID、value、source、scope 和判断依据。
+5. 不批准、不接受 digest、不发布投影，等我对精确 ID 和路径确认。
+6. 确认后只执行已展示的对应命令，任何 baseline 变化就停止并重新 sync。
+```
+
+### 13.2 日常开发任务
+
+```text
+任务：<目标>
+验收：<可验证的完成条件>
+预计路径：<目录或文件>
+
+先用 project-context context 为这些路径生成最小上下文，不扫描无关区域。
+将 Project Contract 要求、临时任务约束和你自己的推断分开陈述。
+完成任务后，用实际 changed paths 运行 sync --json，汇报是否影响长期合同或投影。
+不把当次任务结论自动写入 Contract。
+```
+
+### 13.3 来源漂移维护
+
+```text
+检查当前 Project Contract 健康状态。
+
+1. 先运行 sync --json，保持只读。
+2. 按 source 分组展示 locked/current digest、完整 affected item IDs、fallback、projection paths 和 blocker。
+3. 对每个 item 说明建议是保留、修订还是废弃，但不要自动决定。
+4. 把所有写入动作按 current → proposed 集中展示，等我对精确 source/item ID 和路径确认。
+5. 任何一步失败或 snapshot 变化，停止剩余写入并重新 sync，不重放旧计划。
+```
+
+### 13.4 跨窗口交接
+
+```text
+使用已提供的 Task Context Plan、当前 stage ID、全部上游 Stage Receipts、与每份 Receipt 对应的 Stage Context Bundles，以及显式 changed paths 恢复任务。
+
+先运行 stage-context 只读校验。
+如果任何 receipt/bundle 缺失、重复、错配、篡改、过期或 blocked，立即停止，不根据聊天历史猜测补全。
+只编译显式指定的当前 stage，再按 readTargets 渐进读取。
+Receipt 只记录阶段证据，不代表人已验收、合并或批准长期规范。
+```
+
+## 14. 最小日常检查清单
+
+开始任务前：
+
+- [ ] 当前使用的 CLI 版本是团队固定版本；
+- [ ] 任务目标、验收条件和修改路径已明确；
+- [ ] 已用 `context` 生成与路径匹配的最小上下文；
+- [ ] 已明确外部 Coding Agent 本次可以做哪些写入和外部操作。
+
+规则写入前：
+
+- [ ] AI 已展示 exact ID、source、scope、value、impact 和 baseline；
+- [ ] 用户只批准了已展示的精确对象；
+- [ ] 已先运行 preview 或 `preflight`；
+- [ ] 没有把历史授权扩张到新对象；
+- [ ] 并发变化后已经重新 sync/preflight。
+
+任务结束后：
+
+- [ ] 已把真实 changed paths 传给 `sync`；
+- [ ] 已运行 `check`；
+- [ ] 只把长期有效的新决定提案到 Contract；
+- [ ] 已提交三个 store 和选定的受管投影；
+- [ ] 没有把临时 proposal/bundle/dashboard/聊天历史当成长期真源。
+
+## 15. 命令速查
+
+| 命令 | 用途 | 是否可写 |
+| --- | --- | --- |
+| `capabilities` | 查询版本、schema、action kind 和永久边界 | 否 |
+| `setup` | 聚合安全初始化、保守 discovery 和 Assist Bundle | 仅显式 `--write` |
+| `init` | 创建空的三个 store | 仅显式 `--write` |
+| `discover` | 保守生成首次候选 | 仅保存 proposal 时 `--write` |
+| `register` | 登记明确来源 | 仅显式 `--write` |
+| `propose` | 创建待审的合同项 | 仅保存 proposal 时 `--write` |
+| `approve` | 批准 proposal 或 pending 中的精确 ID | 仅显式 `--write` |
+| `context` | 按路径/任务编译最小上下文 | 否 |
+| `publish` | 生成受管 AGENTS 或 Ruler 投影 | 仅显式 `--write` |
+| `check` | 检测来源、合同和投影漂移 | 否 |
+| `sync` | 聚合变化、影响集、路径信号和维护工作单元 | 否 |
+| `review-source` | 查看单个来源变化与影响集 | 否 |
+| `accept-source-change` | 接受来源新 checkpoint 并撤销受影响批准 | 仅显式 `--write` |
+| `revise` | 以同 ID 修订合同项 | 仅显式 `--write` |
+| `deprecate` | 废弃合同项并保留审计信息 | 仅显式 `--write` |
+| `deprecate-source` | 退役已无活跃引用的来源 | 仅显式 `--write` |
+| `preflight` | 验证 Action Plan 并生成只读 Review Bundle | 否 |
+| `stage-context` | 只编译指定 stage，严格验证 receipt/bundle 链 | 否 |
+| `integration-review` | 合并前审查路径信号、snapshot 和阶段证据 | 否 |
+| `dashboard` | 输出只读治理看板 | 否 |
+
+完整且以当前安装版本为准的语法，始终通过以下命令查看：
+
+```bash
+npx project-context --help
+```