frontend-project-context 1.7.0 → 1.8.0

package/docs/28-REAL-PROJECT-ONBOARDING-CLOSURE-DESIGN.md

@@ -0,0 +1,534 @@
+# 28 — 真实项目初始化与上下文入口改造设计
+
+> 日期：`2026-09-15`
+>
+> 状态：`frozen-design; local-implementation-complete; real-host-acceptance-passed; release-authorized-in-progress`
+>
+> 证据：`frontend-project-context@1.7.0` 在真实 `dtg-tmc-pc` 仓库中的正式接入过程，以及随后无历史 Host 的接管结果。
+>
+> 目标版本：`1.8.0 — Real Project Onboarding Closure`
+>
+> 边界：本文冻结实现接口、执行顺序、验收与停止条件；不授权产品实现、目标项目再验证、Provider、Git、发布或业务代码修改。
+
+## 1. 这次观察真正证明的问题
+
+当前产品把“初始化”做成了治理容器初始化：创建三个 store、插入一段 AI Entry、让状态回到 clean。这个结果不能叫目标项目初始化成功。
+
+真实目标是：
+
+> AI 读取当前安装包中唯一、明确的初始化指令，在目标项目范围内自行分析和改造项目上下文入口，生成足够支撑直接开发的完整真源与 Project Contract；之后任何新 AI 都能从改造后的入口取得这些上下文并进入开发。
+
+这次过程虽然最终手工登记了一批 source/item，并验证了 scope context，但产品自身没有把这条流程交付给 Host。无历史 Host 只看到 `status.health=clean`，没有消费任务 Contract，说明产品仍未真正用起来。
+
+## 2. 三个角色的固定职责
+
+### 2.1 安装包
+
+安装包必须提供初始化的唯一规范和机器可发现入口。它负责告诉 Host：
+
+- 初始化的目标是什么；
+- 只能在哪个目标项目根内工作；
+- 应按什么顺序读取、分析、治理和写入；
+- 哪些结果必须交给人确认；
+- 什么证据才算初始化完成；
+- 遇到不存在、空目录、partial、冲突时如何继续或停止。
+
+这套流程必须来自安装包，不依赖 Host 猜测，也不依赖用户知道低层 CLI。
+
+### 2.2 Host AI
+
+Host AI 是安装包初始化规范的执行者，也是目标项目的语义分析者。它负责：
+
+- 读取包内初始化规范；
+- 锁定用户指定的目标项目根；
+- 只在目标项目根内读取项目入口、规范、配置和必要源码；
+- 分析哪些内容是真实当前事实、哪些是有效规则、哪些已经漂移、哪些只是历史资料；
+- 依据包内规范改造目标项目上下文入口；
+- 生成 sources、items、scope、provenance 和验证说明；
+- 把需要人判断的语义集中展示；
+- 获得批准后执行机械写入并验证新 AI 接管。
+
+Host 不负责发明初始化步骤、产品机制、项目规则或上级目录真源。
+
+### 2.3 用户
+
+用户负责给出目标项目和“初始化”意图，并对长期项目真源作最终确认。用户不负责：
+
+- 发现命令；
+- 选择 register/propose/approve 的执行顺序；
+- 判断哪份 plan 或日志要保留；
+- 手工推动每一个中间步骤；
+- 告诉 Host 下一步该读哪个文件。
+
+## 3. 目标项目边界
+
+初始化必须先冻结一个明确的 `targetRoot`。此后：
+
+- 项目分析、真源候选、源码和配置读取不得越过 `targetRoot`；
+- 不得向上寻找另一个项目的 `RTK.md`、设计文档、Project Contract 或工作流；
+- Host 平台自动注入的父级指令只约束 Host 的安全行为，不能被登记为目标项目真源；
+- 包内初始化规范来自当前目标项目安装的 `frontend-project-context` 包，不等于读取父级自研仓库；
+- 任何目标根外资料只有在用户明确指定时才能作为 external reference 候选，不能静默参与初始化。
+
+这次 Host 从目标项目跑到上级目录读取 `RTK.md`，属于 Host 边界失败，不是正常的 include 解析需求，也不能据此设计父级真源链。
+
+## 4. 接入版本与目标项目规范的关系
+
+两个层次不能混在一起：
+
+1. **初始化方法**以目标项目当前安装包内规范为准。旧 AGENTS 中的 plan、日志、OpenSpec 或其他标准流程不能改写初始化步骤。
+2. **项目内容**只从目标项目自身寻找。现有 AGENTS、README、docs、配置和源码都是候选，需要对照当前实现判断，不能因为文件存在就直接服从。
+
+安装包不替目标项目发明规范。它只要求 Host 用统一方法把目标项目真实存在的事实和规则治理成 Contract。
+
+## 5. 完整初始化流程
+
+### 阶段 1：读取包内初始化规范
+
+Host 在目标项目本地依赖中找到与已安装版本一致的初始化指令，确认：
+
+- 包名和精确版本；
+- targetRoot；
+- 产品边界和人工批准边界；
+- 当前目标项目是未初始化、已初始化、空目录、partial 还是 invalid；
+- 本轮只做初始化，不执行业务开发、Git 或发布。
+
+包不存在时停止并报告安装需求；不得下载或读取其他目录中的替代实现。
+
+### 阶段 2：分析目标项目，而不是先创建空容器
+
+在写入 `.project-context` 前，Host 只读分析目标项目中的：
+
+- AI 上下文入口及其引用；
+- package/build/format/lint/test 等实际配置；
+- 应用启动、路由、请求、状态、国际化等稳定工程入口；
+- 团队声明的规范与当前实现是否一致；
+- 历史文档、计划、日志、review cache 是否仍被真实流程消费。
+
+读取范围由目标项目结构和包内规范决定，不由 Host 自己发明“标准流程”。必要源码用于验证事实，不等于把全部源码登记为长期真源。
+
+### 阶段 3：先治理上下文入口
+
+Host 必须先给出目标入口改造结果：
+
+- 保留仍然有效的项目边界；
+- 修正与当前配置或代码冲突的描述；
+- 删除或降级不再使用的强制流程；
+- 去掉默认生成但没人消费的 plan、日志和 review 要求；
+- 把根入口收敛为“如何进入 Project Contract 和任务上下文”；
+- 把长期事实和规则迁移到 Project Contract，而不是继续堆在入口正文。
+
+入口改造不是只插入四五行 marker。它要让新 AI 不会再次绕过 Project Contract、服从过期流程或自行扩张读取范围。
+
+### 阶段 4：生成完整真源与 Contract
+
+Host 根据已验证的目标项目事实，生成本项目实际需要的：
+
+- source：稳定 ID、类型、目标根内 locator、digest；
+- item：fact、policy、reference、validation-description；
+- scope：project、path-prefix、file；
+- provenance、verification 和必要 override；
+- 入口与 Contract 的关系；
+- 尚未确认或无法验证的明确缺口。
+
+“完整”不是把所有文件登记进去，而是：对目标项目已识别的关键开发入口、工程约束和团队规则没有静默空白；新 AI 执行代表性真实任务时，不需要回到旧文档猜测基本流程。
+
+如果 Host 仍有未决权威冲突或关键入口未覆盖，初始化必须保持未完成，不能用三个 store 已存在来掩盖。
+
+### 阶段 5：一次集中语义确认
+
+Host 向用户一次展示：
+
+- 上下文入口将如何改造；
+- 哪些旧规范保留、修正、降级或排除，以及依据；
+- 将登记的 source；
+- 将批准的 Contract item、scope 和来源；
+- 仍未解决的冲突或缺口；
+- 初始化后新 AI 的实际入口。
+
+用户确认的是目标项目语义和入口结果，不是逐条 CLI 命令。Host 在同一授权范围内完成后续机械步骤；出现新对象或新冲突时才重新请求确认。
+
+### 阶段 6：落地与清理
+
+Host 按包内规范执行已有安全原语，最终目标项目只保留：
+
+- `.project-context/contract.json`；
+- `.project-context/sources.lock.json`；
+- `.project-context/projections.lock.json`；
+- 已改造并获准保留的项目上下文入口；
+- 固定版本依赖所需的 package 变更。
+
+proposal、Action Plan、Review Bundle、日志、临时摘要只在执行中存在；如果后续没有消费者，不能留在目标仓库中。
+
+### 阶段 7：真正的接管验收
+
+启动一个不继承初始化对话的新 Host，只给它目标项目和一项真实开发需求。它必须：
+
+1. 从目标项目入口发现 Project Context；
+2. 读取当前任务适用的 Contract；
+3. 输出实际命中的 item IDs、scope 和必要 source/read targets；
+4. 按这些上下文进入目标源码；
+5. 不读取目标根外的自研仓库或上级项目资料；
+6. 不重新服从已被入口治理排除的旧流程。
+
+未发生第 2 至第 4 步，初始化失败；无论 `.project-context` 是否完整、`status` 是否 clean，都不能改判成功。
+
+## 6. 初始化成功定义
+
+成功必须同时满足：
+
+- 当前安装包的初始化规范被 Host 实际读取和遵循；
+- targetRoot 明确且全过程未越界；
+- 目标项目上下文入口已经按真实项目现状改造；
+- 关键目标项目真源已登记，Contract 中存在经人批准且有来源的有效 items；
+- 旧规范冲突已修正、降级、排除或明确阻断；
+- 没有无人消费的 plan、日志、proposal 或 review 残留；
+- Project Context 治理状态 clean；
+- 代表性路径能编译出符合 scope 的上下文；
+- 无历史 Host 能从入口读取 Contract 并直接进入真实开发任务。
+
+以下都不能单独叫初始化成功：
+
+- 创建了 `.project-context` 目录；
+- 创建了三个 store；
+- 插入了 AI Entry marker；
+- `status` 返回 clean；
+- CLI 测试通过；
+- 手工调用一次 context 成功；
+- 当前有历史对话的观察窗口知道下一步。
+
+## 7. 本次真实卡点的准确归类
+
+### 产品流程缺陷
+
+- 包内没有把完整初始化规范可靠交付给 Host；
+- 初始化没有强制先治理目标上下文入口再生成 Contract；
+- 用户被暴露给低层命令和重复确认；
+- 完成条件停留在文件/状态，而不是新 AI 直接开发。
+
+### Host 执行缺陷
+
+- 越过 targetRoot 读取上级 `RTK.md`；
+- 没有按目标项目范围寻找真源；
+- 把 `status` 维护字段当成任务上下文结果；
+- clean 后未读取 Contract 就准备进入源码。
+
+### 已观察到的实现卡点
+
+- 空 `.project-context` 被错误判为 partial；
+- 发布入口后，若该入口同时是 source，会触发预期 digest 变化；
+- 临时 proposal/plan 的默认持久化增加垃圾和操作成本。
+
+这些实现卡点只能在完整流程固定后统一修，不能继续逐个补丁推动产品方向。
+
+### 外部环境事件
+
+- npm 用户缓存权限；
+- Provider 模型缓存解析；
+- 网络超时和 WebSocket/HTTPS 重连。
+
+它们需要单独报告，但不能混入目标项目真源设计，也不能诱导 Host 读取上级目录。
+
+## 8. 冻结实现合同
+
+### 8.1 版本与分类
+
+本闭环作为 `1.8.0 — Real Project Onboarding Closure` 实现。它修复产品宪法第 7 节“项目可以按文档独立、安全初始化并被 AI 使用”的完成缺口，不修改产品身份、内核或永久边界，因此不需要宪法变更。
+
+`1.8.0` 不包含 A-144、Sidecar、Provider、Agent Runtime、业务开发执行、Git 或发布自动化。
+
+### 8.2 包内唯一初始化指令与发现接口
+
+唯一规范文件固定为：
+
+```text
+docs/AI-PROJECT-INITIALIZATION.md
+```
+
+它随 npm 包发布，是 Host 初始化流程的唯一正文。README、CLI help 和操作手册只能引用它，不能复制另一套流程。
+
+新增只读命令：
+
+```text
+project-context instructions --project PATH [--json | --prompt]
+```
+
+固定行为：
+
+- 在 `.project-context` 不存在时也可运行；
+- 只使用当前目标项目本地安装的包代码和包内指令，不下载、不回退到其他版本；
+- `--project` 经 realpath 固定为 `targetRoot`，不存在的目录或越界 symlink 失败封闭；
+- `--prompt` 输出 Host 可直接执行的完整 Markdown 指令；
+- `--json` 输出 `initialization-instruction` schema 1，至少包含 package name/version、instruction id/version/packagePath/digest/content、resolved targetRoot 和永久边界；
+- 不读取目标项目正文、不创建 store、不生成 proposal、不授予写入权限。
+
+`capabilities` 升为 schema 8 / exchange protocol 8，并新增 `initializationInstruction` 描述，固定公开 instruction id、version、packagePath、digest 及上述命令；现有 `initialization` 状态字段继续保留。这样 Host 可以从 CLI help 或 capabilities 确定性发现同一指令，安装路径和 pnpm symlink 细节不暴露给用户流程。
+
+### 8.3 一次集中语义确认的绑定对象
+
+Host 在任何持久写入前完成目标项目只读分析，并向用户展示一个不落盘的集中审查视图。该视图不是新的长期 schema 或仓库工件，但授权必须绑定以下精确内容：
+
+- package version 与 instruction digest；
+- resolved targetRoot；
+- 将写入 store 的 project id 与 name；
+- 项目入口原始 digest、完整改造 diff 和预期最终 digest；
+- 保留、修正、降级、排除的旧规范及依据；
+- 完整 proposal digest、全部待批准 item IDs、source IDs、scope、provenance 与 verification；
+- 每个已识别关键开发域的处置：纳入 Contract、经人确认排除，或 unresolved blocker；
+- 初始化后选取的代表性任务路径；
+- 将被清理的短生命周期工件。
+
+存在 unresolved blocker 时不能请求批准。用户的一次“确认/批准”只覆盖上述 digest 和 ID 集合；执行中出现内容变化、新对象、新冲突或 baseline 漂移，原授权立即失效并返回新的集中审查，而不是逐条追问 CLI 操作。
+
+### 8.4 两类项目状态的执行顺序
+
+#### 未初始化或只有空 `.project-context`
+
+空 `.project-context` 必须等同未初始化，而不是 partial。集中审查获批后，Host 按固定顺序执行：
+
+1. 重新验证 package version、instruction digest、targetRoot、入口 before digest 和 proposal 输入来源；
+2. 运行现有 `setup --write` 创建三个治理 store；该动作只是机械 bootstrap，不得报告初始化成功；
+3. 对目标入口的人工拥有区域应用已批准的精确 diff；
+4. 运行 `publish-entry --write` 写入产品拥有的受管 marker；
+5. 验证入口完整文件等于审查中的预期最终 digest；
+6. 将已批准的完整 proposal 以 create-only 方式暂存为 `.project-context/initialization.proposal.json`；
+7. 对 proposal 中全部已批准 IDs 执行一次 `approve --proposal ... --ids ... --write`；复用当前 `approveProposal` 同时登记所引用 sources、校验实时 digest 并批准 items 的能力；
+8. 删除 setup proposal 和 initialization proposal；
+9. 执行 `check`、`status`、代表性路径 `context`，验证 Contract 命中结果。
+
+入口若本身是 proposal source，其 source digest 必须绑定第 5 步的最终文件内容，避免 publish-entry 后立即形成预期 source drift。
+
+#### 已初始化项目
+
+不得重新 setup 或覆盖 store。Host 先运行 `status/sync`，把现有 Contract、source drift、入口状态与新分析放进同一个集中审查。获批后复用现有 register/revise/accept/reapprove/publish 原语完成一次机械执行；任何 `partial`、`invalid`、ownership conflict 或无法绑定的 baseline 都停止写入并返回恢复证据。
+
+这两条路径对用户呈现相同的一个语义审查，不把底层命令序列变成用户操作手册。
+
+### 8.5 AI Entry renderer 4
+
+AI Entry 升为 renderer 4，固定以下启动语义：
+
+```text
+运行本地离线 status
+→ uninitialized：读取 instructions，执行完整初始化流程
+→ partial / invalid：停止写入并报告恢复证据
+→ attention：执行对应 sync/maintenance 工作单元
+→ clean：根据真实任务确定 targetRoot 内目标路径
+→ 必须运行 context --path ... --task ... 并消费命中的 Contract
+→ Contract 非空、scope 命中且必要 read targets 到位后，才进入源码开发
+```
+
+clean 不再等于直接执行任务。入口必须要求 Host 报告实际命中的 item IDs 和 scope；没有适用 item 或关键上下文覆盖不足时，报告 onboarding/context gap，不得假装已取得项目规范。
+
+目标入口人工区域的治理仍由 Host 在用户批准的精确 diff 下完成；产品只拥有 marker，不扩大为任意文件覆写器。
+
+### 8.6 状态与完成语义
+
+`project-status` 升为 schema 2，新增独立的 `contractReadiness`：
+
+- `not-initialized`：store 尚未建立；
+- `contract-incomplete`：store 存在，但 active source、approved item 或 current AI Entry 任一项缺失；
+- `contract-ready`：治理健康为 clean，存在 active sources 和 approved items，AI Entry 为 current。
+
+`health` 继续只表达治理健康，不能代替 readiness。`clean + empty Contract` 的 next action 必须是 `complete-onboarding`，不得再返回 `ready-for-task`；`contract-ready` 的下一动作改为 `compile-task-context`，明确真实任务仍须先消费 Contract。
+
+`contractReadiness=contract-ready` 只证明目标项目具备编译上下文的结构条件，不宣称初始化全流程或真实任务已经成功。代表性 scope context 仍必须在本轮初始化中实际运行；一次真正的无历史 Host 接管是 `1.8.0` 发布前的外部产品验收门，二者都不能由状态字段自证。
+
+### 8.7 工件策略
+
+- setup proposal 与 initialization proposal 只允许出现在 `.project-context/` 的短生命周期路径，写入必须 create-only；
+- 成功后必须删除，失败时默认删除，只有用户明确要求恢复证据时才保留；
+- 集中审查、Action Plan 和 Review Bundle 默认留在 Host 会话或系统临时目录；
+- 不新增日志、长期 plan、review cache、初始化 receipt 或第二份项目真源；
+- 三个 store、受管 marker 和用户确认保留的项目入口是唯一长期初始化产物。
+
+## 9. 冻结验收合同
+
+### 9.1 本地确定性验收
+
+实现至少新增以下独立验收：
+
+| ID | 验收事实 |
+| --- | --- |
+| O-01 | 未初始化项目可通过 help、capabilities 和 `instructions` 得到同一包内指令、版本与 digest，且全程只读、离线。 |
+| O-02 | `instructions` 将 `--project` 固定为 resolved targetRoot，并拒绝不存在路径、父级真源扫描和越界 symlink。 |
+| O-03 | 不存在和空 `.project-context` 都进入未初始化流程；缺少部分 store 才是 partial 并失败封闭。 |
+| O-04 | setup preview/write 不再被断言为完整初始化，空 Contract 即使 health clean 也为 `contractReadiness=contract-incomplete`。 |
+| O-05 | 一份包含多个 sources/items/scopes 的 proposal 可在一次 approval 中原子登记并批准，任一 source digest 变化则零写入。 |
+| O-06 | 入口人工区域精确 diff 与受管 marker 可以共同落地；最终完整 digest 被 proposal source 绑定，完成后无预期 drift。 |
+| O-07 | AI Entry renderer 4 在 clean 状态仍强制执行 task/path context，并在 Contract 空或未命中时停止。 |
+| O-08 | 已初始化 clean、attention、partial、invalid 四类状态分别走维护、恢复或上下文路径，不重复 setup。 |
+| O-09 | 成功后 setup/initialization proposal、Action Plan、Review Bundle 和日志没有仓库残留。 |
+| O-10 | 代表性 project/path-prefix/file scope 均能返回预期 item IDs，sibling scope 继续隔离。 |
+| O-11 | capabilities 8、instruction schema 1、project-status 2、AI Entry renderer 4 的兼容和升级声明完整，旧项目可先 upgrade-check。 |
+| O-12 | npm pack 内容只包含声明的唯一初始化指令，不存在 README、manual、help 与指令正文的流程分叉。 |
+
+现有 A-88 改名并限缩为 store/entry 健康测试；A-89 改名并限缩为 CLI 路由 fixture，不得继续作为 Host 接管证据。
+
+### 9.2 真实 Host 发布阻断验收
+
+在本地 O-01 至 O-12 全部通过且另获真实项目授权后，使用正式候选包执行一次完整接入：
+
+1. 初始化 Host 不继承本设计讨论，只得到目标项目、用户初始化意图和本地安装包；
+2. 用户只进行一次集中语义确认；
+3. 初始化后仓库满足第 6 节全部条件；
+4. 第二个无历史 Host 只得到目标项目和一项真实开发需求；
+5. 它留在 targetRoot，先从入口运行 context，报告命中的 item IDs/scope/source，再进入真实源码；
+6. 它不读取父级自研仓库，也不执行已被入口治理排除的旧流程。
+
+任一条件失败，`1.8.0` 不得发布。只修冻结流程内的确定性阻断；不得在该轮加入新产品方向。
+
+## 10. 有界开发计划
+
+### 工作单元 1：指令交付
+
+- 新增唯一包内指令；
+- 实现只读 `instructions`；
+- 升级 capabilities/schema/help/README/manual 的引用；
+- 完成 O-01、O-02、O-12。
+
+### 工作单元 2：初始化机械闭环
+
+- 修正空目录分类；
+- 固定完整 proposal 一次批准和最终入口 digest 顺序；
+- 清理短生命周期工件；
+- 完成 O-03、O-05、O-06、O-08、O-09。
+
+### 工作单元 3：入口与 readiness
+
+- 实现 AI Entry renderer 4；
+- 实现 project-status schema 2 与 contractReadiness；
+- 降级 A-88/A-89 的证明范围；
+- 完成 O-04、O-07、O-10、O-11。
+
+### 工作单元 4：本地封版与外部验收准备
+
+- 运行完整回归、package metadata/schema/pack 检查；
+- 更新版本、迁移说明和候选包证据；
+- 输出一次真实项目验收所需的最小交接，不执行真实项目、Provider、Git 或发布。
+
+每个工作单元只修自己的失败；遇到需要 Provider、Agent Runtime、任意业务文件写入器、自动批准、父级项目真源或新长期工件的方案，立即停止并判定偏离设计。
+
+## 11. 实现文件边界
+
+预计允许修改：
+
+- `docs/AI-PROJECT-INITIALIZATION.md`、README、操作手册、升级说明；
+- CLI/capabilities/instruction loader；
+- project-store 的空目录判定；
+- setup/approval 周边的初始化编排辅助，但不新增通用 apply；
+- AI Entry renderer、project status；
+- 对应 schema、migration manifest、fixtures 和测试；
+- package version/metadata 与 `PROJECT_STATE.json`、`RTK.md` 的实现事实同步。
+
+明确禁止：
+
+- 修改产品宪法；
+- 实现 Provider、Agent Runtime、业务任务执行或任意业务代码写入器；
+- 自动批准 Contract；
+- 向上扫描项目真源；
+- 自动安装、网络、Git、发布；
+- 把 A-144、Sidecar、Persistent KV、日志系统或新 discovery 白名单并入 `1.8.0`。
+
+## 12. 新开发窗口授权入口
+
+新窗口只需读取：
+
+1. `docs/00-PRODUCT-CONSTITUTION.md`；
+2. `PROJECT_STATE.json`；
+3. `RTK.md`；
+4. 本文第 8 至第 11 节；
+5. 当前未提交差异，避免覆盖本次设计前已存在的改动。
+
+授权语句应明确为：
+
+> 按 `docs/28-REAL-PROJECT-ONBOARDING-CLOSURE-DESIGN.md` 冻结合同实现 `1.8.0`，只完成本地代码、schema、文档和 O-01 至 O-12 验收；保护现有未提交改动，不访问真实目标项目，不调用 Provider，不执行 Git、网络或发布。完成后归档实现事实并停止，等待真实 Host 验收授权。
+
+该语句才授权实现；本文归档和普通“继续/确认”均不扩张执行权限。
+
+## 附录 A：冻结设计依据的代码与安装包核对结果
+
+冻结接口前已经完成只读代码核对，当前 `1.7.0` 事实如下。
+
+### A.1 包内没有唯一 Host 初始化指令
+
+`package.json.files` 会发布 `bin/`、`src/`、`schemas/`、`docs/`、`examples/` 等内容，npm 也会携带根 README；但当前没有一份被声明为 Host 初始化唯一入口的文件。首次接入说明分散在：
+
+- 根 README 的多处中英文段落；
+- `docs/USER-AND-AI-OPERATION-MANUAL.md`；
+- CLI help；
+- 初始化完成后才可能写入的 AI Entry。
+
+`capabilities` 只返回命令、schema、版本和永久边界，没有返回初始化指令路径、targetRoot 规则、入口治理要求或完成条件。Host 因此只能自行拼装流程。
+
+### A.2 当前 setup 只建立容器
+
+`runSetup` 的写入结果是：
+
+- 初始化三个 store；
+- 写一份 `.project-context/setup.proposal.json`；
+- proposal 保持 proposed；
+- 不负责目标入口治理；
+- 不负责 Host 的语义分析；
+- 不生成已批准的完整 Project Contract。
+
+这套原语本身没有违反安全边界，但不能继续被描述成用户层“项目初始化完成”。
+
+### A.3 当前 AI Entry 在 clean 后跳过 Contract 消费
+
+renderer 3 的 clean 分支原文语义是“继续遵守本文件其余仓库规则，并执行用户任务”。它没有要求 Host：
+
+- 根据任务定位目标路径；
+- 编译适用的 Project Contract；
+- 报告命中的 item/source；
+- 在 Contract 为空或关键覆盖缺失时停止。
+
+因此真实 Host 从 status 直接走向源码，是当前入口允许的结果，不应只归责于模型。
+
+### A.4 当前验收错误地把文件和 clean 当作接管
+
+- A-88 只运行 setup write、publish-entry 和 status，然后以 `health=clean` 判定接管闭环；它没有批准任何目标项目语义，也没有证明 Contract 非空。
+- A-89 不是一次真实 Host 运行。测试代码只读取 AGENTS、直接调用 CLI status，并断言 `nextActions=[ready-for-task]`；没有 AI、没有目标任务、没有 context 调用、没有源码入口。
+- 历史 registry/隔离副本验收额外手工调用过一次正常 task context，只证明 Context Compiler 可用，不证明新 Host 会从入口自动使用它。
+
+因此已有测试覆盖了原语，不覆盖用户所说的完整初始化。
+
+### A.5 现有原语可以复用，但不能继续暴露为用户流程
+
+当前已有：
+
+- setup/sync Assist Bundle；
+- register/propose/approve；
+- Action Plan 与只读 preflight；
+- publish-entry；
+- context/context-query；
+- source review、accept、reapprove 与 check/status。
+
+真正缺失的是安装包交付给 Host 的完整指令和端到端完成门。第 8 至第 11 节据此只新增必要的只读指令接口与完成语义，并复用现有安全原语。
+
+## 13. 本地实现事实归档
+
+`2026-09-15`，用户使用第 12 节精确授权语句批准本地实现。实现保持第 8 至第 11 节冻结边界，结果如下：
+
+- 包版本提升为 `1.8.0`，新增唯一包内指令 `docs/AI-PROJECT-INITIALIZATION.md` 和只读 `instructions --json|--prompt`；
+- capabilities / Exchange Protocol 升至 8，新增 initialization-instruction schema 1；project-status 升至 schema 2，并新增独立 `contractReadiness`；
+- AI Entry 升至 renderer 4，clean 状态仍强制 task/path context、实际 item IDs/scope/read targets 和 onboarding/context gap 停止语义；
+- 空 `.project-context` 继续按未初始化处理；完整 proposal 复用现有 `approveProposal` 原子批准，入口最终 digest 可作为 proposal source checkpoint；
+- Migration Manifest 加入 `1.7.0 → 1.8.0` 的显式 AI Entry republish 路径；Contract、source lock、proposal、projection lock 和普通 projection renderer 无迁移；
+- 新增独立 O-01 至 O-12，`npm run check` 共 207/207 通过；
+- 未新增 Provider、Agent Runtime、通用 apply、业务代码写入器、长期初始化 store、日志或 cache。
+
+本轮没有访问真实目标项目，没有调用 Provider，没有执行 Git、网络或发布。真实目标项目的完整初始化与第二个无历史 Host 接管仍是 `1.8.0` 发布前的独立阻断验收，必须另获授权；A-144 与 Sidecar 继续后置。
+
+## 14. 真实 Host 发布阻断验收事实归档
+
+`2026-09-15`，用户另行授权并对集中语义审查结果进行一次确认。验收使用本地 `frontend-project-context-1.8.0.tgz` 正式候选包，在真实 `dtg-tmc-pc` 的隔离副本中执行；真实目标原仓库始终只读，未写入任何 onboarding 或业务文件。
+
+- 候选包 SHA-256 为 `3e74ce4205e481631ca28b60a54aef2c4457c0a3896328b593999308e1953524`，包内初始化指令 digest 为 `sha256:8ec3bbf0202c3893514325db3f48d23adbcf18d7668b9731ac4f10e2a3be4d9e`；
+- 集中审查绑定 proposal digest `sha256:7e3c7e2af58ef7d228d481604137fe164fb1756c59e8f3c9b7a0e217df4c5e0b`、19 个 source、18 个 item、入口完整 digest `sha256:8866d00904beefe30464c55670e705848002b8c4afd5e5fc1cc22149098034fc` 与 package.json digest `sha256:c9764da564cc7c15dcfd64e753b05ad9eacda9542edc268cb6551907d645e81d`；
+- 确认后按冻结顺序机械执行 setup、精确入口 diff、renderer 4 marker 发布、最终 digest 校验和一次原子 proposal approval；setup/initialization proposal 与遗留 `init.txt` 随后从隔离副本移除；
+- 最终 `check` 无 finding，`status` 为 `health=clean`、`contractReadiness=contract-ready`，Contract digest 为 `sha256:65eebab516c58382d94ceb8dd44a2280347d048fd515b928dac286a2c21fcaa7`；project、`path-prefix:src`、`path-prefix:src/router` 与两个精确 flight file scope 均完成代表性 context 验证；
+- 第二个无历史 Host 只获得隔离 targetRoot 与真实只读任务。它自行从 AGENTS 入口执行 `status → context`，先报告实际命中的 item IDs、scope 和 source，再读取 `protocolPriceDialog.vue`、`submitTripBtn.vue` 及必要调用方，完成 `priceDetails` 展平与 `orderSerialNo` 传递链路定位；
+- fresh Host 全程留在 targetRoot，未继承初始化讨论，未写文件，未执行 Git、网络、Provider、构建、安装、发布或业务代码修改。
+
+据此，第 9.2 节真实 Host 发布阻断验收通过。该授权已经消费；用户已于同日另行授权 `1.8.0` 发布，发布结果将在完成后继续归档。Provider、A-144、Sidecar、真实目标写入与业务代码修改继续后置。

package/docs/AI-PROJECT-INITIALIZATION.md

@@ -0,0 +1,89 @@
+# AI Project Initialization
+
+> Instruction ID: `ai-project-initialization`
+>
+> Instruction version: `1`
+>
+> Applies to: the exact locally installed `frontend-project-context` package version that contains this file
+
+This is the package's only normative Host instruction for initializing a target project. Other package documents and CLI help may point here but do not define a competing initialization flow.
+
+## Objective
+
+Turn the user-selected target project into a development-ready, human-approved Project Contract. Initialization is complete only after the project entry is governed, the important project sources and scoped items are approved, temporary artifacts are gone, Project Context is healthy, and representative task context compiles. Store creation, an AI Entry marker, `health=clean`, or a successful CLI call is not sufficient by itself.
+
+## Authority and target boundary
+
+1. Use only the `frontend-project-context` code and this instruction from the target project's current local installation. Never download or fall back to another package version.
+2. Treat the resolved path reported by `project-context instructions --project PATH --json` as the immutable `targetRoot` for this run.
+3. Read project entries, documentation, configuration, and necessary source only within `targetRoot`. Do not search parent or sibling directories for `AGENTS.md`, `RTK.md`, design documents, contracts, workflows, or source material.
+4. A path or symlink that resolves outside `targetRoot` is not target-project evidence. Stop and report it; do not follow it.
+5. Platform-injected parent instructions may constrain Host safety but are not target-project truth. An external reference may participate only when the user explicitly names it.
+6. This flow does not authorize Provider calls, Agent Runtime, Git, network access, dependency installation, package-manager mutation, business-code changes, task execution, automatic approval, release, or publication.
+
+## Phase A: preflight and read-only analysis
+
+1. Record the package name/version, instruction ID/version/digest, and resolved `targetRoot` from `instructions --json`.
+2. Run the local CLI's read-only `status --json`.
+   - `uninitialized`, including an empty `.project-context` directory: continue read-only analysis.
+   - `partial` or `invalid`: stop all writes and return exact present/missing files and finding codes.
+   - `attention`, `conflict`, or initialized `clean`: do not run setup again. Include current Contract, source drift, entry ownership, and `sync` work units in the same review.
+3. Before creating stores, inspect only target-root material needed to establish current project truth: AI context entries and their references; package/build/format/lint/test configuration; stable application, routing, request, state, and localization entry points; active team rules; and whether historical plans, logs, or review caches are still consumed.
+4. Verify statements against current configuration or necessary source. A file's existence alone does not make its contents authoritative. Do not register all source code as long-lived truth.
+5. Identify each critical development domain as one of: included in the proposed Contract, explicitly excluded with a human-reviewed reason, or an unresolved blocker. Any unresolved blocker prevents approval.
+
+## Phase B: govern the project entry first
+
+Prepare an exact whole-file before digest, human-owned-region diff, and expected whole-file final digest for the target context entry.
+
+- Preserve valid project boundaries.
+- Correct descriptions contradicted by current configuration or source.
+- Downgrade or remove obsolete mandatory workflows and unconsumed plan/log/review requirements.
+- Make the root entry route every real task through local `status` and task/path `context` before source development.
+- Move durable facts and rules into the Project Contract instead of accumulating them in entry prose.
+
+The product may write only its marker-delimited managed region. Any change to the human-owned region requires the user's approval of the exact diff.
+
+## Phase C: prepare one concentrated semantic review
+
+Without writing to the target repository, present one review bound to all of the following:
+
+- package version and instruction digest;
+- resolved `targetRoot`;
+- project ID and name;
+- entry before digest, exact diff, and expected final digest;
+- each legacy rule retained, corrected, downgraded, or excluded, with evidence;
+- the complete proposal digest and every source ID, item ID, kind, value/statement, scope, provenance, and verification;
+- the disposition of every identified critical development domain;
+- representative project, path-prefix, and file task paths;
+- every short-lived artifact that will be removed.
+
+Do not request approval while any critical domain or authority conflict is unresolved. One user approval authorizes only this exact digest and ID set. Any changed input, new object, new conflict, or baseline drift invalidates approval and requires a new concentrated review.
+
+## Phase D: mechanical application after approval
+
+For an uninitialized project or an empty `.project-context` directory:
+
+1. Revalidate package version, instruction digest, `targetRoot`, entry before digest, proposal digest, and every proposal source digest.
+2. Run `setup --write` only to bootstrap the three stores; never report this as completed initialization.
+3. Apply only the approved human-region entry diff.
+4. Run `publish-entry --write` for the managed marker.
+5. Verify the entire entry's final digest. If the entry is a proposal source, the proposal must bind this final content.
+6. Create `.project-context/initialization.proposal.json` with create-only semantics.
+7. Run one `approve --proposal .project-context/initialization.proposal.json --ids <ALL_APPROVED_IDS> --by <REVIEWER> --write`. This existing primitive atomically registers referenced sources, rechecks live digests, and approves the selected items.
+8. Remove both `.project-context/setup.proposal.json` and `.project-context/initialization.proposal.json`.
+
+For an initialized project, never run setup or overwrite stores. Use `status` and `sync`, then apply the approved register/revise/accept/reapprove/publish operations against their exact current baselines. Stop on `partial`, `invalid`, ownership conflict, source drift not covered by the review, or any unbound baseline.
+
+On any failure, remove short-lived setup/initialization proposals unless the user explicitly requests those exact files as recovery evidence. Do not persist the semantic review, Action Plan, Review Bundle, initialization receipt, log, or cache in the repository.
+
+## Phase E: deterministic completion evidence
+
+Run all of the following inside `targetRoot`:
+
+1. `check` has no findings.
+2. `status --json` reports `health=clean`, `contractReadiness=contract-ready`, active sources, approved items, and current AI Entry renderer.
+3. Representative `context --path ... --task ...` calls prove project, path-prefix, and file scope hits and sibling isolation; record the actual item IDs, scopes, and necessary read targets.
+4. No setup proposal, initialization proposal, Action Plan, Review Bundle, log, or initialization cache remains in the repository.
+
+These facts establish local onboarding readiness, not full product acceptance. A separately authorized, memoryless Host must later receive only the initialized target project and a real development request, discover Project Context from the entry, consume the applicable Contract, report actual IDs/scopes/sources, remain within `targetRoot`, and only then enter target source. Until that external gate passes, stop and report that real Host acceptance is pending.

package/docs/README.md

@@ -8,6 +8,18 @@
 
    固定产品身份、内核、永久边界、v1 完成条件、真实项目规则、需求分类和阶段停止规则。动态的当前事实、授权和下一步由 `PROJECT_STATE.json` 唯一记录；其他文档与宪法冲突时，以宪法为准。
 
+## 讨论记录
+
+[27-TEAM-SHARED-CONTEXT-DIRECTION-DISCUSSION.md](./27-TEAM-SHARED-CONTEXT-DIRECTION-DISCUSSION.md)
+
+记录 `2026-09-14` 关于“让团队共同拥有同一份项目上下文”的产品意义、真实项目应用重点，以及 Stateful Agent、Persistent KV 和增量上下文的远期讨论方向。该文档仅供团队查看和继续讨论，不是冻结设计、路线或实现授权。
+
+## 已冻结、待实现设计
+
+[28-REAL-PROJECT-ONBOARDING-CLOSURE-DESIGN.md](./28-REAL-PROJECT-ONBOARDING-CLOSURE-DESIGN.md)
+
+基于 `2026-09-15` 在真实 `dtg-tmc-pc` 隔离副本中的正式接入与无历史 Host 接管过程，`1.8.0 — Real Project Onboarding Closure` 冻结并完成：包内唯一初始化指令、严格 targetRoot、目标入口治理、完整 proposal 一次语义确认、AI Entry renderer 4、project-status schema 2、O-01 至 O-12 以及无历史 Host 发布门。实现与 Host 验收事实见 `docs/28` 第 13、14 节；当前只执行用户另行授权的发布流程。
+
 ## 支持性设计文档
 
 1. [01-PRODUCT-CORE.md](./01-PRODUCT-CORE.md)