@fluentcommerce/ai-skills 0.1.0

package/content/dev/skills/fluent-feature-plan/PLAN_TEMPLATE.md

@@ -0,0 +1,695 @@
+# Feature Plan Template
+
+> **Source of truth** for all implementation plans generated by planning-gated skills.
+> Referenced from individual skill Planning Gate sections.
+> Enhance this file to improve all future plans across all skills.
+
+---
+
+## Universal Source Classification
+
+Every table row in every section of a plan carries a **Source** column. This makes plans self-contained — a reviewer can scan any section and immediately see what's new (risky, needs review), what's reused (lower risk, proven pattern), and what's unchanged (context only).
+
+| Label | Meaning | Required Detail |
+|-------|---------|----------------|
+| **NEW** | Doesn't exist yet, must be created | Full pseudo logic / value shape / trigger spec |
+| **EXISTING** | Already deployed, no modification needed | State current value, confirm no change |
+| **MODIFIED** | Already exists but needs changes | Show before → after diff |
+| **REUSED** | Pattern exists in codebase, copy the approach | Reference source file/rule |
+| **OOTB** | Platform rule, use with configuration only | State which props/values to configure |
+
+---
+
+## Plan File Conventions
+
+**Account-scoped path:** `accounts/<PROFILE>/plans/<YYYY-MM-DD>-<skill-short-name>-<brief-slug>.md`
+
+**Repo-scoped path:** `.fluent-ai-skills/plans/<YYYY-MM-DD>-<skill-short-name>-<brief-slug>.md`
+
+Use account-scoped when targeting a Fluent environment. Use repo-scoped for package-internal work.
+
+**Naming rules:**
+- `<PROFILE>` — active Fluent CLI profile (e.g., `HMDEV`, `SAGIRISH`)
+- `<YYYY-MM-DD>` — creation date
+- `<skill-short-name>` — generating skill without `fluent-` prefix (e.g., `feature-plan`, `rule-scaffold`, `workflow-builder`)
+- `<brief-slug>` — 2-4 word kebab-case description (e.g., `curbside-pickup`, `order-hd-returns`)
+
+**Status lifecycle:** `PENDING` → `APPROVED` / `REJECTED` → implementation → session summary references plan file.
+
+---
+
+## Template
+
+Every plan file MUST follow this structure. Omit sections marked _optional_ when they don't apply. Sections marked **required** must always be present.
+
+````markdown
+# Plan: <Feature Title>
+
+| Field | Value |
+|-------|-------|
+| Status | `PENDING` |
+| Created | <YYYY-MM-DD> |
+| Skill | `/fluent-<skill-name>` |
+| Profile | <PROFILE> |
+| Retailer(s) | <RETAILER_REF> (ID: <N>) |
+| Module(s) | <module names if applicable> |
+| Approved by | --- |
+| Revision | 1 |
+
+## Table of Contents
+
+1. [Business Context](#1-business-context)
+2. [Scope](#2-scope)
+3. [Architecture & Diagrams](#3-architecture--diagrams)
+4. [Workflows](#4-workflows)
+5. [Statuses](#5-statuses)
+6. [Rulesets — Change Summary](#6-rulesets--change-summary)
+   - 6.1 [Complete Workflow Inventory](#61-complete-workflow-inventory) (full rules + props)
+7. [Rules Inventory](#7-rules-inventory)
+8. [Detailed Design (New Rules)](#8-detailed-design-new-rules)
+9. [Settings](#9-settings)
+10. [Webhooks](#10-webhooks)
+11. [Scheduled Events](#11-scheduled-events)
+12. [GraphQL Operations](#12-graphql-operations)
+13. [Cross-Entity Impact](#13-cross-entity-impact)
+14. [Files](#14-files)
+15. [Risks & Mitigations](#15-risks--mitigations)
+16. [Test Plan](#16-test-plan)
+17. [Deployment Sequence](#17-deployment-sequence)
+18. [Rollback Plan](#18-rollback-plan)
+
+---
+
+## 1. Business Context **[required]**
+
+> **Business objective:** <What business problem does this solve?>
+> **Trigger:** <What triggered this — user story, bug, go-live requirement?>
+> **Success criteria:** <How do we know this is done? Measurable outcome.>
+
+## 2. Scope **[required]**
+
+<One paragraph: what this plan achieves technically. Reference specific workflow names, entity types, and module names.>
+
+**In scope:**
+- <bulleted list>
+
+**Out of scope:**
+- <bulleted list>
+
+## 3. Architecture & Diagrams **[required — at least one diagram]**
+
+### 3.1 State Machine
+
+> Mermaid `stateDiagram-v2` for workflow creation or modification.
+> Show ALL statuses. Annotate: `:::added`, `:::removed`, `:::modified`.
+
+```mermaid
+stateDiagram-v2
+    [*] --> CREATED
+    CREATED --> BOOKED : ConfirmOrder
+    BOOKED --> AWAITING_PICKUP : CurbsideRequested:::added
+    AWAITING_PICKUP --> COMPLETE : ConfirmPickup:::added
+    AWAITING_PICKUP --> CANCELLED : CurbsideTimeout:::added
+    BOOKED --> FULFILLED : FulfilmentComplete
+```
+
+### 3.2 Cross-Entity Event Flow
+
+> Mermaid `sequenceDiagram` for cross-entity events, webhooks, or multi-step processing.
+
+```mermaid
+sequenceDiagram
+    participant WF as Workflow Engine
+    participant R1 as CreateCurbsidePickup [NEW]
+    participant R2 as ValidatePickupWindow [NEW]
+    participant GQL as GraphQL API
+    participant EXT as External Webhook
+
+    WF->>R2: run(context) [ORDER]
+    R2->>GQL: SettingUtils.getSettingByRef(curbside.pickup.config)
+    GQL-->>R2: {maxPickupHours: 48}
+    R2->>R2: Validate window
+    WF->>R1: run(context) [ORDER]
+    R1->>GQL: query order items
+    GQL-->>R1: OrderItem[]
+    R1->>GQL: createFulfilment(type=CURBSIDE)
+    GQL-->>R1: Fulfilment created
+    WF->>EXT: POST /curbside/notify (via SendWebhook OOTB)
+```
+
+### 3.3 Data Flow _(optional)_
+
+> Mermaid `flowchart` for complex processing, decision trees, or event propagation chains.
+
+### 3.4 Before → After Diff _(optional)_
+
+> For modifications to existing workflows. Use `workflow.diff` output or describe changes.
+
+### 3.5 Entity Relationships _(optional)_
+
+> For module scaffolding or retailer config. Show entity types and their edges.
+
+### 3.6 Workflow Processing Flow **[required when modifying an existing workflow]**
+
+> Mermaid `flowchart TD` showing the complete ruleset→status processing chain for each modified workflow.
+> Highlights NEW and MODIFIED rulesets with green styling. Shows how new rulesets fit into the existing flow.
+> This complements the state machine (§3.1) which shows statuses only — this shows the rulesets that drive transitions.
+
+```mermaid
+flowchart TD
+    subgraph "ORDER (order lifecycle)"
+        O1[CREATED] -->|CREATE| O2[ON_VALIDATION]
+        O2 -->|ValidateOrder| O2
+        O2 -->|"ConfirmValidation + ProcessOrder"| O3[IN_PROGRESS]
+        O3 -->|NotifyFulfilmentShipped| O4[SHIPPED]
+        O4 -->|"NotifyFulfilmentDelivered + TransitionToCompleted"| O5[COMPLETED]
+    end
+    subgraph "FULFILMENT_CHOICE (FC routing)"
+        FC1[FC CREATED] -->|RouteFulfilmentChoice| FC2{Route by type}
+        FC2 -->|HD| FC3[ProcessHDFC]
+        FC2 -->|CC| FC4[ProcessCCFC]
+        FC2 -->|CURBSIDE| FC5[ProcessCurbsideFC]:::added
+    end
+    subgraph "FULFILMENT (lifecycle by subtype)"
+        F1[FUL CREATED] -->|AssignFulfilment| F2[READY]
+        F2 -->|ConfirmAllocation| F3[RECEIVED]
+        F3 -->|CreateInvoice| F4[INVOICED]
+        F4 -->|ConfirmPick| F5[PICKPACK]
+        F5 -->|"ReadyForPickup (CURBSIDE)"| F6[READY_FOR_PICKUP]:::added
+        F6 -->|"ConfirmCollection (CURBSIDE)"| F7[COLLECTED]:::added
+    end
+
+    classDef added fill:#90EE90,stroke:#333
+```
+
+> **Format guidance:**
+> - One `subgraph` per entity type in the workflow
+> - Node labels show status names; edge labels show ruleset/event names
+> - Use `:::added` class for NEW rulesets/statuses, bold edge labels for MODIFIED
+> - Keep it high-level — show the routing and status flow, not individual rules within rulesets
+> - This diagram pairs with §6.1 Complete Workflow Inventory which shows the detail per ruleset
+
+## 4. Workflows **[required]**
+
+| Workflow | Source | Current Ver | Action | Details |
+|----------|--------|-------------|--------|---------|
+| ORDER::HD | MODIFIED | v12 | Modify | Add CurbsidePickupRequested ruleset, add 2 statuses |
+| FULFILMENT::CURBSIDE | NEW | — | Create | New workflow for curbside fulfilments |
+| FULFILMENT::HD | EXISTING | v8 | — | No change — listed for context |
+
+## 5. Statuses **[required when touching workflows]**
+
+| Status | Source | Entity Type | Workflow | Added By |
+|--------|--------|-------------|----------|----------|
+| CREATED | EXISTING | ORDER | ORDER::HD | Already in workflow |
+| BOOKED | EXISTING | ORDER | ORDER::HD | Already in workflow |
+| AWAITING_PICKUP | NEW | ORDER | ORDER::HD | SetState in CurbsidePickupRequested ruleset |
+| PICKED_UP | NEW | ORDER | ORDER::HD | SetState in ConfirmCurbsidePickup ruleset |
+| READY_FOR_PICKUP | NEW | FULFILMENT | FULFILMENT::CURBSIDE | SetState in PrepareCurbside ruleset |
+| COLLECTED | NEW | FULFILMENT | FULFILMENT::CURBSIDE | SetState in ConfirmCollection ruleset |
+
+## 6. Rulesets — Change Summary **[required when touching workflows]**
+
+> Quick-glance table of what rulesets are being added, modified, or referenced. Full detail (every rule, every prop) lives in §6.1.
+
+| Ruleset | Source | Workflow | From Status | To Status | Change Summary |
+|---------|--------|----------|-------------|-----------|----------------|
+| CurbsidePickupRequested | NEW | ORDER::HD | BOOKED | AWAITING_PICKUP | 3 rules: ValidatePickupWindow (NEW), CreateCurbsidePickupRule (NEW), SendEvent (OOTB) |
+| ConfirmCurbsidePickup | NEW | ORDER::HD | AWAITING_PICKUP | PICKED_UP | 2 rules: UpdateFulfilmentStatus (EXISTING), SetOrderStatus (OOTB) |
+| BookOrder | EXISTING | ORDER::HD | CREATED | BOOKED | No change — listed for context |
+
+### 6.1 Complete Workflow Inventory **[required when modifying an existing workflow]**
+
+> The **single source of truth** for the entire workflow. Lists ALL rulesets — not just new/modified — with every rule and every prop value.
+> This replaces the need to read the raw workflow JSON. Reviewers can see exactly where new rulesets fit, what's already there, and what each rule does.
+
+**Format:** One block per ruleset, grouped by entity type. Each block shows:
+- **Heading:** `# | RulesetName | Source marker` — bold for NEW/MODIFIED
+- **Metadata:** Entity type, subtype (if filtered), trigger status, event type
+- **Description:** What the ruleset does
+- **Rules table:** Every rule in execution order with full prop values and source annotations
+- **User actions:** If the ruleset exposes UI buttons
+
+**Source markers:** `EXISTING` = no change, `MODIFIED` = changed by this plan (show what changed), `NEW` = added by this plan
+
+---
+
+#### ORDER Rulesets (N existing, N new, N modified)
+
+##### 1. CREATE | EXISTING
+**Entity:** ORDER | **Trigger:** CREATED | **EventType:** NORMAL
+> Order created. Create missing products, send webhook, branch on fraud.
+
+| # | Rule | Props | Source |
+|---|------|-------|--------|
+| 1 | CreateMissingVariantProducts | — | EXISTING |
+| 2 | SendWebhookWithDynamicAttributes | `setting: webhook.order.created` | EXISTING |
+| 3 | SendEventOnVerifyingAttributeValue | `attributeName: fraudCheckRequired, onMatchEventName: InitFraudCheck, noMatchEventName: SkipFraudCheck` | EXISTING |
+
+---
+
+##### 2. BookOrder | EXISTING
+**Entity:** ORDER | **Trigger:** BOOKED | **EventType:** NORMAL
+> Standard booking, no change.
+
+| # | Rule | Props | Source |
+|---|------|-------|--------|
+| 1 | ... | ... | EXISTING |
+
+---
+
+##### 3. **CurbsidePickupRequested** | **NEW**
+**Entity:** ORDER | **Trigger:** BOOKED | **EventType:** NORMAL
+> Validates curbside request (time window, vehicle desc) and creates CURBSIDE fulfilment.
+
+| # | Rule | Props | Source |
+|---|------|-------|--------|
+| 1 | **ValidatePickupWindow** | `configSettingName: curbside.pickup.config, pickupTimePath: event.requestedPickupTime, vehicleDescPath: event.vehicleDescription` | **NEW** |
+| 2 | **CreateCurbsidePickupRule** | `fulfilmentType: CURBSIDE, pickupLocationPath: event.pickupLocationRef` | **NEW** |
+| 3 | SendEvent | `eventName: FulfilmentCreated` | OOTB |
+
+**User Actions:**
+```json
+[{"eventName": "CurbsidePickupRequested", "context": [{"label": "REQUEST CURBSIDE PICKUP", "type": "PRIMARY"}]}]
+```
+
+---
+
+> _Repeat for every ruleset in the workflow. Use `...` only for large EXISTING blocks where props are unchanged and well-known. Never abbreviate NEW or MODIFIED rulesets._
+
+#### Summary
+
+| Entity | Existing | New | Modified | Total |
+|--------|----------|-----|----------|-------|
+| ORDER | N | N | N | N |
+| FULFILMENT_CHOICE | N | N | N | N |
+| FULFILMENT | N | N | N | N |
+| **Total** | **N** | **N** | **N** | **N** |
+
+> **Key rules for this section:**
+> - **Every ruleset gets a block** — no exceptions. This is the complete workflow.
+> - **Every rule in every ruleset gets a row** with its full props.
+> - **Props must show actual values**, not placeholders. For EXISTING rulesets, read from the workflow JSON.
+> - **NEW and MODIFIED blocks are bolded** in the heading and in rule rows.
+> - **MODIFIED rulesets** must show what changed — add a note like "Added rule #3 (NEW)" or "Changed prop `type` from `CC` to `CURBSIDE`".
+> - **Group by entity type** with entity-level count headers.
+> - **User actions** are shown as JSON blocks below the rules table (only if the ruleset has them).
+> - This section replaces the need to cross-reference §6 and §6.1 — it is the single comprehensive reference.
+
+## 7. Rules Inventory **[required]**
+
+> ALL rules involved in the feature. Every rule classified by source.
+> A feature typically involves a mix of OOTB, existing custom, and new custom rules.
+
+| ID | Rule Name | Source | Module / Plugin | Entity | Inline/Scheduled | Purpose |
+|----|-----------|--------|----------------|--------|-----------------|---------|
+| R1 | CreateCurbsidePickupRule | **NEW** | sagirish-extensions | ORDER | Inline | Creates CURBSIDE fulfilment with pickup location |
+| R2 | ValidatePickupWindow | **NEW** | sagirish-extensions | ORDER | Inline | Validates pickup time is within allowed window |
+| R3 | SendEvent | **OOTB** | fc-core | ORDER | Inline | Fires CurbsidePickupCreated → FULFILMENT. Config: `eventName=CurbsidePickupCreated` |
+| R4 | SetAttributes | **OOTB** | fc-core | FULFILMENT | Inline | Sets estimatedPickupTime from event attribute. Config: `attributeMap={...}` |
+| R5 | SendWebhook | **OOTB** | fc-plugin-webhook | ORDER | Inline | HTTP POST to curbside notification endpoint. Config: `settingName=webhook.curbside.notify` |
+| R6 | ScheduleExpiry | **OOTB** | fc-plugin-order | ORDER | Inline | Schedules CurbsideTimeout event. Config: `delay=30m, eventName=CurbsideTimeout` |
+| R7 | UpdateFulfilmentStatus | **EXISTING** | sagirish-extensions | FULFILMENT | Inline | Reused from HD flow — no code changes needed |
+| R8 | SetOrderStatus | **OOTB** | fc-core | ORDER | Inline | Sets ORDER to target status. Config: `status=AWAITING_PICKUP` |
+
+> **For OOTB rules:** state the prop/config values to set in the ruleset.
+> **For EXISTING rules:** confirm no code changes needed, or if MODIFIED, note what changes.
+> **For NEW rules:** full pseudo logic in §8.
+
+## 8. Detailed Design (New Rules) **[required if any NEW rules exist]**
+
+> For each **NEW** rule in §7, provide: class metadata, parameters table, pseudo logic, and GraphQL operations.
+> Skip this section entirely if all rules are OOTB or EXISTING.
+
+---
+
+### R1: CreateCurbsidePickupRule
+
+**Class:** `com.fluentcommerce.rule.order.CreateCurbsidePickupRule`
+**Extends:** `BaseRule`
+**Entity:** ORDER
+
+#### Parameters
+
+| Param | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| pickupLocationPath | String | Yes | — | JSON path to pickup location ref |
+| estimatedPickupTimePath | String | No | — | JSON path to estimated pickup time |
+| fulfilmentType | String | No | `CURBSIDE` | Fulfilment subtype |
+| vehicleDescriptionPath | String | No | — | JSON path to vehicle description |
+
+#### Pseudo Logic
+
+```
+FUNCTION run(context):
+    order = context.getEntity()
+    event = context.getEvent()
+
+    // 1. Extract required fields
+    pickupLocationRef = extractFromPath(event, props.pickupLocationPath)
+    IF pickupLocationRef IS NULL:
+        THROW "Pickup location ref is required but was null at path: {pickupLocationPath}"
+
+    // 2. Extract optional fields
+    estimatedPickupTime = extractFromPath(event, props.estimatedPickupTimePath)  // nullable
+    vehicleDescription = extractFromPath(event, props.vehicleDescriptionPath)    // nullable
+
+    // 3. Fetch order items
+    items = DynamicUtils.queryList(context, "items", OrderItem.class, null)
+    IF items IS EMPTY:
+        THROW "Order has no items — cannot create fulfilment"
+
+    // 4. Build fulfilment
+    fulfilmentRef = "CURB-{order.ref}-{pickupLocationRef}"
+    fulfilmentInput = CreateFulfilmentInput {
+        ref: fulfilmentRef,
+        type: props.fulfilmentType OR "CURBSIDE",
+        deliveryType: "CURBSIDE",
+        order: { id: order.id },
+        fromLocation: { ref: pickupLocationRef },
+        items: items.map(i => { ref: i.ref, quantity: i.quantity }),
+        attributes: [
+            { name: "pickupLocationRef", value: pickupLocationRef },
+            { name: "estimatedPickupTime", value: estimatedPickupTime },
+            { name: "vehicleDescription", value: vehicleDescription },
+            { name: "deliveryType", value: "CURBSIDE" },
+            { name: "createdByRule", value: "CreateCurbsidePickupRule" }
+        ]
+    }
+
+    // 5. Execute mutation
+    DynamicUtils.create(context, fulfilmentInput)
+
+    // 6. Log
+    context.addLog("Created curbside fulfilment {fulfilmentRef} for order {order.ref}")
+```
+
+#### GraphQL Operations
+
+**Query — Fetch order items:** _(REUSED pattern from CreateFulfilmentFromSourcingLocation)_
+```graphql
+query {
+  orderById(id: $orderId) {
+    items { edges { node { id ref quantity productRef } } }
+  }
+}
+```
+
+**Mutation — Create fulfilment:** _(REUSED pattern)_
+```graphql
+mutation($input: CreateFulfilmentInput!) {
+  createFulfilment(input: $input) { id ref status }
+}
+```
+
+---
+
+### R2: ValidatePickupWindow
+
+**Class:** `com.fluentcommerce.rule.order.ValidatePickupWindowRule`
+**Extends:** `BaseRule`
+**Entity:** ORDER
+
+#### Parameters
+
+| Param | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| configSettingName | String | Yes | — | Setting key for pickup config JSON |
+| pickupTimePath | String | Yes | — | JSON path to requested pickup time in event |
+
+#### Pseudo Logic
+
+```
+FUNCTION run(context):
+    order = context.getEntity()
+    event = context.getEvent()
+
+    // 1. Read config from setting
+    config = SettingUtils.getSettingByRef(context, props.configSettingName)
+    maxPickupHours = config.lobValue.maxPickupHours
+
+    // 2. Extract requested pickup time from event
+    requestedPickupTime = extractFromPath(event, props.pickupTimePath)
+    IF requestedPickupTime IS NULL:
+        THROW "Requested pickup time is required at path: {pickupTimePath}"
+
+    // 3. Validate window
+    orderCreatedOn = order.createdOn
+    deadline = orderCreatedOn + maxPickupHours hours
+    IF requestedPickupTime > deadline:
+        THROW "Pickup time {requestedPickupTime} exceeds allowed window of {maxPickupHours}h from order creation"
+
+    // 4. Pass — validation gate, no mutation
+    context.addLog("Order {order.ref} passed pickup window validation")
+```
+
+#### GraphQL Operations
+
+**Query — Read setting:** _(REUSED pattern — SettingUtils utility)_
+```graphql
+query {
+  settings(first: 1, filter: { name: { eq: $settingName }, context: { eq: "RETAILER" } }) {
+    edges { node { lobValue } }
+  }
+}
+```
+
+---
+
+> _Repeat this pattern for each NEW rule._
+
+## 9. Settings **[required when creating/modifying settings]**
+
+| Setting Key | Source | Context | Context ID | Value Type | Shape / Example | Used By (Rule) |
+|------------|--------|---------|-----------|-----------|-----------------|---------------|
+| curbside.pickup.config | **NEW** | RETAILER | 5 | LOB | `{"maxPickupHours": 48, "zones": ["ZONE_A", "ZONE_B"], "requireVehicleDesc": true}` | R2: ValidatePickupWindow |
+| webhook.curbside.notify | **NEW** | RETAILER | 5 | LOB | `{"url": "https://store-api.example.com/curbside/notify", "headers": {"X-Api-Key": "..."}}` | R5: SendWebhook |
+| ORDER_HD_FULFILMENT_TYPE | **EXISTING** | RETAILER | 5 | STRING | Already exists, value `"HD"` — no change | — |
+
+> **For NEW settings:** full JSON example showing all fields.
+> **For EXISTING settings:** confirm current value and whether it needs modification.
+> **For MODIFIED settings:** show before → after diff.
+
+## 10. Webhooks _(optional)_
+
+| Setting Name | Source | Method | Endpoint Pattern | Trigger Rule | Payload Shape |
+|-------------|--------|--------|-----------------|-------------|---------------|
+| webhook.curbside.notify | **NEW** | POST | `${url}` from setting | R5: SendWebhook (OOTB) | `{"orderRef": "...", "pickupTime": "...", "locationRef": "...", "vehicleDesc": "..."}` |
+
+> Omit this section if no webhooks are involved.
+
+## 11. Scheduled Events _(optional)_
+
+| Event Name | Source | Delay | Entity Type | Triggered By (Rule) | Purpose |
+|-----------|--------|-------|-------------|-------------------|---------|
+| CurbsideTimeout | **NEW** | 30min | ORDER | R6: ScheduleExpiry (OOTB) | Cancel pickup if not collected |
+
+> Omit this section if no scheduled events are involved.
+
+## 12. GraphQL Operations **[required when rules make GraphQL calls]**
+
+| Operation | Source | Type | Root Field | Selected Fields | Used By (Rule) | Purpose |
+|-----------|--------|------|-----------|----------------|---------------|---------|
+| Fetch order items | **REUSED** pattern from CreateFulfilmentFromSourcingLocation | Query | orderById.items | id, ref, quantity | R1: CreateCurbsidePickupRule | Get items for fulfilment creation |
+| Create fulfilment | **REUSED** pattern | Mutation | createFulfilment | ref, type, order, items, attributes | R1: CreateCurbsidePickupRule | Create CURBSIDE fulfilment |
+| Read setting | **REUSED** — SettingUtils | Query | settings | lobValue | R2: ValidatePickupWindow | Read pickup config |
+
+> **"REUSED pattern"** means existing code in the codebase already does this — copy the approach.
+> **"NEW"** would mean a novel GraphQL operation not seen in the codebase.
+
+## 13. Cross-Entity Impact **[required for multi-entity features]**
+
+| Source Entity | Target Entity | Mechanism | Source | Action |
+|--------------|--------------|-----------|--------|--------|
+| ORDER | FULFILMENT | createFulfilment mutation | **NEW** (in R1: CreateCurbsidePickupRule) | Creates CURBSIDE fulfilment |
+| ORDER | FULFILMENT | SendEvent (OOTB R3) | **REUSED** | Fires CurbsidePickupCreated |
+| FULFILMENT | ORDER | SendEvent (OOTB) | **REUSED** | Status update event back to ORDER |
+
+> Omit this section for single-entity features.
+
+## 14. Files **[required]**
+
+| # | Action | Path | Source | Description |
+|---|--------|------|--------|-------------|
+| 1 | Create | `.../src/main/java/.../CreateCurbsidePickupRule.java` | NEW | Rule R1 |
+| 2 | Create | `.../src/test/java/.../CreateCurbsidePickupRuleTest.java` | NEW | Tests for R1 (4 tests) |
+| 3 | Create | `.../src/main/java/.../ValidatePickupWindowRule.java` | NEW | Rule R2 |
+| 4 | Create | `.../src/test/java/.../ValidatePickupWindowRuleTest.java` | NEW | Tests for R2 (3 tests) |
+| 5 | Modify | `.../resources/module.json` | MODIFIED | Wire R1, R2 registrations |
+| 6 | Modify | `accounts/.../workflows/.../ORDER__HD.json` | MODIFIED | Add CurbsidePickupRequested + ConfirmCurbsidePickup rulesets |
+| 7 | Create | `accounts/.../workflows/.../FULFILMENT__CURBSIDE.json` | NEW | New curbside fulfilment workflow |
+
+> All paths relative to `accounts/<PROFILE>/SOURCE/<repo>/`.
+
+## 15. Risks & Mitigations **[required]**
+
+| Risk | Severity | Impact | Mitigation |
+|------|----------|--------|-----------|
+| Ruleset trigger overlaps with existing OnCreate | HIGH | Events route to wrong ruleset | Verify trigger uniqueness via workflow-analyzer |
+| New rule throws on null pickup location | MEDIUM | Order stuck in current status | Unit test null/empty inputs; validation guard |
+| Webhook endpoint not provisioned at go-live | LOW | Notification silently fails | Setting updated later; log warning |
+
+## 16. Test Plan **[required]**
+
+| # | Test | Type | Event | Expected Status | Assertion |
+|---|------|------|-------|----------------|-----------|
+| 1 | Happy path: curbside pickup | E2E | CurbsidePickupRequested | ORDER → AWAITING_PICKUP | status + fulfilment created |
+| 2 | Pickup collected | E2E | ConfirmCurbsidePickup | ORDER → PICKED_UP | status + fulfilment COLLECTED |
+| 3 | Timeout cancellation | E2E | (wait 30min) | ORDER → CANCELLED | scheduled event fired |
+| 4 | Regression: normal HD | E2E | CreateOrder | ORDER → BOOKED | Existing flow unaffected |
+| 5 | R1: creates fulfilment | Unit | — | — | Mutation called with correct args |
+| 6 | R1: throws on missing location | Unit | — | — | RuntimeException |
+| 7 | R2: rejects expired window | Unit | — | — | RuntimeException |
+| 8 | R2: passes valid pickup time | Unit | — | — | No exception, log written |
+
+## 17. Deployment Sequence **[required for environment changes]**
+
+| # | Step | Depends On | Skill | Rollback |
+|---|------|-----------|-------|----------|
+| 1 | Validate module structure | — | `/fluent-module-validate` | N/A |
+| 2 | Build module v1.2.4 | 1 | `/fluent-build` | N/A (local) |
+| 3 | Pre-deploy check | 2 | `/fluent-pre-deploy-check` | N/A |
+| 4 | Deploy module | 3 (READY) | `/fluent-module-deploy` | Re-deploy v1.2.3 |
+| 5 | Upload ORDER::HD v13 | 4 | `/fluent-workflow-deploy` | Re-upload v12 |
+| 6 | Upload FULFILMENT::CURBSIDE v1 | 4 | `/fluent-workflow-deploy` | Delete workflow |
+| 7 | Create settings (2) | 5, 6 | `/fluent-settings` | Delete settings |
+| 8 | E2E test | 7 | `/fluent-e2e-test` | — |
+
+> **Ordering constraint:** Module deploy (step 4) must complete before workflow deploy (steps 5-6). Workflows reference rules that are registered during module deployment. Deploying workflows before the module causes NO_MATCH events.
+
+## 18. Rollback Plan _(optional — recommended for production changes)_
+
+> How to reverse this change:
+> 1. Re-upload ORDER::HD v12 via `/fluent-workflow-deploy`
+> 2. Delete FULFILMENT::CURBSIDE workflow (or leave dormant -- no triggers will route to it)
+> 3. Delete/disable webhook and config settings
+> 4. Re-deploy module v1.2.3 via `/fluent-module-deploy`
+> 5. Note: New statuses (AWAITING_PICKUP, PICKED_UP) become dormant (no triggers route to them)
+````
+
+---
+
+## Section Applicability Guide
+
+Not every plan needs every section. Use this guide:
+
+| Section | When Required |
+|---------|-------------|
+| 1. Business Context | **Always** |
+| 2. Scope | **Always** |
+| 3. Architecture & Diagrams | **Always** (at least one diagram) |
+| 4. Workflows | **Always** (even "No workflow changes" is valid) |
+| 5. Statuses | When adding or modifying workflow statuses |
+| 6. Rulesets — Change Summary | **Always** when touching workflows (quick-glance table of what's changing) |
+| 6.1 Complete Workflow Inventory | When modifying an existing workflow. **Full rules + props for every ruleset** — the single source of truth |
+| 7. Rules Inventory | **Always** when the feature involves rules |
+| 8. Detailed Design (New Rules) | When any rule is **NEW** |
+| 9. Settings | When creating/modifying settings |
+| 10. Webhooks | When adding webhook-based rules |
+| 11. Scheduled Events | When adding time-delayed events |
+| 12. GraphQL Operations | When rules make GraphQL calls |
+| 13. Cross-Entity Impact | When feature spans multiple entity types |
+| 14. Files | **Always** |
+| 15. Risks | **Always** |
+| 16. Test Plan | **Always** |
+| 17. Deployment Sequence | When deploying to an environment |
+| 18. Rollback Plan | Recommended for production; optional for dev/sandbox |
+
+## Rules Classification Decision Flow
+
+Before classifying any rule, follow this decision tree:
+
+1. **Search `plugin.list`** for an OOTB match by name or description
+2. **If OOTB exists and fits** → label as **OOTB**, document the prop values to configure
+3. **If OOTB exists but doesn't quite fit** → document why. Consider wrapping (OOTB + custom pre/post rule) vs writing from scratch
+4. **Search existing custom source** (`accounts/<PROFILE>/SOURCE/`) for a similar rule
+5. **If existing custom fits** → label as **EXISTING**, confirm no changes needed
+6. **If existing custom needs tweaks** → label as **MODIFIED**, show before → after
+7. **If pattern exists** but no reusable rule → label the approach as **REUSED** in GraphQL Operations (§12)
+8. **Only when no viable alternative exists** → label as **NEW**, provide full pseudo logic in §8
+
+## Diagram Requirements
+
+Plans MUST include visual Mermaid diagrams. Include ALL that apply:
+
+| Diagram | When Required | Mermaid Type |
+|---------|-------------|-------------|
+| State machine | Any workflow creation or modification | `stateDiagram-v2` |
+| Cross-entity event flow | Cross-entity events, webhooks, multi-step processing | `sequenceDiagram` |
+| Data flow | Complex processing, decision trees, event propagation | `flowchart` |
+| Before → After diff | Modifications to existing workflows | Text or `workflow.diff` |
+| Entity relationships | Module scaffolding, retailer config | `erDiagram` or `flowchart` |
+| Workflow processing flow | Modifying an existing workflow with multiple rulesets | `flowchart TD` |
+
+For workflow modifications, the state diagram MUST show ALL statuses (not just new ones) and annotate changes with `:::added`, `:::removed`, `:::modified`. The workflow processing flow (§3.6) MUST show all rulesets in execution context with NEW/MODIFIED highlighted.
+
+**Syntax validation:** Before writing any plan file, validate all Mermaid blocks against `/fluent-mermaid-validate` and the Mermaid Syntax Rules below.
+
+## Mermaid Syntax Rules
+
+**MANDATORY: Validate every Mermaid block against these rules before outputting.**
+
+### All Diagrams
+- First line after the mermaid fence MUST be the diagram type (`stateDiagram-v2`, `sequenceDiagram`, `flowchart TD`, etc.) — no blank line between fence and type
+- Node/state IDs: alphanumeric and underscores only. NO spaces, NO hyphens, NO special chars. Use `as` aliasing for display names
+- Every `subgraph`, `alt`, `opt`, `loop`, `par`, `state { }` block MUST have a matching `end`
+- No HTML tags in labels (use `<br/>` only in flowchart node labels, nowhere else)
+- No trailing semicolons
+
+### stateDiagram-v2
+- MUST use `stateDiagram-v2` (NOT `stateDiagram` — v1 has different syntax)
+- Start/end: `[*]` (brackets required)
+- Transitions: `StateA --> StateB : EventName` (double dash + arrow)
+- WRONG: `->` (single arrow), `=>`, `-->` without space before `:`
+- Composite: `state "Display Name" as alias`
+- Notes: `note right of StateName : text`
+- Style annotations: `StateName:::className` (three colons)
+
+### sequenceDiagram
+- Declare participants: `participant A as "Display Name"` — MUST appear before first use
+- Messages: `A->>B: text` (solid request), `A-->>B: text` (dashed response), `A-)B: text` (async)
+- WRONG: `A->B` (renders as different arrow type, usually not what you want)
+- WRONG: `A-->B` (this is a dotted line without arrowhead)
+- Activations: `activate A` / `deactivate A` on separate lines, OR `A->>+B:` / `B-->>-A:`
+- Blocks: `alt condition` / `else other` / `end` — every block needs `end`
+- Notes: `Note over A,B: text` or `Note right of A: text` (capital N)
+
+### flowchart
+- MUST declare direction: `flowchart TD` (top-down), `flowchart LR` (left-right), `flowchart RL`, `flowchart BT`
+- WRONG: `flowchart` alone (no direction = parse error), `graph TD` (deprecated, use `flowchart`)
+- Node shapes: `A[rect]`, `A(rounded)`, `A{diamond}`, `A((circle))`, `A>flag]`, `A([stadium])`, `A[[subroutine]]`
+- Arrows: `-->` solid, `-.->` dotted, `==>` thick
+- Labels on arrows: `A -->|label text| B` (pipes around label)
+- WRONG: `A --> label --> B`, `A --label--> B`
+- Subgraphs: `subgraph Title` ... `end` — can be nested
+- Node IDs MUST NOT start with a digit or contain spaces: `node1` OK, `1node` BAD, `my node` BAD
+
+### classDiagram
+- Class: `class ClassName { +String field; +method() }` — visibility prefixes: `+` public, `-` private, `#` protected
+- Relationships: `A *-- B` composition, `A o-- B` aggregation, `A --> B` dependency, `A --|> B` inheritance
+
+### erDiagram
+- Entities: plain names `ORDER`, `FULFILMENT` (no brackets)
+- Relationships: `ORDER ||--o{ FULFILMENT : "has"` — cardinality markers: `||` exactly one, `o|` zero-or-one, `}|` one-or-more, `}o` zero-or-more
+- WRONG: using flowchart syntax, missing relationship label string
+
+### Pre-Output Checklist
+Before including any mermaid block in output:
+1. Diagram type on first line? (no blank line after fence)
+2. All IDs alphanumeric/underscore only?
+3. All blocks closed with `end`?
+4. Arrow syntax correct for this diagram type?
+5. Participant/node declarations before first use?
+6. No mixing of syntax from different diagram types?
+
+## Plan Lifecycle
+
+1. **Create** — Agent writes plan file with `Status: PENDING`, `Revision: 1`. Creates the plans directory if needed.
+2. **Present** — Agent shows the full plan content to the user and waits for approval.
+3. **Approve/Reject** — User responds:
+   - **Approved** ("yes", "go ahead", "approved", "do it") → update `Status: APPROVED`, `Approved by: user`, proceed
+   - **Rejected with feedback** → increment `Revision`, revise content, reset `Status: PENDING`, re-present
+   - **Questions** → answer without changing the file. If answers lead to changes, revise and increment revision
+   - **"Just do it" / "skip planning"** → write `Status: APPROVED (auto-skip)`, `Approved by: user (gate skipped)`, proceed
+4. **Reference** — During implementation, the plan file is the single source of truth for what was agreed.
+5. **Post-implementation** — Session summary references the plan file path. Future sessions can read approved plans.