@joshuafolkken/kit 1.1050.0 → 1.1128.0

package/scripts/review/review-brief.ts

@@ -1,6 +1,7 @@
 import { agent_role_profile, type AgentProfile } from '#scripts/agent/agent-role-profile'
 import { file_map_stamp, type FileMapStamp } from '#scripts/josh/file-map-stamp'
 import { review_checkout, type ReviewCheckout } from './review-checkout'
+import { review_diff_parts, type DiffParts } from './review-diff-parts'
 
 // The text `josh review:brief` prints — the `/code-review` invocation, composed from what the run
 // already knows (joshuafolkken/kit#1241).
@@ -56,7 +57,7 @@ function attest_line(nonce: string): string {
 const RUBRIC_RELATIVE_PATH = 'prompts/review-rubric.md'
 
 function rubric_line(rubric_path: string): string {
-	return `Rubric: read \`${rubric_path}\` first and apply it — it is the severity tests, the round output format, the nine categories and the stop conditions this review is scored against. You do not carry them otherwise, so a review that skips it is scored on the wrong rules.`
+	return `Rubric: read \`${rubric_path}\` first, with the Read tool rather than \`cat\` — it is larger than the Bash output cap, so a Bash print comes back truncated (joshuafolkken/kit#2963) — and apply it: it is the severity tests, the round output format, the nine categories and the stop conditions this review is scored against. You do not carry them otherwise, so a review that skips it is scored on the wrong rules.`
 }
 
 function checkout_block(checkout: ReviewCheckout, nonce: string): string {
@@ -413,6 +414,9 @@ interface BriefInput {
 	// The tree a finished, clean review of this branch was briefed on, so round 1 is a resume
 	// (joshuafolkken/kit#2945). Absent, round 1 reads the whole change.
 	resumed_from?: FileMapStamp | undefined
+	// The change written as parts under the Bash output cap (joshuafolkken/kit#2963). Absent when the
+	// write failed, and the target line alone then names the change.
+	diff?: { parts: DiffParts; cap: number } | undefined
 }
 
 const SECOND_ROUND = 2
@@ -431,10 +435,24 @@ function target_block(input: BriefInput): string {
 	return round_two_block(input.stamps.round_one, input.tree, input.checkout.root, input.base)
 }
 
+// **Only beside a whole-change target** (joshuafolkken/kit#2963): each part is a path's diff against
+// the base, so beside a narrowed round 2 or a resumed round 1 the list would hand the reviewer the
+// code that narrowing exists to keep out of scope. Decided by the target actually printed, not by
+// the round: every round that cannot narrow widens through `whole_change_target`, and that round
+// needs the parts as much as a first one does.
+function diff_block(input: BriefInput, target: string): ReadonlyArray<string> {
+	const is_whole_change = target.includes(whole_change_target(input.checkout.root, input.base))
+
+	if (!is_whole_change || input.diff === undefined) return []
+
+	return ['', review_diff_parts.reading_block(input.diff.parts, input.diff.cap)]
+}
+
 // The level alone on the first line, because the level-only mode's contract — a caller reading the
 // answer with `$(...)` — is the one thing a brief must not break.
 function compose(input: BriefInput): string {
 	const profile = input.profile ?? agent_role_profile.DEFAULT_PROFILES.reviewer
+	const target = target_block(input)
 
 	return [
 		input.level,
@@ -448,29 +466,24 @@ function compose(input: BriefInput): string {
 		gate_line(input.stamps, input.tree, input.base),
 		TEST_COMMAND_LINE,
 		'',
-		target_block(input),
+		target,
+		...diff_block(input, target),
 	].join('\n')
 }
 
 const review_brief = {
 	attest_line,
 	BASE_MOVED_PREFIX,
-	base_moved_line,
 	carried_line,
-	checkout_block,
 	checkout_warning,
 	compose,
 	dropped_line,
 	EMPTY_DELTA_LINE,
 	gate_line,
-	green_stamp,
-	in_flight_line,
-	live_marker,
 	RESUMED_HEADING,
 	matching_stamp,
 	no_snapshot_line,
 	NOTHING_LEFT_LINE,
-	NOT_VERIFIED_LINE,
 	rubric_line,
 	RUBRIC_RELATIVE_PATH,
 	ROUND_TWO_HEADING,

package/scripts/review/review-checkout.ts

@@ -21,8 +21,9 @@ interface ReviewCheckout {
 	head: string
 }
 
-// Three git spawns that do not depend on each other, so they are issued together rather than one
-// after another: the brief is printed in front of a review the run is waiting on.
+// Three git reads that do not depend on each other, so they are issued together rather than one after
+// another: the brief is printed in front of a review the run is waiting on. The root is a near-instant
+// synchronous `rev-parse` (joshuafolkken/kit#3065); the branch and head still overlap.
 async function read_checkout(): Promise<ReviewCheckout> {
 	const [root, branch, head] = await Promise.all([
 		git_command.repository_root(),

package/scripts/review/review-diff-parts.ts

@@ -0,0 +1,89 @@
+// The change handed to the reviewer as files no larger than the Bash output cap
+// (joshuafolkken/kit#2963). The brief used to name the whole change as one `git diff` and the rubric
+// as one path, and the forked reviewer printed both through Bash: every print past
+// `BASH_MAX_OUTPUT_LENGTH` came back as a truncated preview plus a saved file it then re-read, and both
+// stayed in the cached prefix of every later request — 120 overflows and 68 re-reads in one review.
+//
+// **The diff is split, not shortened.** Each changed path gets its own parts, every part fits under the
+// cap, and the parts of one path concatenate back to exactly its diff — so the scope a review covers
+// is the one `git diff` lists, and only the size of a single read changes.
+
+// A map from each changed path to the absolute part files that carry its diff, in order.
+type DiffParts = Readonly<Record<string, ReadonlyArray<string>>>
+
+const LINE_BREAK = '\n'
+
+// A line longer than the budget is cut by characters: a minified file or a lockfile line would
+// otherwise produce one part past the cap, which is the read this module exists to remove.
+function cut_line(line: string, budget: number): Array<string> {
+	const pieces: Array<string> = []
+
+	for (let start = 0; start < line.length; start += budget) {
+		pieces.push(line.slice(start, start + budget))
+	}
+
+	return pieces
+}
+
+function pieces_of(text: string, budget: number): Array<string> {
+	return text.split(/(?<=\n)/u).flatMap((line) => cut_line(line, budget))
+}
+
+// Line-preserving where a line fits, so a part ends on a line boundary and a reader never sees a hunk
+// cut mid-line unless that one line is itself over the budget.
+function is_full(current: string, piece: string, budget: number): boolean {
+	return current.length > 0 && current.length + piece.length > budget
+}
+
+function split_text(text: string, budget: number): Array<string> {
+	const parts: Array<string> = []
+	let current = ''
+
+	for (const piece of pieces_of(text, budget)) {
+		if (is_full(current, piece, budget)) {
+			parts.push(current)
+			current = ''
+		}
+
+		current += piece
+	}
+
+	return current.length > 0 ? [...parts, current] : parts
+}
+
+function part_header(relative: string, index: number, count: number): string {
+	return `# ${relative} — part ${String(index + 1)} of ${String(count)}${LINE_BREAK}`
+}
+
+// The header is counted inside the cap, so the file a reader opens — header included — is what fits.
+// The count in the header is the final one, so it is sized against the widest header it can carry.
+function part_texts(relative: string, diff: string, cap: number): Array<string> {
+	const budget = Math.max(1, cap - part_header(relative, diff.length, diff.length).length)
+	const bodies = split_text(diff, budget)
+
+	return bodies.map((body, index) => `${part_header(relative, index, bodies.length)}${body}`)
+}
+
+function body_of(part: string): string {
+	return part.slice(part.indexOf(LINE_BREAK) + 1)
+}
+
+function part_list(parts: DiffParts): string {
+	return Object.entries(parts)
+		.flatMap(([relative, files]) => [`  ${relative}`, ...files.map((file) => `    ${file}`)])
+		.join(LINE_BREAK)
+}
+
+// **The read instruction names the tool as well as the files.** A part under the cap would survive a
+// `cat`, but the Read tool is the one read that is never truncated, and naming it keeps the reviewer
+// from reaching back for the whole `git diff` the target line defines the change by.
+function reading_block(parts: DiffParts, cap: number): string {
+	return [
+		`Reading the diff: Bash output is cut at ${String(cap)} characters, so the change is written below as one or more parts per path, each under that cap, and together exactly the diff. Read the parts of every path you review with the Read tool. Do not print the diff, or any file this brief names, through Bash (\`git diff\`, \`cat\`).`,
+		part_list(parts),
+	].join(LINE_BREAK)
+}
+
+const review_diff_parts = { body_of, part_texts, reading_block, split_text }
+
+export { review_diff_parts, type DiffParts }

package/scripts/review/review-diff-write.ts

@@ -0,0 +1,97 @@
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import path from 'node:path'
+import { git_spawn } from '#scripts/git/git-spawn'
+import { stamp_file } from '#scripts/josh/stamp-file'
+import { review_diff_parts, type DiffParts } from './review-diff-parts'
+
+// Writes the change as the parts `review-diff-parts.ts` cuts it into (joshuafolkken/kit#2963).
+//
+// **One diff per path, read the way the target line defines the change** — `git -C <root> diff
+// <base> -- <path>` for a tracked path, and the file's own content for an untracked one, which no
+// `git diff` lists. The parts are written to the temp directory keyed per checkout, the same place the
+// brief's other records live, and the directory is replaced on every brief so a part from an earlier
+// tree is never offered beside this one's.
+
+const DIRECTORY_PREFIX = 'josh-review-diff-'
+const DIRECTORY_MODE = 0o700
+const FILE_MODE = 0o600
+const PART_SUFFIX = '.diff'
+const INDEX_WIDTH = 3
+const NUL = '\0'
+const SLUG_SEPARATOR = '__'
+
+function untracked_text(root: string, relative: string): string {
+	try {
+		const content = readFileSync(path.join(root, relative), 'utf8')
+
+		if (content.includes(NUL)) return `untracked binary file ${relative}, not shown\n`
+
+		return `untracked file ${relative}, shown whole:\n${content}`
+	} catch {
+		return `${relative} is listed by the change but holds no diff and no file\n`
+	}
+}
+
+async function path_diff(root: string, base: string, relative: string): Promise<string> {
+	const diff = await git_spawn.read(['-C', root, 'diff', '--no-color', base, '--', relative])
+
+	return diff.length > 0 ? diff : untracked_text(root, relative)
+}
+
+function part_name(position: number, relative: string, index: number): string {
+	const prefix = String(position).padStart(INDEX_WIDTH, '0')
+
+	return `${prefix}-${relative.split('/').join(SLUG_SEPARATOR)}-${String(index + 1)}${PART_SUFFIX}`
+}
+
+interface PathText {
+	relative: string
+	text: string
+}
+
+function write_path(
+	directory: string,
+	position: number,
+	entry: PathText,
+	cap: number,
+): Array<string> {
+	return review_diff_parts.part_texts(entry.relative, entry.text, cap).map((part, index) => {
+		const file = path.join(directory, part_name(position, entry.relative, index))
+
+		writeFileSync(file, part, { flag: 'wx', mode: FILE_MODE })
+
+		return file
+	})
+}
+
+function fresh_directory(root: string): string {
+	const directory = stamp_file.stamp_path(DIRECTORY_PREFIX, root, '')
+
+	rmSync(directory, { recursive: true, force: true })
+	mkdirSync(directory, { mode: DIRECTORY_MODE })
+
+	return directory
+}
+
+interface DiffRequest {
+	root: string
+	base: string
+	paths: ReadonlyArray<string>
+	cap: number
+}
+
+async function write_parts(request: DiffRequest, directory?: string): Promise<DiffParts> {
+	const { root, base, paths, cap } = request
+	const texts = await Promise.all(
+		paths.map(async (relative) => ({ relative, text: await path_diff(root, base, relative) })),
+	)
+	const target = directory ?? fresh_directory(root)
+
+	return Object.fromEntries(
+		texts.map((entry, position) => [entry.relative, write_path(target, position, entry, cap)]),
+	)
+}
+
+const review_diff_write = { path_diff, write_parts }
+
+export { review_diff_write }

package/scripts/review/review-finding-ledger.ts

@@ -151,7 +151,6 @@ function has_issue_record(content: string, issue: number): boolean {
 
 const review_finding_ledger = {
 	CATEGORIES,
-	SEVERITIES,
 	category_counts,
 	finding_line,
 	has_issue_record,

package/scripts/review/review-record-cli.ts

@@ -1,6 +1,6 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
-import { parseArgs } from 'node:util'
+import { cli_flags } from '#scripts/lib/cli-flags'
 import { observation_ledger_home } from '#scripts/observations/observation-ledger-home'
 import { review_finding_ledger, type Finding } from './review-finding-ledger'
 import { review_record, type RecordVerdict } from './review-record'
@@ -71,21 +71,14 @@ function parse_findings(specs: ReadonlyArray<string>): ReadonlyArray<Finding> |
 }
 
 function parse_argv(argv: ReadonlyArray<string>): Parsed | undefined {
-	try {
-		const parsed = parseArgs({
-			args: [...argv],
-			options: OPTIONS,
-			strict: true,
-			allowPositionals: true,
-		})
-
-		return {
-			check: parsed.values.check === true,
-			issue: parsed.values.issue,
-			positionals: parsed.positionals,
-		}
-	} catch {
-		return undefined
+	const parsed = cli_flags.arguments_of(argv, OPTIONS)
+
+	if (parsed === undefined) return undefined
+
+	return {
+		check: parsed.values.check === true,
+		issue: parsed.values.issue,
+		positionals: parsed.positionals,
 	}
 }
 
@@ -186,7 +179,7 @@ async function main(argv: ReadonlyArray<string>): Promise<void> {
 	process.exitCode = await run(argv, new Date())
 }
 
-const review_record_cli = { USAGE, build_lines, parse_finding, run }
+const review_record_cli = { build_lines, parse_finding, run }
 
 if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
 

package/scripts/review/review-record.ts

@@ -55,7 +55,6 @@ function refusal_message(issue: number): string {
 }
 
 const review_record = {
-	MISSING_REASON,
 	check,
 	refusal_message,
 }

package/scripts/review/review-round2-cli.ts

@@ -77,7 +77,7 @@ async function main(argv: ReadonlyArray<string>): Promise<void> {
 	process.exitCode = await run(argv)
 }
 
-const review_round2_cli = { CLOSED_FLAG, JSON_KEY, KNOWN_FLAGS, main, parse_options, run, USAGE }
+const review_round2_cli = { CLOSED_FLAG, parse_options, run }
 
 if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
 

package/scripts/review/review-stamps.ts

@@ -102,18 +102,15 @@ function clear_round_one(target?: string): void {
 }
 
 const review_stamps = {
-	BRIEFED_PREFIX,
 	briefed_stamp,
 	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,
 }
 

package/scripts/review/review-tree.ts

@@ -3,6 +3,7 @@ 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'
+import { observation_ledger } from '#scripts/observations/observation-ledger'
 
 // The tree `josh review:brief` records: every path the change touches, and the digest of its content
 // (joshuafolkken/kit#1241).
@@ -30,8 +31,18 @@ function digest_of(root: string, relative: string): string {
 
 // 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.
+//
+// **The observation ledger is left out of the map**, for the reason `hook-gate-reuse.ts` drops it from
+// the status it reads: it is no code any check runs (joshuafolkken/kit#1756). Kept in, a review's line
+// appended after the gate moved the map, so the ledger commit `pnpm josh followup` pushes carried a
+// tree the record no longer matched — the pre-push hook re-ran the whole unit suite inside the push's
+// 120-second budget, the timed-out push was retried over the still-running suite, and the commit's
+// undo then moved the tree under both (joshuafolkken/kit#2998). Filtered here, every reader of the map
+// — the gate's record, both hooks, the brief and the round-2 fix delta — agrees on it.
 function tree_of(root: string, paths: ReadonlyArray<string>): Record<string, string> {
-	const sorted = [...paths].toSorted((left, right) => left.localeCompare(right))
+	const sorted = paths
+		.filter((relative) => !observation_ledger.is_ledger_path(relative))
+		.toSorted((left, right) => left.localeCompare(right))
 
 	return Object.fromEntries(sorted.map((relative) => [relative, digest_of(root, relative)]))
 }
@@ -43,6 +54,7 @@ function tree_of(root: string, paths: ReadonlyArray<string>): Record<string, str
 // 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`).
+// The observation ledger is dropped inside `tree_of`, above (joshuafolkken/kit#3017).
 async function read_changed_tree(
 	paths?: ReadonlyArray<string>,
 	root?: string,
@@ -53,6 +65,6 @@ async function read_changed_tree(
 	)
 }
 
-const review_tree = { ABSENT_DIGEST, digest_of, read_changed_tree, tree_of }
+const review_tree = { ABSENT_DIGEST, read_changed_tree, tree_of }
 
 export { review_tree }

package/scripts/rules/decision-oracle-stage.ts

@@ -0,0 +1,18 @@
+import { run_stage } from '#scripts/run/run-stage'
+import type { DecisionOracle } from './decision-oracle'
+
+// The stage-ladder oracle (joshuafolkken/kit#3042), kept beside the enumeration rather than inside it
+// because `decision-oracle.ts` sits at its file-size limit. Where a run on an issue starts — and whether
+// the command typed has already been reached — is computed by `run:entry` from the issue and the tree's
+// hold, so the skill's stage table points at the command rather than re-deciding it in prose. The
+// vocabulary is `run_stage`'s own start tokens, never a second copy.
+const RUN_ENTRY_ORACLE: DecisionOracle = {
+	name: 'run:entry',
+	decision:
+		'Where a run on an issue starts, and whether the typed command has already been reached',
+	args: '<N> [--to kickoff|halfrun|prrun|fullrun]',
+	vocabulary: run_stage.START_TOKENS,
+	single_source: '.claude/skills/workflow-commands/SKILL.md → §2k',
+}
+
+export { RUN_ENTRY_ORACLE }

package/scripts/rules/decision-oracle.ts

@@ -6,6 +6,7 @@
 // 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.
+import { RUN_ENTRY_ORACLE } from './decision-oracle-stage'
 
 // Paths that appear in more than one entry's `single_source` field.
 const CHAIN_RULE_MD = '.claude/skills/workflow-commands/chain-rule.md'
@@ -22,11 +23,11 @@ const BACKLOGRUN_MD = '.claude/skills/workflow-commands/backlogrun.md'
 // 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`'
+const RUN_MERGE_REFERENCE = 'docs/josh-commands-automation.md → `josh run:merge`'
+const EPIC_NEXT_REFERENCE = 'docs/josh-commands-automation.md → `josh epic:next`'
+const BACKLOG_BUDGET_REFERENCE = 'docs/josh-commands-automation.md → `josh backlog:budget`'
+const RUN_LIVENESS_REFERENCE = 'docs/josh-commands-automation.md → `josh run:liveness`'
+const AUTO_OK_NEXT_REFERENCE = 'docs/josh-commands-automation.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'
@@ -311,7 +312,7 @@ const DECISION_ORACLES: ReadonlyArray<DecisionOracle> = [
 			"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`',
+		single_source: 'docs/josh-commands-automation.md → `josh epic --reconcile`',
 	},
 	{
 		name: 'lane:list',
@@ -319,8 +320,9 @@ const DECISION_ORACLES: ReadonlyArray<DecisionOracle> = [
 			'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',
+		single_source: 'docs/josh-commands-automation.md → The `in-progress` / lane difference',
 	},
+	RUN_ENTRY_ORACLE,
 ]
 
 // Returns the command name for an oracle entry. When `command` is omitted from the entry,
@@ -339,4 +341,5 @@ const decision_oracle = {
 	get_command,
 }
 
+export type { DecisionOracle }
 export { decision_oracle }

package/scripts/rules/delivered-rules.ts

@@ -18,6 +18,7 @@ import { lane_interactive_ask } from './lane-interactive-ask'
 import { lane_park } from './lane-park'
 import { lane_switch_main } from './lane-switch-main'
 import { oracle_consulted } from './oracle-consulted'
+import { permission_guards } from './permission-guards'
 import { piped_verification } from './piped-verification'
 import { poll_loop } from './poll-loop'
 import { pre_gate_cut } from './pre-gate-cut'
@@ -143,8 +144,10 @@ const { is_issue_filing, on_bash_command } = bash_triggers
 // exemptions and the three tests that decide the second one. The three tests are spelled out rather
 // than named, because a delivery that said only "an interrupt is exempt" would hand the deciding back
 // to judgement at exactly the moment nothing else is open to read (joshuafolkken/kit#1518).
+// `WIP_CAP` is the number's single source; `wip-cap.md` states it once and a test pins the two equal.
+const WIP_CAP = 30
 const WIP_CAP_REASON =
-	"⛔ backlog WIP cap: count the target repository's open Issues before filing. With more than 30 " +
+	`⛔ backlog WIP cap: count the target repository's open Issues before filing. With more than ${String(WIP_CAP)} ` +
 	'open, close one first; nothing honestly closable means do not file. Two filings are exempt and ' +
 	'proceed while stating the overage — one the run is blocked by, and an interrupt, decided by ' +
 	'three tests rather than judgement: a verification answers wrongly, a documented workflow cannot ' +
@@ -482,6 +485,10 @@ const DELIVERED_RULES: ReadonlyArray<DeliveredRule> = [
 	git_force.ROW,
 	worktree_guard.ROW,
 	file_body.ROW,
+	// **The deny-list bypasses closed by argv and path rather than glob** (joshuafolkken/kit#2983) — an
+	// index mutation, a recursive forced `rm` or destructive `gh` call, and a protected file. Each
+	// claims a command or file no row above does and refuses every occurrence (`permission-guards.ts`).
+	...permission_guards.ROWS,
 	// **The hand-written wait loop a lane child improvises over a backgrounded command's output**
 	// (joshuafolkken/kit#2371). `early-heartbeat` refuses a bare `sleep` and stands down on any loop
 	// keyword; this is the loop it left — a `while`/`until` that sleeps between probes of an output
@@ -788,6 +795,7 @@ const delivered_rules = {
 	SHELL_BODY_REASON,
 	SWITCH_ENV_KEY,
 	THIRD_PARTY_WRITE_REASON: third_party_write.THIRD_PARTY_WRITE_REASON,
+	WIP_CAP,
 	WIP_CAP_REASON,
 	WORKTREE_MUTATION_REASON: worktree_guard.WORKTREE_MUTATION_REASON,
 	delivery,

package/scripts/rules/destructive-command.ts

@@ -0,0 +1,119 @@
+import { bash_triggers } from './bash-triggers'
+import { gh_api } from './gh-api'
+import { git_argv } from './git-argv'
+import { shell_segments } from './shell-segments'
+
+// The trigger and the delivered text behind the `destructive-command` row of `delivered-rules.ts`
+// (joshuafolkken/kit#2983): a recursive forced `rm`, and the `gh` calls that delete or close shared
+// state — none of which the deny list stopped, or stopped only in one spelling (`Bash(rm -rf *)`
+// misses `rm -fr`, `rm -r -f` and `rm --recursive --force`). The argv is read through `git-argv.ts`'s
+// wrapper cut, so `sudo rm -fr` and `env gh pr close` are seen too.
+//
+// **What is refused is the decision recorded on the Issue, not every destructive act.** `gh issue
+// close` passes — the WIP-cap procedure closes Issues legitimately — and so does removing a label from
+// an Issue (`DELETE repos/<o>/<r>/issues/<N>/labels/<name>`), which the `in-progress` and
+// `needs-decision` steps of the workflow documents issue. Every other `DELETE repos/…` is refused.
+//
+// **It fires on every occurrence**, for the reason `git-force.ts` does.
+
+const RM_COMMAND = 'rm'
+const RECURSIVE_LONG = '--recursive'
+const RECURSIVE_LETTERS = 'rR'
+const FORCE_LONG = '--force'
+const FORCE_LETTER = 'f'
+
+function has_flag(args: ReadonlyArray<string>, long: string, letters: string): boolean {
+	return args.some((argument) => argument === long || git_argv.short_cluster_has(argument, letters))
+}
+
+function is_recursive_forced_rm(segment: string): boolean {
+	const args = git_argv.arguments_of(segment, RM_COMMAND)
+
+	if (args === undefined) return false
+
+	return (
+		has_flag(args, RECURSIVE_LONG, RECURSIVE_LETTERS) && has_flag(args, FORCE_LONG, FORCE_LETTER)
+	)
+}
+
+const GH_COMMAND = 'gh'
+const REPO_GROUP = 'repo'
+const REPO_REMOVALS: ReadonlySet<string> = new Set(['delete', 'archive'])
+const REPO_EDIT = 'edit'
+const VISIBILITY_FLAG = '--visibility'
+const PR_GROUP = 'pr'
+const PR_CLOSE = 'close'
+
+// `gh repo delete` / `archive`, and `gh repo edit --visibility …`.
+function is_destructive_repo_action(action: string, args: ReadonlyArray<string>): boolean {
+	if (REPO_REMOVALS.has(action)) return true
+
+	return action === REPO_EDIT && args.some((argument) => argument.startsWith(VISIBILITY_FLAG))
+}
+
+function is_destructive_gh_command(args: ReadonlyArray<string>): boolean {
+	const [group, action = ''] = args
+
+	if (group === PR_GROUP) return action === PR_CLOSE
+
+	return group === REPO_GROUP && is_destructive_repo_action(action, args)
+}
+
+const DELETE_METHOD = 'DELETE'
+const REPOSITORY_PATH = 'repos/'
+// Removing one label from one Issue — the workflow's own `in-progress` / `needs-decision` step.
+// Anchored on the whole argument, so a label path smuggled into a field value (`-f x=repos/…/labels/a`)
+// does not exempt the real endpoint beside it.
+const ISSUE_LABEL_PATH =
+	/^['"]?\/?repos\/[^/\s'"]+\/[^/\s'"]+\/issues\/\d+\/labels\/[^/\s'"]+['"]?$/u
+
+// Judged on the call with its wrapper cut off, since `gh_api.is_gh_api` anchors on a leading `gh` and
+// would otherwise miss `env gh api -X DELETE …` that the `gh pr close` branch already sees. Every
+// argument naming a repository path must be a label removal for the call to pass.
+function is_destructive_api_call(args: ReadonlyArray<string>): boolean {
+	const call = [GH_COMMAND, ...args].join(' ')
+
+	if (!gh_api.is_gh_api(call) || gh_api.method_of(call) !== DELETE_METHOD) return false
+
+	return args.some(
+		(argument) => argument.includes(REPOSITORY_PATH) && !ISSUE_LABEL_PATH.test(argument),
+	)
+}
+
+function is_destructive_gh(segment: string): boolean {
+	const args = git_argv.arguments_of(segment, GH_COMMAND)
+
+	if (args === undefined) return false
+
+	return is_destructive_gh_command(args) || is_destructive_api_call(args)
+}
+
+function is_destructive_segment(segment: string): boolean {
+	return is_recursive_forced_rm(segment) || is_destructive_gh(segment)
+}
+
+function is_destructive_command(command: string): boolean {
+	return shell_segments.segments_of(command).some((segment) => is_destructive_segment(segment))
+}
+
+const DESTRUCTIVE_COMMAND_REASON =
+	'⛔ destructive command: a recursive forced `rm` (`rm -rf`, `rm -fr`, `rm -r -f`, `rm --recursive ' +
+	'--force`), `gh repo delete` / `archive`, `gh repo edit --visibility`, `gh pr close`, or a `gh api ' +
+	'-X DELETE repos/…` call deletes or closes something that cannot be restored, which is Tier C and ' +
+	'needs explicit current-turn user instruction (`prompts/collaboration-workflow/operating-rules.md`). ' +
+	'The `.claude/settings.json` deny list matches prefix globs, so it misses these spellings; this row ' +
+	'reads the argv instead. Remove a file or directory one path at a time without `-f`, or ask the user ' +
+	'to run the command in their own terminal. `gh issue close` and removing a label from an Issue ' +
+	'(`DELETE repos/<o>/<r>/issues/<N>/labels/<name>`) are not refused. **This rule fires on every ' +
+	'occurrence, not once per run.**'
+
+const ROW = {
+	id: 'destructive-command',
+	is_trigger: bash_triggers.on_bash_command(is_destructive_command),
+	reason: DESTRUCTIVE_COMMAND_REASON,
+	decide: (): boolean => true,
+}
+
+const destructive_command = { DESTRUCTIVE_COMMAND_REASON, ROW, is_destructive_command }
+
+export { destructive_command }

package/scripts/rules/direct-filing.ts

@@ -14,7 +14,7 @@ const DIRECT_FILING_REASON =
 	'lint and its classification labels, the depth and `route:` labels, the `## Origin` check when filing ' +
 	'into another repository, and `epic:bundle` after the create — so none of them is a step to remember. ' +
 	'When the scout prints candidates it holds the filing: read each, then reissue with `--distinct <N,…>` ' +
-	'for the ones that are separate deliverables. Reference: `docs/josh-commands.md` → "`josh issue:file`". ' +
+	'for the ones that are separate deliverables. Reference: `docs/josh-commands-automation.md` → "`josh issue:file`". ' +
 	'**This rule fires on every occurrence, not once per run.**'
 
 function is_any_filing(command: string): boolean {