@zigrivers/scaffold 3.27.0 → 3.29.0

package/content/knowledge/core/git-workflow-patterns.md

@@ -2,6 +2,14 @@
 name: git-workflow-patterns
 description: Git branching strategies, commit conventions, PR workflows, merge policies, and CI integration patterns for AI-agent-driven development
 topics: [git, branching, commits, pull-requests, ci-cd, merge-strategy, worktrees]
+volatility: stable
+last-reviewed: null
+version-pin: null
+sources:
+  - url: https://git-scm.com/docs/git-worktree
+    anchor: '#_description'
+  - url: https://www.conventionalcommits.org/en/v1.0.0/
+    anchor: '#specification'
 ---
 
 # Git Workflow Patterns

package/content/knowledge/core/multi-model-research-dispatch.md

@@ -2,6 +2,12 @@
 name: multi-model-research-dispatch
 description: Patterns for dispatching research and adversarial challenge to external AI models (Codex, Gemini) with reconciliation rules and single-model fallback
 topics: [multi-model, research, competitive-analysis, red-team, codex, gemini, dispatch, reconciliation]
+volatility: fast-moving
+last-reviewed: null
+version-pin: null
+sources:
+  - url: https://ai.google.dev/gemini-api/docs
+  - url: https://docs.anthropic.com/en/docs/claude-code/cli-reference
 ---
 
 # Multi-Model Research Dispatch

package/content/knowledge/core/multi-model-review-dispatch.md

@@ -2,6 +2,12 @@
 name: multi-model-review-dispatch
 description: Patterns for dispatching reviews to AI CLI tools (Codex, Gemini, Claude), including fallback strategies and finding reconciliation
 topics: [multi-model, code-review, codex, gemini, claude, review-synthesis]
+volatility: fast-moving
+last-reviewed: null
+version-pin: null
+sources:
+  - url: https://ai.google.dev/gemini-api/docs
+  - url: https://docs.anthropic.com/en/docs/claude-code/cli-reference
 ---
 
 # Multi-Model Review Dispatch

package/content/knowledge/core/multi-service-api-contracts.md

@@ -2,6 +2,11 @@
 name: multi-service-api-contracts
 description: Internal API versioning, backward compatibility, retries, and idempotency patterns
 topics: [internal-api-versioning, backward-compatibility, retries, idempotency, contract-evolution]
+volatility: evolving
+last-reviewed: null
+version-pin: 'RFC 9110'
+sources:
+  - url: https://www.rfc-editor.org/rfc/rfc9110
 ---
 
 ## Summary

package/content/knowledge/core/multi-service-architecture.md

@@ -2,6 +2,11 @@
 name: multi-service-architecture
 description: Service boundary design, communication patterns, service discovery, and networking topology
 topics: [service-boundaries, communication-patterns, service-discovery, networking-topology, data-ownership, sync-vs-async]
+volatility: evolving
+last-reviewed: null
+version-pin: null
+sources:
+  - url: https://docs.aws.amazon.com/whitepapers/latest/microservices-on-aws/microservices-on-aws.html
 ---
 
 ## Summary

package/content/knowledge/core/multi-service-auth.md

@@ -2,6 +2,12 @@
 name: multi-service-auth
 description: Mutual TLS, service tokens, zero-trust architecture, and audience scoping
 topics: [mtls, service-tokens, zero-trust, audience-scoping, token-rotation]
+volatility: evolving
+last-reviewed: null
+version-pin: 'RFC 6749 / OIDC Core 1.0'
+sources:
+  - url: https://www.rfc-editor.org/rfc/rfc6749
+  - url: https://openid.net/specs/openid-connect-core-1_0.html
 ---
 
 ## Summary

package/content/knowledge/core/multi-service-data-ownership.md

@@ -2,6 +2,14 @@
 name: multi-service-data-ownership
 description: Table ownership, shared-nothing data patterns, and event-driven synchronization
 topics: [table-ownership, shared-nothing, event-driven-sync, data-partitioning, eventual-consistency]
+volatility: evolving
+last-reviewed: null
+version-pin: null
+sources:
+  - url: https://martinfowler.com/articles/microservices.html
+    anchor: '#DecentralizedDataManagement'
+  - url: https://microservices.io/patterns/data/database-per-service.html
+    anchor: '#solution'
 ---
 
 ## Summary

package/content/knowledge/core/multi-service-observability.md

@@ -2,6 +2,14 @@
 name: multi-service-observability
 description: Distributed tracing, correlation IDs, cross-service SLOs, and failure attribution
 topics: [distributed-tracing, correlation-ids, cross-service-slos, failure-attribution]
+volatility: evolving
+last-reviewed: null
+version-pin: 'OpenTelemetry 1.x'
+sources:
+  - url: https://opentelemetry.io/docs/specs/otel/
+    anchor: '#overview'
+  - url: https://www.w3.org/TR/trace-context/
+    anchor: '#traceparent-header'
 ---
 
 ## Summary

package/content/knowledge/core/multi-service-resilience.md

@@ -2,6 +2,11 @@
 name: multi-service-resilience
 description: Circuit breakers, bulkheads, timeout budgets, and failure isolation strategies
 topics: [circuit-breakers, bulkheads, timeout-budgets, failure-isolation, retry-storms]
+volatility: evolving
+last-reviewed: null
+version-pin: null
+sources:
+  - url: https://docs.aws.amazon.com/wellarchitected/latest/reliability-pillar/welcome.html
 ---
 
 ## Summary

package/content/knowledge/core/multi-service-task-decomposition.md

@@ -2,6 +2,14 @@
 name: multi-service-task-decomposition
 description: Breaking multi-service work into per-service implementation waves
 topics: [per-service-waves, dependency-ordering, parallel-implementation, shared-infrastructure-first]
+volatility: stable
+last-reviewed: null
+version-pin: null
+sources:
+  - url: https://martinfowler.com/articles/microservices.html
+    anchor: '#OrganizedAroundBusinessCapabilities'
+  - url: https://microservices.io/patterns/decomposition/decompose-by-business-capability.html
+    anchor: '#solution'
 ---
 
 ## Summary

package/content/knowledge/core/multi-service-testing.md

@@ -2,6 +2,11 @@
 name: multi-service-testing
 description: Consumer-driven contract testing, cross-service E2E strategies, and service test doubles
 topics: [contract-tests, pact, schema-registry, cross-service-e2e, test-doubles]
+volatility: evolving
+last-reviewed: null
+version-pin: null
+sources:
+  - url: https://docs.pact.io/
 ---
 
 ## Summary

package/content/knowledge/core/operations-runbook.md

@@ -2,6 +2,14 @@
 name: operations-runbook
 description: Deployment pipeline, deployment strategies, monitoring, alerting, and incident response
 topics: [operations, ci-cd, deployment, monitoring, incident-response, alerting, rollback]
+volatility: evolving
+last-reviewed: null
+version-pin: null
+sources:
+  - url: https://sre.google/sre-book/table-of-contents/
+    anchor: '#part-iii-practices'
+  - url: https://sre.google/workbook/table-of-contents/
+    anchor: '#incident-response'
 ---
 
 ## Summary

package/content/knowledge/core/project-structure-patterns.md

@@ -2,6 +2,10 @@
 name: project-structure-patterns
 description: Directory layout patterns by framework, module organization, and file placement rules
 topics: [project-structure, directory-layout, module-organization, file-placement, monorepo, colocation]
+volatility: stable
+last-reviewed: null
+version-pin: null
+sources: []
 ---
 
 # Project Structure Patterns

package/content/knowledge/core/review-step-template.md

@@ -2,6 +2,10 @@
 name: review-step-template
 description: Shared template pattern for review pipeline steps including multi-model dispatch, finding severity, and resolution workflow
 topics: [review, template, multi-model, quality-gates, methodology]
+volatility: stable
+last-reviewed: null
+version-pin: null
+sources: []
 ---
 
 # Review Step Template

package/content/knowledge/core/security-best-practices.md

@@ -2,6 +2,12 @@
 name: security-best-practices
 description: OWASP Top 10, authentication, authorization, data protection, and threat modeling
 topics: [security, owasp, authentication, authorization, threat-modeling, secrets-management, dependency-auditing]
+volatility: fast-moving
+last-reviewed: null
+version-pin: 'OWASP Top 10 2021'
+sources:
+  - url: https://owasp.org/Top10/
+    anchor: '#top-10-list'
 ---
 
 ## Summary

package/content/knowledge/core/system-architecture.md

@@ -2,6 +2,12 @@
 name: system-architecture
 description: Architecture patterns, component design, and project structure
 topics: [architecture, components, modules, data-flow, project-structure, state-management]
+volatility: stable
+last-reviewed: null
+version-pin: null
+sources:
+  - url: https://martinfowler.com/articles/microservices.html
+  - url: https://microservices.io/patterns/index.html
 ---
 
 ## Summary

package/content/knowledge/core/task-decomposition.md

@@ -2,6 +2,11 @@
 name: task-decomposition
 description: Breaking architecture into implementable tasks with dependency analysis and agent context
 topics: [tasks, decomposition, dependencies, user-stories, parallelization, sizing, critical-path]
+volatility: stable
+last-reviewed: null
+version-pin: null
+sources:
+  - url: https://github.com/steveyegge/beads
 ---
 
 # Task Decomposition
@@ -12,7 +17,7 @@ Expert knowledge for breaking user stories into implementable tasks with depende
 
 ### Story-to-Task Mapping
 
-User stories bridge PRD features and implementation tasks. Each story decomposes into tasks following the technical layers needed. Every task must trace back to a user story, and every story to a PRD feature (PRD Feature → US-xxx → Task BD-xxx).
+User stories bridge PRD features and implementation tasks. Each story decomposes into tasks following the technical layers needed. Every task must trace back to a user story, and every story to a PRD feature (PRD Feature → US-xxx → Task bd-<id>).
 
 ### Task Sizing
 
@@ -146,9 +151,9 @@ Every task must trace back to a user story, and every user story must trace to a
 ```
 PRD Feature: User Profile Management
   -> US-002: Edit display name and bio
-    -> Task BD-42: implement PATCH /api/v1/users/:id
-    -> Task BD-43: add profile edit form component
-    -> Task BD-44: add profile edit page with state management
+    -> Task bd-a3f8: implement PATCH /api/v1/users/:id
+    -> Task bd-a3f9: add profile edit form component
+    -> Task bd-a3fa: add profile edit page with state management
 ```
 
 This traceability ensures:

package/content/knowledge/core/task-tracking.md

@@ -2,6 +2,14 @@
 name: task-tracking
 description: Task tracking patterns including Beads methodology, task hierarchies, progress tracking, and lessons-learned workflows
 topics: [task-management, beads, progress-tracking, lessons-learned, autonomous-work]
+volatility: evolving
+last-reviewed: null
+version-pin: null
+sources:
+  - url: https://github.com/steveyegge/beads
+    anchor: '#beads'
+  - url: https://martinfowler.com/bliki/UserStory.html
+    anchor: '#task-tracking'
 ---
 
 # Task Tracking
@@ -18,7 +26,9 @@ Core properties:
 - **Repository-local** — Task data lives in `.beads/`, committed alongside code
 - **Git-hook synced** — Task state updates automatically on commit via data-sync hooks
 - **CLI-driven** — All operations via `bd` commands (create, list, status, ready)
-- **ID-prefixed commits** — Every commit message includes `[BD-xxx]` for traceability
+- **ID-prefixed commits** — Every commit message includes `[bd-<id>]` for traceability
+
+> IDs are hash-based and lowercase (e.g., `bd-a3f8`). The `bd-` prefix is configurable at `bd init` time. Hierarchical IDs for epic children: `bd-a3f8.1`, `bd-a3f8.1.1`. Older example IDs in this doc using `BD-42`-style uppercase digits reflect a pre-v1.0.0 convention; current upstream emits hash-based lowercase IDs.
 
 ### Task Hierarchy
 
@@ -34,18 +44,24 @@ Epics group related tasks. Tasks are the unit of work assignment — one task pe
 
 ### Progress Tracking
 
-Track task status through a simple state machine:
+Beads tracks task status through this state machine (upstream v1.0.4 enum):
 
+```text
+open → in_progress → closed       (happy path)
+            ↓
+        blocked | deferred         (off-path)
 ```
-ready → in-progress → review → done
-                  ↘ blocked
-```
 
-- **ready** — All dependencies met, can start immediately
-- **in-progress** — Agent is actively working on it
-- **review** — Implementation complete, awaiting PR merge
-- **done** — PR merged, tests passing on main
-- **blocked** — Cannot proceed, dependency or question unresolved
+- **open** — Not started.
+- **in_progress** — Atomically claimed via `bd update <id> --claim` or `bd ready --claim`.
+- **blocked** — Dependency unresolved (set automatically when a `blocks:` dep exists on an open issue).
+- **deferred** — Hidden from `bd ready` until `--defer` date passes.
+- **closed** — Completed (via `bd close <id>`). Reopen with `bd reopen <id>`.
+- **pinned** / **hooked** — Special states; rarely set manually.
+
+Beads also exposes a *status category* dimension (`active | wip | done | frozen`) for higher-level grouping. Use `bd state <id>` to query, `bd statuses` to list valid statuses.
+
+> Scaffold previously documented `ready → in-progress → review → done` — none of those (except via `ready` as a *query*) are upstream statuses. The `review` state, if needed, can be added per-project via `bd config set types.custom_statuses '[{"name":"review","category":"wip"}]'`.
 
 ### Lessons-Learned Workflow
 
@@ -70,7 +86,7 @@ bd init              # Creates .beads/ directory with data store and git hooks
 Initialization creates:
 - `.beads/` — Data directory (committed to git)
 - Git hooks for automatic data sync (these are Beads data hooks, not code-quality hooks like pre-commit linters)
-- Initial `[BD-0]` bootstrap convention
+- Initial `[bd-<id>]` bootstrap convention (lowercase hash-style)
 
 #### Core Commands
 
@@ -78,25 +94,26 @@ Initialization creates:
 |---------|---------|-------------|
 | `bd create "title"` | Create a new task | Starting new work |
 | `bd list` | Show all tasks | Session start, planning |
-| `bd status BD-xxx` | Check task state | Before picking up work |
-| `bd start BD-xxx` | Mark task in-progress | Beginning work on a task |
-| `bd done BD-xxx` | Mark task complete | After PR merged |
+| `bd show <id>` | Inspect full task (alias `bd view`) | Before picking up work |
+| `bd update <id> --claim` | Atomically claim (assigns to you + sets `in_progress`) | Beginning work on a task |
+| `bd ready --claim --json` | Find and claim first ready task in one call | Picking next task with no preference |
+| `bd close <id>` (alias `bd done`) | Mark task complete | After PR merged |
 | `bd ready` | List tasks ready to start | Picking next task |
-| `bd block BD-xxx "reason"` | Mark task blocked | When dependency is unmet |
+| `bd update <id> --status blocked` | Mark task blocked | When dependency is unmet |
 
 #### Commit Message Convention
 
 Every commit references its Beads task:
 
 ```
-[BD-42] feat(api): implement user registration endpoint
+[bd-a3f8] feat(api): implement user registration endpoint
 
 - Add POST /api/v1/auth/register
 - Add input validation with zod schema
 - Add integration tests for happy path and validation errors
 ```
 
-The `[BD-xxx]` prefix enables:
+The `[bd-<id>]` prefix enables:
 - Automatic task-to-commit traceability
 - Progress tracking based on commit activity
 - Session reconstruction (which commits belong to which task)
@@ -108,13 +125,13 @@ The `[BD-xxx]` prefix enables:
 1. Review `tasks/lessons.md` for recent patterns and corrections
 2. Run `bd ready` to see available tasks
 3. Pick the highest-priority ready task (or continue an in-progress task)
-4. Run `bd start BD-xxx` to claim the task
+4. Run `bd update <id> --claim` to atomically claim the task (or skip step 2-3 and just `bd ready --claim --json`)
 5. Read the task description and acceptance criteria before writing code
 
 #### Session End Protocol
 
-1. Commit all work with `[BD-xxx]` prefix
-2. If task is complete: create PR, run `bd done BD-xxx`
+1. Commit all work with `[bd-<id>]` prefix (lowercase hash-style)
+2. If task is complete: create PR, run `bd close <id>` (alias: `bd done`)
 3. If task is incomplete: leave clear notes about current state and next steps
 4. If lessons were learned: update `tasks/lessons.md`
 
@@ -124,7 +141,7 @@ A task is done when:
 - All acceptance criteria from the task description are met
 - Tests pass (`make check` or equivalent)
 - Code follows project coding standards
-- Changes are committed with proper `[BD-xxx]` message
+- Changes are committed with proper `[bd-<id>]` message
 - PR is created (or merged, depending on workflow)
 
 Do not mark a task done based on "it seems to work." Prove it works — tests pass, logs clean, behavior verified.
@@ -184,14 +201,14 @@ For complex projects, maintain a progress summary:
 # Progress
 
 ## Current Sprint
-- [x] BD-10: Database schema migration (done)
-- [x] BD-11: Auth middleware (done)
-- [ ] BD-12: User registration endpoint (in-progress)
-- [ ] BD-13: Login endpoint (ready)
-- [ ] BD-14: Profile management (blocked — needs BD-12)
+- [x] bd-a1b2: Database schema migration (done)
+- [x] bd-a1b3: Auth middleware (done)
+- [ ] bd-a3f8: User registration endpoint (in_progress)
+- [ ] bd-a3f9: Login endpoint (open, ready to pick up)
+- [ ] bd-a3fa: Profile management (blocked — needs bd-a3f8)
 
 ## Blocked
-- BD-14: Waiting on BD-12 (user model finalization)
+- bd-a3fa: Waiting on bd-a3f8 (user model finalization)
 ```
 
 #### Completion Criteria Checklists
@@ -199,7 +216,7 @@ For complex projects, maintain a progress summary:
 Each task should define explicit completion criteria, not vague goals:
 
 ```markdown
-## BD-12: User registration endpoint
+## bd-a3f8: User registration endpoint
 
 ### Done when:
 - [ ] POST /api/v1/auth/register endpoint exists
@@ -218,8 +235,90 @@ Each task should define explicit completion criteria, not vague goals:
 
 **Missing lessons.** The user corrects the same mistake three sessions in a row because nobody captured it in `tasks/lessons.md`. Fix: treat lesson capture as mandatory, not optional. After every correction, update the file before continuing with other work.
 
-**Task ID drift.** Commits stop including `[BD-xxx]` prefixes partway through the project. Traceability breaks down. Fix: make task ID inclusion a habit enforced by review. If using a pre-commit hook, validate the prefix.
+**Task ID drift.** Commits stop including `[bd-<id>]` prefixes partway through the project. Traceability breaks down. Fix: make task ID inclusion a habit enforced by review. If using a pre-commit hook, validate the prefix.
 
 **Overloaded tasks.** A single task covers "implement the API, write the UI, add tests, update docs." This overflows a single session and makes progress tracking meaningless. Fix: split into tasks that each fit in one agent session (30-90 minutes).
 
 **Lessons without rules.** A lesson says "we had trouble with X" but doesn't state a preventive rule. Future sessions read the lesson but don't know what to do differently. Fix: every lesson must include a concrete rule — "Always do Y" or "Never do Z" — not just a description of what went wrong.
+
+### Agent context: `bd prime` is the SSOT
+
+Beads ships `bd prime` as the single source of truth for workflow context injected into agent sessions. The default output is ~1-2k tokens and includes:
+- Current ready/in-progress task counts
+- The next 1-2 ready tasks with full descriptions
+- Recent activity (last few closed/updated)
+- Persistent memories set via `bd remember`
+
+Variants:
+- `bd prime` — full default
+- `bd prime --memories-only` — just persistent memories (very small)
+- `bd prime --full` — extended context (use sparingly; ~5k tokens)
+- `bd prime --hook-json` — Claude Code SessionStart hook envelope
+
+Override the default output by writing `.beads/PRIME.md` (Markdown, free-form). The `bd setup claude` / `bd setup gemini` recipes wire `bd prime --hook-json` into SessionStart hooks for you — you don't typically invoke it by hand.
+
+`bd onboard` emits a one-line snippet you can paste into any agent context file to remind it about `bd prime`.
+
+### Two memory scopes — when to use which
+
+Scaffold-generated projects have two persistent memory layers when `.beads/` exists:
+
+- **Filesystem auto-memory** (per-user, cross-project) — facts about you the developer. Stored under `~/.claude/projects/.../memory/` by the Claude Code client.
+- **`bd remember`** (per-project, team-shareable) — facts about this project. Stored in `.beads/embeddeddolt/`, committed with the repo.
+
+For project-level facts that should travel with the repo (in-flight context, team conventions, project-specific blockers, decisions), use `bd remember` instead of filesystem memory. See `content/knowledge/core/ai-memory-management.md` for the full scope split table.
+
+### Editor integration via `bd setup` recipes
+
+Beads ships built-in setup recipes that write the integration block into CLAUDE.md, AGENTS.md, GEMINI.md, or `.cursor/rules/` for you, using marker-managed format that survives re-runs:
+
+- `bd setup claude` — Claude Code (writes CLAUDE.md block + SessionStart/PreCompact hooks)
+- `bd setup codex` — Codex CLI (writes `.agents/skills/beads/SKILL.md` + AGENTS.md section)
+- `bd setup gemini` — Gemini CLI (writes GEMINI.md section + hooks)
+- `bd setup cursor` / `bd setup windsurf` / `bd setup aider` / `bd setup factory` / `bd setup mux` — other editors
+
+Each recipe is idempotent (re-running it does not duplicate content), reversible (`--remove`), and verifiable (`--check`). Recipe choice determines profile (claude/gemini default to `minimal` ~60% smaller; codex/factory/mux default to `full`). There is no runtime `--profile` flag in v1.0.4 — recipe choice is the knob.
+
+Custom recipes can be added via `bd setup --add <name> <path>`, persisted in `.beads/recipes.toml`.
+
+### Optional: enable custom issue types
+
+`bd create -t` supports `bug`, `feature`, `task`, `epic`, `chore`, `decision` out of the box. To use `story`, `milestone`, or `spike`, enable them via project config:
+
+```bash
+bd config set types.custom '["story", "milestone", "spike"]'
+```
+
+After that, `bd create -t story "US-XXX: …"` works as expected.
+
+### Production option: off-site backup
+
+Beads can push a versioned mirror to filesystem, S3, GCS, Azure Blob, or DoltHub:
+
+```bash
+bd backup init s3://my-bucket/beads-backup/
+bd backup sync     # push current DB
+bd backup restore  # bring it back if needed
+```
+
+Worth setting up for any project where task state matters beyond the developer's laptop.
+
+### When to use the MCP server (rarely)
+
+Beads ships a Python MCP server (`beads-mcp`) for clients that don't have shell access — e.g., Claude Desktop, some IDE plugins. Install:
+
+```bash
+uv tool install beads-mcp   # or: pip install beads-mcp
+```
+
+For Claude Code, Cursor, Windsurf, and any agent with shell access, **CLI + hooks is preferred** — it's ~1-2k tokens of context (via `bd prime`) vs 10-50k for the MCP tool schemas. Only reach for `beads-mcp` when shell access isn't available.
+
+### Safe re-initialization
+
+If you need to re-init a Beads database (e.g., migrating to a fresh prefix, recovering from corruption), use the explicit flags rather than `--force`:
+
+- `bd init --reinit-local` — bypass the local-exists guard
+- `bd init --discard-remote` — explicitly authorize discarding remote Dolt history
+- `bd init --destroy-token DESTROY-<prefix>` — required in non-interactive mode for destructive re-init
+
+Stable exit codes: `10` (remote divergence), `11` (local exists), `12` (destroy-token missing). The legacy `--force` flag still works but is deprecated.

package/content/knowledge/core/tech-stack-selection.md

@@ -2,6 +2,14 @@
 name: tech-stack-selection
 description: Framework evaluation methodology, decision matrices, and technology tradeoff analysis
 topics: [tech-stack, framework-selection, decision-matrix, tradeoffs, scalability, ecosystem]
+volatility: fast-moving
+last-reviewed: null
+version-pin: null
+sources:
+  - url: https://www.thoughtworks.com/radar
+    anchor: '#technology-radar'
+  - url: https://martinfowler.com/articles/microservice-trade-offs.html
+    anchor: '#evaluating'
 ---
 
 # Tech Stack Selection

package/content/knowledge/core/test-skeleton-generation.md

@@ -2,6 +2,10 @@
 name: test-skeleton-generation
 description: Patterns for translating acceptance criteria into framework-specific test skeleton files
 topics: [testing, test-generation, acceptance-criteria, tdd, test-skeletons]
+volatility: stable
+last-reviewed: null
+version-pin: null
+sources: []
 ---
 
 # Test Skeleton Generation

package/content/knowledge/core/testing-strategy.md

@@ -2,6 +2,14 @@
 name: testing-strategy
 description: Test pyramid, testing patterns, coverage strategy, and quality gates
 topics: [testing, tdd, test-pyramid, quality-gates, coverage, test-data, mocking]
+volatility: stable
+last-reviewed: null
+version-pin: null
+sources:
+  - url: https://martinfowler.com/articles/practical-test-pyramid.html
+    anchor: '#TheTestPyramid'
+  - url: https://martinfowler.com/bliki/TestDouble.html
+    anchor: '#test-doubles'
 ---
 
 # Testing Strategy

package/content/knowledge/core/user-stories.md

@@ -2,6 +2,14 @@
 name: user-stories
 description: Expert knowledge for translating product requirements into well-formed user stories
 topics: [user-stories, personas, acceptance-criteria, story-splitting, INVEST, epics, traceability]
+volatility: stable
+last-reviewed: null
+version-pin: null
+sources:
+  - url: https://martinfowler.com/bliki/UserStory.html
+    anchor: '#user-story'
+  - url: https://www.agilealliance.org/glossary/user-stories/
+    anchor: '#user-stories'
 ---
 
 # User Stories
@@ -293,7 +301,7 @@ Every PRD feature must map to at least one user story. This is a non-negotiable
 - Loading states, empty states, and offline behavior are often implied but not stated
 
 **Traceability notation:**
-- Use IDs to create a traceable chain: PRD-REQ-001 → US-001 → (downstream: Task BD-42)
+- Use IDs to create a traceable chain: PRD-REQ-001 → US-001 → (downstream: Task bd-a3f8)
 - Story IDs (US-001, US-002, ...) are stable — they persist through updates and are referenced by downstream phases
 
 ### Story Dependencies

package/content/knowledge/core/user-story-innovation.md

@@ -2,6 +2,10 @@
 name: user-story-innovation
 description: Techniques for discovering UX enhancements and innovation opportunities in user stories
 topics: [innovation, ux-enhancements, user-stories, gap-analysis, differentiators]
+volatility: stable
+last-reviewed: null
+version-pin: null
+sources: []
 ---
 
 # User Story Innovation

package/content/knowledge/core/ux-specification.md

@@ -2,6 +2,11 @@
 name: ux-specification
 description: UX documentation patterns — user flows, interaction states, component architecture, accessibility, and responsive behavior
 topics: [ux, accessibility, wireframes, user-flows, responsive-design, components, interaction-states]
+volatility: stable
+last-reviewed: null
+version-pin: null
+sources:
+  - url: https://www.w3.org/WAI/standards-guidelines/wcag/
 ---
 
 # UX Specification

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

@@ -2,6 +2,11 @@
 name: data-pipeline-architecture
 description: Lambda vs Kappa architecture tradeoffs, medallion architecture (bronze/silver/gold), and CDC patterns for data pipelines
 topics: [data-pipeline, architecture, lambda, kappa, medallion, bronze-silver-gold, cdc, change-data-capture]
+volatility: stable
+last-reviewed: null
+version-pin: null
+sources:
+  - url: https://martinfowler.com/bliki/DataLake.html
 ---
 
 Data pipeline architecture is the set of structural decisions that determine how data flows from sources to consumers, how it is stored at each stage, and how historical data is reprocessed when logic changes. The wrong architecture creates systems that are either operationally complex (Lambda), too rigid for historical reprocessing (pure streaming), or without clear data quality boundaries (no medallion layers). These decisions are expensive to reverse and must be made explicitly.

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

@@ -2,6 +2,10 @@
 name: data-pipeline-batch-patterns
 description: DAG design, partitioning strategies, incremental loads, backfill strategies, and dependency management for batch data pipelines
 topics: [data-pipeline, batch, dag, partitioning, incremental-load, backfill, dependency-management, airflow]
+volatility: stable
+last-reviewed: null
+version-pin: null
+sources: []
 ---
 
 Batch pipeline design decisions — DAG structure, partition strategy, incremental load mechanics, and backfill tooling — determine whether a pipeline is operationally maintainable or a constant source of incidents. Most batch pipeline failures stem from four root causes: missing idempotency, no backfill support, poorly managed upstream dependencies, and partitioning strategies that don't match query access patterns. Address all four up front.

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

@@ -2,6 +2,10 @@
 name: data-pipeline-conventions
 description: Naming conventions, error handling patterns, idempotency, and dead-letter queue patterns for data pipelines
 topics: [data-pipeline, conventions, naming, error-handling, idempotency, dead-letter, patterns]
+volatility: stable
+last-reviewed: null
+version-pin: null
+sources: []
 ---
 
 Data pipeline conventions are the shared language that makes a pipeline system maintainable across teams and time. Inconsistent naming, absent idempotency guarantees, and ad-hoc error handling are the top causes of data corruption and operational incidents. Establish and enforce these conventions from day one — retrofitting them onto running production pipelines is expensive and risky.

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

@@ -2,6 +2,10 @@
 name: data-pipeline-dev-environment
 description: Local development setup with Docker, sample data generation, replay tooling, and test fixtures for data pipelines
 topics: [data-pipeline, dev-environment, docker, local-development, sample-data, replay, test-fixtures]
+volatility: evolving
+last-reviewed: null
+version-pin: null
+sources: []
 ---
 
 A productive data pipeline development environment must run locally without requiring cloud accounts, production credentials, or access to real data. Engineers must be able to ingest, process, debug, and test the full pipeline on their laptop in under 10 minutes from a clean checkout. This requires containerized dependencies, synthetic sample data, and tooling to replay specific scenarios.