@joshuafolkken/kit 1.1514.0 → 1.1784.0

package/scripts/rules/direct-issue-comment.ts

@@ -0,0 +1,117 @@
+import { bash_triggers } from './bash-triggers'
+import { direct_pr_create } from './direct-pr-create'
+import { gh_api } from './gh-api'
+import { git_argv } from './git-argv'
+import { shell_segments } from './shell-segments'
+
+// The `direct-issue-comment` row of `delivered-rules.ts`. A run's own comment has to carry
+// `RUN_MARKER`, or `issue-watch-diff.ts` reads it as a person's update: the run's review then reads as
+// briefed before the issue changed, and `josh followup` refuses the merge (joshuafolkken/kit#4221).
+// `pnpm josh issue:comment` is the one path that writes the marker, so a hand-built `gh issue comment`
+// or `gh api` write to `…/issues/<N>/comments` is refused and pointed there. It reads the argv through
+// `direct-pr-create.ts`'s cut, so a quoted mention is not a call and `bash -c '…'` still is.
+//
+// **Only the checkout's own repository**: `issue:comment` posts there and nowhere else, so the row
+// claims the spellings that target it — the `{owner}` placeholder, and `gh issue comment` with no
+// repository selector. A comment to another repository named outright is left to `third-party-write`.
+//
+// **It fires on every occurrence**, for the reason `git-force.ts` does.
+
+const ISSUE_GROUP = 'issue'
+const COMMENT_ACTION = 'comment'
+const API_SUBCOMMAND = 'api'
+const REPO_SELECTOR = /^(?:-R|--repo)(?:=|$)/u
+// One issue's (or pull request's — REST serves both as issues) comment collection. Anchored on the
+// whole endpoint argument, so `…/issues/comments/<id>` and a listing elsewhere are not read as it. The
+// number is any one segment, so `issues/$N/comments` is seen as well.
+const SEGMENT = String.raw`[^/\s'"]+`
+const QUOTE = `['"]?`
+const API_ORIGIN = String.raw`(?:https://api\.github\.com)?/?`
+const COMMENTS_PATH = new RegExp(
+	`^${QUOTE}${API_ORIGIN}repos/${SEGMENT}/${SEGMENT}/issues/${SEGMENT}/comments/?${QUOTE}$`,
+	'u',
+)
+
+function is_comment_cli_call(args: ReadonlyArray<string>): boolean {
+	if (args.some((argument) => REPO_SELECTOR.test(argument))) return false
+
+	const [group, action] = direct_pr_create.positional_words(
+		args,
+		direct_pr_create.VALUE_TAKING_FLAGS,
+	)
+
+	return group === ISSUE_GROUP && action === COMMENT_ACTION
+}
+
+function is_own_comments_endpoint(endpoint: string): boolean {
+	const owner = gh_api.repo_target(endpoint)?.owner ?? ''
+
+	return gh_api.is_owner_placeholder(owner) && COMMENTS_PATH.test(endpoint)
+}
+
+function is_comment_api_call(args: ReadonlyArray<string>): boolean {
+	const call = [direct_pr_create.GH_COMMAND, ...args].join(' ')
+
+	if (!gh_api.is_gh_api(call) || !gh_api.is_write(call)) return false
+
+	const [subcommand, endpoint = ''] = direct_pr_create.positional_words(
+		args,
+		direct_pr_create.API_VALUE_TAKING_FLAGS,
+	)
+
+	return subcommand === API_SUBCOMMAND && is_own_comments_endpoint(endpoint)
+}
+
+function is_comment_segment(segment: string): boolean {
+	const args = git_argv.arguments_of(segment, direct_pr_create.GH_COMMAND)
+
+	if (args === undefined || direct_pr_create.is_help_call(args)) return false
+
+	return is_comment_cli_call(args) || is_comment_api_call(args)
+}
+
+function is_direct_issue_comment(command: string): boolean {
+	return direct_pr_create.has_run_segment(command, is_comment_segment)
+}
+
+// `pnpm josh issue:comment` — the act that keeps the rule, segment-wise so a spelling quoted inside
+// another command's body is not read as one.
+const COMMENT_NAMES: ReadonlySet<string> = new Set(['issue:comment'])
+
+function is_josh_comment(command: string): boolean {
+	return shell_segments
+		.segments_of(command)
+		.some((segment) => shell_segments.is_josh_command(segment, COMMENT_NAMES))
+}
+
+function is_any_comment(command: string): boolean {
+	return is_direct_issue_comment(command) || is_josh_comment(command)
+}
+
+const DIRECT_ISSUE_COMMENT_REASON =
+	'⛔ direct issue comment: `gh issue comment` (or a `gh api` write to `…/issues/<N>/comments`) posts ' +
+	'without the run marker, so the run reads its own comment as a person updating the issue — the ' +
+	'review goes stale and `pnpm josh followup` refuses the merge. Post with ' +
+	'`pnpm josh issue:comment <N> --body-file <path>` instead (`shell-body.md`). ' +
+	'**This rule fires on every occurrence, not once per run.**'
+
+const ROW = {
+	id: 'direct-issue-comment',
+	is_trigger: bash_triggers.on_bash_command(is_direct_issue_comment),
+	reason: DIRECT_ISSUE_COMMENT_REASON,
+	decide: (): boolean => true,
+	keeps: bash_triggers.on_bash_command(is_josh_comment),
+	reaches: bash_triggers.on_bash_command(is_any_comment),
+	about: {
+		title: 'Direct issue comment',
+		topic: '`shell-body.md`',
+		fires:
+			"a comment to the checkout's own repository outside `josh issue:comment` (`gh issue comment` with no `--repo`, or a `gh api` write to `repos/{owner}/<r>/issues/<N>/comments`); it points at `pnpm josh issue:comment`. Every occurrence",
+		quiet:
+			'`pnpm josh issue:comment`, or reading the comments — the path that writes the run marker',
+	},
+}
+
+const direct_issue_comment = { DIRECT_ISSUE_COMMENT_REASON, ROW, is_direct_issue_comment }
+
+export { direct_issue_comment }

package/scripts/rules/direct-pr-create.ts

@@ -17,6 +17,7 @@ const PR_GROUP = 'pr'
 // `new` is gh's own alias for `pr create`.
 const PR_CREATE_ACTIONS: ReadonlySet<string> = new Set(['create', 'new'])
 const FLAG_PREFIX = '-'
+const HELP_FLAGS: ReadonlySet<string> = new Set(['-h', '--help'])
 // The repository selector gh accepts before `pr` or between `pr` and its action; with no `=` it
 // swallows the next word, so that word is not read as the group or the action.
 const VALUE_TAKING_FLAGS: ReadonlySet<string> = new Set(['-R', '--repo'])
@@ -80,16 +81,64 @@ function is_pr_create_cli_call(args: ReadonlyArray<string>): boolean {
 	return group === PR_GROUP && PR_CREATE_ACTIONS.has(action)
 }
 
+// A help call prints the usage and creates nothing. A help flag right after another flag may be that
+// flag's value (`--title -h`), so it is not read as one — a boolean flag before it errs toward refusal.
+function is_help_call(args: ReadonlyArray<string>): boolean {
+	return args.some(
+		(argument, index) =>
+			HELP_FLAGS.has(argument) && !(args[index - 1] ?? '').startsWith(FLAG_PREFIX),
+	)
+}
+
 function is_pr_create_segment(segment: string): boolean {
 	const args = git_argv.arguments_of(segment, GH_COMMAND)
 
-	if (args === undefined) return false
+	if (args === undefined || is_help_call(args)) return false
 
 	return is_pr_create_cli_call(args) || is_pr_create_api_call(args)
 }
 
+// Quoted text the shell still runs: a command substitution, or the string `sh -c` (its `-c` alone or
+// in a cluster such as `-lc`, after any other flags), `ssh` or `eval` executes. `ssh` and `eval` count
+// only as the segment's program, so `grep -E "ssh|gh pr create"` stays one quoted pattern.
+const RUNS_QUOTED_TEXT = /\$\(|`/u
+const QUOTED_TEXT_RUNNERS: ReadonlySet<string> = new Set(['ssh', 'eval'])
+const SHELL_DASH_C = /\b(?:ba|da|k|z)?sh\s+(?:-\S+\s+)*-[A-Za-z]*c\b/u
+// A `#` comment hides its apostrophe from the shell but not from the quote pairing, so a multi-line
+// segment holding one may be lines the pairing joined (`# don't` … `'`) rather than one quoted span.
+const COMMENT_MARKER = /(?:^|\s)#/mu
+const LINE_BREAK = '\n'
+
+function is_run_by_shell(segment: string): boolean {
+	if (RUNS_QUOTED_TEXT.test(segment) || SHELL_DASH_C.test(segment)) return true
+
+	return QUOTED_TEXT_RUNNERS.has(git_argv.program_of(segment)?.name ?? '')
+}
+
+function is_runs_quoted_text(segment: string): boolean {
+	if (is_run_by_shell(segment)) return true
+
+	return segment.includes(LINE_BREAK) && COMMENT_MARKER.test(segment)
+}
+
+// A segment whose quotes still run keeps the plain cut, so `bash -c 'git push && gh pr create --fill'`
+// is refused as it was before the quote-aware cut.
+function judged_segments(segment: string): Array<string> {
+	return is_runs_quoted_text(segment) ? shell_segments.commands_of(segment) : [segment]
+}
+
+// The cut is quote-aware, so `grep -E "a|gh pr create|b"` stays one `grep` call rather than yielding
+// a `gh pr create` segment from inside its pattern (joshuafolkken/kit#4091). Shared with the
+// `direct-issue-comment` row, which judges a `gh` call by the same cut.
+function has_run_segment(command: string, is_match: (segment: string) => boolean): boolean {
+	return shell_segments
+		.quote_aware_commands_of(command)
+		.flatMap((segment) => judged_segments(segment))
+		.some((segment) => is_match(segment))
+}
+
 function is_direct_pr_create(command: string): boolean {
-	return shell_segments.segments_of(command).some((segment) => is_pr_create_segment(segment))
+	return has_run_segment(command, is_pr_create_segment)
 }
 
 const DIRECT_PR_CREATE_REASON =
@@ -103,8 +152,25 @@ const ROW = {
 	is_trigger: bash_triggers.on_bash_command(is_direct_pr_create),
 	reason: DIRECT_PR_CREATE_REASON,
 	decide: (): boolean => true,
+	about: {
+		title: 'Direct PR creation',
+		topic: '`CLAUDE.md` → Git Rules',
+		fires:
+			'`gh pr create`, or a `gh api` write to `repos/<o>/<r>/pulls`; it points at `pnpm josh pr`. Every occurrence',
+		quiet: '`pnpm josh pr`, or reading a PR — the path that writes `closes #N`',
+	},
 }
 
-const direct_pr_create = { DIRECT_PR_CREATE_REASON, ROW, is_direct_pr_create }
+const direct_pr_create = {
+	API_VALUE_TAKING_FLAGS,
+	DIRECT_PR_CREATE_REASON,
+	GH_COMMAND,
+	ROW,
+	VALUE_TAKING_FLAGS,
+	has_run_segment,
+	is_direct_pr_create,
+	is_help_call,
+	positional_words,
+}
 
 export { direct_pr_create }

package/scripts/rules/early-heartbeat.ts

@@ -1,4 +1,5 @@
 import { hook_decision, type GuardRun } from '#scripts/josh/hook-decision'
+import { MS_PER_SECOND } from '#scripts/lib/timeouts'
 import { run_progress } from '#scripts/run/progress/run-progress'
 import { run_progress_clock } from '#scripts/run/progress/run-progress-clock'
 import { run_progress_config } from '#scripts/run/progress/run-progress-config'
@@ -105,7 +106,7 @@ function wait_duration_ms(command: string): number {
 		NO_SECONDS,
 	)
 
-	return seconds * run_progress.MS_PER_SECOND
+	return seconds * MS_PER_SECOND
 }
 
 function is_armed(target: string, now_ms: number): boolean {

package/scripts/rules/file-body.ts

@@ -184,6 +184,13 @@ const ROW = {
 	is_trigger: bash_triggers.on_bash_command((command: string) => carries_a_file_body(command)),
 	reason: FILE_BODY_REASON,
 	decide: (): boolean => true,
+	about: {
+		title: 'No file body on the shell',
+		topic: '`file-edits.md`',
+		fires:
+			'a heredoc write to an existing file, a writing `node -e` / interpreter heredoc, or `perl -0pi -e`. Every occurrence',
+		quiet: 'a new file, a read-only heredoc, or a short `sed -i`',
+	},
 }
 
 const file_body = {

package/scripts/rules/filing-cap.ts

@@ -117,6 +117,13 @@ const ROW = {
 	is_trigger: bash_triggers.on_bash_command(bash_triggers.is_issue_filing),
 	reason: FILING_CAP_REASON,
 	decide,
+	about: {
+		title: 'The 10-Issue filing cap per run',
+		topic: '`.claude/skills/workflow-commands/prerequisite.md`, `observation-filing.md`',
+		fires:
+			'the 11th `pnpm josh issue:file` in a run that already has 10 filings not refused; failed calls do not count. Every occurrence',
+		quiet: 'fewer than 10 filings not refused',
+	},
 }
 
 const filing_cap = {

package/scripts/rules/git-argv.ts

@@ -13,8 +13,9 @@
 
 // The wrapper words that may stand in front of `git`, the same ones `run-tail-rule.ts` skips in front of
 // `josh`: environment assignments, the package-manager launchers, `sudo`, `env`, and an opening
-// subshell parenthesis. Left in, `sudo git push --force`, `env git commit` and `(git push -f)` are
-// silently not a git command.
+// subshell parenthesis — plus `time` with its flags, read here only. Left in, `sudo git push --force`,
+// `env git commit` and `(git push -f)` are silently not a git command, and
+// `/usr/bin/time -p pnpm exec eslint .` is not an `eslint` run (joshuafolkken/kit#4356).
 const ENV_ASSIGNMENT = /^[A-Za-z_]\w*=/u
 const WRAPPER_WORDS: ReadonlySet<string> = new Set([
 	'pnpm',
@@ -24,7 +25,13 @@ const WRAPPER_WORDS: ReadonlySet<string> = new Set([
 	'sudo',
 	'command',
 	'env',
+	'time',
 ])
+// The wrappers whose own flags stand between them and the program (`time -p`), skipped with them.
+const FLAGGED_WRAPPERS: ReadonlySet<string> = new Set(['time'])
+// Their flags that consume a separate following value (`time -o <file>`, `time -f <format>`), so the
+// value is not read as the program.
+const WRAPPER_VALUE_FLAGS: ReadonlySet<string> = new Set(['-o', '-f', '--output', '--format'])
 const SUBSHELL_OPEN = '('
 
 // The git global options that consume a **separate** following token as their value, so the parser
@@ -50,18 +57,50 @@ interface GitCall {
 	args: ReadonlyArray<string>
 }
 
-// Split on whitespace alone. A refspec such as `:branch` and a short cluster such as `-uf` are single
-// tokens with no inner spaces, and neither force detection nor stash detection needs to look inside a
-// quoted argument — the one place a quote matters (a commit message) belongs to a subcommand neither
-// caller judges.
-const WHITESPACE = /\s+/u
+// Split on whitespace outside quotes, keeping each quote in its word. A quoted span is one word, so
+// `c='x; gh pr create'` is one environment assignment rather than an assignment followed by a `gh`
+// call (joshuafolkken/kit#4091); a backslash-escaped character outside quotes opens no span, and a
+// quote left unclosed is read as a plain character.
+const WORD = /(?:\\.|'[^']*'|"(?:\\.|[^"\\])*"|\S)+/gsu
 
 function words_of(segment: string): Array<string> {
-	return segment.split(WHITESPACE).filter((word) => word !== '')
+	return segment.match(WORD) ?? []
+}
+
+const PATH_SEPARATOR = '/'
+
+// The program a word launches, read off the path's last component, so `/usr/bin/git` is `git`.
+function program_name(word: string): string {
+	return word.slice(word.lastIndexOf(PATH_SEPARATOR) + NEXT)
 }
 
 function is_wrapper_token(word: string): boolean {
-	return word === SUBSHELL_OPEN || ENV_ASSIGNMENT.test(word) || WRAPPER_WORDS.has(word)
+	return (
+		word === SUBSHELL_OPEN || ENV_ASSIGNMENT.test(word) || WRAPPER_WORDS.has(program_name(word))
+	)
+}
+
+// The words a flagged wrapper's flag spans, its value included; 0 when the word is not a flag.
+function wrapper_flag_width(word = ''): number {
+	if (!word.startsWith(FLAG_PREFIX)) return 0
+
+	return WRAPPER_VALUE_FLAGS.has(word) ? AFTER_VALUE : NEXT
+}
+
+// The index after the wrapper word at `index`, past its own flags when it is a flagged wrapper.
+function after_wrapper_word(words: ReadonlyArray<string>, index: number): number {
+	let next = index + NEXT
+
+	if (!FLAGGED_WRAPPERS.has(program_name(words[index] ?? ''))) return next
+
+	let width = wrapper_flag_width(words[next])
+
+	while (width > 0) {
+		next += width
+		width = wrapper_flag_width(words[next])
+	}
+
+	return next
 }
 
 // Skip the wrapper: environment assignments, a launcher word, and a leading subshell parenthesis. The
@@ -69,7 +108,9 @@ function is_wrapper_token(word: string): boolean {
 function after_wrapper(words: ReadonlyArray<string>): number {
 	let index = 0
 
-	while (index < words.length && is_wrapper_token(words[index] ?? '')) index += NEXT
+	while (index < words.length && is_wrapper_token(words[index] ?? '')) {
+		index = after_wrapper_word(words, index)
+	}
 
 	return index
 }
@@ -94,14 +135,30 @@ function after_globals(words: ReadonlyArray<string>, start: number): number {
 	return index
 }
 
+interface ProgramCall {
+	name: string
+	args: Array<string>
+}
+
+// The program the segment launches once the wrapper is skipped, with the words after it, or
+// `undefined` for a segment with no program word.
+function program_of(segment: string): ProgramCall | undefined {
+	const words = words_of(segment)
+	const command_index = after_wrapper(words)
+	const word = words[command_index]
+
+	if (word === undefined) return undefined
+
+	return { name: program_name(word), args: words.slice(command_index + NEXT) }
+}
+
 // The words after `command` once the wrapper is skipped, or `undefined` when the segment does not
 // invoke it. `gh` and `rm` are judged by the same wrapper cut as `git`, so
 // `env gh pr close` and `sudo rm -rf` are read as the calls they are.
 function arguments_of(segment: string, command: string): Array<string> | undefined {
-	const words = words_of(segment)
-	const command_index = after_wrapper(words)
+	const call = program_of(segment)
 
-	return words[command_index] === command ? words.slice(command_index + NEXT) : undefined
+	return call?.name === command ? call.args : undefined
 }
 
 // The subcommand and the arguments after it, or `undefined` when the segment is not a git invocation.
@@ -135,6 +192,7 @@ function short_cluster_has(token: string, letters: string): boolean {
 	return false
 }
 
-const git_argv = { arguments_of, parse, short_cluster_has }
+const git_argv = { arguments_of, parse, program_of, short_cluster_has }
 
 export { git_argv }
+export type { ProgramCall }

package/scripts/rules/git-force.ts

@@ -24,6 +24,9 @@ import { shell_segments } from './shell-segments'
 // deletes (`:branch`). Both open the refspec with a character the deny list cannot match as a literal.
 const FORCE_LONG_PREFIX = '--force'
 const DELETE_LONG = '--delete'
+// `--mirror` force-updates every remote ref to the local set and deletes the rest; `--prune` deletes
+// every remote branch with no local counterpart. Both are a delete with no refspec to read.
+const DESTRUCTIVE_PUSH_LONG: ReadonlySet<string> = new Set([DELETE_LONG, '--mirror', '--prune'])
 const PUSH_SHORT_LETTERS = 'fd'
 const FORCE_OR_DELETE_REFSPEC = /^[+:]/u
 
@@ -31,7 +34,7 @@ function is_force_or_delete_push(args: ReadonlyArray<string>): boolean {
 	return args.some(
 		(argument) =>
 			argument.startsWith(FORCE_LONG_PREFIX) ||
-			argument === DELETE_LONG ||
+			DESTRUCTIVE_PUSH_LONG.has(argument) ||
 			git_argv.short_cluster_has(argument, PUSH_SHORT_LETTERS) ||
 			FORCE_OR_DELETE_REFSPEC.test(argument),
 	)
@@ -66,7 +69,7 @@ function is_destructive_segment(segment: string): boolean {
 // quoted inside another command's argument is read as the write it is not, exactly as every other
 // trigger in this directory reads its own.
 function is_force_or_delete(command: string): boolean {
-	return shell_segments.segments_of(command).some((segment) => is_destructive_segment(segment))
+	return shell_segments.commands_of(command).some((segment) => is_destructive_segment(segment))
 }
 
 // The instruction in the shape a refusal can carry: what the command does and the one route left. The
@@ -87,6 +90,13 @@ const ROW = {
 	is_trigger: bash_triggers.on_bash_command(is_force_or_delete),
 	reason: GIT_FORCE_REASON,
 	decide: (): boolean => true,
+	about: {
+		title: 'Force push / branch delete',
+		topic: '`operating-rules.md`',
+		fires:
+			'a `git push` / `git branch` read as force (`--force` / `-f` / `-uf` …) or delete (`--delete` / `-d` / `-D` / `:branch`) in any spelling. Every occurrence',
+		quiet: 'a plain `git push` / `git branch`',
+	},
 }
 
 const git_force = {

package/scripts/rules/guard-remedy.ts

@@ -52,7 +52,9 @@ const GUARD_REMEDIES: Readonly<Record<string, GuardRemedy>> = {
 	'raw-field-body': judgment('the body moves to a file the call does not name'),
 	'rule-body': judgment('a trigger-plus-pointer line is written, not derived'),
 	'direct-filing': judgment(ANOTHER_COMMAND),
+	'direct-issue-comment': judgment(ANOTHER_COMMAND),
 	'direct-pr-create': judgment(ANOTHER_COMMAND),
+	'pr-merge': judgment(ANOTHER_COMMAND),
 	'josh-git-bare': judgment(ANOTHER_COMMAND),
 	'run-tail': judgment(ANOTHER_COMMAND),
 	'pre-gate-cut': judgment(ANOTHER_COMMAND),
@@ -65,6 +67,8 @@ const GUARD_REMEDIES: Readonly<Record<string, GuardRemedy>> = {
 	'agent-model': judgment("which model fits the unit is the author's call"),
 	'lane-carry-conflict': judgment(ANOTHER_COMMAND),
 	'lane-switch-main': judgment(ANOTHER_COMMAND),
+	'lane-direct-tool': judgment(ANOTHER_COMMAND),
+	'timed-rerun': judgment(ANOTHER_COMMAND),
 	'oracle-consulted': judgment(ANOTHER_COMMAND),
 	'test-declared': judgment(ANOTHER_COMMAND),
 	batching: judgment(ANOTHER_COMMAND),

package/scripts/rules/implementation-cut-verdict.ts

@@ -11,7 +11,7 @@ import { z } from 'zod'
 // threshold crossing rather than once per run, that read can no longer be paid on every edit, so the
 // verdict is cached beside the instant it was read and a burst of edits shares one read.
 //
-// **An in-memory memo cannot span two edits.** `pnpm josh rule:guard` runs as a fresh process on each
+// **An in-memory memo cannot span two edits.** `pnpm josh pretool:guard` runs as a fresh process on each
 // `PreToolUse`, so the cache is a per-checkout stamp rather than a module variable — the same handoff
 // shape the refusal stamp itself uses.
 //

package/scripts/rules/implementation-cut.ts

@@ -1,11 +1,11 @@
 import { agent_session_role } from '#scripts/agent/agent-session-role'
 import { CONTEXT_CUT_THRESHOLD } from '#scripts/cost-runtime/context-cut-threshold'
 import { cost_cli, type CostVerdict } from '#scripts/cost-runtime/cost-cli'
-import { cost_format } from '#scripts/cost-runtime/cost-format'
 import { cost_verdict } from '#scripts/cost-runtime/cost-verdict'
 import type { GuardRun } from '#scripts/josh/hook-decision'
 import { lane_child_marker, type MarkerSource } from '#scripts/lane/lane-child-marker'
 import { lane_paths } from '#scripts/lane/lane-paths'
+import { figure_format } from '#scripts/lib/figure-format'
 import { run_cut, type RunCut } from '#scripts/run/cut/run-cut'
 import { run_cut_decline } from '#scripts/run/cut/run-cut-decline'
 import { run_cut_handoff } from '#scripts/run/cut/run-cut-handoff'
@@ -170,8 +170,8 @@ function is_over_threshold_edit(
 
 // **The threshold in the refusal text is assembled from the constant, never spelled**.
 // A spelled literal is left behind when the shared threshold moves, telling agents the wrong number;
-// building it from `CONTEXT_CUT_THRESHOLD` keeps the two from drifting. `cost_format.format_tokens` renders it the way every cost report does.
-const THRESHOLD_TEXT = `${cost_format.format_tokens(CONTEXT_CUT_THRESHOLD)}-token`
+// building it from `CONTEXT_CUT_THRESHOLD` keeps the two from drifting. `figure_format.format_tokens` renders it the way every cost report does.
+const THRESHOLD_TEXT = `${figure_format.format_tokens(CONTEXT_CUT_THRESHOLD)}-token`
 
 // The instruction in the shape a refusal can carry: the handoff in the format the parser reads, the
 // cut, and the one verdict that ends the turn — `cut` is the only one, so a run told merely to "take
@@ -224,6 +224,14 @@ const ROW = {
 		'⛔ implementation-phase cut: this checkout is a lane dispatched',
 		"⛔ implementation-phase cut: this run's context crossed the",
 	],
+	about: {
+		title: 'The implementation-phase cut',
+		topic:
+			'`.claude/skills/workflow-commands/pre-gate-cut.md` → "It is a guard, fired at the edit that crosses the threshold"',
+		fires:
+			'an `Edit` / `Write` by an uncut lane child whose recent context is over the `pnpm josh cost --cut` threshold; it hands over `pnpm josh run:cut --impl <N> --handoff <path>`. At each threshold crossing',
+		quiet: 'not a lane child, a non-editing tool, already cut, or under the threshold',
+	},
 }
 
 const implementation_cut = {

package/scripts/rules/index-guard.ts

@@ -46,7 +46,7 @@ function is_index_segment(segment: string): boolean {
 }
 
 function is_index_mutation(command: string): boolean {
-	return shell_segments.segments_of(command).some((segment) => is_index_segment(segment))
+	return shell_segments.commands_of(command).some((segment) => is_index_segment(segment))
 }
 
 const INDEX_MUTATION_REASON =
@@ -61,6 +61,13 @@ const ROW = {
 	is_trigger: bash_triggers.on_bash_command(is_index_mutation),
 	reason: INDEX_MUTATION_REASON,
 	decide: (): boolean => true,
+	about: {
+		title: 'Index mutation',
+		topic: '`operating-rules.md`',
+		fires:
+			'`git add` / `commit` / `reset` / `rm` / `mv` / `restore --staged` in any spelling. Every occurrence',
+		quiet: '`pnpm josh git` — the approved commit flow',
+	},
 }
 
 const index_guard = { INDEX_MUTATION_REASON, ROW, is_index_mutation }

package/scripts/rules/issue-comments.ts

@@ -21,7 +21,7 @@ const ISSUE_VIEW_COMMAND = new RegExp(String.raw`^gh\s+${gh_api.GH_FLAGS}issue\s
 // (`…/issues`) and every sub-resource under it (`…/issues/1319/comments`) are left alone.
 const ISSUE_BODY_PATH = /repos\/[^\s'"]*\/issues\/\d+(?=$|["'\s])/u
 // **A write to that path is not a read of it**, which is why the body read below asks `gh_api.is_read`:
-// `gh api` sends POST as soon as any field flag appears, and `kickoff` PATCHes `…/issues/<N>` to
+// `gh api` sends POST as soon as any field flag appears, and a run PATCHes `…/issues/<N>` to
 // normalize a title and to fill a blank body — so without the read check the delivery would be spent
 // refusing a write, and the genuine body read later in the same run would never be guarded.
 // A segment that fetches comments: the flag, a `comments` field in a `--json` projection, or the
@@ -164,6 +164,14 @@ const ROW = {
 	rewrite_note: COMMENTS_NOTE,
 	// The opening the reason carried before it led with the command.
 	former_reasons: ["⛔ an Issue's comments are part of the Issue: read them before implementing"],
+	about: {
+		title: 'Reading Issue comments',
+		topic: '`issue-comments.md`',
+		fires:
+			'a `Bash` that reads only the Issue body (`gh issue view <N>`, or a GET ending in `…/issues/<N>`). Refused until it is re-read with the comments',
+		quiet:
+			'no Issue read, or a read with `--comments` / `--json comments` / `…/comments` from the start',
+	},
 }
 
 const issue_comments = {

package/scripts/rules/josh-git-bare.ts

@@ -66,6 +66,13 @@ const ROW = {
 	is_trigger: bash_triggers.on_bash_command(is_bare_josh_git),
 	reason: JOSH_GIT_BARE_REASON,
 	decide: (): boolean => true,
+	about: {
+		title: 'Bare `pnpm josh git`',
+		topic: '`CLAUDE.md` → Git Rules',
+		fires:
+			'`pnpm josh git` without `-y`, whose staging prompt cancels with no TTY. Every occurrence',
+		quiet: '`pnpm josh git -y`',
+	},
 }
 
 const josh_git_bare = {