mandrel 2.22.0 → 2.23.0

package/.agents/docs/configuration.md

@@ -291,6 +291,7 @@ top-level keys are validation errors.
 | `feedbackLoop` | No | `object` | — | Nested configuration block. |
 | `feedbackLoop.auditResultsAutoFile` | No | `boolean` | `true` | When true (default), the close-time audit-results graduator auto-files non-blocking audit-results findings as follow-up issues routed by source classification. Set to false to suppress auto-filing; findings remain accessible in the structured comments on the Story. |
 | `feedbackLoop.retroProposals` | No | `boolean` | `true` | When true (default), the retro auto-files its actionable routed proposals as meta::<framework-gap\|consumer-improvement> + friction::<category> issues via the graduator pre-parsed-findings seam, and the rendered retro sections list the filed issue numbers instead of paste-ready gh command stanzas. Set to false to fall back to the command stanzas. |
+| `feedbackLoop.frictionWindowDays` | No | `integer` | `30` | How many days back the run-scope friction recurrence window reaches (Story #4850). The window spans every surviving per-Story signal stream rather than the triggering run's own Stories, so that a defect firing once per Story can reach the actionable threshold; this bounds it by age so a defect fixed weeks ago stops re-routing. Rows older than the bound — and rows carrying no readable timestamp — are excluded and counted on the roll-up step result. Default 30. |
 | `auditToStories` | No | `object` | — | Nested configuration block. |
 | `auditToStories.severityFloor` | No | `"critical"` \| `"high"` \| `"medium"` \| `"low"` \| `"all"` | `"high"` | Minimum severity a finding must meet to be proposed as a Story on an unattended `/audit-to-stories --auto` sweep (Story #4626). Default high. |
 | `auditToStories.autoComment` | No | `boolean` | `true` | When true (default), `/audit-to-stories --auto` posts a re-detected comment on an already-open matched Issue instead of silently skipping it. |

package/.agents/schemas/agentrc.schema.json

@@ -1430,6 +1430,12 @@
               "type": "boolean",
               "default": true,
               "description": "When true (default), the retro auto-files its actionable routed proposals as meta::<framework-gap|consumer-improvement> + friction::<category> issues via the graduator pre-parsed-findings seam, and the rendered retro sections list the filed issue numbers instead of paste-ready gh command stanzas. Set to false to fall back to the command stanzas."
+            },
+            "frictionWindowDays": {
+              "type": "integer",
+              "minimum": 1,
+              "default": 30,
+              "description": "How many days back the run-scope friction recurrence window reaches (Story #4850). The window spans every surviving per-Story signal stream rather than the triggering run's own Stories, so that a defect firing once per Story can reach the actionable threshold; this bounds it by age so a defect fixed weeks ago stops re-routing. Rows older than the bound — and rows carrying no readable timestamp — are excluded and counted on the roll-up step result. Default 30."
             }
           },
           "additionalProperties": false

package/.agents/scripts/diagnose-friction.js

@@ -31,6 +31,7 @@
  */
 import { spawnSync } from 'node:child_process';
 import crypto from 'node:crypto';
+import { constants as osConstants } from 'node:os';
 import { getLimits, resolveConfig } from './lib/config-resolver.js';
 import { Logger } from './lib/Logger.js';
 import { appendSignal } from './lib/observability/signals-writer.js';
@@ -97,6 +98,72 @@ function classifyFrictionCategory(errorOutput) {
   return { category: matched.category, remediation: matched.remediation };
 }
 
+/**
+ * `spawnSync`'s own `timeout` option kills the child with `SIGTERM`, so a
+ * SIGTERM observed here almost always means the interceptor's configured
+ * `executionTimeoutMs` bound fired. Any other signal — a `SIGKILL` from the
+ * OOM killer, an operator `kill -9` — originated outside this process.
+ *
+ * @type {string}
+ */
+const INTERCEPTOR_TIMEOUT_SIGNAL = 'SIGTERM';
+
+/** Shell convention for "the process died by signal N": exit `128 + N`. */
+const SIGNAL_EXIT_BASE = 128;
+
+/**
+ * Describe a child that never exited normally — `status === null`, Node's
+ * documented representation of "did not exit normally". The raw status must
+ * never reach `process.exit`, because `process.exit(null)` exits **0**: the
+ * interceptor would report success for a command it just watched get killed
+ * (Story #4851).
+ *
+ * Which signal fired is the diagnostic value: SIGTERM points at the
+ * interceptor's own bound, anything else at the host. Recording that plus the
+ * bound itself is what makes the row actionable to a consumer who cannot edit
+ * the materialized framework tree.
+ *
+ * Deliberately module-local and pure — exporting it for tests would fail the
+ * `--production` dead-exports ratchet, and folding it into `main` would spend
+ * the file's per-file maintainability-delta headroom. The CLI contract is the
+ * seam the unit tests drive.
+ *
+ * @param {{signal: (string|null), error?: {message?: string}}} result A
+ *   `spawnSync` result whose `status` is `null`.
+ * @param {number} executionTimeoutMs The resolved interceptor bound, in ms.
+ * @returns {{category: string, remediation: string, details: object,
+ *   preview: string, exitCode: number}}
+ */
+function describeAbnormalExit(result, executionTimeoutMs) {
+  const signal = typeof result.signal === 'string' ? result.signal : null;
+  if (signal === null) {
+    return {
+      category: FRICTION_DEFAULT.category,
+      remediation: FRICTION_DEFAULT.remediation,
+      details: {
+        killedBySignal: null,
+        killOrigin: 'spawn-failure',
+        executionTimeoutMs,
+      },
+      preview: `Command did not exit normally and reported no signal: ${result.error?.message ?? 'spawn produced no exit status'}.`,
+      exitCode: 1,
+    };
+  }
+
+  const timedOut = signal === INTERCEPTOR_TIMEOUT_SIGNAL;
+  const killOrigin = timedOut ? 'interceptor-timeout' : 'external';
+  const signum = osConstants.signals[signal];
+  return {
+    category: timedOut ? 'Execution Timeout' : 'Execution Killed',
+    remediation: timedOut
+      ? ` - ${signal} matches the interceptor's own executionTimeoutMs bound (${executionTimeoutMs}ms), so the command was almost certainly cut off rather than broken. Split it into smaller steps, or raise the bound.`
+      : ` - ${signal} originated outside the interceptor — the executionTimeoutMs bound (${executionTimeoutMs}ms) did not fire, so suspect an OOM kill or a hard kill from the host. Reduce the command's memory footprint or give the host more headroom.`,
+    details: { killedBySignal: signal, killOrigin, executionTimeoutMs },
+    preview: `Command terminated by signal ${signal} (${killOrigin}); executionTimeoutMs=${executionTimeoutMs}.`,
+    exitCode: Number.isInteger(signum) ? SIGNAL_EXIT_BASE + signum : 1,
+  };
+}
+
 function toIntOrNull(value) {
   if (value == null) return null;
   const n = Number.parseInt(String(value), 10);
@@ -121,6 +188,7 @@ function buildFrictionSignal({
   category,
   commandStr,
   errorPreview,
+  terminationDetails = null,
 }) {
   return {
     kind: 'friction',
@@ -133,11 +201,14 @@ function buildFrictionSignal({
     // and always null.
     taskId: null,
     category,
+    // `emitter.command` is what `classifySignalSource` step 1 scans, so the
+    // command-scan stays authoritative for `source`: a consumer command killed
+    // by its own host remains consumer-actionable (Story #4851).
     emitter: {
       tool: 'diagnose-friction.js',
       command: commandStr,
     },
-    details: { errorPreview },
+    details: { errorPreview, ...(terminationDetails ?? {}) },
   };
 }
 
@@ -176,10 +247,22 @@ export async function main(args = process.argv.slice(2)) {
   if (result.stderr) process.stderr.write(result.stderr);
 
   if (result.status !== 0) {
+    // A `null` status means the child never exited normally; the cause lives in
+    // `result.signal`, not in the status.
+    const abnormal =
+      result.status === null
+        ? describeAbnormalExit(result, executionTimeoutMs)
+        : null;
+    // With both streams empty an abnormal termination names its signal; the
+    // `Unknown exit code` fallback is therefore reachable only with a real
+    // numeric status, never as `Unknown exit code null`.
+    const noOutputFallback = abnormal
+      ? abnormal.preview
+      : `Unknown exit code ${result.status}`;
     const errorOutput = (
       result.stderr ||
       result.stdout ||
-      `Unknown exit code ${result.status}`
+      noOutputFallback
     ).trim();
     const errorPreview = errorOutput.substring(0, 500);
 
@@ -188,7 +271,12 @@ export async function main(args = process.argv.slice(2)) {
       'Command failed. Appending friction signal to NDJSON stream...',
     );
 
-    const { category, remediation } = classifyFrictionCategory(errorOutput);
+    // An abnormal termination classifies itself: the marker scan reads output
+    // the kill may have truncated (or never produced), so it cannot name the
+    // signal.
+    const classified = classifyFrictionCategory(errorOutput);
+    const category = abnormal?.category ?? classified.category;
+    const remediation = abnormal?.remediation ?? classified.remediation;
 
     const { storyId: resolvedStoryId, epicId: resolvedEpicId } =
       resolveContextIds({ storyId, epicId }, config);
@@ -199,6 +287,7 @@ export async function main(args = process.argv.slice(2)) {
       category,
       commandStr,
       errorPreview,
+      terminationDetails: abnormal?.details ?? null,
     });
 
     // Story #2874 — accept story-only context (no parent Epic). When
@@ -236,7 +325,9 @@ export async function main(args = process.argv.slice(2)) {
     Logger.error(remediation);
     Logger.error('----------------------------------------\n');
 
-    process.exit(result.status);
+    // Never `process.exit(result.status)` on a null status — that exits 0 and
+    // reports success for a killed command.
+    process.exit(abnormal?.exitCode ?? result.status);
   } else {
     process.exit(0);
   }

package/.agents/scripts/lib/config-settings-schema-delivery.js

@@ -322,12 +322,20 @@ const REVIEW_SCHEMA = {
  * issues via the graduator pre-parsed-findings seam, and the rendered retro
  * sections list the filed issue numbers instead of paste-ready `gh` command
  * stanzas; set it to `false` to fall back to the command stanzas.
+ *
+ * `frictionWindowDays` (Story #4850) bounds the run-scope friction recurrence
+ * window by row age. The window deliberately spans every surviving signal
+ * stream rather than the triggering run's own Stories — that is what lets a
+ * once-per-Story systemic defect reach the ≥ 2 actionable threshold — which
+ * left it unbounded in time, so a defect fixed weeks ago kept re-routing. An
+ * integer ≥ 1; unset means 30 days.
  */
 const FEEDBACK_LOOP_SCHEMA = {
   type: 'object',
   properties: {
     auditResultsAutoFile: { type: 'boolean' },
     retroProposals: { type: 'boolean' },
+    frictionWindowDays: { type: 'integer', minimum: 1 },
   },
   additionalProperties: false,
 };

package/.agents/scripts/lib/observability/runtime-friction.js

@@ -355,9 +355,18 @@ export async function emitCloseRecoveredFriction({ storyId, config } = {}) {
  * `tool-degraded` from the scoped-lint runner from one out of lens
  * materialization. It is descriptive, never a routing key.
  *
+ * `ts` joined the shape in Story #4850, and it joined it **here** rather than
+ * in a second read beside the run-scope gather. The composer had no notion of
+ * *when* its corpus happened, so it borrowed the triggering run as the window
+ * and titled every proposal with a claim the evidence block below it already
+ * contradicted. Carrying the timestamp through the one shared normalizer is
+ * what lets the recurrence window be both bounded and describable; re-reading
+ * it beside one of the two gathers is precisely the drift that made the
+ * recovery-netting unreachable in Story #4649.
+ *
  * @param {unknown} parsed          One parsed NDJSON row.
  * @param {number}  fallbackStoryId Stream owner, used when the row has none.
- * @returns {{ category: string, source: 'framework'|'consumer', storyId: number, tool: string, details: object }|null}
+ * @returns {{ category: string, source: 'framework'|'consumer', storyId: number, tool: string, ts: string|null, details: object }|null}
  */
 export function normalizeGatheredSignal(parsed, fallbackStoryId) {
   if (!parsed || typeof parsed !== 'object') return null;
@@ -374,6 +383,7 @@ export function normalizeGatheredSignal(parsed, fallbackStoryId) {
     source: parsed.source === 'framework' ? 'framework' : 'consumer',
     storyId: Number.isInteger(recordStoryId) ? recordStoryId : fallbackStoryId,
     tool: typeof emitterTool === 'string' ? emitterTool.trim() : '',
+    ts: parsableTimestamp(parsed.ts),
     details:
       parsed.details && typeof parsed.details === 'object'
         ? parsed.details
@@ -381,6 +391,24 @@ export function normalizeGatheredSignal(parsed, fallbackStoryId) {
   };
 }
 
+/**
+ * The row's `ts` when it is a string a `Date` can read, else `null`.
+ *
+ * `signal-event.schema.json` requires `ts`, and both producers stamp
+ * `new Date().toISOString()` — but the gathers read whatever survives on disk,
+ * including rows a truncated write left half-formed. Resolving to `null`
+ * rather than guessing a time is what lets the recurrence window exclude an
+ * undateable row explicitly instead of aging it in as "recent".
+ *
+ * @param {unknown} value
+ * @returns {string|null}
+ */
+function parsableTimestamp(value) {
+  if (typeof value !== 'string') return null;
+  const trimmed = value.trim();
+  return Number.isFinite(Date.parse(trimmed)) ? trimmed : null;
+}
+
 /**
  * Pure predicate: is this signal a recovery marker for its own category?
  * Shared with the retro composer so the "recovered" discriminator is read

package/.agents/scripts/lib/orchestration/run-epilogue.js

@@ -557,22 +557,29 @@ async function executeFollowUpRollup({
   // Shared with the story-scoped gather (Story #4649): `storyId` + `details`
   // are what the composer's recovery-netting keys on, and two hand-rolled
   // copies of this loop are how they got dropped in the first place.
-  const signals = await gatherRunFrictionSignals(stories, config);
+  const { signals, window: frictionWindow } = await gatherRunFrictionSignals(
+    stories,
+    config,
+  );
   const repos = resolveFollowUpRepos(config);
   const primaryId = Number(stories[0]);
+  // Story #4850 — `runToken` and `anchorStoryIds` are INPUTS. This used to
+  // compose with the primary Story's numeric id standing in for the run and
+  // then rewrite the rendered title/body by regex over a `plan-run \d+`
+  // substring, which meant the composer's own wording could not be changed
+  // without silently breaking the patch. `anchorStoryIds` is what lets the
+  // composer tell a corpus confined to this run from one spanning the whole
+  // surviving window, so it never titles the latter as if it were the former.
   const proposals = composeRoutedProposals({
     anchorId: Number.isInteger(primaryId) ? primaryId : 1,
     anchorKind: 'run',
+    runToken: String(planRunId ?? ''),
+    anchorStoryIds: stories,
     frameworkRepo: repos.frameworkRepo,
     consumerRepo: repos.consumerRepo,
     signals,
     unresolvedBlockedEvents: [],
   });
-  // Patch titles to mention the plan-run token (anchorKind run uses numeric id).
-  for (const item of [...proposals.framework, ...proposals.consumer]) {
-    item.title = item.title.replace(/plan-run \d+/, `plan-run ${planRunId}`);
-    item.body = item.body.replace(/plan-run \d+/g, `plan-run ${planRunId}`);
-  }
   const graduated = await graduateFn({
     epicId: primaryId,
     provider,
@@ -619,6 +626,11 @@ async function executeFollowUpRollup({
     signalCount: signals.length,
     storyCount: stories.length,
     filed: graduated.filed?.length ?? 0,
+    // Story #4850 — the recurrence window the gather actually applied, and what
+    // it dropped. `signalCount` alone cannot distinguish "the window is bounded
+    // at 30 days and 40 rows aged out" from "nothing older exists", and an
+    // operator triaging a roll-up needs to know which corpus produced it.
+    frictionWindow,
     // Story #4828 — everything below is what the roll-up saw and what became
     // of it. The pre-#4828 result reported `signalCount` and `filed` and
     // nothing in between, so nine signals routing into one proposal whose

package/.agents/scripts/lib/orchestration/story-follow-ups.js

@@ -26,6 +26,33 @@ import { upsertStructuredComment } from './ticketing.js';
 
 export const FOLLOW_UPS_COMMENT_TYPE = 'follow-ups';
 
+/** Milliseconds in one day — the unit `frictionWindowDays` is expressed in. */
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+
+/** Window bound applied when `frictionWindowDays` is unset. */
+const DEFAULT_FRICTION_WINDOW_DAYS = 30;
+
+/**
+ * How many days back the run-scope recurrence window reaches (Story #4850).
+ *
+ * Defaults to 30 rather than to "unbounded": the widened cross-run window
+ * exists to let a once-per-Story defect reach the ≥ 2 threshold, and 30 days is
+ * long enough for that while short enough that a defect fixed last month stops
+ * re-routing. An absent, non-integer, or sub-1 value takes the default — the
+ * runtime AJV in `config-settings-schema-delivery.js` rejects those at load, so
+ * reaching this fallback means the config never went through the validator.
+ *
+ * @param {object} [config]
+ * @returns {number}
+ */
+function resolveFrictionWindowDays(config) {
+  const raw = config?.delivery?.feedbackLoop?.frictionWindowDays;
+  const days = Number(raw);
+  return Number.isInteger(days) && days >= 1
+    ? days
+    : DEFAULT_FRICTION_WINDOW_DAYS;
+}
+
 /**
  * @param {object} [config]
  * @returns {{ frameworkRepo: string, consumerRepo: string, currentRepo: { owner: string, repo: string } }}
@@ -145,18 +172,55 @@ function signalIdentity(parsed, file, lineNumber) {
  * Unusable ids are skipped rather than throwing — a roll-up must not fail the
  * epilogue over one malformed entry.
  *
+ * **Bounded by age, not by run (Story #4850).** Widening the window to the
+ * whole surviving temp tree also made it unbounded in *time*: a defect fixed
+ * weeks ago kept its occurrences on disk and kept re-routing forever, burying
+ * a genuine new regression underneath a historical ledger. Rows older than
+ * `delivery.feedbackLoop.frictionWindowDays` (default 30) are excluded, as are
+ * rows carrying no `ts` a `Date` can read — excluding an undateable row is the
+ * direction that fails toward under-counting, and under-counting fails toward
+ * not filing. Both exclusions are **counted and reported**, so a caller can
+ * tell a bounded window from an unbounded one without reading prose.
+ *
+ * A recovery marker is written after the incident it cancels, so a marker can
+ * never fall outside a window its incident is inside — the netting cannot be
+ * broken by the age floor.
+ *
  * @param {Array<number|string>} storyIds The run's own Stories.
  * @param {object} [config]
- * @returns {Promise<Array<{ category: string, source: 'framework'|'consumer', storyId: number, details: object }>>}
+ * @param {{ now?: number }} [clock] Injected epoch-ms seam so a test can pin
+ *   the window without touching the system clock.
+ * @returns {Promise<{
+ *   signals: Array<{ category: string, source: 'framework'|'consumer', storyId: number, ts: string|null, details: object }>,
+ *   window: { days: number, cutoff: string, excludedStale: number, excludedUnparseable: number },
+ * }>}
  */
-export async function gatherRunFrictionSignals(storyIds, config) {
+export async function gatherRunFrictionSignals(
+  storyIds,
+  config,
+  { now = Date.now() } = {},
+) {
+  const days = resolveFrictionWindowDays(config);
+  const cutoffMs = now - days * MS_PER_DAY;
   const signals = [];
   const seen = new Set();
+  let excludedStale = 0;
+  let excludedUnparseable = 0;
   const take = (parsed, fallbackStoryId, identity) => {
     if (seen.has(identity)) return;
     seen.add(identity);
     const signal = normalizeGatheredSignal(parsed, fallbackStoryId);
-    if (signal) signals.push(signal);
+    if (!signal) return;
+    const ms = signal.ts === null ? Number.NaN : Date.parse(signal.ts);
+    if (!Number.isFinite(ms)) {
+      excludedUnparseable += 1;
+      return;
+    }
+    if (ms < cutoffMs) {
+      excludedStale += 1;
+      return;
+    }
+    signals.push(signal);
   };
 
   for (const raw of Array.isArray(storyIds) ? storyIds : []) {
@@ -178,7 +242,15 @@ export async function gatherRunFrictionSignals(storyIds, config) {
     config,
   );
 
-  return signals;
+  return {
+    signals,
+    window: {
+      days,
+      cutoff: new Date(cutoffMs).toISOString(),
+      excludedStale,
+      excludedUnparseable,
+    },
+  };
 }
 
 /**

package/.agents/scripts/lib/templates/decomposer-prompts.js

@@ -155,7 +155,7 @@ The serialized \`body\` string renders these markdown sections (in order):
 - **Observed-behavior claims open with \`Current state (verified <date>)\`.** Any Spec claim about how the codebase behaves today MUST open with that preamble (e.g. \`Current state (verified 2026-07-17): …\`) so a reader can tell a verified observation from an assumption, and can tell when the observation went stale.
 - **Intent-then-proxy acceptance shape.** When an acceptance item verifies through a proxy check (a grep, a file-exists probe, an exit-code test), state the intent clause before the proxy check — what outcome the check stands in for — so the proxy never becomes the goal (e.g. "the workflow names hygiene findings as re-author input: \`grep -n "textHygiene" …\` exits 0").
 - **Slicing checkpoints are one line each.** Each \`## Slicing\` checkpoint is a single line naming the checkpoint; implementation detail lives in \`## Spec\`, never duplicated into Slicing. A Slicing section outweighing its Spec is a defect the text-hygiene lint flags.
-- **Bodies record decisions, never questions to the operator.** Never persist an open question ("Flag if…", "TBD", "confirm with the operator") into a Story body — the executing sub-agent is non-interactive and cannot answer it. Resolve the unknown before authoring, or restate it as a declarative Key Assumption the agent can act on.
+- **Bodies record decisions, never questions to the operator.** Never persist an open question ("Flag if…", "TBD", "confirm with the operator") into a Story body — the executing sub-agent is non-interactive and cannot answer it. Triage each unknown by who can resolve it: an AFK-shaped unknown (a fact in docs, a third-party API surface, observable repo behavior) MUST be resolved by your own research before authoring — never restated as an assumption; only a HITL-shaped unknown (a genuine product or architecture call the operator owns) may be restated as a declarative Key Assumption the agent can act on, stating the default chosen (a decision-made-by-default).
 - **non_goals** (OPTIONAL, in body string as the \`## Non-Goals\` section): A short list of capabilities or changes this Story explicitly does NOT deliver — an advisory negative-scope bound that fences the executing agent away from adjacent work. It is **advisory and NON-GATING**: the validator does not require, count, or reject on it, and an absent or empty section renders nothing. Use the EXACT single-word hyphenated heading spelling \`## Non-Goals\` (a space-separated heading like \`## Out of Scope\` is NOT recognized by the parser and will be dropped). Reach for it when a Story's negative boundary is non-obvious from its \`acceptance[]\` alone; omit it otherwise.
 
 #### SPEC PROSE CONTRACT — state the contract, not the implementation:

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

@@ -36,6 +36,46 @@ whole surface exists to remove.
 Mixed ids and prose in one invocation is a **hard error**: refuse and ask which
 was meant, rather than guessing a mode and doing the wrong work.
 
+## Unknown triage — AFK vs HITL
+
+Every open question interrogation surfaces is triaged by **who can resolve
+it**, not parked in one bucket (a shape borrowed from the Wayfinder skill's
+HITL/AFK ticket typing):
+
+- **AFK** (away from keyboard — the agent resolves it alone): the answer is a
+  fact something already records — third-party docs, a dependency's API
+  surface, observable behavior of this repo. Research it during interrogation
+  (per `.agents/instructions.md` § 1.C) and fold the answer into the plan as a
+  verified claim. An AFK unknown never becomes a Key Assumption — an
+  assumption standing in for a checkable fact is just an unchecked fact.
+- **HITL** (human in the loop — only the operator can resolve it): a genuine
+  product or architecture call — what to support, what to drop, which
+  trade-off to prefer. Nothing the agent reads can answer it; presenting a
+  researched recommendation is fine, deciding is not.
+
+Boundary examples: *"does library X support streaming?"* is AFK (read its
+docs); *"should we drop Node 18 support?"* is HITL (a support-policy call);
+*"does our CLI already validate this flag?"* is AFK (read the code);
+*"which of two valid schema shapes should the new field use?"* is HITL when
+both fit — but first verify it is not settled by an existing convention,
+which would make it AFK.
+
+**Attended runs** present the HITL list at Gate #1 as "needs your decision",
+one line each, alongside the sharpened intent. **Under `--yes`** nobody is at
+the keyboard: AFK unknowns are researched exactly as in an attended run, and
+each HITL unknown degrades to a declarative Key Assumption that names the
+default chosen and marks it a decision-made-by-default, e.g.:
+
+> **Key Assumption (decision-made-by-default):** new-style envelopes only;
+> re-emitting legacy envelopes was ruled out by default, not by the operator.
+
+(Keep the assumption itself declarative — "flag if wrong" phrasing trips the
+open-question hygiene lint, and the deliverer cannot answer it anyway.)
+
+The marker keeps the operator's undelegated decisions findable after the
+fact: reviewing a `--yes` plan means scanning its decisions-made-by-default,
+not re-deriving which assumptions were really the agent's to make.
+
 ## Gate #1 → the light path (in-session handoff)
 
 On a confirmed `deliverLightSuggestion`, `/plan` routes into

package/.agents/workflows/plan.md

@@ -14,7 +14,7 @@ description:
 
 Single planning path — there is no Epic/Story router, no scope-triage
 `epic|story` verdict. **Derive the mode from what the operator typed, announce
-it, then act**; there is nothing for them to remember:
+it, then act**:
 
 | Invocation | Mode | Behavior |
 | --- | --- | --- |
@@ -24,11 +24,10 @@ it, then act**; there is nothing for them to remember:
 | `/plan 4712[,4713…]` | tickets | Fetch issue(s), analyze into proper Stories (prefer N=1 rewrite). |
 | `/plan 4712`, already delivered | amends | Amend a shipped Story from a **delta envelope**, not a re-interrogation. |
 
-**Resolving a bare id.** Ids alone are ambiguous between *amend* and *tickets*,
-so read live state rather than asking: `agent::done` can only be amended, an
-open unplanned issue can only be planned. **Announce the derivation** — "4712
-is `agent::done` → amending" — so a wrong read costs one correction, not a
-wasted run. Ask **only** for an open Story already at `agent::ready`.
+**Resolving a bare id.** Read live state rather than asking: `agent::done` can
+only be amended, an open unplanned issue can only be planned. **Announce the
+derivation** — "4712 is `agent::done` → amending" — so a wrong read costs one
+correction. Ask **only** for an open Story already at `agent::ready`.
 
 `--body` is **not** a `/plan` entry; persist goes through `plan-persist.js`.
 
@@ -62,19 +61,26 @@ node .agents/scripts/plan-context.js --seed "<seed>" \
 
 **Always pass `--out`.** Persist auto-discovers the envelope from `--plan-dir`
 and derives source ids from its `sourceTickets[]`; the CLI also writes
-**`stories.template.json`**, the skeleton step 2 starts from.
+**`stories.template.json`**, step 2's skeleton.
 
 The envelope carries docs context, the story-author
 prompt, `sourceTickets[]`, `duplicates[]` (open **Stories**, never Epics), and
 advisory `complexitySignals` (**no routing authority**). A trivial scope earns
 `--route-downgrade-reason "<why>"` at persist — shape-validated, failing closed
-to `full` ([detail](helpers/plan-reference.md)). Under `--yes`, do not ask
-free-form operator questions — unknowns land in Key Assumptions.
+to `full` ([detail](helpers/plan-reference.md)).
+
+**Triage each unknown by resolver**
+([detail](helpers/plan-reference.md)): an **AFK** unknown (research settles
+it) is resolved before authoring, never assumed; a **HITL** unknown (an
+operator call) goes to Gate #1 as "needs your decision". Under `--yes`, do
+not ask free-form operator questions — AFK unknowns are still researched;
+only HITL unknowns land in Key Assumptions, each marked a
+decision-made-by-default.
 
 **Gate #1** — STOP to confirm the sharpened plan intent and any
 duplicate-candidate review. Under `--yes`, auto-proceed.
 
-When `complexitySignals.deliverLightSuggestion.suggested` is `true`, offer —
+On a truthy `deliverLightSuggestion.suggested`, offer —
 **advisory, never an automatic reroute** — to deliver the seed instead of
 planning it. On confirm, route **in this session** into
 [`helpers/deliver-light.md`](helpers/deliver-light.md), filling its gate from
@@ -88,9 +94,9 @@ A truthy `complexitySignals.uiSurface` marks a UI-touching plan: name
 ### 2. Author
 
 **One-shot authoring.** Start from `stories.template.json`; author
-`stories.json` in one pass. Entries are pre-resolved; keep tiers/assumptions
-valid. `body` is a markdown string **or** a structured object; persist parses
-either, serializes the canonical markdown, and syncs top-level `acceptance[]` /
+`stories.json` in one pass. `body` is a markdown string **or** a structured
+object; persist parses either, serializes the canonical markdown, and syncs
+top-level `acceptance[]` /
 `verify[]` into it — never dual-author those lists.
 
 **Grounding = your reads + Phase 8.** Nothing inventories the repo for you:
@@ -149,9 +155,8 @@ node .agents/scripts/plan-persist.js \
   [--source-tickets 123,456]
 ```
 
-At lite shape, `--chain-on-clean` chains that dry-run into the real persist in
-one round-trip **only** when it is clean and `lite`; a full plan keeps its
-review round-trip.
+At lite shape, `--chain-on-clean` chains a clean dry-run into the real persist
+in one round-trip; a full plan keeps its review round-trip.
 
 Persist creates `type::story` issue(s) plus a `plan-run::<id>` grouping label
 (**metadata only**); N>1 `depends_on` edges become `blocked by #<id>` footers.

package/docs/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 All notable changes to this project will be documented in this file.
 
+## [2.23.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.22.0...mandrel-v2.23.0) (2026-07-30)
+
+
+### Added
+
+* **plan:** triage interrogation unknowns by resolver — AFK research vs HITL operator decision (refs [#4845](https://github.com/dsj1984/mandrel/issues/4845)) ([#4846](https://github.com/dsj1984/mandrel/issues/4846)) ([3cfcd00](https://github.com/dsj1984/mandrel/commit/3cfcd00f3885fc588bdf2bb4597118a790f9b270))
+
+
+### Fixed
+
+* **diagnose-friction:** name the signal that killed a child instead of reporting "Unknown exit code null" and exiting 0 ([#4851](https://github.com/dsj1984/mandrel/issues/4851)) ([#4853](https://github.com/dsj1984/mandrel/issues/4853)) ([1985be1](https://github.com/dsj1984/mandrel/commit/1985be1b97d751d094acf7dd371b97124039cc6d))
+* **rollup:** describe the friction corpus by its own window, not the triggering run (refs [#4850](https://github.com/dsj1984/mandrel/issues/4850)) ([#4852](https://github.com/dsj1984/mandrel/issues/4852)) ([d866697](https://github.com/dsj1984/mandrel/commit/d8666976be30d218115b9db32602359d55379f88))
+* **rollup:** track anchorKind in the triggering-anchor label ([#4854](https://github.com/dsj1984/mandrel/issues/4854)) ([b7e4ddf](https://github.com/dsj1984/mandrel/commit/b7e4ddf8c362f7c31c2abd73ee181a94f78f6dd2))
+
 ## [2.22.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.21.0...mandrel-v2.22.0) (2026-07-30)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mandrel",
-  "version": "2.22.0",
+  "version": "2.23.0",
   "description": "Claude Code-first opinionated workflow framework: instructions, skills, rules, and SDLC workflows that govern AI coding assistants.",
   "files": [
     ".agents/",