@rungs/cli 0.1.0

package/modules/concurrency/gates/concurrency.toml

@@ -0,0 +1,54 @@
+# Gate table for the `concurrency` module.
+
+# ── concurrency-no-integration-checkout ───────────────────────────────────────
+
+[git_state]
+refuse_checked_out = ["{{integration_branch}}"]
+scope              = "all-worktrees"
+message = """
+`{{integration_branch}}` is checked out in {worktree}. Nothing should hold it: `rungs land` runs
+from wherever you are, verifies on a scratch ref, and advances the branch with a compare-and-swap.
+Holding it checked out blocks every other session and does not prevent concurrent landing anyway —
+switching to the scratch ref releases it mid-run, and two land processes have been measured running
+at once under exactly that design.
+"""
+
+# ── concurrency-generated-not-text-merged ─────────────────────────────────────
+#
+# Two failure modes, and the second is the quiet one: drivers declared in .gitattributes are inert
+# until installed, so a fresh clone silently gets git's default merge on files that must never be
+# text-merged.
+
+[merge_driver_check]
+attributes_file = ".gitattributes"
+required_drivers = ["rungs-ledger", "rungs-generated"]
+verify_installed = true
+install_command  = "rungs setup git"
+message = """
+The merge drivers named in .gitattributes are not installed in this clone, so they are inert and
+merges are falling back to git's default. For a generated artifact that default is a clean text
+merge of a file that is a fixed point of nothing — it surfaces later as a mismatch with an
+uninformative diff. Run `rungs setup git` once per clone.
+"""
+
+# ── self-tests ────────────────────────────────────────────────────────────────
+
+[[self_test]]
+gate    = "concurrency-no-integration-checkout"
+expect  = "fail"
+fixture = { worktrees = [{ branch = "{{integration_branch}}" }] }
+
+[[self_test]]
+gate    = "concurrency-no-integration-checkout"
+expect  = "pass"
+fixture = { worktrees = [{ branch = "feature/wi-001" }] }
+
+[[self_test]]
+gate    = "concurrency-generated-not-text-merged"
+expect  = "fail"
+fixture = { declared = ["rungs-ledger", "rungs-generated"], installed = [] }
+
+[[self_test]]
+gate    = "concurrency-generated-not-text-merged"
+expect  = "pass"
+fixture = { declared = ["rungs-ledger", "rungs-generated"], installed = ["rungs-ledger", "rungs-generated"] }

package/modules/concurrency/module.toml

@@ -0,0 +1,113 @@
+[module]
+name    = "concurrency"
+version = "1.0.0"
+rung    = 5
+summary = "Many sessions on one integration branch: a verified base to cut from, attributed failures, a land protocol that cannot redden the branch, and merge drivers per conflict class."
+
+[requires]
+modules = ["backlog", "gates", "ci"]
+
+[conflicts]
+modules = []
+
+# ── THRESHOLD ─────────────────────────────────────────────────────────────────
+#
+# `add` states this and requires explicit confirmation:
+#
+#   Below roughly five concurrent sessions on one integration branch, every
+#   mechanism here is pure overhead. It is a real tooling surface with its own
+#   failure modes, and it earns its cost only when sessions genuinely cannot see
+#   each other's work.
+#
+# Selling this to a rung-1 repo is the most likely way this tool does harm.
+
+[threshold]
+metric  = "concurrent sessions on one integration branch"
+minimum = 5
+confirm = true
+
+[params.integration_branch]
+description = "The shared branch work lands on"
+default     = "main"
+
+[params.green_prefix]
+description = """
+Ref marking the last merge that was actually verified. Branches are cut from this rather than from
+the tip, so a session does not start on top of an unverified merge.
+"""
+default     = "green/"
+
+[params.integ_prefix]
+description = "Scratch ref a merge is verified on before the integration branch moves"
+default     = "integ/"
+
+[[gates]]
+id     = "concurrency-no-integration-checkout"
+kind   = "declared"
+engine = "git-state"
+table  = "gates/concurrency.toml"
+tier   = "fast"
+why    = """
+Recorded as a correction, not a preference. The first design held the integration branch checked
+out for the whole verification and called that single-writer. It was both worse than useless: it
+blocked every other session — on one measured day every session in the repo sat in standby behind
+one land — and it did not prevent concurrent landing anyway, because switching to the scratch ref
+releases the branch mid-run. Two land processes were measured running at once.
+"""
+
+[[gates]]
+id     = "concurrency-generated-not-text-merged"
+kind   = "declared"
+engine = "merge-driver-check"
+table  = "gates/concurrency.toml"
+tier   = "fast"
+why    = """
+Two branches that each regenerated an artifact produce hunks git interleaves cleanly into something
+neither pipeline would emit. The failure surfaces later as a digest mismatch with an uninformative
+diff. The driver refuses and prints the regenerate command instead.
+"""
+
+[detect]
+# `.gitattributes` was in this list and is a near-universal file — it reported
+# axiom-mesh, a repo with 29 branches and no land protocol at all, as having
+# concurrency tooling. A signature that matches nearly every repo is not a
+# signature. What is actually distinctive is a declared merge driver.
+paths        = [".git/rungs-land.lock"]
+# A custom merge driver declaration is what actually discriminates: 21 of them
+# in the one repo of the four that runs a land protocol, and none in the other
+# three. The file itself is near-universal, so it is scanned rather than counted.
+marker_paths = [".gitattributes"]
+markers      = ["rungs:begin concurrency", "merge="]
+
+[[detect.paradigm]]
+id      = "trunk-based"
+compare = "docs/research/synthesis.md#35-concurrency-model"
+note    = """
+Few branches and direct merges is not a lesser model — it is the right one below the threshold, and
+two of the four source repos ran hundreds of commits that way. Report the branch and worktree
+counts and let the operator decide; never install this because the mechanism is interesting.
+"""
+
+[provenance]
+sources  = ["rift-forge"]
+patterns = [
+  "green-ref",
+  "failure-attribution",
+  "land-protocol",
+  "lock-not-checkout",
+  "no-pre-land-full-verify",
+  "preflight",
+  "conflict-classes",
+  "regenerate-never-merge",
+  "id-claiming",
+  "worktree-lifecycle",
+  "ci-at-land-time",
+]
+incident = """
+rift-forge reached 401 branches and 51 live worktrees with many sessions branching off one
+candidate and unable to see each other. This module ships its corrections included, because both
+were expensive: the checkout-based lock that blocked every session and did not work, and the
+pre-land full verify that widened the window the merge then conflicted in — three of five land
+attempts refused in one measured session, every one after a 4–12 minute pre-verify, every one on
+the same four generated artifacts.
+"""

package/modules/design-sync/fragments/AGENTS.md

@@ -0,0 +1,8 @@
+<!-- rungs:begin design-sync@1.0.0 -->
+## Design
+
+The design authority is external. Pull it with **`/design-pull`** into `{{mirror}}/` — generated,
+never hand-edited — and decide what the pull means with **`/design-align`**. It owns layout and
+visual language; it does not own this repo's technical constraints, and a conflict is a request to
+send upstream. **Every delta is routed; there is no fourth option.**
+<!-- rungs:end design-sync -->

package/modules/design-sync/gates/design.toml

@@ -0,0 +1,70 @@
+# Gate table for the `design-sync` module.
+
+# ── design-deltas-routed ──────────────────────────────────────────────────────
+#
+# Reads the pull record and requires every delta to name a route. The gate cannot judge whether a
+# route is the right one — only that a decision was made and written down.
+
+[register_schema]
+file          = "{{mirror}}/PULL-RECORD.md"
+table         = "Deltas"
+required_cols = ["Delta", "Route", "Where"]
+enum          = { Route = ["implement", "defer", "upstream", "accept-as-is"] }
+non_empty     = ["Where"]
+message       = """
+Delta "{delta}" has no route. Every difference is work we have decided to do, work we have decided
+to defer, a disagreement to send upstream, or a mirror that is stale. A fifth state — noticed and
+unrouted — is how the design and the implementation drift while both sides believe they are aligned.
+"""
+
+# A deferred delta must carry a revisit trigger. "Later" is not a route.
+[[register_schema.conditional]]
+when      = { Route = "defer" }
+non_empty = ["Where"]
+min_words = { Where = 4 }
+message   = "Delta \"{delta}\" is deferred with no revisit trigger. A deferral with no trigger is a decision to never do it, taken without saying so."
+
+# ── design-mirror-not-edited ──────────────────────────────────────────────────
+
+[[render_freshness]]
+id       = "design-mirror"
+targets  = ["{{mirror}}/**"]
+generated_by = "rungs design pull"
+detect   = "local-modification"
+message  = """
+{file} in the mirror has been edited locally. The mirror is generated and the next pull destroys
+this — and until then it is a fact about the design system that the design system does not know.
+Route it instead: a work item if we should change, an upstream request if they should.
+"""
+
+# ── self-tests ────────────────────────────────────────────────────────────────
+
+[[self_test]]
+gate    = "design-deltas-routed"
+expect  = "fail"
+fixture = { row = { Delta = "spacing scale changed", Route = "", Where = "" } }
+
+[[self_test]]
+gate    = "design-deltas-routed"
+expect  = "pass"
+fixture = { row = { Delta = "spacing scale changed", Route = "implement", Where = "WI-051" } }
+
+[[self_test]]
+gate    = "design-deltas-routed"
+expect  = "fail"
+fixture = { row = { Delta = "new chart component", Route = "defer", Where = "later" } }
+
+[[self_test]]
+gate    = "design-deltas-routed"
+expect  = "pass"
+fixture = { row = { Delta = "new chart component", Route = "defer", Where = "revisit when analytics ships" } }
+
+[[self_test]]
+gate    = "design-mirror-not-edited"
+expect  = "fail"
+fixture = { modified = ["{{mirror}}/tokens.json"] }
+
+[[self_test]]
+gate    = "design-mirror-not-edited"
+expect  = "pass"
+fixture = { modified = [] }

package/modules/design-sync/module.toml

@@ -0,0 +1,82 @@
+[module]
+name    = "design-sync"
+version = "1.0.0"
+rung    = 3
+summary = "An external design authority pulled into a local mirror, with every delta routed to a work item, a future item, or an upstream change request — never silent divergence."
+
+[requires]
+modules = ["backlog", "skills"]
+
+[conflicts]
+modules = []
+
+[params.source]
+description = "The upstream design authority — a URL, a project id, or a repository."
+default     = ""
+required    = true
+consumed_by = "design-pull"
+# Behavioural: it tells the pull where to fetch from and never appears in a
+# template. Deliberately not written into the skill body — the skill would then
+# carry a URL that changes independently of it.
+
+[params.mirror]
+description = "Local mirror of the pulled design system. Generated; never hand-edited."
+default     = "design-system"
+
+[params.request_path]
+description = "Where upstream change requests are drafted before being sent"
+default     = "docs/design-requests"
+
+[[gates]]
+id     = "design-deltas-routed"
+kind   = "declared"
+engine = "register-schema"
+table  = "gates/design.toml"
+tier   = "fast"
+why    = """
+Every difference between the mirror and the implementation is either work we have decided to do,
+work we have decided to defer, or a disagreement to send upstream. A fourth category — noticed and
+not routed — is how a design system and its implementation drift apart while both sides believe
+they are aligned.
+"""
+
+[[gates]]
+id     = "design-mirror-not-edited"
+kind   = "declared"
+engine = "render-freshness"
+table  = "gates/design.toml"
+tier   = "fast"
+why    = "A hand-edit in the mirror is a local change that the next pull silently destroys, and until then it is a fact about the design system that the design system does not know."
+
+[skills.design-pull]
+# Read-only against upstream. Safe for a model to run unprompted.
+
+[skills.design-align]
+# No extensions: it writes backlog items and drafts requests, both of which
+# are reversible and reviewable. It does not send anything upstream.
+
+[detect]
+paths   = ["design-system/**", "docs/**/design-tokens*", ".design/**"]
+markers = ["rungs:begin design-sync"]
+
+[[detect.paradigm]]
+id      = "design-in-repo"
+paths   = ["**/tokens.{json,css,scss}", "**/theme.{ts,css}"]
+compare = "docs/research/synthesis.md#2-convergences--where-independent-repos-agreed"
+note    = """
+A design system authored *in* this repo is not an external authority and does not need syncing —
+it needs the ordinary rules for shared code. This module is for the case where somebody else owns
+the design and disagreements have to travel back to them. Report and stop.
+"""
+
+[provenance]
+sources  = ["rift-forge", "hexguard-templates"]
+patterns = ["external-authority-precedence", "two-way-design-sync"]
+incident = """
+hexguard-templates states the precedence rule that makes an external authority workable: the design
+project is "layout/visual guidance, not a functional spec, and its output must still satisfy this
+repo's technical constraints". Without a stated precedence, an external source either gets ignored
+or overrides constraints it knows nothing about. rift-forge industrialised the same integration into
+a down-pull plus an alignment pass whose rule is that every delta is routed somewhere — never
+silent divergence, and never forced convergence either.
+"""

package/modules/design-sync/skills/design-align/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: design-align
+description: >-
+  Reconcile the pulled design mirror against what is actually implemented, routing every difference
+  to a work item, a deferred item, or an upstream change request. Use after a design pull, or when
+  asked to "align with the design", "does this match the mock", "triage the design deltas", or
+  "what does the new design mean for us". Pulling the mirror down is /design-pull; this decides
+  what the pull means.
+---
+
+# Align with the design
+
+**Every delta is routed. There is no fourth option.**
+
+A difference that is noticed and not routed is how a design system and its implementation drift
+apart while both sides believe they are aligned — and the drift is discovered by a user, or by
+someone rebuilding a screen and finding two sources of truth.
+
+## Precedence, before anything
+
+The design authority owns **layout, visual language, spacing, colour, motion intent**. It does not
+own this repo's technical constraints, accessibility floor, or component boundaries. A design that
+requires breaking one of those is a **disagreement to send upstream**, not an instruction.
+
+State which side owns a contested decision *before* deciding the delta — most arguments here are
+really arguments about ownership.
+
+## For each delta, choose exactly one
+
+| Route | When | What you write |
+| --- | --- | --- |
+| **Implement now** | It is in scope, and the current phase covers it | A work item, with the delta as its rationale |
+| **Defer** | Real, agreed, but belongs to a later phase | A work item marked deferred, **with the revisit trigger** — not a vague "later" |
+| **Send upstream** | The design conflicts with a constraint it does not know about, or is internally inconsistent | A draft in `{{request_path}}`, stating the constraint and what we need |
+| **Accept as-is** | The implementation is right and the mirror is stale | Nothing local — but say so in the pull's record, or the same delta reappears next pull |
+
+## What makes this fail
+
+- **Batching deltas into one "design alignment" item.** They have different owners, different
+  phases, and different answers. One item hides all of that and gets deferred as a lump.
+- **Implementing ahead of the roadmap** because the design shows it. A design is not a schedule.
+- **Silently adjusting the mirror** to match what is built. The mirror is generated; the next pull
+  destroys the edit, and until then it is a fact about the design that the designer does not know.
+- **Treating a stale mirror as authoritative.** Check when the pull happened before trusting a
+  delta.
+
+## Finish
+
+Report the counts per route, and **how many deltas were examined**. A pass that found nothing and a
+pass that compared nothing produce the same output, and only one of them means the design is
+implemented.

package/modules/design-sync/skills/design-pull/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: design-pull
+description: >-
+  Pull the design system down from the upstream authority into the local mirror, and record what
+  changed since the last pull. Use when asked to "pull the design", "sync the design system", "get
+  the latest tokens/components", or before starting UI work that should match a current design.
+  Down-sync only — it never pushes local changes upstream. Deciding what the pull means is
+  /design-align.
+---
+
+# Pull the design system
+
+**Down-sync only.** This skill never sends anything upstream; that is `/design-align`'s change
+request, drafted for a person to send.
+
+## 1. Record where you are starting
+
+Note the mirror's current state before pulling — what came down last time and when. Without it,
+"what changed" degrades into "everything looks different", which is not a delta list.
+
+## 2. Pull into `{{mirror}}/`
+
+The mirror is **generated**. Anything hand-edited there is destroyed by this step, which is why
+`design-mirror-not-edited` exists — if it has fired, resolve that before pulling or the edit
+disappears along with whatever it was compensating for.
+
+## 3. Report what changed, in design terms
+
+Not a file diff. Group by what a person would recognise:
+
+- tokens added, changed, removed
+- components added, changed, removed
+- layout or spacing rules changed
+- anything **removed** — the most consequential category and the easiest to miss, because a removal
+  looks like nothing rather than like a change
+
+## 4. Say what you could not tell
+
+An upstream that reorganised its files produces a diff that looks like a rewrite. Say so rather
+than reporting hundreds of false deltas — an alignment pass fed noise gets abandoned, and the real
+deltas go with it.
+
+## 5. Stop
+
+**Do not implement anything.** Do not open work items. Do not adjust components to match. The pull
+establishes what upstream says; `/design-align` decides what that means here, against precedence
+rules and the current phase.
+
+Hand off with the delta list and the pull date. That date is what makes the next reader able to
+tell a live delta from a stale one.

package/modules/doc-authority/files/{{registry_path}}

@@ -0,0 +1,59 @@
+**Authoritative for:** which document owns which topic.
+**Not authoritative for:** the content of any topic listed below.
+
+# Document ownership
+
+The arbiter. **When a question arises about where something belongs, it is resolved here first,
+before any content is written.** If the answer is missing, add the row before writing.
+
+## The registry
+
+The third column is what makes this enforceable rather than aspirational: it converts "one source
+of truth" from a principle into a lookup, and it is what `rungs check` reads.
+
+| Topic | Owner | Must NOT appear in |
+| --- | --- | --- |
+| *(example)* Build and test commands | `AGENTS.md` | `README.md`, `docs/**` |
+| | | |
+
+<!-- Add a row before writing content whose home is unclear. A row costs a minute; a topic living
+     in two documents costs a divergence nobody notices until they disagree. -->
+
+## The rules this enforces
+
+**No fact is stated in two documents.** If a value, rule or contract already exists in its owning
+document, the second one references it with a link — never restates it, **not even as a summary.**
+
+**Paraphrase is not permitted.** This is the one people argue with, so it is worth being explicit:
+a paraphrase looks maintained while it decays. A summary that "just gives the gist" is a second
+statement of the fact, and when the original changes, the gist becomes wrong while still reading
+as deliberate.
+
+**Drift is a bug**, not untidiness. A document that paraphrases rather than references *will*
+diverge — the only question is when it is noticed and what was built on it in the meantime.
+
+**No redirect stubs.** A file that exists only to say "go elsewhere" gets cited, and the citation
+looks authoritative. Delete it and repoint the citers.
+
+**Review outbound links on every edit.** After editing, confirm the documents you link to still
+say what you are citing them for. This is the step that catches drift while it is cheap.
+
+## Scope headers
+
+Every document opens with both blocks, so a reader who opened the wrong file learns it in one line:
+
+```markdown
+**Authoritative for:** …
+**Not authoritative for:** …
+```
+
+The repository root `README.md` is exempt — it is a navigation page.
+
+**A stub may contain only scope headers and cross-references** until it is explicitly promoted.
+This is what stops a placeholder quietly accreting content it does not own.
+
+## When two documents both claim a topic
+
+Do not split the difference, and do not pick the better-written one. Decide which is the **owner**,
+move the content there, and leave a link. A topic owned by two documents is owned by neither, and
+the next reader will find whichever one search puts first.

package/modules/doc-authority/files/{{rules_path}}

@@ -0,0 +1,51 @@
+**Authoritative for:** which cross-cutting working rules exist, and which surfaces restate each one.
+**Not authoritative for:** why any rule is what it is — that lives in the rule's own authority document.
+
+# Working rules
+
+A **working rule** is how we do something: how an id is claimed, how a dataset is republished,
+which source outranks which. It is different from a domain fact in one specific way, and it is
+worse: a stale domain fact produces a number someone can check, while **a stale working rule
+produces someone confidently doing the retired thing, correctly, all day.**
+
+A working rule lives in more places than its authority:
+
+| Surface | What it holds | What keeps it true |
+| --- | --- | --- |
+| the **authority document** | the rule, and *why* — the only place the reasoning belongs | review |
+| the **always-on document** | the one-paragraph version every session reads | this registry's gate |
+| the **skills that execute it** | the step-by-step form, where it is actually met | this registry's gate |
+| the **tool that automates it** | the rule made mechanical, and its self-test | its own gate |
+
+## The registry
+
+Each rule is declared with the surfaces that restate it. A surface that **engages the topic** must
+carry the rule's current vocabulary and must not carry the retired instruction.
+
+| Rule | Authority | Surfaces that restate it | Retired wording |
+| --- | --- | --- | --- |
+| *(example)* Ids are claimed on your own branch | `docs/backlog/README.md` | `AGENTS.md`, `skills/work-item` | "claim on the integration branch" |
+| | | | |
+
+## Four rules about changing a rule
+
+1. **Fix the authority first, then the citers.** A citer corrected against a stale authority is a
+   second wrong statement, and the next reader cannot tell which one won.
+2. **A citation is not propagation.** *"See §3"* ages into a **false claim** the moment §3 changes
+   — and it reads as verified precisely because it names a source.
+3. **Declare the rule here** when it is cross-cutting, with its surfaces. That is what turns "we
+   should remember to update the skills" into a build failure. Adding a cross-cutting rule without
+   a row is how the next several get missed.
+4. **A tool that invalidates a generated artifact must say so in its own output.** The standing
+   rule: **a green check means "not yet regenerated", never "current".**
+
+## Exemptions
+
+Prose that *quotes* a retired rule to explain why it was retired is exempted by name and reason:
+
+```markdown
+<!-- working-rule-ok: <rule-id> — quotes the retired wording to explain the change -->
+```
+
+**The marker is ignored unless it states a reason.** An escape hatch nobody has to justify is not
+an escape hatch, it is an off switch. Never exempt by rewriting the history.

package/modules/doc-authority/fragments/AGENTS.md

@@ -0,0 +1,9 @@
+<!-- rungs:begin doc-authority@1.0.0 -->
+## Document ownership
+
+Before writing content whose home is unclear, resolve it in
+[`{{registry_path}}`]({{registry_path}}) — it is the arbiter, and its third column says where a
+topic must **not** appear. **No fact is stated in two documents, and paraphrase is not permitted**:
+a paraphrase looks maintained while it decays. Changing a cross-cutting working rule means updating
+every surface in [`{{rules_path}}`]({{rules_path}}) — **a citation is not propagation.**
+<!-- rungs:end doc-authority -->