@rungs/cli 0.3.0 → 0.4.0

package/modules/README.md

@@ -84,9 +84,27 @@ whether its guard has ever actually fired.
    `consumed_by = "render"` — `instructions.harnesses` decides which harnesses exist and will never
    appear in a template. A dead-parameter lint that does not know the difference reports the second
    kind as unused, and the obvious "fix" deletes it.
-3. **`[provenance]` is required and validated.** Sources, patterns, and the incident. A module with
-   no traceable source is one somebody invented, and `doctor` cannot ask its questions without the
-   incident ([ADR-0005](../docs/decisions/ADR-0005-self-instrumentation.md)).
+3. **`[provenance]` is required and validated, and it declares which kind of module this is.** A
+   module with no traceable source is one somebody invented, which is what
+   [CLAUDE.md](../CLAUDE.md)'s evidence rule exists to prevent — so say which you are writing.
+   `kind = "extracted"` is the default and the shape all fifteen bundled modules use: `sources`,
+   `patterns` and `incident`, all required. `kind = "designed"` requires a first-person `rationale`
+   and **may not carry `sources` or `incident` at all**, because half a claim reads to a later
+   reader exactly like a whole one. `patterns` stays allowed for both: the catalogue entries are
+   themselves evidenced, and citing one claims nothing about this module's own history.
+3a. **The `designed` marker is printed, not merely stored.** `rungs modules` and `rungs add` both
+   name it wherever they name the module. This matters more than it looks: `[provenance]` is
+   validated at load and **read by no other code path**, so without a surface the distinction would
+   be a field nobody sees — which is rule 3's own failure mode wearing a new hat (F-037, F-038).
+   Note what this rule used to claim, and did not check: that `doctor` cannot ask its
+   [ADR-0005](../docs/decisions/ADR-0005-self-instrumentation.md) tier B question without the
+   incident. It can. That question quotes the **gate's `why`**, which `add` copies into
+   `.ai/gates.toml` — a different field, in a different file, that has always been the one doing
+   the work.
+3b. **`[conflicts]` is enforced by `add`, and the relation is symmetric.** Declaring
+   `conflicts = ["backlog"]` refuses the install and stops, the way a paradigm does, overridable
+   with `--confirm-conflict`. Only one side ever has to declare it — a module authored outside this
+   package can name a bundled one, and the bundled one will never name it back.
 4. **Skills stay spec-pure.** Six Agent Skills fields; Claude Code extensions are opted into in
    `module.toml`, per skill, with the portability cost stated there.
 5. **Every gate declares a self-test asserting both directions.** A gate whose rules are currently
@@ -131,6 +149,10 @@ whether its guard has ever actually fired.
    WI-001, where the same inference existed as a comment beside a `""` default, was implemented
    nowhere, and shipped a dangling `# AGENTS.md — ` into every scaffold. **A default that states
    its own derivation is checkable; a comment that states it is not.**
+9b-ii. **`rungs` is the other reserved namespace.** `{{rungs.version}}` is read from the executing
+   package's manifest and cannot be set by a module or consumer. It lets generated launchers pin the
+   artifact that emitted them without freezing that version as an install parameter: explicitly
+   running a newer CLI makes the managed launcher stale, and `upgrade --apply` advances it.
 9c. **A path parameter may contain separators**, so one parameter places a whole subtree —
    `files/{{path}}/README.md` with `path = "docs/decisions"`. A second "leaf" parameter is never
    needed, and adding one was caught and reverted during authoring.

package/modules/adr/files/{{path}}/README.md

@@ -9,7 +9,7 @@ it is superseded by a new record that names it.
 ## Index
 
 <!-- rungs:begin adr-index -->
-<!-- Generated by `rungs render`. -->
+<!-- Generated by `node .ai/rungs.mjs render`. -->
 
 | ADR | Title | Status | Date |
 | --- | --- | --- | --- |

package/modules/adr/gates/adr.toml

@@ -8,7 +8,7 @@ block   = { file = "{{path}}/README.md", marker = "adr-index" }
 derives = "file-index"
 sources = ["{{path}}/{{id_prefix}}-*.md"]
 columns = ["id", "title", "status", "date"]
-command = "rungs render"
+command = "node .ai/rungs.mjs render"
 
 # ── adr-required-fields ───────────────────────────────────────────────────────
 

package/modules/adr/module.toml

@@ -1,6 +1,6 @@
 [module]
 name    = "adr"
-version = "1.1.0"
+version = "1.2.0"
 rung    = 1
 summary = "Numbered, immutable decision records, with an admission rule that keeps the directory from becoming a second documentation tree."
 

package/modules/audit/fragments/AGENTS.md

@@ -1,8 +1,8 @@
-<!-- rungs:begin audit@1.0.0 -->
+<!-- rungs:begin audit@1.1.0 -->
 ## Assessments
 
 **`/assess`** checks one {{subject}} against [`{{criteria_path}}`]({{criteria_path}}) and writes
 each failure as a **row in the findings register**. Never a document per subject — that shape
-reached 268 files in one repo with no way to say which findings were open, and `rungs check`
+reached 268 files in one repo with no way to say which findings were open, and `node .ai/rungs.mjs check`
 refuses it re-forming.
 <!-- rungs:end audit -->

package/modules/audit/module.toml

@@ -1,6 +1,6 @@
 [module]
 name    = "audit"
-version = "1.0.0"
+version = "1.1.0"
 rung    = 2
 summary = "A repeatable assessment whose output is rows in the findings register, never a document per subject."
 

package/modules/audit/skills/assess/SKILL.md

@@ -39,7 +39,7 @@ Each failure is one row: severity from the criteria table, what specifically fai
 (a path, a symbol, a command), when to act, how to fix.
 
 **Do not produce an audit document.** One repo in the corpus generated 268 of them and still cannot
-say which findings are open — the prompt was fine, the output form was the defect. `rungs check`
+say which findings are open — the prompt was fine, the output form was the defect. `node .ai/rungs.mjs check`
 refuses the document tree from re-forming.
 
 ## 4. Report the run itself

package/modules/backlog/files/docs/{{root}}/BACKLOG.md

@@ -7,7 +7,7 @@ The board. One row per live work item, grouped by status. Items live in
 [`items/`](items/); finished work moves to [`archive/`](archive/).
 
 <!-- NEXT-ID: {{id_prefix}}-001 -->
-<!-- Claim from this marker and bump it on your own branch. `rungs check` refuses a duplicate. -->
+<!-- Claim from this marker and bump it on your own branch. `node .ai/rungs.mjs check` refuses a duplicate. -->
 
 ## In progress
 

package/modules/backlog/files/docs/{{root}}/README.md

@@ -91,14 +91,14 @@ An epic (`type: epic`) has no branch of its own. Membership is a **two-way link*
 ## 8. Archiving
 
 `items/` should hold only work that can still change. Move finished items to `archive/` with
-`rungs backlog archive` — it recomputes every link repo-wide, so archived ids still resolve and
+`node .ai/rungs.mjs backlog archive` — it recomputes every link repo-wide, so archived ids still resolve and
 stay permanently spent.
 
 **Never edit an archived item.** If archived work turns out to be wrong, that is a *new* item.
 
 ## 9. What keeps this true
 
-Three gates, run by `rungs check`:
+Three gates, run by `node .ai/rungs.mjs check`:
 
 | Gate | Refuses |
 | --- | --- |

package/modules/backlog/files/docs/{{root}}/archive/README.md

@@ -6,7 +6,7 @@
 Finished work items, moved here so [`../items/`](../items/README.md) holds only work that can still
 change.
 
-Move them with `rungs backlog archive`, never by hand — it recomputes every link repo-wide, and
+Move them with `node .ai/rungs.mjs backlog archive`, never by hand — it recomputes every link repo-wide, and
 archived ids stay indexed so citations to them keep resolving and the ids stay permanently spent.
 
 **Never edit an archived item.** If archived work turns out to be wrong, that is a new item. The

package/modules/backlog/files/docs/{{root}}/items/README.md

@@ -7,7 +7,7 @@ One file per work item: `{{id_prefix}}-###-slug.md`, from
 [`../TEMPLATE.md`](../TEMPLATE.md).
 
 This directory holds **only work that can still change.** Finished items move to
-[`../archive/`](../archive/) with `rungs backlog archive`, which recomputes every link repo-wide so
+[`../archive/`](../archive/) with `node .ai/rungs.mjs backlog archive`, which recomputes every link repo-wide so
 archived ids still resolve and stay permanently spent.
 
 Never edit an archived item. If archived work turns out to be wrong, that is a new item.

package/modules/backlog/fragments/AGENTS.md

@@ -1,9 +1,9 @@
-<!-- rungs:begin backlog@1.0.0 -->
+<!-- rungs:begin backlog@1.2.0 -->
 ## Work tracking
 
 Non-trivial work is a **work item** (`{{id_prefix}}-###`) under
 [`docs/{{root}}/`](docs/{{root}}/README.md) — that file is the methodology and is mandatory reading
 before your first item. Branch `{{branch_prefix}}/{{id_prefix}}-###-slug` off
 `{{integration_branch}}`; claim ids from `NEXT-ID` on your own branch; never scope-creep an item.
-Status must agree with git, and `rungs check` enforces it. Execute one with **`/work-item`**.
+Status must agree with git, and `node .ai/rungs.mjs check` enforces it. Execute one with **`/work-item`**.
 <!-- rungs:end backlog -->

package/modules/backlog/module.toml

@@ -1,6 +1,6 @@
 [module]
 name    = "backlog"
-version = "1.1.0"
+version = "1.2.0"
 rung    = 1
 summary = "Work items with stable ids, an eight-status lifecycle, a board, and the three gates that keep the bookkeeping honest."
 

package/modules/backlog/skills/work-item/SKILL.md

@@ -64,7 +64,7 @@ Status → `in_progress`.
 Run the narrowest validation that covers what you touched, then the repo's standard gate set:
 
 ```bash
-rungs check
+node .ai/rungs.mjs check
 ```
 
 Existing tests are not weakened to make a change pass. If a test is genuinely wrong, that is its

package/modules/ci/files/{{workflow_path}}

@@ -28,7 +28,7 @@ jobs:
           node-version: '22'
 
       # Runs every gate in .ai/gates.toml — the same set, in the same order, as
-      # `rungs check` locally. A CI-only gate is one nobody can reproduce.
+      # `node .ai/rungs.mjs check` locally. A CI-only gate is one nobody can reproduce.
       #
       # Plain `check`, no flags. This said `check --tier full --reporter github`:
       # `--tier` is not a flag the CLI accepts and `--reporter` does not exist at
@@ -38,7 +38,7 @@ jobs:
       # that installed `ci` had a job that failed on every push and blamed the
       # repo for it (F-030).
       - name: Run gates
-        run: npx @rungs/cli check
+        run: node .ai/rungs.mjs check
 
   # Add a matrix job per package here rather than a workflow per package.
   # A checklist step that creates a file creates N files:
@@ -47,5 +47,5 @@ jobs:
   #     matrix:
   #       package: [a, b, c]
   #
-  # `rungs check` reports the workflow count and fails past the threshold in
+  # `node .ai/rungs.mjs check` reports the workflow count and fails past the threshold in
   # .ai/gates.toml, for exactly that reason.

package/modules/ci/module.toml

@@ -1,6 +1,6 @@
 [module]
 name    = "ci"
-version = "1.1.0"
+version = "1.2.0"
 rung    = 1
 summary = "One workflow that runs the gate registry, a matrix instead of a file per item, and a check that keeps it that way."
 

package/modules/concurrency/files/docs/concurrent-sessions.md

@@ -14,11 +14,11 @@ branch, and they cannot see each other's work.**
 
 | | |
 | --- | --- |
-| `rungs session start <branch>` | Cuts from `{{green_prefix}}<branch>` — the last merge that was actually verified — not the tip. Falls back to the tip and **says so** |
-| `rungs check` | The fast tier. Run it constantly |
-| `rungs preflight` | The integration branch moved: did it change files *you* changed? That, not the commit count, predicts a conflict |
-| `rungs land <branch>` | merge → verify **the merged tree** → fast-forward → move the green ref |
-| `rungs worktrees` | What is finished and prunable. **Reports only** — removing someone else's worktree is not a script's call |
+| `node .ai/rungs.mjs session start <branch>` | Cuts from `{{green_prefix}}<branch>` — the last merge that was actually verified — not the tip. Falls back to the tip and **says so** |
+| `node .ai/rungs.mjs check` | The fast tier. Run it constantly |
+| `node .ai/rungs.mjs preflight` | The integration branch moved: did it change files *you* changed? That, not the commit count, predicts a conflict |
+| `node .ai/rungs.mjs land <branch>` | merge → verify **the merged tree** → atomically advance integration and green refs |
+| `node .ai/rungs.mjs worktrees` | What is finished and prunable. **Reports only** — removing someone else's worktree is not a script's call |
 
 ## Do not run the full tier before landing
 
@@ -35,10 +35,17 @@ deliberate question, never as a ritual.
 
 ## A failure is attributed, never just counted
 
-`land` re-runs each failing gate against the merge base in the throwaway worktree it already has,
-and reports each failure as **inherited** (already red before you started — stated, never blocking)
-or **INTRODUCED** (yours — blocks). Anything it cannot attribute also blocks: **we do not land on an
-unknown.**
+`land` re-runs each failing gate against the merge base in the throwaway worktree it already has.
+A finding is **inherited** only when one independent control reproduces it too: the invoking
+worktree must be clean, detached and at the exact integration commit. That checkout can retain
+ignored dependencies a fresh worktree does not have. If the exact control passes while the scratch
+fails, the scratch runtime is **UNVERIFIED**, not evidence that the branch inherited a red gate.
+An attached, dirty or different-commit invoking worktree cannot be the control, so a scratch
+failure then blocks and the merge is parked for recovery.
+
+With that control established, each failure is reported as **inherited** (already red before you
+started — stated, never blocking) or **INTRODUCED** (yours — blocks). Anything it cannot attribute
+also blocks: **we do not land on an unknown.**
 
 Attribution is **per finding, not per gate.** The first implementation compared gate ids, which
 made an already-red gate a blind spot: a branch could add new broken links and land them as
@@ -54,22 +61,63 @@ fix is a gate you learn to bypass, and a bypassed gate reports nothing.*
 
 ## Land, then move the tip — in that order
 
-`land` merges into a scratch `{{integ_prefix}}…` ref, verifies **that** tree, and only then
-fast-forwards with a compare-and-swap. Two things follow:
+`land` merges in a detached scratch worktree, verifies **that** tree, and only then advances the
+integration and green refs together in one expected-old transaction. Both writes target the exact,
+direct stored refs without following symbolic refs. Two things follow:
 
 - **The integration branch cannot go red from a merge nobody verified** — the ref update is
-  unreachable otherwise, and a refusal leaves it bit-for-bit unchanged with the merged tree parked
-  for you to fix.
+  unreachable otherwise, and a refusal does not partially advance integration or its verified
+  marker. The merged tree is kept for you to fix.
 - **Concurrent landing is refused, not silently merged.** A real lock names its holder and start
-  time and is taken over if the holder died.
-
-**Nothing keeps the integration branch checked out.** If something needs it checked out, that is a
-bug in whatever it is doing.
+  time and is taken over if the holder died. Git also compares both managed refs with the values
+  captured before verification; a competing change wins without being overwritten.
+
+**Nothing keeps the integration or green ref checked out.** `land` refuses before gates if a
+worktree holds either one, then checks exact ref identity and holders again after arbitrary gate
+code and immediately before the transaction. Case-aliased and symbolic configured refs are
+rejected because their spelling can otherwise make checkout discovery and ref mutation disagree.
+A worktree branch spelling that collides by the same Windows/APFS key counts as a holder even when
+its branch ref is dangling, so Rungs will not create a differently spelled managed or recovery ref
+behind that worktree's stale index and files.
+
+Rungs queries the repository's ref backend before checking raw stored refs. Git versions that
+predate that query are files-only and may either reject the option or echo it while exiting zero;
+both responses use the files scanner. An actual backend other than `files` or `reftable` is refused
+until Rungs can enumerate it safely.
+
+There is one deliberately narrow raw-Git boundary. After the last identity check but before Git
+takes a lock, another process can replace a validated direct ref with a same-object-ID symbolic ref,
+or create a dangling symbolic ref at the recovery name Rungs is about to create. Git's public ref
+transaction compares object IDs (or absence), not direct-versus-symbolic type. `--no-deref`
+protects the symbolic target. Supported Git versions differ on whether create-only refuses a
+dangling symbolic name or replaces the name itself, so Rungs cannot rely on one portable ref-type
+precondition. Do not mutate managed or recovery refs outside the Rungs land protocol; closing these
+micro-windows requires a cooperative repository-wide transaction protocol, not another
+before/after check.
+
+## Recovery refs are retained
+
+When a verified merge cannot advance, `land` reports the exact branch that preserves it. The
+preferred name is `{{integ_prefix}}<branch>`. If that branch is checked out or already preserves
+different work, Rungs creates a collision-free name containing the full merge identity instead.
+Creation is compare-and-swap and never follows a symbolic ref.
+
+Within that cooperative protocol, Rungs never overwrites or deletes an observed recovery branch,
+including after a later successful land. Cleanup is an explicit operator decision: inspect the
+reported ref and every worktree holding it, then delete it only when its work is no longer needed.
+Repeating the same refused land reuses an unheld recovery ref that already points at the identical
+merge instead of accumulating duplicates.
 
 ## Three things to know when a land refuses
 
 - **Your worktree is untouched.** `land` does all its work in a throwaway worktree of its own, so
   whatever you had checked out is still checked out. A refusal costs you nothing to recover from.
+- **Use the recovery ref that the refusal reports.** Its name can carry a merge-identity suffix when
+  the preferred `{{integ_prefix}}…` name is held or contains other work. Do not assume the preferred
+  name was changed, and remove recovery refs only after inspecting them.
+- **Run from the detached integration checkout when inherited red is possible.** All-green merges
+  need no baseline control. A failing scratch can be attributed as inherited only when the invoking
+  worktree is clean, detached and still at the integration commit with its gate runtime available.
 - **Check the exit code of `land` itself.** Piping it through `tail` or `grep` reports *that*
   command's status, so a refused land reads as success.
 - **Reconcile generated artifacts by regenerating, never by merging text.** Take one side, re-run
@@ -88,6 +136,6 @@ scheduling instead.
 
 ## Worktree lifetime is item lifetime
 
-Delete the branch when it lands. `rungs worktrees` measures whether that happened and flags
+Delete the branch when it lands. `node .ai/rungs.mjs worktrees` measures whether that happened and flags
 worktrees that are merged and clean — and, more usefully, ones that are merged **and dirty**, where
 uncommitted work is sitting in a branch that has already landed.

package/modules/concurrency/fragments/AGENTS.md

@@ -1,10 +1,11 @@
-<!-- rungs:begin concurrency@1.0.0 -->
+<!-- rungs:begin concurrency@1.4.0 -->
 ## Concurrent sessions
 
 Many sessions share `{{integration_branch}}` and cannot see each other — see
-[`docs/concurrent-sessions.md`](docs/concurrent-sessions.md). Cut with `rungs session start`
+[`docs/concurrent-sessions.md`](docs/concurrent-sessions.md). Cut with `node .ai/rungs.mjs session start`
 (from the last **verified** merge, not the tip), run the fast tier constantly, and land with
-`rungs land` — **never `git merge` by hand**. Do not run the full tier before landing: it widens
+`node .ai/rungs.mjs land` — **never `git merge` by hand**. Do not run the full tier before landing: it widens
 the window the merge then conflicts in. Reconcile generated artifacts by **regenerating**, never
-by merging text.
+by merging text. Keep the integration and green refs out of every worktree while landing. A refused
+land reports the exact recovery ref it preserved; Rungs never deletes that ref for you.
 <!-- rungs:end concurrency -->

package/modules/concurrency/fragments/gitattributes

@@ -1,5 +1,5 @@
-# rungs:begin concurrency@1.0.0
-# Merge drivers per conflict class. INERT until `rungs setup git` installs them — the driver names
+# rungs:begin concurrency@1.4.0
+# Merge drivers per conflict class. INERT until `node .ai/rungs.mjs setup git` installs them — the driver names
 # below mean nothing to git on a fresh clone, and merges quietly fall back to the default. For a
 # generated artifact that default is a clean text merge of a file that is a fixed point of nothing.
 

package/modules/concurrency/gates/concurrency.toml

@@ -6,7 +6,7 @@
 refuse_checked_out = ["{{integration_branch}}"]
 scope              = "all-worktrees"
 message = """
-`{{integration_branch}}` is checked out in {worktree}. Nothing should hold it: `rungs land` runs
+`{{integration_branch}}` is checked out in {worktree}. Nothing should hold it: `node .ai/rungs.mjs land` runs
 from wherever you are, verifies on a scratch ref, and advances the branch with a compare-and-swap.
 Holding it checked out blocks every other session and does not prevent concurrent landing anyway —
 switching to the scratch ref releases it mid-run, and two land processes have been measured running
@@ -23,12 +23,12 @@ at once under exactly that design.
 attributes_file = ".gitattributes"
 required_drivers = ["rungs-ledger", "rungs-generated"]
 verify_installed = true
-install_command  = "rungs setup git"
+install_command  = "node .ai/rungs.mjs setup git"
 message = """
 The merge drivers named in .gitattributes are not installed in this clone, so they are inert and
 merges are falling back to git's default. For a generated artifact that default is a clean text
 merge of a file that is a fixed point of nothing — it surfaces later as a mismatch with an
-uninformative diff. Run `rungs setup git` once per clone.
+uninformative diff. Run `node .ai/rungs.mjs setup git` once per clone.
 """
 
 # ── self-tests ────────────────────────────────────────────────────────────────

package/modules/concurrency/module.toml

@@ -1,6 +1,6 @@
 [module]
 name    = "concurrency"
-version = "1.2.0"
+version = "1.4.0"
 rung    = 5
 summary = "Many sessions on one integration branch: a verified base to cut from, attributed failures, a land protocol that cannot redden the branch, and merge drivers per conflict class."
 

package/modules/doc-authority/files/{{registry_path}}

@@ -9,7 +9,7 @@ before any content is written.** If the answer is missing, add the row before wr
 ## The registry
 
 The third column is what makes this enforceable rather than aspirational: it converts "one source
-of truth" from a principle into a lookup, and it is what `rungs check` reads.
+of truth" from a principle into a lookup, and it is what `node .ai/rungs.mjs check` reads.
 
 | Topic | Owner | Must NOT appear in |
 | --- | --- | --- |

package/modules/doc-authority/module.toml

@@ -1,6 +1,6 @@
 [module]
 name    = "doc-authority"
-version = "1.0.0"
+version = "1.1.0"
 rung    = 4
 summary = "One owner per topic, declared in a registry and checked — plus a propagation gate for rules that live in more surfaces than their authority."
 

package/modules/findings/files/docs/{{backlog.root}}/FINDINGS.md

@@ -46,7 +46,7 @@ reason**:
 | **fixed** | It was resolved directly | What changed, and where |
 | **dismissed** | It is not a problem, or not one worth solving | *Why not* — this is the one people skip, and it is the one that stops the same observation being recorded again next month |
 
-`rungs check` refuses a closed finding with no reason.
+`node .ai/rungs.mjs check` refuses a closed finding with no reason.
 
 ## What this register does not do
 

package/modules/findings/gates/findings.toml

@@ -73,6 +73,11 @@ gate    = "findings-disposition-has-reason"
 expect  = "pass"
 fixture = { table = "Open", row = { Id = "{{id_prefix}}-002", Sev = "high", Pri = "now", What = "x", Evidence = "none — hunch" } }
 
+[[self_test]]
+gate    = "findings-disposition-has-reason"
+expect  = "pass"
+fixture = { table = "Open", row = { Id = "—", Sev = "", Pri = "", What = "*nothing open*", Evidence = "" } }
+
 [[self_test]]
 gate    = "findings-self-declared-closure"
 expect  = "fail"

package/modules/findings/module.toml

@@ -1,6 +1,6 @@
 [module]
 name    = "findings"
-version = "1.1.0"
+version = "1.2.0"
 rung    = 1
 summary = "A register for what is noticed before it is decided, with a triage path into work items."
 

package/modules/findings/skills/record-finding/SKILL.md

@@ -54,7 +54,7 @@ Every finding leaves **Open** by exactly one disposition, each with a written re
 
 **Dismissal is the one that matters.** It is the disposition people skip, and its reason is what
 stops the same observation being recorded again next month by someone who cannot tell it was
-already considered. `rungs check` refuses a closed finding with no reason.
+already considered. `node .ai/rungs.mjs check` refuses a closed finding with no reason.
 
 ## Before triaging, re-check
 

package/modules/gates/files/.ai/gates.toml

@@ -1,6 +1,6 @@
 # Gate registry.
 #
-# Every gate this repo runs is declared here, and `rungs check` runs them. Modules add their own
+# Every gate this repo runs is declared here, and `node .ai/rungs.mjs check` runs them. Modules add their own
 # entries on install — those live inside marked blocks and are regenerated; anything outside a
 # block is yours and is never touched.
 

package/modules/gates/fragments/AGENTS.md

@@ -1,8 +1,9 @@
-<!-- rungs:begin gates@1.0.0 -->
+<!-- rungs:begin gates@1.1.0 -->
 ## Gates
 
-`rungs check` runs everything in [`.ai/gates.toml`](.ai/gates.toml) — fast tier constantly, full
-tier at a boundary. **Never weaken a gate to make a change pass**; if a gate is wrong that is its
-own work. Every rule you add declares `gated` or `review-only` — there is no third option. Broke a
-rule that already existed? Do not restate it, make it mechanical: **`/harden-rule`**.
+`node .ai/rungs.mjs check` runs everything in [`.ai/gates.toml`](.ai/gates.toml) — fast tier
+constantly, full tier at a boundary. **Never weaken a gate to make a change pass**; if a gate is
+wrong that is its own work. Every rule you add declares `gated` or `review-only` — there is no third
+option. Broke a rule that already existed? Do not restate it, make it mechanical:
+**`/harden-rule`**.
 <!-- rungs:end gates -->

package/modules/gates/module.toml

@@ -1,6 +1,6 @@
 [module]
 name    = "gates"
-version = "1.0.0"
+version = "1.1.0"
 rung    = 1
 summary = "The gate runner, the registry every other module registers into, the run ledger, and the generic structural gate set."
 

package/modules/instructions/files/.ai/rules/README.md

@@ -1,8 +1,8 @@
 # Path-scoped rules
 
 **These files are the source. The copies under `.claude/rules/`, `.github/instructions/` and
-`.cursor/rules/` are generated — do not edit those.** Run `rungs render` after changing anything
-here; `rungs check` refuses a stale rendering.
+`.cursor/rules/` are generated — do not edit those.** Run `node .ai/rungs.mjs render` after changing
+anything here; `node .ai/rungs.mjs check` refuses a stale rendering.
 
 A rule here loads only when an agent touches a matching file, so it costs nothing until it is
 relevant. That is what keeps [`../../AGENTS.md`](../../AGENTS.md) inside its line budget.

package/modules/instructions/files/.ai/rungs.mjs

@@ -0,0 +1,52 @@
+import { existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+const pinnedPackageSpec = '@rungs/cli@{{rungs.version}}';
+const pinnedVersion = pinnedPackageSpec.slice('@rungs/cli@'.length);
+const requested = process.argv.slice(2);
+
+// The launcher cannot discover an upgrade while running its current pin. An
+// upgrade therefore names the next exact version explicitly; the newer CLI
+// rewrites this managed file to make that version the normal pin. Tags, ranges,
+// URLs and paths are refused.
+const exactVersion = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z]+(?:\.[0-9A-Za-z]+)*)?(?:\+[0-9A-Za-z]+(?:\.[0-9A-Za-z]+)*)?$/;
+let selectedVersion = pinnedVersion;
+if (requested[0] === 'upgrade' && requested[1] === '--to') {
+  if (!exactVersion.test(requested[2] ?? '')) {
+    console.error('rungs launcher: upgrade --to requires an exact version such as 1.2.3 or 1.2.3-beta.1');
+    process.exit(1);
+  }
+  selectedVersion = requested[2];
+  requested.splice(1, 2);
+} else if (requested.includes('--to')) {
+  console.error('rungs launcher: --to is only valid immediately after upgrade');
+  process.exit(1);
+}
+
+const packageSpec = selectedVersion === pinnedVersion ? pinnedPackageSpec : `@rungs/cli@${selectedVersion}`;
+const npmArgs = ['exec', '--yes', `--package=${packageSpec}`, '--', 'rungs', ...requested];
+
+// npm is a JavaScript program. Calling its entry point through this Node process
+// avoids a shell on every platform, so an argument cannot become shell syntax.
+// npm sets npm_execpath when it launched the parent; standard Node installers
+// also place npm beside node. POSIX can safely fall back to its executable.
+const adjacentNpm = join(dirname(process.execPath), 'node_modules', 'npm', 'bin', 'npm-cli.js');
+const inheritedNpm = process.env.npm_execpath;
+const npmCli = inheritedNpm && existsSync(inheritedNpm) ? inheritedNpm : existsSync(adjacentNpm) ? adjacentNpm : undefined;
+
+if (!npmCli && process.platform === 'win32') {
+  console.error('rungs launcher: could not locate npm-cli.js beside Node; install npm or invoke this command from npm');
+  process.exitCode = 1;
+} else {
+  const child = npmCli
+    ? spawnSync(process.execPath, [npmCli, ...npmArgs], { stdio: 'inherit', windowsHide: true })
+    : spawnSync('npm', npmArgs, { stdio: 'inherit' });
+
+  if (child.error) {
+    console.error(`rungs launcher: ${child.error.message}`);
+    process.exitCode = 1;
+  } else {
+    process.exitCode = child.status ?? 1;
+  }
+}

package/modules/instructions/files/AGENTS.md

@@ -5,7 +5,9 @@ Canonical agent policy for this repository. Read in full before making changes.
 This is the **always-on** document: facts every session needs. Anything that applies to one part of
 the tree belongs in [`.ai/rules/`](.ai/rules/README.md) instead, and anything that is a multi-step
 procedure belongs in a skill. Both load only when relevant, and this file has a line budget that
-`rungs check` enforces.
+`node .ai/rungs.mjs check` enforces. Use `node .ai/rungs.mjs <command>` for every Rungs command;
+the committed launcher pins the exact CLI version this repository has reviewed. To upgrade, choose
+the next immutable version explicitly: `node .ai/rungs.mjs upgrade --to <exact-version> --apply`.
 
 ## What this is
 
@@ -19,7 +21,7 @@ everything is slow enough to get skipped; running the wrong subset proves nothin
 | Change surface | Run |
 | --- | --- |
 | *(fill in per surface)* | |
-| anything | `rungs check` |
+| anything | `node .ai/rungs.mjs check` |
 
 ## Task loop
 

package/modules/instructions/files/CLAUDE.md

@@ -5,7 +5,7 @@
   no second copy to drift (ADR-0001). The import is used rather than a symlink because a symlink
   requires Administrator or Developer Mode on Windows.
 
-  Add Claude-specific content below this comment. It is yours; `rungs upgrade` will not touch it.
+  Add Claude-specific content below this comment. It is yours; `node .ai/rungs.mjs upgrade` will not touch it.
 -->
 
 ## Claude Code

package/modules/instructions/fragments/AGENTS.md

@@ -1,8 +1,8 @@
-<!-- rungs:begin instructions@1.1.0 -->
+<!-- rungs:begin instructions@1.2.0 -->
 ## Repo map
 
 <!-- rungs:begin repo-map -->
-<!-- Generated. Run `rungs render` after moving directories. -->
+<!-- Generated. Run `node .ai/rungs.mjs render` after moving directories. -->
 <!-- rungs:end repo-map -->
 ## Execution boundary
 

package/modules/instructions/gates/core.toml

@@ -23,7 +23,7 @@ id      = "rules"
 sources = [".ai/rules/**/*.md"]
 exclude = [".ai/rules/README.md"]   # the scaffold doc is not a rule
 targets = [".claude/rules/**/*.md", ".github/instructions/**/*.instructions.md", ".cursor/rules/**/*.mdc"]
-command = "rungs render"
+command = "node .ai/rungs.mjs render"
 # Targets are checked only for harnesses in the installed matrix; the rest are ignored rather
 # than reported missing.
 
@@ -34,7 +34,7 @@ id      = "repo-map"
 block   = { file = "AGENTS.md", marker = "repo-map" }
 derives = "directory-tree"
 depth   = 2
-command = "rungs render"
+command = "node .ai/rungs.mjs render"
 
 # ── instructions-shell-backticks (hook: pre-tool-use) ─────────────────────────
 #