@tea-agent/loop-agent 0.14.0 → 0.15.0

package/skills/frontend-verification/references/verification-checklist.md

@@ -2,26 +2,19 @@
 
 ## Static And Behavior Evidence
 
-- Type/compile, lint/format, build, and schema/client checks ran when required.
-- Generated output was authorized.
-- Tests cover changed logic/flows and regressions.
-- Browser/e2e/manual evidence exists when explicitly required.
-- Selected-strategy behavior and applicable loading, empty, error, success, disabled,
-  permission, retry, and boundary states have evidence from fixed DAG entrypoints.
-- When generated, Mock-specific verification checks service/handler/schema/fixtures;
-  behavior evidence separately proves page consumption.
-- For Mock strategies, activation is explicit/non-production and a production/default-
-  real-path build with Mock off confirms the real request remains default.
-- `not-needed` has positive readiness/no-remote evidence plus applicable real or
-  no-remote behavior evidence. Mock-backed evidence remains frontend-only and never
-  satisfies real API integration.
+- Required type/compile, lint/format, build, schema/client, browser/e2e/manual checks ran.
+- Generated output was authorized; tests cover changed logic, flows, and regressions.
+- Fixed DAG entrypoints prove selected-strategy behavior and applicable loading/empty/error/success/disabled/permission/retry/boundary states.
+- Mock-specific checks cover service/handler/schema/fixtures; behavior evidence separately proves page consumption.
+- Mock activation is explicit/non-production; a default-real-path build with Mock off proves the real request remains default.
+- `not-needed` has real/no-remote evidence, or default-auto skipped-Mock rationale with Real Integration Gap preserved when no project Mock capability exists.
+- Mock-backed evidence is frontend-only and never satisfies real API integration.
 
 ## Design And Component Evidence
 
 - Claims cite knowledge-base retrieval or `<repoRoot>/openSpec/**` fallback.
-- Evidence records query/source/version/time or fallback search terms, paths, headings, and applied rules.
-- Relevant `openSpec/` matches become the current-project specification and satisfy source availability; only the knowledge-base connection remains unavailable.
-- Missing both sources blocks explicit compliance or an unresolved required design decision.
+- Evidence records query/source/time or fallback search terms, paths, headings, and applied rules.
+- Relevant `openSpec/` matches satisfy source availability; missing both sources blocks explicit compliance or required design decisions.
 
 ## Status
 
@@ -35,12 +28,11 @@ Only passed satisfies a required check. Other optional statuses remain disclosed
 
 ## Closeout Checks
 
-- List exact commands, source, exit status, and archived output/artifact when available.
-- Map every criterion to evidence or a named gap.
+- List exact commands/source/exit status/artifacts; map every criterion to evidence or a named gap.
 - Record review verdict before completion.
 - Do not conflate static, behavior, browser/visual/manual, or knowledge-base proof.
-- If only mock evidence exists, report `Frontend status: mock-validated` and
-  `Real integration: pending`, with the actual API verification as follow-up.
+- If only Mock evidence exists, report `Frontend status: mock-validated` and `Real integration: pending`, with actual API verification follow-up.
+- If default `auto` skipped Mock and no real API evidence exists, report `Frontend status: locally-validated` and `Real integration: pending`.
 
 ```markdown
 ## Changes
@@ -64,5 +56,4 @@ Only passed satisfies a required check. Other optional statuses remain disclosed
 - None.
 ```
 
-If review is not pass or a required check is not passed, describe the task as
-incomplete and list concrete follow-up.
+If review is not pass or a required check is not passed, describe the task as incomplete and list concrete follow-up.

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

@@ -16,7 +16,7 @@
 
 对于默认 `standard` 任务，生成器根据标题、`source/需求.md` 和结构化 `allowedPaths` 做保守、确定性的需求分类。只有高置信的前端实现需求自动选择 `frontend-implementation` DAG；后端、前后端混合、明确排除前端或证据不足的需求继续使用 governance profile 选出的模板。分类不会把普通后端实现路由到 `backend-test`，也不会替换由显式 profile、`workflowPolicy` 或 supervised quality gate 选中的 supervised 模板。
 
-前端专用链在 `frontend-scout-pi` 后加入只读 `frontend-mock-assess-pi` 和确定性 contract gate，根据接口契约、后端就绪度、生成期能力 seed 与固化验证入口选择 `native|browser-intercept|request-adapter|not-needed|blocked`。策略直接传给 plan、两阶段 design review、唯一 writer、实现 review 和 closeout；真实请求保持默认，缺少契约、生产隔离或可执行验证时 gate 阻塞。可选 `frontendMock` 配置声明 `auto|required|disabled`、既有服务目录与专项命令；不安全或不完整的显式 required 合同只生成无 writer 的评估链，有可信命令时才增加 `frontend-mock-verify-shell`。Mock-backed 证据只证明前端状态；`not-needed` 需要真实或无远程接口行为证据。未调用后端时 closeout 报告 `Frontend status: mock-validated` 与 `Real integration: pending`。
+前端专用链在 `frontend-scout-pi` 后加入只读 `frontend-mock-assess-pi` 和确定性 contract gate，根据接口契约、后端就绪度、生成期能力 seed 与固化验证入口选择 `native|browser-intercept|request-adapter|not-needed|blocked`。策略直接传给 plan、两阶段 design review、唯一 writer、实现 review 和 closeout；真实请求保持默认，缺少契约、生产隔离、注释真实请求或显式 required 合同不完整时 gate 阻塞。可选 `frontendMock` 配置声明 `auto|required|disabled`、既有服务目录与专项命令；默认 `auto` 下没有已确认 Mock 能力时跳过 Mock 继续实现并保留真实联调缺口，不安全或不完整的显式 required 合同只生成无 writer 的评估链，有可信命令时才增加 `frontend-mock-verify-shell`。Mock-backed 证据只证明前端状态；跳过 Mock 且未调用后端时 closeout 报告 `Frontend status: locally-validated` 与 `Real integration: pending`。
 
 显式专用 `taskKind` 保持兼容并优先于任务源分类，也不扩充 governance profile：`frontend-implementation` 显式选择前端实现 DAG，`frontend-test` 选择 FE-test RAG DAG，`backend-test` 选择后端测试 DAG，`knowledge-sync` 选择 Feature 测试知识回写 DAG，`knowledge-graph-bootstrap` 选择业务知识图谱开荒/增量 DAG。后端测试链为 `analyze-inputs-pi → backend-test-analysis-contract-shell → backend-test-environment-scout-pi → backend-test-execution-contract-shell → generate-backend-functional-cases-pi → emit-backend-case-manifest-pi → backend-test-case-manifest-shell → review-backend-cases-pi → review-backend-cases-gate-shell → generate-backend-pytest-pi → backend-test-traceability-gate-shell → execute-backend-pytest-shell → parse-backend-test-result-shell → classify-backend-test-result-pi → test-retrospect-pi → backend-test-outcome-gate-shell`。analysis/execution/case-manifest gate 写入 run-owned contracts；parse materialize Backend Test Result v1（`contracts/backend-test-result.json`）。Case Manifest 确定性校验 AC→case 覆盖；traceability gate 校验 generated file/symbol。execute 在非空 JUnit 下将 pytest exit 0/1 视为节点成功以便 always-run retrospect；`backend-test-outcome-gate-shell` 以 result.outcome 收口；retrospect 使用 manifest coverageSummary + Result v1，不得自造 coverage%。`evidenceGaps`、未知 framework、secret 值、路径穿越或 preflight 失败时后续 writer/execute 不启动。`knowledge-sync` 链必须绑定 `featureId`；图谱运维公共入口是 `loop-agent knowledge query|graph-init|graph-materialize|graph-promote|graph-incremental-prepare`。治理等级仍由既有 `minimal|standard|reviewed|supervised` 规则推断。
 

package/docs/agent-dag-recovery-playbook.md

@@ -1,195 +0,0 @@
-# Agent DAG Recovery Playbook（恢复手册）
-
-> **关联**：[`agent-dag-runner.md`](agent-dag-runner.md)（CLI 与 run 语义）· [`templates/agent-dag-decision-gate.prompt.md`](templates/agent-dag-decision-gate.prompt.md)（Decision Gate 消费 recovery 证据）
-
-## 定位
-
-Agent DAG **recovery planning 是只读、派生、advisory** 的。`dag report` 与 `buildDagDecisionGateEvidence()` 从 `.harness/dag-runs/` 的 canonical facts 聚合 `normalizedFailureCategory` → `recoveryRecommendation`，供人工或 Decision Gate prompt 消费。
-
-中断后不要从上游摘要手工生成 impl-only DAG。先修复 `.harness/tasks/<task-id>/source/` 或计划，再对同一 task 重新执行 `dag run-task`、严格 `dag validate` 和新的 `run-dag`。新生成的完整 DAG 会重新冻结 `sourceBinding` 并经过 contract/scout/plan/gate；v3 孤立 writer 如果既无来源绑定、也无只读 planner 上游，会被 strict governance 拒绝。完整规则见 [`design/dag-source-binding-and-recovery.md`](design/dag-source-binding-and-recovery.md)。
-
-Production Readiness v0.1 在 normalized DAG category 之上增加 product-line routing。Report 与 doctor 输出应保留 raw DAG fact 并派生，不重写已完成 facts：
-
-```text
-raw_failure_category
-dag_normalized_failure_category
-product_line_failure_category
-recommended_follow_up
-```
-
-Product-line taxonomy 定义见 `ai_workspace/loop-agent/design/state-and-failure-taxonomy.md`。
-
-### 前端设计门禁专用恢复路径
-
-前端 DAG 的 design gate shell 失败（`frontend-first-design-gate-shell`、`frontend-final-design-gate-shell`、`frontend-design-gate-shell`）**不路由为 `ProductBug` / `dev-fix`**。此类失败固定路由为：
-
-- `productLineFailureCategory`: `ContractMismatch`
-- `recommendedFollowUp`: `frontend-plan-revision-and-rerun`
-
-恢复动作由 `planDagRecovery` 根据实际的 `normalizedFailureCategory` 和 run status 决定（通常为 `rerun-after-fix` 或 `manual-review`），但 product-line 维度的分类确保 Task Pool 和 morning report 不会将其混入普通 bug backlog。
-
-**非目标（本 playbook 不覆盖、runner 不实现）：**
-
-- 自动 retry / resume 节点执行
-- 修改 `completed/` 或 `paused/` 下的历史 run facts
-- 把 `autoRetryEligible` 当作 runtime 触发器
-- 仅凭 recovery 派生字段自动 approve Decision Gate
-
-## 快速命令
-
-```bash
-cd .
-
-# 全局 runtime 健康（active/paused/completed 摘要 + healthIssues；advisoryOnly）
-npm run dev -- dag doctor
-
-# 单 run 生命周期（approvalFlow、hasHumanApproval、nextRecommendedAction）
-npm run dev -- dag status --run-id <run-id>
-
-# 聚焦最新 paused run（--paused-latest ≡ --lifecycle paused --latest）
-npm run dev -- dag report --paused-latest [--json|--markdown]
-
-# 默认 compact Markdown 表格
-npm run dev -- dag report --run-id <run-id>
-
-# 机器可读 JSON（含 primaryFailure / primaryRecovery / downstreamSkippedNodes）
-npm run dev -- dag report --run-id <run-id> --json
-
-# 人类交接 Recovery Plan（四段结构化 Markdown）
-npm run dev -- dag report --run-id <run-id> --markdown
-
-# 过滤器
-npm run dev -- dag report --failed-only                              # 仅失败/需恢复
-npm run dev -- dag report --latest --failed-only                    # 最新一条需恢复 run
-npm run dev -- dag report --action retry-node                       # 按 primaryRecovery.action 筛选
-npm run dev -- dag report --lifecycle paused --action resume-or-reject
-
-# Decision Gate envelope dry-run（不 resume/retry；validate 无效时 exit 1）
-npm run dev -- dag decision inspect --run-id <run-id> [--node-id <node-id>]
-npm run dev -- dag decision validate --run-id <run-id> [--node-id <node-id>]
-```
-
-### Paused run operator 路径
-
-1. `dag report --paused-latest --json` 或 `dag doctor` — 定位最新 paused run 与 `primaryRecovery`
-2. `dag status --run-id <id>` — 读 `approvalFlow`、`escalationArtifactPath`、`pendingNodes`
-3. （可选）`dag decision validate --run-id <id>` — envelope preflight
-4. `dag approve --run-id <id> --option <option-id>` → `dag resume --run-id <id>`；或 `dag reject --run-id <id> --reason "..."`
-
-精确 approval 顺序见 [`agent-dag-runner.md`](agent-dag-runner.md) §Paused lifecycle。
-
-Decision Gate prompt 侧：`buildDagDecisionGateEvidence()`（`./src/core/dag-decision-evidence.ts`）从 `DagRunReportEntry` 生成 prompt-friendly 摘要，字段与 JSON report 对齐，**不**写回 run state。
-
-## `dag report --json` schema 锁定
-
-- **Schema 文件**：`ai_workspace/loop-agent/templates/agent-dag-report.schema.json`
-- **Envelope**：`{ schemaVersion: 1, runs: DagRunReportEntry[] }`
-- **稳定消费字段**（Decision Gate / tooling 应依赖）：`primaryFailure`、`primaryRecovery`、`downstreamSkippedNodes`、`recoveryRecommendation`、`normalizedFailureCategory`；node 级 `decisionEnvelope`、`artifacts`；paused 级 `pausedByNodeId`、`pauseReason`
-- **测试**：`./test/dag-report.test.ts` §`dag report JSON schema contract` 对 fixture run 做 schema 校验
-- **变更策略**：breaking 字段变更须 bump `schemaVersion` 并同步 schema 文件与测试
-
-## Recovery Action 枚举
-
-| Action | 含义 | 典型触发 |
-|--------|------|----------|
-| `none` | 无需恢复 | 成功完成 |
-| `monitor` | 进行中，等待结束 | `PENDING` / `RUNNING` |
-| `retry-node` | 修复瞬态条件后可重跑节点 | timeout；executor 瞬态（network/quota/rate-limit/unavailable） |
-| `rerun-after-fix` | 先修根因再重跑 | auth、validation、shell-command、static-error、非瞬态 executor |
-| `resume-or-reject` | 人工审批后继续或拒绝 | paused + decision-envelope / human-required |
-| `manual-review` | 人工审查后再定路径 | write-guard、human-rejected、unknown、非 paused 的 decision-envelope |
-| `inspect-upstream` | 先查上游失败 | SKIPPED 下游节点 |
-| `unknown` | 未映射类别（不应出现在正常派生路径） | 内部兜底 |
-
-## Product-Line Routing v0.1
-
-| Product-line category | Default follow-up |
-|---|---|
-| `SpecUnclear` | `spec-clarification` |
-| `ContractMismatch` | `architecture-contract-fix` |
-| `ProductBug` | `dev-fix` |
-| `TestBug` | `qa-fix-test` |
-| `EnvFailure` | `env-fix` 或 retry verify |
-| `FlakyTest` | `flaky-test-analysis` |
-| `RiskyChange` | `human-review` / `architecture-review` |
-| `DependencyFailure` | unblock dependency |
-| `NeedsHuman` | `human-review` |
-| `Unknown` | human triage |
-
-## 类别 → 动作 → operator 指引
-
-| Normalized category | Recovery action | Operator guidance | Anti-patterns |
-|---------------------|-----------------|-------------------|---------------|
-| `success` | `none` | 归档验收；按需 review artifacts | 对成功 run 发起 retry |
-| `timeout` | `retry-node` | 查日志/artifacts 确认瞬态；人工重跑节点 | 未查根因就循环重试；指望 runner 自动 retry |
-| `executor`（network/quota/rate-limit/unavailable） | `retry-node` | 等后端/配额恢复后重跑 | 把 auth/validation 误判为瞬态 executor |
-| `executor`（其他 raw） | `rerun-after-fix` | 查 executor.jsonl、node result | 盲目 retry 非瞬态 backend 错误 |
-| `auth` | `rerun-after-fix` | 更新 API key/凭证后重跑 | 在凭证未修复时 retry |
-| `write-guard` | `manual-review` | 审 writeSet/writePolicy、prompt、result.summary | read-only 节点写根 `artifacts/`；扩大 writeSet 掩盖违规 |
-| `validation` | `rerun-after-fix` | 修 schema/output/test 后再跑 | 跳过验证直接 approve |
-| `shell-command` | `rerun-after-fix` | 读 stdout/stderr、修命令或 repo 状态 | 只重跑 shell 不改命令 |
-| `static-error` | `rerun-after-fix` | 查 static config 与 emitted markdown | 当 LLM 节点 retry |
-| `decision-envelope`（paused） | `resume-or-reject` | `dag approve --run-id <id> --option <option-id>` / `dag reject --run-id <id> --reason "..."` → `dag resume --run-id <id>` | 未读 envelope 就 approve；用 recovery 字段单独 auto-approve |
-| `decision-envelope`（非 paused） | `manual-review` | 读 decision.envelope.json / validation artifact | 绕过 Decision Gate schema |
-| `human-required`（paused） | `resume-or-reject` | 提供人工输入 → approve/resume | 在 escalation 未解决时 resume |
-| `human-required`（非 paused） | `manual-review` | 读 human-escalation artifacts | 忽略 `requiresHuman` |
-| `human-rejected` | `manual-review` | 修订 contract/source；**新 run** | 对同一 contract 自动 retry |
-| `skipped` | `inspect-upstream` | 修上游 ERROR/SKIPPED 再考虑下游 | 直接 retry SKIPPED 节点 |
-| `unknown` | `manual-review` | 读 state.json、executor.jsonl、node artifacts | 假设 `autoRetryEligible` 会触发执行 |
-
-## Handoff Recovery Plan 结构
-
-`dag report --markdown` 的 **Recovery Plan** 含四段（与 JSON 稳定字段一一对应）：
-
-1. **Primary Failure** — `primaryFailure`（node 或 run scope）
-2. **Recovery Action** — `primaryRecovery`（action、summary、reason、flags、commandHint）
-3. **Blocked Downstream / Skipped Nodes** — `downstreamSkippedNodes`
-4. **Recommended Operator Action** — 面向 operator 的步骤摘要
-
-保存 handoff 时重定向到平台临时目录或 `ai_workspace/loop-agent/reports/`，不要写入 `.harness/dag-runs/`。
-
-## Decision Gate 消费约定
-
-1. 优先 `dag report --json` 或 `buildDagDecisionGateEvidence()` 的 **verified** 派生摘要。
-2. 映射到 `decision` / `nextAction` 须保守；recovery 证据是 **advisory only, not an execution directive**。
-3. `autoRetryEligible: true` 仅表示「规划上可人工重试」，**不**触发 runner。
-4. paused run 的人类路径仍是 M5 CLI：`dag approve --run-id <id> --option <option-id>` / `dag reject --run-id <id> --reason "..."` / `dag resume --run-id <id>`（见 [`agent-dag-runner.md`](agent-dag-runner.md) §Decision Gate）。
-5. Envelope 干跑：`dag decision inspect|validate` 重解析 run facts；`validate` 无效时 exit 1；**不**写 artifact、**不** resume。
-
-## Active stale run recovery（advisory detection）
-
-`dag doctor` 与 `dag status` 通过 `detectDagRunHealthIssues()` 检测 lifecycle 不一致，**不** mutate run facts。
-
-| Code | 典型场景 | operator 指引 |
-|------|----------|------------|
-| `terminal-in-active` | run 已完成但 `active/<run-id>/` 残留 | 对照 `completed/` canonical facts；手动 archive 或删除 stale 目录 |
-| `paused-in-active` | pause 后目录未迁至 `paused/` | `dag doctor` 诊断；修复 facts 后再 approve/resume |
-| `lifecycle-status-mismatch` | `paused/` 下 status 非 paused | 同上 |
-| `missing-approval-artifact` | approve 后 artifact 缺失 | 勿 resume；re-approve 或 restore artifact |
-| `non-terminal-in-completed` | completed 目录 status 异常 | manual-review only |
-| `run-id-mismatch` / `missing-state-json` | 目录损坏或命名错误 | Inspect；勿 auto-mutate completed facts |
-
-**Deferred runtime**：无 `dag recover apply` 或自动 cleanup；未来可能增加只读 `dag recover plan`（设计占位，未实现）。
-
-## 事实源与边界
-
-| 类型 | 位置 | 规则 |
-|------|------|------|
-| Canonical run facts | `.harness/dag-runs/{active\|paused\|completed}/<run-id>/` | **只读**；report 不写回 |
-| 派生 report | stdout / 重定向文件 | 可随时再生 |
-| 工作块摘要 | 根 `artifacts/` | 非 per-run 历史；read-only DAG 节点不得写 |
-
-## 验证
-
-```bash
-cd . && npx vitest run \
-  test/dag-report.test.ts \
-  test/dag-recovery-recommendation.test.ts \
-  test/dag-decision-gate-recovery-dogfood.test.ts \
-  test/dag-decision-evidence.test.ts \
-  test/dag-decision-envelope.test.ts \
-  test/dag-approve-resume.test.ts \
-  test/cli-contract.test.ts
-```
-
-实现细节与映射逻辑：`./src/core/dag-recovery-recommendation.ts`、`dag-report.ts`、`dag-decision-evidence.ts`。

package/docs/agent-dag-runner.md

@@ -1,67 +0,0 @@
-# Agent DAG Runner
-
-Agent DAG 是 loop-agent 的声明式编排 runtime。DAG 将工作拆为节点、按序执行 eligible ranks、记录 artifacts，并用 gate 做 review 与验证。
-
-## 基本用法
-
-```bash
-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>` 为平台原生临时目录。Windows 上 `--output`、`--dag`、`--cwd` 的实际值用原生路径。
-
-## Executors
-
-- `static`：确定性生成的 artifacts 或 notes
-- `shell`：验证与文件系统检查
-- `pi`：规划、review、诊断；节点设 `toolProfile: "write"` 时有界写入
-
-## Retry (read-only Pi nodes)
-
-planner/scout/reviewer/verifier/closeout 角色的只读 Pi 节点可声明 opt-in `retryPolicy`，用于在同一 run 内有界重试模型连接中断、provider 限流、临时不可用或请求 timeout。生成器会为这些安全节点自动声明默认策略：总尝试次数 3（手工配置上限 5），指数退避，单次等待上限 30s。
-
-- 仅以下原始失败分类默认可重试：`timeout`、`network`、`rate-limit`、`unavailable`。
-- `quota`、`auth`、`invalid-output`、`write-guard`、`decision-envelope` 与未知失败不重试。`quota` 不是 rate limit，不会被自动重试。
-- 资格由确定性 helper 判断：仅 `writePolicy=read-only|none`（或 Pi 默认只读）的 planner/scout/reviewer/verifier/closeout 可用。supervisor、implementer、writer（`toolProfile=write` 或 `writePolicy=exclusive`）、docs-only、dynamic、shell、static 与 decision-gate 节点一律不重试，DAG validation 会拒绝其策略。
-- 每次 attempt 写入独立不可变证据（`<node-id>/attempt-<n>.json`，run-relative path），最终 node record 的 `attempts` 字段引用完整 attempt 历史；后一次成功不会覆盖前一次失败证据。
-- 重试期间复用同一 run、controller identity、skill snapshot、prompt、model 与上游输入。节点终态的 `durationMs`、`tokensUsed`、`parsedEvents` 聚合全部 attempts；退避等待会刷新 `lastActivityAt`，避免被误判为 node-quiet。当前退避会占用该节点所在的并发槽。
-
-示例：
-
-```json
-{
-  "retryPolicy": {
-    "maxAttempts": 3,
-    "backoff": "exponential",
-    "initialDelayMs": 2000,
-    "maxDelayMs": 30000,
-    "retryCategories": ["timeout", "network", "rate-limit", "unavailable"]
-  }
-}
-```
-
-未声明 `retryPolicy` 的历史 DAG 行为不变（单次执行、无 `attempts` 字段，也不新增 attempt artifact）。
-
-## Skills
-
-DAG spec 可声明 `defaults.skills`、`skillsByRole` 与节点级 `skills`。Runner 优先从目标项目 `.agents/skills/<skill-name>/SKILL.md` 解析本地指令，再回退到包内 `.agents/skills/`，并在各节点 `skills.json` artifact 中记录解析元数据。
-
-执行前可用 `dag validate --strict-skills` 做 opt-in skill audit；该门禁会在 missing/error/truncated skill 或 unresolved reference 出现时失败。默认 role skill 应来自 `ai_workspace/loop-agent/.agents/skills/vetted-skill-registry.md` 中记录的 repo-local wrapper。
-
-目标项目的 `loop-agent` skill 位于 `.agents/skills/loop-agent/SKILL.md`。loop-agent 源仓库和 npm 包内置版本仍位于 `.agents/skills/loop-agent/SKILL.md`；遗留根路径 `skill/SKILL.md` 仅为旧 worktree 保留兼容 fallback。
-
-## Artifacts
-
-DAG artifacts 位于：
-
-```text
-.harness/dag-runs/<state>/<run-id>/artifacts/<node-id>/
-```
-
-根目录 `artifacts/` 不是有效的默认 DAG artifact 位置。
-
-## Shell Gates
-
-- `shell.verdictGate` 从注入的当前 run 目录读取 `$HARNESS_DAG_RUN_DIR/<fromNodeId>.json`；不应自行发现 active run paths。

package/docs/cursor-prompt-sidecar.md

@@ -1,36 +0,0 @@
-# cursor-prompt Sidecar
-
-`cursor-prompt` 是显式、手工触发的 one-shot sidecar。它不是受治理 Agent runtime，也不参与 DAG、Loop 自动写入、Delegate `--auto-run` 或 task writer 选择。
-
-## 产品定位
-
-| 路径 | 角色 |
-|---|---|
-| Pi DAG (`implement-pi` / `repair-pi`) | 唯一受治理 Agent writer |
-| shell / static | 确定性验证与静态输出 |
-| `cursor-prompt` | 人工 one-shot 干预；成功不等于任务完成 |
-
-## 用法
-
-```bash
-loop-agent cursor-prompt --cwd . "bounded task prompt"
-loop-agent cursor-prompt --file <path>
-loop-agent cursor-prompt --stdin
-loop-agent cursor-prompt --model <id>
-loop-agent cursor-prompt --timeout <ms>
-loop-agent cursor-prompt --stream
-loop-agent cursor-prompt --list-models
-```
-
-调用时才加载 `@cursor/sdk`。缺少 SDK 或 `CURSOR_API_KEY` 时，只有这条命令失败；普通 Agent DAG / doctor / init 不要求 Cursor。
-
-## 约束
-
-- 不读取 `harness.json` task config / DAG facts 作为授权来源。
-- 不复制 DAG `writeSet`、repair、resume 或 Loop auto-execute 能力。
-- 返回后由主会话检查 diff，并显式运行 shell verification。
-- one-shot evidence 写入 `.harness/runs/{active,completed,failed}`。
-
-## 迁移说明
-
-旧 `executor: "cursor"` DAG、`executors.cursor`、`loopAutoWritePolicy` 与 `cursor-fix` 已硬切删除。需要写入时请重新生成 Pi-only DAG，或仅在人工干预场景使用本 sidecar。

package/docs/decisions/README.md

@@ -1,18 +0,0 @@
-# 决策
-
-本目录存放架构决策记录（ADR）。模板见 `docs/templates/adr.md`。
-
-## 索引
-
-| ADR | 状态 | 摘要 |
-| --- | --- | --- |
-| [`0001-pi-only-agent-runtime.md`](0001-pi-only-agent-runtime.md) | accepted | 受治理 Agent 仅 Pi；`cursor-prompt` 为显式 sidecar |
-| [`0002-task-pool-runtime-root.md`](0002-task-pool-runtime-root.md) | accepted | Task Pool 唯一根 `.harness/task-pool/`，旧 `.task-pool/` 不兼容 |
-| [`0003-docs-dual-tree-converge.md`](0003-docs-dual-tree-converge.md) | accepted | `website/docs/` 用法 vs `docs/` 治理；docs-converge 检查表 |
-| [`0004-task-pool-feature-scoped-task-identity.md`](0004-task-pool-feature-scoped-task-identity.md) | accepted | Task Pool 复合身份 `{featureId,taskId}`、state v2、legacy fail-closed、Observe composite route |
-
-**读者注意（M4）**：ADR 0004 **决策边界**仍有效；正文中「M2+ 未改 consumers/Observe」段落是 M0/M1 当时的切片叙述，现已过时。实现进度以 `docs/progress/2026-07-15-task-pool-v2-feature-scoped-task-identity.md`、最终报告 `docs/reports/2026-07-15-task-pool-v2-feature-scoped-task-identity.md` 与 `CHANGELOG.md [Unreleased]` 为准。本任务 **不修改** ADR 0004 正文（不在 closeout allowedPaths）。
-
-新增跨版本架构取舍时：用模板新增 `NNNN-title.md`，并更新本表。不要把 ADR 正文复制进 `website/docs/`。
-
-实施细节与证据仍以对应 `docs/exec-plans/completed/` 与 `CHANGELOG.md` 为准；ADR 只固化决策边界。

package/docs/design/README.md

@@ -1,167 +0,0 @@
-# 设计笔记
-
-`docs/design/` 存放将 `loop-agent` 作为更大产品线 agent 平台内仓库本地 runtime 的规划笔记。这些是设计输入，不是 `src/` 已具备该能力的证明——**除非**页首明确写了实现校准条，且有 `src/` / CHANGELOG / completed plan 旁证。
-
-**维护日：2026-07-16** — 索引与归档建议按当前代码（`@tea-agent/loop-agent@0.12.0` + 主干 Unreleased）再采样。
-
-| 文档 | 用途 |
-|---|---|
-| `taskspec-to-loop-agent-mapping.md` | 将产品线 TaskSpec 适配为 `loop-agent` task 的契约 |
-| `taskspec-to-loop-agent-mapping.yaml` | 同上契约的结构化对照表 |
-| `state-and-failure-taxonomy.md` | 文档、Task Pool、DAG、Loop 共用的 canonical status 与 failure taxonomy |
-| `frontend-implementation-workflow.md` | 前端 DAG 实现 / 评审 / 验证工作流与证据约定 |
-| `frontend-mock-data-workflow.md` | 前端任务先读取规范、识别项目 Mock 服务、生成 Mock 合同并做专项验证的已实现设计 |
-| `dag-source-binding-and-recovery.md` | 新生成 DAG 的权威任务源绑定、前端需求编号覆盖门禁与中断后完整重生成规则 |
-| `full-chain-test-knowledge-base.md` | 全流程测试知识库分层、目录、对象模型、与 backend-test-dag / Feature QA 的读写映射 |
-| `full-chain-testing-system-redesign.md` | **综合重设计**：知识库权威层 + I/T/V/K 四类 DAG + knowledge-sync v2 硬化与迁移 |
-| `testing-knowledge-base-impl-spec.md` | **知识库实现细节 v1（先冻结）**：目录、schema、ID、读写矩阵、校验规则、MVP 清单 |
-| `knowledge-graph-and-query-spec.md` | **业务知识图谱 + 查询协议 v1**：实体/边、knowledge-links、kb-query 分层、索引 materialize |
-| `knowledge-graph-ai-bootstrap.md` | **AI 构建图谱 + 初始化 B0–B6**：staging 提案、人审晋升、bootstrap DAG、增量更新 |
-| `verification-subdag-plugin.md` | 独立测试全流程 Verification DAG 与三种实现 DAG 的 compose 设计（若分支存在） |
-## 归档策略（何时迁入 `archive/`）
-
-满足以下**多数**条件时可归档：
-
-1. 对应能力已在 `src/` 落地，且有 `docs/exec-plans/completed/*` 或 dated report / CHANGELOG 版本说明；
-2. 文档主体是**阶段性计划 / 月度 WBS / 已关闭路线图**，不再驱动实现决策；
-3. 继续放在 design 根目录会让新人误判为「未做完」或「下一件必做」。
-
-**不要归档**（仍放根目录）：
-
-- 仍被代码/CLI/映射表**持续引用**的契约（taxonomy、taskspec mapping、frontend workflow 等）；
-- 仍有 **active exec-plan** 或大段 **planned/deferred** 的设计真源（如 Eval Lab）；
-- 长期路线与方法论笔记（六个月规划、腾讯实践、研发模式）——可加校准条，不必塞进 archive；
-- 纯视觉 token 参考（`DESIGN-*.md`）。
-
----
-
-## 契约与实现映射（优先读 · 仍活）
-
-| 文档 | 用途 | 归档建议 |
-|---|---|---|
-| `taskspec-to-loop-agent-mapping.md` / `.yaml` | TaskSpec → loop-agent task 契约 | **保留**（随 schema 更新） |
-| `state-and-failure-taxonomy.md` | 状态 / failure taxonomy | **保留** |
-| `frontend-implementation-workflow.md` | 前端 DAG 实现/评审/验证约定 | **保留**（活工作流） |
-| `full-chain-test-knowledge-base.md` | 测试知识库分层与对象模型 | **保留**（K 族权威设计） |
-| `full-chain-testing-system-redesign.md` | I/T/V/K 综合重设计 | **保留**（后续 T/V 与 hardening 仍可能引用；MVP 已部分 ship） |
-| `testing-knowledge-base-impl-spec.md` | 知识库实现细节 v1 | **保留**（规格冻结；DAG 细节另文） |
-| `knowledge-graph-and-query-spec.md` | 图谱 + 查询协议 v1 | **保留**（Phase A 已实现，规格仍真源） |
-| `knowledge-graph-ai-bootstrap.md` | AI bootstrap B0–B6 / staging | **保留**（bootstrap MVP 已实现，增量/产品化仍引用） |
-
-**执行 Contract（knowledge 已完成归档）：** `docs/exec-plans/completed/2026-07-14-knowledge-sync-and-graph.md`
-
----
-
-## 实验 / 评测（设计输入 · 进行中）
-
-| 文档 | 用途 | 归档建议 |
-|---|---|---|
-| `recursive-self-improvement-eval-lab.md` | Harness Eval Lab 设计真源 | **保留 active**：M1 + M2 W2.1–W2.3 已实现；W2.4 / M3+ 未做。执行计划：`docs/exec-plans/active/2026-07-16-recursive-self-improvement-eval-lab.md` |
-
-> 设计 README 旧句「W2.3 仍未实现」已过时：W2.3 run association **已合入**（见 active plan 进度与 `CHANGELOG.md [Unreleased]`）。
-
----
-
-## 路线与产品线笔记（非实现证明 · 保留 + 校准条）
-
-| 文档 | 用途 | 归档建议 |
-|---|---|---|
-| `dynamic-workflow-dag-engine-roadmap.md` | Dynamic Workflow 阶段规划 | **保留**：页首有落地校准；高风险 shard/merge 等仍是 roadmap |
-| `六个月规划.md` | 长期路线 | **保留**：页首 **2026-07-16** 已补 0.12.0 / Task Pool v2 / Ready Planner / Eval 指针；第 3–6 月仍有效前瞻 |
-| `产品线共享知识库.md` | 产品线文档仓库上游事实源 | **保留**（docs-sync 等仍多为未来） |
-| `研发模式.md` | 10 日 Feature 团队工作流 | **保留**（方法论） |
-| `腾讯实践对当前项目的指引.md` | 外部实践映射 | **保留**（背景；源文在 website practices） |
-
----
-
-## 视觉参考（保留）
-
-| 文档 | 用途 | 归档建议 |
-|---|---|---|
-| `DESIGN-cursor.md` | Observe 暖白 / Cursor 风格 token | **保留**（视觉参考） |
-| `DESIGN-lovable.md` | Lovable 暖色视觉参考 | **保留** |
-
----
-
-## 本次已迁入 `archive/`（2026-07-16）
-
-| 文档 | 原因 |
-|---|---|
-| `archive/2026-07-14-loop-agent-self-update-notifier.md` | 自更新提醒 **已实现**（0.11.0 + report/completed plan）；设计不再是「尚未实现」 |
-| `archive/2026-07-16-priority-ready-planner-contract.md` | Ready Planner **已实现并 closeout**；原 M0 RED「未实现」状态条会误导 |
-
----
-
-## 已归档（历史）
-
-| 文档 | 用途 |
-|---|---|
-| `archive/2026-07-07-agent-worker-plan.md` | Worker 落地计划（已实现于 `src/worker/`） |
-| `archive/2026-07-07-taskspec-plan.md` | TaskSpec v0.1 设计（已实现） |
-| `archive/2026-07-10-下一阶段任务-功能开发完成.md` | 样本/失败硬化完成记录 |
-| `archive/2026-07-10-observe-ui.md` | Observe UI v0（OBS-001～010） |
-| `archive/2026-07-10-observe-ui-optimization.md` | 中文 DAG-first / 过程时间线 |
-| `archive/2026-07-10-observe-ui-goal.md` | OBS 进度看板（全部 done） |
-| `archive/2026-07-14-observe-ui-roadmap.md` | Observe R1–R5 路线图（已完成） |
-| `archive/2026-07-11-第一月规划.md` / `第一月wbs.md` | 首月闭环历史 |
-| `archive/2026-07-12-第二月规划.md` | 第二月 Feature 闭环历史 |
-| `archive/2026-07-14-loop-agent-self-update-notifier.md` | CLI 自更新提醒设计（已实现） |
-| `archive/2026-07-16-priority-ready-planner-contract.md` | Ready Planner M0 合同（已实现） |
-
----
-
-## 根目录文件 — 归档建议一览（2026-07-16）
-
-| 文件 | 建议 | 说明 |
-|---|---|---|
-| `README.md` | 保留 | 本索引 |
-| `taskspec-to-loop-agent-mapping.*` | 保留 | 活契约 |
-| `state-and-failure-taxonomy.md` | 保留 | 活契约 |
-| `frontend-implementation-workflow.md` | 保留 | 活工作流 |
-| `full-chain-test-knowledge-base.md` | 保留 | K 族设计真源 |
-| `full-chain-testing-system-redesign.md` | 保留（可选日后拆「已落地摘要」） | 综合草案；部分已 ship |
-| `testing-knowledge-base-impl-spec.md` | 保留 | 规格冻结 |
-| `knowledge-graph-and-query-spec.md` | 保留 | 协议真源 |
-| `knowledge-graph-ai-bootstrap.md` | 保留 | bootstrap 设计真源 |
-| `recursive-self-improvement-eval-lab.md` | **保留 active** | Eval Lab 真源 |
-| `dynamic-workflow-dag-engine-roadmap.md` | 保留 | roadmap + 校准 |
-| `六个月规划.md` | 保留 | 路线；校准条已含 0.12 / Unreleased |
-| `产品线共享知识库.md` | 保留 | 上游知识库愿景 |
-| `研发模式.md` | 保留 | 方法论 |
-| `腾讯实践对当前项目的指引.md` | 保留 | 实践映射 |
-| `DESIGN-cursor.md` / `DESIGN-lovable.md` | 保留 | 视觉 |
-| ~~`2026-07-14-loop-agent-self-update-notifier.md`~~ | **已归档** | 见上 |
-| ~~`2026-07-16-priority-ready-planner-contract.md`~~ | **已归档** | 见上 |
-
-### 暂不建议归档（但可标注「部分落地」）
-
-- **knowledge 四件套 + full-chain\***：exec-plan 已 complete，但设计文仍是目录/schema/增量协议的权威；归档会切断引用习惯。若未来拆出「实现状态」短页，可把**纯进度段落**迁 archive，规格正文仍留根。
-- **六个月规划 / Dynamic Workflow roadmap**：含未来月与未完成 primitive；只做页首校准，整篇归档会丢前瞻。
-
----
-
-## 命名约定（2026-07-09 起）
-
-| 名称 | 含义 | 状态 |
-|---|---|---|
-| `loop-agent` | 仓库本地 runtime / 治理控制器 CLI | 已发布 |
-| `agent-worker` | 产品线 TaskSpec 批处理适配层 CLI | 已发布 |
-| `agent-platform` | 早期规划设想名；**不是**当前 CLI | 仅未来 monorepo/上层服务语境 |
-
-```text
-产品线 docs / TaskSpec / TaskGraph
-  → agent-worker（本地批处理适配）
-    → loop-agent（runtime kernel）
-      → Pi（受治理 Agent） / shell / static
-      → cursor-prompt（显式手工 one-shot sidecar，非受治理 writer）
-```
-
-## 维护规则
-
-1. 保持 TaskSpec 字段、status、failure category、命令示例与契约文档一致。
-2. 未来平台组件标为目标架构，除非已存在于 `src/` 或 `scripts/`。
-3. 命令示例只用 `agent-worker` / `loop-agent`。
-4. `config-types` / profile routing 变更时更新 mapping 文档。
-5. failure / Task Pool state 变更时更新 taxonomy。
-6. **过期月规划 / 已关闭实现合同**迁入 `archive/`，并更新本 README。
-7. 运行 `bash scripts/check-repo.sh`（或至少 check-doc-index / check-doc-links）。

package/docs/development-principles.md

@@ -1,73 +0,0 @@
-# 开发原则
-
-loop-agent 是面向 agentic coding 的工作流 runtime。仓库应保持小而显式、可验证。
-
-## 操作立场
-
-项目采用「人类掌舵、智能体执行」的工程模型。Agent 可实现、验证与总结，但持久意图与完成证据必须落在仓库中。
-
-这个模型吸收了 Anthropic 长时运行 agent harness、OpenAI Codex harness engineering、腾讯端到端 Harness Engineering 和社区 agent harness 实践中的共同经验：用短入口文档导航长期知识，用结构化任务状态和 handoff artifact 跨 session 传递事实，用独立验证和评审回路约束 agent 输出，并把人类注意力集中在意图、边界、架构和反馈系统上。面向使用者的背景资料收录在 `website/docs/practices/`。
-
-- 仓库是记录系统。决策、契约、计划、测试、报告与交接属于 tracked files。
-- `AGENTS.md` 是操作地图，不是知识 dump。长期方法论与决策属于 `ai_workspace/loop-agent/`。
-- 工作以小步、可逆、可验证的增量推进。
-- 状态不确定时，先跑基线验证再开新工。
-- 完成由新鲜证据定义，而非意图或信心。
-
-## 原则
-
-1. 一次任务只推进一个有边界的工作块。
-2. 设计新行为前先搜索现有代码、文档、脚本与测试。
-3. Shell 验证是完成权威。
-4. Runtime 状态在 `.harness/`；持久决策在 `ai_workspace/loop-agent/`。
-5. Pi writer 节点必须由显式 allowed/forbidden paths 与 writeSet 约束；Cursor 仅可作为 `cursor-prompt` one-shot sidecar，不进入受治理 DAG/Loop 写入路径。
-6. Pi review/planning 路径是 advisory，除非后跟确定性验证。
-7. 反复出现的约束应固化为文档、测试、脚本、检查或模板。
-8. 不要把隐藏流程状态只留在聊天里。
-9. 不要把占位实现当作已完成交付。
-10. 新增抽象前先沿用现有局部模式。
-
-## 仓库结构
-
-- 源码：`src/`
-- 测试：`test/`
-- Skill 指令：源码仓库和 npm 包内置在 `.agents/skills/`，目标项目 repo-local skills 在 `.agents/skills/`
-- 验证与维护脚本：`scripts/`
-- 治理与交接产物：`ai_workspace/loop-agent/`
-
-## 变更纪律
-
-行为变更要更新测试；工作流或命令变更要更新文档与示例；治理变更要更新 `harness.json` 与相关检查脚本。
-
-当工作影响需求、行为、跨命令契约或 harness 规则时，更新对应持久产物：
-
-- 设计/契约文档 — 变更后的预期
-- 测试或验证脚本 — 变更后的行为
-- progress log 或 report — 非平凡交接证据
-- ADR — 架构或公开契约决策
-- 模板 — 重复流程可复用时
-
-除非 contract 明确说明必须一起移动，否则不要在一个工作块里混合无关重构、新功能与大规模文档迁移。
-
-## 搜索与复用
-
-实现前先检视现有系统：
-
-- 仓库已索引且任务需要理解代码时，优先用 CodeGraph。
-- 可用时用 `rg` 做文本搜索、`fd` 找文件。
-- 引入新 helper 前先读邻近测试与 helper。
-- 优先结构化 parser 与现有本地 API，避免 ad hoc 字符串处理。
-
-在搜索证明否则之前，假设系统可能已有部分解法。
-
-## 完成纪律
-
-完成声明必须回答：
-
-- 改了什么
-- 为何选此方案
-- 哪条命令验证、结果如何
-- 是否影响契约、文档、测试或脚本
-- 剩余风险或后续项
-
-验证失败时，报告失败命令与观察到的状态，而不是软化完成定义。

package/docs/exec-plans/README.md

@@ -1,6 +0,0 @@
-# 执行计划
-
-- `active/README.md` — 当前进行中的计划
-- `completed/README.md` — 已完成的计划
-
-影响多文件、公开命令行为或仓库治理的变更应使用 execution plan。