@tea-agent/loop-agent 0.1.0

package/docs/exec-plans/README.md

@@ -0,0 +1,6 @@
+# Execution Plans
+
+- `active/README.md` lists currently active plans.
+- `completed/README.md` lists completed plans.
+
+Use an execution plan for changes that affect multiple files, public command behavior, or repository governance.

package/docs/exec-plans/active/README.md

@@ -0,0 +1,5 @@
+# Active Execution Plans
+
+Use this directory for execution plans that are currently in progress.
+
+Source repositories may keep concrete active plan files next to this README. The npm package carries this README as a directory contract and does not copy loop-agent source-history active plans; target repositories generate their own active plans.

package/docs/exec-plans/completed/README.md

@@ -0,0 +1,5 @@
+# Completed Execution Plans
+
+Completed plans are moved here after their implementation and verification finish.
+
+The npm package carries this README as a directory contract. Concrete completed plans are target-repository history and are not copied from loop-agent's source history.

package/docs/feature-workflow.md

@@ -0,0 +1,184 @@
+# Feature Workflow
+
+This document separates two layers:
+
+- Session governance: how the supervising human/agent should structure a work session.
+- Runtime workflows: what the code actually executes under `src/workflows/`.
+
+## Default Session Protocol
+
+1. Orient: read `README.md`, `harness.json`, and this docs index.
+2. Select: choose one bounded work block.
+3. Contract: state deliverables, non-goals, completion criteria, verification commands, and failure conditions.
+4. Implement: make the smallest coherent change and update required docs, scripts, and tests.
+5. Verify: run commands from `verification-matrix.md`; use fresh output for any completion claim.
+6. Handoff: record evidence in `docs/progress/`, `docs/reports/`, an exec plan, or an ADR when useful.
+
+## Orient
+
+Start by understanding the current system rather than assuming absence:
+
+- read the repository entrypoints listed in `harness.json`
+- check `git status --short --branch` and recent commits
+- search existing source, tests, scripts, docs, and templates before adding new structure
+- run the smallest baseline check if the task depends on a healthy baseline
+- read methodology docs when the task involves TDD, verification claims, or debugging
+
+If the baseline is already broken, record the failing command and decide whether the current work block is to repair the baseline or to proceed with a clearly scoped known failure.
+
+## Select
+
+Keep a work block narrow enough to verify. Avoid combining unrelated refactors, features, and documentation migrations.
+
+A selected block should have:
+
+- a single user-visible or maintainer-visible outcome
+- explicit allowed paths when delegating write work
+- known non-goals
+- a verification command that can prove the result
+
+## Contract
+
+For non-trivial work, write or update an execution plan, sprint contract, progress log, or issue-sized note before implementation. The contract should state:
+
+- deliverables
+- non-goals
+- acceptance criteria
+- verification commands
+- failure conditions
+- expected artifacts to update
+
+For bug fixes, the contract should include the reproduction path and the regression test or smoke check that proves the fix.
+
+## Implement
+
+Make the smallest coherent change that satisfies the contract.
+
+- Prefer existing helpers and directory boundaries.
+- Update tests for behavior changes.
+- Update docs and examples for workflow or command changes.
+- Update `harness.json`, check scripts, or templates for governance changes.
+- Do not submit placeholder implementations as completed work.
+- When a repeated constraint appears, promote it into a durable artifact.
+
+## Verify
+
+Verification is the completion authority.
+
+- Use `docs/verification-matrix.md` to choose the narrowest proving command.
+- Run the full command fresh.
+- Read the exit code and output.
+- Fix failures or report the exact failing state.
+- Do not claim completion from stale output or partial checks.
+
+## Agent DAG First
+
+For complex implementation work, prefer the DAG workflow:
+
+```bash
+loop-agent new-task <task-id> "Task title"
+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 .
+```
+
+`<temp-dir>` means the platform-native temp directory. Use native paths for actual file operations on macOS and Windows; use `/` only for stable repo refs, JSON/Markdown evidence refs, and glob conventions.
+
+This is not a linear OS-CIVH runtime state machine. In code, DAG has three command phases:
+
+1. `dag run-task` loads `.harness/tasks/<task-id>/source/需求.md`, optional `执行约束.md`, `task.json`, and adapter verification commands, then writes a DAG spec.
+2. `dag validate` validates schema, dependencies, governance profile, write boundaries, model routing, and shell verification metadata.
+3. `run-dag` loads the DAG, topologically sorts tasks into ranks, executes runnable nodes with bounded concurrency, persists `.harness/dag-runs/<lifecycle>/<run-id>/`, and transfers the run to `completed` or `paused`.
+
+The standard generated hybrid DAG defaults to no-Cursor execution:
+
+```text
+contract-pi
+  -> scout-src + scout-tests
+  -> plan-pi
+  -> implement-pi
+  -> verify-pi
+  -> closeout-pi
+```
+
+`implement-pi` uses `executor: "pi"` with `toolProfile: "write"`. When `harness.json` explicitly disables Pi and enables Cursor, the implementation and repair writer nodes use `implement-cursor` / `repair-cursor` instead.
+
+The review-gated template inserts:
+
+```text
+verify-pi -> review-pi -> review-gate-shell -> closeout-pi
+```
+
+The supervised template adds write-set audit, soft/hard shell verification, process supervision, bounded repair, decision gates, and optional convergence retry passes around the implementation path.
+
+Source references:
+
+- `src/commands/dag-run-task.ts`
+- `src/commands/dag-validate.ts`
+- `src/commands/run-dag.ts`
+- `src/workflows/dag/init-hybrid.ts`
+- `src/workflows/dag/runner.ts`
+
+The supervising agent remains responsible for:
+
+- writing the contract
+- bounding allowed and forbidden paths
+- reviewing DAG/writeSet scope
+- selecting verification commands
+- recording handoff evidence
+
+## Removed Sequential Workflow
+
+The historical Level 1 sequential command surface has been removed from the public workflow. Do not use `loop-agent run analyze|plan|spec|implement|verify|retrospective|auto|loop|continue|study` for new work.
+
+Use the DAG path instead:
+
+```bash
+loop-agent new-task <task-id> "Task title"
+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 .
+```
+
+Legacy `.harness/tasks/<task-id>/.workflow_state.json` files may still be read for compatibility until task status is fully migrated to the DAG-oriented read model. They are not the authority for new task completion.
+
+## Outer Loop Runtime
+
+The `loop` command is a long-running task-control layer, not the same thing as the session governance protocol. It records rounds and signals, can run shell verification, Pi review, Cursor fixes, or DAG actions, and can choose the next automatic action.
+
+Supported loop actions are:
+
+- `shell-verify`
+- `pi-review`
+- `cursor-fix`
+- `dag`
+- `record-round`
+- `add-signal`
+- `closeout`
+
+Source references:
+
+- `src/commands/loop.ts`
+- `src/workflows/loop/actions.ts`
+- `src/workflows/loop/state.ts`
+- `src/workflows/loop/rounds.ts`
+
+## Debugging And TDD
+
+Use the methodology docs when the task demands it:
+
+- behavior changes and bug fixes: `docs/harness-methodology-tdd.md`
+- completion or handoff claims: `docs/harness-methodology-verification.md`
+- failures and unexpected behavior: `docs/harness-methodology-debugging.md`
+
+## Handoff
+
+A handoff should state:
+
+- what changed
+- what was intentionally left out
+- which verification commands ran
+- whether contracts, docs, tests, or scripts were affected
+- any remaining risks or follow-up work
+
+For substantial work, update `docs/progress/`, `docs/reports/`, the active exec plan, or `docs/decisions/` so the next session can resume without relying on chat history.

package/docs/harness-methodology-debugging.md

@@ -0,0 +1,153 @@
+# Harness Methodology: Systematic Debugging
+
+从 Superpowers `systematic-debugging` skill 中提取的调试方法，适配本仓库 harness 工作流。
+
+## Iron Law
+
+```
+NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
+```
+
+没有完成 Phase 1（根因调查），就不能提出任何修复方案。修症状 = 失败。
+
+## 何时使用
+
+适用于任何技术问题：
+- 测试失败
+- 生产 bug
+- 意外行为
+- 性能问题
+- 构建/集成失败
+
+**尤其要在以下情况使用：**
+- 时间压力下（紧急情况最容易让人猜）
+- "一个快速修复"看起来很明显
+- 已经试过多次修复
+- 上一个修复没奏效
+- 不完全理解问题
+
+## 四阶段流程
+
+每个阶段必须完成才能进入下一个。
+
+### Phase 1：根因调查
+
+**在尝试任何修复之前：**
+
+1. **仔细读错误信息**
+   - 不要跳过 error 和 warning
+   - 错误信息常常包含精确的解决方案
+   - 完整读 stack trace
+   - 记下文件名、行号、错误码
+
+2. **稳定复现**
+   - 能可靠触发吗？
+   - 精确步骤是什么？
+   - 每次都发生？
+   - 如果不能复现 → 收集更多数据，不要猜
+
+3. **检查最近变更**
+   - 什么改动可能导致这个问题？
+   - `git diff`、最近提交
+   - 新依赖、配置变更
+   - 环境差异
+
+4. **多组件系统：收集跨层证据**
+
+   当系统涉及多个组件（CI → build → sign, API → service → DB）：
+   ```
+   对每个组件边界：
+     - 记录进入组件的数据
+     - 记录离开组件的数据
+     - 验证环境/配置传播
+     - 检查每层状态
+
+   跑一次收集证据 → 分析证据确定失败组件 → 针对该组件调查
+   ```
+
+5. **追踪数据流**
+
+   当错误在深层调用栈中：
+   - 坏值从哪里来？
+   - 谁用坏值调用了这里？
+   - 持续向上追踪直到源头
+   - 在源头修复，不在症状处修复
+
+### Phase 2：模式分析
+
+1. **找工作中的例子** — 在同一个代码库里定位相似的工作代码
+2. **对照参考实现** — 完整阅读参考实现，不要跳读
+3. **识别差异** — 列出工作和失败之间的每一项差异，再小也不假设"这不重要"
+4. **理解依赖** — 需要哪些其他组件、设置、配置、假设？
+
+### Phase 3：假设与测试
+
+1. **形成单一假设** — "我认为 X 是根因，因为 Y"
+2. **最小测试** — 做最小的改动来测试假设，一次只变一个变量
+3. **验证后再继续** — 成功了？→ Phase 4。没成功？→ 形成新假设。不要在原假设上叠加更多修复
+
+### Phase 4：实现
+
+1. **创建失败测试用例** — 遵循 RED-GREEN-REFACTOR（见 `docs/harness-methodology-tdd.md`）
+2. **实现单一修复** — 解决已识别的根因，一次一个改动，不顺手重构
+3. **验证修复** — 测试通过？其他测试没坏？问题真的解决了？
+4. **如果修复无效**：
+   - 尝试了几个修复？
+   - < 3 个 → 回到 Phase 1 重新分析
+   - **≥ 3 个 → 停止，质疑架构（Phase 4.5）**
+
+### Phase 4.5：质疑架构
+
+**以下模式表明架构问题：**
+- 每次修复暴露新的共享状态/耦合/不同位置的问题
+- 修复需要"大规模重构"才能实现
+- 每次修复在其他地方产生新症状
+
+**停止并质疑基础：**
+- 这个模式从根本上正确吗？
+- 我们是否在"靠惯性坚持它"？
+- 是否应该重构架构，而不是继续修症状？
+
+在尝试更多修复之前讨论。
+
+## Red Flags：停止并回到 Phase 1
+
+如果你发现自己这样想：
+- "先快速修一下，后面再调查"
+- "试试改 X 看看行不行"
+- "一次改多个东西然后跑测试"
+- "跳过测试，手工验证就行"
+- "大概就是 X 的问题，直接修吧"
+- "不太确定但可能有用"
+- "再试一个修复"（已经试了 2+ 次）
+
+**以上任何一种 → 停止。回到 Phase 1。**
+
+## 和 Harness 工作流的对齐
+
+| 调试阶段 | Harness 步骤 |
+|---------|-------------|
+| Phase 1：根因调查 | Baseline：先验证当前基线，确认 bug 是可复现的 |
+| Phase 2：模式分析 | Orient：读相关代码、文档、测试，找参考 |
+| Phase 3：假设测试 | Contract：写清修复假设和验证方法 |
+| Phase 4：实现 | Implement → Verify（TDD：先写失败测试） |
+| Phase 4.5：质疑架构 | 可能需要新的 exec plan |
+
+## 快速参考
+
+| 阶段 | 关键活动 | 成功标准 |
+|------|---------|---------|
+| 1. 根因 | 读错误、复现、查变更、收集证据 | 理解 WHAT 和 WHY |
+| 2. 模式 | 找工作中的例子、对比 | 识别差异 |
+| 3. 假设 | 形成理论、最小测试 | 确认或新假设 |
+| 4. 实现 | 创建测试、修复、验证 | Bug 解决、测试通过 |
+
+## 当流程揭示"无根因"时
+
+如果系统性调查揭示问题确实属于环境性、时序性或外部依赖：
+1. 已完成流程（不是跳过）
+2. 记录调查了什么
+3. 实现适当处理（重试、超时、错误提示）
+4. 添加监控/日志供将来调查
+
+**但是：** 95% 的"无根因"案例是不完整调查。

package/docs/harness-methodology-tdd.md

@@ -0,0 +1,130 @@
+# Harness Methodology: Test-Driven Development
+
+从 Superpowers `test-driven-development` skill 中提取的 TDD 纪律，适配本仓库 harness 工作流。
+
+## Iron Law
+
+```
+NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST
+```
+
+在测试之前写的任何实现代码，必须在写测试前删除。不是"留作参考"、不是"边写测试边改"——删除就是删除，从零开始实现。
+
+## RED-GREEN-REFACTOR 循环
+
+### RED：写一个失败测试
+
+写一个最小的测试，展示代码应该做什么。
+
+**要求：**
+- 一个行为
+- 清晰的命名
+- 真实代码（除非不可避免才 mock）
+
+```
+✅ test('rejects empty email', async () => {
+     const result = await submitForm({ email: '' });
+     expect(result.error).toBe('Email required');
+   })
+
+❌ test('retry works', ...)  // 名字模糊
+❌ test('validates email and domain and whitespace')  // 一次测太多
+```
+
+### Verify RED：看着它失败
+
+**不可跳过。**
+
+```bash
+npm test path/to/test.test.ts
+```
+
+确认：
+- 测试**失败**（不是报错）
+- 失败原因是你预期的（因为功能还没实现，而不是拼写错误）
+- 测试通过？→ 你在测已有行为，修正测试。测试报错？→ 修复错误，重新跑到真的失败为止。
+
+### GREEN：最小实现
+
+写刚好能让测试通过的最简单代码。不要加功能、不要重构其他代码、不要"顺手优化"。
+
+### Verify GREEN：看着它通过
+
+**不可跳过。**
+
+```bash
+npm test path/to/test.test.ts
+```
+
+确认：
+- 测试通过
+- 其他测试依然通过
+- 输出干净（无 error、warning）
+
+### REFACTOR：清理
+
+只在 GREEN 之后：
+- 消除重复
+- 改善命名
+- 提取辅助函数
+
+保持测试绿色。不添加行为。
+
+## 为什么顺序重要
+
+**"我先写实现再补测试"** → 实现后写的测试立即通过，这什么都证明不了。你可能测了错误的东西、漏了边界情况、从未见过它抓到 bug。测试先行迫使你看到测试失败，证明它确实在测有意义的东西。
+
+**"我已经手工测过了"** → 手工测试是临时的。没有记录、不能重跑、压力下容易忘。"刚刚试了能用" ≠ 全面覆盖。自动化测试是系统性的，每次跑得一样。
+
+**"删掉已写代码太浪费"** → 沉没成本谬误。时间已经花了。现在的选择是：(a) 删掉重写 TDD（X 小时，高信心）vs (b) 保留它然后补测试（30 分钟，低信心，大概率有 bug）。保留不可信的代码才是真正的浪费。
+
+## TDD 与 Harness 工作流的对齐
+
+| TDD 阶段 | Harness 步骤 |
+|----------|-------------|
+| RED | Contract → 写验收标准（含测试预期） |
+| GREEN | Implement → 最小实现 |
+| REFACTOR | Verify 通过后可做受控清理 |
+| 循环 | 下一个工作块 |
+
+## 验证清单
+
+在标记工作完成前：
+
+- [ ] 每个新函数/方法有对应测试
+- [ ] 看过每个测试在实现前失败
+- [ ] 每个测试因预期原因失败（功能缺失，不是拼写错误）
+- [ ] 为每个测试写了最小实现
+- [ ] 所有测试通过
+- [ ] 输出干净（无 error、warning）
+- [ ] 测试使用真实代码（仅在不可避免时 mock）
+- [ ] 边界情况和错误路径已覆盖
+
+无法勾完所有框 → 跳过了 TDD → 从 RED 重新开始。
+
+## 反模式
+
+- **测试 mock 行为而非真实行为**：mock 只在调用外部 API/DB 等不可避免时使用
+- **给生产类加仅测试用的方法**：设计接口应同时对生产者和消费者友好
+- **不理解依赖就 mock**：先理解数据流，再 mock
+
+## Bug 修复的 TDD
+
+发现 bug → 先写复现它的失败测试 → RED-GREEN-REFACTOR → 测试即证明修复有效且防止回归。
+
+永远不要在没有测试的情况下修 bug。
+
+## 当卡住时
+
+| 问题 | 解法 |
+|------|------|
+| 不知道怎么写测试 | 先写期望的 API 调用方式；先写断言 |
+| 测试太复杂 | 设计太复杂，简化接口 |
+| 必须 mock 一切 | 代码耦合太重，用依赖注入 |
+| 测试 setup 巨大 | 提取辅助函数；还是复杂？简化设计 |
+
+## 参考
+
+- Harness 工作流：`docs/feature-workflow.md`
+- 验证矩阵：`docs/verification-matrix.md`
+- Sprint Contract 模板：`docs/templates/sprint-contract.md`

package/docs/harness-methodology-verification.md

@@ -0,0 +1,27 @@
+# Verification Methodology
+
+Completion claims require current evidence.
+
+## Gate Function
+
+1. Identify the command that proves the claim.
+2. Run the full command.
+3. Read the output and exit code.
+4. Fix failures or report the exact failing state.
+5. Only then claim the result.
+
+## Common Gates
+
+| Claim | Command |
+|---|---|
+| Governance is valid | `bash scripts/check-repo.sh` |
+| TypeScript compiles | `npm run typecheck` |
+| Behavior is covered | `npm test` |
+| Full local delivery is valid | `bash scripts/ci.sh` |
+
+## Red Flags
+
+- claiming completion from intent
+- relying on stale command output
+- using a narrow check for a broad claim
+- skipping failed command details

package/docs/loop-agent-harness.md

@@ -0,0 +1,42 @@
+# loop-agent Harness
+
+loop-agent provides a local harness for structured agent work.
+
+## Runtime Areas
+
+- `.harness/tasks/` stores task source, constraints, state, and loop facts.
+- `.harness/dag-runs/` stores DAG run state and artifacts.
+- `.harness/runs/` stores one-shot tool run evidence.
+- `.harness/cache/` stores local runtime cache.
+- `.harness/live/` stores transient live-session files.
+
+## Skill Instructions
+
+- `skills/loop-agent/` stores loop-agent's repo-owned skill instructions and references.
+- `skills/<skill-name>/` stores local copies of skills referenced by DAG templates, including supervised implementation roles.
+- Historical `skill/` is no longer a required repository path; runtime lookup keeps it only as a compatibility fallback for `loop-agent`.
+
+## Package Assets
+
+The npm package includes static capability assets needed to run and explain the harness: `bin/`, `dist/`, `skills/`, top-level `docs/*.md`, `docs/templates/`, `examples/`, `harness.json`, `AGENTS.md`, `README.md`, and `CHANGELOG.md`.
+
+Generated or historical task facts are not package assets. Existing files under `docs/progress/`, `docs/reports/`, `docs/exec-plans/`, and `docs/decisions/` belong to the target repository's history; the package carries only the directory README files for those areas.
+
+When `loop-agent` is installed from npm and used against another project, DAG skill instructions resolve from configured, user, or target-local skill directories when present, then fall back to the package-bundled `skills/`. A target project may add local skills, but it does not need loop-agent's source history or a copied `skills/` directory to use the default DAG workflow.
+
+## Command Surfaces
+
+- `new-task`, `status`, `inspect`, `doctor`
+- `dag run-task`, `dag validate`, `run-dag`, `dag report`, `dag resume`
+- `delegate`, `harvest`, `promote-run`, `closeout`
+- `loop init`, `loop run`, `loop status`, `loop closeout`
+- `pi-prompt`, `cursor-prompt`
+- `docs audit`, `handoff check`, `spine audit`, `knowledge curate`
+
+## Verification Preset
+
+The shell preset `loop-agent-standard-verify` runs typecheck and focused DAG tests. Full delivery should still use:
+
+```bash
+bash scripts/ci.sh
+```

package/docs/progress/README.md

@@ -0,0 +1,3 @@
+# Progress Logs
+
+Use this directory for concise handoff logs that should survive chat context.

package/docs/reports/README.md

@@ -0,0 +1,3 @@
+# Reports
+
+Use this directory for verification, audit, benchmark, and closeout reports.

package/docs/templates/adr.md

@@ -0,0 +1,60 @@
+# ADR 模板
+
+## 标题
+
+> 建议文件名：`0001-<topic>.md`
+
+## 状态
+
+- proposed / accepted / superseded
+
+## 背景
+
+- 当前遇到的工程或架构问题是什么？
+- 为什么现在必须做决定？
+- 相关上下文、历史方案、约束有哪些？
+
+## 决策
+
+- 最终选择什么方案？
+- 明确边界、适用范围、默认行为是什么？
+
+## 备选方案
+
+1. 方案 A：
+2. 方案 B：
+3. 方案 C：
+
+## 取舍理由
+
+- 为什么选择当前方案？
+- 为什么不选其他方案？
+- 主要 trade-off 是什么？
+
+## 影响范围
+
+- 影响的代码目录：
+- 影响的文档/契约：
+- 影响的测试/脚本：
+- 影响的开发流程/harness：
+
+## 后果
+
+### 正面后果
+
+- 
+
+### 负面后果 / 成本
+
+- 
+
+## 验证与落地
+
+- 需要补哪些实现、脚本或测试：
+- 如何验证决策已经生效：
+
+## 复审条件
+
+当出现以下情况时，建议重新审视本 ADR：
+
+-