mandrel 2.52.0 → 2.54.0

package/.agents/scripts/lib/observability/source-classifier.js

@@ -87,6 +87,7 @@ const FRAMEWORK_SCRIPT_BASENAMES = Object.freeze([
   'bootstrap.js',
   'check-action-pinning.js',
   'check-arch-cycles.js',
+  'check-audit-attribution.js',
   'check-baseline-drift.js',
   'check-baseline-scope.js',
   'check-baselines.js',
@@ -98,6 +99,7 @@ const FRAMEWORK_SCRIPT_BASENAMES = Object.freeze([
   'check-gherkin-corpus.js',
   'check-knip-entries.js',
   'check-lifecycle-lint.js',
+  'check-pinned-override-notes.js',
   'check-schema-references.js',
   'check-test-temp-hygiene.js',
   'check-windows-git-perf.js',

package/.agents/scripts/lib/orchestration/epic-container.js

@@ -110,6 +110,33 @@ export function isEpicTicket(issue) {
   return normalizeLabels(issue?.labels).includes(TYPE_LABELS.EPIC);
 }
 
+/**
+ * Resolve the GraphQL node id an Epic's native sub-issue read addresses it by.
+ *
+ * Both casings are accepted because the field name depends on which provider
+ * method produced the object, and neither caller can tell from the value it
+ * holds: `getTicket` (and every other single-issue read) runs through
+ * `issueToTicket`, which renames `node_id` to `nodeId`, while
+ * `listIssuesByLabel` returns the REST payload **verbatim** — six consumers
+ * read its raw shape, so mapping it there would be a far wider change than
+ * the two reads that actually need the id.
+ *
+ * Returns `null` when neither name carries one. That is the load-bearing
+ * half: an absent id reaches GraphQL as `$id: ID!` = `undefined`, which the
+ * API rejects and `classifyGithubError` calls `permanent` — so the gateway
+ * rethrows with no retry and no feature-disabled fallback, and the caller
+ * degrades to the body checklist while reporting a hard API failure it never
+ * really had. Callers skip the read on a `null` instead, the same clean
+ * no-op `providers/github/board-add.js` makes with `reason: 'no-node-id'`.
+ *
+ * @param {{ nodeId?: unknown, node_id?: unknown }} epic
+ * @returns {string|null}
+ */
+export function resolveEpicNodeId(epic) {
+  const nodeId = epic?.nodeId ?? epic?.node_id;
+  return typeof nodeId === 'string' && nodeId !== '' ? nodeId : null;
+}
+
 /**
  * Render a container Epic's body.
  *

package/.agents/scripts/lib/orchestration/epic-rollup.js

@@ -40,12 +40,17 @@
  * @module lib/orchestration/epic-rollup
  * @see Story #5205
  * @see Story #5210 — fail closed on a degraded child read.
+ * @see Story #5255 — a closed child contributes no `agent::*` state.
  */
 
 import { Logger } from '../Logger.js';
 import { AGENT_LABELS, TYPE_LABELS } from '../label-constants.js';
 import { ColumnSync, LABEL_TO_COLUMN } from './column-sync.js';
-import { isEpicTicket, readEpicChildIdsFrom } from './epic-container.js';
+import {
+  isEpicTicket,
+  readEpicChildIdsFrom,
+  resolveEpicNodeId,
+} from './epic-container.js';
 import { resolveOperatorFromCandidates } from './lease-guard-shared.js';
 import { deriveParentState } from './ticketing/bulk.js';
 
@@ -54,6 +59,13 @@ import { deriveParentState } from './ticketing/bulk.js';
  * Epic carries an owner. `agent::blocked` counts: a blocked child is still
  * this operator's problem, and dropping the assignee at the moment someone
  * needs to be found would invert the signal.
+ *
+ * "Blocked" here means an **open** blocked child. `deriveParentState` stopped
+ * reading closed children's `agent::*` labels in Story #5255 — a superseded
+ * Story closed while still wearing `agent::blocked` is not someone's problem
+ * to pick up, and the stale label used to derive `agent::blocked` forever,
+ * which both held an owner on the container and pinned it open past the
+ * `derived !== DONE` bail below.
  */
 const IN_FLIGHT_STATES = new Set([
   AGENT_LABELS.EXECUTING,
@@ -68,15 +80,22 @@ const IN_FLIGHT_STATES = new Set([
  * borrow four lines would invert the dependency direction for no gain. What
  * matters is that the *reader* handed to `readEpicChildIdsFrom` behaves the
  * same on both paths, which is what keeps an Epic from being expandable but
- * unclosable.
+ * unclosable. The shared `resolveEpicNodeId` is what makes "the same" true of
+ * the id itself: the Epics reaching this reader come from
+ * `listIssuesByLabel`, whose raw REST payload carries `node_id`, while the
+ * expansion path's come from `getTicket`, whose mapped ticket carries
+ * `nodeId`.
  *
  * @param {object} provider
  * @returns {(epic: object) => Promise<number[]>}
  */
 function nativeChildReader(provider) {
   return async (epic) => {
-    if (typeof provider?._getNativeSubIssues !== 'function') return [];
-    return provider._getNativeSubIssues(epic?.nodeId, epic?.number ?? epic?.id);
+    const nodeId = resolveEpicNodeId(epic);
+    if (nodeId === null) return [];
+    return (
+      provider?._getNativeSubIssues?.(nodeId, epic?.number ?? epic?.id) ?? []
+    );
   };
 }
 

package/.agents/scripts/lib/orchestration/plan-persist/supersede-ops.js

@@ -28,6 +28,15 @@
  *      partial failure reports which tickets were and were not closed so the
  *      operator can finish by hand.
  *
+ * The close also strips the source ticket's `agent::*` label (Story #5255).
+ * A retired ticket has no agent state, and the one it kept was read as live
+ * work: `agent::blocked` is the state a Story must be in to be re-planned, so
+ * this path closes exactly the tickets carrying it, and a closed-but-blocked
+ * child pinned its container Epic open on every rollup thereafter. The
+ * derivation in `ticketing/bulk.js` now ignores closed children's labels too —
+ * that half covers the tickets already closed and the ones closed by hand;
+ * this one stops new ones being written.
+ *
  * Idempotency is keyed off the `superseded-by` structured-comment marker
  * (`upsertStructuredComment`), not a bare `postComment`, so a re-run cannot
  * double-comment.
@@ -36,6 +45,7 @@
  */
 
 import { Logger } from '../../Logger.js';
+import { AGENT_LABELS } from '../../label-constants.js';
 import {
   concurrentMap,
   FANOUT_CONCURRENCY,
@@ -55,6 +65,40 @@ const SUPERSEDED_BY_COMMENT_TYPE = 'superseded-by';
  */
 export const SUPERSEDE_CLOSE_REASON = 'not_planned';
 
+/**
+ * Every `agent::*` label, as the set the supersede close strips.
+ *
+ * A retired ticket has no agent state. `agent::done` would be the wrong
+ * substitute — the work was re-planned, never delivered — so the label is
+ * removed rather than rewritten, and the ticket ends carrying only its
+ * `type::`/domain labels and the supersede comment that explains it.
+ */
+const AGENT_STATE_LABELS = Object.freeze(Object.values(AGENT_LABELS));
+
+/**
+ * The single `updateTicket` mutation that retires a source ticket.
+ *
+ * Closing and clearing the state ride one write: two calls could leave the
+ * ticket closed but still wearing `agent::blocked`, which is the shape that
+ * pinned a container Epic open forever (Story #5255).
+ *
+ * A ticket with no `agent::*` label gets the bare close, unchanged from before
+ * that Story — `updateTicket` merges a `labels` mutation by reading the issue
+ * back, so an unconditional empty `remove` would buy a wasted round-trip per
+ * superseded ticket. `_ticketSnapshot` feeds that merge the copy
+ * `probeSourceTicket` already fetched.
+ *
+ * @param {{ labels?: unknown }} ticket The probe's fresh copy.
+ * @returns {object} Mutations for `provider.updateTicket`.
+ */
+function supersedeCloseMutations(ticket) {
+  const close = { state: 'closed', state_reason: SUPERSEDE_CLOSE_REASON };
+  const labels = Array.isArray(ticket?.labels) ? ticket.labels : [];
+  const remove = AGENT_STATE_LABELS.filter((label) => labels.includes(label));
+  if (remove.length === 0) return close;
+  return { ...close, labels: { remove }, _ticketSnapshot: ticket };
+}
+
 /**
  * Coerce one `supersedes[]` entry into `{ id, note }`.
  *
@@ -329,13 +373,22 @@ export function buildSupersedeCommentBody({
 /**
  * Resolve the live state of a source ticket.
  *
- * @returns {Promise<{ ok: true, state: string } | { ok: false, reason: string }>}
+ * The ticket itself rides along so the close can strip the `agent::*` label
+ * without a second read: `updateTicket`'s label merge takes a
+ * `_ticketSnapshot` for exactly this, and this probe has already paid for the
+ * fresh copy.
+ *
+ * @returns {Promise<{ ok: true, state: string, ticket: object } | { ok: false, reason: string }>}
  */
 async function probeSourceTicket(provider, id) {
   try {
     const ticket = await provider.getTicket(id, { fresh: true });
     if (!ticket) return { ok: false, reason: 'not-found' };
-    return { ok: true, state: String(ticket.state ?? 'open').toLowerCase() };
+    return {
+      ok: true,
+      state: String(ticket.state ?? 'open').toLowerCase(),
+      ticket,
+    };
   } catch (err) {
     return { ok: false, reason: `inaccessible: ${err.message}` };
   }
@@ -370,10 +423,7 @@ async function closeOneSupersededTicket({
         sourceTicketIds,
       }),
     );
-    await provider.updateTicket(id, {
-      state: 'closed',
-      state_reason: SUPERSEDE_CLOSE_REASON,
-    });
+    await provider.updateTicket(id, supersedeCloseMutations(probe.ticket));
     return { outcome: 'closed' };
   } catch (err) {
     return { outcome: 'failed', reason: err.message };

package/.agents/scripts/lib/orchestration/ticketing/bulk.js

@@ -401,25 +401,59 @@ async function cascadeCompletion(provider, ticketId, opts = {}) {
  * Derive the parent `agent::*` state from the composition of its children.
  *
  * Rules (Story #2676):
- * - Any child carrying `agent::blocked` → parent should be `agent::blocked`.
+ * - Any **open** child carrying `agent::blocked` → parent should be
+ *   `agent::blocked`.
  * - Otherwise, every child is `agent::done` (or closed) → parent should be
  *   `agent::done`.
- * - Otherwise, any child carrying `agent::executing` or `agent::closing` →
- *   parent should be `agent::executing`.
+ * - Otherwise, any **open** child carrying `agent::executing` or
+ *   `agent::closing` → parent should be `agent::executing`.
  * - Otherwise (e.g. all children still `agent::ready`) → return `null` to
  *   signal "leave the parent unchanged". A parent already partway through
  *   the lifecycle MUST NOT be downgraded just because one child reverted.
  *
+ * **A closed child contributes no `agent::*` state** (Story #5255). Its label
+ * records the state it was in when it stopped, not outstanding work, and
+ * nothing clears it on the way out: a Story re-planned out of `agent::blocked`
+ * is closed as superseded still wearing that label, and the blocked rule then
+ * pinned its container Epic open forever — `epic-rollup.js` bails before its
+ * close path on any derived state other than `agent::done`, so the Epic
+ * reported `pending` every run with every child long since closed. Filtering
+ * here rather than at that one call site is what also covers a child closed by
+ * hand with a stale state label attached. The all-done branch already counted
+ * `state === 'closed'` as done, so a closed child keeps exactly that meaning
+ * and loses only its vote on the other two.
+ *
  * The function is pure and exported so the rule can be exercised in
  * isolation by unit tests without dragging the cascade I/O surface in.
  *
  * @param {Array<{ labels?: string[], state?: string }>} siblings
  * @returns {string|null} A `STATE_LABELS.*` value, or `null` for no-op.
  */
+/**
+ * The labels that still describe **live** work on this child.
+ *
+ * Empty for a closed child: its `agent::*` label records the state it stopped
+ * in, not outstanding work, and the two live-state rules in
+ * {@link deriveParentState} must not read it. The all-done rule reads the
+ * child's labels directly, so a closed child keeps counting as done.
+ *
+ * Module-level rather than another local arrow inside `deriveParentState`:
+ * the CRAP baseline keys anonymous functions positionally within their
+ * enclosing scope, so adding or removing one there renumbers every later
+ * arrow and reports the shift as drift on code that did not change.
+ *
+ * @param {{ labels?: string[], state?: string }} sibling
+ * @returns {string[]}
+ */
+function liveChildLabels(sibling) {
+  if (sibling?.state === 'closed') return [];
+  return Array.isArray(sibling?.labels) ? sibling.labels : [];
+}
+
 export function deriveParentState(siblings) {
   if (!Array.isArray(siblings) || siblings.length === 0) return null;
   const labelsOf = (s) => (Array.isArray(s?.labels) ? s.labels : []);
-  if (siblings.some((s) => labelsOf(s).includes(STATE_LABELS.BLOCKED))) {
+  if (siblings.some((s) => liveChildLabels(s).includes(STATE_LABELS.BLOCKED))) {
     return STATE_LABELS.BLOCKED;
   }
   const allDone = siblings.every(
@@ -428,8 +462,8 @@ export function deriveParentState(siblings) {
   if (allDone) return STATE_LABELS.DONE;
   const anyActive = siblings.some(
     (s) =>
-      labelsOf(s).includes(STATE_LABELS.EXECUTING) ||
-      labelsOf(s).includes(STATE_LABELS.CLOSING),
+      liveChildLabels(s).includes(STATE_LABELS.EXECUTING) ||
+      liveChildLabels(s).includes(STATE_LABELS.CLOSING),
   );
   if (anyActive) return STATE_LABELS.EXECUTING;
   return null;

package/.agents/scripts/lib/pinned-override-notes.js

@@ -0,0 +1,100 @@
+/**
+ * pinned-override-notes.js — keep a load-bearing dependency note honest.
+ *
+ * `package.json` carries a `"//"` block of prose notes keyed by dotted config
+ * path. Two of them are safety notes about a pinned `overrides` entry: they
+ * record WHY the pin exists, which advisories removing it reintroduces, and
+ * that the `overrides` range and the direct `dependencies` range MUST move in
+ * lockstep because npm has no way to reference one from the other.
+ *
+ * A note like that is consulted precisely when someone is deciding whether a
+ * bump is safe — so a stale version inside it hands out wrong premises about
+ * a coupling the note itself calls a trap. Nothing enforced either claim, and
+ * both had drifted: the note described `^4.2.0` while the pin had moved twice.
+ *
+ * This module derives the checks from the `"//"` keys themselves rather than
+ * naming any package, so a second pinned override gets the same guarantee by
+ * writing its note.
+ */
+
+/** A `"//"` key that documents a pinned override, e.g. `overrides.js-yaml`. */
+const OVERRIDE_NOTE_KEY = /^overrides\.(.+)$/;
+
+/**
+ * Extract every semver range that appears literally in a note's prose.
+ *
+ * Deliberately permissive about the surrounding words — a note is prose, and
+ * pinning its phrasing would make it unwritable. What matters is only that
+ * the range it quotes is the range in force.
+ *
+ * Not exported: it is an implementation detail of the audit below, and its
+ * behaviour is observable through that — a note quoting only bare versions
+ * yields no `stale-note`, a note quoting a mismatched range yields one.
+ *
+ * @param {string} text
+ * @returns {string[]}
+ */
+function quotedRanges(text) {
+  if (typeof text !== 'string') return [];
+  return [...text.matchAll(/[\^~]\d+\.\d+\.\d+/g)].map((m) => m[0]);
+}
+
+/**
+ * Audit one package document's pinned-override notes.
+ *
+ * Two findings per documented override, each naming the drift rather than
+ * just asserting a mismatch:
+ *   - `lockstep` — `overrides.<name>` and `dependencies.<name>` disagree. The
+ *     companion note declares they must not; a split silently gives the
+ *     direct and transitive resolutions different floors.
+ *   - `stale-note` — the note quotes at least one range but not the one in
+ *     force, so its stated version is behind the pin it describes. A note
+ *     quoting no range at all is not scored: prose that names no version
+ *     cannot go stale.
+ *
+ * @param {{ '//'?: Record<string,string>, overrides?: Record<string,string>, dependencies?: Record<string,string> }} pkg
+ * @returns {{ findings: Array<{ kind: string, name: string, detail: string }>, checked: string[] }}
+ */
+export function auditPinnedOverrideNotes(pkg) {
+  const notes = pkg?.['//'] ?? {};
+  const overrides = pkg?.overrides ?? {};
+  const dependencies = pkg?.dependencies ?? {};
+  const findings = [];
+  const checked = [];
+
+  for (const [key, text] of Object.entries(notes)) {
+    const match = OVERRIDE_NOTE_KEY.exec(key);
+    if (!match) continue;
+    const name = match[1];
+    const pinned = overrides[name];
+    if (typeof pinned !== 'string') {
+      findings.push({
+        kind: 'orphan-note',
+        name,
+        detail: `"//"["${key}"] documents an override that no longer exists in the overrides block. Delete the note or restore the pin — a safety note for a pin nobody has is read as though the pin were still there.`,
+      });
+      continue;
+    }
+    checked.push(name);
+
+    const direct = dependencies[name];
+    if (typeof direct === 'string' && direct !== pinned) {
+      findings.push({
+        kind: 'lockstep',
+        name,
+        detail: `overrides.${name} is "${pinned}" but dependencies.${name} is "${direct}". The "//" note declares these move in lockstep; a split gives the direct and transitive resolutions different floors.`,
+      });
+    }
+
+    const quoted = quotedRanges(text);
+    if (quoted.length > 0 && !quoted.includes(pinned)) {
+      findings.push({
+        kind: 'stale-note',
+        name,
+        detail: `"//"["${key}"] quotes ${quoted.map((q) => `"${q}"`).join(', ')} but the pin in force is "${pinned}". The note is what tells the next author whether a bump is safe, so it must state the version it is describing.`,
+      });
+    }
+  }
+
+  return { findings, checked };
+}

package/.agents/scripts/resolve-stories.js

@@ -39,6 +39,7 @@ import { parseArgs } from 'node:util';
 import { runAsCli } from './lib/cli-utils.js';
 import { resolveConfig } from './lib/config-resolver.js';
 import { Logger, routeAllOutputToStderr } from './lib/Logger.js';
+import { resolveEpicNodeId } from './lib/orchestration/epic-container.js';
 import { expandEpicIds } from './lib/orchestration/epic-expansion.js';
 import {
   buildStoriesEnvelope,
@@ -98,15 +99,20 @@ export function resolveStoriesProvider({
  * Injected into `expandEpicIds` so the lib layer stays provider-agnostic,
  * exactly as `paginate` is injected into `readNativeBlockedBy`. A provider
  * without the GraphQL surface yields `[]`, and the Epic body's checklist
- * carries the children on its own.
+ * carries the children on its own — as does an Epic carrying no resolvable
+ * node id, which `resolveEpicNodeId` reports rather than letting an
+ * `undefined` reach the API as a rejected `ID!` variable.
  *
  * @param {object} provider
  * @returns {(epic: object) => Promise<number[]>}
  */
 export function nativeChildReader(provider) {
   return async (epic) => {
-    if (typeof provider?._getNativeSubIssues !== 'function') return [];
-    return provider._getNativeSubIssues(epic?.nodeId, epic?.number ?? epic?.id);
+    const nodeId = resolveEpicNodeId(epic);
+    if (nodeId === null) return [];
+    return (
+      provider?._getNativeSubIssues?.(nodeId, epic?.number ?? epic?.id) ?? []
+    );
   };
 }
 

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

@@ -2,8 +2,7 @@
 description: >-
   The deliver path's one bundled framework read: dispatch decision, engine
   invariants, the change-set/ceremony incantation, the acceptance-eval gate,
-  the credited full-suite run, and the terminal envelope contract — the
-  engine reads one file, not the helper/schema set, each session.
+  the credited full-suite run, and the terminal envelope contract.
 ---
 
 # Deliver digest (read once per session)
@@ -123,14 +122,13 @@ node <main-repo>/.agents/scripts/evidence-gate.js --standalone \
   --scope-id <storyId> --gate test --worktree <workCwd> -- npm test
 ```
 
-Dispatch it in the **background**: it outruns the host's synchronous Bash
-ceiling, and its completion re-invokes you. Never spawn a task to poll or
+Dispatch it in the **background**: it outruns the host's sync Bash ceiling, and its completion re-invokes you. Never spawn a task to poll or
 `sleep`-loop against it ([`parallel-tooling.md`](parallel-tooling.md)
 Rule 2).
 
 Read the **output**, not the exit code: capture skips — no test run, no
-credit — when nothing changed under the CRAP `targetDirs`, so run the suite
-yourself before handing off.
+credit — when nothing changed under the CRAP `targetDirs`. Run the scoped
+projects for the roots you changed plus `verify[]`, not the whole suite.
 
 `verify[]` is scoped entries **plus** this one run: an entry that is itself a
 full-suite command is reported credited against the same stamp, never

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

@@ -309,8 +309,11 @@ children at both per-Story lifecycle edges — the `agent::executing` flip in
 `epicRollup` step) — which is why it holds at **N=1**, where no epilogue runs.
 
 - **Status** follows the children's composition (`deriveParentState` mapped
-  onto the board's three options): any child executing or blocked → `In
-  Progress`, every child `agent::done` or closed → `Done`. It is written
+  onto the board's three options): any **open** child executing or blocked →
+  `In Progress`, every child `agent::done` or closed → `Done`. A **closed**
+  child contributes no `agent::*` state at all — its label records where it
+  stopped, and a superseded Story closed still wearing `agent::blocked` used
+  to pin its container open forever. It is written
   **directly**, never via a label: the container carries no `agent::*` label
   by construction, which is what keeps it out of the bare `/mandrel-deliver`
   ready list.

package/.agents/workflows/helpers/plan-reference.md

@@ -598,7 +598,7 @@ link that makes the history readable.
 
 | Behaviour | Contract |
 | --- | --- |
-| Default | Comment + close every source ticket as `not_planned`. |
+| Default | Comment + close every source ticket as `not_planned`, **clearing its `agent::*` label** in the same write — a retired ticket has no agent state, and `agent::done` would claim a delivery that never happened. |
 | `--no-close-superseded` | Skips all commenting and closing. Story creation is unchanged. Use it for a genuinely partial supersede — when the plan folded in only *part* of an issue and the remainder must stay open. |
 | `--dry-run` | Posts no comment and closes nothing; reports what it would have done. |
 | Re-run | Idempotent — the comment is keyed off a `superseded-by` structured-comment marker, and an already-closed source is skipped. |

package/docs/CHANGELOG.md

@@ -15,6 +15,26 @@ All notable changes to this project will be documented in this file.
 -->
 <!-- markdownlint-disable-file MD004 MD012 MD037 -->
 
+## [2.54.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.53.0...mandrel-v2.54.0) (2026-09-09)
+
+
+### Fixed
+
+* a closed child pins its container Epic open forever: the rollup reads its stale agent::* label, and the supersede close is what writes one ([#5255](https://github.com/dsj1984/mandrel/issues/5255)) ([#5256](https://github.com/dsj1984/mandrel/issues/5256)) ([672428f](https://github.com/dsj1984/mandrel/commit/672428f1e0fba1388a1a001d2840e7eb827b9373))
+
+## [2.53.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.52.0...mandrel-v2.53.0) (2026-09-09)
+
+
+### Added
+
+* a red SCA check says whose defect it is, and the js-yaml override's load-bearing note can no longer drift from the pin it describes ([#5248](https://github.com/dsj1984/mandrel/issues/5248)) ([#5250](https://github.com/dsj1984/mandrel/issues/5250)) ([38f4c3a](https://github.com/dsj1984/mandrel/commit/38f4c3a6acbf6e5a0bb6f9586c5a04c1f3abed02))
+* close stops paying for whole-repo work already done: the lint gate resolves project.commands.lint, and coverage-capture announces (or refuses) an uncredited full-suite run before it spawns one ([#5244](https://github.com/dsj1984/mandrel/issues/5244)) ([#5245](https://github.com/dsj1984/mandrel/issues/5245)) ([bb4216c](https://github.com/dsj1984/mandrel/commit/bb4216cf1f443ebeb3bac6a22171fffa107d028d))
+
+
+### Fixed
+
+* epic rollup's native sub-issue read passes an undefined node id, degrading every Epic's child list ([#5251](https://github.com/dsj1984/mandrel/issues/5251)) ([#5252](https://github.com/dsj1984/mandrel/issues/5252)) ([5da2df5](https://github.com/dsj1984/mandrel/commit/5da2df5322a8527c33cd4ebafa4584bdfedf867d))
+
 ## [2.52.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.51.0...mandrel-v2.52.0) (2026-09-08)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mandrel",
-  "version": "2.52.0",
+  "version": "2.54.0",
   "description": "Claude Code-first opinionated workflow framework: instructions, skills, rules, and SDLC workflows that govern AI coding assistants.",
   "files": [
     ".agents/",
@@ -33,7 +33,7 @@
     "baselines:scope": "node .agents/scripts/check-baseline-scope.js",
     "baselines:prune": "node .agents/scripts/prune-baseline-orphans.js",
     "lint:md": "markdownlint-cli2 \".agents/**/*.md\" \"*.md\" \"!node_modules/**\" \"!.worktrees/**\"",
-    "lint": "node .agents/scripts/run-lint.js && node .agents/scripts/check-generated-validator.js --check && npm run docs:check",
+    "lint": "node .agents/scripts/run-lint.js && node .agents/scripts/check-generated-validator.js --check && node .agents/scripts/check-pinned-override-notes.js && npm run docs:check",
     "docs:gen": "node .agents/scripts/generate-config-docs.js && node .agents/scripts/generate-workflows-doc.js && node .agents/scripts/generate-lens-checklists.js",
     "docs:check": "node .agents/scripts/generate-config-docs.js --check && node .agents/scripts/generate-workflows-doc.js --check && node .agents/scripts/generate-lens-checklists.js --check && node .agents/scripts/check-doc-links.js && npm run skills:check",
     "skills:index": "node .agents/scripts/generate-skills-index.js",
@@ -110,7 +110,7 @@
   "dependencies": {
     "ajv": "^8.20.0",
     "ajv-formats": "^3.0.1",
-    "js-yaml": "^4.3.1",
+    "js-yaml": "^4.3.2",
     "minimatch": "^10.0.0",
     "picomatch": "^4.0.4",
     "typhonjs-escomplex": "^0.1.0"
@@ -129,11 +129,11 @@
   },
   "//": {
     "peerDependencies.@cucumber/gherkin": "OPTIONAL peer, mirroring the `typescript` precedent, and deliberately NOT a runtime dependency. `check-gherkin-corpus.js` is the only consumer and it is opt-in behind `qa.gherkinLint`, so a consumer with no BDD tier must gain nothing from an upgrade. The devDependency alongside it is what lets this repository's own suite drive the real parser. The gate resolves it through a require path anchored at the consumer project — `.agents/` reaches a consumer by plain file copy, so a bare specifier would resolve against the consumer's module chain, which under a non-hoisting linker need not hold it.",
-    "overrides.js-yaml": "COUPLED to devDependencies.markdownlint-cli2 — do not bump either alone, and do NOT drop this override. It is load-bearing: markdownlint-cli2 0.22.x pulls js-yaml 4.1.1, which carries GHSA-52cp-r559-cp3m (high) and GHSA-h67p-54hq-rp68 (moderate); removing the override was measured to reintroduce both (1 high + 1 moderate), while with it in place `npm audit` is clean. An npm override also wins over a transitive package's own pin, so this tree-wide ^4.2.0 is imposed on every js-yaml consumer regardless of what they declare — and markdownlint-cli2 0.23.x declares an exact js-yaml 5.2.1. A dry-run bump confirmed the trap: markdownlint-cli2 0.23.1 resolves against js-yaml 4.3.0, two majors off what it declares, silently. The only safe move is to raise this override and bump markdownlint-cli2 in ONE reviewed commit (first confirming cosmiconfig, under @commitlint/cli, tolerates the same major). renovate.json excludes markdownlint-cli2 from devDependency auto-merge so that pair cannot drift apart unattended.",
+    "overrides.js-yaml": "COUPLED to devDependencies.markdownlint-cli2 — do not bump either alone, and do NOT drop this override. It is load-bearing: markdownlint-cli2 0.22.x pulls js-yaml 4.1.1, which carries GHSA-52cp-r559-cp3m (high) and GHSA-h67p-54hq-rp68 (moderate); removing the override was measured to reintroduce both (1 high + 1 moderate), while with it in place `npm audit` is clean. An npm override also wins over a transitive package's own pin, so this tree-wide ^4.3.2 is imposed on every js-yaml consumer regardless of what they declare — and markdownlint-cli2 0.23.x declares an exact js-yaml 5.2.1. A dry-run bump confirmed the trap: markdownlint-cli2 0.23.1 resolves against js-yaml 4.3.0, two majors off what it declares, silently. The only safe move is to raise this override and bump markdownlint-cli2 in ONE reviewed commit (first confirming cosmiconfig, under @commitlint/cli, tolerates the same major). renovate.json excludes markdownlint-cli2 from devDependency auto-merge so that pair cannot drift apart unattended. The floor has since been raised twice for advisories against the pinned range itself (most recently to ^4.3.2 for GHSA-2883-xcg3-v3hh, whose fix is 4.3.2) — raising it is safe and does NOT touch the coupling above; check-pinned-override-notes.js now fails the build if this sentence and the pin disagree.",
     "dependencies.js-yaml": "States the SAME range as overrides.js-yaml above. The two are deliberate duplicates — npm has no way to reference the direct range from the overrides block — so they MUST move in lockstep; changing one without the other silently splits the direct and transitive resolutions."
   },
   "overrides": {
-    "js-yaml": "^4.3.1",
+    "js-yaml": "^4.3.2",
     "markdown-it": "^14.2.0"
   }
 }