mandrel 2.40.0 → 2.42.0

package/.agents/skills/stack/qa/gherkin-authoring/reference.md

@@ -3,102 +3,9 @@
 **Read this when** a task engages one of the sections below and the Policy
 Capsule in [`SKILL.md`](SKILL.md) does not settle it on its own. The capsule is
 the contract; this file is the reference material behind it. The enforcement
-rules (tag taxonomy, forbidden patterns, Outline conventions) are owned by the
-SSOT rule, [`gherkin-standards.md`](../../../../rules/gherkin-standards.md).
-
-## Canonical Given / When / Then Phrasing
-
-`.feature` prose is written for a product-minded reader, not a test harness.
-Each clause has exactly one job:
-
-- **Given** — a precondition that is *already true* when the scenario starts.
-  Stative, past or present tense. No actions.
-  - Good: `Given a signed-in account-owner with an unpaid invoice`.
-  - Bad: `Given the user clicks the login button` (that's a When).
-- **When** — the single business action under test. One verb, one actor, one
-  event. Splitting a When into multiple clauses is almost always wrong — move
-  the extra clauses into Given.
-  - Good: `When they issue the invoice`.
-  - Bad: `When they log in and issue the invoice and download the PDF`.
-- **Then** — an observable, user-visible outcome. Assert what the *user* sees or
-  what the *business* records, not what the system emits internally.
-  - Good: `Then the invoice appears in the issued invoices list`.
-  - Bad: `Then a 201 is returned` (forbidden; see
-    [gherkin-standards § Forbidden Patterns](../../../../rules/gherkin-standards.md#forbidden-patterns)).
-- **And / But** — continuation clauses. They inherit the mood of the most recent
-  Given/When/Then. Never start a scenario with And/But.
-
-Voice and tense: third-person, present tense, role-qualified noun actors
-(`the user`, `a billing-admin`, not "I" or "we"). One clause, one fact —
-comma-chained facts hide compound assertions. Numbers and identifiers go in
-`Examples` tables or fixtures, not inline prose.
-
-## Translating PRD Acceptance Criteria to Scenarios
-
-PRD ACs are the raw material. The authoring move is **one AC → one scenario**
-unless the AC encodes a matrix (then it becomes a Scenario Outline — see below).
-
-Walkthrough — a PRD AC from a billing feature:
-
-> **AC-3:** When a billing-admin issues an invoice for a customer with a
-> negative balance, the system rejects the issue and shows an error naming the
-> outstanding amount.
-
-Translation steps:
-
-1. **Identify the domain.** Billing → tag the scenario `@domain-billing`.
-2. **Identify the actor and precondition.** "billing-admin", "customer with a
-   negative balance" → two Givens.
-3. **Identify the single action.** "issues an invoice" → one When.
-4. **Identify the observable outcome.** "rejects the issue and shows an error
-   naming the outstanding amount" → two Thens (business outcome, then
-   user-visible detail).
-5. **Pick the risk tag.** If the originating ticket was `risk::high`, add
-   `@risk-high`.
-
-Resulting scenario:
-
-```gherkin
-@domain-billing @risk-high
-Scenario: Issuing an invoice is rejected when the customer has a negative balance
-  Given a signed-in billing-admin
-  And a customer with a negative account balance
-  When the billing-admin issues an invoice for that customer
-  Then the issue is rejected
-  And the rejection message names the outstanding amount
-```
-
-Heuristics:
-
-- If a single AC needs more than **one When**, it is really two ACs. Split
-  before you write.
-- If a Then starts with "and the database has…" or "and the API returned…", you
-  have crossed into step-definition or contract-test territory. Rewrite it as
-  user-visible language or move the assertion to a contract test.
-- If an AC says "the system logs X", that's an engineering non-functional
-  requirement — cover it with a focused unit or integration test, not a
-  `.feature` file.
-
-## Background vs. Given, Outline vs. Multi-Scenario
-
-Two authoring decisions authors routinely get wrong.
-
-**Background vs. Given.** `Background` runs before **every** scenario in the
-file. Use it only when every scenario genuinely shares the precondition **and**
-it has no per-scenario variation (no `<placeholders>`, no per-scenario data).
-Prefer a per-scenario Given when only some scenarios need the precondition, when
-it varies by role/plan/fixture, or when a reader cannot understand the scenario
-without scrolling up. Rule of thumb: if you find yourself writing *"except in
-the admin scenario, where the Background step is actually…"*, delete the
-Background.
-
-**Scenario Outline vs. multiple Scenarios.** Use `Scenario Outline` when the
-**same behavior** is exercised across a **bounded matrix** (roles, plan tiers,
-locales) — the Givens/When/Thens are identical and only the data varies. Use
-multiple `Scenario` blocks when the Givens differ structurally, the When verb
-differs, or the Then outcomes differ in kind, not just value. Keep `Examples`
-tables under ~12 rows, and split them by tag when rows need different tags
-(e.g. `@risk-high` on admin rows only).
+rules (tag taxonomy, forbidden patterns, Outline conventions, step reuse) are
+owned by the SSOT rule,
+[`gherkin-standards.md`](../../../../rules/gherkin-standards.md).
 
 ## Step-Definition Library Structure
 
@@ -122,22 +29,11 @@ tests/
 - Step text follows the scenario text verbatim — divergence between scenario
   prose and step text is a bug. Parameterize only over values that actually
   vary; keep implementations ≤20 lines (a longer one signals a missing helper).
-
-**Reuse before authoring** — the non-negotiable workflow is in
-[gherkin-standards § Step Reuse](../../../../rules/gherkin-standards.md#step-reuse--grep-before-you-write):
-
-1. Search for the verb: `rg -n "issues? an invoice" tests/steps`.
-2. If the phrase exists, **change your scenario** to use it — do not fork a
-   near-duplicate step.
-3. If a near-match exists, extend the existing step and update every call site
-   in the same PR.
-4. Only when no reasonable match exists, add a new step in the correct domain
-   directory.
-
-**Deprecation.** When a step is superseded, move the old definition into
-`steps/_deprecated/` with a comment naming the replacement, migrate every call
-site in the same PR, and delete the `_deprecated/` entry when the migration
-lands. Never leave two live step definitions that mean the same thing.
+- **Reuse before authoring, and deprecate cleanly.** Both are the SSOT rule's:
+  [gherkin-standards § Step Reuse](../../../../rules/gherkin-standards.md#step-reuse--grep-before-you-write).
+  A superseded definition moves into `steps/_deprecated/` with a comment naming
+  its replacement, every call site migrates in the same PR, and the
+  `_deprecated/` entry is deleted when the migration lands.
 
 ## Authoring Checklist
 
@@ -151,7 +47,7 @@ Before opening a PR that adds or edits a `.feature` file:
 - [ ] `Background` is justified (applies to every scenario in the file).
 - [ ] If a Scenario Outline is used, the matrix is bounded (≤12 rows) and the
       shape is truly identical across rows.
-- [ ] Every step phrase grep-matches an existing step definition **or** is
+- [ ] Every step phrase matches an existing step definition **or** is
       accompanied by a new step definition in the right domain directory.
 - [ ] Reads standalone — a product reader who has never seen the codebase can
       understand the intent without opening a step file.

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

@@ -13,14 +13,15 @@ vendor: playwright
 
 ## Policy Capsule
 
-- Complete the pre-authoring grep-for-existing-steps checklist before writing any new scenario text; record the matches in your output.
+- Complete the step-reuse sequence in [`gherkin-standards.md` § Step Reuse](../../../../rules/gherkin-standards.md#step-reuse--grep-before-you-write) before any scenario text is written, and report its results; that rule is the only home for it.
 - Keep `.feature` files free of Playwright API calls — scenarios describe intent, step definitions translate to browser actions.
-- Generate step bindings into a dedicated directory (e.g. `.features-gen/`) and add it to `.gitignore`; never commit generated specs.
-- Drive runs by tag expression (`--grep "@smoke and not @flaky"`), not filename globs; use the canonical `@smoke`/`@risk-high`/`@platform-*`/`@domain-*` taxonomy.
+- Generate step bindings into a dedicated directory (e.g. `.features-gen/`) and add it to `.gitignore`; never commit generated specs, and point `testDir` at that directory.
+- Drive runs by tag expression (`npx bddgen && npx playwright test --grep "@smoke and not @flaky"`), not filename globs; fail the run when generation matches zero scenarios.
 - Inject fixtures via `createBdd` rather than pulling singletons from module scope; reset persistent state through fixture teardown, not stray `After` hooks.
 - Reuse `storageState` for authenticated scenarios — create a logged-in user fixture instead of repeating login steps in `Background`.
-- Keep `trace: 'on-first-retry'` (or `'retain-on-failure'`) enabled; reproduce failures by `@scenario-id` tag, not by title.
+- Keep `trace: 'on-first-retry'` (or `'retain-on-failure'`) enabled; reproduce failures by `@scenario-id` tag, not by title, and use `PWDEBUG=1` rather than `page.pause()` in step files.
 - Shard with Playwright's native `--shard=i/N`; never partition by tag expression across CI jobs.
+- Use Playwright projects (not Cucumber profiles) for browser matrix fan-out, so sharding, retries, and trace config stay in one place.
 
 Guidance for running Gherkin `.feature` files against Playwright via
 `playwright-bdd`. Pairs with the `gherkin-authoring` skill (scenario prose) and
@@ -30,157 +31,31 @@ between them.
 > **Version:** consumers pick their own `playwright-bdd` version. This skill
 > documents behavioral constraints, not a pinned release.
 
-## Pre-authoring checklist (mandatory)
-
-The agent MUST complete every item below AND MUST include the results in its
-output report BEFORE any scenario text is written. See
-[§ Step Reuse — Grep Before You Write](../../../../rules/gherkin-standards.md#step-reuse--grep-before-you-write)
-for rationale.
-
-1. Run `rg` against the project's steps directory and list every step signature
-   you will reuse. Format: one `Given/When/Then "…"` per line.
-2. For each scenario line you plan to author, identify the matching existing
-   step. For any line with no match, either rephrase to reuse an existing step
-   or record it as a gap. Do NOT author new step definitions during scenario
-   authoring.
-3. State the canonical domain tag and platform tag you will apply (or note
-   "Cross-Platform → no platform tag" per `gherkin-standards.md`).
-4. Confirm the AC's `data-testid`, URL, and payload hints will be stripped from
-   scenario prose.
-
-If you cannot complete every item, stop and report — do not proceed to scenario
-authoring.
-
-## 1. Core Principles
-
-- **One source of truth per scenario:** `.feature` files describe intent; step
-  definitions translate intent into Playwright calls. Never author browser
-  actions in `.feature` prose.
-- **Deterministic tag filtering:** every scenario carries enough tags that any
-  CI shard can be selected by a tag expression without inspecting file paths.
-- **Fixture-per-scenario isolation:** scenarios must not share mutable state.
-  Treat each scenario as a fresh browser context.
-- **Trace-first debugging:** keep the Playwright Trace Viewer workflow intact —
-  `playwright-bdd` wraps Playwright, it does not replace its diagnostics.
-
-## 2. Config Patterns
-
-- Generate step-definition bindings into a dedicated output directory (commonly
-  `.features-gen/`) and add it to `.gitignore`. Do not commit generated specs.
-- Point `playwright.config.ts` at the generated directory via `testDir`; keep a
-  single `defineBddConfig` block that lists `features` and `steps` paths.
-- Register the Cucumber HTML/JSON reporter alongside the Playwright HTML
-  reporter so a headless CI invocation emits machine-readable evidence
-  alongside the agent-driven `/qa-run` sweep.
-- Use Playwright projects (not Cucumber profiles) for browser matrix fan-out —
-  keeps sharding, retries, and trace config in one place.
-
-## 3. Fixture Composition
-
-- Extend Playwright's `test` via `playwright-bdd`'s `createBdd` so fixtures
-  (auth state, API clients, seeded data) are injected into `Given`/`When`/
-  `Then` callbacks by name, not pulled from module-level singletons.
-- Layer fixtures: base Playwright fixtures → domain fixtures (authenticated
-  user, seeded tenant) → scenario-scoped helpers. Each layer depends only on the
-  layer below.
-- Reset persistent state with fixture teardown, not with `After` hooks buried in
-  step files — teardown order is then deterministic and visible in the fixture
-  graph.
-- Reuse `storageState` for authenticated scenarios; create a "logged-in user"
-  fixture rather than repeating login steps in `Background`.
-
-## 4. Tag-Filtered Execution
-
-- Drive runs via tag expressions, not filename globs:
-  `npx bddgen && npx playwright test --grep "@smoke and not @flaky"`.
-- Use the canonical tag taxonomy defined in
-  [`.agents/rules/gherkin-standards.md`](../../../../rules/gherkin-standards.md#tag-taxonomy)
-  (`@smoke`, `@risk-high`, `@platform-*`, `@domain-*`). Do not invent parallel
-  tag vocabularies in the runner config; extend via `@domain-*` only.
-- Wire tag-filtered headless runs to a single npm script so operators never
-  reconstruct the generate-then-run sequence by hand; the agent-driven
-  `/qa-run` selector mirrors the same tag expressions for browser sweeps.
-- Fail the run if generation produces zero matching scenarios — a silent empty
-  suite is worse than a red build.
-
-## 5. Debug & Trace Workflow
-
-- Keep `trace: 'on-first-retry'` (or `'retain-on-failure'`) in the Playwright
-  config. `playwright-bdd` preserves the trace attachment because each scenario
-  maps to a Playwright test.
-- Reproduce a single failing scenario with `--grep "@scenario-id"` rather than
-  the scenario title — titles change, tags are stable.
-- Open traces with `npx playwright show-trace` against the artifact produced
-  under `test-results/`; the trace timeline annotates each `Given`/`When`/
-  `Then` step, which is the primary debug affordance.
-- For step-definition bugs, run with `PWDEBUG=1` to drop into the inspector at
-  the failing step — do not add `page.pause()` calls inside step files.
-
-## 6. Sharding & CI Notes
-
-- Shard with Playwright's native `--shard=i/N`; do not partition by tag
-  expression across jobs — tag-sharding makes flake triage non-deterministic.
-- Run `bddgen` once per job before `playwright test`; cache the generated
-  directory only if the cache key includes every `.feature` and step file.
-- Publish the Cucumber HTML/JSON report as the evidence artifact, alongside
-  the Playwright HTML report and any trace zips.
-- Quarantine `@flaky` scenarios with a dedicated job that does not gate the
-  merge queue; do not silently retry flakes in the main suite.
-
-## Recommended invocation template
-
-Use this template when invoking a subagent to author a `.feature` file from an
-Acceptance Criterion.
-
-```text
-You are an AI coding agent. Your sole task is to invoke the
-**stack/qa/playwright-bdd** skill (defined in this repo) to author one new
-acceptance scenario from a single Acceptance Criterion. You receive nothing
-about this codebase except the AC text and the skill itself — you must
-discover everything else (existing step library, naming conventions, etc.)
-through the skill's prescribed workflow.
-
-Follow the skill's guidance precisely. Your output will be evaluated
-against `.agents/rules/gherkin-standards.md`.
-
-**Skill to invoke.** Read `.agents/skills/stack/qa/playwright-bdd/SKILL.md`
-and follow it. Also read `.agents/rules/gherkin-standards.md` (which the
-skill references).
-
-**The Acceptance Criterion (your sole input).** {{AC_TEXT}}
-
-**Your task.**
-1. Read the skill and the gherkin rule.
-2. Per the skill's "Step Reuse — Grep Before You Write" section, grep
-   {{STEPS_DIR}} to discover the existing step vocabulary BEFORE
-   authoring. List the matches you found.
-3. Author a NEW `.feature` file at {{OUTPUT_PATH}} that covers this AC.
-4. You are FORBIDDEN from editing any file under {{STEPS_DIR}}. This
-   task tests scenario authorship and step REUSE. If a step you need does
-   not exist, you must either rephrase the scenario to reuse what exists,
-   or report that as a gap (do not silently invent).
-5. Tag the feature/scenario per the canonical taxonomy in
-   `gherkin-standards.md`.
-6. Honor every "Forbidden Patterns" rule. `data-testid` hints in the AC
-   parentheses are for the step-definition layer; they MUST NOT appear in
-   your scenario text.
-
-**Report back.** Sections A–E: discovered steps, exact `.feature` content,
-step-coverage analysis, forbidden-patterns self-audit, uncertainty/gaps.
-```
-
-This template encodes the invocation prompt used in the Epic C pilot of
-dsj1984/athlete-portal, where a general-purpose subagent — given only an AC and
-a pointer to this skill — produced a publishable scenario on the first attempt
-with **zero Forbidden-Patterns violations**, reused **4 of 5** needed steps from
-the existing library, and surfaced the single remaining step as a clean, named
-gap rather than inventing one. Future maintainers: resist the urge to "simplify"
-this template. Its explicit grep-before-author step, the hard prohibition on
-editing the steps directory, and the mandated gap-report section are what forced
-those outcomes.
-
-## 7. Cross-References
+## Project-Specific Wiring
+
+The capsule above is the contract. Three points bind this runtime to the rest
+of the framework:
+
+- **Tags come from one taxonomy.** Selection uses the canonical set defined in
+  [`.agents/rules/gherkin-standards.md` § Tag Taxonomy](../../../../rules/gherkin-standards.md#tag-taxonomy)
+  (`@smoke`, `@risk-high`, `@platform-*`, `@domain-*`, `@flaky`, `@skip`). Do
+  not invent parallel tag vocabularies in the runner config; extend via
+  `@domain-*` only. The agent-driven `/qa-run` selector mirrors the same tag
+  expressions, so a scenario set is addressable identically from both surfaces.
+- **`@flaky` runs in its own non-gating job.** Quarantine `@flaky` scenarios in
+  a dedicated CI job that does not gate the merge queue, and never silently
+  retry flakes inside the gating suite. `@flaky` is a debt marker with an owner,
+  not a permanent label.
+- **The Cucumber JSON report is the headless evidence artifact.** Register the
+  Cucumber HTML/JSON reporter alongside the Playwright HTML reporter and publish
+  it (with the trace zips) so a headless CI invocation emits machine-readable
+  evidence next to the agent-driven [`/qa-run`](../../../../workflows/qa-run.md)
+  sweep. Wire the generate-then-run sequence to a single npm script so operators
+  never reconstruct it by hand.
+
+## Cross-References
 
 - Scenario authoring rules: `.agents/rules/gherkin-standards.md`.
+- Scenario authoring skill: `.agents/skills/stack/qa/gherkin-authoring/SKILL.md`.
 - Browser-level conventions: `.agents/skills/stack/qa/playwright/SKILL.md`.
 - Operator entry point: `.agents/workflows/qa-run.md`.