@joshuafolkken/kit 1.872.0

package/.claude/skills/workflow-commands/latest-gate.md

@@ -0,0 +1,85 @@
+# The dependency update — when `josh latest` runs
+
+`josh latest` updates corepack, every dependency, the published ranges and `pnpm audit`, in that
+order and over the network. Until joshuafolkken/kit#1215 every entry point put it at the head of
+every run and called it **mandatory, never skip** — so a standalone `fullrun` paid 60–120 seconds
+for it before touching the issue, and a batch that ran ten children paid it ten times unless the
+entry's own file happened to hoist it by hand. This file is that rule's **single source**; every
+entry point references it and none restates it.
+
+## Ask the command; do not decide
+
+```bash
+pnpm josh latest:scope   # → required | skip ; the reason on stderr
+```
+
+**`required` means run it. `skip` means the update is already current and this run does not.**
+
+**The input is when `josh latest` last finished in this checkout, and nothing else.** "The
+dependencies are probably still fresh" is a judgement made under time pressure, and time pressure
+resolves it toward `skip` exactly when a stale dependency is most likely to matter — the same reason
+`pnpm josh review:brief --level-only` took the review level out of an agent's hands.
+
+- **No record answers `required`.** A fresh checkout, a cleared temp directory, a run that fell over
+  halfway — every one of them lands there, and none of them is evidence that anything is current.
+- **The record is written by `josh latest` itself**, as the last step of its chain, so a chain that
+  failed leaves nothing behind and the next run updates again.
+- **The window is 12 hours**, moved in either direction by `JOSH_LATEST_MAX_AGE_HOURS`. A value that
+  is not a positive number falls back to the default rather than disabling the update.
+- **The record is per checkout.** An epic that spans repositories therefore updates each one on its
+  own schedule, which is what the old "once per session, not once per run" wording was reaching for.
+
+## What runs when the answer is `required`
+
+```bash
+git stash push -u -m "josh latest"    # only if the working tree has staged or modified files
+git switch main && git pull
+pnpm josh latest     # on `required` only
+pnpm josh stash:pop "josh latest"     # only if you stashed above — by message, never a positional pop
+```
+
+**The pop is by message, never a bare `git stash pop`.** The stash is a repository-wide stack every
+work tree shares, so a positional pop would take whichever lane last pushed rather than the one this
+step saved (joshuafolkken/kit#2050).
+
+Then **load the `dependency-update` skill and follow its procedure** — the overrides in **both**
+`pnpm-workspace.yaml` and `package.json`, and the one expected `devEngines` pnpm bump. That condition
+is unchanged and unconditional: it applies to every run in which `josh latest` actually ran, and
+never reports the pins intact without having been run.
+
+**On `skip`, one line of that block goes away and no more.** `pnpm josh latest` does not run, and
+the `dependency-update` skill is not read, because nothing rewrote a pin for it to check.
+
+**Two of those steps are not this gate's, and making either conditional breaks something.**
+`git switch main && git pull` runs per issue and per child either way: it is what brings the previous
+merge into the tree, and an issue that skips it starts implementing on a stale default branch. The
+stash before it is the branch switch's, not the update's — a dirty tree stops `git switch` whatever
+this command answered — so it is conditional on the **tree**, never on the answer.
+
+## The vulnerability net is not what moved
+
+`pnpm audit` runs inside `josh latest`, so a `skip` skips that reading too. **What still covers every
+merge is CI**: the `Security Audit` job runs on every pull request and is one of the required checks
+`pnpm josh followup` waits on, so nothing reaches the default branch without a fresh audit —
+whatever this gate answered locally. The local reading is a head start on a failure CI would catch
+anyway; it was never the only net.
+
+## Why an elapsed-time window rather than "once per batch"
+
+The batch entry points had already hoisted the update to the head of a batch, and that hoist is
+correct — but it says nothing about a standalone `fullrun`, which **is** the head of its own
+one-issue batch and therefore updated on every invocation. A session that runs six issues one at a
+time paid the full cost six times while a batch of the same six paid it once, for no difference
+anybody chose. An elapsed-time window is the one condition that reads the same at every entry point,
+so no entry needs a rule of its own — and the batch hoists survive it unchanged, because a batch's
+second child asks the same command and is told `skip`.
+
+**The lock file the update rewrites still lands with whichever issue ran it.** `josh latest` leaves
+`pnpm-lock.yaml` modified and that issue's `pnpm josh git -y` commits it, exactly as before. What the
+window removes is the other runs carrying the same bumps; it does not make that one diff clean.
+Should the issue then fail CI on a bump rather than on its own change, that is a dependency problem
+found once — fix it forward before parking the issue for it.
+
+This file is the single source of the rule. `fullrun.md`, `halfrun.md`, `backlogrun.md` and `backlogrun.md`
+each name `pnpm josh latest:scope` at the point their procedure reaches it and route here for
+everything else; `docs/josh-commands.md` documents the command itself.

package/.claude/skills/workflow-commands/needs-human-review.md

@@ -0,0 +1,64 @@
+# `needs-human-review` — the child that stops before its commit
+
+**This is the body of `SKILL.md` §2z, relocated here so the entry read carries the trigger and the
+pointer, not the procedure** (joshuafolkken/kit#2189). `SKILL.md` §2z is the resident stub;
+`fullrun.md`, `halfrun.md` and `backlogrun.md` route here for the definition. It is read at its point
+of use — the moment `pnpm josh issue:state <N>` answers `human_review: yes`.
+
+An issue carrying **`needs-human-review`** is degraded to a `halfrun`-shaped stop, whichever entry
+point reached it — `fullrun` or `backlogrun`. It is `auto-ok`'s opposite: that label widens
+unattended execution past an epic's edge, this one withholds its last step, and both may be applied
+**only by a person**. It exists because some work's quality is not something a test can judge — a
+**published artifact** whose unit tests say nothing about the writing, or **a choice that was a
+person's to make** such as picking one of several generated candidates.
+
+- **Implementation and the verification gate run normally** — refactor, `pnpm josh gate`,
+  `/code-review`, exactly as for any other child.
+- **Run `pnpm josh test:e2e` yourself before stopping.** With no pull request there is no CI E2E job,
+  and `pnpm josh followup` is never reached. This is `halfrun`'s situation exactly: you run it and read
+  what it prints. A printed skip is the answer for a project with no E2E suite; a skip nobody saw
+  printed is not.
+- **Nothing is committed, pushed, opened as a pull request or merged.** `pnpm josh bump`,
+  `pnpm josh git` and `pnpm josh followup` are never reached.
+- **The working tree is left uncommitted, and nothing is stashed.**
+- **Send a `confirmation` Telegram and stop the whole run.** The remaining children are not started —
+  inside a `backlogrun` this is the one thing that is *not* park-and-continue.
+- The Telegram body carries the **resume command**, in the same form `halfrun`'s own stop uses.
+- **Resuming is `halfrun`'s stop exactly**: a person looks at the working tree and, if it is right,
+  carries on from the commit themselves. The stop report carries that resume command too, not only the
+  Telegram.
+
+**Stopping is the specification, not a failure.** The label's job is to stop a batch walking past a
+decision that was a person's to make.
+
+**Read the answer from `pnpm josh issue:state <N>`, never by matching the label string yourself.** It
+prints a `human_review: yes` / `human_review: no` line beside the state and the labels, through the
+same case-insensitive comparison every other workflow label goes through — so `Needs-Human-Review` is
+not missed. **Ask once, before implementing**: `epic:next` prints a bare issue number and `fullrun`
+and a batch child are handed one, so the check is one call of its own, made the moment the number is in
+hand and before the plan.
+
+```bash
+pnpm josh issue:state <N>                      # state, labels, and human_review
+pnpm josh issue:state <N> --repo <owner/repo>  # a child in another repository
+```
+
+**Never apply or remove it**, exactly as strongly as `auto-ok`: a mark a run can clear for itself is
+not a mark. Everything but typing the command on an explicit instruction in the current turn is a
+proposal, written as an Issue comment and left for the person. The label itself is created once per
+repository, by a person:
+
+```bash
+gh api repos/{owner}/{repo}/labels -f name=needs-human-review -f color=d93f0b -f description="Implement and verify, but stop before committing so a person can look"
+```
+
+**It is not `needs-decision`, and reading it as one breaks two things.** `needs-decision` withholds a
+run's *start*; this withholds its *end*. So a `needs-human-review` issue is still offered — excluded,
+the artifact a person is meant to look at would never be produced — and a child stopped by it **goes on
+holding its repository**, because the uncommitted work is still in the checkout; read as parked there,
+the next child would start `git switch main && git pull` on top of it. The code encodes both halves by
+leaving the label out of two sets: `scripts/git/issue-labels.ts` keeps it out of
+`NOT_DIRECTLY_RUNNABLE_LABELS` and `scripts/epic/epic-busy.ts` keeps it out of the parked set.
+
+Each entry point's own branch stays in its own file — `fullrun.md`, `halfrun.md`,
+`backlogrun.md` — and routes here for the definition.

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

@@ -0,0 +1,349 @@
+# The observation filing procedure — `SKILL.md` §2i's body
+
+**This is `SKILL.md` → §2i's procedure, and it is read when an observation turns up — not at the
+entry** (joshuafolkken/kit#1797). §2i keeps the rule itself: file it without asking, apply the depth
+test, record what the test turns away, and carry the run on. Everything that decides *how* — the
+depth table and its labels, the depth-0 share, the ledger's grammar and commit path, the promotion on
+a second sighting, and what a delegated child does instead — is here, because none of it binds until
+a run has actually found something worth filing. A `fullrun` that never finds one never reads it, and
+the one that does reads it in full, in the same turn, before it files.
+
+**The trigger is the judgement, not the run's progress** — an ended run, a `kickoff` and a mid-talk
+turn all file; an offer to file is sent back by the `Stop` hook (joshuafolkken/kit#2422).
+
+**A run that judges something worth filing files it, and does not ask.** An upstream defect stops the
+run, a split replaces it, and a prerequisite goes in front of it (`SKILL.md` → §2d). An ordinary
+observation changes none of those: it carries no `route:` label, causes no stash or park, and the run
+continues. A first-party target is Tier A, decided by `pnpm josh repo:party`; a third-party target is
+Tier C (`CLAUDE.md`). Name what was filed in the completion report. An observation nobody would act
+on is dropped rather than filed.
+
+**The filing ceilings still apply.** Count this filing in the ten-Issue limit for the run. An
+observation is discretionary, so above 30 open Issues in the target repository, close one first or do
+not file (`prompts/collaboration-workflow/wip-cap.md`). Before the `gh api … issues` call, run
+`pnpm josh issue:scout "<title>"` (`issue-scout.md`). When it is the second filing of the run, run
+`pnpm josh issue:fold` first; the guard refuses that filing without the fold
+(`split-assessment.md` → "The same two questions decide the filing-time fold"). After filing, run
+`pnpm josh epic:bundle <new>` so the Issue is offered by its epic; an `auto-ok` epic adds it to the
+backlog pool (`backlogrun-steps.md` → "What one invocation approves").
+
+The detail below is read at the filing decision, and the marker suite pins the rules here.
+
+### 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 | The subject | Where it lives |
+| --- | --- | --- |
+| **0** | What a consumer of this package touches | A `josh` command's behavior, a distributed document or config, the published package |
+| **1** | The run orchestration that executes an Issue | `fullrun` / `backlogrun`, lanes, the `epic:*` commands, the filing routes themselves |
+| **2** | What measures a run | `josh cost` and the run-timing report |
+
+**The depth is recorded on the Issue as a label, and the label is applied when the Issue is filed**
+(joshuafolkken/kit#1729). `depth:0`, `depth:1` and `depth:2` are the three, defined once in
+`scripts/git/issue-labels.ts` and carrying no definition of their own — **the table above is the
+single source**, and a label description that paraphrased it would be a second copy of the rule.
+**Every filing route applies one**, this route and the other three of §2d's table alike: a `new`
+entry point, a `route:tier-a` prerequisite, a `route:interrupt`, a split child and a review round
+cap's branch-2 filing all pass through a `gh api … issues` call, and the depth label goes in it
+beside whatever `route:` label that call already carries.
+
+```bash
+gh api repos/{owner}/{repo}/issues -f title="<title>" -f 'labels[]=depth:1' -f body="<body>"
+gh api repos/{owner}/{repo}/issues/<N>/labels -f 'labels[]=depth:1'   # an Issue already filed
+```
+
+**Create the three once per repository**, before the first filing that applies one — REST auto-creates
+a missing label with a generated color and no description, and the three lines below are what give
+each a stable color a reader can scan a listing by. `DEPTH_LABELS` in `scripts/git/issue-labels.ts`
+is the single source of the colors and descriptions, and `scripts/rules/issue-depth-label.test.ts` keys
+these lines to it so the two cannot drift.
+
+```bash
+gh api repos/{owner}/{repo}/labels -f name=depth:0 -f color=0e8a16 -f description="Depth 0 — what a consumer of this package touches (SKILL.md §2i)" --silent 2>/dev/null || true
+gh api repos/{owner}/{repo}/labels -f name=depth:1 -f color=fbc02d -f description="Depth 1 — the run orchestration that executes an Issue (SKILL.md §2i)" --silent 2>/dev/null || true
+gh api repos/{owner}/{repo}/labels -f name=depth:2 -f color=c5def5 -f description="Depth 2 — what measures a run (SKILL.md §2i)" --silent 2>/dev/null || true
+```
+
+- **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.
+- **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.
+- **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.
+
+- **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".
+  **Cannot cite one, it is not filed**: it goes to the ledger below, and what files it later is
+  either the blockage arriving or a second sighting of the same thing. Pull rather than push — the
+  fix follows the jam or the repeat, never the lone sighting.
+- **A depth-0 observation does not take this test.** That is the product, and the two ceilings above
+  stay its only limits.
+- **`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:
+  - **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.
+  - **Which way it tips** — what range of the number selects which choice. A number that selects the
+    same action whatever it turns out to be changes no decision, and a filing that cannot write this
+    line is describing one.
+  - **Cannot write both, it is not filed** — the same exit the depth-0 gate takes: the ledger below,
+    pulled into an Issue by the jam arriving or the second sighting, never pushed by the lone idea.
+- **This narrows depth 2 alone, and the exemptions above carry over unchanged.** `route:tier-a` and
+  `route:interrupt` do not take this requirement any more than they take the depth-0 citation, a
+  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.
+
+**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).
+
+**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
+finding at all, so what it excludes is excluded for a reason a reader can check.
+
+**And a PR that *adds* a measurement names its reader in the same way.** The requirement above binds
+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.
+
+### 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 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.
+- **`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.
+- **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.
+
+**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
+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).
+
+- **The destination is `docs/observations.md` in the repository the observation is about** — the same
+  repository the Issue would have been filed into. **The count and the append are both run in that
+  repository's checkout**, resolved the way §2c (`target-repository.md`) resolves any cross-repository target, and the file 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
+  subject, never the working directory. **A third-party target gets no line either** — Tier C covers
+  the ledger exactly as it covers the Issue that would otherwise have been filed there.
+- **It is append-only.** A line is never edited and never deleted, because the count of lines
+  carrying one key is what says whether an observation has recurred; a second sighting is a second
+  line, not a rewrite of the first. **A merge conflict in it is resolved by keeping both sides** —
+  two lanes appending at once is the ordinary case, and a repeated key is the whole signal, so
+  dropping either side destroys exactly what the file is for.
+- **The completion report keeps its line too.** The ledger is what the next run can read; the report
+  is what this run's reader sees. Neither replaces the other.
+- **The append is not the end of it** — a line only becomes readable to anyone else once it has
+  merged, and "The commit path" below is how it gets there.
+
+**One observation is one line: five fields, each separated from the next by a vertical bar with one
+space on either side.**
+
+```
+- k:<slug> | d<n> | <YYYY-MM-DD> | <where> | <what>
+```
+
+| Field          | What it holds                                                                                                             |
+| -------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| `k:<slug>`     | The identity key — lowercase letters and digits, in words joined by `-`. This is what makes a repeat machine-readable      |
+| `d<n>`         | The depth of the subject — `d1`, `d2`, or whatever deeper depth the table above may one day name. **There is no `d0` line**: a depth-0 observation is filed outright and never reaches the ledger |
+| `<YYYY-MM-DD>` | The date of **this** sighting                                                                                             |
+| `<where>`      | One file path or one command — where the thing was seen                                                                   |
+| `<what>`       | The phenomenon, one sentence, carrying no vertical bar of its own                                                         |
+
+A sample, in the shape a real entry takes:
+
+```
+- k:example | d1 | 2026-09-10 | pnpm josh run:progress | The report printed a fill-in placeholder where a clock time belonged
+```
+
+**`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 file 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.
+
+**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. **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 file is not a count of zero, though** — there `grep` exits 2 and prints no
+number at all, so an empty answer means create the ledger, never that this is a first sighting.
+
+```bash
+grep -c '^- k:<slug> |' <that repository's checkout>/docs/observations.md || true
+```
+
+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.
+
+**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).
+
+### 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 ordinary run never commits the ledger, and that is enforced rather than remembered.**
+  `pnpm josh git` stages with `docs/observations.md` excluded, in the one staging step every entry
+  point goes through (`scripts/git/git-staging.ts`), so a `fullrun` in the primary checkout **cannot**
+  carry a ledger line into an Issue that has nothing to do with it. It is not a rule a run has to
+  remember at the commit — a run that had to would be the run that forgets.
+- **The parent flushes the ledger as a pull request of its own** — `pnpm josh observations:flush`. It
+  stages that one path and nothing else, commits it on a branch of its own, opens a docs-only pull
+  request, waits on the same required checks every other pull request waits on, merges it and returns
+  the checkout to the default branch. **Nothing is committed to the default branch directly**, which
+  is the constraint this route had to satisfy.
+- **`pnpm josh followup` runs the flush itself, so no run has to remember to** (joshuafolkken/kit#1810).
+  The flush is the ledger's only commit path, and until it was wired into `followup` nothing called
+  it — an appended line stayed in the working tree until a person ran the command by hand, the same
+  defect the staging exclusion above was built to avoid. After the merge and before it releases the working-tree
+  hold, `followup` reads the tree, and **only when the ledger holds a pending append** returns the
+  checkout to the default branch (`pnpm josh ms`) and flushes. A run that appended nothing pays
+  nothing, and a lane skips it (next bullet). A flush that fails is reported and does not take the merge, the
+  epic close or the hold release down with it. **A side effect: on a run that did flush, `followup`
+  ends on the default branch.**
+- **A lane's writers use the primary checkout's ledger** (joshuafolkken/kit#2419): a lane refuses
+  `pnpm josh ms`, so its own copy had no way out. `pnpm josh observations:flush` acts on the primary
+  checkout from a lane. **A dispatched lane child does not flush at all** (joshuafolkken/kit#2492): its
+  `run:tail` skips the step, and the `backlogrun` flushes every lane's lines once, in one pull request,
+  at `pnpm josh run:carry --end`.
+- **Mixing the lines into a child's pull request was considered and is refused.** That is the
+  contamination the exclusion above exists to end, and adopting it would turn the defect into the
+  specification: a ledger line in an unrelated diff is a line no reviewer of that diff has a reason
+  to question.
+- **Run by hand it goes in the primary checkout, once per cycle rather than once per observation** —
+  but with `pnpm josh followup` now flushing automatically (above), a hand run is the exception rather
+  than the rule. It refuses off the default branch and refuses a working tree holding anything besides
+  the ledger, so a run in progress cannot be flushed out from under, and a lane's checkout is never
+  the one it acts on.
+- **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 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:
+
+- **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.
+- **Both ceilings still apply**, exactly as they do above: 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.
+
+**A third and later sighting appends a line and files nothing more.** The Issue from the second one
+is already open, and `pnpm josh issue:scout` is what finds it; the extra lines are evidence for that
+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
+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
+ledger, format or threshold is added.
+
+### A delegated child does not take this route
+
+**A delegated child files `route:tier-a` and `route:interrupt` only.** Its discretionary
+observations are not filed by the child at all: they go back in the summary's "Observations that
+could bite later" line (`backlogrun-child.md` → "What the summary carries, and how long it may be"), and the
+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 —
+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.
+
+**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
+(joshuafolkken/kit#1649, joshuafolkken/kit#1797).