@tea-agent/loop-agent 0.22.0 → 0.24.0

package/dist/commands/init.js

@@ -13,16 +13,20 @@ const GITIGNORE_BLOCK_END = "# LOOP_AGENT_INIT_END";
 const INIT_SURFACE_STATE_PATH = ".harness/init-surface.json";
 const DEFAULT_GOVERNANCE_ROOT = "ai_workspace/loop-agent";
 const CORE_DOC_FILES = [
-    "README.md",
-    "architecture/runtime-boundaries.md",
-    "development-principles.md",
-    "feature-workflow.md",
-    "verification-matrix.md",
-    "loop-agent-harness.md",
-    "harness-methodology-tdd.md",
-    "harness-methodology-verification.md",
-    "harness-methodology-debugging.md",
+    { source: "README.md", target: "README.md" },
+    { source: "architecture/runtime-boundaries.md", target: "architecture/runtime-boundaries.md" },
+    { source: "governance/development-principles.md", target: "development-principles.md" },
+    { source: "governance/feature-workflow.md", target: "feature-workflow.md" },
+    { source: "governance/verification-matrix.md", target: "verification-matrix.md" },
+    { source: "runtime/loop-agent-harness.md", target: "loop-agent-harness.md" },
+    { source: "governance/harness-methodology-tdd.md", target: "harness-methodology-tdd.md" },
+    { source: "governance/harness-methodology-verification.md", target: "harness-methodology-verification.md" },
+    { source: "governance/harness-methodology-debugging.md", target: "harness-methodology-debugging.md" },
+    { source: "templates/README.md", target: "templates/README.md" },
 ];
+function coreDocSourceForTarget(target) {
+    return CORE_DOC_FILES.find((entry) => entry.target === target)?.source ?? target;
+}
 const GOVERNANCE_README_DIRS = [
     "decisions",
     "design",
@@ -771,68 +775,59 @@ function buildManagedAgentsBlock(input) {
         "### 默认立场",
         "",
         "- 仓库是记录系统：决策、契约、计划、验证、报告和交接应进入可追踪文件。",
-        "- 一次只推进一个有边界、可验证的工作块。",
-        "- 实现前先搜索现有代码、文档、脚本和测试，避免重复造轮子。",
+        "- 一次只推进一个有边界、可验证的工作块；实现前先搜索现有代码、文档、脚本和测试。",
         "- Shell 验证是完成依据；模型建议不能替代命令证据。",
         "- 保留无关的用户改动，不要回退自己没有做的修改。",
         "- 委托模型写入前，必须把写入边界写成结构化 `task.json.allowedPaths` / `task.json.forbiddenPaths`，再审查生成 DAG 的 writer `writeSet`；不要只依赖 `source/执行约束.md` 的自然语言约束。",
-        "- 本仓库对 openCode 等主会话的定位是 **Compatibility / Operator Assist**：主会话编排 `loop-agent` / `agent-worker` CLI 与只读诊断，**不是**默认实现 agent。",
+        "- 本仓库对 openCode 等主会话的定位是 **Compatibility / Operator Assist**：主会话编排 CLI 与只读诊断，**不是**默认实现 agent。",
         "",
         "### 主会话硬约束（Compatibility / Operator Assist）",
         "",
-        "主会话（含 openCode、Cursor Chat、其他宿主 agent）必须遵守以下硬约束；skills 与本文件是纪律文档，**不能**替代 `task.json` / DAG `writeSet` / runtime 执法。",
+        "主会话（含 openCode、Cursor Chat、其他宿主 agent）= **operator-only**；skills 与本文件是纪律文档，**不能**替代 `task.json` / DAG `writeSet` / runtime 执法。",
         "",
         "| 类别 | 规则 |",
         "|---|---|",
-        "| **角色** | 主会话 = **operator-only**，不是 implementer。 |",
-        "| **允许** | 调用已发布 `loop-agent` / `agent-worker` CLI；只读 `status` / `dag status` / `dag doctor` / `dag report` / `inspect` / `agent-worker observe`；准备或修正任务源 `source/*` 与 `task.json` 边界；记录 human gate；跑 shell 验证与 handoff。 |",
-        "| **禁止** | 绕过 `loop-agent` / `agent-worker` CLI，用宿主 Edit/Write/ApplyPatch 等直接改业务实现；在 CLI/DAG 失败后「救火改文件」；用聊天自述代替 shell 验证完成声明。 |",
-        "| **失败时只允许** | `loop-agent dag doctor` / `dag report` / `dag reconcile-run`（及适用的 `agent-worker task reconcile` / `pool mark-failed`）；记 human gate；修正 **任务源 / task.json / DAG 包** 后 re-validate 并 **经 CLI 重跑**。 |",
-        "| **实现写入** | 业务代码与功能修复 **只** 经受治理 DAG writer（`implement-pi` / `repair-pi` 等）通过 `dag run-task` / `run-dag`（或 worker 子进程调用的同一路径）完成。 |",
+        "| **允许** | 已发布 `loop-agent` / `agent-worker` CLI；只读 status/doctor/report/inspect/observe；准备 `source/*` 与 `task.json` 边界；human gate；shell 验证与 handoff。 |",
+        "| **禁止** | 绕过 CLI 用宿主 Edit/Write/ApplyPatch 直接改业务实现；CLI/DAG 失败后「救火改文件」；用聊天自述代替 shell 验证。 |",
+        "| **失败时** | `dag doctor` / `dag report` / `dag reconcile-run`（及适用 worker reconcile）；修正任务源/`task.json`/DAG 后经 CLI 重跑。 |",
+        "| **实现写入** | 业务代码 **只** 经受治理 DAG writer（`implement-pi` / `repair-pi`）经 `dag run-task` / `run-dag`。 |",
         "",
         "**永远不要**：`loop-agent` / `agent-worker` 失败 ⇒ 主会话直接改仓库实现。",
         "",
         "### 自然语言入口路由",
         "",
-        "用户用中文表达意图时，按以下三类入口路由；只读与写入必须严格区分。",
-        "",
         "| 用户表达 | 入口 | 执行动作 |",
         "|---|---|---|",
         "| loop-agent 初始化 / loop agent 初始化 / loop agent初始化 / 初始化 loop-agent | 初始化 | 完成确定性初始化闭环 |",
         "| 初始化更新校验 / 检查初始化更新 / loop-agent 初始化更新校验 / loop agent初始化更新校验 | 更新校验 | 只读报告，不写入 |",
-        "| 初始化对齐 / 升级后对齐 / reconcile 初始化 / loop-agent 初始化对齐 | 升级对齐 | 自动应用确定性安全动作；活跃运行或人工决策时零写入 |",
-        "| 初始化安全更新 / 应用初始化更新 / loop-agent 初始化安全更新 / loop agent初始化安全更新 | 安全更新 | check-update 后只执行确定性安全动作 |",
+        "| 初始化对齐 / 升级后对齐 / reconcile 初始化 / loop-agent 初始化对齐 | 升级对齐 | 自动应用确定性安全动作；活跃 DAG/Worker 或人工决策时零写入 |",
+        "| 初始化安全更新 / 应用初始化更新 / loop-agent 初始化安全更新 / loop agent初始化安全更新 | 安全更新 | 先 check-update，再只执行确定性安全动作 |",
         "",
-        "**更新校验（只读）**：用户说“初始化更新校验”“检查初始化更新”时，只读执行下面命令，汇报 deterministic actions、model merge、human decisions 和 next steps。**这一步不得自动执行 `apply-safe` 或模型合并。**",
+        "**更新校验（只读）**：只读执行下面命令；**不得自动**执行 `apply-safe` 或模型合并。",
         "",
         "```bash",
         "loop-agent init check-update --repo-root . --markdown",
         "```",
         "",
-        "**升级对齐（写入型统一入口）**：用户说“初始化对齐”“升级后对齐”时，执行 `loop-agent init reconcile --repo-root .`。该入口不自动 bootstrap surface、不自动模型合并；存在活跃 DAG/Worker、human decisions 或无法确认 Worker 状态时必须零写入并报告状态。",
+        "**升级对齐**：`loop-agent init reconcile --repo-root .`；存在活跃 DAG/Worker、human decisions 时必须零写入。",
         "",
-        "**安全更新（写入型）**：用户明确说“初始化安全更新”“应用初始化更新”时，先 check-update，再执行确定性安全动作；surface 缺失时先 bootstrap，存在 human decisions 时停下等用户决策。model merge 任务必须带 allowed/forbidden paths，且不得自动决策。安全更新完成后必须复查 `loop-agent init doctor --repo-root .`、`loop-agent inspect --repo-root .`、`loop-agent docs audit --repo-root .` 与目标项目治理检查（如 `bash scripts/check-repo.sh`）。",
+        "**安全更新**：先 check-update，再 `apply-safe`；surface 缺失才 `--bootstrap-surface`。完成后复查 `init doctor` / `inspect` / `docs audit` 与目标治理检查。",
         "",
         "```bash",
         "loop-agent init check-update --repo-root . --markdown",
         "loop-agent init update --repo-root . --apply-safe",
         "```",
         "",
-        "仅当 check-update 报告 surface 缺失时才执行 `loop-agent init update --repo-root . --bootstrap-surface`。",
-        "",
         "### 初始化闭环",
         "",
         `当用户要求初始化 loop-agent（“初始化 loop-agent”“loop agent 初始化”“loop agent初始化”“loop-agent 初始化”），或发现 \`README.md\` / \`${input.governanceRoot}/verification-matrix.md\` 仍停留在通用初始化状态时，模型应在同一轮工作中完成初始化闭环，不要把补全文档和验证矩阵留给用户交互。`,
         "",
-        "标准流程：",
+        "1. 运行 `loop-agent init instructions --repo-root .`。",
+        "2. 运行 `loop-agent init --repo-root . --profile full --merge`。",
+        `3. 基于真实项目文件补全根 \`README.md\`、\`${input.governanceRoot}/verification-matrix.md\`，必要时适配 \`scripts/ci-tests.sh\`。`,
+        "4. 复查 `init doctor` / `inspect` / `docs audit` 与 quick verification。",
         "",
-        "1. 运行 `loop-agent init instructions --repo-root .` 获取完整初始化指引。",
-        "2. 运行 `loop-agent init --repo-root . --profile full --merge` 完成确定性脚手架。",
-        "3. 立即读取目标项目的 README、manifest/build/config 文件和顶层源码/模块目录，识别项目类型、模块、运行入口和验证命令。",
-        `4. 基于真实项目文件补全或修正根 \`README.md\`、\`${input.governanceRoot}/verification-matrix.md\`，必要时适配 \`scripts/ci-tests.sh\`。`,
-        "5. 运行 `loop-agent init doctor --repo-root .`、`loop-agent inspect --repo-root .`、`loop-agent docs audit --repo-root .` 和 quick verification。",
-        "",
-        "如果仓库信息不足，写明“尚未从仓库文件中识别到 ...”以及下一步需要的事实；不要留下泛化占位符，也不要只提示用户稍后手填。",
+        "信息不足时写明尚未识别到的事实；不要留下泛化占位符。",
         "",
         "### 文档收敛",
         "",
@@ -840,21 +835,10 @@ function buildManagedAgentsBlock(input) {
         "",
         "### 开始顺序",
         "",
-        "改文件前先完成：",
-        "",
-        "1. 运行 `pwd`。",
-        "2. 阅读 `README.md`。",
-        "3. 阅读 `harness.json`。",
-        `4. 阅读 \`${input.governanceRoot}/README.md\`。`,
-        `5. 实现类工作继续阅读 \`${input.governanceRoot}/development-principles.md\`、\`${input.governanceRoot}/feature-workflow.md\` 和 \`${input.governanceRoot}/verification-matrix.md\`。`,
-        `6. 涉及测试、验证声明或调试时继续阅读 \`${input.governanceRoot}/harness-methodology-tdd.md\`、\`${input.governanceRoot}/harness-methodology-verification.md\` 和 \`${input.governanceRoot}/harness-methodology-debugging.md\`。`,
-        "7. 查看最近提交、相关 plan/progress/report，并检查 `git status --short --branch`。",
-        "8. 运行与本次任务相关的最小基线验证。",
+        `pwd → \`README.md\` → \`harness.json\` → \`${input.governanceRoot}/README.md\` → 实现类再读 principles/feature-workflow/verification-matrix；测试纪律读 harness-methodology-*；\`git status\`；最小基线验证。`,
         "",
         "### Agent DAG 路径",
         "",
-        "默认使用 Agent DAG 作为实现工作流：",
-        "",
         "```bash",
         "loop-agent new-task <task-id> \"任务标题\"",
         "# write .harness/tasks/<task-id>/source/需求.md",
@@ -864,64 +848,40 @@ function buildManagedAgentsBlock(input) {
         "loop-agent run-dag --dag <temp-dir>/<task-id>-dag.json --cwd .",
         "```",
         "",
-        "任务 source 是必需项。`source/需求.md` 写目标、范围、非目标、验收标准和相关链接；`source/执行约束.md` 写允许路径、禁止路径、受保护变更、不变量、预期验证和失败条件。",
-        "",
-        "委托写入前，还要把允许/禁止路径同步到 `.harness/tasks/<task-id>/task.json` 的 `allowedPaths` / `forbiddenPaths` 字段，并在执行前审查生成 DAG 的 writer `writeSet` 是否窄且准确。",
+        "`source/需求.md` 与 `source/执行约束.md` 必需；写入前同步 `task.json.allowedPaths` / `task.json.forbiddenPaths` 并审查 writer `writeSet`。",
         "",
         "凡是影响项目公共契约、执行入口、交付流水线、自动化/治理、数据模型、安全或权限模型、跨模块行为、用户可见工作流的改动，都必须在编辑实现文件前先创建任务、写好两个 source 文件、生成 DAG，并审查 DAG/writeSet。",
         "",
-        "执行 DAG 前必须审查 profile routing、governance profile、writer 的 `writeSet`、`allowedPaths`、`forbiddenPaths`、shell verification 和 decision gate mode。不要执行占位或过宽的写入范围。",
-        "",
         "### 任务类型路由（taskKind）",
         "",
         "- 用户明确提出后端测试、接口/API 测试、pytest，或语境明确为后端的自动化测试时，必须把 `.harness/tasks/<task-id>/task.json` 的 `taskKind` 设置为 `\"backend-test\"`，不得保留默认 `standard`。",
-        "- `backend-test` 是 `taskKind`，不是 `--profile` 的可选值；运行 `dag run-task` 时继续使用 `--profile auto`，也可按需显式选择 `minimal` / `standard` / `reviewed` / `supervised`，不要把业务模板名当作 profile。",
+        "- `backend-test` 是 `taskKind`，不是 `--profile` 的可选值；运行 `dag run-task` 时继续使用 `--profile auto`。",
         "- 仅出现“自动化测试”且无法判断前后端时，先阅读任务源与目标项目技术栈再决定，禁止无条件路由到 `backend-test`。",
         "",
         "### 运行看板（只读）",
         "",
-        "启动统一 Operator Console（含只读 Inspect）：",
-        "",
         "```bash",
         "agent-worker console serve --repo . --port 8790",
         "```",
         "",
-        "浏览器打开 `http://127.0.0.1:8790/`；检视面为 `http://127.0.0.1:8790/inspect/`。默认绑定本机 `127.0.0.1`；可用 `--host 0.0.0.0` 做局域网访问（无网络鉴权，仅可信网络），`--debug` 输出请求日志。不要直接暴露到公开网络。`agent-worker observe serve` 仅为兼容入口。",
+        "浏览器打开 `http://127.0.0.1:8790/`；检视面为 `http://127.0.0.1:8790/inspect/`。默认绑定本机 `127.0.0.1`；不要直接暴露到公开网络。`agent-worker observe serve` 仅为兼容入口。",
         "",
         "### DAG 诊断与收口",
         "",
-        "执行后优先使用 `loop-agent dag report --run-id <run-id> --markdown` 读取 run facts；失败或 paused run 使用 `loop-agent dag doctor --run-id <run-id> --markdown` 诊断。需要生命周期对齐时用 `loop-agent dag reconcile-run --run-id <run-id>`（先只读检查，显式 action 才写入）。失败 DAG run 不应写成成功 closeout，应使用 `loop-agent dag closeout-draft --run-id <run-id>` 生成 failure handoff，保留 what failed、evidence、classification、recommended follow-up、safe retry conditions 和 human decision needed。",
+        "用 `loop-agent dag report --run-id <run-id> --markdown` 读 facts；失败/paused 用 `loop-agent dag doctor --run-id <run-id> --markdown`；生命周期对齐用 `loop-agent dag reconcile-run`。失败 run 用 `dag closeout-draft` 生成 failure handoff，不要写成成功 closeout。",
         "",
-        "失败恢复默认序列：doctor/report → classify → reconcile 或 replan → CLI 重跑 → shell verify。**禁止**把主会话直接 Edit 业务代码当作恢复手段。",
-        "",
-        "### 运行态与 Skills",
-        "",
-        "- `.harness/tasks/` 保存任务状态和 source 材料。",
-        "- `.harness/dag-runs/` 与 `.harness/runs/` 保存运行事实；已完成事实只读。",
-        "- `.agents/skills/` 保存目标项目本地 skill 指令；本地缺失时 runtime 可回退到 npm 包内置 skills。",
-        "- 示例内置在工具中；优先使用 `loop-agent examples list` 和 `loop-agent examples show <name>` 查看，不默认提交到目标仓库。",
-        "",
-        "### 验证",
-        "",
-        `使用 \`${input.governanceRoot}/verification-matrix.md\` 选择验证命令。常用门禁：`,
-        "",
-        "```bash",
-        "bash scripts/check-repo.sh",
-        "bash scripts/ci-governance.sh",
-        "bash scripts/ci-tests.sh",
-        "bash scripts/ci.sh",
-        "loop-agent inspect",
-        "loop-agent doctor",
-        "loop-agent docs audit",
-        "```",
+        "恢复：doctor/report → classify → reconcile/replan → CLI 重跑 → shell verify。**禁止**把主会话直接 Edit 业务代码当作恢复手段。",
         "",
-        "`scripts/ci-tests.sh` 必须反映目标项目真实语言和工具链。初始化生成版本会保守探测常见入口；当已知项目专属命令时，应按目标项目实际情况适配。",
+        "### 运行态与验证",
         "",
-        "Windows 上运行 `scripts/*.sh` 时使用 Git Bash 或兼容 Bash。实际文件操作使用平台原生路径；`/` 仅用于稳定仓库引用、Markdown/JSON 证据引用和 glob 约定。",
+        "- `.harness/tasks/`、`.harness/dag-runs/`、`.harness/runs/` 保存运行事实；已完成事实只读。",
+        "- `.agents/skills/` 为本地 skills；缺失时可回退 npm 包内置。",
+        `- 验证命令选择：\`${input.governanceRoot}/verification-matrix.md\`。常用：\`bash scripts/check-repo.sh\`、\`bash scripts/ci.sh\`、\`loop-agent inspect\`、\`loop-agent doctor\`、\`loop-agent docs audit\`。`,
+        "- `scripts/ci-tests.sh` 必须反映目标项目真实工具链。Windows 脚本用 Git Bash；仓库引用用 `/`。",
         "",
         "### 交接",
         "",
-        `较大的交接应说明改了什么、为什么这样改、验证命令和结果、影响到的 docs/tests/scripts/contracts、剩余风险和下一步。长期结论应进入 \`${input.governanceRoot}/progress\`、\`${input.governanceRoot}/reports\`、\`${input.governanceRoot}/exec-plans\`、\`${input.governanceRoot}/decisions\`、测试、脚本或模板。`,
+        `交接写清变更、原因、验证证据、影响面、风险与下一步；长期结论进入 \`${input.governanceRoot}/progress\`、reports、exec-plans、decisions。`,
         MANAGED_BLOCK_END,
     ].join("\n");
 }
@@ -1373,6 +1333,10 @@ async function buildDesiredSurfaceContent(input) {
         });
         if (generated !== undefined)
             return { content: generated };
+        const mappedSourcePath = path.join(input.assetRoot, "docs", coreDocSourceForTarget(doc));
+        if (await exists(mappedSourcePath)) {
+            return { content: await readFile(mappedSourcePath, "utf-8"), sourcePath: mappedSourcePath };
+        }
     }
     const sourcePath = path.join(input.assetRoot, manifestPath);
     if (await exists(sourcePath))
@@ -1582,6 +1546,10 @@ async function expectedLegacyInitFileSha(input) {
     if (!input.legacyPath.startsWith("docs/") && !input.legacyPath.startsWith("skills/")) {
         return undefined;
     }
+    if (input.legacyPath.startsWith("docs/")) {
+        const doc = input.legacyPath.slice("docs/".length);
+        return fileSha256IfExists(path.join(input.assetRoot, "docs", coreDocSourceForTarget(doc)));
+    }
     return fileSha256IfExists(path.join(input.assetRoot, input.legacyPath));
 }
 function collectSafeRetiredDirectories(paths) {
@@ -1912,6 +1880,7 @@ function buildTargetDocsReadme(input) {
         "- `progress/README.md` - 进度交接日志 / progress handoff logs",
         "- `reports/README.md` - 验证与审计报告 / verification and audit reports",
         "- `decisions/README.md` - 架构决策 / architecture decisions",
+        "- `templates/README.md` - 模板入口与类别说明 / template entrypoint and category guide",
         "- `templates/` - 可复用的计划、报告与 DAG 模板 / reusable planning, reporting, and DAG templates",
         "- `templates/production-readiness-checklist.md` - 低/中风险单仓库 DAG 任务的 production readiness 检查清单 / production readiness checklist for low/medium-risk single-repo DAG work",
         "- `templates/worker-dogfood-setup.md` - 发布控制器下的真实 Worker sample setup / real Worker sample setup with a published controller",
@@ -2016,10 +1985,34 @@ function buildTargetDevelopmentPrinciples(input) {
         "9. Do not add placeholders as completed implementation.",
         "10. Prefer existing local project patterns before adding new abstractions.",
         "",
+        "## Task Slicing: Vertical Tracer Bullets First",
+        "",
+        "Principle 1 covers **granularity** (one bounded block). This section covers **shape**: each slice should cross the real integration layers the work needs and leave an independently verifiable narrow loop.",
+        "",
+        "- Every slice needs its own acceptance criteria, verification commands, and failure conditions.",
+        "- Prefer vertical tracer bullets over horizontal layering. Paths like \"schema → API → UI → tests\" are *possible* examples only; do not assume every project has those layers.",
+        "- Horizontal anti-patterns: finish all of one layer before the next; or write every test first, then implement everything.",
+        "- For behavior changes, use one failing test → minimal implementation → green → next behavior. Do not batch all RED then all GREEN.",
+        "- Split large features into multiple independently runnable tasks/DAGs instead of one oversized writer across every layer.",
+        "",
+        "### Autonomy vs Governance (independent layers)",
+        "",
+        "| Dimension | Meaning | How to decide |",
+        "|---|---|---|",
+        "| Autonomy | Whether the slice needs synchronous human judgment, external access, or non-automatable decisions | Declare AFK/HITL in Contract, open questions, or human gate signals |",
+        "| Governance | How strong review, repair, write-set, and verification gates must be | Default `--profile auto`; route to `minimal` / `standard` / `reviewed` / `supervised` by risk and delivery signals |",
+        "",
+        "- AFK does not mean `minimal` is required; ordinary automatable work may land on `standard` or `reviewed`.",
+        "- HITL does not mean choosing `supervised` alone yields a correct human decision; require a concrete pause reason / decision gate.",
+        "- Use `minimal` only for a single narrow writer, deterministic post shell verification, and no escalation signals.",
+        "- High-risk, public-contract, init/runtime/CI/governance surface, or real human judgment gates should escalate via `auto`, or explicitly choose `reviewed` / `supervised`.",
+        "",
         "## Target Project Adaptation",
         "",
         "The initialized scripts provide language-neutral governance. The initialization model should adapt project-specific verification commands after reading the target project's actual files and toolchain.",
         "",
+        "Repo-local skills live under `.agents/skills/` (mirrored from the package `skills/` fallback).",
+        "",
     ].join("\n");
 }
 function buildTargetFeatureWorkflow(input) {
@@ -2202,6 +2195,28 @@ function buildGovernanceDirectoryReadme(input) {
         .split("/")
         .map((part) => part.replace(/-/g, " "))
         .join(" / ");
+    if (input.dir === "decisions" || input.dir.endsWith("/decisions")) {
+        return [
+            `# ${title}`,
+            "",
+            `This directory stores ${input.projectName} architecture decision records (ADRs).`,
+            "",
+            "## When to write an ADR",
+            "",
+            "Write an ADR only when **all three** are true:",
+            "",
+            "1. **Hard to reverse** — changing the decision later has meaningful cost.",
+            "2. **Surprising without context** — a future reader will ask why this path was chosen.",
+            "3. **Real trade-off** — genuine alternatives existed and one was chosen for specific reasons.",
+            "",
+            "If any condition is missing, skip the ADR. Temporary scheduling, obvious implementation choices, and facts with no alternatives do not belong here.",
+            "",
+            "Use the ADR template under this governance root's `templates/adr.md` (or the package template when projecting). Update this README index when adding a new ADR.",
+            "",
+            "初始化只创建目录契约，不复制 loop-agent 源仓库的历史决策正文。目标项目中的具体 ADR 应由后续任务按真实取舍生成。",
+            "",
+        ].join("\n");
+    }
     return [
         `# ${title}`,
         "",
@@ -2347,11 +2362,11 @@ export async function initializeLoopAgentProject(options) {
         skipped,
     });
     for (const doc of CORE_DOC_FILES) {
-        const generated = buildGeneratedCoreDoc({ doc, projectName, governanceRoot });
+        const generated = buildGeneratedCoreDoc({ doc: doc.target, projectName, governanceRoot });
         if (generated) {
             await writeTextIfMissing({
                 repoRoot,
-                relativePath: path.join(governanceRoot, doc),
+                relativePath: path.join(governanceRoot, doc.target),
                 content: generated,
                 merge,
                 written,
@@ -2362,8 +2377,8 @@ export async function initializeLoopAgentProject(options) {
         await copyFileIfMissing({
             assetRoot,
             repoRoot,
-            sourceRelativePath: path.join("docs", doc),
-            targetRelativePath: path.join(governanceRoot, doc),
+            sourceRelativePath: path.join("docs", doc.source),
+            targetRelativePath: path.join(governanceRoot, doc.target),
             merge,
             written,
             skipped,

package/dist/commands/stats.js

@@ -1,5 +1,6 @@
-import { readFile, readdir } from 'node:fs/promises';
-import path from 'node:path';
+import { readFile, readdir } from "node:fs/promises";
+import path from "node:path";
+import { buildContextUsageReport, formatContextUsageReportHuman, parseStatsContextArgs, } from "../application/context-usage/skill-resolution-stats.js";
 function percentile(values, p) {
     if (values.length === 0)
         return null;
@@ -12,8 +13,8 @@ function formatMs(ms) {
         return `${(ms / 60_000).toFixed(1)} min`;
     return `${(ms / 1_000).toFixed(1)}s`;
 }
-export async function runStats(repoRoot) {
-    const tasksDir = path.join(repoRoot, '.harness', 'tasks');
+async function runLegacyStepStats(repoRoot) {
+    const tasksDir = path.join(repoRoot, ".harness", "tasks");
     const stepRecords = {};
     let taskDirs = [];
     try {
@@ -21,20 +22,20 @@ export async function runStats(repoRoot) {
         taskDirs = entries.filter((e) => e.isDirectory()).map((e) => e.name);
     }
     catch {
-        console.log('no task directories found');
+        console.log("no task directories found");
         return;
     }
     for (const taskId of taskDirs) {
-        const jsonlPath = path.join(tasksDir, taskId, 'logs', 'executor.jsonl');
+        const jsonlPath = path.join(tasksDir, taskId, "logs", "executor.jsonl");
         try {
-            const content = await readFile(jsonlPath, 'utf-8');
+            const content = await readFile(jsonlPath, "utf-8");
             for (const line of content.split(/\r?\n/)) {
                 const trimmed = line.trim();
                 if (!trimmed)
                     continue;
                 try {
                     const record = JSON.parse(trimmed);
-                    if (typeof record.step === 'string' && typeof record.durationMs === 'number') {
+                    if (typeof record.step === "string" && typeof record.durationMs === "number") {
                         const step = record.step;
                         if (!stepRecords[step])
                             stepRecords[step] = [];
@@ -55,7 +56,7 @@ export async function runStats(repoRoot) {
             // skip missing executor.jsonl
         }
     }
-    const stepOrder = ['analyze', 'plan', 'spec', 'implement', 'verify', 'retrospective'];
+    const stepOrder = ["analyze", "plan", "spec", "implement", "verify", "retrospective"];
     let totalRecords = 0;
     let totalTimedOut = 0;
     for (const step of stepOrder) {
@@ -75,10 +76,38 @@ export async function runStats(repoRoot) {
         console.log(`  max    : ${formatMs(Math.max(...durations))}`);
         if (timedOutCount > 0)
             console.log(`  timedOut: ${timedOutCount}`);
-        console.log('');
+        console.log("");
     }
-    console.log(`${'='.repeat(40)}`);
+    console.log(`${"=".repeat(40)}`);
     console.log(`total runs: ${totalRecords}`);
     if (totalTimedOut > 0)
         console.log(`total timed out: ${totalTimedOut}`);
 }
+async function runContextStats(repoRoot, args) {
+    const parsed = parseStatsContextArgs(args);
+    const report = await buildContextUsageReport(repoRoot, { last: parsed.last });
+    if (parsed.json) {
+        process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+    }
+    else {
+        console.log(formatContextUsageReportHuman(report));
+    }
+    if (!report.ok)
+        process.exitCode = 1;
+}
+/**
+ * `stats` — legacy step-duration histogram (default, no subcommand).
+ * `stats context [--last N] [--json]` — skill-resolution / outcome telemetry.
+ */
+export async function runStats(repoRoot, args = []) {
+    const [subcommand, ...rest] = args;
+    if (subcommand === undefined) {
+        await runLegacyStepStats(repoRoot);
+        return;
+    }
+    if (subcommand === "context") {
+        await runContextStats(repoRoot, rest);
+        return;
+    }
+    throw new Error(`unknown stats subcommand: ${subcommand}\nusage: stats | stats context [--last <n>] [--json]`);
+}

package/dist/executors/shell-executor.js

@@ -17,7 +17,7 @@ import { formatFrontendReviewContextStdout, runFrontendReviewContextGate, } from
 import { materializeFrontendLintAssessment, materializeFrontendLintBaseline, } from "../workflows/dag/frontend-lint-baseline.js";
 import { formatTraceabilityGateStdout, materializeBackendTestCaseManifest, runBackendTestTraceabilityGate, } from "../workflows/dag/backend-test-case-manifest.js";
 import { materializeBackendTestExecutionContract } from "../workflows/dag/backend-test-execution-contract.js";
-import { materializeBackendTestResultFromRunDir, parseJunitXml } from "../workflows/dag/backend-test-result-contract.js";
+import { materializeBackendTestResultFromRunDir, parsePytestHtmlReport } from "../workflows/dag/backend-test-result-contract.js";
 import { collectBackendTestHumanCaseCatalog, collectBackendTestMappedPytestScripts, hasBlockingBackendMarkdownSafetyFindings, inspectBackendTestEnvironment, requiredBackendMarkdownCaseAcIds, renderBackendTestFacts, renderBackendTestHtml, redactBackendTestOutput, validateBackendMarkdownCases, validateBackendMarkdownTraceability, writeRunReport, } from "../workflows/dag/backend-test-markdown-workflow.js";
 import { buildBackendTestCanonicalResultFromInitialShellSnippet, materializeBackendTestClassification, } from "../workflows/dag/backend-test-classification-contract.js";
 import { backendTestSemanticReviewSchema, materializeBackendTestSemanticReview, } from "../workflows/dag/backend-test-semantic-review-contract.js";
@@ -102,7 +102,12 @@ export async function executeShellCommand(input) {
         const startedAt = Date.now();
         const injectedEnv = input.dagRunMeta
             ? {
-                HARNESS_DAG_RUN_DIR: input.dagRunMeta.runDir,
+                // Git Bash treats backslashes as escape characters inside double
+                // quotes. On Windows, path.join() produces backslash runDirs like
+                // D:\\...\\active\\<runId>, which corrupt "${HARNESS_DAG_RUN_DIR}/..."
+                // expansions. Normalize to POSIX separators so bash sees a stable
+                // path regardless of host platform.
+                HARNESS_DAG_RUN_DIR: input.dagRunMeta.runDir.replaceAll(path.sep, "/"),
                 HARNESS_DAG_RUN_ID: input.dagRunMeta.runId,
             }
             : undefined;
@@ -384,10 +389,18 @@ async function executeBackendTestPipeline(input, meta) {
                 'mkdir -p "${HARNESS_DAG_RUN_DIR}/reports"',
                 'PYTHON_BIN="$(command -v python || command -v python3 || true)"',
                 'if [ -z "${PYTHON_BIN}" ]; then echo "python/python3 is required for backend-test execution" >&2; exit 127; fi',
-                `PYTHONUTF8=1 PYTHONIOENCODING=utf-8 PYTHONDONTWRITEBYTECODE=1 "\${PYTHON_BIN}" -m pytest ${pytestTargets} -v -p no:cacheprovider -o junit_logging=all -o junit_log_passing_tests=true --junitxml="\${HARNESS_DAG_RUN_DIR}/reports/backend-test.junit.xml"`,
+                // Run pytest exactly once and emit the native pytest-html
+                // self-contained report. The HTML/facts renderers read per-case
+                // captured stdout (HTTP_REQUEST/HTTP_RESPONSE) directly from the
+                // pytest-html data-jsonblob island, so a JUnit XML report is no
+                // longer generated.
+                `PYTHONUTF8=1 PYTHONIOENCODING=utf-8 PYTHONDONTWRITEBYTECODE=1 "\${PYTHON_BIN}" -m pytest ${pytestTargets} -v -p no:cacheprovider --html="\${HARNESS_DAG_RUN_DIR}/reports/backend-test.html" --self-contained-html`,
                 "STATUS=$?",
                 'printf "%s" "${STATUS}" > "${HARNESS_DAG_RUN_DIR}/reports/backend-test-pytest-exit.txt"',
-                'if { [ "${STATUS}" -eq 0 ] || [ "${STATUS}" -eq 1 ]; } && [ -s "${HARNESS_DAG_RUN_DIR}/reports/backend-test.junit.xml" ]; then exit 0; fi',
+                // exit 0 (all pass) or 1 (assertion failures) with a valid
+                // pytest-html report are reportable; collection errors / crashes
+                // (exit >= 2) or a missing report surface as a pipeline error below.
+                'if { [ "${STATUS}" -eq 0 ] || [ "${STATUS}" -eq 1 ]; } && [ -s "${HARNESS_DAG_RUN_DIR}/reports/backend-test.html" ]; then exit 0; fi',
                 'exit "${STATUS}"',
             ].join("; ");
             const results = await executePipelineCommands(input, meta, [pytestCommand]);
@@ -396,11 +409,11 @@ async function executeBackendTestPipeline(input, meta) {
                 return { ok: false, stdout: results.map((result) => result.stdout).join("\n"), stderr: failure.stderr, failureCategory: failure.failureCategory, durationMs: Date.now() - started };
             }
             const reportsDir = path.join(meta.runDir, "reports");
-            const junitContent = await readFile(path.join(reportsDir, "backend-test.junit.xml"), "utf8");
+            const pytestHtmlContent = await readFile(path.join(reportsDir, "backend-test.html"), "utf8");
             const pytestExitCode = Number.parseInt((await readFile(path.join(reportsDir, "backend-test-pytest-exit.txt"), "utf8")).trim(), 10);
             if (![0, 1].includes(pytestExitCode))
                 throw new Error(`pytest did not complete with a reportable exit code: ${pytestExitCode}`);
-            const parsed = parseJunitXml(junitContent);
+            const parsed = parsePytestHtmlReport(pytestHtmlContent);
             const cases = await collectBackendTestHumanCaseCatalog(input.cwd);
             const caseValidationSummary = await readRequiredRunReport(reportsDir, "backend-md-case-validation.md");
             const traceabilitySummary = await readRequiredRunReport(reportsDir, "backend-test-traceability.md");
@@ -413,7 +426,7 @@ async function executeBackendTestPipeline(input, meta) {
                 traceabilitySummary,
             });
             const htmlPath = await writeRunReport(meta.runDir, "backend-test.html", htmlContent);
-            const facts = renderBackendTestFacts({ parsed, cases, pytestExitCode, junitRelativePath: "reports/backend-test.junit.xml", htmlRelativePath: "reports/backend-test.html", junitContent, htmlContent, caseValidationSummary, traceabilitySummary });
+            const facts = renderBackendTestFacts({ parsed, cases, pytestExitCode, htmlRelativePath: "reports/backend-test.html", htmlContent, caseValidationSummary, traceabilitySummary });
             const markdownPath = await writeRunReport(meta.runDir, "backend-test.md", facts);
             const factsPath = await writeRunReport(meta.runDir, "backend-test-facts.md", facts);
             const sanitizedOutputs = results.map((result) => redactBackendTestOutput(result.stdout));