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

package/dist/workflows/dag/types.js

@@ -280,6 +280,37 @@ export const dagBackendTestPipelineSchema = z.enum([
     "markdown-traceability",
     "markdown-execute-html",
 ]);
+export const dagFrontendTestEvidenceValidationSchema = z.object({}).strict();
+export const dagMavenWorkspaceManifestSchema = z.object({
+    files: z.array(z.object({
+        path: z.string(),
+        size: z.number(),
+        mtimeMs: z.number(),
+    })),
+    directories: z.array(z.object({
+        path: z.string(),
+        entryNames: z.array(z.string()),
+    })),
+});
+export const dagMavenVerificationPlanSchema = z.object({
+    schemaVersion: z.number().int().positive(),
+    plannerVersion: z.string().min(1),
+    fingerprint: z.string().min(1),
+    inputDigest: z.string().min(1),
+    targets: z.array(z.object({
+        pomPath: z.string().min(1),
+        artifactId: z.string().min(1),
+        reactorRootPomPath: z.string().min(1).optional(),
+        moduleCoordinate: z.string().min(1).optional(),
+    })),
+    commandDigests: z.array(z.string()),
+    plannedCommands: z.array(z.object({
+        label: z.string(),
+        args: z.array(z.string()),
+    })),
+    workspaceManifest: dagMavenWorkspaceManifestSchema.optional(),
+    shellCommandDigests: z.array(z.string()).optional(),
+});
 export const dagShellConfigSchema = z.object({
     commands: z.array(z.string()).default([]),
     preset: dagShellPresetSchema.optional(),
@@ -293,7 +324,19 @@ export const dagShellConfigSchema = z.object({
     frontendLintBaseline: dagFrontendLintBaselineSchema.optional(),
     frontendVerificationBundle: dagFrontendVerificationBundleSchema.optional(),
     frontendReviewContext: dagFrontendReviewContextSchema.optional(),
+    frontendTestEvidenceValidation: dagFrontendTestEvidenceValidationSchema.optional(),
     backendTestPipeline: dagBackendTestPipelineSchema.optional(),
+    /** JaCoCo coverage collection for backend-test (Java services). When set, node 7 dumps coverage over TCP from a JaCoCo tcpserver agent and feeds it to the L-5 dashboard. */
+    jacocoCoverage: z.object({
+        /** JaCoCo tcpserver endpoint, e.g. "host:6300". */
+        endpoint: z.string().min(1),
+        /** Absolute path to jacococli.jar on this machine, used to convert .exec → jacoco.xml. */
+        cliJarPath: z.string().min(1),
+        /** Business package filter passed to JaCoCo includes, e.g. "com.example.*". Defaults to "*". */
+        includes: z.string().min(1).optional().default("*"),
+        /** TCP connect timeout in ms. Defaults to 5000. */
+        connectTimeoutMs: z.number().int().positive().optional().default(5000),
+    }).strict().optional(),
     verifyEvidence: dagShellVerifyEvidenceSchema.optional(),
     repairArtifactGate: dagRepairArtifactGateSchema.optional(),
     /** fail (default): any nonzero command fails the node. record: finish node FINISHED with failure facts for downstream assess/repair. */
@@ -301,6 +344,8 @@ export const dagShellConfigSchema = z.object({
     envAllowlist: z.array(z.string()).optional(),
     timeoutMs: z.number().optional(),
     cwd: z.string().optional(),
+    /** Frozen Maven verification plan; shell executor re-checks fingerprint before running. */
+    mavenVerificationPlan: dagMavenVerificationPlanSchema.optional(),
 });
 export const dagStaticConfigSchema = z.object({
     resultMarkdown: z.string().min(1),
@@ -408,6 +453,11 @@ export const dagDecisionGateSchema = z.object({
     schemaVersion: z.literal(1).optional(),
     mode: dagDecisionGateModeSchema.optional().default("record-only"),
 });
+export const dagWriterOutcomePolicySchema = z
+    .object({
+    type: z.literal("implementation-outcome-v1"),
+})
+    .strict();
 export const dagConvergenceSpecSchema = z
     .object({
     enabled: z.boolean().optional().default(false),
@@ -465,6 +515,13 @@ export const dagTaskSchema = z.object({
      * on safe read-only Pi nodes before the node becomes ERROR.
      */
     outputProtocol: dagOutputProtocolSchema.optional(),
+    /**
+     * Fail-closed outcome/diff consistency contract for bounded Pi writers.
+     * The writer must begin with IMPLEMENTATION_OUTCOME: changed,
+     * already-satisfied, or blocked; the executor checks it against the
+     * run-attributed diff.
+     */
+    writerOutcomePolicy: dagWriterOutcomePolicySchema.optional(),
     /**
      * Explicit opt-in for the deterministic project governance context resolver
      * (AGENTS.md chain + referenced code standards). Only tasks that set this

package/dist/workflows/dag/validate.js

@@ -461,10 +461,11 @@ function validateShellTaskConfig(task, spec, issues) {
         !shell.backendTestPipeline &&
         !shell.frontendPrewriteGate &&
         !shell.frontendVerificationBundle &&
-        !shell.frontendReviewContext) {
+        !shell.frontendReviewContext &&
+        !shell.frontendTestEvidenceValidation) {
         issues.push({
             type: "missing-shell-commands",
-            message: `shell task ${task.id} requires shell.preset, shell.verdictGate, shell.jsonArtifactGate, shell.backendTestPipeline, and/or non-empty shell.commands`,
+            message: `shell task ${task.id} requires a supported shell operation or non-empty shell.commands`,
         });
     }
     if (commands.some((command) => command.trim().length === 0)) {
@@ -603,6 +604,21 @@ function validateOutputProtocolTaskConfig(task, issues) {
         });
     }
 }
+function validateWriterOutcomePolicyTaskConfig(task, issues) {
+    if (task.writerOutcomePolicy === undefined)
+        return;
+    const isBoundedPiWriter = task.executor === "pi" &&
+        task.toolProfile === "write" &&
+        task.role === "implementer" &&
+        task.writePolicy === "exclusive" &&
+        (task.writeSet?.length ?? 0) > 0;
+    if (!isBoundedPiWriter) {
+        issues.push({
+            type: "invalid-writer-outcome-policy",
+            message: `task ${task.id} declares writerOutcomePolicy but is not a bounded exclusive Pi implementer writer`,
+        });
+    }
+}
 function validateDecisionGateTaskConfig(task, issues) {
     if (!task.decisionGate?.enabled) {
         return;
@@ -757,6 +773,7 @@ export function validateDagSpec(spec) {
         validateDecisionGateTaskConfig(task, issues);
         validateRetryPolicyTaskConfig(task, issues);
         validateOutputProtocolTaskConfig(task, issues);
+        validateWriterOutcomePolicyTaskConfig(task, issues);
         validateProjectGovernanceTaskConfig(task, spec, issues);
         validateFailureAwareDependsOn(task, spec, issues);
     }

package/dist/workflows/loop/actions/dag-action.js

@@ -1,6 +1,7 @@
 import path from "node:path";
 import { mkdir } from "node:fs/promises";
 import { writeLoopDagRecord } from "../../../infrastructure/harness/loop-action-store.js";
+import { getTaskPaths } from "../../../task/runtime.js";
 import { getLoopPaths } from "../paths.js";
 import { appendLoopRound } from "../rounds.js";
 import { rewriteLoopContext } from "../context.js";
@@ -26,7 +27,7 @@ export async function runLoopDagAction(repoRoot, taskId, options = {}) {
     await mkdir(dagEvidenceDir, { recursive: true });
     const dagPath = options.dagPath
         ? path.resolve(repoRoot, options.dagPath)
-        : path.join(dagEvidenceDir, `round-${round}.dag.json`);
+        : getTaskPaths(repoRoot, taskId).dagDraftPath;
     const runner = options.runner ?? resolveDefaultRunner(repoRoot);
     let generated = {};
     if (!options.dagPath) {

package/docs/architecture/dag-execution.md

@@ -128,7 +128,7 @@ decision envelope 中的 **model verdict**（`decision` / `riskLevel` 等解析
 
 - **pause → approve → resume**：`dag approve` 在 paused run 写 `human-approval.json`，将状态改回 `running` 并把目录迁回 `active/`；随后 `resumeDagRun`（`runner.ts`）要求 active lifecycle + approval artifact，并用 `prepareSkillSnapshotForContinuation` 复用 run-owned snapshot。
 - **completed 写入**：只有 runner 在终态 `persistState({ allowCompletedFactsWrite: true })`（`runner.ts`）才能写 completed 目录；该 flag 经 `completed-facts-guard.ts` 校验。
-- **显式 recovery mutation**：`dag reconcile-run`（`src/commands/dag-reconcile-run.ts`，命令层）默认仅检查；只有给出 `--action supersede|abandon` + reason，且 liveness 证明 runner 已停止时，才在原 lifecycle 写 reconciliation/state 并迁移到 `completed/`。它不是修改既有 completed history 的通用入口。Observe / status / doctor 始终只读。
+- **显式 recovery mutation**：`dag reconcile-run`（`src/commands/dag-reconcile-run.ts`，命令层）默认仅检查；只有给出 `--action supersede|abandon` + reason，且 liveness 证明 runner 已停止时，才在原 lifecycle 写 reconciliation/state 并迁移到 `completed/`。仍为 `RUNNING` 的节点保持失败语义，但以 `reconciledAt - startedAt` 补齐节点和当前 attempt 的耗时，原始状态继续冻结在 `reconciliation.json`。它不是修改既有 completed history 的通用入口。Observe / status / doctor 始终只读。
 - **status 枚举**：`DagRunState.status`；`TERMINAL_RUN_STATUSES` 判终态；`isTerminalDagRunStatus` 工具函数。
 
 ## convergence（可选、supervised）
@@ -142,6 +142,10 @@ decision envelope 中的 **model verdict**（`decision` / `riskLevel` 等解析
 
 完成声明的权威是 shell command 的新鲜 exit code 与归档输出。验证命令执行在 `src/executors/shell-executor.ts`，环境与 preset helper 在 `src/executors/shell-verification.ts`；DAG authoring 写入的 `task.shell.verifyEvidence` 元数据由 `src/workflows/dag/node-execution.ts` 复制到 `node.verifyEvidence`。model verdict、Observe 或报告都不能替代这些 shell facts。
 
+supervised 的 `soft-verify-shell` 只运行聚焦命令，明确排除无参数的 `npm test`、`npm run test` 与 `scripts/ci.sh` 等 full-suite 入口；`hard-verify-shell` 保留一次完整 final 集合。task 与 adapter 命令合并时会解包可证明安全的单命令 `bash -lc` wrapper，并以规范化 cwd、argv、env、timeout 做语义去重；`verifyEvidence.commandCount/commandLabels/commandTexts` 必须对应去重后实际执行的命令。
+
+Pi SDK 正常路径继续在内存中传递 system prompt；只有 CLI fallback / `cli-only` 才通过权限收紧的系统临时文件传给 `--append-system-prompt`，归档命令只保存占位符。transport 解析并记录真实 temp root，持有 prompt 文件句柄，并冻结 temp root、随机私有目录、固定文件名三层 identity；收口时先用句柄清空正文，三层 identity 均匹配才精确 `unlink` 文件并非递归 `rmdir` 空目录。未知 sibling、symlink/junction 或 identity 漂移都会拒绝扩大删除范围。shell 与 Pi 子进程以独立进程组启动；超时在 Windows 使用 tree termination、在 POSIX 对进程组发信号，防止 npm/Vitest/tsx 后代在节点结束后继续持有 IPC 或临时文件。
+
 ## Dynamic Workflow
 
 Dynamic Workflow 是 DAG runtime 上方的逻辑编排/编译层，**不**重写 runner：

package/docs/architecture/runtime-boundaries.md

@@ -18,6 +18,9 @@ Application layer (src/application/，逐步引入)
 Workflow runtime (src/workflows/)
   └─ DAG / Dynamic / Loop 核心执行规则；不应依赖 commands
 
+Verification planners (src/verification/)
+  └─ 生成期/执行期验证规划（如 Maven workspace 静态图与冻结计划）；纯库模块，不跑 CLI
+
 Executors (src/executors/)
   └─ Pi / Shell / Static 等受治理外部工具适配；不应依赖 commands 或 CLI formatting
 
@@ -66,11 +69,18 @@ Governance (scripts/check-*.sh, src/governance/)
 - **允许依赖**：`src/executors/**`、`src/task/**`、`src/records/**`、`src/shared/**`、application use-case（目标态）。
 - **禁止**：`import` 来自 `src/commands/**`（见下方过渡例外）。
 
+### Verification planners
+
+- **位置**：`src/verification/**`（当前含 `src/verification/maven/**`）
+- **职责**：在 DAG 生成阶段与 `verify-shell` 执行前，对任务作用域驱动的验证命令做静态规划与冻结计划复核（例如 Maven Workspace Graph、`-f/-pl/-am` 重写、`.harness/cache/` 图缓存、`verification-plan-stale`）。
+- **允许依赖**：`src/adapters/types`（`VerifyCommand`）、Node 标准库；由 `src/workflows/dag/**` 与 `src/executors/shell-executor.ts` 调用。
+- **禁止**：执行 Maven/npm 等外部 goal 做发现；依赖 `src/commands/**` 或 CLI；把独立 POM 拼成伪 reactor；按 first-match/深度/字典序/启动 cwd 选择目标。
+
 ### Executors
 
 - **位置**：`src/executors/**`
 - **职责**：封装 Pi SDK、shell 执行、static 输出与 write guard。受治理 Agent runtime 只有 Pi。
-- **允许依赖**：`src/shared/**`、外部 SDK（不含 `@cursor/sdk`）。
+- **允许依赖**：`src/shared/**`、`src/verification/**`（执行前计划复核）、外部 SDK（不含 `@cursor/sdk`）。
 - **禁止**：依赖 `src/commands/**`、CLI 输出格式，或 import `src/sidecars/**` / `@cursor/sdk`。
 
 ### Sidecars

package/docs/architecture/worker-and-feature.md

@@ -88,6 +88,8 @@ controller identity 与 DAG skill snapshot 是两个不同冻结层（前者跨
 | 入口 | 职责 |
 | --- | --- |
 | `agent-worker feature verify-final` | **唯一** canonical writer：Feature Verification Bundle、`qa-pass.json`、`final-verification.json` |
+| `agent-worker feature advance` | 编排 verify-final → delivery → closeout preview[/apply]（ADR 0007 运维入口） |
+| `agent-worker feature doctor` | 只读诊断证据/Pool/dirty worktree；建议下一步命令 |
 | Feature Packet `FINAL-VERIFY-*`（若保留） | 可选 **local smoke recipe**（样本 `verify:final` / reports）；Task Done ≠ Final Verification Record |
 | `feature delivery` | 重验 verify-final 证据；省略路径时默认 `.harness/task-pool/evidence/<featureId>/{qa-pass,final-verification}.json` |
 | `feature closeout` | 只认 Delivery manifest + Final Verification Record 链 |

package/docs/init-surface.manifest.json

@@ -55,6 +55,7 @@
     "skills/agent-worker/references/agent-worker-operator.md",
     "skills/loop-agent/SKILL.md",
     "skills/loop-agent/references/command-reference.md",
+    "skills/loop-agent/references/source-and-plan-practice.md",
     "skills/loop-agent/references/docs-converge.md",
     "skills/ai-engineering-context/SKILL.md",
     "skills/verification-before-completion/SKILL.md",
@@ -133,6 +134,7 @@
     ".agents/skills/agent-worker/references/agent-worker-operator.md",
     ".agents/skills/loop-agent/SKILL.md",
     ".agents/skills/loop-agent/references/command-reference.md",
+    ".agents/skills/loop-agent/references/source-and-plan-practice.md",
     ".agents/skills/loop-agent/references/docs-converge.md",
     ".agents/skills/ai-engineering-context/SKILL.md",
     ".agents/skills/verification-before-completion/SKILL.md",
@@ -212,6 +214,7 @@
     ".agents/skills/agent-worker/references/agent-worker-operator.md": "copied",
     ".agents/skills/loop-agent/SKILL.md": "copied",
     ".agents/skills/loop-agent/references/command-reference.md": "copied",
+    ".agents/skills/loop-agent/references/source-and-plan-practice.md": "copied",
     ".agents/skills/loop-agent/references/docs-converge.md": "copied",
     ".agents/skills/ai-engineering-context/SKILL.md": "copied",
     ".agents/skills/verification-before-completion/SKILL.md": "copied",

package/docs/templates/backend-test-dag.json

@@ -250,7 +250,7 @@
         ".harness/dag-runs/**",
         "artifacts/**"
       ],
-      "outputContract": "One scoped pytest execution over Markdown-mapped scripts producing a valid pytest-html report with per-case captured output, self-contained reports/backend-test.html and reports/backend-test.md, plus internal reports/backend-test-facts.md evidence; exit 0/1 with valid evidence continues.",
+      "outputContract": "One scoped pytest execution over Markdown-mapped scripts producing a valid pytest-html report with per-case captured output, self-contained reports/backend-test.html, reports/backend-test.md, reports/backend-test-facts.md, a deterministic self-contained reports/backend-test-l5-dashboard.html (machine-computed L-5 metrics, no JSON), and an optional contracts/code-coverage-v1.json when jacocoCoverage is configured (JaCoCo TCP dump → jacoco.xml → parsed; failure-safe); exit 0/1 with valid evidence continues.",
       "subtask_prompt": "Resolve the final Markdown Automation Notes/自动化映射 to a unique, safe set of testcase/**/test_*.py targets and execute only those scripts exactly once. Prefer the deterministic module one-to-one path when a mapped script is missing but the module stem file exists. Generate a native pytest-html self-contained report, then render the primary self-contained Chinese HTML report from the same pytest-html plus final Markdown case metadata without rerun. Keep 测试结论, quality status, failure overview, and a polished per-case result card with concise scenario, automation test name, result, duration, and redacted bounded HTTP request parameters/response results for both passed and failed cases. Do not render a technical/execution evidence section in HTML; retain auditable paths and hashes in facts.",
       "shell": {
         "commands": [
@@ -283,8 +283,8 @@
         ".harness/dag-runs/**",
         "artifacts/**"
       ],
-      "outputContract": "Final Markdown report and L-5 conclusion under docs/test-reports/**; no JSON.",
-      "subtask_prompt": "Generate the final Markdown report from upstream facts and run-owned environment, advisory case-validation, advisory traceability, pytest-html and HTML evidence. Do not emit JSON.\n\nUse this exact human-facing section order: 测试结论 → 执行概览 → 质量校验 → 失败分析 → 风险与建议 → 证据与 L-5. Put the decision and key numbers first, use compact tables/bullets, and keep headings concise. Do not paste entire upstream reports, duplicate per-case tables already present in facts, or repeat the same evidence in multiple sections; link to paths/hashes and quote only the findings needed for the conclusion.\n\nAlways state the exact PASS/FAIL status and findings from nodes 4 and 6. Their FAIL status does not block pytest, but it must remain visible as a quality/traceability risk and must never be rewritten as PASS.\n\nInclude environment, case quality/review, automation mapping, exact pytest facts, failure classification/analysis, risks, regression recommendations, evidence paths/hashes, coverage availability, and L-5 READY/NOT READY.\n\nNever override Shell/pytest-html facts. L-5 requires pass=100%, AC=100%, automation>=90%, line>=80%, branch>=70%, skipped=0 and no blocking Critical risk.\n\nWrite only under docs/test-reports/**."
+      "outputContract": "Final Markdown report and L-5 conclusion under docs/test-reports/**; the deterministic L-5 dashboard at reports/backend-test-l5-dashboard.html is the authoritative visualization and must be linked, not re-rendered; no JSON.",
+      "subtask_prompt": "Generate the final Markdown report from upstream facts and run-owned environment, advisory case-validation, advisory traceability, pytest-html and HTML evidence. Do not emit JSON.\n\nUse this exact human-facing section order: 测试结论 → 执行概览 → 质量校验 → 失败分析 → 风险与建议 → 证据与 L-5. Put the decision and key numbers first, use compact tables/bullets, and keep headings concise. Do not paste entire upstream reports, duplicate per-case tables already present in facts, or repeat the same evidence in multiple sections; link to paths/hashes and quote only the findings needed for the conclusion.\n\nThe L-5 metrics and visualization are already produced deterministically by node 7 at reports/backend-test-l5-dashboard.html (rendered from computeL5ReportMetrics). Link to that dashboard as the authoritative L-5 view; do not recompute pass/AC/automation/coverage numbers or re-render an HTML dashboard yourself. Quote its L-5 decision verbatim.\n\nAlways state the exact PASS/FAIL status and findings from nodes 4 and 6. Their FAIL status does not block pytest, but it must remain visible as a quality/traceability risk and must never be rewritten as PASS.\n\nInclude environment, case quality/review, automation mapping, exact pytest facts, failure classification/analysis, risks, regression recommendations, evidence paths/hashes, coverage availability, and L-5 READY/NOT READY.\n\nNever override Shell/pytest-html facts. L-5 requires pass=100%, AC=100%, automation>=90%, line>=80%, branch>=70%, skipped=0 and no blocking Critical risk.\n\nWrite only under docs/test-reports/**."
     }
   ],
   "sourceBinding": {

package/docs/templates/product-line/README.md

@@ -1,6 +1,22 @@
 # Product-line feature packet
 
-Copy this directory for each product feature. Replace angle-bracket placeholders, keep IDs stable, and run:
+**推荐入口（确定性脚手架）：**
+
+```bash
+agent-worker feature scaffold --repo . --template backend-only \
+  --feature-id F-2026-010 --title "..." \
+  --be-path services/example/** \
+  --verify-command "npm run typecheck" --verify-command "npm test"
+agent-worker task validate-feature features/F-2026-010
+```
+
+批量示例见 [`feature-scaffold-batch.example.yaml`](feature-scaffold-batch.example.yaml)。
+
+**生成快照（可读、防漂移，非 dogfood）**见 [`scaffold-samples/`](scaffold-samples/)：`backend-only` / `frontend-only` / `fe-with-api`。刷新：`node --import tsx/esm scripts/generate-scaffold-samples.mjs`；校验：同脚本 `--check` 或 `bash scripts/check-scaffold-samples.sh`。
+
+操作说明以 skill 包内 `skills/agent-worker/references/agent-worker-operator.md` § Feature Packet Scaffold 为准（不依赖 website 是否随包）。
+
+也可手工复制本目录占位文件，替换 angle-bracket placeholders，保持 IDs 稳定，然后运行：
 
 ```bash
 agent-worker task validate-feature <feature-dir>

package/docs/templates/product-line/feature-scaffold-batch.example.yaml

@@ -0,0 +1,31 @@
+# Example batch for: agent-worker feature scaffold --batch <this-file> --repo <repo>
+# Every feature_id must be explicit (v1 does not auto-allocate IDs).
+# Any invalid row fails the whole batch with zero writes.
+
+features:
+  - feature_id: F-2026-010
+    title: Banner 拉取欢迎语
+    template: fe-with-api
+    description: 前端 Banner 调用薄 API 展示欢迎语
+    fe_paths:
+      - apps/web/src/welcome/**
+    be_paths:
+      - services/welcome/**
+    verify_commands:
+      - npm run typecheck
+      - npm test
+    acceptance:
+      - id: AC-001
+        title: 页面展示非空 message
+        given: 欢迎语接口可用
+        when: 用户打开页面
+        then: 页面展示非空 message
+
+  - feature_id: F-2026-011
+    title: 设置页主题切换
+    template: frontend-only
+    fe_paths:
+      - apps/web/src/settings/theme/**
+    verify_commands:
+      - npm run typecheck
+      - npm test

package/docs/templates/product-line/scaffold-samples/README.md

@@ -0,0 +1,36 @@
+# Scaffold samples (generated snapshots)
+
+> **身份**：由 `agent-worker feature scaffold` **同一套 typed builders** 生成的只读快照，供人阅读与防漂移对照。  
+> **不是** 运行中的 dogfood Feature，**不是** 默认模板源（生成器仍以 `src/worker/feature/scaffold.ts` 为准）。  
+> **不要** 复制进 `features/` 当业务 Feature；日常请直接跑 `feature scaffold`。
+
+## 目录
+
+| 子目录 | 模板 | 快照 feature_id |
+| --- | --- | --- |
+| `backend-only/` | pure backend | `F-2099-901` |
+| `frontend-only/` | pure frontend | `F-2099-902` |
+| `fe-with-api/` | contract + BE + FE | `F-2099-903` |
+
+ID 使用 `F-2099-*` 号段，避免与 `features/F-2026-*` dogfood 混淆。
+
+## 刷新 / 校验
+
+```bash
+# 按当前 scaffold 实现重写本目录
+node --import tsx/esm scripts/generate-scaffold-samples.mjs
+
+# CI / 本地：快照必须与当前 builder 一致
+node --import tsx/esm scripts/generate-scaffold-samples.mjs --check
+npx vitest run test/worker/feature/scaffold-samples.test.ts
+```
+
+`scripts/check-repo.sh` 会调用 `--check`。若你改了 scaffold 模板语义，请先 generate 再提交快照。
+
+## 与真实 Packet 的关系
+
+| 路径 | 用途 |
+| --- | --- |
+| 本目录 | 文档可读快照 + 漂移门禁 |
+| `features/F-2026-*` | 仓库内真实 / dogfood Feature |
+| 用户目标仓 `features/F-YYYY-NNN/` | `feature scaffold --repo <target>` 写入处 |

package/docs/templates/product-line/scaffold-samples/backend-only/acceptance.yaml

@@ -0,0 +1,13 @@
+schema_version: 1
+feature_id: F-2099-901
+acceptance:
+  - id: AC-001
+    title: Scaffold sample — backend-only
+    priority: must
+    type: behavior
+    given: 需求与路径边界已冻结
+    when: Feature Packet 内实现任务完成
+    then: 验收目标达成且 verify.commands 通过
+    verification:
+      expected_task_refs:
+        - BE-IMPL-001

package/docs/templates/product-line/scaffold-samples/backend-only/design.md

@@ -0,0 +1,14 @@
+# Design — Scaffold sample — backend-only
+
+## Goals
+
+Generated snapshot for docs/templates/product-line/scaffold-samples. Not a live dogfood Feature.
+
+## Paths
+
+- Backend allowed paths:
+  - `services/sample-backend/**`
+
+## Artifacts
+
+- `BE-IMPL-001` produces `backend-impl`

package/docs/templates/product-line/scaffold-samples/backend-only/feature.yaml

@@ -0,0 +1,3 @@
+schema_version: 1
+feature_id: F-2099-901
+profile: generic

package/docs/templates/product-line/scaffold-samples/backend-only/requirement.md

@@ -0,0 +1,6 @@
+# Scaffold sample — backend-only
+
+Generated snapshot for docs/templates/product-line/scaffold-samples. Not a live dogfood Feature.
+
+Feature ID: `F-2099-901`
+Template: `backend-only`

package/docs/templates/product-line/scaffold-samples/backend-only/tasks/BE-IMPL-001.yaml

@@ -0,0 +1,83 @@
+schema_version: 1
+id: BE-IMPL-001
+feature_id: F-2099-901
+title: Scaffold sample — backend-only — 后端实现
+description: Generated snapshot for
+  docs/templates/product-line/scaffold-samples. Not a live dogfood Feature.
+repo:
+  name: loop-agent
+  path_ref: .
+  default_branch: main
+type: backend-feature
+priority: P2
+risk_level: medium
+depends_on: []
+source_docs:
+  requirement: ../requirement.md
+  acceptance: ../acceptance.yaml
+  design: ../design.md
+acceptance_refs:
+  - AC-001
+scope:
+  goals:
+    - 实现后端变更并满足验收
+  non_goals:
+    - 不扩展到模板外的 Task 节点（无 BE-TEST/FE-TEST/FINAL-VERIFY）
+  assumptions:
+    - verify.commands 由 scaffold 调用方显式提供
+  open_questions: []
+constraints:
+  allowed_paths:
+    - services/sample-backend/**
+    - docs/progress/F-2099-901/be/status.md
+    - docs/progress/F-2099-901/be/**
+  forbidden_paths:
+    - config/prod/**
+    - .env
+    - .env.*
+    - secrets/**
+    - apps/**
+  hard_constraints:
+    - 不读取生产密钥
+    - 不绕过 scaffold 冻结的 depends/produces/consumes
+execution:
+  workflow: agent-dag
+verify:
+  preset: standard
+  mode: serial
+  quota: full
+  commands:
+    - id: verify-1
+      label: npm run typecheck
+      command: npm run typecheck
+      required: true
+      timeout_ms: 300000
+    - id: verify-2
+      label: npm test
+      command: npm test
+      required: true
+      timeout_ms: 300000
+worker:
+  execution_mode: generate-validate-run
+  max_attempts: 1
+  timeout_ms: 7200000
+  require_clean_worktree: true
+  require_human_review: true
+  create_worktree: false
+loop_agent:
+  profile_policy: mapped
+  strict_models: true
+  strict_governance: true
+  max_concurrent: 1
+outputs:
+  required:
+    - dag_json
+    - dag_validate_json
+    - run_record
+    - dag_report_json
+    - shell_verification
+    - closeout_or_failure_handoff
+failure_policy:
+  failed_run_promote: false
+  generate_closeout_draft: true
+  create_followup_task: true

package/docs/templates/product-line/scaffold-samples/backend-only/tasks/task-graph.yaml

@@ -0,0 +1,14 @@
+schema_version: 1
+feature_id: F-2099-901
+nodes:
+  - id: BE-IMPL-001
+    task: BE-IMPL-001.yaml
+    type: backend-feature
+    depends_on: []
+    produces:
+      - kind: backend-impl
+        schemaId: backend-impl-v1
+        path: services/sample-backend
+parallel_policy:
+  max_parallel_tasks: 1
+  disallow_same_file_parallel_writes: true

package/docs/templates/product-line/scaffold-samples/fe-with-api/acceptance.yaml

@@ -0,0 +1,15 @@
+schema_version: 1
+feature_id: F-2099-903
+acceptance:
+  - id: AC-001
+    title: Scaffold sample — fe-with-api
+    priority: must
+    type: behavior
+    given: 需求与路径边界已冻结
+    when: Feature Packet 内实现任务完成
+    then: 验收目标达成且 verify.commands 通过
+    verification:
+      expected_task_refs:
+        - CONTRACT-001
+        - BE-IMPL-001
+        - FE-IMPL-001

package/docs/templates/product-line/scaffold-samples/fe-with-api/design.md

@@ -0,0 +1,18 @@
+# Design — Scaffold sample — fe-with-api
+
+## Goals
+
+Generated snapshot for docs/templates/product-line/scaffold-samples. Not a live dogfood Feature.
+
+## Paths
+
+- Backend allowed paths:
+  - `services/sample-api/**`
+- Frontend allowed paths:
+  - `apps/web/src/sample-api/**`
+- Contract path: `docs/contracts/F-2099-903/api.md`
+
+## Artifacts
+
+- `CONTRACT-001` produces `api-contract`
+- `BE-IMPL-001` / `FE-IMPL-001` consume `api-contract` (only formal consumers)

package/docs/templates/product-line/scaffold-samples/fe-with-api/feature.yaml

@@ -0,0 +1,3 @@
+schema_version: 1
+feature_id: F-2099-903
+profile: generic

package/docs/templates/product-line/scaffold-samples/fe-with-api/requirement.md

@@ -0,0 +1,6 @@
+# Scaffold sample — fe-with-api
+
+Generated snapshot for docs/templates/product-line/scaffold-samples. Not a live dogfood Feature.
+
+Feature ID: `F-2099-903`
+Template: `fe-with-api`

package/docs/templates/product-line/scaffold-samples/fe-with-api/tasks/BE-IMPL-001.yaml

@@ -0,0 +1,84 @@
+schema_version: 1
+id: BE-IMPL-001
+feature_id: F-2099-903
+title: Scaffold sample — fe-with-api — 后端实现
+description: Generated snapshot for
+  docs/templates/product-line/scaffold-samples. Not a live dogfood Feature.
+repo:
+  name: loop-agent
+  path_ref: .
+  default_branch: main
+type: backend-feature
+priority: P2
+risk_level: medium
+depends_on:
+  - CONTRACT-001
+source_docs:
+  requirement: ../requirement.md
+  acceptance: ../acceptance.yaml
+  design: ../design.md
+acceptance_refs:
+  - AC-001
+scope:
+  goals:
+    - 按契约实现后端
+  non_goals:
+    - 不扩展到模板外的 Task 节点（无 BE-TEST/FE-TEST/FINAL-VERIFY）
+  assumptions:
+    - verify.commands 由 scaffold 调用方显式提供
+  open_questions: []
+constraints:
+  allowed_paths:
+    - services/sample-api/**
+    - docs/progress/F-2099-903/be/status.md
+    - docs/progress/F-2099-903/be/**
+  forbidden_paths:
+    - config/prod/**
+    - .env
+    - .env.*
+    - secrets/**
+    - apps/**
+  hard_constraints:
+    - 不读取生产密钥
+    - 不绕过 scaffold 冻结的 depends/produces/consumes
+execution:
+  workflow: agent-dag
+verify:
+  preset: standard
+  mode: serial
+  quota: full
+  commands:
+    - id: verify-1
+      label: npm run typecheck
+      command: npm run typecheck
+      required: true
+      timeout_ms: 300000
+    - id: verify-2
+      label: npm test
+      command: npm test
+      required: true
+      timeout_ms: 300000
+worker:
+  execution_mode: generate-validate-run
+  max_attempts: 1
+  timeout_ms: 7200000
+  require_clean_worktree: true
+  require_human_review: true
+  create_worktree: false
+loop_agent:
+  profile_policy: mapped
+  strict_models: true
+  strict_governance: true
+  max_concurrent: 1
+outputs:
+  required:
+    - dag_json
+    - dag_validate_json
+    - run_record
+    - dag_report_json
+    - shell_verification
+    - closeout_or_failure_handoff
+failure_policy:
+  failed_run_promote: false
+  generate_closeout_draft: true
+  create_followup_task: true