@tea-agent/loop-agent 0.1.0-fe-test.0

package/skills/grill-with-docs/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: grill-with-docs
+description: >-
+  Grilling session that challenges a plan against the existing domain model,
+  sharpens terminology, and proposes CONTEXT.md / ADR updates as decisions
+  crystallise. Use when the user wants to stress-test a plan against project
+  language and documented decisions. Explicit interactive operator skill only —
+  not a default DAG role.
+references:
+  - path: context-format.md
+    required: true
+  - path: adr-format.md
+    required: true
+---
+
+# Grill With Docs
+
+显式交互式 operator skill。用于压力测试计划与术语；**不**加入默认 planner / reviewer / implementer role mapping，避免普通 DAG 被问答阻塞。
+
+## What to do
+
+Interview the user relentlessly about every aspect of the plan until shared understanding. Walk each design branch, resolve decision dependencies one-by-one. For each question, provide a recommended answer.
+
+Ask questions one at a time; wait for feedback before continuing.
+
+If a question can be answered by exploring the codebase, explore the codebase instead.
+
+## Path resolution
+
+1. Read `harness.json.governanceRoot`（缺省时常见为源码仓库 `docs`，目标项目 `ai_workspace/loop-agent`）。
+2. Decisions 目录 = `${governanceRoot}/decisions/`（本仓库即 `docs/decisions/`）。
+3. Glossary = 仓库根 `CONTEXT.md`（多 context 时见 `CONTEXT-MAP.md`）。
+4. **禁止**硬编码平行 `adr/` 目录树；只用 `${governanceRoot}/decisions/`。
+
+## Write boundary
+
+- Inline 更新 `CONTEXT.md` / ADR **必须**服从当前 task `allowedPaths` 与 DAG `writeSet`。
+- 无写权限时：只返回建议与待确认 patch，**不得**越界写文档。
+- 不得绕过 human gate、write guard 或 shell completion authority。
+
+## During the session
+
+### Challenge against the glossary
+
+术语与 `CONTEXT.md` 冲突时立即指出。
+
+### Sharpen fuzzy language
+
+模糊或过载词要提出规范术语。
+
+### Discuss concrete scenarios
+
+用具体场景压力测试边界。
+
+### Cross-reference with code
+
+声称与代码不符时立即表面矛盾。
+
+### Update CONTEXT.md only when allowed
+
+术语敲定后，若有写权限则按 `context-format.md` 立刻更新；否则只给出建议 patch。
+
+`CONTEXT.md` 是 glossary 且仅是 glossary：不含实现细节、规格草稿、计划状态或架构决策。
+
+### Offer ADRs sparingly
+
+仅当三条同时成立才提议 ADR：
+
+1. **Hard to reverse** — 改变成本可观
+2. **Surprising without context** — 未来读者会追问 why
+3. **Real trade-off** — 曾有合理备选并基于具体理由选择
+
+缺一则跳过。格式遵循目标仓库已有模板（见 `adr-format.md`），本仓库使用完整 `docs/templates/adr.md` 字段，不用单段极简 ADR 覆盖本地约定。
+
+## Supporting formats
+
+Required references（已进入 skill snapshot）：
+
+- `context-format.md`
+- `adr-format.md`

package/skills/grill-with-docs/adr-format.md

@@ -0,0 +1,58 @@
+# ADR Format
+
+ADRs live under `${harness.json.governanceRoot}/decisions/`（源码仓库通常为 `docs/decisions/`；普通初始化目标项目通常为 `ai_workspace/loop-agent/decisions/`）。
+
+Do **not** create a parallel `adr/` tree. Use `decisions/` under the governance root only.
+
+Create the decisions directory lazily — only when the first ADR is needed and write permission exists.
+
+## Template
+
+Follow the **target repository's existing ADR template**. In the loop-agent source repo that is `docs/templates/adr.md` with full sections:
+
+- 标题 / 状态
+- 背景
+- 决策
+- 备选方案
+- 取舍理由
+- 影响范围
+- 后果（正面 / 负面）
+- 验证与落地
+- 复审条件
+
+Do not replace a full local template with a one-paragraph mini-ADR.
+
+Target projects may ship a copy of the template under their governance `templates/` directory; use that when present.
+
+## Numbering
+
+Scan the decisions directory for the highest existing `NNNN-*.md` number and increment by one. Update the decisions README index when one exists.
+
+## When to offer an ADR
+
+All three must be true:
+
+1. **Hard to reverse** — the cost of changing your mind later is meaningful
+2. **Surprising without context** — a future reader will wonder why this path was chosen
+3. **The result of a real trade-off** — genuine alternatives existed and one was chosen for specific reasons
+
+If any is missing, skip the ADR.
+
+### What qualifies
+
+- Architectural shape and integration patterns between contexts
+- Technology choices that carry lock-in
+- Boundary and scope decisions (explicit no-es included)
+- Deliberate deviations from the obvious path
+- Constraints not visible in the code
+- Rejected alternatives when the rejection is non-obvious
+
+### What does not
+
+- Temporary scheduling
+- Obvious implementation choices with no alternatives
+- Facts that belong in code, tests, or progress/report artifacts
+
+## Write boundary
+
+Only create or edit ADR files when the current task `allowedPaths` / DAG `writeSet` allow it. Otherwise return a suggested patch for human or writer follow-up.

package/skills/grill-with-docs/context-format.md

@@ -0,0 +1,52 @@
+# CONTEXT.md Format
+
+## Structure
+
+```md
+# {Context Name}
+
+{One or two sentence description of what this context is and why it exists.}
+
+## 使用说明（optional but recommended）
+
+- CONTEXT.md is a glossary and nothing else.
+- Do not store implementation details, draft specs, plan status, or architecture decisions.
+
+## 术语 / Language
+
+**Order**:
+{A one or two sentence description of the term}
+_Avoid_: Purchase, transaction
+
+**Invoice**:
+A request for payment sent to a customer after delivery.
+_Avoid_: Bill, payment request
+```
+
+Prefer the target repository's existing heading style（本仓库使用「术语」与 `_避免_`）。
+
+## Rules
+
+- **Be opinionated.** When multiple words exist for the same concept, pick the best one and list the others under `_Avoid_` / `_避免_`.
+- **Keep definitions tight.** One or two sentences max. Define what it IS, not what it does.
+- **Glossary only.** No implementation details, specs, plan status, or ADRs.
+- **Only include terms specific to this project's context.** General programming concepts do not belong.
+- **Group terms under subheadings** when natural clusters emerge.
+
+## Single vs multi-context repos
+
+**Single context (most repos):** One `CONTEXT.md` at the repo root.
+
+**Multiple contexts:** A `CONTEXT-MAP.md` at the repo root lists the contexts, where they live, and how they relate.
+
+The skill infers which structure applies:
+
+- If `CONTEXT-MAP.md` exists, read it to find contexts
+- If only a root `CONTEXT.md` exists, single context
+- If neither exists, propose a root `CONTEXT.md` lazily when the first term is resolved — create only when write permission exists
+
+When multiple contexts exist, infer which one the current topic relates to. If unclear, ask.
+
+## Write boundary
+
+Only edit `CONTEXT.md` when current task `allowedPaths` / DAG `writeSet` allow it. Otherwise return a suggested patch.

package/skills/init-capability-evolution/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: init-capability-evolution
+description: 用于 loop-agent 本仓库的初始化能力演化审查，判断代码、skill、模板、包范围或 DAG 默认能力变化是否需要同步更新目标项目 init surface。
+---
+
+# Init Capability Evolution
+
+本 skill 用于 loop-agent 本仓库。当变更可能影响 `loop-agent init` 初始化其他项目的能力时使用。
+
+## Goal
+
+让模型自行判断并维护初始化能力，而不是依赖人工记忆：
+
+- 新能力是否应该进入目标项目。
+- 新增/修改的 skill 是否应随 npm 包和 `init --profile full` 投影。
+- 目标项目的 `AGENTS.md`、README managed block、治理 docs、scripts 或 templates 是否需要更新。
+- `package.json files` 与 `ai_workspace/loop-agent/init-surface.manifest.json` 是否仍覆盖真实发布范围。
+- 是否需要目标项目 smoke、init doctor、docs audit 或 package dry-run 证据。
+
+## Trigger Tiers
+
+按 `ai_workspace/loop-agent/init-surface.manifest.json` 的 `evolutionReview.tiers` 判断成本：
+
+- `advisory`：只记录提示，不阻塞。
+- `surface-check`：运行 `bash scripts/check-init-surface.sh`；通过即可。
+- `model-review`：写一份简短 init evolution review，必要时修改 init surface、包范围、文档、skill 或测试。
+
+不要把小改动升级成重流程。只有当变化可能改变目标项目初始化体验、默认 DAG 行为、skill resolution、发布包边界或 init 生成物时，才进入 model-review。
+
+## Review Questions
+
+审查时逐条回答：
+
+1. 本次变更会改变目标项目执行 `loop-agent init --profile full --merge` 后得到的文件、规则或能力吗？
+2. 是否新增、删除或重命名了 `.agents/skills/**`，并且目标项目需要 repo-local 可审计副本？
+3. 是否改变了默认 DAG role skills、skill resolution、strict skill audit 或 task prompt 注入？
+4. 是否新增通用治理模板、script matrix、production readiness 或 operator recovery 文档，需要目标项目初始化后可见？
+5. `package.json files` 是否包含所有 npm 运行和初始化所需静态资料？
+6. `ai_workspace/loop-agent/init-surface.manifest.json` 是否更新了 package / init / exclude / trigger contract？
+7. 旧目标项目是否只需 advisory、需要手工复制新增文件，还是需要未来 `init audit/update` 迁移能力？
+
+## Output
+
+轻量审查可以只在 handoff 中说明。高影响审查应写入：
+
+```text
+ai_workspace/loop-agent/reports/init-evolution/YYYY-MM-DD-init-evolution-review.md
+```
+
+报告保持短小，包含：
+
+- changed surface
+- 可由 Git 解析的 Base 和 Head commit/ref；严格检查要求 Base 精确匹配所选 `--base`，Head 可以是运行时当前 `HEAD` 或它的一个可解析祖先提交。若 Head 是祖先，则 `reportHead..HEAD` 区间内一旦出现新的 `model-review` 高影响路径就会拒绝该报告；仅有 `advisory` 或 `surface-check` 变化不会让已完成的高影响审查失效。`working tree`、不可解析文字、无关历史报告都不能为其他变更范围放行严格检查。
+- decision: no init impact / surface check only / init update required
+- files updated
+- verification commands and results
+- residual risk
+
+## Required Verification
+
+按影响面选择最小命令：
+
+```bash
+bash scripts/check-init-surface.sh
+bash scripts/check-repo.sh
+npm test -- init-command dag-skills dag-validate-command
+npm pack --dry-run --ignore-scripts
+```
+
+如果没有新鲜验证证据，不要宣称 init evolution 已完成。

package/skills/local-jacoco-coverage/SKILL.md

@@ -0,0 +1,281 @@
+---
+name: local-jacoco-coverage
+description: >-
+  本地对 Java 后端服务做代码覆盖率检测与分析的端到端编排 skill。在本地或测试环境启动后端服务并挂载 JaCoCo
+  agent（tcpserver 模式），随后用 loop-agent 的 backend-test DAG 跑后端测试，最后把 dump 出的 JaCoCo
+  报告与需求文档（PRD/AC/BR）对齐做覆盖率切片分析。用于：本地 jacoco 覆盖率、需求覆盖率分析、Java 服务覆盖率、
+  后端测试覆盖率、backend-test jacoco、本地挂 jacocoagent、覆盖率对照需求。
+  触发词：本地覆盖率检测、覆盖率分析、jacoco 覆盖率、后端代码覆盖率、需求覆盖率、挂载 jacocoagent、
+  local coverage analysis、jacoco tcpserver dump、backend-test 覆盖率分析、按需求分析覆盖率。
+references:
+  - path: references/runtime-alignment.md
+    required: true
+  - path: references/requirement-to-source-mapping.md
+    required: true
+---
+
+# Local JaCoCo Coverage（本地 Java 后端覆盖率检测与分析）
+
+本 skill 是**编排型操作手册**，不是覆盖率引擎本身。它复用 loop-agent runtime 已内置的 JaCoCo 收集与归一化能力，把"起服务挂 agent → 跑后端测试 DAG → 结合需求分析覆盖率"三件事串成一条可审计、可重复、可验证的本地链路。**禁止重造 runtime 已有的 dump/parse/归一化逻辑**；细节字段真源见 `references/runtime-alignment.md`。
+
+## 默认立场
+
+- 三阶段顺序强约束：**① 起服务挂 agent → ② 跑 backend-test DAG → ③ dump + 按需求切片分析**。前一阶段未拿到可验证证据前，不得进入下一阶段。
+- JaCoCo agent 只在**测试环境**挂载；**生产环境严禁**挂载 `address=0.0.0.0` 的 tcpserver。
+- `includes` 必须显式写**业务包名**（如 `com.yourcompany.*`）；用默认 `*` 会把 Spring/Tomcat 等框架也算进去，覆盖率虚低、无参考价值。
+- 覆盖率数据不是"通过/失败"判据，是**质量观测**。pytest 与 backend-test DAG 的执行结论以 backend-test DAG 本身的 shell verification 为准；JaCoCo 收集**全程失败安全**，任一环节出错都不阻断测试（见 `references/runtime-alignment.md` 容错表）。
+- 需求覆盖率分析必须基于**真实的需求 ID**（`REQ-*`/`BR-*`/`AC-*`）与**真实的源码路径**；禁止凭需求文档文本臆测代码路径或编造覆盖率数字。
+- 本 skill 不写业务代码、不修改生产配置、不写 `.env` 或 credential 文件；它只在测试环境启动 Java 服务、运行 loop-agent CLI、产出 `reports/` 与 `docs/test-reports/` 下的报告。
+
+## 前置确认（BLOCKING）
+
+进入 Step 1 前，必须与用户确认以下事实，缺一项则停下询问，不要猜：
+
+| 项 | 说明 | 示例 |
+| --- | --- | --- |
+| Java 服务仓库与启动方式 | 能否加 JVM 启动参数（mvn / java -jar / docker） | `mvn spring-boot:run` |
+| 业务包名 | JaCoCo `includes` 的过滤前缀，**强烈建议显式指定** | `com.coms.bpm.*` |
+| jacocoagent.jar 路径 | Java 服务所在机器上的 agent jar 绝对路径 | `/opt/jacoco/jacocoagent.jar` |
+| jacococli.jar 路径 | **跑 backend-test 的机器**上的 cli jar 绝对路径（用于 `.exec → xml`） | `/opt/jacoco/jacococli.jar` |
+| dump 端口 | tcpserver 监听端口，需与 backend-test 机器连通 | `6300` |
+| loop-agent 控制器 | 已发布的 npm 包版本，按 AGENTS.md 记录实际版本 | `loop-agent --version` |
+| 需求文档 | PRD / 用户故事 / AC / BR 的路径，Step 3 切片分析的输入 | `docs/product-analysis/<id>/product-requirement.md` |
+
+确认后**回显**给用户："分析范围：业务包 `<X>`，agent 端口 `<port>`，cli jar `<path>`，需求文档 `<path>`"。
+
+## Step 1：本地启动后端服务并挂载 JaCoCo agent（tcpserver）
+
+目标：让 Java 服务在测试期间把执行数据暴露成一个可被 backend-test DAG 跨网络 dump 的 tcpserver。
+
+### 1.1 用封装脚本启动（推荐）
+
+```bash
+# <skill-root> 解析为本 SKILL.md 所在目录
+bash <skill-root>/scripts/start-jacoco-agent.sh \
+  --agent-jar /opt/jacoco/jacocoagent.jar \
+  --includes "com.yourcompany.*" \
+  --port 6300 \
+  -- mvn spring-boot:run
+# 或直接 java -jar：
+# bash <skill-root>/scripts/start-jacoco-agent.sh ... -- java -jar your-app.jar
+```
+
+脚本只做三件事：校验 `--agent-jar` 存在、拼装 `-javaagent:...=output=tcpserver,address=0.0.0.0,port=<port>,includes=<pkg>,append=false`、把 `--` 之后的原始启动命令交给 exec。**它不会修改你的启动命令语义**，只前置 agent 参数。
+
+### 1.2 等价的手工写法（脚本不可用时）
+
+```bash
+java -javaagent:/opt/jacoco/jacocoagent.jar=output=tcpserver,address=0.0.0.0,port=6300,includes=com.yourcompany.*,append=false \
+     -jar your-app.jar
+```
+
+Maven 项目：
+
+```bash
+JACOCO_AGENT="$HOME/.m2/repository/org/jacoco/org.jacoco.agent/0.8.12/org.jacoco.agent-0.8.12-runtime.jar"
+mvn spring-boot:run \
+  -Dspring-boot.run.jvmArguments="-javaagent:${JACOCO_AGENT}=output=tcpserver,address=0.0.0.0,port=6300,includes=com.yourcompany.*,append=false"
+```
+
+Docker：
+
+```dockerfile
+ENV JAVA_TOOL_OPTIONS="-javaagent:/opt/jacoco/jacocoagent.jar=output=tcpserver,address=0.0.0.0,port=6300,includes=com.yourcompany.*,append=false"
+```
+
+```bash
+docker run -p 8080:8080 -p 6300:6300 your-image
+```
+
+### 1.3 自检（BLOCKING，必须通过才进 Step 2）
+
+```bash
+# Java 服务进程里确实带了 jacocoagent
+ps aux | grep -i jacocoagent | grep -v grep
+
+# 端口对 backend-test 机器放行（在 backend-test 机器上跑）
+nc -zv <java-service-host> 6300
+```
+
+`address` 必须是 `0.0.0.0`（跨机器可达）；设成 `127.0.0.1` 则 backend-test 连不上。安全组只放行 backend-test 机器。
+
+> 字段含义、参数取值、安全约束的真源见 `references/runtime-alignment.md` 与项目 `docs/operations/backend-test-jacoco-coverage.md`。
+
+## Step 2：启动后端测试 DAG（backend-test）
+
+目标：让 backend-test DAG 在 Step 7（`execute-backend-pytest-and-html-report-shell`）跑完 pytest，并跨网络 dump JaCoCo 数据。backend-test DAG 是固定 9 节点 Markdown-first 工作流，真源见 `docs/runtime/backend-test-workflow.md`。
+
+### 2.1 建任务并进 writeSet gate
+
+```bash
+loop-agent task advance <task-id> "后端测试 + JaCoCo 覆盖率" \
+  --task-kind backend-test \
+  --prd <需求或测试范围 PRD> \
+  --allowed-path "testcase/**" \
+  --forbidden-path ".harness/**" \
+  --verify "<label>:<项目 AGENTS.md 登记的后端测试命令>" \
+  --json
+```
+
+`--task-kind backend-test` 是选用该 DAG 的唯一方式（**不是** `--profile`）。`--verify` 命令必须取自目标项目 `AGENTS.md` / `docs/governance/verification-matrix.md` 登记的命令，不要假定 `pytest` 存在。
+
+### 2.2 审查返回的 writeSet / gate.digest，批准并长跑
+
+```bash
+loop-agent task advance <task-id> \
+  --approve-gate "write-set-review:<digest>" \
+  --json
+```
+
+### 2.3 在 task.json 注入 jacocoCoverage（让节点 7 自动 dump）
+
+backend-test DAG 默认**不会**收集 JaCoCo，除非任务的执行节点 shell 配置里带 `jacocoCoverage`。字段 schema 真源：`src/workflows/dag/types.ts` 的 `dagShellConfigSchema`。
+
+在 `.harness/tasks/<task-id>/task.json` 的执行节点（`execute-backend-pytest-and-html-report-shell`）`shell` 里加：
+
+```json
+{
+  "id": "execute-backend-pytest-and-html-report-shell",
+  "shell": {
+    "backendTestPipeline": "markdown-execute-html",
+    "jacocoCoverage": {
+      "endpoint": "<java-service-host>:6300",
+      "cliJarPath": "/opt/jacoco/jacococli.jar",
+      "includes": "com.yourcompany.*",
+      "connectTimeoutMs": 5000
+    }
+  }
+}
+```
+
+| 字段 | 必填 | 说明 |
+| --- | --- | --- |
+| `endpoint` | 是 | JaCoCo tcpserver 地址，`host:port`，**必须**与 Step 1.3 自检通过的一致 |
+| `cliJarPath` | 是 | **backend-test 机器**上 `jacococli.jar` 的绝对路径，用于 `.exec → jacoco.xml` |
+| `includes` | 否 | 业务包过滤，默认 `*`（**强烈建议显式指定业务包名**，与 Step 1 一致） |
+| `connectTimeoutMs` | 否 | TCP 连接超时，默认 `5000` |
+
+> 注入时机：若在 Step 2.1 之前注入，`task advance` 会 strict validate 时就带上；若事后补，需重新 `task advance` 触发 DAG 校验。**不要**在 DAG 执行期间修改 task.json。
+
+### 2.4 持续监视直到终态
+
+```bash
+loop-agent task status <task-id> --json
+```
+
+判活用可靠方式：`state.json` 的 `runner.heartbeatAt` 持续刷新 + `session-events.jsonl` 增长 + `dag doctor` 的 `liveness`，不要只靠进程过滤。主 agent 必须持续轮询直到 FINISHED / FAILED / 需要 approve，**不能**轮询一次就走。
+
+### 2.5 产物（DAG run 目录 `.harness/dag-runs/<run-id>/` 下）
+
+- `reports/jacoco.exec` — dump 出的执行数据
+- `reports/jacoco.xml` — cli 转换后的 XML（**Step 3 的输入**）
+- `contracts/code-coverage-v1.json` — runtime 解析后的归一化契约
+- `reports/backend-test-l5-dashboard.html` — L-5 dashboard，line/branch 覆盖率已从 unavailable 变为真实数值
+
+**BLOCKING**：进 Step 3 前确认 `reports/jacoco.xml` 存在且非空。若 Step 2.5 没有 `jacoco.xml`，说明 JaCoCo 收集降级了，按 `references/runtime-alignment.md` 的"排查清单"先修，不要带着空数据做分析。
+
+## Step 3：结合需求文档做覆盖率切片分析
+
+目标：把 Step 2 的 `jacoco.xml` 与需求文档对齐，产出"每个需求覆盖了哪些代码、覆盖率多少、哪些需求路径完全没被测试触达"的切片报告。
+
+### 3.1 把需求映射成可切片的 scope（必读）
+
+先读 `references/requirement-to-source-mapping.md`。核心约束：
+
+- 需求 ID 必须是 `REQ-*` / `BR-*` / `AC-*` 形态（runtime 归一化器的正则要求）。PRD 里的章节标题、用户故事编号要先归一化成这三类前缀。
+- `--source-scope` 必须是**真实存在的源码相对路径**（相对仓库根，逗号分隔）。禁止从需求文本猜路径；路径必须来自 Step 2 的 backend-test facts 或对仓库的定向事实搜索（`rg`/CodeGraph）。
+- 一个需求 ↔ 一组源码路径的映射，是一次**可审计的决策**，不是模型自由发挥。
+
+### 3.2 用 runtime 归一化器产出按需求切片的覆盖率
+
+`loop-agent coverage report` 是 runtime 提供的归一化 CLI（真源 `src/commands/coverage-report.ts`、`src/workflows/dag/backend-test-coverage-contract.ts`）。它接收 `jacoco.xml` + 需求 ID + 源码 scope，输出结构化契约或 Markdown：
+
+```bash
+loop-agent coverage report \
+  --language java \
+  --input <run-dir>/reports/jacoco.xml \
+  --requirement-id BR-CREATE-ORDER \
+  --requirement-id AC-CREATE-ORDER-001 \
+  --source-scope src/main/java/com/yourcompany/order/OrderService.java,src/main/java/com/yourcompany/order/OrderController.java \
+  --markdown \
+  --output docs/test-reports/coverage/BR-CREATE-ORDER.md
+```
+
+参数：
+
+| 参数 | 说明 |
+| --- | --- |
+| `--language java` | **必须** `java`（本 skill 只处理 Java/JaCoCo） |
+| `--input` | Step 2.5 的 `jacoco.xml`，**仓库根相对 POSIX 路径**（runtime 拒绝绝对路径：`artifact path must be a safe relative POSIX path`） |
+| `--requirement-id` | 可重复；格式 `REQ-*`/`BR-*`/`AC-*`；来自需求文档归一化 |
+| `--source-scope` | 逗号分隔的源码相对路径；来自事实搜索，不是猜测 |
+| `--markdown` / `--json` | 输出格式，二选一 |
+| `--output` | 输出文件路径；省略则打到 stdout |
+| `--commit` / `--expected-sha256` | 可选，绑定 commit 与 artifact 指纹做审计 |
+
+### 3.3 端到端串联（多需求批量切片）
+
+```bash
+bash <skill-root>/scripts/run-coverage-analysis.sh \
+  --jacoco-xml <run-dir>/reports/jacoco.xml \
+  --mapping docs/test-reports/coverage/requirement-source-mapping.json \
+  --output-dir docs/test-reports/coverage
+```
+
+`requirement-source-mapping.json` 是你在 3.1 产出的映射，格式：
+
+```json
+{
+  "requirements": [
+    {
+      "ids": ["BR-CREATE-ORDER", "AC-CREATE-ORDER-001"],
+      "sourceScope": [
+        "src/main/java/com/yourcompany/order/OrderService.java",
+        "src/main/java/com/yourcompany/order/OrderController.java"
+      ]
+    },
+    {
+      "ids": ["BR-CANCEL-ORDER"],
+      "sourceScope": [
+        "src/main/java/com/yourcompany/order/OrderService.java"
+      ]
+    }
+  ]
+}
+```
+
+脚本对每个需求调一次 `loop-agent coverage report`，产物落到 `--output-dir/<first-id>.md`，并生成一份汇总 `index.md`（列出每个需求的 line/branch/function 覆盖率与 `unavailable` 标记）。脚本**只调 CLI + 聚合文件**，不自己解析 XML、不算覆盖率。
+
+### 3.4 解读与 GAP 标注
+
+分析结论必须区分：
+
+- **COVERED**：scope 内文件在 `jacoco.xml` 里有命中，覆盖率数值有效。
+- **PARTIAL**：scope 内部分文件有命中、部分文件 0 命中或不在 artifact 里。
+- **GAP**：scope 内文件完全没被任何测试触达（`jacoco.xml` 里该文件 counter 全 0 或缺失）→ 这是**测试缺口**，不是"覆盖率低"，应回灌到 backend-test 的 Coverage Matrix 作为 `GAP`。
+- **unavailable**：JaCoCo 收集本身降级（endpoint 不通、cli 缺失等）→ 先修基础设施，不要把 unavailable 当成 0% 写进报告。
+
+## 完成规则
+
+- Step 1 必须有 `ps`/`nc` 自检证据；Step 2 必须有 backend-test DAG 终态 + `reports/jacoco.xml` 非空证据；Step 3 每个需求的覆盖率必须来自 `loop-agent coverage report` 的真实输出，不得手写数字。
+- 没有新鲜验证证据不声明完成；`unavailable` 必须如实标注并给出排查动作。
+- 产物路径默认 `docs/test-reports/coverage/`；写入前确认目录与项目写入边界一致。
+- 安全收尾：测试结束后建议关闭 Java 服务的 jacocoagent（重启服务不带 `-javaagent`），回收 `6300` 端口放行。
+
+## 排查速查
+
+覆盖率是 `unavailable` 或全 0？按顺序：
+
+1. Java 服务进程参数里有没有 `jacocoagent`？（`ps aux | grep jacocoagent`）
+2. `address` 是不是 `0.0.0.0`？端口对 backend-test 机器放行了吗？（`nc -zv <host> 6300`）
+3. `includes` 业务包名写对了吗？（写错 → 统计到 0 个类）
+4. `jacocoCoverage.endpoint` 与 Step 1 的 `host:port` 一致吗？
+5. `jacocoCoverage.cliJarPath` 路径正确且 `java -jar <cli> --help` 可用吗？
+6. agent 与 cli 版本一致吗？（都 `0.8.12`）
+
+详见 `references/runtime-alignment.md`。
+
+## References
+
+- Required：`references/runtime-alignment.md`、`references/requirement-to-source-mapping.md`
+- 项目级真源（只读引用，不复制）：`docs/operations/backend-test-jacoco-coverage.md`（落地手册）、`docs/runtime/backend-test-workflow.md`（DAG 真源）、`src/workflows/dag/types.ts`（`jacocoCoverage` schema）、`src/commands/coverage-report.ts`（`coverage report` CLI）

package/skills/local-jacoco-coverage/references/requirement-to-source-mapping.md

@@ -0,0 +1,85 @@
+# Requirement → Source Mapping — 把需求文档对齐到覆盖率 scope
+
+Step 3 切片分析的核心难点不是调 CLI，而是**把需求文档正确映射成 `(requirementIds, sourceScope)`**。映射错了，覆盖率数字再准也没意义。本文件给出可审计的映射纪律。
+
+## 1. 需求 ID 归一化（BLOCKING）
+
+runtime 归一化器只接受 `^(?:REQ|BR|AC)-[A-Z0-9]+(?:-[A-Z0-9]+)*$`（见 `runtime-alignment.md` §4）。需求文档里的原始编号通常不直接合规，必须先归一化：
+
+| 需求文档里的写法 | 归一化结果 | 说明 |
+| --- | --- | --- |
+| `3.2 创建订单`（章节标题） | `BR-CREATE-ORDER` | 章节级业务规则 |
+| `US-创建订单-001`（用户故事） | `AC-CREATE-ORDER-001` | 故事级验收标准 |
+| `REQ-001`（已合规） | `REQ-001` | 原样 |
+| `BR_PAYMENT_001` | `BR-PAYMENT-001` | 下划线 → 连字符 |
+
+规则：
+
+- 前缀三选一：`REQ`（顶层需求）/ `BR`（业务规则）/ `AC`（验收标准）。拿不准用 `BR`。
+- body 只能是大写字母、数字、单连字符；全部大写；中文/下划线/空格先 slugify。
+- 一个需求可挂多个 ID（如 `BR-CREATE-ORDER` + `AC-CREATE-ORDER-001`），切片时一起传。
+
+**归一化结果必须写进 mapping 文件并回显给用户确认**，不要只在聊天里说。
+
+## 2. sourceScope 来源（禁止臆测）
+
+`--source-scope` 必须是**仓库里真实存在**的源码相对路径。允许的来源，按优先级：
+
+1. **backend-test DAG facts**：Step 2 的 `contracts/backend-test-case-manifest.json` / `reports/backend-test-markdown-pytest-correspondence.md` 里映射的 pytest symbol → 生产代码路径。这是最可信来源，因为它是"本轮测试实际触达的代码"。
+2. **定向事实搜索**：`rg` 或 CodeGraph 按需求关键词（如"创建订单"）定位 controller/service 类。
+3. **需求文档显式声明**：PRD 里如果写了"涉及 `OrderService`"，可作为线索，但仍需在仓库里验证路径存在。
+
+**禁止**：直接把需求文档里的中文术语当文件名猜路径（如把"订单服务"猜成 `OrderService.java` 而不去仓库验证）。
+
+路径规范：
+
+- 相对仓库根，正斜杠，逗号分隔。
+- 不得含 `..`（runtime 会拒绝 unsafe source scope path）。
+- 粒度到**类文件**（`.java`），不要给到包目录（runtime 按 file 过滤）。
+
+## 3. mapping 文件格式
+
+落到 `docs/test-reports/coverage/requirement-source-mapping.json`，与 `run-coverage-analysis.sh` 的输入一致：
+
+```json
+{
+  "requirements": [
+    {
+      "ids": ["BR-CREATE-ORDER", "AC-CREATE-ORDER-001"],
+      "sourceScope": [
+        "src/main/java/com/yourcompany/order/OrderService.java",
+        "src/main/java/com/yourcompany/order/OrderController.java"
+      ],
+      "rationale": "PRD §3.2 创建订单；pytest symbol test_create_order 映射到 OrderService.create（manifest facts）"
+    },
+    {
+      "ids": ["BR-CANCEL-ORDER"],
+      "sourceScope": [
+        "src/main/java/com/yourcompany/order/OrderService.java"
+      ],
+      "rationale": "PRD §3.3 取消订单；仅 OrderService.cancel 被测试触达"
+    }
+  ]
+}
+```
+
+`rationale` 字段是给审计用的，说明"为什么这个需求对应这些路径"；脚本不消费它，但 review 时必填。
+
+## 4. 解读覆盖率切片时的 GAP 判定
+
+拿到 `loop-agent coverage report` 的输出后，按 `missingData` 与 counter 区分：
+
+| 情况 | 判定 | 动作 |
+| --- | --- | --- |
+| scope 文件都在 artifact 里，line% > 0 | COVERED | 记录数值 |
+| scope 文件部分在 artifact、部分不在 | PARTIAL | 标注哪些文件未命中 |
+| scope 文件全不在 artifact（`source-scope-not-found-in-artifact`） | GAP | 测试完全没触达；回灌 backend-test Coverage Matrix 的 `GAP` |
+| JaCoCo 收集降级（无 `jacoco.xml`） | unavailable | 先修基础设施（见 `runtime-alignment.md` §6），**不要**当 0% |
+
+## 5. 反模式
+
+- ❌ 把整个模块 `src/main/java/com/yourcompany/**` 塞进一个需求的 scope —— 稀释了切片意义，等于没切。
+- ❌ 用需求文档里的业务术语当路径，不在仓库验证 —— 会得到 `source-scope-not-found-in-artifact`。
+- ❌ 一个 source 文件只挂一个需求，但它实际服务多个需求 —— 会让多个需求覆盖率虚高。
+- ❌ 把 `unavailable` 当 0% 写进报告 —— 误导后续决策。
+- ❌ 用 `loop-agent coverage report` 之外的工具自己解析 `jacoco.xml` 再手填数字 —— 绕过归一化器，数字不可审计。