@tea-agent/loop-agent 0.10.0 → 0.12.0

package/docs/design/README.md

@@ -2,33 +2,54 @@
 
 `docs/design/` 存放将 `loop-agent` 作为更大产品线 agent 平台内仓库本地 runtime 的规划笔记。这些是设计输入，不是 `src/` 已具备该能力的证明。
 
-## 文档
+## 契约与实现映射（优先读）
 
-| 文档 | 用途 |
-|---|---|
-| `DESIGN-cursor.md` | Observe 暖白运行控制台采用的 Cursor 风格视觉参考与设计 token |
-| `DESIGN-lovable.md` | Lovable 风格的暖色视觉系统参考 |
-| `产品线共享知识库.md` | 产品线文档仓库作为上游事实源 |
-| `研发模式.md` | 10 个工作日 Feature 团队工作流 |
-| `六个月规划.md` | 六个月路线图与目标架构 |
+| 文档 | 用途 |
+|---|---|
 | `taskspec-to-loop-agent-mapping.md` | 将产品线 TaskSpec 适配为 `loop-agent` task 的契约 |
+| `taskspec-to-loop-agent-mapping.yaml` | 同上契约的结构化对照表 |
 | `state-and-failure-taxonomy.md` | 文档、Task Pool、DAG、Loop 共用的 canonical status 与 failure taxonomy |
-| `archive/2026-07-07-agent-worker-plan.md` | 已归档：Worker 落地计划（基线 0.3.0，M1-M7 物化/调用/Task Pool/batch/morning report 路线图；已随 0.8.0 发布实现于 `src/worker/`） |
-| `archive/2026-07-07-taskspec-plan.md` | 已归档：TaskSpec v0.1 schema 设计（基线 0.3.0，TaskSpec/AcceptanceSpec/TaskGraphSpec schema 与 materialize 规则；已实现于 `src/worker/task-spec/`） |
+| `frontend-implementation-workflow.md` | 前端 DAG 实现 / 评审 / 验证工作流与证据约定 |
+
+## 路线与产品线笔记（非实现证明）
+
+| 文档 | 用途 |
+|---|---|
+| `dynamic-workflow-dag-engine-roadmap.md` | Dynamic Workflow 适配分析与阶段规划；**页首有实现状态 / Pi-only 校准条**（已落地 vs 设计输入）；正文 Cursor 叙述视为历史 |
+| `六个月规划.md` | 长期路线；**页首 2026-07-15 / 0.11.0 校准**；第 1–2 月为 archive/reports 指针，当前有效前瞻从第 3 月起 |
+| `产品线共享知识库.md` | 产品线文档仓库作为上游事实源；**页首 2026-07-15 / 0.11.0 校准**（模板+Feature dogfood 已落地 vs docs-sync 未来） |
+| `研发模式.md` | 10 个工作日 Feature 团队工作流 |
+| `腾讯实践对当前项目的指引.md` | 腾讯 Harness Engineering 实践对本仓库的映射笔记；源文见 `website/docs/practices/tencent-harness-engineering/index.md` |
+
+## 视觉参考
+
+| 文档 | 用途 |
+|---|---|
+| `2026-07-14-loop-agent-self-update-notifier.md` | loop-agent CLI 自更新提醒设计（设计已确认，尚未实现；覆盖用户级状态、npm global 来源证明、精确安装与验证边界） |
+| `DESIGN-cursor.md` | Observe 暖白运行控制台采用的 Cursor 风格视觉参考与设计 token |
+| `DESIGN-lovable.md` | Lovable 风格的暖色视觉系统参考 |
+
+## 已归档
+
+| 文档 | 用途 |
+|---|---|
+| `archive/2026-07-07-agent-worker-plan.md` | 已归档：Worker 落地计划（基线 0.3.0，M1-M7；已随 0.8.0 发布实现于 `src/worker/`） |
+| `archive/2026-07-07-taskspec-plan.md` | 已归档：TaskSpec v0.1 schema 设计（已实现于 `src/worker/task-spec/`） |
 | `archive/2026-07-10-下一阶段任务-功能开发完成.md` | 已归档：真实样本、失败硬化与 QA 闭环的功能性开发完成记录 |
-| `archive/2026-07-10-observe-ui.md` | 已归档：agent-worker 本地只读可观测 UI v0 设计（事件流 / SSE / stale 诊断、事件契约与验收边界；OBS-001～010 已完成，0.9.0 暖白重设计在其上演进） |
-| `archive/2026-07-10-observe-ui-optimization.md` | 已归档：Observe UI 中文化、DAG-first 总览、进行中 DAG 置顶、read-model enrichment、Pi `session-events.jsonl` 落盘与过程时间线（UI-1～UI-9 已实现） |
-| `archive/2026-07-10-observe-ui-goal.md` | 已归档：OBS-001～010 逐任务进度看板（全部 ✅ done） |
-| `archive/2026-07-11-第一月规划.md` | 已归档：首月落地计划（0.8.0 发布 + Round 1/2/3 累计 20 runs / 10 success / 50% / 两次 owner morning decision，第一个月闭环目标全部达成） |
-| `archive/2026-07-11-第一月wbs.md` | 已归档：首月 WBS 与分工（与第一月规划配套，任务编号与估算为历史记录） |
-| `archive/2026-07-12-第二月规划.md` | 已归档：第二月本地 Feature 交付闭环计划（M2-01～08 全部完成；F-2026-002 完整 Closeout、F-2026-003 真实失败恢复闭环、月末硬指标全达成；完成审计见 `docs/reports/2026-07-12-m2-completion-audit.md`） |
+| `archive/2026-07-10-observe-ui.md` | 已归档：Observe UI v0 设计（OBS-001～010；0.9.0 暖白重设计在其上演进） |
+| `archive/2026-07-10-observe-ui-optimization.md` | 已归档：Observe UI 中文化与过程时间线（UI-1～UI-9 已实现） |
+| `archive/2026-07-10-observe-ui-goal.md` | 已归档：OBS-001～010 逐任务进度看板（全部 done） |
+| `archive/2026-07-14-observe-ui-roadmap.md` | 已归档：Observe R1–R5 运营控制台路线图（资源池/Batch-Run/Feature 关联/事件时间线/前端模块化；证据见 completed plans + reports） |
+| `archive/2026-07-11-第一月规划.md` | 已归档：首月落地计划（0.8.0 + Round 1/2/3 闭环） |
+| `archive/2026-07-11-第一月wbs.md` | 已归档：首月 WBS 与分工（历史记录） |
+| `archive/2026-07-12-第二月规划.md` | 已归档：第二月本地 Feature 交付闭环（M2-01～08；见 `docs/reports/2026-07-12-m2-completion-audit.md`） |
 
 ## 命名约定（2026-07-09 起）
 
 | 名称 | 含义 | 状态 |
 |---|---|---|
 | `loop-agent` | 仓库本地 runtime / 治理控制器 CLI | 已发布 |
-| `agent-worker` | 产品线 TaskSpec 批处理适配层 CLI（`bin/agent-worker.js`） | 已发布（0.5.0） |
+| `agent-worker` | 产品线 TaskSpec 批处理适配层 CLI（`bin/agent-worker.js`） | 已发布 |
 | `agent-platform` | 早期规划设想名；**不是**当前 CLI。若出现在六个月目标架构中，仅表示未来产品线 monorepo / 上层服务集合，不得写成可执行命令 |
 
 当前真实分层：
@@ -37,12 +58,12 @@
 产品线 docs / TaskSpec / TaskGraph
   → agent-worker（本地批处理适配）
     → loop-agent（runtime kernel）
-      → Cursor / Pi / shell / static
+      → Pi（受治理 Agent） / shell / static
+      → cursor-prompt（显式手工 one-shot sidecar，非受治理 writer）
 ```
 
 命令示例一律使用 `agent-worker`，不要再写 `agent-platform task ...`。
 
-
 ## 维护规则
 
 设计笔记变更时：
@@ -50,6 +71,7 @@
 1. 保持 TaskSpec 字段、status 名称、failure category 与命令示例与契约文档一致
 2. 未来平台组件标为目标架构，除非已存在于 `src/` 或 `scripts/`
 3. 当前 CLI 命令示例只用 `agent-worker` / `loop-agent`；`agent-platform` 仅可出现在“未来 monorepo/上层服务”语境，并显式标注未实现
-4. `src/task/config-types.ts` 或 DAG profile routing 变更时更新 `taskspec-to-loop-agent-mapping.md`
+4. `src/task/config-types.ts` 或 DAG profile routing 变更时更新 `taskspec-to-loop-agent-mapping.md` / `.yaml`
 5. DAG report category、Loop failure class 或 Task Pool state 变更时更新 `state-and-failure-taxonomy.md`
-6. 运行 `bash scripts/check-repo.sh`
+6. 过期月规划 / 已落地专题设计迁入 `archive/`，并更新本 README
+7. 运行 `bash scripts/check-repo.sh`

package/docs/development-principles.md

@@ -20,7 +20,7 @@ loop-agent 是面向 agentic coding 的工作流 runtime。仓库应保持小而
 2. 设计新行为前先搜索现有代码、文档、脚本与测试。
 3. Shell 验证是完成权威。
 4. Runtime 状态在 `.harness/`；持久决策在 `docs/`。
-5. Pi writer 节点与可选 Cursor 写执行必须由显式 allowed/forbidden paths 约束。
+5. Pi writer 节点必须由显式 allowed/forbidden paths 与 writeSet 约束；Cursor 仅可作为 `cursor-prompt` one-shot sidecar，不进入受治理 DAG/Loop 写入路径。
 6. Pi review/planning 路径是 advisory，除非后跟确定性验证。
 7. 反复出现的约束应固化为文档、测试、脚本、检查或模板。
 8. 不要把隐藏流程状态只留在聊天里。
@@ -31,7 +31,7 @@ loop-agent 是面向 agentic coding 的工作流 runtime。仓库应保持小而
 
 - 源码：`src/`
 - 测试：`test/`
-- Skill 指令：`skills/`
+- Skill 指令：源码仓库和 npm 包内置在 `skills/`，目标项目 repo-local skills 在 `.agents/skills/`
 - 验证与维护脚本：`scripts/`
 - 治理与交接产物：`docs/`
 

package/docs/exec-plans/active/README.md

@@ -6,6 +6,4 @@
 
 当前 active execution plan：
 
-- `2026-07-12-observe-warm-console-redesign.md` — 以暖白、细边界和高密度信息架构重构 Observe Dashboard。
-
-- 已归档：第二月 M2-01～M2-08、`../completed/2026-07-11-observe-dashboard-page-system.md`、`../completed/2026-07-11-observe-dashboard-detail-refinement.md`、`../completed/2026-07-11-observe-terminal-dag-kpi.md`、`../completed/2026-07-11-observe-polling-efficiency.md`、`../completed/2026-07-11-command-performance-guardrails.md` 及更早计划。
+- 已归档：`../completed/2026-07-15-repair-artifact-gate-runtime-contract.md`、`../completed/2026-07-14-observe-ui-r5.md`、`../completed/2026-07-14-observe-ui-r4.md`、`../completed/2026-07-14-observe-ui-r3.md`、`../completed/2026-07-14-observe-ui-r2.md`、`../completed/2026-07-14-observe-ui-r1.md`、`../completed/2026-07-14-init-canonical-layout.md`、`../completed/2026-07-12-observe-warm-console-redesign.md`、`../completed/2026-07-14-website-docs-ia-and-converge.md`、`../completed/2026-07-13-versioned-self-hosting-bootstrap.md`、`../completed/2026-07-12-pi-only-agent-runtime.md`、第二月 M2-01～M2-08、`../completed/2026-07-11-observe-dashboard-page-system.md`、`../completed/2026-07-11-observe-dashboard-detail-refinement.md`、`../completed/2026-07-11-observe-terminal-dag-kpi.md`、`../completed/2026-07-11-observe-polling-efficiency.md`、`../completed/2026-07-11-command-performance-guardrails.md` 及更早计划。

package/docs/exec-plans/completed/README.md

@@ -4,6 +4,23 @@
 
 npm 包携带本 README 作为目录契约。具体 completed plan 属于目标仓库历史，不从 loop-agent 源码历史复制。
 
+- [`2026-07-15-repair-artifact-gate-runtime-contract.md`](2026-07-15-repair-artifact-gate-runtime-contract.md) — 显式 `repairNodeId` + 严格 repair writer 契约、DagSpec `runtimeContract` capability preflight，以及 run-owned controller identity（resume 漂移 fail-closed）
+- [`2026-07-14-backend-test-dag-template.md`](2026-07-14-backend-test-dag-template.md) — 通过 `taskKind: "backend-test"` 生成需求分析、功能用例、pytest 自动化、执行与复盘的 Pi-only 专用 DAG
+- [`2026-07-14-observe-ui-r5.md`](2026-07-14-observe-ui-r5.md) — Observe 原生 ES module 拆分、四态 helper、Pool hash 筛选与入口 re-export
+- [`2026-07-14-observe-ui-r4.md`](2026-07-14-observe-ui-r4.md) — Observe Batch/Pool 有界事件时间线、cursor/limit、JSONL 容量与投影 fault-first
+- [`2026-07-14-observe-ui-r2.md`](2026-07-14-observe-ui-r2.md) — Observe Batch / Worker Run 证据化详情、三层只读结构与安全 artifact preview
+- [`2026-07-14-observe-ui-r3.md`](2026-07-14-observe-ui-r3.md) — Observe Feature 决策详情、copy-only 建议命令与 canonical 对象关系导航
+- [`2026-07-14-observe-ui-r1.md`](2026-07-14-observe-ui-r1.md) — Observe 资源池总览、Task 下钻、精确对象关联与有界 run history
+- [`2026-07-14-init-canonical-layout.md`](2026-07-14-init-canonical-layout.md) — 目标项目治理资料统一到 `ai_workspace/loop-agent/` 与 `.agents/skills/`，并为旧布局提供保守安全迁移
+- [`2026-07-14-self-update-notifier-implementation.md`](2026-07-14-self-update-notifier-implementation.md) — 实现 loop-agent CLI 自更新提醒，覆盖拒绝版本、精确安装、npm global 来源证明和验证收口
+- [`2026-07-12-observe-warm-console-redesign.md`](2026-07-12-observe-warm-console-redesign.md) — 以暖白、细边界和高密度信息架构重构 Observe Dashboard；多轮细节调整后按用户确认收口归档。
+- [`2026-07-14-website-docs-ia-and-converge.md`](2026-07-14-website-docs-ia-and-converge.md) — Website 文档信息架构、双树边界与 `docs-converge` 同步机制
+- [`2026-07-14-frontend-spec-source-fallback.md`](2026-07-14-frontend-spec-source-fallback.md) — 统一前端规范来源为知识库优先、失败后强制检索当前项目 `openSpec/`
+- [`2026-07-13-test-environment-stability.md`](2026-07-13-test-environment-stability.md) — 修复 Windows Git Bash、npm CLI 启动与 Git/Delivery 测试资源分类，避免验证节点反复失败并跳过 DAG 收口
+- [`2026-07-13-sdd-embedded-skills.md`](2026-07-13-sdd-embedded-skills.md) — 目标项目 repo-local SDD skills 的可选 DAG 节点嵌入增强，loop-agent 保持流程、状态与写边界控制
+- [`2026-07-13-frontend-skill-contracts.md`](2026-07-13-frontend-skill-contracts.md) — 补齐前端节点 Skill 的输入、输出、证据与阻断契约，并预留组件/设计知识库接入 TODO
+- [`2026-07-13-versioned-self-hosting-bootstrap.md`](2026-07-13-versioned-self-hosting-bootstrap.md) — 固定已发布 controller identity、冻结 run-owned skills，并由隔离候选包完成 deterministic self-hosting takeover canary
+- [`2026-07-12-pi-only-agent-runtime.md`](2026-07-12-pi-only-agent-runtime.md) — 将 DAG、Loop、Delegate 和 Worker 收敛为 Pi-only 受治理 runtime，仅保留独立的 one-shot `cursor-prompt` sidecar
 - [`2026-07-11-m2-01-feature-review-model.md`](2026-07-11-m2-01-feature-review-model.md) — 第二月首个纵向切片：严格派生 Feature 状态、AC/Delivery/Closeout 证据与只读 `feature review`
 - [`2026-07-12-m2-02-feature-run-orchestration.md`](2026-07-12-m2-02-feature-run-orchestration.md) — Feature 级 dry-run 与复用现有 Worker pipeline 的薄编排入口
 - [`2026-07-12-m2-03-follow-up-tracer-bullet.md`](2026-07-12-m2-03-follow-up-tracer-bullet.md) — ProductBug 失败到人工批准 FIX、依赖重连、Ready 与 verified lineage 的纵向闭环
@@ -48,3 +65,9 @@ npm 包携带本 README 作为目录契约。具体 completed plan 属于目标
 - [`2026-07-10-obs-009.md`](2026-07-10-obs-009.md) — stale、quiet 与 timeout-risk 诊断
 - [`2026-07-10-obs-010.md`](2026-07-10-obs-010.md) — Failure Inbox、文档、package surface 与 smoke 验证
 - [`2026-07-10-observe-ui-review-remediation.md`](2026-07-10-observe-ui-review-remediation.md) — 修复 Observe UI 事件链路、历史 run 投影、artifact 安全边界与失败状态展示
+
+- [`2026-07-13-exec-plan-lifecycle.md`](2026-07-13-exec-plan-lifecycle.md)
+
+- [`2026-07-15-readonly-node-retry.md`](2026-07-15-readonly-node-retry.md)
+
+- [`2026-07-15-init-update-surface-coverage.md`](2026-07-15-init-update-surface-coverage.md)

package/docs/feature-workflow.md

@@ -90,7 +90,7 @@ loop-agent run-dag --dag <temp-dir>/<task-id>-dag.json --cwd .
 2. `dag validate` 校验 schema、依赖、governance profile、写边界、model routing、shell 验证元数据
 3. `run-dag` 加载 DAG、按拓扑排序为 ranks、有界并发执行可运行节点、持久化到 `.harness/dag-runs/<lifecycle>/<run-id>/`，并转入 `completed` 或 `paused`
 
-标准生成的 hybrid DAG 默认无 Cursor：
+标准生成的 hybrid DAG 固定为 Pi-only writer：
 
 ```text
 contract-pi
@@ -102,7 +102,50 @@ contract-pi
   -> closeout-pi
 ```
 
-`implement-pi` 使用 `executor: "pi"` 与 `toolProfile: "write"`。当 `harness.json` 显式禁用 Pi 并启用 Cursor 时，实现与修复 writer 节点改用 `implement-cursor` / `repair-cursor`。
+`implement-pi` / `repair-pi` 使用 `executor: "pi"` 与 `toolProfile: "write"`。受治理 runtime 不再生成或接受 `implement-cursor` / `repair-cursor`；旧 Cursor DAG 会在 schema 校验阶段失败，需要重新生成。
+
+前端任务可通过 `task.json.taskKind = "frontend-implementation"` 选择专用模板：
+
+```text
+frontend-contract-pi
+  -> frontend-scout-pi
+  -> frontend-plan-pi
+  -> frontend-design-gate-pi
+  -> frontend-design-gate-shell
+  -> frontend-implement-pi
+  -> frontend-static-verify-shell
+  -> frontend-behavior-verify-shell
+  -> frontend-review-pi
+  -> frontend-review-gate-shell
+  -> frontend-closeout-pi
+```
+
+这条链在实现前加入 design gate，并将前端静态验证与行为验证分开建模；当前 MVP 不包含独立 a11y、视觉回归或浏览器自动化 executor。
+
+后端测试任务可通过 `task.json.taskKind = "backend-test"` 选择专用模板；它不新增 governance profile：
+
+```text
+analyze-inputs-pi
+  -> generate-backend-functional-cases-pi
+  -> review-backend-cases-pi
+  -> review-backend-cases-gate-shell
+  -> generate-backend-pytest-pi
+  -> execute-backend-pytest-shell
+  -> test-retrospect-pi
+```
+
+这条链覆盖后端功能测试从需求分析到复盘评级的全链路流程：
+
+1. **analyze-inputs-pi**：读取需求.md 和开发详设等参考文档，产出端到端测试分析契约（范围、风险、策略要点）
+2. **generate-backend-functional-cases-pi**：根据契约生成结构化后端功能测试用例（Markdown），用例 ID 带 `BE-` 前缀（如 `BE-ORDER-001`），写入 `testcase/md/`
+3. **review-backend-cases-pi**：评审后端功能测试用例，输出审查报告 + `VERDICT: pass` / `VERDICT: request-revision`
+4. **review-backend-cases-gate-shell**：只有评审首条 verdict 为 `VERDICT: pass` 时才允许继续生成 pytest
+5. **generate-backend-pytest-pi**：将后端功能用例转化为 pytest 自动化代码，仅写入 `testcase/**/test_*.py`
+6. **execute-backend-pytest-shell**：执行 `pytest testcase/` 并生成 HTML 报告
+7. **test-retrospect-pi**：读取上游审查报告和测试报告，生成复盘报告 + 成熟度评级（A/B/C/D）
+
+前端测试模板（`frontend-test-dag`）后续沿用对称命名即可接入。
+前端 shell 验证优先使用任务源 `需求.md` / `执行约束.md` 中声明的前端验证命令，例如 `npm run typecheck`、`npm run build`、`npm test`；解析不到时再使用 adapter 验证命令和模板 fallback。
 
 `verify-shell` 使用 adapter 根据 task verify preset/quota 解析出的最终验证命令，并把新鲜 exit code/stdout/stderr 交给后续只读 verifier。review-gated 模板继续插入：
 
@@ -112,12 +155,29 @@ verify-shell -> verify-pi -> review-pi -> review-gate-shell -> closeout-pi
 
 supervised 模板在实现路径上增加 write-set audit、soft/hard shell 验证、process supervision、有界 repair、decision gates 与可选 convergence retry。
 
+### 只读 Pi 节点安全重试
+
+所有生成模板都会为安全的只读 Pi 节点（planner/scout/reviewer/verifier/closeout，且 `writePolicy=read-only|none`、非 writer、非 dynamic、非 decision-gate）自动声明默认 `retryPolicy`（总尝试 3 次，手工配置最多 5 次，指数退避，单次等待上限 30s）。supervisor 与 implementer 明确不在资格范围。仅重试 `timeout`、`network`、`rate-limit`、`unavailable`；`quota`、`auth`、`invalid-output`、`write-guard` 与未知失败不重试。每次 attempt 保留独立证据，详见 [docs/agent-dag-runner.md](./agent-dag-runner.md#retry-read-only-pi-nodes)。
+
+### 可选 repo-local SDD skill 增强
+
+`dag run-task` 会在目标项目的 `.agents/skills/` 中探测三个可选 skill：
+
+- `SDD-requirement-analysis` → `contract-pi`
+- `SDD-design-analysis` → `plan-pi`
+- `SDD-implementation-test-review` → `implement-pi`、`repair-pi`、`verify-pi`、`review-pi`
+
+命中时，skill 通过节点 `skills` 进入现有 resolved instruction 和 run-owned snapshot 链路，并在节点任务中收到 embedded-mode 约束：只为当前 DAG 阶段提供知识、规范与方法，不得更新 `working_requirements_status.md`、推进 SDD 状态、触发 SDD 用户确认或执行归档。节点的读写边界、当前阶段与输出契约优先；writer 仍只允许写入显式 `writeSet`。`SDD-code-spec-init` 与 `SDD-project-how-to-spec-init` 不会在普通功能 DAG 中自动运行。
+
+探测不到这些 repo-local skills 时，DAG 不追加节点 skill 或约束块，保持当前默认流程。用户级或 npm 包内同名 skill 也不会作为自动启用信号。
+
 源码参考：
 
 - `src/commands/dag-run-task.ts`
 - `src/commands/dag-validate.ts`
 - `src/commands/run-dag.ts`
 - `src/workflows/dag/init-hybrid.ts`
+- `src/workflows/dag/sdd-embedded.ts`
 - `src/workflows/dag/runner.ts`
 
 监督 agent 仍负责：
@@ -130,6 +190,21 @@ supervised 模板在实现路径上增加 write-set audit、soft/hard shell 验
 
 声称 Production Readiness v0.1 的低/中风险单仓库任务，另须遵循 `docs/production-readiness.md` 与 `docs/templates/production-readiness-checklist.md`。该标准冻结支持范围、非目标、必需 DAG 证据、failure routing 字段与最终验证门禁。
 
+## Exec-plan 生命周期
+
+exec-plan 不是手工文档；它有确定性 CLI 生命周期，并与 `dag run-task` 共享同一索引校验源。
+
+```bash
+loop-agent plan create <plan-id> "<title>"
+loop-agent plan complete <plan-id> --summary "<summary>"
+loop-agent plan check
+```
+
+- `new-task` 不自动绑定 exec-plan；微小任务仍可不创建计划。
+- `plan create` 优先读取目标项目 `<governanceRoot>/templates/exec-plan.md`，不存在时回退到发布包内置模板；create/complete 同步 active/completed 索引，拒绝重复 id、路径穿越与不安全文件名，多文件操作均具备回滚保护。
+- `dag run-task` 在生成 DAG 草稿前运行 `plan check` 同源校验，索引漂移立即失败；空仓库与索引一致的仓库不受影响。
+- `plan list`（只读）与 `docs archive`（兼容入口）保留；`scripts/check-exec-plan-index-sync.sh` 仍作为独立最终防线。
+
 ## 已移除的顺序工作流
 
 历史 Level 1 顺序 command surface 已从公开工作流移除。新工作不要用 `loop-agent run analyze|plan|spec|implement|verify|retrospective|auto|loop|continue|study`。
@@ -147,13 +222,12 @@ loop-agent run-dag --dag <temp-dir>/<task-id>-dag.json --cwd .
 
 ## Outer Loop Runtime
 
-`loop` 命令是长跑任务控制层，与会话治理协议不是一回事。它记录 rounds 与 signals，可跑 shell 验证、Pi review、Cursor 修复或 DAG action，并选择下一自动 action。
+`loop` 命令是长跑任务控制层，与会话治理协议不是一回事。它记录 rounds 与 signals，可跑 shell 验证、Pi review 或 DAG action（review/execute），并选择下一自动 action。自动写入只能通过受治理 Pi-only Agent DAG execute；`loopAutoExecutionPolicy` 控制是否允许自动执行，旧 `loopAutoWritePolicy` 会 fail-fast。
 
 支持的 loop actions：
 
 - `shell-verify`
 - `pi-review`
-- `cursor-fix`
 - `dag`
 - `record-round`
 - `add-signal`

package/docs/harness-methodology-debugging.md

@@ -88,7 +88,7 @@ NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
 
 ### Phase 4：实现
 
-1. **创建失败测试用例** — 遵循 RED-GREEN-REFACTOR（见 `docs/harness-methodology-tdd.md`）
+1. **创建失败测试用例** — 遵循 RED-GREEN-REFACTOR（见 `harness-methodology-tdd.md`）
 2. **实现单一修复** — 解决已识别的根因，一次一个改动，不顺手重构
 3. **验证修复** — 测试通过？其他测试没坏？问题真的解决了？
 4. **如果修复无效**：

package/docs/harness-methodology-tdd.md

@@ -125,6 +125,6 @@ npm test path/to/test.test.ts
 
 ## 参考
 
-- Harness 工作流：`docs/feature-workflow.md`
-- 验证矩阵：`docs/verification-matrix.md`
-- Sprint Contract 模板：`docs/templates/sprint-contract.md`
+- Harness 工作流：`feature-workflow.md`
+- 验证矩阵：`verification-matrix.md`
+- Sprint Contract 模板：`templates/sprint-contract.md`

package/docs/init-surface.manifest.json

@@ -10,10 +10,20 @@
     "docs/README.md",
     "docs/init-surface.manifest.json",
     "docs/architecture/runtime-boundaries.md",
+    "docs/architecture/README.md",
+    "docs/architecture/system-overview.md",
+    "docs/architecture/dag-execution.md",
+    "docs/architecture/worker-and-feature.md",
+    "docs/architecture/facts-and-state.md",
+    "docs/architecture/evolution.md",
     "docs/skills/README.md",
     "docs/skills/vetted-skill-registry.md",
     "docs/templates/init-evolution-review.md",
+    "docs/templates/exec-plan.md",
     "docs/templates/production-readiness-checklist.md",
+    "docs/templates/frontend-task-requirement.md",
+    "docs/templates/frontend-task-constraints.md",
+    "docs/templates/frontend-design-contract.md",
     "docs/templates/worker-dogfood-setup.md",
     "docs/templates/worker-dogfood-evidence.md",
     "docs/templates/harness.schema.json",
@@ -32,8 +42,11 @@
     "scripts/check-task-pool-root.sh",
     "docs/templates/agent-dag.schema.json",
     "examples/example-dag.json",
+    "skills/agent-worker/SKILL.md",
+    "skills/agent-worker/references/agent-worker-operator.md",
     "skills/loop-agent/SKILL.md",
     "skills/loop-agent/references/command-reference.md",
+    "skills/loop-agent/references/docs-converge.md",
     "skills/ai-engineering-context/SKILL.md",
     "skills/verification-before-completion/SKILL.md",
     "skills/systematic-debugging/SKILL.md",
@@ -42,7 +55,17 @@
     "skills/test-driven-development/SKILL.md",
     "skills/code-review-core/SKILL.md",
     "skills/init-capability-evolution/SKILL.md",
-    "skills/webapp-testing/SKILL.md"
+    "skills/webapp-testing/SKILL.md",
+    "skills/frontend-implementation/SKILL.md",
+    "skills/frontend-implementation/references/node-contracts.md",
+    "skills/frontend-implementation/references/design-spec.md",
+    "skills/frontend-implementation/references/code-standards.md",
+    "skills/frontend-design-review/SKILL.md",
+    "skills/frontend-design-review/references/review-checklist.md",
+    "skills/frontend-review/SKILL.md",
+    "skills/frontend-review/references/review-findings.md",
+    "skills/frontend-verification/SKILL.md",
+    "skills/frontend-verification/references/verification-checklist.md"
   ],
   "initFullRequired": [
     "README.md",
@@ -56,6 +79,9 @@
     "docs/loop-agent-harness.md",
     "docs/templates/init-evolution-review.md",
     "docs/templates/production-readiness-checklist.md",
+    "docs/templates/frontend-task-requirement.md",
+    "docs/templates/frontend-task-constraints.md",
+    "docs/templates/frontend-design-contract.md",
     "docs/templates/worker-dogfood-setup.md",
     "docs/templates/worker-dogfood-evidence.md",
     "docs/templates/harness.schema.json",
@@ -70,6 +96,7 @@
     "docs/templates/product-line/task.yaml",
     "docs/templates/product-line/closeout.yaml",
     "docs/templates/product-line/links.md",
+    "scripts/check-skill-entry.sh",
     "scripts/check-product-line-docs.sh",
     "scripts/check-repo.sh",
     "scripts/ci-governance.sh",
@@ -78,19 +105,11 @@
     ".harness/prompts/analyze.md",
     ".harness/tasks",
     ".harness/dag-runs/active",
-    "skills/loop-agent/SKILL.md",
-    "skills/loop-agent/references/command-reference.md",
-    "skills/ai-engineering-context/SKILL.md",
-    "skills/verification-before-completion/SKILL.md",
-    "skills/systematic-debugging/SKILL.md",
-    "skills/requesting-code-review/SKILL.md",
-    "skills/codebase-scout/SKILL.md",
-    "skills/test-driven-development/SKILL.md",
-    "skills/code-review-core/SKILL.md",
-    "skills/init-capability-evolution/SKILL.md",
-    "skills/webapp-testing/SKILL.md",
+    ".agents/skills/agent-worker/SKILL.md",
+    ".agents/skills/agent-worker/references/agent-worker-operator.md",
     ".agents/skills/loop-agent/SKILL.md",
     ".agents/skills/loop-agent/references/command-reference.md",
+    ".agents/skills/loop-agent/references/docs-converge.md",
     ".agents/skills/ai-engineering-context/SKILL.md",
     ".agents/skills/verification-before-completion/SKILL.md",
     ".agents/skills/systematic-debugging/SKILL.md",
@@ -99,7 +118,17 @@
     ".agents/skills/test-driven-development/SKILL.md",
     ".agents/skills/code-review-core/SKILL.md",
     ".agents/skills/init-capability-evolution/SKILL.md",
-    ".agents/skills/webapp-testing/SKILL.md"
+    ".agents/skills/webapp-testing/SKILL.md",
+    ".agents/skills/frontend-implementation/SKILL.md",
+    ".agents/skills/frontend-implementation/references/node-contracts.md",
+    ".agents/skills/frontend-implementation/references/design-spec.md",
+    ".agents/skills/frontend-implementation/references/code-standards.md",
+    ".agents/skills/frontend-design-review/SKILL.md",
+    ".agents/skills/frontend-design-review/references/review-checklist.md",
+    ".agents/skills/frontend-review/SKILL.md",
+    ".agents/skills/frontend-review/references/review-findings.md",
+    ".agents/skills/frontend-verification/SKILL.md",
+    ".agents/skills/frontend-verification/references/verification-checklist.md"
   ],
   "initSurface": {
     "README.md": "managed-block",
@@ -113,6 +142,9 @@
     "docs/loop-agent-harness.md": "generated",
     "docs/templates/init-evolution-review.md": "copied",
     "docs/templates/production-readiness-checklist.md": "copied",
+    "docs/templates/frontend-task-requirement.md": "copied",
+    "docs/templates/frontend-task-constraints.md": "copied",
+    "docs/templates/frontend-design-contract.md": "copied",
     "docs/templates/worker-dogfood-setup.md": "copied",
     "docs/templates/worker-dogfood-evidence.md": "copied",
     "docs/templates/harness.schema.json": "copied",
@@ -127,6 +159,7 @@
     "docs/templates/product-line/task.yaml": "copied",
     "docs/templates/product-line/closeout.yaml": "copied",
     "docs/templates/product-line/links.md": "copied",
+    "scripts/check-skill-entry.sh": "generated",
     "scripts/check-product-line-docs.sh": "copied",
     "scripts/check-repo.sh": "generated",
     "scripts/ci-governance.sh": "generated",
@@ -136,19 +169,11 @@
     ".harness/tasks": "directory",
     ".harness/dag-runs/active": "directory",
     ".harness/init-surface.json": "state",
-    "skills/loop-agent/SKILL.md": "copied",
-    "skills/loop-agent/references/command-reference.md": "copied",
-    "skills/ai-engineering-context/SKILL.md": "copied",
-    "skills/verification-before-completion/SKILL.md": "copied",
-    "skills/systematic-debugging/SKILL.md": "copied",
-    "skills/requesting-code-review/SKILL.md": "copied",
-    "skills/codebase-scout/SKILL.md": "copied",
-    "skills/test-driven-development/SKILL.md": "copied",
-    "skills/code-review-core/SKILL.md": "copied",
-    "skills/init-capability-evolution/SKILL.md": "copied",
-    "skills/webapp-testing/SKILL.md": "copied",
+    ".agents/skills/agent-worker/SKILL.md": "copied",
+    ".agents/skills/agent-worker/references/agent-worker-operator.md": "copied",
     ".agents/skills/loop-agent/SKILL.md": "copied",
     ".agents/skills/loop-agent/references/command-reference.md": "copied",
+    ".agents/skills/loop-agent/references/docs-converge.md": "copied",
     ".agents/skills/ai-engineering-context/SKILL.md": "copied",
     ".agents/skills/verification-before-completion/SKILL.md": "copied",
     ".agents/skills/systematic-debugging/SKILL.md": "copied",
@@ -157,7 +182,17 @@
     ".agents/skills/test-driven-development/SKILL.md": "copied",
     ".agents/skills/code-review-core/SKILL.md": "copied",
     ".agents/skills/init-capability-evolution/SKILL.md": "copied",
-    ".agents/skills/webapp-testing/SKILL.md": "copied"
+    ".agents/skills/webapp-testing/SKILL.md": "copied",
+    ".agents/skills/frontend-implementation/SKILL.md": "copied",
+    ".agents/skills/frontend-implementation/references/node-contracts.md": "copied",
+    ".agents/skills/frontend-implementation/references/design-spec.md": "copied",
+    ".agents/skills/frontend-implementation/references/code-standards.md": "copied",
+    ".agents/skills/frontend-design-review/SKILL.md": "copied",
+    ".agents/skills/frontend-design-review/references/review-checklist.md": "copied",
+    ".agents/skills/frontend-review/SKILL.md": "copied",
+    ".agents/skills/frontend-review/references/review-findings.md": "copied",
+    ".agents/skills/frontend-verification/SKILL.md": "copied",
+    ".agents/skills/frontend-verification/references/verification-checklist.md": "copied"
   },
   "packageExcluded": [
     "docs/progress/20*.md",

package/docs/loop-agent-harness.md

@@ -10,20 +10,26 @@ loop-agent 提供结构化 agent 工作的本地 harness。
 - `.harness/cache/` — 本地 runtime 缓存
 - `.harness/live/` — 瞬态 live-session 文件
 - `.harness/task-pool/` — `agent-worker` 的 Task Pool state、batch artifacts、failure handoffs 与 Observe events；它是 `.harness/` 内的独立 Worker runtime root，默认不提交
+- `.harness/dag-runs/<lifecycle>/<run-id>/.runtime/skill-snapshot.json` — 该 run 实际使用的 resolved skill profile snapshot；由 state 中相对 ref 与原始 bytes SHA-256 锚定，随 lifecycle 目录整体迁移
 
 ## Skill 指令
 
 - `skills/loop-agent/` — loop-agent 仓库自有的 skill 指令与参考资料
-- `skills/<skill-name>/` — DAG 模板引用的 skill 本地副本，含 supervised implementation 角色
+- `skills/agent-worker/` — Feature Packet、TaskSpec、Task Pool、controller pinning、自举 candidate canary 与 Worker recovery 的可选 outer-loop operator skill；不是 DAG node skill
+- `.agents/skills/<skill-name>/` — 目标项目 repo-local skill 副本；`skills/<skill-name>/` 仍是 loop-agent 源仓库和 npm 包内置回退路径
 - 历史 `skill/` 不再是必需仓库路径；runtime 查找仅为 `loop-agent` 保留兼容 fallback
 
+目标项目若在 `.agents/skills/` 中提供 `SDD-requirement-analysis`、`SDD-design-analysis`、`SDD-implementation-test-review`，hybrid DAG 生成器会按节点追加对应 skill。该增强只复用 repo-local 知识与方法：loop-agent 仍拥有流程与状态控制权，embedded-mode 约束禁止 SDD 状态推进、确认门禁和归档；初始化/扫描类 SDD skill 不会自动执行。未命中时不会改变默认 DAG。命中的节点 skill 继续由同一 resolved instruction 和 run-owned snapshot 机制冻结，没有第二套 loader 或旁路。
+
 ## Package 资产
 
-npm 包包含运行与说明 harness 所需的静态能力资产：`bin/`、`dist/`、`skills/`、顶层 `docs/*.md`、`docs/templates/`、`examples/`、`harness.json`、`AGENTS.md`、`README.md`、`CHANGELOG.md`。
+npm 包包含运行与说明 harness 所需的静态能力资产：`bin/`、`dist/`、`skills/`（包括 `loop-agent` 与 `agent-worker`）、顶层 `docs/*.md`、`docs/templates/`、`examples/`、`harness.json`、`AGENTS.md`、`README.md`、`CHANGELOG.md`。
 
 生成或历史的 task facts 不是 package 资产。`docs/progress/`、`docs/reports/`、`docs/exec-plans/`、`docs/decisions/` 下现有文件属于目标仓库历史；包只携带这些目录的 README。
 
-从 npm 安装 `loop-agent` 并在其他项目使用时，DAG skill 指令按配置、用户或目标本地 skill 目录解析（若存在），再回退到包内 `skills/`。目标项目可添加本地 skills，但不必复制 loop-agent 源码历史或 `skills/` 目录即可使用默认 DAG 工作流。
+从 npm 安装 `loop-agent` 并在其他项目使用时，DAG skill 指令按配置、用户或目标项目 `.agents/skills/` 解析（若存在），再回退到包内 `skills/`。目标项目可添加本地 skills，但不必复制 loop-agent 源码历史或根 `skills/` 目录即可使用默认 DAG 工作流。
+
+`scripts/self-host-canary.mjs` 是源码仓库维护脚本，不进入 npm package `files`；安装后的 package 不把它作为用户命令 surface。
 
 ## harness.json Schema
 
@@ -54,16 +60,21 @@ DAG 节点的模型由 `executorModels[executor][complexity]` 路由。新 run
 
 DAG agent 节点的输出语言由 `harness.json.workflowPolicy.dag.outputLanguage` 控制，支持 `zh-CN` 和 `en`。未配置时默认 `zh-CN`；`dag run-task` 会把配置写入生成的 DagSpec，手写 DagSpec 缺少该字段时 prompt envelope 同样默认中文。语言规则只约束说明、分析、报告、总结和文档正文，不翻译代码、命令、路径、标识符、JSON 字段、VERDICT 行及其他精确协议字面量。
 
+新 DAG run（包括 dry-run 与 init-only）会在首次 state write 前冻结所有初始 Pi task、dynamic map child template 与 loop body template 的 resolved skill profiles。profile id 包含 ordered skills、learned-pattern mode 和两个 instruction budgets；后续节点只从 snapshot 建 prompt。snapshot/hash/binding/profile 不一致时节点进入 `ERROR` / `skill-snapshot-integrity`，executor 不调用，也不回退实时 skill。旧 run 只有在 ref 与 artifact 都不存在时，才可在 resume 前创建 `legacy-resume-backfill`，且该 mode 只证明剩余节点被固定。
+
 ## Command Surface
 
 - `new-task`、`status`、`inspect`、`doctor`
 - `dag run-task`、`dag validate`、`run-dag`、`dag report`、`dag resume`、`dag reconcile-run`
+- `plan list`、`plan create`、`plan complete`、`plan check`、`docs audit`、`docs archive`
 - `delegate`、`harvest`、`promote-run`、`closeout`
 - `loop init`、`loop run`、`loop status`、`loop closeout`
 - `pi-prompt`、`cursor-prompt`
-- `docs audit`、`handoff check`、`spine audit`、`knowledge curate`
+- `handoff check`、`spine audit`、`knowledge curate`
 - `agent-worker feature review|run|verify-final|delivery|closeout|approve-followup`、`agent-worker task validate|explain-profile|retry|draft-followup`、`agent-worker batch run-ready`、`agent-worker report morning|metrics`、`agent-worker observe serve|snapshot`
 
+`dag run-task` 在生成 DAG 草稿前会运行与 `plan check` 同源的 exec-plan 索引校验；active plan 与 `docs/exec-plans/active/README.md` 索引不一致时立即失败，避免运行昂贵节点后才在末端 shell verify 发现。`plan create` 优先复用目标项目模板并回退到发布包内置 `docs/templates/exec-plan.md`，`plan create`/`plan complete` 的多文件写入均有回滚保护；`new-task` 不自动绑定 exec-plan。
+
 ## Feature Review
 
 `agent-worker feature review --feature-dir <feature-dir> --repo <target-repo>` 是只读的 Feature 级决策入口。它复用 Feature Packet validation、task graph 和 `.harness/task-pool/` 事实，派生 `Draft`、`Ready`、`Running`、`NeedsAction`、`AwaitingQA`、`Deliverable`、`Closed`，同时展示 required AC 覆盖、阻塞、证据和唯一主行动。
@@ -72,6 +83,8 @@ DAG agent 节点的输出语言由 `harness.json.workflowPolicy.dag.outputLangua
 
 `agent-worker feature run --feature-dir <feature-dir> --repo <target-repo>` 是薄编排入口：先执行 Feature validation 和一次目标仓库 preflight，再复用 `runReadyTasks()` 推进 Ready Task，最后刷新 morning report、`.harness/task-pool/observability/snapshot.json` 与 Feature review。`--dry-run` 只读取 Packet/Task Pool 并列出 Ready IDs、步骤和预期产物。默认无 Git 授权时单次最多执行一个 Ready 写任务；checkpoint 模式可按 `--limit` 串行推进，并在每个 Task 后建立 clean boundary。
 
+写入型 Worker 命令可传 `--expected-controller-version` 与 `--expected-controller-fingerprint`。`LoopAgentClient` 先把请求的 bin/PATH/npm shim 解析成冻结的绝对 launch spec，再校验 package name/version、binary SHA-256 和 portable package fingerprint；expected gate 在 materialize、Task Pool `Running` 或目标仓库写入前完成。预检后的命令使用该 launch spec，不会因 PATH、symlink 或安装内容变化而静默切换 controller。
+
 `agent-worker feature verify-final` 在 clean Delivery HEAD 上以已完成的 `qa-execute` TaskSpec 运行独立最终 DAG，跳过 promotion/task closeout，避免 repo write 或 HEAD 移动，并原子生成 canonical QA aggregate 与 HEAD-bound final verification。`agent-worker feature delivery` 从同一 Git transaction 和 Task Pool facts 生成带 hash 的 manifest、Acceptance Coverage 与稳定 `PR.md`，拒绝 dirty/wrong branch、历史或 trailer 漂移、缺失 run/QA/final verification 和 required AC 缺口。`agent-worker feature closeout` 默认只读预览 gates；显式 `--apply --owner` 才原子写回 Closeout，并在 stale facts、写入或 post-validation 失败时恢复原状态。
 
 Morning report 顶部和 Observe 首页直接消费共享 Feature read model，固定从 Status、Next Action、Why、Evidence 开始。`agent-worker report metrics --month YYYY-MM` 写入 `.harness/task-pool/artifacts/metrics/monthly-YYYY-MM.json|md`，每项指标保留分母、样本量、窗口和 missingData。
@@ -80,6 +93,17 @@ Morning report 顶部和 Observe 首页直接消费共享 Feature read model，
 
 业务 Task 失败不会跳过报告与最终 review，但命令返回 `needs-action` 和非零退出码；`noReadyReason` 用于区分 Closed、Deliverable、AwaitingQA、NeedsAction、dependency blocked 与 empty。
 
+## Versioned Self-hosting Canary
+
+源码仓库使用下面的 repo-maintainer 命令验证隔离 candidate package 的确定性接棒：
+
+```bash
+npm run self-host:canary -- --deterministic --output <evidence.json>
+npm run self-host:canary -- --deterministic --tarball <candidate.tgz> --output <evidence.json>
+```
+
+canary 会记录 tarball SHA-256、slot containment、两个 bin identity、由维护脚本独立计算并与候选实现交叉核对的 package fingerprint、每个 required check、skill mirror hashes、Feature dry-run、static/shell DAG run/report 以及 PATH trap。所有子进程都有硬超时；它删除 `HARNESS_ALLOW_ACTIVE_DAG_RUNS`，并要求 trap 中没有 `loop-agent`、`agent-worker` 或 `pi` 调用。`--live` 当前明确失败；deterministic canary 不包含 Pi/model/provider/cost 证明。
+
 ## Follow-up 决策与批准
 
 `agent-worker task draft-followup <task-id> --worker-run-id <id> --feature-dir <feature-dir> --repo <target-repo>` 从失败 run、TaskSpec 和 task graph 生成 `FU-<parent>-NN` 决策产物。ProductBug/TestBug/FlakyTest/DependencyFailure 生成可批准 TaskDraft；连续两次 EnvFailure 生成 `ENV-CHECK-*`，单次只建议 retry；SpecUnclear/ContractMismatch/RiskyChange/NeedsHuman/Unknown 生成人工行动卡。产物与 evidence/index 位于 `.harness/task-pool/artifacts/features/<feature-id>/follow-ups/`；生成过程受 Feature lock 和 dedupe key 保护，不写 Feature Packet、Ready state 或原失败事实。新 run 会 supersede 同 parent 的旧 unresolved 产物，但不会删除历史。