@tea-agent/loop-agent 0.13.0 → 0.15.0

package/dist/workflows/dag/init-hybrid.js

@@ -555,7 +555,7 @@ export function hasApiDependency(sources) {
  * |---|---|---|---|
  * | 无 | 任意 | auto | not-required |
  * | 有 | present | auto | required |
- * | 有 | present/absent/ambiguous | auto | required (strategy chooses a safe mechanism) |
+ * | 有 | absent/ambiguous | auto | not-required (skip Mock, preserve integration gap) |
  * | 任意 | present | required | required |
  * | 任意 | absent/ambiguous | required | blocked |
  * | 任意 | 任意 | disabled | not-required (if spec allows) else blocked |
@@ -587,12 +587,12 @@ export function resolveFrontendMockMode(capability, taskConfig, hasApiDep) {
     if (!hasApiDep) {
         return "not-required";
     }
-    // In auto mode, capability discovery is evidence for the strategy node, not
-    // a final mechanism decision. Projects without a native Mock service may use
-    // an existing browser interception harness or a reversible request adapter.
-    // The deterministic strategy gate blocks before the writer when none can be
-    // verified by the DAG's frozen static/behavior entrypoints.
-    return "required";
+    // In auto mode, frontend Mock is optional. Only require Mock-backed strategy
+    // assessment when a native project Mock capability is actually present.
+    // Projects without confirmed Mock support continue through the normal
+    // frontend writer and must preserve the real integration gap instead of
+    // inventing a temporary Mock framework or blocking solely for missing Mock.
+    return capability.status === "present" ? "required" : "not-required";
 }
 function mapTaskComplexity(complexity) {
     if (complexity === "small")
@@ -1322,6 +1322,12 @@ export function buildStandardHybridDagFromTask(sources) {
     return spec;
 }
 function buildFrontendMockAssessNode(sources, sourceContext, mockContextBlock, fixedVerificationContext, readOnlyPaths, forbiddenPaths) {
+    const configuredPolicy = sources.taskConfig.frontendMock?.policy ?? "auto";
+    const mockMode = sources.frontendMockMode ?? "not-required";
+    const capabilityStatus = sources.frontendMockCapability?.status;
+    const autoMaySkipMissingMock = configuredPolicy === "auto" &&
+        mockMode === "not-required" &&
+        (capabilityStatus === "absent" || capabilityStatus === "ambiguous");
     return {
         id: "frontend-mock-assess-pi",
         depends_on: ["frontend-contract-pi", "frontend-scout-pi"],
@@ -1337,7 +1343,9 @@ function buildFrontendMockAssessNode(sources, sourceContext, mockContextBlock, f
             "Perform read-only Mock assessment and select one safe frontend data strategy.",
             "The first non-empty line must be exactly one of: MOCK_STRATEGY: native, MOCK_STRATEGY: browser-intercept, MOCK_STRATEGY: request-adapter, MOCK_STRATEGY: not-needed, or MOCK_STRATEGY: blocked.",
             "Prefer an existing native Mock facility. Use browser-intercept only with an existing browser/e2e harness. When no Mock exists but the API layer is writable, use request-adapter by adding a minimal reversible adapter/DI seam within the approved writeSet; the real adapter must remain the production default.",
-            "Select not-needed only with positive evidence that no remote API is involved, a stable real backend will be exercised, or existing fixtures already cover the contract without changes. not-needed still requires the fixed behavior entrypoint to exercise applicable real or no-remote behavior verification. When configured policy is required, not-needed is forbidden.",
+            autoMaySkipMissingMock
+                ? "Auto mode may skip Mock when no project Mock capability is confirmed. Select not-needed with positive evidence from contract/scout that no project Mock capability is confirmed, continue without adding Mock files or dependencies, run the fixed verification entrypoints, and record any unproved real API behavior in Real Integration Gap. Do not block solely because no project Mock capability, browser interception harness, or request adapter exists."
+                : "Select not-needed only with positive evidence that no remote API is involved, a stable real backend will be exercised, or existing fixtures already cover the contract without changes. not-needed still requires the fixed behavior entrypoint to exercise applicable real or no-remote behavior verification. When configured policy is required, not-needed is forbidden.",
             "Configured policy disabled requests no Mock but cannot override project specifications; if an actually-read project rule requires Mock, select blocked.",
             "",
             "## Required Output Sections:",
@@ -1356,6 +1364,9 @@ function buildFrontendMockAssessNode(sources, sourceContext, mockContextBlock, f
             "- Read project Mock/API/schema specifications before making any judgment.",
             "- Do not infer Mock service from lockfile-only or transitive dependency evidence.",
             "- Output MOCK_STRATEGY: blocked if capability evidence conflicts, contract fields are missing/conflicting, paths or dependencies are unauthorized, specs were not actually read, sources conflict, production-default-off cannot be proven, the API layer is not writable for a new adapter, or the frozen entrypoints cannot verify the selected strategy.",
+            ...(autoMaySkipMissingMock
+                ? ["- In auto mode with no confirmed project Mock capability, do not block solely because Mock is unavailable or Mock-specific verification is absent; choose not-needed and make the Real Integration Gap explicit unless project specs require Mock or another safety rule is violated."]
+                : []),
             "- Never comment out or replace the real request with inline data, hard-code Mock enablement, import test mocks from a production entrypoint, invent API fields, or place secrets/real user data in fixtures.",
             "- Mock-backed behavior evidence proves the documented frontend contract only; it never proves real API integration.",
             "",
@@ -1564,7 +1575,11 @@ function resolveFrontendMockContextBlock(sources) {
         parts.push("Mock-backed frontend verification is required. Prefer the detected native service; otherwise the assessment may select an existing browser interception harness or reversible request adapter. Any handler, fixture, adapter, and UI changes stay in the single frontend-implement-pi writeSet.");
     }
     if (mode === "not-required") {
-        parts.push("Generation-time evidence does not require Mock. The assessment must still use contract/scout evidence: select not-needed only positively, or select a safe Mock strategy if an API dependency is confirmed.");
+        parts.push("Generation-time evidence does not require Mock. The assessment must still use contract/scout evidence: select not-needed when Mock is intentionally skipped, or select a safe Mock strategy if project evidence supports one.");
+        if ((sources.taskConfig.frontendMock?.policy ?? "auto") === "auto" &&
+            (capability.status === "absent" || capability.status === "ambiguous")) {
+            parts.push("Auto mode may skip Mock when no project Mock capability is confirmed. Do not block solely for missing Mock; keep the real request path as default and record any unproved backend behavior as Real Integration Gap.");
+        }
     }
     if (mode === "blocked") {
         parts.push("Mock contract is blocked. The DAG must stop before any write node executes.");
@@ -1900,7 +1915,7 @@ function buildFrontendHybridDagFromTask(sources) {
                 subtask_prompt: [
                     "Audit the frontend plan before implementation.",
                     "First non-empty line must be exactly VERDICT: pass or VERDICT: request-revision.",
-                    "Request revision when the Mock strategy is MOCK_STRATEGY: blocked, missing, unsupported by repository evidence, inconsistent with the API contract, outside authorized paths/dependencies, unable to prove production-default-off behavior with the fixed production/default-real-path static check, or missing deterministic behavior verification for the selected strategy. Mock strategies require Mock-backed evidence; not-needed requires applicable real or no-remote behavior evidence.",
+                    "Request revision when the Mock strategy is MOCK_STRATEGY: blocked, missing, unsupported by repository evidence, inconsistent with the API contract, outside authorized paths/dependencies, unable to prove production-default-off behavior with the fixed production/default-real-path static check, or missing deterministic behavior verification for the selected strategy. Mock strategies require Mock-backed evidence. not-needed requires applicable real/no-remote behavior evidence unless auto mode explicitly skipped Mock because no project Mock capability exists; in that case the plan must preserve the real request path and record the Real Integration Gap.",
                     "Also request revision for missing applicable UI states, unsupported dependency additions, design-system drift without reason, weak interaction coverage, broad scope, inline fake data, schema drift, or missing deterministic verification commands.",
                     "Read-only: do not modify repository files.",
                     fixedVerificationContext,
@@ -2330,7 +2345,7 @@ function buildFrontendHybridDagFromTask(sources) {
                     "Read the validated frontend-implementation-contract, frontend-verification-trace evidence, static/behavior shell facts, and actual diff. Trace proves command/file/symbol binding only—not semantic correctness.",
                     "Flag .skip/.only, deleted or weakened tests, unauthorized config changes, Mock-only evidence claimed as real integration, and Browser/visual claims (always not-run in this workflow).",
                     "Use the direct contract, original plan, revision/no-op result, and final design review to reconstruct the approved plan and design verdict; do not infer them from the implementation summary.",
-                    "Treat a commented-out real request, default-enabled Mock, production entrypoint importing test mocks, API/fixture contract drift, unauthorized Mock dependency/path, or missing behavior evidence for the selected strategy as at least Important. Mock strategies require Mock-backed evidence; not-needed requires applicable real or no-remote behavior evidence. Verify that the real request remains the default when Mock activation is absent.",
+                    "Treat a commented-out real request, default-enabled Mock, production entrypoint importing test mocks, API/fixture contract drift, unauthorized Mock dependency/path, or missing behavior evidence for the selected strategy as at least Important. Mock strategies require Mock-backed evidence. not-needed requires applicable real/no-remote behavior evidence unless auto mode explicitly skipped Mock because no project Mock capability exists; in that case verify that the real request remains the default and the Real Integration Gap is preserved.",
                     "Inspect the production/default-real-path static evidence directly and require Mock activation to be off for that check.",
                     "Distinguish Mock-backed evidence from real API integration evidence and preserve the Real Integration Gap when the backend was not exercised.",
                     "Review implementation quality, behavior/state coverage, verification evidence, and maintainability. Read-only: do not modify files.",
@@ -2391,6 +2406,7 @@ function buildFrontendHybridDagFromTask(sources) {
                     "Return a frontend closeout summary covering Mock decision/strategy/files/verification/production boundary, changes, verification evidence, review result, known risks, and follow-up.",
                     "Include a coverage matrix for each requirement id, applicable UI state, and verification target/check with status passed|failed|not-run|blocked|unavailable. Always state Browser accessibility verification: not-run and Visual regression: not-run. Use frontend-verification-trace facts; do not invent Browser evidence from component tests.",
                     `When only Mock-backed evidence passed, state exactly Frontend status: mock-validated and Real integration: pending, summarize the Real Integration Gap, and name ${taskConfig.taskId}-real-api-integration-verify as the explicit follow-up task to create/run after backend readiness. This follow-up is not auto-created or auto-executed. Never describe Mock evidence as real API integration.`,
+                    `When Mock was skipped in auto mode and no real API evidence passed, state exactly Frontend status: locally-validated and Real integration: pending, summarize the Real Integration Gap, and name ${taskConfig.taskId}-real-api-integration-verify as the explicit follow-up task when backend readiness matters.`,
                     "Read-only: do not modify code, docs, artifacts, or .harness/dag-runs/.",
                     sourceContext,
                     mockContextBlock,

package/docs/README.md

@@ -1,107 +1,109 @@
-# 文档索引
-
-`docs/` 是 loop-agent 的治理根目录，包含工作流规则、方法论、验证规则、执行计划、报告、进度日志、决策记录和可复用模板。
-
-顶层 `AGENTS.md` 是操作地图。长期知识应落在此处：决策、契约、计划、验证证据、调试笔记和可复用流程规则应记录在 `docs/` 下，而不是只留在聊天里。
-
-**索引职责**：本文件只索引**核心契约、方法论、产物目录入口与模板**。单篇 progress / report / completed plan 的全量列表分别由对应子目录 `README.md` 维护，避免三处精选榜漂移。
-
-站上用法文档在 `../website/docs/`；双树收敛见 `../skills/loop-agent/references/docs-converge.md`。
-
-## 核心文档
-
-- `design/archive/2026-07-14-loop-agent-self-update-notifier.md` — loop-agent CLI 自更新提醒设计（已实现；历史设计说明）
-- `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 指南
-- `agent-dag-recovery-playbook.md` — DAG 失败分类、recovery action 与 operator 处置手册
-- `design/frontend-mock-data-workflow.md` — 已实现的前端 Mock 数据节点、触发条件、规范证据、验证与失败路由
-- `design/dag-source-binding-and-recovery.md` — 新生成 DAG 的权威任务源绑定、前端需求编号覆盖门禁与中断恢复规则
-- `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 目录和脚本检查为准。
-
-## 方法论
-
-- `harness-methodology-tdd.md` — 行为变更与 bug 修复的 TDD 纪律
-- `harness-methodology-verification.md` — 完成声明前的验证纪律
-- `harness-methodology-debugging.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/current-capability-summary.md`
-- `decisions/README.md` — 架构决策（ADR 0001–0004；0004 = Task Pool feature-scoped identity）
-- `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 目录
-
-## 模板
-
-- `templates/project-start-checklist.md` — 开工前检查清单
-- `templates/feature-spec.md` — 有边界的功能规格
-- `templates/sprint-contract.md` — 实现契约与验收标准
-- `templates/exec-plan.md` — 非平凡工作的执行计划
-- `templates/progress-log.md` — 进度与交接日志
-- `templates/qa-report.md` — 验证与 QA 证据
-- `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
-- `templates/production-readiness-checklist.md` — 低/中风险单仓库 DAG readiness 检查清单
+# 文档索引
+
+`docs/` 是 loop-agent 的治理根目录，包含工作流规则、方法论、验证规则、执行计划、报告、进度日志、决策记录和可复用模板。
+
+顶层 `AGENTS.md` 是操作地图。长期知识应落在此处：决策、契约、计划、验证证据、调试笔记和可复用流程规则应记录在 `docs/` 下，而不是只留在聊天里。
+
+**索引职责**：本文件只索引**核心契约、方法论、产物目录入口与模板**。单篇 progress / report / completed plan 的全量列表分别由对应子目录 `README.md` 维护，避免三处精选榜漂移。
+
+站上用法文档在 `../website/docs/`；双树收敛见 `../skills/loop-agent/references/docs-converge.md`。
+
+## 核心文档
+
+- `design/archive/2026-07-14-loop-agent-self-update-notifier.md` — loop-agent CLI 自更新提醒设计（已实现；历史设计说明）
+- `development-principles.md` — 仓库开发原则
+- `github-collaboration.md` — 内部研发人员的轻量 GitHub 协作指南：短分支、简短 PR、CI 与 Squash Merge
+- `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 指南
+- `agent-dag-recovery-playbook.md` — DAG 失败分类、recovery action 与 operator 处置手册
+- `design/frontend-mock-data-workflow.md` — 已实现的前端 Mock 数据节点、触发条件、规范证据、验证与失败路由
+- `design/dag-source-binding-and-recovery.md` — 新生成 DAG 的权威任务源绑定、前端需求编号覆盖门禁与中断恢复规则
+- `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-18-observe-ops-surface-and-rich-timeline.md` — Observe 运营面/执行面重排、检查器半屏与富执行过程
+- `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 目录和脚本检查为准。
+
+## 方法论
+
+- `harness-methodology-tdd.md` — 行为变更与 bug 修复的 TDD 纪律
+- `harness-methodology-verification.md` — 完成声明前的验证纪律
+- `harness-methodology-debugging.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/current-capability-summary.md`
+- `decisions/README.md` — 架构决策（ADR 0001–0004；0004 = Task Pool feature-scoped identity）
+- `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 目录
+
+## 模板
+
+- `templates/project-start-checklist.md` — 开工前检查清单
+- `templates/feature-spec.md` — 有边界的功能规格
+- `templates/sprint-contract.md` — 实现契约与验收标准
+- `templates/exec-plan.md` — 非平凡工作的执行计划
+- `templates/progress-log.md` — 进度与交接日志
+- `templates/qa-report.md` — 验证与 QA 证据
+- `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
+- `templates/production-readiness-checklist.md` — 低/中风险单仓库 DAG readiness 检查清单
 - `templates/init-evolution-review.md` — 初始化能力演化审查报告模板
 - `templates/branch-merge-report.md` — 跨分支合并的功能保留、冲突解析、init/update 与 package surface 审计模板
 - `templates/adr.md` — 架构决策记录（ADR）
-
-## 维护
-
-文档变更后运行：
-
-```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 约定。
-
-完整本地门禁：
-
-```bash
-bash scripts/ci.sh
-```
+
+## 维护
+
+文档变更后运行：
+
+```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 约定。
+
+完整本地门禁：
+
+```bash
+bash scripts/ci.sh
+```

package/docs/architecture/README.md

@@ -1,26 +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、`ai_workspace/loop-agent/exec-plans/completed/`、`ai_workspace/loop-agent/reports/current-capability-summary.md`、ADR 0001–0003。
-- **规划/设计输入**：`ai_workspace/loop-agent/design/`（含 `dynamic-workflow-dag-engine-roadmap.md`、`六个月规划.md`）。这些文件已带 2026-07-14 校准条；凡未兑现的 phase 段落是设计输入，**不是**已实现证明。
-- 凡本目录文档描述未来能力，一律使用「规划 / 未实现 / 前瞻」标签。
-
-## 与其他文档的分工
-
-- 本目录不复制 `runtime-boundaries.md` 的 import 方向表、governance-hook 表与版本化自举边界表，只交叉引用。
-- 用法与操作说明在 `website/docs/`（使用者双树），不在本目录重复。
-- 本目录文档随发布包发布（npm `files` 显式条目 + `ai_workspace/loop-agent/init-surface.manifest.json` `packageRequired`），但 **不**投影到目标项目 init surface；目标项目 init 仍只投影语言无关的 `runtime-boundaries.md`。
+# 架构文档索引
+
+本目录是 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、`ai_workspace/loop-agent/exec-plans/completed/`、`ai_workspace/loop-agent/reports/current-capability-summary.md`、ADR 0001–0003。
+- **规划/设计输入**：`ai_workspace/loop-agent/design/`（含 `dynamic-workflow-dag-engine-roadmap.md`、`六个月规划.md`）。这些文件已带 2026-07-14 校准条；凡未兑现的 phase 段落是设计输入，**不是**已实现证明。
+- 凡本目录文档描述未来能力，一律使用「规划 / 未实现 / 前瞻」标签。
+
+## 与其他文档的分工
+
+- 本目录不复制 `runtime-boundaries.md` 的 import 方向表、governance-hook 表与版本化自举边界表，只交叉引用。
+- 用法与操作说明在 `website/docs/`（使用者双树），不在本目录重复。
+- 本目录文档随发布包发布（npm `files` 显式条目 + `ai_workspace/loop-agent/init-surface.manifest.json` `packageRequired`），但 **不**投影到目标项目 init surface；目标项目 init 仍只投影语言无关的 `runtime-boundaries.md`。