acek-skills 1.2.0 → 1.3.0

package/README.md

@@ -149,7 +149,9 @@ metadata is touched: runs Discovery (project scan + choice-based clarifying ques
 text), proposes Decisions with trade-offs for data model / automation layer / integration pattern
 / security model / Permission Set strategy, then breaks approved work into tasks dispatched to the
 right skill (`sf-admin`, `sf-dev`, `sf-testing`, `sf-devops`, `sf-security-review`,
-`sf-data-migration`). Plans are saved to `instructions/architecture/` and are resumable across
+`sf-data-migration`) — always including a `sf-security-review` task when the plan touches a
+PII-bearing object/field, an integration, or a sharing/OWD change. Plans are saved to
+`instructions/architecture/` and are resumable across
 sessions without re-scanning the project or re-reading chat history. Complements — does not
 replace — `sf-ba` (PRDs) and `sf-ideation` (open-ended brainstorming), and can consume either as
 input.
@@ -177,7 +179,10 @@ data management (import/export/data loader) — anything declarative, no code in
 
 Writes PRDs, user stories, feature specs, and functional requirements — structured Markdown docs
 intended to hand off to an admin or developer. Triggers on "write a PRD", "document requirements",
-"write user stories", or when a business problem needs to become executable documentation.
+"write user stories", or when a business problem needs to become executable documentation. Its
+Admin Spec / Dev Spec templates are for work that will **not** go through `sf-architect`; for
+open-ended brainstorming on a specific existing component instead of net-new requirements, it
+hands off to `sf-ideation`.
 
 </details>
 
@@ -230,8 +235,9 @@ opportunities.
 
 CRUD/FLS checks, sharing model review, `with sharing` enforcement, SOQL injection, XSS in LWC,
 hardcoded credential detection, and a production sign-off checklist. Also covers Shield,
-encryption, audit trail, and a dedicated PII & Data Privacy section — field classification,
-sandbox data masking, and UU PDP-aware review practices.
+encryption, audit trail, a dedicated PII & Data Privacy section — field classification, sandbox
+data masking, and UU PDP-aware review practices — plus Guest User/Experience Cloud access review
+and Connected App/External Client App (OAuth) review checklists.
 
 </details>
 
@@ -239,8 +245,9 @@ sandbox data masking, and UU PDP-aware review practices.
 <summary><strong>sf-testing</strong> — Apex test strategy</summary>
 
 Test classes, `TestDataFactory` patterns, mocking HTTP callouts and platform events, test
-assertions, coverage reports, and debugging org-only test failures. Enforces the 85% coverage
-floor and `AuraHandledException` assertion conventions.
+assertions, coverage reports, debugging org-only test failures, and LWC Jest unit tests
+(`@salesforce/sfdx-lwc-jest`). Enforces the 85% Apex coverage floor, `AuraHandledException`
+assertion conventions, and a 3-scenario minimum (happy/empty/interaction) for every LWC component.
 
 </details>
 
@@ -310,7 +317,7 @@ responds, and doesn't touch any org, sandbox, or production data on its own.
 Yes — deselect any skill in the interactive wizard, or use `install <name>` for a single one.
 
 **Can I re-run install to update after a new version is published?**
-Yes, `npx` always resolves the latest version unless you pin one (`npx acek-skills@1.2.0 install`).
+Yes, `npx` always resolves the latest version unless you pin one (`npx acek-skills@1.3.0 install`).
 Re-running overwrites previously installed files for the skills/targets you select.
 
 **Why do only Claude Code skills auto-trigger?**

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "acek-skills",
-	"version": "1.2.0",
+	"version": "1.3.0",
 	"description": "Installable Claude Code skills for Salesforce development (admin, dev, BA, testing, devops, security review, data migration, ideation)",
 	"bin": {
 		"acek-skills": "bin/cli.js"

package/skills/sf-admin/SKILL.md

@@ -14,7 +14,10 @@ description: >
 
 ## Environment Context
 
-- API Version: **67.0** (Summer '26)
+- API Version: **not hardcoded** — new files inherit whatever `sourceApiVersion` is set in the
+  project's `sfdx-project.json` when scaffolded via SF CLI. When touching an **existing**
+  class/component/metadata item, check its `apiVersion`: below **62.0** → bump to **67.0** as part
+  of the change; 62.0+ → leave as-is unless the task needs 67.0+ behavior specifically.
 - Org Type: Enterprise (single org: sandbox + production)
 - Tooling: **SF CLI** for metadata retrieval; most admin tasks done declaratively in Setup UI
 - Any metadata changes intended for production must go through the DevOps deployment process

package/skills/sf-architect/SKILL.md

@@ -141,12 +141,19 @@ Nothing is built yet. This phase only produces decisions with rationale.
    **Touches** list (exact file(s)/component(s) it will create or modify), a dependency list, and
    status `P` (Pending). `Touches` is what Phase 4 uses to decide which tasks are safe to run in
    parallel — be specific and accurate here, not vague.
-3. **If any task's Owner Skill is `sf-devops` or `sf-data-migration`, resolve org aliases before
+3. **Always add a `sf-security-review` task** when the plan creates or modifies access to any
+   PII-bearing object/field (see `sf-security-review`'s PII & Data Privacy categories), introduces
+   a new integration/callout, or changes the sharing model — never skip it because the feature
+   "seems simple," the same standard already applied to Permission Set Strategy above. Depend it
+   on the relevant `sf-admin`/`sf-dev` tasks and put it before the `sf-devops` deploy task — its
+   sign-off is what fills the CR's "PII Impact" section. Skip only when Project Context confirms
+   none of those three surfaces are touched.
+4. **If any task's Owner Skill is `sf-devops` or `sf-data-migration`, resolve org aliases before
    finalizing** — see [Org Alias Resolution](#org-alias-resolution) below. Skip this step
    entirely if no task touches those two skills; don't ask about aliases a plan doesn't need.
-4. Present the plan summary to the user and ask for explicit approval — options: **Approve**,
+5. Present the plan summary to the user and ask for explicit approval — options: **Approve**,
    **Revise a section**, **Cancel**. Do not proceed on silence or an ambiguous reply.
-5. Only after explicit approval: write the plan file to
+6. Only after explicit approval: write the plan file to
    `instructions/architecture/YYYYMMDD-<feature-slug>-plan.md`.
 
 This is the hard gate. Nothing before this point touches the org or the repo's buildable code.
@@ -185,15 +192,22 @@ dispatched to parallel subagents; tasks that depend on each other still run in s
 1. **Compute the ready set.** A task is ready when every task in its `Depends On` list is `D`.
 2. **Split the ready set into parallel-safe groups.** Two ready tasks can run in the same batch
    only if their `Touches` values don't overlap (no shared file/component). If a task's `Touches`
-   is unclear or ambiguous, treat it as not parallel-safe — run it alone.
+   is unclear or ambiguous, treat it as not parallel-safe — run it alone. **This applies
+   regardless of Owner Skill** — two tasks both owned by `sf-dev` (e.g. two independent LWC
+   components, or two unrelated Apex classes) are just as eligible for the same parallel batch as
+   two tasks owned by different skills, as long as their `Touches` don't overlap. Parallel
+   eligibility is decided by `Touches`, never by which skill owns the task.
 3. **Dispatch the batch:**
    - **Batch of 1** → run directly in the main thread, exactly as before (no subagent overhead
      for solo work).
    - **Batch of 2+** → dispatch each task to a separate subagent via the Task tool, in the same
-     turn. Each subagent prompt must state explicitly: the task description, the exact file(s) in
-     `Touches`, and "follow `sf-[owner skill]`'s conventions exactly as if that skill were invoked
-     directly" — never duplicate that skill's rules into the prompt, just name it and let it
-     trigger in the subagent's own context.
+     turn. This holds even when two or more tasks in the batch share the same Owner Skill (e.g.
+     two `sf-dev` tasks) — each still gets its own subagent, invoked independently; never route
+     two tasks through one subagent just because they'd trigger the same skill. Each subagent
+     prompt must state explicitly: the task description, the exact file(s) in `Touches`, and
+     "follow `sf-[owner skill]`'s conventions exactly as if that skill were invoked directly" —
+     never duplicate that skill's rules into the prompt, just name it and let it trigger in the
+     subagent's own context.
    - **Assign each subagent in a batch a random name from the pool below, unique within that
      batch** — used only as a tracking label in the orchestrator's own narration and Execution Log
      ("Dispatched to Sasha"), never written into code, commits, or file content.
@@ -313,9 +327,11 @@ Permission Set Group `[PSG Name]`
 **Status codes:** `P` Pending · `IP` In Progress · `B` Blocked · `D` Done
 
 **Touches** is what makes parallel dispatch safe: TASK-02, TASK-03, and TASK-04 all depend only on
-TASK-01 and touch different things — they're a valid parallel batch. TASK-05 depends on TASK-03
-and must wait for it. TASK-06 depends on both TASK-04 and TASK-05, so it waits for the slower of
-the two.
+TASK-01 and touch different things — they're a valid parallel batch, dispatched as three separate
+subagents. Note TASK-03 and TASK-04 share the same Owner Skill (`sf-dev`) but still run as two
+independent subagents in that batch — parallel eligibility is decided by `Touches`, not by which
+skill owns the task. TASK-05 depends on TASK-03 and must wait for it. TASK-06 depends on both
+TASK-04 and TASK-05, so it waits for the slower of the two.
 
 ---
 
@@ -398,8 +414,14 @@ best if users need to review before submitting (D) Other — describe your own a
 - ✕ Skipping the Permission Set Strategy decision because the feature "seems simple" — access
   control is part of every feature that touches an object, field, Apex class, or LWC
 - ✕ Assuming a new Permission Set is needed without first scanning for an existing one that fits
+- ✕ Omitting a `sf-security-review` task from Task Breakdown when the plan touches a PII-bearing
+  field/object, adds a new integration/callout, or changes the sharing model
 - ✕ Dispatching two tasks in parallel when their `Touches` overlap, or when either one's
   `Touches` is too vague to be sure it doesn't
+- ✕ Merging two or more same-Owner-Skill tasks into a single subagent because they'd trigger the
+  same skill — each task still gets its own subagent when their `Touches` don't overlap
+- ✕ Treating parallel-safe dispatch as only available across *different* Owner Skills — two tasks
+  under the same skill (e.g. two `sf-dev` tasks) are equally eligible when `Touches` don't overlap
 - ✕ Letting a subagent write directly to the plan file — only the orchestrator writes status/log
   updates, and only after the batch reports back
 - ✕ Reusing the same agent name for two subagents within the same batch

package/skills/sf-ba/SKILL.md

@@ -29,6 +29,14 @@ running `sf-architect` first, or right after — it consumes the PRD as input an
 technical execution plan. `sf-ba` decides WHAT to build; `sf-architect` decides HOW and in what
 order. Don't try to make the PRD carry both.
 
+**Admin Spec and Dev Spec are for work that will NOT go through `sf-architect`** — e.g. handing
+instructions to a human admin/dev directly, or documenting a declarative/code change after the
+fact for the record. If the work is going to be executed via an `sf-architect` plan, skip writing
+these specs: `sf-architect`'s Task Breakdown (with each task's Owner Skill and exact `Touches`)
+already carries that execution detail, and a separately-written spec would just be a second copy
+of the same decisions to keep in sync by hand. Write the PRD, hand it to `sf-architect`, and let
+the plan carry the rest.
+
 ---
 
 ## Document Types

package/skills/sf-data-migration/SKILL.md

@@ -14,7 +14,10 @@ description: >
 
 ## Environment Context
 
-- API Version: **67.0** (Summer '26)
+- API Version: **not hardcoded** — new files inherit whatever `sourceApiVersion` is set in the
+  project's `sfdx-project.json` when scaffolded via SF CLI. When touching an **existing**
+  class/component/metadata item, check its `apiVersion`: below **62.0** → bump to **67.0** as part
+  of the change; 62.0+ → leave as-is unless the task needs 67.0+ behavior specifically.
 - Tooling: **SF CLI** (`sf data` commands) for dev/test volumes; Data Loader for production volumes
 - Always migrate to **sandbox first**, verify, then production
 - Single org: sandbox → production

package/skills/sf-dev/SKILL.md

@@ -13,7 +13,12 @@ description: >
 
 ## Environment Context
 
-- API Version: **67.0** (Summer '26)
+- API Version: **not hardcoded** — new files inherit whatever `sourceApiVersion` is set in the
+  project's `sfdx-project.json` when scaffolded via SF CLI (see [File
+  Creation](#-file-creation--always-via-sf-cli-never-manual) below — this is one more reason to
+  always generate, never hand-create). When touching an **existing** class/component, check its
+  `apiVersion`: below **62.0** → bump to **67.0** as part of the change; 62.0+ → leave as-is unless
+  the task needs 67.0+ behavior specifically.
 - Tooling: **SF CLI** (`sf` commands)
 - Apex LSP: **offline** — never use compile-time SObject type references that require org metadata
 - Version control: **GitHub** (branching: `main → staging → develop → feature/*`)
@@ -174,10 +179,11 @@ public static Result myMethod(String param) {
 
 | Type         | Convention                 | Example                               |
 | ------------ | -------------------------- | ------------------------------------- |
-| Apex Class   | PascalCase                 | `AccountHelper`, `OpportunityTrigger` |
-| Test Class   | PascalCase + `Test` suffix | `AccountHelperTest`                   |
-| Custom Field | PascalCase\_\_c            | `ProjectStatus__c`                    |
-| Variable     | camelCase                  | `accountList`, `oppMap`               |
+| Apex Class   | PascalCase                       | `AccountHelper`, `OpportunityService` |
+| Test Class   | PascalCase + `Test` suffix       | `AccountHelperTest`                   |
+| Apex Trigger | `<Object>Trigger`, one per object | `AccountTrigger`, `OpportunityTrigger` |
+| Custom Field | PascalCase\_\_c                  | `ProjectStatus__c`                    |
+| Variable     | camelCase                        | `accountList`, `oppMap`               |
 
 ### ApexDoc (required on all public methods)
 
@@ -194,34 +200,17 @@ public static List<Result__c> processRecord(Id recordId) { ... }
 
 ### Test Class Pattern
 
-```apex
-@isTest
-private class AccountHelperTest {
-    @TestSetup
-    static void makeData() {
-        // create test records once for all test methods
-    }
-
-    @isTest
-    static void testPositivePath() {
-        Test.startTest();
-        // call method
-        Test.stopTest();
-        // assert
-    }
+Full test class structure, `TestDataFactory` usage, callout/platform-event mocking, and assertion
+conventions are owned by `sf-testing` — follow that skill's pattern exactly rather than
+improvising a competing one here. Two things worth remembering while writing the code being
+tested:
 
-    @isTest
-    static void testNegativePath_insufficientPermission() {
-        // test exception path
-        try {
-            AccountHelper.myMethod(null);
-            Assert.fail('Expected exception not thrown');
-        } catch (AuraHandledException e) {
-            Assert.areEqual('Script-thrown exception', e.getMessage(), 'AuraHandledException message is masked in test context by design');
-        }
-    }
-}
-```
+- `AuraHandledException.getMessage()` always returns `'Script-thrown exception'` in test context
+  (Salesforce by design) — the test asserting your exception path is expected to check this exact
+  string, not your real error message
+- Structure the method so `Test.startTest()` / `Test.stopTest()` around the call actually resets
+  governor limits and forces async paths (Queueable, `@future`, Platform Events) to run — don't
+  write logic that fights that boundary
 
 ---
 
@@ -442,4 +431,6 @@ sf apex run --target-org <alias> --file scripts/apex/myScript.apex
 - [ ] No `WITH SECURITY_ENFORCED` in SOQL — removed in API 67.0
 - [ ] All `@AuraEnabled` methods wrapped in try-catch → `AuraHandledException`
 - [ ] LWC uses SLDS 2 hooks (`var(--slds-g-*, fallback)`) — no hardcoded hex/px, no `.slds-*` overrides
+- [ ] New/modified LWC has a Jest test file under `__tests__/` — see `sf-testing`'s LWC Jest
+      Testing section for the pattern; don't improvise a competing one
 - [ ] Version badge present _if the project has adopted that convention_ (not required by default)

package/skills/sf-devops/SKILL.md

@@ -14,7 +14,10 @@ description: >
 
 ## Environment Context
 
-- API Version: **67.0** (Summer '26)
+- API Version: **not hardcoded** — new files inherit whatever `sourceApiVersion` is set in the
+  project's `sfdx-project.json` when scaffolded via SF CLI. When touching an **existing**
+  class/component/metadata item, check its `apiVersion`: below **62.0** → bump to **67.0** as part
+  of the change; 62.0+ → leave as-is unless the task needs 67.0+ behavior specifically.
 - Branching: `main → staging → develop → feature/*`
 - Production org alias: **`{{PROD_ORG_ALIAS}}`**
 - Sandbox/dev org alias: **`{{DEV_ORG_ALIAS}}`**
@@ -64,6 +67,8 @@ Never skip steps. Never deploy to `{{PROD_ORG_ALIAS}}` without a CR.
       an LWC missing its `js-meta.xml` will fail to deploy or stay invisible in the org
 - [ ] No `@wire` adapter inside a loop
 - [ ] All public `@api` properties have JSDoc
+- [ ] Jest test file exists under `__tests__/` covering at least happy path, empty state, and one
+      interaction/error path (see `sf-testing`'s LWC Jest Testing section) — no LWC ships untested
 
 > **Out of scope for this checklist:** CSS/styling conventions and design system compliance.
 > That belongs to whichever skill built the component — `sf-dev` (standard SLDS 2 styling) or

package/skills/sf-ideation/SKILL.md

@@ -161,6 +161,13 @@ using the project's actual stack, referencing the anchor by name.
 - **Be opinionated** — don't just list options, recommend the best one and explain why.
 - **Think Salesforce seasons** — flag if an idea aligns with an upcoming Salesforce release
   feature that could reduce build effort.
+- **Hand off, don't build.** This skill's job stops at generating and prioritizing ideas — it
+  never writes code, metadata, or a plan file itself, and its output is intentionally **not
+  persisted** to a file. For a **Big Bet** or any idea that needs a real architecture decision
+  (data model, Flow vs Apex, integration pattern, security model), hand off to `sf-architect` — its
+  plan file is where the idea becomes durable. For an idea that should become a formally scoped
+  feature with requirements and acceptance criteria first, hand off to `sf-ba` to write a PRD.
+  Don't try to make this skill's output do either job.
 
 ---
 
@@ -175,3 +182,4 @@ using the project's actual stack, referencing the anchor by name.
 | "apa next step dari PRD [name]?"                                 | Anchor = that PRD (confirm it's closed/approved). Run Extension Questions                                              |
 | "prioritas enhancement mana yang paling worth it?"               | Requires a prior anchored ideation output in this conversation to rank — if none exists, ask which anchor to run first |
 | "ada yang bisa diimprove dari sisi performance?" (no name given) | No anchor — scan project, ask which component to focus the Performance lens on                                         |
+| "let's build idea #[N]" / "jalankan ide nomor [N]"               | Hand off — don't execute here. Route to `sf-architect` if it needs a technical decision, or `sf-ba` if it needs a PRD first |

package/skills/sf-security-review/SKILL.md

@@ -14,7 +14,12 @@ description: >
 
 ## Environment Context
 
-- API Version: **67.0** (Summer '26)
+- API Version: **not hardcoded** — new files inherit whatever `sourceApiVersion` is set in the
+  project's `sfdx-project.json` when scaffolded via SF CLI. When reviewing an **existing**
+  class/component, check its `apiVersion`: below **62.0** → recommend bumping to **67.0** as part
+  of the change; 62.0+ → confirm whether the [API 67.0+ Default Security
+  Model](#-api-670-default-security-model-summer-26) applies before deciding whether a missing
+  manual check is a real gap.
 - Apex LSP: **offline** — use `Schema.getGlobalDescribe()` pattern (not compile-time SObject reference)
 - All security decisions must be documented in the relevant CR before production deploy
 
@@ -370,6 +375,56 @@ When PII-bearing objects/fields are part of the change being reviewed, add to th
 
 ---
 
+## Guest User & Experience Cloud Access
+
+Guest User (unauthenticated Experience Cloud / site visitor) access is one of the highest-risk
+misconfigurations in Salesforce — a single overly-broad Guest User sharing rule or OWD setting can
+expose record data to anyone on the internet, no login required.
+
+### Review Checklist
+
+- [ ] Guest User profile has **no** object permissions beyond what the public-facing page
+      genuinely needs to render — verify against the actual Experience Cloud page, not assumption
+- [ ] No Guest User sharing rule or "Public Read/Write" OWD grants access to a PII-bearing object
+      (see [PII & Data Privacy](#pii--data-privacy)) unless explicitly required and documented
+- [ ] "Secure Guest User Record Access" org setting is enabled (Setup → Sharing Settings) — this
+      caps Guest User access to explicit sharing rules rather than the older default-access model
+- [ ] Guest User cannot create/edit/delete records unless the page's actual function requires it
+      (e.g. a public intake form) — CRUD checked per object, not granted broadly
+- [ ] No Apex class exposed to Guest User (`without sharing` + `global`/`@AuraEnabled` reachable
+      from a public page) returns fields beyond what the page displays — treat any Guest-reachable
+      Apex method as a public API surface, not an internal helper
+- [ ] Community/site URLs referencing record IDs are validated server-side, not trusted as proof
+      of access — a guessable/enumerable ID in a public URL is not an access control
+
+Treat any change that touches a Guest User profile, an Experience Cloud page, or a
+Guest-reachable Apex method as requiring this checklist, in addition to the standard Apex/LWC
+review above.
+
+---
+
+## Connected App & External Client App Review
+
+Relevant whenever a change introduces or modifies a Connected App, External Client App, or any
+OAuth-based integration.
+
+### Review Checklist
+
+- [ ] OAuth scopes requested are the **minimum** needed for the integration's actual purpose —
+      flag broad scopes (`full`, `api` when something narrower would do) without a documented
+      reason
+- [ ] Refresh token policy is explicit (expire on inactivity / never expire) — "never expire" needs
+      a documented justification, not a default
+- [ ] IP restriction is "Enforce IP restrictions" + Trusted IP Ranges unless the integration
+      genuinely runs from unpredictable IPs
+- [ ] Callback URL(s) are exact, not wildcarded, unless the integration pattern requires it
+- [ ] The integration/running user for the app has the minimum Permission Set needed — never
+      "System Administrator" as a convenience default
+- [ ] Client secret / certificate lives in a secrets manager or Named Credential — never committed
+      to source control or hardcoded in an integration script
+
+---
+
 ## Security Review Checklist
 
 ### Apex

package/skills/sf-testing/SKILL.md

@@ -3,11 +3,12 @@ name: sf-testing
 description: >
   Use this skill for ANY Salesforce test-related task: writing Apex test classes, building
   TestDataFactory, mocking HTTP callouts, mocking platform events, writing test assertions,
-  generating test coverage reports, debugging test failures, and designing test strategies.
-  Trigger when the user asks to "write a test class", "fix test coverage", "mock a callout",
-  "write a TestDataFactory", "test fails in org but passes locally", "assert this method",
-  or anything about Apex unit testing, test data, or code coverage. Also use when coverage
-  drops below 85% or when AuraHandledException assertions are involved.
+  generating test coverage reports, debugging test failures, designing test strategies, and
+  writing LWC Jest unit tests. Trigger when the user asks to "write a test class", "fix test
+  coverage", "mock a callout", "write a TestDataFactory", "test fails in org but passes locally",
+  "assert this method", "write a jest test", "test this component", or anything about Apex unit
+  testing, LWC unit testing, test data, or code coverage. Also use when coverage drops below 85%
+  or when AuraHandledException assertions are involved.
 ---
 
 # Salesforce Testing Skill
@@ -15,7 +16,10 @@ description: >
 ## Environment Context
 
 - Minimum coverage: **85%** (aim for 90%+)
-- API Version: **67.0** (Summer '26)
+- API Version: **not hardcoded** — new files inherit whatever `sourceApiVersion` is set in the
+  project's `sfdx-project.json` when scaffolded via SF CLI. When touching an **existing** test
+  class, check its `apiVersion`: below **62.0** → bump to **67.0** as part of the change; 62.0+ →
+  leave as-is unless the task needs 67.0+ behavior specifically.
 - Assertions: prefer the **`Assert` class** (`Assert.areEqual`, `Assert.isTrue`, etc. — API 56.0+)
   over legacy `System.assertEquals`/`System.assert` in new tests
 - `AuraHandledException.getMessage()` in test context **always** returns `'Script-thrown exception'` — this is Salesforce by design, not a bug
@@ -372,6 +376,112 @@ sf apex run test \
 
 ---
 
+## LWC Jest Testing
+
+Every new or modified LWC component needs a Jest test file — same discipline as Apex coverage,
+just not gated by a governor limit. This is separate from `sf-devops`'s LWC review checklist
+(structural: naming, wire usage, JSDoc) and from `shaiden`'s design critique (visual/SLDS
+compliance) — this section owns whether the component's *behavior* is actually tested.
+
+### File Location
+
+```
+force-app/main/default/lwc/myComponent/
+├── myComponent.html
+├── myComponent.js
+├── myComponent.css
+├── myComponent.js-meta.xml
+└── __tests__/
+    └── myComponent.test.js
+```
+
+Uses `@salesforce/sfdx-lwc-jest` — run via `npm run test:unit` (or the project's configured Jest
+script), not SF CLI.
+
+### Test Structure — Standard Pattern
+
+```javascript
+import { createElement } from 'lwc';
+import MyComponent from 'c/myComponent';
+import getRelatedItems from '@salesforce/apex/MyController.getRelatedItems';
+
+// Mock the wired Apex method — never let a Jest test hit a real Apex method
+jest.mock(
+    '@salesforce/apex/MyController.getRelatedItems',
+    () => ({ default: jest.fn() }),
+    { virtual: true }
+);
+
+describe('c-my-component', () => {
+    afterEach(() => {
+        while (document.body.firstChild) {
+            document.body.removeChild(document.body.firstChild);
+        }
+        jest.clearAllMocks();
+    });
+
+    // ─── Happy Path ────────────────────────────────────────────────────────
+    it('renders items after the wire resolves', async () => {
+        const element = createElement('c-my-component', { is: MyComponent });
+        document.body.appendChild(element);
+
+        getRelatedItems.emit([{ Id: '001', Name: 'Test Item' }]);
+        await Promise.resolve();
+
+        const items = element.shadowRoot.querySelectorAll('.my-component__item');
+        expect(items.length).toBe(1);
+    });
+
+    // ─── Empty State ───────────────────────────────────────────────────────
+    it('shows the empty state when there is no data', async () => {
+        const element = createElement('c-my-component', { is: MyComponent });
+        document.body.appendChild(element);
+
+        getRelatedItems.emit([]);
+        await Promise.resolve();
+
+        expect(element.shadowRoot.querySelector('.my-component__empty')).not.toBeNull();
+    });
+
+    // ─── Interaction / Error Path ──────────────────────────────────────────
+    it('fires the itemselected event on click', () => {
+        const element = createElement('c-my-component', { is: MyComponent });
+        document.body.appendChild(element);
+
+        const handler = jest.fn();
+        element.addEventListener('itemselected', handler);
+        element.shadowRoot.querySelector('button')?.click();
+
+        expect(handler).toHaveBeenCalled();
+    });
+});
+```
+
+### Rules
+
+- **Minimum 3 scenarios** per component — same bar as Apex: happy/rendered path, empty state, one
+  interaction or error path
+- Mock every `@wire`/imperative Apex import — a Jest test that reaches a real Apex method is broken
+- Query only through `element.shadowRoot` — never reach into the component's internals directly
+- Assert on rendered output (DOM nodes, text, fired events), not on private component state
+- Run `npm run test:unit` before every PR — same gate as Apex coverage, checked in `sf-devops`'s
+  review
+
+### Run Commands
+
+```bash
+# Run all LWC Jest tests
+npm run test:unit
+
+# Run a single component's tests
+npx sfdx-lwc-jest -- myComponent
+
+# Watch mode during development
+npx sfdx-lwc-jest --watch
+```
+
+---
+
 ## Common Test Failures & Fixes
 
 | Error                                       | Cause                                                              | Fix                                            |