@joshuafolkken/kit 1.1455.0 → 1.1514.0

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

@@ -1,44 +1,34 @@
 # The observation filing procedure
 
-**Read when an observation turns up — not at the entry.** `SKILL.md` → §2's
-table points here for the rule itself: who is asked before a filing, the depth test, what the test
-turns away, and carrying the run on. This file is that rule, 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.
-
-**An unattended run files without asking; an interactive session asks first.** Unattended is a session kit launched under `claude -p` (a lane child, a woken session), a dispatched
-lane child, or the `backlogrun` parent — nobody is there to answer, so an offer to file is sent back
-by the `Stop` hook. In an interactive session, propose the Issue and file it
-once the user confirms; the hook lets the offer through. A current-turn instruction to file, and a
-typed command whose own procedure files (a split, a prerequisite, an upstream interrupt), are that
-confirmation already.
+**Read when an observation turns up — not at the entry.** `SKILL.md` → §2's table points here. **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.
+
+**An unattended run files without asking; an interactive session asks first.** Unattended means a
+`claude -p` session (a lane child, a woken session), a dispatched lane child, or the `backlogrun`
+parent; the `Stop` hook sends an offer to file back. Interactively, propose the Issue and file it
+once the user confirms. A current-turn instruction to file, or a typed command whose procedure files (a
+split, a prerequisite, an upstream interrupt), is that confirmation already.
 
 **The trigger is the judgement, not the run's progress** — an ended run, a `kickoff` and a mid-talk
 turn all file or propose.
 
-**An unattended 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 (`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
-on is dropped rather than filed.
+**An unattended run that judges something worth filing files it, and does not ask.** An ordinary
+observation carries no `route:` label, causes no stash or park, and the run continues (unlike an
+upstream defect, a split or a prerequisite — `prerequisite.md`). First-party target: Tier A, by
+`pnpm josh repo:party`; third-party: Tier C (`CLAUDE.md`). Name what was filed in the completion
+report. Drop an observation nobody would act on.
 
 **Below the filing bar, a line that could still change a person's judgement is a board note**:
 `pnpm josh run:event --append note "#<N> <text>"`, shown by `pnpm josh run:board`
 (`docs/josh-commands-run.md` → "`josh run:board`").
 
-**The filing ceilings still apply.** Count this filing in the ten-Issue limit for the run. An
-observation is discretionary, so above the WIP cap in the target repository, close one first or do
-not file (`prompts/collaboration-workflow/wip-cap.md`). File it with `pnpm josh issue:file`
-(`issue-scout.md`), which lints the body against `prompts/collaboration-workflow/issue-template.md`,
-applies the classification labels it declares, runs the duplicate scan, and runs `epic:bundle` on the
-new Issue so it is offered by its epic; an `auto-ok` epic adds it to the backlog pool
-(`backlogrun-steps.md` → "What one invocation approves"). When it is the second filing of the run, the
-command asks the fold question itself and holds a `fold`
-(`split-assessment.md` → "The same two questions decide the filing-time fold").
-
-The marker suite pins the rules below.
+**The filing ceilings still apply.** Count it in the run's ten-Issue limit; above the target
+repository's WIP cap, close one first or do not file (`prompts/collaboration-workflow/wip-cap.md`).
+File with `pnpm josh issue:file` (`issue-scout.md`): it lints the body, applies the classification
+labels, scans for duplicates and runs `epic:bundle` (an `auto-ok` epic adds it to the backlog pool —
+`backlogrun-steps.md` → "What one invocation approves"). On the second filing of the run it asks the fold
+question and holds a `fold` (`split-assessment.md` → "The same two questions decide the filing-time fold").
 
 ### The depth test — a discretionary filing cites the product work it blocked
 
@@ -51,78 +41,44 @@ The marker suite pins the rules below.
 | **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.**
-`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 `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.
+`depth:0` / `depth:1` / `depth:2` are defined in `scripts/issue/issue-labels.ts` with no definition of
+their own — **the table above is the single source**. **Every filing route applies one**: each route
+of `prerequisite.md`'s table, a split child and a review branch-2 filing pass `--depth <n>` to
+`pnpm josh issue:file`, beside any `--route`.
 
 ```bash
 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
 ```
 
-**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.
+`issue:file` creates any missing workflow label from `DEPTH_LABELS` before the create call.
 
-- **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 (`auto-ok` by `issue:file`'s judgement against the criteria —
-  `backlogrun-steps.md` → "What one invocation approves"); this one records what an Issue is about
-  and withholds nothing.
+- **It is read off the subject, exactly as the table is** — not a judgement, unlike `auto-ok` and
+  `needs-human-review`; it 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.
-- **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.
-
-Rationale: `docs/maintainers/observation-filing-rationale.md` → "Why the depth label is applied at filing".
+- **An Issue carrying more than one counts as the lowest depth present.**
+- **An `epic` takes no depth label** and is excluded from the share's denominator.
 
 - **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 (`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
-  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.** 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,
-    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.
-
-Rationale: `docs/maintainers/observation-filing-rationale.md` → "Why depth gates a discretionary filing".
-
-**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
-drop the one kind of finding both documents agree is never dropped. **That bar is the reason, and the
-subject's depth is not.** Rationale: `docs/maintainers/observation-filing-rationale.md` → "Why a
-review branch-2 filing skips the depth test".
-
-**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.** `route:tier-a` and
-`route:interrupt` carry over unchanged.
+  it stopped or delayed** — an Issue number or a run, never "this would slow runs down". **Cannot cite
+  one, it is not filed**: it goes to the ledger (`observation-ledger.md`); the blockage arriving or a
+  second sighting files it later.
+- **A depth-0 observation does not take this test**; the two ceilings are its only limits.
+- **`route:tier-a` and `route:interrupt` do not take it either**, at any depth.
+- **A depth-2 filing also states, on top of the depth-0 citation:**
+  - **The decision the number would change, named** — the Issue holding the choice, 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.
+  - **Cannot write both, it is not filed** — it goes to the ledger.
+- **This narrows depth 2 alone, and the exemptions above carry over unchanged.**
+
+**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 and
+**does not take the depth test**. **That bar is the reason, and the subject's depth is not.**
+
+**And a PR that *adds* a measurement names its reader in the same way** — the Issue that read the value
+to decide something, or the path of the rule that reads it. **A measurement with no reader is not
+added.** `route:tier-a` and `route:interrupt` carry over unchanged.
 
 ### The depth-0 share — what is counted
 
@@ -131,38 +87,23 @@ measurement with no reader is not added.** `route:tier-a` and
 **The denominator is a rule, not a choice, and this is it:**
 
 - **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.
+- **`route:tier-a` and `route:interrupt` are counted like anything else.**
 - **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**: 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".
+**Two readings of the same backlog give the same number.**
 
-**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 out of scope until the current value has
-been measured the same way more than once.
+**What the number is for is not decided here** — no `backlog:next` change and no target value until it
+has been measured the same way more than once.
 
 ### 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 files `route:tier-a` and `route:interrupt` only.** Its discretionary observations
+go in the summary's "Observations that could bite later" line (`backlogrun-child.md` → "What the
+summary carries, and how long it may be"); the parent files what survives the depth test, 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 child's only route is the summary's "Observations that could bite later"
-line; the parent chooses the key, checks the count and writes the line. **The 10-per-run ceiling for this route is the parent's to
-count.** **Lines its own `review:record` and `measure:rerun` write are not this route** — they go to
-its issue's file in its lane (`observation-ledger.md` → "The ledger — where an observation that
-cannot cite a blockage goes").
-
-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` → §2's table carries the
-trigger of the rule they carry out; nothing under `prompts/collaboration-workflow/` restates either.
-
-Provenance: `docs/maintainers/observation-filing-rationale.md` → "Where each rule came from".
+appends what is left.** **The 10-per-run ceiling for this route is the parent's to count.** **Lines
+its own `review:record` and `measure:rerun` write are not this route** — they go to its issue's file in
+its lane (`observation-ledger.md` → "The ledger — where an observation that cannot cite a blockage goes").

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

@@ -2,38 +2,22 @@
 
 **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.
-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. Provenance: `docs/maintainers/observation-ledger-rationale.md` → "Where
-each rule came from".
 
 ## The ledger — where an observation that cannot cite a blockage goes
 
 **An observation the depth test turns away is recorded in the ledger, not discarded.**
-Rationale: `docs/maintainers/observation-ledger-rationale.md` → "Why the
-ledger exists".
-
-- **The destination is the `.josh/observations/` directory in the repository the
-  observation is about** — the same repository the Issue would have been filed into — **one file per
-  issue**: 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` 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.
+
+- **The destination is the `.josh/observations/` directory in the repository the observation is
+  about**, **one file per issue**: `<N>.md` for the issue the run is executing (its branch's number,
+  a lane's included), or `<YYYY-MM-DD>.md` on the default branch outside any issue's run. **The count
+  and the append are both run in that repository's checkout** (resolved as `target-repository.md`
+  resolves a target). **The subject decides, never the working directory.** **A third-party target
+  gets no line either** (Tier C).
+- **It is append-only.** Never edit or delete a line; a second sighting is a second line. **A merge
+  conflict in it is resolved by keeping both sides.**
+- **The completion report keeps its line too.**
+- **The append is not the end of it** — → "The commit path — how an appended line reaches the
+  default branch" below.
 
 **One observation is one line: five fields, each separated from the next by a vertical bar with one
 space on either side.**
@@ -44,118 +28,74 @@ space on either side.**
 
 | 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 |
+| `k:<slug>`     | The identity key — lowercase letters and digits, in words joined by `-`                                                    |
+| `d<n>`         | The depth of the subject — `d1`, `d2`, or deeper. **There is no `d0` line**: depth 0 is filed outright                     |
 | `<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").
+**`k:example` is reserved for this sample and is never used by a real observation.**
 
 **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 record the sighting with one
-command — it counts what the ledger already holds for the key, appends the line and prints the
-verdict:
+Choose it from the phenomenon, not the run, and record with one command:
 
 ```bash
 pnpm josh observation:record <slug> d<n> '<where>' '<what>' [--checkout <that repository's checkout>]
 ```
 
-Standard output is one token: `file` (this is the second sighting — file it, below) or `ledger` (the
-line is the record, nothing to file); standard error lists the earlier sightings and the file
-appended to. A line that breaks the grammar, or uses `k:example`, is refused with exit 1 and nothing
-appended. **Every
-file of the directory is counted**, in the named checkout rather than the working directory, because
-a recurrence is a recurrence whichever issue's file each sighting sits in; a missing directory is a
-first sighting, and the append creates it.
-
-Free-text comparison is what the key exists to replace, so two lines that read alike under different
-keys are two observations, and a mis-keyed entry is corrected by appending a correctly-keyed line
-rather than by editing the one already written.
+Standard output is one token: `file` (second sighting — file it, below) or `ledger` (nothing to file);
+standard error lists earlier sightings and the file appended to. A broken line, or `k:example`, exits
+1 with nothing appended. **Every file of the directory is counted**, in the named checkout. A
+mis-keyed entry is corrected by appending a correctly-keyed line.
 
-**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 depth gate is not withdrawn, and this is not a way around it** — an observation that *can* cite
+blocked depth-0 work is filed as before.
 
 ## The commit path — how an appended line reaches the default branch
 
-**An append nobody commits is an append nobody can count.** Rationale:
-`docs/maintainers/observation-ledger-rationale.md` → "Why the ledger has a commit path".
-
-- **A run's appended lines ride its own commit.** `pnpm josh git` stages
-  `.josh/observations/` with the run's other changes, in the one staging step every entry
-  point goes through (`scripts/git/git-staging.ts`), so the lines are reviewed and merged with the
-  pull request of the run that recorded them, and the run's CI is the only wait they cost.
-  **Record before the commit, not after the merge:** a finding recorded with `pnpm josh review:record`
-  before `pnpm josh git -y` is carried; the time while CI runs is for the records that need no CI
-  result — filing an observation Issue, drafting the completion report.
-- **A line that breaks the grammar is not carried.** The staging step parses
-  every file of the ledger first — after moving lines still on an old single-file path — and on a broken line leaves the ledger out of the
-  commit and says so; the commit itself goes ahead.
+**An append nobody commits is an append nobody can count.**
+
+- **A run's appended lines ride its own commit** — `pnpm josh git` stages `.josh/observations/`
+  (`scripts/git/git-staging.ts`). **Record before the commit, not after the merge:** a finding recorded
+  with `pnpm josh review:record` before `pnpm josh git -y` is carried.
+- **A line that breaks the grammar is not carried** — the ledger is left out of the commit, which
+  goes ahead.
 - **A review round that passes after the pull request opened is recorded on the Issue, not in the
-  ledger** — `pnpm josh review:record --issue <N> --comment` posts the same `- rf:` lines as a comment
-  and appends nothing. That round reads only, so no commit of the run's follows it; a line in the tree
-  would be pushed onto the open pull request and its CI would start over. `pnpm josh ship --review`
-  does this for a passing round 2. **A round 2 that blocks records in the tree as before** — the fix it
-  stops for is pushed anyway and carries the lines. Once the Issue is closed, the next round recorded
-  to the ledger carries the comment's lines into `<N>-comment-rounds.md` with its own commit, so
-  `pnpm josh review:findings` and the retrospective count them (`review-comment-round.ts`).
+  ledger** — `pnpm josh review:record --issue <N> --comment` (`pnpm josh ship --review` does this for a
+  passing round 2), so CI does not restart. **A round 2 that blocks records in the tree as before.**
+  Once the Issue closes, the next ledger round carries the comment's lines into
+  `<N>-comment-rounds.md` (`review-comment-round.ts`).
 - **`pnpm josh followup` commits any other line appended after the run's commit onto the pull request,
-  before the merge** — the residual path, for an observation recorded between the commit and the
-  merge. After the merge gates and before the CI wait, `followup` reads the tree and, **only when the
-  ledger holds a pending append**, stages the ledger paths alone, commits them and pushes the branch;
-  that push restarts the pull request's CI, and the wait that follows covers it. A broken line refuses
-  the merge, because the line would otherwise be lost with the branch. A run whose lines rode its
-  commit pays nothing.
-- **A lane carries its own lines, in its own pull request.** Its writers
-  append to its own tree's `<N>.md`, so the two steps above take them to the default branch exactly as
-  they do for a run in the primary checkout. **Nothing is held in the primary checkout for later.**
-- **`pnpm josh observations:flush` is left for a line written outside any issue's run** — the
-  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.
+  before the merge** — only when the ledger holds a pending append; a broken line refuses the merge.
+- **A lane carries its own lines, in its own pull request.**
+  **Nothing is held in the primary checkout for later.**
+- **`pnpm josh observations:flush` is left for a line written outside any issue's run**: it commits the
+  ledger alone on its own branch, opens a docs-only pull request, waits on the required checks, merges
+  and returns to the default branch (a single run's `run:tail` runs it). It refuses off the default
+  branch or with anything besides the ledger in the tree. **Nothing is committed to the default branch
+  directly.**
+- **Nothing to flush is an answer, not a failure** — `clean`, exit 0.
 - **The count the promotion below reads is a count of the default branch.**
 
 ## 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"):
+**A repeat is the citation** — counted, not judged:
 
 - **On `observation:record` answering `file`, the observation is filed**, at depth 1 or deeper, with
-  no depth-0 citation. It answers `file` only when exactly one earlier sighting exists — a higher
-  count means the Issue was already opened by the sighting before. The line is appended either way,
-  because the ledger stays append-only.
-- **The Issue quotes the ledger's own dates — the first sighting's and this one's**, both on the
-  command's standard error — so the reader can check the promotion against the file instead of
-  taking the run's word for it.
-- **Both ceilings still apply**, exactly as `observation-filing.md` states them: the 10-per-run cap counts a promoted
-  filing, and the WIP cap still bites, since a promoted observation blocks nothing and is therefore
-  still discretionary.
-
-**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.
+  no depth-0 citation (only when exactly one earlier sighting exists).
+- **The Issue quotes the ledger's own dates — the first sighting's and this one's.**
+- **Both ceilings still apply** (`observation-filing.md`): the 10-per-run cap and the WIP cap.
+
+**A third and later sighting appends a line and files nothing more** — `pnpm josh issue:scout` finds
+the open Issue.
 
 ## 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.** 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.
+category never recurs as a first sighting.** The key is the **category of oversight** —
+`k:missed-case-worktree`. **Depth `d1`, never `d0`**. The `<what>` field leads with `User-reported:`;
+nothing else changes.