@tea-agent/loop-agent 0.24.10 → 0.25.0

package/skills/frontend-implementation/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: frontend-implementation
 description: >-
-  Use for frontend contract, scout, mock strategy, plan, and implementation DAG nodes.
+  Use for frontend contract, scout, mock strategy, and plan DAG nodes.
 references:
   - path: references/node-contracts.md
     required: true
@@ -29,12 +29,8 @@ rules, commands, or retrievals. Scout/planners locate and explicitly read applic
 specs; only successful paired reads count. Lockfile-only, fixture-only, or unread
 search hits do not prove a reusable Mock service.
 
-This broad discovery rule applies only to contract, scout, and plan phases. For
-`frontend-implement-pi`, the run-owned
-`contracts/frontend-implementation-contract.json` is the approved semantic input;
-do not repeat task-source, OpenSpec, AI workspace, plan, or repository-wide
-discovery. For `frontend-repair-pi`, consume that contract plus
-`contracts/frontend-repair-assessment.json` and make only the bounded repair.
+This broad discovery rule applies only to contract, scout, and plan phases.
+Implementation and repair use the separate `frontend-bounded-implement` skill.
 
 ## Implementation Discipline
 

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

@@ -6,9 +6,9 @@ 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 → 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. 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-implement-pi`**: sole exclusive writer. 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. Output changed files, behavior, UI states, styling notes, verification attempted, residual risks. 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.
+- **`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