mandrel 2.15.0 → 2.16.0

package/.agents/scripts/lib/orchestration/plan-context.js

@@ -18,6 +18,11 @@
  */
 
 import { readFile } from 'node:fs/promises';
+import { readAuditRulesSync } from '../audit-suite/audit-rules-reader.js';
+import {
+  hasWebSurface,
+  matchesAnyFilePattern,
+} from '../audit-suite/selector.js';
 import { getLimits } from '../config-resolver.js';
 import { findSimilarOpenStories } from '../duplicate-search.js';
 import { Logger } from '../Logger.js';
@@ -449,18 +454,189 @@ export function buildDeliverLightSuggestion(complexitySignals) {
 }
 
 /**
- * Attach the advisory light-path suggestion to a complexity-signals bag
- * as a **nested** field (Story #4741). Nesting — rather than a new top-level
- * envelope key — keeps every existing per-mode envelope key set byte-stable
- * (AC-5): the suggestion is derived from the signals it rides on.
+ * The `audit-rules.json` lens `target` value marking a lens applicable only to
+ * a project with a rendered frontend.
+ */
+const WEB_LENS_TARGET = 'web';
+
+/**
+ * How many matched UI paths the `uiSurface` signal carries. The signal rides the
+ * `--out` stdout digest, which has a ~2KB contract, and a seed can predict up to
+ * `MAX_PREDICTED_PATHS` paths — enumerating all of them would let one UI-heavy
+ * seed blow that budget. The full count travels beside the sample as
+ * `matchedPathCount`, so nothing is silently lost.
+ */
+const UI_MATCHED_PATH_SAMPLE = 5;
+
+/**
+ * Union of the `triggers.filePatterns` globs every `target: "web"` lens
+ * registers in `audit-rules.json` — the framework's shipped declaration of
+ * "this path is part of a rendered UI surface". Read from the manifest rather
+ * than re-listed here: a second copy of the glob set would be a second thing to
+ * keep in sync, and the manifest is already the place an operator extends it.
+ *
+ * @param {{ audits?: Record<string, object> }} rules
+ * @returns {string[]} Deduplicated globs, in manifest order.
+ */
+function resolveWebFilePatterns(rules) {
+  const patterns = new Set();
+  for (const entry of Object.values(rules?.audits ?? {})) {
+    if (entry?.target !== WEB_LENS_TARGET) continue;
+    for (const glob of entry?.triggers?.filePatterns ?? []) {
+      if (typeof glob === 'string' && glob !== '') patterns.add(glob);
+    }
+  }
+  return [...patterns];
+}
+
+/**
+ * Which predicted paths sit on a UI surface, per the web lens globs.
+ *
+ * An unreadable manifest is **indeterminate**, not "no match": the signal fails
+ * OPEN in the same direction {@link hasWebSurface} does, because a spurious
+ * mention of an operator-invoked command costs nothing while a missed one costs
+ * the whole point of the offer.
+ *
+ * @param {string[]} predictedPaths
+ * @returns {{ matchedPaths: string[], indeterminate: boolean }}
+ */
+function resolveWebFootprintMatch(predictedPaths) {
+  let patterns;
+  try {
+    patterns = resolveWebFilePatterns(readAuditRulesSync());
+  } catch {
+    return { matchedPaths: [], indeterminate: true };
+  }
+  return {
+    matchedPaths: predictedPaths.filter((p) =>
+      matchesAnyFilePattern(patterns, [p]),
+    ),
+    indeterminate: false,
+  };
+}
+
+/**
+ * The one sentence a `uiSurface` signal carries — why the offer fires, or why it
+ * does not. Kept in one place so the fired and unfired shapes stay one object.
+ *
+ * @param {{
+ *   detected: boolean,
+ *   webSurface: boolean,
+ *   indeterminate: boolean,
+ *   sample: string[],
+ *   count: number,
+ * }} facts
+ * @returns {string}
+ */
+function uiSurfaceReason({
+  detected,
+  webSurface,
+  indeterminate,
+  sample,
+  count,
+}) {
+  if (!detected) {
+    return webSurface
+      ? 'no predicted path matches a web lens filePattern — nothing to prototype'
+      : 'project has no rendered web surface — nothing to prototype';
+  }
+  if (indeterminate) {
+    return 'web-capable project and the UI-path manifest could not be read — offering /prototype rather than dropping the option';
+  }
+  const elided = count - sample.length;
+  const shown =
+    elided > 0 ? `${sample.join(', ')}, +${elided} more` : sample.join(', ');
+  return `web-capable project and the predicted footprint touches ${count} UI path(s) (${shown}) — the operator may want /prototype before UI acceptance criteria are authored`;
+}
+
+/**
+ * Derive the advisory **UI-surface** signal from a seed's predicted footprint.
+ *
+ * Two observables, both already shipped, ANDed together:
+ *
+ *   1. the project is web-capable at all (`hasWebSurface` — the same
+ *      applicability predicate the `target: "web"` audit lenses gate on), and
+ *   2. at least one predicted path matches a web lens `filePattern`.
+ *
+ * No new detection surface and no new `.agentrc.json` key: both halves are
+ * derived from the consumer's own checkout, so a frontend-less project — this
+ * repository included — resolves falsey and the offer never fires.
+ *
+ * The signal carries **no routing authority** (`automatic: false`): `/plan`
+ * may say that a plan touches UI and that `/prototype` exists, and must never
+ * invoke it. Pure over its inputs and total — a malformed signal bag or an
+ * unreadable manifest degrades, never throws.
+ *
+ * @param {{
+ *   complexitySignals?: object|null,
+ *   config?: object,
+ *   cwd?: string,
+ * }} [args]
+ * @returns {{
+ *   detected: boolean,
+ *   automatic: false,
+ *   advisory: true,
+ *   webSurface: boolean,
+ *   matchedPaths: string[],
+ *   matchedPathCount: number,
+ *   reasons: string[],
+ * }} `matchedPaths` is a bounded sample
+ *   ({@link UI_MATCHED_PATH_SAMPLE}); `matchedPathCount` is the full total.
+ */
+function buildUiSurfaceSignal({ complexitySignals, config, cwd } = {}) {
+  const predictedPaths = Array.isArray(complexitySignals?.predictedPaths)
+    ? complexitySignals.predictedPaths.filter((p) => typeof p === 'string')
+    : [];
+  const projectRoot =
+    typeof cwd === 'string' && cwd !== '' ? cwd : process.cwd();
+
+  let webSurface;
+  try {
+    webSurface = hasWebSurface({ config, projectRoot });
+  } catch {
+    webSurface = true; // indeterminate ⇒ fail open
+  }
+
+  const { matchedPaths, indeterminate } =
+    resolveWebFootprintMatch(predictedPaths);
+  const detected = webSurface && (indeterminate || matchedPaths.length > 0);
+  const sample = matchedPaths.slice(0, UI_MATCHED_PATH_SAMPLE);
+
+  return {
+    detected,
+    automatic: /** @type {const} */ (false),
+    advisory: /** @type {const} */ (true),
+    webSurface,
+    matchedPaths: sample,
+    matchedPathCount: matchedPaths.length,
+    reasons: [
+      uiSurfaceReason({
+        detected,
+        webSurface,
+        indeterminate,
+        sample,
+        count: matchedPaths.length,
+      }),
+    ],
+  };
+}
+
+/**
+ * Attach the advisory routing/offer signals to a complexity-signals bag as
+ * **nested** fields (Story #4741). Nesting — rather than new top-level envelope
+ * keys — keeps every existing per-mode envelope key set byte-stable: both are
+ * derived from the signals they ride on.
  *
  * @param {object} complexitySignals
- * @returns {object} the same signals plus `deliverLightSuggestion`.
+ * @param {{ config?: object, cwd?: string }} [context]
+ * @returns {object} the same signals plus `deliverLightSuggestion` and
+ *   `uiSurface`.
  */
-function withDeliverLightSuggestion(complexitySignals) {
+function withAdvisorySignals(complexitySignals, { config, cwd } = {}) {
   return {
     ...complexitySignals,
     deliverLightSuggestion: buildDeliverLightSuggestion(complexitySignals),
+    uiSurface: buildUiSurfaceSignal({ complexitySignals, config, cwd }),
   };
 }
 
@@ -701,14 +877,16 @@ async function buildSeedFileModeEnvelope({
     // authority. The planner authors the trivial-vs-standard verdict; persist
     // validates a lite claim against the authored Story's shape. The nested
     // `deliverLightSuggestion` is the advisory plan-side routing handshake
-    // (Story #4741 AC-6) — never an automatic reroute.
-    complexitySignals: withDeliverLightSuggestion(
+    // (Story #4741 AC-6) and `uiSurface` the advisory /prototype offer —
+    // neither is ever an automatic reroute.
+    complexitySignals: withAdvisorySignals(
       buildComplexitySignals({
         seedText: content,
         config,
         riskHeuristics: heuristics,
         cwd,
       }),
+      { config, cwd },
     ),
     duplicates,
     docsContext,
@@ -863,13 +1041,14 @@ async function buildTicketsModeEnvelope({
     mode: 'tickets',
     sourceTickets,
     seed: { text: seed, path: null },
-    complexitySignals: withDeliverLightSuggestion(
+    complexitySignals: withAdvisorySignals(
       buildComplexitySignals({
         seedText: seed,
         config,
         riskHeuristics: heuristics,
         cwd,
       }),
+      { config, cwd },
     ),
     duplicates,
     docsContext,
@@ -988,13 +1167,14 @@ async function buildAmendmentModeEnvelope({
     },
     // The prior body is the seed the delta is authored against.
     seed: { text: priorBody, path: null },
-    complexitySignals: withDeliverLightSuggestion(
+    complexitySignals: withAdvisorySignals(
       buildComplexitySignals({
         seedText: priorBody,
         config,
         riskHeuristics: heuristics,
         cwd,
       }),
+      { config, cwd },
     ),
     duplicates,
     // No plan temp dir and no from-scratch repo interrogation — the prior

package/.agents/scripts/lib/orchestration/single-story-close/gate-log.js

@@ -36,6 +36,24 @@
  * The sink never throws. A log directory that cannot be written degrades to
  * inline streaming — losing the size bound is strictly better than losing the
  * gate output that says why a close failed.
+ *
+ * ## Why the artifact is written asynchronously (Story #4766)
+ *
+ * This sink is the `log` callable that `close-validation/process.js` invokes
+ * from inside the gate child's stdout/stderr `'data'` handler — once per line.
+ * The first cut wrote each line with `fs.writeSync`, which blocks the event
+ * loop while the child keeps writing: the OS pipe buffer fills, the child's
+ * write fails with `EAGAIN`, and a child that does not tolerate that dies. On
+ * a clean `main` `biome ci .` already emits ~625 lines, and it aborts with
+ * exit 101 (a `biome_console` panic, not a lint violation) when it happens —
+ * so the first gate of any close could die on plumbing while its verdict was
+ * green.
+ *
+ * So the write path buffers into an async stream instead: per-line work is
+ * O(1) and never touches a syscall on the drain path. The cost is that the
+ * artifact is not on disk the instant a line is logged, which is why the sink
+ * exposes {@link GateLogSink#flush} — callers await it before reading,
+ * replaying, or naming the artifact as final.
  */
 
 import nodeFs from 'node:fs';
@@ -65,9 +83,9 @@ function logNameFor(storyId) {
  */
 class GateLogSink {
   /**
-   * @param {{ logPath: string|null, streamInline: boolean, write: (line: string) => void, emit: (line: string) => void }} args
+   * @param {{ logPath: string|null, streamInline: boolean, write: (line: string) => void, flush?: () => Promise<void>, emit: (line: string) => void }} args
    */
-  constructor({ logPath, streamInline, write, emit }) {
+  constructor({ logPath, streamInline, write, flush, emit }) {
     /** Absolute path of the artifact, or `null` when capture is unavailable. */
     this.logPath = logPath;
     /** Whether lines are ALSO echoed inline as they arrive. */
@@ -75,6 +93,7 @@ class GateLogSink {
     /** Number of lines captured so far. */
     this.lineCount = 0;
     this._write = write;
+    this._flush = flush ?? (() => Promise.resolve());
     this._emit = emit;
     this._tail = [];
   }
@@ -96,6 +115,19 @@ class GateLogSink {
     };
   }
 
+  /**
+   * Settle the artifact: wait for every buffered line to reach disk and close
+   * the file. Idempotent, never throws, and a no-op on the degraded (no
+   * artifact) path. Await it before reading {@link GateLogSink#logPath} or
+   * handing the path to anyone — the write path is async precisely so it never
+   * stalls a gate child's pipe.
+   *
+   * @returns {Promise<void>}
+   */
+  flush() {
+    return this._flush();
+  }
+
   /**
    * The success-path digest: one line, no gate output. Names the artifact so
    * the caller can open it on demand rather than carrying it all session.
@@ -129,6 +161,50 @@ class GateLogSink {
   }
 }
 
+/**
+ * Wrap an already-open artifact fd in a non-blocking line writer.
+ *
+ * `write` hands the line to a `fs.WriteStream` — O(1), no syscall on the
+ * caller's stack — and `flush` ends the stream, resolving once every buffered
+ * line has reached disk (or the stream has errored; a half-written artifact is
+ * still better than a dead close). Both are best-effort by construction: the
+ * stream's `'error'` is absorbed, so nothing here can abort a close.
+ *
+ * @param {typeof nodeFs} fs
+ * @param {string} logPath
+ * @param {number} handle
+ * @returns {{ write: (line: string) => void, flush: () => Promise<void> }}
+ */
+function createArtifactWriter(fs, logPath, handle) {
+  const stream = fs.createWriteStream(logPath, { fd: handle, autoClose: true });
+  stream.on('error', () => {
+    /* best-effort: a mid-run write failure must not abort the close */
+  });
+  let ending = null;
+  return {
+    write: (line) => {
+      if (ending) return;
+      try {
+        stream.write(`${line}\n`);
+      } catch {
+        /* best-effort: see above */
+      }
+    },
+    flush: () => {
+      ending ??= new Promise((resolve) => {
+        const settle = () => resolve();
+        stream.once('error', settle);
+        try {
+          stream.end(settle);
+        } catch {
+          settle();
+        }
+      });
+      return ending;
+    },
+  };
+}
+
 /**
  * Build the gate-output sink for one close run.
  *
@@ -155,14 +231,14 @@ export function createGateLogSink({
   const verbose = (level ?? resolveLevel()) === 'verbose';
   const dir = logDir ?? path.join(cwd, 'temp', 'orchestration');
 
-  let handle = null;
+  let writer = null;
   let logPath = null;
   try {
     fs.mkdirSync(dir, { recursive: true });
     logPath = path.join(dir, logNameFor(storyId));
     // Truncate: each close run owns its artifact outright, so a re-run never
     // hands the reader a file interleaving two runs' gates.
-    handle = fs.openSync(logPath, 'w');
+    writer = createArtifactWriter(fs, logPath, fs.openSync(logPath, 'w'));
   } catch {
     // No artifact — fall back to inline streaming rather than dropping the
     // gate output on the floor.
@@ -174,13 +250,11 @@ export function createGateLogSink({
     });
   }
 
-  const write = (line) => {
-    try {
-      fs.writeSync(handle, `${line}\n`);
-    } catch {
-      /* best-effort: a mid-run write failure must not abort the close */
-    }
-  };
-
-  return new GateLogSink({ logPath, streamInline: verbose, write, emit });
+  return new GateLogSink({
+    logPath,
+    streamInline: verbose,
+    write: writer.write,
+    flush: writer.flush,
+    emit,
+  });
 }

package/.agents/scripts/lib/orchestration/single-story-close/phases/close-validation.js

@@ -137,22 +137,31 @@ export async function runCloseValidationPhase({
   // Story #4736 — one sink for both `log` seams (gate construction and gate
   // execution), so nothing in the chain can route around the artifact.
   const gateLog = createGateLogSink({ storyId, cwd });
-  const validation = await runCloseValidation({
-    cwd,
-    worktreePath,
-    gates: buildDefaultGates({
-      config,
-      baseBranch,
-      cwd: worktreePath || cwd,
+  let validation;
+  try {
+    validation = await runCloseValidation({
+      cwd,
+      worktreePath,
+      gates: buildDefaultGates({
+        config,
+        baseBranch,
+        cwd: worktreePath || cwd,
+        log: gateLog.log,
+      }),
       log: gateLog.log,
-    }),
-    log: gateLog.log,
-    storyId,
-    // Story #4250 — standalone storyId-anchored evidence keyspace. No
-    // epicId; the standalone flag routes the cache to
-    // temp/standalone/stories/story-<id>/validation-evidence.json.
-    standalone: true,
-  });
+      storyId,
+      // Story #4250 — standalone storyId-anchored evidence keyspace. No
+      // epicId; the standalone flag routes the cache to
+      // temp/standalone/stories/story-<id>/validation-evidence.json.
+      standalone: true,
+    });
+  } finally {
+    // Story #4766 — gate lines are buffered to an async stream so the drain
+    // never blocks a gate child's pipe. Settle the artifact before anything
+    // reads it, replays from it, or reports its path — including on the throw
+    // path, where the artifact is the only surviving record.
+    await gateLog.flush();
+  }
   if (!validation.ok) {
     const [first] = validation.failed;
     const { gate, status, cwd: gateCwd } = first;

package/.agents/scripts/plan-context.js

@@ -167,7 +167,9 @@ export async function emitPlanContext({
       // Advisory only (Story #4722): signals, no route — the planner owns
       // the trivial-vs-standard verdict and persist validates it by shape.
       // The nested `deliverLightSuggestion` is the recorded plan-side routing
-      // handshake (Story #4741 AC-6) — advisory, never an automatic reroute.
+      // handshake (Story #4741 AC-6) and `uiSurface` the recorded /prototype
+      // offer — advisory, never an automatic reroute. Both ride the digest
+      // because with `--out` the digest is the only thing the planner reads.
       complexitySignals: envelope.complexitySignals
         ? {
             artifactCount: envelope.complexitySignals.artifactCount,
@@ -176,6 +178,7 @@ export async function emitPlanContext({
               envelope.complexitySignals.sensitivePathClasses,
             deliverLightSuggestion:
               envelope.complexitySignals.deliverLightSuggestion ?? null,
+            uiSurface: envelope.complexitySignals.uiSurface ?? null,
           }
         : null,
       amends: envelope.amends ? { id: envelope.amends.id } : null,

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