@joshuafolkken/kit 1.1229.0 → 1.1370.0

package/scripts/discovery/repo-origin.ts

@@ -3,7 +3,7 @@
 // Kept separate from the map that consumes it (`repo-map-logic.ts`) because the shapes a remote can
 // take are the part with real variety: a single machine's siblings were measured carrying SSH,
 // an SSH host alias, HTTPS with embedded credentials and a trailing slash, and plain HTTPS — all
-// four pointing at the same repository (joshuafolkken/kit#869).
+// four pointing at the same repository.
 
 // A repository's identity on GitHub. The `owner` half is what the discovery map filters on, so it is
 // derived here from the remote and never from a directory name.
@@ -88,7 +88,7 @@ function parse_url_like(url: string): RepoIdentity | undefined {
 
 // `owner/repo` for a GitHub remote, or nothing for every other remote. Returning nothing is the
 // exclusion the owner restriction depends on: a self-hosted or third-party host never reaches the
-// owner comparison at all (joshuafolkken/kit#869).
+// owner comparison at all.
 function parse_origin_url(url: string): RepoIdentity | undefined {
 	const trimmed = url.trim()
 	if (trimmed === '') return undefined
@@ -147,7 +147,7 @@ function section_groups(lines: ReadonlyArray<string>): Array<Array<string>> {
 }
 
 // The `url` of every `[remote "…"]` section, in config order — the candidates `gh` picks its base
-// repository from when it expands the `{owner}` placeholder (joshuafolkken/kit#3188).
+// repository from when it expands the `{owner}` placeholder.
 function parse_remote_urls_from_config(content: string): Array<string> {
 	const lines = content.split('\n').map((line) => line.trim())
 

package/scripts/discovery/repo-party-cli.ts

@@ -2,8 +2,8 @@
 import { fileURLToPath } from 'node:url'
 import { repo_party, type Party } from './repo-party'
 
-// `josh repo:party [<owner/repo>]` — say whether a repository is first-party or third-party
-// (joshuafolkken/kit#2122). A command rather than a paragraph, for the reason `josh latest:scope` is
+// `josh repo:party [<owner/repo>]` — say whether a repository is first-party or third-party.
+// A command rather than a paragraph, for the reason `josh latest:scope` is
 // one: a rule an agent applies from memory is a rule an agent can talk itself out of, and this one is
 // argued against at exactly the moment a workflow wants to write to another repository.
 //

package/scripts/discovery/repo-party.ts

@@ -1,7 +1,7 @@
 import { repo_discovery } from './repo-discovery'
 import { repo_origin } from './repo-origin'
 
-// **First-party vs third-party, computed rather than judged** (joshuafolkken/kit#2122). `CLAUDE.md`
+// **First-party vs third-party, computed rather than judged**. `CLAUDE.md`
 // and `upstream-interrupt.md` both declared the test mechanical — owner equality between the target
 // repository and the session's — yet nothing computed it: three prose spots restated the manual
 // `gh api … --jq .owner.login`, and whether an owner had actually been read was left to trust. This is
@@ -56,7 +56,7 @@ function remote_owners(repository_path: string): Array<string | undefined> {
 		.map((url) => repo_origin.parse_origin_url(url)?.owner)
 }
 
-// Every owner `gh` could expand the `{owner}` placeholder to (joshuafolkken/kit#3188). `GH_REPO`
+// Every owner `gh` could expand the `{owner}` placeholder to. `GH_REPO`
 // (`[HOST/]OWNER/REPO`) overrides the remotes outright; otherwise `gh` picks its base repository among
 // the GitHub remotes — `upstream` ahead of `origin`, or a `gh repo set-default` choice — so in a fork
 // checkout it can expand to the upstream owner. Answering the whole candidate set rather than

package/scripts/doctor/doctor-consumer.ts

@@ -7,7 +7,7 @@ import { PROBE_TIMEOUT_MS } from '#scripts/lib/timeouts'
 import { KIT_PACKAGE_NAME } from '#scripts/version/kit-descriptor'
 import { z } from 'zod'
 
-// The consumer-setup checks `josh doctor` runs in a repository that installs kit (joshuafolkken/kit#1930).
+// The consumer-setup checks `josh doctor` runs in a repository that installs kit.
 // Each failure was a way the distribution went silently wrong: the plugin never installed so skills
 // were missing, `core.hooksPath` set so lefthook installed nothing, the `CLAUDE.md` pointer resolving
 // to a file that is not there before `pnpm install`, and secretlint not runnable so the pre-commit

package/scripts/doctor/doctor-io.ts

@@ -16,8 +16,7 @@ const AUTO_MERGE_WORKFLOW_PATH = '.github/workflows/dependabot-auto-merge.yml'
 // The command that needs the repository's "Allow auto-merge" setting, and the only thing in the
 // workflow that does. Matching it rather than the filename is what keeps the report tied to the
 // prerequisite: a file of that name which never calls `--auto` creates no prerequisite, and a
-// consumer's own auto-merge workflow which does creates the same one kit's does
-// (joshuafolkken/kit#834).
+// consumer's own auto-merge workflow which does creates the same one kit's does.
 const AUTO_MERGE_COMMAND = 'gh pr merge --auto'
 const YAML_COMMENT_PREFIX = '#'
 
@@ -45,7 +44,7 @@ function resolve_pnpm_global_josh(): string | undefined {
 
 // Whether the working directory is provably *outside* a git work tree. Purely local — no network,
 // and it does not depend on `gh` being installed or authenticated, which is what makes it usable to
-// decide whether a repository-scoped check applies at all (joshuafolkken/kit#805).
+// decide whether a repository-scoped check applies at all.
 //
 // An empty root from a successful run is not an answer, so it is undetermined rather than inside.
 function classify_top_level(top_level: string): GitTopLevel {
@@ -67,8 +66,8 @@ function classify_git_failure(exit_code: number | undefined, stderr: string): Gi
 // directory instead would skip the check in every subdirectory of a consumer repository.
 //
 // `outside` and `undetermined` are kept apart deliberately: only proof of absence may skip the
-// caller's check, because reporting an unknown as a clean result is the false all-clear
-// joshuafolkken/kit#805 exists to remove. See the two classifiers above for what proves what.
+// caller's check, because reporting an unknown as a clean result is a false all-clear. See the two
+// classifiers above for what proves what.
 function resolve_git_top_level(): GitTopLevel {
 	// The C locale `toplevel` asks under is what keeps the stderr match below from failing on a
 	// translated message and bringing the spurious warning back.
@@ -162,7 +161,7 @@ function has_marked_project_file(
 }
 
 // Whether the project has received kit's `.github/dependabot.yml`. The npm entry's
-// `open-pull-requests-limit: 0` is what creates the prerequisite (joshuafolkken/kit#803), so that is
+// `open-pull-requests-limit: 0` is what creates the prerequisite, so that is
 // what is matched.
 function has_distributed_dependabot_config(start: string, boundary?: string): boolean {
 	return has_marked_project_file(start, DEPENDABOT_CONFIG_PATH, boundary, (content) =>
@@ -181,7 +180,7 @@ function is_auto_merge_command_line(line: string): boolean {
 }
 
 // Whether the project runs a Dependabot auto-merge workflow. `gh pr merge --auto` is what needs the
-// repository's "Allow auto-merge" setting, so that is what is matched (joshuafolkken/kit#834).
+// repository's "Allow auto-merge" setting, so that is what is matched.
 function has_auto_merge_workflow(start: string, boundary?: string): boolean {
 	return has_marked_project_file(start, AUTO_MERGE_WORKFLOW_PATH, boundary, (content) =>
 		content.split('\n').some((line) => is_auto_merge_command_line(line)),

package/scripts/doctor/doctor-logic.ts

@@ -79,7 +79,7 @@ function decide_reclaim(
 
 // The discovered map, as `josh doctor` prints it. Printing it is what makes a wrong map noticeable:
 // the map decides which checkouts other commands write to, and a silent one would only be found by
-// the write landing in the wrong place (joshuafolkken/kit#869).
+// the write landing in the wrong place.
 function format_repository_map(map: ReadonlyMap<string, string>): string {
 	if (map.size === 0) return [REPOSITORY_MAP_HEADING, NO_REPOSITORIES_FOUND].join('\n')
 	const rows: Array<string> = []

package/scripts/doctor/doctor-ports.ts

@@ -4,7 +4,7 @@ import { lane_environment } from '#scripts/lane/lane-environment'
 import { file_reader } from '#scripts/lib/read-file'
 
 // Each discovered repository's port seed and the dev / preview ports it resolves to, plus which
-// repositories share a seed (joshuafolkken/kit#1494).
+// repositories share a seed.
 //
 // The formula `seed × 10 + lane` makes distinct seeds occupy disjoint bands, but two repositories on
 // the *same* seed still collide — as do the many that never set one and sit together on seed 0. That

package/scripts/doctor/doctor.ts

@@ -21,8 +21,7 @@ const NOT_ON_PATH = '(not on PATH)'
 const SELF_DIR = path.dirname(fileURLToPath(import.meta.url))
 // Deliberately smaller than the setting query's budget: the two run back to back, so `doctor`'s
 // worst case is the git probe plus this plus GH_TIMEOUT_MS — 2000 + 3000 + 5000, ten seconds. That
-// keeps a command which made no network calls at all before joshuafolkken/kit#805 prompt enough to
-// stay usable when the network is unreachable.
+// keeps the command prompt enough to stay usable when the network is unreachable.
 const REPO_LOOKUP_TIMEOUT_MS = 3000
 
 // Where the local applicability gates look for the artifacts that decide whether a report applies.
@@ -108,7 +107,7 @@ function resolve_gate_scope(git: GitTopLevel): GateScope | undefined {
 }
 
 // Which prerequisites this repository actually has, decided locally so the answer does not depend on
-// `gh` working. The two are independent: a consumer synced before joshuafolkken/kit#834 has the
+// `gh` working. The two are independent: a consumer synced from an older kit can have the
 // Dependabot config and no auto-merge workflow, and a repository that only ever added an auto-merge
 // workflow of its own has the second prerequisite and not the first.
 function resolve_applicable(scope: GateScope): ApplicableSettings {
@@ -125,7 +124,7 @@ function has_any_applicable(applicable: ApplicableSettings): boolean {
 }
 
 // Everything past the gate reports, including a failed lookup: `could not be read` is informative
-// while silence is the false all-clear joshuafolkken/kit#805 exists to remove.
+// while silence would be a false all-clear.
 function report_applicable_settings(
 	applicable: ApplicableSettings,
 	repo: string | undefined,
@@ -140,7 +139,7 @@ function report_applicable_settings(
 
 // Last, and after the local diagnosis: this is the only part of `doctor` that touches the network,
 // and `doctor` is what a user runs when the install is already broken. Offline or behind a hanging
-// proxy the PATH report and `--fix` must still complete (joshuafolkken/kit#805).
+// proxy the PATH report and `--fix` must still complete.
 //
 // Applicability is decided by the artifact rather than by the directory. `doctor` diagnoses the
 // global install and is routinely run from a home directory or from a clone of an unrelated project;
@@ -166,7 +165,7 @@ function report_repository_settings(git: GitTopLevel): void {
 
 // The discovery map, printed for whichever repository `doctor` is standing in. Nothing is printed
 // from outside a repository: discovery is anchored on the current repository's own owner, so without
-// one there is no map to be right or wrong about (joshuafolkken/kit#869).
+// one there is no map to be right or wrong about.
 function report_repository_map(git: GitTopLevel): void {
 	if (git.state !== 'inside') return
 
@@ -177,7 +176,7 @@ function report_repository_map(git: GitTopLevel): void {
 }
 
 // Each discovered repository's port seed and the ports it resolves to, and any seed shared by more
-// than one of them (joshuafolkken/kit#1494). Anchored on the same map as `report_repository_map`, so
+// than one of them. Anchored on the same map as `report_repository_map`, so
 // it prints from inside a repository and nowhere else.
 function report_port_seeds(git: GitTopLevel): void {
 	if (git.state !== 'inside') return
@@ -203,7 +202,7 @@ function consumer_root(git: GitTopLevel): string {
 	return git.state === 'inside' ? git.top_level : PROJECT_ROOT
 }
 
-// The port seed table is opt-in since joshuafolkken/kit#1930: it discovers every sibling repository
+// The port seed table is opt-in: it discovers every sibling repository
 // and was the slowest, least diagnostic part of the default output. `--ports` brings it back.
 function run_reports(ctx: DoctorContext, git: GitTopLevel, options: DoctorOptions): void {
 	print_report(ctx)
@@ -220,7 +219,7 @@ function main(): void {
 
 	// Resolved once and shared: `doctor` is what a user runs when things are already broken, and a
 	// second `git rev-parse` would add a second timeout to a command whose whole contract is to stay
-	// responsive when git itself is hanging (joshuafolkken/kit#805).
+	// responsive when git itself is hanging.
 	const git = doctor_io.resolve_git_top_level()
 
 	run_reports(ctx, git, options)

package/scripts/document/backlogrun-parent-read-set.ts

@@ -1,4 +1,4 @@
-// What a `backlogrun` parent reads, and what that trims from a full read (joshuafolkken/kit#2256).
+// What a `backlogrun` parent reads, and what that trims from a full read.
 //
 // **The parent is the scheduler, and it never implements.** It reads `backlog:next`, dispatches each
 // child in its own delegated `fullrun` unit, opens lanes, runs the progress watcher and the hand-off,
@@ -17,9 +17,8 @@ import { read_set_trim } from './read-set-trim'
 const BACKLOGRUN = 'backlogrun'
 
 // **The `SKILL.md` sections the `backlogrun` parent never uses.** It edits no rule mid-run (§3, read
-// only on an editing turn). The implementer-only rules it used to skip — the `into` target, the
-// working-tree hold, the Issue's comments — are single rows of §2's table since joshuafolkken/kit#3174,
-// so there is no section of them left to trim.
+// only on an editing turn). The implementer-only rules — the `into` target, the working-tree hold,
+// the Issue's comments — are single rows of §2's table, so there is no section of them to trim.
 const UNUSED_SKILL_SECTIONS: ReadonlyArray<string> = [
 	'3. What stays resident, and what is read from here',
 ]
@@ -30,9 +29,9 @@ const SKIPPED_POINT_OF_USE: ReadonlySet<string> = new Set<string>()
 
 // **The parent runs the end-of-run retrospective** (`retrospective.md`) when `run:step` prints it, but its
 // manifest names `retrospective.md` only through `backlogrun-steps.md` — one hop further than the
-// derivation follows — so the parent's reach names it (joshuafolkken/kit#3078). **It polls a
+// derivation follows — so the parent's reach names it. **It polls a
 // delegated unit that went silent** through `backlogrun-recovery.md`, named only from
-// `backlogrun-child.md`, so the reach names that too (joshuafolkken/kit#3175).
+// `backlogrun-child.md`, so the reach names that too.
 const REACHED_POINT_OF_USE: ReadonlySet<string> = new Set([
 	'retrospective.md',
 	'backlogrun-recovery.md',

package/scripts/document/bash-output-cap.ts

@@ -1,10 +1,8 @@
-// The character cap a Bash result is truncated at, read from the settings file rather than restated
-// (joshuafolkken/kit#1797). Every entry-read document is larger than it, so a `cat` of one hands back
-// a middle-truncated preview and the file is then read a second time — the two wasted requests #1797
-// measured. A number copied into code would be a second declaration of the cap and would drift the
-// first time the settings changed; the harness's own default stands in only where the file declares
-// nothing. Split out of `entry-read-set.ts` in joshuafolkken/kit#2161 to keep that file under its
-// line ceiling.
+// The character cap a Bash result is truncated at, read from the settings file rather than restated.
+// Every entry-read document is larger than it, so a `cat` of one hands back
+// a middle-truncated preview and the file is then read a second time. A number copied into code would
+// be a second declaration of the cap and would drift the first time the settings changed; the
+// harness's own default stands in only where the file declares nothing.
 
 import path from 'node:path'
 import { document_section } from './document-section'

package/scripts/document/capped-print-part.ts

@@ -1,7 +1,7 @@
 import path from 'node:path'
 
 // Where `capped-print.ts` writes the parts of an over-cap output, and how a path is recognized as one
-// of them (joshuafolkken/kit#3332). Both halves live here so the writer and the investigation guard,
+// of them. Both halves live here so the writer and the investigation guard,
 // which must not count a read of a part as reading the Issue's subject, share one spelling of the
 // shape — kept free of the writer's own imports, since the guard runs as a hook on every tool call.
 

package/scripts/document/capped-print.ts

@@ -6,7 +6,7 @@ import { bash_output_cap_reader } from './bash-output-cap'
 import { capped_print_part } from './capped-print-part'
 
 // Prints a command's output whole when it fits under the Bash output cap, and as part files when it
-// does not (joshuafolkken/kit#3143). Past `BASH_MAX_OUTPUT_LENGTH` Claude Code saves the output and
+// does not. Past `BASH_MAX_OUTPUT_LENGTH` Claude Code saves the output and
 // hands back a 2 KB preview, and the run spends a turn reading the saved file — 224 overflows and 132
 // re-reads over one day's sessions, `doc:section` and `issue:read` the two most frequent `josh` sources.
 //

package/scripts/document/document-byte-budget.ts

@@ -1,32 +1,25 @@
 // The byte ceiling for every agent-read document NO entry reads — the fallback budget, a ratchet.
 //
-// **This is now the secondary budget** (joshuafolkken/kit#2257). The primary one is the entry total
-// (`entry-read-budget.ts`): a document a workflow entry reads is held by that entry's total and
-// carries no ceiling here, so neither budget holds it twice. What is left for this list is the
-// documents no entry reads — the reference documents a human browses, drawn by
-// `document-reachability.ts` from `read:set`'s output rather than by a hand-written table.
+// **This is the secondary budget.** The primary one is the entry total (`entry-read-budget.ts`): a
+// document a workflow entry reads is held by that entry's total and carries no ceiling here, so
+// neither budget holds it twice. What is left for this list is the documents no entry reads — the
+// reference documents a human browses, drawn by `document-reachability.ts` from `read:set`'s output
+// rather than by a hand-written table.
 //
-// Agent-read documents (`.claude/skills/**/*.md`, `prompts/**/*.md` and the two `docs/josh-commands*.md` references) have
-// been shrunk by reduction epics (joshuafolkken/kit#1929, joshuafolkken/kit#1924) only to swell
-// again, because nothing held the reduced size — a PR that adds a few lines at a time goes unseen
-// until the next reduction epic. This list is that hold for the unreached ones:
-// `document-byte-budget.test.ts` fails `pnpm josh gate` when such a document grows past its recorded
-// ceiling, when the list names a file that no longer exists, or when an unreached file has no entry
-// here.
+// Agent-read documents (`.claude/skills/**/*.md`, `prompts/**/*.md` and the `docs/josh-commands*.md`
+// references) swell when nothing holds their size — a PR that adds a few lines at a time goes unseen.
+// This list is that hold for the unreached ones: `document-byte-budget.test.ts` fails
+// `pnpm josh gate` when such a document grows past its recorded ceiling, when the list names a file
+// that no longer exists, or when an unreached file has no entry here.
 //
 // THE RECORDED CEILING IS BLOCK-QUANTIZED — this is what stops parallel command-adding lanes from
-// serializing on this file (joshuafolkken/kit#2231). Each entry's `bytes` is not the document's exact
-// size but the smallest multiple of `BLOCK_BYTES` at or above it, and that value IS the ceiling. A
-// document that grows within its current block needs no edit here, so most command-adding PRs leave
-// this file untouched rather than bumping a shared line; a document that crosses a block boundary
-// bumps to the next multiple — the same value from every lane, an identical change git auto-merges,
-// not a hand-picked slack unit two branches fight over. Growth is still bounded: the block is the
-// whole of a document's headroom, so it cannot swell without a visible, deterministic bump in the
-// diff. This replaced the earlier exact-size-plus-512-slack ratchet, whose tight slack forced
-// `docs/josh-commands.md` — pinned at its ceiling — to bump on every command addition, the
-// serialization point #2231 removed. It also retired the bespoke `JOSH_COMMANDS_CEILING_BYTES` hard
-// cap and its per-bump changelog comment: the uniform block ratchet now holds that document like any
-// other, so the second cap was a second line to bump for no added hold.
+// serializing on this file. Each entry's `bytes` is not the document's exact size but the smallest
+// multiple of `BLOCK_BYTES` at or above it, and that value IS the ceiling. A document that grows
+// within its current block needs no edit here, so most command-adding PRs leave this file untouched
+// rather than bumping a shared line; a document that crosses a block boundary bumps to the next
+// multiple — the same value from every lane, an identical change git auto-merges, not a hand-picked
+// slack unit two branches fight over. Growth is still bounded: the block is the whole of a document's
+// headroom, so it cannot swell without a visible, deterministic bump in the diff.
 //
 // HOW TO RAISE (or LOWER) A CEILING — this file is the only place, on purpose. When the gate reports a
 // document over its ceiling, copy the exact value the message names (the next block multiple) into
@@ -65,39 +58,25 @@ function block_ceiling(size: number): number {
 // unreached file, so the definition cannot rot as documents move on or off the execution path.
 const DOCUMENT_BYTE_BUDGET: ReadonlyArray<DocumentBudget> = [
 	{ path: '.claude/skills/dependency-update/SKILL.md', bytes: 8192 },
-	// joshuafolkken/kit#3173 split the waves and the `epic:bundle` detail into lazily read references.
-	{ path: '.claude/skills/epic-commands/SKILL.md', bytes: 20_480 },
-	{ path: '.claude/skills/epic-commands/epic-bundle.md', bytes: 12_288 },
-	{ path: '.claude/skills/epic-commands/execution-waves.md', bytes: 12_288 },
+	{ path: '.claude/skills/epic-commands/SKILL.md', bytes: 16_384 },
+	{ path: '.claude/skills/epic-commands/epic-bundle.md', bytes: 8192 },
+	{ path: '.claude/skills/epic-commands/execution-waves.md', bytes: 8192 },
 	{ path: '.claude/skills/verify-ui/SKILL.md', bytes: 8192 },
+	{ path: '.claude/skills/workflow-commands/backlogrun-handoff-report.md', bytes: 4096 },
 	{ path: '.claude/skills/workflow-commands/fullrun-steps.md', bytes: 8192 },
 	{ path: '.claude/skills/workflow-commands/into-target.md', bytes: 4096 },
 	{ path: '.claude/skills/workflow-commands/issue-comments.md', bytes: 8192 },
 	{ path: '.claude/skills/workflow-commands/issue-fold-existing.md', bytes: 4096 },
-	{ path: '.claude/skills/workflow-commands/needs-human-review.md', bytes: 8192 },
+	{ path: '.claude/skills/workflow-commands/needs-human-review.md', bytes: 4096 },
 	{ path: '.claude/skills/workflow-commands/observation-filing.md', bytes: 12_288 },
-	// joshuafolkken/kit#3176 moved the ledger out of `observation-filing.md`, read only when it appends.
 	{ path: '.claude/skills/workflow-commands/observation-ledger.md', bytes: 12_288 },
-	// `pre-gate-cut.md` left this per-document budget in joshuafolkken/kit#2289: it became a point-of-use
-	// document, so its bytes are now held by every entry's total read (`entry-read-budget.ts`) and the
-	// two budgets must not hold it twice — the reachability line moved it from `unreached` to
-	// `point-of-use`.
 	{ path: '.claude/skills/workflow-commands/prerequisite.md', bytes: 8192 },
-	{ path: '.claude/skills/workflow-commands/target-repository.md', bytes: 8192 },
+	{ path: '.claude/skills/workflow-commands/target-repository.md', bytes: 4096 },
 	{ path: '.claude/skills/workflow-commands/working-tree-hold.md', bytes: 8192 },
-	// joshuafolkken/kit#2998 split the reference: the developer commands stay, the rest moved out.
-	// joshuafolkken/kit#3175 raised it: the supervisor, provider-table and answer-to-budget prose moved
-	// here out of `backlogrun-steps.md`, so a run reads it only when it asks about those commands.
-	// joshuafolkken/kit#3277 moved the run, lane and session commands to `docs/josh-commands-run.md`.
-	// joshuafolkken/kit#3280 moved the issue, epic, backlog and review commands to
-	// `docs/josh-commands-backlog.md`.
-	// joshuafolkken/kit#3278 moved `josh latest` and `josh overrides` — commands a person types — from
-	// the automation page to `docs/josh-commands.md`, which grew one block and the automation page shrank one.
-	{ path: 'docs/josh-commands-automation.md', bytes: 49_152 },
-	{ path: 'docs/josh-commands-run.md', bytes: 57_344 },
+	{ path: 'docs/josh-commands-automation.md', bytes: 53_248 },
+	{ path: 'docs/josh-commands-run.md', bytes: 65_536 },
 	{ path: 'docs/josh-commands-backlog.md', bytes: 57_344 },
-	{ path: 'docs/josh-commands.md', bytes: 40_960 },
-	// joshuafolkken/kit#3279 moved the label sections here out of `docs/josh-commands-backlog.md`.
+	{ path: 'docs/josh-commands.md', bytes: 45_056 },
 	{ path: 'docs/labels-and-run-states.md', bytes: 8192 },
 	{ path: 'prompts/coding-standards.md', bytes: 8192 },
 	{ path: 'prompts/collaboration-workflow.md', bytes: 8192 },
@@ -105,34 +84,25 @@ const DOCUMENT_BYTE_BUDGET: ReadonlyArray<DocumentBudget> = [
 	{ path: 'prompts/collaboration-workflow/gh-rest.md', bytes: 8192 },
 	{ path: 'prompts/collaboration-workflow/glossary.md', bytes: 4096 },
 	{ path: 'prompts/collaboration-workflow/issue-citation.md', bytes: 4096 },
-	// #3178 left the template and the judgement tables; the epic commands moved to `epic-commands`, the by-hand fallback stayed.
-	{ path: 'prompts/collaboration-workflow/issue-template.md', bytes: 8192 },
+	{ path: 'prompts/collaboration-workflow/issue-template.md', bytes: 12_288 },
 	{ path: 'prompts/collaboration-workflow/operating-rules.md', bytes: 12_288 },
-	// #3177 moved the rationale to `docs/maintainers/output-bounds-rationale.md`.
 	{ path: 'prompts/collaboration-workflow/output-bounds.md', bytes: 4096 },
 	{ path: 'prompts/collaboration-workflow/overview.md', bytes: 4096 },
-	// #3178 replaced the review-chain restatement with a pointer to `chain-rule.md`.
 	{ path: 'prompts/collaboration-workflow/plan-comment.md', bytes: 8192 },
-	{ path: 'prompts/collaboration-workflow/principles.md', bytes: 12_288 },
+	{ path: 'prompts/collaboration-workflow/principles.md', bytes: 16_384 },
 	{ path: 'prompts/collaboration-workflow/proposal-request.md', bytes: 4096 },
-	// #3178 dropped the restatements `report:lint` and `chain-rule.md` already carry.
 	{ path: 'prompts/collaboration-workflow/report-format.md', bytes: 16_384 },
-	// #3177 cut it to the four questions; the history and lists moved to `docs/maintainers/residency-rationale.md`.
 	{ path: 'prompts/collaboration-workflow/residency.md', bytes: 8192 },
-	// #3186 moved the hook wiring and history to `docs/maintainers/rule-delivery-rationale.md`;
-	// #3179 adds the `index-mutation` / `destructive-command` / `protected-file` entries.
-	{ path: 'prompts/collaboration-workflow/rule-delivery.md', bytes: 20_480 },
+	{ path: 'prompts/collaboration-workflow/rule-delivery.md', bytes: 4096 },
 	{ path: 'prompts/collaboration-workflow/shell-body.md', bytes: 8192 },
-	// #3177 moved the measurements and rejected mechanisms to `docs/maintainers/turn-batching-rationale.md`.
 	{ path: 'prompts/collaboration-workflow/turn-batching.md', bytes: 8192 },
 	{ path: 'prompts/collaboration-workflow/upstream-interrupt.md', bytes: 12_288 },
 	{ path: 'prompts/collaboration-workflow/wip-cap.md', bytes: 12_288 },
 	{ path: 'prompts/refactoring.md', bytes: 8192 },
-	// #3180 moved the history and the lint-settled proofs to `docs/maintainers/`.
 	{ path: 'prompts/review-rubric.md', bytes: 16_384 },
 	{ path: 'prompts/review.md', bytes: 16_384 },
 	{ path: 'prompts/sonar-hotspot-handling.md', bytes: 8192 },
-	{ path: 'prompts/testing-guide.md', bytes: 20_480 },
+	{ path: 'prompts/testing-guide.md', bytes: 16_384 },
 ]
 
 // The recorded ceiling for one path, or undefined when it carries no budget entry.
@@ -142,7 +112,7 @@ function recorded_bytes_for(relative_path: string): number | undefined {
 
 // The bytes an entry has left before its ceiling — the recorded ceiling minus the document's current
 // size. Negative when the document is already over. `josh bytes` prints it as the headroom before an
-// edit, the same number `josh lines` prints for code lines (joshuafolkken/kit#2176).
+// edit, the same number `josh lines` prints for code lines.
 function remaining_bytes(recorded_bytes: number, current_bytes: number): number {
 	return recorded_bytes - current_bytes
 }
@@ -169,9 +139,8 @@ function over_budget_message(
 
 // The failure message the staleness test raises. A recorded ceiling more than a block above the
 // document's actual size is a stale-loose ratchet: the document shrank across a block boundary and
-// its record was never lowered, so the ceiling no longer holds the reduction (the drift
-// joshuafolkken/kit#2125 swept). It names the file, its recorded ceiling, its actual size, and the
-// block multiple to lower the record to.
+// its record was never lowered, so the ceiling no longer holds the reduction. It names the file,
+// its recorded ceiling, its actual size, and the block multiple to lower the record to.
 function stale_budget_message(
 	relative_path: string,
 	recorded_bytes: number,

package/scripts/document/document-byte-check.ts

@@ -7,7 +7,7 @@ import { entry_read_budget } from './entry-read-budget'
 // The byte-ceiling check the gate's `document-byte-budget.test.ts` runs, made reachable on the fast
 // between-edits path — `josh lint:related` calls it over the files it already resolved so a mandated
 // documentation update that grows a document past its ceiling is caught in seconds rather than after
-// the 80–90-second gate (joshuafolkken/kit#2176). The ceiling and its message are
+// the 80–90-second gate. The ceiling and its message are
 // `document-byte-budget.ts`'s alone: this adds no budget of its own, so the fast path can never hold
 // a different line from the gate, and widening one can never loosen the other.
 //
@@ -53,8 +53,8 @@ function over_budget_messages(
 		.filter((message): message is string => message !== undefined)
 }
 
-// The entry-total counterpart: an entry over its recorded ceiling. This is the primary budget
-// (joshuafolkken/kit#2257), so an edit to a covered document — which grows an entry's total, not a
+// The entry-total counterpart: an entry over its recorded ceiling. This is the primary budget,
+// so an edit to a covered document — which grows an entry's total, not a
 // per-document ceiling — is caught here on the same fast path. Stale ceilings are left to the gate's
 // `entry-read-budget.test.ts`, exactly as the per-document staleness is: this path blocks growth.
 function entry_over_budget_message(root: string, entry: string): string | undefined {
@@ -107,7 +107,7 @@ function check_files(root: string, absolute_files: ReadonlyArray<string>): numbe
 // resolved change. `lint:related`'s own fallback lints a superset of the change, so the byte check
 // widens to the whole budget rather than an empty file list — otherwise the fallback would report
 // success on a tree it never read for bytes, and the green record the caller then writes would vouch
-// for a byte dimension it never checked (joshuafolkken/kit#2176).
+// for a byte dimension it never checked.
 function check_all(root: string): number {
 	const absolute_files = document_byte_budget.DOCUMENT_BYTE_BUDGET.map((entry) =>
 		path.join(root, entry.path),

package/scripts/document/document-reachability.ts

@@ -1,10 +1,9 @@
 // Where each agent-read document sits on the execution path, derived from `read:set` — never
-// hand-listed (joshuafolkken/kit#2257).
+// hand-listed.
 //
-// **The per-document byte ceiling could not tell an entry read from a reference document.** A
+// **The per-document byte ceiling cannot tell an entry read from a reference document.** A
 // document a run reads on every entry costs it every session; one nothing routes to costs it nothing.
-// The per-document ceiling held both to the same rule, so a reference document a human browses was
-// budgeted as tightly as the workflow text a run actually reads. This splits the corpus so the
+// This splits the corpus so the
 // primary budget (`entry-read-budget.ts`) can be the total each entry reads, and the per-document
 // ceiling falls back to the documents no entry reaches.
 //
@@ -13,8 +12,8 @@
 // `CLAUDE.md` every entry loads. A document `read:set` never enumerates is `unreached`, and a
 // hand-written table of which is which would be the clone `CLAUDE.md` prohibits, drifting the first
 // time a trigger table row moved. `CLAUDE.md` is resident by construction rather than by the graph,
-// because it is loaded on every request whatever the entry — the misclassification joshuafolkken/kit#2257
-// singled out (a bare reachability walk drops it to "off-path", which is wrong).
+// because it is loaded on every request whatever the entry (a bare reachability walk would drop it to
+// "off-path", which is wrong).
 //
 // **The corpus is passed in, never imported here.** This module sits on the runtime path
 // (`lint-related` → `document-byte-check` → here), so it may not import `ai-document-fixture` — a test
@@ -26,7 +25,7 @@ import { entry_read_set } from './entry-read-set'
 
 // The always-resident rule document. It is not an entry read — every request carries it — so it is
 // named here rather than derived from a trigger table, and the entry-total budget adds it to every
-// entry's total so its growth is held (joshuafolkken/kit#2257).
+// entry's total so its growth is held.
 const RESIDENT_BASE: ReadonlyArray<string> = ['CLAUDE.md']
 const WORKFLOW_DIRECTORY = '.claude/skills/workflow-commands'
 
@@ -104,7 +103,7 @@ function documents_labelled(
 
 // The documents an entry reads — resident plus point-of-use. The entry-total budget governs these;
 // the per-document ceiling falls back to the unreached rest, so neither holds a document the other
-// does (joshuafolkken/kit#2257). Both sides come from `read:set`, so no corpus is needed — which is
+// does. Both sides come from `read:set`, so no corpus is needed — which is
 // what keeps the runtime caller (`document-byte-check`) free of the fixture the corpus lives in.
 function covered_documents(root: string = process.cwd()): Array<string> {
 	return [...new Set([...resident_documents(root), ...point_of_use_documents()])].toSorted(

package/scripts/document/document-read-cli.ts

@@ -4,10 +4,10 @@ import { bash_output_cap_reader } from './bash-output-cap'
 import { document_section } from './document-section'
 import { document_section_cli } from './document-section-cli'
 
-// `josh doc:read <file>` — a Bash-cap-safe read path for a whole document (joshuafolkken/kit#2188).
+// `josh doc:read <file>` — a Bash-cap-safe read path for a whole document.
 //
 // **A `cat` of a document larger than the Bash output cap is a truncated preview, then a second read.**
-// `read:set` measured one entry paying for the same five files twice this way (joshuafolkken/kit#1797):
+// `read:set` measured one entry paying for the same five files twice this way:
 // the shell hands back a middle-truncated preview, so the file is read again with the `Read` tool. This
 // command is the path that avoids it — it never emits an over-cap document through the shell at all.
 //

package/scripts/document/document-scan.ts

@@ -1,5 +1,5 @@
 // Pulling machine-checkable references out of the distributed documents, so a few structural scans
-// can replace the ~140 per-phrase marker suites the documents used to carry (joshuafolkken/kit#1923).
+// can replace the ~140 per-phrase marker suites the documents used to carry.
 // Every function here is a pure string extractor: it takes document text and returns the references
 // it names, which is what lets the scans that call it be checked on a synthetic string with a
 // deliberately broken reference in it.
@@ -18,12 +18,20 @@ const LABEL_PATTERN = /(?:labels\[\]=|\/labels\/|labels -f name=)([a-z][a-z0-9:_
 // quotes — `` `backlogrun-progress.md` → "The hand-off" ``. The code span is optional and a section
 // number may sit between the arrow and the heading (`` `SKILL.md` → §1, "…" ``): both forms are in
 // the documents, as is a name linked to its file (`` [`residency.md`](./residency.md) →「…」 ``), and a
-// pattern that skipped them let a broken reference of each form through (joshuafolkken/kit#3076).
+// pattern that skipped them would let a broken reference of each form through.
 // The backreference pairs the code span's backticks, and the lookbehind keeps a bare name from
 // starting mid-path — inside a URL or after an unpaired backtick.
 const SECTION_PATTERN =
 	/(?<![\w./:`-])(?<tick>`?)(?<file>[\w./-]+\.md)\k<tick>\s*→\s*(?:§\w+,\s*)?["「](?<heading>[^"」]+)["」]/gu
 
+// A reference to a heading of the same document, which names no file: a quoted heading followed by
+// `above` or `below`, or an arrow with no file name before it — `→ "The hand-off"`. A broken one
+// sends the reader after a section that is not there as surely as a cross-document one does.
+// A bare arrow is read only once every `file.md →` form is dropped, so a
+// cross-document reference is never re-read as a reference to the document it sits in.
+const ADJACENT_PATTERN = /["「](?<heading>[^"「」]+)["」]\s+(?:above|below)\b/gu
+const BARE_ARROW_PATTERN = /→\s*(?:§\w+,\s*)?["「](?<heading>[^"「」]+)["」]/gu
+
 // A markdown link's `(target)`, dropped before the section scan so a linked name sits right before its
 // arrow — the link text already carries the file the reference names.
 const LINK_TARGET_PATTERN = /\]\([^)\s]*\)/gu
@@ -79,6 +87,20 @@ function section_references(text: string): Array<SectionReference> {
 		.filter((reference) => !is_placeholder_file(reference.file))
 }
 
+function headings_matching(text: string, pattern: RegExp): Array<string> {
+	return matches(text, pattern).map(({ groups }) => groups?.['heading'] ?? '')
+}
+
+function adjacent_references(text: string): Array<string> {
+	return headings_matching(text, ADJACENT_PATTERN)
+}
+
+function bare_arrow_references(text: string): Array<string> {
+	const unfiled = text.replaceAll(LINK_TARGET_PATTERN, '').replaceAll(SECTION_PATTERN, '')
+
+	return headings_matching(unfiled, BARE_ARROW_PATTERN)
+}
+
 function link_targets(text: string): Array<string> {
 	return matches(text, LINK_PATTERN)
 		.map((match) => match[1] ?? '')
@@ -105,6 +127,8 @@ function reference_forms(title: string): Array<string> {
 }
 
 const document_scan = {
+	adjacent_references,
+	bare_arrow_references,
 	command_references,
 	label_references,
 	link_targets,