-
Notifications
You must be signed in to change notification settings - Fork 0
Glossary
Quick reference for terms used throughout the docs and source.
Adaptive timeout — the timeout value computed for each run_command invocation from .cadillac/cmd_history.jsonl past p95 × 2.5, clamped to 600s. Replaces hardcoded --timeout 30 flags.
Adversarial test — a test written by a second LLM pass specifically designed to break the implementation. Lives in .cadillac/adversarial/test_adversarial.py. Targets the "LLM tests its own code" blind spot.
add_dep — the single sanctioned post-scaffold tool for modifying dependency manifests. Policy-gated through inspector.coerce_version.
apply_proposal — the improve cycle's atomic patch application. Git-applies a proposal's diff, runs unit tests, reverts on regression.
Architecture text — the markdown design doc produced by PLAN phase round 1. Persisted to <workspace>/architecture.md. Feeds the manifest-generation prompt in round 2.
BUILD phase — the main implementation loop. The LLM reads errors, edits files, runs tests, repeats. Most of a build's wall time lives here.
build.jsonl — .cadillac/build.jsonl. Append-only event log: every phase, every tool call, every LLM round-trip. The dashboard tails this.
Budget — a phase's round cap, computed by compute_budgets() from past p90 × 1.2 of matching tagged builds, falling back to DEFAULT_BUDGETS when no history exists.
check_status — LLM tool that reports current phase, round, file count, validation mix.
Code map — the workspace's source rendered into a single string that fits the LLM's context budget. Has three tiers:
- Tier 1 (AST): function/class signatures with docstring summaries
- Tier 2 (regex): import lines + class/function names with line numbers
- Tier 3 (raw): file paths and sizes only
CodeMapBuilder picks the highest-fidelity tier that fits the budget.
Commissioning — Inspector tier 3: end-to-end smoke. Does the entry point load? Does --test dispatch? Does the project compile?
Completeness CRITIC — see CRITIC.
Contract — <workspace>/contracts.json. A flat list of API endpoints (method, path, request shape, response shape) that frontend and backend layers import from. Eliminates contract drift.
CRITIC — phase that audits "did we build what the spec said?". Runs after VALIDATE green. Two-stage: static keyword prefilter + LLM second opinion. Bounces missing features back to BUILD.
Dashboard — the zero-service TUI invoked via python3 -m cadillac dash. Browses past + live builds. Read-only filesystem access.
Decay (lesson) — confidence reduction applied automatically to lessons older than 90 days. Prevents long-tail lessons from staying authoritative forever.
Decomposing — the "D" in CADILLAC. Modular pipeline for 15+ file projects: plan → topologically-sorted modules → dependency waves → per-module scoped executors.
DEPS phase — pip install / npm install / cargo build to fetch declared dependencies.
Endpoint — in contracts.py: one HTTP route with method + path + module + request shape + response shape. In runtime/http: a probe target.
EndpointUnreachable — exception raised by chat() when all 3 retries to the LLM endpoint failed with pure connection errors (refused, DNS fail, unreachable host). Distinct from sentinel-empty-message for HTTP 5xx / timeout (those indicate alive-but-busy, may recover).
Enhance — CLI mode that treats an external codebase as the workspace and iterates BUILD → VALIDATE until clear. For modifying existing projects rather than creating from scratch.
Event — one row in build.jsonl. Has a kind (phase, llm, tool, validation, lesson, ...) and a typed payload.
Fingerprint — a stable identifier for a validation failure: check_name:file:line:error_class. Same fingerprint across retries → stuck-loop detection → surgical mode.
Fix mode — the BUILD state after a retreat_to_build() retreat. run_command is disabled for the first round so the LLM must edit_file first.
Flat pipeline — single-manifest pipeline used when project is <15 files. One executor, one phase loop.
Flow — a runtime-verification HTTP chain. Multiple FlowSteps with capture + assertion.
Functional smoke — VALIDATE check #9. AST-verifies __init__.py re-exports point at real symbols.
Improve cycle — see Improve Cycle. The closed-loop self-improvement: audit + probe + correlate + propose + apply.
Inspector — cadillac/inspector.py. Three-tier policy enforcement at phase boundaries: materials (deps), wiring (cross-file), commissioning (end-to-end smoke).
INTEGRATE phase — modular-pipeline-only. After modules are built, glue them together: top-level entry point, integration tests, shared config.
Iterate — CLI mode that re-runs BUILD → VALIDATE on an existing workspace with an optional new instruction.
Lesson — one row in memory.jsonl. Has type, trigger, fix, polarity (do/dont), tags, confidence, source_task, used count.
Live UI — the Rich-based terminal display that renders during builds. Phase bar + file tree + activity log + validation mix.
Manifest — <workspace>/plan.json. The list of files cadillac plans to write, with declared module structure (in modular builds) and dependency edges.
Materials — Inspector tier 1: dependency version policy. No "*", no Vite 7+ on Node 18, etc.
Meta-lesson — a lesson tagged [cadillac, self] written by the improve cycle's commit_applied() when a patch lifts the matrix score ≥0.05.
Modular pipeline — multi-manifest pipeline used when project is 15+ files. Each module gets its own scoped executor, scratch, code map.
note_lesson — LLM tool that writes to .cadillac/scratch.md. Categories: tried_failed, working_pattern, reminder.
Operational gates — VALIDATE check #7. Schema integrity (static) + missing-env (runtime) + SIGTERM responsiveness (runtime).
PACKAGE phase — final phase. Writes README + requirements/package.json. Trivial — rarely fails.
Phase — one of the 12 named pipeline stages. cadillac/phases.py:Phase enum.
Phase history — phase_budgets.jsonl. Cross-build record of (phase, rounds_used, n_files, tags). Drives adaptive budgets.
Phase state — PhaseState dataclass holding current phase, round counters, retry counts, tier state, stuck-loop fingerprints.
PLAN phase — first build phase. Round 1: architecture markdown. Round 2+: manifest JSON (flat or modular).
Polarity — lesson field: "do" (positive pattern) or "dont" (anti-pattern).
Probe — base dataclass for runtime verification: HTTP Flow, CLI ScriptedRun, library UsageExample all inherit.
Progress — <workspace>/progress.md. Human-readable phase trace updated per round.
Progressive tiers — see Progressive tiers. Build in must → must+should → could waves.
Recall — memory.recall(task). Score-and-rank lessons for the current task. Tag filter + keyword overlap + recency + confidence + cross-task decay.
retreat_to_build() — the standard backward jump from VALIDATE to BUILD on validation failure. Increments validate_retries.
retreat_to_plan() — harder reset, used for irrecoverable architecture errors.
REVIEW phase — adversarial critique on the scaffolded code, before BUILD. Findings inform BUILD; soft phase (no hard fail).
Round — one iteration of the phase loop. Each round is one LLM call + tool-call processing.
RUNTIME phase — see RUNTIME. Drives real flows against the live artifact post-CRITIC.
SCAFFOLD phase — write stub files in dependency-sorted order. Establishes the project skeleton.
Scope (tier) — current SPEC subset the build is targeting: must, must+should, or must+should+could.
Scratch — <workspace>/.cadillac/scratch.md. The LLM's within-build notepad. Re-injected into system prompt every 3 rounds.
ScriptedRun — CLI runtime verification probe. argv + stdin + expected exit code + stdout assertions.
source_task — Lesson field added 2026-05-26. The originating task text that produced this lesson, truncated to 200 chars. Used by recall for cross-task decay.
SPEC phase — pre-PLAN. LLM expands the task into 15-40 stories (must/should/could).
Story — one user-visible capability. Fields: id, title, acceptance, priority, category.
Stuck-loop detection — see Surgical mode. Same fingerprint 3× in a row → switch strategy.
Surgical mode — focused single-file edit triggered by stuck-loop detection. ~500 token context vs the usual 30K. Augmented for undefined name errors with workspace-wide grep.
Tag — Lesson field. Set of language/framework/phase keywords. Used by recall() for filtering.
Tier — see Progressive tiers. A priority slice of the spec.
Tier-1 codemap — AST-based. Highest fidelity. Shows function/class signatures with docstring summaries.
Tier-2 codemap — regex-based. Medium fidelity. Shows imports + class/function names + line numbers.
Tier-3 codemap — raw paths only. Lowest fidelity. Used when project is too large to fit even Tier 2 into context budget.
used — Lesson field. Count of times this lesson has been recalled and applied. Reinforced by boost_confidence.
VALIDATE phase — runs the 12-check gate. Triggers retreat to BUILD on any error-severity failure.
Validation gate — see Validation Pipeline. The 12 checks: stdlib_conflicts, imports, static_names, syntax, lint, security, operational, framework, functional, run, smoke_run, tests.
Wave — in modular pipelines: a group of modules with no inter-dependencies that can be built in parallel.
WIRING phase — cross-layer HTTP smoke for full-stack builds. Boots backend on a free port, probes contract endpoints from a synthetic non-loopback Origin.
Workspace — ~/sandbox/workspace-YYYYMMDD-HHMMSS/. One per build. Contains source files + .cadillac/ state dir.
Zero services — design intent. Cadillac has no daemon, no port, no background process. State is in JSONL files on disk. Press q and nothing remains.
- Architecture — how these terms fit together
- FAQ — design rationale