@rungs/cli 0.2.0 → 0.3.1

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

@@ -29,8 +29,16 @@ jobs:
 
       # 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.
+      #
+      # Plain `check`, no flags. This said `check --tier full --reporter github`:
+      # `--tier` is not a flag the CLI accepts and `--reporter` does not exist at
+      # all, so the two values were parsed as a *path* and a *tier* — every run
+      # checked a directory named `full` and exited 1 with "no gates registered —
+      # is this a rungs repo?". Shipped in three of five profiles, so every repo
+      # that installed `ci` had a job that failed on every push and blamed the
+      # repo for it (F-030).
       - name: Run gates
-        run: npx @rungs/cli check --tier full --reporter github
+        run: npx @rungs/cli check
 
   # Add a matrix job per package here rather than a workflow per package.
   # A checklist step that creates a file creates N files:

package/modules/ci/module.toml

@@ -1,6 +1,6 @@
 [module]
 name    = "ci"
-version = "1.0.0"
+version = "1.1.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."
 

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

@@ -35,9 +35,15 @@ 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.**
+`land` re-runs each failing gate against the merge base in the throwaway worktree it already has,
+and reports each failure 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.**
+
+Attribution is **per finding, not per gate.** The first implementation compared gate ids, which
+made an already-red gate a blind spot: a branch could add new broken links and land them as
+inherited, because that gate was red either way. Measured on a scratch repo, and fixed the same
+day — a gate you have not fixed does not excuse the new violations of it you bring.
 
 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.*
@@ -62,8 +68,8 @@ 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.
+- **Your worktree is untouched.** `land` does all its work in a throwaway worktree of its own, so
+  whatever you had checked out is still checked out. A refusal costs you nothing to recover from.
 - **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

package/modules/concurrency/module.toml

@@ -1,6 +1,6 @@
 [module]
 name    = "concurrency"
-version = "1.0.0"
+version = "1.2.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."
 

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":
@@ -120,9 +131,23 @@ 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.1.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."
 

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

@@ -25,10 +25,10 @@ mismatch is usually a fragment somebody skipped, not a versioning disagreement.
 rungs check
 ```
 
-Run **every** registered gate. This said `rungs check --tier full`, which selects only gates
-labelled `full` — on a repo whose gates are all `fast`, that is zero of them, and the run reports
-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.
+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.
 

package/package.json

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

package/src/backlog.ts

@@ -56,7 +56,14 @@ export function planArchive(repoRoot: string, backlogRoot = 'docs/backlog'): Arc
   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;
+    // 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');
@@ -70,8 +77,16 @@ export function planArchive(repoRoot: string, backlogRoot = 'docs/backlog'): Arc
         .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}-`));
+        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) {

package/src/check.ts

@@ -79,7 +79,13 @@ export class UnknownTierError extends Error {
   }
 }
 
-export function runGates(repoRoot: string, tier?: string, now = () => Date.now()): GateRun[] {
+/**
+ * `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
@@ -95,6 +101,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 (only && !only.has(g.id)) continue;
     if (tier && !tierSelects(runnerTiers, tier, g.tier)) continue;
 
     const started = now();
@@ -181,7 +188,7 @@ export 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');

package/src/cli.ts

@@ -10,6 +10,7 @@ import { appendLedger, type GateRun, ledgerQuestions, loadRegistry, runGates, Un
 import { applyUpgrade, eject, planUpgrade, PROFILES, readRecord, setupGit } from './lifecycle.ts';
 import { explain, IN_SCOPE as EXPLAINABLE } from './explain.ts';
 import { applyArchive, planArchive } from './backlog.ts';
+import { land, preflight, sessionStart, worktrees } from './concurrency.ts';
 import { existsSync } from 'node:fs';
 import type { DetectResult, Manifest } from './types.ts';
 
@@ -316,6 +317,34 @@ function cmdAdd(names: string[], root: string, dryRun: boolean, harnesses: Harne
     }
     (overrides[modName] ??= {})[param] = rhs.join('=');
   }
+
+  // …and an unknown *name* is refused for the same reason a malformed key is.
+  // The comment above says a dropped `--set` "proceeded with the default and
+  // looked successful"; a mistyped module or parameter did exactly that, and the
+  // echo below then printed `set nosuch.param = 1` as though it had applied
+  // (F-028). The whole module set is loaded here, so the names are checkable —
+  // there was never a reason to trust them.
+  for (const [modName, vals] of Object.entries(overrides)) {
+    const mod = mods.find((m) => m.name === modName);
+    if (!mod) {
+      console.log(
+        c.red(`\n  --set names a module that does not exist: ${modName}`) +
+          c.dim(`\n  Known: ${mods.map((m) => m.name).join(', ')}\n`),
+      );
+      return 1;
+    }
+    for (const k of Object.keys(vals)) {
+      if (!(k in mod.params)) {
+        const known = Object.keys(mod.params);
+        console.log(
+          c.red(`\n  --set names a parameter ${modName} does not have: ${k}`) +
+            c.dim(`\n  ${known.length ? `${modName} takes: ${known.join(', ')}` : `${modName} takes no parameters`}`) +
+            c.dim('\n  `rungs modules --params` lists every parameter and its default.\n'),
+        );
+        return 1;
+      }
+    }
+  }
   const params = resolveParams(mods, overrides, root);
   for (const [m, vals] of Object.entries(overrides)) {
     for (const [k, v] of Object.entries(vals)) console.log(c.dim(`  set ${m}.${k} = ${v}`));
@@ -467,6 +496,56 @@ function cmdRender(root: string, harnesses: Harness[], stamp: string) {
   return 0;
 }
 
+/** The loop commands return lines and a verdict; printing them is the CLI's job. */
+function report(r: { ok: boolean; lines: string[] }): number {
+  console.log();
+  for (const l of r.lines) console.log(`  ${r.ok ? l : c.yellow(l)}`);
+  console.log();
+  return r.ok ? 0 : 1;
+}
+
+/**
+ * `land` verifies the *merged* tree, so it needs the gate runner pointed at a
+ * directory that exists only inside the command. This is the reason the loop is
+ * CLI commands rather than scripts the module writes (ADR-0009).
+ */
+function landRunner(dir: string, only?: ReadonlySet<string>) {
+  const runs = runGates(dir, undefined, undefined, only);
+  const failing = runs.filter((r) => r.status === 'fail' || r.status === 'error');
+  return {
+    pass: runs.filter((r) => r.status === 'pass').length,
+    // `file: message`, so the same broken link in the same file is the same
+    // finding across two runs, and a *new* one is visibly not.
+    failing: failing.map((r) => ({
+      id: r.id,
+      findings: r.findings.map((f) => `${f.file ? `${f.file}: ` : ''}${f.message}`),
+    })),
+  };
+}
+
+function cmdWorktrees(root: string) {
+  const { rows, integration } = worktrees(root);
+  console.log(c.bold(`\nrungs worktrees — merged into ${integration}?\n`));
+  if (!rows.length) {
+    console.log(c.dim('  no linked worktrees. `rungs session start <branch>` creates one.\n'));
+    return 0;
+  }
+  for (const w of rows) {
+    const state = w.merged && w.dirty ? c.red('merged · DIRTY') : w.merged ? c.green('merged · prunable') : c.dim('in flight');
+    console.log(`  ${state.padEnd(28)} ${w.branch.padEnd(30)} ${c.dim(w.path)}`);
+  }
+  const risky = rows.filter((w) => w.merged && w.dirty);
+  const prunable = rows.filter((w) => w.merged && !w.dirty);
+  console.log();
+  if (risky.length) {
+    console.log(c.red(`  ${risky.length} worktree(s) hold uncommitted work on a branch that already landed.`));
+    console.log(c.dim('  That is where work actually gets lost. Commit it somewhere or decide to drop it.'));
+  }
+  if (prunable.length) console.log(c.dim(`  ${prunable.length} prunable. Removing a worktree is your call, not this command's.`));
+  console.log();
+  return 0;
+}
+
 function cmdCheck(root: string, tier: string | undefined, stamp: string) {
   let runs: GateRun[];
   try {
@@ -718,6 +797,10 @@ const COMMANDS: [usage: string, blurb: string][] = [
   ['setup git [path]', 'install the merge drivers .gitattributes names'],
   ['modules', 'list the module set and audit the manifests'],
   ['backlog archive [path]', 'move finished items to archive/, repointing every link'],
+  ['session start <branch>', 'cut a branch and worktree from the last verified merge'],
+  ['preflight [path]', 'did the integration branch change files you changed?'],
+  ['land <branch>', 'merge → verify the merged tree → advance, or refuse and park it'],
+  ['worktrees [path]', 'which worktrees are merged, prunable, or merged and still dirty'],
 ];
 
 /** Every flag the parser honours. A flag absent here is a flag nobody can find. */
@@ -831,6 +914,19 @@ switch (cmd) {
   case 'eject':
     process.exit(cmdEject(resolve(args[0] ?? process.cwd()), flags.has('--dry-run')));
   case 'setup': {
+    // The path is `args[1]`, *after* the subcommand — so an omitted `git` put the
+    // path into the subcommand slot, where it was discarded, and `setup` then
+    // wrote git config into the current directory while reporting success about
+    // the repo you named (F-027). `backlog` had refused an unknown subcommand
+    // since it shipped; this one accepted anything and exited 0. The asymmetry
+    // between the two subcommand-taking commands was the whole bug.
+    if (args[0] !== 'git') {
+      console.log(
+        c.red(`\n  unknown: rungs setup ${args[0] ?? ''}`.trimEnd()) +
+          c.dim('\n  The only subcommand is `git`, and the path comes after it: `rungs setup git [path]`.\n'),
+      );
+      process.exit(1);
+    }
     const r = setupGit(resolve(args[1] ?? process.cwd()), flags.has('--dry-run'));
     console.log(
       r.drivers.length
@@ -843,6 +939,19 @@ switch (cmd) {
   }
   case 'render':
     process.exit(cmdRender(resolve(args[0] ?? process.cwd()), HARNESSES, STAMP));
+  case 'session': {
+    if (args[0] !== 'start') {
+      console.log(c.red(`\n  unknown: rungs session ${args[0] ?? ''}`.trimEnd()) + c.dim('\n  The only subcommand is `start`: `rungs session start <branch> [path]`.\n'));
+      process.exit(1);
+    }
+    process.exit(report(sessionStart(process.cwd(), args[1], args[2], flags.has('--dry-run'))));
+  }
+  case 'preflight':
+    process.exit(report(preflight(resolve(args[0] ?? process.cwd()))));
+  case 'land':
+    process.exit(report(land(process.cwd(), args[0], landRunner, flags.has('--dry-run'))));
+  case 'worktrees':
+    process.exit(cmdWorktrees(resolve(args[0] ?? process.cwd())));
   case 'add': {
     const target = flags.has('--into') ? args[args.length - 1] : process.cwd();
     const names = flags.has('--into') ? args.slice(0, -1) : args;