mandrel 2.29.0 → 2.31.0

package/.agents/rules/ci-remediation.md

@@ -51,6 +51,7 @@ the two options above. Name the verdict you reached in the `friction` comment.
 | **defect-in-diff** | The failure reproduces on the branch and not on an unmodified `main` | Option 1 — fix at source |
 | **pre-existing** | The same check fails on an unmodified `main` too | Option 2 — file `meta::framework-gap`; remediate here only if it blocks this delivery |
 | **capacity** | Proven exhaustion of a runner resource, not a property of the diff (see below) | Option 2 — file `meta::framework-gap` **and** escalate to the operator |
+| **unreproducible-tier** | The tier cannot be exercised in this sandbox at all, proven by an attempted attach (see below) | Option 2 — file `meta::framework-gap` **and** escalate on first encounter |
 
 ### The `capacity` verdict
 
@@ -82,10 +83,46 @@ the operator, who owns the runner pool. Do not sit in a retry loop waiting for
 capacity to return.
 
 **Rerunning a failed job to reach green stays forbidden under every verdict,
-`capacity` included.** The verdict changes who owns the fix and where it is
+`capacity` and `unreproducible-tier` included.** The verdict changes who owns the fix and where it is
 filed; it never licenses a re-run, and it is not a route to a green bar. A
 capacity-blocked delivery ends `agent::blocked` — not merged.
 
+### The `unreproducible-tier` verdict
+
+A check can fail on a tier the sandbox cannot run at all — most often a
+browser suite whose Playwright `webServer` block supervises a dev server the
+local process manager daemonizes, which aborts the run with
+`Process from config.webServer exited early` before any test executes. The
+failure is a property of the sandbox's ability to *host* the suite, not of the
+diff.
+
+This is the same structural hole the `capacity` verdict was added to fill, one
+step earlier in the loop. Without it the honest reading is `flaky`, which routes
+to Option 1 — and fix-at-source requires reproducing the failure, which is the
+one thing that cannot be done. The agent then spends the full timebox
+rediscovering that before escalating anyway, and any fix it does author is
+written blind against a tier it never ran.
+
+**Unreproducible must be proven, not inferred.** "The suite did not run for me"
+is not the verdict — it is the symptom every misconfiguration produces. Cite
+both:
+
+- **The attempted attach.** Work the attach-don't-boot seam in the
+  [`playwright`](../skills/stack/qa/playwright/SKILL.md) skill — boot the server
+  out-of-band, point the suite at the running origin, set `reuseExistingServer`
+  — and name which step failed and how. A tier that runs once attached was never
+  unreproducible.
+- **The observed signature.** The verbatim line the runner aborted on, so a
+  later reader can tell a lifetime-ownership mismatch from a genuine boot
+  failure in the app under test.
+
+Absent both readings the verdict is unavailable and the failure routes as it did
+before. On the verdict: file the `meta::framework-gap` issue with the run link,
+the failure signature, and the attach attempt; flip the Story to
+`agent::blocked` with a `friction` comment naming the verdict; and hand back to
+the operator, who owns the sandbox. Do not author a fix for a tier you could not
+run — a blind fix to a suite nobody exercised is how the gap compounds.
+
 ## Verifier
 
 The check is resolved only when it is **green with zero reruns of the failed
@@ -131,3 +168,9 @@ operator under **any** of:
   signature) and escalate on the first encounter rather than burning iterations
   trying to code around it. A proven-capacity failure is this case: reach the
   `capacity` verdict above and escalate on the first encounter.
+- **Unrunnable tier → escalate immediately.** A tier the sandbox cannot host at
+  all is this case too: work the attach seam once, reach the
+  `unreproducible-tier` verdict above with its two readings, and escalate on the
+  **first encounter**. The 30-minute timebox is a ceiling here, never a budget
+  to spend — every minute past the failed attach buys nothing, because no
+  iteration can make an unhostable suite run.

package/.agents/scripts/lib/crap-utils.js

@@ -106,6 +106,73 @@ function resolveBaselinePath({ cwd = process.cwd(), baselinePath } = {}) {
  *   rows: Array<{file: string, method: string, startLine: number, crap: number}>,
  * }|null}
  */
+/**
+ * The envelope-level fields the CRAP compat axes read off a *loaded* baseline
+ * — the set every read path owes `assertBaselineCompatible`.
+ *
+ * It exists because there are TWO read paths and they have now diverged three
+ * times. `check-baselines` loads through `baselines/reader.js`; the
+ * `quality-preview` pre-commit arm loads through `projectCrapEnvelopeToLegacy`
+ * below. Both are ALLOW-LISTS, both feed the same axes, and a stamp added to
+ * one and not the other yields two opposite verdicts on one file: Story #4866
+ * (`scoringSemantics`, `tsTranspilerVersion`), Story #4969 (`rows[].anonymous`)
+ * and Story #4986 (`provenanceStamped`, half-fixed by #4973) were each that
+ * same half-landing.
+ *
+ * Every one of those axes keys on a POSITIVE marker, so a dropped field reads
+ * `undefined` and fails the baseline closed with a remedy that cannot work —
+ * re-deriving it writes the stamp the read path then discards. The projection
+ * below is DERIVED from this list rather than repeating it, so a new stamp is
+ * carried here the moment it is named; a parity test holds the reader to the
+ * same set and names whichever path forgot one.
+ *
+ * Row-level markers are deliberately out: they are projected per-row, not as
+ * envelope stamps.
+ *
+ * Deliberately module-local, mirroring `SCORING_SEMANTICS` in
+ * `baselines/kinds/crap.js`: the writer's `envelopeExtras()` is the single
+ * production door to the stamp set, and exporting this list would add a second
+ * one that only a test reaches. The parity test holds this projection to
+ * `Object.keys(envelopeExtras())` instead, so a stamp the writer starts
+ * emitting fails the test here until it is named — which is the enforcement
+ * this list needs, not an export.
+ */
+const COMPAT_STAMP_FIELDS = Object.freeze([
+  'scoringSemantics',
+  'tsTranspilerVersion',
+  'provenanceStamped',
+]);
+
+/**
+ * Per-stamp coercion applied on the way through the legacy projection. A field
+ * with no entry is carried VERBATIM, which is the correct default: the axes
+ * distinguish "stamped" from "absent", so inventing a value for a stamp the
+ * envelope never wrote is the one thing a read path must not do.
+ */
+const COMPAT_STAMP_NORMALIZERS = {
+  // `null` (not the running value) when unstamped, so `ts-transpiler-drift`
+  // can tell "written by a different transpiler" from "written before the
+  // stamp existed" instead of comparing a value against itself.
+  tsTranspilerVersion: (value) => (typeof value === 'string' ? value : null),
+  scoringSemantics: (value) => value ?? null,
+};
+
+/**
+ * Project the compat stamps off a v2 envelope, driven by
+ * `COMPAT_STAMP_FIELDS`.
+ *
+ * @param {Record<string, unknown>} parsed
+ * @returns {Record<string, unknown>}
+ */
+function projectCompatStamps(parsed) {
+  const stamps = {};
+  for (const field of COMPAT_STAMP_FIELDS) {
+    const normalize = COMPAT_STAMP_NORMALIZERS[field];
+    stamps[field] = normalize ? normalize(parsed[field]) : parsed[field];
+  }
+  return stamps;
+}
+
 /**
  * Story #1895: shipped baseline switched to the canonical envelope shape
  * (`$schema`, `kernelVersion`, `generatedAt`, `rollup`, `rows` keyed on
@@ -122,6 +189,16 @@ function resolveBaselinePath({ cwd = process.cwd(), baselinePath } = {}) {
  * They are carried verbatim now, `null` when the envelope never stamped them,
  * so an axis can tell "written by a different transpiler" apart from "written
  * before the stamp existed" instead of guessing.
+ *
+ * **This projection is one of TWO (Story #4986).** `check-baselines` reads a
+ * baseline through `baselines/reader.js`; `quality-preview` reads the same file
+ * through here. Both feed `assertBaselineCompatible`, so a stamp added to one
+ * allow-list and not the other produces two opposite verdicts on one envelope —
+ * which is what happened to `provenanceStamped`: #4973 added it to the reader
+ * and left this projection dropping it, so the pre-commit CRAP arm rejected
+ * every stamped baseline with an un-satisfiable "re-seed" remedy while the
+ * authoritative gate passed. The stamp block is derived from
+ * `COMPAT_STAMP_FIELDS` above so this projection cannot fall behind again.
  */
 function projectCrapEnvelopeToLegacy(parsed) {
   if (
@@ -134,11 +211,7 @@ function projectCrapEnvelopeToLegacy(parsed) {
   return {
     kernelVersion: parsed.kernelVersion,
     escomplexVersion: resolveEscomplexVersion(),
-    tsTranspilerVersion:
-      typeof parsed.tsTranspilerVersion === 'string'
-        ? parsed.tsTranspilerVersion
-        : null,
-    scoringSemantics: parsed.scoringSemantics ?? null,
+    ...projectCompatStamps(parsed),
     rows: parsed.rows.map((row) => ({
       crap: row.crap,
       file: row.path,

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

@@ -15,6 +15,18 @@
  * added because it would re-ask a question the push exit code already
  * answered authoritatively.
  *
+ * Issue #4990 — the push runs in the Story worktree, not the main
+ * checkout. `core.hooksPath` is the relative `.husky/_`, so the
+ * invocation directory is what selects which tree `pre-push` resolves
+ * and measures. Pushing from the main checkout therefore validated a
+ * tree other than the one being sent — false red when that checkout sat
+ * on unrelated work, and worse, false green whenever it happened to be
+ * clean. `worktreePath` falls back to `cwd` because single-tree mode and
+ * a disabled `delivery.worktreeIsolation` both legitimately have no
+ * worktree, and there the main checkout IS the tree being pushed. The
+ * two sibling phases resolve their tree the same way
+ * (`base-sync.js`, `close-validation.js`).
+ *
  * `gitSync` is accepted as an injected dependency rather than statically
  * imported so the caller's (cache-busted) binding wins. The
  * `single-story-close.js` orchestrator owns the static import; test
@@ -29,6 +41,7 @@ import { gitSync as defaultGitSync } from '../../../git-utils.js';
  *
  * @param {{
  *   cwd: string,
+ *   worktreePath?: string|null,
  *   storyBranch: string,
  *   gitSync?: typeof defaultGitSync,
  *   progress: (tag: string, msg: string) => void,
@@ -36,6 +49,7 @@ import { gitSync as defaultGitSync } from '../../../git-utils.js';
  */
 export function pushStoryBranch({
   cwd,
+  worktreePath = null,
   storyBranch,
   gitSync = defaultGitSync,
   progress,
@@ -46,8 +60,9 @@ export function pushStoryBranch({
     // before this point, but `--skip-validation` skips that chain, and the
     // bypass then left nothing running at all. `pre-push` is the backstop,
     // and it only became reachable once hooks were materialized into
-    // worktrees — which is where every Story branch is built.
-    gitSync(cwd, 'push', '-u', 'origin', storyBranch);
+    // worktrees — which is where every Story branch is built, and where the
+    // cwd below now resolves so the hook reads that tree.
+    gitSync(worktreePath ?? cwd, 'push', '-u', 'origin', storyBranch);
     progress('GIT', `✅ Pushed ${storyBranch}.`);
   } catch (err) {
     throw new Error(

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

@@ -201,6 +201,7 @@ async function runPrePushPhases({
 
 async function openAndReviewPr({
   cwd,
+  worktreePath,
   story,
   storyId,
   storyBranch,
@@ -211,7 +212,11 @@ async function openAndReviewPr({
   setPhase = () => {},
 }) {
   setPhase('push');
-  pushStoryBranch({ cwd, storyBranch, gitSync, progress });
+  // Issue #4990 — push from the Story worktree so `pre-push` measures the
+  // tree being sent. `gh` and the review's ref-based diffs below keep the
+  // caller's `cwd`: they read the shared `.git`, so they resolve identically
+  // from either tree.
+  pushStoryBranch({ cwd, worktreePath, storyBranch, gitSync, progress });
   setPhase('pull-request');
   const { url: prUrl, alreadyMerged } = await ensurePullRequestWith({
     cwd,
@@ -729,6 +734,7 @@ async function runClosePipeline({
     () =>
       openAndReviewPr({
         cwd: options.cwd,
+        worktreePath,
         story,
         storyId: options.storyId,
         storyBranch,

package/.agents/skills/skills.index.json

@@ -1,5 +1,5 @@
 {
-  "generatedAt": "2026-08-02T11:35:53.522Z",
+  "generatedAt": "2026-08-05T00:59:17.768Z",
   "generator": "generate-skills-index.js@1",
   "skills": [
     {
@@ -148,7 +148,7 @@
       "category": "qa",
       "path": ".agents/skills/stack/qa/playwright/SKILL.md",
       "description": "Robust E2E browser testing with Playwright. Use when writing browser-driven tests — leverage auto-waiting (no `waitForTimeout`), prefer user-visible locators (`getByRole`, `getByText`, `getByLabel`) over CSS/XPath, reuse `storageState` for auth, and enable trace-on-first-retry for CI debugging.",
-      "policyCapsuleBullets": 7,
+      "policyCapsuleBullets": 8,
       "allowedTools": null,
       "vendor": "playwright"
     },

package/.agents/skills/stack/qa/playwright/SKILL.md

@@ -19,3 +19,51 @@ vendor: playwright
 - Write tests independent of one another so they run in parallel; clean up shared state in fixtures, not afterwards.
 - Enable `trace: 'on-first-retry'` (or `'retain-on-failure'`) so CI failures are debuggable in the Trace Viewer.
 - Use a unique data set per test run, or tear down state explicitly, to prevent cross-test contamination.
+- Never let Playwright own the lifetime of a dev server it did not start: boot the server out-of-band, point the suite at the running origin, and set `reuseExistingServer` so `webServer` only probes readiness.
+
+## Running a `webServer`-backed suite outside CI
+
+Playwright's `webServer` block **watches the process it spawned**. That
+assumption holds for a dev server that stays in the foreground, and breaks for
+any manager that daemonizes one — the foreground process exits `0` while the
+server keeps serving, Playwright reads the exit as a crash, and the run aborts
+before a single test executes:
+
+```text
+Process from config.webServer exited early
+```
+
+Read that line as a **lifetime-ownership mismatch, not a flake**. It reproduces
+on every invocation, clean tree or not, and no amount of retrying, tree-cleaning
+or timeout-raising changes it. Agent sandboxes and IDE harnesses commonly manage
+dev servers this way (`Dev server already running at … (pid N)`), so an agent
+meets this far more often than a developer does.
+
+### Attach, don't boot
+
+Invert the ownership instead of fighting it — the manager owns the process,
+Playwright owns only the probe:
+
+1. **Boot the server out-of-band** through whatever manages it, and confirm it
+   is serving. Its lifetime is now the manager's concern, not the runner's.
+2. **Point the suite at the already-running origin** — set the config's
+   `baseURL` (or the `webServer.url` the block probes) to that origin, via the
+   project's own environment seam rather than an edit to committed config.
+3. **Set `reuseExistingServer: true`** so Playwright probes the URL, finds it
+   live, and never spawns or supervises a process of its own.
+
+This is the same convention the QA harness already encodes as
+`qa.environments[].baseUrl`: attach to a running origin, never boot one. A suite
+run this way exercises identical browser behavior — only the process supervision
+differs.
+
+### When no attachable origin exists
+
+Some apps genuinely cannot be reached this way — the server is unreachable from
+the sandbox, or the suite depends on a build step the sandbox cannot run. Do
+**not** burn a timebox rediscovering that. Record the observed signature, state
+which of the three steps above failed, and escalate on the first encounter:
+that evidence is exactly what the `unreproducible-tier` verdict in
+[`ci-remediation.md`](../../../../rules/ci-remediation.md) requires, and it is
+the only verdict that lets an unrunnable tier route somewhere other than a dead
+end.

package/docs/CHANGELOG.md

@@ -15,6 +15,20 @@ All notable changes to this project will be documented in this file.
 -->
 <!-- markdownlint-disable-file MD004 MD012 MD037 -->
 
+## [2.31.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.30.0...mandrel-v2.31.0) (2026-08-05)
+
+
+### Added
+
+* **qa:** add an attach-don't-boot seam and an unreproducible-tier verdict (refs [#4994](https://github.com/dsj1984/mandrel/issues/4994)) ([#4995](https://github.com/dsj1984/mandrel/issues/4995)) ([dac7986](https://github.com/dsj1984/mandrel/commit/dac79868a305e34db01005f06f638fc384c21c17)), closes [#4993](https://github.com/dsj1984/mandrel/issues/4993)
+
+## [2.30.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.29.0...mandrel-v2.30.0) (2026-08-04)
+
+
+### Fixed
+
+* **baselines:** carry provenanceStamped through the legacy CRAP projection ([#4986](https://github.com/dsj1984/mandrel/issues/4986)) ([#4987](https://github.com/dsj1984/mandrel/issues/4987)) ([921b521](https://github.com/dsj1984/mandrel/commit/921b521f2094c961fec84acca1f90e068cb77798))
+
 ## [2.29.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.28.0...mandrel-v2.29.0) (2026-08-03)
 
 

package/package.json

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