mandrel 2.38.0 → 2.40.0

package/.agents/README.md

@@ -322,9 +322,12 @@ in `runtime-deps.json`.
 Orchestration and planning are **Story-only** (`type::story`) — `/mandrel-plan`
 persists Stories with inline `acceptance[]` / `verify[]` and a folded
 `## Spec`; `/mandrel-deliver` runs `helpers/deliver-story` on `story-<id>` → PR →
-`main`. There is no `type::epic` / `type::task` label, Epic issue form, or
-`epic/<id>` integration branch; a ticket carrying an `Epic: #N` footer is
-refused by `/mandrel-deliver`. The execution-model contract is owned by
+`main`. There is no `type::task` label, Epic issue form, or `epic/<id>`
+integration branch; a ticket carrying an `Epic: #N` footer is refused by
+`/mandrel-deliver`. `type::epic` exists as a **pure container** — a goal plus a
+child checklist, never delivered itself, expanded to its open Stories by
+`/mandrel-deliver <epicId>` — and its linkage is parent→child only, which is
+what keeps that footer refused. The execution-model contract is owned by
 [`instructions.md` § 5.B](instructions.md) and [`docs/SDLC.md`](docs/SDLC.md).
 
 ---
@@ -775,7 +778,16 @@ time by `resolveQaContract`. Copy the reference shape from
   "qa": {
     "featureRoot": "tests/features",                 // root the selector resolves .feature files against
     "fixturesManifest": "tests/fixtures/personas.json", // persona → seed-data manifest
-    "signInSeam": { "urlTemplate": "/dev/sign-in-as/{persona}" }, // dev seam (see step 3)
+    "environments": {                                // one entry per deployment target
+      "local": {
+        "baseUrl": "http://localhost:3000",
+        "signInSeam": { "urlTemplate": "/dev/sign-in-as/{persona}" } // dev seam (see step 3)
+      },
+      "staging": {
+        "baseUrl": "https://staging.example.test",
+        "allowWrites": false                         // no signInSeam — an honestly seamless target
+      }
+    },
     "personas": ["admin", "member"],                 // name-only array — the honest shape for a url-template seam
     "consoleAllowlist": ["[HMR]"],                   // optional benign-noise filter (default [])
     "designTokens": "src/styles/tokens.css"          // optional visual-check pointer (default null)
@@ -783,8 +795,9 @@ time by `resolveQaContract`. Copy the reference shape from
 }
 ```
 
-`featureRoot`, `fixturesManifest`, `signInSeam`, and `personas` are mandatory;
-omitting any one makes the resolver throw a field-named error.
+`featureRoot`, `fixturesManifest`, `environments`, and `personas` are mandatory;
+omitting any one makes the resolver throw a field-named error. Within an
+environment only `baseUrl` is required — `signInSeam` is optional (see step 3).
 `consoleAllowlist` and `designTokens` default to `[]` and `null`.
 
 `personas` accepts **two shapes** (the resolver normalizes both to one
@@ -800,13 +813,16 @@ canonical internal map keyed by persona name):
   (or credential) seam where that material is genuinely consulted:
 
   ```jsonc
-  "signInSeam": { "skill": "stack/qa/sign-in" },
+  "signInSeam": { "skill": "stack/qa/acme-sso" }, // a skill YOU author (see step 3)
   "personas": {
     "admin": { "credentialRef": "QA_ADMIN_CREDENTIAL" }, // stored-credential reference, never an inline secret
-    "member": { "signInSkill": "stack/qa/sign-in-member" } // or a per-persona sign-in skill
+    "member": { "signInSkill": "stack/qa/acme-sso-member" } // or a per-persona sign-in skill
   }
   ```
 
+  Both skill ids above are **illustrative names for skills you write** — the
+  framework ships no sign-in skill. Step 3 says where they go.
+
 ### 2. Author the fixtures manifest
 
 Create the file referenced by `fixturesManifest`. It binds each persona to the
@@ -824,9 +840,33 @@ credentials are never entered. Expose one of two shapes:
 - **`{ urlTemplate }`** — a dev sign-in route where `{persona}` is substituted
   (e.g. `/dev/sign-in-as/{persona}` → `/dev/sign-in-as/admin`); gate it to
   non-production builds. Pair with the name-only `personas` array.
-- **`{ skill }`** — when sign-in is multi-step or non-URL, point at a consumer
-  skill whose `SKILL.md` the harness reads. Pair with the object-map
-  `personas` form (per step 1).
+- **`{ skill }`** — when sign-in is multi-step or non-URL, name a skill by its
+  tier-relative id (e.g. `stack/qa/acme-sso`) whose `SKILL.md` the harness
+  reads. Pair with the object-map `personas` form (per step 1).
+- **Omit it entirely** — the honest shape for a target with no sign-in seam at
+  all, such as a deployed build whose dev bypass is tree-shaken out. The
+  workflows then drive the unauthenticated surface and record the gap rather
+  than fabricating a session.
+
+**Where a `{ skill }` seam resolves.** The id is looked up under
+`.agents/skills/` (the package payload) and then `.agents/local/skills/` —
+the consumer-writable zone. Author your own sign-in skill in the local zone:
+
+```text
+.agents/local/skills/stack/qa/acme-sso/SKILL.md   →  id: stack/qa/acme-sso
+```
+
+`.agents/local/` is never copied into by `mandrel sync`, never pruned, and
+never reported as payload drift by `mandrel doctor`, so a skill you write
+there survives every upgrade. It is held to the same bar as a shipped skill —
+`validate-skills.js` checks its frontmatter and Policy Capsule, and
+`generate-skills-index.js` writes it into its own
+`.agents/local/skills/skills.index.json` (never into the shipped manifest,
+which must stay byte-identical to the package payload).
+
+A seam naming an id that resolves under neither root is rejected by
+`resolveQaEnvironment` when the contract is resolved — not silently carried
+until a sweep reaches its sign-in step.
 
 Once these three `qa.*` keys are in place, `/qa-explore <surface>`, `/qa-assist`,
 and `/qa-run <selector>` all resolve the contract and operate against the bound

package/.agents/agents/auditor.md

@@ -130,6 +130,11 @@ Record the outcome in the Executive Summary as a single line —
 `Self-cross-check: kept <k> / dropped <d>.` — and, when `d > 0`, name the
 dropped findings with their reason. The line's absence is itself a defect.
 
+Beside it, carry one machine-readable tally of the findings you kept —
+`Severity tally: Critical <n> / High <n> / Medium <n> / Low <n>`, zeros
+included, `Info` never counted. `audit-to-stories` cross-checks that line
+against its parse and refuses a report whose tally is missing or wrong.
+
 ## Fan-out (heavyweight lenses)
 
 When your caller dispatches you for a single dimension of a heavyweight lens

package/.agents/docs/SDLC.md

@@ -7,12 +7,13 @@ each Story is delivered on its own `story-<id>` branch and reaches `main`
 through its own PR.
 
 An Epic may still exist as an **optional untyped human umbrella issue**
-(no `type::epic` label and no shipped Epic issue form — only
-`.github/ISSUE_TEMPLATE/story.yml`), but **delivery and planning
-orchestration are Story-only**: there is no Epic wave loop, no
-`epic/<id>` integration branch, no `epic.yaml` reconciler, and any ticket
-that still carries an `Epic: #N` footer is **refused** by `/mandrel-deliver`
-(close it or re-plan it as a v2 Story).
+(the only shipped issue form is `.github/ISSUE_TEMPLATE/story.yml`), and
+**delivery and planning orchestration are Story-only**: there is no Epic
+wave loop, no `epic/<id>` integration branch, no `epic.yaml` reconciler,
+and any ticket that still carries an `Epic: #N` footer is **refused** by
+`/mandrel-deliver` (close it or re-plan it as a v2 Story). `type::epic`
+exists as a **container only** — a grouping ticket with no execution
+payload, expanded to its children at delivery (ADR `20260905-5139`).
 
 The framework is **Claude Code-first**: `.claude/`, hooks, skills, and
 the slash-command surface lean in on Claude Code as the reference
@@ -247,9 +248,10 @@ self-eval, ceremony, close, CI watch, confirm-merge, cleanup) lives in the
 
 The single operator-facing entry point is `/mandrel-deliver`. It performs no
 git/label mutations itself — `deliver-story` owns every script invocation
-per Story. Any ticket that is not `type::story`, or that still carries an
-`Epic: #N` reference, is a hard error naming the ID and the fix (close or
-re-plan as a v2 Story).
+per Story. A `type::epic` id expands to its open child Stories before
+resolution. Any ticket that is neither of those two types, or that still
+carries an `Epic: #N` reference, is a hard error naming the ID and the fix
+(close or re-plan as a v2 Story).
 
 ### Branch model (authoritative)
 
@@ -560,9 +562,15 @@ Editing the main checkout's `.agentrc.json` only affects **the next**
 
 ### `Epic: #N` refusal
 
-`/mandrel-deliver` refuses any ticket that still carries an `Epic: #N` footer or is
-not `type::story`. This is expected — v2 has no Epic delivery path. Close
-the ticket or re-plan the work as a v2 Story via `/mandrel-plan --tickets <id>`.
+`/mandrel-deliver` refuses any ticket that still carries an `Epic: #N` footer,
+or that is neither `type::story` nor `type::epic`. This is expected — v2 has
+no Epic *delivery* path. Close the ticket or re-plan the work as a v2 Story
+via `/mandrel-plan --tickets <id>`.
+
+The container Epic (ADR `20260905-5139`) does **not** soften this. Its linkage
+runs parent→child only — the Epic body lists its children, and no Story body
+ever gains a footer pointing back — so a ticket carrying `Epic: #N` is still a
+v1 ticket and still refused.
 
 ---
 
@@ -573,6 +581,7 @@ the ticket or re-plan the work as a v2 Story via `/mandrel-plan --tickets <id>`.
 | `npx mandrel init` | Cold-start — install `mandrel` (if absent), `mandrel sync`, `bootstrap.js` (provisions repo + Projects V2 board, labels, branch protection), then the onboarding tail (stack detection, docs scaffolding, doctor gate, `/mandrel-plan` handoff). |
 | `/mandrel-plan --seed "<text>"` | Plan from chat text — interrogate → author **one Story by default** → persist `type::story`. |
 | `/mandrel-plan --seed-file <path>` | Plan from on-disk notes / a plan seed (the `/audit-to-stories` handoff). |
+| `/mandrel-deliver <epicId>` | Deliver every open Story under a container Epic — the id expands before resolution. |
 | `/mandrel-plan --tickets <ids>` | Analyze existing issue(s) into proper Stories (prefer an N=1 rewrite). |
 | `/mandrel-deliver <storyId>` | Deliver one Story via `helpers/deliver-story` — `story-<id>` → PR → `main`. |
 | `/mandrel-deliver <storyId> [<storyId>…]` | Deliver multiple Stories in `depends_on` order (resolved from live state), then run the per-run epilogue. |

package/.agents/docs/agentrc-reference.json

@@ -363,9 +363,6 @@
       },
       "staging": {
         "baseUrl": "https://staging.example.test",
-        "signInSeam": {
-          "skill": "stack/qa/sign-in"
-        },
         "allowWrites": false
       }
     },
@@ -374,7 +371,7 @@
         "credentialRef": "QA_ADMIN_CREDENTIAL"
       },
       "member": {
-        "signInSkill": "stack/qa/sign-in-member"
+        "credentialRef": "QA_MEMBER_CREDENTIAL"
       }
     },
     "gherkinLint": {

package/.agents/docs/configuration.md

@@ -336,8 +336,8 @@ Agent-driven QA harness contract (Epic #3214; environment-keyed by Epic #4326).
 | --- | --- | --- | --- | --- |
 | `featureRoot` | No | `string` | `"tests/features"` | Directory holding the Gherkin feature files the QA sweep drives. |
 | `fixturesManifest` | No | `string` | `"tests/fixtures/personas.json"` | Path to the persona/fixture manifest the harness seeds from. |
-| `environments` | No | `object<map>` | `{"local":{"baseUrl":"http://localhost:3000","signInSeam":{"urlTemplate":"/dev/sign-in-as/{persona}"}},"staging":{"baseUrl":"https://staging.example.test","signInSeam":{"skill":"stack/qa/sign-in"},"allowWrites":false}}` | Deployment targets the QA harness can run against (Epic #4326). A map keyed by environment name (e.g. `local`, `staging`), each carrying its own `baseUrl`, its own per-environment sign-in seam (the same url-template/skill union as the top-level seam), and an optional `allowWrites` gate. resolveQaEnvironment selects one environment per invocation by name or by raw-URL origin match against `baseUrl`; `allowWrites` defaults to true only for the `local` environment. Replaces the retired top-level single `signInSeam`. |
-| `personas` | No | one of: `array`, `object` | `{"admin":{"credentialRef":"QA_ADMIN_CREDENTIAL"},"member":{"signInSkill":"stack/qa/sign-in-member"}}` | Personas the QA-harness sign-in seam accepts. Two accepted shapes: (1) a plain array of persona names — the honest shape for a `urlTemplate` dev-impersonation seam, where the persona name is the sole input the workflow consumes; (2) the object-map form keyed by persona name, where each entry carries per-persona auth material (`credentialRef` or `signInSkill`) consulted only under a skill-based or credential-based seam. |
+| `environments` | No | `object<map>` | `{"local":{"baseUrl":"http://localhost:3000","signInSeam":{"urlTemplate":"/dev/sign-in-as/{persona}"}},"staging":{"baseUrl":"https://staging.example.test","allowWrites":false}}` | Deployment targets the QA harness can run against (Epic #4326). A map keyed by environment name (e.g. `local`, `staging`), each carrying its own `baseUrl`, an optional per-environment sign-in seam, and an optional `allowWrites` gate. `signInSeam` is the union `{ urlTemplate }` (a dev impersonation route) or `{ skill }` (a skill id such as `stack/qa/acme-sso`, resolved against `.agents/skills/` then the consumer-writable `.agents/local/skills/` zone, and rejected loudly by resolveQaEnvironment when it resolves under neither); omit it entirely for a target with no sign-in seam. resolveQaEnvironment selects one environment per invocation by name or by raw-URL origin match against `baseUrl`; `allowWrites` defaults to true only for the `local` environment. Replaces the retired top-level single `signInSeam`. |
+| `personas` | No | one of: `array`, `object` | `{"admin":{"credentialRef":"QA_ADMIN_CREDENTIAL"},"member":{"credentialRef":"QA_MEMBER_CREDENTIAL"}}` | Personas the QA-harness sign-in seam accepts. Two accepted shapes: (1) a plain array of persona names — the honest shape for a `urlTemplate` dev-impersonation seam, where the persona name is the sole input the workflow consumes; (2) the object-map form keyed by persona name, where each entry carries per-persona auth material (`credentialRef` or `signInSkill`) consulted only under a skill-based or credential-based seam. |
 | `gherkinLint` | No | `object` | `{"scopes":{"web":{"featureRoots":["apps/web/tests/features"],"stepRoots":["apps/web/tests/steps"]}},"exemptionTags":["@skip"],"stepWaivers":[]}` | Static Gherkin corpus gate (Story #5013). Optional; the gate runs only when this block is present, so an upgrade never reddens the lint of a consumer that never asked the framework to police its `.feature` files. Inside the opt-in it fails closed: an unresolvable `@cucumber/gherkin` parser, or a scope resolving zero step definitions, exits 1 rather than reporting a clean run. |
 | `gherkinLint.scopes` | Yes | `object<map>` | — | Binding scopes, keyed by name. Each scope resolves its own features against its own step definitions only — pooling every step root into one matcher list is what makes a cross-app false bind possible, where a step defined solely in app B silently vouches for app A. The scope name appears verbatim in every unbound finding. |
 | `gherkinLint.exemptionTags` | No | `array<string>` | `["@skip"]` | Tags marking a scenario as intentionally non-binding, so must-bind skips it. Never an escape from must-compile: a parse error in the file still fails the run. Default: ["@skip"]. |

package/.agents/instructions.md

@@ -147,9 +147,9 @@ sizing) **fail closed** naming what to trim:
   spawn only when the work justifies replicating context. One objective
   per subagent; depth compounds the cost (every nested level re-pays).
 - **Anti-Laziness / No Dead Code.** NEVER use placeholder comments like
-  `// ... existing code ...`; every edit must leave complete, runnable
-  code. Remove unused imports, commented-out code, and dead branches
-  before finalizing.
+  `// ... existing code ...`; every edit must leave complete, runnable code.
+  Remove unused imports, commented-out code, and dead branches before
+  finalizing.
 - **Verification.** Include explicit verification steps in every plan.
 
 ---
@@ -157,28 +157,29 @@ sizing) **fail closed** naming what to trim:
 ## 5. Git & Story Protocol (Strict Standards)
 
 [`rules/git-conventions.md`](rules/git-conventions.md) is the canonical
-reference: `story-<storyId>` branches seeded by `single-story-init.js`,
-every Story reaching `main` via its own PR
-(`helpers/deliver-story` / `single-story-close.js`).
+reference for branch shapes and commit subjects, and is always loaded —
+this section does not restate it.
 
 ### A. Status Tracking & Commit Standards
 
 State mutations are GitHub labels (`agent::ready`, `agent::executing`,
 `agent::done`) via
 `node .agents/scripts/update-ticket-state.js --ticket [ID] --state [STATUS]`.
-Do NOT manually update issue descriptions or status fields unless
-prompted.
+Do NOT manually update issue descriptions or status fields unless prompted.
 
-### B. Ticket hierarchy (Story-only)
+### B. Ticket hierarchy
 
-The v2 ticket model is Story-only: `acceptance[]` / `verify[]` live
+The Story is the only executable ticket: `acceptance[]` / `verify[]`
 inline plus the folded Tech Spec in `## Spec` (over-budget Specs fail
-closed — split or tighten; never write Specs under `docs/`). Optional
-`depends_on` edges order rare multi-Story runs, resolved by `/mandrel-deliver`
-from live state; the `plan-run::<id>` label is filter metadata only.
-Commit subjects reference the Story via `(refs #<storyId>)`. There is no
-`type::epic` / `type::task` label; `/mandrel-deliver` refuses tickets carrying an
-`Epic: #N` footer.
+closed — split or tighten; never under `docs/`). Optional `depends_on`
+edges order rare multi-Story runs, resolved by `/mandrel-deliver` from
+live state; `plan-run::<id>` is filter metadata. Commit subjects
+reference the Story via `(refs #<storyId>)`. There is no `type::task`.
+
+`type::epic` is a container only (goal + child checklist, no `agent::*`,
+never delivered): `/mandrel-plan` offers one above 2 Stories and
+`/mandrel-deliver <epicId>` expands it. Linkage is parent→child only, so
+an `Epic: #N` footer is still refused.
 
 ---
 

package/.agents/schemas/agentrc.schema.json

@@ -1921,7 +1921,9 @@
             },
             "advisoryAllowlist": {
               "type": "array",
-              "items": { "type": "string" },
+              "items": {
+                "type": "string"
+              },
               "description": "Story #5096. Check-run names exempt from blockOnAdvisoryFailure — a red run whose name matches exactly never blocks arming. Matching is exact; an unnamed run can never match and always blocks.",
               "default": []
             }
@@ -1985,7 +1987,7 @@
         },
         "environments": {
           "type": "object",
-          "description": "Deployment targets the QA harness can run against (Epic #4326). A map keyed by environment name (e.g. `local`, `staging`), each carrying its own `baseUrl`, its own per-environment sign-in seam (the same url-template/skill union as the top-level seam), and an optional `allowWrites` gate. resolveQaEnvironment selects one environment per invocation by name or by raw-URL origin match against `baseUrl`; `allowWrites` defaults to true only for the `local` environment. Replaces the retired top-level single `signInSeam`.",
+          "description": "Deployment targets the QA harness can run against (Epic #4326). A map keyed by environment name (e.g. `local`, `staging`), each carrying its own `baseUrl`, an optional per-environment sign-in seam, and an optional `allowWrites` gate. `signInSeam` is the union `{ urlTemplate }` (a dev impersonation route) or `{ skill }` (a skill id such as `stack/qa/acme-sso`, resolved against `.agents/skills/` then the consumer-writable `.agents/local/skills/` zone, and rejected loudly by resolveQaEnvironment when it resolves under neither); omit it entirely for a target with no sign-in seam. resolveQaEnvironment selects one environment per invocation by name or by raw-URL origin match against `baseUrl`; `allowWrites` defaults to true only for the `local` environment. Replaces the retired top-level single `signInSeam`.",
           "default": {
             "local": {
               "baseUrl": "http://localhost:3000",
@@ -1995,9 +1997,6 @@
             },
             "staging": {
               "baseUrl": "https://staging.example.test",
-              "signInSeam": {
-                "skill": "stack/qa/sign-in"
-              },
               "allowWrites": false
             }
           },
@@ -2048,7 +2047,7 @@
                 "type": "boolean"
               }
             },
-            "required": ["baseUrl", "signInSeam"],
+            "required": ["baseUrl"],
             "additionalProperties": false
           }
         },
@@ -2059,7 +2058,7 @@
               "credentialRef": "QA_ADMIN_CREDENTIAL"
             },
             "member": {
-              "signInSkill": "stack/qa/sign-in-member"
+              "credentialRef": "QA_MEMBER_CREDENTIAL"
             }
           },
           "oneOf": [