mandrel 1.57.0

package/.agents/scripts/lib/single-story-sweep.js

@@ -0,0 +1,329 @@
+/**
+ * single-story-sweep.js — Sweep merged `story-*` branches at init.
+ *
+ * Wraps `git-cleanup-branches.js` with a fixed policy tuned for the
+ * `/single-story-deliver` boot path:
+ *
+ *   - Scope: `story-*` only (never touches `epic/*`, `story/<id>/*`, etc.).
+ *   - Mode:  --execute --remote (delete local + origin + prune trackers).
+ *   - Skip:  the current run's `storyBranch` is always excluded, even if a
+ *            stale PR for the same id were already merged.
+ *   - Protection (Story #2011): each candidate is filtered through
+ *            `evaluateProtection` before reaching `executeCleanup`. A
+ *            candidate is protected (not reaped) when its branch HEAD
+ *            differs from the PR's `headRefOid` (unpushed work), when
+ *            its worktree has uncommitted edits, or when the parent
+ *            Story ticket is not in a terminal state. Protected
+ *            candidates surface in the result envelope under
+ *            `protected` so the operator can see what was skipped.
+ *   - Concurrency (Story #2011): the sweep acquires a process-scoped
+ *            lockfile around plan + execute. On lock contention the
+ *            sweep is skipped (init continues — same contract as a
+ *            plan failure).
+ *   - Errors are caught and surfaced in the envelope. The caller MUST NOT
+ *            propagate sweep failures — story init proceeds either way.
+ *
+ * Re-exports the same `planCleanup` / `executeCleanup` injection seams so
+ * tests can stub git/`gh` without touching the CLI.
+ */
+
+import {
+  buildGlobFilter,
+  executeCleanup as defaultExecuteCleanup,
+  planCleanup as defaultPlanCleanup,
+} from '../git-cleanup.js';
+import { evaluateProtection as defaultEvaluateProtection } from './single-story-sweep/protection.js';
+import { acquireSweepLock as defaultAcquireSweepLock } from './single-story-sweep/sweep-lock.js';
+
+const STORY_BRANCH_INCLUDE = 'story-*';
+
+/**
+ * Sweep merged `story-*` branches in `cwd`.
+ *
+ * @param {{
+ *   cwd: string,
+ *   baseBranch: string,
+ *   currentStoryBranch: string,
+ *   logger?: { info?: (m: string) => void, warn?: (m: string) => void },
+ *   planCleanupFn?: typeof defaultPlanCleanup,
+ *   executeCleanupFn?: typeof defaultExecuteCleanup,
+ *   protectionFn?: typeof defaultEvaluateProtection,
+ *   protectionCtx?: object,
+ *   acquireLockFn?: typeof defaultAcquireSweepLock,
+ *   lockPath?: string|null,
+ *   lockTimeoutMs?: number,
+ * }} args
+ * @returns {Promise<{
+ *   ok: boolean,
+ *   skipped: boolean,
+ *   candidates: number,
+ *   localDeleted: number,
+ *   remoteDeleted: number,
+ *   protected: Array<{ branch: string, reason: string, worktreePath?: string|null }>,
+ *   failures: Array<{ branch: string|null, scope: string, stderr?: string }>,
+ *   error?: string,
+ *   reason?: string,
+ * }>}
+ */
+export async function sweepMergedStoryBranches({
+  cwd,
+  baseBranch,
+  currentStoryBranch,
+  logger = {},
+  planCleanupFn = defaultPlanCleanup,
+  executeCleanupFn = defaultExecuteCleanup,
+  protectionFn = defaultEvaluateProtection,
+  protectionCtx = null,
+  acquireLockFn = defaultAcquireSweepLock,
+  lockPath = null,
+  lockTimeoutMs = 60_000,
+} = {}) {
+  const log = {
+    info: typeof logger.info === 'function' ? logger.info : () => {},
+    warn: typeof logger.warn === 'function' ? logger.warn : () => {},
+  };
+
+  if (typeof cwd !== 'string' || cwd.length === 0) {
+    return zeroResult({ error: 'cwd is required' });
+  }
+  if (typeof baseBranch !== 'string' || baseBranch.length === 0) {
+    return zeroResult({ error: 'baseBranch is required' });
+  }
+
+  // Optional lock acquisition. Skip silently when no lockPath is
+  // supplied (e.g. unit tests, callers that opt out). Contention is
+  // non-fatal — return a skipped result and let init continue.
+  let releaseLock = () => {};
+  if (lockPath) {
+    const lockResult = acquireLockFn({
+      lockPath,
+      timeoutMs: lockTimeoutMs,
+    });
+    if (!lockResult.acquired) {
+      log.warn(
+        `[single-story-sweep] lock not acquired (${lockResult.reason}${
+          lockResult.detail ? `: ${lockResult.detail}` : ''
+        }); skipping sweep.`,
+      );
+      return {
+        ok: true,
+        skipped: true,
+        reason: `lock-${lockResult.reason}`,
+        candidates: 0,
+        localDeleted: 0,
+        remoteDeleted: 0,
+        protected: [],
+        failures: [],
+      };
+    }
+    releaseLock = lockResult.release;
+  }
+
+  try {
+    return await runSweepUnderLock({
+      cwd,
+      baseBranch,
+      currentStoryBranch,
+      log,
+      planCleanupFn,
+      executeCleanupFn,
+      protectionFn,
+      protectionCtx,
+    });
+  } finally {
+    try {
+      releaseLock();
+    } catch {
+      // Lock release is best-effort.
+    }
+  }
+}
+
+/**
+ * Inner: the plan + protect + execute pipeline. Kept separate so the
+ * outer `sweepMergedStoryBranches` can stay focused on the lock
+ * acquire/release wrapper.
+ */
+async function runSweepUnderLock({
+  cwd,
+  baseBranch,
+  currentStoryBranch,
+  log,
+  planCleanupFn,
+  executeCleanupFn,
+  protectionFn,
+  protectionCtx,
+}) {
+  const exclude =
+    typeof currentStoryBranch === 'string' && currentStoryBranch.length > 0
+      ? [currentStoryBranch]
+      : [];
+  const filter = buildGlobFilter({
+    include: [STORY_BRANCH_INCLUDE],
+    exclude,
+  });
+
+  let plan;
+  try {
+    plan = planCleanupFn({ cwd, baseBranch, filter });
+  } catch (err) {
+    const msg = err?.message ?? String(err);
+    log.warn(`[single-story-sweep] plan failed: ${msg}`);
+    return zeroResult({ error: `plan: ${msg}` });
+  }
+
+  if (plan.candidates.length === 0) {
+    log.info('[single-story-sweep] no merged story branches to reap.');
+    return {
+      ok: true,
+      skipped: false,
+      candidates: 0,
+      localDeleted: 0,
+      remoteDeleted: 0,
+      protected: [],
+      failures: [],
+    };
+  }
+
+  const { reapable, protectedList } = await partitionCandidates({
+    candidates: plan.candidates,
+    protectionFn,
+    protectionCtx,
+    log,
+  });
+
+  if (reapable.length === 0) {
+    log.info(
+      `[single-story-sweep] all ${plan.candidates.length} candidate(s) protected; no reap.`,
+    );
+    return {
+      ok: true,
+      skipped: false,
+      candidates: plan.candidates.length,
+      localDeleted: 0,
+      remoteDeleted: 0,
+      protected: protectedList,
+      failures: [],
+    };
+  }
+
+  let result;
+  try {
+    result = executeCleanupFn({
+      candidates: reapable,
+      cwd,
+      remote: true,
+    });
+  } catch (err) {
+    const msg = err?.message ?? String(err);
+    log.warn(`[single-story-sweep] execute failed: ${msg}`);
+    return {
+      ok: false,
+      skipped: false,
+      candidates: plan.candidates.length,
+      localDeleted: 0,
+      remoteDeleted: 0,
+      protected: protectedList,
+      failures: [{ branch: null, scope: 'execute', stderr: msg }],
+      error: `execute: ${msg}`,
+    };
+  }
+
+  const localDeleted = result.local.filter((r) => r.ok).length;
+  const remoteDeleted = result.remote.filter((r) => r.ok).length;
+  const reapedBranches = reapable.map((c) => c.branch).join(', ');
+  const protectedSummary =
+    protectedList.length > 0
+      ? `; protected ${protectedList.length} (${protectedList
+          .map((p) => `${p.branch} → ${p.reason}`)
+          .join(', ')})`
+      : '';
+  const summary = `${localDeleted} local + ${remoteDeleted} remote${protectedSummary}`;
+  if (result.ok) {
+    log.info(
+      `[single-story-sweep] reaped ${summary}${reapedBranches ? ` [${reapedBranches}]` : ''}.`,
+    );
+  } else {
+    log.warn(
+      `[single-story-sweep] reaped ${summary} with ${result.failures.length} failure(s) — init continues.`,
+    );
+  }
+
+  return {
+    ok: result.ok,
+    skipped: false,
+    candidates: plan.candidates.length,
+    localDeleted,
+    remoteDeleted,
+    protected: protectedList,
+    failures: result.failures,
+  };
+}
+
+/**
+ * Iterate plan candidates and split them into `reapable` (safe to pass
+ * to executeCleanup) and `protectedList` (skipped, with a reason).
+ *
+ * Protection failures are treated as protected — never reap a candidate
+ * whose state we cannot verify. The reason string travels into the
+ * result envelope and the log line for postmortem clarity.
+ *
+ * When no `protectionCtx` is supplied (legacy callers, unit tests),
+ * the protection check is bypassed entirely and every candidate is
+ * reapable. The CLI surface in `single-story-init.js` always supplies
+ * a ctx, so this fallback never fires in production.
+ */
+async function partitionCandidates({
+  candidates,
+  protectionFn,
+  protectionCtx,
+  log,
+}) {
+  const reapable = [];
+  const protectedList = [];
+  for (const candidate of candidates) {
+    if (!protectionCtx) {
+      reapable.push(candidate);
+      continue;
+    }
+    let verdict;
+    try {
+      verdict = await protectionFn({ candidate, ctx: protectionCtx });
+    } catch (err) {
+      const reason = `protection-eval-error: ${err?.message ?? err}`;
+      log.warn(`[single-story-sweep] protected ${candidate.branch}: ${reason}`);
+      protectedList.push({
+        branch: candidate.branch,
+        reason,
+        worktreePath: candidate.worktreePath ?? null,
+      });
+      continue;
+    }
+    if (verdict?.protected) {
+      log.info(
+        `[single-story-sweep] protected ${candidate.branch}: ${verdict.reason}`,
+      );
+      protectedList.push({
+        branch: candidate.branch,
+        reason: verdict.reason ?? 'unknown',
+        worktreePath: candidate.worktreePath ?? null,
+      });
+      continue;
+    }
+    reapable.push(candidate);
+  }
+  return { reapable, protectedList };
+}
+
+function zeroResult({ error }) {
+  return {
+    ok: false,
+    skipped: true,
+    candidates: 0,
+    localDeleted: 0,
+    remoteDeleted: 0,
+    protected: [],
+    failures: [],
+    error,
+  };
+}

package/.agents/scripts/lib/skills/parse-skill.js

@@ -0,0 +1,202 @@
+// .agents/scripts/lib/skills/parse-skill.js
+//
+// Shared SKILL.md parser used by the skills index generator and the skills
+// validator. Pure I/O on top of a single fs.readFileSync — no network, no
+// child processes, no env reads. Tolerant of CRLF and LF line endings.
+//
+// Public API:
+//
+//   parseSkill(absolutePath, options?) -> {
+//     path,            // repo-relative POSIX path (string)
+//     tier,            // 'core' | 'stack'
+//     category,        // bucket directly under the tier (string)
+//     name,            // parent directory name of SKILL.md (string)
+//     frontmatter,     // YAML-parsed object from between the leading '---' markers
+//     policyCapsule: {
+//       found,         // boolean — true iff a '## Policy Capsule' heading exists
+//       bulletCount,   // integer — count of contiguous top-level '- ' bullets
+//       sectionStart,  // 1-based line number of the heading (null when absent)
+//     },
+//   }
+//
+// The parser asserts that frontmatter.name equals the parent directory name
+// and throws a descriptive Error when the two diverge.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import yaml from 'js-yaml';
+
+const FRONTMATTER_DELIMITER = '---';
+const POLICY_HEADING_RE = /^## Policy Capsule\s*$/;
+const ANY_H2_RE = /^## /;
+const BULLET_RE = /^- /;
+
+/**
+ * Repo root resolver. Walks up from the SKILL.md path until we find a
+ * directory that contains an `.agents/skills` folder — that's the canonical
+ * marker. Falls back to the file's grandparent's grandparent if no marker
+ * is found, which is good enough for tests using temp fixtures.
+ */
+function resolveRepoRoot(absoluteSkillPath) {
+  let dir = path.dirname(absoluteSkillPath);
+  while (dir !== path.dirname(dir)) {
+    if (fs.existsSync(path.join(dir, '.agents', 'skills'))) {
+      return dir;
+    }
+    dir = path.dirname(dir);
+  }
+  // Fallback for fixture trees rooted outside a real .agents layout.
+  return path.resolve(path.dirname(absoluteSkillPath), '..', '..', '..', '..');
+}
+
+function toPosix(p) {
+  return p.split(path.sep).join('/');
+}
+
+/**
+ * Split the source on either CRLF or LF without normalizing line endings.
+ * The returned array's length and indices match the original file's line
+ * count, which lets callers report 1-based line numbers verbatim.
+ */
+function splitLines(src) {
+  return src.split(/\r\n|\n/);
+}
+
+/**
+ * Extract the YAML frontmatter block sitting between the first two '---'
+ * lines. Throws when the file lacks a leading delimiter or never closes it.
+ */
+function extractFrontmatterBlock(lines, skillPath) {
+  if (lines[0] !== FRONTMATTER_DELIMITER) {
+    throw new Error(
+      `SKILL.md is missing the leading '---' frontmatter delimiter: ${skillPath}`,
+    );
+  }
+  for (let i = 1; i < lines.length; i += 1) {
+    if (lines[i] === FRONTMATTER_DELIMITER) {
+      return { yamlText: lines.slice(1, i).join('\n'), bodyStart: i + 1 };
+    }
+  }
+  throw new Error(
+    `SKILL.md frontmatter is not closed by a trailing '---': ${skillPath}`,
+  );
+}
+
+/**
+ * Scan the body for the '## Policy Capsule' heading and count contiguous
+ * top-level '- ' bullets that follow it, stopping at the next '## ' heading
+ * or end-of-file. Blank lines inside the bullet run do not reset the count;
+ * a non-bullet, non-blank line does.
+ */
+function findPolicyCapsule(lines, bodyStart) {
+  let headingIndex = -1;
+  for (let i = bodyStart; i < lines.length; i += 1) {
+    if (POLICY_HEADING_RE.test(lines[i])) {
+      headingIndex = i;
+      break;
+    }
+  }
+  if (headingIndex === -1) {
+    return { found: false, bulletCount: 0, sectionStart: null };
+  }
+
+  let bulletCount = 0;
+  let sawBulletRun = false;
+  for (let i = headingIndex + 1; i < lines.length; i += 1) {
+    const line = lines[i];
+    if (ANY_H2_RE.test(line)) break;
+    if (BULLET_RE.test(line)) {
+      bulletCount += 1;
+      sawBulletRun = true;
+      continue;
+    }
+    if (line.trim() === '') {
+      // Blank lines inside or before the bullet run are tolerated.
+      continue;
+    }
+    if (sawBulletRun) {
+      // Non-blank, non-bullet line after the bullet run terminates it.
+      break;
+    }
+    // Leading prose between heading and the first bullet is allowed.
+  }
+
+  return {
+    found: true,
+    bulletCount,
+    sectionStart: headingIndex + 1, // 1-based
+  };
+}
+
+/**
+ * Parse a SKILL.md file. See module-level docstring for the return shape.
+ */
+export function parseSkill(absolutePath, options = {}) {
+  if (typeof absolutePath !== 'string' || absolutePath.length === 0) {
+    throw new TypeError('parseSkill: absolutePath must be a non-empty string');
+  }
+  if (!path.isAbsolute(absolutePath)) {
+    throw new TypeError(
+      `parseSkill: absolutePath must be absolute (got ${absolutePath})`,
+    );
+  }
+
+  const repoRoot = options.repoRoot ?? resolveRepoRoot(absolutePath);
+  const src = fs.readFileSync(absolutePath, 'utf8');
+  const lines = splitLines(src);
+
+  const { yamlText, bodyStart } = extractFrontmatterBlock(lines, absolutePath);
+
+  let frontmatter;
+  try {
+    frontmatter = yaml.load(yamlText);
+  } catch (err) {
+    throw new Error(
+      `SKILL.md frontmatter is not valid YAML at ${absolutePath}: ${err.message}`,
+    );
+  }
+  if (
+    frontmatter === null ||
+    typeof frontmatter !== 'object' ||
+    Array.isArray(frontmatter)
+  ) {
+    throw new Error(
+      `SKILL.md frontmatter must be a YAML mapping at ${absolutePath}`,
+    );
+  }
+
+  const parentDir = path.dirname(absolutePath);
+  const dirName = path.basename(parentDir);
+
+  if (frontmatter.name !== dirName) {
+    throw new Error(
+      `SKILL.md frontmatter.name (${JSON.stringify(frontmatter.name)}) does not match parent directory name (${JSON.stringify(dirName)}) at ${absolutePath}`,
+    );
+  }
+
+  // Derive tier / category from the path. Layout is:
+  //   <repo>/.agents/skills/<tier>/<...buckets>/<name>/SKILL.md
+  // For core skills the bucket is the literal 'core' (one level deep);
+  // for stack skills the bucket is the first segment under 'stack'
+  // (e.g. 'backend', 'frontend', 'qa').
+  const relPath = toPosix(path.relative(repoRoot, absolutePath));
+  const parts = relPath.split('/');
+  const skillsIdx = parts.indexOf('skills');
+  let tier = null;
+  let category = null;
+  if (skillsIdx >= 0 && parts.length >= skillsIdx + 4) {
+    tier = parts[skillsIdx + 1];
+    category = tier === 'core' ? 'core' : parts[skillsIdx + 2];
+  }
+
+  const policyCapsule = findPolicyCapsule(lines, bodyStart);
+
+  return {
+    path: relPath,
+    tier,
+    category,
+    name: dirName,
+    frontmatter,
+    policyCapsule,
+  };
+}

package/.agents/scripts/lib/skills/walk-skill-files.js

@@ -0,0 +1,56 @@
+// .agents/scripts/lib/skills/walk-skill-files.js
+//
+// Shared traversal for SKILL.md files under `.agents/skills/{core,stack}/`.
+// Used by validate-skills.js and generate-skills-index.js so both CLIs
+// enumerate the same paths in the same deterministic order.
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Recursively enumerate `SKILL.md` paths under a directory.
+ *
+ * @param {string} rootDir
+ * @returns {string[]} absolute paths
+ */
+export function walkSkillFiles(rootDir) {
+  const out = [];
+  if (!fs.existsSync(rootDir)) return out;
+  const stack = [rootDir];
+  while (stack.length > 0) {
+    const dir = stack.pop();
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        stack.push(full);
+      } else if (entry.isFile() && entry.name === 'SKILL.md') {
+        out.push(full);
+      }
+    }
+  }
+  return out;
+}
+
+/**
+ * Build the list of SKILL.md files under `<repoRoot>/.agents/skills/{core,
+ * stack}/`, sorted by POSIX repo-relative path for deterministic output.
+ *
+ * @param {string} repoRoot
+ * @returns {string[]} absolute paths
+ */
+export function collectSkillFiles(repoRoot) {
+  const skillsRoot = path.join(repoRoot, '.agents', 'skills');
+  const coreFiles = walkSkillFiles(path.join(skillsRoot, 'core'));
+  const stackFiles = walkSkillFiles(path.join(skillsRoot, 'stack'));
+  return [...coreFiles, ...stackFiles].sort((a, b) => {
+    const ra = path.relative(repoRoot, a).split(path.sep).join('/');
+    const rb = path.relative(repoRoot, b).split(path.sep).join('/');
+    return ra < rb ? -1 : ra > rb ? 1 : 0;
+  });
+}

package/.agents/scripts/lib/spec/index.js

@@ -0,0 +1,36 @@
+/**
+ * lib/spec/index.js — public surface for the spec I/O module.
+ *
+ * Re-exports the loader (and, in Wave 1, future spec utilities) so
+ * downstream consumers — the reconciler, the rewritten /epic-plan, the
+ * wave-runner — can `import * from '../lib/spec/index.js'` without
+ * reaching into individual submodules.
+ *
+ * The module intentionally re-exports only the public surface defined
+ * by Story #1491; the loader's internal helpers (`_resetValidatorCacheForTests`,
+ * `sortKeysDeep`, `renderStateJson`) remain importable from
+ * `./loader.js` directly for tests but are not part of the consumer
+ * contract.
+ */
+
+export {
+  loadSpec,
+  loadState,
+  SpecNotFoundError,
+  SpecParseError,
+  SpecValidationError,
+  specPath,
+  statePath,
+  writeSpec,
+  writeState,
+} from './loader.js';
+
+export {
+  buildState,
+  canonicalise,
+  canonicalStringify,
+  hashSpecEntry,
+  iterSpecEntries,
+  projectMapping,
+  sha256Hex,
+} from './state.js';