mandrel 2.60.0 → 2.62.0

package/.agents/scripts/generate-lens-checklists.js

@@ -1,34 +1,9 @@
 #!/usr/bin/env node
 /**
- * .agents/scripts/generate-lens-checklists.js — per-lens authoring checklists
- *
- * Distils each canonical audit lens's own `.agents/workflows/audit-<lens>.md`
- * workflow body into one compact authoring checklist under
- * `.agents/audit-checklists/<lens>.md`. The distillation logic is the pure
- * `lib/audit-suite/lens-checklist.js` seam; this entry point owns only the
- * file read/write/prune and the `--check` drift gate.
- *
- * Why (Epic #4405 — shift-left audit): the audit lenses used to surface their
- * concerns only when `/audit-<lens>` ran. These checklists move the concerns to
- * the innermost, write-time tier as committed build artifacts, gated for
- * staleness by `npm run docs:check` exactly like every other generated doc so
- * they can never silently drift from their source workflow.
- *
- * The lens taxonomy is the SSOT `AUDIT_LENSES` list. A lens whose
- * `audit-<lens>.md` workflow is absent produces **no** checklist and is
- * reported (never a silent skip). Stray `.md` files under the checklist
- * directory that no longer map to a lens are pruned in write mode and flagged
- * in `--check` mode, keeping the directory a pure function of its sources.
- *
- * Modes:
- *   (default)  — writes one `<lens>.md` per lens with a workflow, prunes
- *                strays, reports lenses missing a workflow.
- *   --check    — exits 0 when every on-disk file matches the freshly generated
- *                content and no strays exist, throws (→ exit 1) 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`).
+ * Distils each `audit-<lens>.md` workflow into a committed write-time
+ * checklist under `.agents/audit-checklists/`. The directory is a pure
+ * function of its sources: strays are pruned (flagged under `--check`), and a
+ * lens with no workflow is reported, never silently skipped.
  */
 
 import fs from 'node:fs';
@@ -47,12 +22,7 @@ const WORKFLOWS_DIR = path.join(PROJECT_ROOT, '.agents', 'workflows');
 const CHECKLISTS_DIR = path.join(PROJECT_ROOT, '.agents', 'audit-checklists');
 
 /**
- * Pure: plan the expected checklist set from the lens taxonomy, given a
- * workflow-existence predicate and a reader. A lens whose workflow is absent
- * yields no checklist and is recorded in `missing` (never silently skipped).
- * Kept side-effect-free so it is unit-testable with fabricated inputs.
- *
- * @param {ReadonlyArray<string>} lenses — canonical lens names.
+ * @param {ReadonlyArray<string>} lenses
  * @param {(lens: string) => boolean} workflowExists
  * @param {(lens: string) => string} readWorkflow
  * @returns {{ expected: Map<string, string>, missing: string[] }}
@@ -71,17 +41,11 @@ export function planChecklists(lenses, workflowExists, readWorkflow) {
 }
 
 /**
- * Build the full expected checklist set from the lens taxonomy and the on-disk
- * workflow bodies, plus the strays (on-disk checklist files mapping to no
- * current lens).
- *
  * @returns {{
  *   expected: Map<string, string>,
  *   missing: string[],
  *   strays: string[],
- * }} `expected` maps a checklist basename (`<lens>.md`) to its generated
- *   content; `missing` lists lenses with no `audit-<lens>.md`; `strays` lists
- *   on-disk checklist basenames that map to no current lens.
+ * }}
  */
 export function buildExpected({
   fsImpl = fs,
@@ -105,10 +69,10 @@ export function buildExpected({
 }
 
 /**
- * @param {string} basename — e.g. `security.md`
+ * @param {string} basename
  * @param {string} [checklistsDir]
  * @param {string} [projectRoot]
- * @returns {string} repo-relative POSIX path for messages.
+ * @returns {string}
  */
 function relChecklist(
   basename,
@@ -122,14 +86,6 @@ function relChecklist(
 }
 
 /**
- * The generator core, extracted from the CLI shell so both modes — the
- * `--check` drift gate and the write/prune pass — are reachable without
- * touching the real `.agents/audit-checklists` tree.
- *
- * Every seam on the optional final `deps` parameter defaults to the real
- * implementation (`.agents/rules/test-seams.md` rules 1-2, 4), so `main` and
- * `npm run docs:check` are unchanged.
- *
  * @param {string[]} [argv]
  * @param {{
  *   fsImpl?: typeof fs,

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

@@ -1,43 +1,10 @@
 #!/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.
-//
-// Two indexes, never one (Story #5135). The shipped manifest above is a
-// committed payload file that `mandrel doctor` / `mandrel sync-agents`
-// compare byte-for-byte against the installed package, so consumer-authored
-// skills under the `.agents/local/skills/` zone MUST NOT be folded into it —
-// a merged index would read as payload drift in every consumer that authored
-// a skill, and those commands would refuse. Local skills are therefore
-// indexed into their own `.agents/local/skills/skills.index.json`, inside
-// the zone sync never prunes and drift never walks.
-//
-// 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`).
-//
-// Written output is passed through the project formatter (Biome) so that
-// regenerating on a clean tree leaves no format drift behind; the step is
-// best-effort and degrades to plain `JSON.stringify` output where Biome is
-// not installed. See `lib/format-generated-json.js`.
-//
-// Honors AGENT_LOG_LEVEL via the shared `Logger`. Stdout is reserved for
-// the diff text in --check failure mode; informational progress goes to
-// stderr.
+// Writes `.agents/skills/skills.index.json` from every payload SKILL.md;
+// `--check` compares modulo `generatedAt`. Consumer skills under
+// `.agents/local/skills/` get their own index and must never be merged into
+// the payload one: doctor/sync-agents compare it byte-for-byte against the
+// package and would read a merged index as drift. Stdout is reserved for the
+// `--check` diff; progress goes to stderr.
 
 import fs from 'node:fs';
 import path from 'node:path';
@@ -72,11 +39,7 @@ function defaultRepoRoot() {
   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.
- */
+/** Unknown flags throw, for runAsCli to surface. */
 export function parseArgs(argv) {
   if (argv.some((t) => t === '--help' || t === '-h')) {
     return { check: false, root: null, out: null, help: true };
@@ -92,15 +55,7 @@ export function parseArgs(argv) {
   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).
- */
+/** `policyCapsuleBullets: 0` means no capsule was found (validator-rejected). */
 function projectEntry(parsed) {
   return {
     name: parsed.name,
@@ -119,10 +74,6 @@ function projectEntry(parsed) {
   };
 }
 
-/**
- * Build the manifest object (without `generatedAt`) by walking the tree
- * and projecting each parsed SKILL.md into an index entry.
- */
 export function buildManifestBody(repoRoot, collect = collectSkillFiles) {
   const skillFiles = collect(repoRoot);
   const skills = skillFiles.map((absPath) =>
@@ -134,10 +85,6 @@ export function buildManifestBody(repoRoot, collect = collectSkillFiles) {
   };
 }
 
-/**
- * Build the full manifest with `generatedAt`. `nowIso` is injected so
- * tests can pin the timestamp deterministically.
- */
 export function buildManifest(repoRoot, { nowIso, collect } = {}) {
   const body = buildManifestBody(repoRoot, collect);
   return {
@@ -148,44 +95,24 @@ export function buildManifest(repoRoot, { nowIso, collect } = {}) {
 }
 
 /**
- * Serialize a manifest object as canonical JSON: 2-space indent,
- * trailing newline. Two runs against an unchanged corpus produce
- * byte-identical output modulo `generatedAt`.
- *
- * This is the *pre-format* shape. `JSON.stringify` expands every array
- * across multiple lines, while Biome collapses short ones that fit
- * inside `lineWidth` (`"allowedTools": ["Read", "Bash"]`). Writing this
- * text verbatim therefore leaves the tree format-dirty on every run —
- * see `lib/format-generated-json.js`, which reconciles the two.
+ * Pre-format shape: Biome collapses short arrays this expands, so writes go
+ * through `formatGeneratedJson` or the tree is format-dirty on every run.
  */
 export function serializeManifest(manifest) {
   return `${JSON.stringify(manifest, null, 2)}\n`;
 }
 
-/**
- * Resolve the manifest output path given (root, optional explicit
- * override).
- */
 function resolveOutPath(root, override) {
   return override
     ? path.resolve(override)
     : indexPathFor(root, PAYLOAD_SKILLS_SEGMENTS);
 }
 
-/**
- * Resolve the local-zone manifest path. Deliberately NOT overridable by
- * `--out`: that flag redirects the payload manifest (tests stage fixture
- * trees with it), and letting it also move the local manifest would let one
- * invocation write both indexes to the same file.
- */
+/** Not overridable by `--out`, or one run could write both indexes to one file. */
 function resolveLocalOutPath(root) {
   return indexPathFor(root, LOCAL_SKILLS_SEGMENTS);
 }
 
-/**
- * Write one manifest through the project formatter so a regeneration on a
- * clean tree leaves no format drift behind.
- */
 function writeManifest(manifest, outPath, root) {
   const serialized = serializeManifest(manifest);
   const opts = { cwd: root, filename: INDEX_FILENAME };
@@ -196,12 +123,7 @@ function writeManifest(manifest, outPath, root) {
   );
 }
 
-/**
- * Write (or reap) the local-zone manifest. A consumer who deletes their last
- * local skill would otherwise be left with a stale index reporting skills
- * that no longer exist, so an emptied zone removes the artifact rather than
- * leaving it behind.
- */
+/** An emptied local zone removes its index rather than leave a stale one. */
 function writeLocalManifest(localFresh, localOutPath, root) {
   const rel = path.relative(root, localOutPath).split(path.sep).join('/');
   if (localFresh === null) {
@@ -215,11 +137,6 @@ function writeLocalManifest(localFresh, localOutPath, root) {
   Logger.info(`wrote ${rel} (${localFresh.skills.length} entries)`);
 }
 
-/**
- * Compare the local-zone manifest against fresh generator output. Returns
- * null when in sync (including the common case of no local skills and no
- * artifact), or a diff-style message.
- */
 function checkLocalManifest(localFresh, localOutPath) {
   const exists = fs.existsSync(localOutPath);
   if (localFresh === null) {
@@ -240,13 +157,7 @@ function checkLocalManifest(localFresh, localOutPath) {
 }
 
 /**
- * Build the local zone's manifest plan for this invocation: its output path,
- * and a fresh manifest when the consumer has authored any local skill (null
- * otherwise, which is the signal to reap a stale artifact).
- *
- * Split out of `run` so the payload path and the local path each read as one
- * step there rather than interleaving.
- *
+ * A null `localFresh` signals reaping a stale artifact.
  * @param {string} root
  * @param {Date} now
  * @returns {{ localFresh: object | null, localOutPath: string }}
@@ -264,9 +175,6 @@ function buildLocalPlan(root, now) {
 }
 
 /**
- * Render the freshness line's entry counts, naming the local zone only when
- * one exists.
- *
  * @param {object} fresh
  * @param {object | null} localFresh
  * @returns {string}
@@ -279,13 +187,7 @@ function describeCounts(fresh, localFresh) {
 }
 
 /**
- * `--check` mode: compare both manifests against fresh generator output and
- * report the first drift found, payload first.
- *
- * Lives outside `run` so the entry point reads as "resolve inputs, then check
- * or write" — and so the check path's branches are not charged to a function
- * that also owns argument resolution.
- *
+ * Reports the first drift found, payload first.
  * @param {{ outPath: string, fresh: object, localOutPath: string, localFresh: object | null }} plan
  * @returns {{ status: number, output: string }}
  */

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

@@ -1,33 +1,8 @@
 #!/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.
- *   --root     — read and write under another checkout's `.agents/` tree.
- *                See {@link resolveTargets} for why this seam exists.
- *
- * 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`).
+ * Renders `.agents/docs/workflows.md` from the top-level workflow set via the
+ * shared `lib/mandrel-catalog.js`, so the doc and programmatic readers cannot
+ * drift; `--check` gates it.
  */
 
 import fs from 'node:fs';
@@ -43,28 +18,9 @@ const __dirname = path.dirname(__filename);
 const PROJECT_ROOT = path.resolve(__dirname, '..', '..');
 
 /**
- * Resolve the workflow source directory and the generated doc for one
- * repository root.
- *
- * The `--root` seam this backs exists for the drift gate's own test. That
- * test used to prove the gate by editing the *real*
- * `.agents/workflows/mandrel-deliver.md`, running `--check`, and restoring
- * the file in `afterEach`. The proof was sound; the blast radius was not.
- * `node --test` runs test files in parallel against one shared checkout, so
- * for the ~1s the real file sat mutated, every other test file observed a
- * dirty tree — and `tests/enforcement/workflow-script-help.test.js`, whose
- * final assertion is a repo-wide `git status --porcelain`, reported it as
- * "`--help` mutated the working tree" on the Windows Smoke job, where the
- * wider process-spawn cost stretches that window far enough to collide.
- *
- * A generator that can only ever be pointed at its own checkout forces that
- * choice. Pointing it at a fixture root removes it.
- *
- * The `--root` default is applied here rather than at the call site so the
- * one branch it costs lives with the resolution it belongs to.
- *
- * @param {string} [root] Repository root to render against; defaults to this
- *   checkout. A relative path is resolved against the process cwd.
+ * The `--root` seam lets the drift gate's test use a fixture root: mutating
+ * the real workflow file dirties the shared checkout for parallel test files.
+ * @param {string} [root]
  * @returns {{ root: string, workflowsDir: string, docPath: string }}
  */
 export function resolveTargets(root) {
@@ -76,21 +32,11 @@ export function resolveTargets(root) {
   };
 }
 
-/** This checkout's own targets — the default when `--root` is absent. */
 const { workflowsDir: WORKFLOWS_DIR, docPath: DOC_PATH } = resolveTargets();
 
 /**
- * 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.
- *
+ * Escapes `*`/`_` so a glob like `audit-*` is not parsed as emphasis (MD037);
+ * safe globally because descriptions put neither inside code spans.
  * @param {string | null} description
  * @returns {string}
  */
@@ -103,9 +49,6 @@ function cellEscape(description) {
 }
 
 /**
- * Render the full generated `workflows.md` content from the flat command
- * catalog and the loop-unit catalog.
- *
  * @param {Array<{ name: string, description: string | null, vague: boolean }>} catalog
  * @param {Array<{ name: string, description: string | null, vague: boolean }>} [loopCatalog]
  * @returns {string}
@@ -124,7 +67,7 @@ export function renderWorkflowsDoc(catalog, loopCatalog = []) {
     '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',
+    '[`SDLC.md`](https://github.com/dsj1984/mandrel/blob/main/docs/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',
@@ -184,10 +127,7 @@ export function renderWorkflowsDoc(catalog, loopCatalog = []) {
 }
 
 /**
- * Build the canonical generated content and read the on-disk file (if any).
- *
- * @param {string} [root] Repository root to render against; see
- *   {@link resolveTargets}.
+ * @param {string} [root]
  * @returns {{
  *   generated: string,
  *   original: string | null,

package/.agents/scripts/git-cleanup.js

@@ -2,41 +2,9 @@
 /* node:coverage ignore file -- multi-phase repo-cleanup CLI; thin shell over `git` + `gh` */
 
 /**
- * git-cleanup.js — Story #2466 thin CLI shell over the multi-phase
- * cleanup pipeline.
+ * Thin CLI shell over the `lib/orchestration/git-cleanup/phases/` pipeline.
  *
- * The pipeline lives under `lib/orchestration/git-cleanup/phases/`:
- *
- *   1. parse-args   — argv → normalized opts bag (`parseCleanupArgs`).
- *   2. filters      — pure glob + protected-branch helpers.
- *   3. git-probes   — every `gitSpawn` / `gh` subprocess wrapper plus
- *                     small parsers (`probeMergedPr`, etc).
- *   4. branches     — merged-branch reap (`planCleanup`,
- *                     `executeCleanup`).
- *   5. fast-forward — fast-forward-main phase.
- *   6. prune        — prune-remotes phase + `parsePrunedRefs`.
- *   7. stashes      — stash triage (`parseStashList`, `planStashes`,
- *                     `executeStashes`, `stashRefIndex`,
- *                     `buildAllowlistDecider`).
- *   8. render       — operator-facing renderers + `buildJsonEnvelope`,
- *                     `computeExitCode`.
- *   9. cli          — interactive prompts + per-phase drivers + `main`.
- *
- * Public CLI surface, named exports, and exit codes are byte-identical
- * to the pre-refactor implementation. See the original module docstring
- * (preserved below) for the operator-facing flag + phase contract.
- *
- * Phases (selectable, run sequentially when no narrowing flag set):
- *   1. fast-forward-main — `git fetch origin <base>` → `git merge --ff-only`.
- *   2. prune-remotes     — `git fetch --prune <remote>`.
- *   3. branches          — enumerate merged local branches via `gh pr list`
- *                          + `git branch --merged <base>` and reap.
- *   4. stashes           — `git stash list` → optional per-stash drops.
- *
- * Exit codes:
- *   0 — clean (dry-run preview, or every active phase succeeded).
- *   1 — at least one phase reported a failure.
- *   2 — every active phase produced nothing to do (informational).
+ * Exit codes: 0 clean or dry-run, 1 a phase failed, 2 nothing to do.
  */
 
 import { runAsCli } from './lib/cli-utils.js';