mandrel 2.60.0 → 2.62.0

package/.agents/workflows/qa-explore.md

@@ -6,29 +6,18 @@ description: Agent-led exploratory-QA loop — the agent Plans a surface with an
 
 Drive a **bounded, agent-led exploratory-QA session** as a human-in-the-loop
 (HITL) loop: **Plan → Capture → Triage**. The operator names a single surface;
-the agent (acting as the QA engineer) **plans** how it will reach that surface,
-**drives** it itself — through the browser MCP by default, or statically as a
-documented interim — and records each observation as a structured ledger item
-under a strictly read-only capture invariant. Only after explicit operator
-confirmation does it triage the ledger into routed, classified, dedup'd
-follow-up dispositions.
-
-This is the **agent-led** front-end of exploratory QA: **the agent drives, the
-operator watches and gates.** Its human-led sibling is
-[`/qa-assist`](qa-assist.md) — there the *human* drives a single observation and
-the agent scribes/enriches. No human-driven flow lives in `/qa-explore`.
-
-Unlike [`/qa-run`](qa-run.md) (which steps a known set of Gherkin `.feature`
-scenarios through a browser), `/qa-explore` is **open-ended exploration**: the
-agent probes the surface for product bugs, environment-setup friction,
-tooling/DX gaps, missing tests, and enhancement ideas — each captured as a
-`QaLedgerItem`.
+the agent drives it itself — **the agent drives, the operator watches and
+gates** — and records each observation as a `QaLedgerItem` under a strictly
+read-only capture invariant. Its human-led sibling is
+[`/qa-assist`](qa-assist.md); no human-driven flow lives in `/qa-explore`.
+Unlike [`/qa-run`](qa-run.md) (a known set of Gherkin `.feature` scenarios),
+this is **open-ended exploration** for product bugs, environment-setup
+friction, tooling/DX gaps, missing tests, and enhancement ideas.
 
 The shared machinery — contract resolution + loud failure, the session & ledger
 contract, redact-first, the `QaLedgerItem` shape, the triage procedure, and the
 HITL write gate — lives once in [`helpers/qa-core.md`](helpers/qa-core.md); this
-workflow states only the `/qa-explore`-specific phases (Plan / Capture) plus a
-Constraints delta.
+workflow states only the `/qa-explore`-specific phases (Plan / Capture).
 
 > **When to run**: ad-hoc agent-driven exploration of a freshly delivered Story
 > or Feature, a regression sweep over a risky surface before `/mandrel-deliver`, or a
@@ -69,9 +58,7 @@ the skill owns them.
 | `surface` | yes      | `feature:login`, `area:onboarding` | A human label for the single surface to explore. Recorded as each ledger item's `coverage`. |
 
 If no `surface` is supplied, **stop and ask** the operator to name one — do not
-invent scope. `/qa-explore` is **bounded to one surface per session**: explore
-exactly the named surface, do not wander into adjacent surfaces, and start a
-fresh session for a different surface.
+invent scope.
 
 ## Contract & session
 
@@ -171,23 +158,16 @@ For each observation the agent makes while driving:
 
 1. **Redact first** (per [`helpers/qa-core.md`](helpers/qa-core.md)) — scrub the
    evidence string through `redactEvidence` before it touches disk.
-2. **Read the coverage tiers** for the surface the observation points at:
-   gather the tests that exercise it and classify each by path per
-   [`testing-standards.md` § The Three Tiers](../rules/testing-standards.md#the-three-tiers)
-   — a `.feature` file is **acceptance**, a path containing `/contract/` or
-   `.contract.test.` is **contract**, and a path containing `.test.` or
-   `__tests__/` is **unit**. A skipped test leaves its tier uncovered.
-3. **Name the missing test** (if any): take the lowest tier with no live test
-   (unit → contract → acceptance) and write one concrete sentence describing
-   the test that would close it. Every tier covered means no missing test.
-   Record that sentence as the ledger item's `missingTest` (or `null`).
-4. **Append a `QaLedgerItem`** to the ledger (shape per
+2. **Read the coverage tiers and name the missing test** per
+   [`helpers/qa-core.md`](helpers/qa-core.md) § Coverage tiers, recording the
+   sentence as the ledger item's `missingTest` (or `null`).
+3. **Append a `QaLedgerItem`** to the ledger (shape per
    [`helpers/qa-core.md`](helpers/qa-core.md)): a stable `id`, the redacted
    `evidence`, the `coverage` label (the `surface`, or `unknown`), a tentative
    `class` and `severity`, the `missingTest`, and `disposition` left untriaged.
-5. Continue driving until the agent believes the surface is covered, then
+4. Continue driving until the agent believes the surface is covered, then
    propose that exploration is complete.
-6. **Gate:** present the captured ledger (item count, classes, the driving
+5. **Gate:** present the captured ledger (item count, classes, the driving
    method used, the rolling backlog) and ask the operator to confirm moving to
    Triage. Do **not** triage until they confirm.
 
@@ -212,30 +192,10 @@ resumed session will pick up.
 
 ## Constraints
 
-Beyond the shared core ([`helpers/qa-core.md`](helpers/qa-core.md): contract +
-loud failure, session/ledger, redact-first, QaLedgerItem, triage, HITL gate)
-and the driving conventions
-([`stack/qa/qa-harness`](../skills/stack/qa/qa-harness/SKILL.md)),
-the `/qa-explore`-specific deltas are:
-
-- **Agent-led, bounded per surface.** The agent drives one named surface per
-  session and proposes when it is covered; the operator gates the boundary. No
-  human-driven flow lives here — that is [`/qa-assist`](qa-assist.md).
-- **Pick the driving method at Plan time** (drive default; static the documented
-  interim, chosen with a recorded reason, never a silent fallback); do not
-  switch mid-surface without a new Plan note.
-- **Capture is read-only.** The only Capture write is appending ledger lines
-  under `temp/qa/`. No source edits, ticket mutations, product writes, or
-  destructive form submissions. Reach an authenticated surface only through the
-  resolved environment's `signInSeam`; where no seam resolves, record the gap
-  and fall back to static.
-- **Broken navigation is a finding, not a workaround** — never URL-jump around a
-  missing affordance, a nav 404, or a guard redirect loop.
-- **Read tier placement from the rule, not from prose you invent.** The three
-  path rules in
-  [`testing-standards.md` § The Three Tiers](../rules/testing-standards.md#the-three-tiers)
-  decide which tier a test occupies; the missing-test sentence is yours to write
-  from the lowest uncovered tier.
+The shared core in [`helpers/qa-core.md`](helpers/qa-core.md) and the driving
+conventions in [`stack/qa/qa-harness`](../skills/stack/qa/qa-harness/SKILL.md)
+bind this workflow. The `/qa-explore` deltas are stated once, above: one
+surface per session, the method chosen at Plan time, and a read-only Capture.
 
 ## See also
 

package/.agents/workflows/qa-run.md

@@ -6,23 +6,17 @@ description: Drive Gherkin scenarios through a real browser as an agent-driven Q
 
 Execute a consumer's Gherkin `.feature` scenarios through a **real browser**
 (the chrome-devtools MCP surface), with the agent acting as the step executor
-and a human observing. The sweep resolves a **run envelope** — a target
-environment, a concrete scenario set, and an authenticated persona session —
-then delegates each scenario to
-[`helpers/qa-run-scenario.md`](helpers/qa-run-scenario.md), which drives it
-navigation-first and asserts `Then` outcomes semantically against the
-accessibility snapshot. Per-surface console and network are captured as
-structured findings, recorded as `QaLedgerItem`s on the shared session ledger,
-and triaged — after operator sign-off — through the shared classify/route/
-dedup/promote core. The harness never files tickets autonomously.
+and a human observing: resolve a run envelope, drive each scenario through
+[`helpers/qa-run-scenario.md`](helpers/qa-run-scenario.md), record findings as
+`QaLedgerItem`s, and triage after operator sign-off.
 
 The shared machinery — contract resolution + loud failure, the session & ledger
 contract, redact-first, the `QaLedgerItem` shape, the triage procedure, and the
 HITL write gate — lives once in [`helpers/qa-core.md`](helpers/qa-core.md); this
 workflow states only the `/qa-run`-specific phases (env → scope → sign-in →
-drive) plus a Constraints delta. Deterministic Node helpers under
-`.agents/scripts/lib/qa/` own contract, environment, and scenario resolution;
-the agent never invents those decisions in prose.
+drive). Deterministic Node helpers under `.agents/scripts/lib/qa/` own
+contract, environment, and scenario resolution; the agent never invents those
+decisions in prose.
 
 > **When to run**: during sprint testing to exercise a targeted slice of the
 > acceptance suite (a feature, a tag expression, or a domain), for regression
@@ -99,7 +93,8 @@ The chrome-devtools MCP surface (`navigate_page`, `take_snapshot`, `click`,
 `list_network_requests`) is **host-provided** — an external runtime dependency,
 not in-repo code. If the host does not expose it, degrade with a clear error
 ("the chrome-devtools MCP server is unavailable; the QA harness requires a live
-browser surface") and stop. Never attempt a headless fallback.
+browser surface") and stop. Never attempt a headless fallback, and never fall
+back to a retired headless BDD runner.
 
 ### Step 1 — Resolve the environment, then the scope
 
@@ -234,23 +229,6 @@ Then summarize the sweep in chat with:
 
 ## Constraints
 
-Beyond the shared core ([`helpers/qa-core.md`](helpers/qa-core.md): contract +
-loud failure, session/ledger, redact-first, QaLedgerItem, triage, HITL gate)
-and the driving rules ([`helpers/qa-run-scenario.md`](helpers/qa-run-scenario.md):
-navigation-first, semantic `Then`, redaction, sequential-only), the
-`/qa-run`-specific deltas are:
-
-- **Always** resolve a target environment (Step 1) — prompt when no `<env>` is
-  supplied — and **fail loudly** on an unknown name or unmatched URL; never
-  silently fall back to the default.
-- **Always** apply the `allowWrites` guardrail: on a read-only environment,
-  exclude mutating scenarios and report the exclusion count; include them only
-  on explicit in-session operator confirmation.
-- **Always** sign in per persona through the environment's `signInSeam` and
-  confirm the authenticated state with a post-sign-in `take_snapshot` before
-  driving.
-- An **empty selection is operator error**, not a passing sweep — report it and
-  stop.
-- **Never** expand `consoleAllowlist` to suppress genuine error signal.
-- **Never** file follow-up tickets autonomously, and **never** fall back to a
-  retired headless BDD runner.
+The shared core in [`helpers/qa-core.md`](helpers/qa-core.md) and the driving
+rules in [`helpers/qa-run-scenario.md`](helpers/qa-run-scenario.md) bind this
+workflow; the `/qa-run` deltas are the MUSTs in Steps 0–5 above.

package/README.md

@@ -105,7 +105,7 @@ idempotent — safe to re-run anytime.
 
 For the consumer reference and the end-to-end workflow narrative, see
 [`.agents/README.md`](.agents/README.md) and
-[`.agents/docs/SDLC.md`](.agents/docs/SDLC.md). Every `.agentrc.json` key is
+[`docs/SDLC.md`](docs/SDLC.md). Every `.agentrc.json` key is
 documented in [`.agents/docs/configuration.md`](.agents/docs/configuration.md), and the
 slash-command index lives in
 [`.agents/docs/workflows.md`](.agents/docs/workflows.md).

package/bin/mandrel.js

@@ -2,17 +2,8 @@
 // bin/mandrel.js — mandrel CLI entry point
 
 /**
- * Allowlist-based subcommand dispatcher.
- *
- * Only modules listed in SUBCOMMANDS are dispatchable. Each entry declares the
- * name, a one-line description for help output, and the set of known flags so
- * the dispatcher can reject unknown flags before loading the subcommand.
- *
- * Supported top-level flags:
- *   --help / -h    Print subcommand list and exit 0.
- *   --version      Print installed version and exit 0.
- *
- * Each subcommand module must export a default function `run(argv)`.
+ * Allowlist dispatcher: only SUBCOMMANDS entries load, and unknown flags are
+ * rejected before loading. Each module default-exports `run(argv)`.
  */
 
 import { createRequire } from 'node:module';
@@ -21,10 +12,6 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
-// ---------------------------------------------------------------------------
-// Subcommand registry — the ONLY allowed dispatch targets
-// ---------------------------------------------------------------------------
-
 /**
  * @typedef {{ description: string, knownFlags: Set<string> }} SubcommandMeta
  * @type {Map<string, SubcommandMeta>}
@@ -108,13 +95,7 @@ const SUBCOMMANDS = new Map([
   ],
 ]);
 
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-
 /**
- * Read the installed mandrel version from the root package.json.
- *
  * @returns {string}
  */
 function installedVersion() {
@@ -124,8 +105,6 @@ function installedVersion() {
 }
 
 /**
- * Print the help screen listing all subcommands with descriptions.
- *
  * @param {(s: string) => void} [write]
  */
 function printHelp(write = (s) => process.stdout.write(s)) {
@@ -144,8 +123,6 @@ function printHelp(write = (s) => process.stdout.write(s)) {
 }
 
 /**
- * Suggest the closest known subcommand name for a typo (Levenshtein-1).
- *
  * @param {string} input
  * @returns {string | undefined}
  */
@@ -157,8 +134,7 @@ function suggest(input) {
 }
 
 /**
- * Compute Levenshtein edit distance between two strings (capped at 3 for
- * performance — we only care about small distances).
+ * Edit distance; returns 4 early when lengths differ by more than 3.
  *
  * @param {string} a
  * @param {string} b
@@ -182,19 +158,11 @@ function levenshtein(a, b) {
   return prev[b.length];
 }
 
-/**
- * Universal flags that all subcommands accept and that bypass per-subcommand
- * flag validation. Subcommands may handle these themselves internally.
- */
+/** Accepted by every subcommand, bypassing per-subcommand validation. */
 const UNIVERSAL_FLAGS = new Set(['--help', '-h']);
 
 /**
- * Validate the argv array against the known flags for a subcommand.
- * Returns null when all flags are known; an error message string when an
- * unknown flag is detected. Values following `=` or the next positional are
- * allowed — only the flag name prefix is checked.
- *
- * Universal flags (--help, -h) are always allowed and bypass this check.
+ * Only flag names are checked (`--flag=value` is split).
  *
  * @param {string} subName
  * @param {Set<string>} knownFlags
@@ -204,7 +172,6 @@ const UNIVERSAL_FLAGS = new Set(['--help', '-h']);
 function findUnknownFlag(subName, knownFlags, argv) {
   for (const arg of argv) {
     if (!arg.startsWith('-')) continue;
-    // Strip value portion for `--flag=value` form.
     const flagName = arg.includes('=') ? arg.slice(0, arg.indexOf('=')) : arg;
     if (UNIVERSAL_FLAGS.has(flagName)) continue;
     if (!knownFlags.has(flagName)) {
@@ -219,14 +186,9 @@ function findUnknownFlag(subName, knownFlags, argv) {
   return null;
 }
 
-// ---------------------------------------------------------------------------
-// Dispatch
-// ---------------------------------------------------------------------------
-
 const args = process.argv.slice(2);
 const sub = args[0];
 
-// --- Top-level flags (no subcommand) ---
 if (!sub || sub === '--help' || sub === '-h') {
   printHelp();
   process.exit(0);
@@ -237,7 +199,6 @@ if (sub === '--version') {
   process.exit(0);
 }
 
-// --- Subcommand lookup ---
 const meta = SUBCOMMANDS.get(sub);
 if (!meta) {
   const subcommandList = [...SUBCOMMANDS.keys()].join(', ');
@@ -250,7 +211,6 @@ if (!meta) {
   process.exit(1);
 }
 
-// --- Unknown-flag rejection ---
 const subArgv = args.slice(1);
 const unknownFlagError = findUnknownFlag(sub, meta.knownFlags, subArgv);
 if (unknownFlagError) {
@@ -258,7 +218,6 @@ if (unknownFlagError) {
   process.exit(1);
 }
 
-// --- Load and dispatch ---
 const subFile = path.resolve(__dirname, '..', 'lib', 'cli', `${sub}.js`);
 const subFileUrl = pathToFileURL(subFile).href;
 

package/bin/postinstall.js

@@ -2,38 +2,11 @@
 // bin/postinstall.js — best-effort `.agents/` materializer on install.
 
 /**
- * Published-package `postinstall` hook.
- *
- * Runs `mandrel sync` to materialize the package payload into the consumer's
- * `./.agents/` working copy. This hook is **best-effort by contract** (Tech
- * Spec #3459 "Postinstall safety", Feature #3461): it MUST exit 0 even when
- * the sync fails, so that `--ignore-scripts` installs, sandboxed CI, or a
- * transient copy error degrade to the `mandrel doctor`-detected
- * "not materialized" state rather than failing the consumer's install.
- *
- * On any failure it logs a single actionable hint — "run `mandrel sync`" —
- * and exits 0. It performs nothing beyond the local file copy that
- * `mandrel sync` itself does: no network, no shell, no writes outside
- * `./.agents/`.
- *
- * **Source-checkout guard (Story #3489, fixed in #3580).** In the Mandrel
- * framework repo itself, `./.agents/` is not a regenerated working copy — it
- * *is* the committed product, and `mandrel sync` would clobber that source of
- * truth with a copy of `node_modules/mandrel/.agents/`. Today the
- * repo `.npmrc` (`ignore-scripts=true`) masks this, but a contributor running
- * `npm install --ignore-scripts=false` (or a tool that re-enables scripts)
- * would overwrite the source tree. To make the guard intrinsic rather than
- * config-dependent, the hook detects the source checkout and no-ops (exit 0)
- * without invoking the materializer. Consumer installs (where the package is
- * a dependency under `node_modules/`) are unaffected and still materialize
- * `.agents/` as before — see `isSourceCheckout` for the two signals used to
- * tell them apart.
- *
- * Injectable seams (used by tests/cli/postinstall.test.js):
- *   - `sync`             — replaces the real `runSync` from lib/cli/sync.js
- *   - `isSourceCheckout` — replaces the source-checkout detector
- *   - `writeErr`         — replaces process.stderr.write
- *   - `exit`             — replaces process.exit
+ * Runs `mandrel sync` on install. Best-effort by contract: always exits 0 so
+ * `--ignore-scripts`, sandboxed CI, or a copy error degrade to the
+ * doctor-detected "not materialized" state instead of failing the install.
+ * In the framework's own source checkout it no-ops, since `.agents/` there is
+ * the committed product and a sync would clobber it.
  */
 
 import nodeFs from 'node:fs';
@@ -47,36 +20,13 @@ const HINT =
   'mandrel: could not materialize ./.agents/ during install — run `mandrel sync` to finish setup.\n';
 
 /**
- * Detect whether this hook is running inside the Mandrel framework source
- * checkout (as opposed to a consumer project that depends on the package).
- *
- * Two complementary, fail-safe signals — both biased toward running the sync
- * (the safe default for a consumer) — tell the two cases apart:
- *
- * 1. **`node_modules` path guard (primary).** When the package is installed as
- *    a dependency this module lives at
- *    `<consumer>/node_modules/mandrel/bin/postinstall.js`, so its own
- *    resolved path contains a `node_modules` segment. That is true *by
- *    construction* for every dependency install and needs no env var, so a
- *    `node_modules` ancestor is treated as an unambiguous consumer install →
- *    return `false` (run the sync). This is the signal the original guard
- *    (Story #3489) was missing: it resolved the package's **own**
- *    `package.json` (always named `mandrel`) instead of the consumer
- *    root, so it misfired on every consumer install and skipped the sync
- *    (Story #3580).
- *
- * 2. **`INIT_CWD`-rooted name check (source-repo signal).** Outside
- *    `node_modules`, resolve the **invoking project root** and compare its
- *    `package.json#name` to `mandrel`. npm sets `INIT_CWD` to the
- *    directory where `npm install` was invoked — the framework repo root when
- *    a contributor installs the framework itself. When `INIT_CWD` is unset
- *    (e.g. the hook is run directly via `node`, outside npm), fall back to the
- *    module-relative repo root (`bin/postinstall.js` sits one directory below
- *    it), which still resolves to the source repo's own `package.json`.
- *
- * Fails safe: any read/parse error returns `false` (treat as a consumer
- * install and let the best-effort sync run), so a malformed or missing
- * `package.json` never strands a consumer without their `.agents/` payload.
+ * Two signals, both biased toward running the sync:
+ * 1. A `node_modules` segment in this module's own path means a dependency
+ *    install — never the source repo (reading the package's own
+ *    `package.json` would always say `mandrel`).
+ * 2. Otherwise compare the invoking root's `package.json#name` (`INIT_CWD`,
+ *    or the module-relative repo root outside npm) to `mandrel`.
+ * Any read/parse error returns `false`.
  *
  * @param {{ fs?: typeof nodeFs, initCwd?: string, moduleUrl?: string }} [opts]
  * @returns {boolean} `true` when running in the `mandrel` source repo.
@@ -88,13 +38,8 @@ export function isSourceCheckout({
 } = {}) {
   try {
     const here = path.dirname(fileURLToPath(moduleUrl));
-    // Installed as a dependency → unambiguously a consumer install, regardless
-    // of what any package.json#name says. Run the sync.
     if (here.split(path.sep).includes('node_modules')) return false;
 
-    // Source checkout: resolve the invoking project root (the dir where
-    // `npm install` ran) and compare its package name. Fall back to the
-    // module-relative repo root when npm did not set INIT_CWD.
     const root = initCwd || path.join(here, '..');
     const pkg = JSON.parse(
       fs.readFileSync(path.join(root, 'package.json'), 'utf8'),
@@ -106,30 +51,10 @@ export function isSourceCheckout({
 }
 
 /**
- * Run the materializer, swallowing any failure into an exit-0 hint.
- *
- * When invoked inside the framework source checkout the hook short-circuits
- * to a clean exit 0 *before* touching the materializer (Story #3489), so the
- * committed `.agents/` source is never overwritten — even under
- * `--ignore-scripts=false`.
- *
- * `runSync` calls its injected `exit` with a non-zero code when the package
- * is not resolvable (the common `--ignore-scripts`-adjacent failure). We
- * intercept that here instead of letting it propagate to `process.exit`,
- * and we also catch any thrown error (e.g. a mid-copy filesystem fault), so
- * the postinstall lifecycle can never fail the consumer's `npm install`.
- *
- * **Destination root (Story #3584).** `runSync` derives its destination from
- * `process.cwd()`, but npm runs a dependency's lifecycle scripts with cwd set
- * to the **package's own directory** (`node_modules/mandrel`), not
- * the consumer project root. Left unset, the materializer would copy
- * `.agents/` back onto the package's own payload and the consumer's project
- * root would get nothing. We pass `runSync` a `cwd` resolving to `INIT_CWD` —
- * the directory where `npm install` was invoked (the consumer root) — falling
- * back to `process.cwd()` only when the hook runs outside npm (`INIT_CWD`
- * unset). This is scoped to the postinstall path: the manual `mandrel sync` /
- * `mandrel update` paths already run from the project root and keep
- * `runSync`'s default `process.cwd()` behaviour.
+ * Both a non-zero `exit` from `runSync` and a thrown error become the exit-0
+ * hint. The destination is `INIT_CWD` (the consumer root), because npm runs
+ * lifecycle scripts with cwd set to `node_modules/mandrel` — syncing there
+ * would copy the payload onto itself.
  *
  * @param {{
  *   sync?: typeof runSync,
@@ -148,9 +73,7 @@ export function runPostinstall({
   writeErr = (s) => process.stderr.write(s),
   exit = (code) => process.exit(code),
 } = {}) {
-  // Source-checkout guard (Story #3489): never materialize over the
-  // framework's own committed `.agents/` source. No hint — this is the
-  // expected, correct no-op in the framework repo, not a degraded state.
+  // Expected no-op in the framework repo, so no hint.
   if (detectSource()) {
     exit(0);
     return { exitCode: 0, hinted: false, skipped: true };
@@ -158,18 +81,8 @@ export function runPostinstall({
 
   let syncFailed = false;
   try {
-    // No argv is forwarded: the install-time materialization is a plain,
-    // overwrite-in-place copy. The `mandrel sync` tokens in the package.json
-    // `postinstall` string document intent (and are what the hint points
-    // operators at); they are not flags this hook needs to honor.
     sync({
-      // Resolve the destination from INIT_CWD (the consumer project root,
-      // where `npm install` ran), not the package dir npm makes cwd during
-      // the postinstall lifecycle (Story #3584). Fall back to process.cwd()
-      // outside npm, when INIT_CWD is unset.
       cwd: () => initCwd || process.cwd(),
-      // Best-effort: never let sync's own non-zero exit terminate the
-      // install. Record the failure and fall through to the exit-0 hint.
       exit: (code) => {
         if (code !== 0) syncFailed = true;
       },
@@ -182,13 +95,11 @@ export function runPostinstall({
     writeErr(HINT);
   }
 
-  // Always succeed: the install must not fail on a best-effort sync.
   exit(0);
   return { exitCode: 0, hinted: syncFailed, skipped: false };
 }
 
-// Run when invoked directly as the postinstall hook (not when imported by a
-// test). `process.argv[1]` is the resolved path to this file under npm.
+// Only when run as the hook, not when imported by a test.
 const invokedDirectly = process.argv[1]?.endsWith('postinstall.js');
 if (invokedDirectly) {
   runPostinstall();

package/docs/CHANGELOG.md

@@ -15,6 +15,38 @@ All notable changes to this project will be documented in this file.
 -->
 <!-- markdownlint-disable-file MD004 MD012 MD037 -->
 
+## [2.62.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.61.0...mandrel-v2.62.0) (2026-09-18)
+
+
+### Fixed
+
+* **close:** arm auto-merge on a merge-queue-protected base ([#5395](https://github.com/dsj1984/mandrel/issues/5395)) ([#5396](https://github.com/dsj1984/mandrel/issues/5396)) ([6d739ea](https://github.com/dsj1984/mandrel/commit/6d739eadb8ae00bedeb7279b1a765c3e0cc5791e))
+
+## [2.61.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.60.0...mandrel-v2.61.0) (2026-09-18)
+
+
+### ⚠ BREAKING CHANGES
+
+* these .agentrc keys are removed and now fail validation (mandrel update strips them first): delivery.quality.gates.lint, delivery.quality.gates.lighthouse, delivery.quality.gateScoping, delivery.quality.formatAutofix, delivery.quality.codingGuardrails, delivery.quality.baselineEpsilon, delivery.quality.autoRefresh.crapJumpCap, delivery.quality.autoRefresh.scope, delivery.quality.gates.crap.friction, delivery.quality.gates.crap.refreshTag, delivery.quality.gates.crap.refreshTimeoutMs, delivery.quality.gates.crap.incrementalCoverage.enabled, delivery.quality.gates.maintainability.refreshTag, delivery.quality.gates.maintainability.refreshTimeoutMs, delivery.quality.gates.duplication.refreshTimeoutMs, delivery.quality.gates.coverage.timeoutMs, delivery.quality.gates.mutation.strykerConfigPath, delivery.ci.watch, delivery.execution.timeoutMs, delivery.execution.requireCreditedCapture, delivery.tempRetention.staleDays, delivery.mergeWatch.intervalSeconds, delivery.mergeWatch.updateAttempts, delivery.review, delivery.feedbackLoop.frictionWindowDays, delivery.auditToStories, delivery.codeReview.providerConfig, delivery.codeReview.maxFixAttempts, github.defaultTimeoutMs, planning.memoryPool. The lint and lighthouse baseline kinds are gone from check-baselines.
+* removed from the shipped payload (now repo-root scripts/, not distributed): .agents/scripts/test-isolate.js, .agents/scripts/check-test-portability.js, .agents/scripts/install-matrix-assert.js, .agents/scripts/check-audit-attribution.js, .agents/scripts/check-pinned-override-notes.js, .agents/scripts/check-action-pinning.js, .agents/scripts/check-baseline-drift.js, .agents/scripts/check-baseline-scope.js, .agents/scripts/check-generated-validator.js, .agents/scripts/check-knip-entries.js, .agents/scripts/check-lifecycle-lint.js, .agents/scripts/check-schema-references.js, .agents/scripts/check-workflow-citations.js, .agents/scripts/check-workflow-cli-lint.js, .agents/scripts/check-workflow-timeouts.js, .agents/scripts/lint-label-vocabulary.js, .agents/scripts/provision-git-hooks.js, .agents/scripts/run-coverage.js, .agents/scripts/run-lint.js, .agents/scripts/run-test-profile.js, .agents/scripts/run-verify.js, .agents/scripts/update-dead-exports-baseline.js, .agents/scripts/prune-baseline-orphans.js, .agents/scripts/post-structured-comment.js, plus .agents/scripts/lib/test-isolate/, .agents/scripts/lib/test-profile/, .agents/scripts/lib/dynamic-workflow/ and the rules .agents/rules/known-tooling-behavior.md, .agents/rules/test-seams.md and .agents/rules/orchestration-error-handling.md (now docs/contributing/).
+
+### Added
+
+* adopt a contract-once comment policy and trim source comments to it ([#5384](https://github.com/dsj1984/mandrel/issues/5384)) ([#5391](https://github.com/dsj1984/mandrel/issues/5391)) ([13b98de](https://github.com/dsj1984/mandrel/commit/13b98de474019fd61935f8e95b855b8c6f923d7d))
+* cut the unused .agentrc config surface and migrate consumers off it ([#5382](https://github.com/dsj1984/mandrel/issues/5382)) ([#5389](https://github.com/dsj1984/mandrel/issues/5389)) ([660a71c](https://github.com/dsj1984/mandrel/commit/660a71cf5b1acd77a44a4460c4424e43746bf738))
+* stop close re-running the suite after base-sync and failing at pre-push on CRAP scope ([#5378](https://github.com/dsj1984/mandrel/issues/5378)) ([#5379](https://github.com/dsj1984/mandrel/issues/5379)) ([83bda93](https://github.com/dsj1984/mandrel/commit/83bda93942a909bd18307ae0dedabf3c814768af))
+
+
+### Fixed
+
+* make the full-suite lock and close's suite spawns signal-safe, bounded and visible ([#5377](https://github.com/dsj1984/mandrel/issues/5377)) ([#5387](https://github.com/dsj1984/mandrel/issues/5387)) ([e3a32cb](https://github.com/dsj1984/mandrel/commit/e3a32cb6f773892b8cbfd0d4b9bbc81256038777))
+* move contributor-only tooling out of the .agents payload ([#5381](https://github.com/dsj1984/mandrel/issues/5381)) ([#5388](https://github.com/dsj1984/mandrel/issues/5388)) ([984352b](https://github.com/dsj1984/mandrel/commit/984352b0cdcdd5707c8ed0c49e728bc9875634c6))
+
+
+### Changed
+
+* make each close-path merge decision once ([#5383](https://github.com/dsj1984/mandrel/issues/5383)) ([#5390](https://github.com/dsj1984/mandrel/issues/5390)) ([027da2e](https://github.com/dsj1984/mandrel/commit/027da2efe4719c0dc2a6a5065afc710bd0f796a0))
+
 ## [2.60.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.59.0...mandrel-v2.60.0) (2026-09-18)