@tea-agent/loop-agent 0.13.0 → 0.15.0

package/docs/feature-workflow.md

@@ -1,414 +0,0 @@
-# 功能工作流
-
-本文档区分两层：
-
-- **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**：在 `ai_workspace/loop-agent/progress/`、`ai_workspace/loop-agent/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
-
-验证是完成权威。
-
-- 用 `ai_workspace/loop-agent/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]  # small risk 可裁剪
-  -> [frontend-requirement-coverage-shell]
-  -> frontend-implementation-contract-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-verification-trace-shell
-  -> frontend-failure-assess-shell
-  -> frontend-repair-contract-shell
-  -> frontend-repair-pi
-  -> frontend-static-reverify-shell
-  -> frontend-behavior-reverify-shell
-  -> frontend-verification-retrace-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`。
-
-这条链还将前端静态验证与行为验证分开建模，并在 verify 后增加 verification-trace 与单轮 bounded repair（失败可评估/修复/复验；contract/path/依赖/凭据等不可自动修）。Mock-backed 行为验证只证明页面状态和交互，不证明真实后端已就绪或接口已联通。后端未被实际调用时，closeout 必须写明 `Frontend status: mock-validated`、`Real integration: pending`，并列出 `<task-id>-real-api-integration-verify`。该 follow-up 不会自动创建或运行；后端就绪后需要显式创建/执行新的复验任务。生成期会注入确定性风险分级与 React/Next/Vue 等强证据 capability；a11y 仅在项目已有 lint/axe 类工具时声明 static/component 级证据。当前仍不包含浏览器自动化、视觉回归或 browser-level a11y executor。
-
-后端测试任务只有在显式声明 `task.json.taskKind = "backend-test"` 时才选择专用模板；它面向测试工程，不是普通后端实现模式，也不新增 governance profile：
-
-```text
-analyze-inputs-pi
-  -> backend-test-analysis-contract-shell
-  -> backend-test-environment-scout-pi
-  -> backend-test-execution-contract-shell
-  -> generate-backend-functional-cases-pi
-  -> emit-backend-case-manifest-pi
-  -> backend-test-case-manifest-shell
-  -> review-backend-cases-pi
-  -> review-backend-cases-gate-shell
-  -> generate-backend-pytest-pi
-  -> backend-test-traceability-gate-shell
-  -> execute-backend-pytest-shell
-  -> parse-backend-test-result-shell
-  -> classify-backend-test-result-pi
-  -> test-retrospect-pi
-  -> backend-test-outcome-gate-shell
-```
-
-这条链覆盖后端功能测试从需求分析到复盘评级的全链路流程：
-
-- `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 不执行。
-- `backend-test-environment-scout-pi`（read-only）：发现 pytest 配置、test roots、已有 fixture/client、文档化命令与 env *名称*（禁止全仓搜 secrets）；输出 Backend Test Execution Contract v1 纯 JSON。
-- `backend-test-execution-contract-shell`：`jsonArtifactGate.schemaId=backend-test-execution-v1`，校验并 materialize 当前 run 的 `contracts/backend-test-execution.json`；unknown schemaId / path traversal / secret 值 fail-closed。
-- `emit-backend-case-manifest-pi`（read-only）：从 `testcase/md/**` + 已验证 analysis 产出 Backend Test Case Manifest v1 纯 JSON（模型不写 `.harness/**`）。
-- `backend-test-case-manifest-shell`：`jsonArtifactGate.schemaId=backend-test-case-manifest-v1` → `contracts/backend-test-case-manifest.json`；caseId 唯一/格式、显式 AC 覆盖或 evidenceGaps、未知 AC、skipped 无 gapReason fail-closed；`coverageSummary` 由 gate 确定性计算/核对。
-- `backend-test-traceability-gate-shell`：pytest 生成后、execute 前校验 `generated` 的 file/symbol 存在；skipped/unsupported 必须有 gapReason。
-- `generate-backend-functional-cases-pi`：在 execution gate 之后，只消费已验证 analysis/execution 证据，按契约字段生成结构化后端功能测试用例（Markdown），用例 ID 带 `BE-` 前缀（如 `BE-ORDER-001`），写入 `testcase/md/`
-- `review-backend-cases-pi`：评审后端功能测试用例，输出审查报告 + `VERDICT: pass` / `VERDICT: request-revision`
-- `review-backend-cases-gate-shell`：只有评审首条 verdict 为 `VERDICT: pass` 时才允许继续生成 pytest；`request-revision` 或其它结果 **fail-closed 即停**，**不会**自动回到 generate 节点修订（本模板不启用 convergence；修好用例或约束后重新 `dag run-task`）
-- `generate-backend-pytest-pi`：依赖 review gate **与** execution contract，将功能用例转化为 pytest；可写 `testcase/**/test_*.py` 与可选 `helpers/**`/`factories/**`；只使用已验证 fixture/env name/`testRoot`/API 字段；禁止改 conftest/配置与生产代码
-- `execute-backend-pytest-shell`：先对 `contracts/backend-test-execution.json` 做确定性 preflight（framework、`testRoot` 存在且与生成期冻结的 Adapter 路径一致、required env、external base URL env；`managed-command` 无 sourceRef 证据 fail-closed），再执行 `pytest testcase/`；JUnit 写入 `$HARNESS_DAG_RUN_DIR/reports/backend-test-junit.xml`，原始 `pytestExitCode` 写入 `reports/backend-test-pytest-exit.txt`。当 JUnit 非空且 exit 为 0/1 时节点 FINISHED（断言失败不跳过下游）；禁止改测试源码或生产代码
-- `parse-backend-test-result-shell`：确定性 materialize Backend Test Result v1 → `contracts/backend-test-result.json`（损坏/缺失 JUnit fail-closed）
-- `classify-backend-test-result-pi`：read-only 结构化分类（ProductBug|TestBug|EnvFailure|ContractMismatch|FlakyTest|Unknown）；单次失败不得 FlakyTest；collection/command/report-error 不得 ProductBug
-- `test-retrospect-pi`：在 pass 与 assertion-fail 路径均运行；通过率与失败列表只来自 Result v1；不得把失败改写成通过
-- `backend-test-outcome-gate-shell`：仅以 Result v1 `outcome`/counts 收口；全绿 exit 0，否则非零；忽略 retrospective Markdown
-
-最终验证后的知识库回写可通过 `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`、`ai_workspace/loop-agent/test-reports/**`）受控回写
-6. **knowledge-sync-pointer-pi**：写 `features/<featureId>/testing/runs/latest.md` 与 `sync/applied/KS-*.json`
-
-设计说明见 `ai_workspace/loop-agent/design/full-chain-test-knowledge-base.md` §11；JSON 示例见 `ai_workspace/loop-agent/templates/knowledge-sync-dag.json`。
-
-业务知识图谱**初始化**可通过 `task.json.taskKind = "knowledge-graph-bootstrap"` 选择专用模板。跑前先落 B1 骨架：
-
-```bash
-loop-agent knowledge graph-init --product-name <name>
-# 编辑 knowledge/bootstrap/scope.yaml 后再 run-task
-```
-
-（需有 `knowledge/bootstrap/scope.yaml` 与 `status.yaml`；`graph-init` 幂等，默认不覆盖已有 scope/status，可用 `--force`。）
-
-图谱索引与 Phase A 查询（package-backed CLI，非 RAG）：
-
-```bash
-loop-agent knowledge graph-materialize
-loop-agent knowledge query --mode by_feature --feature F-2026-004 --json
-loop-agent knowledge query --mode by_id --id SVC-order --json
-loop-agent knowledge query --mode search --text "预占" --json
-```
-
-**增量更新（非全量开荒）**：缩小 scope 后复用同一 `knowledge-graph-bootstrap` DAG（propose 仅针对 seeds/includes；promote 仍默认不覆盖已有正式文件）：
-
-```bash
-loop-agent knowledge graph-incremental-prepare --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>
-# 如需手工晋升已审阅的 staging，再按顺序执行：
-loop-agent knowledge graph-promote
-loop-agent knowledge graph-materialize
-```
-
-测试知识日常写回仍用 `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/` 索引。设计见 `ai_workspace/loop-agent/design/knowledge-graph-ai-bootstrap.md`，示意 JSON 见 `ai_workspace/loop-agent/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、有界计划修订、只读 verdict 格式恢复、soft/hard shell 验证、process supervision、有界 repair、decision gates 与可选 convergence retry。初审 `request-revision` 不再直接终止：只读 `plan-revision-pi` 最多修订一轮，再由终审和 pass-only gate 决定是否授权 writer。初审与终审遗漏 `VERDICT:` 时各允许一个只读格式修复节点；格式结论不明确时必须转为 `request-revision`，shell gate 不会从正文猜测 pass。
-
-### 只读 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 保留独立证据，详见 [ai_workspace/loop-agent/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 的低/中风险单仓库任务，另须遵循 `ai_workspace/loop-agent/production-readiness.md` 与 `ai_workspace/loop-agent/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 修复：`ai_workspace/loop-agent/harness-methodology-tdd.md`
-- 完成或 handoff 声明：`ai_workspace/loop-agent/harness-methodology-verification.md`
-- 失败与意外行为：`ai_workspace/loop-agent/harness-methodology-debugging.md`
-
-## Handoff
-
-Handoff 应说明：
-
-- 改了什么
-- 有意未做什么
-- 跑了哪些验证命令
-- 是否影响契约、文档、测试或脚本
-- 剩余风险或后续工作
-
-较大工作应更新 `ai_workspace/loop-agent/progress/`、`ai_workspace/loop-agent/reports/`、active exec plan 或 `ai_workspace/loop-agent/decisions/`，以便下一会话不依赖聊天历史。

package/docs/loop-agent-harness.md

@@ -1,142 +0,0 @@
-# loop-agent Harness
-
-loop-agent 提供结构化 agent 工作的本地 harness。
-
-## Runtime 区域
-
-- `.harness/tasks/` — task source、约束、state、loop facts
-- `.harness/dag-runs/` — DAG run state 与 artifacts
-- `.harness/runs/` — one-shot tool run 证据
-- `.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/task-pool/states/<featureId>/<taskId>.json` — Task Pool schema v2 的 canonical state（ADR 0004）；复合身份 `TaskPoolTaskRef = { featureId, taskId }`。扁平 `states/<taskId>.json` 为 legacy，不得静默解释
-- `.harness/dag-runs/<lifecycle>/<run-id>/contracts/backend-test-analysis.json` — `backend-test` 的 run-owned 结构化分析契约；由 deterministic schema gate 从只读 analyze 输出生成，节点记录 path/hash/schema，随 lifecycle 目录迁移且不进入 Git writeSet
-- `.harness/dag-runs/<lifecycle>/<run-id>/.runtime/skill-snapshot.json` — 该 run 实际使用的 resolved skill profile snapshot；由 state 中相对 ref 与原始 bytes SHA-256 锚定，随 lifecycle 目录整体迁移
-
-## Skill 指令
-
-- `.agents/skills/loop-agent/` — loop-agent 仓库自有的 skill 指令与参考资料
-- `.agents/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 副本；`.agents/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/`、`.agents/skills/`（包括 `loop-agent` 与 `agent-worker`）、顶层 `ai_workspace/loop-agent/*.md`、`ai_workspace/loop-agent/templates/`、`examples/`、`harness.json`、`AGENTS.md`、`README.md`、`CHANGELOG.md`。
-
-生成或历史的 task facts 不是 package 资产。`ai_workspace/loop-agent/progress/`、`ai_workspace/loop-agent/reports/`、`ai_workspace/loop-agent/exec-plans/`、`ai_workspace/loop-agent/decisions/` 下现有文件属于目标仓库历史；包只携带这些目录的 README。
-
-从 npm 安装 `loop-agent` 并在其他项目使用时，DAG skill 指令按配置、用户或目标项目 `.agents/skills/` 解析（若存在），再回退到包内 `.agents/skills/`。目标项目可添加本地 skills，但不必复制 loop-agent 源码历史或根 `.agents/skills/` 目录即可使用默认 DAG 工作流。
-
-`scripts/self-host-canary.mjs` 是源码仓库维护脚本，不进入 npm package `files`；安装后的 package 不把它作为用户命令 surface。
-
-## harness.json Schema
-
-`ai_workspace/loop-agent/templates/harness.schema.json` 是面向 IDE 的 `harness.json` JSON Schema。它用于补全字段、提示枚举值、解释 executor/model routing 配置，并尽早暴露拼写错误。
-
-运行时事实源仍是 `src/governance/manifest-types.ts` 中的 Zod `harnessManifestSchema`；CLI 读取 `harness.json` 时继续通过 `loadHarnessManifest()` 解析。JSON Schema 不替代运行时校验，只服务编辑体验。
-
-`loop-agent init --profile full --merge` 会把 schema 投影到目标项目，并在生成的 `harness.json` 写入与 `governanceRoot` 匹配的 `$schema`。旧初始化项目可通过 `loop-agent init check-update` 查看缺失项，并用 `loop-agent init update --apply-safe` 安全补齐 schema 文件和 `$schema` 引用；该安全更新只允许修改 `$schema`，不会重写用户已有 harness 配置。
-
-DAG run state 会记录 runner PID、hostname 和定期 heartbeat，并为节点记录最近活动时间。`loop-agent dag status` 和 `loop-agent dag doctor --run-id <run-id> --markdown` 会将同主机且 PID 已消失的运行识别为 `orphaned`，将进程仍在但 heartbeat 过期的运行识别为 `stale`，将 runner 存活但当前节点超过 5 分钟没有状态活动标记为 `node-quiet`；跨主机运行只标记为 `unknown-host`，不会据此判断远端进程死亡。Observe 使用同一组字段过滤活跃 DAG，并在详情中显示 lifecycle 与 liveness；`node-quiet` 仍视为活跃，只提示操作者检查 session events 和 executor logs。
-
-Observe 和 `dag status` 还会给出 `effectiveStatus`、`stateConsistent` 与 `recoveryEligibility`。主状态以 lifecycle + canonical status + liveness 的综合判定为准，原始 `state.status` 只作为诊断事实展示。遇到历史 `paused/` 目录仍记录 `status=running`、或 active runner 已明确 `orphaned` 时，先运行只读检查：
-
-```bash
-loop-agent dag reconcile-run --run-id <run-id>
-```
-
-确认不应继续后，必须显式选择收口含义并填写原因：
-
-```bash
-loop-agent dag reconcile-run --run-id <run-id> --action supersede --reason "implementation completed elsewhere"
-loop-agent dag reconcile-run --run-id <run-id> --action abandon --reason "operator cancelled obsolete work"
-```
-
-收口会保存 `reconciliation.json` 原始快照，将仍为 RUNNING 的节点标为 ERROR，并把 run 归档到 `completed/`；不会把未执行节点伪造成成功。同机 runner 仍存活、仅 `node-quiet`、heartbeat stale 但 PID 仍存在、跨主机或无法证明停止时都会拒绝收口。
-
-DAG 节点的模型由 `executorModels[executor][complexity]` 路由。新 run 会将解析后的 Pi/Cursor 模型写入节点 state；Observe 读取历史 run 时会从 `run.json` 补算缺失模型。Shell 和 Static 节点不使用模型，因此模型列保持 `-`。
-
-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`
-- `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 pool doctor|migrate-state`、`agent-worker report morning|metrics`、`agent-worker observe serve|snapshot`
-
-`dag run-task` 在生成 DAG 草稿前会运行与 `plan check` 同源的 exec-plan 索引校验；active plan 与 `ai_workspace/loop-agent/exec-plans/active/README.md` 索引不一致时立即失败，避免运行昂贵节点后才在末端 shell verify 发现。`plan create` 优先复用目标项目模板并回退到发布包内置 `ai_workspace/loop-agent/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 覆盖、阻塞、证据和唯一主行动。
-
-默认输出按结果、原因、下一步、证据组织；`--json` 输出 schemaVersion 1 JSON。缺失或损坏的 Packet、state、JSONL 或 closeout 会暴露 validation error / projection warning，不会被误判为无数据、可交付或已关闭。该命令不写 Feature Packet、Task Pool 或 Git。
-
-`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。
-
-显式 `--git-mode checkpoint` 会在 clean preflight 后创建或复用受 transaction record 管理的 `agent/<feature-id>` 本地分支。成功任务只有在 changed/untracked/sensitive 与 TaskSpec allowed/forbidden audit 通过后才 commit；失败任务的 patch、inventory、untracked content 与 boundary audit 写入 `.harness/task-pool/artifacts/features/<feature-id>/git/failures/`，随后 reset/clean 到最近 checkpoint 并再次验证 clean。默认模式不触碰 Git；`--keep-failed-diff` 只保留现场并停止，不允许继续下一个写任务。任何模式都不授权 stash、push、remote PR 或 merge。
-
-业务 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 产物，但不会删除历史。
-
-人工批准只接受 TaskDraft；行动卡不能批准或进入 Ready。批准会校验 draft/evidence hash、repo/path containment、Feature baseline 和冲突，在 staging validation 后写 TaskSpec、graph、Ready、approval/index 与 event。rename、state、approval、index、event 五个故障点均有注入回滚测试；重复批准幂等复用首次结果。`--dry-run` 零写入，`--json` 失败保持 stdout JSON、stderr 无噪声和非零退出码。
-
-## Worker Retry
-
-失败 Task Pool task 必须显式 retry，不能删除 `.harness/task-pool/runs.jsonl` 或复用失败的 `workerRunId`。canonical 命令必须携带 Feature：
-
-```bash
-agent-worker task retry <task-id> --feature-id <feature-id> --repo <target-repo> --reason "provider configuration corrected"
-agent-worker batch run-ready --feature-dir <feature-dir> --repo <target-repo>
-```
-
-`task retry` 只接受指定 Feature 下的 `Failed` state，保留旧 run 和 failure handoff，并写入 `retryOfWorkerRunId`。跨 Feature 同名 Task 时省略 `--feature-id` 必须 fail-closed。下一次 `run-ready` 生成新的 `workerRunId`；`Blocked`、`Done` 或无 state 的 task 必须先由 operator 处理根因，不能盲目重试。
-
-## Task Pool Doctor 与 State 迁移
-
-```bash
-agent-worker pool doctor --repo <target-repo> --json
-agent-worker pool migrate-state --repo <target-repo>            # dry-run 默认
-agent-worker pool migrate-state --repo <target-repo> --apply --owner <owner> --reason <reason>
-```
-
-`pool doctor` 只读扫描 v2 / legacy inventory 与映射证据，exit 0 也可带 findings。`pool migrate-state` 默认零写入；apply 需要 `--owner` 与 `--reason`，保留 bytes/hash 审计 artifact，失败全回滚，且不改写 `runs.jsonl` / `events.jsonl`。
-
-## 验证 Preset
-
-Shell preset `loop-agent-standard-verify` 跑 typecheck 与聚焦 DAG 测试。完整交付仍应使用：
-
-```bash
-bash scripts/ci.sh
-```