@zigrivers/scaffold 3.27.0 → 3.29.0

package/content/knowledge/web3/web3-conventions.md

@@ -2,6 +2,12 @@
 name: web3-conventions
 description: Solidity style and convention discipline for smart-contract teams — forge fmt as single formatter, NatSpec on public functions, pinned pragma, custom errors over string reverts, naming and ordering rules
 topics: [web3, conventions, solidity, forge-fmt, natspec]
+volatility: stable
+last-reviewed: null
+version-pin: 'Solidity 0.8.x'
+sources:
+  - url: https://ethereum.org/en/developers/docs/smart-contracts/languages/
+  - url: https://consensys.github.io/smart-contract-best-practices/
 ---
 
 Solidity is brittle. The compiler is fast and unforgiving, the gas model rewards terseness, and the deployment surface is immutable — every style drift you tolerate during development eventually becomes a bytecode-determinism question, an audit comment, or a bug nobody can patch. The conventions below are the ones enforced by `forge fmt` and code review at every serious shop; encode them as CI gates and they stop being judgment calls.

package/content/knowledge/web3/web3-deployment-and-verification.md

@@ -2,6 +2,13 @@
 name: web3-deployment-and-verification
 description: Deploying smart contracts with forge script — broadcast artifacts as provenance, Etherscan verification, multi-chain flows, testnet rehearsals, mainnet pre-flight, post-deploy role hardening, and CREATE2 deterministic deploys
 topics: [web3, deployment, verification, forge-script, etherscan]
+volatility: evolving
+last-reviewed: null
+version-pin: null
+sources:
+  - url: https://ethereum.org/en/developers/docs/smart-contracts/deploying/
+  - url: https://docs.openzeppelin.com/contracts/5.x/
+  - url: https://docs.safe.global/
 ---
 
 Shipping a contract to mainnet is the most irreversible thing a smart-contract team ever does. There is no rollback, no patch deploy, no `kubectl rollout undo` — once the bytecode is live and users start interacting with it, you live with what you wrote. The instinct from web2 — "deploy fast, fix forward" — produces drained protocols on-chain. Treat deployment as a release event: every privileged operation scripted (not hand-called), every artifact archived (not transient), every step rehearsed on a testnet that mirrors mainnet, and every contract verified on Etherscan before you tell anyone the address. The cost of the discipline is half a day of process; the cost of skipping it is the entire protocol.

package/content/knowledge/web3/web3-dev-environment.md

@@ -2,6 +2,12 @@
 name: web3-dev-environment
 description: Reproducible local Foundry environment for smart-contract teams — pinned solc, pinned forge, anvil, forge-std, direnv, and CI parity
 topics: [web3, dev-environment, foundry, forge, anvil]
+volatility: evolving
+last-reviewed: null
+version-pin: 'Solidity 0.8.x'
+sources:
+  - url: https://ethereum.org/en/developers/docs/programming-languages/
+  - url: https://docs.openzeppelin.com/contracts/5.x/
 ---
 
 A reproducible Foundry environment is what lets every developer (and CI) get the same compile output, the same gas snapshots, and the same fork-test results. The pieces are not exotic: install Foundry through the official channel, pin the toolchain and the Solidity compiler, lean on `forge-std` for tests, push secrets out of your global shell with `direnv`, and mirror the same versions in CI. Skip any one of these and "works on my machine" creeps back in — usually as a gas-snapshot diff that nobody can reproduce.

package/content/knowledge/web3/web3-gas-optimization.md

@@ -2,6 +2,13 @@
 name: web3-gas-optimization
 description: Practical EVM gas optimization — measure first with forge snapshot, storage packing, unchecked loops, calldata vs memory, immutable, external-call discipline, and CI regression checks
 topics: [web3, gas-optimization, solidity, foundry]
+volatility: evolving
+last-reviewed: null
+version-pin: 'Solidity 0.8.x'
+sources:
+  - url: https://ethereum.org/en/developers/docs/gas/
+  - url: https://ethereum.org/en/developers/docs/evm/opcodes/
+  - url: https://consensys.github.io/smart-contract-best-practices/
 ---
 
 Gas matters because every operation a user pays for on Ethereum mainnet is real dollars, and on L2s the calldata you post to L1 is the dominant cost driver — both directions are visible in your users' wallets. But most "optimizations" save under 1% of a transaction's gas and cost clarity in exchange; that trade is rarely worth it. The point of this doc is to give you the small set of techniques that do pay for themselves, the discipline to measure before applying them, and the CI plumbing that catches regressions before they ship. If a section here ever recommends a change that obscures the code without producing a measurable saving, ignore it.

package/content/knowledge/web3/web3-oracles-and-external-data.md

@@ -2,6 +2,13 @@
 name: web3-oracles-and-external-data
 description: Oracle discipline for smart contracts — Chainlink price feeds with staleness/decimals/sign checks, TWAP for DEX prices, VRF for randomness, and fallback patterns that fail safe
 topics: [web3, oracles, chainlink, security]
+volatility: evolving
+last-reviewed: null
+version-pin: null
+sources:
+  - url: https://consensys.github.io/smart-contract-best-practices/
+  - url: https://swcregistry.io/
+  - url: https://ethereum.org/en/developers/docs/oracles/
 ---
 
 A smart contract is a deterministic state machine in a closed universe. The real world — ETH/USD, the weather in Lagos, the winner of last night's match, a genuinely random number — is none of those things. Oracles are the bridge between the two, and every bridge is a new attack surface with its own trust assumptions, latency, and failure modes. The job is not to remove the trust assumption (you cannot) but to make the bridge robust enough that an exploit costs more than the protocol holds. Most "oracle hacks" are not novel cryptography either — they are missed standard patterns: an unchecked staleness, a spot price used where a TWAP belonged, a `block.timestamp` standing in for entropy.

package/content/knowledge/web3/web3-project-structure.md

@@ -2,6 +2,12 @@
 name: web3-project-structure
 description: Opinionated Foundry project layout for smart-contract teams — src, test, script, lib, broadcast, foundry.toml, remappings — covering test naming, deploy provenance, and what belongs in git
 topics: [web3, project-structure, foundry, solidity]
+volatility: stable
+last-reviewed: null
+version-pin: null
+sources:
+  - url: https://ethereum.org/en/developers/docs/smart-contracts/
+  - url: https://docs.openzeppelin.com/contracts/5.x/
 ---
 
 A smart-contract repository is read by more adversarial eyes than almost any other kind of codebase: auditors, MEV searchers, frontrunners, and the occasional regulator. Structure carries weight that goes beyond developer ergonomics. An auditor opening the repo for the first time should be able to find the contract under review, its tests, its deploy script, and its on-chain deployment receipts within thirty seconds. Gas snapshots and fuzz seeds need a fixed home so regressions are diffable. Broadcast logs are the audit trail tying a verified contract address back to a commit SHA — losing or muddling them turns "which version is mainnet running?" into a forensic exercise. Foundry's conventions answer most of these questions; this doc records the opinionated version a team should adopt before the first PR lands.

package/content/knowledge/web3/web3-requirements.md

@@ -2,6 +2,12 @@
 name: web3-requirements
 description: Problem framing, invariants, threat model, trust assumptions, and success metrics for shipping smart contracts and protocols to EVM chains
 topics: [web3, requirements, invariants, threat-model, security]
+volatility: stable
+last-reviewed: null
+version-pin: null
+sources:
+  - url: https://consensys.github.io/smart-contract-best-practices/
+  - url: https://ethereum.org/en/developers/docs/smart-contracts/security/
 ---
 
 A smart contract shipped to an EVM chain without a written invariant set, a threat model, and an explicit list of trust assumptions is a guessing game with adversarial counterparties and irreversible state. This document defines the acceptance spec for a contract or protocol going to Ethereum mainnet, an L2 (Optimism, Arbitrum, Base), or a compatible sidechain. The audience is a senior Solidity engineer or protocol architect who can ship code but has not yet hardened it against funded adversaries. The goal is to force, in writing, the questions an auditor will ask on day one.

package/content/knowledge/web3/web3-security.md

@@ -2,6 +2,14 @@
 name: web3-security
 description: Layered security practices for smart contracts heading to mainnet — defense-in-depth, Checks-Effects-Interactions, pull payments, OpenZeppelin primitives, pause + multisig, and input validation discipline
 topics: [web3, security, solidity, openzeppelin, defense-in-depth]
+volatility: fast-moving
+last-reviewed: null
+version-pin: 'OpenZeppelin Contracts 5.x'
+sources:
+  - url: https://docs.openzeppelin.com/contracts/5.x/
+    anchor: '#security'
+  - url: https://consensys.github.io/smart-contract-best-practices/
+    anchor: '#general-philosophy'
 ---
 
 A smart contract is a public, immutable bank vault that anyone on the planet can call. The mempool is hostile, the bytecode is permanent, and the only patch deployment is a redeploy + migration that your users may or may not follow. Most exploits aren't novel cryptography — they're missed standard patterns: a state update after an external call, a `tx.origin` check that a phishing contract bypassed, a `transfer` to a contract that reverts and bricks an auction. Layered defense beats clever one-off mitigations, every time.

package/content/knowledge/web3/web3-testing.md

@@ -2,6 +2,12 @@
 name: web3-testing
 description: Testing discipline for Foundry smart contracts — unit, fuzz, invariant, and fork tests with coverage and gas snapshots wired into CI
 topics: [web3, testing, foundry, fuzz, invariants, fork-tests]
+volatility: evolving
+last-reviewed: null
+version-pin: null
+sources:
+  - url: https://consensys.github.io/smart-contract-best-practices/
+  - url: https://ethereum.org/en/developers/docs/smart-contracts/testing/
 ---
 
 Smart contracts must work the first time. Once deployed, a bug is a bounty for the next adversary who reads your storage layout, and "we'll patch it next sprint" is not an option when the only patch path is a migration to a brand-new address. Foundry's `forge test` runner makes property-level confidence cheap: unit tests pin known behavior, fuzz tests stress the boundaries you forgot, invariants assert the laws that must hold across every state sequence, and fork tests replay against real mainnet state. Use all four — none of them substitutes for any of the others.

package/content/knowledge/web3/web3-upgradeability.md

@@ -2,6 +2,13 @@
 name: web3-upgradeability
 description: Upgradeable contracts — when not to upgrade, UUPS vs Transparent vs Beacon, OpenZeppelin Upgrades with the Foundry plugin, storage gaps, ERC-7201, initializers, timelocked authorization
 topics: [web3, upgradeability, proxy, openzeppelin, storage]
+volatility: evolving
+last-reviewed: null
+version-pin: 'OpenZeppelin Contracts Upgradeable 5.x'
+sources:
+  - url: https://docs.openzeppelin.com/contracts/5.x/upgradeable
+  - url: https://docs.openzeppelin.com/contracts/5.x/api/proxy
+  - url: https://docs.safe.global/
 ---
 
 Upgradeable contracts trade simplicity for the ability to fix bugs after deployment. The cost is real: a new threat surface (the upgrade key itself), a class of storage-layout bugs that do not exist in immutable contracts, and a permanent dependency on whoever holds upgrade rights. An "upgradeable" protocol is one whose trust assumptions include a future action by an admin — every user of the protocol is implicitly trusting that admin to behave, in perpetuity. The honest default for most protocols is: do not upgrade unless you have to.

package/content/pipeline/build/multi-agent-resume.md

@@ -9,7 +9,7 @@ outputs: []
 conditional: null
 stateless: true
 category: pipeline
-knowledge-base: [tdd-execution-loop, task-claiming-strategy, worktree-management]
+knowledge-base: [tdd-execution-loop, task-claiming-strategy, worktree-management, multi-agent-coordination]
 reads: [coding-standards, tdd, git-workflow]
 argument-hint: "<agent-name>"
 ---
@@ -85,7 +85,7 @@ Before doing anything else, confirm the environment:
    - If NOT in a worktree, stop and instruct the user to set one up or navigate to the correct directory
 
 2. **Beads identity** (if `.beads/` exists)
-   - `echo $BD_ACTOR` — should show `$ARGUMENTS`
+   - `echo $BEADS_ACTOR` — should show `$ARGUMENTS`
    - If not set, the worktree setup may be incomplete
 
 ### State Recovery
@@ -114,14 +114,14 @@ Recover your context by checking the current state of work:
 ### Beads Recovery
 
 **If Beads is configured** (`.beads/` exists):
-- `bd list --actor $ARGUMENTS` — check for tasks with `in_progress` status owned by this agent
-- If a PR shows as merged, close the corresponding task: `bd close <id> && bd sync`
+- `bd list --assignee $ARGUMENTS` — check for tasks with `in_progress` status owned by this agent
+- If a PR shows as merged, close the corresponding task: `bd close <id>`
 - If there is in-progress work, finish it (see "Resume In-Progress Work" below)
 - Otherwise, clean up and start fresh:
   - `git fetch origin --prune && git clean -fd`
   - Run the install command from CLAUDE.md Key Commands
-  - `bd ready` to find the next available task
-- Continue working until `bd ready` shows no available tasks
+  - Atomically claim the next ready task: `TASK=$(bd ready --claim --json | jq -r '.id')` (sets `assignee=$BEADS_ACTOR` + `status=in_progress`; no race window between agents).
+- Continue working until `bd ready --claim --json` returns no task.
 
 **Without Beads:**
 - Read `docs/implementation-playbook.md` as the primary task reference.
@@ -171,8 +171,28 @@ Once in-progress work is complete (or if there was none):
    - Fix any findings at or above `fix_threshold` before proceeding
 
 3. **Create PR** (if not already created for in-progress work)
+   - If Beads is configured, run the PR-readiness checklist first:
+     ```bash
+     if [ -d .beads ]; then
+       bd preflight
+     fi
+     ```
+     Fix any issues `bd preflight` flags before proceeding.
+   - **For 3+ parallel agents**, acquire the project's merge slot to serialize merge-time conflicts:
+     ```bash
+     if [ -d .beads ]; then
+       bd merge-slot acquire --wait    # blocks if held; queues you in priority order
+     fi
+     ```
+     There is one merge slot per project; `--wait` blocks until you have it. Skip for single-agent or two-agent runs. See `content/knowledge/execution/multi-agent-coordination.md`.
    - Push the branch: `git push -u origin HEAD`
    - Create a pull request: `gh pr create`
+   - After the PR merges (or if you abandon the work), release the slot:
+     ```bash
+     if [ -d .beads ]; then
+       bd merge-slot release   # holder verified via $BEADS_ACTOR
+     fi
+     ```
    - Include agent name in PR description for traceability
 
 4. **Run code reviews (MANDATORY)**
@@ -219,7 +239,7 @@ Once in-progress work is complete (or if there was none):
 - Push updates and re-request review
 
 **Task was completed by another agent:**
-- If Beads: `bd sync` will show updated task states
+- If Beads: A `git pull` (and `bd dolt pull` if a Dolt remote is configured) brings the local DB current; run `bd doctor --fix` if anything looks stale.
 - Without Beads: check the plan/playbook for recently completed tasks and open PRs
 - Skip to the next available task
 

package/content/pipeline/build/multi-agent-start.md

@@ -9,7 +9,7 @@ outputs: []
 conditional: null
 stateless: true
 category: pipeline
-knowledge-base: [tdd-execution-loop, task-claiming-strategy, worktree-management]
+knowledge-base: [tdd-execution-loop, task-claiming-strategy, worktree-management, multi-agent-coordination]
 reads: [coding-standards, tdd, git-workflow]
 argument-hint: "<agent-name>"
 ---
@@ -90,7 +90,7 @@ Before writing any code, verify the worktree environment:
    - If on a feature branch with changes, redirect to `/scaffold:multi-agent-resume $ARGUMENTS`
 
 3. **Beads identity** (if `.beads/` exists)
-   - `echo $BD_ACTOR` — should show `$ARGUMENTS`
+   - `echo $BEADS_ACTOR` — should show `$ARGUMENTS`
    - If not set, the worktree setup may be incomplete
 
 4. **Dependency check**
@@ -119,11 +119,13 @@ These rules are critical for multi-agent operation:
 
 **If Beads is configured** (`.beads/` exists):
 - Branch naming: `bd-<id>/<desc>`
-- Run `bd ready` to see available tasks
-- Pick the lowest-ID unblocked task
+- Verify `$BEADS_ACTOR` is set per agent (echo it; bail if empty).
+- Atomically claim the next ready task: `TASK=$(bd ready --claim --json | jq -r '.id')`
+  - This sets `assignee=$BEADS_ACTOR` and `status=in_progress` in a single round-trip — eliminates the race window where two agents both see the same "ready" task.
+  - If `bd ready --claim` returns no task, you're done — exit the loop.
 - Implement following the TDD workflow below
-- After PR is merged: `bd close <id> && bd sync`
-- Repeat with `bd ready` until no tasks remain
+- After PR is merged: `bd close <id>`
+- Repeat (`bd ready --claim --json`) until no tasks remain
 
 **Without Beads:**
 - Branch naming: `<type>/<desc>` (e.g., `feat/add-auth`)
@@ -174,8 +176,28 @@ For each task:
    - Fix any findings at or above `fix_threshold` before proceeding
 
 7. **Create PR**
+   - If Beads is configured, run the PR-readiness checklist first:
+     ```bash
+     if [ -d .beads ]; then
+       bd preflight
+     fi
+     ```
+     Fix any issues `bd preflight` flags before proceeding.
+   - **For 3+ parallel agents**, acquire the project's merge slot to serialize merge-time conflicts:
+     ```bash
+     if [ -d .beads ]; then
+       bd merge-slot acquire --wait    # blocks if held; queues you in priority order
+     fi
+     ```
+     There is one merge slot per project; `--wait` blocks until you have it. Skip for single-agent or two-agent runs. See `content/knowledge/execution/multi-agent-coordination.md`.
    - Push the branch: `git push -u origin HEAD`
    - Create a pull request: `gh pr create`
+   - After the PR merges (or if you abandon the work), release the slot:
+     ```bash
+     if [ -d .beads ]; then
+       bd merge-slot release   # holder verified via $BEADS_ACTOR
+     fi
+     ```
    - Include in the PR description: what was implemented, key decisions, files changed, agent name
    - Follow the PR workflow from `docs/git-workflow.md` or CLAUDE.md
 
@@ -210,10 +232,16 @@ For each task:
 - Resolve conflicts, re-run tests, force-push the branch
 
 **Another agent claimed the same task:**
-- If Beads: `bd sync` will reveal the conflict — pick a different task
+- If Beads: A `git pull` (and `bd dolt pull` if a Dolt remote is configured) brings the local DB current; run `bd doctor --fix` if anything looks stale.
 - Without Beads: check open PRs (`gh pr list`) for overlapping work
 - Move to the next available unblocked task
 
+**A downstream task is blocked on a specific async condition (PR merge, workflow run, timer, human decision):**
+- If Beads: create a gate that blocks the downstream task. The gate has an auto-generated ID. For a PR-merge blocker: `bd gate create --type=gh:pr --blocks <task-id> --await-id=<pr-number> --reason "..."`. For a human-resolved blocker: `bd gate create --blocks <task-id> --reason "..."` (defaults to `--type=human`). Capture the gate ID via `--json | jq -r '.id'` if you need to resolve manually later.
+- The gated task disappears from `bd ready` until the gate resolves. `gh:pr` / `gh:run` / `timer` gates auto-resolve via watchers; `human` gates resolve via `bd gate resolve <gate-id>`.
+- If multiple downstream tasks share one underlying blocker, create one gate per blocked task pointing at the same `--await-id`. For dependency-style blocking ("this task can't start until that task finishes"), use `bd dep add --blocks` instead.
+- See `content/knowledge/execution/multi-agent-coordination.md` for the full pattern.
+
 **Dependency install fails after cleanup:**
 - `git clean -fd` may have removed generated files — re-run the full install sequence
 - If persistent, check if another agent's merge changed the dependency file

package/content/pipeline/build/new-enhancement.md

@@ -263,9 +263,16 @@ For each user story (or logical grouping of small stories):
 **If Beads:**
 ```bash
 bd create "US-XXX: <imperative title>" -p <priority>
-# Priority: 0=blocking release, 1=must-have, 2=should-have, 3=nice-to-have
+# Priority: 0=blocking release, 1=must-have, 2=should-have, 3=nice-to-have, 4=backlog
 ```
 
+For architectural decisions (ADRs), use the built-in `decision` type:
+```bash
+bd create "Use Postgres over MySQL for X" -t decision -p 1
+```
+
+If your project enables custom types via `bd config set types.custom '["story","milestone","spike"]'`, you can also use `-t story` for user-story-sized work and `-t milestone` for releases.
+
 **Without Beads:** Document tasks as a structured list in `docs/implementation-plan.md` with title, priority, dependencies, and description.
 
 #### Task Titles and Descriptions

package/content/pipeline/build/quick-task.md

@@ -157,6 +157,7 @@ Assign priority using Beads conventions:
 - **P1** — Must-have for current milestone
 - **P2** — Should-have (default for most quick tasks)
 - **P3** — Nice-to-have, backlog
+- **P4** — Backlog / future-consideration (lowest priority; effectively deferred)
 
 #### Acceptance Criteria
 Write 2-5 testable acceptance criteria in Given/When/Then format:
@@ -202,6 +203,14 @@ bd create "type(scope): description" -p <priority>
 # Example: bd create "fix(auth): prevent duplicate session creation on rapid re-login" -p 2
 ```
 
+If this task was discovered while doing other work, link the lineage with `discovered-from`:
+```bash
+bd create "fix(parser): handle empty input edge case" \
+  --type bug -p 2 \
+  --deps discovered-from:$CURRENT_TASK_ID
+```
+The new task appears in `bd ready` normally; `discovered-from` is metadata for traceability and does NOT block readiness.
+
 **Without Beads:** Document the task inline and proceed directly to implementation.
 
 Then set the task description with the full context from Phase 2. Include all of:

package/content/pipeline/build/single-agent-resume.md

@@ -98,10 +98,10 @@ Recover your context by checking the current state of work:
 
 **If Beads is configured** (`.beads/` exists):
 - `bd list` — check for tasks with `in_progress` status
-- If a PR shows as merged, close the corresponding task: `bd close <id> && bd sync`
+- If a PR shows as merged, close the corresponding task: `bd close <id>`
 - If there is in-progress work, finish it (see "Resume In-Progress Work" below)
-- Otherwise, start fresh with `bd ready` to find the next available task
-- Continue working until `bd ready` shows no available tasks
+- Otherwise, atomically claim the next ready task: `TASK=$(bd ready --claim --json | jq -r '.id')` (sets `assignee=$BEADS_ACTOR` + `status=in_progress`; no race window).
+- Continue working until `bd ready --claim --json` returns no task.
 
 **Without Beads:**
 - Read `docs/implementation-playbook.md` as the primary task reference.
@@ -148,6 +148,13 @@ Once in-progress work is complete (or if there was none):
    - Fix any findings at or above `fix_threshold` before proceeding
 
 3. **Create PR** (if not already created for in-progress work)
+   - If Beads is configured, run the PR-readiness checklist first:
+     ```bash
+     if [ -d .beads ]; then
+       bd preflight
+     fi
+     ```
+     Fix any issues `bd preflight` flags before proceeding.
    - Push the branch: `git push -u origin HEAD`
    - Create a pull request: `gh pr create`
    - Follow the PR workflow from `docs/git-workflow.md` or CLAUDE.md
@@ -187,7 +194,7 @@ Once in-progress work is complete (or if there was none):
 - Push updates and re-request review
 
 **Task was completed by another agent (multi-agent overlap):**
-- If Beads: `bd sync` will show updated task states
+- If Beads: A `git pull` (and `bd dolt pull` if a Dolt remote is configured) brings the local DB current; run `bd doctor --fix` if anything looks stale.
 - Without Beads: check the plan/playbook for recently completed tasks
 - Skip to the next available task
 

package/content/pipeline/build/single-agent-start.md

@@ -101,11 +101,13 @@ Before writing any code, verify the environment is ready:
 Check if `.beads/` directory exists.
 
 **If Beads is configured:**
-- Run `bd ready` to see available tasks
-- Pick the lowest-ID unblocked task
+- Atomically claim the next ready task: `TASK=$(bd ready --claim --json | jq -r '.id')`
+  - This sets `assignee=$BEADS_ACTOR` (or your git user.name) and `status=in_progress` in a single round-trip — no race window vs other agents.
+  - If you need a specific task by ID instead, use `bd update <id> --claim`.
+  - If `bd ready --claim` returns no task, you're done — exit the loop.
 - Implement following the TDD workflow below
-- After PR is merged, run `bd close <id> && bd sync`
-- Repeat with `bd ready` until no tasks remain
+- After PR is merged, run `bd close <id>`
+- Repeat (`bd ready --claim --json`) until no tasks remain
 
 **Without Beads:**
 1. Read `docs/implementation-playbook.md` as the primary task execution reference.
@@ -153,6 +155,13 @@ For each task:
    - Fix any findings at or above `fix_threshold` before proceeding
 
 7. **Create PR**
+   - If Beads is configured, run the PR-readiness checklist first:
+     ```bash
+     if [ -d .beads ]; then
+       bd preflight
+     fi
+     ```
+     Fix any issues `bd preflight` flags before proceeding. (Note: do NOT use `[ -d .beads ] && bd preflight` — that returns exit-1 when `.beads/` is absent and breaks any caller running under `set -e`.)
    - Push the branch: `git push -u origin HEAD`
    - Create a pull request: `gh pr create`
    - Include in the PR description: what was implemented, key decisions, files changed

package/content/pipeline/consolidation/workflow-audit.md

@@ -37,7 +37,7 @@ inconsistent command formats. Fix all issues found.
 
 ## Quality Criteria
 - (mvp) CLAUDE.md contains complete workflow (9 steps + AI review step 4.5)
-- (mvp) Commit format is consistent everywhere (If Beads: [BD-<id>] type(scope): description. Without Beads: type(scope): description)
+- (mvp) Commit format is consistent everywhere (If Beads: [bd-<id>] type(scope): description. Without Beads: type(scope): description)
 - (mvp) Branch naming is consistent everywhere (If Beads: bd-<task-id>/<short-desc>. Without Beads: <type>/<short-desc>)
 - (mvp) PR workflow includes all 8 sub-steps with --delete-branch flag
 - (mvp) If Beads: task closure uses bd close (not bd update --status completed)

package/content/pipeline/environment/git-workflow.md

@@ -34,11 +34,11 @@ parallel agents, CI pipeline, branch protection, and conflict prevention rules.
 
 ## Quality Criteria
 - (mvp) Branch naming format is consistent (Beads: bd-<task-id>/<desc>. Non-Beads: <type>/<desc>)
-- (mvp) Commit format is consistent (Beads: [BD-<id>] type(scope): desc. Non-Beads: type(scope): desc)
+- (mvp) Commit format is consistent (Beads: [bd-<id>] type(scope): desc. Non-Beads: type(scope): desc)
 - (deep) PR workflow includes all 8 sub-steps (commit, AI review, rebase, push, create,
   auto-merge with --delete-branch, watch CI, confirm merge)
 - (deep) Worktree script creates permanent worktrees with workspace branches
-- (deep) If Beads: BD_ACTOR environment variable documented for agent identity
+- (deep) If Beads: BEADS_ACTOR environment variable documented for agent identity
 - (deep) CI workflow job name matches branch protection context
 - (mvp) Branch cleanup documented for both single-agent and worktree-agent variants
 - (deep) Agent crash recovery procedure documented