@zigrivers/scaffold 3.27.0 → 3.29.0

package/content/knowledge/data-pipeline/data-pipeline-orchestration.md

@@ -2,6 +2,10 @@
 name: data-pipeline-orchestration
 description: DAG vs event-driven vs scheduled orchestration, retry policies, SLA monitoring, and lineage tracking for data pipelines
 topics: [data-pipeline, orchestration, dag, event-driven, scheduling, retry-policies, sla-monitoring, lineage, airflow, prefect, dagster]
+volatility: evolving
+last-reviewed: null
+version-pin: null
+sources: []
 ---
 
 Pipeline orchestration is the control plane that schedules work, manages dependencies, handles failures, and provides visibility into pipeline health. The choice between schedule-driven, event-driven, and DAG-based orchestration determines operational complexity, latency characteristics, and how well the system degrades under load. Poor orchestration design — missing retries, no SLA monitoring, absent lineage — turns data pipelines into production support burdens.

package/content/knowledge/data-pipeline/data-pipeline-project-structure.md

@@ -2,6 +2,10 @@
 name: data-pipeline-project-structure
 description: Canonical directory layout for data pipeline projects covering DAGs, transforms, sinks, quality checks, configuration, and tests
 topics: [data-pipeline, project-structure, dags, transforms, sinks, quality, config, tests]
+volatility: stable
+last-reviewed: null
+version-pin: null
+sources: []
 ---
 
 A well-organized data pipeline project separates pipeline orchestration logic from transformation logic, data sinks, and quality checks. This separation allows each concern to evolve independently and makes the codebase navigable for engineers unfamiliar with the project. The structure below is opinionated but widely applicable to Airflow, Prefect, Dagster, and similar orchestration tools.

package/content/knowledge/data-pipeline/data-pipeline-quality.md

@@ -2,6 +2,10 @@
 name: data-pipeline-quality
 description: Schema validation, anomaly detection, data quality tests using Great Expectations and dbt, and reconciliation patterns
 topics: [data-pipeline, data-quality, schema-validation, anomaly-detection, great-expectations, dbt, reconciliation, testing]
+volatility: evolving
+last-reviewed: null
+version-pin: null
+sources: []
 ---
 
 Data quality failures are the most operationally damaging class of data pipeline bugs because they often go undetected until a business user notices wrong numbers. Unlike pipeline failures (which are loud and immediately visible), quality degradation is silent — data flows, pipelines succeed, but the numbers are wrong. Building quality checks directly into the pipeline, not as a separate offline process, is the only reliable defense.

package/content/knowledge/data-pipeline/data-pipeline-requirements.md

@@ -2,6 +2,10 @@
 name: data-pipeline-requirements
 description: SLA requirements (latency, throughput, freshness), data quality budgets, and regulatory compliance (PII, GDPR) for data pipelines
 topics: [data-pipeline, requirements, sla, latency, throughput, freshness, data-quality, pii, gdpr, compliance]
+volatility: stable
+last-reviewed: null
+version-pin: null
+sources: []
 ---
 
 Data pipeline requirements must be defined in measurable terms before any architecture decision is made. Vague requirements like "fast" or "reliable" translate into untestable systems. Every pipeline needs explicit SLAs for latency, throughput, and data freshness — and a defined budget for data quality violations and regulatory compliance obligations.

package/content/knowledge/data-pipeline/data-pipeline-schema-management.md

@@ -2,6 +2,10 @@
 name: data-pipeline-schema-management
 description: Schema registry, evolution patterns, breaking change detection, and contract testing for data pipeline schemas
 topics: [data-pipeline, schema-management, schema-registry, schema-evolution, breaking-changes, contract-testing, avro, protobuf]
+volatility: evolving
+last-reviewed: null
+version-pin: null
+sources: []
 ---
 
 Schema management is the discipline of controlling how the structure of data changes over time while maintaining compatibility between producers and consumers. Without schema governance, a single field rename in a source system cascades into dozens of broken downstream pipelines, dashboards, and ML models. Schema registry, evolution compatibility rules, breaking change detection, and consumer contract tests are the four pillars that make schema changes safe.

package/content/knowledge/data-pipeline/data-pipeline-security.md

@@ -2,6 +2,10 @@
 name: data-pipeline-security
 description: PII handling, encryption at rest and in transit, access control, and audit logging for data pipelines
 topics: [data-pipeline, security, pii, encryption, access-control, audit-logging, gdpr, data-masking]
+volatility: evolving
+last-reviewed: null
+version-pin: null
+sources: []
 ---
 
 Data pipelines are high-value targets for security incidents because they aggregate sensitive data from multiple systems and often run with broad service account permissions. A pipeline that ingests payment data, user PII, and health records and writes to a central warehouse becomes a single point of compromise. Security must be designed into the pipeline from the start — encryption, least-privilege access, PII handling, and audit logging cannot be retrofitted economically.

package/content/knowledge/data-pipeline/data-pipeline-streaming-patterns.md

@@ -2,6 +2,10 @@
 name: data-pipeline-streaming-patterns
 description: Event time vs processing time, windowing strategies, watermarks, and exactly-once semantics for streaming data pipelines
 topics: [data-pipeline, streaming, event-time, processing-time, windowing, watermarks, exactly-once, flink, kafka-streams]
+volatility: evolving
+last-reviewed: null
+version-pin: null
+sources: []
 ---
 
 Streaming pipeline correctness depends on understanding the distinction between when an event occurred and when it was processed, handling late-arriving data with watermarks, and ensuring that each event is processed exactly once even in the face of failures. Getting these fundamentals wrong produces pipelines that appear to work but silently compute incorrect aggregations — bugs that surface only when business users notice wrong numbers weeks later.

package/content/knowledge/data-pipeline/data-pipeline-testing.md

@@ -2,6 +2,10 @@
 name: data-pipeline-testing
 description: Unit tests for transforms, integration tests, data quality tests, and performance tests for data pipelines
 topics: [data-pipeline, testing, unit-tests, integration-tests, data-quality-tests, performance-tests, tdd, pytest]
+volatility: stable
+last-reviewed: null
+version-pin: null
+sources: []
 ---
 
 Data pipeline testing requires a layered strategy: fast unit tests for transformation logic, integration tests against containerized infrastructure, data quality tests that run inline in production, and performance tests to catch throughput regressions. The most common testing gap in pipeline projects is that DAG files and orchestration logic are tested but transformation functions — the business logic — are not. Transformation functions must be the most heavily tested component because correctness of results depends entirely on them.

package/content/knowledge/data-science/data-science-architecture.md

@@ -2,6 +2,11 @@
 name: data-science-architecture
 description: Local-first architecture for solo and small-team data science — notebook exploration, src/ promotion, idempotent entrypoint pipelines, Polars vs Pandas choice, and artifact separation
 topics: [data-science, architecture, polars, pandas, notebook-promotion]
+volatility: evolving
+last-reviewed: null
+version-pin: null
+sources:
+  - url: https://the-turing-way.netlify.app/reproducible-research/reproducible-research
 ---
 
 "Architecture" sounds heavy for a single analyst opening a notebook, but it is the one decision that separates work a collaborator can rerun tomorrow from a pile of ad-hoc scripts that only you can coax back to life. Solo DS work is local-first, reproducibility-first, and almost never needs Airflow or a Kubernetes cluster. What it needs is a coherent shape that scales from "a single notebook" to "a pipeline a teammate can clone and run" — and a clear story about where raw data, intermediate data, models, and reports each live. This doc lays out that shape and the small set of conventions that make it hold together.

package/content/knowledge/data-science/data-science-conventions.md

@@ -2,6 +2,12 @@
 name: data-science-conventions
 description: Python coding conventions for solo data-science work — ruff for lint+format, pragmatic type hints, pyproject.toml as single config source, import ordering, module layout, naming, and docstrings
 topics: [data-science, conventions, python, ruff, type-hints]
+volatility: evolving
+last-reviewed: null
+version-pin: null
+sources:
+  - url: https://docs.astral.sh/ruff/
+  - url: https://peps.python.org/pep-0008/
 ---
 
 Solo data-science code drifts faster than any other kind of Python: half of it lives in notebooks, the other half migrates into scripts, and nothing stays stable long enough to earn a style review. Consistent conventions are the only thing that keeps cognitive load bounded when you come back to a project after two months. Encode them in tooling (`ruff`, `pyproject.toml`) so they run on save — not on willpower — and the notebook→script promotion path stays smooth instead of becoming a cleanup tax.

package/content/knowledge/data-science/data-science-data-versioning.md

@@ -2,6 +2,12 @@
 name: data-science-data-versioning
 description: When and how to version data for reproducibility — size-based rule for choosing between git+Parquet, git-lfs, and DVC
 topics: [data-science, data-versioning, dvc, parquet, git-lfs]
+volatility: evolving
+last-reviewed: null
+version-pin: null
+sources:
+  - url: https://the-turing-way.netlify.app/reproducible-research/vcs
+  - url: https://git-scm.com/docs/gitattributes
 ---
 
 If you can't answer "what data produced this result", you can't reproduce it.

package/content/knowledge/data-science/data-science-dev-environment.md

@@ -2,6 +2,12 @@
 name: data-science-dev-environment
 description: Reproducible local Python dev environment for data science using uv, direnv, pre-commit, and pyproject.toml
 topics: [data-science, dev-environment, uv, direnv, pre-commit]
+volatility: evolving
+last-reviewed: null
+version-pin: null
+sources:
+  - url: https://docs.astral.sh/uv/
+  - url: https://peps.python.org/pep-0621/
 ---
 
 A data-science project that cannot be recreated in minutes is a liability. Notebooks pick up stale package versions, secrets leak into `.bashrc`, and "works on my machine" kills any chance of a collaborator (or future-you) rerunning an experiment. The fix is not complicated: one lockfile, one place for env vars, one pre-commit hook, no bespoke shell scripts. This guide is opinionated toward solo and small-team workflows where local-first beats container-first.

package/content/knowledge/data-science/data-science-experiment-tracking.md

@@ -2,6 +2,14 @@
 name: data-science-experiment-tracking
 description: Local MLflow setup, run instrumentation, git commit tagging, and run comparison for solo and small-team data science work
 topics: [data-science, experiment-tracking, mlflow, weights-and-biases, reproducibility]
+volatility: fast-moving
+last-reviewed: null
+version-pin: 'MLflow 2.x'
+sources:
+  - url: https://mlflow.org/docs/latest/tracking.html
+    anchor: '#tracking-quickstart'
+  - url: https://docs.wandb.ai/guides/track
+    anchor: '#track-experiments'
 ---
 
 Without experiment tracking, data science becomes archaeology: three weeks after a promising result, a stakeholder asks "which config produced that number?" and answering it turns into a forensic exercise — sifting through notebook history, Slack messages, and commented-out cells. A lightweight experiment tracker fixes this with one discipline: every run logs its hyperparameters, metrics, artifacts, and the git commit SHA that produced it. For a solo DS or small team, you do not need a shared server or a cloud account — a local MLflow instance on SQLite is enough to get the full benefit, and you can graduate to a shared deployment later without changing the instrumentation.

package/content/knowledge/data-science/data-science-model-evaluation.md

@@ -2,6 +2,11 @@
 name: data-science-model-evaluation
 description: Honest model evaluation for solo/small-team DS — metric choice, one-shot holdout, cross-validation, calibration, and error slicing with sklearn
 topics: [data-science, evaluation, sklearn, cross-validation, calibration]
+volatility: evolving
+last-reviewed: null
+version-pin: null
+sources:
+  - url: https://the-turing-way.netlify.app/reproducible-research/testing
 ---
 
 Every solo DS project produces a moment where a notebook prints `0.92 accuracy` on a test set and the author quietly believes the model works. Then it ships — and recall on the minority class is 0.12, the probabilities are miscalibrated, and a single region drives half the error. Evaluation discipline is the only thing separating a model that works from a model that looked like it worked on a single split. At solo scale you do not have an ML platform team checking your work, which makes the discipline entirely your responsibility.

package/content/knowledge/data-science/data-science-notebook-discipline.md

@@ -2,6 +2,11 @@
 name: data-science-notebook-discipline
 description: Notebook discipline for reproducible data science — Marimo as primary, Jupyter plus jupytext as fallback, promoting working cells to tested modules
 topics: [data-science, notebooks, marimo, jupyter, reproducibility]
+volatility: evolving
+last-reviewed: null
+version-pin: null
+sources:
+  - url: https://the-turing-way.netlify.app/reproducible-research/code-quality
 ---
 
 Every data scientist has shipped a notebook that "worked for me in a session" and then produced different numbers the next morning — or worse, different numbers in a colleague's environment or a production run. The usual cause is not a bug in the code; it is hidden state. Jupyter cells can be executed in any order, re-run selectively, or silently depend on variables that were defined in a cell that has since been edited or deleted. The kernel's in-memory state becomes the real program, and the `.ipynb` file is just a partial, sometimes misleading, transcript. For solo and small-team DS work, this is the single biggest source of "it worked yesterday" pain, and it is entirely avoidable with the right tooling and habits.

package/content/knowledge/data-science/data-science-observability.md

@@ -2,6 +2,12 @@
 name: data-science-observability
 description: Monitoring deployed DS models and pipelines — prediction logging to Parquet, scheduled evaluation, basic drift detection, and Evidently for deeper analysis
 topics: [data-science, observability, monitoring, drift, evidently]
+volatility: evolving
+last-reviewed: null
+version-pin: null
+sources:
+  - url: https://opentelemetry.io/docs/concepts/observability-primer/
+  - url: https://sre.google/sre-book/monitoring-distributed-systems/
 ---
 
 Models don't fail loudly. A scoring job keeps running, rows keep landing in the output table, dashboards stay green — and quietly, the predictions get worse. The world drifts away from whatever snapshot you trained on, and nobody notices until a stakeholder says "these numbers look weird." Observability for a solo DS isn't a platform; it's a small set of habits that give you a chance to catch decay before someone else does.

package/content/knowledge/data-science/data-science-project-structure.md

@@ -2,6 +2,11 @@
 name: data-science-project-structure
 description: Opinionated directory layout for solo and small-team data-science projects — notebooks, src, data, models, reports, tests, configs — with a promotion path from exploration to tested modules
 topics: [data-science, project-structure, layout]
+volatility: stable
+last-reviewed: null
+version-pin: null
+sources:
+  - url: https://the-turing-way.netlify.app/project-design/project-design
 ---
 
 A solo data-science project accumulates artifacts faster than most software: half-finished notebooks, CSV dumps, parquet caches, serialized models, PNG charts, and the occasional markdown write-up. Without a deliberate directory structure, the project turns into a folder of 40 loose files within a month and a new contributor — including future-you — cannot tell what is canonical, what is scratch, and what is safe to delete. A clear layout fixes three problems at once: discoverability (where does X live?), git hygiene (what is tracked vs generated?), and the promotion path (how does throwaway notebook code become tested library code?).

package/content/knowledge/data-science/data-science-reproducibility.md

@@ -2,6 +2,14 @@
 name: data-science-reproducibility
 description: Reproducibility for solo/small-team DS — pin deps with uv lock, seed everything, set PYTHONHASHSEED, and reach for Docker only at OS boundaries
 topics: [data-science, reproducibility, determinism, uv, docker]
+volatility: evolving
+last-reviewed: null
+version-pin: null
+sources:
+  - url: https://docs.astral.sh/uv/concepts/projects/
+    anchor: '#uv-lock'
+  - url: https://the-turing-way.netlify.app/reproducible-research/reproducible-research.html
+    anchor: '#reproducible-research'
 ---
 
 You show a result in Monday's meeting. Six months later, on a new laptop, you can't reproduce it. Three things usually cause this: dependencies drifted (a minor NumPy release changed a default), randomness wasn't pinned (a shuffle or init picked a different seed), or the data changed underneath you. Reproducibility is the discipline of eliminating all three so the same inputs always produce the same numbers.

package/content/knowledge/data-science/data-science-requirements.md

@@ -2,6 +2,11 @@
 name: data-science-requirements
 description: Problem framing, success metrics, evaluation-test design, stakeholder contracts, and nonfunctional requirements for solo/small-team data science projects
 topics: [data-science, requirements, evaluation, success-metrics, reproducibility]
+volatility: stable
+last-reviewed: null
+version-pin: null
+sources:
+  - url: https://the-turing-way.netlify.app/project-design/project-design
 ---
 
 As a solo or small-team data scientist without an existing data platform, the single biggest risk to your project is not a bad model — it is ambiguous requirements. Without a tight written spec, a DS project sprawls: the question drifts week to week, the notebook becomes unreproducible, and the stakeholder quietly reinterprets the output. This document defines what "done" looks like for an analytical pipeline, model, or report built from scratch — so you can stop work on time and defend the result.

package/content/knowledge/data-science/data-science-security.md

@@ -2,6 +2,14 @@
 name: data-science-security
 description: Practical security guardrails for solo / small-team data-science work — PII masking at ingest, credential hygiene with direnv and 1Password, data classification tiers, notebook output stripping, and a note on model memorization
 topics: [data-science, security, pii, secrets, data-classification]
+volatility: fast-moving
+last-reviewed: null
+version-pin: 'OWASP ML Top 10 2023'
+sources:
+  - url: https://owasp.org/www-project-machine-learning-security-top-10/
+    anchor: '#ml-top-10'
+  - url: https://csrc.nist.gov/pubs/ai/100/2/e2025/final
+    anchor: '#adversarial-ml'
 ---
 
 DS work has elevated security risk because analysis code routinely touches raw customer data before anyone has had a chance to sanitize it. A notebook can render real names, emails, and account numbers inline, then get committed to git, emailed to a stakeholder, or pasted into Slack without a second thought. Prediction caches and CSV exports quietly duplicate sensitive rows into `data/` subdirectories. Credentials for warehouses and cloud buckets get dropped into `.env` files or — worse — directly into a notebook cell. The blast radius of a sloppy DS workflow is larger than people assume, and the mitigations are not exotic: they are cheap, boring habits that need to be enforced by tooling.

package/content/knowledge/data-science/data-science-testing.md

@@ -2,6 +2,11 @@
 name: data-science-testing
 description: Testing strategy for solo DS code — pytest for pure functions, pandera for DataFrame schemas at test time and at ingest boundaries, and committed CSV fixtures for deterministic tests
 topics: [data-science, testing, pytest, pandera]
+volatility: evolving
+last-reviewed: null
+version-pin: null
+sources:
+  - url: https://the-turing-way.netlify.app/reproducible-research/testing
 ---
 
 Data-science code rots quietly. A notebook cell that worked on Tuesday's snapshot silently breaks on Friday's because an upstream column was renamed, a dtype shifted from `int64` to `float64`, or a categorical grew a new level nobody tested for. Refactors that move feature logic out of a notebook into `src/` routinely regress because there was no test pinning the old behavior. Tests catch these failures at the line that introduced them instead of at the end of a three-hour pipeline run.

package/content/knowledge/execution/enhancement-workflow.md

@@ -2,6 +2,10 @@
 name: enhancement-workflow
 description: Discovery and implementation workflow for adding features to existing projects
 topics: [enhancement, features, planning, discovery]
+volatility: stable
+last-reviewed: null
+version-pin: null
+sources: []
 ---
 
 # Enhancement Workflow

package/content/knowledge/execution/multi-agent-coordination.md

@@ -0,0 +1,129 @@
+---
+name: multi-agent-coordination
+description: Upstream Beads primitives for coordinating parallel agents — bd merge-slot for serialized merge resolution and bd gate for async coordination
+topics: [beads, multi-agent, worktrees, merge-conflicts, coordination, parallel-execution]
+volatility: evolving
+last-reviewed: null
+version-pin: null
+sources:
+  - url: https://github.com/steveyegge/beads
+---
+
+# Multi-Agent Coordination (Beads Primitives)
+
+## Summary
+
+When multiple agents work in parallel worktrees and converge on `main`, two upstream Beads primitives prevent the most common coordination failures: `bd merge-slot` serializes the rebase-and-push race so two agents finishing at once don't clobber each other, and `bd gate` lets a blocked task wait on an arbitrary asynchronous event (CI green, peer review, external approval). Both are optional — scaffold's multi-agent flows work without them — but they meaningfully reduce coordination cost in active parallel workloads.
+
+## Deep Guidance
+
+The two primitives below are the load-bearing Deep Guidance for this entry. The per-command sections explain when to acquire/release each, the failure modes, and the asynchronous coordination patterns they support. Treat the rest of this document (from this heading to EOF) as the section the assembly engine injects.
+
+## `bd merge-slot` — serialized merge resolution
+
+**Problem:** Two agents finish in-flight tasks at roughly the same time. Both rebase on `origin/main` and push. The second agent's push races with the first agent's merge — either gets `non-fast-forward` (retry) or merges a stale base (silent conflict).
+
+**Solution:** Acquire the project's merge slot before rebasing/pushing. Release it after the PR merges. There is **one** merge slot per project (stored as a bead with ID `<prefix>-merge-slot`); the slot uses `status=in_progress` + `metadata.holder` to track the current holder, and a priority-ordered `metadata.waiters` queue.
+
+### Commands
+
+```bash
+# First-time setup (once per project — usually done at bd init time):
+bd merge-slot create
+
+# Before rebasing your feature branch on main:
+bd merge-slot acquire --wait
+# Without --wait, acquire FAILS immediately if the slot is held. With --wait it
+# adds you to the waiters queue and blocks until the slot frees. Holder defaults
+# to $BEADS_ACTOR; pass --holder <name> to override.
+
+# Now safe to rebase and push:
+git fetch origin && git rebase origin/main
+git push -u origin HEAD
+
+# After your PR merges (or if you abandon the work):
+bd merge-slot release
+# --holder is optional (defaults to $BEADS_ACTOR) and is used for verification
+# that you're releasing your own hold, not someone else's.
+
+# To inspect current holder:
+bd merge-slot check
+```
+
+### When to use
+
+Use `bd merge-slot` in multi-agent flows (3+ agents, OR projects where a merge conflict requires careful manual resolution). Skip it for single-agent or two-agent workflows where collisions are rare and `git push` retries are acceptable.
+
+### Failure modes
+
+- **Stale slot** (agent crashes between acquire and release): `bd merge-slot check` reports the current holder. Manual recovery is `bd update <prefix>-merge-slot --status open` to clear the holder field (do this with care — verify the original holder is truly gone first).
+- **Slot held by yourself in a different worktree**: the `--holder` field is checked on release, so multiple worktrees with the same `$BEADS_ACTOR` cannot interfere. Different actors queue behind each other.
+
+## `bd gate` — async coordination gates
+
+**Problem:** Agent A's task can't start until something happens (a PR merges, a workflow completes, a human reviews). Without a gate, Agent A either polls (wasteful) or proceeds anyway and discovers the missing dependency the hard way.
+
+**Solution:** Create a gate issue that blocks the dependent task. The gate is itself a Beads issue with an auto-generated ID. Resolving the gate unblocks the task.
+
+Gate types:
+- `human` (default) — Requires a manual `bd gate resolve <gate-id>`.
+- `timer` — Auto-resolves after `--timeout` (e.g., `--timeout=2h`).
+- `gh:run` — Waits for a GitHub Actions run; `--await-id=<run-id>`.
+- `gh:pr` — Waits for a PR merge; `--await-id=<pr-number>`.
+
+### Commands
+
+```bash
+# When you discover that bd-xyz is blocked until something happens, create a gate.
+# The gate has an auto-generated ID; capture it via --json:
+GATE_ID=$(bd gate create \
+  --blocks bd-xyz \
+  --reason "Waiting for auth-middleware-v2 PR to merge" \
+  --type human \
+  --json | jq -r '.id')
+
+# Common variants:
+# - gh:pr gate (auto-resolves on PR merge)
+bd gate create --type=gh:pr --blocks bd-xyz --await-id=123 --reason "Blocked on PR #123"
+
+# - timer gate
+bd gate create --type=timer --blocks bd-xyz --timeout=2h --reason "Recheck in 2h"
+
+# When the underlying condition is met, resolve manually (human gates) or rely on
+# the type-specific watcher (gh:pr, gh:run, timer):
+bd gate resolve "$GATE_ID" --reason "PR #123 merged, middleware live"
+
+# Check what's gated:
+bd gate list           # open gates only
+bd gate list --all     # include closed
+bd gate check          # evaluate all open gates (resolves any whose condition is met)
+```
+
+### When to use
+
+Use gates for one-off async dependencies — "this task can't proceed until X happens, and X is identifiable as a run ID, a PR number, a timer, or a human decision." Skip them for plain "this task depends on that task" cases, which are covered by `bd dep add --blocks` (a dependency, not a gate).
+
+### Pattern: multiple downstream tasks share one underlying blocker
+
+If five downstream tasks all wait on the same PR merging, create five gh:pr gates (one per blocked issue) all pointing at the same `--await-id=<pr-number>`:
+
+```bash
+for ID in bd-aaa bd-bbb bd-ccc bd-ddd bd-eee; do
+  bd gate create --type=gh:pr --blocks "$ID" --await-id=123 --reason "Blocked on PR #123"
+done
+```
+
+`bd gate check` (or the automatic watcher) resolves all five at once when the PR merges.
+
+> The `bd gate add-waiter` subcommand is a different mechanism — it registers an agent's *wake address* (e.g., "my-project/workers/agent-1") to receive notifications. It's not for chaining issues to gates; use `--blocks` on `bd gate create` for that.
+
+## Composition
+
+Both primitives compose with the rest of the multi-agent flow:
+
+- `bd ready --claim` picks a non-gated, non-blocked task.
+- `bd preflight` validates task readiness before PR (already in scaffold's start prompts).
+- `bd merge-slot acquire` serializes the merge.
+- `bd gate resolve` unblocks downstream waiters when your work lands.
+
+For the canonical sequence in scaffold's multi-agent prompts, see `content/pipeline/build/multi-agent-start.md`.

package/content/knowledge/execution/task-claiming-strategy.md

@@ -2,6 +2,10 @@
 name: task-claiming-strategy
 description: Task selection and management patterns for AI agent execution
 topics: [tasks, execution, agents, planning]
+volatility: stable
+last-reviewed: null
+version-pin: null
+sources: []
 ---
 
 # Task Claiming Strategy
@@ -66,7 +70,7 @@ Before starting a task, verify all its blockers are resolved. After completing e
 ### Multi-Agent Conflict Avoidance — Extended
 
 **Claiming a task:**
-- Creating a feature branch (e.g., `bd-42/add-user-endpoint`) is the claim signal
+- Creating a feature branch (e.g., `bd-a3f8/add-user-endpoint`) is the claim signal
 - Other agents should check for existing branches before claiming the same task
 - If two agents accidentally claim the same task, the one with fewer commits yields
 
@@ -100,9 +104,9 @@ Beads is an optional task-tracking tool. Detect its presence and adapt.
 
 **When `.beads/` directory exists:**
 - Use `bd ready` to list tasks that are ready for work
-- Use `bd claim <id>` to claim a task (if available)
+- Use `bd update <id> --claim` to atomically claim a task (or `bd ready --claim --json` to find and claim the first available in one call)
 - Use `bd close <id>` after PR is merged to mark task complete
-- Task IDs come from Beads (`bd-42`, `bd-43`, etc.)
+- Task IDs come from Beads (`bd-a3f8`, `bd-a3f9`, etc. — hash-based, lowercase)
 - Branch naming follows Beads convention: `bd-<id>/<short-desc>`
 
 **Without Beads:**
@@ -123,6 +127,18 @@ A task is complete when all of the following are true:
 
 Only after all five criteria are met should the task be marked as done.
 
+## Discovered Work
+
+While implementing a claimed task, you may discover bugs or follow-up tasks. Don't silently expand the current task's scope — file the new work as a separate Beads issue with `discovered-from`:
+
+```bash
+bd create "fix(parser): handle empty input edge case" \
+  --type bug -p 2 \
+  --deps discovered-from:$CURRENT_TASK_ID
+```
+
+`discovered-from` is metadata for traceability — the new issue appears in `bd ready` normally and does NOT block the current task. This preserves the audit trail of why the new task exists.
+
 ## See Also
 
 - [tdd-execution-loop](./tdd-execution-loop.md) — Red-green-refactor cycle and commit timing

package/content/knowledge/execution/tdd-execution-loop.md

@@ -2,6 +2,11 @@
 name: tdd-execution-loop
 description: Red-green-refactor execution cycle for AI agents
 topics: [tdd, execution, testing, workflow]
+volatility: stable
+last-reviewed: null
+version-pin: null
+sources:
+  - url: https://martinfowler.com/bliki/TestDrivenDevelopment.html
 ---
 
 # TDD Execution Loop

package/content/knowledge/execution/worktree-management.md

@@ -2,6 +2,11 @@
 name: worktree-management
 description: Git worktree patterns for parallel multi-agent execution
 topics: [git, worktrees, multi-agent, branching]
+volatility: evolving
+last-reviewed: null
+version-pin: null
+sources:
+  - url: https://git-scm.com/docs/git-worktree
 ---
 
 # Worktree Management
@@ -179,16 +184,18 @@ git branch | grep "workspace" | xargs -r git branch -D
 
 Use `-D` here because workspace branches are not merged — they're disposable.
 
-### BD_ACTOR Environment Variable
+### BEADS_ACTOR Environment Variable
 
-When using Beads for task tracking, set `BD_ACTOR` per agent for attribution:
+When using Beads for task tracking, set `BEADS_ACTOR` per agent for attribution:
 
 ```bash
-export BD_ACTOR="agent-1"
+export BEADS_ACTOR="agent-1"
 ```
 
 This ensures that task claims, completions, and other Beads operations are attributed to the correct agent. Set it in the agent's shell environment before starting work.
 
+> Older Beads versions (<v1.0.0) used `BD_ACTOR`. It's still accepted as a deprecated alias — if you see it in legacy scripts, rename when you next edit.
+
 ### Listing Active Worktrees
 
 To see all active worktrees and their branches:

package/content/knowledge/finalization/apply-fixes-and-freeze.md

@@ -2,6 +2,10 @@
 name: apply-fixes-and-freeze
 description: Guidance on prioritizing validation fixes, applying them safely, and freezing documentation for implementation
 topics: [finalization, fixes, freeze, validation, documentation-quality]
+volatility: stable
+last-reviewed: null
+version-pin: null
+sources: []
 ---
 
 # Apply Fixes and Freeze

package/content/knowledge/finalization/developer-onboarding.md

@@ -2,6 +2,10 @@
 name: developer-onboarding
 description: What an effective onboarding guide covers — repo setup, architecture overview, key patterns
 topics: [onboarding, documentation, getting-started, developer-experience]
+volatility: stable
+last-reviewed: null
+version-pin: null
+sources: []
 ---
 
 # Developer Onboarding

package/content/knowledge/finalization/implementation-playbook.md

@@ -2,6 +2,10 @@
 name: implementation-playbook
 description: Structuring work for AI agents — task execution, coding standards, git workflow, quality gates
 topics: [playbook, agents, implementation, coding-standards, git-workflow]
+volatility: stable
+last-reviewed: null
+version-pin: null
+sources: []
 ---
 
 # Implementation Playbook

package/content/knowledge/game/game-accessibility.md

@@ -2,6 +2,10 @@
 name: game-accessibility
 description: Xbox Accessibility Guidelines as best-practice guidance, game-specific a11y categories, CVAA scope, and low-cost high-impact features
 topics: [game-dev, accessibility, xag, cvaa, colorblind, remapping]
+volatility: evolving
+last-reviewed: null
+version-pin: null
+sources: []
 ---
 
 Game accessibility is about removing barriers that prevent players with disabilities from experiencing your game. The Xbox Accessibility Guidelines (XAG) provide the most comprehensive industry framework — not as a legal compliance checklist, but as best-practice guidance that Microsoft explicitly positions as aspirational. Every feature you implement opens your game to more players, and many accessibility features (subtitles, remapping, difficulty options) benefit all players regardless of ability.

package/content/knowledge/game/game-ai-patterns.md

@@ -2,6 +2,10 @@
 name: game-ai-patterns
 description: Behavior trees, GOAP, utility AI, finite state machines, NavMesh pathfinding, perception systems, and companion AI
 topics: [game-dev, ai, behavior-trees, goap, pathfinding, npc]
+volatility: evolving
+last-reviewed: null
+version-pin: null
+sources: []
 ---
 
 Game AI encompasses the systems that control non-player character behavior — from enemy combat tactics to companion pathfinding to ambient NPC routines. Unlike machine learning AI, game AI is deterministic and designed: every behavior is authored by a designer and executed by a runtime system. The goal is not intelligence but the appearance of intelligence — NPCs should behave in ways that feel believable, create interesting gameplay challenges, and respond to the player's actions in readable ways. The core trade-off in game AI is expressiveness vs. complexity: more sophisticated AI systems enable richer behavior but are harder to design, debug, and performance-tune.

package/content/knowledge/game/game-asset-pipeline.md

@@ -2,6 +2,10 @@
 name: game-asset-pipeline
 description: Asset naming taxonomies by engine, per-type specs (poly budgets, texture sizes, audio formats), DCC tool chains, Git LFS config, and file locking
 topics: [game-dev, assets, pipeline, naming, dcc, lfs]
+volatility: evolving
+last-reviewed: null
+version-pin: null
+sources: []
 ---
 
 The asset pipeline is the full chain from an artist's DCC tool (Maya, Blender, Substance Painter, Houdini) through export, import, optimization, and packaging into the final game build. A well-structured pipeline enforces naming conventions, validates assets against per-type budgets on import, automates texture compression and LOD generation, and integrates with version control to prevent binary merge conflicts. Pipeline failures are insidious — a single 4K texture on a UI element or an uncompressed WAV in the audio bank can ship to players because nobody validated the asset against its budget.

package/content/knowledge/game/game-audio-design.md

@@ -2,6 +2,10 @@
 name: game-audio-design
 description: Wwise vs FMOD selection, bus hierarchy, spatial audio, adaptive music systems, VO pipeline, and platform loudness targets
 topics: [game-dev, audio, fmod, wwise, spatial-audio, adaptive-music]
+volatility: evolving
+last-reviewed: null
+version-pin: null
+sources: []
 ---
 
 Game audio is not background decoration — it is a primary feedback channel that communicates game state, spatial awareness, emotional tone, and mechanical timing to the player. A gunshot tells the player where the enemy is, how far away they are, and what weapon they are using. Adaptive music builds tension before the player consciously recognizes danger. Missing or poorly mixed audio creates a hollow, unfinished experience that players feel even if they cannot articulate why. Audio architecture decisions (middleware, bus hierarchy, adaptive systems) must be made early because they affect content pipelines, memory budgets, and CPU budgets throughout production.

package/content/knowledge/game/game-binary-vcs-strategy.md

@@ -2,6 +2,11 @@
 name: game-binary-vcs-strategy
 description: Git LFS deep dive, Perforce and PlasticSCM comparison, large repo tuning, lock protocols, CI for binary assets, VCS selection guide
 topics: [game-dev, vcs, git-lfs, perforce, binary-assets]
+volatility: evolving
+last-reviewed: null
+version-pin: null
+sources:
+  - url: https://git-scm.com/docs/gitattributes
 ---
 
 Game development produces enormous volumes of binary assets — textures, meshes, audio, animations, and engine-specific formats — that fundamentally break assumptions baked into distributed version control systems like Git. A single Unreal project can exceed 100 GB of binary data that cannot be diffed, merged, or compressed efficiently. Choosing the right VCS strategy, configuring it correctly, and establishing team protocols around binary file workflows is a prerequisite for any multi-person game project. The wrong choice creates daily friction that compounds into weeks of lost productivity over a production cycle.