frontend-project-context 1.3.1 → 1.7.0

package/docs/21-PHASE-B-EVIDENCE-FEEDBACK-PROTOCOL-DESIGN.md

@@ -0,0 +1,347 @@
+# 21 — `1.5.0` Phase B Evidence Feedback Protocol 详细设计
+
+> 权威说明：本文是 [19-POST-1.3.1-AI-TAKEOVER-EVIDENCE-AND-UPGRADE-PLAN.md](./19-POST-1.3.1-AI-TAKEOVER-EVIDENCE-AND-UPGRADE-PLAN.md) 中 Phase B 的可开发合同。如与 [00-PRODUCT-CONSTITUTION.md](./00-PRODUCT-CONSTITUTION.md) 冲突，以产品宪法为准。
+>
+> 状态：`implemented-local-verified; A-91-through-A-100-and-all-regressions-pass-106-of-106; release-not-authorized`
+>
+> 目标版本：`frontend-project-context@1.5.0`
+>
+> 基线：仓库内 `1.4.0` 已完成本地实现与 96/96 验收，但尚未发布，也未经过真实 Host/目标项目验证。本文不改变该实现事实。
+
+## 1. 结论
+
+`1.5.0` 只完成 **Evidence Feedback Protocol**：目标项目中的 Host Agent 把一次已发生的 setup、takeover、maintenance、staged-context 或 upgrade 观察，收敛为确定性、体积受限、默认需要人工复核的 Evidence Bundle。人决定是否把它带回中心产品项目；中心项目再按宪法分类证据，而不是让目标项目自动上报、自动修补或自动产生需求。
+
+本阶段固定新增：
+
+- 只读命令 `evidence`；
+- Evidence Input schema 1；
+- Evidence Bundle schema 1；
+- capabilities schema 3 与 exchange protocol 3 的机器声明；
+- 人工转交边界和中心分类模板；
+- A-91 至 A-100。
+
+本阶段不新增 store、不写目标项目、不访问网络、不调用 Provider、不执行测试、不上传证据、不修改 Project Contract，也不实现 Phase C 的升级编排。
+
+## 2. 用户问题
+
+真实目标项目出现问题时，目前只能复制聊天、日志、路径、代码或口头描述返回产品项目。这会同时产生四类风险：
+
+1. 证据携带业务正文、绝对路径、仓库身份、凭据或个人信息；
+2. 关键版本、协议、状态和错误码被遗漏，中心无法复现；
+3. 一次目标项目现象被直接解释为通用内核需求；
+4. 为了“反馈”而引入上传、遥测或中心遥控，突破永久边界。
+
+`1.5.0` 的成功标准不是收集更多数据，而是让人拿到一份**最小、结构化、可核对、不会自行离开项目**的证据。
+
+## 3. 分类与产品边界
+
+本阶段分类为 `optional-adapter-protocol`，服务 AI Exchange Boundary，但不新增第八项内核，也不需要修改产品宪法。
+
+责任固定如下：
+
+| 参与者 | 负责 | 不负责 |
+| --- | --- | --- |
+| 目标项目 Host Agent | 提供已经脱敏的观察输入，调用只读命令，向人展示 bundle | 自动上传、声称已人工复核、修改产品代码 |
+| Frontend Project Context | 严格验证输入，附加本地协议/健康元数据，稳定生成 Evidence Bundle | 读取业务代码、猜测敏感信息、执行复现步骤、决定产品需求 |
+| 人 | 检查自由文本和关联风险，决定是否转交、转交给谁 | 记忆 schema 或手工拼装运行时元数据 |
+| 中心产品项目 | 验证 bundle、聚类、复现、按宪法分类 | 远程控制目标项目、把证据自动晋升为路线或 Contract |
+
+## 4. CLI 合同
+
+唯一新增命令：
+
+```text
+project-context evidence --project PATH --input FILE [--json]
+```
+
+约束：
+
+- 命令永久只读，不接受 `--write`、`--output`、`--upload`、URL、token、destination 或 shell 参数；
+- `FILE` 必须是项目根目录内已存在的普通 JSON 文件，经过既有 path-policy 检查，不跟随越界 symlink；
+- 命令只读取 Evidence Input、现有 Project Context store 与 AI Entry；不读取 input 声明之外的任务工件、日志、业务代码或 Git；
+- uninitialized、partial、invalid、attention 和 clean 都可以产生证据，且所有项目字节保持不变；
+- 输入或 schema 无效返回退出码 2；成功生成 bundle 返回 0，`result: failed` 本身不改变命令退出码；
+- `--json` 输出 canonical pretty JSON；文本模式只给出结果、健康、finding code、bundle digest 和“必须人工复核后转交”的摘要，不展开自由文本；
+- stdout 是唯一输出，重定向或复制属于 Host/人的外部行为，不由产品执行。
+
+## 5. Evidence Input schema 1
+
+输入只表达已经观察到的事实，不包含授权或产品决定：
+
+```json
+{
+  "schemaVersion": 1,
+  "capability": "takeover",
+  "result": "blocked",
+  "environment": {
+    "runtime": "node",
+    "runtimeMajor": 22,
+    "packageManager": "redacted",
+    "projectShape": "single"
+  },
+  "expected": {
+    "code": "takeover-clean",
+    "summary": "A clean project should select ready-for-task."
+  },
+  "observed": {
+    "code": "entry-conflict",
+    "summary": "The managed entry reported an ownership conflict."
+  },
+  "errorCodes": ["ai-entry-ownership-conflict"],
+  "reproduction": [
+    {
+      "operation": "status",
+      "outcome": "blocked",
+      "findingCodes": ["ai-entry-ownership-conflict"]
+    }
+  ],
+  "artifacts": [
+    {
+      "kind": "project-status",
+      "digest": "sha256:..."
+    }
+  ],
+  "redactions": [
+    {
+      "field": "environment.packageManager",
+      "method": "redacted"
+    }
+  ]
+}
+```
+
+### 5.1 固定枚举
+
+- `capability`: `setup | takeover | maintenance | staged-context | upgrade | other-protocol`
+- `result`: `passed | degraded | blocked | failed`
+- `environment.runtime`: `node | other | redacted`
+- `environment.packageManager`: `npm | pnpm | yarn | bun | other | redacted`
+- `environment.projectShape`: `single | monorepo | multi-context | redacted`
+- `reproduction[].operation`: `capabilities | status | setup-preview | sync | check | context | preflight | stage-context | integration-review | publish-entry-preview | remove-entry-preview | upgrade-baseline | other-protocol`
+- `reproduction[].outcome`: `passed | degraded | blocked | failed`
+- `redactions[].method`: `removed | generalized | hashed | redacted | not-collected`
+
+### 5.2 严格限制
+
+- schema 严格拒绝未知字段；
+- `expected.code`、`observed.code`、error/finding code 使用稳定小写 ID；
+- 两个 summary 为必填单行文本，各不超过 500 个 UTF-8 字节；
+- `errorCodes` 最多 32 项，`reproduction` 最多 20 步，`artifacts` 最多 32 项，`redactions` 最多 32 项；
+- canonical UTF-8 输入总量不超过 32 KiB，超限返回 `evidence-input-budget-exceeded`，不得截断；
+- artifact 只允许 `kind + sha256 digest`，不允许 path、URL、正文、base64、文件名或外部 ID；
+- 不接受时间戳、用户名、reviewer、approval、decision、priority、targetVersion 或 release 字段；
+- 输入文件本身是 Host 管理的短生命工件，不被注册为 source，不进入 Contract，也不写入 projection lock。
+
+## 6. 隐私与脱敏合同
+
+schema 通过不等于自由文本已经脱敏。运行时只能保证**按结构不采集**以下字段：
+
+- Project Contract item value/statement；
+- source body、业务代码、diff、日志正文、聊天和模型推理；
+- 项目 ID/name、仓库 URL、绝对路径、分支名、用户名、主机名；
+- token、cookie、环境变量、凭据和上传地址；
+- item/source/path 列表与可反推出业务结构的 locator。
+
+`expected.summary` 与 `observed.summary` 是唯一自由文本面，始终被标为 `human-review-required`。产品不声称通过正则或模型识别完全部敏感信息，也不提供自动“脱敏完成”状态。
+
+如 Host Agent 无法在不暴露业务信息的情况下表达现象，应停止生成可转交证据，只向人报告 `evidence-redaction-blocked`。
+
+## 7. Evidence Bundle schema 1
+
+输出固定为：
+
+```json
+{
+  "schemaVersion": 1,
+  "kind": "target-project-evidence",
+  "product": {
+    "name": "frontend-project-context",
+    "version": "1.5.0",
+    "exchangeProtocolVersion": 3
+  },
+  "capability": "takeover",
+  "result": "blocked",
+  "environment": {},
+  "expected": {},
+  "observed": {},
+  "errorCodes": [],
+  "reproduction": [],
+  "artifacts": [],
+  "redactions": [],
+  "projectContext": {
+    "initialization": "initialized",
+    "health": "conflict",
+    "entryState": "conflict",
+    "findingCodes": ["ai-entry-ownership-conflict"],
+    "schemas": {
+      "contract": 2,
+      "sourcesLock": 1,
+      "projectionsLock": 2
+    }
+  },
+  "transfer": {
+    "state": "human-review-required",
+    "automaticUpload": false,
+    "destination": null
+  },
+  "boundaries": {},
+  "bundleDigest": "sha256:..."
+}
+```
+
+### 7.1 派生规则
+
+- product/version/protocol/schemas 来自当前本地运行时，不接受输入覆盖；
+- `projectContext` 复用 `status` 的初始化、健康、Entry 和 finding code 语义，但剔除项目身份、snapshot digest、source/item/path/readTargets/workUnits；
+- boundaries 复用 capabilities 的永久 false 声明；
+- 输入数组去重并稳定排序；reproduction 保留调用顺序；
+- 不添加 generatedAt、随机 ID、cwd 或机器信息；相同输入与相同 Project Context 状态必须产生逐字节相同 bundle；
+- `bundleDigest` 是排除自身后的 canonical JSON SHA-256；
+- 输出总量不超过 48 KiB，任何超限均失败封闭而不截断；
+- transfer 永远是 `human-review-required`，本阶段没有能把它改为 `approved`、`ready` 或 `sent` 的参数。
+
+### 7.2 状态与观察分离
+
+Evidence Input 的 `result` 是某次能力观察；`projectContext.health` 是生成证据时的治理健康。二者可以不同，命令不得把 clean 解释为观察已通过，也不得把 failed 解释为项目 store 无效。
+
+## 8. 中心接收与分类模板
+
+中心项目只在人工转交后使用以下模板，不由目标项目自动填写产品结论：
+
+```text
+Evidence digest:
+Product version / capability:
+Reproduction status: reproduced | not-reproduced | insufficient
+Constitution category: kernel-defect | constitution-evolution | project-data | optional-adapter | external-tool
+Invariant or completion condition affected:
+Minimal central fixture:
+Duplicate evidence digests / cluster key:
+Human decision: reject | request-more-evidence | design-candidate | project-guidance
+```
+
+固定规则：
+
+1. bundle digest 相同可以去重，但不同 digest 不自动代表不同问题；
+2. 聚类只提高审查优先级，不产生实现顺序；
+3. `failed` 不自动等于内核缺陷；
+4. 只有中心复现违反宪法不变量或既定完成条件，才可进入内核缺陷候选；
+5. `design-candidate` 仍不是设计、实现、Git、发布或目标项目访问授权；
+6. Evidence Bundle 永远不是 Project Contract、source、approval、Action Plan 或 release record。
+
+## 9. capabilities 与协议版本
+
+`1.5.0` 冻结以下 consumer change：
+
+- package version：`1.5.0`；
+- exchange protocol：`3`；
+- capabilities schema：`3`；
+- 新增 `commands: evidence`；
+- 新增 `schemas.evidenceInput: 1`、`schemas.evidenceBundle: 1`；
+- Action Plan、Review Bundle、Assist Bundle、Project Status、Task/Stage schemas 均保持现有版本；
+- action kind 不增加，因为 `evidence` 是只读派生，不是请求持久写入的 action；
+- boundaries 继续声明 `telemetry: false`、`network: false`、`provider: false`、`selfUpdate: false`，并新增 `automaticEvidenceUpload: false`。
+
+capabilities 3 的 schema reader 不需要兼容读取 capabilities 2 文件，因为 capabilities 是运行时输出而非 store；外部 consumer 必须按 schemaVersion 分支。
+
+## 10. migration manifest
+
+`1.5.0` 更新包内 `migration-manifest.json`，精确声明：
+
+- `upgradeFrom` 同时包含当前公共基线 `1.3.1` 与本地能力基线 `1.4.0`；从 `1.3.1` 直达时完整继承 `1.4.0` manifest 的 AI Entry / projection-lock 延迟迁移和回滚声明；
+- Contract、source lock、projection lock、proposal 均无迁移；
+- projection/AI Entry renderer 不变；
+- consumer change 只有 exchange 3、capabilities 3 和两个新 evidence schema；
+- `writes` 为空，rollback class 为 `package-only`；
+- 不读取或转换旧的聊天、日志或用户自建证据文件；
+- 发布前只需候选包独立安装和离线 schema/CLI 冒烟，不需要网络内建能力。
+
+Phase C 的 upgrade check/plan/apply 仍不进入本版本。
+
+## 11. 错误合同
+
+| code | 退出码 | 含义 |
+| --- | --- | --- |
+| `evidence-input-missing` | 2 | input 文件不存在 |
+| `evidence-input-invalid` | 2 | JSON 或 schema 无效 |
+| `evidence-input-outside-project` | 2 | 路径越界或 symlink 不可信 |
+| `evidence-input-budget-exceeded` | 2 | canonical UTF-8 输入超过 32 KiB |
+| `evidence-output-budget-exceeded` | 2 | 完整输出超过 48 KiB |
+| `evidence-redaction-blocked` | 2 | 输入包含结构上禁止的敏感载体或无法形成安全摘要 |
+| `evidence-project-state-unreadable` | 2 | 无法形成最小 Project Context 状态 |
+
+partial/invalid/attention/conflict 是可记录的 Project Context 状态，不因其本身阻止只读证据生成。只有状态无法被现有 `status` 安全解释时才返回 `evidence-project-state-unreadable`。
+
+## 12. 实现结构
+
+获得单独实现授权后，允许的主要变更范围为：
+
+| 文件 | 允许变更 |
+| --- | --- |
+| `src/project-context/evidence-schema.mjs` | 新增严格 input/bundle 归一化、预算和 digest 合同 |
+| `src/project-context/evidence.mjs` | 新增只读 bundle 聚合，复用 status/capabilities |
+| `src/project-context/capabilities.mjs` | capabilities 3、evidence schema 与 boundary 声明 |
+| `src/project-context/exchange-schema.mjs` | package/exchange/capabilities 版本声明，不改变 action plan 语义 |
+| `src/project-context/cli.mjs` | `evidence` 参数 allowlist、输出与退出码 |
+| `schemas/evidence-input.schema.json` | Evidence Input schema 1 |
+| `schemas/evidence-bundle.schema.json` | Evidence Bundle schema 1 |
+| `schemas/capabilities.schema.json` | capabilities schema 3 |
+| `migration-manifest.json` / schema | 1.5.0 无 store 写迁移声明 |
+| `test/project-context/evidence.test.mjs` | A-91 至 A-100 |
+| `test/release/acceptance.test.mjs` | 包文件、版本、manifest、schema 与文档 pin |
+| `README.md`、`docs/04`、`docs/05`、`docs/08`、`UPGRADING.md`、`examples/` | 实现后同步真实公共行为 |
+
+实现不得修改 Contract/source/projection store schema，不得把 Evidence Input 注册为 source，不得引入通用日志解析器、secret scanner、上传器或中心数据库。
+
+## 13. 冻结验收 A-91 至 A-100
+
+- **A-91 严格输入合同**：合法 input 可归一化；未知字段、非法枚举、路径/URL/body/base64/授权字段、超长文本和超量数组稳定失败。
+- **A-92 确定性 Bundle**：相同输入和状态逐字节一致，数组规则稳定，bundle digest 自校验，输出不含时间、随机数、cwd 或机器身份。
+- **A-93 全状态只读采样**：uninitialized、partial、invalid、attention、conflict、clean 都能在零写入下生成准确最小状态；不可读状态失败封闭。
+- **A-94 隐私最小化**：fixture 中的项目 ID/name、绝对路径、source/item/path、Contract 正文、业务代码、日志和 secret 不进入输出；自由文本始终标记人工复核。
+- **A-95 预算与无截断**：32 KiB 输入和 48 KiB 输出边界按 canonical UTF-8 bytes 计算；边界内稳定，越界报错，不静默截断。
+- **A-96 结构化复现**：只接受冻结 operation/outcome/finding code，不执行任何步骤；观察 result 与当前 health 保持分离。
+- **A-97 人工转交边界**：输出永远为 `human-review-required`，无 upload/destination/write 参数，生产源码无网络、遥测或文件输出路径。
+- **A-98 capabilities 与迁移声明**：exchange 3、capabilities 3、两个 schema、无新增 action kind、package-only rollback 与运行时/manifest/package 完全一致。
+- **A-99 中心分类不晋升**：Evidence Bundle 不可作为 proposal/Action Plan/approval 输入；聚类模板不生成 Contract item、产品方向或执行权限。
+- **A-100 永久边界与回归**：A-01 至 A-90、B0、CLI、schema 和发布工件保持；仍无 Provider、Agent Runtime、Git、网络、依赖安装、测试执行、业务写入、自动上传、scheduler 或 daemon。
+
+若每个新增编号对应一个顶层测试，预期实现后总数不少于 106；只能在实现完成后记录实际通过数。
+
+## 14. 实现、验证与发布 Gate
+
+以下权限相互独立：
+
+1. 本文只完成详细设计；
+2. 用户于 `2026-09-11` 以“`1.5.0` 版本开始执行”明确授权本地实现；该权限已用于修改源码、schema、测试、package version、migration manifest 与实现事实文档；
+3. 使用真实目标项目生成证据需要独立范围、脱敏规则和只读访问授权；
+4. 把真实 Evidence Bundle 转交到中心项目需要人逐份决定；
+5. Git commit/tag/push、候选打包、网络和 npm 发布需要新的明确授权。
+
+即使未来实现 A-91 至 A-100 全绿，也不自动获得真实项目或发布权限。
+
+## 15. 明确不做
+
+- 不实现自动上传、遥测、反馈 API、中心账号、队列或控制面。
+- 不让产品扫描业务仓库、日志、diff、聊天或环境变量来“自动找证据”。
+- 不承诺自动识别或清除所有敏感信息。
+- 不保存 Evidence Bundle、Evidence Input、聚类、分析或转交历史。
+- 不把 Evidence Bundle 注册为 source、写入 Contract 或投影。
+- 不根据失败次数、项目数量或相似 digest 自动创建需求。
+- 不提供远程修补、目标项目自更新、Provider 调用或 Agent Runtime。
+- 不实现 Phase C upgrade check/plan/apply。
+- 不发布 `1.4.0` 或 `1.5.0`。
+
+## 16. 停止点
+
+本文已冻结并完成 `1.5.0` 的用户问题、分类、只读 CLI、input/bundle schema、隐私与预算、人工转交、中心分类模板、协议版本、迁移声明、文件范围及 A-91 至 A-100。
+
+用户于 `2026-09-10` 授权“整理下个版本不用发布”，形成了本文；随后于 `2026-09-11` 明确授权开始执行 `1.5.0`。实现已在本地完成并通过 106/106，未生成真实项目证据、提交 Git、访问网络、打包或发布。
+
+本阶段实现权限已消耗。唯一合法下一步是用户明确授权一项具体的实现后工作（例如候选打包、真实项目只读验证或发布），或停止。
+
+## 17. 本地实现结果
+
+`1.5.0` 已新增 `src/project-context/evidence-schema.mjs`、`evidence.mjs`、只读 CLI 入口和两份公开 schema；capabilities schema 与 Exchange Protocol 升至 3，Action Plan/Review Bundle 仍为 2，十类 action kind 不变。migration manifest 同时覆盖 `1.3.1` 与 `1.4.0` 基线，本版本 `writes` 为空且 rollback class 为 `package-only`。
+
+A-91 至 A-100 各对应一项顶层测试，连同 A-01 至 A-90、B0、CLI、machine schema 与发布工件回归共 106/106 通过。测试只使用隔离临时 fixture。实现没有 Provider、Agent Runtime、Git、网络、依赖安装、业务代码执行、自动上传、telemetry、scheduler、daemon 或真实项目访问。