@haiyangbg/buildbeat 0.0.0 → 1.20.0

package/src/writer.js

@@ -0,0 +1,534 @@
+import { createHash } from "node:crypto";
+import {
+  chmodSync,
+  closeSync,
+  existsSync,
+  fsyncSync,
+  lstatSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  renameSync,
+  rmdirSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import {
+  CLI_VERSION,
+  FILE_POLICIES,
+  GITIGNORE_BEGIN_MARKER,
+  GITIGNORE_END_MARKER,
+  GITIGNORE_MARKER_PAIRS,
+  MANIFEST_PATH,
+  MANIFEST_SCHEMA_VERSION,
+  RENDER_REQUIRED_PLACEHOLDERS,
+  SCAFFOLD_VERSION,
+} from "./constants.js";
+import { inspectProject, plannedFiles } from "./project.js";
+
+const TEMPLATE_ROOT = fileURLToPath(new URL("../templates/", import.meta.url));
+const COMPACT_SCRIPT_REFERENCE_TEMPLATES = new Set([
+  "AGENTS.md",
+  "ARCHITECTURE.md",
+  "contracts/PROTOCOL.md",
+  "pm/NOW.md",
+  "pm/status/README.md",
+  "pm/当期看板.md",
+  "指挥台.md",
+]);
+
+export class WriteError extends Error {
+  constructor(code, message, cause = null) {
+    super(message, cause ? { cause } : undefined);
+    this.name = "WriteError";
+    this.code = code;
+  }
+}
+
+function sha256(bytes) {
+  return createHash("sha256").update(bytes).digest("hex");
+}
+
+function replaceAll(text, token, value) {
+  return text.split(token).join(value);
+}
+
+function stableDate(now) {
+  const value = now instanceof Date ? now : new Date(now);
+  if (Number.isNaN(value.getTime())) {
+    throw new WriteError("render.invalid_date", "The scaffold render date is invalid.");
+  }
+  return value;
+}
+
+function localCalendarDate(now) {
+  const value = stableDate(now);
+  const year = String(value.getFullYear()).padStart(4, "0");
+  const month = String(value.getMonth() + 1).padStart(2, "0");
+  const day = String(value.getDate()).padStart(2, "0");
+  return `${year}-${month}-${day}`;
+}
+
+function deterministicValues({ layout, projectName, now }) {
+  return new Map([
+    ["<项目名>", projectName || "project"],
+    ["<yyyy-mm-dd>", localCalendarDate(now)],
+    ["<X.Y>", SCAFFOLD_VERSION.replace(/^v/, "")],
+    ["<默认|紧凑>", layout === "compact" ? "紧凑" : "默认"],
+  ]);
+}
+
+function ownedGitignoreFragment(body) {
+  const normalizedBody = body.replace(/\r\n/g, "\n").replace(/\n*$/, "");
+  return Buffer.from(
+    `${GITIGNORE_BEGIN_MARKER}\n${normalizedBody}\n${GITIGNORE_END_MARKER}\n`,
+    "utf8",
+  );
+}
+
+export function prepareScaffold({ layout, projectName, now = new Date() }) {
+  const values = deterministicValues({ layout, projectName, now });
+  const files = [];
+  const renderedPlaceholders = [];
+  const pendingPlaceholders = [];
+  let gitignore = null;
+
+  for (const item of plannedFiles(layout)) {
+    const source = path.join(TEMPLATE_ROOT, item.template);
+    let text = readFileSync(source, "utf8");
+    for (const [token, value] of values) {
+      if (text.includes(token)) {
+        text = replaceAll(text, token, value);
+        renderedPlaceholders.push({ path: item.target, token, value });
+      }
+    }
+    if (
+      layout === "compact" &&
+      COMPACT_SCRIPT_REFERENCE_TEMPLATES.has(item.template) &&
+      text.includes("scripts/")
+    ) {
+      text = replaceAll(text, "scripts/", "pm/scripts/");
+      renderedPlaceholders.push({
+        path: item.target,
+        token: "scripts/",
+        value: "pm/scripts/",
+      });
+    }
+
+    const pendingTokens = (RENDER_REQUIRED_PLACEHOLDERS[item.template] || [])
+      .filter((token) => text.includes(token));
+    if (pendingTokens.length > 0) {
+      pendingPlaceholders.push({ path: item.target, tokens: pendingTokens });
+    }
+
+    const mode = lstatSync(source).mode & 0o777;
+    if (item.policy === FILE_POLICIES.MERGE_ONLY) {
+      const fragment = ownedGitignoreFragment(text);
+      gitignore = {
+        ...item,
+        fragment,
+        baselineSha256: sha256(fragment),
+        mode,
+      };
+    } else {
+      const content = Buffer.from(text, "utf8");
+      files.push({
+        ...item,
+        content,
+        baselineSha256: sha256(content),
+        mode,
+      });
+    }
+  }
+
+  renderedPlaceholders.sort((a, b) =>
+    a.path.localeCompare(b.path) || a.token.localeCompare(b.token),
+  );
+  pendingPlaceholders.sort((a, b) => a.path.localeCompare(b.path));
+  if (gitignore === null) {
+    throw new WriteError("integration.gitignore_missing", "The bundled gitignore template is missing.");
+  }
+  return { files, gitignore, renderedPlaceholders, pendingPlaceholders };
+}
+
+function ensureDirectory(directory, createdDirectories) {
+  if (existsSync(directory)) {
+    const stat = lstatSync(directory);
+    if (!stat.isDirectory() || stat.isSymbolicLink()) {
+      throw new WriteError("path.unsafe", `A required directory path is not a real directory: ${directory}`);
+    }
+    return;
+  }
+  const parent = path.dirname(directory);
+  if (parent === directory) {
+    throw new WriteError("path.unsafe", `Cannot create target directory: ${directory}`);
+  }
+  ensureDirectory(parent, createdDirectories);
+  try {
+    mkdirSync(directory, { mode: 0o755 });
+    createdDirectories.push(directory);
+  } catch (error) {
+    if (error.code === "EEXIST") {
+      ensureDirectory(directory, createdDirectories);
+      return;
+    }
+    throw error;
+  }
+}
+
+function assertRelativeTarget(relative) {
+  if (
+    typeof relative !== "string" ||
+    relative.length === 0 ||
+    relative.includes("\\") ||
+    path.posix.isAbsolute(relative) ||
+    path.win32.isAbsolute(relative) ||
+    path.posix.normalize(relative) !== relative ||
+    relative.split("/").some((segment) => segment === "" || segment === "." || segment === "..")
+  ) {
+    throw new WriteError("path.unsafe", `Unsafe scaffold target path: ${relative}`);
+  }
+}
+
+function ensureTargetParent(target, relative, createdDirectories) {
+  assertRelativeTarget(relative);
+  ensureDirectory(path.dirname(path.join(target, ...relative.split("/"))), createdDirectories);
+}
+
+function fsyncDirectory(directory) {
+  if (process.platform === "win32") {
+    return;
+  }
+  const descriptor = openSync(directory, "r");
+  try {
+    fsyncSync(descriptor);
+  } finally {
+    closeSync(descriptor);
+  }
+}
+
+function atomicWrite(
+  filename,
+  bytes,
+  mode,
+  { overwrite = false, nextTempId, onRenamed = null },
+) {
+  const parent = path.dirname(filename);
+  const basename = path.basename(filename);
+  let temp = null;
+  let descriptor = null;
+  try {
+    for (let attempt = 0; attempt < 100; attempt += 1) {
+      const candidate = path.join(
+        parent,
+        `.${basename}.buildbeat-${process.pid}-${nextTempId()}-${attempt}.tmp`,
+      );
+      try {
+        descriptor = openSync(candidate, "wx", mode);
+        temp = candidate;
+        break;
+      } catch (error) {
+        if (error.code !== "EEXIST") {
+          throw error;
+        }
+      }
+    }
+    if (descriptor === null || temp === null) {
+      throw new WriteError("write.temp_unavailable", `Could not allocate a temporary sibling for ${filename}.`);
+    }
+    writeFileSync(descriptor, bytes);
+    fsyncSync(descriptor);
+    closeSync(descriptor);
+    descriptor = null;
+    chmodSync(temp, mode);
+
+    if (!overwrite && existsSync(filename)) {
+      throw new WriteError("files.collide", `Destination appeared during the write transaction: ${filename}`);
+    }
+    if (overwrite) {
+      const current = lstatSync(filename);
+      if (!current.isFile() || current.isSymbolicLink()) {
+        throw new WriteError("integration.gitignore_unsafe", ".gitignore is no longer a regular file.");
+      }
+    }
+    renameSync(temp, filename);
+    temp = null;
+    if (typeof onRenamed === "function") {
+      onRenamed();
+    }
+    fsyncDirectory(parent);
+  } finally {
+    if (descriptor !== null) {
+      closeSync(descriptor);
+    }
+    if (temp !== null) {
+      try {
+        unlinkSync(temp);
+      } catch (error) {
+        if (error.code !== "ENOENT") {
+          throw error;
+        }
+      }
+    }
+  }
+}
+
+function markerCount(text, marker) {
+  return text.split(marker).length - 1;
+}
+
+function assertGitignoreBytesSafe(bytes) {
+  const text = bytes.toString("utf8");
+  if (GITIGNORE_MARKER_PAIRS.some(
+    ([beginMarker, endMarker]) =>
+      markerCount(text, beginMarker) !== 0 || markerCount(text, endMarker) !== 0,
+  )) {
+    throw new WriteError(
+      "integration.gitignore_fragment_present",
+      "A BuildBeat or legacy Solobaton .gitignore marker already exists without a valid schema 2 ownership record.",
+    );
+  }
+}
+
+function mergeGitignore(existing, fragment) {
+  if (existing.length === 0) {
+    return fragment;
+  }
+  const separator = existing.at(-1) === 0x0a ? Buffer.from("\n") : Buffer.from("\n\n");
+  return Buffer.concat([existing, separator, fragment]);
+}
+
+function preflight(plan) {
+  if (plan.preview || plan.writesPerformed || !["init", "adopt"].includes(plan.command)) {
+    throw new WriteError("write.invalid_plan", "Only a ready init/adopt apply plan can be written.");
+  }
+  let inspection;
+  try {
+    inspection = inspectProject(plan.target, {
+      collisionLayout: plan.layout,
+      includeDependencies: false,
+    });
+  } catch (error) {
+    throw new WriteError("target.unsafe", error.message, error);
+  }
+  if (plan.command === "adopt" && !inspection.exists) {
+    throw new WriteError("target.not_found", "Brownfield adoption requires an existing project directory.");
+  }
+  if (inspection.installation.state !== "not-installed") {
+    throw new WriteError(
+      `install.${inspection.installation.state.replaceAll("-", "_")}`,
+      "The target is already installed, partial, or mixed; no write was attempted.",
+    );
+  }
+  if (inspection.manifest.state !== "missing") {
+    throw new WriteError(
+      "manifest.already_present",
+      "A lifecycle manifest already exists or is unreadable; ownership cannot be inferred.",
+    );
+  }
+  if (inspection.collisions.length > 0) {
+    throw new WriteError(
+      "files.collide",
+      `${inspection.collisions.length} destination path(s) collide with existing project content.`,
+    );
+  }
+  if (inspection.gitWorktree.state === "dirty") {
+    throw new WriteError("git.dirty", "The target-root Git worktree is not clean.");
+  }
+  if (inspection.gitWorktree.state === "unavailable") {
+    throw new WriteError("git.status_unavailable", "The target has a root .git entry, but Git status failed.");
+  }
+  if (inspection.gitignore.state === "unsafe") {
+    throw new WriteError("integration.gitignore_unsafe", ".gitignore is not a readable regular file.");
+  }
+  if (inspection.gitignore.beginMarkers > 0 || inspection.gitignore.endMarkers > 0) {
+    throw new WriteError(
+      "integration.gitignore_fragment_present",
+      "A BuildBeat or legacy Solobaton .gitignore marker already exists without a valid schema 2 ownership record.",
+    );
+  }
+  return inspection;
+}
+
+function rollback({ createdFiles, createdDirectories, gitignoreBackup, gitignoreModified, nextTempId }) {
+  const failures = [];
+  for (const filename of [...createdFiles].reverse()) {
+    try {
+      unlinkSync(filename);
+    } catch (error) {
+      if (error.code !== "ENOENT") {
+        failures.push(`${filename}: ${error.code || error.message}`);
+      }
+    }
+  }
+  if (gitignoreModified && gitignoreBackup !== null) {
+    try {
+      atomicWrite(
+        gitignoreBackup.path,
+        gitignoreBackup.bytes,
+        gitignoreBackup.mode,
+        { overwrite: true, nextTempId },
+      );
+    } catch (error) {
+      failures.push(`${gitignoreBackup.path}: ${error.code || error.message}`);
+    }
+  }
+  for (const directory of [...createdDirectories].reverse()) {
+    try {
+      rmdirSync(directory);
+    } catch (error) {
+      if (error.code !== "ENOENT" && error.code !== "ENOTEMPTY") {
+        failures.push(`${directory}: ${error.code || error.message}`);
+      }
+    }
+  }
+  return failures;
+}
+
+export function applyScaffold(plan, { now = new Date(), faultInjector = null } = {}) {
+  const inspection = preflight(plan);
+  const rendered = prepareScaffold({
+    layout: plan.layout,
+    projectName: inspection.projectName.value,
+    now,
+  });
+  const target = path.resolve(plan.target);
+  const createdFiles = [];
+  const createdDirectories = [];
+  let gitignoreBackup = null;
+  let gitignoreModified = false;
+  let tempId = 0;
+  const nextTempId = () => {
+    tempId += 1;
+    return tempId;
+  };
+  const maybeFault = (phase, relative) => {
+    if (typeof faultInjector === "function") {
+      faultInjector({ phase, path: relative, writes: createdFiles.length });
+    }
+  };
+
+  try {
+    ensureDirectory(target, createdDirectories);
+
+    for (const item of rendered.files) {
+      ensureTargetParent(target, item.target, createdDirectories);
+      const filename = path.join(target, ...item.target.split("/"));
+      atomicWrite(filename, item.content, item.mode, {
+        nextTempId,
+        onRenamed: () => createdFiles.push(filename),
+      });
+      maybeFault("file", item.target);
+    }
+
+    const gitignorePath = path.join(target, ".gitignore");
+    ensureTargetParent(target, ".gitignore", createdDirectories);
+    let existingGitignore = Buffer.alloc(0);
+    let gitignoreMode = rendered.gitignore.mode || 0o644;
+    const gitignoreExisted = existsSync(gitignorePath);
+    if (gitignoreExisted) {
+      const stat = lstatSync(gitignorePath);
+      if (!stat.isFile() || stat.isSymbolicLink()) {
+        throw new WriteError("integration.gitignore_unsafe", ".gitignore is not a regular file.");
+      }
+      existingGitignore = readFileSync(gitignorePath);
+      assertGitignoreBytesSafe(existingGitignore);
+      gitignoreMode = stat.mode & 0o777;
+      gitignoreBackup = { path: gitignorePath, bytes: existingGitignore, mode: gitignoreMode };
+    }
+    atomicWrite(
+      gitignorePath,
+      mergeGitignore(existingGitignore, rendered.gitignore.fragment),
+      gitignoreMode,
+      {
+        overwrite: gitignoreExisted,
+        nextTempId,
+        onRenamed: () => {
+          if (gitignoreExisted) {
+            gitignoreModified = true;
+          } else {
+            createdFiles.push(gitignorePath);
+          }
+        },
+      },
+    );
+    maybeFault("gitignore", ".gitignore");
+
+    const manifest = {
+      schemaVersion: MANIFEST_SCHEMA_VERSION,
+      scaffoldVersion: SCAFFOLD_VERSION,
+      cliVersion: CLI_VERSION,
+      layout: plan.layout,
+      installedAt: stableDate(now).toISOString(),
+      files: Object.fromEntries(
+        rendered.files.map((item) => [
+          item.target,
+          { policy: item.policy, baselineSha256: item.baselineSha256 },
+        ]),
+      ),
+      integrations: {
+        gitignore: {
+          path: ".gitignore",
+          beginMarker: GITIGNORE_BEGIN_MARKER,
+          endMarker: GITIGNORE_END_MARKER,
+          baselineSha256: rendered.gitignore.baselineSha256,
+        },
+        hooks: null,
+      },
+    };
+    ensureTargetParent(target, MANIFEST_PATH, createdDirectories);
+    maybeFault("before-manifest", MANIFEST_PATH);
+    const manifestFilename = path.join(target, ...MANIFEST_PATH.split("/"));
+    atomicWrite(
+      manifestFilename,
+      Buffer.from(`${JSON.stringify(manifest, null, 2)}\n`, "utf8"),
+      0o644,
+      {
+        nextTempId,
+        onRenamed: () => createdFiles.push(manifestFilename),
+      },
+    );
+
+    return {
+      ...plan,
+      preview: false,
+      writesPerformed: true,
+      targetExists: true,
+      detected: {
+        ...plan.detected,
+        projectName: inspection.projectName,
+      },
+      writtenPaths: [
+        ...rendered.files.map((item) => item.target),
+        ".gitignore",
+        MANIFEST_PATH,
+      ],
+      renderedPlaceholders: rendered.renderedPlaceholders,
+      pendingPlaceholders: rendered.pendingPlaceholders,
+      manifestPath: MANIFEST_PATH,
+      ready: true,
+    };
+  } catch (error) {
+    const rollbackFailures = rollback({
+      createdFiles,
+      createdDirectories,
+      gitignoreBackup,
+      gitignoreModified,
+      nextTempId,
+    });
+    if (rollbackFailures.length > 0) {
+      throw new WriteError(
+        "rollback.incomplete",
+        `Write failed and rollback was incomplete: ${rollbackFailures.join("; ")}`,
+        error,
+      );
+    }
+    if (error instanceof WriteError) {
+      throw error;
+    }
+    throw new WriteError("write.failed", `Scaffold write failed and was rolled back: ${error.message}`, error);
+  }
+}

package/templates/.claude/agents/reviewer.md

@@ -0,0 +1,62 @@
+---
+name: reviewer
+description: review-ready 后单次静默执行的只读审查专家。按 milestone / risk-delta / closure 三种模式核查;未稳定候选返回 NOT_READY,审查中 hash 改变返回 SUPERSEDED。
+tools: Read, Grep, Glob, Bash
+---
+
+你是 <项目名> 的资深独立审查者。**写者≠审者**是质量硬约束 —— 你只读、只出问题清单,**绝不修改代码**。
+
+> `Bash` 只用于读取候选事实(`git status --short` / `git rev-parse` / `git diff` / `git show` / `git log`)和运行项目已经声明的本地验证命令。禁止 checkout / switch / restore / clean / add / commit / push,禁止安装依赖、联网、部署或用 shell 写文件;命令可能改工作树时不要运行。
+
+> **单次静默核查**:除输入缺失或真实阻塞外,不要向主会话发送中间进度、分批 findings 或“仍在审”更新;完成整个 scope 后,先重新读取每个候选仓的 `HEAD` 与 `git status --short`,确认 candidate 未变且仍干净,再一次返回最终正文。发生变化只回 `SUPERSEDED`,避免一轮审查制造多轮 reviewer 状态噪音。
+
+## 背景
+- 项目用「协作总线」多域协作;全栈域可能同时持有契约两端 → **你是契约自审风险的补偿防线**。
+- 唯一契约入口 = `contracts/PROTOCOL.md`;当期需求/设计在 `pm/NOW.md` 指向的看板 + `pm/changes/`。
+- 核查门按**风险批次 + 里程碑候选**运行,不是每个小任务都重跑一次完整审查。轻量机器闸每次提交,受影响测试按变更批次,全量测试绑定里程碑候选。
+
+## 调用输入(先核这五项)
+
+主会话应给出:
+
+1. `mode`: `milestone` / `risk-delta` / `closure`。
+2. `candidate`:精确 commit hash;多仓则给 hash 集。`milestone` 没有 candidate → 只能判「候选未固定」,不得给可合并结论。
+3. `base`:`risk-delta` 必填,审查范围固定为 `base..candidate`;`closure` 改填 finding ID + 修复 hash。
+4. `scope`:需求/设计/契约/提案/证据入口。能从 NOW 自查到的不要反问人。
+5. `review_ready`:`milestone` 必须给出以下四项证据,缺一项就只返回 `NOT_READY`,不展开审查:
+   - 工作包内实现与写者自查已完成,没有已知待修项或计划中的 candidate 修改;
+   - 每个候选仓 `HEAD=candidate`,且 `git status --short` 为空;
+   - 受影响/全量自动化达到项目要求的 L3,有 UI 时真渲染证据已就绪;
+   - candidate 与证据指针已固定,reviewer 期间主会话不会继续修改候选。
+
+### 三种模式
+
+- **`milestone`**:只对 review-ready 的稳定候选 hash 集做一次完整四方核查;默认唯一会产生完整报告的模式。写者自查尚在发现/修复问题时不得启动。
+- **`risk-delta`**:只核修改已冻结对外契约、里程碑完成后新出现的鉴权/租户/Secret/fail-closed/持久化语义或不可逆外部副作用;写者在首次 milestone 前自行发现并收敛的问题不是 risk-delta。结论只覆盖该 delta,**不得外推为整体候选通过**。
+- **`closure`**:主会话应先把首轮 P0/P1 全部合并修完,再一次复核指定 finding 集与必要回归;不得按 finding 逐个调用,不得复制首轮整份背景或重新发散无关 P2。
+
+若同一 candidate 已有 milestone 结论且 hash 未变、机器证据仍绿,直接指出「复用既有结论」;**不要为再放心一次重复全审**。审查返回前 candidate 有变化,立即返回 `SUPERSEDED: <old> -> <new>` 并停止,不得继续核旧 hash 或把写者自发现的连续修补包装成 delta 链;主会话重新满足 review-ready 后再提交替代 milestone。milestone 已完成后,指定 finding 修复走一次合并 `closure`,真正新增的高风险语义走 `risk-delta`;无关改动混进 closure 时判范围不纯。最终候选由「原 milestone 结论 + 后续必要的 delta/closure」覆盖,不把旧 hash 的结论冒充新 hash 结论。
+
+## 审什么(按此顺序,逐条给证据)
+1. **四方一致**:实现 ↔ 设计稿(`design/`)↔ 契约(`contracts/PROTOCOL.md`)↔ 需求(当期 spec/提案)。任一方对不上 = 问题。
+2. **契约两端**:调用方与实现方是否都符合 PROTOCOL(字段名/类型/鉴权/错误码)。同会话改两端最易绕过核查——重点盯。
+3. **架构违规 / 重复造轮子 / 边界条件**。
+4. **安全**:鉴权服务端强制(非按钮隐藏)、凭据不落盘、注入/SSRF、多用户数据隔离。
+5. **四态**(有 UI 时):加载 / 空 / 错误 / 移动端是否都处理。
+6. **界面零元注释**(有 UI 时):可见界面无调试信息 / 口径解释脚注 / 字段说明 / mock 标记 / 开发者自留文案;发现通常判 P1。
+
+## 输出
+- 头部固定列出:`mode` / `base` / `candidate`(多仓 hash 集)/ scope / 证据状态(已复跑 / 只读核验 / 未复跑及原因)。
+- `milestone` 头部另列 review-ready 四项;任一不成立就只输出 `NOT_READY + 缺项`,不产生 P0/P1/P2 报告。
+- 按严重度排序:🔴 P0(阻塞)/ 🟡 P1(阻塞)/ 🟢 P2(默认挂账,不触发一轮完整复核;项目立项时显式升格的除外)。
+- **每条带可核验证据**:`文件:行` / 契约条目 / 复现步骤。无证据的猜测标「待核」,不混入结论。
+- 不照单全收上游说法:宁可标「未确认」也不臆断。
+- 首轮 milestone 报告只保留一份问题原文;主会话合并修完 P0/P1 后,closure 一次追加下表,不重述全文:
+
+| Finding | 修复 hash | 复核范围 | 结果 |
+|---|---|---|---|
+
+- `milestone` 结尾给一句:□ 可合并　□ 修 P0/P1 再合　□ 不通过。
+- `risk-delta` / `closure` 结尾给一句:□ 本 delta/finding 已关闭　□ 仍阻塞;并明确「不代表整体候选通过」。
+
+交回主会话,由人在 Gate3 决定是否合并。**你不合并、不放行。**

package/templates/AGENTS.md

@@ -0,0 +1,64 @@
+# AGENTS.md — <项目名> 工作区 · 工作包路由 + 协作总线
+
+> 本文件走开放标准 `AGENTS.md`,被工作区下**任意会话**自动装载(Claude Code / Cursor / Codex / Gemini CLI / Aider / Zed 等均认)。目的:每个会话开工即知道「当前工作包 / AI 视角 / 读哪 / 写哪」,不靠人转述上下文。
+> **层叠规则**(标准语义):会话从被编辑文件所在目录向上收集沿途所有 `AGENTS.md` 合并,**离得越近优先级越高**。所以本文件只写全局的(路由 / 总线规则 / 红线),各代码子仓的局部细节写进**该仓自己的 `AGENTS.md`**,别往上堆。
+> 全栈总图(架构/基础设施/凭据位置)见 `./ARCHITECTURE.md`,按需读、别全文灌(重)。
+> 根目录的 `CLAUDE.md` 只是一行指针(兼容只认该文件名的工具),**内容单点在本文件**,别往那份里复制任何规则。
+
+## 1. 工作包路由 —— Builder 端到端负责,会话按 AI 视角隔离
+
+> 协作单元是需求/功能工作包。一个 Builder 对工作包的产品判断、实现、测试、合并和发布证据端到端负责;下表只是可调用的 AI 专业视角与文件写边界,不是人类岗位或审批链。多个 Builder 默认认领不同工作包,共享事实仍走 Git 文件总线。
+
+| AI 视角 | cwd | 可写(拥有) | 只读 | 开工先读 | 状态写回 |
+|---|---|---|---|---|---|
+| **产品**(规格/编排) | `pm/` | `pm/**` | 全仓 | `pm/NOW.md` | 当期看板 + `pm/status/产品.md` |
+| **全栈**(实现,含运维) | 工作区根(同持 <N> 个代码仓) | `<代码仓1>/**` + `<代码仓2>/**`(**按仓分别 stage,不 `git add -A`**) | `pm/*` 当期文件、契约 | 各代码仓自己的 `AGENTS.md` + `pm/NOW.md` | `pm/status/全栈.md`(带 hash)+ 各仓 `CHANGELOG.md` + `contracts/PROTOCOL.md` |
+| **测试**(E2E·走查) | `<被测仓>/` | `tests/**` · 视觉基线 · 走查报告 | 实现 + spec + 设计稿 + 契约 | `pm/NOW.md` + `tests/README.md` | `pm/status/测试.md` + 核查门证据(E2E 报告/视觉 diff/对比图,**落 `pm/archive/<期>/evidence/`,换期零搬运**) |
+
+> **设计生成 = 外部工具**(非会话):产品视角写 brief(必须要求**单 HTML 可渲染入口 + 关键流可点**)→ 人喂设计工具 → 稿落 `design/design_N期/` → 测试视角走查 + 提带图 bug。
+> 🔴 **同一 Builder 合并多视角的补偿控制**:里程碑候选必须由 reviewer subagent(只读,见 `.claude/agents/reviewer.md`)全核 + 测试视角独立核两端;实现中出现冻结契约/鉴权/租户/Secret/fail-closed/持久化或不可逆副作用变化时做 `risk-delta` 定向核。写者≠审者不变,但不按每个草稿或小任务重复全审。
+> **开工/收工护栏**:任意会话开工**先跑 `bash scripts/bus-check.sh`** + 各仓 `git pull`;收工前回写证据/状态后再跑 `bus-check --strict`,并保留 warning/unverified 边界。
+
+## 1.5 UI 规范摘要(非 UI 项目可删)
+
+> 项目若启用可选规范，完整设计原则、token、组件、交互、状态与可访问性单点见 `standards/DESIGN.md`；本文件只保留开工必读摘要，不复制正文。该文件缺失不报错。
+
+- 延用既定设计语言与 token；每个可见流程处理 loading / empty / error / disabled / 适用的移动端状态，关键操作提供明确且可访问的反馈。
+- 上线界面零调试信息、实现说明、mock 标记或开发者元注释；Gate2 与终签都以真渲染可点结果走查，静态稿或规范数值不能替代。
+
+## 2. 协作总线十条规则
+
+**① 唯一看板指针** —— 入口永远是 `pm/NOW.md`,它指向当期看板;**换期只改 NOW 一处,看板文件名不得写死进本文件或其它文档**。
+**② 契约落盘不喊话** —— 跨边界接口先改 `contracts/PROTOCOL.md` 再动代码;收到协议声明**独立核查再信**(实测/读代码/查部署配置),不照单全收。
+**③ 交接靠 commit + 落盘** —— 工作包完成或到真实阻塞点 → 状态行带**交付候选/报告** commit hash,下游读 repo 即知进度;hash 不是 status 行自身 commit(禁止自引用)。原子 commit 可以多次,但不为每个 commit 单独收尾和打断人;尚无新候选就写已核基线 hash +「无新候选」,不得编 hash。
+**④ 开工 + 收工护栏** —— 开工先 `bash scripts/bus-check.sh` + 各仓 `git pull`;**部署/改契约/migration 等不可逆动作前再跑一次**。收工前跑受影响测试,回写 contracts/decisions/看板/status/证据,再跑 `bus-check --strict`;它的 exit 0 不消除 warning/unverified。pre-commit 挂同一 strict 机器闸(见 `scripts/pre-commit.sh`)。
+**⑤ 三轨制** —— 快轨(小改:直接改+核查门)/ 标准轨(单功能全流程)/ 重轨(契约变更/大改:+`pm/changes/` 提案+多 agent 评审);NOW 标本期轨道。工作包默认取一条可独立验收的纵向结果或下一个 Gate/里程碑候选,不按文件、commit 或验收条目拆会话。
+**⑥ 核查门(review-ready + 一次候选核查)** —— 轻量机器闸每次提交都跑,受影响自动化测试按变更批次跑。**首次 milestone reviewer 只能在 review-ready 后启动**:工作包内实现与写者自查已完成;所有候选仓 `HEAD=candidate` 且工作树干净;受影响/全量 L3 与真渲染证据已绿;没有已知待修项或计划中的 candidate 修改。此前发现的鉴权/租户/Secret/fail-closed/持久化等实现问题统一记入实现语义清单并先自行收敛,**不得边改 candidate 边开 reviewer**;只有要修改已冻结对外契约或产生不可逆外部副作用才 `STOP_NOW`,批准后按一个风险批次做 `risk-delta`。默认每个工作包、每道 Gate 只启动 **1 次 milestone**;P0/P1 全部修完后再做 **1 次合并 closure**,P2 不复核。reviewer 返回前 candidate 若变化,原审查立即标 `SUPERSEDED`,不得把写者自发现的连续修补包装成 delta 链;重新满足 review-ready 后才启动替代 milestone。已完成 milestone 后出现新的高风险语义变化才核 `risk-delta`;同一 candidate 且机器证据仍绿直接复用。首轮报告保留原文,closure 只追加表。**完成 = hash + 可核验证据**;标准轨最低 L3,重轨与上线必须 L4,L1 只作补充定位。
+**⑦ 变更提案 + 状态分写** —— 跨工作包/共享边界变更走 `pm/changes/` delta 提案;**各 AI 视角只写自己的 `pm/status/{视角}.md`**,别人只读。状态按工作包/里程碑批量更新,不为每个子产物另起一次交接。
+**⑧ 视觉问题带图对比** —— 提 UI bug / 判设计符合性必附『实现截图 ⟷ 设计稿截图』并排 + 标注差异点;纯文字不算证据。
+**⑨ 单点事实** —— 线上版本只信 `bus-check` 实查(任何文档不写"当前线上 vX",契约快照版本仅 `PROTOCOL.md` 头部);多仓项目的 repo/契约/本地部署基线 app 关系只写在 `PROTOCOL.md` 的 `buildbeat-multirepo-map:v1`,不从自然语言猜;每个收敛后的**真实决策包**只在 `pm/decisions.md` 记一行并回写落点,验收条目/推导结论/部分对话进度不单独记拍板;换期必跑压缩仪式(NOW 底部 checklist),**NOW 永远是薄指针、禁堆流水**。
+**⑩ Gate2 真渲染拍板** —— 设计拍板对象必须是真渲染可点原型(`bash scripts/design-preview.sh <期号>`);静态稿/截图只作参考。终签同样含真渲染走查。
+
+> **元原则:能实查的不问人** —— 查代码 / 配置 / 部署平台能得到的事实,不拿去问用户、不信文档、不信上游转述(规则⑨与②的推广)。
+
+## 2.5 任务包与人批节奏
+
+**任务包信封** —— 多步骤工作开工时,从用户目标与当期看板明确 `objective / in_scope / terminal_condition`。需求 ID、验收项、文档和原子 commit 可以细分,但只是追踪单位;默认一个工作包覆盖多个子项。一个工作包可由多个域按写边界接力,多个独立目标也可并行,但每个会话同时只认领一个工作包。只要仍有安全、可逆、在 `in_scope` 内且能推进 `objective` 的工作,会话就继续做。单个文档提交、reviewer 返回、status 回写或普通 P2 只报中间进展,**不得因此结束任务等用户说“继续”**。只在以下三种情况结束:目标带证据完成;遇到必须由人处理的真实阻塞;用户明确只要阶段性检查点。
+
+**审批三级**:
+
+1. **STOP_NOW 立即停**:跨 Gate;扩大已批准范围或重开 non-goal;修改已冻结对外契约;部署/发布/花费/删除等不可逆外部动作;接受安全/合规风险;权威事实冲突且无法实查。停在动作前,一次给推荐方案、影响和最小问题。
+2. **BATCH_AT_GATE 门前批**:冻结前可逆草案选择,或批准目标内的默认值/阈值/失败态归类/实现语义。先写进当期看板「决策收件箱」,继续不依赖它的工作;到 Gate 或约定节奏一次提交**默认 2–5 个真实取舍**(确实只有 1 个就单项),每项带推荐值和后果。若阻塞关键路径,也要合并成一次提问,不得逐条连环问。
+3. **NO_APPROVAL 无需批**:能实查的事实、已批准信封内的派生约束、文案/归档/status/证据整理、普通 P2、不改变外部语义的可逆实现细节。自主完成并说明,不把告知包装成审批。
+
+**人批预算** —— 默认每个工作包、每道 Gate 只有 1 个 `BATCH_AT_GATE` 请求;`STOP_NOW` 是越界例外。用户只回答一部分或要求解释时,保持同一决策包编号,补充说明并更新收件箱,不得包装成一轮新审批。只有当未决项真实阻塞关键路径时才回到同一包追问;否则继续范围内工作。
+
+**决策包口径** —— 验收清单先拆成「人必须取舍的独立决策变量」和「由已选变量/现有契约推导的约束」;只把前者送人批。用户分轮回答时,未收敛项留在看板决策收件箱;收敛后按决策包在 `pm/decisions.md` 记一次,不得为 `3/14 → 11/14 → 14/14` 之类部分进度制造三条永久拍板。
+
+## 3. 红线(每个会话受约束)
+
+1. **凭据不入 git、不出本机**:文档只标位置不写值;本地 .env 必须 gitignore + 600 权限;机器闸 = gitleaks pre-commit 默认装(`scripts/pre-commit.sh`),报警即拦。
+2. **不 `git add -A`**:只 stage 自己域的具体文件;同持多仓按仓分别提交。
+3. **不未授权部署**、不 force-push、不 `--amend`、不 `--no-verify`。
+4. **每次部署完必更对应仓 `CHANGELOG.md`**;长连接服务部署带优雅下线(<PreStop/drain 机制>)。
+5. **写者≠审者**:review-ready 的里程碑候选必过独立 reviewer;写者自发现问题先收敛,不把未稳定候选反复送审。同一 candidate 复用结论,P0/P1 默认合并修复后只做一次 closure。