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

package/skills/local-jacoco-coverage/references/runtime-alignment.md

@@ -0,0 +1,106 @@
+# Runtime Alignment — 与 loop-agent runtime 的字段与契约真源对齐
+
+本 skill 不重新定义 runtime 字段，只把"本 skill 用到的字段"映射到 runtime 真源，避免漂移。**字段含义以本表"真源"列为准；本 skill 文档与之冲突时，以真源为准。**
+
+## 1. backend-test DAG 的 `jacocoCoverage`（Step 2 注入字段）
+
+| 字段 | 类型 | 必填 | 默认 | 真源 |
+| --- | --- | --- | --- | --- |
+| `endpoint` | `string`（`host:port`） | 是 | — | `src/workflows/dag/types.ts` `dagShellConfigSchema.jacocoCoverage.endpoint` |
+| `cliJarPath` | `string`（绝对路径） | 是 | — | `src/workflows/dag/types.ts` `jacocoCoverage.cliJarPath` |
+| `includes` | `string` | 否 | `*` | `src/workflows/dag/types.ts` `jacocoCoverage.includes` |
+| `connectTimeoutMs` | `number`（正整数） | 否 | `5000` | `src/workflows/dag/types.ts` `jacocoCoverage.connectTimeoutMs` |
+
+注入位置：task.json 的执行节点 `execute-backend-pytest-and-html-report-shell` 的 `shell` 块。该节点 pipeline 必须是 `markdown-execute-html`。
+
+## 2. runtime 收集链路（本 skill 不重造）
+
+```text
+Java 服务启动挂 jacocoagent.jar (output=tcpserver)
+        │ pytest 跑完，HTTP 请求覆盖 Java 代码
+        ▼
+backend-test 节点 7 跨网络 TCP 连 host:<port>，dump 出 reports/jacoco.exec
+        │  collectJacocoCoverage (backend-test-markdown-workflow.ts)
+        ▼
+jacococli.jar 把 .exec 转成 reports/jacoco.xml
+        │
+        ▼
+parseJacocoXml → contracts/code-coverage-v1.json (backend-test-coverage-contract.ts)
+        │
+        ▼
+computeL5ReportMetrics → reports/backend-test-l5-dashboard.html
+```
+
+真源：
+- `src/workflows/dag/backend-test-markdown-workflow.ts` — `collectJacocoCoverage`
+- `src/workflows/dag/backend-test-coverage-contract.ts` — `parseJacocoXml`、`readCoverageArtifact`、`formatCoverageMarkdown`
+- `src/executors/shell-executor.ts` — 节点 7 `markdown-execute-html` pipeline
+
+## 3. JaCoCo agent 启动参数（Step 1）
+
+| 参数 | 取值 | 说明 |
+| --- | --- | --- |
+| `output` | `tcpserver` | **必须**；默认 file 模式跨网络读不到 |
+| `address` | `0.0.0.0` | 测试环境允许跨机器；**生产禁用** |
+| `port` | `6300`（约定，可改） | 需与 `jacocoCoverage.endpoint` 一致 |
+| `includes` | `<业务包>.*` | **必须改**；默认 `*` 会统计框架代码 |
+| `append` | `false` | 每次 dump 后重置，保本轮增量 |
+
+版本约定：agent 与 cli 都用 `0.8.12`（或同版本），版本不一致会导致 `.exec` 无法解析。
+
+## 4. `loop-agent coverage report`（Step 3 CLI）
+
+真源：`src/commands/coverage-report.ts`、`src/workflows/dag/backend-test-coverage-contract.ts`。
+
+```
+loop-agent coverage report \
+  --language java \
+  --input <jacoco.xml> \
+  [--requirement-id REQ-...|BR-...|AC-...] (可重复) \
+  [--source-scope path1,path2] \
+  [--commit <sha>] [--expected-sha256 <sha256>] \
+  [--tool-version <ver>] \
+  [--json|--markdown] \
+  [--output <path>]
+```
+
+约束（来自 `backend-test-coverage-contract.ts` 的 zod schema）：
+
+- `--requirement-id` 正则：`^(?:REQ|BR|AC)-[A-Z0-9]+(?:-[A-Z0-9]+)*$`。不合规的 ID 会被拒绝。
+- `--source-scope` 路径不得含 `..`（unsafe source scope path）。
+- `--language java` 时输入必须是 JaCoCo XML；`--language python` 时输入必须是 coverage.py JSON。本 skill 只用 `java`。
+- 输出契约字段：`sourceScope.requirementIds`、`sourceScope.paths`、line/branch/function 三类 `{ covered, missed, total, percent }`、`artifact.sha256`、`missingData[]`。
+
+`missingData` 可能值（决定 PARTIAL/unavailable 标注）：
+
+- `source-scope-requirement-id-missing` — 没给 `--requirement-id`
+- `source-scope-not-found-in-artifact` — `--source-scope` 的路径在 artifact 里完全找不到
+
+## 5. 容错表（JaCoCo 收集失败安全）
+
+来自 `docs/operations/backend-test-jacoco-coverage.md`。任一环节出错都**不阻断** pytest 与 L-5 报告：
+
+| 失败场景 | 结果 |
+| --- | --- |
+| `endpoint` 不通 / 端口未放行 | coverage 降级 `unavailable` |
+| `jacococli.jar` 缺失或执行失败 | coverage 降级 `unavailable` |
+| Java 服务没挂 agent | dump 拿到空数据，coverage 降级 `unavailable` |
+| `jacoco.xml` 解析失败 | coverage 降级 `unavailable` |
+| task 未配置 `jacocoCoverage` | 完全跳过，行为同未启用 |
+
+**pytest 与 L-5 dashboard 永远不会被覆盖率收集阻断。** 因此 Step 2 的 backend-test DAG 终态可能是 FINISHED 但 `jacoco.xml` 缺失——这时进 Step 3 前必须先按排查清单修复。
+
+## 6. 排查清单（覆盖率 unavailable / 全 0）
+
+1. Java 服务进程是否挂了 agent？`ps aux | grep jacocoagent`
+2. 端口是否放行？`nc -zv <host> <port>`（在 backend-test 机器上）
+3. `address` 是否 `0.0.0.0`？（`127.0.0.1` 跨机器连不上）
+4. `includes` 业务包名是否正确？（写错 → 0 个类）
+5. `jacocoCoverage.cliJarPath` 是否正确且 `java -jar <cli> --help` 可用？
+6. agent 与 cli 版本是否一致？
+
+## 7. 安全约束
+
+- JaCoCo agent 暴露代码执行细节，**仅限测试环境**，生产**严禁**挂载。
+- `address=0.0.0.0` 意味着任何能访问 `<port>` 的机器都能 dump；务必用安全组限制到 backend-test 机器。
+- `append=false` 保证每次测试数据隔离。

package/skills/local-jacoco-coverage/scripts/run-coverage-analysis.sh

@@ -0,0 +1,148 @@
+#!/usr/bin/env bash
+# run-coverage-analysis.sh
+# 端到端串联 Step 3：读取 requirement-source-mapping.json，对每个需求调一次
+# `loop-agent coverage report`，把 Markdown 切片落到 --output-dir，并生成 index.md 汇总。
+#
+# 本脚本只调 CLI + 聚合文件，不自己解析 jacoco.xml、不算覆盖率数字。
+# 需求：loop-agent 已安装并可在 PATH 中执行（或通过 --loop-agent 指定）。
+#
+# 用法：
+#   bash 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 \
+#       [--loop-agent <path>] [--language java]
+#
+# 退出码：
+#   0  全部需求切片成功（含 unavailable 标注）
+#   2  参数错误
+#   3  --jacoco-xml 不存在或为空
+#   4  --mapping 不存在或不是合法 JSON
+#   5  mapping 里 requirements 为空
+#   *  继承最后一个 coverage report 的非零退出码
+
+set -euo pipefail
+
+log() { printf '[run-coverage-analysis] %s\n' "$*" >&2; }
+die() { printf '[run-coverage-analysis] ERROR: %s\n' "$*" >&2; exit "${2:-1}"; }
+
+JACOCO_XML=""
+MAPPING=""
+OUTPUT_DIR=""
+LOOP_AGENT="${LOOP_AGENT:-loop-agent}"
+LANGUAGE="java"
+
+args=("$@")
+for ((i = 0; i < ${#args[@]}; i++)); do
+	case "${args[$i]}" in
+		--jacoco-xml)
+			((i + 1 < ${#args[@]})) || die "--jacoco-xml 需要一个值" 2
+			JACOCO_XML="${args[$((i + 1))]}"; ((i++))
+			;;
+		--mapping)
+			((i + 1 < ${#args[@]})) || die "--mapping 需要一个值" 2
+			MAPPING="${args[$((i + 1))]}"; ((i++))
+			;;
+		--output-dir)
+			((i + 1 < ${#args[@]})) || die "--output-dir 需要一个值" 2
+			OUTPUT_DIR="${args[$((i + 1))]}"; ((i++))
+			;;
+		--loop-agent)
+			((i + 1 < ${#args[@]})) || die "--loop-agent 需要一个值" 2
+			LOOP_AGENT="${args[$((i + 1))]}"; ((i++))
+			;;
+		--language)
+			((i + 1 < ${#args[@]})) || die "--language 需要一个值" 2
+			LANGUAGE="${args[$((i + 1))]}"; ((i++))
+			;;
+		--help|-h)
+			sed -n '2,30p' "$0"
+			exit 0
+			;;
+		*)
+			die "未知参数: ${args[$i]}" 2
+			;;
+	esac
+done
+
+[[ -n "$JACOCO_XML" ]] || die "缺少必填 --jacoco-xml <path>" 2
+[[ -s "$JACOCO_XML" ]] || die "--jacoco-xml 不存在或为空: $JACOCO_XML" 3
+[[ -n "$MAPPING" ]] || die "缺少必填 --mapping <path>" 2
+[[ -f "$MAPPING" ]] || die "--mapping 不存在: $MAPPING" 4
+[[ -n "$OUTPUT_DIR" ]] || die "缺少必填 --output-dir <path>" 2
+
+command -v jq >/dev/null 2>&1 || die "需要 jq 来解析 mapping 文件" 2
+command -v "$LOOP_AGENT" >/dev/null 2>&1 || die "找不到 loop-agent 可执行文件（可用 --loop-agent 指定）: $LOOP_AGENT" 2
+
+mkdir -p "$OUTPUT_DIR"
+
+# 校验 mapping 结构
+req_count=$(jq '.requirements | length' "$MAPPING")
+[[ "$req_count" -gt 0 ]] || die "mapping 里 requirements 为空" 5
+
+log "jacoco xml : $JACOCO_XML"
+log "mapping    : $MAPPING"
+log "output dir : $OUTPUT_DIR"
+log "loop-agent : $LOOP_AGENT"
+log "requirements: $req_count"
+log ""
+
+INDEX="$OUTPUT_DIR/index.md"
+{
+	printf '%s\n\n' '# 需求覆盖率切片汇总'
+	printf '%s\n' "- 输入: \`$JACOCO_XML\`"
+	printf '%s\n' "- mapping: \`$MAPPING\`"
+	printf '%s\n' "- 生成时间: $(date -u '+%Y-%m-%dT%H:%M:%SZ')"
+	printf '%s\n' ''
+	printf '%s\n' '| 需求 ID | source files | line | branch | function | 状态 | 切片文件 |'
+	printf '%s\n' '| --- | ---: | ---: | ---: | ---: | --- | --- |'
+} > "$INDEX"
+
+last_exit=0
+for ((i = 0; i < req_count; i++)); do
+	ids_json=$(jq -c ".requirements[$i].ids" "$MAPPING")
+	scope_json=$(jq -c ".requirements[$i].sourceScope" "$MAPPING")
+
+	# 拼 CLI 参数
+	req_args=()
+	while IFS= read -r id; do
+		[[ -n "$id" ]] && req_args+=(--requirement-id "$id")
+	done < <(jq -r '.[]' <<<"$ids_json")
+
+	scope_csv=$(jq -r '. | map(.) | join(",")' <<<"$scope_json")
+	scope_n=$(jq -r 'length' <<<"$scope_json")
+	first_id=$(jq -r '.[0]' <<<"$ids_json")
+
+	out_file="$OUTPUT_DIR/${first_id}.md"
+	log "[$((i + 1))/$req_count] $first_id  (source files: $scope_n)"
+
+	# 调 runtime 归一化器
+	if "$LOOP_AGENT" coverage report \
+		--language "$LANGUAGE" \
+		--input "$JACOCO_XML" \
+		"${req_args[@]}" \
+		--source-scope "$scope_csv" \
+		--markdown \
+		--output "$out_file"; then
+
+		# 从产出的 markdown 里抓 line/branch/function 覆盖率（容错：抓不到就标 unavailable）
+		line_pct=$(grep -iE '^\- *line' "$out_file" | grep -oE '[0-9]+(\.[0-9]+)?%' | head -1 || true)
+		branch_pct=$(grep -iE '^\- *branch' "$out_file" | grep -oE '[0-9]+(\.[0-9]+)?%' | head -1 || true)
+		func_pct=$(grep -iE '^\- *function' "$out_file" | grep -oE '[0-9]+(\.[0-9]+)?%' | head -1 || true)
+		status="COVERED"
+		[[ -z "$line_pct" && -z "$branch_pct" ]] && status="unavailable/PARTIAL"
+
+		printf '| %s | %d | %s | %s | %s | %s | [%s](%s) |\n' \
+			"$first_id" "$scope_n" \
+			"${line_pct:-unavailable}" "${branch_pct:-unavailable}" "${func_pct:-unavailable}" \
+			"$status" "$first_id.md" "$first_id" >> "$INDEX"
+	else
+		last_exit=$?
+		log "[$((i + 1))/$req_count] $first_id  coverage report 失败 (exit $last_exit)"
+		printf '| %s | %d | - | - | - | ERROR(exit %d) | - |\n' "$first_id" "$scope_n" "$last_exit" >> "$INDEX"
+	fi
+done
+
+log ""
+log "汇总已写入: $INDEX"
+exit "$last_exit"

package/skills/local-jacoco-coverage/scripts/start-jacoco-agent.sh

@@ -0,0 +1,110 @@
+#!/usr/bin/env bash
+# start-jacoco-agent.sh
+# 在本地/测试环境启动 Java 后端服务并挂载 JaCoCo agent（tcpserver 模式）。
+# 本脚本只做三件事：校验 --agent-jar 存在、拼装 -javaagent 参数、把 -- 之后的原始启动命令交给 exec。
+# 它不修改启动命令的语义，只前置 agent 参数。
+#
+# 用法：
+#   bash start-jacoco-agent.sh --agent-jar <path> [--includes <pkg>] [--port <n>]
+#                              [--address <ip>] [--append <bool>] -- <启动命令...>
+# 示例：
+#   bash start-jacoco-agent.sh --agent-jar /opt/jacoco/jacocoagent.jar \
+#       --includes "com.yourcompany.*" --port 6300 -- mvn spring-boot:run
+#   bash start-jacoco-agent.sh --agent-jar /opt/jacoco/jacocoagent.jar \
+#       --includes "com.yourcompany.*" -- java -jar your-app.jar
+#
+# 退出码：
+#   0  服务正常退出
+#   2  参数错误
+#   3  --agent-jar 不存在
+#   4  未提供 -- 之后的启动命令
+#   *  继承被启动命令的退出码
+
+set -euo pipefail
+
+log() { printf '[start-jacoco-agent] %s\n' "$*" >&2; }
+die() { printf '[start-jacoco-agent] ERROR: %s\n' "$*" >&2; exit "${2:-1}"; }
+
+AGENT_JAR=""
+INCLUDES="*"
+PORT="6300"
+ADDRESS="0.0.0.0"
+APPEND="false"
+SEPARATOR_IDX=-1
+
+args=("$@")
+for ((i = 0; i < ${#args[@]}; i++)); do
+	case "${args[$i]}" in
+		--agent-jar)
+			((i + 1 < ${#args[@]})) || die "--agent-jar 需要一个值" 2
+			AGENT_JAR="${args[$((i + 1))]}"
+			((i++))
+			;;
+		--includes)
+			((i + 1 < ${#args[@]})) || die "--includes 需要一个值" 2
+			INCLUDES="${args[$((i + 1))]}"
+			((i++))
+			;;
+		--port)
+			((i + 1 < ${#args[@]})) || die "--port 需要一个值" 2
+			PORT="${args[$((i + 1))]}"
+			((i++))
+			;;
+		--address)
+			((i + 1 < ${#args[@]})) || die "--address 需要一个值" 2
+			ADDRESS="${args[$((i + 1))]}"
+			((i++))
+			;;
+		--append)
+			((i + 1 < ${#args[@]})) || die "--append 需要一个值" 2
+			APPEND="${args[$((i + 1))]}"
+			((i++))
+			;;
+		--)
+			SEPARATOR_IDX=$((i + 1))
+			break
+			;;
+		--help|-h)
+			sed -n '2,30p' "$0"
+			exit 0
+			;;
+		*)
+			die "未知参数: ${args[$i]}（启动命令请放在 -- 之后）" 2
+			;;
+	esac
+done
+
+[[ -n "$AGENT_JAR" ]] || die "缺少必填 --agent-jar <path>" 2
+[[ -f "$AGENT_JAR" ]] || die "--agent-jar 不存在: $AGENT_JAR" 3
+[[ "$SEPARATOR_IDX" -ge 0 && "$SEPARATOR_IDX" -lt ${#args[@]} ]] || die "未提供 -- 之后的启动命令" 4
+
+# 拼装 -javaagent 参数（JaCoCo tcpserver 模式）
+AGENT_OPTS="output=tcpserver,address=${ADDRESS},port=${PORT},includes=${INCLUDES},append=${APPEND}"
+JAVA_AGENT="-javaagent:${AGENT_JAR}=${AGENT_OPTS}"
+
+# 取出 -- 之后的启动命令
+launch=("${args[@]:$SEPARATOR_IDX}")
+[[ ${#launch[@]} -gt 0 ]] || die "-- 之后没有启动命令" 4
+
+log "agent jar     : $AGENT_JAR"
+log "agent options : $AGENT_OPTS"
+log "launch command: ${launch[*]}"
+log ""
+log "⚠️  JaCoCo agent 仅限测试环境；生产环境严禁挂载。"
+log "⚠️  address=$ADDRESS 意味着任何能访问 $PORT 的机器都能 dump，请用安全组限制。"
+log ""
+
+# 若启动命令是 java*，直接前置 -javaagent；
+# 若是 mvn*，转成 -Dspring-boot.run.jvmArguments（Spring Boot Maven 插件约定）；
+# 其它命令：前置 JAVA_TOOL_OPTIONS（最通用，但无法覆盖命令里已有的 -javaagent）。
+case "${launch[0]}" in
+	java)
+		exec "${launch[0]}" "$JAVA_AGENT" "${launch[@]:1}"
+		;;
+	mvn)
+		exec "${launch[0]}" "${launch[@]:1}" "-Dspring-boot.run.jvmArguments=$JAVA_AGENT"
+		;;
+	*)
+		JAVA_TOOL_OPTIONS="$JAVA_AGENT" exec "${launch[@]}"
+		;;
+esac

package/skills/loop-agent/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: loop-agent
+description: >-
+  Use when implementing features, processing PRDs or requirements, running structured loop-agent workflows, creating harness tasks, using Agent DAG / task advance lifecycle, pi-prompt planning/review, cursor-prompt one-shot sidecar intervention, initializing a target project with loop-agent, checking init update status, applying a safe init update, or converging website/governance docs after user-visible changes in loop-agent. Triggers: loop-agent, workflow, structured development, harness task, Agent DAG, task advance, task status, dag validate, dag execute, docs converge, Converge Docs, 文档收敛, 结构化开发, 工作流, 需求实现, PRD 实现, 初始化 loop-agent, loop agent 初始化, loop agent初始化, loop-agent 初始化, 初始化更新校验, loop agent初始化更新校验, 检查初始化更新, 初始化安全更新, loop agent初始化安全更新, 应用初始化更新, loop-agent初始化更新, loop-agent 初始化更新, 更新 loop-agent 初始化内容, 升级后对齐. 强路由：loop-agent 帮我完成需求, 帮我实现, 帮我修复, 帮我开发, 使用 loop-agent 完成, 按 loop-agent 流程处理, 通用需求实现；这些表达确定性地进入 task advance / Agent DAG CLI，主会话编排而不直接写业务实现.
+references:
+  - path: references/harness-policy.md
+    required: true
+  - path: references/hybrid-dag.md
+    required: true
+  - path: references/verification-and-failure-handling.md
+    required: true
+---
+
+# loop-agent Workflow
+
+入口只保留路由与硬约束；细节由 frontmatter required references 注入，`command-reference.md` 保持可选。
+
+## 默认立场
+
+- 主入口是 **Agent DAG**；主会话只编排 CLI、审 writeSet、处理 gate、验证与 handoff，不写业务实现。
+- 禁止绕过 CLI 用宿主 Edit/Write「救火」；失败走 doctor/reconcile/human gate/重跑。
+- `pi` 默认 read-only；仅 `toolProfile: "write"` 是 bounded writer。Shell verification 是事实源。
+
+## 初始化升级路由
+
+- 写入型「**loop-agent初始化更新**」「loop-agent 初始化更新」「更新 loop-agent 初始化内容」「升级后对齐」统一运行 `loop-agent init upgrade --repo-root . --json`；处理 controller 返回的单文件 `allowedPaths`，以同一 run `--continue` 推进至终态，不停在中间状态。
+- 升级可能因 gitignore 迁移评估暂停：若 `.agents/` 存在已跟踪内容，需先审查是否有应团队共享的自定义内容；存在 staged 变更或 git 查询失败时需先解决 blocker，再重跑评估。建议的 `git rm -r --cached --ignore-unmatch` 只修改 index、保留工作区文件，且由用户执行而非 controller。
+- 「检查初始化更新」「初始化更新校验」「只检查，不要修改」仅运行 `loop-agent init check-update --repo-root . --markdown`，不得创建 run 或写入。
+- facts 位于 `.harness/init-upgrades/<run-id>/`；禁止业务源码和宽泛 glob。默认管理项目 `.opencode/plugins/`、`.pi/extensions/`、`.pi/settings.json`；Pi trust 后加载，默认不读写 `~/.pi/agent/settings.json`。
+
+## 标准路径
+
+```bash
+loop-agent task advance <task-id> "Title" --prd <prd.md> \
+  --allowed-path "<glob>" --forbidden-path ".harness/**" \
+  --verify "<label>:<command>" --json
+loop-agent task advance <task-id> \
+  --approve-gate "write-set-review:<digest>" --json
+loop-agent task status <task-id> --json
+```
+
+`--verify` 命令应取项目 `AGENTS.md` / 治理文档 verification-matrix.md 登记的验证命令（不要假定 `npm run typecheck` 存在）；`--verify` 可选，省略时自动从 package.json scripts 或既有 managed `task.json.verifyCommands` 推导建议。
+
+非微小跨会话任务可先 `plan create`。主会话只审 gate/writeSet 与验证证据，不拼低层 prepare/run-task/run-dag/promote/closeout 命令串。
+
+## 主题路由
+
+| 主题 | Reference |
+| --- | --- |
+| Harness policy、Loop、SePO-lite | `references/harness-policy.md` |
+| DAG topology、writeSet、recovery | `references/hybrid-dag.md` |
+| Operator commands、`agent-worker` | `references/command-reference.md` |
+| 验证、failure、closeout | `references/verification-and-failure-handling.md` |
+
+## Hard Rules
+
+1. Use vertical tracer bullets across real integration layers；each needs independent acceptance and verification.
+2. Autonomy ≠ governance profile；AFK/HITL 属 human gate，`--profile` 按风险选择。
+3. 必须读取 `source/需求.md`、`source/执行约束.md`，优先原始 `source/references/*`。
+4. `referenceDocs` uses `{ path, name? }[]`, never a string array；`verifyCommands` uses `{ label, command, timeoutMs? }[]`, never a string array。
+5. Agent DAG 才是实现流；review 三向核对 references、derived source、implementation。
+6. read-only DAG/sidecar 不得写 root `artifacts/`；completed run facts 只读。
+7. 关键状态不得只留在聊天；完成前必须验证。
+8. Client recovery 的 `auto|project|user|off` 遵守 ownership；仅 `user` 写用户 Pi settings，overflow 与 transient 分工。
+
+## References
+
+Required：`references/harness-policy.md`、`references/hybrid-dag.md`、`references/verification-and-failure-handling.md`。Optional 见 `references/README.md`；常用 `references/command-reference.md`、`references/source-and-plan-practice.md`、`references/long-running-loop.md`、`references/orchestrator-and-interventions.md`、`references/docs-converge.md`。

package/skills/loop-agent/references/README.md

@@ -0,0 +1,67 @@
+# loop-agent Skill References
+
+本目录是 `../SKILL.md` 的 progressive-disclosure reference layer。`SKILL.md`
+只负责 trigger、入口选择和硬规则；较长的 command details、operational procedures、
+failure handling 与 workflow 细节放在这里，避免主 skill 变成百科。
+
+## 使用方式
+
+1. 先读 `../SKILL.md`，确认当前任务是否真的需要 `loop-agent`。
+2. 根据任务类型只打开相关 reference，不要一次加载整个目录。
+3. 执行时遵循 Agent DAG 路径；历史顺序式 `run ...` workflow 已移除。
+4. 如果 reference 与 `harness.json` 或 repo-local `ai_workspace/loop-agent/loop-agent-harness.md` / `specs/loop-agent-harness.md` 冲突，以
+   `harness.json` 的机器可读 policy 和本目录的 shared policy 为准，并回头修正文档漂移。
+
+## 快速路由
+
+| 场景 | 优先读取 |
+|---|---|
+| 通用 loop-agent harness workflow policy、跨 repo 共同规则 | `harness-policy.md` |
+| 中大型 autonomous implementation、harness-governed work | `harness-policy.md`、`hybrid-dag.md`、`orchestrator-and-interventions.md`、`verification-and-failure-handling.md` |
+| 需要查精确 CLI 用法、setup、goal、docs helper、stats | `command-reference.md` |
+| 低风险 micro task、旧任务目录兼容、DAG runtime 修复 | `task-workflow.md`、`verification-and-failure-handling.md` |
+| DAG 运行中要判断 main session 是否能手术式补丁、是否需要 sidecar prompt | `orchestrator-and-interventions.md` |
+| 短时 one-shot Pi SDK 调用，不创建 `.harness/tasks/` | `pi-prompt.md` |
+| 解释 `.harness/runs/`、one-shot evidence、active 残留或 promotion | `one-shot-runs.md` |
+| 多 worktree 并行委派、delegate/harvest | `multi-worktree.md` |
+| 模型、provider、profile、fallback routing | `model-routing.md` |
+| Long-running `loop` 命令、action 规则、auto mode、signals、loop closeout | `long-running-loop.md` |
+| Three-pass convergence、repair artifact / spine audit / knowledge curate、SePO-lite prompt evolution | `harness-policy.md` |
+| Cursor bounded write 后的独立复核、verify knobs、failure handling | `verification-and-failure-handling.md` |
+
+## Reference 索引
+
+| Reference | 使用场景 |
+|---|---|
+| `harness-policy.md` | 通用 loop-agent harness policy：DAG、命令分层、source materials、loop/sidecar 边界、facts/verification/handoff 规则；repo-local harness docs 应引用它而不是复制规则 |
+| `orchestrator-and-interventions.md` | 协调长时间 autonomous DAG work；判断 main session 是否可以 edit；使用 one-shot Pi/Cursor sidecar；恢复 in-flight workflow |
+| `command-reference.md` | 需要 `.` 的精确 CLI 命令、setup、goal lifecycle、docs helper、stats |
+| `task-workflow.md` | 处理 task source material、task config、repo adapter 或 legacy task 目录布局 |
+| `pi-prompt.md` | 运行短时 one-shot Pi SDK task，且不创建 `.harness/tasks/` |
+| `one-shot-runs.md` | 解释 `.harness/runs/{active,completed,failed}` 的创建条件、生命周期、治理清理与 `promote-run` 关系 |
+| `hybrid-dag.md` | 使用 Agent DAG Level 2 `dag validate` / `dag execute`，Level 3 `dag init-hybrid` / `task advance`，或查看 write policy、DAG source-of-truth 规则 |
+| `pi-subagent-assisted-mode.md` | 启用 `piSubagentMode`，或在 Pi step 内配置 read-only scout / planner / reviewer subagent |
+| `model-routing.md` | 查看或修改 model/provider 默认、profile、routing 或 fallback 行为 |
+| `post-implementation-and-patterns.md` | 处理 post-verify handoff、PRD item 拆分、fast bounded task、quick status 或 Pi timeout |
+| `multi-worktree.md` | 用 isolated worktree、`delegate` 与 `harvest` 并发执行互不重叠的 independent task |
+| `verification-and-failure-handling.md` | 选择 verify knob、Cursor bounded write 后的独立复核、解释 failure mode、执行 completion audit 与 closeout |
+| `long-running-loop.md` | 使用 experimental long-running `loop` outer state：命令入口、action 规则、auto mode 写入边界、signals 与 loop closeout |
+
+## 边界与状态源
+
+- `references/harness-policy.md` 是 shared workflow policy source，供多个 repo 的 thin adapter docs 引用。
+- `../SKILL.md` 是 skill trigger 与 routing source，不承载长流程细节。
+- `ai_workspace/loop-agent/loop-agent-harness.md` / repo-local `specs/loop-agent-harness.md` 是本仓库或目标仓库的 adapter 文档：只描述 runtime 位置、governance root、验证入口和本地边界。
+- `harness.json` 是 workflowPolicy、script entrypoints、artifacts 目录与 model routing 的机器可读 source of truth。
+- `.harness/tasks/<task-id>/` 是 task 运行态状态；不要把运行态事实写进本目录。
+- `.harness/runs/completed/<run-id>/` 是 one-shot tool run evidence；reference 文档只能解释如何读取和 promotion，不应复制 run facts。
+- `.harness/dag-runs/completed/<run-id>/` 是单次 DAG run 的不可变 facts；reference 文档只能解释如何读取和收口，不应复制 run facts。
+
+## 维护规则
+
+- 不要把长段落复制回 `SKILL.md`；需要新增细节时，在本目录新增或更新 reference，并在 `SKILL.md` 添加 routing row。
+- 让 `SKILL.md` 保持 120-180 行以内；reference 文件承担细节。
+- 新 reference 应有清晰标题、触发场景、最小步骤、失败处理和维护边界。
+- 如果某个 reference 变成可独立触发、跨项目通用且不再依赖本仓库上下文，再考虑拆成独立 skill。
+- 更新 command、workflow policy 或 verification 规则时，同步核对 `harness.json`、`references/harness-policy.md`、repo-local harness adapter docs 和 verification matrix。
+- `~/.pi/agent/.agents/skills/loop-agent` 是指向本目录的 symlink，所以仓库内 edits 会直接更新 Pi skill。