bareloop 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -7,6 +7,117 @@ 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

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-Layer%20R%20%C2%B7%20ratchet%20armed-2a6d3a" alt="status: Layer R, ratchet armed">
+  <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,15 +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: Layer R — the within-run ratchet is built and armed.** `runJob()` takes a
-> signed job spec through draft → per-step worker loops → close verdicts → draft PR,
-> under one budget the agent can only tighten; the shell now also detects a worker
-> stuck repeating itself and feeds back its own failed attempts (escalating
-> summary→verbatim). Two frozen probes found the disease in remission under the current
-> loop (F41: 0 fixated pairs in 14, jobs #1/#2/#4), so the ratchet ships inert-by-
-> measurement with its field read deferred to the first run that trips it. Next is
-> Layer 2 (plan-v1 micro-wheels), then executed inheritance (N3) — the ladder's
-> kill-switch question.
+> **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
 

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`
 
@@ -310,7 +385,7 @@ default-enabled until a stuck job (Layer 2, or a manufactured-fixation probe) sh
 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, emit, target?, capRuns?, shellCapUsd?, closeTimeoutMs?, execCmd?, layerRoot? })` → outcome — `src/run.js`
+### `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
@@ -349,6 +424,49 @@ launder a missing `spentUsd` into `$0`. A text-mode job invoked without `opts.ta
 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.4.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"
   },

package/src/exits.js

@@ -0,0 +1,163 @@
+// Layer 2: the exit evaluator — the SHELL's own fixed code for the closed
+// exit menu (PRD v1.12 §3). An exit is declarative data; nothing here ever
+// executes agent-authored text. Doctrine wired in, not promised:
+//
+//   - exits verify FORM, not truth: progress gates only; the operator's close
+//     stays the one arbiter (checks decide nothing, mint nothing).
+//   - `tree-changed` reads OUTCOME — real bytes vs a pre-step snapshot taken
+//     by `snapshotScope` — never git status (always shows the planted bug,
+//     F45) and never gate intent (the F43 identical-refire trap: an allowed
+//     write that lands the same bytes is NOT a change).
+//   - a failing exit's detail is a MECHANICAL gap (a named wall, a count) —
+//     the genre that converts (F38/F46); details carry names and counts only,
+//     never file bodies (they ride the spine, which is append-only forever).
+//   - `check-passes` delegates through the `runCheck` seam the runner wires
+//     to the full runClose machinery; the evaluator itself never spawns. An
+//     unwired or throwing check fails CLOSED (the broken-close class: an
+//     unrunnable check is a stop, never a silent pass).
+
+import { createHash } from 'node:crypto';
+import { readFile, readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { globToPrefix } from './validate.js';
+
+/** The check gap is ALREADY bounded upstream by runClose's boundGap (head +
+ * gapKeep block ≤ 8192 + tail ≈ 10KB, with the failing-test NAMES preserved).
+ * The evaluator must NOT re-truncate it: a 400-char clamp deletes exactly those
+ * `not ok`/`FAILED` names — the mechanical gap the F46 conversion mechanism
+ * feeds the worker (F28 reintroduced). This cap is a defensive backstop above
+ * boundGap's own envelope: a normal bounded gap passes through intact, and only
+ * a pathological seam that returned an unbounded gap would ever be trimmed. */
+const CHECK_GAP_MAX = 12000;
+
+/** @typedef {{ type: string, pass: boolean, detail?: string, fault?: string }} ExitResult
+ * `fault` present means the INSTRUMENT could not judge (unwired snapshot/seam,
+ * a check in runClose's forbidden zone) — it carries the runClose verdict name
+ * ('failed'|'timed-out'|'killed'|'crashed') so the micro-loop escalates through
+ * the same CLOSE_FAULTS taxonomy instead of feeding a fake gap to the worker.
+ * A plain pass:false with no fault is honest worker feedback. */
+
+/**
+ * Snapshot the file state under a scope prefix — the "before" side of
+ * `tree-changed`. Content hashes, not mtimes: only real bytes count as
+ * outcome. A scope directory that does not exist yet snapshots empty (the
+ * step creating it IS the change). Never throws on a missing dir.
+ * @param {string} dir absolute workdir (the run directory)
+ * @param {string} scope a validated scope glob (e.g. `tests/**`)
+ * @returns {Promise<Map<string, string>>} relative path → sha256
+ */
+export async function snapshotScope(dir, scope) {
+  const prefix = globToPrefix(scope);
+  /** @type {Map<string, string>} */
+  const snap = new Map();
+  /** @type {string[]} */
+  let entries;
+  try {
+    entries = /** @type {string[]} */ (await readdir(join(dir, prefix), { recursive: true, encoding: 'utf8' }));
+  } catch {
+    return snap; // missing scope dir = empty snapshot, never a throw
+  }
+  for (const rel of entries) {
+    const full = join(dir, prefix, rel);
+    let body;
+    try { body = await readFile(full); } catch { continue; } // directories and vanished files skip
+    snap.set(`${prefix}/${rel.replaceAll('\\', '/')}`, createHash('sha256').update(body).digest('hex'));
+  }
+  return snap;
+}
+
+/**
+ * Evaluate a step's exits — AND-only (decision 8): the step passes iff EVERY
+ * listed exit passes. All exits are evaluated (never short-circuit): the gap
+ * must name every wall, not the first one hit.
+ * @param {Array<Record<string, any>>} exits validated exit items
+ * @param {{ dir: string, snapshot?: Map<string, string>, runCheck?: (name: string) => Promise<{pass: boolean, gap?: string}> }} ctx
+ *   `dir`: the run directory; `snapshot`: the pre-step `snapshotScope` result
+ *   (required by tree-changed — absent fails closed); `runCheck`: the runner's
+ *   runClose-backed seam (required by check-passes — absent fails closed).
+ * @returns {Promise<{ pass: boolean, results: ExitResult[] }>}
+ */
+export async function evalExits(exits, { dir, snapshot, runCheck }) {
+  /** @type {ExitResult[]} */
+  const results = [];
+  for (const e of exits) {
+    results.push(await evalOne(e, { dir, snapshot, runCheck }));
+  }
+  return { pass: results.every((r) => r.pass), results };
+}
+
+/**
+ * @param {Record<string, any>} e
+ * @param {{ dir: string, snapshot?: Map<string, string>, runCheck?: (name: string) => Promise<{pass: boolean, gap?: string}> }} ctx
+ * @returns {Promise<ExitResult>}
+ */
+async function evalOne(e, { dir, snapshot, runCheck }) {
+  if (e.type === 'artifact-written') {
+    let body;
+    try { body = await readFile(join(dir, e.path), 'utf8'); } catch {
+      return { type: e.type, pass: false, detail: `${e.path} was not written (does not exist)` };
+    }
+    if (body.length === 0) return { type: e.type, pass: false, detail: `${e.path} is empty — a zero-byte artifact is not progress` };
+    if (e.pattern !== undefined && !new RegExp(e.pattern, 'm').test(body)) {
+      return { type: e.type, pass: false, detail: `${e.path} exists but does not match the declared pattern ${e.pattern}` };
+    }
+    return { type: e.type, pass: true };
+  }
+
+  if (e.type === 'tree-changed') {
+    if (!(snapshot instanceof Map)) {
+      // fail CLOSED as a FAULT: without the before-side this instrument is
+      // blind — it must never read "changed" (F45) and never feed the miss to
+      // the worker as if it were inaction
+      return { type: e.type, pass: false, fault: 'failed', detail: `no pre-step snapshot for ${e.scope} — the tree-changed instrument is unwired (instrument fault, not worker inaction)` };
+    }
+    const now = await snapshotScope(dir, e.scope);
+    // deletions count only WITHIN this exit's own scope: the step's `snapshot`
+    // is merged across every tree-changed scope, so an unscoped keys() walk
+    // would read a SIBLING scope's files (absent from this re-scan) as deletions
+    // and pass an unchanged scope by borrowing the other's change.
+    const prefix = globToPrefix(e.scope);
+    const underScope = (/** @type {string} */ p) => p === prefix || p.startsWith(`${prefix}/`);
+    let changed = 0;
+    for (const [path, hash] of now) if (snapshot.get(path) !== hash) changed++;
+    for (const path of snapshot.keys()) if (underScope(path) && !now.has(path)) changed++; // deletions are real changes
+    if (changed === 0) {
+      return { type: e.type, pass: false, detail: `0 files changed under ${e.scope} — the tree is byte-identical to the step start (an identical re-write is not a change)` };
+    }
+    return { type: e.type, pass: true, detail: `${changed} file(s) changed under ${e.scope}` };
+  }
+
+  if (e.type === 'json-valid') {
+    let body;
+    try { body = await readFile(join(dir, e.path), 'utf8'); } catch {
+      return { type: e.type, pass: false, detail: `${e.path} was not written (does not exist)` };
+    }
+    try { JSON.parse(body); } catch (err) {
+      return { type: e.type, pass: false, detail: `${e.path} is not valid JSON: ${String(/** @type {Error} */ (err).message).slice(0, 200)}` };
+    }
+    return { type: e.type, pass: true };
+  }
+
+  if (e.type === 'check-passes') {
+    if (typeof runCheck !== 'function') {
+      return { type: e.type, pass: false, fault: 'failed', detail: `check "${e.name}" cannot run — runCheck is not wired (instrument fault: an unrunnable check is a stop, never a silent pass)` };
+    }
+    try {
+      const r = await runCheck(e.name);
+      if (r.pass) return { type: e.type, pass: true };
+      // the seam's fault (a runClose forbidden-zone verdict) rides through by
+      // NAME: 'crashed' keeps its F32 routing (worker-crash after writes —
+      // the F46 broken-test mechanism), 'timed-out' keeps its own decision
+      if (typeof (/** @type {any} */ (r).fault) === 'string') {
+        return { type: e.type, pass: false, fault: /** @type {any} */ (r).fault, detail: `check "${e.name}": ${(r.gap ?? '').slice(0, CHECK_GAP_MAX)}` };
+      }
+      return { type: e.type, pass: false, detail: `check "${e.name}" red: ${(r.gap ?? '').slice(0, CHECK_GAP_MAX)}` };
+    } catch (err) {
+      return { type: e.type, pass: false, fault: 'failed', detail: `check "${e.name}" crashed the seam: ${String(/** @type {Error} */ (err).message).slice(0, 200)}` };
+    }
+  }
+
+  // belt — the validator already reds unknown types; the evaluator must not
+  // silently pass what it cannot judge
+  return { type: String(e.type), pass: false, fault: 'failed', detail: `unknown exit type "${e.type}" — the evaluator cannot judge it (fail closed)` };
+}

package/src/index.js

@@ -16,7 +16,13 @@ export { makeSpine } from './spine.js';
 // exports map admits only ".", so a deep import cannot reach them).
 export { ralph, runClose, CLOSE_FAULTS } from './ralph.js';
 export { validateConfig, diffPaths, globToPrefix, scanSecrets, LOOP_SHAPES, SLOTS, VERBS } from './validate.js';
-export { validateJob, jobSpecHash, checkApproval, CLOSE_TYPES, CLASSES, CLASS_BY_CLOSE, GOLD_COMPARE, CADENCE_UNITS, PROVIDERS, CONDITION_KEYS, STEP_MODES, TOOL_MENU, LOCKED_TOOLS } from './job.js';
+export { validateJob, jobSpecHash, checkApproval, CLOSE_TYPES, CLASSES, CLASS_BY_CLOSE, GOLD_COMPARE, CADENCE_UNITS, PROVIDERS, CONDITION_KEYS, STEP_MODES, TOOL_MENU, LOCKED_TOOLS, VERDICT_TYPES, LOCKED_VERDICTS } from './job.js';
+// Layer 2: the plan-v1 validator — the agent-authored plan doc's gate; the
+// two-doc split's third validator never happens (plan-v1 gates the PLAN, the
+// job spec stays the arbiter's only home).
+export { validatePlan, EXIT_TYPES, MAX_EXITS_PER_STEP, MAX_PLAN_STEPS, WRITE_VERBS } from './plan.js';
+export { snapshotScope, evalExits } from './exits.js';
+export { runPlan } from './planrun.js';
 export { interpret, STALL_REDS } from './interpret.js';
 export { extractRules, MAX_RULES, MAX_RULE_CHARS } from './extract.js';
 export { runJob } from './run.js';