@rungs/cli 0.1.0

package/modules/audit/gates/audit.toml

@@ -0,0 +1,48 @@
+# Gate table for the `audit` module.
+
+# ── audit-output-is-rows ──────────────────────────────────────────────────────
+#
+# Refuses a per-subject audit document tree from re-forming. Deliberately does not fire on a small
+# number: one or two written-up assessments are a legitimate thing to have. It fires on the shape
+# that scales — a document per subject, accumulating.
+
+[file_population]
+scan          = ["docs/**/audits/**/*.md", "docs/**/*-audit-*.md", "docs/**/*-readiness-*.md"]
+exclude       = ["docs/**/archive/**"]
+warn_at       = 6
+fail_at       = 15
+exempt_marker = "audit-doc-ok:"        # ignored unless it states a reason
+message       = """
+{count} per-subject audit documents. This is the shape that reached 268 files in one repo, where
+there is still no way to say which findings are open — the prompt was good enough to run 268
+times, the output form was the defect. Audit output belongs in the findings register as rows.
+Existing documents are history and can stay; mark them with `<!-- audit-doc-ok: <reason> -->` or
+move them to an archive.
+"""
+
+# ── self-tests ────────────────────────────────────────────────────────────────
+
+[[self_test]]
+gate    = "audit-output-is-rows"
+expect  = "pass"
+fixture = { matching_files = 3 }
+
+[[self_test]]
+gate    = "audit-output-is-rows"
+expect  = "fail"
+fixture = { matching_files = 40 }
+
+[[self_test]]
+gate    = "audit-output-is-rows"
+expect  = "pass"
+fixture = { matching_files = 40, location = "docs/archive/audits/" }
+
+[[self_test]]
+gate    = "audit-output-is-rows"
+expect  = "pass"
+fixture = { matching_files = 40, exempt = "audit-doc-ok: regulatory evidence, retained per policy" }
+
+[[self_test]]
+gate    = "audit-output-is-rows"
+expect  = "fail"
+fixture = { matching_files = 40, exempt = "audit-doc-ok:" }

package/modules/audit/module.toml

@@ -0,0 +1,72 @@
+[module]
+name    = "audit"
+version = "1.0.0"
+rung    = 2
+summary = "A repeatable assessment whose output is rows in the findings register, never a document per subject."
+
+[requires]
+modules = ["findings"]
+
+[conflicts]
+modules = []
+
+# The dependency is the whole point, and it is declared because a repo violated
+# it: an audit with nowhere to land produces unactioned prose.
+
+[params.subject]
+description = "What gets audited, one at a time — package, service, surface, endpoint…"
+default     = "package"
+
+[params.criteria_path]
+description = """
+The criteria list, as a file the repo edits rather than a parameter. A list substituted into a
+skill body is a list nobody maintains, and criteria are the part that changes most.
+"""
+default     = "docs/audit-criteria.md"
+
+[[gates]]
+id     = "audit-output-is-rows"
+kind   = "declared"
+engine = "file-population"
+table  = "gates/audit.toml"
+tier   = "fast"
+why    = """
+hexguard produced 268 per-subject audit documents and there is still no way to say which findings
+are open. The audit prompt was good enough to run 268 times; the output form was the defect. This
+gate refuses the document tree from re-forming.
+"""
+
+[skills.assess]
+# No extensions. Read-only, and useful for a model to reach for when it notices
+# a subject has never been assessed.
+
+[detect]
+# A dedicated audits directory only. The first draft also matched
+# `docs/**/*-audit-*.md` and `*-readiness-*` anywhere, and on a real repo it hit
+# `WI-108-lol-mechanics-fidelity-audit-epic.md` and a launch-readiness epic —
+# work items, not audit documents. Under-detection is the correct bias: a repo
+# with scattered audit files gets a second directory it can see, while a false
+# positive would have the CLI believe it owns somebody's backlog.
+paths   = ["docs/**/audits/**/*.md", "docs/**/audit/**/*.md"]
+markers = ["rungs:begin audit"]
+
+[[detect.adopt_as]]
+kind = "audit-documents"
+note = """
+An existing per-subject audit tree is the failure this module exists to prevent, already present.
+Adopt means: leave the documents alone as history, register the criteria, and report how many
+subjects have documents with no corresponding open finding — which is the number that says how much
+of that work is currently actionable. Never bulk-convert; that would fabricate findings nobody
+verified.
+"""
+
+[provenance]
+sources  = ["hexguard", "axiom-mesh"]
+patterns = ["audit-to-register", "lifecycle-verbs"]
+incident = """
+hexguard ran /assess-package-readiness across its catalogue twice, producing 268 dated documents
+plus a global audit, a triage doc and a methodology doc — and no aggregate state. To know the
+current condition of the catalogue you read 268 files. There was also no work-item object for a
+finding to become, so the assessments could not close. axiom-mesh got this right by logging every
+confirmed defect as a stable AD-### row before any remediation was deferred.
+"""

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

@@ -0,0 +1,62 @@
+---
+name: assess
+description: >-
+  Assess one subject — a package, service, surface or endpoint — against this repo's audit criteria,
+  and record each failure as a row in the findings register. Use when asked to "audit", "assess",
+  "review the readiness of", "check whether X is production-ready", or before promoting, releasing
+  or publicising something. Also use to work through a backlog of unassessed subjects, one at a
+  time. It records observations; it does not fix them and does not open work items — that is
+  /record-finding's triage and /work-item.
+---
+
+# Assess a subject
+
+Read the criteria file first. It is repo-owned and changes; the version in your memory does not
+count.
+
+## 1. One subject at a time
+
+Assessing several at once produces a comparison, which is a different and less useful artifact.
+Name the subject explicitly before starting, and its boundary — what is in it and what is merely
+adjacent.
+
+## 2. Check each criterion against the artifact
+
+**Read the thing, not the documentation about the thing.** A README claiming the errors are typed
+is a claim; the code is the fact. This is the failure that makes an audit worthless: an assessment
+built from the subject's own self-description confirms it.
+
+For each criterion, reach one of three verdicts:
+
+- **passes** — record nothing
+- **fails** — one row in the findings register
+- **cannot tell** — say so, and say what would settle it. A "cannot tell" recorded honestly is
+  more useful than a pass you did not earn
+
+## 3. Write rows, not a document
+
+Each failure is one row: severity from the criteria table, what specifically fails, **evidence**
+(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`
+refuses the document tree from re-forming.
+
+## 4. Report the run itself
+
+Say how many criteria were checked, how many subjects, and **how many files you actually read**.
+
+An audit that found nothing and an audit that read nothing produce the same output, and only one of
+them is good news. A report that cannot fail loudly is not a measurement.
+
+## 5. Stop
+
+Do not fix what you found. Do not open work items. Do not rank. Those are decisions made against
+the register later, deliberately, by someone weighing them against everything else — which is the
+whole reason the register exists.
+
+## What this cannot tell you
+
+- **That a subject is good.** It passed the criteria that were written down.
+- **That the criteria are right.** They are this repo's opinion, in a file you can edit — and a
+  criterion nothing has ever failed is worth suspecting.

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

@@ -0,0 +1,52 @@
+**Authoritative for:** which items exist and what state each is in, and the next free id.
+**Not authoritative for:** why any item exists or how to do it — that is the item file.
+
+# Backlog
+
+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. -->
+
+## In progress
+
+| Id | Title | Type | Branch |
+| --- | --- | --- | --- |
+| — | *nothing in flight* | | |
+
+## Review
+
+| Id | Title | Type | Branch |
+| --- | --- | --- | --- |
+| — | | | |
+
+## Planned
+
+| Id | Title | Type |
+| --- | --- | --- |
+| — | | |
+
+## Accepted
+
+| Id | Title | Type |
+| --- | --- | --- |
+| — | | |
+
+## Proposed
+
+| Id | Title | Type |
+| --- | --- | --- |
+| — | | |
+
+## Deferred
+
+| Id | Title | Revisit when |
+| --- | --- | --- |
+| — | | |
+
+---
+
+Rejected and completed items keep their files — see [`archive/`](archive/). A rejection is part of
+the record, with its reason; deleting one loses the answer to "why not?" and invites the same
+proposal again.

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

@@ -0,0 +1,110 @@
+**Authoritative for:** how work is proposed, decided, planned, executed and reviewed, and the meaning of each status.
+**Not authoritative for:** what any individual item contains, and what the code should look like — see the engineering guides.
+
+# Delivery methodology & backlog
+
+How work is proposed, decided, planned, executed, and reviewed here — and where it is tracked.
+**Mandatory for all contributors, including AI agents.**
+
+This tracks **units of work and their state**. It does not describe behaviour (that is a spec) or
+record decisions (that is an ADR).
+
+---
+
+## 1. Lifecycle
+
+Every unit of work is a **work item** with a stable id (`{{id_prefix}}-###`) and a status:
+
+```mermaid
+stateDiagram-v2
+  [*] --> proposed
+  proposed --> accepted: decision
+  proposed --> rejected: decision
+  accepted --> planned: requirements + impacts
+  accepted --> deferred: not now
+  deferred --> planned: revisited
+  planned --> in_progress: branch + build
+  in_progress --> review: executed + tested
+  review --> planned: changes requested
+  review --> done: approved + merged
+  done --> [*]
+  rejected --> [*]
+```
+
+| Status | Meaning |
+| --- | --- |
+| `proposed` | An idea captured with **rationale**; awaiting a decision |
+| `accepted` | Approved to pursue; not yet planned in detail |
+| `rejected` | Declined; kept for the record **with the reason** |
+| `deferred` | Accepted in principle but intentionally **not now**, with a revisit trigger |
+| `planned` | Requirements, impacts, approach and acceptance criteria written; ready to build |
+| `in_progress` | Being executed on its branch — **the "current" work** |
+| `review` | Executed and tested; under review against the acceptance criteria |
+| `done` | Approved, merged to `{{integration_branch}}`, acceptance criteria met |
+
+## 2. Workflow
+
+1. **Propose** — open an item (`proposed`) stating the problem and **why it matters**. Anyone may
+   propose.
+2. **Decide** — accept, reject, or defer. Record the decision **and its reason** in the item. A
+   rejection is final unless re-proposed with new information.
+3. **Plan** — for an `accepted` item write **requirements**, **impacts**, **approach** (with
+   options and trade-offs where relevant), **acceptance criteria**, and **out of scope**.
+   Significant design choices get an ADR. Status → `planned`.
+4. **Execute + test** — branch, build, test. Status → `in_progress`, then `review`.
+5. **Review** — verify against the acceptance criteria, reconcile any specs or ADRs, merge.
+   Status → `done`. Changes requested → back to `planned` / `in_progress`.
+
+**Planning artifacts ride `{{integration_branch}}`.** Proposals, decisions and plans precede
+execution and do not need a branch; only *code* does.
+
+## 3. Ids
+
+Ids are permanent and never reused, including after archiving. `BACKLOG.md` carries the
+`NEXT-ID` marker; claim from it and bump it **on your own branch**.
+
+An id spent in a branch name or a commit subject without bumping the marker is invisible to the
+check, which reads the working tree. Bump first.
+
+## 4. Branches
+
+`{{branch_prefix}}/{{id_prefix}}-###-slug`, cut from `{{integration_branch}}` and merged back on
+review. Use `chore/`, `docs/` and `spike/` for non-feature work. **Delete the branch on merge.**
+
+## 5. Definition of done
+
+- Acceptance criteria met and demonstrated
+- Tests written and passing; existing tests not weakened
+- Docs updated where public behaviour or developer workflow changed
+- Status is `done` **and the branch is merged** — the two must agree
+
+## 6. Scope discipline
+
+**Never scope-creep an item.** Work discovered mid-flight becomes a *new* item, or a finding if it
+is only an observation. An item that grew a second purpose should have been two.
+
+## 7. Epics and sub-items
+
+An epic (`type: epic`) has no branch of its own. Membership is a **two-way link**: the epic lists
+`children`, each child names its `epic`. Both directions or neither.
+
+## 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
+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`:
+
+| Gate | Refuses |
+| --- | --- |
+| `backlog-ids` | A duplicate id, or a citation to an id that does not exist |
+| `backlog-stale-blocker` | A document claiming it is blocked on work that has finished — it reads as a live constraint and the next session plans around a wall that came down months ago |
+| `backlog-merged-status` | An item whose branch is merged but whose status is still pre-review. One-directional: a merged branch with a pre-review status is always wrong; an unmerged one is not. A genuinely phased item says why with `branch-merged-ok: <reason>` |
+
+The `status` field is typed by a person and "did it land" is a fact in git. When they disagree the
+typed field is what every board and plan reads, so the gate exists to keep it honest.

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

@@ -0,0 +1,56 @@
+---
+id: {{id_prefix}}-000
+title: Short imperative title
+type: feature          # feature | chore | docs | spike | epic
+status: proposed       # proposed | accepted | rejected | deferred | planned | in_progress | review | done
+branch:                # {{branch_prefix}}/{{id_prefix}}-000-slug — set when execution starts; epics have none
+created: YYYY-MM-DD
+updated: YYYY-MM-DD
+related: []            # {{id_prefix}}-###, ADR-####, spec ids
+epic:                  # parent {{id_prefix}}-### — sub-items only
+children: []           # child {{id_prefix}}-### — epics only
+---
+
+## Proposal (rationale)
+
+The problem, and why it matters. Expected value, or the cost of not doing it.
+
+## Decision
+
+`accepted` | `rejected` | `deferred` — date, who, and the reason. Empty until decided.
+
+## Plan
+
+> Filled once `accepted`. Significant design choices get an ADR — link it.
+
+### Requirements
+
+- Explicit and testable.
+
+### Impacts
+
+- Specs and ADRs touched, code areas, data and contracts, migration or ops, risks.
+
+### Approach
+
+- The chosen approach; options considered and their trade-offs; decisions still open.
+
+### Acceptance criteria / tests
+
+- How we will know it is done and correct.
+
+### Out of scope
+
+- **Required — answer, do not delete.** What this item explicitly does *not* cover, plus the
+  follow-up item id if there is one, or an explicit `nothing deferred`.
+>
+> A blank line here is an unfinished plan, exactly like blank acceptance criteria. This section is
+> the one that prevents an item quietly growing a second purpose.
+
+## Execution
+
+Branch, key commits, notes, and any deviation from the plan **with its reason**.
+
+## Review
+
+Verification against each acceptance criterion. What was checked, and how.

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

@@ -0,0 +1,13 @@
+**Authoritative for:** how finished items are archived and why they are never edited afterwards.
+**Not authoritative for:** the content of any archived item, which is fixed at the moment it was archived.
+
+# Archive
+
+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
+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
+value of an archived record is that it says what was decided at the time.

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

@@ -0,0 +1,13 @@
+**Authoritative for:** what lives in this directory and when an item leaves it.
+**Not authoritative for:** the lifecycle itself, which is the methodology one level up.
+
+# Items
+
+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
+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

@@ -0,0 +1,9 @@
+<!-- rungs:begin backlog@1.0.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`**.
+<!-- rungs:end backlog -->

package/modules/backlog/gates/ids.toml

@@ -0,0 +1,106 @@
+# Gate table for the `backlog` module.
+#
+# Consumed by two engines the CLI provides — `id-integrity` and `git-status-reconcile`. No script
+# is written into the repo (ADR-0002). Everything here is data; anything that would need an
+# expression belongs in a `command` gate instead (ADR-0003 revisit trigger 3).
+
+# ── backlog-ids ───────────────────────────────────────────────────────────────
+
+[kinds.item]
+format  = "{{id_prefix}}-\\d{1,4}"
+marker  = { file = "docs/{{root}}/BACKLOG.md", pattern = "NEXT-ID: ({{id_prefix}}-\\d{1,4})" }
+sources = ["docs/{{root}}/items/**/*.md", "docs/{{root}}/archive/**/*.md"]
+# The archive is indexed so archived ids still resolve and stay permanently spent.
+
+[citations]
+# Where a reference to an id may appear, and must resolve.
+roots      = ["docs", "AGENTS.md", "CLAUDE.md", ".ai"]
+extensions = [".md", ".toml"]
+
+# ── backlog-stale-blocker ─────────────────────────────────────────────────────
+#
+# Refuses a document claiming it waits on work that has finished.
+#
+# The vocabulary is deliberately narrow, and that was measured: rift-forge's first draft matched
+# `until {{id_prefix}}-###` and hit 29 lines that were almost all true history in the repo's own
+# voice. `until` and `once … lands` were dropped, and past tense is a record rather than a claim.
+
+[stale_blocker]
+phrases = [
+  "blocked on",
+  "blocked by",
+  "waiting on",
+  "waiting for",
+  "pending",
+]
+# Checked against a preceding-context window, so a sentence explaining a retired claim is not
+# itself refused — a guard that also refuses its own fix is one people disable.
+negation_window = 60
+past_tense_ok   = ["was blocked on", "were blocked on", "had been blocked on", "used to be blocked"]
+exempt_marker   = "owner-ok:"          # ignored unless it states a reason
+scope_exclude   = ["docs/{{root}}/archive/**"]
+
+# ── backlog-merged-status ─────────────────────────────────────────────────────
+#
+# One-directional by design: a merged branch with a pre-review status is always wrong; an unmerged
+# branch at any status is not. The gate can only see items whose branch still exists, so deleting a
+# branch immediately after merge costs you the check — which is why the methodology says to delete
+# it *on* merge, after the status moves.
+
+[merged_status]
+branch_field        = "branch"
+status_field        = "status"
+pre_review_statuses = ["proposed", "accepted", "planned", "in_progress"]
+integration_branch  = "{{integration_branch}}"
+exempt_marker       = "branch-merged-ok:"   # ignored unless it states a reason
+
+# ── self-test ─────────────────────────────────────────────────────────────────
+#
+# A gate whose rules are all currently satisfied is indistinguishable from a gate that matches
+# nothing, so each engine runs these fixtures and asserts BOTH directions.
+
+[[self_test]]
+gate   = "backlog-stale-blocker"
+expect = "fail"
+input  = "The mapper is blocked on {{id_prefix}}-001, which is done."
+
+[[self_test]]
+gate   = "backlog-stale-blocker"
+expect = "pass"
+input  = "The mapper was blocked on {{id_prefix}}-001 until it landed."
+
+[[self_test]]
+gate   = "backlog-stale-blocker"
+expect = "pass"
+input  = "Do not write that a doc is blocked on finished work. <!-- owner-ok: quotes the retired rule to explain it -->"
+
+[[self_test]]
+gate   = "backlog-merged-status"
+expect = "fail"
+input  = "status: in_progress, branch merged into {{integration_branch}}"
+
+[[self_test]]
+gate   = "backlog-merged-status"
+expect = "pass"
+input  = "status: in_progress, branch not merged"
+
+# ── backlog-ids self-tests ────────────────────────────────────────────────────
+#
+# The marker case is the one worth pinning: a NEXT-ID pointing at an id that is
+# already spent hands the next session a collision, and the archive is indexed
+# precisely so an archived id still counts as taken.
+
+[[self_test]]
+gate    = "backlog-ids"
+expect  = "fail"
+fixture = { items = ["{{id_prefix}}-001-a.md", "{{id_prefix}}-001-b.md"] }
+
+[[self_test]]
+gate    = "backlog-ids"
+expect  = "pass"
+fixture = { items = ["{{id_prefix}}-001-a.md", "{{id_prefix}}-002-b.md"] }
+
+[[self_test]]
+gate    = "backlog-ids"
+expect  = "fail"
+fixture = { items = ["{{id_prefix}}-001-a.md"], marker = "{{id_prefix}}-001" }