@fluentcommerce/ai-skills 0.1.0

package/content/dev/skills/fluent-build/SKILL.md

@@ -0,0 +1,192 @@
+---
+name: fluent-build
+description: Build, version, package, and deploy Fluent Commerce extension modules. Handles Maven compilation, version bumping, module packaging, and deployment. Triggers on "build module", "bump version", "package module", "deploy module", "maven build".
+user-invocable: true
+allowed-tools: Bash, Read, Write, Edit, Glob, Grep
+argument-hint: [build|version|package|deploy|full] [--skip-tests]
+---
+
+# Build and Packaging
+
+Build and package Fluent extension modules with consistent versioning.
+
+## Planning Gate
+
+**Before version bumping or packaging, write a plan using the template from `PLAN_TEMPLATE.md` in the `fluent-feature-plan` skill.** Plain `mvn clean install` builds (no version change) are exempt.
+
+**Build-specific emphasis — ensure these are covered:**
+
+1. **Business Context (Section 1)** — what change drives this version bump
+2. **Scope (Section 2)** — current version → new version, bump type (patch/minor/major) with rationale
+3. **Files (Section 6)** — all pom.xml files, module.json, CHANGELOG.md that will be modified
+4. **Impacted retailers (Section 4.8)** — which environments get the new version
+5. **Test Plan (Section 8)** — confirm tests pass before versioning
+6. **Deployment Sequence (Section 9)** — build → test → version bump → package → deploy order
+
+**Write the plan to:** `accounts/<PROFILE>/plans/<YYYY-MM-DD>-build-<slug>.md`. Set `Status: PENDING`.
+
+Present the full plan content to the user and wait for approval before bumping versions. On approval, update the file to `Status: APPROVED`. If the user says "just do it", proceed directly (still write the file for audit trail).
+
+## Ownership Boundary
+
+This skill owns:
+
+- version bumping
+- Maven build/test execution
+- module ZIP packaging
+
+This skill does **not** own deployment runbooks. For deployment:
+
+- use `/fluent-module-deploy` for manual installs
+- use `flow-run` for guarded automation and JSON run reporting
+
+## When to Use
+
+- Java rule or utility code changed
+- Workflow JSON, settings, or resource files changed in `resources/`
+- module version needs bumping before redeploy
+- a new deployable ZIP artifact is required
+- build errors need diagnosis and recovery
+
+## Pre-Check: Module Validation (Enforced Gate)
+
+Before building, check the cached validation report from `/fluent-module-validate`:
+
+```
+accounts/<PROFILE>/analysis/module-validate/<module-name>.report.json
+```
+
+**This is a gating check, not advisory:**
+
+1. **Report exists and `summary.status == "NEEDS_FIXES"`** -- **STOP**. List all FAIL items from the report. Ask the user to confirm proceeding despite validation failures. Do NOT silently continue.
+
+2. **Report exists and `summary.status == "READY_FOR_BUILD"`** -- proceed with build.
+
+3. **Report is missing or stale** (content hash in `.hash` file doesn't match current source) -- **run `/fluent-module-validate` inline** before building. This ensures validation is always current. If inline validation finds FAIL items, apply the same gating behavior as case 1.
+
+The validation report checks: module.json structure, POM consistency, version alignment, rule wiring, test coverage, and more. Building a module that fails validation wastes time and may produce a broken artifact.
+
+## Pre-Check: Load Source Analysis
+
+Before building, check if `/fluent-custom-code` analysis artifacts exist:
+
+```
+accounts/<PROFILE>/analysis/custom-code/source-map.json
+```
+
+If found, read to discover:
+- `modules[].buildRoot` — correct directory to run Maven from
+- `modules[].buildCommand` — build command
+- `modules[].packageScript` — packaging script path
+- `modules[].outputArtifact` — expected output ZIP
+- `modules[].version` — current version (for bump validation)
+
+If not found, fall back to the defaults below. Treat artifact-gate failures as "not found" (for example missing required files, missing hashes, or blocking `missingSources` in `constraints.json`).
+
+## Prerequisites Check
+
+Run before building:
+
+```bash
+node --version
+java --version
+mvn --version
+fluent --version
+```
+
+Use the repository-supported runtime versions for your environment.
+
+## 1) Version Bump (required before redeploy)
+
+> **Full version lifecycle:** For version status, sync, CHANGELOG updates, and git tagging, use `/fluent-version-manage`. This section covers the minimum bump needed before a build.
+
+### When to Bump
+
+**A version bump is required whenever ANY content in the module changes — not just Java code.**
+
+| Change Type | Examples | Bump Required? | Why |
+|------------|---------|---------------|-----|
+| Java code | New rule, bug fix, refactor | **YES** | JAR filename includes version; CLI skips upload if same version exists |
+| Workflow JSON | New ruleset, status change, rule reorder | **YES** | Module version tracks what's deployed; without bump the module install looks identical to last deploy |
+| Settings | New setting, value change | **YES** | Same reason — traceability of what version introduced the change |
+| Resources | New assets, config templates | **YES** | Packaged into the module ZIP; version is the audit trail |
+| No content change | Re-deploy same content | **NO** | Use `--force` flag if re-install is needed |
+
+**Key gotcha:** The Fluent CLI checks the plugin JAR filename against what's already uploaded. If `fc-module-<name>-0.0.30.jar` is already active, uploading the same version results in `"already uploaded: Active - nothing more to do"` — the JAR is silently skipped. **Both `resources/module.json` AND all `pom.xml` files must be bumped in sync**, because Maven uses the POM version for the JAR filename while the CLI uses `module.json` version for the module-level check.
+
+### Version Sync — All Files Must Match
+
+Fluent ignores re-uploading the same module version. Keep these files in sync:
+
+| File | Field |
+|---|---|
+| `plugins/pom.xml` | parent `<version>` |
+| `plugins/rules/<module-alias>/pom.xml` | parent/module `<version>` |
+| `plugins/types/<module-alias>/pom.xml` | parent/module `<version>` |
+| `plugins/util/<module-alias>/pom.xml` | parent/module `<version>` |
+| `resources/module.json` | `"version"` |
+
+### Bump Procedure
+
+1. Read current `resources/module.json` version.
+2. Increment patch version (or minor/major per semver rationale).
+3. Update `resources/module.json` version field.
+4. Update all POM files — use Maven to ensure consistency:
+   ```bash
+   cd plugins/ && mvn versions:set -DnewVersion=<NEW_VERSION> -DgenerateBackupPoms=false
+   ```
+5. Verify old version no longer exists in the module source tree:
+   ```bash
+   grep -r "<old-version>" plugins/*/pom.xml resources/module.json
+   ```
+
+## 2) Build
+
+From `plugins/`:
+
+```bash
+# Full build
+mvn clean install
+
+# Build without tests
+mvn clean install -DskipTests
+
+# Build targeted module with dependencies
+mvn clean install -pl rules/<module-alias> -am
+```
+
+## 3) Package
+
+After a successful build, create a deployable ZIP:
+
+```bash
+# Bash (macOS/Linux/Git Bash on Windows)
+./scripts/build-module.sh
+./scripts/build-module.sh -p              # skip plugins (packaging only)
+```
+
+```powershell
+# PowerShell (Windows native)
+.\scripts\build-module.ps1
+.\scripts\build-module.ps1 -SkipPlugins
+```
+
+Expected output:
+
+`dist/fluent-commerce-<module-name>-<VERSION>.zip`
+
+## 4) Hand Off to Deploy Owner
+
+After packaging completes:
+
+- manual path: `/fluent-module-deploy`
+- automated path: `npx @fluentcommerce/ai-skills flow-run --deploy --yes ...`
+
+## Common Build Failures
+
+| Symptom | Likely cause | First check |
+|---|---|---|
+| `cannot find symbol` | import/type mismatch | validate changed classes and imports |
+| dependency/module not found | wrong module scope/build root | run from `plugins/` and include `-am` where needed |
+| tests fail after model changes | fixture/schema drift | update test fixtures and expected payloads |
+| package script succeeds but ZIP missing expected assets | resource path mismatch | verify `resources/` contents and module build script inputs |

package/content/dev/skills/fluent-connection-analysis/SKILL.md

@@ -0,0 +1,386 @@
+---
+name: fluent-connection-analysis
+description: Analyze workflow connection topology across rulesets and workflows. Produces internal/cross-entity/cross-workflow maps, static-vs-dynamic runtime diffs, and webhook/setting conformance inventories with Mermaid output. Triggers on "connection analysis", "workflow connections", "cross workflow dependencies", "orphaned rulesets", "process flow classification", "webhook dependency map", "expected vs observed rulesets", "runtime workflow diff".
+user-invocable: true
+allowed-tools: Bash, Read, Write, Edit, Glob, Grep
+argument-hint: <workflow-file-or-name> [--deep] [--mermaid] [--output <path>] [--validate <entity-ref> --entity-type ORDER|FULFILMENT] [--from <iso> --to <iso>]
+---
+
+# Fluent Connection Analysis
+
+Connection-focused analysis for Fluent workflows. Use this when the main question is not just "what statuses exist?" but "how does work move between rulesets/workflows and where are the risky dependency points?"
+
+## Ownership Boundary
+
+This skill owns:
+- connection topology (internal, cross-entity, cross-workflow)
+- orphan/missing-target detection
+- process-flow type classification
+- webhook and setting dependency extraction
+
+Related skills:
+- Workflow structure baseline -> `/fluent-workflow-analyzer`
+- Workflow edits/fixes -> `/fluent-workflow-builder`
+- Runtime failure correlation -> `/fluent-trace`
+- Settings validation -> `/fluent-settings`
+
+## When to Use
+
+- Mapping dependencies before changing a workflow
+- Explaining "what triggers what" across entities
+- Finding orphaned rulesets and missing SendEvent targets
+- Auditing integration/webhook touchpoints
+- Producing architecture handover docs with Mermaid diagrams
+- Comparing static expected paths vs runtime observed execution after an event/mutation
+- Verifying rule-referenced settings exist and are valid in live context
+
+## Seamless Default Bundle
+
+Run this skill as a single-pass bundle by default:
+
+1. Static connection topology + risk checks
+2. Settings conformance (`rule props -> live setting status`)
+3. Runtime diff (when `--validate` inputs are provided)
+
+If `--validate` is not provided, still emit sections 1-2 and explicitly mark runtime diff as `NOT_RUN`.
+
+## Connection Analysis Procedure
+
+### 1) Gather Workflow Set
+
+1. Resolve target workflow(s) (local file or via `/fluent-workflow` download).
+2. For dependency analysis, load adjacent workflows in the same retailer (ORDER + FULFILMENT + child types).
+3. Build indexes:
+   - rulesets by `(type, name)`
+   - statuses by `(entityType, name)`
+   - event emitters by `eventName` — scan ALL rules with `eventName` or `noMatchEventName` props (SendEvent, ScheduleEvent, ForwardEvent*, SendEventOnVerifying*, and any other event-emitting rule)
+
+### 2) Build Connection Graph
+
+For each ruleset:
+1. Identify incoming edges:
+   - event-name match (`event.name == ruleset.name`)
+   - status-trigger match (`triggers[].status`)
+2. Identify outgoing edges:
+   - `SendEvent(eventName)` -> target ruleset(s)
+   - `SetState(status)` -> status transition edges
+3. Classify each edge:
+   - `internal`: same workflow/entity scope
+   - `cross-entity`: different entity type
+   - `cross-workflow`: target flexType/workflow differs
+4. Annotate conditional edges:
+   - If a ruleset has a `subtype` field (e.g. `"subtype": "HD_WH"`), mark all its incoming edges as **conditional on subtype**. The event fires for all subtypes but only this ruleset's trigger scope matches the specific subtype.
+   - In the report, label conditional edges: `ConfirmPick --(HD_WH only)--> RequestShipment`
+
+### 3) Detect Risks
+
+Run these checks:
+- orphaned rulesets (no trigger and no inbound SendEvent)
+- missing SendEvent targets (no ruleset receives emitted event)
+- trigger conflicts (multiple rulesets for same status in same type)
+- dead-end non-terminal statuses
+- unreachable statuses (never targeted by SetState)
+
+**Duplicate ruleset severity calibration:**
+- Same name + same entity type + same subtype (or both subtype-empty) + **overlapping trigger statuses** = **HIGH** (ambiguous runtime behavior)
+- Same name + same entity type + same subtype (or both subtype-empty) + **non-overlapping trigger statuses** = **MEDIUM** (maintenance ambiguity; often intentional normal-vs-late variants)
+- Same name + same entity type + **different subtype filters** = **INFO** (usually intentional subtype partitioning; document explicitly)
+
+### 4) Process Flow Classification
+
+Classify each ruleset into one flow type. There are 6 categories (not 5):
+
+| Type | Condition | Examples |
+|------|-----------|---------|
+| `CREATE` | Ruleset name is `CREATE` | ORDER.CREATE, FULFILMENT.CREATE |
+| `SCHEDULED_EVENT` | Ruleset receives event fired by `ScheduleEvent` | ValidationGraceExpired |
+| `CROSS_ENTITY_EVENT` | Ruleset receives event fired by `SendEventForOrder`, `SendEventForAllFulfilmentChoices`, `SendEventForAllFulfilments`, or other cross-entity Send rules | NotifyFCComplete, RouteFulfilmentChoice, CancelFulfilment |
+| `USER_ACTION` | Ruleset has non-empty `userActions[]` | CancelOrder, EscalateFulfilmentChoice |
+| `INTERNAL_EVENT` | Ruleset receives event fired by `SendEvent` or `ForwardEvent*` from another ruleset **within the same entity type** | ValidateOrder (from CREATE), ProcessOrder (from ConfirmValidation), TransitionToShipped (from NotifyFulfilmentShipped) |
+| `INTEGRATION_EVENT` | No inbound SendEvent from any ruleset in the workflow; event arrives from external system | ConfirmValidation, ConfirmPick, ConfirmShipment, ConfirmDelivery |
+
+**How to distinguish INTERNAL_EVENT from INTEGRATION_EVENT:**
+1. Build the emitter index by scanning ALL event-emitting rule patterns in the workflow:
+   - `core.SendEvent` → `eventName` prop
+   - `core.ScheduleEvent` → `eventName` prop
+   - `ForwardEventBy*` (e.g. `ForwardEventByFulfilmentChoiceType`) → `eventName` prop
+   - `SendEventOnVerifying*` (e.g. `SendEventOnVerifyingAttributeValue`) → both `eventName` AND `noMatchEventName` props
+   - `SendEventOnVerifyingAllFulfilment*States` → `eventName` prop
+   - **Catch-all:** Any rule with an `eventName` or `noMatchEventName` prop emits events — include it.
+   Record each emitted event name and which ruleset emits it.
+2. If a ruleset's name appears as an emitted `eventName` from another ruleset in the same entity type → `INTERNAL_EVENT`.
+3. If a ruleset's name does NOT appear as any emitted `eventName` in the workflow → `INTEGRATION_EVENT` (external inbound).
+4. Conditional emitters count: `noMatchEventName` targets, scheduled event targets, and gate-pattern event targets (from `SendEventOnVerifyingAll*`) are all internal emitters.
+5. **Dual classification:** A ruleset can be both a USER_ACTION (has `userActions[]`) and an INTERNAL_EVENT target (e.g. `CancelOrder` is a user action but also sent by `GracePeriodTimeoutCancel`). Use the primary classification per priority order, but note dual roles in the report.
+
+Priority for deterministic classification (first match wins):
+1. `CREATE`
+2. `SCHEDULED_EVENT`
+3. `CROSS_ENTITY_EVENT`
+4. `USER_ACTION`
+5. `INTERNAL_EVENT`
+6. `INTEGRATION_EVENT`
+
+### 5) Webhook + Setting Dependency Mapping
+
+Detect webhook/integration patterns by:
+- rule name patterns (`webhook`, `notify`, `callback`, `publish`, `subscribe`)
+- rule props referencing webhook/setting keys
+
+Detect setting usage by prop-key/value patterns:
+- `setting`, `config`, `parameter`, `option`, `property`
+
+Output:
+- ruleset -> webhook touchpoints
+- ruleset -> setting keys
+- setting -> dependent rulesets/workflows
+- setting runtime contract status (`FOUND`, `MISSING`, `EMPTY`, `INVALID_FORMAT`)
+
+Runtime setting verification:
+1. For each extracted setting key, query live settings using **cascading scope resolution**:
+   - First: `RETAILER` + retailer `contextId`
+   - Then: `ACCOUNT` + `contextId=0`
+   - Use the first scope where the setting is found.
+   Module-installed settings often default to `ACCOUNT` scope. Always check both before reporting `MISSING`.
+2. Validate existence and value shape:
+   - `MISSING`: no setting found.
+   - `EMPTY`: found but `value` and `lobValue` are empty.
+   - `INVALID_FORMAT`: value exists but does not match expected shape (for example webhook JSON missing `url`).
+   - `FOUND`: exists with plausible value shape.
+3. Emit a contract table: `setting -> referencedByRulesets -> runtimeStatus -> notes`.
+
+For full CRUD/migration workflows, hand off to `/fluent-settings`.
+
+### 6) Produce Deliverables
+
+Always generate:
+1. Connection Summary (counts by internal/cross-entity/cross-workflow)
+2. Risk Findings (ordered by severity)
+3. Process Flow Table (ruleset -> flow type)
+4. Integration Dependency Table (webhook + settings)
+
+When `--mermaid` is enabled, generate:
+- state machine per entity (`stateDiagram-v2`)
+- event/connection flow (`flowchart TD`)
+- cross-entity lifecycle (`flowchart LR`)
+
+**Mermaid syntax:** Validate all generated diagrams against `/fluent-mermaid-validate` rules before output (no colons in free text, no unicode arrows, quoted special-char labels).
+
+**Mermaid accuracy rules:**
+- Dotted-line labels between entities must use **event names**, not rule names. If a rule (e.g. `CreateFulfilmentFromSourcingLocation`) creates a child entity, label the edge as "creates entity" or the subsequent CREATE event, not the rule class name.
+- Cross-entity lifecycle must show **intermediate statuses** when an entity transitions through multiple states. E.g. if ReportShortpick sends both NotifyFulfilmentShipped and NotifyFulfilmentDelivered, show the ORDER transitioning through SHIPPED before COMPLETED, not skipping directly to COMPLETED.
+- Annotate subtype-conditional paths in diagrams: `RequestShipment [HD_WH]`, `ReadyForPickup [CC_PFS]`.
+
+### 7) Validate Against Live Data (`--validate`)
+
+Use this when you have a real entity and want to compare "what the static connection graph predicts" vs "what actually executed at runtime". Requires `--validate <entity-ref> --entity-type <TYPE>`.
+
+#### 7a) Resolve Entity and Determine Scope
+
+1. Accept entity ref and type from CLI arguments. Supported types: `ORDER`, `FULFILMENT`, `FULFILMENT_CHOICE`, `ARTICLE`.
+2. Query the entity to confirm it exists and retrieve its current status and subtype:
+   ```
+   graphql.query: { orders(ref: ["<REF>"]) { edges { node { id ref type status } } } }
+   ```
+   (Adjust root field for entity type: `orders`, `fulfilments`, etc.)
+3. Determine the workflow flexType from entity type + subtype (e.g. `ORDER::HD`, `FULFILMENT::HD_WH`).
+4. Load the matching workflow JSON from the local workflow set (Steps 1-2 of the main procedure). If not found locally, download it.
+5. Run Steps 2-4 (Build Connection Graph, Detect Risks, Process Flow Classification) on the workflow to produce the **expected connection graph** — the full set of rulesets, edges, and conditional branches.
+
+#### 7b) Query Live Orchestration Events
+
+Fetch all orchestration events for the entity:
+```
+event.list({
+  "context.entityRef": "<ENTITY_REF>",
+  "context.entityType": "<ENTITY_TYPE>",
+  "eventType": "ORCHESTRATION_AUDIT",
+  "count": 200
+})
+```
+
+Also collect business orchestration events for name-level matching:
+```
+event.list({
+  "context.entityRef": "<ENTITY_REF>",
+  "context.entityType": "<ENTITY_TYPE>",
+  "eventType": "ORCHESTRATION",
+  "count": 200
+})
+```
+
+If more than 200 events exist, paginate using `start` offset until all events are collected for both queries.
+
+For each returned event, extract:
+- `name` — the event/ruleset name that fired
+- `status` — event status (SUCCESS, FAILED, etc.)
+- `createdOn` — timestamp for timing analysis
+- `entityId`, `entityRef`, `entityType` — confirm entity scope
+- `attributes` — any rule-specific attributes (subtype, status transitions)
+- `category` — especially `ruleSet`, `rule`, `ACTION`, `exception` from `ORCHESTRATION_AUDIT`
+
+#### 7c) Cross-Entity Event Tracing
+
+For entity types that spawn or interact with child entities, also query child events:
+
+- **ORDER** entities: query events for related fulfilment choices and fulfilments:
+  ```
+  event.list({
+    "context.rootEntityRef": "<ORDER_REF>",
+    "context.rootEntityType": "ORDER",
+    "context.entityType": "FULFILMENT_CHOICE",
+    "eventType": "ORCHESTRATION",
+    "count": 200
+  })
+  ```
+  Repeat for `context.entityType: "FULFILMENT"`.
+
+- **FULFILMENT** entities: query events for the parent order:
+  ```
+  event.list({
+    "context.entityRef": "<FULFILMENT_REF>",
+    "context.entityType": "FULFILMENT",
+    "eventType": "ORCHESTRATION",
+    "count": 200
+  })
+  ```
+  Also query any articles linked to the fulfilment.
+
+Collect all cross-entity events into a separate list for cross-entity edge validation.
+
+#### 7d) Map Actual Events to Expected Rulesets
+
+For each ruleset in the expected connection graph:
+
+1. **Direct match**: Check if an ORCHESTRATION event with the same `name` as the ruleset name exists in the collected events. If found, mark as **MATCHED**.
+2. **Conditional branch check**: If the ruleset has a `subtype` filter (e.g. `HD_WH` only), check whether the entity's actual subtype matches. If the subtype does not match, mark as **SKIPPED (subtype mismatch: entity is <actual>, ruleset requires <expected>)**.
+3. **Gate ruleset check**: For gate-pattern rulesets (e.g. `SendEventOnVerifyingAllFulfilmentStates`), check if the gate event was emitted by looking for the gate's `eventName` in the event list. If the gate condition was not met, mark as **SKIPPED (gate condition not met)**.
+4. **Cross-entity event check**: For rulesets that emit cross-entity events (via `SendEventForOrder`, `SendEventForAllFulfilmentChoices`, `SendEventForAllFulfilments`), verify the target event appears in the cross-entity event list. If found, mark as **MATCHED (cross-entity)**. If not found, mark as **SKIPPED (cross-entity event not propagated)**.
+5. **Status precondition check**: If a ruleset triggers on a specific status and the entity never reached that status (based on observed SetState transitions), mark as **SKIPPED (status <STATUS> never reached)**.
+
+For each observed event that does NOT correspond to any expected ruleset, mark as **UNEXPECTED**.
+
+#### 7e) Timing Analysis
+
+Sort all matched events by `createdOn` timestamp and compute:
+- **Duration between consecutive events**: time from one ruleset completion to the next
+- **Total execution span**: time from first event to last event
+- **Slowest transition**: the largest gap between consecutive events (potential bottleneck)
+- **Gate wait time**: for gate rulesets, time between the last contributing child event and the gate event firing
+
+Flag any gap exceeding 5 seconds as a potential delay indicator.
+
+#### 7f) Produce Validate Report
+
+Generate the report with these sections:
+
+**Expected Path vs Actual Path Table:**
+```
+| Ruleset | Flow Type | Expected | Observed | Status | Evidence |
+|---------|-----------|----------|----------|--------|----------|
+| CREATE | CREATE | yes | yes | MATCHED | evt-001 |
+| ValidateOrder | INTERNAL_EVENT | yes | yes | MATCHED | evt-002 |
+| ConfirmValidation | INTEGRATION_EVENT | yes | yes | MATCHED | evt-003 |
+| RequestShipment | INTERNAL_EVENT | yes | no | SKIPPED | subtype mismatch: entity is CC, ruleset requires HD_WH |
+| ReadyForPickup | INTERNAL_EVENT | yes | yes | MATCHED | evt-004 |
+| UnknownExternalEvt | - | no | yes | UNEXPECTED | evt-099 |
+```
+
+**Summary Counts:**
+```
+MATCHED: <N> rulesets executed as expected
+SKIPPED: <N> rulesets not executed (with reasons)
+UNEXPECTED: <N> events observed but not in expected path
+```
+
+**Skipped Rulesets Detail:**
+For each SKIPPED ruleset, explain the skip reason:
+- `subtype mismatch` — entity subtype does not match ruleset filter
+- `status never reached` — prerequisite status was never set
+- `gate condition not met` — gate ruleset waiting on child entities that are not all in required state
+- `cross-entity event not propagated` — expected cross-entity event was not observed on child/parent
+- `conditional guard` — rule-level guard/attribute condition not satisfied
+
+**Conditional Branch Report:**
+```
+Branch Point: <ruleset with multiple outgoing conditional edges>
+  Taken: <branch that was observed> (subtype: HD_WH)
+  Not taken: <branch not observed> (subtype: CC_PFS) — SKIPPED
+```
+
+**Timing Analysis:**
+```
+| From | To | Duration | Flag |
+|------|----|----------|------|
+| CREATE | ValidateOrder | 120ms | |
+| ValidateOrder | ConfirmValidation | 45200ms | SLOW (>5s) |
+| ConfirmValidation | ReadyForPickup | 340ms | |
+Total span: 45.66s | Slowest: ValidateOrder -> ConfirmValidation (45.2s)
+```
+
+**Cross-Entity Propagation:**
+```
+| Source Entity | Event Emitted | Target Entity Type | Target Event | Status |
+|--------------|---------------|--------------------|--------------|--------|
+| ORDER:ORD-001 | NotifyFCComplete | FULFILMENT_CHOICE | RouteFulfilmentChoice | MATCHED |
+| ORDER:ORD-001 | CancelFulfilment | FULFILMENT | CancelFulfilment | NOT FOUND |
+```
+
+When `--output <path>` is specified, write the full report to the given file. When `--mermaid` is also enabled, annotate the connection graph diagram with color-coded edges: green for MATCHED, grey for SKIPPED, red for UNEXPECTED.
+
+#### 7g) Runtime Settings Conformance (required in validate mode)
+
+In `--validate` mode, always add a settings conformance section:
+
+1. Reuse extracted setting refs from Step 5 (webhook + non-webhook settings).
+2. Query live settings for each key using **cascading scope resolution**:
+   - First: `RETAILER` (contextId = retailer id)
+   - Then: `ACCOUNT` (contextId = 0)
+   - Use the first scope where the setting is found.
+   Record which scope the setting was found at — this is important for the conformance table.
+3. Evaluate status:
+   - `FOUND`
+   - `MISSING`
+   - `EMPTY`
+   - `INVALID_FORMAT` (for example webhook JSON without `url`)
+   - `CONTRACT_MISMATCH` (exists but runtime evidence suggests wrong value; for example webhook request endpoint differs from configured setting URL)
+4. If `ORCHESTRATION_AUDIT` contains webhook action evidence, compare:
+   - configured webhook URL from setting
+   - observed `Request Endpoint` in audit attributes
+   and emit mismatch findings.
+
+Settings conformance table:
+```
+| Setting | Referenced By | Runtime Status | Evidence |
+|---------|----------------|----------------|----------|
+| webhook.order.created | ORDER.CREATE | FOUND | setting id=... |
+| webhook.carrier.shipment.request | FULFILMENT.RequestShipment | CONTRACT_MISMATCH | configured=https://x, observed=https://y |
+| update.fulfilment.confirmPick | FULFILMENT.ConfirmPick | MISSING | no settings edge |
+```
+
+## Output Template
+
+```text
+=== Connection Analysis: <WORKFLOW_NAME> ===
+
+Topology:
+  Internal edges: <N>
+  Cross-entity edges: <N>
+  Cross-workflow edges: <N>
+
+Findings:
+  [CRITICAL|HIGH|MEDIUM] <finding>
+
+Process Flow Classification:
+  <Ruleset> -> <FlowType>
+
+Webhook/Setting Dependencies:
+  <Ruleset> -> webhook:<keys> setting:<keys>
+```
+
+## Decision Rules
+
+- If the user needs full state machine quality checks -> include `/fluent-workflow-analyzer`.
+- If gaps are found and user asks for fixes -> switch to `/fluent-workflow-builder`.
+- If runtime behavior differs from static analysis -> pivot to `/fluent-trace`.
+