Concepts & Glossary

How to read this guide

Scaffold's other guides each go deep on one system; this one is the map of the vocabulary they share. Every term below gets a short definition and a link to the guide that owns the full story. When two guides use the same word slightly differently (a "verdict" in MMR vs. in the audit engine; a "lens" that lives in the audit but reasons about the knowledge base), this guide is where the seam is named.

Terms cluster into four families:

• Pipeline — how an idea becomes a build-ready spec.
• Observability — the durable record of what the build actually did.
• Review — how independent models gate changes.
• Multi-agent — how parallel worktrees coordinate without stepping on each other.

Pipeline concepts

These describe the meta-prompt pipeline that turns an idea into a frozen, build-ready spec. Full treatment: the pipeline guide.

Phase

One of the 16 ordered stages the pipeline divides into, numbered 0 (vision) through 15 (build). The phase list, slugs, numbers, and display names are defined exactly once, in the PHASES constant src/types/frontmatter.ts:6; every doc, skill, and command resolves against it. Steps within a phase run in order sequence (phase N occupies the N00–N99 band). See the pipeline guide.

Planning vs. build regime

The pipeline splits into two regimes. Planning (phases 0–14) is stateful and sequential — each step produces a durable artifact and is run roughly once, in dependency order, working toward a frozen spec. Build (phase 15) is stateless and on-demand — the execution loops you run repeatedly while actually writing code. See the pipeline guide.

dependencies (hard gate)

A step's frontmatter dependencies src/types/frontmatter.ts:114 are hard gates: scaffold run refuses a step until each dependency is completed, skipped, or disabled by the resolved pipeline/overlay (a disabled dep counts as satisfied). Contrast reads. See Why a step is blocked.

reads (soft reference)

A step's reads src/types/frontmatter.ts:122 are soft references — a step uses an upstream artifact if it's present, but a missing read never blocks execution (the assembler silently skips it). The pipeline guide explains why reads ≠ dependencies is a common trip-up.

Conditional / if-needed

A step marked conditional: 'if-needed' src/types/frontmatter.ts:118 is enabled but only applies to certain project shapes (e.g. database-schema runs only if your project has a database layer). Conditional steps that don't apply count as "satisfied" for dependency purposes. See Conditional steps.

Stateless step

A phase-15 build step with stateless: true src/types/frontmatter.ts:126 — it carries no completion state and can be run over and over (the agent loops, resume commands, quick-task, new-enhancement). The pipeline never tracks or gates these. See the pipeline guide.

CREATE vs. UPDATE mode

Every document-creating prompt detects whether its output file already exists. On first run it's CREATE mode; on a re-run it's UPDATE mode, which preserves human/team customizations and changes only what genuinely needs to change. This is what makes planning phases safe to iterate. See CREATE vs UPDATE mode.

Methodology preset

Which steps are enabled. Three presets ship — mvp, custom (balanced), and deep (the schema default and most thorough). Presets are layered with overlays. See Methodology & depth.

Depth (1–5)

How thorough each enabled step's output is, on a 1–5 scale from Minimal to Exhaustive (depth 3 is the recommended default). Orthogonal to the preset: the preset picks the steps, depth dials each one's detail. At depth 4–5 some review/validation steps add external- or multi-model dispatch. See Depth.

Overlay

A preset layer (content/methodology/*-overlay.yml) applied on top of a preset. Overlays are either project-type (keyed by project-type, e.g. web-app, mobile, CLI, library) or structural (e.g. multi-service, which has no project-type and is activated by the presence of services[] in config). Most overlays only inject domain knowledge into existing steps; a few enable whole step families (game, multi-service). See Project-type playbooks.

Observability concepts

These describe Build Observability — the durable record of what the build did, and the audit that checks it against the planning docs. Full treatment: the build observability guide.

Ledger

The append-only .scaffold/activity.jsonl file where every durable observation lands as one JSON object per line. Writes are lock-guarded so parallel worktrees never corrupt it, each event is capped at 4 KiB, and secrets and home paths are redacted on the way in and out. See The ledger.

Event

One typed entry in the ledger, written via scaffold observe event <type> …. There are nine event types src/observability/engine/types.ts:9 (task_claimed, task_completed, decision_recorded, blocker_hit, blocker_resolved, pr_opened, progress_heartbeat, finding_acknowledged, knowledge_gap_signal), each with its own payload allow-list. See The nine event types.

Adapter

A component that synthesizes events from the surrounding tools (git, GitHub, MMR jobs, pipeline state, test runs) so the timeline reflects more than what agents chose to record. Eight adapters exist src/observability/engine/types.ts:69; five emit replay events, three are availability probes. See Adapters.

Lens (A–I)

An independent audit check function inside scaffold observe audit. The suite runs nine lenses, A through I — TDD coverage, AC coverage, coding-standards drift, tech-stack drift, design-system drift, scope, decisions, cross-doc consistency, and knowledge gaps. Lenses A–G run under --scope code, H and I under --scope docs. See The nine-lens audit. Lens I (I-knowledge-gaps) lives in the audit but reasons about the knowledge base — its full behavior is in the knowledge-freshness guide.

Finding

A single issue a lens reports, carrying a severity (P0–P3), a title, a source doc, and an optional fix hint. Findings can be open, acknowledged (silenced via scaffold observe ack), or skipped (a lens whose required adapter was missing). See The nine-lens audit.

Audit verdict

The overall result of an audit run. The engine computes exactly three verdicts src/observability/engine/types.ts:6: pass (no blocking findings, no skipped lenses), degraded-pass (no blocking findings but ≥1 lens skipped), and blocked (≥1 open finding at or above fix_threshold). Note this is not the same set as MMR's four verdicts — see MMR verdict. See Verdict taxonomy.

fix_threshold

The severity cutoff that decides which findings count as blocking. A finding blocks when its status is open and its severity is at or above the threshold (default P2). The threshold never hides findings — it only decides which ones drive a blocked verdict. The same name and default govern the MMR gate. See fix_threshold and the MMR gate.

--fix flow

scaffold observe audit --fix doesn't just report blocking findings — it dispatches an agent to fix each one, verifies the fix with a single-lens re-audit, and writes a post-fix report, all under abort-safe stashing. See The --fix flow.

Stall signal

A staleness alert raised on the "Needs Attention" surface when scaffold observe progress runs — e.g. a claimed task with no recent activity, a PR that hasn't merged, an unaddressed blocker. Six signals are defined; five fire today. Thresholds are configurable under stall: in .scaffold/observability.yaml. See Stall detection.

Phase-boundary audit

A non-gating cross-document audit that fires automatically when a planning document at a phase boundary is marked complete. It runs only the H-cross-doc lens at scope=docs, prints a one-line summary, and never blocks the state transition. The six boundary steps are user-stories, tech-stack, coding-standards, design-system, implementation-plan, and implementation-playbook. See Phase-boundary triggers and the pipeline view.

doc-conformance channel

The seam where the audit plugs into multi-model review: a built-in MMR channel that runs scaffold observe audit --output-mode=mmr-findings and emits findings in MMR's Finding shape. Disabled by default; enable with --channels=doc-conformance. See MMR doc-conformance channel and the MMR channel architecture.

Knowledge concepts

These describe the knowledge base and how it stays current. Full treatment: the knowledge-freshness guide and the knowledge guide.

Knowledge entry

A domain-expertise document under content/knowledge/<category>/<slug>.md, injected into prompts during assembly. Each declares a name, volatility tier, and a list of sources. See the knowledge guide and Adding a new entry.

Volatility tier

How often an entry is expected to drift, on a three-tier scale — fast-moving, evolving (default), stable — which sets the daily cron's re-audit cadence (14 / 60 / 180 days). See the cadence model.

Knowledge-gap signal

A knowledge_gap_signal ledger event emitted when an agent hits a topic the KB doesn't cover. Lens I aggregates these over a rolling 90-day window into P1/P2 findings, suppressing any topic an entry already covers. This is where the observability and knowledge-freshness systems meet. See How a gap closes.

Review concepts

These describe Multi-Model Review (MMR). Full treatment: the MMR guide and the review-workflow guide.

Channel

One independent AI reviewer in an MMR run — a separate subprocess given the same prompt and run in isolation. The built-in channels are codex, gemini, claude, grok, and the opt-in doc-conformance; the scaffold run wrappers add a Superpowers code-reviewer agent channel. A channel is pure config data, not per-channel code. See Channel architecture.

Compensating pass

When a channel is degraded (not installed, auth-failed, timed out), MMR runs a claude -p pass focused on that channel's strength area, labeled e.g. [compensating: Grok-equivalent]. These findings are single-source and low-confidence. See Degraded mode.

Reconcile

The step that groups every channel's findings by a stable key, de-duplicates them, and scores each group for agreement and confidence — producing the single list and verdict. Agreement between channels raises confidence; disagreement surfaces ambiguity. mmr reconcile also folds an external agent channel's findings into an existing job. See Findings, reconciliation & verdicts.

finding_key

The stable identity MMR computes for a finding so the same issue can be tracked across rounds and acknowledgments. Line numbers are stripped from the location and severity is excluded, so the same issue at P1 vs. P2 collapses to one key; a character-5-gram shingle backs a fuzzy match for re-worded findings. See Stable identity.

MMR verdict

The gate result of a review. MMR computes four verdicts: pass, degraded-pass, blocked, and needs-user-decision (no channel completed). Proceed only on pass or degraded-pass.

Multi-agent concepts

These describe how parallel agents share a repo without colliding. Full treatment: the multi-agent guide, with the durable record covered in the observability guide.

Worktree

An isolated git working tree used for parallel agent execution, so multiple agents (and humans) can build different parts of a project at once without sharing a checkout. Each worktree has its own ledger. See the multi-agent guide.

Worktree identity

The stable per-worktree identity recorded in .scaffold/identity.json on first write — a worktree_id (UUID), a worktree_label, and created_at. It's what lets the harvester tell one worktree's events from another's, and what stamps every event's worktree_id. See Worktree identity.

Ledger harvest

Copying a worktree's local ledger into the primary repo's archive before the worktree is removed, so the build's reasoning survives teardown. harvest --recover separately rotates already-harvested stale entries from .scaffold/activity-archive/active/ into the monthly YYYY-MM.jsonl archives when their worktree is no longer live — it does not rescue an unharvested ledger; that ledger is lost once the worktree is removed. See Harvest, recover & teardown.

Teardown

Removing a finished worktree the safe way — scripts/teardown-agent-worktree.sh harvests the ledger first, then runs git worktree remove, then deletes the workspace branch. Harvesting before removal is what closes the decisions-die-at-teardown gap. See Harvest, recover & teardown.

See also

• The Scaffold Pipeline — phases, dependencies, presets, depth.
• Build Observability — ledger, events, the nine lenses, verdicts, --fix.
• Knowledge Freshness — volatility tiers, gap signals, Lens I.
• MMR Reference — channels, reconciliation, the four verdicts.
• Multi-agent — worktrees and parallel execution.
• Review workflow — running reviews end to end.
• CLI reference — the full command surface.