@joshuafolkken/kit 1.872.0

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

@@ -0,0 +1,109 @@
+# `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).
+
+**`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`
+plus every child of an epic whose root carries it, ordered by dependency and grouped into waves. With
+`#N1 #N2 …` it runs those named items in the order they were typed, one at a time, and **then** drains
+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).
+
+**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
+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.
+
+## Explicit invocation required (MANDATORY)
+
+**Never start a `backlogrun` unless the user has typed the keyword in the current turn's prompt.**
+This is the same rule the other entry points carry, at the same strength — `SKILL.md` → §0 is its
+single source, and `CLAUDE.md` → "Explicit invocation required (MANDATORY)" is where it stays resident
+so it binds on a turn where nothing here has been read. It matters more here than anywhere else,
+because this is the entry point with the widest authorization: a conversational "clear the backlog" is
+**not** an invocation, a confirmation question is no substitute for the keyword, and an earlier turn's
+authorization does not carry.
+
+**The keystroke starts the invocation; it does not have to land in every session that invocation
+spans.** A `backlogrun` cut mid-run and resumed is still that one invocation
+(`backlogrun-steps.md` → "The session cut is inside the invocation"). This reading covers `backlogrun`
+and it alone — a `fullrun` cut still waits for the keyword.
+
+## 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.
+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` is a person's alone.
+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. `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 the answer-to-word mapping, "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 |
+| `backlogrun-progress.md` | starting the progress watcher (`pnpm josh run:progress --wait`) and the hand-off check at a merge (`pnpm josh cost --cut`) | the heartbeat, 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 |
+
+## Guards
+
+| Guard | Limit | On reaching it |
+| --- | --- | --- |
+| Children per run | 30 | Stop and report; an epic this large should be split. |
+| Issues filed per run | 10 | Stop and report; a run filing more than this has lost the plot. |
+| Consecutive child failures | 3 | Stop and report; something is wrong with the environment, not the children. |
+
+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.

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

@@ -0,0 +1,98 @@
+# `/code-review` → `followup` chain rule (MANDATORY)
+
+## Run the review-to-merge chain
+
+This is the execution contract for `fullrun` and `backlogrun`; 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
+   "<title> #<N>"` (`--cite <N>`), then **end the turn** on `launched`/`busy`. A stop relaunches a child
+   whose `run:step` names `ship --log <N>`: fix, re-detach (`--review` only if no round is recorded,
+   else step 4). `failed` → step 1.
+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).
+   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
+   and gate. Never version-bump a child (`pnpm josh release` decides).
+3. Before acting on any review round, run `pnpm josh review:attest --check`. `missing` or `mismatch`
+   discards it without counting; rerun against the brief's checkout. A review error receives a
+   `confirmation` Telegram and stops.
+4. Route the attested verdict mechanically:
+   - Clean or Low-only round 1: no second round. Fix, file, or drop each Low with a one-line reason.
+   - High/Medium round 1: fix it, then ask `pnpm josh review:round2 --round-1-closed`. On `skip`, record
+     the skip on the Issue. On `required`, open the PR first and run the verification pass from
+     `pnpm josh review:brief --round 2` beside CI.
+   - Round 2 is final. Fix a branch-1 finding, run its scoped check, push it, then run the gate. Dispose
+     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.
+   **`pnpm josh followup` refuses the merge until the round is recorded**
+   (`pnpm josh review:record --check --issue <N>`, joshuafolkken/kit#2343).
+5. **The clean path ships in one call** — with no second round due, background
+   `pnpm josh ship "<title> #<N>" --body-file <evidence.md>`: gate → `git -y` → foreground `followup` → `run:tail`, stopping at the
+   first failure (joshuafolkken/kit#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`.
+
+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
+CodeRabbit/Claude Review finding or a CI failure. In a lane `josh ms` refuses; the parent closes it. Managed config claims are reported by `followup` and do not stop the merge.
+
+Recommendations are informational; severity decides. A CodeRabbit rate-limit warning is not a finding.
+
+## 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.
+
+- **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).
+- **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-lanes.md` → "Conflicts are not predicted"
+  early. **This is the one place a conflicted merge's procedure is written** (joshuafolkken/kit#2445):
+  `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.
+- **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).
+- **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).
+- **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.
+- **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 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 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).
+
+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/delegation.md

@@ -0,0 +1,52 @@
+# Delegation decisions — `SKILL.md` §2b's procedure
+
+Read this file when the first delegation decision arises during a run, not at workflow entry.
+
+Designing, assessing a split and reviewing are judgement; applying a fix the gate has already named is
+not. The steps whose answer is already decided go to a cheaper execution tier, and the judgement stays
+where it is.
+
+**Ask before delegating any step of a run**, and use what it answers:
+
+```bash
+pnpm josh delegate <step>   # → delegate | keep ; the reason on stderr
+pnpm josh delegate --list   # the enumeration, and what was rejected and why
+```
+
+**Never decide it yourself. Anything not on the list is `keep`.** A step earns its place by naming
+**how a wrong result is caught** cheaply in the parent tier, not merely by being unlikely to fail.
+`pnpm josh delegate --list` names both delegatable and rejected steps; a rejected step either has no
+verifier or lets a wrong result propagate too far. The command distinguishes `kept deliberately`
+from `kept by default`. `docs/josh-commands.md` → "`josh delegate`" carries the full enumeration.
+
+**The mechanism is not the unit.** `pnpm josh delegate` covers a run step, a file-disjoint Step 0
+implementation unit (`pnpm josh fanout`), and `epic-child` — an epic's child and a named issue of a
+`backlogrun` alike. Do not add a second batch-child mechanism. Read `backlogrun-child.md` → "Each child
+runs in a delegated unit" at child dispatch; `backlogrun-steps.md` → "Named issues run first, in order"
+applies to named issues. `docs/josh-commands.md` → "`josh fanout`" carries file-disjoint dispatch.
+
+**`followup-filing` delegates the late review-finding filing chain** with the parent's finding text;
+the parent verifies the new Issue using `pnpm josh issue:state <new>`. For `epic-child`, the parent
+likewise verifies `pnpm josh issue:state <N>` after the unit returns. Read `human_review:` too: an open
+`needs-human-review` child is the authorized stop (`SKILL.md` → §2z), not a failed child. The per-entry
+classification lives in `backlogrun-child.md` → "Each child runs in a delegated unit".
+
+## The pre-implementation reading — what goes to a unit, and from which file
+
+**Delegate reading that explains the Issue's subject; keep reading files this run will edit in the
+main line.** The unit returns conclusions with `file:line` citations, never the file text. It may run
+a temporary probe script and return its output.
+
+**The threshold is 3 files, and it is a count, not a forecast.** When the next read reaches it,
+delegate the unread investigation. Brief the unit on what was already read; do not re-read it there.
+**A delegation resets the counter rather than spending it**; `pnpm josh investigation:guard` counts
+unedited files and refuses the threshold read. `pnpm josh delegate --list` prints the threshold.
+`docs/josh-commands.md` → "`josh investigation:guard`" carries the command's counting details.
+
+**The main line does not idle while the unit reads:** read files this run will edit, then verify the
+unit's cited lines. Independent investigations launch together; a brief that needs another unit's
+answer waits for that answer.
+
+**When the Issue already names the file, function or rule, read that edit target in the main line.**
+It is not `survey`, and it is not `diagnosis`: the unit describes how the subject works;
+the main line decides what that means and what to change.

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

@@ -0,0 +1,118 @@
+# `pnpm josh followup` — the post-execution reference
+
+The parts of the `followup` procedure a run reaches **after** it has issued `pnpm josh followup`: how
+to read the stage-timing block the command prints, the AI-reviewer comment scan and the config-file
+report it runs, and the release ask that closes the completion summary. `followup.md` carries what a
+run needs **before** it issues the command and points here for the rest, so the read that lands in the
+turn that issues `pnpm josh followup` stays small (joshuafolkken/kit#1905).
+
+This file is the single source of the sections below; `followup.md`, `fullrun.md`, `backlogrun.md` and
+`backlogrun.md` point here rather than restating them.
+
+## Reading the stage-timing block
+
+### It prints how long each of those stages took
+
+Since joshuafolkken/kit#1349 the command closes with one row per stage and a total, so "where did
+`followup` spend its time" is read rather than guessed. The shape, with illustrative durations:
+
+```
+followup stage: closes-and-context        2.1 s
+followup stage: checks-wait               28.4 s
+followup stage: coderabbit-comments       1.3 s
+followup stage: ai-review-comments        2.0 s
+followup stage: telegram                  1.1 s
+followup stage: merge                     2.6 s
+followup stage: completion-and-epic-close 1.4 s
+followup stages total:                    38.9 s
+```
+
+- **The block is printed on a failed run too**, up to and including the stage that threw, which is
+  named `interrupted`. A `followup` that exits non-zero on an AI-review blocker or a red check is the
+  invocation whose wait was longest, and one that printed nothing would leave the measurement blind to
+  exactly those. **A short block there is the run stopping early, not the printer breaking**: the
+  stages after the failure never ran, so they have no duration to report.
+- **The `merge` row appears only on a run that merged**, so a `--no-merge` block is a row shorter.
+- **Two rows say `and` because the requests behind them go out together** (joshuafolkken/kit#1446).
+  `closes-and-context` is the former `closes-check` plus `context` — the pull request body, the
+  repository name, the pull request URL and the issue title, four reads that need nothing from one
+  another; `completion-and-epic-close` is the former `completion-comment` plus `epic-close`. A lap
+  records an interval rather than a call, so a batch is one row, and the name is what says which
+  stages it holds. **The one dependency inside the batch is kept**: with no issue number on the
+  command line the title read waits for the body that names it, and only that read waits.
+  **`checks-wait` is untouched**, which is the point — what was overlapped was never a wait.
+- **The total is the sum of the stages, not the command's whole wall clock.** What sits outside it is
+  the tail the workflow script runs afterwards — the review-record clears, the hold
+  release, the next-issue listing and the version line — so a run-timing reading of the same
+  span is longer, and that gap is the tail. It is normally a second or two.
+- **What was measured is on joshuafolkken/kit#1349**, and cutting any of it is deliberately not this
+  block's business: the required-check wait and the AI-review scan are the merge gate, and narrowing
+  either to make a number smaller is the workaround `CLAUDE.md` prohibits.
+
+A `failure` Telegram is sent **by hand, exactly once**, and only when the agent has finally given up
+recovering — never once per retry:
+
+```bash
+pnpm josh notify --task-type failure --issue-url "<issue-url>" --body "<the reason and what is unresolved>"
+```
+
+## AI reviewer comment scan (automatic in `pnpm josh followup`)
+
+`pnpm josh followup` scans top-level PR comments from AI reviewers (Claude Review, CodeRabbit summary comments) **independently of CI status**. This scan runs after CI is green and after the existing CodeRabbit line-comment check. The goal is to ensure substantive findings posted by AI reviewers _after_ CI goes green are not silently shipped.
+
+**Temporary (kit#753)**: while CodeRabbit reviews are slow, CodeRabbit is non-blocking end to end — it is excluded from the default required checks (restore via `JOSH_REQUIRED_CHECKS`), `Actionable comments posted: N` is downgraded to an informational log, and unresolved CodeRabbit line comments no longer require an ignore reason. Every skip is printed to the console and appended to the completion Telegram body. Claude Review blockers are unchanged. Revert together with kit#752.
+
+- Blocker heuristics (conservative, structural — not NLP):
+  - **Claude Review** (`author.login = claude`): body contains `### Issues`, `### Problem`, `#### Logic bug`, or a numbered finding heading like `### 1. ...`
+  - **CodeRabbit** (`author.login = coderabbitai` / `coderabbitai[bot]`): body contains `Actionable comments posted: N` with N > 0. Rate-limit notices (`rate limited by coderabbit.ai` / `Rate limit exceeded`) and "No actionable comments" summaries are ignored.
+- If blockers exist and **no** ignore reason is supplied: `pnpm josh followup` sends a `confirmation` Telegram and exits non-zero. Fix the findings (or provide an ignore reason) and re-run.
+- If blockers exist and `--ai-review-ignore-reason "<reason>"` is supplied: the workflow posts an ignore-reason comment to the PR (mirroring the CodeRabbit ignore-reason flow) and proceeds to completion.
+- Acknowledgment-only Claude comments (`All issues resolved ✓`, `Everything else looks good`) do not match the blocker heuristics, so rounds where the AI reviewer explicitly signs off do not trigger a false positive.
+- **A comment listing that could not be read is treated exactly like a standing blocker.** A rate limit, expired auth, a dropped connection — every one of them used to arrive as an empty listing, so the gate passed without having read anything (joshuafolkken/kit#973). `confirmation` Telegram, non-zero exit, re-run once the read succeeds. `--ai-review-ignore-reason` still gets past it, because what it means is unchanged: a person has looked — and the run then carries an audit note saying the scan was bypassed.
+- **The CodeRabbit line-comment listing is the exception**: unreadable there is reported as an audit note rather than blocking, because kit#753 has CodeRabbit not blocking the merge at all. That reader also answers unreadable when the PR number itself would not resolve, which the top-level scan never has to do. Revert with kit#752.
+
+## Config file reporting (inside `pnpm josh followup`)
+
+**Nothing here asks you to compare anything by eye** (joshuafolkken/kit#1578). `pnpm josh followup` reads the tracked branch diff itself and matches every changed path against everything `josh sync` distributes — the three lists `AI_COPY_FILES`, `AI_COPY_FILE_MAPPINGS`, `AI_COPY_DIRECTORIES`, plus `SYNCED_PATHS`, the destinations `sync` writes directly (`playwright.config.ts`, `eslint.config.js`, the rest).
+
+**It stops nothing** (joshuafolkken/kit#1592). What it produces is a report: the claimed paths and the list that claimed each one go into **the completion notification and the completion report on the Issue**, and the run continues to the CI wait and the merge exactly as a run that distributes nothing does. A run passing `--no-merge` is not reported on, because nothing has been distributed yet.
+
+**It was a confirmation stop until joshuafolkken/kit#1592, and measurement is what removed it rather than preference.** In kit the condition is nearly always true, because kit is the distribution source: every change to `CLAUDE.md`, to `prompts/`, to `.claude/skills/` or to the distributed part of `docs/` is by definition a change to a distributed path. Measured on `epicrun #1413`, **two of three children stopped here** — and in both, the distributed file was the one that child's own acceptance criteria had ordered changed. The gate was not catching an unintended edit; it was stopping the work, and ending unattended execution until a person retyped one command.
+
+**There is deliberately no branch on which repository this is.** Stopping in a consumer project — where editing a distributed file really is the mistake `CLAUDE.md` → "Route distributed-doc / config changes upstream to kit" names, since the next `josh sync` overwrites it silently — while staying quiet in kit was weighed and rejected on joshuafolkken/kit#1592: it needs a distribution-source test this package does not have, no case is recorded of the gate having saved a consumer's work, and the report below reaches a consumer's reader just as well.
+
+**The matching itself is unchanged, and so is the reason it is mechanical.** The instruction the mechanical read replaced was skipped in two runs out of three on the day it was measured, and one of those two could not have succeeded by eye at all: `AI_COPY_DIRECTORIES` holds directories, so a distributed path such as `.claude/skills/workflow-commands/backlogrun.md` appears in no list textually.
+
+```bash
+pnpm josh sync:scope    # managed | clean, naming which list claimed each path; alias: josh sys
+```
+
+- **There is no flag to pass and nothing to approve.** `--managed-config-ignore-reason` is gone with the stop it existed to get past.
+- This report is produced independently of AI reviewer comment scanning, which still stops the run on a standing blocker
+
+## When `pnpm josh release` runs
+
+**The release point is a position plus a command's answer, never a judgement** (joshuafolkken/kit#1582). joshuafolkken/kit#1169 took the version off the branch and put it behind one command a person types; nothing said *when* to type it, and because nothing fails when nobody does — CI green, every pull request merged, every Issue closed — 53 merges reached main unreleased and no consumer of this package saw one of them.
+
+**The position: once per invocation, after the last merge.** Ask when `pnpm josh followup` has merged the last pull request *this invocation* authorized — 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. Asked per child it would cut a release in the middle of a batch whose remaining children are still moving main.
+
+**The answer: `pnpm josh release:scope`.**
+
+```bash
+pnpm josh release:scope          # → required | skip | unknown ; alias: josh res
+pnpm josh release:scope --json   # the same answer as one JSON object
+```
+
+| It answers | What it means                                                    | What the run does                                                               |
+| ---------- | ---------------------------------------------------------------- | --------------------------------------------------------------------------------- |
+| `required` | main has taken at least one merge since the version last changed | Close the completion report with the release request, naming `pnpm josh release` |
+| `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 threshold is one, and that is deliberate.** joshuafolkken/kit#1582's own complaint is that accumulating makes a single version larger and its contents harder to trace afterwards, so a release per invocation is the cadence rather than a compromise — and it is the cadence that already held while every child bumped, before joshuafolkken/kit#1486 removed that. What keeps it from firing per child is the position above, not a larger number.
+
+**The run never types `pnpm josh release` itself.** That command opens a pull request of its own, merges it, and starts the tag → publish → `production` chain: outward-facing and effectively irreversible, so it is Tier C (`CLAUDE.md` → "Decision autonomy"). Typing `fullrun` authorizes merging *this Issue's* pull request and nothing past it. On `required` the run reports the request as its closing line and stops there; a person types the command in the primary checkout, on the default branch, with a clean tree.
+
+**`pnpm josh release --dry-run` was checked first and does not answer this.** It refuses off the default branch and on a dirty working tree, and it counts against `HEAD` rather than `origin/<default>` — and every position above is a feature branch or a lane, which is exactly where it throws. So `release:scope` adds **no counting of its own**: it reads `git_followup_pending.read_pending`, the same fetch-then-count `pnpm josh followup` already uses for the Telegram line, and the two therefore cannot disagree.
+
+**This section is the single source.** `fullrun.md`, `backlogrun.md` and `backlogrun.md` point here rather than restating it, and `docs/josh-commands.md` → "`josh release:scope`" documents the command itself.

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

@@ -0,0 +1,222 @@
+# Finishing a run — `pnpm josh followup`
+
+Everything between a green CI and a merged PR: what `followup` scans for, the gate that stops a run,
+how auto-merge is authorized, and the Telegram notifications. `fullrun` and `backlogrun` both end here;
+`halfrun` never reaches this file, because it stops before the commit.
+
+This file is the single source of the rule.
+
+## Run `pnpm josh followup`
+
+Run it in the foreground after `pnpm josh git` and after every required review disposition:
+
+```bash
+pnpm josh followup "<title> #<N>" --notify-message-file <report-file>
+```
+
+The report uses the session language: plain `Cause:`, `Fix:` and `Result:` lines, then `Details:`
+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. Keep the
+default Issue target. Ignore a finding only after verifying it is inapplicable; rate-limit text is not
+a finding.
+
+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.
+
+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. Read
+`followup-reference.md` after execution for timing output, reviewer-scan details, config claims and the
+release ask.
+
+## Command stages and options — reference
+
+`pnpm josh followup` is a **separate script run after `pnpm josh git`**, not a stage inside it. The
+commit and the pull request come first; this is everything after them.
+
+What one invocation does, in order:
+
+- **Waits for the CI status checks — the required ones only.** A non-required check (CodeQL, Workers
+  Builds) is never waited on. A non-required check that failed is still reported to the user
+  (`prompts/collaboration-workflow/operating-rules.md` → "CI チェック失敗時の対応").
+- **Checks unresolved CodeRabbit line comments**, posting the ignore-reason comment when one is
+  supplied.
+- **Scans the AI reviewers' top-level comments** — run independently of CI status.
+- **Sends the `completion` Telegram (✅) itself**, once every gate above has passed. A CI failure or an
+  exception is re-thrown as-is with **no** Telegram sent — so a silent run is a failed run. **It fires
+  before the merge, not after it**: a merge rejected by branch protection or a conflict leaves the ✅
+  already sent, so never read a received completion Telegram as proof the pull request merged — read
+  what the command printed.
+- **Merges** — unless `--no-merge` was passed. **Merging is the default**, and `--merge` is a
+  deprecated no-op. `--no-merge` is the only thing that stops it.
+- **Posts the completion report to the Issue**, after the merge: it edits the Issue body when the body
+  is empty, and adds a comment when it already has content. The report never goes to the pull request.
+  A run that stopped at the merge therefore has no Issue comment, and the missing comment is what a
+  failed merge looks like from GitHub.
+- **Closes the epics the Issue completes**, on a merged run only.
+- **Takes the `in-progress` label back off the Issue**, on a merged run only. A run that merged nothing
+  keeps it. The removal reads the Issue's labels and sends back the spelling GitHub stored, so an
+  `In-Progress` repository is not missed, and an Issue that never carried the label is never written to.
+- **Nothing after the merge can end the run.** Once the pull request has merged, every remaining step —
+  the Issue comment, the epic close, the review records and the working-tree hold
+  release — runs on its own: one that fails is reported by name, with the command that finishes it by
+  hand where one exists (`pnpm josh run:release --force` for the hold; `gh pr comment` or `gh api …
+  /comments` for the completion report). Before the merge nothing changes: a failure there still ends
+  the run, because re-running the command is the whole recovery. **A reported cleanup failure is not a
+  merge failure**: read the ⚠ lines, run what they name, and do not re-run the merge.
+- **Recovers the issue number from the pull request body** when the invocation named none: the `closes
+  #N` keyword supplies it.
+### The post-execution reference is in `followup-reference.md`
+
+Everything the run reaches **after** it issues `pnpm josh followup` is in `followup-reference.md`, so
+the read that lands in the turn that issues the command stays small: the per-stage timing block the
+command prints and how to read it, the `failure` Telegram sent by hand when recovery is given up, the
+AI-reviewer comment scan, the config-file report, and the release ask that closes the completion
+summary. What stays below is what a run needs **before** it issues the command.
+
+### The options
+
+| Option | What it is |
+| --- | --- |
+| `--no-merge` | **The only flag that stops the merge.** Merging is the default; `--merge` is a deprecated no-op |
+| `--notify-target` | `pr` \| `issue` \| `both`, defaulting to `issue`. **Keep the default** — the workflow puts no completion report on the pull request |
+| `--notify-message` | The completion comment body, in the `JOSH_SESSION_LANG` language (`ja` when unset), in the two-layer report shape: three lines of `Cause: / Fix: / Result:` first, one plain sentence each with no jargon or file names, then the changes as bullets under `Details:`. **Not a bare list of `Added … / Changed …`** |
+| `--notify-message-file` | The same body, read from a file (`-` reads stdin). **Use it whenever the report names a command or a path** — inside shell double quotes a backtick or a `$` is evaluated before this command starts (`prompts/collaboration-workflow/shell-body.md`) |
+| `--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>"` |
+
+Example 1 — the basic form (`fullrun` includes the merge):
+
+```bash
+pnpm josh followup "<issue-title> #<issue-number>" \
+  --notify-message "Implemented <title>
+Cause: <why this was needed, in one plain sentence>
+Fix: <what was changed, in one plain sentence>
+Result: <what is different for the user now>
+
+Details:
+- Added ...
+- Changed ..."
+```
+
+Example 2 — with a CodeRabbit ignore reason:
+
+```bash
+pnpm josh followup "<issue-title> #<issue-number>" \
+  --notify-message "Implemented <title>
+Cause: ...
+Fix: ...
+Result: ...
+
+Details:
+- Added ...
+- Fixed ..." \
+  --coderabbit-ignore-reason "<why the finding does not apply>"
+```
+
+Example 3 — with an AI-review (Claude Review) blocker ignore reason:
+
+```bash
+pnpm josh followup "<issue-title> #<issue-number>" \
+  --notify-message "Implemented <title>
+Cause: ...
+Fix: ...
+Result: ...
+
+Details:
+- Added ...
+- Fixed ..." \
+  --ai-review-ignore-reason "<tracked in issue #123>"
+```
+
+Example 4 — no merge (after a `kickoff`, or when the merge is done by hand). **`--no-merge` is not
+decoration**: leave it out and this command merges.
+
+```bash
+pnpm josh followup "<issue-title> #<issue-number>" \
+  --no-merge \
+  --notify-message "Implemented <title>
+Cause: ...
+Fix: ...
+Result: ...
+
+Details:
+- Added ..."
+```
+
+## `auto-merge` — Default `fullrun` behavior
+
+Every `fullrun` / `fullrun new` invocation uses `pnpm josh followup`, which handles the full sequence
+internally: wait for CI → verify AI review findings → send completion notification → merge. The user
+does **not** need to add a keyword. Invoking `fullrun` is itself the explicit authorization to merge.
+
+```bash
+pnpm josh followup "<title> #<N>" --notify-message "..."
+pnpm josh ms
+```
+
+- **Always run `pnpm josh ms` after a successful merge.** `pnpm josh followup` leaves the working tree
+  on the merged feature branch; `pnpm josh ms` (checkout default branch + `git pull`) returns it to the
+  default branch with the merge commit pulled. Skip this step only if the merge itself failed.
+- **In a lane, the terminal step is `pnpm josh lane:close <N>` instead, and `josh ms` refuses.** A lane
+  is a linked work tree, and git allows one branch in one work tree at a time. `josh ms` exits non-zero
+  there and says so, which is the expected answer. The default-branch refresh is the parent's, in the
+  primary checkout.
+- **AI review findings are checked automatically.** `pnpm josh followup` scans for CodeRabbit / Claude
+  Review findings before merging. If blockers are found, it sends a `confirmation` Telegram and exits
+  non-zero — fix the findings and re-run. **Green CI is not authorization to merge while AI review
+  findings are open.** (SonarCloud findings are not scanned by `followup`; the `sonar-qube.yml` CI
+  workflow runs the scan with `sonar.qualitygate.wait=true`, so a red Quality Gate fails the required
+  `SonarQube` check, which `followup` waits on.)
+- **CodeRabbit rate-limit is not a finding.** If the only CodeRabbit comment is a rate-limit warning
+  (`rate limited by coderabbit.ai` or `Rate limit exceeded`) and there is no substantive review, treat
+  it as "no findings" and proceed. Same if CodeRabbit produced no comment on the latest commit.
+- **Verify CodeRabbit findings before bypassing.** Do not pass `--coderabbit-ignore-reason` reflexively
+  — first verify. Example: CodeRabbit may flag a GitHub Actions SHA pin like `pnpm/action-setup@<sha> #
+  v6.0.8` as "not matching the tag" because it queried the annotated-tag-object SHA, not the commit
+  SHA. Confirm with `gh api repos/<owner>/<repo>/commits/<tag> --jq '.sha'` — if that matches the
+  pinned SHA, the finding is a false positive. Only then bypass, citing the verification command.
+- Merge goes through REST internally — the pull request's own merge endpoint with an explicit
+  `merge_method` (`gh pr merge` goes through GraphQL, which a cloud session is refused). **That path is
+  `followup`'s, not yours**: `.claude/settings.json` refuses `gh pr merge` and the `gh api` / `gh api
+  graphql` spellings of the same merge; `followup` calls gh from inside a node script. The prohibition
+  in `CLAUDE.md` → "Git Rules" is the rule.
+- Use the merge strategy the repo allows (`--merge` / `--squash` / `--rebase`); default to `--merge`.
+  Inspect with `gh api repos/<owner>/<repo> --jq '{allow_merge_commit, allow_squash_merge,
+  allow_rebase_merge}'` when unsure.
+- Do **not** pass `--delete-branch` unless the user asks.
+- If the merge fails (branch protections, conflicts), report the reason and stop — do not retry with
+  different flags or bypass protections.
+- **If the user wants to skip the merge step**, use `kickoff` or say "do not merge" in the same turn,
+  and pass `--no-merge`. Outside a `fullrun` invocation, never run `gh pr merge` on your own.
+
+## Completion notifications: always via `pnpm josh followup`
+
+Never send `completion` Telegram notifications manually with `pnpm josh notify --task-type completion
+...`. Always use `pnpm josh followup` — it fetches the PR URL through REST
+(`repos/{owner}/{repo}/pulls/{N}`) and always includes it, whereas the manual CLI does not
+auto-populate `--pr-url`.
+
+**Always run `pnpm josh followup` in the foreground** (no `&`, no shell backgrounding). **It is the
+deliberate exception to `background-commands.md`**: nearly every step after it reads its result, so
+detaching it would buy an empty turn. It waits for CI — 32 minutes by default, about 34 worst case —
+which can outlast one tool call, so give the call the largest timeout it accepts (in Claude Code,
+`timeout: 600000`). Where the harness detaches an over-running command and reports when it finishes,
+wait for that report instead of re-running. Where it kills the call at the cap, set `JOSH_CI_TIMEOUT_SECONDS`
+to a budget that fits inside the cap and re-run once CI has settled. Shell backgrounding never works.
+
+- Applies to the initial PR and every follow-up commit — re-run `pnpm josh followup "<title> #<N>"
+  --notify-message "..."` each time you want to notify completion (notification is sent right before
+  the merge).
+- `pnpm josh notify` remains the right tool for `planning`, `confirmation`, `kickoff_retry` and
+  `failure` notifications.
+- **The count of unreleased merges is surfaced at completion — not a version.** When `pnpm josh
+  followup` finishes it prints `🚚 unreleased merges on main: <n>` and puts the same count in the
+  `completion` Telegram body. **Do not report a shipped version**: a child no longer bumps, so
+  `package.json` names the *previous* release, and what ships is decided later by `pnpm josh release`.
+  What the run *does* about it is `followup-reference.md` → "When `pnpm josh release` runs".