@rungs/cli 0.3.1 → 0.4.0

package/modules/instructions/module.toml

@@ -1,6 +1,6 @@
 [module]
 name    = "instructions"
-version = "1.1.0"
+version = "1.2.0"
 rung    = 0
 summary = "The agent entry point, the harness bridge, path-scoped rule sources, and the render pipeline. The one module every repo installs."
 

package/modules/release/files/{{changelog_dir}}/CONSUMED_THROUGH

@@ -0,0 +1 @@
+UNINITIALIZED

package/modules/release/gates/release.toml

@@ -6,11 +6,12 @@
 # tests and tooling changes do not need release notes, and a gate that demands one for a typo fix
 # is a gate people learn to bypass.
 
-[file_population]
+[change_requires_file]
+base_branch          = "{{backlog.integration_branch}}"
 require_when_changed = ["src/**", "lib/**", "app/**", "server/**", "web/**", "packages/**"]
 requires_one_of     = ["{{changelog_dir}}/*.md"]
 ignore_when_only    = ["docs/**", "**/*.test.*", "**/*.spec.*", ".github/**", "*.md"]
-exempt_marker       = "changelog-ok:"      # ignored unless it states a reason
+exempt_marker       = "changelog-ok:"      # ignored unless followed by substantive text on that line
 message = """
 This branch changes shipping code and adds no fragment in {{changelog_dir}}/. Add one, or state why
 not with `changelog-ok: <reason>` — internal refactors with no user-visible effect are a legitimate
@@ -37,7 +38,7 @@ rule    = "all-agree"
 # version is a judgement about *your* repo, and the engine guessing it is how a healthy layout gets
 # a red gate. rungs' own docs site is the case that found this — a private, never-published package
 # sitting at its own version beside the CLI (F-023).
-exclude = []
+exclude = ["{{version_exclude}}"]
 
 # No `autofix` key. It named a "rungs release sync-version" command that does not exist and never
 # has, so the message told whoever hit this gate to run something that would fail. The engine now
@@ -63,6 +64,11 @@ note = "A green check means these files agree, not that the version is correct e
 # The other half of the fragment discipline. `release-changelog-fragment` catches a release-worthy
 # change that added no fragment; this catches a fragment that was consumed and never deleted.
 #
+# `CONSUMED_THROUGH` is the offline assertion that separates a fragment being prepared from an
+# equal-version fragment already assembled into a release. It is consumer-maintained state: the
+# module emits `UNINITIALIZED`, and the owner explicitly chooses `none` or the last consumed
+# version. A concrete value equals the package version in a steady tree.
+#
 # Only filenames that parse as a version are judged. A repo whose fragments are named per-change
 # (`42.feature.md`) states no version, so there is nothing to compare and nothing is claimed — a
 # gate that refused a naming convention it was not asked about is one people turn off.
@@ -70,11 +76,17 @@ note = "A green check means these files agree, not that the version is correct e
 [[changelog_freshness]]
 id        = "release-fragment-current"
 fragments = ["{{changelog_dir}}/*.md"]
-version   = { file = "package.json", path = "version" }
+versions = [
+  { file = "package.json", path = "version" },
+  { file = "Directory.Build.props", xpath = "//Version" },
+  { file = "pyproject.toml", path = "project.version" },
+  { file = "*/package.json", path = "version" },
+]
+consumed_through = "{{changelog_dir}}/CONSUMED_THROUGH"
 message = """
-This fragment names a version below the one being prepared, so it belongs to a release that already
-shipped. Delete it — fragments are consumed, not archived, and one left behind is republished as
-though it were new work.
+This fragment names an already-consumed version or falls below the package version being prepared.
+Delete it — fragments are consumed, not archived, and one left behind is republished as though it
+were new work.
 """
 
 # ── self-tests ────────────────────────────────────────────────────────────────
@@ -104,29 +116,117 @@ gate    = "release-changelog-fragment"
 expect  = "fail"
 fixture = { changed = ["src/a.ts"], fragments = [], exempt = "changelog-ok:" }
 
+# The tracked consumption marker is state, not release-note content. Its extensionless name must
+# not satisfy the changed-fragment obligation.
+[[self_test]]
+gate    = "release-changelog-fragment"
+expect  = "fail"
+fixture = { changed = ["src/a.ts"], fragments = ["{{changelog_dir}}/CONSUMED_THROUGH"] }
+
+[[self_test]]
+gate    = "release-changelog-fragment"
+expect  = "fail"
+fixture = { changed = ["src/a.ts"], fragments = [], inherited_exempt = "changelog-ok: historical internal rename" }
+
+[[self_test]]
+gate    = "release-changelog-fragment"
+expect  = "pass"
+fixture = { changed = ["src/a.ts"], fragments = [], inherited_exempt = "changelog-ok: historical internal rename", exempt = "changelog-ok: new cache path; output is unchanged" }
+
+[[self_test]]
+gate    = "release-fragment-current"
+expect  = "fail"
+fixture = { dir = "changelog.d", version = "0.2.0", fragments = [] }
+
 [[self_test]]
 gate    = "release-fragment-current"
 expect  = "fail"
-fixture = { dir = "changelog.d", version = "0.2.0", fragments = ["0.1.1.md"] }
+fixture = { dir = "changelog.d", version = "0.2.0", consumed_through = "UNINITIALIZED", fragments = [] }
+
+[[self_test]]
+gate    = "release-fragment-current"
+expect  = "fail"
+fixture = { dir = "changelog.d", version = "0.2.0", consumed_through = "", fragments = [] }
+
+[[self_test]]
+gate    = "release-fragment-current"
+expect  = "fail"
+fixture = { dir = "changelog.d", version = "0.2.0", consumed_through = "v0.2.0", fragments = [] }
+
+[[self_test]]
+gate    = "release-fragment-current"
+expect  = "fail"
+fixture = { dir = "changelog.d", version = "0.2.0", consumed_through = " 0.2.0 ", fragments = [] }
+
+[[self_test]]
+gate    = "release-fragment-current"
+expect  = "fail"
+fixture = { dir = "changelog.d", version = "0.2.0", consumed_through = "\uFEFF0.2.0", fragments = [] }
+
+[[self_test]]
+gate    = "release-fragment-current"
+expect  = "fail"
+fixture = { dir = "changelog.d", version = "0.2.0", consumed_through = "0.2.0\n", fragments = [] }
+
+[[self_test]]
+gate    = "release-fragment-current"
+expect  = "fail"
+fixture = { dir = "changelog.d", version = "0.2.0", consumed_through = "0.1.0", fragments = [] }
+
+[[self_test]]
+gate    = "release-fragment-current"
+expect  = "fail"
+fixture = { dir = "changelog.d", version = "0.2.0", consumed_through = "0.3.0", fragments = [] }
+
+# `none` is the explicit first-release exception. The equal fragment is still being prepared.
+[[self_test]]
+gate    = "release-fragment-current"
+expect  = "pass"
+fixture = { dir = "changelog.d", version = "0.2.0", consumed_through = "none", fragments = ["0.2.0.md"] }
 
 [[self_test]]
 gate    = "release-fragment-current"
 expect  = "pass"
-fixture = { dir = "changelog.d", version = "0.2.0", fragments = ["0.2.0.md"] }
+fixture = { dir = "changelog.d", version = "0.2.0", consumed_through = "0.2.0", fragments = [] }
+
+# F-025: after a cut, the forgotten fragment and package version are equal. The concrete
+# consumption boundary is what makes that shape fail rather than look like preparation.
+[[self_test]]
+gate    = "release-fragment-current"
+expect  = "fail"
+fixture = { dir = "changelog.d", version = "0.2.0", consumed_through = "0.2.0", fragments = ["0.2.0.md"] }
+
+[[self_test]]
+gate    = "release-fragment-current"
+expect  = "fail"
+fixture = { dir = "changelog.d", version = "0.2.0", consumed_through = "0.2.0", fragments = ["0.1.1.md"] }
 
 # A fragment for a version *above* the one being prepared is not stale — it is a branch that
 # already decided it is a minor while the package has not been bumped yet.
 [[self_test]]
 gate    = "release-fragment-current"
 expect  = "pass"
-fixture = { dir = "changelog.d", version = "0.2.0", fragments = ["0.3.0.md"] }
+fixture = { dir = "changelog.d", version = "0.2.0", consumed_through = "0.2.0", fragments = ["0.3.0.md"] }
 
 # Per-change fragment naming states no version, so there is nothing to compare and nothing is
 # claimed. The gate must stay silent rather than refuse a convention it was not asked about.
 [[self_test]]
 gate    = "release-fragment-current"
 expect  = "pass"
-fixture = { dir = "changelog.d", version = "0.2.0", fragments = ["42.feature.md"] }
+fixture = { dir = "changelog.d", version = "0.2.0", consumed_through = "0.2.0", fragments = ["42.feature.md"] }
+
+# The release module's version gate supports Node, .NET and Python repositories. The consumption
+# boundary must use the same ecosystem-neutral source set rather than making the latter two
+# permanently red after their first release.
+[[self_test]]
+gate    = "release-fragment-current"
+expect  = "pass"
+fixture = { dir = "changelog.d", version = "0.2.0", version_file = "Directory.Build.props", consumed_through = "0.2.0", fragments = [] }
+
+[[self_test]]
+gate    = "release-fragment-current"
+expect  = "pass"
+fixture = { dir = "changelog.d", version = "0.2.0", version_file = "pyproject.toml", consumed_through = "0.2.0", fragments = [] }
 
 [[self_test]]
 gate    = "release-version-consistent"
@@ -138,16 +238,68 @@ gate    = "release-version-consistent"
 expect  = "pass"
 fixture = { packages = { "package.json" = "1.2.0", "web/package.json" = "1.2.0" } }
 
-# The F-023 case: a sibling deliberately versioned on its own is excluded and the gate stays green,
-# rather than reporting a healthy layout as a disagreement.
+# All three advertised ecosystems contribute to one comparison. Equal values pass; changing only
+# Python fails and the engine's finding names every contributing file beside its value.
+[[self_test]]
+gate    = "release-version-consistent"
+expect  = "pass"
+fixture = { versions = { "package.json" = "1.2.0", "pyproject.toml" = "1.2.0", "Directory.Build.props" = "1.2.0" } }
+
+[[self_test]]
+gate    = "release-version-consistent"
+expect  = "fail"
+fixture = { versions = { "package.json" = "1.2.0", "pyproject.toml" = "2.0.0", "Directory.Build.props" = "1.2.0" } }
+
+# A matched source is evidence even when it is broken: malformed documents, missing configured
+# locations and unusable values all fail rather than disappearing from the comparison.
+[[self_test]]
+gate    = "release-version-consistent"
+expect  = "fail"
+fixture = { version_files = { "package.json" = "{" } }
+
+[[self_test]]
+gate    = "release-version-consistent"
+expect  = "fail"
+fixture = { version_files = { "pyproject.toml" = "[project" } }
+
+[[self_test]]
+gate    = "release-version-consistent"
+expect  = "fail"
+fixture = { version_files = { "package.json" = "{\"name\":\"fixture\"}" } }
+
+[[self_test]]
+gate    = "release-version-consistent"
+expect  = "fail"
+fixture = { version_files = { "pyproject.toml" = "[project]\nname = \"fixture\"\n" } }
+
+[[self_test]]
+gate    = "release-version-consistent"
+expect  = "fail"
+fixture = { version_files = { "Directory.Build.props" = "<Project><PropertyGroup><VersionPrefix>1.2.0</VersionPrefix></PropertyGroup></Project>" } }
+
+[[self_test]]
+gate    = "release-version-consistent"
+expect  = "fail"
+fixture = { version_files = { "Directory.Build.props" = "<Project><Version>1.2.0</Version>" } }
+
+[[self_test]]
+gate    = "release-version-consistent"
+expect  = "fail"
+fixture = { version_files = { "Directory.Build.props" = "<Project><![CDATA[<Version>1.2.0</Version>]]></Project>" } }
+
+[[self_test]]
+gate    = "release-version-consistent"
+expect  = "fail"
+fixture = { version_files = { "package.json" = "{\"version\":{}}" } }
+
+# Unmatched sources are optional when one valid source participates. When none of the configured
+# globs contributes a file, the gate refuses to manufacture a green result from zero evidence.
 [[self_test]]
 gate    = "release-version-consistent"
 expect  = "pass"
-fixture = { packages = { "package.json" = "1.2.0", "web/package.json" = "0.0.1" }, exclude = ["web/package.json"] }
+fixture = { versions = { "package.json" = "1.2.0" } }
 
-# …and excluding one sibling must not blind the gate to a different one. An `exclude` that
-# silently widened would be worse than no gate, because it would still report green.
 [[self_test]]
 gate    = "release-version-consistent"
 expect  = "fail"
-fixture = { packages = { "package.json" = "1.2.0", "web/package.json" = "0.0.1", "api/package.json" = "9.9.9" }, exclude = ["web/package.json"] }
+fixture = { version_files = { "README.md" = "# no version source\n" } }

package/modules/release/module.toml

@@ -1,6 +1,6 @@
 [module]
 name    = "release"
-version = "1.2.0"
+version = "1.6.0"
 rung    = 3
 summary = "Candidate, stable and deploy branch lines; one procedure for cutting a release, hotfixing and rolling back; changelog fragments instead of a shared file."
 
@@ -42,10 +42,14 @@ description = "semver | calver"
 default     = "semver"
 consumed_by = "render"
 
+[params.version_exclude]
+description = "One glob for files versioned independently of this release. Use a brace group for several paths; empty excludes nothing."
+default     = ""
+
 [[gates]]
 id     = "release-changelog-fragment"
 kind   = "declared"
-engine = "file-population"
+engine = "change-requires-file"
 applicability = "repo-content"
 table  = "gates/release.toml"
 tier   = "fast"
@@ -59,13 +63,13 @@ the change.
 id     = "release-fragment-current"
 kind   = "declared"
 engine = "changelog-freshness"
-applicability = "repo-content"
+applicability = "our-schema"
 table  = "gates/release.toml"
 tier   = "fast"
 why    = """
 Fragments are consumed at release time, not archived — one left behind appears in the next release
-too, where it reads as unreleased work. `cut-release` §3 has said so in prose since it was written,
-and prose did not hold it: this repo's own `0.1.1` fragment survived two releases (F-022).
+too, where it reads as unreleased work. The tracked consumption boundary distinguishes a fragment
+being prepared from the equal-version fragment this repo left behind after v0.2.0 (F-025).
 """
 
 [[gates]]

package/modules/release/skills/cut-release/SKILL.md

@@ -12,17 +12,28 @@ description: >-
 
 **Every step below is reversible except the tag and the deploy.** Know which one you are on.
 
-## 1. Decide the version
+## 1. Initialise the consumption boundary
+
+Open `{{changelog_dir}}/CONSUMED_THROUGH`. If it says `UNINITIALIZED`, replace it with `none` only
+when no release has ever consumed fragments; otherwise write the exact last version whose fragments
+were assembled. **Do not infer this from a package version, tag or registry.** Those say what was
+versioned or published, not whether its fragments were actually consumed.
+
+This is a changelog-consumption claim, not a publication claim. In a steady tree its concrete value
+equals the package version. During the reversible preparation below it briefly moves ahead, then the
+version bump restores equality before the final gate.
+
+## 2. Decide the version
 
 From the changelog fragments in `{{changelog_dir}}/`, not from memory or from what the last release
 was. A breaking change in any fragment decides the major; a feature decides the minor. If the
 fragments do not support the version you were asked for, **say so before continuing** — that
 mismatch is usually a fragment somebody skipped, not a versioning disagreement.
 
-## 2. Gate
+## 3. Gate the current tree
 
 ```bash
-rungs check
+node .ai/rungs.mjs check
 ```
 
 Run **every** registered gate. This step used to name a "--tier full" flag that the CLI does not
@@ -30,7 +41,8 @@ accept, so both words were parsed as positionals and the run checked a directory
 exist — reporting no gates rather than a pass. A release step that gates on nothing while looking
 green is worse than one that is skipped, because nobody goes back to check it.
 
-Narrow to a tier (`rungs check --fast`) only when you know the tier holds what you meant to run.
+Narrow to a tier (`node .ai/rungs.mjs check fast`) only when you know the tier holds what you meant
+to run.
 
 **Do not proceed on a red gate**, and do not weaken one to get through. A release is exactly the
 moment the temptation is highest and the cost of yielding is highest.
@@ -38,17 +50,31 @@ moment the temptation is highest and the cost of yielding is highest.
 If a gate is red for reasons that predate this work, say so explicitly and get a decision. Shipping
 past a known-red gate is a choice someone should make on purpose.
 
-## 3. Assemble the changelog
+## 4. Assemble the changelog and advance the boundary
+
+As one reversible preparation, combine the fragments into the release section, **delete the
+fragments**, and set `{{changelog_dir}}/CONSUMED_THROUGH` to the version being prepared. Fragments
+are consumed, not archived — a fragment left behind appears in the next release too. Advancing the
+marker in the same change makes a retained equal-version fragment mechanically red (F-025).
+
+## 5. Bump the version
 
-Combine the fragments into the release section, then **delete the fragments**. They are consumed,
-not archived — a fragment left behind appears in the next release too.
+In every place it appears. The bump restores equality with the consumption boundary;
+`release-version-consistent` computes agreement across version surfaces rather than trusting you.
 
-## 4. Bump the version
+## 6. Gate the prepared tree
+
+Run **every** registered gate again. The preliminary gate proved the starting point; this one proves
+the exact tree that will be tagged. It must see the package version and concrete consumption
+boundary agree, with no fragment at or below that boundary.
+
+```bash
+node .ai/rungs.mjs check
+```
 
-In every place it appears. `release-version-consistent` computes this rather than trusting you;
-run it before tagging, because a version that disagrees with itself is discovered by a user.
+Do not tag on red, and require CI to pass at the exact prepared commit.
 
-## 5. Tag and merge
+## 7. Tag and merge
 
 - Annotated tag on the candidate, message naming the release.
 - Merge the candidate into `{{stable_branch}}`.
@@ -56,7 +82,7 @@ run it before tagging, because a version that disagrees with itself is discovere
   roll back to** — a rollback that means reverting commits on the stable line is a rollback nobody
   performs correctly under pressure.
 
-## 6. Open the next candidate
+## 8. Open the next candidate
 
 Cut a new `{{candidate_prefix}}<next>` immediately. A period with no open candidate is a period
 where work lands somewhere improvised.
@@ -69,9 +95,11 @@ Branch **from the deploy branch, never from the candidate** — the candidate co
 work, and shipping it as a hotfix is how an unrelated feature reaches production during an
 incident.
 
-Fix → gate → tag a patch version → merge into `{{stable_branch}}` **and forward into the active
-candidate**. The forward-merge is the step people skip, and skipping it means the next release
-silently reverts the hotfix.
+Fix and add its patch fragment, then use the same reversible preparation as a normal cut: assemble
+the fragment, delete it, advance `{{changelog_dir}}/CONSUMED_THROUGH`, bump every version surface,
+and run every gate against the exact prepared commit. Only then tag the patch, merge it into
+`{{stable_branch}}` **and forward into the active candidate**. The forward-merge is the step people
+skip, and skipping it means the next release silently reverts the hotfix.
 
 ## Rollback
 

package/modules/session/files/{{archive}}/README.md

@@ -9,7 +9,7 @@ Closed sessions, one file each, newest first in the index generated into
 
 The filename does the work. Someone scanning this directory should be able to find the session
 that closed a given piece of work without opening anything — which is why the name carries both
-halves, not just a number. `rungs check` refuses a name that does not.
+halves, not just a number. `node .ai/rungs.mjs check` refuses a name that does not.
 
 ## What an archive note holds
 

package/modules/session/files/{{path}}

@@ -50,8 +50,8 @@ Keep it short. This document is read at the start of every session, and a long o
 ## Archive
 
 <!-- rungs:begin session-archive -->
-<!-- Generated by `rungs render` from {{archive}}/. The link above is relative and assumes
+<!-- Generated by `node .ai/rungs.mjs render` from {{archive}}/. The link above is relative and assumes
      the archive sits beside this file, which is the default. A relative link between two
      parameterised paths cannot be computed without logic, and ADR-0003 has none — so moving
-     one without the other is a divergence `rungs check` will report as a broken link. -->
+     one without the other is a divergence `node .ai/rungs.mjs check` will report as a broken link. -->
 <!-- rungs:end session-archive -->

package/modules/session/module.toml

@@ -1,6 +1,6 @@
 [module]
 name    = "session"
-version = "1.2.0"
+version = "1.3.0"
 rung    = 1
 summary = "A handoff document carrying state between sessions: resume point, active constraints, and a dated archive."
 

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

@@ -9,7 +9,7 @@ need to know what is happening right now, that is the backlog, not here.
 ## Index
 
 <!-- rungs:begin specs-index -->
-<!-- Generated by `rungs render`. -->
+<!-- Generated by `node .ai/rungs.mjs render`. -->
 
 | Spec | Scope | Status | File |
 | --- | --- | --- | --- |
@@ -37,7 +37,7 @@ explicit note. **Never ✅.**
 
 A spec that overclaims integration is worse than no spec, because it is read as verified — by the
 next contributor, by a plan that cites it, and by an agent deciding a story is already handled.
-`rungs check` refuses a ✅ story that does not name what closed it.
+`node .ai/rungs.mjs check` refuses a ✅ story that does not name what closed it.
 
 ## Proposing new cross-cutting scope
 

package/modules/specs/module.toml

@@ -1,6 +1,6 @@
 [module]
 name    = "specs"
-version = "1.0.0"
+version = "1.1.0"
 rung    = 2
 summary = "Behaviour specifications with stable feature and story ids, per-story status, a mandatory scope section, and a gate against overclaiming."
 

package/modules/workflows/module.toml

@@ -1,6 +1,6 @@
 [module]
 name    = "workflows"
-version = "1.1.0"
+version = "1.2.0"
 rung    = 2
 summary = "Decision procedures: how to decompose work, whether to reuse or build, and how much planning a piece of work earns."
 

package/modules/workflows/rules/planning-tiers.md

@@ -35,7 +35,7 @@ Any one of these is enough:
 
 ## Tier is declared, not inferred
 
-Every plan carries `tier:` in its frontmatter. `rungs check` reads it and checks that tier's
+Every plan carries `tier:` in its frontmatter. `node .ai/rungs.mjs check` reads it and checks that tier's
 required sections are present and non-empty. A plan with no tier cannot be checked, and tiering
 degrades back into "write whatever felt right" — which is the judgement call this table replaces.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rungs/cli",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Installs and maintains a repository's agentic development system, composed from modules.",
   "author": "Antoine Dancre",
   "repository": {
@@ -43,7 +43,8 @@
   ],
   "license": "MIT",
   "dependencies": {
-    "smol-toml": "^1.8.0"
+    "saxes": "6.0.0",
+    "smol-toml": "1.8.0"
   },
   "devDependencies": {
     "esbuild": "^0.25.12"