@joshuafolkken/kit 1.1471.0 → 1.1784.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/settings.json

@@ -54,7 +54,7 @@
 				"hooks": [
 					{
 						"type": "command",
-						"command": "project_root=\"$(env -u GIT_ALTERNATE_OBJECT_DIRECTORIES -u GIT_COMMON_DIR -u GIT_DIR -u GIT_INDEX_FILE -u GIT_NAMESPACE -u GIT_OBJECT_DIRECTORY -u 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",
+						"command": "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",
 						"timeout": 180
 					}
 				]
@@ -66,7 +66,7 @@
 				"hooks": [
 					{
 						"type": "command",
-						"command": "project_root=\"$(env -u GIT_ALTERNATE_OBJECT_DIRECTORIES -u GIT_COMMON_DIR -u GIT_DIR -u GIT_INDEX_FILE -u GIT_NAMESPACE -u GIT_OBJECT_DIRECTORY -u 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",
+						"command": "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
 					}
 				]
@@ -74,11 +74,11 @@
 		],
 		"PreToolUse": [
 			{
-				"matcher": "Bash|Edit|Read|Write|AskUserQuestion",
+				"matcher": "Bash|Edit|Read|Write|AskUserQuestion|Agent|Task",
 				"hooks": [
 					{
 						"type": "command",
-						"command": "project_root=\"$(env -u GIT_ALTERNATE_OBJECT_DIRECTORIES -u GIT_COMMON_DIR -u GIT_DIR -u GIT_INDEX_FILE -u GIT_NAMESPACE -u GIT_OBJECT_DIRECTORY -u 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",
+						"command": "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 +90,7 @@
 				"hooks": [
 					{
 						"type": "command",
-						"command": "project_root=\"$(env -u GIT_ALTERNATE_OBJECT_DIRECTORIES -u GIT_COMMON_DIR -u GIT_DIR -u GIT_INDEX_FILE -u GIT_NAMESPACE -u GIT_OBJECT_DIRECTORY -u 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",
+						"command": "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 +102,7 @@
 				"hooks": [
 					{
 						"type": "command",
-						"command": "project_root=\"$(env -u GIT_ALTERNATE_OBJECT_DIRECTORIES -u GIT_COMMON_DIR -u GIT_DIR -u GIT_INDEX_FILE -u GIT_NAMESPACE -u GIT_OBJECT_DIRECTORY -u 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",
+						"command": "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/epic-commands/SKILL.md

@@ -5,9 +5,6 @@ description: Procedures for `josh epic:audit`, `epic:next` and `epic:bundle`. Re
 
 # The `josh epic:*` commands
 
-This skill is the single source for the three commands. Reasons: `docs/maintainers/epic-commands-rationale.md`
-→ "Where each rule came from".
-
 The workflow keywords themselves — `kickoff`, `fullrun`, `halfrun`, `prrun`, `backlogrun` — live in the
 `workflow-commands` skill.
 
@@ -32,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
@@ -60,29 +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 format's history:
-`docs/maintainers/epic-commands-rationale.md` → "Creating an epic by hand".
+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.
@@ -91,39 +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`.
-
-History: `docs/maintainers/epic-commands-rationale.md` → "`epic:audit` — why the children are read across".
+**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:
 
@@ -133,55 +102,35 @@ 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.
 
-Why: `docs/maintainers/epic-commands-rationale.md` → "`epic:next` — why it answers as it does".
-
 ## 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. History: `docs/maintainers/epic-commands-rationale.md` → "Cross-repository epics".
+- **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 | — |
 
 **A placing answer is acted on with `epic-bundle.md`**. `Nothing to bundle.` needs no further read.
-
-History: `docs/maintainers/epic-commands-rationale.md` → "`epic:bundle` — why issues filed apart are bundled afterwards";
-the reasons behind `epic-bundle.md`: `docs/maintainers/epic-commands-rationale.md` → "`epic:bundle` — why each answer reads as it does";
-behind `execution-waves.md`: `docs/maintainers/epic-commands-rationale.md` → "Execution waves — why a wave is not a mechanism".

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

@@ -2,14 +2,18 @@
 
 Read this when a filing's `epic:bundle` answer places the issue (`add_to_epic`, `create_epic`, or a
 choice between epics), or when `SKILL.md` → "`josh epic:bundle <N>` — does this new issue belong with
-one already filed?" does not settle it. `Nothing to bundle.` needs neither. Reasons:
-`docs/maintainers/epic-commands-rationale.md` → "`epic:bundle` — why each answer reads as it does".
+one already filed?" does not settle it. `Nothing to bundle.` needs neither.
 
-**Only two things count as a signal**: the issues referring to each other in prose, or a `blocked-by`
-already recorded between them. **A similar title never counts on its own.**
+**Only two things count as a signal**: one issue naming the other in its acceptance criteria
+(`## 受け入れ条件` / `## Acceptance criteria`) or its `parent: #N` / `親: #N` line, or a `blocked-by`
+recorded between them. A reference elsewhere, or a similar title, never counts; the evidence line
+names the section.
+
+**A placing answer you do not follow** — check it against both issues first; record the reason as an
+`Auto-decided:` line on the issue.
 
 **The release issue is neither a candidate nor a subject**, like an epic — its `blocked-by` relations
-are mechanical. Any other `blocked-by` or prose reference still counts.
+are mechanical. Any other `blocked-by` or counted reference still counts.
 
 **The search is not limited to the open backlog.** Every number the subject's own body names is read
 (capped at twenty), whatever its state:
@@ -35,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.**
@@ -52,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/epic-commands/execution-waves.md

@@ -1,8 +1,7 @@
 # Execution waves — parallel, then one alone, then the rest
 
 Read this when an epic's children need an order between groups — a wave boundary, or one child that
-must run alone. It builds on `SKILL.md` → "`josh epic:next <E…>` — what is runnable". Reasons:
-`docs/maintainers/epic-commands-rationale.md` → "Execution waves — why a wave is not a mechanism".
+must run alone. It builds on `SKILL.md` → "`josh epic:next <E…>` — what is runnable".
 
 **A wave is not a mechanism, and there is nothing to add for one** — the dependency declaration
 already expresses it.

package/.claude/skills/verify-ui/SKILL.md

@@ -7,8 +7,7 @@ argument-hint: '[route] [route...]'
 # Verify the rendered screen
 
 A rendered-UI change is not done until someone has looked at it (`CLAUDE.md` → completion gate);
-passing tests are not that look. Rationale: `docs/maintainers/verify-ui-rationale.md` → "Why the skill
-reads as it does".
+passing tests are not that look.
 
 ## 1. Decide which routes to capture
 

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

@@ -5,10 +5,7 @@ description: Procedures for `kickoff`, `fullrun`, `halfrun`, `prrun` and `backlo
 
 # Issue-driven workflow commands
 
-`kickoff`, `fullrun`, `halfrun`, `prrun` and `backlogrun` are the shorthand commands this
-package's collaboration workflow is built on. **This file is their manifest — triggers and pointers,
-never a procedure**: each rule is stated once, in the file its row names. History:
-`docs/maintainers/workflow-commands-rationale.md` → "Where each rule came from".
+Each rule is stated once, in the file its row names.
 
 ## 0. The rule that fires before any of them — explicit invocation
 
@@ -19,8 +16,9 @@ alone**: `backlogrun-steps.md` → "The session cut is inside the invocation".
 ## 1. Which file to read
 
 Read this file, then the files the typed command's row names. A command file is a **manifest** of
-terse triggers and pointers; `pnpm josh run:step <N>` prints the run's next single action, computed
-from the event stream, the carry record and the issue state, never the conversation.
+terse triggers and pointers; `pnpm josh run:step <N>` prints the run's next single action and the
+section that governs it, computed from the event stream, the carry record and the issue state, never
+the conversation; a section it prints is not fetched again.
 
 | Typed keyword                            | Read                                        |
 | ---------------------------------------- | ------------------------------------------- |
@@ -31,8 +29,8 @@ from the event stream, the carry record and the issue state, never the conversat
 | `backlogrun` / `backlogrun #N…` / `backlogrun #E…` | `backlogrun.md` — its dispatched child reads `fullrun.md` + `split-assessment.md` in its own unit, not the parent at entry |
 
 `entry-sequence.md` holds the entry sequence and stop branches `fullrun`, `halfrun` and `prrun` share;
-each manifest carries only its difference. `split-assessment.md` → "The question" is read at the
-entry as a section, its split-handling detail only when a split is found.
+each manifest carries only its difference. `split-assessment.md` → "The question" is printed by
+`pnpm josh run:entry` at the entry, its split-handling detail read only when a split is found.
 
 ### The fetch is one `Read` call per file
 
@@ -47,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 |
 | `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.
@@ -81,9 +79,9 @@ from — read at that trigger, never restated here.
 | 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` |
@@ -100,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 | Send a `confirmation` Telegram first, so the user is alerted off-screen | `CLAUDE.md` → "Mid-workflow stop notification" |
+| Any mid-workflow stop | `stop:guard` sends the `confirmation` Telegram; on its refusal, send it | `CLAUDE.md` → "Mid-workflow stop notification" |
 
 ## 3. What stays resident, and what is read from here
 

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

@@ -7,7 +7,7 @@
 - Background `pnpm josh gate` beside the review; join it before commit.
 - 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.
@@ -17,7 +17,6 @@
 - 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.
-Where each rule came from: `docs/maintainers/background-commands-rationale.md` → "Where each rule came from".
 
 ## How the wait ends — the task's exit, never a regex over its output
 
@@ -26,9 +25,8 @@ when it *exits* — that completion notification is what ends the wait, not a re
 limit.
 
 **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
-(`prompts/collaboration-workflow/rule-delivery.md`; `docs/maintainers/background-commands-rationale.md`
-→ "Why a poll loop is refused").
+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`).
 
 **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
@@ -37,8 +35,7 @@ hand-armed timer).
 ## The tail and what overlaps each wait
 
 **Never give a foreground call a timeout above the harness cap** — a larger number detaches it without
-the completion notification (`docs/maintainers/background-commands-rationale.md` → "Why the tail
-collects idle time").
+the completion notification.
 
 **The tail is emptied before `followup` is issued.** Each step is asked one question: **does it read the
 merge result?**
@@ -62,17 +59,16 @@ 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
-push reissued detached is not refused again (`docs/maintainers/background-commands-rationale.md` → "Why
-the push is guarded").
+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` →
 "Taking the cut".
 
 **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

@@ -1,14 +1,6 @@
 # `backlogrun` — running a child (shared mechanics, delegation, liveness, session setup)
 
-Point-of-use, read one section at a time from `backlogrun.md` → "The route table". Reasons:
-
-- `docs/maintainers/backlogrun-child-rationale.md` → "Why the file is read by section"
-- `docs/maintainers/backlogrun-child-rationale.md` → "Why a bare Issue promotes itself under `backlogrun` but not under `fullrun`"
-- `docs/maintainers/backlogrun-child-rationale.md` → "Why each child runs in a delegated unit"
-- `docs/maintainers/backlogrun-child-rationale.md` → "Why the summary is bounded the way it is"
-- `docs/maintainers/backlogrun-child-rationale.md` → "Why the audit runs before the first child"
-- `docs/maintainers/backlogrun-child-rationale.md` → "Why `josh latest` is hoisted to the session"
-- `docs/maintainers/backlogrun-child-rationale.md` → "Why the preflight is part of the claim"
+Point-of-use, read one section at a time from `backlogrun.md` → "The manifest — the ordered flow".
 
 ## Running a child — the shared mechanics
 
@@ -23,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.**
 
@@ -52,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;
@@ -73,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 once a place is free: `scripts/backlog/backlog-occupied.ts`.
 
 ### What the summary carries, and how long it may be
 
@@ -89,7 +84,8 @@ is unchanged.
 
 ## A delegated unit that stopped without reporting
 
-**Hand the child off without blocking, and poll** — a stopped unit leaves no notification. Once its
+**Hand the child off without blocking, and wait on `pnpm josh lane:await <N>`** — a stopped unit
+leaves no notification, so the await's exit is the wake. Once its
 output is unchanged for the silent-unit window, read `backlogrun-recovery.md` → "A delegated unit that
 stopped without reporting" and ask `pnpm josh run:liveness`.
 
@@ -100,14 +96,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