@rungs/cli 0.1.0

package/modules/instructions/module.toml

@@ -0,0 +1,127 @@
+[module]
+name    = "instructions"
+version = "1.0.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."
+
+[requires]
+modules = []
+
+[conflicts]
+modules = []
+
+# ── parameters ────────────────────────────────────────────────────────────────
+
+[params.project_name]
+description = "Name used in the entry document's first line"
+default     = ""            # inferred from the repo directory when blank
+
+[params.harnesses]
+description  = "Which coding agents to emit for. Drives the ADR-0001 render matrix."
+default      = ["claude", "agents-md"]
+allowed      = ["claude", "copilot", "cursor", "agents-md"]
+consumed_by  = "render"
+# `consumed_by` marks a *behavioural* parameter: it changes what the CLI does rather than being
+# substituted into a template, so it will never appear as {{harnesses}} anywhere. Without this a
+# dead-parameter lint would report it, and the obvious "fix" would be to delete the parameter that
+# decides which harnesses exist.
+
+[params.core_budget]
+description = """
+Maximum lines in AGENTS.md before `instructions-core-size` fails. 200 is Anthropic's published
+guidance: "Longer files consume more context and reduce adherence." Fragments merged by other
+modules count against it, which is deliberate — the budget is what forces content into
+path-scoped rules instead.
+"""
+default     = 200
+
+# ── gates ─────────────────────────────────────────────────────────────────────
+
+[[gates]]
+id     = "instructions-core-size"
+kind   = "declared"
+engine = "file-budget"
+table  = "gates/core.toml"
+tier   = "fast"
+why    = "rift-forge's entry document reached 1513 lines and every session read all of it, in the one repo that otherwise measured everything."
+
+[[gates]]
+id     = "instructions-render-current"
+kind   = "declared"
+engine = "render-freshness"
+table  = "gates/core.toml"
+tier   = "fast"
+why    = "A rendered rule that no longer matches its source is a rule the agent is not reading. A green check means 'not yet regenerated', never 'current'."
+
+[[gates]]
+id     = "instructions-repo-map-current"
+kind   = "declared"
+engine = "render-freshness"
+table  = "gates/core.toml"
+tier   = "fast"
+why    = "Every source repo hand-maintained a repo map and one of them grew five duplicated entries — in the file every session reads first."
+
+# A hook is a gate with a lifecycle trigger rather than a runner trigger. It is
+# registered into the harness that supports it and reported as degraded for those
+# that do not, exactly like any other ADR-0001 target.
+[[gates]]
+id      = "instructions-shell-backticks"
+kind    = "declared"
+engine  = "shell-safety"
+table   = "gates/core.toml"
+trigger = "pre-tool-use"
+matcher = "Bash|PowerShell"
+why     = """
+Inside a double-quoted shell string, backticks are command substitution, so a `node -e "…"` that
+writes documentation deletes the backticked words and leaves grammatical text behind. It exits 0.
+rift-forge measured six occurrences and six repair passes in one session, documented it, and was
+broken three more times before making it a hook — which is the whole argument for the escalation
+ladder this module ships.
+"""
+
+# ── detection (ADR-0004) ──────────────────────────────────────────────────────
+
+[detect]
+paths = [
+  "AGENTS.md",
+  "CLAUDE.md",
+  ".github/copilot-instructions.md",
+  ".cursorrules",
+  ".ai/instructions.md",
+]
+markers = ["rungs:begin instructions"]
+
+# No `detect.paradigm`: there is no competing paradigm for "the file the agent
+# reads first". Every repo either has one or does not.
+
+[[detect.infer]]
+param   = "harnesses"
+# Presence of a harness's own directory proposes adding it to the matrix.
+# Proposes only — a stale `.cursorrules` is not consent to emit Cursor rules.
+paths   = { claude = ".claude/", copilot = ".github/instructions/", cursor = ".cursor/" }
+
+# ── provenance (required, validated) ──────────────────────────────────────────
+
+[provenance]
+sources  = ["axiom-mesh", "hexguard", "hexguard-templates", "rift-forge"]
+patterns = [
+  "entry-point",
+  "agents-md-bridge",
+  "scoped-instructions",
+  "core-size-budget",
+  "validation-matrix",
+  "repo-map",
+  "narrowest-anchor-loop",
+  "negative-conventions",
+  "comms-style",
+  "shell-editing-rules",
+  "instruction-hardening",
+]
+incident = """
+All four source repos converged on a single canonical entry document, and all four put content in
+it that decayed. axiom-mesh's 350-line file had to warn four times that one of its own routing
+targets was a dead redirect. hexguard-templates' repo map grew five duplicated entries in the file
+every session reads first, in the repo whose conventions forbid restating scope. rift-forge reached
+1513 lines with no path scoping at all, while hexguard had solved that with applyTo globs a month
+earlier. Nobody had both completeness and scope.
+"""

package/modules/release/fragments/AGENTS.md

@@ -0,0 +1,8 @@
+<!-- rungs:begin release@1.0.0 -->
+## Releases
+
+`{{candidate_prefix}}<version>` integrates the next release, `{{stable_branch}}` is the released
+line, and `{{deploy_branch_prefix}}<version>` is what you deploy from **and roll back to**. Ship
+with **`/cut-release`** — never by hand. Changed shipping code? Add a fragment in
+`{{changelog_dir}}/` on the same branch.
+<!-- rungs:end release -->

package/modules/release/gates/release.toml

@@ -0,0 +1,85 @@
+# Gate table for the `release` module.
+
+# ── release-changelog-fragment ────────────────────────────────────────────────
+#
+# Fires on a branch that changed shipping code and added no fragment. Deliberately narrow: docs,
+# 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]
+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
+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
+reason, and saying so takes less time than reconstructing it at cut time.
+"""
+
+# ── release-version-consistent ────────────────────────────────────────────────
+#
+# The version is derivable, so it is computed rather than compared against a typed value. Probing
+# only what the data settles without judgement: every listed location must agree with every other,
+# which needs no opinion about which is right.
+
+[[computed_claim]]
+id      = "version"
+sources = [
+  { file = "package.json", path = "version" },
+  { file = "*/package.json", path = "version" },
+  { file = "Directory.Build.props", xpath = "//Version" },
+  { file = "pyproject.toml", path = "project.version" },
+]
+rule    = "all-agree"
+autofix = "rungs release sync-version"
+message = """
+Version disagrees across {count} locations: {values}. One of them was bumped and the others were
+not, which is discovered by a user rather than by us. Do not hand-edit — run the autofix.
+"""
+
+# What this does not cover is pinned, so green never reads as "verified":
+[computed_claim.pins]
+uncovered = [
+  "version strings embedded in source constants",
+  "versions in documentation prose",
+  "container image tags",
+]
+note = "A green check means these files agree, not that the version is correct everywhere."
+
+# ── self-tests ────────────────────────────────────────────────────────────────
+
+[[self_test]]
+gate    = "release-changelog-fragment"
+expect  = "fail"
+fixture = { changed = ["src/a.ts"], fragments = [] }
+
+[[self_test]]
+gate    = "release-changelog-fragment"
+expect  = "pass"
+fixture = { changed = ["src/a.ts"], fragments = ["{{changelog_dir}}/42.feature.md"] }
+
+[[self_test]]
+gate    = "release-changelog-fragment"
+expect  = "pass"
+fixture = { changed = ["docs/a.md"], fragments = [] }
+
+[[self_test]]
+gate    = "release-changelog-fragment"
+expect  = "pass"
+fixture = { changed = ["src/a.ts"], fragments = [], exempt = "changelog-ok: internal rename, no user-visible effect" }
+
+[[self_test]]
+gate    = "release-changelog-fragment"
+expect  = "fail"
+fixture = { changed = ["src/a.ts"], fragments = [], exempt = "changelog-ok:" }
+
+[[self_test]]
+gate    = "release-version-consistent"
+expect  = "fail"
+fixture = { values = ["1.2.0", "1.1.0"] }
+
+[[self_test]]
+gate    = "release-version-consistent"
+expect  = "pass"
+fixture = { values = ["1.2.0", "1.2.0"] }

package/modules/release/module.toml

@@ -0,0 +1,97 @@
+[module]
+name    = "release"
+version = "1.0.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."
+
+[requires]
+modules = ["backlog", "ci"]
+
+[conflicts]
+modules = []
+
+[params.candidate_prefix]
+description = """
+Prefix for the branch integrating the next release — `candidate/0.2.0`. A prefix, not a full name:
+the version is decided when a release is cut, not when the module is installed, so a parameter
+holding the whole branch name would be stale before it was ever used.
+"""
+default     = "candidate/"
+
+[params.stable_branch]
+description = "The released line. Tagged, never developed on directly."
+default     = "main"
+
+[params.deploy_branch_prefix]
+description = """
+Long-lived branch cut per release to deploy from — and to roll back to. A rollback that means
+reverting commits on the stable line is a rollback nobody performs under pressure.
+"""
+default     = "release/"
+
+[params.changelog_dir]
+description = """
+One file per change instead of a shared CHANGELOG. A shared changelog is a guaranteed conflict on
+every concurrent branch, and the conflict is always resolved by keeping both — which is how
+duplicate entries ship.
+"""
+default     = "changelog.d"
+
+[params.version_scheme]
+description = "semver | calver"
+default     = "semver"
+consumed_by = "render"
+
+[[gates]]
+id     = "release-changelog-fragment"
+kind   = "declared"
+engine = "file-population"
+table  = "gates/release.toml"
+tier   = "fast"
+why    = """
+A change with no changelog fragment is a change the release notes will not mention, discovered at
+cut time when nobody remembers what it did. Cheaper to require the fragment on the branch that made
+the change.
+"""
+
+[[gates]]
+id     = "release-version-consistent"
+kind   = "declared"
+engine = "computed-claim"
+table  = "gates/release.toml"
+tier   = "fast"
+why    = "A version appears in several files and drifts in exactly one of them. It is derivable, so it is computed rather than typed."
+
+[skills.cut-release]
+extensions = { disable-model-invocation = true }
+extension_note = """
+Cutting a release tags, merges and moves a deploy branch. A model must never decide that now is the
+moment to ship. This costs packaging for claude.ai uploads and the Skills API; it stays portable to
+every skills-compatible CLI.
+"""
+
+[detect]
+paths   = ["CHANGELOG.md", "changelog.d/**", ".github/workflows/release*.yml", "docs/**/release-workflow.md"]
+markers = ["rungs:begin release"]
+
+[[detect.paradigm]]
+id      = "trunk-tag-only"
+paths   = [".github/workflows/release*.yml"]
+compare = "docs/research/synthesis.md#5-the-maturity-ladder"
+note    = """
+Tagging directly on the trunk is a legitimate, cheaper model, and most repos should stay there. The
+candidate/stable/deploy split earns its cost when several sessions integrate into one release and
+a rollback has to be possible without reverting commits. Report the difference; do not convert.
+"""
+
+[provenance]
+sources  = ["rift-forge"]
+patterns = ["candidate-and-release-lines", "release-skill"]
+incident = """
+rift-forge separates the candidate that integrates the next release, the stable line that is tagged,
+and a long-lived deploy branch cut per release — because a rollback that means reverting commits on
+the stable line is a rollback nobody performs correctly under pressure. Its changelog is fragment
+files rather than one document, for the same reason its id ledgers needed a merge driver: a shared
+file touched by every concurrent branch conflicts every time, and the conflict is always resolved
+by keeping both.
+"""

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

@@ -0,0 +1,81 @@
+---
+name: cut-release
+description: >-
+  Cut, tag and ship a release from the active candidate — gates, version bump, changelog assembly,
+  annotated tag, the long-lived deploy branch, merge to the stable line, and opening the next
+  candidate — plus the hotfix and rollback flows. Use when asked to "cut / ship / tag the release",
+  "release v1.2.0", "bump the version", "hotfix production", "roll back the deploy", or "open the
+  next candidate". Executing one tracked item is /work-item; assessing readiness is /assess.
+---
+
+# Cut a release
+
+**Every step below is reversible except the tag and the deploy.** Know which one you are on.
+
+## 1. 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
+
+```bash
+rungs check --tier full
+```
+
+**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.
+
+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
+
+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.
+
+## 4. Bump the version
+
+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.
+
+## 5. Tag and merge
+
+- Annotated tag on the candidate, message naming the release.
+- Merge the candidate into `{{stable_branch}}`.
+- Cut `{{deploy_branch_prefix}}<version>` from the tag. **This is what you deploy from and what you
+  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
+
+Cut a new `{{candidate_prefix}}<next>` immediately. A period with no open candidate is a period
+where work lands somewhere improvised.
+
+---
+
+## Hotfix
+
+Branch **from the deploy branch, never from the candidate** — the candidate contains unreleased
+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.
+
+## Rollback
+
+Point the deploy at the previous `{{deploy_branch_prefix}}<version>`. Do not revert commits.
+
+**Then record why**, as a finding at minimum. A rollback with no written cause is one the team
+repeats, and the pressure of the moment is exactly why it will not be remembered otherwise.
+
+## What this skill will not do
+
+- Decide *whether* to release. That is a judgement about readiness, not a procedure.
+- Proceed past a red gate without an explicit decision from a person.
+- Deploy. Tagging and cutting the branch is where this stops; what consumes them is your
+  infrastructure.

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

@@ -0,0 +1,28 @@
+# Session archive
+
+Closed sessions, one file each, newest first in the index generated into
+[`{{path}}`](../session.md).
+
+## Naming
+
+`YYYY-MM-DD_session-NN_<what-closed>-and-<what-is-next>.md`
+
+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.
+
+## What an archive note holds
+
+- What was delivered, and what was **not** delivered that was planned
+- Decisions taken, with their reasons — especially ones that became active constraints
+- The handoff state at close: what the next session was told to do
+- Anything that turned out to be wrong during the session, and what replaced it
+
+## What it is not
+
+**An archive note is a record, not a source of truth.** It says what was believed at a moment. If
+it disagrees with a spec, a decision record, or the code, those win — and the disagreement is
+worth a finding, because it means something changed without its authority being updated.
+
+**Never edit an archived note** to reflect what was learned later. Its value is that it is what
+was known then.

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

@@ -0,0 +1,56 @@
+# Session state
+
+The live handoff. **Rewritten as work moves, not appended to.** Everything here is present tense;
+history belongs in [`{{archive}}/`](archive/README.md).
+
+Keep it short. This document is read at the start of every session, and a long one is skimmed.
+
+## Current objective
+
+<!-- One or two sentences. What is being pursued right now, not the roadmap. -->
+
+## In progress
+
+<!-- What is actually being worked on, with its id. Empty is a valid and honest answer. -->
+
+## Resume from
+
+<!-- The single next concrete action. A path, a command, a work-item id — something a cold session
+     can act on without reconstructing context. This is the section that earns the document. -->
+
+## Up next
+
+1.
+
+## Active constraints — do not reopen
+
+<!-- Decisions already settled that a fresh session would otherwise relitigate, each with why it
+     is closed. Name them specifically: "the storage boundary is fixed by ADR-0007, do not
+     re-scope it" beats "architecture is settled".
+
+     This is the section that pays for the document. Without it every session re-derives, and
+     re-derivation reaches a different answer often enough to matter. -->
+
+-
+
+## Working assumptions
+
+<!-- Things believed true and not verified this session. Being wrong here is normal; the value is
+     that the next session knows which claims to distrust first. -->
+
+-
+
+## Open questions
+
+<!-- Blocking and non-blocking, marked. "None blocking" is a useful thing to state. -->
+
+-
+
+## Archive
+
+<!-- rungs:begin session-archive -->
+<!-- Generated by `rungs 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. -->
+<!-- rungs:end session-archive -->

package/modules/session/fragments/AGENTS.md

@@ -0,0 +1,6 @@
+<!-- rungs:begin session@1.0.0 -->
+## Session state
+
+Read [`{{path}}`]({{path}}) first. Treat **Active constraints — do not reopen** as binding:
+settled decisions, not suggestions. Close a session with **`/close-session`**.
+<!-- rungs:end session -->

package/modules/session/gates/session.toml

@@ -0,0 +1,63 @@
+# Gate table for the `session` module.
+
+# ── session-sections-present ──────────────────────────────────────────────────
+#
+# Presence, not content. A gate cannot judge whether a resume point is useful, and one that tried
+# would be the confidently-wrong probe. An empty section under its heading is allowed — an honest
+# "nothing in progress" is a real answer, and demanding prose would produce filler.
+
+[sections]
+file     = "{{path}}"
+required = [
+  "Current objective",
+  "In progress",
+  "Resume from",
+  "Up next",
+  "Active constraints — do not reopen",
+  "Working assumptions",
+  "Open questions",
+]
+non_empty = false
+message   = """
+{file} is missing `{section}`. The fixed section list is the point: a handoff that drops
+"Active constraints" is one where the next session reopens a settled question.
+"""
+
+# ── session-archive-named ─────────────────────────────────────────────────────
+
+[filename_schema]
+scan    = ["{{archive}}/*.md"]
+exclude = ["{{archive}}/README.md"]
+pattern = "^\\d{4}-\\d{2}-\\d{2}_session-\\d+_[a-z0-9-]+\\.md$"
+message = """
+`{file}` does not name what closed and what came next. Use
+YYYY-MM-DD_session-NN_<what-closed>-and-<what-is-next>.md — the filename is what makes the
+directory scannable without opening anything.
+"""
+
+# ── self-tests ────────────────────────────────────────────────────────────────
+
+[[self_test]]
+gate    = "session-sections-present"
+expect  = "fail"
+fixture = { sections = ["Current objective", "In progress", "Resume from"] }
+
+[[self_test]]
+gate    = "session-sections-present"
+expect  = "pass"
+fixture = { sections = ["Current objective", "In progress", "Resume from", "Up next", "Active constraints — do not reopen", "Working assumptions", "Open questions"] }
+
+[[self_test]]
+gate   = "session-archive-named"
+expect = "fail"
+input  = "{{archive}}/session-4.md"
+
+[[self_test]]
+gate   = "session-archive-named"
+expect = "pass"
+input  = "{{archive}}/2026-08-14_session-04_storage-closeout-and-api-handoff.md"
+
+[[self_test]]
+gate   = "session-archive-named"
+expect = "pass"
+input  = "{{archive}}/README.md"

package/modules/session/module.toml

@@ -0,0 +1,72 @@
+[module]
+name    = "session"
+version = "1.0.0"
+rung    = 1
+summary = "A handoff document carrying state between sessions: resume point, active constraints, and a dated archive."
+
+[requires]
+modules = []
+
+[conflicts]
+modules = []
+
+# A `mode = file | board` parameter was specified in the catalog and dropped on
+# authoring. "Board mode" meant deriving session state from the backlog and
+# creating no file — which is not a mode, it is **not installing this module**.
+# A parameter whose value is "do nothing" is the absence of the module, and
+# substitution-only templating cannot express it anyway.
+
+[params.path]
+description = "The live handoff document"
+default     = ".ai/session.md"
+
+[params.archive]
+description = "Where closed sessions are kept"
+default     = ".ai/archive"
+
+[[gates]]
+id     = "session-sections-present"
+kind   = "declared"
+engine = "frontmatter-schema"
+table  = "gates/session.toml"
+tier   = "fast"
+why    = """
+The sections are the value. A handoff missing "Active constraints" is one where the next session
+reopens a settled question, which is the specific failure this document exists to prevent.
+"""
+
+[[gates]]
+id     = "session-archive-named"
+kind   = "declared"
+engine = "filename-schema"
+table  = "gates/session.toml"
+tier   = "fast"
+why    = "An archive whose filenames do not say what closed and what came next is a folder nobody opens."
+
+[skills.close-session]
+extensions = { disable-model-invocation = true }
+extension_note = """
+Closing a session archives the live document and rewrites it. A model should not decide the session
+is over. Opting in costs packaging for claude.ai uploads and the Skills API; it stays portable to
+every skills-compatible CLI.
+"""
+
+[detect]
+paths = [
+  ".ai/session.md",
+  ".ai/context/session.md",
+  "docs/**/session.md",
+  ".ai/context/archive/**/*.md",
+]
+markers = ["rungs:begin session"]
+
+[provenance]
+sources  = ["axiom-mesh"]
+patterns = ["session-handoff", "settled-decisions-lock", "dated-session-archive"]
+incident = """
+axiom-mesh kept 21 dated handoff notes and a live session document with fixed sections, and its
+resume state is genuinely readable cold — the only repo of the four where a new session can start
+without reconstructing context from git. The section that earns its keep is "Active constraints /
+decisions since last archive", whose wording is a standing instruction not to reopen settled
+questions: "do not reopen helper ownership, topology, host-boundary … unless explicitly re-planned."
+"""