@codedology/code-forge 0.7.6 → 0.8.0

package/src/state/brief-status.mjs

@@ -0,0 +1,131 @@
+/**
+ * B64a (issue #13 item 6): the short status of one run — the data `code-forge status` prints, as
+ * text or as one JSON line. A pure function: it reads the run record and the ledger rows it is
+ * handed and nothing else (no file, no lock, no row written); the CLI (`src/cli/status.mjs`) reads
+ * them and renders the result. The object it returns has exactly the keys of the `--json` run
+ * object, in order: run_id, status, mode, spent_usd, unknown_usd_sessions, budget_usd, blocks,
+ * more, closed, stopped.
+ *
+ * Per run: its status (null when the record has none — `run status` then prints no status either;
+ * the text shows `-`), its mode (`brief` for a `run start --mode brief` run, else `plan`), the
+ * spend (`runSpend`, the same numbers `run status` prints as spent_usd and unknown_usd_sessions;
+ * both null when the caller could not read the ledger, `rows: null`) and the budget the caller
+ * read, then one entry per block that is neither closed nor stopped — closed and stopped blocks are
+ * only counted. A block entry holds:
+ *  - `state`: `open` on its first attempt, `attempt-<n>` after `block attempt` raised it to n; a
+ *    block whose record status is anything other than open shows that status as its state;
+ *  - `level`: the level it was dispatched at (the run record);
+ *  - `model`: `<provider>/<model>` (or the model alone) of the block's latest coder `session` /
+ *    `session.background` row of the run that names a model — the rows `src/session/spawn.mjs`
+ *    writes carry `role`, `provider`, `model`; a `ledger add coder` row (`manual`, no model) is
+ *    skipped — null when the ledger names none;
+ *  - `gate`: the block's LAST gate run — `gate.done` says pass (`all_ok: true`) or fail, a
+ *    `gate.red` with no `gate.done` after it is a fail; the name is the failing gate (the last
+ *    `gate.red` of that run), null on a pass; `{result: 'none', name: null}` when no gate ran;
+ *  - `findings`: the open review findings of the block, counted by the caller's `findingsOf`
+ *    (the CLI counts what the block close gate would refuse, `src/review/gate-check.mjs`).
+ * Blocks are in block id order (numeric-aware: B2 before B10).
+ */
+
+import { runSpend } from '../ledger/spend.mjs';
+
+/**
+ * @typedef {{id: string, state: string, level: string | null, model: string | null, gate: {result: 'pass' | 'fail' | 'none', name: string | null}, findings: number}} BlockStatus
+ * @typedef {{run_id: string, status: string | null, mode: 'plan' | 'brief', spent_usd: number | null, unknown_usd_sessions: number | null, budget_usd: number | null, blocks: BlockStatus[], more: number, closed: number, stopped: number}} RunStatus
+ */
+
+/** @param {string} a @param {string} b @returns {number} */
+const byBlockId = (a, b) => a.localeCompare(b, 'en', { numeric: true }) || (a < b ? -1 : a > b ? 1 : 0);
+
+/**
+ * The block's last gate run (see the module doc).
+ * @param {Array<Record<string, any>>} mine - the block's rows of the run, in ledger order.
+ * @returns {{result: 'pass' | 'fail' | 'none', name: string | null}}
+ */
+export function lastGate(mine) {
+  /** @type {string | null} */
+  let red = null;
+  /** @type {{result: 'pass' | 'fail' | 'none', name: string | null}} */
+  let last = { result: 'none', name: null };
+  for (const r of mine) {
+    if (r.event === 'gate.red') {
+      red = typeof r.gate === 'string' ? r.gate : null;
+      last = { result: 'fail', name: red };
+    } else if (r.event === 'gate.done') {
+      last = r.all_ok === true ? { result: 'pass', name: null } : { result: 'fail', name: red };
+      red = null;
+    }
+  }
+  return last;
+}
+
+/**
+ * The engine/model of the block's latest coder session row, or null.
+ * @param {Array<Record<string, any>>} mine @returns {string | null}
+ */
+export function coderModel(mine) {
+  for (let i = mine.length - 1; i >= 0; i -= 1) {
+    const r = mine[i];
+    if ((r.event === 'session' || r.event === 'session.background') && r.role === 'coder' && typeof r.model === 'string' && r.model.length > 0) {
+      return typeof r.provider === 'string' && r.provider.length > 0 ? `${r.provider}/${r.model}` : r.model;
+    }
+  }
+  return null;
+}
+
+/**
+ * @param {{
+ *   record: Record<string, any>, rows: Array<Record<string, any>> | null, budget: number | null,
+ *   findingsOf: (blockId: string) => number,
+ * }} opts - `rows`: the project's ledger rows (other runs are filtered out here), null when the
+ *   ledger could not be read; `budget`: the workspace's `budget.usd` (null when unset), as
+ *   `run status` reads it.
+ * @returns {RunStatus}
+ */
+export function briefStatus({ record, rows, budget, findingsOf }) {
+  const runId = String(record.run_id);
+  /** @type {Map<string, Array<Record<string, any>>>} the run's rows, grouped by block once */
+  const byBlock = new Map();
+  for (const r of rows ?? []) {
+    if (r?.run !== runId || typeof r.block !== 'string') continue;
+    const list = byBlock.get(r.block);
+    if (list) list.push(r);
+    else byBlock.set(r.block, [r]);
+  }
+  const spend = rows == null ? null : runSpend(rows, runId);
+  const entries = record.blocks && typeof record.blocks === 'object' ? record.blocks : {};
+  const ids = Object.keys(entries).sort(byBlockId);
+  /** @type {BlockStatus[]} */
+  const blocks = [];
+  let closed = 0;
+  let stopped = 0;
+  for (const id of ids) {
+    const entry = entries[id];
+    const status = typeof entry?.status === 'string' ? entry.status : 'open';
+    if (status === 'closed') closed += 1;
+    else if (status === 'stopped') stopped += 1;
+    if (status === 'closed' || status === 'stopped') continue;
+    const mine = byBlock.get(id) ?? [];
+    const attempt = Number.isInteger(entry?.attempt) ? entry.attempt : 1;
+    blocks.push({
+      id,
+      state: status !== 'open' ? status : attempt > 1 ? `attempt-${attempt}` : 'open',
+      level: typeof entry?.level === 'string' ? entry.level : null,
+      model: coderModel(mine),
+      gate: lastGate(mine),
+      findings: findingsOf(id),
+    });
+  }
+  return {
+    run_id: runId,
+    status: typeof record.status === 'string' ? record.status : null,
+    mode: record.mode === 'brief' ? 'brief' : 'plan',
+    spent_usd: spend === null ? null : spend.usd,
+    unknown_usd_sessions: spend === null ? null : spend.unknown,
+    budget_usd: budget,
+    blocks,
+    more: 0,
+    closed,
+    stopped,
+  };
+}

package/src/state/config-snapshot.mjs

@@ -34,6 +34,16 @@ export const IMMUTABLE_KEYS = Object.freeze({
   // B58: the owner's switch past the local per-file review is set before the run starts or not at
   // all, so nobody turns it on (or off) mid-run
   'review.external': 'the outside reviewer is fixed by the owner before the run starts',
+  // B62a: every block of the run is isolated the same way — only two blocks that each have their
+  // own worktree may share owned paths — so neither key changes mid-run
+  'proof.isolation': 'every block of the run is isolated the same way',
+  'proof.worktree': 'the worktrees and branches of the open blocks were made with it',
+  // B63b: it tightens `block close` (the coder's green test run), so it is authority like
+  // `review.external`; the rest of `context` stays live
+  'context.require_coder_tests': 'whether close needs the coder\'s green test run is fixed by the owner before the run starts',
+  // B64b: the block-end hook runs a command on the owner's machine at every block end, so only
+  // the owner sets it, before the run starts
+  'hooks.on_block_end': 'it runs a command on the owner\'s machine at every block end; fixed by the owner before the run starts',
 });
 
 /** @param {unknown} v @returns {boolean} what `JSON.stringify` drops from an object. */
@@ -154,24 +164,74 @@ export function snapshotFor(record, ticket) {
 }
 
 /**
- * B58: the outside reviewer named by the snapshot in force when `review.external.required` is
- * true; null otherwise (key absent, `required` false, or a record from before snapshots). The key
- * is immutable ({@link IMMUTABLE_KEYS}), so this is the value `run start` stored.
+ * The config snapshot in force for the run (no ticket pin), or null for a record from before
+ * snapshots.
  * @param {Record<string, any>} record
- * @returns {string | null}
+ * @returns {Record<string, any> | null}
  * @throws {StateError} `config-snapshot` when the snapshot in force does not match its hash.
  */
-export function externalReviewer(record) {
-  let snap;
+export function configInForce(record) {
   try {
-    snap = snapshotFor(record, '');
+    return snapshotFor(record, '')?.config ?? null;
   } catch (thrown) {
     if (!(thrown instanceof Error) || thrown.message !== 'config-snapshot') throw thrown;
     throw new StateError('config-snapshot', `run ${record.run_id}: the config snapshot in force does not match its hash`);
   }
-  const external = snap?.config.review?.external;
+}
+
+/**
+ * B58: the outside reviewer named by the snapshot in force when `review.external.required` is
+ * true; null otherwise (key absent, `required` false, or a record from before snapshots). The key
+ * is immutable ({@link IMMUTABLE_KEYS}), so this is the value `run start` stored.
+ * @param {Record<string, any>} record
+ * @returns {string | null}
+ * @throws {StateError} `config-snapshot` when the snapshot in force does not match its hash.
+ */
+export function externalReviewer(record) {
+  const external = configInForce(record)?.review?.external;
   if (!isMapping(external) || external.required !== true) return null;
   // required without a usable name is no switch at all (the schema refuses it; this is the floor)
   const name = typeof external.name === 'string' ? external.name.trim() : '';
   return name === '' ? null : name; // trimmed: no row ever carries padding
 }
+
+/**
+ * B63b: whether `block close` needs the coder's `TESTS <command> exit=0` line — true only when the
+ * snapshot in force sets `context.require_coder_tests: true` (false for the key absent or false,
+ * or a record from before snapshots). The key is immutable ({@link IMMUTABLE_KEYS}), so this is
+ * the value `run start` stored; the live config is never read.
+ * @param {Record<string, any>} record
+ * @returns {boolean}
+ * @throws {StateError} `config-snapshot` when the snapshot in force does not match its hash.
+ */
+export function requireCoderTests(record) {
+  const context = configInForce(record)?.context;
+  return isMapping(context) && context.require_coder_tests === true;
+}
+
+/** The default `hooks.on_block_end.timeout_s`. */
+export const HOOK_TIMEOUT_DEFAULT_S = 60;
+/** The schema's bounds of `hooks.on_block_end.timeout_s`. */
+export const HOOK_TIMEOUT_MIN_S = 1;
+export const HOOK_TIMEOUT_MAX_S = 600;
+
+/**
+ * `hooks.on_block_end` of the run-start config snapshot (never the live config), or null when it
+ * is absent or malformed (the schema refuses a malformed one at `run start`).
+ * @param {Record<string, any>} record
+ * @returns {{argv: string[], timeoutS: number} | null}
+ */
+export function blockEndHook(record) {
+  let hook;
+  try {
+    hook = configInForce(record)?.hooks?.on_block_end;
+  } catch {
+    return null;
+  }
+  if (hook === null || typeof hook !== 'object') return null;
+  const { argv, timeout_s: timeout } = hook;
+  if (!Array.isArray(argv) || argv.length === 0 || !argv.every((a) => typeof a === 'string' && a.length > 0)) return null;
+  const timeoutS = timeout === undefined ? HOOK_TIMEOUT_DEFAULT_S : timeout;
+  if (!Number.isInteger(timeoutS) || timeoutS < HOOK_TIMEOUT_MIN_S || timeoutS > HOOK_TIMEOUT_MAX_S) return null;
+  return { argv: [...argv], timeoutS };
+}

package/src/state/registry.mjs

@@ -34,6 +34,10 @@
  * vs `src/**` and vs `src/feature/*.swift` overlap, vs `src/*.mjs` and `src/featureX/*` do not);
  * a `file` entry against a glob overlaps only when the glob matches it (`src/README` vs
  * `src/**\/*.mjs` does not).
+ *
+ * B62a — between two OPEN BLOCKS the rule is `blocksOverlap`: two blocks that each have their own
+ * worktree (`proof.isolation: worktree`) may own the same path; any pair with a shared-tree block
+ * in it is checked with `findOverlap` exactly as above.
  */
 
 import { StateError } from './paths.mjs';
@@ -99,21 +103,24 @@ export function expandBraces(pattern) {
 
 /**
  * @param {unknown} owned
+ * @param {{label?: string, code?: string}} [as] - B60: `block open --tests` checks its test files by
+ *   the same rules, named `test files` with the code `bad-tests`.
  * @returns {string[]}
  * An EXACT entry (no `*`, `?` or `{`) may contain `[ ] ( ) ! + @ }` — real routes such as
  * `pages/[id].vue`, `app/(group)/page.tsx`, `@types/x.d.ts` — and is matched literally by
  * string equality. A GLOB entry may not: there those characters would be character-class or
  * extglob syntax this matcher does not implement, so it is refused with that reason rather than
  * silently read one way by us and another way by git or a shell.
- * @throws {StateError} `bad-owned` — empty, absolute, `.`/`..`/empty segments (checked on every
+ * @throws {StateError} with code `as.code` (default `bad-owned`) and a message that starts with
+ *   `as.label` (default `owned files`) — empty, absolute, `.`/`..`/empty segments (checked on every
  *   brace alternative), backslashes, unbalanced braces, or unsupported glob syntax in a glob.
  */
-export function assertOwned(owned) {
-  if (!Array.isArray(owned) || owned.length === 0) throw new StateError('bad-owned', 'owned files: at least one path is required');
+export function assertOwned(owned, { label = 'owned files', code = 'bad-owned' } = {}) {
+  if (!Array.isArray(owned) || owned.length === 0) throw new StateError(code, `${label}: at least one path is required`);
   for (const entry of owned) {
     /** @param {string} why */
     const refuse = (why) => {
-      throw new StateError('bad-owned', `owned files: invalid path ${JSON.stringify(entry)}: ${why}`);
+      throw new StateError(code, `${label}: invalid path ${JSON.stringify(entry)}: ${why}`);
     };
     if (typeof entry !== 'string' || entry.length === 0) refuse('must be a non-empty string');
     if (entry.includes('\\')) refuse('backslashes are not allowed (POSIX paths only)');
@@ -240,6 +247,30 @@ export function findOverlap(ownedA, ownedB, { kindsA, kindsB } = {}) {
   return null;
 }
 
+/**
+ * One open block as the overlap rule sees it: its owned entries, their kinds (B57) and its own
+ * worktree, if any (B62a). `worktree` is the run record's `{path, branch, base_sha}` (or, for a
+ * block being opened, `{path}` of the tree it is about to get); `null` or absent means it works in
+ * the shared tree (export or lock isolation). Every caller passes this one shape.
+ * @typedef {{owned_files: ReadonlyArray<string>, owned_kinds?: OwnedKinds, worktree?: {path: string} | null}} OverlapBlock
+ */
+
+/**
+ * B62a: the owned-files overlap rule between two open blocks. Two blocks that EACH have their own
+ * worktree, at different paths, may own the same path — each edits its own copy on its own branch,
+ * and nothing is merged by code-forge — so the pair never overlaps. Two blocks on the SAME tree
+ * path edit one tree, and a block without a worktree (export or lock isolation) edits the shared
+ * tree: both are checked exactly as before B62a ({@link findOverlap}, B57's kinds included).
+ * @param {OverlapBlock} a @param {OverlapBlock} b
+ * @returns {[string, string] | null} the first overlapping pair (a's entry, b's entry), or null.
+ */
+export function blocksOverlap(a, b) {
+  const treeA = a.worktree ?? null;
+  const treeB = b.worktree ?? null;
+  if (treeA !== null && treeB !== null && treeA.path !== treeB.path) return null;
+  return findOverlap(a.owned_files, b.owned_files, { kindsA: a.owned_kinds, kindsB: b.owned_kinds });
+}
+
 /**
  * Does `owned` own repo-relative `file`? A directory-like exact entry owns its path and every path
  * below it, a `file` one (per `kinds`) only itself (B57); a glob entry owns what it matches. A

package/src/state/run.mjs

@@ -132,11 +132,17 @@ async function pinWorker(workerPid, probe) {
   return { pid: workerPid, started_at: startedAt };
 }
 
+/** B59: the run modes `run start --mode` takes; `plan` is the default and is never recorded. */
+export const RUN_MODES = Object.freeze(['plan', 'brief']);
+
 /**
  * `run start`: record + key + worker pin + ledger `run.start`, all under the run lock. An
  * existing run id is refused before anything is written (its key and record stay untouched).
+ * B59: `mode: 'brief'` (a run with briefs and no plan) is stored in the record as `mode` and
+ * written as a signed `run.mode {mode: 'brief', plan: 'none'}` row right after `run.start`; `plan`
+ * or no mode leaves the record and the rows exactly as before. Nothing changes the mode later.
  * @param {{
- *   workspace: string, project: string, config?: Record<string, any>, engine?: string,
+ *   workspace: string, project: string, config?: Record<string, any>, engine?: string, mode?: string,
  *   runId?: string, workerPid?: number, orchestratorPid?: number, soloPid?: string | null,
  *   writeRow: WriteRow, probe?: StartTimeProbe, now?: Date,
  * }} opts
@@ -149,6 +155,8 @@ export async function startRun(opts) {
     throw new StateError('bad-project', 'project slug must match /^[a-z0-9][a-z0-9-]*$/ (config key project.slug)');
   }
   const workspace = assertWorkspaceOutsideRuns(opts.workspace);
+  if (opts.mode !== undefined && !RUN_MODES.includes(opts.mode)) throw new StateError('usage', `--mode must be one of ${RUN_MODES.join(', ')}`);
+  const brief = opts.mode === 'brief';
   // B58: the schema lets `review.external` stand without a name while `required` is off; on, the
   // reviewer must be named — refused before anything is written
   const external = config.review?.external;
@@ -172,6 +180,7 @@ export async function startRun(opts) {
     status: 'active',
     blocks: {},
     orphans: [],
+    ...(brief ? { mode: 'brief' } : {}),
     // B35: the config snapshot the worker reviews with (`run reload` replaces it). Only when the
     // caller passed the loaded config: a record without it keeps the worker on its boot config.
     ...(opts.config !== undefined ? { config: initialConfigState(config) } : {}),
@@ -185,6 +194,7 @@ export async function startRun(opts) {
     await generateKey(runId);
     await saveRun(record);
     await writeSigned(runId, writeRow, { event: 'run.start', engine: record.engine, worker_pinned: worker !== null });
+    if (brief) await writeSigned(runId, writeRow, { event: 'run.mode', mode: 'brief', plan: 'none' });
     // B58: the owner's outside reviewer is on the ledger from the first row of the run on
     const reviewer = externalReviewer(record);
     if (reviewer !== null) await writeSigned(runId, writeRow, { event: 'review.external', required: true, reviewer });
@@ -207,7 +217,9 @@ export async function startRun(opts) {
  * Fixed keys ({@link IMMUTABLE_KEYS}): every one that changed is refused at once
  * (`immutable-key`, nothing written). A record from before snapshots (no `config`) is checked
  * against what it does store: `engine` and the ledger slug (`effectiveSlug`, computed by the
- * caller the same way `run start` did), and B58's `review.external.required` must not turn true;
+ * caller the same way `run start` did), B58's `review.external.required` must not turn true,
+ * B62a's `proof.isolation` must not turn to `worktree`, and B63b's `context.require_coder_tests`
+ * must not turn true;
  * it then gets its first snapshot, `changed_keys: null`, `old_hash: null`.
  *
  * No change (same hash) ⇒ nothing written, no row. Otherwise the record is saved FIRST (it is the
@@ -250,6 +262,13 @@ export async function reloadRun({ runId, config, readPending = () => [], effecti
       // B58: a run started without the key has none to keep — turning it on now is a change; an
       // entry that leaves it off (`required` false or absent, as the schema default) is not
       if (config.review?.external?.required === true) frozen.push('review.external');
+      // B62a: a run started without a snapshot was isolated by export (or lock); turning worktree
+      // isolation on now is a change
+      if (config.proof?.isolation === 'worktree') frozen.push('proof.isolation');
+      // B63b: likewise, a run started without a snapshot never required the coder's tests
+      if (config.context?.require_coder_tests === true) frozen.push('context.require_coder_tests');
+      // B64b: and never had a block-end hook
+      if (config.hooks?.on_block_end !== undefined) frozen.push('hooks.on_block_end');
     }
     if (frozen.length > 0) {
       const why = frozen.map((key) => `${key} cannot change mid-run (${IMMUTABLE_KEYS[/** @type {keyof typeof IMMUTABLE_KEYS} */ (key)]})`);

package/src/util/breadcrumbs.mjs

@@ -27,6 +27,7 @@ import path from 'node:path';
 export const SUBCOMMANDS = Object.freeze({
   autopilot: ['start', 'status', 'stop'],
   block: ['open', 'attempt', 'rebase', 'claim', 'close', 'stop', 'waive'],
+  context: ['pack'],
   gates: ['detect', 'run', 'secret-scan', 'safe-edit', 'scope', 'acceptance', 'transcript-grep'],
   jev: ['ask'],
   keys: ['list', 'set', 'test', 'remove'],

package/src/util/forbidden.mjs

@@ -277,7 +277,9 @@ export const FORBIDDEN = Object.freeze(
  * always appends them, so every list built for a coder carries them.
  *  - `code-forge block waive` — waiving a review finding is human-only;
  *  - `code-forge autopilot` (any subcommand, B45) — the owner's grant to a delegate;
- *  - `--no-require-reviews` — the human's way out of `block close`'s per-file review check.
+ *  - `--no-require-reviews` — the human's way out of `block close`'s per-file review check;
+ *  - `--remove-worktree` (B62a) — `block close` removing the block's worktree, the orchestrator's
+ *    alone. `block close` itself is not on this list, so the flag is listed on its own.
  * @type {ReadonlyArray<ForbiddenEntry>}
  */
 export const CODER_ONLY_FORBIDDEN = Object.freeze(
@@ -306,6 +308,12 @@ export const CODER_ONLY_FORBIDDEN = Object.freeze(
       tokens: ['--no-require-reviews'],
       description: 'Close a block without the per-file review check (--no-require-reviews) — human-only',
     },
+    {
+      id: 'code-forge-remove-worktree',
+      kind: 'contains',
+      tokens: ['--remove-worktree'],
+      description: "Remove a block's worktree at close (block close --remove-worktree, B62a) — the orchestrator only",
+    },
   ].map(freezeEntry),
 );
 
@@ -342,6 +350,33 @@ export function mergeForbidden(extraTokens = []) {
   return [...FORBIDDEN, ...CODER_ONLY_FORBIDDEN, ...extras];
 }
 
+/** B64b: the id of the entry {@link hookForbidden} builds. */
+export const HOOK_FORBIDDEN_ID = 'code-forge-on-block-end-hook';
+
+/**
+ * B64b: the owner's `hooks.on_block_end` command as a coder-forbidden `prefix` entry — the hook
+ * runs only from the orchestrator's block-end verbs, never for a coder. The tokens are TRIMMED:
+ * the command name of `argv[0]` (its basename, as every reading normalizes it), plus `argv[1]`
+ * when there is one that is not blank (clause 3, "if any"). `argv[1]` stays ONE token even with
+ * inner whitespace — a literal match, as ruled. No entry (`[]`, so a list built with it is
+ * unchanged) when there is no hook (`argv` absent, empty, or not all non-empty strings), or when
+ * `argv[0]` is blank, names a directory (`/`, `dir/`), or is `.` or `..`. Appended by the caller
+ * after the static entries; it never replaces or weakens one.
+ * @param {unknown} argv
+ * @returns {ForbiddenEntry[]}
+ */
+export function hookForbidden(argv) {
+  if (!Array.isArray(argv) || argv.length === 0 || !argv.every((a) => typeof a === 'string' && a.length > 0)) return [];
+  const first = argv[0].trim();
+  // a command name that is blank, a directory (`/`, `dir/`), `.` or `..` matches nothing a coder runs
+  if (first.length === 0 || /[/\\]$/.test(first)) return [];
+  const name = commandName(first).trim();
+  if (name.length === 0 || name === '.' || name === '..') return [];
+  const arg = argv.length > 1 ? argv[1].trim() : '';
+  const tokens = arg.length > 0 ? [name, arg] : [name];
+  return [freezeEntry({ id: HOOK_FORBIDDEN_ID, kind: 'prefix', tokens, description: 'Run the configured on_block_end hook (hooks.on_block_end) — it runs only at a block end, from the orchestrator\'s verbs' })];
+}
+
 // ── Normalization ────────────────────────────────────────────────────────────
 
 /** git global options that take the NEXT argv token as their value (when not written `--opt=value`). */

package/src/util/gate-token.mjs

@@ -0,0 +1,8 @@
+/**
+ * The one argv item a gate uses for the block's related tests. It lives in `util` because two
+ * layers need the same value: `gates/expand.mjs` expands it, and `config/validate.mjs` refuses it as
+ * a gate's command (`config` may not import `gates`).
+ */
+
+/** A gate argv item that is EXACTLY this string expands to the block's test files. */
+export const TEST_FILES_TOKEN = '{test_files}';