@joshuafolkken/kit 1.1005.0 → 1.1035.0

package/.claude/settings.json

@@ -56,11 +56,7 @@
 				"hooks": [
 					{
 						"type": "command",
-						"command": "echo 'MANDATORY before writing any implementation code: present the two-layer work summary in the session language — 3 plain sentences (Now / Change / Check) a non-programmer can follow. Name the concrete subject in each line — subject-less prose is not acceptable; no file paths, function or type names, or CLI option flags — only internal identifiers are banned, not names the reader sees on screen. Then Details, then every change with its test. Ordinary markdown, never wrapped in a code fence. Required in fullrun/halfrun/backlogrun even when the Issue body was filled; presentation only, never a confirmation stop. Completion reports lead with Cause / Fix / Result. Tests are required for ALL changes; zero tests without explicit approval is a violation. Full rule: Code Change Rules Step 0 in CLAUDE.md.'"
-					},
-					{
-						"type": "command",
-						"command": "echo 'Deleting a git-tracked file is reversible, so it is NOT Tier C — do not ask for confirmation on reversibility grounds. Still inspect the target first and surface anything that contradicts the task.'"
+						"command": "echo 'MANDATORY before writing any implementation code: present the two-layer work summary (Now / Change / Check, then every change with its test). Full rule: Code Change Rules Step 0 in CLAUDE.md.'"
 					},
 					{
 						"type": "command",

package/.claude/skills/dependency-update/SKILL.md

@@ -11,8 +11,10 @@ half: what you actually run to find out whether a command already touched them,
 one change that is expected. It applies after `pnpm update`, `josh latest`, `pnpm josh overrides`,
 a Dependabot merge, or any other command that can rewrite dependency versions.
 
-The canonical extended reference is `prompts/collaboration-workflow/operating-rules.md` → the overrides protection
-section; this skill is the operational procedure, and the two must agree.
+This skill is the single source of the overrides protection's procedure;
+`prompts/collaboration-workflow/operating-rules.md` only points here. Overrides were added on
+purpose — for security, compatibility or a working guarantee (for example
+`"esbuild@<=0.24.2": ">=0.25.0"` for Workers build compatibility).
 
 ## 1. Effective overrides live in the workspace — inspect both files
 
@@ -35,7 +37,8 @@ git diff -- pnpm-workspace.yaml package.json
 and confirm the effective `overrides:` block in `pnpm-workspace.yaml` and any historical
 `pnpm.overrides` declarations in `package.json` are untouched, **and** that `devDependencies`
 versions still respect the effective overrides. If any entry was removed, modified, or bumped past
-an override, restore it immediately.
+an override, restore it immediately, investigate why it changed, and report that to the user — never
+keep the change without explicit approval.
 
 `josh latest` prints its own verdict as its last overrides line (`✔ overrides unchanged (<n> from
 <file>)`, or a `⚠ overrides changed` warning), and `pnpm josh overrides` compares effective workspace

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

@@ -6,8 +6,9 @@ description: The procedures for the `josh epic:*` commands that make an epic run
 # The `josh epic:*` commands
 
 These three commands are what turn an epic from a list of issue numbers into something a run can
-execute unattended. The canonical extended reference is `prompts/collaboration-workflow/` — `epic-bundle.md`, `epic-audit.md` and `cross-repo-epic.md` between them; this
-skill is the operational procedure, and the two must agree.
+execute unattended. **This skill is their single source**: `prompts/collaboration-workflow/` keeps
+`epic-bundle.md`, `epic-audit.md` and `cross-repo-epic.md` only as pointers here, and the history
+behind the rules is `docs/maintainers/epic-commands-rationale.md` (joshuafolkken/kit#2892).
 
 The workflow keywords themselves — `kickoff`, `fullrun`, `halfrun`, `backlogrun` — live in the
 `workflow-commands` skill.
@@ -80,9 +81,12 @@ adds is reading *inside* the children:
 | The search for those issues could not read the open backlog | **error** |
 | That search stopped before the end of the backlog | warning |
 
-**Only errors fail it.** The first check fires on a legitimate forward reference as readily as on a
-real missing dependency; failing on both would make design notes unwritable. A forward reference the
-other child *already depends on* is not reported at all.
+**Only errors fail it** (exit 1); a warning leaves the exit code alone. The first check fires on a
+legitimate forward reference as readily as on a real missing dependency; failing on both would make
+design notes unwritable, so the reader judges and the machine only keeps it from being missed. A
+forward reference the other child *already depends on* is not reported at all. Acceptance criteria
+that require what a child free to run later produces cannot be met however anyone decides, which is
+why that check is an error.
 
 **A pair with either child closed is a warning, not an error.** What makes an undeclared order a
 contradiction is that the criteria's child *can run first*, and one end closing is enough to make
@@ -92,11 +96,13 @@ audit forever, which stops every future run of that epic at the first step. It i
 dropped because dropping it hands the same pair to the first check, which reports it as an implicit
 dependency instead: the same one line, minus the detail that the name is in the acceptance criteria
 (joshuafolkken/kit#1010, widened from both-closed to either-closed by joshuafolkken/kit#1597 after a
-closed child citing an open sibling **as evidence** held an epic red at step one).
+closed child citing an open sibling **as evidence** held an epic red at step one). **The demotion
+needs the closed state confirmed**: `epic_issue.normalize_state` maps every state but `CLOSED`
+(`MERGED` included) to `OPEN`, so a state that could not be confirmed stays an error.
 
 **Fixing what it finds is Tier A** — re-pointing a dependency or correcting prose is reversible and
-will otherwise stall the work. Park with `needs-decision` only when the contradiction is a design
-choice nobody has made.
+will otherwise stall the work, so fix it without asking and record why on the issue. Park with
+`needs-decision` only when the contradiction is a design choice nobody has made.
 
 **The two `orphan search` findings are the exception, because neither is a contradiction.** They are
 about the search itself rather than about anything the children say (joshuafolkken/kit#1033):
@@ -114,6 +120,8 @@ about the search itself rather than about anything the children say (joshuafolkk
 state or artifact, list the existing code referencing that concept and confirm some child owns
 updating it. Label names are single-sourced in `scripts/git/issue-labels.ts`.
 
+History: `docs/maintainers/epic-commands-rationale.md` → "`epic:audit` — why the children are read across".
+
 ## `josh epic:next <E…>` — what is runnable
 
 Returns **every** runnable child, bundled per repository with the local checkout to run it in.
@@ -243,12 +251,12 @@ in `Dependencies` — is what a wave has to satisfy, and editing the body alone
 with nothing after it** — which is exactly what a hub is the moment the earlier wave has been chained
 into it. `chains_containing` finds several indices; `is_branching_after` does not hold, because it
 requires a successor in **every** chain naming the target and a hub has none in any of them; so
-`ambiguous_position_error` is raised (`scripts/git/git-epic-chains.ts`). **The first child of the
+`ambiguous_position_error` is raised (`scripts/epic/epic-chains.ts`). **The first child of the
 next wave therefore goes into the declaration by hand**, with its `blocked-by` recorded to match.
 Once the hub has a successor, `--after <hub>` branches a new line and the rest of that wave goes in
 with it.
 
-**Nothing in the parsing or the consistency check forbids this.** `DECLARED_CHAIN_LINE` in `scripts/git/git-epic-parse.ts`
+**Nothing in the parsing or the consistency check forbids this.** `DECLARED_CHAIN_LINE` in `scripts/epic/epic-parse.ts`
 asks only that a line be *nothing but* a chain, so there may be any number of chain lines and **one
 child may be an endpoint of several of them** — `parse_dependency_links` expands each line
 independently and flattens the result, dropping only self-loops. `find_anomalies` in
@@ -328,7 +336,11 @@ to implement.
 - **The epic auto-closes only when every cross-repository child's state could actually be read.** One
   unreadable child leaves it open, exactly as before.
 - **An epic in another repository must be referenced as `owner/repo#N`** — `backlogrun
-  joshuafolkken/kit#858 --only`. A bare `#N` resolves to *this* repository's issue of that number.
+  joshuafolkken/kit#858 --only`, `epic:next joshuafolkken/kit#858 --repo joshuafolkken/app-kit`. A
+  bare `#N` resolves to *this* repository's issue of that number. A cross-repository epic exists in
+  one repository only.
+- **`epic:next` prints each candidate's repository and local checkout** from joshuafolkken/kit#869's
+  map; a repository with no checkout prints `(no local checkout)` and is **never cloned on its own**.
 
 **A dependency that crosses a repository is not satisfied by the blocking issue closing.** Merging
 does not publish: the merge, the auto-tag and the publish run one after another, so a consumer told
@@ -341,12 +353,17 @@ default branch declares has appeared in the registry.
 wait on — so a closed blocker there resolves rather than waiting until the run's own eight-hour
 timeout with nothing an operator can edit to clear it. The answer is read from the blocker
 repository's own manifest and never from the registry: a registry 404 also means "this token may not
-see it", so resolving on one would start a consumer child before its blocker's release existed.
+see it", so resolving on one would start a consumer child before its blocker's release existed. A
+manifest read that fails (rather than answering 404) is told apart by HTTP status and still waits.
 
 **The evaluation is an AND in that order.** While the blocker is open the registry is never
 consulted, so a run never stalls on a publish from the moment it starts. The target is that exact
 version, never "something newer" — a consumer several releases behind would otherwise be satisfied by
-a publish that predates the change.
+a publish that predates the change. **A child no longer bumps the version** (joshuafolkken/kit#1486):
+the version moves only when `pnpm josh release` runs, so the target is the release that includes the
+blocker, and the default branch's version just after its merge is the previous release, which would
+satisfy the wait at once. The publish check shares `josh propagate`'s implementation; it is not
+defined twice. History: `docs/maintainers/epic-commands-rationale.md` → "Cross-repository epics".
 
 ## `josh epic:bundle <N>` — does this new issue belong with one already filed?
 
@@ -373,14 +390,18 @@ all: `repos/{owner}/{repo}/issues/<N>` serves one too, and a merged PR does not
 
 **A number that does not exist is not a gap.** A typo, or another repository's number quoted in
 prose, is dropped in silence — neither a candidate nor something the command reports it could not
-read. Reported as a gap it puts `⚠ Could not read #N.` above the verdict, and the rule below stops an
-unattended run on exactly that, for a reference that never existed (joshuafolkken/kit#957). **The two
+read. Reported as a gap it puts `⚠ Could not read #N.` above the verdict, and the could-not-answer rule
+(`prompts/review.md` → "Three-way disposition after the cap") stops an unattended run on exactly that, for a reference that never existed (joshuafolkken/kit#957). **The two
 are told apart by HTTP status, never by `gh`'s wording**: 404 is nothing at that number, 403 and 429
 are a rate limit. GitHub answers 404 for an issue the token may not see as well, so as not to leak
 its existence — which does not reach this command, because it probes the repository whose open issues
 it has just listed. The probe costs one REST request and runs **only** when a read has already
 failed, and only on the path that needs the distinction: the backlog's own relation reads, up to two
-hundred of them, never pay it.
+hundred of them, never pay it, and the referenced-number reads are capped at twenty. **Only the
+subject's own body is followed** — the reverse direction would scan every closed issue, and a
+follow-up already names its parent. The reference parsing is the same implementation as
+`epic:audit`'s implicit-dependency check, applied to the backlog instead of one epic. The open backlog
+is small enough to scan whole, so there is no index or cache.
 
 | Candidates | Do | Tier |
 | --- | --- | --- |
@@ -392,6 +413,11 @@ hundred of them, never pay it.
 | No strong signal | Nothing | — |
 | **The epic listing was cut short** | **Nothing** — every placing row above is withheld | — |
 
+**`none` is a legitimate answer** — a self-review outside any workflow has no current issue to point
+at, so the issue stays in the backlog: what the procedure requires is running the command and
+following its answer, not landing every issue in an epic. The review-cap follow-up's filing and the
+answer table it acts on are `prompts/review.md` → "Three-way disposition after the cap".
+
 **Every row that *places* the issue asserts a negative, so a cut epic listing withholds all of them**
 (joshuafolkken/kit#1697). "No epic already tracks this issue" — which `create_epic` asserts about the
 candidates too — is only as good as the listing it was read from, and an epic past the cut tracks its
@@ -399,7 +425,8 @@ children invisibly. **`add_to_epic` rests on it as much as `create_epic` does**:
 the epic a *candidate* sits in, while an unseen epic already tracks the issue itself, is the same
 duplicate by another route. The cut was already on standard error
 (`⚠ The epic listing …`) while standard output went on printing an executable
-instruction such as `Create an epic for these (Tier A — do it).` — and the rule below that reads a warning as "could not answer" is written for one above
+instruction such as `Create an epic for these (Tier A — do it).` — and the rule that reads a warning as "could not answer" (`prompts/review.md` → "Three-way
+disposition after the cap") is written for one above
 `Nothing to bundle.`, so it never reached this verdict. Acted on as Tier A, that is a **second epic
 over an already-tracked issue**, which the auto-close and `epic:next` cannot both be right about
 (joshuafolkken/kit#943). The verdict now says so itself:
@@ -462,3 +489,5 @@ Full behavior: `docs/josh-commands.md` → "`josh issue:file`".
 **When the relation carries an order, record it** in `blocked-by` and in the epic's `Dependencies` —
 on an addition as much as on a new epic. Without it the batch survives and the reason for it does
 not. An order **nobody declared is not invented**.
+
+History: `docs/maintainers/epic-commands-rationale.md` → "`epic:bundle` — why issues filed apart are bundled afterwards".

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

@@ -28,16 +28,8 @@ resident in the AI documents, because it has to hold when this skill has *not* b
 - The rule applies even when the user authorized a related workflow in an earlier turn. Each
   invocation must be re-typed by the user in the current turn.
 
-**A session cut inside a declared budget is not a new invocation.** A `backlogrun` that is cut and
-resumed is still the one invocation a person typed — the keyword authorized the declared budget, and
-the cut is an execution detail of spending it. What this rule forbids is _inferring_ a workflow from a
-request's shape. **The reading covers `backlogrun` and it alone** — a `fullrun` cut still waits for
-the keyword, because a `fullrun` ends at one issue and has nothing to carry.
-
-**`backlogrun-steps.md` → "The session cut is inside the invocation" is the single source of the
-mechanism** — the record, the two commands, and what each answer means, and how a named-issue
-`backlogrun #N1 #N2 …` pins its list to what was typed while the issues it has finished live in the
-record's `done` field rather than shrinking the string.
+**A session cut inside a declared budget is not a new invocation — for `backlogrun` alone**; its
+single source is `backlogrun-steps.md` → "The session cut is inside the invocation".
 
 ## 1. Which file to read
 
@@ -62,7 +54,7 @@ lists `backlogrun.md` alone: its parent orchestrates and never implements, so `f
 Every procedure for *running* a `backlogrun` item — lanes (`backlogrun-lanes.md`), park-and-continue,
 the guards — stays `backlogrun.md`'s. The on-demand sections `into-target.md` (an `into` suffix) and `target-repository.md`
 (an `owner/repo#` prefix) are read only when their trigger is typed, and §3's residency procedure lives
-in `rule-residency.md`, reached only when a rule is placed, moved or retired.
+in `prompts/collaboration-workflow/residency.md`, reached only when a rule is placed, moved or retired.
 
 ### The fetch is one `Read` call per file
 
@@ -251,15 +243,8 @@ there. A dispatched lane child never runs the retrospective.
 
 ## 3. What stays resident, and what is read from here
 
-**The residency criterion and its procedure are `rule-residency.md`, read only when a rule is being
-placed, moved or retired — never at any entry, and never during a run.** It carries question 0 (is the
-answer computable from mechanically readable inputs, so it is a decision oracle — `pnpm josh
-oracle:list`), the ordering question (does it decide *when or in what order* rather than *what*, so it
-goes in the run driver `pnpm josh run:step` — `prompts/collaboration-workflow/residency.md` → ordering
-question), the first question (can the trigger be named as one tool call, so the body moves out of
-`CLAUDE.md` to a hook via `prompts/collaboration-workflow/rule-delivery.md`), the second question
-(does it have to fire on a turn where no skill was loaded, so it stays in `CLAUDE.md`), and the
-procedure that decides how much of a resident rule is resident — the trigger-plus-pointer shape, the
-enumeration of every resident rule with an on-demand counterpart, and the retirement route and its
-three tests. `rule-residency.md` is the single source; the moment it binds is a turn spent editing
-these documents, never a turn spent executing an Issue.
+**The residency criterion is `prompts/collaboration-workflow/residency.md`, its single source — read
+only when a rule is being placed, moved or retired, never at any entry and never during a run.** Its
+questions are asked there in order — question 0 (`pnpm josh oracle:list`), the ordering question
+(`pnpm josh run:step`), the first and the second — beside how much of a resident rule stays and the
+retirement route; none is restated here.

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

@@ -117,8 +117,10 @@ summary is bounded the way it is".
    discretionary observation has**: a child files `route:tier-a` and `route:interrupt` only, and the
    parent files what survives — `SKILL.md` → §2i, the single source. **What the parent does with the
    rest is append it, not drop it**: an observation that cannot cite the depth-0 work it blocked
-   becomes one line in the observation ledger, and a second line under the same key files it. **The
-   child never writes that file** — it cannot tell its observation from the sibling lane's.
+   becomes one line in the observation ledger, and a second line under the same key files it. **A
+   child appends only to its own issue's file, `docs/maintainers/observations/<N>.md`, in its own
+   lane** (joshuafolkken/kit#2919) — it merges with the child's pull request, and a sibling lane's
+   file is never one it touches.
 4. **Decisions taken and why**, where the decision was not already logged as an Issue comment.
 5. **What was left undone**, and under whose authority.
 

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

@@ -27,18 +27,9 @@ therefore runs exactly one epic's children and stops.
 
 ## Explicit invocation required (MANDATORY)
 
-**Never start a `backlogrun` unless the user has typed the keyword in the current turn's prompt.**
-This is the same rule the other entry points carry, at the same strength — `SKILL.md` → §0 is its
-single source, and `CLAUDE.md` → "Explicit invocation required (MANDATORY)" is where it stays resident
-so it binds on a turn where nothing here has been read. It matters more here than anywhere else,
-because this is the entry point with the widest authorization: a conversational "clear the backlog" is
-**not** an invocation, a confirmation question is no substitute for the keyword, and an earlier turn's
-authorization does not carry.
-
-**The keystroke starts the invocation; it does not have to land in every session that invocation
-spans.** A `backlogrun` cut mid-run and resumed is still that one invocation
-(`backlogrun-steps.md` → "The session cut is inside the invocation"). This reading covers `backlogrun`
-and it alone — a `fullrun` cut still waits for the keyword.
+**Never start a `backlogrun` unless the user has typed the keyword in the current turn's prompt** —
+`SKILL.md` → "0. The rule that fires before any of them — explicit invocation"; a cut and resumed run
+is still that one invocation (`backlogrun-steps.md` → "The session cut is inside the invocation").
 
 ## The manifest — the ordered flow
 

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

@@ -55,7 +55,8 @@ that covers the same work stops the run rather than filing a second Issue (`SKIL
 `<N>`. (3) Add
 `in-progress` (as above). (4) Post the agreed plan in the session language: fill the body if blank,
 otherwise add a comment. (5) If the working tree already has staged or modified files,
-`git stash push -m "fullrun new: pre-existing changes"` first. (6) `git switch main && git pull`. (7)
+`git stash push -m "fullrun new: pre-existing changes" -- ':!docs/maintainers/observations'` first
+(joshuafolkken/kit#2919). (6) `git switch main && git pull`. (7)
 `pnpm josh latest:scope`; on `required` run `josh latest` and load the `dependency-update` skill; on
 `skip` neither runs (`latest-gate.md` is the single source). If you stashed in (5),
 `pnpm josh stash:pop "fullrun new: pre-existing changes"` — by message, never a positional `git stash
@@ -78,8 +79,8 @@ release:scope` and close the completion summary with what it answered** (`follow
 ## The release ask — the last step of either form
 
 **One call folds the post-merge bookkeeping** (joshuafolkken/kit#2372): after the merge, `pnpm josh
-run:tail <N>` commits the observation ledger (`observations:flush` — skipped by a dispatched lane child,
-whose `backlogrun` flushes once at `run:carry --end`; joshuafolkken/kit#2492), reads the completion citations
+run:tail <N>` commits ledger lines written outside any issue's run (`observations:flush`,
+joshuafolkken/kit#2919), reads the completion citations
 (`issue:cite`, given the closed issue and any follow-ups filed this run) and decides the release scope
 (`release:scope`) in one round trip, joining each under its own header. **On the clean path `run:tail`
 runs inside `pnpm josh ship`** as its report step (joshuafolkken/kit#2398), so it is a standalone call

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

@@ -46,7 +46,7 @@ call reports `hold`.
    `pnpm josh latest:scope` — update dependencies only on `required` (`latest-gate.md`), never on every
    run. `run:step` names every later action in order — the verification gate, `pnpm josh followup`,
    `pnpm josh ms`, the release ask — each read at the point-of-use doc the header lists, never
-   re-narrated here (`residency.md` → ordering question).
+   re-narrated here (`residency.md` → "順序の問い").
 
 ## The progress step and the lane-child seam
 

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

@@ -59,7 +59,8 @@ back with fixes, treat each as a new round: implement, re-run `pnpm josh gate`,
 mirror `fullrun new` (1)–(8): derive an English title (or use the provided one) → create the Issue
 (`pnpm josh issue:file "<title>" --body-file <body-file> --depth <n>`, body per
 `prompts/collaboration-workflow/issue-template.md`; its duplicate scan is read per `SKILL.md` → §2e) → add `in-progress` → post the agreed plan → stash
-any pre-existing changes with `git stash push -m "halfrun new: pre-existing changes"`, popped by
+any pre-existing changes with `git stash push -m "halfrun new: pre-existing changes" -- ':!docs/maintainers/observations'`
+(the pathspec keeps the observation ledger in the tree for this run's commit; joshuafolkken/kit#2919), popped by
 message with `pnpm josh stash:pop "halfrun new: pre-existing changes"`, never a positional `git stash pop` →
 `git switch main && git pull` → `pnpm josh latest:scope` → implement → run the gate (as above, `pnpm
 josh test:e2e` run by **you**) → `pnpm josh run:hold <N> --halfrun-stop` → send the `confirmation`

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

@@ -39,7 +39,7 @@ new epic" when what gets created is often a single Issue.
   applies depends on what the target is, and promoting rewrites someone else's Issue into a container.
 - **A cross-repository target is written `owner/repo#N`** and inserted from that repository's
   checkout; run there, since `epic --add` reads and writes only the repository it runs from
-  (`prompts/collaboration-workflow/cross-repo-epic.md`). A bare `#N` resolves to this repository's
+  (`.claude/skills/epic-commands/SKILL.md` → "Epics that span repositories"). A bare `#N` resolves to this repository's
   issue of that number.
 - **No suffix leaves the behavior exactly as it was.**
 

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

@@ -175,10 +175,15 @@ joshuafolkken/kit#1726 is the worked case: its own body says the depth test woul
 and it was filed anyway, because **discarding it was the only alternative on offer**
 (joshuafolkken/kit#1728).
 
-- **The destination is `docs/maintainers/observations.md` in the repository the observation is about** — the same
-  repository the Issue would have been filed into. **The count and the append are both run in that
-  repository's checkout**, resolved the way §2c (`target-repository.md`) resolves any cross-repository target, and the file is
-  created on the first append where that repository has none. **The subject decides, never the
+- **The destination is the `docs/maintainers/observations/` directory in the repository the
+  observation is about** — the same repository the Issue would have been filed into — **one file per
+  issue** (joshuafolkken/kit#2919): append to `<N>.md` for the issue the run is executing (the number
+  its branch leads with, a lane's included), or to `<YYYY-MM-DD>.md` for a line written on the
+  default branch outside any issue's run. Parallel lanes therefore write different files, and their
+  pull requests never conflict on the ledger. **The count and the append are both run in that
+  repository's checkout** — in this repository, the work tree the run is in, a lane's inside a lane —
+  resolved the way §2c (`target-repository.md`) resolves any cross-repository target, and the
+  directory is created on the first append where that repository has none. **The subject decides, never the
   working directory**: an observation about this package's own orchestration, seen while a run is
   inside a repository that consumes it, is recorded here rather than there — the append follows the
   subject, never the working directory. **A third-party target gets no line either** — Tier C covers
@@ -186,8 +191,8 @@ and it was filed anyway, because **discarding it was the only alternative on off
 - **It is append-only.** A line is never edited and never deleted, because the count of lines
   carrying one key is what says whether an observation has recurred; a second sighting is a second
   line, not a rewrite of the first. **A merge conflict in it is resolved by keeping both sides** —
-  two lanes appending at once is the ordinary case, and a repeated key is the whole signal, so
-  dropping either side destroys exactly what the file is for.
+  one file per issue should keep it from arising, but a repeated key is the whole signal, so
+  dropping either side destroys exactly what the ledger is for.
 - **The completion report keeps its line too.** The ledger is what the next run can read; the report
   is what this run's reader sees. Neither replaces the other.
 - **The append is not the end of it** — a line only becomes readable to anyone else once it has
@@ -215,21 +220,22 @@ A sample, in the shape a real entry takes:
 ```
 
 **`k:example` is reserved for this sample and is never used by a real observation**, so the count
-below can be run over the whole file without the sample answering for one. **The grammar is defined
+below can be run over the whole ledger without the sample answering for one. **The grammar is defined
 here rather than in the ledger** because this skill is distributed to every repository that consumes
 the package and `docs/` is not — a rule that named a definition the reader never received would
 leave every consumer's ledger shaped by hand.
 
 **The identity key is the whole of the repeat test — never a similarity judgement about the prose.**
 Choose the key from the phenomenon rather than from the run, then count what the ledger already holds
-for it, in that repository's checkout rather than the working directory. **The `|| true` is not
-decoration**: `grep -c` exits non-zero on a count of zero, which is the first-sighting branch and the
-common one, so without it the step reads as a failed command wherever an exit status is being
-watched. **A missing file is not a count of zero, though** — there `grep` exits 2 and prints no
-number at all, so an empty answer means create the ledger, never that this is a first sighting.
+for it, in that repository's checkout rather than the working directory. **Every file of the
+directory is counted**, because a recurrence is a recurrence whichever issue's file each sighting
+sits in. **The `|| true` is not decoration**: `grep -c` exits non-zero on a count of zero, which is
+the first-sighting branch and the common one, so without it the step reads as a failed command
+wherever an exit status is being watched. **A missing directory is still a first sighting** — `cat`
+complains on standard error and the count is zero; the append below creates the directory.
 
 ```bash
-grep -c '^- k:<slug> |' <that repository's checkout>/docs/maintainers/observations.md || true
+cat <that repository's checkout>/docs/maintainers/observations/*.md | grep -c '^- k:<slug> |' || true
 ```
 
 Free-text comparison is what the key exists to replace, so two lines that read alike under different
@@ -254,7 +260,7 @@ that is empty on every other machine**, and every sighting was a first one, whic
 joshuafolkken/kit#1728 created the ledger to end.
 
 - **A run's appended lines ride its own commit** (joshuafolkken/kit#2763). `pnpm josh git` stages
-  `docs/maintainers/observations.md` with the run's other changes, in the one staging step every entry
+  `docs/maintainers/observations/` with the run's other changes, in the one staging step every entry
   point goes through (`scripts/git/git-staging.ts`), so the lines are reviewed and merged with the
   pull request of the run that recorded them, and the run's CI is the only wait they cost. Until
   #2763 the ledger was excluded there (joshuafolkken/kit#1756) and every run that appended a line
@@ -263,35 +269,28 @@ joshuafolkken/kit#1728 created the ledger to end.
   before `pnpm josh git -y` is carried; the time while CI runs is for the records that need no CI
   result — filing an observation Issue, drafting the completion report.
 - **A line that breaks the grammar is not carried** (joshuafolkken/kit#2123). The staging step parses
-  the ledger first — after moving lines still on the old path (joshuafolkken/kit#2724) — and on a
-  broken line leaves the ledger out of the commit and says so; the commit itself goes ahead.
-- **What no run's commit carried is flushed as a pull request of its own** — `pnpm josh
-  observations:flush`: a lane's lines (next bullets) and a line appended after the commit, such as a
-  second review round's record. It stages that one path and nothing else, commits it on a branch of
-  its own, opens a docs-only pull request, waits on the same required checks every other pull request
-  waits on, merges it and returns the checkout to the default branch. **Nothing is committed to the
-  default branch directly.**
-- **`pnpm josh followup` runs that flush itself, so no run has to remember to** (joshuafolkken/kit#1810).
-  After the merge and before it releases the working-tree hold, `followup` reads the tree, and **only
-  when the ledger still holds a pending append** returns the checkout to the default branch
-  (`pnpm josh ms`) and flushes. A run whose lines rode its commit pays nothing, and a lane skips it
-  (next bullet). A flush that fails is reported and does not take the merge, the epic close or the
-  hold release down with it. **A side effect: on a run that did flush, `followup` ends on the default
-  branch.**
-- **A lane's writers use the primary checkout's ledger** (joshuafolkken/kit#2419): a lane refuses
-  `pnpm josh ms`, so its own copy had no way out. `pnpm josh observations:flush` acts on the primary
-  checkout from a lane. **A dispatched lane child does not flush at all** (joshuafolkken/kit#2492): its
-  `run:tail` skips the step, and the `backlogrun` flushes every lane's lines once, in one pull request,
-  at `pnpm josh run:carry --end`.
-- **A lane child's pull request does not carry the lines, and that is deliberate.** Lanes run side by
-  side, and two pull requests that each append at the ledger's tail conflict with each other the
-  moment the first merges — a conflict ends the other's CI wait. The batch's single flush at
-  `run:carry --end` is already one pull request per batch, not one per child.
-- **Run by hand it goes in the primary checkout, once per cycle rather than once per observation** —
-  but with the lines riding the run's commit and `pnpm josh followup` flushing the rest (above), a hand
-  run is the exception rather than the rule. It refuses off the default branch and refuses a working tree holding anything besides
-  the ledger, so a run in progress cannot be flushed out from under, and a lane's checkout is never
-  the one it acts on.
+  every file of the ledger first — after moving lines still on an old single-file path
+  (joshuafolkken/kit#2724, joshuafolkken/kit#2919) — and on a broken line leaves the ledger out of the
+  commit and says so; the commit itself goes ahead.
+- **`pnpm josh followup` commits a line appended after the run's commit onto the pull request, before
+  the merge** (joshuafolkken/kit#2919) — a second review round's record is the usual case. After the
+  merge gates and before the CI wait, `followup` reads the tree and, **only when the ledger holds a
+  pending append**, stages the ledger paths alone, commits them and pushes the branch; the CI wait
+  that follows covers the pushed commit. A broken line refuses the merge, because the line would
+  otherwise be lost with the branch. A run whose lines rode its commit pays nothing.
+- **A lane carries its own lines, in its own pull request** (joshuafolkken/kit#2919). Its writers
+  append to its own tree's `<N>.md`, so the two steps above take them to the default branch exactly as
+  they do for a run in the primary checkout. Lanes once wrote to the primary checkout's single file
+  instead (joshuafolkken/kit#2419) and a `backlogrun` flushed them all at `run:carry --end`
+  (joshuafolkken/kit#2492); another run's stash of that checkout took the lines before the flush saw
+  them, so neither route remains. **Nothing is held in the primary checkout for later.**
+- **`pnpm josh observations:flush` is left for a line written outside any issue's run** — the
+  date-named file a retrospective or a hand append on the default branch writes. It stages the ledger
+  and nothing else, commits it on a branch of its own, opens a docs-only pull request, waits on the
+  same required checks every other pull request waits on, merges it and returns the checkout to the
+  default branch; a single run's `run:tail` runs it after the merge. It refuses off the default branch
+  and refuses a working tree holding anything besides the ledger, so a run in progress cannot be
+  flushed out from under. **Nothing is committed to the default branch directly.**
 - **Nothing to flush is an answer, not a failure.** With the ledger matching the commit it sits on
   the command prints `clean` and exits 0 — most cycles append nothing, and a command that errored
   there would be one nobody runs.

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

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

package/.codex/hooks.json

@@ -41,11 +41,7 @@
 				"hooks": [
 					{
 						"type": "command",
-						"command": "echo 'MANDATORY before writing any implementation code: present the two-layer work summary in the session language — 3 plain sentences (Now / Change / Check) a non-programmer can follow. Name the concrete subject in each line — subject-less prose is not acceptable; no file paths, function or type names, or CLI option flags — only internal identifiers are banned, not names the reader sees on screen. Then Details, then every change with its test. Ordinary markdown, never wrapped in a code fence. Required in fullrun/halfrun/backlogrun even when the Issue body was filled; presentation only, never a confirmation stop. Completion reports lead with Cause / Fix / Result. Tests are required for ALL changes; zero tests without explicit approval is a violation. Full rule: Code Change Rules Step 0 in CLAUDE.md.'"
-					},
-					{
-						"type": "command",
-						"command": "echo 'Deleting a git-tracked file is reversible, so it is NOT Tier C — do not ask for confirmation on reversibility grounds. Still inspect the target first and surface anything that contradicts the task.'"
+						"command": "echo 'MANDATORY before writing any implementation code: present the two-layer work summary (Now / Change / Check, then every change with its test). Full rule: Code Change Rules Step 0 in CLAUDE.md.'"
 					},
 					{
 						"type": "command",

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

@@ -36,7 +36,7 @@ jobs:
           fetch-depth: 0 # Shallow clones should be disabled for a better relevancy of analysis
       - name: SonarQube Scan
         if: env.SONAR_TOKEN != ''
-        uses: SonarSource/sonarqube-scan-action@ba9859eae8dd6bd29e412f25ddbbef3d032000f4 # v8.2.2
+        uses: SonarSource/sonarqube-scan-action@d209202bc7d53ff1cc128f7f907dac145c9d6ae9 # v8.3.0
         with:
           # Wait for the SonarCloud Quality Gate and fail this job (a required PR check) when the
           # gate is red, so a PR that introduces a Maintainability / code-smell finding cannot be

package/AGENTS.md

@@ -1,29 +1,8 @@
 # Agent Instructions
 
 > **All rules for this repository live in [`CLAUDE.md`](./CLAUDE.md). Read it in full before doing
-> any work here, and follow every rule in it.** This file exists only to point at it.
+> any work here, and follow every rule in it.** This file exists only to point at it. Nothing in
+> `CLAUDE.md` is Claude-specific — it applies to whatever agent is doing the work.
 
-`CLAUDE.md` is the single source. It is named for the tool that reads it by default, but nothing in
-it is Claude-specific — the naming conventions, quality limits, code-change rules, verification
-gate, git rules and collaboration workflow apply to whatever agent is doing the work.
-
-Rules that only apply while a particular command is running are not in `CLAUDE.md` either. It routes
-to them, and the routing is part of the rules: read the `<name>` skill when
-`CLAUDE.md` tells you to, and `prompts/*.md` when it names one.
-
-There is no include directive here, only the sentence above. `GEMINI.md` carries an `@CLAUDE.md`
-line because Gemini CLI documents that syntax; the tools that read `AGENTS.md` document no
-equivalent, so inventing one would put a line in this file that no reader acts on. **The pointer is
-therefore prose an agent has to act on, and it has not been verified against Codex or Cursor** —
-only Claude is in use here, and that decision is recorded in joshuafolkken/kit#970 under
-`## Decisions`.
-
-## Why this file is a pointer
-
-`AGENTS.md`, `GEMINI.md` and `CLAUDE.md` used to be three near-identical copies of the same rules,
-which meant one rule change had to be written three times and reviewed three times
-(joshuafolkken/kit#963). That is the clone the rules themselves prohibit — see "No clones —
-single-source" in `CLAUDE.md` — so the rules were single-sourced and these two became pointers.
-
-**Do not copy rules back into this file.** A rule added here is a fourth place to forget to update.
-Every change to how agents work in this repository belongs in `CLAUDE.md`.
+**Do not copy rules back into this file.** Every change to how agents work in this repository belongs
+in `CLAUDE.md`.