bareloop 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -5,6 +5,200 @@ All notable changes to bareloop are documented here. Format:
 [SemVer](https://semver.org/spec/v2.0.0.html). Pre-1.0: **minor** = a ladder rung or
 feature lands, **patch** = docs, fixes, scaffolding.
 
+## [Unreleased]
+
+## [0.5.0] — 2026-07-23
+
+### Added
+
+- **Layer 2 core — the plan-v1 flow (design record
+  `docs/plans/2026-07-21-layer-2-plan-v1-design.md`; premise validated in F46).**
+  The semantic converter, built:
+  - **job-v1 four-field plan shape** (`src/job.js`): `goal` / `verdictType`
+    (`green|soft-green|hitl` frozen radio — v1 admits `green` only; a locked type is a
+    `request-red` with the type as a structured `verb` field) / `close` / `checks[]`
+    (operator-SIGNED named checks: the predicate-close body + a slug name, same
+    validation, same runClose machinery; checks decide nothing and mint nothing) /
+    `tools` (the plan ceiling). Exclusive with legacy `steps[]` (`shape-conflict` red);
+    `steps[]` is co-existing scaffolding with a staged sunset — archives alongside
+    config-v1 when the Layer 2 path proves itself in its battery.
+  - **plan-v1 validator** (`src/plan.js`, `validatePlan`): gates the AGENT-authored
+    plan against the SIGNED spec — verbs ⊆ ceiling (`verb-escape`, verb as structured
+    data), rounds ≤ shell cap, targets/scopes inside the fence, exits from the closed
+    menu only (`exit-illegal`), `check-passes` resolving against the signed menu
+    (`check-unknown` names the menu), no `dependsOn` (strictly sequential — an inert
+    knob is a fake contrast lever), AND-only exit composition max 2, and the F17
+    pairing law (check-passes on a write step demands tree-changed — the seed tree is
+    green). Fails CLOSED on a missing/non-plan-shape job (`job-invalid`).
+  - **exit evaluator** (`src/exits.js`, `snapshotScope`/`evalExits`): the shell's own
+    fixed code for `artifact-written` / `tree-changed` / `json-valid` /
+    `check-passes`. Outcome, never intent: sha256 snapshots, identical re-writes are
+    not changes (F43), git status never consulted (F45). Instrument faults ride out as
+    `fault` by runClose verdict name — escalated, never fed to the worker as a gap.
+  - **the judge seam** (`src/ralph.js`): `ralph({ judge })` — the PRD v1.12 §4
+    generalization; shell-injected, inexpressible in any config or plan. Same verdict
+    vocabulary, so the forbidden zone, F32 worker-crash routing (a check crashed by the
+    worker's own test feeds back — the F46 mechanism), and cap taxonomy are unchanged.
+  - **the plan executor** (`src/planrun.js`, `runPlan`): close precheck
+    (`already-green` distinct, F17) → checks preflight ($0, before tokens) → read-only
+    SCOUT → PLAN (one redraft with reds fed back) → sequential micro-loops with
+    exit-gap feedback → ONE replan (exhaustion only) → the operator's close with one
+    bounded fix loop. Every round metered `worker-round` with a phase label (F12);
+    prompt contract v1.12 §5 mutation-proven; `plan-executed` (plan-as-executed,
+    design law #2) on the spine.
+  - **runJob dispatch** (`src/run.js`): a plan-shape spec routes through the ONE
+    runJob entry — same approval gate, smoke, ledger, and job-end money contract.
+    New outcomes: `already-green | plan-red | check-red | close-red`.
+  - 139 new tests (503 total), TDD throughout, 3 targeted mutations fired and killed.
+    Built and integration-tested against scripted providers.
+- **Layer 2 rung ACCEPTED — the real-model acceptance battery (F47; prereg
+  `docs/02-experiments/TESTGEN-PREREG.md` §2026-07-22a/b).** Job #4 (TESTGEN) run
+  through the REAL plan flow (`runJob → runPlan`: scout → the agent DRAFTS the plan →
+  validator gates → per-step check-loops → outer grader), on `anthropic-api`,
+  claude-sonnet-5, vs F39's baseline (0 conversion) and the F46 POC (hardwired).
+  **3/3 valid acting rows converted (≥2/3 bar) → accepted; 3/3 cleared the 45% bar
+  (67.5/55/55, vs the POC's 27.5/40/37.5 with 0 at 45); 3/3 the agent composed the
+  `check-passes(clean-run)` exit ITSELF** (the one thing the POC could not test). Every
+  green driven by the step check-loop alone; all writes fenced, source frozen, secrets
+  clean; the F45 spend guard stopped an unpriced casualty. 7 provider-red casualties
+  across an Overloaded window (excluded as evidence), $27.36 of a $30 cap. This trips
+  the "path closes green end-to-end" milestone: **`steps[]` and config-v1 sunset on
+  landing.** Driver `scripts/run-battery-l2accept.mjs` (gained `--need`/`--priorUsd`
+  for a multi-run continuation under one governed cap).
+- **Module 4d — native clipipe worker surface (BA-16; `bare-agent` → `^0.33.0`).** The
+  plan flow now runs on TWO surfaces: the `Loop` (API, unchanged) and, when
+  `job.provider === 'clipipe-subscription'`, the `claude` CLI's NATIVE tool channel — the
+  subscription path (no metered API). Since native governance is constructor-time and
+  per-worker, the runner takes a `nativeProvider` FACTORY (`{policy, onTurn?, maxTurns,
+  hasTools}) => provider`) it calls fresh per worker: `hasTools:true` → native tool mode
+  (the SAME `wireGate` fence clips onto the provider — a live POC proved an out-of-scope
+  write is DENIED); `hasTools:false` → the toolless drafter runs metered claude-json TEXT
+  mode (a native session reports no cost — this path keeps the drafter's spend visible).
+  Money reconciles per session (accounted `worker-round` = session total; `worker-turn` =
+  attribution); `max_turns` is a bounded attempt, not an escalation; a missing factory is
+  `interpreter-red`, never a silent fall-back to the API. 5 native tests + a live
+  end-to-end smoke on the real CLI (green, all workers metered, `spendComplete` honest).
+
+- **Native read-cap — the CLI truncation fix (F48; `bare-agent` → `^0.33.1`, BA-17
+  ranged read).** On the `clipipe-subscription` surface the `claude` CLI truncates a large
+  tool result (~40–50KB, measured) BEFORE the model sees it — spilling the remainder to a
+  fenced-off `tool-results/` file and wrapping it in a "read in chunks" notice the model
+  distrusts as injection — so a whole-file `shell_read` of a large file blinded the native
+  worker (0-write stall). The runner now bounds the native `shell_read` result below the CLI
+  cap (`NATIVE_READ_CAP`) and returns a TRUSTED notice steering to `ctx_get` ranged retrieval,
+  plus a native-only strategy line; the API path is untouched (full result rides into context).
+  Measured: **0 → 7 writes** on the real job. Cross-surface verdict (F48): the native surface
+  is capable at the STEP but did not carry job #4 to a grade — 0/2 acting rows vs the API's
+  3/3, and a 3.5× budget raise ($8→$28) was refuted (escalated on the F39 semantic-stall at
+  $7). IN only as a babysat, $0-marginal-billing fallback; **only the `anthropic-api` surface
+  is guaranteed.** Local LLMs remain deferred and unmeasured.
+
+### Fixed
+
+- **Layer 2 pre-release review (F48) — 4 fixes, 2 correctness** (TDD, failing-then-passing
+  test each; full suite 519/519): (1) a provider-red/gate-red raised DURING a step's micro-loop
+  was collapsed to `step-red:<id>` — a transport CASUALTY recorded as a capability failure and
+  missing the F44 `spendComplete:false` floor; each terminal category now rides out under its own
+  name so the returned outcome and the emitted escalation agree (F11). (2) `tree-changed` counted
+  a sibling scope's files as deletions when a step had ≥2 tree-changed exits (merged snapshot),
+  falsely passing an unchanged scope — deletions are now scoped to the exit's own prefix. (3)
+  abandoned-plan artifacts no longer ride forward as the new plan's "prior steps' results" after a
+  replan. (4) dead `isUnpriced()` sub-conditions removed from the replan/cap-halt terminal (the
+  step-end guard already returns `pricing-red` first).
+- **Layer 2 whole-branch review — 8 doctrine-restoring fixes to the plan flow** (all in the
+  graduated Layer 2 code, none in pre-existing modules; validated against source with 0
+  refuted, a failing-then-passing test each): a `gold` close validated under `verdictType:
+  green` crashed `runPlan` with no `job-end` (now `close-unsupported` before tokens); the
+  `check-passes` gap was re-truncated to 400 chars, deleting the gapKeep failing-test names
+  (F28 reintroduced — now carried whole); no in-flight `pricing-red` (F6 — now bails at
+  scout/plan/step); the plan drafter's Gate budget was frozen pre-execute and reused for the
+  replan (now a fresh drafter per `obtainPlan`); a money-gate halt triggered a replan instead
+  of stopping (F45 — now gated on funds, drained → honest `cap-halt`); the step-setup catch
+  recorded a category the escalation contradicted (F11 — now agreed); the plan branch dropped
+  F44's `spendComplete:false` on a transport-throw `provider-red`; a write-only tool ceiling
+  validated, blinding the scout (now requires ≥1 read-capable verb).
+
+## [0.4.0] — 2026-07-21
+
+### Added
+
+- **Layer R — the root, the within-run ratchet (`src/root.js`; design record
+  `docs/plans/2026-07-19-layer-r-design.md`, interview-locked 2026-07-19).** The shell
+  mechanically detects fixation — consecutive attempts rewriting the same file(s)
+  without moving the close's kept-failure set — and injects an escalating note into the
+  next attempt's prompt: a capped summary first, then the worker's own prior failed
+  edit content verbatim (the BA-14 rejected-edit-buffer shape, rewritten for our
+  attempt loop). Fixation-gated (inert when not stuck — RSI §3.3: the lift is a
+  fixation phenomenon, an honest null on a strong unstuck model), shell-authored (the
+  worker authors nothing, gains no verb), within-run only (state dies with the run;
+  inheritance stays verdict-gated). Red-set comparison strips the spec-reporter's
+  per-run duration stamps (POC-measured: kept lines are never byte-stable) —
+  comparison-only, the delivered gap is untouched. Spine event `root-injected` carries
+  stage/mode/streak/paths, never content (append-only law). Ships **OFF by default**
+  (`layerRoot: false` on `runJob`/`interpret`; pass `true` for the ON/experimental arm) —
+  decided 2026-07-21: fixation is extinct on every current job (F41), so ON has never won
+  its own A/B; the default flip to `true` defers to the first Layer 2 job that produces
+  natural fixation (see `docs/01-product/LAYERS.md` Layer R note).
+
+### Fixed
+
+- **F44 — fresh whole-branch review: three correctness bugs + cleanups, all validated and
+  mutation-proven.** (1) A casualty job-end laundered unknown spend as complete: `1b0720c`
+  put `spentUsd` on every path, so a provider-red TRANSPORT THROW reported
+  `spendComplete: true` (F6 violation — the failed call's cost is unknown) and the battery
+  scripts' `spentUsd == null` casualty-STOP never fired. Fixed both sides: the transport
+  provider-red now reports `spendComplete: false` (the metered draft-truncation keeps
+  `true`), and the frozen battery/probe scripts key their STOP on
+  `spendComplete === false || spentUsd == null`. (2) Layer R's outcome probe mislabeled a
+  missed-anchor edit as "landed" when its `newText` appeared elsewhere (substring
+  false-positive) — now discriminated by the tool result, exact-equality for writes, one
+  read not two. (3) Layer R false-fired on a progressing text-mode worker with no gapKeep
+  (write-overlap is constant-true when the single target is rewritten every attempt) — a
+  `writesInformative` flag now requires a known-unmoved red-set when writes carry no
+  information. Cleanups: double redaction, unbounded `attempts` retention, a dead ternary.
+  (2) and (3) are latent behind the OFF-by-default `layerRoot`.
+
+- **Layer R settled its note on the gate's allow, which is written BEFORE the tool runs
+  (F43).** An `allow` record states INTENT, never that bytes reached a file:
+  `shell_edit` returns an anchor miss as a refusal *result* and a byte-cap overflow as a
+  throw, both leaving the file untouched with the allow already on the audit. The
+  verbatim note could therefore present content to the worker as "your own previous
+  changes — they landed" while that text was provably absent from the file it named
+  (reproduced end-to-end: 3 allowed edits, 0 bytes changed). Fixed by splitting the two
+  axes rather than merging them — the DETECTOR keeps reading intent (an edit that never
+  applied is still repetition; a tree-diff detector measured blind to it on every
+  attempt), while the NOTE settles on the observed file through `Loop`'s
+  `onToolResult` seam. An unapplied repeat now names the missed anchor instead, which is
+  the mechanical gap genre (F38). `commitWrite` is replaced by `settleWrite(landed)`.
+- **Guarded the `maxTurns` LLM-round invariant (F43 follow-up).** bareguard's `maxTurns`
+  ticks on every `gate.record`; our cap means "LLM rounds" only because the sole record
+  path is the LLM one (tool calls take `gate.check`, which does not tick). That was
+  correct but unguarded — wiring tool results into `gate.record` would silently halve the
+  LLM budget (the F37 lower-silent-ceiling class). Added a guard test pinning "every
+  `gate.record` is `type:llm`" (mutation-proven: wiring tool records turns it red) and a
+  config comment marking the invariant load-bearing. No behavior change; no upstream ask —
+  bareguard already offers the correct counters.
+- **F41 — the disposition: armed-and-inert, field read deferred.** Before any ON/OFF
+  battery spent money, two cheap reads measured the disease's base rate: the archive
+  sweep (`poc/layer-r-base-rate.mjs`, $0 — every surviving spine is OFF-arm by
+  construction) read 0 fixated in 10 pairs on jobs #2/#4; two frozen probes on a
+  rebuilt job #1 patient (`scripts/run-probe-layer-r.mjs`, $10.12 total) read 0
+  fixated in 4 pairs — including against a three-plant tree (three subsystems, one fix
+  cannot green) that forced a full 8→4→green ladder across three judged attempts.
+  Every pair was healthy navigation. F21's fixation was a broken-loop symptom, cured
+  by the F20/F21/F30/BA-13 fixes. Because ON has therefore never won its own A/B,
+  Layer R ships **OFF by default** (decided 2026-07-21; `layerRoot: true` is the ON
+  arm) — measured cost-free when enabled and healthy (zero injections across all
+  probe runs); the repetition-drop ON/OFF read, and the default-flip decision, defer
+  to the first run whose spine records `root-injected`. No learning claim is minted.
+
+### Changed
+
+- **`jobs/litectx-maintainer.json` `budgetUsd` 1.5 → 4.5** (probe 2, re-signed): $1.50
+  funded exactly ONE judged attempt on the real patient — a run could red at attempt 1
+  and die at the gate mid-attempt-2, structurally unable to produce across-attempt
+  evidence. The advertised budget must fund the attempts the cap promises.
+
 ## [0.3.0] — 2026-07-19
 
 ### Fixed

package/README.md

@@ -13,7 +13,7 @@
 <p align="center">
   <img src="https://img.shields.io/github/package-json/v/hamr0/bareloop?label=version&color=2a4f8c" alt="version (auto from package.json)">
   <img src="https://img.shields.io/badge/license-Apache%202.0-2a4f8c" alt="license: Apache 2.0">
-  <img src="https://img.shields.io/badge/status-N2%20%C2%B7%20headless%20loop-2a6d3a" alt="status: N2, headless loop">
+  <img src="https://img.shields.io/badge/status-Layer%202%20%C2%B7%20accepted-2a6d3a" alt="status: Layer 2, accepted">
 </p>
 
 **"Automate this job — I don't know the best workflow."** For tasks that are **repeated,
@@ -25,10 +25,15 @@ inheritance with ledger-counted attribution.
 The pitch in one line: **workflows that earn their own design, with receipts** — every
 inherited rule carries the green that minted it and the contrast that attributed it.
 
-> **Status: N2 — the headless loop is real.** `runJob()` takes a signed job spec through
-> draft → per-step worker loops → close verdicts → draft PR, under one budget the agent
-> can only tighten. Rungs N0–N2 have landed (roadmap below); next is executed
-> inheritance (N3), where the ladder's kill-switch question gets its answer.
+> **Status: Layer 2 — accepted.** The agent now authors its own workflow: `runJob()`
+> takes a signed job spec, surveys the repo, **drafts a validated plan of bounded steps**
+> (each with an operator-signed self-check it may reference but never author), and runs it
+> under an un-gameable outer close and one budget it can only tighten. On the real-model
+> acceptance battery (F47) the emergent flow converted a job the same worker failed 4/4
+> before — 3/3 runs, clearing the owned bar every time, composing its own check exits. The
+> within-run ratchet (Layer R) ships armed-and-inert by measurement (F41). Next: **N3 —
+> executed inheritance**, where the workflow persists and improves across runs (the
+> ladder's kill-switch question).
 
 ## Quick start
 
@@ -98,6 +103,8 @@ ladder, and the stop is a result.
 | **N0** ✅ | Port + outer shell + spine (token-free) — v0.1.0 |
 | **N1** ✅ | Job/close schema + validator — v0.2.0 |
 | **N2** ✅ | Single-job headless loop — job #1 minimal (review→fix→PR, hard greens only) — v0.3.0 |
+| **Layer R** ✅ | Within-run ratchet: shell-side fixation detector (intent) + rejected-edit feedback (outcome), **shipped OFF by default** (F41: fixation in remission, so ON has never won its A/B; F43 split the two axes; field read + default decision defer to Layer 2) — v0.4.0 |
+| **Layer 2** | plan-v1 micro-wheels — the road: bounded steps with in-run verifiable exits (the F39-measured semantic converter) |
 | **N3** | Executed inheritance + contrast-bit extractor — **kill-switch: rules must transmit across non-identical runs** |
 | **N4** | Verdict classes complete (soft/HITL minting) |
 | **N5** | Scheduler + budget ops |

package/bareloop.context.md

@@ -1,10 +1,16 @@
 # bareloop — Integration Guide
 
-> **Current through N2** (headless single-job loop: `runJob`, text + tool middles, the
-> draft-PR hitl step); API sections fill in as build-ladder rungs land (PRD §10). What is
-> settled — the boundary, the architecture, the refusals, the constraints — is settled
-> for good. Per LIBRARY_CONVENTIONS §3 this file ships with the package and is the
-> complete adopter contract; the README is only the pitch.
+> **Current through Layer 2 (ACCEPTED, F47)** (headless single-job loop: `runJob`, text +
+> tool middles, the draft-PR hitl step; the plan-v1 flow — four-field job shape, agent-
+> authored validated plans, in-run check exits — validated end-to-end on the real-model
+> acceptance battery: 3/3 conversion, 3/3 over the owned bar, the agent composing its own
+> check exits). The plan shape is the primary path; legacy `steps[]` co-exists but sunsets
+> on landing. Runs on two worker surfaces — the API `Loop` and, for
+> `clipipe-subscription`, the CLI's native tool channel (module 4d). API sections fill in
+> as build-ladder rungs land (PRD §10). What is settled — the boundary, the architecture,
+> the refusals, the constraints — is settled for good. Per LIBRARY_CONVENTIONS §3 this
+> file ships with the package and is the complete adopter contract; the README is only
+> the pitch.
 
 ## What this is
 
@@ -80,6 +86,22 @@ unknown-field reds.
 | `steps[].tools` | unique subset of `read\|grep\|write\|edit\|recall\|get` | the SPEC-side tool grant (`TOOL_MENU`, frozen; defaults to the full menu) — the drafted config cannot express mode or tools; `edit` (BA-13) is the anchored exact-once replace, judged by the SAME writeScope fence as `write`; requesting `run` (`LOCKED_TOOLS`) reds with the DISTINCT code `request-red` (locked-but-listed: the red IS the admission evidence the ledger tallies; a typo stays `invalid-value`) |
 | `escalation` | `{ mode: "decision-ready" }` | the pain channel is not optional |
 
+**The plan shape (Layer 2, design record 2026-07-21).** A job-v1 spec declares EITHER the
+`steps[]` chain above OR the four-field plan shape — never both (`shape-conflict` red).
+In the plan shape the AGENT authors the step plan at run time (gated by `validatePlan`);
+the human signs only:
+
+| field | shape | notes |
+|---|---|---|
+| `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) |
+| `close` | a close object (table below) | ONE close, the only truth; `green` demands a hard-class close (`close-hierarchy` red on a rubric/hitl close) |
+| `checks` | optional array of `{ name, cmd, expect, judged?, gapKeep? }` | the operator-SIGNED named-check menu: the predicate-close body plus a kebab slug `name`, validated by the same rules, executed under the same runClose machinery. Plans reference them via the `check-passes(name)` exit; the agent can never author, edit, or compose one. **Checks decide nothing and mint nothing** — a check result is a progress gate and a gap source only |
+| `tools` | optional unique subset of `TOOL_MENU` | the CEILING every plan step's grant must fit inside (defaults to the full menu); `run` reds `request-red` here exactly as on a step grant. On a legacy `steps[]` spec this field is an `invalid-value` red (steps grant tools per step) |
+
+`steps[]` is co-existing scaffolding with a staged sunset: it archives alongside
+config-v1 once the Layer 2 path proves itself in its battery — not before.
+
 **Close types and the hierarchy** (a close is data, never code; verdict-class laundering
 is a named red `close-hierarchy`):
 
@@ -140,18 +162,36 @@ drafted workflow config cannot express it (unknown-field red). The gap path also
 **both** streams (stdout + stderr), so a failure printed to stdout survives stderr noise
 (F28's adjacent hazard — the old `err || out` returned stderr alone and lost it).
 
-Red vocabulary (both validators): `parse-error`, `unknown-field`, `missing-required`,
+**The plan document (`schema: "plan-v1"`, AGENT-authored — the only document the emergent
+middle writes; `validatePlan` gates it against the SIGNED job spec before tokens burn):**
+
+| field | shape | notes |
+|---|---|---|
+| `steps` | ordered array, 1..8 (`MAX_PLAN_STEPS`) | strictly sequential — array order IS the order; no `dependsOn` (unknown-field red: an inert knob is a fake contrast lever) |
+| `steps[].id` | kebab slug, unique | |
+| `steps[].action` | non-empty text | the step's task — the worker sees only this step |
+| `steps[].tools` | non-empty unique subset of the SPEC ceiling | a verb beyond the ceiling reds `verb-escape` with the verb as structured data (overreach, distinct from the operator-side `request-red`); `run` is `verb-escape` at every layer |
+| `steps[].rounds` | int 1..shell cap (default 40) | the step's per-attempt tool-round bound (the Gate's `maxTurns` natively) |
+| `steps[].target` | path inside the fence | v1.18 deliverable; REQUIRED on write-granted steps |
+| `steps[].exit` | 1..2 items (`MAX_EXITS_PER_STEP`), ALL must pass (AND-only, no OR/NOT) | closed menu (`EXIT_TYPES`): `artifact-written(path, pattern?)` · `tree-changed(scope)` · `json-valid(path)` · `check-passes(name)`. `check-passes` must name a SIGNED check (`check-unknown` red names the signed menu); on a write-granted step it must be paired with `tree-changed` (`exit-illegal` — the seed tree is green, a lone check would pass untouched, F17/F46). Exits verify FORM, not truth — progress gates; the operator's close stays the one arbiter |
+
+Red vocabulary (all three validators): `parse-error`, `unknown-field`, `missing-required`,
 `invalid-value`, `bounds`, `duplicate-id`, `close-type`, `close-hierarchy`,
-`secret-literal`, `scope-escape`, `fence-invalid` (a malformed `jobWriteScope` fence — attributed to `jobWriteScope`, never the workflow config), plus the workflow-side verb reds (`verb-illegal`,
-`verb-placement`, `verb-params`, `slot-overflow`). The `secret-literal` sweep is
+`secret-literal`, `scope-escape`, `fence-invalid` (a malformed `jobWriteScope` fence — attributed to `jobWriteScope`, never the workflow config), `shape-conflict` (both job shapes declared),
+`request-red` (locked-but-listed: a locked tool or verdictType — admission demand the
+ledger tallies), plus the workflow-side verb reds (`verb-illegal`,
+`verb-placement`, `verb-params`, `slot-overflow`) and the plan-side reds (`verb-escape`,
+`exit-illegal`, `check-unknown`, `job-invalid` — a plan validated against a missing or
+non-plan-shape job fails CLOSED). The `secret-literal` sweep is
 defense-in-depth against known token shapes — env-only loading remains the law, not the
 sweep.
 
 ## Public API
 
-*Landed through N2 (spine + shell + both validators + interpreter with text/tool middles
-+ extractor + runJob). Still TBD: N3 (contrast-bit extractor live), N4 (verdict classes —
-gold/rubric close EXECUTION), N5 (scheduler + budget ops + CLI), N6 (panel).*
+*Landed through N2 + the Layer 2 core (spine + shell + three validators + interpreter
+with text/tool middles + the plan executor + extractor + runJob). Still TBD: N3
+(contrast-bit extractor live), N4 (verdict classes — gold/rubric close EXECUTION), N5
+(scheduler + budget ops + CLI), N6 (panel).*
 
 ### `makeSpine(file)` → `emit(type, data?)` — `src/spine.js`
 
@@ -159,7 +199,7 @@ Append-only JSONL event emitter bound to one file. `seq` monotonic per spine, `t
 last. Consumers are pure listeners; nothing reads the file back. Returns each event as
 written.
 
-### `ralph({ middle, close, capRuns, emit, redact?, closeTimeoutMs?, cwd?, expect?, judged?, gapKeep?, workerWrites? })` → `'green' | 'escalated'` — `src/ralph.js`
+### `ralph({ middle, close?, judge?, capRuns, emit, redact?, closeTimeoutMs?, cwd?, expect?, judged?, gapKeep?, workerWrites? })` → `'green' | 'escalated'` — `src/ralph.js`
 
 The dumb outer shell: `while close-red and under-cap: run the middle`. `close` is an argv
 whose exit code is truth (`runClose` is also exported); the red gap text feeds the next
@@ -205,6 +245,15 @@ to the gate audit's allow-decision write/edit lines (run_id-scoped); no seam or
 keeps the old behavior — an instrument crash still escalates `close-crashed`, never retried.
 Measured motivation: battery pass 1 (F31) lost 4 of 7 rows to exactly this escalation.
 
+**The judge seam (Layer 2, PRD v1.12 §4).** `judge?: async () => {verdict, gap?, detail?}`
+— a SHELL-injected replacement for `runClose`, so a plan step's micro-loop is judged by
+the exit evaluator instead of a command. It returns the same verdict vocabulary, so the
+forbidden zone, F32 worker-crash routing (a check crashed by the worker's own broken test
+feeds back — the F46 mechanism), and the cap taxonomy apply unchanged. `close` becomes
+optional when `judge` is present; the seam is wired by `runPlan` only and is
+inexpressible in any config or plan — the agent never authors its judge any more than
+its close.
+
 Escalations are decision-ready (category, options, spend); cap-halt is its own
 category, never merged with "wrong". A thrown middle is relayed by its `category`
 property (`cap-halt`, `gate-red`, …); an unnamed throw is `interpreter-red`. Close output
@@ -235,9 +284,35 @@ a leak on the very output it was guarding.
 The operator-owned sibling (never an extension) of `validateConfig`: validates a
 `job-v1` spec — see **All options** for the full schema, close types, and hierarchy.
 Never throws on JSON text or plain parsed data (the ingest contract); returns the
-parsed spec on ok, `null` on any red. Menus exported:
+parsed spec on ok, `null` on any red. Validates BOTH job shapes (legacy `steps[]` and
+the Layer 2 plan shape — see the option tables above). Menus exported:
 `CLOSE_TYPES`, `CLASSES`, `CLASS_BY_CLOSE`, `GOLD_COMPARE`, `CADENCE_UNITS`,
-`PROVIDERS`, `CONDITION_KEYS`, `STEP_MODES`, `TOOL_MENU`, `LOCKED_TOOLS`.
+`PROVIDERS`, `CONDITION_KEYS`, `STEP_MODES`, `TOOL_MENU`, `LOCKED_TOOLS`,
+`VERDICT_TYPES`, `LOCKED_VERDICTS`.
+
+### `validatePlan(input, { job, maxStepRounds? })` → `{ ok, reds, plan }` — `src/plan.js`
+
+The third validator: gates the AGENT-authored plan doc (`schema: "plan-v1"`) against the
+SIGNED job spec before tokens burn — the ceiling, the fence, and the checks menu all come
+from `job` (a missing or non-plan-shape job fails CLOSED, `job-invalid`). Never throws;
+same `{ code, path, detail }` red shape as its siblings; `verb-escape` reds carry the
+escaping verb as a structured `verb` field (the ledger keys on it). `maxStepRounds`
+(default 40 — the shell's tool-mode per-attempt bound) ceilings every step's `rounds`.
+Menus exported: `EXIT_TYPES`, `MAX_EXITS_PER_STEP`, `MAX_PLAN_STEPS`, `WRITE_VERBS`.
+
+### `snapshotScope(dir, scope)` / `evalExits(exits, { dir, snapshot?, runCheck? })` — `src/exits.js`
+
+The shell's own fixed code for the closed exit menu — nothing here executes
+agent-authored text. `snapshotScope` hashes every file under a scope prefix (the
+"before" side of `tree-changed`; a missing dir snapshots empty). `evalExits` is AND-only
+and never short-circuits — the result names EVERY failing wall (`{ pass, results }`,
+each result `{ type, pass, detail?, fault? }`). `tree-changed` reads OUTCOME (bytes vs
+the snapshot): an identical re-write is NOT a change (F43) and git status is never
+consulted (F45). `artifact-written` rejects zero-byte files. `check-passes` delegates
+through the `runCheck` seam (the runner wires runClose); an unwired or crashed seam
+fails CLOSED with `fault` carrying a runClose verdict name — an instrument fault
+escalates through `CLOSE_FAULTS`, never masquerades as worker feedback. Failing details
+are counts and names only, never file bodies (they ride the append-only spine).
 
 ### `jobSpecHash(job)` / `checkApproval(job, approvals)` — `src/job.js`
 
@@ -285,7 +360,32 @@ the close judges the tree; on-green `remember` retains the worker's change summa
 Worker-caused close crashes feed back as `worker-crash` gaps via the gate audit (F32 —
 see `ralph` above).
 
-### `runJob(spec, { approvals, workdir, provider, emit, target?, capRuns?, shellCapUsd?, closeTimeoutMs?, execCmd? })` → outcome — `src/run.js`
+**Layer R — the within-run ratchet (`layerRoot`, default `false`; design record
+2026-07-19).** The shell mechanically detects fixation across attempts — consecutive
+attempts that rewrote the same file(s) without moving the close's kept-failure set
+(`closeGapKeep` lines, duration stamps stripped before comparing; without a gapKeep the
+detector degrades to write-overlap alone and the spine event names the mode) — and
+injects an escalating note into the next prompt: first a capped summary naming the
+repeated files, then (if still stuck) the worker's OWN prior failed edit content
+verbatim, scrubbed and capped with trims announced. Inert unless stuck; the worker
+authors nothing and gains no verb. Two axes, deliberately separate (F43): the DETECTOR
+reads INTENT (the gate audit's allow-set — an edit whose anchor missed is still the
+worker reaching for that file again, and a tree-diff detector measured blind to exactly
+that), while the NOTE's claims about file contents read OUTCOME (settled post-execution
+through `Loop`'s `onToolResult`). So a repeat that never applied is told its anchor
+missed, and only content actually in the file is ever described as having landed. Spine event `root-injected` carries
+`{stage, mode, streak, paths, redSetSize}` — counts and paths only, NEVER content (the
+spine is append-only). State dies with the run: this is within-run scratch, not
+across-run memory. `layerRoot: true` (on `interpret` and `runJob`) is the ON/experimental
+arm; the default is OFF. Status (F41): the ratchet is MEASURED inert on every current
+job — two frozen probes + an archive sweep read 0 fixated pairs in 14 (the F21 repetition
+disease was a broken-loop symptom, since cured). Because ON has therefore never won its
+own A/B, it ships **OFF by default (decided 2026-07-21)** — armed and correct, but not
+default-enabled until a stuck job (Layer 2, or a manufactured-fixation probe) shows ON
+beats OFF. Flip the default to `true` the day that evidence lands; a `root-injected` event
+on your spine (when you pass `layerRoot: true`) is a signal worth reading, not noise.
+
+### `runJob(spec, { approvals, workdir, provider, nativeProvider?, emit, target?, capRuns?, shellCapUsd?, closeTimeoutMs?, execCmd?, layerRoot? })` → outcome — `src/run.js`
 
 The N2 runner — the shell's top layer; composes everything below it and interprets
 nothing itself. Sequence: **approval gate** (human-signs-always — refuses an unapproved
@@ -312,10 +412,61 @@ round the API cut off mid-generation (`truncated:max_tokens`, bare-agent 0.27.0/
 before which it laundered into a clean finish, F25); in both cases no verdict exists and the
 failed round's spend is only partly known (F6). `cap-halt` is drafting spend consuming the whole job budget before a
 valid config existed. Both are decision-ready escalations with a terminal `job-end`:
-the spine never dangles. A text-mode job invoked without `opts.target` is a `job-red`
+the spine never dangles. **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) — and it is stated even on the pre-token reds,
+where the honest figure is a real `0`. `spendComplete` says whether that figure is EXACT:
+`false` means one or more rounds came back unpriced (F6), so `spentUsd` is a FLOOR
+("at least $X", true total unknowable) and must not be read as a total. Both fields are
+present on all outcomes, so a consumer never branches on field presence and never has to
+launder a missing `spentUsd` into `$0`. A text-mode job invoked without `opts.target` is a `job-red`
 before ANY provider call (and `interpret` itself throws a TypeError for direct
 callers) — reds-before-tokens applies to the call, not just the spec.
 
+**The plan flow (Layer 2).** A plan-shape spec routes through the SAME `runJob` entry —
+same approval gate, same smoke, same metered ledger, same job-end money contract
+(`job-start` carries `shape: 'plan'` + the goal instead of a steps list; no `opts.target`
+needed — plan steps are tool-mode by construction). The flow (`runPlan`, also exported
+for direct callers who own their own ledger): **close precheck** (`already-green` is a
+DISTINCT zero-token outcome; a forbidden-zone verdict escalates before spend) → **checks
+preflight** (every SIGNED check runs once at $0 — an unrunnable check is a `check-red`
+stop before tokens, not a fault mid-plan) → **SCOUT** (read-only by construction: the
+write verbs are not 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
+fed back, then `plan-red`) → **EXECUTE** (strictly sequential micro-loops: `ralph` with
+the exit-evaluator judge; tree snapshots at step start; the gap names every failing
+wall — mechanical genre, F46's measured mechanism; artifacts feed forward labeled by
+step id) → **ONE replan**, triggered by exhaustion only (an instrument stop never
+replans) → **the operator's close**, a red feeding ONE bounded fix loop judged by the
+REAL close. `plan-executed` (the plan-as-executed record, design law #2) lands on the
+spine on every path that executed steps. Additional outcomes: `already-green |
+plan-red | check-red | close-red`. Worker prompts hold the v1.12 §5 contract
+(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.
+
+**Two worker surfaces — API and native clipipe (BA-16, module 4d).** The plan flow is
+provider-agnostic: the close, the checks, and the exit evaluator are commands and form
+checks, so ONLY the worker differs. `job.provider === 'clipipe-subscription'` drives tools
+NATIVELY (the `claude` CLI owns the turn cycle) instead of through the `Loop`; every other
+provider runs the Loop unchanged (byte-identical — the API path cannot regress). Native
+governance is **constructor-time and per-worker**, so the runner cannot reuse one injected
+instance: pass `opts.nativeProvider`, a FACTORY the runner calls fresh per worker as
+`({ policy, onTurn?, maxTurns, hasTools }) => provider`. Return the right mode by `hasTools`:
+`true` → native tool mode (`toolProtocol:'claude-mcp'`, wire the gate's `policy` + `onTurn` +
+`maxTurns` onto the provider — the SAME `wireGate` fence, so a write outside the scope is
+DENIED at the bridge, live-proven); `false` → the toolless drafter, where a native session
+reports NO cost, so return a metered claude-json TEXT provider (`--output-format json`,
+`parse:'claude-json'`) — never an unmetered, invisible-spend session. A missing factory on a
+`clipipe-subscription` job is `interpreter-red`, never a silent fall-back to the metered API.
+Money reconciles PER SESSION (the CLI prices the session, `costUsd` null per turn,
+authoritative at close): the accounted `worker-round` is the session total, per-turn
+`worker-turn` events are attribution only. `maxTurns` (→ CLI `--max-turns`) is the
+per-attempt bound and surfaces `max_turns` as a BOUNDED attempt (judged, gap fed forward),
+the native analog of `loop.stop()`. Live-validated green end-to-end on the real CLI; the
+Loop path is untouched.
+
 **Resume-to-cap (close-first skip):** every predicate step runs its close FIRST, before
 any tokens (`close-precheck` on the spine, output scrubbed at capture like every close).
 Already-green skips the step for zero tokens as a DISTINCT record — `step-end` outcome

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bareloop",
-  "version": "0.3.0",
+  "version": "0.5.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",
@@ -23,7 +23,7 @@
     "prepublishOnly": "npm run build:types"
   },
   "dependencies": {
-    "bare-agent": "^0.29.0",
+    "bare-agent": "^0.33.1",
     "bareguard": "^0.12.0",
     "litectx": "^0.29.1"
   },