frontend-project-context 1.8.0 → 1.10.0

package/docs/31-TASK-CONTEXT-INTEGRITY-REPAIR-DESIGN.md

@@ -0,0 +1,281 @@
+# 31 — Task Context Integrity Repair 设计
+
+> 日期：`2026-09-22`
+>
+> 状态：`implemented-local; self-host-adopted; two-project-real-host-revalidation-passed`
+>
+> 目标版本：`1.9.1 — Task Context Integrity Repair`
+>
+> 权威边界：本文冻结 `1.9.0` 本地实现后发现的 Context 消费正确性修复、兼容合同与可证伪验收。`2026-09-22` 已按本文完成本地实现、自托管采用与两个真实项目的独立授权复验；该阶段未调用 Provider，未执行 Git、网络、打包或发布。后续打包与发布的授权及结果只由动态项目状态记录。
+
+## 1. 结论先行
+
+`1.9.0` 已完成 TC-01 至 TC-16 与既有回归，但后续自托管只读审计发现三个会破坏其冻结语义的内核正确性缺陷：
+
+1. task target 与 registered source 指向同一路径时，会生成重复 `readTargets.path`，随后被 Context Bundle 自身的严格 validator 拒绝；
+2. 同一 JSON 文件存在多个 `json-pointer` source 时，聚合记录没有合并全部 `pointers`，Host 可能获得不完整的最小读取位置；
+3. Context Bundle 与 Coverage Audit 各自解析 coverage profile，其中前者会把部分非法 v2 静默降级，导致同一 Contract 在两个入口产生不同结论。
+
+三项均属于 `docs/30` 已冻结能力的正确性缺陷，不是新产品能力、目标项目数据缺口或 Host 执行偏差。`1.9.0` 保留为“本地实现完成但被新证据阻断的未发布候选”；下一本地候选改为补丁版本 `1.9.1`。在本设计实现并通过验收前，不进入原定的两个真实项目 Host 复验。
+
+## 2. 已确认事实与缺陷归类
+
+| ID | 事实 | 分类 | 发布影响 |
+| --- | --- | --- | --- |
+| IR-01 | `consumptionRecords()` 分别用 `task:<path>` 和 `source:<path>` 建立记录；同一物理路径可出现两次 | P0 内核缺陷 | 阻断 1.9 真实 Host 复验 |
+| IR-02 | merge 只合并 role、item IDs、source IDs 和 reasons，不合并 `pointers` | P0 内核缺陷 | 阻断最小读取职责可信性 |
+| IR-03 | Context Bundle 使用宽松 coverage parser，Coverage Audit 使用严格 parser | P0 内核缺陷 | 阻断 coverage 结论一致性 |
+| IR-04 | `PROJECT_STATE.json` 的 compatibility 摘要仍残留 1.8.0 协议版本 | 动态事实缺陷 | 在冻结设计同步中修正，不算产品实现 |
+| IR-05 | 当前自托管 Contract 仍为 schema 1，尚未实际采用 consumption、digestMode 或 coverage profile | 本地采用缺口 | 纳入实现后的自托管采用门，不冒充内核缺陷 |
+
+本轮不把 npm cache `EPERM`、真实项目尚未复验或未启用 Provider 归入产品缺陷。
+
+## 3. 版本与永久边界
+
+### 3.1 版本裁决
+
+- 目标 package version 为 `1.9.1`；
+- 公共已发布基线仍为 `1.8.0`；
+- `1.9.0` 未打包、未发布、未做两个项目的真实 Host 复验；
+- `1.9.1` 是对 `1.9.0` 冻结语义的补丁修复，不新增用户能力；
+- 实现后从 `1.8.0` 或本地 `1.9.0` 进入 `1.9.1` 均为 `package-only`，不自动迁移任何目标项目 Contract。
+
+### 3.2 保持不变
+
+- 产品宪法、产品身份与七项内核不变；
+- Contract 可读 schema `1/2/3`、特性 schema `3` 不变；
+- Context Bundle schema `1` 不变；
+- Coverage Audit schema `2`、coverage profile v2 不变；
+- Capabilities / Exchange Protocol `9` 不变；
+- Initialization Instruction schema `2`、AI Entry renderer `5` 不变；
+- Project Status、projection renderer 和全部其他公开 schema 不变；
+- 不新增持久 store、CLI 命令、权限、Provider、Agent Runtime 或业务代码写入器。
+
+## 4. Read Target 唯一身份与聚合合同
+
+### 4.1 唯一身份
+
+`readTargets[]` 的唯一身份固定为规范化后的项目相对 `path`。task target、file source、path source 和 json-pointer source 不得再用不同前缀形成独立身份。
+
+所有贡献先进入同一个 path record，再统一输出：
+
+```text
+normalize path
+→ get-or-create one record by path
+→ merge role and all provenance fields
+→ remove provenance-only records from readTargets
+→ stable sort by path
+→ validate and seal bundle
+```
+
+每个规范化 path 最多输出一条 read target。严格 validator 继续拒绝外部构造的重复 path；修复的是 builder 不再生成非法数据，不是放宽 validator。
+
+### 4.2 完整、无损合并
+
+同一路径的所有贡献固定按以下规则合并：
+
+- `role`：按 `required > conditional > provenance-only` 取最强职责；
+- `itemIds`：完整并集、去重、稳定排序；
+- `sourceIds`：完整并集、去重、稳定排序；
+- `reasons`：完整并集、去重、稳定排序；
+- `pointers`：全部 json-pointer locator 的完整并集、去重、稳定排序；
+- 不存在 json-pointer contribution 时省略 `pointers`，不得输出空数组；
+- RFC 6901 的空字符串根 pointer `""` 是合法值，不得按假值过滤。
+
+如果 task target 与任意 source 同路径：
+
+- 最终 role 必须为 `required`；
+- 必须保留 `task-target` 和全部 `contract-source:*` reasons；
+- source/item provenance 不得因 task target 已要求读取而丢失；
+- `pointers` 只表达该路径关联的 JSON Pointer locator，不得覆盖或收窄 task target、file source 或 path source 的路径级读取职责。
+
+### 4.3 provenance-only 去重
+
+- 只有 provenance-only 贡献的路径不进入 `readTargets`；
+- 其来源继续按 source ID 出现在 `provenanceSources`；
+- 同一路径已有 required 或 conditional read target 时，相关本地 provenance source 只并入该 path record，不得再重复出现在 `provenanceSources`；
+- required target 的存在性检查每个 path 只执行一次；
+- 输入 target、item 和 source 的遍历顺序不得改变规范输出或 `bundleDigest`。
+
+## 5. Coverage Profile 单一解析源
+
+### 5.1 共享模块
+
+实现阶段抽取一个纯本地、无持久副作用的共享模块，例如：
+
+```text
+src/project-context/coverage-profile.mjs
+```
+
+该模块唯一负责：
+
+- 找到唯一 approved `policy / project.registration-coverage`；
+- 无 profile 时返回 `null`；
+- 多个 active profile 时返回 `coverage-profile-conflict`；
+- 严格解析和规范化既有 v1；
+- 严格解析 v2 exact keys、domain ID/path 唯一性、稳定顺序、disposition、itemIds、有效 scope 和 exclusion rationale；
+- 以最长路径优先、domain ID 打破平局的规则选择匹配 domain；
+- 返回供 Context Bundle 与 Coverage Audit 共同使用的规范结果。
+
+`context-bundle.mjs` 与 `adaptive-context.mjs` 不得继续保存各自的 parser。为避免内部调用漂移，后者可以 re-export 既有 helper 名称，但实现必须只有一处。
+
+### 5.2 失败封闭
+
+- 合法 v1/v2 的既有含义不变；
+- 非法 v2 不再静默降级为 v1；
+- 两个入口对非法 profile 都返回 `coverage-profile-invalid`；
+- 两个入口对多 active profile 都返回 `coverage-profile-conflict`；
+- 不自动把 v1 迁移为 v2；
+- 不自动生成、修改或批准 coverage；
+- Context Bundle 与 Coverage Audit 可以保留各自的展示映射，但不得重新解释 profile。
+
+## 6. 自托管采用门
+
+`1.9.1` 本地实现通过代码测试后，才允许在同一实现授权内使用现有治理原语完成有界 self-host adoption：
+
+1. 注册本文及 `PROJECT_STATE.json#/planning/taskContextIntegrityRepair` 为 source；
+2. 新增 `task.context.integrity-repair` Contract item；
+3. 对少量高价值现有 item 显式 author required/conditional source 职责，使 Contract 升级至 schema 3；
+4. 若登记根 `AGENTS.md` 作为人工真源，必须使用 `outside-owned-ai-entry` 且验证 marker/ownership；
+5. 新增 coverage profile v2 时，必须诚实区分 `contract-covered`、`dynamic-investigation`、`excluded-approved` 和 `unresolved`；不得把全仓伪装为已覆盖；
+6. 用已修复的 exact-path Context 对本文、`PROJECT_STATE.json`、`package.json` 等 registered source/多 pointer 路径做本地 dogfood；
+7. 最终 `check/status` 回到 clean。
+
+这一门只证明本仓库采用了 1.9 能力，不能替代两个真实项目的无历史 Host 复验。
+
+## 7. 兼容合同
+
+允许变化：
+
+- 受 IR-01/IR-02 影响的短生命周期 Context Bundle 内容和 `bundleDigest`；
+- 非法 coverage profile 从错误容忍收紧为失败封闭；
+- package/runtime/docs 中的候选版本事实从 `1.9.0` 更新为 `1.9.1`；
+- 自托管 Contract 在显式治理动作后使用 schema-3 字段和 coverage profile。
+
+必须保持：
+
+- CLI 命令与参数；
+- 纯文本 Context 与 `--json.content` 的选择语义；
+- 合法 Context Bundle schema 1 的字段形状；
+- schema-1/2 Contract 的只读字节稳定性；
+- source/projection lock 兼容；
+- 所有不受缺陷影响的 bundle 语义；
+- 现有 TC-01 至 TC-16 的断言不得删除、改名或弱化。
+
+## 8. 冻结验收合同
+
+| ID | 可证伪验收事实 |
+| --- | --- |
+| HC-01 | 任意 task/source contribution 聚合后，每个规范化 path 只产生一个记录，输出按 path 稳定排序。 |
+| HC-02 | task target 恰好也是 registered source 时，Context Bundle 成功生成；该 path 只出现一次、role 为 required，并保留 task 与 Contract reasons。 |
+| HC-03 | 表驱动覆盖职责格：仅 provenance 不进入 readTargets；conditional 压过 provenance；required 压过其余；task target 与任何来源重合均为 required。 |
+| HC-04 | 同一 path 由 task、required、conditional 和 provenance 多项共同贡献时，itemIds、sourceIds、reasons、pointers 均为完整、唯一、排序并集。 |
+| HC-05 | 同一 JSON 文件登记多个 json-pointer source 时只产生一个 read target，并完整保留根 pointer 与多个嵌套 pointer。 |
+| HC-06 | file/path/json-pointer 混合贡献及遍历顺序不改变 pointer/provenance 结果；无 pointer contribution 时省略 pointers。 |
+| HC-07 | 同一 source 被多个 effective item 以不同职责引用时，source ID 唯一、全部 item/reason 保留、职责取最强值。 |
+| HC-08 | 纯 provenance source 仍进入 provenanceSources；同 path 已有 read target 时不得重复出现。 |
+| HC-09 | 反转 target、item、source 顺序不改变 bundle 或 digest；手工构造重复 path 的 bundle 仍被严格 validator 拒绝。 |
+| HC-10 | 生产代码只有一个 coverage profile parser/selector；Context Bundle 与 Coverage Audit 均使用共享模块。 |
+| HC-11 | 合法 v2 的四种 disposition、outside-declared 和嵌套最长路径命中在两个消费者中一致。 |
+| HC-12 | v2 未知字段、重复 ID/path、非规范路径、非法 disposition、未排序 itemIds、无效 item 引用或缺 rationale 时，两入口均失败封闭。 |
+| HC-13 | 合法 v1 在两个入口继续可读；非法 v1 和多个 active profile 分别得到一致的 invalid/conflict 错误。 |
+| HC-14 | HC-01 至 HC-14、TC-01 至 TC-16 及全部既有 223 项回归通过；公开 schema/protocol/renderer 不升级，且实现过程无边界外副作用。 |
+
+若每个 HC 对应一个顶层自动化用例，最低总数为 `237/237`。最终实现事实必须记录实际测试数，但不得用计数替代上述语义断言。
+
+## 9. 有界实施单元
+
+### 工作单元 1：路径级消费聚合
+
+- 将 read target map key 收敛为 normalized path；
+- 完成 role 与所有集合字段的无损 merge；
+- 修复 provenance-only 去重和 required path 单次检查；
+- 完成 HC-01 至 HC-09。
+
+### 工作单元 2：Coverage 单一解释器
+
+- 抽取共享 parser/selector；
+- 两个消费者改用共享结果；
+- 保留合法 v1/v2 兼容并收紧非法 profile；
+- 完成 HC-10 至 HC-13。
+
+### 工作单元 3：版本事实、回归与本地采用
+
+- 更新 package、migration manifest、必要文档与测试版本事实到 `1.9.1`；
+- 保持公开安装/发布声明与实际 registry 状态一致；
+- 完成 HC-14、全部回归和第 6 节 self-host adoption；
+- 同步实现事实并恢复 clean。
+
+## 10. 预计实现文件边界
+
+允许范围：
+
+- `src/project-context/context-bundle.mjs`；
+- `src/project-context/adaptive-context.mjs`；
+- 一个共享 coverage profile helper；
+- `test/project-context/task-context-consumption.test.mjs`、必要 coverage 测试及 release metadata 测试；
+- `package.json`、`migration-manifest.json` 和现有包白名单/版本元数据；
+- README、操作手册、本文、`PROJECT_STATE.json`、`RTK.md`；
+- 通过正式治理命令完成的本仓库 Contract/source/coverage/consumption 同步。
+
+明确禁止：
+
+- 修改产品宪法；
+- Context Bundle schema 2、Contract schema 4、coverage profile v3；
+- 新 CLI、自动读取、自动批准、自动迁移或语义完整性声明；
+- 借补丁重构 discovery、scope compiler、renderer、source digest 或其他无关模块；
+- 访问或修改真实目标项目；
+- Provider、Agent Runtime、业务代码写入；
+- 依赖安装、Git、网络、打包或发布。
+
+## 11. 外部验收门
+
+本地 `1.9.1` 实现、HC-01 至 HC-14、全部回归及 self-host adoption 刚完成、尚未取得外部复验授权时，只允许声明：
+
+```text
+1.9.1-local-implementation-complete;
+two-project-real-host-revalidation-not-authorized;
+release-not-authorized
+```
+
+随后必须获得独立授权，才可在两个真实项目中使用同一冻结候选复验：未知路径 locate、跨页面/组件/API/store 多路径、registered source 与 task target 重合、typed read targets、coverage gap、最小读取和结束 clean。该授权及结果现已记录于第 14 节；Provider、打包与发布仍是更后的独立授权门。
+
+## 12. 已消费的实现授权
+
+本轮实现授权文本为：
+
+> 按 `docs/31-TASK-CONTEXT-INTEGRITY-REPAIR-DESIGN.md` 冻结合同实现 `1.9.1`，范围仅限本地产品代码、共享 coverage parser、版本元数据、文档、自托管 Contract 采用、HC-01 至 HC-14、TC-01 至 TC-16 及全部回归；保护现有工作，不访问真实目标项目，不调用 Provider，不执行依赖安装、Git、网络、打包或发布。完成后同步实现事实并停止，等待两个项目使用 `1.9.1` 冻结候选进行真实 Host 复验的独立授权。
+
+该授权已执行并消费完毕。未来不得据此继续访问真实项目、调用 Provider、执行 Git/网络/打包/发布，或扩大产品实现范围。
+
+## 13. 本地实现事实
+
+`2026-09-22` 已完成以下闭环：
+
+- package/runtime/migration/schema 版本事实更新为 `1.9.1`，公开 registry 基线仍如实保持 `1.8.0`；
+- read target 按规范化 path 唯一聚合，完整保留 role、item/source/reason 并集与所有 JSON Pointer；
+- `src/project-context/coverage-profile.mjs` 成为 Context Bundle 与 Coverage Audit 的唯一严格 parser/selector；
+- HC-01 至 HC-14、TC-01 至 TC-16 与全部回归共 `237/237` 通过；
+- 自托管 Contract 已升级为 schema 3，采用了显式 consumption、`outside-owned-ai-entry` 与 coverage profile v2；
+- Context Bundle schema 1、Coverage Audit schema 2、Capabilities / Exchange Protocol 9、Initialization Instruction schema 2 和 AI Entry renderer 5 均保持不变；
+- 未新增持久 store，未访问真实目标项目，未调用 Provider，未执行依赖安装、Git、网络、打包或发布。
+
+本地实现完成时的唯一下一步是等待独立授权，在两个真实项目中使用同一 `1.9.1` 冻结候选执行真实 Host 复验；该门已在第 14 节完成。
+
+## 14. 两项目真实 Host 复验事实
+
+`2026-09-22`，用户单独授权两个真实项目使用同一 `1.9.1` 冻结候选进行真实 Host 复验。两项目共同挂载只读候选快照 `sha256:be7d15fa66e289c6a7cf7e482649a2b5a6ded4d573c270cd2fa2d3ac883d78ee`，未运行 package manager，未修改 package manifest 或 lockfile。
+
+- `dtg-tmc-mobile` 从未知路径任务先执行 locate，再收敛到 `pages/trip/index.vue`、`pages/trip/components/non-whitelist-confirm.vue`、`common/config/api.order.js` 与 `pages.json`；`pages.json` 同时是 task target 与 registered source，最终只有一个规范化 required read target，item/source/reason 并集完整；
+- `dtg-tmc-pc` 收敛到机票页面、确认弹窗、客规弹窗、路由与 API 配置六条最小路径；实际链路未使用 Vuex/store，因此没有为满足验收标签虚构 store 路径；另以 `src/main.js` 验证 task/source 同路径只生成一个规范化 read target；
+- 两个 Host 均按 required/conditional/provenance-only 做最小读取，没有重复读取 provenance-only；两项目 registered source 均为 file locator，因此 JSON Pointer 的真实项目重合验证不适用，指针无损语义继续由 HC 自动化覆盖；
+- 两个目标 Contract 均报告 `registration-coverage-not-declared`；mobile 的 `common/config/api.order.js` 另为 `project-scope-only`。这些属于目标 Contract 数据 gap，不是本轮已证产品缺陷；
+- 两项目结束时均为 `health=clean`、`contractReadiness=contract-ready`、renderer 5、0 findings、0 pending items；未调用 Provider，未执行 Git、网络、构建、项目测试、业务代码修改、打包或发布。
+
+本轮未确认新的产品缺陷。后端 `101005` payload 与 `type=2` 的运行时业务语义未做接口实测，保留为未证风险，不进入产品修补。真实 Host 复验授权已消费；当前唯一下一步是等待对 `1.9.1` 打包与发布的独立决定和授权。
+
+## 15. 复验后自托管 coverage 治理收口
+
+`2026-09-23` 的只读审计发现：普通 `status` 为 `clean/contract-ready`，但自托管 `coverage-audit` 因 `templates` 域的 `unresolved` disposition 返回 `registrationCoverage=unresolved`。该目录当前为空，没有可登记的模板文件；这属于已批准 coverage profile 的待裁定域，不是产品内核缺陷。
+
+本次单独授权的治理收口将 `templates` 改为 `dynamic-investigation`：未来若出现模板内容，Host 仍须按具体任务调查、判断是否需要登记到 Contract；不把空目录宣称为 `contract-covered`，也不以 `excluded-approved` 隐藏未来内容。coverage 的保证继续仅限已声明域，且不代表全仓语义完整。页首阶段事实同步为两项目复验已完成；打包与发布仍是独立授权门。

package/docs/32-PROJECT-TO-TASK-INTERACTION-PROPOSAL.md

@@ -0,0 +1,173 @@
+# 32 — 面向开发人员的项目上下文交互与生命周期设计
+
+> 状态：产品方向已批准；设计冻结；实现、真实目标项目改造、发布均待下一步执行授权。
+>
+> 日期：`2026-09-29`。
+>
+> 证据：移动端机票首页真实开发任务；`frontend-project-context@1.9.1` 的项目状态、AI Entry、Context Bundle 与初始化规范。用户明确批准整体改造与设计落档，并要求等待下一步执行。
+
+## 1. 用户问题与失败判定
+
+用户安装 Project Context 是为了让项目上下文参与后续开发。当前产品把项目治理状态和任务可开发状态混在一起：`health=clean`、`contractReadiness=contract-ready` 只证明现有 Contract 与来源一致；`context` 即使返回 `project-scope-only` 或 `registration-coverage-not-declared`，CLI 仍以成功退出。AI Entry 只要求报告 gap，未定义关键任务上下文缺失时的交接动作。
+
+移动端机票首页任务已经展示结果：Host 进入了 `AGENTS.md` 和 Project Context，却没有从中取得任务设计；它仍然开始实施。此时项目入口存在，但项目到开发任务的交接失败。初始化时代表性路径可以编译、只读任务可以消费 Contract，均不能替代这一验收。
+
+本设计的成功标准是：项目接入后，用户无论是否给出开发需求，都能收到准确的当前状态与下一步；有开发需求时，Host 必须获得可追溯的任务上下文，或者拿到明确的缺口和补齐动作。不能用“命令运行成功”代替“任务已准备好”。
+
+## 2. 单一入口与两层状态
+
+项目面向 Host 的入口仍为根 `AGENTS.md`。安装包、CLI、Contract 和临时任务上下文均位于这个入口后面，不另造第二个项目入口。
+
+产品分别报告两种状态：
+
+| 维度 | 状态 | 含义 |
+| --- | --- | --- |
+| 项目接入 | `not-connected`、`needs-governance`、`available` | 本地包、入口、来源和长期 Contract 是否可用。`available` 不表示某个开发任务已就绪。 |
+| 当前任务 | `none`、`discovering`、`needs-evidence`、`needs-decision`、`ready-to-implement`、`blocked` | 针对用户当前意图，是否已经找到必要资料、读取目标上下文并处理关键缺口。没有任务时保持 `none`。 |
+
+包被加入依赖但 `AGENTS.md` 尚未连接时，必须显示 `not-connected`，不能宣称安装已完成上下文接管。项目连接是一次明确、可审查的入口接入动作；它沿用现有 marker 所有权保护和长期 Contract 人工审批。`npm install` 本身不能被当作项目语义批准。
+
+安装体验需要一个面向用户的单一“接入本项目”动作：它检测本地包和既有入口，展示将写入的受管 marker 与项目现状，取得必要授权后完成入口连接，并立即返回下节的项目卡片。底层 `setup`、`publish-entry`、`register` 和 `approve` 仍可复用，但不要求用户逐条选择命令。若既有项目真源尚待人工确认，界面直接显示 `needs-governance` 与待确认语义，不伪装为接入完成。该动作的具体 CLI 名称须在实现合同中冻结；这里固定用户可见行为。
+
+## 3. 安装后没有开发需求
+
+用户说“装好了”“看看这个项目”，或者从项目入口开始但尚未描述任务时，Host 先运行项目本地状态与只读概览。它应向用户交付一张简短的项目卡片：
+
+- 已连接的项目、包版本、入口和 Contract 状态；
+- 已批准且与日常开发有关的事实/规则范围；
+- 已知未治理的关键域、来源冲突或覆盖缺口；
+- 当前没有任务，因此任务状态为 `none`；
+- 可直接用自然语言开始的动作：描述要改的现象或功能、给出已有需求/设计文件、继续当前工作区的改动，或先请求只读盘点。
+
+Host 只在确有歧义时问用户一个能推进工作的具体问题。没有需求时，不创建伪造的 Task Context Plan，不猜测业务目标，不修改源码，也不把项目卡片称为任务就绪证明。
+
+示例交付：
+
+> Project Context 已连接本项目，项目规则可用；目前没有开发任务。你可以直接说“修复机票首页切换问题”，或给我现有设计文件让我先盘点。收到具体需求后，我会核对相关设计与当前实现，再告诉你是可以开始，还是需要补充资料或决定。
+
+没有用户消息、没有 Host 会话、也没有主动运行的安装/接入命令时，普通本地包不能自行向用户发送这张卡片。产品必须在安装/接入命令的输出和每次 Host 从 `AGENTS.md` 进入时提供它，不能宣传静默安装后会主动对话。
+
+## 4. 用户给出新需求或改造需求
+
+同一个入口进入一次任务交接：
+
+1. **接收意图**：保留用户原话，判断是只读调查、设计、实现、继续已有实现，还是不明确的想法；不把任务原话写成长期 Contract。
+2. **盘点已有证据**：在 `targetRoot` 内定位相关需求/设计、当前文件、调用链、已有临时计划及工作区改动。搜索结果只能是候选；Host 核对内容和时效。用户显式给出的外部资料按既有外部来源规则处理。
+3. **编译并消费**：先消费 project scope；目标路径明确后，用完整的最小路径集合编译 Context；读取 required，按任务判断 conditional。设计文档即使不在长期 Contract 中，也可作为本次任务的短期输入，标明来源和当前版本，不自动批准为长期规则。
+4. **处理缺口**：把缺失的设计、接口字段、默认行为、冲突规则和覆盖空白分开。能通过获准的只读调查解决的，给出具体目标继续调查；需要产品或业务决策的，向用户提出精确问题；来源/权限冲突则阻断相应动作。
+5. **交付任务决定**：输出 `ready-to-implement` 或明确的非就绪状态、证据路径、已消费 item IDs、缺口、待确认问题及下一动作。任务中发现新的影响路径或新的关键缺口时，回到第 2 至第 4 步重新编译。
+
+`project-scope-only` 本身不一律阻断。能通过源码调查得到的实现事实可以形成短期任务证据；缺少必须由用户决定的语义时，不能把调查或猜测当成确认。`ready-to-implement` 只说明已声明任务及证据的交接条件满足，不宣称全仓语义完整，也不授予业务代码写入权限。
+
+## 5. 已有项目、已有文档与进行中的工作
+
+| 当前情况 | 产品与 Host 的交接动作 |
+| --- | --- |
+| 项目已有 `AGENTS.md`、文档和工程约定，但未初始化 Contract | 只读分析现有入口与真源；展示保留、修正、迁移、排除及未决冲突；获得对精确长期语义的批准后接入。保留人工入口内容。 |
+| 已有 `.project-context` | 使用 `status`/`sync` 检查和增量维护；保留既有来源、审批与入口所有权，不重跑 `setup` 覆盖。 |
+| 已有需求或设计文档 | 先核对文档与当前实现是否适用；本次任务可短期引用，稳定且可复用的内容另行提议进入长期 Contract。 |
+| 已有工作区改动、任务计划或阶段 Receipt | 先归属现有改动并验证基线；从现状继续交接，不重建或覆盖用户工作，也不把旧计划自动视为批准。 |
+| 用户只说“继续”“改造一下”且目标不明 | 先展示从当前项目中找到的候选任务和已有改动，并提出最小澄清；未锁定目标前任务保持 `discovering`。 |
+
+开发过程中，Host 对新发现的稳定项目知识给用户一份简短的“建议纳入长期 Contract”清单。它与本次任务完成报告分开；用户批准前不能自动提升为长期规则。这样真实开发会反哺上下文，下一次任务才有增量价值。
+
+## 6. 机器交接与约束边界
+
+> 当前实施以 [docs/35](./35-CONTEXT-FIRST-TASK-HANDOFF-DESIGN.md) 为准：提供可消费的上下文门禁，由 Host 遵循；不以钩子或全通道写入拦截为前提。本节以下关于实施保护的文字保留为原方案历史，不构成现行验收门。
+
+需要一个明确的任务交接结果，而不是把 `status`、`context` 和 Markdown gap 交给 Host 自行解释。最小结果包含：项目接入状态、任务状态、任务目标与路径、Contract 快照、命中的 item IDs、required/conditional read targets、短期任务证据、未解决的 gap、需要用户回答的问题以及下一步。`status` 的项目健康与任务就绪必须分字段显示。
+
+任务交接在 `needs-evidence`、`needs-decision` 或 `blocked` 时不能输出“可开始实施”。CLI 生成 Bundle 成功不等于任务交接成功；机器接口应提供显式状态与可区分的退出结果。适配的 Host 必须在业务代码写入前检查当前任务交接状态。沿用同一个 `AGENTS.md` 入口；执行前约束是入口后的消费保护，不是新的项目真源或第二入口。
+
+实施保护只约束当前开发任务的业务写入。为补齐证据所需的只读调查，以及已获准的项目治理操作仍可执行；保护状态需随任务目标、路径、Contract 快照或关键证据变化而失效，再次交接后才能继续。短期任务结果不能充当长期 Contract 的批准或业务代码写入授权。
+
+`AGENTS.md` 文本和普通 CLI 无法从技术上强迫任意 AI 工具遵守写入前检查。若产品承诺“强制”，必须定义受支持 Host 的可执行保护接口，并对未接入该接口的 Host 明确标示为指导模式。产品不能对未受控的 Host 声称硬性接管。
+
+## 7. 任务交接最低验收
+
+> 现行固定验收为 [docs/35 第 10 节](./35-CONTEXT-FIRST-TASK-HANDOFF-DESIGN.md) CF-01 至 CF-14。下列原第 6 项“硬性接管”已被用户的上下文优先定位取代；真实 Agent 消费仍是 H 阶段验收。
+
+1. **无需求安装**：全新和已有项目接入后，用户能得到项目卡片及自然语言起步方式；任务状态为 `none`；没有虚构需求或业务写入。
+2. **现有项目接入**：人工 `AGENTS.md`、已有规范和工作区改动不被覆盖；项目状态与当前任务状态清楚分开。
+3. **移动端失败复现**：在只给新 Host 目标项目和机票首页真实需求时，若设计未进入本次任务证据，交接不得是 `ready-to-implement`；Host 必须找到设计或提出缺口，不能直接实施。
+4. **设计可用后继续**：Host 实际读取设计、现有入口、配置字段与相关调用链；缺少字段或默认行为决策时停在 `needs-decision`；补齐后重新编译并进入实施。
+5. **开发中发现新路径**：Context 以新完整路径集合重新编译；任务状态和证据随之更新。
+6. **硬性接管声明**：受支持 Host 的业务写入在非就绪状态被拦住；不支持执行保护的 Host 明确显示指导模式。仅有 `clean`、单次 Context 命中、本地测试或只读 Host 盘点不得通过这一项。
+
+验收必须使用不继承产品设计讨论的真实 Host 和真实开发任务，记录它实际看到的交接结果与代码行为。不能再用内部测试数量或代表性只读查询替代。
+
+## 8. 开发人员直接与项目上下文对话
+
+产品向 Host 提供结构化、可追溯的项目回答；Host 用自然语言和开发人员交流。开发人员不应看到一串 `status → context-query → stage-context → sync` 命令，也不必知道 Contract schema。项目对话面统一使用四个短栏目：**已确认**、**待核实**、**需要你决定**、**接下来会做什么**。每条会影响实施的判断都能展开到来源、适用路径、当前版本或时间以及是否获人批准。
+
+例如用户说“继续做机票首页”，项目先回答：
+
+> 我找到当前机票首页设计、进行中的 V1/V2 改动和适用的项目规则。设计对版本字段的来源有要求，但当前证据还没有确认空值时显示哪一版。我会先核对现有 API 与加载顺序；这个决定若仍无依据，我会请你确认，之后再继续改代码。
+
+这段话必须由实际证据生成；找不到设计就说“尚未找到”，不能以流畅口吻补造。对话不是长期真源，Host 的推理和聊天记录不自动写入 Contract。开发人员确认的临时任务决定进入任务记录；只有具有跨任务长期效力的事实，才另行提交给人工批准的 Contract。
+
+## 9. 现有功能逐项归位
+
+| 现有能力 | 当前事实 | 面向开发人员的归位 |
+| --- | --- | --- |
+| `instructions`、`init`、`setup`、`discover`、`publish-entry`、`remove-entry` | 有安装和初始化原语，但需要 Host 编排，用户会碰到底层步骤 | 收到“接入项目”意图时走一次引导，最后直接展示项目卡片；入口仍是 `AGENTS.md`。移除入口时明确提示接管已关闭。 |
+| `register`、`propose`、`approve`、`review-source`、`accept-source-change`、`revise`、`deprecate`、`deprecate-source` | 长期 Contract、来源维护与人工批准机制已存在 | 留在维护者审查层；普通开发人员只需看清什么规则有效、为什么需要确认。 |
+| `status`、`check`、`sync`、`dashboard` | 能报告项目健康、漂移与维护项 | 作为项目对话的证据输入；把“当前任务相关”与“以后集中维护”分开提醒。 |
+| `context`、`context-query`、`coverage-audit`、`index-context` | 能选择作用域、声明覆盖与新鲜度；`context-query` 的 ready 只覆盖已声明证据 | 合并为一次任务交接体验；保留底层协议，但不得把项目健康或已声明闭包误称为业务需求完整。 |
+| `stage-context`、`integration-review`、`reconcile-truth` | 能验证调用方提供的 Plan、Receipt、路径、基线和碰撞；不自行知道任务、分支或发布事实 | 长任务和环境流转时由项目对话调用；开发人员看到阶段目标、变化、风险和待确认点，不手写机器工件。 |
+| `evidence`、`preflight`、`upgrade-*` | 已有反馈、精确治理写入审查及版本迁移协议 | 分别归入问题反馈、维护者操作和升级引导；不成为每个开发任务的默认负担。 |
+| `capabilities`、schema、migration manifest、`publish` | 已有协议自描述和其他 AI 消费者投影 | 维持兼容与机器交换；普通项目对话只显示当前消费者是否接入，不展示协议细节。 |
+| 跨窗口任务记忆、需求时效、提醒、实施前保护 | 现行核心未形成完整闭环 | 是这轮产品定义与设计重点；不能因已有单项协议而宣称可用。 |
+
+功能保留以真实使用链路为准：能直接帮助开发人员作决定的，进入项目对话；只保证机器正确性的，保持底层能力；没有消费场景的额外记录不继续堆入默认流程。同一任务的 `context` 与 `context-query` 必须共享选择语义，避免两套结论。
+
+## 10. 跨窗口任务记录与需求过期
+
+及时提醒需要跨会话记住任务依据。本设计冻结**最小任务记录**，与长期 Contract 分开：任务 ID、原始需求或其可信引用、来源及摘要、目标/验收、相关路径、已确认决定、未决问题、关联的分支或 revision 标签、当前阶段、证据快照、明确的有效期或取代关系、最近一次人工确认。它不保存完整聊天、模型推理、全量 diff 或源码正文；结束、撤销、合并后按明确规则归档或清理。项目本地必须能承载最小记录，团队已有任务系统时可由适配器承载；两者使用同一机器合同。任何一方都不是第二份长期项目规范。
+
+“需求过期”只由可核对的事件触发：用户给出的截止/复核日期到达、来源被更新或明确取代、验收条件改变、任务所依赖的 Contract 或环境快照改变、当前分支与记录的基线不一致。没有日期和变化证据时，产品不能凭时间长短断言需求失效。过期保留历史记录，当前任务转为 `needs-evidence` 或 `needs-decision`；说明哪一条依据变了、影响哪个目标、需要谁确认。
+
+提醒分两类：
+
+1. **事件触发**：打开项目、接新任务、继续旧任务、目标路径或来源变化、阶段切换、合并/发布证据传入时，立即计算相关提醒。这是产品默认可兑现的“及时”。
+2. **定时主动通知**：用户关闭会话后仍按日期发通知，需要用户选择的调度器或外部任务系统和通知权限。现行 CLI、`AGENTS.md` 均不具备此能力；未集成前只承诺下一次进入项目时提醒。
+
+提醒只发给当前任务相关人员，按 `阻断实施 / 等待决定 / 提醒复核` 排序；同一原因和快照只提示一次，变化后再出现。开发人员可以看到“为何现在提醒”“忽略会影响什么”，但忽略提醒不能自动批准长期 Contract 或覆盖明确阻断。
+
+## 11. 从需求分支到主分支、环境和新任务
+
+已有四层事实模型可复用：批准的项目 Contract、需求分支候选、集成候选、实际发布快照。产品应在一次连续项目对话中处理它们，而不是把一个分支的临时决定直接变成全项目事实。
+
+| 时刻 | 项目对开发人员说明什么 | 所需证据及界限 |
+| --- | --- | --- |
+| 创建或继续需求 | 当前适用规则、已有设计/实现、未决问题、此分支采用的基线 | 任务记录和用户需求；分支标签只作定位信号，不能证明已创建分支或获得写入权限。 |
+| 开发与 QA | 当前阶段完成了什么、验收证据绑定到哪个 revision、哪些结论因改动失效 | Host 提供的 changed paths、测试/构建结果和 Receipt；产品不代替测试。 |
+| 合入主分支或进入集成环境 | 哪些需求候选发生冲突，哪些局部验收可复用，哪些组合验证必须重做 | Host 提供实际合并结果与集成快照；未看到证据就不能声称已合并或可发布。 |
+| 进入预发/生产或回滚 | 当前运行的是哪个制品/配置、对应哪份 Contract 与需求决定，灰度适用哪些范围 | 发布系统/Host 提供的实际 revision、制品、环境和结果；产品不执行发布。 |
+| 后续新任务 | 先提示当前项目规范、生产事实和待维护候选的区别；旧需求过期或回滚造成的影响只在相关范围提醒 | 从当前环境与 Contract 快照重新计算；不能把“曾计划上线”当作“已上线”。 |
+
+主分支、预发和生产环境的实际名称由项目配置或用户提供；产品不假定所有团队都使用 `master`。当前 `reconcile-truth` 等命令只消费外部传入的证据，尚未构成开发人员直接可用的环境对话面。
+
+## 12. 实施顺序与停止条件
+
+> 下表是原 A—D 路线的历史规划。当前顺序为 [docs/35](./35-CONTEXT-FIRST-TASK-HANDOFF-DESIGN.md) 的 D → L → H：最小跨消费者任务记录提前进入 L；L 本地闭环不等待 Host 钩子，H 才验证两个不同 Agent 的实际消费。更广的提醒和环境生命周期另行分期，不属于本次 L 授权。
+
+| 阶段 | 首个可用结果 | 必须通过的真实验收 |
+| --- | --- | --- |
+| A. 接入与任务交接修复 | 单一接入动作、项目卡片、任务状态、证据缺口、受支持 Host 的实施前保护 | 无需求用户得到明确起步方式；移动端机票首页缺少设计时不能绿灯写代码；设计与决定补齐后能继续。 |
+| B. 跨窗口与提醒 | 最小任务记录、继续已有工作、来源/决定过期、事件触发提醒 | 新 Host 不继承旧聊天也能解释当前任务、未决点和过期原因；无关变化不骚扰当前开发。 |
+| C. 环境流转 | 需求、主分支、集成、生产快照的对话与精确差异提醒 | 合并、预发、上线、回滚各使用实际外部证据；不把候选当已发布事实。 |
+| D. 扩展集成 | 更多 Host 的实施前保护和经用户选择的定时通知 | 每个适配器单独证明阻断能力与通知权限；未支持的 Host 保持清楚的指导模式声明。 |
+
+阶段 A 未在真实开发任务中通过前，不再以内部测试、schema 扩张、只读示例或新版本发布宣称产品已接管。每阶段先验证人能否理解并完成实际工作，再考虑协议兼容与实现细节。
+
+## 13. 产品定义影响与决策点
+
+这个设计超出旧版宪法仅把产品定义为 Contract 编译、投影和交换层的范围。用户已于 `2026-09-29` 明确批准整体产品方向和设计落档；按宪法第 11 节，同步以下产品定义变更：
+
+- 第 2、3 节：把安装后项目概览、开发人员对话、任务上下文交接和相关提醒列入产品承诺；
+- 第 4 节：加入短期任务证据、就绪状态、项目对话结果与环境快照消费的产品责任，同时保持长期 Contract 的人工审批；
+- 第 5 节：明确最小任务记录、事件触发提醒及受支持 Host 的实施前保护的允许边界；若要覆盖任意 Host 或关闭会话后的主动定时通知，须另行决定 Agent Runtime / scheduler 边界；
+- 第 7 节：把无需求起步、已有项目继续、真实任务缺口阻断、跨窗口过期提醒和实施前交接列入完成条件。
+
+本设计授权已消费。`1.9.1` 的既有发布事实不等于本设计已实现；本轮不改 CLI、schema、目标项目、包版本或发布物。下一次必须从阶段 A 的接口与真实失败用例开始执行，不能从阶段 C/D 或旧版的发布门继续。