@execuro-sw-ecosystem/sw-ecosystem-agentic-harness 0.1.0

package/skills/sw-verify-feature/reference/verification-report-template.md

@@ -0,0 +1,57 @@
+# Verification report template
+
+Copy verbatim, fill, delete every `<!-- -->` hint. Keep section numbers and titles unchanged — a re-run of `sw-verify-feature` diffs against the previous report by these anchors, and the `AC-n` identifiers must match the source spec and PRD exactly (an AC present only in the PRD still keeps its PRD numbering).
+
+This report is a record of one verification run, not a living document like the PRD or tech spec. Never soften a `not pass` into `partly` to be agreeable, and never omit a line to make the report shorter — a missing gate line reads as "not checked," which is itself a defect.
+
+---
+
+```markdown
+# VERIFICATION-NNNN — <Feature name>
+
+| | |
+| --- | --- |
+| **Overall verdict** | fully verified \| not fully verified |
+| **Source spec** | specs/NNNN-slug-spec.md |
+| **Run date** | YYYY-MM-DD |
+| **Verifiers consulted** | tests, architecture, code-quality <!-- list only the ones that actually ran; append "— not consulted: <name> (<reason>)" if any failed to spawn -->|
+
+## 1. Per-AC Verdicts
+
+One row per acceptance criterion in the union of the source spec and the source PRD — same `AC-n` numbering, no additions, no omissions. A verifier that reported no line at all for an AC counts as `not pass` from that verifier, not a silent skip. An AC present in the PRD but missing from the spec still gets a row, verdict `not pass`, dimension `traceability` — no verifier could have tested an AC the spec never mentions.
+
+| AC | Verdict | Failing dimension(s) | Evidence | Note |
+| --- | --- | --- | --- | --- |
+| <!-- AC-1 --> | <!-- pass / partly / not pass --> | <!-- tests / architecture / code-quality / traceability, or "—" if pass --> | <!-- test names, file:line, e2e result, screenshot path --> | <!-- one sentence from the verifier that drove the downgrade, or "—" if pass --> |
+
+## 2. Whole-Feature Gates
+
+Gates that don't map to a single AC, carried from each verifier unchanged and prefixed by source.
+
+```
+[tests] Test Health Report: <!-- pointer to §3, or "no tests flagged" -->
+[architecture] Project guidelines: <!-- "project rules applied: N sections from project/guidelines/…", "Project guidelines: none — inherited from Shopware platform guidelines", "not found: guidelines/<v>/<file> — MCP unavailable, disk fallback used", or "not found: guidelines/<v>/<file> (reported, continued)" for a single missing file while the MCP itself is reachable -->
+[architecture] shopware-cli Twig linters (admin-twig, storefront-twig) | <!-- pass/fail/not run --> | <!-- N errors, N warnings, or install command -->
+[code-quality] PHPStan/ESLint/Stylelint (shopware-cli --full) | <!-- pass/fail/not run --> | <!-- N errors, N warnings, or install command -->
+[code-quality] PHPUnit regression (full plugin suite) | <!-- pass/fail --> | <!-- N failing tests, list if any -->
+[code-quality] Project guidelines: <!-- "project rules applied: N sections from project/guidelines/…", "Project guidelines: none — inherited from Shopware platform guidelines", "not found: guidelines/<v>/<file> — MCP unavailable, disk fallback used", "not found: guidelines/<v>/<file> (reported, continued)", or "same as [architecture] above" -->
+[tests] PRD AC coverage: <!-- <passed>/<total> passed, <failed> failed, <absent> absent — omit this line entirely if no source PRD was found, do not report 0/0 -->
+```
+
+## 3. Test Health Report
+
+Every test the tests verifier located, `healthy` or `flagged` with the specific reason. Empty only if the tests verifier was not consulted — state that explicitly rather than leaving the section blank with no note.
+
+```
+test::method (type) — healthy
+test::method (type) — flagged: <specific reason>
+```
+
+## 4. Overall Verdict
+
+<!-- One paragraph: fully verified, or the count of ACs not passing/partly plus whether every whole-feature gate passed. A "not run"/"not active" gate does not block per-AC verdicts but must be named here rather than silently reading as fully verified. -->
+```
+
+---
+
+Naming: save as `specs/NNNN-slug-verification.md`, same `NNNN-slug` as the spec it verifies. A re-run overwrites the previous report in place — this is a snapshot of the latest run, not an append-only log; if the caller wants history, that's what git provides.

package/skills/sw-verify-feature-ac-tests/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: sw-verify-feature-ac-tests
+description: Verify that a feature's acceptance criteria are backed by tests that actually exist, actually pass, and actually test what their name/comment/PHPDoc claims. Classifies tests by type (API/PHPUnit, Admin Panel/Playwright, Storefront/Playwright, CLI/PHPUnit), runs a test-health audit to catch false, mismatched, or unhealthy tests, then reports per-AC Coverage and Execution as pass / partly / not pass. One of three parallel verifiers spawned by sw-verify-feature; can also be run standalone.
+when_to_use: Trigger phrases — "verify AC tests for spec 0007", "audit test health for this feature", "are these tests actually testing what they claim", "check test coverage for epic 1".
+argument-hint: [specs/NNNN-slug-spec.md]
+allowed-tools: Read Glob Grep Bash mcp__playwright__browser_navigate mcp__playwright__browser_click mcp__playwright__browser_type mcp__playwright__browser_fill_form mcp__playwright__browser_snapshot mcp__playwright__browser_take_screenshot mcp__playwright__browser_wait_for mcp__playwright__browser_console_messages mcp__playwright__browser_network_requests mcp__playwright__browser_evaluate mcp__playwright__browser_select_option mcp__playwright__browser_press_key mcp__playwright__browser_hover mcp__playwright__browser_tabs mcp__playwright__browser_close
+---
+
+# sw-verify-feature-ac-tests
+
+Independently verify the test layer of a feature against its spec. This skill performs the verification itself using its own tools — it does not delegate execution to an agent. It answers one question per AC: is this acceptance criterion actually, healthily, tested?
+
+## Read-only contract
+
+This skill observes and reports. It never changes the project: no file created, edited, or deleted (tests included), no fix applied, no migration run, no git action. Cache clears and `theme:compile` to observe current code/UI are the only state changes allowed. Anything found wrong is a report line, never a fix.
+
+The one exception is failure screenshots (step 5): written under `var/verification-screenshots/`, which is gitignored, never inside tracked project paths.
+
+## Inputs
+
+| Argument | Behaviour |
+| --- | --- |
+| Path to `specs/NNNN-slug-spec.md` | Verify the AC tests for this spec against the current codebase |
+| `; ` followed by a detected Shopware/PHP version + evidence (e.g. from `sw-verify-feature`'s brief) | Use it as verified — no re-detection needed |
+| Nothing | Ask the user for the spec path |
+
+## Procedure
+
+### 0. Shopware/PHP version and readiness
+
+**Version:** from `args` if stated with evidence, use it as verified; else detect via `vendor/shopware/core/composer.json` → `composer.lock` → `composer.json` ("unconfirmed"). Ambiguous or unknown → stop, never guess — blocking question to the caller, or ask the user if run standalone. Version-specific test-utility names (traits, stubs, helper APIs) differ enough between minors to make a wrong guess produce a false pass/fail.
+
+Readiness: read the `sw-setup` table from `args`, or invoke `sw-setup` yourself standalone. An unticked row a type needs (vendor/ — API/CLI; Acceptance-test project, Playwright browsers, ATS env — Admin Panel/Storefront) → `not run (environment)` for that AC/type, naming `/sw-setup`; never `partly`.
+
+### 1. Load the AC list
+
+Read the spec's acceptance criteria and, for each, the test(s)/scenario(s) defined.
+
+### 2. Classify relevant test types per AC
+
+For each AC, determine which of these apply:
+
+- **API** — Store API / Admin API behavior (PHPUnit functional tests)
+- **Admin Panel** — Administration UI behavior (Playwright, e2e headed)
+- **Storefront** — Storefront UI behavior (Playwright, e2e headed)
+- **CLI** — `bin/console` command behavior (PHPUnit)
+
+An AC can require more than one type (e.g. an Admin API endpoint plus the Admin UI screen calling it). If the spec doesn't name the type explicitly, infer it from the behavior. Note the expected type(s) before searching — the coverage baseline; a type the AC needs but has no test is a coverage gap, not something to drop.
+
+### 3. Locate the actual tests
+
+For each AC/type, find the test file/method that corresponds to it, matching by name/description/PHPDoc against the spec — not by assumption. Record what you found (or didn't) per AC/type.
+
+An AC with no locatable test for a needed type is `not pass` for that type regardless of how "done" the feature looks.
+
+
+### 4-6. Test health audit, execution and coverage scoring
+
+Follow `reference/audit-execute-score.md` in this skill's directory: audit each located
+test against what its name, comment or PHPDoc claims, execute the relevant suites, then
+score Coverage and Execution per AC. Read-only — never edit or repair a test to make it
+pass.
+
+### 7. Report
+
+```
+Test Health Report:
+  test::method (type) — healthy
+  test::method (type) — flagged: <specific reason>
+
+AC-n | Coverage: pass/partly/not pass/not run (environment) | Execution: pass/partly/not pass | types covered | evidence (test names, e2e result, screenshot path if a failure was captured) | note if partly/not pass/not run
+```
+
+Then a one-line verdict: fully covered and healthy, or the count of ACs not passing/partly plus a pointer to the Test Health Report entries that drove those scores.
+
+Never mark an AC `pass` to be agreeable. A flagged test is a reason to downgrade, not a detail to omit — `partly` always carries the one-sentence reason for the doubt.

package/skills/sw-verify-feature-ac-tests/reference/audit-execute-score.md

@@ -0,0 +1,40 @@
+# Audit, execute and score
+
+Steps 4-6 of `sw-verify-feature-ac-tests`, entered once the relevant test types are classified and the actual tests located. The health audit runs before execution on purpose: a test that does not test what it claims must not be allowed to score an AC green by passing.
+
+### 4. Test health audit
+
+For every test located in step 3, read its actual body — not just its name — and classify it `healthy` or `flagged`. Flag any of:
+
+- **False/errored test**: trivial assertions (`assertTrue(true)`), tests marked `skipped`/`incomplete`, assertions that can never fail given the setup, or swallowed exceptions instead of a failing test.
+- **Name/intent mismatch**: the method name, comment, or PHPDoc claims to verify X, but the body verifies Y or nothing related.
+- **Unhealthy**: heavy mocking that replaces the behavior under test, assertions on implementation details (call counts, private state) over observable behavior, timing-dependent waits/sleeps, or setup guaranteeing a green result regardless of the code under test.
+
+Record each flagged test with its specific reason — this list is the Test Health Report.
+
+### 5. Execute
+
+Run the suites relevant to the types identified in step 2:
+
+- API / CLI → PHPUnit
+- Admin Panel / Storefront → Playwright MCP, headed/click-through — actually drive the flow described in the spec (navigate, click, type, read the resulting DOM/network), not a blind DOM assertion.
+
+If a live check doesn't reflect an already-applied change, rule out stale cache before concluding the implementation is wrong.
+
+**On any failure or unexpected state**, capture evidence before moving on:
+- Admin Panel / Storefront (Playwright) → `mcp__playwright__browser_take_screenshot` at the point of failure, saved to `var/verification-screenshots/<spec-slug>/AC-n-<type>-<short-label>.png`. Take it before dismissing/navigating away, so it shows the actual failure, not a recovered page.
+- API / CLI (PHPUnit) → no screenshot; capture the failing assertion output/response body as evidence text instead.
+
+Record **Execution: pass / no pass** per test type actually run, with the screenshot path (if any) attached as evidence for every failure.
+
+### 6. Score coverage per AC
+
+For each AC, per type identified in step 2:
+
+- **pass** — a `healthy` test exists and its execution passed.
+- **partly** — a test exists but is `flagged` (health doubt), or it exists and passes but only covers part of the AC's described behavior, or execution could not be conclusively determined (e.g. a flaky-looking run worth a second opinion rather than an outright fail).
+- **not pass** — no test found, the located test is flagged false/mismatched with none other covering the claim, or execution failed.
+- **not run (environment)** — step 0's table shows an unticked row the type needs; name `/sw-setup`, never downgrade to `partly`/`not pass`.
+
+Roll per-type scores into one **Coverage** verdict: `pass` only if every type is `pass`; `not pass` if any is `not pass`; else `not run (environment)` if any is `not run (environment)`; else `partly`.
+

package/skills/sw-verify-feature-architecture/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: sw-verify-feature-architecture
+description: Verify that a feature's implementation matches the architectural decisions its spec made, and complies with Shopware's own Core conventions plus any written Project guidelines this repo defines. Reports per-AC pass/partly/not pass with the specific guideline or mismatch behind any non-pass. One of three parallel verifiers spawned by sw-verify-feature; can also be run standalone.
+when_to_use: Trigger phrases — "verify architecture for spec 0007", "does this implementation follow the spec's design", "check Core/Project guideline compliance for this feature", "architecture audit for epic 1".
+argument-hint: [specs/NNNN-slug-spec.md]
+allowed-tools: Read Glob Grep Bash mcp__ShopwareDevKnowledgeBase__list_docs mcp__ShopwareDevKnowledgeBase__grep_docs mcp__ShopwareDevKnowledgeBase__read_doc mcp__ShopwareDevKnowledgeBase__kb_status
+---
+
+# sw-verify-feature-architecture
+
+Independently verify the architecture layer of a feature against its spec. This skill performs the verification itself using its own tools — it does not delegate the check to an agent. It answers one question per AC: does the real implementation match the architectural decision the spec made, and does it follow Shopware's Core conventions plus this project's own written guidelines (if any exist)?
+
+## Read-only contract
+
+This skill observes and reports. It never changes the project: no file created, edited, or deleted, no fix applied, no migration run, no git action.
+
+## Inputs
+
+| Argument | Behaviour |
+| --- | --- |
+| Path to `specs/NNNN-slug-spec.md` | Verify the architecture for this spec against the current codebase |
+| `; ` followed by a detected Shopware/PHP version + evidence (e.g. from `sw-verify-feature`'s brief) | Use it as verified — no re-detection needed |
+| Nothing | Ask the user for the spec path |
+
+## Procedure
+
+### 0. Shopware/PHP version
+
+**Version:** from `args` if stated with evidence, use it as verified; else detect via `vendor/shopware/core/composer.json` → `composer.lock` → `composer.json` ("unconfirmed"). Ambiguous or unknown → stop, never guess — blocking question to the caller, or ask the user if run standalone. Extension points, DAL flags, and deprecations checked in step 2 below are version-specific.
+
+### 1. Load the AC list and architectural decisions
+
+Read the spec's acceptance criteria and, for each, the architectural/technical decision it names (extension point, DAL model, DI/decoration target, migration, cart/checkout hook, API surface, etc.).
+
+
+### 2. Gather guideline sources
+
+Follow the "Step 2" half of `reference/guidelines-and-twig.md` in this skill's
+directory.
+
+### 3. Verify each AC
+
+For every AC, inspect the actual code that implements it and check:
+
+- **Architectural mapping**: does the implementation use the extension point/pattern the spec's decision names? A passing test with an implementation that diverges from the spec's decision (e.g. spec says event subscriber, code patches a core class) is not a pass here even if the tests skill scores it green.
+- **Core compliance**: does it violate a Core convention gathered in step 2 (e.g. a `vendor/` patch, a raw un-versioned FK on a versioned entity, price mutated in a subscriber instead of a cart processor, a global/context-free read)? Any such violation is `not pass`.
+- **Project compliance**: does it violate a Project guideline found in step 2, if any exist? Weight this the same as a Core violation.
+
+
+### 4. Guardrail: shopware-cli Twig linters
+
+Follow the "Step 4" half of `reference/guidelines-and-twig.md` in this skill's
+directory. Read-only: report what the linter says, never fix it.
+
+### 5. Report
+
+```
+AC-n | pass/partly/not pass | Core/Project guideline violated or architectural mismatch | evidence (file:line) | note if partly/not pass
+
+Project guidelines: <"project rules applied: N sections from project/guidelines/…" | "Project guidelines: none — inherited from Shopware platform guidelines" | "not found: guidelines/<v>/<file> — MCP unavailable, disk fallback used" | "not found: guidelines/<v>/<file> (reported, continued)">
+shopware-cli Twig linters | pass/fail/not run | admin-twig,storefront-twig — N errors, N warnings (or install command)
+```
+
+Then a one-line verdict: fully compliant, or the count of ACs not passing/partly with the guideline category (Core vs Project vs architectural mismatch) behind each.
+
+Never mark an AC `pass` to be agreeable. `partly` always carries the one-sentence reason (e.g. "extension point correct, but DAL association not batched — Core performance guideline").

package/skills/sw-verify-feature-architecture/reference/guidelines-and-twig.md

@@ -0,0 +1,27 @@
+# Guideline sources and the Twig-linter guardrail
+
+Steps 2 and 4 of `sw-verify-feature-architecture`. Step 2 decides which Core and Project guidelines apply to this feature and where they come from; step 4 is the read-only `shopware-cli` Twig guardrail. Neither mutates code.
+
+### 2. Gather guideline sources
+
+**Core** — Shopware's own architectural conventions: extension points over core patches, DI/decoration over reflection, versioned/inherited/translatable DAL modelling rules, idempotent migrations, `SalesChannelContext` as the unit of correctness, headless-first (Store API before Storefront controller logic), rule builder/flow actions before hardcoded conditions. Confirm the specific pattern against `mcp__ShopwareDevKnowledgeBase` and the installed `vendor/shopware/*` version — never from memory, versions drift.
+
+**Guidelines**: first call `read_doc { path: "guidelines/<version>/<base-file>" }` with the detected Shopware major (6.6 or 6.7), then its surface file(s) for the area touched. Each is the effective file — Shopware's rules with this project's rules merged in; a `[project …]` section takes precedence. Apply every rule; cite it by the section's tag-line path, as `[rule: <path>]` — the tag line already ends with `#anchor`. If a call returns a not-found notice, say so in the report and continue — never substitute rules from memory. `<base-file>` is `architecture-guidelines.md`; surface files are `be-`/`fe-architecture-guidelines.md` of the touched areas.
+
+Fallback when the MCP is unavailable: read `docs/project-wiki/guidelines/` directly on disk (project rules only, no platform merge) and state in the report that platform rules were unavailable.
+
+**Project** — report which sections actually came from the project layer: `project rules applied: N sections from project/guidelines/…` when at least one `[project …]` tag appears in an effective file read above, or `Project guidelines: none — inherited from Shopware platform guidelines` when every section read is `[platform]`. This is a neutral fact, not a failure — do not treat "none" as a violation. Distinguish two not-found cases, both reported plainly and never replaced by memory: the whole MCP being unreachable (disk fallback used, above) versus one `read_doc` call for a named `guidelines/<v>/<file>` returning a not-found notice while the MCP itself answers other calls — report the latter as `not found: guidelines/<v>/<file> (reported, continued)` and keep going with whatever files did resolve.
+
+
+### 4. Guardrail: shopware-cli Twig linters
+
+`shopware-cli` bundles two tools with real, read-only checks relevant to Core-guideline compliance: `admin-twig` and `storefront-twig` (deprecated/incorrect Twig block usage — an extension-point correctness signal, since Shopware's Twig block/`sw_extends` conventions are how Storefront/Admin templates are meant to be extended).
+
+1. Read the shopware-cli row from the `sw-setup` table (brief, or invoke `sw-setup` standalone). Unticked → report this gate `not run`, naming `/sw-setup`; don't block the rest of this skill on it.
+2. Run `shopware-cli extension validate --full --only=admin-twig,storefront-twig custom/plugins/<PluginName>`.
+   - **Important**: `--only` has no effect without `--full` — passing `--only` alone silently resets to the default `sw-cli` structural checks and these two linters never run. Always pass both flags together.
+3. The same `validate` call (even without `--full`) also flags deprecated `services.xml`/`routes.xml` in favor of the YAML format as a `warning` — a Symfony/Core convention signal worth carrying into this gate too, since it's a structural check bundled by default.
+4. Every `error` is a fail for this gate; `warning` is reported but doesn't block unless a Core/Project guideline explicitly requires avoiding it.
+
+Note for context, not a gate to run here: Shopware's actual deprecated-pattern/upgrade-compatibility detector is `rector`, but it only executes via `shopware-cli extension fix` (mutates files, no dry-run) — that tool belongs to `sw-implement-feature` (fixing), not to this read-only verification skill. Do not attempt to run it here.
+

package/skills/sw-verify-feature-code-quality/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: sw-verify-feature-code-quality
+description: Verify the code-quality gate for a feature — identifies which tool suites actually apply (PHPStan, ESLint, Stylelint, sw-cli structural validation via shopware-cli, PHPUnit regression), executes them, and checks the touched files against written Core and Project guidelines' quality/style clauses (naming, duplication, dead code, unneeded complexity). Reports whole-plugin gate results plus any per-AC quality defect found in that AC's files. One of three parallel verifiers spawned by sw-verify-feature; can also be run standalone.
+when_to_use: Trigger phrases — "verify code quality for spec 0007", "run static analysis for this feature", "does this pass PHPStan/ESLint", "code quality gate for epic 1".
+argument-hint: [specs/NNNN-slug-spec.md]
+allowed-tools: Read Glob Grep Bash mcp__ShopwareDevKnowledgeBase__list_docs mcp__ShopwareDevKnowledgeBase__grep_docs mcp__ShopwareDevKnowledgeBase__read_doc mcp__ShopwareDevKnowledgeBase__kb_status
+---
+
+# sw-verify-feature-code-quality
+
+Independently verify the code-quality layer of a feature against its spec. This skill performs the verification itself using its own tools — it does not delegate execution to an agent. It answers two questions: do the automated tool gates pass, and does the touched code follow this project's written quality/style guidelines?
+
+This is distinct from `sw-verify-feature-architecture`, which reads the same guideline sources for their *architectural-decision* clauses (extension points, DAL modelling, DI/decoration). This skill reads them for their *quality/style* clauses (naming, duplication, dead code, unneeded complexity, comment discipline).
+
+## Read-only contract
+
+This skill observes and reports. It never changes the project: no file created, edited, or deleted, no auto-fix applied (`shopware-cli extension fix`/`format`, etc.), no git action.
+
+`shopware-cli` also bundles `php-cs-fixer`, `prettier`, and `rector` — but each of those has an empty `Check()` in shopware-cli's own source and only does real work through `extension format` or `extension fix` (file-mutating; `php-cs-fixer` has a `--dry-run` mode but fixing is still not this skill's job). Those three are `sw-implement-feature`'s tools for fixing code, not this skill's for validating it — do not run them here even in dry-run.
+
+## Inputs
+
+| Argument | Behaviour |
+| --- | --- |
+| Path to `specs/NNNN-slug-spec.md` | Verify code quality for this spec's implementation against the current codebase |
+| `; ` followed by a detected Shopware/PHP version + evidence (e.g. from `sw-verify-feature`'s brief) | Use it as verified — no re-detection needed |
+| Nothing | Ask the user for the spec path |
+
+## Procedure
+
+### 0. Shopware/PHP version
+
+**Version:** from `args` if stated with evidence, use it as verified; else detect via `vendor/shopware/core/composer.json` → `composer.lock` → `composer.json` ("unconfirmed"). Ambiguous or unknown → stop, never guess — blocking question to the caller, or ask the user if run standalone. Which PHPStan/rule level and toolchain shape applies can be version-dependent.
+
+### 1. Identify the plugin and touched areas
+
+From the spec, identify the plugin directory (e.g. `custom/plugins/<PluginName>`) and which areas it touches: PHP backend, Administration JS, Storefront JS/Twig/SCSS, CLI.
+
+### 2. Identify which tool suites actually apply
+
+Don't run everything blind — scope to what the touched areas need:
+
+- PHP touched → PHPStan, PHPUnit regression suite
+- Administration/Storefront JS touched → ESLint
+- Storefront SCSS/Admin LESS touched → Stylelint
+- Nothing outside PHP → skip ESLint/Stylelint and say so, don't silently omit the line
+
+(Twig linting — `admin-twig`/`storefront-twig` — is `sw-verify-feature-architecture`'s gate, not this skill's; don't duplicate it here.)
+
+
+### 3-4. Guideline sources and the tool gates
+
+Follow `reference/gates.md` in this skill's directory: gather the Core and Project
+guideline sources for the quality/style dimension, then execute the tool gates that
+step 2 found applicable. Read-only — report what a gate says, never fix it.
+
+### 5. Manual quality read
+
+For the files this feature actually touched (not the whole plugin), check against the quality/style clauses gathered in step 3 plus general good-practice defaults if no written guideline covers a case: no dead code left behind, no unneeded abstraction for a one-shot operation, no duplicated logic that should be one place, naming that matches project convention, no comments explaining *what* obvious code does. Note each defect against the specific AC whose files it appears in.
+
+### 6. Report
+
+```
+AC-n | pass/partly/not pass | quality defect found in this AC's files (or "no defects found") | evidence (file:line)
+
+PHPStan/ESLint/Stylelint/sw-cli (shopware-cli --full --only=phpstan,eslint,stylelint,sw-cli) | pass/fail/not run | N errors, N warnings (or install command)
+PHPUnit regression (full plugin suite) | pass/fail | N failing tests (list if any)
+Project guidelines: <"project rules applied: N sections from project/guidelines/…" | "Project guidelines: none — inherited from Shopware platform guidelines" | "not found: guidelines/<v>/<file> — MCP unavailable, disk fallback used" | "not found: guidelines/<v>/<file> (reported, continued)">
+```
+
+Then a one-line verdict: fully clean, or the count of gates failing/not-run plus the count of ACs with a quality defect.
+
+Never mark a gate `pass` to be agreeable, and never mark it `not run` as a quiet substitute for a real failure. `partly` on an AC line always carries the one-sentence reason for the defect found.

package/skills/sw-verify-feature-code-quality/reference/gates.md

@@ -0,0 +1,22 @@
+# Guideline sources and the tool gates
+
+Steps 3 and 4 of `sw-verify-feature-code-quality`, entered once the plugin, the touched areas and the applicable tool suites are known. Step 3 decides which written guidelines apply; step 4 runs the gates. Both are read-only — nothing here mutates code.
+
+### 3. Gather guideline sources (quality/style dimension)
+
+Guidelines: first call `read_doc { path: "guidelines/<version>/<base-file>" }` with the detected Shopware major (6.6 or 6.7), then its surface file(s) for the area touched. Each is the effective file — Shopware's rules with this project's rules merged in; a `[project …]` section takes precedence. Apply every rule; cite it by the section's tag-line path, as `[rule: <path>]` — the tag line already ends with `#anchor`. If a call returns a not-found notice, say so in the report and continue — never substitute rules from memory. `<base-file>` is `code-guidelines.md` plus `qa-guidelines.md`; surface files are `be-`/`admin-`/`storefront-code-guidelines.md` and `be-`/`fe-qa-guidelines.md` of the touched areas. Read them for quality/style clauses (naming conventions, duplication limits, dead-code policy, comment policy, complexity limits) and apply them in step 5.
+
+Fallback when the MCP is unavailable: read `docs/project-wiki/guidelines/` directly on disk (project rules only, no platform merge) and state in the report that platform rules were unavailable.
+
+Report which sections actually came from the project layer: `project rules applied: N sections from project/guidelines/…` when at least one `[project …]` tag appears in an effective file read above, or `Project guidelines: none — inherited from Shopware platform guidelines` when every section read is `[platform]`. Neutral fact, not a failure. Distinguish two not-found cases, both reported plainly and never replaced by memory: the whole MCP being unreachable (disk fallback used, above) versus one `read_doc` call for a named `guidelines/<v>/<file>` returning a not-found notice while the MCP itself answers other calls — report the latter as `not found: guidelines/<v>/<file> (reported, continued)` and keep going with whatever files did resolve.
+
+### 4. Execute the tool gates
+
+**PHPStan / ESLint / Stylelint / sw-cli structural** — bundled by Shopware's own toolchain, not run standalone:
+1. Read the shopware-cli row from the `sw-setup` table (brief, or invoke `sw-setup` standalone). Unticked → report that gate line `not run`, naming `/sw-setup` — do not block the rest of this skill on it.
+2. `shopware-cli extension validate --full --only=phpstan,eslint,stylelint,sw-cli custom/plugins/<PluginName>` — scoped to the four tools that actually have a real, check-only `Check()` in shopware-cli's toolchain and no real `Fix()`/`Format()` of their own (confirmed from source: `internal/verifier/{phpstan,eslint,stylelint,sw_cli}.go`), matching the areas identified in step 2. `sw-cli` here is the extension's structural/manifest validation (`extension.yml`, plugin metadata, packaging rules) — it has nowhere else to run since `sw-implement-feature` never invokes it (no `Fix()`) and no other verifier covers it.
+   - **Important**: `--only` has no effect without `--full` in `extension validate` — passing `--only` alone silently resets to the default `sw-cli`-only structural check and the others never run. Always pass both flags together.
+3. Every `error` is a fail for this gate; `warning` is reported but doesn't block unless the spec's tech decisions require avoiding it.
+
+**PHPUnit regression suite** — broader than `sw-verify-feature-ac-tests`' per-AC execution: run the plugin's *entire* PHPUnit suite (not just the tests mapped to this feature's ACs) to catch regressions the change may have caused elsewhere in the plugin. Report pass/fail with the failing test list if any.
+