mandrel 2.31.0 → 2.33.0

package/.agents/scripts/lib/config/gates/lint.schema.js

@@ -1,9 +1,18 @@
 /* node:coverage ignore file -- AJV schema declaration (data-as-code) */
 
-import { GATE_BASE } from './shared.js';
+import { gateBase } from './shared.js';
 
 export const LINT_GATE = {
   type: 'object',
-  properties: { ...GATE_BASE },
+  description:
+    'Lint-count ratchet. Floors are absolute error/warning counts; the baseline pins the current count so a regression is visible even while the floor is not yet met.',
+  properties: {
+    ...gateBase({
+      enabled: true,
+      baselinePath: 'baselines/lint.json',
+      tolerance: { kind: 'absolute', value: 0 },
+      floors: { '*': { errorCount: 0 } },
+    }),
+  },
   additionalProperties: false,
 };

package/.agents/scripts/lib/config/gates/maintainability.schema.js

@@ -1,29 +1,51 @@
 /* node:coverage ignore file -- AJV schema declaration (data-as-code) */
 
+import { MAINTAINABILITY_GATE_DEFAULTS } from '../quality.js';
 import {
-  GATE_BASE,
+  gateBase,
   LIST_OR_EXTENDER_OF_STRINGS,
   SAFE_STRING,
 } from './shared.js';
 
 export const MAINTAINABILITY_GATE = {
   type: 'object',
+  description:
+    'Maintainability-index ratchet. Scores per file as the average over its methods, so deleting a small high-MI method can legitimately lower a file’s score.',
   properties: {
-    ...GATE_BASE,
-    targetDirs: LIST_OR_EXTENDER_OF_STRINGS,
+    ...gateBase({
+      enabled: MAINTAINABILITY_GATE_DEFAULTS.enabled,
+      baselinePath: MAINTAINABILITY_GATE_DEFAULTS.baselinePath,
+      tolerance: MAINTAINABILITY_GATE_DEFAULTS.tolerance,
+      floors: MAINTAINABILITY_GATE_DEFAULTS.floors,
+    }),
+    targetDirs: {
+      ...LIST_OR_EXTENDER_OF_STRINGS,
+      description:
+        "Directories whose JS sources the maintainability gate scores. Mandrel ships a `src/`-centric default; projects whose executable code lives elsewhere (e.g. this repo's `.agents/scripts/` plus `tests/`) override here. The framework default is intentionally not auto-discovered, so an override is the explicit, auditable signal.",
+      default: [...MAINTAINABILITY_GATE_DEFAULTS.targetDirs],
+    },
     // Story #4731 — commit-subject substring that acknowledges a deliberate
-    // maintainability baseline refresh in the compared range. Mirrors the CRAP
-    // gate's `refreshTag`; a range commit carrying it that touches the baseline
-    // file demotes head-vs-base regressions (floors still enforced).
-    refreshTag: { ...SAFE_STRING, minLength: 1 },
-    // Story #2165 — bounded timeout for `npm run maintainability:update`
-    // spawned by the baseline-attribution refresh path. Mirrors
-    // `coverage.timeoutMs` (Story #2142).
-    refreshTimeoutMs: { type: 'integer', minimum: 1 },
-    // Story #3217 — glob patterns matched against canonicalised repo-relative
-    // paths to exclude files from MI discovery before scoring. Orthogonal to
-    // `components` (grouping). Absent/empty preserves existing behaviour.
-    ignoreGlobs: { type: 'array', items: { type: 'string', minLength: 1 } },
+    // maintainability baseline refresh in the compared range.
+    refreshTag: {
+      ...SAFE_STRING,
+      minLength: 1,
+      description:
+        "Commit-subject substring that acknowledges a deliberate maintainability baseline refresh in the compared range. Mirrors the CRAP gate's `refreshTag`; a range commit carrying it that touches the baseline file demotes head-vs-base regressions (floors still enforced).",
+    },
+    refreshTimeoutMs: {
+      type: 'integer',
+      minimum: 1,
+      description:
+        'Bounded timeout (ms) for `npm run maintainability:update` spawned by the baseline-attribution refresh path. Mirrors `coverage.timeoutMs`: a SIGKILL fired at the budget boundary maps to exit 124 so the close orchestrator can flip the Story to `agent::blocked`. Default 60000 (Story #2165).',
+      default: MAINTAINABILITY_GATE_DEFAULTS.refreshTimeoutMs,
+    },
+    ignoreGlobs: {
+      type: 'array',
+      items: { type: 'string', minLength: 1 },
+      description:
+        'Minimatch glob patterns matched against the canonicalised repo-relative path of each discovered file. Files matching any pattern are excluded from MI discovery before scoring. Orthogonal to `components` (grouping) — a file excluded here never appears in any component bucket. Absent or empty preserves the existing IGNORED_DIRS-only behaviour (Story #3217).',
+      default: [...MAINTAINABILITY_GATE_DEFAULTS.ignoreGlobs],
+    },
   },
   additionalProperties: false,
 };

package/.agents/scripts/lib/config/gates/mutation.schema.js

@@ -1,12 +1,24 @@
 /* node:coverage ignore file -- AJV schema declaration (data-as-code) */
 
-import { GATE_BASE, NULLABLE_NONEMPTY_SAFE_STRING } from './shared.js';
+import { gateBase, NULLABLE_NONEMPTY_SAFE_STRING } from './shared.js';
 
 export const MUTATION_GATE = {
   type: 'object',
+  description:
+    'Stryker mutation-score ratchet. Off in practice for most consumers — the baseline kind is registered but no framework path runs Stryker.',
   properties: {
-    ...GATE_BASE,
-    strykerConfigPath: NULLABLE_NONEMPTY_SAFE_STRING,
+    ...gateBase({
+      enabled: true,
+      baselinePath: 'baselines/mutation.json',
+      tolerance: { kind: 'percent', value: 0 },
+      floors: { '*': { score: 60 } },
+    }),
+    strykerConfigPath: {
+      ...NULLABLE_NONEMPTY_SAFE_STRING,
+      description:
+        'Repo-relative path to the Stryker config. `null` lets Stryker resolve its own default.',
+      default: null,
+    },
   },
   additionalProperties: false,
 };

package/.agents/scripts/lib/config/gates/shared.js

@@ -48,10 +48,21 @@ export const LIST_OR_EXTENDER_OF_STRINGS = {
 /** Object-shaped tolerance: `{ kind: 'absolute' | 'percent', value: number }`. */
 export const TOLERANCE_SCHEMA = {
   type: 'object',
+  description:
+    'How much a rollup may drift from the committed baseline before the gate reports a regression.',
   required: ['kind', 'value'],
   properties: {
-    kind: { type: 'string', enum: ['absolute', 'percent'] },
-    value: { type: 'number', minimum: 0 },
+    kind: {
+      type: 'string',
+      enum: ['absolute', 'percent'],
+      description:
+        'Whether `value` is read as raw metric units (`absolute`) or as a percentage of the baseline (`percent`).',
+    },
+    value: {
+      type: 'number',
+      minimum: 0,
+      description: 'The tolerance magnitude. 0 means no drift is allowed.',
+    },
   },
   additionalProperties: false,
 };
@@ -84,6 +95,8 @@ export const TOLERANCE_SCHEMA = {
  */
 export const FLOORS_SCHEMA = {
   type: 'object',
+  description:
+    'Workspace-keyed absolute floors: `{ "<workspace>": { "<metric>": number } }`. `"*"` is the project-wide catch-all; the metric keyset is open so per-rollup keys flow through without each gate enumerating them. Floors are absolute — unlike `tolerance`, they are enforced regardless of the baseline.',
   additionalProperties: {
     type: 'object',
     additionalProperties: { type: 'number' },
@@ -102,16 +115,52 @@ export const FLOORS_SCHEMA = {
  */
 export const COMPONENTS_SCHEMA = {
   type: 'object',
+  description:
+    'Per-gate component map — component name to the glob list whose files roll up under it. Defaults to `{ "*": ["**"] }` at the resolver layer.',
   additionalProperties: {
     type: 'array',
     items: { type: 'string', minLength: 1 },
   },
 };
 
-export const GATE_BASE = {
-  enabled: { type: 'boolean' },
-  baselinePath: { ...SAFE_STRING, minLength: 1 },
-  tolerance: TOLERANCE_SCHEMA,
-  floors: FLOORS_SCHEMA,
-  components: COMPONENTS_SCHEMA,
-};
+/**
+ * Build the shared four-field gate base with per-gate `default` annotations
+ * layered on (Story #5007). The base fields are identical in shape across
+ * every gate but their defaults are not — each gate ships its own
+ * `baselinePath`, tolerance, and floors — so the defaults are supplied by the
+ * calling gate module rather than baked in here.
+ *
+ * @param {{ enabled?: boolean, baselinePath?: string,
+ *   tolerance?: object, floors?: object }} [defaults]
+ * @returns {object} A fresh `properties` fragment; never a shared reference.
+ */
+export function gateBase(defaults = {}) {
+  return {
+    enabled: {
+      type: 'boolean',
+      description:
+        'When false, the checker exits 0 with a skip line and the gate is reported as `skipped`, never omitted.',
+      ...(defaults.enabled === undefined ? {} : { default: defaults.enabled }),
+    },
+    baselinePath: {
+      ...SAFE_STRING,
+      minLength: 1,
+      description:
+        "Repo-root-relative path to the gate's committed baseline artifact.",
+      ...(defaults.baselinePath === undefined
+        ? {}
+        : { default: defaults.baselinePath }),
+    },
+    tolerance: {
+      ...TOLERANCE_SCHEMA,
+      ...(defaults.tolerance === undefined
+        ? {}
+        : { default: defaults.tolerance }),
+    },
+    floors: {
+      ...FLOORS_SCHEMA,
+      ...(defaults.floors === undefined ? {} : { default: defaults.floors }),
+    },
+    components: COMPONENTS_SCHEMA,
+  };
+}

package/.agents/scripts/lib/config/github.js

@@ -61,7 +61,6 @@ export const NOTIFICATIONS_DEFAULTS = Object.freeze({
     'operator-message',
     'merge.unlanded',
     'merge.flip-failed',
-    'loop.tick',
   ]),
 });
 

package/.agents/scripts/lib/config/limits.js

@@ -6,7 +6,6 @@
  * `planning.*` and `delivery.*`:
  *
  *   - `delivery.execution.timeoutMs` (per-process execution timeout)
- *   - `delivery.lease.ttlMs` (assignee-as-lease staleness window — Story #3480)
  *   - `delivery.signals.{rework, retry}` (performance-signal detector
  *     thresholds — `hotspot` retired with Epic #4406; `churn`/`idle` dropped)
  *
@@ -14,7 +13,9 @@
  *   - `maxTickets` — decomposer reviewability budget (Story #4163)
  *
  * Dropped entirely: `maxInstructionSteps`, `friction.*`, `executionMaxBuffer`,
- * `signals.{churn, idle}`, `delivery.preflight`, `delivery.maxTokenBudget`
+ * `signals.{churn, idle}`, `delivery.preflight`, `delivery.lease.ttlMs`
+ * (Story #5006 deleted the lease TTL: with no heartbeat source every foreign
+ * claim read live, so the window decided nothing), `delivery.maxTokenBudget`
  * (planning no longer sizes against a token-budget envelope; session-mass
  * ceilings are absolute in `DEFAULT_MODEL_CAPACITY`), and
  * `planning.context.{maxBytes, summaryMode}` (Story #4541 — the `applyBudget`
@@ -39,26 +40,12 @@ export const SIGNALS_DEFAULTS = Object.freeze({
   retry: Object.freeze({ repeatCount: 3 }),
 });
 
-/**
- * Default TTL for the assignee-as-lease primitive (Story #3480). A claim
- * whose owner's last heartbeat is older than this window is considered stale
- * and may be reclaimed by another operator.
- *
- * Note: no shipped caller supplies a real heartbeat — the emitter was inert
- * and was deleted (A22), so the guards anchor liveness to `now` and every
- * foreign claim reads live (fail-closed; clear a stranded claim with
- * `--steal`). This value is therefore only consulted by a caller that threads
- * its own `heartbeatAt`, and is kept as the documented default for that seam.
- */
-export const LEASE_TTL_MS_DEFAULT = 900000;
-
 /**
  * Framework defaults for the surviving limits surface.
  */
 export const LIMITS_DEFAULTS = Object.freeze({
   maxTickets: 80,
   executionTimeoutMs: 600000,
-  leaseTtlMs: LEASE_TTL_MS_DEFAULT,
   signals: SIGNALS_DEFAULTS,
 });
 
@@ -94,7 +81,6 @@ function mergeSignals(userSignals) {
  * @returns {{
  *   maxTickets: number,
  *   executionTimeoutMs: number,
- *   leaseTtlMs: number,
  *   signals: ReturnType<typeof mergeSignals>,
  * }}
  */
@@ -107,13 +93,10 @@ export function resolveLimits(config) {
     delivery.execution && typeof delivery.execution === 'object'
       ? delivery.execution
       : {};
-  const lease =
-    delivery.lease && typeof delivery.lease === 'object' ? delivery.lease : {};
   return {
     maxTickets: LIMITS_DEFAULTS.maxTickets,
     executionTimeoutMs:
       execution.timeoutMs ?? LIMITS_DEFAULTS.executionTimeoutMs,
-    leaseTtlMs: lease.ttlMs ?? LIMITS_DEFAULTS.leaseTtlMs,
     signals: mergeSignals(delivery.signals),
   };
 }
@@ -141,31 +124,3 @@ export function getLimits(config) {
 export function getSignals(config) {
   return getLimits(config).signals;
 }
-
-/**
- * Resolve the assignee-as-lease TTL in milliseconds (Story #3480). Standalone
- * accessor so the `ticket-lease` module can import it without dragging the
- * whole limits surface into its bundle. Precedence:
- *
- *   1. An explicit `override` (a positive finite number) — lets a caller or
- *      test pin the TTL directly.
- *   2. `delivery.lease.ttlMs` from the resolved config.
- *   3. `LEASE_TTL_MS_DEFAULT`.
- *
- * A non-positive or non-finite override is ignored (falls through to config /
- * default) so a stray `0` can never collapse every claim to instantly-stale.
- *
- * @param {object | null | undefined} config
- * @param {number} [override]
- * @returns {number}
- */
-export function resolveLeaseTtlMs(config, override) {
-  if (
-    typeof override === 'number' &&
-    Number.isFinite(override) &&
-    override > 0
-  ) {
-    return override;
-  }
-  return getLimits(config).leaseTtlMs;
-}

package/.agents/scripts/lib/config/qa.js

@@ -0,0 +1,105 @@
+/**
+ * `qa.gherkinLint` accessor — the static Gherkin corpus gate's contract.
+ *
+ * The gate is **opt-in**: absent this block, `check-gherkin-corpus.js` reports
+ * that it is not configured and exits 0. That is not politeness. `.agents/`
+ * reaches a consumer by plain file copy, so every framework upgrade lands this
+ * gate in every project at once; a default-on corpus lint would redden the
+ * `lint` required check of every repo that happens to own a `.feature` file it
+ * never asked the framework to police.
+ *
+ * Inside the opt-in the posture inverts and the gate fails **closed** — an
+ * unresolvable parser or a scope that resolves no step definitions is an
+ * error, never a quiet pass. Both are the same blackout the gate exists to
+ * catch, wearing a different costume.
+ *
+ * Scopes are the load-bearing shape. Pooling every step root into one matcher
+ * list makes a cross-app false bind possible: a step defined only in app B's
+ * suite silently vouches for app A's feature, and the gate reports green on a
+ * corpus that cannot generate. Resolving each feature against **its own**
+ * scope's step roots makes that structurally impossible rather than merely
+ * unlikely.
+ */
+
+/**
+ * Framework defaults for the two escape hatches. `@skip` is the conventional
+ * "not meant to run" tag across cucumber-js and playwright-bdd, so it is the
+ * default exemption; the waiver list starts empty because every entry is a
+ * project-specific admission that the step index guessed wrong.
+ */
+const GHERKIN_LINT_DEFAULTS = Object.freeze({
+  exemptionTags: Object.freeze(['@skip']),
+  stepWaivers: Object.freeze([]),
+});
+
+/** Coerce a value to an array of non-empty strings. */
+function stringArray(value, fallback) {
+  if (!Array.isArray(value)) return [...fallback];
+  return value.filter((item) => typeof item === 'string' && item.length > 0);
+}
+
+/**
+ * Normalize one scope entry into `{ name, featureRoots, stepRoots }`.
+ *
+ * @param {string} name
+ * @param {object} raw
+ * @returns {{ name: string, featureRoots: string[], stepRoots: string[] }}
+ */
+function normalizeScope(name, raw) {
+  return {
+    name,
+    featureRoots: stringArray(raw?.featureRoots, []),
+    stepRoots: stringArray(raw?.stepRoots, []),
+  };
+}
+
+/**
+ * Normalize a raw `qa.gherkinLint` block.
+ *
+ * @param {object | null | undefined} raw
+ * @returns {{
+ *   scopes: Array<{ name: string, featureRoots: string[], stepRoots: string[] }>,
+ *   exemptionTags: string[],
+ *   stepWaivers: string[],
+ * } | null} `null` when the block is absent or not an object
+ */
+function resolveGherkinLint(raw) {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return null;
+  const scopesRaw =
+    raw.scopes && typeof raw.scopes === 'object' && !Array.isArray(raw.scopes)
+      ? raw.scopes
+      : {};
+  return {
+    scopes: Object.keys(scopesRaw)
+      .sort()
+      .map((name) => normalizeScope(name, scopesRaw[name])),
+    exemptionTags: stringArray(
+      raw.exemptionTags,
+      GHERKIN_LINT_DEFAULTS.exemptionTags,
+    ),
+    stepWaivers: stringArray(
+      raw.stepWaivers,
+      GHERKIN_LINT_DEFAULTS.stepWaivers,
+    ),
+  };
+}
+
+/**
+ * Read the normalized `qa.gherkinLint` contract off a resolved config.
+ *
+ * @param {object | null | undefined} config
+ * @returns {ReturnType<typeof resolveGherkinLint>}
+ */
+export function getGherkinLint(config) {
+  return resolveGherkinLint(config?.qa?.gherkinLint);
+}
+
+/**
+ * Module-private surface the suite drives directly, bundled behind one export
+ * for the same reason as `bdd-step-index.js`: `getGherkinLint` is the whole
+ * public API, and the normalizer and its defaults are how it is built.
+ */
+export const __testing = Object.freeze({
+  GHERKIN_LINT_DEFAULTS,
+  resolveGherkinLint,
+});

package/.agents/scripts/lib/config/runners.js

@@ -30,9 +30,19 @@ export const DEFAULT_DECOMPOSER = Object.freeze({
  * `verifyWaveResults` loop it claimed to bound never existed in the tree, and
  * its only reader was the retired execution-analysis CLI, which echoed the
  * number into a report rather than bounding anything.
+ *
+ * **Serialization tradeoff — `footprintGuard`.** `enforce` is the default and
+ * stays it: the file-overlap guard encodes delivery-time-only knowledge (which
+ * implementation windows are open, which Stories a foreign lease holds) that no
+ * plan-time `depends_on` edge can carry, so demoting it by default would trade
+ * a real merge-conflict class for throughput nobody asked for. `advisory`
+ * detects collisions and reports every would-be withhold but lets dispatch
+ * follow the declared edges alone — for runs whose ordering is fully declared
+ * (Story #5044).
  */
 const DEFAULT_DELIVER_RUNNER = Object.freeze({
   concurrencyCap: 3,
+  footprintGuard: 'enforce',
 });
 
 /**
@@ -51,28 +61,40 @@ export const DEFAULT_CODE_REVIEW = Object.freeze({
  *
  * @param {object | null | undefined} config
  * @returns {{
- *   deliverRunner: { concurrencyCap: number },
+ *   deliverRunner: { concurrencyCap: number, footprintGuard: 'enforce'|'advisory' },
  *   codeReview: { maxFixAttempts: number, maxFixScopeFiles: number, autoFixSeverity: 'high'|'medium' },
  *   decomposer: { concurrencyCap: number },
  * }}
  */
 export function getRunners(config) {
-  const deliverRunnerUser = config?.delivery?.deliverRunner ?? {};
-  const codeReviewUser = config?.delivery?.codeReview ?? {};
   return {
-    deliverRunner: {
-      concurrencyCap:
-        deliverRunnerUser.concurrencyCap ??
-        DEFAULT_DELIVER_RUNNER.concurrencyCap,
-    },
-    codeReview: {
-      maxFixAttempts:
-        codeReviewUser.maxFixAttempts ?? DEFAULT_CODE_REVIEW.maxFixAttempts,
-      maxFixScopeFiles:
-        codeReviewUser.maxFixScopeFiles ?? DEFAULT_CODE_REVIEW.maxFixScopeFiles,
-      autoFixSeverity:
-        codeReviewUser.autoFixSeverity ?? DEFAULT_CODE_REVIEW.autoFixSeverity,
-    },
+    deliverRunner: withDefaults(
+      DEFAULT_DELIVER_RUNNER,
+      config?.delivery?.deliverRunner,
+    ),
+    codeReview: withDefaults(DEFAULT_CODE_REVIEW, config?.delivery?.codeReview),
     decomposer: DEFAULT_DECOMPOSER,
   };
 }
+
+/**
+ * Overlay an operator's block onto the framework defaults — the per-key `??`
+ * fallback these accessors have always applied, written once.
+ *
+ * Iterating the **defaults'** keys rather than the user's is what keeps the
+ * returned shape closed: a key the framework does not define cannot reach a
+ * consumer through here even if one somehow survived AJV, so a typo degrades to
+ * the default rather than to an undefined a caller would read as configuration.
+ *
+ * @template {Record<string, unknown>} T
+ * @param {T} defaults      Frozen framework defaults.
+ * @param {object|null|undefined} user Operator block from `.agentrc`.
+ * @returns {T} A fresh object; the frozen defaults are never mutated.
+ */
+function withDefaults(defaults, user) {
+  const out = { ...defaults };
+  for (const key of Object.keys(defaults)) {
+    if (user?.[key] != null) out[key] = user[key];
+  }
+  return out;
+}

package/.agents/scripts/lib/config/temp-paths.js

@@ -13,7 +13,7 @@
  *     ├─ techspec.md
  *     ├─ manifest.md          (dispatch manifest)
  *     ├─ retro.md             (mirror of GitHub retro at Epic close)
- *     ├─ lifecycle.ndjson     (lifecycle bus ledger)
+ *     ├─ lifecycle.ndjson     (lifecycle ledger)
  *     ├─ checkpoints/...      (pre-v2 epic-runner state store; retained layout)
  *     ├─ <name>               (runArtifactPath escape hatch)
  *     └─ stories/
@@ -124,7 +124,7 @@ export function _clearMainCheckoutRootCache() {
  *
  * The shared test bootstrap (`lib/test-env.js`) sets this to a fresh
  * `os.tmpdir()` directory before spawning the test runner, so any test that
- * reaches a writer (`signals-writer`, the lifecycle `LedgerWriter`, etc.)
+ * reaches a writer (`signals-writer`, `appendLedgerEvent`, etc.)
  * *without* explicitly injecting an absolute tempRoot still resolves under
  * scratch instead of the repo's real `temp/` tree. This is the single
  * injection seam: because every path helper funnels a relative root through
@@ -573,9 +573,10 @@ function storyArtifactPath(eid, sid, name, config) {
 }
 
 /**
- * `temp/run-<eid>/lifecycle.ndjson` — append-only lifecycle bus ledger
- * (Story #2510). The LedgerWriter persists every emitted/completed/failed
- * record here; the TraceLogger renders the companion markdown from it.
+ * `temp/run-<eid>/lifecycle.ndjson` — append-only lifecycle ledger
+ * (Story #2510). `appendLedgerEvent` persists one `emitted` record here per
+ * merge-terminal outcome; Story #5024 retired the `LedgerWriter` listener and
+ * the `TraceLogger` markdown companion that preceded it.
  *
  * The path is also the canonical input the standalone `lifecycle-emit`
  * CLI feeds to `buildDefaultListenerChain` when assembling the default