@joshuafolkken/kit 1.1229.0 → 1.1370.0

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
 }

package/scripts/report/report-lint.ts

@@ -1,10 +1,14 @@
+import { report_format_reference } from './report-format-reference'
+
 // The mechanical half of the two-layer work summary (`CLAUDE.md` Step 0, single-sourced in
 // `prompts/collaboration-workflow/report-format.md`) is a fixed shape, yet only an advisory echo in
 // the `UserPromptSubmit` hook ever mentions it and nothing reads the summary an agent actually
 // wrote. This checks the half a machine can: the labels are present, the overview lines stay inside
 // their length, nothing wraps the summary in a code fence, and no file path or CLI flag leaks into
 // the overview. The judgement half — whether the subject is concrete — is deliberately left out,
-// because a machine cannot answer it (joshuafolkken/kit#2123).
+// because a machine cannot answer it.
+
+const TEMPLATE_HEADING = report_format_reference.SUMMARY_TEMPLATE_HEADING
 
 // The session-facing labels are Japanese because that is the form the summary is written in
 // (`JOSH_SESSION_LANG` defaults to `ja`); `report-format.md`'s template is the single source and the
@@ -33,7 +37,7 @@ const CLI_FLAG_PATTERN = /(?:^|\s)--[a-z]/u
 const BOLD_MARKER = '**'
 const LEADING_LABEL_PUNCTUATION = /^[\s:：]+/u
 
-// The case-based test declaration (joshuafolkken/kit#2246): the changes section carries a first tier
+// The case-based test declaration: the changes section carries a first tier
 // of fixed-vocabulary cases — each non-applicable one crossed out with a reason — and a second tier
 // of at-least-three "if it breaks" conditions. This checks the mechanical half: the two tier markers
 // are present, an N/A cross-out carries a reason, and the second tier holds enough conditions (or the
@@ -235,8 +239,18 @@ function lint_report(summary: string): ReadonlyArray<string> {
 	]
 }
 
+// The violations followed by one line naming where the summary's shape is written
+// — the violations say what is wrong, the pointer where the right shape is.
+// A clean summary stays empty, so `ok` is still the only output of a pass.
+function with_reference(violations: ReadonlyArray<string>): ReadonlyArray<string> {
+	if (violations.length === 0) return violations
+
+	return [...violations, `→ the template: ${report_format_reference.pointer(TEMPLATE_HEADING)}`]
+}
+
 const report_lint = {
 	lint_report,
+	with_reference,
 	REQUIRED_LABELS,
 	MAX_OVERVIEW_CHARS,
 	CASE_LABEL,

package/scripts/review/disposition-cli.ts

@@ -2,8 +2,8 @@
 import { fileURLToPath } from 'node:url'
 import { disposition } from './disposition-logic'
 
-// `josh disposition <path...>` — the machine half of the three-way review disposition
-// (joshuafolkken/kit#2181). It prints `runtime` when any named path reaches a runtime path — a
+// `josh disposition <path...>` — the machine half of the three-way review disposition.
+// It prints `runtime` when any named path reaches a runtime path — a
 // runtime code path, a distributed artifact a consumer reads, or the verification guarding either —
 // and `non-runtime` when every path is inert. `prompts/review.md` → "Three-way disposition after the
 // cap" leaves the run one judgement after this: whether the finding is a confirmed defect.

package/scripts/review/disposition-logic.ts

@@ -1,7 +1,7 @@
 import { review_level } from './review-level'
 
 // Whether a review finding reaches a runtime path — the half of the three-way disposition a machine
-// can answer (joshuafolkken/kit#2181). `prompts/review.md` → "Three-way disposition after the cap"
+// can answer. `prompts/review.md` → "Three-way disposition after the cap"
 // routes a non-High finding to branch 2 (file it) only when it is a **confirmed defect that reaches a
 // runtime code path**. "Reaches" is read exactly as the review-level rubric reads it — a runtime code
 // path, a distributed artifact a consumer reads, or the verification guarding either — which is the

package/scripts/review/live-evidence.ts

@@ -1,11 +1,11 @@
 import { git_gh_command } from '#scripts/gh/git-gh-command'
 import { git_command } from '#scripts/git/git-command'
 import { reproduction_measure } from '#scripts/issue/reproduction-measure'
+import { report_format_reference } from '#scripts/report/report-format-reference'
 import { test_declared_logic, type Verdict } from '#scripts/test/test-declared-logic'
 
-// joshuafolkken/kit#2446. "Done" meant lint, types and unit tests were green and the review found
-// nothing — proof the code is right in isolation, never that the feature works where it runs. The
-// recent defects (#2402, #2419, #2393) all came through that gap. **This is the seam where it closes**:
+// Lint, types and unit tests green and a review that found nothing prove the code is right in
+// isolation, never that the feature works where it runs. **This is the seam where that gap closes**:
 // a runtime change merges only once its pull request carries the acceptance criteria run for real —
 // the command and the output it actually printed, in the evidence section `EVIDENCE_HEADING` names.
 //
@@ -15,6 +15,9 @@ import { test_declared_logic, type Verdict } from '#scripts/test/test-declared-l
 // reproduction-section parser, so a prose "confirmed it works" is refused here exactly as it is there.
 
 const EVIDENCE_HEADING = '## 実機証跡'
+// The shape the section needs and where it is written down, so a refusal
+// names the format instead of leaving the reader to search for it.
+const EVIDENCE_FORMAT = `under ${EVIDENCE_HEADING}, a backticked command followed by a fenced block holding the output it actually printed (prose such as "confirmed" is not accepted) — format: ${report_format_reference.pointer(report_format_reference.COMPLETION_REPORT_HEADING)}`
 
 function verdict_for(paths: ReadonlyArray<string>, body: string | undefined = ''): Verdict {
 	if (test_declared_logic.runtime_files(paths).length === 0) return 'exempt'
@@ -49,12 +52,12 @@ async function check(branch_name: string): Promise<Verdict> {
 function refusal_message(): string {
 	return [
 		`Merge refused: this pull request changes runtime code but its body has no ${EVIDENCE_HEADING} section.`,
-		'Run the acceptance criteria for real, then add the section: a backticked command followed by a',
-		'fenced block holding the output it actually printed (prose such as "confirmed" is not accepted).',
+		'Run the acceptance criteria for real, then add the section:',
+		EVIDENCE_FORMAT,
 		'Update the body with `gh api -X PATCH repos/{owner}/{repo}/pulls/<N> -F body=@<path>`, then re-run.',
 	].join('\n')
 }
 
-const live_evidence = { EVIDENCE_HEADING, check, refusal_message, verdict_for }
+const live_evidence = { EVIDENCE_FORMAT, EVIDENCE_HEADING, check, refusal_message, verdict_for }
 
 export { live_evidence }

package/scripts/review/review-attest-cli.ts

@@ -3,8 +3,7 @@ import { fileURLToPath } from 'node:url'
 import { review_attest, type AttestVerdict } from './review-attest'
 import { review_checkout } from './review-checkout'
 
-// `josh review:attest` — the two halves of the checkout contract `josh review:brief` opens
-// (joshuafolkken/kit#1522).
+// `josh review:attest` — the two halves of the checkout contract `josh review:brief` opens.
 //
 // **`josh review:attest <nonce>` is run by the review**, from the checkout it actually read. It
 // compares that checkout against the one the brief described and exits non-zero when they differ, so

package/scripts/review/review-attest.ts

@@ -6,7 +6,7 @@ import { stamp_file } from '#scripts/josh/stamp-file'
 import { json_value } from '#scripts/lib/json-value'
 import { review_checkout, type ReviewCheckout } from './review-checkout'
 
-// The record that says which checkout a `/code-review` actually read (joshuafolkken/kit#1522).
+// The record that says which checkout a `/code-review` actually read.
 //
 // **The root cause is not ours to fix.** `/code-review` is forked by the harness and inherits the
 // session's working directory; nothing in this repository decides that. What *is* ours is the
@@ -242,7 +242,7 @@ function is_written_since(source: string, taken_at: string): boolean {
 	}
 }
 
-// **Whether the last briefed review of this branch finished** (joshuafolkken/kit#2945). A ship resumed
+// **Whether the last briefed review of this branch finished**. A ship resumed
 // after a stop re-issues round 1, and without this answer it briefed the whole change again — the
 // files the finished review had just read, re-read at full cost. It is asked before `record_target`
 // mints the next nonce, since that call drops the record it reads. The branch must match: the pointer
@@ -265,7 +265,7 @@ function is_reviewed_on(checkout: ReviewCheckout, findings_path: string, root?:
 }
 
 // Whether a record written at `written_at` belongs to the brief the pointer names rather than an earlier
-// one (joshuafolkken/kit#2945): that brief writes it right after minting the pointer. ISO timestamps
+// one: that brief writes it right after minting the pointer. ISO timestamps
 // order as strings.
 function is_briefed_since(written_at: string, root?: string): boolean {
 	const pointer = read_pointer(root)