mandrel 1.77.0 → 1.79.0

package/.agents/scripts/providers/github/errors.js

@@ -48,6 +48,40 @@ const TRANSIENT_MESSAGES = [
 
 const PERMISSION_MESSAGES = ['unauthorized', 'forbidden', 'permission'];
 
+// Network/connectivity blips that the gh-CLI path surfaces on `err.stderr`
+// (Go HTTP errors, e.g. `dial tcp ...: i/o timeout`) and the direct `fetch`
+// path surfaces as `TypeError: fetch failed` with the real reason on
+// `err.cause` (e.g. `ETIMEDOUT`, `ENOTFOUND`). Folded in from the former
+// `transient-retry.js` predicate (Story #4298) so the single canonical
+// classifier retries the **union** of transient HTTP statuses/codes AND
+// transient network errors. The `\b50[234]\b` alternative also catches a
+// bare 502/503/504 surfaced only in an error message string (no `.status`).
+const TRANSIENT_NETWORK_RE =
+  /i\/o timeout|dial tcp|TLS handshake timeout|connection reset|connection refused|temporary failure|could not resolve host|no such host|network is unreachable|socket hang up|fetch failed|ConnectTimeoutError|UND_ERR_CONNECT_TIMEOUT|ETIMEDOUT|ECONNRESET|ECONNREFUSED|ENOTFOUND|EAI_AGAIN|\b50[234]\b/i;
+
+/**
+ * True when an error looks like a retryable network/connectivity blip.
+ * Scans the union of fields both transport paths populate (`stderr`,
+ * `message`, `code`, and the nested `cause.message` / `cause.code` the
+ * `fetch` path uses). Module-private — folded in from the former
+ * `transient-retry.js` predicate (Story #4298) and consumed only by
+ * `classifyGithubError` below; its behavior is exercised through that public
+ * classifier rather than as a standalone export (keeps the dead-export gate
+ * green — nothing outside this module imports it).
+ */
+function isTransientNetworkError(err) {
+  const hay = [
+    err?.stderr,
+    err?.message,
+    err?.code,
+    err?.cause?.message,
+    err?.cause?.code,
+  ]
+    .filter(Boolean)
+    .join(' ');
+  return TRANSIENT_NETWORK_RE.test(hay);
+}
+
 function matchesAny(haystack, needles) {
   for (const n of needles) if (haystack.includes(n)) return true;
   return false;
@@ -97,19 +131,36 @@ export function classifyGithubError(err) {
   if (matchesAny(lower, FEATURE_DISABLED_MESSAGES)) return 'feature-disabled';
   if (isTransientStatus(status)) return 'transient';
   if (isTransientByCodeOrMessage(code, lower)) return 'transient';
+  // Union with the former `transient-retry.js` predicate (Story #4298):
+  // retry on network/connectivity blips the status/code checks above miss
+  // (e.g. a `dial tcp ... i/o timeout` on `err.stderr` from the gh-CLI path,
+  // or `ECONNREFUSED` / `ENETUNREACH`). Checked before the permission rule so
+  // a transient network failure never masquerades as a permanent denial.
+  if (isTransientNetworkError(err)) return 'transient';
   if (isPermissionSignal(status, lower)) return 'permission';
   return 'permanent';
 }
 
 // ---------------------------------------------------------------------------
-// Transient-retry helper (Story #2852)
+// Transient-retry helper (Story #2852; unified in Story #4298)
 // ---------------------------------------------------------------------------
 //
+// The single canonical `withTransientRetry` for the GitHub provider. Story
+// #4298 collapsed the former two divergent same-named implementations (this
+// one + the network-only one in the deleted `transient-retry.js`) into this
+// one primitive. Its default classifier (`classifyGithubError`) is the
+// **union** predicate — it retries on transient HTTP statuses/codes AND on
+// transient network/connectivity errors — so every former consumer of either
+// module keeps (or gains) its prior retry coverage with no shim.
+//
 // Mirrors the addSubIssue retry contract in `sub-issues.js` so read-path
 // callers (paginateRest, getTicket, getNativeSubIssues, …) absorb the same
 // jittered exponential backoff on transient GitHub errors instead of
 // bubbling a one-shot 502/429/ECONNRESET that kills a longer pipeline
-// (e.g. the /deliver Phase E retro).
+// (e.g. the /deliver Phase E retro). The network consumers repointed here
+// (branch-protection, labels, projects-v2-graphql) call with no opts, so
+// they adopt these defaults; their retry *classes* (the network blips) are
+// preserved via the unified classifier above.
 
 export const TRANSIENT_RETRY_DEFAULTS = Object.freeze({
   maxAttempts: 6,

package/.agents/scripts/providers/github/labels.js

@@ -16,7 +16,7 @@
  * @see Story #2462 — Split GitHubProvider god class into seven composed gateways.
  */
 
-import { withTransientRetry } from './transient-retry.js';
+import { withTransientRetry } from './errors.js';
 
 /**
  * Detect the "label already exists" signal across the surfaces `gh label

package/.agents/scripts/providers/github/projects-v2-graphql.js

@@ -7,7 +7,7 @@
  * `unavailable:true` envelopes. Wave 3 deletes the old submodules.
  */
 import { execSync } from 'node:child_process';
-import { withTransientRetry } from './transient-retry.js';
+import { withTransientRetry } from './errors.js';
 
 // Resolve an owner node id per-scope. Querying `user` and `organization`
 // together in one request makes GitHub return a NOT_FOUND error for whichever

package/.agents/scripts/run-lint.js

@@ -78,6 +78,17 @@ const tasks = [
     cmd: 'node',
     args: ['.agents/scripts/check-arch-cycles.js'],
   },
+  {
+    // Loop-unit frontmatter gate (Story #4288, Epic #4284). Validates
+    // every `.agents/workflows/loops/*.md` loop unit against
+    // `.agents/schemas/loop-unit.schema.json`. An absent/empty loops
+    // directory is a clean pass; a malformed unit (e.g. a self-paced
+    // cadence missing its required `verify`) fails the lint gate with a
+    // message naming the offending file + field.
+    name: 'loop-units',
+    cmd: 'node',
+    args: ['.agents/scripts/check-loop-units.js'],
+  },
 ];
 
 function runTask({ name, cmd, args }) {

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

@@ -290,13 +290,14 @@ When the Acceptance Spec contains **one or more `Disposition: new` rows**, you M
 - **goal** (in body string): contains the literal token `bdd-scaffold`.
 - **depends_on**: EMPTY (`[]`) — the scaffold runs first, in wave 0.
 - **changes** (in body string): one `{ path, assumption: "creates" }` entry per distinct `.feature` file named in a `new` row.
-- **acceptance** (top-level array): MUST assert (a) every new `.feature` file exists, and (b) every new scenario within them carries an `@skip` tag. Keep items observable (a command exits 0; a file exists at a path).
-- **verify** (top-level array): a grep/validate command (tier `validate`), NOT an e2e runner — verifying that a file exists with a tag needs no browser/playwright run.
+- **acceptance** (top-level array): MUST assert (a) every new `.feature` file exists, (b) every new scenario within them carries an `@skip` tag, AND (c) every new scenario also carries its **namespaced per-Epic AC tag** `@epic-<id>-ac-N` (one tag per AC ID the scenario satisfies). Keep items observable (a command exits 0; a file exists at a path).
+- **The namespaced AC tag is REQUIRED at scaffold time, not only at de-skip time.** Phase 7 finalize's `acceptance-spec-reconciler.js` matches AC IDs only against `@epic-<id>-ac-*` / `@pending` tags under `tests/features/**` — a bare `@ac-N` tag is deliberately ignored to prevent cross-Epic collision (Story #3362). A scaffolded scenario carrying `@skip` but no `@epic-<id>-ac-N` tag reads as `missing[]` at finalize and throws, aborting close, even after the implementation Story de-skips it — the tag was never added in either pass. Tag each scenario with both `@skip` AND `@epic-<id>-ac-N` (substituting the Epic's real ID and the scenario's own AC number) in this SAME wave-0 commit; do not defer the AC tag to the later de-skip edit.
+- **verify** (top-level array): a grep/validate command (tier `validate`), NOT an e2e runner — verifying that a file exists with the required tags needs no browser/playwright run. Include a check that each new AC ID's namespaced tag is present in the scaffolded files, alongside the `@skip` check.
 - Each implementation Story whose `verify[]` references a scaffolded `.feature` path MUST add `depends_on: ["<scaffold-slug>"]` so the scaffold lands in an earlier wave. Omitting the link trips the soft `missing-bdd-scaffold` finding in `ticket-validator-conflicts.js` (advisory, not a hard block).
 
 When the Acceptance Spec contains **zero `new`-disposition rows** (every row is `updated` or `unchanged`), do NOT emit a scaffold Story — there is nothing to create.
 
-**Worked example.** Acceptance Spec with two `new` rows (`AC-1` -> `tests/features/billing/invoice.feature`, `AC-2` -> `tests/features/billing/refund.feature`). The scaffold Story below uses a serialized string `body`, top-level `acceptance`/`verify` arrays, and an empty `depends_on`:
+**Worked example.** Epic #42, Acceptance Spec with two `new` rows (`AC-1` -> `tests/features/billing/invoice.feature`, `AC-2` -> `tests/features/billing/refund.feature`). The scaffold Story below uses a serialized string `body`, top-level `acceptance`/`verify` arrays, an empty `depends_on`, and tags each scenario with both `@skip` and its namespaced `@epic-42-ac-N` tag:
 
     {
       "slug": "scaffold-billing-feature-files",
@@ -306,16 +307,18 @@ When the Acceptance Spec contains **zero `new`-disposition rows** (every row is
       "labels": ["type::story", "persona::qa-engineer"],
       "acceptance": [
         "tests/features/billing/invoice.feature and tests/features/billing/refund.feature both exist on the branch",
-        "every Scenario in the two new feature files is preceded by an @skip tag (grep for un-skipped scenarios returns zero matches)"
+        "every Scenario in the two new feature files is preceded by an @skip tag (grep for un-skipped scenarios returns zero matches)",
+        "the invoice.feature scenario carries @epic-42-ac-1 and the refund.feature scenario carries @epic-42-ac-2"
       ],
       "verify": [
         "test -f tests/features/billing/invoice.feature && test -f tests/features/billing/refund.feature (validate)",
-        "test -z \"$(grep -rL '@skip' tests/features/billing/*.feature)\" (validate)"
+        "test -z \"$(grep -rL '@skip' tests/features/billing/*.feature)\" (validate)",
+        "grep -q '@epic-42-ac-1' tests/features/billing/invoice.feature && grep -q '@epic-42-ac-2' tests/features/billing/refund.feature (validate)"
       ],
-      "body": "## Goal\nbdd-scaffold: create the @skip-tagged feature files the billing-flows implementation Stories verify against, so wave-0 lands them before any implementation Story runs.\n\n## Changes\n- {\"path\": \"tests/features/billing/invoice.feature\", \"assumption\": \"creates\"}\n- {\"path\": \"tests/features/billing/refund.feature\", \"assumption\": \"creates\"}\n\n## Acceptance\n- [ ] tests/features/billing/invoice.feature and tests/features/billing/refund.feature both exist on the branch\n- [ ] every Scenario in the two new feature files is preceded by an @skip tag\n\n## Verify\n- test -f tests/features/billing/invoice.feature && test -f tests/features/billing/refund.feature (validate)\n- test -z \"$(grep -rL '@skip' tests/features/billing/*.feature)\" (validate)\n"
+      "body": "## Goal\nbdd-scaffold: create the @skip-tagged, @epic-42-ac-N-tagged feature files the billing-flows implementation Stories verify against, so wave-0 lands them before any implementation Story runs.\n\n## Changes\n- {\"path\": \"tests/features/billing/invoice.feature\", \"assumption\": \"creates\"}\n- {\"path\": \"tests/features/billing/refund.feature\", \"assumption\": \"creates\"}\n\n## Acceptance\n- [ ] tests/features/billing/invoice.feature and tests/features/billing/refund.feature both exist on the branch\n- [ ] every Scenario in the two new feature files is preceded by an @skip tag\n- [ ] the invoice.feature scenario carries @epic-42-ac-1 and the refund.feature scenario carries @epic-42-ac-2\n\n## Verify\n- test -f tests/features/billing/invoice.feature && test -f tests/features/billing/refund.feature (validate)\n- test -z \"$(grep -rL '@skip' tests/features/billing/*.feature)\" (validate)\n- grep -q '@epic-42-ac-1' tests/features/billing/invoice.feature && grep -q '@epic-42-ac-2' tests/features/billing/refund.feature (validate)\n"
     }
 
-The implementation Stories that later un-skip and flesh out these scenarios each carry `depends_on: ["scaffold-billing-feature-files"]`, placing them in a later wave than the scaffold.
+The implementation Stories that later un-skip and flesh out these scenarios each carry `depends_on: ["scaffold-billing-feature-files"]`, placing them in a later wave than the scaffold. They MUST NOT add the `@epic-42-ac-N` tag themselves — it is already present from the scaffold pass; their job is to remove `@skip` once the scenario passes.
 
 ### SCOPE-OVERLAP FLAGGING (docs/runbook downstream of config work)
 

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.