@joshuafolkken/kit 1.2116.0 → 1.3000.0

package/.claude/agents/design-consultant.md

@@ -0,0 +1,19 @@
+---
+name: design-consultant
+description: Design consultation unit on Fable — weighs a design, architecture or trade-off question the consultation main line (Opus) brings, and returns a recommendation with its reasons and `file:line` citations. Dispatch it for a design, architecture or trade-off decision; operating, filing and plain questions stay in the main line.
+tools: Read, Grep, Glob, Bash
+model: fable
+---
+
+You are a design consultation unit dispatched by the consultation main line. Your job is to answer
+**one design question** — a module boundary, a data shape, an abstraction, a trade-off between
+approaches — and recommend what to do.
+
+- Start from the brief: the question, the options the main line already sees, and what it has ruled out.
+- Read the code the question touches; cite what you rely on as `file:line`. Never paste file text.
+- Search with read-only `Bash` where no `Grep` / `Glob` tool is given — `grep`, `rg`, `ls`, `find`
+  without `-exec` / `-delete`, `git log` / `git diff` / `git show`.
+- Never edit, stage or commit anything.
+- Return one recommendation, the reasons it wins over each alternative, and the risks it leaves. Where
+  the choice is a genuine toss-up, say so and name the fact that would decide it. Do not invent an
+  interface the code does not have; say it does not exist.

package/.claude/agents/investigator.md

@@ -11,8 +11,18 @@ to find out **how the subject currently works**, not what to change.
 
 - Start from what the brief says the main line already concluded; do not re-read what it lists as read.
 - Search and read freely — this context is yours, and keeping it out of the main line is why you exist.
-- Never edit, stage or commit anything. A throwaway probe script may be written to the session
-  scratchpad, run, and deleted; return its output alone.
+  Where the harness provides no `Grep` / `Glob` tool, search with read-only `Bash` — `grep`, `rg`
+  without a glob, `ls` with a glob, `find` without `-exec` / `-delete`, `git log` / `git diff` /
+  `git show`, `pnpm josh help` — which a consultation scope passes (`prompts/collaboration-workflow/principles.md`
+  → "consult-vs-execute").
+- Never edit, stage or commit anything. A throwaway probe script may be written to `.josh/tmp/`
+  (git-ignored), run, and deleted; return its output alone.
 - Return the conclusion plus the `file:line` citations that support each claim. Never paste file
   text beyond a short quoted line — the main line opens the cited lines to verify you.
+- Include the existing function signatures the planned change will call (parameters, return types
+  and overloads it needs), plus the existing test fixtures its tests will use (paths and setup or
+  helper usage), each with `file:line` citations. If either does not apply or was not found, say so;
+  do not invent an API or fixture, or paste whole implementations.
 - Report what the code does, never a root cause or a fix: deciding that stays in the main line.
+- Keep the reply within 60 lines and 3,000 characters: one bullet per claim with its citations,
+  grouped under the brief's questions, with no preamble, recap or list of the files you opened.

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

@@ -15,5 +15,16 @@ its `review:attest` step.
 - 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.
+- Write the review in the rubric's output format to a file outside the checkout (under `/tmp`), then
+  submit it with the findings in one call: `pnpm josh review:submit --review <absolute-path>` (round 2:
+  `--round 2`; a relative path is refused), the findings one per line
+  on stdin as `[fixed ]<category>:<severity>:<file>[:<line>] — <one sentence>` (`--interaction` for
+  the interaction brief, the one whose file name carries `interaction-`; `--none` and no stdin when
+  there is none). It lints the review and checks the lines together; fix everything it reports and
+  run it again. The dispatcher records that slot with `pnpm josh review:record --from-slot` and
+  never copies findings from your reply.
+- Keep the review to the rubric's items: a finding's problem and minimal fix in at most three lines
+  (its other sites one list of citations), a category with no finding in one proof line, and no
+  walkthrough of the diff.
+- Reply within 2,000 characters: the review file's path on the first line, then the finding lines
+  you submitted, one per line (`none` when there is none) — not the review again.

package/.claude/agents/reviewer.md

@@ -15,5 +15,16 @@ its `review:attest` step.
 - 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.
+- Write the review in the rubric's output format to a file outside the checkout (under `/tmp`), then
+  submit it with the findings in one call: `pnpm josh review:submit --review <absolute-path>` (round 2:
+  `--round 2`; a relative path is refused), the findings one per line
+  on stdin as `[fixed ]<category>:<severity>:<file>[:<line>] — <one sentence>` (`--interaction` for
+  the interaction brief, the one whose file name carries `interaction-`; `--none` and no stdin when
+  there is none). It lints the review and checks the lines together; fix everything it reports and
+  run it again. The dispatcher records that slot with `pnpm josh review:record --from-slot` and
+  never copies findings from your reply.
+- Keep the review to the rubric's items: a finding's problem and minimal fix in at most three lines
+  (its other sites one list of citations), a category with no finding in one proof line, and no
+  walkthrough of the diff.
+- Reply within 2,000 characters: the review file's path on the first line, then the finding lines
+  you submitted, one per line (`none` when there is none) — not the review again.

package/.claude/settings.json

@@ -13,6 +13,10 @@
 			"Read(!.env.example)",
 			"Read(!.env.test)",
 			"Read(./.dev.vars)",
+			"Read(~/.config/gh/**)",
+			"Read(~/.codex/auth.json)",
+			"Read(~/.netrc)",
+			"Read(~/.ssh/**)",
 			"Bash(git push --force*)",
 			"Bash(git push -f*)",
 			"Bash(git push *--force*)",
@@ -39,13 +43,22 @@
 			"Bash(gh pr merge*)",
 			"Bash(gh api *pulls/*/merge*)",
 			"Bash(gh api graphql*mergePullRequest*)",
-			"Bash(sudo *)"
+			"Bash(sudo *)",
+			"Bash(curl *)",
+			"Bash(wget *)",
+			"Bash(nc *)",
+			"Bash(gh auth token*)",
+			"Bash(printenv)"
 		]
 	},
 	"env": {
 		"BASH_MAX_OUTPUT_LENGTH": "8000"
 	},
 	"enableArtifact": false,
+	"statusLine": {
+		"type": "command",
+		"command": "pnpm josh usage:tee"
+	},
 	"hooks": {
 		"SessionStart": [
 			{
@@ -53,8 +66,18 @@
 				"hooks": [
 					{
 						"type": "command",
-						"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
+						"command": "sh \"$CLAUDE_PROJECT_DIR/scripts/hooks/run-hook.sh\" audit-provision --session-start",
+						"timeout": 90
+					}
+				]
+			},
+			{
+				"matcher": "clear",
+				"hooks": [
+					{
+						"type": "command",
+						"command": "sh \"$CLAUDE_PROJECT_DIR/scripts/hooks/run-hook.sh\" audit-provision --session-model",
+						"timeout": 10
 					}
 				]
 			}
@@ -65,7 +88,7 @@
 				"hooks": [
 					{
 						"type": "command",
-						"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",
+						"command": "sh \"$CLAUDE_PROJECT_DIR/scripts/hooks/run-hook.sh\" session-lang",
 						"timeout": 10
 					}
 				]
@@ -73,11 +96,11 @@
 		],
 		"PreToolUse": [
 			{
-				"matcher": "Bash|Edit|Read|Write|AskUserQuestion|Agent|Task",
+				"matcher": "Bash|Edit|Read|Write|AskUserQuestion|Agent|Task|Glob|Grep|WebFetch",
 				"hooks": [
 					{
 						"type": "command",
-						"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",
+						"command": "sh \"$CLAUDE_PROJECT_DIR/scripts/hooks/run-hook.sh\" pretool-guard",
 						"timeout": 20
 					}
 				]
@@ -85,11 +108,11 @@
 		],
 		"PostToolUse": [
 			{
-				"matcher": "Edit|Write",
+				"matcher": "Edit|Write|Bash",
 				"hooks": [
 					{
 						"type": "command",
-						"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",
+						"command": "sh \"$CLAUDE_PROJECT_DIR/scripts/hooks/run-hook.sh\" format-edited",
 						"timeout": 90
 					}
 				]
@@ -101,7 +124,7 @@
 				"hooks": [
 					{
 						"type": "command",
-						"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",
+						"command": "sh \"$CLAUDE_PROJECT_DIR/scripts/hooks/run-hook.sh\" stop-guard",
 						"timeout": 20
 					}
 				]

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

@@ -1,6 +1,6 @@
 ---
 name: dependency-update
-description: Checks after `pnpm update`, `josh latest`, `josh adopt`, `pnpm josh overrides` or any dependency update — the `overrides` survived, the one expected `devEngines` change. Read it before reporting the pins intact or pinning a bump back.
+description: Checks after `pnpm update`, `josh latest`, `josh adopt`, `pnpm josh overrides` or any dependency update — `overrides` kept, one expected `devEngines` change. Read it before reporting the pins or pinning a bump back.
 ---
 
 # After a dependency-update command
@@ -17,25 +17,22 @@ versions. Overrides exist on purpose (e.g. `"esbuild@<=0.24.2": ">=0.25.0"` for
 **`package.json` is ignored** (verified with pnpm 12.6.0). Inspect both to preserve existing
 declarations, but an absent package field says nothing about workspace overrides.
 
-## 2. The check is a command you run, not a conclusion you reach
+## 2. Quote the printed overrides verdict
 
-```bash
-git diff -- pnpm-workspace.yaml package.json
-```
+`josh latest`, `josh adopt` and `josh latest:if-required` print it after §3's line and a
+`✖ <file> overrides changed` heading per moved block. `overrides: keep` — keep. `overrides: restore (…)`
+(non-zero exit) — restore the moved entries, investigate, report. `overrides: not judged (…)` — run
+the check below.
 
-(after `josh adopt`, which has already committed and returned to the default branch:
-`git diff <default>...<branch> -- pnpm-workspace.yaml package.json`). Confirm both overrides blocks
-are untouched **and** `devDependencies` still respect the effective overrides. A removed, modified or
-over-bumped entry: restore it immediately, investigate, and report — never keep it without approval.
+**No verdict printed** (`pnpm update`, a Dependabot merge) — run `pnpm josh overrides --diff HEAD`
+(`<default>...<branch>` once committed) and quote its `✔` / `✖` lines the same way.
 
-`josh latest` prints its verdict as its last overrides line (`✔ overrides unchanged (<n> from
-<file>)` or `⚠ overrides changed`); `pnpm josh overrides` compares against a saved snapshot —
-**quote what one printed.**
+It covers the overrides blocks only: confirm overridden packages' `devDependencies` still respect them.
 
 ## 3. `devEngines` — the one expected change
 
-**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
+**Read the verdict line, never compare by eye.** `pnpm josh overrides` prints it first — against
+`HEAD`, or the `--diff` range's base — and `josh latest` prints it after its pnpm bump
 (`scripts/version/development-engines-verdict.ts`). Quote it:
 
 - `devEngines: unchanged` / `devEngines: kept` — keep. `kept` is the lockstep pnpm bump (the version

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

@@ -1,6 +1,6 @@
 ---
 name: epic-commands
-description: Procedures for `josh epic:audit`, `epic:next` and `epic:bundle`. Read it before running one, before an epic tracks a child in another repository, when `epic:bundle` places a filed issue, and when recording a decision on a `needs-decision` child.
+description: Procedures for `josh epic:audit`, `epic:next`, `epic:bundle`, an epic child in another repository and a `needs-decision` decision. Read it before any of them and when `epic:bundle` places a filed issue.
 ---
 
 # The `josh epic:*` commands
@@ -15,8 +15,8 @@ epic:audit → find contradictions across the children, and fix what it finds (T
 backlogrun → which calls epic:next each round
 ```
 
-Front-loading every `needs-decision` is `backlogrun`'s job: `backlogrun-steps.md` → "Resolve what
-the plan can resolve, before starting". A `backlogrun #E --only`'s pre-check is `epic:audit`.
+Settling every `needs-decision` is `backlogrun`'s job: `backlogrun-steps.md` → "Resolve what
+the plan can resolve"; a `推奨なし` park → `backlogrun-park.md` → "A park the driver decides". A `pnpm josh backlogrun <E> --only`'s pre-check is `epic:audit`.
 
 Read `execution-waves.md` only when children need an order between groups (a wave boundary, or a child
 that must run alone), and `epic-bundle.md` only when a filing's `epic:bundle` answer places the issue.
@@ -31,6 +31,8 @@ Recording a decision removes that child's `needs-decision` label (Tier A; `backl
   (`epic-bundle.md`).
 - **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.
+- A decision that changes one child's scope → state the new `- 規模見積もり:` line in a record naming
+  that child alone; `scripts/epic/epic-decide.ts`.
 
 ```md
 ## Decisions
@@ -120,15 +122,15 @@ learn their state** — only to implement.
 ## `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 and writes nothing; `--apply` writes an `add_to_epic` /
-`create_epic` answer.**
+when that step printed `⚠`. **It recommends and writes nothing; `--apply` writes every placing answer
+— `ask` into its `Recommended:` epic, with the decision recorded.**
 
 | 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** (`epic-bundle.md`) | **A** |
+| Spread across **different** epics | **The `Recommended:` epic** — most related issues, older on a tie; none on a cycle (`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,17 +39,16 @@ 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.**
+**`pnpm josh epic:bundle <N> --apply` writes `add_to_epic` / `create_epic`, and `ask` into its
+`Recommended:` epic** (most related issues, older on a tie), recording the decision on **both** the
+issue and the epic's `## Decisions`. **Placing is Tier A; merging epics is not proposed here.**
 
 **An epic and its own parent do not produce the spread verdict** — the issue goes to the inner epic.
 **The narrowing drops parents, never peers**: an unrelated epic beside a nested chain, or a cyclic
-declaration, still asks. Stop (Tier B) only where the epics left are genuinely too close to separate.
+declaration (no `Recommended:`, so `--apply` writes nothing), still asks. Stop (Tier B) only where
+the epics left are genuinely too close to separate.
 
-**Write both halves in the one call that places the issue: `pnpm josh epic --add <E> <N...>
+**By hand, write both halves in one call: `pnpm josh epic --add <E> <N...>
 --decision-file <path|->`.** It appends to the epic's `## Decisions` and comments the same text on
 each child added. **Never hand-edit the epic body to add the entry.** Refused before anything is
 written:

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

@@ -1,6 +1,6 @@
 ---
 name: verify-ui
-description: Screenshot the affected route with the project's own command and check it matches the intent. Use it before reporting any UI, layout, styling, copy or interaction change as done.
+description: Screenshot the changed route with the project's own command. Use it before reporting a UI, layout, styling, copy or interaction change done.
 argument-hint: '[route] [route...]'
 ---
 
@@ -18,23 +18,17 @@ passing tests are not that look.
 
 State the list before capturing.
 
-## 2. Find this project's screenshot command
+## 2. Capture
 
-Stop at the first hit:
-
-1. `pnpm josh-app shot` — the SvelteKit application toolkit (`@joshuafolkken/app-kit`).
-2. `pnpm josh-game shot` — the game toolkit (`@joshuafolkken/game-kit`).
-3. A project-local script named `shot`, `screenshot` or `verify:ui` in `package.json`.
-
-Option 1 exists since app-kit 0.86.0; game-kit carries no `shot` yet —
-the version a project has installed is the only thing that decides.
-
-**Decide by the printed command list, not by whether the toolkit is installed.** Run the toolkit with
-no subcommand (`pnpm josh-app`) and read its usage line; an absent toolkit and one without `shot` both
-exit non-zero.
+Run `pnpm josh ui:shot <route>...` once, with every route (`pnpm josh ui:shot / /blog`). It finds this
+project's screenshot command and runs it; do not probe the candidates by hand. The command prints the
+image paths, and its exit status is the result. A failed capture is not a passed gate.
 
 ### When there is no screenshot command
 
+`ui:shot` says so — `no screenshot command in this project — tried:` and the candidates — and exits
+non-zero. Only then:
+
 **Capture through the project's own E2E suite**: add `await page.screenshot({ path: … })` to the
 Playwright spec covering the screen (or a new spec) and run it.
 
@@ -45,19 +39,15 @@ Never report the gate as satisfied on tests alone. Never stand up a preview serv
 it from a throwaway script. A project that should have the command and does not is an issue against
 the application toolkit.
 
-## 3. Capture
-
-Run the command once for every route (`pnpm josh-app shot / /blog`) and note the output directory (on
-the E2E fallback, the `path` option). A non-zero exit is the result. A failed capture is not a passed gate.
-
-## 4. Look at the images
+## 3. Look at the images
 
 Read every produced image with the Read tool — capturing without opening does not close the gate.
 Check the change's intent: element present, placed, sized, spaced, colored and worded as intended;
 nothing else disappeared or moved; the layout holds at the captured viewport.
 
-## 5. Report
+## 4. Report
 
-- **Matches the intent**: route by route, what you checked, with the image paths.
+- **Matches the intent**: route by route, what you checked, with the image paths (on the E2E
+  fallback, the `path` option).
 - **Does not match**: route, intended result, what the image shows, image path. Fix and capture again.
-- **Could not capture**: the report from step 2 or step 3, unchanged. This is not a pass.
+- **Could not capture**: the report from step 2, unchanged. This is not a pass.

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

@@ -1,6 +1,6 @@
 ---
 name: workflow-commands
-description: Procedures for `kickoff`, `fullrun`, `halfrun`, `prrun` and `backlogrun`. Read it the moment one is typed (with or without `#N` / `new`), before any command, and when asked what one does or a run must be resumed or repaired.
+description: Procedures for `kickoff`, `fullrun`, `halfrun`, `prrun`, `backlogrun` (with or without `#N` / `new`). Read it before running, explaining, resuming or repairing one.
 ---
 
 # Issue-driven workflow commands
@@ -13,12 +13,15 @@ Its single source is `CLAUDE.md` → "Explicit invocation required (MANDATORY)",
 holds when this skill is not loaded. **A session cut inside a declared budget is not a new invocation — for `backlogrun`
 alone**: `backlogrun-steps.md` → "The session cut is inside the invocation".
 
+**Consultation main-session scope and implementation handoff follow
+`prompts/collaboration-workflow/principles.md` → "consult-vs-execute".** A keyword selects the
+existing procedure below; it does not turn the consultation main session into an implementation lane.
+
 ## 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 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.
+section that governs it; a section it prints is not fetched again.
 
 | Typed keyword                            | Read                                        |
 | ---------------------------------------- | ------------------------------------------- |
@@ -34,8 +37,7 @@ each manifest carries only its difference. `split-assessment.md` → "The questi
 
 ### The fetch is one `Read` call per file
 
-**Fetch each file above with one `Read` call of its own — never `cat`, never two in one command.** A
-Bash result is capped at `BASH_MAX_OUTPUT_LENGTH` characters and truncates a longer document;
+**Fetch each file above with one `Read` call of its own — never `cat`, never two in one command.**
 `pnpm josh doc:read <file>` is the cap-safe whole-file read.
 
 ### Four documents are read at the point of use, not at the entry
@@ -46,14 +48,14 @@ Each is fetched at its named scope, in the same turn, by the named command that
 | Document                | Read it when                                                                   |
 | ----------------------- | ------------------------------------------------------------------------------ |
 | `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`; a lane child reads "A lane child" alone) — the gate overlaps the review |
+| `followup.md` → "Run `pnpm josh followup`" | Never fetched: `pnpm josh followup` prints it as it starts, once per session — none in a followup any `josh ship` runs, a repeat names the section in one line |
+| `chain-rule.md` → "Run the review-to-merge chain" | Before the first `pnpm josh gate` launch (`fullrun` / `prrun` / `backlogrun`), never fetched: `run:step` prints it at `implement`, `run:review` (which launches the gate) and `ship` once per session — a lane child gets "A lane child" alone, a repeat names the section in one line |
 | `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 `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.
+`backlogrun-park.md` → "park and continue" at that point of use**, and **every implementing run starts
+`pnpm josh run:progress --wait` once its hold is claimed** — `progress-watcher.md` → "Progress while
+the run is quiet" is never fetched: `run:entry` prints it.
 
 ### A section reference is read as a section
 
@@ -64,29 +66,28 @@ pnpm josh doc:section <file.md> "<heading>"   # the section, verbatim
 pnpm josh read:set [<keyword>]                # what an entry reads, and what it costs
 ```
 
-A heading that does not resolve is refused, with the file's own headings listed.
-
 ## 2. What every one of them shares
 
-Each shared rule is a **trigger, a one-line action, and the single source** the procedure is read
-from — read at that trigger, never restated here.
+Each shared rule is a **trigger, a one-line action, and the single source** read at that trigger.
 
 | Trigger | Action | Single source |
 | --- | --- | --- |
+| Consultation main (Fable / Astra), excluding lane and `run:handoff` children | `pnpm josh run:handoff <keyword> … --brief-file .josh/tmp/brief.md` | `docs/josh-commands-board.md` → "josh run:handoff" |
+| A file passed as a `*-file` argument (body, plan, brief, rationale, human-steps, review note) | Write it under `.josh/tmp/` | `prompts/collaboration-workflow/shell-body.md` → "安全な書き方" |
 | 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" (model-priced 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` (`new`: `--adopt`) | `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 any work starts (every entry) | The split assessment; the default is not to split — separability **and** a scope over the size guide must hold together; a `fullrun` / `halfrun` that finds a split files the epic and **stops** | `split-assessment.md` → "The question" |
 | 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`) |
+| `run:prep` answers `latest: required` | `pnpm josh latest:if-required` — it prints the `dependency-update` check | `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 --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" |
+| Implementation is done | Refactor → `main:merge` (no lane child) → `pnpm josh gate`, then (green) a subagent `/code-review` → 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" |

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

@@ -5,8 +5,9 @@
 - **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. Also `lint:related` /
-  `test:related` / `check:related` / `metrics` with work to overlap: a wait past the 5-min cache TTL
+  `test:related` / `check:related` / read-only `metrics` with work to overlap: a wait past the 5-min cache TTL
   rewrites the context.
+- `metrics --accept` writes must finish before verification starts; use the existing `josh ship` pre-detach sequence (`run-ship-pre-detach.ts`) for approval re-recording before checks.
 - Issue `pnpm josh git -y` in the background; its completion resumes the run, so the turn never ends
   at the push.
 - `pnpm josh followup` stays in the foreground (`followup.md`).
@@ -47,8 +48,10 @@ merge result?**
   `pnpm josh epic:next`, `pnpm josh backlog:next --exclude <N>`, `pnpm josh lane:close` /
   `pnpm josh lane:list`. **De-duplicating a step is not removing it** — none is dropped or answered
   from memory.
-- **It does not — it is composed in the turn that issues `followup`**: the epic progress counter
-  *values* and the completion report body. **Only the write follows the merge.**
+- **Epic progress counters → `pnpm josh run:merge <N> --epic <E> --repo <owner/repo>` posts them**
+  after the merge (`docs/josh-commands-run.md` → "josh run:merge").
+- **It does not — it is composed in the turn that issues `followup`**: the completion report body.
+  **Only the write follows the merge.**
 - **`pnpm josh cost --cut` stays after the merge**, though it reads nothing from it (`backlogrun-progress.md`
   → "The check is asked at every merge").
 
@@ -59,7 +62,7 @@ merge result?**
 | `pnpm josh gate` | a subagent running `/code-review` with the brief `pnpm josh review:brief` prints |
 | `pnpm josh git -y` | Write the completion notification body to a file for `--notify-message-file`, and settle the three-way disposition of any remaining non-High finding |
 | CI, after the push | The second review round where one is due, the branch-2 filing through `pnpm josh issue:file`, which runs `epic:bundle` itself (`prompts/review.md` → "Review round cap") |
-| `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` |
+| `pnpm josh followup` | Nothing — it is foreground. **The post-merge tail is taken before the call**: 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`. the