@joshuafolkken/kit 1.872.0

package/scripts/rules/lane-park.ts

@@ -0,0 +1,122 @@
+import { NEEDS_DECISION_LABEL } from '#scripts/git/issue-labels'
+import { lane_child_marker } from '#scripts/lane/lane-child-marker'
+import { shell_segments } from './shell-segments'
+
+// A dispatched lane child records its park before it stops, delivered at the call it binds on
+// (joshuafolkken/kit#2034).
+//
+// **A lane child that stopped for a decision left no question behind.** A `backlogrun` dispatches a
+// child as a detached `fullrun #<N>` process, and its only route to ask a person anything is to park
+// the Issue — `needs-decision` plus a comment carrying the question. Measured twice in one run on
+// 2026-09-14: #2012's child had its `AskUserQuestion` refused (it is headless), wrote the question
+// into its final message, sent a `confirmation` Telegram and exited; #2011 wrote a Tier B decision to
+// its final message and exited the same way. Neither left a label or a comment, so the parent found an
+// OPEN Issue with `in-progress` and no question, and a person looking at the Issue could not tell what
+// to answer. The child is the one process that knows the question, the options and whether it stashed,
+// and that knowledge died with its turn.
+//
+// **The stop is one shell call, so the rule is delivered rather than resident.** `CLAUDE.md` mandates
+// a `confirmation` Telegram before any mid-workflow stop, so `pnpm josh notify --task-type
+// confirmation` is the call every lane-child stop passes through. The agent that obeys this is always
+// a `claude -p` child, so the rule leaves residency entirely (`prompts/collaboration-workflow/rule-delivery.md`).
+//
+// **Why once per run and not a synchronous compliance check.** The pre-gate cut can stay silent on a
+// compliant run because the cut record is a local file it reads synchronously; the park is a label on
+// GitHub, which a `PreToolUse` guard cannot read (it answers synchronously, network calls are out).
+// Scanning the transcript tail for the label instead is unsafe in the one direction that matters: a
+// child that merely *read* `backlogrun-park.md`, whose prose carries the very `labels[]=needs-decision`
+// command, would look compliant and the guard would fall silent on a real violation — the whole bug,
+// reappearing inside its own check. So the row carries no `already_satisfied`: it fires once per run on
+// the stop, the reason is a checklist rather than an accusation, and a child that already parked simply
+// reissues. One wasted round trip on the compliant path is the safe direction; a missed park is not.
+
+// `josh notify`, in either spelling — the alias `nf` is expanded to `notify` before this sees it, the
+// same way `pre-gate-cut.ts` matches `gate` through `ga`.
+const NOTIFY_COMMANDS: ReadonlySet<string> = new Set(['notify'])
+// The task type that marks a stop waiting on a person, taken quoted or bare so `--task-type
+// confirmation` and `--task-type=confirmation` read alike. A `progress` or `pr` notification is not a
+// stop and never matches.
+const CONFIRMATION_TASK_TYPE = /(?:^|\s)--task-type[=\s]+["']?confirmation\b/u
+
+// A segment that sends the mid-workflow-stop Telegram. Segment-wise and alias-expanded for the reason
+// every predicate in this directory is: one shell line carries several commands, and a name quoted
+// inside a body is not the command being invoked.
+function is_confirmation_notify(command: string): boolean {
+	return shell_segments
+		.segments_of(command)
+		.some(
+			(segment) =>
+				shell_segments.is_josh_command(segment, NOTIFY_COMMANDS) &&
+				CONFIRMATION_TASK_TYPE.test(segment),
+		)
+}
+
+// The josh notify invocation in either spelling, anywhere in a blob of text. The stop guard
+// (joshuafolkken/kit#2121) asks whether a confirmation notify was issued *this turn* by scanning the
+// transcript tail rather than one command, so the "is it a stop notification" judgement stays here —
+// the same `CONFIRMATION_TASK_TYPE` regex, never a second copy of it.
+const NOTIFY_INVOCATION = /josh\s+(?:notify|nf)\b/u
+
+// **A blob, not a single command, so it cannot be segmented.** The tail is raw transcript text with a
+// notify command embedded in a JSONL string, so the two halves are tested against the whole: a josh
+// notify appears and a `--task-type confirmation` appears. That is looser than `is_confirmation_notify`
+// on purpose — the guard's safe direction is to read a real stop notification as present, so a run
+// that sent one is never told it did not.
+function mentions_confirmation_notify(text: string): boolean {
+	return NOTIFY_INVOCATION.test(text) && CONFIRMATION_TASK_TYPE.test(text)
+}
+
+// **The command test comes first and the world is consulted second**, so the `is_child_of` read — the
+// dispatch mark against this checkout's own issue — runs only on the handful of calls that are a
+// confirmation stop, not on every `Bash` call in the run. `is_child_of` is the same mechanical
+// human-or-child fact the pre-gate cut reads: a person working in a lane carries no mark and sees no
+// refusal, and a mark that leaked in naming another issue is read as a person too.
+function is_unparked_stop(
+	command: string,
+	is_lane_child: boolean = lane_child_marker.is_child_of(process.cwd()),
+): boolean {
+	if (!is_confirmation_notify(command)) return false
+
+	return is_lane_child
+}
+
+// **Keeping this rule is applying `needs-decision`**, the one act the park asks for before the stop.
+// It reads an actual `Bash` command — a label application by REST or by `gh issue edit` — never the
+// transcript tail, so a doc read that quotes the command is not mistaken for the run making it.
+const APPLIES_NEEDS_DECISION = new RegExp(
+	String.raw`(?:labels\[\]=|--add-label[= ]'?)${NEEDS_DECISION_LABEL}\b`,
+	'u',
+)
+
+function records_the_park(command: string): boolean {
+	return APPLIES_NEEDS_DECISION.test(command)
+}
+
+// The instruction in the shape a refusal can carry: what the stop must leave behind, how to record it,
+// and the reissue sentence every delivery needs. **The park procedure is named, not restated** — the
+// single source is `backlogrun-park.md` → "park and continue", and a second copy here would be the
+// clone `CLAUDE.md` prohibits.
+const LANE_PARK_REASON =
+	'⛔ lane child park: this session is a dispatched lane child, and a stop that waits on a person must ' +
+	'leave the question on the Issue before it sends this Telegram — otherwise the parent finds an OPEN ' +
+	'Issue with `in-progress` and no question, and a person cannot tell what to answer ' +
+	'(joshuafolkken/kit#2034 measured this twice in one run). The child is the only process that knows ' +
+	'the question, the options and whether it stashed, so it records the park itself rather than leaving ' +
+	'the parent to guess from a log. Before you notify and stop: apply `needs-decision` and post a ' +
+	'comment carrying the question, the options, and whether work was stashed — ' +
+	"`gh api repos/{owner}/{repo}/issues/<N>/labels -f 'labels[]=needs-decision'` then " +
+	'`pnpm josh issue:comment <N> --body-file <path>`. If this stop is a ' +
+	'`needs-human-review` or `already-done` one, that label is already on the Issue and there is nothing ' +
+	'to add. Then reissue this notify — it fires once per run and cannot repeat on the call in hand. The ' +
+	'procedure is `.claude/skills/workflow-commands/pre-gate-cut.md` → "A lane child records its park ' +
+	'before it stops", and the park itself is `backlogrun-park.md` → "park and continue".'
+
+const lane_park = {
+	LANE_PARK_REASON,
+	is_confirmation_notify,
+	is_unparked_stop,
+	mentions_confirmation_notify,
+	records_the_park,
+}
+
+export { lane_park }

package/scripts/rules/lane-switch-main.ts

@@ -0,0 +1,139 @@
+import { lane_child_marker } from '#scripts/lane/lane-child-marker'
+import { lane_paths } from '#scripts/lane/lane-paths'
+import { bash_triggers } from './bash-triggers'
+import { git_argv } from './git-argv'
+import { shell_segments } from './shell-segments'
+
+// A dispatched lane child is stopped from running `git switch main` — the fifth of the "always fails or
+// answers nothing" misfires joshuafolkken/kit#2297 catalogued (joshuafolkken/kit#2313). A lane is a
+// linked work tree, `main` is checked out by the primary work tree, and git allows one branch in one
+// work tree at a time — so the call is **structurally guaranteed to fail** with `fatal: 'main' is
+// already used by worktree at '<the primary checkout>'`. It was measured 11 times in the 2026-09-21
+// backlogrun, always in a lane child.
+//
+// **The source is the parent's step, not the child's.** The distributed procedures write
+// `git switch main && git pull` as the step before reading the dependency scope, and that is *correct in
+// the primary checkout* (`backlogrun-lanes.md` → "Once per repository, before the first lane opens"). A
+// child that runs the same line verbatim fails every time, and the failure is not free: a refused call
+// drops the independent calls batched beside it (joshuafolkken/kit#2177), so a batching child loses the
+// most. `josh main:sync` (`main-sync.ts`) already refuses inside a linked work tree for the same reason;
+// this is the *raw* form of the same call, refused before it fails rather than after.
+//
+// **It refuses rather than rewrites, because a `PreToolUse` guard can only `allow` / `deny` a command,
+// never substitute a different one** (joshuafolkken/kit#2313 decision comment). So the refusal hands back
+// the next command, exactly as #2297 required of `test:declared`: the lane is already on its own issue
+// branch, branched from a fresh default before it opened, and the latest default is brought in during the
+// gate by `pnpm josh main:merge` — so skip the step and keep implementing on the current branch.
+//
+// **The branch is judged against the lane's own, not the name `main`.** `already used by worktree` is a
+// property of any branch the primary work tree holds, not of the literal `main`, and the default branch
+// differs per repository — so hardcoding `main` would both miss a renamed default and need an async
+// `get_default_branch`. A lane child belongs on its own `<issue>-lane` branch; a `git switch` to anything
+// else is the misfire. Its own branch is read synchronously from the checkout path
+// (`lane_paths.lane_issue_of`), the weaker-but-synchronous lane test a guard is bound to
+// (joshuafolkken/kit#1864). `git switch` alone is covered — it never means a pathspec, so there is no
+// ambiguity — and `git checkout -- <path>` stays `worktree-guard.ts`'s.
+//
+// **The command test comes first and the world is consulted second**, so the lane read runs only on the
+// handful of calls that are a plain branch switch, not on every `Bash` call — the ordering
+// `lane-carry-conflict.ts` and `worktree-guard.ts` share. A person working in a lane carries no dispatch
+// mark and sees no refusal. It fires on every occurrence, not once per run: a child must never run this,
+// so the route is always "continue implementing", never a reissue (`git-force.ts`).
+
+const SWITCH_SUBCOMMAND = 'switch'
+
+// The flags under which a `git switch` does not collide with a branch the primary work tree holds: a
+// create (`-c` / `-C` / `--create` / `--force-create`) moves to a branch nothing else can hold, and a
+// detach (`-d` / `--detach`) checks out a commit with no branch at all. A segment carrying any of them is
+// not the misfire this rule refuses.
+const NON_COLLIDING_FLAGS: ReadonlySet<string> = new Set([
+	'-c',
+	'-C',
+	'--create',
+	'--force-create',
+	'-d',
+	'--detach',
+])
+
+const FLAG_PREFIX = '-'
+
+// The branch a `git switch <branch>` selects, or `undefined` when the segment is not a plain branch
+// switch: not a `switch` at all, a create/detach, or with no positional target (a bare `git switch`, or
+// `git switch -` for the previous branch — `-` starts with the flag prefix, so it is never read as a
+// target).
+function switch_target(segment: string): string | undefined {
+	const call = git_argv.parse(segment)
+
+	if (call?.subcommand !== SWITCH_SUBCOMMAND) return undefined
+	if (call.args.some((argument) => NON_COLLIDING_FLAGS.has(argument))) return undefined
+
+	return call.args.find((argument) => !argument.startsWith(FLAG_PREFIX))
+}
+
+// Every branch a shell line's `git switch` segments select. A line carries several commands, so each
+// segment is judged on its own — a `git switch main && git pull && git switch <issue>-lane` yields both
+// targets, and the switch back to the lane's own branch is the one that keeps this silent.
+function switch_targets(command: string): ReadonlyArray<string> {
+	return shell_segments
+		.segments_of(command)
+		.map((segment) => switch_target(segment))
+		.filter((target): target is string => target !== undefined)
+}
+
+// The lane's own branch — `<issue>-lane` — read from the checkout path, or `undefined` when the checkout
+// is not a lane. A lane child is always in a lane, so this resolves whenever the mark below does.
+function own_lane_branch(directory: string): string | undefined {
+	const issue = lane_paths.lane_issue_of(directory)
+
+	return issue === undefined ? undefined : lane_paths.lane_branch(issue)
+}
+
+// True when this session is a dispatched lane child switching to a branch that is not its own. The
+// command test is first, so the dispatch mark and the lane branch are read only on a real branch switch.
+function is_switch_away_from_lane(
+	command: string,
+	is_lane_child: boolean = lane_child_marker.is_child_of(process.cwd()),
+	own_branch: string | undefined = own_lane_branch(process.cwd()),
+): boolean {
+	if (!is_lane_child || own_branch === undefined) return false
+
+	return switch_targets(command).some((target) => target !== own_branch)
+}
+
+// The instruction in the shape a refusal can carry: what the command does, why it cannot succeed, and the
+// next command to run instead. The procedure is named, not restated — its single sources are
+// `backlogrun-lanes.md` and `backlogrun-child.md`, and a second copy here would be the clone `CLAUDE.md`
+// prohibits. Apostrophes are avoided so the single-quoted literal needs no escaping, as the siblings do.
+const LANE_SWITCH_MAIN_REASON =
+	'⛔ lane child on `git switch main`: this session is a dispatched lane child, and switching to the ' +
+	'default branch here always fails — a lane is a linked work tree, the primary checkout holds the ' +
+	'default branch, and git allows one branch in one work tree at a time (`fatal: main is already used ' +
+	'by worktree at <the primary checkout>`, measured 11 times in the 2026-09-21 backlogrun). Do not ' +
+	'switch: the lane is already on its own issue branch, branched from a fresh default before it opened, ' +
+	'and the latest default is brought in during the gate by `pnpm josh main:merge`. So skip this step ' +
+	'and keep implementing on the current branch — no `git switch`, no `git pull`. `pnpm josh main:sync` ' +
+	'(`josh ms`) is refused in a lane for the same reason, and a lane is finished with `pnpm josh ' +
+	'lane:close <issue-number>`. The parent runs `git switch main && git pull` in the primary checkout ' +
+	'before each lane opens, never the child — `backlogrun-lanes.md` and `backlogrun-child.md` are the ' +
+	'single sources. This rule fires on every occurrence, not once per run.'
+
+// The row itself, so `delivered-rules.ts` spreads one entry. `is_trigger` reads the input through
+// `on_bash_command` — the `Bash` tool-name gate every command row shares — and `decide` returns true so
+// it refuses every occurrence. It declares no `keeps`: continuing is the absence of a call, not a call,
+// so the row is reported unmeasured rather than scored on an act that does not exist (`git-force.ts`).
+const ROW = {
+	id: 'lane-switch-main',
+	is_trigger: bash_triggers.on_bash_command(is_switch_away_from_lane),
+	reason: LANE_SWITCH_MAIN_REASON,
+	decide: (): boolean => true,
+}
+
+const lane_switch_main = {
+	LANE_SWITCH_MAIN_REASON,
+	ROW,
+	is_switch_away_from_lane,
+	switch_target,
+	switch_targets,
+}
+
+export { lane_switch_main }

package/scripts/rules/oracle-consulted.ts

@@ -0,0 +1,81 @@
+import type { GuardedCall } from '#scripts/time-runtime/time-batch-guard'
+import { bash_triggers } from './bash-triggers'
+import { decision_oracle } from './decision-oracle'
+import type { DeliveredRule } from './delivered-rules'
+import { oracle_firing, type FiringPoint } from './oracle-firing'
+import { shell_segments } from './shell-segments'
+import { tail_commands } from './tail-commands'
+
+// The one generic rule that turns a declared firing point into a delivered guard (joshuafolkken/kit#2324).
+// `oracle-firing.ts` records, per oracle, the action that must consult it first; this generates a
+// `DeliveredRule` for each such oracle — refused when the run performs the governed action without
+// having run the oracle's command earlier, stood down once it has.
+//
+// **It is `issue-scout`'s shape, generalized.** Each generated row is once per run with an
+// `already_satisfied` stand-down read off the tail — refuse the governed call, hand back the command,
+// stand down once that command is on the tail. What `issue-scout` and `issue-fold` hand-wrote per
+// oracle, this reads from the registry: the refusal is assembled from the oracle's decision, command,
+// answer vocabulary and single source, so no oracle carries a hand-written refusal of its own. **No new
+// delivery path** — the rows join `DELIVERED_RULES` and fire through the same `create_transcript_guard`
+// shell every other row uses.
+
+// One oracle entry, aliased so the generated rows' signatures stay under the line limit.
+type Oracle = (typeof decision_oracle.DECISION_ORACLES)[number]
+
+// The oracle's own command, the one act each generated rule asks for. Matched in either spelling by
+// `is_josh_command`, which expands the alias before comparing.
+function command_names(oracle: Oracle): ReadonlySet<string> {
+	return new Set([decision_oracle.get_command(oracle)])
+}
+
+// Keeping the rule: a call that runs the oracle. Segment-wise, so a spelling quoted inside the governed
+// call's own arguments is not read as the consultation it skipped.
+function runs_the_oracle(command: string, names: ReadonlySet<string>): boolean {
+	return shell_segments
+		.segments_of(command)
+		.some((segment) => shell_segments.is_josh_command(segment, names))
+}
+
+// The full `pnpm josh <command> <args>` string the refusal hands back, from the registry alone.
+function command_line(oracle: Oracle): string {
+	const command = decision_oracle.get_command(oracle)
+
+	return oracle.args ? `pnpm josh ${command} ${oracle.args}` : `pnpm josh ${command}`
+}
+
+// The refusal, assembled from the registry so no oracle carries a hand-written one: what the call is
+// doing, the decision it skipped, the command that answers it and the tokens that command emits, and
+// the single source of the procedure.
+function reason_for(oracle: Oracle, firing_point: FiringPoint): string {
+	return (
+		`⛔ decision oracle not consulted: this is ${firing_point.describes}, but the run has not run ` +
+		`\`${command_line(oracle)}\` first — the oracle that decides ${oracle.decision.toLowerCase()}. ` +
+		`It answers ${oracle.vocabulary.join(' | ')}; single source ${oracle.single_source}. Reissue ` +
+		`after running it and reading its verdict. It fires once per run and cannot repeat on the call ` +
+		`in hand.`
+	)
+}
+
+function row_for(oracle: Oracle, firing_point: FiringPoint): DeliveredRule {
+	const names = command_names(oracle)
+
+	return {
+		id: `oracle-consulted:${oracle.name}`,
+		is_trigger: bash_triggers.on_bash_command(firing_point.governs),
+		reason: reason_for(oracle, firing_point),
+		already_satisfied: (tail: string, _call: GuardedCall): boolean =>
+			tail_commands.prior_bash_commands(tail).some((command) => runs_the_oracle(command, names)),
+		keeps: bash_triggers.on_bash_command((command: string) => runs_the_oracle(command, names)),
+	}
+}
+
+// One row per oracle that declared a firing point, in registry order. Spread into `DELIVERED_RULES`
+// after the filing rows, so a firing point that overlaps a filing (`issue:lint`) delivers on the
+// reissue rather than ahead of `wip-cap` / `issue-scout`.
+const ROWS: ReadonlyArray<DeliveredRule> = oracle_firing
+	.firing_oracles()
+	.map(({ oracle, firing_point }) => row_for(oracle, firing_point))
+
+const oracle_consulted = { ROWS, command_line, reason_for, row_for, runs_the_oracle }
+
+export { oracle_consulted }

package/scripts/rules/oracle-firing.ts

@@ -0,0 +1,151 @@
+import { bash_triggers } from './bash-triggers'
+import { decision_oracle } from './decision-oracle'
+import { shell_segments } from './shell-segments'
+
+// The firing-point declaration every decision oracle owes (joshuafolkken/kit#2324). An oracle records a
+// *decision*, but nothing on the oracle entry says which action must consult it first — so the 32
+// oracles have a command each and a firing point almost never. This module is the missing half: for
+// every oracle name, either the governed action (a `FiringPoint`, matched as a Bash command) or the
+// reason none can be named. A run adding an oracle must answer one or the other, and the totality is
+// enforced by `oracle-firing.test.ts` rather than by judgement.
+//
+// **It lives beside `decision-oracle.ts`, not inside it**, because that file sits 15 code lines under
+// the 300 ceiling and 32 declarations would breach it. The registry stays a printable enumeration; the
+// firing points key off its names, and the test asserts the keys cover every oracle exactly once. The
+// predicate lives on the declaration so a line fully names its own trigger — the generic guard
+// (`oracle-consulted.ts`) reads it rather than carrying a second table keyed by name.
+
+// The governed action an oracle must precede: a human description printed by `oracle:list`, and a Bash
+// predicate the generic guard fires on.
+interface FiringPoint {
+	describes: string
+	governs: (command: string) => boolean
+}
+
+// **A package-add, not a bare install.** `pnpm add <pkg>` / `yarn add` / `bun add` add a dependency, as
+// does `npm install <pkg>` with a package argument; a bare `pnpm install` reinstalls the lockfile and
+// adds nothing, so it is left alone. Segment-wise, so a spelling quoted inside another command's body is
+// not read as the add it is not.
+const PACKAGE_ADD = /^(?:pnpm|yarn|bun)\s+add\s+\S|^npm\s+(?:install|i)\s+[^-\s]/u
+
+function is_package_add(command: string): boolean {
+	return shell_segments.segments_of(command).some((segment) => PACKAGE_ADD.test(segment))
+}
+
+// The two firing points wired — the oracles whose governed call can be named without guessing: the
+// package add and the Issue filing. The rest declare why none can be named, so the unenforced oracles
+// are visible rather than silently missing.
+const FIRING: ReadonlyMap<string, FiringPoint> = new Map([
+	[
+		'pkg:scout',
+		{
+			describes: 'a package-add command (`pnpm add …`, `npm install <pkg>`)',
+			governs: is_package_add,
+		},
+	],
+	[
+		'issue:lint',
+		{
+			describes: 'an Issue-filing call (`gh api …/issues`, `gh issue create`)',
+			governs: bash_triggers.is_issue_filing,
+		},
+	],
+])
+
+// The reason an oracle names no firing point, in three recurring shapes plus the one-off reasons for
+// oracles already gated or sequenced elsewhere. `PHASE` — the governed act is a run phase, not one
+// shell call. `READ` — it answers a status question and governs no action of its own. `SELF` — the
+// command is itself the act, with nothing earlier to gate. A guard for any of these would fire on the
+// wrong turn or double-gate a call another rule already claims; `release:scope` (joshuafolkken/kit#2334)
+// is the one that *trails* rather than gates — it reads state that only exists after the merge.
+const PHASE =
+	'the act it governs is a phase of a run, not a single shell call a trigger can anchor on'
+const READ = 'it answers a status question and governs no action of its own to gate before'
+const SELF = 'the command is itself the governed act; there is no earlier call to gate before it'
+
+const LATEST_SCOPE_REASON =
+	'the run it governs (`pnpm josh latest`) is already gated at its point of use by the latest-gate; ' +
+	'a firing here would double-gate it'
+const EPIC_BUNDLE_REASON =
+	'it runs after a filing to place it, and that filing is already gated by `issue-scout`; it has no ' +
+	'earlier call of its own'
+const RELEASE_SCOPE_REASON =
+	'it reads the release owed *after* `pnpm josh followup` has merged (`git_followup_pending`), so it ' +
+	'trails the merge rather than gating it; a firing on `followup` would gate a check that must run ' +
+	'once the merge is done, reading a pre-merge state that has not yet arrived'
+
+const NOT_NAMED: ReadonlyMap<string, string> = new Map([
+	['release:scope', RELEASE_SCOPE_REASON],
+	['delegate', PHASE],
+	['review:level', READ],
+	['review:round2', READ],
+	['disposition', READ],
+	['review:attest', READ],
+	['latest:scope', LATEST_SCOPE_REASON],
+	['run:hold', SELF],
+	['cost:cut', READ],
+	['epic:bundle', EPIC_BUNDLE_REASON],
+	['issue:scout', 'the filing it governs is already gated by the `issue-scout` delivered rule'],
+	[
+		'issue:fold',
+		'the second filing it governs is already gated by the `issue-fold` delivered rule',
+	],
+	['cases', READ],
+	['issue:state', READ],
+	['run:cut:resume', SELF],
+	['run:cut:gate', SELF],
+	['backlog:budget', READ],
+	['run:liveness', READ],
+	['stash:pop', SELF],
+	['backlog:next', READ],
+	['auto-ok:next', READ],
+	['epic:next', READ],
+	['run:merge', PHASE],
+	['run:step', SELF],
+	['refactor:scan', PHASE],
+	['split:assess', PHASE],
+	['sonar:hotspots', READ],
+	['clone:scan', PHASE],
+	['epic:reconcile', SELF],
+	['lane:list', READ],
+])
+
+// The declaration for one oracle: a firing point, a reason none is named, or neither — the last is the
+// undeclared state the test refuses.
+interface FiringDeclaration {
+	firing_point?: FiringPoint
+	not_firing_reason?: string
+}
+
+function declaration_for(name: string): FiringDeclaration {
+	const firing_point = FIRING.get(name)
+
+	if (firing_point !== undefined) return { firing_point }
+
+	const not_firing_reason = NOT_NAMED.get(name)
+
+	return not_firing_reason === undefined ? {} : { not_firing_reason }
+}
+
+// Every oracle that declares a firing point, paired with it — the generic guard's input.
+function firing_oracles(): ReadonlyArray<{
+	oracle: (typeof decision_oracle.DECISION_ORACLES)[number]
+	firing_point: FiringPoint
+}> {
+	return decision_oracle.DECISION_ORACLES.flatMap((oracle) => {
+		const firing_point = FIRING.get(oracle.name)
+
+		return firing_point === undefined ? [] : [{ oracle, firing_point }]
+	})
+}
+
+const oracle_firing = {
+	FIRING,
+	NOT_NAMED,
+	declaration_for,
+	firing_oracles,
+	is_package_add,
+}
+
+export type { FiringDeclaration, FiringPoint }
+export { oracle_firing }

package/scripts/rules/oracle-list-cli.ts

@@ -0,0 +1,81 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { decision_oracle } from './decision-oracle'
+import { oracle_firing } from './oracle-firing'
+
+// `josh oracle:list` — print the decision oracles enumeration (joshuafolkken/kit#2117).
+//
+// A command rather than a paragraph: the criterion is `prompts/collaboration-workflow/residency.md`
+// → question 0, and the list is what it points at. Adding an oracle here is the whole action;
+// nothing else is updated.
+
+const ARGV_OFFSET = 2
+const INDENT = '  '
+const FIELD_WIDTH = 10
+
+function pad_field(label: string): string {
+	return label.padEnd(FIELD_WIDTH)
+}
+
+// The firing point an oracle governs, or the reason none is named — one line either way, so `oracle:list`
+// shows at a glance which oracles a guard enforces and which stay visibly unenforced (joshuafolkken/kit#2324).
+function firing_line(oracle: (typeof decision_oracle.DECISION_ORACLES)[0]): string {
+	const declaration = oracle_firing.declaration_for(oracle.name)
+
+	if (declaration.firing_point !== undefined) {
+		return `${INDENT}${INDENT}${pad_field('fires on')}${declaration.firing_point.describes}`
+	}
+
+	return `${INDENT}${INDENT}${pad_field('no firing')}${declaration.not_firing_reason ?? ''}`
+}
+
+function format_oracle(oracle: (typeof decision_oracle.DECISION_ORACLES)[0]): string {
+	const command = decision_oracle.get_command(oracle)
+	const command_with_args = oracle.args
+		? `pnpm josh ${command} ${oracle.args}`
+		: `pnpm josh ${command}`
+
+	return [
+		`${INDENT}${oracle.name}`,
+		`${INDENT}${INDENT}${pad_field('decision')}${oracle.decision}`,
+		`${INDENT}${INDENT}${pad_field('command')}${command_with_args}`,
+		`${INDENT}${INDENT}${pad_field('answers')}${oracle.vocabulary.join(' | ')}`,
+		firing_line(oracle),
+		`${INDENT}${INDENT}${pad_field('source')}${oracle.single_source}`,
+	].join('\n')
+}
+
+function print_list(): void {
+	console.info('decision oracles:')
+
+	for (const oracle of decision_oracle.DECISION_ORACLES) {
+		console.info(format_oracle(oracle))
+	}
+}
+
+function run(argv: ReadonlyArray<string>): number {
+	if (argv.length > 0) {
+		console.error('Usage: josh oracle:list')
+
+		return 1
+	}
+
+	print_list()
+
+	return 0
+}
+
+function main(argv: ReadonlyArray<string>): void {
+	process.exitCode = run(argv)
+}
+
+const oracle_list_cli = {
+	format_oracle,
+	main,
+	print_list,
+	run,
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) main(process.argv.slice(ARGV_OFFSET))
+
+export { oracle_list_cli }