@tea-agent/loop-agent 0.12.0 → 0.13.0-beta.0

package/docs/feature-workflow.md

@@ -1,261 +1,389 @@
-# 功能工作流
-
-本文档区分两层：
-
-- **Session governance**：监督方（人/agent）如何组织一次工作会话
-- **Runtime workflows**：`src/workflows/` 下代码实际执行的内容
-
-## 默认会话协议
-
-1. **Orient**：读 `README.md`、`harness.json` 与本 docs 索引
-2. **Select**：选一个有限边界的工作块
-3. **Contract**：写明交付物、非目标、完成标准、验证命令、失败条件
-4. **Implement**：做最小连贯变更，同步更新必要文档、脚本与测试
-5. **Verify**：按 `verification-matrix.md` 跑命令；完成声明用新鲜输出
-6. **Handoff**：在 `docs/progress/`、`docs/reports/`、exec plan 或 ADR 中记录证据
-
-## Orient
-
-先理解当前系统，不要默认「没有」：
-
-- 读 `harness.json` 列出的仓库入口
-- 查 `git status --short --branch` 与最近提交
-- 新增结构前搜索现有源码、测试、脚本、文档与模板
-- 任务依赖健康基线时跑最小基线检查
-- 涉及 TDD、完成声明或调试时读方法论文档
-
-基线已坏时，记录失败命令，并决定当前块是修基线还是在明确范围内接受已知失败。
-
-## Select
-
-工作块要窄到可验证。避免无关重构、功能与文档迁移混在一起。
-
-选中的块应有：
-
-- 单一用户可见或维护者可见结果
-- 委托写工作时显式 allowed paths
-- 已知非目标
-- 能证明结果的验证命令
-
-## Contract
-
-非平凡工作应在实现前写或更新 execution plan、sprint contract、progress log 或 issue 级笔记。Contract 应包含：
-
-- 交付物
-- 非目标
-- 验收标准
-- 验证命令
-- 失败条件
-- 预期更新的 artifacts
-
-Bug 修复的 contract 应含复现路径，以及证明修复的回归测试或 smoke check。
-
-## Implement
-
-做满足 contract 的最小连贯变更。
-
-- 优先现有 helper 与目录边界
-- 行为变更更新测试
-- 工作流或命令变更更新文档与示例
-- 治理变更更新 `harness.json`、检查脚本或模板
-- 不把占位实现当作已完成
-- 重复约束出现时固化为持久产物
-
-## Verify
-
-验证是完成权威。
-
-- 用 `docs/verification-matrix.md` 选最窄的证明命令
-- 完整重跑命令
-- 读 exit code 与输出
-- 修失败或报告确切失败状态
-- 不用陈旧输出或部分检查声明完成
-
-## Agent DAG First
-
-复杂实现优先 DAG 工作流：
-
-```bash
-loop-agent new-task <task-id> "Task title"
-loop-agent dag run-task <task-id> --profile auto --strict-models --output <temp-dir>/<task-id>-dag.json
-loop-agent dag validate --dag <temp-dir>/<task-id>-dag.json --strict-models --strict-governance
-loop-agent run-dag --dag <temp-dir>/<task-id>-dag.json --cwd .
-```
-
-`<temp-dir>` 为平台原生临时目录。macOS/Windows 上实际文件操作用原生路径；`/` 仅用于稳定 repo 引用、JSON/Markdown 证据引用和 glob 约定。
-
-这不是线性 OS-CIVH runtime 状态机。代码里 DAG 有三个命令阶段：
-
-1. `dag run-task` 加载 `.harness/tasks/<task-id>/source/需求.md`、可选 `执行约束.md`、`task.json` 与 adapter 验证命令，写出 DAG spec
-2. `dag validate` 校验 schema、依赖、governance profile、写边界、model routing、shell 验证元数据
-3. `run-dag` 加载 DAG、按拓扑排序为 ranks、有界并发执行可运行节点、持久化到 `.harness/dag-runs/<lifecycle>/<run-id>/`，并转入 `completed` 或 `paused`
-
-标准生成的 hybrid DAG 固定为 Pi-only writer：
-
-```text
-contract-pi
-  -> scout-src + scout-tests
-  -> plan-pi
-  -> implement-pi
-  -> verify-shell
-  -> verify-pi
-  -> closeout-pi
-```
-
-`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 模板继续插入：
-
-```text
-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 仍负责：
-
-- 写 contract
-- 限定 allowed/forbidden paths
-- 审查 DAG/writeSet 范围
-- 选择验证命令
-- 记录 handoff 证据
-
-声称 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`。
-
-改用 DAG 路径：
-
-```bash
-loop-agent new-task <task-id> "Task title"
-loop-agent dag run-task <task-id> --profile auto --strict-models --output <temp-dir>/<task-id>-dag.json
-loop-agent dag validate --dag <temp-dir>/<task-id>-dag.json --strict-models --strict-governance
-loop-agent run-dag --dag <temp-dir>/<task-id>-dag.json --cwd .
-```
-
-遗留 `.harness/tasks/<task-id>/.workflow_state.json` 在 task status 完全迁移到 DAG 导向读模型前仍可读，但不是新任务完成的权威。
-
-## Outer Loop Runtime
-
-`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`
-- `dag`
-- `record-round`
-- `add-signal`
-- `closeout`
-
-源码参考：
-
-- `src/commands/loop.ts`
-- `src/workflows/loop/actions.ts`
-- `src/workflows/loop/state.ts`
-- `src/workflows/loop/rounds.ts`
-
-## 调试与 TDD
-
-任务需要时使用方法论文档：
-
-- 行为变更与 bug 修复：`docs/harness-methodology-tdd.md`
-- 完成或 handoff 声明：`docs/harness-methodology-verification.md`
-- 失败与意外行为：`docs/harness-methodology-debugging.md`
-
-## Handoff
-
-Handoff 应说明：
-
-- 改了什么
-- 有意未做什么
-- 跑了哪些验证命令
-- 是否影响契约、文档、测试或脚本
-- 剩余风险或后续工作
-
-较大工作应更新 `docs/progress/`、`docs/reports/`、active exec plan 或 `docs/decisions/`，以便下一会话不依赖聊天历史。
+# 功能工作流
+
+本文档区分两层：
+
+- **Session governance**：监督方（人/agent）如何组织一次工作会话
+- **Runtime workflows**：`src/workflows/` 下代码实际执行的内容
+
+## 默认会话协议
+
+1. **Orient**：读 `README.md`、`harness.json` 与本 docs 索引
+2. **Select**：选一个有限边界的工作块
+3. **Contract**：写明交付物、非目标、完成标准、验证命令、失败条件
+4. **Implement**：做最小连贯变更，同步更新必要文档、脚本与测试
+5. **Verify**：按 `verification-matrix.md` 跑命令；完成声明用新鲜输出
+6. **Handoff**：在 `docs/progress/`、`docs/reports/`、exec plan 或 ADR 中记录证据
+
+## Orient
+
+先理解当前系统，不要默认「没有」：
+
+- 读 `harness.json` 列出的仓库入口
+- 查 `git status --short --branch` 与最近提交
+- 新增结构前搜索现有源码、测试、脚本、文档与模板
+- 任务依赖健康基线时跑最小基线检查
+- 涉及 TDD、完成声明或调试时读方法论文档
+
+基线已坏时，记录失败命令，并决定当前块是修基线还是在明确范围内接受已知失败。
+
+## Select
+
+工作块要窄到可验证。避免无关重构、功能与文档迁移混在一起。
+
+选中的块应有：
+
+- 单一用户可见或维护者可见结果
+- 委托写工作时显式 allowed paths
+- 已知非目标
+- 能证明结果的验证命令
+
+## Contract
+
+非平凡工作应在实现前写或更新 execution plan、sprint contract、progress log 或 issue 级笔记。Contract 应包含：
+
+- 交付物
+- 非目标
+- 验收标准
+- 验证命令
+- 失败条件
+- 预期更新的 artifacts
+
+Bug 修复的 contract 应含复现路径，以及证明修复的回归测试或 smoke check。
+
+## Implement
+
+做满足 contract 的最小连贯变更。
+
+- 优先现有 helper 与目录边界
+- 行为变更更新测试
+- 工作流或命令变更更新文档与示例
+- 治理变更更新 `harness.json`、检查脚本或模板
+- 不把占位实现当作已完成
+- 重复约束出现时固化为持久产物
+
+## Verify
+
+验证是完成权威。
+
+- 用 `docs/verification-matrix.md` 选最窄的证明命令
+- 完整重跑命令
+- 读 exit code 与输出
+- 修失败或报告确切失败状态
+- 不用陈旧输出或部分检查声明完成
+
+## Agent DAG First
+
+复杂实现优先 DAG 工作流：
+
+```bash
+loop-agent new-task <task-id> "Task title"
+loop-agent dag run-task <task-id> --profile auto --strict-models --output <temp-dir>/<task-id>-dag.json
+loop-agent dag validate --dag <temp-dir>/<task-id>-dag.json --strict-models --strict-governance
+loop-agent run-dag --dag <temp-dir>/<task-id>-dag.json --cwd .
+```
+
+`<temp-dir>` 为平台原生临时目录。macOS/Windows 上实际文件操作用原生路径；`/` 仅用于稳定 repo 引用、JSON/Markdown 证据引用和 glob 约定。
+
+## 业务模板（taskKind）与治理 Profile
+
+这两层要分开：
+
+| 层 | 入口 | 作用 | 合法取值 |
+|----|------|------|----------|
+| 业务模板 | `task.json.taskKind` | 选专用 DAG 节点链 | `standard` / `frontend-implementation` / `frontend-test` / `backend-test` / `knowledge-sync` / `knowledge-graph-bootstrap` 等 |
+| 治理 profile | `dag run-task --profile` | 风险与流程强度 | **仅** `auto` / `minimal` / `standard` / `reviewed` / `supervised` |
+
+专用业务流水线**不要**写成 `--profile frontend-test` / `--profile backend-test` / `--profile knowledge-sync` / `--profile knowledge-graph-bootstrap`：CLI 会拒绝这些值。正确做法是写 `task.json.taskKind`（`knowledge-sync` 还须 `featureId`）。
+
+| 用户描述关键词 | 正确入口 | 模板 |
+|--------------|----------|------|
+| 后端测试、接口测试、pytest 自动化 | `taskKind: "backend-test"` | backend-test-dag |
+| 前端功能测试、浏览器测试、Playwright CLI | `taskKind: "frontend-test"` | frontend-test-dag |
+| 前端实现、UI/组件开发 | `taskKind: "frontend-implementation"`（或 standard 下高置信自动分类） | frontend-implementation |
+| 测试知识回写 / 知识同步 | `taskKind: "knowledge-sync"` + `featureId` | knowledge-sync-dag |
+| 业务知识图谱开荒 / 增量 | `taskKind: "knowledge-graph-bootstrap"` | knowledge-graph-bootstrap-dag |
+| 普通实现、修复、功能 | `taskKind: "standard"` + `--profile auto`（默认） | 由 governance / 任务源分类推断 |
+
+**后端测试示例：**
+
+```bash
+loop-agent new-task <task-id> "后端测试任务"
+# 将需求文档放入 .harness/tasks/<task-id>/source/需求.md
+# 将参考文档放入 .harness/tasks/<task-id>/source/references/
+# 在 .harness/tasks/<task-id>/task.json 设置：
+#   { "taskKind": "backend-test", ... }
+loop-agent dag run-task <task-id> --execute --cwd .
+# 需要收紧治理时再叠加合法 profile，例如：
+# loop-agent dag run-task <task-id> --profile supervised --execute --cwd .
+```
+
+这不是线性 OS-CIVH runtime 状态机。代码里 DAG 有三个命令阶段：
+
+1. `dag run-task` 加载 `.harness/tasks/<task-id>/source/需求.md`、可选 `执行约束.md`、`task.json` 与 adapter 验证命令，写出 DAG spec
+2. `dag validate` 校验 schema、依赖、governance profile、写边界、model routing、shell 验证元数据
+3. `run-dag` 加载 DAG、按拓扑排序为 ranks、有界并发执行可运行节点、持久化到 `.harness/dag-runs/<lifecycle>/<run-id>/`，并转入 `completed` 或 `paused`
+
+标准生成的 hybrid DAG 固定为 Pi-only writer：
+
+```text
+contract-pi
+  -> scout-src + scout-tests
+  -> plan-pi
+  -> implement-pi
+  -> verify-shell
+  -> verify-pi
+  -> closeout-pi
+```
+
+`implement-pi` / `repair-pi` 使用 `executor: "pi"` 与 `toolProfile: "write"`。受治理 runtime 不再生成或接受 `implement-cursor` / `repair-cursor`；旧 Cursor DAG 会在 schema 校验阶段失败，需要重新生成。
+
+专用模板选择与 governance profile 是两层独立路由。显式声明的专用 `taskKind` 始终优先；对于默认 `standard` 任务，生成器会根据任务标题、`source/需求.md` 和结构化 `allowedPaths` 做保守、确定性的需求分类。只有高置信的前端实现需求才自动选择 `frontend-implementation` 模板；由显式 profile、`workflowPolicy` 或 supervised quality gate 选中的 supervised 模板不会被自动分类降级。后端、前后端混合、明确排除前端或无法可靠判断的需求继续使用 governance profile 选出的通用模板，绝不会自动进入 `backend-test-dag`。已有 `taskKind: "frontend-implementation"` 继续作为兼容入口和有意覆盖：
+
+```text
+frontend-contract-pi
+  -> frontend-scout-pi
+  -> frontend-mock-assess-pi
+  -> frontend-mock-contract-gate-shell
+  -> frontend-plan-pi
+  -> frontend-design-gate-pi
+  -> frontend-first-design-gate-shell
+  -> frontend-plan-revision-pi
+  -> [frontend-requirement-coverage-shell]
+  -> frontend-final-design-review-pi
+  -> frontend-final-design-gate-shell
+  -> frontend-implement-pi
+  -> [frontend-mock-verify-shell]
+  -> frontend-static-verify-shell
+  -> frontend-behavior-verify-shell
+  -> frontend-review-pi
+  -> frontend-review-gate-shell
+  -> frontend-closeout-pi
+```
+
+`frontend-mock-assess-pi` 是 contract/scout 之后、plan 之前的只读策略节点。它先确认接口契约与后端就绪度，再按项目能力选择已有原生 Mock、浏览器拦截、请求适配层或 `not-needed`。static/behavior shell 命令在 DAG 生成时已固化，策略只能选择能由这些入口验证的方案；缺少契约、无法保证生产默认关闭、所选策略没有可执行验证或只能靠注释真实请求时输出 `MOCK_STRATEGY: blocked`。`not-needed` 仍需真实或无远程接口的行为证据。Mock 代码由唯一 writer `frontend-implement-pi` 按已批准计划实现，不增加第二个 writer。
+
+前端链在计划前显示 Mock/API/schema 读取、生成期能力 seed、五态策略和 contract gate。可在 `task.json.frontendMock` 设置 `policy: auto|required|disabled`、安全的 `serviceRoot` 和生成时固化的专项 `verifyCommands`。已有原生服务时优先复用；没有原生能力时可使用现有浏览器拦截或可逆 request adapter。不安全或不完整的显式 required 合同只生成无 writer 的评估 DAG；有可信专项命令时实现后先运行 `frontend-mock-verify-shell`，再进入静态和行为验证。规范读取证据继续显示在 Observe 节点详情中。
+
+新生成 DAG 还会冻结 `sourceBinding`（任务源路径、SHA-256 与显式 `REQ/BR/AC` 编号）。前端任务存在显式编号时，`frontend-requirement-coverage-shell` 只检查 `frontend-plan-revision-pi` 输出的当前生效计划证据，缺少任一编号就阻断最终 design review 和 writer；即使首轮 design review 直接通过，revision 节点也必须复述完整 Requirement Coverage，避免从已被取代的原计划借用编号。DAG 中断后应修复 task source 并重新生成完整 DAG；不要用聊天摘要拼接 impl-only 后半段。严格治理会拒绝没有 `sourceBinding`、也没有只读 planner 上游的 v3 孤立 writer。
+
+这条链在实现前加入两阶段 design gate：首轮 design review 同时接受 `VERDICT: pass` 和 `VERDICT: request-revision`，request-revision 时由只读 `frontend-plan-revision-pi` 消费原计划与 design findings 完成修订，再经 `frontend-final-design-review-pi` 和 `frontend-final-design-gate-shell` 最终门禁；只有最终 `VERDICT: pass` 才授权写入。`MOCK_STRATEGY: blocked`、真实请求被注释、生产默认启用 Mock 或 Mock 与接口契约不一致都不得通过。design gate 失败路由为 `ContractMismatch` / `frontend-plan-revision-and-rerun`，不路由为 `ProductBug` / `dev-fix`。
+
+这条链还将前端静态验证与行为验证分开建模；Mock-backed 行为验证只证明页面状态和交互，不证明真实后端已就绪或接口已联通。后端未被实际调用时，closeout 必须写明 `Frontend status: mock-validated`、`Real integration: pending`，并列出 `<task-id>-real-api-integration-verify`。该 follow-up 不会自动创建或运行；后端就绪后需要显式创建/执行新的复验任务。当前 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
+```
+
+这条链覆盖后端功能测试从需求分析到复盘评级的全链路流程：
+
+- `analyze-inputs-pi`：只读输出严格的 Backend Test Analysis v1 JSON；`backend-test-analysis-contract-shell` 确定性校验 source binding、AC IDs、schema 与敏感值，并把规范化结果写入当前 run 的 `contracts/backend-test-analysis.json`。gate 节点记录 artifact path / SHA-256 / schema ID，随 lifecycle 目录整体迁移；非法或来源不一致时 fail-closed，后续 case/pytest writers 不执行。
+- `generate-backend-functional-cases-pi`：只消费已验证 analysis artifact，按契约字段生成结构化后端功能测试用例（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；`request-revision` 或其它结果 **fail-closed 即停**，**不会**自动回到 generate 节点修订（本模板不启用 convergence；修好用例或约束后重新 `dag run-task`）
+5. **generate-backend-pytest-pi**：将后端功能用例转化为 pytest 自动化代码；可写 `testcase/**/test_*.py` 与可选 `testcase/**/helpers/**`、`testcase/**/factories/**`，禁止改 conftest/配置与生产代码；数据构造 API 优先，DB 直写仅限已有安全测试库 fixture
+6. **execute-backend-pytest-shell**：执行 `pytest testcase/`；目标工作区保持 `writePolicy: read-only`，内置 `--junitxml` 将报告写入当前 `$HARNESS_DAG_RUN_DIR/reports/backend-test-junit.xml`（不依赖 `pytest-html`），报告随 run 从 active 归档到 completed/paused，禁止改测试源码或生产代码
+7. **test-retrospect-pi**：读取上游审查报告和测试报告，生成复盘报告 + 成熟度评级（A/B/C/D）
+
+最终验证后的知识库回写可通过 `task.json.taskKind = "knowledge-sync"` 选择专用模板（与 `backend-test` 一样走 taskKind 路由，不占用 governance `--profile`）。
+
+**必须绑定 `featureId`**（fail-closed）。解析顺序：`task.json.featureId` → `hardConstraints` 中 `featureId=F-…` → 需求正文中的 `F-YYYY-NNN` → 若 `taskId` 本身是 `F-*`。生成器会把 writeSet 收窄到 `features/<featureId>/…`，validate 只检查该 Feature 下的 draft。
+
+```json
+{
+  "taskKind": "knowledge-sync",
+  "featureId": "F-2026-004"
+}
+```
+
+```text
+knowledge-sync-collect-pi
+  -> knowledge-sync-draft-pi
+  -> knowledge-sync-validate-shell
+  -> knowledge-sync-review-qa-pi
+  -> knowledge-sync-review-domain-pi      # parallel with qa/evidence
+  -> knowledge-sync-review-evidence-pi
+  -> knowledge-sync-multi-review-gate-shell   # all VERDICT: pass
+  -> knowledge-sync-apply-pi
+  -> knowledge-sync-pointer-pi
+```
+
+这条链在 shell 最终验证证据之后，把稳定事实写入 Feature 测试知识库（L1），而不是把 `.harness` 大日志搬进 docs：
+
+1. **knowledge-sync-collect-pi**：只读汇总 final verification / AC / 用例 / 缺陷 / 需求 delta 候选
+2. **knowledge-sync-draft-pi**：写入 `features/<featureId>/testing/sync/pending/knowledge-sync-draft.json`
+3. **knowledge-sync-validate-shell**：校验该路径 draft 的 schema、`featureId` 一致、operations 目标路径、finalVerification 门禁
+4. **多视角审查（并行）**：QA/验收、领域/产品、证据/审计 三个只读 reviewer；聚合门禁要求全部 `VERDICT: pass`
+5. **knowledge-sync-apply-pi**：仅在 `features/<featureId>/testing/**`（及该 Feature 的 `requirement-delta.md`、`docs/test-reports/**`）受控回写
+6. **knowledge-sync-pointer-pi**：写 `features/<featureId>/testing/runs/latest.md` 与 `sync/applied/KS-*.json`
+
+设计说明见 `docs/design/full-chain-test-knowledge-base.md` §11；JSON 示例见 `docs/templates/knowledge-sync-dag.json`。
+
+业务知识图谱**初始化**可通过 `task.json.taskKind = "knowledge-graph-bootstrap"` 选择专用模板。跑前先落 B1 骨架：
+
+```bash
+bash scripts/kb-bootstrap-init-skeleton.sh --root .
+# 编辑 knowledge/bootstrap/scope.yaml 后再 run-task
+```
+
+（需有 `knowledge/bootstrap/scope.yaml` 与 `status.yaml`；脚本幂等，默认不覆盖已有 scope/status，可用 `--force`。）
+
+图谱索引与 Phase A 查询（脚本，非 RAG）：
+
+```bash
+bash scripts/kb-graph-materialize.sh --root .
+bash scripts/kb-query.sh --mode by_feature --feature F-2026-004 --json
+bash scripts/kb-query.sh --mode by_id --id SVC-order --json
+bash scripts/kb-query.sh --mode search --text "预占" --json
+```
+
+**增量更新（非全量开荒）**：缩小 scope 后复用同一 `knowledge-graph-bootstrap` DAG（propose 仅针对 seeds/includes；promote 仍默认不覆盖已有正式文件）：
+
+```bash
+bash scripts/kb-graph-incremental-prepare.sh --root . \
+  --feature F-2026-004 --service order [--reset-staging]
+# 审阅 knowledge/bootstrap/scope.yaml（update_mode: incremental）
+# task.json.taskKind = "knowledge-graph-bootstrap"
+loop-agent dag run-task <id>
+bash scripts/kb-graph-materialize.sh --root .
+```
+
+测试知识日常写回仍用 `knowledge-sync`（`featureId` 必填），与图谱增量入口分离。
+
+```text
+kg-bootstrap-preflight-shell
+  -> kg-bootstrap-inventory-shell
+  -> kg-bootstrap-propose-pi
+  -> kg-bootstrap-validate-shell
+  -> kg-bootstrap-review-structure-pi
+  -> kg-bootstrap-review-evidence-pi      # parallel with structure/safety
+  -> kg-bootstrap-review-safety-pi
+  -> kg-bootstrap-multi-review-gate-shell  # all VERDICT: pass
+  -> kg-bootstrap-promote-shell
+  -> kg-bootstrap-materialize-shell
+```
+
+AI 只写 `knowledge/bootstrap/staging/**`；禁止 self-`asserted`；**结构 / 证据 / 边界安全** 三视角审查全部通过后才 promote（默认不覆盖已有正式文件）；materialize 写 `knowledge/graph/` 索引。设计见 `docs/design/knowledge-graph-ai-bootstrap.md`，示意 JSON 见 `docs/templates/knowledge-graph-bootstrap-dag.json`。
+
+前端测试模板（`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 模板继续插入：
+
+```text
+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 仍负责：
+
+- 写 contract
+- 限定 allowed/forbidden paths
+- 审查 DAG/writeSet 范围
+- 选择验证命令
+- 记录 handoff 证据
+
+声称 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`。
+
+改用 DAG 路径：
+
+```bash
+loop-agent new-task <task-id> "Task title"
+loop-agent dag run-task <task-id> --profile auto --strict-models --output <temp-dir>/<task-id>-dag.json
+loop-agent dag validate --dag <temp-dir>/<task-id>-dag.json --strict-models --strict-governance
+loop-agent run-dag --dag <temp-dir>/<task-id>-dag.json --cwd .
+```
+
+遗留 `.harness/tasks/<task-id>/.workflow_state.json` 在 task status 完全迁移到 DAG 导向读模型前仍可读，但不是新任务完成的权威。
+
+## Outer Loop Runtime
+
+`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`
+- `dag`
+- `record-round`
+- `add-signal`
+- `closeout`
+
+源码参考：
+
+- `src/commands/loop.ts`
+- `src/workflows/loop/actions.ts`
+- `src/workflows/loop/state.ts`
+- `src/workflows/loop/rounds.ts`
+
+## 调试与 TDD
+
+任务需要时使用方法论文档：
+
+- 行为变更与 bug 修复：`docs/harness-methodology-tdd.md`
+- 完成或 handoff 声明：`docs/harness-methodology-verification.md`
+- 失败与意外行为：`docs/harness-methodology-debugging.md`
+
+## Handoff
+
+Handoff 应说明：
+
+- 改了什么
+- 有意未做什么
+- 跑了哪些验证命令
+- 是否影响契约、文档、测试或脚本
+- 剩余风险或后续工作
+
+较大工作应更新 `docs/progress/`、`docs/reports/`、active exec plan 或 `docs/decisions/`，以便下一会话不依赖聊天历史。