@tea-agent/loop-agent 0.24.11-beta.0 → 0.25.0

package/skills/agent-worker/references/agent-worker-operator.md

@@ -31,6 +31,8 @@ Leaf DAG nodes 不得递归启动 `agent-worker`。Worker 负责 DAG 之外的 s
 
 ## Feature and Task Pool Flow
 
+0. **新建 Packet（确定性脚手架，无模型）** — 包内自洽说明见下节 *Feature Packet Scaffold*；不依赖 website 文档站。
+
 1. 阅读 Feature Packet，校验其 TaskSpecs 与 dependency graph。
 2. 从持久化的 Task Pool state 推导下一步动作；不要从 chat history 重建 lifecycle state。canonical state 键是 `{ featureId, taskId }`（路径 `.harness/task-pool/states/<featureId>/<taskId>.json`）。
 3. 对可写 batch 只冻结一次 controller，并将其 identity 传播到下游 evidence。
@@ -55,6 +57,88 @@ Leaf DAG nodes 不得递归启动 `agent-worker`。Worker 负责 DAG 之外的 s
 8. Inspect（原 Observe）只读：推荐 `agent-worker console serve` 的 `/inspect/#/...`；兼容 `observe serve|snapshot`。canonical Task 路由为 `/api/features/:featureId/tasks/:taskId` 与 `#/feature/:featureId/task/:taskId`。8790 `/api/health` 为 `OperatorSurfaceHealthV1`；8787 仍为 `ObserveHealthV1`。
 9. Official Console：`agent-worker console serve|doctor`（默认 loopback；可 `--host 0.0.0.0` / `--debug`）。Recovery CTA 为 report/doctor/decision/resume/reconcile/regenerate/打开检视；无 Cancel、无主 CTA「直接改代码」。主会话 Compatibility Assist 不得替代 Console/CLI 执法。
 
+## Feature Packet Scaffold
+
+确定性入口：一个纯 BE/FE 需求 → 一个 `features/F-YYYY-NNN/` Packet → Task Pool 串行掘进。主会话只跑 CLI，不手写 TaskGraph。
+
+### 边界（v1）
+
+| 做 | 不做 |
+| --- | --- |
+| 模板 + 槽位确定性生成 | 一键 LLM 生成完整合同 |
+| `profile: generic` 短图 | 默认 `fullstack-v1` / 复制 `F-2026-005` 全图 |
+| 显式 `--verify-command` | 猜测项目测试命令 |
+| 一需求一 Feature 目录 | 跨 Feature 自动 depends / 并行 Pool |
+| 写盘前同源 `task validate-feature` | 读/写 `.harness/**` 或构造 `LoopAgentClient` |
+
+### 三模板
+
+| 模板 | 最小图 |
+| --- | --- |
+| `backend-only` | `BE-IMPL-001`（需 ≥1 `--be-path`） |
+| `frontend-only` | `FE-IMPL-001`（需 ≥1 `--fe-path`） |
+| `fe-with-api` | `CONTRACT-001` → `BE-IMPL-001` + `FE-IMPL-001`（consumers 仅实现节点；两端 path 都要） |
+
+v1 **不**生成 `BE-TEST` / `FE-TEST` / `FINAL-VERIFY`。`feature_id` 强制 `F-YYYY-NNN`（≥3 位序号）。输出固定 `<repo>/features/<feature-id>`；无 `--force` / `--out`；已存在目录（含空目录）一律拒绝。
+
+### 日常命令
+
+```text
+# 可选 dry-run：完整 parse/render/validate，零写入
+agent-worker feature scaffold --repo <repo> --template backend-only \
+  --feature-id F-2026-010 --title "..." \
+  --be-path services/example/** \
+  --verify-command "npm run typecheck" --verify-command "npm test" \
+  --dry-run --json
+
+agent-worker feature scaffold --repo <repo> --template frontend-only \
+  --feature-id F-2026-011 --title "..." \
+  --fe-path apps/web/src/settings/** \
+  --verify-command "npm test" --json
+
+agent-worker feature scaffold --repo <repo> --template fe-with-api \
+  --feature-id F-2026-012 --title "..." \
+  --be-path services/api/** --fe-path apps/web/src/api/** \
+  [--contract-path docs/contracts/F-2026-012/api.md] \
+  --verify-command "npm test" --json
+
+# 机器门禁 → 只读决策 → 串行掘进（固定 published controller）
+agent-worker task validate-feature features/F-2026-010
+agent-worker feature review --feature-dir features/F-2026-010 --repo <repo> --json
+agent-worker feature run --feature-dir features/F-2026-010 --repo <repo> \
+  --loop-agent-bin <published> \
+  --expected-controller-version <version> \
+  --expected-controller-fingerprint sha256:<hex> \
+  --git-mode checkpoint --limit 1 --json
+
+# Failed 只走官方恢复
+agent-worker task retry <taskId> --feature-id F-2026-010 --repo <repo> --reason "..."
+```
+
+### Batch
+
+```text
+agent-worker feature scaffold --repo <repo> --batch <yaml-or-json> [--dry-run] [--json]
+```
+
+- 与单条 flags 互斥；每条必须显式 `feature_id` / `title` / `template` / `verify_commands`。
+- 任一非法、冲突、目标已存在或写盘失败 → **整批零写入**（已提交目录回滚）。
+- 示例形状（包内模板若存在）：`docs/templates/product-line/feature-scaffold-batch.example.yaml`。
+- 三模板生成快照（只读、防漂移，非 live Feature）：`docs/templates/product-line/scaffold-samples/{backend-only,frontend-only,fe-with-api}/`。
+
+### 多需求策略
+
+1. 一个需求条目 → 一个 Feature 目录。
+2. 多个 FE/BE 需求：batch scaffold 后 **串行** `feature run --limit 1`（先完 F-010 再 F-011）。
+3. 后端可独立交付时：先 `backend-only`，再 `frontend-only`（跨 Feature 依赖只写文档，不做自动 depends_on）。
+4. 同 Feature 内 BE+FE 原子交付用 `fe-with-api`。
+
+### 内容与完成定义
+
+- scaffold 只给骨架；`requirement.md` / AC 文案由人或后续「只填槽、不改 graph」skill 填充。
+- v1 完成 = Packet 可 scaffold 且 Pool 可掘进到图内 Task **Done**；`verify-final` / Delivery / Closeout 为 v1.5（ADR 0007），非 scaffold 必经。
+- 已知恢复限制：mid-run `SIGKILL` 可能导致 Pool `Running` 且 `runs.jsonl` 缺失时 reconcile 失败（FC-B）；勿对 worker 随意 SIGKILL；Failed 后用 `task retry`。
+
 ## Versioned Self-Hosting
 
 - Published version N 是整个 maintenance batch 的 controller；不要在任务中途切换。

package/skills/frontend-implementation/references/node-contracts.md

@@ -6,8 +6,8 @@ Pre-write nodes are read-only. Preserve IDs, labels, commands, language, require
 
 - **`frontend-contract-pi`**: `Scope`, `Non-goals`, `Acceptance Criteria`, `UI States`, `Target Runtime Environment`, `Risks`, `Verification Expectations`. No guessed requirements.
 - **`frontend-scout-pi`**: routes, components, tokens, data/API/Mock, scripts, tests, assets. Fact vs inference vs gap. Query the knowledge base when available and always search+read `openspec/schemas/`, `openspec/project-specs/`, and `ai_workspace/` before repo fallback. Output stack, routes, components, styling, conventions, state/data, test entry points, reuse, risks.
-- **`frontend-plan-pi` + conditional design loop**: AC → explicit observable `expectedOutcome`, interactions → explicit `trigger` + `expectedBehavior`, then steps, in-bound files, applicable UI states, reuse, deps, Mock/API strategy, activation/rollback, frozen verify entrypoints, real-integration gap, and exactly one `frontend-implementation-contract-v1` JSON object. IDs plus file paths are not sufficient behavior semantics. Use `uiStates: []` for logic-only changes with no user-visible UI state; do not invent UI states. Applicable states require behavior/implementation/verification, while non-applicable states require a reason and omit empty behavior placeholders. Prefer native Mock; browser intercept only with existing e2e; request-adapter only for a reversible seam. `auto` may select `not-needed` when no project Mock capability exists, while keeping real requests default and recording the gap; `required` cannot. Initial design pass uses the original plan; only exact `request-revision` runs read-only revision plus final review. Small-risk runs one design review only.
-- **`frontend-prewrite-gate-shell`**: the sole write authorization. Resolve effective plan/review, require exact pass, retain every REQ/BR/AC id, enforce Mock policy, validate schema/source binding, and materialize `contracts/frontend-implementation-contract.json`. Fallback is allowed only when a conditional primary is absent; an existing malformed primary fails closed. Generation-time blocked Mock produces one deterministic blocking shell node and no writer.
+- **`frontend-plan-pi` + conditional design loop**: AC → explicit observable `expectedOutcome`, interactions → explicit `trigger` + `expectedBehavior`, then steps, in-bound files, applicable UI states, reuse, deps, Mock/API strategy, activation/rollback, frozen verify entrypoints, real-integration gap, and exactly one `frontend-implementation-contract-v1` JSON object. IDs plus file paths are not sufficient behavior semantics. Use `uiStates: []` for logic-only changes with no user-visible UI state; do not invent UI states. Applicable states require behavior/implementation/verification, while non-applicable states require a reason and omit empty behavior placeholders. Prefer native Mock; browser intercept only with existing e2e; request-adapter only for a reversible seam. `auto` with absent/ambiguous project Mock capability must select `not-needed`, keep real requests default, and record the gap; `required` cannot select `not-needed`. Initial design pass uses the original plan; only exact `request-revision` runs read-only revision plus final review. Small-risk runs one design review only.
+- **`frontend-prewrite-gate-shell`**: the sole write authorization. Resolve effective plan/review, require exact pass, retain every REQ/BR/AC id, enforce Mock policy, validate schema/source binding and writeSet containment, and materialize `contracts/frontend-implementation-contract.json`. A planned fixture or consumer may be a future writer output and need not exist before authorization. Fallback is allowed only when a conditional primary is absent; an existing malformed primary fails closed. Generation-time blocked Mock produces one deterministic blocking shell node and no writer.
 - **`frontend-implement-pi`**: sole regular exclusive writer and consumer of `frontend-bounded-implement`, not this discovery skill. Stay in `writeSet`; real requests default-on; Mock reversible, dev/test-only, production-off. Atomic handler/intercept/adapter with consumer+tests. Stop on forbidden paths or guesses. First line must be `IMPLEMENTATION_OUTCOME: changed|already-satisfied|blocked`; runtime checks it against the attributed diff. Optional mock-verify when frozen; static+behavior always; behavior must prove page consumption. Skipped-Mock `not-needed` keeps real integration pending unless the real backend path has fresh evidence.
 
 ## Contract / trace / stages (M1–M2)

package/skills/loop-agent/SKILL.md

@@ -13,13 +13,12 @@ references:
 
 # loop-agent Workflow
 
-Entry for `loop-agent`: trigger, routing, hard rules. Details live in `references/` on demand. `references/command-reference.md` is discoverable via the routing table, **not** a required reference.
+Entry: routing and hard rules. Required details come from frontmatter references；`command-reference.md` stays optional below.
 
 ## 默认立场
 
 - 主入口是 **Agent DAG**（经 `loop-agent` / 可选 `agent-worker` CLI）。
-- 本 skill 对宿主定位是 **Compatibility / Operator Assist**，不写业务代码。
-- **主会话 = operator-only**：编排 CLI、审 writeSet、只读 status/doctor/report、记 human gate、跑 Shell verification 与 handoff。
+- 宿主仅作 **Compatibility / Operator Assist**：主会话编排 CLI、审 writeSet、读 status/doctor/report、处理 human gate、验证与 handoff；不写业务代码。
 - **严禁**主会话绕过 CLI 用宿主 Edit/Write 改业务实现，或 CLI 失败后「救火改文件」。
 - DAG `pi` executor 默认 read-only；`toolProfile: "write"` 时为 bounded writer；sidecar 须 per call 收窄。
 - Shell verification 是事实源；长期结论写回 `ai_workspace/loop-agent/`、`docs/decisions/` 或 `skills/`。
@@ -51,13 +50,14 @@ CLI `src/cli/`；DAG `src/workflows/dag/`；loop `src/workflows/loop/`；executo
 
 ## Hard Rules
 
-1. Prefer vertical tracer bullets: each slice crosses the real integration layers with independent acceptance/verification. Do not horizontal-slice.
+1. Use vertical tracer bullets across real integration layers；each needs independent acceptance and verification.
 2. Autonomy ≠ governance profile: declare AFK/HITL in human gate; choose `--profile` by risk.
 3. Source materials mandatory: `source/需求.md`、`source/执行约束.md`、优先 `source/references/*` originals。
-4. Agent DAG is the implementation workflow；review three-way checks references + derived source + implementation。
-5. 主会话不绕过 CLI 直接写业务代码；失败只走 doctor/reconcile/human gate/重跑。
-6. DAG `pi` executor read-only unless `toolProfile: "write"`；completed run facts read-only；不得从 read-only DAG/sidecar 写 root `artifacts/`。
-7. No hidden state in chat only；verify before completion.
+4. Structured task config only: `referenceDocs` uses `{ path, name? }[]`, never a string array；`verifyCommands` uses `{ label, command, timeoutMs? }[]`, never a string array。
+5. Agent DAG is the implementation workflow；review three-way checks references + derived source + implementation。
+6. 主会话不绕过 CLI 直接写业务代码；失败只走 doctor/reconcile/human gate/重跑。
+7. DAG `pi` executor read-only unless `toolProfile: "write"`；completed run facts read-only；不得从 read-only DAG/sidecar 写 root `artifacts/`。
+8. No hidden state in chat only；verify before completion.
 
 ## References
 

package/skills/loop-agent/references/command-reference.md

@@ -162,6 +162,8 @@ loop-agent import-prd <task-id> --file ai_workspace/loop-agent/path/to-prd.md [-
 
 把用户原始 PRD **原样复制** 到 `.harness/tasks/<task-id>/source/references/`，并写入 `source/source-manifest.json`（含 SHA-256）与 `task.json.referenceDocs`。此步骤不调用模型、不改写内容。随后再写派生的 `source/需求.md` 执行契约；冲突时以 `source/references/*` 为准。
 
+`referenceDocs` 是 `{ path, name? }[]` 对象数组，不是路径字符串数组；`import-prd` 会确定性写入正确结构。
+
 ### Task Contract / operator machine surface
 
 ```bash
@@ -514,10 +516,17 @@ loop-agent knowledge query --mode search --text "keyword" --json
 agent-worker task validate <task.yaml>            # 三层校验 TaskSpec，输出 JSON
 agent-worker task explain-profile <task.yaml>     # 解释业务 type/risk -> DAG governance profile 映射
 agent-worker task validate-feature <feature-dir>  # 校验完整 feature packet 的验收、依赖、TaskSpec 和验证命令
+agent-worker feature scaffold --repo <repo-root> --template <backend-only|frontend-only|fe-with-api> \
+  --feature-id F-YYYY-NNN --title "..." \
+  [--be-path <pattern> ...] [--fe-path <pattern> ...] [--contract-path <path>] \
+  --verify-command <cmd> [--verify-command <cmd> ...] \
+  [--batch <yaml-or-json>] [--dry-run] [--json]
 agent-worker feature review --feature-dir <feature-dir> --repo <repo-root> [--json]
 agent-worker feature run --feature-dir <feature-dir> --repo <repo-root> [--dry-run] [--git-mode checkpoint] [--keep-failed-diff] [--json]
+agent-worker feature doctor --feature-dir <feature-dir> --repo <repo-root> [--json]
+agent-worker feature advance --feature-dir <feature-dir> --repo <repo-root> [--task-id <FINAL-VERIFY-id>] [--loop-agent-bin loop-agent] [--dry-run] [--apply --owner <owner>] [--json]
 agent-worker feature verify-final --feature-dir <feature-dir> --repo <repo-root> --task-id <qa-execute-id> [--json]
-agent-worker feature delivery --feature-dir <feature-dir> --repo <repo-root> --qa-evidence <path> --final-verification <path> [--waivers <path>] [--dry-run] [--json]
+agent-worker feature delivery --feature-dir <feature-dir> --repo <repo-root> [--qa-evidence <path>] [--final-verification <path>] [--waivers <path>] [--dry-run] [--json]
 agent-worker feature closeout --feature-dir <feature-dir> --repo <repo-root> [--apply --owner <owner>] [--json]
 agent-worker report metrics --repo <repo-root> --month <YYYY-MM> [--json]
 agent-worker task draft-followup <task-id> --worker-run-id <id> --feature-dir <feature-dir> --repo <repo-root> [--json]
@@ -552,12 +561,15 @@ agent-worker observe snapshot --repo <repo-root>  # 输出 GlobalSnapshot JSON
 - Worker runtime state 落在目标 repo 的 `.harness/task-pool/`（artifacts、JSONL/state、晨报、failure handoffs）。自 0.8.0 起该目录是唯一受支持的 Task Pool runtime root；旧路径不读取、不迁移、不合并、不重映射。
 - preflight 在 `new-task` 前跑 `loop-agent --version`、`inspect`、`docs-audit`、`git status --short --branch`，可选 `--check-repo`。一次夜间批处理期间不升级控制器，记录实际 `loop-agent` 版本。
 - `batch run-ready` 默认在 stderr 输出人类可读进度（批次起止、每个 task 的阶段与耗时、report 决策），stdout 只保留最终 JSON，便于管道取用；加 `--quiet` 可关闭进度。
+- `feature scaffold` 确定性生成 Feature Packet（`backend-only` / `frontend-only` / `fe-with-api`），默认 `profile: generic`，输出到 `<repo>/features/<feature-id>`；写盘前同源 `validate-feature`；`--batch` 全有或全无；不调用模型、不碰 `.harness/**`。
 - `feature review` 只读派生 Feature 状态、required AC 覆盖、阻塞、证据和唯一下一步。默认输出简洁的人类摘要，`--json` 输出 schemaVersion 1 JSON；损坏事实会显式降级，不会写 Feature Packet 或 Task Pool。
 - `feature run` 薄编排 validation、preflight、现有 run-ready、morning report、Observe snapshot 和最终 review。`--dry-run` 零写入；Git checkpoint 可用前单次最多推进一个 Ready 写任务。
 - `feature run` 遇到业务 Task 失败时仍刷新证据，但返回 `needs-action` 和非零退出码；无 Ready 是正常结果，并通过 `noReadyReason` 说明 Closed、Deliverable、AwaitingQA、NeedsAction、依赖阻塞或空 Feature。
 - `feature run --git-mode checkpoint` 是唯一 checkpoint 授权：要求 clean repo，在本地 `agent/<feature-id>` 分支按成功 Task commit；失败先保存 patch/untracked/boundary audit 再恢复 clean。默认不 commit；从不 stash/push/merge/创建远程 PR。`--keep-failed-diff` 会停止 Feature，不继续后续 Task。
+- `feature doctor` 只读诊断 Feature 交付就绪：Task Pool 状态、dirty worktree、canonical evidence / Delivery manifest 是否存在，并给出下一步命令建议（不自动修复）。
+- `feature advance`（ADR 0007）编排 `verify-final → delivery → closeout preview[/apply]`：默认 evidence 路径取自 verify-final；`--dry-run` 时 Delivery 不写盘且不 apply closeout；`--apply --owner` 在 closeout preview ready 后原子 apply。不执行实现链 Ready tasks（仍用 `feature run`）。
 - `feature verify-final` 在 clean Delivery HEAD 上复用已完成的 `qa-execute` TaskSpec 运行独立 DAG，跳过 promotion/closeout，原子生成 canonical QA aggregate 和 HEAD-bound final verification；相同 HEAD 的 canonical 成功 run 可幂等复用。
-- `feature delivery` 复用 transaction record，校验 Git history/trailers/changed files、成功 run、canonical QA/final verification 和 required AC，原子生成 manifest、coverage 与 `PR.md`；`--dry-run` 零写入。`feature closeout` 默认只读复验全部 gates，显式 `--apply --owner` 才原子写回，stale facts 或 post-validation 失败会整体回滚。
+- `feature delivery` 复用 transaction record，校验 Git history/trailers/changed files、成功 run、canonical QA/final verification 和 required AC，原子生成 manifest、coverage 与 `PR.md`；省略 evidence 路径时默认 `.harness/task-pool/evidence/<featureId>/{qa-pass,final-verification}.json`；`--dry-run` 零写入。`feature closeout` 默认只读复验全部 gates，显式 `--apply --owner` 才原子写回，stale facts 或 post-validation 失败会整体回滚。
 - `report metrics` 按 UTC 月去重投影 Feature/Failure/Follow-up/Delivery/AC/decision/recovery/boundary 指标，同时写 JSON 与 Markdown；每项保留 numerator、denominator、sampleSize 和 missingData。
 - `task draft-followup` 会按全部 failure category 生成 TaskDraft 或人工行动卡：ProductBug/TestBug/FlakyTest/DependencyFailure 可批准；EnvFailure 连续两次后才生成 ENV-CHECK；Spec/Contract/Risk/Human/Unknown 只给行动卡。人工以 `feature approve-followup --dry-run` 预览，再带非空 `--owner` 批准 TaskDraft；行动卡不能批准。批准在 staging validation 后写 TaskSpec、graph、Ready/approval/event，原失败事实不改写，并有 rename/state/approval/index/event 回滚门禁。
 - `task retry` 是失败 Task 的唯一重试入口。它会保留原有运行记录和 failure handoff，并让下一次 `batch run-ready` 使用新的 `workerRunId`；不要删除运行态文件或手动修改状态来重试。

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

@@ -124,6 +124,28 @@ On Windows, run Bash scripts through Git Bash or a configured compatible Bash. D
 
 若 `spec`、`plan` 或 DAG generation 后 source materials 变更，implementation 前 regenerate 或 revalidate plan/DAG。
 
+`task.json` 中以下字段必须是结构化对象数组，不能写成字符串数组：
+
+```json
+{
+  "referenceDocs": [
+    {
+      "name": "requirement",
+      "path": "docs/requirement.md"
+    }
+  ],
+  "verifyCommands": [
+    {
+      "label": "tests",
+      "command": "npm test",
+      "timeoutMs": 120000
+    }
+  ]
+}
+```
+
+`referenceDocs` 每项至少包含 `path`，可选 `name`；`verifyCommands` 每项至少包含 `label` 与 `command`，可选正整数 `timeoutMs`。持久化入口会在写盘前校验完整 TaskConfig，格式错误不会留下部分 `task.json`。
+
 ## Long-running loop policy
 
 `loop` 用于 long-running outer task memory：objective/context projection、round records、signals、derived events、verification summaries、closeout draft。它不是 Agent DAG 的 substitute。

package/skills/loop-agent/references/task-workflow.md

@@ -75,6 +75,11 @@ loop-agent --repo-root /path/to/target-repo <command>
 - `verifyCommands` / adapter verification settings
 - `dagFallbackReason`，仅用于记录为何某个长期 loop 缺少 DAG round evidence
 
+结构化数组字段：
+
+- `referenceDocs` 必须是 `{ path, name? }[]`，不能是路径字符串数组。
+- `verifyCommands` 必须是 `{ label, command, timeoutMs? }[]`，不能是命令字符串数组。
+
 切片形状：每个 task 应是可独立验证的垂直 tracer bullet，而不是某一层的水平批处理。Autonomy（AFK/HITL）与 governance profile（`minimal`/`standard`/`reviewed`/`supervised`）分开声明；默认 `--profile auto`。
 
 ## Verification