rhachet-roles-bhrain 0.31.0 → 0.31.2

package/dist/contract/cli/learn.d.ts

@@ -0,0 +1,9 @@
+/**
+ * .what = cli entrypoint for the learn.domain.terms skill (both faces)
+ * .why = the onStop hook nudges when the distillation is stale; the clone runs it
+ *        to reflect + distill
+ *
+ * exits 0 when fresh (hook), after the guide (clone), or after --help
+ * exits 2 when stale (hook) to hold the stop open (never a write)
+ */
+export declare const learnDomainTerms: () => Promise<void>;

package/dist/contract/cli/learn.js

@@ -0,0 +1,342 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.learnDomainTerms = void 0;
+/**
+ * .what = cli entrypoint for the learner learn.domain.terms skill
+ * .why = enables shell invocation via package-level import, isolated on its own
+ *        cli subpath so the onStop hook loads minimal modules (see
+ *        rule.require.isolated-cli-subpath-exports)
+ *
+ * two faces, one skill (mirrors the driver's route.drive):
+ *   --when hook.onStop → staleness check; exit 2 to hold the stop when the
+ *                        distillation is stale, else exit 0 (read-only, never writes)
+ *   (no --when)        → the clone's reflect-and-distill guide; findserts the
+ *                        glossary scaffold, then prints how to distill
+ */
+const helpful_errors_1 = require("helpful-errors");
+const getInvocationArgs_1 = require("../../domain.operations/cli/getInvocationArgs");
+const genDomainTermsScaffold_1 = require("../../domain.operations/learn/genDomainTermsScaffold");
+const getDomainTermsPaths_1 = require("../../domain.operations/learn/getDomainTermsPaths");
+const getSweepProgress_1 = require("../../domain.operations/learn/getSweepProgress");
+const isProgressArticulated_1 = require("../../domain.operations/learn/isProgressArticulated");
+const isSweepStale_1 = require("../../domain.operations/learn/isSweepStale");
+/**
+ * .what = emit the established two-line header — mascot + slogan, then scroll + command
+ * .why = all three faces (clone guide, onStop nudge, --help) open the SAME way; render
+ *        from ONE place so the headers can never drift out of sync
+ *        (rule.require.single-source-of-truth-for-render). the slogan varies by face
+ *        (the nudge is a staleness reminder, the others a plain invocation) but the
+ *        shape — `🦉 <slogan>` / blank / `📜 <command>` — is identical for all
+ */
+const emitHeader = (emit, input) => {
+    emit(`🦉 ${input.slogan}`);
+    emit('');
+    emit(`📜 ${input.command}`);
+};
+/**
+ * .what = the flag portion of a token — the part before any `=` (e.g. `--help=x` → `--help`)
+ * .why = one splitter so both the help check and the allowlist parse the combined
+ *        `--flag=value` form the same way (rule.require.ubiqlang — one parse of a token)
+ */
+const asFlagName = (arg) => arg.split('=')[0];
+/**
+ * .what = the flags the rhachet harness always injects to identify the invocation
+ * .why = `rhx <skill>` prepends --skill/--role/--repo (each with a value) to the argv it
+ *        hands the wrapper; they name WHICH skill ran, they are NOT part of this skill's
+ *        own surface. they must be stripped before the strict allowlist runs, else
+ *        assertKnownFlags rejects the harness's own flags and the onStop hook can never fire
+ */
+const RHACHET_INJECTED_FLAGS = ['--skill', '--role', '--repo'];
+/**
+ * .what = the caller's own args — the invocation args minus the rhachet-injected flags
+ * .why = leaves only this skill's surface (--when / --help) for strict validation, so a
+ *        genuine typo or stray positional is still caught while the harness flags pass
+ *        through. handles both the space form (`--skill x`) and the combined (`--skill=x`)
+ */
+const getOwnArgs = (argv) => {
+    const args = (0, getInvocationArgs_1.getInvocationArgs)(argv);
+    // mark each injected flag token, plus the value token after a space-form one
+    const dropped = new Set();
+    args.forEach((arg, index) => {
+        if (!RHACHET_INJECTED_FLAGS.includes(asFlagName(arg)))
+            return;
+        dropped.add(index);
+        // `--skill=x` carries its value inline; `--skill x` puts it in the next token
+        if (!arg.includes('='))
+            dropped.add(index + 1);
+    });
+    return args.filter((_, index) => !dropped.has(index));
+};
+/**
+ * .what = detect a --help / -h request in argv (both bare and `--help=` combined forms)
+ * .why = a help request must short-circuit BEFORE either face runs, so the clone face
+ *        never writes on a --help (rule.require.help-on-demand). the combined `--help=x`
+ *        form must also count, else it silently falls through to the clone face that writes
+ */
+const isHelpRequested = (argv) => {
+    const args = getOwnArgs(argv);
+    return args.some((arg) => ['--help', '-h'].includes(asFlagName(arg)));
+};
+/**
+ * .what = the flags this skill recognizes (its whole surface)
+ * .why = one allowlist so assertKnownFlags can reject all else — a typo like
+ *        --wen must fail loud, never silently fall through to the clone face
+ */
+const KNOWN_FLAGS = ['--when', '--help', '-h'];
+/**
+ * .what = is this token one the skill recognizes?
+ * .why = accepts the conventional combined `--flag=value` form a human expects
+ *        (rule.forbid.friction-hazards), via asFlagName. the posix `--` marker is
+ *        already filtered by getInvocationArgs, so it never reaches here
+ */
+const isKnownToken = (arg) => KNOWN_FLAGS.includes(asFlagName(arg));
+/**
+ * .what = reject any token the skill does not recognize (unknown flags AND stray positionals)
+ * .why = an unrecognized token — a typo `--wen`, a `--verbose`, or a bare positional `foo` —
+ *        must NOT be silently ignored, else the clone face runs and writes when the caller
+ *        intended the hook face or a no-op. this skill has ZERO positional args, so any token
+ *        that is not a known flag (nor a --when value) is a fault. fail-loud
+ *        (rule.forbid.friction-hazards, safe-by-default)
+ */
+const assertKnownFlags = (argv) => {
+    const args = getOwnArgs(argv);
+    // the token right after a space-form `--when` is its VALUE, not a flag — skip it so
+    // a value that starts with `-` (e.g. `--when -x`) reads as the value and parseWhen
+    // gives the precise `invalid --when: -x` error, not a generic unknown-token one
+    const whenIndex = args.indexOf('--when');
+    const whenValueIndex = whenIndex === -1 ? -1 : whenIndex + 1;
+    const unknown = args.filter((arg, index) => index !== whenValueIndex && !isKnownToken(arg));
+    if (unknown.length === 0)
+        return;
+    throw new helpful_errors_1.BadRequestError(`unexpected arg(s): ${unknown.join(', ')}. this skill accepts only: --when hook.onStop | --help | -h`, { unknown });
+};
+/**
+ * .what = validate a --when value into the one supported hook context
+ * .why = an absent or wrong value is a caller error, never a silent fall-through to
+ *        the clone face (which writes). fail-loud on both (rule.forbid.failhide)
+ */
+const asWhenValue = (value) => {
+    if (value === 'hook.onStop')
+        return 'hook.onStop';
+    // render the fault legibly: an absent token reads '(absent)', an empty value
+    // (e.g. the combined `--when=` form) reads '(empty)' — never a blank before the
+    // period, which would read as a cryptic error (rule.forbid.friction-hazards)
+    const shown = value === undefined ? '(absent)' : value === '' ? '(empty)' : value;
+    throw new helpful_errors_1.BadRequestError(`invalid --when: ${shown}. only 'hook.onStop' is supported`, { when: value ?? null });
+};
+/**
+ * .what = parse the --when hook context from argv
+ * .why = selects the hook face vs the clone face; only hook.onStop is a hook
+ *        context here (this skill has no onBoot face). accepts both the combined
+ *        `--when=value` and the space-separated `--when value` forms
+ */
+const parseWhen = (argv) => {
+    const args = getOwnArgs(argv);
+    // combined form `--when=value` → validate its inline value
+    const combined = args.find((arg) => arg.startsWith('--when='));
+    if (combined)
+        return asWhenValue(combined.slice('--when='.length));
+    // no --when at all → clone face
+    const whenIndex = args.indexOf('--when');
+    if (whenIndex === -1)
+        return undefined;
+    // space-separated form `--when value` → validate the next token
+    return asWhenValue(args[whenIndex + 1]);
+};
+/**
+ * .what = the shared distill guidance body — the how (reflect + act) + the canon
+ * .why = both faces teach the SAME moves and cite the SAME canon; render them from
+ *        ONE place, into a caller-supplied sink (stdout for the clone guide, stderr
+ *        for the onStop nudge), so the two renders can never drift
+ *        (rule.require.single-source-of-truth-for-render,
+ *        rule.forbid.duplicate-format-tree-operations). every line is a mid-branch
+ *        (`├─`), so each face wraps it with its own opener and closer
+ */
+const emitDistillMoves = (emit, input) => {
+    emit('   ├─ do this now — review + redistill the terms this round touched');
+    emit('   │  ├─ 1. recall — which domain objects & operations did you declare or engage?');
+    emit('   │  │        split each name into its terms (getStone → verb `get` + noun `stone`)');
+    emit('   │  ├─ 2. conform-or-dispute each EXTANT term (already in the glossary):');
+    emit('   │  │     ├─ your contract uses the canonical word → conform, you are done');
+    emit('   │  │     └─ you reached for a synonym → rename to the canonical word,');
+    emit('   │  │           or open a dispute in its `.reason` (adhere, or argue — never drift)');
+    emit('   │  ├─ 3. pave the path for each NEW term (born this round, not yet in the glossary):');
+    emit('   │  │     ├─ write its `term=<x>._.choice.*` cluster:');
+    emit('   │  │     │     ├─ term=<x>._.choice._.md              (say: chosen word, kind, forbidden synonyms)');
+    emit('   │  │     │     ├─ term=<x>._.choice.reason.md         (ref: etymology, disputes, evidence — required)');
+    emit('   │  │     │     └─ term=<x>._.choice.example=<abc>.md  (ref: one per notable example — optional)');
+    emit('   │  │     └─ or cite it — point to the extant declaration you reused');
+    emit('   │  └─ 4. articulate progress.md — REQUIRED, the last step every round:');
+    emit('   │        ├─ what you conformed, disputed, and paved this round — and why');
+    emit('   │        ├─ a term the round SETTLED (declared dobj/dop, judged synonym) → capture it NOW');
+    emit('   │        ├─ defer ONLY a term you truly cannot finish (needs discovery, dispute still open)');
+    emit(`   │        └─ sentinel = ${input.progressPath}`);
+    emit('   │');
+    // the canon — the booted briefs + rules that DEFINE a domain-term lesson + its rules,
+    // so the reader recalls exactly what a term is + why it is kept
+    emit('   ├─ the canon — what a term is + why it is kept');
+    emit('   │  ├─ why  · im_an.obsessive_learner.for.domain.terms.md (the trait)');
+    emit('   │  ├─ rule · rule.require.domain-term-itemization (itemize each declared term)');
+    emit('   │  ├─ rule · rule.forbid.domain-term-synonyms (canonical term, or dispute)');
+    emit('   │  ├─ how  · template.domain-term.md + howto.domain-term-disputes.[guide].md');
+    emit(`   │  └─ glos · ${input.glossaryReadmePath}`);
+};
+/**
+ * .what = emit the onStop staleness nudge to stderr
+ * .why = stderr (not stdout) per rule.forbid.stdout-on-exit-errors; cli hooks
+ *        surface stderr on non-zero exit
+ *
+ * structure: ask → why → [shared how + canon] → the-time-is-now → close, so the ask is
+ * never abstract — the reader learns WHAT to do, WHY it matters, HOW to do it, WHICH
+ * booted briefs/rules define the concepts, and that the moment to act is now
+ */
+const emitStaleNudge = (input) => {
+    const emit = (line) => console.error(line);
+    emitHeader(emit, {
+        slogan: 'time again, to tend the terms',
+        command: 'learn.domain.terms --when hook.onStop',
+    });
+    emit('   │');
+    emit('   ├─ the ask — now, before you rest');
+    emit('   │  └─ review the terms this round touched, then redistill: conform-or-dispute');
+    emit('   │     the extant ones, and pave the path for any new ones. the steps are below');
+    emit('   │');
+    emit('   ├─ the why');
+    emit('   │  └─ the repo vocabulary compiles hour by hour; a term touched but not tended');
+    emit('   │     is a lesson lost — the next traveler re-derives it, or drifts to a synonym.');
+    emit('   │     an hour has passed, so the moment to tend it is now');
+    emit('   │');
+    emitDistillMoves(emit, input);
+    emit('   │');
+    emit('   ├─ the time to capture is now');
+    emit('   │  └─ your distillation went stale (> 1 hour) — tend it before you rest');
+    emit('   │');
+    emit('   └─ 🪷 distill, then rest — the glossary grows, the floor rises for all who follow');
+};
+/**
+ * .what = emit the scaffold-status line(s) of the clone guide
+ * .why = split out so the guide stays flat — a guard clause + early return keeps
+ *        the two cases (no-op run vs written) linear, no else branch
+ *        (rule.forbid.else-branches). a no-op pass is silent: the scaffold already
+ *        converged, so there is no news to report — silence keeps the guide on the
+ *        one thing that matters, the distillation (rule.require.status-feedback:
+ *        report what CHANGED; an unchanged scaffold is not a change)
+ */
+const emitScaffoldStatus = (input) => {
+    // a no-op run wrote no path this pass (every piece already converged) — stay silent
+    if (input.created.length === 0)
+        return;
+    // otherwise, name each artifact written this pass (findsert create or upsert reconcile)
+    console.log('   ├─ scaffold written');
+    input.created.forEach((path, index) => {
+        const isLast = index === input.created.length - 1;
+        console.log(`   │  ${isLast ? '└─' : '├─'} ${path}`);
+    });
+};
+/**
+ * .what = emit the clone-face reflect-and-distill guide to stdout
+ * .why = the sweep does no work on its own — the learner decides what the round
+ *        was worth. this guide names the glossary + scaffold status, then renders
+ *        the SAME shared how + canon body the onStop nudge does (emitDistillMoves),
+ *        so the clone face and the hook face can never teach a divergent guide
+ */
+const emitReflectionGuide = (input) => {
+    const emit = (line) => console.log(line);
+    emitHeader(emit, { slogan: 'tend the terms', command: 'learn.domain.terms' });
+    emit(`   ├─ glossary = ${input.glossaryDir}`);
+    emitScaffoldStatus({ created: input.created });
+    emit('   │');
+    emitDistillMoves(emit, {
+        progressPath: input.progressPath,
+        glossaryReadmePath: input.glossaryReadmePath,
+    });
+    emit('   │');
+    emit('   └─ 🪷 distill, then rest — the glossary grows, the floor rises for all who follow');
+};
+/**
+ * .what = emit the --help usage to stdout (both faces, args, exit codes)
+ * .why = every user-faced op must explain itself on demand; help is not an error,
+ *        so it goes to stdout + exits 0 (rule.require.help-on-demand)
+ */
+const emitHelp = () => {
+    const emit = (line) => console.log(line);
+    emitHeader(emit, { slogan: 'tend the terms', command: 'learn.domain.terms' });
+    emit('');
+    emit('  usage:');
+    console.log('    learn.domain.terms                  # clone face: write the scaffold,');
+    console.log('                                        # then guide the reflect-and-distill');
+    console.log('    learn.domain.terms --when hook.onStop');
+    console.log('                                        # hook face: staleness check');
+    console.log('    learn.domain.terms --help | -h      # this help');
+    console.log('');
+    console.log('  faces:');
+    console.log('    ├─ clone (no --when) → writes the scaffold, prints the guide; exit 0');
+    console.log('    └─ hook  (--when hook.onStop) → read-only staleness check');
+    console.log('       ├─ fresh distillation (< 1 hour) → exit 0 (session rests)');
+    console.log('       └─ stale (> 1 hour) → exit 2 (holds the stop, never a write)');
+    console.log('');
+    console.log('  --when values: hook.onStop (only)');
+};
+/**
+ * .what = cli entrypoint for the learn.domain.terms skill (both faces)
+ * .why = the onStop hook nudges when the distillation is stale; the clone runs it
+ *        to reflect + distill
+ *
+ * exits 0 when fresh (hook), after the guide (clone), or after --help
+ * exits 2 when stale (hook) to hold the stop open (never a write)
+ */
+const learnDomainTerms = async () => {
+    // --help: print usage, exit 0, never mutate. a help request must not run the
+    // clone face (which writes the scaffold) — safe-by-default (rule.require.help-on-demand)
+    if (isHelpRequested(process.argv)) {
+        emitHelp();
+        return;
+    }
+    // a bad --when is a caller-constraint, not a malfunction — exit 2, not 1
+    // (rule.require.exit-code-semantics). allowlist BadRequestError only; any other
+    // throw propagates to the wrapper's exit-1 backstop (no failhide)
+    const when = (() => {
+        try {
+            assertKnownFlags(process.argv);
+            return parseWhen(process.argv);
+        }
+        catch (error) {
+            if (!(error instanceof helpful_errors_1.BadRequestError))
+                throw error;
+            console.error(error.message);
+            return process.exit(2);
+        }
+    })();
+    const paths = (0, getDomainTermsPaths_1.getDomainTermsPaths)();
+    // hook face: read-only staleness check
+    if (when === 'hook.onStop') {
+        // freshness turns on BOTH a recent mtime AND a real articulation in the content,
+        // so a bare `touch` cannot silence the nudge (guards the one hard requirement)
+        const progress = await (0, getSweepProgress_1.getSweepProgress)({ path: paths.progressPath });
+        const articulated = (0, isProgressArticulated_1.isProgressArticulated)({ content: progress.content });
+        const stale = (0, isSweepStale_1.isSweepStale)({
+            mtime: progress.mtime,
+            articulated,
+            now: new Date(),
+        });
+        // fresh, articulated distillation → let the session rest
+        if (!stale)
+            return;
+        // stale → hold the stop open with a gentle nudge (never blocks a write)
+        emitStaleNudge({
+            progressPath: paths.progressPath,
+            glossaryReadmePath: paths.readmePath,
+        });
+        process.exit(2);
+    }
+    // clone face: findsert the scaffold, then guide the reflection
+    const scaffold = await (0, genDomainTermsScaffold_1.genDomainTermsScaffold)();
+    emitReflectionGuide({
+        glossaryDir: scaffold.glossaryDir,
+        glossaryReadmePath: paths.readmePath,
+        created: scaffold.created,
+        progressPath: paths.progressPath,
+    });
+};
+exports.learnDomainTerms = learnDomainTerms;
+//# sourceMappingURL=learn.js.map

package/dist/contract/cli/learn.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"learn.js","sourceRoot":"","sources":["../../../src/contract/cli/learn.ts"],"names":[],"mappings":"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"}

package/dist/contract/cli/route.js

@@ -29,6 +29,7 @@ const fs = __importStar(require("fs/promises"));
 const helpful_errors_1 = require("helpful-errors");
 const path = __importStar(require("path"));
 const RouteStoneGuard_1 = require("../../domain.objects/Driver/RouteStoneGuard");
+const getInvocationArgs_1 = require("../../domain.operations/cli/getInvocationArgs");
 const delRouteBind_1 = require("../../domain.operations/route/bind/delRouteBind");
 const getRouteBind_1 = require("../../domain.operations/route/bind/getRouteBind");
 const getRouteBindByBranch_1 = require("../../domain.operations/route/bind/getRouteBindByBranch");
@@ -61,26 +62,6 @@ const findStoneByName_1 = require("../../domain.operations/route/stones/findSton
 const getAllStones_1 = require("../../domain.operations/route/stones/getAllStones");
 const isPromisedActionSlugAbsent_1 = require("../../domain.operations/route/stones/isPromisedActionSlugAbsent");
 const enumFilesFromGlob_1 = require("../../utils/enumFilesFromGlob");
-/**
- * .what = detects if node was invoked via `node -e "code"` (eval mode)
- * .why = in eval mode, argv has no entrypoint path and args come after --
- *
- * argv patterns:
- *   normal: ['node', '/path/to/entry.js', '--arg', 'val']
- *   eval:   ['node', 'arg1', 'arg2'] (node strips -e and code from argv!)
- *
- * detection: if argv[1] doesn't look like a file path, assume eval mode
- */
-const isNodeEvalMode = (argv) => {
-    const secondArg = argv[1];
-    if (!secondArg)
-        return false;
-    // entrypoint path (ends with js/ts extension) = normal mode
-    if (/\.(js|ts|mjs|cjs)$/.test(secondArg))
-        return false;
-    // otherwise assume eval mode (node strips -e and code from argv)
-    return true;
-};
 /**
  * .what = copies bytes read from a buffer into a new buffer
  * .why = encapsulates buffer slice for readability in stdin read loops
@@ -167,13 +148,11 @@ const isValidStonePassageAction = (input) => {
     return !!input.action && VALID_STONE_PASSAGE_ACTIONS.has(input.action);
 };
 /**
- * .what = extracts clean args from argv, skipping node/entrypoint args and separators
- * .why = encapsulates argv preprocessing for readability
+ * .what = extracts clean args from argv, skips node/entrypoint args and the `--` separator
+ * .why = the canonical eval-mode slice now lives in one place (domain.operations/cli/
+ *        getInvocationArgs), so route + learn share it instead of divergent copies
  */
-const getCleanArgsFromArgv = (input) => {
-    const skipCount = isNodeEvalMode(input.argv) ? 1 : 2;
-    return input.argv.slice(skipCount).filter((arg) => arg !== '--');
-};
+const getCleanArgsFromArgv = (input) => (0, getInvocationArgs_1.getInvocationArgs)(input.argv);
 /**
  * .what = parses cli args into options object
  * .why = simple arg parser without external dependencies
@@ -447,6 +426,16 @@ options:
                      onStop: show guidance, exit 2 (block premature stop)
   --help             show this help message
 
+output:
+  when the stone can self-drive, route.drive echoes the current stone + guidance.
+  when it has halted and needs a human, it switches to a halt message instead:
+    ✋ halted, stone marked blocked         a driver wall (--as blocked) — clear it
+    👋 halted, peer reviewer budget exhausted   approve as-is, or extend the budget
+    💥 halted, guard malfunction            a reviewer or judge broke — a human must fix
+  onStop honors the same halt: exit 2 keeps the route in motion, exit 0 allows a
+  clean stop, exit 1 escalates a malfunction (per rule.require.exit-code-semantics).
+  onBoot always exits 0 (it never blocks session start).
+
 examples:
   route.drive                        # echo current stone
   route.drive --when hook.onBoot     # show stone, exit 0 (for onBoot hooks)
@@ -467,10 +456,20 @@ options:
   --help             show this help message
 
 output:
-  bound, stone unpassed     🗿 <stone>
-  bound, all stones passed  🗿 route complete 🎉
+  bound, stone + phase      🗿 <stone>, <phase> <emoji>
+  bound, all stones passed  🗿 route complete 🌴🤙
   unbound / no stones       (empty line)
 
+  the phase suffix names where inside the stone the driver is, tipped with an
+  attention-color emoji at the end of the line (read the color, then the words):
+    yield 🌾                 the stone yields its artifact — calm, no attention
+    review.self, r7/r10 🔍   self-reviews, r{done}/r{total} — machine's turn
+    review.peer, l3@i002 🔍  peer review, l{level}@i{rounds} — machine's turn
+    judge, approved? 👋      a human must approve — attention needed
+    ..., exhausted 👋        peer budget spent, a human must approve or extend
+    ..., blocked ✋          blocked, act now — attention needed
+    ..., malfunction 💥      a reviewer or judge broke, a human must fix
+
 errors:
   a genuine fault is logged to stderr and exits non-zero; the harness then renders
   a blank line (the fault is surfaced on stderr, never silently hidden)
@@ -1469,7 +1468,9 @@ const routeMutateGrant = async () => {
         grantOption: options.grant,
     });
     if (!action || !['allow', 'block', 'get'].includes(action)) {
-        console.log(`
+        // usage on an invalid/absent action is an error path → stderr, not stdout
+        // (rule.forbid.stdout-on-exit-errors: stdout may be hidden on non-zero exit)
+        console.error(`
 route.mutate grant - manage route protection privilege
 
 usage:
@@ -1480,7 +1481,9 @@ usage:
 options:
   --route <path>    route path (default: auto-detect from branch)
 `);
-        process.exit(1);
+        // exit 2 = constraint: the caller gave a bad action and must fix the invocation
+        // (rule.require.exit-code-semantics: 0 ok, 1 malfunction, 2 constraint)
+        process.exit(2);
     }
     try {
         // get route from option or auto-detect
@@ -1679,7 +1682,9 @@ const routeGuardBudget = async () => {
     // validate --add option
     const addStr = options.add;
     if (!addStr) {
-        console.log(`
+        // usage on an absent required flag is an error path → stderr, not stdout
+        // (rule.forbid.stdout-on-exit-errors: stdout may be hidden on non-zero exit)
+        console.error(`
 route.guard.budget - extend peer reviewer budget
 
 usage:
@@ -1694,12 +1699,16 @@ options:
   --peer    peer reviewer slug to extend (default: all peers)
   --route   path to route directory (default: auto-detect from branch)
 `);
-        process.exit(1);
+        // exit 2 = constraint: the caller omitted a required flag and must fix the invocation
+        // (rule.require.exit-code-semantics: 0 ok, 1 malfunction, 2 constraint)
+        process.exit(2);
     }
     const addAmount = asPositiveIntegerOrNull({ value: addStr });
     if (addAmount === null) {
         console.error('error: --add must be a positive integer');
-        process.exit(1);
+        // exit 2 = constraint: the caller passed a malformed value and must fix the
+        // invocation (rule.require.exit-code-semantics: 0 ok, 1 malfunction, 2 constraint)
+        process.exit(2);
     }
     const peerSlug = options.peer;
     const stoneName = options.stone;