@rungs/cli 0.1.0

package/modules/backlog/module.toml

@@ -0,0 +1,150 @@
+[module]
+name    = "backlog"
+version = "1.0.0"
+rung    = 1
+summary = "Work items with stable ids, an eight-status lifecycle, a board, and the three gates that keep the bookkeeping honest."
+
+[requires]
+modules = ["instructions"]
+
+[conflicts]
+modules = []
+
+# ── parameters ────────────────────────────────────────────────────────────────
+# Only things that substitute cleanly into prose and paths are parameters.
+# The eight-status lifecycle is deliberately NOT one: a status set cannot be
+# substituted into a table, a state diagram and a gate without a template
+# language, and ADR-0003 chose not to have one. A repo that wants different
+# statuses edits the file, and `add` records the divergence (ADR-0004 state 3).
+
+[params.id_prefix]
+description = "Prefix for work-item ids, e.g. WI-042"
+default     = "WI"
+pattern     = "^[A-Z]{1,6}$"
+
+[params.root]
+description = "Directory under docs/ that holds the backlog"
+default     = "backlog"
+
+[params.integration_branch]
+description = "Branch that item branches are cut from and merged back into"
+default     = "main"
+
+[params.branch_prefix]
+description = "Prefix for a feature item's branch"
+default     = "feature"
+
+# ── gates ─────────────────────────────────────────────────────────────────────
+# All three are `declared`: a CLI engine plus the table below. No script is
+# written into the repo (ADR-0002).
+
+[[gates]]
+id     = "backlog-ids"
+kind   = "declared"
+engine = "id-integrity"
+table  = "gates/ids.toml"
+tier   = "fast"
+why    = "An id claimed twice is two items the board shows as one."
+
+[[gates]]
+id     = "backlog-stale-blocker"
+kind   = "declared"
+engine = "id-integrity"
+table  = "gates/ids.toml"
+tier   = "fast"
+why    = """
+A document saying it is blocked on finished work reads as a live constraint, and the next session
+plans around a wall that came down months ago. rift-forge measured 95% of 474 rows naming a
+finished item as next owner, then found those routes quoted in a code comment as evidence.
+"""
+
+[[gates]]
+id     = "backlog-merged-status"
+kind   = "declared"
+engine = "git-status-reconcile"
+table  = "gates/ids.toml"
+tier   = "fast"
+why    = """
+An item whose branch is merged cannot still be on its way to review. Measured 2026-08-13 in
+rift-forge: 37 items sat at `review` with their code already landed, and one sat `in_progress`
+for eight days after its own merge.
+"""
+
+# ── skills ────────────────────────────────────────────────────────────────────
+# SKILL.md files stay restricted to the six Agent Skills spec fields (ADR-0001).
+# Claude Code extensions are opted into here, per skill, with the cost stated.
+
+[skills.work-item]
+extensions = { disable-model-invocation = true }
+extension_note = """
+`work-item` creates branches and merges. A model should not decide on its own that now is the
+moment. Opting in means this skill no longer packages for claude.ai uploads or the Skills API,
+which reject non-spec keys with a hard error; it remains portable to every skills-compatible CLI.
+"""
+
+[skills.backlog-summary]
+# No extensions. Read-only, and useful for a model to reach for unprompted.
+
+# ── detection (ADR-0004) ──────────────────────────────────────────────────────
+# Presence is decided by `paths` and `markers` only. Biased toward false
+# negatives: when uncertain, fail to match.
+
+[detect]
+paths = [
+  "docs/*/items/**/*.md",
+  "docs/*/BACKLOG.md",
+  "docs/*/TEMPLATE.md",
+  "docs/.ai/backlog/**/*.md",
+]
+markers = ["rungs:begin backlog"]
+
+# A different system serving the same function. Never auto-adopted; `add` prints
+# the comparison and stops (ADR-0004 state 5).
+[[detect.paradigm]]
+id      = "milestones"
+paths   = ["docs/**/milestones/index.md", ".ai/context/session.md"]
+compare = "docs/research/synthesis.md#33-unit-of-work"
+note    = """
+Milestones (`M##-T#`) suit long sequenced programmes; work items suit continuous flow. They can
+coexist — a milestone overlay sits on top of items. Three real options: adopt milestones as the
+unit and install only the missing gates, install items alongside, or skip.
+"""
+
+# Proposes a parameter once presence is already established. Never concludes
+# presence — hexguard-templates has 207 well-formed `FOUND-US-###` matches and
+# no backlog; they are spec story ids.
+[[detect.infer]]
+param   = "id_prefix"
+# The lookbehind is load-bearing and was added after a real false positive:
+# `\b([A-Z]{1,6})-\d` matches `US-110` inside `FOUND-US-110`, because `-` to `U`
+# is a word boundary. On hexguard-templates that proposed `US` — a spec story
+# id — as the backlog prefix, which is precisely the failure ADR-0004 was
+# written about, arriving through the inference path instead of the presence one.
+pattern = "(?<![A-Za-z0-9-])([A-Z]{1,6})-\\d{1,4}\\b"
+min     = 20
+scope   = ["docs/**/*.md"]
+exclude = ["docs/specs/**", "docs/decisions/**", "docs/adr/**"]
+# Encodings, hashes and standards share the id shape. On hexguard the top
+# proposal was `UTF` at 32 matches, from `UTF-8`.
+exclude_values = ["UTF", "SHA", "ISO", "RFC", "MD", "AES", "RSA", "HTTP", "IPV", "X"]
+
+# ── provenance (required, validated) ──────────────────────────────────────────
+
+[provenance]
+sources  = ["rift-forge", "axiom-mesh"]
+patterns = [
+  "work-item-lifecycle",
+  "item-template-required-fields",
+  "branch-per-item",
+  "planning-rides-trunk",
+  "scope-discipline",
+  "epics-and-subitems",
+  "bookkeeping-gates",
+]
+incident = """
+Two of the four source repos had no unit of work at all, and both show the same consequence:
+hexguard produced 268 audit reports that could not become anything, because no object existed for
+a finding to turn into; hexguard-templates cannot say what is in flight. rift-forge, which has the
+object, needed two gates to keep its status fields honest — 37 items were found claiming `review`
+with their code already on the integration branch.
+"""

package/modules/backlog/rules/work-items.md

@@ -0,0 +1,44 @@
+---
+description: >-
+  How to read and change a work item — required sections, status honesty, and the scope rule.
+  Loads when an agent touches the backlog.
+paths:
+  - "docs/{{root}}/**/*.md"
+enforcement: gated
+---
+
+# Working on a work item
+
+**Authority:** [`docs/{{root}}/README.md`](../../docs/{{root}}/README.md). This rule is the
+short form an agent meets while editing; the reasoning lives there.
+
+## Before changing an item
+
+- **Re-derive the state; do not quote the board.** A status line, a board row or a triage is
+  bookkeeping *about* the work, not the work. Check the artifact the claim is about — the branch,
+  the tests, the file — before acting on what a field says.
+- **The template's sections are required, not suggested.** `Out of scope` and
+  `Acceptance criteria` may be answered with an explicit "none, because…" but may not be left
+  blank or deleted. A blank one is an unfinished plan.
+
+## While executing
+
+- **Never scope-creep.** Work discovered mid-flight becomes a **new item**; a mere observation
+  becomes a **finding**. An item that grew a second purpose should have been two.
+- **Deviations from the plan go in `## Execution`, with the reason.** A plan that silently stopped
+  matching what was built is worse than no plan, because it reads as verified.
+
+## When it lands
+
+- **Move the status in the same change that merges the branch.** `backlog-merged-status` refuses a
+  merged branch sitting at a pre-review status — measured elsewhere at 37 items, one of them eight
+  days stale.
+- **Never write that something is blocked on finished work.** `backlog-stale-blocker` refuses it:
+  it reads as a live constraint and the next session plans around a wall that came down months ago.
+  Past tense ("was blocked on") is a record and is allowed.
+
+## Escape hatches
+
+Both gates take an exemption **that must state a reason** — `branch-merged-ok: <why>` and
+`owner-ok: <why>`. A marker with no reason is ignored: an escape hatch nobody has to justify is not
+an escape hatch, it is an off switch.

package/modules/backlog/skills/backlog-summary/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: backlog-summary
+description: >-
+  Summarize the backlog: open work items grouped by category, the highest-value items with the
+  reasoning, stale or contradictory bookkeeping, and workflow-health observations with concrete
+  suggestions. Use whenever asked to "summarize the backlog", "what's open", "backlog status /
+  report / health", "rank the backlog", "what should we do next", or for any prioritization of
+  open work — even when the word "backlog" is not used but the question is about what to build
+  next. Read-only: it reports, it never changes an item. Executing one item is /work-item.
+---
+
+# Summarize the backlog
+
+Read-only. **This skill never edits an item, a status, or the board.**
+
+## 1. Read from the current tip, not a copy
+
+Run against `{{integration_branch}}` as it is now. A worktree copy or a cached report goes stale,
+and a summary built on one is confidently wrong about what is open.
+
+## 2. Gather
+
+Read every file in `docs/{{root}}/items/`, plus `BACKLOG.md`. Do **not** trust the board's grouping
+— derive status from the item files and note any disagreement, which is itself a finding worth
+reporting.
+
+## 3. Report
+
+### Open work, by category
+
+Group by the natural categories of this repo (its subsystems, surfaces, or domains — not by
+status). For each: count, and the items with a one-line summary each.
+
+### Highest-value items, with the reasoning
+
+Rank the top few, and **state why each ranks where it does** — value, cost, what it unblocks, what
+it stops costing. A ranking without reasoning is an opinion wearing a number.
+
+### Bookkeeping that disagrees with reality
+
+Report, do not fix:
+
+- items whose `status` and merged branch disagree
+- items `in_progress` with no branch, or with a branch that no longer exists
+- documents claiming they wait on work that has finished
+- epics whose `children` links are not reciprocated
+
+### Workflow health
+
+Observations about the *process*, with a concrete suggestion each:
+
+- items sitting in one status for a long time
+- items whose acceptance criteria are blank while their status is past `planned`
+- how much work arrives as items versus as unrecorded changes
+- whether `items/` has outgrown readability and wants archiving
+
+## 4. What this cannot tell you
+
+State these limits in the output rather than leaving the reader to infer them:
+
+- it measures **what is recorded**, not what is happening — work done without an item is invisible
+- a ranking is a judgement, and the reasoning is there so it can be argued with
+- an empty result and an unread backlog produce the same summary, so say how many files were read
+
+A report that cannot fail loudly is not a measurement.

package/modules/backlog/skills/work-item/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: work-item
+description: >-
+  Execute a backlog work item ({{id_prefix}}-###) end to end through its lifecycle: claim or open
+  the item, branch, plan, implement, test, review, merge, and move the status. Use when asked to
+  "work on / tackle / start / do / ship {{id_prefix}}-###", to pick up the next item from the
+  backlog, or to work an epic's sub-items. Also use to open a new item from a request that turns
+  out to be real work rather than a quick fix. An out-of-scope observation is a finding, not an
+  item — that is /record-finding. Shipping a version is /cut-release. This skill is one item,
+  start to finish.
+---
+
+# Execute a work item
+
+**Authority:** [`docs/{{root}}/README.md`](../../../docs/{{root}}/README.md). Read it once per
+session before the first item; this skill is the execution form, not the reasoning.
+
+## 0. Establish the item
+
+- Given an id → open `docs/{{root}}/items/{{id_prefix}}-###-*.md`.
+- Given a request with no id → decide first **whether this is an item at all**: a one-line fix with
+  no design choice is just a change; an observation you are not acting on now is a **finding**. If
+  it is an item, claim the next id from the `NEXT-ID` marker in `BACKLOG.md` and **bump the marker
+  on your own branch**, then copy `TEMPLATE.md`.
+- Given "the next item" → read the board, but **re-derive before committing to it**. A board row is
+  bookkeeping about the work, not the work; scoping from a stale row is how work that is already
+  done gets started again.
+
+## 1. Check the status is real
+
+Before doing anything, confirm the item's `status` and `branch` agree with git. If the branch is
+merged and the status is pre-review, the work landed and the field lied — fix the field, say so in
+`## Execution`, and stop. That is the whole task.
+
+## 2. Plan, if it is not planned
+
+An `accepted` item needs its plan filled before code: **requirements · impacts · approach ·
+acceptance criteria · out of scope**. None may be blank.
+
+- Acceptance criteria must be **checkable**. "Works correctly" is not a criterion; "given X, the
+  endpoint returns 422 with a typed error" is.
+- `Out of scope` is required — answer it or write `nothing deferred`. It is the section that stops
+  an item quietly growing a second purpose.
+- A significant design choice gets an ADR. Link it; do not restate it here.
+
+Status → `planned`.
+
+## 3. Branch and execute
+
+```bash
+git switch -c {{branch_prefix}}/{{id_prefix}}-###-slug {{integration_branch}}
+```
+
+Status → `in_progress`.
+
+- **Follow the repo's engineering guides**, not this skill, for how the code should look.
+- **Work discovered mid-flight does not join this item.** A new item, or a finding. Record it and
+  carry on — do not widen the branch.
+- Deviations from the plan go in `## Execution` **with the reason**, as you make them. A plan that
+  silently stopped matching what was built reads as verified and is not.
+
+## 4. Test
+
+Run the narrowest validation that covers what you touched, then the repo's standard gate set:
+
+```bash
+rungs check
+```
+
+Existing tests are not weakened to make a change pass. If a test is genuinely wrong, that is its
+own item with its own reasoning.
+
+## 5. Review
+
+Walk **each** acceptance criterion and write what you checked in `## Review`. A criterion you
+cannot demonstrate is not met — leave it open and say so rather than marking the item done.
+
+Status → `review`.
+
+## 6. Land
+
+Merge into `{{integration_branch}}`, **move the status to `done` in the same change**, then delete
+the branch. In that order: the merged-status gate can only see items whose branch still exists, so
+deleting first costs you the check.
+
+Update the board: remove the row from **In progress**, and archive the item if the repo archives on
+completion.
+
+## When to stop and ask
+
+- The plan cannot be written because the requirement is ambiguous in a way that changes the work.
+- Execution reveals the approach is wrong — reopen the plan rather than improvising past it.
+- Acceptance criteria conflict with something already shipped.
+
+In each case, write what you found in the item first. The next session reads the item, not this
+conversation.

package/modules/ci/files/{{workflow_path}}

@@ -0,0 +1,43 @@
+# Gate run. Generated by `rungs`; the trigger block is regenerated from the `trigger` parameter.
+name: checks
+
+on:
+  # rungs:begin ci-triggers
+  push:
+    branches: ['**']
+  pull_request:
+  # rungs:end ci-triggers
+
+concurrency:
+  # One run per ref. A superseded run tells you about a tree nobody has any more.
+  group: checks-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  gates:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # Gates that compare against the merge base need history. Cheaper than
+          # discovering mid-run that a gate cannot see what it is attributing against.
+          fetch-depth: 0
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+
+      # Runs every gate in .ai/gates.toml — the same set, in the same order, as
+      # `rungs check` locally. A CI-only gate is one nobody can reproduce.
+      - name: Run gates
+        run: npx rungs check --tier full --reporter github
+
+  # Add a matrix job per package here rather than a workflow per package.
+  # A checklist step that creates a file creates N files:
+  #
+  #   strategy:
+  #     matrix:
+  #       package: [a, b, c]
+  #
+  # `rungs check` reports the workflow count and fails past the threshold in
+  # .ai/gates.toml, for exactly that reason.

package/modules/ci/gates/ci.toml

@@ -0,0 +1,44 @@
+# Gate table for the `ci` module.
+
+# ── ci-workflow-proliferation ─────────────────────────────────────────────────
+#
+# Counts near-identical workflow files. Similarity is structural — job names, step commands, and
+# `uses:` refs — not textual, because near-identical files differ exactly in the package name.
+
+[file_population]
+scan            = [".github/workflows/*.yml", ".github/workflows/*.yaml"]
+similarity_on   = ["job_ids", "step_uses", "step_run_shape"]
+similarity_min  = 0.85
+warn_at         = 4
+fail_at         = 8
+exempt_marker   = "proliferation-ok:"      # ignored unless it states a reason
+message         = """
+{count} workflows share ~{similarity} of their structure. This is the shape that reached 98 files
+in one repo, where changing release policy became a 98-file edit. Replace them with one workflow
+and a `strategy.matrix`, or state why not with `# proliferation-ok: <reason>`.
+"""
+
+# The threshold is deliberately low. A repo with 8 genuinely different workflows can exempt them
+# once; a repo generating one per package hits it at the point the pattern is still cheap to undo.
+
+# ── self-tests ────────────────────────────────────────────────────────────────
+
+[[self_test]]
+gate    = "ci-workflow-proliferation"
+expect  = "fail"
+fixture = { workflows = 12, similarity = 0.97 }
+
+[[self_test]]
+gate    = "ci-workflow-proliferation"
+expect  = "pass"
+fixture = { workflows = 12, similarity = 0.30 }
+
+[[self_test]]
+gate    = "ci-workflow-proliferation"
+expect  = "pass"
+fixture = { workflows = 12, similarity = 0.97, exempt = "proliferation-ok: per-runtime, they differ in the container image" }
+
+[[self_test]]
+gate    = "ci-workflow-proliferation"
+expect  = "fail"
+fixture = { workflows = 12, similarity = 0.97, exempt = "proliferation-ok:" }

package/modules/ci/module.toml

@@ -0,0 +1,74 @@
+[module]
+name    = "ci"
+version = "1.0.0"
+rung    = 1
+summary = "One workflow that runs the gate registry, a matrix instead of a file per item, and a check that keeps it that way."
+
+[requires]
+modules = ["gates"]
+
+[conflicts]
+modules = []
+
+# Rung 1, but bundled in the `disciplined` profile rather than `tracked`: rung is
+# how mature the practice is, a profile is which problem you have. A solo repo
+# can be at rung 1 without needing CI at all.
+
+[params.provider]
+description  = "CI provider. Only `github` is implemented."
+default      = "github"
+allowed      = ["github"]
+consumed_by  = "render"
+
+[params.trigger]
+description  = """
+When the gate run fires. `push` runs on every push to any branch. `land` runs only on the
+integration branch and on merge refs, which is what a repo with billed minutes and many concurrent
+sessions wants — rift-forge measured ~19 billed minutes per run, and one run per push across ~15
+sessions is 400-1000 minutes a day.
+"""
+default      = "push"
+allowed      = ["push", "land"]
+consumed_by  = "render"
+# Reaches file content through the `ci-triggers` managed block, not through a
+# conditional. That is the general mechanism: a behavioural parameter changes
+# what the renderer writes into a block, and substitution-only stays intact.
+
+[params.workflow_path]
+description = "Where the workflow file lands"
+default     = ".github/workflows/checks.yml"
+
+[[gates]]
+id     = "ci-workflow-proliferation"
+kind   = "declared"
+engine = "file-population"
+table  = "gates/ci.toml"
+tier   = "fast"
+why    = """
+hexguard has 98 near-identical per-package release workflows because a phase checklist told the
+agent to add one each time. Changing release policy there is a 98-file edit and the workflow
+directory is unreadable. A checklist step that creates a file creates N files, and nobody notices
+until N is large — so the count is checked.
+"""
+
+[detect]
+paths   = [".github/workflows/*.yml", ".github/workflows/*.yaml", ".gitlab-ci.yml", "azure-pipelines.yml"]
+markers = ["rungs:begin ci"]
+
+[[detect.adopt_as]]
+kind = "existing-workflows"
+note = """
+A repo with workflows has CI; it does not have this registry-driven one. Adopt means: leave every
+existing workflow alone, add one that runs `rungs check`, and report the proliferation count so the
+owner can see what they have. Never rewrite or delete a workflow — that is somebody's deploy.
+"""
+
+[provenance]
+sources  = ["hexguard", "rift-forge"]
+patterns = ["matrix-not-per-item-ci", "workflow-proliferation-check", "ci-at-land-time"]
+incident = """
+hexguard's .github/workflows/ holds 99 files: one CI workflow and 98 per-package release
+workflows, near-identical, hand-maintained, emitted one at a time by Phase 3 of a mandatory
+checklist. rift-forge went the other way and made CI cost-aware — item branches are deliberately
+not triggers, because the repository is private and one run is ~19 billed minutes.
+"""

package/modules/concurrency/files/docs/concurrent-sessions.md

@@ -0,0 +1,87 @@
+**Authoritative for:** the loop many sessions share: where to branch from, when to verify, how to land, and which conflicts are the tooling’s problem.
+**Not authoritative for:** the backlog lifecycle those branches carry, and the gates the loop runs.
+
+# Concurrent sessions
+
+**Read the threshold first.** Below roughly five sessions working at once on one integration
+branch, everything here costs more than it returns. It is a real tooling surface with its own
+failure modes.
+
+Every rule assumes one thing: **many sessions work at once, in separate worktrees, off one shared
+branch, and they cannot see each other's work.**
+
+## The loop
+
+| | |
+| --- | --- |
+| `rungs session start <branch>` | Cuts from `{{green_prefix}}<branch>` — the last merge that was actually verified — not the tip. Falls back to the tip and **says so** |
+| `rungs check` | The fast tier. Run it constantly |
+| `rungs preflight` | The integration branch moved: did it change files *you* changed? That, not the commit count, predicts a conflict |
+| `rungs land <branch>` | merge → verify **the merged tree** → fast-forward → move the green ref |
+| `rungs worktrees` | What is finished and prunable. **Reports only** — removing someone else's worktree is not a script's call |
+
+## Do not run the full tier before landing
+
+`land` runs it on the merged tree itself. A separate full run beforehand proves nothing land will
+not prove — and it is not merely wasted time: **the integration branch moves while it runs**, so
+the pre-verify is what widens the window the merge then conflicts in.
+
+Measured in one session: three of five land attempts refused, every one after a 4–12 minute
+pre-verify, every one on the same generated artifacts. The attempt that landed did merge → resolve
+→ regenerate → land with nothing in between.
+
+So: **fast tier constantly, full tier at the boundary.** Reach for it early only to answer a
+deliberate question, never as a ritual.
+
+## A failure is attributed, never just counted
+
+`check` re-runs each failing gate against the merge base in a throwaway worktree and reports it as
+**inherited** (already red before you started — stated, never blocking) or **INTRODUCED** (yours —
+blocks). Anything it cannot attribute also blocks: **we do not land on an unknown.**
+
+This is not politeness about blame. *A gate that is red for reasons you did not cause and cannot
+fix is a gate you learn to bypass, and a bypassed gate reports nothing.*
+
+> **Attribution makes a red gate survivable, which also removes the pressure to fix it.** One repo
+> ran 11 of its last 15 CI runs red on two permanently-broken jobs. The ledger's ageing signal
+> exists for exactly this: fix them or delete them.
+
+## Land, then move the tip — in that order
+
+`land` merges into a scratch `{{integ_prefix}}…` ref, verifies **that** tree, and only then
+fast-forwards with a compare-and-swap. Two things follow:
+
+- **The integration branch cannot go red from a merge nobody verified** — the ref update is
+  unreachable otherwise, and a refusal leaves it bit-for-bit unchanged with the merged tree parked
+  for you to fix.
+- **Concurrent landing is refused, not silently merged.** A real lock names its holder and start
+  time and is taken over if the holder died.
+
+**Nothing keeps the integration branch checked out.** If something needs it checked out, that is a
+bug in whatever it is doing.
+
+## Three things to know when a land refuses
+
+- **Your worktree is left detached.** Your branch and commits are safe; the files in front of you
+  are simply not yours. Switch back and carry on. Do not "restore" anything.
+- **Check the exit code of `land` itself.** Piping it through `tail` or `grep` reports *that*
+  command's status, so a refused land reads as success.
+- **Reconcile generated artifacts by regenerating, never by merging text.** Take one side, re-run
+  the producer, and re-pin what moved with the reason at the pin.
+
+## What conflicts, and which of it is the tooling's problem
+
+| Class | Handling |
+| --- | --- |
+| **Id ledgers** — boards, registers, indexes | The driver takes the higher `NEXT-ID` and keeps both claim comments. **It resolves nothing else** — a row that moved section is handed back, because a union merge would keep both copies of it |
+| **Generated artifacts** | The driver **always refuses** and prints the regenerate command |
+| **Shared code** | **Not a tooling problem — a scheduling one.** Give a hot surface one owner at a time and batch same-surface work behind one session. `preflight` tells you when you are about to collide |
+
+That third row is the honest one: it names the class this will not automate and prescribes
+scheduling instead.
+
+## Worktree lifetime is item lifetime
+
+Delete the branch when it lands. `rungs worktrees` measures whether that happened and flags
+worktrees that are merged and clean — and, more usefully, ones that are merged **and dirty**, where
+uncommitted work is sitting in a branch that has already landed.

package/modules/concurrency/fragments/AGENTS.md

@@ -0,0 +1,10 @@
+<!-- rungs:begin concurrency@1.0.0 -->
+## Concurrent sessions
+
+Many sessions share `{{integration_branch}}` and cannot see each other — see
+[`docs/concurrent-sessions.md`](docs/concurrent-sessions.md). Cut with `rungs session start`
+(from the last **verified** merge, not the tip), run the fast tier constantly, and land with
+`rungs land` — **never `git merge` by hand**. Do not run the full tier before landing: it widens
+the window the merge then conflicts in. Reconcile generated artifacts by **regenerating**, never
+by merging text.
+<!-- rungs:end concurrency -->

package/modules/concurrency/fragments/gitattributes

@@ -0,0 +1,15 @@
+# rungs:begin concurrency@1.0.0
+# Merge drivers per conflict class. INERT until `rungs setup git` installs them — the driver names
+# below mean nothing to git on a fresh clone, and merges quietly fall back to the default. For a
+# generated artifact that default is a clean text merge of a file that is a fixed point of nothing.
+
+# Id ledgers: take the higher NEXT-ID counter, keep both claim comments, resolve nothing else.
+docs/**/BACKLOG.md    merge=rungs-ledger
+docs/**/FINDINGS.md   merge=rungs-ledger
+
+# Generated artifacts: always refuse, and print the regenerate command.
+.claude/rules/**      merge=rungs-generated
+.github/instructions/** merge=rungs-generated
+.cursor/rules/**      merge=rungs-generated
+.ai/render-report.md  merge=rungs-generated
+# rungs:end concurrency