@joshuafolkken/kit 1.1453.0 → 1.1471.0

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

@@ -43,23 +43,16 @@ Rationale: `docs/maintainers/backlogrun-recovery-rationale.md` → "Why the poll
 
 ## Conflicts are not predicted
 
-**The child merges `origin/main` into its lane before its gate now, so this path is the fallback rather
-than the first line.** Every `fullrun` runs `pnpm josh main:merge` ahead of the gate
-(`chain-rule.md` → "origin/main is merged in before the gate", the single source), so an overlap
-already on `main` is resolved before the gate reads the tree. What this section covers is an overlap
-that lands on `main` *after* it, which `followup` still reports as a conflict.
+**This path is the fallback**: every `fullrun` runs `pnpm josh main:merge` ahead of the gate
+(`chain-rule.md` → "origin/main is merged in before the gate"), so it covers an overlap that lands on
+`main` *after* it. **Nothing here forecasts which children will overlap** — a conflicting pull request
+comes back `mergeStateStatus: DIRTY`, which `git-pr-checks-eval.ts` reads as a **failure**, so `pnpm josh
+followup` ends that child with a named conflict in about ten seconds.
 
-**Nothing here forecasts which children will overlap.** The overlap surfaces where GitHub already
-reports it: a pull request that conflicts with its base comes back `mergeStateStatus: DIRTY`, which
-`git-pr-checks-eval.ts` reads as a **failure** rather than polling through it — so `pnpm josh followup`
-ends that child with a named conflict in about ten seconds.
-
-**That child does not stop: it resolves the conflict in its own lane.** It is **not** counted against
-the consecutive-failure guard either way.
-
-**The merge direction is `origin/main` into the lane's branch, never a rebase**, and no step below
-rewrites a pushed commit. Rationale: `docs/maintainers/backlogrun-recovery-rationale.md` → "Why a conflict
-is resolved in the lane rather than handed to a person".
+**That child does not stop: it resolves the conflict in its own lane**, uncounted by the
+consecutive-failure guard. **The merge direction is `origin/main` into the lane's branch, never a
+rebase**; no step rewrites a pushed commit (`docs/maintainers/backlogrun-recovery-rationale.md` → "Why a
+conflict is resolved in the lane rather than handed to a person").
 
 1. **Resolve in the lane.** `git fetch origin main`, merge `origin/main` into the lane's branch, resolve
    in place. Do not close the lane, open another, or switch its branch.
@@ -96,7 +89,5 @@ Meeting any of the four, the child is parked — `needs-decision` plus a comment
 it was, read against `backlogrun-park.md` → "Only a person's judgement carries `needs-decision`" — and its lane is **kept**, because the pushed branch is the resume path
 (`backlogrun-lanes.md` → "What happens to a lane").
 
-**Leave the tree clean before parking: `git merge --abort` precedes a park under conditions 1, 2 or 4.**
-Conditions 1 and 2 are read mid-merge with conflict markers still in the tree, condition 4 after a merge
-that is resolved but not committed; condition 3 fires before any merge is started, so there is nothing
-to abort.
+**Leave the tree clean before parking: `git merge --abort` precedes a park under conditions 1, 2 or 4**
+(condition 3 fires before any merge starts).

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

@@ -1,26 +1,30 @@
 # `backlogrun` — the detailed procedure behind the manifest
 
-Point-of-use, read one section at a time from `backlogrun.md` → "The route table"; how the driver runs the loop on its own is `docs/maintainers/backlogrun-driver.md`.
+Point-of-use, read one section at a time from `backlogrun.md` → "The route table"; how the driver runs the loop on its own is `docs/maintainers/backlogrun-driver.md`. Reasons:
+
+- `docs/maintainers/backlogrun-steps-rationale.md` → "Why the authorization boundary is shaped this way"
+- `docs/maintainers/backlogrun-steps-rationale.md` → "Why a session cut does not end the run"
+- `docs/maintainers/backlogrun-steps-rationale.md` → "Why the plan and the decision pass come first"
+- `docs/maintainers/backlogrun-steps-rationale.md` → "Why the loop's contract is shaped this way"
+- `docs/maintainers/backlogrun-steps-rationale.md` → "Why the idle watch lasts 8 hours from when the hands became free"
+- `docs/maintainers/backlogrun-steps-rationale.md` → "Why the cost check skips a watch"
+- `docs/maintainers/backlogrun-steps-rationale.md` → "Where each rule came from"
 
 ## What one invocation approves
 
 **One `backlogrun` approves every merge of every issue `pnpm josh backlog:next` offers** — `auto-ok`
 issues, every child of an epic whose root carries it, and a run's own filing once `pnpm josh
 epic:bundle` (Tier A, `observation-filing.md`) has placed it under such a root. **A named issue is
-approved by the keyword and its number, not by `auto-ok`** ("Named issues run first, in order"). What
-runs is stated by the keyword and its arguments, never inferred from a request's shape. **Two repairs
-that would bound this the other way are prohibited** — dropping a run's own filings, and requiring a
-person's `auto-ok` on a child; the brake below bounds it. A Tier C action inside a child still stops that child.
+approved by the keyword and its number, not by `auto-ok`**. What runs is stated by the keyword and its
+arguments, never inferred. **Two repairs that would bound this the other way are prohibited** —
+dropping a run's own filings, and requiring a person's `auto-ok` on a child; the brake below bounds it.
+A Tier C action inside a child still stops that child.
 
 **`pnpm josh issue:file` judges `auto-ok` and prints it** — `auto-ok: applied` or
-`auto-ok: not applied` with the reason; `scripts/issue/issue-auto-ok.ts` is the single source. Every
-filing is judged the same way, whoever asked for it: the excluded labels, then the body's
-`- 人の判断:` declaration (`issue-template.md`). **Declare `- 人の判断: 要` when the new issue needs a
-person's judgement** — a Tier B toss-up or a Tier C action inside it; `--no-auto-ok` withholds it too.
-The retrospective's filings are judged the same way and count against the same brake.
-
-Rationale: `docs/maintainers/backlogrun-steps-rationale.md` → "Why the authorization boundary is shaped this way";
-provenance of each rule: `docs/maintainers/backlogrun-steps-rationale.md` → "Where each rule came from"
+`auto-ok: not applied` with the reason (`scripts/issue/issue-auto-ok.ts`). Every filing, the
+retrospective's included, is judged the same way: the excluded labels, then the body's `- 人の判断:`
+declaration (`issue-template.md`). **Declare `- 人の判断: 要` when the new issue needs a person's
+judgement** — a Tier B toss-up or a Tier C action inside it; `--no-auto-ok` withholds it too.
 
 ### The brake that replaces the promise
 
@@ -33,30 +37,26 @@ provenance of each rule: `docs/maintainers/backlogrun-steps-rationale.md` → "W
 | **Ten filings per invocation** | additions to the pool on **every** filing route (`prerequisite.md`) — `route:tier-a`, `route:interrupt` and a review branch-2 filing are exempt from the depth test (`observation-filing.md`), never from this ceiling | `run:carry --filed` |
 | The WIP cap on open issues | the pool across invocations | `prompts/collaboration-workflow/wip-cap.md` |
 
-**This section is the single source of how the `epic:bundle` obligation and this authorization
-boundary meet.** `observation-filing.md` points here rather than restating it.
+**This section is the single source of how the `epic:bundle` obligation and this boundary meet.**
 
 ## Named issues run first, in order
 
-**`backlogrun #N1 #N2 …` runs the named issues before it touches the pool**,
-in the order typed, **one at a time — no lanes**, each as a full `fullrun` in a delegated unit
-(`backlogrun-child.md` → "Each child runs in a delegated unit"); the parent reads each one's state back
-with `pnpm josh issue:state <N>`, never the unit's summary. `pnpm josh backlog:plan #N1 #N2 …` renders
-the order, and `scripts/backlog/backlog-named.ts` is its single source.
+**`backlogrun #N1 #N2 …` runs the named issues before it touches the pool**, in the order typed, **one
+at a time — no lanes**, each as a `fullrun` in a delegated unit (`backlogrun-child.md` → "Each child
+runs in a delegated unit"), read back with `pnpm josh issue:state <N>`. `pnpm josh backlog:plan #N1
+#N2 …` renders the order (`scripts/backlog/backlog-named.ts`).
 
-**A named issue that cannot finish parks, and the rest of the named list is skipped**; the run then
-drains the pool, and the report lists what was not started (`backlog_named.after_failure`). A
-`needs-human-review` named issue stops the whole run (`needs-human-review.md`). **`--only` runs the
-named list and stops there, draining no pool** — a failure under `--only` ends the run, and `--only`
-with no named issues is refused before anything starts (`backlog_named.startup`).
+**A named issue that cannot finish parks, and the rest of the named list is skipped**; the run drains
+the pool and reports what was not started (`backlog_named.after_failure`). A `needs-human-review` named
+issue stops the whole run. **`--only` runs the named list and stops there, draining no pool** — a
+failure ends the run, and `--only` with no named issues is refused (`backlog_named.startup`).
 
 ## The session cut is inside the invocation
 
 **Typing `backlogrun` once authorizes the declared budget, and a session cut does not end the run** —
-the next session picks the same invocation up from the carry record (`backlogrun-progress.md` → "The
-hand-off"). The record keeps the opening invocation string, `--only` and the named list included; a
-resumed session runs `remaining` from `--json`. The contract is `docs/josh-commands-run.md` →
-"`josh run:carry`".
+the next session resumes the invocation from the carry record (`backlogrun-progress.md` → "The
+hand-off"), which keeps the invocation string, `--only` and the named list; it runs `remaining` from
+`--json` (`docs/josh-commands-run.md` → "`josh run:carry`").
 
 ```bash
 pnpm josh run:carry --begin "backlogrun --max 5 --idle 30" --owner "$PPID"
@@ -64,9 +64,9 @@ pnpm josh run:carry --json                                                   # r
 pnpm josh run:wake --start                                                   # same turn as --begin; `running` under `josh backlogrun`
 ```
 
-**Always pass `--owner "$PPID"`**, and ask it before the plan, in the same turn as the first `pnpm josh
-ms`. **The record is the parent loop's, and a lane never touches it**; count into it with `--merged <N>`
-and `--filed 1`, and **`--cut` is the session's last write**.
+**Always pass `--owner "$PPID"`**, before the plan, in the same turn as the first `pnpm josh ms`. **The
+record is the parent loop's; a lane never touches it**. Count with `--merged <N>` and `--filed 1`;
+**`--cut` is the session's last write**.
 
 | It answers | What the run does |
 | --- | --- |
@@ -85,30 +85,27 @@ named epic's children", never the root as a standalone `fullrun`, then ask `pnpm
 a child number or `complete` continues; only `stop` or a failure records `pnpm josh run:carry --done <E>
 --owner "$PPID"`.
 
-**A person keeps control of the run** — `pnpm josh run:wake --list` reads it, `pnpm josh backlogrun
---stop` stops it (`docs/josh-commands.md` → "`josh backlogrun`").
-
-Rationale: `docs/maintainers/backlogrun-steps-rationale.md` → "Why a session cut does not end the run"
+**A person keeps control** — `pnpm josh run:wake --list` reads it, `pnpm josh backlogrun --stop` stops
+it (`docs/josh-commands.md` → "`josh backlogrun`").
 
 ## The plan, before the first child starts
 
 **Report the plan before anything is dispatched. The plan is one command's output** — `pnpm josh
-backlog:plan`, rendered from the same
-pool `backlog:next` answers from. Report all four of its sections (Ready now, Waiting, Waiting on a
-person, Out of scope) to the person in the session language, with any truncated-listing `⚠`.
+backlog:plan`, from the pool `backlog:next` answers from. Report all four sections (Ready now, Waiting,
+Waiting on a person, Out of scope) in the session language, with any truncated-listing `⚠`.
 
 ### Resolve what the plan can resolve, before starting
 
 **Settle every `needs-decision` issue the plan listed in one pass**, from one `pnpm josh issue:read <N>
-<N> …` call (body and comments, `issue-comments.md`):
+<N> …` call (`issue-comments.md`):
 
 - **An answer already in the issue** — record it as a comment and **remove the label** (Tier A).
   **Never measure in order to decide**: a question needing a benchmark or a run stays labelled.
 - **A person's judgement** — apply `needs-decision` (`backlogrun-park.md` → "Only a person's judgement
-  carries `needs-decision`"); the next plan classifies it by the label alone.
-- **Order and isolate** — a native `blocked-by` where one must land first;
-  `run:solo` on all three `backlogrun-lanes.md` → "A solo run" conditions, **every other one `run:lane`**,
-  commenting the reason.
+  carries `needs-decision`").
+- **Order and isolate** — a native `blocked-by` where one must land first; `run:solo` on all three
+  `backlogrun-lanes.md` → "A solo run" conditions, **every other one `run:lane`**, commenting the
+  reason.
 - **`priority:high`** only on a cited ground (a stated deadline, a person's written policy), commented;
   **never remove it**.
 - **Report `pnpm josh backlog:plan --waves`** with the plan, never an order derived by hand; then start
@@ -116,9 +113,7 @@ person, Out of scope) to the person in the session language, with any truncated-
 
 **`needs-decision`, `run:solo`, `run:lane` and `priority:high` are the only workflow labels a run
 applies by hand** — never `needs-human-review` (`needs-human-review.md`), and `auto-ok` only through
-`pnpm josh issue:file` or `pnpm josh auto-ok:judge`, which check the exclusions first.
-
-Rationale: `docs/maintainers/backlogrun-steps-rationale.md` → "Why the plan and the decision pass come first"
+`pnpm josh issue:file` or `pnpm josh auto-ok:judge`.
 
 ## The loop
 
@@ -140,11 +135,7 @@ section the row names:
 | `window` | Hand the loop back as is | — |
 
 **A candidate only in another repository is never a token** — report it with its checkout. The budgets,
-verdicts and stops are the driver's own: `docs/maintainers/backlogrun-driver.md` (rationale:
-`docs/maintainers/backlogrun-steps-rationale.md` → "Why the idle watch lasts 8 hours from when the hands became free";
-`docs/maintainers/backlogrun-steps-rationale.md` → "Why the cost check skips a watch").
-
-Rationale: `docs/maintainers/backlogrun-steps-rationale.md` → "Why the loop's contract is shaped this way"
+verdicts and stops are the driver's own: `docs/maintainers/backlogrun-driver.md`.
 
 ## What runs once per session, not once per issue
 

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

@@ -58,42 +58,32 @@ These are the gate → review → PR → merge facts other documents cite; this
 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. 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. 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 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. 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.
-- **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.
-- **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.
-- **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.
+- **The gate runs beside this review, not in front of it** — started with the review, joined before the
+  commit. A red gate is fixed and re-run whatever the review concluded.
+- **origin/main is merged in before the gate** — `pnpm josh main:merge` is the last edit, so the scoped
+  pair and the gate run once over it; a conflict fires `backlogrun-recovery.md` → "Conflicts are not
+  predicted" early. **This is the one place a conflicted merge's procedure is written**: `main:merge`
+  refuses when uncommitted changes touch a path the default branch also changed, or the index holds
+  unresolved or staged paths — commit first with `pnpm josh git -y`, rerun, and **never stash around the
+  merge**. A merge stopped on a conflict: remove the markers, then `pnpm josh git -y` stages the
+  resolution and records the merge commit — **Tier A**; a lane child never asks a person for `git add`.
+- **A single check answers once per tree** — re-run one check by name (`pnpm josh lint:related`,
+  `pnpm josh cspell:dot`, `pnpm josh test:related`, or the type check) after every edit, never twice
+  over an untouched tree. In kit a detached `pnpm josh ship` also checks the metrics totals; accept a
+  grown total with its reason, as its output names.
+- **The pull request opens between the rounds, so CI runs beside round 2** — round 1 runs on the
+  uncommitted tree and its High/Medium fixes land before the commit; the verification pass runs against
+  the open pull request.
+- **The round-2 fix commit is pushed before its gate** — `pnpm josh git -y` again, so the gate runs
+  inside the CI wait and is joined before `pnpm josh followup`.
+- **A clean second round issues the merge in the same turn** — `pnpm josh followup`, after any branch-2
+  filing and `pnpm josh epic:bundle`. Clean: no confirmed High standing, nothing routed to branch 1.
+- **The review runs in a subagent, never a main-line skill load** — `/code-review` through the `Agent`
+  tool, 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:brief` prints the checkout root, branch, 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.
+  before anything acts on the verdict.
 
 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/followup.md

@@ -1,10 +1,9 @@
 # Finishing a run — `pnpm josh followup`
 
 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. Where each rule came from: `docs/maintainers/followup-rationale.md` → "Where each rule
-came from".
+the reviewer scan, the config report and the release ask. `fullrun` and `backlogrun` end here; `halfrun`
+stops before the commit. This file is the single source. Where each rule came from:
+`docs/maintainers/followup-rationale.md` → "Where each rule came from".
 
 ## Run `pnpm josh followup`
 
@@ -20,85 +19,75 @@ 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) 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) runs only the post-merge tail; a report already on the
+Issue is not posted 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`.
-Bypassing the check is Tier C — only on explicit user instruction, and only when the stated window is
-impractically long or the retrigger is rate-limited again.
+**A red rate-limited CodeRabbit check is cleared by a retrigger, not a bypass.** Wait out the stated
+window, post `@coderabbitai review` on the pull request, and rerun `followup`. Bypassing is Tier C — on
+explicit user instruction only, when the window is impractically long or the retrigger is rate-limited
+again.
 
-A pre-merge failure stops the run; an unverifiable AI finding or CI failure needing input receives a
-`confirmation` Telegram. Post-merge cleanup failures are named and do not undo the merge; run the
-named recovery without rerunning it. Because notification precedes merge, the printed result is
-authoritative.
+A pre-merge failure stops the run; an unverifiable AI finding or CI failure needing input sends a
+`confirmation` Telegram. A post-merge cleanup failure is named and does not undo the merge; run the
+named recovery without rerunning `followup`. The printed result is authoritative.
 
-After success, run `pnpm josh ms`; in a lane its refusal is expected and the parent uses
-`pnpm josh lane:close <N>`. Never delete the branch unless requested. The sections below are read
-after execution, when its output needs reading.
+After success, run `pnpm josh ms`; in a lane it refuses and the parent uses `pnpm josh lane:close <N>`.
+Never delete the branch unless requested. The sections below are read when the output needs reading.
 
 ## The options
 
 | Option | What it is |
 | --- | --- |
-| `--no-merge` | **The only flag that stops the merge** — leave it out and the command merges |
-| `--notify-target` | `pr` \| `issue` \| `both`, defaulting to `issue`. **Keep the default** — the workflow puts no completion report on the pull request |
-| `--notify-message` / `--notify-message-file` | The completion comment body in the two-layer report shape — `Cause: / Fix: / Result:`, then `Details:` bullets, never a bare `Added … / Changed …` list. **Use the file form whenever the report names a command or a path** (`prompts/collaboration-workflow/shell-body.md`); `-` reads stdin |
-| `--coderabbit-ignore-reason` | The reason comment for leaving CodeRabbit line comments unresolved |
-| `--ai-review-ignore-reason` | The reason comment for leaving an AI-review blocker (Claude Review / a CodeRabbit summary) unresolved |
-| `--issue-number` | The Issue number — or give it positionally as `"<title> #<number>"`; with neither, the PR body's `closes #N` supplies it |
+| `--no-merge` | **The only flag that stops the merge** |
+| `--notify-target` | `pr` \| `issue` \| `both`, default `issue`. **Keep the default** |
+| `--notify-message` / `--notify-message-file` | The completion comment in the two-layer shape — `Cause: / Fix: / Result:`, then `Details:` bullets, never a bare `Added … / Changed …` list. **Use the file form whenever the report names a command or a path** (`prompts/collaboration-workflow/shell-body.md`); `-` reads stdin |
+| `--coderabbit-ignore-reason` | Why CodeRabbit line comments stay unresolved |
+| `--ai-review-ignore-reason` | Why an AI-review blocker (Claude Review / a CodeRabbit summary) stays unresolved |
+| `--issue-number` | The Issue number — or positionally as `"<title> #<number>"`; with neither, the PR body's `closes #N` |
 
 ## `auto-merge` — Default `fullrun` behavior
 
-Invoking `fullrun` is itself the explicit authorization to merge; the user adds no keyword.
+Invoking `fullrun` is itself the explicit authorization to merge.
 
-- **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**:
-  `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.
+- **Always run `pnpm josh ms` after a successful merge**. **In a lane, `pnpm josh lane:close <N>` is the
+  terminal step instead** — `josh ms` refuses there.
+- **Green CI is not authorization to merge while AI review findings are open.** A blocker sends a
+  `confirmation` Telegram and exits non-zero — fix and re-run. SonarCloud is carried by the required
+  `SonarQube` check.
 - **Verify a CodeRabbit finding before bypassing it.** Never pass `--coderabbit-ignore-reason`
   reflexively: a SHA pin flagged "not matching the tag" is checked with `gh api
   repos/<owner>/<repo>/commits/<tag> --jq '.sha'`, and the bypass cites that command.
-- **The merge is `followup`'s, not yours** — it calls the REST merge endpoint from inside a node
-  script, and `.claude/settings.json` refuses `gh pr merge` and its `gh api` spellings (`CLAUDE.md` →
-  "Git Rules"). Do **not** pass `--delete-branch` unless the user asks.
+- **The merge is `followup`'s, not yours** — `.claude/settings.json` refuses `gh pr merge` and its
+  `gh api` spellings (`CLAUDE.md` → "Git Rules"). Do **not** pass `--delete-branch` unless asked.
 - **A failed merge** (branch protection, a conflict) is reported and stops the run — never retried with
-  other flags or past a protection. To skip the merge, use `kickoff` or say "do not merge" in the same
-  turn and pass `--no-merge`.
+  other flags. To skip the merge, use `kickoff` or say "do not merge" in the same turn and pass
+  `--no-merge`.
 
 ## Completion notifications: always via `pnpm josh followup`
 
-**Never send a `completion` Telegram with `pnpm josh notify`** — `followup` sends it with the PR URL,
-which the manual CLI does not fill in. `pnpm josh notify` stays the tool for `planning`,
-`confirmation`, `kickoff_retry` and `failure`. **It fires before the merge**, so a received ✅ is not
-proof the PR merged — read what the command printed; a silent run is a failed run.
+**Never send a `completion` Telegram with `pnpm josh notify`** — `followup` fills in the PR URL.
+`pnpm josh notify` stays the tool for `planning`, `confirmation`, `kickoff_retry` and `failure`. **It
+fires before the merge**, so a ✅ is not proof the PR merged — read what the command printed.
 
-**Always run it in the foreground** — the deliberate exception to `background-commands.md`, because
-nearly every later step reads its result. The CI wait defaults to 32 minutes, so give the call the
-largest timeout it accepts (`timeout: 600000` in Claude Code). Where the harness detaches an
-over-running command, wait for its report; where it kills the call, set `JOSH_CI_TIMEOUT_SECONDS` to fit
-and re-run once CI has settled. Re-run it after every follow-up commit.
+**Always run it in the foreground** — the exception to `background-commands.md`. The CI wait defaults
+to 32 minutes; give the call the largest timeout it accepts (`timeout: 600000` in Claude Code). Where the
+harness detaches the call, wait for its report; where it kills it, set `JOSH_CI_TIMEOUT_SECONDS` and
+re-run once CI has settled. Re-run after every follow-up commit.
 
 **The count of unreleased merges is surfaced at completion — not a version.** It prints `🚚 unreleased
-merges on main: <n>` and puts the count in the Telegram. **Do not report a shipped version**: a child
-no longer bumps, so `package.json` names the previous release. What the run does about it is "When
-`pnpm josh release` runs" below.
+merges on main: <n>`. **Do not report a shipped version** — a child no longer bumps. See "When `pnpm
+josh release` runs" below.
 
 ## Reading the stage-timing block
 
-The command closes with one `followup stage: <name> <seconds>` row per stage and a
-`followup stages total:` line, so where it spent its time is read, not guessed.
+One `followup stage: <name> <seconds>` row per stage, then `followup stages total:`.
 
-- **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 failed run prints it too**, up to the stage that threw, named `interrupted`. The `merge` row
+  appears only on a run that merged.
 - **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.
+  overlapped.
+- **The total is the sum of the stages**, not the wall clock — the post-merge tail sits outside it.
 
 A `failure` Telegram is sent **by hand, exactly once**, and only when recovery is given up:
 
@@ -108,36 +97,30 @@ pnpm josh notify --task-type failure --issue-url "<issue-url>" --body-file <reas
 
 ## AI reviewer comment scan
 
-`followup` scans top-level PR comments from AI reviewers **independently of CI status**, so a finding
-posted after CI goes green is not silently shipped.
+`followup` scans top-level PR comments from AI reviewers **independently of CI status**.
 
 - **Blockers are structural, not NLP**: a Claude Review body with `### Issues`, `### Problem`,
   `#### Logic bug` or a numbered `### 1. …` heading; a CodeRabbit `Actionable comments posted: N` with
   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** — never an empty listing that
-  passes.
+  non-zero; with it, the reason is posted and the run proceeds.
+- **A comment listing that could not be read is a standing blocker**.
 - **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. When it is reverted:
+  (restore via `JOSH_REQUIRED_CHECKS`); its findings are audit notes. Reverting it:
   `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. **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.
+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.
 
 ## When `pnpm josh release` runs
 
-**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
-checkout, after the last lane is closed.
+**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.
+With lanes the parent asks it, in the primary checkout, after the last lane is closed.
 
 ```bash
 pnpm josh release:scope          # → required | skip | unknown
@@ -149,11 +132,9 @@ pnpm josh release:scope          # → required | skip | unknown
 | `skip`     | the count is zero — nothing is waiting to ship                   | Say so in one line and finish                                                     |
 | `unknown`  | the count could not be read                                      | **Report it as `unknown`** — it is never read as `skip`                           |
 
-**The run never types `pnpm josh release` itself.** It opens and merges a PR of its own and starts
-the tag → publish → `production` chain — outward-facing and effectively irreversible, so Tier C.
-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.
+**The run never types `pnpm josh release` itself** — it starts the tag → publish → `production` chain,
+outward-facing and effectively irreversible, so Tier C. A person types it in the primary checkout, on
+the default branch, with a clean tree.
 
 **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

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

@@ -35,7 +35,8 @@ 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
 followup "<title> #<N>" --notify-message "Implemented <title>\\nCause: ...\\nFix: ...\\nResult:
-...\\n\\nDetails:\\n- <change1>"'`. The stop report names the same two, in the same order.
+...\\n\\nDetails:\\n- <change1>"' --recommended "Verify by hand, then prrun #<N>" --alternative "fullrun
+#<N>"`. The stop report names the same two, in the same order.
 **Invoking `halfrun` is _not_ authorization to commit, push, or merge** — do not run `pnpm josh git -y` or `pnpm josh followup` yourself. If the user comes
 back with fixes, treat each as a new round: implement, re-run `pnpm josh gate`, send another
 `confirmation` Telegram, stop again.