mandrel 2.59.0 → 2.61.0

package/.agents/scripts/lib/mandrel-catalog.js

@@ -1,51 +1,23 @@
 /**
- * mandrel-catalog.js
- *
- * Walks `.agents/workflows/*.md` (top-level only — `helpers/` are
- * path-included modules, not slash commands) and produces the
- * Mandrel-owned slash-command catalog.
- *
- * This is the canonical catalog backend. The consumer-shipped
- * `.agents/docs/workflows.md` is generated from it by
- * `generate-workflows-doc.js`, and `npm run docs:check` gates that doc
- * against drift — same source-of-truth contract as
- * `sync-claude-commands.js`, just one layer up (catalog of what's
- * synced, not the sync itself). The retired `mandrel` discoverability
- * command used to render this catalog live; Story #3708 replaced it
- * with the gated, generated `workflows.md` so the catalog is shipped
- * and drift-checked rather than ephemeral.
- *
- * Pure functions only: no GitHub I/O, no file writes, no provider
- * factory. Callers (the doc generator, the unit test) pass an
- * absolute path to a workflows directory in; the function returns a
- * sorted array of `{ name, description }` entries plus a
- * `renderCatalog()` helper that produces a human-readable markdown
- * bullet list.
+ * mandrel-catalog.js — the slash-command catalog backend, built from
+ * top-level `.agents/workflows/*.md` (`helpers/` are not commands). The
+ * shipped `.agents/docs/workflows.md` is generated from it and drift-gated.
+ * Read-only: no GitHub I/O, no writes.
  */
 
 import fs from 'node:fs';
 import path from 'node:path';
 
 /**
- * Parse a workflow markdown file's YAML frontmatter and return its
- * `description:` field, normalized to a single-line string.
- *
- * Handles both the inline form (`description: foo bar`) and the
- * YAML folded-block form (`description: >-` followed by indented
- * continuation lines). Both forms appear in the live workflow set —
- * see `.agents/workflows/signals.md` (folded) vs.
- * `.agents/workflows/agents-bootstrap-github.md` (inline).
- *
- * Returns `null` if the file has no frontmatter or no `description:`
- * key. Returns the trimmed, whitespace-collapsed string otherwise.
+ * Frontmatter `description:` as one whitespace-collapsed line; handles both
+ * inline and folded/literal block forms.
  *
  * @param {string} source — full file contents.
  * @returns {string | null}
  */
 export function extractDescription(source) {
   if (typeof source !== 'string') return null;
-  // Frontmatter must be the first block. Match `---\n...\n---` at
-  // the start of the file; tolerate a leading BOM.
+  // Frontmatter must be the first block; tolerate a leading BOM.
   const trimmed = source.replace(/^/, '');
   if (!trimmed.startsWith('---')) return null;
   const end = trimmed.indexOf('\n---', 3);
@@ -62,53 +34,37 @@ export function extractDescription(source) {
       continue;
     }
     const rest = match[1].trim();
-    // Folded / literal block forms: `>-`, `>`, `|`, `|-`. The actual
-    // value follows on subsequent indented lines.
     if (/^[>|][-+]?\s*$/.test(rest) || rest === '') {
       const collected = [];
       let j = i + 1;
       while (j < lines.length) {
         const next = lines[j];
-        // Stop on the next top-level key (column-0 alphanumeric +
-        // colon) — that's the next frontmatter entry.
+        // Stop at the next column-0 frontmatter key.
         if (/^[A-Za-z][\w-]*\s*:/.test(next)) break;
-        // Blank line inside a folded block is permissible; keep
-        // collecting until the next top-level key.
         collected.push(next.trim());
         j += 1;
       }
       const joined = collected.join(' ').replace(/\s+/g, ' ').trim();
       return joined.length > 0 ? joined : null;
     }
-    // Inline form.
     return rest.replace(/\s+/g, ' ').trim();
   }
   return null;
 }
 
 /**
- * Heuristic: treat a description as "vague" when it carries no
- * information beyond the workflow's own name. Callers can use this to
- * nudge the maintainer when a description needs tightening — it does
- * **not** block the catalog from rendering. The
- * description-frontmatter audit pass (Task #1619 acceptance) is a
- * one-time sweep; this helper exists so the audit doesn't silently
- * regress later.
+ * Advisory nudge for a too-short description; never blocks rendering.
  *
  * @param {string | null} description
  * @returns {boolean}
  */
 export function isVagueDescription(description) {
   if (!description) return true;
-  // Fewer than 30 characters of substance is suspicious for a
-  // discoverability menu entry.
   if (description.trim().length < 30) return true;
   return false;
 }
 
 /**
- * Build the Mandrel-owned catalog from an on-disk workflows directory.
- *
  * @param {string} workflowsDir — absolute path to `.agents/workflows/`.
  * @returns {Array<{ name: string, description: string | null, vague: boolean }>}
  */
@@ -121,9 +77,7 @@ export function buildCatalog(workflowsDir) {
   const entries = fs.readdirSync(workflowsDir, { withFileTypes: true });
   const catalog = [];
   for (const entry of entries) {
-    // Only top-level .md files — `helpers/` is intentionally not in
-    // the runnable catalog (mirrors `sync-claude-commands.js`'s
-    // `isTopLevelWorkflow` filter).
+    // Top-level files only, mirroring `sync-claude-commands.js`.
     if (!entry.isFile()) continue;
     if (!entry.name.endsWith('.md')) continue;
     if (entry.name === 'README.md') continue;
@@ -141,15 +95,8 @@ export function buildCatalog(workflowsDir) {
 }
 
 /**
- * Build the loop-unit catalog from a workflows directory's `loops/`
- * namespace. Loop units live at `.agents/workflows/loops/<name>.md` and
- * project to the namespaced `/loops:<name>` slash command (Story #4289).
- * They are catalogued separately from the flat top-level commands because
- * they carry a distinct invocation form.
- *
- * Returns an empty array when the `loops/` subdirectory is absent (the
- * common case before the starter loops land in a later Story) — an absent
- * namespace is a clean "no loop units", not an error.
+ * `loops/<name>.md` units, invoked as `/loops:<name>`; an absent `loops/`
+ * directory yields `[]`, not an error.
  *
  * @param {string} workflowsDir — absolute path to `.agents/workflows/`.
  * @returns {Array<{ name: string, description: string | null, vague: boolean }>}
@@ -177,11 +124,6 @@ export function buildLoopCatalog(workflowsDir) {
 }
 
 /**
- * Render the catalog as a plain-markdown bullet list. Kept as a
- * lightweight alternative rendering of the same catalog backend that
- * `generate-workflows-doc.js` renders into the shipped
- * `.agents/docs/workflows.md` table.
- *
  * @param {Array<{ name: string, description: string | null, vague: boolean }>} catalog
  * @returns {string}
  */

package/.agents/scripts/lib/notifications/notifier.js

@@ -1,33 +1,14 @@
 /**
- * Notification helpers — shared severity vocabulary and webhook URL resolver.
+ * Notification helpers — severity vocabulary and webhook URL resolver for
+ * `notify.js`. Both channels (GitHub comments, Slack webhook) gate only on
+ * their event allowlists; severity is envelope metadata:
+ *   - low    — routine progress; `transitionTicketState` skips `notify()`.
+ *   - medium — operator-visible milestones (Story/Epic done, merged).
+ *   - high   — operator must act: webhook prefix `[Action Required]`, and
+ *              comments always `@mention` the operator.
  *
- * The unified `notify()` API in `notify.js` is the single dispatch entry
- * point for two event-allowlist-gated channels: GitHub comments
- * (`notifications.commentEvents`) and the Slack webhook
- * (`notifications.webhookEvents`). Both channels filter independently by
- * event-name membership — there is no fallback chain and severity is no
- * longer a routing factor for either channel.
- *
- * Severity vocabulary: low | medium | high. Severity is carried as
- * envelope metadata so Slack consumers can color-code by it and so
- * high-severity comments still `@mention` the operator, but it does not
- * gate channel delivery.
- *   - low    — routine pipeline progress: task transitions, story-run
- *              progress upserts. `transitionTicketState` skips the
- *              `notify()` dispatch entirely for these so the comment
- *              channel never sees them.
- *   - medium — operator-visible milestones: story / epic → done
- *              transitions, story-merged, epic milestones.
- *   - high   — operator must act: epic blockers, HITL gates,
- *              autonomous-chain failures. Webhook envelope prefix is
- *              `[Action Required]`; high-severity comments always
- *              `@mention` the operator.
- *
- * Webhook URL resolution: `process.env.NOTIFICATION_WEBHOOK_URL` only —
- * loaded from `.env` locally, the Claude Code web environment-variables UI,
- * or `ENV_FILE` on GitHub Actions. The webhook URL is never read from
- * `.agentrc.json` and (as of Epic #702) is no longer sourced from
- * `.mcp.json`.
+ * The webhook URL comes only from `process.env.NOTIFICATION_WEBHOOK_URL`,
+ * never from `.agentrc.json` or `.mcp.json`.
  */
 
 import { AGENT_LABELS } from '../label-constants.js';
@@ -35,12 +16,9 @@ import { AGENT_LABELS } from '../label-constants.js';
 export const SEVERITY_RANK = Object.freeze({ low: 0, medium: 1, high: 2 });
 
 /**
- * Compute the severity of a ticket-state-transition event.
- *
- * Today only Story or Epic tickets reaching `agent::done` rate `medium`;
- * every other transition (intermediate or task-level) is `low`. State-
- * transition events never reach `high` — that level is reserved for
- * explicit `notify()` calls signalling operator action is required.
+ * Only a Story/Epic reaching `agent::done` rates `medium`; transitions never
+ * reach `high`, which is reserved for explicit operator-action `notify()`
+ * calls.
  *
  * @param {{ kind?: string, ticket?: { type?: string }, toState?: string|null }} event
  */
@@ -53,10 +31,7 @@ export function eventSeverity(event) {
   return 'low';
 }
 
-/**
- * Render a state-transition event into a human-readable summary line used
- * as both the GitHub comment body and the webhook message text.
- */
+/** Used as both comment body and webhook text. */
 export function renderTransitionMessage(event) {
   const type = event.ticket?.type ?? 'ticket';
   const id = event.ticket?.id;

package/.agents/scripts/lib/npm-scripts.js

@@ -1,30 +1,13 @@
 /**
- * npm-scripts.js — shared `package.json` scripts probe (Story #4473).
- *
- * A single, dependency-free reader used wherever the framework must decide
- * whether a consumer actually ships a given npm script before spawning
- * `npm run <name>`. Two call sites depend on it:
- *   - `close-validation/gates.js` — only registers the coverage-capture gate
- *     when a `test:coverage` script exists (otherwise a consumer without it
- *     turns the gate into a guaranteed first-try close failure).
- *   - `coverage-capture.js` — fails fast with a one-line, fix-naming
- *     diagnostic instead of surfacing npm's opaque "Missing script" exit when
- *     invoked without the script.
- *
- * The reader is deliberately forgiving: any failure (missing file,
- * unreadable, unparseable, or no `scripts` object) resolves to an empty map
- * so callers treat "cannot prove the script exists" as "absent" without
- * throwing.
+ * npm-scripts.js — does the consumer ship an npm script, checked before
+ * spawning `npm run <name>`. Any read failure means "absent", never a throw.
  */
 
 import { existsSync, readFileSync } from 'node:fs';
 import path from 'node:path';
 
 /**
- * Read the `scripts` map from the `package.json` at `cwd`.
- *
  * @param {string|undefined|null} cwd - Directory containing `package.json`.
- *   Defaults to `process.cwd()`.
  * @returns {Record<string, string>} The scripts map, or `{}` on any failure.
  */
 export function readPackageScripts(cwd) {
@@ -41,11 +24,9 @@ export function readPackageScripts(cwd) {
 }
 
 /**
- * Does the consumer define a runnable npm script by this name? A script is
- * "runnable" when it is a present, non-empty string.
+ * Runnable means a present, non-empty string.
  *
- * @param {Record<string, string>} scripts - A scripts map (from
- *   `readPackageScripts`).
+ * @param {Record<string, string>} scripts - A scripts map.
  * @param {string} name - The script name to check (e.g. `test:coverage`).
  * @returns {boolean}
  */

package/.agents/scripts/lib/observability/metrics-ledger.js

@@ -1,34 +1,7 @@
 /**
- * metrics-ledger.js — the narrow shared metrics-ledger boundary (Story #4712).
- *
- * Owns the one append-tail implementation for the plan-metrics ledger:
- * path resolution, serialization, lazy directory creation, size-capped
- * rotation, and the append itself. Every ledger writer — the plan-domain
- * appenders in `../orchestration/plan-metrics.js` and the close-domain
- * findings-yield entry point below — routes through
- * {@link appendLedgerRecord}, so the open→append→rotate→close tail exists
- * exactly once and cannot drift between call sites.
- *
- * The findings-yield entry point (Story #4699) lives here rather than in
- * the plan-domain module so the story-close review spine
- * (`../orchestration/story-close/phases/review-core.js`) depends on this
- * narrow shared ledger module instead of plan-domain internals.
- *
- * Wire contract (unchanged by the #4712 re-home): record shapes, file
- * locations (`temp/run-<id>/plan-metrics.json` / the standalone stream),
- * and the rotation threshold are exactly what `plan-metrics.js` shipped —
- * readers (`readPlanMetrics` / `summarizePlanMetrics`) stay plan-side and
- * key kinded records on `kind`, never on absent fields.
- *
- * Robustness contract (mirrors `signals-writer.js`):
- *   - **No buffering.** Each append opens, writes one line, closes.
- *   - **Rotation.** When an append would push the ledger past
- *     `maxBytes`, the current file is renamed to `<name>.1` (replacing any
- *     prior rollover) and the append starts a fresh ledger.
- *   - **Best-effort at the entry points.** {@link appendLedgerRecord}
- *     itself throws on fs failure; each public appender catches, warns via
- *     `Logger`, and returns `false` so metric capture can never fail the
- *     wrapped plan phase or Story close.
+ * metrics-ledger.js — the one append tail for the plan-metrics ledger, kept
+ * outside the plan domain so the close spine needn't import plan internals.
+ * Public appenders are best-effort so capture never fails a phase or close.
  */
 
 import fs from 'node:fs/promises';
@@ -44,40 +17,17 @@ import { Logger } from '../Logger.js';
 export const PLAN_METRICS_BASENAME = 'plan-metrics.json';
 export const PLAN_METRICS_SCHEMA_VERSION = 1;
 
-/**
- * Record kind for a per-close, per-lens findings-yield entry (Story #4699).
- * One record per Story close whose review ran (or floor-skipped) at least
- * one local lens:
- *
- * ```json
- * { "v": 1, "kind": "findings-yield", "cli": "story-close-review",
- *   "storyId": 4699, "epicId": null,
- *   "lenses": [{ "lens": "audit-clean-code", "findings": 0,
- *                "skippedByFloor": false }],
- *   "diffFloor": { "skip": false, "reason": "at-or-above-floor",
- *                  "floor": 40, "changedLineCount": 120 },
- *   "at": "..." }
- * ```
- *
- * The ledger only records — no roster behavior changes ride on it. Its
- * purpose is evidentiary: a lens that stays at zero findings across N
- * closes becomes droppable on measurement instead of assumption.
- */
+/** Evidence for dropping a lens that stays at zero findings. */
 const PLAN_METRICS_KIND_FINDINGS_YIELD = 'findings-yield';
 
-/**
- * Rotation threshold. At ~200 bytes per record this is ~5000 invocations —
- * far beyond any real plan run, so rotation only fires on pathological
- * accumulation.
- */
+/** ~5000 records; rotation only fires on pathological accumulation. */
 export const MAX_LEDGER_BYTES = 1024 * 1024;
 
 /**
- * Resolve the ledger path for an Epic (or the standalone stream when
- * `epicId` is `null` — the v2 Epic-less plan/healthcheck case).
+ * `null` `epicId` → the standalone stream.
  *
  * @param {number|null} epicId
- * @param {object} [config] Resolved config (threads `project.paths.tempRoot`).
+ * @param {object} [config]
  * @returns {string}
  */
 export function planMetricsPath(epicId, config) {
@@ -92,9 +42,8 @@ export function planMetricsPath(epicId, config) {
 }
 
 /**
- * Rotate the ledger when appending `incomingBytes` would exceed
- * `maxBytes`. Single-generation rollover: `plan-metrics.json` →
- * `plan-metrics.json.1` (any prior `.1` is replaced).
+ * Roll over to `<file>.1` (replacing any prior) when the append would exceed
+ * `maxBytes`.
  *
  * @param {string} filePath
  * @param {number} incomingBytes
@@ -106,7 +55,7 @@ async function rotateIfNeeded(filePath, incomingBytes, maxBytes) {
   try {
     size = (await fs.stat(filePath)).size;
   } catch {
-    return false; // No existing ledger — nothing to rotate.
+    return false;
   }
   if (size + incomingBytes <= maxBytes) return false;
   await fs.rename(filePath, `${filePath}.1`);
@@ -114,20 +63,15 @@ async function rotateIfNeeded(filePath, incomingBytes, maxBytes) {
 }
 
 /**
- * The single ledger append tail (Story #4712): serialize the record to one
- * newline-terminated JSON line, create the ledger directory lazily, rotate
- * when the byte cap would be exceeded, and append.
- *
- * Throws on any fs failure — the best-effort posture (warn + `false`,
- * never throw) belongs to the public appenders that wrap this, because
- * each labels its own failure mode.
+ * Throws on fs failure; the wrapping public appenders own the best-effort
+ * posture and label their own failure.
  *
- * @param {object} record Fully-built ledger record (already validated).
+ * @param {object} record
  * @param {{
  *   epicId?: number|null,
  *   config?: object,
  *   maxBytes?: number,
- * }} [opts] `maxBytes` is a test seam for the rotation threshold.
+ * }} [opts]
  * @returns {Promise<void>}
  */
 export async function appendLedgerRecord(record, opts = {}) {
@@ -143,11 +87,7 @@ export async function appendLedgerRecord(record, opts = {}) {
 }
 
 /**
- * Append one findings-yield record (Story #4699). Called once per Story
- * close by the review spine when the local-lens pass matched (or
- * floor-skipped) at least one lens. Best-effort: returns `false` (after a
- * `Logger.warn`) instead of throwing on any failure, so a ledger failure
- * can never fail the close.
+ * Append one findings-yield record. Never throws.
  *
  * @param {{
  *   storyId: number,
@@ -157,7 +97,7 @@ export async function appendLedgerRecord(record, opts = {}) {
  *   diffFloor?: object|null,
  * }} entry
  * @param {object} [config]
- * @param {{ maxBytes?: number }} [opts] Test seam for the rotation threshold.
+ * @param {{ maxBytes?: number }} [opts]
  * @returns {Promise<boolean>} true when the line was written.
  */
 export async function appendFindingsYield(entry, config, opts = {}) {