@joshuafolkken/kit 1.2116.0 → 1.3000.0

package/SECURITY.md

@@ -25,7 +25,7 @@ The `files` field of `package.json` decides what the published `@joshuafolkken/k
 **Code that runs on your machine and in CI**
 
 - `dist/`, `scripts/` — the `josh` command and the scripts behind it. They read and write files in your repository, run `git`, `gh` and `pnpm`, and call the GitHub API and, when configured, the Telegram API.
-- `.claude/settings.json` — Claude Code hooks that run `pnpm josh …` commands on session start, on each prompt, before and after tool calls and on stop, plus a deny list for staging, committing, merging, force pushes, branch deletions and reads of `.env`, `.env.*` (except the tracked `.env.example` and `.env.test`) and `.dev.vars`. The deny list and the `pretool-guard` hook are a guardrail, not a sandbox: another spelling of the same action (a git command inside `bash -c '…'`, a script that opens the file itself) gets through, and an instruction planted in text the agent reads can run with your permissions; the section linked below describes these limits and what keeps them small. It allows `Bash(*)` and ships no `permissions.defaultMode`, which Claude Code v2.1.257 and later ignore in a project settings file; the distributed `.vscode/settings.json` turns the VS Code extension's prompts off — an opt-out default, described in [`docs/init.md` → "Claude Code permission mode"](https://github.com/joshuafolkken/kit/blob/main/docs/init.md#claude-code-permission-mode).
+- `.claude/settings.json` — Claude Code hooks that run `pnpm josh …` commands on session start, on each prompt, before and after tool calls and on stop, plus a deny list for staging, committing, merging, force pushes, branch deletions and reads of `.env`, `.env.*` (except the tracked `.env.example` and `.env.test`), `.dev.vars` and the credential files `~/.config/gh/**`, `~/.codex/auth.json`, `~/.netrc` and `~/.ssh/**`; the `pretool-guard` hook refuses the same reads through a shell reader, and of `~/.curlrc` and `~/.npmrc` too. The deny list and the `pretool-guard` hook are a guardrail, not a sandbox: another spelling of the same action (a git command inside `bash -c '…'`, a script that opens the file itself) gets through, and an instruction planted in text the agent reads can run with your permissions; the section linked below describes these limits and what keeps them small. It allows `Bash(*)` and ships no `permissions.defaultMode`, which Claude Code v2.1.257 and later ignore in a project settings file; the distributed `.vscode/settings.json` turns the VS Code extension's prompts off — an opt-out default, described in [`docs/init.md` → "Claude Code permission mode"](https://github.com/joshuafolkken/kit/blob/main/docs/init.md#claude-code-permission-mode).
 - `.codex/` — the same hooks for Codex (`hooks.json`) and its project settings (`config.toml`).
 - `.github/` — GitHub Actions workflows (CI, tagging, pull request classification, Dependabot auto-merge, SonarQube and production), composite actions, `dependabot.yml`, the pull request template and the release-notes config. `josh sync` overwrites the distributed workflows; their action references are pinned to commit SHAs. kit's own `publish.yml` ships in the package but is never copied into a project.
 - `lefthook/` — Git hook presets: lint before commit, checks before push.
@@ -61,6 +61,14 @@ sh install-safe-chain.sh
 
 Stop if `shasum` does not print `install-safe-chain.sh: OK`. Then restart your terminal; if the warning still appears, run `safe-chain setup` and restart it again.
 
+The shell integration wraps every `pnpm` call, `pnpm josh …` included, which costs about 0.25 s per call and adds up across an agent's many josh runs. `pnpm josh` installs nothing, and the `pnpm` calls josh makes itself are child processes that never pass through a shell function, so exempting it loses no protection. In `~/.zshrc`, after the line safe-chain added:
+
+```sh
+pnpm() { [ "$1" = josh ] && { command pnpm "$@"; return; }; wrapSafeChainCommand pnpm "$@"; }
+```
+
+`pnpm install`, `pnpm add` and every other subcommand still go through safe-chain.
+
 ## Secrets
 
 kit never stores a secret in a file it ships or commits. The ones it uses:
@@ -71,6 +79,8 @@ kit never stores a secret in a file it ships or commits. The ones it uses:
 - `GH_TOKEN` — authenticates `gh` in CI and cloud sessions, where `gh auth login` is not available.
 - `NODE_AUTH_TOKEN` — the GitHub Packages credential, only for projects that still install kit from there ([authentication.md](https://github.com/joshuafolkken/kit/blob/main/docs/authentication.md)). The `prepare` script above reads it.
 
+An unattended agent runs with `Bash(*)`, so an instruction planted in text it reads could send one of these off the machine. The `egress` guard row (`scripts/rules/egress-guard.ts`) refuses an agent's `Bash` call that reaches another host (`curl`, `wget`, `nc`, `ssh`, `scp`, a remote `rsync`, a network call in an inline `node -e` / `python -c` script, `gh` sent to a host other than github.com) or prints a credential (`gh auth token`, `printenv`, a bare `env`, a `*TOKEN*` / `*SECRET*` / `*KEY*` variable, a keychain secret through `security find-generic-password` / `find-internet-password` / `dump-keychain` / `export` or `security -i`), nested in `bash -c`, `eval` or `$(…)` as well. The same row refuses a direct `gh` write against github.com: a subcommand other than `browse`, `search`, `status` or a read action (`view`, `list`, `diff`, `checks`, …), a `gh api graphql` call that merges a pull request or writes to another owner's repository, and any other `gh api` call with a non-`GET` method or a field flag (`-f`, `-F`, `--input`) (`scripts/rules/shell-permissions.ts` → `is_gh_write`). Writes go through the `pnpm josh` routes instead — `issue:file`, `issue:comment`, `issue:priority`, `git`, `pr` — or the user runs them. `gh` reads against github.com, `git` and `pnpm` stay allowed. `.claude/settings.json` denies `curl`, `wget`, `nc`, `gh auth token` and `printenv` as a static backstop for when the hook does not run, so a plain `curl` / `wget` is refused even to localhost; the hook's localhost / GitHub allowance covers only the spellings that deny list does not reach (a nested or wrapped call).
+
 ## MCP External Endpoints
 
 This project ships `.mcp.json` which connects to external MCP servers at runtime (e.g. `https://mcp.svelte.dev/mcp`). These servers are treated as trusted third-party services. Consumers should be aware that:

package/cspell/index.yaml

@@ -47,6 +47,11 @@ ignorePaths:
   #   - '**/*.min.js'
   #   - '**/*.svg'
 words:
+  - curlrc
+  - mktemp
+  # safe-chain's release asset name for its static Linux binary, which the distributed
+  # `setup-pnpm` action fetches (joshuafolkken/kit#6849).
+  - linuxstatic
   # pnpm's `.pnpmfile.mjs` hook file that strips the safe-chain preinstall at pack time
   # (joshuafolkken/kit#2693). Distributed, because `josh init` / `josh sync` copy that file, which
   # names itself, into a published consumer (joshuafolkken/kit#3110).
@@ -61,6 +66,9 @@ words:
   # The process-listing command `epicrun.md` names among the traces a stopped delegated unit leaves
   # (joshuafolkken/kit#1212). Distributed, because the skill that names it is copied by `josh sync`.
   - pgrep
+  # The home credential file the `protected-file` guard refuses a read of (joshuafolkken/kit#6003).
+  # Distributed, because the package ships `scripts/rules/`, whose guard reason names it.
+  - netrc
   # The shell variable naming the parent process, which `josh run:carry --owner "$PPID"` passes so the
   # record can name the long-lived session spending the budget (joshuafolkken/kit#1722). Distributed,
   # because `backlogrun.md` types that command and `josh sync` copies that skill.
@@ -132,6 +140,9 @@ words:
   - newbot
   - userinfobot
   - lefthook
+  # In kit's distributed `pnpm-workspace.yaml`, inside a region `josh sync` drops before writing it
+  # (joshuafolkken/kit#5500); the cspell guard reads the file as kit ships it.
+  - minimatch
   - mischeck
   - multicriteria
   - narratively

package/dist/.inputs-verified.json

@@ -0,0 +1 @@
+{"digest":"5d0af563bfd68dd88cb498884bb72e25cf1df6f038dc3078bd93eac35b808781","signatures":{"scripts/build/build-hooks.ts":"1794446491904.79:12610","scripts/build/build-bin.ts":"1794446491904.79:1594",".npmrc":"1794446491874.3955:51","eslint.config.js":"1794446491884.6775:4805","eslint/base.js":"1794446491884.8599:16317","eslint/checkout-rooted-parser.js":"1794446491884.8599:1956","eslint/config-fingerprint.js":"1794446491884.8599:10894","eslint/rules/code-quality.js":"1794446491884.8599:11312","eslint/rules/comment-why-only.js":"1794446491885.8142:4882","eslint/rules/early-return-one-liner.js":"1794446491885.8142:4326","eslint/rules/english-only-prose.js":"1794446491885.8142:5509","eslint/rules/formatting.js":"1794446491885.8142:1218","eslint/rules/import.js":"1794446491885.8142:3293","eslint/rules/namespace-object-export.js":"1794446491885.8142:4219","eslint/rules/naming-convention.js":"1794446491885.8142:3526","eslint/rules/promise.js":"1794446491885.8142:1349","eslint/rules/sonarjs.js":"1794446491885.8142:2032","eslint/rules/test-filename.js":"1794446491885.8142:5790","eslint/rules/test-helper-bans.js":"1794446491885.8142:1843","eslint/rules/typescript.js":"1794446491885.8142:6487","eslint/rules/unicorn.js":"1794446491885.8142:13756","eslint/untyped-environment.js":"1794446491885.8142:1074","eslint/untyped.js":"1794446491885.8142:2701","eslint/vanilla.js":"1794446491885.8142:72","node_modules/.modules.yaml":"1794446505109.9824:37097","package.json":"1794446491887.3635:7556","pnpm-lock.yaml":"1794446491887.3877:182629","pnpm-workspace.yaml":"1794446491887.3877:3219","tsconfig.json":"1794446492113.461:366","tsconfig.sonar.json":"1794446492113.461:427","tsconfig/base.json":"1794446492113.461:1889","scripts/josh/josh.ts":"1794446491979.3328:2970","scripts/josh/josh-read-only.ts":"1794446491978.3335:2500","scripts/doctor/doctor-consumer.ts":"1794446491914.3882:6198","scripts/josh/command-usage.ts":"1794446491976.034:3040","scripts/josh/josh-gh-usage.ts":"1794446491978.3335:2146","scripts/josh/josh-logic.ts":"1794446491978.3335:10810","scripts/josh/josh-command-map.ts":"1794446491976.3347:1523","scripts/josh/josh-aliases.ts":"1794446491976.3347:2961","scripts/josh/run-github-prerequisite.ts":"1794446491979.3328:889","scripts/version/kit-descriptor.ts":"1794446492098.4443:535","scripts/josh/josh-composite-arguments.ts":"1794446491978.3335:2438","scripts/josh/josh-in-process.ts":"1794446491978.3335:4353","scripts/issue/issue-number-shape.ts":"1794446491968.3394:2067","scripts/lib/timeouts.ts":"1794446492002.319:3134","scripts/lib/json-value.ts":"1794446492001.3198:2003","scripts/lib/read-file.ts":"1794446492001.3198:1581","scripts/gh/gh-core-rate-limit.ts":"1794446491939.315:5185","scripts/gh/gh-request-tally.ts":"1794446491939.315:4736","scripts/gh/gh-usage-event.ts":"1794446491939.3567:2864","scripts/gh/git-gh-exec.ts":"1794446491940.3562:23236","scripts/josh/josh-environment-file.ts":"1794446491978.3335:2898","scripts/build/local-bin.ts":"1794446491904.79:5938","scripts/lib/schemas.ts":"1794446492001.3198:2354","scripts/lib/spawn-exit.ts":"1794446492001.3198:1787","scripts/gate/core-budget.ts":"1794446491932.3745:18044","scripts/hooks/hook-lap.ts":"1794446491953.6292:2109","scripts/josh/command-suggest.ts":"1794446491976.034:2206","scripts/lib/package-manifest.ts":"1794446492001.3198:3257","scripts/git/git-spawn-sync.ts":"1794446491948.3513:3238","scripts/josh/kit-only.ts":"1794446491979.3328:1323","scripts/josh/package-directory.ts":"1794446491979.3328:854","scripts/josh/josh-commands-workflow.ts":"1794446491977.334:12902","scripts/josh/josh-commands-ai.ts":"1794446491976.3347:26182","scripts/josh/josh-commands-clone.ts":"1794446491976.3347:569","scripts/josh/josh-commands-development.ts":"1794446491976.3347:11556","scripts/josh/josh-commands-hooks.ts":"1794446491976.3347:2542","scripts/josh/josh-commands-lint.ts":"1794446491977.334:3560","scripts/josh/josh-commands-maintenance.ts":"1794446491977.334:10101","scripts/josh/josh-commands-project.ts":"1794446491977.334:9012","scripts/josh/josh-commands-versioning.ts":"1794446491977.334:4557","scripts/discovery/repo-origin.ts":"1794446491913.742:7673","scripts/gh/gh-usage-log.ts":"1794446491939.3567:1876","scripts/lib/error-message.ts":"1794446492001.2554:879","scripts/run/carry/run-carry.ts":"1794446492051.29:29907","scripts/gh/git-gh-spawn-width.ts":"1794446491944.3538:360","scripts/josh/agent-session-environment.ts":"1794446491976.034:10693","scripts/lib/bounded-pool.ts":"1794446492001.2554:5461","scripts/lib/token-shape.ts":"1794446492002.319:3806","scripts/gh/gh-call-kind.ts":"1794446491939.315:3275","scripts/gh/git-gh-check.ts":"1794446491939.3567:611","scripts/gh/git-gh-failure.ts":"1794446491940.3562:6068","scripts/gh/git-gh-retry.ts":"1794446491944.3538:6409","scripts/git/git-execa-error.ts":"1794446491947.7063:2072","scripts/josh/josh-command-types.ts":"1794446491976.3347:16683","scripts/lib/pnpm-reach.ts":"1794446492001.3198:1380","scripts/gate/machine-capacity.ts":"1794446491935.3591:16281","scripts/run/ship/run-ship-lap.ts":"1794446492070.379:5345","ports/index.js":"1794446491888.4102:10170","scripts/lib/ancestor-directories.ts":"1794446492001.2554:1368","scripts/josh/platform-temporary.ts":"1794446491979.3328:3312","scripts/josh/process-identity.ts":"1794446491979.3328:16732","scripts/josh/stamp-file.ts":"1794446491980.3323:10331","scripts/lib/poll.ts":"1794446492001.3198:7949","scripts/test/unit-worker-share.ts":"1794446492093.265:8988","scripts/gate/busy-average.ts":"1794446491932.3745:4119","scripts/gate/core-admission.ts":"1794446491932.3745:17116","scripts/gate/core-budget-timing.ts":"1794446491932.3745:1879","scripts/gate/core-reservation.ts":"1794446491932.3745:2994","scripts/gate/core-wait.ts":"1794446491933.3604:9281","scripts/gate/core-wait-record.ts":"1794446491933.3604:1703","scripts/gate/core-weights.ts":"1794446491933.3604:5185","scripts/gate/held-mark.ts":"1794446491935.3591:2127","scripts/josh/durable-state.ts":"1794446491976.034:3509","scripts/run/carry/run-carry-conversation.ts":"1794446492050.6802:4883","scripts/git/git-location-environment.ts":"1794446491947.7063:2947","scripts/git/constants.ts":"1794446491947.7063:1955","scripts/lib/atomic-write.ts":"1794446492001.2554:2344","scripts/test/unit-run-marker.ts":"1794446492092.2656:8718","scripts/gate/core-priority.ts":"1794446491932.3745:1583","scripts/lane/lane-paths.ts":"1794446491989.327:7268","scripts/lane/lane-ledger-write.ts":"1794446491987.3281:11207","scripts/init/init-paths.ts":"1794446491959.3447:350","scripts/test/unit-lane-count.ts":"1794446492092.2656:3210","scripts/josh/process-owner.ts":"1794446491979.3328:822","scripts/josh/josh-commands-ship.ts":"1794446491977.334:11873","scripts/josh/josh-commands-backlog.ts":"1794446491976.3347:8309","scripts/josh/josh-commands-document.ts":"1794446491976.3347:3482","scripts/josh/josh-commands-epic.ts":"1794446491976.3347:7282","scripts/josh/josh-commands-issue.ts":"1794446491977.334:9318","scripts/josh/josh-commands-review.ts":"1794446491977.334:8553","scripts/josh/josh-commands-run.ts":"1794446491977.334:12722","scripts/josh/josh-commands-test-check.ts":"1794446491977.334:2953","scripts/gate/gate-plan.ts":"1794446491934.3596:21362","scripts/josh/josh-commands-agent-hooks.ts":"1794446491976.3347:5184","scripts/josh/durable-state-root.ts":"1794446491976.034:2442","scripts/cost-runtime/own-session.ts":"1794446491910.3955:2644","scripts/cost-runtime/cost-transcript.ts":"1794446491910.3955:24340","scripts/git/git-common-directory.ts":"1794446491947.7063:4650","scripts/josh/durable-state-migrate.ts":"1794446491976.034:4274","scripts/lane/lane-ledger-kind.ts":"1794446491986.3286:904","scripts/lane/lane-state-record.ts":"1794446491996.3228:2850","scripts/discovery/git-directory.ts":"1794446491913.742:2654","scripts/rules/gh-api.ts":"1794446492025.3054:8116","scripts/git/parse-json-array.ts":"1794446491950.35:3885","scripts/cost-runtime/cost-usage.ts":"1794446491910.3955:11106","scripts/josh/josh-commands-issue-write.ts":"1794446491976.3347:13582","scripts/josh/josh-commands-progress.ts":"1794446491977.334:5380","scripts/josh/josh-commands-pause.ts":"1794446491977.334:2882","scripts/josh/josh-commands-prime.ts":"1794446491977.334:1187","scripts/gate/gate-labels.ts":"1794446491933.3604:2268","scripts/josh/josh-verdict.ts":"1794446491979.3328:7342","scripts/gate/gate-checks.ts":"1794446491933.3604:9327","scripts/git/repository-lock.ts":"1794446491950.35:6188","scripts/agent/agent-provider.ts":"1794446491890.629:5819","scripts/git/git-command.ts":"1794446491947.7063:19780","scripts/run/run-invocation.ts":"1794446492064.2822:11258","scripts/run/carry/run-carry-added.ts":"1794446492050.6802:2257","scripts/run/carry/run-carry-change.ts":"1794446492050.6802:2966","scripts/rules/git-argv.ts":"1794446492025.3054:8430","scripts/time-runtime/time-instant.ts":"1794446492095.2637:1048","scripts/issue/issue-body-keys.ts":"1794446491964.3418:8771","scripts/run/carry/run-carry-streak.ts":"1794446492050.6802:4739","scripts/lib/status-icons.ts":"1794446492001.3198:1614","scripts/git/git-spawn.ts":"1794446491949.3508:6778","scripts/lib/cli-flags.ts":"1794446492001.2554:8663","scripts/git/git-diff-reads.ts":"1794446491947.7063:13924","scripts/git/git-pre-push-hook.ts":"1794446491948.3513:5796","scripts/git/git-push-transport.ts":"1794446491948.3513:5219","scripts/josh/session-language.ts":"1794446491980.3323:1492","scripts/git/git-ssh-keepalive.ts":"1794446491949.3508:4447"}}

package/dist/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. `node_modules/@joshuafolkken/kit/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. `node_modules/@joshuafolkken/kit/prompts/collaboration-workflow/principles.md` → "elegant-design"; conflicting quality goals, or a remedy for defects → "quality-priority".
 - **Write concise prose: conditions and actions only.** `node_modules/@joshuafolkken/kit/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. `node_modules/@joshuafolkken/kit/prompts/collaboration-workflow/principles.md` → "consult-vs-execute".
+- **Distinguish consultation from execution.** Main-session scope and implementation handoff: `node_modules/@joshuafolkken/kit/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. `node_modules/@joshuafolkken/kit/prompts/collaboration-workflow/principles.md` → "upstream-to-kit".
 - **Latest-first, fix forward — pin back only as a last resort.** `node_modules/@joshuafolkken/kit/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. `node_modules/@joshuafolkken/kit/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. `node_modules/@joshuafolkken/kit/prompts/collaboration-workflow/operating-rules.md` → "decision-autonomy".
+Classify each decision point and act; stop **only** where the user's judgment is genuinely needed. `node_modules/@joshuafolkken/kit/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 `node_modules/@jos
 
 ### 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 `node_modules/@jos
 
 ## 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: `node_modules/@joshuafolkken/kit/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: `node_modules/@joshuafolkken/kit/prompts/collaboration-workflow/operating-rules.md` → "git-rules".
 
 ## Collaboration Workflow
 
-The issue-driven flow: `node_modules/@joshuafolkken/kit/prompts/collaboration-workflow.md`.
+The issue-driven flow: `node_modules/@joshuafolkken/kit/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/dist/commands/adopt.js

@@ -0,0 +1,222 @@
+#!/usr/bin/env tsx
+import {
+  propagate_run,
+  propagate_steps
+} from "./chunk-7CHCZBNF.js";
+import "./chunk-P7FPXAHP.js";
+import {
+  adopt_toolkits
+} from "./chunk-EFHSCUFN.js";
+import {
+  self_sync_guard
+} from "./chunk-OGNTJ5JB.js";
+import "./chunk-SADJPNDB.js";
+import "./chunk-U2UH4VM4.js";
+import "./chunk-WGULS5DA.js";
+import "./chunk-HH2KDLTP.js";
+import "./chunk-CRNPPKP2.js";
+import {
+  KIT_PACKAGE_NAME
+} from "./chunk-PBOS7MTW.js";
+import "./chunk-FNQW6NY7.js";
+import "./chunk-65E4OZJ7.js";
+import "./chunk-XXNEY4B3.js";
+import "./chunk-EWVR5AEX.js";
+import "./chunk-C6QSVO5K.js";
+import "./chunk-ZBFNQUY7.js";
+import "./chunk-34DND4BA.js";
+import "./chunk-QQBMVC5W.js";
+import "./chunk-X7PN54LZ.js";
+import {
+  repo_discovery
+} from "./chunk-MDKDJF2K.js";
+import "./chunk-HQ2HSZBN.js";
+import "./chunk-3NWAGIA6.js";
+import {
+  cli_flags
+} from "./chunk-2FE3C4PH.js";
+import "./chunk-TBIX5FRN.js";
+import "./chunk-IGD6QJPH.js";
+import "./chunk-FFHEGWPK.js";
+import "./chunk-R6QE5VJG.js";
+import {
+  repo_origin
+} from "./chunk-4ZHWTTQW.js";
+import "./chunk-RDRN56E4.js";
+import "./chunk-XDF25GSU.js";
+import "./chunk-EBVS2LKX.js";
+import "./chunk-AQ3PMSXK.js";
+import "./chunk-QVOFWFWC.js";
+import "./chunk-G6BXCWPH.js";
+import "./chunk-CDY4NFQG.js";
+import "./chunk-OKYFQJW3.js";
+import "./chunk-HHBC6QZE.js";
+import "./chunk-QWWTC3XR.js";
+import "./chunk-ILGPZ47M.js";
+import {
+  PROJECT_ROOT
+} from "./chunk-3CCGKX7Y.js";
+import "./chunk-KSR23NYN.js";
+import "./chunk-F7XLEK55.js";
+import "./chunk-UGCUSRZF.js";
+import "./chunk-AKQYYHP2.js";
+import "./chunk-CJKPF5DJ.js";
+import "./chunk-RBU2NKHF.js";
+import "./chunk-NKKH3PBE.js";
+import "./chunk-B77ZMVHS.js";
+import "./chunk-B5GXZK3E.js";
+import "./chunk-KTLR4Y32.js";
+import "./chunk-ZNX2LJCQ.js";
+import "./chunk-VJE3RJAX.js";
+import "./chunk-WPAQUMHC.js";
+import "./chunk-HIU2WXB6.js";
+
+// scripts/adopt/adopt.ts
+import { dirname as __josh_dirname } from "node:path";
+import { fileURLToPath as __josh_file_path } from "node:url";
+import { fileURLToPath } from "node:url";
+
+// scripts/adopt/adopt-logic.ts
+var ADOPT_ORIGIN = "Opened by `josh adopt` in this repository, which also ran `josh latest` \u2014 the other dependencies and the pnpm pin are updated alongside.";
+var INCOMPLETE_HEADLINE = "Refusing to adopt: these declared toolkits would fall out of the plan, and the run would sync the rest without them.";
+var INCOMPLETE_EFFECT = "The toolkits overlay files derived from kit's own (see docs/maintainers/sync-rationale.md), so syncing kit without one rewrites that overlay back to kit's original \u2014 a wrong diff wearing kit's face.";
+var MISPLACED_CAUSE = "declared under `dependencies`; the upgrade installs with `pnpm add -D` and would relocate it. Move it to `devDependencies`.";
+var ABSENT_CAUSE = "no runnable CLI here; the package or its `node_modules/.bin` shim is missing. Run `pnpm install`.";
+function refuse_inside_kit_repository(project_root) {
+  if (self_sync_guard.read_package_name(project_root) !== KIT_PACKAGE_NAME) return void 0;
+  return [
+    `Refusing to adopt: this is ${KIT_PACKAGE_NAME}'s own repository.`,
+    "Adoption carries a published toolkit inward, so it runs in a repository that consumes one.",
+    "Run it from a consumer project instead."
+  ].join("\n");
+}
+function refuse_without_kit(releases) {
+  if (releases.some((release) => release.package_name === KIT_PACKAGE_NAME)) return void 0;
+  return [
+    `Refusing to adopt: ${KIT_PACKAGE_NAME} is not a direct dev dependency here.`,
+    "The verification gate and the pull request run through `pnpm josh`, which it provides.",
+    `Add it with \`pnpm add -D ${KIT_PACKAGE_NAME}\` and run this again.`
+  ].join("\n");
+}
+function name_causes(package_names, cause) {
+  return package_names.map((package_name) => `  ${package_name} \u2014 ${cause}`);
+}
+function refuse_incomplete_plan(misplaced, unresolved) {
+  const moved = name_causes(misplaced, MISPLACED_CAUSE);
+  const named = [...moved, ...name_causes(unresolved, ABSENT_CAUSE)];
+  if (named.length === 0) return void 0;
+  return [INCOMPLETE_HEADLINE, INCOMPLETE_EFFECT, ...named].join("\n");
+}
+function resolve_self_target(project_root) {
+  const origin_url = repo_discovery.read_origin_url(project_root);
+  if (origin_url === void 0) return void 0;
+  const identity = repo_origin.parse_origin_url(origin_url);
+  if (identity === void 0) return void 0;
+  return { repo: repo_origin.format_identity(identity), path: project_root, state: "ready" };
+}
+function build_plan(releases) {
+  return { releases, origin: ADOPT_ORIGIN };
+}
+var adopt_logic = {
+  ADOPT_ORIGIN,
+  refuse_inside_kit_repository,
+  refuse_without_kit,
+  refuse_incomplete_plan,
+  resolve_self_target,
+  build_plan
+};
+
+// scripts/adopt/adopt.ts
+var __josh_meta = import.meta;
+var __josh_source_url = new URL("../../scripts/adopt/adopt.ts", __josh_meta.url).href;
+var __josh_source_filename = __josh_file_path(__josh_source_url);
+var __josh_source_dirname = __josh_dirname(__josh_source_filename);
+var SUCCESS_EXIT_CODE = 0;
+var FAILURE_EXIT_CODE = 1;
+var ARGV_OFFSET = 2;
+var DRY_RUN_FLAG = "--dry-run";
+var KNOWN_FLAGS = [DRY_RUN_FLAG];
+var DRY_RUN_REASON = "would be adopted";
+var NOTHING_TO_ADOPT = "No @joshuafolkken toolkit is installed here; nothing to adopt.";
+var NO_ORIGIN = "Refusing to adopt: this checkout has no GitHub `origin`, so there is nowhere to open the issue.";
+function parse_options(argv) {
+  const options = { is_dry_run: argv.includes(DRY_RUN_FLAG) };
+  const usage = cli_flags.refuse_unknown_flags(argv, KNOWN_FLAGS, "adopt");
+  return usage === void 0 ? options : { ...options, usage };
+}
+function announce_releases(releases) {
+  console.info(`Adopting: ${releases.map((release) => release.package_name).join(", ")}`);
+}
+function report(result) {
+  console.info("");
+  console.info(propagate_run.format_report([result]));
+  return propagate_run.has_failure([result]) ? FAILURE_EXIT_CODE : SUCCESS_EXIT_CODE;
+}
+function run_sequence(target, plan) {
+  const step = plan === void 0 ? propagate_steps.describe_step : propagate_steps.create_step_runner(plan);
+  const reason = plan === void 0 ? DRY_RUN_REASON : propagate_run.PROPAGATED_REASON;
+  return report(propagate_run.run_target(target, step, reason, propagate_run.ADOPT_STEP_ORDER));
+}
+function refuse_incomplete_plan2(project_root) {
+  const refusal = adopt_logic.refuse_incomplete_plan(
+    adopt_toolkits.misplaced_toolkits(project_root),
+    adopt_toolkits.unresolved_toolkits(project_root)
+  );
+  if (refusal === void 0) return void 0;
+  console.error(refusal);
+  return FAILURE_EXIT_CODE;
+}
+function stop_reason(releases) {
+  if (releases.length === 0) {
+    console.info(NOTHING_TO_ADOPT);
+    return SUCCESS_EXIT_CODE;
+  }
+  const refusal = adopt_logic.refuse_without_kit(releases);
+  if (refusal === void 0) return void 0;
+  console.error(refusal);
+  return FAILURE_EXIT_CODE;
+}
+function adopt_target(project_root, releases, is_dry_run) {
+  const target = adopt_logic.resolve_self_target(project_root);
+  if (target === void 0) {
+    console.error(NO_ORIGIN);
+    return FAILURE_EXIT_CODE;
+  }
+  announce_releases(releases);
+  return run_sequence(target, is_dry_run ? void 0 : adopt_logic.build_plan(releases));
+}
+function run_here(project_root, is_dry_run) {
+  const incomplete = refuse_incomplete_plan2(project_root);
+  if (incomplete !== void 0) return incomplete;
+  const releases = adopt_toolkits.discover_toolkits(project_root);
+  const stop = stop_reason(releases);
+  return stop ?? adopt_target(project_root, releases, is_dry_run);
+}
+function run(argv, project_root = PROJECT_ROOT) {
+  const options = parse_options(argv);
+  if (options.usage !== void 0) {
+    console.error(options.usage);
+    return FAILURE_EXIT_CODE;
+  }
+  const refusal = adopt_logic.refuse_inside_kit_repository(project_root);
+  if (refusal !== void 0) {
+    console.error(refusal);
+    return FAILURE_EXIT_CODE;
+  }
+  return run_here(project_root, options.is_dry_run);
+}
+function main(argv) {
+  process.exit(run(argv));
+}
+var adopt = {
+  KNOWN_FLAGS,
+  NOTHING_TO_ADOPT,
+  parse_options,
+  run_sequence,
+  run_here,
+  run
+};
+if (process.argv[1] === fileURLToPath(__josh_source_url)) main(process.argv.slice(ARGV_OFFSET));
+export {
+  adopt
+};

package/dist/commands/auth-setup-cli.js

@@ -0,0 +1,127 @@
+#!/usr/bin/env tsx
+import {
+  claude_token
+} from "./chunk-3WRQP3QE.js";
+import {
+  token_shape
+} from "./chunk-AQ3PMSXK.js";
+import "./chunk-HIU2WXB6.js";
+
+// scripts/auth/auth-setup-cli.ts
+import { dirname as __josh_dirname } from "node:path";
+import { fileURLToPath as __josh_file_path } from "node:url";
+import { fileURLToPath } from "node:url";
+import { parseArgs } from "node:util";
+import { execa } from "execa";
+
+// scripts/auth/claude-token-output.ts
+import { stripVTControlCharacters } from "node:util";
+var { REDACTED, ANTHROPIC_OAUTH_TOKEN: TOKEN_PATTERN } = token_shape;
+var TOKEN_START = "sk-ant-oat";
+var EVERY_TOKEN_PATTERN = new RegExp(TOKEN_PATTERN.source, "gu");
+var CONTINUATION_PATTERN = /^[\w-]+$/u;
+var LINE_BREAK_PATTERN = /\r?\n/u;
+function is_continuation(line) {
+  return CONTINUATION_PATTERN.test(line) && !line.startsWith(TOKEN_START);
+}
+function continuation(lines) {
+  const length = lines.findIndex((line) => !is_continuation(line.trim()));
+  return (length === -1 ? lines : lines.slice(0, length)).map((line) => line.trim());
+}
+function redact(lines) {
+  const start = lines.findIndex((line) => TOKEN_PATTERN.test(line));
+  if (start === -1) return [...lines];
+  const [head = "", ...rest] = lines.slice(start);
+  const remaining = rest.slice(continuation(rest).length);
+  return [
+    ...lines.slice(0, start),
+    head.replaceAll(EVERY_TOKEN_PATTERN, () => REDACTED),
+    ...redact(remaining)
+  ];
+}
+function capture(output) {
+  const lines = stripVTControlCharacters(output).split(LINE_BREAK_PATTERN);
+  const start = lines.findIndex((line) => TOKEN_PATTERN.test(line));
+  const head = lines[start];
+  const shown = redact(lines).join("\n");
+  if (head === void 0) return { token: void 0, shown };
+  const token = [TOKEN_PATTERN.exec(head)?.[0], ...continuation(lines.slice(start + 1))].join("");
+  return { token, shown };
+}
+function live_length(output) {
+  const start = output.indexOf(TOKEN_START);
+  if (start !== -1) return start;
+  const prefixes = Array.from(
+    { length: TOKEN_START.length },
+    (_, index) => TOKEN_START.slice(0, index + 1)
+  );
+  const held = prefixes.findLast((prefix) => output.endsWith(prefix));
+  return output.length - (held?.length ?? 0);
+}
+var claude_token_output = { capture, live_length };
+
+// scripts/auth/auth-setup-cli.ts
+var __josh_meta = import.meta;
+var __josh_source_url = new URL("../../scripts/auth/auth-setup-cli.ts", __josh_meta.url).href;
+var __josh_source_filename = __josh_file_path(__josh_source_url);
+var __josh_source_dirname = __josh_dirname(__josh_source_filename);
+var ARGV_OFFSET = 2;
+var FAILURE_EXIT_CODE = 1;
+var CLAUDE = "claude";
+var SAVED = `saved: ${claude_token.VARIABLE} (macOS keychain)`;
+var NO_TOKEN = "claude setup-token printed no token, so nothing was saved.";
+var NO_KEYCHAIN = `This machine has no macOS keychain, so nothing was run. Run \`claude setup-token\` yourself and export ${claude_token.VARIABLE} \u2014 josh fresh:run reads it when the keychain has none.`;
+var NOT_SAVED = "The keychain did not keep the token. Run `pnpm josh auth:setup` again.";
+function refuse(message) {
+  console.error(message);
+  return FAILURE_EXIT_CODE;
+}
+function check() {
+  const date = claude_token.saved_date();
+  if (date === void 0) {
+    return refuse(`missing: no ${claude_token.VARIABLE} saved. ${claude_token.SETUP_HINT}`);
+  }
+  console.info(`ok: ${claude_token.VARIABLE} saved on ${date} (macOS keychain)`);
+  return 0;
+}
+function store(token) {
+  if (token === void 0) return refuse(NO_TOKEN);
+  if (!claude_token.save(token)) return refuse(NOT_SAVED);
+  console.info(SAVED);
+  return 0;
+}
+function show_live(printed, chunk) {
+  printed.text += printed.decoder.decode(chunk, { stream: true });
+  const live = claude_token_output.live_length(printed.text);
+  process.stdout.write(printed.text.slice(printed.shown, live));
+  printed.shown = live;
+}
+async function setup() {
+  if (!claude_token.has_keychain()) return refuse(NO_KEYCHAIN);
+  const printed = { decoder: new TextDecoder(), text: "", shown: 0 };
+  const child = execa(CLAUDE, ["setup-token"], {
+    stdin: "inherit",
+    stderr: "inherit",
+    reject: false
+  });
+  child.stdout.on("data", (chunk) => {
+    show_live(printed, chunk);
+  });
+  const result = await child;
+  const held = printed.text.slice(printed.shown) + printed.decoder.decode();
+  const { token, shown } = claude_token_output.capture(held);
+  process.stdout.write(shown);
+  if (result.failed) return refuse(`claude setup-token failed: ${result.shortMessage ?? CLAUDE}`);
+  return store(token);
+}
+async function run(argv) {
+  const { values } = parseArgs({ args: [...argv], options: { check: { type: "boolean" } } });
+  return values.check === true ? check() : await setup();
+}
+var auth_setup_cli = { run };
+if (process.argv[1] === fileURLToPath(__josh_source_url)) {
+  process.exitCode = await run(process.argv.slice(ARGV_OFFSET));
+}
+export {
+  auth_setup_cli
+};