@tea-agent/loop-agent 0.14.0 → 0.16.0

package/AGENTS.md

@@ -73,7 +73,7 @@
 - `src/`：loop-agent 运行时代码
 - `test/`：Vitest 测试套件
 - `bin/loop-agent.js`：CLI 可执行入口
-- `skills/`：loop-agent 源仓库和 npm 包内置 skill 指令与参考资料；目标项目初始化后只生成 `.agents/skills/`，不再生成根 `skills/`。初始化还会向目标项目 `.gitignore` 合并 loop-agent managed block，忽略 `.harness/tasks/*`、`.harness/dag-runs/*`、`.harness/runs/*`、`.harness/init-surface.json`、`.harness/task-pool/*`、`.task-pool/`、`.worktrees/` 等运行态事实，但保留 `.harness/prompts/` 和目录占位可共享，不会整目录忽略 `.harness/`。
+- `skills/`：loop-agent 源仓库和 npm 包内置 skill 指令与参考资料；目标项目初始化后只生成 `.agents/skills/`，不再生成根 `skills/`。初始化还会向目标项目 `.gitignore` 合并 loop-agent managed block，忽略 `.harness/tasks/*`、`.harness/dag-runs/*`、`.harness/runs/*`、`.harness/evaluation/`、`.harness/init-surface.json`、`.harness/task-pool/*`、`.task-pool/`、`.worktrees/` 等运行态事实，但保留 `.harness/prompts/` 和目录占位可共享，不会整目录忽略 `.harness/`。
 - `.harness/`：任务、DAG、run、cache 和 live state 等运行态目录
 - `docs/`：治理文档、计划、报告和模板
 - `website/`：Docusaurus 用户文档站

package/CHANGELOG.md

@@ -1,5 +1,74 @@
 # 更新日志
 
+## [0.16.0] - 2026-07-19
+
+### 重点更新
+
+- Eval Lab 落地受控评测外环，支持 candidate 矩阵编排、Context Policy A/B dogfood 与 Ignition 研究门禁，全程 autoPromote=false，晋升须人工审核
+- Worker 新增 TaskSpec 显式工作流路由，为四类任务生成带哈希锚定的 Task Outcome，并在晋升前校验 run_record、dag_json 等必需产物
+- 新增 fullstack-v1 Feature Profile，支持确定性结构门禁与 Feature Verification Bundle v1，交付与收尾阶段任一身份漂移或产物篡改均阻断发布
+- Eval Lab 落地固定预算运行时，DagSpec v3 可声明硬预算门禁，超限 fail closed 并输出预算账本，缺失 token 不被当作 0
+
+### 新增
+
+- Eval Lab 新增 Context Policy A/B dogfood 脚本，串联 corpus/candidate/campaign/scorecard 与人工 promote（默认 dry-run），不改 DAG 默认策略
+- Eval Lab 新增 Ignition 研究门禁命令，记录多代 proposer 并给出趋势 verdict，恒为研究用途，不自动晋升
+- Eval Lab 新增 Corpus 契约命令与 dogfood 样板清单（15 个异质任务，public/private/held_out 齐全）
+- Eval Lab 新增 public/private campaign 与 private-verifier，支持多 seed 可重复计划与 candidate 内容泄漏门禁
+- Eval Lab 新增 anti-hack 审计与 Promotion Policy v1，检测验证弱化与可疑 outlier，promote 须通过多项门禁且默认 dry-run
+- Eval Lab 新增固定预算运行时，支持按节点累计资源消耗，硬门禁超限 fail closed 并写出 budget-ledger
+- Eval Lab 新增可切换 Context Policy（baseline-v1 默认与原先一致，role-specialized-v1 按角色调整预算）
+- 新增 fullstack-v1 dogfood Feature F-2026-005，提供零依赖可运行目标仓与双覆盖验收样板
+- 新增 fullstack-v1 Feature Profile，对 packet 执行确定性结构门禁，未声明 profile 的 legacy packet 行为不变
+- AcceptanceSpec verification 新增可选的实现/验证任务引用、required_evidence 与 integration 声明，保留 legacy 字段兼容
+- TaskGraph 节点新增可选 consumes/produces 声明与 Ready Planner artifact gate，上游产物不可验证时下游阻塞
+
+### 改进
+
+- TaskSpec 支持可选 execution.workflow，可确定性物化为任务 DAG 类型并展示在 Worker、Task Pool、晨报与 Observe
+- Ready Planner 明确仅做 envelope 级绑定，不重算产物文件 sha256，文件级 hash 在 Outcome projection 与 Feature Verification Bundle 执行
+- DAG 节点 authoring guidance 明确 Pi 是唯一受治理 writer，cursor-prompt 仅作手工 one-shot sidecar
+- Eval Lab propose 与 experiment 命令支持有界提出 experimenting candidate，accept/reject 须通过 scorecard 门禁，不自动改写已接受 skill
+- 文档基线全面校准至 0.15.0，同步半年规划、仓库分析与路线图，harness Pi MED 路由至 grok-4.5
+- Eval Lab dogfood 脚本改为可安全重复运行，并记录 promote --apply 序列供后续分析
+
+### 修复
+
+- 对齐 Task Outcome 与 Ready Planner 契约：Ready 仅做 envelope 级绑定，Outcome 产物补齐独立 schemaId，失败时写入 outcomeFailure
+- 规范化 shell_verification 为标准 evidence token（兼容旧 shell-verification），未知 outputs.required token 保持兼容不阻塞
+- 清理 0.15.0 版本仍残留在 Unreleased 区块的更新日志条目
+- Eval Lab 运行态（candidate/campaign/scorecard）现被 .gitignore 忽略，旧项目可用 init check-update 刷新 ignore 区块
+
+## [0.15.0] - 2026-07-18
+
+### 重点更新
+
+- 新增 Pull Request 的只读 AI 自动审查，自动检查代码缺陷与测试缺口并更新评论
+- 引入内部测试版本夜间自动发布工作流，主干达标后自动更新版本并发布
+- 收紧 npm 发布包范围，仅保留 init 与 runtime 必需的文档和脚本
+- 修复预发布版本被误发布至 latest 的风险，发布门禁改为按版本号状态严格限制
+
+### 新增
+
+- 新增 Pull Request 的只读 AI 自动审查：在创建、重新打开、转为 ready 或更新提交时检查 bug、测试缺口、runtime boundary 等，并更新单条 PR 评论
+- 新增内部测试版本夜间自动发布：达到提交门槛并通过发布检查后，自动更新版本、生成中文说明并发布 GitHub Release 与 npm
+- 新增面向内部研发人员的轻量 GitHub 协作指南和简短 Pull Request 模板，统一采用短分支与 Squash Merge 的最小协作闭环
+- 新增 `.editorconfig` 与 `.gitattributes`，统一常见文本文件的 UTF-8、LF、缩进和文件末尾换行约定
+
+### 改进
+
+- 收紧 npm 发布包中的 `docs/` 范围：只保留 init/runtime 所需的治理文档、architecture、skills 与 templates
+- 收紧 npm 发布包中的 `scripts/`：只保留知识库实际调用的脚本，不再打包源仓治理检查与 `.sh` 包装
+- 前端实现 DAG 的 `frontendMock.policy=auto` 不再因为目标项目缺少 Mock 能力而阻塞，无确认能力时自动跳过并保留真实请求默认路径
+- 文档基线全面校准至 0.14.0，修复了多处的文档索引遗漏与旧路径引用
+
+### 修复
+
+- 修复私有仓库 AI PR 审查因通过网页 `*.diff` 地址拉取差异导致 404 的问题，改为经 GitHub API 获取 diff
+- 修复预发布版本误发布到 `latest` 的问题：发布门禁改为按版本号的 prerelease 状态限制 dist-tag，beta prerelease 仅允许 `beta` tag
+- 修复网站更新日志（Changelog）的版本插入位置错误：新版本段落不再错误地插入到读者摘要之前，保持页面结构正常
+- 修复网站更新日志中残留的 `[Unreleased]` 块未随版本发布移除的问题
+
 ## [0.14.0] - 2026-07-18
 
 ### 重点更新
@@ -29,8 +98,26 @@
 
 ## [Unreleased]
 
-- 新增内部测试版本夜间自动发布：达到提交门槛并通过发布检查后，自动更新版本、生成中文说明并发布 GitHub Release 与 npm；手动运行默认只做 dry-run。
-- 发布说明支持 OpenAI-compatible 模型，模型不可用时自动使用保守摘要。
+- `.gitignore` 与 `loop-agent init` managed block 现忽略 `.harness/evaluation/`，避免把 Eval Lab 运行态（candidate/campaign/scorecard）误提交；旧目标项目可用 `init check-update` / `update --apply-safe` 刷新 ignore 区块。
+- Eval Lab 增加可复现 Context Policy A/B dogfood：`bash scripts/eval-dogfood-context-policy-ab.sh` 串联 corpus/candidate/campaign/scorecard 与人工 promote（默认 dry-run）；证据见 `docs/reports/2026-07-19-eval-dogfood-context-policy-ab.md`。只演评测协议，不改 DAG 默认 context policy，也不声称自进化成功。
+- Eval Lab 增加 Ignition 研究门禁：`eval ignition record|evaluate|show|list` 记录多代 proposer 并给出趋势 verdict（`insufficient_evidence` / `trend_*` / `inconclusive`）。恒为研究用途：`rsiLevel1ClaimAllowed=false`，从不 auto-promote，也不构成 RSI Level 1 产品承诺。
+- Eval Lab 落地受控外环与 candidate 矩阵：`eval propose from-curate` 有界提出 experimenting candidate；`eval campaign matrix` 支持 dry-run / stub / pi-plan，以及 `--mode pi --dag-template` 的有界 DAG dry-run；`eval outer-loop run` 可串联 propose→campaign→matrix。全程 `autoPromote=false`，晋升仍须人工门禁。
+- Eval Lab 打通 learned guidance 实验路径：`eval experiment from-curate` 将 `knowledge curate` 提案登记为 `experimenting` candidate（写入 `ai_workspace/.../learned-proposal.md`，不改已接受 skill）；`accept` 须 campaign scorecard 的 held-out 不回退与 policy 通过，`reject` 保留 pattern 适用范围证据。仍无 auto-promote。
+- Eval Lab 补齐 anti-hack 与 Promotion Policy v1：`eval campaign scorecard|audit` 检测 verification weakening / command 缩减 / 可疑 outlier（只标记人工复核、不自动剔分）；`eval promote --campaign-id` 须通过 private 改进、held-out 不回退、预算与安全门禁，并仍默认 dry-run / `--apply` + `--reason`。不自动晋升。
+- Eval Lab 新增 public/private campaign：`eval private-verifier *` 与 `eval campaign create|plan|run`；多 seed 计划可重复（`planHash`），private verifier 仅控制器侧可见并对 candidate 内容做泄漏门禁；held_out 仅作 promotion gate 占位。仍不自动晋升，也不自动跑完整 Pi candidate 矩阵。
+- Eval Lab 落地固定预算运行时：DagSpec v3 可声明 `budget`（hard / record-only），runner 按节点累计 calls/wall/passes/tokens/context，硬门禁超限 fail closed 并写出 `budget-ledger.json` 与 budget report；`eval budget show --run-id` 可只读查看。缺失 token 不会被当成 0。
+- DAG 节点 authoring guidance 改为明确 Pi 是唯一受治理 writer，`cursor-prompt` 仅作手工 one-shot sidecar，不再把 Cursor 写成 first-class executor。
+- Eval Lab 抽出可切换的 Context Policy：`baseline-v1`（默认，行为与原先一致）与 `role-specialized-v1`（按角色调整 upstream/skill 预算）；DagSpec 可选 `defaults.contextPolicyId`，`eval context-policy list|show` 可查看策略清单。不含 live campaign 编排。
+- Eval Lab 新增初始 Corpus 契约：`eval corpus register|show|list|validate`，附带可提交样板 `docs/templates/evaluation/corpus-dogfood-v0.manifest.json`（15 个异质任务、public/private/held_out 齐全、每任务 2–3 seed）；只冻结评测样本合同与 `corpusHash`，不跑 live campaign。
+- Eval Lab 补齐 incumbent alias 与人工门禁的 promote/rollback：`eval alias show|list`、`eval promote|rollback`（默认 dry-run，`--apply` 才移动别名）；只改 alias/decision 事实，不改写 candidate bundle 或已完成 DAG facts；仍无 live campaign、硬预算或自动晋升。
+- 对齐 Task Outcome / Ready Planner 契约：Ready 仅做 envelope 级绑定；Outcome 产物补齐独立 `schemaId`；失败 envelope 写入 `outcomeFailure`；`shell_verification` 为规范 evidence token（兼容旧 `shell-verification`）；未知 `outputs.required` token 保持兼容并固化测试。
+- 新增 fullstack-v1 dogfood Feature `F-2026-005`（本地欢迎语端到端样板）：显式 `execution.workflow`、验收双覆盖、TaskGraph `produces`/`consumes` 与 Final Verification 入口；并提供可运行目标仓 `dogfood/fullstack-welcome/`（零依赖 Node HTTP + WelcomeBanner + API/e2e/smoke）。`docs/templates/product-line/` 同步补充 `feature.yaml` 与 workflow/双覆盖指引。`F-2026-001`～`004` 仍作 generic/legacy 对照。
+- `agent-worker feature verify-final` 现可聚合 hash-bound `backend-test` / `frontend-test` Outcome，生成 Feature Verification Bundle v1；Delivery 与 Closeout 会重新验证 bundle、typed outcome、Feature/Task/workflow/controller identity 和 Delivery HEAD，任一漂移或篡改都会阻止交付。既有 `qa-execute` QA aggregate 继续兼容。
+- 新增 `fullstack-v1` Feature Profile：Feature Packet 可选 `feature.yaml` 声明 profile 与 scope，`agent-worker task validate-feature` 对 `fullstack-v1` packet 执行确定性结构门禁（required backend/frontend/backend-test/frontend-test workflow、frontend-test 依赖实现与后端验证、final-verify 覆盖、测试 workflow 不含产品写路径、writer writeSet 重叠须串行）。fullstack profile 必须有 scope；required AC 必须声明实现、验证与 evidence refs，任一门禁失败 fail closed 并输出阶段缺口与修复建议；未声明 profile 的 generic/legacy packet 行为零变化。
+- AcceptanceSpec `verification` 新增全部 optional 的 `implementation_task_refs`、`verification_task_refs`、`required_evidence`、`integration`（`not-applicable`/`mock-allowed`/`real-required`），保留 legacy `expected_task_refs`，schema 仍为 `.strict()`；Feature review 的 coverage 投影在 dual-mode 下复用 Task Outcome envelope 的 `integrationStatus`：实现 Done 但缺验证 evidence、或 `real-required` 仅由 mock/local 满足时，required AC 派生为 `awaiting-verification`（只读派生，非新状态机），Feature 不得被报告为 deliverable。
+- 为 TaskGraph 节点新增可选 `consumes`/`produces` 声明与 Ready Planner artifact gate：上游 Done 但 Outcome envelope 级绑定（Feature/producer/kind/可选 schemaId/source binding）不可验证时，下游以 `required-artifact-missing` 阻塞；Ready Planner 只做 envelope 绑定，不重算产物文件 sha256（文件级 hash 在 Outcome projection 与 Feature Verification Bundle / verify-final / Delivery / Closeout 执行）。artifact 资格是额外门禁，priority 不得越过 gate。gate 原因经 `ReadyExecutionPlan.blocked[*].artifactGate` 投影，供 Feature review、晨报与 Observe 共用。
+- Worker 现为四类 TaskSpec workflow 生成 hash-anchored Task Outcome（含独立 `schemaId` 与失败时的 `outcomeFailure`），并在 promotion 前校验 `run_record`、`dag_json`、`shell_verification` 等已知 required output（未知 legacy token 保持兼容、不阻塞）；Feature review、晨报与 Observe 可引用 outcome 证据，缺失或不一致会以 ContractMismatch/EnvFailure 失败收口。
+- TaskSpec 现支持可选 `execution.workflow`，可确定性物化为任务 DAG 类型并展示在 Worker、Task Pool、晨报与 Observe；旧 QA 任务保持原有执行行为，同时给出需人工选择测试 workflow 的迁移提示。
 
 ## [0.13.0] - 2026-07-18
 
@@ -47,21 +134,21 @@
 
 ## [0.12.0] - 2026-07-16
 
-- **只读 Pi 节点安全重试**：opt-in `retryPolicy`（network / rate-limit / unavailable / timeout）；writer / shell 等声明策略会校验失败。见 [Agent DAG](./guides/agent-dag.md)。
+- **只读 Pi 节点安全重试**：opt-in `retryPolicy`（network / rate-limit / unavailable / timeout）；writer / shell 等声明策略会校验失败。见 [Agent DAG](./website/docs/guides/agent-dag.md)。
 - **`taskKind: backend-test`**：需求分析 → 功能用例 → pytest → 复盘。
 - **知识同步与业务图谱 MVP**：`taskKind: knowledge-sync`（须 `featureId`）/ `knowledge-graph-bootstrap`；`loop-agent knowledge query|graph-init|graph-materialize|graph-promote|graph-incremental-prepare`（`knowledge curate` 仍只负责 repair guidance 提案）。
 - **init surface 全量跟踪**：`check-update` / `update --apply-safe` 覆盖包内全部 `docs/templates/**` 与 `skills/**` 到目标目录的投影。
-- 详见根 `CHANGELOG.md [0.12.0]`；站上 [当前规划](./overview/roadmap.md) 与 [功能导览](./overview/feature-map.md)。
+- 详见根 `CHANGELOG.md [0.12.0]`；站上 [当前规划](./website/docs/overview/roadmap.md) 与 [功能导览](./website/docs/overview/feature-map.md)。
 
 ## [0.11.0] - 2026-07-15
 
-- **Observe 本地运营面 R1–R5**：资源池 / Task 下钻、Batch·Run 三层事实、Feature 决策详情与对象关系条、有界事件历史、ES modules 前端模块化；`observe serve` keep-alive / SSE keepalive，可选非 loopback 绑定（默认仍 `127.0.0.1`）。见 [Observe](./guides/observe-ui.md)。
+- **Observe 本地运营面 R1–R5**：资源池 / Task 下钻、Batch·Run 三层事实、Feature 决策详情与对象关系条、有界事件历史、ES modules 前端模块化；`observe serve` keep-alive / SSE keepalive，可选非 loopback 绑定（默认仍 `127.0.0.1`）。见 [Observe](./website/docs/guides/observe-ui.md)。
 - **版本化自举**：controller identity / package fingerprint / expected gate、run-owned skill snapshot、deterministic `self-host:canary`、`skills/agent-worker` 及目标镜像；dogfood Feature `F-2026-004`。
 - **DagSpec v3 + repair 契约**：新 DAG 携带 `runtimeContract`；supervised `repairNodeId`；run-owned controller identity pin。
-- **`plan create` / `plan complete` / `plan check`**：exec-plan 生命周期与 DAG 前置索引校验。见 [CLI 参考](./reference/cli.md)。
-- **CLI 自更新提醒**：交互式成功命令后检查 npm 新版本；`LOOP_AGENT_DISABLE_UPDATE_CHECK=1` 可关。见 [安装](./quick-start/installation.md)。
+- **`plan create` / `plan complete` / `plan check`**：exec-plan 生命周期与 DAG 前置索引校验。见 [CLI 参考](./website/docs/reference/cli.md)。
+- **CLI 自更新提醒**：交互式成功命令后检查 npm 新版本；`LOOP_AGENT_DISABLE_UPDATE_CHECK=1` 可关。见 [安装](./website/docs/quick-start/installation.md)。
 - **init 布局收敛**：目标项目默认 `ai_workspace/loop-agent/` + `.agents/skills/`；`init update --apply-safe` 可安全迁移旧根 `docs/` / `skills/`。
-- **文档站 IA**：intro 概念地图与 30 分钟路径；[功能导览](./overview/feature-map.md)、[架构导读](./overview/architecture.md)、[当前规划](./overview/roadmap.md)；Markdown 断链构建失败；`skills/loop-agent/references/docs-converge.md` 固化文档收敛检查表。
+- **文档站 IA**：intro 概念地图与 30 分钟路径；[功能导览](./website/docs/overview/feature-map.md)、[架构导读](./website/docs/overview/architecture.md)、[当前规划](./website/docs/overview/roadmap.md)；Markdown 断链构建失败；`skills/loop-agent/references/docs-converge.md` 固化文档收敛检查表。
 - 可选 repo-local SDD skill 嵌入；前端 DAG skill 契约与验证命令安全解析。
 
 ## [0.10.0] - 2026-07-12
@@ -73,17 +160,17 @@
 
 ## [0.9.0] - 2026-07-12
 
-- Observe 看板重设计为暖白运行控制台：统一信息层级、依赖图 + 节点表、右侧节点检查器、安全 Markdown；本机资源 guardrail。见 [Observe](./guides/observe-ui.md)。
+- Observe 看板重设计为暖白运行控制台：统一信息层级、依赖图 + 节点表、右侧节点检查器、安全 Markdown；本机资源 guardrail。见 [Observe](./website/docs/guides/observe-ui.md)。
 
 ## [0.8.0] 及更早
 
-- 0.8.0：[CLI 参考](./reference/cli.md) 补充 `task validate-feature`、`task retry`、`scripts/worker-nightly.sh` + GitHub Actions、`capabilities: [interactive-ui]`，Task Pool 唯一根 `.harness/task-pool/`。
+- 0.8.0：[CLI 参考](./website/docs/reference/cli.md) 补充 `task validate-feature`、`task retry`、`scripts/worker-nightly.sh` + GitHub Actions、`capabilities: [interactive-ui]`，Task Pool 唯一根 `.harness/task-pool/`。
 - 0.7.5：Observe 新增 DAG 依赖图可视化。
 - 0.7.0：interactive-ui writer-only HIGH 路由与 UI 交付契约。
 - 更早条目见根目录 `CHANGELOG.md`。
 
 ## 文档站点同步说明
 
-- 站上 guide / reference 与根 `docs/` 双树边界见 [架构导读 · 双树边界](./overview/architecture.md#双树边界)。
+- 站上 guide / reference 与根 `docs/` 双树边界见 [架构导读 · 双树边界](./website/docs/overview/architecture.md#双树边界)。
 - 活能力短摘要：[`docs/reports/current-capability-summary.md`](https://github.com/tea-agent/loop-agent/blob/main/docs/reports/current-capability-summary.md)。
 - 冻结基线长文：[`docs/reports/2026-07-02-repository-analysis.md`](https://github.com/tea-agent/loop-agent/blob/main/docs/reports/2026-07-02-repository-analysis.md)（2026-07-16 再采样对齐 0.12.0 + 主干 Unreleased；勿当第二 CHANGELOG）。

package/README.md

@@ -45,7 +45,7 @@ loop-agent inspect
 
 ## 自动发布
 
-仓库通过 GitHub Actions 定时检查 `main`，达到提交门槛并通过发布检查后，自动更新版本、生成 Release 说明并发布 GitHub Release 与 npm。手动触发默认只执行 dry-run，不产生远端发布副作用；具体配置、版本规则和恢复步骤见 [`docs/exec-plans/active/2026-07-18-nightly-auto-release.md`](docs/exec-plans/active/2026-07-18-nightly-auto-release.md)。
+仓库通过 GitHub Actions 定时检查 `main`，达到提交门槛并通过发布检查后，自动更新版本、生成 Release 说明并发布 GitHub Release 与 npm。手动触发默认只执行 dry-run，不产生远端发布副作用；具体配置、版本规则和恢复步骤见 [`docs/exec-plans/completed/2026-07-18-nightly-auto-release.md`](docs/exec-plans/completed/2026-07-18-nightly-auto-release.md)。
 
 ## 初始化目标项目
 
@@ -77,7 +77,7 @@ loop-agent init --repo-root <target-repo> --profile full --merge
 loop-agent init doctor --repo-root <target-repo>
 ```
 
-`init instructions` 会输出给模型/Agent 执行完整初始化的指引包，不要求目标项目已有 `harness.json`。默认初始化会 merge 已有 `AGENTS.md`、`harness.json` 和 loop-agent 治理资料，生成语言无关的治理脚本矩阵、中文根 README 入口、`ai_workspace/loop-agent/` 目标项目治理资料、`.agents/skills/` repo-local skills、`harness.json` IDE schema 指引和 `.harness/` 骨架；不会在目标项目根目录生成 `skills/`，也不会把 loop-agent 生成的治理资料写到根 `docs/`。已有 README 会保留用户正文并插入/更新 loop-agent managed block。初始化还会向 `.gitignore` 合并一个 loop-agent managed block（`# LOOP_AGENT_INIT_START/END`），把 `.harness/tasks/*`、`.harness/dag-runs/*`、`.harness/runs/*`、`.harness/live/`、`.harness/cache/`、`.harness/init-surface.json`、`.harness/task-pool/*`、`.task-pool/`、`.agents/skills/*/node_modules/`、`.worktrees/` 等个人/会话运行态事实和 repo-local skill 本地依赖忽略掉，同时保留 `.harness/prompts/` 和目录占位可共享，不会整目录忽略 `.harness/`，也不会覆盖用户已有的 ignore 规则。
+`init instructions` 会输出给模型/Agent 执行完整初始化的指引包，不要求目标项目已有 `harness.json`。默认初始化会 merge 已有 `AGENTS.md`、`harness.json` 和 loop-agent 治理资料，生成语言无关的治理脚本矩阵、中文根 README 入口、`ai_workspace/loop-agent/` 目标项目治理资料、`.agents/skills/` repo-local skills、`harness.json` IDE schema 指引和 `.harness/` 骨架；不会在目标项目根目录生成 `skills/`，也不会把 loop-agent 生成的治理资料写到根 `docs/`。已有 README 会保留用户正文并插入/更新 loop-agent managed block。初始化还会向 `.gitignore` 合并一个 loop-agent managed block（`# LOOP_AGENT_INIT_START/END`），把 `.harness/tasks/*`、`.harness/dag-runs/*`、`.harness/runs/*`、`.harness/evaluation/`、`.harness/live/`、`.harness/cache/`、`.harness/init-surface.json`、`.harness/task-pool/*`、`.task-pool/`、`.agents/skills/*/node_modules/`、`.worktrees/` 等个人/会话运行态事实和 repo-local skill 本地依赖忽略掉，同时保留 `.harness/prompts/` 和目录占位可共享，不会整目录忽略 `.harness/`，也不会覆盖用户已有的 ignore 规则。
 
 新初始化会写入 `.harness/init-surface.json`，记录当前 controller 版本、初始化投影文件 hash 和 manifest hash。已用旧版本初始化的目标项目，可以用下面的维护入口对齐新版本初始化能力：
 
@@ -105,7 +105,7 @@ loop-agent dag validate --dag <temp-dir>/<task-id>-dag.json --strict-models --st
 loop-agent run-dag --dag <temp-dir>/<task-id>-dag.json --cwd .
 ```
 
-`dag run-task` 会先尊重显式声明的专用 `taskKind`。对于默认 `standard` 任务，它会根据任务标题、`source/需求.md` 和结构化 `allowedPaths` 做保守、确定性的需求分类；只有高置信的前端实现需求才会自动进入前端专用节点链。只读 `frontend-mock-assess-pi` 在计划前读取 Mock/API/schema 证据，并通过确定性 contract gate 选择原生 Mock、浏览器拦截、请求适配层、`not-needed` 或明确阻塞；它只能使用 DAG 生成时已固化的验证入口。可选 `task.json.frontendMock` 可设置 `auto|required|disabled`、既有服务目录和专项验证命令；不安全或不完整的显式 required 合同不会生成 writer。真实请求始终是默认路径，唯一写节点仍是 `frontend-implement-pi`。自动分类不会覆盖显式 profile、`workflowPolicy` 或 supervised quality gate。后端、混合或证据不足的需求继续使用通用模板，也不会自动进入 `backend-test`。Mock 验证只证明前端状态与交互；未实际请求后端时，收尾保留 `Frontend status: mock-validated`、`Real integration: pending`，并给出 `<task-id>-real-api-integration-verify`。该复验任务不会自动创建或执行，需要在后端就绪后显式运行。
+`dag run-task` 会先尊重显式声明的专用 `taskKind`。对于默认 `standard` 任务，它会根据任务标题、`source/需求.md` 和结构化 `allowedPaths` 做保守、确定性的需求分类；只有高置信的前端实现需求才会自动进入前端专用节点链。只读 `frontend-mock-assess-pi` 在计划前读取 Mock/API/schema 证据，并通过确定性 contract gate 选择原生 Mock、浏览器拦截、请求适配层、`not-needed` 或明确阻塞；它只能使用 DAG 生成时已固化的验证入口。可选 `task.json.frontendMock` 可设置 `auto|required|disabled`、既有服务目录和专项验证命令；默认 `auto` 下没有已确认 Mock 能力时会跳过 Mock 继续前端实现，并保留真实联调缺口，不会因为缺 Mock 本身阻塞。不安全或不完整的显式 required 合同仍不会生成 writer。真实请求始终是默认路径，唯一写节点仍是 `frontend-implement-pi`。自动分类不会覆盖显式 profile、`workflowPolicy` 或 supervised quality gate。后端、混合或证据不足的需求继续使用通用模板，也不会自动进入 `backend-test`。Mock 验证只证明前端状态与交互；未实际请求后端时，收尾保留 `Real integration: pending`，并给出 `<task-id>-real-api-integration-verify`。该复验任务不会自动创建或执行，需要在后端就绪后显式运行。
 
 测试结论写回与业务知识图谱（结构化 Git，非 RAG）：
 
@@ -281,6 +281,7 @@ npm run self-host:canary -- --deterministic --tarball <candidate.tgz> --output <
 | 路径 | 用途 |
 |---|---|
 | `AGENTS.md` | 本仓库的 agent 开工协议、会话协议和长期工作规则 |
+| `docs/github-collaboration.md` | 内部贡献者的轻量 GitHub 协作指南：短分支、PR、CI 与 Squash Merge |
 | `harness.json` | loop-agent 在本仓库的模型、executor、治理根目录和脚本配置 |
 | `docs/README.md` | 治理文档索引 |
 | `docs/verification-matrix.md` | 不同变更类型对应的验证命令 |
@@ -293,6 +294,8 @@ npm run self-host:canary -- --deterministic --tarball <candidate.tgz> --output <
 
 ## 本仓库开发
 
+内部贡献代码时，先阅读 [`docs/github-collaboration.md`](docs/github-collaboration.md)。当前采用轻量协作方式：一个小工作块使用一个短分支，通过简短 Pull Request、CI 和同事确认后，默认 Squash Merge 到 `main`。
+
 本地源码开发：
 
 ```bash
@@ -318,9 +321,9 @@ Windows 上运行 `scripts/*.sh` 时使用 Git Bash 或已配置的兼容 Bash
 
 ## 发布包内容
 
-发布包包含静态运行和指导资料：`bin/`、`dist/`、`skills/`（包括 `loop-agent` 与可选的 `agent-worker` operator skill）、`docs/*.md`、`docs/architecture/runtime-boundaries.md`、`docs/skills/`、`docs/templates/`、`docs/init-surface.manifest.json`、`examples/`、`harness.json`、`AGENTS.md`、`README.md` 和 `CHANGELOG.md`。
+发布包包含静态运行和指导资料：`bin/`、`dist/`、`skills/`（包括 `loop-agent` 与可选的 `agent-worker` operator skill）、必要的治理文档（`docs/README.md`、三份 methodology、显式列出的 `docs/architecture/*.md`）、`docs/skills/`、`docs/templates/`、`docs/init-surface.manifest.json`、知识库运行脚本（`scripts/kb-*.mjs` 与 `kb-bootstrap-init-skeleton.sh`）、`examples/`、`harness.json`、`AGENTS.md`、`README.md` 和 `CHANGELOG.md`。
 
-`docs/progress/`、`docs/reports/`、`docs/exec-plans/`、`docs/decisions/` 等目录下的任务正文是目标仓库实时生成或历史事实；npm 包只携带这些目录的 README，不携带本仓库已有历史记录。
+`docs/progress/`、`docs/reports/`、`docs/exec-plans/`、`docs/decisions/`、`docs/design/` 的任务正文与目录 README 不随包发布；`loop-agent init` 会在目标项目生成空目录契约，具体 plan/progress/report/decision 由后续真实任务写入。源仓库专属说明（如 agent-dag playbook、sidecar 说明）也不再打进 npm 包。
 
 DAG skill 指令优先从用户配置目录和目标项目 `.agents/skills/` 解析；目标项目未提供本地 skill 时，CLI 会回退到 npm 包内置的 `skills/`。因此普通项目不需要复制 loop-agent 仓库历史文档或根 `skills/` 目录才可获得默认 DAG 能力。
 
@@ -336,4 +339,20 @@ node bin/loop-agent.js --help
 npm pack --dry-run
 ```
 
+`npm publish` 时会通过 `prepublishOnly` 依次执行：
+
+1. `node scripts/check-npm-publish-policy.mjs` — 发布策略门禁
+2. `npm run typecheck`
+3. `npm test`
+4. `npm run build`
+
+### frontend 分支发布限制
+
+在 `frontend` 分支执行 `npm publish` 时，必须同时满足：
+
+- `package.json` 版本为合法的 SemVer **beta** 预发布版本（例如 `0.13.0-beta.1`）
+- 必须显式指定 `--tag beta`（即 `npm publish --tag beta`）
+
+任一条件不满足时，`prepublishOnly` 会在上传 npm registry 前失败并给出中文错误提示。其他分支不受此限制。
+
 发布入口 `bin/loop-agent.js` 只加载 `dist/cli.js`；`npm run dev -- <args>` 只用于源码开发和定位问题。

package/dist/application/evaluation/alias.js

@@ -0,0 +1,184 @@
+import { readFile } from "node:fs/promises";
+import { aliasHistoryPath, commitAliasMove, listAliasNames, listIncumbentCandidateIds, makeDecisionId, readIncumbentAlias, readPromotionDecision, } from "../../infrastructure/evaluation/alias-store.js";
+import { readCandidateRecord } from "../../infrastructure/evaluation/candidate-store.js";
+async function requireAcceptedCandidate(input) {
+    const record = await readCandidateRecord(input.repoRoot, input.candidateId);
+    if (record.status !== "accepted") {
+        throw new Error(`alias move requires candidate lifecycle accepted; ${input.candidateId} is ${record.status}`);
+    }
+    return {
+        candidateId: record.manifest.candidateId,
+        bundleHash: record.manifest.bundleHash,
+    };
+}
+function buildDecision(input) {
+    const decisionId = makeDecisionId({
+        alias: input.alias,
+        action: input.action,
+        toCandidateId: input.toCandidateId,
+        createdAt: input.createdAt,
+    });
+    return {
+        schemaVersion: 1,
+        decisionId,
+        alias: input.alias,
+        action: input.action,
+        fromCandidateId: input.fromCandidateId,
+        toCandidateId: input.toCandidateId,
+        toBundleHash: input.toBundleHash,
+        reason: input.reason,
+        actor: "human",
+        humanRequired: true,
+        applied: input.applied,
+        createdAt: input.createdAt,
+        campaignId: input.campaignId ?? null,
+    };
+}
+async function planAliasMove(input) {
+    const reason = input.reason.trim();
+    if (!reason) {
+        throw new Error("alias move requires non-empty --reason");
+    }
+    const createdAt = input.now ?? new Date().toISOString();
+    const previous = await readIncumbentAlias(input.repoRoot, input.alias);
+    if (input.action === "rollback" && !previous) {
+        throw new Error(`cannot rollback alias ${input.alias}: alias does not exist yet`);
+    }
+    const target = await requireAcceptedCandidate({
+        repoRoot: input.repoRoot,
+        candidateId: input.toCandidateId,
+    });
+    if (previous && previous.candidateId === target.candidateId) {
+        throw new Error(`alias ${input.alias} already points at candidate ${target.candidateId}`);
+    }
+    const decision = buildDecision({
+        alias: input.alias,
+        action: input.action,
+        fromCandidateId: previous?.candidateId ?? null,
+        toCandidateId: target.candidateId,
+        toBundleHash: target.bundleHash,
+        reason,
+        applied: !input.dryRun,
+        createdAt,
+        campaignId: input.campaignId,
+    });
+    const nextAlias = {
+        schemaVersion: 1,
+        alias: input.alias,
+        candidateId: target.candidateId,
+        bundleHash: target.bundleHash,
+        updatedAt: createdAt,
+        updatedByDecisionId: decision.decisionId,
+        previousCandidateId: previous?.candidateId ?? null,
+    };
+    if (input.dryRun) {
+        return {
+            dryRun: true,
+            decision: { ...decision, applied: false },
+            alias: nextAlias,
+            previous,
+        };
+    }
+    const historySeq = previous ? await nextHistorySeq(input.repoRoot, input.alias) : 1;
+    const historyEvent = {
+        schemaVersion: 1,
+        seq: historySeq,
+        decisionId: decision.decisionId,
+        action: input.action,
+        fromCandidateId: previous?.candidateId ?? null,
+        toCandidateId: target.candidateId,
+        toBundleHash: target.bundleHash,
+        at: createdAt,
+    };
+    await commitAliasMove({
+        repoRoot: input.repoRoot,
+        decision,
+        nextAlias,
+        historyEvent,
+    });
+    // W2.4 does not auto-retire the previous incumbent: lifecycle `accepted` ≠
+    // alias pointer, and rollback drills must be able to point back without
+    // inventing a new candidate id. Operators may `eval candidate transition
+    // --to retired` separately.
+    return {
+        dryRun: false,
+        decision,
+        alias: (await readIncumbentAlias(input.repoRoot, input.alias)),
+        previous,
+    };
+}
+async function nextHistorySeq(repoRoot, alias) {
+    const text = await readFile(aliasHistoryPath(repoRoot, alias), "utf-8").catch(() => "");
+    const lines = text
+        .split("\n")
+        .map((line) => line.trim())
+        .filter(Boolean);
+    return lines.length + 1;
+}
+export async function promoteAlias(input) {
+    return planAliasMove({
+        ...input,
+        action: "promote",
+        dryRun: input.dryRun !== false,
+    });
+}
+export async function rollbackAlias(input) {
+    return planAliasMove({
+        ...input,
+        action: "rollback",
+        dryRun: input.dryRun !== false,
+    });
+}
+export async function showAlias(input) {
+    const current = await readIncumbentAlias(input.repoRoot, input.alias);
+    if (!current) {
+        throw new Error(`alias not found: ${input.alias}`);
+    }
+    return current;
+}
+export async function listAliases(input) {
+    const names = await listAliasNames(input.repoRoot);
+    const rows = [];
+    for (const name of names) {
+        const current = await readIncumbentAlias(input.repoRoot, name);
+        if (current)
+            rows.push(current);
+    }
+    return rows;
+}
+export async function isCandidatePromotionApplied(input) {
+    const incumbents = await listIncumbentCandidateIds(input.repoRoot);
+    return incumbents.has(input.candidateId);
+}
+export function formatAliasMarkdown(alias) {
+    return [
+        `# Alias: ${alias.alias}`,
+        "",
+        `- candidateId: \`${alias.candidateId}\``,
+        `- bundleHash: \`${alias.bundleHash}\``,
+        `- previousCandidateId: \`${alias.previousCandidateId ?? "null"}\``,
+        `- updatedByDecisionId: \`${alias.updatedByDecisionId}\``,
+        `- updatedAt: \`${alias.updatedAt}\``,
+        "",
+    ].join("\n");
+}
+export function formatAliasMoveMarkdown(result) {
+    const mode = result.dryRun ? "dry-run" : "applied";
+    return [
+        `# Alias ${result.decision.action} (${mode})`,
+        "",
+        `- alias: \`${result.decision.alias}\``,
+        `- from: \`${result.decision.fromCandidateId ?? "null"}\``,
+        `- to: \`${result.decision.toCandidateId}\``,
+        `- bundleHash: \`${result.decision.toBundleHash}\``,
+        `- decisionId: \`${result.decision.decisionId}\``,
+        `- applied: \`${result.decision.applied}\``,
+        `- reason: ${result.decision.reason}`,
+        "",
+        result.dryRun
+            ? "_No alias files were written (dry-run). Pass `--apply` to commit._"
+            : "_Alias pointer updated; candidate bundles and completed DAG facts were not rewritten._",
+        "",
+    ].join("\n");
+}
+export { readPromotionDecision };

package/dist/application/evaluation/budget.js

@@ -0,0 +1,192 @@
+import { z } from "zod";
+/**
+ * Campaign / DAG hard-budget contract (Eval Lab W3.4–W3.5 / M3).
+ *
+ * Token incompleteness: missing `tokensUsed` must never be treated as 0.
+ * When `maxTokens` is set, only known token samples accumulate; breach fires
+ * only when the known sum exceeds the limit. Calls + wall time + repair passes
+ * are the primary hard dimensions for v1.
+ */
+export const campaignBudgetModeSchema = z.enum(["hard", "record-only"]);
+export const campaignBudgetLimitsSchema = z
+    .object({
+    maxTokens: z.number().int().positive().optional(),
+    maxWallTimeMs: z.number().int().positive().optional(),
+    maxExecutorCalls: z.number().int().positive().optional(),
+    maxRepairPasses: z.number().int().nonnegative().optional(),
+    maxConcurrency: z.number().int().positive().optional(),
+    maxContextChars: z.number().int().positive().optional(),
+})
+    .strict()
+    .superRefine((limits, ctx) => {
+    const hasHardDim = limits.maxTokens !== undefined ||
+        limits.maxWallTimeMs !== undefined ||
+        limits.maxExecutorCalls !== undefined ||
+        limits.maxRepairPasses !== undefined ||
+        limits.maxContextChars !== undefined;
+    if (!hasHardDim) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "budget.limits requires at least one of maxTokens, maxWallTimeMs, maxExecutorCalls, maxRepairPasses, maxContextChars",
+        });
+    }
+});
+export const campaignBudgetSchema = z
+    .object({
+    schemaVersion: z.literal(1),
+    mode: campaignBudgetModeSchema.default("hard"),
+    limits: campaignBudgetLimitsSchema,
+})
+    .strict();
+export function createBudgetLedger(budget) {
+    return {
+        schemaVersion: 1,
+        mode: budget.mode,
+        limits: { ...budget.limits },
+        consumed: {
+            tokens: null,
+            wallTimeMs: 0,
+            executorCalls: 0,
+            repairPasses: 0,
+            peakContextChars: 0,
+            missingTokenNodeIds: [],
+        },
+        breaches: [],
+        status: budget.mode === "record-only" ? "record-only" : "ok",
+    };
+}
+export function resolveEffectiveMaxConcurrent(requested, budget) {
+    const limit = budget?.limits.maxConcurrency;
+    if (limit === undefined) {
+        return { maxConcurrent: Math.max(1, requested), clamped: false };
+    }
+    const maxConcurrent = Math.max(1, Math.min(requested, limit));
+    return { maxConcurrent, clamped: maxConcurrent < requested };
+}
+function pushBreach(ledger, breach) {
+    const full = {
+        ...breach,
+        at: breach.at ?? new Date().toISOString(),
+    };
+    const duplicate = ledger.breaches.some((existing) => existing.dimension === full.dimension &&
+        existing.nodeId === full.nodeId &&
+        existing.limit === full.limit);
+    if (!duplicate) {
+        ledger.breaches.push(full);
+    }
+    if (ledger.mode === "hard") {
+        ledger.status = "breached";
+    }
+}
+function checkLimit(ledger, dimension, consumed, limit, opts) {
+    if (limit === undefined)
+        return undefined;
+    const exceeded = opts?.inclusive ? consumed >= limit : consumed > limit;
+    if (!exceeded)
+        return undefined;
+    const breach = {
+        dimension,
+        limit,
+        consumed,
+        at: new Date().toISOString(),
+        ...(opts?.nodeId ? { nodeId: opts.nodeId } : {}),
+    };
+    pushBreach(ledger, breach);
+    return breach;
+}
+/**
+ * Pre-node check (no call increment yet).
+ * Discrete call budget uses inclusive compare so maxExecutorCalls=1 allows the
+ * first node then blocks starting a second.
+ */
+export function checkBudgetPreNode(ledger, sample) {
+    ledger.consumed.wallTimeMs = sample.wallTimeMs;
+    ledger.consumed.repairPasses = sample.repairPasses;
+    return (checkLimit(ledger, "executorCalls", ledger.consumed.executorCalls, ledger.limits.maxExecutorCalls, { inclusive: true }) ??
+        checkLimit(ledger, "wallTimeMs", sample.wallTimeMs, ledger.limits.maxWallTimeMs) ??
+        checkLimit(ledger, "repairPasses", sample.repairPasses, ledger.limits.maxRepairPasses));
+}
+/**
+ * Record one finished node execution attempt and evaluate hard limits.
+ * Increments executorCalls by 1. Does not invent tokens when missing.
+ */
+export function recordNodeBudgetSample(ledger, sample) {
+    ledger.consumed.executorCalls += 1;
+    ledger.consumed.wallTimeMs = sample.wallTimeMs;
+    ledger.consumed.repairPasses = sample.repairPasses;
+    if (sample.tokensUsed === undefined) {
+        if (!ledger.consumed.missingTokenNodeIds.includes(sample.nodeId)) {
+            ledger.consumed.missingTokenNodeIds.push(sample.nodeId);
+        }
+    }
+    else {
+        ledger.consumed.tokens = (ledger.consumed.tokens ?? 0) + sample.tokensUsed;
+    }
+    if (sample.contextChars !== undefined) {
+        ledger.consumed.peakContextChars = Math.max(ledger.consumed.peakContextChars, sample.contextChars);
+    }
+    return (checkLimit(ledger, "executorCalls", ledger.consumed.executorCalls, ledger.limits.maxExecutorCalls, { nodeId: sample.nodeId, inclusive: true }) ??
+        checkLimit(ledger, "wallTimeMs", ledger.consumed.wallTimeMs, ledger.limits.maxWallTimeMs, { nodeId: sample.nodeId }) ??
+        checkLimit(ledger, "repairPasses", ledger.consumed.repairPasses, ledger.limits.maxRepairPasses, { nodeId: sample.nodeId }) ??
+        (ledger.consumed.tokens !== null
+            ? checkLimit(ledger, "tokens", ledger.consumed.tokens, ledger.limits.maxTokens, { nodeId: sample.nodeId })
+            : undefined) ??
+        checkLimit(ledger, "contextChars", ledger.consumed.peakContextChars, ledger.limits.maxContextChars, { nodeId: sample.nodeId }));
+}
+export function isHardBudgetBreached(ledger) {
+    return Boolean(ledger && ledger.mode === "hard" && ledger.status === "breached");
+}
+/** Mark all PENDING nodes as SKIPPED due to budget breach (fail closed). */
+export function skipPendingNodesForBudgetBreach(nodes, breach) {
+    const skipped = [];
+    const reason = `budget_breach:${breach.dimension}`;
+    for (const [id, node] of Object.entries(nodes)) {
+        if (node.status !== "PENDING")
+            continue;
+        node.status = "SKIPPED";
+        node.skippedReason = reason;
+        skipped.push(id);
+    }
+    return skipped;
+}
+export function formatBudgetReportMarkdown(ledger) {
+    const limits = ledger.limits;
+    const c = ledger.consumed;
+    const lines = [
+        `# Budget Ledger`,
+        ``,
+        `- **mode**: ${ledger.mode}`,
+        `- **status**: ${ledger.status}`,
+        ``,
+        `## Limits`,
+        ``,
+        `| dimension | limit |`,
+        `|---|---|`,
+        `| maxTokens | ${limits.maxTokens ?? "n/a"} |`,
+        `| maxWallTimeMs | ${limits.maxWallTimeMs ?? "n/a"} |`,
+        `| maxExecutorCalls | ${limits.maxExecutorCalls ?? "n/a"} |`,
+        `| maxRepairPasses | ${limits.maxRepairPasses ?? "n/a"} |`,
+        `| maxConcurrency | ${limits.maxConcurrency ?? "n/a"} |`,
+        `| maxContextChars | ${limits.maxContextChars ?? "n/a"} |`,
+        ``,
+        `## Consumed`,
+        ``,
+        `| dimension | value |`,
+        `|---|---|`,
+        `| tokens | ${c.tokens ?? "n/a (missing)"} |`,
+        `| wallTimeMs | ${c.wallTimeMs} |`,
+        `| executorCalls | ${c.executorCalls} |`,
+        `| repairPasses | ${c.repairPasses} |`,
+        `| peakContextChars | ${c.peakContextChars} |`,
+        `| missingTokenNodes | ${c.missingTokenNodeIds.join(", ") || "none"} |`,
+    ];
+    if (ledger.breaches.length > 0) {
+        lines.push(``, `## Breaches`, ``);
+        for (const breach of ledger.breaches) {
+            lines.push(`- **${breach.dimension}**: consumed ${breach.consumed} > limit ${breach.limit}` +
+                (breach.nodeId ? ` (node ${breach.nodeId})` : "") +
+                ` at ${breach.at}`);
+        }
+    }
+    return `${lines.join("\n")}\n`;
+}