mandrel 2.22.0 → 2.24.0

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/scripts/lib/workers/maintainability-worker.js

@@ -7,16 +7,20 @@
  * Message contract — see lib/cpu-pool.js:
  *   IN  : { item: string }      — absolute file path to score
  *         { exit: true }        — drain & terminate
- *   OUT : { ok: true, result: { filePath, score: number | null } }
+ *   OUT : { ok: true, result: { filePath, score, unscorable?, reason? } }
  *
  * `score` is `null` only when the file genuinely cannot be read (ENOENT
- * or other I/O error). Parse failures inside escomplex still resolve to
- * `0` to preserve byte-for-byte parity with the pre-pool serial path
- * (calculateForSource swallows parse errors and returns 0).
+ * or other I/O error).
+ *
+ * A file the kernel cannot analyse comes back as `unscorable: true` with the
+ * kernel's own `reason`, rather than as a bare `0`. The `0` is still carried in
+ * `score` for wire compatibility, but it is no longer the only signal — the
+ * point of the flag is that the caller can *report* the file instead of
+ * silently dropping it (see `maintainability-engine.js`'s `UNSCORABLE`).
  */
 
 import { parentPort } from 'node:worker_threads';
-import { calculateForFile } from '../maintainability-engine.js';
+import { scoreFile } from '../maintainability-engine.js';
 
 /**
  * Pure handler for a single inbound worker message. Exported so unit
@@ -24,7 +28,7 @@ import { calculateForFile } from '../maintainability-engine.js';
  * without spawning a real `Worker` thread.
  *
  * @param {unknown} msg
- * @param {{ score?: (filePath: string) => number | null }} [deps]
+ * @param {{ score?: (filePath: string) => { score: number, unscorable: boolean, reason: string|null } }} [deps]
  * @returns {{kind: 'exit'} | {kind: 'reply', message: object}}
  */
 export function handleMaintainabilityWorkerMessage(msg, deps = {}) {
@@ -40,12 +44,13 @@ export function handleMaintainabilityWorkerMessage(msg, deps = {}) {
     };
   }
   const filePath = msg.item;
-  const scoreFn = deps.score ?? calculateForFile;
+  const scoreFn = deps.score ?? scoreFile;
   try {
-    const score = scoreFn(filePath);
+    // `scoreFn` returns `{ score, unscorable, reason }` — spread so the flag
+    // and its reason reach the pool caller intact.
     return {
       kind: 'reply',
-      message: { ok: true, result: { filePath, score } },
+      message: { ok: true, result: { filePath, ...scoreFn(filePath) } },
     };
   } catch (err) {
     // I/O or other unexpected error — surface as a per-item null score

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

@@ -48,6 +48,11 @@ Because the predicted footprint is a *declaration* — a guess, and a gameable o
 multi-capability enumeration). Size is enforced where ground truth is available:
 the diff backstop in step 4. Do not talk yourself past that one.
 
+**The backstop counts by the same principle.** It reads magnitude — changed
+lines over implementation files — not artifacts, and exempts the test and doc
+companions the framework itself mandates. A ceiling that punishes a repo for
+obeying its own test-first rule is a ceiling that over-fires.
+
 Sensitivity is the exception and stays absolute: a footprint touching an auth,
 crypto, billing, or migration class routes `full` however small or mechanical —
 and unlike a ceiling, it is **not overridable** (§ Recording a proceed-light
@@ -136,10 +141,22 @@ answer).
    node .agents/scripts/deliver-light.js --backstop --story <storyId>
    ```
 
-   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. This is the pass that actually bounds
-   size, which is why the prediction gate above can afford to be coarse.
+   This is the pass that actually bounds size, which is why the prediction gate
+   above can afford to be coarse. It measures **magnitude on the change's
+   implementation half** — changed lines (additions + deletions) plus a file
+   sprawl tripwire — never raw artifact count. Tests, `docs/**`, `**/*.md`,
+   `baselines/**`, and lockfiles are exempt from the counts, because the
+   framework mandates those companions and obeying it must not inflate the
+   number that then rejects the change. They are **not** exempt from
+   sensitive-path matching, which runs over the full change set.
+
+   Exit `3` (`blocked: true`) means the diff exceeds a light ceiling or touches a
+   sensitive-path class. STOP, flip `agent::blocked`, and **recycle the receipt**
+   through the envelope's `nextCommand` (`/plan <storyId>`) — tickets mode
+   rewrites it into properly-planned Stories and closes it as superseded. Do not
+   land, and do not leave the receipt open with no successor: it already carries
+   the branch, the worktree, and the implementation, all of which are evidence
+   the plan should read.
 
 5. **Close and land (same engine).** Exactly [`/deliver`](../deliver.md)'s close:
 

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,29 @@
 
 All notable changes to this project will be documented in this file.
 
+## [2.24.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.23.0...mandrel-v2.24.0) (2026-07-31)
+
+
+### Fixed
+
+* **deliver:** hold the Story assignee-lease until the PR is confirmed merged (refs [#4860](https://github.com/dsj1984/mandrel/issues/4860)) ([#4861](https://github.com/dsj1984/mandrel/issues/4861)) ([d722a65](https://github.com/dsj1984/mandrel/commit/d722a6558f2fa1af6aa428d2f8549101c4bedc23))
+* **maintainability:** score the Babel AST the escomplex kernel actually parses ([#4859](https://github.com/dsj1984/mandrel/issues/4859)) ([279b86f](https://github.com/dsj1984/mandrel/commit/279b86fa49c48454b5e8421ca1e0bb01f54a3bba))
+* scope the light diff backstop by change magnitude, and recycle the receipt instead of orphaning it ([#4856](https://github.com/dsj1984/mandrel/issues/4856)) ([#4857](https://github.com/dsj1984/mandrel/issues/4857)) ([114b479](https://github.com/dsj1984/mandrel/commit/114b4797f248bf00064206f32f490413e28276fb))
+
+## [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.24.0",
   "description": "Claude Code-first opinionated workflow framework: instructions, skills, rules, and SDLC workflows that govern AI coding assistants.",
   "files": [
     ".agents/",