bareloop 0.8.0 → 0.10.0

package/bareloop.context.md

@@ -98,6 +98,7 @@ the step plan at run time (gated by `validatePlan`); the human signs only:
 | `goal` | non-empty text | what the agent plans against |
 | `verdictType` | `green` \| `soft-green` \| `hitl` | declared radio, never inferred (`VERDICT_TYPES`, frozen). v1 ADMITS only `green`; declaring `soft-green`/`hitl` reds `request-red` with the type as a structured `verb` field (declared-but-locked — the tool-menu pattern). Every `request-red` also carries `lib` — the territory the demand lands against, stamped at the emit site (`verdictType` → `bareloop`, a locked tool verb → `bare-agent`): the ledger keys and its `suggestedAsk` seed on it, so a bareloop-catalogue refusal never files as an upstream ask |
 | `close` | **an ORDERED LIST of named stages** `[{ name, cmd, expect, judged?, gapKeep?, offer?, needs? }, ...]` (PRD v1.28), or a close object (table below) **only** for the declared-but-locked verdict classes | the destination, the only thing hand-authored; the check menu DERIVES from it (below). The plan flow executes a staged close directly and adapts a bare `predicate` object into a one-stage list; a `gold`/`rubric`/`hitl` object close validates (the declared-but-locked verdict classes still parse) but the plan flow refuses it at runtime as `close-unsupported` — it names no command to run |
+| `closeDecl` | **the AUTHORED close** `{ genre: "TYPES", lang: "js"\|"python", stages: [{ name, kind, params }], notes? }` | the ALTERNATIVE to `close`, and the point of the close-authoring rung: the user answers an interview and an LLM composes a DECLARATION over kinds whose implementations we own — never a script, never a shell fragment, never a new kind. **`close` and `closeDecl` are alternatives**: declaring both reds `close-duplicated` (two closes are two arbiters). It is HARD-class by construction (`CLASS_BY_CLOSE.declared`), so a locked verdict on one reds `close-hierarchy` as well as `request-red`. The declaration is validated by `validateCloseDecl`; the TREE-GROUNDED half of that gate (the path rule, and the scoped-job derivation that arms the F84 one-population law) is DEFERRED at spec-validation time — a job spec is validated with no repository in hand — and the runner re-runs it GROUNDED against the real seed before any stage and before any token. It stores the counting RULE and never a number (D12): there is no seed field, and `baseline: "seed"` is measured at each run's own HEAD |
 | `checks` | **RETIRED** (PRD v1.28/v1.32) | hand-authored checks are gone, not merely discouraged: declaring `checks` reds `checks-derived` by name. The check menu is DERIVED from the close's own stages instead — see **Staged close** below. The hazard this removes is measured, not theoretical: job #5's three hand-written checks were re-implementations of three stages the close already ran, and a hand-carved copy can drift LENIENT (the worker passes the operator's ruler and fails the real inspection) |
 | `tools` | optional unique subset of `TOOL_MENU` (14 verbs, below) | the CEILING every plan step's grant must fit inside (omitting it means the full menu — and the hash is taken over that RESOLVED form, so a `TOOL_MENU` widening flips an omitted-`tools` spec's hash and forces a re-sign; see `jobSpecHash`, MED-1); `run` is `LOCKED_TOOLS` and reds `request-red` — locked-but-listed, and the red IS the admission evidence the ledger tallies (a typo stays `invalid-value`). A ceiling of write-class and store-class verbs ONLY reds `invalid-value`: the scout surveys read-only, so it would be handed an empty menu and survey blind |
 
@@ -293,6 +294,14 @@ N−1 are enforced only at the close, at the end of the run. That is a COST shap
 hole — the close still refuses a tree that fails any stage, and nothing green is minted mid-run
 — but a stage first tested at the tail is a stage the run pays full price to discover.
 
+**The ceiling of 2 is RULED, not provisional (2026-08-13, PRD v1.63 §3).** One check per write
+step is the contract: a step passing its own in-run check is never a verdict, only the close is
+truth, and widening the ceiling so a step's own gate could approximate the close would move
+judgement into the part the agent authors. Plan around one check; do not plan for a second one
+arriving. It is raised only on a demonstrated starvation case (a real run where a step provably
+cannot express its progress gate within one check and stalls for it), never for wording comfort,
+and the change is the operator's — arbiter territory.
+
 Red vocabulary (both validators): `parse-error`, `unknown-field`, `missing-required`,
 `invalid-value`, `bounds`, `duplicate-id`, `close-type`, `close-hierarchy`,
 `secret-literal`, `scope-escape`,
@@ -306,9 +315,12 @@ on refusals). It binds WRITES, not observations: on the exit side it fires only
 the narrow one does), and `artifact-written`/`json-valid` paths carry no step-scope red at
 all — the evaluator asks nothing about who wrote the file, so naming a prior step's artifact
 is legal and satisfiable. `job-invalid` — a plan validated against a
-missing or non-plan-shape job fails CLOSED). `stageClose(close)` is the ONE staging
-every check-menu consumer shares (array → itself; legacy object predicate → its
-one-stage list, named `close`; gold/rubric/hitl → null). The `secret-literal` sweep is
+missing or non-plan-shape job fails CLOSED). `closeStagesOf(job)` is the ONE staging
+every check-menu consumer shares — it reads whichever close field the spec carries:
+`closeDecl` → its declared stages (each enriched with the arbiter's own `gapKeep`), else
+`stageClose(close)` (array → itself; legacy object predicate → its one-stage list, named
+`close`; gold/rubric/hitl → null). A consumer reading `close` alone would see a declared
+job as closeless and offer the drafter an empty check menu. The `secret-literal` sweep is
 defense-in-depth against known token shapes — env-only loading remains the law, not the
 sweep.
 
@@ -449,7 +461,169 @@ retired-but-accepted, so a plan carries no iteration bound to check; `scopes` is
 `tree-changed` scope menu — the array of scope strings the drafter prompt listed, which
 `runJob`/`runPlan` build internally from the signed fence plus the real directories beneath
 it (a direct `validatePlan` caller may pass its own array); omitted, it derives from the
-signed `writeScope` alone, never a free-text fallback. Menus exported: `EXIT_TYPES`, `MAX_EXITS_PER_STEP`, `MAX_PLAN_STEPS`, `WRITE_VERBS` — plus `stageClose`.
+signed `writeScope` alone, never a free-text fallback. Menus exported: `EXIT_TYPES`, `MAX_EXITS_PER_STEP`, `MAX_PLAN_STEPS`, `WRITE_VERBS` — plus `stageClose` and `closeStagesOf`.
+
+### Close authoring — the user declares what done means (`src/kinds.js`, `src/authoring.js`, `src/authorscout.js`, `src/authorflow.js`, `src/declaredclose.js`, `src/authorjob.js`)
+
+The one layer where a human still wrote code. A close used to be a hand-written script
+per patient; now the user PICKS A VERDICT CLASS, answers that class's questions, and an LLM
+composes a DECLARATION over kinds whose implementations bareloop owns. **v1 admits exactly
+ONE genre** (`TYPES`: a type checker stops complaining without breaking the tests) and
+exactly one verdict class (`green`) — everything else refuses honestly, and every refusal
+is COUNTED.
+
+**The verdict class is the USER's answer (PRD v1.57 §1), and it DRIVES the authoring.**
+`verdictType` is a declared radio the preflight validates, never inferred:
+`VERDICT_CLASSES` = `green` | `soft-green` | `hitl`, with `LOCKED_CLASSES` =
+`soft-green` | `hitl` declared-but-locked. Picking a locked one returns a counted
+`request-red` refusal at ADMISSION — before that class's questions are ever asked. The
+pick is also a PROMISE: every catalogue kind carries the `verdictClass` it can honestly
+render, `closeCeiling(declaration)` reports the highest class a declaration demands, and a
+declaration ABOVE the pick is a `class-ceiling` red naming the kind that raised it (inert
+in v1 by construction — every live kind is mechanical).
+
+**The pipeline, in call order.** Each piece is exported so an adopter can drive it, cache
+a step, or test it without a provider.
+
+| step | call | what it is |
+|---|---|---|
+| interview | `runInterview({ verdictType, answers, repoPath })` → `{ ok, answers, verdictType, refusal, reds }` | PURE — no model, no repo, no clock. THREE frozen question sets keyed by verdict class (`QUESTION_SETS`; `questionsFor(cls)` / `requiredAnswersFor(cls)`), and the interview asks NOTHING about a genre. The green set is six questions, answers keyed by number; the soft-green and hitl sets are named but LOCKED (`questions: null`, absent rather than empty) and their selection refuses before they run. `verdictType` and `repoPath` are STRUCTURED input, never parsed out of prose. Answers are scrubbed at INGEST |
+| survey | `runAuthorScout({ workdir, provider, attempts?, ceilingUsd? })` → `{ state, facts, reason, meta, raw, raws, calls, budgetStop }` | a bounded READ-ONLY LLM survey. Read-only by MENU CONSTRUCTION (`AUTHOR_SCOUT_VERBS` = the full menu minus write-class and store-class verbs), 8 rounds, F59's reserved toolless final round. **`state: 'ABSENT'` means the scout did not complete — never "no special facts are needed"**, and a parsed `{}` is one of its five ABSENT routes. Up to `SCOUT_ATTEMPTS` (**3**, hardcoded — PRD v1.58) attempts: `attempts` is TIGHTEN-ONLY and CLAMPS rather than throws (floor **1**, because a scout that never ran is an ABSENT nobody can act on), the direction every cap in this system runs in. **A retry fires on the typed MALFORMED class alone** (`SCOUT_RETRY_CAUSES` = `empty` \| `unparseable`); what is excluded is excluded for a reason — `call-failed` covers transport and `truncated:max_tokens`, both provider-red with NO redraft; `short` is F59's cut-off population and already has its own instrument INSIDE the attempt; `non-object` and `empty-object` are valid JSON with wrong or vacuous content, which is a SEMANTIC failure, and F38/F39 measured what re-asking one buys (the same distribution, sampled twice) — that is the self-healing line, and it is not crossed here. The re-ask is TOOLLESS over the conversation the survey already produced (the repository was already read; only the emission was unreadable) and names the mechanical parse error and nothing else. **There is no JSON repair behind it and there never will be** — a repairer decides what the model MEANT and writes it down as though the model had said it, in the one artefact whose whole job is to be honest about what a repository contains. `meta.attempts` / `meta.attemptsAllowed` record what was paid for; every attempt is metered under its own label (`author-scout`, `author-scout#2`, …) and leaves its raw behind. **`ceilingUsd` is the operator's money ceiling** (PRD v1.62) — checked BETWEEN attempts and before F59's reserved round, so no paid call escapes it; `null`/absent is UNBOUNDED, and a non-null non-finite value THROWS (the shared `capStop` seam — see `authorClose` below). When it ends the ladder, `budgetStop` names which stop (`cap-halt` \| `pricing-red`) and a survey that was never asked for carries the typed cause `not-funded` — deliberately OUTSIDE `SCOUT_RETRY_CAUSES`, because a retry is precisely what the cap forbade |
+| listing | `buildSeedListing({ workdir, seedRef, sourcePaths, testPaths })` | mechanical, `$0`, no model. `files` is the WHOLE tree (what the validator judges paths against); `block` is scoped to the survey's own paths and capped in ANNOUNCED tiers (what the prompt carries). Handing the validator the scoped half would make a job scoped to `src/` read as whole-tree and silently disarm the one-population law |
+| authoring | `authorClose({ workdir, seedRef, lang, verdictType, answers, scout, listing, generate, ceilingUsd? })` | the grounded loop: author → validate → run EVERY stage at the seed → feed the MEASURED results back → revise, bounded at `MAX_REVISIONS` (2) — a passed `maxRevisions` is TIGHTEN-ONLY, so a caller may LOWER that ceiling and never buy more revise rounds than the constant (floor **0**: one authoring call with no revise round is a legal ask, and unlimited revising would launder thrash as adaptation) — early-stop on an unchanged declaration. The declaration is emitted through a SCHEMA-FORCED TOOL CALL (`declare_close`), never parsed out of prose; the feedback is EXECUTION OUTPUT only — no model ever reviews another model's close. The return carries **`raws`**: what every model call actually SAID, the scout's attempts absorbed together with the declaration's, in the cost book's own order and under the same labels it meters. Each is `{ label, attempt, bytes, trimmed, text, cause, reason }` through the ONE persist helper (`scrubRaw` — redacted over the ONE `SECRET_PATTERNS` inventory, since a raw is the record most likely in this system to carry a live credential; bounded at `RAW_PERSIST_MAX` (8000) with the trim ANNOUNCING its own full size, and the cut walked back off a continuation byte so a multi-byte character is never split). `raws` is present on EVERY path **including the `$0` preflight refusals** — the path that spends nothing more is exactly the one whose evidence used to vanish with the process. `iterations` records what each turn MEANT (declaration, validation, seed read); `raws` records what it SAID, and a malformation is only ever visible in the second. **`ceilingUsd` is the same operator ceiling the survey took** — the scout's spend is ABSORBED into this loop's cost book before its first call is weighed, so spend already incurred folds in and re-entering cannot silently widen it. It is checked immediately before EVERY paid call (the author call, each revise, and each malformed-emission retry). **A MALFORMED ceiling is an ERROR, not a silent unbounded run** (v1.64 §3): the seam every ceiling read goes through (`capStop`, `src/text.js`) THROWS on a non-null non-finite value — `'2.50'`, `NaN`, `Infinity`, `true`, `{}` — before the first paid call, and the throw propagates uncaught rather than being caught into an ABSENT survey, because a caught one would hand you the very silent-unbounded run it exists to prevent. `null`/omitted is the STATED operator choice for unbounded; `0` and negatives are finite, legal, and cap-halt immediately. The advertised ceiling and the enforced ceiling can therefore never be different numbers. A `cap-halt` here can arrive with `ok:true` — a close that was already validated and measured survives the money stop, exactly as a late provider casualty does |
+| everything above, composed | `authorCloseForJob({ verdictType, answers, repoPath, lang, generate, ceilingUsd?, ... })` → `{ ok, closeDecl, verdictType, refusal, cost, ... }` | refuses at the cheapest gate that can refuse: an interview refusal costs **zero**. THE GENRE REFUSAL LIVES HERE (not in the interview): a language the catalogue owns no data for, and a LOCKED KIND the model reached for, both come back as counted `request-red` demand. **`ceilingUsd` is ONE number handed to BOTH paid seams** (the survey's and the declaration loop's) — the advertised ceiling and the enforced ceiling are the same ceiling. It travels as an EXPLICIT `null` when unset, because unbounded is a stated choice and an absent field read as falsy is that state reached by accident — and anything that is neither a finite number nor `null` throws at the seam rather than becoming that state by typo |
+| assembly | `assembleSpec(specDraft, { closeDecl, verdictType })` | folds the authored half into the OPERATOR's half. Budgets, the fence, cadence, escalation and the provider are never authored by anything here. The GOAL is passed through, not generated. **A draft that ALREADY carries the authored half is REFUSED — it THROWS, never merges and never overwrites.** `AUTHORED_SPEC_FIELDS` (`close`, `closeDecl`, `verdictType`) names the fields this fold WRITES, as data, so the refusal and the fold cannot disagree about which half of the spec is which; the rule is `job.js`'s one step earlier (two closes are two arbiters, and picking one silently is how a signed artefact stops meaning what the signer read). `scripts/run-author.mjs` asks the same question at **$0 BEFORE the scout**, so the answer never arrives after the model has been paid |
+| the three gates | `prepareSigning({ spec, workdir, seedRef? })` → `{ ok, specHash, gates, work, guards, refusal }` | D9, and it NEVER signs |
+
+**D5 — the mandatory guards are SHOWN and FIXED, and the battery keys off the VERDICT
+CLASS** (PRD v1.57 §2 — what a battery is FOR is the class of dishonesty that class of
+verdict admits). `CLASS_BATTERIES` is the attachment point (structure, un-removability,
+which slot is the model's); the tool-specific CONTENTS — which suppression patterns, which
+extensions — resolve at COMPOSITION from the language the declaration names. The green
+battery injects `changed-from-seed`
+and `no-suppressions` FULLY PARAMETERISED (`classGuards({ verdictType, lang })`, which
+THROWS rather than ever hand back an empty battery for a known class and language); the
+model fills exactly one
+slot (the target prefixes) and cannot change, drop, rename, re-kind or NARROW them —
+`validateDeclaration` reds `guard-weakened` on any of it, including on an added `scope` that
+would shrink what the suppression scan covers. `genreEnv(lang, { sourcePrefixes })` is the
+same idea for environment: `MYPYPATH` on a Python patient is a fact no user can supply and
+no model found, it moves no seed number, and a declaration that authors it itself reds
+`genre-owned-env`.
+
+**The kind catalogue** (`KIND_CATALOGUE`, and it IS the whole vocabulary): `command-exit`,
+`count-not-worse`, `pattern-absent-in-diff`, `files-changed` are live; `judged-floor` and
+`human-confirms` are NAMED BUT LOCKED (and carry `verdictClass` `soft-green`/`hitl`), so
+declaring one is a counted `locked-kind` red rather than an unknown-kind typo; `harness-loop` (TESTGEN) is ABSENT from v1 entirely. In
+tool mode a locked kind is INEXPRESSIBLE — the schema carries one branch per live kind — so
+that demand arrives through the interview layer instead (`refuseLockedKind(kind)`).
+
+**A red `count-not-worse` gap carries the LINES it counted, not only how many (F98).** Each
+term's **KEPT** matched lines nest under that term's own breakdown row — the row that already
+prints its `contributes +n`/`-n`, so a line's arithmetic role travels with it. Kept means the
+lines that survived the scope filter and were actually read by the aggregate (a `first` term
+echoes only the line that produced its value), which is to say the ones the count is made of.
+A scope-DROPPED line is never among them (it was never counted, so naming it would aim the
+worker outside its own population, F84's one-population law), duplicates collapse within a
+term (a line feeding two terms plays two roles and appears under each), and the value is
+still computed from the parsed values and never from this list.
+They ride the **existing** gap channel and invent none: the declared stage's `gapKeep` prefix
+on every line (Layer R's `redKeep` is DERIVED from that prefix), the same `GAP_LINE_CAP`, and
+the same announced trim on overflow — so a consumer parsing the gap sees more lines under the
+same shape, never a new one. `parseValue` returns them as `matched` alongside `value`,
+per-term, index-aligned with the breakdown. The
+licence is the one `pattern-absent-in-diff` already runs under: the instrument NAMED these
+lines, and echoing what it named is not the barred move of naming a culprit it never
+reported. **Nothing here can flip a signed spec hash** — the verdict logic, the baselines,
+the counting, the `closeDecl` schema and `detail` are untouched; only what the executor TELLS
+the worker changed.
+
+**The three gates, and the signature (D9).** Nothing LLM-judges a close.
+1. `validateCloseDecl(closeDecl, { verdictType, ... })` — schema, kinds, params, the F84
+   one-population law, F49's static nested-quantifier reject, the D5 guard equality, the
+   class ceiling, and the listing rule (a declared path SELECTS from the seed tree or it
+   does not exist). `verdictType` is REQUIRED and has no default: the guard battery hangs
+   off it, and a validator with no class in hand reds `class-absent` rather than reporting
+   a declaration it never checked D5 against.
+2. the CLOSE PRECHECK — every stage runs against the real patient. A stage that cannot run
+   is `broken-close`: a CASUALTY, never a red.
+3. the SEED-VERDICT READ — every stage, offered or not, at the seed. Which are RED (that is
+   the work) and which are GREEN (those are the guards) is handed back for the user to read.
+   **A close with no WORK stage red at seed is refused decision-ready** — it grades nothing,
+   and an instrument that scans nothing reads clean exactly like one that measures correctly.
+
+**KNOWN LIMIT: gate 1 does not check a parser's FORMAT, and never will (F94, ruled WON'T-BUILD
+2026-08-13, PRD v1.63 §1).** A declaration can name the right stage, over the right population,
+with the right aggregate, and carry a `lineMatch` for a shape the tool never prints. Detecting
+that at draft time needs stage → tool attribution, and `npm run typecheck` defeats it
+mechanically: the declared command names npm, what prints is `tsc`, and the mapping lives in a
+`package.json` the validator does not read. A detector that resolved some spellings and passed
+the rest would read as coverage while being blind exactly where patients differ. **Gates 2 and 3
+are the instrument for this class, and they work** — a term matching nothing over a non-empty
+population reads unknown-not-zero (F6/F45/F93), so the seed-verdict read refuses it at $0 before
+a signature, which is how the real case was caught. Formats are checked by RUNNING the tool,
+never by reading a string. The complementary defence is upstream of the gate: for the tools the
+genre owns facts about, `genreInstruments` hands the author the measured pattern (with its real
+captured line) instead of asking, so fewer declarations reach gate 1 carrying an invented format
+at all. Reopens only if a wrong-format parser ever reaches a SIGNED close.
+
+Then the human signs `specHash`, unchanged: the approvals array and the human's word are
+the arbiter relocating to the user, not disappearing. **Re-authoring is a spec edit (D6)** —
+a different declaration is different bytes, a different resolved hash, and a new signature.
+The guards are stored ENUMERATED and every short-form parser is expanded, so no
+omittable-with-a-default field can change what runs without changing what was signed.
+
+**A signing surface must show the GOAL and the judged stages as one reading (F87).** The
+goal has to state everything the close will judge, and **nothing derives one from the other
+or checks them against each other** — the only derivation runs close-stages → check menu, one
+hop, one direction. So the sole defence against an unstated stage is that the person signing
+reads both halves at once, and any surface you build around `prepareSigning` inherits that
+obligation. Both reference runners now do it: `scripts/run-u.mjs --approve` names every close
+stage (name + kind) under the goal — for **BOTH spec forms**, through `closeStagesOf`, since
+gating that block on `closeDecl` reached exactly one of the eleven shipped specs and left the
+other ten (command `close[]`) showing the goal with no stages under it, which is the same
+half-reading in the guard against it (F100); a command stage prints `[command]` and NOT the
+catalogue kind name it does not carry — and `scripts/run-author.mjs` prints the goal above the
+declaration via `declarationLines(spec)` in `scripts/author-readout.mjs`, rendered from the
+**RESOLVED** spec — the bytes that get hashed, never the draft and never the authored half
+alone. An absent goal renders as absent rather than as a bare label. This is a READING, not a
+validator: nothing compares the goal to the declaration, because deriving one from the other
+is exactly what F87 forbids.
+
+**Refusals are COUNTED (D13).** `refusalEvents(refusal)` returns the spine events: a
+`job-red` carrying `{ code: 'request-red', verb, lib: 'bareloop' }` — the `lib` stamped at
+the EMIT SITE, so `classifyIncidents` files it against bareloop's own catalogue and its
+`suggestedAsk` reads `bareloop: …` rather than seeding an upstream ask — plus one
+decision-ready `escalation` under `close-unauthorable`, which is in the ledger's excluded
+set precisely because the demand is already counted once. A refusal that is a STOP rather
+than demand (a broken instrument, a close with nothing to do) emits the escalation ALONE.
+**Known limit, stated:** v1's derivation cannot tell `soft-green` from `hitl` and does not
+try — both refuse under one verb (`non-green-verdict`), because naming which locked class a
+job belongs to would be a guess about prose.
+
+**At run time** the declared close is executed by the kind executor, never compiled down to
+shell (that would turn owned kinds back into authored strings — the exact thing D3 makes
+inexpressible). `runPlan` picks the executor from which field the signed spec carries and
+everything downstream is the same code: first-red-wins, the `CLOSE_FAULTS` forbidden zone
+(routed by a TYPED fault, so a timeout still offers "raise the close timeout"), the same
+`close stage "<name>" failed:` gap header the trend reader parses, the same scrub at the
+emission boundary, and the check menu still derived from stage names one hop. The seed is
+READ at run start (`seedAtHead`) and recorded on a `close-decl` spine event together with
+the grounded re-validation's result. Direct executor access: `runDeclaredStages(stages,
+redact, { cwd, seedRef, timeoutMs })` returns `runClose`'s verdict shape **plus one added
+field, `notes`** — the DIAGNOSTIC channel, per stage and on the summary, ABSENT when empty
+(never `''`). M1's kinds announce some things whichever way a stage lands (a declared env var
+that was dropped, the scope filter's own arithmetic), and a RED carries those out inside its
+`gap` while a GREEN and an instrument stop had nowhere to put them — checking the GREENS is
+doctrine, and an audit trail that only survives a red cannot do it. It is deliberately NOT
+`gap`: every consumer guards with `if (gap)`, so a green carrying one would read as
+revision-worthy and a stop carrying one would look like a verdict it never rendered. **Nothing
+routes on it, nothing bounds on it, and no verdict moves because of it** — it rides the records
+that already spread the whole verdict (`close-precheck`, `outer-close`, ralph's
+`close-verdict`). `runDeclaredClose`
+and `seedRead` are the kind executor's own two entries (`runDeclaredClose` is named apart
+from ralph's shipped `runClose` because one runs a DECLARATION and the other an argv);
+`closeStagesOf(job)` is the ONE staging every close consumer reads, widened to both fields.
 
 ### `snapshotScope(dir, scope)` / `evalExits(exits, { dir, snapshot?, runCheck? })` — `src/exits.js`
 
@@ -504,10 +678,10 @@ Reserved spine vocabulary (V7, machinery-free until job #1 surfaces one):
 `coordination-red` — a failure between units (scope contention, step order, store
 races), never to be folded into worker/interpreter reds.
 
-### `runJob(spec, { approvals, workdir, provider, nativeProvider?, providerFor?, emit, capRuns?, strikeLimit?, shellCapUsd?, closeTimeoutMs?, layerRoot?, bridge?, priorSpentUsd?, priorSpendComplete?, priorWallMs?, resumeSeed?, resumeGrades?, resumeReplans? })` → outcome — `src/run.js`
+### `runJob(spec, { approvals, workdir, provider, nativeProvider?, providerFor?, emit, capRuns?, strikeLimit?, shellCapUsd?, closeTimeoutMs?, layerRoot?, bridge?, priorSpentUsd?, priorSpendComplete?, priorWallMs?, resumeSeed?, resumeGrades?, resumeReplans?, resumeBranch? })` → outcome — `src/run.js`
 
-The last six are the RESUME fold and are documented under *Resuming a killed run* below; they
-default to `0` / `true` / `0` / `null` / `[]` / `null`, so a fresh run passes none of them.
+The last seven are the RESUME fold and are documented under *Resuming a killed run* below; they
+default to `0` / `true` / `0` / `null` / `[]` / `null` / `null`, so a fresh run passes none of them.
 Three of them are folds of a bound the operator SIGNED (money, wall, replans) and one is a
 readout seed (grades) — the distinction matters and is spelled out there.
 
@@ -519,8 +693,11 @@ known-answer round-trip before tokens: `smoke-red` — a silent degradation thro
 `min(job budget − spent, shell cap)`.
 
 Outcomes: `green | already-green | escalated | unapproved-spec | job-red | smoke-red |
-plan-red | check-red | close-red | close-unsupported | recipe-stale | pricing-red |
-provider-red | interpreter-red | cap-halt | wall-halt | step-stalled | step-red:<id>`. `provider-red` is a
+plan-red | check-red | close-red | close-unsupported | recipe-stale | branch-red | pricing-red |
+provider-red | interpreter-red | cap-halt | wall-halt | step-stalled | step-red:<id>`.
+`branch-red` is the WORK BRANCH refusing (below): the patient is not a git checkout, its
+branch namespace has no free name, or a resume's recorded branch is gone. Zero tokens, and
+never a fallback to working on the branch the run was handed. `provider-red` is a
 transport throw or a worker round the API cut off mid-generation (`truncated:max_tokens`,
 BA-6 — before which it laundered into a clean finish, F25): no verdict exists and the failed
 round's spend is only partly known (F6). `cap-halt` is the wallet; `wall-halt` is the clock
@@ -544,9 +721,37 @@ three times on one call — each stall silently abandons the hung call and reiss
 laundered into `provider-red`, and carries `spendComplete:false` (an abandoned call may
 already have been billed). **The reissue is wall-aware:** past the run's deadline the fuse does
 not self-heal — self-heal is what a run does with time left — and it gives up as `wall-halt`,
-not `step-stalled`, since a replan has nothing left to re-allocate. Every one of them is a
+not `step-stalled`, since a replan has nothing left to re-allocate. **A `step-stalled` run is
+a CHECKPOINT, not a verdict** (hamr's ruling, 2026-08-13 — PRD v1.64 §1): it is resumable on
+the reference runner alongside the two governance halts, the work on disk stands, and its
+`spendComplete:false` carries forward as a floor. Every one of them is a
 decision-ready escalation with a terminal `job-end`: the spine never dangles.
 
+**`gate-red` is not in that list, and the plan flow no longer mints it (F98).** A fence
+DENIAL STREAK — bare-agent's BA-11 deny-spin guard returning `denied:*` after consecutive
+refusals — is a **BOUNDED ATTEMPT, never a terminal**, on BOTH worker surfaces: the attempt
+ends, `attempt-bounded` is emitted with the `reason`, the close judges the partial work, the
+gap feeds forward, the caps are unchanged and the loop continues.
+**The NEXT attempt is told which bound fired** (v1.64 §2): the bound carries
+`{iteration, cause, reason}`, and where the cause is `denied` the note says the GATE cut the
+attempt and quotes what the gate recorded, verbatim — instead of the round-cutoff sentence,
+which was false on cause and on count and aimed the worker at its read budget when the thing
+that stopped it was the fence. **Nothing is invented**: bare-agent returns `denied:<tool>`
+and nothing else — no path, no streak count — so neither is claimed. Every other cause keeps
+the round-bound wording byte for byte. The reason is scrubbed ONCE at capture through the one
+`SECRET_PATTERNS` inventory and shared by prompt and spine, and trimmed under the repo's one
+`GAP_TRIM_MARKER` (F90.2). It is the same lane
+`max_turns` and `loop.stop()` take, for the same reason — the attempt ran, produced audited
+work, and was cut short by a governance bound doing its job. **The fence holding is the
+system working, which is the opposite of a fault**; routing it as an instrument stop killed a
+converging run with $1.77 and 21.6 wall-minutes still on it. Nothing about the gate changed:
+the same actions are denied, the same audit rows are written, a genuine scope escape produces
+exactly what it did before — it now costs one bounded attempt instead of the whole run. The
+category survives only as a passthrough (`ralph`'s decision table still answers to it if a
+caller's own middle throws it, and `EXCLUDED_ESCALATIONS` still lists it so a future emission
+is filed as governance rather than re-read as a capability gap), but no site in this library
+raises it.
+
 **Every `job-end` carries the money, on every path**: `{ outcome, spentUsd, spendComplete }`
 (plus `step`/`cause`/`detail` where the outcome has them). `spentUsd` is the accumulated sum
 of PRICED rounds ONLY — never an estimate from token counts or averages (cap-not-estimate) —
@@ -568,7 +773,9 @@ their own ledger): **close precheck** (`already-green` is a
 DISTINCT zero-token outcome; a forbidden-zone verdict escalates before spend) → **check-menu
 preflight** (`check-menu` names the derived menu, then every OFFERED stage's chain runs once
 at $0 — an unrunnable stage is a `check-red` stop before tokens, not a fault mid-plan) →
-**SCOUT** (read-only by construction: neither the
+**THE WORK BRANCH** (below — created before the first paid call, `branch-red` if it cannot
+be; on a RESUME it runs FIRST, ahead of the precheck and the preflight, because the recorded
+branch IS the tree those instruments must measure) → **SCOUT** (read-only by construction: neither the
 write-class nor the store-class verbs are in its menu; hard-bounded rounds) → **PLAN** (the decompose call —
 the planner never sees the repo, only the scout blob; drafted against a schema
 description with check NAMES only; `validatePlan` gates it, one redraft with the reds
@@ -586,6 +793,56 @@ plan-red | check-red | close-red | wall-halt`. Worker prompts hold the v1.12 §5
 (mutation-proven): the absolute repo root, the step's action/target, prior artifacts,
 the gap — NEVER the budget, the close command, a check's command, or the arbiter's books.
 
+**THE WORK BRANCH — a hard rule, and a REQUIREMENT on the patient (PRD v1.57 §3).** hamr's
+ruling, verbatim: *"The agent creates a NEW BRANCH before it touches any code — a HARD RULE,
+no exceptions. Not a default, not a preference: no job edits the branch it was handed, and
+none edits `main`."* So **the patient must be a git repository with at least one commit** —
+that is new, and it is the honest consequence of the rule rather than an option. And the
+patient itself is **ALWAYS a separate COPY of the repo being treated, never the original**
+(hamr, 2026-08-09): the branch bounds where writes land, but workers and close stages
+still mutate the patient tree (branches per try, caches, worktrees) — the copy is the
+blast radius; the original never carries it. What the run does, before its first paid
+call:
+
+- **The name is DERIVED from the SIGNED spec**, never model-authored (a branch name is
+  arbiter bookkeeping): `bareloop-` + the spec's own `job` slug — `bareloop-typecheck-fix`.
+  `workBranchName(spec)` is exported so a runner can show it at its approval gate. The goal
+  prose is deliberately NOT an input: it is edited between runs without changing what the
+  job is, and the branch name would move with it.
+- **A name already taken is SUFFIXED** `-2`, `-3`… — a second run of the same spec is a
+  second blast radius and never reuses the first one's branch.
+- **A RESUME returns to ITS OWN branch.** Pass `resumeBranch` (read off the dead spine by
+  `readResume` as `restart.branch`); without it the deterministic name would collide with the
+  killed leg's own branch and mint a `-2` beside the work the resume exists to keep. The
+  recorded branch is the ONLY branch a resume can land on — it is validated and checked out,
+  never re-derived from the spec and never suffixed. A recorded branch that no longer exists
+  is a `branch-red` STOP, never a fresh start.
+- **On a RESUME this step runs FIRST**, ahead of the close precheck and the check preflight
+  (cold, it runs after them — see the already-green bullet). Both are $0 readings OF A TREE,
+  and on a resume the tree they must read is the recorded branch's: standing on whatever ref
+  the operator handed back, the precheck could read `already-green` off a tree that is not
+  this run's and every `baseline: "seed"` stage would baseline against it. Nothing is minted
+  by moving it — the resume arm creates nothing — and a resume whose branch is gone or foreign
+  now stops `branch-red` before the arbiter grades anything at all.
+- **`work-branch { branch, created, resumed, from, base, repo, collided? }`** lands on the
+  spine at creation — the run's books say where its work went.
+- **Every failure is `branch-red`**, escalated decision-ready with zero spend. There is no
+  fallback to the handed branch anywhere; and `mkWorker`, the ONE seam that grants
+  write-class verbs, refuses to build a write-capable worker with no branch prepared, so the
+  ordering is a convenience and the guard is the rule.
+- **A COLD run's `already-green` tree leaves no branch behind** — the precheck returns above
+  this step, and a run with no work has no blast radius to bound. The clause is about
+  MINTING: a RESUME that reads `already-green` off its own branch (which it is standing on by
+  then) leaves that branch and the paid work on it exactly where they were.
+
+**What it does NOT do.** bareloop never commits, so the branch bounds where work LANDS: the
+tree stands on a branch nobody handed the run, and the handed ref is never moved or written
+through. It is not containment — v1.41's local-trust model is unchanged, and worker/close
+children still run as the operator's OS user with network egress. A workdir that is a
+SUBDIRECTORY of a repository gets its branch in the enclosing repository (git resolves
+upwards, exactly as every other git read in the flow does); the `work-branch` record's `repo`
+field names which repository that was, rather than leaving it to be discovered.
+
 **The strike ladder — how a STEP ends (F77–F79).** A plan step is **not** bounded by a
 number of iterations. It runs until it stops making PROGRESS: a *strike* is a red iteration
 that repeats an already-seen gap or wrote nothing, and `strikeLimit` strikes (shell option on
@@ -713,7 +970,7 @@ is read, so a resume of a resume inherits the previous leg's chain and not the o
 (`createClock`, `src/clock.js`) from the signed `maxWallMs` and emits `wall-clock` with the
 requested AND enforced numbers up front, plus the `closeStages` count that explains the gap
 between them (`enforcedMs = maxWallMs + closeStages × closeTimeoutMs`, one expression — the
-stage count comes from `stageClose`, the same staging the runner executes). Enforcement is a
+stage count comes from `closeStagesOf`, the same staging the runner executes). Enforcement is a
 **between-round deadline** — the only seam that exists, since `loop.stop()` cannot cut an
 in-flight call (F61: fired at 500ms,
 returned at 4,018ms) — so an attempt that crosses the deadline mid-flight emits `wall-bounded`,
@@ -831,7 +1088,9 @@ learning credit and runs no on-green retention. A close that cannot RUN is a `br
 escalation before any provider call. So the resume story is: a `cap-halt` or `wall-halt`
 stop IS the checkpoint (the workdir + the close), the human raises `budgetUsd` or
 `maxWallMs` (a new spec hash — re-sign), and the rerun picks up where the budget died,
-paying zero provider calls for anything already green.
+paying zero provider calls for anything already green. (Those two are the *allowance* stops,
+the ones with a lever to raise. They are not the whole resumable set — `step-stalled` is also
+a checkpoint, with nothing to re-sign; see `resumableOutcomes` under the resume reader.)
 
 **Unpriced is never free (F6/F12):** the ledger meters **per ROUND** (`worker-round`, at
 bare-agent's `onLlmResult` seam) — money is counted as it is spent, never at the end of an
@@ -853,7 +1112,14 @@ the loop contract (F16 — it is ONE attempt inside `while close-red and under-c
 re-run with the close's verdict; without this a model one-shots and can eat the budget in
 reads before ever writing). It is NOT allowed to read the run's own machinery (F14): the gate
 audit, the smoke store and the litectx store are denied — the agent neither authors the
-arbiter nor reads its books. N2 bounds (honest): `gold`/`rubric` closes refuse
+arbiter nor reads its books. **That denial is now REGISTERED in the persona, not left to be
+discovered (F98):** `PERSONA_TOOLS` names `gate-audit.jsonl`, `.smoke`, `.litectx` and the
+run's spine as always-denied, records of how the worker is being judged and never anything
+about its task, beside the absolute-path law it is the twin of — both are fence facts a worker
+cannot infer. It renders for EVERY worker on every grant (a worker granted only `write` gets
+no component strategy paragraph at all and must still be told). The fence is unchanged; what
+changed is that the rule is stated instead of learned one refusal at a time, which cost a real
+run the rounds of a bounded attempt. N2 bounds (honest): `gold`/`rubric` closes refuse
 `close-unsupported` (execution lands at N4).
 
 ### The reuse registry (Layer 3) — `src/bridges.js`, `src/selection.js`
@@ -1054,8 +1320,8 @@ the secrets scan.
 A reuse run is up to `tries + 1` full jobs long, so a kill mid-run is a real event and it
 must not cost the whole envelope. **`readResume(events, {deathAt?, direct?, resumableOutcomes?})`**
 reads the dead run's own spine back into the state a resume continues from: `{ started,
-approvalHash, completed[], tried[], restart (with its step-level `seed` and its close
-`grades`), r1Missing, spentUsd,
+approvalHash, completed[], tried[], restart (with its step-level `seed`, its close
+`grades`, and its work `branch`), r1Missing, spentUsd,
 spendComplete, carrySpentUsd, carrySpendComplete, ended, greened, … }`. Hand that object to
 **`runReuse({…, resume})`** and the run picks up where it stopped.
 
@@ -1073,16 +1339,45 @@ semantics are byte-unchanged (PRD v1.46 §3):
   is `$0`: a leg whose every round came back unpriced folds nothing countable and is still not
   exact, so the declaration is emitted to carry that unknown forward rather than letting it read
   as an exact zero (F6).
-- **`resumableOutcomes: ['cap-halt', 'wall-halt']`** reclassifies a landed `job-end` whose
-  outcome is a GOVERNANCE HALT as a restart rather than a completed row. "A landed job-end is
-  complete" is true of a VERDICT; a halt means an operator-owned allowance ran out with the
-  work on disk and the plan on the spine. A green or any red stays non-resumable under every
-  setting — a verdict already rendered is never re-bought.
+- **`resumableOutcomes: [...]`** reclassifies a landed `job-end` whose outcome is a
+  CHECKPOINT rather than a verdict as a restart rather than a completed row. "A landed
+  job-end is complete" is true of a VERDICT; a checkpoint means the work is on disk and the
+  plan is on the spine with nothing decided against them. **The set is the CALLER's**, and
+  the reference runner's is `['cap-halt', 'wall-halt', 'step-stalled']` (`run-u`'s
+  `RESUMABLE_HALTS`). The first two are governance halts — an operator-owned allowance ran
+  out. `step-stalled` joined them 2026-08-13 on hamr's ruling (PRD v1.64 §1): it is the one
+  terminal whose OWN escalation already offers *"retry the run"*, nothing about the work on
+  disk is wrong, and the shape that named the fix is a stall that trips with time left and
+  then rides out past the wall — losing a checkpoint a `wall-halt` would have kept. Its NAME
+  deliberately stays `step-stalled` because `runJob` keys the **F44 spend FLOOR** on that
+  outcome; renaming it would report unknown spend as exact. The floor travels: a stalled
+  leg's `spendComplete:false` reaches the preview as `≥$x` and the resumed leg as
+  `priorSpendComplete: false`, so the next terminal stays a floor rather than healing an
+  unknown by inheriting it. A green or any red stays non-resumable under every setting — a
+  verdict already rendered is never re-bought.
+  **One exception, and it is a DERIVATION rather than a widening (D4a, F96).** A recorded
+  `step-red` is re-read as a wall-halt — and becomes resumable — when the run's OWN spine
+  carries a `wall-bounded {bounded: true}` record STRICTLY BEFORE its terminal, and only when
+  `'wall-halt'` is itself in `resumableOutcomes`. It fires on the run's own primary evidence,
+  which no caller can assert; a `step-red` with no wall record in front of it is untouched, so
+  "a red is an answer" survives intact. It touches no close verdict — the grades stand and the
+  resume seeds from them. The readout surfaces `wallDerivedHalt` so an operator resuming a spine
+  that SAYS `step-red` is told which record turned it into a checkpoint. **This is a PERMANENT
+  safety net, not a migration shim (ruled 2026-08-13, PRD v1.63 §2):** the defect that minted
+  the shape is fixed at source, but spines are append-only forever, so the population it protects
+  can never shrink — and on a healthy spine it is a branch that is never taken.
+
+`restart.branch` is the WORK BRANCH the dead leg was working on, READ off its `work-branch`
+record and never re-derived: the name is deterministic from the signed spec, so a restart that
+recomputed it would collide with its own predecessor and be handed a fresh `-2` beside the work
+it came back for (the declared-fold precedent, `priorSpentUsd`'s exactly). Pass it on as
+`resumeBranch`; `runReuse` does it for you. `null` — a leg killed before it ever branched — is
+the cold path, and correct, because a leg that never branched has no work to strand.
 
 `scripts/run-u.mjs --resume <runid|path>` is the operator-side consumer: it skips the patient
 reset (`resumeTreeGate` instead — a dirty tree is what a resume expects; only a moved HEAD
-stops it), folds the halted run's money and wall in, re-enters at the checkpoint, and arms the
-outside watchdog on the REMAINING wall. The top-up itself stays a spec edit the human signs.
+stops it), folds the halted run's money and wall in, returns to the dead leg's own work branch,
+re-enters at the checkpoint, and arms the outside watchdog on the REMAINING wall. The top-up itself stays a spec edit the human signs.
 **A zero wall remainder REFUSES the launch** (exit 2, before the key and before the patient):
 W-2 says a run out of time keeps the grade it has and stops, so a resume with no time to start
 anything in is a decision, not an unbounded launch — and launching it used to hand the outside
@@ -1152,6 +1447,12 @@ and is re-signed.
   fold — a garbage, non-finite or negative `count` reads as `0` rather than widening the ceiling.
   Null/omitted is the cold path. The disarm control is pinned: a resumed leg with an UNSPENT
   ceiling still replans, so the bound is bounded, not switched off.
+  **NEVER-REFILL is now the RULING, not just the behaviour (2026-08-13, PRD v1.63 §4).** A resume
+  inherits the spent replan ledger, entire; a refill would let every kill buy an allowance, which
+  is unlimited replanning through the side door, and unlimited replanning launders thrash as
+  adaptation. The consequence for an adopter is a real one and is deliberate: a resume whose
+  ledger is already spent re-enters its plan with no channel to replace it. That is not funded —
+  it is SHOWN, by the resume banner, before you sign.
 - **Under the REMAINDER, never a fresh allotment.** The killed attempt's spend and wall
   FOLD IN (`runJob`'s `priorSpentUsd`/`priorSpendComplete`/`priorWallMs`, `createClock`'s
   `priorElapsedMs`), so
@@ -1221,12 +1522,19 @@ whichever territory was seen first), `broken-close` (consumer-attributed),
 `verb` field, prose-quoted verb as legacy fallback; both classes take their `lib` from the
 red's own stamp, so neither seeds an upstream ask for a bareloop-catalogue refusal),
 `retention-red`, `config-red`
-(drafting friction — attributed to bareloop's own schema/prompt). Deliberate exclusions
+(drafting friction — attributed to bareloop's own schema/prompt). Close-authoring
+refusals ride the SAME `request-red` channel with `lib: 'bareloop'` stamped at the emit
+site (`refusalEvents`), so genre/verdict/locked-kind demand is counted without ever
+seeding an upstream ask. Deliberate exclusions
 (`EXCLUDED_ESCALATIONS`, a runtime set — anything outside classified ∪ excluded is
 counted as unmapped, never dropped): `cap-halt`/`wall-halt` (budget stories, money and
 time), `step-stalled` (the stall fuse firing is our governance, not an observed provider
 failure), `step-variance` (a planning story), `gate-red`/`smoke-red` (governance working
-as intended / already counted), `hitl-close`/`close-unsupported` (by design),
+as intended / already counted — and `gate-red` is no longer minted anywhere in this library,
+kept listed because this set is EXECUTABLE: dropping a name would not delete the category, it
+would re-file any future emission of it as a counted capability gap), `hitl-close`/`close-unsupported`/`close-unauthorable` (by design — and the last one
+is excluded for a SECOND reason: its demand is already counted once as the `request-red`
+the same refusal emits, so counting the escalation too would double every refusal),
 `close-timeout`/`close-killed`/`close-crashed` (the arbiter's own named terminals, F17);
 `close-verdict`/`artifact-red` stay worker stories, `pr-red` operator environment.
 `suggestedAsk` on every row is a template seed for an upstream ask — filing stays human;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bareloop",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "description": "Workflows that earn their own design, with receipts — agent-authored workflows for repeated, long, verifiable jobs that improve across runs under an un-gameable gate.",
   "type": "module",
   "main": "./src/index.js",