@tea-agent/loop-agent 0.1.0-fe-test.0

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

@@ -0,0 +1,175 @@
+# Main Orchestrator、Agent DAG 与受控干预
+
+协调长时 loop-agent work、判断 main session 是否可 edit、在 Agent DAG / one-shot Cursor / one-shot Pi 间选择，或在不失 auditability 的情况下恢复 in-flight workflow 时使用本文。
+
+## 核心立场
+
+**Agent DAG 优先，main session = Compatibility / Operator Assist，executor 经 CLI 实现，shell 验证。**
+
+`harness.json.workflowPolicy` 的 repo 级 policy 将 Agent DAG 作为 autonomous 与 harness-governed work 的 implementation workflow。历史顺序式 `run ...` workflow 已移除。
+
+main session 是 decision-maker 与 scheduler，**不是** implementer。稀缺 context 只用于 objective 对齐、调用 `loop-agent` / `agent-worker`、DAG/writeSet review、failure triage、verification review 与 handoff。长时 implementation 必须委派给 Pi-only Agent DAG node（经 CLI）、shell verification 或 worktree `delegate`；Cursor 仅显式 one-shot sidecar。
+
+**严禁**主会话绕过 CLI 直接改业务实现，或在 DAG/worker 失败后「救火改文件」。宿主 Edit/Write 不是受治理恢复路径。
+
+## 默认执行模型
+
+| Actor | 主角色 | 避免 |
+| --- | --- | --- |
+| Main session (Operator Assist) | Objective、contract、**CLI 编排**、DAG review、routing、failure triage（doctor/reconcile）、approve/reject/resume、shell verify、handoff | 成为 coder；绕过 CLI 写业务树；失败后直接 Edit |
+| Agent DAG runner | 可恢复 multi-node orchestration、write policy、run artifacts | 不更新 DAG/source 的 ad-hoc replanning |
+| Cursor one-shot prompt | 显式有界诊断/介入；非默认 | 当 DAG executor、自动写入、无 path scope 宽写、失败默认恢复 |
+| Pi executor / prompt | DAG 内 scouting/planning/review/write profile；sidecar 只读诊断 | 充当 hidden state；主会话假装自己是 Pi writer |
+| Shell executor | 确定性验证事实 | 智能 repair |
+| Human gate | Product、architecture、risk、permission | 常规 implementation debugging |
+
+## 入口选择
+
+**Agent DAG**（`task advance` → review/writeSet → `dag execute`）为默认，用于 autonomous implementation、workflow/harness/docs governance 变更、multi-file work，或任何受益于多 executor、parallel scout、显式 write policy、shell evidence、review gate、Decision Gate 的工作。
+
+**supervised Agent DAG** 用于 `governanceProfile=supervised`，或工作触及 loop-agent runtime、scripts/CI、schema/public contract、多个 exclusive writer、repair flow 或 high-cost path。
+
+**one-shot Pi / Cursor prompt** 仅作受控 sidecar intervention，不是 workflow state source，也不是 CLI 失败后的默认出口。
+
+**main-session 直接写业务实现：默认禁止。** 仅治理/脚手架层面的极窄修正见下文「允许的 operator 写入」；功能实现、bugfix、多文件逻辑变更必须走 DAG CLI。
+
+## Sidecar intervention 协议
+
+sidecar intervention 是一次性 Pi 或 Cursor prompt，用于 unblock 主 workflow。
+
+调用前说明：
+
+1. 观察到什么问题。
+2. 为何当前 DAG/step 不应盲目继续。
+3. sidecar 是 read-only 还是可写文件。
+4. 可写工作的精确 allowed/forbidden paths。
+5. 预期输出及记录位置。
+
+典型 routing：
+
+| 情况 | 使用 |
+| --- | --- |
+| 需 quick root-cause analysis、plan critique、log 解读 | one-shot Pi prompt，read-only |
+| 需 codebase-indexed multi-file 诊断或 bounded patch | one-shot Cursor prompt |
+| 需确定性 evidence | shell command / shell DAG node |
+| DAG topology、writeSet 或 source contract 错误 | stop/revise DAG 或 source；不要绕开 patch |
+| requirement、architecture 或 risk 决策不清 | Decision Gate / human approval |
+
+规则：
+
+- 同一 issue 不应反复 sidecar。若需要，pause 并 replan。
+- 可写 sidecar 须在 edit 后跑 targeted verification。
+- 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
+
+Agent DAG read-only node **不得**写 root `artifacts/`。
+
+- root `artifacts/修改记录.md` 与 `artifacts/验证结果.md` 是 legacy / explicit-write 摘要；不是 per-node 不可变历史，也不是新工作流默认交付路径。
+- Agent DAG node 发现属于 node output 与 runner-owned artifacts，位于 `.harness/dag-runs/<state>/<run-id>/<node-id>/`；Cursor 节点的 `修改记录.md` / `验证结果.md` 位于 `.harness/dag-runs/<state>/<run-id>/artifacts/<node-id>/`。
+- 不要把 root `artifacts/` 当作所有 DAG node 的共享 state 交集；`.harness/dag-runs/<run-id>/` 才是 DAG state 交集。
+- `./artifacts/**` 不是 DAG artifact 位置；出现该目录通常表示 Cursor prompt 没有收到 DAG-owned artifact dir。
+- 若必须更新 root `artifacts/`，用显式 write-capable DAG node；不要用主会话「顺手写 root artifacts」代替节点。
+
+**Linked skill-reference writeSet candidates**：DAG task 变更 workflow 语义时，scout 应提议 `skills/loop-agent/references/**` 为 **writeSet expansion candidates**，并在下一轮 DAG 中写入，而不是 post-DAG 由主会话大段补写 skill。
+
+**允许的 operator 写入必须记录**：若发生下文极窄 operator 文件维护，须在 `ai_workspace/loop-agent/reports/`、`progress/` 或 exec plan 留下 scope + verification — 不可静默、不可当作实现完成。
+
+**勿把 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）
+
+`.harness/dag-runs/completed/<run-id>/` 是 canonical per-run 历史。视为 **只读 evidence**，不是可写 workflow state。
+
+- **允许**：读 node JSON、`result.summary.md`、decision envelope、shell stdout、随 run directory 归档的 `artifacts/<node-id>/修改记录.md` / `验证结果.md`，用于 review、Decision Gate 或 post-DAG closeout。
+- **禁止**：run 归档到 `completed/` 后再追加或改写 side file；mutate 历史 `run.json` / `state.json` / `artifacts/**`；把 completed facts 当作 revision DAG 的 write target。
+- **Recovery**：revision DAG 需要 prior evidence 时，在 node output 或 main-session report 中消费 — 不要 in-place patch completed 目录。
+- **Promotion**：需要把 completed DAG 或 one-shot run evidence 汇总为 task artifacts 时，用 deterministic `promote-run <task-id> --run-id <run-id>`；需要长期 progress 时再用 `closeout task <task-id>`。这两个命令消费历史 facts，但不修改历史 facts。
+
+P5 验证：future agent 可从 practice report + completed node artifacts 继续，无需 root `artifacts/**` 摘要。
+
+### Agent DAG run 中的 main-session intervention
+
+main session 编排；不是默认 implementer。in-flight run 期间：
+
+| Action | 何时 | 记录位置 |
+| -------- | ------ | ---------- |
+| Inspect status / node artifacts | 始终允许 | progress 或 sidecar output 中的 notes |
+| Sidecar read-only Pi/Cursor prompt | 诊断、plan critique、log 解读 | resume 前的 findings |
+| Surgical patch | **不适用于** exclusive writer（如 `implement-pi` / `repair-pi`）active 期间的工作区写；仅当无 active exclusive writer、变更极窄且可 verify 的治理元数据时才可考虑 | `ai_workspace/loop-agent/reports/` 或 exec plan，含 scope + verification |
+| DAG/source repair | topology、writeSet 或 prompt contract 错误；writer 非 active 时修正元数据 | 编辑平台临时目录中的 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`、`ai_workspace/loop-agent/reports/`、`ai_workspace/loop-agent/progress`、exec-plan indexes — 非 root `artifacts/`，除非 explicit narrow writeSet |
+
+**Live-run 纪律（与目标项目 AGENTS managed block 同口径）**：
+
+- Operator 须持续监控 run，直到 controller 报告 run 已结束（节点/流程终态如 `FINISHED`、`FAILED` 或 `partial_failed`），或 Decision Gate **需要 approve**；不要在节点仍运行时假定完成。
+- 判活须组合 runner heartbeat、session events 与 `dag doctor` liveness/provider meaningful progress；Runner heartbeat 只证明 lease，alone ≠ progress。
+- exclusive writer 运行期间：主会话与其他 writer **不得并发修改工作区**，以免 write-guard 错误归因；只读 status/doctor/report/observe/console 与 approve/reject/resume CLI 仍允许。
+
+**Verdict 与 Decision Gate 提醒**（authoring guidance，非 runtime 变更）：
+
+- `shell.verdictGate` 后的 review/supervisor node：首条非空行须精确为 `VERDICT: pass` 或 `VERDICT: request-revision`（P2/P4）。
+- 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：`ai_workspace/loop-agent/agent-dag-runner.md` §「Agent DAG authoring checklist」与 `hybrid-dag.md` § Authoring checklist。
+
+## 允许的 operator 写入（极窄；默认仍走 CLI）
+
+主会话**默认零业务写权限**。下列**全部**成立时，才允许维护**治理/任务元数据**（不是产品功能实现）：
+
+1. 变更不触及业务功能逻辑；通常是 task source、DAG JSON typo、doc index、或删除 scratch。
+2. 原因已知；不需要 broad system understanding。
+3. 不改变 product requirement 语义、architecture、public API、data model 或 cross-platform contract。
+4. 不与 active DAG exclusive `writeSet` 冲突；且 exclusive writer 运行期间**一律禁止**主会话/其他 writer 并发改工作区（不仅是路径重叠判断），以免 write-guard 错误归因。
+5. 可立即 shell verify。
+6. 记录 scope + verification；且**下一步仍是 CLI re-validate / rerun**，不是「主会话继续实现」。
+
+好例子：
+
+- 修 DAG JSON path / schema typo 后 `dag validate` + `dag execute`。
+- 修正 doc index link 或 typo。
+- 删除明显 out-of-scope 的生成 scratch。
+- 补全 `source/执行约束.md` 中的 allowedPaths 列表后 regenerate DAG。
+
+坏例子（**一律禁止**）：
+
+- CLI/DAG 失败后主会话直接改 `src/**`「救火」。
+- 手工按计划实现功能或修测试失败。
+- 改 API/contract 语义或 refactor 子系统。
+- 编辑 in-flight exclusive DAG node 拥有的实现文件。
+- exclusive writer active 时主会话或其他 writer 并发修改工作区（即使自认无 writeSet 冲突）。
+- 用 `cursor-prompt` / 宿主 Write 代替 `implement-pi` / `repair-pi`。
+
+失败默认序列（替代旧 surgical-patch 心智）：
+
+```text
+1. dag doctor / dag report / status
+2. 分类失败；需要时 reconcile-run 或 human gate
+3. 仅当 source/DAG 包错误时最小修正元数据
+4. dag validate → dag execute / worker 重试
+5. shell verification
+6. 记录 evidence；禁止主会话实现收尾
+```
+
+## 失败状态机
+
+```text
+Run DAG workflow (via loop-agent / agent-worker CLI)
+  -> success: shell verify -> handoff
+  -> node/step failure: diagnose with doctor/report
+       -> transient/tool issue: CLI retry or explicit read-only sidecar advice -> verify -> resume
+       -> bounded implementation issue: DAG repair-pi / re-run writer via CLI（禁止主会话 Edit 实现）
+       -> DAG design/source issue: stop -> fix DAG/source metadata -> validate -> rerun
+       -> requirement/architecture issue: Decision Gate / human approval -> resume/reject
+  -> verification failure: CLI bounded repair loop 或 replan；永不主会话手改冒充完成
+```
+
+## 记录要求
+
+每次 intervention 须留可恢复 trail：
+
+- 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/pi-prompt.md

@@ -0,0 +1,23 @@
+# One-shot Pi SDK Prompt Helper（`pi-prompt`）
+
+短时 Pi SDK task、不需要完整 `.harness/tasks/<id>` workflow 时使用本文。替代 ad-hoc 临时代码脚本导入 `executeSingleSdkAttempt` 的做法。
+
+### One-shot Pi SDK prompt helper
+
+短时 Pi SDK task、不需要完整 `.harness/tasks/<id>` workflow 时，用 `loop-agent pi-prompt`，勿创建 ad-hoc 临时代码脚本导入 `executeSingleSdkAttempt`。`pi-prompt` 是一次性 full-capability helper；是否只读由本次调用的 prompt 与 `--tools` 决定。
+
+```bash
+loop-agent pi-prompt "Reply with exactly OK."
+loop-agent pi-prompt --stdin < <temp-dir>/task.md
+loop-agent pi-prompt --file <temp-dir>/task.md
+loop-agent pi-prompt --cwd ~/go/src/loop-agent --tools read,grep,find,ls "Review the current diff. Do not edit files."
+loop-agent pi-prompt --cwd ~/go/src/loop-agent --tools subagent,read --timeout 2400000 "Use subagent exactly once ..."
+loop-agent pi-prompt --model gpt-5.5 --cwd ~/go/src/loop-agent "Deeply diagnose this failure."
+loop-agent pi-prompt "Reply with exactly OK."
+```
+
+`<temp-dir>` 表示平台原生临时目录；实际命令中使用本机路径。
+
+默认：`--provider wizard-local --model glm-5.2`；高复杂度 one-shot 可显式 `--model gpt-5.5`。按需用 `--provider`、`--model`、`--thinking`、`--tools`、`--timeout` 覆盖。
+
+`pi-prompt` 仅用于 quick one-shot SDK call。**不**创建 `.harness/tasks/`、不跑 verification、不写 handoff artifact、不保留 workflow state。须可恢复、可验证的 implementation work 用 DAG 路径；需要隔离写入时使用 bounded Cursor 或 `delegate`。

package/skills/loop-agent/references/pi-subagent-assisted-mode.md

@@ -0,0 +1,84 @@
+# Pi Subagent Assisted Mode
+
+loop-agent task 启用 `piSubagentMode`、在 analyze/plan/spec/retrospective 内需要 read-only scout/planner/reviewer subagents，或配置 project-local agents/prompts 时使用本文。
+
+`task.json` 支持可选字段 `piSubagentMode`，用于 step 级 `subagent` tool delegation：
+
+| Mode | analyze | plan | spec | implement | retrospective | verify |
+|------|---------|------|------|-----------|----------------|--------|
+| `off`（默认） | read only | read only | read only | +write/edit/bash | read only | read only |
+| `analyze-plan` | **+subagent** | **+subagent** | **+subagent** | 同 off | 同 off | 同 off |
+| `full` | **+subagent** | **+subagent** | **+subagent** | 同 off | **+subagent** | 同 off |
+
+### 何时启用
+
+在 `task.json` 设 `piSubagentMode: "analyze-plan"` 或 `piSubagentMode: "full"` 当：
+- task 涉及大规模 codebase 阅读，适合 parallel scout agents
+- analysis 或 planning 需多角度调查（如跨模块比较实现）
+- retrospective review 适合独立 reviewer subagent（`full` mode）
+
+### step 内使用 `subagent` 的指引
+
+subagent 可用时，**仅用于 read-only task**：
+- **Parallel scout**：dispatch 多个 subagent 同时搜索/阅读不同区域
+- **Chain**：一个 subagent scout，另一个基于发现 planning
+- **Reviewer**：用 subagent 在定稿前 review analysis/plan
+
+**不要**用 subagent 做 writing、editing 或执行命令。subagent 输出仅 advisory；务必 verify 并将发现并入自己的输出。**不要**把 subagent 结果当作权威 state 或 artifact source。
+
+### 前置条件
+
+- Pi runtime 环境须有 `subagent` tool（经 Pi subagent extension 加载）
+- 推荐用 Pi 自带 example 文件安装：
+
+```bash
+mkdir -p ~/.pi/agent/extensions/subagent ~/.pi/agent/agents ~/.pi/agent/prompts
+
+ln -sf /usr/local/lib/node_modules/@earendil-works/pi-coding-agent/examples/extensions/subagent/index.ts ~/.pi/agent/extensions/subagent/index.ts
+ln -sf /usr/local/lib/node_modules/@earendil-works/pi-coding-agent/examples/extensions/subagent/agents.ts ~/.pi/agent/extensions/subagent/agents.ts
+
+for f in /usr/local/lib/node_modules/@earendil-works/pi-coding-agent/examples/extensions/subagent/agents/*.md; do
+  ln -sf "$f" ~/.pi/agent/agents/$(basename "$f")
+done
+
+for f in /usr/local/lib/node_modules/@earendil-works/pi-coding-agent/examples/extensions/subagent/prompts/*.md; do
+  ln -sf "$f" ~/.pi/agent/prompts/$(basename "$f")
+done
+```
+
+- 最小 smoke check：
+
+```bash
+pi -p --no-session --no-context-files --no-skills --tools subagent "Reply with exactly OK."
+```
+
+  预期输出：`OK`
+- mode 按 task opt-in；默认 `off` 保持向后兼容
+- 任何 mode 下 `implement` 都不给 `subagent`（防止 nested multi-writer）
+
+### 内置 Project-Local Agents 与 Prompts
+
+本 repo 提供 `.pi/agents/` 与 `.pi/prompts/` 模板，供 `piSubagentMode` 使用：
+
+**Agents**（`.pi/agents/`）
+
+| Agent | Role | 对应阶段 |
+|-------|------|----------|
+| `loop-agent-scout` | 只读侦察：code、tests、docs、governance | Scout |
+| `loop-agent-planner` | 最小可执行计划；强调验证与回退 | Plan |
+| `loop-agent-reviewer` | 严格审查：范围漂移、验证缺口、契约破坏 | Verify / Review |
+| `loop-agent-worker` | 有界实现与修补 | Implement |
+
+另有通用 agents：`scout` / `planner` / `worker` / `reviewer`（中文提示，可被通用 prompt 模板调用）。模型以各 agent frontmatter 为准（当前仓库默认对齐 `harness.json` 的 Pi executor）。
+
+**Prompt Templates**（`.pi/prompts/`）：输入 `/loop-agent-*` 或通用模板名调用
+
+| Template | Flow |
+|----------|------|
+| `loop-agent-scout-and-plan` | parallel scout → planner |
+| `loop-agent-analyze-wide` | 3 parallel scouts → 结构化分析 |
+| `loop-agent-review-only` | 独立审查计划/实现/验证 |
+| `loop-agent-implement-and-review` | worker → reviewer → worker |
+| `scout-and-plan` / `implement` / `implement-and-review` | 通用 chain（调用 `scout`/`planner`/`worker`/`reviewer`） |
+
+传 `agentScope: "both"` + `confirmProjectAgents: false` 以访问 repo-local agents。

package/skills/loop-agent/references/post-implementation-and-patterns.md

@@ -0,0 +1,54 @@
+# 实现后处理与常见模式
+
+用于 post-verify handoff、多 item PRD 处理、fast bounded task、快速 status 检查与 Pi timeout 处理。
+
+## 实现后处理
+
+DAG run、promotion、closeout 和最终验证完成后：
+
+1. 检查 git diff 确认预期变更
+2. 用 git commit 并 push
+3. 用户说「继续」时，跑 `status` 看 task 是否 `completed`，再创建下一个 task
+
+## 常见模式
+
+### 处理多 item PRD
+
+```
+0. plan create <feature-plan> "…"（整份 PRD 一个 plan，多 task 共用）
+1. new-task <id>-r1 → import-prd（同一 PRD 或切片说明）→ 派生 需求.md → dag … → promote/closeout
+2. new-task <id>-r2 → 重复
+3. plan complete <feature-plan> --summary "…"
+```
+
+详见 `source-and-plan-practice.md` 案例 A/C。
+
+### Bounded task 路径
+
+```
+1. new-task <id>
+2. 有 PRD 文件：task advance --prd + 工程边界 flags（默认不手写两 source）
+3. 非微小：plan create（或挂到已有 active plan）
+4. task advance <id> --profile auto --strict-models
+5. dag validate --dag .harness/tasks/<id>/dag.json --strict-models --strict-governance
+6. dag execute --dag .harness/tasks/<id>/dag.json --cwd <repo-root>
+7. task advance (promotion) / closeout / final verification
+8. 有 plan：plan complete
+```
+
+默认 DAG 草稿：`.harness/tasks/<id>/dag.json`。何时可跳过 import/plan：见 `source-and-plan-practice.md`。
+
+**关键**：实现 work 由 DAG node 和 executor 执行；main session 负责审 DAG、审 writeSet、跑验证和 handoff。
+
+### 跨所有 task 快速 status
+
+```bash
+loop-agent stats
+```
+
+### 处理 pi timeout
+
+- 默认每 step timeout 现为 30 分钟 — 通常足够
+- pi step 仍 timeout 时，用 `stats` 看 duration 分布
+- Bash tool call 应用宽松 timeout：analyze/plan 300s，implement 480s+，verify/retrospective 240s+
+- 失败时优先读 `dag report` / `dag doctor`，再决定 repair DAG、bounded Cursor fix 或暂停

package/skills/loop-agent/references/source-and-plan-practice.md

@@ -0,0 +1,169 @@
+# Source 与 Exec-plan 最佳实践
+
+很多用户只跑最短 runtime 命令，**漏掉** PRD 归档纪律与 `plan create`。二者**不是** `task advance` 的硬依赖，但在「有原始 PRD / 非微小实现」场景下应成为默认纪律。本文给出**何时用、何时可跳、命令顺序与案例**。
+
+相关命令细节：`command-reference.md`（task advance / plan / status）。
+Task 目录布局：`task-workflow.md`。  
+仓库治理全文：目标仓 `governanceRoot` 下 `feature-workflow.md`（若有）。
+
+## 先分清三层
+
+| 层 | 命令 / 路径 | 作用 | 主路径是否强制 |
+| --- | --- | --- | --- |
+| Source 事实 | `task advance --prd` → `source/references/*` + `source-manifest.json` | 原始 PRD **不可变**归档 | 否（有 PRD 文件时**强烈推荐**） |
+| Source 契约 | `task advance` 投影 `source/需求.md`、`执行约束.md` + managed paths | DAG 生成与验收真源 | **是**（至少 `需求.md`；默认不手写） |
+| Exec-plan | `plan create` / `plan complete` / `plan check` | 仓库级计划索引与交接 | 否（**非微小**推荐） |
+| Task lifecycle | `task advance` → writeSet gate → `--approve-gate` → `task status` | 可执行编排与证据 | **是**（常规实现） |
+
+规则记忆：
+
+1. **`task advance` 在有 `--prd` 时会归档 PRD，但不自动绑 plan。**
+2. **`task advance` 主要消费派生 `需求.md`**；会校验 plan **索引一致性**，但不要求当前 task 已有 active plan。
+3. 冲突时：**`source/references/*`（原始）> 派生 `需求.md` > 聊天口述。**
+
+## 决策：何时使用 `--prd`（原 import-prd 纪律）
+
+### 应该用（默认「有就 import」）
+
+- 用户给了独立 PRD / 需求文档 / 设计说明文件（`.md` / 导出稿）。
+- 多轮对话已把需求定稿，且希望 **hash 可追溯**（避免模型把原文改成「唯一 source」）。
+- Worker / 多人协作：后续 review 必须三方对照 references + 需求.md + 实现。
+- 目标仓 `ai_workspace/loop-agent/` 或 `docs/` 里已有权威 PRD/spec，任务只是执行切片。
+
+### 可以跳过 PRD 归档
+
+- 真正微小：单文件 typo、一行配置、纯脚本命令说明，**没有**独立需求文档。
+- 用户只在聊天里给了 3～5 条验收点，可用 `--from-text` 并标明「来源：会话 YYYY-MM-DD」。
+- 已有 task 的 `source/references/` 与 manifest 完好，本次只是 re-run lifecycle。
+
+### 反模式
+
+- 把用户 PRD **整篇改写**进 `需求.md` 后删掉原文路径。
+- AI 直接 edit `source/references/*`。
+- 只把 PRD 路径写在聊天里，不落盘到 task 容器。
+- 把 `product-analysis.md` 当可执行 PRD，或把 analysis/clarification 改写成假 AC 以通过 prepare。
+- intake 失败后在原 PRD 目录生成「兼容格式」Markdown / `reviewed-draft.json`，再用 `--from-draft` 绕过（默认禁止）。
+- 把 `--from-draft` 当作 `EMPTY_ACCEPTANCE` 的自动恢复手段。
+
+### Product Analysis 套件
+
+| 文件 | role | 用途 |
+|---|---|---|
+| `product-requirement.md` | `requirement` | **唯一**可执行需求事实源（complete 后才进 DAG） |
+| `product-analysis.md` | `analysis` | 分析证据；**不能**单独作为 requirement |
+| `requirement-clarification.md` | `clarification` | 决策追溯；**不能**单独作为 requirement |
+
+`task advance --prd` 可多次传入；未写 `--role` 时按路径/frontmatter 推断。intake 未完成时 lifecycle 为 `intake-incomplete`（PRD 已归档，DAG 未生成）。
+
+### 推荐顺序（有 PRD 时）
+
+```bash
+loop-agent task advance <task-id> "简短标题" \
+  --prd <path-to-original-prd.md> \
+  --allowed-path "<glob>" \
+  --json
+# 默认无 LLM 写 source；工程边界用 flags 显式给出
+# 内部投影：source/需求.md、source/执行约束.md、task.json paths/verify
+loop-agent task advance <task-id> --approve-gate "write-set-review:<digest>" --json
+loop-agent task status <task-id> --json
+```
+
+首次 advance 后用 `task status` 确认 lifecycle / gate；不要再拼已删除的 import-prd / prepare / run-task 命令串。
+
+## 决策：何时 `plan create`
+
+### 应该用（默认「非微小就 create」）
+
+- 跨多文件 / 多模块、需要 **Contract → 分块 → 验证 → 交接** 的实现。
+- 预计超过一次会话，或要交给其他 agent / 人继续。
+- 会改 CLI、runtime、init 投影、发布面、治理脚本等 **高 blast-radius** 区域。
+- 团队要求 active plan 进 `docs/exec-plans/`（或目标仓 `governanceRoot/exec-plans/`）索引。
+- 本仓库 `AGENTS.md` 对「非微小实现」要求 plan + DAG 时。
+
+### 可以跳过 plan create
+
+- 真正 one-shot：路径已知、验收一条命令、无长期决策要记。
+- 纯 operator 维护：改一个 README 链接、修索引笔误（仍应验证，但不必开 plan）。
+- 已有 **进行中** active plan 覆盖同一工作块：更新该 plan，而不是平行再开一个同题 plan。
+
+### 与 task 的关系
+
+- **一个 plan 可覆盖多个 task**；**一个 task 也不强制 1:1 plan**。
+- plan id 建议 `YYYY-MM-DD-<slug>`；task id 可更短（业务切片名）。
+- 完成后：`plan complete <plan-id> --summary "..."`（或目标仓等价流程），不要只关 task 忘了 plan 索引。
+
+### 推荐顺序（非微小 + 有 PRD）
+
+```bash
+loop-agent plan create <plan-id> "<title>"
+# 在 plan 中写清范围、非目标、验证、允许路径（人类/agent 共读）
+loop-agent task advance <task-id> "切片标题" --prd <prd> --allowed-path "<glob>" --json
+loop-agent task advance <task-id> --approve-gate "write-set-review:<digest>" --json
+loop-agent task status <task-id> --json
+loop-agent plan complete <plan-id> --summary "结果导向摘要 + 验证证据"
+```
+
+微小 escape hatch（须在 handoff / plan 或 task 备注写明边界）：
+
+```bash
+loop-agent task advance <task-id> "微小修复" --from-text "..." --allowed-path "<glob>" --json
+loop-agent task advance <task-id> --approve-gate "write-set-review:<digest>" --json
+```
+
+## 实践案例
+
+### 案例 A — 用户丢来一份 PRD 文件（默认完整路径）
+
+**信号**：`帮我按这个 PRD 实现…` + 附件/路径。  
+**做法**：非微小则先 `plan create`（或复用 active plan）→ **`task advance --prd`** → 审查 writeSet gate → `--approve-gate`。
+**验收**：`source/references/` 有原文；manifest hash 在；review 能三方对照。
+
+### 案例 B — 聊天里三句话小需求（可跳过 PRD + plan）
+
+**信号**：`把 X 按钮文案改成 Y`，单文件。  
+**做法**：`task advance --from-text` → approve gate…
+**不要**：为了「流程完整」空跑不存在的 PRD 文件步骤或堆一个空洞 plan。
+
+### 案例 C — 源仓改 CLI 默认行为（必须 plan，PRD 视情况）
+
+**信号**：行为变更、CHANGELOG、skills/init 多表面。  
+**做法**：**`plan create`** 先冻结契约与工作块 → 按块 `task advance` → 定向验证 → `plan complete`。
+**验收**：active/completed 索引与 plan 正文一致；`plan check` / `task advance` 索引 preflight 不红。
+
+### 案例 D — agent-worker / Feature 已 materialize source_docs
+
+**信号**：TaskSpec 已把 `source_docs` 拷进 `source/references/`。  
+**做法**：通常 **不必再 import 同一文件**；检查 references + 派生 `需求.md` 顶部「冲突以 references 为准」→ 补边界 → `task advance`。
+**仍建议**：产品线级大功能在 Feature / 仓库层有 plan 或 Feature Packet 记录。
+
+### 案例 E — 用户说「loop-agent 帮我完成 XXX」无附件
+
+**信号**：强路由进 DAG，但无 PRD 路径。  
+**做法**：主会话 **先问清**是否有 PRD 文件；有则 `--prd`；无则 `--from-text` 写入共识并标来源 → 判断微小 vs 非微小决定是否 `plan create` → 再 `task advance`。
+**禁止**：主会话直接写业务代码代替 lifecycle。
+
+## 宿主 agent 检查清单（编排时）
+
+在第一次 `task advance` 前快速自问：
+
+1. 是否存在用户/仓库原始需求文件？→ **有则 `--prd`**。
+2. `source/需求.md` 是否含目标、非目标、可验证验收？→ **无则由 advance 投影或补 flags**。
+3. `allowedPaths` / `forbiddenPaths` 是否已结构化？→ **无则先写 flags**。
+4. 是否非微小 / 跨会话 / 高 blast-radius？→ **`plan create` 或更新已有 active plan**。
+5. 是否仅聊天约束？→ **落盘到 source 或 plan**，不要只留在对话。
+
+## 与「主路径」文档的关系
+
+`SKILL.md` / `command-reference.md` 的 **主路径** 仍是最短 runtime 闭环（便于抄命令）。
+**系统化默认**应读作：
+
+```text
+[非微小?] plan create（或复用 active plan）
+task advance [--prd | --from-text] + 工程边界 flags
+审查 writeSet gate
+task advance --approve-gate
+task status
+[有 plan?] plan complete
+```
+
+不要把 PRD 归档 / `plan create` 伪造成「无文件也必须执行」的假步骤；用本节决策表选择，而不是一律省略。

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

@@ -0,0 +1,104 @@
+# Task Workflow 规则
+
+本文只保留 legacy task 目录和 source material 的读取规则。历史顺序式 `run analyze|plan|spec|implement|verify|auto|loop|continue` 工作流已经移除，不再作为 micro、fallback 或 compatibility 执行路径。
+
+## 当前执行入口
+
+所有需要可恢复、可验证、可交接的实现工作都走 `task advance` lifecycle（内部驱动 Agent DAG）：
+
+```bash
+# 非微小：loop-agent plan create <plan-id> "<title>"（可与 task 解耦，见 source-and-plan-practice.md）
+loop-agent task advance <task-id> "Task Title" \
+  --prd <prd> \
+  --allowed-path "<glob>" \
+  --json
+loop-agent task advance <task-id> --approve-gate "write-set-review:<digest>" --json
+loop-agent task status <task-id> --json
+```
+
+默认 DAG 草稿仍为 `.harness/tasks/<task-id>/dag.json`。repo-relative 示例用 `/`；Windows 由 Node 解析本地路径。何时必须 PRD / `plan create`：见 `source-and-plan-practice.md`。
+
+当目标仓库是 loop-agent 本仓库时，`loop-agent` 命令必须来自 npm 上已发布的安装包。首次安装或有意升级可用 `@tea-agent/loop-agent@latest`（当前推荐稳定版；`@next` 仅用于尝鲜/测试 main 构建，`release-0.x` 固定某条版本线），但一次自举任务启动后不要中途升级控制器，并记录 `npm list -g @tea-agent/loop-agent --depth=0` 显示的实际版本。不要用当前工作区的 `npm link` 或 `npm run dev` 控制会改动 CLI、DAG runtime、executor、package metadata 或 build output 的任务；源码开发和 focused debugging 才使用 `npm run dev -- <args>`。
+
+主会话默认是 **Compatibility / Operator Assist**：实现工作必须走上方 DAG CLI。低风险的文档/index/task-source 元数据修正仅作 operator 维护，须记录 scope、跑验证，且**不得**扩展为业务实现或 CLI 失败后的救火写码；见 `orchestrator-and-interventions.md`。
+
+## Source Materials
+
+`task advance` 创建 task 后至少维护：
+
+```text
+.harness/tasks/<task-id>/
+  source/
+    references/          # 原始 PRD / design / acceptance（不可变）
+    source-manifest.json # task advance --prd 写入的 hash 清单
+    需求.md              # 派生执行契约
+    执行约束.md
+  task.json
+```
+
+- 用户原始 PRD 用 `task advance --prd <prd>` 归档到 `source/references/`，禁止 AI 改写。**有文件就归档**。
+- Product Analysis 套件职责：`product-requirement.md` 是唯一可执行需求事实源；`product-analysis.md` / `requirement-clarification.md` 仅引用。未显式 `--role` 时按文件名/frontmatter 推断（analysis / clarification / requirement）。
+- 遇到 `PRODUCT_ANALYSIS_NOT_EXECUTABLE` / `PRODUCT_REQUIREMENT_PENDING` / `EMPTY_ACCEPTANCE`：**禁止**改写原始产物，**禁止**在原 PRD 目录生成兼容 Markdown 或 `reviewed-draft.json` 自救；应换正确 requirement 文档或补真实验收标准后重试。
+- `--from-draft` 仅用于人工 reviewed draft / managed 恢复 / 调试，不是 intake 失败的默认恢复路径。
+- 确定性解析失败且缺口为结构性时，`task advance` 可自动做**一次** Semantic Intake（只读 Pi → `artifacts/intake/semantic-draft.json` → prepare）；analysis/pending/真缺决策不会调用。可用 `LOOP_AGENT_SEMANTIC_INTAKE=0` 关闭。禁止在原 PRD 目录写 sidecar。
+- 默认用 `task advance`（带 `--allowed-path` / `--verify`）投影 `需求.md` / `执行约束.md` 与 managed paths；**不要**默认让 LLM/主会话手写两 source。
+- 无独立 PRD 的微小任务可用 `task advance --from-text ...` escape hatch（见 `source-and-plan-practice.md`）。
+- 若 `ai_workspace/loop-agent/` 已有权威 plan/spec/PRD，优先 `task advance --prd` 归档并派生薄契约；避免把长 PRD 直接改写成唯一 source。
+- 仓库级 exec-plan（`plan create`）与 harness task **解耦**：非微小实现应有 plan 或复用 active plan；微小任务可不建 plan。
+- Worker / TaskSpec materialize 路径会把 `source_docs` 复制到 `source/references/`，并在派生 `需求.md` 顶部声明“冲突以 references 为准”；`acceptance_refs` 应展开为短摘要而不只写 ID。
+- review 节点必须三方对照：`source/references/*`（尤其 requirement/acceptance）、派生 `需求.md`、以及实现/验证证据。
+
+## Task State
+
+当前 task 状态由 DAG-oriented read model 推导：
+
+- source readiness
+- DAG draft
+- latest DAG run
+- promotion
+- closeout
+- loop state
+- legacy workflow snapshot
+
+旧 `.workflow_state.json` 只能作为兼容读取输入，不是新任务 next action 或完成状态的权威来源。
+
+## Repo Adapters
+
+loop-agent 自动检测所在 repo，并按目标 repo 的 `harness.json` 与治理根目录选择验证入口。跨目录操作时显式传入目标仓库：
+
+```bash
+loop-agent --repo-root /path/to/target-repo <command>
+```
+
+## Task Config
+
+新任务不应写入旧 `flow` 字段。常用字段是：
+
+- `taskId`
+- `title`
+- `complexity`
+- `allowedPaths`
+- `forbiddenPaths`
+- `hardConstraints`
+- `verifyCommands` / adapter verification settings
+- `dagFallbackReason`，仅用于记录为何某个长期 loop 缺少 DAG round evidence
+
+结构化数组字段：
+
+- `referenceDocs` 必须是 `{ path, name? }[]`，不能是路径字符串数组。
+- `verifyCommands` 必须是 `{ label, command, timeoutMs? }[]`，不能是命令字符串数组。
+
+切片形状：每个 task 应是可独立验证的垂直 tracer bullet，而不是某一层的水平批处理。Autonomy（AFK/HITL）与 governance profile（`minimal`/`standard`/`reviewed`/`supervised`）分开声明；默认 `--profile auto`。
+
+## Verification
+
+完成声明必须来自新鲜验证证据。按目标 repo 的 `harness.json.governanceRoot` 下 `verification-matrix.md` 选择最小证明命令；loop-agent 自身常用：
+
+```bash
+npm run typecheck
+npm test
+bash scripts/check-repo.sh
+bash scripts/ci.sh
+```
+
+Windows 上通过 Git Bash 或配置好的兼容 Bash 运行 `scripts/*.sh`；不要把 POSIX 路径假设写入 CLI、模板或 task source。