@joshuafolkken/kit 1.929.0 → 1.953.0

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

@@ -126,5 +126,11 @@ act, so the run continues rather than stalling — the sanctioned boundary disti
 turn-end this section forbids. The boundary, its two commands and the resume verification are the
 `pre-gate-cut.md` skill document, its single source.
 
+**A headless lane child (`claude -p`) is where "a background command re-invokes the run" does not
+hold: its background Bash tasks are killed when its turn ends** (joshuafolkken/kit#2704). It hands the
+gate-to-merge region to `pnpm josh ship --detach` instead (`chain-rule.md` step 0); `pnpm josh
+rule:guard` refuses a backgrounded `josh gate` / `git` / `followup` there, and the `Stop` hook sends a
+child with a task still running back to wait rather than to notify.
+
 The operational section above is the single source of the rule. `followup.md`, `chain-rule.md` and
 `backlogrun-progress.md` → "Progress while the run is quiet" route here for it rather than restating it.

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

@@ -125,7 +125,7 @@ brief hands them to the unit.
    discretionary observation has**: a child files `route:tier-a` and `route:interrupt` only, and the
    parent files what survives — `SKILL.md` → §2i, the single source. **What the parent does with the
    rest is append it, not drop it**: an observation that cannot cite the depth-0 work it blocked
-   becomes one line in `docs/observations.md`, and a second line under the same key files it. **The
+   becomes one line in the observation ledger, and a second line under the same key files it. **The
    child never writes that file** — it cannot tell its observation from the sibling lane's.
 4. **Decisions taken and why**, where the decision was not already logged as an Issue comment.
 5. **What was left undone**, and under whose authority.

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

@@ -111,16 +111,17 @@ written.
 **Running unattended gets harder, not easier, and that is the honest trade.** Many lanes make the
 overlap between children real, and every overlap that becomes a conflict costs the child that loses the
 race a resolution, a re-run gate and a review ("Conflicts are not predicted" below), and parks it
-outright under that section's four conditions. The run finishes more work per hour **and** spends more
-of each child's budget on merge races. Do not report the first without the second.
+outright under that section's four conditions. Report the throughput gain only with its merge-race
+cost.
 
 ### Once per repository, before the first lane opens
 
 In the **primary checkout**, in this order, and never again per lane:
 
-1. `git switch main && git pull` — every lane is branched from this ref.
+1. `git switch main && git pull` — every lane branches from this ref.
 2. `pnpm josh latest:scope`, and the update on `required` — "`josh latest` runs once per session" above.
 3. `pnpm josh lane:prune` — closes the lanes an interruption left registered without a work tree.
+4. `pnpm josh run:tidy` — sweeps merged lanes and stashes (as `run:hold` does).
 
 **`pnpm josh latest` is never run inside a lane, whatever `latest:scope` answers there** — the command
 enforces it: `latest:scope` answers `skip` in a lane and `pnpm josh latest` refuses outright, fronted

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

@@ -176,7 +176,7 @@ joshuafolkken/kit#1726 is the worked case: its own body says the depth test woul
 and it was filed anyway, because **discarding it was the only alternative on offer**
 (joshuafolkken/kit#1728).
 
-- **The destination is `docs/observations.md` in the repository the observation is about** — the same
+- **The destination is `docs/maintainers/observations.md` in the repository the observation is about** — the same
   repository the Issue would have been filed into. **The count and the append are both run in that
   repository's checkout**, resolved the way §2c (`target-repository.md`) resolves any cross-repository target, and the file is
   created on the first append where that repository has none. **The subject decides, never the
@@ -230,7 +230,7 @@ watched. **A missing file is not a count of zero, though** — there `grep` exit
 number at all, so an empty answer means create the ledger, never that this is a first sighting.
 
 ```bash
-grep -c '^- k:<slug> |' <that repository's checkout>/docs/observations.md || true
+grep -c '^- k:<slug> |' <that repository's checkout>/docs/maintainers/observations.md || true
 ```
 
 Free-text comparison is what the key exists to replace, so two lines that read alike under different
@@ -255,7 +255,7 @@ that is empty on every other machine**, and every sighting was a first one, whic
 joshuafolkken/kit#1728 created the ledger to end.
 
 - **An ordinary run never commits the ledger, and that is enforced rather than remembered.**
-  `pnpm josh git` stages with `docs/observations.md` excluded, in the one staging step every entry
+  `pnpm josh git` stages with `docs/maintainers/observations.md` excluded, in the one staging step every entry
   point goes through (`scripts/git/git-staging.ts`), so a `fullrun` in the primary checkout **cannot**
   carry a ledger line into an Issue that has nothing to do with it. It is not a rule a run has to
   remember at the commit — a run that had to would be the run that forgets.

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

@@ -18,7 +18,7 @@ another is the failure this section exists to prevent:
 | A defect originating in **another package**                                 | File the upstream Issue and **stop** — Tier A for a first-party target; a third-party one is Tier C, recorded and drafted rather than filed (`CLAUDE.md` → "Cross-package problems"; `prompts/collaboration-workflow/upstream-interrupt.md`) |
 | This Issue was really **several** (a split)                                 | File the children and the epic and **stop** — except under `backlogrun`, whose authorization already covers a batch, so the children are filed and run through (`split-assessment.md`) |
 | Another Issue in **this** repository has to land first (**a prerequisite**) | This section                                                                                                            |
-| Something worth filing that is **none of the three** (**an observation**)   | File it **without asking** — Tier A for a first-party target — and **carry the run straight on**: nothing is stashed, nothing is parked (§2i). **A delegated child does not file here**, and a filing at depth 1 or deeper cites the depth-0 work it blocked; one that cannot cite it goes to `docs/observations.md` and is filed on its second sighting — all of them §2i's |
+| Something worth filing that is **none of the three** (**an observation**)   | File it **without asking** — Tier A for a first-party target — and **carry the run straight on**: nothing is stashed, nothing is parked (§2i). **A delegated child does not file here**, and a filing at depth 1 or deeper cites the depth-0 work it blocked; one that cannot cite it goes to `docs/maintainers/observations.md` and is filed on its second sighting — all of them §2i's |
 
 **File the prerequisite with the `route:tier-a` label**, so a Tier A filing made during implementation
 stays countable by filing route afterwards. **This paragraph belongs to the prerequisite row, not to

package/.github/workflows/ci.yml

@@ -4,9 +4,13 @@ on:
   push:
     branches: [main]
 
+  # No `labeled` / `unlabeled`: a label added right after the pull request opens started a second
+  # run on the same commit, the concurrency block below cancelled one of the two, and a cancelled
+  # run left in the newer check suite blocked the merge (joshuafolkken/kit#2712). The one check that
+  # reads labels runs in `pr-classification.yml` instead.
   pull_request:
     branches: [main]
-    types: [opened, synchronize, reopened, labeled, unlabeled]
+    types: [opened, synchronize, reopened]
 
 # A push run is grouped by the commit it carries, so a later push to main never cancels an earlier
 # one. Without the sha every push to main shares one group — `github.ref` is `refs/heads/main` for
@@ -23,6 +27,12 @@ concurrency:
 # set the JOSH_PLAYWRIGHT_BROWSERS repository variable to a space-separated list to widen it.
 env:
   JOSH_PLAYWRIGHT_BROWSERS: ${{ vars.JOSH_PLAYWRIGHT_BROWSERS || 'chromium' }}
+  # The safe-chain release every "Setup safe-chain" step installs, and the SHA-256 of that release's
+  # install-safe-chain.sh. The installer puts the safe-chain binary under ~/.safe-chain/bin and
+  # adds it to PATH beside the shims; `pnpm dlx … setup-ci` left only the shims, which then let
+  # every install through without a scan (joshuafolkken/kit#2711). `josh latest` moves both together.
+  SAFE_CHAIN_INSTALLER_VERSION: 1.5.20
+  SAFE_CHAIN_INSTALLER_SHA256: 0ad25efe15d1fa56105157a454d647223e78eb0c53d1f85e3d10afcd722e7bfd
 
 jobs:
   node-26-pnpm:
@@ -308,7 +318,11 @@ jobs:
             ${{ runner.os }}-cspell-cache-
 
       - name: Setup safe-chain
-        run: pnpm dlx @aikidosec/safe-chain@1.5.20 setup-ci
+        run: |
+          installer="$RUNNER_TEMP/install-safe-chain.sh"
+          curl --proto '=https' -fsSL "https://github.com/AikidoSec/safe-chain/releases/download/$SAFE_CHAIN_INSTALLER_VERSION/install-safe-chain.sh" -o "$installer"
+          echo "$SAFE_CHAIN_INSTALLER_SHA256  $installer" | sha256sum -c -
+          sh "$installer" --ci
 
       - name: Install dependencies
         env:
@@ -352,10 +366,6 @@ jobs:
       - name: Run verification gate
         run: pnpm josh gate --verbose --no-unit
 
-      - name: Check release classification
-        if: github.event_name == 'pull_request'
-        run: pnpm josh pr:classification
-
   # The other half of the gate, on a runner of its own. It carries the same setup steps as
   # `static-checks` rather than sharing them: a GitHub job is its own machine, so every job that
   # needs Node sets Node up, and this workflow already writes that preamble once per job. The
@@ -411,7 +421,11 @@ jobs:
             ${{ runner.os }}-pnpm-store-
 
       - name: Setup safe-chain
-        run: pnpm dlx @aikidosec/safe-chain@1.5.20 setup-ci
+        run: |
+          installer="$RUNNER_TEMP/install-safe-chain.sh"
+          curl --proto '=https' -fsSL "https://github.com/AikidoSec/safe-chain/releases/download/$SAFE_CHAIN_INSTALLER_VERSION/install-safe-chain.sh" -o "$installer"
+          echo "$SAFE_CHAIN_INSTALLER_SHA256  $installer" | sha256sum -c -
+          sh "$installer" --ci
 
       - name: Install dependencies
         env:
@@ -623,7 +637,11 @@ jobs:
             ${{ runner.os }}-build-cache-e2e-
 
       - name: Setup safe-chain
-        run: pnpm dlx @aikidosec/safe-chain@1.5.20 setup-ci
+        run: |
+          installer="$RUNNER_TEMP/install-safe-chain.sh"
+          curl --proto '=https' -fsSL "https://github.com/AikidoSec/safe-chain/releases/download/$SAFE_CHAIN_INSTALLER_VERSION/install-safe-chain.sh" -o "$installer"
+          echo "$SAFE_CHAIN_INSTALLER_SHA256  $installer" | sha256sum -c -
+          sh "$installer" --ci
 
       - name: Install dependencies
         env:

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

@@ -0,0 +1,76 @@
+name: Release classification
+
+# The release-classification check, on its own because it is the one check that reads labels
+# (joshuafolkken/kit#2712). While it lived in CI, CI had to rerun on `labeled` / `unlabeled`; `josh pr`
+# labels a pull request the moment it opens, so every pull request started two CI runs on one commit,
+# and CI's per-ref concurrency cancelled one of them. GitHub judges a check name by its newest check
+# suite, and which of the two runs sat in the newer suite was a race — when it was the cancelled one,
+# the pull request stayed BLOCKED until someone reran it.
+on:
+  pull_request:
+    branches: [main]
+    types: [opened, synchronize, reopened, labeled, unlabeled]
+
+# Deliberately no `concurrency` block. Cancelling is exactly what left the blocking suite behind, and
+# nothing here needs it: every run reads the pull request's labels as they stand when it runs, not as
+# its event carried them, so whichever suite GitHub counts as newest holds a current verdict.
+
+jobs:
+  classification:
+    name: Release classification
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      contents: read
+      packages: read
+      pull-requests: read
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Setup Node.js
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version: '24'
+
+      - name: Configure GitHub Packages authentication for existing projects
+        run: printf '//npm.pkg.github.com/:_authToken=${NODE_AUTH_TOKEN}\n' >> "$HOME/.npmrc"
+
+      - 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"
+
+      - name: Setup pnpm
+        uses: pnpm/setup@fbda4c85fc2e1e08721cd8763afea8f48d60f024 # v3.0.0
+        with:
+          version: ${{ steps.pnpm-version.outputs.version }}
+          install: false
+
+      - name: Resolve pnpm store path
+        run: echo "PNPM_STORE_PATH=$(pnpm store path)" >> "$GITHUB_ENV"
+
+      - name: Setup pnpm store cache
+        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
+        with:
+          path: ${{ env.PNPM_STORE_PATH }}
+          key: ${{ runner.os }}-pnpm-store-${{ hashFiles('pnpm-lock.yaml') }}
+          restore-keys: |
+            ${{ runner.os }}-pnpm-store-
+
+      - name: Setup safe-chain
+        run: pnpm dlx @aikidosec/safe-chain@1.5.20 setup-ci
+
+      - name: Install dependencies
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: pnpm install --frozen-lockfile --ignore-scripts
+
+      - name: Check release classification
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: pnpm josh pr:classification

package/README.md

@@ -1,42 +1,64 @@
 # @joshuafolkken/kit
 
-Shared toolchain config and CLI for TypeScript projects — ESLint, Prettier, TypeScript, Lefthook, cspell, VS Code, and AI assistant files (CLAUDE.md, plus AGENTS.md / GEMINI.md pointing at it), wired together. It is framework-agnostic; the SvelteKit-specific layer lives in the separate [`@joshuafolkken/app-kit`](https://github.com/joshuafolkken/app-kit) package.
+A development toolkit that sets up a repository for AI-assisted work with one command. `josh init` gives an AI assistant (Claude Code, Codex, Gemini, Cursor) the project's rules, and the `josh` CLI runs the checks and the Git / GitHub Issue workflow the same way in every project. You stop copying config between repositories and re-explaining conventions to the assistant. For the problems kit exists to solve, see [why.md](./docs/why.md) (Japanese).
 
-- **`josh` CLI** — lint, format, type-check, git workflow, versioning, and security auditing from any directory.
-- **Project config package** — ESLint / Prettier / tsconfig presets, prompts, and scripts consumed as a devDependency.
+## What your project gets
 
-## Prerequisites
+kit does not branch by language. It asks one question — does the project use Node tooling? — and picks a [profile](./docs/init.md#project-profiles):
 
-- [Node.js](https://nodejs.org/) 22.19.0 or later with [pnpm](https://pnpm.io/) — [getting-started.md](./docs/getting-started.md) covers installing both
-- [gh CLI](https://cli.github.com/) for `josh version` and existing GitHub Packages consumers. It is not required to install kit from public npm; see [authentication.md](./docs/authentication.md) for setup when needed.
+| Your project                             | Profile  | What you get                                                      |
+| ---------------------------------------- | -------- | ----------------------------------------------------------------- |
+| Node project (JavaScript / TypeScript)   | `node`   | The full set: ESLint, type check, unit and E2E tests, Git hooks   |
+| HTML / CSS (browser JavaScript included) | `static` | Formatting (Prettier), AI assistant files, Git / VS Code settings |
+| Another language (Python, Rust, Go, …)   | `static` | AI assistant files and Git / VS Code settings only                |
+
+kit adds no linter or test runner for languages other than JavaScript and TypeScript; in a `static` project, `josh` skips each check that has nothing to run and says why.
 
 ## Quick start
 
+In your project directory:
+
 ```bash
-pnpm add -g @joshuafolkken/kit          # install the josh CLI globally
-josh help
+pnpm add -D --allow-build=esbuild @joshuafolkken/kit
+pnpm exec josh init
+pnpm install
+pnpm josh format
+pnpm josh gate
 ```
 
-Using the kit inside a project? See [docs/package.md](./docs/package.md).
+It needs [Node.js](https://nodejs.org/) 22.19.0 or later with [pnpm](https://pnpm.io/), even for a `static` project; [getting-started.md](./docs/getting-started.md) installs both. The global `josh` command ([cli.md](./docs/cli.md)) and the [gh CLI](https://cli.github.com/) for `josh version` and the GitHub Issue workflow are optional.
 
 ## Documentation
 
-| Guide                                           | What it covers                                                                   |
-| ----------------------------------------------- | -------------------------------------------------------------------------------- |
-| [why.md](./docs/why.md)                         | Why kit exists — the AI-development problems it solves, for practitioners        |
-| [getting-started.md](./docs/getting-started.md) | First install for an `index.html` site or a non-Node project, without Git        |
-| [authentication.md](./docs/authentication.md)   | GitHub Packages auth for existing projects                                       |
-| [cli.md](./docs/cli.md)                         | Install and use the global `josh` CLI                                            |
-| [package.md](./docs/package.md)                 | Use the kit as a project devDependency — configs, prompts, scripts, `josh init`  |
-| [publishing.md](./docs/publishing.md)           | First public npm release and trusted publishing setup                            |
-| [josh-commands.md](./docs/josh-commands.md)     | Full `josh` CLI command reference                                                |
-| [overview.md](./docs/overview.md)               | What the kit provides and how it works                                           |
-| [troubleshooting.md](./docs/troubleshooting.md) | `401`/`404` auth errors, `josh: command not found`, stale shim, version mismatch |
+**Get started**
+
+- [getting-started.md](./docs/getting-started.md) — first install for an `index.html` site or a non-Node project (`static`)
+- [package.md](./docs/package.md) — add kit to a Node project (`node`)
+- [tutorial.md](./docs/tutorial.md) — your first change with an agent, from Issue to merge
+- [how-to.md](./docs/how-to.md) — step-by-step guides by task: update, release, run Issues, fix a failing gate
+- [overview.md](./docs/overview.md) — what kit sets up and how it works
+
+**Commands and configuration**
+
+- [cli.md](./docs/cli.md) — install the global `josh` command
+- [josh-commands.md](./docs/josh-commands.md) — every `josh` command ([catalog](./docs/josh-command-catalog.md))
+- [init.md](./docs/init.md) — what `josh init` creates, per profile
+- [sync.md](./docs/sync.md) — what `josh sync` updates after an upgrade
+- [manual-config.md](./docs/manual-config.md) — use the presets without `josh init`
+- [package-api.md](./docs/package-api.md) — the config presets and libraries the package exports
+
+**AI workflow and operations**
+
+- [scripts-ai.md](./docs/scripts-ai.md) — Telegram notifications and the Issue workflow commands
+- [cloud-session.md](./docs/cloud-session.md) — running in an agent container
+- [eval.md](./docs/eval.md) — measuring whether the agent rules are followed
+- [troubleshooting.md](./docs/troubleshooting.md) — install and auth errors
+- [authentication.md](./docs/authentication.md) — existing GitHub Packages installs only
 
 ## Contributing
 
-Community standards live in [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md); security reports go through [SECURITY.md](./SECURITY.md). Development conventions are documented in `CLAUDE.md`; `AGENTS.md` and `GEMINI.md` are pointers to it.
+Community standards live in [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md); security reports go through [SECURITY.md](./SECURITY.md). Development conventions are in [CLAUDE.md](./CLAUDE.md); releases are in [publishing.md](./docs/publishing.md), and maintainer records in [docs/maintainers/](./docs/maintainers/).
 
 ## License
 
-MIT
+[MIT](./LICENSE)

package/dist/hooks/batch-guard.js

@@ -9,10 +9,10 @@ import {
   load_environment_file,
   notice_refusal_path,
   refusal_path
-} from "./chunk-ROULPSQC.js";
-import "./chunk-7XQ6TK3R.js";
-import "./chunk-SXPTRFPG.js";
-import "./chunk-2PGRQ62K.js";
+} from "./chunk-V7RH56HU.js";
+import "./chunk-OM5VDM6F.js";
+import "./chunk-O3PEDF3M.js";
+import "./chunk-EYFJ74MJ.js";
 import "./chunk-WPALEIRX.js";
 import "./chunk-RKUAD3I6.js";
 export {