@joshuafolkken/kit 1.1514.0 → 1.2114.0

package/.claude/agents/investigator.md

@@ -1,6 +1,6 @@
 ---
 name: investigator
-description: Read-only investigation unit for the pre-implementation reading — finds out how an Issue's subject currently works and returns the conclusion with its `file:line` citations, never the file text. Dispatch it when `pnpm josh investigation:guard` asks for a delegated unit, or when `pnpm josh delegate investigation` answers `delegate`.
+description: Read-only investigation unit for the pre-implementation reading — finds out how an Issue's subject currently works and returns the conclusion with its `file:line` citations, never the file text. Dispatch it when the `investigation` row of `pnpm josh rule:list` asks for a delegated unit, or when `pnpm josh delegate investigation` answers `delegate`.
 tools: Read, Grep, Glob, Bash
 model: sonnet
 effort: low

package/.claude/agents/reviewer-verification.md

@@ -0,0 +1,19 @@
+---
+name: reviewer-verification
+description: The pre-commit review's round 2 (the verification pass) in one agent — the `reviewer` agent at the verification effort. Dispatch it for the round `pnpm josh review:brief --round 2` describes, with the `model` the brief prints.
+tools: Read, Grep, Glob, Bash, Edit, Write
+model: sonnet
+effort: high
+---
+
+You are the review itself, not a launcher of one. The brief you are handed is the whole
+`/code-review` invocation: the level on its first line, the rubric it names, the checkout it pins and
+its `review:attest` step.
+
+- Review the diff in this agent, against the rubric the brief names. You carry no `Skill` and no
+  `Agent` tool, so the review never forks a second agent that reads the same diff and brief again.
+- Run `pnpm josh review:attest <nonce>` from the checkout the brief pins, as the brief says. Never run
+  `pnpm josh review:brief` yourself: a new brief drops the attestation you left.
+- Apply a fix only where the brief's level and your dispatcher ask for one; never commit, stage or push.
+- Return the findings in the rubric's output format; check it first with `pnpm josh review:lint`
+  (round 2: `--round 2`; findings on stdin) and fix what it reports.

package/.claude/agents/reviewer.md

@@ -0,0 +1,19 @@
+---
+name: reviewer
+description: The pre-commit review in one agent — reads the `pnpm josh review:brief` it is handed, reviews the diff against the rubric the brief names, and runs the brief's `review:attest` step. Dispatch it for the `/code-review` round of `chain-rule.md` step 1, with the `model` the brief prints.
+tools: Read, Grep, Glob, Bash, Edit, Write
+model: opus
+effort: medium
+---
+
+You are the review itself, not a launcher of one. The brief you are handed is the whole
+`/code-review` invocation: the level on its first line, the rubric it names, the checkout it pins and
+its `review:attest` step.
+
+- Review the diff in this agent, against the rubric the brief names. You carry no `Skill` and no
+  `Agent` tool, so the review never forks a second agent that reads the same diff and brief again.
+- Run `pnpm josh review:attest <nonce>` from the checkout the brief pins, as the brief says. Never run
+  `pnpm josh review:brief` yourself: a new brief drops the attestation you left.
+- Apply a fix only where the brief's level and your dispatcher ask for one; never commit, stage or push.
+- Return the findings in the rubric's output format; check it first with `pnpm josh review:lint`
+  (round 2: `--round 2`; findings on stdin) and fix what it reports.

package/.claude/settings.json

@@ -1,6 +1,5 @@
 {
 	"permissions": {
-		"defaultMode": "bypassPermissions",
 		"allow": ["Bash(*)"],
 		"deny": [
 			"Bash(rm -rf *)",
@@ -54,7 +53,7 @@
 				"hooks": [
 					{
 						"type": "command",
-						"command": "if project_root=\"$(unset GIT_ALTERNATE_OBJECT_DIRECTORIES GIT_COMMON_DIR GIT_DIR GIT_INDEX_FILE GIT_NAMESPACE GIT_OBJECT_DIRECTORY GIT_WORK_TREE; git rev-parse --show-toplevel 2>/dev/null)\"; then unset GIT_ALTERNATE_OBJECT_DIRECTORIES GIT_COMMON_DIR GIT_DIR GIT_INDEX_FILE GIT_NAMESPACE GIT_OBJECT_DIRECTORY GIT_WORK_TREE; else project_root=\"$(git rev-parse --show-toplevel)\"; fi && cd \"$project_root\" && sh scripts/hooks/run-hook.sh audit-provision",
+						"command": "export JOSH_HOOK_CWD=\"$PWD\" && project_root=\"${CLAUDE_PROJECT_DIR:-$( (unset GIT_ALTERNATE_OBJECT_DIRECTORIES GIT_COMMON_DIR GIT_DIR GIT_INDEX_FILE GIT_NAMESPACE GIT_OBJECT_DIRECTORY GIT_WORK_TREE; git rev-parse --show-toplevel 2>/dev/null) || git rev-parse --show-toplevel)}\" && cd \"$project_root\" && sh scripts/hooks/run-hook.sh audit-provision --session-start",
 						"timeout": 180
 					}
 				]
@@ -66,7 +65,7 @@
 				"hooks": [
 					{
 						"type": "command",
-						"command": "if project_root=\"$(unset GIT_ALTERNATE_OBJECT_DIRECTORIES GIT_COMMON_DIR GIT_DIR GIT_INDEX_FILE GIT_NAMESPACE GIT_OBJECT_DIRECTORY GIT_WORK_TREE; git rev-parse --show-toplevel 2>/dev/null)\"; then unset GIT_ALTERNATE_OBJECT_DIRECTORIES GIT_COMMON_DIR GIT_DIR GIT_INDEX_FILE GIT_NAMESPACE GIT_OBJECT_DIRECTORY GIT_WORK_TREE; else project_root=\"$(git rev-parse --show-toplevel)\"; fi && cd \"$project_root\" && sh scripts/hooks/run-hook.sh session-lang",
+						"command": "export JOSH_HOOK_CWD=\"$PWD\" && project_root=\"${CLAUDE_PROJECT_DIR:-$( (unset GIT_ALTERNATE_OBJECT_DIRECTORIES GIT_COMMON_DIR GIT_DIR GIT_INDEX_FILE GIT_NAMESPACE GIT_OBJECT_DIRECTORY GIT_WORK_TREE; git rev-parse --show-toplevel 2>/dev/null) || git rev-parse --show-toplevel)}\" && cd \"$project_root\" && sh scripts/hooks/run-hook.sh session-lang",
 						"timeout": 10
 					}
 				]
@@ -78,7 +77,7 @@
 				"hooks": [
 					{
 						"type": "command",
-						"command": "if project_root=\"$(unset GIT_ALTERNATE_OBJECT_DIRECTORIES GIT_COMMON_DIR GIT_DIR GIT_INDEX_FILE GIT_NAMESPACE GIT_OBJECT_DIRECTORY GIT_WORK_TREE; git rev-parse --show-toplevel 2>/dev/null)\"; then unset GIT_ALTERNATE_OBJECT_DIRECTORIES GIT_COMMON_DIR GIT_DIR GIT_INDEX_FILE GIT_NAMESPACE GIT_OBJECT_DIRECTORY GIT_WORK_TREE; else project_root=\"$(git rev-parse --show-toplevel)\"; fi && cd \"$project_root\" && sh scripts/hooks/run-hook.sh pretool-guard",
+						"command": "export JOSH_HOOK_CWD=\"$PWD\" && project_root=\"${CLAUDE_PROJECT_DIR:-$( (unset GIT_ALTERNATE_OBJECT_DIRECTORIES GIT_COMMON_DIR GIT_DIR GIT_INDEX_FILE GIT_NAMESPACE GIT_OBJECT_DIRECTORY GIT_WORK_TREE; git rev-parse --show-toplevel 2>/dev/null) || git rev-parse --show-toplevel)}\" && cd \"$project_root\" && sh scripts/hooks/run-hook.sh pretool-guard",
 						"timeout": 20
 					}
 				]
@@ -90,7 +89,7 @@
 				"hooks": [
 					{
 						"type": "command",
-						"command": "if project_root=\"$(unset GIT_ALTERNATE_OBJECT_DIRECTORIES GIT_COMMON_DIR GIT_DIR GIT_INDEX_FILE GIT_NAMESPACE GIT_OBJECT_DIRECTORY GIT_WORK_TREE; git rev-parse --show-toplevel 2>/dev/null)\"; then unset GIT_ALTERNATE_OBJECT_DIRECTORIES GIT_COMMON_DIR GIT_DIR GIT_INDEX_FILE GIT_NAMESPACE GIT_OBJECT_DIRECTORY GIT_WORK_TREE; else project_root=\"$(git rev-parse --show-toplevel)\"; fi && cd \"$project_root\" && sh scripts/hooks/run-hook.sh format-edited",
+						"command": "export JOSH_HOOK_CWD=\"$PWD\" && project_root=\"${CLAUDE_PROJECT_DIR:-$( (unset GIT_ALTERNATE_OBJECT_DIRECTORIES GIT_COMMON_DIR GIT_DIR GIT_INDEX_FILE GIT_NAMESPACE GIT_OBJECT_DIRECTORY GIT_WORK_TREE; git rev-parse --show-toplevel 2>/dev/null) || git rev-parse --show-toplevel)}\" && cd \"$project_root\" && sh scripts/hooks/run-hook.sh format-edited",
 						"timeout": 90
 					}
 				]
@@ -102,7 +101,7 @@
 				"hooks": [
 					{
 						"type": "command",
-						"command": "if project_root=\"$(unset GIT_ALTERNATE_OBJECT_DIRECTORIES GIT_COMMON_DIR GIT_DIR GIT_INDEX_FILE GIT_NAMESPACE GIT_OBJECT_DIRECTORY GIT_WORK_TREE; git rev-parse --show-toplevel 2>/dev/null)\"; then unset GIT_ALTERNATE_OBJECT_DIRECTORIES GIT_COMMON_DIR GIT_DIR GIT_INDEX_FILE GIT_NAMESPACE GIT_OBJECT_DIRECTORY GIT_WORK_TREE; else project_root=\"$(git rev-parse --show-toplevel)\"; fi && cd \"$project_root\" && sh scripts/hooks/run-hook.sh stop-guard",
+						"command": "export JOSH_HOOK_CWD=\"$PWD\" && project_root=\"${CLAUDE_PROJECT_DIR:-$( (unset GIT_ALTERNATE_OBJECT_DIRECTORIES GIT_COMMON_DIR GIT_DIR GIT_INDEX_FILE GIT_NAMESPACE GIT_OBJECT_DIRECTORY GIT_WORK_TREE; git rev-parse --show-toplevel 2>/dev/null) || git rev-parse --show-toplevel)}\" && cd \"$project_root\" && sh scripts/hooks/run-hook.sh stop-guard",
 						"timeout": 20
 					}
 				]

package/.claude/skills/dependency-update/SKILL.md

@@ -34,16 +34,15 @@ over-bumped entry: restore it immediately, investigate, and report — never kee
 
 ## 3. `devEngines` — the one expected change
 
-**Exception — the `josh latest` lockstep pnpm bump is expected, NOT a violation.** **KEEP** a
-`devEngines.packageManager.version` change **if and only if** it equals everything after `pnpm@` in
-the new `packageManager` pin — **byte-identical, `+sha512…` Corepack integrity suffix included**
-(`scripts/version/latest-corepack.ts` → `sync_development_engines`). Reverting it would re-introduce
-the mismatch.
-
-**Restore + ask** when `devEngines` changed any other way: the version no longer matches
-`packageManager` (a dropped or truncated suffix counts), its structure changed (`name` / `onFail` /
-fields), or something other than `josh latest` touched it. One structural change is expected and
-kept: `josh sync` moving `devEngines.packageManager.onFail` from `"error"` to `"download"`.
+**Read the verdict line, never compare by eye.** `pnpm josh overrides` prints it first, and
+`josh latest` prints it after its pnpm bump — `HEAD`'s `package.json` against the working tree
+(`scripts/version/development-engines-verdict.ts`). Quote it:
+
+- `devEngines: unchanged` / `devEngines: kept` — keep. `kept` is the lockstep pnpm bump (the version
+  byte-identical to the `packageManager` pin, `+sha512…` suffix included) or `josh sync` moving
+  `onFail` from `"error"` to `"download"`.
+- `devEngines: restore (<reason>)` — restore + ask. Also restore when something other than
+  `josh latest` / `josh sync` touched it.
 
 ## 4. When the bump breaks something — fix forward
 

package/.claude/skills/epic-commands/SKILL.md

@@ -29,9 +29,8 @@ Recording a decision removes that child's `needs-decision` label (Tier A; `backl
 
 - **Decided as a child joins the epic**: `pnpm josh epic --add … --decision-file` writes both
   (`epic-bundle.md`).
-- **About a child the epic already tracks**: that flag refuses an insertion with nothing to add.
-  Comment on each child with `pnpm josh issue:comment <N> --body-file <path>`, and **say in the report
-  that the epic's `## Decisions` entry is still pending**.
+- **About a child the epic already tracks**: `pnpm josh epic --decide <E> <N...> --decision-file
+  <path|->` writes the entry, the comments and the label removal; a rerun writes nothing twice.
 
 ```md
 ## Decisions
@@ -57,28 +56,17 @@ pnpm josh epic "<epic-title>" <N1> <N2> ... --ordered  # argument order is the d
 ```
 
 After any hand edit run `pnpm josh epic:check <E>` (exit 1 when the body no longer parses).
-`pnpm josh followup` closes the epic once every task-list child is closed; one tracking a
-cross-repository child is closed by hand. Without `josh`: `issue-template.md`.
+The epic closes once every task-list child is closed, whichever path closes the last child
+(`pnpm josh followup`, `josh issue:measured`, `josh run:merge`); one whose last child a person
+closed (`already-done`) closes at the next of those closes, for any child. One with a child whose
+state cannot be read is closed by hand. Without `josh`: `issue-template.md`.
 
 ## `josh epic:audit <E>` — contradictions across the children
 
 `epic:check` verifies the format; this verifies the children agree. Run it **without being asked**
 when a `backlogrun` starts a named epic's children, and right after a child is added or a dependency
-changed. Cycle and declaration checks are reused from `epic:next`; it adds:
-
-| Check | Level |
-| --- | --- |
-| A child's body names another child, nothing orders the two | warning |
-| A child's **acceptance criteria** name another child, nothing orders the two | **error**; a warning once both are closed or when the pair spans two repositories — the child is still offered as runnable until the relation is recorded |
-| A body cites a missing or already-closed issue | warning |
-| A task-list row points at another **epic** | warning — `epic:next` already withholds the row; a person should look |
-| An issue names this epic as parent that the task list does not track | warning |
-| The search for those issues could not read the open backlog | **error** |
-| That search stopped before the end of the backlog | warning |
-
-**Only errors fail it** (exit 1). A forward reference the other child already depends on is not
-reported. A pair is demoted to a warning only when the closed state is **confirmed** (any state but
-`CLOSED` normalizes to `OPEN`).
+changed. **Only errors fail it** (exit 1); the checks are `docs/josh-commands-backlog.md` →
+"`josh epic:audit`".
 
 **Fixing what it finds is Tier A** — fix it and record why on the issue. Park with `needs-decision`
 only for a design choice nobody has made.
@@ -87,37 +75,24 @@ The two `orphan search` findings are about the search, not the children:
 
 - `✖ orphan search: Could not list the open issues…` — **re-run the audit**; nothing to fix or decide.
   If it keeps failing, check `gh auth status` and the rate limit.
-- `⚠ orphan search: The open-issue scan hit its …` — only the newest 500 issues (or 50 bodies) were
-  covered; the audit passes. Look further by hand if an orphan is expected.
+- `⚠ orphan search: The open-issue scan hit its …` — the audit passes. Look further by hand if an
+  orphan is expected.
 
-**It cannot check** that when a child introduces a new label, command, state or artifact, some child
-owns updating the existing code referencing that concept — do that at planning. Label names live in
-`scripts/issue/issue-labels.ts`.
+**That a child introducing a new label, command, state or artifact updates the existing code
+referencing it is checked at planning**, not here: each plan's `### 影響を受ける既存の利用者` section,
+drafted by `pnpm josh plan:consumers` and required by `issue:plan`, names every consumer and which
+issue fixes it. Label names live in `scripts/issue/issue-labels.ts`.
 
 ## `josh epic:next <E…>` — what is runnable
 
-Returns **every** runnable child, bundled per repository with its local checkout. `--repo <owner/repo>`
-narrows to one and prints a single token (an issue number or the verdict); `--lanes` beside it prints
-one number per line, **up to the number of free lanes in that repository**.
+Returns **every** runnable child, bundled per repository with its local checkout; several epics answer
+as one pool, prioritized in the order they were named. How it weighs blockers, lanes and nested epics:
+`docs/josh-commands-backlog.md` → "`josh epic:next`".
 
-- **Several epics answer as one**: every argument before the first flag is an epic; their runnable
-  children merge into one pool per repository. **Priority is the order the epics were named**, then
-  each epic's own task-list order (its declared chain still decides what is runnable).
 - **Reorder with `pnpm josh epic --add <E> <N> --order-before <M>`** (or `--order-after <M>`), never a
-  hand edit; declarations and `blocked-by` relations stay as they were. Moving a row does not free a
-  child a chain still holds — the command prints a ⚠️ line instead.
-- **A child two epics track enters once**, kept by the epic named earlier.
-- **One unusable graph refuses the whole answer**; **one reference that does not parse fails the
-  read**. Worked form: `docs/josh-commands-backlog.md` → "`josh epic:next`".
-
-**An `in-progress` issue occupies a lane, not the repository.** Free lanes are `JOSH_LANE_LIMIT`
-(**default 4**) minus that repository's `in-progress` listing. At zero the answer is `wait`, with the
-holders on standard error. A parked child releases its lane; a `needs-human-review` stop keeps it.
-
-**A child that is itself an epic is never offered** and waits on a *person*. The test is the child's
-`epic` label, never how its row is written: a cross-repository `owner/repo#N` row that is not an epic
-stays runnable. **A parent epic over another epic never auto-closes** (a grandchild's merge never
-reaches it); `epic:audit` reports the row.
+  hand edit. Moving a row does not free a child a chain still holds — the command prints a ⚠️ line.
+- **Order two epics with a native `blocked-by` relation and name both** — `epic:next <E1> <E2>`, or
+  `backlog:next`.
 
 Children that are not runnable are sorted by **whether waiting helps**, never by label:
 
@@ -127,47 +102,33 @@ Children that are not runnable are sorted by **whether waiting helps**, never by
 | Waiting on time | Wait and ask again |
 | Waiting on a person | Stop and report |
 
-**A blocker outside every named epic is weighed**: closed, it resolves (cross-repository: after its
-release); open and tracked by an epic named in the same call, the child waits on time (or on a person,
-if the blocker does); open and untracked, the child waits on a person and the blocker is named on
-standard error; an unknown state reads as waiting. **Order two epics with a native `blocked-by`
-relation and name both** — `epic:next <E1> <E2>`, or `backlog:next`.
-
 Two things stop the command: a **circular dependency**, and a **disagreement between the epic body
 and the `blocked-by` relations**. Only a line that is *nothing but* a chain is a declaration — a prose
 line recommending an execution order is a suggestion, not a dependency.
 
 ## Epics that span repositories
 
-Write cross-repository children as `owner/repo#N` or a full issue URL. Their state is read through
-`gh api`, so **no local clone is needed to learn it** — only to implement.
+Write cross-repository children as `owner/repo#N` or a full issue URL; **no local clone is needed to
+learn their state** — only to implement.
 
 - **The owner restriction is inherited unchanged**: a different owner is never a target.
-- **The epic auto-closes only when every cross-repository child's state could be read.**
 - **An epic in another repository is referenced as `owner/repo#N`** — `backlogrun
   joshuafolkken/kit#<E> --only`, `epic:next joshuafolkken/kit#<E> --repo joshuafolkken/app-kit`. A
   bare `#N` is this repository's issue.
-- **`epic:next` prints each candidate's local checkout**; none prints `(no local checkout)` and is
-  **never cloned on its own**.
-
-**A cross-repository dependency resolves only when the blocker is closed and the version its default
-branch declares is in the registry** (checked in that order; that exact version). A child no longer
-bumps the version, so the target is the release that includes the blocker. **Unless that repository
-publishes nothing**: no `package.json` on its default branch, or `private`, resolves on close — read
-from its manifest, never the registry; a failed manifest read (not a 404) still waits. The publish
-check is `josh propagate`'s.
+- **A candidate printed `(no local checkout)` is never cloned on its own.**
 
 ## `josh epic:bundle <N>` — does this new issue belong with one already filed?
 
 Runs right after any filing; **`pnpm josh issue:file` runs it as its last step** — run it by hand only
-when that step printed `⚠`. **It recommends; it writes nothing.**
+when that step printed `⚠`. **It recommends and writes nothing; `--apply` writes an `add_to_epic` /
+`create_epic` answer.**
 
 | Candidates | Do | Tier |
 | --- | --- | --- |
 | **The new issue itself already has an epic** | Nothing — an issue belongs to at most one | — |
 | Already a child of an epic | Add to **that** epic; do not create a second | A |
 | Spread across an epic and its **own parent** | Add to the inner epic — the parent already contains it | A |
-| Spread across **different** epics | **Choose the one you recommend, add to it, and record why** | **A** |
+| Spread across **different** epics | **Choose the one you recommend** (`epic-bundle.md`) | **A** |
 | In no epic, two or more counting the new issue | Create an epic | A |
 | No strong signal | Nothing | — |
 | **The epic listing was cut short** | **Nothing** — every placing row above is withheld | — |

package/.claude/skills/epic-commands/epic-bundle.md

@@ -39,6 +39,8 @@ Could not confirm which epic already tracks these — do not place this issue in
 It prints no children or order. What survives the cut is a membership that *was* found (the table's
 first row).
 
+**`pnpm josh epic:bundle <N> --apply` writes `add_to_epic` / `create_epic`**; `ask` is placed below.
+
 **Placing an issue is not merging epics.** Choosing between two candidate epics is Tier A: take the one
 you recommend and write the decision (taken, rejected, why, date) on **both** the issue and the epic's
 `## Decisions`. **Merging two epics is a different action, and nothing here proposes it.**
@@ -56,7 +58,7 @@ written:
   order in backticks or a fenced block.
 - **An empty record, or `--decision-file` with no usable path.**
 
-For children the epic already tracks: `SKILL.md` → "Recording a decision".
+Children already tracked: `pnpm josh epic --decide` (`SKILL.md` → "Recording a decision").
 
 **Its sibling runs before the filing: `pnpm josh issue:scout "<title>"`** — the same epic question for
 an issue not yet filed, plus whether the work is already filed. **Both run**: `pnpm josh issue:file`

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

@@ -45,12 +45,12 @@ Each is fetched at its named scope, in the same turn, by the named command that
 
 | Document                | Read it when                                                                   |
 | ----------------------- | ------------------------------------------------------------------------------ |
-| `latest-gate.md`        | `pnpm josh latest:scope` answers `required` — before `josh latest` runs         |
+| `latest-gate.md`        | `run:prep` answers `latest: required` — before `josh latest:if-required` runs  |
 | `followup.md` → "Run `pnpm josh followup`" | Before issuing `pnpm josh followup`, in that same turn |
-| `chain-rule.md` → "Run the review-to-merge chain" | Before the first `pnpm josh gate` launch (`fullrun` / `prrun` / `backlogrun`) — the gate overlaps the review, so the section is read before it |
+| `chain-rule.md` → "Run the review-to-merge chain" | Before the first `pnpm josh gate` launch (`fullrun` / `prrun` / `backlogrun`; a lane child reads "A lane child" alone) — the gate overlaps the review |
 | `background-commands.md` → "Background the gate and push" | Before backgrounding `pnpm josh gate` — the first long-running command a run detaches (`fullrun` / `halfrun` / `prrun` / `backlogrun`) |
 
-A `skip` answer from `latest:scope` reads nothing. **A lane child that parks reads
+A `latest: skip` answer reads nothing. **A lane child that parks reads
 `backlogrun-park.md` → "park and continue" at that point of use**, and **every implementing run reads
 `progress-watcher.md` → "Progress while the run is quiet"** before starting `pnpm josh run:progress
 --wait` once its hold is claimed.
@@ -75,22 +75,22 @@ from — read at that trigger, never restated here.
 | --- | --- | --- |
 | First call of any entry | `#N`: `pnpm josh run:entry <N> --to <command>` (claims the tree, except `kickoff`); `new` (not `kickoff`): `pnpm josh run:hold`; `busy` / `unknown` stop | `working-tree-hold.md` |
 | `run:entry` prints its stage line | The command sets how far a run goes, the Issue where it starts; **`start: reached` redoes nothing** — stop (at `merged`, the next line answers) | `docs/how-to/run-issues.md` |
-| Same turn as the hold (not a dispatched child, not `kickoff`) | `pnpm josh cost --cut`; `under` continues, `over` stops — `run:entry` notifies and runs `run:release` (by hand for `new`) | `backlogrun-progress.md` → "The hand-off" (shared 135,000 threshold) |
+| Same turn as the hold (not a dispatched child, not `kickoff`) | `pnpm josh cost --cut`; `under` continues, `over` stops — `run:entry` notifies and runs `run:release` (by hand for `new`) | `backlogrun-progress.md` → "The hand-off" (model-priced threshold) |
 | An entry typed with an `owner/repo#` prefix or a short `repo#` name | Resolve the target and its checkout; an explicit foreign owner stops the run | `target-repository.md` |
 | A `new` entry typed with an `into <target>` suffix | Insert the artifact into the named epic with `pnpm josh epic --add <E> <N>` | `into-target.md` |
 | Before any work starts (every entry) | The split assessment; the default is not to split — separability **and** a scope clearly over one gate must hold together; a `fullrun` / `halfrun` that finds a split files the epic and **stops** | `split-assessment.md` → "The question" |
-| Before implementing (every `#N` entry) | `pnpm josh issue:read <N>` — the body and the comments; the later of a body and a comment wins | `issue-comments.md` |
-| `pnpm josh issue:state <N>` answers `human_review: yes` | Implement and gate, then stop before the commit; the label is applied only by a person | `needs-human-review.md` |
-| Before implementing (every implementing entry) | `pnpm josh latest:scope`; on `required` read the doc and run `josh latest`, then load the `dependency-update` skill; `kickoff` never reaches it | `latest-gate.md` (read whole, only on `required`) |
+| Before implementing (every implementing entry) | `pnpm josh run:prep <N>` (`run:entry` bundles it; `kickoff` reads `pnpm josh issue:read <N>`) — the body and the comments; the later of a body and a comment wins | `issue-comments.md` |
+| `run:prep` answers `human_review: yes` | Implement and gate, run `pnpm josh test:e2e`, then stop before the commit with `pnpm josh run:hold <N> --human-review-stop`; the label is applied only by a person | `needs-human-review.md` |
+| `run:prep` answers `latest: required` | Read the doc and run `pnpm josh latest:if-required`, then load the `dependency-update` skill | `latest-gate.md` (read whole, only on `required`) |
 | Before delegating any run step | `pnpm josh delegate <step>` decides eligibility, never you | `delegation.md` |
 | The pre-implementation reading reaches 3 unedited files | Delegate the unread investigation; a file this run will edit is read in the main line | `delegation.md` → "The pre-implementation reading" |
 | Immediately before implementation | Present the two-layer work summary (once per Issue); `kickoff` posts a plan instead | `prompts/collaboration-workflow/report-format.md` |
-| While implementing | Re-run one check by name, not the whole gate — `pnpm josh lint:related`, `pnpm josh cspell:dot`, `pnpm josh test:related`; `pnpm josh review:brief` refuses a brief on a tree the last two were not green on | `chain-rule.md` |
-| Implementation is done | Refactor → `pnpm josh main:merge` → `pnpm josh gate` beside a subagent `/code-review`, joined before the commit → round cap → PR → merge | `chain-rule.md` → "Run the review-to-merge chain" |
+| While implementing | Re-run one check by name, not the whole gate — `pnpm josh lint:related`, `pnpm josh cspell:dot`, `pnpm josh test:related --touched` (full reach once the implementation is done); `pnpm josh review:brief` refuses a brief on a tree the last two were not green on | `chain-rule.md` |
+| Implementation is done | Refactor → `main:merge` (no lane child) → `pnpm josh gate` beside a subagent `/code-review`, joined before the commit → round cap → PR → merge | `chain-rule.md` → "Run the review-to-merge chain" |
 | A review has run | Its verdict counts only once `pnpm josh review:attest --check` answers `ok`; `missing` / `mismatch` are refusals `pnpm josh followup` blocks the merge on | `chain-rule.md` → "The brief names the checkout, and a review that read another one is refused" |
 | A command can take minutes | Issue it in the background; the turn never ends at the push (`pnpm josh followup` stays foreground) | `background-commands.md` → "Background the gate and push" |
 | E2E gate | The CI E2E job where the command ends in a PR (`fullrun` / `prrun` / `backlogrun`, enforced by `pnpm josh followup`); you run `pnpm josh test:e2e` yourself where it does not (`halfrun`) | `prompts/testing-guide.md` → "Closing the E2E gate without a human run" |
-| Filing any new Issue | `pnpm josh issue:file` — it runs the `issue:scout` scan first; read its duplicate and epic answers | `issue-scout.md` |
+| Filing any new Issue | `pnpm josh issue:file` — it runs the `issue:scout` scan; read its duplicate and epic answers | `issue-scout.md` |
 | Another Issue here must land first | A prerequisite is a dependency, not a park — file it, stash, record the dependency; `fullrun` / `halfrun` stop, `backlogrun` continues | `prerequisite.md` |
 | Something worth filing, none of the three | Unattended: file it (Tier A, first-party); else ask; a delegated child returns it to the parent instead | `observation-filing.md` |
 | A defect in kit's own verification turns up | It runs alone when all three conditions hold; a batch resumes once it merges | `backlogrun-lanes.md` → "A solo run" |
@@ -98,7 +98,7 @@ from — read at that trigger, never restated here.
 | `backlogrun`'s authorization | The whole `auto-ok` opted-in pool as well as its named items; `pnpm josh backlog:next` offers them | `backlogrun.md` |
 | `run:step` prints the retrospective step (a run drained its backlog and stopped, not a lane child) | Run what it prints once, file 0–2 improvements, then `pnpm josh run:carry --retrospective` | `retrospective.md` |
 | Any artifact prose (Issue bodies, comments, Telegram) | Session language (`JOSH_SESSION_LANG`, default `ja`); Issue/PR titles stay English | `prompts/collaboration-workflow/overview.md` |
-| Any mid-workflow stop | `stop:guard` sends the `confirmation` Telegram; on its refusal, send it | `CLAUDE.md` → "Mid-workflow stop notification" |
+| Any mid-workflow stop | `stop:guard` sends the `confirmation` Telegram; on its refusal, send it | `rule-delivery.md` → "stop-notify" |
 
 ## 3. What stays resident, and what is read from here
 

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

@@ -4,10 +4,12 @@
 
 - **The clean path folds the region into one backgrounded `pnpm josh ship`** (preflight → gate → `git -y` →
   foreground `followup` → `run:tail`). The calls below serve a due second round.
-- Background `pnpm josh gate` beside the review; join it before commit.
+- Background `pnpm josh gate` beside the review; join it before commit. Also `lint:related` /
+  `test:related` / `check:related` / `metrics` with work to overlap: a wait past the 5-min cache TTL
+  rewrites the context.
 - Issue `pnpm josh git -y` in the background; its completion resumes the run, so the turn never ends
   at the push.
-- Keep `pnpm josh followup` in the foreground — nearly every following step reads its result.
+- `pnpm josh followup` stays in the foreground (`followup.md`).
 - **Record before the CI wait ends, never after the merge**: the commit
   carries the observation ledger lines recorded so far, and while CI runs the run makes the records
   that need no CI result — observation Issues, the completion report draft.
@@ -16,18 +18,19 @@
   session-cost check after the merge.
 - A lane child's hand-off or pre-gate cut is the sole turn boundary before the push (`chain-rule.md`).
 
-Use harness detachment so completion returns to the run. Foreground timeouts stay within the cap.
-
 ## How the wait ends — the task's exit, never a regex over its output
 
 **Background it from the first, then end the turn.** A `run_in_background` command re-invokes the run
 when it *exits* — that completion notification is what ends the wait, not a regex match or the block
-limit.
+limit. A backgrounded `Agent` → the same; in a lane child → the `lane-background` row of `pnpm josh rule:list`.
 
-**Never hand-write a `while`/`until` … `sleep` loop over the output file** — a regex that never matches
-waits to the block limit, one that matches a mid-run line exits early. `pnpm josh rule:guard` refuses it
+**Never hand-write a `while`/`until` … `sleep` loop over the output file, or a counted `for` that sleeps** — a regex that never matches
+waits to the block limit, one that matches a mid-run line exits early. the `poll-loop` row of `pnpm josh rule:list` refuses it
 (`prompts/collaboration-workflow/rule-delivery.md`).
 
+Nor a `sleep` chain followed by a read before the completion notification (`sleep 20; tail …/x.output`,
+`sleep 20; ps -p <pid>`) — the same poll unrolled; the same row refuses it.
+
 **To glance at interim output, `Read` the output file once**, never in a sleep loop. CI is waited on by
 `pnpm josh followup`; a progress heartbeat is `run:progress --wait`'s job (`early-heartbeat` refuses a
 hand-armed timer).
@@ -59,8 +62,8 @@ merge result?**
 | `pnpm josh followup` | Nothing — it is foreground. **The post-merge tail is taken before the call**: compose the epic progress counters first, and leave after the merge only the steps that read its result, plus `pnpm josh cost --cut` |
 
 **The turn never ends at the push.** The `pnpm josh git -y` completion resumes the run, and that turn
-goes straight through any branch-2 filing and `pnpm josh epic:bundle` to `pnpm josh followup`. `pnpm
-josh rule:guard` refuses the foreground push (`prompts/collaboration-workflow/rule-delivery.md`); the
+goes straight through any branch-2 filing and `pnpm josh epic:bundle` to `pnpm josh followup`. the
+`run-tail` row of `pnpm josh rule:list` refuses the foreground push (`prompts/collaboration-workflow/rule-delivery.md`); the
 push reissued detached is not refused again.
 
 **One turn does end before the push: a dispatched lane child's pre-gate cut** — `pre-gate-cut.md` →
@@ -68,7 +71,7 @@ push reissued detached is not refused again.
 
 **A headless lane child (`claude -p`) is where "a background command re-invokes the run" does not
 hold: its background Bash tasks are killed when its turn ends.** It hands the gate-to-merge region to a
-foreground `pnpm josh ship --detach` (`chain-rule.md` step 0); `pnpm josh rule:guard` refuses a
+foreground `pnpm josh ship --detach` (`chain-rule.md` step 0); the `lane-background` row of `pnpm josh rule:list` refuses a
 backgrounded `josh gate` / `git` / `followup` / `ship` there, and the `Stop` hook sends a child with a
 task still running back to wait.
 

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

@@ -15,8 +15,9 @@ or a split found mid-run does **not** stop it:
 
 1. File the new Issue(s) — `route:split` for a split, `route:tier-a` for a prerequisite — no
    confirmation.
-2. **Stash and remove `in-progress`**, as steps 2 and 4 of "A prerequisite discovered mid-run" do:
-   `git stash push -u -m "..."`, a `gh api repos/{owner}/{repo}/issues/<N>/comments` post recording the
+2. **Stash and remove `in-progress`**: for a prerequisite `<P>`, `pnpm josh run:pause <N> --for <P>`
+   (`prerequisite.md`), which also records the dependency step 3 would; for a split,
+   `pnpm josh stash:push "..."`, `pnpm josh issue:comment <N> --body-file <path>` recording the
    stash, and `pnpm josh run:release <N>`.
 3. **Ask `pnpm josh epic:bundle <N>` whether an epic already tracks `#<N>` before creating one.**
 
@@ -44,7 +45,7 @@ or a split found mid-run does **not** stop it:
 5. **Do not stop.** Continue into the loop against `#<E>`.
 
 - **Nothing found means no epic** — the run finishes at `#<N>`'s merge.
-- **Every guard applies unchanged** — 30 children, 10 Issues filed, 3 consecutive failures.
+- **Every guard applies unchanged** (`backlogrun.md` → "Guards").
 - **`fullrun` does not promote itself** — it files and **stops** (`split-assessment.md` → "Finding a
   split mid-run stops the run"). `josh epic:next` still refuses an Issue with no task list.
 - **A bare Issue named beside an epic is a mistyped command.** Named alone, the refusal is the answer;
@@ -65,6 +66,8 @@ unit, run the child in the parent's context and still ask the hand-off at every
 - **The brief names the invocation it descends from** — e.g. `backlogrun #<E> --only`, the child
   number, and that it runs as `fullrun #<N>` under that authorization; the unit refuses a brief without
   it.
+- A child whose ship waits on its merge frees its lane — the next child launches beside it, and a
+  stop at `followup` relaunches the child at most one lane past the limit: `run-ship-place.ts`.
 
 ### What the summary carries, and how long it may be
 
@@ -75,6 +78,8 @@ unit, run the child in the parent's context and still ask the hand-off at every
   delegated child does not take this route"); decisions not yet logged; what was left undone, on whose
   authority.
 - **Cut**: the changed-file list, per-round review detail, restated rules.
+- Before the final message → `pnpm josh report:lint --child-summary < summary.md` (labels in the
+  session language).
 
 The person-facing report (`prompts/collaboration-workflow/report-format.md` → 「完了報告（セッション向け）」)
 is unchanged.
@@ -93,14 +98,13 @@ creates the epic. Errors stop the run; warnings are read and passed. Fixing a fi
 
 ## `josh latest` runs once per session, not once per child
 
-Ask once, the first time the loop hands back a child number, before implementing it:
+Run once, the first time the loop hands back a child number, before implementing it:
 
 ```bash
-pnpm josh latest:scope   # → required | skip ; the reason on stderr
-git stash push -u -m "backlogrun: josh latest #<N>"        # only if the tree has staged or modified files — never conditional on the answer
+pnpm josh stash:push "backlogrun: ms #<N>"   # `clean` when nothing changed
 pnpm josh ms
-pnpm josh latest         # on `required` only
-pnpm josh stash:pop "backlogrun: josh latest #<N>"         # only if you stashed above — by message, not a positional pop
+pnpm josh stash:pop "backlogrun: ms #<N>"    # only after `stashed` above
+pnpm josh latest:if-required                 # stash → josh latest → pop; nothing on `skip`
 ```
 
 On `required`, load the `dependency-update` skill; `latest-gate.md` is the single source. A resumed

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

@@ -1,29 +1,11 @@
 # `backlogrun` — the hand-off report
 
-The format of the report a `backlogrun` writes when it hands the rest of a batch to a new session —
-read when the run stops at the hand-off (`backlogrun-progress.md` → "The hand-off"). The two-layer
-structure and the label translations are `prompts/collaboration-workflow/report-format.md`.
+Read when the run stops at the hand-off (`backlogrun-progress.md` → "The hand-off").
 
-**The hand-off is a fourth kind of stop — not a completion, a park or a failure.**
-**It never uses `Cause` / `Fix` / `Result`**: an unfinished epic would read as finished.
+**Run `pnpm josh run:report --handoff`, and relay what it prints.** It prints the hand-off report
+from `run:carry` and `cost --cut`, and sends the same text as the `confirmation` Telegram, the resume
+command as its `--recommended`. Nothing in it is written by hand. A send that did not go out is
+named on stderr; the printed report is still the hand-off.
 
-```md
-**■ 区切り**
-
-- **終わったこと**: <このセッションでマージした子を番号で名指しする>
-- **残っていること**: <残りの子を件数と番号で名指しする。park した子はその旨も>
-- **止めた理由**: <なぜここで区切ったか。判断ではなくコマンドの答えを書く>
-- **次に打つコマンド**: <このランを再開するコマンド。`backlogrun` なら残りだけの `backlogrun #<next> #<after> …`（指定 epic だけなら `backlogrun #<E> --only`）>
-
-**技術詳細**
-
-- 計測: <`pnpm josh cost` が出した値と閾値>
-- 引き継ぎ: <状態は GitHub にあり、会話には何も無いこと>
-```
-
-- One sentence per line, no internal identifiers, every child named by number. **Never omit
-  `Remaining`** — it is the one line that tells this report from a completion report
-- Telegram uses the same format and is **sent with `--task-type confirmation`** (`completion` would
-  announce an unfinished epic as done), `--recommended` naming the resume command
-- **Write it only when the run stops.** While a run carries on past the threshold it writes none; the
-  epic progress comment is the record
+- **Run it only when the run stops.** While a run carries on past the threshold there is no report;
+  the epic progress comment is the record

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

@@ -4,9 +4,8 @@ Point-of-use, read one section at a time from `backlogrun.md` → "The manifest
 
 ## Concurrency: as many children per repository as it has free lanes
 
-**One session per repository**, each running only its own repository's children. The lane ceiling is
-`.claude/skills/epic-commands/SKILL.md` → "An `in-progress` issue occupies a lane"; a dependency that
-crosses a repository is `.claude/skills/epic-commands/SKILL.md` → "Epics that span repositories".
+**One session per repository**, each running only its own repository's children. The lane ceiling and a
+dependency that crosses a repository are `docs/josh-commands-backlog.md` → "`josh epic:next`".
 
 ## A solo run
 
@@ -16,10 +15,15 @@ merged. **Decide it from three conditions that must all hold, never from how ser
 it a defect (not an improvement, refactor, removal or feature)? Is it in kit's own verification gate
 (lint / type check / spell check / unit tests), the code review, the pre-push hook, or the merge
 checks — not a consumer repository's CI or template? Does it, on `main` now, make unrelated PRs
-answer wrongly (a false green or a false red)? All three, and the issue carries `run:solo`; any one
-missing, and it carries `run:lane`. `backlog:next` and `epic:next --lanes` answer `triage` for an
-issue with neither, so a filed issue carries one of the two from its filing. **It stops the other
-lanes for one reason only: a batch run on broken verification leaves nobody's result trustworthy.**
+answer wrongly (a false green or a false red) **on every run**? All three, and the issue carries
+`run:solo`; any one missing, and it carries `run:lane`. `backlog:next` and `epic:next --lanes` answer
+`triage` for an issue with neither, so a filed issue carries one of the two from its filing. **It stops
+the other lanes for one reason only: a batch run on broken verification leaves nobody's result
+trustworthy.**
+
+**A wrong answer that only comes some of the time — a flaky test, a timeout under load — is not a solo
+run.** It carries `run:lane` and `priority:critical`, so it leads the next offer while the other lanes
+keep running: a flake costs another lane one rerun, less than every lane stopped until it merges.
 
 ## Lanes — running more than one child at a time
 
@@ -31,7 +35,7 @@ stay serial.**
 
 **A lane child may cut its own turn before the gate** — `pre-gate-cut.md`, the single source. The
 child is told apart from a person, and handed its resume stage, by `JOSH_LANE_CHILD`
-(`pre-gate-cut.md` → "The dispatch mark" and "The stage is passed to the resumed child").
+(`docs/josh-commands-run.md` → "`josh run:cut`"; `pre-gate-cut.md` → "The stage is passed to the resumed child").
 
 **A lane's review does not inherit the lane, and `pnpm josh review:brief` is what closes that**: it
 prints the lane's root, branch and HEAD, targets written `git -C <root> …`, and a nonce the review
@@ -47,14 +51,14 @@ are not predicted").
 
 ### Once per repository, before the first lane opens
 
-In the **primary checkout**, in order, never per lane: `pnpm josh ms`; `pnpm josh latest:scope` and the
-update on `required` (`backlogrun-child.md` → "`josh latest` runs once per session, not once per
+In the **primary checkout**, in order, never per lane: `pnpm josh ms`; `pnpm josh latest:if-required`
+(`backlogrun-child.md` → "`josh latest` runs once per session, not once per
 child"); `pnpm josh lane:prune`; `pnpm josh run:tidy`.
 
 **The rewritten lock file reaches a pull request through the first lane.** Only if the update rewrote
-anything: `git stash push -u -m "backlogrun: josh latest before lanes"` in the primary checkout, and
+anything: `pnpm josh stash:push "backlogrun: josh latest before lanes"` in the primary checkout, and
 record it on the first child's Issue. **The first lane's `pnpm josh lane:launch "$n" --stash
-"backlogrun: josh latest before lanes"` pops it by message** — never a positional `stash pop`. **Under
+"backlogrun: josh latest before lanes"` pops it by message.** **Under
 `backlog:drive` the driver passes `--stash`, never you**; the push stays the parent's.
 
 ### Opening one lane and dispatching its child
@@ -83,7 +87,7 @@ Everything else is unchanged; `pnpm josh followup` releases the lane's hold at t
 **The child is started as a process of its own, not as a subagent of this session** (`lane:dispatch`,
 `lane:launch`'s final step):
 
-- **It records where the child writes** — `<temp>/josh-lane-dispatch-<N>.log`.
+- **It records where the child writes** — `<common git dir>/josh/run-state/josh-lane-dispatch-<N>-<key>.log`, which survives a reboot.
 - **A refusal is an empty capture beside a non-zero exit**, with a `warning` Telegram. **Park that
   child and name the log the message carries**; never re-dispatch into the same lane without reading it.
 - **A child that started with nowhere to write exits zero and warns** — **wait on that lane with
@@ -113,7 +117,7 @@ read `backlogrun-recovery.md` → "Conflicts are not predicted" when `pnpm josh
 | The child was **parked before its commit** | **Left open**, its uncommitted work in place, its directory and held seat recorded on the Issue | The shared stash stack is unsafe; `lane:close` is a **forced** removal. `pnpm josh lane:launch <N>` re-dispatches into the kept lane (a failed-install lane is still refused) |
 | The child was **parked after its commit and push** | **Left open**, its directory and held seat recorded on the Issue | `lane:close` would take the **local branch**, the resume path |
 | The child hit a **merge conflict** | **Left open** — the resolution happens in it | `backlogrun-recovery.md` → "Conflicts are not predicted"; a park there takes the row above |
-| The child stopped on **`needs-human-review`** | **Left open and untouched** | The uncommitted work is what a person looks at. Name the lane directory in the stop report and Telegram |
+| The child stopped on **`needs-human-review`** | **Left open and untouched** | The uncommitted work is what a person looks at. `run:hold <N> --human-review-stop` names the lane directory in the Telegram; the stop report names it too |
 | The child **failed** | Whichever of the two parked rows applies, plus the consecutive-failure count | **A merge conflict is not this row**, and is not counted |
 | **`lane:open` failed on the install** | `pnpm josh lane:close <N>`, then park the child | Frees the seat; a person fixes the cause. Carry pnpm's reason into the park note |
 | The lane is **spent** — no child working in it, its Issue closed, not one this run launched and has not collected with `run:merge`, a clean tree, no commit that is on no remote | Nothing to do — `pnpm josh lane:prune` closes it | Any other lane is kept, with the reason on standard error |