@rungs/cli 0.1.0

package/modules/session/skills/close-session/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: close-session
+description: >-
+  Close out a working session: write the dated archive note, reset the live handoff document to a
+  cold-readable resume point, and record what became an active constraint. Use when asked to
+  "close the session", "wrap up", "archive this session", "hand off", "write the handoff", or at
+  the end of a long stretch of work before context is lost. Recording an out-of-scope observation
+  is /record-finding; finishing a tracked item is /work-item.
+---
+
+# Close a session
+
+The test for everything below: **could a session starting cold tomorrow, with no memory of this
+conversation, pick up from the document alone?** If not, it is not closed.
+
+## 1. Write the archive note
+
+`{{archive}}/YYYY-MM-DD_session-NN_<what-closed>-and-<what-is-next>.md`. The filename carries both
+halves so the directory is scannable without opening anything.
+
+Contents:
+
+- **Delivered** — what actually landed, with ids.
+- **Not delivered** — what was planned and did not happen, **and why**. This is the half people
+  skip, and it is the half that stops the next session re-planning the same thing.
+- **Decisions taken**, with reasons. Flag any that should become an active constraint.
+- **What turned out to be wrong** during the session, and what replaced it.
+
+Write what was believed at close. **Never revise an archived note later** — its value is that it
+records what was known then.
+
+## 2. Rewrite the live document
+
+`{{path}}` is **rewritten, not appended to.** Delete what is no longer true rather than layering
+qualifications on it.
+
+- **Resume from** — one concrete next action. A path, a command, an id. Not "continue the
+  refactor"; something that can be executed.
+- **Active constraints** — move any decision here that a fresh session would otherwise relitigate,
+  each with why it is closed. Be specific: *"the storage boundary is fixed by ADR-0007, do not
+  re-scope it"* beats *"architecture is settled"*. **This section is what pays for the document.**
+- **Working assumptions** — what is believed but unverified. Being wrong here is expected; the
+  value is telling the next session which claims to distrust first.
+- **Open questions** — mark which block progress. "None blocking" is worth stating.
+
+## 3. Check it against the archive
+
+The live document should now say nothing the archive note repeats. If it does, one of them is
+wrong later: **the live document is present tense, the archive is past tense**, and a fact in both
+will drift in one.
+
+## 4. What not to do
+
+- **Do not close a session to avoid finishing something.** If work is half-done, say so in
+  `In progress` with what remains — a handoff that hides a loose end is worse than no handoff.
+- **Do not summarise the conversation.** The archive records outcomes and decisions, not a
+  narrative. Nobody reads a transcript.
+- **Do not promote an assumption to a constraint** because it went unchallenged. A constraint is
+  something decided; an assumption is something believed.

package/modules/skills/fragments/AGENTS.md

@@ -0,0 +1,8 @@
+<!-- rungs:begin skills@1.0.0 -->
+## Skills
+
+Multi-step procedures live in [`{{dir}}/`]({{dir}}/) and load only when used. Authoring rules are
+in [`.ai/rules/`](.ai/rules/README.md): six spec frontmatter fields and no more, a description that
+lists the phrases people actually say, and **every skill names its neighbours** — the failure past a
+dozen skills is the wrong one firing and running to completion.
+<!-- rungs:end skills -->

package/modules/skills/gates/skills.toml

@@ -0,0 +1,94 @@
+# Gate table for the `skills` module.
+#
+# Moved here from `gates/structural.toml`: what a SKILL.md may contain is knowledge about skills,
+# not a repo-agnostic structural fact. `gates` contributes the frontmatter-schema engine.
+
+# ── skills-spec-pure ──────────────────────────────────────────────────────────
+
+[[frontmatter_schema]]
+id       = "skills"
+scan     = ["{{dir}}/**/SKILL.md"]
+required = ["name", "description"]
+allowed  = ["name", "description", "license", "compatibility", "metadata", "allowed-tools"]
+# Extensions are legal only when the owning module opted in. The gate reads that manifest rather
+# than a repo-local allowlist, so the portability cost stays attached to the decision.
+extensions_allowed_from = "module.toml:skills.<name>.extensions"
+message = """
+`{file}` uses non-spec frontmatter key `{key}`. claude.ai uploads and the Skills API reject unknown
+keys with a hard error rather than ignoring them. If this is deliberate, opt in from the owning
+module's manifest, where the portability cost is recorded next to the choice.
+"""
+
+# ── skills-description-routes ─────────────────────────────────────────────────
+#
+# Structure, not quality. A gate cannot judge whether a description is *good*; it can tell that it
+# is a single clause with no trigger vocabulary, which is the shape that never fires.
+
+[[frontmatter_schema.field_shape]]
+field     = "description"
+min_words = 20
+requires_any = ["Use when", "Use for", "Use whenever", "Trigger"]
+message   = """
+`{file}`'s description does not say when to use it. At startup an agent loads only the name and
+description, so this is the entire routing surface — lead with the use case and list the phrases
+people actually say.
+"""
+
+# ── skills-names-neighbours ───────────────────────────────────────────────────
+#
+# Only fires past a threshold: in a repo with three skills there is nothing to disambiguate, and
+# demanding cross-references there is the checklist-as-noise failure.
+
+[cross_reference]
+scan            = ["{{dir}}/**/SKILL.md"]
+field           = "description"
+min_skills      = 6
+requires_mention_of_peer = true
+exempt_marker   = "no-neighbours-ok:"     # ignored unless it states a reason
+message = """
+`{file}` names no neighbouring skill. With {count} skills in this repo, the failure mode is no
+longer "no skill fires" but "a plausible-but-wrong skill fires and runs to completion". Name the
+adjacent skills and the boundary, in one clause each.
+"""
+
+# ── self-tests ────────────────────────────────────────────────────────────────
+
+[[self_test]]
+gate    = "skills-spec-pure"
+expect  = "fail"
+fixture = { frontmatter = { name = "x", description = "d", "argument-hint" = "y" }, opted_in = [] }
+
+[[self_test]]
+gate    = "skills-spec-pure"
+expect  = "pass"
+fixture = { frontmatter = { name = "x", description = "d", "disable-model-invocation" = true }, opted_in = ["disable-model-invocation"] }
+
+[[self_test]]
+gate    = "skills-spec-pure"
+expect  = "fail"
+fixture = { frontmatter = { name = "x", description = "d", "disable-model-invocation" = true }, opted_in = [] }
+
+[[self_test]]
+gate    = "skills-description-routes"
+expect  = "fail"
+fixture = { description = "Executes the release process." }
+
+[[self_test]]
+gate    = "skills-description-routes"
+expect  = "pass"
+fixture = { description = "Cut, tag and ship a release from the active candidate. Use when asked to cut the release, tag a version, hotfix production, or roll back a deploy." }
+
+[[self_test]]
+gate    = "skills-names-neighbours"
+expect  = "pass"
+fixture = { skill_count = 3, mentions_peer = false }
+
+[[self_test]]
+gate    = "skills-names-neighbours"
+expect  = "fail"
+fixture = { skill_count = 9, mentions_peer = false }
+
+[[self_test]]
+gate    = "skills-names-neighbours"
+expect  = "pass"
+fixture = { skill_count = 9, mentions_peer = false, exempt = "no-neighbours-ok: the only skill touching deployment" }

package/modules/skills/module.toml

@@ -0,0 +1,89 @@
+[module]
+name    = "skills"
+version = "1.0.0"
+rung    = 2
+summary = "Skill-authoring discipline and the gates that hold it: spec-pure frontmatter, descriptions that route, neighbours named, and output that lands somewhere."
+
+[requires]
+modules = ["instructions"]
+
+[conflicts]
+modules = []
+
+# This is not "the ability to have skills" — every module ships skills through
+# its own skills/ directory. This module ships the discipline for writing good
+# ones, and it is where the SKILL.md frontmatter schema lives, because knowing
+# what a skill may contain is knowledge about skills rather than a repo-agnostic
+# structural fact.
+
+[params.dir]
+description = """
+Where skills live. Resolved from the harness set (ADR-0001): `.claude/skills/` reaches Claude Code,
+Copilot and Cursor today; `.agents/skills/` is the vendor-neutral direction and is not read by
+Claude Code.
+"""
+default     = ".claude/skills"
+allowed     = [".claude/skills", ".agents/skills"]
+consumed_by = "render"
+
+[[gates]]
+id     = "skills-spec-pure"
+kind   = "declared"
+engine = "frontmatter-schema"
+table  = "gates/skills.toml"
+tier   = "fast"
+why    = """
+The Agent Skills spec allows six frontmatter fields. Anything else is a harness extension, and
+claude.ai uploads and the Skills API reject unknown keys with a hard error rather than ignoring
+them. An extension must be opted into in the owning module's manifest, where its portability cost
+is stated at the point of the choice.
+"""
+
+[[gates]]
+id     = "skills-description-routes"
+kind   = "declared"
+engine = "frontmatter-schema"
+table  = "gates/skills.toml"
+tier   = "fast"
+why    = """
+A description is the entire routing surface — at startup an agent loads only the name and
+description, so a vague one is the single most common reason a skill never fires. It has to name
+what the skill does and the phrases people actually say.
+"""
+
+[[gates]]
+id     = "skills-names-neighbours"
+kind   = "declared"
+engine = "cross-reference"
+table  = "gates/skills.toml"
+tier   = "fast"
+why    = """
+Past about a dozen skills with overlapping vocabulary the failure stops being "no skill fires" and
+becomes "a plausible-but-wrong skill fires and runs to completion". Every skill naming its
+neighbours makes each one a correction surface.
+"""
+
+[detect]
+paths   = [".claude/skills/**/SKILL.md", ".agents/skills/**/SKILL.md", ".github/prompts/*.prompt.md", ".ai/prompts/*.md"]
+markers = ["rungs:begin skills"]
+
+[[detect.adopt_as]]
+kind = "prompt-library"
+paths = [".github/prompts/*.prompt.md", ".ai/prompts/*.md"]
+note = """
+A markdown prompt library is a skill set without an invocation surface. Adopting means proposing a
+conversion — frontmatter added, one directory per skill — and it is worth doing: the format is now
+an open standard, so the portability objection that justified staying with plain prompts is gone.
+`add` proposes; it never rewrites a prompt in place.
+"""
+
+[provenance]
+sources  = ["rift-forge", "axiom-mesh", "hexguard"]
+patterns = ["invocable-procedure", "skill-neighbours", "prompt-writes-artifact", "operating-skills", "prompt-index-routing"]
+incident = """
+axiom-mesh wrote 21 prompt playbooks, several with no equivalent anywhere else, and gave them no
+invocation surface at all — they must be found, opened and pasted. hexguard-templates shipped the
+best decision procedure in the corpus behind a placeholder table. rift-forge, at 13 skills, had to
+invent the neighbour-naming convention because descriptions alone had stopped disambiguating
+/curate-mechanic from /curate-champion from /patch-ingest.
+"""

package/modules/skills/rules/skill-authoring.md

@@ -0,0 +1,71 @@
+---
+description: >-
+  How to write a skill that fires when it should, does not fire when it should not, and leaves
+  something behind. Loads when creating or editing any SKILL.md.
+paths:
+  - "{{dir}}/**/SKILL.md"
+enforcement: gated
+---
+
+# Writing a skill
+
+## What earns a skill
+
+A **multi-step procedure with a beginning and an end**. Not a fact — that is the entry document.
+Not a rule about a surface — that is a path-scoped rule. A skill's body loads only when it is used,
+so long reference material costs nothing until needed; a fact that belongs in every session costs
+the full context every session and belongs elsewhere.
+
+## Frontmatter: six fields, and that is the list
+
+`name` · `description` · `license` · `compatibility` · `metadata` · `allowed-tools`.
+
+Anything else is a harness extension. claude.ai uploads and the Skills API **reject** unknown keys
+with a hard error rather than ignoring them, so an extension is opted into in the owning module's
+manifest, where the cost is stated at the point of the choice — not added here quietly.
+
+The two that matter:
+
+- **`disable-model-invocation: true`** for anything with side effects — releases, deploys, sends,
+  merges. You do not want a model deciding that now is the moment to ship.
+- **`user-invocable: false`** for background knowledge that is not an action anyone would type.
+
+## The description is the whole routing surface
+
+At startup an agent loads **only the name and description**. A vague description is the single most
+common reason a skill never fires.
+
+Write it in the third person. Lead with the use case, then **list the phrases people actually
+say** — the exact words, not a paraphrase of the capability.
+
+> *Execute a backlog work item end to end… Use when asked to "work on / tackle / start / ship
+> WI-###", to pick up the next item, or to work an epic's sub-items.*
+
+## Name your neighbours
+
+**Every skill names the adjacent skills and the boundary between them**, in the description, in one
+clause each.
+
+The failure this fixes is not "no skill fires". It is **a plausible-but-wrong skill firing and
+running to completion** — which is worse, because it produces confident output against the wrong
+procedure. Naming neighbours makes every skill a correction surface:
+
+> *One mechanic across many subjects is /curate-mechanic; a whole new dataset is /patch-ingest;
+> this skill is one subject, whole kit.*
+
+## Land something durable
+
+A skill that only produces conversation evaporates. **Say in the body where the output goes** — a
+register row, a document at a known path, a status field. This is what makes a skill set compound
+instead of being re-derived every session.
+
+## Write standing instructions, not one-time steps
+
+The rendered body enters the conversation once and stays for the session; it is not re-read on
+later turns. Guidance that should apply throughout a task must read as a standing rule, not as
+step 4.
+
+## Say what the skill cannot do
+
+Near the end, briefly. The limits are what stop it being used for the adjacent problem it almost
+fits — which is the same failure as the wrong skill firing, arriving one step later.

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

@@ -0,0 +1,63 @@
+**Authoritative for:** spec conventions: ids, per-story status, the mandatory scope section, and how to propose new cross-cutting scope.
+**Not authoritative for:** the behaviour of any surface, which each spec owns, and what is currently being built, which is the backlog.
+
+# Specs
+
+What each surface is supposed to do. **Specs describe behaviour; they do not track work** — if you
+need to know what is happening right now, that is the backlog, not here.
+
+## Index
+
+<!-- rungs:begin specs-index -->
+<!-- Generated by `rungs render`. -->
+
+| Spec | Scope | Status | File |
+| --- | --- | --- | --- |
+| — | | | |
+
+<!-- rungs:end specs-index -->
+
+## Conventions
+
+- **Frontmatter on every spec:** `id`, `type: spec`, `scope`, `status`, `created`, `updated`.
+- **Stable ids** per feature (`{{feature_format}}`) and per story (`{{story_format}}`). Cite these
+  from commits, pull requests and work items so work traces back to the spec that justified it.
+- **Status is per feature and story, not per file:** ✅ implemented · 🟡 partial · ⬜ planned.
+  Fine-grained integration detail belongs in the linked plan or work item; the spec only has to be
+  accurate at the feature level.
+- **The Scope section is mandatory**, and its out-of-scope half is the point: it is what stops an
+  agent silently expanding a surface while implementing an unrelated story.
+- **One file per surface.** Split into `spec.md` + `stories/` only past ~{{split_lines}} lines —
+  do not pre-split. Structure created ahead of content is structure nobody fills.
+
+## Demo is not done
+
+An endpoint, screen or flow that exists to **showcase** a capability in isolation is 🟡 with an
+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.
+
+## Proposing new cross-cutting scope
+
+Written down so a fresh contributor does not have to reverse-engineer it from examples:
+
+1. **Find the surface that owns it.** If two surfaces both plausibly own it, that is the thing to
+   resolve first — not by picking one, but by naming the boundary.
+2. **Claim the next feature id** under that surface's prefix.
+3. **State the mechanism once**, in the owning spec, and have other specs reference it. A
+   mechanism described in two specs will diverge, and the second copy always reads as authoritative
+   to whoever finds it first.
+4. **Name a reference consumer.** A cross-cutting feature with no consumer is a design, not a
+   requirement.
+5. **Fill Non-goals and Open questions.** An empty Open questions section on a new proposal is
+   almost always untrue.
+
+## Status legend
+
+| | |
+| --- | --- |
+| ✅ | Implemented and integrated. Names the commit, pull request or work item that closed it |
+| 🟡 | Partial. **Carries a note saying what is missing** — a bare 🟡 is a guess |
+| ⬜ | Planned. Specified, not built |

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

@@ -0,0 +1,62 @@
+---
+id: <PREFIX>
+type: spec
+scope: <what surface this covers>
+status: draft          # draft | stable | superseded
+created: YYYY-MM-DD
+updated: YYYY-MM-DD
+---
+
+# <Surface> — specification
+
+## Purpose
+
+What this surface is for, in two or three sentences. The property that must not break.
+
+## Scope
+
+**In scope**
+
+-
+
+**Out of scope**
+
+- **Required — answer, do not delete.** What this surface explicitly does *not* cover, and where
+  that lives instead if it lives anywhere.
+>
+> This half is why the section is mandatory. Without it, "the spec did not say I could not" is a
+> defensible reading, and surfaces grow sideways during unrelated work.
+
+## Reference implementation
+
+<!-- The directory that demonstrates the correct pattern. Cheaper than prose and it cannot drift
+     from the code, because it *is* the code. -->
+
+## Features
+
+### <PREFIX>-F01 — <name>
+
+**Status:** ⬜
+
+<What it does. The mechanism, stated once — other specs reference this rather than restating it.>
+
+#### Stories
+
+| Id | Story | Status | Closed by |
+| --- | --- | --- | --- |
+| `<PREFIX>-US-001` | As a …, I can … | ⬜ | |
+
+**Acceptance criteria**
+
+- Checkable statements. "Given X, the endpoint returns 422 with a typed error", not "handles
+  errors properly".
+
+## Non-goals
+
+Things a reader might reasonably expect here and will not find, **with the reason**. A non-goal
+without a reason reads as an oversight and gets proposed again.
+
+## Open questions
+
+Unresolved, with who or what would resolve them. An empty section on a new spec is almost always
+untrue — say "none known" deliberately if you mean it.

package/modules/specs/fragments/AGENTS.md

@@ -0,0 +1,8 @@
+<!-- rungs:begin specs@1.0.0 -->
+## Specs
+
+Behaviour is specified in [`{{path}}/`]({{path}}/README.md) with stable feature and story ids —
+cite them from commits and work items. Specs say what is *in scope*; they do not track what is
+happening. **Demo is not done**: a showcase is 🟡 with a note, never ✅, and a ✅ story must name
+what closed it.
+<!-- rungs:end specs -->

package/modules/specs/gates/specs.toml

@@ -0,0 +1,119 @@
+# Gate table for the `specs` module.
+
+# ── specs-status-evidence ─────────────────────────────────────────────────────
+#
+# The "demo is not done" gate. A story claiming completion must name what closed it; a partial
+# story must say what is missing. Presence, never quality — a gate cannot judge whether the named
+# commit actually implemented the story, and one that tried would be confidently wrong.
+
+[register_schema]
+scan          = ["{{path}}/**/*.md"]
+table_columns = ["Id", "Story", "Status", "Closed by"]
+enum          = { Status = ["✅", "🟡", "⬜"] }
+
+[[register_schema.conditional]]
+when      = { Status = "✅" }
+non_empty = ["Closed by"]
+message   = """
+Story {id} is marked ✅ with nothing in `Closed by`. A spec that overclaims integration is read as
+verified — by the next contributor, by a plan citing it, and by an agent deciding the story is
+already handled. Name the commit, pull request or work item, or mark it 🟡 with what is missing.
+"""
+
+[[register_schema.conditional]]
+when      = { Status = "🟡" }
+requires_note = true
+message   = "Story {id} is 🟡 with no note. A bare partial is a guess; say what is missing."
+
+# ── specs-scope-section ───────────────────────────────────────────────────────
+
+[sections]
+scan      = ["{{path}}/**/*.md"]
+exclude   = ["{{path}}/README.md", "{{path}}/TEMPLATE.md"]
+required  = ["Purpose", "Scope"]
+non_empty = true
+# The out-of-scope half specifically, not just the heading.
+required_subsections = { Scope = ["Out of scope"] }
+message   = """
+{file} has no non-empty `Out of scope`. Without it, "the spec did not say I could not" is a
+defensible reading, and the surface grows sideways during unrelated work.
+"""
+
+# ── specs-ids-unique ──────────────────────────────────────────────────────────
+
+[kinds.feature]
+format  = "[A-Z]{2,8}-F\\d{2}"
+sources = ["{{path}}/**/*.md"]
+
+[kinds.story]
+format  = "[A-Z]{2,8}-US-\\d{1,4}"
+sources = ["{{path}}/**/*.md"]
+
+[citations]
+roots      = ["docs", ".ai", "AGENTS.md"]
+extensions = [".md"]
+
+# ── specs-split-threshold ─────────────────────────────────────────────────────
+
+[file_budget]
+scan      = ["{{path}}/**/*.md"]
+exclude   = ["{{path}}/README.md"]
+max_lines = {{split_lines}}
+warn_at   = 0.85
+message   = """
+{file} is past {{split_lines}} lines. Split it into spec.md + stories/ — a spec nobody reads to
+the end is one whose later sections collect unverified claims. Do not pre-split anything else.
+"""
+
+# ── self-tests ────────────────────────────────────────────────────────────────
+
+[[self_test]]
+gate    = "specs-status-evidence"
+expect  = "fail"
+fixture = { row = { Id = "X-US-001", Status = "✅", "Closed by" = "" } }
+
+[[self_test]]
+gate    = "specs-status-evidence"
+expect  = "pass"
+fixture = { row = { Id = "X-US-001", Status = "✅", "Closed by" = "WI-042" } }
+
+[[self_test]]
+gate    = "specs-status-evidence"
+expect  = "fail"
+fixture = { row = { Id = "X-US-002", Status = "🟡" }, note = "" }
+
+[[self_test]]
+gate    = "specs-scope-section"
+expect  = "fail"
+fixture = { sections = ["Purpose", "Scope"], subsections = { Scope = ["In scope"] } }
+
+[[self_test]]
+gate    = "specs-scope-section"
+expect  = "pass"
+fixture = { sections = ["Purpose", "Scope"], subsections = { Scope = ["In scope", "Out of scope"] } }
+
+[[self_test]]
+gate    = "specs-split-threshold"
+expect  = "fail"
+fixture = { file = "{{path}}/a/spec.md", lines = 900 }
+
+[[self_test]]
+gate    = "specs-split-threshold"
+expect  = "pass"
+fixture = { file = "{{path}}/a/spec.md", lines = 400 }
+
+# ── specs-ids-unique self-tests ───────────────────────────────────────────────
+#
+# Story ids are cited from commits, plans and work items, so a duplicate makes
+# every one of those citations ambiguous — and the citation still resolves,
+# which is why this is checked rather than left to be noticed.
+
+[[self_test]]
+gate    = "specs-ids-unique"
+expect  = "fail"
+fixture = { stories = ["FOUND-US-001", "FOUND-US-001"] }
+
+[[self_test]]
+gate    = "specs-ids-unique"
+expect  = "pass"
+fixture = { stories = ["FOUND-US-001", "AUTH-US-001"] }