@joshuafolkken/kit 1.1094.0 → 1.1128.0

package/.github/workflows/pr-classification.yml

@@ -31,9 +31,7 @@ jobs:
           persist-credentials: false
 
       - name: Setup Node.js
-        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
-        with:
-          node-version: '24'
+        uses: ./.github/actions/setup-node
 
       - name: Configure GitHub Packages authentication for existing projects
         run: printf '//npm.pkg.github.com/:_authToken=${NODE_AUTH_TOKEN}\n' >> "$HOME/.npmrc"

package/.github/workflows/production.yml

@@ -15,6 +15,7 @@ jobs:
       group: production-update
       queue: max
     runs-on: ubuntu-latest
+    timeout-minutes: 10
     permissions:
       contents: write
     steps:

package/.github/workflows/publish.yml

@@ -25,9 +25,8 @@ jobs:
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
-      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+      - uses: ./.github/actions/setup-node
         with:
-          node-version: 24
           registry-url: 'https://npm.pkg.github.com'
           scope: '@joshuafolkken'
 
@@ -54,9 +53,12 @@ jobs:
         env:
           LATEST: ${{ steps.registry-latest.outputs.latest }}
 
-      - run: pnpm publish --no-git-checks --tag ${{ steps.publish-tag.outputs.tag }} --registry https://npm.pkg.github.com
+      # The tag reaches the command through the environment rather than expanded into it, so a step
+      # output is never parsed as shell (joshuafolkken/kit#3084).
+      - run: pnpm publish --no-git-checks --tag "$PUBLISH_TAG" --registry https://npm.pkg.github.com
         env:
           NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          PUBLISH_TAG: ${{ steps.publish-tag.outputs.tag }}
 
   publish-npm:
     if: startsWith(github.ref, 'refs/tags/v')
@@ -71,9 +73,8 @@ jobs:
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
-      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+      - uses: ./.github/actions/setup-node
         with:
-          node-version: 24
           registry-url: 'https://registry.npmjs.org'
 
       # Before setup-pnpm, for the same reason as publish-github's lookup (joshuafolkken/kit#3060).
@@ -99,7 +100,9 @@ jobs:
           LATEST: ${{ steps.registry-latest.outputs.latest }}
 
       - name: Publish to npm
-        run: cd "$RUNNER_TEMP" && npm publish kit.tgz --access public --tag ${{ steps.publish-tag.outputs.tag }} --registry https://registry.npmjs.org --userconfig /dev/null
+        run: cd "$RUNNER_TEMP" && npm publish kit.tgz --access public --tag "$PUBLISH_TAG" --registry https://registry.npmjs.org --userconfig /dev/null
+        env:
+          PUBLISH_TAG: ${{ steps.publish-tag.outputs.tag }}
 
   update-production:
     needs: [publish-github, publish-npm]
@@ -121,9 +124,7 @@ jobs:
         with:
           fetch-depth: 0
 
-      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
-        with:
-          node-version: 24
+      - uses: ./.github/actions/setup-node
 
       - uses: ./.github/actions/setup-pnpm
         with:

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

@@ -20,6 +20,8 @@ jobs:
       contents: read
       packages: read
     runs-on: ubuntu-latest
+    # The scan waits for SonarCloud's Quality Gate, so the limit leaves room for that wait.
+    timeout-minutes: 20
     # 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.
@@ -35,6 +37,21 @@ jobs:
         if: env.SONAR_TOKEN != ''
         with:
           fetch-depth: 0 # Shallow clones should be disabled for a better relevancy of analysis
+      # The dependencies are installed before the scan, on a push as well as on a pull request:
+      # `tsconfig.sonar.json` extends `@joshuafolkken/kit/tsconfig/base`, which a consumer resolves
+      # only from node_modules, so a scan ahead of the install read a config it could not load
+      # (joshuafolkken/kit#3082). The new-code check below runs `pnpm josh` from the same install.
+      - name: Setup Node.js
+        if: env.SONAR_TOKEN != ''
+        uses: ./.github/actions/setup-node
+      - name: Configure GitHub Packages authentication for existing projects
+        if: env.SONAR_TOKEN != ''
+        run: printf '//npm.pkg.github.com/:_authToken=${NODE_AUTH_TOKEN}\n' >> "$HOME/.npmrc"
+      - name: Setup pnpm and install dependencies
+        if: env.SONAR_TOKEN != ''
+        uses: ./.github/actions/setup-pnpm
+        with:
+          node-auth-token: ${{ secrets.GITHUB_TOKEN }}
       # SonarCloud's New Code starts at the previous version, so an analysis without
       # `sonar.projectVersion` never moves that start and New Code grows without end, diluting every
       # ratio the Quality Gate judges (joshuafolkken/kit#3045). The version is `package.json`'s, so
@@ -57,19 +74,6 @@ jobs:
       # job (a required PR check) when the pull request adds any new issue, of any type or severity,
       # or any new duplicated block (joshuafolkken/kit#3045). An issue resolved in SonarCloud as
       # accepted or a false positive is not counted. A push to main has no pull request to read.
-      - name: Setup Node.js
-        if: env.SONAR_TOKEN != '' && github.event_name == 'pull_request'
-        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
-        with:
-          node-version: '24'
-      - name: Configure GitHub Packages authentication for existing projects
-        if: env.SONAR_TOKEN != '' && github.event_name == 'pull_request'
-        run: printf '//npm.pkg.github.com/:_authToken=${NODE_AUTH_TOKEN}\n' >> "$HOME/.npmrc"
-      - name: Setup pnpm and install dependencies
-        if: env.SONAR_TOKEN != '' && github.event_name == 'pull_request'
-        uses: ./.github/actions/setup-pnpm
-        with:
-          node-auth-token: ${{ secrets.GITHUB_TOKEN }}
       - name: Fail on new Sonar issues or duplicated blocks
         if: env.SONAR_TOKEN != '' && github.event_name == 'pull_request'
         env:

package/.pnpmfile.mjs

@@ -0,0 +1,29 @@
+// josh-managed-pnpmfile: @joshuafolkken/kit
+// `josh init` / `josh sync` copy this file into every project that publishes (joshuafolkken/kit#3110)
+// and overwrite it while this first line stays; edit it in kit, not here.
+// Strips the Safe Chain `preinstall` from the packed manifest only (joshuafolkken/kit#2693).
+// kit writes it to run Safe Chain for the repository's own development installs; shipped, it becomes
+// a build script every consumer's pnpm refuses to run unapproved, and it could not protect them
+// anyway — their install has already started by the time a dependency's `preinstall` runs. The
+// repository's package.json keeps it; `pnpm pack` and `pnpm publish` call this hook on the copy they
+// write. Any other lifecycle script — a native build, a binary download — is the package's own and
+// ships untouched.
+const SAFE_CHAIN_PACKAGE = '@aikidosec/safe-chain'
+
+function is_safe_chain_preinstall(name, command) {
+	return name === 'preinstall' && command.includes(SAFE_CHAIN_PACKAGE)
+}
+
+function strip_safe_chain_preinstall(manifest) {
+	const scripts = Object.fromEntries(
+		Object.entries(manifest.scripts ?? {}).filter(
+			([name, command]) => !is_safe_chain_preinstall(name, command),
+		),
+	)
+
+	return { ...manifest, scripts }
+}
+
+const hooks = { beforePacking: strip_safe_chain_preinstall }
+
+export { hooks, is_safe_chain_preinstall }

package/AGENTS.md

@@ -1,18 +1,11 @@
 # Agent Instructions
 
 > **All rules for this repository live in [`CLAUDE.md`](./CLAUDE.md). Read it in full before doing
-> any work here, and follow every rule in it.** This file exists only to point at it. The rules apply
-> to whatever agent is doing the work, but `CLAUDE.md` is written for Claude Code and names its
-> features — read them as follows.
+> any work here, and follow every rule in it.** This file exists only to point at it.
 
-- **Hooks.** Codex runs the same hooks from `.codex/hooks.json`, which is generated from
-  `.claude/settings.json`. Where Codex does not show a hook's output, apply the rule yourself — resolve
-  `JOSH_SESSION_LANG` from `.env` rather than waiting for it to be injected.
-- **Skills, `/verify-ui` and `/code-review`.** Where `CLAUDE.md` says to load a skill or run one in a
-  subagent, read that skill's `SKILL.md` and follow it in your own session.
-- **The `.claude/settings.json` deny list** is not enforced here. The rules it backs — no commits,
-  merges, staging or other shared-state changes without instruction — still bind you.
-- **`AskUserQuestion`** means asking the user in plain text.
+**Codex runs the same hooks from `.codex/hooks.json`**, generated from `.claude/settings.json`; where
+it does not show a hook's output, apply that rule yourself. How to read `CLAUDE.md`'s Claude Code
+features here is `prompts/collaboration-workflow/principles.md` → "Claude Code 以外のエージェントでの読み替え".
 
 **Do not copy rules back into this file.** Every change to how agents work in this repository belongs
 in `CLAUDE.md`.

package/CLAUDE.md

@@ -36,7 +36,7 @@ Classify each decision point into one tier and act; stop **only** when the choic
 
 ## Environment Variables
 
-A `.env` at the project root: `TELEGRAM_BOT_TOKEN` and `TELEGRAM_CHAT_ID` are required for notifications; `JOSH_SESSION_LANG`, `PORT_SEED` and `JOSH_REPO_PATHS` are optional and personal. Setup and semantics: [docs/scripts-ai.md](https://github.com/joshuafolkken/kit/blob/main/docs/scripts-ai.md) and [docs/josh-commands.md](https://github.com/joshuafolkken/kit/blob/main/docs/josh-commands.md).
+A `.env` at the project root: `TELEGRAM_BOT_TOKEN` and `TELEGRAM_CHAT_ID` are required for notifications; `JOSH_SESSION_LANG`, `PORT_SEED` and `JOSH_REPO_PATHS` are optional and personal. Details: [environment-variables.md](https://github.com/joshuafolkken/kit/blob/main/docs/environment-variables.md), [josh-commands.md](https://github.com/joshuafolkken/kit/blob/main/docs/josh-commands.md).
 
 **GitHub operations are `gh api` (REST) — instructing prose included — and need `gh` installed; some environments lack it.** Auth: `gh auth login`; `GH_TOKEN` in CI/cloud. `prompts/collaboration-workflow/gh-rest.md`.
 
@@ -100,12 +100,14 @@ A `.env` at the project root: `TELEGRAM_BOT_TOKEN` and `TELEGRAM_CHAT_ID` are re
 
 For every code modification, in order:
 
-0. **Work summary + test declaration** _(before writing any implementation code)_: a two-layer summary — a plain-language overview a non-programmer can follow (three lines, **Now / Change / Check**, one sentence each, in the session language; name the concrete subject in each line — subject-less prose is not acceptable; no file paths, function or type names, or CLI option flags — only internal identifiers are banned, not names the reader sees on screen), **Details**, then **every change with its test** (`<what changes> — Test: <Unit|E2E> — <file path> — <what it verifies>`). Ordinary markdown, **never wrapped in a code fence**, once per Issue before implementation — required in fullrun/halfrun/backlogrun even when the Issue body was filled (`kickoff` is exempt); completion reports lead with **Cause / Fix / Result**. `prompts/collaboration-workflow/report-format.md`; `pnpm josh report:lint` checks the form, and a session's first runtime `Edit` / `Write` points here. Presentation only, never a confirmation stop.
+0. **Work summary + test declaration** _(before writing any implementation code)_: once per Issue, present a two-layer summary in ordinary markdown, **never wrapped in a code fence** — required in fullrun/halfrun/backlogrun even when the Issue body was filled (`kickoff` is exempt). Presentation only, never a confirmation stop. `prompts/collaboration-workflow/report-format.md`; `pnpm josh report:lint` checks the form.
 
+   - **Overview** — three lines, **Now / Change / Check**, one sentence each, in the session language, that a non-programmer can follow; name the concrete subject in each line — subject-less prose is not acceptable. Use no file paths, function or type names, or CLI option flags — only internal identifiers are banned, not names the reader sees on screen.
+   - **Details**, then **every change with its test**: `<what changes> — Test: <Unit|E2E> — <file path> — <what it verifies>`. Completion reports lead with **Cause / Fix / Result**.
    - **Tests are required for ALL changes** — zero tests without explicit approval is a violation (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.
-   - **Basic-profile manual-check exception:** when `package.json` records `josh.profile: basic` (or its former name `static`) and the change touches only files in languages kit cannot test (HTML/CSS, or sources such as Lua), verify by hand instead of with an automated test. For HTML/CSS, open the page in a browser and check layout, links and interactions in the HTML at the intended screen widths; for any other source, actually run the changed code. Report what you observed either way. JavaScript and TypeScript files still need automated tests, even when changed alongside. `pnpm josh test:declared` prints `exempt` with the reason in this case only.
-   - **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`).
+   - **Non-runtime updates (pre-approved manual-only exception)**: a change touching no executable runtime code path — docs, non-executable config, editor/IDE files, cosmetic asset swaps with no selector/path change — may be verified by hand; declare it in Step 0 with the reason. The mechanically exempt (`*.md`, `.editorconfig`, `.idea/**`, `.vscode/**`, `prompts/**`) need no declaration. A runtime change whose test is infeasible needs the reason and user approval.
+   - **Basic-profile manual-check exception:** under `josh.profile: basic` (or `static`), a change touching only languages kit cannot test (HTML/CSS, Lua …) is verified by hand — a browser check of layout, links and interactions in the HTML, or actually run the changed code — and reported; JavaScript and TypeScript still need tests. `prompts/testing-guide.md`.
+   - **`pnpm josh test:declared`** answers `required` / `exempt` / `satisfied` from the changed paths; a runtime change with no test is refused at `pnpm josh git -y` on `required`.
    - **Read a target's line headroom before editing: `pnpm josh lines <path>`** — near the limit, `Target` carries the splitting plan.
 
 1. **Refactor first** — before any refactoring, read and follow `prompts/refactoring.md`; apply high/medium refactoring to all new/modified code and do not proceed until none remain.
@@ -129,7 +131,11 @@ Run the full verification set **in order**; do not skip, reorder, or report comp
 
 ## Pre-commit Self-Review (mandatory)
 
-Before every `git commit` (follow-up commits included), self-review against `prompts/review.md` — a subagent runs `/code-review`, never a main-line `Skill` load: the staged diff, and `git diff main...HEAD` before opening or updating a PR. Level from `pnpm josh review:brief --level-only`; resolve all high/medium findings; iterate — **no further than the round cap**, the last round a verification pass over the fix delta. Then route each remaining non-High finding through the three-way disposition: fix in place, file it as a follow-up Issue only when it is a confirmed defect that reaches a runtime path (`pnpm josh disposition <path>` answers `runtime` / `non-runtime`) — or drop it with a one-line PR note (the default). **A filed finding is run through `pnpm josh epic:bundle <new>` before the current Issue closes.** A confirmed High blocks rather than buying a round past the cap. `prompts/review.md` → "Review round cap".
+Before every `git commit` (follow-up commits included), self-review against `prompts/review.md` — a subagent runs `/code-review`, never a main-line `Skill` load. `prompts/review.md` → "Review round cap".
+
+- **Scope** — the staged diff, and `git diff main...HEAD` before opening or updating a PR; level from `pnpm josh review:brief --level-only`.
+- **Rounds** — resolve all high/medium findings, **no further than the round cap**, the last round a verification pass over the fix delta. A confirmed High blocks rather than buying a round past the cap.
+- **Each remaining non-High finding** — fix in place, file it as a follow-up Issue only when it is a confirmed defect that reaches a runtime path (`pnpm josh disposition <path>`), or drop it with a one-line PR note (the default). **A filed finding is run through `pnpm josh epic:bundle <new>` before the current Issue closes.**
 
 ## Doc Sync Rules
 
@@ -137,14 +143,14 @@ Before every `git commit` (follow-up commits included), self-review against `pro
 
 ## Git Rules
 
-- **No commits** unless explicitly requested. **No PR merges, branch deletions, force pushes or other shared-state mutations** unless explicitly requested in the current turn — the default end state is PR still OPEN. **Exception**: invoking `fullrun` authorizes the merge, via `pnpm josh followup`. `.claude/settings.json` denies these, but the deny is narrower than the rule — never read "the tool let me" as permission. `prompts/collaboration-workflow/operating-rules.md` → "指示されていない行動は取らない".
+- **No commits** unless explicitly requested. **No PR merges, branch deletions, force pushes or other shared-state mutations** unless explicitly requested in the current turn — the default end state is PR still OPEN. **Exception**: invoking `fullrun` or `backlogrun` authorizes the merge, via `pnpm josh followup` — `prrun` does not. `.claude/settings.json` denies these, but the deny is narrower than the rule — never read "the tool let me" as permission. `prompts/collaboration-workflow/operating-rules.md` → "指示されていない行動は取らない".
 - **Never stage or mutate the git index on your own.** `git add` / `git rm --cached` / `git restore --staged` / `git commit` overwrite the user's snapshot and are denied by settings; inspection is read-only. Staging is allowed only on an explicit current-turn instruction or an authorized commit flow (`pnpm josh git`). `prompts/collaboration-workflow/operating-rules.md` → "git index を勝手に変更しない".
 - **For git operations use `pnpm josh git`.** After a failed push, fix, push manually, then `pnpm josh pr` — **never** `gh pr create` directly, which bypasses `closes #N` generation so the Issue will not auto-close.
 - **Start-of-conversation git status is a stale snapshot.** Before acting on any working-tree / index / stash / branch assumption, run `git status` (and `git stash list`) live first.
 
 ## Collaboration Workflow
 
-- For the issue-driven proposal/plan/execution/notification flow, follow `prompts/collaboration-workflow/` (indexed by `prompts/collaboration-workflow.md`; each topic is its own file).
+- The issue-driven flow is `prompts/collaboration-workflow/`, indexed by `prompts/collaboration-workflow.md`.
 - **Before writing a rule as prose, place it by `prompts/collaboration-workflow/residency.md`** — its single source. A computable answer goes to `pnpm josh oracle:list` and an ordering rule to `pnpm josh run:step`, never into `CLAUDE.md` or a prompt file.
 - **Count the target repository's open Issues before filing; above the WIP cap, close one first.** Nothing honestly closable means do not file. A filing the run is blocked by is exempt, and so is an **interrupt** — three tests decide that, never judgement: a verification answers wrongly, a documented workflow cannot complete, or data is lost or written outside the repository; both exemptions proceed, stating the overage. Meeting none of the three, a finding stays discretionary. `pnpm josh rule:guard` states it again at the call that files. The count command and both procedures: `prompts/collaboration-workflow/wip-cap.md`.
 
@@ -162,11 +168,13 @@ Before every `git commit` (follow-up commits included), self-review against `pro
 | `halfrun [#N \| new]`    | Implement + gate, then **stop before commit** for manual verification                                                                                                 | + `halfrun.md` + `split-assessment.md`                           |
 | `backlogrun [#N1 #N2 …]` | Run named Issues and epics in order (an epic runs its children first), then drain the opted-in backlog — dependency order, lanes. `--only` stops after the named list | + `backlogrun.md` + `split-assessment.md` + the `fullrun` set    |
 
-**`queue` and `epicrun` were removed** — tell a user who types `queue` to run `backlogrun #N1 #N2 …`, and one who types `epicrun` to run `backlogrun #E --only` (drop `--only` to also drain the backlog).
+**`queue` and `epicrun` were removed** — point `queue` to `backlogrun #N1 #N2 …` and `epicrun` to `backlogrun #E --only`.
 
-**Three rules decide what a run does when the work turns out not to be one Issue** — the split assessment every entry point applies identically (**its default is not to split**: separability **and** a scope clearly exceeding one verification gate — the size guide in `split-assessment.md`, measured by `pnpm josh split:assess` — must both hold), a prerequisite discovered mid-run (a dependency, not parked), and a named `backlogrun` item that is not an epic. All bind only after a command has started, so all are read from the `workflow-commands` skill: `split-assessment.md`, `SKILL.md` → §2d, `backlogrun-child.md` → "When `#N` is not an epic", and `fullrun.md` / `halfrun.md` / `backlogrun.md` for the branch each entry takes.
+**The `josh epic:*` commands have their own skill** — `epic:audit`, `epic:next`, `epic:bundle`, and how an epic spans repositories. **Read the `epic-commands` skill before running any of them, before writing an epic that tracks a child in another repository, and right after filing an issue.** Three rules bind outside those commands:
 
-**The `josh epic:*` commands have their own skill** — `epic:audit`, `epic:next`, `epic:bundle`, and how an epic spans repositories. **Read the `epic-commands` skill before running any of them, before writing an epic that tracks a child in another repository, and right after filing an issue.** Three rules stay here because they bind outside those commands: **recording a decision removes that child's `needs-decision` label** (Tier A); **fixing what the audit finds is Tier A**, park only when the contradiction is a design choice nobody has made; and **an epic in another repository is referenced as `owner/repo#N`** (a bare `#N` resolves to this repository's issue). Canonical reference: `.claude/skills/epic-commands/SKILL.md`.
+- Recording a decision removes that child's `needs-decision` label (Tier A).
+- **Fixing what the audit finds is Tier A**; park only when the contradiction is a design choice nobody has made.
+- **An epic in another repository is referenced as `owner/repo#N`** — a bare `#N` resolves to this repository's issue.
 
 #### Explicit invocation required (MANDATORY)
 
@@ -177,18 +185,17 @@ Never start a `kickoff` / `halfrun` / `prrun` / `fullrun` / `backlogrun` workflo
 - Instead, **prompt the user to type the command themselves**, with the exact phrasing: "Please run \`<command>\` to start this task." (e.g. "Please run \`halfrun new\` to start this task.").
 - This applies even when the user authorized a related workflow in an earlier turn — each invocation must be re-typed in the current turn.
 
-**A session cut inside a declared budget is not a new invocation** — a `backlogrun` cut and resumed is the one invocation a person typed, and it continues rather than waiting to be retyped; **`backlogrun` alone**, though — a `fullrun` cut still waits for the keyword. Single source: `backlogrun-steps.md` → "The session cut is inside the invocation".
+**A session cut inside a declared budget is not a new invocation — for `backlogrun` alone**: a resumed `backlogrun` continues, while a `fullrun` cut still waits for the keyword. `backlogrun-steps.md` → "The session cut is inside the invocation".
 
-**A `backlogrun` parks a child instead of stopping the run**, and its procedure is read from `backlogrun-park.md` → "park and continue", which is that rule's single source.
+**A `backlogrun` parks a child instead of stopping the run** — `backlogrun-park.md` → "park and continue".
 
 #### Mid-workflow stop notification (`confirmation`)
 
-Whenever you pause **any** run mid-execution to wait for the user — a `kickoff` / `halfrun` / `prrun` / `fullrun` stop, an upstream-Issue interrupt, a Tier C confirmation — you MUST send a Telegram notification **before** stopping, so the user is alerted off-screen. `halfrun`'s built-in stop before commit is a confirmation pause and follows this same rule.
+Before pausing **any** run to wait for the user — a command's stop (`halfrun`'s stop before commit included), an upstream-Issue interrupt, a Tier C confirmation — you MUST send this Telegram, so the user is alerted off-screen:
 
 ```bash
 pnpm josh notify --task-type confirmation --issue-url "<issue-url>" --body=$'<one-line reason>\n<what is needed from the user>'
 ```
 
-- Use `--body=...` (single token) when the body starts with `-`, otherwise `parseArgs` rejects it
-- Send only once per stop — do not spam if you re-evaluate within the same pause
-- Skip the notification when the stop was explicitly requested by the user in the same turn (they already know)
+- Send it once per stop; skip it when the user asked for the stop in this same turn.
+- Pass `--body=...` as one token when the body starts with `-`, otherwise `parseArgs` rejects it.

package/GEMINI.md

@@ -1,22 +1,13 @@
 # Agent Instructions
 
 > **All rules for this repository live in [`CLAUDE.md`](./CLAUDE.md). Read it in full before doing
-> any work here, and follow every rule in it.** This file exists only to point at it. The rules apply
-> to whatever agent is doing the work, but `CLAUDE.md` is written for Claude Code and names its
-> features — read them as follows.
+> any work here, and follow every rule in it.** This file exists only to point at it.
 
 @CLAUDE.md
 
-- **No hooks run under Gemini.** Every rule `CLAUDE.md` says a hook enforces or delivers is silently
-  unenforced here, so apply each one yourself: present the work summary before implementing, resolve
-  `JOSH_SESSION_LANG` from `.env`, run `pnpm josh lint:related` and `pnpm josh cspell:dot` after
-  editing instead of relying on the format-on-edit hook, and cite every Issue with a link and a short
-  title instead of relying on the stop-time check.
-- **Skills, `/verify-ui` and `/code-review`.** Where `CLAUDE.md` says to load a skill or run one in a
-  subagent, read that skill's `SKILL.md` and follow it in your own session.
-- **The `.claude/settings.json` deny list** is not enforced here. The rules it backs — no commits,
-  merges, staging or other shared-state changes without instruction — still bind you.
-- **`AskUserQuestion`** means asking the user in plain text.
+**No hooks run under Gemini**, so every rule a hook delivers is yours to apply unaided. How to read
+`CLAUDE.md`'s Claude Code features here — that list of rules included — is
+`prompts/collaboration-workflow/principles.md` → "Claude Code 以外のエージェントでの読み替え".
 
 **Do not copy rules back into this file.** Every change to how agents work in this repository belongs
 in `CLAUDE.md`.

package/README.md

@@ -12,7 +12,7 @@
 [![CI](https://github.com/joshuafolkken/kit/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/joshuafolkken/kit/actions/workflows/ci.yml)
 [![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=joshuafolkken_kit&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=joshuafolkken_kit)
 
-**Write a GitHub Issue. Your AI agent takes it to a merged PR — the same way in every project.**
+**Tell your AI agent the change. It files the GitHub Issue and takes it to a merged PR — the same way in every project.**
 
 kit gives Claude Code or Codex (or Gemini, Cursor) your project's rules, checks and an Issue-driven workflow.
 
@@ -54,6 +54,7 @@ Each kit includes the one to its left: app-kit builds on kit, game-kit builds on
 | ------------ | ------------------------------------------------ |
 | `kickoff`    | Writes the plan on the Issue, then stops         |
 | `halfrun`    | Implements and self-reviews, stops before commit |
+| `prrun`      | Opens a green pull request, stops before merge   |
 | `fullrun`    | Plans if needed, implements through to merge     |
 | `backlogrun` | Runs many Issues unattended                      |
 
@@ -66,13 +67,17 @@ Each keyword in full: [Run Issues with the workflow keywords](./docs/how-to/run-
 
 ## Quick start
 
-Requires Node.js, pnpm and the gh CLI — [how to install them](./docs/setup/prerequisites.md).
+Requires Node.js, pnpm (kit is installed and run with pnpm only) and the gh CLI — [how to install them](./docs/setup/prerequisites.md). Sign in once with `gh auth login` before `josh start`.
 
 ```bash
 pnpm add -D --allow-build=esbuild --allow-build=unrs-resolver @joshuafolkken/kit
 pnpm exec josh start
 ```
 
+`josh start` picks the project's profile, writes kit's rules and checks, and creates the GitHub repository and workflow labels when they are missing. On a repository that already has history it opens a setup pull request instead of committing to `main` — merge it before your first run ([what it does](./docs/init.md#josh-init-or-josh-start)).
+
+Add the two Telegram credentials to `.env` so a run that needs you can reach you, or `JOSH_NOTIFY=off` to go without — [Set up notifications](./docs/how-to/set-up-notifications.md).
+
 Then open your agent and follow the [tutorial](./docs/tutorial.md).
 
 No Issue workflow? [Node projects](./docs/setup/full.md#2-install-and-initialize-with-josh-init) · [Other projects](./docs/setup/basic.md)
@@ -81,4 +86,4 @@ No Issue workflow? [Node projects](./docs/setup/full.md#2-install-and-initialize
 
 [Tutorial](./docs/tutorial.md) · [How-to](./docs/how-to.md) · [Commands](./docs/josh-commands.md) · [Troubleshooting](./docs/troubleshooting.md) · [All docs](./docs/overview.md)
 
-[Releases](https://github.com/joshuafolkken/kit/releases) · [Security](./SECURITY.md) · [Contributing](./CLAUDE.md) · [Maintaining kit](./docs/maintainers/README.md) · [MIT](./LICENSE)
+[Releases](https://github.com/joshuafolkken/kit/releases) · [Security](./SECURITY.md) · [Contributing](./docs/maintainers/README.md) · [MIT](./LICENSE)

package/SECURITY.md

@@ -30,6 +30,7 @@ The `files` field of `package.json` decides what the published `@joshuafolkken/k
 - `.github/` — GitHub Actions workflows (CI, tagging, pull request classification, Dependabot auto-merge, SonarQube and production), composite actions, `dependabot.yml`, the pull request template and the release-notes config. `josh sync` overwrites the distributed workflows; their action references are pinned to commit SHAs. kit's own `publish.yml` ships in the package but is never copied into a project.
 - `lefthook/` — Git hook presets: lint before commit, checks before push.
 - The `preinstall` script `josh init` adds to `package.json` runs `pnpm dlx @aikidosec/safe-chain setup-ci` on every install, then a `node -e` check that only prints a warning, and only outside CI. The `prepare` script it adds runs `lefthook install` when Lefthook is present, then, when tsx is present, kit's `fix-gh-packages` script: only when the project `.npmrc` routes a scope to GitHub Packages, it reads a GitHub token (`NODE_AUTH_TOKEN`, a token in the project `.npmrc`, or `gh auth token`), queries GitHub Packages and rewrites tarball URLs in `pnpm-lock.yaml`.
+- `.pnpmfile.mjs` — a pnpm `beforePacking` hook that removes that safe-chain `preinstall` from the manifest `pnpm pack` and `pnpm publish` write, and changes nothing else. `josh init` and `josh sync` copy it only into a project whose `package.json` is not `private: true`, and never over a pnpmfile of the project's own.
 
 **Agent instructions and skills**
 

package/cspell/index.yaml

@@ -41,6 +41,10 @@ ignorePaths:
   #   - '**/*.min.js'
   #   - '**/*.svg'
 words:
+  # pnpm's `.pnpmfile.mjs` hook file that strips the safe-chain preinstall at pack time
+  # (joshuafolkken/kit#2693). Distributed, because `josh init` / `josh sync` copy that file, which
+  # names itself, into a published consumer (joshuafolkken/kit#3110).
+  - pnpmfile
   # Git's `--show-toplevel` flag is added to every Codex hook command when `josh sync` copies the
   # hooks into a consumer. The consumer spell-checks that transformed file with this dictionary.
   - toplevel

package/dist/CLAUDE.basic.md

@@ -1,8 +1,8 @@
 # Project instructions
 
-- 既存のファイルと利用者の設定を尊重し、変更する前に内容を確認する。
-- 変更には検証を付け、実行した結果を報告する。
-- HTML、CSS、JavaScript のファイルがある場合は Prettier で整形する。
-- 画面に見える変更をした場合はブラウザーで表示と操作を確認する。
-- JavaScript または TypeScript の動作を変更した場合は、その動作を確認する自動テストを追加する。
-- Git や GitHub を使う場合だけ、それぞれのワークフローを利用する。
+- Respect existing files and the user's settings, and read a file's contents before changing it.
+- Verify every change, and report the results you actually observed.
+- Format HTML, CSS and JavaScript files with Prettier when the project has any.
+- After a change that is visible on screen, check its display and interaction in a browser.
+- After changing JavaScript or TypeScript behavior, add an automated test that checks that behavior.
+- Use the Git or GitHub workflow only when you use Git or GitHub.

package/dist/CLAUDE.md

@@ -36,7 +36,7 @@ Classify each decision point into one tier and act; stop **only** when the choic
 
 ## Environment Variables
 
-A `.env` at the project root: `TELEGRAM_BOT_TOKEN` and `TELEGRAM_CHAT_ID` are required for notifications; `JOSH_SESSION_LANG`, `PORT_SEED` and `JOSH_REPO_PATHS` are optional and personal. Setup and semantics: [docs/scripts-ai.md](https://github.com/joshuafolkken/kit/blob/main/docs/scripts-ai.md) and [docs/josh-commands.md](https://github.com/joshuafolkken/kit/blob/main/docs/josh-commands.md).
+A `.env` at the project root: `TELEGRAM_BOT_TOKEN` and `TELEGRAM_CHAT_ID` are required for notifications; `JOSH_SESSION_LANG`, `PORT_SEED` and `JOSH_REPO_PATHS` are optional and personal. Details: [environment-variables.md](https://github.com/joshuafolkken/kit/blob/main/docs/environment-variables.md), [josh-commands.md](https://github.com/joshuafolkken/kit/blob/main/docs/josh-commands.md).
 
 **GitHub operations are `gh api` (REST) — instructing prose included — and need `gh` installed; some environments lack it.** Auth: `gh auth login`; `GH_TOKEN` in CI/cloud. `node_modules/@joshuafolkken/kit/prompts/collaboration-workflow/gh-rest.md`.
 
@@ -100,12 +100,14 @@ A `.env` at the project root: `TELEGRAM_BOT_TOKEN` and `TELEGRAM_CHAT_ID` are re
 
 For every code modification, in order:
 
-0. **Work summary + test declaration** _(before writing any implementation code)_: a two-layer summary — a plain-language overview a non-programmer can follow (three lines, **Now / Change / Check**, one sentence each, in the session language; name the concrete subject in each line — subject-less prose is not acceptable; no file paths, function or type names, or CLI option flags — only internal identifiers are banned, not names the reader sees on screen), **Details**, then **every change with its test** (`<what changes> — Test: <Unit|E2E> — <file path> — <what it verifies>`). Ordinary markdown, **never wrapped in a code fence**, once per Issue before implementation — required in fullrun/halfrun/backlogrun even when the Issue body was filled (`kickoff` is exempt); completion reports lead with **Cause / Fix / Result**. `node_modules/@joshuafolkken/kit/prompts/collaboration-workflow/report-format.md`; `pnpm josh report:lint` checks the form, and a session's first runtime `Edit` / `Write` points here. Presentation only, never a confirmation stop.
+0. **Work summary + test declaration** _(before writing any implementation code)_: once per Issue, present a two-layer summary in ordinary markdown, **never wrapped in a code fence** — required in fullrun/halfrun/backlogrun even when the Issue body was filled (`kickoff` is exempt). Presentation only, never a confirmation stop. `node_modules/@joshuafolkken/kit/prompts/collaboration-workflow/report-format.md`; `pnpm josh report:lint` checks the form.
 
+   - **Overview** — three lines, **Now / Change / Check**, one sentence each, in the session language, that a non-programmer can follow; name the concrete subject in each line — subject-less prose is not acceptable. Use no file paths, function or type names, or CLI option flags — only internal identifiers are banned, not names the reader sees on screen.
+   - **Details**, then **every change with its test**: `<what changes> — Test: <Unit|E2E> — <file path> — <what it verifies>`. Completion reports lead with **Cause / Fix / Result**.
    - **Tests are required for ALL changes** — zero tests without explicit approval is a violation (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 (`node_modules/@joshuafolkken/kit/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.
-   - **Basic-profile manual-check exception:** when `package.json` records `josh.profile: basic` (or its former name `static`) and the change touches only files in languages kit cannot test (HTML/CSS, or sources such as Lua), verify by hand instead of with an automated test. For HTML/CSS, open the page in a browser and check layout, links and interactions in the HTML at the intended screen widths; for any other source, actually run the changed code. Report what you observed either way. JavaScript and TypeScript files still need automated tests, even when changed alongside. `pnpm josh test:declared` prints `exempt` with the reason in this case only.
-   - **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 (`node_modules/@joshuafolkken/kit/prompts/collaboration-workflow/rule-delivery.md`).
+   - **Non-runtime updates (pre-approved manual-only exception)**: a change touching no executable runtime code path — docs, non-executable config, editor/IDE files, cosmetic asset swaps with no selector/path change — may be verified by hand; declare it in Step 0 with the reason. The mechanically exempt (`*.md`, `.editorconfig`, `.idea/**`, `.vscode/**`, `prompts/**`) need no declaration. A runtime change whose test is infeasible needs the reason and user approval.
+   - **Basic-profile manual-check exception:** under `josh.profile: basic` (or `static`), a change touching only languages kit cannot test (HTML/CSS, Lua …) is verified by hand — a browser check of layout, links and interactions in the HTML, or actually run the changed code — and reported; JavaScript and TypeScript still need tests. `node_modules/@joshuafolkken/kit/prompts/testing-guide.md`.
+   - **`pnpm josh test:declared`** answers `required` / `exempt` / `satisfied` from the changed paths; a runtime change with no test is refused at `pnpm josh git -y` on `required`.
    - **Read a target's line headroom before editing: `pnpm josh lines <path>`** — near the limit, `Target` carries the splitting plan.
 
 1. **Refactor first** — before any refactoring, read and follow `node_modules/@joshuafolkken/kit/prompts/refactoring.md`; apply high/medium refactoring to all new/modified code and do not proceed until none remain.
@@ -129,7 +131,11 @@ Run the full verification set **in order**; do not skip, reorder, or report comp
 
 ## Pre-commit Self-Review (mandatory)
 
-Before every `git commit` (follow-up commits included), self-review against `node_modules/@joshuafolkken/kit/prompts/review.md` — a subagent runs `/code-review`, never a main-line `Skill` load: the staged diff, and `git diff main...HEAD` before opening or updating a PR. Level from `pnpm josh review:brief --level-only`; resolve all high/medium findings; iterate — **no further than the round cap**, the last round a verification pass over the fix delta. Then route each remaining non-High finding through the three-way disposition: fix in place, file it as a follow-up Issue only when it is a confirmed defect that reaches a runtime path (`pnpm josh disposition <path>` answers `runtime` / `non-runtime`) — or drop it with a one-line PR note (the default). **A filed finding is run through `pnpm josh epic:bundle <new>` before the current Issue closes.** A confirmed High blocks rather than buying a round past the cap. `node_modules/@joshuafolkken/kit/prompts/review.md` → "Review round cap".
+Before every `git commit` (follow-up commits included), self-review against `node_modules/@joshuafolkken/kit/prompts/review.md` — a subagent runs `/code-review`, never a main-line `Skill` load. `node_modules/@joshuafolkken/kit/prompts/review.md` → "Review round cap".
+
+- **Scope** — the staged diff, and `git diff main...HEAD` before opening or updating a PR; level from `pnpm josh review:brief --level-only`.
+- **Rounds** — resolve all high/medium findings, **no further than the round cap**, the last round a verification pass over the fix delta. A confirmed High blocks rather than buying a round past the cap.
+- **Each remaining non-High finding** — fix in place, file it as a follow-up Issue only when it is a confirmed defect that reaches a runtime path (`pnpm josh disposition <path>`), or drop it with a one-line PR note (the default). **A filed finding is run through `pnpm josh epic:bundle <new>` before the current Issue closes.**
 
 ## Doc Sync Rules
 
@@ -137,14 +143,14 @@ Before every `git commit` (follow-up commits included), self-review against `nod
 
 ## Git Rules
 
-- **No commits** unless explicitly requested. **No PR merges, branch deletions, force pushes or other shared-state mutations** unless explicitly requested in the current turn — the default end state is PR still OPEN. **Exception**: invoking `fullrun` authorizes the merge, via `pnpm josh followup`. `.claude/settings.json` denies these, but the deny is narrower than the rule — never read "the tool let me" as permission. `node_modules/@joshuafolkken/kit/prompts/collaboration-workflow/operating-rules.md` → "指示されていない行動は取らない".
+- **No commits** unless explicitly requested. **No PR merges, branch deletions, force pushes or other shared-state mutations** unless explicitly requested in the current turn — the default end state is PR still OPEN. **Exception**: invoking `fullrun` or `backlogrun` authorizes the merge, via `pnpm josh followup` — `prrun` does not. `.claude/settings.json` denies these, but the deny is narrower than the rule — never read "the tool let me" as permission. `node_modules/@joshuafolkken/kit/prompts/collaboration-workflow/operating-rules.md` → "指示されていない行動は取らない".
 - **Never stage or mutate the git index on your own.** `git add` / `git rm --cached` / `git restore --staged` / `git commit` overwrite the user's snapshot and are denied by settings; inspection is read-only. Staging is allowed only on an explicit current-turn instruction or an authorized commit flow (`pnpm josh git`). `node_modules/@joshuafolkken/kit/prompts/collaboration-workflow/operating-rules.md` → "git index を勝手に変更しない".
 - **For git operations use `pnpm josh git`.** After a failed push, fix, push manually, then `pnpm josh pr` — **never** `gh pr create` directly, which bypasses `closes #N` generation so the Issue will not auto-close.
 - **Start-of-conversation git status is a stale snapshot.** Before acting on any working-tree / index / stash / branch assumption, run `git status` (and `git stash list`) live first.
 
 ## Collaboration Workflow
 
-- For the issue-driven proposal/plan/execution/notification flow, follow `node_modules/@joshuafolkken/kit/prompts/collaboration-workflow/` (indexed by `node_modules/@joshuafolkken/kit/prompts/collaboration-workflow.md`; each topic is its own file).
+- The issue-driven flow is `node_modules/@joshuafolkken/kit/prompts/collaboration-workflow/`, indexed by `node_modules/@joshuafolkken/kit/prompts/collaboration-workflow.md`.
 - **Before writing a rule as prose, place it by `node_modules/@joshuafolkken/kit/prompts/collaboration-workflow/residency.md`** — its single source. A computable answer goes to `pnpm josh oracle:list` and an ordering rule to `pnpm josh run:step`, never into `CLAUDE.md` or a prompt file.
 - **Count the target repository's open Issues before filing; above the WIP cap, close one first.** Nothing honestly closable means do not file. A filing the run is blocked by is exempt, and so is an **interrupt** — three tests decide that, never judgement: a verification answers wrongly, a documented workflow cannot complete, or data is lost or written outside the repository; both exemptions proceed, stating the overage. Meeting none of the three, a finding stays discretionary. `pnpm josh rule:guard` states it again at the call that files. The count command and both procedures: `node_modules/@joshuafolkken/kit/prompts/collaboration-workflow/wip-cap.md`.
 
@@ -162,11 +168,13 @@ Before every `git commit` (follow-up commits included), self-review against `nod
 | `halfrun [#N \| new]`    | Implement + gate, then **stop before commit** for manual verification                                                                                                 | + `halfrun.md` + `split-assessment.md`                           |
 | `backlogrun [#N1 #N2 …]` | Run named Issues and epics in order (an epic runs its children first), then drain the opted-in backlog — dependency order, lanes. `--only` stops after the named list | + `backlogrun.md` + `split-assessment.md` + the `fullrun` set    |
 
-**`queue` and `epicrun` were removed** — tell a user who types `queue` to run `backlogrun #N1 #N2 …`, and one who types `epicrun` to run `backlogrun #E --only` (drop `--only` to also drain the backlog).
+**`queue` and `epicrun` were removed** — point `queue` to `backlogrun #N1 #N2 …` and `epicrun` to `backlogrun #E --only`.
 
-**Three rules decide what a run does when the work turns out not to be one Issue** — the split assessment every entry point applies identically (**its default is not to split**: separability **and** a scope clearly exceeding one verification gate — the size guide in `split-assessment.md`, measured by `pnpm josh split:assess` — must both hold), a prerequisite discovered mid-run (a dependency, not parked), and a named `backlogrun` item that is not an epic. All bind only after a command has started, so all are read from the `workflow-commands` skill: `split-assessment.md`, `SKILL.md` → §2d, `backlogrun-child.md` → "When `#N` is not an epic", and `fullrun.md` / `halfrun.md` / `backlogrun.md` for the branch each entry takes.
+**The `josh epic:*` commands have their own skill** — `epic:audit`, `epic:next`, `epic:bundle`, and how an epic spans repositories. **Read the `epic-commands` skill before running any of them, before writing an epic that tracks a child in another repository, and right after filing an issue.** Three rules bind outside those commands:
 
-**The `josh epic:*` commands have their own skill** — `epic:audit`, `epic:next`, `epic:bundle`, and how an epic spans repositories. **Read the `epic-commands` skill before running any of them, before writing an epic that tracks a child in another repository, and right after filing an issue.** Three rules stay here because they bind outside those commands: **recording a decision removes that child's `needs-decision` label** (Tier A); **fixing what the audit finds is Tier A**, park only when the contradiction is a design choice nobody has made; and **an epic in another repository is referenced as `owner/repo#N`** (a bare `#N` resolves to this repository's issue). Canonical reference: `.claude/skills/epic-commands/SKILL.md`.
+- Recording a decision removes that child's `needs-decision` label (Tier A).
+- **Fixing what the audit finds is Tier A**; park only when the contradiction is a design choice nobody has made.
+- **An epic in another repository is referenced as `owner/repo#N`** — a bare `#N` resolves to this repository's issue.
 
 #### Explicit invocation required (MANDATORY)
 
@@ -177,18 +185,17 @@ Never start a `kickoff` / `halfrun` / `prrun` / `fullrun` / `backlogrun` workflo
 - Instead, **prompt the user to type the command themselves**, with the exact phrasing: "Please run \`<command>\` to start this task." (e.g. "Please run \`halfrun new\` to start this task.").
 - This applies even when the user authorized a related workflow in an earlier turn — each invocation must be re-typed in the current turn.
 
-**A session cut inside a declared budget is not a new invocation** — a `backlogrun` cut and resumed is the one invocation a person typed, and it continues rather than waiting to be retyped; **`backlogrun` alone**, though — a `fullrun` cut still waits for the keyword. Single source: `backlogrun-steps.md` → "The session cut is inside the invocation".
+**A session cut inside a declared budget is not a new invocation — for `backlogrun` alone**: a resumed `backlogrun` continues, while a `fullrun` cut still waits for the keyword. `backlogrun-steps.md` → "The session cut is inside the invocation".
 
-**A `backlogrun` parks a child instead of stopping the run**, and its procedure is read from `backlogrun-park.md` → "park and continue", which is that rule's single source.
+**A `backlogrun` parks a child instead of stopping the run** — `backlogrun-park.md` → "park and continue".
 
 #### Mid-workflow stop notification (`confirmation`)
 
-Whenever you pause **any** run mid-execution to wait for the user — a `kickoff` / `halfrun` / `prrun` / `fullrun` stop, an upstream-Issue interrupt, a Tier C confirmation — you MUST send a Telegram notification **before** stopping, so the user is alerted off-screen. `halfrun`'s built-in stop before commit is a confirmation pause and follows this same rule.
+Before pausing **any** run to wait for the user — a command's stop (`halfrun`'s stop before commit included), an upstream-Issue interrupt, a Tier C confirmation — you MUST send this Telegram, so the user is alerted off-screen:
 
 ```bash
 pnpm josh notify --task-type confirmation --issue-url "<issue-url>" --body=$'<one-line reason>\n<what is needed from the user>'
 ```
 
-- Use `--body=...` (single token) when the body starts with `-`, otherwise `parseArgs` rejects it
-- Send only once per stop — do not spam if you re-evaluate within the same pause
-- Skip the notification when the stop was explicitly requested by the user in the same turn (they already know)
+- Send it once per stop; skip it when the user asked for the stop in this same turn.
+- Pass `--body=...` as one token when the body starts with `-`, otherwise `parseArgs` rejects it.

package/dist/CLAUDE.static.md

@@ -1,8 +1,8 @@
 # Project instructions
 
-- 既存のファイルと利用者の設定を尊重し、変更する前に内容を確認する。
-- 変更には検証を付け、実行した結果を報告する。
-- HTML、CSS、JavaScript のファイルがある場合は Prettier で整形する。
-- 画面に見える変更をした場合はブラウザーで表示と操作を確認する。
-- JavaScript または TypeScript の動作を変更した場合は、その動作を確認する自動テストを追加する。
-- Git や GitHub を使う場合だけ、それぞれのワークフローを利用する。
+- Respect existing files and the user's settings, and read a file's contents before changing it.
+- Verify every change, and report the results you actually observed.
+- Format HTML, CSS and JavaScript files with Prettier when the project has any.
+- After a change that is visible on screen, check its display and interaction in a browser.
+- After changing JavaScript or TypeScript behavior, add an automated test that checks that behavior.
+- Use the Git or GitHub workflow only when you use Git or GitHub.