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

package/skills/loop-agent/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: loop-agent
 description: >-
-  Use when implementing features, processing PRDs or requirements, running structured loop-agent workflows, creating harness tasks, using Agent DAG, run-dag, pi-prompt planning/review, cursor-prompt one-shot sidecar intervention, or converging website/governance docs after user-visible changes in loop-agent. Triggers: loop-agent, workflow, structured development, harness task, Agent DAG, docs converge, Converge Docs, 文档收敛, 结构化开发, 工作流, 需求实现, PRD 实现.
+  Use when implementing features, processing PRDs or requirements, running structured loop-agent workflows, creating harness tasks, using Agent DAG, run-dag, pi-prompt planning/review, cursor-prompt one-shot sidecar intervention, initializing a target project with loop-agent, checking init update status, applying a safe init update, or converging website/governance docs after user-visible changes in loop-agent. Triggers: loop-agent, workflow, structured development, harness task, Agent DAG, docs converge, Converge Docs, 文档收敛, 结构化开发, 工作流, 需求实现, PRD 实现, 初始化 loop-agent, loop agent 初始化, loop agent初始化, loop-agent 初始化, 初始化更新校验, loop agent初始化更新校验, 检查初始化更新, 初始化安全更新, loop agent初始化安全更新, 应用初始化更新.
 references:
   - path: references/harness-policy.md
     required: true
@@ -19,7 +19,7 @@ references:
 
 ## Canonical Harness Policy
 
-Shared loop-agent harness workflow 规则见 `references/harness-policy.md`。Repo-local `docs/loop-agent-harness.md` / `specs/loop-agent-harness.md` 应保持为 local runtime path、governance root、verification commands 的 thin adapters。
+Shared loop-agent harness workflow 规则见 `references/harness-policy.md`。Repo-local `ai_workspace/loop-agent/loop-agent-harness.md` / `specs/loop-agent-harness.md` 应保持为 local runtime path、governance root、verification commands 的 thin adapters。
 
 ## 默认立场
 
@@ -29,7 +29,7 @@ Shared loop-agent harness workflow 规则见 `references/harness-policy.md`。Re
 - `pi-prompt` 与 `cursor-prompt` 都是一次性 full-capability helper；用作 sidecar 时必须在 prompt 和 tool/model 参数里显式收窄。
 - Cursor 仅是显式、手工触发的 `cursor-prompt` one-shot sidecar，不是受治理 DAG/Loop writer；受治理写入固定为 `implement-pi` / `repair-pi`，必须给出 allowed / forbidden paths 与 writeSet。
 - Shell verification 是事实源；任何完成声明都必须有本轮命令输出。
-- 长期结论写回 `docs/exec-plans/`、`docs/reports/`、`docs/progress/` 或 `./skill/`。
+- 长期结论写回 `ai_workspace/loop-agent/exec-plans/`、`ai_workspace/loop-agent/reports/`、`ai_workspace/loop-agent/progress/` 或 `./skill/`。
 
 ## 唯一推荐执行路径
 
@@ -70,7 +70,7 @@ loop-agent run-dag --dag <temp-dir>/<task-id>-dag.json --cwd <repo-root>
 
 需要写代码时，默认使用 DAG `pi` executor 的 write tool profile（`implement-pi` / `repair-pi`）。Pi writer 节点必须包含 task id、目标、allowed paths、forbidden paths、writeSet、硬约束和预期验证，并在执行后由主会话独立运行 shell verification。
 
-`cursor-prompt` 仅作人工 one-shot sidecar intervention，不进入 Loop auto-execute / Delegate auto-run / DAG writer 选择。细节见 `docs/cursor-prompt-sidecar.md`、`references/harness-policy.md` 和 `references/verification-and-failure-handling.md`。
+`cursor-prompt` 仅作人工 one-shot sidecar intervention，不进入 Loop auto-execute / Delegate auto-run / DAG writer 选择。细节见 `ai_workspace/loop-agent/cursor-prompt-sidecar.md`、`references/harness-policy.md` 和 `references/verification-and-failure-handling.md`。
 
 Pi writer prompt（以及可选 sidecar prompt）都必须包含：
 
@@ -92,7 +92,7 @@ bounded writer 完成后，主会话必须独立复核；命令清单见 `refere
 |---|---|
 | Long-Running Loop（`loop` init/status/run/record-round/add-signal/closeout、auto mode、signals） | `references/long-running-loop.md` |
 | Three-Pass Convergence、repair artifact、spine audit、knowledge curate、SePO-lite prompt evolution | `references/harness-policy.md` |
-| Operator commands（status/doctor/report/closeout/promote/inspect/spine/knowledge/docs/handoff） | `references/command-reference.md` |
+| Operator commands（status/doctor/report/closeout/promote/inspect/spine/knowledge/ai_workspace/loop-agent/handoff） | `references/command-reference.md` |
 | 伴生 CLI `agent-worker`（TaskSpec / Task Pool / batch / morning report） | `references/command-reference.md` |
 | Post-writer 独立验证、verify knobs、failure handling、closeout | `references/verification-and-failure-handling.md` |
 | Docs Converge（用户可见变更后的站上/治理文档同步检查表） | `references/docs-converge.md` |

package/skills/loop-agent/references/README.md

@@ -9,7 +9,7 @@ failure handling 与 workflow 细节放在这里，避免主 skill 变成百科
 1. 先读 `../SKILL.md`，确认当前任务是否真的需要 `loop-agent`。
 2. 根据任务类型只打开相关 reference，不要一次加载整个目录。
 3. 执行时遵循 Agent DAG 路径；历史顺序式 `run ...` workflow 已移除。
-4. 如果 reference 与 `harness.json` 或 repo-local `docs/loop-agent-harness.md` / `specs/loop-agent-harness.md` 冲突，以
+4. 如果 reference 与 `harness.json` 或 repo-local `ai_workspace/loop-agent/loop-agent-harness.md` / `specs/loop-agent-harness.md` 冲突，以
    `harness.json` 的机器可读 policy 和本目录的 shared policy 为准，并回头修正文档漂移。
 
 ## 快速路由
@@ -51,7 +51,7 @@ failure handling 与 workflow 细节放在这里，避免主 skill 变成百科
 
 - `references/harness-policy.md` 是 shared workflow policy source，供多个 repo 的 thin adapter docs 引用。
 - `../SKILL.md` 是 skill trigger 与 routing source，不承载长流程细节。
-- `docs/loop-agent-harness.md` / repo-local `specs/loop-agent-harness.md` 是本仓库或目标仓库的 adapter 文档：只描述 runtime 位置、governance root、验证入口和本地边界。
+- `ai_workspace/loop-agent/loop-agent-harness.md` / repo-local `specs/loop-agent-harness.md` 是本仓库或目标仓库的 adapter 文档：只描述 runtime 位置、governance root、验证入口和本地边界。
 - `harness.json` 是 workflowPolicy、script entrypoints、artifacts 目录与 model routing 的机器可读 source of truth。
 - `.harness/tasks/<task-id>/` 是 task 运行态状态；不要把运行态事实写进本目录。
 - `.harness/runs/completed/<run-id>/` 是 one-shot tool run evidence；reference 文档只能解释如何读取和 promotion，不应复制 run facts。
@@ -64,4 +64,4 @@ failure handling 与 workflow 细节放在这里，避免主 skill 变成百科
 - 新 reference 应有清晰标题、触发场景、最小步骤、失败处理和维护边界。
 - 如果某个 reference 变成可独立触发、跨项目通用且不再依赖本仓库上下文，再考虑拆成独立 skill。
 - 更新 command、workflow policy 或 verification 规则时，同步核对 `harness.json`、`references/harness-policy.md`、repo-local harness adapter docs 和 verification matrix。
-- `~/.pi/agent/skills/loop-agent` 是指向本目录的 symlink，所以仓库内 edits 会直接更新 Pi skill。
+- `~/.pi/agent/.agents/skills/loop-agent` 是指向本目录的 symlink，所以仓库内 edits 会直接更新 Pi skill。

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

@@ -25,7 +25,7 @@ loop-agent doctor
 
 发布包入口加载 `dist/cli.js`；开发入口加载 `src/cli.ts`。
 
-发布包携带静态能力资料：`skills/`、`docs/*.md`、`docs/templates/` 和 `examples/`。`docs/progress/`、`docs/reports/`、`docs/exec-plans/`、`docs/decisions/` 的任务正文属于目标仓库运行中生成的事实，不从 npm 包复制；包内只保留这些目录的 README 说明。
+发布包携带静态能力资料：`.agents/skills/`、`ai_workspace/loop-agent/*.md`、`ai_workspace/loop-agent/templates/` 和 `examples/`。`ai_workspace/loop-agent/progress/`、`ai_workspace/loop-agent/reports/`、`ai_workspace/loop-agent/exec-plans/`、`ai_workspace/loop-agent/decisions/` 的任务正文属于目标仓库运行中生成的事实，不从 npm 包复制；包内只保留这些目录的 README 说明。
 
 ## 命令参考
 
@@ -41,8 +41,14 @@ loop-agent doctor
    loop-agent run-dag --dag <temp-dir>/<task-id>-dag.json --cwd <repo-root>
    ```
    `<temp-dir>` 表示平台原生临时目录；也可以省略 `--output`，再使用命令 JSON 输出里的 `outputPath`。主路径 JSON 输出含稳定 summary：`dag run-task` 的 `message` 为 `DAG draft created`，`dag validate` 的 `message` 为 `DAG validation passed` 且含 `checks.writeSets` / `checks.decisionGates`，`run-dag` 的 `message` 为 `DAG run finished`。
-2. **Operator 工具**，用于 recovery、诊断与 closeout：
+2. **Operator 工具**，用于 recovery、诊断、评测重放与 closeout：
    ```bash
+   loop-agent eval replay --spec <path> --json
+   loop-agent eval report --replay-id <id> --markdown
+   loop-agent eval candidate register --manifest <path> --json
+   loop-agent eval candidate show --candidate-id <id> --json
+   loop-agent eval candidate list --json
+   loop-agent eval candidate transition --candidate-id <id> --to <state> --reason <text> --json
    loop-agent dag status --run-id <run-id>
    loop-agent dag doctor
    loop-agent dag report --latest --markdown
@@ -55,7 +61,7 @@ loop-agent doctor
    loop-agent promote-run <task-id> --run-id <run-id>
    loop-agent closeout task <task-id>
    loop-agent spine audit <task-id> --markdown
-   loop-agent knowledge curate --markdown --output docs/reports/<task-id>-learned-proposal.md
+   loop-agent knowledge curate --markdown --output ai_workspace/loop-agent/reports/<task-id>-learned-proposal.md
    loop-agent loop-benchmark --markdown
    ```
 3. **Escape hatch**，仅用于 worktree 隔离委派、executor 调试或 one-shot 诊断：
@@ -94,6 +100,15 @@ export CODE_AGENT_PI_BACKEND=cli-only    # 紧急回滚：纯 CLI 路径
 SDK 回归或 SDK 可选依赖不可用时用 `cli-only` 诊断。CLI fallback 路径须与现有 workflow 行为兼容。
 
 ### 初始化与旧项目更新
+
+用户中文表达到命令的映射（与目标项目 `AGENTS.md` 的“自然语言入口路由”保持一致）：
+
+| 用户表达 | 命令 |
+|---|---|
+| loop-agent 初始化 / loop agent 初始化 / loop agent初始化 / 初始化 loop-agent | 先运行 `loop-agent init instructions --repo-root .`，再运行 `loop-agent init --repo-root . --profile full --merge`，随后补全 README/验证矩阵并复查 doctor/inspect/docs audit |
+| 初始化更新校验 / loop agent初始化更新校验 / 检查初始化更新 | `loop-agent init check-update --repo-root . --markdown`（只读，不得隐含 `apply-safe`） |
+| 初始化安全更新 / loop agent初始化安全更新 / 应用初始化更新 | 先 `loop-agent init check-update --repo-root . --markdown`，再 `loop-agent init update --repo-root . --apply-safe`（surface 缺失时先 `--bootstrap-surface`；human decisions 存在时停下等用户） |
+
 ```bash
 loop-agent init instructions --repo-root <target-repo>
 loop-agent init --repo-root <target-repo> --profile full --merge
@@ -126,7 +141,7 @@ loop-agent new-task <task-id> "Task Title"
 
 ### 导入原始 PRD（不可变事实源）
 ```bash
-loop-agent import-prd <task-id> --file docs/path/to-prd.md [--name requirement] [--json]
+loop-agent import-prd <task-id> --file ai_workspace/loop-agent/path/to-prd.md [--name requirement] [--json]
 ```
 
 把用户原始 PRD **原样复制** 到 `.harness/tasks/<task-id>/source/references/`，并写入 `source/source-manifest.json`（含 SHA-256）与 `task.json.referenceDocs`。此步骤不调用模型、不改写内容。随后再写派生的 `source/需求.md` 执行契约；冲突时以 `source/references/*` 为准。
@@ -149,7 +164,7 @@ loop-agent promote-run <task-id> --run-id <run-id>
 loop-agent closeout task <task-id>
 ```
 
-`promote-run` 从 completed DAG facts 或 one-shot completed run evidence 生成 task `修改记录.md` / `验证结果.md`，不调用 LLM、不修改 completed run facts。`closeout task` 从 task artifacts 生成 `docs/progress/YYYY-MM-DD-<slug>.md`，验证证据不足时必须写明剩余风险。
+`promote-run` 从 completed DAG facts 或 one-shot completed run evidence 生成 task `修改记录.md` / `验证结果.md`，不调用 LLM、不修改 completed run facts。`closeout task` 从 task artifacts 生成 `ai_workspace/loop-agent/progress/YYYY-MM-DD-<slug>.md`，验证证据不足时必须写明剩余风险。
 
 one-shot run evidence 位于 `.harness/runs/{active,completed,failed}/<run-id>/`。`cursor-prompt` 与 Pi `cursor` tool 会创建这类 run evidence；当前 `pi-prompt` 不创建 `.harness/runs/`。active 目录只应保留 live one-shot run，残留或 `.DS_Store` 等系统文件应清理。详见 `one-shot-runs.md`。
 
@@ -225,8 +240,8 @@ loop-agent dag validate --dag <temp-dir>/hybrid-dag.json --strict-models # 非 c
 loop-agent dag validate --dag <temp-dir>/hybrid-dag.json --strict-governance # governance warning 时失败
 loop-agent dag validate --dag <temp-dir>/hybrid-dag.json --strict-skills # missing/error/truncated skill 或 unresolved reference 时失败
 loop-agent dag validate --dag <temp-dir>/hybrid-dag.json --strict-governance --spine-task <task-id> # 同时消费 minimal spec spine audit
-loop-agent dag validate --dag docs/templates/agent-dag.supervised-implementation.json --strict-models --strict-governance  # role=supervisor + write-set-gate topology
-cp docs/templates/agent-dag.supervised-implementation.json <temp-dir>/supervised-dag.json
+loop-agent dag validate --dag ai_workspace/loop-agent/templates/agent-dag.supervised-implementation.json --strict-models --strict-governance  # role=supervisor + write-set-gate topology
+cp ai_workspace/loop-agent/templates/agent-dag.supervised-implementation.json <temp-dir>/supervised-dag.json
 (npx vitest run test/dag-supervised-template.test.ts test/dag-validate.test.ts test/dag-shell-executor.test.ts --reporter=dot)  # supervised template + shell.verdictGate runtime
 loop-agent run-dag --dag <temp-dir>/hybrid-dag.json --cwd <repo-root>          # 执行 Agent DAG
 loop-agent run-dag --dag <temp-dir>/hybrid-dag.json --init-only --canvas-path <temp-dir>/hybrid-dag.canvas.tsx # 可选 derived Canvas view
@@ -236,15 +251,15 @@ loop-agent dag workflow-plan <task-id> --profile pr-review --output <temp-dir>/<
 loop-agent dag workflow-validate --workflow <temp-dir>/<task-id>.workflow.json --strict-governance
 loop-agent dag workflow-compile --workflow <temp-dir>/<task-id>.workflow.json --output <temp-dir>/<task-id>-dag.json --manifest <temp-dir>/<task-id>-compile-manifest.json
 loop-agent dag run-task <task-id> --profile auto         # 推断 governanceProfile，经 workflowPolicy.dag.profileRouting 路由
-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 implementation DAG；自动前端分类不会降级它
 loop-agent dag run-task <task-id> --execute --cwd <repo-root>  # generate + validate + execute（先 narrow writeSet）
 loop-agent dag run-task <task-id> --dry-run --cwd <repo-root>  # generate + validate + active dry-run snapshot
 loop-agent dag status --run-id <run-id>                  # 单次 run JSON 摘要（approvalFlow, healthIssues）
 loop-agent dag doctor                                    # 扫描 active/paused/completed runs；advisoryOnly health report
-loop-agent dag report [--run-id <run-id>] [--lifecycle active|paused|completed|all] [--json|--markdown] [--failed-only] [--latest] [--paused-latest] [--action <recovery-action>]  # derived per-node 聚合（只读）；JSON 锁定于 docs/templates/agent-dag-report.schema.json；--paused-latest 聚焦最新 paused run；playbook: docs/agent-dag-recovery-playbook.md
+loop-agent dag report [--run-id <run-id>] [--lifecycle active|paused|completed|all] [--json|--markdown] [--failed-only] [--latest] [--paused-latest] [--action <recovery-action>]  # derived per-node 聚合（只读）；JSON 锁定于 ai_workspace/loop-agent/templates/agent-dag-report.schema.json；--paused-latest 聚焦最新 paused run；playbook: ai_workspace/loop-agent/agent-dag-recovery-playbook.md
 loop-agent dag reconcile-run --run-id <run-id>            # 只读检查 effectiveStatus 与恢复/收口资格
 loop-agent dag reconcile-run --run-id <run-id> --action supersede --reason "..." # 显式保留证据并标记为任务已另行完成
 loop-agent dag reconcile-run --run-id <run-id> --action abandon --reason "..."   # 显式保留证据并收口为已放弃
@@ -264,19 +279,21 @@ loop-agent dag resume --run-id <run-id>                  # approve 后继续
 - `dag validate` 做 schema/topology/ranks 检查；审 `warnings` 中的显式 `executorModels` drift 与 governance lint。
 - 手写临时 DAG spec 执行前用 `dag validate --strict-models`，model-matrix drift 应 fail fast。
 - read-only artifact-boundary 或 DAG 内 shell governance warning 应 fail fast 时用 `dag validate --strict-governance`。
-- 人工 handoff 视图用 `dag report --markdown`（summary、node timeline、failures、四段 Recovery Plan、artifacts、建议 next action）。仅 derived、advisory；需保存时重定向到平台临时目录或 `docs/reports/`。
+- 人工 handoff 视图用 `dag report --markdown`（summary、node timeline、failures、四段 Recovery Plan、artifacts、建议 next action）。仅 derived、advisory；需保存时重定向到平台临时目录或 `ai_workspace/loop-agent/reports/`。
 - operator 聚焦最新 paused run 用 `dag report --paused-latest`（等同 `--lifecycle paused --latest`；勿与显式 `--lifecycle` 并用）。
-- 需 operator 关注的 run 用 `dag report --failed-only`、`--latest`、`--action <recovery-action>` 收窄。category→action 映射见 `docs/agent-dag-recovery-playbook.md`。
+- 需 operator 关注的 run 用 `dag report --failed-only`、`--latest`、`--action <recovery-action>` 收窄。category→action 映射见 `ai_workspace/loop-agent/agent-dag-recovery-playbook.md`。
 - 只读扫描 `.harness/dag-runs/` 下所有 run 的生命周期 health issue 与建议 action 用 `dag doctor`（`advisoryOnly: true`；不 mutate facts）。
 - approve/resume 前用 `dag status --run-id <id>` 看单次 lifecycle、`approvalFlow`、`hasHumanApproval`。
 - lifecycle、raw status 与 liveness 冲突时先用 `dag reconcile-run --run-id <id>` 只读检查。只有 runner 已证明停止且 operator 明确给出 `supersede|abandon` 与 reason 时才允许收口；它保存原始 state，不把未执行节点标成成功。
 - task status、source/artifacts、DAG outcome、verification 记录可能 drift 时用 `dag reconcile-tasks --glob '<pattern>'`。默认仅报告；`--patch` 显式且不能伪造 verification evidence。
 - 大型 PRD closeout 用 `dag final-verification <task-id>` 生成确定性 DAG，final verification 在 closeout artifact 创建之后。
 - 从 run facts dry-run envelope 解析用 `dag decision inspect|validate`；`validate` 在无效 envelope 时 exit 1；永不自动 resume/retry。
-- Decision Gate prompt 可用 `buildDagDecisionGateEvidence()`（`src/workflows/dag/decision-evidence.ts`）做与 `dag report --json`、`docs/templates/agent-dag-report.schema.json` 对齐的只读摘要；不 mutate run state，不执行 retry/resume。
+- Decision Gate prompt 可用 `buildDagDecisionGateEvidence()`（`src/workflows/dag/decision-evidence.ts`）做与 `dag report --json`、`ai_workspace/loop-agent/templates/agent-dag-report.schema.json` 对齐的只读摘要；不 mutate run state，不执行 retry/resume。
 - 仅当有意在 `.harness/dag-runs/active/` 下要 active run snapshot 时用 `run-dag --dry-run`。
-- task source 应从 `harness.json.workflowPolicy.dag.profileRouting` 与确定性 candidate `governanceProfile` 选 standard / review-gated / supervised template 时用 `dag run-task --profile auto`。无 `--profile` 仅用于旧 standard-compatible 输出；强制 template family 用 `--profile minimal|standard|reviewed|supervised`。
-- 业务专用 DAG 通过 `task.json.taskKind` 选择，不扩充 governance profile：`frontend-implementation` 选择前端实现模板，`backend-test` 选择需求分析 → 功能用例 → 评审 → pytest 生成/执行 → 复盘的后端测试模板。
+- task source 应从 `harness.json.workflowPolicy.dag.profileRouting` 与确定性 candidate `governanceProfile` 选择通用候选模板时用 `dag run-task --profile auto`。无 `--profile` 仅用于旧 standard-compatible 输出；`--profile minimal|standard|reviewed|supervised` 选择治理路由，其中 supervised 模板不会被自动前端分类替换。
+- 默认 `standard` 任务会根据标题、`source/需求.md` 和结构化 `allowedPaths` 做保守、确定性的需求分类。只有高置信的前端实现需求自动选择 `frontend-implementation`；后端、前后端混合、明确排除前端或无法可靠判断的需求保留 governance profile 选出的模板，绝不自动进入 `backend-test`。显式 profile、`workflowPolicy` 或 supervised quality gate 已选中 supervised 时，自动分类不得降低治理等级。
+- 新生成 DAG 会冻结任务源路径、SHA-256 和显式 `REQ/BR/AC` 到 `sourceBinding`。前端计划漏号时 `frontend-requirement-coverage-shell` 在 writer 前阻断。中断恢复应修复 task source 后重新运行 `dag run-task`，不要生成只携带上游摘要的 impl-only DAG；strict governance 会拒绝无来源绑定且无只读 planner 上游的 v3 孤立 writer。
+- 显式专用 `taskKind` 保持兼容并优先于任务源分类，也不扩充 governance profile：`frontend-implementation` 可有意覆盖为带 Mock 规范评估、contract gate、design gate 和验证链的前端模板；可选 `frontendMock` 配置 auto/required/disabled、既有服务目录和专项验证命令，required 合同不完整时不会生成 writer。`backend-test` 显式选择需求分析 → 功能用例 → 评审 → pytest 生成/执行 → 复盘的后端测试工程模板。
 
 ### Saved Dynamic Workflow operator UX
 ```bash
@@ -292,7 +309,51 @@ loop-agent workflow replay <run-id>
 
 ### Cursor sidecar
 
-`cursor-worker` 已删除。人工干预使用 `cursor-prompt` one-shot sidecar；见 `docs/cursor-prompt-sidecar.md`。
+`cursor-worker` 已删除。人工干预使用 `cursor-prompt` one-shot sidecar；见 `ai_workspace/loop-agent/cursor-prompt-sidecar.md`。
+
+### Eval Replay（M1，只读 completed evidence）
+
+```bash
+loop-agent eval replay --spec <replay-spec.json> [--json|--markdown] [--output <path>]
+loop-agent eval report --replay-id <id> [--json|--markdown]
+```
+
+`eval replay` 只读取 `.harness/dag-runs/completed/<runId>/state.json` 与 `run.json`，要求 spec 携带两者的 SHA-256，hash 不一致时 fail closed。它将 completed DAG report 归一化为 verification、Token、耗时、executor calls、repair passes，并把 canonical scorecard 写到 `.harness/evaluation/replays/<replayId>/`。缺失 Token/耗时记录为 `null + missingFields`，不会补造为 0。
+
+M1 是 replay-only：不执行 Pi、不启动 DAG、不实现 private verifier、固定预算 enforcement 或 candidate promotion；所有 scorecard 固定 `promotionEligible=false` 且包含 `replay_only`。
+
+### Eval Candidate Registry（M2 W2.1–W2.2）
+
+```bash
+loop-agent eval candidate register --manifest <candidate-manifest.json> [--json|--markdown]
+loop-agent eval candidate show --candidate-id <id> [--json|--markdown]
+loop-agent eval candidate list [--json|--markdown]
+loop-agent eval candidate transition --candidate-id <id> --to <state> --reason <text> [--json|--markdown]
+```
+
+注册不可变 Candidate Bundle 到 `.harness/evaluation/candidates/<candidateId>/`（`manifest.json` + append-only `lifecycle.jsonl`）。`bundleHash` 由 canonical payload 计算，与 `candidateId`/createdAt/lifecycle 分离；content refs 必须为 repo-relative safe path，且不得进入 evaluator/kernel/completed-facts 等 forbidden surface。`accepted` 仅是 registry 状态，**不**移动 incumbent alias、不 promotion。
+
+Replay spec 最小结构：
+
+```json
+{
+  "schemaVersion": 1,
+  "replayId": "context-policy-replay-001",
+  "incumbentCandidateId": "baseline",
+  "challengerCandidateId": "role-context-v1",
+  "evidence": [
+    {
+      "candidateId": "baseline",
+      "taskRef": "task-a",
+      "seed": 1,
+      "split": "private",
+      "runId": "completed-run-id",
+      "stateSha256": "<64 hex>",
+      "runSha256": "<64 hex>"
+    }
+  ]
+}
+```
 
 ### 检查 task status
 ```bash
@@ -302,7 +363,7 @@ loop-agent status <task-id>
 ### Docs governance helpers
 ```bash
 loop-agent docs audit
-loop-agent docs archive docs/exec-plans/active/<plan>.md
+loop-agent docs archive ai_workspace/loop-agent/exec-plans/active/<plan>.md
 loop-agent plan list
 loop-agent plan create <plan-id> "<title>"
 loop-agent plan complete <plan-id> --summary "<summary>"
@@ -323,11 +384,11 @@ loop-agent handoff coverage <task-id> [--json|--markdown]
 ### Pi runtime reuse benchmark / decision（无 live call）
 ```bash
 loop-agent pi-reuse-benchmark \
-  --report docs/reports/<benchmark-report>.md \
+  --report ai_workspace/loop-agent/reports/<benchmark-report>.md \
   --json
 
 loop-agent pi-reuse-benchmark \
-  --report docs/reports/<benchmark-report>.md \
+  --report ai_workspace/loop-agent/reports/<benchmark-report>.md \
   --off-executor /path/to/off/executor.jsonl \
   --on-executor /path/to/on/executor.jsonl \
   --approval /path/to/approval.json \
@@ -339,7 +400,7 @@ loop-agent pi-reuse-benchmark \
 ### Loop convergence benchmark baseline（无 live call）
 ```bash
 loop-agent loop-benchmark --markdown
-loop-agent loop-benchmark --markdown --output docs/reports/2026-06-30-loop-agent-loop-benchmark.md
+loop-agent loop-benchmark --markdown --output ai_workspace/loop-agent/reports/2026-06-30-loop-agent-loop-benchmark.md
 ```
 
 生成 M0 deterministic baseline，对照 `single-repair`、`3-pass-convergence`、`3-pass-convergence+quota`。**不**跑 live Pi/Cursor call、不创建 task、不改 `convergence.enabled` 默认值。live dogfood 证据缺失时输出 `blocked` 并建议保持 opt-in。
@@ -370,11 +431,24 @@ loop-agent spine audit <task-id> --markdown
 ### Knowledge curator proposal
 ```bash
 loop-agent knowledge curate --markdown
-loop-agent knowledge curate --markdown --output docs/reports/<task-id>-learned-proposal.md
+loop-agent knowledge curate --markdown --output ai_workspace/loop-agent/reports/<task-id>-learned-proposal.md
 ```
 
 读取 `.harness/knowledge/patterns.jsonl` 中 completed convergence repair pattern，按 `failureClass + fixScope shape + invariant` 去重，生成 human-gated learned guidance proposal。命令只生成 proposal，不直接修改 `./skill/references/learned/*.md`；输出会先通过 skill safety audit。
 
+### Knowledge graph / query CLI
+```bash
+loop-agent knowledge graph-init --product-name <name>
+loop-agent knowledge graph-materialize
+loop-agent knowledge graph-promote
+loop-agent knowledge graph-incremental-prepare --feature F-2026-004 --service <service>
+loop-agent knowledge query --mode by_feature --feature F-2026-004 --json
+loop-agent knowledge query --mode by_id --id SVC-order --json
+loop-agent knowledge query --mode search --text "keyword" --json
+```
+
+这些子命令是 package-backed 公共入口，封装包内 knowledge runtime 资产。目标项目应使用 `loop-agent knowledge ...`，不要要求仓库内直接运行未投影的 package-only kb runtime scripts。Feature 测试知识日常写回用 `task.json.taskKind = "knowledge-sync"`（必须绑定 `featureId`）；业务图谱开荒/增量用 `taskKind = "knowledge-graph-bootstrap"`。
+
 ### Worker TaskSpec pipeline（伴生 CLI `agent-worker`）
 
 `agent-worker` 是与 `loop-agent` 一起发布的独立 CLI（`bin/agent-worker.js -> dist/worker/cli.js`），面向“产品线 Worker”场景：把一批 TaskSpec 规约成可校验、可串行调度、可晨报的流水线。它不进入 `loop-agent` 命令树，也不自带 executor——执行权全部通过子进程委托给已发布的 `loop-agent` CLI（最终是 DAG runtime + shell verification）。
@@ -439,7 +513,7 @@ loop-agent harvest <task-id> [--squash] [--no-archive] [--keep-worktree]
 loop-agent worktree create|list|remove ...
 ```
 
-用于 worktree 隔离以及可选的 Pi-only DAG 执行与 merge 收口。常规 autonomous work 应优先 Agent DAG；详见 `multi-worktree.md` 与 `docs/cursor-prompt-sidecar.md`。
+用于 worktree 隔离以及可选的 Pi-only DAG 执行与 merge 收口。常规 autonomous work 应优先 Agent DAG；详见 `multi-worktree.md` 与 `ai_workspace/loop-agent/cursor-prompt-sidecar.md`。
 
 ### One-shot Cursor sidecar（escape hatch）
 ```bash

package/skills/loop-agent/references/docs-converge.md

@@ -3,7 +3,7 @@
 本 reference 把会话协议中的 **Converge Docs** 落成可执行检查表。
 定位是**收敛 / 同步**，不是「每次重新 invent 文档大纲」。
 
-权威规划：`docs/exec-plans/completed/2026-07-14-website-docs-ia-and-converge.md`。
+权威规划：`ai_workspace/loop-agent/exec-plans/completed/2026-07-14-website-docs-ia-and-converge.md`。
 站与治理双树边界：`website/README.md`。
 
 ## 何时触发
@@ -12,7 +12,7 @@
 
 - 用户可见行为变更（CLI 输出、默认工作流、init 投影、Observe/Worker 主路径）。
 - 新增 / 修改 / 删除 CLI 命令或关键 flags。
-- runtime / 架构边界变更（`docs/architecture/*`、executor 角色、Worker 边界）。
+- runtime / 架构边界变更（`ai_workspace/loop-agent/architecture/*`、executor 角色、Worker 边界）。
 - active plan 创建、blocked、完成或归档。
 - 准备发布或写 `CHANGELOG.md` 版本条目。
 - 用户明确要求「文档收敛」「docs converge」「同步 website docs」。
@@ -24,9 +24,9 @@
 
 | 受众 | 主要入口 | 权威细节 |
 | --- | --- | --- |
-| 新贡献者 | `website/docs/intro.md` → `overview/architecture` → `overview/roadmap` → first-run | 根 `docs/architecture/*`、active plans |
+| 新贡献者 | `website/docs/intro.md` → `overview/architecture` → `overview/roadmap` → first-run | 根 `ai_workspace/loop-agent/architecture/*`、active plans |
 | 使用者 | `overview/feature-map`、`quick-start/*`、`guides/*`、`reference/*` | CLI help、根 `CHANGELOG.md` |
-| 维护者 / agent | 本检查表 + `AGENTS.md` Converge Docs | `docs/`、`skills/`、`scripts/check-*.sh` |
+| 维护者 / agent | 本检查表 + `AGENTS.md` Converge Docs | `ai_workspace/loop-agent/`、`.agents/skills/`、`scripts/check-*.sh` |
 
 ## 页面清单（站上活文档）
 
@@ -34,7 +34,7 @@
 | --- | --- |
 | `website/docs/intro.md` | 概念地图 + 30 分钟路径；非能力堆砌 |
 | `website/docs/overview/feature-map.md` | 功能导览 → guide/CLI |
-| `website/docs/overview/architecture.md` | 架构导读；链到 `docs/architecture/` |
+| `website/docs/overview/architecture.md` | 架构导读；链到 `ai_workspace/loop-agent/architecture/` |
 | `website/docs/overview/roadmap.md` | 当前有效规划短索引 |
 | `website/docs/quick-start/*` | 安装 / init / first-run |
 | `website/docs/guides/*` | 主路径操作说明 |
@@ -50,26 +50,26 @@
 
 | 若变更了… | 必须检查 / 更新 |
 | --- | --- |
-| 新/改 CLI 命令 | `website/docs/reference/cli.md` + `skills/loop-agent/references/command-reference.md`（及 agent-worker 相关 reference） |
+| 新/改 CLI 命令 | `website/docs/reference/cli.md` + `.agents/skills/loop-agent/references/command-reference.md`（及 agent-worker 相关 reference） |
 | 用户可见行为 | 对应 `guides/*` 或 `quick-start/*`；根 `CHANGELOG.md`；必要时 `overview/feature-map.md` / `intro.md` |
-| runtime / 边界 | 根 `docs/architecture/*`；站上 `overview/architecture.md` 导语与外链 |
+| runtime / 边界 | 根 `ai_workspace/loop-agent/architecture/*`；站上 `overview/architecture.md` 导语与外链 |
 | 默认工作流 | `intro.md` 流程图 + `guides/agent-dag.md` / `guides/harness-policy.md` |
-| active plan 状态 | `overview/roadmap.md` 短索引 + `docs/exec-plans/active/README.md` |
+| active plan 状态 | `overview/roadmap.md` 短索引 + `ai_workspace/loop-agent/exec-plans/active/README.md` |
 | 发布 | 根 `CHANGELOG.md` 为版本事实源；`website/docs/changelog.md` 只写摘要与链接；roadmap 仅在规划状态变化时更新 |
-| skill / init 投影 | `docs/init-surface.manifest.json`、相关测试、必要时 `docs/skills/*` |
+| skill / init 投影 | `ai_workspace/loop-agent/init-surface.manifest.json`、相关测试、必要时 `ai_workspace/loop-agent/.agents/skills/*` |
 
 跨树链接规则：
 
 - 站内页面用 Docusaurus 相对文档链接。
-- 链到根目录 `docs/`、`AGENTS.md`、`CHANGELOG.md` 等时，使用
+- 链到根目录 `ai_workspace/loop-agent/`、`AGENTS.md`、`CHANGELOG.md` 等时，使用
   `https://github.com/tea-agent/loop-agent/blob/main/<repo-path>`，
-  正文同时写出 repo-relative path；禁止伪造站内 `/docs/architecture/...` 作为根目录文档路由。
+  正文同时写出 repo-relative path；禁止伪造站内 `/ai_workspace/loop-agent/architecture/...` 作为根目录文档路由。
 
 ## 执行步骤（最小闭环）
 
 1. **列出本轮用户可见 diff**（命令、行为、边界、计划状态）。
 2. **对照上表**产出缺口清单（页面路径 + 要改的一句话）。
-3. **最小补丁**：只改清单内页面；禁止顺手重写 practices 或迁移整个 `docs/`。
+3. **最小补丁**：只改清单内页面；禁止顺手重写 practices 或迁移整个 `ai_workspace/loop-agent/`。
 4. **验证**（见下节）。
 5. **Handoff** 二选一：
    - 已更新：列出改动页面与验证命令结果。
@@ -103,11 +103,11 @@ npx vitest run test/init-command.test.ts test/package-surface.test.ts
 ## 禁止事项
 
 - 每次会话从头撰写全新文档大纲或「重新规划整个 docs 树」。
-- 把 `docs/design/`、exec-plans、reports 全文复制进 `website/docs/`。
-- 在站上建立第二套与 `docs/architecture/*` 冲突的架构真源。
+- 把 `ai_workspace/loop-agent/design/`、exec-plans、reports 全文复制进 `website/docs/`。
+- 在站上建立第二套与 `ai_workspace/loop-agent/architecture/*` 冲突的架构真源。
 - 未读 `website/README.md` 与相关 exec-plan 就扩大 scope。
 - 用删测试、降 `onBrokenMarkdownLinks` 或忽略 `docs:build` 失败制造「完成」。
-- 新增独立公共 skill 目录承载本检查表（应留在 `skills/loop-agent/references/`）。
+- 新增独立公共 skill 目录承载本检查表（应留在 `.agents/skills/loop-agent/references/`）。
 
 ## 与现有能力的关系
 

package/skills/loop-agent/references/harness-policy.md

@@ -70,9 +70,9 @@ loop-agent run-dag \
 
 `loop-agent` is the preferred global CLI. For self-hosting loop-agent development, the controller must be an installed npm-published package. Use `npm install -g @tea-agent/loop-agent@latest` for first install or intentional upgrades, then treat the installed version as frozen for the current task and record `npm list -g @tea-agent/loop-agent --depth=0`. Do not repeatedly fetch `npx @latest` inside DAG nodes, and do not use the current working tree's `npm link` or `npm run dev` to control tasks that may edit CLI, DAG runtime, executors, package metadata, or build output. Use `npm run dev -- <args>` only for source debugging and focused CLI development.
 
-The npm package carries static capability assets: `skills/`, top-level governance docs, `docs/templates/`, `examples/`, `harness.json`, `AGENTS.md`, `README.md`, and `CHANGELOG.md`. Generated or historical task facts under `docs/progress/`, `docs/reports/`, `docs/exec-plans/`, and `docs/decisions/` belong to the target repository; package only their directory README files, not prior run content.
+The npm package carries static capability assets: `.agents/skills/`, top-level governance docs, `ai_workspace/loop-agent/templates/`, `examples/`, `harness.json`, `AGENTS.md`, `README.md`, and `CHANGELOG.md`. Generated or historical task facts under `ai_workspace/loop-agent/progress/`, `ai_workspace/loop-agent/reports/`, `ai_workspace/loop-agent/exec-plans/`, and `ai_workspace/loop-agent/decisions/` belong to the target repository; package only their directory README files, not prior run content.
 
-For arbitrary target repositories, DAG skill instructions must not depend on loop-agent source history being copied into the target repo. Resolve configured, user, or target-local skills when present, then fall back to package-bundled `skills/` as the stable default capability set.
+For arbitrary target repositories, DAG skill instructions must not depend on loop-agent source history being copied into the target repo. Resolve configured, user, or target-local skills when present, then fall back to package-bundled `.agents/skills/` as the stable default capability set.
 
 `<temp-dir>` means the platform-native temp directory. Use native paths for actual `--output`, `--dag`, and `--cwd` values on macOS and Windows; use `/` only for stable repo refs, JSON/Markdown evidence refs, and glob conventions.