mandrel 2.60.0 → 2.61.0

package/.agents/scripts/ceremony-derive.js

@@ -1,41 +1,15 @@
 #!/usr/bin/env node
 
 /**
- * ceremony-derive.js — derive a Story's acceptance ceremony from ground truth
- * (Story #5313).
+ * ceremony-derive.js — derive a Story's acceptance ceremony from the branch,
+ * not from a hand-carried incantation: compute the `<base>...story-<id>`
+ * change set once, derive its level and sensitive classes, resolve the
+ * ceremony, print one JSON object.
  *
- * The deliver digest used to hand the worker a three-module import block to
- * paste into `node --input-type=module -e` — compute the change set, derive
- * the level, resolve the ceremony — and every hand-carried incantation is a
- * transcription risk (the object-vs-string `derivedLevel` slip alone routed a
- * whole class of Stories to the null fail-safe). This CLI is that block,
- * scripted: one invocation, one JSON object, computed from the branch rather
- * than recalled.
- *
- *   1. Compute the change set ONCE for `<base>...story-<id>`
- *      (`lib/orchestration/change-set.js`).
- *   2. Derive the change level and the sensitive-path classes from it
- *      (`lib/orchestration/review-depth.js#deriveChangeLevel`).
- *   3. Resolve the ceremony for the configured profile
- *      (`lib/orchestration/ceremony-routing.js#resolveCeremonyForRisk`).
- *
- * Stdout: a single JSON object —
- *   { storyId, baseRef, headRef, files, enumerated, level, classes, profile,
- *     mode, reason, verdictOwner }
- *
- * `files` is the one change set the verdict owner must be handed; the caller
- * never lets it re-enumerate the diff. `files: null` means the diff could not
- * be enumerated.
- *
- * `level` / `classes` are what **review depth** reads (`resolveDepth`), and a
- * sensitive class still resolves `deep`. They do not route the verdict owner:
- * `verdictOwner` follows the ceremony profile alone (Story #5343) —
- * `inline-self-eval` under `minimal` / `standard`, `fresh-critic` under
- * `strict` — and since Story #5366 the resolver does not even accept the
- * level, so the two signals cannot be confused for one decision.
- *
- * Exit codes: 0 on a derived decision (including the `null` fail-safe — an
- * unenumerable diff is a decision, not an error), 1 on a usage error.
+ * `files` is the one change set the verdict owner is handed (`null` = not
+ * enumerable). `level`/`classes` feed review depth only; `verdictOwner`
+ * follows the ceremony profile alone. Exit 0 on any derived decision,
+ * including the `null` fail-safe; 1 on a usage error.
  */
 
 import { parseArgs } from 'node:util';
@@ -66,8 +40,6 @@ const USAGE = {
 };
 
 /**
- * Parse the CLI argv. Exported for tests.
- *
  * @param {string[]} argv
  * @returns {{ storyId: number|null, base: string|null, cwd: string|null }}
  */
@@ -90,9 +62,6 @@ export function parseArgv(argv) {
 }
 
 /**
- * The derivation itself — pure over its injected collaborators, so tests can
- * pin the envelope without spawning git or reading a config.
- *
  * @param {{ storyId: number, baseRef: string, cwd: string, ceremonyProfile: string }} input
  * @param {{
  *   computeChangeSetImpl?: typeof computeChangeSet,
@@ -121,10 +90,7 @@ export function deriveCeremony(
   const { level, classes } = deriveChangeLevelImpl({
     changedFiles: changeSet.files,
   });
-  // The level is still derived and still printed — review depth reads it —
-  // but the ceremony profile alone resolves the verdict owner, and the
-  // resolver accepts nothing else, so nothing here can be talked into a
-  // different owner by the diff.
+  // The resolver takes the profile only, so the diff cannot change the owner.
   const ceremony = resolveCeremonyImpl({ ceremonyProfile });
   return {
     storyId,
@@ -142,8 +108,6 @@ export function deriveCeremony(
 }
 
 /**
- * CLI shell: resolve the config-backed defaults, derive, print.
- *
  * @param {string[]} [argv]
  * @param {{
  *   resolveConfigImpl?: typeof resolveConfig,

package/.agents/scripts/check-arch-cycles.js

@@ -1,36 +1,9 @@
 /**
- * CLI: ratchet-down architecture gate for import cycles (Story #3991).
- *
- * Walks every `.js` file across the project's **distributed surface**
- * (the `files[]` set published to npm — `.agents/scripts/`, `bin/`, and
- * the root `lib/`, excluding `node_modules`), parses relative
- * static-import edges (`from './…/x.js'`), detects directed cycles via
- * DFS, and compares them against the committed allowlist at
- * `baselines/arch-cycles.json`.
- *
- * The multi-root scan resolves every root into a **single** import graph
- * keyed by repository-relative module ids (Story #4071). This lets
- * `findCycles` catch cycles that cross the documented lifecycle↔runtime
- * partition — e.g. a `bin/` lifecycle script and an `.agents/scripts/lib`
- * runtime module importing each other — which a single-root scan cannot
- * see because it only walks one side of the partition.
- *
- * Ratchet semantics mirror `check-dead-exports.js`:
- *   - Any detected cycle NOT in the allowlist → exit 1, cycle path printed.
- *   - Allowlisted cycle no longer detected → printed as `-` (removal),
- *     warning that the allowlist can shrink. Removals-only exits 0.
- *   - Clean diff → exit 0.
- *
- * Cycles are normalized by rotating to the lexicographically-smallest
- * member so the same cycle always serializes identically regardless of
- * the DFS entry point.
- *
- * Flags:
- *   --baseline <path>  override the allowlist path (default
- *                      `baselines/arch-cycles.json`, resolved from cwd)
- *   --root <path>      scan a single explicit root instead of the default
- *                      distributed surface, relativized against that root
- *   --json             write the structured envelope to stdout
+ * CLI: ratchet-down gate for relative static-import cycles across the npm
+ * distributed surface, against the allowlist `baselines/arch-cycles.json`.
+ * All roots resolve into ONE graph keyed by repo-relative ids, so a cycle
+ * crossing the `bin/` ↔ `.agents/scripts/lib` partition is visible. Exit 1
+ * only on a new cycle; a vanished allowlisted cycle is reported as `-`.
  */
 
 import fs from 'node:fs';
@@ -44,17 +17,10 @@ import {
   parseRelativeImports,
 } from './lib/import-graph.js';
 
-// The import-graph builder itself lives in `lib/import-graph.js` (Story
-// #4902) so `audit-baselines.js` can rank hotspots by import in-degree
-// against the same graph this ratchet detects cycles in. Re-exported here
-// because this module's named exports are its unit-test surface and its
-// documented contract; the behaviour is unchanged by the move.
+// Shared with `audit-baselines.js`; re-exported as part of this module's contract.
 export { buildGraph, collectJsFiles, DEFAULT_ROOTS, parseRelativeImports };
 
 /**
- * Parse argv for `--baseline <path>`, `--root <path>`, and `--json`.
- * Exported so unit tests can pin the parser.
- *
  * @param {string[]} argv
  * @returns {{ baselinePath: string | null, rootPath: string | null, json: boolean }}
  */
@@ -84,10 +50,8 @@ export function parseArgv(argv = []) {
 }
 
 /**
- * Pure helper: rotate a cycle (array of module ids, no repeated terminal
- * element) so it starts at its lexicographically-smallest member. The same
- * cycle therefore always serializes identically regardless of where the
- * DFS entered it.
+ * Rotate a cycle to start at its smallest member, so it serializes the same
+ * whatever the DFS entry point.
  *
  * @param {string[]} cycle
  * @returns {string[]}
@@ -102,10 +66,8 @@ export function normalizeCycle(cycle) {
 }
 
 /**
- * Detect directed cycles in the graph via iterative-stack DFS (white /
- * gray / black coloring). Each back edge to a gray node yields the cycle
- * slice currently on the DFS path. Cycles are normalized and deduplicated
- * by their serialized form, then sorted for stable output.
+ * Iterative three-colour DFS; each back edge to a gray node yields the path
+ * slice as a cycle. Normalized, deduplicated, sorted.
  *
  * @param {Map<string, string[]>} graph
  * @returns {string[][]} normalized cycles
@@ -162,8 +124,7 @@ export function findCycles(graph) {
 }
 
 /**
- * Pure helper: read the allowlist envelope from disk. Returns the parsed
- * object or `null` when the file is missing or unparseable.
+ * `null` when missing or unparseable.
  *
  * @param {string} baselinePath
  * @returns {{ cycles?: string[][] } | null}
@@ -180,9 +141,7 @@ export function loadBaseline(baselinePath) {
 }
 
 /**
- * Pure helper: diff detected cycles against the allowlist. Both sides are
- * normalized before comparison so rotation differences never count as
- * drift. Identity is the ` -> `-joined normalized cycle.
+ * Both sides normalized, so a rotation never counts as drift.
  *
  * @param {string[][]} allowlisted
  * @param {string[][]} detected
@@ -199,10 +158,6 @@ export function diffCycles(allowlisted, detected) {
 }
 
 /**
- * Pure helper: render the human-readable diff. `+` lines are new cycles
- * (gate fail), `-` lines are fixed cycles whose allowlist entry can be
- * removed. A one-line summary always follows.
- *
  * @param {{ added: string[][], removed: string[][] }} diff
  * @returns {string}
  */
@@ -224,9 +179,6 @@ export function renderDiff(diff) {
 }
 
 /**
- * Top-level CLI entry. Exported so tests can drive the full pipeline
- * against a tmpdir fixture graph.
- *
  * @param {{
  *   argv?: string[],
  *   cwd?: string,
@@ -242,10 +194,8 @@ export async function runCli({
   stderr = process.stderr,
 } = {}) {
   const { baselinePath, rootPath, json } = parseArgv(argv);
-  // With an explicit `--root`, scan that single root and relativize ids
-  // against it (unchanged contract). Without it, scan the full distributed
-  // surface and relativize every id against the repo root (`cwd`) so edges
-  // that cross two roots resolve into a single graph.
+  // `--root` scans one root relative to itself; otherwise every root is
+  // relativized against `cwd` so cross-root edges join one graph.
   const graphRoot = rootPath ? path.resolve(cwd, rootPath) : path.resolve(cwd);
   const scanDirs = (rootPath ? [rootPath] : DEFAULT_ROOTS).map((dir) =>
     path.resolve(cwd, dir),

package/.agents/scripts/check-baselines.js

@@ -1,40 +1,10 @@
 #!/usr/bin/env node
 
-// .agents/scripts/check-baselines.js — Story #2466 thin CLI shell.
-//
-// Unified baseline dispatcher. The pipeline now lives under
-// `lib/orchestration/check-baselines/phases/`:
-//
-//   1. parse-args  — CLI flag parsing + canned `--help` text.
-//   2. floors      — `compareToFloor`, `assertFloorAxesExist`, `applyFloors`.
-//   3. compare     — scope resolution, base-baseline read, compare + tolerance.
-//   4. evaluate    — per-kind pipeline: load → floor → compare → tolerance.
-//   5. friction    — centralised friction emission (one event per
-//                    {kind, severity} tuple).
-//   6. report      — JSON / text rendering of the aggregated report.
-//   7. pipeline    — fan-out across enabled kinds, accumulate, aggregate
-//                    exit codes via `lib/baselines/exit-codes#aggregate`.
-//
-// Public CLI surface, exit codes, and friction payloads are byte-identical
-// to the pre-refactor implementation. The named exports below are the
-// same set the existing unit tests import.
-//
-// Pipeline stages per kind (Story #1965 / Task #1977):
-//   1. schema   — `reader.load(kind)` validates against per-kind schema.
-//   2. floor    — `applyFloors(kind, rollup, gateBlock.floors)`.
-//   3. tolerance — `gateBlock.tolerance` clamps near-floor compare deltas.
-//   4. compare   — head vs base via `git-base.readBaseFromGit(ref, path)`.
-//
-// Exit-code contract (Task #1975, see `lib/baselines/exit-codes.js`):
-//   0 EXIT_PASS        — every enabled gate is green.
-//   1 EXIT_FLOOR       — at least one floor breach.
-//   2 EXIT_SCHEMA      — at least one schema validation error.
-//   3 EXIT_CONFIG      — config resolution failure (mapped by main()).
-//   4 EXIT_REGRESSION  — at least one head-vs-base regression.
+// check-baselines.js — thin CLI shell over the unified baseline dispatcher in
+// `lib/orchestration/check-baselines/phases/` (per kind: schema → floor →
+// compare vs base → tolerance). Exit codes: `lib/baselines/exit-codes.js`.
 
-// Fail-fast if the framework's runtime deps are not installed — must be the
-// first import so the check runs before any third-party-importing sibling
-// module is evaluated (Story #3432).
+// Must be the first import: fail fast before any third-party import evaluates.
 import './lib/runtime-deps/ensure-installed.js';
 import { EXIT_CONFIG } from './lib/baselines/exit-codes.js';
 import { runAsCli } from './lib/cli-utils.js';
@@ -53,8 +23,7 @@ import {
 } from './lib/orchestration/check-baselines/phases/pipeline.js';
 import { formatReport } from './lib/orchestration/check-baselines/phases/report.js';
 
-// Named exports preserved for the unit-test surface (Story #2466 — byte-
-// identical CLI parity). Tests import directly from this module path.
+// Re-exported: tests import these from this module path.
 export {
   applyFloors,
   assertFloorAxesExist,
@@ -66,18 +35,9 @@ export {
 };
 
 /**
- * Run the dispatcher and *return* its exit code rather than calling
- * `process.exit()`.
- *
- * The return is load-bearing (Story #4783's defect, reintroduced here):
- * `process.exit()` terminates before a queued async pipe write drains, so a
- * full `--gate coverage` report — a quarter of a megabyte of JSON — arrived
- * truncated at the 64 KiB pipe boundary under the `| tee` in CI's coverage
- * step, while still exiting 0. Handing the code back to `runAsCli`'s
- * `propagateExitCode` path settles it through `settleCli`/`flushStdio`
- * instead, which assigns `process.exitCode` and lets Node terminate once
- * stdout has drained. The 0/1/2/3/4 contract in `lib/baselines/exit-codes.js`
- * is unchanged — only *when* the process leaves is.
+ * Returns the exit code rather than calling `process.exit()`: exiting early
+ * truncates a large report at the 64 KiB pipe boundary; `runAsCli` sets
+ * `process.exitCode` and lets stdout drain.
  *
  * @returns {Promise<number>} An exit code from the `EXIT_*` contract.
  */