@joshuafolkken/kit 1.1050.0 → 1.1128.0

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

@@ -7,6 +7,10 @@ run-name: Publish ${{ github.ref_name }}
 on:
   workflow_dispatch:
 
+# Every job installs through `.github/actions/setup-pnpm`, so the jobs holding the publish rights
+# install behind the same hash-verified safe-chain scan as CI (joshuafolkken/kit#2982). The store
+# cache is off here: a cache entry another run saved never reaches a job with publish credentials.
+
 jobs:
   publish-github:
     if: startsWith(github.ref, 'refs/tags/v')
@@ -21,39 +25,40 @@ 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'
 
-      - name: Resolve pnpm version
-        id: pnpm-version
+      # Read before setup-pnpm puts the safe-chain shims on PATH: safe-chain hides recent versions from
+      # registry metadata and prints a notice to stdout, which corrupts the value (joshuafolkken/kit#3060).
+      - name: Read registry latest
+        id: registry-latest
         run: |
-          version=$(node -p "const m = require('./package.json'); m.packageManager?.match(/^pnpm@([^+]+)/)?.[1] ?? (m.devEngines?.packageManager?.name === 'pnpm' ? m.devEngines.packageManager.version?.split('+')[0] : 'latest') ?? 'latest'")
-          test -n "$version"
-          echo "version=$version" >> "$GITHUB_OUTPUT"
+          latest=$(cd "$RUNNER_TEMP" && npm view @joshuafolkken/kit dist-tags.latest --registry https://npm.pkg.github.com)
+          echo "latest=$latest" >> "$GITHUB_OUTPUT"
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
-      - uses: pnpm/setup@fbda4c85fc2e1e08721cd8763afea8f48d60f024 # v3.0.0
+      - uses: ./.github/actions/setup-pnpm
         with:
-          version: ${{ steps.pnpm-version.outputs.version }}
-          install: false
-
-      - run: pnpm install --frozen-lockfile --ignore-scripts
+          cache: 'false'
 
       - name: Select GitHub Packages tag
         id: publish-tag
         run: |
           version=$(node -p "require('./package.json').version")
-          latest=$(cd "$RUNNER_TEMP" && npm view @joshuafolkken/kit dist-tags.latest --registry https://npm.pkg.github.com)
-          tag=$(pnpm exec tsx scripts/release/publish-tag-cli.ts "$version" "$latest")
+          tag=$(pnpm exec tsx scripts/release/publish-tag-cli.ts "$version" "$LATEST")
           echo "tag=$tag" >> "$GITHUB_OUTPUT"
         env:
-          NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          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')
@@ -68,24 +73,20 @@ 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'
 
-      - name: Resolve pnpm version
-        id: pnpm-version
+      # Before setup-pnpm, for the same reason as publish-github's lookup (joshuafolkken/kit#3060).
+      - name: Read registry latest
+        id: registry-latest
         run: |
-          version=$(node -p "const m = require('./package.json'); m.packageManager?.match(/^pnpm@([^+]+)/)?.[1] ?? (m.devEngines?.packageManager?.name === 'pnpm' ? m.devEngines.packageManager.version?.split('+')[0] : 'latest') ?? 'latest'")
-          test -n "$version"
-          echo "version=$version" >> "$GITHUB_OUTPUT"
+          latest=$(cd "$RUNNER_TEMP" && npm view @joshuafolkken/kit dist-tags.latest --registry https://registry.npmjs.org)
+          echo "latest=$latest" >> "$GITHUB_OUTPUT"
 
-      - uses: pnpm/setup@fbda4c85fc2e1e08721cd8763afea8f48d60f024 # v3.0.0
+      - uses: ./.github/actions/setup-pnpm
         with:
-          version: ${{ steps.pnpm-version.outputs.version }}
-          install: false
-
-      - run: pnpm install --frozen-lockfile --ignore-scripts
+          cache: 'false'
 
       - run: pnpm pack --out "$RUNNER_TEMP/kit.tgz"
 
@@ -93,12 +94,15 @@ jobs:
         id: publish-tag
         run: |
           version=$(node -p "require('./package.json').version")
-          latest=$(cd "$RUNNER_TEMP" && npm view @joshuafolkken/kit dist-tags.latest --registry https://registry.npmjs.org)
-          tag=$(pnpm exec tsx scripts/release/publish-tag-cli.ts "$version" "$latest")
+          tag=$(pnpm exec tsx scripts/release/publish-tag-cli.ts "$version" "$LATEST")
           echo "tag=$tag" >> "$GITHUB_OUTPUT"
+        env:
+          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]
@@ -120,26 +124,18 @@ jobs:
         with:
           fetch-depth: 0
 
-      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
-        with:
-          node-version: 24
-
-      - name: Resolve pnpm version
-        id: pnpm-version
-        run: |
-          version=$(node -p "const m = require('./package.json'); m.packageManager?.match(/^pnpm@([^+]+)/)?.[1] ?? (m.devEngines?.packageManager?.name === 'pnpm' ? m.devEngines.packageManager.version?.split('+')[0] : 'latest') ?? 'latest'")
-          test -n "$version"
-          echo "version=$version" >> "$GITHUB_OUTPUT"
+      - uses: ./.github/actions/setup-node
 
-      - uses: pnpm/setup@fbda4c85fc2e1e08721cd8763afea8f48d60f024 # v3.0.0
+      - uses: ./.github/actions/setup-pnpm
         with:
-          version: ${{ steps.pnpm-version.outputs.version }}
-          install: false
-
-      - run: pnpm install --frozen-lockfile --ignore-scripts
+          cache: 'false'
 
+      # Tags through v1.887.0 predate automatic GitHub Releases and must not block the first new one.
       - name: Publish GitHub Release
-        run: pnpm exec tsx scripts/release/github-release-cli.ts
+        run: pnpm josh release:github
         env:
           GH_TOKEN: ${{ github.token }}
           RELEASE_TAG: ${{ github.ref_name }}
+          RELEASE_START_TAG: v1.887.0
+          RELEASE_WORKFLOW: publish.yml
+          RELEASE_JOBS: publish-github,publish-npm,update-production

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

@@ -18,7 +18,10 @@ jobs:
     name: SonarQube
     permissions:
       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.
@@ -34,11 +37,45 @@ 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
+      # each `josh bump` that reaches main starts a new New Code period.
+      - name: Resolve project version
+        id: project-version
+        if: env.SONAR_TOKEN != ''
+        run: |
+          version=$(jq -r '.version // empty' package.json)
+          echo "args=${version:+-Dsonar.projectVersion=$version}" >> "$GITHUB_OUTPUT"
       - name: SonarQube Scan
         if: env.SONAR_TOKEN != ''
         uses: SonarSource/sonarqube-scan-action@d209202bc7d53ff1cc128f7f907dac145c9d6ae9 # v8.3.0
         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
+          # Wait for the SonarCloud Quality Gate and fail this job when the gate is red. The gate
+          # judges ratings and ratios, not counts, so it alone lets a few new code smells or a small
+          # copied block through; the new-code check below is what fails on a single finding.
+          args: -Dsonar.qualitygate.wait=true ${{ steps.project-version.outputs.args }}
+      # The new-code check reads the pull request's analysis from the SonarCloud API and fails this
+      # 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: Fail on new Sonar issues or duplicated blocks
+        if: env.SONAR_TOKEN != '' && github.event_name == 'pull_request'
+        env:
+          PULL_REQUEST: ${{ github.event.pull_request.number }}
+        run: pnpm josh sonar:new-code "$PULL_REQUEST"

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,8 +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. Nothing in
-> `CLAUDE.md` is Claude-specific — it applies to whatever agent is doing the work.
+> any work here, and follow every rule in it.** This file exists only to point at it.
+
+**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

@@ -1,8 +1,6 @@
 # Claude Code Instructions
 
-> **This file is the single source for every agent rule.** `AGENTS.md` and `GEMINI.md` are pointers to it and carry no rules of their own — a rule addition, spec change or wording fix is written **once**, here. History: `docs/maintainers/claude-md-history.md`.
->
-> Each rule is written as a **trigger plus a pointer** — enough to act safely with nothing else loaded, with the steps and rationale at the pointer.
+> **This file is the entry point for every agent rule.** `AGENTS.md` and `GEMINI.md` are pointers to it and carry no rules of their own — a rule's trigger is written **once**, here, and its procedure and any number it uses **once**, at its pointer. History, and the explanations kept out of this file: `docs/maintainers/claude-md-history.md`.
 
 ## Project
 
@@ -19,8 +17,8 @@ Stack: TypeScript · pnpm · SvelteKit · Vitest · Playwright · TailwindCSS ·
 - **Distinguish consultation from execution.** A question about approach or a goal statement ("どうすべき？", "〜したい") is a request for analysis only — act only on an explicit imperative or a workflow keyword. `prompts/collaboration-workflow/principles.md` → "相談と実行".
 - **Route distributed-doc / config changes upstream to kit.** In a consumer repo never edit kit-distributed docs/config locally (`josh sync` overwrites them); propose the change for kit. In kit itself you are the source. `prompts/collaboration-workflow/principles.md` → "配布ドキュメント".
 - **Latest-first, fix forward — pin back only as a last resort.** Adopt newest versions by default and resolve a breaking bump forward, recording why on the rare pin-back. `prompts/collaboration-workflow/principles.md` → "最新優先".
-- **Output language follows `JOSH_SESSION_LANG`** (default `ja`; a hook injects it). It governs session-facing output and artifact prose (Issue bodies, comments, Telegram). English stays for Issue/PR titles, code comments/test titles/commit messages, and script-emitted strings. `prompts/collaboration-workflow/overview.md`.
-- **Cite an Issue with a number-link and a short Japanese title in session-facing output** — `[#<N>](https://github.com/<owner>/<repo>/issues/<N>) — <短い要約>`. `prompts/collaboration-workflow/issue-citation.md`.
+- **Output language follows `JOSH_SESSION_LANG`** (default `ja`; a hook injects it). It governs session-facing output and artifact prose (Issue bodies, comments, Telegram). English stays for Issue/PR titles, code comments/test titles/commit messages, and script-emitted strings. One language per doc layer (English here; mostly Japanese in the prompt files). `prompts/collaboration-workflow/overview.md`.
+- **Cite an Issue with a number-link and a short title in the session language in session-facing output** — `[#<N>](https://github.com/<owner>/<repo>/issues/<N>) — <short summary>`. `prompts/collaboration-workflow/issue-citation.md`.
 - **Durable rules belong in prompts/docs, not local MEMORY.** Encode a lasting rule as a change to kit's distributed prompts/docs, not auto-memory; propose the edit when the turn does not authorize one. `prompts/collaboration-workflow/principles.md` → "恒久ルール".
 - **Never carry a file's new text inside a shell command.** Edit a region with the Edit tool, never a heredoc — unless the change is so scattered the partial edit would carry more text than the file. The criterion is whether the command carries the replacement wholesale, not the tool's name. `prompts/collaboration-workflow/file-edits.md`.
 - **Never put a body in shell double quotes** — a backtick or `$` there is _executed_; pass the body by path. `prompts/collaboration-workflow/shell-body.md`.
@@ -38,7 +36,7 @@ Classify each decision point into one tier and act; stop **only** when the choic
 
 ## Environment Variables
 
-Read from a `.env` file at the project root by the AI scripts, `josh port` and `playwright.config.ts`. `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 full 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`.
 
@@ -66,7 +64,7 @@ Read from a `.env` file at the project root by the AI scripts, `josh port` and `
 ### Quality limits
 
 - Function complexity ≤5 · nesting ≤2 · function ≤25 lines · file ≤300 lines · params ≤4 · statements per function ≤10 · cognitive complexity ≤4
-- **Those line counts are code lines, not physical lines** (`max-lines` / `max-lines-per-function` run with `skipBlankLines` + `skipComments`) — judge by what `pnpm josh lint` reports, never `wc -l`. Test files (`*.test.ts` / `*.e2e.ts`) allow 35 code lines per function.
+- **Those line counts are code lines, not physical lines** — judge by what `pnpm josh lint` reports, never `wc -l`. Test files (`*.test.ts` / `*.e2e.ts`) allow 35 code lines per function.
 - Magic numbers: extract all literals except `0`, `1`, `-1` to named `UPPER_CASE` constants
 - No `any` · no unused vars · no floating promises · type assertions (`as`) are restricted
 - All function params and return types must be explicitly typed
@@ -96,18 +94,20 @@ Read from a `.env` file at the project root by the AI scripts, `josh port` and `
 
 - Before building a feature, check whether a well-maintained package already solves the problem rather than writing original code first, and propose replacing hand-rolled implementations with a suitable package when it improves maintainability.
 - Prefer modern, actively-maintained packages (maintenance, popularity, bundle size, TypeScript support, license, fit). **If one is clearly the best fit, select it** (Tier A — log it); **only when two or more are genuinely close**, present about three ranked options and let the user choose.
-- **Measure the choice before you judge it — `pnpm josh pkg:scout <keywords>`.** It ranks the candidate packages by downloads, last publish, bundled types, license and install size, and prints `clear` when the leader is ahead by at least the near-tie threshold (select it, Tier A) or `close` when the top two are within it (ask, Tier B) — so "clearly best" and "genuine toss-up" are read off the output rather than decided by impression.
+- **Measure the choice before you judge it — `pnpm josh pkg:scout <keywords>`:** `clear` → select it (Tier A), `close` → ask (Tier B). Metrics and threshold: `docs/josh-commands-automation.md`.
 
 ## Code Change Rules
 
 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 the `UserPromptSubmit` hook 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 の手動確認例外:** `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`).
+   - **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.
@@ -131,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 — **at most two reviews in total**, the second 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`, so the only judgement left is whether the defect is confirmed — 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 third round; CI runs no Claude review, so this pass is authoritative. `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
 
@@ -139,20 +143,20 @@ 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; with more than 30 open, 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`.
+- **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`.
 
 ### Shorthand Commands
 
-`kickoff`, `fullrun`, `halfrun` and `backlogrun` are the Issue-driven shorthand commands. **Their procedures are not resident** — they live in the `workflow-commands` skill. **What stays here is decided by one question: must the rule fire on a turn where no skill was loaded?** Explicit invocation, the mid-workflow stop notification, the `overrides` / `devEngines` prohibitions, the UI-verification gate and the three `epic:*` rules below all do; everything a run reaches only after reading the skill is routed to, never restated (`prompts/collaboration-workflow/residency.md` → "第 2 問").
+`kickoff`, `fullrun`, `prrun`, `halfrun` and `backlogrun` are the Issue-driven shorthand commands. **Their procedures are not resident** — they live in the `workflow-commands` skill. **What stays here is decided by one question: must the rule fire on a turn where no skill was loaded?** Explicit invocation, the mid-workflow stop notification, the `overrides` / `devEngines` prohibitions, the UI-verification gate and the three `epic:*` rules below all do; everything a run reaches only after reading the skill is routed to, never restated (`prompts/collaboration-workflow/residency.md` → "第 2 問").
 
 **Read the skill before running any part of a command — including the first `gh` call.**
 
@@ -160,36 +164,38 @@ Before every `git commit` (follow-up commits included), self-review against `pro
 | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
 | `kickoff [#N \| new]`    | Plan only — normalize title, post the plan, notify, **stop**                                                                                                          | `workflow-commands` skill + `kickoff.md` + `split-assessment.md` |
 | `fullrun [#N \| new]`    | Plan → implement → gate → PR → **merge** → notify                                                                                                                     | + `fullrun.md` + `split-assessment.md` + `chain-rule.md`         |
+| `prrun [#N \| new]`      | `fullrun` up to a green, mergeable PR, then **stop** for a person to merge by hand                                                                                    | + `prrun.md` + the `fullrun` set                                 |
 | `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 — about 10 changed files, about 400 changed lines (test files excluded) — 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)
 
-Never start a `kickoff` / `halfrun` / `fullrun` / `backlogrun` workflow (including their `#N` and `new` variants) unless the user has typed the keyword in the **current turn's prompt**.
+Never start a `kickoff` / `halfrun` / `prrun` / `fullrun` / `backlogrun` workflow (including their `#N` and `new` variants) unless the user has typed the keyword in the **current turn's prompt**.
 
 - Conversational requests like "implement X", "fix Y", "open a PR for Z" are **NOT** implicit invocations — do not infer authorization from the request shape.
 - Do **NOT** ask confirmation questions like "Shall I run `fullrun`?". A confirmation prompt is not a substitute for explicit invocation.
 - 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` / `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,10 +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. Nothing in
-> `CLAUDE.md` is Claude-specific — it applies to whatever agent is doing the work.
+> any work here, and follow every rule in it.** This file exists only to point at it.
 
 @CLAUDE.md
 
+**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

@@ -1,43 +1,89 @@
 # @joshuafolkken/kit
 
-**Write a GitHub Issue. Your AI agent takes it to a merged PR — the same way in every project.**
-
-kit gives Claude Code (or Codex, Gemini, Cursor) your project's rules, checks and an Issue-driven workflow. You type one keyword. The agent plans, implements, verifies, opens the PR and merges it.
+[![Claude Code](https://img.shields.io/badge/Claude_Code-supported-D97757?logo=claude&logoColor=white)](https://claude.com/claude-code)
+[![Codex](https://img.shields.io/badge/Codex-supported-412991)](https://openai.com/codex/)
+[![npm version](https://img.shields.io/npm/v/@joshuafolkken/kit)](https://www.npmjs.com/package/@joshuafolkken/kit)
+[![License](https://img.shields.io/github/license/joshuafolkken/kit)](./LICENSE)
+
+[![Node.js](https://img.shields.io/node/v/@joshuafolkken/kit?logo=nodedotjs)](https://nodejs.org/)
+[![TypeScript](https://img.shields.io/npm/dependency-version/@joshuafolkken/kit/peer/typescript?logo=typescript)](https://www.typescriptlang.org/)
+[![pnpm](https://img.shields.io/github/package-json/packageManager/joshuafolkken/kit?logo=pnpm&label=pnpm)](https://pnpm.io/)
+
+[![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)
+
+**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.
+
+## Sound familiar?
+
+Each pain links to how it is solved — or read [the whole story](./docs/why.md).
+
+| Your pain                                                                                                                  | kit | [app-kit] | [game-kit] |
+| -------------------------------------------------------------------------------------------------------------------------- | :-: | :-------: | :--------: |
+| [Done doesn't mean done](./docs/why.md#done-doesnt-mean-done)                                                              | ✅  |    ✅     |     ✅     |
+| [Quality slips with every change](./docs/why.md#quality-slips-with-every-change)                                           | ✅  |    ✅     |     ✅     |
+| [I keep repeating the same instructions](./docs/why.md#i-keep-repeating-the-same-instructions)                             | ✅  |    ✅     |     ✅     |
+| [The agent does things I never asked for](./docs/why.md#the-agent-does-things-i-never-asked-for)                           | ✅  |    ✅     |     ✅     |
+| [Reviewing every change is a chore](./docs/why.md#reviewing-every-change-is-a-chore)                                       | ✅  |    ✅     |     ✅     |
+| [Some changes need a human eye](./docs/why.md#some-changes-need-a-human-eye)                                               | ✅  |    ✅     |     ✅     |
+| [I spend all day talking to the agent](./docs/why.md#i-spend-all-day-talking-to-the-agent)                                 | ✅  |    ✅     |     ✅     |
+| [Big requests come back sloppy](./docs/why.md#big-requests-come-back-sloppy)                                               | ✅  |    ✅     |     ✅     |
+| [I want many Issues solved at once](./docs/why.md#i-want-many-issues-solved-at-once)                                       | ✅  |    ✅     |     ✅     |
+| [AI costs keep climbing](./docs/why.md#ai-costs-keep-climbing)                                                             | ✅  |    ✅     |     ✅     |
+| [Writing Issues is a chore](./docs/why.md#writing-issues-is-a-chore)                                                       | ✅  |    ✅     |     ✅     |
+| [Wiring AI up to GitHub is a chore](./docs/why.md#wiring-ai-up-to-github-is-a-chore)                                       | ✅  |    ✅     |     ✅     |
+| [I can't tell if the agent is stuck or done](./docs/why.md#i-cant-tell-if-the-agent-is-stuck-or-done)                      | ✅  |    ✅     |     ✅     |
+| [One task overwrote another's work](./docs/why.md#one-task-overwrote-anothers-work)                                        | ✅  |    ✅     |     ✅     |
+| [A session cut off and I lost track](./docs/why.md#a-session-cut-off-and-i-lost-track)                                     | ✅  |    ✅     |     ✅     |
+| [The backlog fills with duplicate Issues](./docs/why.md#the-backlog-fills-with-duplicate-issues)                           | ✅  |    ✅     |     ✅     |
+| [Setting up SvelteKit on Cloudflare takes a day](https://github.com/joshuafolkken/app-kit/blob/main/docs/setup/install.md) |  —  |    ✅     |     ✅     |
+| [I'm not sure the app is secure](https://github.com/joshuafolkken/app-kit/blob/main/docs/security-headers.md)              |  —  |    ✅     |     ✅     |
+| [Nobody looked at the screen](https://github.com/joshuafolkken/app-kit/blob/main/docs/shot.md)                             |  —  |    ✅     |     ✅     |
+| [Starting a 3D game means building it all first](https://github.com/joshuafolkken/game-kit/blob/main/docs/install.md)      |  —  |     —     |     ✅     |
+
+Each kit includes the one to its left: app-kit builds on kit, game-kit builds on app-kit.
+
+[app-kit]: https://github.com/joshuafolkken/app-kit
+[game-kit]: https://github.com/joshuafolkken/game-kit
 
 ## The workflow
 
-| You type         | The agent                                                              |
-| ---------------- | ---------------------------------------------------------------------- |
-| `kickoff new`    | Files the Issue from your conversation, posts the plan and stops       |
-| `halfrun #N`     | Implements and verifies, then stops before commit so you can look      |
-| `fullrun #N`     | Implements, verifies, self-reviews, opens the PR, waits for CI, merges |
-| `backlogrun #N…` | Works through several Issues (or an epic) unattended                   |
+| You type     | The agent                                        |
+| ------------ | ------------------------------------------------ |
+| `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                      |
 
-## Why you can trust "done"
+Each keyword in full: [Run Issues with the workflow keywords](./docs/how-to/run-issues.md). When a run needs you, it [notifies you on Telegram](./docs/how-to/set-up-notifications.md).
 
-- **Checks are commands, not requests.** Lint, type check, spell check and tests run as one gate. "It should pass" doesn't count.
-- **Missing tests stop the commit.** kit decides from the changed files whether a test is required, and stops the commit until the agent adds one or declares the change exempt.
-- **It tells you when it stops.** A run that needs you sends a [Telegram notification](./docs/how-to/set-up-notifications.md).
+## Why you can trust "done"
 
-More: [why kit exists](./docs/why.md) (Japanese)
+- **Checks are commands.** Lint, types, spelling and tests run as one gate — "it should pass" doesn't count.
+- **No test, no commit.** kit decides from the changed files whether a test is required.
 
 ## Quick start
 
-Requires Node.js 22.19+, pnpm 12+ 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? Run `pnpm --allow-build=esbuild dlx @joshuafolkken/kit init` instead — see setup for [Node projects](./docs/setup/full.md#2-install-and-initialize-with-josh-init) or [other projects](./docs/setup/basic.md).
+No Issue workflow? [Node projects](./docs/setup/full.md#2-install-and-initialize-with-josh-init) · [Other projects](./docs/setup/basic.md)
 
 ## Docs
 
-[Tutorial](./docs/tutorial.md) · [How-to](./docs/how-to.md) · [Commands](./docs/josh-commands.md) · [Troubleshooting](./docs/troubleshooting.md) · [Overview & all docs](./docs/overview.md)
-
-## Contributing · License
+[Tutorial](./docs/tutorial.md) · [How-to](./docs/how-to.md) · [Commands](./docs/josh-commands.md) · [Troubleshooting](./docs/troubleshooting.md) · [All docs](./docs/overview.md)
 
-[CLAUDE.md](./CLAUDE.md) · [publishing.md](./docs/publishing.md) · [MIT](./LICENSE)
+[Releases](https://github.com/joshuafolkken/kit/releases) · [Security](./SECURITY.md) · [Contributing](./docs/maintainers/README.md) · [MIT](./LICENSE)