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

package/docs/architecture/README.md

@@ -0,0 +1,35 @@
+# 架构文档索引
+
+本目录是 loop-agent 维护者架构文档入口。每篇文档回答一个具体问题，不重复 `runtime-boundaries.md` 的依赖方向表与 governance-hook 表；遇到契约级事实请回到该文件。
+
+**维护日：2026-07-27** — 索引与演进叙述对齐仓库头 `@tea-agent/loop-agent@0.24.0`。边界表仍以 `runtime-boundaries.md` 与 `scripts/check-*.sh` 为准。
+
+## 阅读路径
+
+建议按以下顺序阅读——先全景，再主路径，再边界/事实，最后路线：
+
+1. `runtime-boundaries.md` — runtime 层边界、依赖方向与治理 hook 的机器校验契约（**先读，是其他文档的边界真源**）。
+2. `agents-invariants.md` — `AGENTS.md`（source）与 init managed block 的「什么不能删」不变量契约（短语真源 + 行数 guardrail 语义）。
+3. `system-overview.md` — loop-agent / agent-worker / 治理层 / 外部系统的全景关系。
+4. `dag-execution.md` — Agent DAG 主调用链、rank 调度、executor、skill snapshot、生命周期。
+5. `worker-and-feature.md` — agent-worker 子进程边界、controller identity、Task Pool、Feature、Observe 与 Console。
+6. `facts-and-state.md` — `.harness/` 各根目录、canonical facts、derived read models 与不可变规则。
+7. `evolution.md` — 当前已实现能力 vs 第 3–6 月未来方向（明确标注规划/未实现）。
+8. `state-and-failure-taxonomy.md` — Task Pool、DAG、Loop 与报告共用的 canonical 状态/失败分类。
+9. `taskspec-to-loop-agent-mapping.md` / `.yaml` — TaskSpec 到 worker/runtime 的兼容合同与机器可读镜像。
+10. `knowledge-graph-and-query-spec.md` — 业务知识图谱、knowledge-links 与查询协议。
+11. `testing-knowledge-base-impl-spec.md` — 测试知识库 schema、ID、读写矩阵和校验规则。
+
+## 事实与规划的区分
+
+- **当前事实源**：`src/` 源码、发布 CLI、`docs/exec-plans/completed/`、`docs/reports/current-capability-summary.md`、ADR 0001–0005。
+- **规划/设计输入**：`docs/design/`（含 fullstack / Console / 六个月规划等）。页首校准条与 completed plan 未背书前，**不是**已实现证明。
+- 目标项目初始化后，治理根目录通常为 `ai_workspace/loop-agent/`（与本源仓 `docs/` 同源契约投影）；站上用法在 `website/docs/`。
+- 凡本目录文档描述未来能力，一律使用「规划 / 未实现 / 前瞻」标签。
+
+## 与其他文档的分工
+
+- 本目录不复制 `runtime-boundaries.md` 的 import 方向表、governance-hook 表与版本化自举边界表，只交叉引用。
+- 用法与操作说明在 `website/docs/`（使用者双树），不在本目录重复。
+- 产物索引：`docs/exec-plans/*`、`docs/progress/`、`docs/reports/`（reports 按类型子目录；见各目录 README）。
+- 本目录文档随发布包发布（npm `files` 显式条目 + `docs/init-surface.manifest.json` `packageRequired`），但 **不**投影到目标项目 init surface；目标项目 init 仍只投影语言无关的 `runtime-boundaries.md`。

package/docs/architecture/dag-execution.md

@@ -0,0 +1,165 @@
+# 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
+```
+
+### runtime contract preflight、repair writer 与 Task Contract binding
+
+- `src/workflows/dag/runtime-contract.ts` `assertRuntimeContractCompatible` 依据 controller capabilities（`DAG_CONTROLLER_CAPABILITIES`：`agentRuntime="pi-only"`、`repairWriterProtocol="explicit-node-v1"`）校验 DagSpec v3 必需的 `runtimeContract`。v3 让旧 controller 在解析阶段拒绝；新 controller 的 `validateDagUseCase`、`runDagUseCase`、`runDag` 与 resume 还会校验 capability 和可选最低版本，不兼容在任何节点执行前 fail-fast。legacy v1/v2 DagSpec 可读但没有 v3 握手。
+- **DagSpec v4（0.17.0+）**：新 writer 生成默认携带 `taskContractBinding`（managed Task Contract）。exclusive writer（`writePolicy: "exclusive"`）启动门禁要求 v4 binding；只读 / static / shell 历史 DAG 可继续执行。operator capabilities 声明 `generatedSpecVersion: 4` 与 binding schema（`src/shared/operator/capabilities.ts`）。CLI 面见 `loop-agent task contract *` 与 Console confirm-run。
+- `src/workflows/dag/repair-artifact.ts` `resolveRepairTaskForGate` 解析 `shell.repairArtifactGate`：优先显式 `repairNodeId`，否则推导唯一的下游受治理 Pi writer（`repairWriterContractIssues` 校验 executor/toolProfile/writePolicy/path 契约）。`validate.ts` 与 `node-execution.ts` 复用同一 resolver，runtime 不再按节点名硬编码。
+- `src/workflows/dag/controller-identity.ts` 在 run 创建前要求 controller identity 可解析，再由 `captureControllerIdentity` 冻结到 `<runDir>/controller-identity.json`；`verifyControllerIdentityForResume` 在 resume 前重新校验并对漂移、篡改或 legacy-unpinned run fail closed。
+
+### 专用 taskKind 与模板选择（架构摘要）
+
+- `initHybridDagFromTask` 按 `task.json.taskKind`（及前端需求自动分类）选择专用拓扑：`frontend-implementation`、`frontend-test`、`backend-test`、`knowledge-sync`、`knowledge-graph-bootstrap` 等；默认 `standard` 走 governance profile 通用实现链。
+- **backend-test（0.17.x）**：Markdown-first 固定短链（环境硬门 → Markdown 用例/Review → 单次 pytest + HTML → 报告与 L-5）；不在本页展开节点清单，见 `docs/runtime/backend-test-workflow.md` 与 completed markdown-first plan。
+- 专用模板不是新的 governance profile：风险等级仍由 profile 规则判断；写边界仍受 `allowedPaths` / `forbiddenPaths` / `writeSet` 约束。
+
+## 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`）。
+
+## 自适应 liveness（节点活动 vs runner lease）
+
+实现见 `src/workflows/dag/liveness-policy.ts` 与设计文档 `docs/design/active/dag-adaptive-liveness-and-supervision.md`。
+
+- **runner lease**（`runner.heartbeatAt`，约 15s）只证明 runner 进程事件循环；**不是** Pi meaningful progress。
+- **真实活动**：SDK provider/tool event 与 CLI stdout|stderr 刷新 provider/tool/output；attempt-fenced，旧 attempt 晚到事件 no-op。SDK noisy delta 只续租 transport watchdog，不刷新 meaningful progress。
+- **节点投影** `livenessStatus`：`active | quiet | suspected-stall | probing | needs-attention`。
+- **absolute max** 默认 4h wall clock（不可被空心跳续期）；历史 30 分钟不再是活跃 Pi 节点硬杀边界。
+- `assessDagRunLiveness` 在 lease 新鲜但无 meaningful activity 时返回 `node-quiet` / `suspected-stall` / `needs-attention`；doctor codes 含 `node-activity-quiet`、`node-activity-suspected-stall`、`node-needs-attention`。
+- Observe/read-model 仅为 derived/advisory。
+
+## 生命周期：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/`。仍为 `RUNNING` 的节点保持失败语义，但以 `reconciledAt - startedAt` 补齐节点和当前 attempt 的耗时，原始状态继续冻结在 `reconciliation.json`。它不是修改既有 completed history 的通用入口。Observe / status / doctor 始终只读。
+- **status 枚举**：`DagRunState.status`；`TERMINAL_RUN_STATUSES` 判终态；`isTerminalDagRunStatus` 工具函数。
+
+## convergence（supervised 默认启用、有界自愈）
+
+- 控制器：`src/workflows/dag/convergence/controller.ts` `runConvergencePassController`，在 runner rank 间被调用。
+- supervised 路径的 convergence 由 task `maxFixLoops` 派生（`init-hybrid.ts` `resolveSupervisedConvergence`）：`maxFixLoops > 0` ⇒ `enabled: true`、`maxPasses = maxFixLoops + 1`（初次执行 + 修复预算）、`chainNodeIds` 覆盖 `process-supervisor-pi → process-gate-shell → repair-pi → hard-verify-shell → review-pi → review-verdict-recovery-pi → review-gate-shell`；`maxFixLoops === 0` ⇒ `enabled: false`。task-level `convergence` config 仍默认 `{ enabled: false }`（opt-in），不会被 supervised 路径以外的模板启用。
+- 触发源：hard verify 可恢复失败（`nonzero-exit` 等）与 review 合法 `request-revision`（`review-gate-shell` ERROR）进入同一有界恢复链；两者都套用 non-retry / regression / max-passes 守卫。
+- 重算边界：进入下一轮时重置 convergence chain，以及 `hard-verify-shell` 的完整后代闭包（包括已 `FINISHED` 的 authority/governance 节点与 failure-aware closeout），防止修复后复用首轮陈旧治理或交接证据。
+- 证据回灌：每轮 pass 记录写入 `state.convergence.passHistory`，并归档到 `<runDir>/convergence/pass-<n>/`；下一轮 supervisor/repair 的 prompt 确定性注入上一轮失败类别、review verdict、repairArtifact 摘要与 `convergence/pass-<n>/<node>.json` 证据指针（`prompt.ts` `formatConvergenceFeedbackBlock`），并对列表项数、单项长度和完整 block（4000 字符）设置硬上限，不依赖搜索 run 目录。
+- 安全失败不重试：`write-guard` / `auth` / `missing-api-key` / `human-rejected` / `decision-gate-requires-human` / `timeout` / `spawn-error` 继续 fail-closed。
+- 非 supervised 模板（未声明 `chainNodeIds` 且无 `review-gate-shell`）保持原 hard-verify-only 行为。
+
+## 完成权威 = 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。
+
+supervised 的 `soft-verify-shell` 只运行聚焦命令，明确排除无参数的 `npm test`、`npm run test` 与 `scripts/ci.sh` 等 full-suite 入口；`hard-verify-shell` 保留一次完整 final 集合。task 与 adapter 命令合并时会解包可证明安全的单命令 `bash -lc` wrapper，并以规范化 cwd、argv、env、timeout 做语义去重；`verifyEvidence.commandCount/commandLabels/commandTexts` 必须对应去重后实际执行的命令。
+
+Pi SDK 正常路径继续在内存中传递 system prompt；只有 CLI fallback / `cli-only` 才通过权限收紧的系统临时文件传给 `--append-system-prompt`，归档命令只保存占位符。transport 解析并记录真实 temp root，持有 prompt 文件句柄，并冻结 temp root、随机私有目录、固定文件名三层 identity；收口时先用句柄清空正文，三层 identity 均匹配才精确 `unlink` 文件并非递归 `rmdir` 空目录。未知 sibling、symlink/junction 或 identity 漂移都会拒绝扩大删除范围。shell 与 Pi 子进程以独立进程组启动；超时在 Windows 使用 tree termination、在 POSIX 对进程组发信号，防止 npm/Vitest/tsx 后代在节点结束后继续持有 IPC 或临时文件。
+
+## Dynamic Workflow
+
+Dynamic Workflow 是 DAG runtime 上方的逻辑编排/编译层，**不**重写 runner：
+
+```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 深度编排等仍是**设计输入**，见 `ai_workspace/loop-agent/design/dynamic-workflow-dag-engine-roadmap.md`（带 2026-07-14 校准条）。

package/docs/architecture/evolution.md

@@ -0,0 +1,108 @@
+# 架构演进：当前内核与未来边界
+
+本文区分 `loop-agent` 当前已实现架构和第 3–6 月前瞻。当前事实以代码、`CHANGELOG.md`、`docs/reports/current-capability-summary.md` 与 completed/active plans 为准；路线以 `docs/design/active/六个月规划.md` 为准。
+
+对照版本：`@tea-agent/loop-agent@0.35.3`（2026-08-16）。
+
+## 当前架构
+
+```text
+Skills / AGENTS
+      ↓
+loop-agent CLI → application use cases → workflow runtime → Pi/Shell/Static executors
+      ↓                                  ↓
+task source / contracts              run-owned facts / artifacts / receipts
+
+agent-worker CLI / Console
+      ↓ frozen published controller subprocess
+loop-agent CLI
+```
+
+### 已实现能力
+
+| 域 | 当前事实 | 权威入口 |
+| --- | --- | --- |
+| 标准生命周期 | `task advance` 是唯一标准 mutation 入口；`task status` 只读；run 级 `dag` 命令保留为 advanced recovery/forensic | ADR 0008、`docs/governance/feature-workflow.md` |
+| DAG kernel | Contract/Scout/Plan/Implement/Verify/Closeout；dynamic workflow、pause/resume、doctor/report/rerun/reconcile | `dag-execution.md`、`agent-dag-runner.md` |
+| 写入与契约 | Pi-only writer、Task Contract、DagSpec v4 binding、writeSet review、writer admission、write guard | ADR 0001、`runtime-boundaries.md` |
+| 专用 taskKind | `frontend-implementation`、`backend-test`、`frontend-test`、knowledge 路径；显式 taskKind 贯穿 intake→task→DAG | `CHANGELOG.md [0.35.0]`–`[0.35.3]` |
+| Backend test | map-shard、execution readiness、generated-output conflict、collection/pytest 结构化失败、恢复加固 | completed plans、`CHANGELOG.md [0.30.0]`–`[0.31.1]` |
+| Frontend implementation | canonical prewrite result、两层 writer gate、统一 writer helper、rollback journal、child recovery、root manifest | completed `2026-08-13-frontend-implementation-dag-optimization.md` |
+| Frontend test | lean 默认 DAG、case map、evidence/quality report；安全边界 hard gate，内容质量 advisory | completed `2026-08-07-frontend-test-dag-lean-nodes.md` |
+| Worker / Feature | TaskSpec、feature-scoped Task Pool、Ready Planner、Outcome、Verification Bundle、Delivery/Closeout | `worker-and-feature.md`、current capability summary |
+| Worker readiness baseline | Attempt identity、immutable owner、lineage/revision、task-scoped lease、controller protocol、acceptance、reconcile | Agent Worker PR v1 Phase 1–7 / `0.32.0` |
+| Operator Surface | 裸 `agent-worker console`；Operate、`/inspect/`、Operator Chat、recovery CTA、intake bridge | ADR 0005、0011–0013 |
+| 自举与验证 | controller identity、skill snapshot、deterministic/live canary、verified tarball、`verify:tree` receipt | `runtime-boundaries.md`、verification matrix |
+
+### 当前不变量
+
+- `loop-agent` 拥有 repo-local DAG kernel；`agent-worker` 通过冻结的已发布 CLI 子进程执行，不复制内核。
+- 受治理 Agent writer 只有 Pi；`cursor-prompt` 只是显式 one-shot sidecar。
+- shell verification / Final Verification 是完成权威；模型 verdict 与 UI projection 不是。
+- Console 是本地 loopback 控制面；canonical mutation 仍经 sibling CLI/application contract。
+- controller identity 和 run-owned skill snapshot 分属不同冻结层，不能互相替代。
+- recovery 必须保留原始终态并生成显式 reconciliation/continuation 事实。
+
+完整 import 与 runtime 依赖规则见 `runtime-boundaries.md`，本文不复制其机器校验表。
+
+## 当前尚未 Ready
+
+| 项目 | 状态 |
+| --- | --- |
+| Agent Worker PR v1 Phase 8 | `NOT_READY`：burn-in、live Closeout、C4/C7 crash 未收口；live Pi canary 已验证 |
+| Fullstack release train | I40 Delivery/Closeout live；FC-B orphan recovery failed，overall=partial |
+| Operator Chat primary session | 主体能力已发布；event recovery / dogfood 门槛仍 open |
+| frontend-test | formal V7 smoke 与独立成功率报告 open |
+| backend-test | 真实 provider 五路径 smoke blocked-external |
+
+## 下一阶段目标架构
+
+未来能力不直接塞入当前 runtime，而是增加两个外层边界：
+
+```text
+Organization Control Plane
+  Feature Graph / Queue / Policy / Approval / Remote Adapters
+                     ↓ assignment + lease
+Isolated Execution Plane
+  Workspace Manager / published loop-agent / repo-local agent-worker projection
+                     ↓ immutable refs + receipts
+Evidence & Trust Plane
+  Artifact Manifest / Git & CI Receipts / Audit / Metrics / SLO
+```
+
+### 演进顺序
+
+| 阶段 | 新边界 | 不能破坏的旧边界 |
+| --- | --- | --- |
+| 远程交付 | Git/PR/CI adapter、head-bound receipt、approval | repo-local writer gate 与 verification authority |
+| 隔离 Worker | workspace lease、fencing、credential/network policy、artifact projection | frozen controller 与 DAG run facts |
+| 跨仓库 Feature | repo-qualified TaskRef、contract hash、saga/compensation | 每仓库独立 Task/PR/CI/terminal state |
+| 生产治理 | versioned policy、audit、SLO、semi-auto lane | owner opt-in、可撤销授权、fail-closed |
+
+### 未来合同
+
+- `AssignmentEnvelope`
+- `WorkspaceLease`
+- `ControllerAttestation`
+- `GitMutationReceipt`
+- `CiRunReceipt`
+- `ArtifactManifest`
+- `PolicyDecision`
+- `FeatureCloseout`
+
+这些对象必须先有 schema、fixture、verifier、失败语义和 ADR，再接真实 provider。
+
+## 仍属前瞻、禁止写成已交付
+
+- 自动远程 push / PR / CI / merge。
+- 线上队列、容器 Worker Pool、多租户与跨 region 调度。
+- 组织级凭据代理、策略服务与审计服务。
+- 跨仓库原子交付；目标模型是 saga 与补偿，不是伪全局事务。
+- Eval Lab auto-promote、默认自动 merge、自动发布或 RSI Level 1。
+
+## 文档演进规则
+
+1. 新能力先由代码、测试、live campaign、completed plan 或正式报告证明。
+2. 证明成立后更新 current capability summary 和本页“当前架构”。
+3. 未证明部分只保留在 active design/exec-plan，不能通过修改措辞升级状态。
+4. 使用者短索引同步到 `website/docs/overview/roadmap.md`，避免复制长版本流水账。

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

@@ -0,0 +1,74 @@
+# 事实与状态
+
+本页说明 `.harness/` 各根目录、canonical facts、derived read models 与不可变规则，并逐条标出 canonical|derived 与 writable|read-only。完成权威是 shell verification（ADR 0001）；model verdict、Observe、报告都是 derived 或 advisory 视图。
+
+**维护校准：2026-07-22** — Task Contract / Console 不改变「完成权威 = shell」；managed contract 与 DagSpec binding 是启动/漂移门禁，不是 verification 替代物。
+
+## 六类运行态对象
+
+| 对象 | 物理根 | 源码入口 | 性质 |
+| --- | --- | --- | --- |
+| 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/`（唯一根；state v2 见下） | `src/worker/pool/run-store.ts` `TASK_POOL_RELATIVE_ROOT`（ADR 0002 / 0004） | 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、controller identity（`controller-identity.json`，冻结执行 controller 的 package version/binary 哈希/portable fingerprint，state 记录相对 ref 与内容哈希，resume 时重新校验、漂移 fail closed）、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/`。
+- **Task Pool state identity（ADR 0004）**：canonical 键为 `{ featureId, taskId }`（`TaskPoolTaskRef`），不是裸 `taskId`。
+- **Observe snapshot 不是事实源**：`buildGlobalSnapshot` 投影失败返回安全错误摘要而非全零健康，不改变执行成败。
+- **节点 liveness 投影是保守 canonical 字段**：`lastProviderActivityAt` / `lastToolActivityAt` / `lastOutputActivityAt` / `lastMeaningfulProgressAt` / `livenessStatus` 由 runner/executor 写入 active run facts；runner lease heartbeat **不得**刷新 meaningful progress。Observe badge（quiet/suspected-stall/needs-attention/needs-reconcile）仍是 derived。
+
+### Task Pool state 布局与迁移
+
+| 路径 / 对象 | 性质 | 说明 |
+| --- | --- | --- |
+| `.harness/task-pool/states/<featureId>/<taskId>.json` | canonical 可写 | schema v2；路径解码 identity 必须与文件内容一致 |
+| `.harness/task-pool/states/<taskId>.json`（扁平 v1） | legacy | 不得静默猜 Feature；存在时 v2 写入 fail-closed |
+| `.harness/task-pool/runs.jsonl` / `events.jsonl` | canonical append-only | migration 不改写 JSONL；`workerRunId` 仍是执行历史键 |
+| `agent-worker pool doctor` | 只读诊断 | inventory + mapping 证据；exit 0 可有 findings |
+| `agent-worker pool migrate-state` | 显式迁移 | 默认 dry-run；`--apply --owner --reason` 才写入；失败全回滚 |
+
+`readFeatureTaskPoolStates` / `listTaskPoolStates` 是 v2 列表入口；deprecated `readAllTaskPoolStates` 仅扫描 legacy 扁平 state，不合并 v2。
+
+## 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` 范围；详见 `ai_workspace/loop-agent/init-surface.manifest.json`。

package/docs/architecture/runtime-boundaries.md

@@ -0,0 +1,226 @@
+# Runtime Boundaries
+
+本文定义 loop-agent 各 runtime 层的 module interface、允许的依赖方向，以及治理检查 hook。目标是把命令、文档、import 架构、controller identity 与 run-owned execution facts 收敛为可机器校验的边界契约。
+
+## 分层概览
+
+```text
+Skill layer
+  ├─ DAG/runtime 入口策略（.agents/skills/loop-agent/）
+  └─ Feature/Task Pool 外层 operator 路由（.agents/skills/agent-worker/）
+
+CLI layer (src/cli/)
+  └─ argv 解析、adapter 解析、调用 application / command handler、格式化输出
+
+Init-upgrade command layer (src/commands/init-upgrade.ts)
+  └─ controller-owned init-upgrade state machine、frozen identity、target `.harness/init-upgrades/` facts、safe action receipts and bounded merge contracts
+
+Application layer (src/application/，逐步引入)
+  └─ 一次用户意图的 typed use-case interface，供 CLI、Loop、Workflow 复用
+
+Workflow runtime (src/workflows/)
+  └─ DAG / Dynamic / Loop 核心执行规则；不应依赖 commands
+
+Verification planners (src/verification/)
+  └─ 生成期/执行期验证规划（如 Maven workspace 静态图与冻结计划）；纯库模块，不跑 CLI
+
+Executors (src/executors/)
+  └─ Pi / Shell / Static 等受治理外部工具适配；不应依赖 commands 或 CLI formatting
+
+Sidecars (src/sidecars/)
+  └─ 显式手工 one-shot 工具（如 cursor-prompt）；不得被 workflows/application/task/worker 依赖
+
+Worker adapter (src/worker/)
+  └─ 产品线 TaskSpec / Task Pool / Observe 本地适配；冻结已发布 loop-agent controller identity，
+     以绝对子进程 launch spec 调用 CLI，不得 in-process import CLI、commands 或 application
+
+Infrastructure / Store (src/infrastructure/，逐步引入)
+  └─ .harness 文件系统副作用、run lifecycle、原子写入规则
+
+Governance (scripts/check-*.sh, src/governance/)
+  └─ 防止 command registry、skill entry、import architecture 漂移
+```
+
+## 各层职责
+
+### Skill layer
+
+- **位置**：`.agents/skills/loop-agent/**` 与 `.agents/skills/agent-worker/**`
+- **职责**：`loop-agent` skill 定义单个 DAG/runtime 工作的入口、硬规则与 reference 路由；`agent-worker` skill 只定义 Feature Packet、TaskSpec、Task Pool、controller pinning、自举 release train 与失败恢复的外层 operator 路由。
+- **路由边界**：DAG leaf node 不得递归启动 `agent-worker`；`agent-worker` 不得加入 `DEFAULT_SKILLS_BY_ROLE`，也不实现 executor、scheduler、prompt 或 write guard。
+- **禁止**：在入口 skill 中重复维护 CLI command 列表或与 `src/cli/catalog.ts` 冲突的事实源。
+
+### CLI layer
+
+- **位置**：`src/cli.ts`、`src/cli/**`
+- **职责**：解析全局 flag（如 `--repo-root`）、解析 top-level / subcommand、调用 command handler、输出 help / JSON / Markdown。
+- **允许依赖**：`src/commands/**`（handler wiring）、`src/adapters/**`、`src/shared/**`、逐步引入的 `src/application/**`。
+- **禁止**：在 router 中维护与 catalog 独立的 command 事实源（Phase 1 整改目标）。
+
+### Init-upgrade command boundary
+
+- **位置**：`src/commands/init-upgrade.ts`，复用 `src/commands/init.ts` 的 ownership scan / safe action 与 `src/commands/client-recovery.ts` 的 generated recovery builders。
+- **职责**：拥有可恢复升级状态机与目标项目 run facts；version gate、identity drift、active runtime/lock、workspace re-scan、single-file merge boundary、home zero-write fingerprint 和 completion invariant 都由 controller 决定。
+- **禁止**：OpenCode/Pi plugin、主会话 skill 或 notifier 拥有升级状态机；命令不得修改业务源码、用户 home 或以宽泛路径授权模型。主会话仅可按 controller 返回的具体 `allowedPaths` 合并 init surface，随后必须 `--continue`。
+
+### Application layer
+
+- **位置**：`src/application/**`（按计划逐步引入）
+- **职责**：封装一次用户意图的 typed result（如 validate DAG、run DAG、report），供 CLI 与 workflow runtime 共用。
+- **允许依赖**：`src/workflows/**`、`src/infrastructure/**`、`src/task/**`、`src/records/**`。
+- **禁止**：直接承担 CLI formatting 或 argv 解析。
+
+### Workflow runtime
+
+- **位置**：`src/workflows/dag/**`、`src/workflows/dynamic/**`、`src/workflows/loop/**`
+- **职责**：DAG spec 校验与执行、dynamic workflow 编译与 expansion、Loop 状态机与 action 编排；新 DAG run 在任何节点执行前创建 run-owned resolved skill profile snapshot，并在普通节点、dynamic child、approve/resume 路径执行 integrity gate。
+- **skill snapshot 契约**：snapshot ref 使用 run-relative `.runtime/skill-snapshot.json` 与原始 bytes SHA-256；ref、artifact、profile 或 binding 不一致时 fail closed，不允许回退 live skill resolution。旧 run 只有在 ref 与 artifact 都不存在时，才可在 resume 前标记为 `legacy-resume-backfill` 并冻结剩余节点。
+- **允许依赖**：`src/executors/**`、`src/task/**`、`src/records/**`、`src/shared/**`、application use-case（目标态）。
+- **禁止**：`import` 来自 `src/commands/**`（见下方过渡例外）。
+
+### Verification planners
+
+- **位置**：`src/verification/**`（当前含 `src/verification/maven/**`）
+- **职责**：在 DAG 生成阶段与 `verify-shell` 执行前，对任务作用域驱动的验证命令做静态规划与冻结计划复核（例如 Maven Workspace Graph、`-f/-pl/-am` 重写、`.harness/cache/` 图缓存、`verification-plan-stale`）。
+- **允许依赖**：`src/adapters/types`（`VerifyCommand`）、Node 标准库；由 `src/workflows/dag/**` 与 `src/executors/shell-executor.ts` 调用。
+- **禁止**：执行 Maven/npm 等外部 goal 做发现；依赖 `src/commands/**` 或 CLI；把独立 POM 拼成伪 reactor；按 first-match/深度/字典序/启动 cwd 选择目标。
+
+### Executors
+
+- **位置**：`src/executors/**`
+- **职责**：封装 Pi SDK、shell 执行、static 输出与 write guard。受治理 Agent runtime 只有 Pi。
+- **允许依赖**：`src/shared/**`、`src/verification/**`（执行前计划复核）、外部 SDK（不含 `@cursor/sdk`）。
+- **禁止**：依赖 `src/commands/**`、CLI 输出格式，或 import `src/sidecars/**` / `@cursor/sdk`。
+
+### Sidecars
+
+- **位置**：`src/sidecars/cursor-prompt/**`
+- **职责**：`cursor-prompt` one-shot 手工干预；仅在显式调用时动态加载 `@cursor/sdk`。
+- **禁止**：被 `src/workflows/**`、`src/application/**`、`src/task/**`、`src/worker/**` 或普通 `src/executors/**` import。
+
+### Worker adapter
+
+- **位置**：`src/worker/**`，独立 `agent-worker` CLI 为 `src/worker/cli.ts`。
+- **职责**：TaskSpec 校验与物化、Task Pool batch/retry/morning report under `.harness/task-pool/`、失败路由，以及只读 Observe 事件/快照/UI；实际 DAG 执行通过 `LoopAgentClient` 启动已发布的 `loop-agent` 子进程。自 0.8.0 起该目录是唯一受支持的 Task Pool runtime root，旧路径不读取、不迁移、不合并、不重映射。
+- **controller identity**：写入型 Feature/batch/Task/final verification 在任何目标仓库或 Task Pool 状态写入前解析并冻结 schemaVersion 1 identity，包括 package name/version、绝对 entry/real entry、直接可执行 launch spec、binary SHA-256 和覆盖 `package.json`、`bin/**`、`dist/**`、`.agents/skills/**` 的 portable fingerprint。expected version/fingerprint 不匹配时 fail-fast；后续 spawn 不重新查询 PATH。
+- **证据传播**：canonical Worker record、Task Pool run、batch/Feature、QA/final evidence 可选携带同一 identity；只有所有相关层都省略 identity 时才按 legacy evidence 接受，部分缺失或锚点不一致会拒绝。
+- **Worker-aware recovery**：`agent-worker task reconcile --action abandon` 由 Worker 持有 Worker run ↔ DAG run association，再调用 DAG-kernel reconcile（`src/workflows/dag/reconcile-run.ts`）并把 Task Pool 投影为 `Failed` + recovery evidence。低层 `loop-agent dag reconcile-run` 只维护 DAG lifecycle，不搜索/修改 Task Pool。应急入口 `pool mark-failed` 同属 Worker，禁止覆盖 `Done`。
+- **允许依赖**：TaskSpec、Task Pool、observability、Node filesystem/path、明确的 shared/task contract，以及只读/共享的 `src/workflows/dag/**` reconcile/lifecycle helpers；它不是第二套 executor 或 DAG kernel。
+- **禁止**：in-process import `src/cli/**`、`src/commands/**` 或 `src/application/**`。
+
+### Infrastructure / Store
+
+- **位置**：`src/infrastructure/harness/**`（按计划逐步引入）；过渡期部分逻辑仍在 `src/workflows/dag/lifecycle.ts`、`src/records/**`。
+- **职责**：`.harness/tasks`、`.harness/dag-runs`、`.harness/runs`、loop state 的集中读写；completed run facts 只读约束。DAG run 自有的 `.runtime/skill-snapshot.json` 随 lifecycle 目录整体迁移，state 只保存相对 ref 和 hash，不保存 active/paused/completed 绝对路径。
+- **DAG recovery mutation**：`dag reconcile-run` 是显式 operator 边界；默认仅检查，只有给出 action + reason 且 runner 已证明停止时才能保存原始快照、写 terminal reconciliation facts 并迁移 lifecycle。Observe、status 和 doctor 始终只读。Task Pool 侧的 abandon/Failed 投影由 `agent-worker task reconcile` 持有，不得让 DAG kernel 反向依赖 Worker。
+- **禁止**：把 raw path mutation 扩散给 runner、loop action 或 command handler。
+
+### Governance
+
+- **位置**：`scripts/check-repo.sh` 及子脚本、`src/governance/**`、相关 Vitest。
+- **职责**：在 CI / in-flight DAG 中检测文档链接、exec plan 状态、架构 import、command registry 漂移、两个公共 skill entry 与 init/package surface 完整性。源码仓库另提供 `scripts/self-host-canary.mjs` 作为 repo-maintainer candidate takeover 证据入口；它不属于发布 package surface。
+
+## 允许的依赖方向
+
+```text
+Skill (docs)          ──advisory──>  CLI catalog / command-reference（人类可读，机器 drift check）
+
+CLI                   ──────────>   Application (目标态)
+CLI                   ──────────>   Commands (handler 薄层)
+Commands              ──────────>   Application / Workflows / Infrastructure
+
+Workflow runtime      ──────────>   Executors / Task / Records / Application (目标态)
+Workflow runtime      ──X──>        Commands  （目标态禁止；见过渡例外）
+
+Executors             ──────────>   Shared / 外部 SDK
+Executors             ──X──>        Commands / CLI
+
+Worker adapter        ──────────>   TaskSpec / Task Pool / observability / 子进程 CLI contract
+Worker adapter        ──X──>        Commands / CLI / Application（in-process）
+
+Application           ──────────>   Workflows / Infrastructure / Task / Records
+Application           ──X──>        CLI formatting
+
+Infrastructure        ──────────>   Shared / node:fs
+Runner / Loop         ──(迁移中)──>  逐步改为仅经 Store / Application
+```
+
+## 版本化自举边界
+
+版本化自举包含两个不同的冻结层，不能用其中一个替代另一个：
+
+| 层 | 冻结对象 | 生命周期 | 权威证据 |
+| --- | --- | --- | --- |
+| Controller identity | 实际发布包、entry/realEntry、launch spec、binary hash、portable package fingerprint | Feature/batch/Task/final verification | Worker、Task Pool、batch/Feature、QA/final evidence 中的 `controllerIdentity` |
+| DAG skill snapshot | 某个 run 实际注入 prompt 的 ordered skill profiles、learned flag、budgets 与 dynamic bindings | 单个 DAG run，包括 pause/resume | `state.skillSnapshotRef` + `<runDir>/.runtime/skill-snapshot.json` |
+
+源码仓库的 deterministic candidate canary 是第三类、只读/确定性接棒证据：候选 tarball 安装到隔离 slot，两个 bin 从包内绝对入口启动，PATH 中放置 controller fallback trap，并只执行 Feature dry-run 与 static/shell DAG。它必须证明 `piExecutorObserved=false`、`modelExecutorObserved=false` 和 `featureExecutedTasks=[]`，因此不能被描述为 live Pi takeover，也不承担 candidate-package Pi skill source resolution 证明；snapshot 定向测试和真实 DAG evidence 单独承担后者。
+
+**规则摘要**
+
+| From | May import | Must not import |
+| ------ | ------------ | ----------------- |
+| `src/commands/**` | application, workflows, infrastructure, task, records, executors, shared | — |
+| `src/workflows/**` | executors, task, records, shared, application（目标） | `src/commands/**` |
+| `src/executors/**` | shared, 外部 SDK | `src/commands/**`, `src/cli/**` |
+| `src/worker/**` | worker-local modules, task contracts, shared, Node APIs | `src/commands/**`, `src/cli/**`, `src/application/**` |
+| `src/cli/**` | commands, adapters, shared, application（目标） | — |
+| `.agents/skills/**` | （Markdown 引用，非 TS import） | 运行时 TS 模块 |
+
+## 已知过渡耦合
+
+当前没有允许的 `src/workflows/**` / `src/executors/**` forbidden import，也没有允许的 `src/worker/**` → `src/{cli,commands,application}/**` TypeScript import。
+
+`scripts/check-architecture-boundaries.sh` 的 transitional allowlist 保持为空。任何新增的 `workflows/executors/worker` forbidden import 必须导致检查 **exit 1**；如果未来确有临时例外，必须先写入 active exec plan，说明移除时间和验证门禁。
+
+## Governance 钩子
+
+以下脚本由 `scripts/check-repo.sh` 调用（Phase 0 起）：
+
+| Script | 检查内容 | 失败条件 |
+| -------- | ---------- | ---------- |
+| `scripts/check-architecture-boundaries.sh` | workflow/executor forbidden import，及 Worker → CLI/commands/application import | 新的未 allowlist violation |
+| `scripts/check-command-registry-drift.sh` | `command-reference.md` 中的 top-level command vs `src/cli/catalog.ts` | 文档引用未注册 command |
+| `scripts/check-exec-plan-index-sync.sh` | `ai_workspace/loop-agent/exec-plans/{active,completed}` 目录文件 vs 对应 `README.md` 索引 | 任一 plan 文件未在索引登记 |
+| `scripts/check-skill-entry.sh` | `loop-agent` / `agent-worker` 的 frontmatter、required references、入口行数与 operator trigger vocabulary | 任一公共 skill 缺失、reference/trigger 漂移或入口超过 hard limit |
+
+版本化自举相关 exec plan：`ai_workspace/loop-agent/exec-plans/active/2026-07-13-versioned-self-hosting-bootstrap.md`。
+
+`src/governance/exec-plans.ts` 是 exec-plan 创建、完成与索引校验的共享 TypeScript 事实源：`plan create`/`plan complete`/`plan check` 与 `dag run-task` 前置校验都调用它。`scripts/check-exec-plan-index-sync.sh` 是独立的 shell 最终防线，与 TypeScript checker 并存；两者均不删除或弱化。
+
+### 验证命令
+
+```bash
+bash scripts/check-repo.sh
+bash scripts/check-architecture-boundaries.sh
+bash scripts/check-command-registry-drift.sh
+bash scripts/check-skill-entry.sh
+```
+
+Runtime 变更另需 `npm run typecheck` 及对应 targeted Vitest（见 exec plan 各 Phase 验证关口）。
+
+## Client session 恢复边界
+
+主会话模型有两类常见缺口：**瞬态 UnknownError**（非标准 502 / `LLMRequestError` / 网络抖动 / 超时经 TypeValidation 落入 UnknownError，内置 APIError 重试不命中）与 **上下文过大**（含内网中文「请求上下文过大」及常见英文 overflow 文案，默认 overflow 识别不全）。loop-agent 通过 **职责分离的项目级产物** 补偿，不修改 OpenCode/Pi 上游，也不引入外部监督器，不改默认模型 `contextWindow`。
+
+| 面 | 路径 / 入口 | 边界 |
+| --- | --- | --- |
+| OpenCode transient-retry | `.opencode/plugins/loop-agent-transient-retry.js`（init surface `generated`） | 仅瞬态 UnknownError resume；busy/retry 门控 + backoff；overflow/401/配额/取消/业务标 permanent（`plugin-ignore-permanent-error`），**不** compact |
+| OpenCode overflow-compact | `.opencode/plugins/loop-agent-context-overflow-compact.js`（init surface `generated`） | 仅 context overflow → `session.compact`（无则 `summarize`）+ 有限 `promptAsync` 续接；`MAX_OVERFLOW_RECOVERIES ≤ 2`；session 锁；非 overflow 不动作 |
+| Pi project extension | `.pi/extensions/loop-agent-context-overflow.js`（init surface `generated`） | `message_end` 上将 overflow `errorMessage` 幂等改写为 `context_length_exceeded:` 前缀，触发 Pi 原生 compact/retry；**不**写 `~/.pi` settings / compaction / 模型窗口 |
+| Pi 用户配置 | `~/.pi/agent/settings.json` | **不**进入项目 `.harness/init-surface.json` hash；仅 `--client-recovery=user` 可字段级补缺并原子写；`auto`/`project`/`off` 与 `check-update` 默认零写 home；读取时只有 `ENOENT` 视为缺文件，其他 I/O 错误 fail closed |
+| CLI mode | `--client-recovery=auto\|project\|user\|off`（默认 `auto`） | `auto`/`project` 安装上述三份项目产物；`user` = 三产物 + 显式 Pi retry 合并；`off` 全跳过 |
+| Ownership | recorded sha256 + apply-safe | 三份 generated 缺失可补、与 recorded hash 一致可升级；用户改过 → model merge / human decision，禁止静默覆盖 |
+
+实现落点：`src/commands/client-recovery.ts`（共享 `isContextOverflow`、生成器与 install）+ `src/commands/init.ts`（surface 编排与 `written` 投影）。
+
+## 演进里程碑
+
+| Phase | 边界变化 |
+| ------- | ---------- |
+| 0（当前） | 文档 + 机器 guard；已知 loop/actions.ts 耦合 advisory |
+| 1 | CLI command definition 单源 |
+| 2 | Skill entry 瘦身 + frontmatter references |
+| 3 | DAG application use-case；Loop 开始脱离 command JSON |
+| 6 | `workflows → commands` import check 已从 advisory 改为 **fail** |
+| 7 | Harness Store / Repository 集中 `.harness` 副作用 |