@rungs/cli 0.1.3 → 0.2.0

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.2.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,182 @@
+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) {
+    if (/README\.md$/i.test(rel) || /TEMPLATE\.md$/i.test(rel)) 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);
+      const unfinished = children.filter((c) => {
+        const f = items.find((i) => i.includes(`${c}-`));
+        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,50 @@ export function loadRegistry(repoRoot: string): { runner: any; gates: RegistryGa
   return { runner: raw.runner ?? {}, gates: raw.gates ?? [] };
 }
 
+/**
+ * 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;
+  }
+}
+
 export function runGates(repoRoot: string, tier?: string, now = () => Date.now()): GateRun[] {
-  const { gates } = loadRegistry(repoRoot);
+  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 +95,7 @@ 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 (tier && !tierSelects(runnerTiers, tier, g.tier)) continue;
 
     const started = now();
     let status: Status = 'pass';
@@ -124,7 +166,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);
@@ -157,7 +199,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 +219,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;
 
 /**