@tea-agent/loop-agent 0.16.1-beta.2 → 0.16.2

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

@@ -2,7 +2,7 @@
 
 ## 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.
+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. A first review may return `request-revision` to drive a single `revise-backend-cases-pi` pass; **final** review (`review-backend-cases-final-pi`) must emit `VERDICT: pass` before `generate-backend-pytest-pi`.
 
 Do **not** create `executor: reviewer`. Reviewer is a **role** on `executor: pi`.
 
@@ -56,7 +56,9 @@ Do NOT re-read source documents. Use the validated analysis artifact, case manif
 | **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 (manifest coverageSummary or evidenceGaps) | Critical |
-| **Manifest consistency** | Markdown cases align with Case Manifest v1 caseId/acIds | Critical |
+| **Manifest consistency** | Markdown case bodies **and** any AC matrix list the **same full** `BE-*` ids as Case Manifest v1 `caseId`→`acIds`. Never claim "all cases" / "全部用例" cover an AC unless every case maps that AC. | Critical |
+| **Planned automation** | Missing `test_*.py` before generate-pytest is **Informational only**, not Critical | Informational |
+| **Out-of-scope ACs** | Flyway / frontend e2e / `mvn test` etc. already in manifest `evidenceGaps` must not be treated as uncovered Critical | Informational |
 | **Case structure** | Each case has: ID, Title, Precondition, Steps, Expected Result | Important |
 | **No duplicate IDs** | All test case IDs are unique across files | Critical |
 
@@ -77,7 +79,11 @@ Do NOT re-read source documents. Use the validated analysis artifact, case manif
 
 ### Output Shape (after verdict line)
 
-1. **Coverage Assessment** — table mapping each AC to covering test case IDs (or "uncovered").
+1. **Coverage Assessment** — table mapping each AC to covering **full** test case IDs (or "uncovered" / gap).
 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.
+4. **Required revisions** (only when `request-revision` on the **first** review) — numbered, concrete MD edits for `revise-backend-cases-pi` (fix matrices, acIds, full BE-* ids).
+
+### Final review note
+
+When this prompt is used for `review-backend-cases-final-pi` after revision, still use the same checklist. Remaining Critical issues must yield `request-revision` (final gate will stop the DAG). Do not pass with unresolved MD↔manifest AC mismatches.

package/docs/templates/backend-test-execution.schema.json

@@ -69,7 +69,12 @@
         "additionalProperties": false,
         "required": ["path", "description"],
         "properties": {
-          "path": { "type": "string", "minLength": 1 },
+          "path": {
+            "type": "string",
+            "minLength": 1,
+            "pattern": "^/(?!/)(?!.*(?:^|/)\\.{1,2}(?:/|$))(?!.*//)(?!.*\\\\)[^?#]*$",
+            "description": "HTTP URL path on the target service for readiness probes (e.g. /api/health). Not a repository file path; must start with one /, use POSIX separators, and must not include duplicate slashes, dot segments, query, fragment, or scheme. Runtime trims surrounding whitespace before validating and materializing the normalized path."
+          },
           "description": { "type": "string", "minLength": 1 }
         }
       }

package/docs/templates/branch-merge-report.md

@@ -6,6 +6,8 @@ Target before merge: `<full SHA>`
 Source: `<source-ref>@<full SHA>`
 Merge base: `<full SHA>`
 Merge commit: `<full SHA or follow-up commit reference>`
+Merge mode: `quick | standard | deep`
+Mode rationale: `<why this mode is sufficient>`
 
 ## Naming Convention
 
@@ -18,6 +20,12 @@ Use `YYYY-MM-DD-origin-<source>-into-<target>-<source-short-sha>.md` under `docs
 - Predicted conflicts: `<count and files>`.
 - Baseline verification: `<commands and results>`.
 
+## Final Source Drift Check
+
+- Final fetch: `<command and timestamp>`.
+- Final source tip: `<full SHA>`.
+- Source advanced during work: `<no | yes, with re-audit details>`.
+
 ## Incoming Capabilities
 
 | Capability | Key files / contracts | Expected user or runtime result | Verification |
@@ -80,6 +88,12 @@ Record overlapping or high-risk files that Git merged without conflict. These ar
 
 Add focused tests and real init/update/browser/CLI smokes required by the merged capabilities.
 
+## Mode Completion Check
+
+- Required gates for selected mode: `<list>`.
+- Passed gates: `<list>`.
+- Any mode upgrade during execution: `<no | from quick/standard to standard/deep, with reason>`.
+
 ## Residual Risk
 
 - `<unverified external environment, performance, migration, or compatibility risk>`

package/docs/templates/evaluation/campaign-budget-v1.json

@@ -0,0 +1,12 @@
+{
+	"schemaVersion": 1,
+	"mode": "hard",
+	"limits": {
+		"maxTokens": 2000000,
+		"maxWallTimeMs": 86400000,
+		"maxExecutorCalls": 500,
+		"maxRepairPasses": 50,
+		"maxConcurrency": 2,
+		"maxContextChars": 120000
+	}
+}

package/docs/templates/evaluation/campaign-dogfood-v0.json

@@ -0,0 +1,24 @@
+{
+  "schemaVersion": 1,
+  "campaignId": "camp-dogfood-context-policy-ab",
+  "createdAt": "2026-07-19T00:00:00.000Z",
+  "status": "prepared",
+  "policyVersion": "promotion-policy-v1",
+  "incumbentCandidateId": "REPLACE_INCUMBENT_CANDIDATE_ID",
+  "challengerCandidateIds": ["REPLACE_CHALLENGER_CANDIDATE_ID"],
+  "corpusId": "corpus-dogfood-v0",
+  "corpusHash": "REPLACE_AFTER_CORPUS_REGISTER",
+  "privateVerifierId": "pv-dogfood-v0",
+  "privateVerifierManifestHash": "REPLACE_AFTER_PRIVATE_VERIFIER_REGISTER",
+  "budget": {
+    "schemaVersion": 1,
+    "mode": "hard",
+    "limits": {
+      "maxExecutorCalls": 500,
+      "maxWallTimeMs": 86400000,
+      "maxRepairPasses": 50,
+      "maxConcurrency": 2
+    }
+  },
+  "notes": "M4 dogfood: single-variable Context Policy A/B. Replace candidate/corpus/privateVerifier hashes after register. held_out cells are promotion_gate_only."
+}

package/docs/templates/evaluation/campaign-evidence-v1.json

@@ -0,0 +1,44 @@
+{
+  "schemaVersion": 1,
+  "campaignId": "campaign-dogfood-v0",
+  "challengerCandidateId": "cand-challenger-example",
+  "cells": [
+    {
+      "candidateId": "cand-baseline-example",
+      "taskRef": "synthetic/private-1",
+      "seed": 1,
+      "split": "private",
+      "verifyPassed": false
+    },
+    {
+      "candidateId": "cand-challenger-example",
+      "taskRef": "synthetic/private-1",
+      "seed": 1,
+      "split": "private",
+      "verifyPassed": true
+    },
+    {
+      "candidateId": "cand-baseline-example",
+      "taskRef": "synthetic/heldout-1",
+      "seed": 1,
+      "split": "held_out",
+      "verifyPassed": true
+    },
+    {
+      "candidateId": "cand-challenger-example",
+      "taskRef": "synthetic/heldout-1",
+      "seed": 1,
+      "split": "held_out",
+      "verifyPassed": true
+    }
+  ],
+  "diffs": [],
+  "verifyCommands": {
+    "incumbent": ["npm test", "npm run typecheck"],
+    "challenger": ["npm test", "npm run typecheck"]
+  },
+  "budgetStatus": {
+    "incumbent": "ok",
+    "challenger": "ok"
+  }
+}

package/docs/templates/evaluation/context-policy-baseline-v1.json

@@ -0,0 +1,17 @@
+{
+  "schemaVersion": 1,
+  "policyId": "baseline-v1",
+  "description": "Current DAG context assembly: shared upstream char budget, role skill defaults, learned patterns only for implementer.",
+  "knobs": {
+    "maxUpstreamCharsByRole": {
+      "default": 2000
+    },
+    "includeLearnedPatternsRoles": ["implementer"],
+    "perSkillMaxCharsByRole": {
+      "default": 3000
+    },
+    "totalMaxCharsByRole": {
+      "default": 12000
+    }
+  }
+}

package/docs/templates/evaluation/context-policy-role-specialized-v1.json

@@ -0,0 +1,28 @@
+{
+  "schemaVersion": 1,
+  "policyId": "role-specialized-v1",
+  "description": "Role-specialized upstream and skill-instruction budgets; skill names still resolve via baseline merge order.",
+  "knobs": {
+    "maxUpstreamCharsByRole": {
+      "default": 2000,
+      "scout": 1200,
+      "reviewer": 1200,
+      "implementer": 3000,
+      "verifier": 1600,
+      "closeout": 1600,
+      "planner": 2000,
+      "supervisor": 2000
+    },
+    "includeLearnedPatternsRoles": ["implementer", "closeout"],
+    "perSkillMaxCharsByRole": {
+      "default": 3000,
+      "scout": 2500,
+      "implementer": 3500
+    },
+    "totalMaxCharsByRole": {
+      "default": 12000,
+      "scout": 10000,
+      "implementer": 14000
+    }
+  }
+}

package/docs/templates/evaluation/corpus-dogfood-v0.manifest.json

@@ -0,0 +1,118 @@
+{
+  "schemaVersion": 1,
+  "corpusId": "corpus-dogfood-v0",
+  "createdAt": "2026-07-19T00:00:00.000Z",
+  "description": "W1.5 initial dogfood corpus contract: 15 heterogeneous tasks with public/private/held_out splits. Contract-only; not live campaign evidence.",
+  "tasks": [
+    {
+      "taskRef": "features/F-2026-001/login-flow",
+      "class": "fullstack",
+      "split": "public",
+      "seeds": [1, 2, 3],
+      "featureId": "F-2026-001",
+      "description": "Dogfood login Feature packet (public feedback allowed)."
+    },
+    {
+      "taskRef": "features/F-2026-002/profile-filter",
+      "class": "implement",
+      "split": "public",
+      "seeds": [1, 2],
+      "featureId": "F-2026-002",
+      "description": "Profile filter implementation path."
+    },
+    {
+      "taskRef": "features/F-2026-005/welcome-banner",
+      "class": "fullstack",
+      "split": "public",
+      "seeds": [1, 2, 3],
+      "featureId": "F-2026-005",
+      "description": "fullstack-v1 welcome sample (public)."
+    },
+    {
+      "taskRef": "synthetic/docs-agents-converge",
+      "class": "docs",
+      "split": "public",
+      "seeds": [1, 2],
+      "description": "Docs/AGENTS converge style task (synthetic contract slot)."
+    },
+    {
+      "taskRef": "synthetic/docs-changelog-summary",
+      "class": "docs",
+      "split": "public",
+      "seeds": [1, 2, 3],
+      "description": "Changelog-style documentation task."
+    },
+    {
+      "taskRef": "synthetic/frontend-welcome-render",
+      "class": "frontend",
+      "split": "public",
+      "seeds": [1, 2],
+      "description": "Frontend render/accessibility contract slot."
+    },
+    {
+      "taskRef": "features/F-2026-003/empty-profile-regression",
+      "class": "bugfix",
+      "split": "private",
+      "seeds": [1, 2, 3],
+      "featureId": "F-2026-003",
+      "description": "Empty profile id/displayName regression (private selection)."
+    },
+    {
+      "taskRef": "features/F-2026-004/versioned-bootstrap",
+      "class": "bootstrap",
+      "split": "private",
+      "seeds": [1, 2],
+      "featureId": "F-2026-004",
+      "description": "Versioned self-host bootstrap canary (private)."
+    },
+    {
+      "taskRef": "synthetic/backend-test-welcome-api",
+      "class": "backend-test",
+      "split": "private",
+      "seeds": [1, 2, 3],
+      "description": "Backend API test workflow contract slot."
+    },
+    {
+      "taskRef": "synthetic/refactor-outcome-tokens",
+      "class": "refactor",
+      "split": "private",
+      "seeds": [1, 2],
+      "description": "Bounded refactor around evidence token naming."
+    },
+    {
+      "taskRef": "synthetic/implement-ready-planner-gate",
+      "class": "implement",
+      "split": "private",
+      "seeds": [1, 2, 3],
+      "description": "Ready Planner artifact-gate implementation slot."
+    },
+    {
+      "taskRef": "synthetic/heldout-docs-handoff",
+      "class": "docs",
+      "split": "held_out",
+      "seeds": [1, 2],
+      "description": "Held-out docs/handoff generalization slot; never used for candidate generation."
+    },
+    {
+      "taskRef": "synthetic/heldout-bugfix-gate",
+      "class": "bugfix",
+      "split": "held_out",
+      "seeds": [1, 2, 3],
+      "description": "Held-out bugfix gate; promotion-only signal."
+    },
+    {
+      "taskRef": "synthetic/heldout-fullstack-smoke",
+      "class": "fullstack",
+      "split": "held_out",
+      "seeds": [1, 2],
+      "description": "Held-out fullstack smoke; not for public feedback."
+    },
+    {
+      "taskRef": "synthetic/heldout-bootstrap-slot",
+      "class": "bootstrap",
+      "split": "held_out",
+      "seeds": [1, 2, 3],
+      "description": "Held-out bootstrap identity/slot discipline."
+    }
+  ]
+}

package/docs/templates/evaluation/matrix-dag-dry-run-v1.json

@@ -0,0 +1,21 @@
+{
+  "version": 3,
+  "title": "eval-matrix-cell-dry-run",
+  "runtimeContract": {
+    "schemaVersion": 1,
+    "agentRuntime": "pi-only",
+    "repairWriterProtocol": "explicit-node-v1"
+  },
+  "tasks": [
+    {
+      "id": "matrix-cell-static",
+      "depends_on": [],
+      "complexity": "LOW",
+      "executor": "static",
+      "subtask_prompt": "Matrix cell placeholder; evaluation binding is injected by campaign matrix.",
+      "static": {
+        "resultMarkdown": "matrix cell dry-run placeholder"
+      }
+    }
+  ]
+}

package/docs/templates/evaluation/matrix-fixture-v1.json

@@ -0,0 +1,10 @@
+{
+  "schemaVersion": 1,
+  "defaultVerifyPassed": false,
+  "results": [
+    {
+      "split": "public",
+      "verifyPassed": true
+    }
+  ]
+}

package/docs/templates/evaluation/private-verifier-dogfood-v0.json

@@ -0,0 +1,16 @@
+{
+  "schemaVersion": 1,
+  "privateVerifierId": "pv-dogfood-v0",
+  "createdAt": "2026-07-19T00:00:00.000Z",
+  "description": "M4 dogfood private verifier. Controller-only; never enter candidate contentRefs/prompts/skill snapshots.",
+  "checks": [
+    {
+      "checkId": "node-version-ok",
+      "kind": "shell",
+      "command": ["node", "-e", "process.exit(process.versions.node ? 0 : 1)"],
+      "cwd": ".",
+      "timeoutMs": 15000,
+      "expectedExitCode": 0
+    }
+  ]
+}

package/docs/templates/product-line/AGENTS.md

@@ -4,5 +4,6 @@
 - Treat `constraints.allowed_paths` and `constraints.forbidden_paths` as machine-enforced write boundaries; review DAG writer `writeSet` before execution.
 - Advance only tasks whose dependencies are complete. Preserve failed run records; retries receive new worker run IDs.
 - A Ready task must have acceptance references, non-empty allowed/forbidden paths, and deterministic verification commands.
+- For `fullstack-v1` packets (`feature.yaml`), every TaskSpec should declare `execution.workflow`; required ACs need implementation/verification refs, `required_evidence`, and integration policy. Parallel writers must not share overlapping `allowed_paths`.
 - QA records an independent verdict and evidence. Do not write `status: success` closeout until `qa_verdict: pass` and non-empty `qa_evidence` exist.
 - Human gates remain human decisions. Record owner, time, reason, evidence, and follow-up without rewriting failed history.

package/docs/templates/product-line/README.md

@@ -7,3 +7,20 @@ agent-worker task validate-feature <feature-dir>
 ```
 
 The validator checks acceptance ID uniqueness, task references and dependencies, cycles, TaskSpec/path/verification completeness, and QA evidence before a successful closeout.
+
+## Profiles
+
+| Profile | How to declare | Behavior |
+|---|---|---|
+| `generic`（默认） | 省略 `feature.yaml`，或 `profile: generic` | 保持 legacy 校验；不强制 `execution.workflow` / 双覆盖 AC |
+| `fullstack-v1` | `feature.yaml` 中 `profile: fullstack-v1` 并声明 `scope` | 强制显式 workflow、required AC 双覆盖、frontend-test 依赖、writer writeSet 串行等结构门禁 |
+
+端到端全栈 dogfood 样板见仓库 `features/F-2026-005/`（欢迎语链路：契约 → BE/FE 实现 → backend-test / frontend-test → Final Verification）。
+
+## Minimal files
+
+- `feature.yaml`（可选；fullstack 必填）
+- `requirement.md` / `design.md` / `test-plan.md`
+- `acceptance.yaml`
+- `tasks/task-graph.yaml` + `tasks/*.yaml`
+- `links.md` / `closeout.yaml`（按交付阶段）

package/docs/templates/product-line/acceptance.yaml

@@ -12,3 +12,12 @@ acceptance:
       expected_task_refs:
         - BE-001
         - QA-001
+      # fullstack-v1 required AC fields (optional for generic packets):
+      # implementation_task_refs:
+      #   - BE-001
+      # verification_task_refs:
+      #   - BE-TEST-001
+      # required_evidence:
+      #   - backend-test-result-v1
+      #   - shell_verification
+      # integration: real-required

package/docs/templates/product-line/feature.yaml

@@ -0,0 +1,11 @@
+schema_version: 1
+feature_id: F-YYYY-NNN
+# generic = legacy/simple packet (default when this file is absent)
+# fullstack-v1 = enable structural gates for explicit workflows + dual-coverage ACs
+profile: generic
+# Uncomment and set true flags when profile is fullstack-v1:
+# scope:
+#   backend: true
+#   frontend: true
+#   backendVerification: true
+#   frontendVerification: true

package/docs/templates/product-line/task-graph.yaml

@@ -5,11 +5,19 @@ nodes:
     task: BE-001.yaml
     type: backend-feature
     depends_on: []
+    # Optional artifact-aware edges (Ready Planner envelope-level gate):
+    # produces:
+    #   - kind: backend-impl
+    #     schemaId: backend-impl-v1
   - id: QA-001
     task: QA-001.yaml
     type: qa-execute
     depends_on:
       - BE-001
+    # consumes:
+    #   - kind: backend-impl
+    #     schemaId: backend-impl-v1
+    #     producerTaskId: BE-001
 parallel_policy:
   max_parallel_tasks: 2
   disallow_same_file_parallel_writes: true

package/docs/templates/product-line/task.yaml

@@ -30,6 +30,10 @@ constraints:
     - <protected/path/**>
   hard_constraints:
     - Do not access production secrets
+# Explicit runtime workflow → taskKind. For fullstack-v1 packets this should be set
+# on every TaskSpec. Allowed: agent-dag | frontend-implementation | backend-test | frontend-test
+execution:
+  workflow: agent-dag
 verify:
   preset: standard
   mode: serial

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tea-agent/loop-agent",
-  "version": "0.16.1-beta.2",
+  "version": "0.16.2",
   "type": "module",
   "bin": {
     "loop-agent": "bin/loop-agent.js",
@@ -14,6 +14,7 @@
     "docs/harness-methodology-tdd.md",
     "docs/harness-methodology-verification.md",
     "docs/harness-methodology-debugging.md",
+    "docs/local-development-environment.md",
     "docs/architecture/runtime-boundaries.md",
     "docs/architecture/README.md",
     "docs/architecture/system-overview.md",

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

@@ -6,10 +6,10 @@ Pre-write nodes are read-only. Preserve IDs, labels, commands, language, require
 
 - **`frontend-contract-pi`**: `Scope`, `Non-goals`, `Acceptance Criteria`, `UI States`, `Target Runtime Environment`, `Risks`, `Verification Expectations`. No guessed requirements.
 - **`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
+- **`frontend-mock-assess-pi` + gate**: first non-empty 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.
+  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).
 - **`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)

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

@@ -466,6 +466,11 @@ agent-worker report metrics --repo <repo-root> --month <YYYY-MM> [--json]
 agent-worker task draft-followup <task-id> --worker-run-id <id> --feature-dir <feature-dir> --repo <repo-root> [--json]
 agent-worker feature approve-followup --feature-dir <feature-dir> --followup-id <id> --repo <repo-root> --owner <owner> [--dry-run] [--json]
 agent-worker task retry <task-id> --repo <repo-root> [--reason "<已修复的原因>"]
+agent-worker task reconcile <task-id> --feature-id <feature-id> --worker-run-id <id> --dag-run-id <id> --action abandon --reason "<text>" --repo <repo-root> [--force-abandon-recoverable]
+agent-worker pool mark-failed --feature-id <feature-id> --task-id <task-id> --worker-run-id <id> --reason "<text>" --repo <repo-root>
+agent-worker pool doctor --repo <repo-root> [--json] [--mapping <file>]
+agent-worker pool migrate-state --repo <repo-root> [--apply --owner <owner> --reason <reason>] [--mapping <file>] [--json]
+agent-worker feature git advance-checkpoint --feature-id <feature-id> --reason "<text>" --repo <repo-root>
 agent-worker batch plan-ready --feature-dir <feature-dir> --repo <repo-root> [--limit <count>] [--json]
 agent-worker batch run-ready \
   --feature-dir <feature-dir> \                   # 含 tasks/task-graph.yaml

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

@@ -18,7 +18,10 @@
 
 前端专用链在 `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`。
 
-显式专用 `taskKind` 保持兼容并优先于任务源分类，也不扩充 governance profile：`frontend-implementation` 显式选择前端实现 DAG，`frontend-test` 选择 FE-test RAG DAG，`backend-test` 选择后端测试 DAG，`knowledge-sync` 选择 Feature 测试知识回写 DAG，`knowledge-graph-bootstrap` 选择业务知识图谱开荒/增量 DAG。后端测试链为 `analyze-inputs-pi → backend-test-analysis-contract-shell → backend-test-environment-scout-pi → backend-test-execution-contract-shell → generate-backend-functional-cases-pi → emit-backend-case-manifest-pi → backend-test-case-manifest-shell → review-backend-cases-pi → review-backend-cases-gate-shell → generate-backend-pytest-pi → backend-test-traceability-gate-shell → execute-backend-pytest-shell → parse-backend-test-result-shell → classify-backend-test-result-pi → test-retrospect-pi → backend-test-outcome-gate-shell`。analysis/execution/case-manifest gate 写入 run-owned contracts；parse materialize Backend Test Result v1（`contracts/backend-test-result.json`）。Case Manifest 确定性校验 AC→case 覆盖；traceability gate 校验 generated file/symbol。execute 在非空 JUnit 下将 pytest exit 0/1 视为节点成功以便 always-run retrospect；`backend-test-outcome-gate-shell` 以 result.outcome 收口；retrospect 使用 manifest coverageSummary + Result v1，不得自造 coverage%。`evidenceGaps`、未知 framework、secret 值、路径穿越或 preflight 失败时后续 writer/execute 不启动。`knowledge-sync` 链必须绑定 `featureId`；图谱运维公共入口是 `loop-agent knowledge query|graph-init|graph-materialize|graph-promote|graph-incremental-prepare`。治理等级仍由既有 `minimal|standard|reviewed|supervised` 规则推断。
+
+> Backend-test vNext：Analysis v2 明确 responseBody shape、ordering、field comparison/precision 与 sourceRefs，并兼容归一化 v1；pytest 生成后 traceability 会按真实 symbol 更新 generated Manifest 和 global/in-scope/cross-domain coverage，随后执行结构化语义 review，最多一次 testcase-only revision，final pass 后才运行 initial pytest。Observe snapshot 投影 initial/classification/repair/final/effective facts。
+
+显式专用 `taskKind` 保持兼容并优先于任务源分类。`backend-test` 选择固定 **24 个真实顶层节点**的后端测试 DAG：intake 双合同、cases+manifest、单次 case revision、pytest 生成与 semantic review、单次 semantic revision、initial execute+parse、classification+eligibility、单次 TestBug repair、final/effective Result、retrospective 和 outcome gate。三条可选分支由 fail-closed `runIf` 控制，不通过动态子节点隐藏数量；所有原有 contracts/JUnit/Result/traceability/repair safety artifacts 继续保留。`knowledge-sync` 与 `knowledge-graph-bootstrap` 继续通过各自显式 taskKind 选择知识回写/图谱开荒 DAG。治理等级仍由 `minimal|standard|reviewed|supervised` 推断。
 
 ### DAG workflow 层级
 
@@ -99,7 +102,7 @@ contract-pi → scout-src ∥ scout-tests → plan-pi → write-set-audit-pi
   → write-set-gate-shell → implement-pi → soft-verify-shell → process-supervisor-pi → process-gate-shell
   → repair-pi → hard-verify-shell
   → [authority-surface-audit-pi → authority-surface-gate-shell]  # 可选
-  → review-pi → review-gate-shell → decision-pi → closeout-pi
+  → review-pi → review-verdict-recovery-pi → review-gate-shell → decision-pi → closeout-pi
 ```
 
 | Stage | 减少 main-session 工作的方式 |
@@ -115,9 +118,9 @@ contract-pi → scout-src ∥ scout-tests → plan-pi → write-set-audit-pi
 | `repair-pi` | supervisor 请求 revision 时在 repair `writeSet` 内 bounded exclusive fix |
 | `hard-verify-shell` | lint/typecheck + `HARNESS_ALLOW_ACTIVE_DAG_RUNS=1 check-repo.sh` fact |
 | `authority-surface-audit-pi` + `authority-surface-gate-shell` | 可选 permission/state/tool-exposure audit；仅 authority signal 或显式 `authority-surface-audit` marker 时插入；gate 仅接受 `VERDICT: pass` |
-| `review-pi` + `review-gate-shell` | Critical/Important → `request-revision`；node JSON 上 `shell.verdictGate` block，除非 extracted verdict 行为 `VERDICT: pass` |
+| `review-pi` + `review-verdict-recovery-pi` + `review-gate-shell` | Critical/Important → `request-revision`；recovery 只规范化 VERDICT 协议（不得从自然语言猜 pass）；gate 只认 `review-verdict-recovery-pi` 的 `VERDICT: pass` |
 
-**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` 以兼容；需要固定非 `VERDICT:` 协议首行的 Pi 节点可显式声明 `firstProtocolLine`，executor 会把第一条匹配前缀的行提升为 canonical 首行，不匹配时不伪造。`frontend-mock-assess-pi` 用它固定 `MOCK_STRATEGY:`，gate 仍保持 `first-non-empty` exact-match。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`。
+**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 属性与路径边界。