How a development session executes

Short question rounds capture identity, stage, monetization, and the invariants — the facts no repo scan can produce. Answers land in the founder's own words as kb/normative/00-product-intent.md and 01-invariants.md (INV-1…5), provenance elicited: code changes can never invalidate them, only diverge from them.

Agents read the repo only at the pin and draft the maps every future session will lean on: strategy rationale from docs, the capability map (marketing promises vs actual handlers), data sources ("do we already have this data?"), and integrations (why each exists, which vendor capabilities are used, who depends on what). Every claim cited path:line @pin; everything enters as pending-ratification.

Brownfield code has lost its tradeoffs; the residue hasn't. assume0 harvests the scars — frozen constants, timing values, swallowed exceptions, deleted files, reverts — and an agent turns the most decision-laden into hypothesis cards: assumption, evidence, implicitly rejected alternative, cost if wrong, and one question the founder can answer in a sentence.

dup0 + linters harvest candidates; an agent classifies them — contradiction, duplicate-debt, deliberate variation, or noise — and drafts proposed conventions. A norm binds only once ratified: rejected norms are recorded too, so no agent proposes them again.

The batches land in QUEUE.md as numbered, evidence-anchored questions — a sitting of twenty answers, not an essay. speccraft-ratify walks them: facts promote to ratified, hypotheses get killed on the record, divergences get ruled (fix-code | fix-model | accepted-deviation) into ledger/. From here the ratchet is closed: the steady-state loop below keeps the KB honest commit by commit.

The agent opens in the repo and learns the KB exists before writing a line. Claude Code gets a live SessionStart injection; Codex and OpenCode read the same facts from AGENTS.md → .speccraft/KB-STATUS.md, which the ship loop keeps current as of the last commit.

Before touching a module, the agent walks the memory palace: anchors on every KB fact are matched against the files about to change, returning facts in trust order. Ratified facts are restated as constraints in the plan. NO COVERAGE on a risk path is a stop sign — check the data-source and integration maps for existing capability, record the gap, then proceed.

Normal coding. In Claude Code, every Edit/Write on a product file fires a PostToolUse hook that injects the anchored facts for exactly that file — including into subagents, which prose instructions can't reach. Attempts to edit founder lanes are denied at edit time. Codex and OpenCode rely on the procedures plus the git guard downstream.

speccraft-decide: the moment a tradeoff is made — a threshold fixed, a failure tolerated, an alternative rejected — it lands as an append-only ADR in .speccraft/kb/decisions/. "Arbitrary" is a valid rationale; invented ones are not. speccraft-diverge: if the task conflicts with a ratified fact, the conflicting part stops, the divergence is filed in QUEUE.md with evidence, and a TODO(speccraft-diverge #N) marks the hole. Sessions never self-ratify.

The pre-commit lane guard runs for every tool and every human. Staged changes to kb/normative/, kb/derived/, or ledger/ are rejected unless the commit carries KB_RATIFY=1 (a founder ruling) or KB_SHIPLOOP=1 (the loop's own re-pin). Prose instructions can be ignored; this cannot.

Human-paced, not commit-paced. The founder walks QUEUE.md — divergences, confrontation batches, staleness flags — one item at a time, highest consequence first. Rulings land in their lanes: facts promote to kb/normative/, divergences to ledger/DIV-* with fix-code | fix-model | accepted-deviation, conventions gain scope. The commit carries KB_RATIFY=1, and every future session's stage 0 inherits the result. This is the only door into ratified truth.