@joshuafolkken/kit 1.1035.0 → 1.1050.0

package/.claude/skills/verify-ui/SKILL.md

@@ -15,7 +15,7 @@ green while spacing, layout and styling are visibly broken. This skill is the lo
 In order:
 
 1. The routes given as arguments (`/verify-ui / /blog`).
-2. Otherwise, derive the candidates with `pnpm josh ui:routes` (alias `josh uir`): it reads the
+2. Otherwise, derive the candidates with `pnpm josh ui:routes`: it reads the
    change (the branch diff, or the staged diff with `--staged`) and lists the routes it touches,
    tracing a changed shared component to the routes that render it. From that list **pick the ones a
    reader would notice** — that narrowing is the judgement the command leaves to you.

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

@@ -92,8 +92,8 @@ procedure alone, and the rest of `backlogrun-park.md` is read only when it is re
 **A pointer written `` `X.md` → "Heading" `` is read as that section, never by opening `X.md` whole:**
 
 ```bash
-pnpm josh doc:section <file.md> "<heading>"   # the section, verbatim ; alias: josh ds
-pnpm josh read:set [<keyword>]                # what an entry reads, and what it costs ; alias: josh rs
+pnpm josh doc:section <file.md> "<heading>"   # the section, verbatim
+pnpm josh read:set [<keyword>]                # what an entry reads, and what it costs
 ```
 
 The section is fetched in the same turn, printed verbatim with its subsections; **a heading that does

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

@@ -2,7 +2,7 @@
 
 ## Background the gate and push
 
-- **The clean path folds the region into one backgrounded `pnpm josh ship`** (gate → `git -y` →
+- **The clean path folds the region into one backgrounded `pnpm josh ship`** (preflight → gate → `git -y` →
   foreground `followup` → `run:tail`; joshuafolkken/kit#2398). The calls below serve a due second round.
 - Background `pnpm josh gate` beside the review; join it before commit.
 - Issue `pnpm josh git -y` in the background; its completion resumes the run, so the turn never ends

package/.claude/skills/workflow-commands/backlogrun-child.md

@@ -164,7 +164,7 @@ unit was given** — this session's own unless the unit was handed a separate wo
 the recovery below is taken there too.
 
 ```bash
-pnpm josh run:liveness <N> --output <path> --process none    # alias: josh rv
+pnpm josh run:liveness <N> --output <path> --process none
 pnpm josh run:liveness <N> --output <path> --process alive
 pnpm josh run:liveness <N> --output <path> --process none --window 45 --repo <owner/repo>
 ```
@@ -290,7 +290,7 @@ separate command to ask first. Rationale: `docs/maintainers/backlogrun-child-rat
 preflight is part of the claim".
 
 ```bash
-answer=$(pnpm josh run:hold 926)   # alias: josh rh ; one token on stdout, prose on stderr
+answer=$(pnpm josh run:hold 926)   # one token on stdout, prose on stderr
 ```
 
 | Answer | What it found | What to do |

package/.claude/skills/workflow-commands/backlogrun-lanes.md

@@ -137,7 +137,7 @@ runs `lane:open`, then — only when `--stash` is given, which is the first lane
 into the lane and re-installs against the lock it brought in, then `lane:dispatch`:
 
 ```bash
-pid=$(pnpm josh lane:launch "$n") || exit 1   # the child's pid on stdout, nothing else; alias: josh lnla
+pid=$(pnpm josh lane:launch "$n") || exit 1   # the child's pid on stdout, nothing else
 pid=$(pnpm josh lane:launch "$n" --stash "backlogrun: josh latest before lanes") || exit 1   # the first lane only, and only if `josh latest` stashed
 ```
 

package/.claude/skills/workflow-commands/backlogrun-park.md

@@ -33,6 +33,12 @@ authorization, whether it came from a named epic or from the opted-in pool:
   is Tier A" carries the re-dispatch itself. A released child takes a lane exactly as any batch child
   does.
 
+## The parent does not investigate a lane failure itself
+
+**A lane failure whose reason is not on its Issue is read by a unit** — `pnpm josh delegate
+lane-failure-investigation` (joshuafolkken/kit#2947); the parent checks the cited lines and
+`pnpm josh issue:state` before it parks, re-dispatches or files.
+
 ## `needs-human-review` — the one stop that is not a park
 
 A child carrying **`needs-human-review`** is degraded to a `halfrun`-shaped stop and **the whole run ends

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

@@ -50,11 +50,11 @@ for a whole interval (that exit says so on standard error). **Nothing in flight
 parked, a stop — run `pnpm josh run:progress --mark` in the same turn to restart the silence clock. The clock is silence, never a timer
 (`docs/josh-commands.md` → "`josh run:progress`").
 
-**Do not keep a progress clock of your own** — the hook refuses the arm rather than asking.
-`scripts/rules/early-heartbeat.ts` → `decide` refuses a sleep-only `Bash` call on three tests — a timer it already allowed is still live, the
-report it would produce would land before the interval is up, or the wait runs longer than the interval
-— so **a single correctly-spaced arm is allowed**. It is still not the way to report; the step above
-prints without arming anything, and `--wait` is not a wait timer.
+**Do not keep a progress clock of your own** — the hook refuses the arm rather than asking
+(`scripts/rules/early-heartbeat.ts` → `decide`), though **a single correctly-spaced arm is allowed**. It
+is still not the way to report; the step above prints without arming anything, and `--wait` is not a
+wait timer. Rationale: `docs/maintainers/backlogrun-progress-rationale.md` → "Why the heartbeat reads
+as it does".
 
 **The default interval is twenty minutes, overridable — by the person, not the run.**
 `JOSH_PROGRESS_INTERVAL_MINUTES` moves both sides (the guard reads it through the watcher's reader);
@@ -65,14 +65,11 @@ moves the watcher alone** — it makes the watcher quieter than the floor, never
 **Every unscheduled progress statement is answered by `pnpm josh run:progress --once`** — presented in
 the same five field lines, the reply to an explicit ask and the note just after a run starts alike.
 **Never write a clock time the command did not print** (not an approximation, not a placeholder — where
-a field is missing, say so). **`--once` records the report**, so no `--mark` beside it. **A live timer
-is counted from the record the guard writes when it allows one**, never from the machine's `sleep`
-processes.
+a field is missing, say so). **`--once` records the report**, so no `--mark` beside it.
 
 **Every report opens with the time the observation was taken** — not only how long it has been quiet: an
-absolute instant, `at YYYY-MM-DD HH:MM±HH:MM / YYYY-MM-DDTHH:MMZ`. **The date is part of it**, and **the local clock
-leads with UTC beside it and the offset that ties them**. **It is added, never substituted for the
-elapsed figure**, and **the presented line needs no stamp computed for it** — the command prints the
+absolute instant, `at YYYY-MM-DD HH:MM±HH:MM / YYYY-MM-DDTHH:MMZ`. **It is added, never substituted for
+the elapsed figure**, and **the presented line needs no stamp computed for it** — the command prints the
 `at` stamp and the `next` field.
 
 **The line carries observations, never "still running", and nothing in it is a verification result** —
@@ -87,8 +84,8 @@ promoted to interrupt, never demoted to requested.**
 
 **The report surface belongs to the run, not to the session** (joshuafolkken/kit#2207). The run's
 session-facing events — a plan posted, a child launched, a PR opened, a review round, a park, a cut, a
-stop, a merge — are appended to one ordered stream keyed to the run's identity (`pnpm josh run:event`),
-which survives the cut because it is the run's and not any one session's. **Every session is a writer;
+stop, a merge — are appended to one ordered stream keyed to the run's identity (`pnpm josh run:event`).
+**Every session is a writer;
 the reader is a script in a pane of the person's own, never a conversation** (#2492):
 `pnpm josh run:event --watch` prints each event the moment it lands, in the session language, and the
 `heartbeat` events say the run is alive when quiet. **No session relays the stream** — name the watch command once, at the first cut or when
@@ -106,8 +103,7 @@ remaining child blocked behind a parked one, the backlog drained of anything run
 streak tripped — is pushed to the interrupt tier: `pnpm josh run:carry --end --stopped "<reason>"` sends one ⏸️ confirmation
 as it ends the record, and because the record is gone by the second `--end` the same stop never notifies
 twice. A parked child is pushed by the child itself, which records the park and sends its own
-`confirmation` before it stops (`backlogrun-park.md`). **Nothing new carries either one** — both ride the
-existing notification types and the record the watcher already keeps. Rationale for the tiers:
+`confirmation` before it stops (`backlogrun-park.md`). Rationale for the tiers:
 `docs/maintainers/backlogrun-progress-rationale.md` → "Why the signal tiers are split this way".
 
 **A heartbeat is emitted from the moment a run has started, even before any child carries
@@ -146,9 +142,8 @@ long.
 watcher's scope and placement: `docs/maintainers/backlogrun-progress-rationale.md` → "Why the watcher
 runs where it does".
 
-**A run that merges needs no teardown; a run that stops has to end the reporting itself.** The issue
-leaves the `in-progress` listing at the merge, so whatever is waiting prints nothing and `--hours` ends
-it. **A stop keeps that label on purpose** — so **no further `--wait` is started** after the stop
+**A run that merges needs no teardown; a run that stops has to end the reporting itself.** **A stop
+keeps the `in-progress` label on purpose** — so **no further `--wait` is started** after the stop
 notification, and any long-running watcher still in the background is stopped in the same turn. That
 covers `halfrun`'s stop before commit, a `needs-human-review` stop, a split or prerequisite stop, and
 a `backlogrun` named issue's failure stop.
@@ -167,9 +162,9 @@ answers=$(pnpm josh epic:next 858 909 --repo joshuafolkken/kit --lanes)
 # every named epic, merged into the same pool — "Several epics in one run" above
 ```
 
-**`--lanes` is the form to use.** A lane's branch is `<N>-lane`, which `pnpm josh git` commits from, so
-a child handed a lane runs the whole `fullrun` procedure inside it. Read a line per child, and treat a
-single non-numeric line as the verdict.
+**`--lanes` is the form to use.** Read a line per child, and treat a single non-numeric line as the
+verdict. Rationale: `docs/maintainers/backlogrun-progress-rationale.md` → "Why a named epic's children
+run in lanes".
 
 1. Run the command above.
 2. **One or more numbers** — where the child runs in this session's own checkout, its `fullrun` claim
@@ -317,8 +312,8 @@ the next turn of this session costs more than the threshold in billed input.
 
 **135,000 is shared by the scheduler entry, scheduler hand-off and lane worker implementation cut.**
 The value is `CONTEXT_CUT_THRESHOLD` in `scripts/cost-runtime/context-cut-threshold.ts`; `cost --cut`,
-`run:merge` and `run_cut.IMPLEMENTATION_CONTEXT_THRESHOLD` all read it rather than carrying separate
-numbers. The output ceiling and the entry-read figure are a separate 150,000, not this threshold.
+`run:merge`, `run_cut.IMPLEMENTATION_CONTEXT_THRESHOLD` and the parent hand-off guard all read it. The
+output ceiling and the entry-read figure are a separate 150,000, not this threshold.
 
 ### The check is asked at every merge, and delegation does not excuse it
 
@@ -333,7 +328,7 @@ answer, and take `over`'s branch at that child.
 
 ### When to ask, and what to do
 
-**Ask once per child, immediately after its merge and `pnpm josh ms`** — never mid-child.
+**Ask once per child, immediately after its merge and `pnpm josh ms`**; mid-child, a hook asks (#2947).
 
 ### A parent without a completion callback hands off at its first dispatch
 
@@ -443,10 +438,9 @@ survive the cut is re-dispatched, never adopted** — `pnpm josh lane:open <N>`
 progress comment is generated from it** (joshuafolkken/kit#2024) — children run, Issues filed,
 **consecutive failures**, and the time the run started. `pnpm josh run:merge` writes the merge into
 the record and mirrors the counters onto the epic comment at every child's merge. **The
-consecutive-failure count is the one that matters** — the stopped-unit section leans on it to notice
-the environment is at fault, and a merge resets it. **The record survives a session cut and a
-compaction alike.** Rationale: `docs/maintainers/backlogrun-progress-rationale.md` → "Why state lives
-in records, not the conversation".
+consecutive-failure count is the one that matters**, and a merge resets it. Rationale:
+`docs/maintainers/backlogrun-progress-rationale.md` → "Why state lives in records, not the
+conversation".
 
 ### What carries over, and where it lives
 
@@ -463,16 +457,18 @@ in records, not the conversation".
 
 ## Waiting, and never waiting forever
 
-| Setting | Value | Why |
+| Setting | Value | Meaning |
 | --- | --- | --- |
 | Polling interval | 60 s | **A floor between two asks, never a clock the parent sets.** It bounds a re-ask made while the parent is *already awake*; what wakes it is "The parent keeps no clock of its own" below. |
 | `backlogrun` idle-watch poll | 5 min | Not the interval above, and a floor in the same sense. |
 | Silent delegated unit | 30 min | Not the child's duration — the time its output has gone **unchanged**. Past it, run the traces above and book a stopped unit as a failure. |
-| Stale `in-progress` | 90 min | Longer than any single child has taken; past it, the other session is gone. |
+| Stale `in-progress` | 90 min | Past it, the other session is gone. |
 | Publish wait | 10 min | `josh propagate`'s own budget. A failed publish never appears. |
-| Whole run | 8 h | An unattended run that has not finished overnight needs a person, not more waiting. |
+| Whole run | 8 h | Past it, the run needs a person. |
 
-Each timeout **ends the wait and reports** — none is retried indefinitely. A stale child's label is
+Each timeout **ends the wait and reports** — none is retried indefinitely. Rationale for the figures:
+`docs/maintainers/backlogrun-progress-rationale.md` → "Why the parent waits on classification, not a
+clock". A stale child's label is
 removed first, so the next poll can offer it. **A graph that has deadlocked on a cycle is not this loop's
 to untangle**: `epic:next` detects it and exits with an error.
 
@@ -487,9 +483,7 @@ source and `run:report` the final report.
 `docs/maintainers/backlogrun-progress-rationale.md` → "Why the parent waits on classification, not a
 clock".
 
-The driver checks lane completion every five seconds and makes a new backlog offer no sooner than one
-minute after the previous offer, except after collecting a child — waits that cost no AI turns. The
-watcher reports on its own interval, and a judgment session may take its exit as a prompt to act.
+The watcher reports on its own interval, and a judgment session may take its exit as a prompt to act.
 
 #### The wake exists only while something is in flight
 
@@ -527,7 +521,7 @@ Per-child completion notifications are unchanged: `pnpm josh followup` sends one
 **start** notification when the run begins, and an epic **completion** summary at the end. **Do not
 compose that summary by hand — `pnpm josh run:report` generates it from this invocation's events**
 (joshuafolkken/kit#2249, scoped in #2393): it renders what merged, what parked and why, and what was cut,
-reusing `format_event`, closing with the release tail below. Its output is the Telegram body too — pass it to
+closing with the release tail below. Its output is the Telegram body too — pass it to
 `pnpm josh notify --body-file`.
 
 **That same session asks `pnpm josh release:scope` once, after the last child has merged** — in the

package/.claude/skills/workflow-commands/backlogrun-steps.md

@@ -131,7 +131,7 @@ single source.
 carried in a record rather than in the conversation:
 
 ```bash
-pnpm josh run:carry --begin "backlogrun --max 5 --idle 30" --owner "$PPID"   # alias: josh rc
+pnpm josh run:carry --begin "backlogrun --max 5 --idle 30" --owner "$PPID"
 pnpm josh run:carry --json                                                   # read it back in a resumed session
 ```
 
@@ -204,7 +204,7 @@ judgment starts an AI session, with the branch result and resume flags in its pr
 **Start it in the same turn as `--begin`, and stop it in the same turn as `--end`:**
 
 ```bash
-pnpm josh run:wake --start   # alias: josh rw ; right after `run:carry --begin`
+pnpm josh run:wake --start   # right after `run:carry --begin`
 pnpm josh run:wake --stop    # in the same turn as `run:carry --end`
 ```
 
@@ -267,7 +267,7 @@ run.
 **The plan is one command's output, not an assembly of several:**
 
 ```bash
-pnpm josh backlog:plan          # alias: josh blp
+pnpm josh backlog:plan
 ```
 
 **It renders the same classified pool `backlog:next` answers from**, so **the plan cannot promise an
@@ -282,9 +282,8 @@ order the run does not take**. Its four sections are:
   is distinguished from "not reached yet".
 
 **Report all four to the person, in the session language, before the first child starts.** Epic
-children are enumerated individually rather than summarized under their root. A `⚠` about a truncated
-listing is reported with them: the plan is then partial, and saying so is what keeps it from reading as
-complete.
+children are enumerated individually rather than summarized under their root. Report a truncated-listing
+`⚠` with them: the plan is then partial.
 
 ### Resolve what the plan can resolve, before starting
 
@@ -293,27 +292,28 @@ stop at a time.**
 
 - **Decide everything decidable from the issue itself.** Read the issue's body **and its comments**
   (`SKILL.md` → §2g), and where the answer is already there, record it as an Issue comment and
-  **remove the label** — `CLAUDE.md` → "Decision autonomy" already makes that Tier A. **Read every one
-  of them in one call** — `pnpm josh issue:read <N> <N> …`, the numbers the plan just listed under
-  "Waiting on a person" — rather than a `gh api` pair per issue.
+  **remove the label** — `CLAUDE.md` → "Decision autonomy" already makes that Tier A. **Read them all in
+  one `pnpm josh issue:read <N> <N> …` call**, not a `gh api` pair per issue.
 - **Never measure in order to decide.** A question needing a benchmark, a profile, or a run of the
   thing itself is not settled here: it stays labelled and the plan says so.
-- **Label what you find.** An issue that turns out to need a person's judgement has `needs-decision`
-  applied — the same label a parked child gets, applied the way `backlogrun-park.md` → "park and continue"
-  applies it. **The next plan then classifies it by reading the label alone**, never by reading the
-  body again.
+- **Label what you find.** An issue needing a person's judgement gets `needs-decision`, applied as
+  `backlogrun-park.md` → "park and continue" does. **The next plan classifies it by the label alone**,
+  never the body.
 - **Order and isolate the pool in the same pass** (joshuafolkken/kit#2776), from the same
   `issue:read`: an issue that must land first (it builds what another reuses, or both edit one code
   path) becomes a native `blocked-by`; an issue the `wip-cap.md` → 「実行のしかた」 enumeration hits
   gets `run:solo`, **every other one `run:lane`**. Comment the reason; the offer commands enforce all
   three, answering `triage` while an issue has neither.
+- **`priority:high` puts an issue first** (joshuafolkken/kit#2928; ranking: `docs/josh-commands.md` →
+  `josh backlog:next`). Apply it only on a cited ground — a stated deadline or urgency, or a person's
+  written policy — commenting the ground; **never remove it**.
 - **Report the order those labels produce — `pnpm josh backlog:plan --waves`** (joshuafolkken/kit#2778),
   `backlog:next` played forward wave by wave. Report it with the plan, never an order derived by hand.
 - **Then start the loop.** Whatever is still labelled is reported as parked and left standing; the
   run does not wait on it.
 
-**`needs-decision`, `run:solo` and `run:lane` are the workflow labels a run may apply, and none is
-`auto-ok` or `needs-human-review`.** Those two stay a person's alone (this file, `SKILL.md` → §2z); a
+**`needs-decision`, `run:solo`, `run:lane` and `priority:high` are the workflow labels a run may
+apply, and none is `auto-ok` or `needs-human-review`.** Those two stay a person's alone (this file, `SKILL.md` → §2z); a
 run parks with `needs-decision` and a person clears it.
 
 Rationale: `docs/maintainers/backlogrun-steps-rationale.md` → "Why the plan and the decision pass come first"
@@ -331,7 +331,7 @@ returns the verdict with the issues to start. It stays both halves' contract sou
 *means* changes here.
 
 ```bash
-offer=$(pnpm josh backlog:offer --started "$started" --active "$active")   # alias: josh blo
+offer=$(pnpm josh backlog:offer --started "$started" --active "$active")
 offer=$(pnpm josh backlog:offer --started "$started" --active "$active" --exclude 1630,1631)   # after #1630, #1631 merged
 ```
 

package/.claude/skills/workflow-commands/chain-rule.md

@@ -35,8 +35,8 @@ Review results and successful pushes are never turn boundaries.
    **`pnpm josh followup` refuses the merge until the round is recorded**
    (`pnpm josh review:record --check --issue <N>`, joshuafolkken/kit#2343).
 5. **The clean path ships in one call** — with no second round due, background
-   `pnpm josh ship "<title> #<N>" --body-file <evidence.md>`: gate → `git -y` → foreground `followup` → `run:tail`, stopping at the
-   first failure (joshuafolkken/kit#2398). `--review` runs both rounds (#2489). **Else a due round 2
+   `pnpm josh ship "<title> #<N>" --body-file <evidence.md>`: PR preflight (#2946) → gate → `git -y` →
+   `followup` → `run:tail`, stopping at the first failure (#2398). `--review` runs both rounds (#2489). **Else a due round 2
    does not fit `ship`**: the PR opens between the rounds — background `pnpm josh git -y "<title> #<N>"`, round 2 beside CI, then
    `pnpm josh followup`.
 

package/.claude/skills/workflow-commands/followup-reference.md

@@ -84,7 +84,7 @@ pnpm josh notify --task-type failure --issue-url "<issue-url>" --body "<the reas
 **The matching itself is unchanged, and so is the reason it is mechanical.** The instruction the mechanical read replaced was skipped in two runs out of three on the day it was measured, and one of those two could not have succeeded by eye at all: `AI_COPY_DIRECTORIES` holds directories, so a distributed path such as `.claude/skills/workflow-commands/backlogrun.md` appears in no list textually.
 
 ```bash
-pnpm josh sync:scope    # managed | clean, naming which list claimed each path; alias: josh sys
+pnpm josh sync:scope    # managed | clean, naming which list claimed each path
 ```
 
 - **There is no flag to pass and nothing to approve.** `--managed-config-ignore-reason` is gone with the stop it existed to get past.
@@ -99,7 +99,7 @@ pnpm josh sync:scope    # managed | clean, naming which list claimed each path;
 **The answer: `pnpm josh release:scope`.**
 
 ```bash
-pnpm josh release:scope          # → required | skip | unknown ; alias: josh res
+pnpm josh release:scope          # → required | skip | unknown
 pnpm josh release:scope --json   # the same answer as one JSON object
 ```
 

package/.claude/skills/workflow-commands/issue-comments.md

@@ -12,7 +12,7 @@ delegated unit executing `fullrun`'s procedure, and the hook keys its once-per-r
 same turn as whatever else the run already needs:
 
 ```bash
-pnpm josh issue:read <N> [<N> ...]     # body and comments, one call per batch; alias: josh ird
+pnpm josh issue:read <N> [<N> ...]     # body and comments, one call per batch
 gh api repos/{owner}/{repo}/issues/<N>/comments --jq '.[] | {user: .user.login, created_at, body}'
 ```
 

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

@@ -32,13 +32,7 @@ The detail below is read at the filing decision, and the marker suite pins the r
 
 ### The depth test — a discretionary filing cites the product work it blocked
 
-**A run that has just spent an hour inside the workflow tooling files findings about the workflow
-tooling** (joshuafolkken/kit#1698). Measured on the `backlogrun` of 2026-09-09: 5 Issues shipped and
-15 filed, of which 13 were discretionary — and all 20 were about this package's own run
-orchestration or the tools that measure it, with not one change a consumer of the package would see.
-**A listing that measures itself has no natural stopping condition**, because every measurement
-creates something new to measure. So the condition comes from outside, and **depth is what supplies
-it — read off the subject rather than judged**:
+**Depth is read off the subject rather than judged** (joshuafolkken/kit#1698):
 
 | Depth | The subject | Where it lives |
 | --- | --- | --- |
@@ -75,16 +69,14 @@ gh api repos/{owner}/{repo}/labels -f name=depth:2 -f color=c5def5 -f descriptio
 - **It is read off the subject, exactly as the table is** — so applying it is not a judgement and not
   a person's to make, which is what separates it from `auto-ok` and `needs-human-review`. Those two
   decide what a run may do; this one records what an Issue is about and withholds nothing.
-- **Applied at filing, not at completion.** A depth assigned when the work finishes is assigned by
-  whoever happens to close it, and the share below is a question about the *open* backlog — an Issue
-  that never carried the label was never in the numerator's reach.
+- **Applied at filing, not at completion.**
 - **An Issue carrying more than one counts as the lowest depth present**, the one closest to the
-  consumer. It is a fixed tie-break rather than a preference: without one the same backlog measured
-  twice can answer twice, which is the whole defect joshuafolkken/kit#1729 was filed for.
+  consumer.
 - **An `epic` takes no depth label**, because it has no subject of its own to read one off — its
   children carry the subjects, and the share below excludes it from the denominator for that same
-  reason. A depth label present on an Issue the count skips is exactly the ambiguity this section
-  exists to remove.
+  reason.
+
+Rationale: `docs/maintainers/observation-filing-rationale.md` → "Why the depth label is applied at filing".
 
 - **A discretionary observation at depth 1 or deeper is filed only where it can cite the depth-0 work
   it stopped or delayed** — named as an Issue number or a run, never as "this would slow runs down".
@@ -96,12 +88,8 @@ gh api repos/{owner}/{repo}/labels -f name=depth:2 -f color=c5def5 -f descriptio
 - **`route:tier-a` and `route:interrupt` do not take it either**, at any depth: a filing the run
   cannot proceed without is already citing its own blockage.
 - **A depth-2 filing — one whose subject is what measures a run — carries a further requirement, on
-  top of the depth-0 citation above rather than in place of it** (joshuafolkken/kit#1975). The
-  citation the depth-0 gate asks for is one a slow run can always produce, so it barely bites on a
-  measurement Issue: "runs are slow" and "the diff is large" both name depth-0 work, while the number
-  the Issue proposes to produce changes nothing — and a listing that measures itself has no natural
-  stopping condition precisely there. So a discretionary depth-2 filing states two things the depth-0
-  citation does not force:
+  top of the depth-0 citation above rather than in place of it** (joshuafolkken/kit#1975). A
+  discretionary depth-2 filing states two things the depth-0 citation does not force:
   - **The decision the number would change, named** — the Issue number holding the choice it is
     waiting on, or a decision a person is about to make. "Slow", "large" and "worth knowing" are not a
     decision.
@@ -115,15 +103,15 @@ gh api repos/{owner}/{repo}/labels -f name=depth:2 -f color=c5def5 -f descriptio
   depth-0 observation does not take it because it is the product, and a review round cap's branch-2
   filing (below) clears its own bar and never reaches this one.
 
+Rationale: `docs/maintainers/observation-filing-rationale.md` → "Why depth gates a discretionary filing".
+
 **It governs this route only — the fourth row of §2d's table.** A review finding routed to branch 2
 of `prompts/review.md` → "Review round cap" is filed under that section's own bar — a confirmed
 defect reaching a runtime path, with a written failure scenario — and **does not take the depth
 test**: it has already cleared a bar this route has not, so gating it on a citation as well would
 drop the one kind of finding both documents agree is never dropped. **That bar is the reason, and the
-subject's depth is not** — the sentence here used to say that a defect in a `josh` command's behavior
-is depth 0 by construction, and joshuafolkken/kit#1694 and joshuafolkken/kit#1703 are both branch-2
-filings whose subject is the epic tooling, which the table above puts at depth 1
-(joshuafolkken/kit#1675).
+subject's depth is not.** Rationale: `docs/maintainers/observation-filing-rationale.md` → "Why a
+review branch-2 filing skips the depth test".
 
 **This is not the count cap that was rejected.** A cap is rationing — past the number the finding is
 lost, and nothing about it says which findings were worth having. This changes what counts as a
@@ -133,34 +121,26 @@ finding at all, so what it excludes is excluded for a reason a reader can check.
 a depth-2 Issue that *proposes* a measurement; a pull request that *adds* one — a new report column,
 section, scope or subcommand, a diagnostic step — states in its body the reader that consumes it: the
 Issue number that read the value to decide something, or the path of the rule that reads it. **A
-measurement with no reader is not added** — this is joshuafolkken/kit#2012's test, the one that
-retired every column no decision reads, moved to the moment a column is proposed so the retirement
-never has to be filed again. `route:tier-a` and `route:interrupt` carry over unchanged.
+measurement with no reader is not added** (joshuafolkken/kit#2012). `route:tier-a` and
+`route:interrupt` carry over unchanged.
 
 ### The depth-0 share — what is counted
 
-**joshuafolkken/kit#1698 set a measurable target: the share of open Issues at depth 0** — 3/23
-≈ 13% on 2026-09-09 (joshuafolkken/kit#1729). Counted by eye it is not reproducible: done again on
-2026-09-10 it produced 3/14 ≈ 21%, and the two figures **are not comparable**: they took different
-denominators, and neither said which. So the denominator is fixed here as a rule rather than left to
-the counter.
+**The depth-0 share is the share of open Issues at depth 0** (joshuafolkken/kit#1698,
+joshuafolkken/kit#1729).
 
 **The denominator is a rule, not a choice, and this is it:**
 
-- **Counted: every open Issue that does not carry `epic`.** An epic is a container for other Issues
-  rather than a deliverable of its own — counting one counts its children twice, and an epic has no
-  subject of its own to read a depth off.
+- **Counted: every open Issue that does not carry `epic`.**
 - **`route:tier-a` and `route:interrupt` are counted like anything else.** The depth test above
-  exempts them from its *citation* requirement; it never said they are not work. Excluded, a run
-  could improve the share by choosing a filing route.
-- **An Issue with no depth label is in the denominator**, counted separately as `unlabelled`. Left
-  out, the share would improve every time a filing skipped the label — the one direction a
-  measurement must never be able to move on its own.
+  exempts them from its *citation* requirement; it never said they are not work.
+- **An Issue with no depth label is in the denominator**, counted separately as `unlabelled`.
 - **The numerator is what is left**: open, non-epic Issues carrying `depth:0`.
 
-**Two readings of the same backlog give the same number**, which is what the hand counts could not
-do: the denominator is a rule rather than a choice, so nothing in the count is left to the counter's
-judgement.
+**Two readings of the same backlog give the same number**: nothing in the count is left to the
+counter's judgement.
+
+Rationale: `docs/maintainers/observation-filing-rationale.md` → "Why the depth-0 denominator is fixed".
 
 **What the number is for is not decided here.** Changing what `backlog:next` offers on the strength
 of it, and setting a target value, are both deliberately out of scope until the current value has
@@ -168,12 +148,9 @@ been measured the same way more than once (joshuafolkken/kit#1729 → 範囲外)
 
 ### The ledger — where an observation that cannot cite a blockage goes
 
-**"Not filed" used to mean "gone", and that is what walked the depth test past itself.** The
-completion report was the only place such an observation could land, and a completion report is
-read once and then scrolls away — so the next run met the same thing as a first sighting, forever.
-joshuafolkken/kit#1726 is the worked case: its own body says the depth test would not have filed it,
-and it was filed anyway, because **discarding it was the only alternative on offer**
-(joshuafolkken/kit#1728).
+**An observation the depth test turns away is recorded in the ledger, not discarded**
+(joshuafolkken/kit#1728). Rationale: `docs/maintainers/observation-filing-rationale.md` → "Why the
+ledger exists".
 
 - **The destination is the `docs/maintainers/observations/` directory in the repository the
   observation is about** — the same repository the Issue would have been filed into — **one file per
@@ -221,9 +198,8 @@ A sample, in the shape a real entry takes:
 
 **`k:example` is reserved for this sample and is never used by a real observation**, so the count
 below can be run over the whole ledger without the sample answering for one. **The grammar is defined
-here rather than in the ledger** because this skill is distributed to every repository that consumes
-the package and `docs/` is not — a rule that named a definition the reader never received would
-leave every consumer's ledger shaped by hand.
+here rather than in the ledger** (`docs/maintainers/observation-filing-rationale.md` → "Why the
+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
@@ -244,27 +220,17 @@ rather than by editing the one already written.
 
 **The depth gate is not withdrawn, and this is not a way around it.** An observation that *can* cite
 the depth-0 work it stopped is filed exactly as it was before — this route is only for the ones that
-could not, and whose sole previous destination was nothing (joshuafolkken/kit#1698's gate stands
-unchanged).
+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). The ledger was
-given a destination and no route out of the working tree the line was written in, and **structurally
-nobody was going to commit one**: the parent session that appends never runs `pnpm josh git`, a child
-runs it inside a lane work tree that cannot see the parent's checkout, and in the primary checkout
-`git add -u` swept the line into whatever unrelated pull request that run was opening. Measured on
-the day the ledger shipped, `docs/observations.md` had exactly one commit — the one that created
-it — and seven lines had never left a working tree. **So the repeat count below was reading a file
-that is empty on every other machine**, and every sighting was a first one, which is the state
-joshuafolkken/kit#1728 created the ledger to end.
+**An append nobody commits is an append nobody can count** (joshuafolkken/kit#1756). Rationale:
+`docs/maintainers/observation-filing-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
   `docs/maintainers/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. Until
-  #2763 the ledger was excluded there (joshuafolkken/kit#1756) and every run that appended a line
-  paid a second branch, CI wait and merge after its own — 144 ledger-only pull requests in one month.
+  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.
@@ -280,10 +246,7 @@ joshuafolkken/kit#1728 created the ledger to end.
   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
   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. Lanes once wrote to the primary checkout's single file
-  instead (joshuafolkken/kit#2419) and a `backlogrun` flushed them all at `run:carry --end`
-  (joshuafolkken/kit#2492); another run's stash of that checkout took the lines before the flush saw
-  them, so neither route remains. **Nothing is held in the primary checkout for later.**
+  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
   date-named file a retrospective or a hand append on the default branch writes. It stages the ledger
   and nothing else, commits it on a branch of its own, opens a docs-only pull request, waits on the
@@ -300,10 +263,9 @@ joshuafolkken/kit#1728 created the ledger to end.
 
 ### The second sighting is what files it
 
-**A repeat is the citation.** joshuafolkken/kit#1698 asked a discretionary filing to be pulled by a
-blockage rather than pushed by a sighting; an observation recorded twice has been pulled — it came
-back on its own, which no single sighting can demonstrate. So the gate has a second way through, and
-it is counted rather than judged:
+**A repeat is the citation**, so the gate has a second way through, and it is counted rather than
+judged (rationale: `docs/maintainers/observation-filing-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
@@ -336,19 +298,12 @@ could bite later" line (`backlogrun-child.md` → "What the summary carries, and
 parent files what survives — under the depth test above, and inside the run's ceiling.
 
 **A delegated child does not append to the ledger either — the parent collapses the duplicates and
-appends what is left.** The ledger's whole value is that one key means one phenomenon, and a child
-holding one Issue's worth of context cannot tell its observation from the sibling lane's: eight
-children appending in parallel would write the same thing under eight keys, and every one of them
-would then read as a first sighting. The child's route is unchanged and is the only one it has —
+appends what is left.** The child's route is unchanged and is the only one it has —
 the summary's "Observations that could bite later" line — and the parent chooses the key, checks the
-count and writes the line.
-
-**Two reasons, and a child can solve neither for itself.** It holds one Issue's worth of context, so
-**it cannot tell its observation from the one a sibling filed twenty minutes earlier** — the 15
-filings of 2026-09-09 were collapsed to 12 within that same day, which means they were collapsible
-at the moment they were made. And **the 10-per-run ceiling for this route is the parent's to
-count**: six children counting two or three filings each never reach it, which is why it did not
-fire once on the run that filed fifteen.
+count and writes the line. **The 10-per-run ceiling for this route is the parent's to count.**
+
+Rationale: `docs/maintainers/observation-filing-rationale.md` → "Why a delegated child neither files
+nor appends".
 
 **This file is the single source of every procedure above**, and `SKILL.md` → §2i is the single
 source of the rule they carry out; nothing under `prompts/collaboration-workflow/` restates either