mandrel 1.76.0 → 1.78.0

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/skills/core/epic-plan-decompose-author/SKILL.md

@@ -206,6 +206,7 @@ They are NOT top-level ticket fields.
 
 - **slug**: MUST be hyphen-case (`^[a-z0-9][a-z0-9-]*$`). Do not use underscores.
 - **goal** (in body string): One sentence stating WHY this Story exists within the Epic.
+- **reason_to_exist** (REQUIRED, encoded in the body `<!-- meta: {...} -->` comment — NOT a top-level ticket field): One sentence stating the single coherent reason this Story exists, distinct from the broader `goal` prose. Every Story MUST carry a non-empty `reason_to_exist`; it is the machine-checkable form of the cohesion rule (**one Story = one coherent change with one reason to exist**). The `epic-plan-consolidate` critic flags any Story whose body carries no non-empty reason, and the sizing validator (`ticket-validator-sizing.js`) emits a deterministic **soft** `missing-reason-to-exist` finding as the runtime backstop. Encode it as `<!-- meta: {"reason_to_exist": "..."} -->`.
 - **changes** (in body string): Each entry is an object `{ path, assumption }` where `assumption` is one of `creates | refactors-existing | deletes`. The Phase 8 validator probes the base branch for every declared path and rejects the decompose when the declared assumption contradicts reality: `creates` against an existing path is an error, `refactors-existing` / `deletes` against a missing path is an error. Use `refactors-existing` for in-place edits to a file already on `main`; `creates` for net-new files; `deletes` for removals. Acceptable path shapes include explicit files (`src/components/Foo.tsx`), glob patterns (`tests/e2e/*.spec.ts`, `**/*.astro`), and module identifiers that resolve to files.
 - **references** (in body string, optional): Object-form entries `{ path, assumption: "exists" }` for paths the Story **reads** but does not modify (test fixtures it relies on, sibling modules it imports, feature files it scans). The validator probes these like `changes` and rejects the decompose when an `exists` path is absent on the base branch. Use this list to make read-dependencies explicit so a hallucinated or stale assumption surfaces at planning time rather than execution time.
 - **NEW-FILE CONTRACT (must-follow)**: Any path the Story references in `goal`, `acceptance`, or `verify` that does **not** already exist on `main` MUST also appear in the same Story's `changes` array with `assumption: "creates"`. The freshness validator probes `main` for every referenced code path and rejects the decompose when a missing path is absent from `changes` — even when the Story is the one authoring the file. Example: a Story creating `tests/lib/foo.test.js` whose `verify` runs `node --test tests/lib/foo.test.js` MUST include `{ "path": "tests/lib/foo.test.js", "assumption": "creates" }` in `changes`, otherwise the validator emits a freshness miss and the decompose round trips for a re-emit.
@@ -266,10 +267,11 @@ Declaring `wide` with a non-empty reason **lifts the `hardFiles` rejection** —
 
 #### BINDING ACCEPTANCE vs ADVISORY CHANGES (authoring altitude)
 
-`acceptance[]` and `verify[]` are the **binding contract** the executor MUST satisfy — they are the sole definition of "done." `changes[]` and `references[]` are an **advisory implementation sketch**: your best prediction of the file footprint, which the executor is permitted to revise when the real codebase diverges from the sketch. Author at that altitude:
+The canonical altitude + New-File Contract wording is single-sourced in `AUTHORING_ALTITUDE_GUIDANCE` in `ticket-validator-sizing.js` (Story #4272); the rendered decomposer prompt interpolates the same strings, so do not restate a divergent version here. The three canonical statements:
 
-- Write `acceptance[]`/`verify[]` to capture the **outcome**, independent of any one file layout. Do NOT pin an incidental implementation detail (an internal helper name, a private file path) into an acceptance item that the advisory `changes[]` is free to reshape — assert the observable behaviour instead.
-- Keep `changes[]`/`references[]` as the honest predicted footprint. They still pass through the structural file-assumption gate (the `creates`/`refactors-existing`/`deletes` probes against the base branch) and the New-File Contract unchanged — advisory does NOT mean unvalidated. The executor's latitude to revise the approach never licenses skipping `acceptance[]`/`verify[]` or any `rules/security-baseline.md` MUST.
+- **Binding contract vs advisory sketch.** `acceptance[]` and `verify[]` are the Story's **binding contract** — the executor MUST satisfy them exactly, and they are the only definition of "done." `changes[]` and `references[]` are an **advisory implementation sketch**: your best prediction of the file footprint, which the executor MAY revise when the real codebase diverges from the sketch. Author `acceptance[]` / `verify[]` to assert the **outcome** independent of any one file layout — never pin an incidental implementation detail (an internal helper name, a private file path) into an acceptance item that the advisory `changes[]` is free to reshape; assert the observable behaviour instead.
+- **New-File Contract.** Any path named in a Story's `goal`, `acceptance`, or `verify` that does NOT already exist on `main` MUST also appear in that Story's `changes[]` with `assumption: "creates"`; otherwise the freshness validator rejects the decompose — even when the Story is the one authoring the file.
+- **Advisory does not mean unvalidated.** `changes[]` paths still pass the base-branch file-assumption probes (a `creates` against an existing path still fails), the New-File Contract still holds, and the executor's latitude to revise the approach never licenses skipping `acceptance[]` / `verify[]` or relaxing any `rules/security-baseline.md` MUST.
 
 #### NAVIGATE-DON'T-DEEP-LINK (signed-in acceptance scenarios)
 

package/.agents/workflows/helpers/acceptance-self-eval.md

@@ -43,6 +43,33 @@ per-criterion, mid-delivery, and evaluates the actual work product.
      optional advisory pre-flight — a criterion cannot be scored `met` without
      the supporting `verify[]` evidence where a `verify[]` command is relevant
      to it.
+   - **Shares `lint` / `typecheck` evidence with close (Story #4250).** When a
+     `verify[]` command is **byte-identical** to a close-validation gate — in
+     practice only the cheap, command-identical `lint` and `typecheck` gates
+     (`npm run lint` and the resolved `project.commands.typecheck`) — the
+     critic MUST run it through `evidence-gate.js` so a passing run records an
+     evidence entry in the **same keyspace** `close-validation/runner.js`
+     consults. Run it in the **same Story worktree** the close validates (the
+     HEAD-sha key enforces "unchanged HEAD") and pass the exact gate name:
+
+     ```bash
+     # Epic-attached Story:
+     node <main-repo>/.agents/scripts/evidence-gate.js \
+       --epic-id <epicId> --scope-id <storyId> --gate lint \
+       --worktree <worktree> -- npm run lint
+
+     # Standalone Story (no parent Epic) — use --standalone, omit --epic-id:
+     node <main-repo>/.agents/scripts/evidence-gate.js \
+       --standalone --scope-id <storyId> --gate typecheck \
+       --worktree <worktree> -- <resolved typecheck command>
+     ```
+
+     Close's `shouldSkip` then short-circuits that gate when HEAD is
+     unchanged; a redraft round (HEAD moves) correctly busts it. **Never**
+     run the coverage / CRAP suite through `evidence-gate.js` to stamp it
+     fresh — a false-fresh coverage record without `coverage-final.json`
+     silently weakens the floor. Limit the evidence-share to `lint` and
+     `typecheck`.
    - Emits a verdict file under `temp/` conforming to
      [`acceptance-eval-verdict.schema.json`](../../schemas/acceptance-eval-verdict.schema.json):
      one `{ index, criterion, verdict: met|partial|unmet, evidence,

package/.agents/workflows/helpers/deliver-epic.md

@@ -167,11 +167,25 @@ Validates `type::epic`, enumerates `type::story` descendants, parses
 (to enumerate the open Story set), and upserts the `epic-run-state`
 checkpoint in the per-Story-status shape (a flat `stories` map seeded at
 `pending`, plus the global `concurrencyCap`). Treat the printed JSON as
-`state`: `{ epicId, storyCount, concurrencyCap, stories, checkpointInitializedAt }`.
+`state`: `{ epicId, storyCount, concurrencyCap, stories, prdId, techSpecId, checkpointInitializedAt }`.
 `stories` is the flat dispatch hint (`{ storyId, worktree, title }` per open
 Story); the ready-set `tick` (Phase 2) decides which to dispatch on each
 beat. Flip the Epic to `agent::executing` (idempotent) after the CLI returns.
 
+**Epic linkages resolved once (Story #4253).** The envelope also carries
+`prdId` and `techSpecId` — the Epic's linked PRD / Tech-Spec issue ids,
+resolved a **single** time here from the Epic snapshot prepare already
+holds (no extra fetch). Capture both and thread them into **every**
+per-Story `story-init.js` invocation (§ 2b → `epic-deliver-story` Step 0)
+as `--prd <prdId> --tech-spec <techSpecId>`. This collapses the N
+per-Story `getEpic` round-trips (one per child, each in its own process
+with its own provider cache) to this one parent-side resolution — the
+immutable Epic issue is invariant for the lifetime of a delivery run.
+When a linkage is `null` (the Epic links no PRD or Tech Spec), omit the
+corresponding flag; the child's `story-init.js` then falls back to its
+own `getEpic` resolution for the missing id, preserving graceful
+degradation.
+
 > **Preflight guards (Story #3482 / F-workflow-guards).** Before the
 > snapshot phase runs — and before any worktree is created — prepare runs
 > two **fail-closed** guards
@@ -334,7 +348,10 @@ matching `story.dispatch.end` record is appended later by
 `epic-execute-record-wave.js` (via `emit-story-dispatch-end.js`, Story #3900)
 after the Agent return is recorded in § 2c.
 
-Each Agent call's prompt must (1) name the Story + Epic ids, (2)
+Each Agent call's prompt must (1) name the Story + Epic ids **and the
+`prdId` / `techSpecId` from the Phase 1 prepare envelope** (Story #4253) so
+the child can thread `--prd <prdId> --tech-spec <techSpecId>` into its
+`story-init.js` Step 0 — omit whichever flag is `null`, (2)
 instruct the child to invoke `helpers/epic-deliver-story <storyId>`
 (whose Step 4 defines the child's return shape), (3) remind the child
 of the **non-interactive contract** (no clarifying questions;

package/.agents/workflows/helpers/epic-deliver-story.md

@@ -77,9 +77,22 @@ the parent's permissions but have **no input channel** mid-run.
 Run from the **main checkout** (the worktree does not exist yet):
 
 ```bash
-node .agents/scripts/story-init.js --story <storyId>
+node .agents/scripts/story-init.js --story <storyId> \
+  --prd <prdId> --tech-spec <techSpecId>
 ```
 
+**Thread the Epic linkages (Story #4253).** The parent `/deliver` resolved
+the Epic's `prdId` / `techSpecId` **once** in its Phase 1 prepare and passed
+them into your dispatch prompt. Forward them as `--prd` / `--tech-spec` so
+this `story-init.js` run **skips** the per-Story `getEpic` round-trip — the
+two ids are invariant for the whole delivery run, so re-fetching the
+immutable Epic per Story is pure waste (and secondary-rate-limit pressure
+during wide fan-out). **Omit** whichever flag the prompt reported as `null`;
+`story-init.js` then falls back to its own `getEpic` resolution for the
+missing id (graceful degradation on a missing Epic linkage). When dispatched
+interactively with neither flag, drop both — the legacy single-fetch path is
+unchanged.
+
 > **Execution mode (sub-agents must read).** This command typically takes
 > 3–6 minutes when the worktree's per-tree install runs. Invoke it
 > **synchronously** with the Bash tool's maximum timeout
@@ -139,11 +152,15 @@ the Story-level rollup the parent `/deliver` aggregator reads).
 Run a single Story-implementation phase against the inline `acceptance[]`
 / `verify[]` arrays on the Story body.
 
-1. Flip the snapshot to the `implementing` phase:
+1. Flip the snapshot to the `implementing` phase. Pass `--epic <epicId>`
+   and `--branch story-<storyId>` from the Step 0 envelope so the render
+   skips the `readEpicIdFromStory` / `resolveStoryBranch` GitHub reads
+   (pass these same flags to **every** `story-phase.js` call below):
 
    ```bash
    node .agents/scripts/story-phase.js \
-     --story <storyId> --phase implementing
+     --story <storyId> --epic <epicId> --branch story-<storyId> \
+     --phase implementing
    ```
 
 2. Read the Story body's inline `acceptance[]` and `verify[]` arrays
@@ -166,11 +183,14 @@ Run a single Story-implementation phase against the inline `acceptance[]`
    evidence** — they are no longer optional advisory pre-flight.
 
 5. Once the eval loop returns `proceed`, flip the snapshot to `closing`
-   and proceed to Step 3:
+   and proceed to Step 3 (Step 3 invokes close directly — it no longer
+   re-renders the `closing` snapshot, so this is the single `closing`
+   render):
 
    ```bash
    node .agents/scripts/story-phase.js \
-     --story <storyId> --phase closing
+     --story <storyId> --epic <epicId> --branch story-<storyId> \
+     --phase closing
    ```
 
 6. If blocked (including by the eval loop reaching its round cap with
@@ -180,7 +200,8 @@ Run a single Story-implementation phase against the inline `acceptance[]`
 
    ```bash
    node .agents/scripts/story-phase.js \
-     --story <storyId> --phase blocked
+     --story <storyId> --epic <epicId> --branch story-<storyId> \
+     --phase blocked
    ```
 
 ### Step 1a — Bounded acceptance self-eval loop (**required, not optional**)
@@ -195,6 +216,18 @@ The critic reads the Story's inline `acceptance[]` / `verify[]` arrays from the
 
 Epic-attached specifics for this path:
 
+- **Critic evidence-share** (Story #4250). When the critic runs a `verify[]`
+  command that is byte-identical to a close gate (`lint` / `typecheck`), it
+  records the pass into the Epic-keyed evidence keyspace via `--epic-id
+  <epicId>` so `story-close.js` short-circuits the gate at unchanged HEAD.
+  Run it in the **Story worktree** (`.worktrees/story-<storyId>`):
+
+  ```bash
+  node .agents/scripts/evidence-gate.js \
+    --epic-id <epicId> --scope-id <storyId> --gate lint \
+    --worktree .worktrees/story-<storyId> -- npm run lint
+  ```
+
 - **Gate invocation** (pass `--epic <epicId>` so the per-criterion signal lands
   on the Epic-scoped stream):
 
@@ -235,16 +268,18 @@ fine as advisory pre-flight.)
 
 ## Step 3 — Close (`story-close.js`)
 
-Flip the snapshot to the closing phase, then invoke close. Pass the
-main-checkout path via `--cwd` so the merge and branch deletion run
-against the main repo (branches checked out in a worktree cannot be
+Step 1 item 5 already flipped the snapshot to the `closing` phase, so this
+step does **not** re-render it (the duplicate render was removed). Invoke
+close directly. Pass the parent Epic id via `--epic <epicId>` from the
+Step 0 envelope so close skips re-parsing the Epic hierarchy off the
+Story body (which also closes the malformed-`Epic:`-line failure mode).
+Pass the main-checkout path via `--cwd` so the merge and branch deletion
+run against the main repo (branches checked out in a worktree cannot be
 deleted from themselves):
 
 ```bash
-node .agents/scripts/story-phase.js \
-  --story <storyId> --phase closing
-
-node <main-repo>/.agents/scripts/story-close.js --story <storyId> --cwd <main-repo>
+node <main-repo>/.agents/scripts/story-close.js \
+  --story <storyId> --epic <epicId> --cwd <main-repo>
 ```
 
 In single-tree mode, `--cwd` defaults to `PROJECT_ROOT`. The script merges
@@ -261,7 +296,8 @@ After close, upsert a terminal snapshot:
 
 ```bash
 node .agents/scripts/story-phase.js \
-  --story <storyId> --phase done
+  --story <storyId> --epic <epicId> --branch story-<storyId> \
+  --phase done
 ```
 
 ---

package/.agents/workflows/helpers/single-story-deliver.md

@@ -215,6 +215,18 @@ proceed / redraft / block decision) is the single-homed include
 
 Standalone specifics for this path:
 
+- **Critic evidence-share** (Story #4250). When the critic runs a `verify[]`
+  command that is byte-identical to a close gate (`lint` / `typecheck`), it
+  records the pass into the standalone evidence keyspace via `--standalone`
+  (no parent Epic to key on) so Step 3's close short-circuits the gate at
+  unchanged HEAD. Run it in the **Story worktree** (`workCwd` from Step 0):
+
+  ```bash
+  node <main-repo>/.agents/scripts/evidence-gate.js \
+    --standalone --scope-id <storyId> --gate lint \
+    --worktree <workCwd> -- npm run lint
+  ```
+
 - **Gate invocation** (omit `--epic` — there is no parent Epic):
 
   ```bash

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.