@joshuafolkken/kit 1.1383.0 → 1.1435.0

package/scripts/init/workflow-mark.ts

@@ -0,0 +1,35 @@
+import { json_value } from '#scripts/lib/json-value'
+
+// `josh start` sets a project up for the GitHub Issue workflow and `josh init` alone does not. The
+// difference decides whether a `basic` project receives `.claude/settings.json`, whose permissions,
+// hooks and plugin an unattended `backlogrun` agent runs on (#3796).
+//
+// `josh start` hands the mark to the setup it runs through this variable, not an argument: that setup
+// may be the project's own kit it hands off to or a toolkit's command (`--init-command`), and an older
+// one refuses an argument it does not know but ignores a variable. The setup records the mark in
+// `package.json`, where every later `josh init` and `josh sync` reads it.
+const WORKFLOW_ENV = 'JOSH_WORKFLOW'
+const GITHUB_WORKFLOW = 'github'
+
+function is_requested(environment: NodeJS.ProcessEnv = process.env): boolean {
+	return environment[WORKFLOW_ENV] === GITHUB_WORKFLOW
+}
+
+function is_recorded(manifest: Record<string, unknown> | undefined): boolean {
+	const josh = manifest?.['josh']
+
+	return json_value.is_record(josh) && josh['workflow'] === GITHUB_WORKFLOW
+}
+
+function request(environment: NodeJS.ProcessEnv = process.env): void {
+	environment[WORKFLOW_ENV] = GITHUB_WORKFLOW
+}
+
+// The `josh` record's field for the mark — none for a project `josh start` did not set up, so a
+// `josh init` never writes the mark of its own accord.
+function recorded_fields(has_workflow: boolean): Record<string, string> {
+	return has_workflow ? { workflow: GITHUB_WORKFLOW } : {}
+}
+
+const workflow_mark = { is_requested, is_recorded, request, recorded_fields }
+export { workflow_mark }

package/scripts/issue/issue-ack-cli.ts

@@ -0,0 +1,84 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { git_command } from '#scripts/git/git-command'
+import { issue_number_shape } from '#scripts/issue/issue-number-shape'
+import { session_cite } from '#scripts/issue/session-cite'
+import { issue_watch, type Acknowledged } from './issue-watch'
+
+// `josh issue:ack <N>` — record that the run has read a person's update to its issue, so the hook,
+// the review attestation and `josh followup` stop raising it. It prints the update it acknowledges:
+// the same read becomes the new baseline (`issue-watch.ts` → `acknowledge`), so nothing that arrived
+// after the hook spoke can be acknowledged without being printed here.
+//
+// **The number is asked for, though the record already carries it**, so an acknowledgement typed for
+// one issue cannot silently clear the watch on another.
+
+const SUCCESS_EXIT_CODE = 0
+const FAILURE_EXIT_CODE = 1
+const ARGV_OFFSET = 2
+const USAGE = 'Usage: josh issue:ack <issue-number>'
+const NO_WATCH_LINE =
+	'No run recorded a baseline for that issue in this checkout (`josh run:entry` writes it), or the issue could not be read — nothing was acknowledged.'
+const NOTHING_NEW_LINE = 'No person has updated the issue since the run last read it.'
+
+function parse_number(argv: ReadonlyArray<string>): string | undefined {
+	const [first] = argv
+
+	if (first === undefined || argv.length !== 1) return undefined
+
+	return issue_number_shape.ISSUE_NUMBER_PATTERN.test(first) ? first : undefined
+}
+
+function report(acknowledged: Acknowledged): void {
+	const heading = `Acknowledged issue ${session_cite.issue(acknowledged.issue)}.`
+
+	console.info(
+		acknowledged.diff === undefined
+			? `${heading} ${NOTHING_NEW_LINE}`
+			: `${heading}\n\n${acknowledged.diff}`,
+	)
+}
+
+async function acknowledge(issue_number: string): Promise<number> {
+	const root = await git_command.repository_root()
+
+	if (issue_watch.read_record(root)?.issue !== issue_number) {
+		console.error(NO_WATCH_LINE)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	const acknowledged = await issue_watch.acknowledge(root)
+
+	if (acknowledged === undefined) {
+		console.error(NO_WATCH_LINE)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	report(acknowledged)
+
+	return SUCCESS_EXIT_CODE
+}
+
+async function run(argv: ReadonlyArray<string>): Promise<number> {
+	const issue_number = parse_number(argv)
+
+	if (issue_number === undefined) {
+		console.error(USAGE)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	return await acknowledge(issue_number)
+}
+
+async function main(argv: ReadonlyArray<string>): Promise<void> {
+	process.exitCode = await run(argv)
+}
+
+const issue_ack_cli = { run }
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
+
+export { issue_ack_cli }

package/scripts/issue/issue-labels.ts

@@ -70,6 +70,9 @@ const ALREADY_DONE_LABEL = 'already-done'
 // it; **`auto-ok` never rides on it** — `issue-auto-ok.ts` refuses the default for it on every path,
 // since a release is Tier C — and only a person opts it into unattended execution.
 const RELEASE_LABEL = 'release'
+// Applied to an Issue whose second review round was skipped, so the condition stays auditable
+// (`prompts/review.md` → "When round 2 is skipped entirely, and when it is not").
+const REVIEW_ROUND2_SKIPPED_LABEL = 'review-round2-skipped'
 
 // The four labels that mean an open issue must not be handed to a run as it stands: an `epic`
 // tracks a batch and is never run directly (its children are), `in-progress` is already claimed by
@@ -205,8 +208,11 @@ interface LabelDefinition {
 }
 
 // What `josh start` provisions on a new repository so the first `kickoff` finds every label a run
-// applies with its intended color. The `epic` and `in-progress` metadata is
-// the one the workflow documents create them with; the labels only a person applies are left out.
+// applies with its intended color. The metadata is the one the workflow documents create each label
+// with. **The labels only a person applies are provisioned too**: a person cannot apply a label the
+// repository does not have, so leaving one out made the first `auto-ok` a manual creation step.
+// `bug` is GitHub's default label, kept because `issue:file` applies it to a bug fix and a
+// repository may have been created without the defaults.
 const WORKFLOW_LABELS: ReadonlyArray<LabelDefinition> = [
 	{
 		name: EPIC_LABEL,
@@ -235,6 +241,32 @@ const WORKFLOW_LABELS: ReadonlyArray<LabelDefinition> = [
 		color: 'fef2c0',
 		description: 'Tracks the next release; its blockers are the merged work it publishes',
 	},
+	{
+		name: AUTO_OK_LABEL,
+		color: '0e8a16',
+		description: 'Opted in to unattended execution outside an epic',
+	},
+	{
+		name: NEEDS_DECISION_LABEL,
+		color: 'd93f0b',
+		description: 'Parked: needs a decision before it can run',
+	},
+	{
+		name: NEEDS_HUMAN_REVIEW_LABEL,
+		color: 'd93f0b',
+		description: 'Implement and verify, but stop before committing so a person can look',
+	},
+	{
+		name: ALREADY_DONE_LABEL,
+		color: '6f42c1',
+		description: 'Verified already merged — a person closes it',
+	},
+	{
+		name: REVIEW_ROUND2_SKIPPED_LABEL,
+		color: 'c5def5',
+		description: 'Review round 2 was skipped under the condition in prompts/review.md',
+	},
+	{ name: BUG_LABEL, color: 'd73a4a', description: "Something isn't working" },
 	...FILING_ROUTE_LABELS,
 	...DEPTH_LABELS,
 ]
@@ -329,12 +361,6 @@ function depth_label_of(labels: ReadonlyArray<LabelReference> | undefined): stri
 // document operates on a label name that does not exist here — a stale or mistyped `labels[]=…`
 // otherwise fails silently at run time. One source, so a label added above joins the scan without a
 // second edit.
-// Applied to an Issue whose second review round was skipped, so the condition stays auditable
-// (`prompts/review.md` → "When round 2 is skipped entirely, and when it is not"). Provisioned inline
-// by the run that applies it rather than through `FILING_ROUTE_LABELS`, but still a managed label the
-// documents operate on, so the label-reference scan has to know it.
-const REVIEW_ROUND2_SKIPPED_LABEL = 'review-round2-skipped'
-
 const ALL_LABELS: ReadonlySet<string> = new Set([
 	EPIC_LABEL,
 	BUG_LABEL,
@@ -363,6 +389,11 @@ const ALL_LABELS: ReadonlySet<string> = new Set([
 	IGNORE_FOR_RELEASE_LABEL,
 ])
 
+// The managed labels `REPOSITORY_LABELS` deliberately does not provision, each with its reason. Every
+// other member of `ALL_LABELS` is provisioned — `issue-labels.test.ts` fails on one that is in
+// neither list, so a label added above cannot silently become one a repository lacks. Empty today.
+const EXEMPT_FROM_PROVISIONING: ReadonlyMap<string, string> = new Map<string, string>()
+
 export type { LabelDefinition, ReleaseClassification }
 export {
 	ALL_LABELS,
@@ -379,6 +410,7 @@ export {
 	DEPTH_LABELS,
 	ENHANCEMENT_LABEL,
 	EPIC_LABEL,
+	EXEMPT_FROM_PROVISIONING,
 	FILING_ROUTE_LABELS,
 	has_any_label,
 	has_label_name,

package/scripts/issue/issue-state-cli.ts

@@ -1,10 +1,11 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
 import { git_gh_command } from '#scripts/gh/git-gh-command'
+import type { IssueReadReason } from '#scripts/gh/git-gh-issue-read'
 import { issue_number_shape } from '#scripts/issue/issue-number-shape'
 import { bounded_pool } from '#scripts/lib/bounded-pool'
 import { cli_flags } from '#scripts/lib/cli-flags'
-import { issue_report_failures, type ReadFailureKind } from './issue-report-failures'
+import { issue_report_failures } from './issue-report-failures'
 import { issue_state, type IssueState } from './issue-state'
 
 // `josh issue:state <N> [<N> ...]` — print each issue's state and labels, in the spelling the
@@ -50,7 +51,14 @@ interface StateRequest {
 // One issue's state, or the failure kind. Named for export because `run:prep` reads the state beside
 // the body and the dependency-update scope, reusing this read rather than a
 // second one that would drift from the `human_review` decision `parse_issue_state` owns.
-type StateRead = { kind: 'state'; state: IssueState } | { kind: ReadFailureKind }
+//
+// **Why a read failed rides along where the request said it**: `backlog:drive` names the reason when it
+// hands an unreadable named issue back. Both are optional, so a caller that only separates the kinds
+// needs no edit.
+type StateRead =
+	| { kind: 'state'; state: IssueState }
+	| { kind: 'missing' }
+	| { kind: 'unreadable'; reason?: IssueReadReason | undefined; status?: number | undefined }
 
 interface IssueReport {
 	issue_number: string
@@ -102,11 +110,13 @@ function parse_request(argv: ReadonlyArray<string>): StateRequest | undefined {
 async function read_issue(issue_number: string, repo?: string): Promise<StateRead> {
 	const read = await git_gh_command.issue_view_json_classified(issue_number, STATE_FIELDS, repo)
 
-	if (read.kind !== 'read') return { kind: read.kind }
+	if (read.kind !== 'read') return read
 
 	const parsed = issue_state.parse_issue_state(read.json)
 
-	return parsed === undefined ? { kind: 'unreadable' } : { kind: 'state', state: parsed }
+	return parsed === undefined
+		? { kind: 'unreadable', reason: 'malformed' }
+		: { kind: 'state', state: parsed }
 }
 
 // Through the shared pool rather than a raw `Promise.all`: each read spawns a `gh` process, and a

package/scripts/issue/issue-watch-diff.ts

@@ -0,0 +1,152 @@
+import { read_json_listing } from '#scripts/git/parse-json-array'
+import { z } from 'zod'
+
+// What a person changed on an issue since a run last read it, as the one pure answer the hook, the
+// review attestation, `josh issue:ack` and `josh followup` all print. Kept free of I/O so the four
+// callers cannot each draw the line between "a person's update" and "noise" differently.
+//
+// **A person's update is a body edit or a comment nobody automated.** A bot's comment (`type: Bot`,
+// or a `[bot]` login) is not one. A run's own comment is posted under the person's own `gh` login,
+// so the login cannot tell the two apart; `git-gh-issue-write.ts` stamps every comment josh posts
+// with `RUN_MARKER`, and a marked comment is not one either. An unmarked comment written by hand
+// through a raw `gh api` counts as a person's — the direction that costs one `josh issue:ack`, never a
+// missed correction.
+//
+// **Comment edits are out of scope.** A new comment carries an id above the baseline's; an edited
+// one keeps its id and is not seen. The body is compared whole, so its edits are.
+
+const RUN_MARKER = '<!-- josh:run -->'
+const BOT_TYPE = 'Bot'
+const BOT_SUFFIX = '[bot]'
+const NO_COMMENT_ID = 0
+const UNKNOWN_AUTHOR = '(unknown)'
+const UNKNOWN_TIME = '(undated)'
+
+const BODY_HEADING = 'Body edited:'
+const REMOVED_PREFIX = '- '
+const ADDED_PREFIX = '+ '
+const COMMENT_HEADING = 'New comment by '
+const AT = ' at '
+const SECTION_SEPARATOR = '\n\n'
+const LINE_SEPARATOR = '\n'
+const CRLF = '\r\n'
+
+const comment_schema = z.looseObject({
+	id: z.number(),
+	user: z.looseObject({ login: z.string(), type: z.string().optional() }).nullish(),
+	created_at: z.string().optional(),
+	body: z.string().nullish(),
+})
+
+interface WatchComment {
+	id: number
+	author: string
+	is_automated: boolean
+	created_at: string
+	body: string
+}
+
+interface WatchSnapshot {
+	body: string
+	comments: ReadonlyArray<WatchComment>
+}
+
+interface WatchBaseline {
+	body: string
+	last_comment_id: number
+}
+
+function is_bot(user: z.infer<typeof comment_schema>['user']): boolean {
+	return user?.type === BOT_TYPE || (user?.login.endsWith(BOT_SUFFIX) ?? false)
+}
+
+function is_automated(user: z.infer<typeof comment_schema>['user'], body: string): boolean {
+	return is_bot(user) || body.includes(RUN_MARKER)
+}
+
+function to_comment(raw: z.infer<typeof comment_schema>): WatchComment {
+	const body = raw.body ?? ''
+	const author = raw.user?.login ?? UNKNOWN_AUTHOR
+	const created_at = raw.created_at ?? UNKNOWN_TIME
+
+	return { id: raw.id, author, is_automated: is_automated(raw.user, body), created_at, body }
+}
+
+// `undefined` — never `[]` — for a listing that could not be read, so a failed read is never taken
+// for "nobody commented".
+function parse_comments(json: string | undefined): ReadonlyArray<WatchComment> | undefined {
+	if (json === undefined) return undefined
+
+	const listing = read_json_listing(json, comment_schema)
+
+	return listing.kind === 'read' ? listing.rows.map((row) => to_comment(row)) : undefined
+}
+
+function last_comment_id(comments: ReadonlyArray<WatchComment>): number {
+	return Math.max(NO_COMMENT_ID, ...comments.map((comment) => comment.id))
+}
+
+function baseline_of(snapshot: WatchSnapshot): WatchBaseline {
+	return { body: snapshot.body, last_comment_id: last_comment_id(snapshot.comments) }
+}
+
+function lines_missing_from(source: string, other: string): Array<string> {
+	const present = new Set(other.split(LINE_SEPARATOR))
+
+	return source.split(LINE_SEPARATOR).filter((line) => line.trim() !== '' && !present.has(line))
+}
+
+// GitHub stores a body saved in its web editor with CRLF line endings, so one edited line to a body
+// josh wrote over the API with LF would otherwise read as every line removed and added.
+function to_lf(body: string): string {
+	return body.split(CRLF).join(LINE_SEPARATOR)
+}
+
+// The lines that left and the lines that arrived — not a positional diff, which would need a
+// dependency in a hook that runs on every tool call, and a reader comparing a spec only needs which
+// sentences changed.
+function body_section(previous_raw: string, current_raw: string): string | undefined {
+	const previous = to_lf(previous_raw)
+	const current = to_lf(current_raw)
+
+	if (previous === current) return undefined
+
+	const removed = lines_missing_from(previous, current).map((line) => `${REMOVED_PREFIX}${line}`)
+	const added = lines_missing_from(current, previous).map((line) => `${ADDED_PREFIX}${line}`)
+
+	return [BODY_HEADING, ...removed, ...added].join(LINE_SEPARATOR)
+}
+
+function comment_section(comment: WatchComment): string {
+	return `${COMMENT_HEADING}${comment.author}${AT}${comment.created_at}${LINE_SEPARATOR}${comment.body}`
+}
+
+function new_person_comments(
+	baseline: WatchBaseline,
+	snapshot: WatchSnapshot,
+): ReadonlyArray<WatchComment> {
+	return snapshot.comments.filter(
+		(comment) => comment.id > baseline.last_comment_id && !comment.is_automated,
+	)
+}
+
+// The unread update as the text a run is shown, or `undefined` when a person changed nothing.
+function unread_diff(baseline: WatchBaseline, snapshot: WatchSnapshot): string | undefined {
+	const body = body_section(baseline.body, snapshot.body)
+	const comments = new_person_comments(baseline, snapshot).map((comment) =>
+		comment_section(comment),
+	)
+	const sections = [...(body === undefined ? [] : [body]), ...comments]
+
+	return sections.length === 0 ? undefined : sections.join(SECTION_SEPARATOR)
+}
+
+const issue_watch_diff = {
+	RUN_MARKER,
+	baseline_of,
+	parse_comments,
+	unread_diff,
+}
+
+export type { WatchBaseline, WatchComment, WatchSnapshot }
+export { issue_watch_diff }

package/scripts/issue/issue-watch-gate.ts

@@ -0,0 +1,81 @@
+import { git_command } from '#scripts/git/git-command'
+import { session_cite } from '#scripts/issue/session-cite'
+import { review_attest } from '#scripts/review/review-attest'
+import { issue_watch, type WatchRecord } from './issue-watch'
+
+// The refusals a person's unread issue update raises, composed once so the hook, `josh review:attest
+// --check` and `josh followup` say the same thing about the same state.
+//
+// **The gates poll on every call** (`interval_ms: 0`): they run a handful of times per run, and the
+// poll is a conditional request that a 304 answers for free. Only the hook, which runs on every tool
+// call, spaces its polls out.
+
+const EVERY_CALL_MS = 0
+
+function ack_command(issue: string): string {
+	return `pnpm josh issue:ack ${issue}`
+}
+
+function unread_message(record: Pick<WatchRecord, 'issue' | 'pending'>): string {
+	return [
+		`A person updated issue ${session_cite.issue(record.issue)} after this run read it, and the run has not taken the update in:`,
+		record.pending ?? '',
+		`Read it, compare it with the acceptance criteria, fix what it changes, then run \`${ack_command(record.issue)}\` to record that it was read.`,
+	].join('\n\n')
+}
+
+function review_message(record: WatchRecord, briefed_at: string): string {
+	return [
+		`Issue ${session_cite.issue(record.issue)} was updated after the review was briefed (taken in at ${record.acknowledged_at}, briefed at ${briefed_at}), so the review read the earlier specification.`,
+		'Re-run `/code-review` with a fresh `pnpm josh review:brief`, so the review reads the change against the updated issue.',
+	].join('\n')
+}
+
+async function polled(root: string): Promise<WatchRecord | undefined> {
+	return await issue_watch.poll({ interval_ms: EVERY_CALL_MS }, root)
+}
+
+// The merge-time refusal: a person's update the run has not acknowledged. `undefined` when there is
+// none, when no run recorded a baseline in this checkout, or when the issue could not be read — an
+// unreachable GitHub does not hold a merge `josh followup` would otherwise make.
+async function unread_refusal(root: string): Promise<string | undefined> {
+	const record = await polled(root)
+
+	return record?.pending === undefined ? undefined : unread_message(record)
+}
+
+// The review-time refusal: an unread update, or one taken in after the review was briefed — the fix
+// it led to is then a change the review never saw.
+async function review_refusal(root: string): Promise<string | undefined> {
+	const record = await polled(root)
+
+	if (record === undefined) return undefined
+	if (record.pending !== undefined) return unread_message(record)
+
+	const pointer = review_attest.read_pointer(root)
+
+	if (pointer === undefined || record.acknowledged_at <= pointer.taken_at) return undefined
+
+	return review_message(record, pointer.taken_at)
+}
+
+async function review_refusal_here(): Promise<string | undefined> {
+	return await review_refusal(await git_command.repository_root())
+}
+
+// Throws the refusal, for the `josh followup` seams that stop by throwing.
+async function assert_read_here(): Promise<void> {
+	const refusal = await unread_refusal(await git_command.repository_root())
+
+	if (refusal !== undefined) throw new Error(refusal)
+}
+
+const issue_watch_gate = {
+	assert_read_here,
+	review_refusal,
+	review_refusal_here,
+	unread_message,
+	unread_refusal,
+}
+
+export { issue_watch_gate }

package/scripts/issue/issue-watch-hook.ts

@@ -0,0 +1,54 @@
+import { error_text } from '#scripts/lib/error-message'
+import { issue_watch, type WatchRecord } from './issue-watch'
+import { issue_watch_gate } from './issue-watch-gate'
+
+// The `PreToolUse` adapter that shows a run a person's update to its issue on the next tool call,
+// composed into `pretool-guard.ts` — the one PreToolUse hook — rather than added as a second
+// `.claude/settings.json` entry.
+//
+// **It polls at most once per interval.** Every tool call reads the checkout's record from disk; only
+// one whose last poll is older than `POLL_INTERVAL_MS` asks GitHub, with the ETag of the previous
+// answer, so an unchanged issue costs a 304. The request is bounded well under the hook's own timeout.
+//
+// **It refuses once per update.** The refusal is what puts the update in front of the run; repeating
+// it on every call would wedge the run before it could act. A further update changes the pending text
+// and is shown again. `josh issue:ack` clears it, and the review attestation and `josh followup` keep
+// refusing until it does — the hook is the early warning, not the enforcement.
+//
+// **It fails open.** No record, an unreadable issue or a thrown error allows the call: a hook that
+// stalls every tool call over a network blip would cost more than the update it watches for.
+
+const POLL_INTERVAL_MS = 180_000
+const POLL_TIMEOUT_MS = 5000
+
+function is_new_to_run(record: WatchRecord | undefined): record is WatchRecord {
+	return record?.pending !== undefined && record.pending !== record.shown
+}
+
+async function new_update_reason(now: Date): Promise<string | undefined> {
+	const record = await issue_watch.poll({
+		interval_ms: POLL_INTERVAL_MS,
+		timeout_ms: POLL_TIMEOUT_MS,
+		now,
+	})
+
+	if (!is_new_to_run(record)) return undefined
+
+	issue_watch.mark_shown(record)
+
+	return issue_watch_gate.unread_message(record)
+}
+
+async function watch_reason(now: Date = new Date()): Promise<string | undefined> {
+	try {
+		return await new_update_reason(now)
+	} catch (error) {
+		error_text.trace_swallowed('issue_watch_hook.watch_reason', error)
+
+		return undefined
+	}
+}
+
+const issue_watch_hook = { POLL_INTERVAL_MS, watch_reason }
+
+export { issue_watch_hook }