Imported from thomasholknielsen/claude-tweaks (.claude/skills/gh-api-module-pattern/SKILL.md). Install upstream with npx skills add thomasholknielsen/claude-tweaks --skill gh-api-module-pattern. Copyright stays with the author.

gh-api module pattern

How this repo writes Node modules that shell to gh. Two shipped instances define the pattern: plugin/bin/lib/issues/capabilities-probe.js (reads) and plugin/bin/lib/issues/link.js (writes). Two shipped bugs in one session (#626, #610) came from getting the flag rules wrong — read that table before writing any gh api call.

The injectable runner

• The module takes runner(args), invoked as if gh ${args.join(' ')}, returning stdout; a throw is a failed call. Export defaultRunner = execFileSync('gh', args, { encoding: 'utf8' }) — always an argv array, never a shell string (no injection surface, no quoting bugs).
• Tests never touch real gh: fake runners branch on the args shape (isGraphQL, isPost-style lazy helpers) and throw new Error('unexpected ' + args.join(' ')) on anything unhandled — a wrong endpoint fails loudly instead of passing silently. Record values inside the runner, assert after it returns (an AssertionError thrown inside a runner can be swallowed by the module's own try/catch).
• A module may carry two runner seams, and they have opposite failure contracts. plugin/bin/lib/claim-targets/claim-targets.js takes both: deps.ghApi — the plugin/bin/lib/issues/claim-store.js contract, which never throws and returns {stdout, failure, status} so a 404/409/422 arrives as data — for contents-API reads and writes, and deps.gh — the throwing runner above — for everything else (repo view, label list/create, issue edit, issue comment). Decide which seam a call belongs to before writing it: a never-throwing runner wrapped in try/catch reads as success on every rejection, and a throwing one used bare escapes uncaught.
• An argv array stops shell injection, not flag injection. A caller-supplied value that begins with - is still read as an option by the command itself, so any such value needs an end-of-options separator ahead of it. For git the separator is --end-of-options, not --: -- switches rev-parse --verify and merge-base into pathspec mode and silently changes what they resolve — verified empirically before the fix landed, after -- was tried first (#888 review lens 3b). plugin/bin/lib/blast-radius-cli.js is the shipped instance, on both of its revision-resolving calls. Pin the separator with a fake-runner test that asserts the exact argv array for a value like -evil (tests/bin-lib/blast-radius-cli.test.js), not just that the call succeeded.
• The same seam serves non-gh commands. plugin/bin/lib/blast-radius-cli.js takes deps.git and deps.readFile on exactly the contract above and cites this skill for it. Nothing in the injectable-runner rules is gh-specific — the argv-array rule, the loud-throw fake, and record-inside/assert-after all carry over unchanged; only the gh api flag table below is gh-only.
• Bound every remote-contacting call on the seam; leave local-only calls unbounded. execFileSync has no default timeout, so a black-holed remote hangs the caller indefinitely. Every gh call and every network git call (fetch, remote prune, ls-remote) passes an explicit timeout — GH_TIMEOUT_MS = 5000 (plugin/bin/lib/issues/claim-store.js, plugin/bin/claim-targets.js), FETCH_TIMEOUT_MS = 5000 (plugin/bin/lib/reconcile/classify.js, pr-state.js, red-tip.js), or plugin/bin/lib/hooks/git-exec.js's DEFAULT_TIMEOUT_MS = 10000 for anything routed through runGit. A batched call earns a wider bound than the 5s single-call convention — plugin/bin/fetch-sub-issues.js's runner passes timeout: 30000 for a 50-alias GraphQL batch and states the reason in a comment beside it; widen deliberately with a stated reason rather than carrying 5000 over by copy. Local-only reads (rev-parse, git config, branch -r --merged) take none. The defaultRunner shape above is the argv-array rule, not a complete options object — a gh runner copied from it still owes a timeout. On a seam that is otherwise all-local, widen it with a per-call options argument rather than bounding every call: plugin/bin/residue.js's runner(argv, opts) takes exactly such a per-call execFileSync options object (#663), and the seam's existing catch-all already maps a timeout kill onto its normal failure value. That seam has no bounded call site today — the git remote prune it was added for was since removed, and plugin/bin/lib/residue/probes/branches.js states why in a comment beside the gap ("No git remote prune here: this probe's findings are read-only") — so keep the options argument and pass a timeout the moment a probe contacts a remote, rather than reading the absent call as evidence the seam is unused. Omitting the bound is defensible only with a stated reason — plugin/bin/lib/reconcile/shared-fetch.js skips timeoutMs so git-exec.js's CT_HOOKS_GIT_TIMEOUT_MS escape hatch still applies, and says so in a comment.
• The same probe copied across N separate modules is the cross-module instance of the sibling-drift bullet below — consolidate into one shared, injectable helper rather than leaving each copy to drift on its own options object. plugin/bin/lib/repo-resolve.js's ghAvailable(deps = {}) (#2017) replaced seven near-verbatim execFileSync('gh', ['--version'], …) probes scattered across file-feedback.js, link-records.js, materialize.js, release-claim.js, compose-context/resolve-conditions.js, wrap-up/engine-verify.js, and repo-resolve.js itself — each had quietly drifted on its options object (stdio: 'ignore' vs stdio: 'pipe', some with no timeout at all) before the consolidation. A grep-backed test (tests/bin-lib/repo-resolve.test.js) now pins '--version' to the single production site, so the count can't silently regress back to N copies. A caller whose own seam shape differs (engine-verify.js's deps.gh(args, cwd) takes a cwd the shared helper has no slot for) wraps the shared call in a one-line adapter rather than reintroducing a local copy.
• Sibling default runners in one module drift on their options object — build both from one factory, once you've decided they should share it. A module shelling to both git and gh on this seam ends up with a defaultGit and a defaultGh differing only in the command name, so a rule applied to one silently leaves the other behind. plugin/bin/lib/wrap-up/engine-verify.js shipped the pair unbounded, then gained timeout: 5000 on defaultGh alone when the bullet above was applied to its remote-contacting call (7569d4ce8, refs #900), and needed a separate whole-branch review later the same day to notice defaultGit had been left behind (#1230, 76fd10487) — one options object, edited twice, hours apart, because nothing but eyeballing the two copies could show they disagreed. It now builds both from makeDefaultRunner(cmd) — one closure over one options object — so the two can no longer diverge by copy (#1222). Weigh what the factory costs before reaching for it: it forces symmetry, and the bullet above says symmetry is not automatically correct (that module's git calls are all local and owe no bound at all — a uniform 5s is merely harmless there, not required). Factor when the siblings genuinely should share their options; otherwise keep them separate and state beside each why it differs. Same remedy as the sync/async twin drift under Async fan-out below, on a different axis: factor at the point of duplication rather than diffing copies later.
• A seam whose calls are probes runs quiet, and carries its own error class so the CLI can pick the exit code. plugin/bin/lib/verify/changed-files.js (#1922) shells to git on exactly the seam above, and every real call passes stdio: ['ignore', 'pipe', 'pipe'] — the posture blast-radius-cli.js's own default git() already uses — because base resolution asks questions it expects to fail: merge-base --is-ancestor on a stale stamp anchor, rev-parse --verify on a ref that may not exist. Without the quiet posture a benign miss leaks git's own fatal: line to the stderr of a process that is about to exit 0, which reads to a caller as a real error. The message is not thrown away: the module raises a named ChangedFilesError carrying it, and the CLI — not the module — decides what an unresolvable base means per mode, since the same module-level failure is a different class of problem depending on who asked. verify.js --scope maps it to the usage-class exit 2 (an unresolvable base is a malformed invocation, not a check failure), verify.js --changed-files to its own documented exit 1, and both re-throw anything that is not a ChangedFilesError rather than flattening an unrelated bug into a tidy exit code. A bare throw new Error on the seam would force the CLI to string-match its own module to tell the two apart.

The three gh api value mechanisms (the bug source)

URL path placeholders (repos/{owner}/{repo}/…) are a fourth thing: always substituted, no flag involved. Never collapse these into "always -F for owner/repo" — that generalization is exactly what shipped #610's bug, with a plan-authored test pinning the wrong flag.

A caller-overridable REST path has no bound-variable escape hatch. The {owner}/{repo} path placeholders above always resolve from gh's own ambient repo context (the cwd's git remote) — there is no -f owner=…/-F owner=… equivalent that rebinds a REST path segment the way -f owner=… rebinds a GraphQL variable (row 2 above). A CLI that must honor its own --repo owner/name override for a REST call (rather than gh's ambient context) therefore has to build the path string itself — plugin/bin/fetch-sub-issues.js's --resolve-retries retry loop does exactly this (`repos/${owner}/${repo}/issues/${n}/sub_issues`, #1153 review finding). That loses the placeholder mechanism's implicit safety: the interpolated owner/repo values need their own validation before they reach the path, since a lax upstream parser (this repo's shared parseRepo accepts any non-/ segment, including ./..) can otherwise redirect the call. fetch-sub-issues.js added a narrow owner !== '.' && owner !== '..' guard at its own call site rather than tightening the shared parseRepo (9 callers, most never resolve a caller-supplied --repo at all) — a reminder to validate at the interpolation site when you can't fix the shared resolver's blast radius in the same change.

gh api graphql is where two of these rows collide: a String! variable needs -f, and -f never expands {owner}/{repo}, so the placeholder mechanism is simply unavailable to a GraphQL variable. Resolve the slug locally instead — plugin/bin/lib/hooks/git-exec.js's repoSlugOf parses it out of remote get-url origin and is shared by reconcile/pr-state.js and reconcile/release-merged.js (#1082) — and pass it as -f owner=…/-f name=…. claim-targets.js's gh repo view --json nameWithOwner form is for a seam holding a gh runner but no repo root; hooks/teardown-run.js's inline copy of the same regex predates the shared helper and is not license for a fourth.

Batching and failure posture

• Resolve everything up front in one call where the API allows it (aliased GraphQL: one i{N}: issue(number:{N}){ databaseId } per distinct number), and chunk the alias list rather than letting one query grow without bound — plugin/bin/fetch-sub-issues.js slices its input at 50 numbers per call and merges each chunk's result into one envelope.
• The alias-query builder is a pure function in plugin/bin/lib/issues/record.js, separate from whatever runs it. buildNativeDependencyQuery, buildNativeSubIssuesQuery, and buildNativeParentQuery each take a numbers array, return the query string, and return null for an empty or non-array input — an empty repository{} selection set is invalid GraphQL, so the caller must branch on null rather than send it. record.js requires nothing but ./facet-shape and shells out nowhere, which is what lets tests/bin-lib/issues/record.test.js pin each builder with plain regex assertions and no fake runner at all; the transport, the chunking, and the partial-result posture below all belong to the caller (plugin/bin/lib/issues/native-dependencies.js, plugin/bin/resolve-blockers.js, or a skill's own node -e line), never to the builder. Add a fourth builder the same way — and factor the shared query($owner:String!,$repo:String!){ repository(owner:$owner,name:$repo){ … } } envelope out when you do: the three above repeat it verbatim today (#1194 hindsight).
• Two sanctioned partial-result postures; choose by whether the caller can recover per item. Throw on a partial result when partial data is unusable — plugin/bin/lib/issues/native-dependencies.js's fetchNativeDependencies throws naming every missing i{N} alias (#723), because a caller that silently drops a dependency edge ships a wrong graph. Return a retry envelope when the caller has a per-item fallback — the same file's fetchNativeSubIssues returns {byParent, retry} (#1097), routing a single missing or null alias onto retry for the caller's per-parent REST loop instead of failing the whole batch; such a parent never lands in byParent as [], because an empty array already means "fetched, has no sub-issues". A whole-response failure (data.repository null or missing) throws under both postures — an envelope degrades per item, never per batch.
• Routing an existing caller onto a shared module inherits that module's posture — re-check the caller's blast radius, not just its output shape. The two postures above are chosen when a module is written; the hazard lands at the caller migration, where a call site that degraded per item silently starts degrading per batch. plugin/skills/dispatch/queue-pull-script.md's work-links: native branch (#1309) moved from a hand-rolled gh api graphql response fed to record.js's partitionByOpenNativeBlockers — which reads a missing i{N} alias as an empty blocker list and so fails open for that one candidate — onto plugin/bin/resolve-blockers.js, whose fetchNativeDependencies throws on any single missing alias (the throw on a partial result posture above), exits 3, and disables native blocker filtering for every candidate in the run. The per-record output shape was identical and the suite stayed green; only the failure fan-out changed, so no shape-level assertion could catch it. When such a migration is the point of the change, state the old and new degrade granularity side by side in the record, and give the caller an exit-code branch that separates a partial result from a total outage instead of one catch-all else.
• A bulk alias query is chunked, all-or-nothing, and never authorizes a destructive act by itself. plugin/bin/lib/reconcile/pr-state.js's resolvePrStatesBulk (#1082) resolves N branches' governing PRs in ceil(N/50) calls of b{i}: ref(qualifiedName:"refs/heads/…"){ associatedPullRequests } aliases — the chunk size is probe-measured, not guessed: 50 aliases cost 1 GraphQL rate-limit point. It returns a complete Map or a failure sentinel, never a partial map: a transport throw, an HTTP-200 body carrying errors[], and an alias key missing from data.repository each fail the whole call, because a dropped chunk's branches are otherwise indistinguishable from branches with no PR. Bulk evidence is also weaker than a per-branch read — ref() is null for a branch deleted after its PR merged — so a caller screens with it to skip cheaply and re-confirms via resolvePrState before anything destructive (prune-remote.js, archive-branches.js).
• Per-write calls are each independently try/caught into {ok: [...], failed: [{…, error}]} — one failed edge never aborts the batch. An "already exists" 422 is a re-run, not a failure: it lands in ok with already: true (live-confirmed wording: GitHub answers Validation failed: Target issue has already been taken).
• Error text: join err.message/err.stderr/err.stdout, with a String(err) fallback so a non-Error throw never yields an empty failed[].error.
• Enumerate an operation's full documented error-status set in one sitting. Adding one status per bug report ships the same misclassification serially: plugin/bin/lib/issues/claim-store.js's Contents-API PUT got its 422 create-race branch in 75c8b3b6, then the symmetric 409 sha-mismatch branch in 4ee0fbcc — one defect class, found twice, the second time by a review lens. Read the endpoint's documented statuses first (Contents PUT: 404 read-miss, 409 sha-mismatch, 422 create-race) and branch on all of them in the same commit.
• Rate-limit recognition and burst pacing. Classify a gh api rate-limit failure per plugin/skills/_shared/github-rate-limit.md's taxonomy before deciding whether to retry — a plain 403 under that file's rules is not transient and must not be retried. When a module issues a scripted sequence of mutative calls, follow that file's burst-shape rules.
• A transient-failure retry on a non-idempotent mutating call needs a dedup-safe recheck, not the same blind retry as an idempotent read. A 5xx/timeout/reset signature is ambiguous about where the failure happened: the request may have reached GitHub and succeeded, with only the response lost. Retrying gh issue list/issue view on that signature is free — a second read changes nothing. Retrying gh issue create (or any other non-idempotent write) the same way risks filing a duplicate. plugin/bin/lib/feedback/file-feedback.js's createWithDedupSafeRetry is the shipped instance (#834/#835 review): before each retry of the create call, it re-runs the module's own dedup search for a marker unique to this call — a hit means the "failed" attempt actually succeeded, so that result is reused instead of creating a second one. A single generic retry wrapper applied uniformly across a module's read and write calls is exactly the shape this hazard hides in.
• A machine-filed issue carries only the labels its filing context can actually justify — and the module's header says so. The two shipped gh issue create sites split on whether an LLM is in the loop. plugin/bin/lib/feedback/file-feedback.js's fileDraft takes labels from its caller, because the /feedback skill orchestrating it can judge them. plugin/bin/lib/reconcile/escalate-residue.js files --label bug and nothing else, from the no-LLM contexts named in its header (session-start.js in-process, bin/hooks.js reconcile) — deliberately, not as a gap (#1216): risk:*/size:* are content judgments no mechanical caller can score, a fixed always-low default is wrong on its own, and ready asserts a spec-shaped body that a terse auto-report is not. Leave the enrichment to the downstream path that demonstrably picks the issue up — a plain open issue is already a backlog-stage record that /specify shapes and /backlog grants route onward — and record the posture in the module's header comment, since the alternative is a later reader re-opening the thin label set as a missing-facets bug (which is what #1216 was).
• Widen an existing call's -q projection before adding a second API call. When a later step needs one more field off data you already fetched, extend the jq filter rather than issuing a fresh request — plugin/bin/lib/issues/claim-store.js's listClaimEntries widened -q .[].name to -q '[.[] | {name, sha}]' to get each claim blob's sha from the same single Contents-API directory listing (#820 D6), instead of a second lookup per entry.
• Cross-check a documented failure-status word against append.js's STATUSES enum before wiring a batch CLI's catch to log nothing on failure. plugin/bin/lib/log-decision/append.js's STATUSES (AUTO/STAGED/KEPT-PROMPT/SCANNED/REFUSED/SKIP) has no FAILED member. A consuming skill's prose can still document a FAILED {time} — … decisions.md template its own closing-summary tally counts on — apply-refine-labels.js (#844) shipped exactly this gap: its catch block only appends to the stdout JSON's failed[] array, never to decisions.md, because FAILED isn't a loggable status. Check the enum, not just the prose, before assuming a documented status word is writable via appendEntry.
• On a path another process may prune, read and catch — never existsSync-then-read. These modules read .claude-tweaks/pipelines/ run-dirs that this project's own reconcile/archive passes prune concurrently, so an existsSync guard ahead of readFileSync/readdirSync is a window, not a check: the path can vanish between the two calls and the read throws exactly where the guard promised it could not. Read straight off and wrap in try/catch — an absent path and a mid-read prune then arrive as the same degraded value, with one code path instead of two. plugin/bin/lib/wrap-up/engine-verify.js shipped the guard-then-read pair three times (resolvedIssueNumbers, memory-updates's index read, and its per-check map); two independent review agents reproduced it and 997e571c fixed all three. A bare existsSync used as a verdict, with no read behind it (resolveArchivedRunDir, the run-dir-archived check), is not this hazard — the pair is.
• One unit's throw never aborts the report, and the verdict a throw maps to is a decision. The per-write {ok, failed} rule above generalizes past runner calls: any module mapping a registry of independent units to results wraps each unit in its own try/catch, because one uncaught throw prints no output at all and exits through Node's default path, silently colliding with the CLI's documented exit-code contract. engine-verify.js's runVerify maps its CHECKS array that way and maps a throw to fail, not unknown: for a gate whose whole purpose is to block on doubt, a unit that could not determine its own state is evidence to block rather than to shrug. Pick the direction the module errs and say so beside the catch — the two are not interchangeable.
• isIndeterminate is the wrong failure filter when a probe's negative answer lives in stdout. plugin/bin/lib/hooks/git-exec.js exports isIndeterminate (timeout/spawn/no-git) for failures where "the question went unanswered, rather than answered in the negative" — but that split only holds for a call whose negative answer is the non-zero exit (merge-base --is-ancestor, rev-parse --verify). For a probe that answers in stdout — git ls-files -- <dir> prints nothing for an untracked path and still exits 0 — a definitive FAILURE.GIT_ERROR (corrupt index, unreadable object store) is exactly as unanswered as a timeout, so filtering on isIndeterminate and letting git-error fall through to the falsy branch reads "the probe broke" as "the answer is no". plugin/bin/lib/reconcile/archive-merged.js's hasTrackedContent (#2227) shipped that in 751f22c92 — the whole-branch review explicitly waved the git-error case through as "an answer" — and a later review lens caught it against the module's own sibling guard, archiveRunDir's ls-files-failed refusal, which already fails closed on any failure; 67af77ee7 made every failure kind assume tracked. When a probe result selects a route rather than filling a report field, branch on failure as one condition, say which direction is safe in a comment beside it, and check the sibling probe in the same module before adopting a narrower filter than it uses.

Async fan-out

execFileSync blocks the event loop regardless of how the calling code is structured, so a concurrency pool built over sync runners buys nothing — the async runner below is what actually makes fan-out non-blocking. plugin/bin/lib/reconcile/gh-pool.js establishes the async sibling to the sync seam above:

• Export an async runner via promisify(execFile), returning the same {stdout, failure, status} shape the sync deps.ghApi-style seam already returns (release-merged.js's ghApiAsync, console-execute.js's execFileAsync) — same contract, non-blocking transport.
• Reuse a single injectable ghApi option for both sync and async call sites rather than adding a second override parameter: a sync test fake gets wrapped in an already-resolved promise (release-merged.js's releaseMerged opts) so callers and tests don't need to know which transport a given call uses.
• gh-pool.js's runWithConcurrency fans calls out order-preserving and concurrency-capped, with each item's own try/catch storing the Error at its index — the async form of "one failed edge never aborts the batch" above. Clamp the concurrency cap to >= 1: an unclamped Math.min(cap, len) with cap <= 0/NaN spawns zero workers and silently resolves an all-undefined array instead of throwing or doing the work.
• A new async runner needs a non-blocking proof, and it must be structural, not wall-clock. promisify(execFile) and execFileSync under an async wrapper are indistinguishable by signature, so the property this whole section depends on has to be tested explicitly — but on this shared machine any assertion over elapsed time flakes under sibling-session load wherever the margin sits: tests/bin-lib/reconcile/pr-state.test.js's event-loop test burned a fixed < 400ms bound (#1127), then a concurrent-vs-sequential ratio (#1404), before landing on an existence check — each spawned gh wrapper drops a marker file for its own lifetime, samples how many coexist, and the test asserts the observed max is >= 2. That holds at any machine speed and is impossible for a blocking implementation, whose single-threaded spawns can never overlap. console-execute.js and release-merged.js carry the same seam with no such test; add one on this shape when you touch them.
• promisify(execFile) (or execFileSync) must be called at the site the runner fires, not hoisted to module scope. A module whose sync half already resolves cp.execFileSync(...) at call time (rather than a require-time destructure) exists specifically so t.mock.method(cp, 'execFileSync', ...)/a plain cp.execFileSync = stub reassignment reaches it — but const execFileAsync = promisify(cp.execFile) at the top of the file snapshots the original cp.execFile reference through promisify, silently defeating that same mockability for the async sibling alone (plugin/bin/lib/hooks/git-exec.js's runGitAsync, #872: shipped once, broke a timeout test's ability to mock a hung child, fixed by calling promisify(cp.execFile) inside the function body instead). To stub a hung/slow async call deterministically without this, give the stub a [require('util').promisify.custom] property — the same hook Node's own child_process.execFile carries — since a plain callback-shaped stub only returns a bare value under generic promisify, not the {stdout, stderr} shape execFile's real custom implementation provides.
• A real async timeout race against a fast child is not equivalent to execFileSync's timeout at the same timeoutMs. execFileSync's timeout enforcement reliably beats even a trivial, sub-millisecond child on ordinary hardware; execFile's async timeout is a genuine setTimeout-vs-real-child-completion race that a sufficiently fast/cache-warm host (a fresh CI runner in particular) can occasionally win on the child's side even at timeoutMs: 1 — the #872 incident above (a test green 20/20 on one machine, red on GitHub Actions). Test an async timeout's classification branch with a mocked hung child (per the bullet above), never by racing a real short-lived process against a millisecond-scale deadline.
• Once a sync/async twin pair's two catch blocks are independently hand-written, they drift — extract a shared runClassified/runClassifiedAsync try/execute/catch scaffold instead. git-exec.js's runGit/runGitAsync and preflight.js's ghHealthCheck/ghHealthCheckAsync each retyped the same try { … } catch (err) { return shape(err); } body once per twin — a whole-branch pre-release review (pre-v6.110.0) caught runGit's stderr field added without the mirroring update landing on runGitAsync, despite a header comment asserting "identical return shape" (#1652). The fix is two tiers: plugin/bin/lib/shared-primitives.js's runClassified(fn, mapError) / runClassifiedAsync(fn, mapError) are the shared try/execute/catch shell (sync executes fn() directly, async awaits it; both call mapError(err) on a throw and never otherwise) — and each pair additionally defines its own buildSuccess/buildFailure once, called from both twins, so a shape fix (a new field, a renamed key) lands in one function instead of two. Do this only where a pair's own classification/shaping logic is actually duplicated — a twin that's a pure delegator with no try/catch of its own (shared-fetch.js's sharedFetch/sharedFetchAsync, which just calls runGit/runGitAsync) has nothing to extract and inherits the fix transitively through the primitive it already calls.

The CLI wrapper contract

• Logic lives in an exported run(argv, deps); every side effect (runner, ghAvailable, remoteUrl, stdout, stderr) goes through deps so tests inject fakes. Every deps call that can throw (e.g. remoteUrl outside a git repo) is try/caught into the documented exit-code contract — an un-wrapped deps call is where #610's one post-review high landed.

• require.main === module guard sets process.exitCode = run(...) (never process.exit, which can truncate piped stdout). --help short-circuits before any availability probe. This one is pinned mechanically, not by grep — tests/bin-lib/exit-code-conformance.test.js (#1903) walks every plugin/bin/**/*.js, extracts the text each require.main === module guard governs, and fails on a direct process.exit(...) inside it. Three prior records (#1176, #1313, #1535) each closed one violation of this rule found by a manual sweep that missed another, which is why the sweep was replaced. A new guard needs no registration; a deliberate exception goes in that test's ALLOWLIST with its reason stated beside it (today: bin/hooks.js, whose stdout is a synchronous fs.writeSync(1, …) with nothing pending to flush, and bin/lib/statusline-wrapper-source.js, which deliberately hard-stops on a child process's own exit code).

• The guard rule above only sees a file's own entry-point guard — it does not follow the call graph into a library function that guard invokes. plugin/bin/lib/health-core/*.js are shared library files invoked from deep inside all four health-suite CLIs' (code-health.js, harness-health.js, journey-health.js, docs-health.js) own correctly-guarded main() — outside any guard #1903's scan can see, so a process.exit() there was invisible to it (#2053: churn-report.js, mark.js, retry-cli.js's update each did this after a pending stdout/stderr write). The fix mirrors the guard rule's own shape one level down rather than making the mechanical scan call-graph-aware (disproportionate for a bug class with exactly three known instances): each library function returns a numeric code (or undefined) instead of exiting, and each CLI's main() dispatch line captures that return value into process.exitCode, e.g. if (cmd === 'churn-report') { const code = cmdChurnReport(args); if (code) process.exitCode = code; return; } — the same process.exitCode = N; return; shape every other branch in the same main() already uses. tests/bin-lib/exit-code-conformance.test.js adds a second, narrower rule for this: a flat per-file sweep of plugin/bin/lib/health-core/*.js (no guard extraction, no call-graph walk) failing on any direct process.exit( anywhere in the file. Never widen this scope to all of plugin/bin/lib/** — bin/lib/statusline-wrapper-source.js's own process.exit() calls are a different case (a guard-less whole-script file, not a library function invoked from another file's guard) already covered by the guard-scoped test's own ALLOWLIST above.

• A multi-verb dispatcher needs one table-driven guard, not N per-verb ones. plugin/bin/hooks.js isn't a single-purpose CLI in the sense above — it's one main(argv) dispatching 14 documented subcommands (plus 6 harness-invoked EVENTS names). Before #1143, each subcommand branch treated a stray --help/-h as an ordinary argument, ran for real, and on the --run-omitted verbs could fall through to resolveRunArg's implicit "newest non-terminal run" guess — silently stamping a sibling session's run-state.json (observed 2026-08-20). The fix generalizes the single-CLI --help short-circuit above into one USAGE lookup table (verb → usage string) checked once, ahead of every branch in main(), before any lib call or resolveRunArg scan — not a per-verb early-return copy-pasted 14 times. Regression risk for this shape specifically: the guard's own coverage can silently drift from the dispatch table it guards (a verb added to main()'s cmd === '...' chain with no matching USAGE entry gets no guard at all) — tests/hooks-help-guard.test.js pins this with a structural test scanning main()'s source for every cmd === '...' branch and asserting each has a USAGE entry, not just the reverse (iterating USAGE's own keys, which proves nothing about branches missing from the table).

• Exit codes are a documented contract, and this repo ships three base vocabularies — pick the one the CLI's sibling and its consuming prose already use, then spell it out in the file's header comment and USAGE:

  • Combined-2 (plugin/bin/link-records.js): 0 success or partial-with-failed, 1 upstream resolution failure, 2 malformed invocation or missing dependency.
  • Split-1/2 (plugin/bin/resolve-blockers.js, plugin/bin/fetch-sub-issues.js): 0 success, 1 malformed invocation, 2 missing dependency or unresolvable owner/repo, 3 the remote call itself failed.
  • Sanctioned-writer (plugin/bin/log-decision.js, plugin/bin/stage-item.js, plugin/bin/set-config.js): 0 written (the written path echoed to stdout), 2 malformed invocation, 3 the run dir is missing or not anchored under the main checkout, or the target file is unwritable — no 1 at all. These are the run-directory writers a worktree-isolated session reaches for when Edit/Write refuses the run dir (decisions.md, staged/, config.yml respectively), and the skill prose that invokes them branches on 3 as "wrong run dir — re-resolve $RUN_ROOT". Copying Split-1/2 into a fourth writer would make its malformed case land on a code its siblings use for an anchoring failure.

  Never mix them inside one family: a caller that branches on a sibling's codes reads the wrong branch silently.

• Every malformed-input class must actually reach its malformed code — Number('') === 0 passes Number.isInteger, so validate positivity and pair-structure explicitly.

• Codes above the base vocabulary are per-CLI domain outcomes and are not portable. plugin/bin/claim-targets.js ships 3 (contested — holder JSON on stdout) and 4 (transient gh failure), branched on by plugin/skills/flow/claim-targets.md Step 2.8; plugin/bin/fetch-sub-issues.js ships 4 for "the capability probe says the GraphQL field is unavailable — take the documented fallback". Spell each one out in that CLI's own USAGE and in the prose that branches on it; never assume a number carries its meaning across CLIs.

• A read-only status verb is status-as-data: it exits 0 in every state, and the JSON on stdout is the answer. The vocabularies above key the outcome of doing something; a verb that only reports the state of an artifact the CLI itself wrote has no such outcome to key. plugin/bin/verify.js --stamp-status (#1921) is the shipped instance — its header states the rule outright ("Status is data, never a failure — exit 0 in every case, including 'no checkout at all'") — and it prints {present, match, …} whether the pass stamp is absent, present-but-mismatched, or unreadable because there is no git dir to read from. Spending a non-zero code on "absent" would force every consuming skill to reimplement the state machine in shell, and a sibling reading that code as "not verified" is exactly the misread it prevents. Two constraints keep the exemption honest: malformed invocation of the status verb still throws into the vocabulary's usage code (--stamp-status rejects --cmd, --scope, --base, --integration-branch), and the exemption is declared in the CLI's own USAGE alongside its other modes so a reader sees which verbs it covers.

• A guard added to an existing run(argv, deps) reaches the environment through deps too. The seam above is stated as "every side effect", so an argument-validation read — process.cwd(), a git-root probe, a stat — reads as exempt and gets called directly. It isn't. plugin/bin/materialize.js's --run-dir anchoring guard (#790) shipped calling plugin/bin/lib/hooks/worktree-detect.js's isAnchoredUnderRoot directly while the cwd/mainRoot calls beside it were already injected; only a review lens caught the one-of-three gap. A validation guard bolted onto an already-seamed CLI is exactly where the seam gets holed, because it doesn't feel like a side effect — inject it (deps.cwd, deps.mainRoot, deps.isAnchored) as you write it, and add the fake to every consuming test's deps object in the same commit.

• A run-directory argument gets one of four boundary guards; pick before writing the check. plugin/skills/_shared/pipeline-run-dir.md's CLI-argument-boundary section is canonical and enumerates all four itself ("Four shapes live at this boundary"); this bullet is the bin/-side summary, never a second registry. (1) Pipeline-owned binaries (hooks.js, wrap-up-engine.js, materialize.js, apply-refine-labels.js) refuse any value not anchored under the main checkout and exit 2. (2) The two resolver CLIs (plugin/bin/resolve-profile.js, plugin/bin/resolve-policy.js, #1065) call worktree-detect.js's checkRunDirAnchoredOrOutside — a resolved path inside any checkout must be anchored, a path outside every checkout is accepted as-is — and exit 1, their own documented invocation-failure code. (3) The Sanctioned-writer family above (log-decision.js, stage-item.js, set-config.js) applies the same strict anchoring, but through plugin/bin/lib/stage-item/write.js's exported resolveTarget rather than worktree-detect.js directly, and refuses with exit 3, not 2. Import that resolveTarget when you add a fourth writer instead of re-deriving the predicate — set-config.js (#1376) does, on its record's own instruction — and pin the refusal with a fixture carrying both a real main-checkout run dir and a worktree-local shadow of it, asserting the shadow's file is byte-unchanged after the exit 3. (4) The composer CLI (plugin/bin/compose-context.js, #1988) is a run-directory writer ({run}/context/{step}.md) that nonetheless takes the resolver family's anchored-or-outside rule — through plugin/bin/lib/run-dir-guard.js's anchoredOrOutsideMessage, the shared message renderer the two resolvers already call — and rejects with exit 2, its malformed-invocation code, not 3. Strict is the default; anchored-or-outside needs a documented legitimate outside-repo use, and shape 4's is narrow enough to be non-precedential: its callers never branch on a run-dir code (a skill step's documented fallback on any non-zero exit is to read the named source files directly), and its tests spawn the real binary against tmp-root fixtures outside any checkout, the same documented use the resolvers have. A fifth writer inherits shape 4's reasoning only if its own callers share it; otherwise shape 3 is the default. The deps-injection rule above is scoped to binaries that already have a path-handling seam: the two resolvers are main(argv) CLIs with none, so their guard calls worktree-detect directly and is tested by spawning the real binary against tests/helpers/git-fixtures.js repos rather than by a fake — compose-context.js does have the seam and injects every path-handling call through it (deps.cwd, deps.mainRoot, deps.isDirectory, deps.anchoredOrOutsideMessage), which is the shape a new run-dir-taking CLI should copy.

• A sanctioned writer that read-modify-writes a shared file guards it; a create-only writer doesn't. The Sanctioned-writer family above splits on write shape, not on file type. plugin/bin/lib/log-decision/append.js's appendEntry read-modify-writes one shared decisions.md that concurrent bin/log-decision.js processes contend for, so it runs the whole read-modify-write-rename under plugin/bin/lib/file-lock.js's withLock (mkdir-based, best-effort/fail-open — a lock it can't acquire in LOCK_WAIT_MS proceeds unlocked rather than hanging the caller) and renames a per-process decisions.md.tmp-${process.pid} over the target, so a concurrent reader never sees a torn file even when the lock was missed (#816). plugin/bin/lib/stage-item/write.js needs neither: it creates staged/<id><ext> at a per-item path, so there is no read-modify-write to lose. The family's third member is guarded by neither, and the bullet above does not classify it: plugin/bin/lib/set-config/write.js's setConfigLever read-modify-writes the shared config.yml (replace the key's line, drop later duplicate lines, append when absent) through a bare fs.writeFileSync — no withLock, no tmp+rename. That is tolerable only because config.yml has no concurrent multi-process writer the way decisions.md does: the Manifesto writes it once per run, and the ceremony escape hatch downgrades a single lever in place later in that same run. #1580's --set batch form narrows the margin rather than widening it — it runs the whole read-modify-write once per lever in a sequential loop (13 rewrites for a full Manifesto), so a downstream bin/resolve-policy.js --run read racing that loop can land between two rewrites, and writeFileSync's truncate-then-write opens a short-read window on each one. Before adding a second concurrent writer of config.yml, or widening the batch further, give setConfigLever the same withLock + tmp+rename pairing appendEntry already has. The pairing is the repo's established shape for a contended bookkeeping file — plugin/bin/lib/hooks/context.js (run-state.json), plugin/bin/lib/flow/manifest.js (manifest.yml, tmp+rename only), plugin/bin/lib/json-store.js, and plugin/bin/lib/declined-learning/store.js all ship some combination of it — but it is documented only in file-lock.js's own header, so a new writer copied from a sibling silently inherits whichever half that sibling happened to have. Decide the shape before writing the file, and reuse withLock rather than hand-rolling a second mutex.

• When an endpoint has no GitHub MCP equivalent, say so and name the real fallback; never invent an MCP row in plugin/skills/_shared/github-write-transport.md.

• Hoist a warning-emitting check ahead of the destructive call it warns about, not after. plugin/bin/repair-claim.js (commit 387b53f4e, spec #1608 Finding 3) and plugin/bin/release-claim.js (spec #1710) both shipped the same bug independently: resolveTarget — the run-dir anchoring check whose stderr warning tells an operator decisions.md will not be written — ran after the CLI's own destructive write (repair/release.releaseClaim), so the warning arrived only once the irreversible part was already done. Both fixes were pure reorderings — compute resolveTarget (and emit its warning) before the destructive call, leave formatEntry/appendEntry after it since they need the outcome. Two independent CLIs shipping the identical ordering mistake is a pattern, not a coincidence: when a CLI on this seam pairs a destructive write with a warning about why its own audit trail might not land, write the warning-emitting check first.