mandrel 2.59.0 → 2.61.0

package/.agents/scripts/lint-issue-body.js

@@ -1,29 +1,9 @@
 #!/usr/bin/env node
 // .agents/scripts/lint-issue-body.js
 /**
- * Issue-body conformance lint (Story #4227).
- *
- * Runs the canonical `story-body.parse()` against a human-opened
- * `type::story` issue body and reports whether the body
- * round-trips. This is the drift guard between the generated GitHub Issue
- * Forms (`lib/bootstrap/issue-forms-template.js`) and the parser: if a
- * human files a ticket whose body `parse()` rejects (or which lacks the
- * binding `goal` / `acceptance` / `verify` sections), the lint surfaces a
- * **comment** on the issue rather than failing silently — the supported
- * human entry points (`/mandrel-plan` from an existing Epic ID, the qa-assist →
- * `/mandrel-plan` handoff) depend on a parseable body.
- *
- * ## Design
- *
- * - `evaluateIssueBody(body)` is **pure** (no I/O): it parses the body and
- *   returns a structured conformance verdict. This is the unit-tested core.
- * - The CLI wrapper reads the issue body + labels (via `gh` or env), runs
- *   the evaluator, and posts/updates a single marker comment when the body
- *   is non-conformant. Network-touching, exercised in CI.
- *
- * GitHub Issue Forms render a skipped optional field as the literal
- * `_No response_`; the evaluator strips that sentinel so an empty optional
- * section does not masquerade as content.
+ * Drift guard between the generated Issue Forms and the Story-body parser:
+ * a human-filed Story whose body does not round-trip gets an informational
+ * marker comment (never a CI failure).
  *
  * @module lint-issue-body
  */
@@ -32,17 +12,9 @@ import { spawnSync } from 'node:child_process';
 import { runAsCli } from './lib/cli-utils.js';
 import { parse, StoryBodyParseError } from './lib/story-body/story-body.js';
 
-/**
- * Marker that identifies the lint's own comment so re-runs update rather
- * than duplicate it.
- */
 export const LINT_COMMENT_MARKER = '<!-- mandrel:issue-body-conformance -->';
 
-/**
- * The binding sections every conformant ticket body MUST carry. `changes`
- * and `references` are advisory (per the Engineer persona's implementation
- * latitude), so they are not required here.
- */
+/** `changes` and `references` are advisory, so not required. */
 const REQUIRED_SECTIONS = [
   { field: 'goal', label: 'Goal' },
   { field: 'acceptance', label: 'Acceptance' },
@@ -50,9 +22,7 @@ const REQUIRED_SECTIONS = [
 ];
 
 /**
- * Strip the GitHub Issue Form empty-field sentinel so a skipped optional
- * field is treated as absent rather than literal content.
- *
+ * Issue Forms render a skipped field as `_No response_`; treat it as absent.
  * @param {string} body
  * @returns {string}
  */
@@ -65,22 +35,16 @@ function stripNoResponseSentinel(body) {
 
 /**
  * @typedef {object} ConformanceVerdict
- * @property {boolean}  conformant   - True when the body parses AND carries
- *   every required section with non-empty content.
- * @property {string[]} problems     - Human-readable problem statements
- *   (empty when conformant).
- * @property {string[]} warnings     - Non-fatal parser warnings surfaced for
- *   transparency (e.g. legacy-path-entry).
- * @property {boolean}  parseFailed  - True when `parse()` threw (fail-closed).
+ * @property {boolean}  conformant
+ * @property {string[]} problems
+ * @property {string[]} warnings
+ * @property {boolean}  parseFailed
  */
 
 /**
- * Evaluate an issue body for conformance with the canonical Story-body
- * schema. Pure — no I/O. Fail-closed parse errors are caught and reported
- * as a non-conformant verdict (never thrown), because the caller's job is
- * to *comment*, not to crash CI.
- *
- * @param {string} body - Raw issue-body markdown.
+ * Pure. Parse errors become a non-conformant verdict, never a throw: the
+ * caller's job is to comment, not crash CI.
+ * @param {string} body
  * @returns {ConformanceVerdict}
  */
 export function evaluateIssueBody(body) {
@@ -114,8 +78,6 @@ export function evaluateIssueBody(body) {
 
   const problems = [];
 
-  // An unstructured body parses but carries no structured sections — that
-  // is exactly the human-filed shape this lint exists to catch.
   if (result.info.isUnstructuredBody) {
     problems.push(
       'The body has no recognised `## Goal` / `## Acceptance` / `## Verify` sections. ' +
@@ -145,9 +107,6 @@ export function evaluateIssueBody(body) {
 }
 
 /**
- * Render the markdown comment body the lint posts on a non-conformant
- * issue. Carries {@link LINT_COMMENT_MARKER} so re-runs update in place.
- *
  * @param {ConformanceVerdict} verdict
  * @returns {string}
  */
@@ -179,9 +138,6 @@ export function renderConformanceComment(verdict) {
 }
 
 /**
- * Thin `gh` wrapper. Returns the trimmed stdout, throwing on a non-zero
- * exit so the CLI surfaces the failure (orchestration-error-handling rule).
- *
  * @param {string[]} args
  * @returns {string}
  */
@@ -196,8 +152,6 @@ function gh(args) {
 }
 
 /**
- * Stage 5: only `type::story` tickets are in scope (type::epic retired).
- *
  * @param {string[]} labelNames
  * @returns {boolean}
  */
@@ -206,10 +160,6 @@ export function isStoryTicket(labelNames) {
 }
 
 /**
- * Evaluate an issue payload and optionally post a conformance comment.
- * Pure with respect to GitHub when `ghFn` is injected — the CLI `main`
- * is a thin argv wrapper around this helper.
- *
  * @param {{
  *   issue: string|number,
  *   repo?: string,
@@ -266,12 +216,6 @@ export function runLintIssueBody({
   return { conformant: false, problems: verdict.problems };
 }
 
-/**
- * CLI entry. Reads the target issue (number from `--issue` or the
- * `ISSUE_NUMBER` env), fetches its body + labels, and — when the body is
- * non-conformant — upserts a single marker comment. Always exits 0 (the
- * lint *informs*, it does not block), unless an unexpected I/O error occurs.
- */
 async function main() {
   const args = process.argv.slice(2);
   const get = (flag) => {

package/.agents/scripts/mandrel-update-preflight.js

@@ -1,42 +1,12 @@
 #!/usr/bin/env node
 
 /**
- * mandrel-update-preflight.js — Story #4170
- * (feat(mandrel-update): add a first-run preflight before the updater)
- *
- * A first-run preflight for the `/mandrel-update` workflow. The workflow
- * otherwise jumps straight to `npx mandrel update` with no guard rails;
- * this preflight catches three day-0 failure modes *before* the version
- * bump:
- *
- *   1. **Wrong project (hard stop).** Running the updater in the framework
- *      repo itself or in a non-consumer (no `mandrel` dependency in
- *      `package.json`, or no materialized `.agents/` directory) silently
- *      does the wrong thing. The consumer-shape check is a BLOCKER: it
- *      exits non-zero so the workflow halts before bumping anything.
- *   2. **Dirty git index (warn).** `mandrel update` deliberately leaves the
- *      lockfile *staged* (see `lib/cli/update.js`); the workflow's commit
- *      step then `git add`s and commits. If the index already holds
- *      unrelated staged changes, that step would sweep them into the
- *      `chore: update mandrel` commit. Warn so the operator can unstage
- *      first.
- *   3. **Offline (warn).** The CLI throws a usable error on a failed
- *      `npm view`, but a one-line up-front reachability check gives a
- *      friendlier "you're offline" signal before any version probe.
- *
- * Severity is consistent with framework preflight conventions
- * (cf. `single-story-close.js` runStoryClosePreflight, `mandrel-update-preflight.js`):
- * the consumer-shape check is a hard stop (blocker), dirty-index and offline
- * are warn-only and never block the run.
- *
- * Out of scope (per the Story): folding these checks into
- * `lib/cli/update.js` itself — the CLI stays git-free and
- * side-effect-scoped; this is a workflow-layer concern.
- *
- * The detection logic is a pure function (`runMandrelUpdatePreflight`) that
- * takes injectable probes so it is unit-testable without touching the real
- * filesystem, git index, or network. The CLI wrapper wires the real probes
- * and maps a blocker finding to a non-zero exit code.
+ * mandrel-update-preflight.js — first-run guard for `/mandrel-update`, run
+ * before the version bump. Hard-stops outside a consumer repo (no `mandrel`
+ * dependency or no `.agents/`). Warns on a dirty index (the update leaves the
+ * lockfile staged, so the commit step would sweep unrelated staged files in)
+ * and when the registry is unreachable. Kept out of `lib/cli/update.js`, which
+ * stays git-free.
  */
 
 import { execFileSync } from 'node:child_process';
@@ -54,16 +24,11 @@ import { Logger } from './lib/Logger.js';
  */
 
 /**
- * Real-world probes. Each is overridable in tests via the `probes` option.
- *
- * @param {string} projectRoot Absolute consumer repo root.
+ * @param {string} projectRoot
  */
 export function makeProbes(projectRoot) {
   return {
-    /**
-     * Read + parse `package.json`. Returns the parsed object, or `null`
-     * when the file is missing or unparseable.
-     */
+    /** `null` when missing or unparseable. */
     readPackageJson() {
       const pkgPath = path.join(projectRoot, 'package.json');
       if (!existsSync(pkgPath)) return null;
@@ -73,16 +38,10 @@ export function makeProbes(projectRoot) {
         return null;
       }
     },
-    /** Does the materialized `.agents/` directory exist? */
     agentsDirExists() {
       return existsSync(path.join(projectRoot, '.agents'));
     },
-    /**
-     * Are there staged (index) changes? Returns true when
-     * `git diff --cached --name-only` is non-empty. Returns false on any
-     * git error (not a repo, git missing) — a missing index is not a
-     * dirty index.
-     */
+    /** False on any git error: a missing index is not a dirty one. */
     hasStagedChanges() {
       try {
         const out = execFileSync('git', ['diff', '--cached', '--name-only'], {
@@ -95,11 +54,6 @@ export function makeProbes(projectRoot) {
         return false;
       }
     },
-    /**
-     * Is the npm registry reachable? Probes `npm ping` (a PM-agnostic
-     * reachability query that does not mutate anything). Returns true when
-     * the ping succeeds, false on any failure (offline / registry down).
-     */
     registryReachable() {
       try {
         execFileSync('npm', ['ping'], {
@@ -117,22 +71,16 @@ export function makeProbes(projectRoot) {
 }
 
 /**
- * Pure preflight evaluator. Runs the three checks against the supplied
- * probes and returns a structured result. Never throws; never performs
- * I/O directly (all I/O is behind `probes`).
+ * Pure: all I/O is behind `probes`. `ok` means no findings at all.
  *
  * @param {object} options
  * @param {ReturnType<typeof makeProbes>} options.probes
  * @returns {{ ok: boolean, blocked: boolean, findings: PreflightFinding[] }}
- *   `blocked` is true when any blocker-severity finding fired (the
- *   consumer-shape hard stop). `ok` is true when there are no findings of
- *   any severity.
  */
 export function runMandrelUpdatePreflight({ probes }) {
   /** @type {PreflightFinding[]} */
   const findings = [];
 
-  // 1. Consumer-shape check — BLOCKER (hard stop).
   const pkg = probes.readPackageJson();
   const deps = pkg
     ? {
@@ -158,7 +106,6 @@ export function runMandrelUpdatePreflight({ probes }) {
     });
   }
 
-  // 2. Dirty-index check — WARN only.
   if (probes.hasStagedChanges()) {
     findings.push({
       id: 'dirty-index',
@@ -169,7 +116,6 @@ export function runMandrelUpdatePreflight({ probes }) {
     });
   }
 
-  // 3. Offline check — WARN only.
   if (!probes.registryReachable()) {
     findings.push({
       id: 'offline',
@@ -185,9 +131,6 @@ export function runMandrelUpdatePreflight({ probes }) {
 }
 
 /**
- * Render the findings to a logger. Blockers go to `error`, warnings to
- * `warn`. A clean result logs a single `info` line.
- *
  * @param {{ ok: boolean, blocked: boolean, findings: PreflightFinding[] }} result
  * @param {{ info: Function, warn: Function, error: Function }} logger
  */
@@ -222,9 +165,6 @@ async function main() {
   const probes = makeProbes(projectRoot);
   const result = runMandrelUpdatePreflight({ probes });
   reportPreflight(result, Logger);
-  // Machine-parsable JSON envelope on stdout for tooling / the workflow to
-  // read. Use process.stdout.write (not console.log) per the no-console
-  // enforcement boundary: human-facing output goes through Logger above.
   process.stdout.write(`${JSON.stringify(result)}\n`);
   return result.blocked ? 2 : 0;
 }

package/.agents/scripts/merge-baseline.js

@@ -1,46 +1,17 @@
 #!/usr/bin/env node
 
 /**
- * merge-baseline.js — git merge driver for `baselines/*.json` (Story #5215).
+ * merge-baseline.js — git merge driver for `baselines/*.json`.
  *
- * ## The failure it replaces
- *
- * Every baseline write stamps `generatedAt` on line 4, so two branches that
- * each refresh a baseline ALWAYS differ there — even when they moved
- * completely disjoint rows. Git merges JSON as text, so whether it can
- * separate that hunk from the moved rows is an accident of proximity:
- *
- *   - it cannot → a conflict on work that never overlapped (the observed
- *     `coverage.json` / `maintainability.json` "always conflicts" pattern);
- *   - it can → it splices both sides' row lines into a row set neither side
- *     scored, and the ratchet then guards a number no scorer produced (the
- *     observed `crap.json` "silently auto-merges" pattern).
- *
- * The quiet one is the worse one. A baseline is a set of rows keyed by
- * identity plus a rollup derived from them, so this driver merges it as
- * that — see `lib/baselines/merge-envelopes.js` for the semantics.
- *
- * ## Contract
+ * A text merge of a baseline either conflicts on the always-different
+ * `generatedAt` stamp or, worse, silently splices both sides' rows into a set
+ * no scorer produced. This merges rows by identity and re-derives the rollup.
+ * Files that are not a known row baseline go to `git merge-file` unchanged.
  *
  *   node .agents/scripts/merge-baseline.js %O %A %B %P
  *
- * git's merge-driver calling convention: `%O` ancestor, `%A` ours (and the
- * file the driver MUST leave its result in), `%B` theirs, `%P` the real
- * pathname being merged. Exit 0 merged clean, non-zero conflicted.
- *
- * Registered per clone (registration is per-clone, so `mandrel doctor` is
- * the guard that it happened, not `mandrel sync`):
- *
- *   .gitattributes:  baselines/*.json merge=mandrel-baseline
- *   git config:      merge.mandrel-baseline.driver
- *
- * ## Not every `baselines/*.json` is an envelope
- *
- * That glob also matches arch-cycles, cyclomatic, dead-exports, audit-ledger,
- * context-budget and workflow-citations — files with their own shapes and no
- * row identity. Anything whose `$schema` is not a known per-kind envelope is
- * handed straight back to `git merge-file`, so registering the driver cannot
- * change their behaviour.
+ * `%A` is ours and MUST hold the result. Exit 0 clean, non-zero conflicted.
+ * Registration is per-clone git config, so `mandrel doctor` guards it.
  */
 
 import fs from 'node:fs';
@@ -71,13 +42,11 @@ function rowBlock(row) {
 }
 
 /**
- * Wrap each conflicting row in git conflict markers, leaving every other row
- * merged. Operates on the canonical text the writer already produced, so the
- * non-conflicting remainder of the file is byte-identical to what a clean
- * merge would have written.
+ * Wrap each conflicting row in markers within the canonical text, so the rest
+ * is byte-identical to a clean merge.
  *
- * @param {string} text Canonical serialization of the merged envelope.
- * @param {Array<object>} conflicts Row-scoped conflict records.
+ * @param {string} text
+ * @param {Array<object>} conflicts
  * @returns {string}
  */
 export function renderConflictMarkers(text, conflicts) {
@@ -86,8 +55,7 @@ export function renderConflictMarkers(text, conflicts) {
     const placed = conflict.ours ?? conflict.theirs;
     if (placed === undefined) continue;
     const block = rowBlock(placed);
-    // The row may or may not be the last element of `rows`; keep whichever
-    // separator follows it on both sides so the markers wrap whole lines.
+    // Keep the row's trailing separator (if any) so markers wrap whole lines.
     const withComma = `${block},`;
     const [needle, suffix] = out.includes(withComma)
       ? [withComma, ',']
@@ -125,18 +93,13 @@ function readSide(file) {
 }
 
 /**
- * Hand the merge back to git's own text merge. Used for every
- * `baselines/*.json` that is not a known per-kind envelope, and for one that
- * is too damaged to parse — in both cases the driver must not invent a
- * result, and git's behaviour is exactly what the repo had before.
+ * Fall back to git's text merge for unknown or unparseable files; the driver
+ * never invents a result.
  *
  * @returns {number} git merge-file's own exit code.
  */
 function delegateToGit(basePath, oursPath, theirsPath) {
-  // `stdio: 'inherit'` so git's own conflict reporting reaches the operator
-  // exactly as it would have with no driver registered. `spawnChild` returns
-  // the RAW result deliberately: a `status` of null means the child was
-  // killed, and that must never be read as a clean merge.
+  // A null status means the child was killed — never a clean merge.
   const result = spawnChild(
     'git',
     ['merge-file', oursPath, basePath, theirsPath],
@@ -152,20 +115,8 @@ function delegateToGit(basePath, oursPath, theirsPath) {
 }
 
 /**
- * Which merge does this file get?
- *
- * Two families answer, and neither is "all of `baselines/*.json`":
- *
- *   - **Envelope kinds** — the eight kernel kinds, merged by the kind
- *     module's own `rowIdentity` with the rollup RE-DERIVED.
- *   - **Plain row baselines** — `cyclomatic`, `dead-exports` and
- *     `dead-exports-production`, which are row sets with a real identity but
- *     no kernel protocol. Until Story #5277 these fell through to
- *     `git merge-file` even though `.gitattributes` routes them here, so the
- *     attribute promised a row merge the driver never performed.
- *
- * Anything else — arch-cycles, audit-ledger, context-budget,
- * workflow-citations — resolves `null` and is handed back to git unchanged.
+ * Envelope kinds (rollup re-derived) or plain row baselines (cyclomatic,
+ * dead-exports*); anything else resolves `null` and goes back to git.
  *
  * @param {unknown} ours
  * @param {unknown} theirs
@@ -180,11 +131,8 @@ function resolveMergeTarget(ours, theirs) {
 }
 
 /**
- * Serialize the merged result into `%A`. Envelope kinds go through the shared
- * writer (which validates against the per-kind schema); plain baselines are
- * written with the same `JSON.stringify(…, null, 2)` + trailing newline their
- * own generators use, which is what keeps a clean merge byte-identical to a
- * regeneration.
+ * Plain baselines use their generators' exact serialization so a clean merge
+ * is byte-identical to a regeneration.
  *
  * @param {string} oursPath
  * @param {{ envelope: object }} merged
@@ -199,15 +147,8 @@ function writeMerged(oursPath, merged, isEnvelopeKind) {
 }
 
 /**
- * Register the driver in this clone (`--install`).
- *
- * The driver script installs its own registration because the registration is
- * the half that cannot travel: `.gitattributes` is tracked and ships with the
- * repo, `merge.mandrel-baseline.driver` is per-clone git config and is absent
- * in every fresh clone — silently, with git falling back to a text merge and
- * reporting nothing. Wired into this repo's `prepare` script so `npm install`
- * completes the registration, and idempotent so every later `prepare` is a
- * no-op.
+ * `--install`: the per-clone git config does not travel with the repo and its
+ * absence is silent, so `prepare` runs this (idempotent).
  *
  * @returns {number} Process exit code.
  */
@@ -239,11 +180,8 @@ export function runMergeBaseline(argv) {
     return 2;
   }
 
-  // Git hands the driver temp filenames RELATIVE to the worktree root it
-  // invokes us from (`.merge_file_xxxxxx`), so every path is resolved before
-  // use — the shared writer refuses a relative path, and that refusal only
-  // shows up under a real `git merge`, never when the driver is called
-  // directly with absolute paths.
+  // Git passes worktree-relative temp names; the shared writer refuses
+  // relative paths.
   const [basePath, oursPath, theirsPath] = [baseArg, oursArg, theirsArg].map(
     (p) => path.resolve(p),
   );
@@ -269,9 +207,7 @@ export function runMergeBaseline(argv) {
 }
 
 /**
- * Merge a file whose kind the driver DOES understand, and leave the result in
- * `%A`. A merge that throws is handed back to git rather than half-written:
- * the driver must never invent a result for a baseline it could not model.
+ * A merge that throws is handed back to git rather than half-written.
  *
  * @param {object} ctx
  * @returns {number} Process exit code.
@@ -297,9 +233,7 @@ function mergeResolved({
     return delegateToGit(basePath, oursPath, theirsPath);
   }
 
-  // Write the canonical projection first even when conflicted: the marker
-  // rendering operates on exactly the bytes a clean merge would have left,
-  // so the merged remainder of a conflicted file is identical to it.
+  // Written even when conflicted: markers are rendered onto these bytes.
   writeMerged(oursPath, merged, isEnvelopeKind);
 
   if (merged.conflicts.length === 0) {
@@ -310,15 +244,11 @@ function mergeResolved({
 }
 
 /**
- * Report a conflicted merge and render its markers into `%A`.
- *
- * Both scopes get markers. An envelope-level conflict used to be reported on
- * stderr alone, leaving a file that looked cleanly merged while git held the
- * path unmerged — the operator had to reconstruct from scrollback which stamp
- * disagreed.
+ * Both row and envelope conflicts get in-file markers, so the file never
+ * looks cleanly merged while git holds it unmerged.
  *
  * @param {{ kind: string, merged: object, oursPath: string, label: string }} ctx
- * @returns {number} Always 1 — a conflicted merge.
+ * @returns {number} Always 1.
  */
 function markConflicts({ kind, merged, oursPath, label }) {
   const rowConflicts = merged.conflicts.filter((c) => c.scope === 'row');
@@ -339,13 +269,8 @@ function markConflicts({ kind, merged, oursPath, label }) {
 }
 
 /**
- * Report every conflict on stderr, then name the regeneration command.
- *
- * The regenerate line is not decoration. The merged file's rollup was derived
- * from a row set that still carries conflict markers, so resolving the markers
- * by hand leaves the rollup describing a tree nobody scored — the same silent
- * wrong number the driver exists to prevent, arrived at from the other
- * direction. Saying it here is the only place an operator sees it.
+ * Names the regenerate command: the rollup was derived from unresolved rows,
+ * so hand-resolving the markers leaves it describing a tree nobody scored.
  *
  * @param {{ kind: string, label: string, rowConflicts: Array<object>, envelopeConflicts: Array<object> }} args
  */