@joshuafolkken/kit 1.1453.0 → 1.1471.0

package/.claude/skills/workflow-commands/progress-watcher.md

@@ -13,9 +13,8 @@ point-of-use document, never an entry read, and the single source of the heartbe
 pnpm josh run:progress --wait --output <the transcript path of each delegated unit>   # in the background
 ```
 
-**Start it once; it reports by itself.** Each silence interval appends the
-five labelled lines to the run's event stream as a heartbeat and to the ambient log, prints nothing to
-standard output and keeps running — so a scheduled report never wakes the session, and the session
+**Start it once; it reports by itself.** Each silence interval appends the five labelled lines to the
+event stream and the ambient log, prints nothing to standard output and keeps running — the session
 relays none. **It exits only on one of three, and the command computes which:**
 
 | Exit                                                    | What the session does                                                  |
@@ -27,22 +26,20 @@ relays none. **It exits only on one of three, and the command computes which:**
 **A report is not an exit, and neither is a decline** — with no run recorded it keeps waiting, and the
 `--hours` exit says so on standard error.
 
-**`pnpm josh run:watcher:guard` detects a missed restart**: wired into
-`pretool-guard`, it refuses the next tool call while lane children are in
-flight and the watcher's life record has gone stale — once per run, so the restart is not blocked.
+**`pnpm josh run:watcher:guard` detects a missed restart** — via `pretool-guard` it refuses the next
+tool call while lane children are in flight and the watcher's record is stale, once per run.
 
-**`--mark` at every real report.** Whenever the run reports something of its own, run
-`pnpm josh run:progress --mark` in the same turn to restart the silence clock. The clock is silence,
-never a timer (`docs/josh-commands-run.md` → "`josh run:progress`").
+**`--mark` at every real report** — `pnpm josh run:progress --mark` in the same turn restarts the
+silence clock (`docs/josh-commands-run.md` → "`josh run:progress`").
 
-**Do not keep a progress clock of your own** — the hook refuses the arm rather than asking
+**Do not keep a progress clock of your own** — the hook refuses the arm
 (`scripts/rules/early-heartbeat.ts` → `decide`), though a single correctly-spaced arm is allowed.
 `--wait` is not a wait timer.
 
 **The default interval is twenty minutes, overridable — by the person, not the run.**
-`JOSH_PROGRESS_INTERVAL_MINUTES` moves both sides (the guard reads it through the watcher's reader);
-`josh` → `progress_interval_minutes` in `package.json` sits one step below the variable. **`--interval`
-moves the watcher alone** — it makes the watcher quieter than the floor, never the guard stricter.
+`JOSH_PROGRESS_INTERVAL_MINUTES` moves both sides; `josh` → `progress_interval_minutes` in
+`package.json` sits one step below it. **`--interval` moves the watcher alone** — quieter, never the
+guard stricter.
 Rationale: `docs/maintainers/progress-watcher-rationale.md` → "Why the heartbeat reads as it does".
 
 ### What a report says
@@ -75,21 +72,19 @@ signal tiers are split this way".
 `JOSH_LANE_CHILD` mark** — it still runs `--mark` for the parent's clock, but every reporting form
 (`--wait`, `--once`, the default watch) exits at once with a notice.
 
-**It is started in the target repository's checkout, and `--mark` is run there too.** A heartbeat is
-emitted from the moment a run has started — a registered lane, a held work tree or a carried budget —
-even before any child carries `in-progress`; only a checkout with no run recorded stays silent.
+**It is started in the target repository's checkout, and `--mark` is run there too.** It beats from the
+moment a run has started — a registered lane, a held work tree or a carried budget; only a checkout
+with no run recorded stays silent.
 
 **In a single-issue run, a real report is any turn that puts a progress statement in front of the
-person** — four of them, `--mark` run in the same turn as each: **the Step 0 work summary, the pull
-request opening, each review round's verdict, and any `confirmation` / `failure` / `completion`
-notification or stop.** **A tool result only you read is not one** — a gate run, a `gh` read, an edit.
-`--output` is omitted there, and `record` reads `unread`. In a `backlogrun`, a child merged, parked or
-stopped is the report.
-
-**A run that merges needs no teardown; a run that stops has to end the reporting itself.** A stop
-keeps the `in-progress` label on purpose, so **no further `--wait` is started** after the stop
-notification, and the running `--wait` is stopped in the same turn, since no report ends it. That
-covers `halfrun`'s stop before commit, a `needs-human-review` stop, a split or prerequisite stop, and a
+person** — `--mark` in the same turn as each: **the Step 0 work summary, the pull request opening, each
+review round's verdict, and any `confirmation` / `failure` / `completion` notification or stop.** **A
+tool result only you read is not one.** `--output` is omitted there, and `record` reads `unread`. In a
+`backlogrun`, a child merged, parked or stopped is the report.
+
+**A run that merges needs no teardown; a run that stops has to end the reporting itself** — **no
+further `--wait` is started** after the stop notification, and the running one is stopped in the same
+turn: `halfrun`'s stop before commit, a `needs-human-review`, split or prerequisite stop, a
 `backlogrun` named issue's failure stop. Rationale: `docs/maintainers/progress-watcher-rationale.md` →
 "Why the watcher runs where it does".
 

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

@@ -27,7 +27,8 @@ Where `fullrun` runs `pnpm josh followup` and merges, `prrun` does three things
    follows for finishing without an agent:
    `pnpm josh notify --task-type confirmation --issue-url "<issue-url>" --body=$'prrun ready to
    merge: <pr-url>\nNext: fullrun #<N>\nAfter a manual merge, without an agent: pnpm josh followup
-   "<title> #<N>"'`. The stop report names the same two, in the same order.
+   "<title> #<N>"' --recommended "fullrun #<N>" --alternative "Merge by hand, then pnpm josh
+   followup"`. The stop report names the same two, in the same order.
 
 **Invoking `prrun` is _not_ authorization to merge** — never run `pnpm josh followup` without
 `--no-merge` in a `prrun`. After a person merges by hand, the same `pnpm josh followup "<title> #<N>"`

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

@@ -1,75 +1,56 @@
 # The end-of-run retrospective
 
-**This is the retrospective's procedure, and it is read when `run:step` prints the retrospective step —
-not at the entry.** `SKILL.md` → §2's table keeps the rule itself: run what `run:step` prints once,
-file the improvements worth carrying into the next run, stack the rest, and mark the step done.
-Everything that decides *how* — what the four sections mean, how the top two are chosen, the
-exclusions, and the `auto-ok` judgement — is here. Read it in full, in the same turn, before filing.
+**Read it when `run:step` prints the retrospective step — not at the entry.** `SKILL.md` → §2's table
+keeps the rule: run what `run:step` prints once, file the improvements worth carrying, stack the rest,
+mark the step done. Read this file in full, in the same turn, before filing.
 
-**When it fires is not this file's, and not a judgement.** The run driver prints the step the moment the
-backlog drains — `backlog:offer` marks that drain on the event stream and `run:step` fires the
-retrospective at it, *before* the idle watch, so the improvement issues it files are what the watch then
-picks up; a run that stops without draining — the failure guard, `--idle 0` — still prints it at the
-stop position. It is kit-only — `run:step` prints the step only in the kit repository.
+**When it fires is not a judgement.** `run:step` prints the step when `backlog:offer` marks the backlog
+drained, *before* the idle watch, so the watch picks up what it files; a run that stops without
+draining — the failure guard, `--idle 0` — still prints it at the stop position. Kit-only.
 
 Rationale: `docs/maintainers/retrospective-rationale.md` → "Why the retrospective is read at its step";
 provenance: `docs/maintainers/retrospective-rationale.md` → "Where each rule came from".
 
 ## The digest is read, not skimmed
 
-The command `run:step` prints folds four measurements that already exist into one digest — it adds no
-new measurement (the observation-filing rule against readerless numbers). Read each section for what it
-is for:
+The command `run:step` prints folds four existing measurements into one digest — it adds none:
 
-- **Run cost & time by role.** A role whose share of the wall clock runs ahead of its share of the cost
-  is marked `waiting-heavy` — the run spent that time waiting rather than working. That gap is a
-  candidate improvement, not a verdict: a role that waits by design is not a defect.
-- **Recurring review findings.** A category that keeps coming back across rounds is friction in the
-  code or the rules the reviews keep catching; the zero-finding denominator tells a genuinely quiet
-  category apart from one nobody looked at.
-- **Observation ledger.** How many observations are already held without being filed — a reminder to
-  promote one a second sighting has now earned, rather than a fresh finding.
-- **Run events.** The parks, outages, cuts and review rounds the run hit — where it did not run
-  straight through.
+- **Run cost & time by role.** A role whose wall-clock share runs ahead of its cost share is marked
+  `waiting-heavy` — a candidate improvement, not a verdict: some roles wait by design.
+- **Recurring review findings.** A category that keeps coming back is friction the reviews keep
+  catching; the zero-finding denominator separates a quiet category from an unexamined one.
+- **Observation ledger.** Observations held without being filed — promote one a second sighting earned.
+- **Run events.** The parks, outages, cuts and review rounds — where the run did not run straight through.
 
-The digest closes by pointing back here; the two targets it names are **the run itself** (the first,
-third and fourth sections) and **the repository** (the second, and anything the run surfaced that lives
-outside it).
+The two targets are **the run itself** (sections one, three, four) and **the repository** (section two,
+and anything the run surfaced that lives outside it).
 
 ## What to file, and how the top two are chosen
 
-**The filing condition is the existing depth test, unchanged** — a filing cites the product work it
-improves, and a `depth:2` finding names which decision it turns on (`observation-filing.md` → "The depth
-test"). An improvement that cannot pass the test is not filed; it is not a shortfall of the two-item
-count, it simply is not yet a finding.
+**The filing condition is the existing depth test, unchanged** (`observation-filing.md` → "The depth
+test"). What cannot pass it is not filed — not a shortfall, just not yet a finding.
 
 **Order what passes by effect, and file the top two.** **The third onward is stacked in the observation
-ledger**, on the same append path `pnpm josh observations:flush` already drains. **File nothing when
-nothing passes** — a run whose measurements show no improvement worth carrying files zero Issues.
+ledger** (drained by `pnpm josh observations:flush`). **File nothing when nothing passes.**
 `docs/maintainers/retrospective-rationale.md` → "Why the top two are a selection, not a ration".
 
-**Exclude what is already filed or already done, through the existing scout** (`issue-scout.md`). File
-each with `pnpm josh issue:file`, which runs the scout before creating anything: an **open** candidate
-covering the same work means do not file it, and a `(closed)` candidate covering it means the work is
-already merged. Neither exclusion is a new mechanism. The same call runs `epic:bundle` on each new
-Issue, as after any filing.
+**Exclude what is already filed or already done, through the existing scout** (`issue-scout.md`): file
+with `pnpm josh issue:file`, which scouts first — an **open** candidate covering it means do not file, a
+`(closed)` one means already merged. It also runs `epic:bundle` on each new Issue.
 
 ## `auto-ok`, and closing the step
 
-**What a retrospective files is judged for `auto-ok`** — an improvement that needs no person's
-judgement declares `- 人の判断: 不要`, so `issue:file` applies the label (with the run label `prompts/collaboration-workflow/issue-template.md` requires) and the next run picks it up
-without waiting for a person. **`backlogrun-steps.md` → "What one invocation approves" is that
-judgement's single source**; it is written there, beside the brakes that bound it, rather than restated here. Every brake still counts a retrospective's filings: the
+**What a retrospective files is judged for `auto-ok`** — one needing no person's judgement declares
+`- 人の判断: 不要`, so `issue:file` applies the label (with the run label
+`prompts/collaboration-workflow/issue-template.md` requires). **`backlogrun-steps.md` → "What one
+invocation approves" is that judgement's single source.** Every brake still counts these filings: the
 ten-per-invocation ceiling, the WIP cap, `--max` and the 150,000-token session budget.
 
 **Close with `pnpm josh run:carry --retrospective --summary "<result>" --owner "$PPID"`.** It marks the
-retrospective run on the carry record, so `run:step` prints `stop` from then on rather than the step a
-second time. The mark rides the record across a session cut and is removed with the record at
-`pnpm josh run:carry --end`, so one invocation runs the retrospective exactly once whether or not it was
-cut. **`--summary` is required** — the same close writes it as one `retrospective` event on the event
-stream, so a zero-filing retrospective differs from one that never ran; name
-the issues filed (or that none were) and the candidates dropped with why.
+carry record so `run:step` prints `stop` from then on; the mark survives a session cut and is removed at
+`pnpm josh run:carry --end`, so one invocation runs it exactly once. **`--summary` is required** — it is
+written as a `retrospective` event, so a zero-filing retrospective differs from one that never ran; name
+the issues filed (or none) and the candidates dropped with why.
 
-**A dispatched lane child never reaches any of this** — the batch runs the retrospective at its own end,
-never a child's, exactly as it asks `release:scope` once at the batch's end. `run:step` already answers
-`stop` for a lane child at the stop position, so a child never prints the step to begin with.
+**A dispatched lane child never reaches any of this** — the batch runs it at its own end; `run:step`
+answers `stop` for a lane child at the stop position.

package/.claude/skills/workflow-commands/split-assessment.md

@@ -1,52 +1,43 @@
 # The split assessment — one definition, every entry point
 
-Before any entry point starts work on an Issue, decide whether the request is really **one**
-deliverable or several. This file is the single definition; every command applies it identically.
+Before any entry point starts work on an Issue, decide whether the request is **one** deliverable or
+several. This file is the single definition; every command applies it identically. Reasons:
+`docs/maintainers/split-assessment-rationale.md` → "Why the default is not to split" and
+`docs/maintainers/split-assessment-rationale.md` → "Why diff size is not a reason to split".
 
 ## The question
 
-**The default is not to split.** Two questions have to answer yes **together**; either one alone
-leaves the work as one Issue:
+**The default is not to split.** Two questions have to answer yes **together**:
 
 1. **Does the request contain two or more deliverables that could each be merged separately?**
 2. **Does the whole of it clearly exceed what one verification gate can confirm in one pass?** The
    guide is **about 10 changed files and about 400 changed lines** (test files excluded).
    Under that, it is one Issue however many separable pieces a reader can name inside it.
 
-Separately mergeable is still the first test, and it is unchanged: a change that must land in one
-commit to be correct is one deliverable however big it is. What changed is that **separability alone
-no longer splits anything** — it is now a necessary condition rather than a sufficient one.
-
-**The guide is a guide, and "clearly" is the operative word.** A run that has to argue itself past the
-numbers has already answered no. They are read against the whole request's estimate, not against the
-diff a first pass happens to produce, and a request that lands at 11 files is not thereby a split.
+A change that must land in one commit to be correct is one deliverable however big it is; **separability
+alone no longer splits anything**. **"Clearly" is the operative word** — a run that has to argue past
+the numbers has answered no. They are read against the whole request's estimate, and 11 files is not
+thereby a split.
 
 ## The same two questions decide the filing-time fold
 
 **The entry's split decision and the filing-time fold decision are the same two conditions, stated
-here once.** This assessment asks whether *one request* is several deliverables; the fold decision asks
-whether *several findings from one session* are one Issue — and reads the **same two questions in the
-same conjunction**: separability, and whether the whole clearly exceeds one gate.
-`pnpm josh issue:fold "<title>" …` answers `fold` / `separate` / `no-fold-needed`; its size half is
-`pnpm josh split:assess`, called not recomputed, and `separate` needs both halves exactly as `split`
-does. A diff with no non-test file, or none readable, answers `undetermined`: the size is then the
-whole request's estimate above. **There is no second criterion.** `observation-filing.md`'s observation, the review round cap's branch 2 and `prerequisite.md`'s
+here once** — the fold asks whether *several findings from one session* are one Issue, with the same
+conjunction. `pnpm josh issue:fold "<title>" …` answers `fold` / `separate` / `no-fold-needed`; its size
+half is `pnpm josh split:assess`, called not recomputed. A diff with no readable non-test file answers
+`undetermined`, and the size is the request's estimate. **There is no second criterion.**
+`observation-filing.md`'s observation, the review round cap's branch 2 and `prerequisite.md`'s
 prerequisite each route a second filing through it — `pnpm josh issue:file` asks it itself at the
 run's second filing, never the first, and holds only a `fold`.
 
 ## Diff size is not a reason to split, and that is measured
 
-**Size is a bar a split has to clear; it is never a reason to split.** Question 2 is a *minimum* — below
-it the work stays whole — and nothing makes a large diff a reason to divide one. **A proposal to add a
-size threshold that splits more is required to say why the round-1 measurement does not reach it.**
-Rationale: `docs/maintainers/split-assessment-rationale.md` → "Why the default is not to split" and
-`docs/maintainers/split-assessment-rationale.md` → "Why diff size is not a reason to split".
+**Size is a bar a split has to clear; it is never a reason to split.** **A proposal to add a size
+threshold that splits more is required to say why the round-1 measurement does not reach it.**
 
-**The size half is measured, not eyeballed — `pnpm josh split:assess`.** It counts the branch's
-changed files and changed lines with test files excluded and answers `split` / `single` on size
-alone, so the guide can be checked against real diffs after the fact rather than trusted from an
-estimate. It answers the **size** question only; separability (question 1) stays a judgement, which is
-why a `split` from this command is the size condition met, not a decision to divide the Issue.
+**The size half is measured, not eyeballed — `pnpm josh split:assess`** counts the branch's changed
+files and lines, test files excluded, and answers `split` / `single` on size alone. Separability stays
+a judgement, so its `split` is the size condition met, not a decision to divide.
 
 ## What each entry point does with the answer
 
@@ -59,26 +50,19 @@ why a `split` from this command is the size condition met, not a decision to div
 
 ## A prerequisite is not a split
 
-"This needs something else done first" is a different answer from "this is really several things". A
-split means the request in hand contains two or more deliverables; a prerequisite means it is still
-**one** deliverable that has another one in front of it. The prerequisite rule is `prerequisite.md`, its
-single source; each entry's own branch is in `backlogrun-park.md` → "A prerequisite discovered mid-run" and, for
-the stopping entry points, in `fullrun.md` / `halfrun.md`.
+A split means the request contains several deliverables; a prerequisite means it is **one** deliverable
+with another in front of it. `prerequisite.md` is the single source; each entry's branch is in
+`backlogrun-park.md` → "A prerequisite discovered mid-run" and `fullrun.md` / `halfrun.md`.
 
 ## Two or more always means an epic
 
 **Splitting into two or more Issues always creates an epic. There is no count threshold and no ordering
-condition to evaluate.** This is about what follows a split, never about whether to make one — the bar
-for that is "The question" above. **An entry point that applies a different condition is a defect** —
-the whole point of one definition is that where the split was noticed cannot change what happens next.
-
-The epic is the non-closing home for the split rationale. A comment on the first child is buried the
-moment that child merges and closes.
+condition to evaluate.** **An entry point that applies a different condition is a defect.** The epic
+is the non-closing home for the split rationale.
 
 **Each split child is filed with the `route:split` label** —
-`pnpm josh issue:file "<sub-title>" --body-file <body-file> --depth <n> --route split` — so the
-backlog's composition stays countable by filing route rather than by grepping issue bodies. Each child
-is judged for `auto-ok` like any filing (`kickoff.md` → "Words typed after `new`").
+`pnpm josh issue:file "<sub-title>" --body-file <body-file> --depth <n> --route split` — and judged for
+`auto-ok` like any filing (`kickoff.md` → "Words typed after `new`").
 
 ## Promote, or create a new epic
 
@@ -87,33 +71,25 @@ on the Issue, without asking.
 
 - **`#N` is a request, a discussion, or a container → promote it.**
   `pnpm josh epic --promote <N> <N1> <N2> ... [--ordered]`. The body is appended to, never replaced.
-- **`#N` is itself one of the deliverables → keep `#N` as a child and create a new epic.** A bug report
-  that turns out to need three fixes is the case: promoting the report would leave the report itself
-  with nowhere to live.
+- **`#N` is itself one of the deliverables → keep `#N` as a child and create a new epic** — e.g. a bug
+  report that needs three fixes.
 
 ## `backlogrun` is the one entry that does not stop
 
-`backlogrun` asked for the batch's authorization, so a split found under it is filed and continued through
-rather than stopped — including when the `backlogrun` was given a bare, non-epic Issue, where the split is
-what creates the epic (`backlogrun-child.md` → "When `#N` is not an epic"). The assessment itself is identical;
-only what follows the answer differs.
+A split found under `backlogrun` is filed and continued through — including from a bare, non-epic
+Issue, where the split creates the epic (`backlogrun-child.md` → "When `#N` is not an epic").
 
 ## Finding a split mid-run stops the run
 
-`fullrun` and `halfrun` **stop** after filing the children and the epic. They do not continue into
-implementation, and they do not silently become a `backlogrun`. Typing `fullrun` approved implementing and
-merging **one** Issue; a batch of N is a different authorization. Report what was filed and end with:
+`fullrun` and `halfrun` **stop** after filing the children and the epic — typing `fullrun` approved
+**one** Issue. Report what was filed and end with:
 
 > Please run `backlogrun #<E> --only` to execute this epic.
 
 ## There is no `kickoff epic`
 
-A separate keyword for "split this conversation into an epic" would duplicate `kickoff new` exactly,
-leaving a person to decide which of two commands to type for one job. The assessment above is how a
-split is reached from every entry.
+It would duplicate `kickoff new`; the assessment above reaches a split from every entry.
 
 ## Issues filed separately, found related later
 
-Issues that were filed at different times and turn out to be related afterwards are **not** a split — a
-split is about one request in hand containing several deliverables. That case is outside this
-assessment, and `pnpm josh epic --promote` is what handles it.
+Not a split — `pnpm josh epic --promote` handles it.

package/.claude/skills/workflow-commands/working-tree-hold.md

@@ -3,10 +3,9 @@
 **The single source of the hold**, read at its point of use — the moment a run is about to claim or
 release the tree. History: `docs/maintainers/working-tree-hold-rationale.md` → "Where each rule came from".
 
-**Ask `pnpm josh run:hold` before anything else, and obey what it answers.** It is the first call of
-`fullrun` and `halfrun` alike — before the title is normalized, before `pnpm josh ms`, and **before
-a `new` entry files its Issue**, because a run stopped after the filing has already left behind the
-artifact it should not have created.
+**Ask `pnpm josh run:hold` before anything else, and obey what it answers** — the first call of
+`fullrun` and `halfrun`, before the title, before `pnpm josh ms`, and **before a `new` entry files its
+Issue**.
 
 ```bash
 pnpm josh run:hold <N>        # a `#N` entry point
@@ -17,81 +16,65 @@ pnpm josh run:release --force # a record left behind by a run that has ended
 ```
 
 - **`hold` — this run now holds the tree. Continue.**
-- **`busy` — another run holds it. Stop.** Send a `confirmation` Telegram carrying what the command
-  printed on stderr (the holder, when the record was written, and the release command) and stop.
-  **File nothing, create no branch, edit nothing.**
+- **`busy` — another run holds it. Stop.** Send a `confirmation` Telegram carrying its stderr (the
+  holder, when the record was written, the release command). **File nothing, create no branch, edit
+  nothing.**
 - **`unknown` — nothing was established. Stop the same way.** It is not "the tree is free".
 
 **The unit is the working tree** — one branch, one index and one uncommitted diff, and a linked work
-tree has its own three. **`backlogrun`'s per-repository guard (`epic-busy.ts`) is a separate layer and is
-unchanged.**
-
-**`kickoff` does not claim it** — it touches GitHub, never the branch, index or diff. Rationale for both:
-`docs/maintainers/working-tree-hold-rationale.md` → "Why the unit is the working tree".
-
-**Claim it in the checkout the run will edit.** The record is keyed to the work tree the command runs
-in, so a cross-repository `fullrun owner/repo#N` resolves that repository's checkout from `pnpm josh
-doctor` **first** — that resolution is a read and writes nothing — and claims there.
-
-**A release names the run it belongs to.** `pnpm josh run:release <N>` removes the record only where the
-record names `<N>`, the bare form only the unnumbered run's, and a record belonging to anything else
-answers **`held`** and is left standing. **`pnpm josh run:release --force` is the one spelling that
-removes a record this run did not write**, and the `busy` stop message names it rather than the
-ordinary one.
-
-**Release what the claim recorded, which is not always the Issue number.** A `#N` entry claimed `<N>`
-and releases `<N>`; a **`new` entry claimed before its Issue existed**, so it releases with the
-**bare** form however many numbers the run has acquired since — so a `fullrun new` that stops on a
-split types `pnpm josh run:release`, not `pnpm josh run:release <N>`. The bare form removes no
-label, so every `new` stop that releases — a split, a prerequisite or a third-party target — also runs `gh api -X DELETE repos/{owner}/{repo}/issues/<N>/labels/in-progress
-2>/dev/null || true`.
-
-**Releasing is the run's, not a person's memory.** `pnpm josh followup` releases the hold on a merged
-run, and a record abandoned by a crashed session expires after 8 hours. **A stop that leaves the tree
-clean releases it explicitly**: a `fullrun` / `halfrun` that stops on a split, a prerequisite or a
-third-party target ends with `pnpm josh run:release <N>` (bare where that run entered as `new`, followed by the label DELETE above).
-**`halfrun`'s stop before commit keeps the hold**, and so does a `needs-human-review` stop: the
-uncommitted work still in the tree is exactly what a second run would trample, so the release command
-goes in the stop report and the Telegram for the person to type. **`fullrun #<N>` of the same issue
-adopts a `halfrun`'s kept hold** rather than being refused `busy` by it — "The halfrun resume" below. **An expired record over a tree that
-still has uncommitted changes does not free it**: the command answers `busy` and says to commit, stash,
-or release once the work is done; only an expired record over a clean tree is replaced.
-
-**The batch entry points claim per child, not per batch.** `backlogrun` never
-call it themselves; each child runs the `fullrun` procedure, so it claims on entry and `pnpm josh
-followup` releases it at that child's merge. The command's behavior and the answer table are
-`docs/josh-commands-run.md` → "`josh run:hold` / `josh run:release`"; this file is the single source of
-the procedure.
+tree has its own three. **`backlogrun`'s per-repository guard (`epic-busy.ts`) is a separate layer.** **`kickoff`
+does not claim it** (`docs/maintainers/working-tree-hold-rationale.md` → "Why the unit is the working
+tree").
+
+**Claim it in the checkout the run will edit** — a cross-repository `fullrun owner/repo#N` resolves
+that checkout from `pnpm josh doctor` **first** (a read) and claims there.
+
+**A release names the run it belongs to.** `pnpm josh run:release <N>` removes only a record naming
+`<N>`, the bare form only the unnumbered run's; anything else answers **`held`** and stands. **`pnpm
+josh run:release --force` is the one spelling that removes a record this run did not write**, and the
+`busy` message names it.
+
+**Release what the claim recorded.** A `#N` entry releases `<N>`; a **`new` entry claimed before its
+Issue existed**, so it releases with the **bare** form — a `fullrun new` that stops on a split types
+`pnpm josh run:release`. The bare form removes no label, so every `new` stop that releases also runs
+`gh api -X DELETE repos/{owner}/{repo}/issues/<N>/labels/in-progress 2>/dev/null || true`.
+
+**Releasing is the run's, not a person's memory.** `pnpm josh followup` releases on a merged run; an
+abandoned record expires after 8 hours. **A stop that leaves the tree clean releases it explicitly** —
+a split, a prerequisite or a third-party target ends with `pnpm josh run:release <N>` (bare for a `new`
+entry, plus the label DELETE). **`halfrun`'s stop before commit keeps the hold**, as does a
+`needs-human-review` stop: the release command goes in the stop report and the Telegram for the person
+to type. **`fullrun #<N>` of the same issue adopts a `halfrun`'s kept hold** — "The halfrun resume"
+below. **An expired record over a tree that still has uncommitted changes does not free it** — it
+answers `busy`; only an expired record over a clean tree is replaced.
+
+**The batch entry points claim per child, not per batch** — each `backlogrun` child claims on entry and
+`pnpm josh followup` releases at its merge. The answer table is `docs/josh-commands-run.md` → "`josh
+run:hold` / `josh run:release`".
 
 ## The halfrun resume
 
-**`fullrun #<N>` or `prrun #<N>` after a `halfrun` stop resumes it instead of claiming.** The
-stop is **recorded, never inferred**: the `halfrun` ends with `pnpm josh run:hold <N> --halfrun-stop`,
-which marks its own record (re-keying a `halfrun new`'s unnumbered one to the filed issue) — a
-`halfrun` still implementing or a `backlogrun` child leaves the same hold over the same dirty tree, and
-must not be adopted. On a marked hold for `#<N>` over a dirty tree, `run:entry` asks the session budget
-(`over` stops as usual), adopts the hold with the `fullrun` mark and prints `entry #<N> — resume:
-halfrun`. **Skip the title, the plan, the split assessment, `pnpm josh ms`,
-`latest:scope` and the implementation**: the diff in the tree is what the person verified. Re-read the
-issue (`pnpm josh issue:read <N>`), then run the gate **in full** from the refactor (`chain-rule.md` →
-"Run the review-to-merge chain") — a fix made during the manual check has had no gate — and ship as
-any `fullrun` does.
+**`fullrun #<N>` or `prrun #<N>` after a `halfrun` stop resumes it instead of claiming.** The stop is
+**recorded, never inferred**: the `halfrun` ends with `pnpm josh run:hold <N> --halfrun-stop`, marking
+its record (re-keying a `halfrun new`'s unnumbered one) — a `halfrun` still implementing or a
+`backlogrun` child leaves the same dirty tree and is not adopted. On a marked hold for `#<N>`,
+`run:entry` asks the session budget, adopts the hold and prints `entry #<N> — resume: halfrun`. **Skip
+the title, the plan, the split assessment, `pnpm josh ms`, `latest:scope` and the implementation**;
+re-read the issue (`pnpm josh issue:read <N>`), run the gate **in full** from the refactor
+(`chain-rule.md` → "Run the review-to-merge chain"), and ship as any `fullrun` does.
 
 ## The prrun resume
 
-**`fullrun #<N>` after a `prrun` stop resumes it the same way.** The `prrun`
-ends with `pnpm josh run:hold <N> --prrun-stop`, which writes the commit its pull request is on into its
-own record; only a record carrying that commit is adopted. `run:entry` asks the session budget, adopts
-the hold with the `fullrun` mark and prints one of three tokens — read, never inferred:
-
-- **`resume: prrun-merged`** — a person merged the pull request. Run `pnpm josh followup "<title>
-  #<N>"` alone: it detects the merge and runs only the post-merge tail.
-- **`resume: prrun-merge`** — the branch is still on the stop's commit, both here and on the pull
-  request, and the tree is clean, so what was verified is what would merge. Skip the gate and the
-  review; run `pnpm josh followup` to merge.
-- **`resume: prrun-gate`** — the branch moved (locally, or by a push made on GitHub), its pull request
-  could not be read, or the tree is dirty: a person changed something. Run the
-  gate **in full** and the review (`chain-rule.md` → "Run the review-to-merge chain"), then ship as any
-  `fullrun` does.
+**`fullrun #<N>` after a `prrun` stop resumes it the same way.** The `prrun` ends with `pnpm josh
+run:hold <N> --prrun-stop`, which records its pull request's commit; only a record carrying it is
+adopted. `run:entry` prints one of three tokens — read, never inferred:
+
+- **`resume: prrun-merged`** — a person merged it. Run `pnpm josh followup "<title> #<N>"` alone; it
+  runs only the post-merge tail.
+- **`resume: prrun-merge`** — branch and pull request still on the stop's commit, tree clean. Skip the
+  gate and the review; run `pnpm josh followup` to merge.
+- **`resume: prrun-gate`** — the branch moved, its pull request could not be read, or the tree is
+  dirty. Run the gate **in full** and the review (`chain-rule.md` → "Run the review-to-merge chain"),
+  then ship.
 
 All three skip the title, the plan, the split assessment and the implementation.

package/CLAUDE.md

@@ -7,13 +7,14 @@ Stack: TypeScript · pnpm · SvelteKit · Vitest · Playwright · TailwindCSS ·
 ## Communication
 
 - **Answer opinion-seeking questions from a neutral standpoint.** A leading question is not a cue to agree — recommend the option you genuinely judge best.
-- **Fix root causes, not symptoms.** Where the proper fix is out of scope, surface the root cause instead of papering over it.
+- **Fix root causes, not symptoms.** Where the proper fix is out of scope, surface it instead of papering over it.
 - **Cross-package problems → file the upstream Issue, then stop.** A defect in another package (a dependency, or `josh` / kit tooling) is never worked around locally — **weakening a verification gate is a workaround too**. File it (first-party Tier A, third-party Tier C) and stop. `prompts/collaboration-workflow/upstream-interrupt.md`. Your own repository's run tooling is not another package: `upstream-interrupt.md` → "実行中のリポジトリ自身のラン機構の不具合".
 - **Third-party repositories are Tier C.** Decide the party with `pnpm josh repo:party`; every write to a tracker we do not own needs explicit current-turn instruction. `prompts/collaboration-workflow/upstream-interrupt.md`.
 - **No clones — single-source, even across package boundaries.** Duplicate non-trivial logic only after presenting the alternative and getting explicit approval. `prompts/collaboration-workflow/principles.md` → "no-clones".
 - **Design for elegance and simplicity first.** Before adding a hook, guard, rule or abstraction, ask whether fixing the cause makes it unnecessary. `prompts/collaboration-workflow/principles.md` → "elegant-design"; conflicting quality goals → "quality-priority".
+- **Write concise prose: conditions and actions only.** `prompts/collaboration-workflow/principles.md` → "concise-prose".
 - **Distinguish consultation from execution.** A question or goal statement asks for analysis only — act on an explicit imperative or a workflow keyword. `prompts/collaboration-workflow/principles.md` → "consult-vs-execute".
-- **Route distributed-doc / config changes upstream to kit.** In a consumer repo never edit kit-distributed docs/config (`josh sync` overwrites them); in kit you are the source. `prompts/collaboration-workflow/principles.md` → "upstream-to-kit".
+- **Route distributed-doc / config changes upstream to kit.** In a consumer repo never edit kit-distributed docs/config; in kit you are the source. `prompts/collaboration-workflow/principles.md` → "upstream-to-kit".
 - **Latest-first, fix forward — pin back only as a last resort.** `prompts/collaboration-workflow/principles.md` → "latest-first".
 - **Output language follows `JOSH_SESSION_LANG`** (default `ja`) for session output and artifact prose; English for Issue/PR titles, code comments, test titles, commit messages and script strings. `prompts/collaboration-workflow/overview.md`.
 - **Durable rules belong in prompts/docs, not local MEMORY.** `prompts/collaboration-workflow/principles.md` → "durable-rules".
@@ -31,16 +32,16 @@ Log auto-decisions: an Issue comment in an Issue workflow, else a one-line "Auto
 
 ## Critical Conventions (non-standard — always apply)
 
-Naming, exports, file names and content rules are enforced by `eslint/rules/`; their single source is `prompts/coding-standards.md` → "Conventions". `function` syntax, not arrows (named SvelteKit route handlers may use the typed-const arrow idiom) — lint does not check it.
+Naming, exports, file names and content rules are enforced by `eslint/rules/`; their single source is `prompts/coding-standards.md` → "Conventions". `function` syntax, not arrows (named SvelteKit route handlers may use typed-const arrows); lint does not check it.
 
 ### Quality limits
 
-- Function complexity ≤5 · nesting ≤2 · function ≤25 lines · file ≤300 lines · params ≤4 · statements per function ≤10 · cognitive complexity ≤4 — line counts are code lines, not physical lines (`pnpm josh lint`); test files allow 35 code lines per function.
+- Function complexity ≤5 · nesting ≤2 · function ≤25 lines · file ≤300 lines · params ≤4 · statements per function ≤10 · cognitive complexity ≤4 — line counts are code lines, not physical lines; test functions allow 35 code lines.
 - No magic numbers beyond `0`, `1`, `-1` · no `any` · restricted `as` · explicit param and return types · single short early return → one-liner `if (x) return y`.
 
 ## Package-First Development
 
-Before building a feature, check for a well-maintained package — measure with `pnpm josh pkg:scout <keywords>`: `clear` → select it (Tier A), `close` → ask (Tier B).
+Before building a feature, run `pnpm josh pkg:scout <keywords>`: `clear` → use it (Tier A), `close` → ask (Tier B).
 
 ## Code Change Rules
 
@@ -82,5 +83,5 @@ Never start a `kickoff` / `halfrun` / `prrun` / `fullrun` / `backlogrun` workflo
 Before pausing **any** run for the user — a command's stop, an upstream-Issue interrupt, a Tier C confirmation — send once per stop (skip when the user asked for the stop this turn):
 
 ```bash
-pnpm josh notify --task-type confirmation --issue-url "<issue-url>" --body=$'<one-line reason>\n<what is needed from the user>'
+pnpm josh notify --task-type confirmation --issue-url "<url>" --body=$'<reason>' --recommended "<choice>" --alternative "<other>"
 ```

package/README.md

@@ -39,7 +39,7 @@ Next: [tutorial](./docs/tutorial.md)
 
 #### Your first backlogrun
 
-Tell the agent the change you want, then type `kickoff new` to it. The Issue gets the `auto-ok` label when it needs no judgement from you (or add the label to an existing Issue).
+File Issues with `kickoff new`, then run:
 
 ```bash
 pnpm josh backlogrun
@@ -59,14 +59,7 @@ Next: [tutorial](./docs/tutorial.md#without-github-one-change-checked-locally)
 
 ### Adding kit to an existing project
 
-- **Files written:** settings per profile, including Prettier — always on `full`, and on `basic` only when the project has web files and no formatter of its own ([per profile](./docs/init.md#project-profiles)); `--dry-run` previews them.
-- **Overwritten by `josh sync`:** the managed files, such as `.github/workflows/ci.yml` and `AGENTS.md` ([the list](./docs/sync.md#ai-files-overwritten)).
-- **Permissions:** the Claude Code settings kit writes (with `josh start`, or on `full`) set `bypassPermissions` with `Bash(*)`, guarded by a deny list and a hook ([how to opt out](./docs/init.md#claude-code-permission-mode)).
-- **On GitHub:** `josh start` adds labels, and on an existing `main` an Issue and a setup PR that you merge yourself ([the steps](./docs/init.md#josh-init-or-josh-start)).
-
-## Claude Code in a fresh-machine run
-
-A `josh fresh:run` scenario that runs Claude Code needs a sign-in saved once with `pnpm josh auth:setup` ([steps](./docs/maintainers/fresh-machine.md#claude-code)).
+Check first: [what kit changes in your project](./docs/how-to/add-kit.md#what-kit-changes-in-your-project)
 
 ## Docs