@joshuafolkken/kit 1.1514.0 → 1.2114.0

package/scripts/rules/delivered-rules.ts

@@ -1,21 +1,27 @@
 import { investigation_reads } from '#scripts/delegation/investigation-reads'
+import { will_refuse as will_batch_refuse } from '#scripts/hooks/batch-guard'
 import { hook_decision, type GuardRun, type TranscriptGuardSpec } from '#scripts/josh/hook-decision'
-import { lane_guard_policy } from '#scripts/lane/lane-guard-policy'
 import { time_batch_guard, type GuardedCall } from '#scripts/time-runtime/time-batch-guard'
 import { agent_model } from './agent-model'
 import { bash_triggers } from './bash-triggers'
+import { concise_reply } from './concise-reply'
+import { credential_body } from './credential-body'
 import { direct_filing } from './direct-filing'
+import { direct_issue_comment } from './direct-issue-comment'
+import { direct_issue_read } from './direct-issue-read'
 import { early_heartbeat } from './early-heartbeat'
-import { file_body } from './file-body'
-import { filing_cap } from './filing-cap'
+import { file_edit_rows } from './file-edit-rows'
 import { git_force } from './git-force'
 import { implementation_cut } from './implementation-cut'
+import { investigator_foreground } from './investigator-foreground'
 import { issue_comments } from './issue-comments'
 import { josh_git_bare } from './josh-git-bare'
 import { lane_background } from './lane-background'
 import { lane_carry_conflict } from './lane-carry-conflict'
+import { lane_direct_tool } from './lane-direct-tool'
 import { lane_interactive_ask } from './lane-interactive-ask'
 import { lane_park } from './lane-park'
+import { lane_spilled_read } from './lane-spilled-read'
 import { lane_split_park } from './lane-split-park'
 import { lane_switch_main } from './lane-switch-main'
 import { oracle_consulted } from './oracle-consulted'
@@ -24,11 +30,14 @@ import { piped_verification } from './piped-verification'
 import { poll_loop } from './poll-loop'
 import { pre_gate_cut } from './pre-gate-cut'
 import { raw_field_body } from './raw-field-body'
+import { reviewer_foreground } from './reviewer-foreground'
+import { round_one_check_related } from './round-one-check-related'
 import { rule_body_guard } from './rule-body-guard'
 import { run_tail_rule } from './run-tail-rule'
 import { shell_body_trigger } from './shell-body-trigger'
 import { test_declared_commit } from './test-declared-commit'
 import { third_party_write } from './third-party-write'
+import { timed_rerun } from './timed-rerun'
 import { worktree_guard } from './worktree-guard'
 
 // The rules delivered by a `PreToolUse` refusal at the moment they bind, rather than carried resident
@@ -50,15 +59,32 @@ type CallTest = (
 // The tail is read lazily: most calls no rewrite applies to never need it.
 type CallRewrite = (call: GuardedCall, tail: () => string) => Record<string, unknown> | undefined
 
+// The human-readable side `pnpm josh rule:list` renders, carried on the row so a rule is one entry.
+interface RuleAbout {
+	title: string
+	// The single source of the rule's procedure.
+	topic: string
+	fires: string
+	// The silent turn — it matches the state in which the rule is already kept.
+	quiet: string
+	// The hook command that delivers it; absent reads as `PRETOOL_GUARD`.
+	entry?: string
+}
+
+// Every row here — batching and investigation included — is delivered by the one `PreToolUse`
+// process (`scripts/hooks/pretool-guard.ts`).
+const PRETOOL_GUARD = 'pnpm josh pretool:guard'
+
 // `id` keys the rule's own refusal record, so one rule firing never spends another's budget.
 interface DeliveredRule {
 	id: string
 	is_trigger: (call: GuardedCall) => boolean
 	// The only text that reaches the model: the instruction and the pointer.
 	reason: string
+	about: RuleAbout
 	// A stand-down when an earlier act on the tail already satisfied the rule; checked first, so a
-	// satisfied call spends no record.
-	already_satisfied?: (tail: string, call: GuardedCall) => boolean
+	// satisfied call spends no record. `run` names the session, for a stand-down that outlives the tail.
+	already_satisfied?: (tail: string, call: GuardedCall, run: GuardRun) => boolean
 	// For a rule that binds on every occurrence instead of once per run. `at_ms` is this row's own last
 	// refusal, so an immediate reissue can be let through.
 	decide?: (call: GuardedCall, run: GuardRun, can_record: boolean, at_ms: number) => boolean
@@ -76,9 +102,12 @@ interface DeliveredRule {
 	// Openings the reason had before it was reworded, so `rule-value.ts` still credits a refusal
 	// delivered with the old text while those transcripts remain in its window.
 	former_reasons?: ReadonlyArray<string>
+	// The reasons a Stop hook sends a turn back with on this row's behalf, so `rule-value.ts` counts
+	// that block as this row's refusal.
+	stop_reasons?: ReadonlyArray<string>
 }
 
-// Scored but possibly delivered by its own binary (batching, investigation) — joining `DELIVERED_RULES`
+// Scored but possibly delivered by its own guard inside `pretool-guard.ts` (batching, investigation) — joining `DELIVERED_RULES`
 // would refuse one violation twice — so `is_trigger` is optional here.
 type MeasuredRule = Omit<DeliveredRule, 'is_trigger'> & {
 	is_trigger?: DeliveredRule['is_trigger']
@@ -95,10 +124,17 @@ const { SHELL_BODY_REASON, carries_a_body, is_shell_evaluated_body, keeps_body_s
 const DELIVERED_RULES: ReadonlyArray<DeliveredRule> = [
 	// First: a third-party write is stopped before the first-party filing rows count anything.
 	third_party_write.ROW,
-	// The direct call only; `filing-cap` below triggers on `issue:file`. The WIP cap and the fold
-	// question are `issue:file`'s own steps, so no row gates them.
+	// Before every first-party row: a credential is refused whatever the call's other faults, and the
+	// commands those rows point at run the same scan in-process.
+	credential_body.ROW,
+	// The direct call only. The filing cap, the WIP cap and the fold question are `issue:file`'s own
+	// steps, so no row gates them.
 	direct_filing.ROW,
-	filing_cap.ROW,
+	// Before the body rows: a comment posted by hand is refused whatever its body, and the command it
+	// points at takes the body by path, so the body rows have nothing left to say.
+	direct_issue_comment.ROW,
+	// Before `issue-comments`, whose rewrite would add the unfiltered comments to the same read.
+	direct_issue_read.ROW,
 	issue_comments.ROW,
 	{
 		id: 'shell-body',
@@ -106,8 +142,17 @@ const DELIVERED_RULES: ReadonlyArray<DeliveredRule> = [
 		reason: SHELL_BODY_REASON,
 		keeps: on_bash_command(keeps_body_safe),
 		reaches: on_bash_command(carries_a_body),
+		about: {
+			title: 'No body on the shell',
+			topic: '`shell-body.md`',
+			fires:
+				'a double-quoted body value (`-f body="…"` / `-f "body=…"` / `--body "…"` / `--notify-message "…"`) carrying a backtick or `$`',
+			quiet: 'the shell does not evaluate the body',
+		},
 	},
 	raw_field_body.ROW,
+	// Before `piped-verification`, whose rewrite would run under `pipefail` a check that must not run.
+	round_one_check_related.ROW,
 	{
 		id: 'piped-verification',
 		is_trigger: on_bash_command(piped_verification.is_masked_verification),
@@ -117,6 +162,13 @@ const DELIVERED_RULES: ReadonlyArray<DeliveredRule> = [
 		// A masking whose filter reads to the end is rewritten under `pipefail`, never refused.
 		rewrite: piped_verification.pipefail_input,
 		rewrite_note: piped_verification.PIPEFAIL_NOTE,
+		about: {
+			title: 'Piped verification',
+			topic: '`output-bounds.md`',
+			fires:
+				'a pass/fail josh check (`gate` / `check*` / `lint*` / `cspell*` / `test*` / `eval` / `overrides` / `ranges`) in front of a pipe — rewritten under `set -o pipefail` when every filter reads to the end (`tail`, a full-reading `grep`, `cut`, `sort`, `uniq`, `wc`, `tee`, an `awk` / `sed` that cannot exit early and carries no `<` / `>` / `&`), refused otherwise',
+			quiet: 'the exit code reaches the caller — a failure reads as a failure',
+		},
 	},
 	{
 		id: 'early-heartbeat',
@@ -125,6 +177,14 @@ const DELIVERED_RULES: ReadonlyArray<DeliveredRule> = [
 		decide: early_heartbeat.decide,
 		keeps: on_bash_command(early_heartbeat.is_progress_watch),
 		reaches: on_bash_command(early_heartbeat.waits_for_progress),
+		about: {
+			title: 'Early progress report',
+			topic:
+				'`.claude/skills/workflow-commands/progress-watcher.md` → "Progress while the run is quiet"',
+			fires:
+				'a `Bash` whose only purpose is waiting (`sleep` alone, or `echo` / `:` / `date`) while a timer is live or before the interval. Every occurrence',
+			quiet: 'no hand-made wait timer — `run:progress` holds the one clock',
+		},
 	},
 	// Before `run-tail`: whether to commit at all is decided before how to push.
 	test_declared_commit.ROW,
@@ -138,6 +198,13 @@ const DELIVERED_RULES: ReadonlyArray<DeliveredRule> = [
 		decide: run_tail_rule.decide,
 		keeps: run_tail_rule.is_backgrounded_push_step,
 		reaches: run_tail_rule.is_push_step_call,
+		about: {
+			title: 'Idle run tail',
+			topic: '`.claude/skills/workflow-commands/background-commands.md`',
+			fires:
+				'`pnpm josh git -y` (`josh g`, `--yes` alike) issued in the **foreground**. Every occurrence',
+			quiet: 'issued in the background — its completion resumes the run',
+		},
 	},
 	// Reads the lane name and the cut record. Once per run, not `decide`: taking the cut ends the
 	// process, and the verdicts that leave a run at the gate all need the reissue through. `reaches`
@@ -149,26 +216,43 @@ const DELIVERED_RULES: ReadonlyArray<DeliveredRule> = [
 		reason: pre_gate_cut.PRE_GATE_CUT_REASON,
 		keeps: on_bash_command(pre_gate_cut.takes_the_cut),
 		reaches: pre_gate_cut.reaches_the_pre_gate_boundary,
+		about: {
+			title: 'The cut before the gate',
+			topic: '`.claude/skills/workflow-commands/pre-gate-cut.md`',
+			fires:
+				'`pnpm josh gate` (`josh ga`) in a lane work tree whose `JOSH_LANE_CHILD` names the Issue and has no cut record',
+			quiet: 'outside a lane, no marker (a person in the lane), or already cut',
+		},
 	},
 	// A split child's park is refused before `lane-park` sees it.
 	lane_split_park.ROW,
 	lane_park.ROW,
 	lane_interactive_ask.ROW,
 	agent_model.ROW,
+	investigator_foreground.ROW,
+	reviewer_foreground.ROW,
 	lane_carry_conflict.ROW,
 	lane_switch_main.ROW,
+	// Before `lane-direct-tool`, its one overlap (a timed tool in a lane): the record is the right first
+	// act, and `lane-direct-tool` delivers on the reissue of a `time`-prefixed tool.
+	timed_rerun.ROW,
+	lane_direct_tool.ROW,
+	lane_spilled_read.ROW,
 	// Disjoint from `run-tail` by the `-y` flag.
 	josh_git_bare.ROW,
 	// The Bash-string gaps the deny glob cannot express, read by argv; `delivered-rules-bash.test.ts`
 	// pins that no two rows claim one command.
 	git_force.ROW,
 	worktree_guard.ROW,
-	file_body.ROW,
+	...file_edit_rows.SHELL_ROWS,
 	...permission_guards.ROWS,
 	poll_loop.ROW,
 	// Before `rule-body`, its one overlap: the cut is the right first act, and `rule-body` delivers on
 	// the reissue in the fresh process.
 	implementation_cut.ROW,
+	// Before `rule-body`, its one overlap (a whole-file `Write` of a rule document): the right tool is
+	// chosen before the placement questions are asked of its text.
+	file_edit_rows.REWRITE_ROW,
 	rule_body_guard.ROW,
 	...oracle_consulted.ROWS,
 ]
@@ -186,6 +270,13 @@ const BATCHING_RULE: MeasuredRule = {
 	reason: time_batch_guard.REASON,
 	keeps: batches_the_turn,
 	reaches: time_batch_guard.is_guarded_call,
+	about: {
+		title: 'Turn batching',
+		topic: '`turn-batching.md`',
+		fires:
+			'the `Bash` / `Edit` / `Read` after three single-call turns in a row; fires **again** every three more such turns',
+		quiet: 'calls per round trip above the floor',
+	},
 }
 
 // No `is_trigger`, as for batching. No `keeps`: any dispatch would read as compliance, so it is left
@@ -194,12 +285,21 @@ const INVESTIGATION_RULE: MeasuredRule = {
 	id: 'investigation',
 	reason: investigation_reads.REASON,
 	reaches: investigation_reads.is_refusable_call,
+	about: {
+		title: 'Investigation delegation threshold',
+		topic: '`delegation.md`',
+		fires:
+			'the `Read` / `Bash` that makes the third read of a file the run will not edit; fires **again** once reads pile up to the threshold again',
+		quiet: 'reads under the threshold — nothing to delegate yet',
+	},
 }
 
 const MEASURED_RULES: ReadonlyArray<MeasuredRule> = [
 	...DELIVERED_RULES,
 	BATCHING_RULE,
 	INVESTIGATION_RULE,
+	// Delivered by `stop:guard`; listed here so `rule:value` counts its refusals.
+	concise_reply.ROW,
 ]
 
 // Once per run, so a run that obeyed is never wedged. A call the batching guard may refuse is stepped
@@ -213,14 +313,11 @@ const BATCH_REFUSAL_WINDOW_MS = 10_000
 
 // Asked with its real record, not `NEVER_MS`: that guard never refuses one sequence twice.
 function will_batch_guard_refuse(tail: string, call: GuardedCall, run: GuardRun): boolean {
-	// In a lane child the batching guard only notices, so there is nothing to stand aside for.
-	if (lane_guard_policy.mode_here('batching') !== 'refuse') return false
-
 	const refused_at_ms = BATCH_STAMP.last_ms(BATCH_STAMP.path(run.transcript))
 
 	if (run.now_ms - refused_at_ms < BATCH_REFUSAL_WINDOW_MS) return true
 
-	return time_batch_guard.should_block(tail, call, refused_at_ms)
+	return will_batch_refuse(tail, call, run)
 }
 
 function is_first_delivery(
@@ -246,7 +343,7 @@ function delivery_decision(rule: DeliveredRule): TranscriptGuardSpec['should_blo
 		delivered_at_ms: number,
 		run: GuardRun,
 	): boolean {
-		if (already_satisfied?.(tail, call) === true) return false
+		if (already_satisfied?.(tail, call, run) === true) return false
 		if (decide === undefined) return true
 
 		return decide(call, run, !will_batch_guard_refuse(tail, call, run), delivered_at_ms)
@@ -289,9 +386,8 @@ function is_enabled(): boolean {
 const delivered_rules = {
 	DELIVERED_RULES,
 	EARLY_HEARTBEAT_REASON: early_heartbeat.EARLY_HEARTBEAT_REASON,
-	FILE_BODY_REASON: file_body.FILE_BODY_REASON,
+	FILE_BODY_REASON: file_edit_rows.FILE_BODY_REASON,
 	DIRECT_FILING_REASON: direct_filing.DIRECT_FILING_REASON,
-	FILING_CAP_REASON: filing_cap.FILING_CAP_REASON,
 	GIT_FORCE_REASON: git_force.GIT_FORCE_REASON,
 	ISSUE_COMMENTS_REASON: issue_comments.ISSUE_COMMENTS_REASON,
 	LANE_INTERACTIVE_ASK_REASON: lane_interactive_ask.LANE_INTERACTIVE_ASK_REASON,
@@ -300,6 +396,7 @@ const delivered_rules = {
 	PIPED_VERIFICATION_REASON: piped_verification.PIPED_VERIFICATION_REASON,
 	POLL_LOOP_REASON: poll_loop.POLL_LOOP_REASON,
 	PRE_GATE_CUT_REASON: pre_gate_cut.PRE_GATE_CUT_REASON,
+	PRETOOL_GUARD,
 	RAW_FIELD_BODY_REASON: raw_field_body.RAW_FIELD_BODY_REASON,
 	RUN_TAIL_REASON: run_tail_rule.RUN_TAIL_REASON,
 	SHELL_BODY_REASON,
@@ -313,5 +410,5 @@ const delivered_rules = {
 	is_issue_filing,
 }
 
-export type { CallRewrite, DeliveredRule, MeasuredRule }
+export type { CallRewrite, DeliveredRule, MeasuredRule, RuleAbout }
 export { delivered_rules }

package/scripts/rules/destructive-command.ts

@@ -39,24 +39,16 @@ function is_recursive_forced_rm(segment: string): boolean {
 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))
-}
-
+// `gh repo delete` / `archive`; a `gh repo edit` (`--visibility` included) is `repo-admin.ts`'s.
 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)
+	return group === REPO_GROUP && REPO_REMOVALS.has(action)
 }
 
 const DELETE_METHOD = 'DELETE'
@@ -93,11 +85,11 @@ function is_destructive_segment(segment: string): boolean {
 }
 
 function is_destructive_command(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))
 }
 
 const DESTRUCTIVE_COMMAND_REASON =
-	'⛔ destructive command: a recursive forced `rm`, a `gh repo delete` / `archive` / visibility edit, ' +
+	'⛔ destructive command: a recursive forced `rm`, a `gh repo delete` / `archive`, ' +
 	'`gh pr close` or a `gh api -X DELETE` cannot be undone, which is Tier C. Remove one path at a ' +
 	'time without `-f`, or ask the user to run it. It fires on every occurrence ' +
 	'(`prompts/collaboration-workflow/operating-rules.md`).'
@@ -109,6 +101,13 @@ const ROW = {
 	decide: (): boolean => true,
 	// The opening the reason carried before it was cut to the action and the next command.
 	former_reasons: ['⛔ destructive command: a recursive forced `rm` (`rm -rf`'],
+	about: {
+		title: 'Destructive command',
+		topic: '`operating-rules.md`',
+		fires:
+			'`rm -rf` (any spelling), `gh repo delete` / `archive`, `gh pr close`, `gh api -X DELETE`. Every occurrence',
+		quiet: "`gh issue close` or removing an Issue label — the workflow's own steps",
+	},
 }
 
 const destructive_command = { DESTRUCTIVE_COMMAND_REASON, ROW, is_destructive_command }

package/scripts/rules/direct-filing.ts

@@ -8,8 +8,8 @@ import { bash_triggers } from './bash-triggers'
 // pointed there.
 
 const DIRECT_FILING_REASON =
-	'⛔ direct filing: an Issue is filed with `pnpm josh issue:file "<title>" --body-file <path> ' +
-	'--depth <0|1|2>`, never with `gh api …/issues` or `gh issue create` — it runs the scout, the lint, ' +
+	'⛔ direct filing: an Issue is filed with `pnpm josh issue:file "<title>" --body-file <path>`, ' +
+	'never with `gh api …/issues` or `gh issue create` — it runs the scout, the lint, ' +
 	'the labels and `epic:bundle` itself. It fires on every occurrence (`docs/josh-commands-backlog.md` ' +
 	'→ "`josh issue:file`").'
 
@@ -27,6 +27,14 @@ const ROW = {
 	decide: (): boolean => true,
 	keeps: bash_triggers.on_bash_command(bash_triggers.is_issue_filing),
 	reaches: bash_triggers.on_bash_command(is_any_filing),
+	about: {
+		title: 'Direct filing',
+		topic: '`docs/josh-commands-backlog.md` → `josh issue:file`',
+		fires:
+			'a `Bash` that creates an Issue outside `josh issue:file` (`gh issue create`, or a POST with `title` to `…/issues`); the refusal hands over the `pnpm josh issue:file` form. Every occurrence',
+		quiet:
+			'filing through `pnpm josh issue:file` — the duplicate scan, the body check and `epic:bundle` all run',
+	},
 }
 
 const direct_filing = { DIRECT_FILING_REASON, ROW }

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

@@ -0,0 +1,139 @@
+import type { RepoIdentity } from '#scripts/discovery/repo-origin'
+import { repo_party } from '#scripts/discovery/repo-party'
+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, the checkout's own `owner/repo`
+// spelled out (the one repository the placeholders can expand to, `repo_party.current_repository`, the
+// candidate set `third-party-write` reads; joshuafolkken/kit#4737), and `gh issue comment` with no
+// repository selector. A comment to another repository named outright is left to `third-party-write`,
+// and so is every spelled-out one where the placeholders could expand to more than one repository.
+//
+// **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
+}
+
+type ResolveOwnRepository = () => RepoIdentity | undefined
+
+// The checkout's own repository is read only for an owner spelled out, so a placeholder write and
+// every other command pay nothing for the config read.
+function is_own_comments_endpoint(endpoint: string, resolve_own: ResolveOwnRepository): boolean {
+	const target = gh_api.repo_target(endpoint)
+
+	if (target === undefined || !COMMENTS_PATH.test(endpoint)) return false
+
+	return (
+		gh_api.is_owner_placeholder(target.owner) || repo_party.is_own_repository(target, resolve_own())
+	)
+}
+
+function is_comment_api_call(
+	args: ReadonlyArray<string>,
+	resolve_own: ResolveOwnRepository,
+): 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, resolve_own)
+}
+
+function is_comment_segment(segment: string, resolve_own: ResolveOwnRepository): 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, resolve_own)
+}
+
+// `resolve_own` is injected so the suite fixes the checkout's repository without reading the real one.
+function is_direct_issue_comment(
+	command: string,
+	resolve_own: ResolveOwnRepository = repo_party.current_repository,
+): boolean {
+	return direct_pr_create.has_run_segment(command, (segment) =>
+		is_comment_segment(segment, resolve_own),
+	)
+}
+
+// `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` whose owner is the `{owner}` placeholder or the checkout's own `owner/repo` spelled out); 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 }