@ddse/acm-examples 0.5.0 → 0.5.2

package/data/incidents/incidents.json

@@ -1,30 +0,0 @@
-[
-  {
-    "id": "INC-2045",
-    "service": "checkout-api",
-    "reportedAt": "2025-10-05T03:22:00Z",
-    "customerImpact": "MAJOR",
-    "category": "OUTAGE",
-    "signalScore": 0.91,
-    "declaredSeverity": "CRITICAL",
-    "vipCustomer": true
-  },
-  {
-    "id": "INC-2078",
-    "service": "analytics-stream",
-    "reportedAt": "2025-10-05T09:40:00Z",
-    "customerImpact": "MINOR",
-    "category": "PERFORMANCE",
-    "signalScore": 0.63,
-    "declaredSeverity": "MEDIUM"
-  },
-  {
-    "id": "INC-2099",
-    "service": "identity-core",
-    "reportedAt": "2025-10-05T11:05:00Z",
-    "customerImpact": "MAJOR",
-    "category": "SECURITY",
-    "signalScore": 0.74,
-    "declaredSeverity": "HIGH"
-  }
-]

package/data/incidents/routing_rules.json

@@ -1,36 +0,0 @@
-[
-  {
-    "id": "ROUTE-CHECKOUT-CRITICAL",
-    "service": "checkout-api",
-    "category": "OUTAGE",
-    "minSeverity": "HIGH",
-    "queue": "incident-bridge",
-    "escalatesTo": "director-oncall@northwind.example",
-    "notes": "Critical checkout outages route directly to the incident bridge."
-  },
-  {
-    "id": "ROUTE-CHECKOUT-MEDIUM",
-    "service": "checkout-api",
-    "category": "OUTAGE",
-    "minSeverity": "MEDIUM",
-    "queue": "payments-oncall",
-    "notes": "Medium outages handled by payments engineers."
-  },
-  {
-    "id": "ROUTE-ANALYTICS-PERF",
-    "service": "analytics-stream",
-    "category": "PERFORMANCE",
-    "minSeverity": "MEDIUM",
-    "queue": "analytics-sre",
-    "notes": "Performance degradations owned by analytics SRE."
-  },
-  {
-    "id": "ROUTE-ID-SECURITY",
-    "service": "identity-core",
-    "category": "SECURITY",
-    "minSeverity": "HIGH",
-    "queue": "security-incident",
-    "escalatesTo": "ciso@northwind.example",
-    "notes": "Security incidents always escalate to CISO contact."
-  }
-]

package/data/invoices/invoices.json

@@ -1,38 +0,0 @@
-[
-  {
-    "id": "INV-84721",
-    "supplier": "Skyline Components",
-    "total": 18450,
-    "currency": "USD",
-    "purchaseOrderId": "PO-99231",
-    "receivedAt": "2025-09-29T14:12:00Z",
-    "lines": [
-      { "sku": "SRV-FW-EDGE", "description": "Edge firewall appliance", "quantity": 5, "unitPrice": 2500 },
-      { "sku": "SRV-SUP-24M", "description": "24 month premium support", "quantity": 5, "unitPrice": 190 }
-    ]
-  },
-  {
-    "id": "INV-84758",
-    "supplier": "Northwind Training",
-    "total": 6120,
-    "currency": "USD",
-    "purchaseOrderId": "PO-99244",
-    "receivedAt": "2025-09-30T09:48:00Z",
-    "lines": [
-      { "sku": "TRN-COACHING", "description": "Onsite coaching workshop", "quantity": 3, "unitPrice": 1800 },
-      { "sku": "TRN-MATERIALS", "description": "Participant materials", "quantity": 30, "unitPrice": 18 }
-    ]
-  },
-  {
-    "id": "INV-84761",
-    "supplier": "Rapid Devices",
-    "total": 9200,
-    "currency": "USD",
-    "purchaseOrderId": "PO-99231",
-    "receivedAt": "2025-10-01T11:05:00Z",
-    "lines": [
-      { "sku": "SRV-FW-EDGE", "description": "Edge firewall appliance", "quantity": 4, "unitPrice": 2400 },
-      { "sku": "SRV-SUP-24M", "description": "24 month premium support", "quantity": 4, "unitPrice": 190 }
-    ]
-  }
-]

package/data/invoices/purchase-orders.json

@@ -1,38 +0,0 @@
-[
-  {
-    "id": "PO-99231",
-    "initiator": "Darius Patel",
-    "department": "Network Engineering",
-    "total": 18500,
-    "currency": "USD",
-    "status": "approved",
-    "lines": [
-      { "sku": "SRV-FW-EDGE", "description": "Edge firewall appliance", "quantity": 5, "unitPrice": 2500 },
-      { "sku": "SRV-SUP-24M", "description": "24 month premium support", "quantity": 5, "unitPrice": 200 }
-    ]
-  },
-  {
-    "id": "PO-99244",
-    "initiator": "Megan Lee",
-    "department": "People Operations",
-    "total": 6200,
-    "currency": "USD",
-    "status": "approved",
-    "lines": [
-      { "sku": "TRN-COACHING", "description": "Onsite coaching workshop", "quantity": 3, "unitPrice": 1800 },
-      { "sku": "TRN-MATERIALS", "description": "Participant materials", "quantity": 30, "unitPrice": 20 }
-    ]
-  },
-  {
-    "id": "PO-99267",
-    "initiator": "Laila Ortiz",
-    "department": "Manufacturing",
-    "total": 11800,
-    "currency": "USD",
-    "status": "pending",
-    "lines": [
-      { "sku": "MFG-CNC-LEASE", "description": "CNC equipment lease", "quantity": 1, "unitPrice": 9600 },
-      { "sku": "MFG-SAFETY-KIT", "description": "Safety equipment kit", "quantity": 40, "unitPrice": 55 }
-    ]
-  }
-]

package/data/issues.json

@@ -1,99 +0,0 @@
-[
-  {
-    "issueId": "ISS-001",
-    "title": "Unable to complete checkout",
-    "description": "Payment processing fails at the final step with error code 500",
-    "severity": "high",
-    "status": "open",
-    "reportedBy": "C-789",
-    "reportedAt": "2025-01-15T10:30:00Z",
-    "category": "payment",
-    "affectedUsers": 45,
-    "region": "US-EAST"
-  },
-  {
-    "issueId": "ISS-002",
-    "title": "Product images not loading",
-    "description": "Product detail pages show broken image placeholders instead of actual product photos",
-    "severity": "medium",
-    "status": "investigating",
-    "reportedBy": "C-456",
-    "reportedAt": "2025-01-14T14:20:00Z",
-    "category": "ui",
-    "affectedUsers": 120,
-    "region": "EU-WEST"
-  },
-  {
-    "issueId": "ISS-003",
-    "title": "Email notifications delayed",
-    "description": "Order confirmation emails are arriving 2-3 hours after order placement instead of immediately",
-    "severity": "low",
-    "status": "resolved",
-    "reportedBy": "C-123",
-    "reportedAt": "2025-01-13T09:15:00Z",
-    "resolvedAt": "2025-01-14T16:00:00Z",
-    "category": "notifications",
-    "affectedUsers": 200,
-    "region": "global"
-  },
-  {
-    "issueId": "ISS-004",
-    "title": "Search results inaccurate",
-    "description": "Product search returns irrelevant results and misses exact matches",
-    "severity": "high",
-    "status": "open",
-    "reportedBy": "C-555",
-    "reportedAt": "2025-01-16T11:45:00Z",
-    "category": "search",
-    "affectedUsers": 300,
-    "region": "global"
-  },
-  {
-    "issueId": "ISS-005",
-    "title": "Mobile app crashes on iOS",
-    "description": "App crashes when attempting to view order history on iOS 17",
-    "severity": "critical",
-    "status": "in_progress",
-    "reportedBy": "C-888",
-    "reportedAt": "2025-01-17T08:00:00Z",
-    "category": "mobile",
-    "affectedUsers": 500,
-    "region": "global"
-  },
-  {
-    "issueId": "ISS-006",
-    "title": "Slow page load times",
-    "description": "Homepage and category pages taking 10+ seconds to load during peak hours",
-    "severity": "medium",
-    "status": "open",
-    "reportedBy": "C-777",
-    "reportedAt": "2025-01-16T19:30:00Z",
-    "category": "performance",
-    "affectedUsers": 1000,
-    "region": "US-WEST"
-  },
-  {
-    "issueId": "ISS-007",
-    "title": "Incorrect tax calculation",
-    "description": "Sales tax is being calculated incorrectly for orders in California",
-    "severity": "high",
-    "status": "investigating",
-    "reportedBy": "C-456",
-    "reportedAt": "2025-01-15T13:20:00Z",
-    "category": "billing",
-    "affectedUsers": 75,
-    "region": "US-WEST"
-  },
-  {
-    "issueId": "ISS-008",
-    "title": "Wishlist items disappearing",
-    "description": "Items added to wishlist are randomly being removed after page refresh",
-    "severity": "low",
-    "status": "open",
-    "reportedBy": "C-999",
-    "reportedAt": "2025-01-14T16:45:00Z",
-    "category": "feature",
-    "affectedUsers": 50,
-    "region": "global"
-  }
-]

package/data/knowledge/docs/kb-001.md

@@ -1,7 +0,0 @@
-# Resetting MFA-secured passwords
-
-1. Validate the caller using two account identifiers and the last successful login timestamp.
-2. Confirm MFA enrollment method (TOTP, push, hardware key) and whether the customer still has access.
-3. If hardware key is lost, create a temporary bypass token valid for 10 minutes and log the issuance in the security ledger.
-4. Require the customer to set a new password that meets the 14-character complexity policy.
-5. Close the case by attaching the bypass confirmation ID and notifying the security operations channel.

package/data/knowledge/docs/kb-002.md

@@ -1,7 +0,0 @@
-# Refund eligibility decision tree
-
-- Verify the subscription tier and billing term. Enterprise annual contracts require finance approval.
-- If the incident is tagged as "platform outage", issue a full credit prorated for downtime.
-- For shipping or activation delays, offer expedited onboarding plus a 20% credit if the customer is GOLD or higher.
-- Always document the root cause category and attach supporting telemetry to the refund record.
-- Escalate to the duty manager if the requested credit exceeds $5,000 USD.

package/data/knowledge/docs/kb-003.md

@@ -1,9 +0,0 @@
-# Stabilizing API latency regressions
-
-Monitoring detected elevated p95 latency across the public REST API. Follow this checklist:
-
-1. Inspect deployment history for the impacted service and roll back if a canary exceeded SLOs.
-2. Flush regional CDN caches and confirm cache hit ratios rebound above 92%.
-3. Capture thread dumps from the application nodes to identify blocking calls.
-4. Increase autoscaling floor by two nodes per region while the investigation runs.
-5. Post an update to the status page every 30 minutes until latency returns under 250 ms.

package/data/knowledge/index.json

@@ -1,25 +0,0 @@
-{
-  "snippets": [
-    {
-      "id": "KB-001",
-      "title": "Resetting MFA-secured passwords",
-      "tags": ["identity", "password", "mfa"],
-      "path": "docs/kb-001.md",
-      "summary": "Runbook for agents guiding customers through MFA password reset and device verification."
-    },
-    {
-      "id": "KB-002",
-      "title": "Refund eligibility decision tree",
-      "tags": ["billing", "refund", "policy"],
-      "path": "docs/kb-002.md",
-      "summary": "Policy matrix for issuing refunds based on subscription tier and issue category."
-    },
-    {
-      "id": "KB-003",
-      "title": "Stabilizing API latency regressions",
-      "tags": ["incident", "performance", "api"],
-      "path": "docs/kb-003.md",
-      "summary": "Checklist for diagnosing elevated API latency including caching, rollout, and alerting steps."
-    }
-  ]
-}

package/data/orders.json

@@ -1,106 +0,0 @@
-[
-  {
-    "orderId": "O-2025-001",
-    "customerId": "C-789",
-    "customerName": "John Smith",
-    "orderDate": "2025-01-10",
-    "status": "delivered",
-    "total": 299.99,
-    "items": [
-      { "sku": "PROD-001", "name": "Wireless Headphones", "quantity": 1, "price": 149.99 },
-      { "sku": "PROD-002", "name": "Phone Case", "quantity": 2, "price": 75.00 }
-    ],
-    "shippingAddress": {
-      "street": "123 Main St",
-      "city": "New York",
-      "state": "NY",
-      "zip": "10001",
-      "country": "US"
-    },
-    "region": "US-EAST"
-  },
-  {
-    "orderId": "O-2025-002",
-    "customerId": "C-456",
-    "customerName": "Sarah Johnson",
-    "orderDate": "2025-01-12",
-    "status": "shipped",
-    "total": 599.00,
-    "items": [
-      { "sku": "PROD-003", "name": "Laptop Stand", "quantity": 1, "price": 89.00 },
-      { "sku": "PROD-004", "name": "External Monitor", "quantity": 1, "price": 499.00 },
-      { "sku": "PROD-005", "name": "USB-C Cable", "quantity": 2, "price": 11.00 }
-    ],
-    "shippingAddress": {
-      "street": "456 Oak Ave",
-      "city": "San Francisco",
-      "state": "CA",
-      "zip": "94102",
-      "country": "US"
-    },
-    "region": "US-WEST"
-  },
-  {
-    "orderId": "O-2025-003",
-    "customerId": "C-123",
-    "customerName": "Michael Brown",
-    "orderDate": "2025-01-14",
-    "status": "processing",
-    "total": 1299.99,
-    "items": [
-      { "sku": "PROD-006", "name": "Gaming Keyboard", "quantity": 1, "price": 199.99 },
-      { "sku": "PROD-007", "name": "Gaming Mouse", "quantity": 1, "price": 99.99 },
-      { "sku": "PROD-008", "name": "Gaming Chair", "quantity": 1, "price": 999.99 }
-    ],
-    "shippingAddress": {
-      "street": "789 Elm St",
-      "city": "Chicago",
-      "state": "IL",
-      "zip": "60601",
-      "country": "US"
-    },
-    "region": "US-CENTRAL"
-  },
-  {
-    "orderId": "O-2025-004",
-    "customerId": "C-789",
-    "customerName": "John Smith",
-    "orderDate": "2025-01-15",
-    "status": "cancelled",
-    "total": 49.99,
-    "items": [
-      { "sku": "PROD-009", "name": "Screen Protector", "quantity": 1, "price": 24.99 },
-      { "sku": "PROD-010", "name": "Cleaning Kit", "quantity": 1, "price": 24.99 }
-    ],
-    "shippingAddress": {
-      "street": "123 Main St",
-      "city": "New York",
-      "state": "NY",
-      "zip": "10001",
-      "country": "US"
-    },
-    "region": "US-EAST",
-    "cancellationReason": "Customer requested"
-  },
-  {
-    "orderId": "O-2025-005",
-    "customerId": "C-555",
-    "customerName": "Emily Davis",
-    "orderDate": "2025-01-16",
-    "status": "delivered",
-    "total": 399.50,
-    "items": [
-      { "sku": "PROD-011", "name": "Wireless Charger", "quantity": 2, "price": 79.99 },
-      { "sku": "PROD-012", "name": "Power Bank", "quantity": 1, "price": 59.99 },
-      { "sku": "PROD-013", "name": "Car Mount", "quantity": 3, "price": 59.85 }
-    ],
-    "shippingAddress": {
-      "street": "321 Pine Rd",
-      "city": "Seattle",
-      "state": "WA",
-      "zip": "98101",
-      "country": "US"
-    },
-    "region": "US-WEST"
-  }
-]

package/docs/examples-architecture.md

@@ -1,144 +0,0 @@
-# ACM Examples — Architecture & Implementation Blueprint
-
-Last updated: 2025-10-06
-
-## Overview
-
-This blueprint translates the release implementation plan into concrete module boundaries, task/tool specifications, and planner wiring for the five flagship examples. The intent is to keep the package modular while maximizing reuse of shared registries, data loaders, and context adapters.
-
-Each example is delivered as a capability bundle exposing:
-
-- A goal definition consumable by the `ACMFramework` (#goal slug + metadata).
-- Context assembly helpers that hydrate packets from synthetic data and Nucleus directives.
-- Tool implementations (pure + LLM backed) with deterministic fallbacks for unit testing.
-- Task specifications with policy bindings and ledger annotations.
-- Verification hooks and replay assertions validated via `tests/<example>.test.ts`.
-
-## Shared Components
-
-| Component | Location | Notes |
-|-----------|----------|-------|
-| `createDemoFramework` | `src/framework.ts` (existing) | Updated to register new capabilities and directive handlers. |
-| Data loaders | `src/data/*.ts` | Already implemented; expose typed helpers and caching. |
-| Directive router | `src/context/directives.ts` (new) | Centralizes prefix → loader/provider mapping. |
-| Policy engine extensions | `src/policy/examples-policy.ts` (new) | Encapsulates per-example policy checks (SLA, entitlement guard, etc.). |
-| Verification sheets | `src/verification/<example>.ts` (new) | Deterministic validation of task outputs. |
-| Capability registry | `src/registry/examples.ts` (new) | Registers tasks/tools/capabilities; re-exported through public surface. |
-
-All tools should be authored under `src/tools/<example>/` and tasks under `src/tasks/<example>/`. Shared utility abstractions (e.g., scoring, formatting, result types) live in `src/lib/`.
-
-## Example Blueprints
-
-### 1. Customer Entitlement Checker (`entitlement`)
-
-- **Goal slug:** `entitlement-check`
-- **Context builders:**
-  - `buildEntitlementContext(customerId)` fetches customer + policy snapshots using `getCustomerProfile` and `getPolicyByTier`.
-  - Directive prefix `crm:` resolves to `fetchCustomerProfileTool` for nucleus preflight.
-- **Tools:**
-  - `fetchCustomerProfileTool` — deterministic JSON lookup.
-  - `evaluateEntitlementTool` — pure function comparing policy rules (tier, compliance flags) with customer state; returns `{decision, rationale}`.
-  - `notifySupervisorTool` — simulated side-effect; no-op in tests, emits ledger entry `NOTIFICATION_ENQUEUED` when `decision === "deny"`.
-- **Tasks:**
-  1. `RetrieveCustomerTask` (uses `fetchCustomerProfileTool`).
-  2. `EvaluateEntitlementTask` (uses `evaluateEntitlementTool`; guard `decision === "allow"`).
-  3. `SupervisorNotificationTask` (conditional on guard failure).
-- **Policy & verification:**
-  - Policy: ensure customer tier >= required tier; add ledger note `POLICY_FAIL` on violation.
-  - Verification: result payload must include `decision`, `rationale`, and `policyTrace` entries.
-- **Planner wiring:** linear plan with guard-based branch; replay should include both primary path and optional compensation branch.
-
-### 2. Knowledge Snippet Summarizer (`knowledge`)
-
-- **Goal slug:** `knowledge-summarize`
-- **Context builders:**
-  - `buildKnowledgeContext(query)` indexing metadata for candidate docs.
-  - Directive prefix `kb:` loads Markdown snippets via `getKnowledgeDoc` (already piped through loader with hash-based caching).
-- **Tools:**
-  - `searchKnowledgeTool` — wrap reusable BM25 implementation; returns ranked hits.
-  - `summarizeSnippetTool` — nucleus-backed summarizer with deterministic small-model fallback for tests.
-  - `suggestFollowupsTool` — optional; uses deterministic heuristics derived from doc tags.
-- **Tasks:**
-  1. `SearchKnowledgeTask` (guard: must yield ≥1 hit, otherwise `KnowledgeNotFound` branch calling `suggestFollowupsTool` with escalation instructions).
-  2. `SummarizeSnippetTask` (streams summary paragraphs; attaches tokens to replay).
-  3. `SuggestFollowupsTask` (optional post-processing).
-- **Policy & verification:**
-  - Policy ensures summarizer references source doc ID in output.
-  - Verification asserts summary length bounds and includes bullet follow-ups when branch executed.
-
-### 3. Incident Triage Router (`incident-router`)
-
-- **Goal slug:** `incident-triage`
-- **Context builders:**
-  - `buildIncidentContext(incidentId)` merges incident record, routing matrix, and SLA thresholds.
-  - Directive prefix `inc:` fetches incident; `routing:` fetches matrix slice.
-- **Tools:**
-  - `classifySeverityTool` — deterministic scoring (based on impact, urgency, SLA fields).
-  - `selectQueueTool` — maps severity + service area to queue; returns queue ID with rationale.
-  - `escalateIncidentTool` — logs escalation event (appends to `data/incidents/escalations.log` or memory stub in tests).
-- **Tasks:**
-  1. `AssessIncidentTask` → severity classification.
-  2. `RouteIncidentTask` → queue selection with guard verifying queue exists.
-  3. `EscalateIncidentTask` → executes when severity >= `high` and queue flagged `needsEscalation`.
-- **Policy & verification:**
-  - Policy ensures high severity incidents trigger escalation ledger entry.
-  - Verification checks final payload includes `assignedQueue` and `nextAction` fields.
-
-### 4. Invoice Verification Pipeline (`invoice-verification`)
-
-- **Goal slug:** `invoice-verify`
-- **Context builders:**
-  - `buildInvoiceContext(invoiceId)` loads invoice + matching PO; attaches discrepancy heuristics.
-  - Directive prefix `erp:` fetches purchase order data by PO ID, using `getPurchaseOrder` and caching.
-- **Tools:**
-  - `fetchInvoiceTool` & `fetchPurchaseOrderTool` — deterministic lookups.
-  - `compareLineItemsTool` — wraps existing helper, returning discrepancy list with typed reasons.
-  - `recordFindingsTool` — writes deterministic report JSON (timestamp stubbed) to context attachments.
-- **Tasks:**
-  1. `LoadInvoiceTask` → fetch invoice details.
-  2. `CrossCheckPurchaseOrderTask` → fetch PO.
-  3. `ReconcileLineItemsTask` → produce discrepancy list; guard triggers remediation branch if list non-empty.
-  4. `RecordFindingsTask` → persist outputs (always runs, but includes branch metadata).
-  5. `InitiateRemediationTask` (optional) → triggered when discrepancies exist; simulates ticket creation.
-- **Policy & verification:**
-  - Policy ensures total variance <= configured tolerance; violate → ledger `POLICY_VARIANCE`.
-  - Verification asserts report includes `status`, `discrepancies[]`, and `nextSteps`.
-
-### 5. Agent Coaching Feedback Loop (`coaching`)
-
-- **Goal slug:** `agent-coaching`
-- **Context builders:**
-  - `buildCoachingContext(callId)` loads transcript metadata and scoring rubric.
-  - Directive prefix `transcript:` retrieves transcript body; optional `csat:` directive fetches historic CSAT metrics.
-- **Tools:**
-  - `analyzeTranscriptTool` — sentiment + compliance analysis (deterministic scoring with heuristics; optionally seeds nucleus call for narrative feedback).
-  - `generateFeedbackTool` — nucleus-backed structured feedback (with fallback template).
-  - `logCoachingNoteTool` — deterministic logging (appends to synthetic CRM store or returns stub ID).
-- **Tasks:**
-  1. `AnalyzeTranscriptTask` → produce structured metrics (`sentimentScore`, `complianceFlags`).
-  2. `GenerateFeedbackTask` → produce human-readable coaching tips anchored to metrics.
-  3. `LogCoachingNoteTask` → persist feedback; guard ensures compliance failures trigger escalation note with supervisor mention.
-- **Policy & verification:**
-  - Policy: if compliance failure detected, ensure escalation note created.
-  - Verification: final payload contains `feedbackSummary`, `actionItems`, and `logReference`.
-
-## Planner & CLI Integration
-
-- Extend goal registry at `src/goals/index.ts` with five new entries referencing helper builders.
-- Update CLI selector in `bin/interactive.tsx` and `bin/acm-demo.ts` to expose new options (`--goal` values + interactive menu items).
-- Provide shared helper `resolveExampleGoal(slug)` to map CLI input to goal factories.
-
-## Testing Strategy
-
-- Add integration suites under `tests/examples/` with one spec per example.
-- Mock nucleus responses using existing harness; for deterministic fallbacks, set `NUCLEUS_MODE=offline` in tests.
-- Validate replay bundles by asserting JSON schema + verifying ledger entries.
-- Include snapshot testing (where stable) for final task payloads.
-
-## Next Steps Checklist
-
-1. Scaffold shared modules (`context/directives.ts`, `registry/examples.ts`, `policy/examples-policy.ts`).
-2. Implement entitlement capability end-to-end as reference pattern.
-3. Replicate pattern for the remaining four examples, factoring shared utilities as they emerge.
-4. Wire CLI + goal registry, then author integration tests.
-5. Update documentation & READMEs with usage instructions.