@joshuafolkken/kit 1.872.0

package/scripts-ai/followup-issue-number.ts

@@ -0,0 +1,31 @@
+// One parser for every consumer: `--issue-number` is a free-form string, and `Number('42a')` is
+// NaN — which compares unequal to every issue number and would silently disable the
+// just-completed-issue exclusion. `parse_issue_number_from_text` accepts every shape the positional
+// does (`42`, `#42`, a title ending in `#42`) and guarantees digits-only output, so the command line
+// and the run's tail cannot disagree about what "the completed issue" is.
+//
+// It sits in a module of its own because both consumers need it and neither may import the other:
+// the tail reads it to record a run, and the entry point reads it to build one
+// (joshuafolkken/kit#1539).
+function parse_issue_number_from_text(input: string | undefined): string | undefined {
+	if (input === undefined) return undefined
+	const trimmed = input.trim()
+	const direct_match = /^#?(\d+)$/u.exec(trimmed)
+	if (direct_match?.[1] !== undefined) return direct_match[1]
+	const title_match = /#(\d+)$/u.exec(trimmed)
+
+	return title_match?.[1]
+}
+
+function parse_completed_issue_number(raw: string | undefined): number | undefined {
+	const digits = parse_issue_number_from_text(raw)
+
+	return digits === undefined ? undefined : Number(digits)
+}
+
+const followup_issue_number = {
+	parse_issue_number_from_text,
+	parse_completed_issue_number,
+}
+
+export { followup_issue_number, parse_issue_number_from_text, parse_completed_issue_number }

package/scripts-ai/git-followup-finish.ts

@@ -0,0 +1,217 @@
+import { git_followup_cleanup, type CleanupStep } from '../scripts/git/git-followup-cleanup'
+import { git_followup_pending } from '../scripts/git/git-followup-pending'
+import { git_next_issues } from '../scripts/git/git-next-issues'
+import { review_attest } from '../scripts/review/review-attest'
+import { review_stamps } from '../scripts/review/review-stamps'
+import { run_hold } from '../scripts/run/run-hold'
+import { run_progress_clock } from '../scripts/run/run-progress-clock'
+import { parse_completed_issue_number } from './followup-issue-number'
+
+// **The count of unreleased merges, not the project version** (joshuafolkken/kit#1486). This line
+// used to read the local `package.json` and was read as "the version this run just shipped"; children
+// no longer bump, so that number names the *previous* release and the reading is false. The count is
+// the one `pnpm josh release` acts on, and it is printed here for the same reason it goes into the
+// Telegram: a number that keeps climbing is a release nobody has run.
+//
+// Printed after the merge, and the count is read from a freshly fetched default branch — so this
+// run's own merge is already in it and nothing here says otherwise, unlike the Telegram sent one step
+// earlier from a tree the merge had not reached.
+async function print_pending_release(): Promise<void> {
+	const line = await git_followup_pending.pending_release_line({ is_merge_pending: false })
+
+	if (line !== undefined) console.info(line)
+}
+
+// #821: surface what to run next right where the completion is read. Printed before the project
+// version line, which stays the final line of the console output by contract.
+async function print_next_issues(completed_issue_number: string | undefined): Promise<void> {
+	const lines = await git_next_issues.fetch_next_issue_lines(
+		parse_completed_issue_number(completed_issue_number),
+	)
+	for (const line of lines) console.info(line)
+}
+
+// The tail printed once the workflow itself has finished. `print_pending_release` stays last by
+// contract, so anything added here goes above it.
+async function print_completion(
+	issue_number: string | undefined,
+	should_merge: boolean,
+): Promise<void> {
+	console.info('')
+	console.info('✅ PR followup completed.')
+	// Merged runs only, like the epic auto-close: on `--no-merge` the linked issue is still open
+	// and still the current task, so a "next" list would hide the one issue that matters.
+	if (should_merge) await print_next_issues(issue_number)
+	await print_pending_release()
+}
+
+// A **merged** run ends here, and the round-1 review snapshot's lifetime is one run
+// (joshuafolkken/kit#1441). `--no-merge` is not the end of one — the pull request is still open and
+// the issue is still the current task, the same line `print_next_issues` and the epic auto-close
+// already draw — and clearing there would be the unsafe direction: the next round-1 brief would find
+// no record and write a fresh one against the already-fixed tree, which is the arm-A skip over
+// unreviewed fix code the record exists to prevent.
+function clear_round_one_snapshot(should_merge: boolean): void {
+	if (should_merge) review_stamps.clear_round_one()
+}
+
+// Cleared beside the round-1 snapshot, and for the same reason: the contract's lifetime is one run,
+// and a record left behind is the one the next run's check would read.
+async function clear_review_target(should_merge: boolean): Promise<void> {
+	if (!should_merge) return
+
+	try {
+		await review_attest.clear_here()
+	} catch {
+		/* a fresh `josh review:brief` replaces the record the next run reads */
+	}
+}
+
+// The two review records are one step of the tail: both are cleared by a merged run and neither is
+// worth reporting on its own.
+async function clear_review_records(should_merge: boolean): Promise<void> {
+	clear_round_one_snapshot(should_merge)
+	await clear_review_target(should_merge)
+}
+
+// joshuafolkken/kit#1091: the working-tree hold a typed entry point claims before it starts is
+// released here, on the one seam every `fullrun` — and every child of an `epicrun` or a `queue` —
+// passes through, so a finished run never leaves the next one locked out. **Gated on `should_merge`
+// like the epic auto-close and the round-1 snapshot clear**: a `--no-merge` run has not finished, and
+// its tree is still the one nobody else may start in.
+//
+// It swallows its own failure for the same reason the gate's in-flight marker does: the record must
+// never decide whether a merged run reports success. A record that survives anyway expires on its own
+// eight hours later, which is what covers an abnormally ended run.
+async function release_worktree_hold(should_merge: boolean): Promise<void> {
+	if (!should_merge) return
+
+	try {
+		const directory = await run_hold.worktree_directory()
+
+		if (directory !== undefined) run_hold.release_hold(run_hold.hold_path(directory))
+	} catch {
+		/* the record expires on its own, and `pnpm josh run:release --force` clears it early */
+	}
+}
+
+// joshuafolkken/kit#1821: a `run:progress` watcher outlives the turn that started it and, left alone,
+// waits out its whole bound — up to an hour — after the run it was watching has already merged.
+// Removing its liveness record here, on the same merge seam that releases the working-tree hold, lets
+// the watcher read the record gone on its next tick and stop at once. **Keyed like the hold, on the
+// work tree's own git directory** (`worktree_directory` is `directories[0]`), which is exactly the key
+// the watcher resolved through `run_progress_read.stamp_target`, so the file removed is the file it
+// wrote.
+//
+// It swallows its own failure like the hold release beside it, and needs no recovery command: the
+// record is presence-only and the watcher's own bound ends it regardless, so it must never decide
+// whether a merged run reports success.
+//
+// **A no-op in an `epicrun` / `queue` batch, and deliberately so.** A batch child starts no watcher
+// of its own — the batch watcher is the parent's and outlives the child, which is still running the
+// rest of the batch — so a child keyed on its own lane worktree finds no record here and removes
+// nothing. The parent ends its own watcher on its stop, exactly as it starts it. This ends the
+// watcher of a run whose followup merges and which owns one on the same work tree: a standalone
+// `fullrun`.
+async function end_progress_watcher(should_merge: boolean): Promise<void> {
+	if (!should_merge) return
+
+	try {
+		const directory = await run_hold.worktree_directory()
+
+		if (directory === undefined) return
+
+		run_progress_clock.end_life(run_progress_clock.life_target_of(directory))
+	} catch {
+		/* the watcher's own bound ends it, so a record left behind costs at most one idle watcher */
+	}
+}
+
+// **The steps are independent, and one of them failing must not discard the rest**
+// (joshuafolkken/kit#1539). They used to be bare statements, so whichever threw first ended the
+// process — and the hold release is the last of them, which is how three merged runs left their
+// working tree locked. The order is still the contract: `print_completion` ends with the
+// unreleased-merge count, the final console line.
+function build_report_steps(
+	issue_number: string | undefined,
+	should_merge: boolean,
+): ReadonlyArray<CleanupStep> {
+	return [
+		// No `recovery`: the completion output is console text, which nothing re-prints.
+		{
+			label: 'The completion output',
+			recovery: undefined,
+			run: async () => {
+				await print_completion(issue_number, should_merge)
+			},
+		},
+	]
+}
+
+function build_record_steps(should_merge: boolean): ReadonlyArray<CleanupStep> {
+	return [
+		{
+			label: 'The review records',
+			recovery: undefined,
+			run: async () => {
+				await clear_review_records(should_merge)
+			},
+		},
+		{
+			label: 'The working-tree hold release',
+			// **The forced spelling, because the run that wrote the record is this one and it is
+			// ending** (joshuafolkken/kit#1799). A release names the run it belongs to, so a person
+			// finishing this step by hand is releasing a record they did not write — the plain form
+			// would answer `held` and remove nothing, which is a printed recovery that cannot recover.
+			recovery: 'pnpm josh run:release --force',
+			run: async () => {
+				await release_worktree_hold(should_merge)
+			},
+		},
+		{
+			label: 'The progress watcher',
+			// No recovery: the record is presence-only and the watcher's own bound ends it regardless,
+			// so there is nothing a person types to finish this step by hand.
+			recovery: undefined,
+			run: async () => {
+				await end_progress_watcher(should_merge)
+			},
+		},
+	]
+}
+
+function build_finish_steps(
+	issue_number: string | undefined,
+	should_merge: boolean,
+): ReadonlyArray<CleanupStep> {
+	return [...build_report_steps(issue_number, should_merge), ...build_record_steps(should_merge)]
+}
+
+// The tail every invocation shares. Answers whether all of it completed, so a caller could report a
+// partial tail; nothing acts on it yet, because a merged run has already succeeded and a cleanup that
+// failed is reported where it failed.
+//
+// **Guarded only on a merged run**, the same gate the wrapup applies and from the same definition: a
+// `--no-merge` run has merged nothing, so a failure in its tail is a failure of the run and still
+// ends it.
+async function finish(issue_number: string | undefined, should_merge: boolean): Promise<boolean> {
+	return await git_followup_cleanup.run_guarded_steps(
+		should_merge,
+		build_finish_steps(issue_number, should_merge),
+	)
+}
+
+const git_followup_finish = {
+	finish,
+	build_finish_steps,
+	print_completion,
+	print_next_issues,
+	print_pending_release,
+	clear_review_records,
+	clear_round_one_snapshot,
+	clear_review_target,
+	release_worktree_hold,
+	end_progress_watcher,
+}
+
+export { git_followup_finish }

package/scripts-ai/git-followup-workflow.ts

@@ -0,0 +1,252 @@
+#!/usr/bin/env tsx
+import { parseArgs } from 'node:util'
+import { git_branch } from '../scripts/git/git-branch'
+import { git_error } from '../scripts/git/git-error'
+import { git_notify, type GitNotifyConfig } from '../scripts/git/git-notify'
+import { git_pr_followup } from '../scripts/git/git-pr-followup'
+import { cli_body } from '../scripts/josh/cli-body'
+import { live_evidence } from '../scripts/review/live-evidence'
+import { review_attest } from '../scripts/review/review-attest'
+import { review_record } from '../scripts/review/review-record'
+import { load_optional_environment } from './environment-loader'
+import { parse_issue_number_from_text } from './followup-issue-number'
+import { git_followup_finish } from './git-followup-finish'
+
+load_optional_environment()
+
+// cspell:words coderabbit
+
+/* eslint-disable @typescript-eslint/naming-convention */
+interface CliArguments {
+	values: {
+		branch?: string
+		'issue-number'?: string
+		'notify-target'?: string
+		'notify-message'?: string
+		'notify-message-file'?: string
+		'notify-mentions'?: string
+		'coderabbit-ignore-reason'?: string
+		'ai-review-ignore-reason'?: string
+		'skip-watch'?: boolean
+		'no-merge'?: boolean
+		merge?: boolean
+		help?: boolean
+	}
+	positionals: Array<string>
+}
+/* eslint-enable @typescript-eslint/naming-convention */
+
+// The text is a constant rather than an inline literal: it is one option per supported flag, so it
+// grows with the command and would otherwise push `display_help` past the function line limit every
+// time a flag is added — a limit that exists to catch functions doing several things, which this one
+// never was (joshuafolkken/kit#1578).
+const HELP_TEXT = `
+🚦 PR Followup Workflow
+
+Usage:
+  jf-git-followup [issue] [options]
+
+Options:
+  --branch                     Target branch name (default: current branch)
+  --issue-number               Issue number for completion messages
+  --notify-target              pr | issue | both
+  --notify-message             Completion message header
+  --notify-message-file        Read the completion message from a file (\`-\` reads stdin). Use this
+                               whenever the message carries a backtick or a \`$\` — inside shell
+                               double quotes the shell evaluates them before this command runs
+  --notify-mentions            Comma-separated mentions (user,org/team)
+  --coderabbit-ignore-reason   Reason text when keeping CodeRabbit findings unresolved
+  --ai-review-ignore-reason    Reason text when keeping AI reviewer (Claude Review / CodeRabbit
+                               summary) findings unresolved
+  --skip-watch                 Skip the two-minute check look-ahead and only evaluate latest status
+  --no-merge                   Skip merging the PR (merge is on by default)
+  --merge                      (Deprecated — merge is now the default; kept for backward compatibility)
+  -h, --help                   Show this help
+`
+
+function display_help(): void {
+	console.info(HELP_TEXT)
+}
+
+function parse_cli_arguments(): CliArguments {
+	return parseArgs({
+		options: {
+			branch: { type: 'string' },
+			'issue-number': { type: 'string' },
+			'notify-target': { type: 'string' },
+			'notify-message': { type: 'string' },
+			'notify-message-file': { type: 'string' },
+			'notify-mentions': { type: 'string' },
+			'coderabbit-ignore-reason': { type: 'string' },
+			'ai-review-ignore-reason': { type: 'string' },
+			'skip-watch': { type: 'boolean' },
+			'no-merge': { type: 'boolean' },
+			merge: { type: 'boolean' },
+			help: { type: 'boolean', short: 'h' },
+		},
+		allowPositionals: true,
+	})
+}
+
+async function resolve_branch_name(raw_branch: string | undefined): Promise<string> {
+	if (raw_branch !== undefined && raw_branch.trim().length > 0) return raw_branch.trim()
+
+	return await git_branch.current()
+}
+
+// The message is resolved here rather than inside `git_notify`, so the file form reaches the config
+// as text and the config keeps one `message` field. `--notify-message-file` exists because the inline
+// form is a double-quoted shell argument: a backtick or a `$` in the body is evaluated before this
+// process starts, and joshuafolkken/kit#1198 recorded both halves of that — a Telegram body that
+// silently lost a word, and a comment body whose text ran as git commands.
+function build_notify_config(values: CliArguments['values']): GitNotifyConfig | undefined {
+	return git_notify.build_notify_config({
+		raw_target: values['notify-target'] ?? 'issue',
+		raw_message: cli_body.resolve({
+			inline: values['notify-message'],
+			file_path: values['notify-message-file'],
+			inline_flag: '--notify-message',
+			file_flag: '--notify-message-file',
+		}),
+		raw_mentions: values['notify-mentions'],
+	})
+}
+
+function is_merge_resolved(values: CliArguments['values']): boolean {
+	return values['no-merge'] !== true
+}
+
+// joshuafolkken/kit#1522: `/code-review` is forked by the harness and inherits the *session's*
+// working directory, so a run implementing in a lane can be reviewed against a different tree
+// entirely — one holding the previous child's already-merged code. That review finds nothing wrong
+// and says so, and the run reads the silence as a clean round. **This is the seam where that stops
+// being free**: a merge is refused unless the review attested the checkout it was briefed on.
+//
+// **Absence is a refusal, not a pass.** The defect produced *no* signal, so a check that only
+// compared two present records would answer `ok` in exactly the state it exists to catch.
+//
+// **Scoped to a checkout that actually briefed a review.** `review_attest.check` answers
+// `not-required` where no `josh review:brief` was run here inside a run's lifetime, so a project or
+// a flow that does not use the brief merges exactly as it did before.
+//
+// The direction is deliberate: a wrongly-refused merge costs one re-run of the review, and a wrongly
+// allowed one ships a diff nobody read. Thrown rather than reported, so no `completion` Telegram is
+// sent and nothing merges — `git_pr_followup.run` is never reached.
+// `ok` means the guard was satisfied and `not-required` means it never applied to this checkout —
+// both let the merge proceed, so the two gates below read the verdict through one predicate rather
+// than repeating the pair of statuses.
+function is_merge_permitted(status: string): boolean {
+	return status === 'ok' || status === 'not-required'
+}
+
+const ISSUE_NUMBER_PATTERN = /^[1-9]\d*$/u
+
+function is_valid_issue(issue_number: string | undefined): boolean {
+	return issue_number !== undefined && ISSUE_NUMBER_PATTERN.test(issue_number)
+}
+
+async function assert_review_attested(should_merge: boolean): Promise<void> {
+	if (!should_merge) return
+
+	const verdict = await review_attest.check_here()
+
+	if (is_merge_permitted(verdict.status)) return
+
+	throw new Error(review_attest.refusal_message(verdict))
+}
+
+// joshuafolkken/kit#2343: recording a review round was prose, and prose failed — eleven merges after
+// the instruction landed, `review:record` had never run once, so the recurrence ledger stayed blind.
+// **This is the seam where that stops being a request and becomes a gate**: a merge is refused unless
+// the round left a `- rf:` line for its issue, a zero-finding `none` line included.
+//
+// **Absence is a refusal, `missing` exactly as `assert_review_attested`'s is** — the defect this
+// exists for produced *no* line, so silence must not read as success. A checkout that keeps no ledger
+// answers `not-required` and merges as before, and a run whose issue the followup cannot identify has
+// no key to check, so it carries on rather than blocking on missing information.
+async function assert_review_recorded(
+	should_merge: boolean,
+	issue_number: string | undefined,
+): Promise<void> {
+	if (!should_merge || !is_valid_issue(issue_number)) return
+
+	const issue = Number(issue_number)
+	const verdict = await review_record.check(issue)
+
+	if (is_merge_permitted(verdict.status)) return
+
+	throw new Error(review_record.refusal_message(issue))
+}
+
+// joshuafolkken/kit#2446: a runtime change merges only with its acceptance criteria run for real and
+// recorded in the pull request body — `live_evidence` carries the why. `exempt` (no runtime path
+// changed) merges as before, and a `--no-merge` run has not reached the gate at all.
+async function assert_live_evidence(should_merge: boolean, branch_name: string): Promise<void> {
+	if (!should_merge) return
+
+	const verdict = await live_evidence.check(branch_name)
+
+	if (verdict !== 'required') return
+
+	throw new Error(live_evidence.refusal_message())
+}
+
+// Every pre-merge refusal, in order — each one throws, so nothing merges past the first that fails.
+async function assert_merge_gates(
+	should_merge: boolean,
+	issue_number: string | undefined,
+	branch_name: string,
+): Promise<void> {
+	await assert_review_attested(should_merge)
+	await assert_review_recorded(should_merge, issue_number)
+	await assert_live_evidence(should_merge, branch_name)
+}
+
+async function main(): Promise<void> {
+	const cli = parse_cli_arguments()
+
+	if (cli.values.help === true) {
+		display_help()
+
+		return
+	}
+
+	const issue_number =
+		cli.values['issue-number'] ?? parse_issue_number_from_text(cli.positionals[0] ?? undefined)
+	const should_merge = is_merge_resolved(cli.values)
+	const branch_name = await resolve_branch_name(cli.values.branch)
+
+	await assert_merge_gates(should_merge, issue_number, branch_name)
+	// **The number the run reports on is the one it used**, which is the number the pull request
+	// closes where the invocation named none (joshuafolkken/kit#1539). Recovered inside `run`, so the
+	// tail records a run the command line could not identify rather than silently skipping it.
+	const used_issue_number = await git_pr_followup.run({
+		branch_name,
+		issue_number,
+		notify_config: build_notify_config(cli.values),
+		coderabbit_ignore_reason: cli.values['coderabbit-ignore-reason'],
+		ai_review_ignore_reason: cli.values['ai-review-ignore-reason'],
+		is_skip_watch: cli.values['skip-watch'] === true,
+		should_merge,
+	})
+
+	await git_followup_finish.finish(used_issue_number ?? issue_number, should_merge)
+}
+
+try {
+	await main()
+	console.info('')
+} catch (error) {
+	git_error.handle(error)
+}
+
+const git_followup_workflow = {
+	assert_live_evidence,
+	assert_review_attested,
+	assert_review_recorded,
+	parse_issue_number_from_text,
+	resolve_branch_name,
+	is_merge_resolved,
+}
+
+export { git_followup_workflow }