@joshuafolkken/kit 1.1136.0 → 1.1178.0

package/prompts/review.md

@@ -15,17 +15,10 @@ points to them rather than restating them:
 
 ## When to run
 
-- **Pre-commit self-review** (implementing session, inline): before every `git commit` on a feature
-  branch — scope: the staged diff (`git diff --staged`), level from
-  `pnpm josh review:brief --level-only`.
-- **Workflow review step** (same session, inline): the last stage of the verification gate in `fullrun`
-  / `halfrun` / `backlogrun`, driven by the brief `pnpm josh review:brief` prints. Round 1 runs before the
-  commit — scope: `git diff main`. Round 2 runs after it, beside the CI the commit started
-  (`.claude/skills/workflow-commands/chain-rule.md` → "The pull request opens between the rounds, so CI
-  runs beside round 2").
-
-The workflow review uses the `reviewer` role profile printed by `pnpm josh review:brief`. Pass its
-model and effort explicitly to the review subagent; do not substitute the review level for effort.
+When a review runs is `CLAUDE.md` → "Pre-commit Self-Review"; inside a workflow, round 1 runs before
+the commit and round 2 beside CI (`.claude/skills/workflow-commands/chain-rule.md`). Pass the
+`reviewer` profile's model and effort that `pnpm josh review:brief` prints to the review subagent;
+do not substitute the review level for effort.
 
 Re-run after applying fixes until **no high or medium findings remain — or until the round cap below is
 reached, the first review included — whichever comes first.** The cap below is not optional. The second round
@@ -46,10 +39,8 @@ pnpm josh review:brief --level-only            # the branch diff
 pnpm josh review:brief --level-only --staged   # the staged diff
 ```
 
-**The level is decided from the changed paths and nothing else.** "This one is small" is a judgement
-made under cost pressure, and cost pressure resolves it toward "small" exactly when a defect is most
-likely to be shipped. A rule an agent applies from memory is a rule an agent can talk itself out of;
-one it has to run answers the same way every time.
+**The level is decided from the changed paths and nothing else** — never "this one is small"
+(`docs/maintainers/review-history.md`).
 
 | Every changed path is…                                                                   | Level    | Rounds                  |
 | ---------------------------------------------------------------------------------------- | -------- | ----------------------- |
@@ -64,13 +55,8 @@ would hand a reduced level to a caller that failed to read the diff.
 in `package.json`'s `files` and are written into every consumer project by `josh init` / `josh sync`,
 so a defect in one reaches a consumer and is reviewed at `medium` like any other shipped file.
 
-**Documentation is not inert either, and that is deliberate.** `CLAUDE.md`, `prompts/**`, `.claude/**`
-and `docs/**` are all reviewed at `medium`. The "Non-runtime updates" exception in `CLAUDE.md` exempts
-them from _testing_ — which asks whether an automated test could have caught the defect — while this
-asks whether a human reading the diff is the only thing that can. Measured on joshuafolkken/kit#963 and
-#965, both documentation-only by that classification: a `medium` review found ten real defects in each
-— pointers into sections that had been removed, and citations naming the wrong file, in artifacts
-distributed to every consumer — that nothing else would have caught.
+**Documentation is not inert either.** `CLAUDE.md`, `prompts/**`, `.claude/**` and `docs/**` are all
+reviewed at `medium`, though exempt from _testing_: a reader is the only detector a prose defect has.
 
 **A confirmed High blocks regardless of round count**, and the round cap below does not change that.
 
@@ -78,26 +64,19 @@ distributed to every consumer — that nothing else would have caught.
 
 ## Review round cap (2 rounds)
 
-The severity rule in the rubric is not a stopping condition on its own. Every fix creates new surface,
-and a review whose scope is the whole change finds something in it — so the loop is bounded by how much
-new code the fixes produce, which is unbounded.
+The severity rule in the rubric is not a stopping condition on its own: every fix creates new surface a
+further round would find something in.
 
 **Two rounds is the ceiling, not the schedule.** Whether the second one is due at all is
 `pnpm josh review:round2`'s answer — "When round 2 is skipped entirely, and when it is not" below is
-the single source of that condition (joshuafolkken/kit#1433).
-
-This is measured, not theorized. On joshuafolkken/kit#854 four rounds produced 18 findings; on #855
-two rounds produced 19. Almost none of them was a repeat: each round found new things, and many of
-those were about code the **previous round's fix** had just written. Two rounds of that is diligence; a
-third is the review chasing its own tail.
+the single source of that condition.
 
 ### A merge-conflict resolution review is not one of the two
 
 **When `pnpm josh followup` reports `PR checks failed (merge conflict)`, the child resolves the conflict
-in its own lane and reviews the resolution — and that round does not count against the cap**
-(joshuafolkken/kit#1623). The cap bounds re-reading _the change under review_; a resolution review reads
+in its own lane and reviews the resolution — and that round does not count against the cap**. The cap bounds re-reading _the change under review_; a resolution review reads
 a different subject — not the change, but what merging a moved `main` into it did.
-`.claude/skills/workflow-commands/backlogrun-lanes.md` → "Conflicts are not predicted" is the single source of
+`.claude/skills/workflow-commands/backlogrun-recovery.md` → "Conflicts are not predicted" is the single source of
 the procedure and of the four conditions under which the run steps back instead of resolving.
 `pnpm josh review:attest --check` must answer `ok` before the merge is re-issued, and a confirmed High
 parks the child rather than buying it a further round.
@@ -105,7 +84,7 @@ parks the child rather than buying it a further round.
 ### When round 2 is skipped entirely, and when it is not
 
 **Two rounds is the ceiling; whether the second round runs at all is a command's answer, not a reading
-of a list** (joshuafolkken/kit#1433):
+of a list**:
 
 ```bash
 pnpm josh review:round2 --round-1-closed   # → required | skip ; the reason on stderr
@@ -116,8 +95,7 @@ round-1 High/Medium finding actually closed — by a fix in this working tree, o
 positive — and none was filed or deferred. **Without the flag the answer is `required`**, which is also
 what the command answers to every uncertainty it meets, a missing round-1 snapshot included.
 
-**`skip` has exactly two arms, and both are states in which round 1's fix code needs no review**
-(joshuafolkken/kit#1222 — the round exists because round 1's fix code is otherwise unreviewed):
+**`skip` has exactly two arms, and both are states in which round 1's fix code needs no review**:
 
 | Arm                    | What it is                                                                                                                   |
 | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
@@ -126,9 +104,7 @@ what the command answers to every uncertainty it meets, a missing round-1 snapsh
 
 **Neither arm weakens the standard.** A round-1 High/Medium that did not close is not a closed finding,
 so the flag is not passable; the cap is still two rounds; and a confirmed High still blocks the merge.
-**The wider line joshuafolkken/kit#1433 proposed — exempting anything that is not a runtime code path —
-is not adopted**: a documentation-only diff is exactly where the review is the only detector (the #963 /
-#965 measurement above), so a prompt fix answers `required`.
+A documentation-only fix delta is not inert, so a prompt fix answers `required`.
 
 **A skipped round is recorded on the Issue**, so the condition stays auditable and can be withdrawn if
 a defect is later traced to a skipped delta:
@@ -142,7 +118,7 @@ a defect is later traced to a skipped delta:
 ### Three-way disposition after the cap
 
 **After the second round, place every remaining non-High finding in exactly one of three exits, decided
-from what the finding is rather than from the filer's discretion** (joshuafolkken/kit#1469). **The
+from what the finding is rather than from the filer's discretion**. **The
 default exit is branch 3, and branch 2 has to be earned**. Read them in order — branch 1 where the fix is
 trivial and local, branch 2 only where the finding clears the bar it names, branch 3 for everything
 left, which is most of them. "It might matter later" is branch 3.
@@ -167,12 +143,6 @@ left, which is most of them. "It might matter later" is branch 3.
    suspicion included. **The note is not optional**: one line naming the finding and why it was dropped
    is what keeps a dropped finding auditable rather than invisible.
 
-**What it costs, and why that is the right trade.** A dropped finding that later turns out to matter is
-re-found by the next review of that code, at the price of one round it would have paid anyway. A filed
-finding that never mattered is carried forever — placed in an epic, offered by `epic:next`, read by
-everyone who scans the backlog. The two errors are not symmetric, and the old default was on the
-expensive side of them.
-
 **Findings that reduce to one root judgement are filed as one Issue, not several** — a single follow-up
 Issue with a section per symptom (`## 現象 1` / `## 現象 2`).
 
@@ -187,7 +157,7 @@ Only branch 2 files an Issue. What follows applies to that branch.
   the commit.** Where the run opens a pull request — `fullrun`, `backlogrun` — they go after
   `pnpm josh git -y` and before `pnpm josh followup`; where it does not — `halfrun`, or a standalone
   pre-commit self-review — they run as soon as the disposition is decided. **The chain may run in a
-  delegated unit** — `pnpm josh delegate followup-filing` (joshuafolkken/kit#1892).
+  delegated unit** — `pnpm josh delegate followup-filing`.
 - **When the round files a second follow-up, run `pnpm josh issue:fold` first.** Several findings from
   one review fold into one Issue by default — the filing-time counterpart to the split assessment,
   reading the same two questions (`.claude/skills/workflow-commands/split-assessment.md` → "The same
@@ -204,13 +174,13 @@ Only branch 2 files an Issue. What follows applies to that branch.
      write command yourself — never a hand edit of the epic body, which leaves the task list and the
      `blocked-by` relations disagreeing and `epic:next` returning `error`.
 
-  | Answer                                                                                            | Do                                                                                                                                                                                                                                                                                                                                | Tier                    |
-  | ------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |
-  | `add_to_epic`                                                                                     | `pnpm josh epic --add <E> <new>` — add `--before <M>` / `--after <M>` when the relation carries an order                                                                                                                                                                                                                          | **A — no confirmation** |
-  | `create_epic`                                                                                     | `pnpm josh epic "<title>" <new> <other> [--ordered]`                                                                                                                                                                                                                                                                              | **A — no confirmation** |
-  | `ask` — candidates spread across two or more epics                                                | **Choose the epic you recommend, run its write command, and record the decision** — what was taken, what was rejected, why — on both the new Issue and that epic's `## Decisions`. This does not stop a run and does not park a child (joshuafolkken/kit#1339); stop only where the two epics are genuinely too close to separate | **A — no confirmation** |
-  | `none`                                                                                            | Nothing                                                                                                                                                                                                                                                                                                                           | —                       |
-  | **The command could not answer** — non-zero exit, or **any** ⚠ warning above `Nothing to bundle.` | Stop and report, naming what it said. **A `none` printed after such a warning is not "nothing to bundle"** — the search was incomplete                                                                                                                                                                                            | —                       |
+  | Answer                                                                                            | Do                                                                                                                                                                                                                                                                                                       | Tier                    |
+  | ------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |
+  | `add_to_epic`                                                                                     | `pnpm josh epic --add <E> <new>` — add `--before <M>` / `--after <M>` when the relation carries an order                                                                                                                                                                                                 | **A — no confirmation** |
+  | `create_epic`                                                                                     | `pnpm josh epic "<title>" <new> <other> [--ordered]`                                                                                                                                                                                                                                                     | **A — no confirmation** |
+  | `ask` — candidates spread across two or more epics                                                | **Choose the epic you recommend, run its write command, and record the decision** — what was taken, what was rejected, why — on both the new Issue and that epic's `## Decisions`. This does not stop a run and does not park a child; stop only where the two epics are genuinely too close to separate | **A — no confirmation** |
+  | `none`                                                                                            | Nothing                                                                                                                                                                                                                                                                                                  | —                       |
+  | **The command could not answer** — non-zero exit, or **any** ⚠ warning above `Nothing to bundle.` | Stop and report, naming what it said. **A `none` printed after such a warning is not "nothing to bundle"** — the search was incomplete                                                                                                                                                                   | —                       |
 
 - **A confirmed High is never deferred.** A real defect does not ship because a round counter ran out,
   so a standing High blocks the merge — never fixed-in-place, filed, or dropped as one of the three

package/prompts/testing-guide.md

@@ -22,7 +22,8 @@ Req N: ...
 ### Rules
 
 - **Every user-facing behavior change** (UI interaction, keyboard shortcut, visible state change) must have a corresponding E2E test.
-- **Every logic/utility change** (pure functions, filters, transforms) must have a unit test.
+- **Every logic/utility change** (pure functions, filters, transforms) must have a unit test. A bug fix takes a regression test; a refactor takes tests pinning the existing behavior BEFORE the change (`prompts/refactoring.md`).
+- **Non-runtime updates (pre-approved manual-only exception):** a change touching no executable runtime code path — docs, non-executable config, editor/IDE files, cosmetic asset swaps with no selector/path change — may be verified by hand; declare it in Step 0 with the reason. The mechanically exempt (`*.md`, `.editorconfig`, `.idea/**`, `.vscode/**`, `prompts/**`) need no declaration. A runtime change whose test is infeasible needs the reason and user approval.
 - **basic で kit がテストできない言語だけの変更:** `package.json` に `josh.profile: basic`（改名前の `static` も同じ）が記録され、変更が HTML/CSS や Lua などのソースだけなら自動テストは不要。HTML/CSS はブラウザーで対象ページを開き、想定する画面幅でレイアウト・リンク・HTML 内の操作を確認する。そのほかのソースは変更した処理を実際に動かす。どちらも結果を記録する。同じ変更に JavaScript または TypeScript のファイルが含まれれば自動テストを行う。
 - If a test is genuinely infeasible (e.g., native OS date-picker popup cannot be driven by Playwright), write a comment in the test file explaining why and test the closest observable behavior instead (e.g., that the editor remains open after the `change` event fires).
 - Do **not** report a requirement as done if its test is missing.
@@ -59,7 +60,7 @@ There is exactly **one** convention for every test file — never choose between
 - **The `.svelte.` infix is required for component/browser tests and must be preserved.** `*.svelte.test.ts` routes the file to the **browser/component** vitest project (`include: src/**/*.svelte.{test,spec}.{js,ts}`); plain `*.test.ts` routes to the **node/unit** project (`include: src/**/*.{test,spec}.{js,ts}`). Renaming `Foo.svelte.test.ts` → `Foo.test.ts` silently moves it to the wrong project — do not drop the `.svelte.` infix.
 - **Colocate every test next to the code it exercises.** A top-level `tests/` directory is **not used** — place `foo.test.ts` beside `foo.ts`, and E2E specs under the relevant `src/routes/**` path. The top-level `tests/` ban is **lint-enforced** by the same rule (`eslint/rules/test-filename.js`). Note: `playwright.config.ts` discovers E2E via `testMatch: '**/*.e2e.{ts,js}'`, so an `*.e2e.ts` placed outside `src/routes/**` would still run — that specific `src/routes/**` placement is enforced by **convention/review, not config**, and must be upheld manually.
 
-> **Enforcement:** the `*.spec.ts` ban and the top-level `tests/` ban are enforced by the test-filename rule (`eslint/rules/test-filename.js`), wired into the shared `eslint/base.js`, so they fail loudly in `josh lint` for kit itself, for every consumer of that base config, and for every AI tool. Left as an export a consumer had to remember to wire in, the ban reached only the projects that did — and never the repository distributing it (joshuafolkken/kit#1233). This was chosen over tightening the vitest `{test,spec}` matchers to `{test}` only, because matcher-tightening causes **silent non-execution** of stray `*.spec.ts` files whereas a lint rule fails loudly. (Doc-only guidance had already failed to prevent this drift twice.)
+> **Enforcement:** the `*.spec.ts` ban and the top-level `tests/` ban are enforced by the test-filename rule (`eslint/rules/test-filename.js`), wired into the shared `eslint/base.js`, so they fail loudly in `josh lint` for kit itself, for every consumer of that base config, and for every AI tool (`docs/maintainers/testing-guide-history.md`).
 
 ---
 
@@ -177,19 +178,8 @@ test('returns expected values in sequence', () => {
 
 ## 6. Closing the E2E gate without a human run
 
-The completion gate used to end by asking the user to run `pnpm josh test` and paste the output.
-That step is gone (joshuafolkken/kit#902). It is the rule below that replaces it, and the
-replacement is **not** a relaxation — nothing that a red local run stopped is allowed through.
-
-### Why it existed, and why it no longer does
-
-The reason was never that a human reads E2E output better. It was that `followup` waited 180
-seconds for CI, which no suite containing E2E can finish in — so the command exited red beside a CI
-that was still running, and the only reliable E2E signal left was a person's terminal. That budget
-is now derived from the distributed `templates/workflows/ci.yml` rather than picked as a round
-number: 1920 seconds, the longest run its `needs` graph permits plus runner-queue headroom, with a
-unit test that fails if a declared job budget outgrows it (joshuafolkken/kit#851). CI can now be
-waited on, so it can be relied on.
+No human E2E run closes the gate, and nothing a red local run stopped is let through
+(`docs/maintainers/testing-guide-history.md`).
 
 ### Which result closes the gate
 
@@ -219,60 +209,21 @@ a **defined** outcome, not an accident: a project with no E2E suite has nothing
 read, and the run says so out loud. **A skip you did not see printed is not one** — it is an unread
 result, and it falls under the previous paragraph.
 
-**CI decides the same question, and now by the same rule.** The `e2e-detect` job in
+**CI decides the same question by the same rule.** The `e2e-detect` job in
 `templates/workflows/ci.yml` enables the `e2e` job when any `*.e2e.{ts,js}` exists outside
-`node_modules` — the guard's own glob, dot-directories left out the way the guard's default leaves
-them out — and it does not look at the config's filename at all (joshuafolkken/kit#991). Before
-that it required a file named exactly `playwright.config.ts` **and** an `*.e2e.{ts,js}` under `tests` or
-`src/routes`, so a suite kept anywhere else, or a config named `playwright.config.js`, read as
-"no E2E" in CI while `josh test:e2e` ran it locally: the job's `if:` went false, GitHub recorded it
-as `skipped`, the rollup parser counted the skip as passing exactly as it does for every other
-conditional job, and the first row of the table above closed the gate on a suite nobody ran.
-**Where the specs live was a precondition on the CI signal; it is now a property of the workflow.**
-The agreement is executed rather than described — `scripts/ci/ci-yml-e2e-detect.test.ts` runs the
-workflow's own script against each layout and compares its verdict to the guard's, and asserts over
-the whole matrix that no layout containing specs can yield `enabled=false`. § 1's placement
-convention still stands on its own merits (`eslint/rules/test-filename.js` bans a top-level
-`tests/` directory outright), but the CI signal no longer depends on following it.
-
-**One difference from the guard remains, and it is deliberate and one-sided.** The guard also skips
-when `@playwright/test` is not installed, which is what keeps that optional peer optional for the
-pre-push hook; CI enables the job on the spec alone, so a spec that cannot run ends red rather than
-silently green. Enabling more than the guard costs a failed job, enabling less costs a merge — so
-the difference may widen in that direction and never narrow.
+`node_modules` — the guard's own glob — whatever the config's filename;
+`scripts/ci/ci-yml-e2e-detect.test.ts` pins the agreement. CI enables the job on the spec alone, even
+where the guard skips for a missing `@playwright/test`, so a spec that cannot run ends red rather than
+silently green.
 
 ### The gate is not weakened
 
-Two properties carry the verification the human step used to carry, and both are asserted by tests
-rather than left to prose:
-
 - **A non-passing check keeps the merge closed.** `evaluate_pr_state` returns `success` only when
-  GitHub reports the pull request `CLEAN` **and** every required check passes. A failing E2E job
-  makes GitHub report `UNSTABLE`, and the one opening in that wall — `is_unstable_only_from_coderabbit`,
-  the temporary kit#753 policy — applies only when _every_ non-passing check is CodeRabbit's. So a
-  red E2E can never reach `success`, and `followup` exits non-zero instead of merging.
-- **Weakening the gate is a workaround, and the workaround rules apply to it.** Filtering,
-  narrowing or reinterpreting E2E output to get past it is the violation `CLAUDE.md` names under
-  "Cross-package problems"; reporting the filtered result honestly does not make it compliant.
-
-**`E2E` stays off the required-check list, and that is a decision rather than an oversight**
-(joshuafolkken/kit#991). A required check is satisfied by a _skipped_ job — the rollup parser maps
-`SKIPPED` to `pass` — so requiring `E2E` would have passed on exactly the skipped job described
-above, which is the failure it looks like it would have caught. It adds nothing to the failure path
-either: a red E2E already ends the wait on the poll that sees it. What it would add is a cost —
-a repository whose CI reports no `E2E` context at all resolves the required entry to `missing`,
-which is never `pass`, so the evaluation stays `pending` until the 32-minute wait times out with
-nothing actually wrong. What guarantees the job runs is the detection rule above, not the required
-list. A project that wants it required opts in through `JOSH_REQUIRED_CHECKS`, which
-`scripts/gh/git-pr-checks-eval.test.ts` covers; the decision itself — `E2E` off the default list,
-and a repository reporting no `E2E` check still mergeable — is pinned in
-`scripts/gh/git-pr-checks-e2e-gate.test.ts`.
-
-**A red E2E is reported as soon as it goes red, and by name.** `E2E` is not on the required list, so
-until joshuafolkken/kit#990 nothing ended the wait when it failed: the rollup read as pending,
-`followup` ran out its 32-minute budget, and the run ended in `Timed out while waiting for PR checks
-to complete.` — a message naming neither the job nor the cause. Any failing check now ends the wait
-on the poll that sees it, and the error names it (`PR checks failed (failed checks: E2E).`).
-The poll loop keeps CodeRabbit exempt under the temporary kit#753 policy. **This is a change to how fast the gate
-reports, never to what it lets through** — no failing check gained a path to `success`, which
-`scripts/gh/git-pr-checks-e2e-gate.test.ts` continues to assert.
+  GitHub reports the pull request `CLEAN` **and** every required check passes; the only exception is a
+  non-passing set made entirely of CodeRabbit checks (the temporary kit#753 policy). A failing check
+  ends the wait on the poll that sees it, by name (`PR checks failed (failed checks: E2E).`).
+- **Filtering, narrowing or reinterpreting E2E output to get past it is a workaround** —
+  `CLAUDE.md` → "Cross-package problems"; reporting the filtered result honestly does not make it
+  compliant.
+- **`E2E` stays off the default required-check list**; a project opts in through
+  `JOSH_REQUIRED_CHECKS`. `scripts/gh/git-pr-checks-e2e-gate.test.ts` pins both properties.

package/scripts/agent/agent-role-profile.ts

@@ -74,7 +74,7 @@ const PROVIDER_PROFILES = { anthropic: DEFAULT_PROFILES, openai: OPENAI_PROFILES
 
 // **Effort as a function of the run phase, not the role alone** (joshuafolkken/kit#2382). For the first
 // merge only the mechanical ship/bookkeeping region is lowered: the pre-gate resume drives the gate,
-// commit, PR and merge, applying fixes the gate has already named — work SKILL.md §2b calls the opposite
+// commit, PR and merge, applying fixes the gate has already named — work delegation.md calls the opposite
 // of judgement. The design-judgment implementation phases keep the role default, as does any role/phase
 // with no entry, and the review's own judgement is the reviewer role's (`high`), untouched by lowering
 // the worker here. The investigation phase — highest output density — is left for a later merge, once

package/scripts/agent/codex-hooks.ts

@@ -33,22 +33,13 @@ const UNMATCHED_EVENTS: ReadonlySet<string> = new Set(['UserPromptSubmit'])
 const JSON_INDENT = '\t'
 
 function adapter_command(mode: string): string {
-	return hook_launch.bundle_launch_command(
-		`codex-hook-adapter.js ${mode}`,
-		`pnpm exec tsx scripts/hooks/codex-hook-adapter.ts ${mode}`,
-	)
+	return hook_launch.hook_launch_command(`codex-hook-adapter ${mode}`)
 }
 
 // Each Claude-side guard command the adapter stands in for, keyed by that command verbatim.
 const ADAPTED_COMMANDS: ReadonlyMap<string, string> = new Map([
-	[
-		hook_launch.hook_launch_command('pretool-guard.js', 'pretool:guard'),
-		adapter_command('pretool'),
-	],
-	[
-		hook_launch.hook_launch_command('format-edited.js', 'format:edited'),
-		adapter_command('posttool'),
-	],
+	[hook_launch.hook_launch_command('pretool-guard'), adapter_command('pretool')],
+	[hook_launch.hook_launch_command('format-edited'), adapter_command('posttool')],
 ])
 
 function codex_handler(handler: HookHandler): HookHandler {

package/scripts/backlog/backlog-budget.ts

@@ -59,7 +59,7 @@ type BudgetVerdict =
 	typeof RUN_VERDICT | typeof WATCH_VERDICT | typeof STOP_VERDICT | typeof TRIAGE_VERDICT
 
 // What `backlog:next` answered, in the words this decision needs. The mapping is mechanical and is
-// written once, in `backlogrun-steps.md` → "The loop": numbers are `candidates`, `wait` is `blocked` while
+// written once, in `docs/josh-commands-automation.md` → "`josh backlog:offer`": numbers are `candidates`, `wait` is `blocked` while
 // this run has children in flight and `exhausted` when it does not, `none` is `exhausted`, `stop` is
 // `parked`, `triage` is `untriaged`, and `error` or a failed listing is `unreadable`.
 const ANSWERS = ['blocked', 'candidates', 'exhausted', 'parked', 'unreadable', 'untriaged'] as const

package/scripts/backlog/backlog-drive-cli.ts

@@ -1,7 +1,6 @@
 #!/usr/bin/env tsx
 import { setTimeout as sleep } from 'node:timers/promises'
 import { fileURLToPath } from 'node:url'
-import { CONTEXT_CUT_THRESHOLD } from '#scripts/cost-runtime/context-cut-threshold'
 import { hook_decision } from '#scripts/josh/hook-decision'
 import { josh_command } from '#scripts/josh/josh-run'
 import { lane_await, type AwaitState } from '#scripts/lane/lane-await'
@@ -217,7 +216,8 @@ function merge_token(out: string, code: number): string {
 }
 
 // The child's transcript, where its lane recorded one, so `run:merge` can tell an API outage from a
-// failure exactly as it does for the parent that passes `--output` by hand.
+// failure exactly as it does for the parent that passes `--output` by hand. No hand-off threshold: the
+// supervisor runs this loop, and a process has no context to cut (joshuafolkken/kit#3156).
 async function merge(issue: string, owner: string): Promise<MergeResult> {
 	await backlog_drive_owner.assert_current(owner)
 	const lane = await lane_registry.find_open_lane(issue)
@@ -225,7 +225,7 @@ async function merge(issue: string, owner: string): Promise<MergeResult> {
 		child: issue,
 		epic: undefined,
 		repo: undefined,
-		over: CONTEXT_CUT_THRESHOLD,
+		over: undefined,
 		owner: run_carry.owner_of(Number(owner)),
 		output: lane?.output,
 	})
@@ -381,6 +381,7 @@ async function main(argv: ReadonlyArray<string>): Promise<void> {
 const backlog_drive_cli = {
 	end_line,
 	finish: backlog_drive_finish.finish,
+	merge,
 	merge_token,
 	offer_argv: backlog_drive_offer_argv.offer_argv,
 	parse,

package/scripts/backlog/backlog-drive-offer-argv.ts

@@ -3,11 +3,20 @@ import type { DriveState } from './backlog-drive'
 
 const LIST_SEPARATOR = ','
 
+// **A child in flight is never offered** (joshuafolkken/kit#3156). A lane child merges its own PR and
+// drops `in-progress` before GitHub closes the issue and before the loop collects it, so `backlog:next`
+// can offer it again; launching it then is refused by its still-open lane and handed to an AI session.
+function excluded(state: DriveState): ReadonlyArray<string> {
+	return [...new Set([...state.exclude, ...state.in_flight])]
+}
+
 function offer_argv(
 	state: DriveState,
 	carry: RunCarry,
 	forwarded: ReadonlyArray<string>,
 ): ReadonlyArray<string> {
+	const exclude = excluded(state)
+
 	return [
 		'backlog:offer',
 		'--json',
@@ -21,7 +30,7 @@ function offer_argv(
 		String(state.in_flight.length),
 		'--retries',
 		String(state.retries),
-		...(state.exclude.length === 0 ? [] : ['--exclude', state.exclude.join(LIST_SEPARATOR)]),
+		...(exclude.length === 0 ? [] : ['--exclude', exclude.join(LIST_SEPARATOR)]),
 		...forwarded,
 	]
 }

package/scripts/backlog/backlog-next.ts

@@ -16,7 +16,8 @@ import { PROJECT_ROOT } from '#scripts/init/init-paths'
 import { issue_citation } from '#scripts/rules/issue-citation'
 import { backlog_defect_priority } from './backlog-defect-priority'
 import { backlog_pool } from './backlog-pool'
-import { backlog_rank } from './backlog-rank'
+import { backlog_rank, type GateScope } from './backlog-rank'
+import { backlog_restructure } from './backlog-restructure'
 
 // `josh backlog:next` — what the whole opted-in backlog may run next (joshuafolkken/kit#1630).
 //
@@ -278,7 +279,7 @@ function report_retry(context: PoolContext): number {
 	return SUCCESS_EXIT_CODE
 }
 
-// The rows the offer's cap bounds — the standalone half, which `backlog:plan --waves` reads too.
+// The rows the offer's cap bounds — the standalone half.
 function standalone_keys(context: PoolContext): ReadonlySet<string> {
 	return backlog_pool.standalone_keys(context.opted_in.issues, {
 		tracked: epic_index.withheld_children(context.tracking.index, context.opted_in.issues),
@@ -287,6 +288,16 @@ function standalone_keys(context: PoolContext): ReadonlySet<string> {
 	})
 }
 
+// The running lanes still carry the pickup label, so the opted-in listing holds their bodies too —
+// which is what lets a candidate be held back from a restructure a running lane already makes
+// (joshuafolkken/kit#3221). `backlog:plan --waves` reads the same scope, so its first wave is this offer.
+function gate_scope(context: PoolContext): GateScope {
+	return {
+		standalone: standalone_keys(context),
+		declared: backlog_restructure.declared_of(context.opted_in.issues),
+	}
+}
+
 // The `run:solo` gate is applied here rather than in `resolve`, because `backlog:plan` shares
 // `resolve` and a plan made before the run lists everything (joshuafolkken/kit#2776). The holders are
 // read only on a `run` answer — the one answer the gate can change. The cap follows the gate
@@ -302,7 +313,7 @@ async function gate_solo(result: EpicNextResult, context: PoolContext): Promise<
 
 	if (notice !== undefined) console.error(notice)
 
-	const gated = backlog_rank.gate(result, read, repo, standalone_keys(context))
+	const gated = backlog_rank.gate(result, read, repo, gate_scope(context))
 
 	if (gated.notice !== undefined) console.error(gated.notice)
 
@@ -418,7 +429,7 @@ const backlog_next = {
 	READ_FAILURES,
 	VERDICT_TOKENS,
 	resolve,
-	standalone_keys,
+	gate_scope,
 	context_of,
 	run,
 }

package/scripts/backlog/backlog-offer.ts

@@ -5,15 +5,15 @@ import { backlog_next } from './backlog-next'
 // answered — its stdout tokens and its exit code — into the one word `backlog:budget` is then asked
 // with, plus the issue numbers to start and the consecutive-retry count carried to the next ask.
 //
-// **The mapping is `backlogrun-steps.md` → "The loop"'s table, held here so it cannot drift.** That table
-// fixed which `backlog:next` answer becomes which `backlog:budget` word, and it carried two context
-// branches an agent had to apply by hand every iteration: `wait` is `blocked` while this run has
-// children in flight and `exhausted` when it has none, and `retry` is `blocked` until the third
+// **The mapping is `docs/josh-commands-automation.md` → "`josh backlog:offer`", held here so it cannot
+// drift.** It fixes which `backlog:next` answer becomes which `backlog:budget` word, and it carries two
+// context branches an agent once applied by hand every iteration: `wait` is `blocked` while this run
+// has children in flight and `exhausted` when it has none, and `retry` is `blocked` until the third
 // consecutive one, which is `unreadable`. Both are decided from a count here rather than from a
-// judgement.
+// judgement (joshuafolkken/kit#3175 dropped the prose copy from `backlogrun-steps.md`).
 
 // Three consecutive `retry` answers end the run: below that a transport hiccup is re-asked, at it the
-// outage is not a hiccup. `backlogrun-steps.md` → "The loop" is the single source of the count.
+// outage is not a hiccup. "`josh backlog:offer`" is the single source of the count.
 const RETRY_LIMIT = 3
 const FAILURE_EXIT_CODE = 1
 const NO_RETRIES = 0

package/scripts/backlog/backlog-plan-cli.ts

@@ -10,6 +10,7 @@ import { run_invocation } from '#scripts/run/run-invocation'
 import { backlog_named } from './backlog-named'
 import { backlog_next, type OptedIn } from './backlog-next'
 import { backlog_plan, type NamedPlan, type PlanContext } from './backlog-plan'
+import type { GateScope } from './backlog-rank'
 import { backlog_scope } from './backlog-scope'
 import { backlog_waves } from './backlog-waves'
 
@@ -104,9 +105,9 @@ interface Plan {
 	// past the listing cap. Carrying the *whole* index here instead would move that misreport rather
 	// than remove it: the sentence would name an epic that is withholding nothing.
 	tracked: ReadonlyMap<number, number>
-	// The rows the offer's cap bounds, so `--waves` cuts each wave where `backlog:next` does
-	// (joshuafolkken/kit#2928).
-	standalone: ReadonlySet<string>
+	// The rows the offer's cap bounds and the paths each issue restructures, so `--waves` cuts each
+	// wave where `backlog:next` does (joshuafolkken/kit#2928, joshuafolkken/kit#3221).
+	scope: GateScope
 }
 
 // The listing plus whether it was cut. Carried together because the rows alone cannot say whether
@@ -141,7 +142,7 @@ async function classify(
 		repo: context.repo,
 		exclude,
 		tracked: epic_index.withheld_children(context.tracking.index, context.opted_in.issues),
-		standalone: backlog_next.standalone_keys(context),
+		scope: backlog_next.gate_scope(context),
 	}
 }
 
@@ -172,7 +173,7 @@ function print_plan(plan: Plan, listing: OpenListing, view: PlanView): void {
 	const context = context_of(plan, listing)
 
 	if (view.is_waves) {
-		console.info(backlog_waves.format_waves(plan.result, context, plan.standalone))
+		console.info(backlog_waves.format_waves(plan.result, context, plan.scope))
 
 		return
 	}

package/scripts/backlog/backlog-rank.ts

@@ -4,6 +4,7 @@ import { epic_rank } from '#scripts/epic/epic-rank'
 import type { EpicNextResult } from '#scripts/epic/epic-report'
 import { epic_solo, type SoloGate, type SoloSelection } from '#scripts/epic/epic-solo'
 import { git_next_issues } from '#scripts/issue/git-next-issues'
+import { backlog_restructure, type Declared } from './backlog-restructure'
 
 // What the backlog offers, in the order it is decided (joshuafolkken/kit#2928): rank, then the
 // `run:solo` gate, then the cap. `backlog:next` and `backlog:plan --waves` both call `select`, so the
@@ -78,29 +79,37 @@ interface OfferInput {
 	repo: string
 	// The keys of the standalone rows — the ones the cap bounds.
 	standalone: ReadonlySet<string>
+	// The paths each issue restructures; two candidates claiming one are not offered together
+	// (joshuafolkken/kit#3221). Absent, nothing is separated.
+	declared?: Declared
 }
 
+// The restructure separation runs before the cap, for the reason the gate does: the cap only ever
+// removes what would otherwise be offered.
 function select(input: OfferInput): SoloSelection {
 	const ranked = rank(input.candidates, input.pool)
+	const { read, repo } = input
+	const gated = epic_solo.select(ranked, read, repo)
+	const separated = backlog_restructure.separate(gated, input.declared ?? new Map(), { read, repo })
 
-	return cap(epic_solo.select(ranked, input.read, input.repo), input.standalone)
+	return cap(separated, input.standalone)
+}
+
+interface GateScope {
+	standalone: ReadonlySet<string>
+	declared: Declared
 }
 
 // `backlog:next`'s gate: `epic_solo.gate` with this selection in place of its bare one.
-function gate(
-	result: EpicNextResult,
-	read: BusyRead,
-	repo: string,
-	standalone: ReadonlySet<string>,
-): SoloGate {
+function gate(result: EpicNextResult, read: BusyRead, repo: string, scope: GateScope): SoloGate {
 	const pool = everything_in(result)
 
 	return epic_solo.gate(result, read, repo, (candidates) =>
-		select({ candidates, pool, read, repo, standalone }),
+		select({ candidates, pool, read, repo, ...scope }),
 	)
 }
 
 const backlog_rank = { everything_in, gate, rank_result, select }
 
 export { backlog_rank }
-export type { OfferInput }
+export type { GateScope, OfferInput }