mandrel 1.57.0 → 1.59.0

package/.agents/scripts/lib/orchestration/review-providers/security-review.js

@@ -32,6 +32,7 @@
  */
 
 import { spawnSync } from 'node:child_process';
+import { parseProviderFindings } from './parse-findings.js';
 import { renderDepthDirective } from './review-depth.js';
 
 /**
@@ -138,65 +139,12 @@ export function mapSecurityReviewSeverity(raw) {
  * @throws {Error} when stdout is not parseable JSON.
  */
 export function parseSecurityReviewFindings(rawStdout) {
-  const text = (rawStdout ?? '').trim();
-  if (text.length === 0) return [];
-
-  let parsed;
-  try {
-    parsed = JSON.parse(text);
-  } catch (err) {
-    throw new Error(
-      `[security-review] Failed to parse /security-review stdout as JSON: ${
-        err?.message ?? err
-      }`,
-    );
-  }
-
-  if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
-    if (Array.isArray(parsed.findings)) parsed = parsed.findings;
-    else if (parsed.result !== undefined) parsed = parsed.result;
-    else if (parsed.data !== undefined) parsed = parsed.data;
-  }
-  if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
-    if (Array.isArray(parsed.findings)) parsed = parsed.findings;
-  }
-
-  if (!Array.isArray(parsed)) return [];
-
-  /** @type {Finding[]} */
-  const findings = [];
-  for (const entry of parsed) {
-    if (!entry || typeof entry !== 'object') continue;
-    const title =
-      typeof entry.title === 'string' && entry.title.trim().length > 0
-        ? entry.title.trim()
-        : null;
-    const body =
-      typeof entry.body === 'string' && entry.body.trim().length > 0
-        ? entry.body
-        : typeof entry.message === 'string' && entry.message.trim().length > 0
-          ? entry.message
-          : null;
-    if (!title || !body) continue;
-    /** @type {Finding} */
-    const finding = {
-      severity: mapSecurityReviewSeverity(entry.severity),
-      title,
-      body,
-      category:
-        typeof entry.category === 'string' && entry.category.length > 0
-          ? entry.category
-          : 'security',
-    };
-    if (typeof entry.file === 'string' && entry.file.length > 0) {
-      finding.file = entry.file;
-    }
-    if (Number.isInteger(entry.line) && entry.line > 0) {
-      finding.line = entry.line;
-    }
-    findings.push(finding);
-  }
-  return findings;
+  return parseProviderFindings(rawStdout, {
+    errorPrefix:
+      '[security-review] Failed to parse /security-review stdout as JSON',
+    mapSeverity: mapSecurityReviewSeverity,
+    defaultCategory: 'security',
+  });
 }
 
 /**

package/.agents/scripts/lib/orchestration/single-story-close/phases/close-validation.js

@@ -22,10 +22,8 @@
  * that mock the upstream module URLs.
  */
 
-import {
-  buildDefaultGates as defaultBuildDefaultGates,
-  runCloseValidation as defaultRunCloseValidation,
-} from '../../../close-validation.js';
+import { buildDefaultGates as defaultBuildDefaultGates } from '../../../close-validation/gates.js';
+import { runCloseValidation as defaultRunCloseValidation } from '../../../close-validation/runner.js';
 import { Logger } from '../../../Logger.js';
 
 /**

package/.agents/scripts/lib/orchestration/single-story-close/phases/normalize-pr-title.js

@@ -0,0 +1,241 @@
+/**
+ * normalize-pr-title.js — guarantee the standalone-Story PR title is a
+ * valid Conventional Commit subject so the squash-merge subject on `main`
+ * parses for release-please.
+ *
+ * Story #3969 (framework gap). The repo squash-merges, and GitHub uses the
+ * PR title as the squash-commit subject. `buildPullRequest` previously
+ * emitted the raw human issue title (`<storyTitle> (#<id>)`), which is a
+ * plain description ("Rename the published npm package…") that
+ * release-please's Conventional-Commit parser rejects:
+ *
+ *   ❯ commit could not be parsed: … Rename the published npm package …
+ *   ❯ error: unexpected token ' ' at 1:7, valid tokens [(, !, :]
+ *   ❯ commits: 0  → no release cut
+ *
+ * The `commit-msg` commitlint Husky hook only validates *local* commits and
+ * never runs on a GitHub-UI squash-merge title, so nothing mechanized the
+ * documented "author the PR title in conventional form" contract. This
+ * module mechanizes it.
+ *
+ * Contract (pure where possible — the only side effect is an injectable
+ * `git log` read used to derive the type):
+ *
+ *   - If `storyTitle` is **already** a parseable Conventional Commit
+ *     subject, it is preserved verbatim and suffixed with `(#<storyId>)`.
+ *     No re-prefixing, no double type.
+ *   - Otherwise the title is **synthesized** into conventional form:
+ *     `<type>: <descriptive text> (#<storyId>)`. The `type` is derived
+ *     from the branch's own (already-conventional) commit subjects when
+ *     available, falling back to a safe configured default (`chore`).
+ *
+ * Mirrors the already-normalized Epic-finalize default in
+ * `lib/orchestration/finalize/open-or-locate-pr.js` (`feat: Epic #<id>`),
+ * bringing the standalone path to the same guarantee.
+ */
+
+import { gitSpawn as defaultGitSpawn } from '../../../git-utils.js';
+import { Logger as DefaultLogger } from '../../../Logger.js';
+
+/** Safe default Conventional-Commit type when none can be derived. */
+export const DEFAULT_CONVENTIONAL_TYPE = 'chore';
+
+/**
+ * The Conventional-Commit types Mandrel accepts. Mirrors
+ * `commitlint.config.js` → `type-enum` and `release-please-config.json` →
+ * `changelog-sections`. Kept in sync by hand (single hard-cutover, no
+ * shim) — adding a type means touching all three.
+ */
+export const CONVENTIONAL_TYPES = Object.freeze([
+  'feat',
+  'fix',
+  'perf',
+  'refactor',
+  'revert',
+  'docs',
+  'style',
+  'chore',
+  'test',
+  'build',
+  'ci',
+]);
+
+// Precedence used when a branch carries a mix of conventional types: pick
+// the most release-significant one so the squash subject communicates the
+// branch's headline impact (and release-please bumps appropriately).
+const TYPE_PRECEDENCE = Object.freeze([
+  'feat',
+  'fix',
+  'perf',
+  'refactor',
+  'revert',
+  'docs',
+  'style',
+  'test',
+  'build',
+  'ci',
+  'chore',
+]);
+
+const TYPE_GROUP = CONVENTIONAL_TYPES.join('|');
+// Anchored Conventional-Commit header matcher:
+//   <type>(<optional scope>)<optional !>: <non-empty description>
+// Mirrors the shape `@commitlint/config-conventional` enforces (a known
+// type, an optional parenthesised scope, an optional breaking `!`, a
+// colon-space separator, and a non-empty subject). Used for the pure
+// "is this already conventional?" check and to pull the type off a branch
+// commit subject without spawning commitlint per call.
+const CONVENTIONAL_HEADER_RE = new RegExp(
+  `^(?:${TYPE_GROUP})(?:\\([^()\\r\\n]+\\))?!?: \\S.*$`,
+);
+const LEADING_TYPE_RE = new RegExp(
+  `^(${TYPE_GROUP})(?:\\([^()\\r\\n]+\\))?!?:`,
+);
+
+/**
+ * True iff `subject` is a parseable Conventional Commit subject under the
+ * repo's type vocabulary. Pure.
+ *
+ * @param {string} subject
+ * @returns {boolean}
+ */
+export function isConventionalSubject(subject) {
+  if (typeof subject !== 'string') return false;
+  return CONVENTIONAL_HEADER_RE.test(subject.trim());
+}
+
+/**
+ * Extract the Conventional-Commit `type` from a single commit subject, or
+ * `null` when the subject is not conventional. Pure.
+ *
+ * @param {string} subject
+ * @returns {string|null}
+ */
+export function parseConventionalType(subject) {
+  if (typeof subject !== 'string') return null;
+  const match = subject.trim().match(LEADING_TYPE_RE);
+  return match ? match[1] : null;
+}
+
+/**
+ * Pick the most release-significant type from a list of conventional
+ * types, honouring `TYPE_PRECEDENCE`. Returns `null` for an empty list.
+ * Pure.
+ *
+ * @param {string[]} types
+ * @returns {string|null}
+ */
+export function pickDominantType(types) {
+  const present = new Set(types.filter(Boolean));
+  for (const candidate of TYPE_PRECEDENCE) {
+    if (present.has(candidate)) return candidate;
+  }
+  return null;
+}
+
+/**
+ * Read the branch's own commit subjects (commits unique to the Story
+ * branch relative to the base branch) and derive the dominant
+ * Conventional-Commit type. Returns `DEFAULT_CONVENTIONAL_TYPE` when no
+ * conventional subject is found or the git read fails.
+ *
+ * @param {{
+ *   storyBranch: string,
+ *   baseBranch: string,
+ *   cwd?: string,
+ *   gitSpawn?: typeof defaultGitSpawn,
+ *   logger?: { warn?: Function },
+ * }} args
+ * @returns {string}
+ */
+export function deriveTypeFromBranchCommits({
+  storyBranch,
+  baseBranch,
+  cwd = process.cwd(),
+  gitSpawn = defaultGitSpawn,
+  logger = DefaultLogger,
+}) {
+  try {
+    const range = `${baseBranch}..${storyBranch}`;
+    const result = gitSpawn(cwd, 'log', '--no-merges', '--format=%s', range);
+    if (!result || result.status !== 0) {
+      logger?.warn?.(
+        `[normalize-pr-title] git log ${range} failed (status=${result?.status ?? 'n/a'}); ` +
+          `defaulting type to "${DEFAULT_CONVENTIONAL_TYPE}".`,
+      );
+      return DEFAULT_CONVENTIONAL_TYPE;
+    }
+    const types = String(result.stdout ?? '')
+      .split('\n')
+      .map((line) => parseConventionalType(line))
+      .filter(Boolean);
+    return pickDominantType(types) ?? DEFAULT_CONVENTIONAL_TYPE;
+  } catch (err) {
+    logger?.warn?.(
+      `[normalize-pr-title] could not derive type from branch commits ` +
+        `(defaulting to "${DEFAULT_CONVENTIONAL_TYPE}"): ${err?.message ?? err}`,
+    );
+    return DEFAULT_CONVENTIONAL_TYPE;
+  }
+}
+
+/**
+ * Produce a PR title that parses as a Conventional Commit.
+ *
+ *   - Already-conventional `storyTitle` → preserved verbatim + `(#<id>)`.
+ *   - Otherwise → `<derivedType>: <storyTitle> (#<id>)`.
+ *   - Empty / missing `storyTitle` → `<derivedType>: Story #<id>`.
+ *
+ * The type derivation (`deriveTypeFromBranchCommits`) is the only side
+ * effect, and is skipped entirely when the title is already conventional.
+ *
+ * @param {{
+ *   storyTitle: string,
+ *   storyId: number|string,
+ *   storyBranch?: string,
+ *   baseBranch?: string,
+ *   cwd?: string,
+ *   gitSpawn?: typeof defaultGitSpawn,
+ *   logger?: { warn?: Function },
+ * }} args
+ * @returns {string}
+ */
+export function normalizePrTitle({
+  storyTitle,
+  storyId,
+  storyBranch,
+  baseBranch,
+  cwd = process.cwd(),
+  gitSpawn = defaultGitSpawn,
+  logger = DefaultLogger,
+}) {
+  const idSuffix = `(#${storyId})`;
+  const trimmed = typeof storyTitle === 'string' ? storyTitle.trim() : '';
+
+  // Already conventional → preserve verbatim, append the id reference.
+  if (isConventionalSubject(trimmed)) {
+    return `${trimmed} ${idSuffix}`;
+  }
+
+  // Not conventional → derive a type and synthesize.
+  const type =
+    storyBranch && baseBranch
+      ? deriveTypeFromBranchCommits({
+          storyBranch,
+          baseBranch,
+          cwd,
+          gitSpawn,
+          logger,
+        })
+      : DEFAULT_CONVENTIONAL_TYPE;
+
+  // Lowercase the leading character of a synthesized description so the
+  // subject satisfies commitlint's `subject-case` rule (matching the
+  // `shapeMergeSubject` behaviour). An already-conventional title is left
+  // untouched (it was preserved verbatim above). The empty-title fallback
+  // uses a lowercased `story #<id>` for the same reason.
+  const rawDescription = trimmed.length > 0 ? trimmed : `Story #${storyId}`;
+  const description =
+    rawDescription.charAt(0).toLowerCase() + rawDescription.slice(1);
+  return `${type}: ${description} ${idSuffix}`;
+}

package/.agents/scripts/lib/orchestration/single-story-close/phases/options.js

@@ -10,7 +10,7 @@
 
 import path from 'node:path';
 import { parseSprintArgs } from '../../../cli-args.js';
-import { PROJECT_ROOT } from '../../../config-resolver.js';
+import { PROJECT_ROOT } from '../../../project-root.js';
 
 /**
  * Resolve a flag value from an explicit override, a parsed CLI arg, or a

package/.agents/scripts/lib/orchestration/single-story-close/phases/pull-request.js

@@ -19,6 +19,7 @@
 
 import { gh as defaultGh } from '../../../gh-exec.js';
 import { Logger } from '../../../Logger.js';
+import { normalizePrTitle } from './normalize-pr-title.js';
 
 /**
  * Probe for an existing open PR with `head = storyBranch`; create one if
@@ -76,9 +77,21 @@ export async function ensurePullRequestWith({
   }
 
   progress('PR', `Opening PR for ${storyBranch} → ${baseBranch}...`);
-  const title = storyTitle?.trim()
-    ? `${storyTitle} (#${storyId})`
-    : `Story #${storyId}`;
+  // The repo squash-merges and GitHub uses the PR title as the squash
+  // subject on `main`. A raw human issue title is not a Conventional
+  // Commit, so release-please silently counts it as 0 releasable commits
+  // (Story #3969). Normalize the title to conventional form: preserve an
+  // already-conventional `storyTitle` verbatim, otherwise synthesize a
+  // type derived from the branch's own commit subjects (default `chore`).
+  // `gh-exec` spawns `gh` against the current process cwd (the worktree),
+  // so the branch-commit read uses the same cwd.
+  const title = normalizePrTitle({
+    storyTitle,
+    storyId,
+    storyBranch,
+    baseBranch,
+    cwd: _cwd ?? process.cwd(),
+  });
   const body = [
     `Closes #${storyId}`,
     '',

package/.agents/scripts/lib/orchestration/single-story-close/runner.js

@@ -1,9 +1,7 @@
 import nodeFs from 'node:fs';
 import path from 'node:path';
-import {
-  buildDefaultGates,
-  runCloseValidation,
-} from '../../close-validation.js';
+import { buildDefaultGates } from '../../close-validation/gates.js';
+import { runCloseValidation } from '../../close-validation/runner.js';
 import { resolveConfig } from '../../config-resolver.js';
 import { getStoryBranch, gitSync } from '../../git-utils.js';
 import { Logger } from '../../Logger.js';

package/.agents/scripts/lib/orchestration/single-story-lease-guard.js

@@ -39,16 +39,20 @@
  */
 
 import {
-  acquireLease,
-  normalizeOperatorHandle,
-  releaseLease,
-} from './ticket-lease.js';
+  acquireLeaseFailClosed,
+  resolveOperatorFromCandidates,
+} from './lease-guard-shared.js';
+import { releaseLease } from './ticket-lease.js';
 
 /**
  * Resolve the operator handle used as the lease owner from resolved config.
- * Routes through the shared `normalizeOperatorHandle` so a leading `@` is
+ * Routes through the shared lease-guard kernel
+ * (`lease-guard-shared.resolveOperatorFromCandidates`) so a leading `@` is
  * stripped (the assignees API expects bare logins, not `@`-prefixed mentions)
- * and the self-held-claim comparison matches.
+ * and the self-held-claim comparison matches. The standalone surface's
+ * missing-handle policy is `'throw'` (intentional divergence from the plan
+ * path's `'null'`): init has no best-effort leg that can degrade, so an
+ * unowned lease must refuse immediately.
  *
  * @param {object} config Resolved `.agentrc.json` config.
  * @returns {string} Bare operator handle.
@@ -58,17 +62,16 @@ import {
  *   path cannot safely serialise concurrent runs.
  */
 export function resolveOperator(config) {
-  const handle = normalizeOperatorHandle(config?.github?.operatorHandle);
-  if (handle === null) {
-    throw new Error(
+  return resolveOperatorFromCandidates({
+    candidates: [config?.github?.operatorHandle],
+    missingHandleBehavior: 'throw',
+    missingHandleMessage:
       'single-story lease: no operator identity is configured. ' +
-        'github.operatorHandle is unset or still the shipped `@[USERNAME]` ' +
-        'placeholder, so the standalone Story lease has no owner. Set your own ' +
-        'handle in .agentrc.local.json (e.g. { "github": { "operatorHandle": ' +
-        '"@your-login" } }) and re-run.',
-    );
-  }
-  return handle;
+      'github.operatorHandle is unset or still the shipped `@[USERNAME]` ' +
+      'placeholder, so the standalone Story lease has no owner. Set your own ' +
+      'handle in .agentrc.local.json (e.g. { "github": { "operatorHandle": ' +
+      '"@your-login" } }) and re-run.',
+  });
 }
 
 /**
@@ -99,31 +102,25 @@ export async function acquireStoryLease({
   now,
 }) {
   const owner = operator ?? resolveOperator(config);
-  // Fail closed: with no live-heartbeat source on the standalone path, treat a
-  // foreign assignee as a live claim. Anchoring `heartbeatAt` to the same
-  // `now` the primitive evaluates against makes `isClaimLive` return true for
-  // any foreign owner, so `acquireLease` refuses unless `steal` is set.
-  const resolvedNow =
-    typeof now === 'number' && Number.isFinite(now) ? now : Date.now();
-  const result = await acquireLease({
+  // Fail closed: with no live-heartbeat source on the standalone path, the
+  // shared kernel anchors `heartbeatAt` to the same `now` the primitive
+  // evaluates against, so `isClaimLive` returns true for any foreign owner
+  // and `acquireLease` refuses unless `steal` is set.
+  return acquireLeaseFailClosed({
     provider,
     ticketId: storyId,
     operator: owner,
-    heartbeatAt: resolvedNow,
     steal,
     config,
-    now: resolvedNow,
-  });
-  if (!result.acquired) {
-    throw new Error(
+    now,
+    anchorHeartbeatToNow: true,
+    renderRefusal: (result) =>
       `single-story lease: Story #${storyId} is currently held by @${result.owner}. ` +
-        'Another /single-story-deliver run owns this Story. Coordinate with that ' +
-        'operator, or re-run with --steal to forcibly transfer the claim once you ' +
-        'have confirmed the other run is dead. (The standalone path has no Epic ' +
-        'heartbeat ledger, so a foreign assignee always blocks unless stolen.)',
-    );
-  }
-  return result;
+      'Another /single-story-deliver run owns this Story. Coordinate with that ' +
+      'operator, or re-run with --steal to forcibly transfer the claim once you ' +
+      'have confirmed the other run is dead. (The standalone path has no Epic ' +
+      'heartbeat ledger, so a foreign assignee always blocks unless stolen.)',
+  });
 }
 
 /**

package/.agents/scripts/lib/orchestration/skill-capsule-loader.js

@@ -12,9 +12,8 @@
 
 import fs from 'node:fs';
 import path from 'node:path';
-
-import { PROJECT_ROOT } from '../config-resolver.js';
 import { Logger } from '../Logger.js';
+import { PROJECT_ROOT } from '../project-root.js';
 
 const POLICY_HEADING_RE = /^## Policy Capsule\s*$/;
 const ANY_H2_RE = /^## /;