mandrel 2.23.0 → 2.25.0

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

@@ -36,6 +36,22 @@ 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.
 
+## Default-single split policy — what the seam means
+
+The spine's two escape hatches from N=1 are narrow on purpose:
+
+- **Near-zero overlap** — the pieces touch disjoint files and neither's
+  acceptance criteria can be scored without the other having landed.
+- **Architectural seam** — different deployables, or a migration and its
+  consumer: work that cannot share one branch and one PR without one half
+  sitting unverifiable behind the other.
+
+Everything else is one Story with `## Slicing` checkpoints. When N>1 does
+apply, **every acceptance criterion belongs to exactly one Story** —
+`assertAcceptancePartition` refuses a split whose criteria repeat across
+siblings, because a verbatim-shared criterion is the signature of coupled work
+cut in half rather than genuinely separable work.
+
 ## Unknown triage — AFK vs HITL
 
 Every open question interrogation surfaces is triaged by **who can resolve
@@ -98,6 +114,14 @@ Resume `/plan` at step 2 (Author) **in this same session** — the interrogation
 is still valid and re-paying for it buys nothing. This bounce-back is not an
 escalation.
 
+**Under `--yes` the offer is recorded and planning proceeds** — it is *never*
+auto-downgraded to light. An unattended run has nobody to confirm the reroute,
+and a suggestion is not a confirmation. The same rule governs unknown triage
+unattended: AFK unknowns are still researched, but no free-form operator
+question is asked — each HITL unknown lands in Key Assumptions marked a
+decision-made-by-default, so the record shows what was decided for the operator
+rather than pretending it was decided with them.
+
 Escalation in the *other* direction — an over-scope prompt on the light path —
 is terminal and requires a fresh session. The rule that separates the two, and
 why it must not be flattened into symmetry:
@@ -294,6 +318,16 @@ Either way the critic is **maker-blind**: hand it the draft artifacts
 transcript or the reasons the planner believed its own draft is sound. A
 critic that reads the maker's case grades the case, not the draft.
 
+## What `--dry-run` actually gates
+
+`plan-persist.js --dry-run` is the same command with GitHub writes suppressed,
+and every gate runs before the first `createIssue` would fire — the validator,
+the body parse, the DAG, the capacity and Spec-budget ceilings, the
+reachability check, the split and supersede partitions, and the Tech Spec fold.
+That is the whole point of running it first: a dry run that comes back clean
+has already paid for every deterministic refusal, so the real persist has
+nothing left to discover except network failure.
+
 ## Ready means fully persisted
 
 `agent::ready` is the **terminal** step, not part of the creating POST.

package/.agents/workflows/plan.md

@@ -7,47 +7,43 @@ description:
 
 # /plan
 
-> **Lean spine.** Happy path + gate list; edge-case detail lives in on-demand
+> **Lean spine.** Happy path + gate list; edge-case detail lives on demand in
 > [`helpers/plan-reference.md`](helpers/plan-reference.md).
 
 ## Inputs
 
 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**:
+it, act**:
 
 | Invocation | Mode | Behavior |
 | --- | --- | --- |
 | `/plan` | ask | Ask what to plan; nothing runs first. |
-| `/plan add a --json flag to doctor` | seed | Ideation from the prose: interrogate → author **one Story by default** → persist. |
-| `/plan temp/notes/idea.md` | seed-file | Same, from notes. An argument resolving to an existing file is a path, never prose. |
+| `/plan add a --json flag to doctor` | seed | Ideation from prose: interrogate → author **one Story by default** → persist. |
+| `/plan temp/notes/idea.md` | seed-file | Same, from notes. An existing file is a path, not prose. |
 | `/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.** 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`.
+derivation** — "4712 is `agent::done` → amending". Ask **only** for an open
+Story already at `agent::ready`.
 
 ## Saying what you want
 
-No flags to remember — state intent and the workflow fills in the CLI
-([reference](helpers/plan-reference.md)). Run any script with `--help` rather
-than copying its surface here.
+No flags to remember — state intent; the workflow fills in the CLI
+([reference](helpers/plan-reference.md)). Run scripts with `--help`.
 
 `--yes` is **runner-set, never operator-typed** — cron, `/loop`, and headless
-dispatch set it to mean *nobody is at the keyboard*, which is what auto-proceeds
-the gates below. Never offer it to an operator or add it to an attended run.
+dispatch set it to mean *nobody is at the keyboard*, which auto-proceeds the
+gates below (#1 and #2). Never offer it to an operator or an attended run.
 
 ## Default-single split policy
 
 Author **one Story** unless the pieces have **near-zero overlap** or sit across
-an **architectural seam** (different deployables, migration vs consumer).
-Coupled work stays one Story — `## Slicing` checkpoints, not sibling tickets;
-when N>1 every acceptance criterion belongs to exactly one Story
-(`assertAcceptancePartition` refuses coupled splits). **N=1 is the lean path.**
+an **architectural seam**. Coupled work stays one Story — `## Slicing`
+checkpoints, not sibling tickets
+([detail](helpers/plan-reference.md)). **N=1 is lean.**
 
 ## Procedure
 
@@ -63,54 +59,46 @@ node .agents/scripts/plan-context.js --seed "<seed>" \
 and derives source ids from its `sourceTickets[]`; the CLI also writes
 **`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)).
-
-**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
+The envelope carries docs context, the story-author prompt, `sourceTickets[]`,
+`duplicates[]` (open **Stories**, never Epics) and advisory `complexitySignals`
+(**no routing authority**). A trivial scope can claim the lite route at
+persist — shape-validated, failing closed 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.
 
-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
-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.
+On a truthy `deliverLightSuggestion.suggested`, offer — advisory, never an
+automatic reroute — to deliver the seed instead; on confirm, route **in this
+session** into [`helpers/deliver-light.md`](helpers/deliver-light.md), its gate
+filled from this envelope. A truthy `complexitySignals.uiSurface` marks a
+UI-touching plan: name [`/prototype`](prototype.md) as an operator option,
+never invoke it here. [Both offers](helpers/plan-reference.md).
 
 ### 2. Author
 
 **One-shot authoring.** Start from `stories.template.json`; author
-`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.
+`stories.json` in one pass. `body` is markdown **or** a structured object;
+persist parses either, serializes 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:
-read each file you cite, then persist's file-assumption gate hard-errors on
-every `{path, assumption}` that misses the real tree.
-
-Entry fields (the `stories.template.json` shape):
+**Grounding = your reads + Phase 8.** Nothing inventories the repo: read each
+file you cite; persist's file-assumption gate hard-errors on any
+`{path, assumption}` absent from the tree. Entry fields:
 [reference](helpers/plan-reference.md).
 
 Artifacts under `temp/plan-<slug>/`: `stories.json` (**length 1 by default**;
-over-budget Specs fail closed — split or tighten, never under `docs/`);
-optional `techspec.md` (**N===1 only** — folded into `## Spec`); optional
-`acceptance-manifest.json` (N>1 partition list — `--plan-acceptance`). For N=1
-use the envelope `systemPrompts.story`; split only under the policy above.
+over-budget Specs fail closed — split or tighten, never under `docs/`); optional
+`techspec.md` (**N===1 only** — folded into `## Spec`); optional
+`acceptance-manifest.json` (N>1 partition — `--plan-acceptance`). For N=1 use
+the envelope `systemPrompts.story`; split only under the policy above.
 
 **Tickets mode:** every Story authors a top-level `supersedes[]`; persist
 refuses a partial map ([shape](helpers/plan-reference.md)).
@@ -123,28 +111,27 @@ node .agents/scripts/plan-critics.js \
   [--tech-spec temp/plan-<slug>/techspec.md]
 ```
 
-Run **before** persist — the last point a finding folds into a re-author round.
+Run **before** persist — the last point a finding folds into a re-author.
 It exits 0 on **any** verdict (verdicts route work, they do not gate) and exits
 **1** only on a usage/IO error — no critic ran, no skip ledgered: **do not
-proceed to Persist**; fix and re-run.
+proceed to Persist**, fix and re-run.
 
 - **Both `dispatch: false`** — proceed to Persist (each skip is ledgered).
 - **Either `dispatch: true`** — dispatch **one fresh-context, maker-blind
   sub-agent per firing critic** (hand it only the draft artifacts, never the
   authoring transcript), fold findings into Gate #2 or a re-author round, re-run
   this step. Pre-mortem triggers (incl. the external-dependency probe), the
-  advisory-only `textHygiene.findings[]` lints, and the dispatch shape:
-  [`helpers/plan-reference.md` § Critic dispatch detail](helpers/plan-reference.md).
+  advisory-only `textHygiene.findings[]` lints and dispatch shape:
+  [reference § Critic dispatch detail](helpers/plan-reference.md).
 
 ### 3. Persist
 
 **Gate #2** — STOP for approval before persist **only** when the operator asked
 to review (`--force-review`). Under `--yes`, auto-proceed.
 
-Run persist with `--dry-run` **first** — same command, GitHub writes suppressed;
-every gate (validator, body parse, DAG, capacity, budget, reachability,
-split/supersede partitions, Spec fold) runs before the first `createIssue`.
-Then:
+Run persist with `--dry-run` **first** — same command, writes suppressed;
+every gate runs before the first `createIssue`
+([the list](helpers/plan-reference.md)):
 
 ```bash
 node .agents/scripts/plan-persist.js \
@@ -155,28 +142,25 @@ node .agents/scripts/plan-persist.js \
   [--source-tickets 123,456]
 ```
 
-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.
-`agent::ready` is the **terminal** flip after all receipts land. stdout is pure
-JSON.
+At lite shape, `--chain-on-clean` folds a clean dry-run into the real persist;
+a full plan keeps its review trip.
 
-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)).
+Persist creates `type::story` issue(s), a **metadata-only** `plan-run::<id>`
+label, and `blocked by #<id>` footers for N>1 `depends_on` edges.
+`agent::ready` is the **terminal** flip after receipts land; stdout is pure
+JSON. Tickets mode also comments on and closes each source id
+([detail](helpers/plan-reference.md)).
 
 ## Constraints
 
 - `/plan` starts delivery **only** through a confirmed Gate #1 light route —
   never off its own authored Stories, which land via [`/deliver`](deliver.md).
-- Duplicate search targets open Stories (`type::story`), not Epics.
-- Deterministic gates still fail closed under `--yes`.
+- Duplicate search targets open Stories (`type::story`), not Epics; and
+  deterministic gates still fail closed under `--yes`.
 
 ## See also
 
-- [`/deliver`](deliver.md), [`/audit-to-stories`](audit-to-stories.md),
-  [`helpers/plan-reference.md`](helpers/plan-reference.md) — on-demand detail.
-- [`core/scope-triage`](../skills/core/scope-triage/SKILL.md) — optional
-  split-advisory notes only (no routing verdict).
+[`/deliver`](deliver.md), [`/audit-to-stories`](audit-to-stories.md),
+[`helpers/plan-reference.md`](helpers/plan-reference.md) (on-demand detail),
+[`core/scope-triage`](../skills/core/scope-triage/SKILL.md) — optional
+split-advisory notes only (no routing verdict).

package/docs/CHANGELOG.md

@@ -2,6 +2,44 @@
 
 All notable changes to this project will be documented in this file.
 
+## [2.25.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.24.0...mandrel-v2.25.0) (2026-08-01)
+
+
+### Added
+
+* enforce the no-rerun verifier: disarm auto-merge on the first red and gate re-arming on the head SHA moving ([#4865](https://github.com/dsj1984/mandrel/issues/4865)) ([#4867](https://github.com/dsj1984/mandrel/issues/4867)) ([b95267f](https://github.com/dsj1984/mandrel/commit/b95267fe49cd27ca7cd42bb3bc7ae0c6ceaa5a3a))
+
+
+### Fixed
+
+* **crap:** measure coordinate mixing, not ordinary drift, in the preview gate (refs [#4871](https://github.com/dsj1984/mandrel/issues/4871)) ([#4881](https://github.com/dsj1984/mandrel/issues/4881)) ([63bcb66](https://github.com/dsj1984/mandrel/commit/63bcb66ab46471cfc1b8ad957d60dd1526d0f679))
+* escape the remaining raw NUL delimiters so these diffs are reviewable ([#4896](https://github.com/dsj1984/mandrel/issues/4896)) ([992fc46](https://github.com/dsj1984/mandrel/commit/992fc46b7675736c8fc7af546600cc59ef5ec96d))
+* make the sanctioned CI watch survive a late-arriving required context, and pass --repo through as a real gh flag ([#4890](https://github.com/dsj1984/mandrel/issues/4890)) ([#4893](https://github.com/dsj1984/mandrel/issues/4893)) ([00c23f4](https://github.com/dsj1984/mandrel/commit/00c23f45f57f6b9d11c7314b92f337a31dda4c2b))
+* normalize audit severity and labels without re-minting fingerprints, carry dedupe provenance, and give the lenses a built-but-not-wired mandate ([#4877](https://github.com/dsj1984/mandrel/issues/4877)) ([#4888](https://github.com/dsj1984/mandrel/issues/4888)) ([04f8937](https://github.com/dsj1984/mandrel/commit/04f89373e4dcaa0a47d5501381fb02b5e29bcef6))
+* pin the run's base branch at init and fail closed when config changed mid-run (refs [#4891](https://github.com/dsj1984/mandrel/issues/4891)) ([#4894](https://github.com/dsj1984/mandrel/issues/4894)) ([8099020](https://github.com/dsj1984/mandrel/commit/8099020a9ea2e662c19a1c8a3d9e32d6269df863))
+* **plan:** reconcile the persist body contract and stop acceptance-eval burning a round on every read (refs [#4874](https://github.com/dsj1984/mandrel/issues/4874)) ([#4882](https://github.com/dsj1984/mandrel/issues/4882)) ([33512b4](https://github.com/dsj1984/mandrel/commit/33512b48702e50d9ebaf98dffc396a9ce0091290))
+* ratchet context-budget shrinkage and stop the baseline updaters writing on --help (refs [#4872](https://github.com/dsj1984/mandrel/issues/4872)) ([#4879](https://github.com/dsj1984/mandrel/issues/4879)) ([8d445a4](https://github.com/dsj1984/mandrel/commit/8d445a45e8a4c57b65573213042fb4aec557af08))
+* stamp the version cache with the real clock and end unquoted env values at an unescaped comment marker (refs [#4878](https://github.com/dsj1984/mandrel/issues/4878)) ([#4883](https://github.com/dsj1984/mandrel/issues/4883)) ([d73ee10](https://github.com/dsj1984/mandrel/commit/d73ee10c2f15c3698705281a5979c7394eb03fa4))
+* stop close-resume opening duplicate empty PRs and stop the PR watcher reporting green on a blocked PR ([#4873](https://github.com/dsj1984/mandrel/issues/4873)) ([#4884](https://github.com/dsj1984/mandrel/issues/4884)) ([9d12f8d](https://github.com/dsj1984/mandrel/commit/9d12f8dcd4badbe3b657f1526c284f7689bf04ee))
+* stop the CRAP row builder silently mixing transpiled and original line coordinates, and refuse to compare on an unsound basis ([#4866](https://github.com/dsj1984/mandrel/issues/4866)) ([#4868](https://github.com/dsj1984/mandrel/issues/4868)) ([a6c8c88](https://github.com/dsj1984/mandrel/commit/a6c8c8866c72b1372eb5fd5b7232fb3833e33f93))
+* stop the test suite writing fixture friction signals into the real ledger, and stop unresolvable Story ids reaching an auto-filed ticket ([#4892](https://github.com/dsj1984/mandrel/issues/4892)) ([#4895](https://github.com/dsj1984/mandrel/issues/4895)) ([a607de4](https://github.com/dsj1984/mandrel/commit/a607de49a09c778c1fbefe68d4c57d6a75f0b648))
+* warn about the un-waivable light-path verdict up front, de-conflict on actual footprints, and reconcile the concurrency override ([#4875](https://github.com/dsj1984/mandrel/issues/4875)) ([#4880](https://github.com/dsj1984/mandrel/issues/4880)) ([16d4958](https://github.com/dsj1984/mandrel/commit/16d49584227d783695bb36043e29c64a58aaab39))
+
+
+### Changed
+
+* reclaim workflow-spine byte headroom and move the close-and-land tail to the orchestrator (refs [#4876](https://github.com/dsj1984/mandrel/issues/4876)) ([#4885](https://github.com/dsj1984/mandrel/issues/4885)) ([7d981cd](https://github.com/dsj1984/mandrel/commit/7d981cde4f8c3d1047a09e64d1f193b85fbfd4b6))
+* widen workflow-spine and agent-boot headroom to a real editing margin (refs [#4876](https://github.com/dsj1984/mandrel/issues/4876)) ([#4889](https://github.com/dsj1984/mandrel/issues/4889)) ([45f5482](https://github.com/dsj1984/mandrel/commit/45f548238c9c82a1e36df11320b73c8f9dea27f5))
+
+## [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)
 
 

package/lib/cli/update.js

@@ -247,10 +247,15 @@ function resolveProjectRoot() {
  * `mandrel` version via the daily freshness cache (`version-check.js`).
  *
  * When `bypassCache` is `true` (the default for an explicit `mandrel update`
- * call — Story #4046 A1b), the cache freshness window is effectively zeroed by
- * passing `now` as far in the future, which makes `isStale` treat any existing
- * cache as stale and always issue exactly one network probe. The cache is still
- * written so the post-update `version-current` advisory has a fresh baseline.
+ * call — Story #4046 A1b), `isStale` is asked to skip its freshness read via
+ * `forceRefresh`, so any existing cache is ignored and exactly one network
+ * probe is issued. The cache is still written so the post-update
+ * `version-current` advisory has a fresh baseline.
+ *
+ * The bypass deliberately does **not** shift `now`: the same clock is stamped
+ * into the refreshed `checkedAt`, so a shifted clock would persist a
+ * ~48h-future timestamp and defeat the 24h window for every later passive
+ * check until real time caught up (Story #4878).
  *
  * When `bypassCache` is `false` (passive staleness checks only), the normal
  * 24h-cache semantics apply: a fresh cache returns the cached version with
@@ -281,16 +286,14 @@ async function defaultResolveTargetVersion({
   bypassCache = false,
   log = () => {},
 } = {}) {
-  // When bypassCache is true, push `now` far enough into the future that any
-  // cached checkedAt value is guaranteed to be older than the STALE_AFTER_MS
-  // window, forcing a fresh network probe (Story #4046 A1b).
-  const effectiveNow = bypassCache
-    ? new Date(now.getTime() + 48 * 60 * 60 * 1000)
-    : now;
+  // Bypass the cache by telling isStale to skip its freshness read — never by
+  // shifting `now`, which is also the clock persisted as `checkedAt`
+  // (Story #4046 A1b forcing the probe; Story #4878 keeping the stamp honest).
   const result = await isStale({
     cachePath,
-    now: effectiveNow,
+    now,
     runner,
+    forceRefresh: bypassCache,
     fs,
     log,
   });

package/lib/cli/version-check.js

@@ -142,10 +142,17 @@ export function refreshCache({
  * The freshness comparison uses `>=` so an exactly-24h-old cache counts as
  * stale (the boundary is treated as "due for refresh").
  *
+ * `forceRefresh` skips the freshness read entirely and always probes. It is
+ * the supported way to bypass the cache: callers must **not** fake staleness
+ * by shifting `now` forward, because `now` is also the clock stamped into the
+ * refreshed `checkedAt` — a shifted clock persists a future timestamp and
+ * defeats the freshness window for every later reader (Story #4878).
+ *
  * @param {{
  *   cachePath: string,
  *   now?: Date,
  *   runner: () => (string | Promise<string>),
+ *   forceRefresh?: boolean,
  *   fs?: typeof import('node:fs'),
  *   log?: (msg: string) => void,
  * }} opts
@@ -160,10 +167,11 @@ export async function isStale({
   cachePath,
   now = new Date(),
   runner,
+  forceRefresh = false,
   fs = nodeFs,
   log = () => {},
 }) {
-  const cached = readCache({ cachePath, fs });
+  const cached = forceRefresh ? null : readCache({ cachePath, fs });
 
   if (cached) {
     const ageMs = now.getTime() - new Date(cached.checkedAt).getTime();

package/package.json

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