bareloop 0.3.0 → 0.5.0

package/src/job.js

@@ -51,13 +51,33 @@ export const TOOL_MENU = Object.freeze(['read', 'grep', 'write', 'edit', 'recall
  * menu. Requesting one is a DISTINCT `request-red` (module 4) — the ledger
  * counts admission demand, and a generic invalid-value would bury it as a typo. */
 export const LOCKED_TOOLS = Object.freeze(['run']);
+/** Layer 2 (design record 2026-07-21, decision 5): the verdict-type radio of
+ * the four-field plan shape. v1 ADMITS only `green`; soft-green/hitl are
+ * declared-but-locked — declaring one is a `request-red` (the tool-menu
+ * pattern: disclosure ≠ admission), so the ledger counts the demand and the
+ * non-code rung later fills a declared slot instead of reshaping the schema. */
+export const VERDICT_TYPES = Object.freeze(['green', 'soft-green', 'hitl']);
+export const LOCKED_VERDICTS = Object.freeze(['soft-green', 'hitl']);
+/** which close CLASS a declared verdictType demands — the close hierarchy one
+ * level up: the same laundering guard as CLASS_BY_CLOSE, applied to the plan
+ * shape's single close (green on a rubric would be a fake-hard verdict). */
+const CLASS_BY_VERDICT = Object.freeze({ green: 'hard', 'soft-green': 'soft', hitl: 'hitl' });
 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)
+/** SP-2: API-first; local deferred (PRD §5/§8). `clipipe-subscription` (F42,
+ * bare-agent 0.32.0 tool mode): the CLI as a bare turn-provider on a Claude
+ * subscription — its costUsd axis is NOTIONAL (API-equivalent value, not
+ * billed), so it is a DISTINCT condition: rows never pool with anthropic-api
+ * rows on the cost axis, and budgets sized for one do not transfer. */
+export const PROVIDERS = Object.freeze(['anthropic-api', 'clipipe-subscription']);
 /** 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'];
+const JOB_FIELDS = ['schema', 'job', 'description', 'provider', 'conditions', 'cadence', 'budgetUsd', 'writeScope', 'steps', 'escalation', 'goal', 'verdictType', 'close', '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 */
+const PLAN_CORE_FIELDS = ['goal', 'verdictType', 'close', 'checks'];
 /** 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 = {
@@ -66,6 +86,10 @@ const CLOSE_FIELDS = {
   rubric: ['type', 'criteria'],
   hitl: ['type', 'prompt'],
 };
+/** a named check (decision 1) IS the predicate-close body plus a name — same
+ * fields, same validator, same runClose machinery (a second command shape
+ * would be the F9 two-transforms class one level up) */
+const CHECK_FIELDS = ['name', 'cmd', 'expect', 'judged', 'gapKeep'];
 const SLUG_RE = /^[a-z0-9][a-z0-9-]*$/;
 
 /** @typedef {{code: string, path: string, detail?: string, verb?: string}} Red — `verb` rides request-reds as structured data (the ledger keys on it, never on prose) */
@@ -157,8 +181,22 @@ export function validateJob(input, { shellCapUsd = 2 } = {}) {
     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) {
+  // 4. the two shapes (design record 2026-07-21, decisions 5+6): EITHER the
+  // legacy operator-authored steps[] chain (co-existing scaffolding, staged
+  // sunset — archives alongside config-v1 when the Layer 2 path proves itself)
+  // OR the four-field plan shape (goal/verdictType/close/checks[]) where the
+  // AGENT authors the step plan at run time. Never both: a spec carrying both
+  // would let one shape ride the other as a smuggle channel.
+  const hasSteps = spec.steps !== undefined;
+  const hasPlanCore = PLAN_CORE_FIELDS.some((f) => spec[f] !== undefined);
+  if (hasSteps && hasPlanCore) {
+    red('shape-conflict', 'steps', 'EITHER operator-authored steps[] OR the plan shape (goal/verdictType/close/checks[]) — never both (design record 2026-07-21, decision 6)');
+  } else if (!hasSteps) {
+    if (hasPlanCore || spec.tools !== undefined) validatePlanShape(spec, red, reds);
+    else red('missing-required', 'steps', 'one shape is required: operator-authored steps[] (legacy, staged sunset) or the plan shape goal/verdictType/close/checks[]');
+  } else if (spec.tools !== undefined) {
+    red('invalid-value', 'tools', 'the tool ceiling is a plan-shape field — a legacy steps[] spec grants tools per step');
+  } else 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();
@@ -203,90 +241,7 @@ export function validateJob(input, { shellCapUsd = 2 } = {}) {
 
       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`);
-        // the runner executes cmd as whitespace-split argv with NO shell: quote
-        // characters imply shell semantics the split cannot honor — honest
-        // refusal beats silent misparse (N2 design default)
-        else if (/["']/.test(close.cmd)) red('invalid-value', `${at}.close.cmd`, 'quote characters are inexpressible: cmd runs as whitespace-split argv, no shell');
-        else if (close.cmd !== close.cmd.trim()) red('invalid-value', `${at}.close.cmd`, 'leading/trailing whitespace — argv splits on whitespace and an empty argv[0] cannot spawn; honest refusal beats a silent misparse');
-        if (!Number.isInteger(close.expect)) red('invalid-value', `${at}.close.expect`, 'integer exit code');
-        // The judgment-rendered signal (PRD v1.11, optional). Exit code alone
-        // cannot separate "the suite ran and failed" from "the suite crashed at
-        // load" — they are byte-identical at the seam, and against `node --test`
-        // so are the raw counts (a crashed file is reported as ONE failing test).
-        // So the signal is a FLOOR, not a zero-check: a close declares how many
-        // things it must judge before its exit code means anything at all.
-        if (close.judged !== undefined) {
-          const j = close.judged;
-          if (!isObj(j)) red('invalid-value', `${at}.close.judged`, 'object {pattern, min} — proof the close actually judged something');
-          else {
-            for (const key of Object.keys(j)) {
-              if (!['pattern', 'min'].includes(key)) red('unknown-field', `${at}.close.judged.${key}`);
-            }
-            if (!isNonEmptyString(j.pattern)) red('missing-required', `${at}.close.judged.pattern`, 'regex over the close output with ONE capture group yielding the count');
-            else {
-              let groups = 0;
-              try {
-                // `p|` always matches the empty string, so exec() returns an array
-                // whose length is 1 + the number of capture groups — the only way
-                // to count groups without executing the pattern against real output.
-                groups = (new RegExp(`${j.pattern}|`).exec('')?.length ?? 1) - 1;
-              } catch {
-                red('invalid-value', `${at}.close.judged.pattern`, 'must compile as a RegExp');
-                groups = -1;
-              }
-              // A pattern with no capture group extracts nothing, so EVERY close
-              // would read as crashed — a dead arbiter that reds forever. Red the
-              // spec, not every run.
-              if (groups === 0) red('invalid-value', `${at}.close.judged.pattern`, 'no capture group — the count is read from group 1, so this pattern would crash every close');
-              // More than one is the same defect wearing a subtler hat: runClose
-              // reads group 1 ONLY, so an alternation whose other branch carries
-              // the count leaves group 1 undefined → NaN → judgedCount null →
-              // an exit-0 GREEN stamped 'crashed' (a fake crash, the mirror of
-              // the fake green this floor exists to catch). Alternation stays
-              // fully expressible with non-capturing branches: `(?:a|b) (\d+)`.
-              else if (groups > 1) red('invalid-value', `${at}.close.judged.pattern`, `${groups} capture groups — the count is read from group 1 only; use exactly one capture group and non-capturing (?:…) branches`);
-            }
-            if (!Number.isInteger(j.min) || j.min < 1) {
-              red('invalid-value', `${at}.close.judged.min`, 'integer >= 1 — a floor of 0 is satisfied by judging nothing, which is the check it is meant to make');
-            }
-          }
-        }
-        // The kept-failures pattern (F28, optional). ralph's gap bound head/tail-
-        // elides a large close stream, and a big TAP suite prints its `not ok`
-        // lines in the MIDDLE — so the failing-test NAMES (the causal navigation
-        // input the worker runs on) were deleted in transit and the worker was
-        // told "5 fail" and never WHICH. gapKeep is a regex SOURCE whose matching
-        // lines are PRESERVED in the gap in addition to head+tail. Same discipline
-        // as judged.pattern: a non-empty string that must compile as a RegExp, or
-        // it is a spec red before any tokens burn (reds-before-tokens) — an invalid
-        // keep pattern must never surface as a runtime crash inside the arbiter.
-        if (close.gapKeep !== undefined) {
-          if (!isNonEmptyString(close.gapKeep)) red('invalid-value', `${at}.close.gapKeep`, 'regex source string — lines matching it survive the gap bound (F28)');
-          else {
-            try { new RegExp(close.gapKeep, 'm'); }
-            catch { red('invalid-value', `${at}.close.gapKeep`, 'must compile as a RegExp'); }
-          }
-        }
-      } 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)`);
-        }
-      }
+      if (!validateClose(close, `${at}.close`, red)) return;
       // 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.
@@ -304,6 +259,194 @@ export function validateJob(input, { shellCapUsd = 2 } = {}) {
   return { ok: reds.length === 0, reds, job: reds.length === 0 ? spec : null };
 }
 
+/**
+ * Per-type close contract — fixed menus only. ONE home for both call sites
+ * (a legacy step's close, the plan shape's top-level close): two copies would
+ * be the F9 two-transforms class on the arbiter's own contract.
+ * @param {Record<string, any>} close
+ * @param {string} at path prefix of the close object (e.g. `steps.0.close`, `close`)
+ * @param {(code: string, path: string, detail?: string) => void} red
+ * @returns {boolean} type-in-menu — false means per-type checks were unreachable
+ */
+function validateClose(close, at, red) {
+  if (!CLOSE_TYPES.includes(close.type)) {
+    red('close-type', `${at}.type`, `menu: ${CLOSE_TYPES.join('|')} — a close is data, never code`);
+    return false;
+  }
+  if (close.type === 'predicate') {
+    predicateBody(close, at, red);
+  } else if (close.type === 'gold') {
+    if (close.expected === undefined) red('missing-required', `${at}.expected`);
+    if (!GOLD_COMPARE.includes(close.compare)) red('invalid-value', `${at}.compare`, GOLD_COMPARE.join('|'));
+  } else if (close.type === 'rubric') {
+    if (!isNonEmptyString(close.criteria)) red('missing-required', `${at}.criteria`);
+  } else if (close.type === 'hitl') {
+    if (!isNonEmptyString(close.prompt)) red('missing-required', `${at}.prompt`);
+  }
+  for (const key of Object.keys(close)) {
+    if (!CLOSE_FIELDS[close.type].includes(key)) {
+      red('unknown-field', `${at}.${key}`, `not a ${close.type} field (script bodies and minting claims land here)`);
+    }
+  }
+  return true;
+}
+
+/**
+ * The predicate BODY contract — cmd/expect/judged/gapKeep. Shared verbatim by
+ * the predicate close and the Layer 2 named checks (decision 1: a check runs
+ * under the same runClose machinery, so it validates under the same rules).
+ * @param {Record<string, any>} o the close or check carrying the body
+ * @param {string} at path prefix (e.g. `steps.0.close`, `close`, `checks.1`)
+ * @param {(code: string, path: string, detail?: string) => void} red
+ */
+function predicateBody(o, at, red) {
+  if (!isNonEmptyString(o.cmd)) red('missing-required', `${at}.cmd`);
+  // the runner executes cmd as whitespace-split argv with NO shell: quote
+  // characters imply shell semantics the split cannot honor — honest
+  // refusal beats silent misparse (N2 design default)
+  else if (/["']/.test(o.cmd)) red('invalid-value', `${at}.cmd`, 'quote characters are inexpressible: cmd runs as whitespace-split argv, no shell');
+  else if (o.cmd !== o.cmd.trim()) red('invalid-value', `${at}.cmd`, 'leading/trailing whitespace — argv splits on whitespace and an empty argv[0] cannot spawn; honest refusal beats a silent misparse');
+  if (!Number.isInteger(o.expect)) red('invalid-value', `${at}.expect`, 'integer exit code');
+  // The judgment-rendered signal (PRD v1.11, optional). Exit code alone
+  // cannot separate "the suite ran and failed" from "the suite crashed at
+  // load" — they are byte-identical at the seam, and against `node --test`
+  // so are the raw counts (a crashed file is reported as ONE failing test).
+  // So the signal is a FLOOR, not a zero-check: a close declares how many
+  // things it must judge before its exit code means anything at all.
+  if (o.judged !== undefined) {
+    const j = o.judged;
+    if (!isObj(j)) red('invalid-value', `${at}.judged`, 'object {pattern, min} — proof the close actually judged something');
+    else {
+      for (const key of Object.keys(j)) {
+        if (!['pattern', 'min'].includes(key)) red('unknown-field', `${at}.judged.${key}`);
+      }
+      if (!isNonEmptyString(j.pattern)) red('missing-required', `${at}.judged.pattern`, 'regex over the close output with ONE capture group yielding the count');
+      else {
+        let groups = 0;
+        try {
+          // `p|` always matches the empty string, so exec() returns an array
+          // whose length is 1 + the number of capture groups — the only way
+          // to count groups without executing the pattern against real output.
+          groups = (new RegExp(`${j.pattern}|`).exec('')?.length ?? 1) - 1;
+        } catch {
+          red('invalid-value', `${at}.judged.pattern`, 'must compile as a RegExp');
+          groups = -1;
+        }
+        // A pattern with no capture group extracts nothing, so EVERY close
+        // would read as crashed — a dead arbiter that reds forever. Red the
+        // spec, not every run.
+        if (groups === 0) red('invalid-value', `${at}.judged.pattern`, 'no capture group — the count is read from group 1, so this pattern would crash every close');
+        // More than one is the same defect wearing a subtler hat: runClose
+        // reads group 1 ONLY, so an alternation whose other branch carries
+        // the count leaves group 1 undefined → NaN → judgedCount null →
+        // an exit-0 GREEN stamped 'crashed' (a fake crash, the mirror of
+        // the fake green this floor exists to catch). Alternation stays
+        // fully expressible with non-capturing branches: `(?:a|b) (\d+)`.
+        else if (groups > 1) red('invalid-value', `${at}.judged.pattern`, `${groups} capture groups — the count is read from group 1 only; use exactly one capture group and non-capturing (?:…) branches`);
+      }
+      if (!Number.isInteger(j.min) || j.min < 1) {
+        red('invalid-value', `${at}.judged.min`, 'integer >= 1 — a floor of 0 is satisfied by judging nothing, which is the check it is meant to make');
+      }
+    }
+  }
+  // The kept-failures pattern (F28, optional). ralph's gap bound head/tail-
+  // elides a large close stream, and a big TAP suite prints its `not ok`
+  // lines in the MIDDLE — so the failing-test NAMES (the causal navigation
+  // input the worker runs on) were deleted in transit and the worker was
+  // told "5 fail" and never WHICH. gapKeep is a regex SOURCE whose matching
+  // lines are PRESERVED in the gap in addition to head+tail. Same discipline
+  // as judged.pattern: a non-empty string that must compile as a RegExp, or
+  // it is a spec red before any tokens burn (reds-before-tokens) — an invalid
+  // keep pattern must never surface as a runtime crash inside the arbiter.
+  if (o.gapKeep !== undefined) {
+    if (!isNonEmptyString(o.gapKeep)) red('invalid-value', `${at}.gapKeep`, 'regex source string — lines matching it survive the gap bound (F28)');
+    else {
+      try { new RegExp(o.gapKeep, 'm'); }
+      catch { red('invalid-value', `${at}.gapKeep`, 'must compile as a RegExp'); }
+    }
+  }
+}
+
+/**
+ * The four-field plan shape (design record 2026-07-21, decision 5): goal /
+ * verdictType / close / checks[] (+ the top-level tool ceiling). v1 admits
+ * only verdictType `green`; soft-green/hitl are declared-but-locked and red
+ * as `request-red` — admission demand the ledger counts, never a grant.
+ * @param {Record<string, any>} spec
+ * @param {(code: string, path: string, detail?: string) => void} red
+ * @param {Red[]} reds direct access for structured request-reds
+ */
+function validatePlanShape(spec, red, reds) {
+  if (spec.goal === undefined) red('missing-required', 'goal');
+  else if (!isNonEmptyString(spec.goal)) red('invalid-value', 'goal', 'non-empty text — the goal is what the agent plans against');
+
+  /** @type {string|undefined} the close class the declared verdict demands */
+  let demanded;
+  if (spec.verdictType === undefined) red('missing-required', 'verdictType', `declared radio, never inferred: ${VERDICT_TYPES.join('|')}`);
+  else if (LOCKED_VERDICTS.includes(spec.verdictType)) {
+    // declared-but-locked (disclosure ≠ admission, the tool-menu pattern):
+    // the type rides as a structured field — the ledger keys admission demand
+    // on it, never on prose
+    reds.push({ code: 'request-red', path: 'verdictType', verb: spec.verdictType, detail: `"${spec.verdictType}" is declared-but-locked — not at this rung (v1 admits green only); this red IS the admission evidence, never a grant` });
+    demanded = CLASS_BY_VERDICT[spec.verdictType];
+  } else if (!VERDICT_TYPES.includes(spec.verdictType)) {
+    red('invalid-value', 'verdictType', `menu: ${VERDICT_TYPES.join('|')} — an unknown type is a typo, never a request`);
+  } else {
+    demanded = CLASS_BY_VERDICT[spec.verdictType];
+  }
+
+  if (spec.close === undefined) red('missing-required', 'close', 'declared green with nothing to run it — preflight validates the declaration, never infers');
+  else if (!isObj(spec.close)) red('invalid-value', 'close', 'a close object (type + its fixed fields)');
+  else if (validateClose(spec.close, 'close', red) && demanded !== undefined
+           && !CLASS_BY_CLOSE[spec.close.type].includes(demanded)) {
+    // the hierarchy one level up: the declared verdict demands a close class
+    // its close type cannot legally claim (green-on-rubric is laundering)
+    red('close-hierarchy', 'verdictType', `verdictType ${spec.verdictType} demands a ${demanded}-class close; ${spec.close.type} admits ${CLASS_BY_CLOSE[spec.close.type].join('|')} only (a rubric can never be hard — PRD §7)`);
+  }
+
+  if (spec.checks !== undefined) {
+    if (!Array.isArray(spec.checks) || spec.checks.length === 0) {
+      red('invalid-value', 'checks', 'non-empty array of named checks — omit the field when the job signs none');
+    } else {
+      const seen = new Set();
+      spec.checks.forEach((/** @type {any} */ c, /** @type {number} */ i) => {
+        const at = `checks.${i}`;
+        if (!isObj(c)) { red('invalid-value', at, 'a check must be an object'); return; }
+        for (const key of Object.keys(c)) {
+          if (!CHECK_FIELDS.includes(key)) red('unknown-field', `${at}.${key}`, 'not a check field (script bodies land here)');
+        }
+        if (!isNonEmptyString(c.name) || !SLUG_RE.test(c.name)) red('invalid-value', `${at}.name`, 'kebab-case slug — the plan references checks by name (check-passes(name))');
+        else if (seen.has(c.name)) red('duplicate-id', `${at}.name`, c.name);
+        else seen.add(c.name);
+        predicateBody(c, at, red);
+      });
+    }
+  }
+
+  // the tool CEILING (plan-v1 anchor: every plan step's verbs ⊆ this) — same
+  // grant rules as a step's tools; run stays locked-but-listed (request-red)
+  if (spec.tools !== undefined) {
+    if (!(Array.isArray(spec.tools) && spec.tools.length > 0
+          && spec.tools.every((/** @type {unknown} */ t) => typeof t === 'string')
+          && new Set(spec.tools).size === spec.tools.length)) {
+      red('invalid-value', 'tools', `non-empty unique subset of ${TOOL_MENU.join('|')}`);
+    } else {
+      for (const t of spec.tools.filter((/** @type {string} */ t) => LOCKED_TOOLS.includes(t))) {
+        reds.push({ code: 'request-red', path: 'tools', verb: t, detail: `"${t}" is locked-but-listed — this red IS the admission evidence, never a grant; granted menu: ${TOOL_MENU.join('|')}` });
+      }
+      const unknown = spec.tools.filter((/** @type {string} */ t) => !TOOL_MENU.includes(t) && !LOCKED_TOOLS.includes(t));
+      if (unknown.length) red('invalid-value', 'tools', `unknown tool(s) ${unknown.join(', ')} — menu: ${TOOL_MENU.join('|')}`);
+      // a plan-shape ceiling must grant ≥1 READ-capable verb (review #8): the
+      // scout surveys read-only (the write-class verbs are filtered out of its
+      // menu), so a write-only ceiling hands the scout an EMPTY menu and it
+      // surveys blind — a degradation the validator catches at sign time.
+      else if (!spec.tools.some((/** @type {string} */ t) => TOOL_MENU.includes(t) && !['write', 'edit'].includes(t))) {
+        red('invalid-value', 'tools', 'a plan-shape ceiling must grant ≥1 read-capable verb (read/grep/recall/get) — the scout surveys read-only; a write-only ceiling leaves it blind');
+      }
+    }
+  }
+}
+
 /**
  * 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.

package/src/plan.js

@@ -0,0 +1,237 @@
+// plan-v1 validator — the AGENT-authored half of the two-doc story (Layer 2,
+// design record 2026-07-21; PRD v1.12). The plan is the ONLY document the
+// emergent middle authors: an ordered list of bounded steps, each with a tool
+// grant, a rounds bound, a deliverable target, and a form-check exit. This
+// validator gates it before tokens burn, against the SIGNED job spec:
+//
+//   verbs ⊆ the spec's tool ceiling        → `verb-escape` (the ceiling
+//     exists and the plan overreached — distinct from the operator-side
+//     `request-red`, which is admission demand against the product menu)
+//   bounds ≤ the shell caps                → `bounds`
+//   scopes/targets inside the signed fence → `scope-escape` / `invalid-value`
+//   exits from the closed menu only        → `exit-illegal` (arbiter
+//     inexpressibility: an exit is declarative data the shell evaluates with
+//     its own fixed code — `run` cannot be laundered through it)
+//   check references resolve against the SIGNED checks menu → `check-unknown`
+//     (decision 1: a check the spec doesn't sign does not exist)
+//
+// Like its siblings (validate.js, job.js) it never throws on JSON text or
+// plain parsed data; every failure is a named {code, path, detail} red.
+
+import { TOOL_MENU, LOCKED_TOOLS } from './job.js';
+import { globToPrefix, scopeContained, isObj, isNonEmptyString, sweepSecretLiterals } from './validate.js';
+
+/** the closed exit menu (PRD v1.12 §3 + decision 1's `check-passes`): the
+ * shell evaluates every form with its own fixed code, never a command — the
+ * same both-directions inexpressibility guard as the two-validator split */
+export const EXIT_TYPES = Object.freeze(['artifact-written', 'tree-changed', 'json-valid', 'check-passes']);
+/** decision 8: AND-only conjunction, bounded — no OR (a weak arm would
+ * launder the exit), no NOT */
+export const MAX_EXITS_PER_STEP = 2;
+/** plan size bound — per-step rounds bound the spend, but an unbounded step
+ * COUNT is still an unbounded claim on the wallet; same 8 as loop.maxIterations */
+export const MAX_PLAN_STEPS = 8;
+/** the write-class verbs (BA-13: `edit` is judged by the same fence as
+ * `write`) — a step granting one is a WRITE step for the F17 pairing rule
+ * and the v1.18 target requirement */
+export const WRITE_VERBS = Object.freeze(['write', 'edit']);
+const PLAN_FIELDS = ['schema', 'steps'];
+// decision 7: NO dependsOn — v1 is strictly sequential, array order IS the
+// order; a field nothing consumes is a live-looking knob with zero effect
+// (the F16 inert-op class). The arbiter's own vocabulary (close, budget,
+// fence) is absent by construction — unknown-field at every depth.
+const STEP_FIELDS = ['id', 'action', 'tools', 'rounds', 'target', 'exit'];
+const EXIT_FIELDS = {
+  'artifact-written': ['type', 'path', 'pattern'],
+  'tree-changed': ['type', 'scope'],
+  'json-valid': ['type', 'path'],
+  'check-passes': ['type', 'name'],
+};
+const SLUG_RE = /^[a-z0-9][a-z0-9-]*$/;
+
+/** @typedef {{code: string, path: string, detail?: string, verb?: string}} Red */
+
+/**
+ * Validate an agent-authored plan (`schema: "plan-v1"`) against the SIGNED
+ * job spec. Never throws on JSON text or plain parsed data; every failure is
+ * a named red. Returns the parsed plan on ok (single parse), null on any red.
+ * @param {object|string} input parsed plan, or raw JSON text (parse failures are a red)
+ * @param {{ job?: any, maxStepRounds?: number }} [opts] `job`: the
+ *   validateJob-GREEN four-field spec (the ceiling, the fence, and the checks
+ *   menu all come from it — a missing or non-plan-shape job fails CLOSED);
+ *   `maxStepRounds`: the shell's per-step rounds ceiling (interpret's
+ *   tool-mode TURNS_PER_ATTEMPT) — a step may tighten it, never exceed it.
+ * @returns {{ ok: boolean, reds: Red[], plan: object|null }}
+ */
+export function validatePlan(input, { job, maxStepRounds = 40 } = {}) {
+  /** @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 }); };
+
+  // The signed side, fail-CLOSED (the validate.js fence-invalid pattern): the
+  // ceiling/fence/menu are meaningless without a plan-shape spec, and an open
+  // gate on a malformed one would validate a plan against nothing.
+  if (!isObj(job) || !isNonEmptyString(/** @type {any} */ (job).goal) || !Array.isArray(/** @type {any} */ (job).writeScope)) {
+    return { ok: false, reds: [{ code: 'job-invalid', path: 'job', detail: 'a plan validates only against a validateJob-green plan shape spec (goal/verdictType/close/checks[]) — validate the job first' }], plan: null };
+  }
+  const spec = /** @type {Record<string, any>} */ (job);
+  /** the signed tool ceiling — validateJob permits omission, meaning the full menu */
+  const ceiling = Array.isArray(spec.tools) ? spec.tools : [...TOOL_MENU];
+  const fence = spec.writeScope.map(globToPrefix);
+  const insideFence = (/** @type {string} */ p) => fence.some((f) => p === f || p.startsWith(f + '/'));
+  const checkNames = Array.isArray(spec.checks) ? spec.checks.map((/** @type {any} */ c) => c?.name).filter(isNonEmptyString) : [];
+
+  let p = input;
+  if (typeof p === 'string') {
+    try { p = JSON.parse(p); } catch (e) {
+      return { ok: false, reds: [{ code: 'parse-error', path: '$', detail: String(/** @type {Error} */ (e).message) }], plan: null };
+    }
+  }
+  if (!isObj(p)) return { ok: false, reds: [{ code: 'parse-error', path: '$', detail: 'plan must be a JSON object' }], plan: null };
+  const plan = /** @type {Record<string, any>} */ (p);
+
+  // 1. shape — unknown top-level fields red (a smuggled close/checks/budget
+  // lands here: the arbiter is inexpressible in the plan vocabulary)
+  for (const key of Object.keys(plan)) {
+    if (!PLAN_FIELDS.includes(key)) red('unknown-field', key, 'the plan vocabulary is steps only — the arbiter (close/budget/fence/checks) is signed, never planned');
+  }
+  if (plan.schema === undefined) red('missing-required', 'schema');
+  else if (plan.schema !== 'plan-v1') red('invalid-value', 'schema', `expected "plan-v1", got ${JSON.stringify(plan.schema)}`);
+
+  // 2. steps — ordered array (decision 7: order IS the order), bounded count
+  if (!Array.isArray(plan.steps) || plan.steps.length === 0) {
+    red('missing-required', 'steps', 'non-empty ordered array — v1 executes strictly sequentially, array order is the order');
+  } else if (plan.steps.length > MAX_PLAN_STEPS) {
+    red('bounds', 'steps', `max ${MAX_PLAN_STEPS} steps — per-step rounds bound the spend, the step count bounds the claim on the wallet`);
+  } else {
+    const seen = new Set();
+    plan.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 (!STEP_FIELDS.includes(key)) red('unknown-field', `${at}.${key}`, key === 'dependsOn' ? 'no dependsOn in v1 — strictly sequential, array order is the order (an inert knob is a fake contrast lever)' : 'not a step field — the arbiter is inexpressible here');
+      }
+      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 (!isNonEmptyString(s.action)) red('missing-required', `${at}.action`, 'the step\'s task text — a step without one is an unaimed worker');
+
+      // tools ⊆ the SIGNED ceiling: a verb beyond it is verb-escape with the
+      // verb as structured data (the ledger counts overreach per verb) — an
+      // unknown string stays a typo (invalid-value), never an escape
+      let writeStep = false;
+      if (s.tools === undefined) red('missing-required', `${at}.tools`, 'every step declares its grant — the narrowed menu is the step boundary');
+      else if (!(Array.isArray(s.tools) && s.tools.length > 0
+                 && s.tools.every((/** @type {unknown} */ t) => typeof t === 'string')
+                 && new Set(s.tools).size === s.tools.length)) {
+        red('invalid-value', `${at}.tools`, `non-empty unique subset of the spec ceiling [${ceiling.join(', ')}]`);
+      } else {
+        // three disjoint classes: a LOCKED verb (run — never in any ceiling) is
+        // an escape the ledger must never bury as a typo; a menu verb outside
+        // the SIGNED ceiling is an escape too (overreach, not admission demand);
+        // a string in neither list is a typo (invalid-value)
+        const unknown = s.tools.filter((/** @type {string} */ t) => !TOOL_MENU.includes(t) && !LOCKED_TOOLS.includes(t));
+        if (unknown.length) red('invalid-value', `${at}.tools`, `unknown tool(s) ${unknown.join(', ')} — menu: ${TOOL_MENU.join('|')}`);
+        for (const t of s.tools.filter((/** @type {string} */ t) => LOCKED_TOOLS.includes(t))) {
+          reds.push({ code: 'verb-escape', path: `${at}.tools`, verb: t, detail: `"${t}" is locked at every layer — a worker that can run commands can run its own close` });
+        }
+        for (const t of s.tools.filter((/** @type {string} */ t) => TOOL_MENU.includes(t) && !ceiling.includes(t))) {
+          reds.push({ code: 'verb-escape', path: `${at}.tools`, verb: t, detail: `"${t}" is outside the signed ceiling [${ceiling.join(', ')}] — the plan may narrow the grant, never widen it` });
+        }
+        writeStep = s.tools.some((/** @type {string} */ t) => WRITE_VERBS.includes(t));
+      }
+
+      // rounds ≤ the shell cap (cap-not-estimate; the step bound IS maxTurns)
+      if (!(Number.isInteger(s.rounds) && s.rounds >= 1 && s.rounds <= maxStepRounds)) {
+        red('bounds', `${at}.rounds`, `integer 1..${maxStepRounds} — the step bound is the Gate's maxTurns, it may tighten the shell cap, never exceed it`);
+      }
+
+      // target (v1.18): the per-step deliverable — required on write steps,
+      // always inside the signed fence when present
+      if (s.target === undefined || s.target === '') {
+        if (writeStep) red('missing-required', `${at}.target`, 'a write-granted step declares its deliverable path (v1.18) — an untargeted write step is unattributable');
+      } else if (!isNonEmptyString(s.target) || !scopeContained(s.target)) {
+        red('invalid-value', `${at}.target`, 'a relative path inside the run dir — no absolute paths, no ".." segments');
+      } else if (!insideFence(globToPrefix(s.target))) {
+        red('scope-escape', `${at}.target`, `"${s.target}" is outside the signed fence [${spec.writeScope.join(', ')}]`);
+      }
+
+      validateExit(s, at, red, { checkNames, fence: spec.writeScope, insideFence, writeStep });
+    });
+  }
+
+  // 3. secrets sweep — the agent-authored document is the riskier entry point
+  sweepSecretLiterals(plan, red);
+
+  return { ok: reds.length === 0, reds, plan: reds.length === 0 ? plan : null };
+}
+
+/**
+ * A step's exit: AND-only conjunction from the closed menu, max 2 (decision
+ * 8). Every form is declarative data the shell evaluates with its own fixed
+ * code — `exit-illegal` is the arbiter-inexpressibility red.
+ * @param {Record<string, any>} s the step
+ * @param {string} at step path prefix
+ * @param {(code: string, path: string, detail?: string) => void} red
+ * @param {{ checkNames: string[], fence: string[], insideFence: (p: string) => boolean, writeStep: boolean }} ctx
+ */
+function validateExit(s, at, red, { checkNames, fence, insideFence, writeStep }) {
+  if (!Array.isArray(s.exit) || s.exit.length === 0) {
+    red('missing-required', `${at}.exit`, `non-empty array from the closed menu ${EXIT_TYPES.join('|')} — ALL listed exits must pass (AND-only); a step without an exit has no progress gate`);
+    return;
+  }
+  if (s.exit.length > MAX_EXITS_PER_STEP) {
+    red('exit-illegal', `${at}.exit`, `max ${MAX_EXITS_PER_STEP} exits — AND-only conjunction, bounded (decision 8)`);
+    return;
+  }
+  let hasTreeChanged = false;
+  let hasCheck = false;
+  s.exit.forEach((/** @type {any} */ e, /** @type {number} */ i) => {
+    const eAt = `${at}.exit.${i}`;
+    if (!isObj(e) || !EXIT_TYPES.includes(e.type)) {
+      red('exit-illegal', eAt, `menu: ${EXIT_TYPES.join('|')} — an exit is declarative data the shell evaluates with its own fixed code, never a command`);
+      return;
+    }
+    for (const key of Object.keys(e)) {
+      if (!EXIT_FIELDS[e.type].includes(key)) red('unknown-field', `${eAt}.${key}`, `not a ${e.type} field (commands and script bodies land here)`);
+    }
+    if (e.type === 'check-passes') {
+      hasCheck = true;
+      if (!isNonEmptyString(e.name)) red('invalid-value', `${eAt}.name`, 'the signed check\'s name');
+      else if (!checkNames.includes(e.name)) {
+        // decision 1: a check the spec doesn't sign DOES NOT EXIST — and the
+        // detail names the signed menu so the replan can aim, not guess
+        red('check-unknown', eAt, `"${e.name}" is not a signed check — the agent references checks, never authors them; signed menu: [${checkNames.join(', ') || 'none'}]`);
+      }
+    } else if (e.type === 'tree-changed') {
+      hasTreeChanged = true;
+      if (!isNonEmptyString(e.scope) || !scopeContained(e.scope) || globToPrefix(e.scope).includes('*')) {
+        red('invalid-value', `${eAt}.scope`, 'a contained scope (trailing /** or /* only, no ".." or absolute)');
+      } else if (!insideFence(globToPrefix(e.scope))) {
+        red('scope-escape', `${eAt}.scope`, `"${e.scope}" is outside the signed fence [${fence.join(', ')}]`);
+      }
+    } else { // artifact-written | json-valid — a named file path inside the fence
+      if (!isNonEmptyString(e.path) || !scopeContained(e.path)) {
+        red('invalid-value', `${eAt}.path`, 'a relative file path inside the run dir — no absolute paths, no ".." segments');
+      } else if (!insideFence(globToPrefix(e.path))) {
+        red('scope-escape', `${eAt}.path`, `"${e.path}" is outside the signed fence [${fence.join(', ')}]`);
+      }
+      if (e.type === 'artifact-written' && e.pattern !== undefined) {
+        if (!isNonEmptyString(e.pattern)) red('invalid-value', `${eAt}.pattern`, 'regex source string');
+        else {
+          try { new RegExp(e.pattern, 'm'); }
+          catch { red('invalid-value', `${eAt}.pattern`, 'must compile as a RegExp'); }
+        }
+      }
+    }
+  });
+  // The F17 pairing rule: the seed tree is green, so a lone check-passes on a
+  // write-granted step would pass on the UNTOUCHED repo — an unearned exit.
+  // The POC's changed-from-seed stage existed for exactly this; here it is a
+  // validation law, stated in the plan itself (never hardwired shell code).
+  if (writeStep && hasCheck && !hasTreeChanged) {
+    red('exit-illegal', `${at}.exit`, 'check-passes on a write-granted step requires the tree-changed conjunct — the seed tree is green, so a lone check would pass on the untouched repo (F17/F46 already-green trap)');
+  }
+}