mandrel 1.57.0

package/.agents/scripts/lib/dynamic-workflow/security-report-contract.js

@@ -0,0 +1,83 @@
+// .agents/scripts/lib/dynamic-workflow/security-report-contract.js
+import { assertSectionsContract } from './report-contract-core.js';
+
+/**
+ * The `audit-security` report contract (Epic #3597, Story #3613).
+ *
+ * This is the **single source of truth** for the report shape that BOTH the
+ * sequential lens (`.agents/workflows/audit-security.md` Step 3) and the
+ * orchestrated dynamic-workflow path
+ * (`.claude/workflows/audit-security.workflow.js`) MUST emit to
+ * `{{auditOutputDir}}/audit-security-results.md`. Keeping it here lets the
+ * contract-tier test assert report conformance against one definition rather
+ * than re-deriving headings from prose in two places.
+ *
+ * Generalising the orchestrated dual path to the security lens is explicitly
+ * **report-contract-preserving** — this module documents the existing shape the
+ * sequential lens already emits, it does not introduce a new one.
+ *
+ * @module dynamic-workflow/security-report-contract
+ */
+
+/** The artifact filename the lens writes under `auditOutputDir`. */
+export const REPORT_ARTIFACT_BASENAME = 'audit-security-results.md';
+
+/**
+ * The required top-level (`##`) section headings, in document order, that the
+ * lens markdown's Step 3 template defines. A conformant report MUST contain
+ * each of these headings; the orchestrated path assembles its cross-checked
+ * findings into exactly this skeleton.
+ */
+export const REQUIRED_SECTIONS = Object.freeze([
+  'Executive Summary',
+  'Detailed Findings',
+  'Defensive Recommendations',
+]);
+
+/** The H1 title the report opens with. */
+export const REPORT_TITLE = 'Security Audit Report';
+
+/**
+ * The required field labels inside each `### <finding>` block under
+ * `## Detailed Findings`. Mirrors the strict per-finding structure in the
+ * lens template.
+ */
+export const FINDING_FIELDS = Object.freeze([
+  'Dimension',
+  'Severity',
+  'CWE ID',
+  'Current State',
+  'Recommendation & Rationale',
+  'Agent Prompt',
+]);
+
+/**
+ * The severity buckets the Executive Summary risk profile and per-finding
+ * `Severity` field draw from. The lens speaks in High/Medium/Low (with
+ * Critical as the top High band); this list is the canonical taxonomy the
+ * downstream `audit-to-stories` consumer maps onto Story priority.
+ */
+export const SEVERITY_LEVELS = Object.freeze([
+  'Critical',
+  'High',
+  'Medium',
+  'Low',
+]);
+
+/**
+ * Assert that a rendered markdown report conforms to the contract: it has the
+ * H1 title and every required `##` section heading. Returns a structured
+ * result rather than throwing, so callers (tests, the orchestrated path's
+ * self-check) can report precisely which sections are missing.
+ *
+ * Pure function — string analysis only.
+ *
+ * @param {string} markdown - The rendered report body.
+ * @returns {{ conformant: boolean, missingSections: string[], hasTitle: boolean }}
+ */
+export function assertReportContract(markdown) {
+  return assertSectionsContract(markdown, {
+    title: REPORT_TITLE,
+    requiredSections: REQUIRED_SECTIONS,
+  });
+}

package/.agents/scripts/lib/env-loader.js

@@ -0,0 +1,52 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { Logger } from './Logger.js';
+
+/**
+ * Auto-load .env from the project root if it exists
+ */
+export function loadEnv(projectRoot) {
+  const envPath = path.resolve(projectRoot, '.env');
+  let envContent;
+  try {
+    // Read directly rather than existsSync + readFileSync: the latter is a
+    // TOCTOU race (the file can vanish between the two calls) and double-stats
+    // the path. A single read with code-based error handling is both correct
+    // and cheaper.
+    envContent = fs.readFileSync(envPath, 'utf8');
+  } catch (err) {
+    // A missing .env is the expected case — environment may be provided via
+    // other means, so stay silent. Any other failure (permissions, a
+    // directory in place of the file, I/O error) is worth surfacing so the
+    // operator gets a one-line hint instead of an opaque silent skip.
+    if (err.code !== 'ENOENT') {
+      Logger.warn(
+        `env-loader: failed to read ${envPath} (${err.code ?? err.message}); skipping .env load.`,
+      );
+    }
+    return;
+  }
+
+  envContent.split('\n').forEach((line) => {
+    const match = line.match(/^\s*([\w.-]+)\s*=\s*(.*)?\s*$/);
+    if (match) {
+      const key = match[1];
+      let value = (match[2] || '').trim();
+      // Remove quotes if present
+      if (
+        value.length > 0 &&
+        value.charAt(0) === '"' &&
+        value.charAt(value.length - 1) === '"'
+      ) {
+        value = value.substring(1, value.length - 1);
+      } else if (
+        value.length > 0 &&
+        value.charAt(0) === "'" &&
+        value.charAt(value.length - 1) === "'"
+      ) {
+        value = value.substring(1, value.length - 1);
+      }
+      process.env[key] = value;
+    }
+  });
+}

package/.agents/scripts/lib/epic-merge-lock.js

@@ -0,0 +1,239 @@
+/**
+ * lib/epic-merge-lock.js — Filesystem mutex for Epic-branch merges.
+ *
+ * Parallel-wave story closures can race on the Epic branch: two
+ * `story-close.js` invocations both `git checkout <epic>`, both
+ * `git pull --rebase`, and both attempt to merge — the second push
+ * often ends up rejected or, worse, races past the first and produces
+ * an incorrect history.
+ *
+ * This module provides a best-effort cooperative lock keyed per Epic.
+ * The lock file lives at `<repoRoot>/.git/epic-<epicId>.merge.lock`
+ * (inside `.git/` so it never lands in a commit). Acquisition uses
+ * `fs.openSync(..., 'wx')` for atomicity; on contention we poll every
+ * 250ms until `timeoutMs` elapses.
+ *
+ * Stale-lock stealing:
+ *   - If the PID recorded in the lock is not running (per
+ *     `process.kill(pid, 0)`), or
+ *   - if the lock file is older than `timeoutMs * 2`,
+ *   the lock is stolen (unlinked) and re-acquired.
+ *
+ * Test seams (mirroring `single-story-sweep/sweep-lock.js`):
+ *   - `nowFn`   — `() => number` (ms epoch); replaces `Date.now`.
+ *   - `fsImpl`  — Node `fs` shim; replaces the imported `fs`.
+ *   - `killFn`  — `(pid, signal) => void`; replaces `process.kill`,
+ *                 so a test can make `pidDead` deterministic without
+ *                 fabricating a real dead PID.
+ *   - `sleepFn` — `(ms) => Promise<void>`; replaces the real
+ *                 `setTimeout`-backed sleep, so the poll loop can spin
+ *                 with no wall-clock waits.
+ * All four default to the real implementations, so production callers
+ * (`acquire(epicId, { repoRoot, timeoutMs })`) see no behavior change.
+ */
+
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+
+const POLL_INTERVAL_MS = 250;
+
+/**
+ * Resolve the *common* gitdir for a given working directory.
+ *
+ * In a linked worktree (`git worktree add ...`), `<repoRoot>/.git` is a
+ * one-line gitlink **file**, not a directory. `path.join(repoRoot, '.git')`
+ * therefore points at the gitlink file and any `mkdir`/`openSync` against
+ * it fails with `EEXIST: file already exists`.
+ *
+ * Resolution order:
+ *   1. If `<repoRoot>/.git` is already a directory, return it. Covers the
+ *      main-checkout case and the test fixtures, which create a bare
+ *      `.git/` under a temp root — no need to spawn git for those.
+ *   2. Otherwise (gitlink file, or `.git` absent), shell out to
+ *      `git rev-parse --git-common-dir`. In a worktree this returns the
+ *      parent repo's `.git/`, so lock files placed there are shared
+ *      across every worktree racing on the same Epic — which is the
+ *      correct semantics for an epic-merge mutex.
+ *   3. If neither succeeds, fall back to `<repoRoot>/.git`. Lock
+ *      acquisition will then surface the underlying error to the
+ *      operator with the literal path that failed.
+ */
+export function resolveGitCommonDir(repoRoot, fsImpl = fs) {
+  const local = path.join(repoRoot, '.git');
+  try {
+    if (fsImpl.statSync(local).isDirectory()) return local;
+  } catch {
+    // .git does not exist — fall through to git rev-parse.
+  }
+  try {
+    const out = execFileSync('git', ['rev-parse', '--git-common-dir'], {
+      cwd: repoRoot,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+    if (out) return path.isAbsolute(out) ? out : path.resolve(repoRoot, out);
+  } catch {
+    // not a git repo, or git is unavailable — fall through.
+  }
+  return local;
+}
+
+function lockPathFor(epicId, repoRoot, fsImpl = fs) {
+  return path.join(
+    resolveGitCommonDir(repoRoot, fsImpl),
+    `epic-${epicId}.merge.lock`,
+  );
+}
+
+function isProcessRunning(pid, killFn = process.kill) {
+  if (!Number.isFinite(pid) || pid <= 0) return false;
+  try {
+    // Signal 0 does not deliver a signal; it just checks existence.
+    killFn(pid, 0);
+    return true;
+  } catch (err) {
+    // ESRCH = no such process. EPERM = exists but we can't signal — still alive.
+    return err.code === 'EPERM';
+  }
+}
+
+function readLockMeta(filePath, fsImpl = fs) {
+  try {
+    const raw = fsImpl.readFileSync(filePath, 'utf8');
+    const parsed = JSON.parse(raw);
+    return {
+      pid: Number(parsed.pid),
+      acquiredAt: Number(parsed.acquiredAt),
+    };
+  } catch {
+    return null;
+  }
+}
+
+function tryStealStale(filePath, timeoutMs, seams) {
+  const { fsImpl, nowFn, killFn } = seams;
+  let stats;
+  try {
+    stats = fsImpl.statSync(filePath);
+  } catch {
+    return false;
+  }
+
+  const meta = readLockMeta(filePath, fsImpl);
+  // Corrupted lock file (null meta): we can't verify the writer's PID and
+  // the age comparison is unsafe on Windows where NTFS mtime vs Date.now()
+  // can disagree by hundreds of milliseconds, falsely flipping `ancient`
+  // true at short timeouts. Treat the file as held; the caller times out.
+  // A truly stuck corrupted lock has to be cleared manually — that's the
+  // safer failure mode than wrongly stealing a lock another process owns.
+  if (!meta) return false;
+
+  const ageMs = nowFn() - stats.mtimeMs;
+  const pidDead = !isProcessRunning(meta.pid, killFn);
+  const ancient = ageMs > timeoutMs * 2;
+
+  if (pidDead || ancient) {
+    try {
+      fsImpl.unlinkSync(filePath);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  return false;
+}
+
+function defaultSleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// Inner polling loop. Acquires the lock file with `wx` (atomic
+// create-or-error); on EEXIST it tries to steal a stale lock, then
+// either times out or sleeps and retries. Kept separate from
+// `acquireEpicMergeLock` so the public function's cyclomatic complexity
+// stays flat under CRAP.
+async function pollForLock(epicId, filePath, timeoutMs, seams) {
+  const { fsImpl, nowFn, sleepFn } = seams;
+  const started = nowFn();
+  while (true) {
+    try {
+      const fd = fsImpl.openSync(filePath, 'wx');
+      const acquiredAt = nowFn();
+      fsImpl.writeSync(
+        fd,
+        JSON.stringify({ pid: process.pid, acquiredAt }, null, 2),
+      );
+      fsImpl.closeSync(fd);
+      return { epicId, filePath, acquiredAt };
+    } catch (err) {
+      if (err.code !== 'EEXIST') throw err;
+      if (tryStealStale(filePath, timeoutMs, seams)) continue;
+      if (nowFn() - started >= timeoutMs) {
+        const meta = readLockMeta(filePath, fsImpl);
+        const detail = meta
+          ? ` (held by pid ${meta.pid} since ${new Date(meta.acquiredAt).toISOString()})`
+          : '';
+        throw new Error(
+          `acquireEpicMergeLock timed out after ${timeoutMs}ms for epic ${epicId}${detail}`,
+        );
+      }
+      await sleepFn(POLL_INTERVAL_MS);
+    }
+  }
+}
+
+/**
+ * Acquire an exclusive Epic merge lock.
+ *
+ * @param {number|string} epicId
+ * @param {object} opts
+ * @param {string} opts.repoRoot            Repo working dir; the lock lands
+ *                                          in its common `.git/`.
+ * @param {number} [opts.timeoutMs=60000]   Poll-until deadline.
+ * @param {() => number} [opts.nowFn]       Clock seam (ms epoch).
+ * @param {object} [opts.fsImpl]            Node `fs` shim.
+ * @param {(pid:number, signal:number)=>void} [opts.killFn]
+ *                                          `process.kill` shim for the
+ *                                          pid-liveness probe.
+ * @param {(ms:number)=>Promise<void>} [opts.sleepFn]
+ *                                          Poll-interval sleep shim.
+ * @returns {Promise<{ epicId: number|string, filePath: string, acquiredAt: number }>}
+ * @throws {Error} on timeout.
+ */
+export async function acquireEpicMergeLock(
+  epicId,
+  {
+    repoRoot,
+    timeoutMs = 60_000,
+    nowFn = Date.now,
+    fsImpl = fs,
+    killFn = process.kill.bind(process),
+    sleepFn = defaultSleep,
+  } = {},
+) {
+  if (!repoRoot) throw new Error('acquireEpicMergeLock: repoRoot is required');
+
+  const filePath = lockPathFor(epicId, repoRoot, fsImpl);
+  // Ensure the .git directory exists (it will, in a real repo, but the
+  // tests use a temp dir and need us to be forgiving).
+  fsImpl.mkdirSync(path.dirname(filePath), { recursive: true });
+
+  const seams = { fsImpl, nowFn, killFn, sleepFn };
+  return pollForLock(epicId, filePath, timeoutMs, seams);
+}
+
+/**
+ * Release a previously-acquired Epic merge lock.
+ *
+ * @param {{ filePath: string }} handle
+ * @param {object} [fsImpl] Node `fs` shim for tests.
+ */
+export function releaseEpicMergeLock(handle, fsImpl = fs) {
+  if (!handle?.filePath) return;
+  try {
+    fsImpl.unlinkSync(handle.filePath);
+  } catch (err) {
+    if (err.code !== 'ENOENT') throw err;
+  }
+}

package/.agents/scripts/lib/epic-plan-clarity.js

@@ -0,0 +1,142 @@
+/**
+ * epic-plan-clarity.js — Phase 6 Epic Clarity Gate scoring.
+ *
+ * Pure, deterministic rubric: parse the Epic body for the five canonical
+ * sections defined by `.agents/templates/epic-from-idea.md` (Context,
+ * Goal, Non-Goals, Scope, Acceptance Criteria) and emit a verdict of
+ * `clear` or `needs-refinement` along with a gap list for the refinement
+ * loop seed.
+ *
+ * Verdict rule: `clear` requires **both** (a) ≥ 4 of 5 canonical sections
+ * present, **and** (b) the **Acceptance Criteria** section present. The
+ * Acceptance-Criteria requirement is load-bearing: a downstream
+ * `/epic-deliver` start gate and the close-time acceptance-spec reconciler
+ * both assume the Epic carries acceptance criteria, so a gate that passed an
+ * Epic with no Acceptance Criteria (the pre-Story-#3910 `≥ 4 of 5` behaviour)
+ * advertised a clarity guarantee it did not provide. AC is now a required
+ * section, not one of the four optional passers.
+ *
+ * Heading variants accepted per canonical section (back-compat with the
+ * pre-canonical-headings ideation shape):
+ *   - `## Context`, `## Background`, `## Problem`, `## Problem Statement`,
+ *     `## Context & Problem`
+ *   - `## Goal`, `## Goals`, `## Objective`, `## Objectives`,
+ *     `## Direction`, `## Recommended Direction`
+ *   - `## Non-Goals`, `## Non Goals`, `## Out of Scope`, `## Not Doing`,
+ *     `## Not Doing (and Why)`
+ *   - `## Scope`, `## Scope (...)`, `## MVP Scope`, `## Proposed Scope`,
+ *     `## Work Breakdown`
+ *   - `## Acceptance Criteria`, `## Acceptance`, `## AC`
+ *
+ * Pure ESM, no I/O.
+ */
+
+const SECTION_RE = {
+  context:
+    /^##\s+(?:Context(?:\s+&\s+Problem)?|Background|Problem(?:\s+Statement)?)\s*$/im,
+  goal: /^##\s+(?:Goals?|Objectives?|(?:Recommended\s+)?Direction)\s*$/im,
+  nonGoals:
+    /^##\s+(?:Non[\s-]?Goals|Out\s+of\s+Scope|Not\s+Doing(?:\s+\(and\s+Why\))?)\s*$/im,
+  scope:
+    /^##\s+(?:MVP\s+|Proposed\s+)?Scope(?:\s+\([^)]+\))?\s*$|^##\s+Work\s+Breakdown\s*$/im,
+  acceptanceCriteria: /^##\s+(?:Acceptance(?:\s+Criteria)?|AC)\s*$/im,
+};
+
+/**
+ * Canonical section names, in document order. Exported so callers (CLI,
+ * tests, downstream tooling) can iterate without re-deriving the list.
+ */
+export const SECTION_NAMES = Object.freeze([
+  'context',
+  'goal',
+  'nonGoals',
+  'scope',
+  'acceptanceCriteria',
+]);
+
+const CLEAR_THRESHOLD = 4;
+const PLACEHOLDER_PATTERN = /^_\(not\s+specified\)_$/i;
+
+/**
+ * Classify a section's content as `present`, `placeholder`, or `missing`.
+ *
+ * @param {string|null} content - The text between this heading and the next
+ *   `## ` heading (or EOF). `null` when the heading was not found.
+ * @returns {'present' | 'placeholder' | 'missing'}
+ */
+function classify(content) {
+  if (content === null) return 'missing';
+  const trimmed = content.trim();
+  if (trimmed.length === 0) return 'placeholder';
+  if (PLACEHOLDER_PATTERN.test(trimmed)) return 'placeholder';
+  return 'present';
+}
+
+/**
+ * Score an Epic body against the five canonical sections.
+ *
+ * @param {{ body: string }} args
+ * @returns {{
+ *   verdict: 'clear' | 'needs-refinement',
+ *   sections: Array<{ name: string, status: 'present' | 'placeholder' | 'missing' }>,
+ *   missingOrPlaceholder: string[],
+ * }}
+ */
+const REQUIRED_SECTION = 'acceptanceCriteria';
+
+export function scoreEpicBody({ body } = {}) {
+  const source = typeof body === 'string' ? body : '';
+
+  // First pass: locate every canonical heading and its byte offset so we
+  // can slice the section body up to the next `## ` heading or EOF.
+  const headingHits = [];
+  for (const name of SECTION_NAMES) {
+    const re = SECTION_RE[name];
+    const m = source.match(re);
+    if (m && typeof m.index === 'number') {
+      headingHits.push({
+        name,
+        start: m.index,
+        headingLength: m[0].length,
+      });
+    }
+  }
+  headingHits.sort((a, b) => a.start - b.start);
+
+  // Generic next-heading regex (any `## ` heading, including non-canonical
+  // ones the author may have added between canonical sections).
+  const NEXT_HEADING_RE = /^##\s+/m;
+
+  /** @type {Map<string, string>} */
+  const contentByName = new Map();
+  for (const hit of headingHits) {
+    const sliceStart = hit.start + hit.headingLength;
+    const rest = source.slice(sliceStart);
+    const nextMatch = rest.match(NEXT_HEADING_RE);
+    const sliceEnd =
+      nextMatch && typeof nextMatch.index === 'number'
+        ? sliceStart + nextMatch.index
+        : source.length;
+    contentByName.set(hit.name, source.slice(sliceStart, sliceEnd));
+  }
+
+  const sections = SECTION_NAMES.map((name) => {
+    const content = contentByName.has(name) ? contentByName.get(name) : null;
+    return { name, status: classify(content ?? null) };
+  });
+
+  const missingOrPlaceholder = sections
+    .filter((s) => s.status !== 'present')
+    .map((s) => s.name);
+
+  const presentCount = sections.filter((s) => s.status === 'present').length;
+  const requiredPresent = sections.some(
+    (s) => s.name === REQUIRED_SECTION && s.status === 'present',
+  );
+  const verdict =
+    presentCount >= CLEAR_THRESHOLD && requiredPresent
+      ? 'clear'
+      : 'needs-refinement';
+
+  return { verdict, sections, missingOrPlaceholder };
+}