@joshuafolkken/kit 1.1136.0 → 1.1178.0

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: 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.
+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).
 
 ## Run `pnpm josh followup`
 
@@ -22,9 +21,8 @@ Telegram, merges by default, posts the Issue report, closes completed epics, rem
 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.
+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 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
@@ -32,198 +30,123 @@ named recovery without rerunning it. Because notification precedes merge, the pr
 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.
-- **Confirms the Issue itself closed**, on a merged run only. GitHub has left merged runs' Issues
-  open despite `closes #N` (joshuafolkken/kit#2770), so an Issue still open a few seconds after the
-  merge is closed with a comment saying why, and the repair is printed as a warning.
-- **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
+`pnpm josh lane:close <N>`. Never delete the branch unless requested. The sections below are read
+after execution, when its output needs reading.
+
+## 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 |
+| `--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` | 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`) |
+| `--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>"` |
+| `--issue-number` | The Issue number — or give it positionally as `"<title> #<number>"`; with neither, the PR body's `closes #N` supplies it |
 
-Example 1 — the basic form (`fullrun` includes the merge):
+## `auto-merge` — Default `fullrun` behavior
 
-```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 ..."
-```
+Invoking `fullrun` is itself the explicit authorization to merge; the user adds no keyword.
+
+- **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.
+- **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.
+- **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.
+- **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`.
 
-Example 2 — with a CodeRabbit ignore reason:
+## Completion notifications: always via `pnpm josh followup`
 
-```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>"
-```
+**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.
 
-Example 3 — with an AI-review (Claude Review) blocker ignore reason:
+**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.
 
-```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>"
-```
+**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.
 
-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.
+## Reading the stage-timing block
 
-```bash
-pnpm josh followup "<issue-title> #<issue-number>" \
-  --no-merge \
-  --notify-message "Implemented <title>
-Cause: ...
-Fix: ...
-Result: ...
-
-Details:
-- Added ..."
-```
+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.
 
-## `auto-merge` — Default `fullrun` behavior
+- **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.
+- **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.
 
-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.
+A `failure` Telegram is sent **by hand, exactly once**, and only when recovery is given up:
 
 ```bash
-pnpm josh followup "<title> #<N>" --notify-message "..."
-pnpm josh ms
+pnpm josh notify --task-type failure --issue-url "<issue-url>" --body-file <reason-file>
 ```
 
-- **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` and then `josh sonar:new-code`, so a red
-  Quality Gate or a single new Sonar issue or duplicated block 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.
+## AI reviewer comment scan
 
-## Completion notifications: always via `pnpm josh followup`
+`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.
+
+- **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** (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
+  (restore via `JOSH_REQUIRED_CHECKS`), its actionable count and unreadable line-comment listing are
+  audit notes rather than blockers. Revert together with kit#752.
+
+## 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.
+
+## When `pnpm josh release` runs
+
+**The release point is a position plus a command's answer, never a judgement**
+(joshuafolkken/kit#1582).
+
+**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.
+
+```bash
+pnpm josh release:scope          # → required | skip | unknown
+```
 
-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".
+| 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 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.

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

@@ -9,10 +9,8 @@ the run is at, and the sections below carry that step in full.
 
 File Issues with `pnpm josh issue:file` (it applies the classification labels); see `prompts/collaboration-workflow/issue-template.md`.
 
-**Add `in-progress` the moment `run:hold` answered `hold`** (create if missing:
-`gh api repos/{owner}/{repo}/labels -f name=in-progress -f color=0075ca -f description="Work is
-actively in progress" --silent 2>/dev/null || true`, then `gh api
-repos/{owner}/{repo}/issues/<N>/labels -f 'labels[]=in-progress'`) → Read Issue #N and its comments
+**`in-progress` is already on the Issue** — `run:entry` applied it once the tree was held and the
+budget allowed the run, and `run:release <N>` takes it back off → Read Issue #N and its comments
 (`issue-comments.md`) → **normalize the title** (if not in English or can be phrased more clearly,
 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
@@ -52,9 +50,10 @@ primary checkout; a Claude run keeps it.
 `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
 `prompts/collaboration-workflow/issue-template.md`) — its duplicate scan runs first, and a candidate
-that covers the same work stops the run rather than filing a second Issue (`SKILL.md` → §2e). Capture
-`<N>`. (3) Add
-`in-progress` (as above). (4) Post the agreed plan in the session language: fill the body if blank,
+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" -- ':!docs/maintainers/observations'` first
 (joshuafolkken/kit#2919). (6) `git switch main && git pull`. (7)
@@ -74,7 +73,7 @@ ship "<title> #<N>" --notify-message "..."` (gate → commit/push/PR → the CI-
 stopping at the first failed step; joshuafolkken/kit#2398); **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-reference.md` →
+release:scope` and close the completion summary with what it answered** (`followup.md` →
 "When `pnpm josh release` runs").
 
 ## The release ask — the last step of either form
@@ -93,5 +92,5 @@ own end.
 Once the merge is done, `pnpm josh release:scope` says whether a release is owed — `required`, `skip`
 or `unknown`, and `unknown` is never read as `skip`. On `required` the completion summary closes with
 the request and the exact command; the run never types `pnpm josh release` itself, because publishing
-is Tier C (`followup-reference.md` → "When `pnpm josh release` runs", the single source). A `fullrun`
+is Tier C (`followup.md` → "When `pnpm josh release` runs", the single source). A `fullrun`
 invoked as one child of a `backlogrun` does not ask it — that batch asks once at its own end.

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

@@ -1,84 +1,27 @@
 # `fullrun` — the manifest (plan → implement → PR → merge → notify)
 
-**This file is the manifest, not the procedure** (joshuafolkken/kit#2189). It carries the ordered
-steps as terse triggers and pointers; the fine print of each step is read on demand from the file its
-pointer names, and `pnpm josh run:step <N>` prints the run's next single action, computed from the
-event stream, the carry record and the issue state (`run:next` is its pre-implementation degenerate
-form, and the two share one mapping).
-`chain-rule.md`, `followup.md`, `background-commands.md` and `latest-gate.md` are **not entry
-reads** — each is fetched at its point of use, in the turn that reaches it. The step lists themselves
-are `fullrun-steps.md`, read when a step needs its detail.
+**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.
 
-## The ordered entry sequence
+## The difference — the entry and the end
 
-**One call folds the mechanical steps of this sequence** (joshuafolkken/kit#2372): `pnpm josh
-run:entry <N>` 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, so a lane no longer re-bills its context on each.
-Its `entry #<N> — hold: … · cost: … · verdict: …` line carries the three facts the run branches on; a
-`busy`/`unknown` hold or an `over` budget short-circuits with a non-zero exit, and the numbered steps
-below are the detail behind each fact (`run:entry` reuses their own logic, it does not replace their
-single sources). Step 2 — the `in-progress` label — stays its own call, applied the moment the folded
-call reports `hold`.
+- **The entry passes no `--to`**: `pnpm josh run:entry <N>` is `fullrun`'s stage. Follow `run:step`
+  into `fullrun-steps.md` — the `fullrun #N` list or the `fullrun new` list.
+- **The end merges**: `run:step` names the verification gate, `pnpm josh followup`, `pnpm josh ms` and
+  the release ask in order. Invoking `fullrun` authorizes the merge, through `pnpm josh followup` only.
+- **A split or a prerequisite stops the run**: typing `fullrun` approved **one** Issue.
 
-1. **Claim the working tree — first, before anything else.** For `fullrun #N`, first run the folded
-   `pnpm josh run:entry <N>` above (no `--to` is `fullrun`, §2k); it calls `run:hold` as its first step. For `fullrun new`, call
-   bare `pnpm josh run:hold`, ahead of the title and filing. `hold` continues; `busy` / `unknown` stop
-   with a `confirmation` Telegram carrying stderr.
-   `working-tree-hold.md` is the single source; a cross-repository target resolves its checkout from
-   `pnpm josh doctor` first (`target-repository.md`).
-2. **Apply `in-progress` the moment `run:hold` answered `hold`** — a `#N` counts as holding its lane
-   from the claim (`fullrun-steps.md` carries the create/apply commands; a `fullrun new` applies it
-   right after filing). Every stop that leaves the tree clean removes it in the same turn as
-   `pnpm josh run:release`: `gh api -X DELETE repos/{owner}/{repo}/issues/<N>/labels/in-progress
-   2>/dev/null || true`. A `needs-human-review` stop keeps both hold and label.
-3. **Ask the session boundary in the same turn as the hold** — `pnpm josh cost --cut`. `under`
-   continues; `over` (or unanswerable) stops before the title — `run:entry` sends this and step 1's
-   `confirmation` Telegram and runs `run:release` (`stop notified: …`); by hand only for `new`.
-   **Skip it when dispatched by `backlogrun`** (that batch owns the question). `backlogrun-progress.md`
-   → "The hand-off" is the single source of the check and the shared 135,000 threshold.
-4. **Gather the mechanical reads — `pnpm josh run:prep <N>`**: `issue:read`'s body/comments
-   (`issue-comments.md`), `issue:state`'s state/labels/`human_review`, and `latest:scope`'s dependency
-   scope in one report, run beside `run:hold` and `cost --cut` in the same turn. The §2g comment stops,
-   the `human_review` stop and the dependency decision are read off it.
-5. **Print the next action — `pnpm josh run:step <N>`** (`run:next` for the prose form of the
-   pre-implementation step) — and follow it into `fullrun-steps.md`: the
-   `fullrun #N` list or the `fullrun new` list. Before implementing, `git switch main && git pull`, 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 — the verification gate, `pnpm josh followup`,
-   `pnpm josh ms`, the release ask — each read at the point-of-use doc the header lists, never
-   re-narrated here (`residency.md` → "順序の問い").
+## The lane-child seam
 
-## The progress step and the lane-child seam
-
-- **Start the progress watcher once the hold is claimed** — `pnpm josh run:progress --wait` in the
-  background, started once and relayed never, and `pnpm josh run:progress --mark` in the same turn as
-  every real report (`backlogrun-progress.md` → "Progress while the run is quiet"). A `fullrun`
-  dispatched as a lane child starts none and never reads that document (`pnpm josh read:set
-  lane-child`). **The watcher is a per-session heartbeat; the run's report surface is not it** — the
-  ambient surface is the run's event stream, followed identically before and after a cut, so nothing
-  about the reporter moves when execution hands off (`backlogrun-progress.md` → "The invariant is a
-  tier, not a mechanism").
 - **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
   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`), and it records any park on the Issue before the stop notify.
-  `pre-gate-cut.md` → "Resuming — the fresh process's entry check" and `pre-gate-cut.md` → "Taking
-  the cut" are the single sources of the two.
+  `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`.
-
-## The stop branches
-
-- **`needs-human-review`** — implement and gate, then stop before the commit; `needs-human-review.md`.
-- **A split** — the assessment (`split-assessment.md` → "The question") finds two or more
-  separately-mergeable deliverables over one gate: file the children (each `route:split`) and the epic,
-  then **STOP** with "Please run `backlogrun #<E> --only` to execute this epic." Typing `fullrun`
-  approved **one** Issue.
-- **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`.
-- **An observation** — file it without asking and carry on; `SKILL.md` → §2i.
-
-**Automatic filing is capped at 10 Issues per run.** On reaching it, stop and report.
-
-**The `into <target>` suffix** (a `new` entry) inserts the artifact into a named epic —
-`into-target.md`, read when the suffix is typed.

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

@@ -6,33 +6,20 @@ When this run files a new Issue, file it with `pnpm josh issue:file`, which lint
 implements the change and runs the full verification gate, then **stops before commit** — nothing is
 committed, pushed, or opened as a PR — so a person verifies the working tree by hand. Use it when a change needs human eyes before shipping.
 
-**This file is the manifest** (joshuafolkken/kit#2189): terse ordered steps, each pointing at the file
-that holds its detail.
+**This file is the manifest** (joshuafolkken/kit#2189). The entry sequence and the stop branches are
+`entry-sequence.md`, shared with `fullrun` and `prrun` (joshuafolkken/kit#3174); this file names only
+what is `halfrun`'s own.
 
-## The ordered entry sequence
+## The difference — the entry
 
-1. **Claim the working tree first** — `pnpm josh run:entry <N> --to halfrun` (bare `pnpm josh
-   run:hold` for `new`), ahead of the title and a `new` filing; it folds steps 3 and 5 and starts
-   at its stage line's `start:` (`SKILL.md` → §2k). `busy` / `unknown` stop with a `confirmation` Telegram (`run:entry` sends it). **The stop
-   before commit keeps the hold** (a second run would trample the uncommitted work); a stop on a
-   split, prerequisite or third-party target releases it. `working-tree-hold.md` is the single source; a
-   cross-repository target resolves its checkout from `pnpm josh doctor` first (`target-repository.md`).
-2. **Apply `in-progress` the moment `run:hold` answered `hold`** — the stop before commit keeps it on;
-   a stop that leaves the tree clean removes it in the same turn as `pnpm josh run:release` (`gh api -X
-   DELETE repos/{owner}/{repo}/issues/<N>/labels/in-progress 2>/dev/null || true`).
-3. **Ask the session boundary** — `pnpm josh cost --cut` (folded into `run:entry`); `over` stops — `run:entry` notifies and releases
-   (`halfrun new`: by hand). **Skip it when dispatched by a batch.** `backlogrun-progress.md` → "The hand-off" is
-   the single source of the check and the shared 135,000 threshold.
-4. **Start the progress watcher once the hold is claimed** — `pnpm josh run:progress --wait` in the
-   background, started once — it reports to the event stream itself and nothing is relayed — and
-   `--mark` in the same turn as every real report; the stop before commit ends the watcher
-   itself (`backlogrun-progress.md` → "Progress while the run is quiet").
-5. **The mechanical reads** — `run:entry` folds `run:prep` (body/comments — `SKILL.md` → §2g;
-   `human_review`; `latest:scope`); a `new` entry runs `pnpm josh run:prep <N>` once filed.
+- **`pnpm josh run:entry <N> --to halfrun`** opens the run.
+- **The stop before commit keeps the hold and `in-progress`** — a second run would trample the
+  uncommitted work; a stop on a split, prerequisite or third-party target releases both. The stop also
+  ends the progress watcher itself.
 
 ## The step list
 
-`halfrun #<N>`: add `in-progress` → read Issue #N and its comments → **normalize the title** (same as
+`halfrun #<N>`: read Issue #N and its comments → **normalize the title** (same as
 `fullrun`) → post the agreed plan only if the body is blank → `git switch main && git pull`, then `pnpm
 josh latest:scope` and update dependencies only on `required` (`latest-gate.md`; the
 `dependency-update` skill) → implement → run the **full verification gate** (refactor →
@@ -56,23 +43,10 @@ back with fixes, treat each as a new round: implement, re-run `pnpm josh gate`,
 `halfrun new` or `halfrun new "<title>"`: `kickoff new` + `halfrun #<N>` (no Issue exists yet). Steps
 mirror `fullrun new` (1)–(8): derive an English title (or use the provided one) → create the Issue
 (`pnpm josh issue:file "<title>" --body-file <body-file> --depth <n>`, body per
-`prompts/collaboration-workflow/issue-template.md`; its duplicate scan is read per `SKILL.md` → §2e) → add `in-progress` → post the agreed plan → stash
+`prompts/collaboration-workflow/issue-template.md`; its duplicate scan is read per `issue-scout.md`) → add `in-progress` (as `fullrun new` (3)) → post the agreed plan → stash
 any pre-existing changes with `git stash push -m "halfrun new: pre-existing changes" -- ':!docs/maintainers/observations'`
 (the pathspec keeps the observation ledger in the tree for this run's commit; joshuafolkken/kit#2919), popped by
 message with `pnpm josh stash:pop "halfrun new: pre-existing changes"`, never a positional `git stash pop` →
 `git switch main && git pull` → `pnpm josh latest:scope` → implement → run the gate (as above, `pnpm
 josh test:e2e` run by **you**) → `pnpm josh run:hold <N> --halfrun-stop` → send the `confirmation`
 Telegram and **stop**.
-
-## The stop branches
-
-- **`needs-human-review`** — implement and gate, then stop before the commit; `needs-human-review.md`.
-- **A split** — the assessment (`split-assessment.md` → "The question") finds two or more
-  separately-mergeable deliverables over one gate: file the children (each `route:split`) and the epic,
-  then **STOP** with "Please run `backlogrun #<E> --only` to execute this epic." Typing `halfrun`
-  authorized **one** Issue, never a batch.
-- **A prerequisite** — file it (`route:tier-a`), stash, record the dependency, and **STOP**;
-  `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; `SKILL.md` → §2i.
-
-**Automatic filing is capped at 10 Issues per run.** On reaching it, stop and report.

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

@@ -1,9 +1,9 @@
 # The `into <target>` suffix — where the new Issue lands
 
-**This is `SKILL.md` → §2a's body, read at its point of use — the moment a `new` entry is typed with
-an `into <target>` suffix, not at any entry** (joshuafolkken/kit#2161). A run given a `#N` or a bare
-`new` never reaches it, so it costs a workflow entry nothing to leave it here. `SKILL.md` → §2a keeps
-the trigger and points here.
+**This file is the suffix's single source, read at its point of use — the moment a `new` entry is
+typed with an `into <target>` suffix, not at any entry** (joshuafolkken/kit#2161). A run given a `#N`
+or a bare `new` never reaches it, so it costs a workflow entry nothing to leave it here. `SKILL.md` →
+§2's table keeps the trigger and points here.
 
 `kickoff new` / `fullrun new` / `halfrun new` accept a suffix naming the epic the run's artifact
 belongs to. Without it the artifact belongs to no epic, and `epic:next` only ever offers an epic's

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

@@ -1,8 +1,8 @@
 # An Issue's comments are part of the Issue
 
-**This is the body of `SKILL.md` §2g, relocated here so the entry read carries the trigger and the
-pointer, not the procedure** (joshuafolkken/kit#2189). `SKILL.md` §2g is the resident stub, and every
-`#N` entry file routes here for the definition. It is read at its point of use — before implementing a
+**This file is the single source, so the entry read carries the trigger and the pointer, not the
+procedure** (joshuafolkken/kit#2189). `SKILL.md` → §2's table keeps the trigger, and every `#N` entry
+file routes here for the definition. It is read at its point of use — before implementing a
 `#N` Issue.
 
 **Every `#N` entry point reads the Issue's comments before it implements** — `fullrun`, `halfrun` and
@@ -73,7 +73,6 @@ holding a lane. **Only a person removes it, by closing the Issue.**
 ```bash
 gh api repos/{owner}/{repo}/labels -f name=already-done -f color=6f42c1 -f description="Verified already merged — a person closes it" --silent 2>/dev/null || true
 gh api repos/{owner}/{repo}/issues/<N>/labels -f 'labels[]=already-done'
-gh api -X DELETE repos/{owner}/{repo}/issues/<N>/labels/in-progress 2>/dev/null || true
 ```
 
 The procedure, in order:
@@ -81,10 +80,10 @@ The procedure, in order:
 1. **Record the evidence as an Issue comment, before the label.** Name the pull request or commit that
    merged the work and, for each acceptance criterion the Issue states, the file and lines that satisfy
    it. **A claim with no citations is not the finding this exit is for.**
-2. **Apply `already-done` and remove `in-progress`** — the two commands above. Leaving `in-progress`
-   on holds a lane against an Issue nothing will ever run.
+2. **Apply `already-done`** — the two commands above.
 3. **Commit nothing, push nothing, open no pull request.** The tree is clean, so release the hold with
-   `pnpm josh run:release <N>`.
+   `pnpm josh run:release <N>`, which also removes `in-progress` — left on, it holds a lane against an
+   Issue nothing will ever run.
 4. **Then behave as the entry point does for a parked child.** A `fullrun` / `halfrun` a person typed
    sends a `confirmation` Telegram naming the Issue and the merge that already covers it, and stops. An
    `backlogrun` child is park-and-continue (`backlogrun-park.md` → "park and continue").
@@ -98,7 +97,7 @@ citations: a criterion you cannot point at merged code for is a criterion this r
 
 **The fetch is one call however long the thread is; what costs is carrying it afterwards** — which is
 why the call above projects each comment down to its author, its timestamp and its body. Once the
-thread runs longer than the Issue itself it is exactly the pre-implementation reading §2b describes:
+thread runs longer than the Issue itself it is exactly the pre-implementation reading `delegation.md` describes:
 brief a delegated unit to return **the agreements in force plus the comment URLs that carry them**,
 never the comment text.