@joshuafolkken/kit 1.1240.0 → 1.1373.0

package/scripts/refactor/refactor-scan-cli.ts

@@ -3,7 +3,7 @@ import { fileURLToPath } from 'node:url'
 import { refactor_scan } from './refactor-scan'
 
 // The `josh refactor:scan` entry point. It takes no arguments: the scope is the changed files, or
-// `scripts/` when nothing changed, decided the same way for every run (joshuafolkken/kit#2180).
+// `scripts/` when nothing changed, decided the same way for every run.
 
 if (process.argv[1] === fileURLToPath(import.meta.url)) {
 	process.exitCode = await refactor_scan.run_scan()

package/scripts/refactor/refactor-scan.ts

@@ -5,7 +5,7 @@ import { refactor_lint, type CategoryResult } from './refactor-lint'
 import { refactor_targets } from './refactor-targets'
 
 // `josh refactor:scan` — the command `prompts/refactoring.md` §4.1–§4.3 now point to instead of
-// describing the search by hand (joshuafolkken/kit#2180). It selects the target files, expands the
+// describing the search by hand. It selects the target files, expands the
 // scope along the import graph, asks the project's own eslint which refactoring candidates the scope
 // holds, and answers whether any high- or medium-priority candidate remains.
 //
@@ -16,7 +16,7 @@ import { refactor_targets } from './refactor-targets'
 
 // The convergence vocabulary. `clear` is what §4.3's self-reported "no high- or medium-priority
 // candidate left" loop exit becomes once a command answers it: a token a caller can read, not a claim.
-// `error` is the third answer (joshuafolkken/kit#2180): the eslint run itself did not complete, so the
+// `error` is the third answer: the eslint run itself did not complete, so the
 // scope's state is unknown — kept distinct from `clear` so a failed scan is never read as converged.
 const CLEAR = 'clear'
 const CANDIDATES = 'candidates'

package/scripts/refactor/refactor-targets.ts

@@ -4,7 +4,7 @@ import { changed_paths } from '#scripts/git/changed-paths'
 import { line_targets } from '#scripts/lines/line-targets'
 
 // The target-file selection of `josh refactor:scan` — the priority `prompts/refactoring.md` §4.1
-// used to spell out in prose (joshuafolkken/kit#2180). The scope is the same reading every scoped
+// used to spell out in prose. The scope is the same reading every scoped
 // command decides from — the branch diff plus the untracked files (`changed-paths.ts`) — and only
 // when that is empty does it fall back to `scripts/`, so a run on a clean `main` still has something
 // to scan rather than reporting nothing.

package/scripts/release/github-release-cli.ts

@@ -1,8 +1,14 @@
 import { fileURLToPath } from 'node:url'
 import { git_spawn_sync } from '#scripts/git/git-spawn-sync'
+import { cli_flags } from '#scripts/lib/cli-flags'
 import { github_release } from './github-release'
 import { github_release_environment } from './github-release-environment'
 
+const KNOWN_FLAGS: ReadonlyArray<string> = []
+const COMMAND_NAME = 'release:github'
+const ARGUMENT_START = 2
+const SUCCESS_EXIT_CODE = 0
+
 // A release published without the tag list would pick its previous tag from nothing, so a failed
 // `git tag` stops the run rather than reading as "no tags".
 function local_tags(): Array<string> {
@@ -12,13 +18,29 @@ function local_tags(): Array<string> {
 	return output.split('\n')
 }
 
-async function main(): Promise<void> {
+// **No argument reaches the publish**. The command reads only the
+// environment, so a `--help` it ignored would create a real GitHub Release; a help request prints
+// the usage and any other argument is refused, both before the environment is read.
+async function run_argv(argv: ReadonlyArray<string>): Promise<number> {
+	const answer = cli_flags.answer_help_or_unknown(
+		argv.slice(ARGUMENT_START),
+		KNOWN_FLAGS,
+		COMMAND_NAME,
+	)
+	if (answer !== undefined) return answer
+
 	const { token, tag, settings } = github_release_environment.read_release_input(process.env)
 
 	console.info(await github_release.publish(fetch, token, tag, { ...settings, tags: local_tags() }))
+
+	return SUCCESS_EXIT_CODE
+}
+
+async function main(argv: ReadonlyArray<string>): Promise<void> {
+	process.exitCode = await run_argv(argv)
 }
 
-if (process.argv[1] === fileURLToPath(import.meta.url)) await main()
+if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv)
 
-const github_release_cli = { local_tags }
+const github_release_cli = { local_tags, run_argv }
 export { github_release_cli }

package/scripts/release/github-release-runs.ts

@@ -85,7 +85,7 @@ async function is_release_over(source: RunSource, tag: string): Promise<boolean>
 }
 
 // A lower tag whose publication failed, or finished while no release run is left at work on it,
-// never gains a release: a tag cut before joshuafolkken/kit#3138 was fixed would hold every later one.
+// never gains a release, so waiting on it would hold every later one.
 async function is_release_lost(source: RunSource, tag: string): Promise<boolean> {
 	if (source.workflow === undefined) return false
 

package/scripts/release/release-cli.ts

@@ -1,23 +1,26 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
 import { git_command } from '#scripts/git/git-command'
+import { cli_flags } from '#scripts/lib/cli-flags'
 import { error_text } from '#scripts/lib/error-message'
 import { release_history } from './release-history'
 import { release_plan, type ReleasePlan } from './release-plan'
 import { release_publish } from './release-publish'
 
-// `pnpm josh release` — the one place that decides a version (joshuafolkken/kit#1169).
+// `pnpm josh release` — the one place that decides a version.
 //
 // It does three things and no more: count the merges main has taken since the version last changed,
 // report and stop when that count is zero, and otherwise raise the version by that many minors, open
 // a pull request, merge it and watch for the tag.
 //
-// **It never touches the root checkout** (joshuafolkken/kit#2411). The count is read from
+// **It never touches the root checkout**. The count is read from
 // `origin/<default>`, and the version bump / commit / push happen in a dedicated work tree
 // `release_publish` cuts for the release — so a release can run beside a `backlogrun` (which keeps the
 // root on the default branch) and can start even when the root is dirty or on another branch.
 
 const DRY_RUN_FLAG = '--dry-run'
+const KNOWN_FLAGS: ReadonlyArray<string> = [DRY_RUN_FLAG]
+const COMMAND_NAME = 'release'
 const ARGUMENT_START = 2
 const SUCCESS_EXIT_CODE = 0
 const FAILURE_EXIT_CODE = 1
@@ -73,9 +76,23 @@ function is_dry_run_requested(argv: ReadonlyArray<string>): boolean {
 	return argv.slice(ARGUMENT_START).includes(DRY_RUN_FLAG)
 }
 
+// **Only a known argument reaches the release**. The command publishes,
+// so a `--help` it did not read once started a real release; a help request now prints the usage, and
+// anything else unknown is refused, both before the first fetch.
+async function run_argv(argv: ReadonlyArray<string>): Promise<number> {
+	const answer = cli_flags.answer_help_or_unknown(
+		argv.slice(ARGUMENT_START),
+		KNOWN_FLAGS,
+		COMMAND_NAME,
+	)
+	if (answer !== undefined) return answer
+
+	return await run(is_dry_run_requested(argv))
+}
+
 async function main(): Promise<void> {
 	try {
-		process.exit(await run(is_dry_run_requested(process.argv)))
+		process.exit(await run_argv(process.argv))
 	} catch (error) {
 		console.error(error_text.message_of(error))
 		process.exit(FAILURE_EXIT_CODE)
@@ -84,6 +101,6 @@ async function main(): Promise<void> {
 
 if (process.argv[1] === fileURLToPath(import.meta.url)) void main()
 
-const release_cli = { is_dry_run_requested, run, DRY_RUN_FLAG }
+const release_cli = { is_dry_run_requested, run, run_argv, DRY_RUN_FLAG }
 
 export { release_cli }

package/scripts/release/release-history.ts

@@ -1,15 +1,16 @@
 import { git_command } from '#scripts/git/git-command'
+import { json_value } from '#scripts/lib/json-value'
 import { package_with_version_schema } from '#scripts/lib/schemas'
 import { version_targets } from '#scripts/version/version-targets'
 import { release_plan, type ReleasePlan, type VersionedCommit } from './release-plan'
 
 // Reading main's history for the two numbers a release is made of: where the version last changed,
-// and how many merges have landed since (joshuafolkken/kit#1169).
+// and how many merges have landed since.
 
 const { PACKAGE_JSON } = version_targets
 
 // How far back the search for "the commit that last changed the version" goes, counted in commits
-// that touched `package.json`. Once children stop bumping (joshuafolkken/kit#1486) that file still
+// that touched `package.json`. Once children stop bumping that file still
 // changes for every dependency update, so the base can sit several entries down — but a repository
 // that has taken thirty `package.json` commits without a single release has a different problem, and
 // guessing past that point would be worse than saying so.
@@ -18,8 +19,7 @@ const BASE_SEARCH_LIMIT = 30
 // **Which ref the history is read from.** `josh release` runs on a pulled default branch, so `HEAD`
 // is main there and the default is right. A caller on a feature branch names the ref it means —
 // `origin/main` — because `--first-parent` from a branch tip walks that branch rather than main, and
-// the count would silently omit every merge main took after the branch was cut
-// (joshuafolkken/kit#1486).
+// the count would silently omit every merge main took after the branch was cut.
 const DEFAULT_TIP = 'HEAD'
 
 // The reads this module makes, named so a test can answer them without a git repository. Production
@@ -42,11 +42,7 @@ const git_reader: HistoryReader = {
 function parse_version(content: string | undefined): string | undefined {
 	if (content === undefined) return undefined
 
-	try {
-		return package_with_version_schema.parse(JSON.parse(content)).version
-	} catch {
-		return undefined
-	}
+	return json_value.parse_with(content, package_with_version_schema)?.version
 }
 
 async function read_version_at(
@@ -90,7 +86,7 @@ async function read_base(
 
 // The version `package.json` carries at a git revision. `josh release` reads it from
 // `origin/<default>` rather than from the checkout's own `package.json`, so the number it raises is
-// main's latest even when the run happens in a work tree cut for the release (joshuafolkken/kit#2411).
+// main's latest even when the run happens in a work tree cut for the release.
 async function read_current_version(
 	tip: string = DEFAULT_TIP,
 	reader: HistoryReader = git_reader,

package/scripts/release/release-plan.ts

@@ -1,6 +1,6 @@
 import semver from 'semver'
 
-// What a release is, decided from main's history alone (joshuafolkken/kit#1169).
+// What a release is, decided from main's history alone.
 //
 // **A version is a property of main's history, not of a branch.** `bump-version.ts` reads the local
 // `package.json` and increments it, so two branches cut from the same version both claim the same
@@ -51,7 +51,7 @@ function previous_version_of(
 // **The newest commit whose `package.json` version differs from the version immediately before it.**
 //
 // **A commit that touched `package.json` without moving the version is skipped**, which is what makes
-// this right once children stop bumping (joshuafolkken/kit#1486): a dependency update rewrites the
+// this right once children stop bumping: a dependency update rewrites the
 // file every time and must not be mistaken for a release.
 //
 // **Both sides have to be readable for this to be a version change.** An unreadable neighbor makes
@@ -96,7 +96,7 @@ function short_sha(sha: string): string {
 
 // **The count is the line a person reads**, which is why it is built here rather than at each caller:
 // the release command prints it, and so does anything else that wants to say how much is waiting to
-// ship (joshuafolkken/kit#1169 → "the count of unreleased merges shows somewhere visible").
+// ship.
 function format_pending_line(pending: number): string {
 	return `${PENDING_ICON} unreleased merges on main: ${String(pending)}`
 }

package/scripts/release/release-progress.ts

@@ -9,13 +9,12 @@ import { version_targets } from '#scripts/version/version-targets'
 import { z } from 'zod'
 import { release_tag } from './release-tag'
 
-// The stage lines `pnpm josh release` prints, and the two stages it waits for after the tag
-// (joshuafolkken/kit#3193).
+// The stage lines `pnpm josh release` prints, and the two stages it waits for after the tag.
 //
 // **The tag starts the distribution, it does not finish it.** `publish.yml` runs off the tag:
 // `publish-npm` puts the version on npm and `create-release` opens the GitHub Release once the
-// publishing jobs pass. The command used to stop at the tag and call the release published, ahead of
-// both. It now waits for each, prints one line per stage reached, and prints the completion line only
+// publishing jobs pass. Stopping at the tag would call the release published ahead of both, so the
+// command waits for each, prints one line per stage reached, and prints the completion line only
 // when every stage has — a stage that times out is named with ❌ and the run exits non-zero.
 
 const { PACKAGE_JSON } = version_targets

package/scripts/release/release-publish.ts

@@ -11,8 +11,7 @@ import { release_tag } from './release-tag'
 import { release_worktree } from './release-worktree'
 
 // The write half of `pnpm josh release`: the branch, the commit, the pull request, the merge, the
-// wait for the tag (joshuafolkken/kit#1169) and the watch on what the tag publishes
-// (`release-progress.ts`, joshuafolkken/kit#3193).
+// wait for the tag and the watch on what the tag publishes (`release-progress.ts`).
 //
 // **The merge goes through the same gate every other pull request does.** `wait_for_pr_success` is
 // the merge gate `pnpm josh followup` waits on, and it is called here rather than reimplemented —
@@ -57,7 +56,7 @@ function existing_branch_message(branch_name: string): string {
 	return `\`${branch_name}\` already exists — a previous release attempt got as far as opening it. Finish or delete that pull request and branch, then run \`pnpm josh release\` again.`
 }
 
-// **A remote that cannot be asked is refused, not read as "no branch there"** (joshuafolkken/kit#1641).
+// **A remote that cannot be asked is refused, not read as "no branch there"**.
 // `pnpm josh release` pushes, opens a pull request, merges it and waits for a tag, so it cannot
 // finish without the remote in any case: refusing here is the failure the run was going to have
 // anyway, moved in front of the version write and the commit — which is the whole point of this
@@ -72,9 +71,9 @@ function unreachable_remote_message(branch_name: string): string {
 // it and reach `push`, which then fails with git's non-fast-forward message: the raw error this
 // guard exists to replace, and now after two writes rather than before them.
 //
-// **`git branch --list --remotes` could not answer it, which is why origin is asked directly.** Its
-// short names carry the remote — `origin/x`, never `x` — so the unprefixed pattern this used to pass
-// matched nothing and the remote arm reported "absent" for every branch that has ever existed. The
+// **`git branch --list --remotes` cannot answer it, which is why origin is asked directly.** Its
+// short names carry the remote — `origin/x`, never `x` — so an unprefixed pattern matches nothing and
+// reports "absent" for every branch that has ever existed. The
 // remote-tracking refs it reads are stale anyway, since nothing in this workflow prunes them, so
 // `git_remote_branch.ask` puts the question to origin itself.
 async function is_release_branch_taken(branch_name: string): Promise<boolean> {
@@ -93,7 +92,7 @@ async function refuse_existing_branch(branch_name: string): Promise<void> {
 	throw new Error(existing_branch_message(branch_name))
 }
 
-// **The leftovers go before the guard asks** (joshuafolkken/kit#3058). A run cut off before its
+// **The leftovers go before the guard asks**. A run cut off before its
 // `finally`, or a `worktree add` that failed after creating its branch, leaves a local
 // `release/v<version>` that the guard would otherwise refuse as a release already opened.
 async function clear_the_way(branch_name: string): Promise<void> {
@@ -101,7 +100,7 @@ async function clear_the_way(branch_name: string): Promise<void> {
 	await refuse_existing_branch(branch_name)
 }
 
-// **No `checkout -b` and no branch guard here** (joshuafolkken/kit#2411). The work tree is already
+// **No `checkout -b` and no branch guard here**. The work tree is already
 // sitting on the release branch — `release_worktree.create` cut it that way — and the guard ran
 // before that creation, because `worktree_add` makes the branch local and `branch_exists` would then
 // report every release as already taken. This runs after `process.chdir` into the work tree, so the
@@ -167,7 +166,7 @@ function release_running_message(target: string): string {
 	return `Another \`pnpm josh release\` is running in this repository (lock \`${target}\`); wait for it to finish, then run it again.`
 }
 
-// **One release at a time per repository, held for the whole run** (joshuafolkken/kit#3058).
+// **One release at a time per repository, held for the whole run**.
 // `clear_leftover` removes an unpushed, commit-less release branch, which is also what a live run
 // looks like while it installs dependencies — so it may only run once no other release is alive. The
 // lock answers that: a run cut off before its `finally` leaves a record whose owner is gone, which

package/scripts/release/release-scope-cli.ts

@@ -4,12 +4,11 @@ import { git_followup_pending } from '#scripts/followup/git-followup-pending'
 import { path_decision } from '#scripts/josh/path-decision'
 import { release_plan } from './release-plan'
 
-// **Whether a release is owed is a command's answer, not a judgement** (joshuafolkken/kit#1582).
+// **Whether a release is owed is a command's answer, not a judgement**.
 //
-// joshuafolkken/kit#1169 took the version off the branch and put it behind one command a person
-// types, and nothing ever said *when* to type it. Nothing fails when nobody does — CI green, every
-// pull request merged, every Issue closed — so 53 merges reached main unreleased and no consumer of
-// this package saw one of them.
+// A release is one command a person types, and nothing fails when nobody types it — CI green, every
+// pull request merged, every Issue closed — so merges can pile up on main that no consumer of this
+// package ever sees.
 //
 // **`pnpm josh release --dry-run` cannot be the check.** It refuses off the default branch and on a
 // dirty working tree, and it counts against `HEAD`; every position a run asks the question from is
@@ -37,8 +36,8 @@ const FAILURE_EXIT_CODE = 1
 const NOTHING_PENDING_REASON = 'main has taken no merge since the version last changed'
 const RELEASE_HINT = 'run `pnpm josh release` on the default branch of the primary checkout'
 // **Not `skip`.** An unreadable version, a fetch that could not run or a base the search cannot
-// resolve is not "nothing is waiting to ship", and reporting it as one is how a release goes
-// missing quietly a second time.
+// resolve is not "nothing is waiting to ship", and reporting it as one lets a release go missing
+// quietly.
 const UNKNOWN_REASON = 'the unreleased-merge count could not be read — report unknown, never skip'
 
 type ReleaseScope = typeof REQUIRED_SCOPE | typeof SKIPPED_SCOPE | typeof UNKNOWN_SCOPE
@@ -48,9 +47,8 @@ interface Decision {
 	reason: string
 }
 
-// **The threshold is one, and the position carries the rest.** A release per invocation is the
-// cadence joshuafolkken/kit#1582 asks for — its own complaint is that accumulating makes a single
-// version larger and its contents harder to trace afterwards — so anything above zero is owed. What
+// **The threshold is one, and the position carries the rest.** A release per invocation keeps each
+// version small and its contents traceable, so anything above zero is owed. What
 // keeps this from firing per child of a batch is where the question is asked, which belongs to the
 // procedure rather than to this command.
 function decide(pending: number | undefined): Decision {

package/scripts/release/release-tag.ts

@@ -6,12 +6,11 @@ import { poll, type PollOptions } from '#scripts/lib/poll'
 //
 // Merging is what starts the distribution chain: `ci.yml`'s `notify-auto-tag` dispatches, `auto-tag.yml`
 // creates `v<version>`, and `publish.yml` / `production.yml` run off that tag. Every link after the
-// merge can fail silently, and one of them is known to (joshuafolkken/kit#1481: a later push to main
-// cancels the release commit's CI run, so nothing dispatches and nothing is tagged). An automatic
-// release would have been picked up by the next cycle; a release a person types has no next cycle, so
-// the person walks away believing something shipped when nothing did.
+// merge can fail silently — a later push to main cancels the release commit's CI run, so nothing
+// dispatches and nothing is tagged. A release a person types has no next cycle to pick it up, so the
+// person would walk away believing something shipped when nothing did.
 //
-// So this waits for the tag and **reports its absence as a failure** (joshuafolkken/kit#1169 → §3).
+// So this waits for the tag and **reports its absence as a failure**.
 
 const HTTP_OK = 200
 const TAG_POLL_INTERVAL_MS = 15_000
@@ -50,8 +49,7 @@ async function tag_exists(version: string): Promise<boolean> {
 }
 
 // The poll budget for one watched stage, read from that stage's environment variable. Every stage
-// `josh release` waits on — the tag, npm and the GitHub Release — is tuned the same way
-// (joshuafolkken/kit#3193).
+// `josh release` waits on — the tag, npm and the GitHub Release — is tuned the same way.
 function poll_options_for(
 	timeout_environment: string,
 	sleeper?: (duration_ms: number) => Promise<void>,
@@ -79,7 +77,7 @@ async function wait_for_tag(
 
 // **The failure text says what did not happen rather than what went wrong**, because the command
 // cannot know which link broke — only that the tag it was waiting for is not there, and that nothing
-// downstream of the tag can have run. **The tag is not the release** (joshuafolkken/kit#3193): npm and
+// downstream of the tag can have run. **The tag is not the release**: npm and
 // the GitHub Release follow it, so the success line names only the tag.
 function format_result(version: string, is_tagged: boolean): string {
 	if (is_tagged) return `🏷 Tag ${tag_name(version)} created`

package/scripts/release/release-worktree.ts

@@ -6,7 +6,7 @@ import { lane_install } from '#scripts/lane/lane-install'
 import { lane_leftover } from '#scripts/lane/lane-leftover'
 import { lane_paths } from '#scripts/lane/lane-paths'
 
-// The dedicated linked work tree `pnpm josh release` runs inside (joshuafolkken/kit#2411). The whole
+// The dedicated linked work tree `pnpm josh release` runs inside. The whole
 // point is that the release never touches the root checkout: it is cut fresh from
 // `origin/<default>` as the `release/v<version>` branch, the version bump / commit / push all happen
 // there, and it is removed whichever way the run ends. That lets a release run beside a `backlogrun`
@@ -35,8 +35,8 @@ async function remove(directory: string, branch_name: string): Promise<void> {
 	await git_worktree.branch_delete(branch_name)
 }
 
-// **The dependency install is not optional, and disabling the hook is not the way around it**
-// (joshuafolkken/kit#2411). The release commit goes through lefthook's pre-commit, which runs
+// **The dependency install is not optional, and disabling the hook is not the way around it**.
+// The release commit goes through lefthook's pre-commit, which runs
 // `pnpm exec` / `pnpm josh`, and a sibling work tree has no `node_modules` above it — so the tree
 // needs its own, installed the same way a lane's is. A failed install cleans up the tree it created
 // rather than leaving debris, then reports what git printed.
@@ -54,7 +54,7 @@ async function install_or_clean(directory: string, branch_name: string): Promise
 // add --no-track -b release/v<version> <dir> origin/<default>`, which `worktree_add` already spells
 // when it is given a start point.
 //
-// **A failed add takes back the branch it made** (joshuafolkken/kit#3058). `git worktree add -b`
+// **A failed add takes back the branch it made**. `git worktree add -b`
 // creates the branch before it looks at the path, so an add refused for a path that already exists
 // still leaves `release/v<version>` behind — and the next run's branch guard then refuses that name
 // as a release already opened. The guard ran before this call and found no such branch, so one
@@ -80,7 +80,7 @@ async function create(branch_name: string): Promise<string> {
 	return directory
 }
 
-// **A run that never reached its `finally` leaves its tree and branch behind** (joshuafolkken/kit#3058)
+// **A run that never reached its `finally` leaves its tree and branch behind**
 // — a Ctrl-C, a closed terminal — and every later release then fails on them until a person removes
 // both by hand. They are cleared here only when clearing loses nothing: a release branch origin does
 // not have and that carries no commit beyond `origin/<default>`. Uncommitted edits in the tree are

package/scripts/repo/auto-merge-setting-logic.ts

@@ -3,13 +3,11 @@ import { repo_setting, type RepoSettingStatus } from './repo-setting'
 // GitHub's repository-level "Allow auto-merge" setting, as reported by the `allow_auto_merge` field
 // of `GET /repos/{owner}/{repo}`.
 //
-// joshuafolkken/kit#834 added `.github/workflows/dependabot-auto-merge.yml` to the distributed
-// files, so a synced consumer now runs `gh pr merge --auto` on every github-actions patch and minor
-// bump. That command needs this setting: without it the step fails with `Auto-merge is not allowed
-// for this repository`, and the pull request sits green and unmerged — which is the exact state
-// joshuafolkken/app-kit#184 was found in, and the same defect kit itself hit in
-// joshuafolkken/kit#802. The setting is off by default, so distributing the workflow without
-// reporting it would hand every consumer a workflow that never merges anything.
+// `.github/workflows/dependabot-auto-merge.yml` is a distributed file, so a synced consumer runs
+// `gh pr merge --auto` on every github-actions patch and minor bump. That command needs this
+// setting: without it the step fails with `Auto-merge is not allowed for this repository`, and the
+// pull request sits green and unmerged. The setting is off by default, so distributing the workflow
+// without reporting it would hand every consumer a workflow that never merges anything.
 type AutoMergeStatus = RepoSettingStatus
 
 const SETTING_LABEL = 'Repository auto-merge'
@@ -19,8 +17,8 @@ const WORKFLOW_PATH = '.github/workflows/dependabot-auto-merge.yml'
 
 // The remediation for `disabled`, addressed at the repository the report actually resolved. kit
 // prints it and never runs it: changing a repository setting is outward-facing, needs admin scope,
-// and is the maintainer's call — the same line joshuafolkken/kit#805 drew for
-// `automated-security-fixes`, which is why `josh doctor --fix` does not enable this either.
+// and is the maintainer's call — the same line drawn for `automated-security-fixes`, which is why
+// `josh doctor --fix` does not enable this either.
 function enable_command(repo: string | undefined): string {
 	return `gh api -X PATCH repos/${repo_setting.command_target(repo)} -f ${ALLOW_AUTO_MERGE_FIELD}=true`
 }

package/scripts/repo/auto-merge-setting.ts

@@ -2,7 +2,7 @@ import { auto_merge_setting_logic, type AutoMergeStatus } from './auto-merge-set
 import { repo_setting } from './repo-setting'
 
 // Read the repository's "Allow auto-merge" setting. Never throws and never propagates a non-zero
-// exit: an unreadable answer is a reported status, not a command failure (joshuafolkken/kit#834).
+// exit: an unreadable answer is a reported status, not a command failure.
 //
 // The whole repository object is requested rather than a `--jq` projection, because a projection
 // cannot distinguish a field that is `false` from a field the response never carried — and that

package/scripts/repo/repo-setting.ts

@@ -3,16 +3,16 @@ import { PROJECT_ROOT } from '#scripts/init/init-paths'
 
 // The shared half of every "report a GitHub repository setting kit cannot write" check.
 //
-// Two such checks exist — `automated-security-fixes` (joshuafolkken/kit#805) and `allow_auto_merge`
-// (joshuafolkken/kit#834) — and they agree on everything that is not wording: the same bounded
+// Two such checks exist — `automated-security-fixes` and `allow_auto_merge`
+// — and they agree on everything that is not wording: the same bounded
 // `gh api` call, the same rule that an answer which cannot be read is never reported as a negative
 // answer, and the same blank-line-separated report block. That agreement is the contract, so it
 // lives here once rather than being re-derived per setting.
 type RepoSettingStatus = 'enabled' | 'disabled' | 'unreadable'
 
 // Bounded, unlike the repository lookup: these calls only decide what a report *says*, never what
-// gets written, so a timeout degrades to `could not be read` and costs nothing. `josh doctor` made
-// no network calls at all before joshuafolkken/kit#805, and this keeps it prompt.
+// gets written, so a timeout degrades to `could not be read` and costs nothing, and keeps
+// `josh doctor` prompt.
 const GH_TIMEOUT_MS = 5000
 
 // A literal `<owner>/<repo>` would be unusable when pasted into a shell, where `<` redirects — but

package/scripts/repo/repository-labels.ts

@@ -2,7 +2,7 @@ import { git_gh_exec } from '#scripts/gh/git-gh-exec'
 import { REPOSITORY_LABELS, type LabelDefinition } from '#scripts/issue/issue-labels'
 
 // Creates the labels kit's workflow and the distributed `pr-classification.yml` rely on, and only
-// those the repository is missing (joshuafolkken/kit#2797). The one place labels are created: `josh
+// those the repository is missing. The one place labels are created: `josh
 // start` provisions a new repository through it and `josh sync` brings every existing one up to date.
 //
 // Labels already present are left as they are, so a repository that recolored one keeps its choice

package/scripts/repo/required-checks-logic.ts

@@ -3,11 +3,11 @@ import { z } from 'zod'
 
 // The status checks kit's distributed workflows report, keyed by the workflow that reports them —
 // the single source `josh ruleset:check` and `josh doctor` compare a repository's required status
-// checks against (joshuafolkken/kit#3012). Each name is the job's `name:`, the string a ruleset's
+// checks against. Each name is the job's `name:`, the string a ruleset's
 // required check is matched by; `required-checks-logic.test.ts` reads it back off the workflows.
 //
-// `E2E` belongs here even though `josh followup` deliberately does not wait on it
-// (joshuafolkken/kit#991): a ruleset counts a skipped job as passing, and the job is skipped when the
+// `E2E` belongs here even though `josh followup` deliberately does not wait on it:
+// a ruleset counts a skipped job as passing, and the job is skipped when the
 // project has no E2E suite, so requiring it never blocks a merge — it only refuses a red one.
 interface WorkflowChecks {
 	workflow: string

package/scripts/repo/required-checks-report.ts

@@ -2,7 +2,7 @@ import { repo_setting } from './repo-setting'
 import type { RequiredSource } from './required-checks-logic'
 
 // What one read of a repository's required status checks found, against what kit's distributed
-// workflows report (joshuafolkken/kit#3012).
+// workflows report.
 interface RequiredChecksReport {
 	repo: string | undefined
 	branch: string | undefined

package/scripts/repo/ruleset-check-cli.ts

@@ -7,7 +7,7 @@ import { required_checks_report, type RequiredChecksReport } from './required-ch
 import { ruleset_check } from './ruleset-check'
 
 // `josh ruleset:check [--apply]` — say whether the default branch requires every status check kit's
-// distributed workflows report, and with `--apply` add the missing ones (joshuafolkken/kit#3012).
+// distributed workflows report, and with `--apply` add the missing ones.
 // Changing a repository setting is outward-facing, so the write happens only on the flag a person
 // typed; `josh sync` and `josh doctor` never pass it. Exits non-zero while anything is left to do.
 

package/scripts/repo/ruleset-check.ts

@@ -8,7 +8,7 @@ import { required_checks_logic, type ApiRead, type RequiredSource } from './requ
 import { required_checks_report, type RequiredChecksReport } from './required-checks-report'
 
 // Read a repository's required status checks on its default branch and compare them with the checks
-// kit's distributed workflows report (joshuafolkken/kit#3012). Every read degrades to `unreadable`
+// kit's distributed workflows report. Every read degrades to `unreadable`
 // rather than throwing; the one write, `apply_missing`, runs only on `josh ruleset:check --apply`.
 
 function read_api(api_path: string): string | undefined {

package/scripts/report/report-format-reference.ts

@@ -0,0 +1,26 @@
+// Where a fixed-shape failure points its reader. `report:lint`, `test:declared
+// --match` and the live-evidence check each said what was missing but not where the shape is written,
+// so the reader grepped for it. **The document and its headings are named once, here**, and every
+// failure builds its pointer from them — a renamed heading then fails this module's test rather than
+// sending the reader to a section that no longer exists.
+
+const REPORT_FORMAT_PATH = 'prompts/collaboration-workflow/report-format.md'
+const SUMMARY_RULES_HEADING = '作業前サマリはいつ・どう出すか'
+const SUMMARY_TEMPLATE_HEADING = '作業前サマリ（セッション向け・`JOSH_SESSION_LANG` の言語）'
+const COMPLETION_REPORT_HEADING = '完了報告（セッション向け）'
+
+// The heading goes in single quotes in the runnable form: the template heading carries backticks,
+// which a double-quoted shell argument would run as a command substitution.
+function pointer(heading: string): string {
+	return `${REPORT_FORMAT_PATH} → "${heading}" (read it: pnpm josh doc:section ${REPORT_FORMAT_PATH} '${heading}')`
+}
+
+const report_format_reference = {
+	COMPLETION_REPORT_HEADING,
+	pointer,
+	REPORT_FORMAT_PATH,
+	SUMMARY_RULES_HEADING,
+	SUMMARY_TEMPLATE_HEADING,
+}
+
+export { report_format_reference }

package/scripts/report/report-lint-cli.ts

@@ -4,7 +4,7 @@ import { fileURLToPath } from 'node:url'
 import { report_lint } from './report-lint'
 
 // `josh report:lint` — read a two-layer work summary candidate from stdin and print `ok`, or the
-// mechanical violations one per line, exiting non-zero so it works as a gate (joshuafolkken/kit#2123).
+// mechanical violations one per line, exiting non-zero so it works as a gate.
 
 const SUCCESS_EXIT_CODE = 0
 const FAILURE_EXIT_CODE = 1
@@ -27,7 +27,7 @@ function run(summary: string): number {
 		return SUCCESS_EXIT_CODE
 	}
 
-	console.error(violations.join('\n'))
+	console.error(report_lint.with_reference(violations).join('\n'))
 
 	return FAILURE_EXIT_CODE
 }