mandrel 2.51.0 → 2.53.0

package/.agents/scripts/lib/orchestration/worktree-dirty.js

@@ -0,0 +1,80 @@
+/**
+ * lib/orchestration/worktree-dirty.js — "does this branch's checkout carry
+ * uncommitted changes?" (Story #5238).
+ *
+ * Its own module because the light path's diff backstop is otherwise a pure
+ * join over two committed-state git reads, and this is the one question there
+ * that needs a third read of a *working tree*. Keeping it here leaves
+ * {@link module:lib/orchestration/light-backstop} the thin join it claims to
+ * be, and gives the probe its own place to be tested against every way a git
+ * read can fail.
+ *
+ * @module lib/orchestration/worktree-dirty
+ */
+
+import { gitSpawn } from '../git-utils.js';
+import { parseWorktreePorcelain } from '../worktree/inspector.js';
+
+/**
+ * The stdout of a successful git read, or `null` when it cannot be trusted.
+ *
+ * @param {{ status?: number, stdout?: unknown }|null|undefined} result
+ * @returns {string|null}
+ */
+function readableStdout(result) {
+  if (result?.status !== 0) return null;
+  return typeof result.stdout === 'string' ? result.stdout : null;
+}
+
+/**
+ * Locate the checkout that has `branch` checked out, or `null` when no
+ * checkout does.
+ *
+ * `git worktree list --porcelain` enumerates **every** checkout including the
+ * main one, so a repository working on the branch directly (no separate
+ * worktree) is found by this same lookup rather than by a second fallback path.
+ *
+ * @param {{ branch: string, cwd: string, gitFn: typeof gitSpawn }} args
+ * @returns {string|null}
+ */
+function resolveBranchCheckout({ branch, cwd, gitFn }) {
+  const listed = readableStdout(gitFn(cwd, 'worktree', 'list', '--porcelain'));
+  if (listed === null) return null;
+  const match = parseWorktreePorcelain(listed).find(
+    (record) => record.branch === branch,
+  );
+  return match ? match.path : null;
+}
+
+/**
+ * Does the checkout holding `branch` have uncommitted changes?
+ *
+ * **Why the light path asks.** Its diff backstop measures `base...head`, which
+ * is committed state, so a run that implemented and did not commit measures an
+ * empty change set — and the refusal then told the agent its scope was
+ * unverifiable and to escalate, when the actual fix was `git commit`. Measured
+ * in the consumer: the refusal signal is stamped 12:14:06Z and the branch's
+ * only commit 12:15:19Z (issue #5237).
+ *
+ * Total, and deliberately asymmetric: every unreadable surface — a failed
+ * `worktree list`, a branch no checkout holds, a failed `status`, a throwing
+ * git — answers `false`. A probe that cannot see the tree must not be able to
+ * talk a refusal into friendlier guidance than the evidence supports.
+ *
+ * @param {{ branch: string, cwd?: string, gitFn?: typeof gitSpawn }} args
+ * @returns {boolean}
+ */
+export function hasUncommittedWork({
+  branch,
+  cwd = process.cwd(),
+  gitFn = gitSpawn,
+} = {}) {
+  try {
+    const checkout = resolveBranchCheckout({ branch, cwd, gitFn });
+    if (checkout === null) return false;
+    const status = readableStdout(gitFn(checkout, 'status', '--porcelain'));
+    return status !== null && status.trim() !== '';
+  } catch {
+    return false;
+  }
+}

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-light.md

@@ -153,13 +153,19 @@ answer).
    number that then rejects the change. They are **not** exempt from
    sensitive-path matching, which runs over the full change set.
 
-   Exit `3` (`blocked: true`) means the diff exceeds a light ceiling or touches a
-   sensitive-path class. STOP, flip `agent::blocked`, and **recycle the receipt**
-   through the envelope's `nextCommand` (`/mandrel-plan <storyId>`) — tickets mode
-   rewrites it into properly-planned Stories and closes it as superseded. Do not
-   land, and do not leave the receipt open with no successor: it already carries
-   the branch, the worktree, and the implementation, all of which are evidence
-   the plan should read.
+   **Commit before you run it.** The backstop measures **committed** state, so
+   a run that implemented but has not committed measures an empty diff and is
+   refused for a scope it never had. That refusal names the real fix — commit
+   on `story-<id>`, then re-run the backstop — and its `nextCommand` is that
+   re-run, not an escalation.
+
+   Exit `3` (`blocked: true`) otherwise means the diff exceeds a light ceiling or
+   touches a sensitive-path class. STOP, flip `agent::blocked`, and **recycle the
+   receipt** through the envelope's `nextCommand` (`/mandrel-plan <storyId>`) —
+   tickets mode rewrites it into properly-planned Stories and closes it as
+   superseded. Do not land, and do not leave the receipt open with no successor:
+   it already carries the branch, the worktree, and the implementation, all of
+   which are evidence the plan should read.
 
 5. **Close and land (same engine).** Exactly [`/mandrel-deliver`](../mandrel-deliver.md)'s close:
 

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.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)
+
+
+### Fixed
+
+* render deliver-light refusal reasons in retro follow-ups and file each backstop refusal class as its own friction category ([#5238](https://github.com/dsj1984/mandrel/issues/5238)) ([#5239](https://github.com/dsj1984/mandrel/issues/5239)) ([65ff0ff](https://github.com/dsj1984/mandrel/commit/65ff0ff4252ddc4fe34d4d8453159a80afae6223))
+
 ## [2.51.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.50.0...mandrel-v2.51.0) (2026-09-08)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mandrel",
-  "version": "2.51.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"
   }
 }