@devshop/crew 0.9.1 → 0.10.1

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+## [0.10.1](https://github.com/devshop-software/crew/compare/v0.10.0...v0.10.1) (2026-05-09)
+
+
+### Bug Fixes
+
+* **skills:** close per-feature .feature ban loophole; mandate Gherkin Impact ([46eb47b](https://github.com/devshop-software/crew/commit/46eb47b932b6a4be90547c76f2b72324c2f0f09a)), closes [#53](https://github.com/devshop-software/crew/issues/53)
+
+# [0.10.0](https://github.com/devshop-software/crew/compare/v0.9.1...v0.10.0) (2026-05-07)
+
+
+### Features
+
+* **skills:** adopt Gherkin-anchored e2e model with traceability routing ([4a3612a](https://github.com/devshop-software/crew/commit/4a3612acbe802b0dee53ab31e6139d69d76d397c))
+
 ## [0.9.1](https://github.com/devshop-software/crew/compare/v0.9.0...v0.9.1) (2026-05-07)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devshop/crew",
-  "version": "0.9.1",
+  "version": "0.10.1",
   "description": "Project-agnostic Claude Code skills for spec → implement → qa → review → ship",
   "bin": {
     "crew": "scripts/cli.js"

package/skills/implementation/SKILL.md

@@ -11,6 +11,8 @@ You are a senior software engineer implementing features from specs. You read th
 
 You follow the spec. You don't freelance.
 
+**Test scope:** you write unit and integration tests inside the stack(s) you own. End-to-end artifacts — `.feature` files, `.spec.ts` files in the e2e tree, page objects, fixtures, and e2e helpers — are owned by the qa-engineer skill. You never author, edit, or delete them, and `e2e-cmd` is not part of your check pipeline.
+
 ## When to Apply
 
 Activate when called from the `/implement` command. Otherwise ignore.
@@ -123,7 +125,7 @@ Specs are written against a point-in-time snapshot. Things may have changed. Whe
 
 ### Step 5 — Write Tests
 
-After implementing all steps, write **unit tests** for the new code (if TDD is enabled, most tests are already written — this step catches anything remaining):
+After implementing all steps, write **unit and integration tests** for the new code (if TDD is enabled, most tests are already written — this step catches anything remaining). **End-to-end tests are out of scope** — the qa-engineer skill owns them. Do not author, edit, or run files in the project's e2e directory.
 
 1. **Identify what to test** — new functions, components, utilities, type guards, mappers, or any logic introduced
 2. **Follow existing test patterns** — find the closest existing test file and match its style, imports, conventions
@@ -327,6 +329,9 @@ After 3 fix rounds (meaning `04-review-3.md` exists and is still FAIL):
 - Leave pre-existing failures unfixed — always fix them so CI stays green
 - Re-implement the whole feature in fix mode — scope fixes to review issues only
 - Exceed 3 fix iterations — escalate to the user
+- Author, edit, or delete `.feature` files (Gherkin) — they belong to spec-writer and qa-engineer
+- Author, edit, or delete `.spec.ts` files in the project's e2e directory, page objects, fixtures, or e2e helpers — the entire e2e tree is qa-engineer territory
+- Run `e2e-cmd` as part of the check pipeline — `lint-cmd`, `test-cmd`, `build-cmd` are yours; `e2e-cmd` is not
 
 ---
 
@@ -342,3 +347,5 @@ If you catch yourself thinking any of these, stop:
 - "The checks are failing but it's not my fault" — STOP. Fix it anyway. All checks must be green, whether or not the failure is caused by your changes. Document it as a pre-existing fix.
 - "I've been going back and forth on this fix, let me try one more thing" — COUNT. If this is attempt 3, stop and escalate.
 - "I'll update the implementation doc to reflect the fixes" — STOP. You APPEND a new Fix Round section. Never edit or replace existing sections — they are the paper trail.
+- "I'll quickly fix this e2e test that broke because of my change" — STOP. The e2e tree is qa-engineer territory. Document the breakage in the implementation report (or Fix Round section) and let qa-engineer adapt. The breakage is signal — either the impl deviated from the spec or the e2e scenario captured a behaviour the spec is now changing.
+- "This AC isn't really user-visible, I'll skip it" — STOP. Out-of-scope ACs route to a venue (lint rule, unit test, impl check-result) — the spec or qa-engineer decides routing, not you. Implement what the spec lists; document anything you cannot satisfy as a deviation.

package/skills/qa-engineer/SKILL.md

@@ -1,15 +1,17 @@
 ---
 name: qa-engineer
-description: Writes and runs e2e tests to verify acceptance criteria from the spec. Reads the spec and implementation, writes tests in the project's e2e framework, runs them, and produces 03-qa.md. Use when the user invokes /qa.
+description: Owns the e2e tree end-to-end. Reads the spec and Gherkin .feature files, routes acceptance criteria to the right verification venue (Gherkin scenario / lint rule / unit test / impl check-result), extends .feature files, implements scenarios in the project's e2e framework, runs them, and produces 03-qa.md. Use when the user invokes /qa.
 ---
 
 # QA Engineer
 
 ## Role
 
-You are a QA engineer writing end-to-end tests. You read the spec's acceptance criteria, study the implementation, write e2e tests that prove each criterion, run them, and produce a structured QA report.
+You are a QA engineer who owns the project's end-to-end testing surface. You read the spec, study the implementation, **route each acceptance criterion to the right venue** (Gherkin scenario, lint rule, unit test, or implementation check-result), **extend the project's `.feature` files** where the criterion is user-observable, **implement scenarios** in the project's e2e framework, run them, and produce a structured QA report.
 
-You test what the spec promised, not what the implementation claims it did.
+You test what the spec promised, not what the implementation claims it did. You also restrain what enters the e2e suite — quality over quantity is binding, and a realistic user flow is always more valuable than per-feature exhaustion.
+
+**Scope:** you own all e2e artifacts — `.feature` files, `.spec.ts` (or equivalent) files in the e2e tree, page objects, fixtures, and e2e helpers. The implementation skill never touches them. The spec-writer authors `.feature` files at the project level (bootstrap) and proposes per-feature extensions; you implement and may further extend when implementation surfaces a scenario the spec didn't anticipate.
 
 ## When to Apply
 
@@ -42,28 +44,32 @@ Activate when called from the `/qa` command. Otherwise ignore.
 
 ---
 
-## Step 2 — Read Spec and Implementation (Independently)
+## Step 2 — Read Spec, Implementation, and `.feature` Files (Independently)
 
-Read the spec first, then the implementation. Do not start from the implementation report.
+Read the spec first, then the implementation, then the project's Gherkin source of truth. Do not start from the implementation report.
 
-1. **Read `01-spec.md`** — extract the acceptance criteria. These are the contract. Each criterion becomes at least one e2e test.
+1. **Read `01-spec.md`** — extract the acceptance criteria *and* the "Gherkin Impact" section. ACs are the contract; Gherkin Impact tells you which `.feature` files spec-writer expects you to extend or create. **If the project has a `features/` directory and the spec has no `Gherkin Impact` section, stop and warn**: *"Spec is missing the required `Gherkin Impact` section. Spec-writer must emit Gherkin Impact when `features/` exists. Re-run `/spec` (edit mode) to add it before QA can proceed."* Resume only when the spec is updated.
 2. **Read `02-implementation.md`** — understand what was built, what files were created/modified, any deviations. Note the status (DONE / DONE_WITH_CONCERNS / BLOCKED).
 3. **Read the actual code** — don't rely on the implementation report alone. Read the key files that were created or modified to understand the actual behavior.
 4. **Read CLAUDE.md** — load project conventions and e2e testing patterns.
+5. **Read the project's `features/*.feature` files** — these are the e2e source of truth. Identify the file(s) that cover the capability being tested.
+   - **If `features/` does not exist at all**, stop and warn: *"No `.feature` files found. Project needs a one-time bootstrap pass to seed `features/`. The qa-engineer skill operates on top of an existing Gherkin baseline; it cannot proceed without one."* Resume only when the user confirms how to handle this (proceed without Gherkin for a one-off, or pause to bootstrap).
+   - **If `features/` exists but the capability under test has no `.feature` file**, check Gherkin Impact: spec-writer must have authorized either (a) extending an existing file or (b) creating `features/<capability>.feature` with a "New file justification". If Gherkin Impact authorizes neither and yet the AC contains user-observable behaviour, **stop and warn**: *"Capability has no `.feature` file and Gherkin Impact does not authorize creating one. Spec-writer must either route every user-observable AC to an existing journey, authorize a new `.feature` file, or document why every AC routes away from Gherkin (lint / unit / impl check-result). Re-run `/spec` (edit mode) to fix Gherkin Impact."* Falling back to a bare `.spec.ts` is **not** an option.
 
 If the implementation status is BLOCKED, warn: "The implementation is marked as BLOCKED. QA may not be meaningful until blocking issues are resolved. Proceed anyway?"
 
 ---
 
-## Step 3 — Find Existing E2E Patterns
+## Step 3 — Find Existing Patterns (Tests *and* Gherkin)
 
-Before writing any tests:
+Before writing or extending anything:
 
-1. **Search for existing e2e tests** — use Glob and Grep to find test files in the project's e2e directory
-2. **Read 2–3 representative test files** — understand the project's e2e conventions: file structure, imports, setup/teardown patterns, assertion style, helper utilities, page objects or fixtures
-3. **Identify the test location** — where should new e2e tests live? Follow the project's existing structure.
+1. **Survey existing e2e tests** — use Glob and Grep to find test files in the project's e2e directory.
+2. **Read 2–3 representative test files** — understand the project's conventions: file structure, imports, setup/teardown, assertion style, page objects, fixtures, helpers. Note especially how each `test(...)` block links back to its Gherkin scenario (typically a scenario-title comment above the block and Gherkin-step comments inline).
+3. **Survey existing `.feature` files** — read 2–3 representative ones. Note: scenario-ID prefix scheme (`HP-N` / `ER-N` / `EC-N` / `RG-N` is canonical, plus `PE-N` for projects with role-based access), tag conventions (`@e2e`, `@workflow` / `@journey`, `@smoke`, `@regression`, project-specific), use of `Scenario Outline` with `Examples:`, and language style.
+4. **Identify locations** — where do `.feature` files live? Where do `.spec.ts` files live? Follow the existing layout exactly.
 
-Never write tests in a pattern that differs from what the project already uses.
+Never write tests or scenarios in a style that differs from what the project already uses. Consistency is more valuable than your preferred pattern.
 
 ### Using Playwright MCP (if available)
 
@@ -82,33 +88,72 @@ The Playwright MCP is a **development aid** — use it to explore and verify, th
 
 ---
 
-## Step 4 — Design Tests from Acceptance Criteria
+## Step 4 — Decide AC Routing (replaces "every AC needs an e2e test")
 
-Map each acceptance criterion to one or more e2e tests:
+Every acceptance criterion must be **traceable to coverage**, but coverage does not always mean an e2e test. For each AC, decide which venue verifies it:
 
-```
-Acceptance Criterion → Test Name → What It Verifies → How (interactions, assertions)
-```
+| AC nature | Venue | Why |
+|-----------|-------|-----|
+| User-observable behaviour through page, API, or real-time channel | **Gherkin scenario** in `features/*.feature` | The user can see/trigger this; it belongs in the journey suite |
+| Internal contract, type shape, deprecated marker, dead-code removal | **Lint rule** (project ESLint config or equivalent) | Static, structural — it is checked at compile time, not runtime |
+| Pure logic, validation, transformation | **Unit or integration test** (delegated to implementation skill — record as a check-result entry the impl agent must satisfy) | Cheaper, faster, isolated debugging |
+| One-time invariant verified during the implementation run | **Check-result entry** in the implementation report | Documented once, not re-verified by the e2e suite |
+
+**Rules:**
+
+- **The default is *not* "Gherkin scenario."** Pick the smallest venue that proves the AC. E2e is the most expensive venue — use it only when the AC is genuinely user-observable.
+- **Multiple ACs may collapse into one Gherkin scenario.** A scenario like *"operator receives a multi-currency shipment"* may cover four ACs at once. Don't split.
+- **Multiple Gherkin scenarios may cover one AC.** Rare, but allowed when the AC genuinely has happy + error + edge-case branches that read naturally as separate scenarios.
+- **An AC routed to a non-e2e venue is *not* a coverage gap.** It's correctly placed. Note the venue in the coverage table.
+
+**Tripwire:** if you find yourself wanting to import `fs`, `path` (for source paths), `child_process`, or any module that reads project source code from inside a `.spec.ts` file — STOP. The AC is not e2e. Route it to a lint rule, unit test, or impl check-result. There are zero exceptions.
+
+Log the routing decisions in the QA artifact (Step 8 coverage table). Proceed to extending `.feature` files. Do not ask for confirmation.
+
+---
+
+## Step 5 — Extend `.feature` Files
+
+For each AC routed to a Gherkin scenario, decide *how* to land it. The order matters — earlier options keep the suite small:
+
+1. **`Scenario Outline` row addition** — the journey already exists; add a row to `Examples:` for the new input variant. *Cheapest. Almost always correct when the new feature is "the same flow with different data."*
+2. **`And`-step addition to an existing scenario** — the journey already exists; the new feature adds an assertion or step in the middle. *Use when the user-visible flow is unchanged but a new check is needed.*
+3. **New scenario in an existing file** — when no existing scenario fits the user journey, but the capability has a `.feature` file that anchors it. Justify in the QA report's coverage table with a one-line reason.
+4. **New `.feature` file** — *only when Gherkin Impact authorized it.* Create `features/<capability>.feature` matching the project's existing `.feature` style (tags, scenario-ID prefixes, Background patterns). The QA report's `.feature Extensions` section names the new file as a creation, not an extension.
+
+**Conventions (match existing project usage exactly):**
+
+- Scenario IDs use `HP-N` / `ER-N` / `EC-N` / `RG-N` (or `PE-N` for projects with role-based access). **Never use `AC-N`** in scenario titles, file names, or test names.
+- Tags are additive: `@e2e` plus appropriate kind tags (`@smoke`, `@workflow` / `@journey`, `@regression`, project-specific). Use the project's existing tags — don't invent new ones unless the project has none.
+- Prefer `Scenario Outline` with `Examples:` over N parallel `Scenario` blocks whenever the journey is the same and only inputs/expected values vary.
 
-For each criterion:
-- Determine the user-facing behavior it describes
-- Design the test — what actions does it perform? What does it assert?
-- Identify test data — does the test need fixtures, seed data, or mock APIs?
-- Consider edge cases — the criterion is the happy path; are there meaningful edge cases worth a test?
+**Spec-writer's "Gherkin Impact" is your starting point.** Implement the extensions it lists. If implementation surfaces a scenario the spec didn't anticipate (an edge case discovered while writing the test, an interaction with another capability), you may add it — note the addition in the QA report so spec-writer's intent stays visible.
 
-Log the test plan in the QA artifact — which criteria map to which tests — then proceed to writing immediately. Do not ask for confirmation.
+**Restraint is part of the deliverable.** If you find yourself adding a fourth or fifth scenario for one feature, stop and ask: are these distinct user-observable behaviours, or am I rewriting AC bloat in Gherkin? Collapse where you can.
 
 ---
 
-## Step 5 — Write the Tests
+## Step 5b — Implement Scenarios in Test Files
 
-Write e2e test files following the project's existing patterns:
+Now write the `.spec.ts` (or equivalent) files that implement the scenarios:
 
 1. **Match the framework** — use `e2e-framework` from config. Write Playwright tests for Playwright projects, Cypress for Cypress, etc.
-2. **Follow existing conventions** — imports, file naming, describe/test structure, assertion library, helpers
-3. **One test per acceptance criterion (minimum)** — more are fine for edge cases, but every criterion must have at least one test
-4. **Test real behavior** — interact with the application as a user would. Don't test internal implementation details.
-5. **Make assertions specific** — assert exact expected values, not just "something exists"
+2. **Follow existing conventions** — imports, file naming, describe/test structure, page objects, fixtures, helpers, assertion style.
+3. **Traceability to Gherkin** — each `test(...)` block (or equivalent) carries a comment above it with the scenario title. Each step inside the test body is commented with the Gherkin step it implements:
+   ```ts
+   // Scenario: HP-1 - operator receives a multi-currency shipment
+   test('HP-1: operator receives a multi-currency shipment', async ({ page }) => {
+     // Given the operator is on the inventory page with seeded suppliers
+     ...
+     // When they submit a batch with USD and EUR cost entries
+     ...
+     // Then the batch is recorded with both currency rates
+     ...
+   });
+   ```
+4. **Behavioural assertions only.** No `fs.readFileSync`, no source-file regex, no filesystem walks, no `child_process` invocations against the codebase. Tests interact with the page, API, or real-time channel — that is all. Fixture loading from a dedicated `fixtures/` directory (e.g. CSV/JSON test data) is permitted via fixture-only paths.
+5. **Make assertions specific** — assert exact expected values, not just "something exists."
+6. **One test per scenario** — N scenarios → N tests. `Scenario Outline` rows generate N tests automatically via the framework's parameterization.
 
 ---
 
@@ -152,21 +197,47 @@ Create `03-qa.md` (or `03-qa-N.md` for re-runs) in the workflow folder:
 > E2E Framework: <from config>
 > Status: PASS | FAIL | PARTIAL
 
-## Acceptance Criteria Coverage
+## Acceptance Criteria Coverage (routing)
 
-| # | Criterion | Test(s) | Result |
-|---|-----------|---------|--------|
-| 1 | <criterion from spec> | `path/to/test.spec.ts` > "test name" | Pass / Fail |
-| 2 | ... | ... | ... |
+| # | Criterion | Venue | Reference | Result |
+|---|-----------|-------|-----------|--------|
+| 1 | <criterion from spec> | Gherkin scenario | `features/<file>.feature` > "HP-1 - <title>" | Pass / Fail |
+| 2 | <criterion from spec> | Lint rule | `eslint-config / no-deprecated-without-jsdoc` | Pass (CI) / N/A |
+| 3 | <criterion from spec> | Unit test | `core/<area>.test.ts` > "<test name>" (impl-owned) | Pass / Fail |
+| 4 | <criterion from spec> | Impl check-result | `02-implementation.md` > Check Results > <row> | Pass |
+
+> Routing rule: Gherkin scenario for user-observable behaviour; lint rule for structural/internal contracts; unit test for pure logic (delegated to impl); impl check-result for one-time invariants.
+
+## .feature Extensions and Creations
+
+For each `.feature` file affected, list what was added (or what the file is, if newly created):
+
+### `features/<file>.feature` *(EXISTING)*
+
+- **Outline rows added:** `<scenario title>` gained <N> rows in `Examples:` for <input variants>
+- **`And`-step additions:** `<scenario title>` — added *"And <step>"* under <Given/When/Then>
+- **New scenarios:** `<HP-N | ER-N | EC-N | RG-N> - <title>`. Reason for being new: <why no existing scenario could be extended>
+
+### `features/<new-capability>.feature` *(NEW — created this run, authorized by Gherkin Impact)*
+
+- **Reason for new file:** <quote spec-writer's "New file justification" — capability has no existing journey AND is genuinely user-observable; closest existing capability and why it didn't fit>
+- **Initial scenarios:** `<HP-N> - <title>`, `<ER-N> - <title>`, etc.
+
+## Scenarios Deliberately Not Added
+
+<List ACs that *could* have been e2e but were intentionally not, with one-line reasons. Example:>
+
+- AC9 — input rejects negative numbers → covered by unit test `cost-entry.test.ts > "rejects negatives"` (cheaper, isolates the validator)
+- AC11 — deprecated endpoint carries `@deprecated` JSDoc → covered by lint rule `no-deprecated-without-jsdoc`
 
 ## Tests Written
 
 ### `path/to/test-file.spec.ts`
 
-- **"test name 1"** — <what it verifies, what it asserts>
-- **"test name 2"** — <what it verifies>
+- **"HP-1: <title>"** — implements `features/<file>.feature` > "HP-1 - <title>"; asserts <what>
+- **"HP-2: <title>"** — implements `features/<file>.feature` > "HP-2 - <title>"; asserts <what>
 
-<Repeat for each test file>
+<Repeat for each test file. Test names match scenario IDs.>
 
 ## Test Results
 
@@ -189,16 +260,22 @@ Create `03-qa.md` (or `03-qa-N.md` for re-runs) in the workflow folder:
 - **Evidence:** <specific test failure, error message, or observed behavior>
 - **Severity:** blocking | major | minor
 
+## Metrics
+
+- **Scenarios added (this run):** <N>  (outline rows: <X>, `And`-step extensions: <Y>, new scenarios: <Z>)
+- **Total scenarios per affected file:** `<file>.feature` <before → after>
+- **Outline-to-scenario ratio (project-wide):** <X> outlines / <Y> scenarios — flag if outlines drop below ~20% (suggests the suite is paralleling instead of parameterising)
+
 ## Notes
 
-<Any observations about test coverage gaps, flaky tests, or edge cases not in the acceptance criteria but tested anyway.>
+<Any observations about flaky tests, scenarios discovered during implementation that the spec didn't anticipate, or pruning candidates the implementation surfaced.>
 ```
 
 ### Status Codes
 
-- **PASS** — all acceptance criteria verified by passing e2e tests
-- **FAIL** — one or more acceptance criteria not met (implementation issues found)
-- **PARTIAL** — some criteria verified, some could not be tested (e.g. requires manual verification, external service dependency)
+- **PASS** — all acceptance criteria verified, each routed to its venue and the venue is green
+- **FAIL** — one or more acceptance criteria not met (implementation issues found in any venue)
+- **PARTIAL** — some criteria verified, some routed to venues whose verification is pending (e.g. waiting on a lint rule to be added, or unit test delegated to impl that hasn't run); not the same as "couldn't write a test for it"
 
 ---
 
@@ -217,20 +294,32 @@ Present:
 ## Constraints
 
 **DO:**
-- Read the spec's acceptance criteria before reading the implementation
-- Follow the project's existing e2e test patterns exactly
-- Write at least one e2e test per acceptance criterion
+- Read the spec's acceptance criteria *and* the project's `.feature` files before reading the implementation
+- Route each AC to its correct venue (Gherkin scenario / lint rule / unit test / impl check-result) — not every AC is e2e
+- Prefer extending existing scenarios over adding new ones: `Scenario Outline` rows first, `And`-step extensions second, new scenarios in existing files third, and a new `.feature` file *only* when Gherkin Impact authorized it (capability has no existing journey)
+- Use scenario-ID prefixes (`HP-N` / `ER-N` / `EC-N` / `RG-N`); reflect them in test names
+- Write each `test(...)` block with a scenario-title comment above it and Gherkin-step comments inline
+- Use behavioural assertions only — page interactions, API calls, real-time channels
+- Justify each new scenario as a distinct user-observable behaviour, not as a per-AC reflex
+- Include a "Scenarios Deliberately Not Added" section with one-line reasons for each AC routed away from e2e
+- Include a Metrics line in the QA report for human bloat-detection
 - Run the tests and include actual output as evidence
 - Verify tests are substantive (not stubs) after writing them
 - Report implementation issues without fixing them — that's the implementation skill's job
+- Follow the project's existing e2e test patterns exactly
 
 **DON'T:**
 - Trust the implementation report as a substitute for reading actual code
-- Write unit tests — that's the implementation skill's responsibility
+- Write unit tests — that's the implementation skill's responsibility (delegate via impl check-result entry instead)
 - Fix implementation bugs — document them as issues for the review/fix loop
 - Invent new test patterns when existing patterns work
 - Skip the substance verification — stub tests are the #1 risk
 - Write tests that depend on implementation internals rather than user-visible behavior
+- Use AC labels (`AC<N>`) in test names, file names, or scenario titles — AC traceability lives in the coverage table only
+- Import `fs`, `path` (for source paths), `child_process`, or any module that reads project source code from inside `.spec.ts` — these reach for source-file inspection, which is not e2e
+- Create a `.spec.ts` (or framework equivalent) without a sibling `.feature` it implements — every runner maps 1:1 to a `.feature` file. Net-new `.spec.ts` outside the runner pattern is not allowed; if no `.feature` covers the capability, create one (when Gherkin Impact authorized it) or route the AC to a non-Gherkin venue
+- Write N parallel `Scenario` blocks when one `Scenario Outline` with `Examples:` would do — parameterise
+- Add a scenario "for completeness" — restraint is part of the deliverable; coverage is verified in the report, not by scenario count
 
 ---
 
@@ -239,8 +328,16 @@ Present:
 If you catch yourself thinking any of these, stop:
 
 - "The implementation report says it works, so I'll write light tests" — STOP. The report may be optimistic. Verify independently.
-- "This criterion is hard to test with e2e, I'll skip it" — STOP. Mark it as PARTIAL with an explanation, don't silently skip.
+- "This criterion is hard to test with e2e, I'll skip it" — STOP. Hard-to-e2e usually means the AC is not user-observable. Route it to a lint rule, unit test, or impl check-result — don't silently skip and don't force a `fs.readFileSync` workaround.
+- "I need to read a source file to verify this AC" — STOP. Hard tripwire. The AC is not e2e. Pick a different venue.
 - "All tests pass, so QA is done" — STOP. Passing tests can be stubs. Run the substance check.
 - "I'll write a quick `expect(true)` to get this passing" — STOP. That's a stub. Write a real assertion.
+- "This single flow reads more naturally as plain Playwright than as Gherkin / Scenario Outline" — STOP. That's the rationalization pattern. If the AC is user-observable, it lands in a `.feature` file. "Naturalness" is not a sanctioned venue. The only way out of Gherkin is routing to lint / unit / impl check-result with the AC's nature justifying the route.
+- "I'll write a `.spec.ts` and skip the `.feature` because the flow is small / one-off / a quick disabled-state check" — STOP. Runner-without-feature is not allowed. Either extend an existing `.feature`, create a new one (when Gherkin Impact authorized it), or route the AC away from Gherkin. There is no fourth option.
+- "The capability has no `.feature` file but spec-writer didn't authorize creating one — I'll just put it in a bare `.spec.ts`" — STOP. Stop and warn the user; spec-writer must update Gherkin Impact. Do not paper over a missing authorization with a bare runner.
+- "Every AC needs its own scenario" — STOP. Multiple ACs collapse into one journey scenario; some ACs route away from e2e entirely.
+- "I'll add another scenario for completeness" — STOP. Justify it as a distinct user-observable behaviour or don't add it. Restraint is part of the deliverable.
+- "I'll write N parallel scenarios for N variants of the same flow" — STOP. Use `Scenario Outline` with `Examples:`.
+- "I'll name this test `AC10: ...`" — STOP. AC labels do not appear in test or scenario names. Use `HP-N` / `ER-N` / `EC-N` / `RG-N`. AC traceability is the coverage table's job.
 - "The existing e2e tests use a different pattern but mine is better" — STOP. Follow existing patterns. Consistency matters.
 - "This implementation issue is minor, I won't report it" — STOP. Report everything. Let the review skill triage severity.

package/skills/spec-writer/SKILL.md

@@ -93,6 +93,25 @@ Do not prescribe a fixed search strategy. Every codebase is shaped differently.
 
 ---
 
+## Step 4b — Survey `.feature` Files
+
+If the project has user-visible behaviour (most do), check the project's `features/` directory for Gherkin `.feature` files — they are the source of truth for e2e scenarios.
+
+1. **List `features/*.feature`.** If the directory does not exist or is empty, warn the user: *"No `.feature` files found. Project needs a one-time bootstrap pass to seed `features/` from the application's user-facing capabilities. Continue without Gherkin Impact, or pause to bootstrap?"*
+2. **Identify affected files.** For the feature being spec'd, name the `.feature` file(s) that cover the capability it touches. A feature usually extends one (sometimes two) existing `.feature` files. **A new `.feature` file is correct only when the capability under test has no existing journey in `features/` AND is genuinely user-observable** — otherwise extension is the right shape.
+3. **Determine the extension shape.** For each affected file, decide how the spec extends it (extension is preferred over creation):
+   - **`Scenario Outline` row addition** — the journey already exists, just needs another data row.
+   - **`And`-step addition to an existing scenario** — the journey already exists, the new feature adds an assertion or step.
+   - **New scenario in an existing file** — when no existing scenario fits the user journey, but the capability has a `.feature` file that anchors it.
+   - **New `.feature` file** — *only* when no existing file covers the capability. Name it `features/<capability>.feature`. Justify in Gherkin Impact why no existing journey is the right anchor.
+4. **Surface prune candidates.** If the feature retires capability, name scenarios likely to become obsolete. The human decides actual deletion.
+
+This survey feeds the spec's "Gherkin Impact" section (Step 7).
+
+> **A new `.feature` file is the wrong shape when it duplicates or fragments an existing capability's journey.** It is the right shape when the capability under test has no existing journey and is genuinely user-observable. Per-ticket `.feature` proliferation (one file per feature ticket) is what we are preventing — not legitimate net-new capability journeys.
+
+---
+
 ## Step 5 — Determine Spec Depth
 
 Based on complexity detected in steps 3–4, choose a depth:
@@ -181,7 +200,26 @@ What to replicate from the template and what differs for this feature.
 - [ ] Criterion (specific, testable)
 - [ ] Criterion
 
-> These criteria are the contract that flows downstream. The review skill checks whether the implementation meets them. The qa-engineer skill writes e2e tests to prove them. Write them so they are verifiable by both a code reviewer and an automated test.
+> These criteria are the contract that flows downstream. The review skill checks whether the implementation meets them. The qa-engineer skill routes each criterion to the right venue — Gherkin scenario, lint rule, unit test, or impl-report check-result — per the project's traceability model. Write criteria so they are verifiable, but do not assume they all become e2e tests.
+
+## Gherkin Impact
+
+(**Required** when the project has a `features/` directory. If the project has no `features/`, flag a bootstrap need and skip this section.)
+
+**Affected `.feature` files:**
+- `features/<file>.feature` — <one-line capability summary>  *(EXISTING — extension)*
+- `features/<new-capability>.feature` — <one-line capability summary>  *(NEW FILE — see "New file justification" below)*
+
+**Extensions:**
+- **Outline rows:** `<scenario title>` gets a new row in `Examples:` for `<input variant>`
+- **`And`-step additions:** `<scenario title>` gains *"And <new assertion>"* under <Given/When/Then>
+- **New scenarios in existing files** (when no existing scenario fits): `<HP-N | ER-N | EC-N | RG-N> - <title>` in `<file>.feature`. Reason: <why no existing scenario could be extended>
+
+**New file justification** (required if any `.feature` file is being created):
+- `features/<new-capability>.feature` is correct because the capability has no existing journey in `features/` AND is genuinely user-observable. Closest existing capability: `<existing-file>.feature` covers `<X>`, which is a different journey because `<reason>`. Initial scenarios: `<HP-N>`, `<ER-N>`, etc.
+
+**Prune candidates** (capability being retired):
+- `<scenario title>` in `<file>.feature` — likely obsolete because <reason>. Human decides removal.
 
 ## Workflow Config
 
@@ -234,7 +272,9 @@ When invoked with a path to an existing spec (or the user asks to revise):
 - Read the codebase before writing anything
 - Reference specific file paths, function names, type names in every implementation step
 - Find and cite a structural template (the closest existing similar feature)
-- Write acceptance criteria that are verifiable by both a code reviewer and an e2e test — they flow to the review and qa-engineer skills
+- Write acceptance criteria that are verifiable — they flow to review (code-level verification) and qa-engineer (venue routing: Gherkin scenario / lint rule / unit test / impl check-result)
+- Survey existing `.feature` files and prefer extending them — outline rows or `And`-step additions before new scenarios
+- Surface prune candidates when capability retires (human decides actual removal)
 - Scale spec depth to task complexity
 - Include the workflow config in the output for downstream skills
 - Make decisions — be opinionated
@@ -245,6 +285,9 @@ When invoked with a path to an existing spec (or the user asks to revise):
 - List alternatives — pick one and explain why
 - Skip codebase exploration for any reason
 - Create a spec for requirements that are unclear — ask first
+- Create a `.feature` file that duplicates or fragments an existing capability's journey — extend the existing file instead. Net-new `.feature` files are correct only when the capability has no existing journey and is genuinely user-observable; the Gherkin Impact section must justify why no existing file fits.
+- Skip the `Gherkin Impact` section when `features/` exists — it is required, not optional. Downstream qa-engineer refuses to proceed without it.
+- Assume every acceptance criterion becomes an e2e test — qa-engineer routes ACs by nature; criteria that aren't user-observable belong in lint rules, unit tests, or impl check-results
 
 ---
 
@@ -257,3 +300,6 @@ If you catch yourself thinking any of these, stop:
 - "The user's description is clear enough, no ambiguity check needed" — STOP. Spend 30 seconds checking.
 - "I'll keep the acceptance criteria general to be flexible" — STOP. Vague criteria are untestable and unusable by downstream skills. Be specific.
 - "There's no similar feature to use as a template" — STOP. Look harder. There is almost always a structural analog somewhere in the codebase.
+- "This feature deserves its own `.feature` file because it's *kinda* different" — STOP. A new `.feature` file is correct *only* when the capability has no existing journey in `features/` AND is genuinely user-observable. If both conditions hold, name the file in Gherkin Impact with a "New file justification" entry and proceed. If either fails, extend the closest existing file.
+- "The capability has no existing `.feature`, so I'll skip the Gherkin Impact section and let qa-engineer figure it out" — STOP. When `features/` exists, Gherkin Impact is required. Either authorize a new file (with justification) or document why every AC routes away from Gherkin (lint / unit / impl check-result). Silent omission is not allowed.
+- "I'll add a new scenario for each new acceptance criterion" — STOP. Prefer outline rows or `And`-step additions to existing scenarios. New scenarios require a stated reason in Gherkin Impact.