@joshuafolkken/kit 1.1453.0 → 1.1471.0

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

@@ -1,99 +1,82 @@
 # An Issue's comments are part of the Issue
 
-**The single source of the comment read**, read at its point of use — before implementing a `#N`
-Issue. Rationale and history: `docs/maintainers/issue-comments-rationale.md` → "Why comments are read".
+**The single source of the comment read**, read before implementing a `#N` Issue. Rationale and
+history: `docs/maintainers/issue-comments-rationale.md` → "Why comments are read".
 
 **Every `#N` entry point reads the Issue's comments before it implements** — `fullrun`, `halfrun` and
-`kickoff`; a `backlogrun` named issue and epic child inherit it through `fullrun`'s procedure. The read
-is one call, made in the same turn as whatever else the run already needs:
+`kickoff`; a `backlogrun` named issue and epic child inherit it through `fullrun`. One call, in the same
+turn as whatever else the run needs:
 
 ```bash
 pnpm josh issue:read <N> [<N> ...]     # body and comments, one call per batch
 gh api repos/{owner}/{repo}/issues/<N>/comments --jq '.[] | {user: .user.login, created_at, body}'
 ```
 
-**The first line is the one to type**; `pnpm josh issue:read` answers the body and the comments for
-every number named, in one call, and **says when a comment listing could not be read rather than
-showing no comments**. The `gh api` form stays for a **cross-repository** read: the command takes no
-`--repo`. Never `gh issue view <N> --comments` — it is GraphQL-backed and a cloud session is answered
-`403`.
+**Type the first line**; it **says when a comment listing could not be read rather than showing no
+comments**. The `gh api` form is for a **cross-repository** read (the command takes no `--repo`). Never
+`gh issue view <N> --comments` — GraphQL-backed, `403` in a cloud session.
 
 **This repository writes its agreements into comments and then reads only bodies.** **What the
-reading is for**, so it is not skimmed: the boundary of the scope — work a comment moved to
-another Issue, or added to this one; the record of an auto-decision already made; a split or epic
-agreement reached after filing; a recorded stash or an in-flight branch; and a **correction of the
+reading is for**: the scope boundary — work a comment moved elsewhere or added here; an auto-decision
+already made; a split or epic agreement; a recorded stash or in-flight branch; a **correction of the
 body's own diagnosis**.
 
 ## When a comment contradicts the body
 
-**The later text is the agreement in force.** A body is written first and is not rewritten when a
-decision arrives, so of a body and a comment that disagree the comment is the newer of the two and
-wins. **This is settled by ordering, never by judging which reads better.** Name in the two-layer work
-summary which comment superseded what.
+**The later text is the agreement in force** — the comment is the newer, so it wins. **This is settled
+by ordering, never by judging which reads better.** Name in the work summary which comment superseded
+what.
 
 **Two answers are not the run's to make, and each is decided from what the comment says:**
 
-- **A comment that reassigns part of the scope to another Issue** takes that part out of scope: do not
-  implement it, whatever acceptance criteria the body still lists, and name the Issue it went to in the
-  completion report.
+- **A comment that reassigns part of the scope to another Issue** takes that part out of scope, whatever
+  the body's criteria say; name the Issue it went to in the completion report.
 - **A comment saying the Issue no longer has a reason to exist** — the defect does not reproduce, or it
-  was fixed elsewhere — takes the exit in the next subsection, "When the work turns out to be already
-  merged". Closing an Issue is Tier C.
+  was fixed elsewhere — takes the exit in "When the work turns out to be already merged". Closing an
+  Issue is Tier C.
 
-Everything else is the ordinary work of the run, **a widened scope included**: a widening large enough
-to be several separately-mergeable deliverables is the split assessment's business
-(`split-assessment.md`), not a second kind of stop.
+Everything else, **a widened scope included**, is ordinary work; a widening into several
+separately-mergeable deliverables is the split assessment's business (`split-assessment.md`).
 
 ## When the work turns out to be already merged
 
-**A run can learn its Issue is already done in two ways, and both end here.** A **comment** says so —
-the bullet above — or the **run itself verifies it**, by reading the merged code and finding every
-acceptance criterion already satisfied. What is left to do afterwards is identical, so there is one
-procedure and not two. **Parking it is not the place**: `needs-decision` means "waiting for an answer
-nobody has given", and here the answer exists.
+**A comment says so, or the run itself verifies it** by finding every acceptance criterion already
+satisfied in merged code — one procedure either way. **Parking it is not the place**: `needs-decision`
+means "waiting for an answer", and here the answer exists.
 
-**The exit is the `already-done` label.** It is `needs-decision`'s counterpart: `epic:next`,
-`backlog:next` and `auto-ok:next` all stop offering the Issue (`scripts/issue/issue-labels.ts` →
-`NOT_DIRECTLY_RUNNABLE_LABELS`, `epic-classify.ts` → `human`), and `epic:busy` stops counting it as
-holding a lane. **Only a person removes it, by closing the Issue.**
+**The exit is the `already-done` label.** `epic:next`, `backlog:next` and `auto-ok:next` stop offering
+the Issue (`scripts/issue/issue-labels.ts` → `NOT_DIRECTLY_RUNNABLE_LABELS`, `epic-classify.ts` →
+`human`), and `epic:busy` stops counting it. **Only a person removes it, by closing the Issue.**
 
 ```bash
 gh api repos/{owner}/{repo}/labels -f name=already-done -f color=6f42c1 -f description="Verified already merged — a person closes it" --silent 2>/dev/null || true
 gh api repos/{owner}/{repo}/issues/<N>/labels -f 'labels[]=already-done'
 ```
 
-The procedure, in order:
-
-1. **Record the evidence as an Issue comment, before the label.** Name the pull request or commit that
-   merged the work and, for each acceptance criterion the Issue states, the file and lines that satisfy
-   it. **A claim with no citations is not the finding this exit is for.**
+1. **Record the evidence as an Issue comment, before the label**: the merging pull request or commit
+   and, per acceptance criterion, the file and lines that satisfy it. **A claim with no citations is not
+   the finding this exit is for.**
 2. **Apply `already-done`** — the two commands above.
-3. **Commit nothing, push nothing, open no pull request.** The tree is clean, so release the hold with
-   `pnpm josh run:release <N>`, which also removes `in-progress` — left on, it holds a lane against an
-   Issue nothing will ever run.
-4. **Then behave as the entry point does for a parked child.** A `fullrun` / `halfrun` a person typed
-   sends a `confirmation` Telegram naming the Issue and the merge that already covers it, and stops. An
-   `backlogrun` child is park-and-continue (`backlogrun-park.md` → "park and continue").
-5. **Never close the Issue.** That is Tier C at every entry point, and the label leaves the close one
-   click away for the person who owns it.
-
-**Nothing about this is a license to skip the work when it merely looks familiar.** The bar is step 1's
-citations: a criterion you cannot point at merged code for is a criterion this run still owes.
+3. **Commit nothing, push nothing, open no pull request.** Release the hold with
+   `pnpm josh run:release <N>`, which also removes `in-progress`.
+4. **Then behave as the entry point does for a parked child.** A typed `fullrun` / `halfrun` sends a
+   `confirmation` Telegram naming the Issue and the covering merge, and stops; a `backlogrun` child is
+   park-and-continue (`backlogrun-park.md` → "park and continue").
+5. **Never close the Issue** — Tier C at every entry point.
+
+**Looking familiar is no license to skip the work**: a criterion you cannot point at merged code for is
+one this run still owes.
 
 ## A long thread
 
-**The fetch is one call however long the thread is; what costs is carrying it afterwards** — which is
-why the call above projects each comment down to its author, its timestamp and its body. Once the
-thread runs longer than the Issue itself it is exactly the pre-implementation reading `delegation.md` describes:
-brief a delegated unit to return **the agreements in force plus the comment URLs that carry them**,
-never the comment text.
+**The fetch is one call; what costs is carrying it** — hence the projection to author, timestamp and
+body. A thread longer than the Issue is the pre-implementation reading `delegation.md` describes: brief
+a unit to return **the agreements in force plus the comment URLs that carry them**, never the text.
 
-**`pnpm josh rule:guard` refuses the body-only read** and hands over the reissue and the conflict rule
-at the moment they bind (`prompts/collaboration-workflow/rule-delivery.md`). **This file is the rule,
-not the hook** — a session that runs no hooks still owes the read.
+**`pnpm josh rule:guard` refuses the body-only read** (`prompts/collaboration-workflow/rule-delivery.md`).
+**This file is the rule, not the hook** — a session without hooks still owes the read.
 
 ## A person's update mid-run
 
-When the hook, `review:attest --check` or `followup` shows an Issue update, read it as above — the
-later text is in force — fix what it changes, then `pnpm josh issue:ack <N>`. The watch and what it
-does not catch: `docs/josh-commands-backlog.md` → "`josh issue:ack`".
+When the hook, `review:attest --check` or `followup` shows an Issue update, read it as above, fix what it
+changes, then `pnpm josh issue:ack <N>`. The watch: `docs/josh-commands-backlog.md` → "`josh issue:ack`".

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

@@ -1,92 +1,83 @@
 # `kickoff` — Planning phase only (plan → Issue → Telegram notify → stop)
 
 - `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 (`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
-  body is blank, `gh api -X PATCH repos/{owner}/{repo}/issues/<N> -f body="<plan>"`; otherwise
-  `pnpm josh issue:comment <N> --body-file <path>`) → **apply the `run:planned` label** — the mark the next
-  command's `run:entry` reads to start at the implementation, provisioned by `josh sync` (`gh api
-  repos/{owner}/{repo}/issues/<N>/labels -f 'labels[]=run:planned' --silent`) → send Telegram
-  notification, its last line `Next: halfrun #<N> | prrun #<N> | fullrun #<N>` → **stop**
-  (do not implement). **When the assessment finds two or more separately-mergeable deliverables**, take
-  the split path instead of posting a plan: create the children as in `kickoff new`, then either
-  **promote `#N`** with `pnpm josh epic --promote <N> <N1> <N2> ... [--ordered] [--rationale-file
-  <path|->]` — the right choice when `#N` is a request, a discussion or a container — or, when `#N` is
-  itself one of the deliverables, keep `#N` as a child and create a new epic with `pnpm josh epic`. That
-  branch is Tier A: choose it and record the reasoning on the Issue without asking. Present `backlogrun #<E> --only` and stop. Plan comments are written in the session language (`JOSH_SESSION_LANG`, default `ja`).
-  Telegram notification: `pnpm josh notify --task-type planning --issue-url "<issue-url>" --body=$'-
-  <bullet1>\n- <bullet2>\n...'`. `--task-type` controls the header icon (`planning` 📋 / `completion` ✅
-  / `failure` ❌ / `kickoff_retry` 🔄 / `confirmation` ⏸️). `--repo-name` and `--issue-title` are
-  auto-fetched from `gh` when not supplied. The Issue URL must be included.
+  nothing and prints the stage line alone; on `start: reached` report the stage line and **stop**. Then:
+  1. Read Issue #N **and every comment on it** — `pnpm josh issue:read <N>`; the later text is the
+     agreement in force (`issue-comments.md`, which also carries the answers that stop the run).
+  2. **Normalize the title** to clear English: `gh api -X PATCH repos/{owner}/{repo}/issues/<N> -f title="<title>"`.
+  3. Analyze requirements → **scope assessment per `split-assessment.md`**.
+  4. Post the plan — a blank body takes `gh api -X PATCH repos/{owner}/{repo}/issues/<N> -f body="<plan>"`,
+     otherwise `pnpm josh issue:comment <N> --body-file <path>` — in the session language
+     (`JOSH_SESSION_LANG`, default `ja`).
+  5. **Apply the `run:planned` label** — the next command's `run:entry` starts at the implementation
+     (`gh api repos/{owner}/{repo}/issues/<N>/labels -f 'labels[]=run:planned' --silent`).
+  6. Send the Telegram notification, its last line `Next: halfrun #<N> | prrun #<N> | fullrun #<N>` →
+     **stop** (do not implement).
+
+  **Two or more separately-mergeable deliverables** take the split path instead of a plan: create the
+  children as in `kickoff new`, then either **promote `#N`** with `pnpm josh epic --promote <N> <N1> <N2>
+  ... [--ordered] [--rationale-file <path|->]` (when `#N` is a request, a discussion or a container), or
+  keep `#N` as a child and create a new epic with `pnpm josh epic`. That branch is Tier A: choose and
+  record the reasoning on the Issue. Present `backlogrun #<E> --only` and stop.
+
+  Telegram: `pnpm josh notify --task-type planning --issue-url "<issue-url>" --body=$'-
+  <bullet1>\n- <bullet2>\n...'`. `--task-type` sets the icon (`planning` 📋 / `completion` ✅ /
+  `failure` ❌ / `kickoff_retry` 🔄 / `confirmation` ⏸️); `--repo-name` and `--issue-title` are
+  auto-fetched. The Issue URL must be included.
 
 **`kickoff` does not claim the working-tree hold, and does not release one** — it touches GitHub, never
-the tree. `working-tree-hold.md` is the single source.
+the tree (`working-tree-hold.md`).
 
 **The target repository is named in front of the Issue reference** — `kickoff kit#new`,
-`kickoff joshuafolkken/kit#<N>`. The definition 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
-checked out here. A target whose owner is not this session's is third-party: Tier C, so it stops rather
-than filing.
+`kickoff joshuafolkken/kit#<N>` (`target-repository.md`). `kickoff` needs no checkout: name the target in
+every `gh api` path, reads included, and never clone. The exception is the split path's epic — `pnpm josh
+epic` writes only the repository it runs in, and the promote arm stops when that repository is not
+checked out here. A third-party owner is Tier C: stop rather than file.
 
 **Read `split-assessment.md` → "The question" first** — `kickoff #N` assesses scope exactly as
-`kickoff new` does. Its default is not to split: separability and a scope that clearly exceeds what one
-verification gate can confirm in one pass have to hold **together**. The rest of `split-assessment.md`
-is read on demand when a split is found.
+`kickoff new` does. The default is not to split: separability and a scope clearly over one verification
+gate must hold **together**. The rest of `split-assessment.md` is read when a split is found.
+
+- `kickoff new` or `kickoff new "<title>"`: (0) **Scope assessment** per `split-assessment.md` — one
+  deliverable takes the **single-issue path**, several the **multi-issue split path**.
+  - **Single-issue path**: (1) Derive an English title, or use the one given. (2) `pnpm josh issue:file
+    "<title>" --body-file <body-file> --depth <n>` plus the labels the words typed after `new` name
+    ("Words typed after `new`", below; body per `prompts/collaboration-workflow/issue-template.md`) —
+    its duplicate scan runs first, and a candidate covering the same work stops the run (`SKILL.md` →
+    `issue-scout.md`). Capture `<N>`. (3) Post the plan as `kickoff #<N>` does. (4) Telegram. (5)
+    **Stop**.
+  - **Multi-issue split path**: (1) Per deliverable, `pnpm josh issue:file "<sub-title>" --body-file
+    <body-file> --depth <n> --route split` plus the labels the words after `new` name (duplicate scan
+    per `issue-scout.md`). A split filed into another repository gives every child body the `## Origin`
+    backlink, the epic the same link as prose (never a checkbox row, which disables its auto-close), and
+    the originating Issue lists children and epic under `## Upstream issues`. (2) **Epic — always, for
+    every split into two or more Issues**: `pnpm josh epic "<epic-title>" <N1> <N2> ... [--ordered]
+    [--rationale-file <path|->] [--origin <owner/repo#N>]`, capturing `<E>`. It builds the `epic` label,
+    the task-list rows (`- [ ] #N`), the machine-readable `Dependencies` and the `backlogrun` line; check
+    a hand-edited epic with `pnpm josh epic:check <E>`. (3) Telegram listing every created Issue. (4)
+    Present `backlogrun #<E> --only`. (5) **Stop**.
+
+  **The epic itself is never implemented** — `backlogrun` runs its *children*, and `pnpm josh followup`
+  closes it once every child is closed. Children with no required order take `None — the children are
+  independent; any execution order works.` under `Dependencies`. **Only when the execution order
+  matters** (`execution-waves.md` → "When a wave may be declared") pass `--ordered`, which treats the
+  argument order as the dependency order.
 
-- `kickoff new` or `kickoff new "<title>"`: No Issue exists yet. Steps: (0) **Scope assessment** per
-  `split-assessment.md`. If multiple → the **multi-issue split path**; if single → the **single-issue
-  path**. **Single-issue path**: (1) Derive an English title from the conversation, or use the provided
-  title. (2) Create Issue: `pnpm josh issue:file "<title>" --body-file <body-file> --depth <n>` plus the labels the words typed after `new` name ("Words typed after `new`", below) (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` →
-  `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 `issue-scout.md`): `pnpm josh issue:file
-  "<sub-title>" --body-file <body-file> --depth <n> --route split` plus the labels the words typed after `new` name. 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
-  plain bullet (never as a checkbox row, which would disable its auto-close), and the originating Issue
-  lists the children and the epic under `## Upstream issues`. (2) **Epic — always, for every split into
-  two or more Issues.** There is no count or ordering condition. **Create it with `pnpm josh epic
-  "<epic-title>" <N1> <N2> ... [--ordered] [--rationale-file <path|->] [--origin <owner/repo#N>]`**,
-  capturing its number `<E>` from the printed URL. The command satisfies the epic's four mechanical
-  requirements by construction — the `epic` label, the task-list rows (`- [ ] #N`), the machine-readable
-  `Dependencies`, and the printed `backlogrun` line. Check an epic you wrote or edited by hand with `pnpm
-  josh epic:check <E>`. Only where `josh` is unavailable, fall back to the manual procedure: ensure the
-  label exists (`gh api repos/{owner}/{repo}/labels -f name=epic -f color=5319e7 -f description="Tracks
-  a batch of child issues from one split" --silent 2>/dev/null || true`), then create the epic with `gh
-  api repos/{owner}/{repo}/issues -f title="<epic-title>" -f 'labels[]=epic' -F body=@<body-file>`. Its body
-  follows the epic format in `prompts/collaboration-workflow/issue-template.md` — split rationale,
-  dependencies, the `backlogrun` command, and a child task list in task-list syntax (`- [ ] #N`). The epic
-  exists as the **non-closing home for the split rationale**. When the children have no required order,
-  write `None — the children are independent; any execution order works.` under `Dependencies`. **The
-  epic itself is never implemented** — a `backlogrun` takes a named epic and runs its *children*. `pnpm josh
-  followup` closes it automatically once every child is closed. **Only when the execution order
-  matters** — the criterion is `execution-waves.md` → "When a wave may be declared" — record it natively: `pnpm josh epic --ordered` treats the argument order as the dependency
-  order; on the manual fallback path, after the child Issues exist, `gh api
-  repos/{owner}/{repo}/issues/<N2>/dependencies/blocked_by -F issue_id="$(gh api
-  repos/{owner}/{repo}/issues/<N1> --jq .id)"` for each dependent pair (the endpoint takes the blocker's
-  **database id**, not its issue number; a failure here is non-fatal). Never fold the relation into the
-  creation call. (3) Send Telegram notification listing all created issues. (4) Present the command
-  `backlogrun #<E> --only`. (5) **Stop** — do not implement.
+  **Only where `josh` is unavailable**, the manual fallback: `gh api repos/{owner}/{repo}/labels -f
+  name=epic -f color=5319e7 -f description="Tracks a batch of child issues from one split" --silent
+  2>/dev/null || true`, then `gh api repos/{owner}/{repo}/issues -f title="<epic-title>" -f
+  'labels[]=epic' -F body=@<body-file>` with the epic format of `issue-template.md`; an order is
+  recorded per pair with `gh api repos/{owner}/{repo}/issues/<N2>/dependencies/blocked_by -F
+  issue_id="$(gh api repos/{owner}/{repo}/issues/<N1> --jq .id)"` (the blocker's **database id**; a
+  failure is non-fatal), never folded into the creation call.
 
-`pnpm josh issue:file` lints the body and applies the classification labels it declares, following `prompts/collaboration-workflow/issue-template.md` for classification (`docs/josh-commands-backlog.md` → `josh issue:file`).
+`pnpm josh issue:file` lints the body and applies the classification labels it declares (`issue-template.md`; `docs/josh-commands-backlog.md` → `josh issue:file`).
 An Issue a consumer can use only once it is published is filed with `--release` (`kickoff new`), or linked with `pnpm josh issue:release <N>` (`kickoff #N`) — either makes it a blocker of the repository's `release` Issue, which never gets `auto-ok` on its own.
 
 ## Words typed after `new`
 
-**`auto-ok` is judged by `pnpm josh issue:file`, never typed** — by the same criteria as every
-filing: the excluded labels and the body's `- 人の判断:` declaration, and a `不要` declaration also needs a run label
-(`issue-template.md`).
+**`auto-ok` is judged by `pnpm josh issue:file`, never typed** — the excluded labels and the body's
+`- 人の判断:` declaration; a `不要` declaration also needs a run label (`issue-template.md`).
 `auto ok` typed after `new` adds nothing.
 
 **Words after `new`** (`kickoff new high`) are read like `into <target>`, never inferred. Each adds its

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,49 @@ 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.
+- **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.
 
 Rationale: `docs/maintainers/observation-filing-rationale.md` → "Why the depth label is applied at filing".
 
 - **A discretionary observation at depth 1 or deeper is filed only where it can cite the depth-0 work
-  it stopped or delayed** — named as an Issue number or a run, never as "this would slow runs down".
-  **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.
+  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.**
 
 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 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.**
+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 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 +92,32 @@ 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.
+**Two readings of the same backlog give the same number.**
 
 Rationale: `docs/maintainers/observation-filing-rationale.md` → "Why the depth-0 denominator is fixed".
 
-**What the number is for is not decided here.** Changing what `backlog:next` offers on the strength
-of it, and setting a target value, are both 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").
+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").
 
-Rationale: `docs/maintainers/observation-filing-rationale.md` → "Why a delegated child neither files
-nor appends".
+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.
+**This file is the single source of every procedure above**; nothing under
+`prompts/collaboration-workflow/` restates it.
 
 Provenance: `docs/maintainers/observation-filing-rationale.md` → "Where each rule came from".