mandrel 2.52.0 → 2.53.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

@@ -45,7 +45,11 @@
 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';
 
@@ -68,15 +72,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/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/docs/CHANGELOG.md

@@ -15,6 +15,19 @@ All notable changes to this project will be documented in this file.
 -->
 <!-- markdownlint-disable-file MD004 MD012 MD037 -->
 
+## [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.53.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"
   }
 }