@tea-agent/loop-agent 0.27.1 → 0.28.0

package/docs/templates/frontend-test-dag.json

@@ -11,19 +11,46 @@
   "globalConstraints": [
     "Do not generate pytest or Playwright source code.",
     "Only use declared isolated test environments; production URLs and real credentials are blocked.",
-    "Every generated browser start command is playwright-cli open --browser=chrome --headed <resolved-base-url> (from task source config.md when present, else http://localhost:5173); subsequent commands stay in that default session and must not use unverified named-session flags.",
+    "Every generated browser start command uses playwright-cli open --browser=chrome --headed followed by the concrete controller-resolved URL (from task source config.md when present, else http://localhost:5173); executable case lines never retain an angle-bracket URL/ref placeholder; subsequent commands stay in that default session and must not use unverified named-session flags.",
     "Case children execute serially. Persist each case result, logs and browser evidence before the next child starts.",
     "A token threshold is a post-case stop check, not a model hard token cap; unstarted cases must be recorded as blocked: token-budget-exhausted.",
     "Default pipeline acceptance is the final retrospect report under testcase/frontend/reports/; case full green is optional quality (frontendTest.strictOutcomeGate).",
     "Default frontendTest.reviewMode=off uses mechanical checklist-shell before materialize; set reviewMode=blocking for legacy dual LLM review gate.",
     "playwright-cli-only: generators and executors may call only skill-declared playwright-cli commands; bare playwright / npx playwright / @playwright/test / Playwright source are forbidden with no native Playwright fallback.",
+    "Browser-tool preflight (preflight-frontend-browser-tool-shell) must reject CODE_AGENT_PI_BACKEND=cli-only, verify the Pi SDK structured custom-tool surface, freeze baseUrl from hash-bound task source config.md (or controller default localhost), and confirm the verified playwright-cli launcher + --help contract before any frontend-test Pi node; missing capability/CLI fails with zero Pi calls.",
+    "Case executors use structured playwright_cli custom tool under commandPolicy capability-allowlist; ordinary writers stay without Bash.",
+    "File outputs use canonical --filename: playwright-cli screenshot --filename final.png (a real target/ref may precede it), playwright-cli pdf --filename final.pdf, and playwright-cli snapshot --filename snapshot.txt only when a snapshot file is needed; a snapshot without filename is response-only. Never use --path, --output, --file, or an output path as a positional target.",
+    "Passed cases require same-child ordered controller receipts: successful open → successful find → successful post-execution cleanup. Pre-start cleanup, snapshot/goto/screenshot/request/console, and ordinary interactions cannot establish passed authority; model prose cannot fake green.",
     "Environment preflight must curl-probe the frozen non-production baseUrl before generate; unreachable or curl-unavailable ends preflight as blocked (frontend-base-url-unreachable|curl-unavailable) so generate/map do not run.",
     "U/D cases must prove current-user data ownership or create cleanable current-user data or authorized Mock; otherwise blocked (current-user-data-unavailable|data-ownership-unverifiable|safe-test-data-setup-unavailable) without cross-user mutation."
   ],
   "tasks": [
     {
-      "id": "retrieve-frontend-test-context-pi",
+      "id": "preflight-frontend-browser-tool-shell",
       "depends_on": [],
+      "executor": "shell",
+      "role": "verifier",
+      "complexity": "LOW",
+      "writePolicy": "read-only",
+      "allowedPaths": [],
+      "forbiddenPaths": [
+        ".harness/**",
+        "artifacts/**"
+      ],
+      "outputContract": "Deterministic SDK-only browser-tool preflight before any frontend-test Pi node; freeze a controller-owned origin and fail closed with browser-command-capability-unavailable | playwright-cli-unavailable | playwright-cli-contract-incompatible.",
+      "subtask_prompt": "Reject cli-only rollback, verify the Pi SDK structured custom-tool capability, freeze baseUrl from controller-owned task source/default, and verify the controller-resolved playwright-cli launcher plus --help lists open/close/find/snapshot/click. Do not install packages. Do not start a browser session.",
+      "shell": {
+        "commands": [],
+        "frontendBrowserToolPreflight": {},
+        "cwd": ".",
+        "timeoutMs": 60000
+      }
+    },
+    {
+      "id": "retrieve-frontend-test-context-pi",
+      "depends_on": [
+        "preflight-frontend-browser-tool-shell"
+      ],
       "executor": "pi",
       "role": "planner",
       "toolProfile": "write",
@@ -83,7 +110,9 @@
       "complexity": "HIGH",
       "writePolicy": "exclusive",
       "writeSet": [
-        "testcase/frontend/cases/**"
+        "testcase/frontend/cases/FE-*.md",
+        "testcase/frontend/cases/index.md",
+        "testcase/frontend/cases/manifest.draft.json"
       ],
       "allowedPaths": [
         "testcase/frontend/rag/**",
@@ -93,7 +122,7 @@
         ".harness/**",
         "artifacts/**"
       ],
-      "outputContract": "Markdown cases, index.md and manifest.draft.json schemaVersion 1; materialize promotes the validated draft to manifest.json; no test source code.",
+      "outputContract": "Markdown cases, index.md and manifest.draft.json schemaVersion 1 only; the exclusive materializer promotes the validated draft to manifest.json, and this generator must not write manifest.json; no test source code.",
       "subtask_prompt_markdown": "./frontend-test-dag.generate-cases.prompt.md"
     },
     {
@@ -161,7 +190,9 @@
       "complexity": "HIGH",
       "writePolicy": "exclusive",
       "writeSet": [
-        "testcase/frontend/cases/**"
+        "testcase/frontend/cases/FE-*.md",
+        "testcase/frontend/cases/index.md",
+        "testcase/frontend/cases/manifest.draft.json"
       ],
       "allowedPaths": [
         "testcase/frontend/rag/**",
@@ -171,8 +202,8 @@
         ".harness/**",
         "artifacts/**"
       ],
-      "outputContract": "Apply the one permitted frontend case revision; no browser execution or evidence writes.",
-      "subtask_prompt": "Apply the sole allowed case revision from the first review. Change only testcase/frontend/cases/**; preserve AC traceability. Do not execute browsers or write evidence."
+      "outputContract": "Apply the one permitted frontend case revision to FE-*.md, index.md, and manifest.draft.json only; must not write manifest.json; no browser execution or evidence writes.",
+      "subtask_prompt": "Apply the sole allowed case revision from the first review. Change only testcase/frontend/cases/FE-*.md, testcase/frontend/cases/index.md, and testcase/frontend/cases/manifest.draft.json; preserve AC traceability. Do not write manifest.json, execute browsers, or write evidence."
     },
     {
       "id": "review-frontend-cases-final-pi",
@@ -250,8 +281,8 @@
         ".harness/**",
         "artifacts/**"
       ],
-      "outputContract": "Mechanical checklist: manifest/case paths, Case ID, non-production playwright-cli open prefix, and AC mapping; strongly recommend playwright-cli without blocking alternative executable tool commands.",
-      "subtask_prompt": "Run the native deterministic frontend case checklist without spawning Bash, PowerShell, or node -e.",
+      "outputContract": "Mechanical checklist: manifest/case paths, Case ID, non-production playwright-cli open prefix, AC mapping, and executable command gate; rejects alternative executable instructions and non-allowlisted playwright-cli commands with ruleId-tagged location evidence.",
+      "subtask_prompt": "Inspect and reject alternative executable instructions in fenced command code, list/indented steps, and explicit shell/terminal command lines. Only allowlisted playwright-cli command instructions may pass; ordinary prose and explicit blocked reasons may describe prohibitions. Run the native deterministic frontend case checklist without spawning Bash, PowerShell, or node -e.",
       "shell": {
         "commands": [],
         "frontendTestCaseChecklist": {},
@@ -267,7 +298,10 @@
       "executor": "shell",
       "role": "verifier",
       "complexity": "LOW",
-      "writePolicy": "read-only",
+      "writePolicy": "exclusive",
+      "writeSet": [
+        "testcase/frontend/cases/**"
+      ],
       "allowedPaths": [
         "testcase/frontend/cases/**"
       ],
@@ -275,11 +309,11 @@
         ".harness/**",
         "artifacts/**"
       ],
-      "outputContract": "Validated frontend manifest payload { cases: [...] }; ruleId-tagged fail-closed validation; atomically materialize testcase/frontend/cases/manifest.json via temp+rename then delete draft; stdout is exactly one final JSON line {cases}.",
-      "subtask_prompt": "Validate and materialize the generated frontend case manifest.",
+      "outputContract": "Validated frontend manifest payload { cases: [...] }; ruleId-tagged fail-closed validation of manifest.draft.json; the exclusive materializer atomically writes testcase/frontend/cases/manifest.json via temp+rename then deletes draft; stdout is exactly one final JSON line {cases}.",
+      "subtask_prompt": "Read and validate only manifest.draft.json after the mechanical checklist passes. Normalize its case payload, atomically materialize manifest.json, then delete the draft. Do not consume a generator-authored manifest.json.",
       "shell": {
         "commands": [
-          "node -e \"const fs=require('fs'),path=require('path');const file='testcase/frontend/cases/manifest.json';if(!fs.existsSync(file))throw new Error('missing '+file);const manifest=JSON.parse(fs.readFileSync(file,'utf8'));if(manifest.schemaVersion!==1||!Array.isArray(manifest.cases))throw new Error('invalid frontend case manifest');const dims=new Set(['core','boundary','flow','backend']);const ids=new Set(),paths=new Set(),evidence=new Set();for(const c of manifest.cases){if(!c||typeof c.caseId!=='string'||!/^FE-[A-Za-z0-9][A-Za-z0-9-]*$/.test(c.caseId)||ids.has(c.caseId))throw new Error('invalid or duplicate caseId');ids.add(c.caseId);if(!dims.has(c.dimension))throw new Error('invalid dimension');if(!Array.isArray(c.acIds)||!c.acIds.length||c.acIds.some(a=>typeof a!=='string'||!a.trim()))throw new Error('invalid acIds');for(const key of ['casePath','evidenceDir']){const value=c[key];if(typeof value!=='string'||path.isAbsolute(value)||value.includes('..'))throw new Error('unsafe '+key);}if(c.casePath!=='testcase/frontend/cases/'+c.caseId+'.md')throw new Error('casePath must match caseId');if(!c.evidenceDir.startsWith('testcase/frontend/evidence/'+c.caseId+'/'))throw new Error('case path escapes frontend test roots');if(paths.has(c.casePath))throw new Error('duplicate casePath');paths.add(c.casePath);if(evidence.has(c.evidenceDir))throw new Error('duplicate evidenceDir');evidence.add(c.evidenceDir);}process.stdout.write(JSON.stringify({cases:manifest.cases}));\""
+          "node -e \"const fs=require('fs'),path=require('path');function fail(ruleId,detail){throw new Error('frontend-test manifest blocked: '+ruleId+(detail?': '+detail:''));}const draft='testcase/frontend/cases/manifest.draft.json',file='testcase/frontend/cases/manifest.json',tmp=file+'.tmp';if(!fs.existsSync(draft))fail('draft-missing','missing '+draft);let manifest;try{manifest=JSON.parse(fs.readFileSync(draft,'utf8'));}catch(error){fail('draft-invalid-json',error.message);}if(manifest.schemaVersion!==1)fail('draft-schema','schemaVersion must be 1');if(!Array.isArray(manifest.cases)||!manifest.cases.length)fail('draft-empty-cases','cases must be a non-empty array');const dims=new Set(['core','boundary','flow','backend']),ids=new Set(),paths=new Set(),evidence=new Set();const cases=manifest.cases.map(c=>{if(!c||typeof c.caseId!=='string'||!/^FE-[A-Za-z0-9][A-Za-z0-9-]*$/.test(c.caseId)||ids.has(c.caseId))fail('case-id-shape','invalid or duplicate caseId');ids.add(c.caseId);if(!dims.has(c.dimension))fail('invalid-dimension',String(c.dimension));if(!Array.isArray(c.acIds)||!c.acIds.length||c.acIds.some(a=>typeof a!=='string'||!a.trim()))fail('ac-mapping','invalid acIds');const casePath='testcase/frontend/cases/'+c.caseId+'.md',evidenceDir='testcase/frontend/evidence/'+c.caseId+'/';if(path.isAbsolute(casePath)||casePath.includes('..')||!fs.existsSync(casePath))fail('case-file-missing',casePath);if(paths.has(casePath))fail('duplicate-case-path',casePath);paths.add(casePath);if(evidence.has(evidenceDir))fail('duplicate-evidence-dir',evidenceDir);evidence.add(evidenceDir);return {caseId:c.caseId,casePath,dimension:c.dimension,acIds:[...c.acIds],evidenceDir};});fs.writeFileSync(tmp,JSON.stringify({schemaVersion:1,cases},null,2)+'\\n');fs.renameSync(tmp,file);fs.unlinkSync(draft);process.stdout.write(JSON.stringify({cases}));\""
         ],
         "cwd": ".",
         "timeoutMs": 120000
@@ -323,9 +357,15 @@
             "playwright-cli"
           ],
           "toolProfile": "write",
+          "commandPolicy": {
+            "mode": "capability-allowlist",
+            "capabilities": [
+              "playwright-cli"
+            ]
+          },
           "complexity": "MED",
-          "subtaskPromptTemplate": "Primary job: EXECUTE {{case.caseId}} from {{case.casePath}} with skill playwright-cli (fresh Pi session). 1) Read baseUrl from testcase/frontend/rag/context.md (config.md preferred, else http://localhost:5173). 2) playwright-cli open --browser=chrome --headed <resolved-base-url> (default session; no -s=). 3) Follow case steps with snapshot before element refs. 4) If env/CLI/baseUrl missing, write blocked evidence and do not open a browser. Always persist {{case.evidenceDir}}execution.md and {{case.evidenceDir}}case-result.json (caseId, status passed|failed|blocked, evidencePaths; blocked needs blockedReason). Validate with node -e before return. Business failed/blocked is not a node failure. Close browser. Return compact JSON (<=1200 chars): {caseId,status,evidencePaths,errorSummary,tokens}.",
-          "outputContract": "Compact JSON <=1200 chars.",
+          "subtaskPromptTemplate": "Primary job: EXECUTE {{case.caseId}} from {{case.casePath}} with skill playwright-cli (fresh Pi session). Use the structured playwright_cli tool for every browser action. Do not request or search for bash. Translate each playwright-cli line in the case Markdown into one playwright_cli tool call. The controller-owned browser capability freezes baseUrl from hash-bound task source config.md or the localhost default; context/case prose may reference but cannot establish or override that origin. Start only with playwright_cli command=open and controller-injected concrete frozen URL args (default session; no -s=). Dynamic refs: literal eX/eY are documentation placeholders, not tool args. Immediately before every structured playwright_cli call that references an element, parse the actual eNN from the immediately preceding latest snapshot and pass only that actual eNN. Never send literal eX/eY, and never reuse a stale ref after a new snapshot. File outputs are canonical: screenshot uses [--filename, final.png] (or [e5, --filename, final.png] only for a real target), pdf uses [--filename, final.pdf], and snapshot writes a file only with [--filename, snapshot.txt]; snapshot without filename is response-only. Never use --path, --output, --file, or an output path as a positional target. Passed authority requires same-child ordered controller receipts: successful open → successful find → successful post-execution cleanup. Only successful find is meaningful; snapshot, goto, screenshot, request/console, and ordinary interactions cannot establish passed. Only when preflight or playwright_cli tool explicitly fails may you write blocked evidence. Always persist {{case.evidenceDir}}execution.md and {{case.evidenceDir}}case-result.json (caseId, status passed|failed|blocked, evidencePaths; blocked needs blockedReason). Business failed/blocked is not a node failure. Close via playwright_cli command=close. Return compact JSON (<=1200 chars): {caseId,status,evidencePaths,errorSummary,tokens}.",
+          "outputContract": "Compact JSON <=1200 chars. Browser actions must use structured playwright_cli tool.",
           "writePolicy": "exclusive",
           "allowedPaths": [
             "testcase/frontend/cases/{{case.caseId}}.md",

package/docs/templates/frontend-test-dag.retrieve-context.prompt.md

@@ -2,16 +2,14 @@
 
 Write only `testcase/frontend/rag/context.md` and `coverage-map.md`. Record traceable facts from the task source, routes, components, API/Mock contracts, existing tests and execution contract. Do not invent fields, credentials, limits or test data.
 
-## Base URL resolution (required)
+## Controller-frozen Base URL (required)
 
-Resolve a single absolute browser base URL and record it explicitly in `context.md` (both a human-readable `base URL` line and a machine-readable `baseUrl: <url>` line):
+The preflight controller resolves and freezes one absolute browser base URL from hash-bound task source `config.md` (or the controller default `http://localhost:5173`) before this Pi node runs. Copy that supplied value and source exactly into `context.md` as `baseUrl: <url>` and `baseUrlSource: <source>`.
 
-1. Prefer frontend URL facts from task source `config.md` (including `source/references/**/config.md` or any attached reference named `config.md`): keys such as `baseUrl`, `base_url`, `frontendBaseUrl`, `FRONTEND_BASE_URL`, `url`, or labeled frontend base URL text.
-2. If no usable absolute `http://` / `https://` URL is found in `config.md` (or equivalent source facts), default to `http://localhost:5173`.
-3. Never use production hosts. Prefer local / isolated non-production URLs.
-4. Also record `baseUrlSource: config.md|<path>` or `baseUrlSource: default-localhost-5173` so later nodes can audit the choice.
-5. Write `environmentProbe: pending`. The environment preflight shell will replace this with `reachable`, `unreachable`, or `curl-unavailable` plus a structured `blockedReason` (for example `frontend-base-url-unreachable`).
-6. Include the exact browser start prefix that generators must copy:
-   `playwright-cli open --browser=chrome --headed <resolved-base-url>`.
+- Do not derive, replace, or override the origin from model reasoning, route text, case prose, existing RAG files, or other repository content.
+- Never use production hosts or credentials.
+- Write `environmentProbe: pending`. The environment preflight shell will replace this with `reachable`, `unreachable`, or `curl-unavailable` plus a structured `blockedReason` (for example `frontend-base-url-unreachable`).
+- Include the exact browser start prefix using the supplied controller-frozen URL:
+  `playwright-cli open --browser=chrome --headed <controller-frozen-base-url>`.
 
 Do not claim the environment is reachable until preflight completes. Preflight does not start the application.

package/docs/templates/frontend-test-dag.retrospect.prompt.md

@@ -2,4 +2,4 @@
 
 Write a dated report under `testcase/frontend/reports/` (for example `frontend-test-retrospect-<date>.md`) after `frontend-test-result-v1` materialization. Do **not** require outcome=pass; failed, incomplete, and blocked runs still need a report.
 
-Combine a short AC → case → browser-evidence review with the closeout: case coverage, passed/failed/blocked results (including `token-budget-exhausted`), evidence gaps, browser anomalies, residual risks, and an A/B/C/D maturity rating. Cite the deterministic case-evidence validation outcome. Passed cases should reference assertion plus screenshot or equivalent browser evidence when available; failed/blocked cases need explicit reasons. Blocked cases never count as passed; a missing or malformed `execution.md` / `case-result.json` is a verification gap, not a pass. Do not write under `docs/**`.
+Combine a short AC → case → browser-evidence review with the closeout: case coverage, passed/failed/blocked results (including `token-budget-exhausted`), evidence gaps, browser anomalies, residual risks, and an A/B/C/D maturity rating. Cite the deterministic case-evidence validation outcome. Passed cases should reference the successful `find` assertion plus screenshot or equivalent browser evidence and the ordered post-execution cleanup receipt when available; failed/blocked cases need explicit reasons. Blocked cases never count as passed; a missing or malformed `execution.md` / `case-result.json` is a verification gap, not a pass. Do not write under `docs/**`.

package/docs/templates/frontend-test-dag.review-cases.prompt.md

@@ -2,4 +2,4 @@
 
 Read the RAG files and Markdown cases only. First line must be `VERDICT: pass` or `VERDICT: request-revision`. Report AC coverage, case independence, evidence completeness, unsafe environment/data dependencies, and manifest issues. This verdict is a deterministic safety gate: `request-revision` blocks manifest materialization and browser execution.
 
-Every case must retain the exact browser-start command prefix with the resolved absolute baseUrl from `testcase/frontend/rag/context.md` (prefer task source `config.md`, else `http://localhost:5173`): `playwright-cli open --browser=chrome --headed <resolved-base-url>`; session flags must not precede `open`, and subsequent commands must remain in its default session without `-s=` or assumed named-session binding. Verify every executable sub-scenario specifies fixture/reset, UI reset, fresh snapshot before element refs, and an evidence write point. Verify each case requires both `execution.md` and `case-result.json` under its own evidence directory. The JSON result must contain matching `caseId`, `status` (`passed`, `failed`, or `blocked`) and `evidencePaths`; blocked cases must name a non-empty `blockedReason` and cannot count as passed.
+Every case must retain the exact browser-start command prefix with the resolved absolute baseUrl from `testcase/frontend/rag/context.md` (prefer task source `config.md`, else `http://localhost:5173`): `playwright-cli open --browser=chrome --headed <resolved-base-url>`; session flags must not precede `open`, and subsequent commands must remain in its default session without `-s=` or assumed named-session binding. Verify every executable sub-scenario specifies fixture/reset, UI reset, fresh snapshot before element refs, a successful `playwright-cli find ...` semantic assertion after `open`, and an evidence write point. `snapshot`, `goto`, `screenshot`, `request`/`console`, and ordinary interactions cannot independently authorize passed. Verify each case requires both `execution.md` and `case-result.json` under its own evidence directory. The JSON result must contain matching `caseId`, `status` (`passed`, `failed`, or `blocked`) and `evidencePaths`; blocked cases must name a non-empty `blockedReason` and cannot count as passed.

package/docs/templates/frontend-test-dag.review-execution.prompt.md

@@ -1,3 +1,3 @@
 # Review frontend execution evidence
 
-Review AC → case → browser-evidence traceability only after deterministic evidence validation. Each manifest case must have `execution.md` and a valid `case-result.json` with matching `caseId`, `status`, and `evidencePaths`; `blocked` requires a non-empty `blockedReason`. A passed case additionally needs assertions and screenshot or equivalent browser evidence. Failed and blocked cases need an explicit cause. Treat `token-budget-exhausted` as blocked; do not substitute model conclusions or static checks for browser evidence.
+Review AC → case → browser-evidence traceability only after deterministic evidence validation. Each manifest case must have `execution.md` and a valid `case-result.json` with matching `caseId`, `status`, and `evidencePaths`; `blocked` requires a non-empty `blockedReason`. A passed case additionally needs a successful `find` semantic assertion, screenshot or equivalent browser evidence, and same-child ordered controller-owned `playwright-cli` receipts: successful `open` → successful `find` → successful `post-execution` cleanup. `pre-start` cleanup, snapshot/goto/screenshot/request/console, and ordinary interactions cannot satisfy this gate. Failed and blocked cases need an explicit cause. Treat `token-budget-exhausted` and `browser-command-evidence-missing` as blocked; do not substitute model conclusions or static checks for browser evidence.

package/harness.json

@@ -59,7 +59,7 @@
     "pi": {
       "description": "Pi planning, review, diagnosis, and bounded writing when DAG toolProfile=write",
       "LOW": "minimax-m3",
-      "MED": "grok-4.5",
+      "MED": "gpt-5.6-terra",
       "HIGH": "gpt-5.6-sol"
     }
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tea-agent/loop-agent",
-  "version": "0.27.1",
+  "version": "0.28.0",
   "type": "module",
   "bin": {
     "loop-agent": "bin/loop-agent.js",

package/skills/loop-agent/SKILL.md

@@ -64,7 +64,7 @@ loop-agent task status <task-id> --json
 6. 主会话不绕过 CLI 直接写业务代码；失败只走 doctor/reconcile/human gate/重跑。
 7. DAG `pi` executor read-only unless `toolProfile: "write"`；completed run facts read-only；不得从 read-only DAG/sidecar 写 root `artifacts/`。
 8. No hidden state in chat only；verify before completion.
-9. Client recovery：`init --client-recovery=auto|project|user|off`；只有 `user` 写 Pi settings；check/update 遵守 ownership。
+9. Client recovery：`init --client-recovery=auto|project|user|off` 投影 transient-retry + overflow-compact + Pi overflow extension；只有 `user` 写 Pi settings；overflow 与 transient 职责分离；check/update 遵守 ownership。
 
 ## References
 

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

@@ -221,8 +221,18 @@ loop-agent --repo-root /path/to/target-repo study init <task-id> "Title" \
   --reference-doc plan:/Users/mac/plans/codex-goal-feature.md \
   --reference-glob "codex-rs/**/goal*.rs"
 
-# 编辑 source/需求.md + source/执行约束.md，然后走 DAG 路径：
+# 编辑 source/需求.md + source/执行约束.md，然后按标准 task lifecycle 推进：
 loop-agent --repo-root <target-repo> task advance <task-id> --profile auto --dag-output .harness/tasks/<task-id>/dag.json --json
+# 审查 writeSet gate 后，继续同一任务：
+loop-agent --repo-root <target-repo> task advance <task-id> --approve-gate "write-set-review:<digest>" --json
+loop-agent --repo-root <target-repo> task status <task-id> --json
+```
+
+`task advance` 会生成并 strict validate 任务 DAG；`--dag-output` 只用于导出可审阅草稿，不要求再把 `dag validate` 或 `dag execute` 当作标准任务的下一步。
+
+仅当有意把导出的 JSON 当作**独立的 advanced arbitrary DagSpec** 排查或执行时，才使用以下高级入口；它们不替代上述标准 task lifecycle：
+
+```bash
 loop-agent --repo-root <target-repo> dag validate --dag .harness/tasks/<task-id>/dag.json --strict-models --strict-governance
 loop-agent --repo-root <target-repo> dag execute --dag .harness/tasks/<task-id>/dag.json --cwd <target-repo>
 ```
@@ -239,7 +249,7 @@ loop-agent --repo-root <target-repo> dag execute --dag .harness/tasks/<task-id>/
 loop-agent reference index <task-id>
 ```
 
-`reference` 是 compatibility / feature-study 辅助入口，用于维护或检查参考资料索引。常规实现任务不要从 `reference` 起步；按 `new-task` + DAG 路径执行。
+`reference` 是 compatibility / feature-study 辅助入口，用于维护或检查参考资料索引。常规实现任务不要从 `reference` 起步；使用 `task advance` 推进同一任务，并用 `task status` 做只读状态确认。
 
 ### Task goal lifecycle（compatibility-only / deprecated-candidate）
 
@@ -264,7 +274,9 @@ loop-agent goal clear <task-id>
   - 用于保持 continuation 行为一致，减少聊天式历史噪音
   - preflight 含 state/mode guard + 启动前 goal 一致性复检
 
-### Agent DAG validation 与 execution
+### Advanced arbitrary DagSpec validation 与 execution
+
+以下 `dag validate`、`dag execute`、`dag report` 与相关 run-level 命令是 **advanced arbitrary DagSpec / forensic** surface，适用于手写或显式导出的独立 DAG、诊断与证据审阅。它们不创建标准 task lifecycle，也不取代标准 mutation 的 `task advance` 或只读状态查询的 `task status`。
 
 ```bash
 loop-agent dag validate --dag <temp-dir>/hybrid-dag.json                 # 常规 validation；无 .harness/dag-runs 副作用
@@ -278,7 +290,7 @@ cp ai_workspace/loop-agent/templates/agent-dag.supervised-implementation.json <t
 loop-agent dag execute --dag <temp-dir>/hybrid-dag.json --cwd <repo-root>     # advanced arbitrary DagSpec；stderr 默认输出节点进度与 30s 心跳，stdout 保持最终 JSON
 loop-agent dag execute --dag <temp-dir>/hybrid-dag.json --cwd <repo-root> --progress-interval-ms 60000 # 调整心跳；--quiet 可禁用
 loop-agent dag execute --dag <temp-dir>/hybrid-dag.json --init-only --canvas-path <temp-dir>/hybrid-dag.canvas.tsx # 可选 derived Canvas view
-bash scripts/dag execute-safe.sh --dag <temp-dir>/hybrid-dag.json --cwd <repo-root> [--timeout-secs 7200]  # 后台运行 + 轮询，避免外层 bash timeout 杀进程（见 agent-dag-runner.md §Adaptive liveness）
+bash scripts/run-dag-safe.sh --dag <temp-dir>/hybrid-dag.json --cwd <repo-root> [--timeout-secs 7200]  # advanced arbitrary DagSpec 的后台运行 + 轮询，避免外层 bash timeout 杀进程（见 agent-dag-runner.md §Adaptive liveness）
 loop-agent dag init-hybrid <task-id>                     # 生成可审阅的 DAG draft
 loop-agent dag workflow-plan <task-id> --profile pr-review --output .harness/tasks/<task-id>/workflows/planned/<name>.workflow.json
 loop-agent dag workflow-validate --workflow .harness/tasks/<task-id>/workflows/planned/<name>.workflow.json --strict-governance
@@ -306,7 +318,7 @@ loop-agent dag resume --run-id <run-id>                  # approve 后继续
 
 **In-flight DAG governance**：shell verify node 内用 `HARNESS_ALLOW_ACTIVE_DAG_RUNS=1 bash scripts/check-repo.sh`；run 归档到 `completed/` 后，在 DAG 外跑裸 `bash scripts/check-repo.sh`。
 
-- `dag validate` 做 schema/topology/ranks 检查；审 `warnings` 中的显式 `executorModels` drift 与 governance lint。
+- `dag validate` 做 arbitrary DagSpec 的 schema/topology/ranks 检查；审 `warnings` 中的显式 `executorModels` drift 与 governance lint。它不替代 `task advance` 的标准任务生成与严格校验。
 - 手写临时 DAG spec 执行前用 `dag validate --strict-models`，model-matrix drift 应 fail fast。
 - read-only artifact-boundary 或 DAG 内 shell governance warning 应 fail fast 时用 `dag validate --strict-governance`。
 - 人工 handoff 视图用 `dag report --markdown`（summary、node timeline、failures、四段 Recovery Plan、artifacts、建议 next action）。仅 derived、advisory；需保存时重定向到平台临时目录或 `ai_workspace/loop-agent/reports/`。
@@ -321,7 +333,7 @@ loop-agent dag resume --run-id <run-id>                  # approve 后继续
 - 大型 PRD closeout 用 `dag final-verification <task-id>` 生成确定性 DAG，final verification 在 closeout artifact 创建之后。
 - 从 run facts dry-run envelope 解析用 `dag decision inspect|validate`；`validate` 在无效 envelope 时 exit 1；永不自动 resume/retry。
 - Decision Gate prompt 可用 `buildDagDecisionGateEvidence()`（`src/workflows/dag/decision-evidence.ts`）做与 `dag report --json`、`ai_workspace/loop-agent/templates/agent-dag-report.schema.json` 对齐的只读摘要；不 mutate run state，不执行 retry/resume。
-- 仅当有意在 `.harness/dag-runs/active/` 下要 active run snapshot 时用 `dag execute --dry-run`。
+- `dag execute --dry-run` 仅用于 advanced arbitrary DagSpec 的预演：snapshot 写入命令返回的 `runDir`（当前形态为 `.harness/dag-runs/dry-run/<runId>/`）；它不创建 active run、不出现在 active overview，也不能作为 `dag resume` 的目标。
 - task source 应从 `harness.json.workflowPolicy.dag.profileRouting` 与确定性 candidate `governanceProfile` 选择治理强度时用 `task advance --profile auto`。无 `--profile` 仅用于旧 standard-compatible 输出；`--profile minimal|standard|reviewed|supervised` 记录治理强度，不替换已识别的专用业务 workflow。
 - 默认 `standard` 任务先读取 `source/需求.md` 中的结构化任务类型，再结合 `allowedPaths` 与 React/Next/Vue 项目能力做确定性分类。确认是前端项目且任务不是明确后端、混合、排除前端或仅文档/测试范围时，自动选择 `frontend-implementation`，不依赖需求关键词；普通后端实现绝不自动进入 `backend-test`。
 - 新生成 DAG 会冻结任务源路径、SHA-256 和显式 `REQ/BR/AC` 到 `sourceBinding`。前端计划漏号时 `frontend-requirement-coverage-shell` 在 writer 前阻断。中断恢复应修复 task source 后重新运行 `task advance`，不要生成只携带上游摘要的 impl-only DAG；strict governance 会拒绝无来源绑定且无只读 planner 上游的 v3 孤立 writer。