mandrel 2.57.0 → 2.58.0

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

@@ -154,6 +154,11 @@ and ceremony is derived from the landed diff at close.
 - **`verify[]` entries are commands.** There is no tier suffix and no
   `manual:<reason>` escape (Story #5312): write the exact command or test
   path the deliverer runs and the acceptance critic reads as evidence.
+- **`changes[]` names what the deliverer authors.** Generated artifacts —
+  quality baselines, generated test indexes, migration journals, lockfiles —
+  are omitted: the work regenerates them, the refresh is a close-gate concern,
+  and a declared shared artifact path reserves a footprint that needlessly
+  serializes sibling Stories at dispatch.
 - **`changes[]` arrive pre-resolved to creates-vs-refactors.** Every path
   the seed predicted is probed against the repo: an existing path is
   emitted with `assumption: "refactors-existing"`, a missing one with
@@ -175,8 +180,14 @@ kept — passes the persist ticket validators with no round-trip.
 Each `stories.json` entry: `slug` (`^[a-z0-9][a-z0-9-]*$`), `type: "story"`,
 `title`, `body` (`goal`, optional `spec`, `changes[{path, assumption}]` —
 `creates|refactors-existing|deletes`, `non_goals`, `reason_to_exist`),
-top-level `acceptance[]`, `verify[]` (`… (unit|contract|e2e|validate)`), and
-`depends_on[]` (a sibling slug, or `#<id>` for an existing open Story).
+top-level `acceptance[]`, `verify[]` (each a **bare command** — there is no
+tier suffix), and `depends_on[]` (a sibling slug, or `#<id>` for an existing
+open Story).
+
+Author `acceptance[]` **without** the `AC-<n>:` handle: the body renderer
+numbers each checkbox from its array position, so a carried handle renders
+doubled. Persist normalises one off rather than refusing, and names the strip
+on the dry-run's repair list.
 
 Nothing in that shape inventories the repo for the author. `changes[]` arrives
 pre-resolved against the working tree, and Phase 8's
@@ -256,6 +267,21 @@ and a path reference matched by substring can read as a dependency a prose
 mention never meant. A finding names the Stories and the fix (a `depends_on`
 edge, or folding the shared edit into one Story) for the operator to weigh.
 
+## Tickets mode — the source ticket is evidence
+
+A `--tickets` envelope carries a third author prompt beside
+`systemPrompts.story` and `systemPrompts.storySplitRules`:
+**`systemPrompts.storyTicketsRules`**. It exists because a
+source ticket arrives already in Story shape — rendered `AC-<n>:` checkboxes,
+a `## Verify` list, a `## Changes` footprint — and an author reading it as a
+template carries that shape forward instead of re-deriving it. The addendum
+binds the author to re-derive `acceptance[]` from the goal, to express
+mechanical checks (a refreshed baseline, a lint exiting 0, a regenerated
+index) as `verify[]` commands rather than acceptance items, and to take the
+source's verify entries for the commands they name rather than their shape.
+Read it whenever the mode is `tickets`; the other three modes do not carry
+the field.
+
 ## Tickets mode — authoring `supersedes[]`
 
 In `--tickets` mode each Story carries a top-level `supersedes` array claiming
@@ -347,10 +373,13 @@ at base.
 exists at base or a `refactors-existing` on one that does not (including a
 path the base branch deleted or renamed, named with the removing commit), a
 goal or acceptance path absent at base, a `verify[]` command naming an absent
-test file, and an `open-question` in a body (`Flag if…`, `TBD`, a trailing
-`?`). The list also names every `changes[]` **repair** the run applied — a
-plain-string bullet or a trailing parenthetical rewritten into
-`{ path, assumption }` by probing base. The same list rides the result
+test file, an `open-question` in a body (`Flag if…`, `TBD`, a trailing `?`),
+and a `pinned-identifier` in an acceptance item — a backticked bare symbol
+that is not a path, a label, a kebab token, a flag or a command, which the
+advisory `changes[]` is free to reshape out from under the criterion. The
+list also names every **repair** the run applied — a plain-string bullet or a
+trailing parenthetical rewritten into `{ path, assumption }` by probing base,
+and an `AC-<n>:` handle normalised off an acceptance item. The same list rides the result
 envelope as `warnings[]` and `repairs[]`, so a `--chain-on-clean` run loses
 nothing.
 

package/.agents/workflows/mandrel-plan.md

@@ -57,7 +57,8 @@ and derives source ids from its `sourceTickets[]`; it also writes
 **`stories.template.json`**, step 2's skeleton.
 
 The envelope carries docs context, the story-author prompt (`systemPrompts.story`,
-plus `systemPrompts.storySplitRules` for an N>1 draft), `sourceTickets[]`,
+plus `systemPrompts.storySplitRules` for an N>1 draft and
+`systemPrompts.storyTicketsRules` in tickets mode), `sourceTickets[]`,
 `duplicates[]` (open **Stories**, never Epics), `epicCandidates[]` +
 `dependencyCandidates[]` (Gate #3; path collisions), `priorFeedback` and
 advisory `complexitySignals` (**no routing authority**). An envelope over the
@@ -97,7 +98,10 @@ a Spec is as long as the work needs, inline, never under `docs/`); optional
 `acceptance-manifest.json` (N>1 — `--plan-acceptance`). Use the envelope
 `systemPrompts.story`; split only under the policy above, and when you do,
 read `systemPrompts.storySplitRules` too — it carries the schedule and
-partition rules the core omits.
+partition rules the core omits. In **tickets mode** also read
+`systemPrompts.storyTicketsRules`: the source ticket is evidence, not a
+template — re-derive `acceptance[]` rather than carrying its list, handles
+and tier suffixes forward.
 
 **Tickets mode:** every Story authors a top-level `supersedes[]`; persist
 refuses a partial map ([shape](helpers/plan-reference.md)).

package/docs/CHANGELOG.md

@@ -15,6 +15,19 @@ All notable changes to this project will be documented in this file.
 -->
 <!-- markdownlint-disable-file MD004 MD012 MD037 -->
 
+## [2.58.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.57.0...mandrel-v2.58.0) (2026-09-12)
+
+
+### Added
+
+* make the close test credit earnable on any test runner, and surface the gap at setup instead of mid-close ([#5324](https://github.com/dsj1984/mandrel/issues/5324)) ([#5329](https://github.com/dsj1984/mandrel/issues/5329)) ([04db145](https://github.com/dsj1984/mandrel/commit/04db145b8f1017121e129897f9207ab51db1c3f8))
+* tickets-mode planning re-derives the Story instead of carrying the source ticket's shape: acceptance handles, tier suffixes, generated-artifact footprints and pinned identifiers ([#5323](https://github.com/dsj1984/mandrel/issues/5323)) ([#5326](https://github.com/dsj1984/mandrel/issues/5326)) ([5563e7a](https://github.com/dsj1984/mandrel/commit/5563e7a264864f78001beb19ce58160a1b483cda))
+
+
+### Fixed
+
+* give base-sync and the Story-scope code review one base ref, so a stale local base branch cannot raise false blockers ([#5325](https://github.com/dsj1984/mandrel/issues/5325)) ([#5328](https://github.com/dsj1984/mandrel/issues/5328)) ([c4032b6](https://github.com/dsj1984/mandrel/commit/c4032b63a63c4cb8cc3f9c9956b6c646e5acd460))
+
 ## [2.57.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.56.0...mandrel-v2.57.0) (2026-09-12)
 
 

package/lib/cli/registry.js

@@ -4,8 +4,11 @@
  *
  * Exports an ordered array of check objects each shaped `{ name, run() }`.
  * `run()` returns `{ ok, detail, remedy? }` — `remedy` is present and
- * non-empty only when `ok` is false. The registry is the single source of
- * truth for which checks the doctor command runs and in what order.
+ * non-empty whenever `ok` is false, and on an `advisory` check that passes
+ * while still having something actionable to say (`test-credit-path`), which
+ * repeats it in `detail` because that is the field the doctor prints for a
+ * passing check. The registry is the single source of truth for which checks
+ * the doctor command runs and in what order.
  *
  * Checks run sequentially in the doctor runner (not in parallel) because
  * some checks are meaningless without a prerequisite having passed first
@@ -1176,6 +1179,90 @@ function probeConfiguredDriver(command, runner, projectRoot) {
   };
 }
 
+// ---------------------------------------------------------------------------
+// check: test-credit-path
+// ---------------------------------------------------------------------------
+
+/**
+ * The runner whose own green full run deposits the close `test` credit as a
+ * side effect (`.agents/scripts/run-tests.js` → `lib/test-run-credit.js`).
+ */
+const MANDREL_TEST_RUNNER = 'run-tests.js';
+
+/**
+ * The deposit that works whatever `npm test` resolves to: it spawns the
+ * project's own suite and stamps the result, so it is honest by construction.
+ */
+const TEST_CREDIT_DEPOSIT_COMMAND =
+  'node .agents/scripts/evidence-gate.js --standalone --scope-id <storyId> --gate test --worktree <workCwd> -- npm test';
+
+/** Remedy shared by every shape that does not earn the credit on its own. */
+const TEST_CREDIT_REMEDY = `run the suite through the depositor instead of bare \`npm test\`: ${TEST_CREDIT_DEPOSIT_COMMAND}`;
+
+/**
+ * The project's `test` script — what `npm test` runs, and therefore what the
+ * close `test` gate spawns. Deliberately read from `package.json` rather than
+ * `project.commands.test`: the close gate's argv is the literal `npm test`, so
+ * the npm script is the command whose shape decides whether a bare run
+ * deposits anything.
+ *
+ * @param {string} projectRoot
+ * @param {typeof fs.readFileSync} readFileImpl
+ * @returns {string|null} The trimmed script, or null when there is none.
+ */
+function readProjectTestScript(projectRoot, readFileImpl) {
+  try {
+    const raw = readFileImpl(path.join(projectRoot, 'package.json'), 'utf8');
+    const script = JSON.parse(raw)?.scripts?.test;
+    return typeof script === 'string' && script.trim().length > 0
+      ? script.trim()
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Report whether this project's test command reaches mandrel's own runner,
+ * and therefore whether a bare `npm test` deposits the close `test` credit
+ * by itself (Story #5324).
+ *
+ * **Always `ok: true`.** A project on `vitest`, `jest` or any other runner is
+ * a supported setup, not a broken install — the only thing it lacks is the
+ * runner-side bonus deposit, and the remedy command covers it. So the check
+ * informs rather than gates, and (unlike every other entry here) carries its
+ * `remedy` alongside a passing verdict; the same guidance also rides in
+ * `detail`, which is the field the doctor prints for a passing check.
+ *
+ * The runner is detected by name, never by executing anything: a script that
+ * reaches `run-tests.js` indirectly reads as "own runner", which errs toward
+ * naming the deposit command — correct on either shape.
+ *
+ * @param {{ projectRoot?: string, readFile?: typeof fs.readFileSync }} [opts]
+ * @returns {{ ok: boolean, detail: string, remedy?: string }}
+ */
+function runTestCreditPath({ projectRoot, readFile = fs.readFileSync } = {}) {
+  const script = readProjectTestScript(projectRoot ?? process.cwd(), readFile);
+  if (script === null) {
+    return {
+      ok: true,
+      detail: `no \`test\` script in package.json — close still spawns \`npm test\`, so ${TEST_CREDIT_REMEDY}`,
+      remedy: TEST_CREDIT_REMEDY,
+    };
+  }
+  if (script.includes(MANDREL_TEST_RUNNER)) {
+    return {
+      ok: true,
+      detail: `\`npm test\` → \`${script}\` reaches mandrel's runner — a green full run on a story branch deposits the close \`test\` credit itself`,
+    };
+  }
+  return {
+    ok: true,
+    detail: `\`npm test\` → \`${script}\` is this project's own runner and never reaches \`${MANDREL_TEST_RUNNER}\`, so it deposits no close \`test\` credit and prints nothing — ${TEST_CREDIT_REMEDY}`,
+    remedy: TEST_CREDIT_REMEDY,
+  };
+}
+
 /**
  * Ordered array of doctor checks. Each entry follows the
  * `{ name: string, run(opts?): { ok: boolean, detail: string, remedy?: string } }` contract.
@@ -1243,6 +1330,15 @@ export const registry = [
     advisory: true,
     run: (opts) => runVersionCurrent(opts),
   },
+  {
+    name: 'test-credit-path',
+    // Non-fatal: `run()` always returns ok:true. A project on its own test
+    // runner is a supported setup that simply has to deposit the close
+    // `test` credit explicitly, so this reports a condition rather than
+    // failing the install (Story #5324).
+    advisory: true,
+    run: (opts) => runTestCreditPath(opts),
+  },
 ];
 
 export default registry;

package/package.json

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