@joshuafolkken/kit 1.1435.0 → 1.1455.0

package/scripts/review/review-round2.ts

@@ -9,14 +9,14 @@ import { review_level } from './review-level'
 //
 // **The two arms are the two states in which round 2's reason does not arise.** Round 2 exists
 // because round 1's *fix code* is unreviewed, and that is structural. Arm A applies where there is no fix code — the findings closed without an edit — so
-// the premise is absent rather than overridden. Arm B applies where the fix code neither executes,
-// nor instructs, nor ships, which is `review-level.ts`'s inert set: the same three ways a defect in
-// this repository escapes, read here for the fix delta instead of the whole change.
+// the premise is absent rather than overridden. Arm B applies where the fix leaves what executes
+// unchanged: `review-level.ts`'s inert set, documentation under `docs/` and the root `README.md`,
+// `prompts/`, and source files whose only change is in comments (`review-code-tree.ts`).
 //
-// **The wider line — "the fix delta touches no runtime code path" — is not adopted**: as
-// `review-level.ts` records, documentation-only diffs carry real defects no test covers. A prompt
-// fix and a test fix are exactly where the review is the only detector, so exempting them would
-// remove the round in the case it earns its keep.
+// **Arm B is wider than the review level's inert set, on purpose** (joshuafolkken/kit#3787). Round 1
+// still reviews a documentation or prompt change in full, and the fix to its findings is still made;
+// what goes unread is only that fix. `.claude/**`, `CLAUDE.md`, tests and configuration stay outside:
+// a test fix can weaken the verification it belongs to, and nothing reads that but the review.
 
 type RoundTwoVerdict = 'required' | 'skip'
 
@@ -33,7 +33,11 @@ const NO_SNAPSHOT_REASON =
 const EMPTY_DELTA_REASON_PREFIX =
 	'the fix delta is empty: round 1 wrote no fix code, so there is no unreviewed fix for a verification pass to read'
 const INERT_DELTA_REASON_PREFIX =
-	'every path round 1 fixed is inert — it neither executes, nor instructs, nor ships'
+	'every path round 1 fixed leaves what executes unchanged — inert, documentation, a prompt, or a comment-only edit'
+const README_PATH = 'README.md'
+const DOCUMENTATION_PREFIX = 'docs/'
+const MARKDOWN_EXTENSION = '.md'
+const PROMPTS_PREFIX = 'prompts/'
 const BASE_MOVED_REASON =
 	'the change base moved since round 1 was recorded, so the two file maps do not cover the same set of paths and their difference is not the fix delta — the round runs rather than reading that difference as one'
 
@@ -51,6 +55,9 @@ interface RoundTwoInput {
 	is_round_one_closed: boolean
 	snapshot: FileMapStamp | undefined
 	tree: Record<string, string>
+	// The paths whose code round 1's fixes left as it was (`review_code_tree.comment_only`). Absent is
+	// none, which is what a run without a code record pays.
+	comment_only?: ReadonlyArray<string>
 }
 
 interface RoundTwoDecision {
@@ -86,13 +93,26 @@ function live_reason(deciding: ReadonlyArray<string>): string {
 	return `round 1's fixes touched paths that execute, instruct or ship: ${path_decision.format_path_list(deciding)}`
 }
 
+function is_documentation(relative: string): boolean {
+	if (relative === README_PATH || relative.startsWith(PROMPTS_PREFIX)) return true
+
+	return relative.startsWith(DOCUMENTATION_PREFIX) && relative.endsWith(MARKDOWN_EXTENSION)
+}
+
+function is_unexecuted(relative: string, comment_only: ReadonlyArray<string>): boolean {
+	if (review_level.is_inert(relative) || is_documentation(relative)) return true
+
+	return comment_only.includes(relative)
+}
+
 function verdict_for_delta(
 	delta: ReadonlyArray<string>,
 	taken_at: string,
+	comment_only: ReadonlyArray<string> = [],
 ): { verdict: RoundTwoVerdict; reason: string } {
 	if (delta.length === 0) return { verdict: SKIPPED_VERDICT, reason: empty_reason(taken_at) }
 
-	const deciding = delta.filter((relative) => !review_level.is_inert(relative))
+	const deciding = delta.filter((relative) => !is_unexecuted(relative, comment_only))
 
 	if (deciding.length === 0) return { verdict: SKIPPED_VERDICT, reason: inert_reason(delta) }
 
@@ -110,7 +130,7 @@ function decide(input: RoundTwoInput): RoundTwoDecision {
 
 	const delta = file_map_stamp.changed_since(input.snapshot, input.tree)
 
-	return { ...verdict_for_delta(delta, input.snapshot.taken_at), delta }
+	return { ...verdict_for_delta(delta, input.snapshot.taken_at, input.comment_only), delta }
 }
 
 const review_round2 = {

package/scripts/review/review-stamps.ts

@@ -13,11 +13,17 @@ const TEST_RELATED_PREFIX = 'josh-test-related-stamp-'
 const GATE_PREFIX = 'josh-gate-stamp-'
 const IN_FLIGHT_PREFIX = 'josh-gate-running-'
 const ROUND_ONE_PREFIX = 'josh-review-round1-'
+const ROUND_ONE_CODE_PREFIX = 'josh-review-round1-code-'
 const BRIEFED_PREFIX = 'josh-review-briefed-'
 
 const gate_stamp: FileMapStampAccess = file_map_stamp.create(GATE_PREFIX, PROJECT_ROOT)
 const in_flight_stamp: FileMapStampAccess = file_map_stamp.create(IN_FLIGHT_PREFIX, PROJECT_ROOT)
 const round_one_stamp: FileMapStampAccess = file_map_stamp.create(ROUND_ONE_PREFIX, PROJECT_ROOT)
+// Written beside the round-1 snapshot: the comment-free digest of each source file (`review-code-tree.ts`).
+const round_one_code_stamp: FileMapStampAccess = file_map_stamp.create(
+	ROUND_ONE_CODE_PREFIX,
+	PROJECT_ROOT,
+)
 // Retaken on every brief: the round-1 snapshot is not the tree a later review read.
 const briefed_stamp: FileMapStampAccess = file_map_stamp.create(BRIEFED_PREFIX, PROJECT_ROOT)
 const lint_related_stamp: FileMapStampAccess = file_map_stamp.create(
@@ -29,24 +35,39 @@ const test_related_stamp: FileMapStampAccess = file_map_stamp.create(
 	PROJECT_ROOT,
 )
 
+// Swallowed: a code record left behind only ever sits beside an older snapshot, which the next
+// round-1 brief replaces together with it.
+function clear_round_one_code(target?: string): void {
+	try {
+		round_one_code_stamp.remove(target)
+	} catch {
+		/* the next round-1 brief overwrites it */
+	}
+}
+
 // Called only from the end of a merged run: a leftover widens the next delta (safe), while an early
 // removal lets round 1 re-snapshot an already-fixed tree (unsafe). Swallowed — the PR already merged.
-function clear_round_one(target?: string): void {
+function clear_round_one(target?: string, code_target?: string): void {
 	try {
 		round_one_stamp.remove(target)
 	} catch {
 		/* a record left behind widens the next round rather than narrowing it */
 	}
+
+	clear_round_one_code(code_target)
 }
 
 const review_stamps = {
 	briefed_stamp,
 	clear_round_one,
+	clear_round_one_code,
 	GATE_PREFIX,
 	gate_stamp,
 	IN_FLIGHT_PREFIX,
 	in_flight_stamp,
 	lint_related_stamp,
+	ROUND_ONE_CODE_PREFIX,
+	round_one_code_stamp,
 	ROUND_ONE_PREFIX,
 	round_one_stamp,
 	test_related_stamp,

package/scripts/rules/shell-body-trigger.ts

@@ -6,7 +6,8 @@
 
 // A body handed to a command as an inline double-quoted argument, in the spellings a run reaches for:
 // `gh`'s field flags (`-f` / `-F` / `--field` / `--raw-field` with `body=`), `gh`'s own `--body`, and
-// `josh`'s `--body` and `--notify-message`. The value is captured so the decision can be made on what
+// `josh`'s `--body` and `--notify-message`, and `josh notify`'s `--recommended` / `--alternative` —
+// free text every confirmation carries, naming the very commands a backtick would run. The value is captured so the decision can be made on what
 // the body actually contains rather than on the flag alone.
 //
 // **`-b` is deliberately absent.** It is `gh`'s short `--body`, but it is also `git checkout -b`, and
@@ -14,7 +15,7 @@
 // spellings end in `-` where this pattern needs whitespace or `=`, so `--body-file <path>` and
 // `--notify-message-file <path>` cannot match it.
 const FIELD_FLAGS = '(?:-f|-F|--field|--raw-field)'
-const MESSAGE_FLAGS = '(?:--body|--notify-message)'
+const MESSAGE_FLAGS = '(?:--body|--notify-message|--recommended|--alternative)'
 
 // **The opening quote sits on either side of `body=`, and both spellings are the same command.** zsh
 // strips the quotes before `gh` is started, so `-f body="… \`pnpm josh ms\` …"` and

package/scripts/rules/stop-rules.ts

@@ -103,7 +103,8 @@ const STOP_NOTIFY_REASON =
 	'⛔ mid-workflow stop notification: this working tree is still held by a run and no `confirmation` ' +
 	'Telegram was sent this turn, so a person is being left to wait off-screen without knowing the run ' +
 	'paused. `CLAUDE.md` → "Mid-workflow stop notification" requires ' +
-	'`pnpm josh notify --task-type confirmation --issue-url "<url>" --body=$\'<reason>\'` before any ' +
+	'`pnpm josh notify --task-type confirmation --issue-url "<url>" --body=$\'<reason>\' ' +
+	'--recommended "<choice>" --alternative "<choice>"` before any ' +
 	'mid-workflow pause. Send it, then end with a one-line confirmation that it was sent — do not repeat ' +
 	'your previous reply. This fires only while the hold is held and no notify is on the transcript, and ' +
 	'`stop_hook_active` lets a second stop through so a run is never wedged.'

package/scripts/run/entry/run-entry-stop.ts

@@ -1,6 +1,6 @@
 import { issue_cite } from '#scripts/issue/issue-cite'
 import { josh_command } from '#scripts/josh/josh-run'
-import { telegram_notify } from '#scripts/notify/telegram-notify'
+import { telegram_notify, type ConfirmInput } from '#scripts/notify/telegram-notify'
 import { lane_park } from '#scripts/rules/lane-park'
 
 // What `run:entry` does on the way out of a stop it decided itself.
@@ -26,14 +26,15 @@ interface StopNotice {
 }
 
 interface StopPorts {
-	notify: (input: { issue_title: string; body: string; recovery: string }) => Promise<boolean>
+	notify: (input: ConfirmInput) => Promise<boolean>
 	release: (issue_number: string) => Promise<boolean>
 	is_parking_child: () => boolean
 }
 
 const RECOVERY = 'If this did not arrive, the run:entry output in the session names the stop.'
+const LATER_ALTERNATIVE = 'Leave the Issue for a later session — nothing was changed'
 const NOTIFY_FAILED_NOTE =
-	'(the confirmation Telegram could not be sent — send it with `pnpm josh notify --task-type confirmation` before stopping)'
+	'(the confirmation Telegram could not be sent — send it with `pnpm josh notify --task-type confirmation --recommended "<choice>"` before stopping)'
 const RELEASED_NOTE = '(hold released by run:entry — the tree is free for the resume)'
 const RELEASE_FAILED_NOTE =
 	'(the hold could not be released — run `pnpm josh run:release` before stopping)'
@@ -78,6 +79,8 @@ async function notify_stop(notice: StopNotice, ports: StopPorts): Promise<void>
 		issue_title: `${notice.command} ${issue_cite.plain(notice.issue_number)} stopped`,
 		body: body_of(notice),
 		recovery: RECOVERY,
+		recommended: `Run \`${notice.command} ${issue_cite.plain(notice.issue_number)}\` again in a fresh session`,
+		alternatives: [LATER_ALTERNATIVE],
 	})
 
 	console.info(is_sent ? lane_park.COMMAND_NOTIFY_MARKER : NOTIFY_FAILED_NOTE)

package/scripts/run/run-stop-notify.ts

@@ -38,6 +38,8 @@ async function announce(notice: StopNotice): Promise<boolean> {
 		issue_title: STOP_TITLE,
 		body: notice.reason,
 		recovery: STOP_RECOVERY,
+		recommended: 'Resolve the reason above, then run `backlogrun` again',
+		alternatives: ['Leave the backlog stopped until a later session'],
 	})
 }
 

package/scripts/uninstall/distributed-files.ts

@@ -17,7 +17,7 @@ function widest_shape(profile: ProjectProfile): ProjectShape {
 	return {
 		profile,
 		reason: 'josh uninstall',
-		has_web: true,
+		should_use_prettier: true,
 		has_typescript: true,
 		has_git: true,
 		has_github: true,