bareloop 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -5,7 +5,87 @@ 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.2.0] — 2026-07-12
+
+### Added
+- **N1 — the job/close schema (rung 2 of the ladder).** `validateJob` (`src/job.js`):
+  the operator-owned `job-v1` spec — the arbiter's rulebook as pure declarative data
+  (close chain, budget, outer write fence, environment label, escalation), validated
+  reds-before-tokens with pinned `code:path` reds. The arbiter split is guarded from
+  both sides by inexpressibility (workflow config can't say `close`/`provider`; job spec
+  can't say `hooks`/`loop`/`memory`, minting claims, or the shell-owned retry cap).
+  Close-authoring hierarchy (PRD §7) enforced as a class menu keyed by close type —
+  verdict-class laundering (`rubric` claiming `hard`) is a named red `close-hierarchy`.
+  `jobSpecHash` + `checkApproval`: the pure half of human-signs-always (sha256 over
+  canonical JSON; an edited spec is unapproved by construction; the N2 runner enforces).
+  Design record: `docs/plans/2026-07-12-n1-job-close-schema-design.md`; POC verdict: F4.
+- **Two-layer write fence.** `validateConfig` accepts `jobWriteScope` (the job spec's
+  operator-owned outer fence); every workflow scope must fit inside it — path-boundary
+  aware (`src2` is not inside `src`) — or it reds `scope-escape`. Same containment law,
+  same code, both layers (the F9 lesson).
+- **Reserved spine vocabulary: `coordination-red`** (V7, PRD v1.7 #1) — documented in
+  `bareloop.context.md`; no machinery until job #1 surfaces one.
+
+### Changed
+- **`validateConfig` returns `{ ok, reds, config }`** — the parsed config on ok, `null`
+  on any red; kills the interpreter's double-parse (N2+ queue item absorbed). Additive
+  for callers reading `ok`/`reds`.
+
+### Fixed
+- **Review hardening (post-build /code-review, 8 findings fixed + 6 sub-cap cleanups;
+  all fixes negative-tested and mutation-checked, zero feature regressions):**
+  cadence/escalation red unknown keys (the last smuggling level in a signed spec is
+  closed); the `jobWriteScope` fence opt fails CLOSED — a malformed fence is its own
+  `fence-invalid` red, never silently skipped, and each escaping scope reds at its own
+  indexed path (`gate.writeScope.N`); scope normalization moved into the shared
+  `globToPrefix` (leading `./`, interior `/./`, `//`, trailing `/` collapse) so a
+  validateJob-green fence like `src/` no longer deadlocks contained workflow configs;
+  `canon()` follows JSON semantics (undefined-valued keys dropped) so approvals survive
+  a disk round-trip, and `checkApproval` never throws (non-JSON spec → `false`);
+  `SECRET_RE` gained a left boundary (`flask-sqlalchemy` no longer reds) and the sweep
+  is shared by BOTH validators — the agent-authored workflow config is now swept too;
+  `interpret` accepts `jobWriteScope` and enforces the fence at the choke point (entry
+  + revision candidates); revision candidates are judged and installed on their PARSED
+  form (a JSON-string candidate no longer false-reds arbiter-touch); exported arbiter
+  menus are frozen; `isObj`/`isNonEmptyString` single-copied in `validate.js`.
+- **Second-round review (self-review of the hardening commit found a regression IT
+  introduced — all fixes TDD'd, mutation-checked, zero feature regressions):**
+  **critical containment escape** — the fence-normalization added to `globToPrefix`
+  stripped a leading `./` before collapsing `//`, so `.//src/**` minted the ABSOLUTE
+  prefix `/src`, validated green, and resolved outside the run directory at enforcement
+  (design law #1); fixed by collapsing `//`+`/./` first (so `.//src/**` → `src`, safe),
+  a belt in `scopeContained` rejecting any normalized-absolute prefix, and an enforcement
+  belt in `interpret` that refuses to build a Gate whose resolved scope escapes the
+  workdir. `canon()` now honors `toJSON` (a `Date` no longer hashes as `{}`; distinct
+  values no longer collide) and `jobSpecHash` never throws (the minting path the runner
+  calls directly is now crash-free on `BigInt`/cycles). `SECRET_RE` left boundary extended
+  to `-`/`_` (`pipeline-sk-transform-utils-v2` no longer false-reds; real keys still red).
+  `jobWriteScope: null`/`undefined` are the legitimate no-fence spellings (no more deadlock
+  on every config); a malformed fence reds `fence-invalid` at path `jobWriteScope`, not the
+  innocent workflow field (no ledger misattribution), with the detail bounded. Shared
+  `legalScopeEntry` gives the scope-legality law one home across all three call sites.
+- **Secrets never enter the spine (hard line), enforced at the source.** `runClose`
+  (`src/ralph.js`) scrubs close-command output the moment it is captured, so a secret a
+  checked command echoes (a 401 dumping a `Bearer …`/`sk-…` header) never reaches the
+  append-only spine or the next worker prompt. The redactor is injected (the shell stays
+  stdlib-only); `interpret` wires bareguard's exported `redact`. A benign gap is returned
+  byte-identical — the failure still reaches the human, just without the token (design
+  law #7 / V4 intact: the redactor is a fixed shell primitive, not an emergent component).
+- `NOTICE` ships in the tarball (npm auto-includes LICENSE/README but not NOTICE; Apache-2.0
+  wants both) — found validating the installed 0.1.0 artifact.
+- **Release-gate review (fresh `/security` + `/diff-review` on the whole release diff;
+  every finding execution-verified, every fix TDD'd):** the spine redactor now scrubs
+  **every shape the validator reds** — bareguard's defaults cover only `Bearer`/`sk-`,
+  so a git close echoing a `ghp_`/`github_pat_`/`AKIA`/`xox` token passed unredacted
+  into the append-only spine (the most plausible leak for job #1, a GitHub PR workflow);
+  `SECRET_PATTERNS` is now the one shape inventory shared by detection and redaction.
+  `interpret` normalizes `workdir` once at entry — a trailing-slash or relative spelling
+  made the enforcement belt false-red every legal scope — and the belt now treats a scope
+  resolving to the run dir itself as escaped. `checkApproval` no longer routes through the
+  un-hashable sentinel (two distinct un-hashable specs cross-approved each other; now
+  un-hashable = unapproved). The secrets sweep tests object **keys**, not just values (a
+  token could ride a key in a `gold` `expected` onto the spine through a green spec). A
+  non-object `cadence` reds once at `cadence`, not twice at paths that don't exist.
 
 ## [0.1.0] — 2026-07-11
 
@@ -119,6 +199,6 @@ feature lands, **patch** = docs, fixes, scaffolding.
   `docs/UPSTREAM-ASKS.md`, guardrails pre-tool hook (local), `.gitignore`.
 - Public GitHub repo `hamr0/bareloop`, `main` branch.
 
-[Unreleased]: https://github.com/hamr0/bareloop/compare/v0.1.0...HEAD
+[0.2.0]: https://github.com/hamr0/bareloop/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/hamr0/bareloop/compare/v0.0.1...v0.1.0
 [0.0.1]: https://github.com/hamr0/bareloop/releases/tag/v0.0.1

package/NOTICE

@@ -0,0 +1,13 @@
+bareloop
+Copyright 2026 hamr0
+
+This product includes software developed by hamr0
+(https://github.com/hamr0/bareloop).
+
+Licensed under the Apache License, Version 2.0 (the "License").
+You may obtain a copy of the License at:
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+This NOTICE file is required by Section 4(d) of the License.
+Forks and derivative works MUST preserve this attribution.

package/bareloop.context.md

@@ -1,10 +1,9 @@
 # bareloop — Integration Guide
 
-> **DRAFT — pre-code.** bareloop is at the name-reservation stage; the API sections below
-> fill in as build-ladder rungs land (PRD §10). What is already settled — the boundary,
-> the architecture, the refusals, the constraints — is settled for good and recorded now.
-> Per LIBRARY_CONVENTIONS §3 this file ships with the package and is the complete adopter
-> contract; the README is only the pitch.
+> **Current through N1** (job/close schema); 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
 
@@ -30,8 +29,42 @@ checkpoints + verdict classes, budget, cadence, provider) → run → watch the
 
 ## All options
 
-*TBD at N1 (job/close schema + validator lands). The schema is the option surface;
-config-red before tokens burn.*
+Two documents, two validators — the schema is the option surface; config-red before
+tokens burn. The arbiter split is guarded from both sides by INEXPRESSIBILITY: the
+workflow config cannot say `close`/`provider`; the job spec cannot say
+`hooks`/`loop`/`memory`, any minting claim, or the shell-owned retry cap — all
+unknown-field reds.
+
+**Job spec (`schema: "job-v1"`, operator-owned — the arbiter's rulebook):**
+
+| field | shape | notes |
+|---|---|---|
+| `job` | kebab-case slug | |
+| `description` | non-empty string | |
+| `provider` | `anthropic-api` | menu; part of the lineage key by definition |
+| `conditions` | `{ providerPath?, closeVerbosity?, taskFraming?, scaffold? }` | declared keys only, string values — the environment label (consumed by the N3 lineage key; recorded on spines from run one) |
+| `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 |
+| `writeScope` | array of contained globs | the operator's outer fence; same containment law as the workflow layer, same code |
+| `steps` | array of `{ id, close, class }` | unique slug ids; every step names its close |
+| `escalation` | `{ mode: "decision-ready" }` | the pain channel is not optional |
+
+**Close types and the hierarchy** (a close is data, never code; verdict-class laundering
+is a named red `close-hierarchy`):
+
+| type | fields (exact — extras red) | legal class |
+|---|---|---|
+| `predicate` | `cmd`, `expect` (int exit code) | `hard` |
+| `gold` | `expected`, `compare: exact\|json-equal` | `hard` |
+| `rubric` | `criteria` | `soft` only — can never mint automatically |
+| `hitl` | `prompt` | `hitl` — a human IS the close |
+
+Red vocabulary (both 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
+defense-in-depth against known token shapes — env-only loading remains the law, not the
+sweep.
 
 ## Public API
 
@@ -51,23 +84,57 @@ The dumb outer shell: `while close-red and under-cap: run the middle`. `close` i
 whose exit code is truth (`runClose` is also exported); the red gap text feeds the next
 iteration. 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`.
+property (`cap-halt`, `gate-red`, …); an unnamed throw is `interpreter-red`. Close output
+is scrubbed at capture (an injected `redact`, wired to bareguard by `interpret` with the
+validators' full secret-shape inventory — Bearer/sk-/ghp_/github_pat_/AKIA/xox) so a
+secret a checked command echoes never enters the append-only spine or a worker prompt —
+a benign gap is byte-identical (secrets hard line; design law #7 intact).
 
-### `validateConfig(input, { shellCapUsd? })` → `{ ok, reds }` — `src/validate.js`
+### `validateConfig(input, { shellCapUsd?, jobWriteScope? })` → `{ ok, reds, config }` — `src/validate.js`
 
 Deterministic schema-v1 predicate; never throws. Every failure is a named red
-`{ code, path, detail? }` — reds before tokens burn. Verb vocabulary bound from litectx
+`{ code, path, detail? }` — reds before tokens burn. Returns the parsed config on ok
+(single parse; `null` on any red). Pass the job spec's `writeScope` as `jobWriteScope`
+and every workflow scope must fit inside the fence (path-boundary aware: `src2` is not
+inside `src`) or it reds `scope-escape`; pass `min(shell cap, job budgetUsd)` as
+`shellCapUsd` to complete the ceiling chain. Verb vocabulary bound from litectx
 (`LOOP_SHAPES`, `SLOTS`, `VERBS` exported). `diffPaths(a, b)` returns changed JSON paths —
 the one-knob mutation checker.
 
+### `validateJob(input, { shellCapUsd? })` → `{ ok, reds, job }` — `src/job.js`
+
+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:
+`CLOSE_TYPES`, `CLASSES`, `CLASS_BY_CLOSE`, `GOLD_COMPARE`, `CADENCE_UNITS`,
+`PROVIDERS`, `CONDITION_KEYS`.
+
+### `jobSpecHash(job)` / `checkApproval(job, approvals)` — `src/job.js`
+
+The pure half of **human-signs-always**: an agent may draft a job spec, but no job runs
+until a human approves that exact version. `jobSpecHash` is sha256 over canonical JSON
+(key-order independent) — any edit changes the hash, so an edited spec is unapproved by
+construction. `checkApproval(job, approvals)` is a pure predicate over
+`{ specHash, signer, ts }` records; the approval record lives OUTSIDE the document it
+signs and is shell/human territory, never agent-writable. The N2 runner enforces it.
+Reserved spine vocabulary (V7, machinery-free until job #1 surfaces one):
+`coordination-red` — a failure between units (scope contention, step order, store
+races), never to be folded into worker/interpreter reds.
+
 ### `interpret(configRaw, opts)` → `'green' | 'escalated' | 'config-red'` — `src/interpret.js`
 
 The only code that reads a config. Composes bareguard `Gate` (write scopes, USD budget),
 litectx (recall/compress/stash/remember hook ops), and the bareagent `Loop` under `ralph`.
 The provider and the close arrive from the shell, never the config. Optional `revisor`
 seam fires once after `STALL_REDS` consecutive close reds; the interpreter owns acceptance
-(arbiter-touch / cap-touch / validation reds). Emits `config-final` — the run-as-executed
-config (design law #2) — on every run.
+(arbiter-touch / cap-touch / validation reds), judged and installed on the candidate's
+PARSED form. Emits `config-final` — the run-as-executed config (design law #2) — on every
+run. Pass the job spec's fence as `jobWriteScope` (or `null`/omit for no fence): it is
+enforced HERE — the one choke point where a config becomes a Gate — on entry AND on every
+revision candidate, so a workflow scope outside the operator's fence reds before tokens.
+An enforcement belt resolves every scope and refuses to build a Gate that escapes the
+workdir, independent of validator correctness (law #1).
 
 ### `extractRules({ config, provider, priorRules, revisionDiff? })` — `src/extract.js`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bareloop",
-  "version": "0.1.0",
+  "version": "0.2.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",
@@ -39,6 +39,7 @@
   "files": [
     "src/",
     "types/",
+    "NOTICE",
     "bareloop.context.md",
     "CHANGELOG.md"
   ],

package/src/index.js

@@ -1,9 +1,13 @@
 // bareloop public surface — grows one rung at a time (PRD §10). N0: the
 // token-free spine. The five modules compose bottom-up: makeSpine feeds ralph,
 // interpret is the only config reader, extractRules distills a green run.
+// N1: the operator-owned job spec (job-v1) — validateJob is validate.js's
+// sibling (never an extension); jobSpecHash/checkApproval are the pure half
+// of human-signs-always (the N2 runner enforces).
 
 export { makeSpine } from './spine.js';
 export { ralph, runClose } from './ralph.js';
 export { validateConfig, diffPaths, globToPrefix, LOOP_SHAPES, SLOTS, VERBS } from './validate.js';
+export { validateJob, jobSpecHash, checkApproval, CLOSE_TYPES, CLASSES, CLASS_BY_CLOSE, GOLD_COMPARE, CADENCE_UNITS, PROVIDERS, CONDITION_KEYS } from './job.js';
 export { interpret, STALL_REDS } from './interpret.js';
 export { extractRules, MAX_RULES, MAX_RULE_CHARS } from './extract.js';

package/src/interpret.js

@@ -12,10 +12,10 @@
 
 import { createRequire } from 'node:module';
 import { writeFileSync, readFileSync } from 'node:fs';
-import { join, resolve } from 'node:path';
-import { Gate } from 'bareguard';
+import { join, resolve, sep } from 'node:path';
+import { Gate, redact } from 'bareguard';
 import { LiteCtx, compress } from 'litectx';
-import { validateConfig, diffPaths, globToPrefix } from './validate.js';
+import { validateConfig, diffPaths, globToPrefix, SECRET_PATTERNS } from './validate.js';
 import { ralph } from './ralph.js';
 
 /** @typedef {Error & {category?: string}} CategorizedError the failure map's carrier: ralph relays by `category` */
@@ -45,6 +45,10 @@ const PERSONA = 'You are a senior engineer. Reply with ONLY the complete content
  * @param {(type: string, data?: object) => object} opts.emit spine emitter
  * @param {object} opts.provider a bareagent provider — SHELL-owned binding (adaptlearn F8: an unsealed binding is a gate bypass)
  * @param {number} [opts.shellCapUsd=2] the shell's USD cap; config budgetUsd is clamped by validation
+ * @param {string[]} [opts.jobWriteScope] the job spec's outer write fence (operator law,
+ *        job-v1) — enforced HERE, the one choke point where a config becomes a Gate:
+ *        every workflow scope must fit inside it (scope-escape config-red otherwise),
+ *        on entry validation and on every revision candidate alike
  * @param {(o: {config: object, gaps: string[], policy: any, onLlmResult: any}) => Promise<{candidate: object|null, parseError?: string|null, costUsd?: number}>} [opts.revisor]
  *        optional mid-run revision seam. Fires ONCE per run after STALL_REDS consecutive
  *        close reds. The interpreter — never the revisor — owns acceptance: the candidate
@@ -54,22 +58,40 @@ const PERSONA = 'You are a senior engineer. Reply with ONLY the complete content
  *        the worker.
  * @returns {Promise<'green'|'escalated'|'config-red'>}
  */
-export async function interpret(configRaw, { task, target, close, workdir, capRuns, emit, provider, shellCapUsd = 2, revisor }) {
-  const v = validateConfig(configRaw, { shellCapUsd });
+export async function interpret(configRaw, { task, target, close, workdir, capRuns, emit, provider, shellCapUsd = 2, jobWriteScope, revisor }) {
+  // Normalize ONCE: a trailing slash or a relative spelling must mean the same
+  // directory everywhere below — the enforcement belt compares string prefixes,
+  // and "/run/" vs "/run" would false-red every legal scope (release review).
+  workdir = resolve(workdir);
+  const v = validateConfig(configRaw, { shellCapUsd, jobWriteScope });
   emit('config-validate', { ok: v.ok, reds: v.reds });
   if (!v.ok) {
     for (const r of v.reds) emit('config-red', r);
     emit('run-end', { outcome: 'config-red', iterations: 0 });
     return 'config-red';
   }
-  let config = typeof configRaw === 'string' ? JSON.parse(configRaw) : configRaw;
+  let config = /** @type {any} */ (v.config); // single parse — validateConfig returns the parsed config on ok
 
   const lc = new LiteCtx({ root: workdir });
+  // Enforcement belt (law #1, un-gameable gate): resolve every scope and prove
+  // it stays under workdir BEFORE building the Gate. validateConfig already
+  // rejects escaping scopes, so this is defense in depth — a future globToPrefix
+  // regression (a spelling that normalizes to an absolute path) can never reach
+  // a live Gate fence. The interpreter and the validator must never disagree (F9).
+  const resolvedScopes = config.gate.writeScope.map((/** @type {string} */ g) => resolve(workdir, globToPrefix(g)));
+  // equality counts as escaped: no legal scope resolves to workdir itself (the
+  // close lives there), so a scope normalizing to ''/'.' is a regression, not a grant
+  const escaped = resolvedScopes.filter((/** @type {string} */ abs) => !abs.startsWith(workdir + sep));
+  if (escaped.length) {
+    for (const abs of escaped) emit('config-red', { code: 'scope-escape', path: 'gate.writeScope', detail: `resolved scope ${abs} escapes the run directory` });
+    emit('run-end', { outcome: 'config-red', iterations: 0 });
+    return 'config-red';
+  }
   const gate = new Gate({
     // bareguard fs.writeScope is prefix-containment, not glob (adaptlearn F4); globToPrefix
     // is the ONE transform shared with the validator's legality rule — mid-path wildcards
     // and workdir-escaping scopes were already rejected up front (adaptlearn F9, law #1).
-    fs: { writeScope: config.gate.writeScope.map((/** @type {string} */ g) => resolve(workdir, globToPrefix(g))) },
+    fs: { writeScope: resolvedScopes },
     budget: { maxCostUsd: config.gate.budgetUsd },
     limits: { maxTurns: 8 * (capRuns + 1) },
     audit: { path: join(workdir, 'gate-audit.jsonl') },
@@ -139,17 +161,22 @@ export async function interpret(configRaw, { task, target, close, workdir, capRu
   // already snapshotted, so gate/escalation (arbiter) and loop.maxIterations
   // (cap) must be byte-identical; anything else that validates is a legal
   // free-axis revision.
-  /** @param {any} candidate */
+  /** @param {any} candidate
+   *  @returns {{ red: {code: string, reds?: object[]} } | { red?: undefined, config: any }} */
   const acceptRevision = (candidate) => {
-    if (!candidate) return { code: 'parse-error' };
-    const cv = validateConfig(candidate, { shellCapUsd });
-    if (!cv.ok) return { code: 'validation', reds: cv.reds };
-    if (JSON.stringify(candidate.gate) !== JSON.stringify(config.gate)
-        || JSON.stringify(candidate.escalation) !== JSON.stringify(config.escalation)) {
-      return { code: 'arbiter-touch' };
+    if (!candidate) return { red: { code: 'parse-error' } };
+    const cv = validateConfig(candidate, { shellCapUsd, jobWriteScope });
+    if (!cv.ok) return { red: { code: 'validation', reds: cv.reds } };
+    // judged and installed on the PARSED form (single-parse contract) — a
+    // string candidate compared raw would false-red arbiter-touch (its .gate
+    // is undefined), and installing it raw would crash every later read
+    const cand = /** @type {any} */ (cv.config);
+    if (JSON.stringify(cand.gate) !== JSON.stringify(config.gate)
+        || JSON.stringify(cand.escalation) !== JSON.stringify(config.escalation)) {
+      return { red: { code: 'arbiter-touch' } };
     }
-    if (candidate.loop?.maxIterations !== config.loop.maxIterations) return { code: 'cap-touch' };
-    return null;
+    if (cand.loop?.maxIterations !== config.loop.maxIterations) return { red: { code: 'cap-touch' } };
+    return { config: cand };
   };
 
   /** @type {string[]} */
@@ -174,12 +201,12 @@ export async function interpret(configRaw, { task, target, close, workdir, capRu
         if (e instanceof HaltError) /** @type {CategorizedError} */ (e).category = 'cap-halt';
         throw e;
       }
-      const red = acceptRevision(rv.candidate);
-      if (red) {
-        emit('revision-red', { iteration, ...red, detail: rv.parseError ?? undefined, costUsd: rv.costUsd ?? 0 });
+      const rr = acceptRevision(rv.candidate);
+      if (rr.red) {
+        emit('revision-red', { iteration, ...rr.red, detail: rv.parseError ?? undefined, costUsd: rv.costUsd ?? 0 });
       } else {
-        emit('revision-accepted', { iteration, changedPaths: diffPaths(config, rv.candidate), costUsd: rv.costUsd ?? 0 });
-        config = rv.candidate;
+        emit('revision-accepted', { iteration, changedPaths: diffPaths(config, rr.config), costUsd: rv.costUsd ?? 0 });
+        config = rr.config;
       }
     }
     if (gap) await runOps('after-red', { iteration, gap, context: {} });
@@ -208,7 +235,13 @@ export async function interpret(configRaw, { task, target, close, workdir, capRu
 
   // the config may tighten the shell's iteration budget, never exceed it (mirrors budgetUsd)
   const effectiveCap = Math.min(capRuns, config.loop.maxIterations ?? capRuns);
-  const outcome = await ralph({ middle, close, capRuns: effectiveCap, emit });
+  // Secrets never enter the spine (hard line): the shell scrubs close output at
+  // the source with bareguard's redactor — BG-1 defaults (Bearer/sk-…) PLUS the
+  // validator's whole shape inventory (SECRET_PATTERNS), so redaction can never
+  // pass a shape detection reds (a git close echoing a ghp_ token was the gap).
+  // Injected here (the layer that owns bareguard) so ralph stays stdlib-only and
+  // the scrub is a fixed shell primitive, not an emergent component (V4 holds).
+  const outcome = await ralph({ middle, close, capRuns: effectiveCap, emit, redact: (/** @type {string} */ s) => redact(s, { patterns: SECRET_PATTERNS }) });
   if (outcome === 'green') {
     // The close already passed — a retention hiccup must not un-green a real
     // green (it would corrupt the learning curve). It degrades loudly:

package/src/job.js

@@ -0,0 +1,252 @@
+// Job-spec validator — the OPERATOR-owned half of the config story (N1,
+// design record: docs/plans/2026-07-12-n1-job-close-schema-design.md).
+// A job spec is the arbiter's rulebook: the close chain, the budget, the
+// outer write fence, the escalation route. It is pure declarative data —
+// no freeform code is expressible anywhere in it — and it validates
+// reds-before-tokens like its sibling validate.js (workflow, agent-authored).
+// The arbiter split is guarded from both sides by INEXPRESSIBILITY: the
+// workflow config cannot say close/provider (validate.js, shipped at N0);
+// the job spec cannot say hooks/loop/memory, any minting claim, or the
+// shell-owned retry cap — all unknown-field reds here.
+//
+// Close-authoring hierarchy (PRD §7) as a class menu keyed by close type:
+// verdict-class laundering (a rubric claiming hard) is a named red, never a
+// judgment call. Minting policy is product doctrine, not job-authorable.
+
+import { createHash } from 'node:crypto';
+import { globToPrefix, scopeContained, isObj, isNonEmptyString, sweepSecretLiterals } from './validate.js';
+
+// The menus below ARE the close-authoring hierarchy (PRD §7) and ship frozen:
+// they are read at call time, so a mutable export would let adopter code
+// enable verdict-class laundering process-wide with one push().
+export const CLOSE_TYPES = Object.freeze(['predicate', 'gold', 'rubric', 'hitl']);
+export const CLASSES = Object.freeze(['hard', 'soft', 'hitl']);
+/** the hierarchy: which verdict classes a close type may claim (PRD §7) */
+export const CLASS_BY_CLOSE = Object.freeze({ predicate: Object.freeze(['hard']), gold: Object.freeze(['hard']), rubric: Object.freeze(['soft']), hitl: Object.freeze(['hitl']) });
+export const GOLD_COMPARE = Object.freeze(['exact', 'json-equal']);
+export const CADENCE_UNITS = Object.freeze(['hour', 'day', 'week']);
+export const PROVIDERS = Object.freeze(['anthropic-api']); // SP-2: API-first; local deferred (PRD §5/§8)
+/** V3 environment label: declared keys only — every field is a lineage-key
+ * candidate at N3. `provider` is part of the key by definition (top-level,
+ * not duplicated here). */
+export const CONDITION_KEYS = Object.freeze(['providerPath', 'closeVerbosity', 'taskFraming', 'scaffold']);
+const JOB_FIELDS = ['schema', 'job', 'description', 'provider', 'conditions', 'cadence', 'budgetUsd', 'writeScope', 'steps', 'escalation'];
+/** exact field set per close type — anything else is an unknown-field red
+ * (freeform code, script bodies, and minting claims all land there) */
+const CLOSE_FIELDS = {
+  predicate: ['type', 'cmd', 'expect'],
+  gold: ['type', 'expected', 'compare'],
+  rubric: ['type', 'criteria'],
+  hitl: ['type', 'prompt'],
+};
+const SLUG_RE = /^[a-z0-9][a-z0-9-]*$/;
+
+/** @typedef {{code: string, path: string, detail?: string}} Red */
+
+/**
+ * Validate an operator-owned job spec (`schema: "job-v1"`). Never throws on
+ * JSON text or plain parsed data — the ingest contract; a live object with a
+ * hostile accessor is outside it. Every failure is a named red. Returns the
+ * parsed spec on ok (single parse), null on any red.
+ * @param {object|string} input parsed spec, or raw JSON text (parse failures are a red)
+ * @param {{ shellCapUsd?: number }} [opts] the shell's hard ceiling — the job
+ *   budget may tighten it, never exceed it (ceiling chain: workflow ≤ job ≤ shell)
+ * @returns {{ ok: boolean, reds: Red[], job: object|null }}
+ */
+export function validateJob(input, { shellCapUsd = 2 } = {}) {
+  /** @type {Red[]} */
+  const reds = [];
+  /** @type {(code: string, path: string, detail?: string) => void} */
+  const red = (code, path, detail) => { reds.push(detail ? { code, path, detail } : { code, path }); };
+
+  let j = input;
+  if (typeof j === 'string') {
+    try { j = JSON.parse(j); } catch (e) {
+      return { ok: false, reds: [{ code: 'parse-error', path: '$', detail: String(/** @type {Error} */ (e).message) }], job: null };
+    }
+  }
+  if (!isObj(j)) return { ok: false, reds: [{ code: 'parse-error', path: '$', detail: 'job spec must be a JSON object' }], job: null };
+  const spec = /** @type {Record<string, any>} */ (j);
+
+  // 1. shape — unknown fields red here: hooks/loop/memory (agent domain),
+  // capRuns (shell domain), minting claims — inexpressibility is the guard.
+  for (const key of Object.keys(spec)) {
+    if (!JOB_FIELDS.includes(key)) red('unknown-field', key);
+  }
+  if (spec.schema === undefined) red('missing-required', 'schema');
+  else if (spec.schema !== 'job-v1') red('invalid-value', 'schema', `expected "job-v1", got ${JSON.stringify(spec.schema)}`);
+  if (!isNonEmptyString(spec.job) || !SLUG_RE.test(spec.job)) red('invalid-value', 'job', 'kebab-case slug');
+  if (!isNonEmptyString(spec.description)) red('missing-required', 'description');
+
+  if (spec.provider === undefined) red('missing-required', 'provider');
+  else if (!PROVIDERS.includes(spec.provider)) red('invalid-value', 'provider', `menu: ${PROVIDERS.join('|')}`);
+
+  // 2. the environment label (V3, design law #5): declared keys only
+  if (spec.conditions !== undefined) {
+    if (!isObj(spec.conditions)) red('invalid-value', 'conditions', 'flat object of declared condition keys');
+    else {
+      for (const [key, value] of Object.entries(spec.conditions)) {
+        if (!CONDITION_KEYS.includes(key)) red('unknown-field', `conditions.${key}`, `declared keys only: ${CONDITION_KEYS.join('|')} (every field is a lineage-key dimension, V3)`);
+        else if (!isNonEmptyString(value)) red('invalid-value', `conditions.${key}`, 'non-empty string');
+      }
+    }
+  }
+
+  if (spec.cadence === undefined) red('missing-required', 'cadence');
+  else if (!isObj(spec.cadence)) red('invalid-value', 'cadence', 'object of {unit, every}');
+  else {
+    const cad = spec.cadence;
+    for (const key of Object.keys(cad)) {
+      if (key !== 'unit' && key !== 'every') red('unknown-field', `cadence.${key}`, 'nested objects red unknown keys too — no smuggling level exists in a signed spec');
+    }
+    if (!CADENCE_UNITS.includes(cad.unit)) red('invalid-value', 'cadence.unit', CADENCE_UNITS.join('|'));
+    if (!(Number.isInteger(cad.every) && cad.every >= 1 && cad.every <= 30)) red('bounds', 'cadence.every', '1..30');
+  }
+
+  if (spec.budgetUsd === undefined) red('missing-required', 'budgetUsd');
+  else if (!(typeof spec.budgetUsd === 'number' && spec.budgetUsd > 0 && spec.budgetUsd <= shellCapUsd)) {
+    red('bounds', 'budgetUsd', `0 < budget <= shell cap ${shellCapUsd} (cap-not-estimate; no self-adjusted budgets, ever)`);
+  }
+
+  // 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).
+  if (spec.writeScope === undefined) red('missing-required', 'writeScope', 'the fence is operator law — the workflow scope must fit inside it');
+  else if (!(Array.isArray(spec.writeScope) && spec.writeScope.length > 0
+             && spec.writeScope.every((/** @type {unknown} */ s) => isNonEmptyString(s)))) {
+    red('invalid-value', 'writeScope', 'non-empty array of glob strings');
+  } else if (!spec.writeScope.every((/** @type {string} */ s) => !globToPrefix(s).includes('*'))) {
+    red('invalid-value', 'writeScope', 'wildcards only as a trailing "/**" or "/*" (enforcement is prefix-containment, adaptlearn F9)');
+  } else if (!spec.writeScope.every(scopeContained)) {
+    red('invalid-value', 'writeScope', 'must be a proper subdirectory of the run directory — no absolute paths, no ".." segments, not the run dir itself (design law #1)');
+  }
+
+  if (spec.escalation === undefined) red('missing-required', 'escalation.mode', 'the pain channel is not optional (law #7)');
+  else {
+    const esc = isObj(spec.escalation) ? spec.escalation : {};
+    for (const key of Object.keys(esc)) {
+      if (key !== 'mode') red('unknown-field', `escalation.${key}`, 'nested objects red unknown keys too — no smuggling level exists in a signed spec');
+    }
+    if (esc.mode !== 'decision-ready') red('invalid-value', 'escalation.mode', 'must be "decision-ready"');
+  }
+
+  // 4. steps + the close chain
+  if (!Array.isArray(spec.steps) || spec.steps.length === 0) {
+    red('missing-required', 'steps', 'non-empty array — a job without closes is ungated spend');
+  } else {
+    const seen = new Set();
+    spec.steps.forEach((/** @type {any} */ s, /** @type {number} */ i) => {
+      const at = `steps.${i}`;
+      if (!isObj(s)) { red('invalid-value', at, 'step must be an object'); return; }
+      for (const key of Object.keys(s)) {
+        if (!['id', 'close', 'class'].includes(key)) red('unknown-field', `${at}.${key}`);
+      }
+      if (!isNonEmptyString(s.id) || !SLUG_RE.test(s.id)) red('invalid-value', `${at}.id`, 'kebab-case slug');
+      else if (seen.has(s.id)) red('duplicate-id', `${at}.id`, s.id);
+      else seen.add(s.id);
+
+      if (s.class === undefined) red('missing-required', `${at}.class`);
+      else if (!CLASSES.includes(s.class)) red('invalid-value', `${at}.class`, CLASSES.join('|'));
+
+      if (!isObj(s.close)) { red('missing-required', `${at}.close`, 'every step names its close — a step without one is ungated spend'); return; }
+      const close = s.close;
+      if (!CLOSE_TYPES.includes(close.type)) {
+        red('close-type', `${at}.close.type`, `menu: ${CLOSE_TYPES.join('|')} — a close is data, never code`);
+        return;
+      }
+      // per-type contracts — fixed menus only
+      if (close.type === 'predicate') {
+        if (!isNonEmptyString(close.cmd)) red('missing-required', `${at}.close.cmd`);
+        if (!Number.isInteger(close.expect)) red('invalid-value', `${at}.close.expect`, 'integer exit code');
+      } else if (close.type === 'gold') {
+        if (close.expected === undefined) red('missing-required', `${at}.close.expected`);
+        if (!GOLD_COMPARE.includes(close.compare)) red('invalid-value', `${at}.close.compare`, GOLD_COMPARE.join('|'));
+      } else if (close.type === 'rubric') {
+        if (!isNonEmptyString(close.criteria)) red('missing-required', `${at}.close.criteria`);
+      } else if (close.type === 'hitl') {
+        if (!isNonEmptyString(close.prompt)) red('missing-required', `${at}.close.prompt`);
+      }
+      for (const key of Object.keys(close)) {
+        if (!CLOSE_FIELDS[close.type].includes(key)) {
+          red('unknown-field', `${at}.close.${key}`, `not a ${close.type} field (script bodies and minting claims land here)`);
+        }
+      }
+      // the hierarchy: one check covers both directions — a class outside the
+      // close type's menu is laundering (rubric-as-hard) or delegation
+      // (hitl-class on a script close); hitl ⇔ hitl falls out of the menus.
+      const legal = CLASS_BY_CLOSE[close.type];
+      if (CLASSES.includes(s.class) && !legal.includes(s.class)) {
+        red('close-hierarchy', `${at}.class`, `${close.type} close admits class ${legal.join('|')} only (a rubric can never be hard; a human IS the hitl close — PRD §7)`);
+      }
+    });
+  }
+
+  // 5. secrets sweep — the SAME shared guard the workflow validator runs
+  // (defense-in-depth against known token shapes; env-only loading is the law)
+  sweepSecretLiterals(spec, red);
+
+  return { ok: reds.length === 0, reds, job: reds.length === 0 ? spec : null };
+}
+
+/**
+ * Canonical JSON — recursive key sort, so the hash binds to CONTENT, not to
+ * the accident of key order a drafting UX or an editor produced.
+ * @param {any} v
+ * @returns {string}
+ */
+function canon(v) {
+  // Follow JSON.stringify semantics — the hash must equal the hash of the
+  // disk round-trip, or an approval minted in memory fails after save/reload
+  // (human-signs-always rejecting an unedited spec). That means honoring toJSON
+  // (a Date serializes to its ISO string, not walked as {}) and dropping
+  // undefined-valued keys, both of which JSON.stringify does. One divergence:
+  // a function/symbol-VALUED key canonizes as null where stringify drops it —
+  // reachable only on non-JSON specs, where a round-trip mismatch is correct.
+  if (v !== null && typeof v === 'object' && typeof (/** @type {any} */ (v).toJSON) === 'function') {
+    return canon(/** @type {any} */ (v).toJSON());
+  }
+  if (Array.isArray(v)) return `[${v.map((x) => (x === undefined ? 'null' : canon(x))).join(',')}]`;
+  if (isObj(v)) {
+    const obj = /** @type {Record<string, any>} */ (v);
+    return `{${Object.keys(obj).sort().filter((k) => obj[k] !== undefined).map((k) => `${JSON.stringify(k)}:${canon(obj[k])}`).join(',')}}`;
+  }
+  const s = JSON.stringify(v);
+  return s === undefined ? 'null' : s; // undefined/function/symbol leaf: not JSON-representable — 'null', never throw
+}
+
+/**
+ * Content hash of a job spec — what an approval record binds to. Any edit to
+ * the spec changes the hash, so an edited spec is unapproved by construction
+ * (interview decision #1: human signs, always, once per spec VERSION).
+ * @param {object} job
+ * @returns {string} sha256 hex
+ */
+export function jobSpecHash(job) {
+  // NEVER throws: the N2 runner mints {specHash, signer, ts} by calling this
+  // directly on the raw job object, so a non-JSON value (BigInt, a cycle, a
+  // throwing getter) must yield a hash, not crash the signer. canon handles
+  // JSON-representable inputs; the guard covers cycles and hostile getters.
+  let c;
+  try { c = canon(job); } catch { c = '\u0000unhashable'; }
+  return createHash('sha256').update(c).digest('hex');
+}
+
+/**
+ * Does an approval record cover this exact spec version? Pure predicate — the
+ * N2 runner refuses to run without it; nothing here writes or prompts. The
+ * approval record lives OUTSIDE the document it signs (a spec never contains
+ * its own signature) and is shell/human territory, never agent-writable.
+ * @param {object} job
+ * @param {unknown} approvals array of { specHash, signer, ts } records
+ * @returns {boolean}
+ */
+export function checkApproval(job, approvals) {
+  if (!Array.isArray(approvals)) return false;
+  // NOT jobSpecHash: its un-hashable sentinel would make every un-hashable
+  // spec hash-equal — an approval minted for one would authorize any other.
+  // Here un-hashable simply means unapproved, full stop.
+  let c;
+  try { c = canon(job); } catch { return false; }
+  const h = createHash('sha256').update(c).digest('hex');
+  return approvals.some((a) => isObj(a) && /** @type {Record<string, unknown>} */ (a).specHash === h);
+}

package/src/ralph.js

@@ -9,9 +9,19 @@ import { spawnSync } from 'node:child_process';
 /**
  * Run a close command; its exit code is the verdict (hard green, PRD §4).
  * 0 → satisfied; nonzero → needs_revision (gap fed back); spawn error → failed (terminal).
+ *
+ * `redact` scrubs the close's own output at the SOURCE — before the gap becomes
+ * a spine event or a worker prompt — so a secret a checked command echoes
+ * (a 401 dumping an `Authorization: Bearer …` header) never enters the
+ * append-only spine (the hard line). It is INJECTED, not imported: the shell
+ * stays stdlib-only and un-gameable, and the redactor is a fixed shell
+ * primitive (bareguard's, wired by the interpreter), never an emergent
+ * component — so V4 holds. The shell's canonical emission IS the redacted text;
+ * a benign gap is returned byte-identical (default: identity).
  * @param {string[]} close argv, e.g. ['node', '--test', 'close/']
+ * @param {(s: string) => string} [redact] source scrubber; identity by default
  */
-export function runClose(close) {
+export function runClose(close, redact = (s) => s) {
   const env = { ...process.env };
   delete env.NODE_TEST_CONTEXT; // a `node --test` close inherits this from a test runner and silently no-ops — a fake green
   const r = spawnSync(close[0], close.slice(1), { env, encoding: 'utf8', timeout: 120_000 });
@@ -20,7 +30,8 @@ export function runClose(close) {
   // The gap must never be falsy: every consumer guards with `if (gap)` — an
   // empty-output red would silently kill gap feedback, after-red hooks, AND
   // stall detection, leaving the worker re-prompted byte-identically to the cap.
-  return { verdict: 'needs_revision', gap: (r.stderr || r.stdout || '').slice(0, 2000) || '(close exited nonzero with no output)', exitCode: r.status };
+  // Redact BEFORE slicing so a token straddling the 2000-char bound can't survive.
+  return { verdict: 'needs_revision', gap: redact(r.stderr || r.stdout || '').slice(0, 2000) || '(close exited nonzero with no output)', exitCode: r.status };
 }
 
 /**
@@ -42,9 +53,11 @@ export function runClose(close) {
  * @param {string[]} opts.close argv whose exit code is truth
  * @param {number} opts.capRuns budget: max middle runs
  * @param {(type: string, data?: object) => object} opts.emit a spine emitter
+ * @param {(s: string) => string} [opts.redact] source scrubber for close output
+ *   (secrets never enter the spine); injected so the shell stays stdlib-only
  * @returns {Promise<'green'|'escalated'>}
  */
-export async function ralph({ middle, close, capRuns, emit }) {
+export async function ralph({ middle, close, capRuns, emit, redact }) {
   emit('run-start', { capRuns, close: close.join(' ') });
   const verdicts = [];
   let gap;
@@ -77,7 +90,7 @@ export async function ralph({ middle, close, capRuns, emit }) {
       return 'escalated';
     }
     emit('middle-done', { iteration });
-    const v = runClose(close);
+    const v = runClose(close, redact);
     verdicts.push(v.verdict);
     emit('close-verdict', { iteration, ...v });
     if (v.verdict === 'satisfied') {

package/src/validate.js

@@ -11,9 +11,9 @@
 
 import { COMPRESS_LEVELS, KINDS, WRITE_KINDS } from 'litectx';
 
-export const LOOP_SHAPES = ['refine', 'plan'];
-export const SLOTS = ['before-attempt', 'after-red', 'on-green'];
-export const VERBS = ['recall', 'compress', 'stash', 'remember'];
+export const LOOP_SHAPES = Object.freeze(['refine', 'plan']);
+export const SLOTS = Object.freeze(['before-attempt', 'after-red', 'on-green']);
+export const VERBS = Object.freeze(['recall', 'compress', 'stash', 'remember']);
 const TOP_FIELDS = ['schema', 'loop', 'memory', 'hooks', 'gate', 'escalation'];
 const MAX_OPS_PER_SLOT = 2;
 
@@ -40,7 +40,23 @@ const VERB_PARAMS = {
  * @param {string} scope
  */
 export function globToPrefix(scope) {
-  return scope.replace(/\/\*\*?$/, '');
+  // One canonical spelling for equivalent paths — leading "./", interior "/./",
+  // doubled "//", trailing "/" all collapse — so the legality rule, the fence
+  // comparison, and bareguard enforcement agree on what a scope NAMES. Without
+  // this, a validateJob-green fence like "src/" would reject every workflow
+  // scope inside it (the F9 red-class across two documents).
+  //
+  // Order is load-bearing: "//" collapses and interior "/./" drops BEFORE the
+  // leading "./" strip, so ".//src" → "src" and never "/src". Stripping first
+  // would MINT an absolute prefix from a relative scope — a design-law-#1
+  // containment escape (resolve(workdir, "/src") ignores workdir entirely).
+  //
+  // Deliberately NOT path.posix.normalize: it resolves ".." segments
+  // (normalize("src/../etc") === "etc"), which must stay VISIBLE so
+  // scopeContained can reject them — the whole point of the containment law.
+  let p = scope.replace(/\/\*\*?$/, '');
+  p = p.replace(/\/{2,}/g, '/').replace(/\/\.(?=\/|$)/g, '').replace(/^(?:\.\/)+/, '').replace(/\/+$/, '');
+  return p;
 }
 
 /**
@@ -48,15 +64,35 @@ export function globToPrefix(scope) {
  * resolve to a PROPER subdirectory of the run directory. Absolute paths and
  * ".." segments escape it; "." / "./**" cover the whole run directory — where
  * the close suite lives. Windows spellings ("..\", "C:\") count as escapes.
+ * Exported for the job validator: the operator's outer fence obeys the SAME
+ * law through the same code — two containment transforms would be the F9
+ * red-class one level up.
  * @param {string} s
  */
-function scopeContained(s) {
+export function scopeContained(s) {
   if (s.startsWith('/') || s.includes('\\') || /^[a-zA-Z]:/.test(s)) return false;
   const prefix = globToPrefix(s);
-  if (prefix === '' || prefix === '.') return false;
+  // Belt: reject a prefix that is empty, the run dir, absolute, or a drive —
+  // checked on the NORMALIZED prefix, not just the raw string, so a spelling
+  // that normalizes to something absolute can never pass (defense in depth
+  // against a future globToPrefix regression; the un-gameable gate, law #1).
+  if (prefix === '' || prefix === '.' || prefix.startsWith('/') || /^[a-zA-Z]:/.test(prefix)) return false;
   return prefix.split('/').every((seg) => seg !== '..');
 }
 
+/**
+ * The per-entry write-scope legality law, one home for all three call sites
+ * (workflow gate.writeScope, the job fence, the operator's job-v1 writeScope):
+ * a non-empty string, no mid-path wildcard (enforcement is prefix-containment,
+ * F9), contained under the run dir (law #1). The chains that need per-check
+ * reds still spell the three steps; fenceOk uses this so a fence can never be
+ * blessed that the job validator would reject.
+ * @param {unknown} s
+ */
+function legalScopeEntry(s) {
+  return isNonEmptyString(s) && !globToPrefix(s).includes('*') && scopeContained(s);
+}
+
 // Each verb is legal ONLY in the slot where it has effect: recall/compress
 // build the attempt context (consumed by before-attempt only), stash parks the
 // gap (which exists only after-red), remember is verdict-gated retention
@@ -69,17 +105,72 @@ const VERB_SLOT = { recall: 'before-attempt', compress: 'before-attempt', stash:
 function isKinds(v) {
   return Array.isArray(v) && v.length > 0 && v.every((k) => KINDS.includes(k));
 }
-function isObj(v) {
+/** Shared with the job validator — one definition of "a JSON object" for both
+ * documents (the sibling-validator drift class).
+ * @param {unknown} v */
+export function isObj(v) {
   return v !== null && typeof v === 'object' && !Array.isArray(v);
 }
+/** @param {unknown} v @returns {v is string} */
+export function isNonEmptyString(v) {
+  return typeof v === 'string' && v.length > 0;
+}
+
+// Secrets never enter the tree/spine/configs (hard line) — BOTH config
+// documents get the same sweep: the agent-authored workflow config is the
+// riskier entry point (machine-written), the operator's job spec the other.
+// Known token shapes only, left-bounded so hyphenated words ("flask-sqlalchemy")
+// never red — defense-in-depth; env-only loading is the law, not this regex.
+// ONE shape inventory for the whole system: detection (this sweep) and the
+// spine redactor (interpret wires these into bareguard's redact) must never
+// disagree on what a secret looks like — a shape the validator reds but the
+// redactor passes is a leak on the very output the validator was guarding.
+export const SECRET_PATTERNS = [
+  /(?<![A-Za-z0-9_-])sk-[A-Za-z0-9_-]{16,}/,
+  /(?<![A-Za-z0-9_-])ghp_[A-Za-z0-9]{20,}/,
+  /(?<![A-Za-z0-9_-])github_pat_[A-Za-z0-9_]{20,}/,
+  /(?<![A-Za-z0-9_-])AKIA[0-9A-Z]{16}/,
+  /(?<![A-Za-z0-9_-])xox[bap]-[A-Za-z0-9-]{10,}/,
+];
+const SECRET_RE = new RegExp(SECRET_PATTERNS.map((r) => r.source).join('|'));
 
 /**
- * Validate a workflow config against schema v1.
+ * Red every string in a config tree that carries a known secret-token shape.
+ * @param {any} root
+ * @param {(code: string, path: string, detail?: string) => void} red
+ */
+export function sweepSecretLiterals(root, red) {
+  (/** @type {(node: any, at: string) => void} */
+  function sweep(node, at) {
+    if (typeof node === 'string') {
+      if (SECRET_RE.test(node)) red('secret-literal', at, 'secrets load from the environment; an append-only record that captures a key captures it forever');
+      return;
+    }
+    if (Array.isArray(node)) node.forEach((v, i) => sweep(v, `${at}.${i}`));
+    else if (isObj(node)) {
+      for (const [k, v] of Object.entries(node)) {
+        const path = at ? `${at}.${k}` : k;
+        // keys too: inside free-form values (a gold expected, a conditions map)
+        // a key is unconstrained, so a token can ride a KEY onto the spine
+        if (SECRET_RE.test(k)) red('secret-literal', path, 'secrets load from the environment; an append-only record that captures a key captures it forever');
+        sweep(v, path);
+      }
+    }
+  })(root, '');
+}
+
+/**
+ * Validate a workflow config against schema v1. Returns the parsed config on
+ * ok (single parse — callers never re-parse; null on any red).
  * @param {object|string} input parsed config, or raw JSON text (parse failures are a red)
- * @param {{ shellCapUsd?: number }} [opts] the shell's cap — a config may tighten it, never exceed it
- * @returns {{ ok: boolean, reds: Array<{code: string, path: string, detail?: string}> }}
+ * @param {{ shellCapUsd?: number, jobWriteScope?: string[] }} [opts] the shell's
+ *   ceilings — a config may tighten either, never exceed. `shellCapUsd`: at N2+
+ *   the shell passes min(shell cap, job budgetUsd) — the ceiling chain
+ *   workflow ≤ job ≤ shell. `jobWriteScope`: the job spec's outer fence
+ *   (operator law, job-v1) — every workflow scope must fit inside it.
+ * @returns {{ ok: boolean, reds: Array<{code: string, path: string, detail?: string}>, config: object|null }}
  */
-export function validateConfig(input, { shellCapUsd = 2 } = {}) {
+export function validateConfig(input, { shellCapUsd = 2, jobWriteScope } = {}) {
   /** @type {Array<{code: string, path: string, detail?: string}>} */
   const reds = [];
   /** @type {(code: string, path: string, detail?: string) => void} */
@@ -88,10 +179,10 @@ export function validateConfig(input, { shellCapUsd = 2 } = {}) {
   let c = input;
   if (typeof c === 'string') {
     try { c = JSON.parse(c); } catch (e) {
-      return { ok: false, reds: [{ code: 'parse-error', path: '$', detail: String(/** @type {Error} */ (e).message) }] };
+      return { ok: false, reds: [{ code: 'parse-error', path: '$', detail: String(/** @type {Error} */ (e).message) }], config: null };
     }
   }
-  if (!isObj(c)) return { ok: false, reds: [{ code: 'parse-error', path: '$', detail: 'config must be a JSON object' }] };
+  if (!isObj(c)) return { ok: false, reds: [{ code: 'parse-error', path: '$', detail: 'config must be a JSON object' }], config: null };
 
   // 1. shape — unknown top-level fields red here (smuggled close/provider included)
   for (const key of Object.keys(c)) {
@@ -128,7 +219,7 @@ export function validateConfig(input, { shellCapUsd = 2 } = {}) {
   }
   if (gate.writeScope === undefined) red('missing-required', 'gate.writeScope');
   else if (!(Array.isArray(gate.writeScope) && gate.writeScope.length > 0
-             && gate.writeScope.every((s) => typeof s === 'string' && s.length > 0))) {
+             && gate.writeScope.every(isNonEmptyString))) {
     red('invalid-value', 'gate.writeScope', 'non-empty array of glob strings');
   } else if (!gate.writeScope.every((s) => !globToPrefix(s).includes('*'))) {
     // adaptlearn F9: enforcement (bareguard fs.writeScope) is prefix-containment — a wildcard
@@ -139,6 +230,29 @@ export function validateConfig(input, { shellCapUsd = 2 } = {}) {
     // A scope that can reach the arbiter's inputs is the config-level
     // fit-to-pass surface (design law #1). Reds-before-tokens.
     red('invalid-value', 'gate.writeScope', 'must be a proper subdirectory of the run directory — no absolute paths, no ".." segments, not the run dir itself (design law #1)');
+  } else if (jobWriteScope !== undefined && jobWriteScope !== null) {
+    // Two-layer fence: the job spec's writeScope is operator law; the authored
+    // config may tighten it, never exceed it (the budget pattern, on paths).
+    // null/undefined are the legitimate "no fence" spellings (job optional at
+    // N2, and the only forms that survive JSON transit) — the layer is skipped,
+    // never a deadlock. A PRESENT-but-malformed fence fails CLOSED with its own
+    // red, attributed to jobWriteScope (NOT the innocent workflow field — the
+    // ledger's contrast attribution must not charge the agent's config for the
+    // operator's broken spec).
+    const fenceOk = Array.isArray(jobWriteScope) && jobWriteScope.length > 0 && jobWriteScope.every(legalScopeEntry);
+    if (!fenceOk) {
+      const shown = JSON.stringify(jobWriteScope).slice(0, 200); // bound: a malformed fence is untrusted caller input, and this rides the append-only spine (ralph's 2000-char precedent)
+      red('fence-invalid', 'jobWriteScope', `not a validateJob-green fence (${shown}) — validate the job spec before threading its fence`);
+    } else {
+      // Boundary-aware: "src2" is not inside "src" — prefix means PATH prefix.
+      const fence = jobWriteScope.map(globToPrefix);
+      const inside = (/** @type {string} */ p) => fence.some((f) => p === f || p.startsWith(f + '/'));
+      gate.writeScope.forEach((/** @type {string} */ s, /** @type {number} */ i) => {
+        if (!inside(globToPrefix(s))) {
+          red('scope-escape', `gate.writeScope.${i}`, `"${s}" is outside the job's fence [${jobWriteScope.join(', ')}] — the workflow may tighten the operator's bound, never exceed it`);
+        }
+      });
+    }
   }
 
   const escalation = isObj(c.escalation) ? c.escalation : {};
@@ -173,7 +287,11 @@ export function validateConfig(input, { shellCapUsd = 2 } = {}) {
     }
   }
 
-  return { ok: reds.length === 0, reds };
+  // 5. secrets sweep — same guard as the job spec (the agent-authored document
+  // is the riskier one; a green config is a ledger fact and inherits forever)
+  sweepSecretLiterals(c, red);
+
+  return { ok: reds.length === 0, reds, config: reds.length === 0 ? c : null };
 }
 
 /**

package/types/index.d.ts

@@ -1,5 +1,6 @@
 export { makeSpine } from "./spine.js";
 export { ralph, runClose } from "./ralph.js";
 export { validateConfig, diffPaths, globToPrefix, LOOP_SHAPES, SLOTS, VERBS } from "./validate.js";
+export { validateJob, jobSpecHash, checkApproval, CLOSE_TYPES, CLASSES, CLASS_BY_CLOSE, GOLD_COMPARE, CADENCE_UNITS, PROVIDERS, CONDITION_KEYS } from "./job.js";
 export { interpret, STALL_REDS } from "./interpret.js";
 export { extractRules, MAX_RULES, MAX_RULE_CHARS } from "./extract.js";

package/types/interpret.d.ts

@@ -11,6 +11,10 @@
  * @param {(type: string, data?: object) => object} opts.emit spine emitter
  * @param {object} opts.provider a bareagent provider — SHELL-owned binding (adaptlearn F8: an unsealed binding is a gate bypass)
  * @param {number} [opts.shellCapUsd=2] the shell's USD cap; config budgetUsd is clamped by validation
+ * @param {string[]} [opts.jobWriteScope] the job spec's outer write fence (operator law,
+ *        job-v1) — enforced HERE, the one choke point where a config becomes a Gate:
+ *        every workflow scope must fit inside it (scope-escape config-red otherwise),
+ *        on entry validation and on every revision candidate alike
  * @param {(o: {config: object, gaps: string[], policy: any, onLlmResult: any}) => Promise<{candidate: object|null, parseError?: string|null, costUsd?: number}>} [opts.revisor]
  *        optional mid-run revision seam. Fires ONCE per run after STALL_REDS consecutive
  *        close reds. The interpreter — never the revisor — owns acceptance: the candidate
@@ -20,7 +24,7 @@
  *        the worker.
  * @returns {Promise<'green'|'escalated'|'config-red'>}
  */
-export function interpret(configRaw: object | string, { task, target, close, workdir, capRuns, emit, provider, shellCapUsd, revisor }: {
+export function interpret(configRaw: object | string, { task, target, close, workdir, capRuns, emit, provider, shellCapUsd, jobWriteScope, revisor }: {
     task: string;
     target: string;
     close: string[];
@@ -29,6 +33,7 @@ export function interpret(configRaw: object | string, { task, target, close, wor
     emit: (type: string, data?: object) => object;
     provider: object;
     shellCapUsd?: number | undefined;
+    jobWriteScope?: string[] | undefined;
     revisor?: ((o: {
         config: object;
         gaps: string[];

package/types/job.d.ts

@@ -0,0 +1,57 @@
+/** @typedef {{code: string, path: string, detail?: string}} Red */
+/**
+ * Validate an operator-owned job spec (`schema: "job-v1"`). Never throws on
+ * JSON text or plain parsed data — the ingest contract; a live object with a
+ * hostile accessor is outside it. Every failure is a named red. Returns the
+ * parsed spec on ok (single parse), null on any red.
+ * @param {object|string} input parsed spec, or raw JSON text (parse failures are a red)
+ * @param {{ shellCapUsd?: number }} [opts] the shell's hard ceiling — the job
+ *   budget may tighten it, never exceed it (ceiling chain: workflow ≤ job ≤ shell)
+ * @returns {{ ok: boolean, reds: Red[], job: object|null }}
+ */
+export function validateJob(input: object | string, { shellCapUsd }?: {
+    shellCapUsd?: number;
+}): {
+    ok: boolean;
+    reds: Red[];
+    job: object | null;
+};
+/**
+ * Content hash of a job spec — what an approval record binds to. Any edit to
+ * the spec changes the hash, so an edited spec is unapproved by construction
+ * (interview decision #1: human signs, always, once per spec VERSION).
+ * @param {object} job
+ * @returns {string} sha256 hex
+ */
+export function jobSpecHash(job: object): string;
+/**
+ * Does an approval record cover this exact spec version? Pure predicate — the
+ * N2 runner refuses to run without it; nothing here writes or prompts. The
+ * approval record lives OUTSIDE the document it signs (a spec never contains
+ * its own signature) and is shell/human territory, never agent-writable.
+ * @param {object} job
+ * @param {unknown} approvals array of { specHash, signer, ts } records
+ * @returns {boolean}
+ */
+export function checkApproval(job: object, approvals: unknown): boolean;
+export const CLOSE_TYPES: readonly string[];
+export const CLASSES: readonly string[];
+/** the hierarchy: which verdict classes a close type may claim (PRD §7) */
+export const CLASS_BY_CLOSE: Readonly<{
+    predicate: readonly string[];
+    gold: readonly string[];
+    rubric: readonly string[];
+    hitl: readonly string[];
+}>;
+export const GOLD_COMPARE: readonly string[];
+export const CADENCE_UNITS: readonly string[];
+export const PROVIDERS: readonly string[];
+/** V3 environment label: declared keys only — every field is a lineage-key
+ * candidate at N3. `provider` is part of the key by definition (top-level,
+ * not duplicated here). */
+export const CONDITION_KEYS: readonly string[];
+export type Red = {
+    code: string;
+    path: string;
+    detail?: string;
+};

package/types/ralph.d.ts

@@ -1,9 +1,19 @@
 /**
  * Run a close command; its exit code is the verdict (hard green, PRD §4).
  * 0 → satisfied; nonzero → needs_revision (gap fed back); spawn error → failed (terminal).
+ *
+ * `redact` scrubs the close's own output at the SOURCE — before the gap becomes
+ * a spine event or a worker prompt — so a secret a checked command echoes
+ * (a 401 dumping an `Authorization: Bearer …` header) never enters the
+ * append-only spine (the hard line). It is INJECTED, not imported: the shell
+ * stays stdlib-only and un-gameable, and the redactor is a fixed shell
+ * primitive (bareguard's, wired by the interpreter), never an emergent
+ * component — so V4 holds. The shell's canonical emission IS the redacted text;
+ * a benign gap is returned byte-identical (default: identity).
  * @param {string[]} close argv, e.g. ['node', '--test', 'close/']
+ * @param {(s: string) => string} [redact] source scrubber; identity by default
  */
-export function runClose(close: string[]): {
+export function runClose(close: string[], redact?: (s: string) => string): {
     verdict: string;
     detail: string;
     gap?: undefined;
@@ -38,11 +48,14 @@ export function runClose(close: string[]): {
  * @param {string[]} opts.close argv whose exit code is truth
  * @param {number} opts.capRuns budget: max middle runs
  * @param {(type: string, data?: object) => object} opts.emit a spine emitter
+ * @param {(s: string) => string} [opts.redact] source scrubber for close output
+ *   (secrets never enter the spine); injected so the shell stays stdlib-only
  * @returns {Promise<'green'|'escalated'>}
  */
-export function ralph({ middle, close, capRuns, emit }: {
+export function ralph({ middle, close, capRuns, emit, redact }: {
     middle: (iteration: number, gap?: string) => void | Promise<void>;
     close: string[];
     capRuns: number;
     emit: (type: string, data?: object) => object;
+    redact?: ((s: string) => string) | undefined;
 }): Promise<"green" | "escalated">;

package/types/validate.d.ts

@@ -9,13 +9,42 @@
  */
 export function globToPrefix(scope: string): string;
 /**
- * Validate a workflow config against schema v1.
+ * A scope may never reach the arbiter's inputs (design law #1): it must
+ * resolve to a PROPER subdirectory of the run directory. Absolute paths and
+ * ".." segments escape it; "." / "./**" cover the whole run directory — where
+ * the close suite lives. Windows spellings ("..\", "C:\") count as escapes.
+ * Exported for the job validator: the operator's outer fence obeys the SAME
+ * law through the same code — two containment transforms would be the F9
+ * red-class one level up.
+ * @param {string} s
+ */
+export function scopeContained(s: string): boolean;
+/** Shared with the job validator — one definition of "a JSON object" for both
+ * documents (the sibling-validator drift class).
+ * @param {unknown} v */
+export function isObj(v: unknown): boolean;
+/** @param {unknown} v @returns {v is string} */
+export function isNonEmptyString(v: unknown): v is string;
+/**
+ * Red every string in a config tree that carries a known secret-token shape.
+ * @param {any} root
+ * @param {(code: string, path: string, detail?: string) => void} red
+ */
+export function sweepSecretLiterals(root: any, red: (code: string, path: string, detail?: string) => void): void;
+/**
+ * Validate a workflow config against schema v1. Returns the parsed config on
+ * ok (single parse — callers never re-parse; null on any red).
  * @param {object|string} input parsed config, or raw JSON text (parse failures are a red)
- * @param {{ shellCapUsd?: number }} [opts] the shell's cap — a config may tighten it, never exceed it
- * @returns {{ ok: boolean, reds: Array<{code: string, path: string, detail?: string}> }}
+ * @param {{ shellCapUsd?: number, jobWriteScope?: string[] }} [opts] the shell's
+ *   ceilings — a config may tighten either, never exceed. `shellCapUsd`: at N2+
+ *   the shell passes min(shell cap, job budgetUsd) — the ceiling chain
+ *   workflow ≤ job ≤ shell. `jobWriteScope`: the job spec's outer fence
+ *   (operator law, job-v1) — every workflow scope must fit inside it.
+ * @returns {{ ok: boolean, reds: Array<{code: string, path: string, detail?: string}>, config: object|null }}
  */
-export function validateConfig(input: object | string, { shellCapUsd }?: {
+export function validateConfig(input: object | string, { shellCapUsd, jobWriteScope }?: {
     shellCapUsd?: number;
+    jobWriteScope?: string[];
 }): {
     ok: boolean;
     reds: Array<{
@@ -23,6 +52,7 @@ export function validateConfig(input: object | string, { shellCapUsd }?: {
         path: string;
         detail?: string;
     }>;
+    config: object | null;
 };
 /**
  * Changed JSON paths between two configs — the one-knob mutation checker
@@ -33,6 +63,7 @@ export function validateConfig(input: object | string, { shellCapUsd }?: {
  * @returns {string[]} sorted changed paths, dot-notation with array indices
  */
 export function diffPaths(a: object, b: object): string[];
-export const LOOP_SHAPES: string[];
-export const SLOTS: string[];
-export const VERBS: string[];
+export const LOOP_SHAPES: readonly string[];
+export const SLOTS: readonly string[];
+export const VERBS: readonly string[];
+export const SECRET_PATTERNS: RegExp[];