@tea-agent/loop-agent 0.13.0-beta.0 → 0.14.0

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

@@ -18,7 +18,7 @@
 
 前端专用链在 `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`。
 
-显式专用 `taskKind` 保持兼容并优先于任务源分类，也不扩充 governance profile：`frontend-implementation` 显式选择前端实现 DAG，`backend-test` 显式选择后端测试 DAG。后端测试链为 `analyze-inputs-pi → backend-test-analysis-contract-shell → 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`。analysis gate 校验 Backend Test Analysis v1、任务源绑定与敏感值，并把规范化 JSON 保存到当前 run 的 `contracts/backend-test-analysis.json`；失败时后续 writer 不启动。治理等级仍由既有 `minimal|standard|reviewed|supervised` 规则推断。
+显式专用 `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` 规则推断。
 
 ### DAG workflow 层级
 
@@ -43,7 +43,7 @@ loop-agent run-dag --dag <temp-dir>/hybrid-dag.json --init-only --canvas-path <t
 
 `<temp-dir>` 表示平台原生临时目录；实际命令中 macOS 与 Windows 都使用本机路径。`/` 只作为 repo refs、JSON/Markdown evidence refs 和 glob 约定的稳定分隔符。
 
-完整 schema 与语义：`docs/agent-dag-runner.md`。Workflow 概览：`docs/loop-agent-harness.md`。
+完整 schema 与语义：`ai_workspace/loop-agent/agent-dag-runner.md`。Workflow 概览：`ai_workspace/loop-agent/loop-agent-harness.md`。
 
 **v2 字段**（均可选；缺失时行为同 v1）：
 
@@ -86,14 +86,16 @@ loop-agent run-dag --dag <temp-dir>/hybrid-dag.json --init-only --canvas-path <t
 
 ### Supervised implementation flow（减少 main-session intervention）
 
-长时 implementation 曾迫使 main session 中途 re-verify、re-review 或 surgical-patch 时，用 `docs/templates/agent-dag.supervised-implementation.json`。
+长时 implementation 曾迫使 main session 中途 re-verify、re-review 或 surgical-patch 时，用 `ai_workspace/loop-agent/templates/agent-dag.supervised-implementation.json`。
 
-**此前 main session 介入原因**：linear hybrid DAG 缺少 in-run writeSet coverage audit、supervision 前归档的 soft verification、read-only process supervisor（`executor: pi`，`role: supervisor` — 非新 executor）、bounded repair exclusive writer、确定性 hard-verify shell fact，以及 fail-closed review verdict gate（除非 whitelist `VERDICT:` 行存在）。
+**此前 main session 介入原因**：linear hybrid DAG 缺少 in-run writeSet coverage audit；旧 supervised write-set gate 在初审返回 `request-revision` 或遗漏 `VERDICT:` 时也会直接 `partial_failed`，需要人工新建下一轮 run。此外还缺少 supervision 前归档的 soft verification、read-only process supervisor（`executor: pi`，`role: supervisor` — 非新 executor）、bounded repair exclusive writer、确定性 hard-verify shell fact，以及 fail-closed review verdict gate（除非 whitelist `VERDICT:` 行存在）。
 
 **Supervised topology**（执行前替换所有 `REPLACE/WITH/...` placeholder）：
 
 ```text
 contract-pi → scout-src ∥ scout-tests → plan-pi → write-set-audit-pi
+  → write-set-audit-format-repair-pi → write-set-format-gate-shell
+  → plan-revision-pi → final-write-set-audit-pi → final-write-set-audit-format-repair-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]  # 可选
@@ -102,8 +104,11 @@ contract-pi → scout-src ∥ scout-tests → plan-pi → write-set-audit-pi
 
 | Stage | 减少 main-session 工作的方式 |
 |-------|------------------------------|
-| `write-set-audit-pi` | implement 前捕获 missing/overlapping writeSet owner |
-| `write-set-gate-shell` | 除非 extracted audit verdict 行为 `VERDICT: pass`，否则 fail-closed block implement |
+| `write-set-audit-pi` | implement 前捕获 missing/overlapping writeSet owner；第一条非空行必须是 canonical verdict |
+| `write-set-audit-format-repair-pi` / `final-write-set-audit-format-repair-pi` | 初审和终审各有一次只读格式恢复；只补 canonical verdict/结构并保留 findings，结论不明确时返回 `request-revision`，不得从一般正文猜 pass |
+| `write-set-format-gate-shell` | 接受格式有效的 pass/request-revision，让有界计划修订继续；本 gate 不授权写入 |
+| `plan-revision-pi` | 最多一轮只读计划修订；初审 pass 时输出 `PASS_NO_REVISION_NEEDED`，request-revision 时解决全部 findings；不得扩大 task `allowedPaths` |
+| `final-write-set-audit-pi` + `write-set-gate-shell` | 终审复核有效计划；只有规范化后的最终 `VERDICT: pass` 授权 implement，终审 request-revision 或格式仍无效时 fail-closed |
 | `soft-verify-shell` | supervision 前归档 focused test exit code |
 | `process-supervisor-pi` | read-only audit coverage、boundary drift、verify gap、repair scope；应 prominently 输出 `VERDICT: pass` 或 `VERDICT: request-revision` |
 | `process-gate-shell` | supervisor node JSON 上 runtime `shell.verdictGate`（仅 `pass` 或 `request-revision`） |
@@ -118,7 +123,7 @@ contract-pi → scout-src ∥ scout-tests → plan-pi → write-set-audit-pi
 
 **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」。
+Prompt invariant：`ai_workspace/loop-agent/templates/agent-dag-process-supervisor.prompt.md`、`ai_workspace/loop-agent/templates/agent-dag-review-verdict.prompt.md`、`ai_workspace/loop-agent/templates/agent-dag-authority-surface-audit.prompt.md`（启用时）。测试：`npx vitest run test/dag-supervised-template.test.ts test/authority-surface.test.ts`。完整叙述：`ai_workspace/loop-agent/agent-dag-runner.md` §「Why main-session interventions happened」。
 
 **未实现**：`executor: supervisor`、whole-run automatic retry/resume、`executor: human`/`decision`、browser executor，或 read-only node 对 root `artifacts/**` 的 exemption。注：有界只读 Pi 节点重试已实现（见下「只读 Pi 节点安全重试」）。
 
@@ -144,20 +149,20 @@ loop-agent dag run-task <task-id> --init-only --cwd <repo-root>
 
 ### DAG 与 artifacts source-of-truth 规则
 
-- 临时 DAG input spec 放平台原生临时目录（例如 `<temp-dir>/<topic>-dag.json`）；可复用 template 放 `examples/` 或 `docs/templates/`。
+- 临时 DAG input spec 放平台原生临时目录（例如 `<temp-dir>/<topic>-dag.json`）；可复用 template 放 `examples/` 或 `ai_workspace/loop-agent/templates/`。
 - **不要**在 `.harness/dag-runs/active/` root 保留手写 DAG input 副本。
 - **不要**把 `.harness/dag-runs/` 内容 commit 到 git。
 - canonical per-run DAG 历史是 `.harness/dag-runs/completed/<run-id>/run.json` 及该 run 目录的 `state.json`、`executor.jsonl`、node artifacts；新建 run directory 使用 `YYYYMMDD-<slug>`。
 - root `artifacts/修改记录.md` 与 `artifacts/验证结果.md` 是 legacy current-work / explicit-write 摘要。不是 per-run 不可变历史，也不是新工作流默认交付路径。
 - Agent DAG read-only node 不得写 root `artifacts/`；若须更新 root artifacts，用显式 `exclusive` write node 或记录了理由、验证与迁移计划的 main-session surgical patch。
 - DAG Cursor 节点交付物必须写入 `.harness/dag-runs/<state>/<run-id>/artifacts/<node-id>/`；`./artifacts/**` 是错误落点。
-- 长期结论须迁入 `docs/exec-plans/`、`docs/reports/` 或 `docs/progress/`。从 completed run evidence 汇总 task artifacts 时用 `promote-run <task-id> --run-id <run-id>`；再用 `closeout task <task-id>` 生成 progress。二者 deterministic，且不 mutate completed run facts。
+- 长期结论须迁入 `ai_workspace/loop-agent/exec-plans/`、`ai_workspace/loop-agent/reports/` 或 `ai_workspace/loop-agent/progress/`。从 completed run evidence 汇总 task artifacts 时用 `promote-run <task-id> --run-id <run-id>`；再用 `closeout task <task-id>` 生成 progress。二者 deterministic，且不 mutate completed run facts。
 
 **DAG author 的 artifact-boundary 提醒**：大量 *讨论* root `artifacts/**` 的 task 仍遵守同一 write guard — read-only node 仅在 node output 返回发现；exclusive node 保持 `artifacts/**` 在 `forbiddenPaths`，除非 concrete path 在 `writeSet`。不要在 declared writeSet 外 instruct implementer 写 `artifacts/修改记录.md` 或 `artifacts/验证结果.md`（P3 boundary-risk practice）。scout 在链接 skill reference 中发现 stale wording 时，把那些 path 纳入 implementer writeSet，或接受记录的 main-session patch（P2 教训：`hybrid-dag.md` 被 scout 发现但 initial writeSet 遗漏）。
 
 ### Decision Gate（M3–M5 runtime）
 
-Pi reviewer node 设 `decisionGate.enabled: true` 时，runner 从 persisted `assistantText`（优先）或 `result.summary.md`（fallback）解析 **恰好一个** info string 为 `DECISION_ENVELOPE_JSON` 的 fenced block。Schema：`docs/templates/agent-dag-decision-envelope.schema.json`。Prompt：`docs/templates/agent-dag-decision-gate.prompt.md`（含 §Recovery Recommendation Consumption 与 schema-adherence 硬规则：勿发明 envelope schema、勿用 `decision: accept`、勿加 extra root key、`audit.runId` 须绑定当前 run id，并填 `audit.nodeId` / `audit.model`）。Playbook：`docs/agent-dag-recovery-playbook.md`。示例 DAG：`examples/decision-gate-agent-dag.json`。
+Pi reviewer node 设 `decisionGate.enabled: true` 时，runner 从 persisted `assistantText`（优先）或 `result.summary.md`（fallback）解析 **恰好一个** info string 为 `DECISION_ENVELOPE_JSON` 的 fenced block。Schema：`ai_workspace/loop-agent/templates/agent-dag-decision-envelope.schema.json`。Prompt：`ai_workspace/loop-agent/templates/agent-dag-decision-gate.prompt.md`（含 §Recovery Recommendation Consumption 与 schema-adherence 硬规则：勿发明 envelope schema、勿用 `decision: accept`、勿加 extra root key、`audit.runId` 须绑定当前 run id，并填 `audit.nodeId` / `audit.model`）。Playbook：`ai_workspace/loop-agent/agent-dag-recovery-playbook.md`。示例 DAG：`examples/decision-gate-agent-dag.json`。
 
 | Milestone | `decisionGate.mode` | 行为 |
 |-----------|---------------------|----------|
@@ -169,10 +174,10 @@ Pi reviewer node 设 `decisionGate.enabled: true` 时，runner 从 persisted `as
 loop-agent dag doctor
 loop-agent dag status --run-id <run-id>
 loop-agent dag report --paused-latest [--json|--markdown]   # 最新 paused run；勿与 --lifecycle 并用
-loop-agent dag report [--run-id <run-id>] [--lifecycle active|paused|completed|all] [--json|--markdown] [--failed-only] [--latest] [--action <recovery-action>]  # derived per-node report（只读）；JSON schema: docs/templates/agent-dag-report.schema.json；仅 advisory — 见 docs/agent-dag-recovery-playbook.md
+loop-agent dag report [--run-id <run-id>] [--lifecycle active|paused|completed|all] [--json|--markdown] [--failed-only] [--latest] [--action <recovery-action>]  # derived per-node report（只读）；JSON schema: ai_workspace/loop-agent/templates/agent-dag-report.schema.json；仅 advisory — 见 ai_workspace/loop-agent/agent-dag-recovery-playbook.md
 loop-agent dag closeout-draft [--run-id <run-id>] [--output <path>]  # M5：从 completed run facts 生成确定性 closeout draft；默认平台临时目录；仅 advisory；不 mutate completed facts
 loop-agent promote-run <task-id> --run-id <run-id>                    # 从 completed DAG/one-shot evidence 汇总 task artifacts；不 mutate completed facts
-loop-agent closeout task <task-id>                                    # 从 task artifacts 生成 docs/progress closeout
+loop-agent closeout task <task-id>                                    # 从 task artifacts 生成 ai_workspace/loop-agent/progress closeout
 loop-agent dag reconcile-tasks --glob '<pattern>' [--json|--markdown]  # 仅报告的 task/run/artifact/verify drift audit
 loop-agent dag final-verification <task-id> [--output <path>]  # 生成 closeout DAG；final verify 依赖 closeout artifact
 loop-agent dag decision inspect --run-id <run-id> [--node-id <node-id>]
@@ -213,11 +218,11 @@ review-heavy DAG 中长 shell stdout 可能掩盖 proof 时，用 **evidence-sum
 - **不要**期望 runner enforce、parse 或 validate `EVIDENCE:` 格式；**不要**在 `shell.verdictGate` 或 shell exit code 已够用时手写 shell grep `EVIDENCE:`。
 - read-only node 不得写 root `artifacts/**`；compact evidence 属于 `.harness/dag-runs/<run-id>/` 下归档的 node output。
 
-完整叙述：`docs/agent-dag-runner.md` §「Evidence Summary as a Practice Convention」。P1 calibration report：`docs/reports/2026-06-08-agent-dag-practice-p1-evidence-summary-docs.md`。
+完整叙述：`ai_workspace/loop-agent/agent-dag-runner.md` §「Evidence Summary as a Practice Convention」。P1 calibration report：`ai_workspace/loop-agent/reports/2026-06-08-agent-dag-practice-p1-evidence-summary-docs.md`。
 
 ### Authoring checklist（P1–P5 practice guidance — 非 runtime 行为）
 
-> 与 `docs/agent-dag-runner.md` §「Agent DAG authoring checklist」相同。Calibration reports：`docs/reports/2026-06-08-agent-dag-practice-p1-evidence-summary-docs.md` … `p5-handoff-closeout-20260608.md`。
+> 与 `ai_workspace/loop-agent/agent-dag-runner.md` §「Agent DAG authoring checklist」相同。Calibration reports：`ai_workspace/loop-agent/reports/2026-06-08-agent-dag-practice-p1-evidence-summary-docs.md` … `p5-handoff-closeout-20260608.md`。
 
 | # | Check | Expect |
 |---|-------|--------|
@@ -225,7 +230,7 @@ review-heavy DAG 中长 shell stdout 可能掩盖 proof 时，用 **evidence-sum
 | 2 | Executor | 每个 task 显式声明 `executor`；`defaults.executor` 是 schema metadata，非 runtime fallback |
 | 3 | Model routing | 用 node `complexity` + `executorModels`；Pi MED（`glm-5.2`）quota 耗尽时提高 Pi node 到 `complexity: HIGH`（`gpt-5.5`）— 勿 mutate canonical model matrix |
 | 4 | Read-only output | read-only / Pi node 在 **node output** 返回发现；runner 归档于 `.harness/dag-runs/<run-id>/<node-id>/` |
-| 5 | Root `artifacts/**` | 非 read-only handoff target；持久记录去 `docs/reports/`、`docs/progress/`，或 narrow exclusive `writeSet` 写 legacy 摘要并记录迁移计划 |
+| 5 | Root `artifacts/**` | 非 read-only handoff target；持久记录去 `ai_workspace/loop-agent/reports/`、`ai_workspace/loop-agent/progress/`，或 narrow exclusive `writeSet` 写 legacy 摘要并记录迁移计划 |
 | 6 | DAG Cursor artifacts | 写入 `.harness/dag-runs/<state>/<run-id>/artifacts/<node-id>/`；不得写入 `./artifacts/**` |
 | 7 | Completed facts | `.harness/dag-runs/completed/**` 仅可读 evidence — 归档后永不 mutate 历史 run 目录、`run.json`、`state.json` 或 `artifacts/**` |
 | 8 | Verdict gate | review/supervisor 应以 `VERDICT: pass` 或 `VERDICT: request-revision` 开头以利阅读；用 current-run `<fromNodeId>.json`（`$HARNESS_DAG_RUN_DIR`）上 `shell.verdictGate` block，exact-match `accept[]`；默认 `lineMode=first-non-empty`，supervised template 用 `first-verdict-line` 容忍 preamble 或第一条 normalized `VERDICT:` 前的常见整行 Markdown emphasis |

package/skills/loop-agent/references/multi-worktree.md

@@ -51,4 +51,4 @@ delegate --auto-run → Pi DAG 跑 contract/scout/plan/implement/verify → comp
 
 Agent DAG 是默认 autonomous path；`delegate`/`harvest` 提供 worktree 隔离与收口，`--auto-run` 仍只运行 Pi-only DAG。需要人工 Cursor 介入时使用独立的 `cursor-prompt` sidecar，不进入 delegate 或 DAG runtime。多 task 并行时，每个 task 独立 `delegate`，完成后分别 `harvest`。
 
-详见 `docs/cursor-prompt-sidecar.md` 与 `docs/loop-agent-harness.md`。
+详见 `ai_workspace/loop-agent/cursor-prompt-sidecar.md` 与 `ai_workspace/loop-agent/loop-agent-harness.md`。

package/skills/loop-agent/references/orchestrator-and-interventions.md

@@ -59,7 +59,7 @@ sidecar intervention 是一次性 Pi 或 Cursor prompt，用于 unblock 主 work
 
 - 同一 issue 不应反复 sidecar。若需要，pause 并 replan。
 - 可写 sidecar 须在 edit 后跑 targeted verification。
-- sidecar 发现须写入 task artifacts、DAG node artifacts、`docs/progress` 或 report 后再 resume。
+- sidecar 发现须写入 task artifacts、DAG node artifacts、`ai_workspace/loop-agent/progress` 或 report 后再 resume。
 - sidecar 输出为 advisory，直到 deterministic command 验证或并入 canonical workflow state。
 
 ### Agent DAG read-only artifact boundary
@@ -74,9 +74,9 @@ Agent DAG read-only node **不得**写 root `artifacts/`。
 
 **Linked skill-reference writeSet candidates**：DAG task 变更 workflow 语义（artifact boundary、verdict gate、evidence summary、intervention policy）时，scout node 应提议 `./skill/references/**` 下链接文件为 **writeSet expansion candidates**，而非仅 primary docs。P2 表明 implementer writeSet 遗漏 `hybrid-dag.md` 时，虽 scout 已发现 drift，仍须 post-DAG main-session patch。
 
-**Bounded main-session patch 须记录**：DAG run 中或之后任何可接受的 surgical patch（scope、变更文件、verification、rationale）应写入 `docs/reports/`、`docs/progress/` 或 active exec plan — 不可静默应用且无 audit trail。
+**Bounded main-session patch 须记录**：DAG run 中或之后任何可接受的 surgical patch（scope、变更文件、verification、rationale）应写入 `ai_workspace/loop-agent/reports/`、`ai_workspace/loop-agent/progress/` 或 active exec plan — 不可静默应用且无 audit trail。
 
-**勿把 root `artifacts/**` 当 read-only DAG handoff**（P3/P5）：即使 task 文本、scout 或 supervisor 讨论 `artifacts/修改记录.md` / `artifacts/验证结果.md`，read-only DAG node 只能在 node output 返回发现。root `artifacts/` 是 legacy / explicit-write 摘要区，不是 in-flight DAG node 的共享 scratchpad，也不是新工作流默认 handoff。post-DAG 持久 handoff 用 `docs/reports/`、`docs/progress/`、exec-plan 索引与 `.harness/dag-runs/completed/<run-id>/` node artifacts。
+**勿把 root `artifacts/**` 当 read-only DAG handoff**（P3/P5）：即使 task 文本、scout 或 supervisor 讨论 `artifacts/修改记录.md` / `artifacts/验证结果.md`，read-only DAG node 只能在 node output 返回发现。root `artifacts/` 是 legacy / explicit-write 摘要区，不是 in-flight DAG node 的共享 scratchpad，也不是新工作流默认 handoff。post-DAG 持久 handoff 用 `ai_workspace/loop-agent/reports/`、`ai_workspace/loop-agent/progress/`、exec-plan 索引与 `.harness/dag-runs/completed/<run-id>/` node artifacts。
 
 ### Completed run facts boundary（P3/P5）
 
@@ -97,10 +97,10 @@ main session 编排；不是默认 implementer。in-flight run 期间：
 |--------|------|----------|
 | Inspect status / node artifacts | 始终允许 | progress 或 sidecar output 中的 notes |
 | Sidecar read-only Pi/Cursor prompt | 诊断、plan critique、log 解读 | resume 前的 findings |
-| Surgical patch | small、obvious、可 verify；无 active `writeSet` 冲突 | `docs/reports/` 或 exec plan，含 scope + verification |
+| Surgical patch | small、obvious、可 verify；无 active `writeSet` 冲突 | `ai_workspace/loop-agent/reports/` 或 exec plan，含 scope + verification |
 | DAG/source repair | topology、writeSet 或 prompt contract 错误 | 编辑平台临时目录中的 DAG 或 plan；re-validate；rerun |
 | Approve/reject/resume | Decision Gate `pause-on-human` | 仅 CLI artifacts |
-| Post-DAG closeout | promotion、report、plan archive、indexes | `promote-run`、`closeout task`、`docs/reports/`、`docs/progress`、exec-plan indexes — 非 root `artifacts/`，除非 explicit narrow writeSet |
+| Post-DAG closeout | promotion、report、plan archive、indexes | `promote-run`、`closeout task`、`ai_workspace/loop-agent/reports/`、`ai_workspace/loop-agent/progress`、exec-plan indexes — 非 root `artifacts/`，除非 explicit narrow writeSet |
 
 **Verdict 与 Decision Gate 提醒**（authoring guidance，非 runtime 变更）：
 
@@ -108,7 +108,7 @@ main session 编排；不是默认 implementer。in-flight run 期间：
 - Decision Gate node：恰好一个 `DECISION_ENVELOPE_JSON` block；`audit.runId` 须为 **当前** run id（P4 misbind 教训；P5 fix）。
 - Pi MED quota 耗尽：提高 Pi node `complexity` 到 `HIGH`，而非改 `executorModels` 或加 auto-retry（P4）。
 
-完整 authoring checklist：`docs/agent-dag-runner.md` §「Agent DAG authoring checklist」与 `hybrid-dag.md` § Authoring checklist。
+完整 authoring checklist：`ai_workspace/loop-agent/agent-dag-runner.md` §「Agent DAG authoring checklist」与 `hybrid-dag.md` § Authoring checklist。
 
 ## Main-session surgical patch policy
 
@@ -165,5 +165,5 @@ Run DAG workflow
 
 每次 intervention 须留可恢复 trail：
 
-- Agent DAG：优先 node artifacts 于 `.harness/dag-runs/<state>/<run-id>/<node-id>/`；长期结论写入 `docs/progress`、`docs/reports` 或 `docs/exec-plans`。read-only node 不得写 root `artifacts/`。
-- Repo docs/skill workflow 变更：以 governance checks 结束，practice 变更时更新本 skill。
+- Agent DAG：优先 node artifacts 于 `.harness/dag-runs/<state>/<run-id>/<node-id>/`；长期结论写入 `ai_workspace/loop-agent/progress`、`ai_workspace/loop-agent/reports` 或 `ai_workspace/loop-agent/exec-plans`。read-only node 不得写 root `artifacts/`。
+- Repo ai_workspace/loop-agent/skill workflow 变更：以 governance checks 结束，practice 变更时更新本 skill。

package/skills/loop-agent/references/task-workflow.md

@@ -36,7 +36,7 @@ loop-agent run-dag --dag <temp-dir>/<task-id>-dag.json --cwd <repo-root>
 - 用户原始 PRD 用 `loop-agent import-prd <task-id> --file <prd>` 归档到 `source/references/`，禁止 AI 改写。
 - `需求.md` 是派生执行契约：写清目标、验收标准、非目标，并用 REQ/AC 或原文锚点映射回 references。
 - `执行约束.md` 写清允许文件、禁止改动、硬约束和验证命令。
-- 若 `docs/` 已有权威 plan/spec/PRD，优先 `import-prd` 复制，再在 `需求.md` 引用；避免把长 PRD 直接改写成唯一 source。
+- 若 `ai_workspace/loop-agent/` 已有权威 plan/spec/PRD，优先 `import-prd` 复制，再在 `需求.md` 引用；避免把长 PRD 直接改写成唯一 source。
 - Worker / TaskSpec materialize 路径会把 `source_docs` 复制到 `source/references/`，并在派生 `需求.md` 顶部声明“冲突以 references 为准”；`acceptance_refs` 应展开为短摘要而不只写 ID。
 - review 节点必须三方对照：`source/references/*`（尤其 requirement/acceptance）、派生 `需求.md`、以及实现/验证证据。
 

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

@@ -1,12 +1,12 @@
 # Verification 与失败处理
 
-选择 verify strategy knobs、解读 verify 结果、决定失败后是否继续，或 closeout workflow/runtime/docs/skill 变更时使用本文。
+选择 verify strategy knobs、解读 verify 结果、决定失败后是否继续，或 closeout workflow/runtime/ai_workspace/loop-agent/skill 变更时使用本文。
 
 ## Verify strategy 与 completion audit
 
 ## Production Readiness v0.1
 
-低/中风险单 repo DAG 任务如果声明 production-ready v0.1，必须按 `docs/production-readiness.md` 和 `docs/templates/production-readiness-checklist.md` 收口。
+低/中风险单 repo DAG 任务如果声明 production-ready v0.1，必须按 `ai_workspace/loop-agent/production-readiness.md` 和 `ai_workspace/loop-agent/templates/production-readiness-checklist.md` 收口。
 
 支持范围：
 
@@ -36,7 +36,7 @@ product_line_failure_category
 recommended_follow_up
 ```
 
-product-line taxonomy 的事实源是 `docs/design/state-and-failure-taxonomy.md`。
+product-line taxonomy 的事实源是 `ai_workspace/loop-agent/design/state-and-failure-taxonomy.md`。
 
 ### Verify 始终在本地跑
 `verify` step 跑确定性命令（check-repo.sh + tests + typecheck）。**不**调用 pi。因此快且可靠。
@@ -75,6 +75,8 @@ product-line taxonomy 的事实源是 `docs/design/state-and-failure-taxonomy.md
 ### 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，或按上述契约补齐修复节点，不要靠改节点名绕过。
+- `repair artifact field "rootCause" must be a non-empty string`：`request-revision` 的 `REPAIR_ARTIFACT_JSON.rootCause` 为空时 parser 不再容错，诊断必须明确根因。只有 `verdict: "pass"` 且 `rootCause` 为空白时才会被确定性规范化为 `No repair required.`，其余字段（fixScope、verdict mismatch、writer 边界）保持 fail-closed。
+- `missing DECISION_ENVELOPE_JSON fenced block` / `decision-envelope-invalid`：`DECISION_ENVELOPE_JSON` info string 的 Markdown 围栏必须存在且唯一。Parser 接受三反引号及更长围栏，但 opening/closing fence 必须同长度，closing 同行只能有空白；不匹配围栏、裸 JSON、多个围栏、malformed JSON、schema-invalid 与 semantic-invalid 仍 fail-closed。若错误 payload 含 `taskId`、`gate`、`verdict`、`summary` 或 `decision: proceed-to-closeout`，说明 decision prompt/schema 漂移；用包含 canonical schema 示例的当前 controller 重新生成 DAG，不要放宽 parser 接受 legacy 结构。
 - `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 保持只读。
 
@@ -128,7 +130,7 @@ child agent 失败时：
 - **意外残留**（tmp 文件、探索性 mock、scratch 输出）：handoff 前删除
 
 ### Closeout 规则
-workflow/runtime/docs/skill 变更结束时：
+workflow/runtime/ai_workspace/loop-agent/skill 变更结束时：
 ```bash
 loop-agent docs audit
 loop-agent handoff check <task-id>

package/skills/requesting-code-review/SKILL.md

@@ -55,7 +55,7 @@ HEAD_SHA=$(git rev-parse HEAD)
 
 [Dispatch code reviewer subagent]
   DESCRIPTION: Added verifyIndex() and repairIndex() with 4 issue types
-  PLAN_OR_REQUIREMENTS: Task 2 from docs/exec-plans/active/deployment-plan.md
+  PLAN_OR_REQUIREMENTS: Task 2 from ai_workspace/loop-agent/exec-plans/active/deployment-plan.md
   BASE_SHA: a7981ec
   HEAD_SHA: 3df7661
 

package/skills/systematic-debugging/CREATION-LOG.md

@@ -54,7 +54,7 @@ Framework 设计以 resist rationalization under pressure：
 
 ## Testing Approach
 
-按 skills/meta/testing-skills-with-subagents 创建 4 个 validation tests：
+按 .agents/skills/meta/testing-skills-with-subagents 创建 4 个 validation tests：
 
 ### Test 1: Academic Context (No Pressure)
 - Simple bug，无 time pressure
@@ -82,7 +82,7 @@ Framework 设计以 resist rationalization under pressure：
 - Flowchart for "fix failed" decision
 
 ### Enhancement 1: TDD Reference
-- Added link to skills/testing/test-driven-development
+- Added link to .agents/skills/testing/test-driven-development
 - Note explaining TDD's "simplest code" ≠ debugging's "root cause"
 - Prevents confusion between methodologies
 
@@ -104,7 +104,7 @@ Bulletproof skill that:
 ## Usage Example
 
 遇到 bug 时：
-1. Load skill: skills/debugging/systematic-debugging
+1. Load skill: .agents/skills/debugging/systematic-debugging
 2. Read overview (10 sec) — reminded of mandate
 3. Follow Phase 1 checklist — forced investigation
 4. If tempted to skip — see anti-pattern，stop

package/skills/systematic-debugging/SKILL.md

@@ -284,7 +284,7 @@ NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
 - **`condition-based-waiting.md`** — 用 condition polling 替代 arbitrary timeouts
 
 **Related principles:**
-- **RED-GREEN-REFACTOR**（见 `docs/harness-methodology-tdd.md`）— 用于 creating failing test case（Phase 4, Step 1）
+- **RED-GREEN-REFACTOR**（见 `ai_workspace/loop-agent/harness-methodology-tdd.md`）— 用于 creating failing test case（Phase 4, Step 1）
 - **Verification discipline** — 宣称 success 前 verify fix worked。Run verification command，读 output，THEN claim result。
 
 ## Real-World Impact

package/skills/systematic-debugging/test-academic.md

@@ -1,6 +1,6 @@
 # Academic Test: Systematic Debugging Skill
 
-You have access to the systematic debugging skill at skills/debugging/systematic-debugging
+You have access to the systematic debugging skill at .agents/skills/debugging/systematic-debugging
 
 Read the skill and answer these questions based SOLELY on what the skill says:
 

package/skills/systematic-debugging/test-pressure-1.md

@@ -2,7 +2,7 @@
 
 **IMPORTANT: This is a real scenario. You must choose and act. Don't ask hypothetical questions - make the actual decision.**
 
-You have access to: skills/debugging/systematic-debugging
+You have access to: .agents/skills/debugging/systematic-debugging
 
 ## Scenario
 

package/skills/systematic-debugging/test-pressure-2.md

@@ -2,7 +2,7 @@
 
 **IMPORTANT: This is a real scenario. You must choose and act. Don't ask hypothetical questions - make the actual decision.**
 
-You have access to: skills/debugging/systematic-debugging
+You have access to: .agents/skills/debugging/systematic-debugging
 
 ## Scenario
 

package/skills/systematic-debugging/test-pressure-3.md

@@ -2,7 +2,7 @@
 
 **IMPORTANT: This is a real scenario. You must choose and act. Don't ask hypothetical questions - make the actual decision.**
 
-You have access to: skills/debugging/systematic-debugging
+You have access to: .agents/skills/debugging/systematic-debugging
 
 ## Scenario
 

package/skills/verification-before-completion/SKILL.md

@@ -118,7 +118,7 @@ Skip any step = lying, not verifying
 - **Contract changes** → 验证 contract docs 已更新 + tests 对齐
 - **Handoff** → 宣称 complete 前运行 `handoff check`
 
-完整 command 选择见项目 `docs/verification-matrix.md`。
+完整 command 选择见项目 `ai_workspace/loop-agent/verification-matrix.md`。
 
 ## Why This Matters