@joshuafolkken/kit 1.1229.0 → 1.1370.0

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

@@ -1,11 +1,9 @@
 # `backlogrun` — the manifest (named issues, epics and the opted-in backlog)
 
-**This file is the manifest, not the procedure** (joshuafolkken/kit#2190). It carries the ordered flow
-as terse triggers and pointers; the fine print of each step is read on demand from
-`backlogrun-steps.md`, its reference-only companion. `backlogrun-steps.md` is **not an entry read** —
-it is classified point-of-use in `entry-read-set.ts`, exactly as the four `backlogrun-*.md` phase
-documents are, so a `backlogrun` entry carries this manifest and nothing else up front
-(joshuafolkken/kit#2010, joshuafolkken/kit#2190).
+**This file is the manifest, not the procedure**: the ordered flow as terse triggers, and the route
+table naming the one section each moment reads. Rationale and provenance:
+`docs/maintainers/backlogrun-rationale.md` → "Why the loop's position is computed";
+`docs/maintainers/backlogrun-rationale.md` → "Where each rule came from".
 
 **`backlogrun` names either nothing, or the issues and epics to run first.** With no argument it runs
 whatever `pnpm josh backlog:next` offers — the whole opted-in backlog, every issue carrying `auto-ok`
@@ -15,12 +13,9 @@ that same backlog. **`--only` stops it after the named list**, draining nothing.
 
 **The loop's current position is computed, not carried in the conversation.** `pnpm josh run:step <N>`
 reads where the run is from the event stream, the carry record and the issue state, and prints the next
-single action — a runnable command, or the one point a person has to judge — so a session cut, a
-compaction or a fresh resume reaches the same next step from the same three inputs
-(joshuafolkken/kit#2248).
+single action — a runnable command, or the one point a person has to judge.
 
-**A named item may be a single issue or an epic** (joshuafolkken/kit#1985, folding in the old
-`epicrun` keyword). A single-issue item is one `fullrun`; **a named epic runs its children in
+**A named item may be a single issue or an epic.** A single-issue item is one `fullrun`; **a named epic runs its children in
 dependency order across the free lanes, and the run does not advance to the next named item until
 every one of that epic's children has been processed — merged or parked.** `backlogrun #E --only`
 therefore runs exactly one epic's children and stops.
@@ -33,56 +28,50 @@ is still that one invocation (`backlogrun-steps.md` → "The session cut is insi
 
 ## The manifest — the ordered flow
 
-Each step is a terse trigger and a pointer; the procedure is read on demand from the section named.
-
 1. **Claim nothing at the entry — this parent orchestrates and never implements.** The working-tree
    hold, the split assessment and `fullrun.md` are read by a dispatched child inside its own delegated
-   `fullrun` unit (`backlogrun-child.md`), never at the parent's entry.
+   `fullrun` unit, never at the parent's entry.
 2. **Begin the carry record before the plan** — `pnpm josh run:carry --begin "<invocation>" --owner
-   "$PPID"` and `pnpm josh run:wake --start`, in the same turn as the first `git switch main && git
-   pull`. The answer table (`began` / `resumed` / `busy` / `standing` / `mismatch` / `expired` /
-   `unreadable` / `unknown`) and the counting/hand-off/resume mechanism are
-   `backlogrun-steps.md` → "The session cut is inside the invocation".
-3. **What this invocation approves** — `backlogrun-steps.md` → "What one invocation approves": the
-   opted-in pool, a run's own filings once bundled, and the brake (`--max`, ten filings, the WIP cap)
-   that bounds the amount. `auto-ok` reaches a run's own filings only through `issue:file`'s default.
+   "$PPID"` and `pnpm josh run:wake --start`, in the same turn as the first `pnpm josh ms`.
+3. **What this invocation approves** — the opted-in pool, a run's own filings once bundled, and the
+   brake that bounds the amount; the route table's row points at the single source of the `auto-ok` default.
 4. **Report the plan before the first child** — `pnpm josh backlog:plan`, then resolve every
-   `needs-decision` issue decidable from its body in one pass. In the same pass, record `blocked-by`
-   between issues that must land in order, and apply `run:solo` where all three of the
-   `backlogrun-lanes.md` → "Lanes — running more than one child at a time" conditions hold, `run:lane` elsewhere. `backlogrun-steps.md` → "The plan,
-   before the first child starts" and its "Resolve what the plan can resolve, before starting".
-5. **Named issues run first, in order** — `backlogrun-steps.md` → "Named issues run first, in order":
-   the supervisor's driver dispatches each as a delegated `fullrun`, one at a time, then drains the
-   pool; `--only` stops after the list.
-6. **The loop belongs to the supervisor** — `run:wake` runs `backlog:drive`; the driver uses
-   `pnpm josh backlog:offer` as its loop head and returns a branch to an AI session only when it needs
-   judgment. `backlogrun-steps.md` → "The loop"
-   fixes what a handed-back branch asks, "The two budgets" the `run` / `watch` / `stop` verdict, "The cost
-   check is not asked during a watch", and "Where the run stops" every termination.
-7. **What runs once per session, not once per issue** — `backlogrun-steps.md` → "What runs once per
-   session, not once per issue": the per-repository preflight, `josh latest` on `required`, the
-   progress watcher, the carry/wake pair, and the release ask.
-8. **End the record when the run ends** — the driver's finish path runs `run:report` before
-   `run:carry --end` (or `--end --stopped "<reason>"`). The supervisor then observes that the record
-   ended and exits; a judgment branch hands its reason and resume flags to the AI session.
-   `backlogrun-steps.md` → "End the record when the run ends" is the single source.
-
-## Running a child — read the phase document at its point of use
-
-Everything about *running one child* — of a named epic or of the opted-in pool — lives in four phase
-documents, split out so the entry read carries only what binds before the first child
-(joshuafolkken/kit#2010). **None of the four is an entry read.** Each is read in full, in the turn the
-named step reaches it, exactly as `backlogrun-steps.md` and the shared gate documents
-(`chain-rule.md` / `latest-gate.md` / `followup.md` / `background-commands.md`) are
-(`SKILL.md` → §1, "Four documents are read at the point of use"):
-
-| Read | In full, before | What it carries |
-| --- | --- | --- |
-| `backlogrun-child.md` | dispatching the first child (`pnpm josh delegate epic-child`, `pnpm josh lane:dispatch`) | the shared per-child `fullrun`, a bare non-epic `#N`, the delegated unit and its summary bound, liveness recovery, and the once-per-session setup (audit, `josh latest`, preflight) |
-| `backlogrun-lanes.md` | opening the first lane (`pnpm josh lane:open`) | the per-repository lane ceiling and the lane lifecycle, and how a merge conflict is resolved |
-| `progress-watcher.md` | starting the progress watcher (`pnpm josh run:progress --wait`) | the heartbeat, shared with every implementing run |
-| `backlogrun-progress.md` | dispatching the first child and the hand-off check at a merge (`pnpm josh cost --cut`) | the hand-off and the cut/resume, waiting without waiting forever, and the end-of-run summary and propagate |
-| `backlogrun-park.md` | a child cannot finish | park-and-continue, the `needs-human-review` stop, a stale `in-progress`, a prerequisite discovered mid-run, and a mid-run split |
+   `needs-decision` issue decidable from its body in one pass, recording `blocked-by`, `run:solo` and
+   `run:lane` in the same pass.
+5. **Named issues run first, in order** — each as a delegated `fullrun`, one at a time, then the pool;
+   `--only` stops after the list.
+6. **The loop belongs to the supervisor** — `run:wake` runs `backlog:drive`, which returns a branch to
+   an AI session only when it needs judgment.
+7. **End the record when the run ends** — `run:report`, then `run:carry --end` (or `--end --stopped
+   "<reason>"`) and `run:wake --stop`.
+
+## The route table
+
+**Read one section, at the moment its row names, with `pnpm josh doc:section <file> "<heading>"`** —
+never a whole document (`SKILL.md` → "A section reference is read as a section"):
+
+| The moment | Read |
+| --- | --- |
+| The entry: the carry record and its answers | `backlogrun-steps.md` → "The session cut is inside the invocation" |
+| What the invocation may merge, and the `auto-ok` default | `backlogrun-steps.md` → "What one invocation approves" |
+| Before the first child: the plan and the decision pass | `backlogrun-steps.md` → "The plan, before the first child starts" |
+| The driver hands a branch back | `backlogrun-steps.md` → "The loop" |
+| Once per session | `backlogrun-steps.md` → "What runs once per session, not once per issue" |
+| `josh latest:scope` answers `required` | `latest-gate.md` (whole) |
+| Starting the progress watcher | `progress-watcher.md` → "Progress while the run is quiet" |
+| The run ends | `backlogrun-steps.md` → "End the record when the run ends" |
+| Labelling an issue `run:solo` | `backlogrun-lanes.md` → "A solo run" |
+| Before the first lane opens | `backlogrun-lanes.md` → "Once per repository, before the first lane opens" |
+| Opening a lane by hand | `backlogrun-lanes.md` → "Opening one lane and dispatching its child" |
+| The first child is in hand | `backlogrun-child.md` → "`josh latest` runs once per session, not once per child" |
+| Dispatching a child | `backlogrun-child.md` → "Each child runs in a delegated unit" |
+| An `epic #N` hand-back, a `merge` branch, or a `run:merge` token | `backlogrun-progress.md` → "Running a named epic's children" |
+| A merge answered `over` | `backlogrun-progress.md` → "The hand-off" |
+| A resumed session | `backlogrun-progress.md` → "Resuming after a cut" |
+| The run's last merge | `backlogrun-progress.md` → "Who sends the summary, and who propagates" |
+| `josh release:scope`, after the last merge | `followup.md` → "When `pnpm josh release` runs" |
+| A unit went silent | `backlogrun-recovery.md` → "A delegated unit that stopped without reporting" |
+| A child cannot finish | `backlogrun-park.md` → "park and continue" |
 
 ## Guards
 
@@ -97,7 +86,7 @@ A failure that is not consecutive parks its child and the run continues.
 ## This file is the single source of the `backlogrun` procedure
 
 `CLAUDE.md` carries the keyword's row in the shorthand table and the explicit-invocation rule;
-`SKILL.md` → §1 routes here. This manifest names which children there are and in what order; the
-procedure for each step is `backlogrun-steps.md`, and *running one child* is the four phase documents
-above. Where any of them could disagree, the rule is that this manifest and `backlogrun-steps.md` add
-nothing to a child's procedure — they only say which children there are.
+`SKILL.md` → §1 routes here. This manifest names which children there are and in what order; each
+step's procedure is the section its route-table row names. Where any of them could disagree, the rule
+is that this manifest and `backlogrun-steps.md` add nothing to a child's procedure — they only say
+which children there are.

package/.claude/skills/workflow-commands/chain-rule.md

@@ -2,22 +2,21 @@
 
 ## Run the review-to-merge chain
 
-This is the execution contract for `fullrun` and `backlogrun`; the record below is reference only.
+This is the execution contract for `fullrun` and `backlogrun`, and for `prrun` up to the pull request: a `prrun` never issues `pnpm josh ship` or a merging `pnpm josh followup` — it opens the pull request with `pnpm josh git -y` and ends by `prrun.md` → "The difference — the end of the run". The record below is reference only.
 Review results and successful pushes are never turn boundaries.
 
-0. **A lane child** (#2428): `pnpm josh main:merge`, the scoped pair, `pnpm josh ship --detach --review
+0. **A lane child**: `pnpm josh main:merge`, the scoped pair, `pnpm josh ship --detach --review
    "<title> #<N>"` (`--cite <N>`), then **end the turn** on `launched`/`busy`. A stop relaunches a child
-   whose prompt names `pnpm josh ship --log <N>` and (Anthropic lane, #2964) the re-detach to run after
+   whose prompt names `pnpm josh ship --log <N>` and (Anthropic lane) the re-detach to run after
    the fix — `pnpm josh ship --detach`, `--review` only if the stopped ship carried it and stopped before
    round 2, which is final (`scripts/run/ship/run-ship-next.ts`); the supervisor skips a recorded round 1.
    `failed` → step 1. A backgrounded `ship` issued alone is moved to the foreground by the hook
-   rather than refused (#3154).
+   rather than refused.
 1. Run `pnpm josh main:merge`. **Then issue `pnpm josh run:cut <N>` alone, before the scoped pair and
-   the gate** — the pre-gate cut (a no-op outside a lane, joshuafolkken/kit#2177). Then run the final scoped lint/test pair and `pnpm josh run:review`: it starts
-   `pnpm josh gate` in the background and prints the `/code-review` brief in one call, so the two overlap
-   rather than the review waiting on the gate (joshuafolkken/kit#2179). Launch the `/code-review`
-   subagent as the `general-purpose` agent type with that brief (every tool, so `--fix` applies; a
-   guessed type name fails, joshuafolkken/kit#2297).
+   the gate** — the pre-gate cut (a no-op outside a lane). Then run the final scoped lint/test pair and
+   `pnpm josh run:review`: it starts `pnpm josh gate` in the background and prints the `/code-review`
+   brief in one call, so the two overlap. Launch the `/code-review` subagent as the `general-purpose`
+   agent type with that brief (every tool, so `--fix` applies; never a guessed type name).
    Never load the review skill in the main line.
 2. Once the review returns, run `pnpm josh run:review --join` to join and read the gate before
    committing; it exits non-zero on a red gate. Fix any red check, then rerun the affected scoped check
@@ -34,14 +33,15 @@ Review results and successful pushes are never turn boundaries.
      of remaining non-High findings; a confirmed High blocks and receives a `confirmation` Telegram.
    Any round-1 fix runs its affected scoped check and the gate before `git -y`.
    Once a round's verdict is attested, record its findings with `pnpm josh review:record --issue <N>
-   [<category>:<severity>:<file> ...]` — a clean round records one zero-finding line.
+   [<category>:<severity>:<file> ...]` — a clean round records one zero-finding line. **A round 2 that
+   passes takes `--comment`** (`observation-ledger.md` → "The commit path").
    **`pnpm josh followup` refuses the merge until the round is recorded**
-   (`pnpm josh review:record --check --issue <N>`, joshuafolkken/kit#2343).
+   (`pnpm josh review:record --check --issue <N>`).
 5. **The clean path ships in one call** — with no second round due, background
-   `pnpm josh ship "<title> #<N>" --body-file <evidence.md>`: PR preflight (#2946) → gate → `git -y` →
-   `followup` → `run:tail`, stopping at the first failure (#2398). `--review` runs both rounds (#2489). **Else a due round 2
-   does not fit `ship`**: the PR opens between the rounds — background `pnpm josh git -y "<title> #<N>"`, round 2 beside CI, then
-   `pnpm josh followup`.
+   `pnpm josh ship "<title> #<N>" --body-file <evidence.md>`: PR preflight → gate → `git -y` →
+   `followup` → `run:tail`, stopping at the first failure. `--review` runs both rounds. **Else a due
+   round 2 does not fit `ship`**: the PR opens between the rounds — background
+   `pnpm josh git -y "<title> #<N>"`, round 2 beside CI, then `pnpm josh followup`.
 
 A lane child may end once, at step 0 or the pre-gate cut (`pre-gate-cut.md`); never at the push. The chain otherwise stops only when the PR is merged, the completion Telegram was sent, and
 `pnpm josh ms` returned to the default branch, or when user judgment is required by an unverifiable
@@ -51,51 +51,47 @@ Recommendations are informational; severity decides. A CodeRabbit rate-limit war
 
 ## Orchestration facts single-sourced here
 
-These are the gate → review → PR → merge facts other documents cite. This file is their single source
-(joshuafolkken/kit#1927 moved them out of `prompts/review.md`, which now carries only the review
-_policy_ — level, round cap, disposition — and `prompts/review-rubric.md` the rubric). Each is stated
-once here; the measurements that motivated each one live in the linked Issues.
+These are the gate → review → PR → merge facts other documents cite; this file is their single source
+(`prompts/review.md` carries the review _policy_, `prompts/review-rubric.md` the rubric). Where each
+rule came from and why it holds: `docs/maintainers/chain-rule-rationale.md` → "Where each rule came
+from", `docs/maintainers/chain-rule-rationale.md` → "Why the orchestration facts hold".
 
 - **The gate runs beside this review, not in front of it** — `pnpm josh gate` is started when the review
-  starts and joined before the commit; the two read the same tree and neither writes to it, so running
-  them serially is pure waiting. A red gate is fixed and re-run whatever the review concluded, and there
-  is no path to a commit on a gate nobody read (joshuafolkken/kit#1242).
+  starts and joined before the commit. A red gate is fixed and re-run whatever the review concluded, and
+  there is no path to a commit on a gate nobody read.
 - **origin/main is merged in before the gate** — `pnpm josh main:merge` merges `origin/<default>` into
-  the branch before the gate and the review start, so the gate verifies the tree that will actually
-  merge rather than one that never existed (joshuafolkken/kit#1837). It is the last edit, so the scoped
-  pair and the gate run once over it. A conflict here fires `backlogrun-recovery.md` → "Conflicts are not predicted"
-  early. **This is the one place a conflicted merge's procedure is written** (joshuafolkken/kit#2445):
+  the branch before the gate and the review start. It is the last edit, so the scoped pair and the gate
+  run once over it. A conflict here fires `backlogrun-recovery.md` → "Conflicts are not predicted"
+  early. **This is the one place a conflicted merge's procedure is written**:
   `main:merge` refuses before merging when uncommitted changes touch a path the default branch also
   changed, or when the index still holds unresolved or staged paths — commit the work first with
-  `pnpm josh git -y`, then rerun it, and **never stash around the merge** (a stash reapplied over it
-  leaves `UU` in the index). A merge that stops on a conflict is finished the same way: remove the
-  markers, then `pnpm josh git -y` stages the resolution and records the merge commit. That commit is
-  the sanctioned flow, so it is **Tier A** — a lane child never stops to ask a person for `git add`, and
-  the `Stop` hook sends back a reply that does.
+  `pnpm josh git -y`, then rerun it, and **never stash around the merge**. A merge that stops on a
+  conflict is finished the same way: remove the markers, then `pnpm josh git -y` stages the resolution
+  and records the merge commit. That commit is the sanctioned flow, so it is **Tier A** — a lane child
+  never stops to ask a person for `git add`, and the `Stop` hook sends back a reply that does.
 - **A single check answers once per tree** — while implementing, re-run a single check by name
   (`pnpm josh lint:related`, `pnpm josh cspell:dot`, `pnpm josh test:related`, or the project's type
   check) after every edit; a repeat of the same command with the same arguments over a tree nothing has
-  touched since buys only a copy of the answer already in hand (joshuafolkken/kit#1383).
+  touched since buys only a copy of the answer already in hand. In kit a detached `pnpm josh ship` also
+  checks the metrics totals before the hand-off, so the implementing session accepts a grown total with
+  its reason, as the ship's output names.
 - **The pull request opens between the rounds, so CI runs beside round 2** — `pnpm josh git -y` sits
   between the two review rounds. Round 1 runs on the uncommitted tree and its High/Medium findings are
   fixed before anything is committed; the verification pass over those fixes then runs against the open
-  pull request, beside the CI the commit started (joshuafolkken/kit#1261).
+  pull request, beside the CI the commit started.
 - **The round-2 fix commit is pushed before its gate** — a fix the second round makes in place is
   pushed (`pnpm josh git -y` again, a follow-up commit) before its `pnpm josh gate`, so the gate runs
-  inside the CI wait and is joined before `pnpm josh followup` rather than in front of it
-  (joshuafolkken/kit#1326). The commit and pre-push hooks and CI's `Checks` job mean pushing first is
-  not pushing unverified code.
+  inside the CI wait and is joined before `pnpm josh followup` rather than in front of it.
 - **A clean second round issues the merge in the same turn** — the turn that reads a clean second round
   issues `pnpm josh followup`, after any branch-2 filing and `pnpm josh epic:bundle` and never in a turn
   of its own. Clean has two halves: no confirmed High is standing, and nothing was routed to branch 1 of
-  the disposition (joshuafolkken/kit#1333).
+  the disposition.
 - **The review runs in a subagent, never a main-line skill load** — `/code-review` is spawned through
-  the `Agent` tool in its own context, as the agent type step 1 names; a mid-run `Skill` load rewrites
-  the whole cached prompt prefix, which is what makes it expensive (joshuafolkken/kit#1855).
+  the `Agent` tool in its own context, as the agent type step 1 names.
 - **The brief names the checkout, and a review that read another one is refused** — `pnpm josh
   review:brief` prints the checkout root, branch and HEAD and a nonce; the review runs `pnpm josh
   review:attest <nonce>` from the tree it read, and `pnpm josh review:attest --check` must answer `ok`
-  before the run or `pnpm josh followup` acts on the verdict, or it is discarded (joshuafolkken/kit#1522).
+  before the run or `pnpm josh followup` acts on the verdict, or it is discarded.
 
 This file is the single source of the gate → review → PR → merge chain rule; other documents reference
 it rather than restating it. `prompts/collaboration-workflow/plan-comment.md` keeps Step 3.

package/.claude/skills/workflow-commands/entry-sequence.md

@@ -1,12 +1,12 @@
 # The entry sequence and the stop branches — shared by `fullrun`, `halfrun` and `prrun`
 
-**This file is the part of the three implementing manifests that is one procedure**
-(joshuafolkken/kit#3174). `fullrun.md`, `halfrun.md` and `prrun.md` name only how their own run
-differs from it; `pnpm josh run:step <N>` prints the run's next single action.
+`fullrun.md`, `halfrun.md` and `prrun.md` name only how their own run differs from this shared
+procedure; `pnpm josh run:step <N>` prints the run's next single action. History:
+`docs/maintainers/entry-sequence-rationale.md` → "Where each rule came from".
 
 ## The ordered entry sequence
 
-**One call folds the mechanical steps** (joshuafolkken/kit#2372): `pnpm josh run:entry <N> --to
+**One call folds the mechanical steps**: `pnpm josh run:entry <N> --to
 <command>` claims the tree, reads the budget, bundles the reads and decides the pre-implementation
 step — steps 1, 3, 4 and 5 below in one round trip. Its `stage #<N>` line says where the run starts
 (`start: reached` redoes nothing — stop), and its `entry #<N> — hold: … · cost: … · verdict: …` line
@@ -33,7 +33,7 @@ short-circuits with a non-zero exit. The numbered steps are the detail behind ea
    dependency scope in one report; a `new` entry runs it once filed. The comment stops, the
    `human_review` stop (`needs-human-review.md`) and the dependency decision are read off it.
 5. **Print the next action — `pnpm josh run:step <N>`** — and follow it into the command's step list.
-   Before implementing, `git switch main && git pull`, then `pnpm josh latest:scope` — update
+   Before implementing, `pnpm josh ms`, then `pnpm josh latest:scope` — update
    dependencies only on `required` (`latest-gate.md`), never on every run. `run:step` names every later
    action in order, each read at the point-of-use document `SKILL.md` lists, never re-narrated here
    (`residency.md` → "順序の問い").
@@ -54,7 +54,7 @@ lane child starts none and never reads that document (`pnpm josh read:set lane-c
 - **A prerequisite** — file it (`route:tier-a`), stash, record the dependency, and **STOP** with
   "Please run `backlogrun #<E> --only` to execute this epic"; `prerequisite.md` is the single source of
   the filing, the `-u` stash and the epic:bundle branch.
-- **An observation** — file it without asking and carry on; `observation-filing.md`.
+- **An observation** — `observation-filing.md` (ask first if interactive).
 
 **Automatic filing is capped at 10 Issues per run.** On reaching it, stop and report.
 

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

@@ -3,7 +3,8 @@
 Everything between a green CI and a merged PR: the command, the merge it authorizes, the notifications,
 the reviewer scan, the config report and the release ask. `fullrun` and `backlogrun` end here;
 `halfrun` never reaches this file, because it stops before the commit. This file is the single source
-of the rule (joshuafolkken/kit#3176 merged the former post-execution reference into it).
+of the rule. Where each rule came from: `docs/maintainers/followup-rationale.md` → "Where each rule
+came from".
 
 ## Run `pnpm josh followup`
 
@@ -19,10 +20,10 @@ bullets. Use the file option whenever it contains a command or path.
 It waits for required CI, checks CodeRabbit and top-level AI review comments, sends the completion
 Telegram, merges by default, posts the Issue report, closes completed epics, removes `in-progress`,
 and releases the hold. Only `--no-merge` stops the merge; `--merge` is a deprecated no-op. **A pull
-request already merged by hand** (a `prrun` stop, joshuafolkken/kit#3023) skips the CI wait, the AI
-review scan and the merge and runs only the post-merge tail; a completion report already on the Issue
-is not posted or notified twice, so re-running is safe. Keep the default Issue target. Ignore a
-finding only after verifying it is inapplicable; rate-limit text is not a finding.
+request already merged by hand** (a `prrun` stop) skips the CI wait, the AI review scan and the merge
+and runs only the post-merge tail; a completion report already on the Issue is not posted or notified
+twice, so re-running is safe. Keep the default Issue target. Ignore a finding only after verifying it
+is inapplicable; rate-limit text is not a finding.
 
 **A red rate-limited CodeRabbit check is cleared by a retrigger, not a bypass.** Wait out the window
 the rate-limit comment states, post `@coderabbitai review` on the pull request, and rerun `followup`.
@@ -55,7 +56,7 @@ Invoking `fullrun` is itself the explicit authorization to merge; the user adds
 
 - **Always run `pnpm josh ms` after a successful merge** — it returns the tree to the default branch
   with the merge commit pulled. **In a lane, `pnpm josh lane:close <N>` is the terminal step instead**:
-  git allows one branch per work tree, so `josh ms` refuses there, and the refresh is the parent's.
+  `josh ms` refuses there, and the refresh is the parent's.
 - **Green CI is not authorization to merge while AI review findings are open.** On a blocker
   `followup` sends a `confirmation` Telegram and exits non-zero — fix and re-run. SonarCloud is not
   scanned here; the required `SonarQube` check carries it.
@@ -90,13 +91,12 @@ no longer bumps, so `package.json` names the previous release. What the run does
 ## Reading the stage-timing block
 
 The command closes with one `followup stage: <name> <seconds>` row per stage and a
-`followup stages total:` line (joshuafolkken/kit#1349), so where it spent its time is read, not
-guessed.
+`followup stages total:` line, so where it spent its time is read, not guessed.
 
 - **A failed run prints it too**, up to the stage that threw, named `interrupted` — a short block is
   the run stopping early, not the printer breaking. The `merge` row appears only on a run that merged.
-- **A row named `<a>-and-<b>` is a batch of requests sent together** (joshuafolkken/kit#1446);
-  `checks-wait` is never overlapped, because it is the merge gate.
+- **A row named `<a>-and-<b>` is a batch of requests sent together**; `checks-wait` is never
+  overlapped, because it is the merge gate.
 - **The total is the sum of the stages**, not the wall clock — the post-merge tail (record clears, the
   hold release, the next-issue listing) sits outside it.
 
@@ -116,25 +116,24 @@ posted after CI goes green is not silently shipped.
   N > 0. Rate-limit notices and sign-offs (`All issues resolved ✓`) match nothing.
 - **A standing blocker without `--ai-review-ignore-reason`** sends a `confirmation` Telegram and exits
   non-zero; with it, the reason is posted to the PR and the run proceeds.
-- **A comment listing that could not be read is a standing blocker** (joshuafolkken/kit#973) — never
-  an empty listing that passes.
-- **Temporary (kit#753)**: CodeRabbit is non-blocking end to end — out of the default required checks
+- **A comment listing that could not be read is a standing blocker** — never an empty listing that
+  passes.
+- **Temporary**: CodeRabbit is non-blocking end to end — out of the default required checks
   (restore via `JOSH_REQUIRED_CHECKS`), its actionable count and unreadable line-comment listing are
-  audit notes rather than blockers. Revert together with kit#752.
+  audit notes rather than blockers. When it is reverted:
+  `docs/maintainers/followup-rationale.md` → "The temporary CodeRabbit exemption".
 
 ## Config file reporting
 
 `followup` matches every changed path against what `josh sync` distributes (`AI_COPY_FILES`,
 `AI_COPY_FILE_MAPPINGS`, `AI_COPY_DIRECTORIES`, `SYNCED_PATHS`) and **reports** the claimed paths in the
-completion notification and the Issue report (joshuafolkken/kit#1578). **It stops nothing**
-(joshuafolkken/kit#1592): in kit every skill or prompt change is a distributed path, so a stop here
-only stopped the work its own acceptance criteria ordered. `pnpm josh sync:scope` gives the same
-answer on demand; there is no flag to pass.
+completion notification and the Issue report. **It stops nothing**
+(`docs/maintainers/followup-rationale.md` → "Why config claims are reported, not stopped").
+`pnpm josh sync:scope` gives the same answer on demand; there is no flag to pass.
 
 ## When `pnpm josh release` runs
 
-**The release point is a position plus a command's answer, never a judgement**
-(joshuafolkken/kit#1582).
+**The release point is a position plus a command's answer, never a judgement.**
 
 **The position: once per invocation, after the last merge** — a lone `fullrun`'s only one, a
 `backlogrun`'s **last** child, never once per child. In a lane the parent asks it, in the primary
@@ -155,3 +154,8 @@ the tag → publish → `production` chain — outward-facing and effectively ir
 Typing `fullrun` authorizes this Issue's merge and nothing past it; a person types the release in the
 primary checkout, on the default branch, with a clean tree. `release:scope` counts nothing of its own —
 it reads the same fetch-then-count `followup` uses for the Telegram line, so the two cannot disagree.
+
+**On `required`, the release request cites the open release Issue** — the one `issue:file --release` / `issue:release <N>` links blockers to — with a number-link
+(`prompts/collaboration-workflow/issue-citation.md`). List it with
+`gh api 'repos/{owner}/{repo}/issues?labels=release&state=open' --jq '.[].number'`; when none is
+open, the request names `pnpm josh release` alone.

package/.claude/skills/workflow-commands/fullrun-steps.md

@@ -1,9 +1,8 @@
 # `fullrun` — the step lists and the branches
 
-**This is the detailed procedure behind `fullrun.md`'s manifest, relocated here so the entry read
-carries the manifest, not the prose** (joshuafolkken/kit#2189). `fullrun.md` is the resident manifest;
-it routes here for the fine print of a step, read on demand — `pnpm josh run:next <N>` names which step
-the run is at, and the sections below carry that step in full.
+**The detailed procedure behind `fullrun.md`'s manifest**, read on demand — `pnpm josh run:next <N>`
+names which step the run is at, and the sections below carry that step in full. History:
+`docs/maintainers/fullrun-steps-rationale.md` → "Where each rule came from".
 
 ## The `fullrun #N` step list
 
@@ -15,28 +14,26 @@ budget allowed the run, and `run:release <N>` takes it back off → Read Issue #
 derive a better English title and `gh api -X PATCH repos/{owner}/{repo}/issues/<N> -f title="<title>"`)
 → post the agreed plan only if the Issue body is blank (`gh api -X PATCH
 repos/{owner}/{repo}/issues/<N> -f body="<plan>"`); if the body already has content, skip the
-plan-posting step → **emit the plan event**: `pnpm josh run:event --append plan "planned #<N>"` (a no-op
-outside a run; no cut follows it — a lane child's context is bounded by the threshold-gated
-implementation cut alone, joshuafolkken/kit#2489)
-→ implement → run the **verification gate** (the full procedure is `chain-rule.md`;
+plan-posting step → implement (the `plan` event `run:board` draws 📝 from is written by code — by
+`run:entry` for a `run:planned` issue, else at the first implementation edit — never by hand; no cut
+follows the plan — a lane child's context is bounded by the
+threshold-gated implementation cut alone) → run the **verification gate** (the full procedure is `chain-rule.md`;
 in outline: refactor → `pnpm josh main:merge` → **a dispatched lane child hands the rest to
-`pnpm josh ship --detach --review "<title> #<N>"` and ends its turn** (`chain-rule.md` step 0,
-joshuafolkken/kit#2428) → otherwise `pnpm josh run:cut <N>` (the pre-gate cut, before the gate; a no-op
+`pnpm josh ship --detach --review "<title> #<N>"` and ends its turn** (`chain-rule.md` step 0) → otherwise `pnpm josh run:cut <N>` (the pre-gate cut, before the gate; a no-op
 outside a lane) → start `pnpm josh gate` and a subagent `/code-review`
 with the brief `pnpm josh review:brief` prints on `git diff main`, join the gate before the commit,
 iterate to no high/medium findings, within the round cap (`prompts/review.md`) → **the clean path folds the ship region into
 one call**, `pnpm josh ship "<title> #<N>"` (gate → commit/push/PR → the CI-wait `followup` → the
-`run:tail` report bookkeeping, stopping at the first failed step; joshuafolkken/kit#2398), with any
+`run:tail` report bookkeeping, stopping at the first failed step), with any
 branch-2 filing (`pnpm josh issue:file`, which runs `epic:bundle` itself) run before it → **when a second round is due `ship` does not
 fit**: open the PR between the rounds with `pnpm josh git -y "<title> #<N>"`, run round 2 beside CI, then
 `pnpm josh followup` and `pnpm josh run:tail <N>`). Issue plan comments are written in the session language (`JOSH_SESSION_LANG`,
-default `ja`). Before implementing, run `git switch main && git pull`, then `pnpm josh latest:scope`
+default `ja`). Before implementing, run `pnpm josh ms`, then `pnpm josh latest:scope`
 and update dependencies only on `required` — `latest-gate.md` is its single source, and on `required`
-load the `dependency-update` skill afterwards. **A dispatched lane child skips the `git switch main &&
-git pull`**: `git switch main` is refused in a lane (the primary checkout holds the default branch, so
-the switch fails with `already used by worktree`), the lane was branched from a fresh default before it
-opened, and the latest default is brought in during the gate by `pnpm josh main:merge`. The parent runs
-`git switch main && git pull` in the primary checkout, never the child — `backlogrun-lanes.md` and
+load the `dependency-update` skill afterwards. **A dispatched lane child skips `pnpm josh ms`** — it
+refuses in a lane, and `pnpm josh main:merge` brings the latest default in during the gate
+(`docs/maintainers/fullrun-steps-rationale.md` → "Why a lane child skips `josh ms`"). The parent runs
+`pnpm josh ms` in the primary checkout, never the child — `backlogrun-lanes.md` and
 `backlogrun-child.md` are the single sources. When running `pnpm josh followup`, pass an
 implementation summary via `--notify-message` in the session language, leading with the three
 plain-language lines: `"Implemented <title>\nCause: ...\nFix: ...\nResult: ...\n\nDetails:\n-
@@ -48,15 +45,15 @@ primary checkout; a Claude run keeps it.
 ## The `fullrun new` step list
 
 `kickoff new` + `fullrun #N` in one run. Steps: (1) Derive an English title, or use the provided one.
-(2) Create Issue: `pnpm josh issue:file "<title>" --body-file <body-file> --depth <n>` (per
+(2) Create Issue: `pnpm josh issue:file "<title>" --body-file <body-file> --depth <n> --requested`,
+with the labels `kickoff.md` → "Words typed after `new`" maps (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 (`issue-scout.md`). Capture
 `<N>`. (3) Add `in-progress` (the bare hold named no issue):
 `gh api repos/{owner}/{repo}/issues/<N>/labels -f 'labels[]=in-progress'`. (4) Post the agreed plan
 in the session language: fill the body if blank,
 otherwise add a comment. (5) If the working tree already has staged or modified files,
-`git stash push -m "fullrun new: pre-existing changes" -- ':!.josh/observations'` first
-(joshuafolkken/kit#2919). (6) `git switch main && git pull`. (7)
+`git stash push -m "fullrun new: pre-existing changes" -- ':!.josh/observations'` first. (6) `pnpm josh ms`. (7)
 `pnpm josh latest:scope`; on `required` run `josh latest` and load the `dependency-update` skill; on
 `skip` neither runs (`latest-gate.md` is the single source). If you stashed in (5),
 `pnpm josh stash:pop "fullrun new: pre-existing changes"` — by message, never a positional `git stash
@@ -70,7 +67,7 @@ before its gate. (12) File whatever the review round cap routed to branch 2 with
 (it runs `epic:bundle` on each), and where (9a) answered `skip` record the skip on the Issue. (13) **Where no second
 round was due** (9a `skip`), fold steps (10)–(13) and the release bookkeeping into one call — `pnpm josh
 ship "<title> #<N>" --notify-message "..."` (gate → commit/push/PR → the CI-wait `followup` → `run:tail`,
-stopping at the first failed step; joshuafolkken/kit#2398); **where a second round ran**, the PR opened
+stopping at the first failed step); **where a second round ran**, the PR opened
 at (11) and the region stays separate — `pnpm josh followup "<title> #<N>" --notify-message "..."` then
 `pnpm josh run:tail <N>`. (14) **After the merge, run `pnpm josh ms`.** (15) **Ask `pnpm josh
 release:scope` and close the completion summary with what it answered** (`followup.md` →
@@ -78,12 +75,11 @@ release:scope` and close the completion summary with what it answered** (`follow
 
 ## The release ask — the last step of either form
 
-**One call folds the post-merge bookkeeping** (joshuafolkken/kit#2372): after the merge, `pnpm josh
-run:tail <N>` commits ledger lines written outside any issue's run (`observations:flush`,
-joshuafolkken/kit#2919), reads the completion citations
-(`issue:cite`, given the closed issue and any follow-ups filed this run) and decides the release scope
-(`release:scope`) in one round trip, joining each under its own header. **On the clean path `run:tail`
-runs inside `pnpm josh ship`** as its report step (joshuafolkken/kit#2398), so it is a standalone call
+**One call folds the post-merge bookkeeping**: after the merge, `pnpm josh
+run:tail <N>` commits ledger lines written outside any issue's run (`observations:flush`), reads the
+completion citations (`issue:cite`, given the closed issue and any follow-ups filed this run) and
+decides the release scope (`release:scope`) in one round trip, joining each under its own header. **On
+the clean path `run:tail` runs inside `pnpm josh ship`** as its report step, so it is a standalone call
 only where a second round kept the ship region separate. It folds only bookkeeping — the
 release ask below stays the single source of what `required` means and the Tier-C publish boundary; a
 `backlogrun` child still leaves `observations:flush`, `issue:cite` and the release ask to the batch's

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

@@ -1,11 +1,11 @@
 # `fullrun` — the manifest (plan → implement → PR → merge → notify)
 
-**This file is the manifest, not the procedure** (joshuafolkken/kit#2189). The entry sequence and
-the stop branches are `entry-sequence.md`, shared with `halfrun` and `prrun` (joshuafolkken/kit#3174);
-this file names only what is `fullrun`'s own. `pnpm josh run:step <N>` prints the run's next single
-action. `chain-rule.md`, `followup.md`, `background-commands.md` and `latest-gate.md` are **not entry
-reads** — each is fetched at its point of use. The step lists are `fullrun-steps.md`, read when a step
-needs its detail.
+**This file is the manifest, not the procedure.** The entry sequence and the stop branches are
+`entry-sequence.md`, shared with `halfrun` and `prrun`; this file names only what is `fullrun`'s own.
+`pnpm josh run:step <N>` prints the run's next single action. `chain-rule.md`, `followup.md`,
+`background-commands.md` and `latest-gate.md` are **not entry reads** — each is fetched at its point of
+use. The step lists are `fullrun-steps.md`, read when a step needs its detail. History:
+`docs/maintainers/fullrun-rationale.md` → "Where each rule came from".
 
 ## The difference — the entry and the end
 
@@ -18,10 +18,10 @@ needs its detail.
 ## The lane-child seam
 
 - **A lane child asks whether it is a resume first — `pnpm josh run:cut --resume <N>`** (`run:entry` asks it
-  before the hold, joshuafolkken/kit#2760); on `resume` it skips the title, plan, hold and implementation and goes to the gate. At the pre-gate
+  before the hold); on `resume` it skips the title, plan, hold and implementation and goes to the gate. At the pre-gate
   boundary — immediately after `pnpm josh main:merge`, before the gate — it takes the cut with
   `pnpm josh run:cut <N>` (the ordered step in `chain-rule.md`, which names the cut's single source),
   and it records any park on the Issue before the stop notify. A run that is not a lane child never
-  reads the cut's document (joshuafolkken/kit#3172).
-- **`resume: halfrun`** adopted a stopped `halfrun` (#2796): gate in full; `resume: prrun-*` a stopped
-  `prrun` (#3023); `working-tree-hold.md`.
+  reads the cut's document.
+- **`resume: halfrun`** adopted a stopped `halfrun`: gate in full; `resume: prrun-*` a stopped
+  `prrun`; `working-tree-hold.md`.