mandrel 2.42.0 → 2.44.0

package/.agents/scripts/prune-plan-run-labels.js

@@ -0,0 +1,218 @@
+#!/usr/bin/env node
+
+// .agents/scripts/prune-plan-run-labels.js — Story #5189.
+//
+// Sweep the repository's `plan-run::<id>` cohort labels and delete the ones
+// that are provably spent.
+//
+// The close tail reaps incrementally — one Story's own labels, as it lands —
+// which keeps a healthy repository flat but does nothing about a pile that
+// already exists, and nothing about a cohort whose last Story was closed by
+// hand rather than by a close. This is the surface that burns an accumulated
+// pile down: it reads the whole label vocabulary through the paginating
+// listing port, so what it can see is bounded by the repository rather than by
+// an API page.
+//
+// The decision is not made here — `lib/orchestration/plan-run-labels/reap.js`
+// owns it, so this sweep and the close-path reap cannot come to different
+// conclusions about when a label is spent. In short: reapable means the label
+// carries at least one issue and every one of them is closed. A label carrying
+// zero issues is NOT reapable by default, because that shape is exactly what
+// an in-flight `plan-persist` looks like between minting its label and
+// creating its Stories; `--include-unreferenced` is the explicit opt-in for an
+// operator who knows no persist is running.
+//
+// Exit codes:
+//   0  nothing reapable (or, without `--check`, the reap was performed)
+//   1  `--check` found at least one label that would be reaped
+//   2  the sweep could not run
+
+// Fail-fast if the framework's runtime deps are not installed — must be the
+// first import so the check runs before any third-party-importing sibling
+// module is evaluated (Story #3432).
+import './lib/runtime-deps/ensure-installed.js';
+import { runAsCli } from './lib/cli-utils.js';
+import { resolveConfig } from './lib/config-resolver.js';
+import { Logger } from './lib/Logger.js';
+import {
+  REAP_REASONS,
+  sweepCohortLabels,
+} from './lib/orchestration/plan-run-labels/reap.js';
+import { createProvider } from './lib/provider-factory.js';
+
+const EXIT_CLEAN = 0;
+const EXIT_WOULD_REAP = 1;
+const EXIT_CANNOT_RUN = 2;
+
+const HELP = {
+  invocation:
+    'node .agents/scripts/prune-plan-run-labels.js [--check] [--json] [--include-unreferenced] [--cwd <dir>]',
+  summary:
+    'Delete the plan-run:: cohort labels whose Stories are all closed. Never touches any other label axis, and never changes how a cohort label is minted.',
+  flags: [
+    ['--check', 'Report what would be reaped, delete nothing, exit 1 if any.'],
+    ['--json', 'Emit the report as JSON instead of text.'],
+    [
+      '--include-unreferenced',
+      'Also reap cohort labels carrying zero issues. Off by default: that shape is indistinguishable from a label an in-flight plan-persist just minted.',
+    ],
+    ['--cwd <dir>', 'Repository root to sweep. Default: process.cwd().'],
+  ],
+  notes: [
+    'Reapable = the label carries at least one issue AND every issue carrying it\nis closed. One open issue anywhere in the cohort keeps the label.',
+    'Exit codes:\n  0  clean, or reaped\n  1  --check found reapable labels\n  2  the sweep could not run',
+  ],
+};
+
+/**
+ * Parse argv into an options bag. An unknown flag is an error, never a silent
+ * no-op — a typo'd `--dry-run` must not read as "delete the labels".
+ *
+ * @param {string[]} argv
+ * @returns {{ check: boolean, json: boolean, includeUnreferenced: boolean, cwd: string }}
+ */
+export function parseArgs(argv = []) {
+  const out = {
+    check: false,
+    json: false,
+    includeUnreferenced: false,
+    cwd: null,
+  };
+  let i = 0;
+  while (i < argv.length) {
+    const arg = argv[i];
+    const value = argv[i + 1];
+    i += 1;
+    if (arg === '--check') out.check = true;
+    else if (arg === '--json') out.json = true;
+    else if (arg === '--include-unreferenced') out.includeUnreferenced = true;
+    else if (arg === '--cwd') {
+      if (typeof value !== 'string' || value.length === 0) {
+        throw new Error('--cwd requires a directory');
+      }
+      out.cwd = value;
+      i += 1;
+    } else throw new Error(`unknown flag "${arg}" (try --help)`);
+  }
+  out.cwd = out.cwd ?? process.cwd();
+  return out;
+}
+
+/**
+ * One human-readable line per cohort label, naming the reason it was kept or
+ * reaped. The reason is printed for every label, not only the reapable ones —
+ * an operator auditing a pile of 235 needs to see why the other 234 stayed.
+ *
+ * @param {object} decision
+ * @param {boolean} check
+ * @returns {string}
+ */
+function renderDecision(decision, check) {
+  if (!decision.reapable) {
+    const suffix =
+      decision.reason === REAP_REASONS.OPEN_STORIES
+        ? ` (open: ${decision.openIssues.join(', ') || 'unknown'})`
+        : '';
+    return `  · keep   ${decision.label} — ${decision.reason}${suffix}`;
+  }
+  const verb = check ? 'would reap' : 'reaped';
+  return `  · ${verb} ${decision.label} — ${decision.reason} (${decision.issueCount} closed issue(s))`;
+}
+
+/**
+ * Render the whole report as text.
+ *
+ * @param {object} report
+ * @returns {string}
+ */
+export function formatReport(report) {
+  const verb = report.check ? 'would reap' : 'reaped';
+  const count = report.check ? report.reapable.length : report.deleted.length;
+  const lines = [
+    `[prune-plan-run-labels] ${verb} ${count} of ${report.evaluated} cohort ` +
+      `label(s) (${report.totalLabels} label(s) in the repository)`,
+    ...report.decisions.map((d) => renderDecision(d, report.check)),
+  ];
+  for (const failure of report.failed) {
+    lines.push(`  ! failed  ${failure.label} — ${failure.detail}`);
+  }
+  if (report.check && report.reapable.length > 0) {
+    lines.push(
+      '',
+      'Run without --check to delete them:',
+      '  node .agents/scripts/prune-plan-run-labels.js',
+    );
+  }
+  return lines.join('\n');
+}
+
+/**
+ * The whole sweep — argv in, exit code out, report written through `writeFn`.
+ *
+ * Exported with its provider/config/output surfaces as default-parameter
+ * seams (`rules/test-seams.md`) so a test drives the *real* argv parsing,
+ * report rendering and exit-code decision against a stub provider. Without
+ * that, the only testable thing here would be a re-implementation of the
+ * decision, which is precisely the copy that drifts.
+ *
+ * @param {string[]} argv
+ * @param {{
+ *   createProviderFn?: Function,
+ *   resolveConfigFn?: Function,
+ *   writeFn?: (text: string) => void,
+ *   warnFn?: (message: string) => void,
+ * }} [seams]
+ * @returns {Promise<number>} the process exit code.
+ */
+export async function runSweep(
+  argv,
+  {
+    createProviderFn = createProvider,
+    resolveConfigFn = resolveConfig,
+    writeFn = (text) => process.stdout.write(text),
+    warnFn = (message) => Logger.warn(`[prune-plan-run-labels] ${message}`),
+  } = {},
+) {
+  let opts;
+  let report;
+  try {
+    opts = parseArgs(argv);
+    report = await sweepCohortLabels({
+      provider: createProviderFn(resolveConfigFn({ cwd: opts.cwd })),
+      includeUnreferenced: opts.includeUnreferenced,
+      check: opts.check,
+      onWarn: warnFn,
+    });
+  } catch (err) {
+    const message = err?.message ?? String(err);
+    writeFn(
+      `${JSON.stringify({ schemaVersion: '1', error: message }, null, 2)}\n`,
+    );
+    return EXIT_CANNOT_RUN;
+  }
+  writeFn(
+    opts.json
+      ? `${JSON.stringify(report, null, 2)}\n`
+      : `${formatReport(report)}\n`,
+  );
+  return report.check && report.reapable.length > 0
+    ? EXIT_WOULD_REAP
+    : EXIT_CLEAN;
+}
+
+/**
+ * CLI entry point. Returns its exit code rather than calling `process.exit()`,
+ * so `runAsCli`'s `propagateExitCode` path settles it through `flushStdio` and
+ * an unbounded report is not truncated at a pipe boundary (Story #4783).
+ *
+ * @returns {Promise<number>}
+ */
+async function main() {
+  return runSweep(process.argv.slice(2));
+}
+
+runAsCli(import.meta.url, main, {
+  source: 'prune-plan-run-labels',
+  usage: HELP,
+  propagateExitCode: true,
+});

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,26 @@ All notable changes to this project will be documented in this file.
 -->
 <!-- markdownlint-disable-file MD004 MD012 MD037 -->
 
+## [2.44.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.43.0...mandrel-v2.44.0) (2026-09-07)
+
+
+### Added
+
+* reap a plan-run cohort label once every Story carrying it is closed ([#5189](https://github.com/dsj1984/mandrel/issues/5189)) ([#5194](https://github.com/dsj1984/mandrel/issues/5194)) ([43ecacb](https://github.com/dsj1984/mandrel/commit/43ecacb7e2fa8469813174623307149cfe59a60a))
+
+
+### Fixed
+
+* **git-cleanup:** record an outcome for every remote-only branch, including the no-PR ones ([#5188](https://github.com/dsj1984/mandrel/issues/5188)) ([#5190](https://github.com/dsj1984/mandrel/issues/5190)) ([8016137](https://github.com/dsj1984/mandrel/commit/8016137e0c5e3b06fb608674cbb68a8fbf212ca8))
+* **review:** disk-probe the scoped-lint code runner so an absent biome degrades by name (refs [#5193](https://github.com/dsj1984/mandrel/issues/5193)) ([#5195](https://github.com/dsj1984/mandrel/issues/5195)) ([cc4bb41](https://github.com/dsj1984/mandrel/commit/cc4bb41a5877366f7e4e488d6d522fcfa3c2f8cd))
+
+## [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.44.0",
   "description": "Claude Code-first opinionated workflow framework: instructions, skills, rules, and SDLC workflows that govern AI coding assistants.",
   "files": [
     ".agents/",