@tea-agent/loop-agent 0.13.0-alpha.0 → 0.13.0

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

@@ -9,12 +9,16 @@
 - `defaultImplementationWorkflow=agent-dag`
 - `dag.defaultEntry=dag run-task`
 - `dag.outputLanguage=zh-CN`；未配置时也默认中文，显式设为 `en` 可切换英文
-- `dag.profileRouting`：`minimal|standard -> standard-dag`，`reviewed -> review-gated-dag`，`supervised -> supervised-implementation`
+- `dag.profileRouting`：通用候选映射为 `minimal|standard -> standard-dag`、`reviewed -> review-gated-dag`、`supervised -> supervised-implementation`
 - `humanGatePolicy.defaultMode=record-only`；需求不清、架构/公共契约风险、凭据/费用/部署风险、重复 gate failure 或高风险决策时升级人工介入
 
 此 policy 驱动 `dag run-task --profile auto`：CLI 仍要求显式 `dag run-task`、`dag validate`、`run-dag`，但 `--profile auto` 在确定性 candidate `governanceProfile` 推断后应用 `workflowPolicy.dag.profileRouting`。生成器还会把 `outputLanguage` 写入 DagSpec，runner 在每个 Pi/Cursor 节点 prompt 中注入语言规则；代码、命令、路径、JSON 字段与 gate token 保持原样。`humanGatePolicy` 是默认人机边界声明；真实暂停仍由 DAG 节点的 `decisionGate.mode: "pause-on-human"` 与 decision envelope 触发。无 profile 的 `dag run-task <task-id>` 仍为 standard-compatible，供 legacy/review workflow。
 
-`task.json.taskKind` 负责选择业务专用模板，不扩充 governance profile：`frontend-implementation` 选择前端实现 DAG，`backend-test` 选择后端测试 DAG。后端测试链为 `analyze-inputs-pi → generate-backend-functional-cases-pi → review-backend-cases-pi → review-backend-cases-gate-shell → generate-backend-pytest-pi → execute-backend-pytest-shell → test-retrospect-pi`，治理等级仍由既有 `minimal|standard|reviewed|supervised` 规则推断。
+对于默认 `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`。
+
+显式专用 `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 层级
 
@@ -39,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）：
 
@@ -60,7 +64,7 @@ loop-agent run-dag --dag <temp-dir>/hybrid-dag.json --init-only --canvas-path <t
 **运维 warning**：
 
 - **常规 validation**：`dag validate --dag <path>` 做 schema/topology/ranks。JSON 输出含 `governanceProfile`（确定性 `minimal|standard|reviewed|supervised` 推断，含 `process` / `delivery` / `codeChange` signal 与 `reasons`），及 model-matrix drift、governance lint（如 read-only artifact-boundary drift 或 DAG 内 `check-repo.sh` shell env drift）的 warnings。手写临时 DAG spec 执行前用 `dag validate --dag <path> --strict-models`；governance warning 应 fail fast 时加 `--strict-governance`。含 `executor: "cursor"` 的旧 DAG 会在 schema 校验失败；默认生成 DAG 使用 `pi` read-only / Pi write profile / shell。仅当有意在 `.harness/dag-runs/active/` 要 active run snapshot 时用 `run-dag --dry-run`。
-- **Governance profile 推断与 routing（code vs skill 分工）**：`./src/workflows/dag/governance-profile.ts` 从 DAG 结构与 write scope 做 **硬确定性推断**。JSON 输出 **报告** `process` / `delivery` / `codeChange` signal 与人类可读 `reasons`；`profile` tier（`minimal|standard|reviewed|supervised`）仅由该模块 code rule 选择（如多个 exclusive writer、repair node、review-gate topology、`loop-agent-runtime-paths`、`scripts-ci-harness-paths`、weak post-implementation shell verification、supervised topology）。baseline `forbiddenPaths`（`.harness/**`、`.harness/dag-runs/**`、`artifacts/**`）是默认 governance，**本身不是** process-risk signal。skill prompt 与本 reference **解释** tier 并摘要 profile 选择原因；不替代 code 推断。`dag run-task` 转发 embedded validate step 的同一 candidate `governanceProfile`。`dag run-task --profile auto` 先将 candidate profile 经 `harness.json.workflowPolicy.dag.profileRouting` 映射，再在 candidate delivery signal 含 `loop-agent-runtime-paths`、`scripts-ci-harness-paths` 或 `public-contract-paths` 时应用 M4 `supervised-quality-gate` promotion；`profileRouting.routingReasons` 记录确定性 reason。无 profile `dag run-task <task-id>` 仍为 standard-compatible；显式 `--profile minimal|standard|reviewed|supervised` 强制对应 template family（当前 policy 下 minimal/standard 路由到 `standard-dag`），高风险 task 应用 `--profile auto` 或显式 `--profile supervised`，而非显式 `--profile reviewed`。
+- **Governance profile 推断与 routing（code vs skill 分工）**：`./src/workflows/dag/governance-profile.ts` 从 DAG 结构与 write scope 做 **硬确定性推断**。JSON 输出 **报告** `process` / `delivery` / `codeChange` signal 与人类可读 `reasons`；`profile` tier（`minimal|standard|reviewed|supervised`）仅由该模块 code rule 选择（如多个 exclusive writer、repair node、review-gate topology、`loop-agent-runtime-paths`、`scripts-ci-harness-paths`、weak post-implementation shell verification、supervised topology）。baseline `forbiddenPaths`（`.harness/**`、`.harness/dag-runs/**`、`artifacts/**`）是默认 governance，**本身不是** process-risk signal。skill prompt 与本 reference **解释** tier 并摘要 profile 选择原因；不替代 code 推断。`dag run-task` 转发 embedded validate step 的同一 candidate `governanceProfile`。`dag run-task --profile auto` 先将 candidate profile 经 `harness.json.workflowPolicy.dag.profileRouting` 映射，再在 candidate delivery signal 含 `loop-agent-runtime-paths`、`scripts-ci-harness-paths` 或 `public-contract-paths` 时应用 M4 `supervised-quality-gate` promotion；`profileRouting.routingReasons` 记录确定性 reason。无 profile `dag run-task <task-id>` 仍为 standard-compatible；显式 `--profile minimal|standard|reviewed|supervised` 选择治理路由的通用候选模板，默认 `standard` 前端任务可在非 supervised 候选上选择前端专用模板，但自动分类不得替换 supervised 候选。高风险 task 应用 `--profile auto` 或显式 `--profile supervised`，而非显式 `--profile reviewed`。
 - **Executor model routing**：DAG spec 选 `executor` 与 `complexity`，可通过 `executorModels.pi` 覆盖 model 名；不选 provider。默认 routing：Pi LOW=`gpt-5.3-codex-spark`、MED=`glm-5.2`、HIGH=`gpt-5.5`。`shell` 不用 model，忽略 `executorModels`。
 - **Active visibility**：真实 `run-dag` execution 在 run/node 转换时写 active `state.json`，归档前 core runner 暴露 isolated `DagRunObserver` hook 供 derived view。`.harness/dag-runs/completed/<run-id>/` / `paused/<run-id>/` 仍是 source of truth；observer 输出非 canonical。
 - **可选 Canvas**：传 `--canvas-path <abs-path>` 或 `--canvas <name>` 输出 derived `.canvas.tsx` live view。省略 flag 行为不变。`--init-only` + Canvas 无需 `CURSOR_API_KEY`。
@@ -75,20 +79,23 @@ loop-agent run-dag --dag <temp-dir>/hybrid-dag.json --init-only --canvas-path <t
 - **Defaults  caveat**：`defaults.skills` / `defaults.writePolicy` 生效。对 `cursor` / `pi` node，resolved skill 名亦由 DAG runner 映射为有界 inline `SKILL.md` instruction，审计于 `<node>/skills.json`；Pi 仍以 `noSkills` / `--no-skills` 运行，故非 Pi ResourceLoader loading。`defaults.executor`、`defaults.model`、`defaults.piBackend`、`defaults.contextProfile` 接受/保留但尚非 runtime default。runtime execution 用 node `executor` + node `complexity`；各 executor 内部自选 model。live contract 已移除 `models`；executor-specific routing 用 `executorModels`。
 - **默认无**跨 node Pi runtime reuse；各 Pi node 是独立 `executePiStep()` call。
 - **Prompt source**：每个 task 仅用一种 prompt source。v1-compatible DAG 用 inline `subtask_prompt`；markdown-backed prompt 用 canonical `subtask_prompt_markdown`。同时提供两字段、皆不提供、或用连字符 alias `subtask_prompt-markdown` 均 fail fast。
+- **Source binding / recovery**：新生成 DAG 在顶层冻结 `sourceBinding`（任务源相对路径、SHA-256、显式 `REQ/BR/AC`）。前端计划在存在显式编号时经过 `frontend-requirement-coverage-shell`；缺号会在 final design review/writer 前 fail closed。中断后重新生成完整 DAG，不要从二手摘要拼接 impl-only DAG；v3 孤立 exclusive writer 若无 `sourceBinding` 且没有只读 planner 上游，会被 strict governance 拒绝。
 - **勿宣称 live smoke 已通过**，除非真实 `run-dag` execution 中 Pi read-only、Pi writer、显式 Cursor 或 shell node 均按 DAG 完成。
 
-可复用 template：`docs/templates/agent-dag.base.json`（model 生成 DAG 的首选 base template）、`docs/templates/agent-dag.schema.json`（JSON Schema）、`docs/templates/agent-dag.supervised-implementation.json`（supervised implementation：writeSet audit、soft/hard verify、process supervisor、repair、review verdict gate）、`docs/templates/backend-test-dag.json`（后端测试专用模板）、`docs/templates/agent-dag-process-supervisor.prompt.md`、`docs/templates/agent-dag-review-verdict.prompt.md`、`docs/templates/agent-dag-authority-surface-audit.prompt.md`（可选 authority surface verifier；authority signal 或显式 enablement 匹配时由 `dag init-hybrid` 插入）、`examples/hybrid-loop-agent-dag.json`、`docs/templates/hybrid-dag.json`。
+可复用 template：`docs/templates/agent-dag.base.json`（model 生成 DAG 的首选 base template）、`docs/templates/agent-dag.schema.json`（JSON Schema）、`docs/templates/agent-dag.supervised-implementation.json`（supervised implementation：writeSet audit、soft/hard verify、process supervisor、repair、review verdict gate）、`docs/templates/backend-test-dag.json`（后端测试专用模板）、`docs/templates/frontend-test-dag.json`（FE-test RAG：Markdown case manifest、串行 Playwright CLI case 子节点与逐 case 证据）、`docs/templates/agent-dag-process-supervisor.prompt.md`、`docs/templates/agent-dag-review-verdict.prompt.md`、`docs/templates/agent-dag-authority-surface-audit.prompt.md`（可选 authority surface verifier；authority signal 或显式 enablement 匹配时由 `dag init-hybrid` 插入）、`examples/hybrid-loop-agent-dag.json`、`docs/templates/hybrid-dag.json`。
 
 ### Supervised implementation flow（减少 main-session intervention）
 
-长时 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]  # 可选
@@ -97,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`） |
@@ -113,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 节点安全重试」）。
 
@@ -123,10 +133,10 @@ Prompt invariant：`docs/templates/agent-dag-process-supervisor.prompt.md`、`do
 loop-agent dag init-hybrid <task-id> [--output <temp-dir>/<task-id>-hybrid-dag.json]
 loop-agent dag run-task <task-id> [--output <temp-dir>/<task-id>-hybrid-dag.json]   # 安全默认：仅 generate + validate，standard-compatible
 loop-agent dag run-task <task-id> --profile auto                                # 推断 candidate governanceProfile，再经 workflowPolicy 路由
-loop-agent dag run-task <task-id> --profile minimal                             # 强制当前 minimal 路由（standard-dag）
-loop-agent dag run-task <task-id> --profile standard                            # 强制 standard-dag
-loop-agent dag run-task <task-id> --profile reviewed                            # 强制 review-gated DAG
-loop-agent dag run-task <task-id> --profile supervised                          # 强制 supervised implementation DAG
+loop-agent dag run-task <task-id> --profile minimal                             # 选择 minimal 通用路由；standard 前端任务可自动使用前端 DAG
+loop-agent dag run-task <task-id> --profile standard                            # 选择 standard 通用路由；standard 前端任务可自动使用前端 DAG
+loop-agent dag run-task <task-id> --profile reviewed                            # 选择 reviewed 通用路由；standard 前端任务可自动使用前端 DAG
+loop-agent dag run-task <task-id> --profile supervised                          # 选择 supervised DAG；自动前端分类不会降级它
 loop-agent dag run-task <task-id> --strict-models                              # 非 canonical executorModels 时失败
 loop-agent dag run-task <task-id> --execute --cwd <repo-root>                        # 要求 narrowed implement writeSet
 loop-agent dag run-task <task-id> --dry-run --cwd <repo-root>                        # active snapshot 于 .harness/dag-runs/active/
@@ -139,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` | 行为 |
 |-----------|---------------------|----------|
@@ -164,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>]
@@ -208,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 |
 |---|-------|--------|
@@ -220,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>