@rungs/cli 0.1.3 → 0.3.0

package/modules/release/gates/release.toml

@@ -32,10 +32,21 @@ sources = [
   { file = "pyproject.toml", path = "project.version" },
 ]
 rule    = "all-agree"
-autofix = "rungs release sync-version"
+
+# Files that are deliberately versioned on their own. Empty by default: which packages share a
+# version is a judgement about *your* repo, and the engine guessing it is how a healthy layout gets
+# a red gate. rungs' own docs site is the case that found this — a private, never-published package
+# sitting at its own version beside the CLI (F-023).
+exclude = []
+
+# No `autofix` key. It named a "rungs release sync-version" command that does not exist and never
+# has, so the message told whoever hit this gate to run something that would fail. The engine now
+# names each file beside the version it states, which is what you need to fix it by hand.
+# (Deliberately not in a code span: `module-commands-exist` reads those as command claims, and it
+# is right to — a phantom command in backticks is exactly what it exists to refuse.)
 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.
+not, which is discovered by a user rather than by us.
 """
 
 # What this does not cover is pinned, so green never reads as "verified":
@@ -47,6 +58,25 @@ uncovered = [
 ]
 note = "A green check means these files agree, not that the version is correct everywhere."
 
+# ── release-fragment-current ──────────────────────────────────────────────────
+#
+# The other half of the fragment discipline. `release-changelog-fragment` catches a release-worthy
+# change that added no fragment; this catches a fragment that was consumed and never deleted.
+#
+# Only filenames that parse as a version are judged. A repo whose fragments are named per-change
+# (`42.feature.md`) states no version, so there is nothing to compare and nothing is claimed — a
+# gate that refused a naming convention it was not asked about is one people turn off.
+
+[[changelog_freshness]]
+id        = "release-fragment-current"
+fragments = ["{{changelog_dir}}/*.md"]
+version   = { file = "package.json", path = "version" }
+message = """
+This fragment names a version below the one being prepared, so it belongs to a release that already
+shipped. Delete it — fragments are consumed, not archived, and one left behind is republished as
+though it were new work.
+"""
+
 # ── self-tests ────────────────────────────────────────────────────────────────
 
 [[self_test]]
@@ -74,12 +104,50 @@ gate    = "release-changelog-fragment"
 expect  = "fail"
 fixture = { changed = ["src/a.ts"], fragments = [], exempt = "changelog-ok:" }
 
+[[self_test]]
+gate    = "release-fragment-current"
+expect  = "fail"
+fixture = { dir = "changelog.d", version = "0.2.0", fragments = ["0.1.1.md"] }
+
+[[self_test]]
+gate    = "release-fragment-current"
+expect  = "pass"
+fixture = { dir = "changelog.d", version = "0.2.0", fragments = ["0.2.0.md"] }
+
+# A fragment for a version *above* the one being prepared is not stale — it is a branch that
+# already decided it is a minor while the package has not been bumped yet.
+[[self_test]]
+gate    = "release-fragment-current"
+expect  = "pass"
+fixture = { dir = "changelog.d", version = "0.2.0", fragments = ["0.3.0.md"] }
+
+# Per-change fragment naming states no version, so there is nothing to compare and nothing is
+# claimed. The gate must stay silent rather than refuse a convention it was not asked about.
+[[self_test]]
+gate    = "release-fragment-current"
+expect  = "pass"
+fixture = { dir = "changelog.d", version = "0.2.0", fragments = ["42.feature.md"] }
+
 [[self_test]]
 gate    = "release-version-consistent"
 expect  = "fail"
-fixture = { values = ["1.2.0", "1.1.0"] }
+fixture = { packages = { "package.json" = "1.2.0", "web/package.json" = "1.1.0" } }
+
+[[self_test]]
+gate    = "release-version-consistent"
+expect  = "pass"
+fixture = { packages = { "package.json" = "1.2.0", "web/package.json" = "1.2.0" } }
 
+# The F-023 case: a sibling deliberately versioned on its own is excluded and the gate stays green,
+# rather than reporting a healthy layout as a disagreement.
 [[self_test]]
 gate    = "release-version-consistent"
 expect  = "pass"
-fixture = { values = ["1.2.0", "1.2.0"] }
+fixture = { packages = { "package.json" = "1.2.0", "web/package.json" = "0.0.1" }, exclude = ["web/package.json"] }
+
+# …and excluding one sibling must not blind the gate to a different one. An `exclude` that
+# silently widened would be worse than no gate, because it would still report green.
+[[self_test]]
+gate    = "release-version-consistent"
+expect  = "fail"
+fixture = { packages = { "package.json" = "1.2.0", "web/package.json" = "0.0.1", "api/package.json" = "9.9.9" }, exclude = ["web/package.json"] }

package/modules/release/module.toml

@@ -1,6 +1,6 @@
 [module]
 name    = "release"
-version = "1.0.0"
+version = "1.2.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."
 
@@ -46,6 +46,7 @@ consumed_by = "render"
 id     = "release-changelog-fragment"
 kind   = "declared"
 engine = "file-population"
+applicability = "repo-content"
 table  = "gates/release.toml"
 tier   = "fast"
 why    = """
@@ -54,10 +55,24 @@ cut time when nobody remembers what it did. Cheaper to require the fragment on t
 the change.
 """
 
+[[gates]]
+id     = "release-fragment-current"
+kind   = "declared"
+engine = "changelog-freshness"
+applicability = "repo-content"
+table  = "gates/release.toml"
+tier   = "fast"
+why    = """
+Fragments are consumed at release time, not archived — one left behind appears in the next release
+too, where it reads as unreleased work. `cut-release` §3 has said so in prose since it was written,
+and prose did not hold it: this repo's own `0.1.1` fragment survived two releases (F-022).
+"""
+
 [[gates]]
 id     = "release-version-consistent"
 kind   = "declared"
 engine = "computed-claim"
+applicability = "our-schema"
 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."

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

@@ -22,9 +22,16 @@ mismatch is usually a fragment somebody skipped, not a versioning disagreement.
 ## 2. Gate
 
 ```bash
-rungs check --tier full
+rungs check
 ```
 
+Run **every** registered gate. This step used to name a "--tier full" flag that the CLI does not
+accept, so both words were parsed as positionals and the run checked a directory that does not
+exist — reporting no gates rather than a pass. A release step that gates on nothing while looking
+green is worse than one that is skipped, because nobody goes back to check it.
+
+Narrow to a tier (`rungs check --fast`) only when you know the tier holds what you meant to run.
+
 **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.
 

package/modules/session/module.toml

@@ -1,6 +1,6 @@
 [module]
 name    = "session"
-version = "1.1.0"
+version = "1.2.0"
 rung    = 1
 summary = "A handoff document carrying state between sessions: resume point, active constraints, and a dated archive."
 
@@ -27,7 +27,8 @@ default     = ".ai/archive"
 [[gates]]
 id     = "session-sections-present"
 kind   = "declared"
-engine = "frontmatter-schema"
+engine = "sections"
+applicability = "our-schema"
 table  = "gates/session.toml"
 tier   = "fast"
 why    = """
@@ -39,6 +40,7 @@ reopens a settled question, which is the specific failure this document exists t
 id     = "session-archive-named"
 kind   = "declared"
 engine = "filename-schema"
+applicability = "our-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."

package/modules/skills/module.toml

@@ -30,6 +30,7 @@ consumed_by = "render"
 id     = "skills-spec-pure"
 kind   = "declared"
 engine = "frontmatter-schema"
+applicability = "our-schema"
 table  = "gates/skills.toml"
 tier   = "fast"
 why    = """
@@ -43,6 +44,7 @@ is stated at the point of the choice.
 id     = "skills-description-routes"
 kind   = "declared"
 engine = "frontmatter-schema"
+applicability = "our-schema"
 table  = "gates/skills.toml"
 tier   = "fast"
 why    = """
@@ -55,6 +57,7 @@ what the skill does and the phrases people actually say.
 id     = "skills-names-neighbours"
 kind   = "declared"
 engine = "cross-reference"
+applicability = "our-schema"
 table  = "gates/skills.toml"
 tier   = "fast"
 why    = """

package/modules/specs/module.toml

@@ -37,6 +37,7 @@ default     = 600
 id     = "specs-status-evidence"
 kind   = "declared"
 engine = "register-schema"
+applicability = "our-schema"
 table  = "gates/specs.toml"
 tier   = "fast"
 why    = """
@@ -49,6 +50,7 @@ integration is worse than no spec, because it is read as verified.
 id     = "specs-scope-section"
 kind   = "declared"
 engine = "sections"
+applicability = "our-schema"
 table  = "gates/specs.toml"
 tier   = "fast"
 why    = "Out-of-scope is what stops an agent silently expanding a surface while implementing an unrelated story."
@@ -57,6 +59,7 @@ why    = "Out-of-scope is what stops an agent silently expanding a surface while
 id     = "specs-ids-unique"
 kind   = "declared"
 engine = "id-integrity"
+applicability = "our-schema"
 table  = "gates/specs.toml"
 tier   = "fast"
 why    = "Story ids are cited from commits, plans and work items; two stories sharing one make every citation ambiguous."
@@ -65,6 +68,7 @@ why    = "Story ids are cited from commits, plans and work items; two stories sh
 id     = "specs-split-threshold"
 kind   = "declared"
 engine = "file-budget"
+applicability = "repo-content"
 table  = "gates/specs.toml"
 tier   = "fast"
 why    = "A spec past the threshold is one nobody reads to the end, and its later sections are where the unverified claims collect."

package/modules/workflows/module.toml

@@ -29,6 +29,7 @@ default     = "docs/plans"
 id     = "workflows-plan-tier-declared"
 kind   = "declared"
 engine = "frontmatter-schema"
+applicability = "our-schema"
 table  = "gates/workflows.toml"
 tier   = "fast"
 why    = """
@@ -41,6 +42,7 @@ call the table exists to replace.
 id     = "workflows-plan-sections"
 kind   = "declared"
 engine = "sections"
+applicability = "our-schema"
 table  = "gates/workflows.toml"
 tier   = "fast"
 why    = "A tier-2 proposal missing its proof-of-reuse gate is a tier-1 plan wearing a heavier label."

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rungs/cli",
-  "version": "0.1.3",
+  "version": "0.3.0",
   "description": "Installs and maintains a repository's agentic development system, composed from modules.",
   "author": "Antoine Dancre",
   "repository": {

package/src/add.ts

@@ -66,7 +66,11 @@ export function addModule(
     const base = join(mod.dir, 'skills');
     const dir = opts.skillsDir ?? '.claude/skills';
     for (const rel of walk(base)) {
-      write(`${dir}/${rel}`, sub(readFileSync(join(base, rel), 'utf8')), 'skill');
+      // Through the same helper `emittedFiles` uses. These two paths both emit
+      // skills and are easy to change apart — patching only `emittedFiles` for
+      // F-019 left `add` still writing the un-extended file, so an install and
+      // an upgrade would have produced different content for the same skill.
+      write(`${dir}/${rel}`, withOptedInExtensions(mod, rel, sub(readFileSync(join(base, rel), 'utf8'))), 'skill');
     }
   }
 
@@ -165,6 +169,31 @@ const gateEntry = (mod: Manifest) => (g: Manifest['gates'][number]) => {
 };
 
 /** Dependency order, refusing anything unmet — naming the incident (ADR-0003). */
+/**
+ * Every module in `order` that cannot be installed because one of the modules
+ * it needs — or itself — is a different paradigm.
+ *
+ * A refusal has to travel *up* the dependency edges, not just stop at the
+ * module that matched. `add audit` pulls `findings` which pulls `backlog`; if
+ * the repo's work lives in an issue tracker, refusing `backlog` and installing
+ * `audit` anyway would ship an audit procedure whose findings have nowhere to
+ * close — which is the exact incident (268 audit documents, no register) that
+ * made `audit → findings → backlog` a declared dependency in the first place.
+ */
+export function blockedByParadigm(order: Manifest[], paradigms: ReadonlySet<string>): Map<string, string> {
+  const blocked = new Map<string, string>();
+  // `order` is already dependency-first, so one forward pass settles it.
+  for (const mod of order) {
+    if (paradigms.has(mod.name)) {
+      blocked.set(mod.name, mod.name);
+      continue;
+    }
+    const dep = mod.requires.find((d) => blocked.has(d));
+    if (dep) blocked.set(mod.name, blocked.get(dep)!);
+  }
+  return blocked;
+}
+
 export function resolveInstallOrder(requested: string[], all: Manifest[]): { order: Manifest[]; missing: string[] } {
   const byName = new Map(all.map((m) => [m.name, m]));
   const order: Manifest[] = [];
@@ -232,6 +261,37 @@ export const contentHash = (s: string) => createHash('sha256').update(s.replace(
  */
 const SHARED = new Set(['AGENTS.md', 'CLAUDE.md', '.gitignore', '.gitattributes', '.ai/gates.toml']);
 
+/**
+ * Add the harness extensions a module opted this skill into.
+ *
+ * F-019. `[skills.work-item] extensions = { disable-model-invocation = true }`
+ * was declared in the `backlog` manifest, documented in `modules/README.md`, and
+ * **implemented at no layer**: `grep -n extensions src/*.ts` returned nothing, so
+ * the key never reached the emitted `SKILL.md`, and the gate that is supposed to
+ * police it could not see the opt-in either. `work-item` creates branches and
+ * merges, and the manifest's stated reason for opting it out of model invocation
+ * had been inert since it was written.
+ *
+ * Injected here rather than written into the source skill because that is the
+ * point of the opt-in: the file stays spec-pure and portable
+ * ([ADR-0001](../docs/decisions/ADR-0001-multi-harness-rendering.md)), and the
+ * extension — with its portability cost — stays attached to the module's
+ * decision to take it.
+ */
+function withOptedInExtensions(mod: Manifest, rel: string, content: string): string {
+  const name = rel.split(/[\\/]/)[0];
+  const extensions = mod.skills?.[name]?.extensions;
+  if (!extensions || !Object.keys(extensions).length) return content;
+
+  const m = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!m) return content; // no frontmatter to extend; `skills-spec-pure` reports it
+  const added = Object.entries(extensions)
+    .filter(([k]) => !new RegExp(`^${k}:`, 'm').test(m[1]))
+    .map(([k, v]) => `${k}: ${v}`);
+  if (!added.length) return content;
+  return content.replace(/^---\n[\s\S]*?\n---/, `---\n${m[1]}\n${added.join('\n')}\n---`);
+}
+
 export function emittedFiles(mod: Manifest, params: Params, skillsDir = '.claude/skills'): Map<string, string> {
   const out = new Map<string, string>();
   const sub = (t: string) => substitute(t, mod.name, params);
@@ -245,7 +305,9 @@ export function emittedFiles(mod: Manifest, params: Params, skillsDir = '.claude
     for (const rel of walk(base)) {
       const target = sub(prefix + rel).split('\\').join('/');
       if (SHARED.has(target)) continue;
-      out.set(target, sub(readFileSync(join(base, rel), 'utf8')));
+      let content = sub(readFileSync(join(base, rel), 'utf8'));
+      if (dir === 'skills') content = withOptedInExtensions(mod, rel, content);
+      out.set(target, content);
     }
   }
   return out;

package/src/backlog.ts

@@ -0,0 +1,197 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname, join, relative, resolve, sep } from 'node:path';
+import { walk } from './glob.ts';
+
+/**
+ * `rungs backlog archive` — move finished items out of `items/` and repoint
+ * every link in the repo at their new home.
+ *
+ * F-015. Three files shipped into **every** consumer repo named this command,
+ * two of them saying "never by hand", and it did not exist: `rungs backlog`
+ * answered *"unknown command"*. So the instruction was unfollowable everywhere
+ * rungs had ever been installed, and the reason it says *never by hand* is
+ * exactly why it could not be worked around — moving 39 files and rewriting
+ * every citation of them is the kind of repo-wide edit that fails silently.
+ *
+ * The link rewrite is the whole substance of the command. It resolves each
+ * link from the citing file's **own** directory rather than pattern-matching
+ * text, because the same target is written `items/WI-001-x.md`,
+ * `../items/WI-001-x.md` and `WI-001-x.md` depending on who is citing it, and a
+ * regex over any one of those spellings silently misses the others.
+ */
+
+export interface ArchiveMove {
+  id: string;
+  status: string;
+  from: string;
+  to: string;
+}
+
+export interface ArchivePlan {
+  root: string;
+  moves: ArchiveMove[];
+  /** Files whose links change, with how many links move in each. */
+  rewrites: { file: string; links: number }[];
+  /** Items that look finished but are not eligible, with the reason. */
+  held: { file: string; reason: string }[];
+}
+
+/** Statuses whose work can no longer change. Mirrors backlog README §8. */
+const FINISHED = new Set(['done', 'rejected']);
+
+const field = (text: string, name: string) => text.match(new RegExp(`^${name}:\\s*(\\S+)`, 'm'))?.[1] ?? '';
+
+const posix = (p: string) => p.split(sep).join('/');
+
+/** A relative markdown link that could point at a repo file. */
+const LINK = /\]\((?!https?:|#|mailto:)([^)\s#]+)((?:#[^)\s]*)?)\)/g;
+
+export function planArchive(repoRoot: string, backlogRoot = 'docs/backlog'): ArchivePlan {
+  const itemsDir = join(repoRoot, ...backlogRoot.split('/'), 'items');
+  const archiveDir = join(repoRoot, ...backlogRoot.split('/'), 'archive');
+  const moves: ArchiveMove[] = [];
+  const held: ArchivePlan['held'] = [];
+
+  const files = walk(repoRoot);
+  const items = files.filter((f) => posix(f).startsWith(posix(relative(repoRoot, itemsDir)) + '/') && f.endsWith('.md'));
+
+  for (const rel of items) {
+    // The **basename**, exactly — not a suffix of the path. `/TEMPLATE\.md$/i`
+    // also matches any item whose filename ends in `-template.md`, and it did:
+    // `WI-010-framework-extraction-template.md` was skipped on every run since
+    // this command shipped, so a `done` item stayed in `items/` while the
+    // command reported "nothing to archive". An anchored regex that is anchored
+    // to the wrong end reads as careful and is not.
+    const base = posix(rel).split('/').pop()!;
+    if (/^(README|TEMPLATE)\.md$/i.test(base)) continue;
+    const text = readFileSync(join(repoRoot, rel), 'utf8');
+    const status = field(text, 'status');
+    const id = field(text, 'id');
+    if (!FINISHED.has(status)) continue;
+
+    // An epic whose children are not all finished is still live bookkeeping: it
+    // is the thing that says what remains. Moving it would file the index of
+    // open work under "cannot change any more".
+    if (field(text, 'type') === 'epic') {
+      const children = (text.match(/^children:\s*\[(.*)\]/m)?.[1] ?? '')
+        .split(',')
+        .map((s) => s.trim())
+        .filter(Boolean);
+      // A child that is **already archived** is finished — that is what being in
+      // `archive/` means. Searching only `items/` made every archived child read
+      // as unfinished, so an epic whose children had all landed could never be
+      // archived and the hold message named five done items as outstanding. The
+      // more finished an epic got, the more stuck it became.
+      const archived = files.filter((f) => posix(f).startsWith(posix(relative(repoRoot, archiveDir)) + '/') && f.endsWith('.md'));
+      const unfinished = children.filter((c) => {
+        const f = items.find((i) => i.includes(`${c}-`)) ?? archived.find((i) => i.includes(`${c}-`));
+        // Still `!f` → genuinely unknown, and an unknown holds. A child nobody
+        // can find is not evidence that it finished.
+        return !f || !FINISHED.has(field(readFileSync(join(repoRoot, f), 'utf8'), 'status'));
+      });
+      if (unfinished.length) {
+        held.push({ file: rel, reason: `epic with unfinished children: ${unfinished.join(', ')}` });
+        continue;
+      }
+    }
+
+    // `posix(rel)` first: `walk` yields `/`-separated paths, so splitting on the
+    // platform `sep` on Windows never splits and the basename came back as the
+    // whole path — producing `archive/docs/backlog/items/WI-001-….md`.
+    moves.push({
+      id,
+      status,
+      from: rel,
+      to: posix(join(relative(repoRoot, archiveDir), posix(rel).split('/').pop()!)),
+    });
+  }
+
+  // Where each moved file ends up, keyed by its absolute old path, so a link can
+  // be looked up by what it resolves to rather than by how it was spelled.
+  const moved = new Map(moves.map((m) => [resolve(repoRoot, m.from), m.to]));
+  const rewrites: ArchivePlan['rewrites'] = [];
+
+  for (const rel of files) {
+    if (!isRewritable(rel)) continue;
+    const links = retargets(repoRoot, rel, moved).length;
+    if (links || moved.has(resolve(repoRoot, rel))) rewrites.push({ file: rel, links });
+  }
+
+  return { root: backlogRoot, moves, rewrites, held };
+}
+
+/**
+ * A module's `files/` and `fragments/` are **templates**, not repo content.
+ * Their links are relative to wherever the fragment merges into, they carry
+ * `{{param}}` tokens, and resolving them here reports every one as broken —
+ * which is why `link_integrity.exclude` already skips them. Rewriting them
+ * would be worse than reporting them: it would bake this repo's paths into what
+ * every consumer repo gets installed.
+ */
+function isRewritable(rel: string): boolean {
+  const p = posix(rel);
+  if (!p.endsWith('.md')) return false;
+  return !/^modules\/[^/]+\/(files|fragments)\//.test(p) && !p.startsWith('node_modules/');
+}
+
+/**
+ * The links in one file that this archive run has to change, and what to.
+ *
+ * Deliberately **only** links whose target moved, plus — when the citing file is
+ * itself moving — links that would otherwise break from the new location. The
+ * first version compared every link's written form against a freshly computed
+ * relative path and counted a difference as a change, which claimed 334 links
+ * across 58 files including `AGENTS.md`, `README.md` and module templates. Most
+ * of those were equivalent spellings of an unmoved target. Rewriting them would
+ * have been a repo-wide reflow disguised as an archive.
+ */
+function retargets(repoRoot: string, rel: string, moved: Map<string, string>): { href: string; to: string }[] {
+  const oldDir = dirname(resolve(repoRoot, rel));
+  const selfMoved = moved.get(resolve(repoRoot, rel));
+  const newDir = dirname(resolve(repoRoot, selfMoved ?? rel));
+  const out: { href: string; to: string }[] = [];
+
+  for (const m of readFileSync(join(repoRoot, rel), 'utf8').matchAll(LINK)) {
+    const href = m[1];
+    if (href.includes('{{')) continue; // a template link, resolved at install
+    const target = resolve(oldDir, decodeURIComponent(href));
+    const targetMoved = moved.get(target);
+    if (!targetMoved && !selfMoved) continue;
+    if (!targetMoved && !existsSync(target)) continue; // already broken; not this command's to fix
+    const targetNew = targetMoved ? resolve(repoRoot, targetMoved) : target;
+    // No `./` prefix. It is never required for a relative markdown link, and
+    // adding it rewrites the spelling of paths whose *target* is what changed —
+    // turning a one-word diff into a whole-line one across 37 files.
+    const to = posix(relative(newDir, targetNew));
+    if (to !== posix(href)) out.push({ href, to });
+  }
+  return out;
+}
+
+export function applyArchive(repoRoot: string, plan: ArchivePlan): void {
+  const moved = new Map(plan.moves.map((m) => [resolve(repoRoot, m.from), m.to]));
+
+  // Rewrite before moving. Every path is computed from the plan rather than from
+  // the filesystem, so the order is a choice — and this order means a crash
+  // halfway leaves the files still where the links say they are.
+  for (const rel of walk(repoRoot)) {
+    if (!isRewritable(rel)) continue;
+    const edits = retargets(repoRoot, rel, moved);
+    if (!edits.length) continue;
+    const path = join(repoRoot, rel);
+    let text = readFileSync(path, 'utf8');
+    // Replace through the same matcher that found them, so a href appearing in
+    // prose as well as in a link cannot be hit by a bare string replace.
+    text = text.replace(LINK, (whole, href: string, anchor: string) => {
+      const edit = edits.find((e) => e.href === href);
+      return edit ? `](${edit.to}${anchor})` : whole;
+    });
+    writeFileSync(path, text);
+  }
+
+  for (const m of plan.moves) {
+    const to = join(repoRoot, ...m.to.split('/'));
+    mkdirSync(dirname(to), { recursive: true });
+    renameSync(join(repoRoot, m.from), to);
+  }
+}

package/src/check.ts

@@ -44,8 +44,56 @@ export function loadRegistry(repoRoot: string): { runner: any; gates: RegistryGa
   return { runner: raw.runner ?? {}, gates: raw.gates ?? [] };
 }
 
-export function runGates(repoRoot: string, tier?: string, now = () => Date.now()): GateRun[] {
-  const { gates } = loadRegistry(repoRoot);
+/**
+ * ADR-0008: a tier is an ordered **level**, not a tag. `[runner] tiers` declares
+ * the order, and asking for one runs every gate at that level or below it.
+ *
+ * This was string equality, so `full` selected only gates labelled `full` — zero
+ * of them on a registry where everything is `fast`, which is this repo. The run
+ * then reported no gates and exited as though the release had been gated, and
+ * `cut-release` told every consumer to gate on exactly that command (F-020).
+ */
+export function tierSelects(runnerTiers: string[], requested: string, gateTier?: string): boolean {
+  if (!gateTier) return true; // untiered gates run in every tier
+  const at = runnerTiers.indexOf(requested);
+  const of = runnerTiers.indexOf(gateTier);
+  // An undeclared tier on either side cannot be ordered. Fall back to equality
+  // rather than guessing a position — silently including it would be worse.
+  if (at < 0 || of < 0) return gateTier === requested;
+  return of <= at;
+}
+
+/**
+ * No parameter properties: Node's strip-only TypeScript mode rejects them, and
+ * `dist/` is built from these sources for a runtime that has no compiler. The
+ * same constraint is what v0.1.1 shipped broken (ERR_UNSUPPORTED_NODE_MODULES_
+ * TYPE_STRIPPING), so it is worth the four extra lines.
+ */
+export class UnknownTierError extends Error {
+  requested: string;
+  declared: string[];
+  constructor(requested: string, declared: string[]) {
+    super(`unknown tier "${requested}"`);
+    this.requested = requested;
+    this.declared = declared;
+  }
+}
+
+/**
+ * `only` narrows the run to named gate ids. Attribution needs it: after a merged
+ * tree goes red, `land` re-runs **just the failing gates** against the merge base
+ * to decide whether they were already red. Re-running all of them would give the
+ * same verdict and cost a second full pass for gates nobody asked about.
+ */
+export function runGates(repoRoot: string, tier?: string, now = () => Date.now(), only?: ReadonlySet<string>): GateRun[] {
+  const { runner, gates } = loadRegistry(repoRoot);
+  const runnerTiers: string[] = Array.isArray(runner?.tiers) ? runner.tiers : [];
+  // A tier nobody declared selects nothing, and "selected nothing" is
+  // indistinguishable from "everything passed" at the exit code. Refuse it here
+  // rather than let a typo read as a green release gate.
+  if (tier && runnerTiers.length && !runnerTiers.includes(tier)) {
+    throw new UnknownTierError(tier, runnerTiers);
+  }
   const files = walk(repoRoot);
   const runs: GateRun[] = [];
 
@@ -53,7 +101,8 @@ export function runGates(repoRoot: string, tier?: string, now = () => Date.now()
     // A hook fires on a tool call, not in the runner. Skipping it here is
     // correct; counting it as a pass would not be.
     if (g.trigger) continue;
-    if (tier && g.tier && g.tier !== tier) continue;
+    if (only && !only.has(g.id)) continue;
+    if (tier && !tierSelects(runnerTiers, tier, g.tier)) continue;
 
     const started = now();
     let status: Status = 'pass';
@@ -124,7 +173,7 @@ export function runGates(repoRoot: string, tier?: string, now = () => Date.now()
  * parameters before parsing — which is also what makes a gate honour the
  * prefix, root and budget that repo actually chose.
  */
-function loadTable(ref: string | undefined, repoRoot: string): any | null {
+export function loadTable(ref: string | undefined, repoRoot: string): any | null {
   if (!ref) return null;
   const [mod, file] = ref.split('/');
   const path = join(MODULES, mod, 'gates', file);
@@ -139,7 +188,7 @@ function loadTable(ref: string | undefined, repoRoot: string): any | null {
 let paramCache: { root: string; params: Params } | null = null;
 
 /** Parameters as the repo installed them, falling back to module defaults. */
-function installedParams(repoRoot: string): Params {
+export function installedParams(repoRoot: string): Params {
   if (paramCache?.root === repoRoot) return paramCache.params;
   const defaults = resolveParams(loadAllModules(MODULES), {}, repoRoot);
   const recordPath = join(repoRoot, '.ai', 'rungs.toml');
@@ -157,7 +206,7 @@ function installedParams(repoRoot: string): Params {
   return defaults;
 }
 
-const tableKey = (engine: string) =>
+export const tableKey = (engine: string) =>
   ({
     'file-budget': 'file_budget',
     sections: 'sections',
@@ -177,6 +226,7 @@ const tableKey = (engine: string) =>
     'rule-propagation': 'rule_propagation',
     'git-state': 'git_state',
     'merge-driver-check': 'merge_driver_check',
+    'board-reconcile': 'board_reconcile',
   })[engine] ?? engine;
 
 /**