bstack

注意

只有这个 SKILL.md 文件，没有其他 bstack 文件？那你安装的内容残缺且无法正常工作。 如果你运行了 npx skills add broomva/bstack，skills.sh 只复制了这个文件，并漏掉了 bin/、scripts/、schemas/ 和模板——这是 vercel-labs/skills#1523 中仓库根目录 SKILL.md 的问题。没有 bstack CLI、没有 bstack bootstrap，也没有 bstack doctor。 bstack 是 CLI + 治理基底，而不是技能。

修复——安装完整版本：

git clone https://github.com/broomva/bstack.git && cd bstack && ./bin/bstack bootstrap

只想获取供 Agent 使用的基础知识入门内容（不需要 CLI）？运行 npx skills add broomva/skills --skill bstack。

bstack — Broomva Stack

二十个不可再分的基础要素。三十个精选技能。一种规范运行模式。一个可自主运行的工作区。

bstack 是一个可移植的基础设施元层——它将现有技能组合为具有约束力的基础要素契约，由 Agent 通过推理来执行，由 doctor 通过检查来执行，由 bootstrap 通过搭建来执行，并由规范运行模式（broomva/autonomous）在执行过程中强制落实。

基底与模式

bstack 提供两个互补层：

• 基底（此技能，/bstack）：20 个基础要素 + 30 个技能 + 治理 + 钩子 + .control/policy.yaml。这是 /bstack bootstrap 安装的内容。基底是能力——即工作区中可用的内容。
• 模式（broomva/autonomous）：在基底之上运行的规范行为。当用户说“开始”/“继续”/“自主运行”时，/autonomous 会触发 20 个反射组成的流水线，依次使用每个基础要素。

安装基底但不安装模式 = 工作区有基础要素，却没有可启用它们的入口。调用模式却没有基底 = 一厢情愿。两者结合：/bstack bootstrap 安装基底，随后 /autonomous 成为实质性工作单元的常驻运行模式。

Bootstrap 本身分为两条流程——确定性的结构化搭建（基础层）加上由 Agent 编写的生成式定制流程（定制层）。请参阅双流程工作区设置：结构化 + 生成式。

快速入门

安装（bstack 是 CLI/基底——通过克隆 + bootstrap 安装，而不是运行 npx skills add；后者会根据 vercel-labs/skills#1523 漏掉 bin//scripts/）：

git clone https://github.com/broomva/bstack.git && cd bstack && ./bin/bstack bootstrap

然后，在 Agent 会话中：

/bstack bootstrap     → install 30 skills + scaffold governance + wire hooks + run doctor
/bstack doctor        → verify primitive contract compliance (always exits 0)
/bstack repair        → fix specific gaps surfaced by doctor (asks before writing)
/bstack status        → show which skills are installed vs missing
/bstack validate      → check skill SKILL.md frontmatter health
/bstack revamp        → full reconfiguration (force-reinstall + rewire + re-doctor)
/bstack wave dispatch <plan...>   → atomic parallel-agent dispatch from N plan files
/bstack wave status <wave-id>     → forensic per-wave state table
/bstack wave list                 → all waves with summary state
/bstack fleet up <roster>         → launch N coordinating peers into ONE worktree
/bstack fleet status [--fleet id] → per-peer liveness (pid-keyed) + suggestions
/bstack fleet list                → all fleets with counts by liveness class
/bstack fleet down --fleet <id>   → stop + remove a fleet's peers, reclaim state
/bstack bench run                 → two-phase skill-evolution benchmark (P11)
/bstack bench compare             → Phase 1 vs Phase 2 REPORT.md
/bstack bench tasks list          → registered task sets
/bstack bench run --runner live --provider databricks --model ...
                                  → real LLM via OpenAI-compatible provider (≥ 0.11.0)
/bstack workspace register        → add this workspace to ~/.broomva/global/registry.yaml (≥ 0.18.0)
/bstack workspace list            → list all registered workspaces (Federation, Phase 8)
/bstack workspace info            → is the current workspace registered?
/bstack workspace deregister      → remove a workspace by --name or --path
/bstack status --aggregate        → federation rollup: name × bstack_version × composite_ω × verdict
/bstack cross-review <pr> --repo <owner/name>
                                  → P20 cross-model adversarial review via remote
                                    git fetch (≥ 0.20.0, BRO-1227 Fix B)

bstack 强制落实的内容

二十个基础要素。每个要素都能针对一种特定的故障模式进行防护，避免其在无人监督的会话中导致混乱：

#	基元	解决的问题
P1	对话桥接	会话失忆
P2	控制门	模型未授权的破坏性操作
P3	线性工单	工作不可见
P4	PR 流水线	合并未经审查的代码
P5	并行 Agent	顺序执行瓶颈；无法寻址的会话在相同文件中发生冲突
P6	知识记账	知识图谱腐化
P7	技能新鲜度检查	npx skills add 快照悄然腐化
P8	分支 + Worktree 清理器	squash 合并累积
P9	CI 监视器 + 高效等待（broomva/p9 技能——名称与编号相符）	等待期间空耗时间（CI、部署、构建——PR CI 是参考实现）
P10	Worktree 卫生规范	PR 生命周期中的脏工作树漂移
P11	实证反馈循环	发布能编译却无法运行的代码
P12	持久循环规范（broomva/persist 技能）	上下文窗口逐渐腐化，导致长周期工作衰退
P13	梦境循环规范	跨层级整合在未经重放的情况下破坏高层规则（“影子梦境”故障模式）
P14	依赖链推理规范	“深入思考依赖链”沦为仪式性说法，没有具体列举上游/下游依赖
P15	行动前状态快照	基于过时或单会话状态制定计划（未提交的工作、进行中的 PR、过期的部署、其他会话的工作树）
P16	晶化规范（Bstack 引擎）	反复出现的有价值模式只存在于用户头脑中，从未提升为技能/基元/策略基础设施
P17	按视角路由的请求表述（计划中的 broomva/role-x 技能）	扁平分发式扇出未能加载领域上下文；Agent 未采用塑造正确 quality_bar 的类型化视角（法律审查与设计、研究不同）执行任务
P18	格式随受众而定规范	不论受众如何，所有内容默认使用 Markdown；没人阅读的长篇规范；当 SVG-HTML 才是正确基元时，使用 ASCII 伪图示 + Unicode 近似配色
P19	编排机制选择规范	反射间交接依赖隐式指令（“请继续”）；为任务形态选择错误机制（超过 1 小时的工作用 /goal，30 分钟任务用 persist，事件等待用 /loop）；因缺少机制而中断自主流程
P20	跨模型对抗式审查门（broomva/cross-review 技能）	同模型回音室；作者自行验证工作；没有不同评估者打出 ≥7/10，导致 AI 垃圾内容（过度工程化的抽象、模板粘贴、不必要的包装器）被合并

完整参考：参见 references/primitives.md。

基元操作化参考（由应用该基元的 Agent 按需加载）：

• 实证（P11）——dogfood 模式手册：references/dogfood-patterns.md。按技术栈分类的交互界面矩阵（Tauri+sidecar / Next.js / Expo RN / Rust CLI / REST API / MCP 服务）。列出技能工具包（视觉部署验证必须使用 Interceptor；gstack / cliclick / screencapture / curl+jq 按技术栈组合）、各技术栈的规范流程、注意事项、Dogfood Plan 合约和回执模板。bstack doctor §13 强制要求提供按技术栈标记的计划（达到三次规则前仅供参考）。

通往 v1.0.0 的路线图——从 v0.3.1 起的架构合约、差距目录和 9 阶段闭合计划，见 specs/2026-05-18-substrate-completion.md（规范版本）和 references/substrate-completion-overview.md（Agent 可读摘要）。此后每个 bstack 版本直至 v1.0.0 都会引用此规范，说明“完成的标准是什么”。

Agent 文案的命名规范（对每个 Agent 均具有约束力）

每个原语都带有一个用于 Agent 文本的短名称。在回复、PR 正文、提交消息、代码注释、知识图谱条目或任何面向人的内容中引用原语时，请使用 Name (Pn) 格式——例如 “应用 Snapshot (P15)”、“通过 Dep-Chain (P14)”、“运行 Bookkeeping (P6)”——不要只写 P15 / P14 / P6。数字是规范标识符（在重命名后仍保持稳定）；名称是便于人阅读的称呼。在回复中首次提及时使用完整格式；同一回复中后续提及可以省略编号，只写 Name（“Snapshot 显示状态干净”），但绝不能只写 Pn。锚点、章节 ID（#p15-state-snapshot-before-action）和原语数量标题（“二十个不可约原语”）仍使用数字，分别是为了保持 URL 稳定性和便于计数。失败模式：只写 Pn 会让回复读起来像一堆数字；跨会话读者若不查索引就无法解读引用。下面的短名称索引是查阅依据。

短名称索引（规范编号）：Bridge (P1) · Gate (P2) · Tickets (P3) · Pipeline (P4) · Fanout (P5) · Bookkeeping (P6) · Freshness (P7) · Janitor (P8) · Wait (P9) · Hygiene (P10) · Empirical (P11) · Persist (P12) · Dream (P13) · Dep-Chain (P14) · Snapshot (P15) · Crystallize (P16) · Lens (P17) · Audience (P18) · Orchestrate (P19) · Cross-Review (P20)。

规范说明位于工作区 CLAUDE.md 的 §Bstack Core Automation Primitives，以及工作区 AGENTS.md 第 93 行附近。本 SKILL.md 重申了此规则，以便在 /bstack 加载的入口处清晰可见。

技能名称 ↔ 原语编号对齐：当某项技能使用数字名称时（例如，Wait 对应 P9，其名称为 p9），原语编号意味着该名称将保持稳定——重命名会导致所有 npx skills add broomva/skills --skill p9 安装失效。使用功能名称的技能（bookkeeping = P6、persist = P12）按功能命名，而非按编号命名。（所有技能均供应自 broomva/skills monorepo；--skill <name> 参数是稳定标识符。）

bstack wave（本版本新增）。 补齐了 Orchestrate (P19) 机制立方体中 N>1 × 跨会话 × 外部触发这一格。若有 N 个独立的计划文件可并行运行，且不会对共享的可变文件进行写入（Fanout (P5)），请使用它。每个计划的 frontmatter 声明其 worktree 和 branch；包装器会原子地验证这些声明、创建 worktree，并为每个计划启动一个 claude --bg。状态保存在 ~/.cache/bstack/wave/<wave-id>/（Persist (P12) 的文件系统即状态模式）中。完整的原语合并映射请参阅工作区仓库中的设计文档 docs/superpowers/specs/2026-05-13-bstack-wave-design.md。从 0.39.1 起，每个计划的 peer 都通过 scripts/peer.py 启动：命名格式为 <worktree>-<ticket>-<slug>（Fanout P5），并使用 --strict-mcp-config 和 crossSessionInbound: accept，使其可无人值守运行；此外，它还会关联到 wave status 中的实时会话（LIVE 列依据真实的 claude agents --json --all 架构来匹配）。需要项目 MCP 服务的计划可在 wave: 下设置 mcp: inherit（或设置 BSTACK_PEER_MCP=inherit）；未知的 wave: 键会按名称拒绝。 bstack fleet（≥ 0.40.0）。 同一单元的另一半：根据成员列表，在一个工作树中协调 N 个同伴。**路由规则——根据工作树维度做决定，并说明你选择了哪个单元：**每个同伴都需要自己的分支和工作树 → bstack wave dispatch <plan...>；同伴在一个工作树中协调 → bstack fleet up <roster>；会话内彼此独立的子任务 → 在一条消息中调用 Fanout（P5）Agent。成员列表条目声明 slug、可选的 ticket/prompt/role/model/mcp，以及 owns（该同伴负责的路径 glob——它的工作区间，会引用到任务说明中）。该机制曾硬编码的本体现在作为配置声明，按以下优先级解析：CLI 标志 > BSTACK_FLEET_<KEY> > ~/.bstack/config.yaml 中的 fleet_<key> > 默认值：base、peer_contract、allowed_tools、state_dir、ticket_pattern、mcp。状态和每个同伴的任务说明存放在 ~/.cache/bstack/fleet/<fleet-id>/ 下；只要还有未回收的同伴，down 就不会删除 fleet 目录；如果无法读取 Agent 列表，status 会显示 unknown，而非显示正常。两个命令共用 scripts/peer.py——Fanout（P5）的命名语法（<worktree>-<ticket>-<slug>）、两个无人值守启动标志（--strict-mcp-config、--settings '{"crossSessionInbound":"accept"}'），以及以 PID 为键的存活状态。

规范运行模式：broomva/autonomous——当用户说“开始”/“继续”/“自主运行”/“自动合并”或发出任何不带具体说明的执行指令时，/autonomous 会触发包含 20 个反射步骤的流水线，按正确顺序调用上述每项原语。没有模式的底层能力处于休眠状态；没有底层能力的模式只是空想。两者结合，才能打造出可自主运行的工作区。

前言（每次会话先运行）

检测技能的安装状态，更新已过期的技能，并检查是否需要首次设置。

# ─── Update check ────────────────────────────────────────────
_BSTACK_ROOT=""
[ -d "$HOME/.claude/skills/bstack" ] && _BSTACK_ROOT="$HOME/.claude/skills/bstack"
[ -z "$_BSTACK_ROOT" ] && [ -d "$HOME/.agents/skills/bstack" ] && _BSTACK_ROOT="$HOME/.agents/skills/bstack"
_UPD=""
if [ -n "$_BSTACK_ROOT" ] && [ -x "$_BSTACK_ROOT/bin/bstack-update-check" ]; then
  _UPD=$("$_BSTACK_ROOT/bin/bstack-update-check" 2>/dev/null || true)
fi
[ -n "$_UPD" ] && echo "$_UPD" || true
_BRANCH=$(git branch --show-current 2>/dev/null || echo "unknown")
echo "BRANCH: $_BRANCH"

# ─── First-time setup check ──────────────────────────────────
# If the init marker is missing, bstack hasn't been onboarded on this
# machine. Recommend the wizard. In Claude Code, the agent should follow
# the `## Onboarding` section below to ask the user the 4 wizard
# questions interactively via the AskUserQuestion tool.
_BSTACK_MARKER="${BROOMVA_STATE_DIR:-$HOME/.config/broomva/bstack}/initialized"
if [ ! -f "$_BSTACK_MARKER" ]; then
  echo "ONBOARDING: bstack not yet initialized on this machine."
  echo "  → In Claude Code: agent will guide you (see ## Onboarding section)."
  echo "  → In a shell: run \`bash $_BSTACK_ROOT/scripts/onboard.sh\`"
fi

如果输出显示 UPGRADE_AVAILABLE <old> <new>：读取 bstack-upgrade/SKILL.md 并遵循其中的内联升级流程。如果显示 JUST_UPGRADED <from> <to>：告诉用户“正在运行 bstack v{to}”并继续。

如果前言输出 ONBOARDING: bstack not yet initialized：在运行任何其他 bstack 命令之前，跳转到下方的 ## Onboarding 部分。新用户将体验引导式的 4 个问题向导；标记文件存在后，回访用户会自动跳过此步骤。

# ─── Skill roster check ──────────────────────────────────────
AGENTS_DIR="${HOME}/.agents/skills"
CLAUDE_DIR="${HOME}/.claude/skills"
ROSTER=(autonomous cross-review agentic-control-kernel control-metalayer-loop harness-engineering-playbook p9 agent-consciousness knowledge-graph-memory prompt-library symphony symphony-forge autoany deep-dive-research-orchestrator skills skills-showcase arcan-glass next-forge alkosto-wait-optimizer content-creation finance-substrate seo-llmeo brand-icons pre-mortem braindump morning-briefing drift-check strategy-critique stakeholder-update decision-log weekly-review role-x)
INSTALLED=0; MISSING=()
for s in "${ROSTER[@]}"; do
  if [ -d "$AGENTS_DIR/$s" ] || [ -d "$CLAUDE_DIR/$s" ]; then
    INSTALLED=$((INSTALLED + 1))
  else
    MISSING+=("$s")
  fi
done
echo "bstack: $INSTALLED/${#ROSTER[@]} skills installed (30 total)"
[ ${#MISSING[@]} -gt 0 ] && echo "Missing: ${MISSING[*]}"

报告数量。如果 30 项均已就绪，请说“bstack 已完整安装”。如果有缺失项，请列出并提供 bootstrap 命令。

技能检查完成后，运行框架验证：

cd ~/broomva && make bstack-check 2>&1

报告结果。如果任何检查失败，请先修复再继续。

入门（首次设置向导）

当前言报告 ONBOARDING: bstack not yet initialized 时，运行引导式向导。共有两种方式——使用相同的底层脚本（scripts/onboard.sh），但由不同的驱动程序运行。

路径 A：在 Claude Code 中（通过 AskUserQuestion 由 Agent 驱动）

在 Claude Code 会话中，Agent 会通过 AskUserQuestion 调用收集 4 项向导输入（用户在聊天中作答），然后使用收集到的标志调用 scripts/onboard.sh。用户的终端中不会出现 read -r 提示——Agent 就是输入机制。

4 个问题（向用户显示的默认值）：

1. 工作区路径 — $HOME/broomva（默认值）。bstack 在此处生成治理文件。
2. 配置文件 — personal / enterprise / autonomous-strict。决定门禁的严格程度：
   • personal — 宽松；适合独立开发 / 实验
   • enterprise — 严格，便于审计
   • autonomous-strict — 遵循 gates-are-trust 原则；L3 自动合并已启用（要求 CI 中包含 G-L3-* 门禁）
3. Life Agent OS 集成 — install / skip。是否同时安装 life-os + arcan 二进制文件。
4. 治理路径的自动合并策略 — human-required / trust-gates：
   • human-required — 在将 G-L3-1/G-L3-2 接入 CI 之前采用的安全默认值
   • trust-gates — L3 信任门禁通过时，L3 路径自动合并

收集完四个答案后，Agent 会调用：

bash "$_BSTACK_ROOT/scripts/onboard.sh" \
  --workspace="$A1" \
  --profile="$A2" \
  --life="$A3" \
  --auto-merge="$A4" \
  --skip-prompts

该脚本通过 bin/bstack-config 将选项保存到 ~/.bstack/config.yaml，针对所选工作区运行 scripts/bootstrap.sh，并在 ~/.config/broomva/bstack/initialized 写入初始化标记。随后，Agent 会向用户报告引导回执（工作区 + 配置文件 + Life + 自动合并 + 引导状态），并建议下一步执行 /autonomous。

如果 AskUserQuestion 不可用（在 Claude Code 之外运行）：转到路径 B。

路径 B：在 shell 中（交互式 read -r 提示）

bash $_BSTACK_ROOT/scripts/onboard.sh

该脚本通过 read -r 提示相同的 4 个问题。后续效果相同：配置已保存、引导已运行、标记已写入。

幂等性 + 重新运行

• 一旦 ~/.config/broomva/bstack/initialized 存在，后续调用 onboard.sh 会立即以状态码 0 退出（不显示提示，也不运行引导）。
• 使用 --force 重新运行向导。
• 使用 --dry-run 可预览选项而不保存。

回执结构（标记文件）

初始化标记是位于 ~/.config/broomva/bstack/initialized 的 YAML 风格扁平文件：

# bstack initialization marker
onboarded_at: 2026-05-12T22:49:44Z
workspace: /Users/foo/broomva
profile: personal
life: skip
auto_merge: human-required
bstack_repo: /Users/foo/.agents/skills/bstack
bootstrap_status: ok           # ok | failed | skipped

后续会话会检查此文件以获取状态。bootstrap_status: failed 会如实记录——用户会知道引导需要后续处理，同时向导答案也不会丢失。

命令

bootstrap — 完整安装与系统接线

scripts/bootstrap.sh 是安装与接线流程。它会：

1. 委托 bin/bstack-skills install 安装配套技能清单（读取 references/companion-skills.yaml，并将每项安装为 npx skills add broomva/skills --skill <name>）——autonomous 是规范的运行模式
2. 从 assets/templates/ 为缺失的治理文件搭建脚手架：
   • CLAUDE.md（工作区不变量 + RCS 层级 + 原语表 P1–P20 + §仪式与实质）
   • AGENTS.md（操作规则 + 各原语对应章节 + 所有推理强制原语的反身触发器）
   • .control/policy.yaml（ci_watch / ci_heal / auto_merge / gates G1–G11）
   • .claude/settings.json（P1、P2、P7 钩子接线）
3. 向现有 Makefile 添加 make 目标（或创建一个）：bstack-check、control-audit、janitor、bstack-primitive-lint（G-L3-1）、bstack-rule-of-three（G-L3-2）、bstack-l3-trust（组合 L3 门禁）
4. 通过 git config core.hooksPath .githooks 安装 pre-commit 钩子（.githooks/pre-commit）
5. 运行 bstack doctor，验证原语契约合规性；并运行 make bstack-l3-trust，验证 L3 门禁通过
6. 提供 bootstrap 回执——报告安装了什么、搭建了什么脚手架，以及哪些内容已存在
7. 建议用户下一项实质性工作单元调用 /autonomous——基础环境已安装；规范模式已准备就绪，可以启用

幂等：绝不覆盖现有的用户自定义内容。如果文件已存在，bootstrap 只会追加缺失的原语章节、区块或钩子，绝不会替换整个文件。

自我应用：在现有工作区中调用 /bstack bootstrap 时，bootstrap 本身会遵循 /autonomous 纪律运行——状态快照、依赖链追踪、验证计划、PR 流水线。安装这套纪律的 bootstrap，本身也践行它所交付的契约。

双流程：bootstrap 并非单次确定性执行。上文的结构化脚手架是基础；随后 Agent 会在其上运行生成式定制流程。完整模型和规范顺序请参阅下文的双流程工作区设置。

双流工作区设置（结构化 + 生成式）

bstack bootstrap 是一个双流操作，而非单次确定性流程。这与 bstack 已在文档中采用的受众（P18）划分一致：确定性的 B 类投影底线，加上具备上下文感知能力的 C 类定制编写层；现在，这一划分也应用于工作区设置本身。

bstack bootstrap  =  STRUCTURED flow      →   GENERATIVE flow            →   VERIFY
                     (deterministic, no LLM)    (agent-authored, contextual)   (deterministic)
                     scripts + templates        tailoring of THIS workspace    bstack doctor
                     + shipped+deployed hooks
                     + gates + .control

1. 结构化流程（底线——可复现，不使用大模型）。 bstack bootstrap 运行幂等脚手架：安装技能；基于 assets/templates/* 搭建治理文件（CLAUDE.md、AGENTS.md、METALAYER.md、.control/policy.yaml、.control/arcs.yaml、.control/rcs-parameters.toml、schemas/）；部署钩子脚本到工作区（control-gate / skill-freshness / conversation-bridge——自 0.37.2 起包含 P6 目录刷新功能——以及 L0/L1 审计钩子）；配置 .claude/settings.json；安装 L3 速率门控 + CI 门控。此流程必须完整且正确——每个已接入的钩子都必须有对应脚本已部署（不得留下悬空引用）。这是无损基线：相同输入 → 每次都得到相同工作区。

2. 生成式流程（定制层——由 Agent 编写，尽可能完善）。 完成结构化脚手架后，Agent 会进行模板无法实现的上下文感知处理。具体而言，Agent 会：

a. 检测技术栈 + 项目意图——依据包括：语言/构建文件、现有代码、README、用户陈述的目标。 b. 针对本项目调整已搭建的治理说明——将通用的 CLAUDE.md / AGENTS.md 占位内容改写为项目专属的不变约束、惯例和架构说明（而非通用模板文本）。 c. 编写项目专属的 CI 工作流——结构化流程会提供 L3 稳定性门控；Agent 则根据检测到的技术栈生成匹配的测试/代码检查/构建任务。 d. 填写 Dogfood Plan（实证，P11），加入与本项目技术栈对应的真实入口界面 + 证据锚点（参见 references/dogfood-patterns.md）。 e. 对于 RCS/RSI 或控制系统代码库——可选地搭建可运行的 L0–L3 基础层 + HIERARCHY/实例化映射，使工作区不仅能描述控制系统，还能运行控制系统。普通代码库跳过此步骤。 f. 为新工作区主动登记初始知识图谱实体 / 决策日志（簿记，P6），绝不征求许可。

3. 验证（确定性）。 bstack doctor 会检查两种流程：结构化契约（治理文件、已接入且已部署的钩子、门控、架构）以及生成式输出（如果 Agent 的定制遗漏了内容，doctor 会指出差距）。生成式输出始终由结构化契约检查，绝不盲目信任。

关键原则：

• 这与既定的受众（P18）规范一致：结构化流程是 B 类投影底线（确定性、无损、可复现）；生成式流程是 C 类定制编写（具备上下文感知能力，尽可能完善）。bstack 已在文档中采用的结构化与生成式划分，现在也应用于工作区设置。
• 结构化流程绝不能接入尚未部署脚本的钩子——本次工作要修复的正是悬空钩子故障模式。禁止“已接入但悬空”：每个钩子引用都必须指向真实、可执行且已部署的脚本。
• Agent 必须先运行结构化流程（幂等底线），再运行生成式流程（定制），最后运行 doctor（验证）。绝不能只运行生成式流程而不运行结构化流程（没有底线），也不能只运行结构化流程而不运行生成式流程（工作区通用且未经定制）。

doctor — 验证原语契约

scripts/doctor.sh。包含八个检查部分：

1. 治理文件存在（CLAUDE.md、AGENTS.md、.control/policy.yaml）
2. CLAUDE.md 原语表包含全部 P1–P20 行，以及正确的计数标题（"Twenty irreducible…"）
3. AGENTS.md 包含每个原语部分（格式为 ### P1: 或 ### P1 — Short: Long，一直到 ### P20）
4. P6、P9、P10、P11、P12、P13、P14、P15、P16、P17、P18、P19、P20（由推理强制执行的原语）包含 Reflexive Trigger Rules
5. .control/policy.yaml 包含必需的区块（ci_watch:、ci_heal:、auto_merge:）
6. .claude/settings.json 配置了预期的钩子脚本（P1、P2、P7）
7. 每个原语的机制在磁盘上都可访问
8. L3 信任门检查通过——如果存在 make bstack-l3-trust 目标，则运行该目标；报告 G-L3-1 和 G-L3-2 的结果；将任何结构性违规或 rule-of-three 违规列为差距

运行模式：默认模式（完整报告）、--quiet（仅显示差距）、--strict（存在差距时退出码为 1，供 CI 通道使用）。**默认情况下始终以退出码 0 退出。**每项差距都包含可执行的 → fix: 提示。

bootstrap 会在最后一步自动调用 doctor --quiet。L3 信任门检查（检查 8）是新模式反合理化层的基底层等效机制——二者都用于弥补治理持续演进、却没有机器可检查证据支撑的失效模式。

repair — 应用针对性修复

scripts/repair.sh。读取 doctor 的差距列表，逐项询问用户是否修复，然后应用相应修复（根据模板添加缺失的原语部分、添加缺失的策略区块、配置缺失的钩子）。可重复执行，结果一致。绝不执行破坏性操作。

status — 已安装与缺失状态 + 脚手架健康状况

重新运行前置步骤。对每项技能显示：名称、层级、已安装/缺失。然后运行 make bstack-check 并报告脚手架健康状况。

validate — 技能 frontmatter 健康状况

scripts/validate.sh。验证每项技能是否具有有效的 SKILL.md 和正确的 frontmatter。然后运行完整的 bstack-check 脚手架验证。

revamp — 完整的 Agent 重新配置

scripts/revamp.sh。触发完整的工作区重新配置：

1. 重新安装全部 30 项技能（强制模式）
2. 根据模板重新生成治理文件（覆盖前会询问）
3. 重新配置钩子（git pre-commit + Claude Code Stop/Notification/PreToolUse/SessionStart）
4. 强制在所有项目中运行对话桥接
5. 运行完整的控制审计
6. 使用当前状态更新 AGENTS.md

workspace — 多工作区联邦注册表（≥ 0.18.0，Phase 8）

bin/bstack-workspace + scripts/workspace.py。维护主机级工作区清单，路径为 ~/.broomva/global/registry.yaml，记录这台机器上由 bstack 治理的工作区。 联邦功能为选择启用且只读——每个工作区仍以自身状态作为事实来源。 该注册表是索引，bstack status --aggregate 会遍历此索引以汇总复合 ω 健康状况。

bstack workspace register             # registers $PWD (name = basename)
bstack workspace register --path ~/projects/foo --tag client-x
bstack workspace list --json          # machine-readable for scripts
bstack workspace info                 # is this workspace registered?
bstack workspace deregister --name foo

退出码：0 正常，2 参数无效，3 架构/解析错误，4 未找到目标，5 不同路径处存在名称冲突。SLO：注册/列出操作的 p50 < 100ms。

联邦功能不是新的原语——没有 P21。它组合了现有原语：Snapshot（P15）生成各工作区的审计信号；v0.16.0 §19 中的多层复合 ω 提供各工作区的判定结果。Doctor §20 会显示注册表健康状况（仅供参考，除非注册表文件的 schema_version != 1）。

Stack 层（30 项技能）

完整技能清单及说明见 references/skills-roster.md。分层架构见 references/stack-architecture.md。包含反身触发条件的完整原语契约见 references/primitives.md。

Metalayer 集成

bstack 是 agentic-control-kernel 的测量基底。该测试框架会记录：

指标	目标	方式
已安装的技能	28/28	前言清单
治理文件	4/4	CLAUDE.md、AGENTS.md、METALAYER.md、.control/policy.yaml
已接入的钩子	4/4	Stop、PreToolUse safety、PreToolUse regression、pre-commit
状态行	active	~/.claude/statusline-command.sh
Bridge 运行状态	最新记录 < 24 h	~/.cache/broomva-bridge-stamp mtime
控制审计	5/5 个部分	make control-audit 退出代码
已编入索引的对话	≥1 个会话	docs/conversations/Conversations.md 存在
原语契约	20/20	bstack doctor 退出代码

何时使用 bstack

• 使用 Broomva 约定设置新项目 → bootstrap
• 验证现有项目是否满足原语契约 → doctor
• 修复 doctor 报告的特定缺口 → repair
• 检查技能是否最新或清单是否完整 → status 或 validate
• 大规模清理工作区 → revamp

将提示词作为共享知识界面

bstack 将 broomva.tech 提示词库视为跨 Agent 的共享知识界面，而非私有仓库。每个 bstack 工作区都能从中获得两项内容：

1. 可复用指令 — 经过版本管理、可参数化的提示词（code-review-agent、deep-research-agent、ai-native-platform-architect、bstack-control-harness-bootstrap 等），任何 Agent 都可以获取并应用。
2. 评估引擎 — 每次获取和完成操作都会向 prompt_invocation 写入一条类型化记录。来源归因（web|cli|skill|api）、延迟、令牌、成本和明确的用户反馈都会流入位于 broomva.tech/api/metrics/* 的评估界面。

反身规则（强制）

当用户要求使用一种已知模式（代码审查、深度研究、平台重设计、测试框架引导等），且该模式存在于库中时，应优先使用它，而不是从头编写。以下五步要求不可妥协：

# 1. Tag the session
export BROOMVA_SOURCE=skill

# 2. Pull — captures invocation_id on stderr
broomva prompts pull <slug> --json 2>&1 | tee /tmp/broomva-last.json

# 3. Use the prompt body as instructions for the work

# 4. MANDATORY after completing the work
broomva prompts complete <invocation_id> \
  --status completed --model <name> \
  --latency-ms <ms> --tokens-in <n> --tokens-out <m>

# 5. Optional — capture explicit user feedback
broomva prompts feedback <invocation_id> --slug <slug> --signal up --text "..."

跳过第 4 步会使记录停留在 pulled 状态，评估引擎也无法从你的运行中学习。24 h 清理程序最终会将其改为 abandoned——这是质量信号，并非有用的运行结果。

发现

broomva prompts list --metrics --sort skill_invokes   # most-invoked first
broomva prompts list --category agent-instructions    # filtered
broomva prompts get <slug> --raw                      # body only

与原语契约的组合

• P1 在对话日志中记录调用 ID——从会话回指评估引擎。
• P4 将 PR 审查提示词调用与合并结果关联起来——按提示词版本衡量通过率。
• P6 将值得综合整理的提示词提升为 research/entities/ 中的实体页面（库是运行时注册表；知识图谱是其结晶形式）。
• P11 使用真实的 tokens_in/out、latency_ms、error_message 完成调用，与 P11 的原则相同：用可衡量的结果进行验证。
• P13 评估引擎不断演进的排名是梦境层级的基底；每次运行的遥测数据则是密集的低层级信号。

完整集成指南包含发现模式、陷阱和各原语的组合方式：references/prompts-integration.md。

自我演进

当 Agent 改进某个原语时，工作流如下：

1. 在多个会话中观察到模式（L3 稳定性预算；快速变化会使系统不稳定）
2. 记录在对话日志中（Stop 钩子——通过 P1 自动完成）
3. 在 AGENTS.md 中结晶固化（一个 PR，有意为之）
4. 如果可通过机械方式设为门禁，则在 .control/policy.yaml 中强制执行（一个 PR，有意为之）
5. 扩展 Doctor 以检查新规则（一个 PR，有意为之）
6. 后续 Agent 继承这项改进

这是 RCS 层级中 L3 的 f₃ 动力学函数。有关正式的稳定性约束，请参阅 references/primitives.md。

另请参阅

• references/primitives.md — 包含反身触发条件的完整 P1–P20 参考
• references/prompts-integration.md — 何时以及如何利用 broomva.tech 提示词库（5 步自动追踪要求、发现流程、常见陷阱）
• references/skills-roster.md — 全部 30 个技能及其安装命令
• references/stack-architecture.md — 层级依赖关系图
• references/quickstart.md — 5 分钟安装指南
• bstack-upgrade/SKILL.md — 版本升级流程