frontend-project-context 1.3.1 → 1.7.0

package/docs/25-REAL-PROJECT-SOURCE-OF-TRUTH-MAINTENANCE-DESIGN.md

@@ -0,0 +1,409 @@
+# 25 — 真实项目全量应用下的真源维护与分支晋升设计
+
+> 权威说明：本文在现有 Knowledge Maintenance、Branch-aware Staged Context、Evidence Feedback、Target Upgrade 与 Adaptive Context 合同之上，冻结真实项目全面接入、多开发人员并发分支、QA/预发/上线晋升和集中真源维护的设计。产品身份与永久边界仍以 [00-PRODUCT-CONSTITUTION.md](./00-PRODUCT-CONSTITUTION.md) 为准。
+>
+> 状态：`design-frozen; protocol-fixture-repaired-local; real-project-validation-not-authorized`
+>
+> 日期：`2026-09-12`
+>
+> 版本：本地协议 fixture 随当前未发布的 `1.7.0` 工作树实现，不构成新版本或发布候选。用户已授权将协议正确性与 A-130 本地修复统一处理；A-130R 已通过，但随后获授权的 Host/Provider 复验仍为完整 8/8、自适应 7/8，`1.7.0` 继续 release-blocked。本文不授权真实项目写入、Git、CI、进一步 Provider 调用、网络或发布。
+
+## 1. 决定
+
+真实项目中的冲突不可避免。产品不以“没有漂移、没有分支冲突”为目标，而以以下可证伪承诺为目标：
+
+> 每个来源漂移、并发真源候选、过期基线和语义冲突都必须被限定在准确 scope 内，并提供有限、可重算、可验证的恢复路径；不相关任务继续，相关 AI 写入在证据不足时停止，现有代码合并与上线流程默认不被旁路治理阻断。
+
+采用以下总体模型：
+
+1. 主分支或调用方明确指定的生产基线保存唯一已批准 `Project Contract`；
+2. 需求分支只产生短生命周期真源候选，不直接批准长期 Contract；
+3. QA、预发和上线结论必须绑定调用方提供的精确代码/制品快照证据，而不是只绑定分支名；
+4. 多分支最终以当前集成/生产基线和最终合并来源重新判定，不合并两份过期 Contract；
+5. 普通漂移进入集中维护批次；只有与当前任务相关且影响强制 policy、validation 或冲突闭包时，才阻断 AI 的持久修改；
+6. 每个 `attention | conflict | blocked` 必须携带恢复类别、准确影响和下一动作，不能成为无解终止状态；
+7. Git/CI 读取、分支管理、测试、合并、发布和外部队列仍由 Host/现有平台负责，核心只验证显式输入并输出模型无关 Review Bundle。
+
+该设计属于现有 source provenance、human-governed Contract、conflict/drift checking 和 AI Exchange Boundary 的真实团队适配，不改变产品宪法。
+
+## 2. 为什么现有地基仍不完整
+
+### 2.1 已经具备
+
+| 能力 | 当前事实 |
+| --- | --- |
+| 单工作区来源维护 | `review-source → accept-source-change → revise/deprecate → approve --pending` 已可收敛到 clean |
+| 并发写安全 | source/item/project digest、CAS、原子替换和条件恢复可拒绝过期写入 |
+| 分阶段上下文 | Task Context Plan、Stage Receipt/Bundle 与 Integration Review 可绑定 Contract 快照、上下文和 changed paths |
+| 任务/全局健康分离 | `context-query` 可让无关全局 finding 不阻断当前任务 |
+| 客观证据包 | `evidence` 可输出结构最小、需人工复核且不自动上传的 Evidence Bundle |
+| 产品自有升级 | upgrade assessment/plan/apply 可单步迁移受管 store、entry 和 projection |
+
+### 2.2 正式多人应用前仍缺少
+
+1. 分支候选与主分支已批准真源的明确身份隔离；
+2. A/B 分支同时修改同一 source、item 或 subject 时的聚合与裁决合同；
+3. QA 修复、cherry-pick、squash、冲突解决和多需求集成后的精确代码/制品快照绑定；
+4. “需求自身验收可继承”与“集成环境验收必须重跑”的区别；
+5. 上线成功、撤回和回滚分别如何影响长期真源候选；
+6. 发布后集中漂移判定、去重和串行维护方式；
+7. 每个 finding 的有限恢复合同，而不只是 fail closed；
+8. 普通开发人员无感使用、维护者集中处理的角色分离；
+9. 不阻断现有 CI/上线的旁路接入模式；
+10. 可重建派生物、短生命周期工件和应版本化 store 的团队 Git 策略。
+
+现有 `Stage Receipt` 绑定 plan、输入 bundle、Contract snapshots、paths 与验收结果，但不绑定实际部署代码或构建制品摘要。它足以证明上下文交接完整，不足以证明“这次 QA 结论仍适用于当前预发/上线代码”。
+
+## 3. 四层事实模型
+
+### 3.1 已批准项目真源
+
+主分支当前已批准 `Project Contract` 是 AI 长期指导的唯一规范真源。registered source 的当前内容是待核对证据；代码已合并或已上线不自动等于规范正确。
+
+### 3.2 分支任务候选
+
+需求 goal、acceptance、临时决定、changed paths 和可能成为长期规则的 decision candidate 只属于该任务。它们可以帮助 QA 和下一阶段理解需求，但不进入长期 Contract，除非后来通过显式 source/item 维护与批准。
+
+### 3.3 集成候选
+
+多个需求进入 QA、预发或 release 分支后，最终合并内容形成一个新的 observed source/code snapshot。它用于碰撞检查和重新验收，仍不自动批准长期规则。
+
+### 3.4 已发布快照
+
+Host 应把实际生产制品或发布 revision 与当时的 Contract snapshots 关联。它证明“生产运行了什么、使用了哪份治理基线”，不证明部署行为必然是正确规范。回滚时发布快照回到实际运行版本，未完成的真源候选不得晋升。
+
+## 4. 来源选择原则
+
+全面应用不等于把所有业务代码登记为长期真源。
+
+优先登记：
+
+- 公司/项目工程规则与安全边界；
+- 稳定架构和目录职责；
+- API schema、字段定义和状态协议；
+- 经确认的业务决定；
+- 测试、验收说明和发布约束；
+- 长期有效的外部规范引用。
+
+普通页面、组件和易变实现代码默认作为 Host 按任务读取的实现证据，而不是长期规范来源。只有当代码确实是唯一权威表达时才登记为 source，并应尽量缩小 locator 和 item scope，避免任何实现编辑都制造全局漂移。
+
+必须分别报告：
+
+- `sourceObservedChange`：来源字节或结构变化；
+- `contractSemanticChange`：长期指导是否需要改变；
+- `implementationChange`：代码实现变化但规范不变。
+
+三者不得互相自动推导。
+
+## 5. 一个需求一个分支的晋升模型
+
+### 5.1 创建需求分支
+
+Host 为任务提供：
+
+- 稳定 `taskId`；
+- opaque `branchLabel`；
+- `baseRevision`；
+- 三个 Project Context snapshot digest；
+- goal、acceptance、初始 paths；
+- Host 已知 changed paths。
+
+分支只读使用主分支 Contract。任务内决定保存在 plan/receipt 等短生命周期工件中，不直接修改长期 store。
+
+### 5.2 开发与 QA
+
+每次修复导致代码内容、构建制品、验收套件或 Contract snapshot 变化时，产生新的 Host Promotion Evidence。旧 QA 结论保留为历史外部证据，但不得解锁新 revision。
+
+### 5.3 预发与 release 分支
+
+Promotion 前必须重新绑定当前集成快照。需求代码内容等价时可以继承需求自身的局部证据；由于其他需求、依赖、配置和公共模块组合已经变化，集成验收必须重新执行并绑定新的集成制品。
+
+### 5.4 上线与回滚
+
+- 上线成功：最终 source/code snapshot 成为长期真源判定的输入；
+- 上线撤回：分支 decision candidates 失效，不进入 Contract；
+- 生产回滚：发布快照指向实际回滚版本，回滚掉的业务决定不得继续作为当前规范；
+- 部分灰度：必须显式记录适用范围，不得把灰度行为提升为无条件项目事实。
+
+## 6. Host Promotion Evidence
+
+正式实现前应冻结一份严格、短生命周期、无权限的输入 schema。最小字段：
+
+```json
+{
+  "schemaVersion": 1,
+  "kind": "host-promotion-evidence",
+  "taskId": "task-id",
+  "stage": "qa",
+  "baseRevision": "opaque-host-label",
+  "candidateRevision": "opaque-host-label",
+  "sourceSnapshotDigest": "sha256:...",
+  "artifactDigest": "sha256:...",
+  "changedPaths": [],
+  "projectSnapshots": {
+    "contract": "sha256:...",
+    "sourcesLock": "sha256:...",
+    "projectionsLock": "sha256:..."
+  },
+  "acceptanceSuiteDigest": "sha256:...",
+  "verificationResults": []
+}
+```
+
+保证必须分层：
+
+- Project Context 可验证：schema、规范 digest、Project snapshots、路径策略、source/item impact、receipt/bundle 链；
+- Host 断言：Git revision、代码树/patch/制品摘要和 CI 结果确实对应目标平台状态；
+- 人工决定：是否发布、是否接受长期语义、由谁批准。
+
+核心不调用 Git/CI，也不得把 Host 断言包装为自身已验证。
+
+Truth Reconciliation 还必须将候选的 `expectedProjectSnapshots` 与当前受管 store 精确比较，并用 `currentAcceptanceSuiteDigest` 绑定当前验收套件。调用方提供的 `current.sources/items` 不是可信镜像；核心必须对照 live source lock 和 Contract 校验，不一致时 fail closed。
+
+## 7. A/B 分支真源碰撞
+
+设主分支来源与 item 为 `S0/I0`：
+
+```text
+S0 / I0
+├── A: SA / IA candidate
+└── B: SB / IB candidate
+        ↓
+最终集成来源 SAB
+        ↓
+基于 S0 → SAB 重新 review
+        ↓
+人工确认 IAB
+```
+
+规则：
+
+1. A、B 候选都绑定 `S0/I0`，都不是真源；
+2. 普通 Git 不合并两份 Contract replacement；
+3. 同 source、同 item 或同 subject 均产生 truth collision，即使 Git 没有文本冲突；
+4. A 先成为主分支基线后，B 的旧 expected digest 必须 stale，B 基于新基线重算；
+5. 冲突解决改变受影响代码时，A/B 旧局部验收失效；
+6. 最终只对 `SAB/IAB` 执行一次来源接受、item 修订和批准。
+
+碰撞必须分类为：
+
+- `duplicate`：同一结果，去重；
+- `compatible-compose`：可组合，生成完整 replacement；
+- `scope-split`：两者均成立但 scope 不同，收窄或显式 override；
+- `supersede`：新规则替换旧规则；
+- `semantic-conflict`：无法同时成立，必须由对应所有者裁决；
+- `implementation-only`：实现变化但 Contract 语义不变。
+
+## 8. 有限恢复合同
+
+任何阻断 finding 的输出至少包含：
+
+- `code`；
+- `affectedSourceIds`、`affectedItemIds`、`affectedSubjects`、`affectedScopes`；
+- expected/actual digest 或 Host baseline label；
+- `blocksTask` 与 `blocksExistingDelivery` 分开报告；
+- `resolutionKinds`；
+- 每种 resolution 对应的 read-only preview invocation；
+- 需要的人类角色；
+- 解决后必须执行的验证；
+- `recomputeFromCurrentBaseline: true`。
+
+固定恢复类别：
+
+1. keep-current-baseline；
+2. accept-branch-change；
+3. compose-compatible-changes；
+4. split-scope-or-override；
+5. replace-or-deprecate-source；
+6. fix-source-and-rerun；
+7. refresh-promotion-evidence；
+8. defer-scoped-conflict。
+
+`blocked` 只表示当前证据不能安全继续，不得表示系统没有下一步。若工具不能生成任何合法恢复类别，应返回 `recovery-contract-incomplete`，视为产品缺陷。
+
+## 9. 任务健康、全局健康与上线互不混用
+
+| 状态 | 当前 AI 任务 | 现有代码 CI/上线 | 真源维护 |
+| --- | --- | --- | --- |
+| 无关 scope 漂移 | warning 后继续 | 不阻断 | 进入集中批次 |
+| 相关 fact/reference 漂移且有可靠证据 | needs-review/扩展 | 默认不阻断 | 生成判定候选 |
+| 相关强制 policy/validation 漂移 | 持久修改前 blocked | 默认不阻断 | 所有者优先处理 |
+| subject/conflict collision | 受影响 scope blocked | 由现有 CI/人决定 | 必须集中裁决 |
+| Project Context 自身 invalid/partial | AI 治理写入 blocked | 不改变现有业务流水线 | 先恢复 store |
+
+试点期所有 Git/CI 集成默认 advisory。未来即使提升 gate，也只能由公司明确选择高风险 policy/validation 类别；产品不得自行把 attention 转为发布阻断。
+
+## 10. 集中漂移维护
+
+Host/CI Sidecar 在合并或发布后聚合显式证据，Project Context 只读生成一个批次 Review Bundle：
+
+1. 按当前主分支/生产基线去除已经过期的分支候选；
+2. 按 source、item、subject、scope 分组和去重；
+3. 对同一当前 source 只计算一次 live digest；
+4. 区分 byte-only、semantic candidate、source replacement 和 unknown；
+5. 为每组给出上述有限恢复类别和现有 CLI preview；
+6. 维护者串行执行 exact digest/impact 的现有写入命令；
+7. 所有 pending item 解决并显式批准后重新投影；
+8. `status/check` 回到 clean。
+
+批次和队列不是 Project Contract，也不由核心持久化。GitLab/GitHub/CI 工件、内部任务系统或本地 Host 均可承载；核心只消费显式输入并输出确定性结果。
+
+## 11. 团队 Git 策略
+
+推荐 Host 策略：
+
+- versioned：`contract.json`、source/projection locks 和团队选择提交的受管入口/投影；
+- rebuildable：Routing Index，不参与人工真源合并；
+- ephemeral：plan、receipt、bundle、promotion evidence、review batch，不作为长期规范；
+- 普通需求分支不直接批准 Contract 或刷新 locks；
+- 真源维护使用短生命周期独立 PR，始终从最新主分支重建；
+- 同一时间最多一个 maintenance PR 进入写入阶段；
+- stale maintenance PR 不手工解决 JSON 冲突，关闭后从 live baseline 重新生成；
+- 受管 AGENTS 区域冲突时保留人工区域，以最新 Contract 重新投影受管区域。
+
+这些是可选 Host/团队策略，不是核心 Git 能力。核心继续只依赖文件和显式调用方信号。
+
+## 12. 角色与无感使用
+
+### 普通开发人员
+
+- 正常创建需求分支和描述任务；
+- 不理解或编辑内部 JSON；
+- 不处理无关漂移；
+- 只在当前需求存在真实语义冲突时确认需求事实或联系所有者。
+
+### 真源维护者
+
+- 集中查看批次 Review Bundle；
+- 判断 source 是否仍权威；
+- 选择 accept/revise/deprecate/scope split；
+- 对 exact IDs 显式批准。
+
+### 业务/技术所有者
+
+- 只处理其负责 subject 的语义冲突；
+- 不负责执行 Project Context 命令。
+
+### Host/CI Sidecar
+
+- 提供 branch/revision/changed paths/制品/CI 等显式信号；
+- 生成或保存短生命周期工件；
+- 不冒充人类批准，不让 Project Context 核心读取 Git 或执行发布。
+
+## 13. 缺陷与升级证据
+
+正确性不能由开发人员口述证明。缺陷至少应具有一项客观证据：
+
+- 修复前失败、修复后通过的确定性测试；
+- 相同输入下可重复的错误结果；
+- CI job 与精确 artifact digest；
+- schema/Contract invariant 违反；
+- 可复验的 source/item/receipt digest 不一致。
+
+主观反馈只用于评价上手成本、干扰程度和可理解性。
+
+中间层升级仍走独立升级 PR：外部 Host 更新依赖和 lockfile，核心执行 assessment/plan/单步 product-owned migration，随后由现有 CI、项目测试与独立新窗口复验。任何业务分支 receipt/promotion evidence 绑定旧协议或旧 Project snapshots 时必须重建，不能自动迁移为通过。
+
+## 14. 建议新增的只读交换面
+
+实现阶段应优先复用现有维护命令，只新增最小的只读编排面：
+
+1. `Host Promotion Evidence schema 1`：承载 Host 断言的代码/制品/阶段/验证绑定；
+2. `Truth Reconciliation Input schema 1`：输入当前主基线及一个或多个分支/晋升证据；
+3. `Truth Reconciliation Review Bundle schema 1`：输出 collision groups、影响、保证等级和有限恢复动作；
+4. 一个只读命令，例如 `reconcile-truth --project PATH --input FILE... --json`；
+5. 可选 Git/CI Sidecar 示例，只负责采集显式信号和展示结果，不进入核心依赖。
+
+不得新增：
+
+- `apply-plan` 或自动执行 Review Bundle；
+- Git/CI/Provider/issue tracker client；
+- 持久 branch/task/queue store；
+- 自动 acceptance、approval、merge、publish 或 rollback；
+- 业务代码解析器和框架专用真源判断；
+- 从已上线代码自动生成长期规范。
+
+## 15. Finding 草案
+
+- `truth-source-collision`；
+- `truth-item-collision`；
+- `truth-subject-collision`；
+- `truth-candidate-baseline-stale`；
+- `truth-current-baseline-invalid`；
+- `promotion-code-snapshot-unbound`；
+- `promotion-evidence-stale`；
+- `promotion-integration-verification-required`；
+- `truth-owner-review-required`；
+- `truth-reconciliation-input-invalid`；
+- `recovery-contract-incomplete`。
+
+每个 finding 必须稳定排序、结构化、无来源正文，并遵守第 8 节恢复合同。
+
+## 16. 可证伪验收合同
+
+以下编号延续 A-130；它们是设计门，不代表实现授权。
+
+| 编号 | 场景 | 必须结果 |
+| --- | --- | --- |
+| A-131 | A/B 基于同一 digest 修改同一 source | 输出一个 source collision，两个候选都不晋升 |
+| A-132 | 不同 source 修改同一 subject | 即使 Git path 不重叠也输出 semantic collision |
+| A-133 | A 先成为新主基线，B 仍提交旧 expected digest | B stale，必须从当前基线重算且不覆盖 A |
+| A-134 | QA 通过后代码修复改变 code/artifact digest | 旧 Promotion Evidence 失效，不能解锁预发 |
+| A-135 | cherry-pick/squash 改变 revision label 但 Host 证明内容等价 | 需求局部证据可继承，保证标记仍为 host-asserted |
+| A-136 | 多需求进入预发，当前需求内容未变 | 集成验证仍必须绑定新的组合制品 |
+| A-137 | 全局漂移与当前任务 scope 无关 | global attention、task ready，普通流水线不阻断 |
+| A-138 | 当前任务强制 policy/validation 漂移 | 只阻断相关 AI 持久修改，并返回有限恢复动作 |
+| A-139 | 上线撤回或生产回滚 | 未实际运行的 decision candidate 不得晋升长期 Contract |
+| A-140 | 多分支批次包含重复、兼容、scope split 和冲突 | 稳定分组、去重并为每组给出合法 resolution kinds |
+| A-141 | 任一 attention/conflict/blocked finding | 均有准确影响、恢复入口、责任角色和重算要求 |
+| A-142 | Sidecar 输入 Git/CI 信号 | 核心仍零 Git/网络/Provider/任务执行/自动批准/持久队列 |
+| A-143 | maintenance PR 基线过期 | 不允许手工合并旧 store；从最新主分支重建后可收敛 |
+| A-144 | 真实项目完整需求周期 | 开发→QA→预发→上线/回滚→集中真源维护可由客观证据重建，且现有业务 CI 默认不被旁路治理阻断 |
+
+A-131 至 A-143 可在隔离 fixture 中实现；A-144 必须在获得真实项目、Host/Git/CI 数据读取和必要外部传输授权后单独执行。真实反馈只评价使用体验，正确性必须由测试、digest、CI 与实际发布证据判定。
+
+## 17. 实施顺序与停止条件
+
+### 阶段 0：设计（本次完成）
+
+- 冻结事实模型、碰撞规则、Promotion Evidence、集中维护和验收；
+- 不修改产品代码或 schema；
+- 不访问目标项目或外部系统。
+
+### 阶段 1：协议 fixture（已修复并完成）
+
+- 已实现 Host Promotion Evidence、Truth Reconciliation Input 与 Truth Reconciliation Review Bundle schema 1；
+- 已实现只读 `reconcile-truth --project PATH --input FILE... --json`；
+- A-131 至 A-143、A-130R 及全部回归共 153/153 通过；
+- 新增四项协议回归：候选 Project snapshot 过期必须产生阻断 finding；current source/item 必须与 live store 集合及内容完全一致；Promotion Evidence 必须同时绑定 Project snapshots 与 acceptance suite；source-only promotion finding 必须保留 item/subject/scope 影响；
+- 公开 Truth Reconciliation Review Bundle schema 已从宽松 object 收紧为与 runtime 一致的严格结构；A-140 已真实覆盖 duplicate、compatible-compose、scope-split 和 semantic-conflict；
+- 不实现 Git Adapter；
+- Exchange Protocol 与 capabilities 升为 6，store、Action Plan 与 Review Bundle schema 不变。
+
+### 阶段 1.1：Truth Resolution Closure（已完成）
+
+- Truth Reconciliation Input 与 Review Bundle 升至 schema 2，增加 `--previous-review`、finding digest、resolution contract 与重算终态；
+- Contract 修正与外部实现修复保持分流，核心不获得业务代码、Git、CI、Provider 或自动裁定权限；
+- A-130T-01 至 A-130T-10 与全部回归纳入 194/194；
+- Exchange Protocol 与 capabilities 升至 7，store、Action Plan、Review Bundle 与持久 renderer 不变。
+
+### 阶段 2：可选 Sidecar 与全项目初始化方案
+
+- 用现有公司 Git/CI 能力采集输入；
+- 只生成 evidence/review，不改变现有 build/deploy gate；
+- 需要 Git/CI 读取范围和目标项目的单独授权。
+
+### 阶段 3：真实项目全量内部验证
+
+- 一个真实项目的所有适合 AI 的开发任务默认经过中间层；
+- 完整走过需求分支、QA 修复、预发、上线或回滚和发布后集中真源维护；
+- A-144 使用客观证据判定；
+- Provider 传输、目标项目写入、Git 和发布分别授权。
+
+停止规则：阶段 1 协议 fixture、A-130 本地补救及已授权的失败复验完成后停止。没有新的明确授权，不继续 A-130 设计/实现修订，不初始化真实项目，不新增 Sidecar、Provider/Git/CI 能力，不执行 A-144，不再次调用 Provider，也不发布任何版本。
+
+## 18. 后续裁定闭环修复
+
+阶段 1 已证明碰撞检测、影响定位和恢复类别可用；其占位式恢复输入、上一 Review 绑定、Contract 修正与外部代码修复分流、机器可验证终态缺口，已在 [docs/26](./26-A130-QUALITY-CLOSURE-AND-ADAPTIVE-DELIVERY-REPAIR-DESIGN.md) 的 Truth Resolution Closure 本地实现中闭合。Truth Reconciliation Input/Review Bundle 已升至 schema 2，A-130T-01 至 A-130T-10 与完整回归共 194/194 通过。
+
+docs/25 继续拥有真源维护的长期语义；docs/26 只拥有这次未发布 `1.7.0` 的闭环修复合同。该授权不包含自动裁定、业务代码写入、持久候选队列、真实项目 A-144、Sidecar、Provider、Git/CI、网络或发布。