@haiyangbg/buildbeat 3.0.0 → 3.1.0

package/example/delivery/envelope/worker.sh

@@ -0,0 +1,70 @@
+#!/usr/bin/env bash
+# BuildBeat v2 worker 包装：把任意 CLI Agent 接进 Runner 的信封合同。
+#
+#   bash delivery/envelope/worker.sh <role> -- <tool command...>
+#   role: builder | fixer | planner（写入步）  reviewer（只读步）
+#
+# 做的事（每一条都对应 docs/v2/guide/05-worker-contract.md 的一条合同）：
+#   1. 工具不在 PATH → exit 75（EX_TEMPFAIL）：内核判基础设施故障停人，不派 fixer、不扣预算；
+#   2. 有 $BUILDBEAT_PROMPT 就把 prompt 文本作为最后一个参数追加给工具（codex exec / claude -p 都吃位置参数）；
+#   3. 写入步：工具返回后若工作树有改动，机械地 git add -A && git commit（提交动作不交给模型）；
+#   4. 只读步：工具的 stdout 落到 $BUILDBEAT_OUTPUT（工具自己写了该文件则不覆盖）；不 commit；
+#   5. 工具退出码原样透传；本脚本自己不判断候选好坏——那是 verify 与 review 的事。
+# cwd 已由内核设为该步的隔离 worktree；不要 cd。
+set -uo pipefail
+
+role="${1:-}"
+shift || true
+if [ "${1:-}" = "--" ]; then
+  shift
+fi
+if [ -z "$role" ] || [ "$#" -eq 0 ]; then
+  echo "usage: worker.sh <builder|fixer|planner|reviewer> -- <tool command...>" >&2
+  exit 64
+fi
+
+tool="$1"
+if ! command -v "$tool" >/dev/null 2>&1; then
+  echo "worker.sh: tool not found in PATH: $tool (exit 75 = infrastructure, not a candidate defect)" >&2
+  exit 75
+fi
+
+input="${BUILDBEAT_INPUT:-{}}"
+run_id="$(printf '%s' "$input" | sed -n 's/.*"runId":"\([^"]*\)".*/\1/p')"
+attempt="$(printf '%s' "$input" | sed -n 's/.*"attempt":\([0-9]*\).*/\1/p')"
+
+args=("$@")
+if [ -n "${BUILDBEAT_PROMPT:-}" ] && [ -f "$BUILDBEAT_PROMPT" ]; then
+  args+=("$(cat "$BUILDBEAT_PROMPT")")
+fi
+
+case "$role" in
+  builder|fixer|planner)
+    "${args[@]}"
+    status=$?
+    if [ -n "$(git status --porcelain 2>/dev/null)" ]; then
+      git add -A
+      git -c user.name="${GIT_AUTHOR_NAME:-buildbeat-worker}" -c user.email="${GIT_AUTHOR_EMAIL:-worker@buildbeat.local}" \
+        commit -q -m "${role}: ${run_id:-run} attempt ${attempt:-?}" || status=$?
+    fi
+    exit "$status"
+    ;;
+  reviewer)
+    if [ -n "${BUILDBEAT_OUTPUT:-}" ]; then
+      captured="$(mktemp "${TMPDIR:-/tmp}/bb-review.XXXXXX")"
+      "${args[@]}" | tee "$captured"
+      status=${PIPESTATUS[0]}
+      if [ ! -s "$BUILDBEAT_OUTPUT" ]; then
+        cp "$captured" "$BUILDBEAT_OUTPUT"
+      fi
+      rm -f "$captured"
+      exit "$status"
+    fi
+    "${args[@]}"
+    exit $?
+    ;;
+  *)
+    echo "worker.sh: unknown role: $role" >&2
+    exit 64
+    ;;
+esac

package/example/delivery/work/WORK-EXPORT-DATE-FILTER/decisions.jsonl

@@ -0,0 +1,3 @@
+{"ts":"2026-09-09T15:09:50.301Z","decisionRef":"A-WORK-EXPORT-DATE-FILTER-1","decision":"approved","transition":"accept-intent","subject":{"artifact":"intent","digest":"sha256:4e0d96de3ff7c5a1fffc8af268ce91784a515ebcc92e6d5ea035d67ef118da92"},"by":"小周"}
+{"ts":"2026-09-09T15:09:50.350Z","decisionRef":"A-WORK-EXPORT-DATE-FILTER-2","decision":"approved","transition":"accept-plan","subject":{"artifact":"plan","digest":"sha256:4f770dd7b20f14c3e64371ec475ea18f0b82e052fba1f3b8649b04d3ac7ec07a"},"by":"小周"}
+{"ts":"2026-09-09T15:09:51.628Z","run":"RUN-EXPORT-01","decisionRef":"D-RUN-EXPORT-01-1","decision":"approved","transition":"enter-wait-merge","subject":{"candidate":"be7e4f9c4d3d5dcd26132f98f660f9e217c47a97","planDigest":"sha256:4f770dd7b20f14c3e64371ec475ea18f0b82e052fba1f3b8649b04d3ac7ec07a","evidenceDigest":"sha256:7c00d8d23d7d1b3f56006f4686a99bd8b3cc0839f105b524cabadd50dfa04f67"},"by":"小周"}

package/example/delivery/work/WORK-EXPORT-DATE-FILTER/intent.md

@@ -0,0 +1,24 @@
+# Intent：导出加日期筛选（WORK-EXPORT-DATE-FILTER）
+
+## 为什么做
+
+月底对账只想看当月流水，现在的 CSV 导出是全量的，用户得在表格里再筛一遍。
+
+## 目标
+
+`exportCsv(ledger, { from, to })` 支持含端点的日期区间，两端都可以省略；导出格式（列序、金额两位小数）不变。
+
+## 非目标
+
+- 不动 `src/ledger.js`（老地盘）；
+- 不做界面，没有 UI 交付；
+- 不改 CSV 的列和编码。
+
+## 止损线
+
+最多 2 个 Run、3 轮 review、总计 1 小时 worker 时间；越线先问所有者"继续还是砍"。
+
+## 验收条件
+
+- `npm test` 全绿，且新增用例覆盖：无边界、单边界、双边界、区间外为空、坏格式、from>to；
+- review 无 P0/P1。

package/example/delivery/work/WORK-EXPORT-DATE-FILTER/plan.md

@@ -0,0 +1,20 @@
+# Plan：导出加日期筛选（WORK-EXPORT-DATE-FILTER）
+
+## 修改范围
+
+`src/export.js`、`tests/export.test.js`（allowedPaths：`src`、`tests`）。
+
+## 实现顺序
+
+1. `exportCsv` 增加第二个参数 `options = {}`，读 `from` / `to`；
+2. 两个边界都按 `YYYY-MM-DD` 校验，坏格式抛 `bad date bound`，`from > to` 抛 `is after`（【EXPORT-1】拍板：不静默）；
+3. 用字符串比较做含端点筛选（ISO 日期字符串可直接比大小）；
+4. `tests/export.test.js` 补：无边界、单边界、双边界、区间外为空、坏格式、from>to。
+
+## 测试方法
+
+verify 步跑 `npm test`（`node --test tests/*.test.js`），退出码回读为证据。
+
+## 风险与回滚
+
+只加参数、默认行为不变，老调用方不受影响；候选不合并即无影响，Run 的工作树可整体 `gc`。

package/example/delivery/work/WORK-EXPORT-DATE-FILTER/run-config.yaml

@@ -0,0 +1,66 @@
+# 简账 · WORK-EXPORT-DATE-FILTER 的 run 配置。路径相对本文件解析。
+# 起跑前：buildbeat doctor --config <本文件>；起跑：buildbeat start --config <本文件> --attempt new
+repo: ../../..
+work: WORK-EXPORT-DATE-FILTER
+run: RUN-EXPORT
+# 从 $(npm root -g)/@haiyangbg/buildbeat/src/v2/presets/software-delivery.yaml 复制到本目录
+workflow: workflow.yaml
+riskPreset: standard
+entry: build
+allowedPaths:
+  - src
+  - tests
+reviewTriage: required
+# 对应 intent 的止损线：3 轮 review
+budgets:
+  maxAttempts:
+    review: 2
+  reviewRoundsPerWork: 3
+cache:
+  verify: tree
+envelope:
+  prompts: ../../envelope/prompts
+  vars:
+    component: export
+redact:
+  - "(token|secret|password|TOKEN|SECRET|PASSWORD)=\\S+"
+requires:
+  - command: node
+    min: "20"
+# 换工具只改 -- 后面的命令
+workers:
+  builder:
+    command: bash
+    args:
+      - delivery/envelope/worker.sh
+      - builder
+      - --
+      - codex
+      - exec
+      - -s
+      - workspace-write
+  verifier:
+    command: bash
+    args:
+      - -lc
+      - npm test
+  reviewer:
+    command: bash
+    args:
+      - delivery/envelope/worker.sh
+      - reviewer
+      - --
+      - codex
+      - exec
+      - -s
+      - read-only
+  fixer:
+    command: bash
+    args:
+      - delivery/envelope/worker.sh
+      - fixer
+      - --
+      - codex
+      - exec
+      - -s
+      - workspace-write

package/example/delivery/work/WORK-EXPORT-DATE-FILTER/runs/RUN-EXPORT-01/run-record.json

@@ -0,0 +1,108 @@
+{
+  "run": "RUN-EXPORT-01",
+  "work": "WORK-EXPORT-DATE-FILTER",
+  "workflow": "software-delivery",
+  "terminal": {
+    "status": "SUCCEEDED",
+    "reason": "final decision approved; the external action (merge) stays manual"
+  },
+  "events": {
+    "from": 1,
+    "to": 31,
+    "lastDigest": "sha256:fb0aad2e3f356dd8cdd3d12c70421536c9033b6bfdac80808023a49df4509dc8"
+  },
+  "startedAt": "2026-09-09T15:09:50.530Z",
+  "finishedAt": "2026-09-09T15:09:51.628Z",
+  "attempts": {
+    "build": 1,
+    "verify": 1,
+    "review": 1
+  },
+  "budgets": {
+    "attempts": {
+      "consumed": 3,
+      "remaining": 1
+    }
+  },
+  "cost": {
+    "reviewRounds": 1,
+    "humanWaits": 1,
+    "infraFailures": 0,
+    "workerMs": 853
+  },
+  "workspaces": {
+    "RUN-EXPORT-01": {
+      "repo": ".",
+      "branch": "run/RUN-EXPORT-01",
+      "worktreePath": ".buildbeat/worktrees/RUN-EXPORT-01",
+      "base": "8f4ef5d4a4bd75c7765fbec860c3f5cbf1e0d02f",
+      "candidate": "be7e4f9c4d3d5dcd26132f98f660f9e217c47a97"
+    }
+  },
+  "evidence": [
+    {
+      "ref": ".buildbeat/runtime/runs/RUN-EXPORT-01/logs/build-1.log",
+      "kind": "command",
+      "subject": "be7e4f9c4d3d5dcd26132f98f660f9e217c47a97",
+      "digest": "sha256:1192f1c2a9a09f23c69d2c3935d2f7a0b3945f2b8aab979f811dd508183755c2",
+      "status": "passed",
+      "grade": "L2"
+    },
+    {
+      "ref": ".buildbeat/runtime/runs/RUN-EXPORT-01/logs/verify-1.log",
+      "kind": "command",
+      "subject": "be7e4f9c4d3d5dcd26132f98f660f9e217c47a97",
+      "digest": "sha256:603a7dd74be408af1575dca2c5a79bc5b211b9de3366812fb70603aa6121fc99",
+      "status": "passed",
+      "grade": "L2",
+      "cacheKey": "sha256:4425cad04706cc2c7f45e5306c573bf756d39d7aa0815d46406810331592e0ea"
+    },
+    {
+      "ref": ".buildbeat/runtime/runs/RUN-EXPORT-01/logs/review-1.log",
+      "kind": "command",
+      "subject": "be7e4f9c4d3d5dcd26132f98f660f9e217c47a97",
+      "digest": "sha256:65b9474c69d677a43341ee0af9f6865ca66a6c620d0ca71e7c1d61e6b806913e",
+      "status": "passed",
+      "grade": "L2"
+    },
+    {
+      "ref": ".buildbeat/runtime/runs/RUN-EXPORT-01/outputs/review-1.json",
+      "kind": "review",
+      "subject": "be7e4f9c4d3d5dcd26132f98f660f9e217c47a97",
+      "digest": "sha256:7c00d8d23d7d1b3f56006f4686a99bd8b3cc0839f105b524cabadd50dfa04f67",
+      "status": "passed",
+      "grade": "L2",
+      "findings": [
+        {
+          "severity": "P2",
+          "summary": "日期区间用字符串比较依赖 YYYY-MM-DD 格式，已有校验兜底，但可以在 export.js 顶部注释里写明这个前提"
+        }
+      ]
+    }
+  ],
+  "decisions": [
+    {
+      "decision": "approved",
+      "transition": "enter-wait-merge",
+      "subject": {
+        "candidate": "be7e4f9c4d3d5dcd26132f98f660f9e217c47a97",
+        "planDigest": "sha256:4f770dd7b20f14c3e64371ec475ea18f0b82e052fba1f3b8649b04d3ac7ec07a",
+        "evidenceDigest": "sha256:7c00d8d23d7d1b3f56006f4686a99bd8b3cc0839f105b524cabadd50dfa04f67"
+      },
+      "decisionRef": "D-RUN-EXPORT-01-1"
+    }
+  ],
+  "approvals": [
+    {
+      "decisionRef": "D-RUN-EXPORT-01-1",
+      "transition": "enter-wait-merge",
+      "subject": {
+        "candidate": "be7e4f9c4d3d5dcd26132f98f660f9e217c47a97",
+        "planDigest": "sha256:4f770dd7b20f14c3e64371ec475ea18f0b82e052fba1f3b8649b04d3ac7ec07a",
+        "evidenceDigest": "sha256:7c00d8d23d7d1b3f56006f4686a99bd8b3cc0839f105b524cabadd50dfa04f67"
+      },
+      "stale": false
+    }
+  ],
+  "unverified": []
+}

package/example/delivery/work/WORK-EXPORT-DATE-FILTER/workflow.yaml

@@ -0,0 +1,44 @@
+# Official software-delivery preset per docs/v2/RFC-0003-workflow-policy.md §2.
+# Step order defines the happy path (each step chains to the next on
+# "succeeded"); fix sits off-path at the end and is reached only via the
+# explicit failure/findings transitions.
+kind: workflow
+version: 1
+name: software-delivery
+entry: intent
+steps:
+  - id: intent
+    worker: planner
+  - id: spec
+    worker: planner
+    optional: true
+    requiredWhen: ui-delivery
+  - id: plan
+    worker: planner
+  - id: build
+    worker: builder
+  - id: verify
+    worker: verifier
+  - id: review
+    worker: reviewer
+    readonly: true
+  - id: wait-merge
+  - id: fix
+    worker: fixer
+transitions:
+  - from: verify
+    on: failed
+    to: fix
+  - from: fix
+    on: succeeded
+    to: verify
+  - from: review
+    on: findings-blocking
+    to: fix
+terminal:
+  - wait-merge
+# Review rounds are capped by default (deploy-campaign charter: two review
+# rounds per run, then a human). Override per project via budgets.maxAttempts.
+budgets:
+  maxAttempts:
+    review: 2

package/example/gitignore.template

@@ -0,0 +1,20 @@
+# 拷入新项目根后改名为 .gitignore(模板文件名不带点,避开 cp 通配符丢点文件的坑)
+
+# macOS
+.DS_Store
+
+# 凭据 / 本地环境(红线①:凭据不入 git)
+*.env
+.env
+.env.*
+*.local
+*.key
+*.pem
+
+# BuildBeat v2 运行时面与隔离工作树(可随时整删重建;不入 git)
+# 同时让 rg / 尊重 .gitignore 的工具不再走进旧工作树;vitest / jest 等要另配 exclude,见 docs/v2/guide/02-workflow-guide.md
+.buildbeat/runtime/
+.buildbeat/worktrees/
+
+# 单仓项目：没有子仓
+node_modules/

package/example/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "jianzhang",
+  "version": "0.3.0",
+  "private": true,
+  "description": "简账：一个虚构的个人记账小工具（BuildBeat 示例项目）",
+  "type": "module",
+  "scripts": {
+    "test": "node --test tests/*.test.js"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/example/pm/decisions.md

@@ -0,0 +1,8 @@
+# decisions — 拍板台账(全工作区唯一决策单点)
+
+> **规则(AGENTS ⑨ 单点事实)**:一个真实决策包收敛后,**第一动作 = 在此追加一行**(倒序),然后才去回写受影响的 SSOT(intent/plan/设计稿);「回写」列登记落点,没回写完 = 欠账可见。Run 级批准不进这里,它们由内核落在各 Work 的 `decisions.jsonl`。
+
+| 日期 | 拍板人 | 决策包 | 回写(落点 → 状态) |
+|---|---|---|---|
+| 2026-09-09 | 小周 | 【EXPORT-1】导出日期筛选:from/to 含端点;两端都可省;格式只认 `YYYY-MM-DD`,坏格式和 from>to 直接报错不静默;金额列保持两位小数、不加币种 | `delivery/work/WORK-EXPORT-DATE-FILTER/plan.md` → ✅ |
+| 2026-09-09 | 小周 | 【BOOTSTRAP】接入 BuildBeat:单仓、长期做;一个 Builder 端到端;`src/ledger.js` 为老地盘只维护;无 UI;worker 用 `codex exec`;通知先不接(等待只在 inbox 里);`standards/` 不生成 | `AGENTS.md` §1 边界、`delivery/envelope/prompts/*`、`run-config.yaml` → ✅ |

package/example/src/export.js

@@ -0,0 +1,25 @@
+// CSV 导出（新地盘）。WORK-EXPORT-DATE-FILTER 给它加了 from / to 日期筛选。
+
+const HEADER = "date,category,amount,note";
+
+function escapeCell(value) {
+  const text = String(value ?? "");
+  return /[",\n]/.test(text) ? `"${text.replace(/"/g, '""')}"` : text;
+}
+
+// options.from / options.to 都是含端点的 "YYYY-MM-DD"；省略一端表示不限。
+export function exportCsv(ledger, options = {}) {
+  const { from, to } = options;
+  for (const bound of [from, to]) {
+    if (bound !== undefined && !/^\d{4}-\d{2}-\d{2}$/.test(bound)) {
+      throw new Error(`bad date bound: ${bound}`);
+    }
+  }
+  if (from && to && from > to) {
+    throw new Error(`from ${from} is after to ${to}`);
+  }
+  const rows = ledger
+    .filter((entry) => (from === undefined || entry.date >= from) && (to === undefined || entry.date <= to))
+    .map((entry) => [entry.date, entry.category, (entry.amount / 100).toFixed(2), entry.note].map(escapeCell).join(","));
+  return [HEADER, ...rows].join("\n") + "\n";
+}

package/example/src/ledger.js

@@ -0,0 +1,16 @@
+// 记账核心（老地盘：只维护，改动一律先问人）。
+// 一条流水 = { date: "YYYY-MM-DD", category, amount, note }；金额以分为单位的整数。
+
+export function addEntry(ledger, entry) {
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(entry.date)) {
+    throw new Error(`bad date: ${entry.date}`);
+  }
+  if (!Number.isInteger(entry.amount)) {
+    throw new Error("amount must be an integer number of cents");
+  }
+  return [...ledger, { note: "", ...entry }];
+}
+
+export function total(ledger) {
+  return ledger.reduce((sum, entry) => sum + entry.amount, 0);
+}

package/example/tests/export.test.js

@@ -0,0 +1,35 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { exportCsv } from "../src/export.js";
+import { addEntry } from "../src/ledger.js";
+
+const ledger = [
+  { date: "2026-08-30", category: "餐饮", amount: 3550, note: "" },
+  { date: "2026-09-01", category: "交通", amount: 1200, note: "地铁, 两程" },
+  { date: "2026-09-15", category: "房租", amount: 250000, note: "" },
+];
+
+test("exports every row with a header when no bounds are given", () => {
+  const csv = exportCsv(ledger);
+  const lines = csv.trimEnd().split("\n");
+  assert.equal(lines[0], "date,category,amount,note");
+  assert.equal(lines.length, 4);
+  assert.equal(lines[2], '2026-09-01,交通,12.00,"地铁, 两程"');
+});
+
+test("from / to bounds are inclusive and each side is optional", () => {
+  assert.equal(exportCsv(ledger, { from: "2026-09-01" }).trimEnd().split("\n").length, 3);
+  assert.equal(exportCsv(ledger, { to: "2026-09-01" }).trimEnd().split("\n").length, 3);
+  assert.equal(exportCsv(ledger, { from: "2026-09-01", to: "2026-09-01" }).trimEnd().split("\n").length, 2);
+  assert.equal(exportCsv(ledger, { from: "2026-10-01" }), "date,category,amount,note\n");
+});
+
+test("malformed or inverted bounds are rejected, not silently ignored", () => {
+  assert.throws(() => exportCsv(ledger, { from: "2026/09/01" }), /bad date bound/);
+  assert.throws(() => exportCsv(ledger, { from: "2026-09-02", to: "2026-09-01" }), /is after/);
+});
+
+test("ledger entries still validate their own date", () => {
+  assert.throws(() => addEntry([], { date: "bad", category: "x", amount: 1 }), /bad date/);
+});

package/example//346/214/207/346/214/245/345/217/260.md

@@ -0,0 +1,40 @@
+# 指挥台 — 简账：Builder 怎么驱动工作（忘了怎么开场就看这页）
+
+> 本仓运行 BuildBeat。会话按所用工具的方式装载 `AGENTS.md`（多数工具自动读根目录 `AGENTS.md` / `CLAUDE.md`；不自动读的，开场把它贴给会话）；活动工作在 `delivery/`。你基本只需说下面这几句话，命令由会话调、不用你手敲。
+
+## 日常六句话
+
+| 你想干什么 | 说什么 | 会话背后调什么 |
+|---|---|---|
+| 看现在到哪了、该谁动 | 「当前进度」/「待办是什么」 | `buildbeat overview --repo .`（每个 Work 的阶段 + 下一步）+ `observe status` |
+| 看有什么等我批 | 「有什么要我拍板」 | `buildbeat inbox --repo .`（每条附可复制的下一句） |
+| 立一件新事 | 「开个 Work：〔一句话目标〕」→ 看完说「接受」 | 建 `delivery/work/<ID>/intent.md + plan.md` → `accept`（digest 绑定） |
+| 让它干活 | 「开工」/「再来一轮」 | 先 `buildbeat doctor --config …`（配置、intent/plan 接受状态、env 姿态、预算），再 `start --config … --attempt new`（自动编号、自动作废旧等待，停在合并决定） |
+| 它是不是卡了 | 「怎么样了」/「卡住了吗」 | `buildbeat status --repo . --run <RUN>`（耗时、历史中位数、最后输出、STALLED） |
+| 拍板 | 「批准 / 拒绝〔RUN-ID〕」；分诊时「这条接受，那条不算」 | `approve` / `reject` / `findings adjudicate`；会话说清批的是哪一步（放行 fixer / 再跑一次 / 合并决定），非终态批准后 `resume` 续跑；合并决定只表示候选够格合并，合并/push/部署逐项另说 |
+
+其他：生产报警看 `delivery/observe/intents/` 草稿 → 「fix_now / schedule / dismiss」；上线用 `release-readback` 预设开一个 Run，「我做完了」就是批准 `enter-apply-readback`；「打扫卫生」= `gc --repo .`（先看计划再 `--apply true`）。
+
+## 新开一个 Work 时会话要动的文件
+
+`delivery/work/<WORK-ID>/`：`intent.md`（为什么 + 止损线）、`plan.md`（怎么做）、`run-config.yaml`（从 `templates/v2/run-config.example.yaml` 改 work / run / allowedPaths / workers）、`workflow.yaml`（从 `$(npm root -g)/@haiyangbg/buildbeat/src/v2/presets/software-delivery.yaml` 复制）。信封与 worker 包装在仓级 `delivery/envelope/`，不用每个 Work 重写。
+
+## 视角开场白
+
+| AI 视角 | 在哪开（cwd） | 你的一句话 |
+|---|---|---|
+| **产品** | 工作区根 | 「把当前目标收成一个 Work」/「验收」——定 intent/plan、维护决策收件箱、按决策包记 `pm/decisions.md` |
+| **全栈** | `<代码仓>/` | 「〔WORK-ID〕该你了，开工」——授权范围内实现，Run 停在合并决定回人批 |
+| **测试** | 工作区根 | 「验〔RUN-ID〕候选」——对精确 candidate 独立核验，报告落所属 Work 目录 |
+
+## 域回复怎么写
+
+面向你收口统一「已做 → 未做 → 下一步」，各一句；证据紧跟事项。下一步只写一条：下一棒是谁、需要你确认什么、或「我继续做，暂不交棒」。
+
+## 按项目阶段的完整问法
+
+未开始 → 立项定方案 → 准备执行 → 执行推进 → 验收合并 → 上线 → 完结换期复盘，每阶段说什么、会话做什么、你得到什么：见 BuildBeat 指南第 0 篇 `docs/v2/guide/00-how-to-talk.md`（Skill 装载目录下同路径）。
+
+## 红线、写边界、审批三级、可见命名进决策卡
+
+全在 `AGENTS.md`，本页不复制。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@haiyangbg/buildbeat",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "description": "BuildBeat: Git-based AI delivery across models, tools, sessions, and people, with context in project files, build-test-review-fix loops, and human decisions.",
   "type": "module",
   "bin": {
@@ -22,6 +22,7 @@
     "!docs/PHASE*.md",
     "!docs/CLI-STRATEGY-2026-08.md",
     "!docs/CLI-PILOT-2026-08-23.md",
+    "example/",
     "src/",
     "templates/",
     "CHANGELOG.md",