@joshuafolkken/kit 1.1229.0 → 1.1370.0

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

@@ -6,9 +6,9 @@ When this run files a new Issue, file it with `pnpm josh issue:file`, which lint
 implements the change and runs the full verification gate, then **stops before commit** — nothing is
 committed, pushed, or opened as a PR — so a person verifies the working tree by hand. Use it when a change needs human eyes before shipping.
 
-**This file is the manifest** (joshuafolkken/kit#2189). The entry sequence and the stop branches are
-`entry-sequence.md`, shared with `fullrun` and `prrun` (joshuafolkken/kit#3174); this file names only
-what is `halfrun`'s own.
+**This file is the manifest.** The entry sequence and the stop branches are `entry-sequence.md`,
+shared with `fullrun` and `prrun`; this file names only what is `halfrun`'s own. History:
+`docs/maintainers/halfrun-rationale.md` → "Where each rule came from".
 
 ## The difference — the entry
 
@@ -20,7 +20,7 @@ what is `halfrun`'s own.
 ## The step list
 
 `halfrun #<N>`: read Issue #N and its comments → **normalize the title** (same as
-`fullrun`) → post the agreed plan only if the body is blank → `git switch main && git pull`, then `pnpm
+`fullrun`) → post the agreed plan only if the body is blank → `pnpm josh ms`, then `pnpm
 josh latest:scope` and update dependencies only on `required` (`latest-gate.md`; the
 `dependency-update` skill) → implement → run the **full verification gate** (refactor →
 start `pnpm josh gate` beside a subagent `/code-review` with the brief `pnpm josh review:brief` prints,
@@ -30,7 +30,7 @@ skip is the answer where the project has no suite) → **mark the stop: `pnpm jo
 --halfrun-stop`** (the record `fullrun #<N>` adopts; `new` passes the filed number) → send a
 `confirmation` Telegram with the resume commands in the body → **stop**. Plan comments are in the session language. The `confirmation` Telegram
 body MUST include the exact resume commands — **the `Next:` line first**, since that is how a verified
-`halfrun` ships (joshuafolkken/kit#2796): its `run:entry` adopts this stop's marked hold and resumes at
+`halfrun` ships: its `run:entry` adopts this stop's marked hold and resumes at
 the gate. The direct commands follow for shipping without an agent:
 `pnpm josh notify --task-type confirmation --issue-url "<issue-url>" --body=$'halfrun ready for manual
 verification\nNext: prrun #<N> | fullrun #<N>\nWithout an agent: pnpm josh git -y "<title> #<N>" && pnpm josh
@@ -42,11 +42,12 @@ back with fixes, treat each as a new round: implement, re-run `pnpm josh gate`,
 
 `halfrun new` or `halfrun new "<title>"`: `kickoff new` + `halfrun #<N>` (no Issue exists yet). Steps
 mirror `fullrun new` (1)–(8): derive an English title (or use the provided one) → create the Issue
-(`pnpm josh issue:file "<title>" --body-file <body-file> --depth <n>`, body per
+(`pnpm josh issue:file "<title>" --body-file <body-file> --depth <n> --requested`, with the labels
+`kickoff.md` → "Words typed after `new`" maps, body per
 `prompts/collaboration-workflow/issue-template.md`; its duplicate scan is read per `issue-scout.md`) → add `in-progress` (as `fullrun new` (3)) → post the agreed plan → stash
 any pre-existing changes with `git stash push -m "halfrun new: pre-existing changes" -- ':!.josh/observations'`
-(the pathspec keeps the observation ledger in the tree for this run's commit; joshuafolkken/kit#2919), popped by
+(the pathspec keeps the observation ledger in the tree for this run's commit), popped by
 message with `pnpm josh stash:pop "halfrun new: pre-existing changes"`, never a positional `git stash pop` →
-`git switch main && git pull` → `pnpm josh latest:scope` → implement → run the gate (as above, `pnpm
+`pnpm josh ms` → `pnpm josh latest:scope` → implement → run the gate (as above, `pnpm
 josh test:e2e` run by **you**) → `pnpm josh run:hold <N> --halfrun-stop` → send the `confirmation`
 Telegram and **stop**.

package/.claude/skills/workflow-commands/into-target.md

@@ -1,31 +1,26 @@
 # The `into <target>` suffix — where the new Issue lands
 
 **This file is the suffix's single source, read at its point of use — the moment a `new` entry is
-typed with an `into <target>` suffix, not at any entry** (joshuafolkken/kit#2161). A run given a `#N`
-or a bare `new` never reaches it, so it costs a workflow entry nothing to leave it here. `SKILL.md` →
-§2's table keeps the trigger and points here.
+typed with an `into <target>` suffix, not at any entry.** A run given a `#N` or a bare `new` never
+reaches it. `SKILL.md` → §2's table keeps the trigger and points here. Rationale:
+`docs/maintainers/into-target-rationale.md` → "Why the suffix reads as it does".
 
 `kickoff new` / `fullrun new` / `halfrun new` accept a suffix naming the epic the run's artifact
 belongs to. Without it the artifact belongs to no epic, and `epic:next` only ever offers an epic's
 children — so a forgotten instruction parks that Issue permanently rather than losing it visibly.
 
 ```
-kickoff new into #909
-fullrun new into #909
-halfrun new into #909
-kickoff new "<title>" into #909
-kickoff new into joshuafolkken/kit#909
+kickoff new into #<E>
+fullrun new into #<E>
+halfrun new into #<E>
+kickoff new "<title>" into #<E>
+kickoff new into joshuafolkken/kit#<E>
 ```
 
-`into` is the spelling because the alternatives collide with forms that already mean something else:
-`kickoff new #909` reads as the existing `kickoff #N`, and `kickoff new epic #909` reads as "create a
-new epic" when what gets created is often a single Issue.
-
 - **One artifact goes in: the top-level one this run created.** No split, and it is the Issue; a
   split, and it is the epic. The children belong to that epic, not to the target.
 - **Insert as soon as the artifact exists** — before implementation in `fullrun new`, before the plan
-  comment in `kickoff new`. Left until the end, a run that stops halfway leaves behind exactly the
-  orphaned Issue this suffix exists to prevent.
+  comment in `kickoff new`.
 - **The insertion always goes through `pnpm josh epic --add <E> <N> [--before <M> | --after <M>]`.**
   Never hand-edit the epic body: the declaration and the `blocked-by` relations then disagree,
   `epic:next` answers `error`, and an unattended run stops.
@@ -35,8 +30,7 @@ new epic" when what gets created is often a single Issue.
   ahead of.
 - **A target that is not an epic is refused, and the refusal names both ways out**:
   `pnpm josh epic --promote <N> <N...>` when it is a request, a discussion or a container, or a new
-  epic over both when it is itself one of the deliverables. Never promote on your own — which arm
-  applies depends on what the target is, and promoting rewrites someone else's Issue into a container.
+  epic over both when it is itself one of the deliverables. Never promote on your own.
 - **A cross-repository target is written `owner/repo#N`** and inserted from that repository's
   checkout; run there, since `epic --add` reads and writes only the repository it runs from
   (`.claude/skills/epic-commands/SKILL.md` → "Epics that span repositories"). A bare `#N` resolves to this repository's
@@ -44,5 +38,5 @@ new epic" when what gets created is often a single Issue.
 - **No suffix leaves the behavior exactly as it was.**
 
 **It is not `epic:bundle`, and both still run.** `epic:bundle` *recommends* an epic for a newly filed
-Issue and does nothing when the signal is weak; `into` is a person naming one explicitly. They are
-separate routes, so the `epic:bundle` call that follows a filing happens exactly as before.
+Issue and does nothing when the signal is weak; `into` is a person naming one explicitly. The
+`epic:bundle` call that follows a filing happens exactly as before.

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

@@ -1,15 +1,11 @@
 # An Issue's comments are part of the Issue
 
-**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, and every `#N` entry
-file routes here for the definition. It is read at its point of use — before implementing a
-`#N` 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".
 
 **Every `#N` entry point reads the Issue's comments before it implements** — `fullrun`, `halfrun` and
-`kickoff`. A `backlogrun` named issue and a `backlogrun` epic child inherit it rather than restate it: each runs in a
-delegated unit executing `fullrun`'s procedure, and the hook keys its once-per-run record on the
-*fork's* transcript, so every child is delivered to in its own right. 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`'s procedure. The read
+is one call, made in the same turn as whatever else the run already needs:
 
 ```bash
 pnpm josh issue:read <N> [<N> ...]     # body and comments, one call per batch
@@ -18,21 +14,12 @@ gh api repos/{owner}/{repo}/issues/<N>/comments --jq '.[] | {user: .user.login,
 
 **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** — which matters here, because the rule below is that the later text wins and a
-comment nobody read cannot win anything. The `gh api` form stays for a **cross-repository** read: the
-command takes no `--repo`.
+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`.
 
-`gh issue view <N> --comments` is GraphQL-backed, a cloud session is answered `403`, and
-`scripts/gh/gh-document-guard.test.ts` refuses it in a runnable block. The REST call above is the portable
-form.
-
-**This repository writes its agreements into comments and then reads only bodies.** A Tier A decision
-is logged as an Issue comment; the review round cap records a dropped finding's disposition; the
-backlog's decision pass writes each decision to a comment on the child; a stash left behind is recorded on the Issue. **The
-place a run is told to write is the place it was never told to read**, and nothing in a body says it
-has been superseded, so the mistake is silent.
-
-**What the reading is for**, so it is not skimmed: the boundary of the scope — work a comment moved to
+**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
 body's own diagnosis**.
@@ -102,7 +89,5 @@ brief a delegated unit to return **the agreements in force plus the comment URLs
 never the comment 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`,
-`scripts/rules/delivered-rules.test.ts`). The refusal reaches Claude Code alone and repeats until the comments are read,
-so **this file is the rule and the hook is what makes it hard to walk past** — a session that runs
-no hooks still owes the read.
+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.

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

@@ -24,32 +24,27 @@
   / `failure` ❌ / `kickoff_retry` 🔄 / `confirmation` ⏸️). `--repo-name` and `--issue-title` are
   auto-fetched from `gh` when not supplied. The Issue URL must be included.
 
-**`kickoff` does not claim the working-tree hold, and does not release one.** What that guard protects
-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. `working-tree-hold.md` is the
-single source.
+**`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 target repository is named in front of the Issue reference** — `kickoff kit#new`,
-`kickoff joshuafolkken/kit#412`. The definition is `target-repository.md`, whose body is `target-repository.md`. `kickoff` is the entry that needs
+`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.
 
-**Read `split-assessment.md` → "The question" first.** It is the split decision every entry point
-applies, including this one — `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 (the size guide is stated there) have to hold **together**.
-The rest of `split-assessment.md` — what each entry does with the answer — is read on demand when a
-split is found.
+**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` 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>` (body
+  title. (2) Create Issue: `pnpm josh issue:file "<title>" --body-file <body-file> --depth <n>
+  --requested` 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)
@@ -57,7 +52,7 @@ split is found.
   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`. Capture each Issue number. **When the split is filed into a repository other than
+  "<sub-title>" --body-file <body-file> --depth <n> --route split --requested` 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
@@ -77,7 +72,7 @@ split is found.
   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**, record it natively: `pnpm josh epic --ordered` treats the argument order as the dependency
+  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
@@ -86,3 +81,19 @@ split is found.
   `backlogrun #<E> --only`. (5) **Stop** — do not implement.
 
 `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`).
+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`
+
+**An Issue a person asked for is filed with `--requested`** — every `new` entry (each child of its
+multi-issue split included), and a request in conversation. A live carry record or an `auto-ok` branch Issue then does not opt it in, so no lane takes
+it before the person picks the run; `auto-ok` comes only from the words below (`issue-auto-ok.ts`). A
+filing the run decides on its own — observation, retrospective, a split the run finds itself, routed — never declares it.
+
+**Words after `new`** (`kickoff new auto ok high`) are read like `into <target>`, never inferred. Each
+adds its labels to the `--requested` filing; a word not in the table is asked about:
+
+| Typed     | Added to `pnpm josh issue:file`    |
+| --------- | ---------------------------------- |
+| `auto ok` | `--label auto-ok --label run:lane` |
+| `high`    | `--label priority:high`            |

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

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

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

@@ -1,16 +1,11 @@
 # `needs-human-review` — the child that stops before its commit
 
-**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`.
+**The single source of the label**, read at its point of use — the moment `pnpm josh issue:state <N>`
+answers `human_review: yes`. Rationale and history: `docs/maintainers/needs-human-review-rationale.md`
+→ "Why the label exists".
 
 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 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.
+point reached it — `fullrun` or `backlogrun` — and the label may be applied **only by a person**.
 
 - **Implementation and the verification gate run normally** — refactor, `pnpm josh gate`,
   `/code-review`, exactly as for any other child.
@@ -28,15 +23,11 @@ person's to make** such as picking one of several generated candidates.
   carries on from the commit themselves. The stop report carries that resume command too, not only the
   Telegram.
 
-**Stopping is the specification, not a failure.** The label's job is to stop a batch walking past a
-decision that was a person's to make.
+**Stopping is the specification, not a failure.**
 
-**Read the answer from `pnpm josh issue:state <N>`, never by matching the label string yourself.** It
-prints a `human_review: yes` / `human_review: no` line beside the state and the labels, through the
-same case-insensitive comparison every other workflow label goes through — so `Needs-Human-Review` is
-not missed. **Ask once, before implementing**: `epic:next` prints a bare issue number and `fullrun`
-and a batch child are handed one, so the check is one call of its own, made the moment the number is in
-hand and before the plan.
+**Read the answer from `pnpm josh issue:state <N>`, never by matching the label string yourself** — it
+compares case-insensitively. **Ask once, before implementing**: one call of its own, made the moment
+the number is in hand and before the plan.
 
 ```bash
 pnpm josh issue:state <N>                      # state, labels, and human_review
@@ -52,13 +43,11 @@ repository, by a person:
 gh api repos/{owner}/{repo}/labels -f name=needs-human-review -f color=d93f0b -f description="Implement and verify, but stop before committing so a person can look"
 ```
 
-**It is not `needs-decision`, and reading it as one breaks two things.** `needs-decision` withholds a
-run's *start*; this withholds its *end*. So a `needs-human-review` issue is still offered — excluded,
-the artifact a person is meant to look at would never be produced — and a child stopped by it **goes on
-holding its repository**, because the uncommitted work is still in the checkout; read as parked there,
-the next child would start `git switch main && git pull` on top of it. The code encodes both halves by
-leaving the label out of two sets: `scripts/issue/issue-labels.ts` keeps it out of
-`NOT_DIRECTLY_RUNNABLE_LABELS` and `scripts/epic/epic-busy.ts` keeps it out of the parked set.
+**It is not `needs-decision`**: `needs-decision` withholds a run's *start*; this withholds its *end*.
+So a `needs-human-review` issue is still offered, and a child stopped by it **goes on holding its
+repository** — `scripts/issue/issue-labels.ts` keeps it out of `NOT_DIRECTLY_RUNNABLE_LABELS` and
+`scripts/epic/epic-busy.ts` keeps it out of the parked set (`docs/maintainers/needs-human-review-rationale.md`
+→ "Why it is not `needs-decision`").
 
 Each entry point's own branch stays in its own file — `fullrun.md`, `halfrun.md`,
 `backlogrun.md` — and routes here for the definition.

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

@@ -1,37 +1,48 @@
 # The observation filing procedure
 
-**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
+**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 (joshuafolkken/kit#3176).
+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.
 
 **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).
+turn all file or propose.
 
-**A run that judges something worth filing files it, and does not ask.** An upstream defect stops the
+**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.
 
+**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, run
-`pnpm josh issue:fold` first; the guard refuses that filing without the fold
+(`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 depth test — a discretionary filing cites the product work it blocked
 
-**Depth is read off the subject rather than judged** (joshuafolkken/kit#1698):
+**Depth is read off the subject rather than judged:**
 
 | Depth | The subject | Where it lives |
 | --- | --- | --- |
@@ -39,8 +50,8 @@ The marker suite pins the rules below.
 | **1** | The run orchestration that executes an Issue | `fullrun` / `backlogrun`, lanes, the `epic:*` commands, the filing routes themselves |
 | **2** | What measures a run | `josh cost` and the run-timing report |
 
-**The depth is recorded on the Issue as a label, and the label is applied when the Issue is filed**
-(joshuafolkken/kit#1729). `depth:0`, `depth:1` and `depth:2` are the three, defined once in
+**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`
@@ -55,7 +66,7 @@ gh api repos/{owner}/{repo}/issues/<N>/labels -f 'labels[]=depth:1'   # an Issue
 
 **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).
+defines, 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
@@ -81,7 +92,7 @@ Rationale: `docs/maintainers/observation-filing-rationale.md` → "Why the depth
 - **`route:tier-a` and `route:interrupt` do not take it either**, at any depth: a filing the run
   cannot proceed without is already citing its own blockage.
 - **A depth-2 filing — one whose subject is what measures a run — carries a further requirement, on
-  top of the depth-0 citation above rather than in place of it** (joshuafolkken/kit#1975). A
+  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
@@ -106,21 +117,16 @@ drop the one kind of finding both documents agree is never dropped. **That bar i
 subject's depth is not.** Rationale: `docs/maintainers/observation-filing-rationale.md` → "Why a
 review branch-2 filing skips the depth test".
 
-**This is not the count cap that was rejected.** A cap is rationing — past the number the finding is
-lost, and nothing about it says which findings were worth having. This changes what counts as a
-finding at all, so what it excludes is excluded for a reason a reader can check.
-
 **And a PR that *adds* a measurement names its reader in the same way.** The requirement above binds
 a depth-2 Issue that *proposes* a measurement; a pull request that *adds* one — a new report column,
 section, scope or subcommand, a diagnostic step — states in its body the reader that consumes it: the
 Issue number that read the value to decide something, or the path of the rule that reads it. **A
-measurement with no reader is not added** (joshuafolkken/kit#2012). `route:tier-a` and
+measurement with no reader is not added.** `route:tier-a` and
 `route:interrupt` carry over unchanged.
 
 ### The depth-0 share — what is counted
 
-**The depth-0 share is the share of open Issues at depth 0** (joshuafolkken/kit#1698,
-joshuafolkken/kit#1729).
+**The depth-0 share is the share of open Issues at depth 0.**
 
 **The denominator is a rule, not a choice, and this is it:**
 
@@ -136,8 +142,8 @@ counter's judgement.
 Rationale: `docs/maintainers/observation-filing-rationale.md` → "Why the depth-0 denominator is fixed".
 
 **What the number is for is not decided here.** Changing what `backlog:next` offers on the strength
-of it, and setting a target value, are both deliberately out of scope until the current value has
-been measured the same way more than once (joshuafolkken/kit#1729 → 範囲外).
+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.
 
 ### A delegated child does not take this route
 
@@ -147,13 +153,16 @@ could bite later" line (`backlogrun-child.md` → "What the summary carries, and
 parent files what survives — under the depth test above, and inside the run's ceiling.
 
 **A delegated child does not append to the ledger either — the parent collapses the duplicates and
-appends what is left.** The child's route is unchanged and is the only one it has —
-the summary's "Observations that could bite later" line — and the parent chooses the key, checks the
-count and writes the line. **The 10-per-run ceiling for this route is the parent's to count.**
+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
-(joshuafolkken/kit#1649, joshuafolkken/kit#1797).
+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".