mandrel 2.65.0 → 2.67.0

package/.agents/scripts/lib/cli/standard-args.js

@@ -24,13 +24,26 @@ const SUPPORTED_FLAGS = Object.freeze({
 
 const FLAG_NAMES = Object.keys(SUPPORTED_FLAGS);
 
-const SUPPORTED_EXTRAS_TYPES = new Set([
-  'string',
-  'boolean',
-  'ticket',
-  'integer',
-  'string-multi',
-]);
+const isNullish = (v) => v === null || v === undefined;
+
+/** Per-type rules shared by built-in and extra flags. */
+const FLAG_TYPES = Object.freeze({
+  string: {
+    normalise: (v, orDefault) =>
+      typeof v === 'string' && v.length > 0 ? v : orDefault(null),
+    isAbsent: (v) => isNullish(v) || v === '',
+  },
+  boolean: { normalise: (v) => v === true, isAbsent: (v) => !v },
+  ticket: { normalise: (v) => parseTicketId(v), isAbsent: isNullish },
+  integer: {
+    normalise: (v, orDefault) => (v === undefined ? orDefault(undefined) : v),
+    isAbsent: (v) => v === undefined || Number.isNaN(v),
+  },
+  'string-multi': {
+    normalise: (v, orDefault) => (Array.isArray(v) ? v : orDefault([])),
+    isAbsent: (v) => !Array.isArray(v) || v.length === 0,
+  },
+});
 
 function camelCase(name) {
   return name.replace(/-([a-z])/g, (_m, c) => c.toUpperCase());
@@ -50,16 +63,33 @@ function normaliseCallSignature(opts) {
   return { argv: argv ?? [], schema, extras };
 }
 
-function buildDefineFlagsSpec(extras) {
+function flagEntries(schema, extras) {
+  const entries = Object.entries(SUPPORTED_FLAGS).map(
+    ([flag, { key, type }]) => ({
+      flag,
+      key,
+      type,
+      def: {},
+      required: schema?.[flag]?.required === true,
+    }),
+  );
+  for (const [flag, def] of Object.entries(extras ?? {})) {
+    entries.push({
+      flag,
+      key: def.alias ?? camelCase(flag),
+      type: def.type,
+      def,
+      required: def.required === true,
+    });
+  }
+  return entries;
+}
+
+function buildDefineFlagsSpec(entries) {
   const spec = {};
-  for (const [flag, { key, type }] of Object.entries(SUPPORTED_FLAGS)) {
+  for (const { flag, key, type, def } of entries) {
     spec[flag] = { type, alias: key };
-  }
-  if (!extras) return spec;
-  for (const [flag, def] of Object.entries(extras)) {
-    const entry = { type: def.type, alias: def.alias ?? camelCase(flag) };
-    if ('default' in def) entry.default = def.default;
-    spec[flag] = entry;
+    if ('default' in def) spec[flag].default = def.default;
   }
   return spec;
 }
@@ -119,10 +149,10 @@ function validateExtras(extras) {
         `parseStandardCliArgs: extras["${flag}"] must be an object`,
       );
     }
-    if (!SUPPORTED_EXTRAS_TYPES.has(def.type)) {
+    if (!Object.hasOwn(FLAG_TYPES, def.type)) {
       const err = new Error(
         `parseStandardCliArgs: extras["${flag}"].type "${def.type}" is unsupported. ` +
-          `Supported: ${[...SUPPORTED_EXTRAS_TYPES].join(', ')}.`,
+          `Supported: ${Object.keys(FLAG_TYPES).join(', ')}.`,
       );
       err.code = 'UNKNOWN_EXTRAS_TYPE';
       throw err;
@@ -130,15 +160,6 @@ function validateExtras(extras) {
   }
 }
 
-function isAbsent(type, cur) {
-  if (type === 'ticket') return cur === null || cur === undefined;
-  if (type === 'string') return cur === null || cur === undefined || cur === '';
-  if (type === 'boolean') return !cur;
-  if (type === 'integer') return cur === undefined || Number.isNaN(cur);
-  if (type === 'string-multi') return !Array.isArray(cur) || cur.length === 0;
-  return cur === undefined || cur === null;
-}
-
 function throwMissing(flag) {
   const err = new Error(
     `parseStandardCliArgs: missing required flag --${flag}`,
@@ -148,56 +169,19 @@ function throwMissing(flag) {
   throw err;
 }
 
-function enforceRequired(values, schema) {
-  if (!schema) return;
-  for (const [flag, rule] of Object.entries(schema)) {
-    if (!rule || rule.required !== true) continue;
-    const meta = SUPPORTED_FLAGS[flag];
-    if (isAbsent(meta.type, values[meta.key])) throwMissing(flag);
-  }
-}
-
-function enforceExtrasRequired(values, extras) {
-  if (!extras) return;
-  for (const [flag, def] of Object.entries(extras)) {
-    if (!def || def.required !== true) continue;
-    const key = def.alias ?? camelCase(flag);
-    if (isAbsent(def.type, values[key])) throwMissing(flag);
+function normaliseValues(raw, entries) {
+  const out = {};
+  for (const { key, type, def } of entries) {
+    const orDefault = (empty) => ('default' in def ? def.default : empty);
+    out[key] = FLAG_TYPES[type].normalise(raw[key], orDefault);
   }
+  return out;
 }
 
-/** Absent strings become `null` and booleans strict `false`. */
-function normaliseValues(raw, extras) {
-  const out = {};
-  for (const [, { key, type }] of Object.entries(SUPPORTED_FLAGS)) {
-    let v = raw[key];
-    if (type === 'ticket') {
-      v = parseTicketId(v);
-    } else if (type === 'string') {
-      v = typeof v === 'string' && v.length > 0 ? v : null;
-    } else if (type === 'boolean') {
-      v = v === true;
-    }
-    out[key] = v;
+function enforceRequired(values, entries) {
+  for (const { flag, key, type, required } of entries) {
+    if (required && FLAG_TYPES[type].isAbsent(values[key])) throwMissing(flag);
   }
-  if (!extras) return out;
-  for (const [flag, def] of Object.entries(extras)) {
-    const key = def.alias ?? camelCase(flag);
-    let v = raw[key];
-    if (def.type === 'boolean') {
-      v = v === true;
-    } else if (def.type === 'string') {
-      if (v === undefined) v = 'default' in def ? def.default : null;
-    } else if (def.type === 'ticket') {
-      v = parseTicketId(v);
-    } else if (def.type === 'string-multi') {
-      if (!Array.isArray(v)) v = 'default' in def ? def.default : [];
-    } else if (def.type === 'integer') {
-      if (v === undefined && 'default' in def) v = def.default;
-    }
-    out[key] = v;
-  }
-  return out;
 }
 
 /**
@@ -222,13 +206,13 @@ export function parseStandardCliArgs(opts = {}) {
     err.flag = unknown;
     throw err;
   }
+  const entries = flagEntries(schema, extras);
   const { values: raw, positionals } = defineFlags(
-    buildDefineFlagsSpec(extras),
+    buildDefineFlagsSpec(entries),
     argv,
   );
-  const values = normaliseValues(raw, extras);
-  enforceRequired(values, schema);
-  enforceExtrasRequired(values, extras);
+  const values = normaliseValues(raw, entries);
+  enforceRequired(values, entries);
   return { values, positionals };
 }
 

package/.agents/scripts/lib/cli-args.js

@@ -133,6 +133,30 @@ function tolerantOverrideReviewBlock(value) {
   }
 }
 
+/**
+ * Best-effort: absent or junk is `null` plus a warning, never a throw.
+ *
+ * @param {unknown} value
+ * @returns {{ tokens: number|null, warning: string|null }}
+ */
+export function parseWorkerTokens(value) {
+  if (value == null) {
+    return {
+      tokens: null,
+      warning:
+        '--worker-tokens not supplied; telemetry.workerTokens records null.',
+    };
+  }
+  const raw = String(value).trim();
+  if (/^\d+$/.test(raw) && Number.isSafeInteger(Number(raw))) {
+    return { tokens: Number(raw), warning: null };
+  }
+  return {
+    tokens: null,
+    warning: `--worker-tokens must be a non-negative integer (got ${JSON.stringify(value)}); telemetry.workerTokens records null.`,
+  };
+}
+
 /**
  * Throws when a validating flag parser rejects a value; error handlers use
  * {@link parseSprintArgsTolerant} instead of re-calling this.
@@ -164,6 +188,7 @@ export function parseSprintArgs(
       'merge-watch-mode': { type: 'string' },
       'rerun-advisory': { type: 'string' },
       'override-review-block': { type: 'string' },
+      'worker-tokens': { type: 'string' },
       executor: { type: 'string' },
       cwd: { type: 'string' },
       'recut-of': { type: 'string' },
@@ -194,6 +219,7 @@ export function parseSprintArgs(
     overrideReviewBlock: tolerant
       ? tolerantOverrideReviewBlock(values['override-review-block'])
       : parseOverrideReviewBlock(values['override-review-block']),
+    workerTokens: values['worker-tokens'],
     executor: values.executor ?? null,
     cwd:
       (typeof values.cwd === 'string' && values.cwd.trim()) ||

package/.agents/scripts/lib/config/gates/shared.js

@@ -23,7 +23,7 @@ export const LIST_OR_EXTENDER_OF_STRINGS = {
   ],
 };
 
-export const TOLERANCE_SCHEMA = {
+const TOLERANCE_SCHEMA = {
   type: 'object',
   description:
     'How much a rollup may drift from the committed baseline before the gate reports a regression.',
@@ -47,7 +47,7 @@ export const TOLERANCE_SCHEMA = {
 /**
  * `"*"` is optional: the resolver injects the framework default when absent.
  */
-export const FLOORS_SCHEMA = {
+const FLOORS_SCHEMA = {
   type: 'object',
   description:
     'Workspace-keyed absolute floors: `{ "<workspace>": { "<metric>": number } }`. `"*"` is the project-wide catch-all; the metric keyset is open so per-rollup keys flow through without each gate enumerating them. Floors are absolute — unlike `tolerance`, they are enforced regardless of the baseline.',
@@ -57,7 +57,7 @@ export const FLOORS_SCHEMA = {
   },
 };
 
-export const COMPONENTS_SCHEMA = {
+const COMPONENTS_SCHEMA = {
   type: 'object',
   description:
     'Per-gate component map — component name to the glob list whose files roll up under it. Defaults to `{ "*": ["**"] }` at the resolver layer.',

package/.agents/scripts/lib/config-settings-schema-delivery.js

@@ -283,8 +283,9 @@ const TEMP_RETENTION_SCHEMA = {
   description:
     'Story #4794. Auto-purge of spent temp artifacts once their Story lands. ' +
     'Classification is an allowlist: only the declared classes below are ever ' +
-    'deleted, so operator scratch files under tempRoot are reported with their ' +
-    'size and left alone. signals.ndjson is never purged by any path.',
+    'deleted, so unrecognized files under tempRoot are reported with their ' +
+    'size and left alone (`/clean-temp` is the operator path for them). ' +
+    'signals.ndjson is never purged by any path.',
   properties: {
     enabled: {
       type: 'boolean',
@@ -326,6 +327,14 @@ const TEMP_RETENTION_SCHEMA = {
             'Age-floored only; the current run is always excluded.',
           default: true,
         },
+        scratch: {
+          type: 'boolean',
+          description:
+            '<tempRoot>/scratch/ — agent-authored scratch. ' +
+            '`scratch/story-<id>/` is purged when that Story lands; any ' +
+            'other `scratch/` entry is age-floored.',
+          default: true,
+        },
       },
       additionalProperties: false,
     },

package/.agents/scripts/lib/feedback-loop/graduate-steps.js

@@ -0,0 +1,205 @@
+/**
+ * One finding's walk through the graduator, as route → dedup → file steps.
+ * Every step receives the gh context as the single `gh` value.
+ */
+
+import { routeOwnership } from '../github/framework-repo.js';
+import {
+  createFollowUpIssue,
+  ensureIssueLabels,
+  findExistingFollowUp,
+  probePathStatus,
+  searchFollowUpByMarker,
+  updateFollowUpIssue,
+} from './graduator-gh.js';
+
+/** @returns {Promise<string|null>} A skip reason, or `null` to continue. */
+export async function probeFindingPath({ finding, gitRef, gh }) {
+  // A path-less finding would misclassify as `file-removed`; skip the probe.
+  if (typeof finding.path !== 'string' || finding.path.trim().length === 0) {
+    return null;
+  }
+  const { exists, probeError } = await probePathStatus({
+    ref: gitRef,
+    path: finding.path,
+    ...gh,
+  });
+  if (probeError) return 'probe-error';
+  return exists ? null : 'file-removed';
+}
+
+/**
+ * Unroutable findings are deferred and named, never re-pointed at the
+ * consumer's repo.
+ *
+ * @returns {{ source: string, routedRepo: object|null, deferred: object|null, skipReason: string|null }}
+ */
+export function routeFinding({
+  finding,
+  classifier,
+  repos,
+  currentRepo,
+  logger,
+  spec,
+}) {
+  const source = classifier(finding.path, null);
+  const routing = routeOwnership({ bucket: source, repos, currentRepo });
+  if (!routing.routable) {
+    const logLine = `[${spec.fnName}] unroutable ${source} finding (${routing.missingKey} is unset) — not filed: ${finding.title ?? finding.path ?? `finding ${finding.index}`}`;
+    logger?.warn?.(logLine);
+    const deferred = {
+      finding,
+      routedRepo: null,
+      source,
+      logLine,
+      missingKey: routing.missingKey,
+    };
+    return { source, routedRepo: null, deferred, skipReason: 'unroutable' };
+  }
+  const routedRepo = routing.routedRepo;
+  if (routing.crossRepo) {
+    const logLine = spec.buildCrossRepoLog({ finding, routedRepo, source });
+    logger?.info?.(logLine);
+    const deferred = { finding, routedRepo, source, logLine };
+    return { source, routedRepo, deferred, skipReason: 'cross-repo-deferred' };
+  }
+  return { source, routedRepo, deferred: null, skipReason: null };
+}
+
+/**
+ * Checks the content-hash marker, then the legacy ordinal marker so
+ * pre-fingerprint filings are not re-filed.
+ *
+ * @returns {Promise<{ number: number|null, state: string, url: string }|null>}
+ */
+export async function dedupFinding({
+  finding,
+  epicId,
+  routedRepo,
+  contentMarker,
+  gh,
+  spec,
+}) {
+  const probe = (marker) =>
+    searchFollowUpByMarker({
+      marker,
+      owner: routedRepo.owner,
+      repo: routedRepo.repo,
+      ...gh,
+    });
+  const hit = await probe(contentMarker);
+  if (hit) return hit;
+  const legacyMarker =
+    typeof spec.buildLegacyMarker === 'function'
+      ? spec.buildLegacyMarker(epicId, finding.index)
+      : null;
+  return legacyMarker ? probe(legacyMarker) : null;
+}
+
+/**
+ * An open, numbered match is refreshed and recorded on `filed` as
+ * `action: 'updated'` (a live write, counted like a creation). Anything else
+ * is `already-filed` and untouched: a closed follow-up is a human's decision.
+ */
+export async function recordRecurrence(walk, existing, body) {
+  const { finding, source, routedRepo, envelope, decorate, skip, gh } = walk;
+  walk.filedMarkers?.add(walk.contentMarker);
+  if (existing.state !== 'open' || existing.number === null) {
+    skip('already-filed');
+    return;
+  }
+  const updated = await updateFollowUpIssue({
+    owner: routedRepo.owner,
+    repo: routedRepo.repo,
+    number: existing.number,
+    body,
+    ...gh,
+  });
+  if (updated.error) {
+    envelope.errors.push(
+      `finding ${finding.index} (${finding.path}): ${updated.error}`,
+    );
+    return;
+  }
+  envelope.filed.push(
+    decorate(
+      {
+        index: finding.index,
+        action: 'updated',
+        issueNumber: existing.number,
+        severity: finding.severity,
+        path: finding.path,
+        source,
+        repo: `${routedRepo.owner}/${routedRepo.repo}`,
+        url: updated.url || existing.url || null,
+      },
+      finding,
+    ),
+  );
+}
+
+function strongReadExisting(walk, labels) {
+  const { epicId, finding, contentMarker, routedRepo, spec } = walk;
+  return findExistingFollowUp({
+    markers:
+      typeof spec.buildMatchTokens === 'function'
+        ? spec.buildMatchTokens({ epicId, finding, contentMarker })
+        : [contentMarker],
+    owner: routedRepo.owner,
+    repo: routedRepo.repo,
+    labels,
+    ...walk.gh,
+  });
+}
+
+/** Cap → label mint → strong-read confirm → create. */
+export async function fileFinding(walk, { title, body, labels }) {
+  const { finding, routedRepo, envelope, decorate, skip, gh } = walk;
+  if (envelope.filed.length >= walk.maxFilingsPerRun) {
+    return skip('cap-reached');
+  }
+  // Before the strong read too: `gh issue list --label <absent>` exits 0
+  // with `[]`, silently defeating the dedup confirm.
+  const ensured = await ensureIssueLabels({
+    owner: routedRepo.owner,
+    repo: routedRepo.repo,
+    labels,
+    labelCache: walk.labelCache,
+    ...gh,
+  });
+  envelope.errors.push(...ensured.errors);
+  if (ensured.missing.length > 0) return skip('label-ensure-failed');
+
+  const confirmed = await strongReadExisting(walk, labels);
+  if (confirmed) return recordRecurrence(walk, confirmed, body);
+
+  const created = await createFollowUpIssue({
+    owner: routedRepo.owner,
+    repo: routedRepo.repo,
+    title,
+    body,
+    labels,
+    ...gh,
+  });
+  if (created.error) {
+    envelope.errors.push(
+      `finding ${finding.index} (${finding.path}): ${created.error}`,
+    );
+    return;
+  }
+  walk.filedMarkers?.add(walk.contentMarker);
+  envelope.filed.push(
+    decorate(
+      {
+        index: finding.index,
+        action: 'created',
+        severity: finding.severity,
+        path: finding.path,
+        source: walk.source,
+        repo: `${routedRepo.owner}/${routedRepo.repo}`,
+        url: created.url,
+      },
+      finding,
+    ),
+  );
+}