frontend-project-context 1.0.1 → 1.2.0

package/docs/08-INSTALLATION-AND-DISTRIBUTION.md

@@ -2,9 +2,9 @@
 
 > 权威说明：本文是支持性设计文档；当前唯一规范真源是 [00-PRODUCT-CONSTITUTION.md](./00-PRODUCT-CONSTITUTION.md)。
 
-状态：`frontend-project-context@1.0.1` README/metadata patch 已完成本地验证并获得发布授权
+状态：`frontend-project-context@1.2.0` 已完成本地实现与 69 项验证；公共 npm 已核验最新版本仍为 `1.0.1`，`1.2.0` 发布未授权
 适用项目：`dtg-frontend-delivery-agent`  
-本文只确定产品如何交付、安装、共享、升级和验证，不授权实现。
+本文记录产品如何交付、安装、共享、升级和验证；它不自行授权打包、registry、Git 或发布操作。
 
 ## 1. 决策摘要
 
@@ -43,29 +43,29 @@ CI 安装项目锁定的依赖版本并执行只读检查。CI 不依赖机器
 面向 Node.js 前端项目，推荐支持包管理器的一次性运行方式，例如：
 
 ```bash
-npx frontend-project-context@1.0.1 init --project . --id PROJECT_ID --name "Project Name"
-pnpm dlx frontend-project-context@1.0.1 init --project . --id PROJECT_ID --name "Project Name"
-bunx frontend-project-context@1.0.1 init --project . --id PROJECT_ID --name "Project Name"
+npx frontend-project-context@1.2.0 setup --project . --id PROJECT_ID --name "Project Name" --json
+pnpm dlx frontend-project-context@1.2.0 setup --project . --id PROJECT_ID --name "Project Name" --json
+bunx frontend-project-context@1.2.0 setup --project . --id PROJECT_ID --name "Project Name" --json
 ```
 
-以上命令只在包实际发布后可用；当前未访问 registry。包名冻结为 `frontend-project-context`，可执行文件名为 `project-context`，CLI 合同以 [04-PROGRAM-DESIGN.md](./04-PROGRAM-DESIGN.md) 为准。
+以上 `1.2.0` 一次性命令只在该版本获得单独发布授权并实际发布后可用；当前公共 registry 最新已核验版本仍为 `1.0.1`。包名冻结为 `frontend-project-context`，可执行文件名为 `project-context`，CLI 合同以 [04-PROGRAM-DESIGN.md](./04-PROGRAM-DESIGN.md) 为准。
 
-初始化入口只负责：
+`setup` 初始化入口只负责：
 
-- 识别当前项目并建立 DTG 配置；
-- 选择需要生成的通用 Markdown、AGENTS 或 Ruler 兼容出口；
-- 明确哪些文件由 DTG 管理、哪些文件由人维护；
-- 预览即将写入的文件；
-- 在用户明确确认后执行首次写入。
+- 在内存中构造与 `init` 相同的空 store 并复用保守 discovery；
+- 输出包含候选、`readTargets` 和 `workUnits` 的 Assist Bundle；
+- preview 时保持项目字节不变；
+- 只有本命令带 `--write` 时创建三个 store 和 create-only proposal；
+- proposal 保持 proposed，后续由人审查明确 ID，再使用既有 approve/publish 命令。
 
-初始化不得自动访问网络、安装额外依赖、批准规范候选或修改业务代码。
+初始化不得自动访问网络、安装额外依赖、批准规范候选、生成投影或修改业务代码。
 
 ### 3.2 正式安装：项目开发依赖
 
 初始化后，DTG 应作为项目开发依赖被锁定，例如：
 
 ```bash
-pnpm add -D frontend-project-context@1.0.1
+pnpm add -D frontend-project-context@1.2.0
 ```
 
 选择项目内安装而不是全局安装，原因是：
@@ -102,7 +102,7 @@ CLI 是初始化、编译、检查和 CI 自动化的参考操作界面，不是
 - 解释某项规则的来源、作用域和最终生效原因；
 - 显式执行配置结构迁移。
 
-具体命令、参数和退出码已经在 [04-PROGRAM-DESIGN.md](./04-PROGRAM-DESIGN.md)、[12-KNOWLEDGE-MAINTENANCE-CLOSURE-ROADMAP.md](./12-KNOWLEDGE-MAINTENANCE-CLOSURE-ROADMAP.md)、[13-READ-ONLY-GOVERNANCE-DASHBOARD-DESIGN.md](./13-READ-ONLY-GOVERNANCE-DASHBOARD-DESIGN.md) 与 [15-SOURCE-LIFECYCLE-CLOSURE-DESIGN.md](./15-SOURCE-LIFECYCLE-CLOSURE-DESIGN.md) 冻结并实现。安装阶段不得通过 `postinstall` 静默修改项目文件。
+具体命令、参数和退出码已经在 [04-PROGRAM-DESIGN.md](./04-PROGRAM-DESIGN.md)、[12-KNOWLEDGE-MAINTENANCE-CLOSURE-ROADMAP.md](./12-KNOWLEDGE-MAINTENANCE-CLOSURE-ROADMAP.md)、[13-READ-ONLY-GOVERNANCE-DASHBOARD-DESIGN.md](./13-READ-ONLY-GOVERNANCE-DASHBOARD-DESIGN.md)、[15-SOURCE-LIFECYCLE-CLOSURE-DESIGN.md](./15-SOURCE-LIFECYCLE-CLOSURE-DESIGN.md)、[16-GUIDED-ONBOARDING-AND-AI-RECONCILIATION-DESIGN.md](./16-GUIDED-ONBOARDING-AND-AI-RECONCILIATION-DESIGN.md) 与 [17-AI-EXCHANGE-BOUNDARY-DESIGN.md](./17-AI-EXCHANGE-BOUNDARY-DESIGN.md) 冻结并实现。安装阶段不得通过 `postinstall` 静默修改项目文件。
 
 无需启动服务即可生成一次性的本地治理看板：
 
@@ -199,3 +199,15 @@ IDE 插件可以在未来提供状态提示、冲突解释和可视化配置，
 详细工件、验证与发布记录见 [14-FORMAL-RELEASE-READINESS.md](./14-FORMAL-RELEASE-READINESS.md)。public npm、private 安全闩解除、release commit/tag/push 和实际 publish 均已完成；本次发布授权已经消耗。
 
 `1.0.1` 是不改变运行逻辑的 patch：README 改为中英双语的用户向入口，包元数据移除 `bin` 规范化警告，并从发布白名单移除只属于源码仓库治理的 `PROJECT_STATE.json` 与 `RTK.md`。当前没有真实可公开访问的源码仓库，因此不伪造 `repository` 或 `bugs` URL。
+
+## 11. `1.1.0` 与 `1.2.0` 本地实现状态
+
+`1.1.0` 增加 `setup`、永远只读的 `sync` 和短生命周期 Assist Bundle schema 1，现归入 AI Exchange Boundary 的模型无关聚合基础。新入口只聚合现有初始化、discovery、source review/impact、checker 和 Scope Compiler；宿主 Agent 触发仍是可选适配器，不增加 Provider、Agent Runtime、Git、网络、scheduler、daemon、自动批准或新 store。
+
+本地 A-01 至 A-55、B0-01/B0-02、CLI 与发布工件共 61 项通过。Contract reader 1/2、proposal/source/projection lock schema 1、renderer 3 与 Dashboard View Model 3 保持兼容，`1.0.1 → 1.1.0` 无数据迁移。
+
+`1.2.0` 已完成 AI Exchange Boundary：新增未初始化/已初始化均可查询的只读 `capabilities`、Action Plan schema 1、只读 `preflight`、Review Bundle schema 1 和四份公开 machine schema。八类 action 只形成预检与 structured invocation，实际写入仍由人授权后复用既有细粒度命令；没有 `apply-plan`。
+
+本地 A-01 至 A-63、B0-01/B0-02、CLI、schema 与发布工件共 69/69 项通过。Contract reader 1/2、proposal/source/projection lock schema 1、renderer 3 与 Dashboard View Model 3 保持兼容，`1.1.0 → 1.2.0` 无 store migration。
+
+本次实现授权不包含 `npm pack` 发布候选核验、registry 访问、tag、push 或 `npm publish`。公共 npm 的 `latest` 仍以已核验的 `1.0.1` 为准，任何 `1.2.0` 发布操作必须获得新的明确授权。

package/docs/16-GUIDED-ONBOARDING-AND-AI-RECONCILIATION-DESIGN.md

@@ -0,0 +1,469 @@
+# 16 — `1.1.0` Guided Onboarding 与 AI-assisted Reconciliation 设计
+
+> 权威说明：本文是 AI Exchange Boundary 的 `1.1.0` 聚合基础设计；宿主 Agent 适配仍是可选适配器。如与 [00-PRODUCT-CONSTITUTION.md](./00-PRODUCT-CONSTITUTION.md) 冲突，以产品宪法为准。
+>
+> 状态：`implemented-local-corrected; A-46-through-A-55-passed; release-not-authorized`
+>
+> 基线：`frontend-project-context@1.1.0` 本地实现、Contract reader schema 1/2、proposal/source lock/projection lock schema 1、renderer 3、Dashboard View Model 3、A-01 至 A-55、B0-01/B0-02、CLI 与发布工件共 61 项通过。
+
+## 1. 结论
+
+`1.1.0` 只解决一个已经被实际使用暴露的问题：产品的治理内核完整，但首次接入和后续维护仍把 `init → discover/register → propose → approve → publish → check` 的低层步骤直接交给用户，人工操作成本过高。
+
+本阶段最初以可选适配器实现；`1.2.0` 产品宪法明确双向桥梁后，其中模型无关的 Assist Bundle 与完整行动摘要归入 AI Exchange Boundary 内核，而 Codex、Claude、MCP 或其他宿主触发仍属于可选适配器。它通过两个聚合入口和一份模型无关的 AI 协作合同，把用户体验改成：
+
+```text
+首次接入：外部 AI 依据协议准备 → 人集中评判一次 → 既有安全命令完成写入
+后续维护：工具统计变化规则 ID → AI 只整理影响子集 → 人确认例外
+```
+
+冻结的新增公共入口只有：
+
+```text
+project-context setup --project PATH --id ID --name NAME [--output FILE] [--write] [--json]
+project-context sync --project PATH [--changed-path RELATIVE_PATH...] [--json]
+```
+
+`setup` 聚合初始化与保守发现；`sync` 聚合全部已登记来源的漂移、规则影响和投影影响。两者都不调用 Provider、不运行 Agent、不读取 Git、不批准规则、不修改业务代码、不自动安装依赖。
+
+AI 由 Codex、Claude 或其他现有 Coding Agent 提供。Frontend Project Context 只产生确定性的 Assist Bundle，并用现有 schema、baseline、impact、approval 和 ownership 机制验证 AI 准备的动作。
+
+## 2. 用户目标与成功标准
+
+### 2.1 首次接入
+
+用户只需要对 Coding Agent 表达：
+
+```text
+为当前项目初始化唯一真源。
+```
+
+Agent 可以在一次会话中自动完成：
+
+1. 调用 `setup` 得到初始化预览、保守来源候选和确定性 fact/reference 候选；
+2. 按 Assist Bundle 的 `readTargets` 渐进读取少量项目资料；
+3. 合并重复表达，起草 policy、reference 和 validation-description；
+4. 用现有 proposal schema 和 `approve` preview 做确定性预检；
+5. 向人展示一份分组审查清单；
+6. 人明确批准 ID 后，Agent 才可调用带 `--write` 的既有命令；
+7. 按用户选定路径生成受管 AGENTS/Ruler 投影并运行 `check`。
+
+用户不再需要逐条拼装 register/propose 命令，但人类批准仍然是合同生效的唯一入口。
+
+### 2.2 后续维护
+
+维护由外部 Agent 或 CI 触发：
+
+```text
+功能或文档变化
+→ project-context sync
+→ 精确 changed source / affected item ID / projection 集合
+→ AI 只读取影响子集
+→ 人批准 source accept、revision、deprecation 或新 item
+→ 显式 republish
+→ check clean
+```
+
+日常无漂移时无需人工动作。有漂移但不涉及语义变化时，Agent 仍必须展示精确变化和拟执行动作；不能因为 AI 判断“安全”就绕过来源接受或规则重新批准。
+
+### 2.3 可证伪的成功标准
+
+- 新项目从零到 clean Contract 的过程中，用户只做一次候选选择与批准，不手写三个 store，不逐条输入低层命令。
+- 已初始化项目一次 `sync` 就能稳定列出全部变化来源及规则 ID 并集，不要求逐个执行 `review-source`。
+- AI 接收的默认工件不包含来源正文，也不包含无关合同项的完整 value/statement。
+- 未发生变化的来源和不在影响闭包中的规则不会进入维护工作单元。
+- Agent 或 CI 可以自动触发读取与统计；任何规范批准和持久写入仍由明确人类授权约束。
+
+## 3. 证据驱动的现状审查
+
+| 现有能力 | 可直接复用 | 唯一缺口 |
+| --- | --- | --- |
+| `initializeProject` | 安全预览和创建三个 store；拒绝覆盖 | 用户必须先单独执行 `init` |
+| `discoverProject` | 确定性发现 package/config/顶层目录/Agent 规则并生成 schema-1 proposal | 只能在已初始化项目上单独调用；没有面向 Agent 的工作单元摘要 |
+| `registerSource` / `buildItemProposal` | 通用来源和四类 item，不需要框架识别 | 手工命令颗粒度过低 |
+| `approveProposal` / `approvePendingItems` | 批量显式 ID、来源重读、冲突预检、快照保护 | 缺少统一的 Agent 审查合同；不能把 AI 建议直接当批准 |
+| `reviewSource` / `sourceImpact` | 精确 direct、verification、reverse override、fallback 和 projection 影响 | 目前每次只审查一个 source |
+| `checkProject` | 全项目漂移、pending、冲突和 projection findings | 输出是发现列表，不是面向维护的聚合行动摘要 |
+| Scope Compiler | 能为显式 changed path 找到适用的批准 item | 当前没有接收调用方 changed path 的维护入口 |
+| project/projection store | 已有 baseline、条件恢复和失败封闭 | 不应再增加全局事务或新 store |
+| Dashboard | 已能只读查看健康、知识、来源和影响 | 本阶段不把它改造成写入式审批应用 |
+
+因此实现不得推倒重写，也不需要新的 Contract、proposal、source lock 或 projection lock schema。唯一产品缺口是把已有原语聚合成适合 Agent 自动调用、适合人集中审查的短生命周期工作单元。
+
+## 4. 固定 CLI 合同
+
+### 4.1 `setup`
+
+```text
+project-context setup --project PATH --id ID --name NAME
+  [--output .project-context/FILE.json] [--write] [--json]
+```
+
+#### 未初始化项目
+
+没有 `--write`：
+
+- 在内存中构造与 `init` 相同的空 Contract；
+- 复用 `discoverProject`，不得增加第二套 scanner；
+- 输出 setup Assist Bundle；
+- 文件系统所有 bytes 保持不变。
+
+带 `--write`：
+
+- 先按现有 `init` 语义创建三个 store；
+- 把 discovery proposal 以 create-only 方式写入 `--output`；未给 `--output` 时使用 `.project-context/setup.proposal.json`；
+- proposal 仍全部为 `proposed`，不含 approval；
+- 不生成 projection，不修改 AGENTS，不执行 `check` 之外的项目命令。
+
+#### 已初始化项目
+
+- `--id` 与 `--name` 必须与现有 Contract 一致；不一致退出 2；
+- 不重写三个 store，只针对当前 Contract 复用 discovery；
+- `--write` 只允许 create-only proposal 输出；已有相同 bytes 返回 unchanged，已有不同内容停止；
+- partial `.project-context/` 继续由现有 loader 失败封闭，不尝试猜测或修复。
+
+#### 权限
+
+`setup --write` 只代表创建空 store 和 proposal 的权限，不代表批准 proposal、接受漂移、创建 projection 或修改业务文件的权限。
+
+### 4.2 `sync`
+
+```text
+project-context sync --project PATH [--changed-path RELATIVE_PATH...] [--json]
+```
+
+`sync` 永远只读，不接受 `--write`、`--output`、`--by`、`--ids` 或任何批准参数。
+
+行为固定为：
+
+1. 读取一次当前 project snapshot；
+2. 对全部 active 本地来源复用 `reviewSource`；
+3. human-decision、external-reference 和 deprecated source 只记录生命周期/可检查性，不读取外部内容；
+4. 对 changed/missing/unreadable source 合并 `sourceImpact`；
+5. 按 item ID 去重 direct、verification 和 override-dependent 关系，保留每个 source 的原因；
+6. 汇总 fallback item 和 direct/stale projection path；
+7. 合并 `checkProject` findings 与当前 pending item；
+8. 对调用方显式给出的 `--changed-path` 做项目内路径规范化，并复用 Scope Compiler 计算这些路径当前适用的批准 item；
+9. changed path 只是外部 Agent/CI 提供的信号，不证明它是来源，不更新 digest，也不读取 Git；
+10. 输出 sync Assist Bundle。
+
+退出码与现有 check/dashboard 对齐：
+
+- `0`：没有 drift、pending、conflict 或 ownership finding；
+- `1`：存在需要审查的变化、pending 或普通阻断 finding；
+- `3`：存在受管 projection ownership conflict；
+- `2`：输入、schema 或项目状态无效；
+- `4`：意外内部失败。
+
+### 4.3 为什么不新增 `apply-ai-plan`
+
+本阶段明确不新增一个能够跨 source accept、revise、deprecate、approve 和 publish 的万能写命令。原因是：
+
+- 它会把多个已经有独立 baseline 和失败恢复语义的动作合并成新的复杂事务；
+- 它容易把“人批准一份摘要”误扩张为“AI 可任意写 Contract”；
+- 现有原语已经可以由 Agent 在一次明确授权内顺序执行；
+- 任一步失败后重新 `sync`，比自动回滚或重放陈旧计划更安全。
+
+用户体验上的“一次确认”由 Agent 协作层完成，持久层仍复用已经验收的细粒度安全命令。
+
+## 5. Assist Bundle schema 1
+
+Assist Bundle 是 stdout 或 proposal 附带的短生命周期派生工件，不是 store，不提交仓库，不进入 Contract，不成为第二份真源。
+
+```json
+{
+  "schemaVersion": 1,
+  "mode": "setup | sync",
+  "project": {
+    "id": "project-id",
+    "name": "Project Name",
+    "initialized": true
+  },
+  "snapshots": {
+    "contract": "sha256:...",
+    "sourcesLock": "sha256:...",
+    "projectionsLock": "sha256:..."
+  },
+  "summary": {
+    "candidateSources": 0,
+    "candidateItems": 0,
+    "changedSources": 0,
+    "affectedItems": 0,
+    "pendingItems": 0,
+    "affectedProjections": 0
+  },
+  "sourceChanges": [],
+  "affectedItems": [],
+  "pendingItems": [],
+  "pathSignals": [],
+  "projectionPaths": [],
+  "findings": [],
+  "readTargets": [],
+  "workUnits": [],
+  "proposal": null,
+  "artifacts": []
+}
+```
+
+### 5.1 `sourceChanges`
+
+每项只包含：
+
+- source ID、kind、项目内 locator；
+- `unchanged | changed | missing | unreadable | not-local-checkable | deprecated`；
+- locked/current digest（存在时）；
+- direct/verification/override-dependent item IDs；
+- fallback item IDs；
+- direct/stale projection paths。
+
+不得包含来源正文或 AI 摘要。
+
+### 5.2 `affectedItems`
+
+只包含影响闭包中的 item：
+
+- ID、kind、subject、scope、status 和 item digest；
+- canonical value 与 statement；
+- source IDs、verification 和 overrides；
+- 按 source 聚合的影响原因。
+
+不在影响闭包中的 item 不复制完整 value/statement。全局统计只保留数量。
+
+### 5.3 `pendingItems`
+
+只包含当前 `status: proposed` 且必须审查的 item。每项保留 ID、kind、subject、scope、digest、value、statement、source、override 和可选 verification；它们不是无关 Contract 复制，而是已明确进入人工审查的行动集。
+
+### 5.4 `pathSignals`
+
+调用方传入的 changed path 规范化后记录：
+
+- path；
+- 当前适用的 approved item IDs；
+- 是否命中某个已登记 file/path source locator；
+- `registered-source | scope-only | unrelated` 分类。
+
+`scope-only` 或 `unrelated` 不能自动登记为 source。AI 可以建议登记，但必须走 proposal/register 与人类审查。`file` source 若指向目录，其内容 digest 覆盖后代，changed path 的 registered-source 判定也覆盖后代；`json-pointer` 只匹配自身文件路径。
+
+### 5.5 `readTargets` 与 `workUnits`
+
+`readTargets` 只给出 AI 下一步可能需要读取的精确 source ID、locator、理由和优先级，不内嵌正文。
+
+`workUnits` 使用稳定排序把工作划分为：
+
+- `onboarding-facts`：discovery 已确定提取的 fact/reference；
+- `authoritative-guidance`：需要 AI 阅读并整理的规则/文档来源；
+- `source-change`：按变化 source 及其影响闭包分组；
+- `path-signal`：外部 Agent 提供但尚未成为来源的变化路径；
+- `pending-review`：当前所有 proposed item 及其精确 source 集；
+- `projection-review`：按路径分组 stale、missing、diverged、renderer 或 ownership finding；
+- `conflict`：必须交给人的冲突或无法验证状态。
+
+每个 work unit 只引用 source/item ID，不复制来源正文。大型项目可以按 work unit 渐进读取；AI 不需要先加载完整 Contract 或全部来源。
+
+### 5.6 `proposal` 与 `artifacts`
+
+- setup 模式携带现有 schema-1 discovery proposal；
+- sync 模式为 `null`，因为已存在 item 的修订必须走 `revise`，source 变化必须走 `accept-source-change`；
+- AI 新建的 proposal 必须继续使用现有 schema 1，并由 `approve` preview 验证；
+- AI 的 confidence、推理过程和临时摘要不得写入 Contract schema。
+- setup 的 `artifacts` 必须返回 proposal 的项目内路径、`preview | create | unchanged` action 与 persisted 状态，使 JSON 消费者不依赖人类文本或默认路径猜测；sync 的 `artifacts` 为空。
+
+## 6. AI 协作协议
+
+### 6.1 输入纪律
+
+Host Agent 必须：
+
+1. 先读取 Assist Bundle 的 summary、workUnits 和 readTargets；
+2. 只读取当前 work unit 指向的文件或 JSON Pointer；
+3. 需要额外来源时说明原因，并把它作为新 source 候选，不静默扩大扫描；
+4. 不把源码存在本身解释为长期 policy；
+5. 不把未知事实补全成肯定陈述；
+6. 保留稳定 source ID、item ID、scope 与 provenance。
+
+### 6.2 AI 可以做的事
+
+- 合并多个已登记来源中语义重复的表达；
+- 从明确配置提取可验证 fact；
+- 把文档规范整理成 proposed policy/reference/validation-description；
+- 建议 scope、override、revision 或 deprecation；
+- 解释变化影响、冲突和人工决策点；
+- 准备已有 CLI 的 preview/write 参数。
+
+### 6.3 AI 不可以做的事
+
+- 调用 `approve` 时自行选择并冒充人类批准者；
+- 未展示 exact ID、source、scope、value、impact 和 baseline 就执行写入；
+- 自动接受 source digest、自动重新批准或静默解决冲突；
+- 修改业务代码来迎合 Contract；
+- 读取完整仓库作为默认动作；
+- 调用 Provider、网络、Git 或第三方 CLI 作为产品内部行为。
+
+### 6.4 单次人工确认合同
+
+Agent 给人的最终审查必须至少分为：
+
+```text
+自动提取事实：可选 ID 列表
+新增/修订规范：current → proposed、source、scope
+来源变化：old/new digest、完整 affected IDs
+废弃项：ID、依赖与 fallback
+投影：将创建/更新的明确路径
+阻断项：冲突、missing、unreadable、未知权威
+```
+
+只有用户明确批准具体组或 ID 后，Agent 才能执行对应的现有写命令。一次对话确认可以授权一组已完整展示的动作，但不能扩张到未展示的 ID、路径或后续新变化。
+
+## 7. 大型知识源与上下文控制
+
+本设计不引入向量数据库、embedding、源码索引、知识缓存或全仓库摘要。控制上下文体积依赖现有的来源身份、digest、scope 和影响图：
+
+1. **默认无正文**：Assist Bundle 不嵌入 source body。
+2. **增量优先**：sync 只展开 changed/missing/unreadable source 的影响闭包。
+3. **精确 locator**：JSON 用 Pointer，文件用项目内路径，目录 source 只表达路径身份。
+4. **作用域过滤**：changed path 只关联真正适用的 approved item。
+5. **稳定工作单元**：Agent 一次只处理一个 work unit；无关单元无需进入模型上下文。
+6. **按需继续读取**：单个大文件由 Host Agent 先读目录/标题/相关段落；产品不复制全文。
+7. **显式超大影响**：单一来源影响超过 100 个 item 时，Bundle 必须标记 `largeImpact: true`，保留所有 item ID、基本元数据、digest 和 source impact，但省略 value、statement、sources、overrides 与 verification；不得静默截断或假装完整理解。
+
+产品保证“默认输出不会主动塞入庞大真源”；Host Agent 是否违反渐进读取纪律属于由其适配器验收，不进入核心 Provider 逻辑。
+
+## 8. 自动触发边界
+
+Frontend Project Context 不实现 scheduler、daemon、watcher、Git hook 管理或 CI 平台客户端。
+
+允许的自动化是由外部系统调用稳定 CLI：
+
+```text
+Coding Agent 完成任务 → sync --changed-path ...
+CI pull request job → check 或 sync --json
+本地 npm script → sync
+```
+
+外部 CI 可以自己从 Git 获得 changed paths 并作为参数传入；产品不执行 Git 命令。自动触发不等于自动批准，`sync` 的只读属性不可配置关闭。
+
+## 9. 原子性、并发与失败恢复
+
+### 9.1 setup
+
+- preview 零写入；
+- store 初始化继续复用既有 create-only/失败封闭语义；
+- proposal 在 stores 成功后 create-only；proposal 创建失败时允许留下一个完整、有效的空项目，而不是回滚或删除已经初始化的 store；
+- 重跑 setup 必须识别现有同一项目并继续，不能覆盖不同 proposal；
+- 不新增跨四文件的事务日志。
+
+### 9.2 sync
+
+- 全程只读；
+- 一次 project snapshot 产生稳定 snapshots digest；
+- 来源在读取期间变化时使用现有 review/check 语义报告，不能写锁；
+- 同输入与同 bytes 输出确定性一致。
+
+### 9.3 Agent 执行
+
+- 每个 accept/revise/deprecate/approve/publish 继续使用自身 baseline 和原子写；
+- 任一步失败后停止剩余写操作，重新 load + sync；
+- 不自动重放旧计划，不用全局 rollback 覆盖已经成功的人类授权动作；
+- 中间状态必须能被 `check` 表达为 changed、pending 或 stale，不能形成静默半成功。
+
+## 10. 错误类别
+
+优先复用现有稳定错误。只新增聚合入口必须表达而现有错误无法准确表达的类别：
+
+| code | 退出码 | 含义 |
+| --- | --- | --- |
+| `setup-project-mismatch` | 2 | 已初始化项目的 id/name 与参数不一致 |
+| `setup-state-partial` | 2 | 三个 store 只存在一部分；拒绝自动修复 |
+| `setup-proposal-conflict` | 2 | 默认或显式 proposal path 已存在不同内容 |
+| `sync-path-invalid` | 2 | changed path 越界、绝对路径、含 `..` 或不规范 |
+
+source changed/missing/unreadable、pending、conflict、projection ownership、baseline changed 等继续使用现有 finding/error 和退出码，不创建同义类别。
+
+## 11. 兼容与迁移
+
+- 包版本为 `1.1.0`，因为新增公开 CLI 与协作协议；不是 `1.0.x` patch。
+- Contract reader 继续读取 schema 1/2；不主动升级 schema 1。
+- proposal、source lock、projection lock 继续 schema 1。
+- projection renderer 继续 3；Dashboard View Model 继续 3。
+- Assist Bundle 独立为短生命周期 schema 1，不写入任何 store。
+- `init`、`discover`、`register`、`propose`、`approve`、`review-source`、`accept-source-change`、`revise`、`deprecate`、`deprecate-source`、`context`、`publish`、`check`、`dashboard` 的参数和结果不改变。
+- Node.js 18+、零运行时依赖、离线核心保持不变。
+- `1.0.1 → 1.1.0` 无数据迁移；旧项目安装新版本即可选择使用 setup/sync。
+
+## 12. 唯一实现范围
+
+| 文件 | 允许变更 |
+| --- | --- |
+| `src/project-context/assist.mjs` | 新增 setup/sync Assist Bundle 的纯聚合与稳定排序 |
+| `src/project-context/cli.mjs` | 新增两个命令、参数 allowlist、人类摘要和退出码映射 |
+| `src/project-context/project-store.mjs` | 仅在 setup 复用需要时暴露最小内存初始化 helper；不得重写 store |
+| `src/project-context/discovery.mjs` | 只允许抽取复用接口；不得新增框架/文件名识别 |
+| `src/project-context/maintenance.mjs` | 只允许复用/导出聚合所需纯 impact helper；既有单 source 语义不变 |
+| `test/project-context/assist.test.mjs` | A-46 至 A-55 |
+| `test/project-context/cli.test.mjs` | 两个公共入口端到端与参数拒绝 |
+| `test/release/acceptance.test.mjs` | help、版本、README/文档入口和包白名单同步 |
+| `README.md`、`docs/04`、`docs/05`、`docs/08`、`UPGRADING.md` | 实现后同步真实行为 |
+
+不得新增第二套 scanner、第二个 scope compiler、数据库、索引、缓存、后台服务或跨动作事务框架。
+
+## 13. 冻结验收 A-46 至 A-55
+
+- **A-46 setup preview 与写入边界**：未初始化项目 preview 零写入且确定性；`--write` 只创建三个 store 与 create-only proposal；JSON 返回 proposal artifact 的精确路径、action 和 persisted 状态；所有 item proposed、无 approval、无 projection/业务文件变化。
+- **A-47 setup 复用与幂等**：候选与 `discoverProject` 完全一致；已初始化同 ID/name 可继续，相异项目和 partial store 失败封闭；不得新增框架识别或重复 scanner。
+- **A-48 sync 聚合准确性**：多个 changed/missing/unreadable source 一次输出；affected item ID 是现有 `sourceImpact` 并集，保留 source/verification/override 原因、fallback 和 projection，排序稳定且 sibling 不误伤。
+- **A-49 changed path 与 Scope Compiler**：显式 changed paths 只经规范化和现有 compiler 映射；registered-source/scope-only/unrelated 准确，目录型 file source 与 path source 都覆盖后代；不访问 Git，不把路径自动提升为来源。
+- **A-50 上下文体积与隐私边界**：默认 Bundle 不含 source body、无关 item value/statement、完整 Contract、嵌入摘要或 Provider 请求；只列 readTargets/workUnits；large impact 不静默截断。
+- **A-51 人工批准边界**：setup/sync 不能 accept、revise、deprecate、approve 或 publish；AI proposal 仍需 schema/baseline/preflight 和 exact IDs；无具体人类批准时所有规范保持 proposed/原 approval 不变。
+- **A-52 首次协议闭环**：隔离 fixture 以脚本化协议顺序完成 setup → 渐进读取 → proposal preview → 一次明确人工 ID 批准 → publish → clean check；它证明公共原语闭环，不声称已验证真实 Codex、Claude 或其他 Host Agent Runtime。
+- **A-53 增量 AI 协作闭环与恢复**：多来源变化通过一次 sync 分组；Agent 准备 accept/revise/deprecate/reapprove；任一步 baseline 或文件并发失败后停止并重新 sync，最终可恢复 clean，无旧计划重放或并发覆盖。
+- **A-54 兼容与永久边界**：A-01 至 A-45、B0-01/B0-02、CLI/A-39 全部继续通过；schema/renderer/dashboard 版本不变；静态/动态证明零 Provider、网络、dependency install、child process、Git、scheduler、daemon、业务代码修改或真实项目访问。
+- **A-55 行动摘要完整性**：无 source drift 但存在 pending item 和 projection-only finding 时，sync 仍返回完整 pending 内容、精确 read target、`pending-review`、`projection-review` 和 projection path。
+
+实现 Gate：A-01 至 A-55、B0-01/B0-02 与 CLI 共至少 59 项通过；README 能让另一位维护者理解“工具输出模型无关工作单元、外部 Agent 准备、人集中批准、sync 增量维护”的完整协议闭环。
+
+## 14. 明确不做
+
+- 不内置 OpenAI、Anthropic、Gemini 或其他 Provider。
+- 不实现 Agent Runtime、提示词执行器或多轮自动决策循环。
+- 不自动批准 fact、policy、reference 或 validation-description。
+- 不自动接受 source digest、解决冲突或执行 deprecation。
+- 不保存 AI 推理、confidence、聊天记录或全文摘要为新 store。
+- 不读取 Git diff、管理 hook、commit、branch、PR 或 push。
+- 不实现 watcher、daemon、scheduler、CI 平台客户端或网络 webhook。
+- 不把 Dashboard 改成写入式审批后台。
+- 不新增 framework、source kind、scope kind、projection target 或成熟工具适配矩阵。
+- 不访问真实业务项目验证本设计。
+
+## 15. 实现顺序与停止条件
+
+2026-09-09 获得单独实现授权后，按以下固定顺序完成：
+
+1. Assist Bundle 纯模型与 sync 聚合；
+2. changed path 的现有 Scope Compiler 映射；
+3. setup 的内存预览和受限写入；
+4. CLI/help/人类摘要；
+5. A-46 至 A-55 与全部回归；
+6. README、04、05、08、UPGRADING、PROJECT_STATE、RTK 和自托管真源同步。
+
+实现前设计阶段曾以以下条件停止：
+
+- 本文、05、文档索引、PROJECT_STATE 和 RTK 已形成无冲突的实现合同；
+- 唯一实现范围、错误、退出码、兼容、失败恢复和验收已冻结；
+- 没有修改 `src/`、`bin/`、`test/`、package version 或发布工件；
+- PROJECT_STATE 明确记录 design complete、implementation not authorized；
+- 下一步只有单独授权 `1.1.0` 实现。
+
+实现前设计完成时不授权产品代码、测试、依赖安装、Provider/网络、真实项目、Git 写入或发布；2026-09-09 的新授权只覆盖本文定义的产品代码、测试和事实同步，仍不授权依赖安装、Provider/网络、真实项目、Git 写入或发布。
+
+## 16. 本地实现结果
+
+冻结范围已完成：
+
+- 新增 `src/project-context/assist.mjs`，稳定生成 setup/sync Assist Bundle；
+- `setup` 支持未初始化内存预览、受限初始化写入、已初始化同项目继续、partial/mismatch/proposal-conflict 失败封闭；
+- `sync` 一次聚合 active 本地来源状态、精确影响闭包、fallback、projection、finding、pending 和调用方 changed path；
+- 大影响工作单元保留全部 ID 并显式标记，不复制来源正文、AI 摘要或无关合同值；
+- 持久动作继续使用原 accept/revise/deprecate/approve/publish 命令以及各自 baseline 和 ownership 保护；
+- 新增 A-46 至 A-55 和两个 CLI 入口回归，全量 `npm run check` 为 61/61。
+
+实现没有更改 Contract、proposal、source lock、projection lock、renderer 或 Dashboard schema，没有增加依赖、Provider、Agent Runtime、网络、Git、child process、后台任务、自动批准或真实项目访问。`1.1.0` 尚未打包或发布；下一阶段必须单独授权。