Glossary

Every Plan Forge term defined.

Auto-generated from capabilities.mjs glossary, hand-edited for clarity.

Getting Started: Read These Five First

If you're new to Plan Forge, these five terms cover 80% of the manual. They build on each other in this order:

1. Plan Forge, the whole shop. A workshop with four stations (Smelt, Forge, Guard, Learn) that take an idea from "vague feature request" all the way to "shipped, monitored, and remembered."
2. Plan, a Markdown file in docs/plans/ that describes one feature. The unit of work Plan Forge operates on.
3. Scope contract, the section of the plan that says exactly which files are in-scope, out-of-scope, and forbidden. Without this, AI agents drift into unrelated code.
4. Slice, one numbered step inside a plan. Plans are broken into 3–7 slices so the AI works in checkpointed chunks. Each slice ends at a validation gate.
5. Validation gate, a concrete shell command (e.g., dotnet test) that must pass before the next slice runs. Gates are how Plan Forge knows the AI didn't break anything.

Read those five and you can follow the rest of the manual without backtracking. The full alphabetical reference begins below, organized by topic.

Core Concepts

Term	Definition
Plan Forge	The AI-Native SDLC Forge Shop. One workshop with four stations, Smelt, Forge, Guard, Learn, connected by gates, telemetry, and persistent memory. Covers every phase of the software lifecycle.
Forge	Shorthand for Plan Forge. Also: .forge/ directory (project data), .forge.json (config).
Plan	A Markdown file in docs/plans/ describing a feature. Contains slices, scope contract, and gates.
Hardened Plan	A plan that passed Step 2, locked-down execution contract with scope, slices, gates, forbidden actions.
Scope Contract	Plan section defining In Scope, Out of Scope, and Forbidden files. Prevents scope creep.
Slice	A 30–120 minute unit of execution within a plan. Has tasks, a validation gate, and optional dependencies. Commit-sized: small enough to catch failures early, large enough to be useful.
Validation Gate	Build + test commands that must pass at every slice boundary before proceeding.
Forbidden Actions	Files or operations the AI must not touch. Enforced by lifecycle hooks and scope checks.
Stop Condition	A condition that halts execution, e.g., "If migration fails, STOP."
Guardrails	Instruction files that auto-load based on the file being edited. 15–18 per preset.
Preset	Stack-specific configuration (dotnet, typescript, python, etc.). Determines which files are installed.
Extension	Community add-on providing instructions, agents, or prompts for a specific domain.
Self-Deterministic Agent Loop	The v2.58 system-wide model: the deterministic slice executor plus ten opt-in inner-loop subsystems (reflexion, trajectories, auto-skills, gate synthesis, postmortems, federation, reviewer, competitive execution, auto-fix, cost-anomaly). Execution stays reproducible; loop context improves each pass. See the canonical overview.
Phase	Versioned chunk of Plan Forge development. Plans live at docs/plans/Phase-N-PLAN.md. A phase contains 1+ plans; each plan contains 1+ slices. Numbering is monotonic across the project (Phase-28.2, Phase-31, etc.).
Tempering	Post-execution coverage & quality subsystem. Scans the diff with pluggable scanners (typecheck, lint, content-audit, secret-scan), classifies findings into real-bug / flaky / noise lanes, and feeds the Bug Registry. Distinct from LiveGuard (runtime defense) and the Reviewer Gate (architectural review). 5 MCP tools: forge_tempering_run/scan/status/drain/approve_baseline.
Skill	A multi-step procedure invoked from chat via a /slash-command (e.g. /code-review, /staging-deploy, /health-check). Defined as SKILL.md files under .github/skills/. Runs through forge_run_skill with its own validation gates.
Project Principles	Project-level guardrails generated by .github/prompts/project-principles.prompt.md and stored in docs/plans/PROJECT-PRINCIPLES.md. Auto-load via project-principles.instructions.md when the file exists. Define forbidden patterns, technology commitments, and architectural boundaries.
AI Plan Hardening Runbook	The canonical 7-step pipeline every plan flows through (Specify → Preflight → Harden → Execute → Sweep → Review → Ship). Master copy: docs/plans/AI-Plan-Hardening-Runbook.md.

The Four Stations

The Forge Shop's organizing taxonomy, every Plan Forge feature lives at one of these four stations.

Term	Definition
Forge Shop	The whole workshop. The collective name for the four stations and the connective tissue (gates, telemetry, memory) that ties them together.
Station	One of the four phase-specific zones in the Forge Shop. Each station has its own tools, agents, artifacts, and gate to the next station.
Act	The Manual's organizational unit. Each Act covers one station's chapters. Act I = Smelt (Ch 1–5), Act II = Forge (Ch 6–15), Act III = Guard (Ch 16–20), Act IV = Learn (Ch 21–24).
🪨 Smelt	Station 1, Intake → Scope Contract. Where rough ideas become hardened plans the Forge can execute. Houses the Specifier agent, the AI Plan Hardening Runbook, the Crucible, and Project Principles.
🔨 Forge (station)	Station 2, Scope Contract → shipped code. Where slices are struck against the anvil. Houses pforge run-plan, slice gates, quorum mode, auto-escalation, and the cost ledger.
🛡️ Guard	Station 3, Post-deploy defense. The watchtower. Houses LiveGuard (secret scan, drift, regression guard, env diff, incident capture), the Watcher, and the Remote Bridge.
🧠 Learn	Station 4, Memory and retrospectives. The brain above the bench. Houses OpenBrain, the Bug Registry, the Testbed, Health DNA, and Forge Intelligence.
Watcher	Tool (forge_watch, forge_watch_live) that tails another project's pforge run from a separate VS Code session. Read-only by contract, cannot modify the target.
Remote Bridge	Notification dispatcher that forwards hub events to Telegram, Slack, Discord, OpenClaw, or a generic webhook. Used for phone-friendly progress updates and approval prompts.
Bug Registry	Closed-loop scanner-bug tracker. Four tools, forge_bug_register, forge_bug_list, forge_bug_update_status, forge_bug_validate_fix. Records live in .forge/bugs/<bugId>.json.
Bug Fingerprint	Hash of scanner name + test name + assertion message + normalized stack trace. Re-registering a duplicate fingerprint returns DUPLICATE_BUG with the existing bugId.
Bug Status	State machine: open → in-fix → validating → fixed, with side branches to wont-fix, duplicate, and noise. Illegal transitions return INVALID_TRANSITION.
Bug Classifier	Heuristic that labels evidence as real-bug (persisted), flaky (ignored), or noise (discarded). Only real-bug writes to .forge/bugs/.
Testbed	Tool (forge_testbed_run) that replays scenario fixtures against a dedicated repo. Scenarios in docs/plans/testbed-scenarios/*.json; findings in docs/plans/testbed-findings/*.json. Feeds the Bug Registry and Health DNA.
Crucible	Smelt-station idea funnel for community extensions. Lifecycle: Submitted → Crystallized → Tempered → Hardened. Stalled Crystallized ideas surface as Watcher anomalies.

Pipeline

Term	Definition
Pipeline	The 7-step process: Specify → Preflight → Harden → Execute → Sweep → Review → Ship.
Step 0 (Specify)	Define what and why, structured specification with acceptance criteria.
Step 2 (Harden)	Convert spec into binding execution contract with slices, gates, and scope.
Step 3 (Execute)	Build code slice-by-slice. Can be automated or manual.
Step 5 (Review Gate)	Independent audit session, checks for drift, scope violations, and quality.
Step 1 (Preflight)	Verifies prerequisites before plan execution, git clean, build green, environment vars set. Ships as a prompt (.github/prompts/step1-preflight-check.prompt.md), not a separate agent persona.
Specifier	Step 0 agent persona that turns a one-line idea into a structured specification with acceptance criteria. Lives at .github/agents/specifier.agent.md.
Plan Hardener	Step 2 agent/runbook that converts a draft plan into a Hardened Plan by adding scope contract, validation gates, forbidden actions, and rollback. Lives at .github/prompts/step2-harden-plan.prompt.md.
Reviewer Gate	Step 5 agent persona that runs in a fresh session, reads the plan's Scope Contract, and audits the diff for drift and quality. Distinct from LiveGuard (runtime layer). Can be delegated to GitHub Copilot cloud agent via forge_delegate_review.
Shipper	Step 6 agent persona for commit, push, deploy, and close. Lives at .github/agents/shipper.agent.md.
Runbook (tool)	The forge_runbook MCP tool that exposes the AI Plan Hardening Runbook as a callable surface, agents can request the canonical step list, gate templates, and prompt URIs without re-reading the Markdown source.
Runbook	Bare term, in Plan Forge always refers to the AI Plan Hardening Runbook (the document) or the forge_runbook tool that exposes it. See both entries for specifics.
applyTo	Frontmatter field in instruction files that controls which files trigger auto-loading. Uses glob patterns (e.g., ** for all files, *.cs for C# only).

Execution

Term	Definition
Full Auto	Mode where gh copilot CLI runs each slice automatically. No human intervention.
Assisted	Mode where human codes in VS Code; orchestrator validates gates between slices.
Worker	The CLI process executing a slice, gh copilot, claude, or codex.
DAG	Directed Acyclic Graph, the dependency graph of slices determining execution order.
[P] tag	Parallel-safe marker on a slice header. Enables concurrent execution.
[depends: Slice N]	Dependency marker. Slice waits for N to complete before starting.
Quorum Mode	Multi-model consensus on slice execution: 3+ models analyze a slice independently, reviewer synthesizes best approach. Auto-winner. CLI: --quorum=auto/power/speed/false.
Quorum Auto	Threshold-based: only slices scoring above the complexity threshold use quorum.
Quorum Power	Multi-model consensus using flagship models (highest quality, highest cost). Complexity threshold 5. CLI: --quorum=power.
Quorum Speed	Multi-model consensus using fast models (lower quality, lower cost). Complexity threshold 7. CLI: --quorum=speed.
Quorum Advisory	Multi-model consensus on Forge-Master prompts (not slices). Returns all replies + dissent summary; human picks the reply. Configured via forgeMaster.quorumAdvisory: "off" | "auto" | "always". Hard-blocked on operational, troubleshoot, build lanes.
Complexity Score	1–10 rating based on file scope, dependencies, security keywords, gate count, historical failure rate.
Escalation Chain	Model failover order: if Model A fails, try B, then C.
Forge-Master	Read-only reasoning orchestrator with three-stage intent classifier (keyword → embedding cache → router LLM). Lives at forge_master_ask + Studio dashboard tab. Phase-28 MVP, subsequently expanded with quorum advisory and unified timeline.
Forge-Master Observer	Background hub subscriber (pforge-master/src/observer-loop.mjs) that batches live Plan Forge events and narrates notable patterns in plain prose via the reasoning loop. Mute-by-default: enable with forgeMaster.observer.enabled: true. Budget-capped via maxUsdPerDay and maxNarrationsPerHour. Started with pforge master observe --start [--detach] or the forge_master_observe MCP tool.
Cross-Run Watcher	Watcher mode (runWatch({ mode: "cross-run" })) that aggregates .forge/runs/*/summary.json across multiple completed runs into a health snapshot. Detects recurring gate failures, retry-rate spikes, cost anomaly trends, and slice-timeout clusters. Feeds the A4 plan-health auditor agent when triggered by hooks.postRun.invokeAuditor.
Auditor Auto-Invoke	PostRun hook behavior (hooks.postRun.invokeAuditor) that automatically triggers the A4 plan-health auditor on run failure (onFailure: true) or every N completed runs (everyNRuns: N). The auditor report is written to .forge/health/latest.md. See forge-json-reference § hooks.postRun.
Embedding Cache	Stage 1.5 of the Forge-Master intent classifier. Cosine-similarity match (≥ 0.85) against previously-classified prompts. Zero API cost on hit, works fully offline once warm. 500-entry LRU.
CRITICAL_FIELDS	The six fields the Crucible critical-fields gate requires before finalizing: build-command, test-command, scope, validation-gates, forbidden-actions, rollback. Added v2.82.1.
Host-Aware Routing	Routing preference that detects the IDE/CLI host (VS Code, Claude Code, Cursor, Windsurf, Zed, CLI) and chooses CLI proxy vs direct API to honor whichever subscription the user is paying for. Modes: auto / gh-copilot / direct-api / drop.
DIRECT_API_ONLY	Routing class for models with no CLI proxy: grok-*, dall-e-*. Always require an API key (XAI_API_KEY / OPENAI_API_KEY).
COPILOT_SERVABLE	Routing class for gpt-* / chatgpt-* models. gh-copilot can proxy them via your Copilot subscription; direct API is fallback if OPENAI_API_KEY is set.

Components

Term	Definition
Smith	Diagnostic tool (pforge smith). Inspects environment, setup, version. Named after a blacksmith.
Sweep	Completeness scan (pforge sweep). Finds TODO/FIXME/stub markers.
Analyze	Consistency scoring (pforge analyze). Scores 0–100 across 4 dimensions.
Orchestrator	Execution engine. Parses plans, schedules slices, spawns workers, validates gates.
Hub	WebSocket event server. Broadcasts slice events to connected clients in real-time.
Dashboard	Web UI at localhost:3100/dashboard. 25 tabs for monitoring, cost, replay, skills, config, watcher, and LiveGuard.
Lifecycle Hook	Automatic actions tied to Plan Forge's pipeline: PreDeploy, PreCommit, PreAgentHandoff, PostSlice (configured via .github/hooks/plan-forge.json). Distinct from Claude Code's own hook names.
OpenBrain	The L3 memory layer. Self-hosted MCP server (PostgreSQL + pgvector) that provides cross-session, cross-tool semantic memory. Plan Forge ships with L1 (Hub) + L2 (.forge/*.jsonl) memory built-in; L3 requires OpenBrain. Without it, Reflexion lessons, Auto-skills, cross-project Federation, and 28 auto-capturing tools become inert. Recommended at install time; easy to add later via pforge brain hint. Deploy options: Docker, Supabase, Kubernetes, Azure. See srnichols.github.io/OpenBrain.
MCP	Model Context Protocol. A standard for AI agents to call functions. Plan Forge's MCP server exposes 105 tools (core + LiveGuard + Watcher + Crucible + Tempering + Bug Registry + Testbed + Forge-Master).
ACI	Agent-Computer Interface. The SWE-agent principle that an agent only performs as well as the surface lets it: bounded payloads, sparse fields, paginated lists, friendly empty-result messages. Enforced in Plan Forge via tool-surface temper guards in architecture-principles.instructions.md. forge_search is the reference standard.
Bridge	Notification dispatcher that forwards WebSocket hub events to external platforms (Slack, Discord, Telegram, generic webhooks).
Knowledge Graph	In-memory graph of Phase / Slice / Commit / File / Run / Bug nodes, queryable via forge_graph_query. Used by Forge-Master for cross-feature reasoning. See Chapter 28.
Cost Ledger	Aggregated token + dollar history across runs (.forge/cost-history.json). Powers forge_cost_report, anomaly detection, and the cost dashboard tab.
Worktree	Git worktree feature used by Plan Forge so multiple developers can run plans on the same repo without colliding. Each worktree gets its own .forge/ directory and a row in the shared team-activity ledger.
Discovery Harness	4-pass build sequence (Harness → Wrapper → Execute → Auto-smelt) that crawls a running app, converts findings to Crucible smelts, runs slices with Tempering, and re-smelts failures into new bugs.
Spec Kit Interop	Bridge that imports GitHub Spec Kit projects via forge_crucible_import using deterministic field mapping (no LLM call). Spec Kit specs become Crucible smelts.
Foundry	Microsoft Foundry, the external Azure-hosted agent platform Plan Forge integrates with. Provides Foundry Toolboxes (MCP-compatible tool bundles), Foundry Agent Service (hosted agent runtime), and Foundry App Insights (OTel sink). See foundry-quota.mjs and the microsoft-foundry skill.
Lattice	v2.95 code-graph engine. Semantic chunk index plus BFS call-graph traversal for any git repository. Produces .forge/lattice/chunks.jsonl and edges.jsonl. Pure-JS chunker with optional tree-sitter upgrade. Five MCP tools: index / stat / query / callers / blast. CLI: pforge lattice.
Anvil	Δ-only memoization layer for the Lattice. Caches expensive analyses (chunk extraction, embedding lookups, gate replays) keyed by content hash; only recomputes the delta when source changes. CLI: pforge anvil stat / purge. Hit rate is reported by forge_lattice_stat.
Triage	Plan Forge's noise-vs-signal classifier surface. Two tools: forge_alert_triage (groups and prioritizes open LiveGuard alerts) and forge_triage_route (routes a finding to a lane, real-bug, flaky, noise, or human-review). CLI: pforge triage.
Timeline	Chronological event view exposed via forge_timeline, merges run events, gate results, commits, and incidents on a single axis for the current phase or slice.
Home Snapshot	Bounded activity overview returned by forge_home_snapshot. Pagination-friendly summary of recent runs, open bugs, drift score, and active plans, the default landing payload for Forge-Master and the Studio home tab.
Image Generation	Image synthesis surface (forge_generate_image) that proxies DALL-E / image models for chapter heroes, diagrams, and marketing assets. DIRECT_API_ONLY, requires OPENAI_API_KEY.
GitHub Metrics	Subsystem (github-metrics.mjs) that ingests PR / issue / commit metrics from the GitHub REST API and feeds them into Health DNA and Forge Intelligence. Paired with github-introspect.mjs for repo-shape introspection.

The Loops

Plan Forge nests four named loops inside its outer Self-Deterministic Agent Loop. Each loop has its own canonical chapter, entries below are the one-line cards.

Term	Definition
Inner Loop	The slice-level reasoning loop composed of the ten inner-loop subsystems (reflexion, trajectories, auto-skills, gate synthesis, postmortems, federation, reviewer, competitive execution, auto-fix, cost anomaly). Wraps every slice attempt. See Inner Loop deep dive.
Competitive Loop	Multi-model race pattern within slice execution. Two or more workers attempt the same slice in parallel; the orchestrator validates each and ships the winner. See Competitive Loop deep dive.
Audit Loop	Closed-loop bug discovery from a running system. Content-audit scanner → triage → drain cycle iterates until convergence. Default off; opt-in via .forge.json#audit.mode. Production environments hard-blocked. See Audit Loop deep dive.
Self-Deterministic Loop	Alias for Self-Deterministic Agent Loop. The system-wide outer loop that wraps the deterministic slice executor with all inner-loop subsystems.

Inner Loop Subsystems

The ten opt-in subsystems that compose the Inner Loop. Each is independently configurable; the Reviewer subsystem reuses the Step 5 Reviewer Gate agent persona (see Pipeline).

Term	Definition
Reflexion	Re-analyzes a failed slice attempt to extract a lesson learned; the lesson is persisted to memory and injected into the next attempt's context.
Trajectory	Captured record of a slice attempt (prompts, tool calls, gates passed/failed, model used, duration). Stored in .forge/trajectories/. The Inner Loop replays trajectories to learn from past runs.
Auto-skill	Auto-promotes a successful prompt pattern into a reusable Skill after 3+ uses. Generated skill lands at .github/skills/<name>/SKILL.md for human review.
Gate Synthesis	Proposes new validation gates based on observed slice failures. If three runs of the same plan fail at the same regression, Gate Synthesis suggests a gate that would have caught it.
Postmortem	Auto-generated retrospective after a failed run, written to .forge/postmortems/. Includes timeline, root cause hypothesis, and a fix proposal.
Federation	Cross-project intelligence sharing via OpenBrain. One project's lesson learned becomes another project's preflight check or postmortem hint.
Competitive Execution	Inner-loop flavor of the Competitive Loop, two models race on the same slice; first valid result wins. Cost-bounded by escalation chain policy.
Auto-fix	Proposes a 1–2 slice fix plan when a gate fails. Stored in docs/plans/auto/. Distinct from LiveGuard's Fix Proposal (which fires on post-deploy drift, not slice-time gate failure).
Cost Anomaly	Flags slices whose token cost is >2σ above their historical baseline. Triggers escalation chain review or quorum threshold adjustment.

LiveGuard

Term	Definition
Drift Score	Numeric score (0–100) measuring how closely code follows architecture guardrails. Lower = more violations.
Fix Proposal	Auto-generated 1–2 slice plan from LiveGuard findings. Stored in docs/plans/auto/.
LiveGuard	Post-coding operational intelligence layer. 14 MCP tools for drift, incidents, deploys, secrets, dependencies, and composite health checks.
MTTR	Mean Time To Resolve. Computed from incident capture to resolvedAt timestamp.
Secret Scan	Entropy-based scan of recent commits for potential hardcoded credentials.
OpenClaw	Optional external analytics service. Receives LiveGuard snapshots via POST for cross-project health monitoring.
Health DNA	Composite project health fingerprint: drift avg, incident rate, test pass rate, model success rate, cost per slice. Persisted to .forge/health-dna.json. Used for cross-session decay detection.
Forge Intelligence	Build-time self-improvement: auto-tuning escalation chains, cost calibration, adaptive quorum thresholds, slice splitting advisories. The forge gets smarter every run.
Recurring Incident	When 3+ incidents hit the same files in 30 days, LiveGuard auto-escalates severity and marks the pattern as systemic.
Deploy Journal	Append-only deploy history exposed via forge_deploy_journal. Each entry records environment, commit, slice range, gates passed, and outcome, the source of truth for "what shipped when" and the basis for rollback decisions.

Worker Guardrails

Term	Definition
PreCommit Chain	Ordered list of validation scripts declared in hooks.preCommit.chain[] that run before every slice commit.
Diff Classifier	The forge_diff_classify MCP tool that scans staged git diffs for security and quality issues.
Plan Lock Hash	SHA-256 hash stored in lockHash frontmatter; the orchestrator refuses to run if the plan body has drifted.
Tool Denylist	The tools.deny frontmatter field that strips listed MCP tools from the worker's session.
Network Allowlist	The network.allowed frontmatter field listing permitted hosts for outbound connections (currently log-only).

Data Structures

Term	Definition
Run	A single plan execution. Creates .forge/runs/<timestamp>/ with results and traces.
Trace	OTLP-compatible JSON recording the full execution with spans, events, and timing.
OTLP	OpenTelemetry Protocol, the standard format for distributed traces. Plan Forge traces are OTLP-compatible and can be exported to Jaeger, Grafana Tempo, or any collector.
Span	A timed unit within a trace, run (root), slice (child), gate (grandchild).
Cost History	.forge/cost-history.json, aggregate token/cost data across all runs.
Index	.forge/runs/index.jsonl, append-only run registry for instant lookup.
SARIF	Static Analysis Results Interchange Format, the OASIS standard JSON schema CI scanners (CodeQL, Semgrep, ESLint, etc.) emit. Plan Forge converts SARIF files into hardenable plans via sarif-to-plan.mjs, turning third-party findings into Crucible smelts.