@tea-agent/loop-agent 0.1.0 → 0.2.0

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

@@ -1,15 +1,15 @@
 # Shared loop-agent Harness Policy
 
-This file is the canonical shared workflow policy for using `.` across repositories. Repo-local harness docs should only describe local adapters: where the runtime lives, which governance root to use, and which verification commands apply.
+本文件是跨仓库使用 `.` 的 canonical shared workflow policy。Repo-local harness docs 只应描述 local adapters：runtime 位置、governance root、适用的 verification commands。
 
 ## Canonical stance
 
-- **Agent DAG** is the default implementation workflow for medium/large, multi-file, architecture-sensitive, public-contract, CI/script, or harness-runtime work.
-- The historical sequential `run analyze|plan|spec|implement|verify|auto|loop|continue` workflow has been removed. Do not present it as a fallback path.
-- **Long-running `loop`** is an outer state/evidence layer above Agent DAG. It records rounds, context compression, signals, and canonical refs; it must not replace DAG writeSet review, Decision Gate, or shell verification for complex work.
-- **Main session** orchestrates: choose one work chunk, prepare source materials, review DAG/writeSet, monitor failures, run final verification, and hand off.
-- **Executors** implement bounded work: Cursor writes within explicit paths, Pi performs read-only planning/review/diagnosis in DAG nodes, shell produces deterministic verification facts.
-- **Shell verification is the completion fact source**. LLM review or advisory output cannot replace command exit codes and archived evidence.
+- **Agent DAG** 是 medium/large、multi-file、architecture-sensitive、public-contract、CI/script 或 harness-runtime 工作的默认 implementation workflow。
+- 历史顺序式 `run analyze|plan|spec|implement|verify|auto|loop|continue` workflow 已移除。不要将其作为 fallback path 呈现。
+- **Long-running `loop`** 是 Agent DAG 之上的 outer state/evidence layer。它记录 rounds、context compression、signals、canonical refs；不得替代 complex work 的 DAG writeSet review、Decision Gate 或 shell verification。
+- **Main session** 负责 orchestrate：选一个 work chunk、准备 source materials、review DAG/writeSet、monitor failures、跑 final verification、hand off。
+- **Executors** 实现 bounded work：Pi 在 DAG nodes 做 read-only planning/review/diagnosis，并在节点声明 `toolProfile: "write"` 时做 bounded implementation/repair；Cursor 是显式启用的可选 bounded writer；shell 产出 deterministic verification facts。
+- **Shell verification 是 completion fact source**。LLM review 或 advisory output 不能替代 command exit codes 与 archived evidence。
 
 ## Command surface tiers
 
@@ -21,7 +21,7 @@ This file is the canonical shared workflow policy for using `.` across repositor
 | Escape hatch | Isolated delegation, one-shot diagnosis or bounded repair | `delegate`, `worktree`, `harvest`, `pi-prompt`, `cursor-prompt`, `cursor-worker` |
 | Experimental | Long-running outer task state | `loop init|status|run|record-round|add-signal|closeout` |
 
-Prompt templates, README snippets, and task instructions should present Primary + Operator first. Compatibility and escape-hatch commands remain available, but must carry their downgrade/fallback meaning.
+Prompt templates、README snippets、task instructions 应优先呈现 Primary + Operator。Compatibility 与 escape-hatch commands 仍可用，但须携带其 downgrade/fallback 含义。
 
 ## Entry selection decision tree
 
@@ -33,34 +33,34 @@ Is this only status, diagnosis, recovery, or closeout?
            yes -> Agent DAG.
 ```
 
-Use Agent DAG rather than broad one-shot execution when any of these signals apply:
-
-- loop-agent runtime, DAG schema, run facts, promotion/closeout, scripts/CI, public contract, or shared protocol is touched.
-- The change needs multiple files, multiple scouts, review gates, Decision Gate, repair flow, or shell gate.
-- `writeSet` is broad, multiple exclusive writers exist, or public interfaces / architecture boundaries change.
-- Requirement, architecture, credential, cost, deployment, security, or authority surface is unclear.
-- A failure repeats and needs recovery planning rather than blind retry.
+在以下任一 signal 适用时用 Agent DAG 而非 broad one-shot execution：
+
+- loop-agent runtime, DAG schema, run facts, promotion/closeout, scripts/CI, public contract, or shared protocol is touched.
+- The change needs multiple files, multiple scouts, review gates, Decision Gate, repair flow, or shell gate.
+- `writeSet` is broad, multiple exclusive writers exist, or public interfaces / architecture boundaries change.
+- Requirement, architecture, credential, cost, deployment, security, or authority surface is unclear.
+- A failure repeats and needs recovery planning rather than blind retry.
 
 ## Agent DAG path
 
-Minimum governed path:
+Minimum governed path：
 
 ```bash
 loop-agent new-task <task-id> "Task Title" [--repo-root <target-repo>]
 # write <target-repo>/.harness/tasks/<task-id>/source/需求.md
 # write <target-repo>/.harness/tasks/<task-id>/source/执行约束.md
 
-loop-agent dag run-task <task-id> \
-  --profile auto \
-  --strict-models \
-  --output <temp-dir>/<task-id>-dag.json \
-  [--repo-root <target-repo>]
-
-loop-agent dag validate \
-  --dag <temp-dir>/<task-id>-dag.json \
-  --strict-models \
-  --strict-governance
-
+loop-agent dag run-task <task-id> \
+  --profile auto \
+  --strict-models \
+  --output <temp-dir>/<task-id>-dag.json \
+  [--repo-root <target-repo>]
+
+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 <target-repo>
@@ -69,27 +69,27 @@ 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.
-
+
 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.
 
 `<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.
 
-Before execution, review `dag run-task` JSON / `reviewPacket`:
+Execution 前 review `dag run-task` JSON / `reviewPacket`：
 
-- `profileRouting`: requested profile, selected profile/template, routing reasons.
-- `governanceProfile`: process, delivery, and code-change signals.
-- Writer nodes: `writePolicy`, `writeSet`, `allowedPaths`, `forbiddenPaths`, broad entries, forbidden overlaps.
-- Shell gates and verification commands.
-- Decision Gate mode (`record-only` vs `pause-on-human`).
-- Any placeholder, `**`, or repo-root writeSet that must be narrowed before execution.
+- `profileRouting`：requested profile、selected profile/template、routing reasons。
+- `governanceProfile`：process、delivery、code-change signals。
+- Writer nodes：`writePolicy`、`writeSet`、`allowedPaths`、`forbiddenPaths`、broad entries、forbidden overlaps。
+- Shell gates 与 verification commands。
+- Decision Gate mode（`record-only` vs `pause-on-human`）。
+- 执行前须 narrow 的 placeholder、`**` 或 repo-root writeSet。
 
-In-flight DAG shell checks should use the repo's active-run override when required (for example `HARNESS_ALLOW_ACTIVE_DAG_RUNS=1 bash scripts/check-repo.sh`). After the DAG is archived, run the repo check again without the in-flight override.
-
-On Windows, run Bash scripts through Git Bash or a configured compatible Bash. Do not require WSL, `/tmp`, `which`, or other POSIX filesystem assumptions in loop-agent CLI behavior.
+In-flight DAG shell checks 在需要时用 repo active-run override（例如 `HARNESS_ALLOW_ACTIVE_DAG_RUNS=1 bash scripts/check-repo.sh`）。DAG archived 后，再不带 in-flight override 跑 repo check。
+
+On Windows, run Bash scripts through Git Bash or a configured compatible Bash. Do not require WSL, `/tmp`, `which`, or other POSIX filesystem assumptions in loop-agent CLI behavior.
 
 ## Task source materials
 
-Every handoff-ready task has:
+每个 handoff-ready task 包含：
 
 ```text
 .harness/tasks/<task-id>/
@@ -99,25 +99,25 @@ Every handoff-ready task has:
     执行约束.md
 ```
 
-`需求.md` should state objective, scope, non-goals, acceptance criteria, and links to repo-local specs or plans.
+`需求.md` 应陈述 objective、scope、non-goals、acceptance criteria，并链接 repo-local specs 或 plans。
 
-`执行约束.md` should state:
+`执行约束.md` 应陈述：
 
 - allowed paths
 - forbidden paths
-- current dirty workspace / protected user changes, if any
-- architecture boundaries and invariants
+- 当前 dirty workspace / protected user changes（如有）
+- architecture boundaries 与 invariants
 - expected verification commands
 - acceptance criteria / failure conditions
-- whether DAG fallback is allowed, and the fallback reason if already known
+- 是否允许 DAG fallback，及若已知时的 fallback reason
 
-If source materials change after `spec`, `plan`, or DAG generation, regenerate or revalidate the plan/DAG before implementation.
+若 `spec`、`plan` 或 DAG generation 后 source materials 变更，implementation 前 regenerate 或 revalidate plan/DAG。
 
 ## Long-running loop policy
 
-`loop` is for long-running outer task memory: objective/context projection, round records, signals, derived events, verification summaries, and closeout draft. It is not a substitute for Agent DAG.
+`loop` 用于 long-running outer task memory：objective/context projection、round records、signals、derived events、verification summaries、closeout draft。它不是 Agent DAG 的 substitute。
 
-Typical loop path for governed work:
+Governed work 的典型 loop path：
 
 ```bash
 loop-agent loop init <task-id>
@@ -130,22 +130,22 @@ loop-agent loop run <task-id> --auto --max-rounds 3 --allow-cursor-fix
 loop-agent loop closeout <task-id>
 ```
 
-Loop action rules:
+Loop action rules：
 
-- `shell-verify` is deterministic; exit code determines the verification record.
-- `pi-review` is read-only; tools are limited to `read,grep,find,ls` and output is structured advisory evidence. Its structured JSON must include `findingSummary`, `failureCategory`, `nextHypothesis`, `recommendedAction`, `fixScope`, and `rootCause`; `recommendedAction` is exactly `implement_fix|replan|pause|done`.
-- `cursor-fix` is bounded write; it must read task `allowedPaths` / `forbiddenPaths`, reject empty `allowedPaths`, reject allowed/forbidden overlap, preserve unrelated files, and be followed by shell verification or review.
-- For `task.json.complexity = medium | large`, `cursor-fix` additionally requires either:
-  - a previous loop `dag` round, or
-  - an explicit `task.json.dagFallbackReason` explaining why DAG could not be used.
-- `loop run --auto` does not write by default. Auto `cursor-fix` requires `task.json.loopAutoWritePolicy="enabled"`, or `loopAutoWritePolicy="approval-required"` plus a pending approval signal or `--allow-cursor-fix`; write guards still fail closed and pause.
-- `loop closeout` must report workflow path: `dag`, `explicit-fallback`, `missing-dag-evidence`, or `micro-or-small`.
-- Medium/large closeout without DAG evidence and without `dagFallbackReason` must list that as a remaining risk.
-- `record-round --decision complete` is only a loop-state candidate; completion still requires shell verification, review verdict, and success-criteria coverage.
+- `shell-verify` 是 deterministic；exit code 决定 verification record。
+- `pi-review` 是 read-only；tools 限于 `read,grep,find,ls`，output 为 structured advisory evidence。Structured JSON 须含 `findingSummary`、`failureCategory`、`nextHypothesis`、`recommendedAction`、`fixScope`、`rootCause`；`recommendedAction`  exactly 为 `implement_fix|replan|pause|done`。
+- `cursor-fix` 是 bounded write；须读 task `allowedPaths` / `forbiddenPaths`，reject empty `allowedPaths`、allowed/forbidden overlap，preserve unrelated files，且须 follow shell verification 或 review。
+- 对 `task.json.complexity = medium | large`，`cursor-fix`  additionally 需要：
+  - previous loop `dag` round，或
+  - explicit `task.json.dagFallbackReason` 说明为何不能用 DAG。
+- `loop run --auto` 默认不 write。Auto `cursor-fix` 需要 `task.json.loopAutoWritePolicy="enabled"`，或 `loopAutoWritePolicy="approval-required"` 加 pending approval signal 或 `--allow-cursor-fix`；write guards 仍 fail closed 并 pause。
+- `loop closeout` 须报告 workflow path：`dag`、`explicit-fallback`、`missing-dag-evidence` 或 `micro-or-small`。
+- 无 DAG evidence 且无 `dagFallbackReason` 的 medium/large closeout 须将其列为 remaining risk。
+- `record-round --decision complete` 仅是 loop-state candidate；completion 仍须 shell verification、review verdict、success-criteria coverage。
 
 ## Supervised DAG convergence
 
-Supervised DAG convergence is optional and task-config driven:
+Supervised DAG convergence 可选且由 task-config 驱动：
 
 ```json
 {
@@ -160,34 +160,34 @@ Supervised DAG convergence is optional and task-config driven:
 
 Rules:
 
-- Default remains single repair unless `convergence.enabled=true`; `HARNESS_DAG_CONVERGENCE=off` is the rollback switch.
-- The supervised process supervisor must emit first-line `VERDICT:` and a `REPAIR_ARTIFACT_JSON` fenced block. Repair prompts should consume artifact `failureClass`, `rootCause`, `fixScope`, and `invariant` first; raw logs are fallback evidence only when the artifact allows it.
-- On retryable `hard-verify-shell` failure before `maxPasses`, preserve current pass evidence under `convergence/pass-N/`, reset the process-supervisor/process-gate/repair/hard-verify segment plus blocked downstream nodes, and re-enter the existing DAG rank execution loop.
-- Do not retry write guards, timeout/spawn/auth failures, or human-gate failures.
-- Pause instead of retrying when conservative regression signals appear, such as a lower shell success count.
-- `dag report --json` and markdown must expose `convergence.passHistory`.
-- Final completion authority remains full shell verification; quota/focused commands are intermediate cost controls only.
-
-## Structured repair, spine audit, and curator gates
+- 默认保持 single repair，除非 `convergence.enabled=true`；`HARNESS_DAG_CONVERGENCE=off` 是 rollback switch。
+- Supervised process supervisor 须 emit 首行 `VERDICT:` 与 `REPAIR_ARTIFACT_JSON` fenced block。Repair prompts 应先消费 artifact `failureClass`、`rootCause`、`fixScope`、`invariant`；raw logs 仅在 artifact 允许时为 fallback evidence。
+- 在 `maxPasses` 前 retryable `hard-verify-shell` failure 时，preserve current pass evidence 于 `convergence/pass-N/`，reset process-supervisor/process-gate/repair/hard-verify segment 及 blocked downstream nodes，再进入现有 DAG rank execution loop。
+- 不要 retry write guards、timeout/spawn/auth failures 或 human-gate failures。
+- 出现 conservative regression signals（如 lower shell success count）时 pause 而非 retry。
+- `dag report --json` 与 markdown 须 expose `convergence.passHistory`。
+- Final completion authority 仍是 full shell verification；quota/focused commands 仅为 intermediate cost controls。
 
-- `shell.repairArtifactGate.fromNodeId` validates the upstream supervisor artifact before repair. Missing/invalid JSON, missing request-revision `fixScope`, or scope outside the downstream repair writer allowedPaths/writeSet fails closed.
-- `spine audit <task-id>` is the deterministic minimal spec spine checker for task source, ownership paths, requirement coverage, and final verification commands.
-- `dag validate --strict-governance --spine-task <task-id>` may consume the same spine audit as part of strict validation.
-- `knowledge curate` reads completed convergence patterns and writes only human-gated proposal Markdown after skill safety preflight.
+## Structured repair, spine audit, and curator gates
+
+- `shell.repairArtifactGate.fromNodeId` validates the upstream supervisor artifact before repair. Missing/invalid JSON, missing request-revision `fixScope`, or scope outside the downstream repair writer allowedPaths/writeSet fails closed.
+- `spine audit <task-id>` is the deterministic minimal spec spine checker for task source, ownership paths, requirement coverage, and final verification commands.
+- `dag validate --strict-governance --spine-task <task-id>` may consume the same spine audit as part of strict validation.
+- `knowledge curate` reads completed convergence patterns and writes only human-gated proposal Markdown after skill safety preflight.
 
 ## SePO-lite prompt evolution
 
-- Learned prompt deltas are human-gated proposals; they must be reviewed before becoming reusable guidance.
-- Prompt deltas are Markdown-only process guidance; they must not include shell commands, credential handling, tool permission expansion, or completion-authority bypass.
-- Accepted learned guidance lives under `./skill/references/learned/<repo>.md` or `default.md`.
-- DAG implementer prompts that already request `loop-agent` may inline at most three human-gated learned Markdown sections.
-- Learned guidance is advisory and never replaces writeSet governance, Decision Gate policy, or shell verification.
+- 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`。
+- 已 request `loop-agent` 的 DAG implementer prompts 可 inline 最多三个 human-gated learned Markdown sections。
+- Learned guidance 为 advisory，永不替代 writeSet governance、Decision Gate policy 或 shell verification。
 
 ## Sidecar interventions
 
-`pi-prompt` and `cursor-prompt` are sidecar interventions, not workflow state.
+`pi-prompt` 与 `cursor-prompt` 是 sidecar interventions，不是 workflow state。
 
-Use `pi-prompt` for short read-only planning, log explanation, or failure diagnosis. When read-only, pass read-only tools and say not to edit files:
+用 `pi-prompt` 做短时 read-only planning、log explanation 或 failure diagnosis。Read-only 时传 read-only tools 并写明不 edit files：
 
 ```bash
 loop-agent pi-prompt \
@@ -197,7 +197,7 @@ loop-agent pi-prompt \
   "Read the task source and diagnose the failure. Do not edit files."
 ```
 
-Use `cursor-prompt` for bounded multi-file diagnosis or small repair only when the prompt includes:
+用 `cursor-prompt` 做 bounded multi-file diagnosis 或 small repair，prompt 须含：
 
 - task id
 - exact objective
@@ -207,52 +207,52 @@ Use `cursor-prompt` for bounded multi-file diagnosis or small repair only when t
 - expected verification
 - instruction to preserve unrelated files
 
-Sidecar output is advisory. If it must become task evidence, promote or summarize it through loop-agent run/task artifacts; do not manually mutate completed DAG or one-shot run facts.
+Sidecar output 为 advisory。若须成为 task evidence，通过 loop-agent run/task artifacts promote 或 summarize；completed DAG 与 one-shot run facts 保持只读。
 
 ## Model and executor boundaries
 
-- Agent DAG uses DAG JSON `executorModels` plus node `executor` / `complexity`; do not infer DAG models from repo `harness.json.models`.
-- DAG `shell` and `static` nodes do not use models.
-- Historical step models under `harness.json.models.<step>` are legacy metadata, not routing for new DAG work.
-- `pi-prompt` / `cursor-prompt` models come from CLI flags or runtime defaults and must be selected per intervention.
-- Pi DAG nodes are read-only planning/review/diagnosis by default.
-- Cursor nodes are bounded writers and must have explicit write scope.
-- Shell nodes produce deterministic verification facts and gates.
+- Agent DAG 用 DAG JSON `executorModels` 加 node `executor` / `complexity`；不要从 repo `harness.json.models` 推断 DAG models。
+- DAG `shell` 与 `static` nodes 不用 models。
+- `harness.json.models.<step>` 下 historical step models 是 legacy metadata，不是新 DAG work 的 routing。
+- `pi-prompt` / `cursor-prompt` models 来自 CLI flags 或 runtime defaults，须 per intervention 选择。
+- Pi DAG nodes 默认 read-only planning/review/diagnosis；声明 `toolProfile: "write"` 时是 bounded writers，须有 explicit write scope。
+- Cursor nodes 是显式启用的可选 bounded writers，须有 explicit write scope。
+- Shell nodes 产出 deterministic verification facts 与 gates。
 
 ## Artifacts and facts boundary
 
-- `.harness/tasks/<task-id>/` is task runtime state.
-- `.harness/tasks/<task-id>/loop/` is loop runtime projection; it does not replace task source or repo specs.
-- `.harness/dag-runs/{active,paused,completed}/<run-id>/` is DAG run fact storage. Completed facts are read-only.
-- `.harness/runs/{active,completed,failed}/<run-id>/` is one-shot Pi/Cursor evidence. Completed/failed facts are read-only.
-- Root `artifacts/` is legacy/current-work summary space, not a DAG read-only scratchpad and not default handoff for new DAG work.
-- Long-term conclusions belong in repo governance docs, progress, reports, decisions, tests, or scripts.
+- `.harness/tasks/<task-id>/` 是 task runtime state。
+- `.harness/tasks/<task-id>/loop/` 是 loop runtime projection；不替代 task source 或 repo specs。
+- `.harness/dag-runs/{active,paused,completed}/<run-id>/` 是 DAG run fact storage。Completed facts 为 read-only。
+- `.harness/runs/{active,completed,failed}/<run-id>/` 是 one-shot Pi/Cursor evidence。Completed/failed facts 为 read-only。
+- Root `artifacts/` 是 legacy/current-work summary space，不是 DAG read-only scratchpad，也不是新 DAG work 的 default handoff。
+- Long-term conclusions 属于 repo governance docs、progress、reports、decisions、tests 或 scripts。
 
-Do not submit runtime histories from `.harness/dag-runs/`, `.harness/runs/`, or `.harness/cache/` unless a task explicitly promotes a trimmed report into repo governance docs.
+除非 task 显式 promote trimmed report 到 repo governance docs，不要提交 `.harness/dag-runs/`、`.harness/runs/` 或 `.harness/cache/` 的 runtime histories。
 
 ## Baseline, dirty workspace, and verification
 
-Before complex implementation:
+Complex implementation 前：
 
-1. Check current directory and target repo.
-2. Read repo entrypoints (`README`, `AGENTS`, `harness.json`, governance index).
-3. Capture minimal baseline verification for the affected area.
-4. If the workspace is dirty, choose one:
-   - isolated worktree, or
-   - explicit user confirmation to work in the current workspace and preserve/possibly include existing changes.
-5. Record known baseline failures with enough detail to distinguish pre-existing failures from task regressions.
+1. Check current directory 与 target repo。
+2. Read repo entrypoints（`README`、`AGENTS`、`harness.json`、governance index）。
+3. Capture affected area 的 minimal baseline verification。
+4. 若 workspace dirty，选一：
+   - isolated worktree，或
+   - explicit user confirmation 在当前 workspace 工作并 preserve/possibly include existing changes。
+5. Record known baseline failures，足以区分 pre-existing failures 与 task regressions。
 
-Verification should be selected from the target repo's verification matrix. For cross-repo documentation refactors, run checks in each affected repo.
+Verification 应从 target repo verification matrix 选择。Cross-repo documentation refactors 时在 each affected repo 跑 checks。
 
 ## Handoff requirements
 
-Every task handoff should answer:
+每个 task handoff 应回答：
 
-1. What changed and why.
-2. Which workflow path was used: DAG, sidecar, or main-session surgical patch.
-3. If downgraded from DAG, the explicit reason and evidence.
-4. Executors used and their boundaries.
-5. Verification commands run and results.
-6. DAG / one-shot / loop refs, if any.
-7. Remaining risks and follow-up tasks.
-8. Whether new rules should be promoted to docs, tests, scripts, or shared skill references.
+1. What changed and why。
+2. 用了哪条 workflow path：DAG、sidecar 或 main-session surgical patch。
+3. 若从 DAG downgrade，explicit reason 与 evidence。
+4. Executors used 及其 boundaries。
+5. Verification commands run 与 results。
+6. DAG / one-shot / loop refs（如有）。
+7. Remaining risks 与 follow-up tasks。
+8. 是否应将 new rules promote 到 docs、tests、scripts 或 shared skill references。

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

@@ -1,21 +1,21 @@
 # Learned loop-agent Patterns
 
-This directory is the human-gated target for SePO-lite prompt evolution.
+本目录是 SePO-lite prompt evolution 的 human-gated target。
 
 Rules:
 
-- Files are Markdown guidance only.
-- `retrospective` may propose `.harness/tasks/<task-id>/source/prompt-delta.md`; it must not merge here automatically.
-- Do not add shell commands, credential handling, tool permission expansion, or completion-authority bypass rules.
-- DAG implementer prompts may load the repo-specific file `<repo>.md` or `default.md` as bounded inline guidance when the node already requests the `loop-agent` skill.
-- Keep entries short and pattern-oriented: failure class, fix scope shape, invariant, and verification evidence.
+- Files 仅为 Markdown guidance。
+- `retrospective` 可 propose `.harness/tasks/<task-id>/source/prompt-delta.md`；不得自动 merge 到此。
+- 不要添加 shell commands、credential handling、tool permission expansion 或 completion-authority bypass rules。
+- DAG implementer prompts 在 node 已 request `loop-agent` skill 时，可将 repo-specific 文件 `<repo>.md` 或 `default.md` 作为 bounded inline guidance 加载。
+- 保持条目 short 且 pattern-oriented：failure class、fix scope shape、invariant、verification evidence。
 
 Acceptance checklist before merging a prompt delta:
 
-- The proposal is Markdown-only process guidance.
-- It contains no shell/runtime command lines or fenced command blocks.
-- It does not ask to read, print, export, collect, or handle credentials, tokens, passwords, secrets, or API keys.
-- It does not expand tool permissions, path allowlists, `allowedPaths`, `forbiddenPaths`, or `writeSet`.
-- It does not skip or bypass shell verification, tests, write guards, decision gates, human gates, or completion evidence.
-- It does not modify, rewrite, delete, overwrite, or mutate completed DAG / one-shot run facts.
-- `loop-agent docs audit` passes after the learned file is edited.
+- Proposal 仅为 Markdown-only process guidance。
+- 不含 shell/runtime command lines 或 fenced command blocks。
+- Credential material、tokens、passwords、secrets 与 API keys 保持不可触达。
+- Tool permissions、path allowlists、`allowedPaths`、`forbiddenPaths` 与 `writeSet` 保持既有边界。
+- Shell verification、tests、write guards、decision gates、human gates 与 completion evidence 均为保留门禁。
+- Completed DAG 与 one-shot run facts 保持只读。
+- Learned file 编辑后 `loop-agent docs audit` 须 pass。

package/skills/loop-agent/references/long-running-loop.md

@@ -0,0 +1,59 @@
+# Long-Running Loop 详细规则
+
+需要跨多轮记录目标、压缩记忆、round facts 引用，或使用 `loop init|status|run|record-round|add-signal|closeout` 时使用本文。`loop` 是 experimental outer workflow state：它不替代 Agent DAG，也不等同于已移除的顺序式 `run loop`。共享 policy 摘要见 `harness-policy.md` 的 "Long-running loop policy" 一节。
+
+## 最小入口
+
+```bash
+loop-agent loop init <task-id>
+loop-agent loop status <task-id>
+loop-agent loop run <task-id> --action shell-verify --command "bash scripts/check-repo.sh"
+loop-agent loop run <task-id> --action pi-review
+loop-agent loop run <task-id> --action cursor-fix --model composer-2.5
+loop-agent loop run <task-id> --action dag
+loop-agent loop run <task-id> --action dag --execute
+loop-agent loop run <task-id> --auto --max-rounds 3
+loop-agent loop run <task-id> --auto --max-rounds 3 --allow-cursor-fix
+loop-agent loop add-signal <task-id> --type human_followup --message "review this boundary before closeout"
+loop-agent loop closeout <task-id>
+loop-agent loop record-round <task-id> \
+  --action manual \
+  --result "summary" \
+  --lesson "what to carry forward" \
+  --next "next bounded action" \
+  --decision continue \
+  --ref ".harness/runs/completed/<run-id>/result.json"
+```
+
+## 状态源与记忆规则
+
+- `loop/objective.md` 与 `loop/context.md` 是运行态投影；exec plan / task source 仍是需求状态源。
+- `rounds.jsonl` 只引用 canonical facts，不复制完整 executor 日志。
+- `context.md` 每轮重写为压缩记忆，不无限 append。
+- `events.jsonl` 只用于 observability，覆盖 loop_start、round_start、action_start、action_finish、context_rewrite、decision、loop_finish；不要把 events 当状态源。
+
+## Action 规则
+
+- `loop run --action shell-verify` 是 deterministic action；命令 exit code 决定 verification result，输出摘要写入 `loop/verification/round-N.json`。
+- `loop run --action pi-review` 必须保持 read-only；工具 allowlist 固定为 `read,grep,find,ls`，输出必须包含 `findingSummary`、`failureCategory`、`nextHypothesis`、`recommendedAction`、`fixScope`、`rootCause`，其中 `recommendedAction` 只能是 `implement_fix|replan|pause|done`。
+- `loop run --action cursor-fix` 必须读取 task `allowedPaths` / `forbiddenPaths`，拒绝空 allowedPaths 或 allowed/forbidden overlap；对 `complexity=medium|large` 的任务，还必须已有 loop `dag` round 证据，或在 `task.json.dagFallbackReason` 中写明 DAG runtime fallback 原因。调用现有 Cursor bounded executor，并把 one-shot evidence 归档到 `.harness/runs/completed|failed/`。
+- `cursor-fix` 只表示 bounded write round 已执行；它不会把 loop 标记 complete，下一步必须进入 `shell-verify` 或 review。
+- `loop run --action dag` 默认是 review mode：调用 `dag run-task <task-id> --profile auto --strict-models` 生成 DAG，再用 `dag validate --strict-models --strict-governance` 校验，并记录 review packet。
+- `loop run --action dag --execute` 才会调用 `run-dag`，随后读取 `dag report --json` 作为 round result；paused DAG 会让 loop 进入 `paused`。
+
+## Auto mode 与写入边界
+
+- `loop run --auto --max-rounds N` 使用 deterministic policy 选择下一轮 action；默认只会自动选择 shell-verify、pi-review、dag review 或 policy pause/block，不自动触发 Cursor 写入。
+- 自动 `cursor-fix` 必须显式 opt-in：`task.json.loopAutoWritePolicy="enabled"`，或 `loopAutoWritePolicy="approval-required"` 加 pending approval signal / `--allow-cursor-fix`。即使 opt-in，也必须通过 `allowedPaths`/`forbiddenPaths`/DAG evidence guard；guard 失败会 pause，不会绕过写入边界。
+- auto mode 遇到同类 failure streak 达阈值会 blocked，避免无限重试。
+
+## Signals
+
+- `loop add-signal` 写入 durable `signals.jsonl`，支持 `human_followup|approval|scope_changed|review_feedback`；urgent/scope_changed 会 pause，review feedback / human follow-up 先走 read-only Pi review，approval 触发下一轮 DAG review packet。
+- Signals 不直接覆盖 `objective.md`；DAG decision envelope / approve / reject / resume 仍由 DAG action 机制管理，loop 只记录 refs。
+
+## Closeout
+
+- `loop closeout` 从 loop state、objective/context、rounds 和 signals 派生 `loop/closeout.md` draft；draft 会标出 workflow path（`dag` / `explicit-fallback` / `missing-dag-evidence` / `micro-or-small`）与 fallback reason。
+- 非 complete 状态必须标 partial/paused/blocked，不能修改 completed facts；medium/large loop 若缺少 DAG round 且没有 `dagFallbackReason`，必须把缺失 DAG 证据列为 remaining risk。
+- 完成声明仍必须由 shell verification、review verdict 和 success criteria coverage 证明。

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

@@ -2,8 +2,6 @@
 
 loop-agent task 启用 `piSubagentMode`、在 analyze/plan/spec/retrospective 内需要 read-only scout/planner/reviewer subagents，或配置 project-local agents/prompts 时使用本文。
 
-## Pi Subagent Assisted Mode
-
 `task.json` 支持可选字段 `piSubagentMode`，用于 step 级 `subagent` tool delegation：
 
 | Mode | analyze | plan | spec | implement | retrospective | verify |

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

@@ -56,6 +56,24 @@
 
 最佳实践：保持 `allowedPaths` 准确。auto-commit 用 task path 约束，避免把无关 dirty 文件扫进 progress commit。
 
+### Cursor bounded write 后的独立复核
+
+Cursor bounded execution 完成后，主会话必须独立执行：
+
+```bash
+git status --short
+git diff --stat
+bash scripts/check-repo.sh
+npm run lint
+npm test
+npm run typecheck
+loop-agent inspect
+loop-agent docs audit
+loop-agent handoff check <task-id>
+```
+
+Cursor 自己报告的完成不算 verification fact；以上命令的 exit code 与输出才是完成声明的证据。
+
 ### 失败处理
 
 child agent 失败时：

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

@@ -1,25 +1,25 @@
 ---
 name: requesting-code-review
-description: Use when completing tasks, implementing major features, or before merging to verify work meets requirements
+description: 在完成任务、实现 major features，或 merge 前验证 work 是否满足 requirements 时使用
 ---
 
 # Requesting Code Review
 
-Dispatch a code reviewer subagent to catch issues before they cascade. The reviewer gets precisely crafted context for evaluation — never your session's history. This keeps the reviewer focused on the work product, not your thought process, and preserves your own context for continued work.
+Dispatch code reviewer subagent，在问题级联前捕获 issue。Reviewer 获得精确 crafted 的 evaluation context — 绝不是你的 session history。这使 reviewer 聚焦 work product，而非你的 thought process，并保留你自己的 context 以继续工作。
 
-**Core principle:** Review early, review often.
+**Core principle：** Review early, review often.
 
 ## When to Request Review
 
-**Mandatory:**
-- After each task in subagent-driven development
-- After completing major feature
-- Before merge to main
+**Mandatory：**
+- subagent-driven development 中每个 task 之后
+- 完成 major feature 之后
+- merge 到 main 之前
 
-**Optional but valuable:**
-- When stuck (fresh perspective)
-- Before refactoring (baseline check)
-- After fixing complex bug
+**Optional but valuable：**
+- 卡住时（fresh perspective）
+- refactoring 前（baseline check）
+- 修复 complex bug 之后
 
 ## How to Request
 
@@ -29,19 +29,19 @@ BASE_SHA=$(git rev-parse HEAD~1)  # or origin/main
 HEAD_SHA=$(git rev-parse HEAD)
 ```
 
-**2. Use the code reviewer template** (`code-reviewer.md` in this skill directory):
+**2. Use the code reviewer template**（本 skill 目录下的 `code-reviewer.md`）：
 
 **Placeholders:**
-- `{DESCRIPTION}` - Brief summary of what you built
-- `{PLAN_OR_REQUIREMENTS}` - What it should do (contract, exec plan, or requirements)
-- `{BASE_SHA}` - Starting commit
-- `{HEAD_SHA}` - Ending commit
+- `{DESCRIPTION}` — 简要 summary of what you built
+- `{PLAN_OR_REQUIREMENTS}` — 它应做什么（contract、exec plan 或 requirements）
+- `{BASE_SHA}` — Starting commit
+- `{HEAD_SHA}` — Ending commit
 
 **3. Act on feedback:**
-- Fix Critical issues immediately
-- Fix Important issues before proceeding
-- Note Minor issues for later
-- Push back if reviewer is wrong (with reasoning)
+- Critical issues 立即修复
+- Important issues 在继续前修复
+- Minor issues 稍后处理
+- Reviewer 有误时 push back（附 reasoning）
 
 ## Example
 
@@ -72,30 +72,30 @@ You: [Fix progress indicators]
 
 ## Integration with Harness Workflow
 
-**After each work chunk (Plan → Contract → Implement → Verify → Handoff):**
-- Review after Implement, before Verify
-- Catch issues before they compound
-- Fix before moving to next task
+**每个 work chunk 之后（Plan → Contract → Implement → Verify → Handoff）：**
+- Implement 之后、Verify 之前 review
+- 在问题 compound 前捕获
+- 进入 next task 前修复
 
-**Before merge / Handoff:**
-- Review before declaring complete
-- Verify against contract acceptance criteria
+**Before merge / Handoff：**
+- 宣称 complete 前 review
+- 对照 contract acceptance criteria 验证
 
-**Ad-Hoc Development:**
-- Review before merge
-- Review when stuck
+**Ad-Hoc Development：**
+- merge 前 review
+- 卡住时 review
 
 ## Red Flags
 
-**Never:**
-- Skip review because "it's simple"
-- Ignore Critical issues
-- Proceed with unfixed Important issues
-- Argue with valid technical feedback
+**Never：**
+- 因 "it's simple" 跳过 review
+- 忽略 Critical issues
+- 带着未修复的 Important issues 继续
+- 与 valid technical feedback 争辩
 
-**If reviewer wrong:**
-- Push back with technical reasoning
-- Show code/tests that prove it works
-- Request clarification
+**If reviewer wrong：**
+- 用 technical reasoning push back
+- 展示证明其有效的 code/tests
+- 请求 clarification
 
-See template at: requesting-code-review/code-reviewer.md
+Template 见：requesting-code-review/code-reviewer.md