@rungs/cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Antoine Dancre
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,196 @@
+# rungs
+
+**Installs and maintains a repository's agentic development system.**
+
+Your agent has instructions. Do they have gates? Is your backlog's status field
+telling the truth about what actually merged? That thing you noticed last
+Tuesday — where did it go?
+
+rungs scaffolds the parts of a working setup — agent instructions, skills, work
+tracking, findings, decision records, validation gates — as **modules you pick**,
+then keeps checking that they still say what they said.
+
+```console
+$ rungs init . tracked
+  instructions   3 create
+  gates          1 create · 1 skill · 2 merge
+  backlog        6 create · 1 rule · 2 skill · 1 merge
+  findings       1 create · 1 skill · 1 merge
+  adr            2 create · 1 merge
+  session        2 create · 1 skill · 1 merge
+
+  registered 18 gates from 6 module(s)
+  rendered 2 file(s) · 0 degraded → .ai/render-report.md
+
+$ rungs check
+  pass backlog-ids                        2ms   2 examined
+  FAIL backlog-merged-status              68ms
+         docs/backlog/items/WI-014-parser.md: branch feature/wi-014 is merged
+         but status is 'in_progress'
+  …
+  17 pass · 1 fail · 0 unimplemented · 0 error
+```
+
+---
+
+## Why this exists
+
+Every rule in here was **paid for once already**.
+
+The content is extracted from four repositories built over six months in
+different stacks — a .NET ingestion platform, a 105-package Angular monorepo, a
+set of reference apps, and a full-stack product with 3,236 commits across 401
+branches. Each solved part of this by hand. Each also failed in ways the others
+did too.
+
+So rungs does not ship a good idea about how to work. It ships **what four repos
+learned, with the incident attached**. Every module declares its provenance, and
+`doctor` quotes that incident back when a gate it installed has never fired:
+
+> `check-findings-register` has run 340 times and never fired. It exists because
+> one repo produced 268 audit reports with no register to close them into. Is
+> that still a risk here — or is this gate scoped too narrowly?
+
+The research is in [`docs/research/`](docs/research/README.md) and stands on its
+own: four repo autopsies, the [eight failure modes all of them
+hit](docs/research/synthesis.md), and a maturity ladder that prices each practice
+so you don't install rung 5 at rung 1.
+
+## Install
+
+Not published yet. For now:
+
+```bash
+git clone <this repo> && cd rungs && npm install
+node src/cli.ts --help
+```
+
+Requires **Node 22.18+** — it runs TypeScript directly, no build step.
+
+Published as **`@rungs/cli`** — the unscoped name `rungs` is unpublishable, being
+one edit away from both `rung` and `runjs`, which npm's typosquat filter refuses.
+The tool, the command and everything it writes are still `rungs`; only the
+package identifier differs:
+
+```bash
+npx @rungs/cli doctor
+```
+
+## What you get
+
+`rungs init . tracked` writes:
+
+```text
+AGENTS.md              # what every session reads — with a line budget that is enforced
+CLAUDE.md              # a one-line bridge: @AGENTS.md. Not a second copy
+.ai/
+  rules/               # path-scoped rules you author, rendered per harness
+  gates.toml           # every gate this repo runs
+  rungs.toml           # what is installed, and a hash of everything we wrote
+.claude/skills/        # spec-compliant Agent Skills — portable to 45+ clients
+docs/backlog/          # work items, a board, a findings register
+docs/decisions/        # ADRs, with an admission rule that keeps the directory small
+```
+
+**Nothing is overwritten, ever.** `add` on a repo that already has a backlog
+keeps yours and installs only what is missing. Files you edit afterwards are
+reported as diverged and left alone.
+
+## Commands
+
+| | |
+| --- | --- |
+| `rungs init [path] [profile]` | Scaffold — `minimal` · `tracked` · `disciplined` · `hardened` · `fleet` |
+| `rungs doctor [path]` | What does this repo already have? Works on repos that never installed anything |
+| `rungs add <module…>` | Install one module, resolving dependencies and adopting what exists |
+| `rungs check [path]` | Run the gates, record the ledger |
+| `rungs render [path]` | Re-emit path-scoped rules for each harness |
+| `rungs upgrade [path]` | Move to newer module versions, never touching what you edited |
+| `rungs eject [path]` | Materialise the engines; stop depending on rungs |
+| `rungs setup git [path]` | Install the merge drivers `.gitattributes` names |
+| `rungs modules` | List the set and audit the manifests |
+
+Add `--dry-run` to any write command.
+
+## Modules
+
+Fifteen, each carrying a **rung** — how mature a practice is — so `add` can tell
+you when you are installing above your level.
+
+| Rung | Modules |
+| --- | --- |
+| **0** any repo with an agent | `instructions` |
+| **1** more than one thing in flight | `gates` `backlog` `findings` `adr` `session` `ci` |
+| **2** repeated work of the same shape | `specs` `workflows` `skills` `audit` |
+| **3** shipping versions, external design | `release` `design-sync` |
+| **4** docs that restate each other | `doc-authority` |
+| **5** 5+ concurrent sessions | `concurrency` |
+
+`concurrency` refuses to install without `--confirm-threshold`, because below
+five simultaneous sessions every mechanism in it costs more than it returns.
+Selling rung 5 to a rung-1 repo is the most likely way this tool does harm.
+
+Full specification: [`docs/design/module-catalog.md`](docs/design/module-catalog.md).
+
+## Which agents
+
+Skills are **spec-compliant Agent Skills**, portable to Claude Code, Codex,
+Cursor, Copilot, Gemini CLI and 40+ others without translation.
+
+Only *path-scoped rules* are genuinely fragmented across harnesses, so that is
+the only thing rungs renders — into `.claude/rules/`, `.github/instructions/`
+and `.cursor/rules/`. Anything a target cannot express is **reported, never
+silently dropped**, in `.ai/render-report.md`.
+
+Reasoning: [ADR-0001](docs/decisions/ADR-0001-multi-harness-rendering.md).
+
+## Design commitments
+
+Four promises that shape everything else:
+
+- **Your repo gains no new language runtime.** rungs writes no gate scripts.
+  Generic gates are declarations run by engines the CLI provides; anything else
+  is a shell command you already own. A .NET repo with no `package.json` stays
+  that way. ([ADR-0002](docs/decisions/ADR-0002-stack-and-runtime-footprint.md))
+- **A gate with no engine blocks — it never reports green.** A registry passing
+  because most of its gates do nothing is the worst failure this tool could have.
+- **`eject` is a promise, not a courtesy.** It materialises the engines into your
+  repo and rewrites the registry to plain commands. A tool whose checks vanish
+  when you uninstall it is one nobody should adopt.
+- **Nothing is measured that needs judgement.** The gate ledger records exit
+  status and wall-clock. It never scores your workflow.
+  ([ADR-0005](docs/decisions/ADR-0005-self-instrumentation.md))
+
+## Status
+
+**Pre-release, v0.1.0.** Everything above runs; nothing is published.
+
+rungs is installed in its own repo and its gates run on every change — 20 pass,
+0 fail. Detection is [verified against all four source
+repos](docs/design/detection-verification.md). Not yet done: publishing, and
+installing into a source repo for real rather than in dry run.
+
+Expect module *contents* to move. The command surface is settled.
+
+## Contributing
+
+Modules are the product, and **a module is a directory that looks like what it
+emits** — markdown and TOML, no code. If you can read the repo it produces, you
+can write one: [`modules/README.md`](modules/README.md).
+
+Every module must declare `[provenance]` with a real incident behind it. A module
+nobody paid for does not ship.
+
+## Repository
+
+| | |
+| --- | --- |
+| [`docs/research/`](docs/research/README.md) | The four repo autopsies, the synthesis, the pattern catalogue |
+| [`docs/design/`](docs/design/README.md) | Product brief, module catalogue, verification |
+| [`docs/decisions/`](docs/decisions/README.md) | ADRs |
+| [`modules/`](modules/README.md) | The fifteen modules |
+| [`src/`](src/) | The CLI, ~2,800 lines |
+
+## Licence
+
+MIT.

package/modules/README.md

@@ -0,0 +1,116 @@
+# Modules
+
+The product. Each directory here is one installable module, in the format set by
+[ADR-0003](../docs/decisions/ADR-0003-module-definition-format.md); the set and its rungs are
+specified in [module-catalog.md](../docs/design/module-catalog.md).
+
+| Module | Rung | Status |
+| --- | --- | --- |
+| [`instructions`](instructions/) | 0 | **authored** — owns `AGENTS.md`, the bridge, `.ai/rules/` |
+| [`gates`](gates/) | 1 | **authored** — owns the runner, registry and ledger |
+| [`backlog`](backlog/) | 1 | **authored** — the format exemplar |
+| [`findings`](findings/) | 1 | **authored** — completes `audit → findings → backlog` |
+| [`adr`](adr/) | 1 | **authored** |
+| [`session`](session/) | 1 | **authored** |
+| [`ci`](ci/) | 1 | **authored** |
+| [`specs`](specs/) | 2 | **authored** |
+| [`workflows`](workflows/) | 2 | **authored** |
+| [`skills`](skills/) | 2 | **authored** |
+| [`audit`](audit/) | 2 | **authored** |
+| [`release`](release/) | 3 | **authored** |
+| [`design-sync`](design-sync/) | 3 | **authored** |
+| [`doc-authority`](doc-authority/) | 4 | **authored** |
+| [`concurrency`](concurrency/) | 5 | **authored** |
+
+**All fifteen are authored.** Installing every one assembles an entry document of **165 of the
+200-line budget**, leaving 35 for the repo's own conventions — and no repo should install all
+fifteen, since rung 3+ modules are for specific problems.
+
+`concurrency` carries a **threshold** in its manifest (`minimum = 5` concurrent sessions,
+`confirm = true`): `add` states it and requires explicit confirmation. Selling rung 5 to a rung-1
+repo is the most likely way this tool does harm.
+
+## Anatomy
+
+**A module is a directory that looks like what it emits.** Disposition is decided by which
+subdirectory a file is in — there is no per-file configuration:
+
+| Directory | Disposition |
+| --- | --- |
+| `files/` | **create** — written into the repo, with `{{param}}` substituted in contents *and paths* |
+| `rules/` | **render** — path-scoped rule sources, emitted per harness ([ADR-0001](../docs/decisions/ADR-0001-multi-harness-rendering.md)) |
+| `skills/` | **copy** — spec-pure `SKILL.md`, byte-for-byte after substitution |
+| `fragments/` | **merge** — managed blocks inside a file another module owns |
+| `gates/` | **declare** — engine tables; **no script is written into the repo** |
+| `module.toml` | the manifest: identity · rung · deps · params · gates · detection · provenance |
+
+**Hooks are not a sixth disposition.** A hook is a gate with a lifecycle trigger instead of a
+runner trigger — `trigger = "pre-tool-use"` plus a `matcher` in the `[[gates]]` entry. It is
+emitted into harnesses that support it and reported as degraded for those that do not, exactly like
+any other render target. A useful consequence: the ledger covers hooks too, so a repo can find out
+whether its guard has ever actually fired.
+
+## Authoring rules
+
+1. **Substitution only, no logic.** A module that needs a conditional is two modules, or a variant.
+1b. **`${{ … }}` is never substituted.** A `$` immediately before `{{` marks a passthrough, because
+   GitHub Actions expressions (`${{ github.ref }}`) share the delimiter. Without this rule the CI
+   module's own workflow file is silently corrupted at install — the kind of collision that
+   produces a broken file rather than an error.
+1c. **A behavioural parameter reaches file content through a managed block**, never a conditional.
+   `ci.trigger` regenerates the `ci-triggers` block inside the workflow rather than branching the
+   template. This is the general escape when substitution alone is not enough.
+2. **Not everything is a parameter.** If a value cannot substitute cleanly into prose, a table
+   *and* a gate, it is the module's opinion — ship it and let a repo diverge. `backlog`'s
+   eight-status lifecycle is the worked example.
+2b. **Two kinds of parameter, and only one is substituted.** A *substitution* parameter appears as
+   `{{name}}` in templates. A *behavioural* one changes what the CLI does and is marked
+   `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)).
+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
+   satisfied is indistinguishable from a gate that matches nothing.
+6. **`[detect]` must correctly classify all four source repos.** That is the Phase 6 acceptance
+   criterion, and it is why detection is biased toward false negatives.
+7. **A managed-block marker uses the target file's comment syntax** — `<!-- rungs:begin x -->` in
+   markdown, `# rungs:begin x` in TOML and `.gitignore`. Found by writing an HTML comment into a
+   TOML registry, where it is a syntax error rather than a marker.
+8. **A fragment is a routing stanza, not a summary — 4 to 8 lines.** The budget is shared, and it
+   is the binding constraint at profile scale, not per module. Measured while authoring the
+   `disciplined` profile: a 73-line skeleton plus ten fragments at ~12 lines each is 193 of the
+   200-line budget with nothing left for the repo's own conventions or repo map. Rewritten as
+   routing stanzas the same profile assembles to **134**, leaving 66 for the repo. A fragment says
+   *what exists, where it lives, and which skill runs it*; the reasoning goes in the module's
+   authority document, and the surface-specific rules go in `.ai/rules/`.
+8b. **Not every module needs a fragment.** `ci` has none — nothing about it changes what an agent
+   should do, and the `gates` fragment already names `rungs check`. A fragment that restates a
+   neighbour's is spending shared budget on a duplicate.
+9b. **A parameter may reference a declared dependency's parameters** as `{{<module>.<param>}}` —
+   `findings` places its register at `docs/{{backlog.root}}/FINDINGS.md` so it lands next to the
+   backlog it feeds. Only declared dependencies; anything else is an undeclared coupling.
+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.
+9d. **A parameter whose value means "do nothing" is the absence of the module.** `session` was
+   specified with `mode = file | board`, where `board` created no files at all. That is not a
+   mode; it is not installing `session`. Dropped.
+9e. **Audit parameters across modules, not within one.** `adr` declared `id_width` that nothing
+   consumed — a knob wired to nothing, invisible until every module was compared at once.
+9f. **A parameter never holds a value decided at runtime.** `release` first declared
+   `candidate_branch = "candidate/{{version}}"`, referencing a version that does not exist at
+   install time. It is a **prefix**; the version is chosen when a release is cut. A parameter
+   holding a runtime value is stale before it is ever used.
+9g. **A module may declare a `[threshold]`** with `confirm = true`, which makes `add` state the
+   cost and require explicit acknowledgement. Only `concurrency` uses it, and it exists because
+   the maturity ladder is advice until something enforces it.
+
+10. **Genuinely optional prose ships commented out, with the reason** — substitution-only templating
+   has no other way to offer a choice, and a commented block is a decision the installer makes once
+   in their editor. Claude Code strips HTML comments before injection, so an unaccepted block costs
+   the agent nothing while staying visible to the human. `instructions`' communication-style block
+   is the worked example.

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

@@ -0,0 +1,52 @@
+**Authoritative for:** the admission rule, the record format, and the index of decisions.
+**Not authoritative for:** the content of any decision — each record is authoritative for its own.
+
+# Decisions
+
+Architecture decision records. **Immutable**: a record is never edited to reflect a new decision —
+it is superseded by a new record that names it.
+
+## Index
+
+<!-- rungs:begin adr-index -->
+<!-- Generated by `rungs render`. -->
+
+| ADR | Title | Status | Date |
+| --- | --- | --- | --- |
+| — | *none yet* | | |
+
+<!-- rungs:end adr-index -->
+
+## Admission rule
+
+**Before creating a record, all five must be true.** If any is false, the content belongs in the
+document that already owns the topic — a spec, a module doc, a rule — not here.
+
+1. The decision **constrains future work** rather than describing current work.
+2. A reasonable **alternative existed and was rejected**, for a reason that can be stated.
+3. **Reversing it later would cost meaningfully more** than making it now.
+4. It is **not already owned** by another document.
+5. It is **not an implementation detail** that the code states more precisely than prose can.
+
+This rule is the whole reason a decision directory stays navigable. Without it, every choice
+becomes a record, the index becomes a second documentation tree, and its entries start
+contradicting the docs that actually own those topics.
+
+## Writing one
+
+Copy [`TEMPLATE.md`](TEMPLATE.md). Required sections, and each is required for a reason:
+
+| Section | Why it is required |
+| --- | --- |
+| **Context** | The forces. A record whose context is one sentence usually failed criterion 1 |
+| **Decision** | Stated in the present tense, as a rule |
+| **Consequences** | **Both** — what this makes easy *and* what it costs. A consequences section with no costs is advocacy |
+| **Alternatives considered** | Each with the reason it lost. This is the section future readers actually come for, and its absence is what criterion 2 is guarding |
+| **Revisit triggers** | Facts about the world that would reopen this — not a date. A record with no trigger is one nobody will ever know to revisit |
+
+## Statuses
+
+`proposed` → `accepted` → `superseded by {{id_prefix}}-####` · or `rejected`.
+
+**Never delete a record**, including a rejected one. The reason something was not done is the
+answer to a question that will be asked again.

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

@@ -0,0 +1,55 @@
+---
+id: {{id_prefix}}-0000
+title: Short imperative statement of the decision
+status: proposed        # proposed | accepted | rejected | superseded
+date: YYYY-MM-DD
+supersedes:             # {{id_prefix}}-#### — when this replaces an earlier record
+superseded_by:          # set when a later record replaces this one
+---
+
+# {{id_prefix}}-0000 — Title
+
+## Context
+
+The forces at work: what is true, what is constrained, what problem is being solved. Enough that
+someone who was not here can tell why a decision was needed at all.
+
+> If this is one sentence, check admission criterion 1 — you may be describing work rather than
+> constraining it.
+
+## Decision
+
+Stated in the present tense, as a rule: *"X is Y"*, not *"we will make X be Y"*.
+
+## Consequences
+
+**Good**
+
+- What this makes possible or cheap.
+
+**Costs and risks**
+
+- What it makes harder, and what could go wrong.
+
+> **Both halves are required.** A consequences section with no costs is advocacy, and the next
+> reader will assume the costs were never considered.
+
+## Alternatives considered
+
+**\<Alternative\>** — what it was, and **the reason it lost**.
+
+> This is the section future readers actually come for. "We considered other options" without
+> naming them is the same as not having considered them.
+
+## Revisit triggers
+
+Facts about the world that would reopen this — not a date. A record with no trigger is one nobody
+will know to revisit.
+
+1. …
+
+## Admission check
+
+Against [the rule](README.md): (1) constrains future work ✅ · (2) a real alternative was rejected
+with a stated reason ✅ · (3) reversing later costs meaningfully more ✅ · (4) not owned by another
+document ✅ · (5) not an implementation detail ✅.

package/modules/adr/fragments/AGENTS.md

@@ -0,0 +1,8 @@
+<!-- rungs:begin adr@1.0.0 -->
+## Decisions
+
+Significant decisions are `{{id_prefix}}-####` records in [`{{path}}/`]({{path}}/README.md).
+**Check the admission rule before writing one** — five criteria, all must hold, or the content
+belongs in the document that already owns the topic. Records are immutable: supersede, never edit,
+never delete.
+<!-- rungs:end adr -->

package/modules/adr/gates/adr.toml

@@ -0,0 +1,65 @@
+# Gate table for the `adr` module.
+
+# ── adr-index-current ─────────────────────────────────────────────────────────
+
+[[render_freshness]]
+id      = "adr-index"
+block   = { file = "{{path}}/README.md", marker = "adr-index" }
+derives = "file-index"
+sources = ["{{path}}/{{id_prefix}}-*.md"]
+columns = ["id", "title", "status", "date"]
+command = "rungs render"
+
+# ── adr-required-fields ───────────────────────────────────────────────────────
+
+[[frontmatter_schema]]
+id       = "adr"
+scan     = ["{{path}}/{{id_prefix}}-*.md"]
+required = ["id", "title", "status", "date"]
+optional = ["supersedes", "superseded_by"]
+enum     = { status = ["proposed", "accepted", "rejected", "superseded"] }
+
+# A superseded record must name its successor, and the successor must name it back. A one-way
+# supersession leaves a reader on the stale record with no way to find the live one.
+[frontmatter_schema.reciprocal]
+pairs = [{ from = "superseded_by", to = "supersedes" }]
+
+# Sections, not prose quality. The gate can check that `Alternatives considered` exists and is not
+# empty; it cannot judge whether the alternatives were real, and one that tried would be the
+# confidently-wrong probe.
+[sections]
+scan     = ["{{path}}/{{id_prefix}}-*.md"]
+required = ["Context", "Decision", "Consequences", "Alternatives considered", "Revisit triggers"]
+non_empty = true
+min_words = { "Alternatives considered" = 15 }
+message  = """
+{file} has no non-empty `{section}`. A record without alternatives is a description of what was
+done rather than a decision — which is what admission criterion 2 is guarding against.
+"""
+
+# ── self-tests ────────────────────────────────────────────────────────────────
+
+[[self_test]]
+gate    = "adr-required-fields"
+expect  = "fail"
+fixture = { file = "{{path}}/{{id_prefix}}-0001-x.md", sections = ["Context", "Decision", "Consequences"] }
+
+[[self_test]]
+gate    = "adr-required-fields"
+expect  = "pass"
+fixture = { file = "{{path}}/{{id_prefix}}-0001-x.md", sections = ["Context", "Decision", "Consequences", "Alternatives considered", "Revisit triggers"] }
+
+[[self_test]]
+gate    = "adr-required-fields"
+expect  = "fail"
+fixture = { frontmatter = { id = "{{id_prefix}}-0001", title = "x", status = "superseded", date = "2026-01-01" } }
+
+[[self_test]]
+gate    = "adr-index-current"
+expect  = "fail"
+fixture = { block_rows = 0, source_files = 3 }
+
+[[self_test]]
+gate    = "adr-index-current"
+expect  = "pass"
+fixture = { block_rows = 3, source_files = 3 }

package/modules/adr/module.toml

@@ -0,0 +1,67 @@
+[module]
+name    = "adr"
+version = "1.0.0"
+rung    = 1
+summary = "Numbered, immutable decision records, with an admission rule that keeps the directory from becoming a second documentation tree."
+
+[requires]
+modules = []
+
+[conflicts]
+modules = []
+
+[params.path]
+description = "Directory holding the records"
+default     = "docs/decisions"
+
+[params.id_prefix]
+description = "Record id prefix"
+default     = "ADR"
+
+# An `id_width` parameter was declared here and removed by the cross-module audit: nothing consumed
+# it. The template hardcodes the width in its example id and the index gate globs `{{id_prefix}}-*`,
+# so it was a knob wired to nothing. It comes back when an id-claiming command needs it, marked
+# `consumed_by`, and not before.
+
+[[gates]]
+id     = "adr-index-current"
+kind   = "declared"
+engine = "render-freshness"
+table  = "gates/adr.toml"
+tier   = "fast"
+why    = "An index that has stopped listing every record is a routing table that silently drops decisions."
+
+[[gates]]
+id     = "adr-required-fields"
+kind   = "declared"
+engine = "frontmatter-schema"
+table  = "gates/adr.toml"
+tier   = "fast"
+why    = """
+A record with no alternatives section is a description of what was done, not a decision. The
+admission rule exists to keep those out, and this gate is what makes the rule more than advice.
+"""
+
+[detect]
+# `docs/**/decisions/**` rather than `docs/decisions/**`: hexguard keeps four
+# numbered workflow decisions in `docs/.ai/decisions/` and the narrower glob
+# missed them entirely. Found by running this against the corpus, not by reading.
+paths   = ["docs/**/adr/**/*.md", "docs/**/decisions/**/*.md", "docs/**/ADR-*.md", "doc/adr/**/*.md"]
+markers = ["rungs:begin adr"]
+
+[[detect.infer]]
+param   = "id_prefix"
+pattern = "\\b(ADR|DEC|RFC)-\\d{3,4}\\b"
+min     = 3
+scope   = ["docs/**/*.md"]
+
+[provenance]
+sources  = ["axiom-mesh", "rift-forge", "hexguard"]
+patterns = ["adr-record", "adr-admission-rule"]
+incident = """
+axiom-mesh reached 48 ADRs and they stayed navigable, because a five-criterion admission rule was
+applied before creation and routed most candidate decisions into the authoritative doc that already
+owned the topic. Without that gate an ADR directory becomes a second, unindexed documentation tree
+whose entries contradict the first. hexguard has the opposite shape: four numbered workflow
+decisions, no admission rule, and no way to tell what else should have been one.
+"""

package/modules/audit/files/{{criteria_path}}

@@ -0,0 +1,43 @@
+**Authoritative for:** what an assessment checks, and the severity of each failing criterion.
+**Not authoritative for:** whether any subject passes, which is a finding, and whether to act on it, which is a decision.
+
+# Audit criteria
+
+What `/assess` checks, one {{subject}} at a time. **Edit this file** — the criteria are the part
+that changes most, and a list buried in a skill body is a list nobody maintains.
+
+Each criterion needs a **verdict that is checkable** rather than a matter of taste. If two people
+could assess the same subject and disagree, the criterion is not written tightly enough yet.
+
+## Criteria
+
+| # | Criterion | Passes when | Severity if failing |
+| --- | --- | --- | --- |
+| 1 | Public surface is documented | Every exported entry point has a description and an example | medium |
+| 2 | Tests cover the contract | The documented behaviour has a test, not just the implementation | high |
+| 3 | Errors are modelled | Expected failures are typed and surfaced, not swallowed | high |
+| 4 | Consumable from outside | A consumer can use it without reading its internals | medium |
+| 5 | No undeclared coupling | Dependencies are declared, not reached through | high |
+| 6 | Change is safe | A breaking change is detectable by something other than a human reading the diff | medium |
+
+<!-- Add, remove and reword freely. Six is a starting point, not a standard. -->
+
+## How a criterion becomes a finding
+
+A failing criterion becomes **one row** in the findings register:
+
+- **Sev** — from the table above
+- **What** — the criterion and the specific way this subject fails it
+- **Evidence** — the path, symbol or command that shows it. **A criterion marked failing with no
+  evidence is an opinion**, and next month nobody can tell whether it was checked
+
+Passing criteria produce **nothing**. An audit that records its passes is an audit that produces a
+document, and a document per subject is the shape this module exists to prevent.
+
+## What an audit does not do
+
+- It does not prioritise. Severity is about the problem; whether to act is a separate decision made
+  against the register.
+- It does not fix anything, and it does not open work items. A finding is the observation; a work
+  item is the decision.
+- **It does not prove a subject is good.** A subject passing six criteria has passed six criteria.

package/modules/audit/fragments/AGENTS.md

@@ -0,0 +1,8 @@
+<!-- rungs:begin audit@1.0.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`
+refuses it re-forming.
+<!-- rungs:end audit -->