@joshuafolkken/kit 1.1514.0 → 1.2114.0

package/scripts/rules/implementation-cut.ts

@@ -1,17 +1,17 @@
+import path from 'node:path'
 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 { json_value } from '#scripts/lib/json-value'
 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'
 import { run_cut_ready } from '#scripts/run/cut/run-cut-ready'
 import type { GuardedCall } from '#scripts/time-runtime/time-batch-guard'
-import { bash_triggers } from './bash-triggers'
+import { edit_tool } from './edit-tool'
 import { implementation_cut_verdict } from './implementation-cut-verdict'
 import { shell_segments } from './shell-segments'
 
@@ -26,30 +26,34 @@ import { shell_segments } from './shell-segments'
 // rather than approximating it — the same statistic and the same threshold, never a second
 // measurement.
 
-// The two edit tools the `PreToolUse` matcher routes here, and the working-tree boundary the cut is
-// taken at. A `PreToolUse` refusal fires *before* the edit lands, so the tree is at the consistent
-// state the previous edit left it — the "between edit batches, never mid-edit" boundary
+// The two edit tools the `PreToolUse` matcher routes here (`edit-tool.ts`), and the working-tree
+// boundary the cut is taken at. A `PreToolUse` refusal fires *before* the edit lands, so the tree is at
+// the consistent state the previous edit left it — the "between edit batches, never mid-edit" boundary
 // `pre-gate-cut.md` requires, reached without waiting for a check to go green.
-const EDIT_TOOLS: ReadonlySet<string> = new Set(['Edit', 'Write'])
-
-function is_edit_tool(name: string): boolean {
-	return EDIT_TOOLS.has(name)
-}
+const { is_edit_tool } = edit_tool
 
 // The one spelling that takes this cut rather than the pre-gate one: `--impl`. A bare `pnpm josh
 // run:cut <N>` is the pre-gate boundary and `--resume` / `--end` / `--json` ask about a cut rather than
-// take one, so the compliance test looks for the flag that makes it the implementation-phase cut.
+// take one, so `cost-run-cut.ts` looks for the flag that makes it the implementation-phase cut.
 const CUT_COMMANDS: ReadonlySet<string> = new Set(['run:cut'])
 const IMPL_FLAG = /(?:^|\s)--impl(?:[=\s]|$)/u
+const RESUME_FLAG = /(?:^|\s)--resume(?:[=\s]|$)/u
 
-function is_impl_cut_segment(segment: string): boolean {
-	return shell_segments.is_josh_command(segment, CUT_COMMANDS) && IMPL_FLAG.test(segment)
+// Segment-wise so a spelling quoted inside a body is not read as the call.
+function calls_cut_with(command: string, flag: RegExp): boolean {
+	return shell_segments
+		.segments_of(command)
+		.some((segment) => shell_segments.is_josh_command(segment, CUT_COMMANDS) && flag.test(segment))
 }
 
-// Whether this command takes the implementation-phase cut, segment-wise so a spelling quoted inside a
-// body is not read as the call.
+// Whether this command takes the implementation-phase cut.
 function takes_the_impl_cut(command: string): boolean {
-	return shell_segments.segments_of(command).some((segment) => is_impl_cut_segment(segment))
+	return calls_cut_with(command, IMPL_FLAG)
+}
+
+// Whether this command asks for a cut's resume verdict — the call a relaunched lane child opens with.
+function resumes_a_cut(command: string): boolean {
+	return calls_cut_with(command, RESUME_FLAG)
 }
 
 // What the trigger has to know about the world, passed in so the decision is testable without a lane on
@@ -133,6 +137,32 @@ function uncut_run_issue(state: LaneCostState): string | undefined {
 	return state.carried()?.issue === issue ? undefined : issue
 }
 
+function file_path_of(call: GuardedCall): string {
+	if (!json_value.is_record(call.input)) return ''
+
+	const value = call.input['file_path']
+
+	return typeof value === 'string' ? value : ''
+}
+
+// **The handoff the refusal asks for is never refused** (joshuafolkken/kit#4975). Only a reissue
+// inside the window passed, so a run that ran a check between the refusal and the handoff `Write`
+// could not write it, and `run:cut --impl` relaunched on the previous cut's stale handoff.
+function is_handoff_write(call: GuardedCall, directory: string, issue: string): boolean {
+	const handoff = path.resolve(directory, run_cut_handoff.handoff_path_of(issue))
+
+	return path.resolve(directory, file_path_of(call)) === handoff
+}
+
+// The uncut run an edit would be refused for — none where the edit is that run's own handoff.
+function refusable_issue(call: GuardedCall, state: LaneCostState): string | undefined {
+	const issue = uncut_run_issue(state)
+
+	if (issue === undefined) return undefined
+
+	return is_handoff_write(call, state.directory, issue) ? undefined : issue
+}
+
 // **An unmeasurable session is cut in a lane and left alone outside one.** A lane child's safety net is
 // the pre-gate direction below; a held run outside a lane is a person's own session, so only a measured
 // `over` interrupts it — a provider with no transcript would otherwise refuse every edit it makes.
@@ -161,24 +191,24 @@ function is_over_threshold_edit(
 ): boolean {
 	if (!is_edit_tool(call.name)) return false
 
-	const issue = uncut_run_issue(state)
+	const issue = refusable_issue(call, state)
 
 	if (issue === undefined) return false
 
 	return warrants_the_cut(state) && state.can_cut(issue)
 }
 
-// **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`
+// **The threshold in the refusal text is named by its command, never spelled**. It is priced at the
+// session's own model (`context-cut-payback.ts`), so no one number is right for every reader, and a
+// spelled literal is left behind when the price list moves.
+const THRESHOLD_TEXT = '`pnpm josh cost --cut`'
 
 // 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
 // the cut" is not left to look it up.
 const IMPLEMENTATION_CUT_REASON =
-	`⛔ implementation-phase cut: refused on every edit past the ${THRESHOLD_TEXT} line. ` +
-	`Write \`${run_cut_handoff.HANDOFF_PATH}\` as ${run_cut_handoff.HANDOFF_FORMAT}, run ` +
+	`⛔ implementation-phase cut: refused on every edit over ${THRESHOLD_TEXT}. ` +
+	`Write \`${run_cut_handoff.HANDOFF_PATH}\`: ${run_cut_handoff.HANDOFF_FORMAT}, run ` +
 	'`pnpm josh run:cut --impl <N> --handoff <path>`; `cut`: end the turn immediately, no Telegram ' +
 	'is owed; else reissue the edit (`.claude/skills/workflow-commands/pre-gate-cut.md`).'
 
@@ -211,19 +241,29 @@ function decide(
 }
 
 // The row itself, so `delivered-rules.ts` spreads one entry. `decide` fires it per threshold crossing
-// in a run that can cut; `keeps` is the implementation cut command, read from a `Bash` call the same
-// way `pre-gate-cut`'s is.
+// in a run that can cut. It declares no `keeps`: the trigger is a budget threshold the child cannot
+// observe, so no run takes `run:cut --impl` before crossing it unaided, and the row is reported
+// unmeasured rather than scored 0% on an act it cannot make (`rule-value.ts` → "A rule with no
+// `keeps` predicate is reported as unmeasured").
 const ROW = {
 	id: 'implementation-cut',
 	is_trigger: is_over_threshold_edit,
 	reason: IMPLEMENTATION_CUT_REASON,
 	decide,
-	keeps: bash_triggers.on_bash_command(takes_the_impl_cut),
 	// The opening the reason carried before it was cut to the action and the next command.
 	former_reasons: [
 		'⛔ 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, the run's own handoff file, already cut, or under the threshold",
+	},
 }
 
 const implementation_cut = {
@@ -233,6 +273,7 @@ const implementation_cut = {
 	decide,
 	is_over_threshold_edit,
 	is_reissued_refusal,
+	resumes_a_cut,
 	takes_the_impl_cut,
 	uncut_run_issue,
 }

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/investigator-foreground.ts

@@ -0,0 +1,231 @@
+import { delegation_policy } from '#scripts/delegation/delegation-policy'
+import { hook_decision, type GuardRun } from '#scripts/josh/hook-decision'
+import { json_value } from '#scripts/lib/json-value'
+import type { GuardedCall } from '#scripts/time-runtime/time-batch-guard'
+import {
+	time_transcript_line,
+	type Block,
+	type TranscriptLine,
+} from '#scripts/time-runtime/time-transcript-line'
+import { agent_model } from './agent-model'
+import { implementation_cut } from './implementation-cut'
+
+// An `investigator` dispatched without `run_in_background: false` is refused until it names it
+// (joshuafolkken/kit#4721).
+//
+// **The background launch is the cost, not the dispatch.** The subagent tool launches in the
+// background by default, so a main line with nothing else to do ends its turn on "waiting for the
+// reply", and the finished result sits in the queue until a later turn — measured at 4 of 33 such
+// dispatches over 7 days, 658 seconds idle, up to 287 in one plan. A foreground dispatch returns the
+// result in the same turn; the edit-target reads that keep the main line busy go in the same message,
+// where they run beside it.
+//
+// **It fires on every occurrence**: the remedy is one field on the same call.
+//
+// **A build whose subagent tool has no such field stands it down** (joshuafolkken/kit#4889). Claude
+// Code 2.1.306 in VS Code declares no `run_in_background`: every dispatch there launched in the
+// background (64 of 64), the model wrote the field as the string `"false"`, and the parsed hook input
+// dropped it — so the refusal could never be met, and it blocked the very delegation the investigation
+// guard demands. A string value is the tell: across 1,700 dispatches in builds that declare the field
+// the model wrote a boolean every time. A first call written bare leaves no string anywhere, so the
+// reissue it was refused into passes on the refused call's body instead (joshuafolkken/kit#4903).
+//
+// **The build is a fact of the session, not of the tail** (joshuafolkken/kit#4966). Each tell is
+// recorded once against the transcript, so a stand-down outlives the 256 KiB window the tells are read
+// from. A boolean `false` the parsed input dropped is a tell too: the transcript keeps what the model
+// wrote, so a dispatch this row refused that wrote it there is one the field never reached.
+//
+// **This row's own refusal is the last tell** (joshuafolkken/kit#5148). The harness drops an undeclared
+// argument before both the hook and the transcript see it, so a reissue rewritten after the refusal
+// leaves no tell on the tail. A reissue that still carries no field passes, and is remembered for the
+// session, when the last answered investigator dispatch on the tail is this row's refusal, alone in its
+// message and inside the refusal-then-reissue window. A sibling of the refused call shares its message,
+// a dispatch after an answered reissue follows a call that ran, and one past the window is a new one —
+// each still refused where the build declares the field.
+
+const INVESTIGATOR_FOREGROUND_REASON =
+	'⛔ investigator foreground: a background `investigator` leaves its result queued until a later turn. ' +
+	'Reissue the call with `run_in_background: false`, and put the reads of files this run will edit in the same message. ' +
+	'It fires on every occurrence (`.claude/skills/workflow-commands/delegation.md`).'
+
+const BACKGROUND_FIELD = 'run_in_background'
+// The fields that make a reissue the same dispatch as the call it repeats.
+const BODY_FIELDS = ['description', 'prompt'] as const
+const GUARD_LABEL = time_transcript_line.guard_from_refusal(INVESTIGATOR_FOREGROUND_REASON)
+const NO_FIELD_STAMP = hook_decision.create_refusal_stamp('josh-investigator-no-field-')
+
+// `kit:investigator` is the consumer's spelling of the same definition.
+function is_investigator(call: GuardedCall): boolean {
+	if (!agent_model.SUBAGENT_TOOLS.has(call.name) || !json_value.is_record(call.input)) return false
+
+	const type = call.input['subagent_type']
+
+	return typeof type === 'string' && type.split(':').at(-1) === delegation_policy.INVESTIGATOR_AGENT
+}
+
+function field_of(input: unknown, key: string): unknown {
+	return json_value.is_record(input) ? input[key] : undefined
+}
+
+function is_foreground(call: GuardedCall): boolean {
+	return field_of(call.input, BACKGROUND_FIELD) === false
+}
+
+function is_background_investigator(call: GuardedCall): boolean {
+	return is_investigator(call) && !is_foreground(call)
+}
+
+function keeps_foreground(call: GuardedCall): boolean {
+	return is_investigator(call) && is_foreground(call)
+}
+
+function is_untyped_field(name: string, input: unknown): boolean {
+	if (!agent_model.SUBAGENT_TOOLS.has(name) || !json_value.is_record(input)) return false
+
+	return typeof input[BACKGROUND_FIELD] === 'string'
+}
+
+// The ids of the tail's calls that have a result, and of those this row refused with the refusal's
+// instant.
+interface TailResults {
+	answered: ReadonlySet<string>
+	refused: ReadonlyMap<string, number>
+}
+
+// A block with the message it was written in, or the instant its line was written.
+interface Placed {
+	block: Block
+	message_id: string
+	at_ms: number
+}
+
+function placed_of(lines: ReadonlyArray<TranscriptLine>): Array<Placed> {
+	return lines.flatMap((line) =>
+		line.blocks.map((block) => ({ block, message_id: line.message_id, at_ms: line.timestamp_ms })),
+	)
+}
+
+function results_of(placed: ReadonlyArray<Placed>): TailResults {
+	const results = placed.filter(({ block }) => block.result_id !== '')
+	const refused = results.filter(({ block }) => block.refusal_guard === GUARD_LABEL)
+
+	return {
+		answered: new Set(results.map(({ block }) => block.result_id)),
+		refused: new Map(refused.map(({ block, at_ms }) => [block.result_id, at_ms])),
+	}
+}
+
+// The field written `false`, in either spelling.
+function writes_foreground(block: Block): boolean {
+	return String(field_of(block.input, BACKGROUND_FIELD)) === 'false'
+}
+
+function has_same_body(block: Block, call: GuardedCall): boolean {
+	return BODY_FIELDS.every((key) => field_of(block.input, key) === field_of(call.input, key))
+}
+
+// The call in hand is not answered yet, and its `false` there is the one the parsed input dropped.
+function is_pending_foreground(block: Block, results: TailResults): boolean {
+	return !results.answered.has(block.id) && writes_foreground(block)
+}
+
+// The call in hand on the tail, or a dispatch this row refused that it repeats. A same-body dispatch
+// that ran is not a tell: a build that declares the field still refuses a bare repeat of it past the
+// reissue window `refuses` reads.
+function is_same_dispatch(block: Block, call: GuardedCall, results: TailResults): boolean {
+	if (!is_investigator(block) || !has_same_body(block, call)) return false
+
+	return results.refused.has(block.id) || is_pending_foreground(block, results)
+}
+
+// A dispatch this row refused although it wrote the field `false`.
+function is_dropped_foreground(block: Block, results: TailResults): boolean {
+	return results.refused.has(block.id) && is_investigator(block) && writes_foreground(block)
+}
+
+function refused_at_ms(dispatch: Placed | undefined, results: TailResults): number {
+	return results.refused.get(dispatch?.block.id ?? '') ?? hook_decision.NEVER_MS
+}
+
+function is_alone(dispatch: Placed, dispatches: ReadonlyArray<Placed>): boolean {
+	return dispatches.filter(({ message_id }) => message_id === dispatch.message_id).length === 1
+}
+
+// The call in hand reissues this row's refusal: the last investigator dispatch with a result is one
+// this row refused, alone in its message, within the reissue window. A sibling launched beside the
+// refused call shares its message, and a dispatch after an answered reissue follows a call that ran.
+function is_reissue(placed: ReadonlyArray<Placed>, results: TailResults, now_ms: number): boolean {
+	const dispatches = placed.filter(({ block }) => is_investigator(block))
+	const last = dispatches.findLast(({ block }) => results.answered.has(block.id))
+	const at_ms = refused_at_ms(last, results)
+
+	if (last === undefined || at_ms === hook_decision.NEVER_MS) return false
+
+	return is_alone(last, dispatches) && now_ms - at_ms < implementation_cut.REISSUE_WINDOW_MS
+}
+
+function tail_shows_no_field(tail: string, call: GuardedCall, now_ms: number): boolean {
+	const placed = placed_of(time_transcript_line.parse_text(tail))
+	const results = results_of(placed)
+	const has_block_tell = placed.some(
+		({ block }) =>
+			is_untyped_field(block.name, block.input) ||
+			is_same_dispatch(block, call, results) ||
+			is_dropped_foreground(block, results),
+	)
+
+	return has_block_tell || is_reissue(placed, results, now_ms)
+}
+
+function remember_no_field(run: GuardRun): boolean {
+	NO_FIELD_STAMP.record(NO_FIELD_STAMP.path(run.transcript), run.now_ms)
+
+	return true
+}
+
+function is_remembered(run: GuardRun): boolean {
+	return NO_FIELD_STAMP.last_ms(NO_FIELD_STAMP.path(run.transcript)) !== hook_decision.NEVER_MS
+}
+
+// True when this session's subagent tool declares no `run_in_background`, so no dispatch in it can run
+// in the foreground: the call in hand or a subagent call on the tail wrote the field as a string, the
+// tail holds the call in hand (or the dispatch it reissues) with the field the parsed input dropped,
+// or this row refused a dispatch that wrote it `false`. The first tell is recorded for the session. A
+// call that names the background explicitly came through a build that declares the field.
+function lacks_background_field(tail: string, call: GuardedCall, run: GuardRun): boolean {
+	if (field_of(call.input, BACKGROUND_FIELD) === true) return false
+	if (is_remembered(run)) return true
+
+	const has_tell =
+		is_untyped_field(call.name, call.input) || tail_shows_no_field(tail, call, run.now_ms)
+
+	return has_tell && remember_no_field(run)
+}
+
+const ROW = {
+	id: 'investigator-foreground',
+	is_trigger: is_background_investigator,
+	reason: INVESTIGATOR_FOREGROUND_REASON,
+	already_satisfied: lacks_background_field,
+	decide: (): boolean => true,
+	keeps: keeps_foreground,
+	reaches: is_investigator,
+	about: {
+		title: 'Investigator dispatched in the foreground',
+		topic:
+			'`.claude/skills/workflow-commands/delegation.md` → "The pre-implementation reading — what goes to a unit, and from which file"',
+		fires:
+			'an `Agent` / `Task` call of the `investigator` type without `run_in_background: false`. Every occurrence',
+		quiet:
+			'another agent type, `run_in_background: false` set, or a session whose subagent tool declares no `run_in_background` (the field written as a string, the tail holding the same description and prompt, a refused dispatch that wrote it `false`, or a reissue still without the field just after this row refused a lone dispatch) — remembered for the session',
+	},
+}
+
+const investigator_foreground = {
+	INVESTIGATOR_FOREGROUND_REASON,
+	ROW,
+	is_background_investigator,
+	lacks_background_field,
+}
+
+export { investigator_foreground }

package/scripts/rules/issue-citation.ts

@@ -1,24 +1,19 @@
-// The bare-`#N` predicate behind the `issue-citation` row of the stop guard,
-// and the printing-side formatter that keeps a bare `#N` out of session-facing output in the first
-// place.
+// The printing-side formatter that keeps a bare `#N` out of session-facing output, and the bare-`#N`
+// predicate it is checked against.
 //
 // **Session-facing output cites an Issue as a number-link, never a bare `#N`.** `CLAUDE.md` and
 // `prompts/collaboration-workflow/issue-citation.md` require `[#<N>](https://github.com/<owner>/<repo>/issues/<N>) — <short summary>`
 // in what the person reads: a bare `#123` is not clickable and does not say which repository's Issue
-// it is. The stop guard reads `last_assistant_message` — the turn's session-facing text — and this
-// predicate answers whether a bare number slipped into it.
+// it is.
 //
-// **It blocks the stop, so a false positive costs a wasted turn**. The nudge
-// now reaches the model rather than the person, so the detection is tightened to what is genuinely a
-// bare citation: a `#N` inside a fenced code block, inside an inline-code span, on a quote line, or
-// right after `PR` / `pull request` is not a citation slip and is skipped. The scan is line-based so
-// each exclusion is decided from the one line the mention sits on.
+// **The detection is what is genuinely a bare citation**: a `#N` inside a fenced code block, inside an
+// inline-code span, on a quote line, or right after `PR` / `pull request` is not a citation slip and is
+// skipped. The scan is line-based so each exclusion is decided from the one line the mention sits on.
 //
-// **`linkify` runs that same scan the other way**: a command whose stdout a
-// run copies into its reply passes the text through it, and every bare `#N` the predicate would flag
-// is rewritten to `[#N](url)` — which the predicate then reads as linked, so the material that fed the
-// duplicate reply is fixed where it is printed rather than scolded after it reaches the screen. The
-// same exclusions hold, so a `#N` in a fenced example or an already-linked reference is left untouched.
+// **`linkify` runs that same scan the other way**: a command whose stdout a run copies into its reply
+// passes the text through it, and every bare `#N` the predicate would flag is rewritten to `[#N](url)`
+// — which the predicate then reads as linked, so the reference is fixed where it is printed. The same
+// exclusions hold, so a `#N` in a fenced example or an already-linked reference is left untouched.
 
 import { issue_cite } from '#scripts/issue/issue-cite'
 
@@ -31,8 +26,8 @@ const ISSUE_NUMBER = /#\d+/gu
 // scan stays linear.
 const REFERENCE_BOUNDARY = /[\s#()[\]<>|]/u
 // A well-formed `owner/repo`: exactly one slash between two non-empty segments — the same shape
-// `issue:cite`'s parser accepts. A path-like run (`src/lib`, `a/b/c`) is not one, so it is not emitted
-// as a prefix that would make the suggested `issue:cite` call refuse the very reference it names.
+// `issue:cite`'s parser accepts. A path-like run (`src/lib`, `a/b/c`) is not one, so it is not linked
+// as a repository.
 const OWNER_REPO = /^[^\s/#]+\/[^\s/#]+$/u
 // A markdown link: `[text](target)`. Each class excludes *both* of its delimiters — no `[`/`]` in the
 // text, no `(`/`)` in the target — so neither star is ambiguous against a nested bracket and there is
@@ -94,11 +89,6 @@ function lead_token(message: string, hash_index: number): string {
 	return message.slice(start, hash_index)
 }
 
-// **The message text alone, never a GitHub-bound artifact.** An Issue body or comment is passed to
-// `gh` as a `Bash` argument, not spoken in `last_assistant_message`, so those never reach here — which
-// is exactly the "silent on GitHub-bound artifacts" behavior the issue asks for, obtained by what the
-// stop guard reads rather than by a second exclusion here.
-//
 // The `owner/repo` written immediately before a `#N`, or '' when the mention is bare — the run of
 // non-boundary characters ending at the `#`, kept only when it holds a `/`. Read backwards a
 // character at a time so a repository name of any length costs its own length and no more.
@@ -184,10 +174,9 @@ function prose_lines(message: string): ReadonlyArray<string> {
 	return lines_outside_fences(message).filter((line) => !QUOTE_LINE.test(line))
 }
 
-// The bare references in the message, in the order they appear and de-duplicated: the block reason
-// names them and turns them into `issue:cite` arguments, so a reference cited twice is not nudged
-// about twice. Fenced-code blocks and quote lines are skipped, so a `#N` shown in an example or quoted
-// from an Issue body is not read as the run's own citation.
+// The bare references in the message, in the order they appear and de-duplicated. Fenced-code blocks
+// and quote lines are skipped, so a `#N` shown in an example or quoted from an Issue body is not read
+// as the run's own citation.
 function bare_references(message: string): ReadonlyArray<string> {
 	const found: Array<string> = []
 
@@ -196,42 +185,10 @@ function bare_references(message: string): ReadonlyArray<string> {
 	return [...new Set(found)]
 }
 
-// Every reference the prompt carries, each as written — `#N` or `owner/repo#N` — with none of the
-// citation exclusions applied: a number pasted inside a fence or a quote is still the person's.
-function prompt_references(prompt: string): ReadonlySet<string> {
-	const found = new Set<string>()
-
-	for (const match of prompt.matchAll(ISSUE_NUMBER)) {
-		found.add(repo_prefix(prompt, match.index) + match[0])
-	}
-
-	return found
-}
-
-// **A number the person's prompt already carried is quoted, not cited**. A
-// pasted log from another repository holds its own `#1`…`#7`; `issue:cite` would link them to this
-// repository's unrelated Issues, so following the refusal would make the reply wrong. Only the exact
-// reference the prompt wrote is exempt, so a bare `#N` the run brought in itself is still refused.
-function unquoted_references(message: string, prompt: string): ReadonlyArray<string> {
-	const quoted = prompt_references(prompt)
-
-	return bare_references(message).filter((reference) => !quoted.has(reference))
-}
-
 function has_bare_reference(message: string): boolean {
 	return bare_references(message).length > 0
 }
 
-// The token `issue:cite` takes for one reference: a qualified `owner/repo#N` is passed as-is, a bare
-// `#N` loses its `#` so the command reads `issue:cite 123` rather than `issue:cite #123`.
-function cite_argument(reference: string): string {
-	return reference.startsWith('#') ? reference.slice(1) : reference
-}
-
-function cite_arguments(references: ReadonlyArray<string>): ReadonlyArray<string> {
-	return references.map((reference) => cite_argument(reference))
-}
-
 // One bare reference rewritten as a number-link: `[#N](url)` for a same-repo mention, or
 // `[owner/repo#N](url)` for a qualified one — the label is the reference exactly as it was written, so
 // the reader sees the number they would have, now clickable. The URL is `issue-cite`'s own assembly,
@@ -286,11 +243,9 @@ function linkify(message: string, slug: string): string {
 
 const issue_citation = {
 	bare_references,
-	cite_arguments,
 	has_bare_reference,
 	linkify,
 	prose_lines,
-	unquoted_references,
 }
 
 export { issue_citation }

package/scripts/rules/issue-comments.ts

@@ -21,14 +21,14 @@ 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
 // comments endpoint. The short `-c` is deliberately absent — it belongs to `wc`, `grep` and `sort`
 // far more often than to `gh`, and reading it as "comments included" silenced the rule on any line
 // that ended in a pipe. A run that types it pays one round trip instead.
-const FETCHES_COMMENTS = /--comments\b|--json\s[\w,]*\bcomments\b|\/comments\b/u
+const FETCHES_COMMENTS = /--comments\b|--json[=\s]['"]?[\w,]*\bcomments\b|\/comments\b/u
 const ISSUES_PATH = /repos\/[^\s'"]*\/issues\//u
 
 // A field projection — `--jq` for `gh api`, `--json` for `gh issue view` — whose value never names the
@@ -38,11 +38,14 @@ const ISSUES_PATH = /repos\/[^\s'"]*\/issues\//u
 // comma list `--json state,labels` and the expression `'{state, labels}'` are read the same way.
 const FIELD_PROJECTION = /(?:--jq|--json)[= ]\s*('[^']*'|"[^"]*"|\S+)/u
 const NAMES_THE_BODY = /\bbody\b/u
+// A projection that names no field at all — `--jq .`, `--jq '.[]'` — passes every field through,
+// the body with them, so it is a body read however it is spelled.
+const NAMES_A_FIELD = /(?:^|[.{,\s'"])[A-Za-z_]/u
 
 function projects_away_body(segment: string): boolean {
-	const projection = FIELD_PROJECTION.exec(segment)
+	const value = FIELD_PROJECTION.exec(segment)?.[1]
 
-	return projection !== null && !NAMES_THE_BODY.test(projection[1] ?? '')
+	return value !== undefined && NAMES_A_FIELD.test(value) && !NAMES_THE_BODY.test(value)
 }
 
 function is_body_read_segment(segment: string): boolean {
@@ -82,7 +85,7 @@ function reads_issue_comments(command: string): boolean {
 }
 
 const RULE_DOC = '`.claude/skills/workflow-commands/issue-comments.md`'
-const COMMENTS_FALLBACK = 'gh api repos/{owner}/{repo}/issues/<N>/comments'
+const COMMENTS_FALLBACK = 'gh api repos/<owner>/<repo>/issues/<N>/comments'
 
 // **The refusal hands over the command that fixes it**, because reading is not the same as
 // obeying: a sentence saying "also read the comments" is prose that moves nothing, while a refused
@@ -164,6 +167,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 = {
@@ -171,7 +182,9 @@ const issue_comments = {
 	ISSUE_COMMENTS_REASON,
 	ROW,
 	comments_input,
+	fetches_issue_comments,
 	is_body_only_issue_read,
+	projects_away_body,
 }
 
 export { 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: '`operating-rules.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 = {