@joshuafolkken/kit 1.1136.0 → 1.1166.0

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

@@ -1,4 +1,4 @@
-# Filing an Issue — `SKILL.md` §2e's procedure
+# Filing an Issue — the procedure
 
 Read this file when an Issue title exists and before the `pnpm josh issue:file` call that files it.
 Every filing asks whether the work already exists and which epic owns it; the command runs the
@@ -25,19 +25,19 @@ pnpm josh issue:file "<title>" --body-file <complete-draft.md> --depth <n> --dis
   line, named in `--distinct`, and the filing carries on.
 - **`none` is an answer.** The command reports no candidate rather than the closest miss.
 - **`Epic:` front-loads the placement.** Its recommendation is `epic:bundle`'s, which makes
-  `add_to_epic` / `create_epic` Tier A and `ask` a stop, in exactly the reading `SKILL.md` → §2a's
+  `add_to_epic` / `create_epic` Tier A and `ask` a stop, in exactly the reading `into-target.md`'s
   `into <target>` suffix would have given by hand. Where the user typed `into <target>`, that naming wins.
 - **`Epic: not asked` is not `Epic: none`.** The epic half decides from the issue numbers the body
   names. **Cite `#N` in the body whenever the work follows an existing Issue** — one line is enough,
   and naming the epic itself (`part of epic #<E>`) is answered with that epic.
 - **`epic:bundle` then runs on the new Issue, in the same call.** Act on its printed answer; a `⚠`
-  means rerun `pnpm josh epic:bundle <N>` — the Issue exists, so never refile.
-- **Every filing route goes through it** — §2d's prerequisite, §2i's observation and the review round
+  means rerun `pnpm josh epic:bundle <N>` — the Issue exists, so never refile; a placing answer
+  reads the `epic-commands` skill.
+- **Every filing route goes through it** — `prerequisite.md`'s prerequisite, `observation-filing.md`'s observation and the review round
   cap's branch-2 filing alike; the guard refuses any other filing call
   (`prompts/collaboration-workflow/rule-delivery.md`).
 - **A `#N` entry point does not file *the Issue it was handed*.** `fullrun #N` / `halfrun #N` /
-  `kickoff #N` are given an Issue that already exists. That says nothing about an Issue such a run goes
-  on to file later, which the bullet above covers.
+  `kickoff #N` are given an Issue that already exists; one such a run files later still goes through it.
 - **The split path files each child through the same command.** The epic is created with
   `pnpm josh epic` over children that were scanned.
 

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

@@ -1,10 +1,10 @@
 # `kickoff` — Planning phase only (plan → Issue → Telegram notify → stop)
 
-- `kickoff #<N>`: **First `pnpm josh run:entry <N> --to kickoff`** (`SKILL.md` → §2k) — it claims
+- `kickoff #<N>`: **First `pnpm josh run:entry <N> --to kickoff`** (`docs/how-to/run-issues.md`) — it claims
   nothing and prints the stage line alone; `start: reached` means the Issue is already planned or further
   up the ladder, so report the stage line and **stop**. Otherwise read existing Issue #N **and every comment on it** — `pnpm josh issue:read <N>`; a
   decision recorded after the body was written lives only in a comment, and the later text is the
-  agreement in force (`SKILL.md` → §2g, which also carries the two answers that stop the run instead) →
+  agreement in force (`issue-comments.md`, which also carries the two answers that stop the run instead) →
   **normalize the title**: if the title is not in English or can be phrased more clearly, derive a
   better English title and run `gh api -X PATCH repos/{owner}/{repo}/issues/<N> -f title="<title>"` →
   analyze requirements → **scope assessment per `split-assessment.md`** → post the plan to the Issue (if
@@ -28,11 +28,11 @@
 is one branch, one index and one uncommitted diff; this command reads the Issue, normalizes the title,
 posts the plan, notifies and stops — every one of those against GitHub, none against the tree. So a
 `fullrun` running in this checkout never stops a `kickoff`, and a `kickoff` never touches the record
-that run is holding. It claims nothing, so it must not release anything either. `SKILL.md` → §2f is the
+that run is holding. It claims nothing, so it must not release anything either. `working-tree-hold.md` is the
 single source.
 
 **The target repository is named in front of the Issue reference** — `kickoff kit#new`,
-`kickoff joshuafolkken/kit#412`. The definition is `SKILL.md` → §2c, whose body is `target-repository.md`. `kickoff` is the entry that needs
+`kickoff joshuafolkken/kit#412`. The definition is `target-repository.md`, whose body is `target-repository.md`. `kickoff` is the entry that needs
 no checkout: name the target repository in the path of every `gh api` call — reads included — and never
 clone. The one exception is the split path's epic, since `pnpm josh epic` writes only the repository it
 runs in — and the promote arm has no remote fallback at all, so it stops when that repository is not
@@ -52,11 +52,11 @@ split is found.
   title. (2) Create Issue: `pnpm josh issue:file "<title>" --body-file <body-file> --depth <n>` (body
   per `prompts/collaboration-workflow/issue-template.md`) — its duplicate scan runs first, and a
   candidate that covers the same work stops the run rather than filing a second Issue (`SKILL.md` →
-  §2e). Capture `<N>`. (3)
+  `issue-scout.md`). Capture `<N>`. (3)
   Post the plan in the session language, using the same body/comment logic as `kickoff #<N>`. (4) Send
   Telegram notification. (5) **Stop** — do not implement. **Multi-issue split path**: (1) For each
   independent deliverable, derive a focused English title and create a separate Issue with the
-  `route:split` label (its duplicate scan is read per `SKILL.md` → §2e): `pnpm josh issue:file
+  `route:split` label (its duplicate scan is read per `issue-scout.md`): `pnpm josh issue:file
   "<sub-title>" --body-file <body-file> --depth <n> --route split`. Capture each Issue number. **When the split is filed into a repository other than
   the one this session is running in**, every child body gets the `## Origin` backlink described in the
   cross-package rule the AI documents keep resident, the epic body carries the same link as prose or a

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

@@ -1,14 +1,14 @@
 # `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
+**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;
+`entry-sequence.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
+unattended execution past an epic's edge, this one withholds its last step, and this one 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.
 
@@ -43,7 +43,7 @@ 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
+**Never apply or remove it**: 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:

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

@@ -1,18 +1,17 @@
-# The observation filing procedure — `SKILL.md` §2i's body
+# The observation filing procedure
 
-**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.
+**Read when an observation turns up — not at the entry** (joshuafolkken/kit#1797). `SKILL.md` → §2's
+table keeps the rule itself: file it without asking, apply the depth test, record what the test turns
+away, and carry the run on. This file is the depth table, the `issue:file` flags and what a delegated
+child does instead. **An observation the depth test turns away, and the kind of miss behind a
+user-reported bug, are recorded by `observation-ledger.md` — read it only then**, in the turn that
+appends (joshuafolkken/kit#3176).
 
 **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
+run, a split replaces it, and a prerequisite goes in front of it (`prerequisite.md`). 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
@@ -28,7 +27,7 @@ new Issue so it is offered by its epic; an `auto-ok` epic adds it to the backlog
 `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").
 
-The detail below is read at the filing decision, and the marker suite pins the rules here.
+The marker suite pins the rules below.
 
 ### The depth test — a discretionary filing cites the product work it blocked
 
@@ -44,7 +43,7 @@ The detail below is read at the filing decision, and the marker suite pins the r
 (joshuafolkken/kit#1729). `depth:0`, `depth:1` and `depth:2` are the three, defined once in
 `scripts/issue/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`
+**Every filing route applies one**, this route and the other three of `prerequisite.md`'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 `pnpm josh issue:file` call, and the depth goes in it as
 `--depth <n>` beside whatever `--route` that call already carries.
@@ -54,21 +53,15 @@ pnpm josh issue:file "<title>" --body-file <body-file> --depth 1
 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/issue/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
-```
+**A repository missing the three gets them from `issue:file` itself** — it creates any missing
+workflow label, with the color and description `DEPTH_LABELS` in `scripts/issue/issue-labels.ts`
+defines, before the create call (joshuafolkken/kit#3176).
 
 - **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.
+  decide what a run may do (`auto-ok` by `issue:file`'s default for a filing found by opted-in work —
+  `backlogrun-steps.md` → "What one invocation approves"); this one records what an Issue is about
+  and withholds nothing.
 - **Applied at filing, not at completion.**
 - **An Issue carrying more than one counts as the lowest depth present**, the one closest to the
   consumer.
@@ -80,7 +73,7 @@ Rationale: `docs/maintainers/observation-filing-rationale.md` → "Why the depth
 
 - **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
+  **Cannot cite one, it is not filed**: it goes to the ledger (`observation-ledger.md`), 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
@@ -96,7 +89,7 @@ Rationale: `docs/maintainers/observation-filing-rationale.md` → "Why the depth
   - **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,
+  - **Cannot write both, it is not filed** — the same exit the depth-0 gate takes: the ledger,
     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
@@ -105,7 +98,7 @@ Rationale: `docs/maintainers/observation-filing-rationale.md` → "Why the depth
 
 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
+**It governs this route only — the fourth row of `prerequisite.md`'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
@@ -146,150 +139,6 @@ Rationale: `docs/maintainers/observation-filing-rationale.md` → "Why the depth
 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
-
-**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
-  issue** (joshuafolkken/kit#2919): 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 §2c (`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
-  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** —
-  one file per issue should keep it from arising, but a repeated key is the whole signal, so
-  dropping either side destroys exactly what the ledger 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 ledger without the sample answering for one. **The grammar is defined
-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
-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.
-
-```bash
-cat <that repository's checkout>/docs/maintainers/observations/*.md | grep -c '^- k:<slug> |' || 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.
-
-### 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:
-`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.
-  **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
-  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
-  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
-  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
-  same required checks every other pull request waits on, merges it and returns the checkout to the
-  default branch; a single run's `run:tail` runs it after the merge. 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. **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 second sighting is what files it
-
-**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
-  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
@@ -305,6 +154,6 @@ count and writes the line. **The 10-per-run ceiling for this route is the parent
 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
+**This file is the single source of every procedure above**, and `SKILL.md` → §2's table carries the
+trigger of the rule they carry out; nothing under `prompts/collaboration-workflow/` restates either
 (joshuafolkken/kit#1649, joshuafolkken/kit#1797).

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

@@ -0,0 +1,150 @@
+# 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).
+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.
+
+## 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
+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
+  issue** (joshuafolkken/kit#2919): 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
+  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
+  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** —
+  one file per issue should keep it from arising, but a repeated key is the whole signal, so
+  dropping either side destroys exactly what the ledger 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 `observation-filing.md`'s depth table 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 ledger without the sample answering for one. **The grammar is defined
+here rather than in the ledger** (`docs/maintainers/observation-ledger-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
+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.
+
+```bash
+cat <that repository's checkout>/docs/maintainers/observations/*.md | grep -c '^- k:<slug> |' || 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.
+
+## 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:
+`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
+  `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.
+  **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
+  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
+  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
+  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
+  same required checks every other pull request waits on, merges it and returns the checkout to the
+  default branch; a single run's `run:tail` runs it after the merge. 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. **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 second sighting is what files it
+
+**A repeat is the citation**, so the gate has a second way through, and it is counted rather than
+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.
+- **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.
+
+**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.