@tea-agent/loop-agent 0.1.0 → 0.2.1

package/docs/architecture/runtime-boundaries.md

@@ -0,0 +1,147 @@
+# Runtime Boundaries
+
+本文定义 loop-agent 各 runtime 层的 module interface、允许的依赖方向，以及治理检查 hook。目标是把「命令、文档、import 架构」从多处维护收敛为可机器校验的边界契约，而不在本阶段改变 runtime 行为。
+
+## 分层概览
+
+```text
+Skill layer
+  └─ 入口策略、reference 路由、硬规则（skills/loop-agent/SKILL.md + references/）
+
+CLI layer (src/cli/)
+  └─ argv 解析、adapter 解析、调用 application / command handler、格式化输出
+
+Application layer (src/application/，逐步引入)
+  └─ 一次用户意图的 typed use-case interface，供 CLI、Loop、Workflow 复用
+
+Workflow runtime (src/workflows/)
+  └─ DAG / Dynamic / Loop 核心执行规则；不应依赖 commands
+
+Executors (src/executors/)
+  └─ Cursor / Pi / Shell 等外部工具适配；不应依赖 commands 或 CLI formatting
+
+Infrastructure / Store (src/infrastructure/，逐步引入)
+  └─ .harness 文件系统副作用、run lifecycle、原子写入规则
+
+Governance (scripts/check-*.sh, src/governance/)
+  └─ 防止 command registry、skill entry、import architecture 漂移
+```
+
+## 各层职责
+
+### Skill layer
+
+- **位置**：`skills/loop-agent/SKILL.md` 及 `skills/loop-agent/references/**`
+- **职责**：定义 agent 何时启用 loop-agent、默认执行路径（Agent DAG）、硬规则与 reference 路由；不承载完整操作手册。
+- **禁止**：在入口 skill 中重复维护 CLI command 列表或与 `src/cli/catalog.ts` 冲突的事实源。
+
+### CLI layer
+
+- **位置**：`src/cli.ts`、`src/cli/**`
+- **职责**：解析全局 flag（如 `--repo-root`）、解析 top-level / subcommand、调用 command handler、输出 help / JSON / Markdown。
+- **允许依赖**：`src/commands/**`（handler wiring）、`src/adapters/**`、`src/shared/**`、逐步引入的 `src/application/**`。
+- **禁止**：在 router 中维护与 catalog 独立的 command 事实源（Phase 1 整改目标）。
+
+### Application layer
+
+- **位置**：`src/application/**`（按计划逐步引入）
+- **职责**：封装一次用户意图的 typed result（如 validate DAG、run DAG、report），供 CLI 与 workflow runtime 共用。
+- **允许依赖**：`src/workflows/**`、`src/infrastructure/**`、`src/task/**`、`src/records/**`。
+- **禁止**：直接承担 CLI formatting 或 argv 解析。
+
+### Workflow runtime
+
+- **位置**：`src/workflows/dag/**`、`src/workflows/dynamic/**`、`src/workflows/loop/**`
+- **职责**：DAG spec 校验与执行、dynamic workflow 编译与 expansion、Loop 状态机与 action 编排。
+- **允许依赖**：`src/executors/**`、`src/task/**`、`src/records/**`、`src/shared/**`、application use-case（目标态）。
+- **禁止**：`import` 来自 `src/commands/**`（见下方过渡例外）。
+
+### Executors
+
+- **位置**：`src/executors/**`
+- **职责**：封装 Cursor SDK/CLI、Pi SDK/CLI、shell 执行与 write guard。
+- **允许依赖**：`src/shared/**`、外部 SDK。
+- **禁止**：依赖 `src/commands/**` 或 CLI 输出格式。
+
+### Infrastructure / Store
+
+- **位置**：`src/infrastructure/harness/**`（按计划逐步引入）；过渡期部分逻辑仍在 `src/workflows/dag/lifecycle.ts`、`src/records/**`。
+- **职责**：`.harness/tasks`、`.harness/dag-runs`、`.harness/runs`、loop state 的集中读写；completed run facts 只读约束。
+- **禁止**：把 raw path mutation 扩散给 runner、loop action 或 command handler。
+
+### Governance
+
+- **位置**：`scripts/check-repo.sh` 及子脚本、`src/governance/**`、相关 Vitest。
+- **职责**：在 CI / in-flight DAG 中检测文档链接、exec plan 状态、架构 import、command registry 漂移、skill entry 完整性。
+
+## 允许的依赖方向
+
+```text
+Skill (docs)          ──advisory──>  CLI catalog / command-reference（人类可读，机器 drift check）
+
+CLI                   ──────────>   Application (目标态)
+CLI                   ──────────>   Commands (handler 薄层)
+Commands              ──────────>   Application / Workflows / Infrastructure
+
+Workflow runtime      ──────────>   Executors / Task / Records / Application (目标态)
+Workflow runtime      ──X──>        Commands  （目标态禁止；见过渡例外）
+
+Executors             ──────────>   Shared / 外部 SDK
+Executors             ──X──>        Commands / CLI
+
+Application           ──────────>   Workflows / Infrastructure / Task / Records
+Application           ──X──>        CLI formatting
+
+Infrastructure        ──────────>   Shared / node:fs
+Runner / Loop         ──(迁移中)──>  逐步改为仅经 Store / Application
+```
+
+**规则摘要**
+
+| From | May import | Must not import |
+|------|------------|-----------------|
+| `src/commands/**` | application, workflows, infrastructure, task, records, executors, shared | — |
+| `src/workflows/**` | executors, task, records, shared, application（目标） | `src/commands/**` |
+| `src/executors/**` | shared, 外部 SDK | `src/commands/**`, `src/cli/**` |
+| `src/cli/**` | commands, adapters, shared, application（目标） | — |
+| `skills/**` | （Markdown 引用，非 TS import） | 运行时 TS 模块 |
+
+## 已知过渡耦合
+
+当前没有允许的 `src/workflows/**` 或 `src/executors/**` → `src/commands/**` TypeScript import。
+
+`scripts/check-architecture-boundaries.sh` 的 transitional allowlist 保持为空。任何新增的 `workflows/executors -> commands` import 必须导致检查 **exit 1**；如果未来确有临时例外，必须先写入 active exec plan，说明移除时间和验证门禁。
+
+## Governance 钩子
+
+以下脚本由 `scripts/check-repo.sh` 调用（Phase 0 起）：
+
+| Script | 检查内容 | 失败条件 |
+|--------|----------|----------|
+| `scripts/check-architecture-boundaries.sh` | `workflows` / `executors` → `commands` import | 新的未 allowlist violation |
+| `scripts/check-command-registry-drift.sh` | `command-reference.md` 中的 top-level command vs `src/cli/catalog.ts` | 文档引用未注册 command |
+| `scripts/check-skill-entry.sh` | `SKILL.md` reference 文件存在、行数阈值 | reference 缺失（fail）；行数 > 220（warn） |
+
+相关 exec plan：`docs/exec-plans/active/2026-07-04-runtime-boundary-remediation.md`。
+
+### 验证命令
+
+```bash
+bash scripts/check-repo.sh
+bash scripts/check-architecture-boundaries.sh
+bash scripts/check-command-registry-drift.sh
+bash scripts/check-skill-entry.sh
+```
+
+Runtime 变更另需 `npm run typecheck` 及对应 targeted Vitest（见 exec plan 各 Phase 验证关口）。
+
+## 演进里程碑
+
+| Phase | 边界变化 |
+|-------|----------|
+| 0（当前） | 文档 + 机器 guard；已知 loop/actions.ts 耦合 advisory |
+| 1 | CLI command definition 单源 |
+| 2 | Skill entry 瘦身 + frontmatter references |
+| 3 | DAG application use-case；Loop 开始脱离 command JSON |
+| 6 | `workflows → commands` import check 已从 advisory 改为 **fail** |
+| 7 | Harness Store / Repository 集中 `.harness` 副作用 |

package/docs/cursor-executor-usage.md

@@ -1,8 +1,8 @@
-# Cursor Executor Usage
+# Cursor Executor 用法
 
-Cursor is used for bounded write implementation. Every Cursor write task must define scope explicitly.
+Cursor 用于有界写实现。每个 Cursor 写任务必须显式定义 scope。
 
-## Required Prompt Fields
+## Prompt 必填字段
 
 - task id
 - objective
@@ -10,7 +10,7 @@ Cursor is used for bounded write implementation. Every Cursor write task must de
 - forbidden paths
 - constraints
 - expected verification
-- instruction to preserve unrelated changes
+- 保留无关变更的指令
 
 ## One-Shot Helper
 
@@ -22,4 +22,4 @@ loop-agent cursor-prompt \
   "<bounded task prompt>"
 ```
 
-After Cursor returns, the main session must inspect the diff and run the relevant verification commands.
+Cursor 返回后，主会话必须检查 diff 并运行相关验证命令。

package/docs/decisions/README.md

@@ -1,3 +1,3 @@
-# Decisions
+# 决策
 
-Use this directory for architecture decision records.
+本目录存放架构决策记录（ADR）。

package/docs/design/README.md

@@ -1,36 +1,36 @@
-# Design Notes
+# 设计笔记
 
-`docs/design/` contains planning notes for using `loop-agent` as the repo-local runtime inside a larger product-line agent platform. These documents are design inputs, not proof that the capability already exists in `src/`.
+`docs/design/` 存放将 `loop-agent` 作为更大产品线 agent 平台内仓库本地 runtime 的规划笔记。这些是设计输入，不是 `src/` 已具备该能力的证明。
 
-## Documents
+## 文档
 
-| Document | Purpose |
+| 文档 | 用途 |
 |---|---|
-| `产品线共享知识库.md` | Product-line docs repository as the upstream source of truth |
-| `研发模式.md` | 10-working-day Feature team workflow |
-| `1个月规划.md` | First-month landing plan |
-| `1月wbs.md` | First-month WBS and ownership |
-| `六个月规划.md` | Six-month roadmap and target architecture |
-| `taskspec-to-loop-agent-mapping.md` | Contract for adapting product-line TaskSpec into `loop-agent` tasks |
-| `state-and-failure-taxonomy.md` | Canonical status and failure taxonomy across docs, Task Pool, DAG, and Loop |
+| `产品线共享知识库.md` | 产品线文档仓库作为上游事实源 |
+| `研发模式.md` | 10 个工作日 Feature 团队工作流 |
+| `1个月规划.md` | 首月落地计划 |
+| `1月wbs.md` | 首月 WBS 与分工 |
+| `六个月规划.md` | 六个月路线图与目标架构 |
+| `taskspec-to-loop-agent-mapping.md` | 将产品线 TaskSpec 适配为 `loop-agent` task 的契约 |
+| `state-and-failure-taxonomy.md` | 文档、Task Pool、DAG、Loop 共用的 canonical status 与 failure taxonomy |
 
-## Current Implementation Boundary
+## 当前实现边界
 
-`loop-agent` currently owns a repo-local harness, Agent DAG generation/validation/execution, shell verification, artifacts, reports, and Loop state. It is not the product-line Task Pool, Orchestrator, docs-sync service, Git/CI platform, or artifact store.
+`loop-agent` 当前拥有：仓库本地 harness、Agent DAG 生成/验证/执行、shell 验证、artifacts、reports、Loop state。它不是产品线 Task Pool、Orchestrator、docs-sync 服务、Git/CI 平台或 artifact store。
 
-The design documents use two kinds of profile names:
+设计文档使用两类 profile 名称：
 
-- Business task profiles: `backend-feature`, `frontend-feature`, `qa-casegen`, `qa-testcode`, `reviewer-gate`.
-- `loop-agent dag run-task --profile` governance profiles: `auto`, `minimal`, `standard`, `reviewed`, `supervised`.
+- **Business task profiles**：`backend-feature`、`frontend-feature`、`qa-casegen`、`qa-testcode`、`reviewer-gate`
+- **`loop-agent dag run-task --profile` governance profiles**：`auto`、`minimal`、`standard`、`reviewed`、`supervised`
 
-Do not pass business task profiles directly to `loop-agent dag run-task --profile` unless the CLI is explicitly extended to support them. Use `taskspec-to-loop-agent-mapping.md` to route business profiles to current governance profiles.
+除非 CLI 显式扩展支持，否则不要把 business task profile 直接传给 `loop-agent dag run-task --profile`。用 `taskspec-to-loop-agent-mapping.md` 将 business profile 路由到当前 governance profile。
 
-## Maintenance Rules
+## 维护规则
 
-When these design notes change:
+设计笔记变更时：
 
-1. Keep TaskSpec fields, status names, failure categories, and command examples consistent with the contract docs.
-2. Mark future platform components as target architecture unless they exist in `src/` or `scripts/`.
-3. Update `taskspec-to-loop-agent-mapping.md` whenever `src/task/config-types.ts` or DAG profile routing changes.
-4. Update `state-and-failure-taxonomy.md` whenever DAG report categories, Loop failure classes, or Task Pool states change.
-5. Run `bash scripts/check-repo.sh`.
+1. 保持 TaskSpec 字段、status 名称、failure category 与命令示例与契约文档一致
+2. 未来平台组件标为目标架构，除非已存在于 `src/` 或 `scripts/`
+3. `src/task/config-types.ts` 或 DAG profile routing 变更时更新 `taskspec-to-loop-agent-mapping.md`
+4. DAG report category、Loop failure class 或 Task Pool state 变更时更新 `state-and-failure-taxonomy.md`
+5. 运行 `bash scripts/check-repo.sh`

package/docs/development-principles.md

@@ -1,71 +1,71 @@
-# Development Principles
+# 开发原则
 
-loop-agent is a workflow runtime for agentic coding work. The repository should stay small, explicit, and verifiable.
+loop-agent 是面向 agentic coding 的工作流 runtime。仓库应保持小而显式、可验证。
 
-## Operating Stance
+## 操作立场
 
-The project uses a human-led, agent-executed engineering model. Agents may implement, verify, and summarize, but durable intent and completion evidence must live in the repository.
+项目采用「人类掌舵、智能体执行」的工程模型。Agent 可实现、验证与总结，但持久意图与完成证据必须落在仓库中。
 
-- The repository is the record system. Decisions, contracts, plans, tests, reports, and handoffs belong in tracked files.
-- `AGENTS.md` is an operating map, not a knowledge dump. Long-lived methodology and decisions belong under `docs/`.
-- Work advances in small, reversible, verifiable increments.
-- Baseline verification comes before new work when the current state is uncertain.
-- Completion is defined by fresh evidence, not by intent or confidence.
+- 仓库是记录系统。决策、契约、计划、测试、报告与交接属于 tracked files。
+- `AGENTS.md` 是操作地图，不是知识 dump。长期方法论与决策属于 `docs/`。
+- 工作以小步、可逆、可验证的增量推进。
+- 状态不确定时，先跑基线验证再开新工。
+- 完成由新鲜证据定义，而非意图或信心。
 
-## Principles
+## 原则
 
-1. One task advances one bounded work block.
-2. Search existing code, docs, scripts, and tests before designing new behavior.
-3. Shell verification is the completion authority.
-4. Runtime state belongs in `.harness/`; durable decisions belong in `docs/`.
-5. Pi writer nodes and optional Cursor write execution must be bounded by explicit allowed and forbidden paths.
-6. Pi review/planning paths are advisory unless followed by deterministic verification.
-7. Repeated constraints should become docs, tests, scripts, checks, or templates.
-8. Do not keep hidden process state only in chat.
-9. Do not add placeholders as completed implementation.
-10. Prefer existing local patterns before adding new abstractions.
+1. 一次任务只推进一个有边界的工作块。
+2. 设计新行为前先搜索现有代码、文档、脚本与测试。
+3. Shell 验证是完成权威。
+4. Runtime 状态在 `.harness/`；持久决策在 `docs/`。
+5. Pi writer 节点与可选 Cursor 写执行必须由显式 allowed/forbidden paths 约束。
+6. Pi review/planning 路径是 advisory，除非后跟确定性验证。
+7. 反复出现的约束应固化为文档、测试、脚本、检查或模板。
+8. 不要把隐藏流程状态只留在聊天里。
+9. 不要把占位实现当作已完成交付。
+10. 新增抽象前先沿用现有局部模式。
 
-## Repository Shape
+## 仓库结构
 
-- Source lives in `src/`.
-- Tests live in `test/`.
-- Skill instructions live in `skills/`.
-- Verification and maintenance scripts live in `scripts/`.
-- Governance and handoff artifacts live in `docs/`.
+- 源码：`src/`
+- 测试：`test/`
+- Skill 指令：`skills/`
+- 验证与维护脚本：`scripts/`
+- 治理与交接产物：`docs/`
 
-## Change Discipline
+## 变更纪律
 
-For behavior changes, update tests. For workflow or command changes, update docs and examples. For governance changes, update `harness.json` and the relevant check scripts.
+行为变更要更新测试；工作流或命令变更要更新文档与示例；治理变更要更新 `harness.json` 与相关检查脚本。
 
-When work affects requirements, behavior, cross-command contracts, or harness rules, update the corresponding durable artifact:
+当工作影响需求、行为、跨命令契约或 harness 规则时，更新对应持久产物：
 
-- design or contract docs for changed expectations
-- tests or verification scripts for changed behavior
-- progress logs or reports for non-trivial handoff evidence
-- ADRs for architecture or public contract decisions
-- templates when a repeated process becomes reusable
+- 设计/契约文档 — 变更后的预期
+- 测试或验证脚本 — 变更后的行为
+- progress log 或 report — 非平凡交接证据
+- ADR — 架构或公开契约决策
+- 模板 — 重复流程可复用时
 
-Do not mix unrelated refactors, new features, and broad documentation migration in one work block unless the contract explicitly says why they must move together.
+除非 contract 明确说明必须一起移动，否则不要在一个工作块里混合无关重构、新功能与大规模文档迁移。
 
-## Search And Reuse
+## 搜索与复用
 
-Before implementing, inspect the existing system:
+实现前先检视现有系统：
 
-- Use CodeGraph first when the repository is indexed and the task needs code understanding.
-- Use `rg` for text search and `fd` for file discovery when available.
-- Read nearby tests and helpers before introducing new helpers.
-- Prefer structured parsers and existing local APIs over ad hoc string manipulation.
+- 仓库已索引且任务需要理解代码时，优先用 CodeGraph。
+- 可用时用 `rg` 做文本搜索、`fd` 找文件。
+- 引入新 helper 前先读邻近测试与 helper。
+- 优先结构化 parser 与现有本地 API，避免 ad hoc 字符串处理。
 
-Assume the system may already contain a partial solution until search proves otherwise.
+在搜索证明否则之前，假设系统可能已有部分解法。
 
-## Completion Discipline
+## 完成纪律
 
-A completion claim must answer:
+完成声明必须回答：
 
-- what changed
-- why this approach was chosen
-- which command verified it and what the result was
-- whether contracts, docs, tests, or scripts were affected
-- what risk or follow-up remains
+- 改了什么
+- 为何选此方案
+- 哪条命令验证、结果如何
+- 是否影响契约、文档、测试或脚本
+- 剩余风险或后续项
 
-If verification fails, report the failing command and observed state instead of softening the completion definition.
+验证失败时，报告失败命令与观察到的状态，而不是软化完成定义。

package/docs/dynamic-workflow-dag-engine-roadmap.md

@@ -147,11 +147,11 @@ LLM / profile 生成 WorkflowSpec JSON
 
 本次复核依据的关键代码与文档：
 
-- `docs/feature-workflow.md`
-- 源码仓库历史 completed execution plan: remove-level1-fallback
-- `src/workflows/dag/types.ts`
-- `src/workflows/dag/validate.ts`
-- `src/workflows/dag/runner.ts`
+- `docs/feature-workflow.md`
+- 源码仓库历史 completed execution plan: remove-level1-fallback
+- `src/workflows/dag/types.ts`
+- `src/workflows/dag/validate.ts`
+- `src/workflows/dag/runner.ts`
 - `src/workflows/dag/lifecycle.ts`
 - `src/workflows/dag/report.ts`
 - `src/workflows/dag/init-hybrid.ts`
@@ -1744,6 +1744,6 @@ https://code.claude.com/docs/en/workflows
 
 [3] 用户上传文档：`2026-07-02-repository-analysis.md`，关于当前 `loop-agent` 仓库结构、DAG 主路径、Loop 语义、治理边界与健康度的分析报告。
 
-[4] 当前源码仓库历史 completed execution plan，关于删除 Level 1 fallback、抽取 shell verification、建立 DAG-oriented task read model 的完成记录；发布包只携带 execution plan 目录说明，不携带具体历史计划正文。
+[4] 当前源码仓库历史 completed execution plan，关于删除 Level 1 fallback、抽取 shell verification、建立 DAG-oriented task read model 的完成记录；发布包只携带 execution plan 目录说明，不携带具体历史计划正文。
 
 [5] 当前源码复核：`src/workflows/dag/types.ts`、`src/workflows/dag/validate.ts`、`src/workflows/dag/runner.ts`、`src/workflows/loop/actions.ts`、`src/task/read-model.ts`、`src/cli/catalog.ts`。

package/docs/exec-plans/README.md

@@ -1,6 +1,6 @@
-# Execution Plans
+# 执行计划
 
-- `active/README.md` lists currently active plans.
-- `completed/README.md` lists completed plans.
+- `active/README.md` — 当前进行中的计划
+- `completed/README.md` — 已完成的计划
 
-Use an execution plan for changes that affect multiple files, public command behavior, or repository governance.
+影响多文件、公开命令行为或仓库治理的变更应使用 execution plan。

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

@@ -1,5 +1,10 @@
-# 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.
+# 进行中的执行计划
+
+本目录存放当前进行中的 execution plan。
+
+源码仓库可在本 README 旁保留具体 active plan 文件。npm 包只携带本 README 作为目录契约，不复制 loop-agent 源码历史的 active plan；目标仓库自行生成 active plan。
+
+当前 active plan：
+
+- [2026-07-04-dag-role-skill-alignment.md](2026-07-04-dag-role-skill-alignment.md)
+- [2026-07-06-production-readiness-hardening.md](2026-07-06-production-readiness-hardening.md)

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

@@ -1,5 +1,9 @@
-# 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.
+# 已完成的执行计划
+
+实现与验证结束后，已完成计划移入此目录。
+
+npm 包携带本 README 作为目录契约。具体 completed plan 属于目标仓库历史，不从 loop-agent 源码历史复制。
+
+- [`2026-07-02-loop-agent-subject-restructure.md`](2026-07-02-loop-agent-subject-restructure.md) — 将原 `tools/code-agent` runtime 提升到仓库根、重命名为 `loop-agent`，移除旧 memory plugin 产品线
+- [`2026-07-04-remove-level1-fallback.md`](2026-07-04-remove-level1-fallback.md) — 移除历史顺序 Level 1 fallback，runtime、文档与 command surface 收敛到 DAG 执行
+- [`2026-07-04-runtime-boundary-remediation.md`](2026-07-04-runtime-boundary-remediation.md) — 整合 CLI/skill/runtime 边界，抽出 DAG/Loop runtime seam，集中 harness store/guard 策略