@tea-agent/loop-agent 0.14.0 → 0.16.0

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.14.0",
+  "version": "0.16.0",
   "type": "module",
   "bin": {
     "loop-agent": "bin/loop-agent.js",
@@ -10,7 +10,10 @@
     "AGENTS.md",
     "bin/",
     "dist/",
-    "docs/*.md",
+    "docs/README.md",
+    "docs/harness-methodology-tdd.md",
+    "docs/harness-methodology-verification.md",
+    "docs/harness-methodology-debugging.md",
     "docs/architecture/runtime-boundaries.md",
     "docs/architecture/README.md",
     "docs/architecture/system-overview.md",
@@ -18,29 +21,16 @@
     "docs/architecture/worker-and-feature.md",
     "docs/architecture/facts-and-state.md",
     "docs/architecture/evolution.md",
-    "docs/decisions/README.md",
-    "docs/design/README.md",
-    "docs/exec-plans/README.md",
-    "docs/exec-plans/active/README.md",
-    "docs/exec-plans/completed/README.md",
     "docs/init-surface.manifest.json",
-    "docs/progress/README.md",
-    "docs/reports/README.md",
     "docs/skills/",
     "docs/templates/",
     "examples/",
     "harness.json",
     "skills/",
-    "scripts/check-product-line-docs.sh",
-    "scripts/check-task-pool-root.sh",
     "scripts/kb-bootstrap-init-skeleton.sh",
-    "scripts/kb-query.sh",
     "scripts/kb-query.mjs",
-    "scripts/kb-graph-materialize.sh",
     "scripts/kb-graph-materialize.mjs",
-    "scripts/kb-graph-promote.sh",
     "scripts/kb-graph-promote.mjs",
-    "scripts/kb-graph-incremental-prepare.sh",
     "scripts/kb-graph-incremental-prepare.mjs",
     "README.md",
     "CHANGELOG.md"
@@ -55,7 +45,7 @@
     "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
     "build": "npm run clean && tsc -p tsconfig.build.json && node -e \"const fs=require('node:fs');const p='dist/worker/observe/static';fs.mkdirSync(p,{recursive:true});fs.cpSync('src/worker/observe/static',p,{recursive:true});\"",
     "prepack": "npm run build",
-    "prepublishOnly": "npm run typecheck && npm test && npm run build",
+    "prepublishOnly": "node scripts/check-npm-publish-policy.mjs && npm run typecheck && npm test && npm run build",
     "lint": "tsc --noEmit",
     "typecheck": "tsc --noEmit",
     "test": "node scripts/run-tests.mjs",

package/skills/browser-tools/SKILL.md

@@ -117,10 +117,10 @@ Wrap everything in an IIFE to run multi-statement code:
   // Multiple operations
   const data = document.querySelector('#target').textContent;
   const buttons = document.querySelectorAll('button');
-  
+
   // Interactions
   buttons[0].click();
-  
+
   // Return results
   return JSON.stringify({ data, buttonCount: buttons.length });
 })()

package/skills/frontend-design-review/references/review-checklist.md

@@ -1,58 +1,40 @@
 # Frontend Design Review Checklist
 
-## Requirement And State Coverage
+## Coverage
 
-- Target route/page/component and non-goals are clear.
-- Every acceptance criterion maps to steps, files, UI behavior, and verification.
-- Assumptions and unresolved ambiguity are explicit.
-- Applicable success, error, loading, empty, disabled, permission, retry, stale-response, and boundary states are handled or marked N/A.
+- Route/component, non-goals, assumptions, and unresolved ambiguity are explicit.
+- Each acceptance criterion maps to steps, files, UI behavior, states, and verification.
+- Success/error/loading/empty/disabled/permission/retry/stale/boundary states are handled or N/A.
 
-## Project And Knowledge Fit
+## Project Fit
 
-- Existing components, hooks, API helpers, mocks, schemas, router patterns, templates, tokens, and theme rules were considered.
-- Component/design choices cite knowledge-base or `openSpec/`; failed/empty knowledge-base queries recurse through `<repoRoot>/openSpec/**` first.
-- Evidence records source status, query terms, paths/headings, and conflicts.
-- Dependencies are authorized; paths fit allowed/write scope and avoid forbidden/generated files.
-- A required Mock-backed strategy reuses native support when proven, otherwise an
-  existing browser-intercept/request-adapter seam; it maps endpoint/states to fixtures,
-  stays in writer scope, and is off in production. `not-needed` adds none.
+- Reuse components, hooks, API helpers, mocks, schemas, router patterns, tokens, and theme rules.
+- Cite knowledge-base or `openSpec/`; failed/empty knowledge queries must search `<repoRoot>/openSpec/**`.
+- Record source status, query terms, paths/headings, conflicts, authorized deps, and allowed paths.
 
-## Interaction And Quality
+## Interaction / Quality
 
-- Actions, feedback, validation timing, navigation, persistence, and recovery are unambiguous.
-- Responsive and overflow behavior covers target environments.
-- Keyboard, focus, semantics, contrast, reduced motion, data lifecycle, cancellation, and error recovery are addressed when applicable.
+- Actions, feedback, validation timing, navigation, persistence, recovery, responsive/overflow, focus/keyboard/semantics/contrast/reduced motion, cancellation, and data lifecycle are covered when applicable.
 
 ## Verification
 
-- Static and behavior commands are exact, discoverable, and deterministic.
-- Tests prove changed state logic and flows at repository-supported levels.
-- Browser/visual checks are required only by task intent or existing gates.
-- Every missing verification path is a blocker or disclosed risk.
-- Verification entrypoints are frozen; any Mock-specific command is generated only
-  from trusted sources, and behavior separately proves page consumption.
-
-## Mock Strategy Safety
-
-- The strategy protocol is valid and not `MOCK_STRATEGY: blocked`.
-- For Mock strategies, API fields and fixture states trace to contract evidence; gaps are explicit.
-- Selection follows repository capability: native mock first, browser interception
-  for existing e2e, request adapter/injection for local preview.
-- The real request remains enabled by default; activation is explicit, reversible,
-  local/test-only, and excluded from production behavior.
-- Verification uses only shell entrypoints fixed when the DAG was generated; the
-  plan does not invent commands that shell nodes cannot execute.
-- Mock strategies include a production/default-real-path build with Mock off and
-  Mock-backed behavior evidence. `not-needed` instead needs applicable real or
-  no-remote behavior evidence.
-- Mock-backed checks prove frontend states only. Real integration remains pending
-  until the actual backend path has fresh evidence.
+- Static/behavior commands are exact, frozen, discoverable, and deterministic.
+- Tests prove changed state and flows at supported levels; browser/visual only when task/gate requires.
+- Missing required verification is a blocker; optional gaps are disclosed risks.
+
+## Mock Safety
+
+- Strategy line is valid and not `MOCK_STRATEGY: blocked`.
+- Mock API fields/states trace to contract evidence; gaps are explicit.
+- Prefer native mock; browser intercept only for existing e2e; request adapter only for reversible local preview.
+- Real request stays default; activation is explicit, reversible, local/test-only, and production-off.
+- Plans use only DAG-frozen shell entrypoints.
+- Mock strategies need default-real-path build with Mock off plus Mock-backed behavior evidence.
+- `not-needed` needs real/no-remote evidence, or default-auto skipped-Mock rationale with Real Integration Gap preserved when no project Mock capability exists.
+- Mock-backed checks prove frontend states only; real integration remains pending until actual backend evidence exists.
 
 ## Verdict Matrix
 
-- Coverage gap, unsafe scope, unauthorized dependency, unresolved required interaction, or missing required verification: request revision.
-- Missing knowledge-base evidence and skipped `openSpec/` fallback: request revision.
-- No relevant knowledge-base or `openSpec/` rule for a required decision: request revision.
-- Unsafe/missing mock strategy or mock evidence presented as real integration: request revision.
-- Knowledge-base unavailable but relevant `openSpec/` rules were applied: advisory connection gap, not a specification gap.
-- Optional cleanup that cannot affect acceptance: advisory.
+- Request revision for coverage gaps, unsafe scope, unauthorized deps, unresolved required interaction, missing required verification, skipped `openSpec/` fallback, unsafe/missing Mock strategy, or Mock evidence presented as real integration.
+- Knowledge-base unavailable but relevant `openSpec/` rules applied is advisory only.
+- Optional cleanup that cannot affect acceptance is advisory.

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

@@ -6,11 +6,11 @@ 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**: first non-empty line  
-  `MOCK_STRATEGY: native|browser-intercept|request-adapter|not-needed|blocked`  
-  Prefer native Mock; browser intercept only with existing e2e; request-adapter only for reversible local preview. `not-needed` needs 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-mock-assess-pi` + gate**: first non-empty line
+  `MOCK_STRATEGY: native|browser-intercept|request-adapter|not-needed|blocked`
+  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.
+- **`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/frontend-review/SKILL.md

@@ -30,7 +30,9 @@ required check, forbidden write, or unmet acceptance criterion forces revision.
 - Inspect static, behavior, and available Mock-specific artifacts directly. For Mock
   strategies, compare the endpoint matrix, handler/fixture/adapter and consumer diff;
   require the real request as default, contract-aligned fixtures, production isolation,
-  and no false real-integration claim. `not-needed` needs applicable real/no-remote evidence.
+  and no false real-integration claim. `not-needed` needs applicable real/no-remote
+  evidence, or an explicit default-auto skipped-Mock rationale with the Real
+  Integration Gap preserved when no project Mock capability is confirmed.
 - Component/design claims require traceable knowledge-base evidence or, after connection/query failure or no match, relevant `<repoRoot>/openSpec/**` evidence. The connector format is TODO; never claim a query or fallback search without evidence. Execute explicit `grep`/`find` to locate spec files and `read` to load them before referencing their rules. Only successful `read` tool calls are observable as "已读取规范文件" in the spec-evidence inspector.
 - Treat shell exit status as authoritative. Do not edit files.
 

package/skills/frontend-review/references/review-findings.md

@@ -43,5 +43,6 @@ Avoid vague advice. When no source location exists, cite the command or artifact
 - Changed files are authorized.
 - Criteria and applicable states have implementation and evidence.
 - Required Mock-backed behavior passed; any generated Mock-specific verification also
-  passed; Mock is not enabled by default in production.
+  passed; Mock is not enabled by default in production. For default-auto skipped
+  Mock, the real request remains default and the Real Integration Gap is preserved.
 - Optional unavailable knowledge-base, browser, visual, or manual checks remain explicit risks.

package/skills/frontend-verification/SKILL.md

@@ -45,7 +45,9 @@ Return Markdown headings:
 - `Follow-up`: concrete work or `None`.
 
 When the backend remains unavailable but required mock-backed checks pass, state
-`Frontend status: mock-validated` and `Real integration: pending`. Use a completed
+`Frontend status: mock-validated` and `Real integration: pending`. When default
+`auto` skipped Mock and no real API evidence passed, state
+`Frontend status: locally-validated` and `Real integration: pending`. Use a completed
 `<task-id>-real-api-integration-verify` task before changing the latter to complete;
 the follow-up is explicit, not auto-created or auto-executed.
 

package/skills/frontend-verification/references/verification-checklist.md

@@ -2,26 +2,19 @@
 
 ## Static And Behavior Evidence
 
-- Type/compile, lint/format, build, and schema/client checks ran when required.
-- Generated output was authorized.
-- Tests cover changed logic/flows and regressions.
-- Browser/e2e/manual evidence exists when explicitly required.
-- Selected-strategy behavior and applicable loading, empty, error, success, disabled,
-  permission, retry, and boundary states have evidence from fixed DAG entrypoints.
-- When generated, Mock-specific verification checks service/handler/schema/fixtures;
-  behavior evidence separately proves page consumption.
-- For Mock strategies, activation is explicit/non-production and a production/default-
-  real-path build with Mock off confirms the real request remains default.
-- `not-needed` has positive readiness/no-remote evidence plus applicable real or
-  no-remote behavior evidence. Mock-backed evidence remains frontend-only and never
-  satisfies real API integration.
+- Required type/compile, lint/format, build, schema/client, browser/e2e/manual checks ran.
+- Generated output was authorized; tests cover changed logic, flows, and regressions.
+- Fixed DAG entrypoints prove selected-strategy behavior and applicable loading/empty/error/success/disabled/permission/retry/boundary states.
+- Mock-specific checks cover service/handler/schema/fixtures; behavior evidence separately proves page consumption.
+- Mock activation is explicit/non-production; a default-real-path build with Mock off proves the real request remains default.
+- `not-needed` has real/no-remote evidence, or default-auto skipped-Mock rationale with Real Integration Gap preserved when no project Mock capability exists.
+- Mock-backed evidence is frontend-only and never satisfies real API integration.
 
 ## Design And Component Evidence
 
 - Claims cite knowledge-base retrieval or `<repoRoot>/openSpec/**` fallback.
-- Evidence records query/source/version/time or fallback search terms, paths, headings, and applied rules.
-- Relevant `openSpec/` matches become the current-project specification and satisfy source availability; only the knowledge-base connection remains unavailable.
-- Missing both sources blocks explicit compliance or an unresolved required design decision.
+- Evidence records query/source/time or fallback search terms, paths, headings, and applied rules.
+- Relevant `openSpec/` matches satisfy source availability; missing both sources blocks explicit compliance or required design decisions.
 
 ## Status
 
@@ -35,12 +28,11 @@ Only passed satisfies a required check. Other optional statuses remain disclosed
 
 ## Closeout Checks
 
-- List exact commands, source, exit status, and archived output/artifact when available.
-- Map every criterion to evidence or a named gap.
+- List exact commands/source/exit status/artifacts; map every criterion to evidence or a named gap.
 - Record review verdict before completion.
 - Do not conflate static, behavior, browser/visual/manual, or knowledge-base proof.
-- If only mock evidence exists, report `Frontend status: mock-validated` and
-  `Real integration: pending`, with the actual API verification as follow-up.
+- If only Mock evidence exists, report `Frontend status: mock-validated` and `Real integration: pending`, with actual API verification follow-up.
+- If default `auto` skipped Mock and no real API evidence exists, report `Frontend status: locally-validated` and `Real integration: pending`.
 
 ```markdown
 ## Changes
@@ -64,5 +56,4 @@ Only passed satisfies a required check. Other optional statuses remain disclosed
 - None.
 ```
 
-If review is not pass or a required check is not passed, describe the task as
-incomplete and list concrete follow-up.
+If review is not pass or a required check is not passed, describe the task as incomplete and list concrete follow-up.

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

@@ -16,7 +16,7 @@
 
 对于默认 `standard` 任务，生成器根据标题、`source/需求.md` 和结构化 `allowedPaths` 做保守、确定性的需求分类。只有高置信的前端实现需求自动选择 `frontend-implementation` DAG；后端、前后端混合、明确排除前端或证据不足的需求继续使用 governance profile 选出的模板。分类不会把普通后端实现路由到 `backend-test`，也不会替换由显式 profile、`workflowPolicy` 或 supervised quality gate 选中的 supervised 模板。
 
-前端专用链在 `frontend-scout-pi` 后加入只读 `frontend-mock-assess-pi` 和确定性 contract gate，根据接口契约、后端就绪度、生成期能力 seed 与固化验证入口选择 `native|browser-intercept|request-adapter|not-needed|blocked`。策略直接传给 plan、两阶段 design review、唯一 writer、实现 review 和 closeout；真实请求保持默认，缺少契约、生产隔离或可执行验证时 gate 阻塞。可选 `frontendMock` 配置声明 `auto|required|disabled`、既有服务目录与专项命令；不安全或不完整的显式 required 合同只生成无 writer 的评估链，有可信命令时才增加 `frontend-mock-verify-shell`。Mock-backed 证据只证明前端状态；`not-needed` 需要真实或无远程接口行为证据。未调用后端时 closeout 报告 `Frontend status: mock-validated` 与 `Real integration: pending`。
+前端专用链在 `frontend-scout-pi` 后加入只读 `frontend-mock-assess-pi` 和确定性 contract gate，根据接口契约、后端就绪度、生成期能力 seed 与固化验证入口选择 `native|browser-intercept|request-adapter|not-needed|blocked`。策略直接传给 plan、两阶段 design review、唯一 writer、实现 review 和 closeout；真实请求保持默认，缺少契约、生产隔离、注释真实请求或显式 required 合同不完整时 gate 阻塞。可选 `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` 规则推断。
 

package/docs/agent-dag-recovery-playbook.md

@@ -1,195 +0,0 @@
-# Agent DAG Recovery Playbook（恢复手册）
-
-> **关联**：[`agent-dag-runner.md`](agent-dag-runner.md)（CLI 与 run 语义）· [`templates/agent-dag-decision-gate.prompt.md`](templates/agent-dag-decision-gate.prompt.md)（Decision Gate 消费 recovery 证据）
-
-## 定位
-
-Agent DAG **recovery planning 是只读、派生、advisory** 的。`dag report` 与 `buildDagDecisionGateEvidence()` 从 `.harness/dag-runs/` 的 canonical facts 聚合 `normalizedFailureCategory` → `recoveryRecommendation`，供人工或 Decision Gate prompt 消费。
-
-中断后不要从上游摘要手工生成 impl-only DAG。先修复 `.harness/tasks/<task-id>/source/` 或计划，再对同一 task 重新执行 `dag run-task`、严格 `dag validate` 和新的 `run-dag`。新生成的完整 DAG 会重新冻结 `sourceBinding` 并经过 contract/scout/plan/gate；v3 孤立 writer 如果既无来源绑定、也无只读 planner 上游，会被 strict governance 拒绝。完整规则见 [`design/dag-source-binding-and-recovery.md`](design/dag-source-binding-and-recovery.md)。
-
-Production Readiness v0.1 在 normalized DAG category 之上增加 product-line routing。Report 与 doctor 输出应保留 raw DAG fact 并派生，不重写已完成 facts：
-
-```text
-raw_failure_category
-dag_normalized_failure_category
-product_line_failure_category
-recommended_follow_up
-```
-
-Product-line taxonomy 定义见 `ai_workspace/loop-agent/design/state-and-failure-taxonomy.md`。
-
-### 前端设计门禁专用恢复路径
-
-前端 DAG 的 design gate shell 失败（`frontend-first-design-gate-shell`、`frontend-final-design-gate-shell`、`frontend-design-gate-shell`）**不路由为 `ProductBug` / `dev-fix`**。此类失败固定路由为：
-
-- `productLineFailureCategory`: `ContractMismatch`
-- `recommendedFollowUp`: `frontend-plan-revision-and-rerun`
-
-恢复动作由 `planDagRecovery` 根据实际的 `normalizedFailureCategory` 和 run status 决定（通常为 `rerun-after-fix` 或 `manual-review`），但 product-line 维度的分类确保 Task Pool 和 morning report 不会将其混入普通 bug backlog。
-
-**非目标（本 playbook 不覆盖、runner 不实现）：**
-
-- 自动 retry / resume 节点执行
-- 修改 `completed/` 或 `paused/` 下的历史 run facts
-- 把 `autoRetryEligible` 当作 runtime 触发器
-- 仅凭 recovery 派生字段自动 approve Decision Gate
-
-## 快速命令
-
-```bash
-cd .
-
-# 全局 runtime 健康（active/paused/completed 摘要 + healthIssues；advisoryOnly）
-npm run dev -- dag doctor
-
-# 单 run 生命周期（approvalFlow、hasHumanApproval、nextRecommendedAction）
-npm run dev -- dag status --run-id <run-id>
-
-# 聚焦最新 paused run（--paused-latest ≡ --lifecycle paused --latest）
-npm run dev -- dag report --paused-latest [--json|--markdown]
-
-# 默认 compact Markdown 表格
-npm run dev -- dag report --run-id <run-id>
-
-# 机器可读 JSON（含 primaryFailure / primaryRecovery / downstreamSkippedNodes）
-npm run dev -- dag report --run-id <run-id> --json
-
-# 人类交接 Recovery Plan（四段结构化 Markdown）
-npm run dev -- dag report --run-id <run-id> --markdown
-
-# 过滤器
-npm run dev -- dag report --failed-only                              # 仅失败/需恢复
-npm run dev -- dag report --latest --failed-only                    # 最新一条需恢复 run
-npm run dev -- dag report --action retry-node                       # 按 primaryRecovery.action 筛选
-npm run dev -- dag report --lifecycle paused --action resume-or-reject
-
-# Decision Gate envelope dry-run（不 resume/retry；validate 无效时 exit 1）
-npm run dev -- dag decision inspect --run-id <run-id> [--node-id <node-id>]
-npm run dev -- dag decision validate --run-id <run-id> [--node-id <node-id>]
-```
-
-### Paused run operator 路径
-
-1. `dag report --paused-latest --json` 或 `dag doctor` — 定位最新 paused run 与 `primaryRecovery`
-2. `dag status --run-id <id>` — 读 `approvalFlow`、`escalationArtifactPath`、`pendingNodes`
-3. （可选）`dag decision validate --run-id <id>` — envelope preflight
-4. `dag approve --run-id <id> --option <option-id>` → `dag resume --run-id <id>`；或 `dag reject --run-id <id> --reason "..."`
-
-精确 approval 顺序见 [`agent-dag-runner.md`](agent-dag-runner.md) §Paused lifecycle。
-
-Decision Gate prompt 侧：`buildDagDecisionGateEvidence()`（`./src/core/dag-decision-evidence.ts`）从 `DagRunReportEntry` 生成 prompt-friendly 摘要，字段与 JSON report 对齐，**不**写回 run state。
-
-## `dag report --json` schema 锁定
-
-- **Schema 文件**：`ai_workspace/loop-agent/templates/agent-dag-report.schema.json`
-- **Envelope**：`{ schemaVersion: 1, runs: DagRunReportEntry[] }`
-- **稳定消费字段**（Decision Gate / tooling 应依赖）：`primaryFailure`、`primaryRecovery`、`downstreamSkippedNodes`、`recoveryRecommendation`、`normalizedFailureCategory`；node 级 `decisionEnvelope`、`artifacts`；paused 级 `pausedByNodeId`、`pauseReason`
-- **测试**：`./test/dag-report.test.ts` §`dag report JSON schema contract` 对 fixture run 做 schema 校验
-- **变更策略**：breaking 字段变更须 bump `schemaVersion` 并同步 schema 文件与测试
-
-## Recovery Action 枚举
-
-| Action | 含义 | 典型触发 |
-|--------|------|----------|
-| `none` | 无需恢复 | 成功完成 |
-| `monitor` | 进行中，等待结束 | `PENDING` / `RUNNING` |
-| `retry-node` | 修复瞬态条件后可重跑节点 | timeout；executor 瞬态（network/quota/rate-limit/unavailable） |
-| `rerun-after-fix` | 先修根因再重跑 | auth、validation、shell-command、static-error、非瞬态 executor |
-| `resume-or-reject` | 人工审批后继续或拒绝 | paused + decision-envelope / human-required |
-| `manual-review` | 人工审查后再定路径 | write-guard、human-rejected、unknown、非 paused 的 decision-envelope |
-| `inspect-upstream` | 先查上游失败 | SKIPPED 下游节点 |
-| `unknown` | 未映射类别（不应出现在正常派生路径） | 内部兜底 |
-
-## Product-Line Routing v0.1
-
-| Product-line category | Default follow-up |
-|---|---|
-| `SpecUnclear` | `spec-clarification` |
-| `ContractMismatch` | `architecture-contract-fix` |
-| `ProductBug` | `dev-fix` |
-| `TestBug` | `qa-fix-test` |
-| `EnvFailure` | `env-fix` 或 retry verify |
-| `FlakyTest` | `flaky-test-analysis` |
-| `RiskyChange` | `human-review` / `architecture-review` |
-| `DependencyFailure` | unblock dependency |
-| `NeedsHuman` | `human-review` |
-| `Unknown` | human triage |
-
-## 类别 → 动作 → operator 指引
-
-| Normalized category | Recovery action | Operator guidance | Anti-patterns |
-|---------------------|-----------------|-------------------|---------------|
-| `success` | `none` | 归档验收；按需 review artifacts | 对成功 run 发起 retry |
-| `timeout` | `retry-node` | 查日志/artifacts 确认瞬态；人工重跑节点 | 未查根因就循环重试；指望 runner 自动 retry |
-| `executor`（network/quota/rate-limit/unavailable） | `retry-node` | 等后端/配额恢复后重跑 | 把 auth/validation 误判为瞬态 executor |
-| `executor`（其他 raw） | `rerun-after-fix` | 查 executor.jsonl、node result | 盲目 retry 非瞬态 backend 错误 |
-| `auth` | `rerun-after-fix` | 更新 API key/凭证后重跑 | 在凭证未修复时 retry |
-| `write-guard` | `manual-review` | 审 writeSet/writePolicy、prompt、result.summary | read-only 节点写根 `artifacts/`；扩大 writeSet 掩盖违规 |
-| `validation` | `rerun-after-fix` | 修 schema/output/test 后再跑 | 跳过验证直接 approve |
-| `shell-command` | `rerun-after-fix` | 读 stdout/stderr、修命令或 repo 状态 | 只重跑 shell 不改命令 |
-| `static-error` | `rerun-after-fix` | 查 static config 与 emitted markdown | 当 LLM 节点 retry |
-| `decision-envelope`（paused） | `resume-or-reject` | `dag approve --run-id <id> --option <option-id>` / `dag reject --run-id <id> --reason "..."` → `dag resume --run-id <id>` | 未读 envelope 就 approve；用 recovery 字段单独 auto-approve |
-| `decision-envelope`（非 paused） | `manual-review` | 读 decision.envelope.json / validation artifact | 绕过 Decision Gate schema |
-| `human-required`（paused） | `resume-or-reject` | 提供人工输入 → approve/resume | 在 escalation 未解决时 resume |
-| `human-required`（非 paused） | `manual-review` | 读 human-escalation artifacts | 忽略 `requiresHuman` |
-| `human-rejected` | `manual-review` | 修订 contract/source；**新 run** | 对同一 contract 自动 retry |
-| `skipped` | `inspect-upstream` | 修上游 ERROR/SKIPPED 再考虑下游 | 直接 retry SKIPPED 节点 |
-| `unknown` | `manual-review` | 读 state.json、executor.jsonl、node artifacts | 假设 `autoRetryEligible` 会触发执行 |
-
-## Handoff Recovery Plan 结构
-
-`dag report --markdown` 的 **Recovery Plan** 含四段（与 JSON 稳定字段一一对应）：
-
-1. **Primary Failure** — `primaryFailure`（node 或 run scope）
-2. **Recovery Action** — `primaryRecovery`（action、summary、reason、flags、commandHint）
-3. **Blocked Downstream / Skipped Nodes** — `downstreamSkippedNodes`
-4. **Recommended Operator Action** — 面向 operator 的步骤摘要
-
-保存 handoff 时重定向到平台临时目录或 `ai_workspace/loop-agent/reports/`，不要写入 `.harness/dag-runs/`。
-
-## Decision Gate 消费约定
-
-1. 优先 `dag report --json` 或 `buildDagDecisionGateEvidence()` 的 **verified** 派生摘要。
-2. 映射到 `decision` / `nextAction` 须保守；recovery 证据是 **advisory only, not an execution directive**。
-3. `autoRetryEligible: true` 仅表示「规划上可人工重试」，**不**触发 runner。
-4. paused run 的人类路径仍是 M5 CLI：`dag approve --run-id <id> --option <option-id>` / `dag reject --run-id <id> --reason "..."` / `dag resume --run-id <id>`（见 [`agent-dag-runner.md`](agent-dag-runner.md) §Decision Gate）。
-5. Envelope 干跑：`dag decision inspect|validate` 重解析 run facts；`validate` 无效时 exit 1；**不**写 artifact、**不** resume。
-
-## Active stale run recovery（advisory detection）
-
-`dag doctor` 与 `dag status` 通过 `detectDagRunHealthIssues()` 检测 lifecycle 不一致，**不** mutate run facts。
-
-| Code | 典型场景 | operator 指引 |
-|------|----------|------------|
-| `terminal-in-active` | run 已完成但 `active/<run-id>/` 残留 | 对照 `completed/` canonical facts；手动 archive 或删除 stale 目录 |
-| `paused-in-active` | pause 后目录未迁至 `paused/` | `dag doctor` 诊断；修复 facts 后再 approve/resume |
-| `lifecycle-status-mismatch` | `paused/` 下 status 非 paused | 同上 |
-| `missing-approval-artifact` | approve 后 artifact 缺失 | 勿 resume；re-approve 或 restore artifact |
-| `non-terminal-in-completed` | completed 目录 status 异常 | manual-review only |
-| `run-id-mismatch` / `missing-state-json` | 目录损坏或命名错误 | Inspect；勿 auto-mutate completed facts |
-
-**Deferred runtime**：无 `dag recover apply` 或自动 cleanup；未来可能增加只读 `dag recover plan`（设计占位，未实现）。
-
-## 事实源与边界
-
-| 类型 | 位置 | 规则 |
-|------|------|------|
-| Canonical run facts | `.harness/dag-runs/{active\|paused\|completed}/<run-id>/` | **只读**；report 不写回 |
-| 派生 report | stdout / 重定向文件 | 可随时再生 |
-| 工作块摘要 | 根 `artifacts/` | 非 per-run 历史；read-only DAG 节点不得写 |
-
-## 验证
-
-```bash
-cd . && npx vitest run \
-  test/dag-report.test.ts \
-  test/dag-recovery-recommendation.test.ts \
-  test/dag-decision-gate-recovery-dogfood.test.ts \
-  test/dag-decision-evidence.test.ts \
-  test/dag-decision-envelope.test.ts \
-  test/dag-approve-resume.test.ts \
-  test/cli-contract.test.ts
-```
-
-实现细节与映射逻辑：`./src/core/dag-recovery-recommendation.ts`、`dag-report.ts`、`dag-decision-evidence.ts`。

package/docs/agent-dag-runner.md

@@ -1,67 +0,0 @@
-# Agent DAG Runner
-
-Agent DAG 是 loop-agent 的声明式编排 runtime。DAG 将工作拆为节点、按序执行 eligible ranks、记录 artifacts，并用 gate 做 review 与验证。
-
-## 基本用法
-
-```bash
-loop-agent dag run-task <task-id> --profile auto --strict-models --output <temp-dir>/<task-id>-dag.json
-loop-agent dag validate --dag <temp-dir>/<task-id>-dag.json --strict-models --strict-governance
-loop-agent run-dag --dag <temp-dir>/<task-id>-dag.json --cwd .
-```
-
-`<temp-dir>` 为平台原生临时目录。Windows 上 `--output`、`--dag`、`--cwd` 的实际值用原生路径。
-
-## Executors
-
-- `static`：确定性生成的 artifacts 或 notes
-- `shell`：验证与文件系统检查
-- `pi`：规划、review、诊断；节点设 `toolProfile: "write"` 时有界写入
-
-## Retry (read-only Pi nodes)
-
-planner/scout/reviewer/verifier/closeout 角色的只读 Pi 节点可声明 opt-in `retryPolicy`，用于在同一 run 内有界重试模型连接中断、provider 限流、临时不可用或请求 timeout。生成器会为这些安全节点自动声明默认策略：总尝试次数 3（手工配置上限 5），指数退避，单次等待上限 30s。
-
-- 仅以下原始失败分类默认可重试：`timeout`、`network`、`rate-limit`、`unavailable`。
-- `quota`、`auth`、`invalid-output`、`write-guard`、`decision-envelope` 与未知失败不重试。`quota` 不是 rate limit，不会被自动重试。
-- 资格由确定性 helper 判断：仅 `writePolicy=read-only|none`（或 Pi 默认只读）的 planner/scout/reviewer/verifier/closeout 可用。supervisor、implementer、writer（`toolProfile=write` 或 `writePolicy=exclusive`）、docs-only、dynamic、shell、static 与 decision-gate 节点一律不重试，DAG validation 会拒绝其策略。
-- 每次 attempt 写入独立不可变证据（`<node-id>/attempt-<n>.json`，run-relative path），最终 node record 的 `attempts` 字段引用完整 attempt 历史；后一次成功不会覆盖前一次失败证据。
-- 重试期间复用同一 run、controller identity、skill snapshot、prompt、model 与上游输入。节点终态的 `durationMs`、`tokensUsed`、`parsedEvents` 聚合全部 attempts；退避等待会刷新 `lastActivityAt`，避免被误判为 node-quiet。当前退避会占用该节点所在的并发槽。
-
-示例：
-
-```json
-{
-  "retryPolicy": {
-    "maxAttempts": 3,
-    "backoff": "exponential",
-    "initialDelayMs": 2000,
-    "maxDelayMs": 30000,
-    "retryCategories": ["timeout", "network", "rate-limit", "unavailable"]
-  }
-}
-```
-
-未声明 `retryPolicy` 的历史 DAG 行为不变（单次执行、无 `attempts` 字段，也不新增 attempt artifact）。
-
-## Skills
-
-DAG spec 可声明 `defaults.skills`、`skillsByRole` 与节点级 `skills`。Runner 优先从目标项目 `.agents/skills/<skill-name>/SKILL.md` 解析本地指令，再回退到包内 `.agents/skills/`，并在各节点 `skills.json` artifact 中记录解析元数据。
-
-执行前可用 `dag validate --strict-skills` 做 opt-in skill audit；该门禁会在 missing/error/truncated skill 或 unresolved reference 出现时失败。默认 role skill 应来自 `ai_workspace/loop-agent/.agents/skills/vetted-skill-registry.md` 中记录的 repo-local wrapper。
-
-目标项目的 `loop-agent` skill 位于 `.agents/skills/loop-agent/SKILL.md`。loop-agent 源仓库和 npm 包内置版本仍位于 `.agents/skills/loop-agent/SKILL.md`；遗留根路径 `skill/SKILL.md` 仅为旧 worktree 保留兼容 fallback。
-
-## Artifacts
-
-DAG artifacts 位于：
-
-```text
-.harness/dag-runs/<state>/<run-id>/artifacts/<node-id>/
-```
-
-根目录 `artifacts/` 不是有效的默认 DAG artifact 位置。
-
-## Shell Gates
-
-- `shell.verdictGate` 从注入的当前 run 目录读取 `$HARNESS_DAG_RUN_DIR/<fromNodeId>.json`；不应自行发现 active run paths。

package/docs/cursor-prompt-sidecar.md

@@ -1,36 +0,0 @@
-# cursor-prompt Sidecar
-
-`cursor-prompt` 是显式、手工触发的 one-shot sidecar。它不是受治理 Agent runtime，也不参与 DAG、Loop 自动写入、Delegate `--auto-run` 或 task writer 选择。
-
-## 产品定位
-
-| 路径 | 角色 |
-|---|---|
-| Pi DAG (`implement-pi` / `repair-pi`) | 唯一受治理 Agent writer |
-| shell / static | 确定性验证与静态输出 |
-| `cursor-prompt` | 人工 one-shot 干预；成功不等于任务完成 |
-
-## 用法
-
-```bash
-loop-agent cursor-prompt --cwd . "bounded task prompt"
-loop-agent cursor-prompt --file <path>
-loop-agent cursor-prompt --stdin
-loop-agent cursor-prompt --model <id>
-loop-agent cursor-prompt --timeout <ms>
-loop-agent cursor-prompt --stream
-loop-agent cursor-prompt --list-models
-```
-
-调用时才加载 `@cursor/sdk`。缺少 SDK 或 `CURSOR_API_KEY` 时，只有这条命令失败；普通 Agent DAG / doctor / init 不要求 Cursor。
-
-## 约束
-
-- 不读取 `harness.json` task config / DAG facts 作为授权来源。
-- 不复制 DAG `writeSet`、repair、resume 或 Loop auto-execute 能力。
-- 返回后由主会话检查 diff，并显式运行 shell verification。
-- one-shot evidence 写入 `.harness/runs/{active,completed,failed}`。
-
-## 迁移说明
-
-旧 `executor: "cursor"` DAG、`executors.cursor`、`loopAutoWritePolicy` 与 `cursor-fix` 已硬切删除。需要写入时请重新生成 Pi-only DAG，或仅在人工干预场景使用本 sidecar。