@tea-agent/loop-agent 0.39.0-beta.8 → 0.39.0-beta.9

package/docs/architecture/evolution.md

@@ -33,6 +33,7 @@ loop-agent CLI
 | Worker readiness baseline | Attempt identity、immutable owner、lineage/revision、task-scoped lease、controller protocol、acceptance、reconcile | Agent Worker PR v1 Phase 1–7 / `0.32.0` |
 | Operator Surface | 裸 `agent-worker console`；Operate、`/inspect/`、Operator Chat、recovery CTA、intake bridge | ADR 0005、0011–0013 |
 | 自举与验证 | controller identity、skill snapshot、deterministic/live canary、verified tarball、`verify:tree` receipt | `runtime-boundaries.md`、verification matrix |
+| Source fidelity ledger | 原始 requirement/acceptance 文档保持语义权威，派生 `source/需求.md` 仅作导航视图；确定性 fragment inventory、受管 `requirement-ledger.json`（进入 Task Contract transaction 与 canonical hash）、source binding v2（仅 frontend taskKind，schemaVersion=2 必填字段）、prewrite fail-closed 门禁（`SOURCE_FIDELITY_*`/`source-*` 稳定错误码）、顺序 reconciliation 与独立 reviewer、human resolution 生效、有界提示词与最终 reviewer 核对清单 | `20260824-frontend-source-fidelity-ledger-v1` + `2026-08-24-frontend-source-fidelity-repair-v2`（本页面下方 init-evolution 审查）、`CHANGELOG.md [Unreleased]` |
 
 ### 当前不变量
 
@@ -106,3 +107,47 @@ Evidence & Trust Plane
 2. 证明成立后更新 current capability summary 和本页“当前架构”。
 3. 未证明部分只保留在 active design/exec-plan，不能通过修改措辞升级状态。
 4. 使用者短索引同步到 `website/docs/overview/roadmap.md`，避免复制长版本流水账。
+
+## Init Evolution Review — 2026-08-24 frontend source fidelity ledger
+
+Base/Head：见 `docs/reports/init-evolution/` 中对应 `*-init-evolution-review.md`（若已提交则含 Base/Head 字段；未提交工作区由 CI 非严格模式放行）。
+
+### Changed Surface
+
+- `src/task/source-prepare/**`：新增 `fragment-inventory.ts`、`ledger.ts`；扩展 `types.ts`、`prepare.ts`、`completeness.ts`、`parse-intent.ts`（无外部 API 变化）。
+- `src/task/contract/**`：`requirement-ledger.json` 进入受管 transaction 与 canonical hash；`TaskContractSourceHashesV1` 新增可选 `requirementLedgerSha256`（legacy ref 向后兼容）。
+- `src/workflows/dag/**`：`dagSourceBindingSchema` 拆为 v1/v2 discriminated union（v2 schemaVersion=2，四个 ledger 字段全部必填；v1 strict 拒绝 ledger 字段）；`init-hybrid` 改读已持久化 ledger（缺失/漂移 fail closed）；prewrite 门禁新增 ledger 检查与失败码。
+- `src/task/source-prepare/**`：新增 `ledger-reconciliation.ts`（顺序 reconciliation）、`ledger-review.ts`（独立 reviewer）；fragment inventory 表格行切分、跨文档稳定 REQ-SRC ID、V4 显式 AC 标题；human resolution 生效。
+- `src/worker/observe/**`：新增只读 `GET /api/tasks/:id/ledger` 与展示（安全摘要，不泄漏原文）。
+- `src/worker/console/**`：Draft/ContractPanel/InspectSplitPanel 安全摘要展示。
+- `docs/templates/frontend-implementation-contract.schema.json`：requirements 增加可选 `sourceFragmentIds`/`sourceRefs`，sourceBinding 增加可选 ledger 字段（all-or-none）。
+
+### Decision
+
+**No init impact / Surface check only**。
+
+Rationale：
+
+- 新增均为模块内部实现；不新增 CLI 命令、不改 init 入口、不改变 target-project 初始化行为。
+- `docs/templates/frontend-implementation-contract.schema.json` 已随 `docs/templates/` 目录 glob 打包（`package.json files`），无需新增 manifest 条目。
+- 运行时加载 schema 的 `loadFrontendImplementationContractJsonSchema` 仅做结构性校验（$id/required/properties/const），新增可选字段不破坏既有契约。
+- 不新增任何运行时或开发依赖（node:crypto、既有 zod/Vitest/Vite/React 19）。
+
+### Updates Made
+
+- `docs/architecture/evolution.md`：本条目。
+- `CHANGELOG.md [Unreleased]`、`CONTEXT.md`：glossary 术语。
+- `docs/templates/frontend-implementation-contract.schema.json`：可选字段同步。
+
+### Verification
+
+```bash
+npm run typecheck && npm run console:typecheck
+npx vitest run test/task-source-prepare.test.ts test/task-contract-canonicalize.test.ts test/task-contract-observe.test.ts test/dag-init-hybrid.test.ts test/frontend-implementation-contract.test.ts test/frontend-prewrite-gate.test.ts test/frontend-writer-admission.test.ts test/worker/observe/dag-inspector-node-input.test.ts test/worker/console/inspect-split-panel.test.ts
+```
+
+### Residual Risk
+
+- 长尾 24K 截断遗漏回归：以确定性分片 inventory + ledger 覆盖统计断言固定（AC-FIDELITY-001/007）。
+- 账本漂移/篡改：inputDigest 复用失效 + prewrite fail closed（AC-FIDELITY-003/006）。
+- 既有带引用 frontend task 重建路径变化：ledger 纳入 canonical hash 改变 `observeTaskContractState` 判定，legacy ref 向后兼容覆盖（AC-FIDELITY-004）。

package/docs/init-surface.manifest.json

@@ -30,9 +30,11 @@
     "docs/templates/frontend-task-requirement.md",
     "docs/templates/frontend-task-constraints.md",
     "docs/templates/frontend-design-contract.md",
+    "docs/templates/frontend-implementation-contract.schema.json",
     "docs/templates/worker-dogfood-setup.md",
     "docs/templates/worker-dogfood-evidence.md",
     "docs/templates/harness.schema.json",
+    "docs/templates/spec-registry.schema.json",
     "docs/templates/interactive-ui-round2-experiment.md",
     "docs/templates/product-line/README.md",
     "docs/templates/product-line/AGENTS.md",
@@ -102,6 +104,7 @@
     "docs/feature-workflow.md",
     "docs/verification-matrix.md",
     "docs/loop-agent-harness.md",
+    "docs/spec-registry.json",
     "docs/harness-methodology-tdd.md",
     "docs/harness-methodology-verification.md",
     "docs/harness-methodology-debugging.md",
@@ -177,6 +180,7 @@
     ".pi/settings.json"
   ],
   "initSurface": {
+    "docs/spec-registry.json": "generated",
     "README.md": "managed-block",
     "AGENTS.md": "managed-block",
     ".gitignore": "managed-block",

package/docs/templates/README.md

@@ -37,7 +37,7 @@
 ## Frontend
 
 - `frontend-task-requirement.md`、`frontend-task-constraints.md`、`frontend-design-contract.md` — 前端任务输入与设计合同。
-- `frontend-implementation-contract.schema.json` — 前端实现合同 schema。
+- `frontend-implementation-contract.schema.json` — 前端实现合同 schema（sourceBinding v2 ledger 字段 all-or-none：任一出现则四项齐全，禁止 v1+optional 冒充 v2）。`requirements[].sourceRefs[].items` 使用合法 `$ref: #/$defs/path`（相对路径、无 `..` 逃逸、无反斜杠），模板 JSON 无非法键，运行时加载器可直接编译（AC-003）。
 - `frontend-test-dag.json` — frontend-test DAG 模板；其 deterministic checklist 会拒绝 alternative executable instructions，仅允许 allowlisted `playwright-cli` command。Pi generator/reviser 的 runtime writeSet 仅授权下列目标项目生成路径（不是本仓库文档索引目标）：
 
   ~~~text
@@ -56,6 +56,7 @@
 - `knowledge-sync-dag.json`、`knowledge-graph-bootstrap-dag.json` — 知识同步与图谱初始化 DAG。
 - `knowledge-sync-draft.schema.json` — 知识同步草稿 schema。
 - `harness.schema.json` — `harness.json` 的 IDE JSON Schema。
+- `spec-registry.schema.json` — 项目级 `ai_workspace/loop-agent/spec-registry.json` 的机器校验 schema。
 
 ## 子目录