mandrel 2.30.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/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,13 @@ 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)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mandrel",
-  "version": "2.30.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/",