@tea-agent/loop-agent 0.2.0 → 0.2.1

package/docs/harness-methodology-verification.md

@@ -1,27 +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.
+1. 确定能证明声明的命令
+2. 完整运行该命令
+3. 读输出与 exit code
+4. 修失败或报告确切失败状态
+5. 然后再声明结果
 
-## 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` |
+| 治理有效 | `bash scripts/check-repo.sh` |
+| TypeScript 编译通过 | `npm run typecheck` |
+| 行为有覆盖 | `npm test` |
+| 完整本地交付有效 | `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

@@ -1,41 +1,41 @@
 # 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:
+loop-agent 提供结构化 agent 工作的本地 harness。
+
+## Runtime 区域
+
+- `.harness/tasks/` — task source、约束、state、loop facts
+- `.harness/dag-runs/` — DAG run state 与 artifacts
+- `.harness/runs/` — one-shot tool run 证据
+- `.harness/cache/` — 本地 runtime 缓存
+- `.harness/live/` — 瞬态 live-session 文件
+
+## Skill 指令
+
+- `skills/loop-agent/` — loop-agent 仓库自有的 skill 指令与参考资料
+- `skills/<skill-name>/` — DAG 模板引用的 skill 本地副本，含 supervised implementation 角色
+- 历史 `skill/` 不再是必需仓库路径；runtime 查找仅为 `loop-agent` 保留兼容 fallback
+
+## Package 资产
+
+npm 包包含运行与说明 harness 所需的静态能力资产：`bin/`、`dist/`、`skills/`、顶层 `docs/*.md`、`docs/templates/`、`examples/`、`harness.json`、`AGENTS.md`、`README.md`、`CHANGELOG.md`。
+
+生成或历史的 task facts 不是 package 资产。`docs/progress/`、`docs/reports/`、`docs/exec-plans/`、`docs/decisions/` 下现有文件属于目标仓库历史；包只携带这些目录的 README。
+
+从 npm 安装 `loop-agent` 并在其他项目使用时，DAG skill 指令按配置、用户或目标本地 skill 目录解析（若存在），再回退到包内 `skills/`。目标项目可添加本地 skills，但不必复制 loop-agent 源码历史或 `skills/` 目录即可使用默认 DAG 工作流。
+
+## Command Surface
+
+- `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`
+
+## 验证 Preset
+
+Shell preset `loop-agent-standard-verify` 跑 typecheck 与聚焦 DAG 测试。完整交付仍应使用：
 
 ```bash
 bash scripts/ci.sh

package/docs/production-readiness.md

@@ -0,0 +1,96 @@
+# Production Readiness v0.1
+
+本文档冻结 2026-07-06 至 2026-07-12 hardening sprint 的单任务 production readiness 标准。
+
+`loop-agent` production readiness v0.1 指：低/中风险的仓库本地 DAG 任务能以稳定、可解释、可验证、可恢复的方式运行。这不是组织级平台 readiness 声明。
+
+## 支持范围
+
+- 单仓库
+- 单任务或小范围有边界任务
+- 低/中风险的代码与文档变更
+- 显式 task source
+- 显式 `allowedPaths`、`forbiddenPaths`、`writeSet`
+- shell 验证命令
+- 通过 `dag report`、`dag doctor`、`promote-run`、`closeout` 交接
+
+## 非目标
+
+- 自动 merge
+- 自动 release
+- 生产 secrets
+- 生产数据库访问
+- 高风险 migration
+- 在线 Worker Pool
+- 多仓库 feature 编排
+- 可写的 Dynamic Workflow sharded migration
+- DAG runtime 之外的第二套 runner
+
+## 必需证据
+
+每个 production-ready v0.1 任务必须保留或产出以下证据：
+
+| 证据 | 要求 |
+|---|---|
+| DAG spec path | 生成的 DAG JSON 路径记录在 CLI 输出、report 或 task artifacts 中 |
+| DAG validation result | `dag validate --strict-models --strict-governance` 有新鲜输出 |
+| Run id | `run-dag` 打印或记录 run id |
+| Shell verification output | 完成声明引用新鲜命令输出，而非 model 自报 |
+| Failure category | 失败 run 在可用时具备 raw、normalized、product-line 与 recommended follow-up 字段 |
+| Closeout 或 failure handoff | 成功 run 可 promote 并 closeout；失败 run 产出 failure handoff 证据而非成功 closeout |
+
+## 必需命令
+
+标准任务路径：
+
+```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 .
+loop-agent dag report --run-id <run-id> --markdown
+loop-agent dag doctor --run-id <run-id>
+loop-agent promote-run <task-id> --run-id <run-id>
+loop-agent closeout task <task-id>
+```
+
+`<temp-dir>` 使用平台原生临时目录。
+
+## 必需标准
+
+| ID | 标准 | 验收 |
+|---|---|---|
+| PRD-01 | 新任务仅推荐 DAG 路径 | README、docs、website、skills 不把已移除的 Level 1 顺序命令当作 fallback |
+| PRD-02 | 写任务有显式边界 | strict DAG governance 在需要时拒绝缺失 `allowedPaths`、`forbiddenPaths` 或 `writeSet` |
+| PRD-03 | 每次 DAG run 有可读 report | `loop-agent dag report --latest --markdown` 显示 status、failure summary 与 next step |
+| PRD-04 | 失败 run 可诊断 | `loop-agent dag doctor` 报告 category 与 recommended follow-up |
+| PRD-05 | Shell 验证是完成权威 | closeout 不接受 model 自报替代新鲜命令输出 |
+| PRD-06 | Failure category 覆盖失败 fixture | validation、write guard、shell、timeout、auth、unknown fixture 均有映射 |
+| PRD-07 | 已完成 DAG facts 不可变 | completed facts guard 仍由测试覆盖 |
+| PRD-08 | CLI 主路径输出指引下一步 | `dag run-task`、`dag validate`、`run-dag`、`dag report` 打印 operator next commands |
+| PRD-09 | 文档面一致 | doc 更新后 `bash scripts/check-repo.sh` 与 `npm run docs:build` 通过 |
+| PRD-10 | sprint 完成前完整本地门禁通过 | 最终 hardening closeout 时 `bash scripts/ci.sh` 通过 |
+
+## Failure Routing
+
+Failure category 是路由字段，不是主任务状态。保留 raw DAG facts，仅在 report、doctor 输出、closeout draft、task artifacts 或后续 Task Pool 记录中追加派生字段。
+
+四层结构：
+
+```text
+raw_failure_category
+dag_normalized_failure_category
+product_line_failure_category
+recommended_follow_up
+```
+
+Product-line category 事实源：`docs/design/state-and-failure-taxonomy.md`。
+
+## Sprint Gate
+
+2026-07-06 sprint 仅在 active execution plan 记录以下内容时视为完成：
+
+- M1–M4 最终状态
+- 必需验证门禁的命令输出
+- 成功、write-guard、shell-failure 场景的 dogfood 证据
+- 剩余风险与后续工作

package/docs/progress/README.md

@@ -1,3 +1,3 @@
-# Progress Logs
+# 进度日志
 
-Use this directory for concise handoff logs that should survive chat context.
+本目录存放应超越聊天上下文的简洁 handoff 日志。

package/docs/reports/README.md

@@ -1,3 +1,5 @@
-# Reports
+# 报告
 
-Use this directory for verification, audit, benchmark, and closeout reports.
+本目录存放验证、审计、benchmark 与 closeout 报告。
+
+- [`2026-07-12-production-readiness-hardening.md`](2026-07-12-production-readiness-hardening.md)

package/docs/templates/agent-dag-decision-gate-dogfood-report.md

@@ -8,7 +8,7 @@
 |---|---|
 | Date | YYYY-MM-DD |
 | Topic |  |
-| DAG input | `<temp-dir>/<topic>-decision-gate-dag.json` |
+| DAG input | `<temp-dir>/<topic>-decision-gate-dag.json` |
 | Run ID |  |
 | Run facts | `.harness/dag-runs/completed/<run-id>/` |
 | Gate type | `acceptance-gate` |

package/docs/templates/agent-dag-process-supervisor.prompt.md

@@ -11,7 +11,7 @@ Do **not** create `executor: supervisor`. Supervisor is a **role** on `executor:
 ```json
 {
   "id": "process-supervisor-pi",
-  "depends_on": ["soft-verify-shell", "implement-pi"],
+  "depends_on": ["soft-verify-shell", "implement-pi"],
   "complexity": "HIGH",
   "executor": "pi",
   "role": "supervisor",
@@ -80,7 +80,7 @@ Rules:
 
 - `verdict` must match the first line.
 - `failureClass` must be one of `syntax`, `runtime`, `logic`, `boundary`, `environment`, `governance`, `unknown`.
-- For `request-revision`, `fixScope` must name the smallest repair paths/components and stay inside the downstream `repair-pi` writeSet/allowedPaths.
+- For `request-revision`, `fixScope` must name the smallest repair paths/components and stay inside the downstream `repair-pi` writeSet/allowedPaths.
 - For `pass`, `fixScope` must be an empty array.
 - `invariant` must state the behavior or contract the repair must preserve.
 - `evidenceRefs` must name node ids or relative artifact paths consulted.

package/docs/templates/agent-dag-report.schema.json

@@ -58,6 +58,21 @@
         "commandHint": { "type": "string" }
       }
     },
+    "dagProductLineFailureCategory": {
+      "type": "string",
+      "enum": [
+        "SpecUnclear",
+        "ContractMismatch",
+        "ProductBug",
+        "TestBug",
+        "EnvFailure",
+        "FlakyTest",
+        "RiskyChange",
+        "DependencyFailure",
+        "NeedsHuman",
+        "Unknown"
+      ]
+    },
     "dagReportPrimaryFailure": {
       "type": "object",
       "additionalProperties": false,
@@ -87,7 +102,11 @@
             "skipped",
             "unknown"
           ]
-        }
+        },
+        "productLineFailureCategory": {
+          "$ref": "#/$defs/dagProductLineFailureCategory"
+        },
+        "recommendedFollowUp": { "type": "string" }
       }
     },
     "dagReportPrimaryRecovery": {
@@ -117,7 +136,11 @@
             "skipped",
             "unknown"
           ]
-        }
+        },
+        "productLineFailureCategory": {
+          "$ref": "#/$defs/dagProductLineFailureCategory"
+        },
+        "recommendedFollowUp": { "type": "string" }
       }
     },
     "dagNodeDecisionEnvelope": {
@@ -333,6 +356,10 @@
             "unknown"
           ]
         },
+        "productLineFailureCategory": {
+          "$ref": "#/$defs/dagProductLineFailureCategory"
+        },
+        "recommendedFollowUp": { "type": "string" },
         "recoveryRecommendation": {
           "$ref": "#/$defs/dagRecoveryRecommendation"
         },
@@ -400,6 +427,10 @@
             "unknown"
           ]
         },
+        "productLineFailureCategory": {
+          "$ref": "#/$defs/dagProductLineFailureCategory"
+        },
+        "recommendedFollowUp": { "type": "string" },
         "recoveryRecommendation": {
           "$ref": "#/$defs/dagRecoveryRecommendation"
         },

package/docs/templates/agent-dag-review-verdict.prompt.md

@@ -9,7 +9,7 @@ Use this prompt for a read-only **review verdict** node after hard verification:
 ```json
 {
   "id": "review-pi",
-  "depends_on": ["hard-verify-shell", "repair-pi"],
+  "depends_on": ["hard-verify-shell", "repair-pi"],
   "complexity": "HIGH",
   "executor": "pi",
   "role": "reviewer",