mandrel 1.77.0 → 1.78.0

package/.agents/scripts/sync-claude-commands.js

@@ -23,10 +23,22 @@
  * environment (CLI, IDE, GUI, web, SDK). On a machine that previously synced
  * the plugin tree, this script reaps it on the next run (see reapPluginTree).
  *
- * Only top-level .md files are projected. The `.agents/workflows/helpers/`
- * subdirectory holds path-included modules (e.g. epic-code-review, epic-retro)
- * that parent workflows read by relative path — they are intentionally **not**
- * exposed as commands, so helpers/ is skipped.
+ * Top-level .md files project flat (`/<name>`). The
+ * `.agents/workflows/helpers/` subdirectory holds path-included modules
+ * (e.g. epic-code-review, epic-retro) that parent workflows read by
+ * relative path — they are intentionally **not** exposed as commands, so
+ * helpers/ is skipped.
+ *
+ * The `.agents/workflows/loops/` subdirectory is the **one** exception to
+ * the skip-subdirectories rule (Story #4289, Epic #4284). Each loop unit
+ * there projects to `.claude/commands/loops/<name>.md`, preserving the
+ * subpath so Claude Code namespaces it as `/loops:<name>` (matching Claude
+ * Code's subdirectory-command namespacing). Hosts that flatten
+ * subdirectory commands surface the same file as the flat fallback
+ * `/loops-<name>` (i.e. `loops-<name>` in the command tree) — the
+ * projection writes the namespaced path; the flat form is the documented
+ * host-side fallback, not a second on-disk copy. No subdirectory other
+ * than `loops/` is recursed.
  *
  * Usage:  node .agents/scripts/sync-claude-commands.js
  */
@@ -127,43 +139,111 @@ function reapPluginTree() {
 reapPluginTree();
 fs.mkdirSync(DEST_DIR, { recursive: true });
 
-// Only sync top-level .md files. Subdirectories (notably helpers/) are
-// ignored — they contain path-included modules, not slash commands.
+// The only namespaced subdirectory we recurse. Every other subdirectory
+// (notably helpers/) is skipped — those hold path-included modules, not
+// slash commands. Loop units under workflows/loops/ project into
+// .claude/commands/loops/ so Claude Code namespaces them as /loops:<name>
+// (Story #4289).
+const LOOPS_NS = 'loops';
+
+// Top-level .md files project flat. Subdirectories are skipped here and the
+// only one re-introduced is loops/ (handled by enumerateLoopUnits below).
 const isTopLevelWorkflow = (entry) =>
   entry.isFile() && entry.name.endsWith('.md');
 
+/**
+ * `README.md` (any case) under `loops/` is namespace documentation, not a
+ * loop unit — it carries no `loop:` frontmatter and must not project as a
+ * `/loops:README` command. Exclude it from the loop-unit enumeration (this
+ * mirrors `check-loop-units.js#isLoopUnitFile`, which excludes it from the
+ * lint gate).
+ *
+ * @param {import('node:fs').Dirent} entry
+ * @returns {boolean}
+ */
+const isLoopUnit = (entry) =>
+  isTopLevelWorkflow(entry) && entry.name.toLowerCase() !== 'readme.md';
+
+/**
+ * Enumerate the loop units under a source dir's `loops/` subdirectory.
+ * Returns entries keyed by the namespaced relative path
+ * (`loops/<name>.md`) so they never collide with a flat top-level command
+ * of the same basename and so the reap can track them distinctly. The
+ * directory's `README.md` is skipped — it is documentation, not a command.
+ *
+ * @param {string} dir — a workflows source root (payload or local).
+ * @returns {Array<{dir: string, name: string, rel: string}>}
+ */
+function enumerateLoopUnits(dir) {
+  const loopsDir = path.join(dir, LOOPS_NS);
+  if (!dirExists(loopsDir)) return [];
+  return fs
+    .readdirSync(loopsDir, { withFileTypes: true })
+    .filter(isLoopUnit)
+    .map((e) => ({
+      dir,
+      name: e.name,
+      rel: `${LOOPS_NS}/${e.name}`,
+    }));
+}
+
 // Enumerate sources: payload first, then local (if it exists). Payload wins
-// on basename collision — a consumer must not silently shadow a core command.
+// on relative-path collision — a consumer must not silently shadow a core
+// command. Each entry carries its destination-relative path (`rel`): a bare
+// basename for flat top-level commands, `loops/<name>.md` for loop units.
 const SRC_DIRS = [PAYLOAD_SRC, LOCAL_SRC].filter(dirExists);
 
-/** @type {Array<{dir: string, name: string}>} */
-const entries = SRC_DIRS.flatMap((dir) =>
-  fs
+/** @type {Array<{dir: string, name: string, rel: string}>} */
+const entries = SRC_DIRS.flatMap((dir) => [
+  ...fs
     .readdirSync(dir, { withFileTypes: true })
     .filter(isTopLevelWorkflow)
-    .map((e) => ({ dir, name: e.name })),
-);
+    .map((e) => ({ dir, name: e.name, rel: e.name })),
+  ...enumerateLoopUnits(dir),
+]);
 
-// Collision policy: payload wins, warn on a shadowed local file.
-const byName = new Map();
+// Collision policy: payload wins, warn on a shadowed local file. Keyed by the
+// destination-relative path so a flat `foo.md` and a `loops/foo.md` are
+// distinct entries.
+const byRel = new Map();
 for (const e of entries) {
-  if (byName.has(e.name)) {
-    Logger.warn(`  shadowed  ${e.name} (local copy ignored; payload wins)`);
+  if (byRel.has(e.rel)) {
+    Logger.warn(`  shadowed  ${e.rel} (local copy ignored; payload wins)`);
     continue;
   }
-  byName.set(e.name, e);
+  byRel.set(e.rel, e);
 }
 
 // sourceSet drives the orphan-reap: any existing command not in this set is
-// removed. Local-projected commands are included, so they survive the reap.
-const sourceSet = new Set(byName.keys());
+// removed. Keyed by destination-relative path so loop units are reaped from
+// the loops/ namespace and flat commands from the root.
+const sourceSet = new Set(byRel.keys());
 
-const existing = fs.readdirSync(DEST_DIR).filter((f) => f.endsWith('.md'));
+/**
+ * List the destination-relative paths of every projected command currently
+ * on disk: flat `*.md` at the root plus `loops/*.md` in the namespace.
+ *
+ * @returns {string[]}
+ */
+function listExistingCommands() {
+  const flat = fs
+    .readdirSync(DEST_DIR)
+    .filter((f) => f.endsWith('.md'))
+    .map((f) => f);
+  const loopsDest = path.join(DEST_DIR, LOOPS_NS);
+  const loops = dirExists(loopsDest)
+    ? fs
+        .readdirSync(loopsDest)
+        .filter((f) => f.endsWith('.md'))
+        .map((f) => `${LOOPS_NS}/${f}`)
+    : [];
+  return [...flat, ...loops];
+}
 
-for (const file of existing) {
-  if (!sourceSet.has(file)) {
-    fs.unlinkSync(path.join(DEST_DIR, file));
-    Logger.info(`  removed  ${file} (no longer in workflows)`);
+for (const rel of listExistingCommands()) {
+  if (!sourceSet.has(rel)) {
+    fs.unlinkSync(path.join(DEST_DIR, rel));
+    Logger.info(`  removed  ${rel} (no longer in workflows)`);
   }
 }
 
@@ -173,15 +253,18 @@ for (const file of existing) {
 // Parallelised so the ~30-file sync doesn't serialise on per-file fs latency
 // (noticeable on Windows where each syscall pays a larger fixed cost).
 let synced = 0;
-const resolvedEntries = Array.from(byName.values());
+const resolvedEntries = Array.from(byRel.values());
 await Promise.all(
-  resolvedEntries.map(async ({ dir, name }) => {
+  resolvedEntries.map(async ({ dir, rel }) => {
     const isLocal = dir === LOCAL_SRC;
     const header = isLocal ? LOCAL_HEADER : HEADER;
-    const content = await fs.promises.readFile(path.join(dir, name), 'utf8');
-    const dest = path.join(DEST_DIR, name);
+    const content = await fs.promises.readFile(path.join(dir, rel), 'utf8');
+    const dest = path.join(DEST_DIR, rel);
     const target = applyHeader(content, header);
 
+    // Ensure the namespace subdirectory exists before writing a loop unit.
+    await fs.promises.mkdir(path.dirname(dest), { recursive: true });
+
     // Skip write if content is already identical (avoid noisy git diffs).
     // Use try/catch over existsSync+readFile so we only pay one syscall.
     try {
@@ -193,7 +276,7 @@ await Promise.all(
 
     await fs.promises.writeFile(dest, target, 'utf8');
     synced++;
-    Logger.info(`  synced   ${name}`);
+    Logger.info(`  synced   ${rel}`);
   }),
 );
 

package/.agents/scripts/update-maintainability-baseline.js

@@ -8,6 +8,18 @@
  * resolution, envelope assembly, and persistence flows through the unified
  * service.
  *
+ * Story #4293: the CLI no longer injects a bespoke maintainability scorer.
+ * It now lets `refreshBaseline` resolve the canonical default scorer
+ * (`buildDefaultMaintainabilityScorer`) the same way `update-crap-baseline.js`
+ * and `update-coverage-baseline.js` route through their canonical defaults.
+ * The previously-injected `buildMaintainabilityScorer` was a stale copy of the
+ * canonical scorer that never received the `ignoreGlobs` fix on its diff-scope
+ * branch, so an ignored-but-changed file (e.g. one matched by
+ * `config-settings-schema*.js` or a consumer's `seed.mjs`) leaked into `rows`
+ * and dragged `rollup["*"].min` below the maintainability floor. The canonical
+ * default scorer applies the ignore filter on BOTH the full-scope walk and the
+ * diff-scope branch, eliminating the divergence at the source.
+ *
  * Surface:
  *
  *   - `--diff-scope <ref>` (or `--diff-scope=<ref>`): explicitly scope the
@@ -18,13 +30,10 @@
  *     Operators wanting a full rewrite must pass `--full-scope` (added by
  *     Task #2214; see that Task's notes for the cut-over).
  *
- * The scoring step (escomplex / typhonjs maintainability index) is
- * injected as a scorer function via the service's `opts.scorer` seam.
  * Full-scope refreshes (`scope.mode === 'full'`) walk every configured
  * target directory; diff/explicit refreshes score only the files the
- * service hands in. This keeps the manual CLI byte-identical (per
- * AC-3 — see Task #2212's byte-identity test) to whatever code path
- * story-close would have produced for the same scope.
+ * service hands in. Both paths drop `ignoreGlobs`-listed files via the
+ * canonical default scorer.
  */
 
 // Fail-fast if the framework's runtime deps are not installed — must be the
@@ -33,16 +42,10 @@
 import './lib/runtime-deps/ensure-installed.js';
 import path from 'node:path';
 import { parseDiffScopeFlag } from './lib/baselines/diff-scope-cli.js';
-import { filterExcludedRows } from './lib/baselines/kinds/maintainability.js';
 import { refreshBaseline } from './lib/baselines/refresh-service.js';
 import { getBaselineEpsilon } from './lib/config/quality.js';
-import {
-  getBaselines,
-  getQuality,
-  resolveConfig,
-} from './lib/config-resolver.js';
+import { getBaselines, resolveConfig } from './lib/config-resolver.js';
 import { Logger } from './lib/Logger.js';
-import { calculateAll, scanDirectory } from './lib/maintainability-utils.js';
 
 /**
  * Parse `--full-scope` (boolean opt-out flag).
@@ -54,60 +57,6 @@ function parseFullScopeFlag(argv = []) {
   return argv.includes('--full-scope');
 }
 
-/**
- * Build the per-kind scorer the service will invoke. The scorer receives
- * `(files, { fullScope })`:
- *
- *   - `fullScope === true`: ignore `files`, walk every configured target
- *     directory, score every supported source file, return rows.
- *   - `fullScope === false`: `files` is the resolved (diff or explicit)
- *     scope. Score only those that fall under a configured target
- *     directory; rows outside that set are dropped (the service / writer
- *     preserves their prior-on-disk entries verbatim).
- *
- * The scorer is `cwd`-aware: the service passes its `cwd` through so all
- * path normalisation stays consistent with diff-scope derivation.
- */
-function buildMaintainabilityScorer({ targetDirs, ignoreGlobs = [], logger }) {
-  return async function maintainabilityScorer(files, opts) {
-    const cwd = opts?.cwd ?? process.cwd();
-    let absPaths;
-    if (opts?.fullScope) {
-      absPaths = [];
-      for (const dir of targetDirs) {
-        const abs = path.isAbsolute(dir) ? dir : path.resolve(cwd, dir);
-        logger.info(`[Maintainability] Scanning ${dir}...`);
-        scanDirectory(abs, absPaths, { cwd, ignoreGlobs });
-      }
-    } else {
-      // Files come in as canonical POSIX repo-relative paths from the
-      // service. Resolve to absolute paths for the scorer, but only keep
-      // the ones that fall under a configured target dir — rows outside
-      // those roots are the gate's responsibility, not the baseline's.
-      const targetAbsDirs = targetDirs.map((dir) =>
-        path.isAbsolute(dir) ? dir : path.resolve(cwd, dir),
-      );
-      absPaths = [];
-      for (const rel of files ?? []) {
-        const abs = path.resolve(cwd, rel);
-        const underTarget = targetAbsDirs.some(
-          (root) => abs === root || abs.startsWith(`${root}${path.sep}`),
-        );
-        if (underTarget) absPaths.push(abs);
-      }
-    }
-
-    logger.info(
-      `[Maintainability] Calculating scores for ${absPaths.length} files...`,
-    );
-    const scores = await calculateAll(absPaths);
-    const rows = Object.entries(scores).map(([p, mi]) => ({ path: p, mi }));
-    // Story #2467 / Task #2494: drop files the escomplex kernel can't parse
-    // so they stop landing as `mi: 0` phantom entries in the baseline.
-    return filterExcludedRows(rows);
-  };
-}
-
 async function main() {
   const argv = process.argv.slice(2);
   const diffScopeRef = parseDiffScopeFlag(argv);
@@ -120,9 +69,6 @@ async function main() {
   }
 
   const config = resolveConfig();
-  const miQuality = getQuality(config).maintainability;
-  const targetDirs = miQuality.targetDirs;
-  const ignoreGlobs = miQuality.ignoreGlobs ?? [];
   const baselinePath = getBaselines(config).maintainability.path;
   const absBaselinePath = path.isAbsolute(baselinePath)
     ? baselinePath
@@ -140,21 +86,18 @@ async function main() {
     );
   }
 
-  const scorer = buildMaintainabilityScorer({
-    targetDirs,
-    ignoreGlobs,
-    logger: Logger,
-  });
-
   // Task #2214 (Epic #2173, AC-2): flag-omission now defaults to
   // diff-scope. The pre-migration default was a full regenerate; operators
   // wanting that behaviour must now pass `--full-scope` explicitly. This is
   // a deliberate breaking CLI behaviour change — see docs/CHANGELOG.md.
+  //
+  // Story #4293: no `scorer` is injected — the service resolves the canonical
+  // default maintainability scorer, which applies `ignoreGlobs` on both the
+  // full-scope walk and the diff-scope branch.
   const refreshOpts = {
     kind: 'maintainability',
     writePath: absBaselinePath,
     epsilon,
-    scorer,
   };
   if (fullScope) {
     refreshOpts.fullScope = true;

package/.agents/workflows/loops/README.md

@@ -0,0 +1,65 @@
+# Loop units (`.agents/workflows/loops/`)
+
+A **loop unit** is a markdown file that defines one unit of *recurring* work
+with a checkable definition of done. Each file's leading YAML frontmatter
+carries a `loop:` block — a cadence, a goal, an optional `verify` oracle, a
+round cap, and an exhaustion policy — validated against
+[`.agents/schemas/loop-unit.schema.json`](../../schemas/loop-unit.schema.json)
+by `node .agents/scripts/check-loop-units.js` (wired into `npm run lint`).
+
+This directory is the **one** namespaced exception to the flat slash-command
+projection. Files here project to `.claude/commands/loops/<name>.md` and are
+invoked as the namespaced `/loops:<name>` command (flat fallback
+`/loops-<name>` on hosts that flatten subdirectory commands). Every other
+top-level workflow projects flat as `/<name>`; `helpers/` is not projected at
+all.
+
+## What a loop unit is — and is not
+
+A loop unit ships **content and contract**, not a runner. It declares:
+
+- **the action** — what one round does;
+- **the goal** — the standing objective each round works toward;
+- **the `verify` oracle** — the runnable check that proves a round is complete
+  (required for `self-paced` cadence, optional for `interval` / `cron`); and
+- **the observability / escalation contract** — the `maxRounds` backstop, the
+  `onExhaust` policy, and the explicit "stop & escalate" conditions in the body.
+
+It does **not** ship the loop driver. **Cadence and iteration are owned by the
+host** — Claude Code's built-in `/loop` (self-paced or interval) and
+`/schedule` (cron). Mandrel deliberately ships **no** `/goal` or `/loop`
+runner of its own. The full rationale, and why this division exists, is fixed
+in the ADR:
+
+> [`docs/decisions/loop-units-division-of-labor.md`](../../../docs/decisions/loop-units-division-of-labor.md)
+> — *Loop units: mandrel owns content + oracle + contract; the host owns
+> cadence + iteration; no runner shipped.*
+
+Read that ADR before adding a runner, a scheduler, or a `/goal` command to the
+framework — the decision to **not** build one is deliberate.
+
+## Cadence → host mapping
+
+| Cadence       | `verify` | Driven by                         | Starter unit                                                   |
+| ------------- | -------- | --------------------------------- | -------------------------------------------------------------- |
+| `self-paced`  | required | `/loop` (no interval)             | [`fix-failing-tests.md`](fix-failing-tests.md) — red → green   |
+| `interval`    | optional | `/loop <interval>` (e.g. `/loop 5m`) | [`watch-ci.md`](watch-ci.md) — poll a PR's checks          |
+| `cron`        | optional | `/schedule` (cron-driven)         | [`nightly-audit.md`](nightly-audit.md) — nightly audit sweep   |
+
+A `self-paced` unit **must** carry a `verify` oracle because nothing external
+paces it — the oracle is the only signal that tells the host when to stop.
+`interval` and `cron` units are paced by an external scheduler, so a
+terminating oracle is optional; they observe, report, and yield each tick.
+
+## Authoring a new loop unit
+
+1. Create `.agents/workflows/loops/<name>.md` with a `loop:` frontmatter block
+   (`cadence` + `goal` required; add `verify` for `self-paced`).
+2. Give it a `description:` so it shows up in the generated catalog
+   ([`.agents/docs/workflows.md`](../../docs/workflows.md), **Loops namespace**).
+3. Body sections: **Action** (what one round does), **Goal & done-signal** (the
+   objective and the oracle/stop check), **Stop & escalate** (when to hand back
+   rather than loop).
+4. Run `node .agents/scripts/check-loop-units.js` (or `npm run lint`) to
+   validate the frontmatter, then `npm run sync:commands` to project it to
+   `/loops:<name>` and `npm run docs:gen` to refresh the catalog.

package/.agents/workflows/loops/fix-failing-tests.md

@@ -0,0 +1,74 @@
+---
+description: >-
+  Self-paced convergence loop that drives a red test suite to green. Each round
+  reads the latest failure, applies the smallest fix, and re-runs the verify
+  oracle (`npm test`); the loop terminates when the oracle exits 0. The host
+  (`/loop`) owns iteration and pacing — mandrel supplies the action, the goal,
+  and the terminating oracle.
+loop:
+  cadence: self-paced
+  goal: >-
+    Drive the project's test suite from red to green by fixing the root cause of
+    each failure, one round at a time, until the verify oracle passes.
+  verify: npm test
+  maxRounds: 10
+  onExhaust: hand-back
+---
+
+# /loops:fix-failing-tests — drive a red suite to green
+
+A **self-paced convergence loop**. The host (`/loop` with no interval) decides
+when to run the next round; this unit supplies the action each round performs,
+the standing goal, and the runnable `verify` oracle that tells the host when to
+stop. When `npm test` exits 0, the goal is met and the loop terminates.
+
+> **Scope.** This loop fixes the **root cause** of failing tests. It does not
+> delete, skip, `.only`, or weaken assertions to force a green bar — that is an
+> escalation condition, not a round (see **Stop & escalate** below).
+
+## Action
+
+Each round:
+
+1. **Read the latest failure.** Run the verify oracle (`npm test`) and read the
+   first failing assertion — name, file, and the expected-vs-actual diff. Fix
+   one failure cluster per round; do not fan out across unrelated failures in a
+   single round.
+2. **Diagnose the root cause.** Decide whether the failure is in the production
+   code under test or in the test's own setup/expectation. Prefer the
+   smallest change that makes the assertion honest — fix the code when the test
+   encodes the intended contract; fix the test only when it asserts the wrong
+   thing and you can state why in one sentence.
+3. **Apply the smallest fix.** Make the minimal edit that addresses the
+   diagnosed cause. Avoid speculative refactors — convergence depends on each
+   round changing exactly one thing.
+4. **Re-run the oracle.** Run `npm test` again. A reduced failure count is
+   progress; a new failure introduced by the fix means the diagnosis was wrong
+   — revert and re-diagnose rather than stacking another fix on top.
+
+## Goal & done-signal
+
+- **Goal:** the test suite passes — every test green, no skipped-to-hide
+  failures.
+- **Done-signal (the oracle):** `npm test` exits 0. This is the single
+  terminating check the host `/loop` evaluates after each round. When it
+  passes, stop — the loop is complete.
+- **Backstop:** `maxRounds: 10`. If the oracle is still red after ten rounds,
+  the `onExhaust: hand-back` policy returns control to the caller with a
+  summary rather than looping indefinitely.
+
+## Stop & escalate
+
+Stop the loop and hand back (do **not** keep iterating) when:
+
+- **The same failure survives the same class of fix twice.** Per the
+  anti-thrashing protocol, a repeated fix against an unchanged failure means
+  the diagnosis is wrong — stop and report what you tried.
+- **A fix would weaken the contract.** If the only way to make the bar green is
+  to delete a test, add `.skip` / `.only`, or relax an assertion to match buggy
+  behaviour, that is a product decision, not a loop round. Stop and surface it.
+- **The failure is environmental, not a code defect** (missing service, absent
+  credential, a flaky timing-dependent test). The loop cannot converge on an
+  external cause — report the blocker so the operator can resolve it.
+- **`maxRounds` is reached with the oracle still red.** Hand back a summary of
+  the remaining failures and the rounds spent.

package/.agents/workflows/loops/nightly-audit.md

@@ -0,0 +1,71 @@
+---
+description: >-
+  Cron maintenance loop that runs a nightly audit sweep over the repository and
+  files actionable findings. Each run executes the audit workflows and routes
+  the results; the host (`/schedule` or a cron-driven `/loop`) owns the cadence.
+  verify is optional for a cron loop — the scheduler owns iteration, so this
+  unit ships the action and goal, not a terminating oracle.
+loop:
+  cadence: cron
+  goal: >-
+    Keep the repository's standing health surfaced by running the audit sweep on
+    a nightly schedule and turning each fresh finding into an actionable, deduped
+    record so regressions are caught within a day rather than at release time.
+  maxRounds: 30
+  onExhaust: report
+---
+
+# /loops:nightly-audit — scheduled maintenance audit sweep
+
+A **cron maintenance loop**. The host (`/schedule`, or a cron-driven `/loop`)
+owns the cadence and fires this unit once per scheduled window — typically
+overnight. Because the scheduler owns iteration, this unit carries **no
+`verify` oracle**: per the loop-unit schema, `verify` is required only for
+`self-paced` cadence and optional for `interval` / `cron`. Each run is a single
+sweep that observes, records, and yields until the next scheduled tick.
+
+## Action
+
+Each scheduled run:
+
+1. **Run the audit sweep.** Execute the relevant audit workflows for the repo
+   (`/audit-security`, `/audit-clean-code`, `/audit-dependencies`,
+   `/audit-quality`, and any others the project relies on). Each audit writes a
+   structured `temp/audits/audit-*-results.md` report — that is the canonical
+   artifact this loop consumes, not free-form prose.
+2. **Diff against the prior night.** Compare the fresh findings against the last
+   sweep's reports and against already-open Issues. A finding seen before is
+   not new signal; only genuinely fresh or regressed findings warrant a record.
+3. **Route fresh findings.** Hand the new findings to `/audit-to-stories`, which
+   deduplicates against existing Issues by fingerprint and either chains into
+   `/plan` or opens standalone Stories. Do not open raw duplicate Issues —
+   dedup is the loop's job, not the operator's.
+4. **Report and yield.** Emit a short digest (sweeps run, new findings, Issues
+   opened or updated) and return control to the scheduler, which sleeps until
+   the next cron window.
+
+## Goal & done-signal
+
+- **Goal:** the repository's health regressions are caught and turned into
+  actionable, deduplicated records within a day, without a human remembering to
+  run the audits by hand.
+- **Done-signal:** the nightly sweep completed and every fresh finding has been
+  routed to a record (or explicitly judged a non-finding). A cron loop has no
+  self-evaluated oracle — the scheduler owns whether the loop runs again; this
+  unit simply finishes the night's sweep and yields.
+- **Backstop:** `maxRounds: 30`. Roughly a month of nightly runs;
+  `onExhaust: report` emits a final digest and stops so a long-lived schedule
+  is renewed deliberately rather than running unbounded.
+
+## Stop & escalate
+
+- **An audit cannot run** (a required tool is missing, the audit harness errors,
+  the working tree is dirty in a way that invalidates the sweep). Report the
+  failure for that audit and continue with the others — do not abort the whole
+  night because one audit broke.
+- **A finding is high-severity and time-sensitive** (an exposed secret, a
+  critical CVE reachable in production). Surface it loudly in the digest rather
+  than letting it sit as one row among many — a nightly cadence is too slow for
+  an actively-exploitable finding.
+- **`maxRounds` is reached.** Emit a final digest (`onExhaust: report`) so the
+  operator can renew or retire the schedule deliberately.

package/.agents/workflows/loops/watch-ci.md

@@ -0,0 +1,68 @@
+---
+description: >-
+  Interval watch loop that polls a pull request's CI checks until they settle.
+  Each round runs `gh pr checks` and reports the delta; the host (`/loop 5m`)
+  owns the cadence and re-invokes the unit on its schedule. verify is optional
+  for an interval loop — the externally-scheduled host owns iteration, so this
+  unit ships the action and goal, not a terminating oracle.
+loop:
+  cadence: interval
+  goal: >-
+    Keep an eye on the current pull request's required CI checks each interval,
+    surfacing the first failed or stuck check the moment it appears so a human
+    can act before the checks finish.
+  maxRounds: 60
+  onExhaust: report
+---
+
+# /loops:watch-ci — poll a PR's checks until they settle
+
+An **interval watch loop**. The host (`/loop <interval> /loops:watch-ci`, e.g.
+`/loop 5m …`) owns the cadence and re-runs this unit on each tick. Because the
+host schedules iteration externally, this unit carries **no `verify` oracle** —
+per the loop-unit schema, `verify` is required only for `self-paced` cadence and
+optional for `interval` / `cron`. The unit's job each round is to observe and
+report, not to converge.
+
+## Action
+
+Each interval:
+
+1. **Read the current check state.** Run `gh pr checks` for the PR under watch
+   (the host supplies the PR number, or it is inferred from the current
+   branch's open PR). Capture the per-check status: pending, passed, or failed.
+2. **Compute the delta since last round.** Compare against the prior round's
+   snapshot. A check that flipped `pending → failed` is the headline; a check
+   that flipped `pending → passed` is progress.
+3. **Surface failures immediately.** On the first failed or cancelled required
+   check, report it — name the check, link the run, and quote the first error
+   line if cheaply available — so a human can act before the rest of the matrix
+   finishes. Do not wait for the whole suite to settle to raise a red check.
+4. **Report and yield.** Emit a one-line status summary
+   (`N passed, M pending, K failed`) and return control to the host, which
+   sleeps until the next interval.
+
+## Goal & done-signal
+
+- **Goal:** the operator learns about a CI failure on the watched PR as early as
+  the polling interval allows, and knows when all required checks have gone
+  green.
+- **Done-signal:** all required checks have a terminal status (every check
+  passed, or at least one has failed). An interval loop has no self-evaluated
+  oracle — the host stops the loop when the operator cancels it, when a failure
+  is surfaced and acted on, or when `maxRounds` is reached.
+- **Backstop:** `maxRounds: 60`. At a 5-minute interval that is ~5 hours of
+  watching; `onExhaust: report` emits a final status and stops rather than
+  polling forever on a wedged check.
+
+## Stop & escalate
+
+- **A required check failed.** Surface it and let the operator decide whether to
+  keep watching the remaining checks or stop. A failed required check is the
+  signal the watch existed to catch.
+- **The PR cannot be resolved** (no open PR for the branch, `gh` not
+  authenticated, the PR was merged or closed out from under the watch). Report
+  the condition and stop — there is nothing left to watch.
+- **`maxRounds` is reached with checks still pending.** Emit a final summary of
+  the stuck checks (`onExhaust: report`) so the operator can investigate the
+  wedged run.

package/docs/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.78.0](https://github.com/dsj1984/mandrel/compare/mandrel-v1.77.0...mandrel-v1.78.0) (2026-06-24)
+
+
+### Added
+
+* Epic [#4284](https://github.com/dsj1984/mandrel/issues/4284) ([#4297](https://github.com/dsj1984/mandrel/issues/4297)) ([0f7c543](https://github.com/dsj1984/mandrel/commit/0f7c543e1ceb1c38ac425c388e338e3bfaaec49e))
+
+
+### Fixed
+
+* **baselines:** apply ignoreGlobs in the maintainability baseline CLI diff-scope branch (refs [#4293](https://github.com/dsj1984/mandrel/issues/4293)) ([#4294](https://github.com/dsj1984/mandrel/issues/4294)) ([c0c7dd5](https://github.com/dsj1984/mandrel/commit/c0c7dd5948314800e5a9d5808fb5eb0b01b09833))
+* **close-validation:** treat biome "No files were processed" as a clean format-gate skip (refs [#4292](https://github.com/dsj1984/mandrel/issues/4292)) ([#4295](https://github.com/dsj1984/mandrel/issues/4295)) ([bf6840d](https://github.com/dsj1984/mandrel/commit/bf6840dd69abbece4eb221797e6432519b6614a0))
+
+
+### Changed
+
+* **github-provider:** unify the two divergent withTransientRetry into one canonical primitive (refs [#4298](https://github.com/dsj1984/mandrel/issues/4298)) ([#4299](https://github.com/dsj1984/mandrel/issues/4299)) ([e5668dc](https://github.com/dsj1984/mandrel/commit/e5668dcca73b37c37d38e52e1eb8d2930a0e1790))
+
 ## [1.77.0](https://github.com/dsj1984/mandrel/compare/mandrel-v1.76.0...mandrel-v1.77.0) (2026-06-24)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mandrel",
-  "version": "1.77.0",
+  "version": "1.78.0",
   "description": "Claude Code-first opinionated workflow framework: instructions, personas, skills, and SDLC workflows that govern AI coding assistants.",
   "files": [
     ".agents/",