mandrel 2.43.0 → 2.45.0

package/.agents/scripts/providers/github/labels.js

@@ -17,6 +17,7 @@
  */
 
 import { withTransientRetry } from './errors.js';
+import { paginateRest } from './request-helpers.js';
 
 /**
  * Detect the "label already exists" signal across the surfaces `gh label
@@ -60,6 +61,28 @@ export function isLabelAlreadyExistsError(err) {
   return false;
 }
 
+/**
+ * Detect the "label does not exist" signal on the delete path. `gh api` exits
+ * non-zero on a 404 with `gh: Not Found (HTTP 404)` on stderr; the REST body
+ * carries `"message": "Not Found"`. Both are matched, and the numeric status
+ * is matched on its own so a transport that surfaces only `err.status` still
+ * classifies.
+ *
+ * Deliberately narrow: only a 404 counts. A 403 (scope) or a 422 must stay
+ * loud, because reading either as "already gone" would let a sweep report
+ * labels as reaped that are all still there.
+ *
+ * @param {unknown} err
+ * @returns {boolean}
+ */
+export function isLabelNotFoundError(err) {
+  if (!err) return false;
+  if (err.status === 404 || err.statusCode === 404) return true;
+  return /\bHTTP\s+404\b|\bnot found\b/i.test(
+    `${err.message ?? ''} ${err.stderr ?? ''}`,
+  );
+}
+
 export class LabelGateway {
   /**
    * @param {{ gh: object, owner: string, repo: string }} deps
@@ -162,6 +185,71 @@ export class LabelGateway {
     return missing;
   }
 
+  /**
+   * List the repository's whole label vocabulary, paginated.
+   *
+   * Deliberately NOT modelled on `_reconcileLabelsPresence`'s
+   * `gh label list --limit 500`. That hard cap is fine for its own job —
+   * "are these 20 bootstrap labels present?" — and fatal for this one: a
+   * caller deciding which labels to delete from a truncated view would skip
+   * exactly the labels that sort after an accumulated pile, which is the
+   * failure Story #5189 exists to stop reproducing. `paginateRest` walks
+   * pages until a short one lands and throws (loudly) rather than truncating
+   * if the repository somehow exceeds its ceiling.
+   *
+   * Rows are projected to the fields a caller can rely on; a row without a
+   * usable `name` is dropped rather than passed on as a deletable target.
+   *
+   * @returns {Promise<Array<{ name: string, color: string|null, description: string|null }>>}
+   * @field-manifest /repos/{owner}/{repo}/labels: name, color, description
+   */
+  async listLabels() {
+    const endpoint = `/repos/${this.owner}/${this.repo}/labels`;
+    const rows = await paginateRest(this._gh, endpoint, {
+      label: `listLabels ${this.owner}/${this.repo}`,
+    });
+    return (Array.isArray(rows) ? rows : [])
+      .filter((row) => typeof row?.name === 'string')
+      .map((row) => ({
+        name: row.name,
+        color: row.color ?? null,
+        description: row.description ?? null,
+      }));
+  }
+
+  /**
+   * Delete one label by name.
+   *
+   * Goes through the REST surface (`DELETE /repos/{owner}/{repo}/labels/{name}`)
+   * rather than `gh label delete`, so the "already gone" signal arrives as a
+   * structured 404 on the same facade every other read here uses instead of
+   * as CLI prose — and so this gateway needs no new verb on the `gh` facade.
+   *
+   * A missing label resolves as a successful no-op. That is not leniency: the
+   * sweep this port exists for is expected to run repeatedly and concurrently
+   * with the close-path reap, so "someone else already deleted it" is the
+   * normal case, not an error.
+   *
+   * @param {string} name
+   * @returns {Promise<{ deleted: boolean, reason: string|null }>}
+   */
+  async deleteLabel(name) {
+    if (typeof name !== 'string' || name.trim().length === 0) {
+      throw new Error('deleteLabel: a non-empty label name is required');
+    }
+    const endpoint = `/repos/${this.owner}/${this.repo}/labels/${encodeURIComponent(name)}`;
+    try {
+      await withTransientRetry(() =>
+        this._gh.api({ method: 'DELETE', endpoint }),
+      );
+      return { deleted: true, reason: null };
+    } catch (err) {
+      if (isLabelNotFoundError(err))
+        return { deleted: false, reason: 'not-found' };
+      throw err;
+    }
+  }
+
   _normalizeLabelListResult(result) {
     if (Array.isArray(result)) return result;
     if (result && typeof result.stdout === 'string') {

package/.agents/scripts/providers/github.js

@@ -133,6 +133,8 @@ const DELEGATIONS = [
   ['getBranchProtection', 'branchProtection.getBranchProtection'],
   ['setBranchProtection', 'branchProtection.setBranchProtection'],
   ['ensureLabels', 'labels.ensureLabels'],
+  ['listLabels', 'labels.listLabels'],
+  ['deleteLabel', 'labels.deleteLabel'],
   ['_reconcileLabelsPresence', 'labels._reconcileLabelsPresence'],
   ['getMergeMethods', 'mergeMethods.getMergeMethods'],
   ['setMergeMethods', 'mergeMethods.setMergeMethods'],

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/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.45.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.44.0...mandrel-v2.45.0) (2026-09-07)
+
+
+### Fixed
+
+* **git-cleanup:** drop the symbolic HEAD ref under its short spelling ([#5197](https://github.com/dsj1984/mandrel/issues/5197)) ([98802f6](https://github.com/dsj1984/mandrel/commit/98802f6ee49b699560ab7362815e054751f3024b))
+
+## [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)
 
 

package/package.json

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