@tea-agent/loop-agent 0.16.25 → 0.17.0

package/skills/frontend-design-review/SKILL.md

@@ -9,19 +9,29 @@ references:
 
 # Frontend Design Review
 
-For first/final design review nodes. Read the checklist, then audit contract, scout,
-mock strategy, plan/revision, task constraints/bounds, and traceable design evidence. The knowledge-
-base connector is TODO: never invent results. If absent/failed/unmatched, require
-`<repoRoot>/openspec/**` search/read evidence before repo conventions.
+For frontend design review nodes. Read the checklist; audit contract, scout, Mock
+strategy, effective plan, task bounds, and traceable design evidence. The knowledge-
+base connector is TODO: never invent results. If unavailable or unmatched, require
+`<repoRoot>/openspec/**` search/read evidence before repository conventions.
 
 ## Verdict Contract
 
 First non-empty line: exactly `VERDICT: pass` or `VERDICT: request-revision`.
-Any blocker requires request-revision; the shell gate reads this line exactly.
+Any blocker requires request-revision. An initial pass is the effective verdict;
+there is no intermediate first-design shell gate.
 
-For `frontend-final-design-review-pi`: recheck the original plan when output is
-`PASS_NO_REVISION_NEEDED`; otherwise verify every Required Plan Correction. Reject
-remaining, incomplete, or newly introduced gaps.
+In standard/full topology, revision and final review run only after initial
+`VERDICT: request-revision`. Verify every Required Plan Correction against the
+complete revision; reject remaining, incomplete, or new gaps. An initial pass uses
+the original plan and skips both conditional nodes.
+
+Small-risk topology instead removes initial review and revision, then runs
+`frontend-final-design-review-pi` as the sole review of the original plan. Do not
+expect initial findings or a revision there.
+
+The deterministic gate prefers final-review output and falls back to initial review
+only when no current-run final output exists. Existing malformed/non-pass primary
+output fails closed.
 
 ## Blocking Conditions
 
@@ -35,20 +45,19 @@ remaining, incomplete, or newly introduced gaps.
   inline fake data; commented real requests; Mock-on production defaults; test-only
   production imports; or Mock evidence reported as real integration.
 
-Knowledge-base absence is advisory if relevant `openspec/` rules were searched/read
-and applied. Block skipped fallback, unresolved conflict, or unresolved UI decisions.
+Knowledge-base absence is advisory if relevant `openspec/` rules were read and
+applied. Block skipped fallback, unresolved conflict, or unresolved UI decisions.
 
 ## Method And Output
 
-Map criteria to steps/files/states/checks, audit paths/evidence, classify Blocking or
-Advisory, and never edit files.
+Map criteria to steps/files/states/checks, audit paths/evidence, classify Blocking
+or Advisory, and never edit files.
 
 ### Spec Evidence Rules
 
-Run `grep`/`find`, then explicit `read` calls for applicable specs and checklist.
-Only successful paired reads count as “已读取规范文件”; summaries do not. List each
-read path/section in `Checked Items`. If the connector is unavailable, search/read
-`openspec/` before accepting repository conventions.
+Run `grep`/`find`, then explicit `read` calls for applicable specs/checklist. Only
+successful paired reads count as “已读取规范文件”; summaries do not. List each path/
+section in `Checked Items`; search/read `openspec/` before accepting conventions.
 
 ```markdown
 VERDICT: pass

package/skills/frontend-implementation/references/node-contracts.md

@@ -8,20 +8,20 @@ Pre-write nodes are read-only. Preserve IDs, labels, commands, language, require
 - **`frontend-scout-pi`**: routes, components, tokens, data/API/Mock, scripts, tests, assets. Fact vs inference vs gap. Knowledge base first; else search+read `<repoRoot>/openspec/**` before repo fallback. Output stack, routes, components, styling, conventions, state/data, test entry points, reuse, risks.
 - **`frontend-mock-assess-pi` + gate**: declares `firstProtocolLine: "MOCK_STRATEGY:"`; canonical output first line
   `MOCK_STRATEGY: native|browser-intercept|request-adapter|not-needed|blocked`
-  Pi output mapping promotes the first matching protocol line ahead of any preamble without inventing or replacing its value; missing, malformed, or blocked strategies still fail closed. Prefer native Mock; browser intercept only with existing e2e; request-adapter only for reversible local preview. Default `auto` may select `not-needed` when contract/scout evidence confirms no project Mock capability, without adding Mock files/deps, while keeping real requests default and recording the Real Integration Gap. Other `not-needed` cases need positive no-remote/stable-backend evidence; invalid when `frontendMock.policy=required`. `blocked` for missing/conflicting contracts, unsafe paths/deps, unread specs, production-default-on, unverifiable entrypoints. Output Mock Decision, API/spec/service evidence, backend readiness, selection evidence, endpoint/fixture matrix, activation, targets, production safety, verification plan, real-integration gap, blocking issues. Never invent fields, store secrets, comment real requests, import test mocks into production, or treat Mock as real integration. Gate uses `first-non-empty` only; never authorizes writes. Unsafe required contracts → no writer.
-- **`frontend-plan-pi` + design loop**: AC → steps, in-bound files, UI states, reuse, deps, activation/rollback, frozen verify entrypoints, real-integration gap. First gate: `VERDICT: pass|request-revision`. Pass may emit `PASS_NO_REVISION_NEEDED`; else full corrected plan without invented evidence. Final review rechecks plan/findings/revision/assessment/Mock safety. Only final `VERDICT: pass` authorizes writes; failure → replan/rerun (not dev-fix). The plan-pi prompt now includes the complete `frontend-implementation-contract-v1` JSON Schema loaded from the loop-agent package `docs/templates/` path, plus deterministic source binding, risk level, and allowed implementation targets. The model does not need to search or guess contract fields; `schemaId`, `targetFiles`, `requirementCoverage` are explicitly forbidden.
+  Pi output mapping promotes the first explicitly labeled Mock strategy line ahead of any preamble, including common bullet, quote, inline-code, fullwidth-colon, `Mock strategy`, and split label/value drift, without inventing or replacing its value; missing, unlabeled, malformed, or blocked strategies still fail closed. Prefer native Mock; browser intercept only with existing e2e; request-adapter only for reversible local preview. Default `auto` may select `not-needed` when contract/scout evidence confirms no project Mock capability, without adding Mock files/deps, while keeping real requests default and recording the Real Integration Gap. Other `not-needed` cases need positive no-remote/stable-backend evidence; invalid when `frontendMock.policy=required`. `blocked` for missing/conflicting contracts, unsafe paths/deps, unread specs, production-default-on, unverifiable entrypoints. Output Mock Decision, API/spec/service evidence, backend readiness, selection evidence, endpoint/fixture matrix, activation, targets, production safety, verification plan, real-integration gap, blocking issues. Never invent fields, store secrets, comment real requests, import test mocks into production, or treat Mock as real integration. Gate uses `first-non-empty` only; never authorizes writes. Unsafe required contracts → no writer.
+- **`frontend-plan-pi` + conditional design loop**: AC → steps, in-bound files, UI states, reuse, deps, activation/rollback, frozen verify entrypoints, real-integration gap. Initial `VERDICT: pass` uses the original plan directly. Only exact `VERDICT: request-revision` runs read-only plan revision plus final review; there is no `frontend-first-design-gate-shell` or pass-path `PASS_NO_REVISION_NEEDED` node. The effective final gate prefers final review when present, otherwise initial review, and only exact pass authorizes writes; malformed/missing/request-revision fails closed → replan/rerun (not dev-fix). The plan-pi prompt includes the complete `frontend-implementation-contract-v1` JSON Schema loaded from the loop-agent package `docs/templates/` path, plus deterministic source binding, risk level, and allowed implementation targets. The model does not need to search or guess contract fields; `schemaId`, `targetFiles`, `requirementCoverage` are explicitly forbidden.
 - **`frontend-implement-pi`**: sole exclusive writer. Stay in `writeSet`; real requests default-on; Mock reversible, dev/test-only, production-off. Atomic handler/intercept/adapter with consumer+tests. Stop on forbidden paths or guesses. Output changed files, behavior, UI states, styling notes, verification attempted, residual risks. Optional mock-verify when frozen; static+behavior always; behavior must prove page consumption. Skipped-Mock `not-needed` keeps real integration pending unless the real backend path has fresh evidence.
 
 ## Contract / trace / stages (M1–M2)
 
-- Contract shell: `jsonArtifactGate` → `contracts/frontend-implementation-contract.json` from revision (one fenced JSON or pure JSON); schemaId `frontend-implementation-contract-v1`. Final design + implement depend on it; `MOCK_STRATEGY: blocked` not implementable.
+- Contract shell: `jsonArtifactGate` → `contracts/frontend-implementation-contract.json` from the effective plan (one fenced JSON or pure JSON); schemaId `frontend-implementation-contract-v1`. Revision is primary and original plan is fallback only when the conditional revision output is absent. Requirement coverage uses the same primary/fallback rule. An existing malformed/schema-invalid/incomplete primary fails closed; fallback never masks it. Final design + implement depend on the artifact; `MOCK_STRATEGY: blocked` not implementable.
 - Trace shell: `frontend-verification-trace-gate` binds contract `verificationTargets` to static/behavior records (`commandLabels`, file exists, optional symbol). Assess `MOCK_STRATEGY:` must match `mockApi.strategy` when present. Writes `contracts/frontend-verification-trace.json`. Browser/visual always `not-run`.
 - Implement stages: (1) contract confirm (2) tests sync (3) component/UI (4) API/Mock (5) frozen checks (6) diff cleanup. Summary: Contract Ref, Changed Files, Requirements, UI States, Tests, Verification Attempts, Deviations, Residual Risks.
 
 ## Repair (M3)
 
-static/behavior/trace may `nonZeroExitPolicy: record`. Assess → `contracts/frontend-repair-assessment.json`. Repair-contract fail-closed on non-repairable (contract/path/dependency/credential/deploy/spec-unclear) or writeSet expansion. `frontend-repair-pi`: same writeSet as implement; no re-spec; max 1 attempt. Reverify/retrace fail policy; review/closeout use post-repair evidence.
+static/behavior/trace may `nonZeroExitPolicy: record`. Assess emits pure JSON and writes `contracts/frontend-repair-assessment.json`. Only `eligible=true` runs `frontend-repair-pi` (same writeSet as implement; no re-spec; max 1 attempt), reverify, and retrace. No-failure condition-skips that branch, while diff/review/read-only `frontend-closeout-pi` continue on initial evidence. Repair-contract fails closed on non-repairable (contract/path/dependency/credential/deploy/spec-unclear), writeSet expansion, ERROR, or hard skip; `all-or-condition-skip` never softens those failures.
 
 ## Risk & capability (M4–M6)
 
-Deterministic risk (no model); high-risk beats small; supervised never small. Small may drop first design gate + plan-revision; contract shell retargets to `frontend-plan-pi`. Capability seed injects adapters; openspec/task sources outrank. A11y: static/component tools only when present; Browser a11y always not-run.
+Deterministic risk (no model); high-risk beats small; supervised never small. Small may drop the initial design review + conditional revision branch; its retained final review audits `frontend-plan-pi`, and contract shell retargets to that plan without fallback. Capability seed injects adapters; openspec/task sources outrank. A11y: static/component tools only when present; Browser a11y always not-run.

package/skills/loop-agent/references/command-reference.md

@@ -34,14 +34,17 @@ loop-agent doctor
 选择命令时按以下优先级：
 
 1. **主路径 DAG**，用于常规 autonomous work：
+
    ```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 <repo-root>
    ```
+
    `<temp-dir>` 表示平台原生临时目录；也可以省略 `--output`，再使用命令 JSON 输出里的 `outputPath`。主路径 JSON 输出含稳定 summary：`dag run-task` 的 `message` 为 `DAG draft created`，`dag validate` 的 `message` 为 `DAG validation passed` 且含 `checks.writeSets` / `checks.decisionGates`，`run-dag` 的 `message` 为 `DAG run finished`。
 2. **Operator 工具**，用于 recovery、诊断、评测重放与 closeout：
+
    ```bash
    loop-agent eval replay --spec <path> --json
    loop-agent eval report --replay-id <id> --markdown
@@ -64,7 +67,9 @@ loop-agent doctor
    loop-agent knowledge curate --markdown --output ai_workspace/loop-agent/reports/<task-id>-learned-proposal.md
    loop-agent loop-benchmark --markdown
    ```
+
 3. **Escape hatch**，仅用于 worktree 隔离委派、executor 调试或 one-shot 诊断：
+
    ```bash
    loop-agent delegate <task-id> --auto-run
    loop-agent harvest <task-id>
@@ -73,6 +78,7 @@ loop-agent doctor
    ```
 
 ### Setup（首次）
+
 ```bash
 npm install -g @tea-agent/loop-agent@latest
 loop-agent --version
@@ -80,12 +86,14 @@ loop-agent --help
 ```
 
 ### 检查 repo harness
+
 ```bash
 loop-agent inspect                                           # 当前 repo（自动检测）
 loop-agent --repo-root /path/to/target-repo inspect           # 指定 repo
 ```
 
 ### 健康检查
+
 ```bash
 loop-agent doctor
 ```
@@ -104,7 +112,7 @@ SDK 回归或 SDK 可选依赖不可用时用 `cli-only` 诊断。CLI fallback
 用户中文表达到命令的映射（与目标项目 `AGENTS.md` 的“自然语言入口路由”保持一致）：
 
 | 用户表达 | 命令 |
-|---|---|
+| --- | --- |
 | loop-agent 初始化 / loop agent 初始化 / loop agent初始化 / 初始化 loop-agent | 先运行 `loop-agent init instructions --repo-root .`，再运行 `loop-agent init --repo-root . --profile full --merge`，随后补全 README/验证矩阵并复查 doctor/inspect/docs audit |
 | 初始化更新校验 / loop agent初始化更新校验 / 检查初始化更新 | `loop-agent init check-update --repo-root . --markdown`（只读，不得隐含 `apply-safe`） |
 | 初始化安全更新 / loop agent初始化安全更新 / 应用初始化更新 | 先 `loop-agent init check-update --repo-root . --markdown`，再 `loop-agent init update --repo-root . --apply-safe`（surface 缺失时先 `--bootstrap-surface`；human decisions 存在时停下等用户） |
@@ -128,6 +136,7 @@ loop-agent init reconcile --repo-root <target-repo> [--json|--markdown]
 `init reconcile` 是升级后对齐入口：surface 缺失返回 `needs-baseline` 且零写入，存在 human decisions 返回 `needs-human-decision` 且零写入，活跃 DAG/Worker 或 Worker 状态无法确认时返回 `blocked-active-runtime` 且零写入；其余情况复用 `--apply-safe` 的安全动作并复查返回 `clean`/`needs-model-merge`/`needs-safe-update`。控制器升级成功后，普通安全仓库命令结束时会自动检测目标项目是否需要 reconcile；非 TTY 只向 stderr 输出 `loop-agent init reconcile --repo-root ...` 提示且不写入目标，TTY 且无 human decisions、无活跃运行时可经明确 `y/yes` 同意后应用 deterministic safe actions。
 
 ### 查看或复制内置示例
+
 ```bash
 loop-agent examples list
 loop-agent examples show <name>
@@ -137,6 +146,7 @@ loop-agent examples copy <name> --output examples/<name>
 `examples` 只读取或复制包内示例，不会自动写入目标项目。省略 `--output` 时，`copy` 会写到目标项目的 `examples/<name>`。
 
 ### 创建新 task
+
 ```bash
 loop-agent new-task <task-id> "Task Title"
 ```
@@ -144,13 +154,30 @@ loop-agent new-task <task-id> "Task Title"
 创建 `.harness/tasks/<task-id>/`，含 `source/`、`artifacts/`、`logs/` 及初始 state。`artifacts/` 默认只预种 `修改记录.md` 与 `验证结果.md`（供后续 `promote-run` / `closeout` 使用）；不再预种 L1 的 `分析报告.md`、`实现计划.md`、`复盘报告.md`。
 
 ### 导入原始 PRD（不可变事实源）
+
 ```bash
 loop-agent import-prd <task-id> --file ai_workspace/loop-agent/path/to-prd.md [--name requirement] [--json]
 ```
 
 把用户原始 PRD **原样复制** 到 `.harness/tasks/<task-id>/source/references/`，并写入 `source/source-manifest.json`（含 SHA-256）与 `task.json.referenceDocs`。此步骤不调用模型、不改写内容。随后再写派生的 `source/需求.md` 执行契约；冲突时以 `source/references/*` 为准。
 
+### Task Contract / operator machine surface
+
+```bash
+loop-agent task contract show <task-id> [--json]
+loop-agent task contract validate --task <task-id> --input <path> --json
+loop-agent task contract diff --task <task-id> --input <path> --json
+loop-agent task contract apply --task <task-id> --input <path> --expected-revision <n> --expected-observed-hash <sha256> --request-id <id> --request-payload-sha256 <sha256> --json
+loop-agent task contract adopt --task <task-id> --expected-revision <n> --expected-observed-hash <sha256> --request-id <id> --request-payload-sha256 <sha256> --json
+loop-agent task contract doctor --task <task-id> --json
+loop-agent task contract recover --task <task-id> --json
+loop-agent operator capabilities [--json]
+```
+
+`task` 是 Task Contract 边界（show/validate/diff/apply/adopt/doctor/recover）。`operator` 返回 Operator machine envelope capabilities，供 Console/控制面做能力协商。
+
 ### Task action context / artifact instructions
+
 ```bash
 loop-agent status <task-id> --json
 loop-agent instructions source --task <task-id> --json
@@ -163,6 +190,7 @@ loop-agent instructions closeout --task <task-id> --json
 `status` 是 agent 行动上下文入口，返回 `artifactPaths`、`runRefs`、`actionContext` 与 `nextActions`。`instructions` 在写入 source、DAG draft、task artifacts、promotion 或 closeout 前返回目标路径、依赖、模板、写策略与完成标准；blocked artifact 会列出 `missingDependencies`。`instructions task-artifacts` 只要求 promote 桥接的 `修改记录.md` / `验证结果.md`，不要求手写分析/计划/复盘三份 L1 报告。
 
 ### Promotion / closeout
+
 ```bash
 loop-agent promote-run <task-id> --run-id <run-id>
 loop-agent closeout task <task-id>
@@ -173,21 +201,26 @@ loop-agent closeout task <task-id>
 one-shot run evidence 位于 `.harness/runs/{active,completed,failed}/<run-id>/`。`cursor-prompt` 与 Pi `cursor` tool 会创建这类 run evidence；当前 `pi-prompt` 不创建 `.harness/runs/`。active 目录只应保留 live one-shot run，残留或 `.DS_Store` 等系统文件应清理。详见 `one-shot-runs.md`。
 
 ### 运行任何 step 前：准备 source materials
+
 `new-task` 之后，先归档原始 PRD，再写派生执行契约：
+
 ```bash
 loop-agent import-prd <task-id> --file <path-to-original-prd.md>
 # then write derived contract:
 mkdir -p <repo-root>/.harness/tasks/<task-id>/source
 cat > <repo-root>/.harness/tasks/<task-id>/source/需求.md
 ```
+
 `需求.md` 写目标、范围、非目标与验收标准，并映射回 `source/references/*`；不要让 AI 直接改写原始 PRD。
 
 若 task 有硬约束（仅允许特定文件、禁止改动），另加：
+
 ```bash
 cat > <repo-root>/.harness/tasks/<task-id>/source/执行约束.md
 ```
 
 ### Feature-study workflow（参考代码 → 轻量实现）
+
 例如「分析参考仓库的一项功能，并在目标仓库实现轻量版本」：
 
 ```bash
@@ -209,6 +242,7 @@ loop-agent --repo-root <target-repo> run-dag --dag <temp-dir>/<task-id>-dag.json
 历史顺序式 `run analyze|plan|spec|implement|verify|retrospective|auto|loop|continue|study` 已移除。新任务不要使用这些命令，也不要在 prompt、skill 或 docs 中把它们描述为 fallback。
 
 ### Reference helpers（compatibility）
+
 ```bash
 loop-agent reference index <task-id>
 ```
@@ -216,6 +250,7 @@ loop-agent reference index <task-id>
 `reference` 是 compatibility / feature-study 辅助入口，用于维护或检查参考资料索引。常规实现任务不要从 `reference` 起步；按 `new-task` + DAG 路径执行。
 
 ### Task goal lifecycle（compatibility-only / deprecated-candidate）
+
 ```bash
 loop-agent goal set <task-id> "Objective text" [--token-budget <number|null>]
 loop-agent goal set <task-id> "Replacement objective" --force
@@ -238,6 +273,7 @@ loop-agent goal clear <task-id>
   - preflight 含 state/mode guard + 启动前 goal 一致性复检
 
 ### Agent DAG validation 与 execution
+
 ```bash
 loop-agent dag validate --dag <temp-dir>/hybrid-dag.json                 # 常规 validation；无 .harness/dag-runs 副作用
 loop-agent dag validate --dag <temp-dir>/hybrid-dag.json --strict-models # 非 canonical executorModels 时失败
@@ -300,6 +336,7 @@ loop-agent dag resume --run-id <run-id>                  # approve 后继续
 - 显式专用 `taskKind` 保持兼容并优先于任务源分类，也不扩充 governance profile：`frontend-implementation` 可有意覆盖为带 Mock 规范评估、contract gate、design gate 和验证链的前端模板；可选 `frontendMock` 配置 auto/required/disabled、既有服务目录和专项验证命令，required 合同不完整时不会生成 writer。`backend-test` 显式选择需求分析 → 功能用例 → 评审 → pytest 生成/执行 → 复盘的后端测试工程模板。
 
 ### Saved Dynamic Workflow operator UX
+
 ```bash
 loop-agent workflow list
 loop-agent workflow inspect <name>
@@ -360,11 +397,13 @@ Replay spec 最小结构：
 ```
 
 ### 检查 task status
+
 ```bash
 loop-agent status <task-id>
 ```
 
 ### Docs governance helpers
+
 ```bash
 loop-agent docs audit
 loop-agent docs archive ai_workspace/loop-agent/exec-plans/active/<plan>.md
@@ -387,6 +426,7 @@ loop-agent coverage report --language python|java --input <coverage.json|jacoco.
 - `handoff coverage`：从 `source/需求.md` 抽取 checklist / numbered / `REQ-*` 项并输出 coverage audit；未覆盖项 exit 1；`explicitly_out_of_scope` 不计为缺口
 
 ### Pi runtime reuse benchmark / decision（无 live call）
+
 ```bash
 loop-agent pi-reuse-benchmark \
   --report ai_workspace/loop-agent/reports/<benchmark-report>.md \
@@ -403,6 +443,7 @@ loop-agent pi-reuse-benchmark \
 对已有 benchmark plan/report 文件及可选 `executor.jsonl` evidence 做确定性摘要。**不**跑 live Pi call、不创建 task、不改 `CODE_AGENT_PI_REUSE_RUNTIME`（默认仍为 `off`）。输出 `defer`、`maintain-opt-in` 或 `eligible-for-human-review` — 永不 default-on。
 
 ### Loop convergence benchmark baseline（无 live call）
+
 ```bash
 loop-agent loop-benchmark --markdown
 loop-agent loop-benchmark --markdown --output ai_workspace/loop-agent/reports/2026-06-30-loop-agent-loop-benchmark.md
@@ -411,6 +452,7 @@ loop-agent loop-benchmark --markdown --output ai_workspace/loop-agent/reports/20
 生成 M0 deterministic baseline，对照 `single-repair`、`3-pass-convergence`、`3-pass-convergence+quota`。**不**跑 live Pi/Cursor call、不创建 task、不改 `convergence.enabled` 默认值。live dogfood 证据缺失时输出 `blocked` 并建议保持 opt-in。
 
 ### Long-running loop outer state（experimental）
+
 ```bash
 loop-agent loop init <task-id>
 loop-agent loop status <task-id>
@@ -426,6 +468,7 @@ loop-agent loop closeout <task-id>
 `loop` 是 Agent DAG 之上的长程状态和 evidence layer，记录 rounds、signals、verification summaries 和 closeout draft。它不是替代 `dag run-task` / `run-dag` 的实现路径；medium/large work 仍需要 DAG evidence 或明确 fallback reason。
 
 ### Minimal spec spine audit
+
 ```bash
 loop-agent spine audit <task-id> --json
 loop-agent spine audit <task-id> --markdown
@@ -434,6 +477,7 @@ loop-agent spine audit <task-id> --markdown
 检查 task 的 `source/需求.md`、`source/执行约束.md`、`task.json.allowedPaths` / `forbiddenPaths`、需求覆盖与 final verification command labels。`medium` / `large` task 的空 `allowedPaths`、allowed/forbidden overlap、未覆盖验收项、无 final verify command 都会让 audit 非零退出。
 
 ### Knowledge curator proposal
+
 ```bash
 loop-agent knowledge curate --markdown
 loop-agent knowledge curate --markdown --output ai_workspace/loop-agent/reports/<task-id>-learned-proposal.md
@@ -442,6 +486,7 @@ loop-agent knowledge curate --markdown --output ai_workspace/loop-agent/reports/
 读取 `.harness/knowledge/patterns.jsonl` 中 completed convergence repair pattern，按 `failureClass + fixScope shape + invariant` 去重，生成 human-gated learned guidance proposal。命令只生成 proposal，不直接修改 `./skill/references/learned/*.md`；输出会先通过 skill safety audit。
 
 ### Knowledge graph / query CLI
+
 ```bash
 loop-agent knowledge graph-init --product-name <name>
 loop-agent knowledge graph-materialize
@@ -511,6 +556,7 @@ agent-worker observe snapshot --repo <repo-root>  # 输出 GlobalSnapshot JSON
 - 当前 Worker 仍是 v0（库 + CLI + dogfood），未接入定时/CI 驱动；`report morning` 只能从已有 Task Pool runs 汇总。
 
 ### 查看 duration statistics
+
 ```bash
 loop-agent stats
 ```
@@ -526,6 +572,7 @@ loop-agent worktree create|list|remove ...
 用于 worktree 隔离以及可选的 Pi-only DAG 执行与 merge 收口。常规 autonomous work 应优先 Agent DAG；详见 `multi-worktree.md` 与 `ai_workspace/loop-agent/cursor-prompt-sidecar.md`。
 
 ### One-shot Cursor sidecar（escape hatch）
+
 ```bash
 loop-agent cursor-prompt --cwd <repo-root> "Review this task without editing files."
 loop-agent cursor-prompt --cwd <repo-root> --file /tmp/bounded-cursor-task.md

package/skills/loop-agent/references/hybrid-dag.md

@@ -16,12 +16,12 @@
 
 对于默认 `standard` 任务，生成器根据标题、`source/需求.md` 和结构化 `allowedPaths` 做保守、确定性的需求分类。只有高置信的前端实现需求自动选择 `frontend-implementation` DAG；后端、前后端混合、明确排除前端或证据不足的需求继续使用 governance profile 选出的模板。分类不会把普通后端实现路由到 `backend-test`，也不会替换由显式 profile、`workflowPolicy` 或 supervised quality gate 选中的 supervised 模板。
 
-前端专用链在 `frontend-scout-pi` 后加入只读 `frontend-mock-assess-pi` 和确定性 contract gate，根据接口契约、后端就绪度、生成期能力 seed 与固化验证入口选择 `native|browser-intercept|request-adapter|not-needed|blocked`。策略直接传给 plan、两阶段 design review、唯一 writer、实现 review 和 closeout；真实请求保持默认，缺少契约、生产隔离、注释真实请求或显式 required 合同不完整时 gate 阻塞。可选 `frontendMock` 配置声明 `auto|required|disabled`、既有服务目录与专项命令；默认 `auto` 下没有已确认 Mock 能力时跳过 Mock 继续实现并保留真实联调缺口，不安全或不完整的显式 required 合同只生成无 writer 的评估链，有可信命令时才增加 `frontend-mock-verify-shell`。Mock-backed 证据只证明前端状态；跳过 Mock 且未调用后端时 closeout 报告 `Frontend status: locally-validated` 与 `Real integration: pending`。
+前端专用链在 `frontend-scout-pi` 后加入只读 `frontend-mock-assess-pi` 和确定性 contract gate，根据接口契约、后端就绪度、生成期能力 seed 与固化验证入口选择 `native|browser-intercept|request-adapter|not-needed|blocked`。策略直接传给 plan、条件 design review、唯一 writer、实现 review 和 closeout；真实请求保持默认，缺少契约、生产隔离、注释真实请求或显式 required 合同不完整时 gate 阻塞。standard/full 拓扑的 initial design pass 直接使用 original plan，只有 request-revision 才运行 plan revision 和 final review；small-risk 拓扑保留 final review 作为对 original plan 的单一审查。已删除 `frontend-first-design-gate-shell`，保留的 final gate 只接受生效 initial/final verdict 的 pass。可选 `frontendMock` 配置声明 `auto|required|disabled`、既有服务目录与专项命令；默认 `auto` 下没有已确认 Mock 能力时跳过 Mock 继续实现并保留真实联调缺口，不安全或不完整的显式 required 合同只生成无 writer 的评估链，有可信命令时才增加 `frontend-mock-verify-shell`。Mock-backed 证据只证明前端状态；跳过 Mock 且未调用后端时 closeout 报告 `Frontend status: locally-validated` 与 `Real integration: pending`。初始验证后的 assessment 输出 JSON，只有 `eligible=true` 才运行 repair/reverify/retrace；绿色路径跳过该分支后仍继续 diff/review/只读 `frontend-closeout-pi`，non-repairable 或 `ERROR` 仍硬阻断。
 
 
-> Backend-test vNext：Analysis v2 明确 responseBody shape、ordering、field comparison/precision 与 sourceRefs，并兼容归一化 v1；pytest 生成后 traceability 按真实 symbol 更新 generated Manifest 和 coverage，随后执行唯一一次结构化语义 review。任何 `request-revision` 由确定性 gate 终止当前 run。pytest 只执行一次，Observe 对新 run 投影 initial/canonical、classification 与 coverage；历史 repair/final evidence 仍兼容读取。
+> Backend-test report-first：Analysis v2 明确 responseBody shape、ordering、field comparison/precision 与 sourceRefs，并兼容归一化 v1 及窄范围 evidence gap alias；Manifest 后直接生成 pytest，case review 作为 advisory evidence 进入 canonical context。pytest 生成后由确定性 traceability 校验真实 file/symbol/case 映射，再执行唯一一次 pytest。exit 0/1 且 JUnit 有效都继续 Result、classification、retrospective 与最终 L-5；Observe 对新 run 投影 initial/canonical、classification 与 coverage，历史 repair/final evidence 仍兼容读取。
 
-显式专用 `taskKind` 保持兼容并优先于任务源分类。`backend-test` 选择固定 **15 个真实顶层节点**的后端测试 DAG：intake 双合同、cases+manifest、用例 pass-only gate、pytest 生成与 semantic review、语义 pass-only gate、单次 execute+parse、classification、canonical Result、retrospective 和 outcome gate。新 run 没有 case revision、semantic revision、repair eligibility、TestBug repair 或 final rerun；失败分类继续支持独立 follow-up。`knowledge-sync` 与 `knowledge-graph-bootstrap` 继续通过各自显式 taskKind 选择知识回写/图谱开荒 DAG。治理等级仍由 `minimal|standard|reviewed|supervised` 推断。
+显式专用 `taskKind` 保持兼容并优先于任务源分类。`backend-test` 选择固定 **12 个真实顶层节点**的报告优先 DAG：intake 双合同、cases+manifest、advisory case review、pytest 生成、确定性 traceability gate、单次 execute+parse、classification、包含 review/traceability 的 canonical context、retrospective 与最终 L-5。case review 不授权或阻断 writer；pytest assertion failure 是 Result testOutcome，不再由最终 outcome shell gate 将报告流水线判失败。`knowledge-sync` 与 `knowledge-graph-bootstrap` 继续通过各自显式 taskKind 选择知识回写/图谱开荒 DAG。治理等级仍由 `minimal|standard|reviewed|supervised` 推断。
 
 ### DAG workflow 层级
 
@@ -82,7 +82,7 @@ loop-agent run-dag --dag <temp-dir>/hybrid-dag.json --init-only --canvas-path <t
 - **Defaults  caveat**：`defaults.skills` / `defaults.writePolicy` 生效。对 `cursor` / `pi` node，resolved skill 名亦由 DAG runner 映射为有界 inline `SKILL.md` instruction，审计于 `<node>/skills.json`；Pi 仍以 `noSkills` / `--no-skills` 运行，故非 Pi ResourceLoader loading。`defaults.executor`、`defaults.model`、`defaults.piBackend`、`defaults.contextProfile` 接受/保留但尚非 runtime default。runtime execution 用 node `executor` + node `complexity`；各 executor 内部自选 model。live contract 已移除 `models`；executor-specific routing 用 `executorModels`。
 - **默认无**跨 node Pi runtime reuse；各 Pi node 是独立 `executePiStep()` call。
 - **Prompt source**：每个 task 仅用一种 prompt source。v1-compatible DAG 用 inline `subtask_prompt`；markdown-backed prompt 用 canonical `subtask_prompt_markdown`。同时提供两字段、皆不提供、或用连字符 alias `subtask_prompt-markdown` 均 fail fast。
-- **Source binding / recovery**：新生成 DAG 在顶层冻结 `sourceBinding`（任务源相对路径、SHA-256、显式 `REQ/BR/AC`）。前端计划在存在显式编号时经过 `frontend-requirement-coverage-shell`；缺号会在 final design review/writer 前 fail closed。中断后重新生成完整 DAG，不要从二手摘要拼接 impl-only DAG；v3 孤立 exclusive writer 若无 `sourceBinding` 且没有只读 planner 上游，会被 strict governance 拒绝。
+- **Source binding / recovery**：新生成 DAG 在顶层冻结 `sourceBinding`（任务源相对路径、SHA-256、显式 `REQ/BR/AC`）。前端计划在存在显式编号时经过 `frontend-requirement-coverage-shell`；修订计划为 primary，只在条件分支未产生输出时 fallback 到原计划。主来源存在但缺号时仍在 writer 前 fail closed。中断后重新生成完整 DAG，不要从二手摘要拼接 impl-only DAG；v3 孤立 exclusive writer 若无 `sourceBinding` 且没有只读 planner 上游，会被 strict governance 拒绝。
 - **勿宣称 live smoke 已通过**，除非真实 `run-dag` execution 中 Pi read-only、Pi writer、显式 Cursor 或 shell node 均按 DAG 完成。
 
 可复用 template：`docs/templates/agent-dag.base.json`（model 生成 DAG 的首选 base template）、`docs/templates/agent-dag.schema.json`（JSON Schema）、`docs/templates/agent-dag.supervised-implementation.json`（supervised implementation：writeSet audit、soft/hard verify、process supervisor、repair、review verdict gate）、`docs/templates/backend-test-dag.json`（后端测试专用模板）、`docs/templates/frontend-test-dag.json`（FE-test RAG：Markdown case manifest、串行 Playwright CLI case 子节点与逐 case 证据）、`docs/templates/agent-dag-process-supervisor.prompt.md`、`docs/templates/agent-dag-review-verdict.prompt.md`、`docs/templates/agent-dag-authority-surface-audit.prompt.md`（可选 authority surface verifier；authority signal 或显式 enablement 匹配时由 `dag init-hybrid` 插入）、`examples/hybrid-loop-agent-dag.json`、`docs/templates/hybrid-dag.json`。