mandrel 2.25.0 → 2.26.0

package/.agents/scripts/lib/worktree/git-hooks.js

@@ -0,0 +1,206 @@
+/**
+ * worktree/git-hooks.js
+ *
+ * Materialize the repository's git hooks directory into a linked worktree.
+ *
+ * `core.hooksPath` is resolved by git against **each working tree's own
+ * root**, not against the common git dir. A relative value therefore points
+ * at a directory that only exists in the checkout that generated it — husky
+ * writes `.husky/_` from its `prepare` script in the main checkout and
+ * self-ignores it — so every linked worktree resolves the hooks path to a
+ * directory that is not there. Git finds no hooks and proceeds silently:
+ * `commit-msg`, `pre-commit` and `pre-push` do not run for any commit made in
+ * a worktree, without anyone passing a bypass flag.
+ *
+ * This module closes that gap by copying the resolved hooks directory into
+ * the worktree at the same relative path. It is deliberately total about the
+ * cases where there is nothing to do — an unset or absolute `core.hooksPath`,
+ * or a source directory that does not exist — because a consumer project
+ * without husky must not fail worktree creation. Every other outcome either
+ * materializes the hooks or throws: a silent skip is the defect being fixed.
+ */
+
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import * as defaultGit from '../git-utils.js';
+import { assertPathContainment } from '../path-security.js';
+
+// Skip reasons. Deliberately not exported: they are part of the result
+// digest's observable contract, so callers and tests read them as the literal
+// strings they are printed as, not through a symbol that could be renamed
+// without anyone noticing the digest changed.
+//
+//   hooks-path-unset  — git uses the common `hooks` dir, already shared.
+//   hooks-path-absolute — resolves alike from every working tree already.
+//   source-absent     — no hooks directory to mirror (no husky in this project).
+//   same-checkout     — target is the source; copying it onto itself would
+//                       destroy the only copy.
+const SKIP_UNSET = 'hooks-path-unset';
+const SKIP_ABSOLUTE = 'hooks-path-absolute';
+const SKIP_SOURCE_ABSENT = 'source-absent';
+const SKIP_SAME_CHECKOUT = 'same-checkout';
+
+/**
+ * Read `core.hooksPath` as configured for `repoRoot`.
+ *
+ * `git config --get` exits non-zero when the key is unset, which is a
+ * legitimate state rather than an error, so this reports `null` for both an
+ * unset key and an empty value.
+ *
+ * @param {string} repoRoot
+ * @param {{ gitSpawn: Function }} gitImpl
+ * @returns {string|null}
+ */
+function readHooksPath(repoRoot, gitImpl) {
+  const res = gitImpl.gitSpawn(repoRoot, 'config', '--get', 'core.hooksPath');
+  if (res.status !== 0) return null;
+  const value = (res.stdout ?? '').trim();
+  return value.length > 0 ? value : null;
+}
+
+/**
+ * Canonical form of `dir` for identity comparison.
+ *
+ * `realpathSync.native` is used so a symlinked temp root (macOS `/var` →
+ * `/private/var`) does not make a checkout look distinct from itself. A path
+ * that cannot be resolved falls back to `path.resolve`, which is enough for
+ * the comparison to stay conservative.
+ *
+ * @param {string} dir
+ * @param {typeof fs} fsImpl
+ * @returns {string}
+ */
+function canonical(dir, fsImpl) {
+  const resolved = path.resolve(dir);
+  try {
+    return fsImpl.realpathSync.native(resolved);
+  } catch {
+    return resolved;
+  }
+}
+
+/**
+ * Names of the regular files directly inside `dir`, sorted.
+ *
+ * @param {string} dir
+ * @param {typeof fs} fsImpl
+ * @returns {string[]}
+ */
+function hookFileNames(dir, fsImpl) {
+  return fsImpl
+    .readdirSync(dir, { withFileTypes: true })
+    .filter((ent) => ent.isFile())
+    .map((ent) => ent.name)
+    .sort();
+}
+
+/**
+ * Materialize `repoRoot`'s resolved git hooks directory into `worktree`.
+ *
+ * Idempotent, and refreshing rather than preserving: an existing target is
+ * replaced so an upgraded husky can never leave a stale shim behind.
+ *
+ * @param {object} opts
+ * @param {string} opts.repoRoot   Absolute path to the checkout that owns the hooks.
+ * @param {string} opts.worktree   Absolute path to the worktree to provision.
+ * @param {{ gitSpawn: Function }} [opts.gitImpl]
+ * @param {typeof fs} [opts.fsImpl]
+ * @returns {{ action: 'materialized' | 'skipped', reason?: string,
+ *   hooksPath: string|null, source: string|null, target: string|null,
+ *   hooks: string[] }}
+ * @throws {Error} when the source exists but the hooks could not be placed.
+ */
+export function materializeGitHooks({
+  repoRoot,
+  worktree,
+  gitImpl = defaultGit,
+  fsImpl = fs,
+} = {}) {
+  if (!repoRoot || typeof repoRoot !== 'string') {
+    throw new Error('worktree.hooks: repoRoot is required');
+  }
+  if (!worktree || typeof worktree !== 'string') {
+    throw new Error('worktree.hooks: worktree is required');
+  }
+
+  const skip = (reason, hooksPath = null) => ({
+    action: 'skipped',
+    reason,
+    hooksPath,
+    source: null,
+    target: null,
+    hooks: [],
+  });
+
+  const hooksPath = readHooksPath(repoRoot, gitImpl);
+  if (hooksPath === null) return skip(SKIP_UNSET);
+  if (path.isAbsolute(hooksPath)) return skip(SKIP_ABSOLUTE, hooksPath);
+
+  if (canonical(repoRoot, fsImpl) === canonical(worktree, fsImpl)) {
+    return skip(SKIP_SAME_CHECKOUT, hooksPath);
+  }
+
+  const source = path.resolve(repoRoot, hooksPath);
+  if (!fsImpl.existsSync(source)) return skip(SKIP_SOURCE_ABSENT, hooksPath);
+
+  const target = path.resolve(worktree, hooksPath);
+  // `core.hooksPath` is repo configuration, but it still reaches a recursive
+  // remove below — a `../..` value must not be able to delete outside the
+  // worktree it claims to provision.
+  assertPathContainment(
+    path.resolve(worktree),
+    target,
+    'worktree.hooks: core.hooksPath',
+    { allowEmpty: false },
+  );
+
+  try {
+    fsImpl.rmSync(target, { recursive: true, force: true });
+    fsImpl.mkdirSync(path.dirname(target), { recursive: true });
+    fsImpl.cpSync(source, target, { recursive: true });
+  } catch (err) {
+    throw new Error(
+      `worktree.hooks: failed to materialize ${source} into ${target}: ${err.message}`,
+    );
+  }
+
+  // Verify rather than trust the copy. The whole point of this module is that
+  // a hooks directory which is absent behaves exactly like one that is
+  // present and empty — git runs neither, and says nothing either way.
+  const expected = hookFileNames(source, fsImpl);
+  const actual = new Set(
+    fsImpl.existsSync(target) ? hookFileNames(target, fsImpl) : [],
+  );
+  const missing = expected.filter((name) => !actual.has(name));
+  if (missing.length > 0) {
+    throw new Error(
+      `worktree.hooks: materialized ${target} is missing ${missing.length} hook(s): ${missing.join(', ')}`,
+    );
+  }
+
+  return { action: 'materialized', hooksPath, source, target, hooks: expected };
+}
+
+/**
+ * Resolve the checkout that owns the shared git config from `cwd`.
+ *
+ * `--git-common-dir` reports the common git dir from any working tree —
+ * `.git` from the main checkout, an absolute path from a linked worktree —
+ * so the owning checkout is its parent. This is what lets the standalone CLI
+ * be run from inside a worktree with no arguments.
+ *
+ * @param {string} cwd
+ * @param {{ execFileSyncImpl?: typeof execFileSync }} [deps]
+ * @returns {string}
+ */
+export function resolveCommonCheckout(
+  cwd,
+  { execFileSyncImpl = execFileSync } = {},
+) {
+  const out = execFileSyncImpl('git', ['rev-parse', '--git-common-dir'], {
+    cwd,
+    encoding: 'utf8',
+  }).trim();
+  return path.dirname(path.resolve(cwd, out));
+}

package/.agents/scripts/lib/worktree/lifecycle/creation.js

@@ -123,6 +123,12 @@ export async function ensure(ctx, storyId, branch) {
   applyNodeModulesStrategy(ctx, wtPath);
   phase('bootstrap');
   ctx.copyBootstrapFiles(wtPath);
+  // Unconditional, and deliberately not routed through `copyBootstrapFiles`:
+  // that path is driven by `bootstrapFiles` and its provisioner copies single
+  // files, while a hooks directory is a tree. A worktree without hooks accepts
+  // commits no gate ever sees, so this runs for every worktree the manager
+  // creates and throws rather than degrading.
+  ctx.provisionGitHooks(wtPath);
   phase('install');
   const installStatus = installDependencies(ctx, wtPath);
 

package/.agents/scripts/lib/worktree-manager.js

@@ -25,6 +25,7 @@ import {
   DEFAULT_WORKSPACE_FILES,
   provision as provisionWorkspace,
 } from './workspace-provisioner.js';
+import { materializeGitHooks } from './worktree/git-hooks.js';
 import {
   maybeWarnWindowsPath,
   parseWorktreePorcelain,
@@ -161,6 +162,19 @@ export class WorktreeManager {
           logger: wrapped,
         });
       },
+      provisionGitHooks: (wtPath) => {
+        const result = materializeGitHooks({
+          repoRoot: this.repoRoot,
+          worktree: wtPath,
+          gitImpl: this.git,
+        });
+        this.logger.info(
+          result.action === 'materialized'
+            ? `worktree.bootstrap hooks materialized path=${result.target} hooks=${result.hooks.length}`
+            : `worktree.bootstrap hooks skipped reason=${result.reason}`,
+        );
+        return result;
+      },
     };
   }
 

package/.agents/scripts/plan-run-epilogue.js

@@ -5,6 +5,7 @@
  *
  * Usage:
  *   node .agents/scripts/plan-run-epilogue.js --stories 1,2,3
+ *   node .agents/scripts/plan-run-epilogue.js --stories 101-104   # inclusive range
  *
  * Keyed on the delivered id set: an `adhoc-<sorted-ids>` run id is
  * synthesized from `--stories`. Story #4540 retired the `--run <planRunId>`
@@ -19,6 +20,7 @@ import { resolveConfig } from './lib/config-resolver.js';
 import { Logger } from './lib/Logger.js';
 import { runPlanRunEpilogue } from './lib/orchestration/run-epilogue.js';
 import { createProvider } from './lib/provider-factory.js';
+import { expandIdList } from './lib/util/parse-id-list.js';
 
 const CLI_OPTIONS = {
   stories: { type: 'string' },
@@ -65,10 +67,17 @@ export async function main(argv = process.argv.slice(2), deps = {}) {
   // along with the label itself. The epilogue is keyed on the delivered id
   // set, and the synthesized `adhoc-<ids>` id it already used for positional
   // runs is now the only id it needs.
-  const stories = values.stories
-    .split(',')
-    .map((s) => Number(s.trim()))
-    .filter((n) => Number.isInteger(n) && n > 0);
+  // Range tokens expand here too (`--stories 101-104`): /deliver blesses the
+  // dash range at the operator surface, so the id set the epilogue is keyed on
+  // must read the same shape. Rejecting a bad token is deliberate — the old
+  // silent filter turned a typo into an empty, wrongly-keyed rollup.
+  const { ids: stories, error: storiesError } = expandIdList(values.stories, {
+    flag: '--stories',
+    prefix: '[plan-run-epilogue] ',
+  });
+  if (storiesError) {
+    throw new Error(storiesError);
+  }
 
   const planRunId = `adhoc-${[...stories].sort((a, b) => a - b).join('-')}`;
 
@@ -162,7 +171,10 @@ await runAsCli(import.meta.url, main, {
     summary:
       'Close out a delivery run: roll up the delivered Stories’ signals and report the run’s loop health.',
     flags: [
-      ['--stories <ids>', 'Comma-separated delivered Story ids (required).'],
+      [
+        '--stories <ids>',
+        'Comma-separated delivered Story ids, singles or A-B ranges (required).',
+      ],
       ['--cwd <path>', 'Repository root (default: process cwd).'],
     ],
   },

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

@@ -321,6 +321,16 @@ export class TicketGateway {
    * avoid a read-before-write. When other PATCH fields are present, or when
    * removing labels, computes the final label set and returns it to the
    * caller for inclusion in the PATCH.
+   *
+   * The additive POST goes through `withTransientRetry` (Story #4961) on the
+   * same policy as every other call in this file. Story #4952 raised the
+   * `/plan` write loops that reach this endpoint — the `agent::ready` flips
+   * and the checkpoint fan-out — off serial, which is precisely what makes
+   * GitHub's secondary rate limit likelier; `gh-exec` already classifies that
+   * as transient, so the only thing missing was a backoff behind it.
+   * Retry does not change what the caller observes on a genuine failure: an
+   * exhausted or non-transient error still throws, so `markStoriesReady`
+   * still collects it into the complete failure set.
    */
   async _applyLabelMutations(
     ticketId,
@@ -331,11 +341,15 @@ export class TicketGateway {
     const { add = [], remove = [] } = labelMutations;
 
     if (add.length > 0 && remove.length === 0 && !hasOtherPatchFields) {
-      await this._gh.api({
-        method: 'POST',
-        endpoint: `/repos/${this.owner}/${this.repo}/issues/${ticketId}/labels`,
-        body: { labels: add },
-      });
+      await withTransientRetry(
+        () =>
+          this._gh.api({
+            method: 'POST',
+            endpoint: `/repos/${this.owner}/${this.repo}/issues/${ticketId}/labels`,
+            body: { labels: add },
+          }),
+        { label: `addLabels #${ticketId}`, onRetry: defaultRetryWarn },
+      );
       return { skipPatch: true };
     }
 
@@ -351,6 +365,11 @@ export class TicketGateway {
   }
 
   /**
+   * The issue PATCH is wrapped in `withTransientRetry` (Story #4961) for the
+   * same reason as the additive label POST above — see
+   * {@link TicketGateway#_applyLabelMutations}. Both are the write half of the
+   * fan-outs Story #4952 raised; the reads in this file were already wrapped.
+   *
    * @field-manifest PATCH /repos/{owner}/{repo}/issues/{n}:
    *                 body, assignees, state, state_reason, labels
    */
@@ -379,11 +398,15 @@ export class TicketGateway {
     }
 
     if (Object.keys(patch).length > 0) {
-      await this._gh.api({
-        method: 'PATCH',
-        endpoint: `/repos/${this.owner}/${this.repo}/issues/${ticketId}`,
-        body: patch,
-      });
+      await withTransientRetry(
+        () =>
+          this._gh.api({
+            method: 'PATCH',
+            endpoint: `/repos/${this.owner}/${this.repo}/issues/${ticketId}`,
+            body: patch,
+          }),
+        { label: `updateTicket #${ticketId}`, onRetry: defaultRetryWarn },
+      );
       this.invalidateTicket(ticketId);
     }
   }

package/.agents/scripts/provision-git-hooks.js

@@ -0,0 +1,85 @@
+#!/usr/bin/env node
+
+/**
+ * provision-git-hooks.js
+ *
+ * Materialize the repository's git hooks into a linked worktree, so commits
+ * made there are subject to the same `commit-msg` / `pre-commit` / `pre-push`
+ * gates as commits made in the main checkout.
+ *
+ * Worktrees created by `single-story-init.js` are provisioned automatically as
+ * part of `worktree.bootstrap`. This entry point exists for the worktrees the
+ * orchestrator never creates — a harness or hand-made `git worktree add` —
+ * which are otherwise unreachable. Run it from inside such a worktree with no
+ * arguments.
+ */
+
+import path from 'node:path';
+import { runAsCli } from './lib/cli-utils.js';
+import {
+  materializeGitHooks,
+  resolveCommonCheckout,
+} from './lib/worktree/git-hooks.js';
+
+/**
+ * @param {object} [opts]
+ * @param {string[]} [opts.argv]
+ * @param {string} [opts.cwd]
+ * @returns {{ action: string, reason?: string, hooksPath: string|null,
+ *   target: string|null, hooks: string[], worktree: string, repoRoot: string }}
+ */
+export function runProvisionGitHooks({
+  argv = process.argv.slice(2),
+  cwd = process.cwd(),
+} = {}) {
+  const positional = [];
+  let repoRootFlag = null;
+  for (let i = 0; i < argv.length; i += 1) {
+    if (argv[i] === '--repo-root') {
+      repoRootFlag = argv[i + 1];
+      if (!repoRootFlag) {
+        throw new Error('--repo-root requires a path');
+      }
+      i += 1;
+      continue;
+    }
+    positional.push(argv[i]);
+  }
+
+  const worktree = path.resolve(cwd, positional[0] ?? '.');
+  const repoRoot = repoRootFlag
+    ? path.resolve(cwd, repoRootFlag)
+    : resolveCommonCheckout(worktree);
+
+  const result = materializeGitHooks({ repoRoot, worktree });
+  return { ...result, worktree, repoRoot };
+}
+
+runAsCli(
+  import.meta.url,
+  async () => {
+    const result = runProvisionGitHooks();
+    // Compact single-line digest: this is the machine contract, and the
+    // hook file list is bounded by the hooks directory itself.
+    process.stdout.write(`${JSON.stringify(result)}\n`);
+  },
+  {
+    source: 'provision-git-hooks',
+    usage: {
+      invocation:
+        'node .agents/scripts/provision-git-hooks.js [<worktree-path>] [--repo-root <path>]',
+      summary:
+        "Materialize the repository's git hooks into a linked worktree so its commits are gated.",
+      flags: [
+        [
+          '<worktree-path>',
+          'Worktree to provision (default: the current directory).',
+        ],
+        [
+          '--repo-root <path>',
+          'Checkout that owns the hooks (default: derived from --git-common-dir).',
+        ],
+      ],
+    },
+  },
+);

package/.agents/scripts/quality-preview.js

@@ -30,6 +30,8 @@ import {
   runMaintainabilityPreview,
 } from './lib/baselines/preview-gates.js';
 import { respondToHelp } from './lib/cli-usage.js';
+import { getQuality, resolveConfig } from './lib/config-resolver.js';
+import { resolveCyclomaticPolicy } from './lib/cyclomatic-ceiling.js';
 
 const USAGE = {
   invocation:
@@ -46,6 +48,14 @@ const USAGE = {
   ],
 };
 
+/**
+ * Framework default for `delivery.quality.codingGuardrails.cyclomaticFlag`,
+ * used only when a caller drives `mergeEnvelopes` / `renderTable` without a
+ * resolved config in hand (tests, and the pure-function surface). `runCli`
+ * always passes the resolved value.
+ */
+const DEFAULT_CYCLOMATIC_FLAG = 8;
+
 /**
  * Parse `--changed-since <ref>` from argv. Defaults to `HEAD` when the flag is
  * present without a value. Returns `null` when the flag is absent so callers
@@ -97,6 +107,47 @@ export function parseStagedFlag(argv) {
   return argv.includes('--staged');
 }
 
+/**
+ * Coerce a caller-supplied flag ceiling to a usable number, falling back to
+ * the framework default for anything non-finite.
+ *
+ * @param {unknown} value
+ * @returns {number}
+ */
+function normalizeFlag(value) {
+  const n = Number(value);
+  return Number.isFinite(n) ? n : DEFAULT_CYCLOMATIC_FLAG;
+}
+
+/**
+ * Fold one CRAP violation into its per-file aggregate row. Mutates `row`.
+ *
+ * Split out of `mergeEnvelopes` (Story #4923): threading the resolved
+ * `cyclomaticFlag` through pushed that function from c=12 — exactly at the
+ * must-fix ceiling — to c=13, and the same Story starts *enforcing* that
+ * ceiling. Recording its own breach in `baselines/cyclomatic.json` would have
+ * been the first re-spend of the slack the Story reclaims.
+ *
+ * @param {{ worstCrapDelta: number, newOverCeilingMethods: number }} row
+ * @param {{ crap?: number, ceiling?: number, baseline?: number, cyclomatic?: number, kind?: string }} v
+ * @param {number} flag resolved `codingGuardrails.cyclomaticFlag`
+ * @returns {void}
+ */
+function foldCrapViolation(row, v, flag) {
+  const crap = Number(v.crap ?? 0);
+  const isNew = v.kind === 'new';
+  const against = Number((isNew ? v.ceiling : v.baseline) ?? 0);
+  const delta = crap - against;
+  if (Number.isFinite(delta) && delta > row.worstCrapDelta) {
+    row.worstCrapDelta = delta;
+  }
+  if (!isNew) return;
+  const cyclomatic = Number(v.cyclomatic ?? 0);
+  if (Number.isFinite(cyclomatic) && cyclomatic > flag) {
+    row.newOverCeilingMethods += 1;
+  }
+}
+
 /**
  * Merge an MI envelope (from `runMaintainabilityPreview`) and a CRAP
  * envelope (from `runCrapPreview`) into a per-file delta map. Pure —
@@ -109,9 +160,16 @@ export function parseStagedFlag(argv) {
  *     methods (max of `crap - baseline` for matched-baseline rows, `crap`
  *     for new-method rows). 0 when the file has no CRAP violations.
  *   - `newOverCeilingMethods`: count of new-method violations (kind:'new')
- *     scoring above the `c=8` ceiling (matches the column header
- *     "new-method count over c=8" in the AC). The CRAP envelope's
- *     `cyclomatic` field is the per-method `c` reading.
+ *     scoring above the flag ceiling. The CRAP envelope's `cyclomatic` field
+ *     is the per-method `c` reading.
+ *
+ * `cyclomaticFlag` is the resolved
+ * `delivery.quality.codingGuardrails.cyclomaticFlag` (Story #4923). It used to
+ * be the literal `8` written into this function and into the column header, so
+ * a consumer that tuned the knob saw its own value validated by the schema,
+ * defaulted by the bootstrap, resolved by `lib/config/quality.js` — and then
+ * ignored here. The parameter defaults to the framework default so a caller
+ * with no config in hand still gets the historical reading.
  *
  * @param {{ violations?: Array<{ file: string, drop?: number }> } | null} miEnvelope
  * @param {{ violations?: Array<{
@@ -122,6 +180,7 @@ export function parseStagedFlag(argv) {
  *   cyclomatic: number,
  *   kind: 'new' | 'regression' | 'drifted-regression' | string,
  * }>} | null} crapEnvelope
+ * @param {{ cyclomaticFlag?: number }} [opts]
  * @returns {{
  *   rows: Array<{
  *     file: string,
@@ -130,9 +189,15 @@ export function parseStagedFlag(argv) {
  *     newOverCeilingMethods: number,
  *   }>,
  *   totals: { miRegressions: number, crapViolations: number },
+ *   cyclomaticFlag: number,
  * }}
  */
-export function mergeEnvelopes(miEnvelope, crapEnvelope) {
+export function mergeEnvelopes(
+  miEnvelope,
+  crapEnvelope,
+  { cyclomaticFlag = DEFAULT_CYCLOMATIC_FLAG } = {},
+) {
+  const flag = normalizeFlag(cyclomaticFlag);
   /** @type {Map<string, { miDrop: number, worstCrapDelta: number, newOverCeilingMethods: number }>} */
   const byFile = new Map();
   const ensure = (file) => {
@@ -155,25 +220,7 @@ export function mergeEnvelopes(miEnvelope, crapEnvelope) {
   const crapViolations = crapEnvelope?.violations ?? [];
   for (const v of crapViolations) {
     if (!v?.file) continue;
-    const row = ensure(v.file);
-    const crap = Number(v.crap ?? 0);
-    if (v.kind === 'new') {
-      const ceiling = Number(v.ceiling ?? 0);
-      const delta = crap - ceiling;
-      if (Number.isFinite(delta) && delta > row.worstCrapDelta) {
-        row.worstCrapDelta = delta;
-      }
-      const cyclomatic = Number(v.cyclomatic ?? 0);
-      if (Number.isFinite(cyclomatic) && cyclomatic > 8) {
-        row.newOverCeilingMethods += 1;
-      }
-    } else {
-      const baseline = Number(v.baseline ?? 0);
-      const delta = crap - baseline;
-      if (Number.isFinite(delta) && delta > row.worstCrapDelta) {
-        row.worstCrapDelta = delta;
-      }
-    }
+    foldCrapViolation(ensure(v.file), v, flag);
   }
 
   const rows = Array.from(byFile.entries())
@@ -188,6 +235,7 @@ export function mergeEnvelopes(miEnvelope, crapEnvelope) {
         (crapEnvelope?.summary?.regressions ?? 0) +
         (crapEnvelope?.summary?.newViolations ?? 0),
     },
+    cyclomaticFlag: flag,
   };
 }
 
@@ -239,21 +287,28 @@ export function computeExitCode(merged, miExit, crapExit) {
 }
 
 /**
- * Render the per-file delta table. Header columns match the AC verbatim:
- *   "file", "MI delta", "worst CRAP delta", "new-method count over c=8".
+ * Render the per-file delta table. Columns:
+ *   "file", "MI delta", "worst CRAP delta", "new-method count over c=<flag>".
+ *
+ * The last header used to hardcode `c=8`, which quietly lied to any consumer
+ * that had tuned `codingGuardrails.cyclomaticFlag`. It now names the value the
+ * count was actually taken against, read off the merge result.
  *
  * Pure — accepts pre-computed merge rows and returns a multi-line string. The
  * table renders even on a clean diff so operators see the "no drift" signal.
  *
- * @param {{ rows: Array<{ file: string, miDrop: number, worstCrapDelta: number, newOverCeilingMethods: number }>, totals: { miRegressions: number, crapViolations: number } }} merged
+ * @param {{ rows: Array<{ file: string, miDrop: number, worstCrapDelta: number, newOverCeilingMethods: number }>, totals: { miRegressions: number, crapViolations: number }, cyclomaticFlag?: number }} merged
  * @returns {string}
  */
 export function renderTable(merged) {
+  const flag = Number.isFinite(Number(merged?.cyclomaticFlag))
+    ? Number(merged.cyclomaticFlag)
+    : DEFAULT_CYCLOMATIC_FLAG;
   const header = [
     'file',
     'MI delta',
     'worst CRAP delta',
-    'new-method count over c=8',
+    `new-method count over c=${flag}`,
   ];
   const lines = [];
   lines.push(`| ${header.join(' | ')} |`);
@@ -274,6 +329,31 @@ export function renderTable(merged) {
   return lines.join('\n');
 }
 
+/**
+ * Resolve `codingGuardrails.cyclomaticFlag` for the tree at `cwd`
+ * (Story #4923), falling back to the framework default when the config cannot
+ * be resolved at all.
+ *
+ * Best-effort by design: `quality:preview` is a developer-facing report, and a
+ * run in a tree with no readable `.agentrc.json` should still render its table
+ * rather than abort. Extracted from `runCli` rather than inlined so the CLI
+ * body stays under the cyclomatic must-fix ceiling this same Story starts
+ * enforcing — a gate whose own delivery breaches it is not a gate.
+ *
+ * @param {{ cwd: string, stderr: { write: (s: string) => void } }} args
+ * @returns {number}
+ */
+function resolveCyclomaticFlag({ cwd, stderr }) {
+  try {
+    return resolveCyclomaticPolicy(getQuality(resolveConfig({ cwd }))).flag;
+  } catch (err) {
+    stderr.write(
+      `[quality:preview] config resolution failed, using cyclomaticFlag=${DEFAULT_CYCLOMATIC_FLAG}: ${err?.message ?? err}\n`,
+    );
+    return DEFAULT_CYCLOMATIC_FLAG;
+  }
+}
+
 /**
  * Top-level CLI entry: invoke both per-kind preview runners, merge, render,
  * and exit with the right code. Exposed as `runCli` so tests can drive the
@@ -319,7 +399,11 @@ export async function runCli({
   const crapExit = crapResult.exitCode;
   const miEnvelope = miResult.envelope;
   const crapEnvelope = crapResult.envelope;
-  const merged = mergeEnvelopes(miEnvelope, crapEnvelope);
+  // Story #4923 — the over-ceiling column counts against the *resolved*
+  // `codingGuardrails.cyclomaticFlag`, not the literal that used to be written
+  // into `mergeEnvelopes` and the column header.
+  const cyclomaticFlag = resolveCyclomaticFlag({ cwd, stderr });
+  const merged = mergeEnvelopes(miEnvelope, crapEnvelope, { cyclomaticFlag });
 
   if (json) {
     stdout.write(