mandrel 2.42.0 → 2.43.0

package/.agents/scripts/lib/orchestration/plan-context.js

@@ -912,6 +912,10 @@ async function gatherEnvelopeInputs({
             epic: { id: 0, title: epicTitle, body: seed },
             github: config.github ?? null,
             cwd,
+            // Story #5182 — the memory-hygiene advisory's two thresholds.
+            // They live on `planning`, not the `project` block `settings`
+            // carries, so they ride the opts bag rather than that legacy one.
+            memoryPool: config.planning?.memoryPool ?? null,
           },
         ),
       () =>

package/.agents/scripts/lib/orchestration/planning/authoring-context.js

@@ -165,7 +165,15 @@ export async function buildAuthoringContext(
       () => buildPlanningDocsContext({ seedIssueId: epic.id, settings, cwd }),
       () => verifyBddRunnerPendingTag({ cwd: PROJECT_ROOT }),
       () => scanBddScenariosBestEffort(),
-      () => buildMemoryPoolAdvisory({ cwd: PROJECT_ROOT }),
+      () =>
+        buildMemoryPoolAdvisory({
+          cwd: PROJECT_ROOT,
+          // Story #5182 — `planning.memoryPool` thresholds. Spread so an
+          // unset block, or a block setting only one key, leaves the other
+          // on its framework default rather than passing `undefined` in as
+          // a value the builder would have to re-defaults itself.
+          ...(opts.memoryPool ?? {}),
+        }),
       () =>
         fetchPriorFeedback({
           owner: githubCfg?.owner,

package/.agents/scripts/lib/orchestration/planning/memory-pool-advisory.js

@@ -19,12 +19,28 @@
  * only the attended `/memory-consolidate` pass, reading content, can tell the
  * difference. This module counts and stats; it never judges an entry.
  *
+ * **Growth, never size (Story #5182).** The second arm used to be an absolute
+ * ceiling of a hundred entries. A consolidation pass prefers `correct` over
+ * `dead` by design, so a pool that crosses a fixed ceiling stays over it
+ * forever: the nudge then fired on every plan however fresh the stamp, and a
+ * permanent recommendation is one the operator learns to ignore. The arm now
+ * measures **entries written since the last pass** — the one quantity a pass
+ * actually resets, because Step 6 records the post-rewrite entry count in the
+ * stamp as the next run's growth baseline.
+ *
+ * A stamp carrying a date but no usable `entryCount` (every stamp written
+ * before that Story) leaves growth **unmeasured**. That is not
+ * "never consolidated" — an operator did review the pool — so the growth arm
+ * simply stays silent and only the age arm can speak, until the next pass
+ * writes a baseline.
+ *
  * Detection is filesystem-only — no child processes, no `gh` probes, no
  * network. Every failure path fails soft to "no pool, no recommendation": the
  * advisory can degrade the nudge, never a plan.
  *
  * Test seams: `cwd`, `env`, `fsImpl` (node:fs-compatible `statSync` /
- * `readdirSync` / `readFileSync`), `now`, and the two thresholds.
+ * `readdirSync` / `readFileSync`), `now`, and the two thresholds
+ * (`staleAfterDays`, `growthDelta`).
  *
  * `buildMemoryPoolAdvisory` is the **only** export: the helpers below have no
  * caller outside this module, and exporting one solely for a test would add a
@@ -40,8 +56,8 @@ import * as path from 'node:path';
 /** Recommend a consolidation pass once the stamp is this old. */
 const STALE_AFTER_DAYS = 30;
 
-/** Recommend a consolidation pass once the pool holds more entries than this. */
-const ENTRY_COUNT_CEILING = 100;
+/** Recommend a pass once this many entries were written since the last one. */
+const GROWTH_DELTA = 25;
 
 /** Stamp file written by `/memory-consolidate` after its operator gate. */
 const STAMP_FILENAME = '.consolidation-stamp.json';
@@ -94,21 +110,47 @@ function resolveMemoryPoolDir({ cwd, env = process.env, homedir } = {}) {
 }
 
 /**
- * Read the consolidation stamp, returning its ISO timestamp or `null`.
- * A missing, unreadable, unparseable, or malformed stamp is indistinguishable
+ * The growth baseline a stamp records: its entry count, or `null` when it
+ * records none. `null` is *unmeasured*, never zero — a zero baseline would
+ * score every entry in the pool as newly written.
+ *
+ * @param {unknown} count
+ * @returns {number|null}
+ */
+function readBaseline(count) {
+  return Number.isInteger(count) && count >= 0 ? count : null;
+}
+
+/**
+ * Read the consolidation stamp.
+ *
+ * `at` is the ISO timestamp of the last pass, or `null` when there was none:
+ * a missing, unreadable, unparseable or date-less stamp is indistinguishable
  * from "never consolidated" — all four mean the same thing to the advisory.
+ * A stamp whose date is unusable carries no baseline either, so `baseline`
+ * follows it to `null` rather than describing a pass that cannot be dated.
+ *
+ * `baseline` is the entry count that pass left behind — the growth arm's
+ * reference point. It is `null` on a stamp that predates Story #5182 (date
+ * only) and on a malformed count, which reads as *unmeasured growth*, never
+ * as zero growth: a `0` baseline would score the whole pool as new.
  *
- * @returns {string|null}
+ * @returns {{ at: string|null, baseline: number|null }}
  */
 function readStamp({ poolDir, fsImpl }) {
+  const unstamped = { at: null, baseline: null };
   try {
     const raw = fsImpl.readFileSync(path.join(poolDir, STAMP_FILENAME), 'utf8');
     const parsed = JSON.parse(raw);
-    const value = parsed?.lastConsolidatedAt;
-    if (typeof value !== 'string' || value.length === 0) return null;
-    return Number.isNaN(Date.parse(value)) ? null : value;
+    const at = parsed.lastConsolidatedAt;
+    // `Date.parse` rejects the empty string as NaN, so this one test covers
+    // both an absent date and an unusable one.
+    if (typeof at !== 'string' || Number.isNaN(Date.parse(at))) {
+      return unstamped;
+    }
+    return { at, baseline: readBaseline(parsed.entryCount) };
   } catch {
-    return null;
+    return unstamped;
   }
 }
 
@@ -127,6 +169,83 @@ function countEntries({ poolDir, fsImpl }) {
   }
 }
 
+/**
+ * The advisory's field set, defaulted to the fail-soft "no usable pool"
+ * reading. Every return path spreads its own findings over this, so the
+ * envelope's shape is declared once — a new field cannot reach some callers
+ * and not others, which is the failure mode a per-branch object literal has.
+ *
+ * @param {object} fields
+ * @returns {{ present: boolean, entryCount: number, lastConsolidatedAt: string|null,
+ *            entriesSinceConsolidation: number|null, recommend: boolean,
+ *            reasons: string[] }}
+ */
+function envelope(fields) {
+  return {
+    present: false,
+    entryCount: 0,
+    lastConsolidatedAt: null,
+    entriesSinceConsolidation: null,
+    recommend: false,
+    reasons: [],
+    ...fields,
+  };
+}
+
+/**
+ * Collect the reasons a pool wants a consolidation pass. An empty array is
+ * the quiet verdict; the caller turns it into `recommend` and supplies the
+ * standing-down sentence, so every arm lives in one place.
+ *
+ * The two arms are independent and both are reported when both fire.
+ *
+ * @param {{ stamp: { at: string|null, baseline: number|null },
+ *           growth: number|null, now: Date|string|number,
+ *           staleAfterDays: number, growthDelta: number }} args
+ * @returns {string[]}
+ */
+function collectReasons({ stamp, growth, now, staleAfterDays, growthDelta }) {
+  const reasons = [];
+
+  if (stamp.at === null) {
+    reasons.push(
+      'no consolidation stamp — this pool has never been consolidated',
+    );
+  } else {
+    const ageDays =
+      (new Date(now).getTime() - Date.parse(stamp.at)) / MS_PER_DAY;
+    if (ageDays > staleAfterDays) {
+      reasons.push(
+        `last consolidated ${Math.floor(ageDays)} days ago (over the ${staleAfterDays}-day threshold)`,
+      );
+    }
+  }
+
+  // `growth === null` is unmeasured, not zero — a pre-#5182 stamp carries no
+  // baseline, and guessing one would re-invent the ceiling this arm replaced.
+  if (growth !== null && growth >= growthDelta) {
+    reasons.push(
+      `${growth} entries written since the last consolidation (at or over the ${growthDelta}-entry growth delta)`,
+    );
+  }
+
+  return reasons;
+}
+
+/**
+ * The sentence a quiet pool explains itself with — one per reason it is quiet,
+ * so "nothing to do" never reads the same as "nothing measurable".
+ *
+ * @param {{ growth: number|null, growthDelta: number }} args
+ * @returns {string}
+ */
+function quietReason({ growth, growthDelta }) {
+  if (growth === null) {
+    return 'memory pool is within the freshness threshold; growth is unmeasured until the next /memory-consolidate stamps an entry count';
+  }
+  return `memory pool is within both thresholds — ${growth} entries written since the last consolidation (under the ${growthDelta}-entry growth delta)`;
+}
+
 /**
  * Build the `memoryPoolAdvisory` envelope field.
  *
@@ -141,9 +260,10 @@ function countEntries({ poolDir, fsImpl }) {
  * @param {string} [opts.homedir]
  * @param {Date|string|number} [opts.now]
  * @param {number} [opts.staleAfterDays]
- * @param {number} [opts.entryCountCeiling]
+ * @param {number} [opts.growthDelta]
  * @returns {{ present: boolean, entryCount: number, lastConsolidatedAt: string|null,
- *            recommend: boolean, reasons: string[] }}
+ *            entriesSinceConsolidation: number|null, recommend: boolean,
+ *            reasons: string[] }}
  */
 export function buildMemoryPoolAdvisory({
   cwd = process.cwd(),
@@ -152,15 +272,9 @@ export function buildMemoryPoolAdvisory({
   homedir,
   now = new Date(),
   staleAfterDays = STALE_AFTER_DAYS,
-  entryCountCeiling = ENTRY_COUNT_CEILING,
+  growthDelta = GROWTH_DELTA,
 } = {}) {
-  const absent = (reason) => ({
-    present: false,
-    entryCount: 0,
-    lastConsolidatedAt: null,
-    recommend: false,
-    reasons: [reason],
-  });
+  const absent = (reason) => envelope({ reasons: [reason] });
 
   const poolDir = resolveMemoryPoolDir({ cwd, env, homedir });
   if (!poolDir) {
@@ -184,48 +298,38 @@ export function buildMemoryPoolAdvisory({
     return absent(`memory pool at ${poolDir} could not be listed`);
   }
 
-  const lastConsolidatedAt = readStamp({ poolDir, fsImpl });
-  const reasons = [];
+  const stamp = readStamp({ poolDir, fsImpl });
+  // Reported raw: a pruning pass can leave this negative, and saying the pool
+  // shrank by 7 is more use to the operator than clamping it to zero.
+  const growth = stamp.baseline === null ? null : entryCount - stamp.baseline;
+
+  const found = {
+    present: true,
+    entryCount,
+    lastConsolidatedAt: stamp.at,
+    entriesSinceConsolidation: growth,
+  };
 
   // An empty pool has nothing to consolidate, whatever the stamp says.
   if (entryCount === 0) {
-    return {
-      present: true,
-      entryCount: 0,
-      lastConsolidatedAt,
-      recommend: false,
+    return envelope({
+      ...found,
       reasons: ['memory pool is empty — nothing to consolidate'],
-    };
+    });
   }
 
-  if (lastConsolidatedAt === null) {
-    reasons.push(
-      'no consolidation stamp — this pool has never been consolidated',
-    );
-  } else {
-    const ageDays =
-      (new Date(now).getTime() - Date.parse(lastConsolidatedAt)) / MS_PER_DAY;
-    if (ageDays > staleAfterDays) {
-      reasons.push(
-        `last consolidated ${Math.floor(ageDays)} days ago (over the ${staleAfterDays}-day threshold)`,
-      );
-    }
-  }
-
-  if (entryCount > entryCountCeiling) {
-    reasons.push(
-      `${entryCount} entries (over the ${entryCountCeiling}-entry threshold)`,
-    );
-  }
+  const reasons = collectReasons({
+    stamp,
+    growth,
+    now,
+    staleAfterDays,
+    growthDelta,
+  });
 
-  return {
-    present: true,
-    entryCount,
-    lastConsolidatedAt,
+  return envelope({
+    ...found,
     recommend: reasons.length > 0,
     reasons:
-      reasons.length > 0
-        ? reasons
-        : ['memory pool is within both freshness thresholds'],
-  };
+      reasons.length > 0 ? reasons : [quietReason({ growth, growthDelta })],
+  });
 }

package/.agents/workflows/memory-consolidate.md

@@ -2,8 +2,8 @@
 description: >-
   Attended consolidation pass over this project's agent memory pool — merge
   duplicates, verify claims against the current tree, prune with operator
-  confirmation, rewrite the index, and stamp the pool so the /mandrel-plan advisory
-  goes quiet.
+  confirmation, rewrite the index, and stamp the pool with the date and entry
+  count the /mandrel-plan advisory measures its next nudge against.
 ---
 
 # /memory-consolidate [--dry-run]
@@ -93,14 +93,26 @@ pointers only, never memory content.
 Then write the receipt to `.consolidation-stamp.json` in the pool root:
 
 ```json
-{ "lastConsolidatedAt": "<ISO-8601 timestamp>" }
+{ "lastConsolidatedAt": "<ISO-8601 timestamp>", "entryCount": 42 }
 ```
 
-The `/mandrel-plan` Phase 0 advisory reads this file; until it is written, the nudge
-keeps firing. Write it **only** after Gate #2 — the stamp asserts an operator
-reviewed the pass, so writing it early makes it a lie.
+`entryCount` is the surviving non-index `*.md` count **after** the rewrite —
+count the directory, never the plan. It is the baseline the next run measures
+growth against, so a wrong number silently mis-arms the nudge.
+
+The `/mandrel-plan` Phase 0 advisory re-arms on exactly two conditions: the
+stamp aging past `planning.memoryPool.staleAfterDays` (30), or
+`planning.memoryPool.growthDelta` (25) entries written since that count. Pool
+size alone never triggers it — a pass that keeps every entry still quiets the
+nudge. A stamp with no `entryCount` leaves growth unmeasured, and only the age
+arm can speak until the next pass writes one.
+
+Write it **only** after Gate #2 — the stamp asserts an operator reviewed the
+pass, so writing it early makes it a lie.
 
 Close with counts: entries read, corrected, merged, pruned, and the new total.
+Then the forecast the operator would otherwise derive by hand: when the
+advisory next fires, and which arm reaches it first.
 
 ## Constraints
 

package/docs/CHANGELOG.md

@@ -15,6 +15,13 @@ All notable changes to this project will be documented in this file.
 -->
 <!-- markdownlint-disable-file MD004 MD012 MD037 -->
 
+## [2.43.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.42.0...mandrel-v2.43.0) (2026-09-07)
+
+
+### Added
+
+* memory-pool advisory measures growth since the last consolidation instead of an absolute entry ceiling ([#5182](https://github.com/dsj1984/mandrel/issues/5182)) ([#5183](https://github.com/dsj1984/mandrel/issues/5183)) ([cccdd69](https://github.com/dsj1984/mandrel/commit/cccdd69546e5dfb4c6d1e205423ff52f07982ade))
+
 ## [2.42.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.41.0...mandrel-v2.42.0) (2026-09-06)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mandrel",
-  "version": "2.42.0",
+  "version": "2.43.0",
   "description": "Claude Code-first opinionated workflow framework: instructions, skills, rules, and SDLC workflows that govern AI coding assistants.",
   "files": [
     ".agents/",