@joshuafolkken/kit 1.1229.0 → 1.1370.0

package/.claude/skills/workflow-commands/observation-ledger.md

@@ -1,24 +1,25 @@
 # The observation ledger — grammar, commit path and promotion
 
 **Read only when the depth test in `observation-filing.md` turns an observation away, or a user
-reports a bug** (its kind of miss, below), in the turn that appends the line (joshuafolkken/kit#3176).
+reports a bug** (its kind of miss, below), in the turn that appends the line.
 A run that files outright, or finds nothing, never reads it. This file is the single source of the ledger's grammar, its commit path and the
-second-sighting promotion.
+second-sighting promotion. Provenance: `docs/maintainers/observation-ledger-rationale.md` → "Where
+each rule came from".
 
 ## The ledger — where an observation that cannot cite a blockage goes
 
-**An observation the depth test turns away is recorded in the ledger, not discarded**
-(joshuafolkken/kit#1728). Rationale: `docs/maintainers/observation-ledger-rationale.md` → "Why the
+**An observation the depth test turns away is recorded in the ledger, not discarded.**
+Rationale: `docs/maintainers/observation-ledger-rationale.md` → "Why the
 ledger exists".
 
 - **The destination is the `.josh/observations/` directory in the repository the
   observation is about** — the same repository the Issue would have been filed into — **one file per
-  issue** (joshuafolkken/kit#2919): append to `<N>.md` for the issue the run is executing (the number
+  issue**: append to `<N>.md` for the issue the run is executing (the number
   its branch leads with, a lane's included), or to `<YYYY-MM-DD>.md` for a line written on the
   default branch outside any issue's run. Parallel lanes therefore write different files, and their
   pull requests never conflict on the ledger. **The count and the append are both run in that
   repository's checkout** — in this repository, the work tree the run is in, a lane's inside a lane —
-  resolved the way `target-repository.md` (`target-repository.md`) resolves any cross-repository target, and the
+  resolved the way `target-repository.md` resolves any cross-repository target, and the
   directory is created on the first append where that repository has none. **The subject decides, never the
   working directory**: an observation about this package's own orchestration, seen while a run is
   inside a repository that consumes it, is recorded here rather than there — the append follows the
@@ -61,18 +62,22 @@ here rather than in the ledger** (`docs/maintainers/observation-ledger-rationale
 ledger exists").
 
 **The identity key is the whole of the repeat test — never a similarity judgement about the prose.**
-Choose the key from the phenomenon rather than from the run, then count what the ledger already holds
-for it, in that repository's checkout rather than the working directory. **Every file of the
-directory is counted**, because a recurrence is a recurrence whichever issue's file each sighting
-sits in. **The `|| true` is not decoration**: `grep -c` exits non-zero on a count of zero, which is
-the first-sighting branch and the common one, so without it the step reads as a failed command
-wherever an exit status is being watched. **A missing directory is still a first sighting** — `cat`
-complains on standard error and the count is zero; the append below creates the directory.
+Choose the key from the phenomenon rather than from the run, then record the sighting with one
+command — it counts what the ledger already holds for the key, appends the line and prints the
+verdict:
 
 ```bash
-cat <that repository's checkout>/.josh/observations/*.md | grep -c '^- k:<slug> |' || true
+pnpm josh observation:record <slug> d<n> '<where>' '<what>' [--checkout <that repository's checkout>]
 ```
 
+Standard output is one token: `file` (this is the second sighting — file it, below) or `ledger` (the
+line is the record, nothing to file); standard error lists the earlier sightings and the file
+appended to. A line that breaks the grammar, or uses `k:example`, is refused with exit 1 and nothing
+appended. **Every
+file of the directory is counted**, in the named checkout rather than the working directory, because
+a recurrence is a recurrence whichever issue's file each sighting sits in; a missing directory is a
+first sighting, and the append creates it.
+
 Free-text comparison is what the key exists to replace, so two lines that read alike under different
 keys are two observations, and a mis-keyed entry is corrected by appending a correctly-keyed line
 rather than by editing the one already written.
@@ -83,27 +88,34 @@ could not.
 
 ## The commit path — how an appended line reaches the default branch
 
-**An append nobody commits is an append nobody can count** (joshuafolkken/kit#1756). Rationale:
+**An append nobody commits is an append nobody can count.** Rationale:
 `docs/maintainers/observation-ledger-rationale.md` → "Why the ledger has a commit path".
 
-- **A run's appended lines ride its own commit** (joshuafolkken/kit#2763). `pnpm josh git` stages
+- **A run's appended lines ride its own commit.** `pnpm josh git` stages
   `.josh/observations/` with the run's other changes, in the one staging step every entry
   point goes through (`scripts/git/git-staging.ts`), so the lines are reviewed and merged with the
   pull request of the run that recorded them, and the run's CI is the only wait they cost.
   **Record before the commit, not after the merge:** a finding recorded with `pnpm josh review:record`
   before `pnpm josh git -y` is carried; the time while CI runs is for the records that need no CI
   result — filing an observation Issue, drafting the completion report.
-- **A line that breaks the grammar is not carried** (joshuafolkken/kit#2123). The staging step parses
-  every file of the ledger first — after moving lines still on an old single-file path
-  (joshuafolkken/kit#2724, joshuafolkken/kit#2919) — and on a broken line leaves the ledger out of the
+- **A line that breaks the grammar is not carried.** The staging step parses
+  every file of the ledger first — after moving lines still on an old single-file path — and on a broken line leaves the ledger out of the
   commit and says so; the commit itself goes ahead.
-- **`pnpm josh followup` commits a line appended after the run's commit onto the pull request, before
-  the merge** (joshuafolkken/kit#2919) — a second review round's record is the usual case. After the
-  merge gates and before the CI wait, `followup` reads the tree and, **only when the ledger holds a
-  pending append**, stages the ledger paths alone, commits them and pushes the branch; the CI wait
-  that follows covers the pushed commit. A broken line refuses the merge, because the line would
-  otherwise be lost with the branch. A run whose lines rode its commit pays nothing.
-- **A lane carries its own lines, in its own pull request** (joshuafolkken/kit#2919). Its writers
+- **A review round that passes after the pull request opened is recorded on the Issue, not in the
+  ledger** — `pnpm josh review:record --issue <N> --comment` posts the same `- rf:` lines as a comment
+  and appends nothing. That round reads only, so no commit of the run's follows it; a line in the tree
+  would be pushed onto the open pull request and its CI would start over. `pnpm josh ship --review`
+  does this for a passing round 2. **A round 2 that blocks records in the tree as before** — the fix it
+  stops for is pushed anyway and carries the lines. The comment's lines are outside the count
+  `pnpm josh review:findings` and the retrospective read.
+- **`pnpm josh followup` commits any other line appended after the run's commit onto the pull request,
+  before the merge** — the residual path, for an observation recorded between the commit and the
+  merge. After the merge gates and before the CI wait, `followup` reads the tree and, **only when the
+  ledger holds a pending append**, stages the ledger paths alone, commits them and pushes the branch;
+  that push restarts the pull request's CI, and the wait that follows covers it. A broken line refuses
+  the merge, because the line would otherwise be lost with the branch. A run whose lines rode its
+  commit pays nothing.
+- **A lane carries its own lines, in its own pull request.** Its writers
   append to its own tree's `<N>.md`, so the two steps above take them to the default branch exactly as
   they do for a run in the primary checkout. **Nothing is held in the primary checkout for later.**
 - **`pnpm josh observations:flush` is left for a line written outside any issue's run** — the
@@ -114,11 +126,8 @@ could not.
   and refuses a working tree holding anything besides the ledger, so a run in progress cannot be
   flushed out from under. **Nothing is committed to the default branch directly.**
 - **Nothing to flush is an answer, not a failure.** With the ledger matching the commit it sits on
-  the command prints `clean` and exits 0 — most cycles append nothing, and a command that errored
-  there would be one nobody runs.
-- **The count the promotion below reads is a count of the default branch**, which is what this route
-  buys: a ledger line that merged is one every later run, every other machine and every fresh clone
-  can see, and only then can a second sighting be recognized as one.
+  the command prints `clean` and exits 0.
+- **The count the promotion below reads is a count of the default branch.**
 
 ## The second sighting is what files it
 
@@ -126,12 +135,13 @@ could not.
 judged (rationale: `docs/maintainers/observation-ledger-rationale.md` → "Why a second sighting
 files"):
 
-- **On the count answering exactly `1`, the observation is filed**, at depth 1 or deeper, with no
-  depth-0 citation — `1` and not "1 or more", because a higher count means the Issue was already
-  opened by the sighting that answered `1`. The ledger line is appended as well, because the ledger
-  stays append-only.
-- **The Issue quotes the ledger's own dates — the first sighting's and this one's** — so the reader
-  can check the promotion against the file instead of taking the run's word for it.
+- **On `observation:record` answering `file`, the observation is filed**, at depth 1 or deeper, with
+  no depth-0 citation. It answers `file` only when exactly one earlier sighting exists — a higher
+  count means the Issue was already opened by the sighting before. The line is appended either way,
+  because the ledger stays append-only.
+- **The Issue quotes the ledger's own dates — the first sighting's and this one's**, both on the
+  command's standard error — so the reader can check the promotion against the file instead of
+  taking the run's word for it.
 - **Both ceilings still apply**, exactly as `observation-filing.md` states them: the 10-per-run cap counts a promoted
   filing, and the WIP cap still bites, since a promoted observation blocks nothing and is therefore
   still discretionary.
@@ -143,7 +153,7 @@ Issue, not new ones.
 ## A user-found bug is recorded by its kind of miss (user-found)
 
 **A user-reported bug is fixed or filed as always; this records the *kind of miss* alongside so the
-category never recurs as a first sighting** (joshuafolkken/kit#2246). The key is the **category of
+category never recurs as a first sighting.** The key is the **category of
 oversight** — `k:missed-case-worktree` — so a second bug of the same kind counts against the first.
 **Depth `d1`, never `d0`**: the *kind of miss* is what a run fails to enumerate, which the table puts
 at depth 1. Nothing else changes; the `<what>` field leads with `User-reported:`, and no second

package/.claude/skills/workflow-commands/pre-gate-cut.md

@@ -106,8 +106,8 @@ pnpm josh run:cut --resume <N>
   for the plan and the recorded decisions, then go straight to `pnpm josh gate`.
 - `resume-impl` (0) — like `resume`, but the cut was taken **during** implementation. Skip the title, the plan, the fresh hold claim and the split assessment,
   re-read the plan, then **continue implementation** — do **not** go straight to the gate.
-- `handed-off` (0) — a successor has already adopted this cut, `is_handed_off` is spent
-  (joshuafolkken/kit#1935). This process was woken **after** its own cut. **End the turn quietly and do
+- `handed-off` (0) — a successor has already adopted this cut, `is_handed_off` is spent.
+  This process was woken **after** its own cut. **End the turn quietly and do
   nothing**: a benign stop, no Telegram owed.
 - `stale` (1) — the record does not match the tree (wrong branch, a clean tree, an expired record, or
   an unknown hand-off state). **A resume failure**: send a `confirmation` Telegram and stop; never gate
@@ -145,7 +145,7 @@ decisions are read back from the issue. Rationale:
 - **The cut is exclusive** — `run:cut` writes the record with an exclusive create, so a second cut on
   the same tree is refused `busy`.
 - **The resume is unique.** Taking the hand-off over spends it — a second `run:cut --resume` reads a
-  spent record and is answered `handed-off` (joshuafolkken/kit#1935), and the take-over is itself an
+  spent record and is answered `handed-off`, and the take-over is itself an
   exclusive create, so two resumes racing cannot both win. One lane crosses the pre-gate boundary
   exactly once.
 
@@ -176,7 +176,7 @@ not once per run**; **An edit reissued right after a refusal passes**; **An unme
 warrants the cut**; **It is silent between a cut and its resume**. Rationale:
 `docs/maintainers/pre-gate-cut-rationale.md` → "Why the rules are guards, not prose";
 `scripts/rules/implementation-cut.ts` implements it. A child that ended without cutting is detected
-after the fact by `pnpm josh run:ending <N> --output <path>` (joshuafolkken/kit#2139).
+after the fact by `pnpm josh run:ending <N> --output <path>`.
 
 ## The threshold
 
@@ -191,8 +191,7 @@ the push is never a turn boundary (`chain-rule.md`).
 
 **The trigger**: a dispatched lane child about to stop for a decision (a Tier B toss-up, a Tier C
 action, an upstream defect) parks its own Issue first — `backlogrun-park.md` → "park and
-continue" — so the parent's `pnpm josh run:liveness` reads it `settled` (joshuafolkken/kit#2034),
-after #2012 and #2011. A `needs-human-review` or `already-done` stop already carries its label.
+continue" — so the parent's `pnpm josh run:liveness` reads it `settled`. A `needs-human-review` or `already-done` stop already carries its label.
 `pnpm josh rule:guard` refuses `pnpm josh notify --task-type confirmation` from a marked child until
 then — **It fires once per run.**, and a person's own `fullrun` is never refused
 (`scripts/rules/lane-park.ts`).
@@ -205,9 +204,10 @@ the child promoted this run, on every occurrence (`scripts/rules/lane-split-park
 ### The interactive ask is refused one call earlier
 
 **The trigger**: a headless session ends the turn on an interactive ask, so the notify guard never
-fires (#2178). `pnpm josh rule:guard` therefore refuses `AskUserQuestion` for a marked lane child on
-every occurrence — park the question instead (joshuafolkken/kit#2201), completing
-joshuafolkken/kit#2034. A child that slips past is recovered by `pnpm josh run:ending`, which lifts
+fires. `pnpm josh rule:guard` therefore refuses `AskUserQuestion` for a marked lane child on
+every occurrence — park the question instead.
+A child that slips past is recovered by `pnpm josh run:ending`, which lifts
 the refused ask into the park basis; `scripts/rules/lane-interactive-ask.ts` and the shared
 `scripts/agent/interactive-ask.ts` implement it.
 
+Provenance of each rule: `docs/maintainers/pre-gate-cut-rationale.md` → "Where each rule came from".

package/.claude/skills/workflow-commands/prerequisite.md

@@ -1,24 +1,32 @@
 # A prerequisite discovered mid-run — a dependency, not a park
 
-**This file is the single source, so the entry read carries the trigger and the pointer, not the
-procedure** (joshuafolkken/kit#2189). `SKILL.md` → §2's table keeps the trigger, and each entry file
-(`entry-sequence.md` / `backlogrun-park.md`) routes here for the definition. It is
-read at its point of use — the moment a run discovers that another Issue in this repository has to
-land first.
+**The single source of the prerequisite branch**, read at its point of use — the moment a run
+discovers that another Issue in this repository has to land first. History:
+`docs/maintainers/prerequisite-rationale.md` → "Where each rule came from".
 
-**A prerequisite discovered mid-run is a dependency, not a park.** Finding that something else in
-*this* repository has to land first is a third situation, distinct from an upstream defect and from a
-split: the Issue in hand is still one deliverable, it just needs another one before it.
+**A prerequisite discovered mid-run is a dependency, not a park** — the Issue in hand is still one
+deliverable, it just needs another one before it.
 
-**Four kinds of other work turn up mid-run, and the procedure differs for each.** Reading one as
-another is the failure this section exists to prevent:
+**Four kinds of other work turn up mid-run, and the procedure differs for each:**
 
 | What turned up                                                              | What to do                                                                                                              |
 | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
 | A defect originating in **another package**                                 | File the upstream Issue and **stop** — Tier A for a first-party target; a third-party one is Tier C, recorded and drafted rather than filed (`CLAUDE.md` → "Cross-package problems"; `prompts/collaboration-workflow/upstream-interrupt.md`) |
 | This Issue was really **several** (a split)                                 | File the children and the epic and **stop** — except under `backlogrun`, whose authorization already covers a batch, so the children are filed and run through (`split-assessment.md`) |
 | Another Issue in **this** repository has to land first (**a prerequisite**) | This section                                                                                                            |
-| Something worth filing that is **none of the three** (**an observation**)   | File it **without asking** — Tier A for a first-party target — and **carry the run straight on**: nothing is stashed, nothing is parked (`observation-filing.md`). **A delegated child does not file here**, and a filing at depth 1 or deeper cites the depth-0 work it blocked; one that cannot cite it goes to the run's own `.josh/observations/<N>.md` and is filed on its second sighting — all of them `observation-filing.md`'s |
+| Something worth filing that is **none of the three** (**an observation**)   | File it **without asking** in an unattended run, propose it first in an interactive session — Tier A for a first-party target — and **carry the run straight on**: nothing is stashed, nothing is parked (`observation-filing.md`). **A delegated child does not file here**, and a filing at depth 1 or deeper cites the depth-0 work it blocked; one that cannot cite it goes to the run's own `.josh/observations/<N>.md` and is filed on its second sighting — all of them `observation-filing.md`'s |
+
+**A stop on a defect in this repository's own gate or run tooling is a prerequisite too.** The
+defect's Issue is the prerequisite — filed if it is not yet, used by its number if it is — and it is
+never recorded as an upstream interrupt, because the tooling is not another package
+(`prompts/collaboration-workflow/upstream-interrupt.md` → "実行中のリポジトリ自身のラン機構の不具合").
+
+**A stop that a dependency can express is never a person's decision.** This is the single source of
+that rule. A recommendation of "record `<N>` must land first and go on" is taken without asking;
+`needs-decision` is reserved for a design decision nobody has made, a Tier B toss-up, or a Tier C
+action. `pnpm josh run:merge` enforces the computable half: an unfinished child with an open
+blocked-by is released to **wait** — no `needs-decision` label, no failure counted — and the backlog
+offer hands it back once its blockers merge.
 
 **File the prerequisite with the `route:tier-a` label**, so a Tier A filing made during implementation
 stays countable by filing route afterwards. **This paragraph belongs to the prerequisite row, not to
@@ -33,7 +41,7 @@ The command lints the body against `prompts/collaboration-workflow/issue-templat
 classification labels it declares, and runs the duplicate scan and `epic:bundle` itself
 (`docs/josh-commands-backlog.md` → `josh issue:file`).
 
-Every "file the prerequisite" below means that labelled filing, and it always happens **first**: the
+Every *file the prerequisite* step below means that labelled filing, and it always happens **first**: the
 steps after it name a number that does not exist until it is. **Its duplicate scan is read exactly as
 it is for a `new` entry** (`issue-scout.md`): a filing made mid-run is the one most likely to duplicate something.
 
@@ -42,8 +50,8 @@ it is for a `new` entry** (`issue-scout.md`): a filing made mid-run is the one m
 - **A named epic under `backlogrun`** files without confirmation, records the dependency with
   `pnpm josh epic --add <E> <N> --before <M>` — `<E>` the epic, `<N>` the prerequisite just filed,
   `<M>` the child in hand — and the run **continues rather than parking it** (`backlogrun-park.md` → "A
-  prerequisite discovered mid-run"). Parking is only for a prerequisite that *cannot* be expressed as
-  a dependency — one needing a design decision nobody has made, a Tier B toss-up, or a Tier C action.
+  prerequisite discovered mid-run"). A child outside any epic records the same relation on itself
+  directly; that branch is the same section's.
 - **`fullrun` / `halfrun`** file the same way without asking, insert the prerequisite into the epic
   that already tracks the Issue or create one over both, and then **stop**, leaving the person one
   command to type (`fullrun.md` / `halfrun.md`). Typing `fullrun` approved implementing **one** Issue;
@@ -53,7 +61,7 @@ it is for a `new` entry** (`issue-scout.md`): a filing made mid-run is the one m
 
 - **`git stash push -u` — the `-u` is not optional.** The work in progress almost always includes a
   new `*.test.ts`, which is untracked, and a stash without `-u` leaves exactly those files in the tree
-  for the next child's `git switch main && git pull` to refuse.
+  for the next child's `pnpm josh ms` to refuse.
 - **The Issue comment is what gets the stash popped, not the Telegram.** The run that later picks the
   paused Issue up reads that comment and pops before implementing — **by message,
   `pnpm josh stash:pop "<the -m message>"`, never a positional `git stash pop`**, because the stash is

package/.claude/skills/workflow-commands/progress-watcher.md

@@ -2,7 +2,7 @@
 
 **Read this file in full when the run's hold is claimed, before the watcher starts.** It is a
 point-of-use document, never an entry read, and the single source of the heartbeat for `fullrun`,
-`halfrun`, `prrun` and the `backlogrun` parent alike (joshuafolkken/kit#3172). `kickoff` starts none.
+`halfrun`, `prrun` and the `backlogrun` parent alike. `kickoff` starts none.
 
 ## Progress while the run is quiet
 
@@ -13,7 +13,7 @@ point-of-use document, never an entry read, and the single source of the heartbe
 pnpm josh run:progress --wait --output <the transcript path of each delegated unit>   # in the background
 ```
 
-**Start it once; it reports by itself** (joshuafolkken/kit#3102). Each silence interval appends the
+**Start it once; it reports by itself.** Each silence interval appends the
 five labelled lines to the run's event stream as a heartbeat and to the ambient log, prints nothing to
 standard output and keeps running — so a scheduled report never wakes the session, and the session
 relays none. **It exits only on one of three, and the command computes which:**
@@ -27,8 +27,8 @@ relays none. **It exits only on one of three, and the command computes which:**
 **A report is not an exit, and neither is a decline** — with no run recorded it keeps waiting, and the
 `--hours` exit says so on standard error.
 
-**`pnpm josh run:watcher:guard` detects a missed restart** (joshuafolkken/kit#2113): wired into
-`pretool-guard` (joshuafolkken/kit#2353), it refuses the next tool call while lane children are in
+**`pnpm josh run:watcher:guard` detects a missed restart**: wired into
+`pretool-guard`, it refuses the next tool call while lane children are in
 flight and the watcher's life record has gone stale — once per run, so the restart is not blocked.
 
 **`--mark` at every real report.** Whenever the run reports something of its own, run
@@ -47,18 +47,22 @@ Rationale: `docs/maintainers/progress-watcher-rationale.md` → "Why the heartbe
 
 ### What a report says
 
-**Every unscheduled progress statement is answered by `pnpm josh run:progress --once`** — the reply to
-an explicit ask and the note just after a run starts alike; it is exempt from the interval and records
-the report itself, so no `--mark` beside it. **Relay its five field lines verbatim** — round, rephrase
+**Every unscheduled progress statement is answered by `pnpm josh run:progress --once`** — under
+`backlogrun`, `pnpm josh run:board --chat` in one code block — the reply to an explicit ask and
+the note just after a run starts alike; each is exempt from the interval and records the report
+itself, so no `--mark` beside it. **Relay its lines verbatim** — round, rephrase
 or re-label nothing, and **never write a clock time the command did not print**; where a field is
 missing, say so. **A field's empty value is an observation, never a state** (`record unread` is not
 *not stalled*), and **nothing in the lines is a verification result** — no gate, CI or check rollup.
 
-**The heartbeat is ambient, never a Telegram.** `pnpm josh run:event --watch` is its reader, in a pane
-of the person's own; **no session relays the stream** — name the watch command once, at the first cut
-or when asked. `pnpm josh run:wake --list` is the one-line read for a person who types for it.
+**The heartbeat is ambient, never a Telegram.** `pnpm josh run:board` is its reader, in a pane of the
+person's own; **no session relays the stream** — name the board command once, at the first cut or when
+asked; `.vscode/tasks.json` starts it on folder open once VSCode's automatic-task prompt is allowed.
+`pnpm josh run:event --watch` stays for following the raw events one by one. `pnpm josh run:wake --list` is the one-line read for a person who types for it.
+**A request for periodic progress is never a CronCreate job** — on screen, name `pnpm josh run:board`;
+off-screen, start `pnpm josh run:board --every <minutes>` in the background (`docs/josh-commands-run.md`).
 
-**A stop is the only interrupt** (joshuafolkken/kit#2136): a `backlogrun` that has stopped ends with
+**A stop is the only interrupt**: a `backlogrun` that has stopped ends with
 `pnpm josh run:carry --end --stopped "<reason>"`, which sends one ⏸️ confirmation; a parked child sends
 its own (`backlogrun-park.md`). Rationale: `docs/maintainers/progress-watcher-rationale.md` → "Why the
 signal tiers are split this way".
@@ -88,3 +92,5 @@ notification, and the running `--wait` is stopped in the same turn, since no rep
 covers `halfrun`'s stop before commit, a `needs-human-review` stop, a split or prerequisite stop, and a
 `backlogrun` named issue's failure stop. Rationale: `docs/maintainers/progress-watcher-rationale.md` →
 "Why the watcher runs where it does".
+
+Provenance of each rule: `docs/maintainers/progress-watcher-rationale.md` → "Where each rule came from".

package/.claude/skills/workflow-commands/prrun.md

@@ -1,10 +1,10 @@
 # `prrun` — the manifest (plan → implement → PR → green → stop, a person merges)
 
 `prrun` sits between `halfrun` (stop before commit) and `fullrun` (auto-merge). It runs `fullrun`
-up to a green, mergeable pull request and **stops before the merge**, so a person merges by hand
-(joshuafolkken/kit#3023). **Read `fullrun.md` and `entry-sequence.md` for every step** — the entry
+up to a green, mergeable pull request and **stops before the merge**, so a person merges by hand.
+**Read `fullrun.md` and `entry-sequence.md` for every step** — the entry
 sequence, the step lists, the gate, the review and the stop branches are `fullrun`'s, unchanged. This
-file names only the difference, never a second copy of the procedure.
+file names only the difference.
 
 ## The difference — the entry
 

package/.claude/skills/workflow-commands/retrospective.md

@@ -1,21 +1,19 @@
 # The end-of-run retrospective
 
 **This is the retrospective's procedure, and it is read when `run:step` prints the retrospective step —
-not at the entry** (joshuafolkken/kit#2328). `SKILL.md` → §2's table keeps the rule itself: run what `run:step` prints once,
+not at the entry.** `SKILL.md` → §2's table keeps the rule itself: run what `run:step` prints once,
 file the improvements worth carrying into the next run, stack the rest, and mark the step done.
-Everything that decides *how* — what the four sections mean, how the top two are chosen rather than
-rationed, the exclusions, and the `auto-ok` default that lets the next run pick them up — is here,
-because none of it binds until a run has actually drained its backlog. A run that never empties its pool
-never reads it; the one that does reads it in full, in the same turn, before it files.
+Everything that decides *how* — what the four sections mean, how the top two are chosen, the
+exclusions, and the `auto-ok` default — is here. Read it in full, in the same turn, before filing.
 
 **When it fires is not this file's, and not a judgement.** The run driver prints the step the moment the
 backlog drains — `backlog:offer` marks that drain on the event stream and `run:step` fires the
 retrospective at it, *before* the idle watch, so the improvement issues it files are what the watch then
-picks up (joshuafolkken/kit#2335); a run that stops without draining — the failure guard, `--idle 0` —
-still prints it at the stop position. Either way the rule that decides *when* a run acts lives in
-`run:step`'s state transitions rather than in prose here, which is `CLAUDE.md`'s run-driver rule. This
-file is reached only once the step is already owed. It is kit-only — `run:step` prints the step only in
-the kit repository — so a consumer run never reaches this procedure.
+picks up; a run that stops without draining — the failure guard, `--idle 0` — still prints it at the
+stop position. It is kit-only — `run:step` prints the step only in the kit repository.
+
+Rationale: `docs/maintainers/retrospective-rationale.md` → "Why the retrospective is read at its step";
+provenance: `docs/maintainers/retrospective-rationale.md` → "Where each rule came from".
 
 ## The digest is read, not skimmed
 
@@ -45,13 +43,10 @@ improves, and a `depth:2` finding names which decision it turns on (`observation
 test"). An improvement that cannot pass the test is not filed; it is not a shortfall of the two-item
 count, it simply is not yet a finding.
 
-**Order what passes by effect, and file the top two.** This is a selection, not a ration
-(`observation-filing.md` → "This is not the count cap"): nothing that passed the test is lost, because
-**the third onward is stacked in the observation ledger**, on the same append path
-`pnpm josh observations:flush` already drains. So "two" is the amount one turn hands the next run, not a
-ceiling on what may be recorded. **File nothing when nothing passes** — a run whose measurements show no
-improvement worth carrying files zero Issues, and that is what makes the "file → drain → file again"
-loop converge.
+**Order what passes by effect, and file the top two.** **The third onward is stacked in the observation
+ledger**, on the same append path `pnpm josh observations:flush` already drains. **File nothing when
+nothing passes** — a run whose measurements show no improvement worth carrying files zero Issues.
+`docs/maintainers/retrospective-rationale.md` → "Why the top two are a selection, not a ration".
 
 **Exclude what is already filed or already done, through the existing scout** (`issue-scout.md`). File
 each with `pnpm josh issue:file`, which runs the scout before creating anything: an **open** candidate
@@ -73,7 +68,7 @@ retrospective run on the carry record, so `run:step` prints `stop` from then on
 second time. The mark rides the record across a session cut and is removed with the record at
 `pnpm josh run:carry --end`, so one invocation runs the retrospective exactly once whether or not it was
 cut. **`--summary` is required** — the same close writes it as one `retrospective` event on the event
-stream (joshuafolkken/kit#2342), so a zero-filing retrospective differs from one that never ran; name
+stream, so a zero-filing retrospective differs from one that never ran; name
 the issues filed (or that none were) and the candidates dropped with why.
 
 **A dispatched lane child never reaches any of this** — the batch runs the retrospective at its own end,

package/.claude/skills/workflow-commands/split-assessment.md

@@ -29,9 +29,10 @@ whether *several findings from one session* are one Issue — and reads the **sa
 same conjunction**: separability, and whether the whole clearly exceeds one gate.
 `pnpm josh issue:fold "<title>" …` answers `fold` / `separate` / `no-fold-needed`; its size half is
 `pnpm josh split:assess`, called not recomputed, and `separate` needs both halves exactly as `split`
-does. **There is no second criterion.** `observation-filing.md`'s observation, the review round cap's branch 2 and `prerequisite.md`'s
-prerequisite each route a second filing through it, delivered by `pnpm josh rule:guard` at the run's
-second `pnpm josh issue:file` call, never the first.
+does. A diff with no non-test file, or none readable, answers `undetermined`: the size is then the
+whole request's estimate above. **There is no second criterion.** `observation-filing.md`'s observation, the review round cap's branch 2 and `prerequisite.md`'s
+prerequisite each route a second filing through it — `pnpm josh issue:file` asks it itself at the
+run's second filing, never the first, and holds only a `fold`.
 
 ## Diff size is not a reason to split, and that is measured
 
@@ -76,7 +77,8 @@ moment that child merges and closes.
 
 **Each split child is filed with the `route:split` label** —
 `pnpm josh issue:file "<sub-title>" --body-file <body-file> --depth <n> --route split` — so the
-backlog's composition stays countable by filing route rather than by grepping issue bodies.
+backlog's composition stays countable by filing route rather than by grepping issue bodies. A split of
+a person's `kickoff new` also takes `--requested` (`kickoff.md` → "Words typed after `new`").
 
 ## Promote, or create a new epic
 

package/.claude/skills/workflow-commands/target-repository.md

@@ -1,41 +1,39 @@
 # The `owner/repo#` prefix — which repository the run acts on
 
 **This file is the prefix's single source, read at its point of use — the moment an entry is typed with an
-`owner/repo#` prefix (or a short `repo#` name), not at any entry** (joshuafolkken/kit#2161). A run
-given a bare `#N` or `new` targets the session's own repository and never reaches it, so it costs a
-workflow entry nothing to leave it here. `SKILL.md` → §2's table keeps the trigger and points here.
+`owner/repo#` prefix (or a short `repo#` name), not at any entry.** A run given a bare `#N` or `new`
+targets the session's own repository and never reaches it. `SKILL.md` → §2's table keeps the trigger and
+points here. Rationale: `docs/maintainers/target-repository-rationale.md` → "Why the prefix reads as it does".
 
 Every entry point takes the target repository in front of the Issue reference. Without it the target
 is the repository the session runs in.
 
 ```
-kickoff joshuafolkken/kit#412
+kickoff joshuafolkken/kit#<N>
 kickoff kit#new
 kickoff kit#new "<title>"
-fullrun joshuafolkken/app-kit#12
-halfrun kit#412
-backlogrun kit#1 kit#2
-backlogrun joshuafolkken/kit#858 --only
+fullrun joshuafolkken/app-kit#<N>
+halfrun kit#<N>
+backlogrun kit#<N> kit#<M>
+backlogrun joshuafolkken/kit#<N> --only
 ```
 
-- **One definition, every entry point.** The prefix goes where `#N` goes, so no new keyword is added,
-  and `owner/repo#new` stands in the same slot as `owner/repo#N`.
+- **One definition, every entry point.** The prefix goes where `#N` goes, and `owner/repo#new` stands
+  in the same slot as `owner/repo#N`.
 - **A short name expands by prefixing the session repository's owner** — `pnpm josh repo:party`
-  computes the party — and **never by searching kit#869's map**, which answers where a checkout is
-  rather than which repository is meant. A short name therefore satisfies the first-party test (owner
-  equality) by construction, so **there is structurally no path by which a short name resolves to a
-  third-party target**, and a repository that is not checked out here is still a valid `kickoff`
-  target. A name that does not exist fails as `gh` not found: report it, never read it as a near-miss
-  for another name.
-- **It is not the standing prohibition on a bare `#N`.** What that forbids is a bare *Issue number*,
-  which resolves without complaint to a different issue of the same number; a bare *repository* name
-  whose owner is determined has no such failure mode.
+  computes the party — and **never by searching `pnpm josh doctor`'s checkout map**. A short name
+  therefore satisfies the first-party test (owner equality) by construction, so **there is structurally
+  no path by which a short name resolves to a third-party target**, and a repository that is not
+  checked out here is still a valid `kickoff` target. A name that does not exist fails as `gh` not
+  found: report it, never read it as a near-miss for another name.
+- **It is not the standing prohibition on a bare `#N`**, which forbids a bare *Issue number*; a bare
+  *repository* name whose owner is determined is allowed.
 - **An explicit owner that is not the session's is a third-party target, and it stops the run.**
-  `fullrun <other-owner>/repo#12` names a tracker we do not own, and every write there is Tier C
+  `fullrun <other-owner>/repo#<N>` names a tracker we do not own, and every write there is Tier C
   (`CLAUDE.md` → "Third-party repositories are Tier C"). **Decide it mechanically** with
   `pnpm josh repo:party <owner/repo>` — a `third-party` verdict stops the run. Typing the prefix is not the
-  explicit instruction that rule requires. **Send a `confirmation` Telegram and stop** — nothing has
-  been produced yet, so there is no finding to record and no draft to prepare.
+  explicit instruction that rule requires. **Send a `confirmation` Telegram and stop** — there is no
+  finding to record and no draft to prepare.
 - **No prefix leaves the behavior exactly as it was** — the target is the session's repository.
 - **`kickoff` needs no checkout**: name the target repository with `--repo <owner/repo>` on every
   `pnpm josh issue:file` call and in the path of every `gh api` call, and never clone. The one exception
@@ -45,15 +43,14 @@ backlogrun joshuafolkken/kit#858 --only
   `direct-filing` guard, and `pnpm josh issue:file` lints an epic body against the Issue template. The
   promote arm stops the same way.
 - **The implementing entries require a checkout and never create one — when the target is another
-  repository.** A prefix naming the session's own repository changes nothing (`fullrun kit#412` in the
-  kit checkout behaves exactly as `fullrun #412`). Otherwise resolve the checkout from `pnpm josh
+  repository.** A prefix naming the session's own repository changes nothing (`fullrun kit#<N>` in the
+  kit checkout behaves exactly as `fullrun #<N>`). Otherwise resolve the checkout from `pnpm josh
   doctor`'s map; **no checkout there, or a tree that is not clean, stops the run** with a
-  `confirmation` Telegram — cloning decides the layout of someone's machine for them, and a dirty tree
-  holds work that is not yours to stash. Otherwise the commands that act on the target execute in that
-  checkout.
+  `confirmation` Telegram — never clone, never stash. Otherwise the commands that act on the target
+  execute in that checkout.
 - **A named epic is exempt from the whole bullet above**: `owner/repo#E` names where the *epic* lives,
   not where its children are implemented. Its state is read against that repository through `gh api`,
   so that repository needs no checkout. The checkout rules bind each child at implementation time,
   against **that child's** repository ("Concurrency" in `backlogrun.md`).
 - **Independent of `into <target>`**: this says which repository the run acts on, `into` says which
-  epic the artifact joins — `kickoff kit#new into joshuafolkken/kit#909` is one correct line.
+  epic the artifact joins — `kickoff kit#new into joshuafolkken/kit#<E>` is one correct line.

package/.claude/skills/workflow-commands/working-tree-hold.md

@@ -1,12 +1,10 @@
 # The working-tree hold — one run per tree
 
-**This file is the single source, so the entry read carries the trigger and the pointer, not the
-procedure** (joshuafolkken/kit#2189). `SKILL.md` → §2's table keeps the trigger, and
-`entry-sequence.md` routes here for the definition. It is read at its point of use — the moment
-a run is about to claim or release the tree.
+**The single source of the hold**, read at its point of use — the moment a run is about to claim or
+release the tree. History: `docs/maintainers/working-tree-hold-rationale.md` → "Where each rule came from".
 
 **Ask `pnpm josh run:hold` before anything else, and obey what it answers.** It is the first call of
-`fullrun` and `halfrun` alike — before the title is normalized, before `git switch main`, and **before
+`fullrun` and `halfrun` alike — before the title is normalized, before `pnpm josh ms`, and **before
 a `new` entry files its Issue**, because a run stopped after the filing has already left behind the
 artifact it should not have created.
 
@@ -24,15 +22,12 @@ pnpm josh run:release --force # a record left behind by a run that has ended
   **File nothing, create no branch, edit nothing.**
 - **`unknown` — nothing was established. Stop the same way.** It is not "the tree is free".
 
-**The unit is the working tree, and `epic-busy.ts` is not reused for it.** That read answers about a
-*repository* and implements `backlogrun`'s one-child-per-repository rule; what these entry points contend
-for is one branch, one index and one uncommitted diff, and a linked work tree has its own three.
-**`backlogrun`'s own guard is unchanged** — the two layers guard different resources.
+**The unit is the working tree** — one branch, one index and one uncommitted diff, and a linked work
+tree has its own three. **`backlogrun`'s per-repository guard (`epic-busy.ts`) is a separate layer and is
+unchanged.**
 
-**`kickoff` does not claim it, and that is an exemption rather than an omission.** `kickoff` touches
-none of branch, index or uncommitted diff: it reads the Issue, normalizes the title, posts the plan,
-notifies and stops, every one of those against GitHub. It is a fact about the command rather than a
-judgement made at the entry, and it changes nothing for `fullrun` or `halfrun`.
+**`kickoff` does not claim it** — it touches GitHub, never the branch, index or diff. Rationale for both:
+`docs/maintainers/working-tree-hold-rationale.md` → "Why the unit is the working tree".
 
 **Claim it in the checkout the run will edit.** The record is keyed to the work tree the command runs
 in, so a cross-repository `fullrun owner/repo#N` resolves that repository's checkout from `pnpm josh
@@ -70,14 +65,13 @@ the procedure.
 
 ## The halfrun resume
 
-**`fullrun #<N>` or `prrun #<N>` after a `halfrun` stop resumes it instead of claiming**
-(joshuafolkken/kit#2796, #3042). The
+**`fullrun #<N>` or `prrun #<N>` after a `halfrun` stop resumes it instead of claiming.** The
 stop is **recorded, never inferred**: the `halfrun` ends with `pnpm josh run:hold <N> --halfrun-stop`,
 which marks its own record (re-keying a `halfrun new`'s unnumbered one to the filed issue) — a
 `halfrun` still implementing or a `backlogrun` child leaves the same hold over the same dirty tree, and
 must not be adopted. On a marked hold for `#<N>` over a dirty tree, `run:entry` asks the session budget
 (`over` stops as usual), adopts the hold with the `fullrun` mark and prints `entry #<N> — resume:
-halfrun`. **Skip the title, the plan, the split assessment, `git switch main && git pull`,
+halfrun`. **Skip the title, the plan, the split assessment, `pnpm josh ms`,
 `latest:scope` and the implementation**: the diff in the tree is what the person verified. Re-read the
 issue (`pnpm josh issue:read <N>`), then run the gate **in full** from the refactor (`chain-rule.md` →
 "Run the review-to-merge chain") — a fix made during the manual check has had no gate — and ship as
@@ -85,7 +79,7 @@ any `fullrun` does.
 
 ## The prrun resume
 
-**`fullrun #<N>` after a `prrun` stop resumes it the same way** (joshuafolkken/kit#3023). The `prrun`
+**`fullrun #<N>` after a `prrun` stop resumes it the same way.** The `prrun`
 ends with `pnpm josh run:hold <N> --prrun-stop`, which writes the commit its pull request is on into its
 own record; only a record carrying that commit is adopted. `run:entry` asks the session budget, adopts
 the hold with the `fullrun` mark and prints one of three tokens — read, never inferred: