@tea-agent/loop-agent 0.9.0 → 0.10.0-alpha.0

package/dist/workflows/loop/actions.js

@@ -7,21 +7,17 @@ import { validateDagUseCase } from "../../application/dag/validate-dag.js";
 import { formatDagReportHandoffMarkdown, formatDagReportMarkdown, } from "../dag/report.js";
 import { loadTaskConfig } from "../../task/runtime.js";
 import { appendLoopEvent } from "./events.js";
-import { appendLoopRound, readLoopRounds } from "./rounds.js";
+import { appendLoopRound } from "./rounds.js";
 import { rewriteLoopContext } from "./context.js";
 import { loadLoopState } from "./state.js";
 import { drainLoopSignals, pendingLoopSignals, readLoopSignals, } from "./signals.js";
 import { decideNextLoopAutoAction, } from "./policy/auto-policy.js";
-import { validateLoopCursorFixPolicy } from "./policy/cursor-fix-policy.js";
 import { configureLoopDagDefaultRunner, } from "./actions/dag-action.js";
 import { readLatestPiReviewRecord } from "./actions/pi-review.js";
 import { runLoopWorkflowGateSignalAction, } from "./actions/workflow-action.js";
-import { hasDagRound } from "./actions/shared.js";
 export { decideNextLoopAutoAction } from "./policy/auto-policy.js";
-export { validateLoopCursorFixPolicy } from "./policy/cursor-fix-policy.js";
 export { resolveLoopShellVerifyCommands, runLoopShellVerification } from "./actions/shell-verify.js";
 export { buildLoopPiReviewPrompt, runLoopPiReview, } from "./actions/pi-review.js";
-export { buildLoopCursorFixPrompt, runLoopCursorFix } from "./actions/cursor-fix.js";
 export { runLoopDagAction } from "./actions/dag-action.js";
 export { runLoopWorkflowAction, runLoopWorkflowGateSignalAction, } from "./actions/workflow-action.js";
 async function defaultDagCommandRunner(repoRoot, command, args) {
@@ -58,6 +54,17 @@ async function defaultDagCommandRunner(repoRoot, command, args) {
 configureLoopDagDefaultRunner(defaultDagCommandRunner);
 async function defaultAutoActionRunner(input) {
     if (isLoopActionName(input.action)) {
+        if (input.action === "dag") {
+            await runLoopAction({
+                action: "dag",
+                repoRoot: input.repoRoot,
+                taskId: input.taskId,
+                options: {
+                    mode: input.dagMode ?? "review",
+                },
+            });
+            return;
+        }
         await runLoopAction({
             action: input.action,
             repoRoot: input.repoRoot,
@@ -81,7 +88,6 @@ async function defaultAutoActionRunner(input) {
 function isLoopActionName(action) {
     return (action === "shell-verify" ||
         action === "pi-review" ||
-        action === "cursor-fix" ||
         action === "dag" ||
         action === "workflow");
 }
@@ -117,33 +123,10 @@ export async function runLoopAuto(repoRoot, taskId, options = {}) {
             }
             continue;
         }
-        const hasApprovalSignal = pendingLoopSignals(signals).some((signal) => signal.type === "approval");
-        const policyAllowsCursorFix = taskConfig.loopAutoWritePolicy === "enabled" ||
-            (taskConfig.loopAutoWritePolicy === "approval-required" &&
-                (Boolean(options.allowCursorFix) || hasApprovalSignal));
-        let cursorFixPolicyError;
-        if (policyAllowsCursorFix &&
-            state.lastAction === "pi-review" &&
-            latestPiReview?.structured.recommendedAction === "implement_fix") {
-            try {
-                const rounds = await readLoopRounds(repoRoot, taskId);
-                validateLoopCursorFixPolicy({
-                    allowedPaths: taskConfig.allowedPaths,
-                    forbiddenPaths: taskConfig.forbiddenPaths,
-                    complexity: taskConfig.complexity,
-                    dagFallbackReason: taskConfig.dagFallbackReason ?? "",
-                    hasDagRound: hasDagRound(rounds),
-                });
-            }
-            catch (error) {
-                cursorFixPolicyError = error instanceof Error ? error.message : String(error);
-            }
-        }
         const next = decideNextLoopAutoAction(state, signals, {
-            loopAutoWritePolicy: taskConfig.loopAutoWritePolicy,
-            allowCursorFix: options.allowCursorFix,
+            loopAutoExecutionPolicy: taskConfig.loopAutoExecutionPolicy,
+            approvalGranted: options.approvalGranted,
             latestPiReview: latestPiReview?.structured,
-            cursorFixPolicyError,
         });
         actions.push(next);
         await appendLoopEvent(repoRoot, taskId, {

package/dist/workflows/loop/benchmark.js

@@ -194,7 +194,7 @@ export const LOOP_BENCHMARK_FIXTURE_SAMPLES = [
             regressionPause: false,
             changedPaths: 1,
             repairPasses: 1,
-        }, ["./test/loop-workflow.test.ts"], "Approval or enabled policy triggers bounded cursor-fix."),
+        }, ["./test/loop-workflow.test.ts"], "Approval or enabled policy triggers bounded DAG execute."),
         result("3-pass-convergence+quota", {
             pass: true,
             fullVerifyPass: true,

package/dist/workflows/loop/index.js

@@ -5,4 +5,4 @@ export { rewriteLoopContext } from "./context.js";
 export { appendLoopSignal, drainLoopSignals, parseLoopSignalType, pendingLoopSignals, readLoopSignals, } from "./signals.js";
 export { appendLoopEvent, readLoopEvents } from "./events.js";
 export { generateLoopCloseout } from "./closeout.js";
-export { buildLoopPiReviewPrompt, buildLoopCursorFixPrompt, decideNextLoopAutoAction, resolveLoopShellVerifyCommands, runLoopAuto, runLoopCursorFix, runLoopDagAction, runLoopPiReview, runLoopShellVerification, runLoopWorkflowGateSignalAction, runLoopWorkflowAction, validateLoopCursorFixPolicy, } from "./actions.js";
+export { buildLoopPiReviewPrompt, decideNextLoopAutoAction, resolveLoopShellVerifyCommands, runLoopAuto, runLoopDagAction, runLoopPiReview, runLoopShellVerification, runLoopWorkflowGateSignalAction, runLoopWorkflowAction, } from "./actions.js";

package/dist/workflows/loop/policy/auto-policy.js

@@ -55,28 +55,34 @@ export function decideNextLoopAutoAction(state, signals = [], options = {}) {
     }
     if (state.lastAction === "pi-review") {
         if (options.latestPiReview?.recommendedAction === "implement_fix") {
-            const policy = options.loopAutoWritePolicy ?? "off";
+            const policy = options.loopAutoExecutionPolicy ?? "off";
             const approvalSignal = pendingSignals.find((signal) => signal.type === "approval");
-            const allowedByPolicy = policy === "enabled" ||
-                (policy === "approval-required" &&
-                    (Boolean(options.allowCursorFix) || Boolean(approvalSignal)));
-            if (options.cursorFixPolicyError) {
+            const approved = Boolean(options.approvalGranted) || Boolean(approvalSignal);
+            if (policy === "off") {
                 return {
-                    action: "pause",
-                    reason: `cursor-fix policy guard failed: ${options.cursorFixPolicyError}`,
-                    decision: "pause",
+                    action: "dag",
+                    dagMode: "review",
+                    reason: `pi-review recommended implement_fix; loopAutoExecutionPolicy=off (DAG review only)`,
+                    decision: "continue",
                 };
             }
-            if (allowedByPolicy) {
+            if (policy === "approval-required" && !approved) {
                 return {
-                    action: "cursor-fix",
-                    reason: `pi-review recommended implement_fix; loopAutoWritePolicy=${policy}`,
-                    decision: "continue",
+                    action: "pause",
+                    reason: `pi-review recommended implement_fix; loopAutoExecutionPolicy=approval-required without approval`,
+                    decision: "pause",
                 };
             }
+            return {
+                action: "dag",
+                dagMode: "execute",
+                reason: `pi-review recommended implement_fix; loopAutoExecutionPolicy=${policy}`,
+                decision: "continue",
+            };
         }
         return {
             action: "dag",
+            dagMode: "review",
             reason: "read-only review produced next action; generate a governed DAG review packet",
             decision: "continue",
         };
@@ -85,19 +91,21 @@ export function decideNextLoopAutoAction(state, signals = [], options = {}) {
     if (approvalSignal) {
         return {
             action: "dag",
+            dagMode: "review",
             reason: `approval signal received; generate next governed DAG packet: ${approvalSignal.message}`,
             decision: "continue",
         };
     }
-    if (state.lastAction === "cursor-fix" || state.lastAction === "dag") {
+    if (state.lastAction === "dag") {
         return {
             action: "shell-verify",
-            reason: `${state.lastAction} round must be followed by deterministic shell verification`,
+            reason: "dag round must be followed by deterministic shell verification",
             decision: "continue",
         };
     }
     return {
         action: "dag",
+        dagMode: "review",
         reason: "default to DAG governed review packet for the next bounded round",
         decision: "continue",
     };

package/dist/workflows/loop/policy/path-patterns.js

@@ -0,0 +1,13 @@
+import { pathMatchesPattern } from "../../../shared/git-progress.js";
+export function normalizePattern(pattern) {
+    return pattern.replace(/\\/g, "/").replace(/^\.\//, "").replace(/\/\*\*$/, "");
+}
+export function patternsOverlap(allowed, forbidden) {
+    const a = normalizePattern(allowed);
+    const f = normalizePattern(forbidden);
+    return (a === f ||
+        a.startsWith(`${f}/`) ||
+        f.startsWith(`${a}/`) ||
+        pathMatchesPattern(a, forbidden) ||
+        pathMatchesPattern(f, allowed));
+}

package/docs/README.md

@@ -4,19 +4,39 @@
 
 顶层 `AGENTS.md` 是操作地图。长期知识应落在此处：决策、契约、计划、验证证据、调试笔记和可复用流程规则应记录在 `docs/` 下，而不是只留在聊天里。
 
+**索引职责**：本文件只索引**核心契约、方法论、产物目录入口与模板**。单篇 progress / report / completed plan 的全量列表分别由对应子目录 `README.md` 维护，避免三处精选榜漂移。
+
+站上用法文档在 `../website/docs/`；双树收敛见 `../skills/loop-agent/references/docs-converge.md`。
+
 ## 核心文档
 
 - `development-principles.md` — 仓库开发原则
 - `architecture/runtime-boundaries.md` — runtime 层边界与依赖方向
+- `architecture/README.md` — 架构文档目录索引与阅读路径
+- `architecture/system-overview.md` — loop-agent / agent-worker / 治理层 / 外部系统全景
+- `architecture/dag-execution.md` — Agent DAG 主调用链、rank 调度、executor、skill snapshot、生命周期
+- `architecture/worker-and-feature.md` — agent-worker 子进程边界、controller identity、Task Pool、Feature 与 Observe
+- `architecture/facts-and-state.md` — harness 事实与状态、canonical/derived、可写/只读边界
+- `architecture/evolution.md` — 当前已实现能力 vs 第 3–6 月未来方向
 - `feature-workflow.md` — 有边界的功能工作流
 - `verification-matrix.md` — 验证命令选择
 - `production-readiness.md` — Production Readiness v0.1 范围、证据与 DAG hardening 标准
 - `loop-agent-harness.md` — runtime 与 command surface 概览
 - `agent-dag-runner.md` — Agent DAG runner 指南
-- `cursor-executor-usage.md` — Cursor executor 用法
-- `dynamic-workflow-dag-engine-roadmap.md` — Dynamic Workflow DAG Engine 路线图与适配分析
+- `agent-dag-recovery-playbook.md` — DAG 失败分类、recovery action 与 operator 处置手册
+- `cursor-prompt-sidecar.md` — `cursor-prompt` one-shot sidecar 用法（非受治理 writer）
 - `init-surface.manifest.json` — npm 包范围、目标项目初始化投影与 `init check-update` surface 分类的机器校验契约
 
+## 近期完成合同（入口）
+
+完整列表见 `exec-plans/completed/README.md`。近期高频入口：
+
+- `exec-plans/completed/2026-07-14-website-docs-ia-and-converge.md` — Website IA、双树边界与 docs-converge
+- `exec-plans/completed/2026-07-13-versioned-self-hosting-bootstrap.md` — 版本化自举与 candidate canary
+- `exec-plans/completed/2026-07-12-pi-only-agent-runtime.md` — Pi-only 受治理 runtime
+- `exec-plans/completed/2026-07-12-observe-warm-console-redesign.md` — Observe 暖白运行控制台
+- `exec-plans/completed/2026-07-12-m2-08-closeout-dogfood-release.md` — 第二月 Closeout 与 dogfood 收口（M2-01～08 见 completed 索引）
+
 ## 设计思想来源
 
 - `../website/docs/practices/` — Anthropic 长时运行 agent harness、OpenAI Codex harness engineering、腾讯端到端 Harness Engineering 与社区 agent harness 实践资料。当前仓库的“人类掌舵、智能体执行”、仓库即记录系统、小步增量、结构化 handoff 和 shell verification 纪律均受这些实践启发；权威执行规则仍以本目录治理文档、根目录 AGENTS.md、harness.json、skills 目录和脚本检查为准。
@@ -29,25 +49,19 @@
 
 ## 产物目录
 
-- `design/README.md` — 设计草稿与实现契约
+- `design/README.md` — 设计草稿、契约映射与路线图（含 design/dynamic-workflow-dag-engine-roadmap.md）
 - `exec-plans/active/README.md` — 进行中的执行计划
-- `exec-plans/completed/README.md` — 已完成的执行计划
-- `progress/README.md` — 进度交接日志
-- `reports/README.md` — 验证与审计报告
-- `reports/2026-07-11-round3-worker-expansion.md` — Round 3 Worker 扩量、0.7.4 FE green、QA review blocker 与第二轮 owner decision
-- `reports/2026-07-11-observe-dag-visualization.md` — Observe DAG edges、SVG 图形化、交互与真实 Chrome smoke 验证证据
-- `reports/2026-07-11-0.7.5-init-evolution-review.md` — 0.7.5 package/version 变化对目标项目初始化 surface 的影响审查
-- `reports/2026-07-11-command-performance-audit.md` — 命令并发、验证、Observe 和子进程输出的性能审计
-- `reports/2026-07-11-command-performance-followups.md` — Observe 快照复用、输出缓冲和 reference index 遍历优化的验证记录
-- `reports/2026-07-11-observe-terminal-dag-kpi.md` — 终态 DAG 被误计为活跃数的修复记录
-- `reports/2026-07-12-observe-warm-console-redesign.md` — 暖白运行控制台视觉重构与桌面验证记录
-- `decisions/README.md` — 架构决策
+- `exec-plans/completed/README.md` — 已完成的执行计划（全量）
+- `progress/README.md` — 进度交接日志（全量）
+- `reports/README.md` — 验证与审计报告（全量）；活能力摘要见 `reports/current-capability-summary.md`
+- `decisions/README.md` — 架构决策（ADR 0001–0003）
 - `skills/README.md` — repo-local skill registry and vetting notes
 - `templates/` — 可复用的规划、报告与 DAG 模板
 
 ## 仓库 Skills
 
 - `../skills/loop-agent/` — loop-agent 自身的 skill 指令与参考资料
+- `../skills/agent-worker/` — Feature Packet / Task Pool / versioned self-hosting 的可选 outer-loop operator skill；不进入默认 DAG role skills
 - 每个额外 skill 在仓库根 `../skills/` 下使用独立子目录；这些本地副本由 DAG 模板引用，维护不依赖外部 agent skill 目录
 
 ## 模板
@@ -58,8 +72,8 @@
 - `templates/exec-plan.md` — 非平凡工作的执行计划
 - `templates/progress-log.md` — 进度与交接日志
 - `templates/qa-report.md` — 验证与 QA 证据
-- `templates/worker-dogfood-setup.md` — 发布控制器下的真实 Worker sample setup 与 retry 纪律
-- `templates/worker-dogfood-evidence.md` — BE/FE/QA sample、Observe、morning report 与 coverage evidence 模板
+- `templates/worker-dogfood-setup.md` — 发布 controller identity 固定、真实 Worker sample、candidate canary 与 retry 纪律
+- `templates/worker-dogfood-evidence.md` — controller fingerprint、skill snapshot、canary、BE/FE/QA、Observe 与 failure evidence 模板
 - `templates/harness.schema.json` — `harness.json` 的 IDE JSON Schema，随初始化投影到目标项目
 - `templates/interactive-ui-round2-experiment.md` — interactive UI prompt/model A/B/C 对照实验与统一指标模板
 - `templates/product-line/` — 可投影的 Feature/Task/QA/Links 产品线包；配合 `agent-worker task validate-feature` 做 docs CI
@@ -72,9 +86,14 @@
 文档变更后运行：
 
 ```bash
+node bin/loop-agent.js docs audit --repo-root .
+bash scripts/check-doc-index.sh
+bash scripts/check-doc-links.sh
 bash scripts/check-repo.sh
 ```
 
+涉及 `website/docs/` 时再跑 `npm run docs:build`，并按 `skills/loop-agent/references/docs-converge.md` 同步 `overview/roadmap.md` 等站上活页。
+
 Windows 上通过 Git Bash 或已配置的兼容 Bash 运行脚本。实际文件操作使用平台原生路径；`/` 仅用于 repo 引用、JSON/Markdown 证据引用和 glob 约定。
 
 完整本地门禁：

package/docs/agent-dag-recovery-playbook.md

@@ -15,7 +15,7 @@ product_line_failure_category
 recommended_follow_up
 ```
 
-Product-line taxonomy 定义见 `design/state-and-failure-taxonomy.md`。
+Product-line taxonomy 定义见 `docs/design/state-and-failure-taxonomy.md`。
 
 **非目标（本 playbook 不覆盖、runner 不实现）：**
 

package/docs/architecture/README.md

@@ -0,0 +1,26 @@
+# 架构文档索引
+
+本目录是 loop-agent 维护者架构文档入口。每篇文档回答一个具体问题，不重复 `runtime-boundaries.md` 的依赖方向表与 governance-hook 表；遇到契约级事实请回到该文件。
+
+## 阅读路径
+
+建议按以下顺序阅读——先全景，再主路径，再边界/事实，最后路线：
+
+1. `runtime-boundaries.md` — runtime 层边界、依赖方向与治理 hook 的机器校验契约（**先读，是其他文档的边界真源**）。
+2. `system-overview.md` — loop-agent / agent-worker / 治理层 / 外部系统的全景关系。
+3. `dag-execution.md` — Agent DAG 主调用链、rank 调度、executor、skill snapshot、生命周期。
+4. `worker-and-feature.md` — agent-worker 子进程边界、controller identity、Task Pool、Feature 与 Observe。
+5. `facts-and-state.md` — `.harness/` 各根目录、canonical facts、derived read models 与不可变规则。
+6. `evolution.md` — 当前已实现能力 vs 第 3–6 月未来方向（明确标注规划/未实现）。
+
+## 事实与规划的区分
+
+- **当前事实源**：`src/` 源码、发布 CLI、`docs/exec-plans/completed/`、`docs/reports/current-capability-summary.md`、ADR 0001–0003。
+- **规划/设计输入**：`docs/design/`（含 `dynamic-workflow-dag-engine-roadmap.md`、`六个月规划.md`）。这些文件已带 2026-07-14 校准条；凡未兑现的 phase 段落是设计输入，**不是**已实现证明。
+- 凡本目录文档描述未来能力，一律使用「规划 / 未实现 / 前瞻」标签。
+
+## 与其他文档的分工
+
+- 本目录不复制 `runtime-boundaries.md` 的 import 方向表、governance-hook 表与版本化自举边界表，只交叉引用。
+- 用法与操作说明在 `website/docs/`（使用者双树），不在本目录重复。
+- 本目录文档随发布包发布（npm `files` 显式条目 + `docs/init-surface.manifest.json` `packageRequired`），但 **不**投影到目标项目 init surface；目标项目 init 仍只投影语言无关的 `runtime-boundaries.md`。

package/docs/architecture/dag-execution.md

@@ -0,0 +1,134 @@
+# Agent DAG 执行架构
+
+本页说明 Agent DAG 的主调用链、rank 调度、executor、run-owned skill snapshot、decision gate 与 pause/completed 生命周期。命令面与 `test/cli-contract.test.ts` 一致；符号归属以 `src/` 为准。完整 import 边界与 governance hook 见 `runtime-boundaries.md`。
+
+## 主调用链
+
+### 生成 + 校验 + 执行（`dag run-task`）
+
+```text
+src/commands/dag-run-task.ts  runDagRunTask
+  → src/application/dag/generate-task-dag.ts  generateTaskDagUseCase
+      └─ src/workflows/dag/init-hybrid.ts  initHybridDagFromTask     （生成 DagSpec）
+      └─ src/application/dag/validate-dag.ts  validateDagUseCase      （候选 + 最终校验）
+      └─ assertSafeForExecution                               （执行前安全检查）
+      └─ src/application/dag/run-dag.ts  runDagUseCase              （执行）
+```
+
+`generateTaskDagUseCase` 内部先 `initHybridDagFromTask` 生成 `DagSpec`，再调用 `validateDagUseCase` 做候选与最终两次校验，随后 `assertSafeForExecution` 确认 DAG 可安全执行，最后委托 `runDagUseCase` 执行。`runDagRunTask` 还 `export` 了 `assertSafeForExecution` 供命令层复用。
+
+### 直接执行既有 DAG（`run-dag`）
+
+```text
+src/commands/run-dag.ts
+  → src/application/dag/run-dag.ts  runDagUseCase
+      → src/workflows/dag/runner.ts  runDag
+```
+
+`run-dag` 是 top-level 命令，**不**在 `dag` 子树下（与 `dag run-task` 区分）。`runDagUseCase` 是 application 层 typed use-case，`runDag` 是 workflow runtime 核心。
+
+### 校验
+
+```text
+src/commands/dag-validate.ts  runDagValidate
+  → src/application/dag/validate-dag.ts  validateDagUseCase
+```
+
+## rank 调度
+
+拓扑排序与按 rank 执行的符号归属（校准版，勿笼统归到 `runner.ts`）：
+
+| 职责 | 源码入口 | 说明 |
+| --- | --- | --- |
+| 拓扑排序 | `src/workflows/dag/topo.ts` `topoSortToRanks` | Kahn 算法，返回 `string[][]` ranks 并检测环 |
+| 单次 rank 执行 | `src/workflows/dag/scheduler.ts` `executeDagRanksOnce` | rank 间遍历、节点执行编排 |
+| run 主循环 | `src/workflows/dag/runner.ts` `runDag` / `executeDagCheckpoint` | 调用 scheduler + persistence + convergence |
+
+`scheduler.ts` `executeDagRanksOnce` 内每个 rank：
+
+1. `pauseGateRunnable`（满足 `isPauseOnHumanDecisionGate` 的节点，来自 `decision-envelope.ts`）**串行**先跑；任一节点触发 pause 即停止后续。
+2. `regularRunnable` 经 `mapConcurrent` 并发执行，`maxConcurrent` 默认 **4**（`runner.ts` `Math.max(1, opts.maxConcurrent ?? 4)`）。
+3. `rankWriterNodeIds`（`executor === "pi"` && `toolProfile === "write"` && `writePolicy === "exclusive"`）注入同 rank 的不相交 writeSet 上下文（`createExecuteNodeForRank`）。
+4. 依赖未就绪的节点标 `SKIPPED`。
+
+`mapConcurrent` 来自 `src/shared/concurrency.ts`（或等价 shared 工具）。
+
+## executor（Pi-only 受治理 runtime）
+
+- 注册表：`src/workflows/dag/executor-registry.ts`
+  `DEFAULT_DAG_EXECUTOR_REGISTRY = { pi, shell, static }`。
+- schema：`src/workflows/dag/types.ts`
+  `dagNodeExecutorSchema = z.enum(["pi","shell","static"])`；DagNodeExecutor 默认 `"pi"`（`executor: dagNodeExecutorSchema.default("pi")`）。
+- `executor: "cursor"` 在 schema refine 阶段抛 `CURSOR_DAG_EXECUTOR_REMOVED_ERROR`（Pi-only = ADR 0001）。
+- Pi handler 先 `requireModel(input)` 校验已解析 model，再委托 `executeDagPiNode`（`src/executors/dag-pi-executor.ts`）。
+- shell handler = `executeDagShellNode`（`src/executors/shell-executor.ts`）；static handler = `executeDagStaticNode`（`src/executors/dag-static-executor.ts`）。
+
+Executor 不得依赖 commands 或 CLI formatting；Cursor 不在受治理路径（`runtime-boundaries.md` §Executors）。
+
+## run-owned skill snapshot
+
+每个新 DAG run 在首个节点执行前冻结本次注入 prompt 的 skill 集合，保证 live skill 后续被修改/删除/补建不会影响当前 run：
+
+| 步骤 | 源码入口 |
+| --- | --- |
+| 首节点前创建 | `runDag` 调 `createSkillSnapshot({ mode: "run-start" })`（`src/workflows/dag/skill-snapshot.ts`） |
+| 写入产物 | `writeSkillSnapshot(runDir, snapshot)` → `<runDir>/.runtime/skill-snapshot.json`（常量 `SKILL_SNAPSHOT_REL_PATH = ".runtime/skill-snapshot.json"`） |
+| state 只存相对引用 | `state.skillSnapshotRef` = `{ schemaVersion, path: ".runtime/skill-snapshot.json", sha256, createdAt, mode }`，**不**存绝对路径 |
+| resume 续用 | `prepareSkillSnapshotForContinuation`（resume 路径，`src/workflows/dag/runner.ts` `resumeDagRun`） |
+| 完整性校验 | 普通节点、dynamic child、approve/resume 都执行 integrity gate，ref/artifact/profile/binding 不一致即 fail closed，不回退实时解析 |
+| legacy 兼容 | 旧 run 只在 ref 与 artifact 都不存在时可标 `legacy-resume-backfill` 并冻结剩余节点 |
+
+snapshot 与 controller identity 是两个不同冻结层，详见 `runtime-boundaries.md` §版本化自举边界。
+
+## decision gate 与 pause
+
+- `isPauseOnHumanDecisionGate`（`src/workflows/dag/decision-envelope.ts`）：`task.decisionGate?.mode === "pause-on-human"` 且 decision gate 启用时，该节点在 rank 内**串行先跑**。
+- `shouldPauseOnHumanEscalation`（`decision-envelope.ts`，在 `src/workflows/dag/node-execution.ts` 调用）：decision envelope 判定需人工升级时，写 `human-escalation.json`（与 `human-escalation.md`）并触发 pause。
+- pause 时 `state.pausedByNodeId` + `pauseReason` + `humanDecisionNodeId` 被写入；`human-escalation.json` 落在 `<runDir>/<nodeId>/`。
+
+decision envelope 中的 **model verdict**（`decision` / `riskLevel` 等解析自文本）是 `advisoryOnly: true` 派生视图，**不**是完成权威（`facts-and-state.md`）。
+
+## 生命周期：active / paused / completed
+
+`src/workflows/dag/lifecycle.ts` 定义三个目录：
+
+| 目录 | 写入规则 |
+| --- | --- |
+| `.harness/dag-runs/active/<runId>/` | run 进行中 |
+| `.harness/dag-runs/paused/<runId>/` | 触发 pause；resume 需 `human-approval.json` |
+| `.harness/dag-runs/completed/<runId>/` | 终态；除 runner 终态写外只读（`completed-facts-guard.ts`） |
+
+扫描顺序：`DAG_LIFECYCLE_SCAN_ORDER = ["paused", "active", "completed"]`（locate/status 等按此顺序解析 runId）。
+
+关键规则：
+
+- **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 始终只读。
+- **status 枚举**：`DagRunState.status`；`TERMINAL_RUN_STATUSES` 判终态；`isTerminalDagRunStatus` 工具函数。
+
+## convergence（可选、supervised）
+
+- 控制器：`src/workflows/dag/convergence/controller.ts` `runConvergencePassController`，在 runner rank 间被调用。
+- 特性默认 **off**（`task/config-types.ts` `convergence` 默认 `{ enabled: false }`）。
+- 启用后按 `maxPasses`（默认 3）做多轮 repair，回归时可 `pauseOnRegression`。
+- 产物落在 `<runDir>/convergence/pass-<n>/`。
+
+## 完成权威 = shell verification
+
+完成声明的权威是 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。
+
+## Dynamic Workflow
+
+Dynamic Workflow 是 DAG runtime 上方的逻辑编排/编译层，**不**重写 runner：
+
+```text
+WorkflowSpec (src/workflows/dynamic/spec.ts workflowSpecSchema)
+  → validate (src/workflows/dynamic/validate.ts)
+  → compile (src/workflows/dynamic/compile.ts compileWorkflowToDag) → DagSpec
+  → 同一 run-dag 执行
+```
+
+- 动态语义：`map_agent` / `verify_agent` / `reduce_agent` / `condition` / `loop_until` / `human_gate` / `command` / `artifact_transform`。
+- agent-like 节点 executor 仅 `pi` | `static`（schema 已不含 `cursor`）。
+- 未完全兑现的 runtime limits 强执法、更广 profile、Loop 原生 `workflow` action 深度编排等仍是**设计输入**，见 `docs/design/dynamic-workflow-dag-engine-roadmap.md`（带 2026-07-14 校准条）。

package/docs/architecture/evolution.md

@@ -0,0 +1,52 @@
+# 架构演进：当前 vs 未来
+
+本页区分 loop-agent **当前已实现**的架构能力与**未来规划**。当前事实以代码、发布 CLI、已完成计划为准；未来能力一律标「规划 / 未实现 / 前瞻」。权威源：`CHANGELOG.md`、`docs/reports/current-capability-summary.md`、ADR 0001–0003、`docs/exec-plans/completed/`。
+
+## 当前已实现（0.10.0 + 主干 Unreleased）
+
+| 域 | 现状 | 权威入口 |
+| --- | --- | --- |
+| 受治理 Agent runtime | **Pi-only**；`cursor-prompt` 仅显式 one-shot sidecar | ADR 0001、`CHANGELOG.md [0.10.0]` |
+| Agent DAG 主链 | `dag run-task` → generate → validate → `run-dag`；report/doctor/reconcile-run | `dag-execution.md`、`test/cli-contract.test.ts` |
+| Dynamic Workflow | `WorkflowSpec` → validate → compile → 同一 `run-dag`；agent-like 节点仅 `pi\|static` | `src/workflows/dynamic/{spec,validate,compile}.ts`、`website/docs/guides/dynamic-workflow.md` |
+| 版本化自举 | controller identity + run-owned skill snapshot + deterministic canary | `docs/reports/2026-07-13-versioned-self-hosting-bootstrap.md` |
+| Feature 交付（M2） | review/run/approve-followup/delivery/closeout/verify-final | `docs/reports/2026-07-12-m2-completion-audit.md` |
+| Task Pool | 唯一根 `.harness/task-pool/` | ADR 0002 |
+| Observe | 本地只读暖白控制台（derived） | `website/docs/guides/observe-ui.md` |
+| 文档双树 | `website/docs/` 用法 vs `docs/` 治理；docs-converge | ADR 0003 |
+| 文档治理 | `docs/architecture/` 主题文档（本目录）+ package 可达 | 本目录 README |
+
+### 受治理 runtime 的边界（已实现、不变式）
+
+- DAG writer 固定 `implement-pi` / `repair-pi`；`executor: "cursor"`、`implement-cursor` / `repair-cursor`、Cursor worker、`cursor-fix` 已从受治理路径移除。
+- 完成权威 = shell verification；model verdict / Observe / 报告是 derived/advisory。
+- Worker 通过已发布 `loop-agent` 子进程执行，不 in-process import runtime kernel（governance 机器校验）。
+
+## 未来规划（第 3–6 月，**未实现**）
+
+以下能力来自 `docs/design/六个月规划.md` 与 `docs/design/dynamic-workflow-dag-engine-roadmap.md`（两文件均带 2026-07-14 校准条，未交付 phase 为**设计输入**，不是已实现证明）。它们**当前不存在于代码或 CLI**：
+
+| 未来方向 | 状态 | 规划来源 |
+| --- | --- | --- |
+| 远程 PR / CI | 规划 / 未实现 | `docs/design/六个月规划.md`（第 3 个月起） |
+| 线上 / 云 Worker | 规划 / 未实现 | 同上 |
+| 云 Task Pool / SQL / Orchestrator | 规划 / 未实现 | 同上（第 2 月原始设计已调整为本地 Feature 闭环） |
+| 多仓库平台 | 规划 / 未实现 | 同上 |
+| 组织级服务 | 规划 / 未实现 | 同上 |
+| Web Console（远端） | 规划 / 未实现 | 同上 |
+| Dynamic Workflow runtime limits 强执法、更广 profile | 设计输入 | `docs/design/dynamic-workflow-dag-engine-roadmap.md`（未勾选 phase） |
+| Loop 与 Dynamic Workflow 更深的双向集成、稳定化与自动恢复 | 设计输入 | 同上；当前已有基础 `workflow` action，不应误写为完全缺失 |
+
+> 注意：`docs/design/dynamic-workflow-dag-engine-roadmap.md` 是 2026-07-04 历史叙述；文中凡把 Cursor 写成受治理 executor 或 `loop` 的 `cursor-fix` 动作，均为**历史叙述**，现状以 Pi-only + 显式 `cursor-prompt` sidecar 为准。
+
+## 已收敛为 archive / 历史基线（非未来）
+
+- 第 1–2 月规划已收敛为 archive/reports 指针，不在本文展开：`docs/design/archive/2026-07-12-第二月规划.md`。
+- `docs/reports/2026-07-02-repository-analysis.md` 自 2026-07-14 起冻结为**历史基线快照**，不再滚动追加 Unreleased 能力。
+- 活能力短摘要在 `docs/reports/current-capability-summary.md`。
+
+## 文档本体的演进边界
+
+- 本目录新增文档随发布包发布（`package.json` `files` + manifest `packageRequired` 显式条目），但 **不**投影到目标项目 init surface（AC-7）；目标项目 init 仍只投影语言无关的 `runtime-boundaries.md`。
+- `runtime-boundaries.md` 是边界真源；本目录其他文档交叉引用，不复制其 import 方向表 / governance-hook 表 / 版本化自举边界表。
+- 未来如有能力落地，应先改 `src/`/CLI/ADR/completed plan，再回写本目录的「已实现」表。

package/docs/architecture/facts-and-state.md

@@ -0,0 +1,58 @@
+# 事实与状态
+
+本页说明 `.harness/` 各根目录、canonical facts、derived read models 与不可变规则，并逐条标出 canonical|derived 与 writable|read-only。完成权威是 shell verification（ADR 0001）；model verdict、Observe、报告都是 derived 或 advisory 视图。
+
+## 六类运行态对象
+
+| 对象 | 物理根 | 源码入口 | 性质 |
+| --- | --- | --- | --- |
+| Task | `.harness/tasks/<taskId>/` | `src/task/runtime.ts` `getTaskDir` | canonical，可写 |
+| DAG run | `.harness/dag-runs/{active,paused,completed}/<runId>/` | `src/workflows/dag/lifecycle.ts` `DAG_RUNS_DIR` | canonical，active/paused 可写；completed 受 guard |
+| one-shot run | `.harness/runs/{active,completed,failed}/<slug>/` | `src/infrastructure/harness/one-shot-run-store.ts`（逻辑封装见 `src/records/one-shot-runs.ts`） | canonical；active 可写，completed/failed 为终态事实 |
+| Loop | `.harness/tasks/<taskId>/loop/` | `src/workflows/loop/**` | canonical，**不是独立根**，是 task 之上的多轮状态机 |
+| Task Pool | `.harness/task-pool/`（唯一根） | `src/worker/pool/run-store.ts` `TASK_POOL_RELATIVE_ROOT`（ADR 0002） | canonical，可写（Worker 专用，可选） |
+| Observe snapshot | Worker 内存/HTTP 派生视图 | `src/worker/observability/read-model.ts` `buildGlobalSnapshot` | **derived**，advisory |
+
+### 区分要点
+
+- **Task vs DAG run**：Task 是用户意图的源（`source/`、需求、执行约束、artifacts）；DAG run 是一次执行实例，`<runId>/` 下落 spec、state、节点 artifacts、skill snapshot、decision envelope、convergence。
+- **DAG run vs one-shot run**：DAG run 在 `.harness/dag-runs/`，有三态 lifecycle；one-shot run（当前主要由 `cursor-prompt` 及显式 one-shot evidence 路径产生）在 `.harness/runs/`，三态为 `active|completed|failed`。`pi-prompt` 当前不创建该目录下的 run evidence。两者是不同根、不同 schema。
+- **Loop 不是顶层根**：Loop 状态在 `.harness/tasks/<taskId>/loop/`，是 task 之上的多轮状态机（round、signal、context、failureStreak、closeout）。
+- **Task Pool 是 Worker 专用可选根**：只有使用 `agent-worker` 产品线时才存在；唯一根 `.harness/task-pool/`。
+- **Observe snapshot 不是事实源**：`buildGlobalSnapshot` 投影失败返回安全错误摘要而非全零健康，不改变执行成败。
+
+## canonical（可写）
+
+- `.harness/tasks/<taskId>/` — `getTaskDir`。
+- `.harness/dag-runs/{active,paused}/<runId>/` — run 进行中 / 暂停。
+- `.harness/runs/active/<slug>/` — one-shot 运行中；完成或失败后通过 store 迁移到终态目录。
+- `.harness/tasks/<taskId>/loop/` — Loop 状态机。
+- `.harness/task-pool/` — Worker Task Pool（可选）。
+
+`.harness/prompts/` 与 `.harness/init-surface.json` 属于初始化投影/控制资料，不是一次执行的 canonical run fact，需与上面的任务和 run 对象区分。
+
+## canonical（只读 / 不可变）
+
+- `.harness/dag-runs/completed/<runId>/` — 除 runner 终态 `persistState({ allowCompletedFactsWrite: true })` 与显式 `dag reconcile-run`（`--action supersede|abandon` + reason，runner 已证明停止）外只读。
+- `.harness/runs/completed/<slug>/` 与 `.harness/runs/failed/<slug>/` — one-shot 终态事实；公共写接口只对 active run 开放，完成/失败通过 store 迁移。
+- `completed-facts-guard.ts`（`src/infrastructure/harness/`）是 completed 路径 enforcement 入口：`assertHarnessWriteAllowed(targetPath, { repoRoot, allowCompletedFactsWrite? })`。
+- promotion（completed → task artifacts 回填）由 `src/records/promotion.ts` 经 `loadCompletedDagEvidence` 读 completed state 后写 task artifacts。
+
+## derived / advisory（不可作完成权威）
+
+| 视图 | 来源 | 为何不可作权威 |
+| --- | --- | --- |
+| Observe snapshot / 首页 KPI | `buildGlobalSnapshot` 投影 `.harness/` + Task Pool | derived；投影失败安全降级 |
+| decision envelope 的 model verdict | `decision` / `riskLevel` 解析自文本 | `advisoryOnly: true`（`decision-envelope.ts` / `decision-evidence.ts` / `lifecycle.ts`） |
+| canvas / event observer | `notifyRunObserver` / `notifyNodeObserver` | try/catch 吞；明确派生视图，不 affect canonical 执行 |
+| DAG report / doctor | `src/application/dag/report-dag.ts` + `src/workflows/dag/report.ts`；doctor 在 `src/workflows/dag/lifecycle.ts` | 只读总结，operator 决策辅助 |
+| knowledge-curator proposal | `src/workflows/dag/knowledge-curator.ts` | advisory process guidance，不改 accepted learned skill |
+| morning report / metrics | `src/worker/report/**` | derived 统计，含分母/样本量/缺失说明 |
+
+## 完成权威
+
+完成权威 = shell command 的 exit code 与归档 stdout/stderr。执行入口是 `src/executors/shell-executor.ts`，环境/preset helper 在 `src/executors/shell-verification.ts`；`node.verifyEvidence` 保存 DAG authoring 提供的验证阶段、命令来源与标签等元数据。model verdict、Observe、报告都不构成完成判定。
+
+## init 投影的 `.harness` 入口
+
+`init --profile full` 在目标项目创建 `.harness/tasks`（directory）、`.harness/dag-runs/active`（directory）、`.harness/prompts/analyze.md`（generated）、`.harness/init-surface.json`（state）。这些是 init surface，不在 `packageExcluded`/`initExcluded` 范围；详见 `docs/init-surface.manifest.json`。