mandrel 2.15.0 → 2.17.0

package/.agents/scripts/plan-run-epilogue.js

@@ -27,9 +27,23 @@ const CLI_OPTIONS = {
 
 /**
  * @param {string[]} [argv]
+ * @param {{
+ *   resolveConfigImpl?: typeof resolveConfig,
+ *   createProviderImpl?: typeof createProvider,
+ *   runPlanRunEpilogueImpl?: typeof runPlanRunEpilogue,
+ *   logger?: { info: Function, warn: Function },
+ * }} [deps] Injectable seams; every entry defaults to the real
+ *   implementation (`.agents/rules/test-seams.md` rules 1-2), so the CLI path
+ *   and every production caller are unchanged.
  * @returns {Promise<object>}
  */
-export async function main(argv = process.argv.slice(2)) {
+export async function main(argv = process.argv.slice(2), deps = {}) {
+  const {
+    resolveConfigImpl = resolveConfig,
+    createProviderImpl = createProvider,
+    runPlanRunEpilogueImpl = runPlanRunEpilogue,
+    logger = Logger,
+  } = deps;
   const { values } = parseArgs({
     args: argv,
     options: CLI_OPTIONS,
@@ -44,8 +58,8 @@ export async function main(argv = process.argv.slice(2)) {
     typeof values.cwd === 'string' && values.cwd.trim()
       ? values.cwd.trim()
       : process.cwd();
-  const config = resolveConfig({ cwd });
-  const provider = createProvider(config);
+  const config = resolveConfigImpl({ cwd });
+  const provider = createProviderImpl(config);
 
   // Story #4540 retired the `--run <planRunId>` label-resolution branch
   // along with the label itself. The epilogue is keyed on the delivered id
@@ -58,16 +72,16 @@ export async function main(argv = process.argv.slice(2)) {
 
   const planRunId = `adhoc-${[...stories].sort((a, b) => a - b).join('-')}`;
 
-  const result = await runPlanRunEpilogue({
+  const result = await runPlanRunEpilogueImpl({
     planRunId,
     stories,
     provider,
     config,
     cwd,
   });
-  warnOnUnresolvedBase(result);
-  warnOnEmptyRollup(result);
-  Logger.info(JSON.stringify(result));
+  warnOnUnresolvedBase(result, logger);
+  warnOnEmptyRollup(result, logger);
+  logger.info(JSON.stringify(result));
   if (result.errors?.length) {
     process.exitCode = 1;
   }
@@ -84,15 +98,16 @@ export async function main(argv = process.argv.slice(2)) {
  * roster is still useful.
  *
  * @param {object} result - `runPlanRunEpilogue` envelope.
+ * @param {{ warn: Function }} [logger]
  * @returns {void}
  */
-function warnOnUnresolvedBase(result) {
+function warnOnUnresolvedBase(result, logger = Logger) {
   const roster = (result?.results ?? []).find(
     (r) => r?.kind === 'audit-roster',
   );
   const base = roster?.baseResolution;
   if (base?.resolved !== false) return;
-  Logger.warn(
+  logger.warn(
     `⚠️  Combined landed diff unavailable — the pre-run base sha could not be ` +
       `resolved against \`${base.baseRef}\`: ${base.reason}\n` +
       `    changedFiles is null (NOT an empty set). Determine the run diff by ` +
@@ -117,14 +132,15 @@ function warnOnUnresolvedBase(result) {
  * rather than asserting either reading.
  *
  * @param {object} result - `runPlanRunEpilogue` envelope.
+ * @param {{ warn: Function }} [logger]
  * @returns {void}
  */
-function warnOnEmptyRollup(result) {
+function warnOnEmptyRollup(result, logger = Logger) {
   const rollup = (result?.results ?? []).find(
     (r) => r?.kind === 'follow-up-rollup',
   );
   if (!rollup?.emptyRollupSuspect) return;
-  Logger.warn(
+  logger.warn(
     `⚠️  0 friction signals across ${rollup.storyCount} Stories — telemetry may not ` +
       `have fired.\n` +
       `    An empty roll-up is NOT evidence of a clean run: it is the same output a ` +

package/.agents/scripts/resolve-doc-tiers.js

@@ -50,24 +50,34 @@ export function parseArgv(argv = []) {
  * Top-level CLI entry. Exported so tests can drive it against a fixture root
  * with an injected sink and config.
  *
+ * The optional final `deps` parameter is the module's injectable seam
+ * (`.agents/rules/test-seams.md` rules 1-2): every entry defaults to the real
+ * implementation, so the CLI path below — and any production caller — needs no
+ * configuration change.
+ *
  * @param {{
  *   argv?: string[],
  *   config?: object,
  *   root?: string,
  *   stdout?: { write: (s: string) => void },
  * }} [opts]
+ * @param {{
+ *   resolveConfigImpl?: typeof resolveConfig,
+ *   resolveDocTiersImpl?: typeof resolveDocTiers,
+ * }} [deps]
  * @returns {Promise<number>} always 0
  */
-export async function runCli({
-  argv = process.argv.slice(2),
-  config,
-  root,
-  stdout = process.stdout,
-} = {}) {
+export async function runCli(
+  { argv = process.argv.slice(2), config, root, stdout = process.stdout } = {},
+  {
+    resolveConfigImpl = resolveConfig,
+    resolveDocTiersImpl = resolveDocTiers,
+  } = {},
+) {
   const { rootPath } = parseArgv(argv);
-  const resolvedConfig = config ?? resolveConfig();
+  const resolvedConfig = config ?? resolveConfigImpl();
   const resolvedRoot = root ?? rootPath ?? PROJECT_ROOT;
-  const result = resolveDocTiers(resolvedConfig, { root: resolvedRoot });
+  const result = resolveDocTiersImpl(resolvedConfig, { root: resolvedRoot });
   stdout.write(`${JSON.stringify(result, null, 2)}\n`);
   return 0;
 }

package/.agents/scripts/single-story-close.js

@@ -90,6 +90,10 @@ import { runAsCli } from './lib/cli-utils.js';
 import { formatCliError } from './lib/error-redactor.js';
 import { Logger } from './lib/Logger.js';
 import { emitTerminalFriction } from './lib/observability/runtime-friction.js';
+import {
+  failedTerminalFor,
+  gatesForFailedPhase,
+} from './lib/orchestration/single-story-close/failed-terminal.js';
 import { enableAutoMergeWith } from './lib/orchestration/single-story-close/phases/auto-merge.js';
 import {
   buildSyncFailureCommentBody,
@@ -102,10 +106,8 @@ import {
 } from './lib/orchestration/single-story-close/phases/code-review.js';
 import { ensurePullRequestWith } from './lib/orchestration/single-story-close/phases/pull-request.js';
 import {
-  buildTerminalEnvelope,
   emitTerminalEnvelope,
   exitCodeForTerminal,
-  NEXT_COMMANDS,
 } from './lib/orchestration/story-deliver-terminal.js';
 
 // Story #2990 moved the `gh`-spawn boundary into the `lib/gh-exec.js`
@@ -118,9 +120,13 @@ export const enableAutoMerge = enableAutoMergeWith;
 
 // Re-export pure helpers verbatim — they don't touch `execFileSync`
 // or any URL-mocked module, so the phase exports work unmodified.
+// `gatesForFailedPhase` now lives beside the envelope it feeds
+// (`single-story-close/failed-terminal.js`); it is re-exported here so the
+// CLI's public surface is unchanged by that move.
 export {
   buildStoryReviewCrossRefBody,
   buildSyncFailureCommentBody,
+  gatesForFailedPhase,
   handleSyncFailure,
   parsePrNumber,
   runStoryScopeReview,
@@ -134,95 +140,6 @@ export async function runSingleStoryClose(opts) {
   return mod.runSingleStoryClose(opts);
 }
 
-/**
- * The close pipeline's phase order, as `setPhase` walks it. Only used to
- * decide whether a gate had already run when a later phase died.
- */
-const PHASE_ORDER = Object.freeze([
-  'init',
-  'wrong-tree-guard',
-  'close-validation',
-  'base-sync',
-  'push',
-  'pull-request',
-  'code-review',
-  'auto-merge',
-  'confirm-merge',
-  'post-land',
-  'done',
-]);
-
-/** Each reported gate and the pipeline phase that decides it. */
-const GATE_PHASES = Object.freeze([
-  ['validation', 'close-validation'],
-  ['baseSync', 'base-sync'],
-  ['codeReview', 'code-review'],
-]);
-
-/**
- * Report every gate's outcome for a run that died at `phase`.
- *
- * The schema's contract: "A gate the run skipped … reports `skipped` rather
- * than being omitted, so a missing gate is never mistaken for a passing one."
- * The previous shape named only the gate that died and omitted the rest
- * entirely — exactly the ambiguity the contract forbids.
- *
- * Reconstructed from the phase order, which is sound because the pipeline is
- * strictly sequential: reaching phase N means every gate before it completed.
- * A gate whose phase the run never reached is `skipped`; one the operator
- * turned off via `--skip-validation` / `--skip-sync` is `skipped` too (it did
- * not pass — it never ran).
- *
- * @param {string} phase The phase the run died in.
- * @param {{ skipValidation?: boolean, skipSync?: boolean }} args Parsed CLI args.
- * @returns {Record<string, 'passed'|'failed'|'skipped'>}
- */
-export function gatesForFailedPhase(phase, args = {}) {
-  const skipped = { validation: args.skipValidation, baseSync: args.skipSync };
-  const failedAt = PHASE_ORDER.indexOf(phase);
-  const gates = {};
-  for (const [gate, gatePhase] of GATE_PHASES) {
-    const at = PHASE_ORDER.indexOf(gatePhase);
-    if (gatePhase === phase) gates[gate] = 'failed';
-    else if (failedAt < 0 || at > failedAt) gates[gate] = 'skipped';
-    else gates[gate] = skipped[gate] ? 'skipped' : 'passed';
-  }
-  return gates;
-}
-
-/**
- * Build the `failed` terminal for a phase that crashed.
- *
- * The runner deliberately throws rather than returning a failure (a red gate
- * must not look like a return value), so without this the most common
- * non-happy ending — a failing close-validation gate — would emit **no
- * envelope at all**, exiting 1 with only a stderr line while the workflow
- * docs promise the agent a `failed` envelope naming the phase. Every close
- * invocation emits exactly one envelope; this is the path that keeps that
- * true when a phase dies.
- *
- * `err.closePhase` is tagged by the runner's phase tracker.
- *
- * @param {unknown} err
- * @returns {object|null} A validated envelope, or null when even the story id
- *   is unknown (a usage error — there is nothing to report an envelope about).
- */
-function failedTerminalFor(err) {
-  const phase = err?.closePhase ?? 'init';
-  const args = parseSprintArgs();
-  const storyId = Number(args.storyId);
-  if (!Number.isInteger(storyId) || storyId <= 0) return null;
-  return buildTerminalEnvelope({
-    storyId,
-    status: 'failed',
-    phase,
-    gates: gatesForFailedPhase(phase, args),
-    failure: { reason: String(err?.message ?? err) },
-    nextCommand: NEXT_COMMANDS.recover(storyId),
-    elapsedSeconds: 0,
-  });
-}
-
 /**
  * CLI entry — resolves the process exit code from the terminal envelope's
  * status rather than from a thrown/not-thrown distinction, so `pending`
@@ -234,7 +151,7 @@ async function main() {
     const outcome = await runSingleStoryClose();
     return exitCodeForTerminal(outcome?.terminal ?? { status: 'failed' });
   } catch (err) {
-    const terminal = failedTerminalFor(err);
+    const terminal = failedTerminalFor(err, parseSprintArgs());
     if (!terminal) throw err;
     // Mirror runAsCli's default error line (which this catch pre-empts) so the
     // human-facing failure text is unchanged, then emit the envelope.

package/.agents/scripts/update-crap-baseline.js

@@ -13,6 +13,7 @@ import {
 } from './lib/config-resolver.js';
 import { loadCoverage } from './lib/coverage-utils.js';
 import {
+  checkResolutionFloor,
   resolveEscomplexVersion,
   resolveTsTranspilerVersion,
   scanAndScore,
@@ -71,6 +72,7 @@ async function main() {
   const crap = getQuality(config).crap;
   const targetDirs = Array.isArray(crap.targetDirs) ? crap.targetDirs : [];
   const requireCoverage = crap.requireCoverage !== false;
+  const minMethodResolutionRate = crap.minMethodResolutionRate ?? 0.75;
   const coveragePath =
     args.coveragePath ?? crap.coveragePath ?? 'coverage/coverage-final.json';
   const baselinePath = args.baselinePath ?? getBaselines(config).crap.path;
@@ -117,6 +119,7 @@ async function main() {
       scannedFiles,
       skippedFilesNoCoverage,
       skippedMethodsNoCoverage,
+      resolution,
     } = await scanAndScore({
       targetDirs,
       coverage,
@@ -137,6 +140,16 @@ async function main() {
         `[CRAP] Skipped ${skippedMethodsNoCoverage} method(s) whose per-method coverage was unresolved.`,
       );
     }
+    if (resolution) {
+      Logger.info(
+        `[CRAP] Method resolution: ${resolution.resolvedMethods}/${resolution.joinableMethods} ` +
+          `(${(resolution.rate * 100).toFixed(1)}%) in files with coverage.`,
+      );
+    }
+    // Fail closed BEFORE the service persists anything — a thin baseline is
+    // never written and then apologised for.
+    const refusal = checkResolutionFloor(resolution, minMethodResolutionRate);
+    if (refusal) throw new Error(refusal);
 
     return (rows ?? []).filter(
       (r) => typeof r?.crap === 'number' && Number.isFinite(r.crap),

package/.agents/workflows/helpers/deliver-light.md

@@ -27,15 +27,36 @@ over-scope work silently.
 Two callers, one gate: whichever door you arrived through, the suitability gate
 below is the decision. A `/plan` Gate #1 suggestion is a *suggestion* — it is
 read against seed-time signals (`DELIVER_LIGHT_SUGGESTION_CEILINGS`: artifacts,
-risk hits, sensitive-path classes), while the gate here is read against a
-predicted *shape* (`STORY_SHAPE_CEILINGS`: `maxChanges`, `maxAcceptance`). They
-are deliberately two different checks, so the gate still runs after a confirm.
+risk hits, sensitive-path classes), while the gate here is read against the
+predicted work's *effort and risk* (`STORY_SHAPE_CEILINGS`: change kinds,
+magnitude, uncertainty, deployable span). They are deliberately two different
+checks, so the gate still runs after a confirm.
+
+## Scope by effort, not by artifact count {#scope-by-effort}
+
+**Counting the footprint is the wrong axis.** Three identical one-line edits
+across three files is trivial work with a high count; a 200-line rewrite of one
+module is a single change. The axes are therefore effort and risk: distinct
+change **kinds** (N instances of one mechanical edit is one kind at N sites), a
+coarse **magnitude** bucket, and **uncertainty** — is the shape determined by
+the request, or does it still need the design decisions `/plan` exists to
+resolve?
+
+Because the predicted footprint is a *declaration* — a guess, and a gameable one
+— this gate is deliberately **coarse**: it rejects clearly-epic work only
+(multiple deployables, a migration plus its consumers, an explicit
+multi-capability enumeration). Size is enforced where ground truth is available:
+the diff backstop in step 4. Do not talk yourself past that one.
+
+Sensitivity is the exception and stays absolute: a footprint touching an auth,
+crypto, billing, or migration class routes `full` however small or mechanical.
 
 ## Four invariants (do not skip one)
 
 1. **Suitability gate.** The prompt's predicted footprint is judged by the
-   shared shape machinery (`deriveStoryShape` / `deriveChangeLevel`) **and** a
-   ledgered model verdict with a recorded reason. Both must agree on `lite`.
+   shared effort/risk machinery (`deriveStoryShape` / `deriveChangeLevel`)
+   **and** a ledgered model verdict with a recorded reason. Both must agree on
+   `lite`.
 2. **Over-scope stops — it never hard-fails.** An over-ceiling prompt STOPS and
    asks the operator to escalate to `/plan` or proceed light. Under `--yes` it
    fails closed to an **`escalated` terminal envelope** that ends the session
@@ -50,12 +71,16 @@ are deliberately two different checks, so the gate still runs after a confirm.
 ## Procedure
 
 1. **Predict + gate.** Form the predicted footprint (new files, edited files,
-   acceptance count) and your ledgered verdict (a recorded reason for `lite`),
-   then run the gate:
+   acceptance count), judge its effort honestly (`--kinds` / `--magnitude` /
+   `--uncertainty`, per § Scope by effort), and record your ledgered verdict (a
+   recorded reason for `lite`), then run the gate — it documents every flag
+   itself, so run it with `--help` rather than guessing:
 
    ```bash
    node .agents/scripts/deliver-light.js --prompt "<prompt>" \
      --creates <csv> --refactors <csv> --acceptance <n> \
+     --kinds <csv> --magnitude trivial|moderate|substantial \
+     --uncertainty determined|needs-design \
      --route lite --reason "<why this is trivial>" [--amends '#<id>'] [--yes]
    ```
 
@@ -106,7 +131,8 @@ are deliberately two different checks, so the gate still runs after a confirm.
 
    Exit `3` (`blocked: true`) means the landed diff exceeds the light ceilings
    (file count or a sensitive-path class). STOP, flip `agent::blocked`, and
-   escalate to `/plan` — do not land.
+   escalate to `/plan` — do not land. This is the pass that actually bounds
+   size, which is why the prediction gate above can afford to be coarse.
 
 5. **Close and land (same engine).** Exactly [`/deliver`](../deliver.md)'s close:
 

package/.agents/workflows/helpers/plan-reference.md

@@ -49,9 +49,9 @@ things make that safe, and both are worth understanding before changing it:
    suggestion that routed you.
 2. **The gate still runs.** The suggestion is read against seed-time ceilings
    (`DELIVER_LIGHT_SUGGESTION_CEILINGS` — artifacts, risk hits, sensitive-path
-   classes); the light gate is read against a predicted shape
-   (`STORY_SHAPE_CEILINGS` — `maxChanges`, `maxAcceptance`). Two different
-   checks on purpose, so a confirm is not a bypass.
+   classes); the light gate is read against the predicted work's effort and risk
+   (`STORY_SHAPE_CEILINGS` — change kinds, magnitude, uncertainty, deployable
+   span). Two different checks on purpose, so a confirm is not a bypass.
 
 **When the light gate answers `ask-operator`**, the two ceiling sets disagreed.
 Resume `/plan` at step 2 (Author) **in this same session** — the interrogation
@@ -63,6 +63,26 @@ is terminal and requires a fresh session. The rule that separates the two, and
 why it must not be flattened into symmetry:
 [`deliver-light.md` § Why the two directions differ](deliver-light.md).
 
+## Gate #1 → the `/prototype` offer (`uiSurface`)
+
+`complexitySignals.uiSurface` is the second advisory Gate #1 offer, and the
+weaker of the two on purpose: it carries **no routing authority and adds no
+gate**. Both halves are derived from observables already in the checkout — the
+`hasWebSurface` applicability predicate the `target: "web"` audit lenses gate
+on, and whether any predicted path matches a web lens `filePattern` registered
+in `audit-rules.json`. There is no configuration key to set: a project with no
+rendered frontend resolves falsey and the offer never fires.
+
+When it does fire, **name [`/prototype`](../prototype.md) and stop there.**
+`/plan` must never invoke it — operator invocation is the entire design, because
+the value is a human looking at a layout before its UI acceptance criteria are
+frozen.
+
+**Under `--yes` the offer is recorded and planning proceeds** — no reroute, no
+prototype written, no gate raised. This is exactly how `deliverLightSuggestion`
+behaves unattended, and for the same reason: an unattended run has nobody to
+review an artifact, so recording the offer is the whole of the right behaviour.
+
 ## Shape-derived complexity routing (`complexitySignals`)
 
 Complexity routes on the **objective shape of the authored work**, never on
@@ -85,9 +105,10 @@ decision:
   (`full`) stands.
 - **Persist backstops the claim deterministically.** After authoring, the
   work has measurable shape, so persist validates the `lite` claim against
-  each Story's own shape — `changes[]` count, acceptance-criteria count,
-  creates-vs-refactors mix, glob-free footprint, and sensitive-path classes,
-  against the framework `STORY_SHAPE_CEILINGS` — and **fails closed to
+  each Story's own shape — distinct change kinds, declared magnitude,
+  uncertainty, deployable/migration span, glob-free footprint, and
+  sensitive-path classes, against the framework `STORY_SHAPE_CEILINGS` (effort
+  and risk, never artifact counts) — and **fails closed to
   `full`** when any Story exceeds them (the refusal is ledgered on the
   checkpoint too). The lite route is **not** licence to drop a
   non-negotiable — every decision's `preserves` field enumerates what still

package/.agents/workflows/plan.md

@@ -82,6 +82,9 @@ this envelope, not the raw seed; an `ask-operator` verdict returns here to
 step 2 with the interrogation intact. Under `--yes` it is recorded and planning
 proceeds — never auto-downgraded to light.
 
+A truthy `complexitySignals.uiSurface` marks a UI-touching plan: name
+[`/prototype`](prototype.md) as an operator option — never invoke it here.
+
 ### 2. Author
 
 **One-shot authoring.** Start from `stories.template.json`; author
@@ -156,8 +159,7 @@ JSON.
 
 In tickets mode persist resolves source ids **envelope-first** and closes each
 as `not_planned` with a comment (default on;
-[detail](helpers/plan-reference.md)). On a stranded persist, re-run the same
-command — never hand-delete issues.
+[detail](helpers/plan-reference.md)).
 
 ## Constraints
 

package/.agents/workflows/prototype.md

@@ -0,0 +1,104 @@
+---
+description: >-
+  Operator-invoked UI prototype pass. Discovers the consumer's design-system
+  SSOT first, then — only after the operator confirms — writes exactly one
+  self-contained HTML file under the gitignored workspace-root temp tree, so a
+  layout can be reviewed before its UI acceptance criteria are authored.
+---
+
+# /prototype [what to prototype]
+
+UI acceptance criteria are otherwise authored blind: "the dashboard shows the
+active runs" says nothing about layout, density, or interaction, so delivery
+resolves those by taste. `/prototype` puts a reviewable artifact in front of the
+operator before the criteria are written.
+
+**Operator-invoked only.** `/plan` may report that a plan touches UI and that
+this command exists; it must never run it. No workflow, gate, or script invokes
+`/prototype` — the whole design rests on the operator asking for it.
+
+## Procedure
+
+### Step 0 — Discover the design-system SSOT (first, before anything is drawn)
+
+You cannot prototype *in the project's visual language* until you have found the
+language. Locate and read the consumer's sources of truth — the same set
+[`/audit-ux-ui`](audit-ux-ui.md) Step 0 mandates:
+
+- **Design tokens / theme** — a `tailwind.config.{js,ts}`, CSS custom properties
+  (`:root { --color-*, --space-* }`), a `theme/` / `tokens/` /
+  `design-system/` directory, or a CSS-in-JS theme object.
+- **Component roster** — the shared component directory (`components/ui/**`, a
+  published design-system package) that raw elements are expected to defer to.
+- **Documented conventions** — `docs/style-guide.md`, plus `docs/web-routes.md`
+  when the surface is a route, whenever they exist in the consumer checkout.
+
+Report what you found — token names, the component roster, the style-guide rules
+— and draw only against that discovered baseline. **No artifact is drawn until
+this step has run.**
+
+### Step 0a — When no design-system SSOT is discoverable
+
+Report the absence explicitly, then emit a **low-fidelity frame**: boxes,
+labels, and hierarchy, in the host's default typography with no colour system.
+Do **not** invent a visual language. A prototype in a palette the project never
+adopted reviews the invention rather than the layout, and the operator cannot
+tell which of the two they are approving.
+
+### Step 1 — Confirm before writing (**hard gate**)
+
+Describe the layout you intend — surfaces, hierarchy, states, and which
+discovered tokens and components it reuses — and **STOP**. Nothing is written to
+disk until the operator confirms; never write silently. This is the disk-write
+policy [`core/idea-refinement`](../skills/core/idea-refinement/SKILL.md) already
+applies to its one-pager.
+
+### Step 2 — Write exactly one self-contained HTML file
+
+On confirm, write **exactly one** self-contained `.html` file — inline CSS, no
+build step, no fetched external assets — under the **gitignored workspace-root
+temp tree** (`temp/prototypes/<slug>.html`). One file, because a prototype is a
+thing to look at, not a codebase to maintain; self-contained, because it has to
+open from disk with no server and no install.
+
+Report the path, and iterate in place on that same file.
+
+### Step 3 — Optional: publish to a host
+
+Host publishing is an **optional upgrade of that same file** and never the
+artifact of record — the file under the temp tree stays authoritative. Publish
+only when the operator asks, and keep the two identical by re-publishing the
+file rather than editing a published copy.
+
+### Step 4 — Carry the review through to the Story
+
+The **default carry-through is a fold into the Story's `## Spec`.** Delivery
+reads the Story body and never the temp tree, so a layout that exists only as a
+temp artifact is a layout delivery cannot see. Record the reviewed decisions —
+surfaces, hierarchy, states, and the named tokens and components — as contract
+prose in `## Spec`, and turn the observable ones into UI acceptance criteria.
+
+**Committing a prototype is opt-in, per Story.** Ask; never default to it. A
+prototype is wrong the moment the real UI ships, and a repository with a
+documentation-freshness gate already carries that failure mode.
+
+## Constraint
+
+- **Nothing reaches disk without a confirm.** Step 1 is a hard gate, not a
+  courtesy.
+- **One file, under the temp tree.** Never a second artifact, never outside the
+  gitignored workspace-root temp tree, and never a committed prototype
+  directory by default.
+- **Never invoked automatically.** `/plan` records the offer and proceeds with
+  planning; no workflow, gate, or script may call this command.
+- **Read-only over the codebase.** The prototype file is the only write. Do not
+  edit application source, tokens, or components to make a prototype render.
+- **Discovered baseline only.** No invented palette, type scale, or component
+  vocabulary when the project defines none.
+
+## See also
+
+- [`/audit-ux-ui`](audit-ux-ui.md) — the same design-system SSOT discovery,
+  applied as a review lens after the UI ships.
+- [`/plan`](plan.md) — where the advisory `complexitySignals.uiSurface` offer
+  surfaces. It names this command; it never runs it.

package/README.md

@@ -181,10 +181,14 @@ dimensions, run model, and how to benchmark a new version.
 
 ## Contributors
 
-Only `.agents/` is distributed to consumers — it ships inside the
-`mandrel` npm package and is materialized into a consumer's
-`./.agents/` directory by `mandrel sync`. Everything else in this
-repository is internal development tooling.
+The published `mandrel` package ships three directories — `.agents/`, `bin/`,
+and `lib/` (see the `files` array in [`package.json`](package.json)).
+`.agents/` is the payload `mandrel sync` materializes into a consumer's
+`./.agents/` directory; `bin/mandrel.js` and its `lib/` implementation stay
+inside `node_modules/mandrel/` and back the `npx mandrel …` CLI used
+throughout this README. Everything else in this repository — `docs/`,
+`tests/`, `.github/`, the root tooling configs — is internal development
+tooling and is not published.
 
 Common commands while developing the framework itself:
 
@@ -204,8 +208,12 @@ Deeper reference material lives in `docs/` rather than inline here:
 - [`.agents/docs/workflows.md`](.agents/docs/workflows.md) — slash-command
   index (auto-generated from the workflow set).
 - [`docs/CHANGELOG.md`](docs/CHANGELOG.md) — release history.
-- [`AGENTS.md`](AGENTS.md) — repository onboarding, the single-package release
-  topology, PAT / npm-token setup, and major-version policy. Releases are
+- [`AGENTS.md`](AGENTS.md) — the repository-level orientation pointer; it
+  links on to [`docs/onboarding.md`](docs/onboarding.md) for the layout,
+  commands, and development standards.
+- [`docs/release-operations.md`](docs/release-operations.md) — the Release
+  Checklist, the Install Matrix release gate, the single-package release
+  topology, PAT / npm-token setup, and the major-version policy. Releases are
   automated by `release-please`: land Conventional Commits on `main` and it
   opens a combined `chore: release main` PR that squash-merges itself once
   CI is green, tags `main`, and publishes `mandrel` to npm.

package/docs/CHANGELOG.md

@@ -2,6 +2,47 @@
 
 All notable changes to this project will be documented in this file.
 
+## [2.17.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.16.0...mandrel-v2.17.0) (2026-07-26)
+
+
+### Added
+
+* **crap:** wire the baseline-refresh projection layer and add CRAP freshness + full-scope drift detection ([#4776](https://github.com/dsj1984/mandrel/issues/4776)) ([#4778](https://github.com/dsj1984/mandrel/issues/4778)) ([8c49a12](https://github.com/dsj1984/mandrel/commit/8c49a12be6ca5ecaca60d8f0bc868f47c9a02534))
+
+
+### Fixed
+
+* **audit-to-stories:** anchor findings to their real primary file (refs [#4781](https://github.com/dsj1984/mandrel/issues/4781)) ([#4782](https://github.com/dsj1984/mandrel/issues/4782)) ([a5794c0](https://github.com/dsj1984/mandrel/commit/a5794c02c3443c39ce116699c311b4cdd8001788))
+* **cli:** drain stdio before exit and settle the audit fan-out per dimension (refs [#4783](https://github.com/dsj1984/mandrel/issues/4783)) ([#4787](https://github.com/dsj1984/mandrel/issues/4787)) ([3422fd5](https://github.com/dsj1984/mandrel/commit/3422fd564773d0e79ac4d16af5bbc5414d06c65b))
+* **crap:** join per-method coverage in original-source coordinates — TS scoring resolves ~5% of methods ([#4775](https://github.com/dsj1984/mandrel/issues/4775)) ([#4777](https://github.com/dsj1984/mandrel/issues/4777)) ([1464c75](https://github.com/dsj1984/mandrel/commit/1464c75c061960aaa9ee1af88175d9706b044c26))
+* **deliver:** keep the terminal envelope alive after the worktree reap (refs [#4784](https://github.com/dsj1984/mandrel/issues/4784)) ([#4791](https://github.com/dsj1984/mandrel/issues/4791)) ([907b7bd](https://github.com/dsj1984/mandrel/commit/907b7bdb951a70a7155e5a9a50afdbea7a81d6a6))
+* **deps:** decouple the js-yaml override from markdownlint-cli2, close Node-engine drift, and re-enable knip dependency rules ([#4784](https://github.com/dsj1984/mandrel/issues/4784)) ([#4788](https://github.com/dsj1984/mandrel/issues/4788)) ([9ed687b](https://github.com/dsj1984/mandrel/commit/9ed687bead90d3e0edf76e7d0e700b0f51e8cb5d))
+* **docs:** re-sync the reference docs to the contracts the code actually implements ([#4785](https://github.com/dsj1984/mandrel/issues/4785)) ([#4790](https://github.com/dsj1984/mandrel/issues/4790)) ([00d9270](https://github.com/dsj1984/mandrel/commit/00d92708b3d3ac0978c073c5a31fd6a80a25767e))
+* **docs:** supersede the stale ADR chain in place and archive the retired pattern history ([#4786](https://github.com/dsj1984/mandrel/issues/4786)) ([#4789](https://github.com/dsj1984/mandrel/issues/4789)) ([5ba2e34](https://github.com/dsj1984/mandrel/commit/5ba2e3486973b87603fd3f2f23f750f18e75e240))
+* **git-cleanup:** report the refs the prune phase actually dropped (refs [#4772](https://github.com/dsj1984/mandrel/issues/4772)) ([#4773](https://github.com/dsj1984/mandrel/issues/4773)) ([16424d5](https://github.com/dsj1984/mandrel/commit/16424d53305549841b6294ceb1d7651baf1f98e7))
+
+
+### Changed
+
+* **quality:** floor CRAP on methodsAbove20 instead of a fitted max ceiling ([#4779](https://github.com/dsj1984/mandrel/issues/4779)) ([647130b](https://github.com/dsj1984/mandrel/commit/647130b313a85add64978205d4bb300e90e3c9a3)), closes [#4775](https://github.com/dsj1984/mandrel/issues/4775)
+
+## [2.16.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.15.0...mandrel-v2.16.0) (2026-07-25)
+
+
+### Added
+
+* **workflows:** add operator-invoked /prototype and an advisory uiSurface offer (refs [#4765](https://github.com/dsj1984/mandrel/issues/4765)) ([#4769](https://github.com/dsj1984/mandrel/issues/4769)) ([d3f7173](https://github.com/dsj1984/mandrel/commit/d3f71734ef8573ffa40187b5f4f8a97be6e32041))
+
+
+### Fixed
+
+* **close-validation:** drain gate output without stalling the child's pipe (refs [#4766](https://github.com/dsj1984/mandrel/issues/4766)) ([#4770](https://github.com/dsj1984/mandrel/issues/4770)) ([fd75550](https://github.com/dsj1984/mandrel/commit/fd75550288411a4c92831ac7c9b946e2cce5a686))
+
+
+### Changed
+
+* **routing:** scope the light path by effort and risk (refs [#4764](https://github.com/dsj1984/mandrel/issues/4764)) ([#4767](https://github.com/dsj1984/mandrel/issues/4767)) ([c4851ab](https://github.com/dsj1984/mandrel/commit/c4851abe218721145daaeb4353af400223b588e6))
+
 ## [2.15.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.14.0...mandrel-v2.15.0) (2026-07-25)