mandrel 2.44.0 → 2.46.0

package/.agents/scripts/lib/gh-exec.js

@@ -158,6 +158,35 @@ export class GhGraphqlError extends GhExecError {
   }
 }
 
+/**
+ * Render a `gh` failure as one operator-legible line: the error message plus
+ * the reason `gh` itself printed.
+ *
+ * Every `GhExecError` carries the captured `stderr`, but the classified
+ * message keeps only the exit status — so a caller that logs `err.message`
+ * alone flattens every unclassified failure to `gh-exec: gh exited with code
+ * 1`. That is exactly what hid an HTTP 422 `description is too long` behind
+ * three identical "label ensure failed" warnings (Story #5201). `gh` prints
+ * the actionable sentence on the *last* stderr line — the leading lines are
+ * the `HTTP 422:` banner and the API URL — so that line is what is appended.
+ *
+ * Non-`GhExecError` inputs (a plain `Error` from a provider fake, a thrown
+ * string) degrade to their own message, so this is safe on any catch path.
+ *
+ * @param {unknown} err
+ * @returns {string} `"<message>: <gh stderr detail>"`, or just the message
+ *   when no stderr was captured.
+ */
+export function describeGhFailure(err) {
+  const message = String(err?.message ?? err ?? 'unknown error');
+  const lines = String(err?.stderr ?? '')
+    .split('\n')
+    .map((line) => line.trim())
+    .filter(Boolean);
+  const detail = lines.at(-1);
+  return detail ? `${message}: ${detail}` : message;
+}
+
 /**
  * Classify a non-zero `gh` invocation into the most specific typed error
  * subclass available. Pure function — no side effects, no I/O.

package/.agents/scripts/lib/orchestration/git-cleanup/phases/git-probes.js

@@ -49,6 +49,19 @@ export function listLocalBranches(cwd) {
  * Pure: strip the `<remote>/` prefix off a remote-ref listing and drop the
  * symbolic `HEAD` entry.
  *
+ * `HEAD` arrives under two spellings. `%(refname:lstrip=3)` renders
+ * `refs/remotes/origin/HEAD` as the literal `HEAD`, but
+ * `%(refname:short)` — what both callers ask for — shortens it to the bare
+ * remote name `origin`, because git keeps the remote segment only when the
+ * result would otherwise be ambiguous. Missing that second spelling leaked
+ * a phantom `origin` candidate into the remote-only sweep, which the reap
+ * phase then reported as `already gone`.
+ *
+ * Both spellings are rejected **before** the prefix strip, because the
+ * strip is what makes them ambiguous: a real branch named `origin` lists
+ * as `origin/origin` and strips to `origin` too. Discriminating on the raw
+ * line keeps that branch reapable while still dropping the symbolic ref.
+ *
  * Shared by {@link listRemoteBranches} and {@link listRemoteMergedBranches}
  * so both enumerations speak the same short-name vocabulary the planner's
  * remote-only walk keys on — a divergence there would make the ancestry
@@ -64,8 +77,9 @@ function shortRemoteNames(stdout, remoteName) {
     .split('\n')
     .map((l) => l.trim())
     .filter(Boolean)
+    .filter((l) => l !== 'HEAD' && l !== remoteName)
     .map((l) => (l.startsWith(prefix) ? l.slice(prefix.length) : l))
-    .filter((b) => b && b !== 'HEAD');
+    .filter(Boolean);
 }
 
 /* node:coverage ignore next */

package/.agents/scripts/lib/orchestration/plan-persist/epic-ops.js

@@ -16,6 +16,7 @@
 
 import { createHash } from 'node:crypto';
 import { linkStoriesToEpic } from '../../../providers/github/sub-issue-add.js';
+import { describeGhFailure } from '../../gh-exec.js';
 import { Logger } from '../../Logger.js';
 import { LABEL_COLORS, TYPE_LABELS } from '../../label-constants.js';
 import { composeEpicBody } from '../epic-container.js';
@@ -103,8 +104,9 @@ async function ensureEpicLabel({ provider }) {
     return true;
   } catch (err) {
     Logger.warn(
-      `[plan-persist] "${TYPE_LABELS.EPIC}" label ensure failed (${err.message}) — ` +
-        'skipping the container Epic. The Stories are unaffected and deliver by id.',
+      `[plan-persist] "${TYPE_LABELS.EPIC}" label ensure failed ` +
+        `(${describeGhFailure(err)}) — skipping the container Epic. ` +
+        'The Stories are unaffected and deliver by id.',
     );
     return false;
   }

package/.agents/scripts/lib/orchestration/plan-persist/run-plan-persist.js

@@ -632,10 +632,20 @@ function logEffectiveRoute(route, isLiteRoute) {
  * Log the operator-facing persist epilogue: adoption, the ready primary, the
  * deliver command, and the cohort grouping label.
  *
- * @param {{ created: object[], primary: object, planRunLabel: string }} args
+ * @param {{
+ *   created: object[],
+ *   primary: object,
+ *   planRunLabel: string,
+ *   planRunLabelApplied: boolean,
+ * }} args
  * @returns {void}
  */
-function logPersistEpilogue({ created, primary, planRunLabel }) {
+function logPersistEpilogue({
+  created,
+  primary,
+  planRunLabel,
+  planRunLabelApplied,
+}) {
   const adopted = created.filter((story) => story.adopted);
   if (adopted.length > 0) {
     Logger.info(
@@ -652,10 +662,15 @@ function logPersistEpilogue({ created, primary, planRunLabel }) {
   );
   // Metadata only — a GitHub filter for the cohort this run authored, never
   // a delivery-resolution input (/mandrel-deliver stays ids-only, Story #4540).
-  Logger.info(
-    `[plan-persist] Cohort grouping label: ${planRunLabel} — filter with ` +
-      `label:${planRunLabel}`,
-  );
+  // Gated on the ensure result: the label ensure degrades non-fatally, and
+  // advertising a filter GitHub just refused to create is worse than saying
+  // nothing (Story #5201). The derived id survives in the result envelope.
+  if (planRunLabelApplied) {
+    Logger.info(
+      `[plan-persist] Cohort grouping label: ${planRunLabel} — filter with ` +
+        `label:${planRunLabel}`,
+    );
+  }
 }
 
 /**
@@ -800,11 +815,12 @@ export async function runPlanPersist({
   const isLiteRoute = route?.route === 'lite';
   logEffectiveRoute(route, isLiteRoute);
 
-  const { created, planRunLabel } = await createStoryIssues({
-    provider,
-    stories,
-    opts: { dryRun, routeLabel: isLiteRoute ? LITE_ROUTE_LABEL : null },
-  });
+  const { created, planRunLabel, planRunLabelApplied } =
+    await createStoryIssues({
+      provider,
+      stories,
+      opts: { dryRun, routeLabel: isLiteRoute ? LITE_ROUTE_LABEL : null },
+    });
 
   const primary = created[0];
   const waveTable = buildWaveTable(
@@ -883,7 +899,12 @@ export async function runPlanPersist({
   supersede.sourceTicketOrigin = sourceTicketOrigin;
 
   await cleanupPlanDirs({ config, planDir, skipCleanup });
-  logPersistEpilogue({ created, primary, planRunLabel });
+  logPersistEpilogue({
+    created,
+    primary,
+    planRunLabel,
+    planRunLabelApplied,
+  });
 
   return {
     stories: created,

package/.agents/scripts/lib/orchestration/plan-persist/story-ops.js

@@ -22,6 +22,7 @@ import {
   ownedProvenanceSource,
 } from '../../findings/provenance-field.js';
 import { carryProvenanceFooters } from '../../findings/route-finding.js';
+import { describeGhFailure } from '../../gh-exec.js';
 import { Logger } from '../../Logger.js';
 import { AGENT_LABELS, TYPE_LABELS } from '../../label-constants.js';
 import {
@@ -902,8 +903,8 @@ async function ensurePersistLabel({
     return true;
   } catch (err) {
     Logger.warn(
-      `[plan-persist] ${role} label ensure failed (${err.message}) — ` +
-        'creating the Stories without it. Add the label by hand if you ' +
+      `[plan-persist] ${role} label ensure failed (${describeGhFailure(err)})` +
+        ' — creating the Stories without it. Add the label by hand if you ' +
         'want it.',
     );
     return false;
@@ -978,6 +979,7 @@ async function ensurePersistLabel({
  *   created: Array<{ slug: string, id: number, url?: string, title: string, adopted: boolean }>,
  *   dependencyEdges: { edgesAdded: number, edgesSkipped: number, edgesFailed: number, storiesProcessed: number }|null,
  *   planRunLabel: string,
+ *   planRunLabelApplied: boolean,
  *   routeLabel: string|null,
  * }>}
  */
@@ -1012,6 +1014,10 @@ export async function createStoryIssues({ provider, stories, opts = {} }) {
       })),
       dependencyEdges: null,
       planRunLabel: cohortLabel,
+      // A dry run writes nothing, so nothing was ensured and nothing carries
+      // the label — the derived id is still reported, the application is not
+      // claimed.
+      planRunLabelApplied: false,
       routeLabel,
     };
   }
@@ -1021,8 +1027,8 @@ export async function createStoryIssues({ provider, stories, opts = {} }) {
     label: cohortLabel,
     color: PLAN_RUN_LABEL_COLOR,
     description:
-      'Groups the Stories one /mandrel-plan persist run authored (metadata ' +
-      'only — /mandrel-deliver stays ids-only).',
+      'Groups the Stories one /mandrel-plan persist run authored — ' +
+      'metadata only, never a deliver input.',
     role: 'cohort',
   });
   const applyRouteLabel =
@@ -1032,8 +1038,8 @@ export async function createStoryIssues({ provider, stories, opts = {} }) {
       label: routeLabel,
       color: LITE_ROUTE_LABEL_COLOR,
       description:
-        'Ceremony-lite hint (human-visible only): /mandrel-deliver re-derives the ' +
-        'route from the Story body shape; every close gate runs unchanged.',
+        'Ceremony-lite hint only: /mandrel-deliver re-derives the route; ' +
+        'every close gate still runs.',
       role: 'route-marker',
     }));
 
@@ -1111,7 +1117,12 @@ export async function createStoryIssues({ provider, stories, opts = {} }) {
   return {
     created,
     dependencyEdges,
+    // The derived id and whether it actually landed are separate facts. The id
+    // is reported either way (a resumed persist re-derives it, and the
+    // dry-run path reports it write-free); the flag is what an epilogue must
+    // consult before advertising a `label:` filter that may match nothing.
     planRunLabel: cohortLabel,
+    planRunLabelApplied: applyCohortLabel,
     routeLabel: applyRouteLabel ? routeLabel : null,
   };
 }

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

@@ -83,6 +83,46 @@ export function isLabelNotFoundError(err) {
   );
 }
 
+/**
+ * GitHub's cap on a label description. A longer one is refused with an HTTP
+ * 422 that `gh label create` reports as a bare exit 1 — a deterministic
+ * create failure, never a truncation. Lives here rather than in the
+ * provider-agnostic label vocabulary because it is an API constraint of this
+ * provider (Story #5201, where two over-long `plan-persist` descriptions made
+ * the `plan-run::<id>` cohort label uncreatable on every run).
+ */
+// Module-private on purpose: nothing in production reads the number outside
+// the guard below, and the suite pins GitHub's published cap as a literal
+// rather than against our own constant.
+const LABEL_DESCRIPTION_MAX_LENGTH = 100;
+
+/**
+ * Refuse a label description GitHub will reject anyway, **before** `gh` is
+ * spawned.
+ *
+ * The API caps a description at {@link LABEL_DESCRIPTION_MAX_LENGTH}
+ * characters and answers a longer one with an HTTP 422 that `gh label create`
+ * surfaces as a bare exit 1 — legible only to a caller that digs the reason
+ * out of stderr. Failing at the call site instead names the label and its
+ * actual length, so the fix is obvious from the message alone.
+ *
+ * Deliberately a throw rather than a silent truncation: a truncated
+ * description is a label whose text nobody chose, and every `ensureLabels`
+ * caller already handles a throw — the bootstrap paths surface it, and
+ * `plan-persist` degrades to creating its Stories without the cosmetic label.
+ *
+ * @param {{ name?: string, description?: string }} def
+ * @throws {Error} when the description exceeds the cap.
+ */
+function assertLabelDescriptionWithinCap(def) {
+  const description = def?.description ?? '';
+  if (description.length <= LABEL_DESCRIPTION_MAX_LENGTH) return;
+  throw new Error(
+    `label "${def?.name}" description is ${description.length} characters; ` +
+      `GitHub rejects anything over ${LABEL_DESCRIPTION_MAX_LENGTH}`,
+  );
+}
+
 export class LabelGateway {
   /**
    * @param {{ gh: object, owner: string, repo: string }} deps
@@ -94,7 +134,10 @@ export class LabelGateway {
   }
 
   /**
-   * Idempotent label creation. For each labelDef, attempt `gh label create
+   * Idempotent label creation. Each def's description is checked against
+   * GitHub's length cap first (`assertLabelDescriptionWithinCap`) so a
+   * guaranteed-422 create never reaches the network. Then, for each labelDef,
+   * attempt `gh label create
    * <name> --color <hex> --description <text>`. The CLI prints
    * "label already exists" (or the API surfaces a 422 "already_exists"
    * error) when the name is taken; we swallow that and count it as
@@ -114,6 +157,7 @@ export class LabelGateway {
     const created = [];
     const skipped = [];
     for (const def of labelDefs) {
+      assertLabelDescriptionWithinCap(def);
       const color = (def.color ?? '').replace(/^#/, '');
       try {
         await withTransientRetry(() =>

package/docs/CHANGELOG.md

@@ -15,6 +15,20 @@ All notable changes to this project will be documented in this file.
 -->
 <!-- markdownlint-disable-file MD004 MD012 MD037 -->
 
+## [2.46.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.45.0...mandrel-v2.46.0) (2026-09-07)
+
+
+### Fixed
+
+* keep every shipped label description under GitHub's 100-char limit, and make a refused ensure legible ([#5201](https://github.com/dsj1984/mandrel/issues/5201)) ([#5202](https://github.com/dsj1984/mandrel/issues/5202)) ([f444ac6](https://github.com/dsj1984/mandrel/commit/f444ac62255b25fc44603f5603f128083ae327fa))
+
+## [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)
 
 

package/package.json

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