@tea-agent/loop-agent 0.11.0 → 0.12.0

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

@@ -0,0 +1,276 @@
+{
+  "$schema": "./agent-dag.schema.json",
+  "version": 3,
+  "title": "Backend test DAG template",
+  "runtimeContract": {
+    "schemaVersion": 1,
+    "agentRuntime": "pi-only",
+    "repairWriterProtocol": "explicit-node-v1"
+  },
+  "objective": "End-to-end backend functional testing pipeline: analyze requirements → generate functional test cases → review cases → generate pytest automation → execute pytest → retrospective with maturity rating. Covers the full chain from requirement analysis to test maturity assessment.",
+  "successCriteria": [
+    "analyze-inputs-pi returns a read-only test analysis contract covering scope, risks, and strategy",
+    "generate-backend-functional-cases-pi produces structured test cases with BE-<MODULE>-<NNN> IDs under testcase/md/",
+    "review-backend-cases-pi returns VERDICT: pass or request-revision with coverage assessment",
+    "review-backend-cases-gate-shell blocks pytest generation unless the review verdict is VERDICT: pass",
+    "generate-backend-pytest-pi converts reviewed cases into pytest code with 1:1 traceability under testcase/",
+    "execute-backend-pytest-shell runs pytest and produces HTML report under reports/",
+    "test-retrospect-pi generates retrospective report with A/B/C/D maturity rating under docs/test-reports/",
+    "Full traceability from acceptance criteria → functional test case ID → pytest function name"
+  ],
+  "globalConstraints": [
+    "Replace every REPLACE/WITH/... placeholder with concrete repo paths before execution; do not leave template placeholders in production DAG JSON.",
+    "Do not commit runtime traces under .harness/dag-runs/.",
+    "Use only existing executors: pi, shell. Pi writer nodes must set toolProfile=write.",
+    "Read-only nodes must not write repository files, including root artifacts/**.",
+    "Exclusive writer nodes must stay within declared writeSet.",
+    "Every task must explicitly declare executor; defaults.executor is schema-only and not a runtime fallback.",
+    "Functional test case IDs must use BE-<MODULE>-<NNN> format.",
+    "pytest execution must produce HTML reports under reports/.",
+    "Backend-test-dag nodes must maintain traceability from requirements to functional cases to pytest automation.",
+    "pytest automation scripts must use test_ filename prefix for pytest discovery.",
+    "generate-backend-pytest-pi must only create new test files under testcase/; modifying existing framework files (conftest.py, pytest.ini, pyproject.toml) is forbidden.",
+    "review-backend-cases-gate-shell must block pytest generation unless the review verdict is exactly VERDICT: pass.",
+    "If a target test filename already exists under testcase/, add a numeric suffix (_01, _02, ...); never overwrite or append to existing files.",
+    "execute-backend-pytest-shell must not modify test assertions or production code to make tests pass; test failures indicate potential implementation issues and must be reported honestly.",
+    "Prompt templates must not ask main session to write artifacts; node output is the artifact and runner archives it under .harness/dag-runs/.",
+    "Actual file operation paths must be macOS/Windows compatible; use / only for stable repo refs, JSON/Markdown evidence refs, and glob conventions.",
+    "Same-rank exclusive writeSet entries must be disjoint."
+  ],
+  "defaults": {
+    "executor": "pi",
+    "contextProfile": "slim",
+    "skills": [
+      "ai-engineering-context"
+    ],
+    "writePolicy": "read-only"
+  },
+  "skillsByRole": {
+    "planner": [
+      "loop-agent"
+    ],
+    "scout": [],
+    "implementer": [
+      "test-driven-development",
+      "verification-before-completion"
+    ],
+    "reviewer": [
+      "requesting-code-review",
+      "code-review-core"
+    ],
+    "verifier": [
+      "verification-before-completion",
+      "systematic-debugging"
+    ],
+    "closeout": [
+      "loop-agent",
+      "verification-before-completion"
+    ]
+  },
+  "executorModels": {
+    "pi": {
+      "LOW": "gpt-5.3-codex-spark",
+      "MED": "glm-5.2",
+      "HIGH": "gpt-5.5"
+    }
+  },
+  "tasks": [
+    {
+      "id": "analyze-inputs-pi",
+      "depends_on": [],
+      "complexity": "MED",
+      "executor": "pi",
+      "role": "planner",
+      "writePolicy": "read-only",
+      "allowedPaths": [
+        "REPLACE/WITH/SOURCE/PATH/**"
+      ],
+      "forbiddenPaths": [
+        ".harness/**",
+        "artifacts/**"
+      ],
+      "outputContract": "Structured Markdown extracting core content from source documents. No file writes.",
+      "retryPolicy": {
+        "maxAttempts": 3,
+        "backoff": "exponential",
+        "initialDelayMs": 2000,
+        "maxDelayMs": 30000,
+        "retryCategories": [
+          "timeout",
+          "network",
+          "rate-limit",
+          "unavailable"
+        ]
+      },
+      "subtask_prompt": "Read the task source materials and extract the following structured content for downstream test generation.\n\n## Required Output Sections:\n\n### 1. API Endpoints\nList all API endpoints: Method, Path, Description, Request params, Response format.\n\n### 2. Data Model\nFor each table/collection: fields, types, constraints, descriptions.\n\n### 3. Business Logic\nCore business rules, validation rules, calculation formulas.\n\n### 4. State Transitions\nState machines (e.g. order status: pending → paid → shipped → completed).\n\n### 5. Error Scenarios & Error Codes\nAll error codes, error messages, and when they occur.\n\n### 6. External Dependencies\nThird-party services, databases, message queues. Include timeout settings if documented.\n\n### 7. Acceptance Criteria\nExtract ALL acceptance criteria from 需求.md. Number them AC-001, AC-002, etc. If not explicitly listed, derive from functional requirements.\n\n### 8. Risk Areas\nHigh-risk areas requiring extra test coverage.\n\n## Conditional Sections (include ONLY if mentioned in requirements):\n- Authentication & Authorization: include ONLY if requirements mention auth mechanism (JWT, OAuth2, API Key, etc.)\n- Timeout Handling: include ONLY if requirements mention timeout configuration or degradation strategy\n- Concurrency & Idempotency: include ONLY if requirements mention concurrency, idempotency rules, or locking mechanisms\n- State Transitions: include ONLY if requirements mention business state machines\n- If not mentioned in requirements, do NOT include these sections\n\nThis output will be used directly by downstream nodes. Be thorough and structured.\nRead-only: do not modify code, docs, artifacts, or repository files."
+    },
+    {
+      "id": "generate-backend-functional-cases-pi",
+      "depends_on": [
+        "analyze-inputs-pi"
+      ],
+      "complexity": "MED",
+      "executor": "pi",
+      "role": "implementer",
+      "toolProfile": "write",
+      "writePolicy": "exclusive",
+      "writeSet": [
+        "testcase/md/**"
+      ],
+      "allowedPaths": [
+        "testcase/md/**"
+      ],
+      "forbiddenPaths": [
+        ".harness/**",
+        "artifacts/**"
+      ],
+      "outputContract": "Structured backend functional test cases in Markdown under testcase/md/. Each case uses BE-<MODULE>-<NNN> ID format.",
+      "subtask_prompt": "Based on the upstream analyze-inputs-pi output, generate structured backend functional test cases.\n\n## Output Steps (do in order):\n1. First, output a brief summary: how many modules, how many cases planned per module\n2. Then write each test case file under testcase/md/\n\n## Format Rules:\n- Each test case ID: BE-<MODULE>-<NNN> (e.g. BE-ORDER-001)\n- Each file covers one module\n- Case structure: ID, Title, Precondition, Steps, Expected Result\n- Map each case to acceptance criteria (AC-xxx)\n\n## Coverage Requirements:\n- Positive paths: happy path for each acceptance criterion\n- Negative paths: error scenarios (invalid input, not found, state violations)\n- Boundary conditions: empty input, max length, edge values\n\n## Conditional Coverage (include ONLY if mentioned in upstream analysis):\n- State transitions: include ONLY if upstream analyze-inputs-pi mentions state machine\n- Authentication scenarios: include ONLY if upstream analyze-inputs-pi mentions auth mechanism\n- Timeout scenarios: include ONLY if upstream analyze-inputs-pi mentions timeout handling\n- Concurrency scenarios: include ONLY if upstream analyze-inputs-pi mentions concurrency/idempotency rules\n- If not mentioned, do NOT generate these test cases\n\n## Constraints:\n- Stay within writeSet: testcase/md/**\n- Do NOT re-read source documents — use the upstream analyze-inputs-pi output only\n- Do not write root artifacts/**"
+    },
+    {
+      "id": "review-backend-cases-pi",
+      "depends_on": [
+        "generate-backend-functional-cases-pi"
+      ],
+      "complexity": "HIGH",
+      "executor": "pi",
+      "role": "reviewer",
+      "writePolicy": "read-only",
+      "allowedPaths": [
+        "**"
+      ],
+      "forbiddenPaths": [
+        ".harness/**",
+        "artifacts/**"
+      ],
+      "outputContract": "Plain Markdown whose first non-empty line is VERDICT: pass or VERDICT: request-revision; followed by Findings and Coverage Assessment. No file writes.",
+      "retryPolicy": {
+        "maxAttempts": 3,
+        "backoff": "exponential",
+        "initialDelayMs": 2000,
+        "maxDelayMs": 30000,
+        "retryCategories": [
+          "timeout",
+          "network",
+          "rate-limit",
+          "unavailable"
+        ]
+      },
+      "subtask_prompt_markdown": "./backend-test-dag.review-cases.prompt.md"
+    },
+    {
+      "id": "review-backend-cases-gate-shell",
+      "depends_on": [
+        "review-backend-cases-pi"
+      ],
+      "complexity": "LOW",
+      "executor": "shell",
+      "role": "verifier",
+      "writePolicy": "read-only",
+      "allowedPaths": [
+        "**"
+      ],
+      "forbiddenPaths": [
+        ".harness/**",
+        "artifacts/**"
+      ],
+      "outputContract": "Deterministic backend case review gate: exit 0 only when review-backend-cases-pi emits VERDICT: pass.",
+      "subtask_prompt": "Deterministic gate: block pytest generation unless backend case review emitted VERDICT: pass.",
+      "shell": {
+        "commands": [],
+        "verdictGate": {
+          "fromNodeId": "review-backend-cases-pi",
+          "accept": [
+            "VERDICT: pass"
+          ],
+          "label": "backend case review",
+          "lineMode": "first-verdict-line"
+        },
+        "cwd": ".",
+        "timeoutMs": 60000
+      }
+    },
+    {
+      "id": "generate-backend-pytest-pi",
+      "depends_on": [
+        "review-backend-cases-gate-shell"
+      ],
+      "complexity": "HIGH",
+      "executor": "pi",
+      "role": "implementer",
+      "toolProfile": "write",
+      "writePolicy": "exclusive",
+      "writeSet": [
+        "testcase/**/test_*.py"
+      ],
+      "allowedPaths": [
+        "testcase/**/test_*.py"
+      ],
+      "forbiddenPaths": [
+        ".harness/**",
+        "artifacts/**"
+      ],
+      "outputContract": "Pytest test files under testcase/ with 1:1 mapping to functional test case IDs. Summary lists generated files, test function count, and any skipped cases with reasons.",
+      "subtask_prompt_markdown": "./backend-test-dag.generate-pytest.prompt.md"
+    },
+    {
+      "id": "execute-backend-pytest-shell",
+      "depends_on": [
+        "generate-backend-pytest-pi"
+      ],
+      "complexity": "LOW",
+      "executor": "shell",
+      "role": "verifier",
+      "writePolicy": "read-only",
+      "allowedPaths": [
+        "**"
+      ],
+      "forbiddenPaths": [
+        ".harness/**",
+        "artifacts/**"
+      ],
+      "outputContract": "Archived pytest stdout/stderr with exit codes and HTML report path; no source or test file modifications.",
+      "subtask_prompt": "Run pytest for the backend test suite and capture results.",
+      "shell": {
+        "commands": [
+          "python -m pytest testcase/ --html=reports/backend-test-report.html -v"
+        ],
+        "verifyEvidence": {
+          "phase": "final",
+          "quota": "full",
+          "commandSource": "inline",
+          "commandCount": 1,
+          "commandLabels": [
+            "backend pytest execution"
+          ],
+          "finalFullRequired": true
+        },
+        "cwd": ".",
+        "timeoutMs": 300000
+      }
+    },
+    {
+      "id": "test-retrospect-pi",
+      "depends_on": [
+        "execute-backend-pytest-shell"
+      ],
+      "complexity": "MED",
+      "executor": "pi",
+      "role": "closeout",
+      "toolProfile": "write",
+      "writePolicy": "exclusive",
+      "writeSet": [
+        "docs/test-reports/**"
+      ],
+      "allowedPaths": [
+        "docs/test-reports/**"
+      ],
+      "forbiddenPaths": [
+        ".harness/**",
+        "artifacts/**"
+      ],
+      "outputContract": "Markdown retrospective report under docs/test-reports/ with coverage summary, review findings, pytest results, and maturity rating (A/B/C/D).",
+      "subtask_prompt_markdown": "./backend-test-dag.retrospect.prompt.md"
+    }
+  ]
+}

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

@@ -0,0 +1,125 @@
+# Backend Test DAG Retrospect Prompt Template
+
+## Purpose
+
+Use this prompt for a **test retrospective** node: `executor: "pi"`, `role: "closeout"`, `toolProfile: "write"`, `writePolicy: "exclusive"`. The closeout agent reads upstream review reports and pytest execution results, then generates a retrospective report with an objective maturity rating.
+
+Do **not** create a new executor type. This is a standard `executor: pi` writer node.
+
+## Recommended DAG Node Shape
+
+```json
+{
+  "id": "test-retrospect-pi",
+  "depends_on": ["execute-backend-pytest-shell"],
+  "complexity": "MED",
+  "executor": "pi",
+  "role": "closeout",
+  "toolProfile": "write",
+  "writePolicy": "exclusive",
+  "writeSet": ["docs/test-reports/**"],
+  "allowedPaths": ["docs/test-reports/**"],
+  "forbiddenPaths": [".harness/**", "artifacts/**"],
+  "outputContract": "Markdown retrospective report under docs/test-reports/ with coverage summary, review findings, pytest results, and maturity rating (A/B/C/D).",
+  "subtask_prompt_markdown": "./backend-test-dag.retrospect.prompt.md"
+}
+```
+
+## Prompt Body
+
+You are the Backend Test DAG **test retrospective** agent.
+
+Your job is to read upstream outputs (review report + pytest results) and generate a retrospective report with a maturity rating. Write the report under `docs/test-reports/` only. Stay within `writeSet`. Do not write root `artifacts/**`.
+
+### Output Steps (do in order)
+
+1. First, output the maturity rating on the first line: `Rating: A/B/C/D`
+2. Then write the full report under `docs/test-reports/`
+
+### Inputs
+
+1. **Review report** — `review-backend-cases-pi` output (VERDICT, findings, coverage assessment).
+2. **Pytest output** — `execute-backend-pytest-shell` stdout/stderr and exit code.
+3. **HTML report** — `reports/backend-test-report.html` (if generated).
+
+Do NOT re-read source documents. Use upstream outputs only.
+
+### Maturity Rating Criteria
+
+| Rating | Coverage | Pass Rate | Review Findings |
+|--------|----------|-----------|-----------------|
+| **A** | 100% acceptance criteria covered | 100% pytest pass | No Critical or Important findings |
+| **B** | ≥80% acceptance criteria covered | ≥90% pytest pass | Only Informational findings |
+| **C** | ≥60% acceptance criteria covered | ≥70% pytest pass | No Critical findings (Important allowed) |
+| **D** | Below C thresholds | Below C thresholds | Or any Critical finding unresolved |
+
+#### Rating Rules
+
+- **Coverage** = (acceptance criteria with ≥1 covering test case) / (total acceptance criteria) × 100%
+- **Pass rate** = (passed pytest functions) / (total non-skipped pytest functions) × 100%
+- If `review-backend-cases-pi` returned `VERDICT: request-revision` and revision was not completed, cap at **D**.
+- If pytest exit code is non-zero and >30% tests failed, cap at **D** regardless of coverage.
+- Skipped tests (`@pytest.mark.skip`) count as "not covered" for pass rate but not as failures.
+
+### Report Structure
+
+Write the report as a Markdown file named `backend-test-retrospect-<date>.md` under `docs/test-reports/`.
+
+```markdown
+# Backend Test Retrospective Report
+
+**Date:** <YYYY-MM-DD>
+**Task:** <task-id>
+**Maturity Rating:** <A|B|C|D>
+
+## 1. Test Coverage Summary
+
+| Metric | Value |
+|--------|-------|
+| Total acceptance criteria | N |
+| Covered by test cases | N (X%) |
+| Total functional test cases | N |
+| Positive path cases | N |
+| Negative path cases | N |
+| Boundary cases | N |
+
+## 2. Automation Results
+
+| Metric | Value |
+|--------|-------|
+| Total pytest functions | N |
+| Passed | N |
+| Failed | N |
+| Skipped | N |
+| Pass rate | X% |
+| Pytest exit code | N |
+
+### Failed Test Analysis
+
+| Test Case ID | Function | Failure Reason | Root Cause |
+|--------------|----------|----------------|------------|
+| ... | ... | ... | ... |
+
+## 3. Review Findings
+
+| Severity | Finding | Status |
+|----------|---------|--------|
+| Critical | ... | Resolved / Unresolved |
+| Important | ... | Resolved / Unresolved |
+| Informational | ... | Resolved / Unresolved |
+
+## 4. Maturity Rating Rationale
+
+Explain which threshold was met or missed, and why the specific rating was assigned.
+
+## 5. Recommendations
+
+- Actionable items for improving the rating in the next iteration.
+- Specific gaps to close (uncovered criteria, flaky tests, missing negative paths).
+```
+
+### Output Shape (after rating line)
+
+After the mandatory maturity rating line, provide a brief summary paragraph before writing the full report file.
+
+Do not include chain-of-thought. Do not write root `artifacts/**`.

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

@@ -0,0 +1,81 @@
+# Backend Test DAG Review Cases Prompt Template
+
+## Purpose
+
+Use this prompt for a read-only **backend test case review** node: `executor: "pi"`, `role: "reviewer"`, `writePolicy: "read-only"`. The reviewer audits generated backend functional test cases for completeness, format compliance, and traceability to source requirements. Downstream `generate-backend-pytest-pi` depends on a `VERDICT: pass` to proceed.
+
+Do **not** create `executor: reviewer`. Reviewer is a **role** on `executor: pi`.
+
+## Recommended DAG Node Shape
+
+```json
+{
+  "id": "review-backend-cases-pi",
+  "depends_on": ["generate-backend-functional-cases-pi"],
+  "complexity": "HIGH",
+  "executor": "pi",
+  "role": "reviewer",
+  "writePolicy": "read-only",
+  "allowedPaths": ["**"],
+  "forbiddenPaths": [".harness/**", "artifacts/**"],
+  "outputContract": "Plain Markdown whose first non-empty line is VERDICT: pass or VERDICT: request-revision; followed by Findings and Coverage Assessment. No file writes.",
+  "subtask_prompt_markdown": "./backend-test-dag.review-cases.prompt.md"
+}
+```
+
+## Prompt Body
+
+You are the Backend Test DAG **test case reviewer** (read-only).
+
+Your job is to audit the generated backend functional test cases for completeness, format compliance, requirement coverage, and traceability. You are **not** an implementer or test generator. Do not edit repository files, including root `artifacts/**`.
+
+### Mandatory First Line
+
+The **first non-empty line** of your response must be exactly one of:
+
+- `VERDICT: pass`
+- `VERDICT: request-revision`
+
+No preamble, heading, or blank lines before the verdict line.
+
+### Inputs to Review
+
+1. **Acceptance criteria** — from upstream `analyze-inputs-pi` output (AC-001, AC-002, ...).
+2. **Generated test cases** — files under `testcase/md/`.
+
+Do NOT re-read source documents. Use upstream outputs only.
+
+### Review Checklist
+
+| Area | Check | Severity if Missing |
+|------|-------|---------------------|
+| **ID format** | Every test case ID matches `BE-<MODULE>-<NNN>` (e.g. `BE-ORDER-001`) | Critical |
+| **Positive path coverage** | Happy-path scenarios for each acceptance criterion | Critical |
+| **Negative path coverage** | Error/exception scenarios (invalid input, not found, state violations) | Important |
+| **Boundary conditions** | Edge cases (empty input, max length, edge values) | Important |
+| **State transitions** | Illegal state changes covered | Important |
+| **Requirement traceability** | Each acceptance criterion (AC-xxx) maps to at least one test case ID | Critical |
+| **Case structure** | Each case has: ID, Title, Precondition, Steps, Expected Result | Important |
+| **No duplicate IDs** | All test case IDs are unique across files | Critical |
+
+### Conditional Coverage (check ONLY if mentioned in upstream analysis)
+
+- **Authentication coverage**: check ONLY if `analyze-inputs-pi` mentions auth mechanism (JWT, OAuth2, API Key, etc.)
+- **Timeout coverage**: check ONLY if `analyze-inputs-pi` mentions timeout handling or degradation strategy
+- If not mentioned in upstream analysis, do NOT flag as missing
+
+### Verdict Rules
+
+| Condition | Verdict |
+|-----------|---------|
+| All Critical checks pass, Important checks have no more than 2 findings | `VERDICT: pass` |
+| Any Critical check fails | `VERDICT: request-revision` |
+| More than 2 Important findings | `VERDICT: request-revision` |
+| Only Informational findings | `VERDICT: pass` (with findings listed) |
+
+### Output Shape (after verdict line)
+
+1. **Coverage Assessment** — table mapping each AC to covering test case IDs (or "uncovered").
+2. **Findings** — bullet list tagged `Critical`, `Important`, or `Informational`.
+3. **Statistics** — total case count, positive/negative/boundary breakdown, module distribution.
+4. **Required revisions** (only when `request-revision`) — numbered items for the upstream generator to fix.

package/package.json

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

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

@@ -276,6 +276,7 @@ loop-agent dag resume --run-id <run-id>                  # approve 后继续
 - Decision Gate prompt 可用 `buildDagDecisionGateEvidence()`（`src/workflows/dag/decision-evidence.ts`）做与 `dag report --json`、`docs/templates/agent-dag-report.schema.json` 对齐的只读摘要；不 mutate run state，不执行 retry/resume。
 - 仅当有意在 `.harness/dag-runs/active/` 下要 active run snapshot 时用 `run-dag --dry-run`。
 - task source 应从 `harness.json.workflowPolicy.dag.profileRouting` 与确定性 candidate `governanceProfile` 选 standard / review-gated / supervised template 时用 `dag run-task --profile auto`。无 `--profile` 仅用于旧 standard-compatible 输出；强制 template family 用 `--profile minimal|standard|reviewed|supervised`。
+- 业务专用 DAG 通过 `task.json.taskKind` 选择，不扩充 governance profile：`frontend-implementation` 选择前端实现模板，`backend-test` 选择需求分析 → 功能用例 → 评审 → pytest 生成/执行 → 复盘的后端测试模板。
 
 ### Saved Dynamic Workflow operator UX
 ```bash

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

@@ -14,6 +14,8 @@
 
 此 policy 驱动 `dag run-task --profile auto`：CLI 仍要求显式 `dag run-task`、`dag validate`、`run-dag`，但 `--profile auto` 在确定性 candidate `governanceProfile` 推断后应用 `workflowPolicy.dag.profileRouting`。生成器还会把 `outputLanguage` 写入 DagSpec，runner 在每个 Pi/Cursor 节点 prompt 中注入语言规则；代码、命令、路径、JSON 字段与 gate token 保持原样。`humanGatePolicy` 是默认人机边界声明；真实暂停仍由 DAG 节点的 `decisionGate.mode: "pause-on-human"` 与 decision envelope 触发。无 profile 的 `dag run-task <task-id>` 仍为 standard-compatible，供 legacy/review workflow。
 
+`task.json.taskKind` 负责选择业务专用模板，不扩充 governance profile：`frontend-implementation` 选择前端实现 DAG，`backend-test` 选择后端测试 DAG。后端测试链为 `analyze-inputs-pi → generate-backend-functional-cases-pi → review-backend-cases-pi → review-backend-cases-gate-shell → generate-backend-pytest-pi → execute-backend-pytest-shell → test-retrospect-pi`，治理等级仍由既有 `minimal|standard|reviewed|supervised` 规则推断。
+
 ### DAG workflow 层级
 
 | 优先级 | 入口 | 使用场景 |
@@ -42,7 +44,7 @@ loop-agent run-dag --dag <temp-dir>/hybrid-dag.json --init-only --canvas-path <t
 **v2 字段**（均可选；缺失时行为同 v1）：
 
 - 顶层：`objective`、`successCriteria`、`globalConstraints`、`defaults`、`skillsByRole`、`executorModels`
-- 每 node：`role`、`skills`、`writePolicy`、`writeSet`、`piStep`、`shell`、`outputContract`、`executor`（`pi` | `shell` | `static`）；Pi 写入节点额外声明 `toolProfile: "write"`
+- 每 node：`role`、`skills`、`writePolicy`、`writeSet`、`piStep`、`shell`、`outputContract`、`executor`（`pi` | `shell` | `static`）；Pi 写入节点额外声明 `toolProfile: "write"`；安全只读 Pi 节点可选声明 `retryPolicy`（生成器自动注入默认值）
 
 **Model 生成 DAG 的 template 卫生**：
 
@@ -75,7 +77,7 @@ loop-agent run-dag --dag <temp-dir>/hybrid-dag.json --init-only --canvas-path <t
 - **Prompt source**：每个 task 仅用一种 prompt source。v1-compatible DAG 用 inline `subtask_prompt`；markdown-backed prompt 用 canonical `subtask_prompt_markdown`。同时提供两字段、皆不提供、或用连字符 alias `subtask_prompt-markdown` 均 fail fast。
 - **勿宣称 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/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`。
+可复用 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/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`。
 
 ### Supervised implementation flow（减少 main-session intervention）
 
@@ -107,9 +109,13 @@ contract-pi → scout-src ∥ scout-tests → plan-pi → write-set-audit-pi
 
 **Verdict gate contract（`shell.verdictGate`）**：声明 `fromNodeId`、`accept[]`、可选 `label`、可选 `lineMode`。runner 展开为一条 shell command，从 injected current run directory 读 `$HARNESS_DAG_RUN_DIR/<fromNodeId>.json`，对 extracted `assistantText ?? stdout` verdict line 与 `accept[]` exact-match。默认 `lineMode` 为 `first-non-empty` 以兼容；supervised gate 用 `first-verdict-line` 选 Pi 在 preamble 或常见整行 Markdown emphasis（如 `**VERDICT: pass**`）后第一条 normalized `VERDICT:` line。勿用 `result.summary.md`、grep VERDICT、latest-active-run discovery 或 multi-command stateful gate。`--strict-governance` 对 anti-pattern fail。supervisor 仍为 `executor: pi` 上的 `role: supervisor`。
 
+**Repair artifact gate contract（`shell.repairArtifactGate`）**：声明 `fromNodeId`（supervisor artifact 节点）与 `repairNodeId`（承接修订的 Pi 修复节点）。runner **不再**按节点名（历史 `repair-cursor` / `repair-pi`）猜测 repair 节点：显式 `repairNodeId` 必须存在、直接 `depends_on` gate、且是受治理 Pi writer（`executor: pi`、`toolProfile: write`、`writePolicy: exclusive`、`allowedPaths`+`writeSet` 非空且 `writeSet` 不与 `forbiddenPaths` 冲突）。新生成的 supervised DAG 总是写入 `repairNodeId`；旧 DAG 缺失时只在能唯一、安全地推导出下游 Pi writer 时兼容，零个或多个候选、或候选不满足契约都在执行前 fail closed。validation 覆盖存在性、直接下游、writer 属性与路径边界。
+
+**Runtime contract 与 controller identity**：新生成的 DagSpec 使用 `version: 3`，并必须携带 `runtimeContract`（`schemaVersion` / `agentRuntime: "pi-only"` / `repairWriterProtocol: "explicit-node-v1"` / 可选 `minimumControllerVersion`）。v3 是旧 controller 无法忽略的解析边界；capability 与最低版本是新 controller 的执行前兼容门。`init-hybrid` 不硬编码 `minimumControllerVersion`，手写 spec 可按需 pin。每个新 run 必须解析并冻结 controller identity（package version、binary SHA-256、portable fingerprint）到 `controller-identity.json`；解析失败不创建 run。`dag report` 展示 identity 与 runtime-contract compatibility，resume 对漂移、篡改或 legacy-unpinned run 全部 fail closed；legacy run 仍可只读报告或显式 reconcile。
+
 Prompt invariant：`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`（启用时）。测试：`npx vitest run test/dag-supervised-template.test.ts test/authority-surface.test.ts`。完整叙述：`docs/agent-dag-runner.md` §「Why main-session interventions happened」。
 
-**未实现**：`executor: supervisor`、automatic retry/resume、`executor: human`/`decision`、browser executor，或 read-only node 对 root `artifacts/**` 的 exemption。
+**未实现**：`executor: supervisor`、whole-run automatic retry/resume、`executor: human`/`decision`、browser executor，或 read-only node 对 root `artifacts/**` 的 exemption。注：有界只读 Pi 节点重试已实现（见下「只读 Pi 节点安全重试」）。
 
 ### Level 3 task-to-DAG（`dag init-hybrid` / `dag run-task`）
 
@@ -179,6 +185,19 @@ loop-agent dag resume --run-id <run-id>   # approve 后继续
 
 **In-flight DAG run 期间的 governance**：live run 内 shell verify node 须用 `HARNESS_ALLOW_ACTIVE_DAG_RUNS=1 bash scripts/check-repo.sh`。run 归档到 `completed/` 后，在 DAG 外跑裸 `bash scripts/check-repo.sh`。
 
+### 只读 Pi 节点安全重试（read-only retry）
+
+planner/scout/reviewer/verifier/closeout 角色的安全只读 Pi 节点可声明 `retryPolicy`，在同一 run 内有界重试模型连接中断、provider 限流、临时不可用或请求 timeout。生成模板自动注入默认策略（总尝试 3 次，手工配置最多 5 次，指数退避，单次等待上限 30s）。supervisor 与 implementer 明确不重试。
+
+- 仅重试原始分类：`timeout`、`network`、`rate-limit`、`unavailable`。`quota` **不**是 rate limit，不重试；`auth`、`invalid-output`、`write-guard`、`decision-envelope` 与未知失败同样不重试。
+- 资格由确定性 helper 判断，executor 内不硬编码循环；仅 `writePolicy=read-only|none`（或 Pi 默认只读）的上述角色可用。supervisor / implementer / writer / docs-only / dynamic / shell / static / decision-gate 节点声明 `retryPolicy` 会在 DAG validation 阶段失败。
+- 每次 attempt 写入独立不可变证据 `<node-id>/attempt-<n>.json`（run-relative path），最终 node record `attempts` 字段引用完整历史；后一次成功不覆盖前一次失败证据。
+- 重试复用同一 run、controller identity、skill snapshot、prompt、model 与上游输入；退避等待刷新 `lastActivityAt` 避免误判 node-quiet。
+- 节点终态聚合全部 attempts 的耗时、Token 与事件数；当前 backoff 等待会占用该节点的并发槽。
+- 未声明 `retryPolicy` 的历史 DAG 行为不变（单次执行，不新增 attempt artifact）。
+
+实现：`src/workflows/dag/retry-policy.ts`、`node-execution.ts`、`validate.ts`。测试：`npx vitest run test/dag-node-retry.test.ts test/dag-validate.test.ts test/dag-init-hybrid.test.ts`。
+
 ### Evidence summary guidance（practice convention — 非 runtime）
 
 review-heavy DAG 中长 shell stdout 可能掩盖 proof 时，用 **evidence-summary-shell** 作为 authoring pattern。**不是** runtime executor、schema field 或 parser。

package/skills/loop-agent/references/verification-and-failure-handling.md

@@ -72,6 +72,12 @@ product-line taxonomy 的事实源是 `docs/design/state-and-failure-taxonomy.md
 - 独立 audit 报告用 `handoff coverage <task-id> [--json|--markdown]`。
 - task status、source/artifacts、DAG outcome、verification 记录可能 drift 时用 `dag reconcile-tasks --glob '<pattern>' [--json|--markdown]`。默认仅报告；`--patch` 不能伪造 verification evidence。
 
+### supervised repair gate 与 runtime contract 失败
+
+- `repair artifact gate failed: ... no unique governed Pi writer` / `declares repairNodeId "..." but no task with that id exists`：DagSpec 的 `shell.repairArtifactGate` 未声明 `repairNodeId`，或声明的修复节点缺失、不是 gate 直接下游、不是受治理 Pi writer（`executor: pi`、`toolProfile: write`、`writePolicy: exclusive`、`allowedPaths`/`writeSet` 非空且不与 `forbiddenPaths` 冲突）。用当前 controller 重新生成 supervised DAG，或按上述契约补齐修复节点，不要靠改节点名绕过。
+- `incompatible DAG runtime contract` / `runtime contract requires ...`：DagSpec 的 `runtimeContract` 要求的能力超出当前 controller。升级 controller 或用当前 controller 重新生成 DAG；该 preflight 在任何节点执行前失败，不会留下半执行的 run。
+- `controller identity drifted` / `artifact was tampered with`：resume 时的 controller 与 run 创建时冻结的 identity 不一致（package 内容、binary 或 fingerprint 变化），或 `controller-identity.json` 被篡改。启动新 run，而不是在漂移后 resume；completed run facts 保持只读。
+
 ### Verify 默认保存进度
 `verify` 成功后，loop-agent 默认：