bareloop 0.16.0 → 0.18.0

package/CHANGELOG.md

@@ -5,7 +5,57 @@ 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.18.0] — 2026-08-31
+
+### Added
+
+- **Close stages declare their comparison direction (F120).** `job-v1` close stages gain an
+  optional `direction: 'up'|'down'` field; absent means `'down'` (unchanged behaviour for
+  every existing close). `src/trend.js`'s close-fix governor hardcoded lower-is-better —
+  wrong for a rate-shaped close, where up is better — and cap-halted a converging G2 run
+  for improving (live on `u-mtgr1qnu`); a mirror defect funded a collapsing rate as
+  progress. Direction is never inferred from goal prose and never LLM-judged; a new
+  `isBetter(stage,a,b)` helper in `src/trend.js` drives `countImproved` and both
+  `best`-tracking sites, `createTrend` gains a `directions` option, `STAGE_FIELDS`
+  (`src/job.js`) validates the field against an allow-list. `scripts/run-u.mjs` prints each
+  stage's direction at the close-stage banner. 7 new tests, each proven failing against the
+  old code first; both production job hashes independently re-verified unchanged.
+
+### Changed
+
+- **`--read-shim` defaults to A1 (cap) in `scripts/run-u.mjs`** (hamr's call, 2026-08-31).
+  `--read-shim off` restores A0. The three frozen bench rows in `docs/product/BENCH-PREREG.md`
+  pin `off` explicitly, so their baselines keep the condition they were established under —
+  no bench re-baseline required or paid.
+
+### Fixed
+
+- **`resolveWorkerModel` is now exported from the package root.** `bareloop.context.md`
+  names it as the spec-model resolution mechanism, but v0.17.0 shipped it reachable only
+  in-repo (`src/job.js`) — the exports map admits only `.`, so an adopter could not import
+  it. Documented-but-unexported is a false contract (same rule that exported `checkMenu`);
+  caught by validating the installed 0.17.0 artifact from the registry. Additive only.
+- **G2 cold-variant `clean-run` close dropped a vacuous stage.** The borrowed
+  `changed-from-seed` stage compared against a seed manifest that can never show a change
+  on a genuinely cold patient (zero files under `tests/testgen/` at seed), firing a spurious
+  `unchanged-red` before the worker had written anything. New
+  `scripts/testgen-cold-check-close.mjs` (grader-identical minus that stage);
+  `jobs/aurora-testgen-cold.json`'s `clean-run` stage repoints to it. Live-proven: the
+  re-establish run recorded zero `unchanged-red` events.
+
+## [0.17.0] — 2026-08-31
+
+### Added
+
+- **Publish workflow gates on the types being usable BY AN ADOPTER, not just internally.** `npm run typecheck` (`tsc --noEmit`) checks the *source*; it cannot see the generated `.d.ts` as an adopter resolves it from inside `node_modules`, which is the one thing consumers actually get. The publish workflow now packs the tarball, installs it into a clean consumer project, and compiles a quickstart against it, so a release whose published types are broken cannot reach the registry.  The consumer pins `@types/node` to the major this package builds against instead of floating to the newest, so a stricter DefinitelyTyped release cannot turn the publish gate red for reasons unrelated to the commit being published. Verified locally: the quickstart compiles green against a packed tarball, and a deliberately broken dereference fails it. CI only — no runtime or published-artifact change.
+
+- **Worker model name in the signed spec (build-list #3)**: `job-v1` gains an optional
+  `model` field — a non-empty string naming the exact worker provider model id. Absent,
+  behaviour is unchanged (the runner's own default); present, it is part of the signed
+  spec hash and `scripts/run-u.mjs` runs the job on that model. A `--model <tier>` flag
+  naming a different model is refused (`resolveWorkerModel`, `src/job.js`) rather than
+  silently overridden — the spec always wins. Worker only; the judge model stays
+  library-pinned pending recalibration.
 
 ## [0.16.0] — 2026-08-30
 

package/bareloop.context.md

@@ -52,6 +52,35 @@ inherited rule carries the green that minted it and the contrast that attributed
 - **Is not:** a general agent, a swarm, or an orchestrator framework. One-off or small
   jobs are out of scope — that's a CLI session, not a bareloop job.
 
+## Which mode / components do I need?
+
+- **Verdict class — how "done" gets decided:** `green` (a mechanical close: exit code =
+  truth, `src/kinds.js` `LIVE_KINDS`) is the default and the only class with a live-proven
+  paid run. `soft-green` (a judged floor behind a signed calibration gate, plus a review
+  door) is fully admitted (`VERDICT_TYPES`, `src/job.js:106`) but has never rendered a live
+  verdict — see `## Public API` → "THE JUDGED FLOOR" and "THE REVIEW DOOR" below. `hitl` is
+  LEGACY: still admitted (removal is a future breaking change) but retired as a design
+  (PRD Addendum v1.71); its pause machinery lives on as the review door, not as a class to
+  pick for new jobs.
+- **Worker surface — how the agent runs:** `provider: 'anthropic-api'` (the default, the
+  only one with an operational guarantee, F48) drives `bare-agent`'s `Loop` and takes the
+  shell-owned `provider` binding. `provider: 'clipipe-subscription'` (`src/job.js:135`)
+  drives the worker natively over the Claude CLI's own tool channel and requires
+  `opts.nativeProvider` in `runJob`/`runPlan` — its `costUsd` axis is notional, never pools
+  with `anthropic-api` on cost, and budgets don't transfer between them.
+  `job.provider === 'clipipe-subscription'` with no `nativeProvider` supplied is
+  `interpreter-red`, never a silent fall-back to the metered API (`src/planrun.js:1073`).
+- **Reuse — where a workflow comes from:** a plain `runJob` always drafts cold. Passing
+  `bridge` starts from one standalone bridge file (`src/reuse.js`'s envelope, `## The reuse
+  ENVELOPE and runReuse` below). The CLI's `--registry <dir>` / library-level `registryDir`
+  (`src/reuse.js`, `scripts/run-u.mjs`) instead reads/writes dated rows in an
+  operator-supplied directory of plain JSON files — no database, no default location; a
+  named-but-missing registry is a red, never conjured (`## The reuse registry (Layer 3)`
+  below).
+- **Read shim:** `readShim` defaults to `false` on both `runJob` (`src/run.js:205`) and
+  `runPlan` (`src/planrun.js:808`) — the OFF arm wraps nothing at all. Opt in with `true`,
+  `'cap'`, or `'diff'` (`src/readshim.js`) only once the read-hygiene tradeoff is wanted.
+
 ## Minimal usage
 
 ```js
@@ -106,6 +135,7 @@ minting claim, or the shell-owned retry cap — all unknown-field reds.
 | `cadence` | `{ unit: hour\|day\|week, every: 1..30 }` | validated now, consumed at N5 (Scheduler) |
 | `budgetUsd` | `0 < n <= shell cap` | ceiling chain: workflow ≤ job ≤ shell — each layer may tighten, never exceed |
 | `maxWallMs` | optional integer ms `>= MIN_WALL_MS` (one close timeout) | the run's wall clock. **NO DEFAULT, by ruling** — absent means time-unbounded *by explicit operator choice*, never by fallback (F45: a defaulted cap is a silent second ceiling). Enforcement is a BETWEEN-ROUND deadline, so the honest worst case is `maxWallMs + closeStages × closeTimeoutMs` — every stage of a staged close gets the FULL timeout — and all three numbers are reported (`loop.stop()` cannot cut an in-flight call — F61 measured 500ms→4,018ms). The `MIN_WALL_MS` floor is a ONE-stage number, so a spec with many stages can validate while its overshoot dwarfs its cap: the clock reports that honestly rather than the floor pretending to prevent it (stage-aware floor parked, PRD v1.39). Operator-only, tighten-only; adding or changing it changes the spec hash |
+| `model` | optional non-empty string, exact provider model id (e.g. `"claude-sonnet-5"`) | the WORKER's model, build-list #3. Absent means today's runner default; present it wins over a `--model` flag outright, and a flag naming a different id is refused (`resolveWorkerModel`, `src/job.js`) rather than silently overridden. Part of the signed hash like every other field. Worker only — the judge model stays library-pinned (`JUDGE_MODEL`) pending recalibration |
 | `writeScope` | array of contained globs | the operator's outer fence; the plan's own scopes must fit inside it, same containment code |
 | `steps` | RETIRED | operator-authored `steps[]` was deleted (PRD v1.32); a spec carrying it reds `shape-retired:steps` by name rather than half-running |
 | `escalation` | `{ mode: "decision-ready" }` | the pain channel is not optional |
@@ -117,7 +147,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). **All three are ADMITTED today** — `LOCKED_VERDICTS` is empty, so nothing reds `request-red` on the class itself. `soft-green` has its judged floor (`judged-floor`, signed rubric card + calibration gate) and is the forward path for a job needing judgement, paired with the end-of-run review door; `hitl` is LEGACY — retired as a design direction (see the direction note at the top) but still admitted and still works exactly as documented here. Every `request-red` (e.g. for a locked TOOL verb, not a verdict class) 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) | 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 still VALIDATES (`CLOSE_TYPES`) but the plan flow refuses all three at runtime as `close-unsupported` — an object close names no command to run. The modern route to a judged or human-decided close is a staged `closeDecl` (`judged-floor` / `human-confirms` stage kinds), not this object form |
+| `close` | **an ORDERED LIST of named stages** `[{ name, cmd, expect, judged?, gapKeep?, offer?, needs?, direction? }, ...]` (PRD v1.28), or a close object (table below) | 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 still VALIDATES (`CLOSE_TYPES`) but the plan flow refuses all three at runtime as `close-unsupported` — an object close names no command to run. The modern route to a judged or human-decided close is a staged `closeDecl` (`judged-floor` / `human-confirms` stage kinds), not this object form |
 | `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 |
@@ -175,6 +205,7 @@ contract the single close object has always used) plus:
 | `name` | unique kebab-case slug | the plan references it via `check-passes(name)`; duplicates red `duplicate-id` |
 | `offer` | optional boolean, default offered | `offer: false` hides the stage from the derived menu — it never reaches the agent. For a stage that cannot stand alone as a ruler: a PRECONDITION (e.g. "the seed commit exists" — passes instantly, teaches nothing) or the **final grading stage** — of the ten specs in `jobs/`, four hide a final `verdict` stage and six hide a `changed-from-seed` precondition instead (a per-spec convention, not a schema rule — nothing stops a stage named last from being offered except the spec author remembering to set the flag; preflight's `check-menu` event always names the full menu either way, so a forgotten flag is visible in the run's own record) |
 | `needs` | optional non-empty array of EARLIER stage names | a stage that reads what an earlier stage built (e.g. "the public API matches what an earlier stage emitted") names its prerequisite chain; picking it via `check-passes` runs the chain first, then the stage itself. Every name must be declared before this stage (`invalid-value` otherwise); `needs` + `offer: false` together is incoherent (`invalid-value`) — a stage with a chain to run must be reachable |
+| `direction` | optional `'up'` \| `'down'`, allow-list validated (anything else is `invalid-value`) | which way this stage's numeric series is READING as progress — `'down'` (fewer is better: typecheck errors, suppressions) or `'up'` (more is better: a fault-detection rate). **Absent means `'down'`** — every close built before this field existed is a count-shaped close, so the silent default is behaviour-identical for all of them (F120). Never inferred from the goal text and never LLM-judged — prose the agent writes must never influence its own halt rule, the same reasoning that keeps every close hand-authored or declared, never judged. Consulted by `isBetter(stage,a,b)` in `src/trend.js`, the one place the close-fix governor's `countImproved` and `best`-tracking read direction; `scripts/run-u.mjs` prints each stage's direction at the close-stage banner so a silent default is never invisible |
 
 The stages run in declared order as the close itself; the first red renders the verdict and
 later stages never run. `checkMenu(close)` returns only the offerable stages (each with its
@@ -2480,6 +2511,73 @@ JSONL spine (single source for every UI), litectx store per job, per-run ledger.
 the bare suite: bareagent, bareguard, litectx, barebrowse, baremobile — the full surface
 is disclosed to the authoring agent; only admitted verbs are callable per job.
 
+## Extension contract
+
+hamr's law, verbatim: **the agent may author anything whose only verbs are gated
+primitives; it may never author the arbiter — the close, the budget, the fence, the
+merge.** What an adopter can plug into `runJob` (`src/run.js:205`):
+
+- **Providers.** `provider` (shell-owned LLM binding for the `Loop`/API path),
+  `nativeProvider` (a factory required for a `clipipe-subscription` job),
+  `providerFor(tier)` (per-step model-tier provider, forwarded to the plan flow), and
+  `judgeProvider` (SOFTGREEN's own seam — the provider a judged close stage runs its
+  locate-only call through; distinct from `provider`/`providerFor` because the judge tier
+  is fixed, never the worker's). All four are documented at `src/run.js:91-101`.
+- **Close stage kinds.** The catalogue is fixed and enumerated (`LIVE_KINDS`,
+  `src/kinds.js:142`: `command-exit`, `count-not-worse`, `pattern-absent-in-diff`,
+  `files-changed`, `human-confirms`, `judged-floor`). An adopter's declaration SELECTS
+  from this menu; it never authors a new kind — a stage naming an unimplemented or unknown
+  kind is a hard runtime stop (`src/kinds.js:1885-1888`), not a way to run adopter code
+  inside the close.
+- **`emit` — the spine sink.** `makeSpine(file)` (`src/spine.js:21`) returns an
+  `emit(type, data)` that appends one JSONL line per event; any function with that
+  signature can stand in as a custom sink, but it is write-only — nothing in bareloop reads
+  the spine back, so a custom sink cannot feed anything into a run's own decisions.
+- **`rates` is NOT an extension point.** A rates passthrough was designed but never built;
+  pricing is guesstimate-plus-loud-`estimated`-flag by ruling, and rate tables are the
+  customer's own responsibility, not a bareloop seam to wire up.
+
+Everything else in `runJob`'s options — budgets, caps, the close, the fence, merge/publish
+— is arbiter territory and is never adopter-suppliable as behavior, only as signed,
+schema-validated data.
+
+## Threat model summary
+
+**Local-trust model, NOT a sandbox.** The worker runs with the OS user's own permissions.
+Both the close (`src/ralph.js:222`) and a declared close stage's environment
+(`src/kinds.js:351`) start from a full copy of `process.env` and spawn child processes
+under it — this is a passthrough, not a jail.
+
+**What the arbiter guarantees:**
+- **Cap-not-estimate money and time.** `budgetUsd` is validated `0 < budget <= shellCapUsd`
+  with the check's own name, `cap-not-estimate` (`src/job.js:227`); spend is never a
+  projection.
+- **A signed spec hash refuses drift.** `jobSpecHash`/`checkApproval` (`src/job.js:703,
+  723`) mean an edited spec is unapproved by construction; `runJob` red-lines
+  `'unapproved-spec'` before any provider call if no approval record matches the exact spec
+  version (`src/run.js:289-290`).
+- **Secrets never enter the tree, the spine, the ledger, or a close's child process.**
+  `redactSecrets` (`src/validate.js:130`) scrubs at every emission boundary in the
+  authoring path; `CLOSE_ENV_DENY` (`src/ralph.js:136-153`) strips provider keys and
+  known credential-shaped env-var names from the copy of `process.env` handed to a close
+  child, by name/prefix/suffix-shape — a strip of a COPY, so the host process (and
+  bare-agent, which reads the real key every round) keeps its own credentials.
+- **The worker is fenced off the arbiter's own books.** The authoring scout's read scope
+  denies the gate audit path and every `ARBITER_BOOK_STORES` path under the workdir
+  (`src/authorscout.js:295`); a plan step's read scope is the workdir alone
+  (`src/planrun.js:1894`).
+
+**What it does not guarantee:** no network egress control and no container/VM isolation —
+this repo has neither built nor documented either. `CLOSE_ENV_DENY`'s deny rule matches
+only credential-shaped names (`src/ralph.js:136-153`); any env var that doesn't match that
+shape passes through to the close's child process untouched. `SSH_AUTH_SOCK` is one of them
+and stays on purpose — stripping it would break git-over-SSH inside a close — but the deny
+list itself carries no comment saying so; this paragraph is the record.
+
+**What an adopter must do:** keys load from the environment only (`.env.example` below);
+the patient is always a COPY of the target repo, never the original — the copy is the
+blast radius.
+
 ## What's NOT in bareloop, and why
 
 - **No agent-authored arbiters.** Closes, budgets, caps, merge/publish decisions live

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "bareloop",
-  "version": "0.16.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.",
+  "version": "0.18.0",
+  "description": "Workflows that earn their own design, with receipts \u2014 agent-authored workflows for repeated, long, verifiable jobs that improve across runs under an un-gameable gate.",
   "type": "module",
   "main": "./src/index.js",
   "types": "./types/index.d.ts",

package/src/index.js

@@ -24,7 +24,7 @@ export { makeSpine } from './spine.js';
 // name. Documented-but-unexported is a false contract; the additions are additive.
 export { ralph, runClose, runStages, CLOSE_FAULTS } from './ralph.js';
 export { globToPrefix, scanSecrets } from './validate.js';
-export { validateJob, jobSpecHash, checkApproval, checkMenu, CLOSE_TYPES, CLASS_BY_CLOSE, GOLD_COMPARE, CADENCE_UNITS, PROVIDERS, CONDITION_KEYS, TOOL_MENU, LOCKED_TOOLS, STORE_VERBS, VERDICT_TYPES, LOCKED_VERDICTS } from './job.js';
+export { validateJob, jobSpecHash, checkApproval, checkMenu, resolveWorkerModel, CLOSE_TYPES, CLASS_BY_CLOSE, GOLD_COMPARE, CADENCE_UNITS, PROVIDERS, CONDITION_KEYS, TOOL_MENU, LOCKED_TOOLS, STORE_VERBS, 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).

package/src/job.js

@@ -140,7 +140,7 @@ export const CONDITION_KEYS = Object.freeze(['providerPath', 'closeVerbosity', '
 // `steps` stays in the field list ONLY so a retired spec reds by name
 // (`shape-retired`) instead of falling through to a generic unknown-field —
 // the operator gets told what happened, not just that something is wrong.
-const JOB_FIELDS = ['schema', 'job', 'description', 'provider', 'conditions', 'cadence', 'budgetUsd', 'maxWallMs', 'writeScope', 'steps', 'escalation', 'goal', 'verdictType', 'close', 'closeDecl', 'checks', 'tools'];
+const JOB_FIELDS = ['schema', 'job', 'description', 'provider', 'conditions', 'cadence', 'budgetUsd', 'maxWallMs', 'model', 'writeScope', 'steps', 'escalation', 'goal', 'verdictType', 'close', 'closeDecl', 'checks', 'tools'];
 /** the four-field plan shape's core (decision 5) — presence of any of these
  * declares the shape; `tools` (the ceiling) rides the shape but alone does not
  * declare it, so a legacy spec carrying it gets a pointed red, not a conflict */
@@ -240,6 +240,17 @@ export function validateJob(input, { shellCapUsd = 2 } = {}) {
       `integer milliseconds >= ${MIN_WALL_MS} (one close timeout). Enforcement is a between-round deadline, measured as maxWallMs + closeStages x closeTimeoutMs (design addendum 1: loop.stop() cannot cut an in-flight call; W5: every close stage runs under the full timeout), so a budget under one close cannot fund its own close and the advertised number would be more wrong than right`);
   }
 
+  // MODEL — the worker's provider model id (build-list #3, hamr's GO
+  // 2026-08-30). OPTIONAL, exactly like budgetUsd/maxWallMs before it: absent
+  // means today's behaviour (the runner's own default), present it is part
+  // of the signed hash — jobSpecHash canonizes the whole resolved spec
+  // (resolveSpec), so a spec that names a model is an operator signing off
+  // on THAT model, not merely on the goal/close it runs against. The judge
+  // model stays library-pinned pending recalibration — out of scope here.
+  if (spec.model !== undefined && !isNonEmptyString(spec.model)) {
+    red('invalid-value', 'model', 'non-empty string — exact provider model id (e.g. "claude-sonnet-5")');
+  }
+
   // 3. the outer write fence — operator law (interview decision #4), same
   // containment rules as the workflow layer THROUGH THE SAME CODE (F9: two
   // transforms would let a fence validate green and mean something else).
@@ -481,7 +492,7 @@ export function checkMenu(close) {
 }
 
 /** the fields a close STAGE may carry — anything else is a smuggle channel */
-const STAGE_FIELDS = ['name', 'cmd', 'expect', 'judged', 'gapKeep', 'offer', 'needs'];
+const STAGE_FIELDS = ['name', 'cmd', 'expect', 'judged', 'gapKeep', 'offer', 'needs', 'direction'];
 
 /**
  * Validate the staged close. Every stage is a predicate BODY under the same
@@ -523,6 +534,17 @@ function validateStagedClose(stages, red) {
         if (bad.length) red('invalid-value', `${at}.needs`, `must name stages declared BEFORE this one (a prerequisite that has not run yet cannot be one): ${bad.join(', ')} — earlier stages: ${[...earlier].join(', ') || 'none'}`);
       }
     }
+    // the close-fix governor's comparison direction (2026-08-31 ruling, hamr's
+    // option A): a signed, per-stage field, never inferred from goal prose and
+    // never LLM-judged. 'up' = higher is better (a rate of good things caught,
+    // e.g. mutation-kill %); 'down' = lower is better (a count of bad things
+    // remaining, e.g. typecheck errors or suppressions). Absent means 'down' —
+    // the field defaults to the trend reader's pre-existing behaviour exactly,
+    // so every close authored before this field existed keeps an IDENTICAL
+    // spec hash (an absent field adds nothing to the hash).
+    if (s.direction !== undefined && s.direction !== 'up' && s.direction !== 'down') {
+      red('invalid-value', `${at}.direction`, `"up" or "down" — up means higher is better (a rate of good things caught), down means lower is better (a count of bad things remaining); omit for down (the default)`);
+    }
   });
 }
 
@@ -732,3 +754,30 @@ export function checkApproval(job, approvals) {
   const h = createHash('sha256').update(c).digest('hex');
   return approvals.some((a) => isObj(a) && /** @type {Record<string, unknown>} */ (a).specHash === h);
 }
+
+/**
+ * Pure decision: which worker model id a run actually uses (build-list #3,
+ * hamr's GO 2026-08-30). The signed spec's `model`, if present, is what an
+ * operator SIGNED — it wins outright. A `--model` runner flag naming a
+ * DIFFERENT id is refused rather than silently overridden (spec wins, a
+ * mismatched flag is a mistake worth stopping on, never a silent swap); the
+ * same id from both is not a conflict. Extracted from scripts/run-u.mjs so
+ * the decision is testable without running the script or touching a provider.
+ * @param {{ specModel?: string, flagModel?: string, defaultModel: string }} args
+ *   `specModel` — `job.model` if the signed spec carries one, else undefined.
+ *   `flagModel` — the model id an explicit `--model <tier>` resolved to, else
+ *   undefined (a flag that was never passed, not merely a default tier name).
+ *   `defaultModel` — the runner's own default when neither spec nor flag says.
+ * @returns {{ model: string, source: 'spec'|'flag'|'default' }}
+ * @throws {Error} when the spec names a model and the flag names a different one
+ */
+export function resolveWorkerModel({ specModel, flagModel, defaultModel }) {
+  if (specModel !== undefined) {
+    if (flagModel !== undefined && flagModel !== specModel) {
+      throw new Error(`spec names model "${specModel}" but --model resolved to "${flagModel}" — the signed spec wins; a mismatched --model flag is refused, never silently overridden. Drop --model or point it at the same model.`);
+    }
+    return { model: specModel, source: 'spec' };
+  }
+  if (flagModel !== undefined) return { model: flagModel, source: 'flag' };
+  return { model: defaultModel, source: 'default' };
+}

package/src/planrun.js

@@ -1363,7 +1363,13 @@ export async function runPlan(job, { workdir, provider, nativeProvider, provider
    * an unchanged tree is flat on its own evidence while the RUN — the thing the human
    * is deciding about — may have been converging when its allowance ran out. Cold, the
    * seed is empty and this is byte-identical to the pre-resume reader. */
-  const runTrend = createTrend({ stageOrder: stagedClose.map((/** @type {any} */ s) => s.name), seed: resumeGrades });
+  // per-stage comparison direction, read straight off the signed close (2026-08-31
+  // ruling): a stage absent here — every close authored before this field existed
+  // included — resolves to 'down' inside createTrend, so this is additive only.
+  const stageDirections = Object.fromEntries(
+    stagedClose.filter((/** @type {any} */ s) => s?.direction === 'up' || s?.direction === 'down').map((/** @type {any} */ s) => [s.name, s.direction]),
+  );
+  const runTrend = createTrend({ stageOrder: stagedClose.map((/** @type {any} */ s) => s.name), seed: resumeGrades, directions: stageDirections });
   /** the run-level MONEY record, one shape wherever the wallet stops the run —
    * W-2's `emitWallHalt` in a money coat, and deliberately its mirror image. hamr's
    * ruling for TIME was "keep the grade we already have and stop"; a money cut is
@@ -3396,6 +3402,7 @@ export async function runPlan(job, { workdir, provider, nativeProvider, provider
       stageOrder: stagedClose.map((/** @type {any} */ s) => s.name),
       limit: FIX_STRIKE_LIMIT,
       blindCap: capRuns,
+      directions: stageDirections,
     });
     fixTrend.record({ gap: post.gap ?? '' });
     /** ralph's `ladder` seam, filled by the trend reader instead of the step

package/src/trend.js

@@ -212,12 +212,25 @@ const UNSTAGED = '(unstaged)';
  *   grades a PREVIOUS leg of this same run already recorded, oldest first, read off
  *   its own spine. Baselines only (see THE SEED above). Empty/omitted is the cold
  *   path and is byte-identical to the pre-resume reader.
+ * @param {Record<string, 'up'|'down'>} [opts.directions] per-stage comparison
+ *   direction, read from the signed close spec (2026-08-31 ruling, hamr's option
+ *   A) — never inferred, never LLM-judged. 'up' = higher is better (a rate of good
+ *   things caught); 'down' = lower is better (a count of bad things remaining, the
+ *   pre-existing behaviour). A stage absent from this map — including every close
+ *   authored before this field existed — resolves to 'down', so a cold spec's
+ *   trend reading is byte-identical to before this option existed.
  */
-export function createTrend({ stageOrder = [], limit = FIX_STRIKE_LIMIT, blindCap = null, seed = [] } = {}) {
+export function createTrend({ stageOrder = [], limit = FIX_STRIKE_LIMIT, blindCap = null, seed = [], directions = {} } = {}) {
   /** @type {Map<string, number[]>} stage → every count it reported, in order */
   const series = new Map();
-  /** @type {Map<string, number>} stage → the BEST (lowest) count it ever reported */
+  /** @type {Map<string, number>} stage → the BEST (max for 'up', min for 'down') count it ever reported */
   const best = new Map();
+  /** is `a` a BETTER reading than `b` for this stage, under its own declared
+   * direction? 'up' stages are better when higher (a caught-rate climbing);
+   * every other stage — including one absent from `directions` — is better
+   * when lower, which is the ORIGINAL, only comparison this reader ever made. */
+  const isBetter = (/** @type {string} */ stage, /** @type {number} */ a, /** @type {number} */ b) =>
+    (directions[stage] === 'up' ? a > b : a < b);
   /** the furthest stage index reached so far; null until a KNOWN stage is seen */
   let bestStageIdx = null;
   let iterations = 0;
@@ -249,7 +262,7 @@ export function createTrend({ stageOrder = [], limit = FIX_STRIKE_LIMIT, blindCa
     if (!series.has(st)) series.set(st, []);
     /** @type {number[]} */ (series.get(st)).push(v);
     const b = best.get(st);
-    if (b === undefined || v < b) best.set(st, v);
+    if (b === undefined || isBetter(st, v, b)) best.set(st, v);
   }
 
   return {
@@ -273,7 +286,7 @@ export function createTrend({ stageOrder = [], limit = FIX_STRIKE_LIMIT, blindCa
       // ── the two comparisons, each against this stage's OWN history ──
       const priorBest = best.get(st);
       const countComparable = v !== null && priorBest !== undefined;
-      const countImproved = countComparable && v < /** @type {number} */ (priorBest);
+      const countImproved = countComparable && isBetter(st, /** @type {number} */ (v), /** @type {number} */ (priorBest));
       // the ordering signal only exists between two KNOWN positions that DIFFER —
       // an unnamed stage has no position, and standing still says nothing
       const stageComparable = idx >= 0 && bestStageIdx !== null && idx !== bestStageIdx;
@@ -286,7 +299,7 @@ export function createTrend({ stageOrder = [], limit = FIX_STRIKE_LIMIT, blindCa
       if (v !== null) {
         if (!series.has(st)) series.set(st, []);
         /** @type {number[]} */ (series.get(st)).push(v);
-        if (priorBest === undefined || v < priorBest) best.set(st, v);
+        if (priorBest === undefined || isBetter(st, v, priorBest)) best.set(st, v);
       }
       if (idx >= 0 && (bestStageIdx === null || idx > bestStageIdx)) bestStageIdx = idx;
       if (stageImproved) advancedEver = true;
@@ -348,10 +361,12 @@ export function createTrend({ stageOrder = [], limit = FIX_STRIKE_LIMIT, blindCa
       // question is the different one of whether the LAST attempt helped.
       const numeric = rows.filter((r) => r.values.length > 1);
       const render = numeric.map((r) => `${r.stage} ${r.values.join(' → ')}`).join('; ');
-      // convergence is defined PER STAGE and per stage only: some axis is lower than
-      // where it started. First-vs-last, because the question a halt asks is "did
-      // this run make net progress", not "did the last attempt help".
-      const fell = numeric.some((r) => r.values[r.values.length - 1] < r.values[0]);
+      // convergence is defined PER STAGE and per stage only: some axis moved toward
+      // its OWN declared better direction from where it started — lower for a
+      // 'down' stage (a count of bad things remaining), higher for an 'up' stage (a
+      // rate of good things caught). First-vs-last, because the question a halt asks
+      // is "did this run make net progress", not "did the last attempt help".
+      const improvedNet = numeric.some((r) => isBetter(r.stage, r.values[r.values.length - 1], r.values[0]));
 
       // No stage ever reported a comparable number: the honest answer, stated rather
       // than rounded up to either direction. A "flat" here would recommend rewriting
@@ -385,7 +400,7 @@ export function createTrend({ stageOrder = [], limit = FIX_STRIKE_LIMIT, blindCa
       // Past this point a real number decided it, so motion is not consulted and is
       // not reported: a byte comparison beside a measured direction can only ever
       // contradict it, and the contradiction would be the weaker signal winning.
-      return fell
+      return improvedNet
         ? {
           trend: 'converging',
           motion: null,

package/types/index.d.ts

@@ -2,7 +2,7 @@ export { makeSpine } from "./spine.js";
 export { runPlan } from "./planrun.js";
 export { ralph, runClose, runStages, CLOSE_FAULTS } from "./ralph.js";
 export { globToPrefix, scanSecrets } from "./validate.js";
-export { validateJob, jobSpecHash, checkApproval, checkMenu, CLOSE_TYPES, CLASS_BY_CLOSE, GOLD_COMPARE, CADENCE_UNITS, PROVIDERS, CONDITION_KEYS, TOOL_MENU, LOCKED_TOOLS, STORE_VERBS, VERDICT_TYPES, LOCKED_VERDICTS } from "./job.js";
+export { validateJob, jobSpecHash, checkApproval, checkMenu, resolveWorkerModel, CLOSE_TYPES, CLASS_BY_CLOSE, GOLD_COMPARE, CADENCE_UNITS, PROVIDERS, CONDITION_KEYS, TOOL_MENU, LOCKED_TOOLS, STORE_VERBS, VERDICT_TYPES, LOCKED_VERDICTS } from "./job.js";
 export { validatePlan, stageClose, EXIT_TYPES, MAX_EXITS_PER_STEP, MAX_PLAN_STEPS, WRITE_VERBS, closeStagesOf } from "./plan.js";
 export { snapshotScope, evalExits } from "./exits.js";
 export { runJob, ACCOUNTED_ROUND_TYPES } from "./run.js";

package/types/job.d.ts

@@ -82,6 +82,30 @@ export function jobSpecHash(job: object): string;
  * @returns {boolean}
  */
 export function checkApproval(job: object, approvals: unknown): boolean;
+/**
+ * Pure decision: which worker model id a run actually uses (build-list #3,
+ * hamr's GO 2026-08-30). The signed spec's `model`, if present, is what an
+ * operator SIGNED — it wins outright. A `--model` runner flag naming a
+ * DIFFERENT id is refused rather than silently overridden (spec wins, a
+ * mismatched flag is a mistake worth stopping on, never a silent swap); the
+ * same id from both is not a conflict. Extracted from scripts/run-u.mjs so
+ * the decision is testable without running the script or touching a provider.
+ * @param {{ specModel?: string, flagModel?: string, defaultModel: string }} args
+ *   `specModel` — `job.model` if the signed spec carries one, else undefined.
+ *   `flagModel` — the model id an explicit `--model <tier>` resolved to, else
+ *   undefined (a flag that was never passed, not merely a default tier name).
+ *   `defaultModel` — the runner's own default when neither spec nor flag says.
+ * @returns {{ model: string, source: 'spec'|'flag'|'default' }}
+ * @throws {Error} when the spec names a model and the flag names a different one
+ */
+export function resolveWorkerModel({ specModel, flagModel, defaultModel }: {
+    specModel?: string;
+    flagModel?: string;
+    defaultModel: string;
+}): {
+    model: string;
+    source: "spec" | "flag" | "default";
+};
 export const CLOSE_TYPES: readonly string[];
 /** the hierarchy: which verdict classes a close type may claim (PRD §7). Read by
  * the verdictType check — a declared verdict may not demand a class its close

package/types/trend.d.ts

@@ -30,8 +30,15 @@ export function readGrade(gap?: string): {
  *   grades a PREVIOUS leg of this same run already recorded, oldest first, read off
  *   its own spine. Baselines only (see THE SEED above). Empty/omitted is the cold
  *   path and is byte-identical to the pre-resume reader.
+ * @param {Record<string, 'up'|'down'>} [opts.directions] per-stage comparison
+ *   direction, read from the signed close spec (2026-08-31 ruling, hamr's option
+ *   A) — never inferred, never LLM-judged. 'up' = higher is better (a rate of good
+ *   things caught); 'down' = lower is better (a count of bad things remaining, the
+ *   pre-existing behaviour). A stage absent from this map — including every close
+ *   authored before this field existed — resolves to 'down', so a cold spec's
+ *   trend reading is byte-identical to before this option existed.
  */
-export function createTrend({ stageOrder, limit, blindCap, seed }?: {
+export function createTrend({ stageOrder, limit, blindCap, seed, directions }?: {
     stageOrder?: string[] | undefined;
     limit?: number | undefined;
     blindCap?: number | null | undefined;
@@ -39,6 +46,7 @@ export function createTrend({ stageOrder, limit, blindCap, seed }?: {
         stage?: string | null;
         value?: number | null;
     }[] | undefined;
+    directions?: Record<string, "up" | "down"> | undefined;
 }): {
     /**
      * Read one RED close grade. A green never reaches here (both callers stop on