@joshuafolkken/kit 1.872.0

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

@@ -0,0 +1,267 @@
+# What stays resident, and how much — `SKILL.md` §3's body
+
+**This is `SKILL.md` → §3's body, and it is read when a rule is being placed, moved or retired — not
+at any entry** (joshuafolkken/kit#1797, joshuafolkken/kit#2161). **Nothing in a run reaches it.** The
+moment it binds is a turn spent editing `CLAUDE.md` or one of these documents, which is why it costs a
+workflow entry nothing to leave it here. `SKILL.md` → §3 keeps the heading and points here; the
+questions that decide *whether* a rule stays now live below, alongside the procedure that decides *how
+much* of it does. The `rule:value` readings this file used to carry no longer gate reduction — that
+gating was retracted on 2026-09-13 (joshuafolkken/kit#1931 → `## Decisions`) and they are retained
+below only as history.
+
+## Whether a rule stays
+
+**Before either question below, ask question 0:** `prompts/collaboration-workflow/residency.md` → question 0 — can the rule's answer be computed from mechanically readable inputs alone? If yes, it is a decision oracle and neither question below applies; `pnpm josh oracle:list` shows the existing ones. Only a no reaches the ordering question.
+
+**Then ask the ordering question:** `prompts/collaboration-workflow/residency.md` → ordering question — does the rule decide *when or in what order* to act rather than *what*? If so it belongs in the run driver's state transitions (`pnpm josh run:step`, `scripts/run/run-step.ts`), not either channel below. Only a rule that decides *what* reaches the first question.
+
+**The first question is whether the rule's trigger can be named:**
+
+> **Can the moment the rule begins to bind be named as one tool call?**
+
+**A rule whose trigger can be named moves its body out of `CLAUDE.md`.** It goes on the enumeration in
+`prompts/collaboration-workflow/rule-delivery.md`, and a hook refuses that call and states the rule —
+cheaper than resident prose, because it costs nothing on every other turn, and **stronger, because a
+refusal cannot be skimmed past**. **Relocating is not deleting** — the rule's text survives, on a
+stronger channel.
+
+**What stays behind is the trigger and the criterion, one line, because the channel reaches one
+harness.** `CLAUDE.md` is agent-agnostic by construction — `AGENTS.md`, `GEMINI.md` and `.cursorrules`
+are pointers to it, and a Codex, Gemini or Cursor session runs no `.claude/settings.json` hook at all;
+so does a Claude Code session with the guard's own off-switch set. **The gain is the body, not the
+line.** A rule may leave residency entirely only where the agent that has to obey it is always this
+harness.
+
+Only a rule whose trigger cannot be named reaches the second question:
+
+**A rule stays in `CLAUDE.md` if and only if it has to fire on a turn where no skill was loaded.** That
+test has exactly one input: when does the rule first bind — before a command has started, or after.
+Everything a run reaches only *after* it has read this skill is routed to from `CLAUDE.md`, never
+restated there.
+
+`CLAUDE.md` is the only document this section is about. `AGENTS.md` and `GEMINI.md` hold no rules at
+all — they are pointers to it.
+
+### The second question: how much of a resident rule is resident
+
+The criterion above decides **whether** a rule stays. It says nothing about **how much of it** stays,
+and for a long time nothing did — so a rule that passed arrived with its whole procedure attached,
+and `CLAUDE.md` grew back to within 585 bytes of its ceiling with the procedures already moved out
+(joshuafolkken/kit#964).
+
+**A resident rule is written as its trigger plus a pointer.** Two things and no third:
+
+1. **The trigger** — the situation that fires it, and the one instruction that must be obeyed before
+   anything else is read. Written so an agent that reads nothing further still does the safe thing:
+   stops, files, refuses, asks.
+2. **The pointer** — the topic file under `prompts/collaboration-workflow/` or the skill file that holds
+   the procedure, named exactly enough to open without searching.
+
+Everything else — the steps, the worked examples, the rationale, the failure it was written after —
+belongs at the pointer. **The test is whether the resident text still produces correct behavior on a
+turn where the pointer is never opened.** If dropping a sentence would let an agent proceed wrongly
+rather than merely proceed less well informed, that sentence is part of the trigger. If dropping it
+only costs context, it belongs at the pointer.
+
+**Trimming is moving, and deleting is the exception that has to be earned.** Before a sentence leaves
+`CLAUDE.md` it has to exist at the pointer, and the marker suite that pinned it has to be re-pointed
+there rather than dropped. A canonical section that is thinner than the resident copy is the normal
+case, not a reason to delete — the resident text is then the fuller version, and it is moved in
+before it is cut out.
+
+**A system that can only move eventually jams, so one route out exists — and it is narrow**
+(joshuafolkken/kit#1525). A rule is *retired* rather than moved only where deleting it cannot change
+what any agent does, and that has to be shown rather than argued:
+
+1. **It is a clone of text that has a declared single source**, and the source is named in the same
+   document. Where the two differ the copy is the wrong one, so nothing can correctly depend on it.
+2. **It carries no sentence that exists nowhere else** — checked against the source it duplicates,
+   not against a memory of it.
+3. **No marker suite pins it**, so no assertion is being dropped along with it.
+
+**"It looks redundant" satisfies none of the three, and a rule with a firing test, a marker, or a
+measured effect is not a candidate at all.** Every rule in these documents was written after a
+specific failure; one that changes nothing today may simply be one whose failure has not recurred
+*because it is there*. When the three do not all hold, the finding is recorded as a candidate with
+its evidence and left standing — a listed candidate costs nothing and can be taken up later, while a
+wrongly deleted rule fails silently, months later, in a run nobody is watching.
+
+**The scope of this list is every resident rule that has an on-demand counterpart** — a skill or an
+on-demand prompt carrying the procedure the resident text routes to. Those are the rules the
+criterion is *about*: each one could have moved, and stayed for a reason worth naming. Within that
+scope the list is exhaustive, and a rule with a counterpart that is resident without appearing here
+has not been checked.
+
+Counting by skill would draw the line in the wrong place — `verify-ui` is routed to as readily as
+this skill is, and one entry below routes to `prompts/review.md`, which is not a skill at all.
+
+Outside the scope the documents carry a great deal more — the naming conventions, the quality
+limits, the code-change rules, Package-First. **None of that belongs on this list**: there is no
+on-demand copy for them to have moved to, so the question the criterion asks does not arise, and
+their absence here is correct rather than an omission (joshuafolkken/kit#955).
+
+Within that scope, every rule that passes the test is resident in full, and a marker suite asserts
+each one present in `CLAUDE.md` — `scripts/claude/workflow-skills.test.ts` for most of them,
+`scripts/claude/verify-ui-skill.test.ts` for the UI gate,
+`scripts/document/document-markers.test.ts` for the follow-up filing step, and
+`scripts/document/document-markers.test.ts` for the file-editing prohibition. **A trigger-delivered rule
+is pinned differently** — by what its refusal says and by the trigger firing, in
+`scripts/rules/turn-batching-rule.test.ts`, `scripts/backlog/backlog-manufacturing-rule.test.ts` and
+`scripts/rules/delivered-rules.test.ts`, with only its one-line trigger asserted resident:
+
+- **Explicit invocation required** — it decides whether a workflow starts at all, so it binds on the
+  turn the user types the keyword, which is before anything here has been read.
+- **The mid-workflow stop notification** — most pauses that need it (an upstream-Issue interrupt, a
+  Tier C confirmation) happen on turns carrying no workflow keyword at all.
+- **The `overrides` prohibition** and **the `devEngines` prohibition** — a dependency command can be
+  run on any turn, including one that never loads `dependency-update`, and by the time the skill
+  would be read the pin has already been rewritten.
+- **The follow-up filing step after the review round cap** — filing the Issue and bundling it into an
+  epic. A pre-commit self-review runs outside any workflow as readily as inside one, and the Issue it
+  files is orphaned just the same; the step has to be readable on a turn that never typed a keyword.
+  Its full form is in `prompts/review.md` → "Review round cap" (joshuafolkken/kit#946).
+- **The UI-verification gate** — a rendered change is not done until the screen has been looked at,
+  and the procedure for capturing it is `verify-ui`. The gate binds whenever a UI change is reported
+  finished, which is routinely a turn with no workflow keyword typed and no skill loaded.
+- **The three `josh epic:*` rules that bind outside those commands** — recording a decision removes
+  that child's `needs-decision` label, fixing what `epic:audit` finds is Tier A, and an epic in
+  another repository is referenced as `owner/repo#N`. Each fires on a turn where no `epic:*` command
+  was run: the moment an issue is filed, or a decision written. The commands' own procedures are in
+  `.claude/skills/epic-commands/`, which is where everything else about them lives.
+- **The prohibition on carrying a file's new text inside a shell command** — an edit happens on any
+  turn at all, and there is no skill that a run loads *before* editing. Placed on demand, this one
+  rule would never fire once, which reads exactly like having deleted it. The measured cost, the
+  allowed/prohibited table and the reasoning are at
+  `prompts/collaboration-workflow/file-edits.md`; what stays resident is the instruction and the
+  criterion that decides it — whether the command carries the replacement wholesale, not which tool
+  was used (joshuafolkken/kit#1150). **The same criterion binds the Edit itself**: rewriting a whole
+  file to fix the three lines a review named carries the replacement wholesale exactly as a heredoc
+  does, so the resident instruction covers it in one clause and the three cases that justify writing
+  a file whole stay at the pointer (joshuafolkken/kit#1260).
+
+**These left this list at the first question, and are delivered by a hook instead**
+(joshuafolkken/kit#1524). None lost a sentence; each is pinned by the firing test named beside it
+rather than by a residency marker, and `prompts/collaboration-workflow/rule-delivery.md` is the
+enumeration and the single source of what a turn where the trigger does not fire means. **The four
+described below are not the whole set** — the enumeration has grown to nine rows, of which
+`scripts/rules/delivered-rules.ts` carries seven and two are their own binaries. The count that used to
+open this paragraph said `Four` and had been wrong since the fifth row landed, which is what a
+restated count does; it is gone rather than corrected, because a number kept in two places drifts
+again (joshuafolkken/kit#1525).
+
+- **The instruction to put independent calls in one turn** — `pnpm josh batch:guard` refuses the
+  `Bash`, `Edit` or `Read` call that would make a third consecutive single-call turn, and states the criterion
+  there. **`Edit` joined `Bash` in joshuafolkken/kit#1762, and `Read` in joshuafolkken/kit#1798**, because edits carry most of the recoverable
+  round trips and the guard could not reach one of them, and because a cluster holding one `Read` was breaking the wiring rather than the count.
+  It was resident through every run the topic file measures, and moved none of them, so what the
+  relocation gave up is prose that was not being obeyed
+  (`prompts/collaboration-workflow/turn-batching.md`, `scripts/rules/turn-batching-rule.test.ts`).
+- **The backlog WIP cap** — `pnpm josh rule:guard` refuses the `Bash` call that files an Issue
+  (`gh issue create`, or a `title`-bearing POST to `…/issues`) and delivers the count, the refusal,
+  both exemptions and the three tests that decide the interrupt one — the three kept whole, because a
+  delivery saying only "an interrupt is exempt" hands the deciding back to judgement
+  (joshuafolkken/kit#1518). A comment endpoint is not a filing and is left alone
+  (`prompts/collaboration-workflow/wip-cap.md`, `scripts/backlog/backlog-manufacturing-rule.test.ts`).
+- **The Issue's comments** — `pnpm josh rule:guard` refuses the `Bash` call that reads an Issue's
+  body without them (`gh issue view <N>`, or a `GET` of a path ending `…/issues/<N>`) and hands over
+  the reissue that carries them plus the rule for a comment that contradicts the body. It is the one
+  row whose trigger `batch:guard` also considers, so it stands aside on that guard's turn and fires
+  on the reissue. §2g is the procedure and stays here, because a session that runs no hooks still
+  owes the read (`prompts/collaboration-workflow/rule-delivery.md`,
+  `scripts/rules/delivered-rules.test.ts`).
+- **The prohibition on putting a body inside shell double quotes** — `pnpm josh rule:guard` refuses
+  the `Bash` call whose inline body value carries a backtick or a `$`, the two characters this
+  harness's zsh was measured to evaluate there, and hands back the path-shaped spellings
+  (`--body-file`, `--field body=@<path>`, `--notify-message-file`). **The trigger reads the body, not
+  the flag**: every worked example in these documents passes a placeholder, which is inert, so keying
+  on the flag would refuse the turns where the rule is already kept. It is also the one row whose
+  trigger deliberately overlaps another — a filing whose body carries a backtick is `wip-cap`'s
+  first, and this one's on the reissue. A one-line trigger stays resident because a hook reaches
+  Claude Code alone (`prompts/collaboration-workflow/shell-body.md`,
+  `scripts/rules/shell-body-rule.test.ts`, joshuafolkken/kit#1198).
+
+These do not pass it, and live in a skill instead: the split assessment (`split-assessment.md`), a
+prerequisite discovered mid-run (§2d, with each entry's branch in
+`fullrun.md` / `halfrun.md` / `backlogrun.md`), a named `backlogrun` item's acceptance
+of an Issue that is not an epic and its park-and-continue behavior (`backlogrun.md`), the whole
+verification gate and merge chain (`chain-rule.md` / `followup.md`), and the post-update verification
+procedure (`.claude/skills/dependency-update/`) that the two prohibitions above route to.
+
+The `auto-ok` pickup and its "only a person applies the label" rule (`backlogrun.md`) are the borderline
+case worth naming, because a prohibition on writing usually *is* resident. It is not, and the reason
+is that `auto-ok` exists nowhere but the documents that also forbid an agent applying it: a turn that
+opens none of them is a turn on which the label is never reached, so residency would buy nothing.
+
+**The criterion is not advisory.** `scripts/claude/workflow-skills.test.ts` caps each document at
+`RESIDENT_CEILING_BYTES` and requires headroom under it, so a procedure restated resident costs
+budget that the next genuinely-resident rule then has to take back out of existing prose.
+
+**The freeze on reducing resident text was lifted on 2026-09-13** (joshuafolkken/kit#1931 →
+`## Decisions`, carried out in joshuafolkken/kit#1924). Until then `rule:value` was read as a
+gate on reduction: three successive readings each retired nothing, and `CLAUDE.md` stayed at ~56 KB
+while its duplicated procedure bodies — the completion gate, the pre-commit self-review, the Step 0
+report format, the upstream-interrupt procedure — sat resident beside pointers that already held them.
+**That gating is retracted.** `rule:value` remains a *measurement* — a low unaided-keep ratio is still
+evidence a resident copy earns its place — but a reading that retires nothing no longer freezes the
+document, and a resident copy whose body is duplicated at a declared pointer is trimmed to its trigger
+under **Trimming is moving** above, without waiting for a reading to license it. **The readings below
+are retained as history of how the gate was applied, not as a live constraint.**
+
+**What leaves when the budget binds is decided by measurement, not by which sentence a marker
+happened to pin** (joshuafolkken/kit#1525). The old order was the reverse: a rule edited to keep a
+byte count lost whichever neighboring sentence was not pinned by a marker, so the least-defended
+text went rather than the least-useful one, and the bias grew with every rule added
+(joshuafolkken/kit#951). `rule:value` replaces that with a reading — over this checkout's
+recorded sessions it reports, per trigger-delivered rule, how often the run had already kept the rule
+at the moment the trigger fired. **That window is the rule's absence**, because the hook has said
+nothing yet and only the carried text is asking; the ratio is what the carried text earns unaided.
+
+**The first reading refused the deletion it was built to justify, which is why the measurement runs
+first.** Over 220 recorded runs the WIP cap — which keeps a resident copy — was kept unaided in 55% of
+the runs that reached it, while the Issue-comments rule, which has **no** resident copy, managed
+15%. The resident text was the obvious candidate on a reading of the prose, since the refusal repeats
+it almost word for word; the number says it is doing a great deal of work and must stay.
+
+**The second reading covers every rule, and it found no candidate either** (joshuafolkken/kit#1643).
+The first reading could score only two rows, so nobody could tell whether the candidates were
+exhausted or merely unmeasured. All six now declare a compliance test, and over 225 recorded runs they
+read: `shell-body` 81%, `early-heartbeat` 67%, `wip-cap` 57%, `issue-comments` 15%,
+`piped-verification` 13%, `run-tail` 4%. **The two rules that keep a resident copy are the two at the
+top** — `shell-body` at 81% and `wip-cap` at 57% — and exactly one rule without a copy sits between
+them: `early-heartbeat`, at 67% over **18 runs**, the smallest denominator in the table by a factor of
+five. So the resident copies are earning their place, and **nothing is retired on this reading**. The
+figures move as the corpus grows, so the next run of this question re-reads them rather than quoting
+these.
+
+**The third reading added the row the table had never carried, and it changed no verdict either**
+(joshuafolkken/kit#1792). The batching guard is delivered by a binary of its own, so it sat outside
+the registry `rule:value` read and the most-cited resident rule in the repository had no continuous
+reading at all. Over 297 recorded runs it reads **86% unaided over 276 runs, with 47 refusals** — the
+top of the table, so it too is earning its place and nothing is retired on this reading. **The row is scored on its refusal rather than on a trigger**, because whether a call would
+be refused depends on the turns behind it, which is also where the turn-is-a-message-id correction the
+first reading of the row exposed came from.
+
+**Measuring the four needed a distinction the first reading did not have, and it is the half worth
+carrying forward.** A rule's denominator is the situation it governs, and that is the trigger only
+where the trigger is a *neutral* act — filing an Issue, reading one — which a run keeping the rule
+performs anyway. The other four fire only on the violation: a run that backgrounded every push never
+trips `run-tail`. Scored against the trigger they would all have read near zero, and near zero reads
+as "the carried text earns nothing" — **a manufactured retirement candidate, which is the one outcome
+this measurement exists to prevent**. Such a row declares `reaches` instead, the governed act in
+either spelling.
+
+**The three tests then refused every remaining candidate, and that is the route working rather than
+failing.** The four resident one-liners left behind by trigger delivery all fail test 2: the
+paragraph above records why a line stays behind when the hook reaches one harness, so each carries a
+sentence that exists nowhere else. The duplicate list of delivered rules in
+`prompts/collaboration-workflow/residency.md` looked like a clean test-1 case — a stale summary
+sitting directly beneath a pointer to its own single source — and fails test 3, because
+`scripts/rules/shell-body-rule.test.ts` and `scripts/rules/turn-batching-rule.test.ts` each assert that a
+delivered rule is listed there. **Being pinned is what test 3 is for**: that assertion is the design
+requirement it looks like an accident of. Only the restated count above was retired. **A run that
+finds nothing retirable records the candidates with their evidence and stops there**, rather than
+lowering the bar until a deletion appears. A rule
+scoring `-` has declared no compliance test and is **unmeasured, never zero** — it is not thereby a
+candidate.
+
+**The fourth reading swept the eight mechanization PRs of the reduction epic (joshuafolkken/kit#2117–#2124) and retired nothing, which is again the route working** (joshuafolkken/kit#2125). Each PR that moved a judgement into a command trimmed its own resident prose to trigger-plus-pointer as it landed, so the sweep found no procedure restated in full: the mechanized triggers — the computable-answer question 0 (`oracle:list`), `test:declared`, `issue:scout` and the filing cap, the shell-body guard, `repo:party`, and the fixed-shape linters (`issue:lint` / `report:lint`) — each already resolve to their declared single source (`prompts/collaboration-workflow/residency.md`, `rule-delivery.md`, `wip-cap.md`, `shell-body.md`, `upstream-interrupt.md`, `report-format.md`) rather than carrying the procedure resident. **The one candidate the sweep raised was the `Stop` hook's arrival** (joshuafolkken/kit#2121): the resident `CLAUDE.md` → "Mid-workflow stop notification" section looked like a delivered rule whose copy could shrink to a one-liner, but it fails test 3 — `scripts/document/document-markers.test.ts` pins its heading and `scripts/claude/workflow-skills.test.ts` pins its `notify` command and its `parseArgs` line — and it fails test 2, because `stop-rules.ts`'s `STOP_NOTIFY_REASON` names this very section as the single source the delivered text points at, so trimming it would strand the pointer. The hold-release and issue-citation stop rules introduced no resident duplication at all: their single sources are `SKILL.md` → §2f and `issue-citation.md`, which the hook points to, and the resident issue-citation text was already a one-line trigger. **What the sweep reclaimed was a stale byte-budget record, not prose**: `chain-rule.md` was reduced in joshuafolkken/kit#2078 but its recorded size was never lowered, so the ratchet in `scripts/document/document-byte-budget.ts` was tightened 18,031 → 6,240 to hold that reduction. **The reclamation was only possible because nothing enforced it** — the ratchet's growth guard catches a document that swells past its ceiling but is blind to one that shrinks and leaves its record standing, which is how chain-rule.md's stale-loose entry survived two reduction epics unseen. So a staleness guard was added beside it (`recorded ≤ actual + slack`): an unrecorded shrink now fails `pnpm josh gate` rather than drifting, so the next reduction epic finds nothing stale to reclaim.

package/.claude/skills/workflow-commands/split-assessment.md

@@ -0,0 +1,130 @@
+# The split assessment — one definition, every entry point
+
+Before any entry point starts work on an Issue, decide whether the request is really **one**
+deliverable or several. This file is the single definition; every command applies it identically.
+
+## The question
+
+**The default is not to split.** Two questions have to answer yes **together**; either one alone
+leaves the work as one Issue:
+
+1. **Does the request contain two or more deliverables that could each be merged separately?**
+2. **Does the whole of it clearly exceed what one verification gate can confirm in one pass?** The
+   guide is **about 10 changed files and about 400 changed lines** (test files excluded).
+   Under that, it is one Issue however many separable pieces a reader can name inside it.
+
+Separately mergeable is still the first test, and it is unchanged: a change that must land in one
+commit to be correct is one deliverable however big it is. What changed is that **separability alone
+no longer splits anything** — it is now a necessary condition rather than a sufficient one.
+
+**The guide is a guide, and "clearly" is the operative word.** A run that has to argue itself past the
+numbers has already answered no. They are read against the whole request's estimate, not against the
+diff a first pass happens to produce, and a request that lands at 11 files is not thereby a split.
+
+## The same two questions decide the filing-time fold
+
+**The entry's split decision and the filing-time fold decision are the same two conditions, stated
+here once.** This assessment asks whether *one request* is several deliverables; the fold decision asks
+whether *several findings from one session* are one Issue — and reads the **same two questions in the
+same conjunction**: separability, and whether the whole clearly exceeds one gate.
+`pnpm josh issue:fold "<title>" …` answers `fold` / `separate` / `no-fold-needed`; its size half is
+`pnpm josh split:assess`, called not recomputed, and `separate` needs both halves exactly as `split`
+does. **There is no second criterion.** §2i's observation, the review round cap's branch 2 and §2d's
+prerequisite each route a second filing through it, delivered by `pnpm josh rule:guard` at the run's
+second `gh api … issues` call, never the first.
+
+## Why the default is not to split
+
+**The rules were manufacturing Issues faster than runs could close them.** Execution was never the
+bottleneck; arrival was, and this assessment was one of the routes producing it: `route:split`
+accounted for **28 of the 119 open Issues (24%)**.
+
+**Separability is not scarce, which is why a test made only of it splits nearly everything.** Almost
+any request can be described as several deliverables that could each ship alone, so the old test bit on
+requests worth a handful of lines. The second question is what makes the test bite only where one Issue
+would genuinely be unverifiable in one pass. The review round cap's default and the WIP cap changed
+alongside it, in one commit.
+
+## Diff size is not a reason to split, and that is measured
+
+**Size is a bar a split has to clear; it is never a reason to split.** Question 2 is a *minimum* — below
+it the work stays whole — and nothing makes a large diff a reason to divide one. Splitting an Issue in
+two to shorten review round 1 lengthens it, because each Issue pays round 1's fixed cost again while
+the size-dependent part is merely divided between the halves (measured in joshuafolkken/kit#1436:
+round 1's cost is dominated by a fixed part that two Issues pay twice, so there is no diff size at
+which splitting to cut it pays). **A proposal to add a size threshold that splits more is required to
+say why that data does not reach it.**
+
+**The size half is measured, not eyeballed — `pnpm josh split:assess`.** It counts the branch's
+changed files and changed lines with test files excluded and answers `split` / `single` on size
+alone, so the guide can be checked against real diffs after the fact rather than trusted from an
+estimate. It answers the **size** question only; separability (question 1) stays a judgement, which is
+why a `split` from this command is the size condition met, not a decision to divide the Issue.
+
+## What each entry point does with the answer
+
+| Entry | Single | Two or more |
+| --- | --- | --- |
+| `kickoff new` | Create one Issue, post the plan, stop | Create the children, create a **new epic**, stop |
+| `kickoff #N` | Post the plan on `#N`, stop | Create the children, then **promote `#N`** or create a new epic (below), stop |
+| `fullrun new` / `halfrun new` | Proceed as usual | Create the children and the epic, then **stop** |
+| `fullrun #N` / `halfrun #N` | Proceed as usual | Create the children, promote or create the epic, then **stop** |
+
+## A prerequisite is not a split
+
+"This needs something else done first" is a different answer from "this is really several things". A
+split means the request in hand contains two or more deliverables; a prerequisite means it is still
+**one** deliverable that has another one in front of it. The prerequisite rule is `SKILL.md` → §2d, its
+single source; each entry's own branch is in `backlogrun-park.md` → "A prerequisite discovered mid-run" and, for
+the stopping entry points, in `fullrun.md` / `halfrun.md`.
+
+## Two or more always means an epic
+
+**Splitting into two or more Issues always creates an epic. There is no count threshold and no ordering
+condition to evaluate.** This is about what follows a split, never about whether to make one — the bar
+for that is "The question" above. **An entry point that applies a different condition is a defect** —
+the whole point of one definition is that where the split was noticed cannot change what happens next.
+
+The epic is the non-closing home for the split rationale. A comment on the first child is buried the
+moment that child merges and closes.
+
+**Each split child is filed with the `route:split` label**, so the backlog's composition stays
+countable by filing route rather than by grepping issue bodies.
+
+## Promote, or create a new epic
+
+`kickoff #N` and the `#N` runs have one branch, and it is Tier A — decide it and record the reasoning
+on the Issue, without asking.
+
+- **`#N` is a request, a discussion, or a container → promote it.**
+  `pnpm josh epic --promote <N> <N1> <N2> ... [--ordered]`. The body is appended to, never replaced.
+- **`#N` is itself one of the deliverables → keep `#N` as a child and create a new epic.** A bug report
+  that turns out to need three fixes is the case: promoting the report would leave the report itself
+  with nowhere to live.
+
+## `backlogrun` is the one entry that does not stop
+
+`backlogrun` asked for the batch's authorization, so a split found under it is filed and continued through
+rather than stopped — including when the `backlogrun` was given a bare, non-epic Issue, where the split is
+what creates the epic (`backlogrun-child.md` → "When `#N` is not an epic"). The assessment itself is identical;
+only what follows the answer differs.
+
+## Finding a split mid-run stops the run
+
+`fullrun` and `halfrun` **stop** after filing the children and the epic. They do not continue into
+implementation, and they do not silently become a `backlogrun`. Typing `fullrun` approved implementing and
+merging **one** Issue; a batch of N is a different authorization. Report what was filed and end with:
+
+> Please run `backlogrun #<E> --only` to execute this epic.
+
+## There is no `kickoff epic`
+
+A separate keyword for "split this conversation into an epic" would duplicate `kickoff new` exactly,
+leaving a person to decide which of two commands to type for one job. The assessment above is how a
+split is reached from every entry.
+
+## Issues filed separately, found related later
+
+Issues that were filed at different times and turn out to be related afterwards are **not** a split — a
+split is about one request in hand containing several deliverables. That case is outside this
+assessment, and `pnpm josh epic --promote` is what handles it.

package/.claude/skills/workflow-commands/target-repository.md

@@ -0,0 +1,58 @@
+# The `owner/repo#` prefix — which repository the run acts on
+
+**This is `SKILL.md` → §2c's body, read at its point of use — the moment an entry is typed with an
+`owner/repo#` prefix (or a short `repo#` name), not at any entry** (joshuafolkken/kit#2161). A run
+given a bare `#N` or `new` targets the session's own repository and never reaches it, so it costs a
+workflow entry nothing to leave it here. `SKILL.md` → §2c keeps the trigger and points here.
+
+Every entry point takes the target repository in front of the Issue reference. Without it the target
+is the repository the session runs in.
+
+```
+kickoff joshuafolkken/kit#412
+kickoff kit#new
+kickoff kit#new "<title>"
+fullrun joshuafolkken/app-kit#12
+halfrun kit#412
+backlogrun kit#1 kit#2
+backlogrun joshuafolkken/kit#858 --only
+```
+
+- **One definition, every entry point.** The prefix goes where `#N` goes, so no new keyword is added,
+  and `owner/repo#new` stands in the same slot as `owner/repo#N`.
+- **A short name expands by prefixing the session repository's owner** — `pnpm josh repo:party`
+  computes the party — and **never by searching kit#869's map**, which answers where a checkout is
+  rather than which repository is meant. A short name therefore satisfies the first-party test (owner
+  equality) by construction, so **there is structurally no path by which a short name resolves to a
+  third-party target**, and a repository that is not checked out here is still a valid `kickoff`
+  target. A name that does not exist fails as `gh` not found: report it, never read it as a near-miss
+  for another name.
+- **It is not the standing prohibition on a bare `#N`.** What that forbids is a bare *Issue number*,
+  which resolves without complaint to a different issue of the same number; a bare *repository* name
+  whose owner is determined has no such failure mode.
+- **An explicit owner that is not the session's is a third-party target, and it stops the run.**
+  `fullrun <other-owner>/repo#12` names a tracker we do not own, and every write there is Tier C
+  (`CLAUDE.md` → "Third-party repositories are Tier C"). **Decide it mechanically** with
+  `pnpm josh repo:party <owner/repo>` — a `third-party` verdict stops the run. Typing the prefix is not the
+  explicit instruction that rule requires. **Send a `confirmation` Telegram and stop** — nothing has
+  been produced yet, so there is no finding to record and no draft to prepare.
+- **No prefix leaves the behavior exactly as it was** — the target is the session's repository.
+- **`kickoff` needs no checkout**: name the target repository in the path of every `gh api` call and
+  never clone. The one exception is the split path's epic, since `pnpm josh epic` only writes the
+  repository it runs in — run it in that repository's checkout, or fall back to `gh api
+  repos/<owner/repo>/labels …` followed by `gh api repos/<owner/repo>/issues -f title="<epic-title>" -f
+  'labels[]=epic' -f body="<body>"`, and report that `epic:check` could not be run. The promote arm has
+  no such fallback: with no checkout there, file the children and stop.
+- **The implementing entries require a checkout and never create one — when the target is another
+  repository.** A prefix naming the session's own repository changes nothing (`fullrun kit#412` in the
+  kit checkout behaves exactly as `fullrun #412`). Otherwise resolve the checkout from `pnpm josh
+  doctor`'s map; **no checkout there, or a tree that is not clean, stops the run** with a
+  `confirmation` Telegram — cloning decides the layout of someone's machine for them, and a dirty tree
+  holds work that is not yours to stash. Otherwise the commands that act on the target execute in that
+  checkout.
+- **A named epic is exempt from the whole bullet above**: `owner/repo#E` names where the *epic* lives,
+  not where its children are implemented. Its state is read against that repository through `gh api`,
+  so that repository needs no checkout. The checkout rules bind each child at implementation time,
+  against **that child's** repository ("Concurrency" in `backlogrun.md`).
+- **Independent of `into <target>`**: this says which repository the run acts on, `into` says which
+  epic the artifact joins — `kickoff kit#new into joshuafolkken/kit#909` is one correct line.

package/.claude/skills/workflow-commands/working-tree-hold.md

@@ -0,0 +1,66 @@
+# The working-tree hold — one run per tree
+
+**This is the body of `SKILL.md` §2f, relocated here so the entry read carries the trigger and the
+pointer, not the procedure** (joshuafolkken/kit#2189). `SKILL.md` §2f is the resident stub, and
+`fullrun.md` / `halfrun.md` route here for the definition. It is read at its point of use — the moment
+a run is about to claim or release the tree.
+
+**Ask `pnpm josh run:hold` before anything else, and obey what it answers.** It is the first call of
+`fullrun` and `halfrun` alike — before the title is normalized, before `git switch main`, and **before
+a `new` entry files its Issue**, because a run stopped after the filing has already left behind the
+artifact it should not have created.
+
+```bash
+pnpm josh run:hold <N>        # a `#N` entry point ; alias: josh rh
+pnpm josh run:hold            # a `new` entry point, before the issue exists
+pnpm josh run:release <N>     # that same run releasing its own record ; alias: josh rr
+pnpm josh run:release         # the bare form releases the unnumbered run's own record
+pnpm josh run:release --force # a record left behind by a run that has ended
+```
+
+- **`hold` — this run now holds the tree. Continue.**
+- **`busy` — another run holds it. Stop.** Send a `confirmation` Telegram carrying what the command
+  printed on stderr (the holder, when the record was written, and the release command) and stop.
+  **File nothing, create no branch, edit nothing.**
+- **`unknown` — nothing was established. Stop the same way.** It is not "the tree is free".
+
+**The unit is the working tree, and `epic-busy.ts` is not reused for it.** That read answers about a
+*repository* and implements `backlogrun`'s one-child-per-repository rule; what these entry points contend
+for is one branch, one index and one uncommitted diff, and a linked work tree has its own three.
+**`backlogrun`'s own guard is unchanged** — the two layers guard different resources.
+
+**`kickoff` does not claim it, and that is an exemption rather than an omission.** `kickoff` touches
+none of branch, index or uncommitted diff: it reads the Issue, normalizes the title, posts the plan,
+notifies and stops, every one of those against GitHub. It is a fact about the command rather than a
+judgement made at the entry, and it changes nothing for `fullrun` or `halfrun`.
+
+**Claim it in the checkout the run will edit.** The record is keyed to the work tree the command runs
+in, so a cross-repository `fullrun owner/repo#N` resolves that repository's checkout from `pnpm josh
+doctor` **first** — that resolution is a read and writes nothing — and claims there.
+
+**A release names the run it belongs to.** `pnpm josh run:release <N>` removes the record only where the
+record names `<N>`, the bare form only the unnumbered run's, and a record belonging to anything else
+answers **`held`** and is left standing. **`pnpm josh run:release --force` is the one spelling that
+removes a record this run did not write**, and the `busy` stop message names it rather than the
+ordinary one.
+
+**Release what the claim recorded, which is not always the Issue number.** A `#N` entry claimed `<N>`
+and releases `<N>`; a **`new` entry claimed before its Issue existed**, so it releases with the
+**bare** form however many numbers the run has acquired since — so a `fullrun new` that stops on a
+split types `pnpm josh run:release`, not `pnpm josh run:release <N>`.
+
+**Releasing is the run's, not a person's memory.** `pnpm josh followup` releases the hold on a merged
+run, and a record abandoned by a crashed session expires after 8 hours. **A stop that leaves the tree
+clean releases it explicitly**: a `fullrun` / `halfrun` that stops on a split, a prerequisite or a
+third-party target ends with `pnpm josh run:release <N>` (bare where that run entered as `new`).
+**`halfrun`'s stop before commit keeps the hold**, and so does a `needs-human-review` stop: the
+uncommitted work still in the tree is exactly what a second run would trample, so the release command
+goes in the stop report and the Telegram for the person to type. **An expired record over a tree that
+still has uncommitted changes does not free it**: the command answers `busy` and says to commit, stash,
+or release once the work is done; only an expired record over a clean tree is replaced.
+
+**The batch entry points claim per child, not per batch.** `backlogrun` never
+call it themselves; each child runs the `fullrun` procedure, so it claims on entry and `pnpm josh
+followup` releases it at that child's merge. The command's behavior and the answer table are
+`docs/josh-commands.md` → "`josh run:hold` / `josh run:release`"; this file is the single source of
+the procedure.

package/.claude-plugin/marketplace.json

@@ -0,0 +1,15 @@
+{
+	"name": "kit",
+	"description": "The joshuafolkken/kit plugin marketplace — ships kit's distributed Claude Code skills to consumer projects.",
+	"owner": {
+		"name": "joshuafolkken",
+		"url": "https://github.com/joshuafolkken"
+	},
+	"plugins": [
+		{
+			"name": "kit",
+			"source": "./.claude",
+			"description": "joshuafolkken/kit distributed skills: Issue-driven workflow commands, epic:* commands, post-dependency-update verification, the UI-verification gate."
+		}
+	]
+}

package/.coderabbit.yaml

@@ -0,0 +1,50 @@
+language: en-US
+
+reviews:
+  profile: chill
+  high_level_summary: false
+  changed_files_summary: false
+  sequence_diagrams: false
+  poem: false
+  auto_review:
+    enabled: true
+    drafts: false
+
+  finishing_touches:
+    docstrings:
+      enabled: false
+    unit_tests:
+      enabled: false
+
+  path_filters:
+    - '!src/lib/paraglide/**'
+    - '!messages/**'
+    - '!pnpm-lock.yaml'
+    - '!worker-configuration.d.ts'
+    - '!**/*.d.ts'
+    - '!drizzle/**'
+    - '!static/**'
+    - '!*.config.*'
+
+knowledge_base:
+  opt_out: true
+
+tools:
+  github-checks:
+    enabled: false
+  languagetool:
+    enabled: false
+  shellcheck:
+    enabled: false
+  markdownlint:
+    enabled: false
+  ast-grep:
+    essential_rules: false
+  biome:
+    enabled: false
+  gitleaks:
+    enabled: true
+  hadolint:
+    enabled: false
+  yamllint:
+    enabled: false

package/.codex/config.toml

@@ -0,0 +1,8 @@
+[shell_environment_policy]
+inherit = "core"
+
+[shell_environment_policy.set]
+BASH_MAX_OUTPUT_LENGTH = "8000"
+
+[mcp_servers.svelte]
+url = "https://mcp.svelte.dev/mcp"