mandrel 1.82.0 → 1.84.0

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

@@ -1,5 +1,5 @@
 {
-  "generatedAt": "2026-07-04T00:29:42.907Z",
+  "generatedAt": "2026-07-04T23:12:38.376Z",
   "generator": "generate-skills-index.js@1",
   "skills": [
     {
@@ -567,8 +567,8 @@
       "tier": "stack",
       "category": "qa",
       "path": ".agents/skills/stack/qa/qa-explore-driving/SKILL.md",
-      "description": "Conventions for agent-driven exploratory QA driving — how the agent itself drives a surface during `/qa-explore` (agent-led), as opposed to the human-led `/qa-assist`. Use when the agent explores a running app via the browser MCP (navigation-first, the default) or walks a static surface (the documented interim until consumer persona-seeding lands), under a strictly read-only capture invariant. The exploration procedure lives in `.agents/workflows/qa-explore.md`; this skill is the driving-conventions reference it leans on.",
-      "policyCapsuleBullets": 8,
+      "description": "Conventions for agent-driven exploratory QA driving — how the agent itself drives a surface during `/qa-explore` (agent-led), as opposed to the human-led `/qa-assist`. Use when the agent explores a running app via the browser MCP (navigation-first, the default) — including authenticated deployed surfaces reached through the resolved environment's sign-in seam — or walks a static surface (the documented interim where no seam resolves), under a strictly read-only capture invariant. The exploration procedure lives in `.agents/workflows/qa-explore.md`; this skill is the driving-conventions reference it leans on.",
+      "policyCapsuleBullets": 9,
       "allowedTools": null,
       "vendor": null
     },

package/.agents/skills/stack/qa/qa-explore-driving/SKILL.md

@@ -4,9 +4,10 @@ description:
   Conventions for agent-driven exploratory QA driving — how the agent itself
   drives a surface during `/qa-explore` (agent-led), as opposed to the
   human-led `/qa-assist`. Use when the agent explores a running app via the
-  browser MCP (navigation-first, the default) or walks a static surface (the
-  documented interim until consumer persona-seeding lands), under a strictly
-  read-only capture invariant. The exploration procedure lives in
+  browser MCP (navigation-first, the default) — including authenticated
+  deployed surfaces reached through the resolved environment's sign-in seam —
+  or walks a static surface (the documented interim where no seam resolves),
+  under a strictly read-only capture invariant. The exploration procedure lives in
   `.agents/workflows/qa-explore.md`; this skill is the driving-conventions
   reference it leans on.
 ---
@@ -16,9 +17,10 @@ description:
 ## Policy Capsule
 
 - Drive the running app **by default** through the browser MCP, navigation-first: start at a root and reach each surface only via UI affordances — never URL-jump to a deep link.
-- Treat **static driving** (reading source, routes, and rendered markup without a live runtime) as the **documented interim** method, chosen at Plan time when a live runtime is not reachable — never the silent fallback.
+- Resolve the target **environment** at Plan time (via `resolveQaEnvironment`) and record its name in the ledger; each environment keys its own `baseUrl`, `signInSeam`, and `allowWrites`.
+- Treat **static driving** (reading source, routes, and rendered markup without a live runtime) as the **documented interim** method, chosen at Plan time **only where no seam resolves** for the target environment — never the silent fallback.
 - Hold the **read-only capture invariant** absolutely: the agent makes no source edits and no product mutations while driving; the only write is appending to the `temp/qa/<sessionId>` ledger.
-- Authenticated driving depends on **consumer persona-seeding infrastructure that this Epic does not deliver**; without it, drive only the unauthenticated surface or fall back to static, and record the gap — never enter real credentials or fabricate a session.
+- Authenticated driving follows the resolved environment's **`signInSeam`**: sign in through a dev `url` seam (persona name substituted into the template) or a `skill` seam (a stored `credentialRef` read by the named sign-in skill), with **mandatory redaction** of all captured evidence. Never type real credentials inline or fabricate a session; where an environment resolves no seam, drive the unauthenticated surface or fall back to static and record the gap.
 - Pick the driving method explicitly in the Plan phase (drive vs. static) and record it in the ledger; do not switch methods mid-surface without a new Plan note.
 - Every phase transition and every GitHub write is HITL-gated; the agent drives and captures, but never files or promotes findings autonomously.
 - Broken navigation, a missing affordance, or a guard redirect loop is a **finding**, not a workaround — record it and move on; do not route around it with a direct URL.
@@ -65,15 +67,14 @@ state rather than an artifact of a deep link.
 
 ## 2. Static Driving — the Documented Interim
 
-Static driving is the **explicitly documented interim** method for when a live
-runtime is not reachable — most commonly because authenticated driving needs
-consumer persona-seeding infrastructure that does not yet exist (§ 4). It walks
-the surface from source, route definitions, and rendered markup rather than a
-running browser.
+Static driving is the **explicitly documented interim** method for when **no
+seam resolves** for the target environment — the resolved environment carries
+no `signInSeam` the agent can drive through (§ 4). It walks the surface from
+source, route definitions, and rendered markup rather than a running browser.
 
 - **Choose it at Plan time, never silently.** Static is a deliberate Plan-phase
-  decision recorded in the ledger ("method: static, reason: no reachable
-  authenticated runtime"), not an unannounced fallback the agent slips into
+  decision recorded in the ledger ("environment: preview, method: static,
+  reason: no seam resolves"), not an unannounced fallback the agent slips into
   when the browser MCP hiccups.
 - **It is interim, not equivalent.** Static driving cannot exercise real
   authorization, routing guards, or runtime console/network signal. Treat its
@@ -81,10 +82,10 @@ running browser.
   same coverage a driven pass would.
 - **Same read-only invariant.** Static driving reads source and routes; it makes
   no edits. The read-only capture invariant (§ 3) applies identically.
-- **Promote to driving when the runtime lands.** Static is the bridge until the
-  consumer's persona-seeding infrastructure (§ 4) makes authenticated driving
-  possible. When that lands, re-run the surface driven; do not leave a surface
-  permanently static when it could be driven.
+- **Promote to driving when a seam lands.** Static is the bridge until the
+  target environment resolves a `signInSeam` (§ 4) that makes driven
+  authenticated exploration possible. When that lands, re-run the surface
+  driven; do not leave a surface permanently static when it could be driven.
 
 ## 3. The Read-Only Capture Invariant
 
@@ -109,29 +110,42 @@ and the Epic's security considerations — it is not a soft preference.
   (ticket creation, promotion) happen only behind an operator confirmation gate.
   The agent never files or promotes findings autonomously.
 
-## 4. Authenticated Driving Depends on Consumer Infra (Not Delivered Here)
-
-Driving an **authenticated** surface requires signing in as a seeded persona.
-That seeding — provisioning a test persona with the right org, role, and data
-so the agent can reach a logged-in surface navigation-first — is **consumer
-persona-seeding infrastructure that this Epic does not deliver**. It is an
-explicit non-goal of the `/qa-explore` rebuild.
-
-- **Unauthenticated surface only, by default.** Without persona-seeding infra in
-  the consumer project, drive only the surface reachable without sign-in, or
-  fall back to static driving (§ 2) for the authenticated surface. Record the
-  gap in the ledger so the partial coverage is visible.
-- **Never enter real credentials.** The agent MUST NOT type real usernames,
-  passwords, or tokens to reach an authenticated surface, and MUST NOT fabricate
-  or forge a session. This is a hard security boundary, not a convenience to
+## 4. Authenticated Driving Follows the Per-Environment Seam
+
+Driving an **authenticated** surface requires signing in. The resolved target
+environment (via `resolveQaEnvironment`, § Policy Capsule) carries the
+`signInSeam` the agent drives through — the same discriminated-union shape
+`qa-harness` resolves via its contract. When a seam resolves, authenticated
+deployed surfaces are **driven**, not statically deferred.
+
+- **Drive the authenticated surface through the seam.** When the target
+  environment carries a `signInSeam`, sign in via that seam and then reach the
+  authenticated surface navigation-first — including authenticated **deployed**
+  hosts. The two seam kinds:
+  - **`kind: 'url'` (dev impersonation).** Substitute the persona **name** into
+    the seam's URL template and navigate there. The persona name is the sole
+    input; no per-persona auth material is read.
+  - **`kind: 'skill'` (procedural / credential).** Invoke the named consumer
+    sign-in skill, which reads a per-persona **`credentialRef`** — an indirect
+    handle to a stored credential, never an inline secret. Read the skill's
+    `SKILL.md` and follow it.
+- **Never enter real credentials inline.** The agent MUST NOT type real
+  usernames, passwords, or tokens to reach an authenticated surface, and MUST
+  NOT fabricate or forge a session. Sign-in flows only through the seam, which
+  consumes a persona name or a `credentialRef` indirection — never a
+  hand-typed secret. This is a hard security boundary, not a convenience to
   work around.
-- **The dependency is the consumer's to satisfy.** When a consumer wants driven
-  authenticated exploration, the consumer supplies a dev sign-in seam and seeded
-  personas (the same shape `qa-harness` resolves via its contract). Until then,
-  authenticated coverage is static or deferred — say which in the ledger.
-- **Surface the gap, don't paper over it.** A surface that could not be driven
-  because authenticated seeding is absent is itself a coverage signal worth
-  recording, not a silent skip.
+- **Redaction is mandatory.** Every captured evidence string — console,
+  network, headers — passes through the shared redaction path (§ 3) before it
+  reaches disk or GitHub; bearer tokens, session cookies, `Authorization`
+  headers, and PII are masked. Authenticated driving raises the stakes on
+  redaction, it does not relax it.
+- **Static only where no seam resolves.** When the target environment resolves
+  **no** `signInSeam`, drive only the unauthenticated surface or fall back to
+  static driving (§ 2), and record the gap in the ledger so the partial
+  coverage is visible. A surface that could not be driven because the
+  environment carries no seam is itself a coverage signal worth recording, not
+  a silent skip.
 
 ## 5. Cross-References
 

package/.agents/workflows/helpers/code-review.md

@@ -19,6 +19,18 @@ is merged upstream. It runs in two scopes:
 - **Epic scope** — reviews the cumulative diff between an Epic branch and
   `main`, before `/deliver` opens the integration pull request.
 
+**Invariant — Story-scope review runs outside the maker's LLM context.**
+The Story-scope review executes inside the `story-close.js` /
+`single-story-close.js` close subprocess, **not** in the delivering
+child's (maker agent's) LLM context. The close pipeline invokes it after
+the delivering child has exited, so the change set is reviewed by a
+process the maker cannot influence. The enforcing code path is
+[`.agents/scripts/lib/orchestration/story-close/phases/code-review.js`](../../scripts/lib/orchestration/story-close/phases/code-review.js)
+(invoked from `runStoryCloseLocked`; both close entry points reach it
+through the shared `runStoryReviewCore` spine). A future refactor MUST
+preserve this isolation: do not move Story-scope review into the maker's
+context or run it as a step of the delivering child.
+
 > **Persona**: `architect` · **Skills**: `core/code-review-and-quality`,
 > `core/security-and-hardening`
 
@@ -107,18 +119,21 @@ The pipeline will:
 
 ## Step 2 — Review Pillars
 
-For each changed file, execute a strict review against three pillars. The
-middle pillar (**Integration Review**) deliberately defers the security /
+For each changed file, execute a strict review against four pillars. The
+second pillar (**Integration Review**) deliberately defers the security /
 performance / quality / coverage sweeps to the change-set-scoped audits
 that already ran upstream — re-walking them here is duplication, not
 defense-in-depth.
 
 **Apply the `depth` lever** (see **Review depth** above) to how hard you walk
 these pillars: at `light`, focus on Pillar 1 and reduce Pillars 2–3 to a quick
-scan for obvious breakage; at `standard`, cover all three at today's depth; at
-`deep`, cover all three at full depth and then make a second adversarial pass
+scan for obvious breakage; at `standard`, cover all four at today's depth; at
+`deep`, cover all four at full depth and then make a second adversarial pass
 over the diff hunting for integration regressions and security-relevant edges
-before finalizing findings.
+before finalizing findings. Pillar 4 (**Anti-Gaming / Shortcut Detection**)
+is walked at **every** depth, including `light` — it targets the class of
+correctness failure the deterministic gates structurally cannot see, so it is
+never reduced to a scan.
 
 ### Pillar 1: Spec Adherence
 
@@ -182,6 +197,56 @@ Verify documentation stays synchronized with code:
 - README and CHANGELOG reflect the changes if applicable.
 - Inline comments explain *why*, not *what*.
 
+### Pillar 4: Anti-Gaming / Shortcut Detection
+
+Does the change reach "done" by *fixing the code*, or by *weakening the check
+that would have caught it broken?* This is the class of correctness failure the
+deterministic `verify[]` commands and the ratchet gates structurally cannot
+see: a green suite, a passing lint, and an unchanged maintainability score all
+report success whether the code got correct or the test got quieter. Walk the
+diff for the shortcut taxonomy below and flag every instance — a plausible-but-
+unjustified match is a 🟠 finding, an unambiguous one (test deletion without a
+spec decision, a swallowed error on a real failure path) is a 🔴.
+
+- **Relaxed tests** — an assertion loosened to pass rather than the code fixed
+  to satisfy it: a tightened matcher swapped for a looser one
+  (`toEqual` → `toBeTruthy`, an exact value → `expect.anything()`), a
+  narrowed expected value widened, a strict schema check softened, or a
+  threshold moved to admit the current (wrong) output.
+- **Skipped tests** — a failing test quarantined instead of fixed:
+  `it.skip` / `test.skip` / `xit` / `describe.skip`, a `return` early in the
+  test body, a `--test-name-pattern` / grep exclusion, an `@skip`/`@ignore`
+  tag, or a test commented out wholesale. Deleting a test outright is the
+  most severe form — treat unexplained coverage removal as `test-deletion`
+  (Step 4.5) and never auto-fix it.
+- **Swallowed errors** — a failure path silently absorbed: an empty
+  `catch {}`, `catch (e) {}` with no rethrow/log/handle, a bare
+  `.catch(() => {})` on a promise, a `try` wrapped solely to suppress a
+  throw the caller needs, or an error downgraded to a no-op return so the
+  happy path "passes".
+- **Stub returns** — a hardcoded value standing in for real logic: a function
+  that `return true` / `return []` / `return null` / `return {}` regardless of
+  input, a mock left wired into production code, a `TODO`/`FIXME` guarding an
+  unimplemented branch that the acceptance criteria required, or a constant
+  substituted for a computation the Story asked for.
+- **Fake renames** — a change dressed up as a rename that is actually a
+  deletion or a behavior change: content dropped under cover of a
+  move/rename, a "rename" whose diff quietly alters logic, or a re-export
+  shim that orphans the real implementation while the symbol name survives.
+- **Comment-deletion-as-fix** — a warning silenced by removing its evidence
+  rather than its cause: a failing assertion turned into a comment, a
+  `// TODO: this is broken` note deleted while the breakage remains, a
+  disabled-code block removed to make a diff look clean, or a lint-suppression
+  comment (`biome-ignore`, `eslint-disable`, `@ts-expect-error`) added to mute
+  a real diagnostic instead of fixing it.
+
+For every hit, name the file and line, the taxonomy category, and *why the
+code — not the check — should have changed*. A finding here is legitimate only
+when the diff itself lacks a recorded rationale (a commit-body or Story-comment
+note explaining a deliberate, spec-sanctioned relaxation clears it — per the
+engineer persona's Implementation Latitude, unlogged reshaping is the
+anti-pattern this pillar surfaces).
+
 ## Step 3 — Maintainability Ratchet
 
 Verify that no file's maintainability score has decreased below the project