frontend-project-context 1.9.1 → 1.10.0

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 1.10.0 - 2026-10-02
+
+- Add read-only `project-brief` and `task-handoff` commands, schema-1 task records, current-consumer evidence checks, and instructional context gates. No Agent Runtime, hooks, or business-code writer is added.
+- Add opt-in `--view work` schema 2 to both commands, delivering the complete compiled Context, current task evidence, progress, and concise human output in one handoff. Omitted/legacy views retain schema 1 and their exit behavior.
+- Advance capabilities schema to 11 and AI Entry renderer to 7. Existing Contract, Context Bundle, Coverage Audit, Exchange Protocol, task record and input formats remain readable; owned AI Entry updates remain explicit.
+- Repair two bounded handoff errors: incomplete governance now routes to onboarding, and a missing task record returns a specific error instead of an internal error.
+- Bind consumption to the current task and requirement evidence; reject implementation without an applicable requirement, ignore future-intent-only evidence, normalize path identities, and require finite directory-to-file narrowing.
+- Withhold oversized work output above 1 MiB without truncating required rules into readiness; expose progress and optional knowledge suggestions without automatic Contract adoption.
+- Repair upgrade assessments that incorrectly required file locks for human-decision and external-reference sources; local missing-lock checks remain blocking.
+- Pass 265 local checks, including WF-01–WF-10 and all earlier handoff regressions. Real-project Agent compliance, net task benefit, and maintenance cost remain pending and are not claimed by this release.
+
 ## 1.9.1 - 2026-09-23
 
 - Repair Context Bundle read-target identity so task targets and local Contract sources merge by normalized path without duplicate output.

package/README.md

@@ -22,6 +22,8 @@ AI coding tools often read only part of a repository. Important conventions may
 
 It does **not** call an AI provider, edit business code, manage Git, install dependencies automatically, or approve rules on its own.
 
+Version `1.10.0` adds the local L phase of the approved [context-first handoff](./docs/35-CONTEXT-FIRST-TASK-HANDOFF-DESIGN.md): a project brief, a minimal task record, a read-only handoff result, and instructional context gates. Real-project Agent acceptance remains pending; this release does not claim that a Host will always follow the gates.
+
 ### Requirements
 
 - Node.js 18 or newer
@@ -32,12 +34,12 @@ 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.9.1
+npm install --save-dev --save-exact frontend-project-context@1.10.0
 ```
 
 The package has zero runtime dependencies.
 
-Version `1.9.1` repairs normalized-path read-target aggregation, lossless JSON Pointer union, and shared strict coverage parsing while keeping Context Bundle schema 1, Coverage Audit schema 2, capabilities / Exchange Protocol 9, and AI Entry renderer 5 unchanged. Read-only real-Host revalidation passed in both TMC targets on the same frozen source candidate; that earlier source snapshot is distinct from the published package artifact.
+`1.10.0` retains the `1.9.1` Context integrity repairs and adds `project-brief` and `task-handoff`, including opt-in work views. Capabilities schema advances to 11 and AI Entry renderer to 7; Context Bundle schema 1, Coverage Audit schema 2, Contract schema 3, and Exchange Protocol 9 remain readable. Install the exact version before updating an existing project's owned AI Entry.
 
 ### Quick start
 
@@ -58,7 +60,7 @@ All `npm exec --offline -- project-context` commands below require the exact dev
 npm exec --offline -- project-context publish-entry --project . --output AGENTS.md --write --json
 ```
 
-Version `1.9.1` keeps AI Entry renderer 5: it routes unknown targets through `context --locate`, then recompiles exact multi-path Context and reports item IDs, scopeCoverage, required/conditional read targets, provenance-only sources, and gaps. Existing renderer-1/2/3/4 entries remain readable but stale until an explicit owned republish.
+The current local source uses AI Entry renderer 7: it routes through opt-in work views, delivering the same full Context alongside current task evidence and progress; unknown paths still require locate-then-targeted consumption. Existing renderer-1/2/3/4/5/6 entries remain readable but stale until an explicit owned republish.
 
 Use `remove-entry` with the same output to remove only a trusted managed region. Plans and previews never include `--write`; human approval of the exact path remains required.
 
@@ -265,6 +267,8 @@ All commands are read-only unless that command explicitly includes `--write`. So
 | `propose` | Author a fact, policy, reference, or validation description |
 | `approve` | Explicitly approve selected proposal IDs |
 | `context` | Compile approved context for one or more paths |
+| `project-brief` | Read project health and discover bounded local task records without selecting one |
+| `task-handoff` | Compile current task evidence, read targets, gaps, and an instructional gate |
 | `context-query` | Compile adaptive review JSON or its compact model-facing `--prompt` projection with complete-context fallback |
 | `coverage-audit` | Audit declared registration coverage without claiming all project truth |
 | `index-context` | Preview or explicitly persist a disposable routing index |
@@ -317,6 +321,8 @@ AI 编程工具通常只读取仓库的一部分，而项目约定分散在文
 
 它**不会**调用大模型、修改业务代码、管理 Git、自动安装依赖，也不会替人批准规则。
 
+`1.10.0` 按[上下文优先交接设计](./docs/35-CONTEXT-FIRST-TASK-HANDOFF-DESIGN.md)提供本地 L 阶段：项目概览、最小任务记录、只读交接结果和指令式上下文门禁。真实项目中的 Agent 遵循情况尚未验收；本版本不宣称 Host 必然遵守门禁。扩展提醒和环境生命周期仍是后续范围。
+
 ### 环境要求
 
 - Node.js 18 或更高版本
@@ -327,12 +333,12 @@ AI 编程工具通常只读取仓库的一部分，而项目约定分散在文
 建议固定为开发依赖，让本地与 CI 使用同一版本：
 
 ```bash
-npm install --save-dev frontend-project-context@1.9.1
+npm install --save-dev --save-exact frontend-project-context@1.10.0
 ```
 
 本包没有运行时第三方依赖。
 
-`1.9.1` 修复了规范化 path 级 read-target 聚合、JSON Pointer 无损并集和共享严格 coverage 解析，Context Bundle schema 1、Coverage Audit schema 2、capabilities / Exchange Protocol 9 与 AI Entry renderer 5 保持不变。两个 TMC 目标曾使用同一冻结源码候选完成只读真实 Host 复验；该历史源码快照与正式包工件不是同一字节对象。
+`1.10.0` 保留 `1.9.1` 的 Context 完整性修复，新增 `project-brief`、`task-handoff` 及显式工作视图。Capabilities schema 升至 11、AI Entry renderer 升至 7；Context Bundle schema 1、Coverage Audit schema 2、Contract schema 3 和 Exchange Protocol 9 保持可读。先安装精确版本，再显式更新现有项目受管的 AI Entry。
 
 ### 快速开始
 
@@ -353,7 +359,7 @@ npm exec --offline -- project-context status --project . --json
 npm exec --offline -- project-context publish-entry --project . --output AGENTS.md --write --json
 ```
 
-`1.9.1` 继续使用 AI Entry renderer 5：目标未知时先运行 `context --locate`，随后用完整最小路径集合重新编译 targeted Context，并报告 item IDs、scopeCoverage、required/conditional read targets、provenance-only sources 与 gaps。既有 renderer 1/2/3/4 仍可读取但会标记 stale，只有显式受管 republish 才升级。
+当前本地源码使用 AI Entry renderer 7：通过显式 work 视图直接交付项目概览、完整 Context、任务依据和进度；未知路径仍需 locate → 精确文件集合，实际消费与指令式门禁保持。既有 renderer 1/2/3/4/5/6 可读但会标记 stale，只有显式受管 republish 才升级。
 
 使用相同 output 的 `remove-entry` 只移除可信受管区域。计划与 preview 都不含 `--write`，仍需人对精确路径授权。
 
@@ -561,6 +567,8 @@ npm exec --offline -- project-context dashboard --project . > project-context-da
 | `propose` | 创建 fact、policy、reference 或 validation-description |
 | `approve` | 显式批准选中的 proposal ID |
 | `context` | 为一个或多个路径编译已批准上下文 |
+| `project-brief` | 只读展示项目健康与可选的本地任务记录；不自动选任务 |
+| `task-handoff` | 只读编译本次任务证据、待读项和指令式门禁；`--input -` 可从 stdin 接收输入 |
 | `context-query` | 编译自适应审查 JSON，或生成带完整上下文回退的紧凑 `--prompt` 模型投影 |
 | `coverage-audit` | 审计声明范围内的来源登记覆盖，不宣称发现全部项目真源 |
 | `index-context` | 预览或显式保存可删除的派生路由索引 |
@@ -602,3 +610,14 @@ npm exec --offline -- project-context dashboard --project . > project-context-da
 Apache License 2.0 · `Copyright 2026 Fushan`
 
 See [LICENSE](./LICENSE) and [NOTICE](./NOTICE).
+
+## 日常交接工作视图
+
+[日常使用示例](./docs/38-EVERYDAY-HANDOFF-OPERATION.md) 将项目概览、任务交接、继续和完成后的知识建议连成同一条路径。明确添加 `--view work` 会输出 schema 2；不加参数或 `--view legacy` 保持 schema 1 与原退出码。工作视图交付同一编译器的完整 Context，实际阅读与当前消费者声明仍是必要步骤；输出超过 1 MiB 时明确 withheld，不以截断内容放行。
+
+```bash
+npm exec --offline -- project-context project-brief --project . --view work --json
+npm exec --offline -- project-context task-handoff --project . --input - --view work --json
+```
+
+真实收益验收包括两个业务任务和一次无历史续接，记录准备、读取、定位、返工和维护时间。安装与本地测试通过不能替代这些实际结果。

package/UPGRADING.md

@@ -1,5 +1,13 @@
 # 升级说明
 
+## `1.9.1 → 1.10.0`
+
+先在目标项目中由其现有 Host 将开发依赖与 lockfile 精确固定为 `frontend-project-context@1.10.0`。新版本增加只读 `project-brief`、`task-handoff` 和 schema 1 任务记录；记录由 Host 在当前用户授权下维护，不自动生成、选择或批准长期 Contract。`task-handoff` 的 `gate=proceed` 仅说明已声明的上下文满足本次意图，不授予业务代码写入权限。
+
+Capabilities schema 升至 11，AI Entry renderer 升至 7；Contract schema 3、Context Bundle schema 1、Coverage Audit schema 2 和 Exchange Protocol 9 保持兼容。原有 store 不自动迁移；已拥有的旧 AI Entry 会显示 stale，需由目标项目 Host 审查后显式 `publish-entry --write`。短生命周期 Context 与消费声明应按当前任务重新生成，不继承旧窗口的 ready。迁移清单将 `1.9.1 → 1.10.0` 分类为 `package-only`，并列出显式 AI Entry republish 单元。
+
+本版本完成本地 L 实现；真实项目 Agent 是否读到关键设计并遵守门禁，仍须在后续真实任务中观察，不因安装或 `clean/contract-ready` 自动视为通过。目标项目更新和验收在其独立窗口执行。
+
 ## `1.8.0 / 1.9.0 → 1.9.1`
 
 `1.9.1` 是对未发布 `1.9.0` Context 消费语义的补丁：read target 改为按规范化 path 唯一聚合，同路径多 JSON Pointer 完整保留，Context Bundle 与 Coverage Audit 共用一份严格 coverage profile parser/selector。Context Bundle schema 1、Coverage Audit schema 2、Contract schema 3、capabilities / Exchange Protocol 9 和 AI Entry renderer 5 均不升级。
@@ -147,3 +155,9 @@ Action Plan 和 Review Bundle 都不是 store、Contract 或 approval receipt。
 5. 来源搬迁或永久退役时，先登记替代来源并修订/重新批准所有当前引用，再 preview `deprecate-source`，最后用 preview 返回的 source object digest 显式写入并重新发布投影。
 
 旧 `1.0.0` RC reader 不支持 Contract schema 2，因此成功废弃来源后不能用旧 reader 继续维护该项目。升级不会自动迁移、接受来源变化、修改 item、批准知识、覆盖非受管文件或执行 Git。
+
+### 1.10.0 日常链路工作视图
+
+显式 `--view work` 为 `project-brief` / `task-handoff` 输出 schema 2，默认 legacy 仍为 1；capabilities schema 11 的 `views` 声明这两个分支。AI Entry renderer 7 直接消费工作视图，renderer 1–6 可读但 stale，只有显式 `publish-entry --write` 才更新。受管区域外的人工内容及其摘要规则保持。Contract、Context Bundle、Exchange Protocol 和 task record/input 均不迁移。
+
+[日常使用示例](./docs/38-EVERYDAY-HANDOFF-OPERATION.md) 说明新消费者读取、超限恢复和完成后的知识候选。安装后核对 capabilities 的 views、包版本和受管入口 renderer；安装成功仍需实际任务验收。

package/docs/00-PRODUCT-CONSTITUTION.md

@@ -1,10 +1,10 @@
 # Frontend Project Context — 产品宪法
 
-> 宪法版本：`1.2.0`
+> 宪法版本：`1.3.0`
 >
 > 状态：`frozen`
 >
-> 生效日期：`2026-09-09`
+> 生效日期：`2026-09-29`
 
 ## 1. 文档权威
 
@@ -23,36 +23,40 @@
 
 ## 2. 唯一产品定义
 
-Frontend Project Context 是一个**落在项目中的、位于项目与 AI 编程工具之间的模型无关双向上下文治理与交换层**。
+Frontend Project Context 是一个**落在项目中的、位于项目、开发人员与 AI 编程工具之间的模型无关上下文治理、交互与交换层**。
 
-它把项目明确提供的事实、规则和来源治理为一份人工批准的 `Project Contract`，再针对目录和任务生成最小、可追溯的 `Context Bundle`，投影给已有 AI 编程工具，并把 AI 返回的建议收敛为可预检、可集中审查的短生命周期 action，最后在人明确批准后复用现有安全写入原语。
+它把项目明确提供的事实、规则和来源治理为一份人工批准的 `Project Contract`，再向开发人员提供可追溯的项目概览、任务证据与就绪交接、相关变化提醒；针对目录和任务生成最小 `Context Bundle`，投影给已有 AI 编程工具，并把 AI 返回的建议收敛为可预检、可集中审查的短生命周期 action，最后在人明确批准后复用现有安全写入原语。Host 负责把这些结果以自然语言与开发人员交流，产品不冒充已理解未提供的项目语义。
 
 ```text
 项目显式来源 + 人工规则
 → 候选项
 → 人工批准的 Project Contract
-→ 按目录/任务编译的 Context Bundle
-→ AGENTS.md / Ruler / 其他 AI 工具
+→ 单一项目入口与开发人员可读的项目概览
+→ 任务证据、就绪交接与按目录/任务编译的 Context Bundle
+→ AGENTS.md / Ruler / 其他 AI 工具与开发人员对话
+→ 阶段、集成、生产证据及相关变化提醒
 → AI Action Plan
 → 确定性预检与人工集中审查
 → 已授权的细粒度写入
 → 来源、合同与投影漂移检查
 ```
 
-本产品治理“项目希望 AI 知道什么”和“AI 建议如何在人工授权前被安全表达与预检”，不负责“AI 如何完成开发任务”。
+本产品治理“项目希望 AI 与开发人员知道什么”“当前任务何时具备已声明的上下文证据”和“AI 建议如何在人工授权前被安全表达与预检”，不负责执行开发任务。项目健康、任务就绪、环境事实和实施权限是不同结论，不能互相替代。
 
 ## 3. 固定用户问题
 
-同一项目的知识分散在设计资料、文档、配置、代码和团队约定中，不同 AI 工具会获得不完整、重复或互相冲突的指导，并且规则变化难以追溯。
+同一项目的知识分散在设计资料、文档、配置、代码和团队约定中，不同 AI 工具会获得不完整、重复或互相冲突的指导，并且规则变化难以追溯。开发人员安装产品后也需要知道项目当前掌握了什么、如何开始或继续任务、关键需求何时过期，以及分支和环境变化对当前工作有什么影响。
 
-本产品提供的稳定价值只有四点：
+本产品提供的稳定价值为：
 
 1. 一份有人批准、保留来源的项目合同；
 2. 针对目录和任务的确定性上下文编译；
 3. 同一合同面向多个 AI 消费者的一致投影和漂移检查。
 4. 项目与不同 AI 编程工具之间一份双向、模型无关、可预检且不扩张人工权限的交换协议。
+5. 从同一项目入口给开发人员可追溯的项目概览、任务就绪交接和必要的澄清问题；
+6. 根据明确的任务、来源与环境证据，在相关时点提醒过期、冲突和待确认事项。
 
-如果某项能力不能直接服务这四点，它默认不属于内核。
+如果某项能力不能直接服务这些价值，它默认不属于内核。
 
 ## 4. 固定内核
 
@@ -65,6 +69,7 @@ Frontend Project Context 是一个**落在项目中的、位于项目与 AI 编
 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 和路径明确批准。
+8. **Developer Interaction & Lifecycle Boundary**：从现有 Contract 与显式任务、来源、环境证据生成项目概览、任务就绪状态、最小跨会话任务记录和相关提醒；通过现有单一入口向 Host 提供当前任务的上下文门禁。Host 遵循门禁和当前用户授权；产品不拦截工具、不执行或批准开发任务。
 
 自动 discovery 只是帮助项目首次接入的可选辅助，不是内核完整性的衡量标准。它可以保守地提出候选，但不承担理解所有前端技术和业务语义的责任。
 
@@ -79,7 +84,9 @@ Frontend Project Context 是一个**落在项目中的、位于项目与 AI 编
 - 自动安装依赖、访问网络或修改外部系统；
 - 重建 Kiro、Spec Kit、OpenSpec、Ruler、Rulesync 或成熟 Coding Agent 的完整能力；
 - 为每个框架、路由、状态库、UI 库、构建器、租户或发布平台维护不断增长的识别白名单；
-- 保存 candidate、DecisionRecord、DeliveryRecord 或形成自动修复循环。
+- 保存完整聊天、模型推理、全量 diff 或形成自动修复循环；最小任务记录只保存交接与提醒所必需的结构化依据，不是第二份长期项目规范；
+- 在没有另行选择的外部调度与通知机制时，声称关闭会话后仍能主动定时提醒；
+- 声称仅凭任务交接结果就能技术上强制阻止任意 Host 的业务代码写入。
 
 Vue、React、uni-app、Vuex、Element UI、路由、租户和发布方式等都是项目内容。内核不认识它们时，项目应通过通用来源与 authoring 能力表达，而不是要求内核新增专用逻辑。
 
@@ -92,10 +99,13 @@ Vue、React、uni-app、Vuex、Element UI、路由、租户和发布方式等都
 5. 临时任务约束不能反向改写长期合同。
 6. 默认只读；持久写入必须由当前命令的显式写入选项触发。
 7. 只能覆盖本产品创建且所有权未发生冲突的受管投影。
-8. 未知项目语义是待录入的项目数据，不自动成为产品缺陷。
+8. 未知项目语义是待录入的项目数据；产品若把关键未知项隐藏在成功状态下、未给出补齐路径或错误宣称任务可实施，则属于产品交接缺陷。
 9. 真实项目只能验证预先定义的能力，不能直接产生内核需求。
 10. 新技术、新文件名或单个项目差异不能成为扩大 discovery 的充分理由。
 11. AI 产生的 Action Plan、Review Bundle、推理或建议都不是 Project Contract、approval 或持久执行权限；必须通过 schema、baseline、impact 和人工精确授权边界。
+12. 项目 `clean`、Contract 可用、Context 生成成功与当前任务可实施是不同状态；任何任务就绪结论必须绑定任务目标、证据、范围、快照和未决问题。
+13. 短期任务记录、需求决定、分支候选和环境快照不能自动改写 Project Contract；“计划上线”“已合并”“已上线”必须由不同的实际证据支持。
+14. 过期和提醒必须指向明确的日期、来源变化、取代关系或环境事件；未知时报告未知，不能虚构期限或重复骚扰无关任务。
 
 ## 7. v1 完成定义
 
@@ -131,6 +141,20 @@ v1 只有在以下闭环同时成立时才算产品完成：
 
 完整实现合同以 [17-AI-EXCHANGE-BOUNDARY-DESIGN.md](./17-AI-EXCHANGE-BOUNDARY-DESIGN.md) 为准。
 
+### 7.3 面向开发人员的交互与生命周期完成条件
+
+本节是 `2026-09-29` 获批的新产品方向完成条件，不改写旧版 v1 和 `1.2.0` 的历史完成事实。新方向只有在以下闭环同时成立时才能声称完成：
+
+1. 接入后的用户即使没有开发需求，也能从单一项目入口获得准确的项目概览、已知缺口和自然语言起步方式；仅安装依赖不得被称为完成接管。
+2. 新任务和已有任务都能从当前需求、设计、代码与工作区证据进入可追溯交接；关键证据或决定缺失时，不得输出可实施状态。
+3. 开发人员能直接用自然语言询问项目当前依据、未决点与下一动作；会影响实施的陈述可追溯到批准的 Contract 或标明身份的短期证据。
+4. 跨窗口任务记录只保留必要结构化依据；需求过期、来源变化与环境事件按相关范围提醒，不自动批准长期规则。
+5. 主分支、集成、预发、生产与回滚的结论使用真实外部证据，严格区分候选、已合并和实际运行；产品不执行 Git、CI 或发布。
+6. 入口和交接结果明确当前意图、证据缺口、停止与继续条件；通过独立真实 Agent 的实际消费验证其遵循情况，不承诺全通道技术强制。
+7. 独立真实 Host 在曾失败的移动端任务上证明：缺失设计时停在缺口处理，依据补齐后能继续开发；内部测试、`clean` 或只读 Context 查询均不得替代该验收。
+
+产品方向见 [32-PROJECT-TO-TASK-INTERACTION-PROPOSAL.md](./32-PROJECT-TO-TASK-INTERACTION-PROPOSAL.md)；当前上下文交接实现和验收顺序见 [35-CONTEXT-FIRST-TASK-HANDOFF-DESIGN.md](./35-CONTEXT-FIRST-TASK-HANDOFF-DESIGN.md)。
+
 ## 8. 真实项目与实验规则
 
 `dtg-tmc-mobile` 和 `dtg-tmc-pc` 已经完成 B0。它们证明核心机制和首轮安全修补可以落在真实仓库结构中。
@@ -144,6 +168,8 @@ v1 只有在以下闭环同时成立时才算产品完成：
 - 只有先写出固定、可证伪的产品假设，真实项目才可以再次用于验证该假设；
 - 验证失败先判断是内核不变量失败、项目数据缺失还是适配器问题，后两者不得进入内核修补循环。
 
+真实项目的数据缺失本身不要求内核理解业务；产品漏报显式缺口、错误输出任务就绪或生成不可消费的交接时，按第 7.3 节判断产品交接失败。Host 已收到正确门禁却未遵循时单列 Host 行为，不因此强制新增保护器。
+
 ## 9. 需求分类与拒绝规则
 
 任何新增建议必须先归入且只能归入一类：
@@ -196,3 +222,9 @@ v1 只有在以下闭环同时成立时才算产品完成：
 5. 第 7.2 节新增 `1.2.0` 双向交换完成条件；
 6. Provider、Agent Runtime、开发任务执行、Git、网络、自动批准、业务代码修改和框架识别白名单仍在永久边界外；
 7. 本次授权只包含宪法修订、`1.1.0` 完整性修正和 `docs/17` 设计落盘，不自动授权 `1.2.0` 产品代码、真实项目、Git 写入或发布。
+
+## 14. `1.3.0` 开发人员交互与生命周期修订记录
+
+用户在移动端真实开发中确认：`AGENTS.md` 与 CLI 已被调用，但机票首页关键设计未进入有效任务上下文，工具仍给出成功结果，Host 继续实施；随后明确要求安装后的无需求引导、开发人员与项目直接对话、已有工作接续、任务与环境变化提醒，并于 `2026-09-29` 批准整体产品方向改造与设计落档、要求等待下一步执行。
+
+本次修订改变第 2 至第 5 节的产品承诺、稳定价值、内核和边界说明，细化第 6 节的不变量，并在第 7.3 节增加新方向完成条件。现有包 `frontend-project-context@1.9.1` 的已发布事实不受改写；现有公开协议不因本次文档修订自动升级。实现、目标项目改造、Git、Provider、网络、打包与发布均未由此次设计授权触发。

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

@@ -43,10 +43,10 @@ CI 安装项目锁定的依赖版本并执行只读检查。CI 不依赖机器
 持久初始化前，先把精确版本安装为项目开发依赖：
 
 ```bash
-npm install --save-dev frontend-project-context@1.9.1
+npm install --save-dev --save-exact frontend-project-context@1.10.0
 ```
 
-包名冻结为 `frontend-project-context`，可执行文件名为 `project-context`。安装必须先于任何持久初始化写入，使 discovery 登记的 `package.json` digest 已包含正式依赖，避免补装工具后立即产生 `source-changed`。`1.9.1` 的实现门为 HC-01 至 HC-14、TC-01 至 TC-16 和全部回归；此前两个真实项目的只读 Host 复验使用同一冻结源码候选，目标项目安装发布包及运行具体需求需在各自窗口另行核验。
+包名冻结为 `frontend-project-context`，可执行文件名为 `project-context`。安装必须先于任何持久初始化写入，使 discovery 登记的 `package.json` digest 已包含正式依赖，避免补装工具后立即产生 `source-changed`。`1.10.0` 增加本地 L 阶段的任务交接能力；真实项目更新及具体任务的 Agent 行为须在目标项目窗口另行观察，不因安装或本地检查自动视为通过。
 
 选择项目内安装而不是全局安装，原因是：
 

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 或旧版的发布门继续。