frontend-project-context 1.0.1 → 1.3.0

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## 1.3.0 — unreleased
+
+- 新增严格的 Task Context Plan schema 1 与 Stage Receipt schema 1：宿主显式提供任务、stage 依赖、revision label、snapshot、路径和预算，未知、权限、执行、循环依赖、非法路径与无依赖范围重叠均失败封闭。
+- 新增永远只读的 `stage-context`，复用 Scope Compiler 为显式指定阶段生成 Stage Context Bundle schema 1，并用调用方提供的规范 UTF-8 字节与 read-target 预算失败封闭。
+- 新增永远只读的 `integration-review`，比较 plan/receipt/Contract baseline、宿主提供的 main/branch changed paths、Contract item 重叠、stage 越界、生命周期 finding 和待人判断的 decision candidate。
+- 公开 Stage Context Bundle 和 Integration Review Bundle schema 1，capabilities 增加两个命令、四份 schema 和 `canonical-utf8-bytes` 预算语义。
+- 不新增 store migration、Provider、Agent Runtime、Git 读写、源码正文读取、任务/测试执行、依赖、自动批准、合并或长期事实晋升。
+- A-64 至 A-73 与全部旧回归共 79/79 项为实现 Gate；本条不代表 npm 打包、发布、Git 提交/push 或真实项目验收。
+
+## 1.2.0 — 2026-09-09
+
+- 新增未初始化和已初始化项目均可使用的只读 `capabilities`，公开 package、exchange protocol、schema、command、八类 action 和永久边界。
+- 新增 Action Plan schema 1 和只读 `preflight`，把 AI 建议规范化为带三个 snapshot、action 专属 baseline、精确 impact 与 blocker 的短生命周期输入。
+- 新增 Review Bundle schema 1，稳定分组 current/proposed、item/source/path/projection 影响与结构化 `{ command, args }` invocation；invocation 不含 `--write` 或 `--by`。
+- 发布 capabilities、Assist Bundle、Action Plan 与 Review Bundle 四份 JSON schema，并把 `schemas/` 加入 npm 白名单；动态项目状态继续排除。
+- 八类 action 均复用现有 register/propose/review/accept/revise/deprecate/approve/publish 预检语义；不新增 `apply-plan`、Provider、Agent Runtime、Git、网络、依赖安装、自动批准或业务代码执行。
+- A-56 至 A-63 与全部回归共 69/69 项验收通过；已发布到公共 npm，并完成候选包与 registry tarball 的逐字节一致性及独立安装验证。
+
+## 1.1.0 — unreleased
+
+- 新增 `setup`，在未初始化或已初始化项目中复用现有 discovery，输出不含自动批准的 Assist Bundle；显式写入只创建三个 store 和 create-only proposal。
+- 新增永远只读的 `sync`，一次聚合来源漂移、精确 item 影响、调用方 changed path、投影路径、finding、read target 和稳定 work unit。
+- Assist Bundle schema 1 默认不含来源正文和无关合同值；超过 100 个受影响 item 时保留全部 ID 与基本元数据、省略完整值并显式标记，不静默截断。
+- 补齐 pending-review、projection-review、setup proposal artifact receipt 和目录型 file source 的后代 changed-path 映射。
+- 保持人类为唯一批准者，不增加 Provider、Agent Runtime、网络、Git、依赖、后台服务、自动接受或自动发布能力。
+- A-01 至 A-55、B0-01/B0-02、CLI 和发布工件共 61 项本地验收通过；公共发布尚未授权。
+
 ## 1.0.1 — release candidate
 
 - 把 npm README 重写为面向使用者的中英双语安装、快速上手、工作流和命令入口。

package/README.md

@@ -14,6 +14,8 @@ AI coding tools often read only part of a repository. Important conventions may
 
 - selects the approved guidance that applies to a file or directory;
 - renders focused context for existing coding agents;
+- exposes versioned machine capabilities and schemas for model-neutral hosts;
+- converts AI suggestions into authority-free Action Plans and read-only Review Bundles;
 - publishes managed Markdown, AGENTS, or Ruler-compatible projections;
 - reports source, contract, and projection drift;
 - keeps every persistent write and approval under explicit human control.
@@ -30,23 +32,28 @@ It does **not** call an AI provider, edit business code, manage Git, install dep
 Pin it as a development dependency so local users and CI run the same version:
 
 ```bash
-npm install --save-dev frontend-project-context@1.0.1
+npm install --save-dev frontend-project-context@1.2.0
 ```
 
 The package has zero runtime dependencies.
 
+`1.2.0` is the current independently verified public npm version. The published tarball was byte-matched against the reviewed release candidate and smoke-tested from the official registry.
+
 ### Quick start
 
-Initialize the three project-local stores:
+Let an existing Coding Agent prepare deterministic onboarding candidates:
 
 ```bash
-npx project-context init \
+npx project-context setup \
   --project . \
   --id my-project \
   --name "My Project" \
-  --write
+  --write \
+  --json
 ```
 
+`setup` creates only the three stores and a create-only proposal. It does not approve candidates or publish Agent files. Its JSON `artifacts` receipt reports the exact proposal path and whether it was previewed, created, or already unchanged. Read `summary`, `workUnits`, and `readTargets`, then review the exact proposed IDs.
+
 Register an explicit source:
 
 ```bash
@@ -93,6 +100,62 @@ npx project-context context --project . --path src --locale en
 npx project-context check --project .
 ```
 
+After project sources or implementation paths change, create one read-only reconciliation work unit:
+
+```bash
+npx project-context sync \
+  --project . \
+  --changed-path src/example.ts \
+  --json
+```
+
+`sync` reports changed sources, affected item IDs, pending-item review, path-scoped guidance, projection-only findings, and exact work units. It contains no source bodies and cannot accept, revise, approve, deprecate, or publish anything. A Coding Agent may prepare the existing safe commands, but a human must approve the displayed IDs and paths before writes occur.
+
+Discover the exchange contract without initializing the project:
+
+```bash
+npx project-context capabilities --project . --json
+```
+
+An external AI host can create an Action Plan schema 1 using the returned project snapshots and one of the eight advertised action kinds. Save that short-lived plan inside the project, then produce a read-only Review Bundle:
+
+```bash
+npx project-context preflight \
+  --project . \
+  --plan .project-context/action-plan.json \
+  --json
+```
+
+`preflight` validates the project ID, all three snapshot digests, action-specific baselines, exact impacts, blockers, and projection ownership. It returns structured `{ command, args }` invocations without `--write` or `--by`. The plan and Review Bundle grant no authority: after a human approves exact action IDs and paths, the host must add the required identity and write flags to the existing fine-grained command. Any intervening write invalidates the remaining review and requires a fresh `sync` and `preflight`.
+
+For multi-stage feature work, a host can provide a Task Context Plan, prior Stage Receipts, and explicit changed-path signals. Compile only the requested stage:
+
+```bash
+npx project-context stage-context \
+  --project . \
+  --plan task-context-plan.json \
+  --stage stage-render \
+  --receipt stage-understand.receipt.json \
+  --changed-path src/example.ts \
+  --json
+```
+
+Before an external merge, compare host-provided main/branch path signals with the plan, receipts, current Contract snapshots, and checker findings:
+
+```bash
+npx project-context integration-review \
+  --project . \
+  --plan task-context-plan.json \
+  --receipt stage-understand.receipt.json \
+  --main-changed-path src/shared.ts \
+  --branch-changed-path src/example.ts \
+  --json
+```
+
+Both commands are read-only. They do not inspect Git, read source bodies, execute the task or tests, save task state, promote decisions, or grant merge authority. Budget limits are caller-supplied canonical UTF-8 bytes and read-target counts, not model tokens.
+
+The package publishes eight machine schemas: capabilities, Assist Bundle, Action Plan, Review Bundle, Task Context Plan, Stage Receipt, Stage Context Bundle, and Integration Review Bundle.
+
 Generate the read-only governance dashboard:
 
 ```bash
@@ -122,6 +185,11 @@ Explicit project sources
 → human-approved Project Contract
 → scoped Context Bundle
 → AGENTS / Markdown / Ruler projections
+→ existing AI tool
+→ authority-free Action Plan
+→ read-only Review Bundle
+→ exact human approval
+→ existing fine-grained write command
 → drift check
 ```
 
@@ -131,6 +199,8 @@ All commands are read-only unless that command explicitly includes `--write`. So
 
 | Command | Purpose |
 | --- | --- |
+| `setup` | Aggregate safe initialization, conservative discovery, and an Assist Bundle |
+| `capabilities` | Discover protocol versions, schemas, action kinds, initialization, and permanent boundaries |
 | `init` | Create an empty project contract safely |
 | `register` | Register a file, path, JSON pointer, or human decision |
 | `discover` | Conservatively propose bootstrap candidates |
@@ -139,6 +209,10 @@ All commands are read-only unless that command explicitly includes `--write`. So
 | `context` | Compile approved context for one or more paths |
 | `publish` | Write an owned AGENTS, Markdown, or Ruler projection |
 | `check` | Detect stale sources, contracts, and projections |
+| `sync` | Aggregate source drift, item impact, changed paths, and reconciliation work units |
+| `preflight` | Validate an Action Plan and return a read-only grouped Review Bundle |
+| `stage-context` | Compile the explicitly requested stage within caller-provided byte/read-target budgets |
+| `integration-review` | Review plan, receipts, host path signals, baselines, and context-layer conflicts without Git |
 | `dashboard` | Render the read-only governance dashboard |
 | `review-source` | Review a changed source and its exact impact set |
 | `accept-source-change` | Accept a pinned source digest and revoke affected approvals |
@@ -156,6 +230,10 @@ Run `npx project-context --help` for the complete command syntax.
 - [Knowledge maintenance](./docs/12-KNOWLEDGE-MAINTENANCE-CLOSURE-ROADMAP.md)
 - [Read-only governance dashboard](./docs/13-READ-ONLY-GOVERNANCE-DASHBOARD-DESIGN.md)
 - [Source lifecycle](./docs/15-SOURCE-LIFECYCLE-CLOSURE-DESIGN.md)
+- [Guided onboarding and AI-assisted reconciliation](./docs/16-GUIDED-ONBOARDING-AND-AI-RECONCILIATION-DESIGN.md)
+- [AI exchange boundary](./docs/17-AI-EXCHANGE-BOUNDARY-DESIGN.md)
+- [Branch-aware staged context and handoff](./docs/18-BRANCH-AWARE-STAGED-CONTEXT-DESIGN.md)
+- [AI Exchange Boundary design](./docs/17-AI-EXCHANGE-BOUNDARY-DESIGN.md)
 - [Upgrade notes](./UPGRADING.md)
 
 ## 中文
@@ -166,6 +244,8 @@ AI 编程工具通常只读取仓库的一部分，而项目约定分散在文
 
 - 按文件或目录选择真正生效的已批准规则；
 - 为现有 Coding Agent 生成精简且可追溯的上下文；
+- 向模型无关宿主公开版本化 capability 与机器 schema；
+- 把 AI 建议收敛为无权限 Action Plan 和只读 Review Bundle；
 - 从同一合同生成受管 Markdown、AGENTS 或 Ruler 兼容投影；
 - 检测来源、合同和投影是否过期；
 - 所有持久写入与批准都必须由人显式触发。
@@ -182,23 +262,28 @@ AI 编程工具通常只读取仓库的一部分，而项目约定分散在文
 建议固定为开发依赖，让本地与 CI 使用同一版本：
 
 ```bash
-npm install --save-dev frontend-project-context@1.0.1
+npm install --save-dev frontend-project-context@1.2.0
 ```
 
 本包没有运行时第三方依赖。
 
+`1.2.0` 是当前已独立核验的公共 npm 最新版本。已发布 tarball 与审查过的发布候选逐字节一致，并已从官方 registry 完成安装冒烟验证。
+
 ### 快速开始
 
-初始化三个项目内存储文件：
+让现有 Coding Agent 生成确定性的首次接入候选：
 
 ```bash
-npx project-context init \
+npx project-context setup \
   --project . \
   --id my-project \
   --name "My Project" \
-  --write
+  --write \
+  --json
 ```
 
+`setup` 只创建三个 store 和一份 create-only proposal，不会批准候选或发布 Agent 文件。JSON 中的 `artifacts` receipt 会返回精确 proposal 路径，以及 preview、create 或 unchanged 结果。先读取 `summary`、`workUnits` 和 `readTargets`，再审查具体 proposal ID。
+
 登记一个明确来源：
 
 ```bash
@@ -245,6 +330,62 @@ npx project-context context --project . --path src --locale zh-CN
 npx project-context check --project .
 ```
 
+项目来源或实现路径变化后，可一次生成只读的增量维护工作单元：
+
+```bash
+npx project-context sync \
+  --project . \
+  --changed-path src/example.ts \
+  --json
+```
+
+`sync` 汇总变化来源、受影响 item ID、pending item 审查、路径适用规则、仅投影 finding 和精确 work unit。它不携带来源正文，也不能接受、修订、批准、废弃或发布任何内容。Coding Agent 可以准备既有安全命令，但只有人在看到明确 ID 和路径后才能授权写入。
+
+无需初始化项目即可查询双向交换协议：
+
+```bash
+npx project-context capabilities --project . --json
+```
+
+外部 AI 宿主可使用返回的三个项目 snapshot 和八类 action 生成 Action Plan schema 1。把这份短生命周期计划保存在项目内，再生成只读 Review Bundle：
+
+```bash
+npx project-context preflight \
+  --project . \
+  --plan .project-context/action-plan.json \
+  --json
+```
+
+`preflight` 会验证 project ID、三个 snapshot digest、action 专属 baseline、精确影响集、blocker 和投影所有权，并返回不含 `--write`、`--by` 的结构化 `{ command, args }` invocation。Action Plan 和 Review Bundle 都不授予权限；只有人批准明确 action ID 与路径后，宿主才能为既有细粒度命令补入身份和写入参数。期间任何写入都会使余下 review 失效，必须重新 `sync` 和 `preflight`。
+
+多阶段功能开发中，宿主可以显式提供 Task Context Plan、前序 Stage Receipt 和 changed-path 信号，只编译当前指定阶段：
+
+```bash
+npx project-context stage-context \
+  --project . \
+  --plan task-context-plan.json \
+  --stage stage-render \
+  --receipt stage-understand.receipt.json \
+  --changed-path src/example.ts \
+  --json
+```
+
+外部合并前，可把宿主提供的 main/branch 路径信号与 plan、receipt、当前 Contract snapshot 和 checker finding 一起进行只读审查：
+
+```bash
+npx project-context integration-review \
+  --project . \
+  --plan task-context-plan.json \
+  --receipt stage-understand.receipt.json \
+  --main-changed-path src/shared.ts \
+  --branch-changed-path src/example.ts \
+  --json
+```
+
+两个命令都不会读取 Git 或源码正文、执行任务或测试、保存任务状态、晋升决定或授予合并权限。预算由调用方以规范 UTF-8 字节数和 read-target 数量显式提供，不等同于模型 token。
+
+npm 包公开八份机器 schema：capabilities、Assist Bundle、Action Plan、Review Bundle、Task Context Plan、Stage Receipt、Stage Context Bundle 和 Integration Review Bundle。
+
 生成只读治理看板：
 
 ```bash
@@ -274,6 +415,11 @@ npx project-context dashboard --project . > project-context-dashboard.html
 → 人工批准的 Project Contract
 → 按作用域编译的 Context Bundle
 → AGENTS / Markdown / Ruler 投影
+→ 现有 AI 工具
+→ 无权限 Action Plan
+→ 只读 Review Bundle
+→ 人对明确 action 的批准
+→ 既有细粒度写命令
 → 漂移检查
 ```
 
@@ -283,6 +429,8 @@ npx project-context dashboard --project . > project-context-dashboard.html
 
 | 命令 | 用途 |
 | --- | --- |
+| `setup` | 聚合安全初始化、保守 discovery 和 Assist Bundle |
+| `capabilities` | 查询协议版本、schema、action kind、初始化状态和永久边界 |
 | `init` | 安全创建空项目合同 |
 | `register` | 登记文件、路径、JSON Pointer 或人工决定 |
 | `discover` | 保守提出首次接入候选 |
@@ -291,6 +439,10 @@ npx project-context dashboard --project . > project-context-dashboard.html
 | `context` | 为一个或多个路径编译已批准上下文 |
 | `publish` | 写入仍归工具所有的 AGENTS、Markdown 或 Ruler 投影 |
 | `check` | 检测来源、合同和投影漂移 |
+| `sync` | 聚合来源漂移、item 影响、变化路径和维护工作单元 |
+| `preflight` | 验证 Action Plan 并返回只读分组 Review Bundle |
+| `stage-context` | 在调用方字节/read-target 预算内编译显式指定的当前阶段 |
+| `integration-review` | 不读取 Git，只读审查 plan、receipt、路径信号、baseline 与上下文冲突 |
 | `dashboard` | 生成只读治理看板 |
 | `review-source` | 查看来源变化及精确影响集 |
 | `accept-source-change` | 接受固定摘要并撤销受影响批准 |
@@ -308,6 +460,10 @@ npx project-context dashboard --project . > project-context-dashboard.html
 - [知识维护闭环](./docs/12-KNOWLEDGE-MAINTENANCE-CLOSURE-ROADMAP.md)
 - [只读治理看板](./docs/13-READ-ONLY-GOVERNANCE-DASHBOARD-DESIGN.md)
 - [来源生命周期](./docs/15-SOURCE-LIFECYCLE-CLOSURE-DESIGN.md)
+- [引导式接入与 AI 辅助维护](./docs/16-GUIDED-ONBOARDING-AND-AI-RECONCILIATION-DESIGN.md)
+- [AI 双向交换边界](./docs/17-AI-EXCHANGE-BOUNDARY-DESIGN.md)
+- [分支感知的分阶段上下文与交接](./docs/18-BRANCH-AWARE-STAGED-CONTEXT-DESIGN.md)
+- [AI 双向交换边界设计](./docs/17-AI-EXCHANGE-BOUNDARY-DESIGN.md)
 - [升级说明](./UPGRADING.md)
 
 ## License / 许可证

package/UPGRADING.md

@@ -1,5 +1,49 @@
 # 升级说明
 
+## `1.2.0 → 1.3.0`
+
+`1.3.0` 增加可选 Branch-aware Staged Context & Handoff 协议：四份新的短生命周 schema、只读 `stage-context` 和只读 `integration-review`。Contract、proposal、source/projection lock、renderer、Dashboard View Model、Assist Bundle、Action Plan 和 Review Bundle schema 都不变，旧项目无需迁移 `.project-context/`。
+
+采用该可选协议时：
+
+1. 宿主根据 `schemas/task-context-plan.schema.json` 显式准备 task、stage DAG、workspace label、三个 snapshot 与 UTF-8 字节/read-target 预算。
+2. 运行 `project-context stage-context --project . --plan FILE --stage STAGE_ID --json`；只为当前 stage 提供有效前序 receipt 和 changed-path 信号。
+3. 外部 Coding Agent 执行任务后，由宿主按 `schemas/stage-receipt.schema.json` 记录结构化结果；receipt 不是人工验收或后续权限。
+4. 合并前运行 `project-context integration-review`，显式传入 main/branch changed paths；工具不自行读 Git。
+5. 合并、测试、业务正确性、任务工件存放/删除和长期事实晋升仍由外部工具与人决定。
+
+当前源码已完成实现验收，但未获得 npm 打包或发布授权；已公开核验的 npm `latest` 仍为 `1.2.0`。
+
+## `1.1.0 → 1.2.0`
+
+`1.2.0` 完成模型无关双向 AI Exchange Boundary：新增只读 `capabilities`、Action Plan schema 1、只读 `preflight`、Review Bundle schema 1 和四份公开机器 schema。Contract、proposal、source lock、projection lock、renderer 与 Dashboard View Model 均未升级，旧项目无需迁移 `.project-context/`。
+
+该版本已于 2026-09-09 发布到官方公共 npm，`latest` 指向 `1.2.0`；发布包与冻结候选逐字节一致。
+
+升级后建议：
+
+1. 运行 `project-context capabilities --project . --json`，由宿主读取版本、schema、action kind、初始化状态和永久边界。
+2. 继续使用 `setup`/`sync` 获取项目到 AI 的 Assist Bundle；外部 AI 只生成符合 `schemas/action-plan.schema.json` 的无权限计划。
+3. 运行 `project-context preflight --project . --plan FILE --json`，集中审查 current/proposed、baseline、影响集、blocker、分组与 structured invocation。
+4. 人明确批准具体 action ID 与路径后，宿主才可给 Review Bundle 中的既有细粒度命令补入所需 `--by` 和 `--write`。
+5. 任一写入后，未执行的旧 Review Bundle 与 invocation 全部作废；重新运行 `sync` 和 `preflight`。
+
+Action Plan 和 Review Bundle 都不是 store、Contract 或 approval receipt。升级不会执行 plan、自动批准、自动修复、修改业务代码、读取 Git、访问网络、调用 Provider 或安装依赖。
+
+## `1.0.1 → 1.1.0`
+
+`1.1.0` 新增 `setup`、只读 `sync` 和短生命周期 Assist Bundle schema 1，它们是双向 AI Exchange Boundary 的首个模型无关内核基础；Codex、Claude、MCP 或其他宿主触发仍属可选适配器。Contract reader 仍兼容 schema 1/2，proposal、source lock、projection lock、renderer 3 和 Dashboard View Model 3 均未变化，因此无需迁移 `.project-context/`。
+
+升级后可以继续使用所有原命令，也可以逐步采用：
+
+1. 新项目通过 `project-context setup --project . --id ID --name NAME --json` 先预览；只有明确需要创建三个 store 和 proposal 时才加 `--write`。
+2. 已初始化项目运行 `project-context sync --project . --json`，一次查看全部来源漂移、影响 item、pending review 和仅投影 finding。
+3. 外部 Agent 或 CI 可以把变化路径通过重复的 `--changed-path` 传入；产品本身不读取 Git。
+4. AI 只根据 `readTargets` 和 `workUnits` 渐进读取，准备既有 accept/revise/deprecate/approve/publish 命令。
+5. 人工明确批准具体 ID 和路径后才能执行相应写命令，最后运行 `check`。
+
+升级不会自动创建 proposal、批准规则、接受来源 digest、重发投影、访问网络、运行 Provider、安装依赖或修改业务代码。
+
 ## `1.0.0 → 1.0.1`
 
 `1.0.1` 只修复 npm README、元数据和包文件白名单，不修改 CLI、Contract、lock、projection 或 Dashboard schema。更新依赖版本后无需迁移 `.project-context/`。

package/docs/00-PRODUCT-CONSTITUTION.md

@@ -1,10 +1,10 @@
 # Frontend Project Context — 产品宪法
 
-> 宪法版本：`1.1.1`
+> 宪法版本：`1.2.0`
 >
 > 状态：`frozen`
 >
-> 生效日期：`2026-09-07`
+> 生效日期：`2026-09-09`
 
 ## 1. 文档权威
 
@@ -15,7 +15,7 @@
 - `PROJECT_STATE.json` 只记录当前事实、实现状态、授权和下一步；
 - `RTK.md` 只提供新窗口启动摘要；
 - `README.md` 只提供产品介绍和使用入口；
-- `docs/01` 至 `docs/05`、`docs/08`、`docs/11`、`docs/12` 是形成当前决定的设计或路线说明；
+- `docs/01` 至 `docs/05`、`docs/08`、`docs/11` 至 `docs/17` 是形成当前决定的设计或路线说明；
 - `docs/06`、`docs/07`、`docs/09`、`docs/10` 是历史或验证证据；
 - 任务讨论、实验结果和真实项目观察都是输入证据，不能自行改变本文档。
 
@@ -23,9 +23,9 @@
 
 ## 2. 唯一产品定义
 
-Frontend Project Context 是一个**落在项目中的、位于项目与 AI 编程工具之间的模型无关上下文治理与编译层**。
+Frontend Project Context 是一个**落在项目中的、位于项目与 AI 编程工具之间的模型无关双向上下文治理与交换层**。
 
-它把项目明确提供的事实、规则和来源治理为一份人工批准的 `Project Contract`，再针对目录和任务生成最小、可追溯的 `Context Bundle`，投影给已有 AI 编程工具，并检测来源、合同和投影漂移。
+它把项目明确提供的事实、规则和来源治理为一份人工批准的 `Project Contract`，再针对目录和任务生成最小、可追溯的 `Context Bundle`，投影给已有 AI 编程工具，并把 AI 返回的建议收敛为可预检、可集中审查的短生命周期 action，最后在人明确批准后复用现有安全写入原语。
 
 ```text
 项目显式来源 + 人工规则
@@ -33,22 +33,26 @@ Frontend Project Context 是一个**落在项目中的、位于项目与 AI 编
 → 人工批准的 Project Contract
 → 按目录/任务编译的 Context Bundle
 → AGENTS.md / Ruler / 其他 AI 工具
-→ 来源与投影漂移检查
+→ AI Action Plan
+→ 确定性预检与人工集中审查
+→ 已授权的细粒度写入
+→ 来源、合同与投影漂移检查
 ```
 
-本产品治理“项目希望 AI 知道什么”，不负责“AI 如何完成开发任务”。
+本产品治理“项目希望 AI 知道什么”和“AI 建议如何在人工授权前被安全表达与预检”，不负责“AI 如何完成开发任务”。
 
 ## 3. 固定用户问题
 
 同一项目的知识分散在设计资料、文档、配置、代码和团队约定中，不同 AI 工具会获得不完整、重复或互相冲突的指导，并且规则变化难以追溯。
 
-本产品提供的稳定价值只有三点：
+本产品提供的稳定价值只有四点：
 
 1. 一份有人批准、保留来源的项目合同；
 2. 针对目录和任务的确定性上下文编译；
 3. 同一合同面向多个 AI 消费者的一致投影和漂移检查。
+4. 项目与不同 AI 编程工具之间一份双向、模型无关、可预检且不扩张人工权限的交换协议。
 
-如果某项能力不能直接服务这三点，它默认不属于内核。
+如果某项能力不能直接服务这四点，它默认不属于内核。
 
 ## 4. 固定内核
 
@@ -60,6 +64,7 @@ Frontend Project Context 是一个**落在项目中的、位于项目与 AI 编
 4. **Context Renderer**：生成包含必要批准内容和来源引用的稳定 Context Bundle，任务约束不写回合同；
 5. **Projection Boundary**：把同一合同投影为受管 Markdown、AGENTS 或 Ruler 输入，不重建完整工具适配矩阵；
 6. **Conflict and Drift Check**：报告来源、合同和受管投影变化，不自动修复或静默提升规则。
+7. **AI Exchange Boundary**：以公开、带版本的机器合同向外部 AI 输出 Context/Assist Bundle，并把 AI 建议收敛为无权限的 Action Plan 与只读 Review Bundle；所有持久动作仍需人对精确 action、ID 和路径明确批准。
 
 自动 discovery 只是帮助项目首次接入的可选辅助，不是内核完整性的衡量标准。它可以保守地提出候选，但不承担理解所有前端技术和业务语义的责任。
 
@@ -90,6 +95,7 @@ Vue、React、uni-app、Vuex、Element UI、路由、租户和发布方式等都
 8. 未知项目语义是待录入的项目数据，不自动成为产品缺陷。
 9. 真实项目只能验证预先定义的能力，不能直接产生内核需求。
 10. 新技术、新文件名或单个项目差异不能成为扩大 discovery 的充分理由。
+11. AI 产生的 Action Plan、Review Bundle、推理或建议都不是 Project Contract、approval 或持久执行权限；必须通过 schema、baseline、impact 和人工精确授权边界。
 
 ## 7. v1 完成定义
 
@@ -112,6 +118,19 @@ v1 只有在以下闭环同时成立时才算产品完成：
 
 该版本只扩展现有来源追溯、人工合同治理和漂移检查，没有改变第 2 至第 6 节的产品身份、内核、永久边界和不变量。
 
+### 7.2 AI Exchange Boundary 完成条件
+
+`1.2.0` 的双向桥梁扩展只有在以下闭环同时成立时才算完成：
+
+1. 未初始化或已初始化项目都可以机器可读地查询协议能力、schema 和永久边界；
+2. Context/Assist Bundle、Action Plan 和 Review Bundle 都有公开版本化 schema；
+3. AI 建议可以通过结构化 Action Plan 复用现有原语完成确定性预检，不需要拼接 shell 字符串；
+4. Review Bundle 完整展示 current/proposed、baseline、impact、blocker、item/source/path/projection 和 structured invocation；
+5. 任何人工批准前的交换都保持只读，任何过期 baseline 都失败封闭；
+6. 宿主 Agent 适配可替换，且不改变 Project Contract、scope、approval、ownership 或漂移语义。
+
+完整实现合同以 [17-AI-EXCHANGE-BOUNDARY-DESIGN.md](./17-AI-EXCHANGE-BOUNDARY-DESIGN.md) 为准。
+
 ## 8. 真实项目与实验规则
 
 `dtg-tmc-mobile` 和 `dtg-tmc-pc` 已经完成 B0。它们证明核心机制和首轮安全修补可以落在真实仓库结构中。
@@ -130,11 +149,12 @@ v1 只有在以下闭环同时成立时才算产品完成：
 任何新增建议必须先归入且只能归入一类：
 
 - **内核缺陷**：违反第 6 节不变量或第 7 节既定完成条件，可以进入设计；
+- **宪法级产品演进**：现有稳定价值或内核无法完整表达经用户确认的产品问题，必须按第 11 节单独获得产品方向变更授权；
 - **项目数据**：某项目自己的技术、目录、规则和业务语义，由 Project Contract 表达；
 - **可选适配器**：减少某种来源导入或消费者输出成本，不改变内核；
 - **外部工具职责**：继续采用现成工具，本项目拒绝实现。
 
-无法证明属于内核缺陷的建议，不得进入核心实现。多个项目重复出现也只能提高审查优先级，不能绕过这一分类。
+无法证明属于内核缺陷，且没有按第 11 节获得宪法级产品演进授权的建议，不得进入核心实现。多个项目重复出现也只能提高审查优先级，不能绕过这一分类。
 
 ## 10. 当前事实职责与阶段停止规则
 
@@ -164,3 +184,15 @@ v1 只有在以下闭环同时成立时才算产品完成：
 2. 第 10 节删除会随时间失效的具体“当前下一步”，把当前事实、授权和下一步的唯一记录职责交还给 `PROJECT_STATE.json`；
 3. 产品身份、固定用户问题、内核、永久边界、不变量、需求分类和已有用户数据合同均未改变；
 4. 本次修订不授权产品代码、Git、真实项目、自托管 Project Contract、看板、团队验收或发布工作。
+
+## 13. `1.2.0` 双向桥梁修订记录
+
+本次修订经用户于 `2026-09-09` 在确认“主要功能就是项目与 AI 之间桥梁，有必要可以扩大自研内核”后明确要求执行，变更如下：
+
+1. 第 2 节把单向上下文输出补全为项目 → AI 与 AI → 项目的双向桥梁；
+2. 第 3 节增加“模型无关、可预检、不扩张人工权限的交换协议”作为第四项稳定价值；
+3. 第 4 节新增 AI Exchange Boundary 作为第七项自研内核；
+4. 第 6 节新增 AI 建议不是真源、批准或持久权限的不变量；
+5. 第 7.2 节新增 `1.2.0` 双向交换完成条件；
+6. Provider、Agent Runtime、开发任务执行、Git、网络、自动批准、业务代码修改和框架识别白名单仍在永久边界外；
+7. 本次授权只包含宪法修订、`1.1.0` 完整性修正和 `docs/17` 设计落盘，不自动授权 `1.2.0` 产品代码、真实项目、Git 写入或发布。