@joshuafolkken/kit 1.978.0 → 1.998.0

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

@@ -350,8 +350,9 @@ a publish that predates the change.
 
 ## `josh epic:bundle <N>` — does this new issue belong with one already filed?
 
-Run it right after an issue is filed: by `kickoff` / `fullrun` / `halfrun`, or by any Tier A filing
-mid-implementation, including inside a `backlogrun`. **It recommends; it writes nothing.**
+It runs right after an issue is filed: by `kickoff` / `fullrun` / `halfrun`, or by any Tier A filing
+mid-implementation, including inside a `backlogrun`. **`pnpm josh issue:file` runs it as its last step**;
+run it by hand only when that step printed `⚠`. **It recommends; it writes nothing.**
 
 "Two or more always means an epic" only fires when one request is split on the spot. Two issues filed
 days apart that turn out to be the front and back of one job are executed separately, in whatever
@@ -454,9 +455,9 @@ decisions" section above says what to do instead.
 answers the same epic question for an issue that does not exist yet — this decision, called rather
 than restated — and beside it the one thing this one deliberately refuses: whether the work has
 already been filed, from a title comparison (joshuafolkken/kit#1252). **Both run**, and neither
-replaces the other: the scout is what a `new` entry point asks before `gh api … issues`, and
-`epic:bundle` is what it asks afterwards, from the real number and the relations recorded against it.
-Full behavior: `docs/josh-commands.md` → "`josh issue:scout`".
+replaces the other: `pnpm josh issue:file` runs the scout before it creates the issue, and
+`epic:bundle` afterwards, from the real number and the relations recorded against it.
+Full behavior: `docs/josh-commands.md` → "`josh issue:file`".
 
 **When the relation carries an order, record it** in `blocked-by` and in the epic's `Dependencies` —
 on an addition as much as on a new epic. Without it the batch survives and the reason for it does

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

@@ -193,15 +193,15 @@ third of four mid-run discoveries, distinct from an upstream defect, a split (`s
 and an observation (§2i). The full table, the filing command, the `-u`/`stash:pop` steps and the
 10-per-run cap are `prerequisite.md`, its single source, read at that trigger. **When the prerequisite
 is the run's second filing, `pnpm josh issue:fold` runs first** (§2e), and `pnpm josh rule:guard`
-refuses the second `gh api … issues` call until it has.
+refuses the second `pnpm josh issue:file` call until it has.
 
 ## 2e. Before filing a new Issue — `pnpm josh issue:scout`
 
-**Before every new Issue is filed, run `pnpm josh issue:scout <title>` and read its duplicate and epic
-answers.** This applies inside every workflow, including observations and review follow-ups. The
-guard refuses a filing without it. Read `issue-scout.md` at that point for the duplicate, closed-Issue
-and epic decisions; `issue-fold-existing.md` handles a compatible duplicate. `docs/josh-commands.md`
-→ "`josh issue:scout`" defines the command's output.
+**Every new Issue is filed with `pnpm josh issue:file`, which runs the `issue:scout` scan first — read
+its duplicate and epic answers.** This applies inside every workflow, including observations and review
+follow-ups. The guard refuses any other filing call. Read `issue-scout.md` at that point for the
+duplicate, closed-Issue and epic decisions and for `--distinct`; `issue-fold-existing.md` handles a
+compatible duplicate. `docs/josh-commands.md` → "`josh issue:file`" defines the command.
 
 ## 2f. The working-tree hold — one run per tree
 
@@ -239,14 +239,14 @@ parent-wake half at `backlogrun-progress.md` → "The parent keeps no clock of i
 **When a first-party observation is worth filing, file it without asking and continue the run.**
 Read `observation-filing.md` in full before filing: it decides the depth test, filing ceilings, labels,
 second-filing fold, ledger fallback and delegated-child handoff. Use `pnpm josh repo:party` to decide
-first-party status, then run `pnpm josh issue:scout` before filing (§2e). A third-party target remains
+first-party status, then file with `pnpm josh issue:file` (§2e). A third-party target remains
 Tier C (`CLAUDE.md`).
 
 ## 2j. The end-of-run retrospective — read when `run:step` prints it
 
 **When `pnpm josh run:step` prints the retrospective step, read `retrospective.md` in full and run the
-digest it names once.** File up to two worthwhile improvements through `issue:scout` and
-`epic:bundle`, stack the rest in the observation ledger, and close the step with the command described
+digest it names once.** File up to two worthwhile improvements through `issue:file` (scout and
+`epic:bundle` included), stack the rest in the observation ledger, and close the step with the command described
 there. A dispatched lane child never runs the retrospective.
 
 ## 3. What stays resident, and what is read from here

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

@@ -110,7 +110,7 @@ with. Applied to the three waits a run actually has:
 | --------------- | ----------------- |
 | `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, and `pnpm josh epic:bundle <new>` (`prompts/review.md` → "Review round cap") |
+| 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 and holds the session. **The post-merge tail is what overlaps here, and it is taken before the call rather than beside it**: 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 completion notification for `pnpm josh git -y` is what

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

@@ -90,7 +90,7 @@ still bounded at 25 lines. `pnpm josh lane:dispatch` is where a lane's child is
 child over" in `backlogrun-lanes.md` carries the command.
 
 **The lane child uses the invoking CLI's `worker` profile.** Claude Code defaults to Anthropic
-`claude-opus-5-5` / `medium`; Codex uses `codex exec`, OpenAI `gpt-6-sol` / `medium`, workspace-write and
+`claude-opus-5-5` / `medium`; Codex uses `codex exec`, OpenAI `gpt-6.1-sol` / `medium`, workspace-write and
 JSONL. `JOSH_WORKER_MODEL` overrides Claude Code only; `JOSH_WORKER_EFFORT` covers both providers,
 and legacy `JOSH_LANE_*` applies only here. Bad markers, missing CLI/auth and failure
 refuse or park without fallback or retry.

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

@@ -237,7 +237,7 @@ setting are `docs/josh-commands.md` → "`josh run:wake`".
 
 **Every unattended role runs with the provider selected from the invoking CLI and its own profile.**
 Codex sessions use OpenAI; Claude Code sessions use Anthropic. Anthropic uses scheduler
-`claude-opus-5-5`, worker `claude-opus-5-5` and reviewer `claude-opus-5-5`; OpenAI uses `gpt-6-sol`,
+`claude-opus-5-5`, worker `claude-opus-5-5` and reviewer `claude-opus-5-5`; OpenAI uses `gpt-6.1-sol`,
 with role efforts `medium`/`medium`/`high` (scheduler / worker / reviewer) for both. Role overrides
 resolve before launch; model overrides apply only to Claude Code, effort overrides to either provider,
 and legacy `JOSH_LANE_*` values to the worker only. Invalid configuration, a missing or conflicting

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

@@ -7,7 +7,7 @@ the run is at, and the sections below carry that step in full.
 
 ## The `fullrun #N` step list
 
-Use `pnpm josh issue:lint` `labels:`; see `prompts/collaboration-workflow/issue-template.md`.
+File Issues with `pnpm josh issue:file` (it applies the classification labels); see `prompts/collaboration-workflow/issue-template.md`.
 
 **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
@@ -29,7 +29,7 @@ with the brief `pnpm josh review:brief` prints on `git diff main`, join the gate
 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
+branch-2 filing (`pnpm josh issue:file`, which runs `epic:bundle` itself) 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`
@@ -49,10 +49,10 @@ completion notification, then merges; if blockers are found it exits non-zero
 ## 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-file>` (per `prompts/collaboration-workflow/issue-template.md`). Capture `<N>`. (3) Add
+(2) Create Issue: `pnpm josh issue:file "<title>" --body-file <body-file> --depth <n>` (per
+`prompts/collaboration-workflow/issue-template.md`) — its duplicate scan runs first, and a candidate
+that covers the same work stops the run rather than filing a second Issue (`SKILL.md` → §2e). 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)
@@ -65,8 +65,8 @@ round 1's fixes are in and before the commit. (10) Where the tree was edited aft
 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
+before its gate. (12) File whatever the review round cap routed to branch 2 with `pnpm josh issue:file`
+(it runs `epic:bundle` 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

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

@@ -1,6 +1,6 @@
 # `halfrun` — the manifest (implement + verify, stop before commit)
 
-When this run files a new Issue, run `pnpm josh issue:lint <body-file>` and apply every label in its `labels:` answer at creation; `prompts/collaboration-workflow/issue-template.md` is the single source for this classification. Keep the existing `depth` and `route` labels.
+When this run files a new Issue, file it with `pnpm josh issue:file`, which lints the body and applies the classification labels it declares beside the `--depth` and `--route` labels; `prompts/collaboration-workflow/issue-template.md` is the single source for this classification.
 
 `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
@@ -56,10 +56,9 @@ back with fixes, treat each as a new round: implement, re-run `pnpm josh gate`,
 `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-file>`,
-body per `prompts/collaboration-workflow/issue-template.md`) → add `in-progress` → post the agreed plan → stash
+mirror `fullrun new` (1)–(8): derive an English title (or use the provided one) → create the Issue
+(`pnpm josh issue:file "<title>" --body-file <body-file> --depth <n>`, body per
+`prompts/collaboration-workflow/issue-template.md`; its duplicate scan is read per `SKILL.md` → §2e) → 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

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

@@ -104,6 +104,6 @@ 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,
+`scripts/rules/delivered-rules.test.ts`). The refusal reaches Claude Code alone and repeats until the comments are read,
 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-scout.md

@@ -1,12 +1,13 @@
 # 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:
+Read this file when an Issue title exists and before the `pnpm josh issue:file` call that files it.
+Every filing asks whether the work already exists and which epic owns it; the command runs the
+`issue:scout` scan on the title and body first and holds the filing until every printed candidate is
+named in `--distinct`:
 
 ```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>
+pnpm josh issue:file "<title>" --body-file <complete-draft.md> --depth <n> [--route <route>]
+pnpm josh issue:file "<title>" --body-file <complete-draft.md> --depth <n> --distinct 2801,2795
 ```
 
 - **`Duplicates:` is read, not skimmed.** Open each candidate and apply `issue-fold-existing.md`
@@ -14,32 +15,30 @@ pnpm josh issue:scout "<title>" --body-file <complete-draft.md>
   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.
+- **`--distinct` records that each candidate was read.** Reissue the call listing every candidate you
+  read and judged separate; never list one you have not read.
 - **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.
+  line, named in `--distinct`, 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` /
+- **`Epic: not asked` is not `Epic: none`.** The epic half decides from the issue numbers the body
+  names. **Cite `#N` in the body whenever the work follows an existing Issue** — one line is enough,
+  and naming the epic itself (`part of epic #<E>`) is answered with that epic.
+- **`epic:bundle` then runs on the new Issue, in the same call.** Act on its printed answer; a `⚠`
+  means rerun `pnpm josh epic:bundle <N>` — the Issue exists, so never refile.
+- **Every filing route goes through it** — §2d's prerequisite, §2i's observation and the review round
+  cap's branch-2 filing alike; the guard refuses any other filing call
+  (`prompts/collaboration-workflow/rule-delivery.md`).
+- **A `#N` entry point does not file *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.
+- **The split path files each child through the same command.** The epic is created with
+  `pnpm josh epic` over children that were scanned.
 
-Full behavior, the thresholds and why the duplicate half compares titles rather than bodies:
-`docs/josh-commands.md` → "`josh issue:scout`".
+Full behavior: `docs/josh-commands.md` → "`josh issue:file`" and "`josh issue:scout`".

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

@@ -44,16 +44,15 @@ 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-file>` (body per `prompts/collaboration-workflow/issue-template.md`). Capture `<N>`. (3)
+  title. (2) Create Issue: `pnpm josh issue:file "<title>" --body-file <body-file> --depth <n>` (body
+  per `prompts/collaboration-workflow/issue-template.md`) — its duplicate scan runs first, and a
+  candidate that covers the same work stops the run rather than filing a second Issue (`SKILL.md` →
+  §2e). 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-file>`. Capture each Issue number. **When the split is filed into a repository other than
+  independent deliverable, derive a focused English title and create a separate Issue with the
+  `route:split` label (its duplicate scan is read per `SKILL.md` → §2e): `pnpm josh issue:file
+  "<sub-title>" --body-file <body-file> --depth <n> --route split`. 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
@@ -81,4 +80,4 @@ split is found.
   creation call. (3) Send Telegram notification listing all created issues. (4) Present the command
   `backlogrun #<E> --only`. (5) **Stop** — do not implement.
 
-Before filing, run `pnpm josh issue:lint <body-file>` and apply every label in its `labels:` answer at creation, following `prompts/collaboration-workflow/issue-template.md` for classification.
+`pnpm josh issue:file` lints the body and applies the classification labels it declares, following `prompts/collaboration-workflow/issue-template.md` for classification (`docs/josh-commands.md` → `josh issue:file`).

package/.claude/skills/workflow-commands/observation-filing.md

@@ -20,17 +20,16 @@ on is dropped rather than filed.
 
 **The filing ceilings still apply.** Count this filing in the ten-Issue limit for the run. An
 observation is discretionary, so above 30 open Issues in the target repository, close one first or do
-not file (`prompts/collaboration-workflow/wip-cap.md`). Before the `gh api … issues` call, run
-`pnpm josh issue:scout "<title>"` (`issue-scout.md`). When it is the second filing of the run, run
+not file (`prompts/collaboration-workflow/wip-cap.md`). File it with `pnpm josh issue:file`
+(`issue-scout.md`), which lints the body against `prompts/collaboration-workflow/issue-template.md`,
+applies the classification labels it declares, runs the duplicate scan, and runs `epic:bundle` on the
+new Issue so it is offered by its epic; an `auto-ok` epic adds it to the backlog pool
+(`backlogrun-steps.md` → "What one invocation approves"). When it is the second filing of the run, run
 `pnpm josh issue:fold` first; the guard refuses that filing without the fold
-(`split-assessment.md` → "The same two questions decide the filing-time fold"). After filing, run
-`pnpm josh epic:bundle <new>` so the Issue is offered by its epic; an `auto-ok` epic adds it to the
-backlog pool (`backlogrun-steps.md` → "What one invocation approves").
+(`split-assessment.md` → "The same two questions decide the filing-time fold").
 
 The detail below is read at the filing decision, and the marker suite pins the rules here.
 
-Before filing an observation, run `pnpm josh issue:lint <body-file>` and apply every label in its `labels:` answer at creation; `prompts/collaboration-workflow/issue-template.md` is the single source. Keep the depth label.
-
 ### The depth test — a discretionary filing cites the product work it blocked
 
 **A run that has just spent an hour inside the workflow tooling files findings about the workflow
@@ -53,11 +52,11 @@ it — read off the subject rather than judged**:
 single source**, and a label description that paraphrased it would be a second copy of the rule.
 **Every filing route applies one**, this route and the other three of §2d's table alike: a `new`
 entry point, a `route:tier-a` prerequisite, a `route:interrupt`, a split child and a review round
-cap's branch-2 filing all pass through a `gh api … issues` call, and the depth label goes in it
-beside whatever `route:` label that call already carries.
+cap's branch-2 filing all pass through a `pnpm josh issue:file` call, and the depth goes in it as
+`--depth <n>` beside whatever `--route` that call already carries.
 
 ```bash
-gh api repos/{owner}/{repo}/issues -f title="<title>" -f 'labels[]=depth:1' -F body=@<body-file>
+pnpm josh issue:file "<title>" --body-file <body-file> --depth 1
 gh api repos/{owner}/{repo}/issues/<N>/labels -f 'labels[]=depth:1'   # an Issue already filed
 ```
 

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

@@ -25,16 +25,17 @@ stays countable by filing route afterwards. **This paragraph belongs to the prer
 the table** — the label means a filing the run is *blocked by*, so the observation row carries no
 `route:` label of its own (§2i):
 
-Before that call, run `pnpm josh issue:lint <body-file>` and apply every label in its `labels:` answer at creation; `prompts/collaboration-workflow/issue-template.md` is the single source. Keep `route:tier-a` and `depth`.
-
 ```bash
-gh api repos/{owner}/{repo}/issues -f title="<title>" -f 'labels[]=route:tier-a' -f 'labels[]=depth:<n>' -F body=@<body-file>
+pnpm josh issue:file "<title>" --body-file <body-file> --depth <n> --route tier-a
 ```
 
+The command lints the body against `prompts/collaboration-workflow/issue-template.md`, applies the
+classification labels it declares, and runs the duplicate scan and `epic:bundle` itself
+(`docs/josh-commands.md` → `josh issue:file`).
+
 Every "file the prerequisite" below means that labelled filing, and it always happens **first**: the
-steps after it name a number that does not exist until it is. **`pnpm josh issue:scout "<title>"` goes
-in front of that call, exactly as it does for a `new` entry** (§2e): a filing made mid-run is the one
-most likely to duplicate something.
+steps after it name a number that does not exist until it is. **Its duplicate scan is read exactly as
+it is for a `new` entry** (§2e): a filing made mid-run is the one most likely to duplicate something.
 
 **Each entry point's own branch stays in that entry's file:**
 

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

@@ -53,11 +53,11 @@ ceiling on what may be recorded. **File nothing when nothing passes** — a run
 improvement worth carrying files zero Issues, and that is what makes the "file → drain → file again"
 loop converge.
 
-**Exclude what is already filed or already done, through the existing scout** (`SKILL.md` → §2e). Run
-`pnpm josh issue:scout "<title>"` before each `gh api … issues` call: an **open** candidate covering the
-same work means do not file it, and a `(closed)` candidate covering it means the work is already merged.
-Neither exclusion is a new mechanism. After filing, `pnpm josh epic:bundle <new>` places each Issue, as
-after any filing.
+**Exclude what is already filed or already done, through the existing scout** (`SKILL.md` → §2e). File
+each with `pnpm josh issue:file`, which runs the scout before creating anything: an **open** candidate
+covering the same work means do not file it, and a `(closed)` candidate covering it means the work is
+already merged. Neither exclusion is a new mechanism. The same call runs `epic:bundle` on each new
+Issue, as after any filing.
 
 ## `auto-ok`, and closing the step
 

package/.claude/skills/workflow-commands/rule-residency.md

@@ -165,8 +165,8 @@ again (joshuafolkken/kit#1525).
 - **The Issue's comments** — `pnpm josh rule:guard` refuses the `Bash` call that reads an Issue's
   body without them (`gh issue view <N>`, or a `GET` of a path ending `…/issues/<N>`) and hands over
   the reissue that carries them plus the rule for a comment that contradicts the body. It is the one
-  row whose trigger `batch:guard` also considers, so it stands aside on that guard's turn and fires
-  on the reissue. §2g is the procedure and stays here, because a session that runs no hooks still
+  row whose trigger `batch:guard` also considers, yet it refuses on that guard's turn too, since it
+  repeats until the comments are read. §2g is the procedure and stays here, because a session that runs no hooks still
   owes the read (`prompts/collaboration-workflow/rule-delivery.md`,
   `scripts/rules/delivered-rules.test.ts`).
 - **The prohibition on putting a body inside shell double quotes** — `pnpm josh rule:guard` refuses

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

@@ -31,7 +31,7 @@ same conjunction**: separability, and whether the whole clearly exceeds one gate
 `pnpm josh split:assess`, called not recomputed, and `separate` needs both halves exactly as `split`
 does. **There is no second criterion.** §2i's observation, the review round cap's branch 2 and §2d's
 prerequisite each route a second filing through it, delivered by `pnpm josh rule:guard` at the run's
-second `gh api … issues` call, never the first.
+second `pnpm josh issue:file` call, never the first.
 
 ## Why the default is not to split
 
@@ -88,8 +88,9 @@ the whole point of one definition is that where the split was noticed cannot cha
 The epic is the non-closing home for the split rationale. A comment on the first child is buried the
 moment that child merges and closes.
 
-**Each split child is filed with the `route:split` label**, so the backlog's composition stays
-countable by filing route rather than by grepping issue bodies.
+**Each split child is filed with the `route:split` label** —
+`pnpm josh issue:file "<sub-title>" --body-file <body-file> --depth <n> --route split` — so the
+backlog's composition stays countable by filing route rather than by grepping issue bodies.
 
 ## Promote, or create a new epic
 

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

@@ -37,12 +37,13 @@ backlogrun joshuafolkken/kit#858 --only
   explicit instruction that rule requires. **Send a `confirmation` Telegram and stop** — nothing has
   been produced yet, so there is no finding to record and no draft to prepare.
 - **No prefix leaves the behavior exactly as it was** — the target is the session's repository.
-- **`kickoff` needs no checkout**: name the target repository in the path of every `gh api` call and
-  never clone. The one exception is the split path's epic, since `pnpm josh epic` only writes the
-  repository it runs in — run it in that repository's checkout, or fall back to `gh api
-  repos/<owner/repo>/labels …` followed by `gh api repos/<owner/repo>/issues -f title="<epic-title>" -f
-  'labels[]=epic' -F body=@<body-file>`, and report that `epic:check` could not be run. The promote arm has
-  no such fallback: with no checkout there, file the children and stop.
+- **`kickoff` needs no checkout**: name the target repository with `--repo <owner/repo>` on every
+  `pnpm josh issue:file` call and in the path of every `gh api` call, and never clone. The one exception
+  is the split path's epic, since `pnpm josh epic` only writes the repository it runs in — run it in
+  that repository's checkout. With no checkout there, file the children, report that the epic could
+  not be created, and stop — a hand-built `gh api …/issues` filing of the epic is refused by the
+  `direct-filing` guard, and `pnpm josh issue:file` lints an epic body against the Issue template. The
+  promote arm stops the same way.
 - **The implementing entries require a checkout and never create one — when the target is another
   repository.** A prefix naming the session's own repository changes nothing (`fullrun kit#412` in the
   kit checkout behaves exactly as `fullrun #412`). Otherwise resolve the checkout from `pnpm josh

package/.github/workflows/sonar-qube.yml

@@ -19,16 +19,26 @@ jobs:
     permissions:
       contents: read
     runs-on: ubuntu-latest
+    # A consumer that does not use SonarCloud has no SONAR_TOKEN, and the scan would fail on
+    # authentication and turn a required check red (joshuafolkken/kit#2815). `secrets` cannot be read
+    # in a step `if:`, so the secret is lifted into the job env and the steps branch on that instead.
+    # Token presence is the only signal that needs no consumer setup; a run GitHub withholds secrets
+    # from (a fork pull request, Dependabot without the secret) skips too — see sonar-hotspot-handling.md.
+    env:
+      SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
     steps:
+      - name: Skip SonarQube Scan
+        if: env.SONAR_TOKEN == ''
+        run: echo "SonarQube scan skipped because SONAR_TOKEN is not set."
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        if: env.SONAR_TOKEN != ''
         with:
           fetch-depth: 0 # Shallow clones should be disabled for a better relevancy of analysis
       - name: SonarQube Scan
+        if: env.SONAR_TOKEN != ''
         uses: SonarSource/sonarqube-scan-action@ba9859eae8dd6bd29e412f25ddbbef3d032000f4 # v8.2.2
         with:
           # Wait for the SonarCloud Quality Gate and fail this job (a required PR check) when the
           # gate is red, so a PR that introduces a Maintainability / code-smell finding cannot be
           # merged green. Without this flag the scan only uploads results and never blocks.
           args: -Dsonar.qualitygate.wait=true
-        env:
-          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}

package/CLAUDE.md

@@ -108,7 +108,7 @@ For every code modification, in order:
 
    - **Tests are required for ALL code changes** (bug fixes, timing/animation fixes and refactors included): bug fix → regression test; UI/animation/timing → E2E for the observable change; logic/utility → unit; refactor → tests pinning existing behavior BEFORE the change (`prompts/refactoring.md`).
    - **Non-runtime updates (pre-approved manual-only exception)**: a change touching no executable runtime code path may proceed with manual verification — declare it in Step 0 and state why. It covers docs, non-executable config, editor/IDE files, and cosmetic asset swaps with no selector/path change; the mechanically exempt (`*.md`, `.editorconfig`, `.idea/**`, `.vscode/**`, `prompts/**`) are recognized by the command below, and the rest stay the exemption a person declares. A test infeasible for a runtime change needs its reason stated and user approval.
-   - **static の HTML/CSS 例外:** `package.json` に `josh.profile: static` が記録され、変更が HTML/CSS だけなら自動テストの代わりにブラウザーで表示を確認する。対象ページを開き、想定する画面幅でレイアウト・リンク・HTML 内の操作を確認し、観察結果を報告する。HTML/CSS と同時に変更した場合も、JavaScript と TypeScript のファイルには自動テストが必要。`pnpm josh test:declared` はこの場合だけ理由を添えて `exempt` と表示する。
+   - **basic の手動確認例外:** `package.json` に `josh.profile: basic`（改名前の `static` も同じ）が記録され、変更が kit がテストを実行できない言語のファイル（HTML/CSS や Lua などのソース）だけなら、自動テストの代わりに手で確認する。HTML/CSS はブラウザーで対象ページを開き、想定する画面幅でレイアウト・リンク・HTML 内の操作を確認する。そのほかのソースは変更した処理を実際に動かす。どちらも観察結果を報告する。JavaScript と TypeScript のファイルには同時に変更した場合も自動テストが必要。`pnpm josh test:declared` はこの場合だけ理由を添えて `exempt` と表示する。
    - **The commit stage answers this mechanically**: `pnpm josh test:declared` prints `required` / `exempt` / `satisfied` from the changed paths, and a runtime change with no test is refused at `pnpm josh git -y` on `required` — add the declared test or declare the non-runtime exception, then reissue (`prompts/collaboration-workflow/rule-delivery.md`).
    - **Read a target's line headroom before editing: `pnpm josh lines <path>`** — near the limit, `Target` carries the splitting plan.
 
@@ -122,7 +122,7 @@ For every code modification, in order:
 Run the full verification set **in order**; do not skip, reorder, or report completion on a failed or skipped step without the user agreeing. Inside a `fullrun` / `backlogrun` the gate runs beside the review and the merge chain (`workflow-commands` skill → §2, `prompts/review.md`).
 
 0. **Test gate** — no tests added? Continue only under the non-runtime exception (Step 0) or explicit approval; otherwise stop and add tests.
-   static プロファイルの HTML/CSS だけの変更には、Step 0 の手動ブラウザー確認を適用できる。
+   basic プロファイルで kit がテストできない言語のファイルだけの変更には、Step 0 の手動確認を適用できる。
 1. **Refactor** — `prompts/refactoring.md`, until no high/medium items remain.
 2. **`pnpm josh gate`** — lint, type check, spell check and unit tests concurrently. One gate per run; while implementing re-run a single check by name (`pnpm josh lint:related` / `pnpm josh cspell:dot` / `pnpm josh test:related`).
 3. **Self-review** — a subagent runs `/code-review` per `prompts/review.md` (never a main-line `Skill` load); level from the changed paths, at most two rounds, high/medium findings resolved. `prompts/review.md` → "Review round cap".

package/README.md

@@ -1,52 +1,62 @@
 # @joshuafolkken/kit
 
-A development toolkit for AI-assisted work. `josh init` gives an AI assistant (Claude Code, Codex, Gemini, Cursor) the project's rules, formatting and checks in one command. With `kickoff`, `fullrun` and `backlogrun`, the agent then takes a GitHub Issue through plan → implement → verify → PR → merge, the same way in every project. Why kit exists: [why.md](./docs/why.md) (Japanese).
+A development toolkit for AI-assisted work. `josh start` (or `josh init`, for a project that will not use the GitHub Issue workflow) gives an AI assistant (Claude Code, Codex, Gemini, Cursor) the project's rules, formatting and checks in one command. With `kickoff`, `fullrun` and `backlogrun`, the agent then takes a GitHub Issue through plan → implement → verify → PR → merge, the same way in every project. Why kit exists: [why.md](./docs/why.md) (Japanese).
 
 ## What your project gets
 
 kit picks a [profile](./docs/init.md#project-profiles) from one question — does the project use Node tooling?
 
-| Your project                             | Profile  | What you get                                                      |
-| ---------------------------------------- | -------- | ----------------------------------------------------------------- |
-| Node project (JavaScript / TypeScript)   | `node`   | The full set: ESLint, type check, unit and E2E tests, Git hooks   |
-| HTML / CSS (browser JavaScript included) | `static` | Formatting (Prettier), AI assistant files, Git / VS Code settings |
-| Another language (Python, Rust, Go, …)   | `static` | AI assistant files and Git / VS Code settings only                |
+| Your project                             | Profile | What you get                                                      |
+| ---------------------------------------- | ------- | ----------------------------------------------------------------- |
+| Node project (JavaScript / TypeScript)   | `full`  | The full set: ESLint, type check, unit and E2E tests, Git hooks   |
+| HTML / CSS (browser JavaScript included) | `basic` | Formatting (Prettier), AI assistant files, Git / VS Code settings |
+| Another language (Python, Rust, Go, …)   | `basic` | AI assistant files and Git / VS Code settings only                |
 
-In a `static` project, `josh` skips each check that has nothing to run and says why.
+In a `basic` project, `josh` skips each check that has nothing to run and says why.
 
 ## Quick start
 
-Requires [Node.js](https://nodejs.org/) 22.19.0+ and [pnpm](https://pnpm.io/) for every profile ([getting-started.md](./docs/getting-started.md)); the [gh CLI](https://cli.github.com/) for `josh version` and the Issue workflow is required by `josh start` and optional otherwise. Run in your project directory.
+Requires [Node.js](https://nodejs.org/) 22.19.0+ and [pnpm](https://pnpm.io/) 12+ for every profile ([how to install them](./docs/setup/basic.md#1-check-the-prerequisites)); the [gh CLI](https://cli.github.com/) for `josh version` and the Issue workflow is required by `josh start` and optional otherwise. Run in your project directory.
 
-### The project is already on GitHub, or will not use GitHub
+One question picks the command: will the project use the GitHub Issue workflow (`kickoff`, `fullrun`, `backlogrun`)? The [profile](./docs/init.md#project-profiles) is chosen the same way either way.
+
+### The project will use the GitHub Issue workflow
 
 ```bash
-pnpm --allow-build=esbuild dlx @joshuafolkken/kit init
-pnpm josh gate
+pnpm add -D --allow-build=esbuild --allow-build=unrs-resolver @joshuafolkken/kit
+pnpm exec josh start
 ```
 
-### The project has no GitHub repository yet, and will use the Issue workflow
+With or without Git and a GitHub repository: `josh start` creates what is missing, and when `main` already has commits it opens a pull request with only kit's files for you to merge.
+
+### The project will not use the GitHub Issue workflow
 
 ```bash
-pnpm add -D --allow-build=esbuild --allow-build=unrs-resolver @joshuafolkken/kit
-pnpm exec josh start
+pnpm --allow-build=esbuild dlx @joshuafolkken/kit init
+pnpm josh gate
 ```
 
-`josh start` also runs `git init` when needed and creates and pushes the GitHub repository. Details: [init.md → `josh init` or `josh start`](./docs/init.md#josh-init-or-josh-start).
+What each command does in each starting state: [init.md → `josh init` or `josh start`](./docs/init.md#josh-init-or-josh-start).
+
+The step-by-step version of these commands, with what each one creates: [Set up the basic profile](./docs/setup/basic.md) · [Set up the full profile](./docs/setup/full.md).
 
 ## Documentation
 
-**Get started**
+**Set up**
+
+- [setup/basic.md](./docs/setup/basic.md) — a `basic` project, from an empty machine
+- [setup/full.md](./docs/setup/full.md) — a Node project, with `josh init` or `josh start`
+- [cli.md](./docs/cli.md) — the global `josh` command
+- [troubleshooting.md](./docs/troubleshooting.md) — install and auth errors
+
+**Use**
 
-- [getting-started.md](./docs/getting-started.md) — first install for a `static` project
-- [package.md](./docs/package.md) — add kit to a Node project
+- [overview.md](./docs/overview.md) — what kit sets up and how it works
 - [tutorial.md](./docs/tutorial.md) — your first change with an agent, from Issue to merge
 - [how-to.md](./docs/how-to.md) — guides by task
-- [overview.md](./docs/overview.md) — what kit sets up and how it works
 
 **Commands and configuration**
 
-- [cli.md](./docs/cli.md) — the global `josh` command
 - [josh-commands.md](./docs/josh-commands.md) — every `josh` command ([catalog](./docs/josh-command-catalog.md))
 - [init.md](./docs/init.md) — what `josh init` creates
 - [sync.md](./docs/sync.md) — what `josh sync` updates
@@ -58,7 +68,6 @@ pnpm exec josh start
 - [scripts-ai.md](./docs/scripts-ai.md) — Issue workflow commands and Telegram notifications
 - [cloud-session.md](./docs/cloud-session.md) — running in an agent container
 - [eval.md](./docs/eval.md) — measuring rule adherence
-- [troubleshooting.md](./docs/troubleshooting.md) — install and auth errors
 - [authentication.md](./docs/authentication.md) — existing GitHub Packages installs only
 
 ## Contributing