@joshuafolkken/kit 1.2114.0 → 1.3000.0

package/.github/workflows/ci.yml

@@ -32,6 +32,21 @@ env:
 # pnpm version resolution, the store cache, the safe-chain installer pin and the install
 # (joshuafolkken/kit#2982).
 jobs:
+  change-scope:
+    runs-on: ubuntu-latest
+    timeout-minutes: 3
+    permissions:
+      contents: read
+    outputs:
+      runtime: ${{ steps.scope.outputs.runtime }}
+      publish: ${{ steps.scope.outputs.publish }}
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - uses: ./.github/actions/change-scope
+        id: scope
   # Every other job runs on the Node.js version `.github/actions/setup-node` names, while `engines`
   # and the esbuild target accept Node 22 and a consumer may already be on 26. This job builds the
   # package and starts the bundled CLI on both ends of that range, so a syntax or API the oldest
@@ -243,22 +258,24 @@ jobs:
   # unguarded. So the two halves run under new names and `Checks` stays exactly what the ruleset
   # already requires: a job that is green only when both halves are.
   #
-  # **The static half is a matrix of three legs** (joshuafolkken/kit#5215). On one runner its seven
+  # **The static half is a matrix of legs** (joshuafolkken/kit#5215). On one runner its seven
   # checks took 4.1 minutes while every unit shard was done in about two, so it was the critical path
   # to `Checks`. Each leg is still `josh gate`, narrowed by `--static-group` to the partition
   # `scripts/gate/gate-static-group.ts` defines, and restores only the caches its checks write — a leg
   # that restored a cache it never writes would save it back unchanged under the same sha-keyed name,
   # racing the leg that does write it. `needs.static-checks.result` is `success` only when every leg is.
+  # joshuafolkken/kit#7108: lint runs as two legs, `lint-1` and `lint-2`, one `josh lint --shard` each —
+  # one leg linted the whole tree in 156 s at the median and about 220 s after a core-module change.
   static-checks:
     name: Static Checks (${{ matrix.group }})
     needs: reuse-pr-checks
     if: ${{ !cancelled() && needs.reuse-pr-checks.outputs.reuse != 'true' }}
     runs-on: ubuntu-latest
-    timeout-minutes: 8
+    timeout-minutes: 12
     strategy:
       fail-fast: false
       matrix:
-        group: [lint, types, rest]
+        group: [lint-1, lint-2, types, rest]
     permissions:
       contents: read
       packages: read
@@ -280,7 +297,7 @@ jobs:
           registry-url: 'https://npm.pkg.github.com'
 
       - name: Setup ESLint cache
-        if: matrix.group == 'lint'
+        if: startsWith(matrix.group, 'lint-')
         uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
         id: eslint-cache
         with:
@@ -305,11 +322,14 @@ jobs:
           # list every local reuse reads — the cache is restored before the install, with no tsx to run
           # it. The lockfile and eslint config hashes move it with the two inputs ESLint's own
           # per-entry check does not cover.
-          key: ${{ runner.os }}-eslint-cache-${{ steps.setup-node.outputs.node-version }}-${{ hashFiles('pnpm-lock.yaml') }}-${{ hashFiles('eslint.config.js', 'eslint/**/*.js') }}-${{ github.sha }}
+          # joshuafolkken/kit#6118: PR-local restore-keys are tried before main's entries.
+          # Keep the config hash in every prefix so an old PR cache cannot hide main's warm lineage.
+          # joshuafolkken/kit#7126: the matrix group follows `eslint-cache-`, so each lint leg keeps its
+          # own lineage, prefix and artifact — the seed and warm jobs below carry the same group.
+          key: ${{ runner.os }}-eslint-cache-${{ matrix.group }}-${{ steps.setup-node.outputs.node-version }}-${{ hashFiles('eslint.config.js', 'eslint/**/*.js') }}-${{ hashFiles('pnpm-lock.yaml') }}-${{ github.sha }}
           restore-keys: |
-            ${{ runner.os }}-eslint-cache-${{ steps.setup-node.outputs.node-version }}-${{ hashFiles('pnpm-lock.yaml') }}-${{ hashFiles('eslint.config.js', 'eslint/**/*.js') }}-
-            ${{ runner.os }}-eslint-cache-${{ steps.setup-node.outputs.node-version }}-${{ hashFiles('pnpm-lock.yaml') }}-
-            ${{ runner.os }}-eslint-cache-${{ steps.setup-node.outputs.node-version }}-
+            ${{ runner.os }}-eslint-cache-${{ matrix.group }}-${{ steps.setup-node.outputs.node-version }}-${{ hashFiles('eslint.config.js', 'eslint/**/*.js') }}-${{ hashFiles('pnpm-lock.yaml') }}-
+            ${{ runner.os }}-eslint-cache-${{ matrix.group }}-${{ steps.setup-node.outputs.node-version }}-${{ hashFiles('eslint.config.js', 'eslint/**/*.js') }}-
 
       # `.tsbuildinfo` and `.cspellcache` were not cached in CI at all, so the type check and spell
       # check ran cold on every run. Both are content-addressed — `tsc` records its compiler options
@@ -349,9 +369,10 @@ jobs:
       # the whole tree cold on every run. Prettier hashes each file's absolute path into its entry
       # (`scripts/josh/josh-command-types.ts` → `GATE_CACHE_SPECS`), which is why no lane shares it,
       # but the runner checks out to the same path on every run, so an earlier run's entries hit. The
-      # key is the eslint cache's shape: lockfile and prettier config hashes, then the sha.
+      # key is the eslint cache's shape: lockfile and prettier config hashes, then the sha. Only the
+      # `lint-1` leg checks formatting (`scripts/lint/lint-shard.ts`), so only it writes the file.
       - name: Setup prettier cache
-        if: matrix.group == 'lint'
+        if: matrix.group == 'lint-1'
         uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
         id: prettier-cache
         with:
@@ -424,17 +445,17 @@ jobs:
       # transient artifact-service error must not turn this required job red; it continues on error.
       - name: Write ESLint cache prefix
         id: eslint-cache-prefix
-        if: github.event_name == 'pull_request' && matrix.group == 'lint'
+        if: github.event_name == 'pull_request' && startsWith(matrix.group, 'lint-')
         env:
-          ESLINT_CACHE_PREFIX: ${{ runner.os }}-eslint-cache-${{ steps.setup-node.outputs.node-version }}-${{ hashFiles('pnpm-lock.yaml') }}-${{ hashFiles('eslint.config.js', 'eslint/**/*.js') }}-
+          ESLINT_CACHE_PREFIX: ${{ runner.os }}-eslint-cache-${{ matrix.group }}-${{ steps.setup-node.outputs.node-version }}-${{ hashFiles('eslint.config.js', 'eslint/**/*.js') }}-${{ hashFiles('pnpm-lock.yaml') }}-
         run: printf '%s\n' "${ESLINT_CACHE_PREFIX}" > eslint-cache-prefix
 
       - name: Upload ESLint cache
-        if: github.event_name == 'pull_request' && matrix.group == 'lint'
+        if: github.event_name == 'pull_request' && startsWith(matrix.group, 'lint-')
         continue-on-error: true
         uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
         with:
-          name: eslint-cache-${{ github.event.pull_request.number }}
+          name: eslint-cache-${{ github.event.pull_request.number }}-${{ matrix.group }}
           path: |
             .eslintcache
             eslint-cache-prefix
@@ -451,13 +472,18 @@ jobs:
   # an outside author's run can write any `.eslintcache` it likes, and main's scope would then let
   # later pull requests skip lint on that forged record (joshuafolkken/kit#5050).
   seed-eslint-cache:
-    name: Seed ESLint Cache
+    name: Seed ESLint Cache (${{ matrix.group }})
     needs: reuse-pr-checks
     if: ${{ needs.reuse-pr-checks.outputs.reuse == 'true' }}
     runs-on: ubuntu-latest
     timeout-minutes: 2
     permissions:
       actions: read
+    # joshuafolkken/kit#7126: one leg per `static-checks` lint group, each seeding its own artifact.
+    strategy:
+      fail-fast: false
+      matrix:
+        group: [lint-1, lint-2]
     steps:
       - name: Download the reused run's ESLint cache
         id: download
@@ -467,6 +493,7 @@ jobs:
           RUN_ID: ${{ needs.reuse-pr-checks.outputs.run-id }}
           PULL_NUMBER: ${{ needs.reuse-pr-checks.outputs.pull-number }}
           AUTHOR_ASSOCIATION: ${{ needs.reuse-pr-checks.outputs.author-association }}
+          GROUP: ${{ matrix.group }}
         run: |
           case "${AUTHOR_ASSOCIATION}" in
             OWNER | MEMBER | COLLABORATOR) ;;
@@ -475,12 +502,12 @@ jobs:
               exit 0
               ;;
           esac
-          if ! gh run download "${RUN_ID}" --repo "${REPOSITORY}" --name "eslint-cache-${PULL_NUMBER}"; then
+          if ! gh run download "${RUN_ID}" --repo "${REPOSITORY}" --name "eslint-cache-${PULL_NUMBER}-${GROUP}"; then
             echo '::notice::The reused run left no ESLint cache; saving nothing.'
             exit 0
           fi
           prefix=$(cat eslint-cache-prefix)
-          if ! printf '%s' "${prefix}" | grep -Eq '^[A-Za-z]+-eslint-cache-v[0-9.]+-[0-9a-f]+-[0-9a-f]+-$'; then
+          if ! printf '%s' "${prefix}" | grep -Eq "^[A-Za-z]+-eslint-cache-${GROUP}-v[0-9.]+-[0-9a-f]+-[0-9a-f]+-\$"; then
             echo '::warning::The ESLint cache prefix is not a cache key; saving nothing.'
             exit 0
           fi
@@ -504,7 +531,7 @@ jobs:
   # result in its post step, so the cold lint is paid on main instead of on a pull request. The lint
   # only saves time, so its step continues on error: a red lint still saves, and leaves the job green.
   warm-eslint-lineage:
-    name: Warm ESLint Lineage
+    name: Warm ESLint Lineage (${{ matrix.group }})
     needs: [reuse-pr-checks, seed-eslint-cache]
     if: ${{ !cancelled() && needs.reuse-pr-checks.outputs.reuse == 'true' }}
     runs-on: ubuntu-latest
@@ -512,6 +539,10 @@ jobs:
     permissions:
       contents: read
       packages: read
+    strategy:
+      fail-fast: false
+      matrix:
+        group: [lint-1, lint-2]
     steps:
       - name: Checkout code
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
@@ -530,11 +561,10 @@ jobs:
         with:
           path: |
             .eslintcache
-          key: ${{ runner.os }}-eslint-cache-${{ steps.setup-node.outputs.node-version }}-${{ hashFiles('pnpm-lock.yaml') }}-${{ hashFiles('eslint.config.js', 'eslint/**/*.js') }}-${{ github.sha }}
+          key: ${{ runner.os }}-eslint-cache-${{ matrix.group }}-${{ steps.setup-node.outputs.node-version }}-${{ hashFiles('eslint.config.js', 'eslint/**/*.js') }}-${{ hashFiles('pnpm-lock.yaml') }}-${{ github.sha }}
           restore-keys: |
-            ${{ runner.os }}-eslint-cache-${{ steps.setup-node.outputs.node-version }}-${{ hashFiles('pnpm-lock.yaml') }}-${{ hashFiles('eslint.config.js', 'eslint/**/*.js') }}-
-            ${{ runner.os }}-eslint-cache-${{ steps.setup-node.outputs.node-version }}-${{ hashFiles('pnpm-lock.yaml') }}-
-            ${{ runner.os }}-eslint-cache-${{ steps.setup-node.outputs.node-version }}-
+            ${{ runner.os }}-eslint-cache-${{ matrix.group }}-${{ steps.setup-node.outputs.node-version }}-${{ hashFiles('eslint.config.js', 'eslint/**/*.js') }}-${{ hashFiles('pnpm-lock.yaml') }}-
+            ${{ runner.os }}-eslint-cache-${{ matrix.group }}-${{ steps.setup-node.outputs.node-version }}-${{ hashFiles('eslint.config.js', 'eslint/**/*.js') }}-
 
       - name: Setup pnpm and install dependencies
         if: steps.eslint-cache.outputs.cache-hit != 'true'
@@ -542,11 +572,14 @@ jobs:
         with:
           node-auth-token: ${{ secrets.GITHUB_TOKEN }}
 
+      # joshuafolkken/kit#7108: each leg lints only its group's shard, the files its lineage holds.
       - name: Lint to write this release's lineage
         id: lint
         if: steps.eslint-cache.outputs.cache-hit != 'true'
         continue-on-error: true
-        run: pnpm josh lint
+        run: pnpm josh lint "--shard=${GROUP#lint-}"
+        env:
+          GROUP: ${{ matrix.group }}
 
   # The other half of the gate, on a runner of its own. A GitHub job is its own machine, so this job
   # sets Node up again; the pnpm preamble is the shared `.github/actions/setup-pnpm` action
@@ -571,8 +604,8 @@ jobs:
   # where a small consumer suite would pay the duplicated setup and could leave a shard with no file.
   unit:
     name: Unit Tests (${{ matrix.shard }}/6)
-    needs: reuse-pr-checks
-    if: ${{ !cancelled() && needs.reuse-pr-checks.outputs.reuse != 'true' }}
+    needs: [reuse-pr-checks, change-scope]
+    if: ${{ !cancelled() && needs.reuse-pr-checks.outputs.reuse != 'true' && needs.change-scope.outputs.runtime == 'true' }}
     strategy:
       fail-fast: false
       matrix:
@@ -635,7 +668,7 @@ jobs:
   # shell body is the pattern to keep out of a workflow regardless of the value's provenance.
   checks:
     name: Checks
-    needs: [reuse-pr-checks, static-checks, unit, node-compat]
+    needs: [reuse-pr-checks, static-checks, unit, node-compat, change-scope]
     if: always()
     runs-on: ubuntu-latest
     timeout-minutes: 2
@@ -650,16 +683,26 @@ jobs:
           STATIC_RESULT: ${{ needs.static-checks.result }}
           UNIT_RESULT: ${{ needs.unit.result }}
           NODE_RESULT: ${{ needs.node-compat.result }}
+          SCOPE_RESULT: ${{ needs.change-scope.result }}
+          RUNTIME_CHANGED: ${{ needs.change-scope.outputs.runtime }}
         run: |
+          readonly SUCCESS='success'
           echo "Reuse PR Checks: ${REUSE_RESULT}"
           echo "Static Checks: ${STATIC_RESULT}"
           echo "Unit Tests: ${UNIT_RESULT}"
           echo "Node builds: ${NODE_RESULT}"
-          if [ "${NODE_RESULT}" != 'success' ]; then
+          if [ "${SCOPE_RESULT}" != "${SUCCESS}" ]; then
+            echo "::error::change classification did not pass"
+            exit 1
+          fi
+          if [ "${NODE_RESULT}" != "${SUCCESS}" ]; then
             echo "::error::the Node build matrix did not pass"
             exit 1
           fi
-          if [ "${STATIC_RESULT}" = 'success' ] && [ "${UNIT_RESULT}" = 'success' ]; then
+          if [ "${STATIC_RESULT}" = "${SUCCESS}" ] && [ "${UNIT_RESULT}" = "${SUCCESS}" ]; then
+            exit 0
+          fi
+          if [ "${STATIC_RESULT}" = "${SUCCESS}" ] && [ "${UNIT_RESULT}" = 'skipped' ] && [ "${RUNTIME_CHANGED}" = 'false' ]; then
             exit 0
           fi
           if [ "${REUSE_RESULT}" = 'true' ] && [ "${STATIC_RESULT}" = 'skipped' ] && \
@@ -842,7 +885,7 @@ jobs:
         run: pnpm build
 
       - name: Run E2E tests
-        run: pnpm test:e2e
+        run: pnpm exec playwright test
 
       # continue-on-error because the step exists to collect evidence, and collecting evidence must
       # not be what decides the release: it runs on always(), so a transient artifact-service error
@@ -861,11 +904,12 @@ jobs:
 
   notify-auto-tag:
     name: Notify Auto Tag
-    needs: [checks, security, e2e-detect, e2e]
+    needs: [checks, security, e2e-detect, e2e, change-scope]
     if: |
       always() &&
       github.event_name == 'push' &&
       github.ref == 'refs/heads/main' &&
+      needs.change-scope.outputs.publish == 'true' &&
       needs.checks.result == 'success' &&
       needs.security.result == 'success' &&
       needs.e2e-detect.result == 'success' &&

package/.github/workflows/publish.yml

@@ -9,7 +9,7 @@ on:
 
 # The jobs holding the publish rights install nothing and run no repository code: a compromised
 # dependency would otherwise publish with valid provenance (joshuafolkken/kit#4633). Every install
-# and every `tsx` run happens in `pack`, which holds no credentials, behind the same hash-verified
+# and every `tsx` run happens in `pack`, which holds no publish credentials, behind the same hash-verified
 # safe-chain scan as CI (joshuafolkken/kit#2982). Its store cache is off: a cache entry another run
 # saved never reaches the tarball the publish jobs receive.
 
@@ -21,12 +21,17 @@ jobs:
     if: startsWith(github.ref, 'refs/tags/v')
     runs-on: ubuntu-latest
     timeout-minutes: 10
+    # `packages: read` lets a published kit that installs @joshuafolkken/kit from GitHub Packages run
+    # the install; it reads packages and publishes none.
     permissions:
       contents: read
+      packages: read
     # One dist-tag for both registries, chosen against npmjs, whose `latest` needs no credentials to
     # read: both receive the same tarball in the same run, so they move in step. `pack` runs outside
     # the `package-publish` queue, so the publish jobs re-check `latest` against its choice (see there).
     outputs:
+      package: ${{ steps.package.outputs.package }}
+      tarball: ${{ steps.package.outputs.tarball }}
       tag: ${{ steps.publish-tag.outputs.tag }}
       version: ${{ steps.publish-tag.outputs.version }}
     steps:
@@ -36,36 +41,52 @@ jobs:
 
       - uses: ./.github/actions/setup-node
 
+      # kit and every kit that publishes to npm run this one file (`josh sync` distributes it), so the
+      # package and tarball names come from package.json rather than being written here.
+      - name: Read package name
+        id: package
+        run: |
+          package=$(node -p "require('./package.json').name")
+          echo "package=$package" >> "$GITHUB_OUTPUT"
+          echo "tarball=${package##*/}.tgz" >> "$GITHUB_OUTPUT"
+
       # 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: |
-          latest=$(cd "$RUNNER_TEMP" && npm view @joshuafolkken/kit dist-tags.latest --registry https://registry.npmjs.org)
+          latest=$(cd "$(mktemp -d)" && npm view "$PACKAGE" dist-tags.latest --registry https://registry.npmjs.org)
           echo "latest=$latest" >> "$GITHUB_OUTPUT"
+        env:
+          PACKAGE: ${{ steps.package.outputs.package }}
 
       - uses: ./.github/actions/setup-pnpm
         with:
           cache: 'false'
+          node-auth-token: ${{ secrets.GITHUB_TOKEN }}
 
       - name: Select publish tag
         id: publish-tag
+        # josh runs the selection through kit's own tsx, which a kit that publishes may not depend on;
+        # `--silent` keeps pnpm's script echo out of the captured tag.
         run: |
           version=$(node -p "require('./package.json').version")
-          tag=$(pnpm exec tsx scripts/release/publish-tag-cli.ts "$version" "$LATEST")
+          tag=$(pnpm --silent josh release:tag "$version" "$LATEST")
           echo "tag=$tag" >> "$GITHUB_OUTPUT"
           echo "version=$version" >> "$GITHUB_OUTPUT"
         env:
           LATEST: ${{ steps.registry-latest.outputs.latest }}
 
-      - run: pnpm pack --out "$RUNNER_TEMP/kit.tgz"
+      - run: pnpm pack --out "$RUNNER_TEMP/$TARBALL"
+        env:
+          TARBALL: ${{ steps.package.outputs.tarball }}
 
       # Kept as long as GitHub lets a run be re-run, so re-running a failed publish job still finds
       # the tarball instead of forcing a full re-run that republishes an existing version.
       - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
         with:
-          name: kit-package
-          path: ${{ runner.temp }}/kit.tgz
+          name: npm-package
+          path: ${{ runner.temp }}/${{ steps.package.outputs.tarball }}
           if-no-files-found: error
           retention-days: 30
 
@@ -92,7 +113,7 @@ jobs:
 
       - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
         with:
-          name: kit-package
+          name: npm-package
           path: ${{ runner.temp }}
 
       # `pack` chose `latest` outside this queue, so another tag's run may have moved npmjs' `latest`
@@ -101,27 +122,30 @@ jobs:
       # run publishing in between does not stop this one; a newer one stops the job before it
       # publishes, and re-running all jobs chooses again. `sort -V` ranks a prerelease above its
       # release, which can only stop a valid run, never let a stale one through. `backfill` needs no
-      # check: a later `latest` is never lower than the one `pack` read. The user config is skipped
-      # so the scoped GitHub Packages registry setup-node wrote does not redirect the lookup.
+      # check: a later `latest` is never lower than the one `pack` read. The lookup runs in an empty
+      # directory with the user config skipped: setup-node writes its scoped GitHub Packages registry to
+      # `$RUNNER_TEMP/.npmrc`, which npm reads as the project config from there (joshuafolkken/kit#5376).
       - name: Confirm npm latest is not newer
         if: needs.pack.outputs.tag == 'latest'
         run: |
-          latest=$(cd "$RUNNER_TEMP" && npm view @joshuafolkken/kit dist-tags.latest --registry https://registry.npmjs.org --userconfig /dev/null)
+          latest=$(cd "$(mktemp -d)" && npm view "$PACKAGE" dist-tags.latest --registry https://registry.npmjs.org --userconfig /dev/null)
           if ! printf '%s\n%s\n' "$latest" "$VERSION" | sort -V -C; then
             echo "::error::npm latest moved to $latest, above $VERSION, after pack chose the tag; re-run all jobs"
             exit 1
           fi
         env:
+          PACKAGE: ${{ needs.pack.outputs.package }}
           VERSION: ${{ needs.pack.outputs.version }}
 
       # 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). setup-node's user config carries
       # the GitHub Packages token, so it is kept here.
       - name: Publish to GitHub Packages
-        run: cd "$RUNNER_TEMP" && npm publish kit.tgz --tag "$PUBLISH_TAG" --registry https://npm.pkg.github.com
+        run: cd "$RUNNER_TEMP" && npm publish "$TARBALL" --tag "$PUBLISH_TAG" --registry https://npm.pkg.github.com
         env:
           NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           PUBLISH_TAG: ${{ needs.pack.outputs.tag }}
+          TARBALL: ${{ needs.pack.outputs.tarball }}
 
   publish-npm:
     needs: pack
@@ -145,26 +169,32 @@ jobs:
 
       - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
         with:
-          name: kit-package
+          name: npm-package
           path: ${{ runner.temp }}
 
       # The same check as publish-github's, for the same reason.
       - name: Confirm npm latest is not newer
         if: needs.pack.outputs.tag == 'latest'
         run: |
-          latest=$(cd "$RUNNER_TEMP" && npm view @joshuafolkken/kit dist-tags.latest --registry https://registry.npmjs.org --userconfig /dev/null)
+          latest=$(cd "$(mktemp -d)" && npm view "$PACKAGE" dist-tags.latest --registry https://registry.npmjs.org --userconfig /dev/null)
           if ! printf '%s\n%s\n' "$latest" "$VERSION" | sort -V -C; then
             echo "::error::npm latest moved to $latest, above $VERSION, after pack chose the tag; re-run all jobs"
             exit 1
           fi
         env:
+          PACKAGE: ${{ needs.pack.outputs.package }}
           VERSION: ${{ needs.pack.outputs.version }}
 
       - name: Publish to npm
-        run: cd "$RUNNER_TEMP" && npm publish kit.tgz --access public --tag "$PUBLISH_TAG" --registry https://registry.npmjs.org --userconfig /dev/null
+        run: cd "$RUNNER_TEMP" && npm publish "$TARBALL" --access public --tag "$PUBLISH_TAG" --registry https://registry.npmjs.org --userconfig /dev/null
         env:
           PUBLISH_TAG: ${{ needs.pack.outputs.tag }}
+          TARBALL: ${{ needs.pack.outputs.tarball }}
 
+  # kit's production.yml skips auto-tag's dispatch, so this call is kit's only production update. A
+  # consumer also gets that dispatch, so the tag is merged twice; the second merge is a no-op queued
+  # behind the first in `production-update`. Left without a condition because create-release needs this job,
+  # and a skipped need would skip the consumer's release too.
   update-production:
     needs: [publish-github, publish-npm]
     permissions:
@@ -189,14 +219,27 @@ jobs:
           fetch-depth: 0
           persist-credentials: false
 
-      - uses: ./.github/actions/setup-node
+      # A repository `josh sync` gave the `GitHub Release` workflow gets its release there, once this
+      # workflow has succeeded; opening it here as well would race that run. kit has none, so its
+      # release is opened here.
+      - name: Check for the GitHub Release workflow
+        id: owner
+        run: |
+          if [ ! -f .github/workflows/github-release.yml ]; then
+            echo "release=true" >> "$GITHUB_OUTPUT"
+          fi
 
-      - uses: ./.github/actions/setup-pnpm
+      - if: steps.owner.outputs.release == 'true'
+        uses: ./.github/actions/setup-node
+
+      - if: steps.owner.outputs.release == 'true'
+        uses: ./.github/actions/setup-pnpm
         with:
           cache: 'false'
 
       # Tags through v1.887.0 predate automatic GitHub Releases and must not block the first new one.
       - name: Publish GitHub Release
+        if: steps.owner.outputs.release == 'true'
         run: pnpm josh release:github
         env:
           GH_TOKEN: ${{ github.token }}

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

@@ -17,8 +17,24 @@ concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}${{ github.event_name == 'push' && format('-{0}', github.sha) || '' }}
   cancel-in-progress: true
 jobs:
+  change-scope:
+    runs-on: ubuntu-latest
+    timeout-minutes: 3
+    permissions:
+      contents: read
+    outputs:
+      runtime: ${{ steps.scope.outputs.runtime }}
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - uses: ./.github/actions/change-scope
+        id: scope
   sonarqube:
     name: SonarQube
+    needs: change-scope
+    if: ${{ always() && (needs.change-scope.result != 'success' || needs.change-scope.outputs.runtime != 'false') }}
     permissions:
       contents: read
       packages: read
@@ -36,6 +52,9 @@ jobs:
       - name: Skip SonarQube Scan
         if: env.SONAR_TOKEN == ''
         run: echo "SonarQube scan skipped because SONAR_TOKEN is not set."
+      - name: Require change classification
+        if: needs.change-scope.result != 'success'
+        run: exit 1
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         if: env.SONAR_TOKEN != ''
         with:
@@ -66,9 +85,17 @@ jobs:
         run: |
           version=$(jq -r '.version // empty' package.json)
           echo "args=${version:+-Dsonar.projectVersion=$version}" >> "$GITHUB_OUTPUT"
+      # Keep analyzer downloads across source changes; a workflow change (including the pinned
+      # scanner action version) rotates the cache key.
+      - name: Cache SonarQube scanner
+        if: env.SONAR_TOKEN != ''
+        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
+        with:
+          path: ~/.sonar/cache
+          key: ${{ runner.os }}-sonar-${{ hashFiles('.github/workflows/sonar-qube.yml') }}
       - name: SonarQube Scan
         if: env.SONAR_TOKEN != ''
-        uses: SonarSource/sonarqube-scan-action@d209202bc7d53ff1cc128f7f907dac145c9d6ae9 # v8.3.0
+        uses: SonarSource/sonarqube-scan-action@e805d875275f728fac1885b413934be6d7c63f65 # v8.4.1
         with:
           # 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

package/.prettierignore

@@ -8,6 +8,8 @@
 .claude/**/*.md
 # Generated one-row-per-command table, pinned by its generator's test; padding would multiply its size (#4162)
 docs/josh-command-catalog.md
+# Append-only ledgers josh writes line by line; Prettier reads a `__` in a recorded path as emphasis (#5808)
+.josh/observations/
 
 # Package Managers
 package-lock.json

package/AGENTS.md

@@ -1,6 +1,5 @@
 # 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.
+> **All rules for this repository live in [`CLAUDE.md`](./CLAUDE.md). Read it in full before any work.**
 
 **Codex runs the same hooks from `.codex/hooks.json`** (generated from `.claude/settings.json`) — apply any rule whose hook output you do not see yourself, per `prompts/collaboration-workflow/principles.md` → "Claude Code 以外のエージェントでの読み替え". Do not copy rules back into this file.

package/CLAUDE.md

@@ -9,7 +9,7 @@
 - **No clones — single-source, even across package boundaries.** Duplicate non-trivial logic only after presenting the alternative and getting explicit approval. `prompts/collaboration-workflow/principles.md` → "no-clones".
 - **Design for elegance and simplicity first.** Before adding a hook, guard, rule or abstraction, ask whether fixing the cause makes it unnecessary. `prompts/collaboration-workflow/principles.md` → "elegant-design"; conflicting quality goals, or a remedy for defects → "quality-priority".
 - **Write concise prose: conditions and actions only.** `prompts/collaboration-workflow/principles.md` → "concise-prose".
-- **Distinguish consultation from execution.** A question or goal statement asks for analysis only — act on an explicit imperative or a workflow keyword. `prompts/collaboration-workflow/principles.md` → "consult-vs-execute".
+- **Distinguish consultation from execution.** Main-session scope and implementation handoff: `prompts/collaboration-workflow/principles.md` → "consult-vs-execute".
 - **Route distributed-doc / config changes upstream to kit.** In a consumer repo never edit kit-distributed docs/config; in kit you are the source. `prompts/collaboration-workflow/principles.md` → "upstream-to-kit".
 - **Latest-first, fix forward — pin back only as a last resort.** `prompts/collaboration-workflow/principles.md` → "latest-first".
 - **Output language follows `JOSH_SESSION_LANG`** (default `ja`) for session output and artifact prose; English for Issue/PR titles, code comments, test titles, commit messages and script strings. `prompts/collaboration-workflow/overview.md`.
@@ -18,11 +18,11 @@
 
 ### Decision autonomy
 
-Classify each decision point and act; stop **only** where the user's judgment is genuinely needed. `prompts/collaboration-workflow/operating-rules.md` → "decision-autonomy".
+Classify each decision point and act; stop **only** where the user's judgment is genuinely needed. `prompts/collaboration-workflow/operating-rules.md` → "decision-autonomy". The stops left to a person, each with why: `scripts/issue/issue-human-stops.ts`.
 
 - **Tier A — reversible implementation / design choices** (library, naming, layout, tests, refactor shape; placing a filed Issue into an epic; self-correction). Pick the clearly-better option, proceed, log it. Unasked filing: unattended only (`observation-filing.md`).
 - **Tier B — genuine toss-up.** The only tier that stops — ask with the candidates and trade-offs.
-- **Tier C — irreversible / shared-state / out-of-scope actions** (merge, branch delete, force push, destructive ops, repo settings, out-of-scope work, `devEngines` / overrides edits): explicit user instruction only, never auto-decided. Deleting a git-tracked file is reversible, so it is not a destructive op — inspect the target first and surface any contradiction. After a dependency-update command, load the `dependency-update` skill before reporting on the pins.
+- **Tier C — irreversible / shared-state / out-of-scope actions** (merge, branch delete, force push, destructive ops, repo settings, out-of-scope work, bypassing a check, `devEngines` / overrides edits): explicit user instruction only, never auto-decided. Deleting a git-tracked file is reversible, so it is not a destructive op — inspect the target first and surface any contradiction. After a dependency-update command, load the `dependency-update` skill before reporting on the pins.
 
 Log auto-decisions: an Issue comment in an Issue workflow, else a one-line "Auto-decided: `<choice>` over `<alt>` because `<reason>`" in the reply.
 
@@ -32,12 +32,12 @@ Naming, exports, file names and content rules are enforced by `eslint/rules/`; t
 
 ### Quality limits
 
-- Function complexity ≤5 · nesting ≤2 · function ≤25 lines · file ≤300 lines · params ≤4 · statements per function ≤10 · cognitive complexity ≤4 — line counts are code lines, not physical lines; test functions allow 35 code lines.
+- <!-- lint: quality-limits -->Function complexity ≤5 · nesting ≤2 · function ≤25 lines · file ≤300 lines · params ≤4 · statements per function ≤10 · cognitive complexity ≤4 — line counts are code lines, not physical lines; test functions allow 35 code lines<!-- /lint -->.
 - No magic numbers beyond `0`, `1`, `-1` · no `any` · restricted `as` · explicit param and return types · single short early return → one-liner `if (x) return y`.
 
 ## Package-First Development
 
-Before building a feature, run `pnpm josh pkg:scout <keywords>`: `clear` → use it (Tier A), `close` → ask (Tier B).
+Before building a feature, run `pnpm josh pkg:scout <keywords>` and act on its `Tier:` line (A: use it, B: ask).
 
 ## Code Change Rules
 
@@ -57,15 +57,15 @@ Before every `git commit`, a subagent runs `/code-review` per `prompts/review.md
 
 ## Git Rules
 
-Commits, the index and shared state (merge, branch delete, force push) only on explicit instruction, through `pnpm josh git` / `pnpm josh pr`; run `git status` live before any tree assumption: `prompts/collaboration-workflow/operating-rules.md` → "git-rules".
+Commits, the index and shared state (merge, branch delete, force push) only on explicit instruction, through `pnpm josh git` / `pnpm josh pr`; run `pnpm josh tree:status` live before any tree assumption: `prompts/collaboration-workflow/operating-rules.md` → "git-rules".
 
 ## Collaboration Workflow
 
-The issue-driven flow: `prompts/collaboration-workflow.md`.
+The issue-driven flow: `prompts/collaboration-workflow/`.
 
 ### Shorthand Commands
 
-`kickoff`, `fullrun`, `prrun`, `halfrun`, `backlogrun` (with `#N` / `new`) are procedures in the `workflow-commands` skill — read it before any part of a command, including the first `gh` call. Read the `epic-commands` skill before any `josh epic:*` command, before writing an epic that tracks a child in another repository, when `epic:bundle` places a filed issue, and when recording a decision on a `needs-decision` child.
+`kickoff`, `fullrun`, `prrun`, `halfrun`, `backlogrun` (with `#N` / `new`) are procedures in the `workflow-commands` skill — read it before any part of a command, including the first `gh` call. The `epic-commands` skill: before `josh epic:*`, a cross-repository epic child or a `needs-decision` decision, and when `epic:bundle` places a filed issue.
 
 #### Explicit invocation required (MANDATORY)
 

package/GEMINI.md

@@ -1,7 +1,6 @@
 # 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.
+> **All rules for this repository live in [`CLAUDE.md`](./CLAUDE.md). Read it in full before any work.**
 
 @CLAUDE.md
 

package/README.md

@@ -67,4 +67,4 @@ Check first: [what kit changes in your project](./docs/how-to/add-kit.md#what-ki
 
 [How-to](./docs/how-to.md) · [All docs](./docs/overview.md)
 
-[app-kit](https://github.com/joshuafolkken/app-kit) · [game-kit](https://github.com/joshuafolkken/game-kit) · [Releases](https://github.com/joshuafolkken/kit/releases) · [Contributing](./docs/maintainers/README.md)
+[app-kit](https://github.com/joshuafolkken/app-kit) · [game-kit](https://github.com/joshuafolkken/game-kit) · [Releases](https://github.com/joshuafolkken/kit/releases) · [Contributing](./CONTRIBUTING.md)