mandrel 2.42.0 → 2.44.0

package/.agents/scripts/lib/orchestration/plan-run-labels/reap.js

@@ -0,0 +1,327 @@
+/**
+ * plan-run-labels/reap.js — the cohort label's end of life (Story #5189).
+ *
+ * `plan-persist` mints one `plan-run::<id>` label per run so the Stories one
+ * plan authored stay filterable in the GitHub UI. That is load-bearing while
+ * any Story in the cohort is open, and inert the moment they are all closed —
+ * but nothing expressed the second half, so the vocabulary grew one label per
+ * persist forever. A consumer repository measured 235 `plan-run::` labels out
+ * of 313 total; past that a paged label listing stops seeing the labels that
+ * sort after the pile, and every list-then-create caller starts failing.
+ *
+ * This module is the **one decision engine** behind both surfaces that act on
+ * that end of life: the per-Story close tail (automatic, incremental) and
+ * `prune-plan-run-labels.js` (manual, whole-repository). Keeping the decision
+ * here rather than in either caller is what stops the two from disagreeing
+ * about when a label is spent.
+ *
+ * **The decision.** A cohort label is reapable only when it carries at least
+ * one issue and every issue carrying it is closed. The "at least one" clause
+ * is the subtle half: a label carrying *zero* issues is indistinguishable from
+ * one an in-flight persist has just minted before creating its Stories, and
+ * deleting it would break that run. So a zero-issue label is reported under an
+ * `unreferenced` reason and reaped only under an explicit opt-in — a default
+ * sweep is safe to run concurrently with a persist.
+ *
+ * **Never load-bearing.** Both surfaces treat a reap failure as a warning.
+ * Label hygiene is a chore; nothing downstream reads the cohort label as an
+ * input (see `PLAN_RUN_LABEL_PREFIX`'s own docblock), so a failed delete costs
+ * a stale label and nothing else.
+ *
+ * @module lib/orchestration/plan-run-labels/reap
+ * @see Story #5189
+ */
+
+import { PLAN_RUN_LABEL_PREFIX } from '../plan-persist/story-ops.js';
+
+/**
+ * Why a cohort label was — or was not — judged reapable. One reason per
+ * label, so a `--json` report is auditable without re-deriving anything.
+ *
+ * - `all-closed`   — carries issues, every one closed. Reapable.
+ * - `open-stories` — at least one issue still open. Not reapable, ever.
+ * - `unreferenced` — carries no issues at all. Reapable only under the
+ *   explicit opt-in, because an in-flight persist looks exactly like this.
+ */
+export const REAP_REASONS = Object.freeze({
+  ALL_CLOSED: 'all-closed',
+  OPEN_STORIES: 'open-stories',
+  UNREFERENCED: 'unreferenced',
+});
+
+/**
+ * Is `name` a plan-run cohort label?
+ *
+ * The prefix is imported from `plan-persist/story-ops.js` rather than
+ * re-declared: minting and reaping must not be able to drift onto two
+ * different strings, which is exactly the failure a copied literal invites.
+ *
+ * @param {unknown} name
+ * @returns {boolean}
+ */
+function isPlanRunLabel(name) {
+  return typeof name === 'string' && name.startsWith(PLAN_RUN_LABEL_PREFIX);
+}
+
+/**
+ * Project an arbitrary label collection onto the sorted, de-duplicated set of
+ * cohort label names. Accepts either bare strings (a ticket's `labels[]`) or
+ * `{ name }` rows (the label listing port), so both callers hand this whatever
+ * their own read returned.
+ *
+ * @param {Array<string|{ name?: string }>} [names]
+ * @returns {string[]}
+ */
+function selectCohortLabels(names) {
+  const seen = new Set();
+  for (const raw of Array.isArray(names) ? names : []) {
+    const name = typeof raw === 'string' ? raw : raw?.name;
+    if (isPlanRunLabel(name)) seen.add(name);
+  }
+  return [...seen].sort();
+}
+
+/**
+ * Decide one cohort label.
+ *
+ * Reads through `listIssuesByLabel({ state: 'all' })` — the paginating read
+ * port — so the verdict is never a function of how many issues fit on one API
+ * page. `state` is compared case-insensitively against `closed` and anything
+ * else counts as open: an unknown state must never be read as "safe to
+ * delete".
+ *
+ * @param {{ provider: object, label: string, includeUnreferenced?: boolean }} args
+ * @returns {Promise<{
+ *   label: string,
+ *   reapable: boolean,
+ *   reason: string,
+ *   issueCount: number,
+ *   openIssues: number[],
+ * }>}
+ */
+async function decideCohortLabel({
+  provider,
+  label,
+  includeUnreferenced = false,
+}) {
+  const result = await provider.listIssuesByLabel({
+    state: 'all',
+    labels: label,
+  });
+  const issues = Array.isArray(result) ? result : [];
+  const open = issues.filter(
+    (issue) => String(issue?.state ?? '').toLowerCase() !== 'closed',
+  );
+  if (issues.length === 0) {
+    return {
+      label,
+      reapable: includeUnreferenced === true,
+      reason: REAP_REASONS.UNREFERENCED,
+      issueCount: 0,
+      openIssues: [],
+    };
+  }
+  if (open.length > 0) {
+    return {
+      label,
+      reapable: false,
+      reason: REAP_REASONS.OPEN_STORIES,
+      issueCount: issues.length,
+      openIssues: open
+        .map((issue) => issue?.number)
+        .filter((n) => Number.isInteger(n)),
+    };
+  }
+  return {
+    label,
+    reapable: true,
+    reason: REAP_REASONS.ALL_CLOSED,
+    issueCount: issues.length,
+    openIssues: [],
+  };
+}
+
+/**
+ * Decide a set of cohort labels.
+ *
+ * Sequential on purpose. The whole-repository sweep can face hundreds of
+ * labels, and a fan-out over a shared REST budget buys wall-clock at the cost
+ * of the one property an operator auditing a pile actually needs: a
+ * deterministic, label-ordered report.
+ *
+ * @param {{
+ *   provider: object,
+ *   labels: Array<string|{ name?: string }>,
+ *   includeUnreferenced?: boolean,
+ * }} args
+ * @returns {Promise<Array<object>>} one decision per cohort label, name-sorted.
+ */
+async function evaluateCohortLabels({
+  provider,
+  labels,
+  includeUnreferenced = false,
+}) {
+  const decisions = [];
+  for (const label of selectCohortLabels(labels)) {
+    decisions.push(
+      await decideCohortLabel({ provider, label, includeUnreferenced }),
+    );
+  }
+  return decisions;
+}
+
+/**
+ * Decide, then (unless `check`) delete.
+ *
+ * A delete that throws is recorded in `failed[]` and warned about rather than
+ * propagated: one unreachable label must not abandon the rest of a sweep, and
+ * on the close path it must not touch the land. A delete the provider reports
+ * as a no-op (`deleted: false` — the label was already gone) is still a
+ * success; that is what makes a re-run idempotent.
+ *
+ * @param {{
+ *   provider: object,
+ *   labels: Array<string|{ name?: string }>,
+ *   includeUnreferenced?: boolean,
+ *   check?: boolean,
+ *   onWarn?: ((message: string) => void)|null,
+ * }} args
+ * @returns {Promise<{
+ *   check: boolean,
+ *   decisions: Array<object>,
+ *   reapable: string[],
+ *   deleted: Array<{ label: string, existed: boolean }>,
+ *   failed: Array<{ label: string, detail: string }>,
+ * }>}
+ */
+async function reapCohortLabels({
+  provider,
+  labels,
+  includeUnreferenced = false,
+  check = false,
+  onWarn = null,
+}) {
+  const decisions = await evaluateCohortLabels({
+    provider,
+    labels,
+    includeUnreferenced,
+  });
+  const reapable = decisions.filter((d) => d.reapable).map((d) => d.label);
+  const deleted = [];
+  const failed = [];
+  if (check !== true) {
+    for (const label of reapable) {
+      try {
+        const outcome = await provider.deleteLabel(label);
+        deleted.push({ label, existed: outcome?.deleted !== false });
+      } catch (err) {
+        const detail = String(err?.message ?? err);
+        failed.push({ label, detail });
+        onWarn?.(`could not delete cohort label "${label}": ${detail}`);
+      }
+    }
+  }
+  return { check: check === true, decisions, reapable, deleted, failed };
+}
+
+/**
+ * The automatic surface's entry point: reap the cohort labels carried by the
+ * Story that just closed.
+ *
+ * The Story's own label set comes from `getTicket` (labels are immutable for
+ * this purpose, so a cached snapshot is fine); every *state* judgment comes
+ * from the fresh `listIssuesByLabel` read inside {@link decideCohortLabel}, so
+ * a primed ticket cache cannot make a still-open sibling look closed.
+ *
+ * A Story whose own issue has not yet registered as closed — the merge webhook
+ * that fires `Closes #<id>` is not instantaneous — simply reports
+ * `open-stories` and is left alone. Deferring is the safe direction, and the
+ * manual sweep is the backstop that collects whatever a race leaves behind.
+ *
+ * @param {{
+ *   storyId: number,
+ *   provider: object,
+ *   includeUnreferenced?: boolean,
+ *   onWarn?: ((message: string) => void)|null,
+ * }} args
+ * @returns {Promise<object>} the {@link reapCohortLabels} envelope, plus
+ *   `evaluated` — how many cohort labels the Story carried.
+ */
+export async function reapPlanRunLabelsForStory({
+  storyId,
+  provider,
+  includeUnreferenced = false,
+  onWarn = null,
+}) {
+  const ticket = await provider.getTicket(storyId);
+  const labels = selectCohortLabels(ticket?.labels);
+  if (labels.length === 0) {
+    return {
+      evaluated: 0,
+      check: false,
+      decisions: [],
+      reapable: [],
+      deleted: [],
+      failed: [],
+    };
+  }
+  const outcome = await reapCohortLabels({
+    provider,
+    labels,
+    includeUnreferenced,
+    onWarn,
+  });
+  return { evaluated: labels.length, ...outcome };
+}
+
+/**
+ * The manual surface's entry point: sweep every cohort label in the repository.
+ *
+ * Reads the whole label vocabulary through the paginating listing port and
+ * projects it onto the cohort axis here, so the sweep is bounded by what the
+ * repository actually holds rather than by an API page size.
+ *
+ * @param {{
+ *   provider: object,
+ *   includeUnreferenced?: boolean,
+ *   check?: boolean,
+ *   onWarn?: ((message: string) => void)|null,
+ * }} args
+ * @returns {Promise<object>} the {@link reapCohortLabels} envelope, plus
+ *   `totalLabels` (whole vocabulary) and `evaluated` (the cohort slice).
+ */
+export async function sweepCohortLabels({
+  provider,
+  includeUnreferenced = false,
+  check = false,
+  onWarn = null,
+}) {
+  const all = await provider.listLabels();
+  const rows = Array.isArray(all) ? all : [];
+  const labels = selectCohortLabels(rows);
+  const outcome = await reapCohortLabels({
+    provider,
+    labels,
+    includeUnreferenced,
+    check,
+    onWarn,
+  });
+  return { totalLabels: rows.length, evaluated: labels.length, ...outcome };
+}
+
+/**
+ * Test-only surface. The five helpers below compose the two exported entry
+ * points (`reapPlanRunLabelsForStory`, `sweepCohortLabels`) and have no
+ * production consumer outside this module, so exporting each one individually
+ * would advertise five API surfaces nothing imports — and `dead-exports
+ * --production` correctly reports each as dead. They are still worth unit
+ * testing per arm, which is what this barrel is for; it follows the same
+ * `__testing` idiom `git-probes.js` and `source-classifier.js` use.
+ */
+export const __testing = {
+  isPlanRunLabel,
+  selectCohortLabels,
+  decideCohortLabel,
+  evaluateCohortLabels,
+  reapCohortLabels,
+};

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 })],
+  });
 }