@fluentcommerce/ai-skills 0.1.0 → 0.3.0

package/content/dev/skills/fluent-session-audit-export/SKILL.md

@@ -1,632 +1,880 @@
----
-name: fluent-session-audit-export
-description: Export a structured JSON audit trail of all session changes. Covers code modifications, Fluent environment mutations, events sent, deployments, and compliance metadata. Machine-readable companion to /fluent-session-summary. Triggers on "export audit", "session audit", "audit trail", "export changes", "compliance report".
-user-invocable: true
-allowed-tools: Bash, Read, Write, Glob, Grep
-argument-hint: [--format json|jsonl] [--output <path>] [--include-readonly]
----
-
-# Session Audit Export
-
-Export the session's complete change history as a structured JSON document. Captures code changes, Fluent environment mutations, events sent, deployments, test results, and compliance metadata in a machine-readable format.
-
-## Purpose
-
-This skill produces the **machine-readable audit trail** for the ADD Feedback Loop (Phase 7) and compliance reporting. Every write operation performed during a session is captured as a typed change record with full provenance: which tool was called, which skill invoked it, what the previous and new state was, and whether the action is reversible.
-
-The JSON output is designed for consumption by CI/CD pipelines, audit systems, Jira integrations, Confluence deployment records, and the ADD feedback loop's scope-completion measurement.
-
-## Ownership Boundary
-
-This skill owns the **JSON export format** and the serialization of tracked changes into the audit document schema.
-
-It does NOT own the tracking itself. The running change log is a cross-cutting concern shared with `/fluent-session-summary`. Both skills read the same underlying tracking data maintained by the agent throughout the session. This skill never maintains a separate tracking log.
-
-Related skills:
-- Human-readable session report -> `/fluent-session-summary`
-- Scope document and task tracking -> `/fluent-scope-decompose`
-- Pre-deploy gate results -> `/fluent-pre-deploy-check`
-- Version lifecycle -> `/fluent-version-manage`
-
-## When to Use
-
-- **End of session** -- export a complete record of everything that was changed
-- **CI/CD integration** -- produce a gate artifact that downstream pipelines can parse
-- **Compliance reporting** -- generate traceability from user stories to deployed changes
-- **ADD feedback loop** -- measure scope completion (tasks completed vs total)
-- **Post-incident review** -- reconstruct exactly what was deployed and when
-- **Handover documentation** -- provide the next engineer with a precise change manifest
-
-## Relationship to `/fluent-session-summary`
-
-| Aspect | `/fluent-session-summary` | `/fluent-session-audit-export` |
-|--------|--------------------------|-------------------------------|
-| Format | Human-readable Markdown tables | Machine-readable JSON / JSONL |
-| Audience | Developer reviewing session in terminal | CI/CD pipelines, audit systems, feedback loops |
-| Detail level | Grouped summary tables with counts | Per-operation records with full metadata |
-| Compliance | Flags irreversible actions in prose | Story-to-change traceability matrix, pre-deploy checklist cross-ref |
-| Rollback info | Lists irreversible actions prominently | Includes concrete rollback command strings per change |
-| Previous/new values | Key fields noted in "Details" column | Structured `previousValue` / `newValue` fields |
-| Tool attribution | Not included | MCP tool name and skill name per change |
-| Invocation | `/fluent-session-summary show` | `/fluent-session-audit-export` |
-| Data source | Shared tracking log | Same shared tracking log |
-
-Both skills consume the same underlying change tracking data. They MUST NOT maintain separate tracking logs. The audit export reads the same data that session-summary presents, then serializes it into the structured schema below.
-
-## Inputs
-
-| Parameter | Required | Default | Description |
-|-----------|----------|---------|-------------|
-| `--format` | No | `json` | Output format: `json` (single document) or `jsonl` (one change record per line) |
-| `--output` | No | Auto-generated path | Output file path. Default: `accounts/<PROFILE>/analysis/session-audit/<sessionId>.audit.json` |
-| `--include-readonly` | No | `false` | Include read-only operations (queries, downloads, introspection). By default only write operations are tracked. |
-| `--profile` | No | Active profile | Profile context for the audit. Determines the output directory. |
-
-## Audit Document JSON Schema
-
-The complete schema for the exported JSON document. Every field, type, and enum value is specified.
-
-### Top-Level Structure
-
-```json
-{
-  "$schema": "fluent-session-audit/v1",
-  "sessionId": "string (UUID v4)",
-  "startedAt": "string (ISO-8601 timestamp of first tracked change)",
-  "endedAt": "string (ISO-8601 timestamp of last tracked change)",
-  "context": {
-    "profile": "string (Fluent CLI profile name, e.g. HMDEV)",
-    "account": "string (API base URL, e.g. hmdev.sandbox.api.fluentretail.com)",
-    "retailer": {
-      "ref": "string (retailer reference, e.g. HM_TEST)",
-      "id": "number (retailer ID, e.g. 5)"
-    },
-    "user": "string (authenticated username, e.g. admin@hmdev)",
-    "agentModel": "string (AI model identifier, e.g. claude-opus-4-6)"
-  },
-  "summary": {
-    "codeChanges": "number (total CODE category changes)",
-    "environmentMutations": "number (total ENVIRONMENT category changes)",
-    "eventsSent": "number (total EVENT actions)",
-    "deploymentsCompleted": "number (total DEPLOY actions)",
-    "testsRun": "number (total TEST category changes)",
-    "testsPassed": "number (tests with result=PASS)",
-    "testsFailed": "number (tests with result=FAIL)",
-    "irreversibleActions": "number (changes where reversible=false)"
-  },
-  "changes": ["array of Change objects (see below)"],
-  "compliance": {
-    "scopeDocumentRef": "string|null (path to scope document if available)",
-    "tasksCompleted": "number (completed tasks from scope decomposition)",
-    "tasksTotal": "number (total tasks from scope decomposition)",
-    "traceability": {
-      "<storyRef>": {
-        "tasks": ["array of task IDs (e.g. T-001, T-002)"],
-        "status": "string (complete|partial|not_started)",
-        "changes": ["array of seq numbers from the changes array"]
-      }
-    },
-    "preDeployChecklist": "string|null (path to pre-deploy checklist JSON if available)",
-    "irreversibleActions": [
-      {
-        "seq": "number (references changes[].seq)",
-        "description": "string (human-readable explanation)",
-        "risk": "string (LOW|MEDIUM|HIGH|CRITICAL)"
-      }
-    ]
-  }
-}
-```
-
-### Change Object Schema
-
-Each entry in the `changes` array has this structure:
-
-```json
-{
-  "seq": "number (1-based sequential identifier, monotonically increasing)",
-  "timestamp": "string (ISO-8601 timestamp of when the change was made)",
-  "category": "string (CODE|ENVIRONMENT|TEST|CONFIG)",
-  "action": "string (depends on category, see table below)",
-  "target": {
-    "type": "string (depends on category and action, see table below)",
-    "...additional fields depending on type"
-  },
-  "details": "string (human-readable description of the change)",
-  "reversible": "boolean (true if the change can be undone)",
-  "rollbackCommand": "string|undefined (concrete command to reverse the change, only when reversible=true and a command is known)",
-  "outcome": "string|undefined (SUCCESS|FAILED|NO_MATCH|PENDING -- for events and mutations)",
-  "previousValue": "any|undefined (previous state, for mutations and setting updates)",
-  "newValue": "any|undefined (new state, for mutations and setting updates)",
-  "diff": {
-    "linesAdded": "number",
-    "linesRemoved": "number"
-  },
-  "result": "string|undefined (PASS|FAIL -- for TEST category)",
-  "tool": "string|undefined (MCP tool name, e.g. event.send, entity.update, graphql.query)",
-  "skill": "string|undefined (skill that triggered this change, e.g. fluent-e2e-test)",
-  "storyRef": "string|undefined (user story identifier, e.g. US-301)"
-}
-```
-
-Note: Fields marked `|undefined` are only present when applicable to the specific change type. The `diff` object is only present for CODE MODIFY actions.
-
-### Target Object Shapes by Category
-
-**CODE targets:**
-
-| Action | target.type | Additional target fields |
-|--------|-------------|------------------------|
-| `CREATE` | `file` | `path` (string -- absolute file path) |
-| `MODIFY` | `file` | `path` (string -- absolute file path) |
-| `DELETE` | `file` | `path` (string -- absolute file path) |
-| `COMMIT` | `git` | `repo` (string), `branch` (string), `hash` (string -- short commit hash) |
-| `PUSH` | `git` | `repo` (string), `branch` (string), `remote` (string -- e.g. origin) |
-
-**ENVIRONMENT targets:**
-
-| Action | target.type | Additional target fields |
-|--------|-------------|------------------------|
-| `MUTATION` | `entity` | `entityType` (string -- ORDER, FULFILMENT, LOCATION, etc.), `entityRef` (string), `entityId` (string\|number), `fields` (string[] -- which fields were changed) |
-| `DEPLOY` | `module` | `name` (string), `version` (string), `retailer` (string) |
-| `DEPLOY` | `workflow` | `name` (string -- e.g. ORDER::HD), `version` (number), `retailer` (string) |
-| `EVENT` | `event` | `eventName` (string), `entityType` (string), `entityRef` (string), `mode` (string -- async\|sync) |
-| `BATCH` | `batch` | `jobName` (string), `jobId` (string), `entityType` (string), `recordCount` (number) |
-
-**TEST targets:**
-
-| Action | target.type | Additional target fields |
-|--------|-------------|------------------------|
-| `ASSERT` | `assertion` | `entityType` (string), `entityRef` (string), `expectedStatus` (string), `actualStatus` (string) |
-| `BUILD` | `build` | `command` (string -- e.g. mvn clean install), `exitCode` (number), `testCount` (number), `failureCount` (number) |
-| `VALIDATE` | `validation` | `validationType` (string -- module\|workflow\|environment), `target` (string -- what was validated) |
-
-**CONFIG targets:**
-
-| Action | target.type | Additional target fields |
-|--------|-------------|------------------------|
-| `SETTING_CREATE` | `setting` | `key` (string), `context` (string -- RETAILER\|ACCOUNT\|LOCATION), `contextId` (number) |
-| `SETTING_UPDATE` | `setting` | `key` (string), `context` (string), `contextId` (number) |
-
-### Action Enum Values by Category
-
-| Category | Valid Actions |
-|----------|-------------|
-| `CODE` | `CREATE`, `MODIFY`, `DELETE`, `COMMIT`, `PUSH` |
-| `ENVIRONMENT` | `MUTATION`, `DEPLOY`, `EVENT`, `BATCH` |
-| `TEST` | `ASSERT`, `BUILD`, `VALIDATE` |
-| `CONFIG` | `SETTING_CREATE`, `SETTING_UPDATE` |
-
-## Change Categories
-
-What falls under each category:
-
-| Category | Source Operations | Tracked From |
-|----------|-----------------|-------------|
-| `CODE` | File creates/edits/deletes, git commits, git pushes, workflow JSON edits, rule class scaffolding | File system operations via Write/Edit tools, git commands via Bash |
-| `ENVIRONMENT` | GraphQL mutations, entity CRUD, event sends, workflow uploads, module deploys, batch job creates/sends | MCP tool calls: `graphql.query` (mutations), `entity.create`, `entity.update`, `event.send`, `workflow.upload`, `batch.create`, `batch.send`, `graphql.batchMutate` |
-| `TEST` | Assertions on entity state, build results, module/workflow validation | MCP tool calls: `test.assert`, Bash `mvn` commands, `environment.validate` |
-| `CONFIG` | Setting creates and updates | MCP tool calls: `setting.upsert`, `setting.bulkUpsert` |
-
-## Capture Mechanism
-
-The audit trail is built from the same tracking protocol used by `/fluent-session-summary`. The agent maintains a running log of write operations throughout the session. Both skills read from this same log.
-
-```
-1. DURING THE SESSION:
-   - After each write operation (mutation, event send, deploy, file edit, commit),
-     the agent appends it to the running change log
-   - This is the same protocol described in /fluent-session-summary
-   - Read-only operations (queries, downloads, introspection) are NOT logged
-     unless --include-readonly is specified
-
-2. ON /fluent-session-audit-export INVOCATION:
-   a. Compile all tracked changes into the JSON schema
-   b. For each ENVIRONMENT change, capture:
-      - MCP tool name used (e.g. event.send, entity.update)
-      - Response status (ok/error mapped to outcome)
-      - Previous vs new state where available
-   c. For each CODE change:
-      - Absolute file path
-      - Action type (CREATE/MODIFY/DELETE)
-      - Line count delta (if available)
-      - Associated skill name
-   d. For each TEST change:
-      - Assertion details and PASS/FAIL result
-      - Build results with test counts
-   e. For each CONFIG change:
-      - Setting key, context, contextId
-      - Previous and new values
-   f. Add compliance section if scope document is available
-   g. Assign sequential seq numbers (1-based, monotonically increasing)
-   h. Compute summary counts
-
-3. WRITE to output path:
-   Default: accounts/<PROFILE>/analysis/session-audit/<sessionId>.audit.json
-   Or: user-specified --output path
-
-4. REPORT: Print the output file path and summary counts to the terminal
-```
-
-## Sensitive Value Redaction
-
-Certain values MUST be redacted before writing the audit document:
-
-**Always redact (replace with `"[REDACTED]"`):**
-- Access tokens and bearer tokens
-- Passwords and client secrets
-- API keys
-- PII: customer email addresses, phone numbers, full names in entity attributes
-- Setting values containing `password`, `secret`, `token`, `key` in the setting name
-
-**Never redact (keep as-is):**
-- Entity refs, IDs, and statuses
-- Event names and entity types
-- File paths
-- Version numbers
-- Workflow names and ruleset names
-- Setting keys (the name itself, not secret values)
-- Retailer refs and IDs
-- User story references
-- Git commit hashes and branch names
-
-## Rollback Commands
-
-For each reversible change, include a concrete `rollbackCommand` string when one can be determined:
-
-| Action | Rollback Command Pattern |
-|--------|------------------------|
-| `DEPLOY` (module) | `fluent module install -p <PROFILE> -r <RETAILER> -m <module-name>:<previousVersion>` |
-| `DEPLOY` (workflow) | Re-upload the previous version workflow JSON via `workflow.upload` |
-| `MUTATION` (entity status) | `entity.update({ entityType, id, fields: { status: "<previousValue>" } })` |
-| `SETTING_CREATE` | Delete the setting (note: no MCP tool for this; manual via GraphQL) |
-| `SETTING_UPDATE` | `setting.upsert({ name, value: "<previousValue>", context, contextId })` |
-| `COMMIT` | `git revert <hash>` |
-| `PUSH` | `git push origin <branch> --force` (flag as destructive) |
-| `EVENT` | Not reversible -- events cannot be un-sent |
-| `BATCH` | Not reversible -- batch records are processed |
-| `CODE CREATE` | `rm <path>` or `git checkout -- <path>` |
-| `CODE MODIFY` | `git checkout -- <path>` |
-
-Changes with `reversible: false` do not have a `rollbackCommand` field.
-
-## Output Paths
-
-Default output location follows the accounts directory convention:
-
-```
-accounts/<PROFILE>/analysis/session-audit/<sessionId>.audit.json
-```
-
-When `--output` is specified, write to that path instead.
-
-If the output directory does not exist, create it.
-
-## JSONL Format Option
-
-When `--format jsonl` is specified, output one JSON object per line instead of a single document:
-
-```
-Line 1: {"$schema":"fluent-session-audit/v1","sessionId":"...","startedAt":"...","endedAt":"...","context":{...},"summary":{...},"compliance":{...}}
-Line 2: {"seq":1,"timestamp":"...","category":"CODE","action":"CREATE","target":{...},...}
-Line 3: {"seq":2,"timestamp":"...","category":"CODE","action":"MODIFY","target":{...},...}
-...
-```
-
-The first line is the session metadata (everything except the `changes` array). Each subsequent line is one change record. This format supports streaming consumption and line-by-line processing by CI/CD tools.
-
-The file extension for JSONL output is `.audit.jsonl`.
-
-## External System Mapping
-
-The audit JSON is designed for consumption by external systems:
-
-| System | Field Mapping | Consumption Pattern |
-|--------|--------------|-------------------|
-| **Jira** | `changes[].storyRef` maps to Jira issue keys (e.g. US-301 -> PROJ-301) | Create work log entries from changes; update story status based on `compliance.traceability[].status` |
-| **Confluence** | Full audit document | Generate deployment record pages; attach as artifact to release pages |
-| **CI/CD** | `compliance.irreversibleActions`, `summary.testsFailed` | Parse audit as deployment gate artifact; fail pipeline if irreversible action count exceeds threshold or tests failed |
-| **Git** | `changes[].target` where `target.type == "git"` | Cross-reference COMMIT entries with PR metadata; verify all commits are in a merged PR |
-| **ADD Feedback Loop** | `compliance.tasksCompleted` / `compliance.tasksTotal` | Measure scope completion percentage; track velocity across sessions |
-
-## Edge Cases
-
-- **No changes made:** Output a valid audit document with an empty `changes` array and all summary counts at 0. Set `startedAt` and `endedAt` to the current timestamp.
-- **Multi-retailer sessions:** If the session spans multiple profiles or retailers, produce one audit document per profile/retailer combination. Each document's `context` reflects its specific target.
-- **Failed writes:** Track with `outcome: "FAILED"` in the change record. Failed operations are still part of the audit trail -- they represent attempted changes.
-- **Dry-run operations:** `event.send` with `dryRun: true`, `entity.create` with `dryRun: true`, and `workflow.upload` with `dryRun: true` are NOT tracked. Dry runs do not change state.
-- **Partial sessions:** If the agent session ends abnormally (timeout, error), the audit captures everything tracked up to that point. The `endedAt` reflects the last tracked change, not the session end.
-- **No scope document:** If no scope decomposition was run, set `compliance.scopeDocumentRef` to `null`, `tasksCompleted` and `tasksTotal` to 0, and `traceability` to an empty object.
-- **No pre-deploy checklist:** If no pre-deploy check was run, set `compliance.preDeployChecklist` to `null`.
-- **Setting bulk upserts:** Each individual setting in a `setting.bulkUpsert` call is tracked as a separate CONFIG change record.
-
-## Integration with `/fluent-session-summary`
-
-Both skills share the same tracking protocol and read the same data:
-
-| Concern | Implementation |
-|---------|---------------|
-| Tracking log | Single running log maintained by the agent during the session |
-| Data ownership | Neither skill owns the log -- it is a cross-cutting concern |
-| Invocation independence | Either skill can be invoked without the other |
-| Consistent counts | Both skills must produce the same counts for the same data |
-| Ordering | Both skills order changes chronologically by timestamp |
-
-When both are invoked in the same session, the text summary from `/fluent-session-summary` and the JSON from `/fluent-session-audit-export` represent the same underlying changes. Any discrepancy is a bug.
-
-## Full Example Audit Document
-
-This example shows a realistic session that scaffolds a rule, configures settings, deploys a module and workflow, runs an E2E test, and commits the code.
-
-```json
-{
-  "$schema": "fluent-session-audit/v1",
-  "sessionId": "a3f1c9e2-7b4d-4e8a-9f12-d6c3a8b5e7f1",
-  "startedAt": "2026-02-23T09:00:12Z",
-  "endedAt": "2026-02-23T11:42:08Z",
-  "context": {
-    "profile": "HMDEV",
-    "account": "hmdev.sandbox.api.fluentretail.com",
-    "retailer": {
-      "ref": "HM_TEST",
-      "id": 5
-    },
-    "user": "admin@hmdev",
-    "agentModel": "claude-opus-4-6"
-  },
-  "summary": {
-    "codeChanges": 4,
-    "environmentMutations": 3,
-    "eventsSent": 2,
-    "deploymentsCompleted": 2,
-    "testsRun": 2,
-    "testsPassed": 2,
-    "testsFailed": 0,
-    "irreversibleActions": 2
-  },
-  "changes": [
-    {
-      "seq": 1,
-      "timestamp": "2026-02-23T09:00:12Z",
-      "category": "CODE",
-      "action": "CREATE",
-      "target": {
-        "type": "file",
-        "path": "accounts/HMDEV/SOURCE/fluentcommerce-fc-module-hm-extensions/plugins/rules/hm-extensions/src/main/java/com/fluentcommerce/hm/CancelOrderRule.java"
-      },
-      "details": "New rule class: CancelOrderRule implementing order cancellation logic",
-      "reversible": true,
-      "rollbackCommand": "rm accounts/HMDEV/SOURCE/fluentcommerce-fc-module-hm-extensions/plugins/rules/hm-extensions/src/main/java/com/fluentcommerce/hm/CancelOrderRule.java",
-      "skill": "fluent-rule-scaffold",
-      "storyRef": "US-301"
-    },
-    {
-      "seq": 2,
-      "timestamp": "2026-02-23T09:05:33Z",
-      "category": "CODE",
-      "action": "MODIFY",
-      "target": {
-        "type": "file",
-        "path": "accounts/HMDEV/SOURCE/fluentcommerce-fc-module-hm-extensions/resources/module.json"
-      },
-      "details": "Registered CancelOrderRule in provides[] array",
-      "diff": {
-        "linesAdded": 8,
-        "linesRemoved": 0
-      },
-      "reversible": true,
-      "rollbackCommand": "git checkout -- accounts/HMDEV/SOURCE/fluentcommerce-fc-module-hm-extensions/resources/module.json",
-      "skill": "fluent-rule-scaffold",
-      "storyRef": "US-301"
-    },
-    {
-      "seq": 3,
-      "timestamp": "2026-02-23T09:12:45Z",
-      "category": "CONFIG",
-      "action": "SETTING_CREATE",
-      "target": {
-        "type": "setting",
-        "key": "WEBHOOK_CANCEL_ORDER_URL",
-        "context": "RETAILER",
-        "contextId": 5
-      },
-      "details": "Created webhook setting for order cancellation notifications",
-      "previousValue": null,
-      "newValue": "https://webhook.site/abc123-def456",
-      "reversible": true,
-      "rollbackCommand": "Delete setting WEBHOOK_CANCEL_ORDER_URL via GraphQL mutation deleteSetting",
-      "tool": "setting.upsert",
-      "skill": "fluent-settings"
-    },
-    {
-      "seq": 4,
-      "timestamp": "2026-02-23T09:45:18Z",
-      "category": "TEST",
-      "action": "BUILD",
-      "target": {
-        "type": "build",
-        "command": "mvn clean install -f accounts/HMDEV/SOURCE/fluentcommerce-fc-module-hm-extensions/plugins/pom.xml",
-        "exitCode": 0,
-        "testCount": 42,
-        "failureCount": 0
-      },
-      "details": "Maven build: 42 tests passed, 0 failures",
-      "result": "PASS",
-      "skill": "fluent-build"
-    },
-    {
-      "seq": 5,
-      "timestamp": "2026-02-23T10:02:07Z",
-      "category": "ENVIRONMENT",
-      "action": "DEPLOY",
-      "target": {
-        "type": "module",
-        "name": "fc-module-hm-extensions",
-        "version": "1.3.0",
-        "retailer": "HM_TEST"
-      },
-      "details": "Module deployed via fluent module install",
-      "previousVersion": "1.2.3",
-      "reversible": true,
-      "rollbackCommand": "fluent module install -p HMDEV -r HM_TEST -m fc-module-hm-extensions:1.2.3",
-      "skill": "fluent-module-deploy"
-    },
-    {
-      "seq": 6,
-      "timestamp": "2026-02-23T10:08:34Z",
-      "category": "ENVIRONMENT",
-      "action": "DEPLOY",
-      "target": {
-        "type": "workflow",
-        "name": "ORDER::HD",
-        "version": 14,
-        "retailer": "HM_TEST"
-      },
-      "details": "Workflow uploaded with new CancelOrder ruleset added",
-      "previousVersion": 13,
-      "reversible": true,
-      "rollbackCommand": "Re-upload ORDER::HD version 13 JSON via workflow.upload",
-      "tool": "workflow.upload",
-      "skill": "fluent-workflow-builder"
-    },
-    {
-      "seq": 7,
-      "timestamp": "2026-02-23T10:15:50Z",
-      "category": "ENVIRONMENT",
-      "action": "EVENT",
-      "target": {
-        "type": "event",
-        "eventName": "CreateOrder",
-        "entityType": "ORDER",
-        "entityRef": "HD_TEST_20260223_001",
-        "mode": "async"
-      },
-      "details": "E2E test: created test order via CreateOrder event",
-      "outcome": "SUCCESS",
-      "reversible": false,
-      "tool": "event.send",
-      "skill": "fluent-e2e-test"
-    },
-    {
-      "seq": 8,
-      "timestamp": "2026-02-23T10:16:22Z",
-      "category": "TEST",
-      "action": "ASSERT",
-      "target": {
-        "type": "assertion",
-        "entityType": "ORDER",
-        "entityRef": "HD_TEST_20260223_001",
-        "expectedStatus": "BOOKED",
-        "actualStatus": "BOOKED"
-      },
-      "details": "Assert order status=BOOKED after ConfirmValidation cascade",
-      "result": "PASS",
-      "tool": "test.assert",
-      "skill": "fluent-e2e-test"
-    },
-    {
-      "seq": 9,
-      "timestamp": "2026-02-23T10:22:11Z",
-      "category": "ENVIRONMENT",
-      "action": "EVENT",
-      "target": {
-        "type": "event",
-        "eventName": "CancelOrder",
-        "entityType": "ORDER",
-        "entityRef": "HD_TEST_20260223_001",
-        "mode": "async"
-      },
-      "details": "E2E test: cancelled test order via CancelOrder event",
-      "outcome": "SUCCESS",
-      "reversible": false,
-      "tool": "event.send",
-      "skill": "fluent-e2e-test"
-    },
-    {
-      "seq": 10,
-      "timestamp": "2026-02-23T10:22:45Z",
-      "category": "ENVIRONMENT",
-      "action": "MUTATION",
-      "target": {
-        "type": "entity",
-        "entityType": "ORDER",
-        "entityRef": "HD_TEST_20260223_001",
-        "entityId": "48291",
-        "fields": ["status"]
-      },
-      "details": "Order status confirmed CANCELLED via workflow processing",
-      "previousValue": "BOOKED",
-      "newValue": "CANCELLED",
-      "outcome": "SUCCESS",
-      "reversible": false,
-      "tool": "graphql.query",
-      "skill": "fluent-e2e-test"
-    },
-    {
-      "seq": 11,
-      "timestamp": "2026-02-23T11:40:30Z",
-      "category": "CODE",
-      "action": "COMMIT",
-      "target": {
-        "type": "git",
-        "repo": "fluentcommerce-fc-module-hm-extensions",
-        "branch": "feature/cancel-order",
-        "hash": "a1b2c3d"
-      },
-      "details": "feat: add cancel order rule and workflow support",
-      "reversible": true,
-      "rollbackCommand": "git revert a1b2c3d"
-    },
-    {
-      "seq": 12,
-      "timestamp": "2026-02-23T11:42:08Z",
-      "category": "CODE",
-      "action": "PUSH",
-      "target": {
-        "type": "git",
-        "repo": "fluentcommerce-fc-module-hm-extensions",
-        "branch": "feature/cancel-order",
-        "remote": "origin"
-      },
-      "details": "Pushed feature/cancel-order to origin",
-      "reversible": true,
-      "rollbackCommand": "git push origin feature/cancel-order --force"
-    }
-  ],
-  "compliance": {
-    "scopeDocumentRef": "scope/cancel-order.md",
-    "tasksCompleted": 8,
-    "tasksTotal": 10,
-    "traceability": {
-      "US-301": {
-        "tasks": ["T-001", "T-002", "T-003", "T-004", "T-005"],
-        "status": "complete",
-        "changes": [1, 2, 3, 5, 6]
-      },
-      "US-302": {
-        "tasks": ["T-006", "T-007", "T-008"],
-        "status": "complete",
-        "changes": [7, 8, 9, 10]
-      },
-      "US-303": {
-        "tasks": ["T-009", "T-010"],
-        "status": "not_started",
-        "changes": []
-      }
-    },
-    "preDeployChecklist": "accounts/HMDEV/analysis/pre-deploy/fc-module-hm-extensions-1.3.0.checklist.json",
-    "irreversibleActions": [
-      {
-        "seq": 7,
-        "description": "Event CreateOrder sent to ORDER/HD_TEST_20260223_001 -- cannot be un-sent",
-        "risk": "LOW"
-      },
-      {
-        "seq": 9,
-        "description": "Event CancelOrder sent to ORDER/HD_TEST_20260223_001 -- cannot be un-sent",
-        "risk": "LOW"
-      }
-    ]
-  }
-}
-```
+---
+name: fluent-session-audit-export
+description: Export a structured JSON audit trail of all session changes. Covers code modifications, Fluent environment mutations, events sent, deployments, and compliance metadata. Machine-readable companion to /fluent-session-summary. Triggers on "export audit", "session audit", "audit trail", "export changes", "compliance report".
+user-invocable: true
+allowed-tools: Bash, Read, Write, Glob, Grep
+argument-hint: [--format json|jsonl] [--output <path>] [--include-readonly]
+---
+
+# Session Audit Export
+
+Export the session's complete change history as a structured JSON document. Captures code changes, Fluent environment mutations, events sent, deployments, test results, and compliance metadata in a machine-readable format.
+
+## Purpose
+
+This skill produces the **machine-readable audit trail** for the ADD Feedback Loop (Phase 7) and compliance reporting. Every write operation performed during a session is captured as a typed change record with full provenance: which tool was called, which skill invoked it, what the previous and new state was, and whether the action is reversible.
+
+The JSON output is designed for consumption by CI/CD pipelines, audit systems, Jira integrations, Confluence deployment records, and the ADD feedback loop's scope-completion measurement.
+
+## Ownership Boundary
+
+This skill owns the **JSON export format** and the serialization of tracked changes into the audit document schema.
+
+It does NOT own the tracking itself. The running change log is a cross-cutting concern shared with `/fluent-session-summary`. Both skills read the same underlying tracking data maintained by the agent throughout the session. This skill never maintains a separate tracking log.
+
+Related skills:
+- Human-readable session report -> `/fluent-session-summary`
+- Scope document and task tracking -> `/fluent-scope-decompose`
+- Pre-deploy gate results -> `/fluent-pre-deploy-check`
+- Version lifecycle -> `/fluent-version-manage`
+
+## When to Use
+
+- **End of session** -- export a complete record of everything that was changed
+- **CI/CD integration** -- produce a gate artifact that downstream pipelines can parse
+- **Compliance reporting** -- generate traceability from user stories to deployed changes
+- **ADD feedback loop** -- measure scope completion (tasks completed vs total)
+- **Post-incident review** -- reconstruct exactly what was deployed and when
+- **Handover documentation** -- provide the next engineer with a precise change manifest
+
+## Relationship to `/fluent-session-summary`
+
+| Aspect | `/fluent-session-summary` | `/fluent-session-audit-export` |
+|--------|--------------------------|-------------------------------|
+| Format | Human-readable Markdown tables | Machine-readable JSON / JSONL |
+| Audience | Developer reviewing session in terminal | CI/CD pipelines, audit systems, feedback loops |
+| Detail level | Grouped summary tables with counts | Per-operation records with full metadata |
+| Compliance | Flags irreversible actions in prose | Story-to-change traceability matrix, pre-deploy checklist cross-ref |
+| Rollback info | Lists irreversible actions prominently | Includes concrete rollback command strings per change |
+| Previous/new values | Key fields noted in "Details" column | Structured `previousValue` / `newValue` fields |
+| Tool attribution | Not included | MCP tool name and skill name per change |
+| Invocation | `/fluent-session-summary show` | `/fluent-session-audit-export` |
+| Data source | Shared tracking log | Same shared tracking log |
+
+Both skills consume the same underlying change tracking data. They MUST NOT maintain separate tracking logs. The audit export reads the same data that session-summary presents, then serializes it into the structured schema below.
+
+## Inputs
+
+| Parameter | Required | Default | Description |
+|-----------|----------|---------|-------------|
+| `--format` | No | `json` | Output format: `json` (single document) or `jsonl` (one change record per line) |
+| `--output` | No | Auto-generated path | Output file path. Default: `accounts/<PROFILE>/sessions/<sessionId>.audit.json` |
+| `--include-readonly` | No | `false` | Include read-only operations (queries, downloads, introspection). By default only write operations are tracked. |
+| `--profile` | No | Active profile | Profile context for the audit. Determines the output directory. |
+
+## Audit Document JSON Schema
+
+The complete schema for the exported JSON document. Every field, type, and enum value is specified.
+
+### Top-Level Structure
+
+```json
+{
+  "$schema": "fluent-session-audit/v1",
+  "sessionId": "string (UUID v4)",
+  "startedAt": "string (ISO-8601 timestamp of first tracked change)",
+  "endedAt": "string (ISO-8601 timestamp of last tracked change)",
+  "context": {
+    "profile": "string (Fluent CLI profile name, e.g. <PROFILE>)",
+    "account": "string (API base URL, e.g. <account>.<env>.api.fluentretail.com)",
+    "retailer": {
+      "ref": "string (retailer reference, e.g. <RETAILER_REF>)",
+      "id": "number (retailer ID, e.g. <RETAILER_ID>)"
+    },
+    "user": "string (authenticated username, e.g. <USER_NAME>)",
+    "agentModel": "string (AI model identifier, e.g. <MODEL_NAME>)"
+  },
+  "summary": {
+    "codeChanges": "number (total CODE category changes)",
+    "environmentMutations": "number (total ENVIRONMENT category changes)",
+    "eventsSent": "number (total EVENT actions)",
+    "deploymentsCompleted": "number (total DEPLOY actions)",
+    "testsRun": "number (total TEST category changes)",
+    "testsPassed": "number (tests with result=PASS)",
+    "testsFailed": "number (tests with result=FAIL)",
+    "irreversibleActions": "number (changes where reversible=false)",
+    "skillsInvoked": "number (total unique skills invoked)",
+    "toolCallsWrite": "number (total write tool calls)",
+    "toolCallsRead": "number (total read tool calls, only when --include-readonly)",
+    "decisionTrailEntries": "number (total decision points captured)"
+  },
+  "changes": ["array of Change objects (see below)"],
+  "skillInvocations": ["array of SkillInvocation objects (see below)"],
+  "toolCalls": ["array of ToolCall objects (see below)"],
+  "decisionTrail": ["array of DecisionEntry objects (see below)"],
+  "compliance": {
+    "scopeDocumentRef": "string|null (path to scope document if available)",
+    "tasksCompleted": "number (completed tasks from scope decomposition)",
+    "tasksTotal": "number (total tasks from scope decomposition)",
+    "traceability": {
+      "<storyRef>": {
+        "tasks": ["array of task IDs (e.g. T-001, T-002)"],
+        "status": "string (complete|partial|not_started)",
+        "changes": ["array of seq numbers from the changes array"]
+      }
+    },
+    "preDeployChecklist": "string|null (path to pre-deploy checklist JSON if available)",
+    "irreversibleActions": [
+      {
+        "seq": "number (references changes[].seq)",
+        "description": "string (human-readable explanation)",
+        "risk": "string (LOW|MEDIUM|HIGH|CRITICAL)"
+      }
+    ]
+  }
+}
+```
+
+### Change Object Schema
+
+Each entry in the `changes` array has this structure:
+
+```json
+{
+  "seq": "number (1-based sequential identifier, monotonically increasing)",
+  "timestamp": "string (ISO-8601 timestamp of when the change was made)",
+  "category": "string (CODE|ENVIRONMENT|TEST|CONFIG)",
+  "action": "string (depends on category, see table below)",
+  "target": {
+    "type": "string (depends on category and action, see table below)",
+    "...additional fields depending on type"
+  },
+  "details": "string (human-readable description of the change)",
+  "reversible": "boolean (true if the change can be undone)",
+  "rollbackCommand": "string|undefined (concrete command to reverse the change, only when reversible=true and a command is known)",
+  "outcome": "string|undefined (SUCCESS|FAILED|NO_MATCH|PENDING -- for events and mutations)",
+  "previousValue": "any|undefined (previous state, for mutations and setting updates)",
+  "newValue": "any|undefined (new state, for mutations and setting updates)",
+  "diff": {
+    "linesAdded": "number",
+    "linesRemoved": "number"
+  },
+  "result": "string|undefined (PASS|FAIL -- for TEST category)",
+  "tool": "string|undefined (MCP tool name, e.g. event.send, entity.update, graphql.query)",
+  "skill": "string|undefined (skill that triggered this change, e.g. fluent-e2e-test)",
+  "storyRef": "string|undefined (user story identifier, e.g. <USER_STORY_ID>)"
+}
+```
+
+Note: Fields marked `|undefined` are only present when applicable to the specific change type. The `diff` object is only present for CODE MODIFY actions.
+
+### SkillInvocation Object Schema
+
+Each entry in the `skillInvocations` array tracks one skill invocation during the session:
+
+```json
+{
+  "seq": "number (1-based sequential, separate from changes[].seq)",
+  "timestamp": "string (ISO-8601 when the skill was invoked)",
+  "skill": "string (skill name, e.g. fluent-rule-scaffold)",
+  "arguments": "object (key arguments: profile, retailer, entityType, moduleName, etc. — NOT full file contents)",
+  "gateResult": "string|undefined (PASS|BLOCKED|SKIPPED — pre-flight or planning gate result)",
+  "gateErrorCode": "string|undefined (PLAN_REQUIRED, PREREQ_MISSING, etc. — only when gateResult=BLOCKED)",
+  "outcome": "string (completed|failed|skipped|blocked)",
+  "failureReason": "string|undefined (only when outcome=failed, skipped, or blocked)",
+  "handoffSignal": "string|undefined (exit signal, e.g. '-> READY: ...path', '-> NEXT: /fluent-build')",
+  "triggeredBy": "number|undefined (seq of the skillInvocation that recommended this via -> NEXT:)",
+  "duration": "string|undefined (approximate duration, e.g. '45s', '2m30s')",
+  "changesProduced": "number[] (seq numbers from changes[] array that this skill produced)",
+  "toolCallsProduced": "number[] (seq numbers from toolCalls[] array that this skill triggered)",
+  "nextRecommended": "string|undefined (downstream skill from Handoff section, e.g. fluent-build)"
+}
+```
+
+### ToolCall Object Schema
+
+Each entry in the `toolCalls` array tracks one MCP tool call during the session:
+
+```json
+{
+  "seq": "number (1-based sequential, separate from changes[].seq and skillInvocations[].seq)",
+  "timestamp": "string (ISO-8601 when the tool was called)",
+  "tool": "string (MCP tool name, e.g. event.send, graphql.query, entity.create)",
+  "server": "string (MCP server: fluent-mcp or fluent-mcp-extn)",
+  "isWrite": "boolean (true for mutations/sends/deploys, false for queries/lists/gets)",
+  "target": {
+    "entityType": "string|undefined",
+    "entityRef": "string|undefined",
+    "description": "string (brief description of what was targeted)"
+  },
+  "outcome": "string (ok|error)",
+  "errorCode": "string|undefined (from error envelope: CONFIG_ERROR, AUTH_ERROR, etc. — only when outcome=error)",
+  "dryRun": "boolean (true if called with dryRun=true)",
+  "skill": "string|undefined (skill that triggered this call)"
+}
+```
+
+Note: Read-only tool calls (`isWrite: false`) are only included when `--include-readonly` is specified. Write tool calls and failed calls are always included.
+
+### DecisionEntry Object Schema
+
+Each entry in the `decisionTrail` array captures one explicit execution decision made by the agent:
+
+```json
+{
+  "seq": "number (1-based sequential, separate from changes[].seq, skillInvocations[].seq, and toolCalls[].seq)",
+  "timestamp": "string (ISO-8601 when the decision was recorded)",
+  "trigger": "string (why a decision was needed: user input, gate, failure, mismatch, or handoff)",
+  "options": "string[] (short labels for options considered)",
+  "selected": "string (chosen option)",
+  "rationale": "string (why the selected option was chosen)",
+  "confidence": "string (high|medium|low)",
+  "assumptions": "string[] (assumptions made when selecting the option)",
+  "skill": "string|undefined (skill context where decision occurred)",
+  "triggeredBy": "number|undefined (seq from skillInvocations[] that led to this decision)",
+  "resultingChanges": "number[] (seq values from changes[] produced because of this decision)"
+}
+```
+
+### Target Object Shapes by Category
+
+**CODE targets:**
+
+| Action | target.type | Additional target fields |
+|--------|-------------|------------------------|
+| `CREATE` | `file` | `path` (string -- absolute file path) |
+| `MODIFY` | `file` | `path` (string -- absolute file path) |
+| `DELETE` | `file` | `path` (string -- absolute file path) |
+| `COMMIT` | `git` | `repo` (string), `branch` (string), `hash` (string -- short commit hash) |
+| `PUSH` | `git` | `repo` (string), `branch` (string), `remote` (string -- e.g. origin) |
+
+**ENVIRONMENT targets:**
+
+| Action | target.type | Additional target fields |
+|--------|-------------|------------------------|
+| `MUTATION` | `entity` | `entityType` (string -- ORDER, FULFILMENT, LOCATION, etc.), `entityRef` (string), `entityId` (string\|number), `fields` (string[] -- which fields were changed) |
+| `DEPLOY` | `module` | `name` (string), `version` (string), `retailer` (string) |
+| `DEPLOY` | `workflow` | `name` (string -- e.g. `<WORKFLOW_NAME>`), `version` (number), `retailer` (string) |
+| `EVENT` | `event` | `eventName` (string), `entityType` (string), `entityRef` (string), `mode` (string -- async\|sync) |
+| `BATCH` | `batch` | `jobName` (string), `jobId` (string), `entityType` (string), `recordCount` (number) |
+
+**TEST targets:**
+
+| Action | target.type | Additional target fields |
+|--------|-------------|------------------------|
+| `ASSERT` | `assertion` | `entityType` (string), `entityRef` (string), `expectedStatus` (string), `actualStatus` (string) |
+| `BUILD` | `build` | `command` (string -- e.g. mvn clean install), `exitCode` (number), `testCount` (number), `failureCount` (number) |
+| `VALIDATE` | `validation` | `validationType` (string -- module\|workflow\|environment), `target` (string -- what was validated) |
+
+**CONFIG targets:**
+
+| Action | target.type | Additional target fields |
+|--------|-------------|------------------------|
+| `SETTING_CREATE` | `setting` | `key` (string), `context` (string -- RETAILER\|ACCOUNT\|LOCATION), `contextId` (number) |
+| `SETTING_UPDATE` | `setting` | `key` (string), `context` (string), `contextId` (number) |
+
+### Action Enum Values by Category
+
+| Category | Valid Actions |
+|----------|-------------|
+| `CODE` | `CREATE`, `MODIFY`, `DELETE`, `COMMIT`, `PUSH` |
+| `ENVIRONMENT` | `MUTATION`, `DEPLOY`, `EVENT`, `BATCH` |
+| `TEST` | `ASSERT`, `BUILD`, `VALIDATE` |
+| `CONFIG` | `SETTING_CREATE`, `SETTING_UPDATE` |
+
+## Change Categories
+
+What falls under each category:
+
+| Category | Source Operations | Tracked From |
+|----------|-----------------|-------------|
+| `CODE` | File creates/edits/deletes, git commits, git pushes, workflow JSON edits, rule class scaffolding | File system operations via Write/Edit tools, git commands via Bash |
+| `ENVIRONMENT` | GraphQL mutations, entity CRUD, event sends, workflow uploads, module deploys, batch job creates/sends | MCP tool calls: `graphql.query` (mutations), `entity.create`, `entity.update`, `event.send`, `workflow.upload`, `batch.create`, `batch.send`, `graphql.batchMutate` |
+| `TEST` | Assertions on entity state, build results, module/workflow validation | MCP tool calls: `test.assert`, Bash `mvn` commands, `environment.validate` |
+| `CONFIG` | Setting creates and updates | MCP tool calls: `setting.upsert`, `setting.bulkUpsert` |
+
+## Capture Mechanism
+
+The audit trail is built from the same shared tracking log used by `/fluent-session-summary`. This export serializes that shared log into a machine-readable schema.
+
+### Centralized Instrumentation Contract
+
+> **Canonical definition:** The shared instrumentation contract (`track.skillStart`, `track.toolCall`, `track.decision`, `track.change`, `track.skillEnd`) is defined in `/fluent-session-summary`. This skill consumes the same shared tracker — see that skill for the full API and rules.
+
+### Serialization Steps
+
+```
+1. DURING THE SESSION:
+   - Record write changes into `changes[]`
+   - Record skill lifecycle into `skillInvocations[]`
+   - Record MCP/CLI tool usage into `toolCalls[]`
+   - Record branch choices into `decisionTrail[]`
+   - Read-only tool calls are included only when --include-readonly is enabled
+
+2. ON /fluent-session-audit-export INVOCATION:
+   a. Compile `changes[]`, `skillInvocations[]`, `toolCalls[]`, and `decisionTrail[]`
+   b. Populate compliance metadata (scope, traceability, checklist) when available
+   c. Assign stable 1-based sequence values per array
+   d. Compute summary counts, including decisionTrailEntries
+
+3. WRITE to output path:
+   Default: accounts/<PROFILE>/sessions/<sessionId>.audit.json
+   Or: user-specified --output path
+
+4. REPORT:
+   Print output file path + aggregate counts
+```
+
+## Sensitive Value Redaction
+
+Certain values MUST be redacted before writing the audit document:
+
+**Always redact (replace with `"[REDACTED]"`):**
+- Access tokens and bearer tokens
+- Passwords and client secrets
+- API keys
+- PII: customer email addresses, phone numbers, full names in entity attributes
+- Setting values containing `password`, `secret`, `token`, `key` in the setting name
+
+**Never redact (keep as-is):**
+- Entity refs, IDs, and statuses
+- Event names and entity types
+- File paths
+- Version numbers
+- Workflow names and ruleset names
+- Setting keys (the name itself, not secret values)
+- Retailer refs and IDs
+- User story references
+- Git commit hashes and branch names
+
+## Rollback Commands
+
+For each reversible change, include a concrete `rollbackCommand` string when one can be determined:
+
+| Action | Rollback Command Pattern |
+|--------|------------------------|
+| `DEPLOY` (module) | `fluent module install -p <PROFILE> -r <RETAILER> -m <module-name>:<previousVersion>` |
+| `DEPLOY` (workflow) | Re-upload the previous version workflow JSON via `workflow.upload` |
+| `MUTATION` (entity status) | `entity.update({ entityType, id, fields: { status: "<previousValue>" } })` |
+| `SETTING_CREATE` | Delete the setting (note: no MCP tool for this; manual via GraphQL) |
+| `SETTING_UPDATE` | `setting.upsert({ name, value: "<previousValue>", context, contextId })` |
+| `COMMIT` | `git revert <hash>` |
+| `PUSH` | `git push origin <branch> --force` (flag as destructive) |
+| `EVENT` | Not reversible -- events cannot be un-sent |
+| `BATCH` | Not reversible -- batch records are processed |
+| `CODE CREATE` | `rm <path>` or `git checkout -- <path>` |
+| `CODE MODIFY` | `git checkout -- <path>` |
+
+Changes with `reversible: false` do not have a `rollbackCommand` field.
+
+## Output Paths
+
+Default output location follows the accounts directory convention:
+
+```
+accounts/<PROFILE>/sessions/<sessionId>.audit.json
+```
+
+When `--output` is specified, write to that path instead.
+
+If the output directory does not exist, create it.
+
+## JSONL Format Option
+
+When `--format jsonl` is specified, output one JSON object per line instead of a single document:
+
+```
+Line 1: {"$schema":"fluent-session-audit/v1","sessionId":"...","startedAt":"...","endedAt":"...","context":{...},"summary":{...},"compliance":{...}}
+Line 2: {"seq":1,"timestamp":"...","category":"CODE","action":"CREATE","target":{...},...}
+Line 3: {"seq":2,"timestamp":"...","category":"CODE","action":"MODIFY","target":{...},...}
+...
+```
+
+The first line is the session metadata (everything except the `changes` array). Each subsequent line is one change record. This format supports streaming consumption and line-by-line processing by CI/CD tools.
+
+The file extension for JSONL output is `.audit.jsonl`.
+
+## External System Mapping
+
+The audit JSON is designed for consumption by external systems:
+
+| System | Field Mapping | Consumption Pattern |
+|--------|--------------|-------------------|
+| **Jira** | `changes[].storyRef` maps to Jira issue keys (e.g. `<USER_STORY_ID>` -> `<TRACKER_ISSUE_KEY>`) | Create work log entries from changes; update story status based on `compliance.traceability[].status` |
+| **Confluence** | Full audit document | Generate deployment record pages; attach as artifact to release pages |
+| **CI/CD** | `compliance.irreversibleActions`, `summary.testsFailed` | Parse audit as deployment gate artifact; fail pipeline if irreversible action count exceeds threshold or tests failed |
+| **Git** | `changes[].target` where `target.type == "git"` | Cross-reference COMMIT entries with PR metadata; verify all commits are in a merged PR |
+| **ADD Feedback Loop** | `compliance.tasksCompleted` / `compliance.tasksTotal` | Measure scope completion percentage; track velocity across sessions |
+
+## Edge Cases
+
+- **No changes made:** Output a valid audit document with an empty `changes` array and all summary counts at 0. Set `startedAt` and `endedAt` to the current timestamp.
+- **Multi-retailer sessions:** If the session spans multiple profiles or retailers, produce one audit document per profile/retailer combination. Each document's `context` reflects its specific target.
+- **Failed writes:** Track with `outcome: "FAILED"` in the change record. Failed operations are still part of the audit trail -- they represent attempted changes.
+- **Dry-run operations:** `event.send` with `dryRun: true`, `entity.create` with `dryRun: true`, and `workflow.upload` with `dryRun: true` are NOT tracked. Dry runs do not change state.
+- **Partial sessions:** If the agent session ends abnormally (timeout, error), the audit captures everything tracked up to that point. The `endedAt` reflects the last tracked change, not the session end.
+- **No scope document:** If no scope decomposition was run, set `compliance.scopeDocumentRef` to `null`, `tasksCompleted` and `tasksTotal` to 0, and `traceability` to an empty object.
+- **No pre-deploy checklist:** If no pre-deploy check was run, set `compliance.preDeployChecklist` to `null`.
+- **Setting bulk upserts:** Each individual setting in a `setting.bulkUpsert` call is tracked as a separate CONFIG change record.
+- **Skill invocations with no tool calls:** A skill like `/fluent-workflow-analyzer` may be invoked but make no MCP tool calls (pure local file analysis). It appears in `skillInvocations` with `toolCallsProduced: []`.
+- **Tool calls outside skill context:** Direct MCP tool calls not triggered by a named skill (e.g., ad-hoc `graphql.query` by the agent) have `skill: undefined` in the toolCalls array.
+- **DryRun tool calls:** Calls with `dryRun: true` have `isWrite: false` and `dryRun: true`. They are only included with `--include-readonly`.
+
+## Integration with `/fluent-session-summary`
+
+Both skills share the same tracking protocol and read the same data:
+
+| Concern | Implementation |
+|---------|---------------|
+| Tracking log | Single running log maintained by the agent during the session |
+| Data ownership | Neither skill owns the log -- it is a cross-cutting concern |
+| Invocation independence | Either skill can be invoked without the other |
+| Consistent counts | Both skills must produce the same counts for the same data |
+| Ordering | Both skills order changes chronologically by timestamp |
+
+When both are invoked in the same session, the text summary from `/fluent-session-summary` and the JSON from `/fluent-session-audit-export` represent the same underlying changes. Any discrepancy is a bug.
+
+## Full Example Audit Document
+
+This example shows a realistic session that scaffolds a rule, configures settings, deploys a module and workflow, runs an E2E test, and commits the code.
+
+```json
+{
+  "$schema": "fluent-session-audit/v1",
+  "sessionId": "a3f1c9e2-7b4d-4e8a-9f12-d6c3a8b5e7f1",
+  "startedAt": "2026-02-23T09:00:12Z",
+  "endedAt": "2026-02-23T11:42:08Z",
+  "context": {
+    "profile": "<PROFILE>",
+    "account": "<account>.<env>.api.fluentretail.com",
+    "retailer": {
+      "ref": "<RETAILER_REF>",
+      "id": "<RETAILER_ID>"
+    },
+    "user": "<USER_NAME>",
+    "agentModel": "<MODEL_NAME>"
+  },
+  "summary": {
+    "codeChanges": 4,
+    "environmentMutations": 3,
+    "eventsSent": 2,
+    "deploymentsCompleted": 2,
+    "testsRun": 2,
+    "testsPassed": 2,
+    "testsFailed": 0,
+    "irreversibleActions": 2,
+    "skillsInvoked": 6,
+    "toolCallsWrite": 4,
+    "toolCallsRead": 1,
+    "decisionTrailEntries": 3
+  },
+  "changes": [
+    {
+      "seq": 1,
+      "timestamp": "2026-02-23T09:00:12Z",
+      "category": "CODE",
+      "action": "CREATE",
+      "target": {
+        "type": "file",
+        "path": "accounts/<PROFILE>/SOURCE/<MODULE_ROOT>/plugins/rules/<MODULE_ALIAS>/src/main/java/com/fluentcommerce/rule/<DOMAIN>/<RULE_CLASS>.java"
+      },
+      "details": "New rule class: <RULE_CLASS> implementing <BUSINESS_CAPABILITY>",
+      "reversible": true,
+      "rollbackCommand": "rm accounts/<PROFILE>/SOURCE/<MODULE_ROOT>/plugins/rules/<MODULE_ALIAS>/src/main/java/com/fluentcommerce/rule/<DOMAIN>/<RULE_CLASS>.java",
+      "skill": "fluent-rule-scaffold",
+      "storyRef": "<USER_STORY_ID_1>"
+    },
+    {
+      "seq": 2,
+      "timestamp": "2026-02-23T09:05:33Z",
+      "category": "CODE",
+      "action": "MODIFY",
+      "target": {
+        "type": "file",
+        "path": "accounts/<PROFILE>/SOURCE/<MODULE_ROOT>/resources/module.json"
+      },
+      "details": "Registered <RULE_CLASS> in provides[] array",
+      "diff": {
+        "linesAdded": 8,
+        "linesRemoved": 0
+      },
+      "reversible": true,
+      "rollbackCommand": "git checkout -- accounts/<PROFILE>/SOURCE/<MODULE_ROOT>/resources/module.json",
+      "skill": "fluent-rule-scaffold",
+      "storyRef": "<USER_STORY_ID_1>"
+    },
+    {
+      "seq": 3,
+      "timestamp": "2026-02-23T09:12:45Z",
+      "category": "CONFIG",
+      "action": "SETTING_CREATE",
+      "target": {
+        "type": "setting",
+        "key": "<SETTING_KEY>",
+        "context": "RETAILER",
+        "contextId": "<RETAILER_ID>"
+      },
+      "details": "Created webhook setting for order cancellation notifications",
+      "previousValue": null,
+      "newValue": "https://<webhook-host>/<path>",
+      "reversible": true,
+      "rollbackCommand": "Delete setting <SETTING_KEY> via GraphQL mutation deleteSetting",
+      "tool": "setting.upsert",
+      "skill": "fluent-settings"
+    },
+    {
+      "seq": 4,
+      "timestamp": "2026-02-23T09:45:18Z",
+      "category": "TEST",
+      "action": "BUILD",
+      "target": {
+        "type": "build",
+        "command": "mvn clean install -f accounts/<PROFILE>/SOURCE/<MODULE_ROOT>/plugins/pom.xml",
+        "exitCode": 0,
+        "testCount": 42,
+        "failureCount": 0
+      },
+      "details": "Maven build: 42 tests passed, 0 failures",
+      "result": "PASS",
+      "skill": "fluent-build"
+    },
+    {
+      "seq": 5,
+      "timestamp": "2026-02-23T10:02:07Z",
+      "category": "ENVIRONMENT",
+      "action": "DEPLOY",
+      "target": {
+        "type": "module",
+        "name": "<MODULE_NAME>",
+        "version": "<VERSION>",
+        "retailer": "<RETAILER_REF>"
+      },
+      "details": "Module deployed via fluent module install",
+      "previousVersion": "<PREVIOUS_VERSION>",
+      "reversible": true,
+      "rollbackCommand": "fluent module install -p <PROFILE> -r <RETAILER_REF> -m <MODULE_NAME>:<PREVIOUS_VERSION>",
+      "skill": "fluent-module-deploy"
+    },
+    {
+      "seq": 6,
+      "timestamp": "2026-02-23T10:08:34Z",
+      "category": "ENVIRONMENT",
+      "action": "DEPLOY",
+      "target": {
+        "type": "workflow",
+        "name": "<WORKFLOW_NAME>",
+        "version": "<WORKFLOW_VERSION>",
+        "retailer": "<RETAILER_REF>"
+      },
+      "details": "Workflow uploaded with new <RULESET_NAME> ruleset added",
+      "previousVersion": "<PREVIOUS_WORKFLOW_VERSION>",
+      "reversible": true,
+      "rollbackCommand": "Re-upload <WORKFLOW_NAME> version <PREVIOUS_WORKFLOW_VERSION> JSON via workflow.upload",
+      "tool": "workflow.upload",
+      "skill": "fluent-workflow-builder"
+    },
+    {
+      "seq": 7,
+      "timestamp": "2026-02-23T10:15:50Z",
+      "category": "ENVIRONMENT",
+      "action": "EVENT",
+      "target": {
+        "type": "event",
+        "eventName": "<EVENT_NAME_1>",
+        "entityType": "ORDER",
+        "entityRef": "<ENTITY_REF_1>",
+        "mode": "async"
+      },
+      "details": "E2E test: created test order via <EVENT_NAME_1> event",
+      "outcome": "SUCCESS",
+      "reversible": false,
+      "tool": "event.send",
+      "skill": "fluent-e2e-test"
+    },
+    {
+      "seq": 8,
+      "timestamp": "2026-02-23T10:16:22Z",
+      "category": "TEST",
+      "action": "ASSERT",
+      "target": {
+        "type": "assertion",
+        "entityType": "ORDER",
+        "entityRef": "<ENTITY_REF_1>",
+        "expectedStatus": "BOOKED",
+        "actualStatus": "BOOKED"
+      },
+      "details": "Assert order status=BOOKED after ConfirmValidation cascade",
+      "result": "PASS",
+      "tool": "test.assert",
+      "skill": "fluent-e2e-test"
+    },
+    {
+      "seq": 9,
+      "timestamp": "2026-02-23T10:22:11Z",
+      "category": "ENVIRONMENT",
+      "action": "EVENT",
+      "target": {
+        "type": "event",
+        "eventName": "<EVENT_NAME_2>",
+        "entityType": "ORDER",
+        "entityRef": "<ENTITY_REF_1>",
+        "mode": "async"
+      },
+      "details": "E2E test: cancelled test order via <EVENT_NAME_2> event",
+      "outcome": "SUCCESS",
+      "reversible": false,
+      "tool": "event.send",
+      "skill": "fluent-e2e-test"
+    },
+    {
+      "seq": 10,
+      "timestamp": "2026-02-23T10:22:45Z",
+      "category": "ENVIRONMENT",
+      "action": "MUTATION",
+      "target": {
+        "type": "entity",
+        "entityType": "ORDER",
+        "entityRef": "<ENTITY_REF_1>",
+        "entityId": "48291",
+        "fields": ["status"]
+      },
+      "details": "Order status confirmed <STATUS_TO> via workflow processing",
+      "previousValue": "<STATUS_FROM>",
+      "newValue": "<STATUS_TO>",
+      "outcome": "SUCCESS",
+      "reversible": false,
+      "tool": "graphql.query",
+      "skill": "fluent-e2e-test"
+    },
+    {
+      "seq": 11,
+      "timestamp": "2026-02-23T11:40:30Z",
+      "category": "CODE",
+      "action": "COMMIT",
+      "target": {
+        "type": "git",
+        "repo": "<REPO_NAME>",
+        "branch": "<BRANCH_NAME>",
+        "hash": "<COMMIT_HASH>"
+      },
+      "details": "feat: <FEATURE_DESCRIPTION>",
+      "reversible": true,
+      "rollbackCommand": "git revert <COMMIT_HASH>"
+    },
+    {
+      "seq": 12,
+      "timestamp": "2026-02-23T11:42:08Z",
+      "category": "CODE",
+      "action": "PUSH",
+      "target": {
+        "type": "git",
+        "repo": "<REPO_NAME>",
+        "branch": "<BRANCH_NAME>",
+        "remote": "<REMOTE_NAME>"
+      },
+      "details": "Pushed <BRANCH_NAME> to <REMOTE_NAME>",
+      "reversible": true,
+      "rollbackCommand": "git push <REMOTE_NAME> <BRANCH_NAME> --force"
+    }
+  ],
+  "skillInvocations": [
+    {
+      "seq": 1,
+      "timestamp": "2026-02-23T09:00:00Z",
+      "skill": "fluent-rule-scaffold",
+      "arguments": { "ruleName": "<RULE_CLASS>", "entityType": "<ENTITY_TYPE>", "module": "<MODULE_NAME>" },
+      "gateResult": "PASS",
+      "outcome": "completed",
+      "handoffSignal": "-> READY: accounts/<PROFILE>/SOURCE/.../<RULE_CLASS>.java",
+      "triggeredBy": null,
+      "duration": "5m33s",
+      "changesProduced": [1, 2],
+      "toolCallsProduced": [],
+      "nextRecommended": "fluent-build"
+    },
+    {
+      "seq": 2,
+      "timestamp": "2026-02-23T09:10:00Z",
+      "skill": "fluent-settings",
+      "arguments": { "settingKey": "<SETTING_KEY>", "context": "RETAILER" },
+      "outcome": "completed",
+      "duration": "2m45s",
+      "changesProduced": [3],
+      "toolCallsProduced": [1],
+      "nextRecommended": "fluent-pre-deploy-check"
+    },
+    {
+      "seq": 3,
+      "timestamp": "2026-02-23T09:40:00Z",
+      "skill": "fluent-build",
+      "arguments": { "module": "<MODULE_ALIAS>" },
+      "gateResult": "PASS",
+      "outcome": "completed",
+      "handoffSignal": "-> READY: accounts/<PROFILE>/SOURCE/.../dist/<MODULE_ARTIFACT>-<VERSION>.jar",
+      "triggeredBy": 1,
+      "duration": "5m18s",
+      "changesProduced": [4],
+      "toolCallsProduced": [],
+      "nextRecommended": "fluent-pre-deploy-check"
+    },
+    {
+      "seq": 4,
+      "timestamp": "2026-02-23T10:00:00Z",
+      "skill": "fluent-module-deploy",
+      "arguments": { "module": "<MODULE_NAME>", "version": "<VERSION>", "retailer": "<RETAILER_REF>" },
+      "gateResult": "PASS",
+      "outcome": "completed",
+      "handoffSignal": "-> READY: <MODULE_NAME> <VERSION> installed to <RETAILER_REF>",
+      "triggeredBy": 3,
+      "duration": "2m07s",
+      "changesProduced": [5],
+      "toolCallsProduced": [],
+      "nextRecommended": "fluent-e2e-test"
+    },
+    {
+      "seq": 5,
+      "timestamp": "2026-02-23T10:05:00Z",
+      "skill": "fluent-workflow-deploy",
+      "arguments": { "workflow": "<WORKFLOW_NAME>", "retailer": "<RETAILER_REF>" },
+      "outcome": "completed",
+      "duration": "3m34s",
+      "changesProduced": [6],
+      "toolCallsProduced": [2],
+      "nextRecommended": "fluent-e2e-test"
+    },
+    {
+      "seq": 6,
+      "timestamp": "2026-02-23T10:12:00Z",
+      "skill": "fluent-e2e-test",
+      "arguments": { "entityType": "<ENTITY_TYPE>", "testPlan": "<TEST_PLAN_NAME>" },
+      "outcome": "completed",
+      "duration": "10m45s",
+      "changesProduced": [7, 8, 9, 10],
+      "toolCallsProduced": [3, 4, 5]
+    }
+  ],
+  "toolCalls": [
+    {
+      "seq": 1,
+      "timestamp": "2026-02-23T09:12:45Z",
+      "tool": "setting.upsert",
+      "server": "fluent-mcp-extn",
+      "isWrite": true,
+      "target": { "description": "Create <SETTING_KEY> at RETAILER:<RETAILER_ID>" },
+      "outcome": "ok",
+      "dryRun": false,
+      "skill": "fluent-settings"
+    },
+    {
+      "seq": 2,
+      "timestamp": "2026-02-23T10:08:34Z",
+      "tool": "workflow.upload",
+      "server": "fluent-mcp-extn",
+      "isWrite": true,
+      "target": { "entityType": "WORKFLOW", "entityRef": "<WORKFLOW_NAME>", "description": "Upload <WORKFLOW_NAME> v<WORKFLOW_VERSION>" },
+      "outcome": "ok",
+      "dryRun": false,
+      "skill": "fluent-workflow-deploy"
+    },
+    {
+      "seq": 3,
+      "timestamp": "2026-02-23T10:15:50Z",
+      "tool": "event.send",
+      "server": "fluent-mcp-extn",
+      "isWrite": true,
+      "target": { "entityType": "ORDER", "entityRef": "<ENTITY_REF_1>", "description": "<EVENT_NAME_1> async" },
+      "outcome": "ok",
+      "dryRun": false,
+      "skill": "fluent-e2e-test"
+    },
+    {
+      "seq": 4,
+      "timestamp": "2026-02-23T10:16:22Z",
+      "tool": "test.assert",
+      "server": "fluent-mcp-extn",
+      "isWrite": false,
+      "target": { "entityType": "ORDER", "entityRef": "<ENTITY_REF_1>", "description": "Assert status=<EXPECTED_STATUS>" },
+      "outcome": "ok",
+      "dryRun": false,
+      "skill": "fluent-e2e-test"
+    },
+    {
+      "seq": 5,
+      "timestamp": "2026-02-23T10:22:11Z",
+      "tool": "event.send",
+      "server": "fluent-mcp-extn",
+      "isWrite": true,
+      "target": { "entityType": "ORDER", "entityRef": "<ENTITY_REF_1>", "description": "<EVENT_NAME_2> async" },
+      "outcome": "ok",
+      "dryRun": false,
+      "skill": "fluent-e2e-test"
+    }
+  ],
+  "decisionTrail": [
+    {
+      "seq": 1,
+      "timestamp": "2026-02-23T09:39:00Z",
+      "trigger": "Build failed",
+      "options": ["retry", "fix-setting", "rollback"],
+      "selected": "fix-setting",
+      "rationale": "Missing setting was deterministic root cause",
+      "confidence": "high",
+      "assumptions": [],
+      "skill": "fluent-build",
+      "triggeredBy": 3,
+      "resultingChanges": [3, 4]
+    },
+    {
+      "seq": 2,
+      "timestamp": "2026-02-23T10:00:00Z",
+      "trigger": "Deployment gate check",
+      "options": ["deploy-now", "run-pre-deploy-check"],
+      "selected": "run-pre-deploy-check",
+      "rationale": "Standard gated release path",
+      "confidence": "high",
+      "assumptions": [],
+      "skill": "fluent-module-deploy",
+      "triggeredBy": 4,
+      "resultingChanges": [5, 6]
+    },
+    {
+      "seq": 3,
+      "timestamp": "2026-02-23T10:12:00Z",
+      "trigger": "Post-deploy verification choice",
+      "options": ["skip-tests", "run-e2e"],
+      "selected": "run-e2e",
+      "rationale": "Deployment verification is mandatory",
+      "confidence": "high",
+      "assumptions": [],
+      "skill": "fluent-e2e-test",
+      "triggeredBy": 6,
+      "resultingChanges": [7, 8, 9, 10]
+    }
+  ],
+  "compliance": {
+    "scopeDocumentRef": "scope/<feature-scope>.md",
+    "tasksCompleted": 8,
+    "tasksTotal": 10,
+    "traceability": {
+      "<USER_STORY_ID_1>": {
+        "tasks": ["T-001", "T-002", "T-003", "T-004", "T-005"],
+        "status": "complete",
+        "changes": [1, 2, 3, 5, 6]
+      },
+      "<USER_STORY_ID_2>": {
+        "tasks": ["T-006", "T-007", "T-008"],
+        "status": "complete",
+        "changes": [7, 8, 9, 10]
+      },
+      "<USER_STORY_ID_3>": {
+        "tasks": ["T-009", "T-010"],
+        "status": "not_started",
+        "changes": []
+      }
+    },
+    "preDeployChecklist": "accounts/<PROFILE>/reports/pre-deploy/<MODULE_NAME>-<VERSION>.checklist.json",
+    "irreversibleActions": [
+      {
+        "seq": 7,
+        "description": "Event <EVENT_NAME_1> sent to <ENTITY_TYPE>/<ENTITY_REF_1> -- cannot be un-sent",
+        "risk": "LOW"
+      },
+      {
+        "seq": 9,
+        "description": "Event <EVENT_NAME_2> sent to <ENTITY_TYPE>/<ENTITY_REF_1> -- cannot be un-sent",
+        "risk": "LOW"
+      }
+    ]
+  }
+}
+```