mandrel 1.57.0

package/.agents/scripts/validate-skills.js

@@ -0,0 +1,278 @@
+#!/usr/bin/env node
+// .agents/scripts/validate-skills.js
+//
+// Walk `.agents/skills/{core,stack}/**/SKILL.md` via the shared parser
+// helper, validate each frontmatter block against
+// `.agents/schemas/skill.schema.json`, enforce Policy Capsule presence
+// (5–12 bullets), and verify membership in `.agents/skills/skills.index.json`
+// when that manifest exists. All findings are batched into a single
+// human-readable report; the process exits non-zero when any finding is
+// surfaced.
+//
+// CLI surface:
+//
+//   node validate-skills.js [--root <dir>]
+//
+//   --root <dir>   Use <dir> as the repo root (defaults to the project
+//                  root containing `.agents/skills`). Useful for tests
+//                  staging fixture trees outside the real repo.
+//
+// Honors AGENT_LOG_LEVEL via the shared `Logger`. The findings report is
+// written to stdout when any finding is present, so callers can capture
+// it for ticket comments or CI logs.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import Ajv from 'ajv';
+import addFormats from 'ajv-formats';
+import { parseStandardCliArgs } from './lib/cli/standard-args.js';
+import { runAsCli } from './lib/cli-utils.js';
+import { Logger } from './lib/Logger.js';
+import { parseSkill } from './lib/skills/parse-skill.js';
+import { collectSkillFiles } from './lib/skills/walk-skill-files.js';
+
+const MIN_CAPSULE_BULLETS = 5;
+const MAX_CAPSULE_BULLETS = 12;
+
+function defaultRepoRoot() {
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  return path.resolve(here, '..', '..');
+}
+
+export function parseArgs(argv) {
+  // `--help` / `-h` is a side-channel signal handled before the shared
+  // parser sees it: the shared parser does not (yet) model help flags as
+  // first-class output, and pre-stripping keeps the legacy parsed shape.
+  if (argv.some((t) => t === '--help' || t === '-h')) {
+    return { root: null, help: true };
+  }
+  const { values } = parseStandardCliArgs({
+    argv,
+    extras: { root: { type: 'string' } },
+  });
+  return { root: values.root };
+}
+
+/**
+ * Load the skill frontmatter schema from the in-repo schemas directory.
+ * Falls back to the script-relative path when the repo root override
+ * does not carry its own schema copy (fixture trees reuse the real one).
+ */
+function loadSkillSchema(repoRoot) {
+  const candidate = path.join(
+    repoRoot,
+    '.agents',
+    'schemas',
+    'skill.schema.json',
+  );
+  if (fs.existsSync(candidate)) {
+    return JSON.parse(fs.readFileSync(candidate, 'utf8'));
+  }
+  const fallback = path.resolve(
+    path.dirname(fileURLToPath(import.meta.url)),
+    '..',
+    'schemas',
+    'skill.schema.json',
+  );
+  return JSON.parse(fs.readFileSync(fallback, 'utf8'));
+}
+
+function loadManifestSchema(repoRoot) {
+  const candidate = path.join(
+    repoRoot,
+    '.agents',
+    'schemas',
+    'skills-index.schema.json',
+  );
+  if (fs.existsSync(candidate)) {
+    return JSON.parse(fs.readFileSync(candidate, 'utf8'));
+  }
+  const fallback = path.resolve(
+    path.dirname(fileURLToPath(import.meta.url)),
+    '..',
+    'schemas',
+    'skills-index.schema.json',
+  );
+  return JSON.parse(fs.readFileSync(fallback, 'utf8'));
+}
+
+function createAjv() {
+  const AjvCtor = Ajv.default ?? Ajv;
+  const ajv = new AjvCtor({ allErrors: true, strict: false });
+  const addFormatsFn = addFormats.default ?? addFormats;
+  addFormatsFn(ajv);
+  return ajv;
+}
+
+function buildValidator(repoRoot) {
+  const ajv = createAjv();
+  const schema = loadSkillSchema(repoRoot);
+  return ajv.compile(schema);
+}
+
+function buildManifestValidator(repoRoot) {
+  const ajv = createAjv();
+  const schema = loadManifestSchema(repoRoot);
+  return ajv.compile(schema);
+}
+
+/**
+ * Read the on-disk skills.index.json manifest, returning `{ exists, paths,
+ * manifest }` where `paths` is the Set of `entry.path` values when the file
+ * is present and parseable, or null otherwise.
+ */
+function readIndex(repoRoot) {
+  const indexPath = path.join(
+    repoRoot,
+    '.agents',
+    'skills',
+    'skills.index.json',
+  );
+  if (!fs.existsSync(indexPath)) {
+    return { exists: false, paths: null, manifest: null, indexPath };
+  }
+  try {
+    const manifest = JSON.parse(fs.readFileSync(indexPath, 'utf8'));
+    const paths = new Set(
+      Array.isArray(manifest.skills)
+        ? manifest.skills
+            .map((s) => s.path)
+            .filter((p) => typeof p === 'string')
+        : [],
+    );
+    return { exists: true, paths, manifest, indexPath };
+  } catch (err) {
+    return {
+      exists: true,
+      paths: null,
+      manifest: null,
+      indexPath,
+      parseError: err.message,
+    };
+  }
+}
+
+/**
+ * Validate a parsed manifest against skills-index.schema.json. Returns
+ * finding strings tagged with the `manifest-schema` pillar.
+ */
+function validateManifestSchema(manifest, indexRelPath, validateManifest) {
+  const findings = [];
+  if (!validateManifest(manifest)) {
+    for (const err of validateManifest.errors ?? []) {
+      const where = err.instancePath || '(root)';
+      findings.push(
+        `${indexRelPath}: manifest-schema: schema violation at ${where}: ${err.message}`,
+      );
+    }
+  }
+  return findings;
+}
+
+/**
+ * Validate a single SKILL.md. Returns an array of finding strings; an
+ * empty array means the file passed every gate.
+ */
+function validateOne(absPath, repoRoot, validateFrontmatter, indexPaths) {
+  const findings = [];
+  let parsed;
+  try {
+    parsed = parseSkill(absPath, { repoRoot });
+  } catch (err) {
+    findings.push(`${rel(absPath, repoRoot)}: parse error — ${err.message}`);
+    return findings;
+  }
+  if (!validateFrontmatter(parsed.frontmatter)) {
+    for (const err of validateFrontmatter.errors ?? []) {
+      const where = err.instancePath || '(root)';
+      findings.push(
+        `${parsed.path}: frontmatter schema violation at ${where}: ${err.message}`,
+      );
+    }
+  }
+  if (!parsed.policyCapsule.found) {
+    findings.push(`${parsed.path}: missing '## Policy Capsule' section`);
+  } else {
+    const n = parsed.policyCapsule.bulletCount;
+    if (n < MIN_CAPSULE_BULLETS || n > MAX_CAPSULE_BULLETS) {
+      findings.push(
+        `${parsed.path}: Policy Capsule has ${n} bullet(s); expected between ${MIN_CAPSULE_BULLETS} and ${MAX_CAPSULE_BULLETS}`,
+      );
+    }
+  }
+  if (indexPaths && !indexPaths.has(parsed.path)) {
+    findings.push(
+      `${parsed.path}: missing from .agents/skills/skills.index.json`,
+    );
+  }
+  return findings;
+}
+
+function rel(absPath, repoRoot) {
+  return path.relative(repoRoot, absPath).split(path.sep).join('/');
+}
+
+/**
+ * Pure entry point used by tests. Returns `{ status, output, findings }`.
+ */
+export function run({ argv = [], repoRoot } = {}) {
+  const parsed = parseArgs(argv);
+  if (parsed.help) {
+    return {
+      status: 0,
+      output: 'Usage: validate-skills.js [--root <dir>]',
+      findings: [],
+    };
+  }
+  const root = parsed.root
+    ? path.resolve(parsed.root)
+    : (repoRoot ?? defaultRepoRoot());
+  const validateFrontmatter = buildValidator(root);
+  const validateManifest = buildManifestValidator(root);
+  const indexInfo = readIndex(root);
+  const indexRel = rel(indexInfo.indexPath, root);
+
+  const findings = [];
+  if (!indexInfo.exists) {
+    findings.push(
+      `index missing: ${indexRel} not found — run 'node .agents/scripts/generate-skills-index.js'`,
+    );
+  } else if (indexInfo.paths === null) {
+    findings.push(`index unparseable: ${indexRel} — ${indexInfo.parseError}`);
+  } else if (indexInfo.manifest !== null) {
+    findings.push(
+      ...validateManifestSchema(indexInfo.manifest, indexRel, validateManifest),
+    );
+  }
+
+  const skillFiles = collectSkillFiles(root);
+  const indexPaths =
+    indexInfo.exists && indexInfo.paths !== null ? indexInfo.paths : null;
+  for (const file of skillFiles) {
+    findings.push(...validateOne(file, root, validateFrontmatter, indexPaths));
+  }
+
+  if (findings.length === 0) {
+    Logger.info(`validate-skills: ${skillFiles.length} skill(s) passed`);
+    return { status: 0, output: '', findings };
+  }
+
+  const header = `validate-skills: ${findings.length} finding(s) across ${skillFiles.length} skill(s)`;
+  const body = findings.map((f) => `  - ${f}`).join('\n');
+  return {
+    status: 1,
+    output: `${header}\n${body}`,
+    findings,
+  };
+}
+
+async function main() {
+  const result = run({ argv: process.argv.slice(2) });
+  if (result.output) {
+    process.stdout.write(`${result.output}\n`);
+  }
+  process.exit(result.status);
+}
+
+runAsCli(import.meta.url, main, { source: 'validate-skills' });

package/.agents/scripts/wave-tick.js

@@ -0,0 +1,335 @@
+#!/usr/bin/env node
+/* node:coverage ignore file */
+
+/**
+ * wave-tick.js — thin CLI shim around `lib/wave-runner/tick.js`.
+ *
+ * Reads the `epic-run-state` checkpoint plus fresh Story labels and
+ * prints one `WaveTickResult` envelope. The slash-command operator
+ * (`/epic-deliver`) consumes the envelope to decide whether to dispatch
+ * the next wave, observe in-flight stories, or finalize the Epic.
+ *
+ * Usage:
+ *   node .agents/scripts/wave-tick.js --epic <epicId> [--check-idle <minutes>]
+ *
+ * The tick is stateless — "loop until terminal" is the caller's job
+ * (today: the markdown's wave loop).
+ *
+ * Output: one JSON object on stdout. Schema in `lib/wave-runner/tick.js`.
+ */
+
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { parseArgs } from 'node:util';
+
+import { runAsCli } from './lib/cli-utils.js';
+import { epicLedgerPath } from './lib/config/temp-paths.js';
+import { resolveConfig } from './lib/config-resolver.js';
+import { Logger } from './lib/Logger.js';
+import { createProvider } from './lib/provider-factory.js';
+import { tick } from './lib/wave-runner/tick.js';
+
+const HELP = `Usage: node .agents/scripts/wave-tick.js --epic <epicId> [--check-idle <minutes>]
+
+Stateless wave-loop planner. Reads the epic-run-state checkpoint on
+Epic #<id>, evaluates the live story-label state, and prints one
+WaveTickResult envelope describing the next dispatchable action.
+
+When --check-idle <minutes> is supplied, the planner skips the normal
+WaveTickResult emit and instead scans the per-Epic lifecycle ledger
+(temp/epic-<id>/lifecycle.ndjson) for in-flight Stories whose most
+recent lifecycle event is older than the threshold. Emits a single
+JSON envelope on stdout and exits non-zero when at least one stalled
+Story is detected. The envelope shape mirrors the wave-stall
+structured-comment payload so the slash-command host can post it
+verbatim.
+`;
+
+export async function runWaveTickCli({
+  epicId,
+  cwd,
+  injectedProvider,
+  injectedConfig,
+} = {}) {
+  if (!Number.isInteger(epicId) || epicId <= 0) {
+    throw new TypeError('runWaveTickCli: --epic must be a positive integer');
+  }
+
+  const config = injectedConfig ?? resolveConfig({ cwd });
+  const provider = injectedProvider ?? createProvider(config);
+
+  const result = await tick({
+    epic: epicId,
+    collaborators: { provider },
+    ctx: { config },
+  });
+
+  return result;
+}
+
+/**
+ * Scan the per-Epic lifecycle ledger and compute, per in-flight Story,
+ * the timestamp of its most recent lifecycle event. A Story is
+ * "in-flight" when the ledger carries a `story.dispatch.start` record
+ * without a matching `story.dispatch.end`. Any other `story.*` event
+ * (notably `story.heartbeat` from Story #3057) refreshes the Story's
+ * last-event timestamp.
+ *
+ * Pure helper — exported for unit tests.
+ *
+ * @param {string} ledgerPath Absolute path to `lifecycle.ndjson`.
+ * @returns {Map<number, string>} `storyId → ISO-8601 timestamp`. Empty
+ *   when the ledger is missing, unreadable, or carries no in-flight
+ *   Stories.
+ */
+export function readLedgerLastEvents(ledgerPath) {
+  if (!ledgerPath || !existsSync(ledgerPath)) return new Map();
+  let raw;
+  try {
+    raw = readFileSync(ledgerPath, 'utf8');
+  } catch {
+    return new Map();
+  }
+  if (!raw) return new Map();
+  const started = new Set();
+  const ended = new Set();
+  const lastTs = new Map();
+  for (const line of raw.split(/\r?\n/)) {
+    if (!line) continue;
+    let record;
+    try {
+      record = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    if (!record || record.kind !== 'emitted') continue;
+    const event = typeof record.event === 'string' ? record.event : '';
+    if (!event.startsWith('story.')) continue;
+    const storyId = record.payload?.storyId;
+    if (!Number.isInteger(storyId) || storyId <= 0) continue;
+    if (event === 'story.dispatch.start') started.add(storyId);
+    else if (event === 'story.dispatch.end') ended.add(storyId);
+    const ts = typeof record.ts === 'string' ? record.ts : null;
+    if (ts) {
+      const prior = lastTs.get(storyId);
+      if (!prior || prior < ts) lastTs.set(storyId, ts);
+    }
+  }
+  const out = new Map();
+  for (const id of started) {
+    if (ended.has(id)) continue;
+    const ts = lastTs.get(id);
+    if (ts) out.set(id, ts);
+  }
+  return out;
+}
+
+/**
+ * Deterministic branch-activity resolver (Story #3900). Returns the epoch-ms
+ * timestamp of the most recent commit on `story-<storyId>` via
+ * `git log -1 --format=%cI`, or `null` when the branch does not exist, has no
+ * commits, or git is unavailable.
+ *
+ * This is the secondary liveness signal the idle watchdog consults before
+ * flagging a Story as stalled: a healthy long-running Story routinely exceeds
+ * the heartbeat threshold during `implementing → closing` (heartbeats fire
+ * only at phase transitions), but its branch keeps gaining commits. A recent
+ * commit is hard, deterministic evidence of forward progress that does not
+ * depend on a heartbeat landing in the ledger. Pure-ish (shells out to git)
+ * and injectable so unit tests never spawn a subprocess.
+ *
+ * @param {number} storyId
+ * @param {{ cwd?: string, exec?: typeof execFileSync }} [deps]
+ * @returns {number|null} epoch-ms of the last commit, or null.
+ */
+export function branchLastCommitMs(storyId, deps = {}) {
+  const exec = deps.exec ?? execFileSync;
+  const cwd = deps.cwd ?? process.cwd();
+  try {
+    const out = exec(
+      'git',
+      ['log', '-1', '--format=%cI', `story-${storyId}`, '--'],
+      { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] },
+    ).trim();
+    if (!out) return null;
+    const ms = Date.parse(out);
+    return Number.isFinite(ms) ? ms : null;
+  } catch {
+    // Branch absent / git unavailable — no deterministic signal.
+    return null;
+  }
+}
+
+/**
+ * Build the wave-stall envelope. Pure helper — exported for unit tests.
+ *
+ * A Story whose latest ledger event is older than the threshold is *not*
+ * flagged as stalled when its `story-<id>` branch carries a commit newer
+ * than the threshold (Story #3900). Branch commits are deterministic
+ * forward-progress evidence that survives the heartbeat-cadence gap during
+ * `implementing → closing`, so consulting them eliminates the false-positive
+ * re-dispatch hazard (two agents on one branch) the watchdog otherwise
+ * manufactures for every healthy long-running Story.
+ *
+ * @param {object} args
+ * @param {number} args.epicId
+ * @param {number} args.thresholdMinutes
+ * @param {Map<number, string>} args.lastEvents `storyId → ISO-8601 ts`
+ *   from {@link readLedgerLastEvents}.
+ * @param {Date} args.now Reference clock for the staleness comparison.
+ * @param {(storyId: number) => (number|null)} [args.branchActivity]
+ *   Resolver for the last commit epoch-ms on `story-<id>`. Defaults to
+ *   {@link branchLastCommitMs}. Injected for tests.
+ * @returns {{
+ *   kind: 'wave-stall',
+ *   epicId: number,
+ *   thresholdMinutes: number,
+ *   checkedAt: string,
+ *   stalled: Array<{storyId: number, lastEventAt: string, idleMinutes: number}>,
+ *   inFlight: number[]
+ * }}
+ */
+export function buildWaveStallEnvelope({
+  epicId,
+  thresholdMinutes,
+  lastEvents,
+  now,
+  branchActivity = branchLastCommitMs,
+}) {
+  const checkedAt = now.toISOString();
+  const thresholdMs = thresholdMinutes * 60 * 1000;
+  const stalled = [];
+  const inFlight = [];
+  for (const [storyId, ts] of lastEvents) {
+    inFlight.push(storyId);
+    const eventMs = Date.parse(ts);
+    if (!Number.isFinite(eventMs)) continue;
+    const idleMs = now.getTime() - eventMs;
+    if (idleMs < thresholdMs) continue;
+
+    // Ledger says idle — consult the branch as a deterministic liveness
+    // signal before declaring a stall. A recent commit means the Story is
+    // making progress despite the heartbeat-cadence gap.
+    const commitMs = branchActivity(storyId);
+    if (
+      typeof commitMs === 'number' &&
+      Number.isFinite(commitMs) &&
+      now.getTime() - commitMs < thresholdMs
+    ) {
+      continue;
+    }
+
+    stalled.push({
+      storyId,
+      lastEventAt: ts,
+      idleMinutes: Math.floor(idleMs / 60000),
+    });
+  }
+  inFlight.sort((a, b) => a - b);
+  stalled.sort((a, b) => a.storyId - b.storyId);
+  return {
+    kind: 'wave-stall',
+    epicId,
+    thresholdMinutes,
+    checkedAt,
+    stalled,
+    inFlight,
+  };
+}
+
+/**
+ * Run the `--check-idle` path. Exported so unit tests can drive the
+ * branch without spawning the CLI subprocess.
+ *
+ * @param {object} args
+ * @param {number} args.epicId
+ * @param {number} args.thresholdMinutes
+ * @param {string} [args.ledgerPath] Override for tests; defaults to the
+ *   canonical `temp/epic-<id>/lifecycle.ndjson`.
+ * @param {Date} [args.now] Override for tests; defaults to wall clock.
+ * @param {object} [args.config] Optional resolved config for tempRoot.
+ * @param {(storyId: number) => (number|null)} [args.branchActivity]
+ *   Branch-liveness resolver; defaults to {@link branchLastCommitMs}.
+ *   Injected for tests so the watchdog never spawns git.
+ * @returns {{envelope: object, stalledCount: number}}
+ */
+export function runCheckIdle({
+  epicId,
+  thresholdMinutes,
+  ledgerPath,
+  now = new Date(),
+  config,
+  branchActivity = branchLastCommitMs,
+}) {
+  if (!Number.isInteger(epicId) || epicId <= 0) {
+    throw new TypeError('runCheckIdle: epicId must be a positive integer');
+  }
+  if (!Number.isInteger(thresholdMinutes) || thresholdMinutes <= 0) {
+    throw new TypeError(
+      'runCheckIdle: thresholdMinutes must be a positive integer',
+    );
+  }
+  const resolvedPath = ledgerPath ?? epicLedgerPath(epicId, config);
+  const lastEvents = readLedgerLastEvents(resolvedPath);
+  const envelope = buildWaveStallEnvelope({
+    epicId,
+    thresholdMinutes,
+    lastEvents,
+    now,
+    branchActivity,
+  });
+  return { envelope, stalledCount: envelope.stalled.length };
+}
+
+async function main(argv) {
+  const { values } = parseArgs({
+    args: argv,
+    options: {
+      epic: { type: 'string' },
+      'check-idle': { type: 'string' },
+      help: { type: 'boolean', short: 'h' },
+    },
+    strict: false,
+    allowPositionals: true,
+  });
+
+  if (values.help) {
+    process.stdout.write(`${HELP}\n`);
+    return;
+  }
+
+  const epicId = Number.parseInt(
+    String(values.epic ?? '').replace(/^#/, ''),
+    10,
+  );
+  if (!Number.isInteger(epicId) || epicId <= 0) {
+    Logger.error('wave-tick: --epic <id> is required (positive integer)');
+    process.exitCode = 2;
+    return;
+  }
+
+  if (values['check-idle'] !== undefined) {
+    const thresholdMinutes = Number.parseInt(String(values['check-idle']), 10);
+    if (!Number.isInteger(thresholdMinutes) || thresholdMinutes <= 0) {
+      Logger.error(
+        'wave-tick: --check-idle <minutes> must be a positive integer',
+      );
+      process.exitCode = 2;
+      return;
+    }
+    const { envelope, stalledCount } = runCheckIdle({
+      epicId,
+      thresholdMinutes,
+    });
+    process.stdout.write(`${JSON.stringify(envelope, null, 2)}\n`);
+    process.exitCode = stalledCount > 0 ? 1 : 0;
+    return;
+  }
+
+  const result = await runWaveTickCli({ epicId });
+  process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+}
+
+runAsCli(import.meta.url, () => main(process.argv.slice(2)), {
+  source: 'wave-tick',
+});