@joshuafolkken/kit 1.872.0

package/scripts/review/review-stamps.ts

@@ -0,0 +1,113 @@
+import { PROJECT_ROOT } from '#scripts/init/init-paths'
+import { file_map_stamp, type FileMapStampAccess } from '#scripts/josh/file-map-stamp'
+
+// The three records `josh review:brief` reads (joshuafolkken/kit#1241, joshuafolkken/kit#1242).
+//
+// **The gate stamp** is written by `josh gate` when all four checks pass, and answers "were lint, the
+// type check, the spell check and the unit tests green on *this exact tree*". Without the tree half
+// the brief would assert a result that a later edit had already invalidated, which is the one kind of
+// report this repository refuses to make.
+//
+// **The in-flight marker** exists only while `josh gate` is running, and answers a question the gate
+// stamp cannot: the review and the gate now start together, so at the moment the brief is composed
+// the checks have usually not finished (joshuafolkken/kit#1242). Without it that state is
+// indistinguishable from "no gate was ever run", and the review agent re-runs the unit suite the run
+// is already running — the exact cost joshuafolkken/kit#1241 removed. **It asserts nothing about the
+// result**, only that a gate was started on this tree and the run joins it before committing.
+//
+// **The marker names its writer by pid *and* start time** (joshuafolkken/kit#1245). A pid on its own
+// is not a process: an interrupted gate leaves its marker behind, and once the operating system
+// reissues that pid the liveness probe passes again and the marker resumes asserting a gate that
+// ended. The pair closes that, because a reissued pid necessarily started after the record was
+// written. **The marker was not made weaker to fix it** — dropping it, or having the brief ignore it,
+// would put the re-run joshuafolkken/kit#1242 removed straight back.
+//
+// **A marker whose gate is gone is left where it is, and that is the decision rather than an
+// oversight** (joshuafolkken/kit#1245's second question). Three things make leaving it correct here.
+// The record is keyed per checkout, so exactly one file exists and nothing accumulates; the next
+// `josh gate` overwrites it, since `write_stamp` unlinks before it creates; and the identity check
+// makes a leftover inert for as long as it sits there. Removing it from the reader would buy none of
+// that and would cost the one thing that matters: the reader deletes on "not running", which is also
+// the answer a platform that cannot report a start time gives for a gate that **is** running — so the
+// sweep would delete live markers there, and the next brief of that same run would lose the in-flight
+// sentence. `unit-worker-share.ts` sweeps and is not inconsistent with this: its markers are keyed per
+// pid, so they accumulate without bound, and that is what a sweep is for.
+//
+// **The round-1 snapshot** is written by the brief itself, so that `--round 2` can name the fix
+// delta by comparison rather than by an agent recalling which files it edited.
+//
+// Both key on `PROJECT_ROOT` rather than the package directory: a globally installed `josh` has one
+// package directory for every project on the machine, so keying on it would let a run in one project
+// answer for another (the distinction joshuafolkken/kit#1215 drew for `josh latest:scope`).
+//
+// **`PROJECT_ROOT` is `process.cwd()`, so the two commands must run from the same directory to share
+// a record.** That is deliberate rather than overlooked: run from different directories they simply
+// miss each other, the brief finds no record, and it prints `Not verified` — the safe direction. The
+// tree *inside* the record cannot be left to `cwd()` the same way, because there a mismatch resolves
+// to "every file absent" on both sides and compares equal, so `review-tree.ts` asks git for the
+// repository root instead.
+
+// **The two scoped records** answer "were `josh lint:related` and `josh test:related` green on this
+// exact tree" (joshuafolkken/kit#1511). They are separate from the gate stamp because they claim
+// something narrower — the changed files rather than the whole project, and two checks rather than
+// four — and folding them into one record would let a green from either half stand for the other.
+// They are read by `scoped-green.ts`, which is where what they mean is written down; they live here
+// because a stamp prefix declared anywhere else is a second place to look for the same kind of file.
+const LINT_RELATED_PREFIX = 'josh-lint-related-stamp-'
+const TEST_RELATED_PREFIX = 'josh-test-related-stamp-'
+
+const GATE_PREFIX = 'josh-gate-stamp-'
+const IN_FLIGHT_PREFIX = 'josh-gate-running-'
+const ROUND_ONE_PREFIX = 'josh-review-round1-'
+
+const gate_stamp: FileMapStampAccess = file_map_stamp.create(GATE_PREFIX, PROJECT_ROOT)
+const in_flight_stamp: FileMapStampAccess = file_map_stamp.create(IN_FLIGHT_PREFIX, PROJECT_ROOT)
+const round_one_stamp: FileMapStampAccess = file_map_stamp.create(ROUND_ONE_PREFIX, PROJECT_ROOT)
+const lint_related_stamp: FileMapStampAccess = file_map_stamp.create(
+	LINT_RELATED_PREFIX,
+	PROJECT_ROOT,
+)
+const test_related_stamp: FileMapStampAccess = file_map_stamp.create(
+	TEST_RELATED_PREFIX,
+	PROJECT_ROOT,
+)
+
+// **The round-1 snapshot's lifetime is one run, and something has to end it**
+// (joshuafolkken/kit#1441). Since the record is written once and never retaken, one left on disk
+// would be the record the **next** run's fix delta is measured against — so the run that ends removes
+// it, and `josh followup` is where a run ends. That is the answer to "the same run or a new one" the
+// retake guard needs, taken from the event itself rather than from a proxy for it.
+//
+// **Only one of the two directions is safe, which is why the caller is a single place.** A record
+// this never reaches — a run that stopped before `followup`, a `--no-merge` invocation, a `halfrun`,
+// a review run on its own — is measured from further back, so the next run's delta is wider and the
+// answer is `required`. **Removing one out of turn is the unsafe direction**: the next round-1 brief
+// finds nothing and writes a fresh record against the already-fixed tree, and arm A then fires on
+// unreviewed fix code — the defect joshuafolkken/kit#1441 closed, reintroduced from the other side.
+// So this is called from the end of a run that **merged**, and from nowhere else.
+//
+// Swallowed, and the caller is why: by the time this runs the pull request has already merged, so a
+// temp-directory problem must not turn a completed run into a failed one.
+function clear_round_one(target?: string): void {
+	try {
+		round_one_stamp.remove(target)
+	} catch {
+		/* a record left behind widens the next round rather than narrowing it */
+	}
+}
+
+const review_stamps = {
+	clear_round_one,
+	GATE_PREFIX,
+	gate_stamp,
+	IN_FLIGHT_PREFIX,
+	in_flight_stamp,
+	LINT_RELATED_PREFIX,
+	lint_related_stamp,
+	ROUND_ONE_PREFIX,
+	round_one_stamp,
+	TEST_RELATED_PREFIX,
+	test_related_stamp,
+}
+
+export { review_stamps }

package/scripts/review/review-tree.ts

@@ -0,0 +1,58 @@
+import { readFileSync } from 'node:fs'
+import path from 'node:path'
+import { changed_paths } from '#scripts/git/changed-paths'
+import { git_command } from '#scripts/git/git-command'
+import { stamp_file } from '#scripts/josh/stamp-file'
+
+// The tree `josh review:brief` records: every path the change touches, and the digest of its content
+// (joshuafolkken/kit#1241).
+//
+// The path list is `#scripts/git/changed-paths`', the same reading `josh review:level` decides from
+// — a second definition of "changed" would let the brief describe a different change from the level
+// printed beside it.
+//
+// **The digests are what a `git diff` cannot give.** The implementation and a review's fixes are
+// uncommitted in the same tree, so a diff cannot say which side of the review a change fell on; a
+// digest taken before round 1 and compared after the fixes names exactly the fix delta.
+
+// A path the change lists but the working tree does not hold — deleted, or renamed away. Recorded
+// rather than dropped: a delete applied by a fix is part of the fix delta, and a dropped entry would
+// read as "unchanged" on the comparison.
+const ABSENT_DIGEST = 'absent'
+
+function digest_of(root: string, relative: string): string {
+	try {
+		return stamp_file.digest(readFileSync(path.join(root, relative)))
+	} catch {
+		return ABSENT_DIGEST
+	}
+}
+
+// Sorted so two readings of one tree produce the same record byte for byte, which is what lets a
+// stored stamp be compared against a fresh reading without a normalization step in between.
+function tree_of(root: string, paths: ReadonlyArray<string>): Record<string, string> {
+	const sorted = [...paths].toSorted((left, right) => left.localeCompare(right))
+
+	return Object.fromEntries(sorted.map((relative) => [relative, digest_of(root, relative)]))
+}
+
+// **The root is asked of git, never taken from `process.cwd()` — nor from `PROJECT_ROOT`, which is
+// defined as `process.cwd()`.** git prints repository-root-relative paths, so joining them onto the
+// working directory resolves to nothing whenever a command runs from a subdirectory: every digest
+// becomes `absent` on both sides of a comparison, and two such maps *agree*. The brief would then
+// say the gate had verified an arbitrarily edited tree, and `--round 2` would report an empty fix
+// delta. **A defect that answers "all clear" is the one shape this record cannot take**, which is why
+// the root is resolved rather than assumed (measured from `scripts/`: 18 of 25 entries `absent`).
+async function read_changed_tree(
+	paths?: ReadonlyArray<string>,
+	root?: string,
+): Promise<Record<string, string>> {
+	return tree_of(
+		root ?? (await git_command.repository_root()),
+		paths ?? (await changed_paths.read_changed_paths(false)),
+	)
+}
+
+const review_tree = { ABSENT_DIGEST, digest_of, read_changed_tree, tree_of }
+
+export { review_tree }

package/scripts/rules/bash-triggers.ts

@@ -0,0 +1,44 @@
+import { cost_blocks } from '#scripts/cost-runtime/cost-blocks'
+import type { GuardedCall } from '#scripts/time-runtime/time-batch-guard'
+import { time_shell } from '#scripts/time-runtime/time-shell'
+
+// The two trigger helpers the enumeration in `delivered-rules.ts` is built from, held here so a rule
+// that lives in its own module can build its own row without importing the enumeration back
+// (joshuafolkken/kit#2119). `is_issue_filing` is the one three rows now share — the WIP cap, the scout
+// gate and the per-run filing cap — so it could not stay a private function of the file that spreads
+// their rows.
+
+// **Only `Bash`, and the omission is deliberate** (joshuafolkken/kit#1390): Claude Code denies one
+// call of a turn and runs the rest, so a refused `Edit` would leave its siblings applied and itself
+// not. Every rule delivered by the enumeration is therefore one whose binding moment is a shell call —
+// so the tool-name guard belongs here rather than to each row, and a row states only what it looks for
+// in the command.
+function on_bash_command(is_match: (command: string) => boolean): (call: GuardedCall) => boolean {
+	return function is_trigger(call: GuardedCall): boolean {
+		if (call.name !== cost_blocks.BASH_TOOL) return false
+
+		return is_match(time_shell.bash_command(call.input))
+	}
+}
+
+// `gh issue create`, in any of the spellings a run reaches for.
+const ISSUE_CREATE_COMMAND = /\bgh\s+(?:\S+\s+)*?issue\s+create\b/u
+// `gh api …/issues` — the path segment has to *end* there, so a comment endpoint
+// (`…/issues/1524/comments`) and a listing under it are both left alone.
+const ISSUES_ENDPOINT = /repos\/[^\s'"]*\/issues(?=$|["'\s])/u
+// A title field is what separates the POST that files from the GET that lists: `gh api …/issues`
+// with no field is a listing, and a listing files nothing. **All four spellings**, `-F` included —
+// it is `--field`'s short form and reads as a different flag to a pattern that only knows `-f`.
+// A body passed with `--input <file>` carries the title inside the file and is not visible here;
+// that limit is recorded beside the non-`gh` one in `prompts/collaboration-workflow/rule-delivery.md`.
+const TITLE_FIELD = /(?:-f|-F|--field|--raw-field)\s*'?title=/u
+
+function is_issue_filing(command: string): boolean {
+	if (ISSUE_CREATE_COMMAND.test(command)) return true
+
+	return ISSUES_ENDPOINT.test(command) && TITLE_FIELD.test(command)
+}
+
+const bash_triggers = { is_issue_filing, on_bash_command }
+
+export { bash_triggers }

package/scripts/rules/decision-oracle.ts

@@ -0,0 +1,342 @@
+// The enumeration of decision oracles — commands that answer a rule question from mechanically
+// readable inputs, making prose reasoning unnecessary (joshuafolkken/kit#2117).
+//
+// **Question 0 of the rule-placement criterion**: "Can the rule's answer be computed from
+// mechanically readable inputs alone?" A yes means the rule is answered by a command on this list,
+// not by prose. Single source: `prompts/collaboration-workflow/residency.md` → question 0.
+//
+// Anything not on this list is answered by prose or by a hook-delivered rule, never by a command.
+
+// Paths that appear in more than one entry's `single_source` field.
+const CHAIN_RULE_MD = '.claude/skills/workflow-commands/chain-rule.md'
+const BACKLOGRUN_PROGRESS_MD = '.claude/skills/workflow-commands/backlogrun-progress.md'
+const SKILL_2E = '.claude/skills/workflow-commands/SKILL.md → §2e'
+const SPLIT_ASSESSMENT_QUESTION =
+	'.claude/skills/workflow-commands/split-assessment.md → The question'
+const PRE_GATE_CUT_MD = '.claude/skills/workflow-commands/pre-gate-cut.md'
+const BACKLOGRUN_MD = '.claude/skills/workflow-commands/backlogrun.md'
+
+// The command reference in `docs/josh-commands.md` — one section per command, headed by the command
+// itself. joshuafolkken/kit#2190 cut `backlogrun.md` back to a manifest of pointers, so a decision it
+// used to carry inline (`run:merge`, `epic:next`, `backlog:budget`, `run:liveness`, `auto-ok:next`)
+// now has its verdict contract only in this reference. That makes it the single source and the section
+// a reader is routed to, in the same `file.md → \`josh <command>\`` form the `epic:reconcile` and
+// `lane:list` entries already use. joshuafolkken/kit#2254.
+const RUN_MERGE_REFERENCE = 'docs/josh-commands.md → `josh run:merge`'
+const EPIC_NEXT_REFERENCE = 'docs/josh-commands.md → `josh epic:next`'
+const BACKLOG_BUDGET_REFERENCE = 'docs/josh-commands.md → `josh backlog:budget`'
+const RUN_LIVENESS_REFERENCE = 'docs/josh-commands.md → `josh run:liveness`'
+const AUTO_OK_NEXT_REFERENCE = 'docs/josh-commands.md → `josh auto-ok:next`'
+
+// Command used by two separate oracle entries (run:cut:resume and run:cut:gate).
+const RUN_CUT_CMD = 'run:cut'
+
+// Vocabulary tokens that appear in more than one oracle's vocabulary array.
+const REQUIRED = 'required'
+const SKIP = 'skip'
+const STOP = 'stop'
+const WAIT = 'wait'
+const RETRY = 'retry'
+const OVER = 'over'
+const UNKNOWN = 'unknown'
+const NONE = 'none'
+const NOT_A_LANE = 'not-a-lane'
+const BUSY = 'busy'
+const HUMAN_REVIEW = 'human-review'
+// Lane liveness verdicts shared by the lane:list oracle and asserted against `lane_occupancy` in its
+// test. `LIVE` is the silent norm; `STOPPED` and `UNKNOWN` lead the difference lines.
+const LIVE = 'live'
+const STOPPED = 'stopped'
+// The verdicts `epic --reconcile` prints; kept in step with the `git_epic_reconcile` constants in its
+// test.
+const RECONCILED = 'reconciled'
+const NOTHING_TO_RECONCILE = 'nothing to reconcile'
+
+// Arguments shared by more than one oracle entry.
+const ISSUE_N_ARG = '<N>'
+const EXCLUDE_ARG = '[--exclude <n>...]'
+
+interface DecisionOracle {
+	// Short identifier used by the CLI and tests.
+	name: string
+	// The rule question the command answers.
+	decision: string
+	// The command subcommand (without the `pnpm josh` prefix). Omit when equal to `name`;
+	// `get_command()` returns the effective value.
+	command?: string
+	// The arguments to pass, shown in the printed listing.
+	args: string
+	// The fixed-vocabulary tokens the command emits — on standard output for a pure decision command,
+	// or on the difference lines of a listing command (`lane:list`) whose standard output is reserved
+	// for its listing. An issue number is not a vocabulary token; only the named string verdicts appear
+	// here, and each is kept in step with the constant its emitting module exports.
+	vocabulary: ReadonlyArray<string>
+	// The single-source document for the decision procedure, in `file.md → section` form.
+	single_source: string
+}
+
+const DECISION_ORACLES: ReadonlyArray<DecisionOracle> = [
+	{
+		name: 'delegate',
+		decision: 'Whether a run step may be delegated to a cheaper execution tier',
+		args: '<step>',
+		vocabulary: ['delegate', 'keep'],
+		single_source: '.claude/skills/workflow-commands/SKILL.md → §2b',
+	},
+	{
+		name: 'review:level',
+		decision: 'The code-review level for the changed paths',
+		command: 'review:brief',
+		args: '--level-only',
+		vocabulary: ['low', 'medium', 'high', 'max'],
+		single_source: 'prompts/review.md',
+	},
+	{
+		name: 'review:round2',
+		decision: 'Whether the second /code-review round is due',
+		args: '[--round-1-closed]',
+		vocabulary: [REQUIRED, SKIP],
+		single_source: CHAIN_RULE_MD,
+	},
+	{
+		name: 'disposition',
+		decision: 'Whether a review finding reaches a runtime path, so it may be filed',
+		args: '<path...>',
+		vocabulary: ['runtime', 'non-runtime'],
+		single_source: 'prompts/review.md → Three-way disposition after the cap',
+	},
+	{
+		name: 'review:attest',
+		decision: 'Whether a /code-review attested the briefed checkout',
+		args: '--check',
+		vocabulary: ['ok', 'missing', 'mismatch', 'not-required'],
+		single_source: CHAIN_RULE_MD,
+	},
+	{
+		name: 'latest:scope',
+		decision: 'Whether this run has to update dependencies first',
+		args: '',
+		vocabulary: [REQUIRED, SKIP],
+		single_source: '.claude/skills/workflow-commands/latest-gate.md',
+	},
+	{
+		name: 'run:hold',
+		decision: 'Whether this working tree is free for a run to claim',
+		args: `[${ISSUE_N_ARG}]`,
+		vocabulary: ['hold', BUSY, UNKNOWN],
+		single_source: '.claude/skills/workflow-commands/SKILL.md → §2f',
+	},
+	{
+		name: 'cost:cut',
+		command: 'cost',
+		decision: 'Whether the session cost exceeds the hand-off threshold',
+		args: '--cut',
+		vocabulary: [OVER, 'under'],
+		single_source: BACKLOGRUN_PROGRESS_MD,
+	},
+	{
+		name: 'release:scope',
+		decision: 'Whether a release is owed after this merge',
+		args: '',
+		vocabulary: [REQUIRED, SKIP, UNKNOWN],
+		single_source: '.claude/skills/workflow-commands/followup-reference.md',
+	},
+	{
+		name: 'epic:bundle',
+		decision: 'Which epic a newly filed issue belongs to',
+		args: ISSUE_N_ARG,
+		vocabulary: ['add_to_epic', 'create_epic', 'ask', 'nothing_to_bundle'],
+		single_source: SKILL_2E,
+	},
+	{
+		name: 'issue:scout',
+		decision: 'Whether a matching open issue already exists before filing',
+		args: '<title>',
+		vocabulary: ['Duplicates:', 'Epic:'],
+		single_source: SKILL_2E,
+	},
+	{
+		name: 'issue:fold',
+		decision: 'Whether findings filed from one session fold into one issue or stay separate',
+		args: '<title...>',
+		vocabulary: ['fold', 'separate', 'no-fold-needed'],
+		single_source: SPLIT_ASSESSMENT_QUESTION,
+	},
+	{
+		name: 'pkg:scout',
+		decision: 'Whether the top package candidate is clearly best (Tier A) or a near-tie (Tier B)',
+		args: '<keywords>',
+		vocabulary: ['clear', 'close'],
+		single_source: 'CLAUDE.md → Package-First Development',
+	},
+	{
+		name: 'issue:lint',
+		decision:
+			'Whether a behavior-change issue declares a deliverable firing point and a re-runnable baseline',
+		args: '<path>',
+		vocabulary: ['ok', '✖ missing heading', '✖ firing point', '✖ baseline'],
+		single_source: 'prompts/collaboration-workflow/issue-template.md',
+	},
+	{
+		name: 'cases',
+		decision:
+			'Each boundary a change crosses (network, process, fs, time) and the abnormal cases it owes',
+		args: '<path...>',
+		vocabulary: ['network', 'process', 'fs', 'time', NONE],
+		single_source: 'prompts/collaboration-workflow/report-format.md → 変更とテスト',
+	},
+	{
+		name: 'issue:state',
+		decision: "An issue's state, labels, and human-review flag",
+		args: ISSUE_N_ARG,
+		vocabulary: ['human_review: yes', 'human_review: no'],
+		single_source: '.claude/skills/workflow-commands/SKILL.md → §2z',
+	},
+	{
+		name: 'run:cut:resume',
+		command: RUN_CUT_CMD,
+		decision: 'Whether a lane child is resuming prior work or starting fresh',
+		args: `--resume ${ISSUE_N_ARG}`,
+		vocabulary: ['fresh', 'resume', NOT_A_LANE],
+		single_source: PRE_GATE_CUT_MD,
+	},
+	{
+		name: 'run:cut:gate',
+		command: RUN_CUT_CMD,
+		decision: 'Whether a lane child should take its pre-gate cut now',
+		args: ISSUE_N_ARG,
+		vocabulary: ['cut', NOT_A_LANE],
+		single_source: PRE_GATE_CUT_MD,
+	},
+	{
+		name: 'backlog:budget',
+		decision: 'Whether a backlogrun may start more work, keep watching, or finish',
+		args: '',
+		vocabulary: ['run', 'watch', STOP],
+		single_source: BACKLOG_BUDGET_REFERENCE,
+	},
+	{
+		name: 'run:liveness',
+		decision: 'Whether a delegated unit is still working or has stopped without reporting',
+		args: `${ISSUE_N_ARG} --output <path>`,
+		vocabulary: ['alive', 'stopped', 'settled', 'undetermined'],
+		single_source: RUN_LIVENESS_REFERENCE,
+	},
+	{
+		name: 'stash:pop',
+		decision: 'Whether a named stash entry exists and can be applied',
+		args: '<message>',
+		vocabulary: ['popped', 'conflicted', 'no-match', 'ambiguous'],
+		single_source: '.claude/skills/workflow-commands/SKILL.md → §2d',
+	},
+	{
+		name: 'backlog:next',
+		decision: 'Which issue the backlog offers next, or whether to wait or stop',
+		args: EXCLUDE_ARG,
+		vocabulary: [WAIT, STOP, RETRY, 'error', NONE],
+		single_source: BACKLOGRUN_MD,
+	},
+	{
+		name: 'auto-ok:next',
+		decision: 'The next opted-in issue outside any epic, or none',
+		args: EXCLUDE_ARG,
+		vocabulary: [NONE],
+		single_source: AUTO_OK_NEXT_REFERENCE,
+	},
+	{
+		name: 'epic:next',
+		decision: "The next runnable child of an epic, or the epic's status",
+		args: '<epic>',
+		vocabulary: [WAIT, STOP, 'complete'],
+		single_source: EPIC_NEXT_REFERENCE,
+	},
+	{
+		name: 'run:merge',
+		decision: 'The post-merge batch step: confirm child, advance, or report a stop condition',
+		args: ISSUE_N_ARG,
+		vocabulary: [OVER, HUMAN_REVIEW, STOP, RETRY, BUSY],
+		single_source: RUN_MERGE_REFERENCE,
+	},
+	{
+		name: 'run:step',
+		decision: 'The run’s next single action, computed from the event stream, carry and issue state',
+		args: ISSUE_N_ARG,
+		// The non-command answers: `run:step` prints a runnable command for a phase with one to run, and
+		// one of these verdicts otherwise. A command line is not a vocabulary token, exactly as an issue
+		// number is not one for `backlog:next`.
+		vocabulary: [
+			'implement',
+			HUMAN_REVIEW,
+			'update-deps',
+			'already-done',
+			'keep-work',
+			WAIT,
+			STOP,
+			UNKNOWN,
+		],
+		single_source: BACKLOGRUN_MD,
+	},
+	{
+		name: 'refactor:scan',
+		decision: 'Whether the refactoring scope still holds high- or medium-priority candidates',
+		args: '',
+		vocabulary: ['clear', 'candidates', 'error'],
+		single_source: 'prompts/refactoring.md',
+	},
+	{
+		name: 'split:assess',
+		decision: 'Whether a change size clears the split guide (the split assessment size question)',
+		args: '[--json]',
+		vocabulary: ['split', 'single'],
+		single_source: SPLIT_ASSESSMENT_QUESTION,
+	},
+	{
+		name: 'sonar:hotspots',
+		decision: 'The Step B disposition for each SonarCloud hotspot on a pull request',
+		args: '<PR>',
+		vocabulary: ['excluded', 'local', 'fix', 'defer', 'unreadable'],
+		single_source: 'prompts/sonar-hotspot-handling.md',
+	},
+	{
+		name: 'clone:scan',
+		decision: 'Whether cross-file or cross-repository code duplication exists',
+		args: '',
+		vocabulary: ['clean', 'clones:'],
+		single_source: 'prompts/collaboration-workflow/no-clones.md',
+	},
+	{
+		name: 'epic:reconcile',
+		command: 'epic',
+		decision:
+			"Whether an epic's declaration matches its recorded relations, and the repair when it does not",
+		args: '--reconcile <E>',
+		vocabulary: [RECONCILED, NOTHING_TO_RECONCILE],
+		single_source: 'docs/josh-commands.md → `josh epic --reconcile`',
+	},
+	{
+		name: 'lane:list',
+		decision:
+			'Whether each in-progress issue holds a live lane, and the two-directional difference',
+		args: '',
+		vocabulary: [LIVE, STOPPED, UNKNOWN],
+		single_source: 'docs/josh-commands.md → The `in-progress` / lane difference',
+	},
+]
+
+// Returns the command name for an oracle entry. When `command` is omitted from the entry,
+// the `name` field doubles as the command name.
+function get_command(oracle: DecisionOracle): string {
+	return oracle.command ?? oracle.name
+}
+
+function find_oracle(name: string): DecisionOracle | undefined {
+	return DECISION_ORACLES.find((oracle) => oracle.name === name.trim())
+}
+
+const decision_oracle = {
+	DECISION_ORACLES,
+	find_oracle,
+	get_command,
+}
+
+export { decision_oracle }

package/scripts/rules/delivered-rules-harness.ts

@@ -0,0 +1,72 @@
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import path from 'node:path'
+import { delivered_rules } from './delivered-rules'
+
+// The payload machinery two delivery suites share (joshuafolkken/kit#2119). `delivered-rules.test.ts`
+// had it first; the filing rules — the scout gate and the per-run cap — need the same temp transcript,
+// payload envelope and per-rule stamp cleanup, so a second copy in `delivered-rules-filing.test.ts`
+// would be the clone `CLAUDE.md` prohibits. Each suite calls `create_harness()` once, so each gets its
+// own work directory and its own tracked transcripts.
+
+const PRE_TOOL_USE = 'PreToolUse'
+const BASH_TOOL = 'Bash'
+
+interface Harness {
+	// The temp directory this harness's transcripts live under.
+	work: string
+	// Every transcript file written, so a suite can clean the batching stamp keyed on each of them.
+	written: ReadonlySet<string>
+	transcript_for: (name: string, text?: string) => string
+	payload_for: (transcript: string, command: string, tool_name?: string) => string
+	payload_of: (name: string, command: string, tool_name?: string, history?: string) => string
+	// Removes every rule's once-per-run stamp for every written transcript, then the work directory.
+	cleanup: () => void
+}
+
+function payload_for(transcript: string, command: string, tool_name = BASH_TOOL): string {
+	return JSON.stringify({
+		hook_event_name: PRE_TOOL_USE,
+		transcript_path: transcript,
+		tool_name,
+		tool_input: { command },
+	})
+}
+
+function create_harness(prefix = 'rule-guard-'): Harness {
+	const work = mkdtempSync(path.join(tmpdir(), prefix))
+	const written = new Set<string>()
+
+	// The trigger reads the call, never the history, so an empty transcript is the honest fixture — it
+	// proves the decision came from the command rather than from anything behind it.
+	function transcript_for(name: string, text = ''): string {
+		const target = path.join(work, `${name}.jsonl`)
+
+		writeFileSync(target, text)
+		written.add(target)
+
+		return target
+	}
+
+	// `history` is the transcript behind the call, empty for a case that reads only the command.
+	function payload_of(name: string, command: string, tool_name = BASH_TOOL, history = ''): string {
+		return payload_for(transcript_for(name, history), command, tool_name)
+	}
+
+	function cleanup(): void {
+		for (const transcript of written) {
+			for (const rule of delivered_rules.DELIVERED_RULES) {
+				rmSync(delivered_rules.delivery_path(rule.id, transcript), { force: true })
+			}
+		}
+
+		rmSync(work, { recursive: true, force: true })
+	}
+
+	return { work, written, transcript_for, payload_for, payload_of, cleanup }
+}
+
+const delivered_rules_harness = { create_harness }
+
+export type { Harness }
+export { delivered_rules_harness }