@joshuafolkken/kit 1.872.0

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

@@ -0,0 +1,93 @@
+# `fullrun` — the step lists and the branches
+
+**This is the detailed procedure behind `fullrun.md`'s manifest, relocated here so the entry read
+carries the manifest, not the prose** (joshuafolkken/kit#2189). `fullrun.md` is the resident manifest;
+it routes here for the fine print of a step, read on demand — `pnpm josh run:next <N>` names which step
+the run is at, and the sections below carry that step in full.
+
+## The `fullrun #N` step list
+
+**Add `in-progress` the moment `run:hold` answered `hold`** (create if missing:
+`gh api repos/{owner}/{repo}/labels -f name=in-progress -f color=0075ca -f description="Work is
+actively in progress" --silent 2>/dev/null || true`, then `gh api
+repos/{owner}/{repo}/issues/<N>/labels -f 'labels[]=in-progress'`) → Read Issue #N and its comments
+(`issue-comments.md`) → **normalize the title** (if not in English or can be phrased more clearly,
+derive a better English title and `gh api -X PATCH repos/{owner}/{repo}/issues/<N> -f title="<title>"`)
+→ post the agreed plan only if the Issue body is blank (`gh api -X PATCH
+repos/{owner}/{repo}/issues/<N> -f body="<plan>"`); if the body already has content, skip the
+plan-posting step → **emit the plan event**: `pnpm josh run:event --append plan "planned #<N>"` (a no-op
+outside a run; no cut follows it — a lane child's context is bounded by the threshold-gated
+implementation cut alone, joshuafolkken/kit#2489)
+→ implement → run the **verification gate** (the full procedure is `chain-rule.md`;
+in outline: refactor → `pnpm josh main:merge` → **a dispatched lane child hands the rest to
+`pnpm josh ship --detach --review "<title> #<N>"` and ends its turn** (`chain-rule.md` step 0,
+joshuafolkken/kit#2428) → otherwise `pnpm josh run:cut <N>` (the pre-gate cut, before the gate; a no-op
+outside a lane) → start `pnpm josh gate` and a subagent `/code-review`
+with the brief `pnpm josh review:brief` prints on `git diff main`, join the gate before the commit,
+iterate to no high/medium findings, at most two reviews → **the clean path folds the ship region into
+one call**, `pnpm josh ship "<title> #<N>"` (gate → commit/push/PR → the CI-wait `followup` → the
+`run:tail` report bookkeeping, stopping at the first failed step; joshuafolkken/kit#2398), with any
+branch-2 filing and `pnpm josh epic:bundle` run before it → **when a second round is due `ship` does not
+fit**: open the PR between the rounds with `pnpm josh git -y "<title> #<N>"`, run round 2 beside CI, then
+`pnpm josh followup` and `pnpm josh run:tail <N>`). Issue plan comments are written in the session language (`JOSH_SESSION_LANG`,
+default `ja`). Before implementing, run `git switch main && git pull`, then `pnpm josh latest:scope`
+and update dependencies only on `required` — `latest-gate.md` is its single source, and on `required`
+load the `dependency-update` skill afterwards. **A dispatched lane child skips the `git switch main &&
+git pull`**: `git switch main` is refused in a lane (the primary checkout holds the default branch, so
+the switch fails with `already used by worktree`), the lane was branched from a fresh default before it
+opened, and the latest default is brought in during the gate by `pnpm josh main:merge`. The parent runs
+`git switch main && git pull` in the primary checkout, never the child — `backlogrun-lanes.md` and
+`backlogrun-child.md` are the single sources. When running `pnpm josh followup`, pass an
+implementation summary via `--notify-message` in the session language, leading with the three
+plain-language lines: `"Implemented <title>\nCause: ...\nFix: ...\nResult: ...\n\nDetails:\n-
+<change1>\n- <change2>"`. **`pnpm josh followup` waits for CI, verifies AI review findings, sends the
+completion notification, then merges; if blockers are found it exits non-zero — fix and re-run.**
+**マージ後に `pnpm josh ms` を実行する。** Codex レーンでは省略し、親の `run:merge` が主チェックアウトで同期する。Claude は従来どおり。
+
+## The `fullrun new` step list
+
+`kickoff new` + `fullrun #N` in one run. Steps: (1) Derive an English title, or use the provided one.
+**(1a) Run `pnpm josh issue:scout "<title>" [--body "<summary>"]` before creating the Issue** — a
+candidate that covers the same work stops the run rather than filing a second Issue (`SKILL.md` → §2e).
+(2) Create Issue: `gh api repos/{owner}/{repo}/issues -f title="<title>" -f 'labels[]=depth:<n>' -f
+body="<body>"` (body per `prompts/collaboration-workflow/issue-template.md`). Capture `<N>`. (3) Add
+`in-progress` (as above). (4) Post the agreed plan in the session language: fill the body if blank,
+otherwise add a comment. (5) If the working tree already has staged or modified files,
+`git stash push -m "fullrun new: pre-existing changes"` first. (6) `git switch main && git pull`. (7)
+`pnpm josh latest:scope`; on `required` run `josh latest` and load the `dependency-update` skill; on
+`skip` neither runs (`latest-gate.md` is the single source). If you stashed in (5),
+`pnpm josh stash:pop "fullrun new: pre-existing changes"` — by message, never a positional `git stash
+pop`. (8) Implement. (9) Run the verification gate (as in `chain-rule.md`; only the first review round
+runs here). (9a) **Ask `pnpm josh review:round2 --round-1-closed` whether a second round is due**, once
+round 1's fixes are in and before the commit. (10) Where the tree was edited after the first gate
+started, re-run `pnpm josh gate` and join it. (11) `pnpm josh git -y "<title> #<N>"` — the pull request
+opens here, between the two rounds. (11a) Run the **second round** now beside the CI, where (9a)
+answered `required` (brief `pnpm josh review:brief --round 2`); a finding it fixes in place is pushed
+before its gate. (12) File whatever the review round cap routed to branch 2, run `pnpm josh epic:bundle
+<new>` on each, and where (9a) answered `skip` record the skip on the Issue. (13) **Where no second
+round was due** (9a `skip`), fold steps (10)–(13) and the release bookkeeping into one call — `pnpm josh
+ship "<title> #<N>" --notify-message "..."` (gate → commit/push/PR → the CI-wait `followup` → `run:tail`,
+stopping at the first failed step; joshuafolkken/kit#2398); **where a second round ran**, the PR opened
+at (11) and the region stays separate — `pnpm josh followup "<title> #<N>" --notify-message "..."` then
+`pnpm josh run:tail <N>`. (14) **After the merge, run `pnpm josh ms`.** (15) **Ask `pnpm josh
+release:scope` and close the completion summary with what it answered** (`followup-reference.md` →
+"When `pnpm josh release` runs").
+
+## The release ask — the last step of either form
+
+**One call folds the post-merge bookkeeping** (joshuafolkken/kit#2372): after the merge, `pnpm josh
+run:tail <N>` commits the observation ledger (`observations:flush` — skipped by a dispatched lane child,
+whose `backlogrun` flushes once at `run:carry --end`; joshuafolkken/kit#2492), reads the completion citations
+(`issue:cite`, given the closed issue and any follow-ups filed this run) and decides the release scope
+(`release:scope`) in one round trip, joining each under its own header. **On the clean path `run:tail`
+runs inside `pnpm josh ship`** as its report step (joshuafolkken/kit#2398), so it is a standalone call
+only where a second round kept the ship region separate. It folds only bookkeeping — the
+release ask below stays the single source of what `required` means and the Tier-C publish boundary; a
+`backlogrun` child still leaves `observations:flush`, `issue:cite` and the release ask to the batch's
+own end.
+
+Once the merge is done, `pnpm josh release:scope` says whether a release is owed — `required`, `skip`
+or `unknown`, and `unknown` is never read as `skip`. On `required` the completion summary closes with
+the request and the exact command; the run never types `pnpm josh release` itself, because publishing
+is Tier C (`followup-reference.md` → "When `pnpm josh release` runs", the single source). A `fullrun`
+invoked as one child of a `backlogrun` does not ask it — that batch asks once at its own end.

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

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

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

@@ -0,0 +1,73 @@
+# `halfrun` — the manifest (implement + verify, stop before commit)
+
+`halfrun` sits between `kickoff` (plan only) and `fullrun` (full execution with auto-merge). It
+implements the change and runs the full verification gate, then **stops before commit** — nothing is
+committed, pushed, or opened as a PR — so the user manually verifies the change (typically by exercising
+the UI in a browser) against the working tree. Use `halfrun` when the change has UI/UX implications or
+anything else that requires human eyes before shipping.
+
+**This file is the manifest** (joshuafolkken/kit#2189): the ordered steps as terse triggers and
+pointers, the detail read on demand from the file each pointer names.
+
+## The ordered entry sequence
+
+1. **Claim the working tree first** — `pnpm josh run:hold <N>` (bare for `halfrun new`), ahead of the
+   title and a `new` entry's filing; `busy` / `unknown` stop with a `confirmation` Telegram. **The stop
+   before commit keeps the hold** (the uncommitted work is what a second run would trample); a stop on a
+   split, prerequisite or third-party target releases it. `working-tree-hold.md` is the single source; a
+   cross-repository target resolves its checkout from `pnpm josh doctor` first (`target-repository.md`).
+2. **Apply `in-progress` the moment `run:hold` answered `hold`** — the stop before commit keeps it on;
+   a stop that leaves the tree clean removes it in the same turn as `pnpm josh run:release` (`gh api -X
+   DELETE repos/{owner}/{repo}/issues/<N>/labels/in-progress 2>/dev/null || true`).
+3. **Ask the session boundary in the same turn as the hold** — `pnpm josh cost --cut`, exactly as
+   `fullrun`; `over` stops with a `confirmation` Telegram and the resume command (`halfrun #<N>` /
+   `halfrun new`). **Skip it when dispatched by a batch.** `backlogrun-progress.md` → "The hand-off" is
+   the single source of the check and the shared 135,000 threshold.
+4. **Start the progress watcher once the hold is claimed** — `pnpm josh run:progress --wait` in the
+   background, `--mark` in the same turn as every real report; the stop before commit ends the watcher
+   itself (`backlogrun-progress.md` → "Progress while the run is quiet").
+5. **Gather the mechanical reads — `pnpm josh run:prep <N>`** (`issue:read`'s body/comments — `SKILL.md`
+   → §2g → `issue-comments.md`; `issue:state`'s `human_review`; `latest:scope`), then `pnpm josh
+   run:next <N>`.
+
+## The step list
+
+`halfrun #<N>`: add `in-progress` → read Issue #N and its comments → **normalize the title** (same as
+`fullrun`) → post the agreed plan only if the body is blank → `git switch main && git pull`, then `pnpm
+josh latest:scope` and update dependencies only on `required` (`latest-gate.md`; load the
+`dependency-update` skill on `required`) → implement → run the **full verification gate** (refactor →
+start `pnpm josh gate` beside a subagent `/code-review` with the brief `pnpm josh review:brief` prints,
+join the gate before the stop, iterate to no high/medium findings, at most two reviews → `pnpm josh
+test:e2e`, run by **you**, because `halfrun` opens no pull request and there is no CI E2E job; a printed
+skip is the answer where the project has no suite) → send a `confirmation` Telegram with the resume
+commands in the body → **stop**. Plan comments are in the session language. The `confirmation` Telegram
+body MUST include the exact resume commands: `pnpm josh notify --task-type confirmation --issue-url
+"<issue-url>" --body=$'halfrun ready for manual verification\nNext: pnpm josh git -y "<title> #<N>" &&
+pnpm josh followup "<title> #<N>" --notify-message "Implemented <title>\\nCause: ...\\nFix:
+...\\nResult: ...\\n\\nDetails:\\n- <change1>"'`.
+**Invoking `halfrun` is _not_ authorization to commit, push, or merge** — do not run `pnpm josh git -y` or `pnpm josh followup` yourself. If the user comes
+back with fixes, treat each as a new round: implement, re-run `pnpm josh gate`, send another
+`confirmation` Telegram, stop again.
+
+`halfrun new` or `halfrun new "<title>"`: `kickoff new` + `halfrun #<N>` (no Issue exists yet). Steps
+mirror `fullrun new` (1)–(8): derive an English title (or use the provided one) → **run `pnpm josh
+issue:scout "<title>" [--body "<summary>"]` before creating the Issue** (`SKILL.md` → §2e) → create the
+Issue (`gh api repos/{owner}/{repo}/issues -f title="<title>" -f 'labels[]=depth:<n>' -f body="<body>"`,
+body per `prompts/collaboration-workflow/issue-template.md`) → add `in-progress` → post the agreed plan → stash
+any pre-existing changes with `git stash push -m "halfrun new: pre-existing changes"`, popped by
+message with `pnpm josh stash:pop "halfrun new: pre-existing changes"`, never a positional `git stash pop` →
+`git switch main && git pull` → `pnpm josh latest:scope` → implement → run the gate (as above, `pnpm
+josh test:e2e` run by **you**) → send the `confirmation` Telegram and **stop**.
+
+## The stop branches
+
+- **`needs-human-review`** — implement and gate, then stop before the commit; `needs-human-review.md`.
+- **A split** — the assessment (`split-assessment.md` → "The question") finds two or more
+  separately-mergeable deliverables over one gate: file the children (each `route:split`) and the epic,
+  then **STOP** with "Please run `backlogrun #<E> --only` to execute this epic." Typing `halfrun`
+  authorized implementing **one** Issue and stopping for manual verification, never a batch.
+- **A prerequisite** — file it (`route:tier-a`), stash, record the dependency, and **STOP**;
+  `prerequisite.md` is the single source of the filing, the `-u` stash and the epic:bundle branch.
+- **An observation** — file it without asking and carry on; `SKILL.md` → §2i.
+
+**Automatic filing is capped at 10 Issues per run.** On reaching it, stop and report.

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

@@ -0,0 +1,48 @@
+# The `into <target>` suffix — where the new Issue lands
+
+**This is `SKILL.md` → §2a's body, read at its point of use — the moment a `new` entry is typed with
+an `into <target>` suffix, not at any entry** (joshuafolkken/kit#2161). A run given a `#N` or a bare
+`new` never reaches it, so it costs a workflow entry nothing to leave it here. `SKILL.md` → §2a keeps
+the trigger and points here.
+
+`kickoff new` / `fullrun new` / `halfrun new` accept a suffix naming the epic the run's artifact
+belongs to. Without it the artifact belongs to no epic, and `epic:next` only ever offers an epic's
+children — so a forgotten instruction parks that Issue permanently rather than losing it visibly.
+
+```
+kickoff new into #909
+fullrun new into #909
+halfrun new into #909
+kickoff new "<title>" into #909
+kickoff new into joshuafolkken/kit#909
+```
+
+`into` is the spelling because the alternatives collide with forms that already mean something else:
+`kickoff new #909` reads as the existing `kickoff #N`, and `kickoff new epic #909` reads as "create a
+new epic" when what gets created is often a single Issue.
+
+- **One artifact goes in: the top-level one this run created.** No split, and it is the Issue; a
+  split, and it is the epic. The children belong to that epic, not to the target.
+- **Insert as soon as the artifact exists** — before implementation in `fullrun new`, before the plan
+  comment in `kickoff new`. Left until the end, a run that stops halfway leaves behind exactly the
+  orphaned Issue this suffix exists to prevent.
+- **The insertion always goes through `pnpm josh epic --add <E> <N> [--before <M> | --after <M>]`.**
+  Never hand-edit the epic body: the declaration and the `blocked-by` relations then disagree,
+  `epic:next` answers `error`, and an unattended run stops.
+- **Decide the position, then record why** — in the target epic's body or as an Issue comment. The
+  position follows whatever criteria the target epic has already been ordered by — work whose effect
+  compounds over the remaining children goes earlier, and a child already in progress is never jumped
+  ahead of.
+- **A target that is not an epic is refused, and the refusal names both ways out**:
+  `pnpm josh epic --promote <N> <N...>` when it is a request, a discussion or a container, or a new
+  epic over both when it is itself one of the deliverables. Never promote on your own — which arm
+  applies depends on what the target is, and promoting rewrites someone else's Issue into a container.
+- **A cross-repository target is written `owner/repo#N`** and inserted from that repository's
+  checkout; run there, since `epic --add` reads and writes only the repository it runs from
+  (`prompts/collaboration-workflow/cross-repo-epic.md`). A bare `#N` resolves to this repository's
+  issue of that number.
+- **No suffix leaves the behavior exactly as it was.**
+
+**It is not `epic:bundle`, and both still run.** `epic:bundle` *recommends* an epic for a newly filed
+Issue and does nothing when the signal is weak; `into` is a person naming one explicitly. They are
+separate routes, so the `epic:bundle` call that follows a filing happens exactly as before.

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

@@ -0,0 +1,109 @@
+# An Issue's comments are part of the Issue
+
+**This is the body of `SKILL.md` §2g, relocated here so the entry read carries the trigger and the
+pointer, not the procedure** (joshuafolkken/kit#2189). `SKILL.md` §2g is the resident stub, and every
+`#N` entry file routes here for the definition. It is read at its point of use — before implementing a
+`#N` Issue.
+
+**Every `#N` entry point reads the Issue's comments before it implements** — `fullrun`, `halfrun` and
+`kickoff`. A `backlogrun` named issue and a `backlogrun` epic child inherit it rather than restate it: each runs in a
+delegated unit executing `fullrun`'s procedure, and the hook keys its once-per-run record on the
+*fork's* transcript, so every child is delivered to in its own right. The read is one call, made in the
+same turn as whatever else the run already needs:
+
+```bash
+pnpm josh issue:read <N> [<N> ...]     # body and comments, one call per batch; alias: josh ird
+gh api repos/{owner}/{repo}/issues/<N>/comments --jq '.[] | {user: .user.login, created_at, body}'
+```
+
+**The first line is the one to type**; `pnpm josh issue:read` answers the body and the comments for
+every number named, in one call, and **says when a comment listing could not be read rather than
+showing no comments** — which matters here, because the rule below is that the later text wins and a
+comment nobody read cannot win anything. The `gh api` form stays for a **cross-repository** read: the
+command takes no `--repo`.
+
+`gh issue view <N> --comments` is GraphQL-backed, a cloud session is answered `403`, and
+`scripts/gh/gh-document-guard.test.ts` refuses it in a runnable block. The REST call above is the portable
+form.
+
+**This repository writes its agreements into comments and then reads only bodies.** A Tier A decision
+is logged as an Issue comment; the review round cap records a dropped finding's disposition; the
+backlog's decision pass writes each decision to a comment on the child; a stash left behind is recorded on the Issue. **The
+place a run is told to write is the place it was never told to read**, and nothing in a body says it
+has been superseded, so the mistake is silent.
+
+**What the reading is for**, so it is not skimmed: the boundary of the scope — work a comment moved to
+another Issue, or added to this one; the record of an auto-decision already made; a split or epic
+agreement reached after filing; a recorded stash or an in-flight branch; and a **correction of the
+body's own diagnosis**.
+
+## When a comment contradicts the body
+
+**The later text is the agreement in force.** A body is written first and is not rewritten when a
+decision arrives, so of a body and a comment that disagree the comment is the newer of the two and
+wins. **This is settled by ordering, never by judging which reads better.** Name in the two-layer work
+summary which comment superseded what.
+
+**Two answers are not the run's to make, and each is decided from what the comment says:**
+
+- **A comment that reassigns part of the scope to another Issue** takes that part out of scope: do not
+  implement it, whatever acceptance criteria the body still lists, and name the Issue it went to in the
+  completion report.
+- **A comment saying the Issue no longer has a reason to exist** — the defect does not reproduce, or it
+  was fixed elsewhere — takes the exit in the next subsection, "When the work turns out to be already
+  merged". Closing an Issue is Tier C.
+
+Everything else is the ordinary work of the run, **a widened scope included**: a widening large enough
+to be several separately-mergeable deliverables is the split assessment's business
+(`split-assessment.md`), not a second kind of stop.
+
+## When the work turns out to be already merged
+
+**A run can learn its Issue is already done in two ways, and both end here.** A **comment** says so —
+the bullet above — or the **run itself verifies it**, by reading the merged code and finding every
+acceptance criterion already satisfied. What is left to do afterwards is identical, so there is one
+procedure and not two. **Parking it is not the place**: `needs-decision` means "waiting for an answer
+nobody has given", and here the answer exists.
+
+**The exit is the `already-done` label.** It is `needs-decision`'s counterpart: `epic:next`,
+`backlog:next` and `auto-ok:next` all stop offering the Issue (`scripts/git/issue-labels.ts` →
+`NOT_DIRECTLY_RUNNABLE_LABELS`, `epic-classify.ts` → `human`), and `epic:busy` stops counting it as
+holding a lane. **Only a person removes it, by closing the Issue.**
+
+```bash
+gh api repos/{owner}/{repo}/labels -f name=already-done -f color=6f42c1 -f description="Verified already merged — a person closes it" --silent 2>/dev/null || true
+gh api repos/{owner}/{repo}/issues/<N>/labels -f 'labels[]=already-done'
+gh api -X DELETE repos/{owner}/{repo}/issues/<N>/labels/in-progress 2>/dev/null || true
+```
+
+The procedure, in order:
+
+1. **Record the evidence as an Issue comment, before the label.** Name the pull request or commit that
+   merged the work and, for each acceptance criterion the Issue states, the file and lines that satisfy
+   it. **A claim with no citations is not the finding this exit is for.**
+2. **Apply `already-done` and remove `in-progress`** — the two commands above. Leaving `in-progress`
+   on holds a lane against an Issue nothing will ever run.
+3. **Commit nothing, push nothing, open no pull request.** The tree is clean, so release the hold with
+   `pnpm josh run:release <N>`.
+4. **Then behave as the entry point does for a parked child.** A `fullrun` / `halfrun` a person typed
+   sends a `confirmation` Telegram naming the Issue and the merge that already covers it, and stops. An
+   `backlogrun` child is park-and-continue (`backlogrun-park.md` → "park and continue").
+5. **Never close the Issue.** That is Tier C at every entry point, and the label leaves the close one
+   click away for the person who owns it.
+
+**Nothing about this is a license to skip the work when it merely looks familiar.** The bar is step 1's
+citations: a criterion you cannot point at merged code for is a criterion this run still owes.
+
+## A long thread
+
+**The fetch is one call however long the thread is; what costs is carrying it afterwards** — which is
+why the call above projects each comment down to its author, its timestamp and its body. Once the
+thread runs longer than the Issue itself it is exactly the pre-implementation reading §2b describes:
+brief a delegated unit to return **the agreements in force plus the comment URLs that carry them**,
+never the comment text.
+
+**`pnpm josh rule:guard` refuses the body-only read** and hands over the reissue and the conflict rule
+at the moment they bind (`prompts/collaboration-workflow/rule-delivery.md`,
+`scripts/rules/delivered-rules.test.ts`). The refusal reaches Claude Code alone and fires once per run,
+so **this file is the rule and the hook is what makes it hard to walk past** — a session that runs
+no hooks still owes the read.

package/.claude/skills/workflow-commands/issue-fold-existing.md

@@ -0,0 +1,27 @@
+# 未着手 Issue への追加要件の統合
+
+## 候補の読み取り
+
+起票予定の目的・要件・受け入れ条件を含む全文を `pnpm josh issue:scout "<title>" --body-file <draft.md>` に渡す。明示的に参照した `#N` は見出しが似ていなくても候補になる。`Duplicates: incomplete` は読み取りまたは探索の不足であり、候補なしという結論ではない。
+
+候補の本文とコメントを `pnpm josh issue:read <N>` で全て読み、状態とラベルを `pnpm josh issue:state <N>` で読む。紐づく PR と依存・実行順も調べる。本文と後のコメントが矛盾した場合は後のコメントを採る。読み取り失敗や打ち切りがあれば統合可否は未確定とする。
+
+## 判定
+
+下書きの各受け入れ条件を既存 Issue と照合する。完全な重複は起票も編集もしない。別の成果物は従来の起票経路を使う。固有の追加要件を統合できるのは、既存 Issue が open かつ未着手で PR がなく、依存と実行順に衝突がなく、合計の規模が `split-assessment.md` → "The question" の一回の検証に収まる場合に限る。状態または判断材料が不明なら統合しない。
+
+判定記録の JSON を作り、`pnpm josh issue:fold-existing <assessment.json> --json` を実行する。`content` は `duplicate` / `compatible` / `separate` / `unknown`、`size_verdict` は `single` / `split` とする。ほかに `is_open`、`is_unstarted`、`has_pull_request`、`has_complete_read`、`has_dependency_conflict`、`is_separable`、`existing_body`、`draft_body`、`verification` を記録する。不明な事実は省略し、`inspect` を得る。判定記録は読んだ証跡であり、読み取りそのものの代わりにはならない。
+
+## 追記と再読
+
+`fold` の場合、追記案の `body` は元の本文を保持し、固有の追加要件と検証方法を末尾に加える。書き込み直前に本文とコメントが判定時から変わっていないことを再確認する。変わっていれば再判定する。
+
+```bash
+pnpm josh issue:fold-existing assessment.json --json > result.json
+jq -e '.verdict == "fold"' result.json
+jq '{body: .body}' result.json > patch.json
+gh api -X PATCH repos/{owner}/{repo}/issues/<N> --input patch.json
+pnpm josh issue:read <N>
+```
+
+再読して、元の要件・コメント中の判断記録・追加要件・検証方法が残ることを確認する。書き込みまたは再読が失敗した場合、統合は完了していない。統合時は新しい Issue を作らない。`separate` は従来の起票経路へ戻り、`inspect` は不足した情報を読み直す。

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

@@ -0,0 +1,45 @@
+# Filing an Issue — `SKILL.md` §2e's procedure
+
+Read this file when an Issue title exists and before the `gh api … issues` call that files it. Every
+filing asks whether the work already exists and which epic owns it; one command answers both:
+
+```bash
+pnpm josh issue:scout "<title>"                                   # alias: josh isc
+pnpm josh issue:scout "<title>" --body "<one-line summary, citing #N where the work follows one>"
+pnpm josh issue:scout "<title>" --body-file <complete-draft.md>
+```
+
+- **`Duplicates:` is read, not skimmed.** Open each candidate and apply `issue-fold-existing.md`
+  before deciding to file. A complete duplicate of an **open** Issue stops with a `confirmation`
+  Telegram and "Please run `fullrun #<existing>` to execute this Issue." A compatible addition follows
+  that file's fold path; a separate deliverable follows the ordinary filing path. A title match alone
+  never authorizes an edit.
+- **A candidate marked `(closed)` is a different answer.** The scan covers what closed recently as
+  well as what is open, because the work most likely to be filed twice is the work that just finished.
+  A closed candidate that covers the same work means **the work is already done** — so there is nothing
+  to run. Verify it against the merged code, then take the exit in `issue-comments.md` → "When the work
+  turns out to be already merged". A closed candidate that does *not* cover the work is noted in one
+  line and the filing carries on.
+- **`none` is an answer.** The command reports no candidate rather than the closest miss.
+- **`Epic:` front-loads the placement.** Its recommendation is `epic:bundle`'s, which makes
+  `add_to_epic` / `create_epic` Tier A and `ask` a stop, in exactly the reading `SKILL.md` → §2a's
+  `into <target>` suffix would have given by hand. Where the user typed `into <target>`, that naming wins.
+- **`Epic: not asked` is not `Epic: none`.** The epic half decides from the issue numbers the summary
+  names, so a title-only call gives it nothing. **Pass `--body` whenever the work follows an existing
+  Issue** — one line citing `#N` is enough, and naming the epic itself (`part of epic #<E>`) is
+  answered with that epic.
+- **It does not replace `epic:bundle`, which still runs after the filing.** This one answers about an
+  Issue that does not exist yet, from a title; that one answers about an Issue that does. Both calls
+  happen — the scout before the `issues` call, `epic:bundle` after it.
+- **Every filing route runs it, not only a `new` entry point, and `pnpm josh rule:guard` refuses a
+  filing the run has not scouted** (`prompts/collaboration-workflow/rule-delivery.md`) — the trigger is
+  the `gh api … issues` call, never which keyword started the run, so `SKILL.md` → §2d's prerequisite,
+  §2i's observation and the review round cap's branch-2 filing all go through it.
+- **A `#N` entry point does not run it *for the Issue it was handed*.** `fullrun #N` / `halfrun #N` /
+  `kickoff #N` are given an Issue that already exists. That says nothing about an Issue such a run goes
+  on to file later, which the bullet above covers.
+- **The split path files each child through the same step.** The epic itself is not scouted: it is
+  created over children that were, and `epic:bundle` places it afterwards.
+
+Full behavior, the thresholds and why the duplicate half compares titles rather than bodies:
+`docs/josh-commands.md` → "`josh issue:scout`".

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

@@ -0,0 +1,82 @@
+# `kickoff` — Planning phase only (plan → Issue → Telegram notify → stop)
+
+- `kickoff #<N>`: Read existing Issue #N **and every comment on it** — `pnpm josh issue:read <N>`; a
+  decision recorded after the body was written lives only in a comment, and the later text is the
+  agreement in force (`SKILL.md` → §2g, which also carries the two answers that stop the run instead) →
+  **normalize the title**: if the title is not in English or can be phrased more clearly, derive a
+  better English title and run `gh api -X PATCH repos/{owner}/{repo}/issues/<N> -f title="<title>"` →
+  analyze requirements → **scope assessment per `split-assessment.md`** → post the plan to the Issue (if
+  body is blank, `gh api -X PATCH repos/{owner}/{repo}/issues/<N> -f body="<plan>"`; otherwise
+  `pnpm josh issue:comment <N> --body-file <path>`) → send Telegram notification → **stop**
+  (do not implement). **When the assessment finds two or more separately-mergeable deliverables**, take
+  the split path instead of posting a plan: create the children as in `kickoff new`, then either
+  **promote `#N`** with `pnpm josh epic --promote <N> <N1> <N2> ... [--ordered] [--rationale-file
+  <path|->]` — the right choice when `#N` is a request, a discussion or a container — or, when `#N` is
+  itself one of the deliverables, keep `#N` as a child and create a new epic with `pnpm josh epic`. That
+  branch is Tier A: choose it and record the reasoning on the Issue without asking. Present `backlogrun #<E> --only` and stop. Plan comments are written in the session language (`JOSH_SESSION_LANG`, default `ja`).
+  Telegram notification: `pnpm josh notify --task-type planning --issue-url "<issue-url>" --body=$'-
+  <bullet1>\n- <bullet2>\n...'`. `--task-type` controls the header icon (`planning` 📋 / `completion` ✅
+  / `failure` ❌ / `kickoff_retry` 🔄 / `confirmation` ⏸️). `--repo-name` and `--issue-title` are
+  auto-fetched from `gh` when not supplied. The Issue URL must be included.
+
+**`kickoff` does not claim the working-tree hold, and does not release one.** What that guard protects
+is one branch, one index and one uncommitted diff; this command reads the Issue, normalizes the title,
+posts the plan, notifies and stops — every one of those against GitHub, none against the tree. So a
+`fullrun` running in this checkout never stops a `kickoff`, and a `kickoff` never touches the record
+that run is holding. It claims nothing, so it must not release anything either. `SKILL.md` → §2f is the
+single source.
+
+**The target repository is named in front of the Issue reference** — `kickoff kit#new`,
+`kickoff joshuafolkken/kit#412`. The definition is `SKILL.md` → §2c, whose body is `target-repository.md`. `kickoff` is the entry that needs
+no checkout: name the target repository in the path of every `gh api` call — reads included — and never
+clone. The one exception is the split path's epic, since `pnpm josh epic` writes only the repository it
+runs in — and the promote arm has no remote fallback at all, so it stops when that repository is not
+checked out here. A target whose owner is not this session's is third-party: Tier C, so it stops rather
+than filing.
+
+**Read `split-assessment.md` → "The question" first.** It is the split decision every entry point
+applies, including this one — `kickoff #N` assesses scope exactly as `kickoff new` does. Its default is
+not to split: separability and a scope that clearly exceeds what one verification gate can confirm in
+one pass (the guide is about 10 changed files and about 400 changed lines) have to hold **together**.
+The rest of `split-assessment.md` — what each entry does with the answer — is read on demand when a
+split is found.
+
+- `kickoff new` or `kickoff new "<title>"`: No Issue exists yet. Steps: (0) **Scope assessment** per
+  `split-assessment.md`. If multiple → the **multi-issue split path**; if single → the **single-issue
+  path**. **Single-issue path**: (1) Derive an English title from the conversation, or use the provided
+  title. **(1a) Run `pnpm josh issue:scout "<title>" [--body "<summary>"]` before creating the Issue** —
+  a candidate that covers the same work stops the run rather than filing a second Issue (`SKILL.md` →
+  §2e). (2) Create Issue: `gh api repos/{owner}/{repo}/issues -f title="<title>" -f 'labels[]=depth:<n>'
+  -f body="<body>"` (body per `prompts/collaboration-workflow/issue-template.md`). Capture `<N>`. (3)
+  Post the plan in the session language, using the same body/comment logic as `kickoff #<N>`. (4) Send
+  Telegram notification. (5) **Stop** — do not implement. **Multi-issue split path**: (1) For each
+  independent deliverable, derive a focused English title, **run `pnpm josh issue:scout "<sub-title>"`
+  on it** (`SKILL.md` → §2e), and create a separate Issue with the `route:split` label: `gh api
+  repos/{owner}/{repo}/issues -f title="<sub-title>" -f 'labels[]=route:split' -f 'labels[]=depth:<n>'
+  -f body="<body>"`. Capture each Issue number. **When the split is filed into a repository other than
+  the one this session is running in**, every child body gets the `## Origin` backlink described in the
+  cross-package rule the AI documents keep resident, the epic body carries the same link as prose or a
+  plain bullet (never as a checkbox row, which would disable its auto-close), and the originating Issue
+  lists the children and the epic under `## Upstream issues`. (2) **Epic — always, for every split into
+  two or more Issues.** There is no count or ordering condition. **Create it with `pnpm josh epic
+  "<epic-title>" <N1> <N2> ... [--ordered] [--rationale-file <path|->] [--origin <owner/repo#N>]`**,
+  capturing its number `<E>` from the printed URL. The command satisfies the epic's four mechanical
+  requirements by construction — the `epic` label, the task-list rows (`- [ ] #N`), the machine-readable
+  `Dependencies`, and the printed `backlogrun` line. Check an epic you wrote or edited by hand with `pnpm
+  josh epic:check <E>`. Only where `josh` is unavailable, fall back to the manual procedure: ensure the
+  label exists (`gh api repos/{owner}/{repo}/labels -f name=epic -f color=5319e7 -f description="Tracks
+  a batch of child issues from one split" --silent 2>/dev/null || true`), then create the epic with `gh
+  api repos/{owner}/{repo}/issues -f title="<epic-title>" -f 'labels[]=epic' -f body="<body>"`. Its body
+  follows the epic format in `prompts/collaboration-workflow/issue-template.md` — split rationale,
+  dependencies, the `backlogrun` command, and a child task list in task-list syntax (`- [ ] #N`). The epic
+  exists as the **non-closing home for the split rationale**. When the children have no required order,
+  write `None — the children are independent; any execution order works.` under `Dependencies`. **The
+  epic itself is never implemented** — a `backlogrun` takes a named epic and runs its *children*. `pnpm josh
+  followup` closes it automatically once every child is closed. **Only when the execution order
+  matters**, record it natively: `pnpm josh epic --ordered` treats the argument order as the dependency
+  order; on the manual fallback path, after the child Issues exist, `gh api
+  repos/{owner}/{repo}/issues/<N2>/dependencies/blocked_by -F issue_id="$(gh api
+  repos/{owner}/{repo}/issues/<N1> --jq .id)"` for each dependent pair (the endpoint takes the blocker's
+  **database id**, not its issue number; a failure here is non-fatal). Never fold the relation into the
+  creation call. (3) Send Telegram notification listing all created issues. (4) Present the command
+  `backlogrun #<E> --only`. (5) **Stop** — do not implement.