mandrel 1.57.0

package/.agents/scripts/generate-lifecycle-docs.js

@@ -0,0 +1,224 @@
+#!/usr/bin/env node
+/**
+ * .agents/scripts/generate-lifecycle-docs.js — Schema-backed lifecycle docs table
+ *
+ * Renders a bounded region inside `docs/LIFECYCLE.md` from every
+ * `.agents/schemas/lifecycle/*.schema.json`. The region is delimited by:
+ *
+ *     <!-- BEGIN GENERATED:lifecycle-events -->
+ *     ...generated table...
+ *     <!-- END GENERATED:lifecycle-events -->
+ *
+ * Columns: | Event | Schema | Description | Required fields |
+ *
+ *   - Event             = schema filename minus `.schema.json`
+ *   - Schema            = relative markdown link to the schema file
+ *   - Description       = the schema's top-level `description` property
+ *   - Required fields   = comma-joined list from the schema's `required` array
+ *                         (rendered as inline code; "—" when empty/absent)
+ *
+ * Skips `README.md`. The `ledger-record.schema.json` file is a record
+ * envelope rather than a lifecycle event, but to keep this generator
+ * literal-schema driven we still emit a row for it — the surrounding doc
+ * already calls out the distinction.
+ *
+ * Modes:
+ *   (default)  — rewrites the bounded region in place.
+ *   --check    — exits 0 when the on-disk region matches the freshly
+ *                generated content, exits 1 with a diff hint otherwise.
+ *
+ * Per `.agents/rules/orchestration-error-handling.md`, unrecoverable
+ * failures surface via `throw new Error(...)` so `runAsCli` can map the
+ * throw to `process.exit(1)` deterministically (no `Logger.fatal`).
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseArgs } from 'node:util';
+import { runAsCli } from './lib/cli-utils.js';
+import { Logger } from './lib/Logger.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const PROJECT_ROOT = path.resolve(__dirname, '..', '..');
+const SCHEMA_DIR = path.join(PROJECT_ROOT, '.agents', 'schemas', 'lifecycle');
+const DOC_PATH = path.join(PROJECT_ROOT, 'docs', 'LIFECYCLE.md');
+const REGION_BEGIN = '<!-- BEGIN GENERATED:lifecycle-events -->';
+const REGION_END = '<!-- END GENERATED:lifecycle-events -->';
+
+/**
+ * Read and parse every `*.schema.json` under the lifecycle schema dir, in
+ * ASCII-sorted filename order. The sort is intentional — it produces a
+ * stable diff regardless of the host filesystem's enumeration order, which
+ * is what makes `--check` reliable across platforms.
+ *
+ * @param {string} dir Absolute path to the schema directory.
+ * @returns {Array<{event:string, file:string, description:string, required:string[]}>}
+ */
+function readLifecycleSchemas(dir) {
+  if (!fs.existsSync(dir)) {
+    throw new Error(`Lifecycle schema directory not found: ${dir}`);
+  }
+  const entries = fs
+    .readdirSync(dir)
+    .filter((name) => name.endsWith('.schema.json'))
+    .sort();
+  if (entries.length === 0) {
+    throw new Error(`No *.schema.json files found in ${dir}`);
+  }
+  return entries.map((file) => {
+    const abs = path.join(dir, file);
+    const raw = fs.readFileSync(abs, 'utf8');
+    let json;
+    try {
+      json = JSON.parse(raw);
+    } catch (err) {
+      throw new Error(`Failed to parse JSON schema ${file}: ${err.message}`);
+    }
+    const event = file.replace(/\.schema\.json$/, '');
+    const description =
+      typeof json.description === 'string' && json.description.trim().length > 0
+        ? json.description.trim()
+        : '';
+    const required = Array.isArray(json.required) ? [...json.required] : [];
+    return { event, file, description, required };
+  });
+}
+
+/**
+ * Escape pipe characters so they survive Markdown table cell parsing.
+ *
+ * @param {string} text
+ * @returns {string}
+ */
+function escapeCell(text) {
+  return text.replace(/\|/g, '\\|');
+}
+
+/**
+ * Render the bounded-region body (the generated content between the two
+ * comment markers, exclusive of the markers themselves).
+ *
+ * @param {ReturnType<typeof readLifecycleSchemas>} rows
+ * @returns {string}
+ */
+function renderTable(rows) {
+  const header = '| Event | Schema | Description | Required fields |';
+  const sep = '| --- | --- | --- | --- |';
+  const body = rows.map((row) => {
+    const eventCell = `\`${row.event}\``;
+    const schemaLink = `[\`${row.file}\`](../.agents/schemas/lifecycle/${row.file})`;
+    const description = escapeCell(row.description || '—');
+    const requiredCell =
+      row.required.length === 0
+        ? '—'
+        : row.required.map((field) => `\`${field}\``).join(', ');
+    return `| ${eventCell} | ${schemaLink} | ${description} | ${requiredCell} |`;
+  });
+  // Surround with blank lines so the markers + table read as a separate block.
+  return ['', header, sep, ...body, ''].join('\n');
+}
+
+/**
+ * Substitute the bounded region inside `original`. Throws if either marker
+ * is missing, or if `BEGIN` appears after `END`. Idempotent — a re-run on
+ * the same input yields byte-identical output.
+ *
+ * @param {string} original
+ * @param {string} body Region body, already including leading/trailing blank
+ *                      lines (as produced by `renderTable`).
+ * @returns {string}
+ */
+function spliceRegion(original, body) {
+  const beginIdx = original.indexOf(REGION_BEGIN);
+  const endIdx = original.indexOf(REGION_END);
+  if (beginIdx === -1) {
+    throw new Error(
+      `Missing region marker "${REGION_BEGIN}" in ${DOC_PATH}. ` +
+        'Insert the marker pair before re-running the generator.',
+    );
+  }
+  if (endIdx === -1) {
+    throw new Error(
+      `Missing region marker "${REGION_END}" in ${DOC_PATH}. ` +
+        'Insert the marker pair before re-running the generator.',
+    );
+  }
+  if (endIdx < beginIdx) {
+    throw new Error(
+      `Region markers out of order in ${DOC_PATH}: END appears before BEGIN.`,
+    );
+  }
+  const before = original.slice(0, beginIdx + REGION_BEGIN.length);
+  const after = original.slice(endIdx);
+  return `${before}\n${body}\n${after}`;
+}
+
+/**
+ * Build the canonical post-generation file content for `docs/LIFECYCLE.md`.
+ *
+ * @param {string} schemaDir
+ * @param {string} docPath
+ * @returns {{ generated: string, original: string }}
+ */
+function buildExpected(schemaDir, docPath) {
+  if (!fs.existsSync(docPath)) {
+    throw new Error(`Target doc not found: ${docPath}`);
+  }
+  const original = fs.readFileSync(docPath, 'utf8');
+  const rows = readLifecycleSchemas(schemaDir);
+  const body = renderTable(rows);
+  const generated = spliceRegion(original, body);
+  return { generated, original };
+}
+
+/**
+ * @param {string[]} argv
+ */
+async function main(argv = process.argv.slice(2)) {
+  const { values } = parseArgs({
+    args: argv,
+    options: {
+      check: { type: 'boolean', default: false },
+    },
+    allowPositionals: false,
+  });
+
+  const { generated, original } = buildExpected(SCHEMA_DIR, DOC_PATH);
+
+  if (values.check) {
+    if (generated === original) {
+      Logger.info(
+        `generate-lifecycle-docs: ${path.relative(PROJECT_ROOT, DOC_PATH)} is up to date.`,
+      );
+      return;
+    }
+    const hint =
+      `${path.relative(PROJECT_ROOT, DOC_PATH)} is out of date. ` +
+      'Run `node .agents/scripts/generate-lifecycle-docs.js` to regenerate the bounded region.';
+    throw new Error(hint);
+  }
+
+  if (generated === original) {
+    Logger.info(
+      `generate-lifecycle-docs: ${path.relative(PROJECT_ROOT, DOC_PATH)} already current — no write.`,
+    );
+    return;
+  }
+  fs.writeFileSync(DOC_PATH, generated, 'utf8');
+  Logger.info(
+    `generate-lifecycle-docs: wrote bounded region into ${path.relative(PROJECT_ROOT, DOC_PATH)}.`,
+  );
+}
+
+export {
+  buildExpected,
+  REGION_BEGIN,
+  REGION_END,
+  readLifecycleSchemas,
+  renderTable,
+  spliceRegion,
+};
+
+runAsCli(import.meta.url, main, { source: 'generate-lifecycle-docs' });

package/.agents/scripts/generate-skills-index.js

@@ -0,0 +1,252 @@
+#!/usr/bin/env node
+// .agents/scripts/generate-skills-index.js
+//
+// Walk `.agents/skills/{core,stack}/**/SKILL.md` via the shared parser
+// helper, project each parsed result into an index entry, and write the
+// aggregated manifest to `.agents/skills/skills.index.json`. Supports a
+// `--check` mode that compares the on-disk manifest against fresh
+// generator output (ignoring the volatile `generatedAt` field) and exits
+// non-zero with a diff-style message if they diverge.
+//
+// CLI surface:
+//
+//   node generate-skills-index.js [--check] [--root <dir>] [--out <file>]
+//
+//   --check        Read the on-disk manifest, compare to generator output
+//                  modulo `generatedAt`. Exit 0 on match, non-zero on
+//                  drift. Does not write.
+//   --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.
+//   --out <file>   Override the manifest output path (defaults to
+//                  `<root>/.agents/skills/skills.index.json`).
+//
+// Honors AGENT_LOG_LEVEL via the shared `Logger`. Stdout is reserved for
+// the diff text in --check failure mode; informational progress goes to
+// stderr.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+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 GENERATOR_ID = 'generate-skills-index.js@1';
+
+/**
+ * Resolve the default repo root: the directory two levels up from this
+ * script (i.e. `<repo>/.agents/scripts/generate-skills-index.js` →
+ * `<repo>`).
+ */
+function defaultRepoRoot() {
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  return path.resolve(here, '..', '..');
+}
+
+/**
+ * Parse CLI flags. Returns `{ check, root, out }`. Unknown flags trigger
+ * a thrown Error (from the shared parser) so the runAsCli boundary can
+ * surface a clean message.
+ */
+export function parseArgs(argv) {
+  if (argv.some((t) => t === '--help' || t === '-h')) {
+    return { check: false, root: null, out: null, help: true };
+  }
+  const { values } = parseStandardCliArgs({
+    argv,
+    extras: {
+      check: { type: 'boolean' },
+      root: { type: 'string' },
+      out: { type: 'string' },
+    },
+  });
+  return { check: values.check, root: values.root, out: values.out };
+}
+
+/**
+ * Project a parseSkill result into an index entry shaped by
+ * `.agents/schemas/skills-index.schema.json`.
+ *
+ * Post-Wave-2 every SKILL.md carries a 5–12-bullet Policy Capsule.
+ * `policyCapsuleBullets` records that count for the manifest entry.
+ * A value of `0` means the parser did not find the capsule section and
+ * is a validator-rejected condition (see validate-skills.js).
+ */
+function projectEntry(parsed) {
+  return {
+    name: parsed.name,
+    tier: parsed.tier,
+    category: parsed.category,
+    path: parsed.path,
+    description: parsed.frontmatter.description,
+    policyCapsuleBullets: parsed.policyCapsule.bulletCount,
+    allowedTools: Array.isArray(parsed.frontmatter.allowed_tools)
+      ? [...parsed.frontmatter.allowed_tools]
+      : null,
+    vendor:
+      typeof parsed.frontmatter.vendor === 'string'
+        ? parsed.frontmatter.vendor
+        : null,
+  };
+}
+
+/**
+ * Build the manifest object (without `generatedAt`) by walking the tree
+ * and projecting each parsed SKILL.md into an index entry.
+ */
+export function buildManifestBody(repoRoot) {
+  const skillFiles = collectSkillFiles(repoRoot);
+  const skills = skillFiles.map((absPath) =>
+    projectEntry(parseSkill(absPath, { repoRoot })),
+  );
+  return {
+    generator: GENERATOR_ID,
+    skills,
+  };
+}
+
+/**
+ * Build the full manifest with `generatedAt`. `nowIso` is injected so
+ * tests can pin the timestamp deterministically.
+ */
+export function buildManifest(repoRoot, { nowIso } = {}) {
+  const body = buildManifestBody(repoRoot);
+  return {
+    generatedAt: nowIso ?? new Date().toISOString(),
+    generator: body.generator,
+    skills: body.skills,
+  };
+}
+
+/**
+ * Serialize a manifest object as canonical JSON: 2-space indent,
+ * trailing newline. Two runs against an unchanged corpus produce
+ * byte-identical output modulo `generatedAt`.
+ */
+export function serializeManifest(manifest) {
+  return `${JSON.stringify(manifest, null, 2)}\n`;
+}
+
+/**
+ * Read the on-disk manifest as a parsed object, or null when missing /
+ * unparseable. The --check pipeline distinguishes "missing" (drift) from
+ * "unparseable" (drift) via the returned `reason` channel.
+ */
+function readOnDiskManifest(outPath) {
+  if (!fs.existsSync(outPath)) {
+    return { manifest: null, reason: 'missing' };
+  }
+  let src;
+  try {
+    src = fs.readFileSync(outPath, 'utf8');
+  } catch (err) {
+    return { manifest: null, reason: `read-error: ${err.message}` };
+  }
+  try {
+    return { manifest: JSON.parse(src), reason: null };
+  } catch (err) {
+    return { manifest: null, reason: `parse-error: ${err.message}` };
+  }
+}
+
+/**
+ * Compare two manifests ignoring `generatedAt`. Returns null when they
+ * match, or a short diff-style message when they diverge.
+ */
+function diffManifestsIgnoringTimestamp(diskManifest, freshManifest) {
+  if (diskManifest === null) {
+    return 'on-disk manifest is missing or unreadable';
+  }
+  const a = { ...diskManifest };
+  const b = { ...freshManifest };
+  delete a.generatedAt;
+  delete b.generatedAt;
+  const sa = JSON.stringify(a);
+  const sb = JSON.stringify(b);
+  if (sa === sb) return null;
+  // Surface a structural summary rather than a full JSON dump.
+  const diskCount = Array.isArray(diskManifest.skills)
+    ? diskManifest.skills.length
+    : 'n/a';
+  const freshCount = Array.isArray(freshManifest.skills)
+    ? freshManifest.skills.length
+    : 'n/a';
+  const summary = [
+    'skills.index.json drift detected:',
+    `  on-disk entries:  ${diskCount}`,
+    `  generated entries: ${freshCount}`,
+    "  run 'node .agents/scripts/generate-skills-index.js' to refresh",
+  ].join('\n');
+  return summary;
+}
+
+/**
+ * Resolve the manifest output path given (root, optional explicit
+ * override).
+ */
+function resolveOutPath(root, override) {
+  return override
+    ? path.resolve(override)
+    : path.join(root, '.agents', 'skills', 'skills.index.json');
+}
+
+/**
+ * Pure entry point used by tests. Returns `{ status, output }` where
+ * `output` is a stdout string to print (may be empty) and `status` is
+ * the exit code.
+ */
+export function run({ argv = [], now = new Date(), repoRoot } = {}) {
+  const parsed = parseArgs(argv);
+  if (parsed.help) {
+    return {
+      status: 0,
+      output: [
+        'Usage: generate-skills-index.js [--check] [--root <dir>] [--out <file>]',
+      ].join('\n'),
+    };
+  }
+  const root = parsed.root
+    ? path.resolve(parsed.root)
+    : (repoRoot ?? defaultRepoRoot());
+  const outPath = resolveOutPath(root, parsed.out);
+  const fresh = buildManifest(root, { nowIso: now.toISOString() });
+
+  if (parsed.check) {
+    const { manifest: disk, reason } = readOnDiskManifest(outPath);
+    if (disk === null) {
+      return {
+        status: 1,
+        output: `skills.index.json drift detected: ${reason}`,
+      };
+    }
+    const diff = diffManifestsIgnoringTimestamp(disk, fresh);
+    if (diff === null) {
+      Logger.info(
+        `skills.index.json is fresh (${fresh.skills.length} entries)`,
+      );
+      return { status: 0, output: '' };
+    }
+    return { status: 1, output: diff };
+  }
+
+  const serialized = serializeManifest(fresh);
+  fs.mkdirSync(path.dirname(outPath), { recursive: true });
+  fs.writeFileSync(outPath, serialized);
+  Logger.info(
+    `wrote ${path.relative(root, outPath).split(path.sep).join('/')} (${fresh.skills.length} entries)`,
+  );
+  return { status: 0, output: '' };
+}
+
+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: 'generate-skills-index' });

package/.agents/scripts/generate-workflows-doc.js

@@ -0,0 +1,168 @@
+#!/usr/bin/env node
+/**
+ * .agents/scripts/generate-workflows-doc.js — Catalog-backed workflows index
+ *
+ * Renders the consumer-shipped slash-command catalog at
+ * `.agents/docs/workflows.md` from the on-disk workflow set under
+ * `.agents/workflows/*.md` (top-level only — `helpers/` are path-included
+ * modules, not runnable slash commands). The catalog logic is shared with
+ * the in-process backend in `lib/mandrel-catalog.js`, so the generated doc
+ * and any programmatic catalog reader never drift from one another.
+ *
+ * Why generated (Story #3708): `workflows.md` used to be hand-maintained and
+ * was *not* drift-gated, so it could silently fall out of sync with the
+ * actual workflow set. The retired `/mandrel` discoverability command was
+ * always accurate because it rendered the catalog live. Rather than keep the
+ * drift-prone hand-authored doc and the accurate-but-ephemeral command, this
+ * generator makes the doc itself a rendering of the same catalog, gates it via
+ * `--check`, and ships it to consumers under `.agents/docs/`.
+ *
+ * Modes:
+ *   (default)  — rewrites `.agents/docs/workflows.md` in full from the
+ *                current workflow set.
+ *   --check    — exits 0 when the on-disk file matches the freshly generated
+ *                content, throws (→ exit 1) with a regeneration hint otherwise.
+ *
+ * Per `.agents/rules/orchestration-error-handling.md`, unrecoverable failures
+ * surface via `throw new Error(...)` so `runAsCli` maps the throw to
+ * `process.exit(1)` deterministically (no `Logger.fatal`).
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseArgs } from 'node:util';
+import { runAsCli } from './lib/cli-utils.js';
+import { Logger } from './lib/Logger.js';
+import { buildCatalog } from './lib/mandrel-catalog.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const PROJECT_ROOT = path.resolve(__dirname, '..', '..');
+const WORKFLOWS_DIR = path.join(PROJECT_ROOT, '.agents', 'workflows');
+const DOC_PATH = path.join(PROJECT_ROOT, '.agents', 'docs', 'workflows.md');
+
+/**
+ * Collapse a catalog description to a single Markdown table-cell-safe line.
+ * The catalog already normalizes whitespace; this neutralizes:
+ *   - pipe characters (`|`) so a description can never break the table grid;
+ *   - stray newlines;
+ *   - bare emphasis markers (`*`, `_`) so a glob like `audit-*` in a
+ *     description is rendered literally instead of being parsed as emphasis
+ *     (which trips markdownlint MD037 in the generated doc).
+ *
+ * Framework workflow descriptions do not embed `*`/`_` inside inline code
+ * spans, so a global escape is safe and keeps the generator pure.
+ *
+ * @param {string | null} description
+ * @returns {string}
+ */
+function cellEscape(description) {
+  if (!description) return '_(no description)_';
+  return String(description)
+    .replace(/\r?\n/g, ' ')
+    .replace(/\|/g, '\\|')
+    .replace(/([*_])/g, '\\$1');
+}
+
+/**
+ * Render the full generated `workflows.md` content from a catalog.
+ *
+ * @param {Array<{ name: string, description: string | null, vague: boolean }>} catalog
+ * @returns {string}
+ */
+export function renderWorkflowsDoc(catalog) {
+  const lines = [
+    '<!--',
+    '  GENERATED FILE — do not edit by hand.',
+    '  Source of truth: `.agents/workflows/*.md` front-matter `description:`.',
+    '  Regenerate with: node .agents/scripts/generate-workflows-doc.js',
+    '  Drift is gated by `npm run docs:check`.',
+    '-->',
+    '',
+    '# Workflow (Slash-Command) Reference Index',
+    '',
+    'This is an **auto-generated reference index** of every slash command shipped',
+    'under `.agents/workflows/` (top-level only — `helpers/` are path-included',
+    'modules, not runnable commands). The canonical workflow narrative lives in',
+    '[`SDLC.md`](SDLC.md) — read that first to understand how the commands',
+    'compose. This file is only for "which command does X?" lookups.',
+    '',
+    'Every command file lives at `.agents/workflows/<name>.md` and is projected',
+    'into a flat `.claude/commands/` tree by `npm run sync:commands` (the',
+    'UserPromptSubmit hook keeps it current) so it shows up as a bare `/<name>`',
+    'slash command (e.g. `/epic-deliver`). The projection writes only',
+    '`.claude/commands/<name>.md` — there is no plugin manifest and no',
+    'marketplace listing. The commands load in every Claude Code environment.',
+    '',
+    'This index is regenerated from each workflow’s front-matter `description:`',
+    'by `node .agents/scripts/generate-workflows-doc.js`; `npm run docs:check`',
+    'fails when it drifts from the on-disk workflow set. To change a command’s',
+    'description, edit the workflow file’s front-matter and regenerate.',
+    '',
+    `## Commands (${catalog.length})`,
+    '',
+    '| Command | Description |',
+    '| --- | --- |',
+  ];
+
+  for (const entry of catalog) {
+    lines.push(`| \`/${entry.name}\` | ${cellEscape(entry.description)} |`);
+  }
+
+  lines.push('');
+  return lines.join('\n');
+}
+
+/**
+ * Build the canonical generated content and read the on-disk file (if any).
+ *
+ * @returns {{ generated: string, original: string | null }}
+ */
+export function buildExpected() {
+  const catalog = buildCatalog(WORKFLOWS_DIR);
+  const generated = renderWorkflowsDoc(catalog);
+  const original = fs.existsSync(DOC_PATH)
+    ? fs.readFileSync(DOC_PATH, 'utf8')
+    : null;
+  return { generated, original };
+}
+
+/**
+ * @param {string[]} argv
+ */
+async function main(argv = process.argv.slice(2)) {
+  const { values } = parseArgs({
+    args: argv,
+    options: {
+      check: { type: 'boolean', default: false },
+    },
+    allowPositionals: false,
+  });
+
+  const { generated, original } = buildExpected();
+  const rel = path.relative(PROJECT_ROOT, DOC_PATH).split(path.sep).join('/');
+
+  if (values.check) {
+    if (original === generated) {
+      Logger.info(`generate-workflows-doc: ${rel} is up to date.`);
+      return;
+    }
+    throw new Error(
+      `${rel} is out of date. ` +
+        'Run `node .agents/scripts/generate-workflows-doc.js` to regenerate it.',
+    );
+  }
+
+  if (original === generated) {
+    Logger.info(`generate-workflows-doc: ${rel} already current — no write.`);
+    return;
+  }
+  fs.mkdirSync(path.dirname(DOC_PATH), { recursive: true });
+  fs.writeFileSync(DOC_PATH, generated, 'utf8');
+  Logger.info(`generate-workflows-doc: wrote ${rel}.`);
+}
+
+export { DOC_PATH, WORKFLOWS_DIR };
+
+runAsCli(import.meta.url, main, { source: 'generate-workflows-doc' });