@tea-agent/loop-agent 0.22.0 → 0.24.0

package/skills/grill-with-docs/SKILL.md

@@ -1,88 +1,80 @@
 ---
 name: grill-with-docs
-description: Grilling session that challenges your plan against the existing domain model, sharpens terminology, and updates documentation (CONTEXT.md, ADRs) inline as decisions crystallise. Use when user wants to stress-test a plan against their project's language and documented decisions.
+description: >-
+  Grilling session that challenges a plan against the existing domain model,
+  sharpens terminology, and proposes CONTEXT.md / ADR updates as decisions
+  crystallise. Use when the user wants to stress-test a plan against project
+  language and documented decisions. Explicit interactive operator skill only —
+  not a default DAG role.
+references:
+  - path: context-format.md
+    required: true
+  - path: adr-format.md
+    required: true
 ---
 
-<what-to-do>
+# Grill With Docs
 
-Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer.
+显式交互式 operator skill。用于压力测试计划与术语；**不**加入默认 planner / reviewer / implementer role mapping，避免普通 DAG 被问答阻塞。
 
-Ask the questions one at a time, waiting for feedback on each question before continuing.
+## What to do
 
-If a question can be answered by exploring the codebase, explore the codebase instead.
-
-</what-to-do>
-
-<supporting-info>
-
-## Domain awareness
+Interview the user relentlessly about every aspect of the plan until shared understanding. Walk each design branch, resolve decision dependencies one-by-one. For each question, provide a recommended answer.
 
-During codebase exploration, also look for existing documentation:
+Ask questions one at a time; wait for feedback before continuing.
 
-### File structure
-
-Most repos have a single context:
+If a question can be answered by exploring the codebase, explore the codebase instead.
 
-```
-/
-├── CONTEXT.md
-├── ai_workspace/loop-agent/
-│   └── adr/
-│       ├── 0001-event-sourced-orders.md
-│       └── 0002-postgres-for-write-model.md
-└── src/
-```
+## Path resolution
 
-If a `CONTEXT-MAP.md` exists at the root, the repo has multiple contexts. The map points to where each one lives:
+1. Read `harness.json.governanceRoot`（缺省时常见为源码仓库 `docs`，目标项目 `ai_workspace/loop-agent`）。
+2. Decisions 目录 = `${governanceRoot}/decisions/`（本仓库即 `docs/decisions/`）。
+3. Glossary = 仓库根 `CONTEXT.md`（多 context 时见 `CONTEXT-MAP.md`）。
+4. **禁止**硬编码平行 `adr/` 目录树；只用 `${governanceRoot}/decisions/`。
 
-```
-/
-├── CONTEXT-MAP.md
-├── ai_workspace/loop-agent/
-│   └── adr/                          ← system-wide decisions
-├── src/
-│   ├── ordering/
-│   │   ├── CONTEXT.md
-│   │   └── ai_workspace/loop-agent/adr/                 ← context-specific decisions
-│   └── billing/
-│       ├── CONTEXT.md
-│       └── ai_workspace/loop-agent/adr/
-```
+## Write boundary
 
-Create files lazily — only when you have something to write. If no `CONTEXT.md` exists, create one when the first term is resolved. If no `ai_workspace/loop-agent/adr/` exists, create it when the first ADR is needed.
+- Inline 更新 `CONTEXT.md` / ADR **必须**服从当前 task `allowedPaths` 与 DAG `writeSet`。
+- 无写权限时：只返回建议与待确认 patch，**不得**越界写文档。
+- 不得绕过 human gate、write guard 或 shell completion authority。
 
 ## During the session
 
 ### Challenge against the glossary
 
-When the user uses a term that conflicts with the existing language in `CONTEXT.md`, call it out immediately. "Your glossary defines 'cancellation' as X, but you seem to mean Y — which is it?"
+术语与 `CONTEXT.md` 冲突时立即指出。
 
 ### Sharpen fuzzy language
 
-When the user uses vague or overloaded terms, propose a precise canonical term. "You're saying 'account' — do you mean the Customer or the User? Those are different things."
+模糊或过载词要提出规范术语。
 
 ### Discuss concrete scenarios
 
-When domain relationships are being discussed, stress-test them with specific scenarios. Invent scenarios that probe edge cases and force the user to be precise about the boundaries between concepts.
+用具体场景压力测试边界。
 
 ### Cross-reference with code
 
-When the user states how something works, check whether the code agrees. If you find a contradiction, surface it: "Your code cancels entire Orders, but you just said partial cancellation is possible — which is right?"
+声称与代码不符时立即表面矛盾。
 
-### Update CONTEXT.md inline
+### Update CONTEXT.md only when allowed
 
-When a term is resolved, update `CONTEXT.md` right there. Don't batch these up — capture them as they happen. Use the format in [context-format.md](./context-format.md).
+术语敲定后，若有写权限则按 `context-format.md` 立刻更新；否则只给出建议 patch。
 
-`CONTEXT.md` should be totally devoid of implementation details. Do not treat `CONTEXT.md` as a spec, a scratch pad, or a repository for implementation decisions. It is a glossary and nothing else.
+`CONTEXT.md` 是 glossary 且仅是 glossary：不含实现细节、规格草稿、计划状态或架构决策。
 
 ### Offer ADRs sparingly
 
-Only offer to create an ADR when all three are true:
+仅当三条同时成立才提议 ADR：
+
+1. **Hard to reverse** — 改变成本可观
+2. **Surprising without context** — 未来读者会追问 why
+3. **Real trade-off** — 曾有合理备选并基于具体理由选择
+
+缺一则跳过。格式遵循目标仓库已有模板（见 `adr-format.md`），本仓库使用完整 `docs/templates/adr.md` 字段，不用单段极简 ADR 覆盖本地约定。
 
-1. **Hard to reverse** — the cost of changing your mind later is meaningful
-2. **Surprising without context** — a future reader will wonder "why did they do it this way?"
-3. **The result of a real trade-off** — there were genuine alternatives and you picked one for specific reasons
+## Supporting formats
 
-If any of the three is missing, skip the ADR. Use the format in [adr-format.md](./adr-format.md).
+Required references（已进入 skill snapshot）：
 
-</supporting-info>
+- `context-format.md`
+- `adr-format.md`

package/skills/grill-with-docs/adr-format.md

@@ -1,47 +1,58 @@
 # ADR Format
 
-ADRs live in `ai_workspace/loop-agent/adr/` and use sequential numbering: `0001-slug.md`, `0002-slug.md`, etc.
+ADRs live under `${harness.json.governanceRoot}/decisions/`（源码仓库通常为 `docs/decisions/`；普通初始化目标项目通常为 `ai_workspace/loop-agent/decisions/`）。
 
-Create the `ai_workspace/loop-agent/adr/` directory lazily — only when the first ADR is needed.
+Do **not** create a parallel `adr/` tree. Use `decisions/` under the governance root only.
 
-## Template
-
-```md
-# {Short title of the decision}
+Create the decisions directory lazily — only when the first ADR is needed and write permission exists.
 
-{1-3 sentences: what's the context, what did we decide, and why.}
-```
+## Template
 
-That's it. An ADR can be a single paragraph. The value is in recording *that* a decision was made and *why* — not in filling out sections.
+Follow the **target repository's existing ADR template**. In the loop-agent source repo that is `docs/templates/adr.md` with full sections:
 
-## Optional sections
+- 标题 / 状态
+- 背景
+- 决策
+- 备选方案
+- 取舍理由
+- 影响范围
+- 后果（正面 / 负面）
+- 验证与落地
+- 复审条件
 
-Only include these when they add genuine value. Most ADRs won't need them.
+Do not replace a full local template with a one-paragraph mini-ADR.
 
-- **Status** frontmatter (`proposed | accepted | deprecated | superseded by ADR-NNNN`) — useful when decisions are revisited
-- **Considered Options** — only when the rejected alternatives are worth remembering
-- **Consequences** — only when non-obvious downstream effects need to be called out
+Target projects may ship a copy of the template under their governance `templates/` directory; use that when present.
 
 ## Numbering
 
-Scan `ai_workspace/loop-agent/adr/` for the highest existing number and increment by one.
+Scan the decisions directory for the highest existing `NNNN-*.md` number and increment by one. Update the decisions README index when one exists.
 
 ## When to offer an ADR
 
-All three of these must be true:
+All three must be true:
 
 1. **Hard to reverse** — the cost of changing your mind later is meaningful
-2. **Surprising without context** — a future reader will look at the code and wonder "why on earth did they do it this way?"
-3. **The result of a real trade-off** — there were genuine alternatives and you picked one for specific reasons
+2. **Surprising without context** — a future reader will wonder why this path was chosen
+3. **The result of a real trade-off** — genuine alternatives existed and one was chosen for specific reasons
 
-If a decision is easy to reverse, skip it — you'll just reverse it. If it's not surprising, nobody will wonder why. If there was no real alternative, there's nothing to record beyond "we did the obvious thing."
+If any is missing, skip the ADR.
 
 ### What qualifies
 
-- **Architectural shape.** "We're using a monorepo." "The write model is event-sourced, the read model is projected into Postgres."
-- **Integration patterns between contexts.** "Ordering and Billing communicate via domain events, not synchronous HTTP."
-- **Technology choices that carry lock-in.** Database, message bus, auth provider, deployment target. Not every library — just the ones that would take a quarter to swap out.
-- **Boundary and scope decisions.** "Customer data is owned by the Customer context; other contexts reference it by ID only." The explicit no-s are as valuable as the yes-s.
-- **Deliberate deviations from the obvious path.** "We're using manual SQL instead of an ORM because X." Anything where a reasonable reader would assume the opposite. These stop the next engineer from "fixing" something that was deliberate.
-- **Constraints not visible in the code.** "We can't use AWS because of compliance requirements." "Response times must be under 200ms because of the partner API contract."
-- **Rejected alternatives when the rejection is non-obvious.** If you considered GraphQL and picked REST for subtle reasons, record it — otherwise someone will suggest GraphQL again in six months.
+- Architectural shape and integration patterns between contexts
+- Technology choices that carry lock-in
+- Boundary and scope decisions (explicit no-es included)
+- Deliberate deviations from the obvious path
+- Constraints not visible in the code
+- Rejected alternatives when the rejection is non-obvious
+
+### What does not
+
+- Temporary scheduling
+- Obvious implementation choices with no alternatives
+- Facts that belong in code, tests, or progress/report artifacts
+
+## Write boundary
+
+Only create or edit ADR files when the current task `allowedPaths` / DAG `writeSet` allow it. Otherwise return a suggested patch for human or writer follow-up.

package/skills/grill-with-docs/context-format.md

@@ -7,7 +7,12 @@
 
 {One or two sentence description of what this context is and why it exists.}
 
-## Language
+## 使用说明（optional but recommended）
+
+- CONTEXT.md is a glossary and nothing else.
+- Do not store implementation details, draft specs, plan status, or architecture decisions.
+
+## 术语 / Language
 
 **Order**:
 {A one or two sentence description of the term}
@@ -16,45 +21,32 @@ _Avoid_: Purchase, transaction
 **Invoice**:
 A request for payment sent to a customer after delivery.
 _Avoid_: Bill, payment request
-
-**Customer**:
-A person or organization that places orders.
-_Avoid_: Client, buyer, account
 ```
 
+Prefer the target repository's existing heading style（本仓库使用「术语」与 `_避免_`）。
+
 ## Rules
 
-- **Be opinionated.** When multiple words exist for the same concept, pick the best one and list the others under `_Avoid_`.
+- **Be opinionated.** When multiple words exist for the same concept, pick the best one and list the others under `_Avoid_` / `_避免_`.
 - **Keep definitions tight.** One or two sentences max. Define what it IS, not what it does.
-- **Only include terms specific to this project's context.** General programming concepts (timeouts, error types, utility patterns) don't belong even if the project uses them extensively. Before adding a term, ask: is this a concept unique to this context, or a general programming concept? Only the former belongs.
-- **Group terms under subheadings** when natural clusters emerge. If all terms belong to a single cohesive area, a flat list is fine.
+- **Glossary only.** No implementation details, specs, plan status, or ADRs.
+- **Only include terms specific to this project's context.** General programming concepts do not belong.
+- **Group terms under subheadings** when natural clusters emerge.
 
 ## Single vs multi-context repos
 
 **Single context (most repos):** One `CONTEXT.md` at the repo root.
 
-**Multiple contexts:** A `CONTEXT-MAP.md` at the repo root lists the contexts, where they live, and how they relate to each other:
-
-```md
-# Context Map
-
-## Contexts
-
-- `src/ordering/CONTEXT.md` — receives and tracks customer orders
-- `src/billing/CONTEXT.md` — generates invoices and processes payments
-- `src/fulfillment/CONTEXT.md` — manages warehouse picking and shipping
-
-## Relationships
-
-- **Ordering → Fulfillment**: Ordering emits `OrderPlaced` events; Fulfillment consumes them to start picking
-- **Fulfillment → Billing**: Fulfillment emits `ShipmentDispatched` events; Billing consumes them to generate invoices
-- **Ordering ↔ Billing**: Shared types for `CustomerId` and `Money`
-```
+**Multiple contexts:** A `CONTEXT-MAP.md` at the repo root lists the contexts, where they live, and how they relate.
 
 The skill infers which structure applies:
 
 - If `CONTEXT-MAP.md` exists, read it to find contexts
 - If only a root `CONTEXT.md` exists, single context
-- If neither exists, create a root `CONTEXT.md` lazily when the first term is resolved
+- If neither exists, propose a root `CONTEXT.md` lazily when the first term is resolved — create only when write permission exists
 
 When multiple contexts exist, infer which one the current topic relates to. If unclear, ask.
+
+## Write boundary
+
+Only edit `CONTEXT.md` when current task `allowedPaths` / DAG `writeSet` allow it. Otherwise return a suggested patch.

package/skills/loop-agent/SKILL.md

@@ -9,142 +9,58 @@ references:
     required: true
   - path: references/verification-and-failure-handling.md
     required: true
-  - path: references/command-reference.md
-    required: true
 ---
 
 # loop-agent Workflow
 
-这是 `loop-agent` 的入口文档，只负责 trigger、routing 和硬规则。较长的 command details、workflow 细节与失败处理放在 `references/`，按需加载。
-
-## Canonical Harness Policy
-
-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。
+Entry for `loop-agent`: trigger, routing, hard rules. Details live in `references/` on demand. `references/command-reference.md` is discoverable via the routing table, **not** a required reference.
 
 ## 默认立场
 
-- 主入口是 **Agent DAG**（经已发布 `loop-agent` / 可选 `agent-worker` CLI）。
-- 本 skill 对 openCode 等宿主的定位是 **Compatibility / Operator Assist**，不是「主会话实现业务代码」。
-- **主会话 = operator-only**：编排 CLI、审 writeSet、只读 status/doctor/report/observe、记 human gate、跑 shell 验证与 handoff。
-- **严禁**主会话绕过 `loop-agent` / `agent-worker` CLI，用宿主 Edit/Write/ApplyPatch 等直接改业务实现，或在 CLI 失败后「救火改文件」。
-- **允许（主会话）**：调用 `loop-agent` / `agent-worker`；只读查 `status` / `dag status` / `dag doctor` / `dag report` / `inspect` / Observe；维护任务源 `source/*` 与结构化 `task.json` 边界（通过 CLI 或显式任务准备步骤，而非替代 DAG writer）。
-- **禁止（主会话）**：直接实现功能/修 bug 业务代码；把 sidecar 当默认 writer；用聊天自述代替 shell 验证。
-- **失败时只允许**：`dag doctor` / `dag report` / `dag reconcile-run`（及 worker 侧 reconcile）、记 human gate、按边界重跑或 replan；不得改走主会话直接写实现。
-- DAG `pi` executor 是唯一受治理 Agent runtime：默认 read-only planning / review / diagnosis；`toolProfile: "write"` 时为 bounded implementation / repair。Pi 模型矩阵 LOW=`gpt-5.3-codex-spark`、MED=`glm-5.2`、HIGH=`gpt-5.5`。
-- `pi-prompt` 与 `cursor-prompt` 是一次性 helper；sidecar 须在 prompt/tool 参数中收窄。Cursor 仅显式手工 `cursor-prompt`，不是 DAG/Loop writer。
-- Shell verification 是事实源；完成声明必须有本轮命令输出。
-- 长期结论写回 `ai_workspace/loop-agent/exec-plans/`、`ai_workspace/loop-agent/reports/`、`ai_workspace/loop-agent/progress/` 或 `./skill/`。
+- 主入口是 **Agent DAG**（经 `loop-agent` / 可选 `agent-worker` CLI）。
+- 本 skill 对宿主定位是 **Compatibility / Operator Assist**，不写业务代码。
+- **主会话 = operator-only**：编排 CLI、审 writeSet、只读 status/doctor/report、记 human gate、跑 Shell verification 与 handoff。
+- **严禁**主会话绕过 CLI 用宿主 Edit/Write 改业务实现，或 CLI 失败后「救火改文件」。
+- DAG `pi` executor 默认 read-only；`toolProfile: "write"` 时为 bounded writer；sidecar 须 per call 收窄。
+- Shell verification 是事实源；长期结论写回 `ai_workspace/loop-agent/`、`docs/decisions/` 或 `skills/`。
 
 ## 唯一推荐执行路径
 
 ```bash
-loop-agent new-task <task-id> "Task Title"
-# Prefer immutable original PRD first:
-# loop-agent import-prd <task-id> --file <path-to-original-prd.md>
-# write derived <repo-root>/.harness/tasks/<task-id>/source/需求.md
-# write <repo-root>/.harness/tasks/<task-id>/source/执行约束.md
-
-loop-agent dag run-task <task-id> --profile auto --strict-models --output <temp-dir>/<task-id>-dag.json
-loop-agent dag validate --dag <temp-dir>/<task-id>-dag.json --strict-models --strict-governance
-loop-agent run-dag --dag <temp-dir>/<task-id>-dag.json --cwd <repo-root>
+loop-agent new-task <task-id> "Title"
+# Prefer immutable PRD: loop-agent import-prd <task-id> --file <path>
+loop-agent dag run-task <task-id> --profile auto --strict-models --output <dag.json>
+loop-agent dag validate --dag <dag.json> --strict-models --strict-governance
+loop-agent run-dag --dag <dag.json> --cwd <repo-root>
 ```
 
-`loop-agent` 默认指 npm 上已发布的全局 CLI。自举迭代 loop-agent 本仓库时，首次安装或有意升级可用 `npm install -g @tea-agent/loop-agent@latest`，但一次自举任务启动后不要中途升级控制器，并记录 `npm list -g @tea-agent/loop-agent --depth=0` 显示的实际版本。不要用当前工作区的 `npm link` 或 `npm run dev` 控制可能改动 CLI、DAG runtime、executor、package metadata 或 build output 的任务。`npm run dev -- <args>` 只用于源码调试和聚焦 CLI 开发。
-
-`<temp-dir>` 表示平台原生临时目录。macOS 和 Windows 都应使用实际平台路径；`/` 只用于 repo refs、JSON/Markdown 证据 refs 和 glob 约定。
-
-执行前必须审阅：
-
-- `profileRouting`
-- `governanceProfile`
-- writer `writeSet`
-- writer `forbiddenPaths`
-- shell verification commands
-- decision gate mode
-
-## Pi Sidecar 入口规则
-
-短时规划、审查、失败归因可使用 full-capability `pi-prompt`，默认模型是 `glm-5.2`：
-
-- 只读 sidecar 必须显式传 `--tools read,grep,find,ls`，并在 prompt 中写明不编辑文件。
-- 高复杂度 one-shot 诊断可显式加 `--model gpt-5.5`。
-- 输出是 advisory，不能替代 deterministic verification；发现必须写回 task source、report、progress 或 exec plan。
-
-## Bounded Write Execution
-
-需要写业务代码时，**只**通过 DAG `pi` writer（`implement-pi` / `repair-pi`）经 `loop-agent run-dag` / `dag run-task --execute` 等 CLI 路径执行。主会话不得自行 Edit 实现文件「代替」writer。
-
-Pi writer 节点必须包含 task id、目标、allowed paths、forbidden paths、writeSet、硬约束和预期验证；执行后由主会话**独立跑 shell 验证**（仍经终端/CLI，不手改代码冒充通过）。
-
-`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 / 可选 sidecar prompt 都必须包含：task id、exact objective、allowed/forbidden paths、hard constraints、expected verification、preserve unrelated files。
-
-bounded writer 完成后，主会话只做独立复核；命令清单见 `references/verification-and-failure-handling.md`。
+执行前审阅 `profileRouting`、`governanceProfile`、writer `writeSet`、`forbiddenPaths`、decision gate mode。
 
 ## 进阶主题路由
 
-以下主题只在 references 中维护细节，不在本文展开：
-
 | 主题 | Reference |
 |---|---|
-| 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/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` |
+| Harness policy、Loop、SePO-lite | `references/harness-policy.md` |
+| Agent DAG topology、writeSet、recovery | `references/hybrid-dag.md` |
+| Operator commands、`agent-worker` | `references/command-reference.md` |
+| 独立验证、failure handling、closeout | `references/verification-and-failure-handling.md` |
 
 ## Source Layout
 
-新代码优先从这些目录进入：
-
-| Area | Entry |
-|---|---|
-| CLI command tree / help / commander program | `src/cli/` |
-| DAG workflow | `src/workflows/dag/` |
-| Long-running loop workflow | `src/workflows/loop/` |
-| Task runtime | `src/task/` |
-| Executors | `src/executors/` |
-| Worker TaskSpec pipeline（伴生 CLI `agent-worker`） | `src/worker/` |
-| Run records / promotion / closeout | `src/records/` |
-| Governance | `src/governance/` |
-| Shared helpers | `src/shared/` |
-| Repo adapters | `src/adapters/` |
-
-不要新增平行兼容入口。CLI public export 的唯一入口是 `src/cli/index.ts`；commander command tree 和 help 实现在 `src/cli/program.ts`。
+CLI `src/cli/`；DAG `src/workflows/dag/`；loop `src/workflows/loop/`；executors `src/executors/`；worker `src/worker/`；governance `src/governance/`。不新增平行兼容入口。
 
 ## Hard Rules
 
-1. One task = one bounded work chunk.
-2. Source materials are mandatory: `source/需求.md` and `source/执行约束.md`. Prefer immutable originals under `source/references/` via `import-prd` or Worker `source_docs`; treat `需求.md` as a derived contract.
-3. Agent DAG is the implementation workflow. Review must three-way check references + derived source + implementation when originals exist.
-4. **Compatibility / Operator Assist**：主会话不得绕过 `loop-agent` / `agent-worker` CLI 直接实现或「救火」改业务代码；失败只走 doctor / reconcile / human gate / 重跑。
-5. DAG `pi` executor stays read-only unless the node sets `toolProfile: "write"`; `pi-prompt` / `cursor-prompt` are full-capability one-shot helpers and must be bounded per call.
-6. Pi writer nodes must be bounded by explicit allowed / forbidden paths and writeSet; Cursor remains `cursor-prompt` sidecar only.
-7. Completed DAG and one-shot run facts are read-only.
-8. Do not write root `artifacts/` from read-only DAG or sidecar steps.
-9. Do not keep hidden workflow state in chat only; write durable conclusions to repo artifacts.
-10. Verify before completion.
+1. Prefer vertical tracer bullets: each slice crosses the real integration layers with independent acceptance/verification. Do not horizontal-slice.
+2. Autonomy ≠ governance profile: declare AFK/HITL in human gate; choose `--profile` by risk.
+3. Source materials mandatory: `source/需求.md`、`source/执行约束.md`、优先 `source/references/*` originals。
+4. Agent DAG is the implementation workflow；review three-way checks references + derived source + implementation。
+5. 主会话不绕过 CLI 直接写业务代码；失败只走 doctor/reconcile/human gate/重跑。
+6. DAG `pi` executor read-only unless `toolProfile: "write"`；completed run facts read-only；不得从 read-only DAG/sidecar 写 root `artifacts/`。
+7. No hidden state in chat only；verify before completion.
 
 ## References
 
-Required（frontmatter 已声明）：
-
-- `references/harness-policy.md`
-- `references/hybrid-dag.md`
-- `references/verification-and-failure-handling.md`
-- `references/command-reference.md`
-
-Optional（按需加载）：
-
-- `references/orchestrator-and-interventions.md`
-- `references/long-running-loop.md`
-- `references/task-workflow.md`
-- `references/pi-prompt.md`
-- `references/one-shot-runs.md`
-- `references/pi-subagent-assisted-mode.md`
-- `references/model-routing.md`
-- `references/multi-worktree.md`
-- `references/post-implementation-and-patterns.md`
-- `references/docs-converge.md` — 用户可见变更后的文档收敛检查表；禁止每次重新规划整站大纲
+Required（按需 inline）：`references/harness-policy.md`、`references/hybrid-dag.md`、`references/verification-and-failure-handling.md`
+
+Optional：`references/command-reference.md`（operator commands、`agent-worker`）、`references/long-running-loop.md`、`references/orchestrator-and-interventions.md`、`references/task-workflow.md`、`references/pi-prompt.md`、`references/one-shot-runs.md`、`references/pi-subagent-assisted-mode.md`、`references/model-routing.md`、`references/multi-worktree.md`、`references/post-implementation-and-patterns.md`、`references/docs-converge.md`

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

@@ -25,7 +25,7 @@ loop-agent doctor
 
 发布包入口加载 `dist/cli.js`；开发入口加载 `src/cli.ts`。
 
-发布包携带静态能力资料：`.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 说明。
+发布包携带静态能力资料：`skills/`（包内内置，含 `loop-agent` 与 `agent-worker`；`loop-agent init` 投影时镜像为目标项目 `.agents/skills/`）、`docs/templates/`、`docs/architecture/`、`docs/skills/` 和 `examples/`。`ai_workspace/loop-agent/`（默认 governanceRoot）下的 `progress/`、`reports/`、`exec-plans/`、`decisions/` 由 `loop-agent init` 在目标项目创建目录并投放 README，其中的任务正文属于目标仓库运行中生成的事实，不从 npm 包复制。
 
 ## 命令参考
 
@@ -285,6 +285,7 @@ cp ai_workspace/loop-agent/templates/agent-dag.supervised-implementation.json <t
 (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
+bash scripts/run-dag-safe.sh --dag <temp-dir>/hybrid-dag.json --cwd <repo-root> [--timeout-secs 7200]  # 后台运行 + 轮询，避免外层 bash timeout 杀进程（见 agent-dag-runner.md §Adaptive liveness）
 loop-agent dag init-hybrid <task-id>                     # 生成可审阅的 DAG draft
 loop-agent dag run-task <task-id>                        # generate + validate（安全默认；无 dag-runs；standard-compatible）
 loop-agent dag workflow-plan <task-id> --profile pr-review --output <temp-dir>/<task-id>.workflow.json
@@ -488,7 +489,7 @@ loop-agent knowledge curate --markdown
 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。
+读取 `.harness/knowledge/patterns.jsonl` 中 completed convergence repair pattern，按 `failureClass + fixScope shape + invariant` 去重，生成 human-gated learned guidance proposal。命令只生成 proposal，不直接修改 `skills/loop-agent/references/learned/*.md`；输出会先通过 skill safety audit。
 
 ### Knowledge graph / query CLI
 
@@ -562,12 +563,17 @@ agent-worker observe snapshot --repo <repo-root>  # 输出 GlobalSnapshot JSON
 - **推荐** `console serve`（默认 `127.0.0.1:8790`）提供 Operate + Inspect；Inspect 路径为 `/inspect/#/...`，API 仍为根 `/api/**`。`observe serve` 为兼容入口（默认 `8787`，启动时 stderr 输出 `OBSERVE_SERVE_DEPRECATED`）；`observe snapshot` 保留。两者都不会启动、暂停或重试 Task / Worker / DAG。
 - 当前 Worker 仍是 v0（库 + CLI + dogfood），未接入定时/CI 驱动；`report morning` 只能从已有 Task Pool runs 汇总。
 
-### 查看 duration statistics
+### 查看 duration statistics / context usage
 
 ```bash
 loop-agent stats
+loop-agent stats context --last 50
+loop-agent stats context --last 50 --json
 ```
 
+- `stats`：legacy step-duration 直方图（`.harness/tasks/*/logs/executor.jsonl`）。
+- `stats context`：最近 N 个 DAG runs 的 **skill-resolution** 与节点 outcome 只读聚合（declared/resolved/missing/error、truncation、`unresolvedReferences.reason`、FINISHED/ERROR/SKIPPED + failureCategory）。**不**宣称模型遵循率或 skill execution rate；corrupted snapshot 记为 finding 且 `ok=false`。
+
 ### Worktree delegate / harvest（escape hatch）
 
 ```bash

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

@@ -77,9 +77,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: `.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.
+The npm package carries static capability assets: `skills/` (bundled in-package, containing `loop-agent` and `agent-worker`; `loop-agent init` mirrors them into the target project's `.agents/skills/`), `docs/templates/`, `docs/architecture/`, `docs/skills/`, `examples/`, `harness.json`, `AGENTS.md`, `README.md`, and `CHANGELOG.md`. `loop-agent init` creates `ai_workspace/loop-agent/` (the default governanceRoot) in the target project with `progress/`, `reports/`, `exec-plans/`, and `decisions/` directories plus their README files; the actual files under those directories belong to the target repository and are not shipped by the npm package.
 
-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.
+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 the package-bundled `skills/` (mirrored as `.agents/skills/` in the target project) 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.
 
@@ -190,7 +190,7 @@ Rules:
 
 - Learned prompt deltas 是 human-gated proposals；成为 reusable guidance 前须 review。
 - Prompt deltas 为 Markdown-only process guidance；不得含 shell commands、credential handling、tool permission expansion 或 completion-authority bypass。
-- Accepted learned guidance 位于 `./skill/references/learned/<repo>.md` 或 `default.md`。
+- Accepted learned guidance 位于 `skills/loop-agent/references/learned/<repo>.md` 或 `default.md`。
 - 已 request `loop-agent` 的 DAG implementer prompts 可 inline 最多三个 human-gated learned Markdown sections。
 - Learned guidance 为 advisory，永不替代 writeSet governance、Decision Gate policy 或 shell verification。
 

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

@@ -238,7 +238,7 @@ review-heavy DAG 中长 shell stdout 可能掩盖 proof 时，用 **evidence-sum
 | 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 |
 | 9 | Decision Gate | 恰好 emit 一个 `DECISION_ENVELOPE_JSON` block；`audit.runId` 须绑定 **当前** run id；禁止 `decision: accept`、发明 schema、extra root key；填 `audit.nodeId` / `audit.model` |
-| 10 | writeSet planning | scout 应列出链接的 `./skill/references/**` 为 **writeSet expansion candidates**（P2：遗漏链接 skill ref 会导致无法在 DAG 内收敛，禁止事后主会话大段补写） |
+| 10 | writeSet planning | scout 应列出链接的 `skills/loop-agent/references/**` 为 **writeSet expansion candidates**（P2：遗漏链接 skill ref 会导致无法在 DAG 内收敛，禁止事后主会话大段补写） |
 | 11 | Evidence summary | `evidence-summary-shell` / leading `EVIDENCE:` 行是 **practice convention**，非 runtime executor、schema field 或 parser |
 | 12 | Featureization | 除非 repeated real-run failure 证明 checklist guidance 不够，勿加 runtime/schema/validator/CLI/executor feature |
 | 13 | writeSet / writer backend | `exclusive` node 用 narrow、disjoint path；无 `**`；固定用 Pi write profile |

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

@@ -72,7 +72,7 @@ Agent DAG read-only node **不得**写 root `artifacts/`。
 - `./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 应提议 `./skill/references/**` 为 **writeSet expansion candidates**，并在下一轮 DAG 中写入，而不是 post-DAG 由主会话大段补写 skill。
+**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 — 不可静默、不可当作实现完成。
 

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

@@ -75,6 +75,8 @@ loop-agent --repo-root /path/to/target-repo <command>
 - `verifyCommands` / adapter verification settings
 - `dagFallbackReason`，仅用于记录为何某个长期 loop 缺少 DAG round evidence
 
+切片形状：每个 task 应是可独立验证的垂直 tracer bullet，而不是某一层的水平批处理。Autonomy（AFK/HITL）与 governance profile（`minimal`/`standard`/`reviewed`/`supervised`）分开声明；默认 `--profile auto`。
+
 ## Verification
 
 完成声明必须来自新鲜验证证据。按目标 repo 的 `harness.json.governanceRoot` 下 `verification-matrix.md` 选择最小证明命令；loop-agent 自身常用：