@joshuafolkken/kit 1.1383.0 → 1.1435.0

package/.claude/skills/epic-commands/SKILL.md

@@ -150,7 +150,7 @@ worked form.
 
 **An `in-progress` issue occupies a lane rather than the whole repository.** The occupancy is counted
 from that repository's own `in-progress` listing — never from anything the session remembers — and
-what is left of `JOSH_LANE_LIMIT` (**default 6**) is what gets offered. At zero the answer is `wait`
+what is left of `JOSH_LANE_LIMIT` (**default 4**) is what gets offered. At zero the answer is `wait`
 and the holders are named on standard error. A parked child releases its lane; one stopped by
 `needs-human-review` goes on holding one, because its uncommitted work is still in that checkout.
 

package/.claude/skills/epic-commands/epic-bundle.md

@@ -9,6 +9,11 @@ settle. `Nothing to bundle.` needs neither.
 already recorded between them. **A similar title never counts on its own** — "related" expands
 without limit, and the threshold is what keeps an unrelated issue out.
 
+**The release issue is neither a candidate nor a subject**, like an epic. `issue:file --release` records
+every change awaiting publication as its blocker, so that relation is mechanical, not a sign of shared
+work. Counted as a signal, it would put the release and an unrelated change in one epic. A
+`blocked-by` or a prose reference between any other two issues still counts.
+
 **The search is not limited to the open backlog.** Every issue number the subject's body names is read
 on its own, whatever its state. A **closed** reference counts only when an open epic already tracks
 it, since the answer worth recovering is `add_to_epic`; an epic created over a closed issue has

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

@@ -113,9 +113,10 @@ The bullets below describe that dispatch:
   trace alone**, because its log will never grow.
 - **The child is started as `fullrun #<N>` with the lane as its working directory.** The batch a
   person approved by typing `backlogrun` covers the child.
-- **It does not pass `--dangerously-skip-permissions`.** What the child may do is the checkout's own
-  `.claude/settings.json` to decide; a headless child reaches `gh` and merges through `pnpm josh
-  followup` without the flag, and the run reports what stopped rather than loosening it.
+- **It passes `--permission-mode bypassPermissions`, never `--dangerously-skip-permissions`.** A
+  current Claude Code ignores the mode `.claude/settings.json` declares, and a new lane worktree is
+  never a trusted workspace; that file's `deny` list still refuses what it names, so the run reports
+  what stopped rather than loosening it.
 
 **Start each child without blocking on it, and poll them all** — a silent one is
 `backlogrun-recovery.md` → "A delegated unit that stopped without reporting", read in that child's
@@ -142,6 +143,7 @@ conflict.
 | The child stopped on **`needs-human-review`** | **Left open and untouched** | The uncommitted work *is* the artifact a person has to look at. Name the lane directory in the stop report and in the Telegram |
 | The child **failed** | Whichever of the two parked rows applies, plus the consecutive-failure count | Same reasoning; only the counter differs. **A merge conflict is not this row** — it takes the row above, and it is not counted |
 | **`lane:open` failed on the install** | `pnpm josh lane:close <N>`, then park the child | A lane exists that no `pnpm josh …` runs in and the next `lane:open` answers `already-open`. Closing frees the seat; parking is right because the cause is one a person fixes. Carry pnpm's reason into the park note |
+| The lane is **spent** — no child working in it, its Issue closed, not one this run launched and has not collected with `run:merge`, a clean tree, no commit that is on no remote | Nothing to do — `pnpm josh lane:prune` closes it | Nothing in it is wanted, so no one has to type the close. Any other lane is kept and `lane:prune` says why on standard error |
 | The run was **interrupted** | Nothing to do — the work tree survives on disk | The next session's `pnpm josh lane:prune` closes what git no longer has a tree for. **Park that child**, naming the lane and `pnpm josh lane:close <N>` as the way out |
 
 **A lane closed after a push is reopened by `pnpm josh lane:open <N>`**, which attaches to a local

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

@@ -61,7 +61,7 @@ resumed session runs `remaining` from `--json`. The contract is `docs/josh-comma
 ```bash
 pnpm josh run:carry --begin "backlogrun --max 5 --idle 30" --owner "$PPID"
 pnpm josh run:carry --json                                                   # read it back in a resumed session
-pnpm josh run:wake --start                                                   # same turn as --begin
+pnpm josh run:wake --start                                                   # same turn as --begin; `running` under `josh backlogrun`
 ```
 
 **Always pass `--owner "$PPID"`**, and ask it before the plan, in the same turn as the first `pnpm josh
@@ -85,7 +85,8 @@ named epic's children", never the root as a standalone `fullrun`, then ask `pnpm
 a child number or `complete` continues; only `stop` or a failure records `pnpm josh run:carry --done <E>
 --owner "$PPID"`.
 
-**A person keeps control of the supervisor** — `pnpm josh run:wake --list` / `--stop`.
+**A person keeps control of the run** — `pnpm josh run:wake --list` reads it, `pnpm josh backlogrun
+--stop` stops it (`docs/josh-commands.md` → "`josh backlogrun`").
 
 Rationale: `docs/maintainers/backlogrun-steps-rationale.md` → "Why a session cut does not end the run"
 
@@ -129,7 +130,7 @@ section the row names:
 | Handed back | What the session does | Read |
 | --- | --- | --- |
 | `triage` | Label each issue stderr names `run:solo` or `run:lane` (`blocked-by` where one must land first) | "Resolve what the plan can resolve, before starting" above |
-| `offer` | Report what stderr printed; **never pick an issue by hand** | — |
+| `offer` | Report what stderr printed — a failed offer, or a named issue whose state stayed unreadable; **never pick an issue by hand** | — |
 | `launch #N` | Read the lane's log and park `#N` | `backlogrun-park.md` → "park and continue" |
 | `merge [<token>] #N` | `environment` ends the run; the others re-read the child | `backlogrun-progress.md` → "Running a named epic's children" |
 | `epic #N` | A named epic's turn | "The session cut is inside the invocation" above |

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

@@ -46,6 +46,7 @@ is still that one invocation (`backlogrun-steps.md` → "The session cut is insi
    session only when it needs judgment.
 7. **End the record when the run ends** — `run:report`, then `run:carry --end` (or `--end --stopped
    "<reason>"`) and `run:wake --stop`. An empty plan is not that end; the driver's idle watch decides it.
+   A person stops a run from the terminal with `pnpm josh backlogrun --stop`, which makes both calls.
 
 ## The route table
 

package/.claude/skills/workflow-commands/chain-rule.md

@@ -5,7 +5,8 @@
 This is the execution contract for `fullrun` and `backlogrun`, and for `prrun` up to the pull request: a `prrun` never issues `pnpm josh ship` or a merging `pnpm josh followup` — it opens the pull request with `pnpm josh git -y` and ends by `prrun.md` → "The difference — the end of the run". The record below is reference only.
 Review results and successful pushes are never turn boundaries.
 
-0. **A lane child**: `pnpm josh main:merge`, the scoped pair, `pnpm josh ship --detach --review
+0. **A lane child**: `pnpm josh main:merge`, the self-check (`prompts/review.md` → "Before round 1 —
+   the implementer's self-check"), the scoped pair, `pnpm josh ship --detach --review
    "<title> #<N>"` (`--cite <N>`), then **end the turn** on `launched`/`busy`. A stop relaunches a child
    whose prompt names `pnpm josh ship --log <N>` and (Anthropic lane) the re-detach to run after
    the fix — `pnpm josh ship --detach`, `--review` only if the stopped ship carried it and stopped before
@@ -13,7 +14,8 @@ Review results and successful pushes are never turn boundaries.
    `failed` → step 1. A backgrounded `ship` issued alone is moved to the foreground by the hook
    rather than refused.
 1. Run `pnpm josh main:merge`. **Then issue `pnpm josh run:cut <N>` alone, before the scoped pair and
-   the gate** — the pre-gate cut (a no-op outside a lane). Then run the final scoped lint/test pair and
+   the gate** — the pre-gate cut (a no-op outside a lane). Then answer the self-check
+   (`prompts/review.md` → "Before round 1 — the implementer's self-check"), run the final scoped lint/test pair and
    `pnpm josh run:review`: it starts `pnpm josh gate` in the background and prints the `/code-review`
    brief in one call, so the two overlap. Launch the `/code-review` subagent as the `general-purpose`
    agent type with that brief (every tool, so `--fix` applies; never a guessed type name).

package/.claude/skills/workflow-commands/issue-comments.md

@@ -91,3 +91,9 @@ never the comment text.
 **`pnpm josh rule:guard` refuses the body-only read** and hands over the reissue and the conflict rule
 at the moment they bind (`prompts/collaboration-workflow/rule-delivery.md`). **This file is the rule,
 not the hook** — a session that runs no hooks still owes the read.
+
+## A person's update mid-run
+
+When the hook, `review:attest --check` or `followup` shows an Issue update, read it as above — the
+later text is in force — fix what it changes, then `pnpm josh issue:ack <N>`. The watch and what it
+does not catch: `docs/josh-commands-backlog.md` → "`josh issue:ack`".

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

@@ -106,8 +106,9 @@ could not.
   and appends nothing. That round reads only, so no commit of the run's follows it; a line in the tree
   would be pushed onto the open pull request and its CI would start over. `pnpm josh ship --review`
   does this for a passing round 2. **A round 2 that blocks records in the tree as before** — the fix it
-  stops for is pushed anyway and carries the lines. The comment's lines are outside the count
-  `pnpm josh review:findings` and the retrospective read.
+  stops for is pushed anyway and carries the lines. Once the Issue is closed, the next round recorded
+  to the ledger carries the comment's lines into `<N>-comment-rounds.md` with its own commit, so
+  `pnpm josh review:findings` and the retrospective count them (`review-comment-round.ts`).
 - **`pnpm josh followup` commits any other line appended after the run's commit onto the pull request,
   before the merge** — the residual path, for an observation recorded between the commit and the
   merge. After the merge gates and before the CI wait, `followup` reads the tree and, **only when the

package/.claude/skills/workflow-commands/pre-gate-cut.md

@@ -169,9 +169,11 @@ built for the lane child.
 **The trigger**: `pnpm josh rule:guard` refuses an `Edit` / `Write` in a dispatched lane child whose
 recent-context cost is over threshold, handing back `pnpm josh run:cut --impl <N> --handoff <path>`.
 `cut` ends the turn; a fresh process's `run:cut --resume <N>` answers `resume-impl` and continues
-implementation — **the implementation resume clears the record**, so the cut may fire again. Outside
-a lane, a held run on a measured `over` keeps the hold, sends a `confirmation` Telegram naming
-`fullrun #<N>` and ends the turn. The refusal states the rest — **It fires on every threshold crossing,
+implementation — **the implementation resume clears the record**, so the cut may fire again. **A cut
+that relaunches its successor owes no Telegram**, the pre-gate cut as much as this one: nobody has
+anything to act on, and a resume answering `stale` / `busy` sends its own. Outside a lane nothing is
+relaunched, so `run:cut --impl` prints the held run's instruction — on a measured `over` that run
+keeps the hold, sends a `confirmation` Telegram naming `fullrun #<N>` and ends the turn. The refusal states the rest — **It fires on every threshold crossing,
 not once per run**; **An edit reissued right after a refusal passes**; **An unmeasurable session
 warrants the cut**; **It is silent between a cut and its resume**. Rationale:
 `docs/maintainers/pre-gate-cut-rationale.md` → "Why the rules are guards, not prose";

package/README.md

@@ -35,6 +35,16 @@ pnpm exec josh start
 
 Next: [tutorial](./docs/tutorial.md)
 
+### Your first backlogrun
+
+Tell the agent the change you want, then type `kickoff new auto ok` to it (or add the `auto-ok` label to an existing Issue).
+
+```bash
+pnpm josh backlogrun
+```
+
+Details: [Run the backlog unattended](./docs/how-to/run-backlog.md)
+
 ### AI assistant only — no GitHub account needed
 
 Requires [Node.js and pnpm](./docs/setup/prerequisites.md).
@@ -45,6 +55,21 @@ pnpm --allow-build=esbuild dlx @joshuafolkken/kit init
 
 Next: [tutorial](./docs/tutorial.md#without-github-one-change-checked-locally)
 
+## Claude Code in a fresh-machine run
+
+A [`josh fresh:run`](./docs/maintainers/fresh-machine.md) scenario that runs Claude Code needs a sign-in, saved once:
+
+1. In a terminal at the kit repository, run:
+
+   ```bash
+   pnpm josh auth:setup
+   ```
+
+2. A browser opens: sign in with your Claude account and press "Authorize".
+3. Done when the terminal prints `saved: CLAUDE_CODE_OAUTH_TOKEN (macOS keychain)`. There is no token to copy or write into a file.
+4. To check, run `pnpm josh auth:setup --check`: it prints `ok` and the day it was saved.
+5. When the token expires, Claude Code in the container fails to sign in — start again from step 1.
+
 ## Docs
 
 [How-to](./docs/how-to.md) · [All docs](./docs/overview.md)

package/dist/hooks/audit-provision.js

@@ -1,14 +1,14 @@
 #!/usr/bin/env tsx
 import {
   timed_fetch
-} from "./chunk-FZ6FUSBM.js";
+} from "./chunk-723HKZO5.js";
 import {
   error_text
 } from "./chunk-CDY4NFQG.js";
 import {
   PROJECT_ROOT,
   stamp_file
-} from "./chunk-NEC4AT4Z.js";
+} from "./chunk-DGT54IH5.js";
 
 // scripts/security/security-audit-provision.ts
 import { chmodSync, mkdirSync, renameSync, rmSync, writeFileSync } from "node:fs";

package/dist/hooks/batch-guard.js

@@ -9,13 +9,13 @@ import {
   load_environment_file,
   notice_refusal_path,
   refusal_path
-} from "./chunk-RYP3TSUJ.js";
-import "./chunk-KC6LUZZ2.js";
-import "./chunk-LC56R53A.js";
-import "./chunk-TT742SIO.js";
-import "./chunk-Y5R47QHU.js";
-import "./chunk-4MGHBTOM.js";
-import "./chunk-NEC4AT4Z.js";
+} from "./chunk-7KMN5QB5.js";
+import "./chunk-5SJSSCJG.js";
+import "./chunk-MU4LJFIV.js";
+import "./chunk-XER6SSIB.js";
+import "./chunk-4BHUPFKF.js";
+import "./chunk-3LE6VLSR.js";
+import "./chunk-DGT54IH5.js";
 export {
   DISABLED_VALUES,
   SWITCH_ENV_KEY,

package/dist/hooks/{chunk-LOJTBU5V.js → chunk-2G5F2YCD.js}

@@ -1,12 +1,12 @@
 import {
   investigation_reads
-} from "./chunk-7VSZ2N4B.js";
+} from "./chunk-QL6QTPWN.js";
 import {
   lane_guard_policy
-} from "./chunk-KC6LUZZ2.js";
+} from "./chunk-5SJSSCJG.js";
 import {
   hook_decision
-} from "./chunk-LC56R53A.js";
+} from "./chunk-MU4LJFIV.js";
 
 // scripts/delegation/investigation-guard.ts
 import { text } from "node:stream/consumers";

package/dist/hooks/{chunk-4MGHBTOM.js → chunk-3LE6VLSR.js}

@@ -4,7 +4,7 @@ import {
   PROBE_TIMEOUT_MS,
   SUITE_TIMEOUT_MS,
   stamp_file
-} from "./chunk-NEC4AT4Z.js";
+} from "./chunk-DGT54IH5.js";
 
 // scripts/lib/json-value.ts
 function parse_or_undefined(text) {
@@ -511,12 +511,19 @@ async function commit(message) {
 async function delete_branch(branch_name) {
   await git_spawn.read(["branch", "-d", branch_name]);
 }
-async function commit_count_beyond(base, tip) {
-  const range = `${base}..${tip}`;
-  const output = await git_spawn.read(["rev-list", "--count", range]);
+async function read_commit_count(revisions) {
+  const output = await git_spawn.read(["rev-list", "--count", ...revisions]);
   const parsed = Number(output);
   if (output.length > 0 && Number.isFinite(parsed)) return parsed;
-  throw new Error(`\`git rev-list --count ${range}\` printed \`${output}\` rather than a count`);
+  throw new Error(
+    `\`git rev-list --count ${revisions.join(" ")}\` printed \`${output}\` rather than a count`
+  );
+}
+async function commit_count_beyond(base, tip) {
+  return await read_commit_count([`${base}..${tip}`]);
+}
+async function commit_count_unpushed(branch_name) {
+  return await read_commit_count([branch_name, "--not", "--remotes"]);
 }
 function is_exit_code_128(cause) {
   return typeof cause === "object" && cause !== null && "exit_code" in cause && cause.exit_code === "128";
@@ -633,6 +640,7 @@ var git_command = {
   checkout,
   commit,
   commit_count_beyond,
+  commit_count_unpushed,
   delete_branch,
   push: push2,
   pull_fast_forward,
@@ -1341,7 +1349,7 @@ function next_added(carry, additions) {
 }
 function add_issues(target, carry, additions) {
   const next = { ...carry, added: next_added(carry, additions) };
-  stamp_file.write_stamp(target, next);
+  stamp_file.replace_stamp(target, next);
   return next;
 }
 var run_carry_added = { add_issues, ordered };
@@ -1434,7 +1442,7 @@ function apply_change(target, carry, change, now = /* @__PURE__ */ new Date()) {
     done: next_done(carry, effective.done),
     retrospective: effective.retrospective === true || carry.retrospective
   };
-  stamp_file.write_stamp(target, next);
+  stamp_file.replace_stamp(target, next);
   return next;
 }
 var run_carry_change = { apply_change };
@@ -2049,6 +2057,7 @@ var run_carry_schema = z2.object({
   owner_pid: z2.number().optional(),
   owner_start: z2.string().optional(),
   owner_transcript: z2.string().optional(),
+  is_owner_headless: z2.boolean().optional(),
   is_handed_off: z2.boolean().optional(),
   done: z2.array(z2.number()).optional(),
   retrospective: z2.boolean().optional(),
@@ -2090,7 +2099,8 @@ function fresh_carry(invocation, owner, now) {
     outages: NO_INCREMENT3,
     owner_pid: owner.pid,
     owner_start: owner.start,
-    owner_transcript: owner.transcript
+    owner_transcript: owner.transcript,
+    is_owner_headless: owner.is_headless
   };
 }
 function begin_carry(target, invocation, owner = NO_OWNER, now = /* @__PURE__ */ new Date()) {
@@ -2103,6 +2113,7 @@ function adopt_carry(target, carry, owner = NO_OWNER) {
     owner_pid: owner.pid,
     owner_start: owner.start,
     owner_transcript: owner.transcript,
+    is_owner_headless: owner.is_headless,
     is_handed_off: false
   };
   stamp_file.remove_stamp(target);
@@ -2119,6 +2130,11 @@ function is_owned_by(carry, owner) {
 function is_foreign_live_owner(carry, owner) {
   return is_owner_live(carry) && !is_owned_by(carry, owner);
 }
+function is_held_by_another(carry, is_live = is_owner_live) {
+  const caller = owner_of(process.pid);
+  const is_own = carry.owner_pid === caller.pid && carry.owner_start === caller.start;
+  return !is_own && is_live(carry);
+}
 function is_handed_off_to(carry, invocation) {
   return carry.is_handed_off === true && carry.invocation === invocation;
 }
@@ -2205,6 +2221,7 @@ var run_carry = {
   fresh_carry,
   is_count_refused,
   is_foreign_live_owner,
+  is_held_by_another,
   is_owner_live,
   lost_message,
   nothing_to_resume_message,

package/dist/hooks/{chunk-Y5R47QHU.js → chunk-4BHUPFKF.js}

@@ -2,7 +2,7 @@ import {
   ENV_FILE_NAME,
   issue_number_shape,
   lane_paths
-} from "./chunk-4MGHBTOM.js";
+} from "./chunk-3LE6VLSR.js";
 
 // scripts/josh/josh-environment-file.ts
 function load_environment_file() {

package/dist/hooks/{chunk-KC6LUZZ2.js → chunk-5SJSSCJG.js}

@@ -1,6 +1,6 @@
 import {
   lane_child_marker
-} from "./chunk-Y5R47QHU.js";
+} from "./chunk-4BHUPFKF.js";
 
 // scripts/lane/lane-guard-policy.ts
 var DEFAULT_MODE = "refuse";

package/dist/hooks/{chunk-FZ6FUSBM.js → chunk-723HKZO5.js}

@@ -1,6 +1,6 @@
 import {
   FETCH_TIMEOUT_MS
-} from "./chunk-NEC4AT4Z.js";
+} from "./chunk-DGT54IH5.js";
 
 // scripts/lib/timed-fetch.ts
 async function timed_fetch(url, init = {}, timeout_ms = FETCH_TIMEOUT_MS) {

package/dist/hooks/{chunk-RYP3TSUJ.js → chunk-7KMN5QB5.js}

@@ -1,12 +1,12 @@
 import {
   lane_guard_policy
-} from "./chunk-KC6LUZZ2.js";
+} from "./chunk-5SJSSCJG.js";
 import {
   hook_decision
-} from "./chunk-LC56R53A.js";
+} from "./chunk-MU4LJFIV.js";
 import {
   time_batch_guard
-} from "./chunk-TT742SIO.js";
+} from "./chunk-XER6SSIB.js";
 
 // scripts/hooks/batch-guard.ts
 import { text } from "node:stream/consumers";

package/dist/hooks/{chunk-NEC4AT4Z.js → chunk-DGT54IH5.js}

@@ -3,6 +3,9 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 var PACKAGE_DIR = path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
 var PROJECT_ROOT = process.cwd();
+function package_path(relative_path) {
+  return path.join(PACKAGE_DIR, relative_path);
+}
 
 // scripts/josh/stamp-file.ts
 import { createHash, randomUUID } from "node:crypto";
@@ -144,6 +147,7 @@ var SUITE_TIMEOUT_MS = 18e5;
 
 export {
   PROJECT_ROOT,
+  package_path,
   PLATFORM_TEMP_ROOT,
   platform_temporary,
   stamp_file,

package/dist/hooks/{chunk-YKUITFT7.js → chunk-EMB55BDF.js}

@@ -1,18 +1,18 @@
 import {
   resolve_local_bin,
   resolve_package_bin
-} from "./chunk-JBBMAPC4.js";
+} from "./chunk-IX6TTTI6.js";
 import {
   ESLINT_EDIT_CACHE_FLAGS,
   time_density_hook
-} from "./chunk-TT742SIO.js";
+} from "./chunk-XER6SSIB.js";
 import {
   file_reader,
   json_value
-} from "./chunk-4MGHBTOM.js";
+} from "./chunk-3LE6VLSR.js";
 import {
   HOOK_PROCESS_TIMEOUT_MS
-} from "./chunk-NEC4AT4Z.js";
+} from "./chunk-DGT54IH5.js";
 
 // scripts/hooks/format-edited-file.ts
 import { existsSync as existsSync2 } from "node:fs";

package/dist/hooks/{chunk-JBBMAPC4.js → chunk-IX6TTTI6.js}

@@ -85,6 +85,10 @@ function resolve_package_bin(base_directory, package_name, bin_name) {
 
 export {
   ancestor_directories,
+  vscode_settings_schema,
+  json_object_schema,
+  string_array_schema,
+  string_record_schema,
   resolve_local_bin,
   find_local_bin_upwards,
   resolve_package_bin