wulf-pulse/docs/wulf-pulse-ticket-analyzer-build-notes.md

# AI Ticket Analyzer — Build Notes

A running journal of the multi-phase build for the AI Ticket Analyzer feature.
Captures what was delivered each phase, design decisions worth flagging, and
what was deliberately left out. Spec lives in
`wulf-pulse-ticket-analyzer-prompt.md`.

This file is updated after each phase ships.

---

## Phase 1 — Migration + Zod schemas

**Delivered**

- `migrations/069_create_analyzer_tables.sql` — three tables
  (`analyzer_analyses`, `analyzer_shares`, `analyzer_jobs`) with `pgcrypto`
  extension guard, indexes per spec, status `CHECK` constraints, and FK types
  corrected to `TEXT` (not `UUID`) to match Better Auth's `user.id`.
- `lib/types/analyzer.ts` — Zod schemas for every LLM-stage parsed JSON
  (`TaggedEvent`, `TriageResponse`, `DeepAnalysisResponse`, `OpusResponse`),
  persisted row shapes, job status, API request bodies, and the internal
  `PreprocessedTicket` payload that flows through the pipeline.

**Decisions worth flagging**

- `triggered_by_user_id` is **nullable + `ON DELETE SET NULL`** (not `NOT NULL`).
  An analysis should still be readable in history if the triggering user is
  later deleted. `analyzer_shares.shared_by_user_id` is `NOT NULL +
  ON DELETE CASCADE` (audit-log style — share rows go with the user).
- `evidence_timestamps` typed as `string().datetime({offset: true})` (ISO
  timestamps), not numeric indices. More robust to model hallucination and
  reads better in the UI.
- `TaggedEvent` does NOT support a "two separate events" form for time entries
  with both Summary + Internal Notes — single event with both fields, per the
  spec's preference for a cleaner timeline.

**Deliberately left out**

- Migration is committed but **not applied** to any running DB. Postgres only
  re-applies migrations on first init of a fresh volume; the existing DB needs
  a manual run of this migration when phase 5 is exercised.

---

## Phase 2 — Stage 0 pre-processor + IT Glue redaction

**Delivered**

- `lib/services/analyzer/itglue-redact.ts` — recursive walk; matches keys
  against `/password|secret|key|token|credential|api[_-]?key/i`; replaces
  values with `[REDACTED]`. Subtree redaction (key matching `auth` → no leaves
  leak), defensive copy, cycle guard (`[CIRCULAR]` marker).
- `lib/services/analyzer/preprocessor.ts` — filters workflow noise + Service
  Desk Notification rows, tags ticket_create/notes/time entries with
  `actor / actor_type / source / visibility / summary_notes / internal_notes /
  hours`, sorts chronologically, computes `sha256` content hash over canonical
  JSON of `(events, status, priority, queue)`.
- `vitest@^4.1.5` added as devDep with `vitest.config.ts` setting up the
  `@/` alias. Two test files at this phase: 32 redaction tests + 36
  preprocessor tests including the regression run against the
  `T20260424.0045` fixture.
- Type-aliasing fix in `lib/types/analyzer.ts`: added `export type X =
  z.infer<typeof X>` for `ActorType`, `EventSource`, `Visibility`, `Severity`,
  `ComplexityTier`, `TicketType` — the Zod-enum const exports alone don't
  produce a usable TypeScript type.

**Decisions worth flagging**

- `actor_type` is classified by **email domain, not author text**, per the
  spec. `lorentz@wulfconsulting.com` is `wulf_tech` regardless of how the
  message reads. Sonnet handles the role nuance at Stage 3.
- Time entries with no narrative content (no summary, no internal notes) are
  dropped — a purely numeric entry adds nothing.
- Vendor-domain allowlist is intentionally short and conservative (Vertafore,
  Datto, Microsoft, etc.). Misclassifying a customer domain as "vendor" is
  worse than the default `client_contact`.

**Deliberately left out**

- No real protection for secrets embedded in **free text** (e.g. a notes field
  containing the literal string "the password is hunter2"). The redaction
  guarantee is on field **keys**, not values. The IT Glue search test
  documents this contract explicitly so it isn't "fixed" without thought.

---

## Phase 3 — Anthropic SDK setup + Stage 1 (Haiku triage)

**Delivered**

- `lib/services/llm/{models,pricing,client,call}.ts` — model ID constants,
  per-model rate table (Haiku $1/$5, Sonnet $3/$15, Opus $5/$25 per 1M tokens
  + cache read/write tiers), lazy SDK singleton, generic
  `callLLMStage<T>({model, system, user, schema, maxTokens, client?})`
  helper that:
  - Marks the system prompt with `cache_control: {type: "ephemeral"}`
  - Sends NO `temperature`/`top_p`/`top_k` (Opus 4.7 would 400)
  - Strips a single ` ```json ` fence before parsing
  - On parse failure, retries **once** with prior-attempt + error in a
    follow-up user turn
  - Returns `{data, usage, estimated_cost_usd, attempts, raw_response}`
- `lib/services/analyzer/stages/stage1-triage.ts` — Haiku caller with the
  spec's verbatim system prompt and a 50KB user-payload cap that drops oldest
  internal-only events first when oversized.
- `lib/services/analyzer/itglue-search.ts` — search facade that runs every
  result through `redact()` before returning. Snippets capped at 2000 chars,
  doc count capped at 10. `itglue-aliases.json` skeleton for known fuzzy
  org-name mappings.
- 32 new tests across pricing/call/Stage 1/IT Glue search.

**Decisions worth flagging**

- **Manual JSON.parse + Zod validate, not `output_config.format` /
  `client.messages.parse()`.** The spec said retry-once on Zod parse failure,
  and Zod 4 ↔ JSON Schema conversion has edge cases I didn't want to depend
  on (e.g. `.datetime({offset: true})` → JSON Schema `format`). Manual parse
  is what the spec asks for and is more transparent.
- **Prompt caching probably won't fire on these stages.** Our system prompts
  are ~1-2 KB (~250-500 tokens); minimum cacheable prefix is 2048 (Sonnet) or
  4096 (Haiku/Opus) tokens. The `cache_control` marker is a no-op below
  threshold and incurs no cost — left in defensively, but caching is not a
  meaningful lever for this workload.
- **Redaction is on KEY names, not free text** — re-stated for emphasis. The
  IT Glue search test asserts this contract.
- **`itglue-aliases.json` is a skeleton** with `_comment` / `_example` keys
  documenting the format. Real org-id entries get added when phase 5 wires
  this into the pipeline.

**Deliberately left out**

- No live API integration test. All Stage 1 tests use a mocked `Anthropic`
  client. A real-API smoke test belongs in phase 5+ when we run end-to-end.
- Did **not** wrap `lib/services/itglue-client.ts` in a redacting search
  facade for non-LLM callers. The redaction primitive is ready; non-LLM
  callers (sync service, data browsers) intentionally have full data — they
  are not the path that needs protection.

---

## Phase 4 — Pipeline + Job worker (Stages 3, 4, 5)

**Delivered**

- `lib/services/analyzer/stages/stage3-deep-analysis.ts` — Sonnet caller,
  spec's verbatim prompt, 80KB payload cap.
- `lib/services/analyzer/stages/stage4-deep-reasoning.ts` — Opus caller plus
  pure helpers `shouldRunDeepReasoning()` and `applyOpusUpdates()`.
- `lib/services/analyzer/data-access.ts` — `loadTicketBundle(ticketNumber)`
  joins `tickets` / `statuses` / `priorities` / `queues` / `companies` /
  `contacts` / `resources` / `ticket_notes` / `time_entries` and returns the
  exact `RawTicketBundle` shape the preprocessor expects. Throws typed
  `TicketNotFoundError`.
- `lib/services/analyzer/persistence.ts` — `getNextAnalysisVersion`,
  `findExistingAnalysisByContentHash`, `insertAnalysis`, plus job
  `claimQueuedJob` / `updateJobStatus` / `completeJob` / `failJob` /
  `queueJob` / `getJob`. Job claim uses `FOR UPDATE SKIP LOCKED` so multiple
  Next.js workers can poll safely.
- `lib/services/analyzer/pipeline.ts` — composes Stage 0 → idempotency check
  → Stage 1 → (Stage 2 if `itglue_lookup_needed`) → Stage 3 → (Stage 4 if
  trigger fires AND cost ceiling not reached) → result. Cost circuit breaker
  trips at $2.00 before Opus, sets `needs_human_review=true` with a
  reason. Returns full `model_traces` for debugging.
- `lib/services/analyzer/worker.ts` — singleton with 2-second poll loop;
  auto-starts in production; opt-in in dev via
  `ANALYZER_WORKER_AUTOSTART=1`; **skipped** under vitest. `runJob()`
  exposed for tests + manual triggers. `TicketNotFoundError` produces a
  user-facing job error message that fingers the sync as the culprit.
- 28 new tests bringing the total to 128.

**Decisions worth flagging**

- **Worker auto-start is more conservative than `sync-scheduler.ts`.** That
  one auto-starts on any non-browser import (including tests). I gated this
  one because the worker hits the database AND runs LLM calls — much higher
  blast radius. To run locally, set `ANALYZER_WORKER_AUTOSTART=1`.
- **Cost circuit breaker only fires before Opus.** Sonnet runs unconditionally
  even if it would push past $2. Spec wording matches; if the team wants
  stricter control, the natural place is next to `COST_CEILING_USD` in
  `pipeline.ts`.
- **Idempotency check matches `status='complete'` only.** Failed runs don't
  poison the cache.
- **IT Glue failures are tolerated.** Search throws → analysis continues
  without context, doesn't fail the run.
- `worker.test.ts` casts `mockImplementationOnce` to `as never` because
  vitest's overload resolution fights us when the mocked function has multiple
  call signatures. Functional, just ugly.

**Deliberately left out**

- No live API integration test (still). Phase 5+ is the natural place for an
  end-to-end smoke test.
- Stage 3 doesn't have a fixture-driven happy-path test like Stage 1; it's
  exercised at the orchestration layer via `pipeline.test.ts` only. Worth
  adding direct Stage 3 tests later.
- Migration `069` still not applied — same as phase 1.

---

## Phase 5 — API routes

**Delivered**

- Persistence read paths added to `lib/services/analyzer/persistence.ts`:
  `getAnalysisById`, `listAnalysesByTicketNumber`, `listNeedsReview`,
  `createShare`, plus a shared `rowToPersistedAnalysis` row mapper.
- 6 routes under `app/api/analyzer/`:
  | Route | Method | Returns |
  |---|---|---|
  | `tickets/[ticketNumber]/analyze` | POST | `{status, jobId?, existingAnalysisId?}` |
  | `tickets/[ticketNumber]/analyses` | GET | `{analyses: PersistedAnalysis[]}` |
  | `jobs/[jobId]` | GET | `{job}` |
  | `analyses/[id]` | GET | `{analysis}` |
  | `analyses/[id]/share` | POST | `{share}` |
  | `needs-review?limit=&offset=` | GET | `{analyses}` |

**Decisions worth flagging**

- **Analyze runs preprocess inline.** The route does
  `loadTicketBundle → preprocessTicket → findExistingAnalysisByContentHash`
  synchronously to support the spec's `existingAnalysisId?` immediate
  response. The worker also runs this — duplicated work, but preprocess is
  fast (deterministic, one DB load) and the alternative (always queue,
  frontend polls to discover the short-circuit) is worse UX.
- **Email send deferred to phase 8** per the spec's delivery order. The share
  route persists the audit row and validates the recipient domain against
  `ALLOWED_SHARE_DOMAINS`. Until phase 8, share rows have `viewed_at = null`
  indefinitely.
- **`requireAuth()` everywhere — not `requireAdmin()`.** Any authenticated
  user can analyze a ticket they have access to. If `/needs-review` should
  be admin-only later, swap that one to `requirePermission('analyzer',
  'review')` once the permission map is decided.
- **No new permission entries added to `lib/permissions.ts`.** Adding scoped
  permissions for a feature still under build risks getting them wrong.
- Routes are NOT in `middleware.ts` `publicRoutes` — they require a session.

**Deliberately left out**

- No API route tests. The repo has zero `app/api/**/*.test.ts` files; the
  routes are thin orchestration on top of already-tested persistence. Adding
  integration tests means setting up a test harness for the auth helpers +
  Postgres, which is a separate effort.

---

## Phase 6 — Frontend pages

**Delivered**

- `components/analyzer/analyze-button.tsx` — `<AnalyzeButton>` with the full
  state machine: POSTs to the analyze endpoint, navigates straight to an
  existing analysis if `existingAnalysisId` came back, otherwise polls
  `/api/analyzer/jobs/:jobId` every 2s and renders stage labels (Queued →
  Fetching → Triaging → Searching IT Glue → Analyzing → Deep review → Done).
  5-minute hard timeout. Failures surface as toast errors. Supports `force`
  for explicit re-run.
- `components/analyzer/share-modal.tsx` — `<ShareModal>` with a shadcn Dialog
  + email field + optional note (max 2000 chars). POSTs to the share
  endpoint and surfaces server-side validation errors (domain not allowed →
  toast).
- `components/analyzer/analysis-view.tsx` — the full 10-section analysis
  layout per spec. Header with model-tier badges (Haiku/Sonnet/Opus pills),
  confidence score, total cost, Share + Re-analyze buttons. Summary, Next
  Step (with rationale collapsed), Timeline (vertical list with 🟢 / 🔒 /
  🔄 markers, click to expand), What Was Done / Should Have Been Done
  side-by-side on wide screens, Gaps colored by severity with "Evidence:"
  links that scroll-and-expand the matching timeline event,
  Post-Resolution (only if present), Human Review Flags (only if needed),
  IT Glue References.
- `app/analyzer/ticket/[ticketNumber]/page.tsx` — ticket detail with the
  Analyze button and a list of historical versions; latest is badged.
- `app/analyzer/analysis/[id]/page.tsx` — fetches one analysis and renders
  it via `<AnalysisView>`.
- `app/analyzer/queue/page.tsx` — needs-review queue, shows ticket number,
  version, summary preview, top reasons, confidence badge, and a `high gap`
  badge if any gap is high severity.

**Decisions worth flagging**

- **Imperative `useState` + `useEffect` + `fetch`**, no SWR / react-query —
  matches CLAUDE.md and the rest of the repo. Don't refactor to a global
  cache layer for these three pages; if it becomes a real pain, that's a
  whole-app concern.
- **`'use client'` everywhere.** The pages use `use(params)` (the React
  hook) to unwrap Next.js 16's `params: Promise<...>` shape on the client.
  Server components weren't appropriate here — every page does interactive
  state (analyze flow, expand events, share modal).
- **Stage labels render directly from `JobStatus` enum values**, not a
  separate label list, so any new statuses added to the enum auto-render
  with their default name.
- **Re-analyze banner not implemented yet.** The spec calls for "New
  activity since last analysis · Re-analyze" when the live content_hash
  drifts from the persisted one. That requires a live-preprocess endpoint
  (or running preprocess on the page render). Skipped for now — the user
  can always click Re-analyze. Worth adding once we have real-world signal
  on whether activity drift is common.
- **No autocomplete on the share-recipient field.** Spec says "autocomplete
  from existing wulf-pulse user list if available". Skipped — the existing
  user list is in Better Auth's `user` table; exposing it requires a
  small API endpoint. Easy follow-up.
- **No navigation entry yet.** `components/navigation/app-navigation.tsx`
  doesn't yet have an "Analyzer" link. Adding that is a one-line edit; I
  left it for the operator to opt in once the feature is staged.
- **Printable analysis view** — the spec mentions "printable" for the
  analysis page. The current layout is print-friendly by accident (no
  fixed sidebars, sectioned cards), but no explicit `@media print` styles
  yet. Add when someone asks.

**Deliberately left out**

- No frontend tests. vitest is configured for `lib/**/*.test.ts` only; the
  pages and components are visually verified. Component tests with
  testing-library would be a separate setup decision.
- Analysis view doesn't auto-refresh while a job is running on a
  *different* version. If a user navigates to an old version while a new
  one is in progress, they don't see the in-progress state. Acceptable —
  the queue view + ticket history give that signal.

---

## Phase 7 — Share-via-email integration

**Delivered**

- `sendAnalysisShareEmail()` added to `lib/services/email.ts` — re-uses the
  existing nodemailer SMTP transport that already serves magic-link and
  invitation mail. Subject `Pulse analysis · <ticket> v<n> — <summary
  excerpt>`, gradient-header HTML body matching the other Pulse emails, plain
  text fallback, `replyTo` set to the sharer so a recipient reply lands with
  the right person.
- Share route `app/api/analyzer/analyses/[id]/share/route.ts` now resolves
  the sharer's session, builds the analysis URL from `BETTER_AUTH_URL`
  (falling back to `NEXT_PUBLIC_BETTER_AUTH_URL`, then `localhost:3100`),
  persists the audit row, then attempts the email send.
- Share-modal frontend handles the new `emailSent`/`emailError` fields:
  success → green toast; row-saved-but-send-failed → orange `toast.warning`
  carrying the SMTP error.

**Decisions worth flagging**

- **Audit row persists even if email send fails.** The `analyzer_shares`
  row is the audit log, not just a delivery receipt. SMTP outages should
  not erase the record that the user attempted a share.
- **Response is HTTP 200 on email failure.** The route returns
  `{share, emailSent: false, emailError}`. A non-2xx would imply the share
  itself failed; surfacing `emailSent: false` is the more honest signal.
- **No `email_sent_at` column added.** Adding it requires a migration and
  a way to retry — neither is asked for by the spec. Send state lives only
  in the response and the server log line `[ANALYZER-SHARE] email send
  failed for share <id>`. If retries become a real need, a dedicated
  `analyzer_share_email_attempts` table is the natural shape.
- **Used existing nodemailer SMTP, not Graph sendMail.** Spec said "via
  M365 Graph using existing wulf-pulse mail integration if one exists;
  otherwise use a new module" — `email.ts` *is* the existing module. The
  Graph integration in this codebase is read-only (mailbox search, user
  reports), not send-capable.
- **HTML escaping is hand-rolled.** Five-replace function for
  amp/lt/gt/quote/apos. The user-controlled fields (sender name, note,
  analysis summary, next step) all flow through it. The repo has no HTML
  escaper utility and the magic-link/invitation emails don't need one
  because their inputs are URLs and admin-set names.

**Deliberately left out**

- **No retries.** A failed send is logged once and surfaced to the user.
  They can re-share if they want — that creates a fresh audit row, which
  is correct behavior.
- **No tests.** `lib/services/email.ts` has no existing tests, mocking
  nodemailer fully would add a non-trivial test scaffold for one
  function, and the share route is route-handler thin. Consistent with
  phases 5/6.
- **No `viewed_at` tracking yet.** The migration has the column but
  nothing writes to it. A `/share/:id/viewed` endpoint with an
  unguessable token would be the smallest addition; spec didn't ask, so
  skipped.

---

## Phase 8 — Operator runbook

**Delivered**

- `docs/wulf-pulse-ticket-analyzer-runbook.md` — cost monitoring queries
  (daily spend, top expensive analyses, multi-run tickets), the cost
  ceiling explanation (`COST_CEILING_USD = 2.00` in `pipeline.ts`), the
  IT Glue alias workflow (where to find org IDs, how to verify via
  `model_traces.itglue.alias_used`), failure triage tables (failed jobs
  vs. `needs_human_review` flagged completes, with the actual error
  strings the worker emits), and a manual-ops section for queueing jobs
  from psql.
- README.md "Documentation" section links the runbook so operators
  finding the project for the first time discover it.

**Decisions worth flagging**

- **Runbook lives in `docs/`, not the README.** Per CLAUDE.md, long-form
  per-feature docs go in `docs/` and the README points to them. Matches
  the existing pattern (workflow-editor-guide, sync guides, etc.).
- **Manual migration step is documented.** Postgres only re-applies
  migrations on first init — operators applying analyzer to an existing
  DB need to run `psql -f migrations/069_*.sql`. The runbook leads with
  this.
- **Listed what's *not* implemented.** Retries, `viewed_at`, share
  `email_sent_at`, pre-Sonnet cost gate, share-recipient autocomplete.
  Better to advertise the gaps than have an operator trip over them.

**Deliberately left out**

- No production-monitoring dashboard (Grafana etc.) — Pulse doesn't have
  one for any other feature, and the SQL queries cover the same ground.
- No README expansion for the analyzer feature itself. Pulse's README is
  intentionally short; the runbook + spec + build notes are the deep
  docs.

---

## Phase 9 — Ticket browser + analysis-view formatting

Reactive to first-use feedback: the analysis page Summary / Next Step
text was bare and dense, and there was no way to discover tickets to
analyze without typing the URL.

**Delivered**

- `<ProseText>` helper inside `analysis-view.tsx` — splits text on blank
  lines, renders each chunk as a separate `<p>` with `leading-7` and
  `whitespace-pre-line`. Applied to Summary, Next Step, Next Step
  rationale, and Post-Resolution Analysis. Single-paragraph text still
  renders cleanly.
- Summary + Post-Resolution headers got an uppercase tracking-wide
  treatment to act as section dividers, and body text bumped to
  `text-base text-foreground` so it reads as a finding rather than a
  caption.
- Next Step card now has a subtle `bg-primary/5` tint, an `ArrowRight`
  icon next to "Recommended Next Step", a stronger separator before
  the rationale collapsible, and the rationale itself renders in a
  bordered indented block.
- New `/analyzer/tickets` browse page — pill-style period chips
  (Today, Yesterday, This week, Last week, Last 30/60 days, All time),
  a client (company) Select, an issue-type Select, and a debounced
  free-text search across ticket_number/title. Compact table with
  per-row Analyze/Re-analyze button (reusing `<AnalyzeButton>`) and a
  "View" button shortcut to the existing analysis when one is
  recorded. Active-filter count + clear-all in the filter card header.
- New API `GET /api/analyzer/tickets/list` — filters by `period`
  (computed in Postgres against `last_activity_date`), `companyId`,
  `issueType`, `search`. Returns 50 rows + total via `COUNT(*) OVER ()`,
  plus `latestAnalysisId` from a LATERAL join into `analyzer_analyses`.
- New API `GET /api/analyzer/tickets/filter-options` — companies that
  have at least one non-deleted ticket (drops dormant accounts) +
  active issue types ordered by `sort_order, label`.
- Top-level "Analyzer" nav menu added to `app-navigation.tsx`, with
  "Browse Tickets" + "Needs Review". Earlier phases left this off
  intentionally; this phase opts in.

**Decisions worth flagging**

- **Period filters on `last_activity_date`, not `create_date`.**
  "Today" surfaces tickets that had activity today (new tickets,
  re-opened, status churn) — much more useful for an analyzer-driven
  triage flow than tickets created today. A new ticket created today
  also has activity today, so we don't lose those.
- **Period math runs in Postgres via `date_trunc('day', NOW())` etc.**
  Database server-clock = app-process clock for an internal Docker
  stack, so naive timestamps and naive `NOW()` agree. If users
  complain about edge-of-day drift, swap to
  `NOW() AT TIME ZONE 'America/New_York'` — Pulse's primary user base.
- **Default period is `last_30d`.** "All time" pulls many thousands of
  rows; defaulting wide-open hurts first-page latency. 30 days hits
  ~7K rows in our DB, paginates cleanly.
- **Per-row analyze button reuses `<AnalyzeButton>` directly.** Each
  row gets its own component instance — no shared state, the running
  state lives per-button. The button navigates on completion, which
  feels right: click Analyze, watch the stages, land on the analysis
  page.
- **`force=true` is set automatically on tickets that already have an
  analysis.** Re-analyze should re-run, not short-circuit to the
  cached row. The "View" button covers the cached path.
- **No Linear/JIRA-style multi-select filters.** Single-value Selects
  are simpler and match the rest of Pulse.

**Deliberately left out**

- **No saved views.** A filter URL is shareable, but there's no
  bookmark / saved-view UX. Add when someone asks.
- **No `latest_analysis_status` exposure.** A failed analysis doesn't
  show up — the LATERAL join filters by `status='complete'`. So a
  ticket whose only analysis failed looks like an un-analyzed ticket.
  Acceptable: re-running is the intended action there anyway.
- **Search is `ILIKE '%...%'`.** No tsvector / trigram index. 7K-row
  scans are sub-100ms in this DB; if the corpus grows past low six
  digits, swap in `pg_trgm`.

---

## Status after each phase

| Phase | Tests | tsc | Notes |
|---|---|---|---|
| 1 | 0 | clean | migration + types only |
| 2 | 68 | clean | redaction + preprocessor regression |
| 3 | 100 | clean | + LLM scaffolding + Stage 1 |
| 4 | 128 | clean | + pipeline + worker |
| 5 | 128 | clean | API routes (no route tests) |
| 6 | 128 | clean | frontend (no FE tests) |
| 7 | 128 | clean | share email via existing SMTP transport |
| 8 | 128 | clean | operator runbook + README link |
| 9 | 128 | clean | browse page + analysis-view formatting + nav entry |

---

# Phase 2 (cross-ticket analysis)

Spec: `docs/ticket-analyzer-phase2-spec.md`. Eight sub-phases delivered as
one Phase 2 push.

## 2.1 — Schema additions

**Delivered**

- Migration 070: `analyzer_stage_executions` table (per-stage I/O for
  every analyzer run, including failed attempts) + three columns on
  `analyzer_analyses`: `source_snapshot`, `aggregate_fingerprint`,
  `fingerprint_generated_at`.
- `model_traces` column annotated with a `LEGACY` `COMMENT ON COLUMN`
  for the SQL side and a `// LEGACY` doc comment in TS — kept for
  back-compat until aggregate reports have soaked.
- Zod schemas: `AggregateFingerprint`, `StageName`, `StageExecution`
  (read-back), `StageExecutionRecord` (write-time interface).

**Decisions worth flagging**

- `analyzer_stage_executions.analysis_id` starts NOT NULL in 070.
  Migration 071 (Phase 2.6) relaxes it and adds the
  mutually-exclusive CHECK with `aggregate_report_id`.
- 070 is idempotent (`IF NOT EXISTS` on every object) so re-running
  against an already-applied DB is safe.

## 2.2 — Pipeline writes to stage executions

**Delivered**

- `recordedStage(meta, fn, callbacks, outputSelector)` helper in
  `pipeline.ts` wraps each stage call, emits a `StageExecutionRecord`
  on success or failure (re-throws after recording). Pipeline wires
  it into Stage 1 (triage), Stage 3 (analyze), Stage 4 (deep_review).
  Stage 0 (preprocess) and Stage 2 (itglue) are recorded inline since
  they're not LLM calls.
- Pipeline result now includes `triage_response`, `sonnet_response`,
  `opus_response` for downstream stages (Stage 6 fingerprint).
- Worker's `runJob` collects records via `onStageRecord` callback,
  bulk-inserts them after `insertAnalysis` succeeds. On pipeline
  throw, worker captures the preprocessed bundle via `onPreprocessed`
  callback, persists a `status='failed'` analyzer_analyses row with
  source_snapshot intact, and bulk-inserts the partial stage records
  linked to it.
- New persistence functions: `bulkInsertStageExecutions`,
  `insertFailedAnalysis`, `updateAnalysisFingerprint`.

**Decisions worth flagging**

- **Failure-tolerant audit**: spec says "Every stage that runs MUST
  insert a row, including stages that fail." We persist a failed
  analyzer_analyses row even on pipeline crash so the partial stage
  records have a parent. Without this the FK would be orphaned.
- **Single bulk insert**: ~5–6 stage rows per pipeline run. One
  multi-VALUES INSERT is fast enough; no need for COPY.
- **`model_traces` double-write retained**: the legacy column still
  receives the old payload. Drop it in a future migration once
  aggregate reports have soaked through prod.

## 2.3 — Prose formatting

**Delivered**

- Stage 3 system prompt updated with the markdown formatting rules
  from the spec verbatim (banned filler phrases, action-verb
  emphasis, no headers).
- `react-markdown@10`, `remark-gfm@4`, `@tailwindcss/typography@0.5`
  added. Tailwind 4 plugin registered via `@plugin
  "@tailwindcss/typography"` in `app/globals.css`.
- `<AnalysisMarkdown>` component at `components/analyzer/analysis-markdown.tsx`
  renders prose with `prose prose-sm dark:prose-invert
  max-w-none prose-p:leading-7`. Coerces stray model headers into
  bold paragraphs (the prompt forbids them but defense-in-depth).
- `<ProseText>` removed. Summary, Recommended Next Step,
  next_step_rationale, and post_resolution_analysis all use
  `<AnalysisMarkdown>`.

**Decisions worth flagging**

- Tailwind 4 syntax: `@plugin "@tailwindcss/typography"` in CSS, no
  JS config needed.
- Stage 3 prompt change is back-compatible — old analyses with
  plain-text summaries still render fine through ReactMarkdown.

## 2.4 — Stage 6 fingerprint + backfill CLI

**Delivered**

- `lib/services/analyzer/stages/stage6-fingerprint.ts` — Haiku call
  with the spec's verbatim system prompt. Server-overrides
  `generated_by_model` and `generated_at` after parse so the model's
  guess for those fields can't drift.
- Worker integration: after `insertAnalysis` succeeds, run
  fingerprint with try/catch. Failure logs a warn, fingerprint
  stays NULL on the row, but the analysis is still complete and
  usable. The fingerprint stage record is added to the bulk insert
  whether it succeeded or failed.
- `scripts/backfill-fingerprints.ts` — idempotent CLI. Reads
  `analyzer_analyses.model_traces.{triage_response, sonnet_response,
  opus_response}` (which Phase 1 was already storing), runs Stage 6,
  writes `aggregate_fingerprint`. Supports `--dry-run` and
  `--limit=N`. Skips analyses where model_traces is incomplete.

**Decisions worth flagging**

- Stage 6 input is just the analysis content (triage + sonnet +
  optional opus). No `pre` payload needed — fingerprinting is about
  the produced *analysis*, not the source ticket.
- Backfill processes oldest-first (triggered_at ASC). Lets us
  observe a few rounds before chewing through hundreds.
- Stage 6 failure is non-fatal. Spec: "If fingerprinting fails, do
  NOT fail the overall analysis."

## 2.5 — Browse / filter UI rebuild

**Delivered**

- New endpoint: `GET /api/analyzer/tickets` (replaces the simpler
  `GET /api/analyzer/tickets/list` from Phase 1.9). Multi-select
  CSV-style query params (clientId, issueType, queue, status,
  priority, assignedTo); analyzed segmented filter (any/yes/no/stale);
  needsReview toggle; search; sort.
- `/api/analyzer/tickets/filter-options` extended with queues,
  statuses, priorities, resources (joined to "has at least one
  ticket" so the dropdowns aren't padded).
- New `<MultiSelect>` component at `components/ui/multi-select.tsx`
  — Popover + checkbox list with optional search box (auto-shown
  above 8 options). One trigger + one popover, no shadcn Command
  dependency.
- `/analyzer/tickets` page rebuilt:
  - Sticky filter bar with period pills, multi-selects, search,
    analyzed segmented, needs-review checkbox, sort
  - Active-filter chips (click to clear individual filter)
  - Bulk selection persisted via localStorage (key
    `analyzer:ticket-selection:v1`) — survives pagination
  - "Analyze N selected" — sequential job queue, forces re-analyze
    on `stale` rows
  - "Generate aggregate report" — routes to `/analyzer/reports/new`;
    only enabled when all selected are `current`
- Top nav reorganized: Browse Tickets / Aggregate Reports / Needs
  Review under "Analyzer".

**Decisions worth flagging**

- **Staleness via `last_activity_date > completed_at`**, not
  content-hash compare. The spec lets either; the date heuristic is
  good enough and avoids per-row preprocessing on 50-row paginated
  responses.
- **`MultiSelect` is a one-popover-per-instance design** — multiple
  popovers can be open across the bar. Acceptable; matches how
  Linear / Vercel's table filters behave.
- **No "Select all matching filters" semantic**. Selection is an
  explicit per-row action stored as ticket numbers in localStorage.
  Filter-level selection adds significant complexity (server has to
  resolve filter→IDs, two-modes everywhere). Skipped for V1; the
  spec's intent (don't lose selection on pagination) is met.
- **Bulk Analyze is sequential, not parallel.** N concurrent calls
  would all hit `claimQueuedJob` and the worker would process them
  one at a time anyway (single in-process worker). Sequential POSTs
  are more honest about that.

## 2.6 — Aggregate reports

**Delivered**

- Migration 071: `analyzer_aggregate_reports` table + ALTER on
  `analyzer_stage_executions` to drop NOT NULL on `analysis_id`,
  add `aggregate_report_id` FK, add the
  `analyzer_stage_executions_parent_check` CHECK constraint
  (`(analysis_id IS NOT NULL) <> (aggregate_report_id IS NOT NULL)`).
- `lib/services/analyzer/stages/aggregate-reduce.ts` — Sonnet (Opus
  opt-in) reduce stage with the spec's verbatim system prompt and
  `AggregateReduceResponse` Zod schema.
- `lib/services/analyzer/aggregate-persistence.ts` — `createAggregateReport`,
  `getAggregateReport`, `listAggregateReports`, `runAggregateReport`,
  `bulkInsertReportStageExecutions`. The runner is fire-and-forget
  (called via `void runAggregateReport(id)` from the POST endpoint);
  it persists distributions immediately so the UI can show partial
  results during the LLM call.
- IT Glue context fetcher: per-client `findOrganizationByName` +
  `getFlexibleAssets`, capped at 200 doc titles total per spec.
  Failure tolerant — per-client errors don't fail the report.
- API endpoints:
  - `POST /api/analyzer/aggregate-reports` — validates (≤100,
    fingerprint exists, not stale), creates pending row, fires runner
  - `GET  /api/analyzer/aggregate-reports/:id` — full report row
    (UI polls this every 3s while pending/running)
  - `GET  /api/analyzer/aggregate-reports` — paginated list
- Pages:
  - `/analyzer/reports/new?ids=T...,T...` — pre-flight: shows
    selected tickets, options (title, IT Glue context toggle),
    Generate button
  - `/analyzer/reports/[id]` — pending → distributions → completed.
    Sections: header, executive summary, four distribution mini-bar
    cards, documentation gaps (with `itglue_check` color tone),
    process gaps (severity tone), recurrence clusters, recommended
    actions (sorted by priority), narrative summary.
  - `/analyzer/reports` — table list of past reports

**Decisions worth flagging**

- **Fire-and-forget runner**, no separate worker module. The POST
  endpoint kicks `void runAggregateReport(id)`; updates land in the
  row when the LLM call completes. Frontend polls. Avoids adding a
  second polling worker alongside `analyzerWorker`.
- **Stage names reused for aggregate sub-stages.** The CHECK constraint
  on `analyzer_stage_executions.stage` enumerates the per-analysis
  stage names. Aggregate sub-stages (SQL aggregation, IT Glue context,
  reduce LLM) are recorded with `stage='analyze'` / `'itglue'` plus
  `aggregate_report_id` set. A future migration could add
  `aggregate_sql` / `aggregate_reduce` to the enum and re-emit those
  rows; for now the existing names are good enough for forensics.
- **`generated_by_user_id` is TEXT nullable**, not `uuid NOT NULL`
  per spec. Better Auth's `user.id` is text, and we want the report
  to remain readable if the generating user is later deleted —
  matches the pattern from `analyzer_analyses.triggered_by_user_id`.
- **Distributions persist before LLM call** so partial-state UI
  doesn't have to wait the full 30–90s for anything to render.

## 2.7 — Cost guards

**Delivered**

- Migration 072: `analyzer_cost_audit` table.
- `lib/services/analyzer/cost-guard.ts`:
  `estimateAggregateReportCost`, `getUserDailySpend`, `evaluateCost`,
  `recordCostAuditDecision`. Thresholds: `REQUIRES_CONFIRMATION_USD = 5`,
  `SOFT_WARN_DAILY_USD = 20`, `HARD_BLOCK_DAILY_USD = 50`.
- `evaluateCost` produces a four-state decision (`approved` /
  `requires_confirmation` / `blocked` / `overridden`) plus boolean
  `softWarn`/`hardBlocked`/`requiresConfirmation`/`isOverride`
  fields the API can return for UX.
- POST `/api/analyzer/aggregate-reports` enforces:
  - `requires_confirmation` → 400 with `requiresConfirmation:true,
    estimatedCost, dailySpendBefore` so the frontend can show
    `confirm()` and re-POST with `confirmedCost:true`.
  - `blocked` → 403 with the daily spend in the body.
  - Every decision (including `approved`) writes a row to
    `analyzer_cost_audit`.
- Override env var `ANALYZER_DAILY_COST_OVERRIDE_USERS`
  (comma-separated user ids).
- Frontend new-report page: catches `requiresConfirmation`,
  shows `window.confirm()` with the dollar figure, retries with
  `confirmedCost: true`.

**Decisions worth flagging**

- **Cost estimate is char/4 → tokens × Sonnet pricing.** Crude but
  pessimistic in the right direction. At 100 tickets the estimate
  comes in under $0.50 — far below the $5 threshold — so the
  confirmation modal almost never fires in practice. Ceiling exists
  to catch payload bloat / Opus-opt-in scenarios.
- **Daily window is trailing 24h, not "today UTC".** Avoids
  midnight-edge-of-day reset gaming; rolling window is what the
  spec calls "$X/day" naturally.
- **Soft warn at $20/day is informational only.** Fields exposed
  in the cost evaluation; UI can choose to surface, but the API
  doesn't refuse to proceed. Hard block at $50/day is the only
  enforcement.

## 2.8 — Documentation

**Delivered**

- `docs/wulf-pulse-ticket-analyzer-runbook.md` — added Phase 2
  sections covering stage execution forensics, fingerprint backfill,
  aggregate report flow + SQL queries, cost guard configuration +
  override env var, and the rebuilt browse UI behavior.
- This file — the per-sub-phase notes above.

---

## Status after Phase 2

| Phase | Tests | tsc | Notes |
|---|---|---|---|
| 2.1 | 128 | clean | schema (070) |
| 2.2 | 128 | clean | stage_executions writes + failure-tolerant persistence |
| 2.3 | 128 | clean | markdown rendering + Stage 3 prompt |
| 2.4 | 128 | clean | Stage 6 fingerprint + backfill CLI |
| 2.5 | 128 | clean | browse UI rebuild |
| 2.6 | 128 | clean | aggregate reports (071, runner, 3 endpoints, 3 pages) |
| 2.7 | 128 | clean | cost guards (072, audit log, threshold gating) |
| 2.8 | 128 | clean | runbook + build notes |

---

## Phase 3 — Link-aware bundle analysis

**Why**

Single-ticket analysis misses the bigger picture for master/problem tickets,
which are explicitly aggregator records — a "Master problem ticket" with a
`RELATED TICKETS:` block in its description naming the constituent
incidents. Aggregate reports already existed (Phase 2.6) but required the
user to pre-analyze every constituent and hand-pick them on
`/analyzer/reports/new`. Phase 3 closes the gap: one click on a problem
ticket fans out individual analyses for each linked ticket and chains them
into an aggregate report.

**Delivered**

- `migrations/073_analyzer_link_aware_bundles.sql`:
  - `analyzer_aggregate_reports.expected_ticket_numbers TEXT[]` — the full
    set of ticket numbers a bundle is waiting on.
  - `analyzer_aggregate_reports.triggered_by_ticket_number TEXT` — the
    master ticket the bundle was launched from.
  - Status check extended to include `'pending_analyses'` (waiting for
    individual analyses) before transitioning to `'pending'` (ready for
    aggregate-reduce).
  - Replaced the partial pending-status index to cover the new state; added
    a GIN index on `expected_ticket_numbers` filtered to
    `pending_analyses` for the worker chain-trigger lookup.
- `lib/services/analyzer/link-discovery.ts`:
  - **Explicit arm** (no LLM, deterministic): regex scan over the ticket
    description and each retained note for `T\d{8}\.\d{4}` references,
    detection of the structured `RELATED TICKETS:` block (refs inside it
    flagged `confidence: 'high'`), and resolution of
    `tickets.problem_ticket_id` to a ticket number. Self-references and
    refs not present in the local mirror are dropped silently. Capped at
    `MAX_EXPLICIT_LINKS = 15`.
  - **Suggested arm** (Haiku, opt-in): one LLM pass over recent
    same-company tickets (±30 days, capped at 50 candidates). Returns up
    to 5 candidates with one-sentence reasons. Hallucination-guarded —
    drops any number not in the candidate list.
  - `detectProblemTicket()` returns boolean + signal list; UI uses signals
    to decide whether to highlight the bundle CTA as the primary action.
- `app/api/analyzer/tickets/[ticketNumber]/links/route.ts`:
  - `GET` returns the explicit arm only (cheap, called on page load).
  - `POST { includeSuggested: true }` runs both arms.
- `app/api/analyzer/tickets/[ticketNumber]/analyze-bundle/route.ts`:
  - Validates master + linked tickets exist locally (single SQL roundtrip).
  - Runs per-ticket idempotency: existing complete analyses with matching
    content hash short-circuit; missing tickets are queued via the existing
    `queueJob()` helper.
  - Cost guard runs against the **new work only** — already-complete
    analyses don't add cost. Per-ticket estimate is a flat $0.15
    (Sonnet-tier pessimistic) plus `estimateAggregateReportCost()` for the
    reduce step.
  - Creates one `analyzer_aggregate_reports` row in
    `'pending_analyses'` (or straight to `'pending'` and fires
    `runAggregateReport()` if everything was already complete).
  - Bundle cap: `MAX_BUNDLE_SIZE = 25`.
- `lib/services/analyzer/aggregate-persistence.ts`:
  - `createAggregateReport` accepts `expectedTicketNumbers` and
    `triggeredByTicketNumber`. When set, status starts as
    `'pending_analyses'`.
  - `chainTriggerForCompletedAnalysis(ticketNumber, analysisId)` — called
    by the worker after each successful job. Atomically appends the
    analysis_id to every pending_analyses bundle expecting that ticket
    (deduped via `analysis_ids @> ARRAY[…]` guard) and re-checks whether
    the full set is now satisfied. Returns `readyReportIds` for the worker
    to fire `runAggregateReport()` on.
- `lib/services/analyzer/worker.ts` — chain-trigger fires from both
  the success branch and the idempotent-short-circuit branch (the bundle
  endpoint's idempotency check happens at submit time, but a parallel
  analysis can complete between then and when the worker picks the job
  up). Failures here are logged but never fail the underlying job.
- `components/analyzer/related-tickets-panel.tsx` — renders above the
  existing `<AnalyzeButton>` on `/analyzer/ticket/[ticketNumber]`:
  - Cheap GET on mount populates the panel only when refs exist or the
    ticket looks like a problem ticket — otherwise the component renders
    nothing.
  - Pre-checked checkboxes for explicit refs; Switch toggle to load
    AI-suggested refs (additive, suggestions show with a badge,
    unchecked by default).
  - Primary CTA is bundle ("Analyze with N linked tickets") highlighted
    when `isProblemTicket=true`. Single-ticket flow is preserved
    untouched on the existing AnalyzeButton in the parent header.
  - Polls `GET /api/analyzer/aggregate-reports/:id` every 3s after submit;
    routes to `/analyzer/reports/:id` on completion.
- `lib/services/analyzer/link-discovery.test.ts` — 18 new tests covering
  the regex, RELATED TICKETS section bounds, problem-ticket signal
  detection, dedup/self-skip, mirror filtering, `MAX_EXPLICIT_LINKS` cap,
  and confidence-based sorting.

**Decisions worth flagging**

- **Bundle is opt-in via the panel, not auto.** A ticket that mentions
  another ticket once in passing (e.g. "see T20260101.0001 for context")
  shouldn't quietly trigger 2× the LLM cost on every analysis. The panel
  is the consent surface — pre-checked when explicit refs exist, but the
  user explicitly picks the CTA.
- **`RELATED TICKETS:` is a strong signal, not a parser-required format.**
  The regex catches T-numbers anywhere; the structured block just
  promotes them to high confidence and acts as a problem-ticket signal.
  No new format is imposed on whoever writes the master ticket.
- **Suggested arm uses Haiku, not Sonnet.** ~$0.005 per call against the
  $5 per-request confirmation threshold — never trips the modal. We never
  fail the whole call if the suggestion arm throws (logged-and-suppressed
  via try/catch in `discoverLinks`).
- **Per-ticket cost estimate is flat $0.15.** We could compute it from the
  preprocessed event count, but at the bundle's typical size (3-10
  tickets) that's $0.45 – $1.50 — far below the $5 confirmation
  threshold. Worth revisiting if we see real false-positive blocks.
- **`pending_analyses` is the new status, distinct from `'pending'`.**
  Explicit two-step state lets the runner stay simple — it never has to
  ask "are all my analyses ready?" — that gate is the chain-trigger's
  job. Existing manual-multi-select reports continue to start at
  `'pending'`; their flow is untouched.
- **`expected_ticket_numbers` matches via array containment, not a
  separate join table.** Postgres GIN gives us O(log n) lookup and the
  data lives where it's used — no new table, no foreign-key cascade
  decisions to make.
- **Self-references and unknown tickets are dropped silently.** The user
  isn't asked to pick from a list; they get a clean "you have N linked
  tickets" panel. A ghost reference (T-number that doesn't exist in the
  mirror) is a sync gap, not a bundle decision.
- **Fixture migration: `T20260424.0045.input.json` updated** to include
  `problem_ticket_id: null` so the type-strict load through the
  preprocessor still parses. The column is nullable in the data-access
  query and on the row type.

**Deliberately left out**

- No retroactive linking for already-completed analyses. If a master
  ticket got a single-ticket analysis before this shipped, the user
  re-runs from the panel to bundle.
- No editing the bundle composition after submit. Re-run with a different
  selection if you want a different scope.
- No time-window auto-correlation arm (e.g. "all tickets at this client in
  the last 6 hours"). At Hynes Industries on 2026-05-01 we observed 84
  tickets in one day — auto-grouping by time would have been useless
  noise. Same-company time-window ranking is what the Haiku suggested arm
  is for.
- No UI for the `/analyzer/reports/[id]` page to flag itself as a "bundle"
  vs a manual report. The new fields are surfaced in the API response but
  the page renders the same regardless.

## Status after Phase 3

| Phase | Tests | tsc | Notes |
|---|---|---|---|
| 3 | 146 | clean | link discovery, bundle endpoint, chain-trigger, panel (073) |

---

## Phase 4 — IT Glue asset audit + documentation write-back

**Why**

Single-ticket analysis already extracts `documentation_gaps_observed` per
ticket (in `aggregate_fingerprint`), but nothing acts on them. The companion
direction — audit IT Glue records *against* ticket history — converts a
passive output into an actionable backlog and offers direct write-back.
Concrete proof: T20260502.0033 (Hynes — tags not printing) was resolved by
identifying a stopped Windows service on MISYS-SQL processing BarTender
scan-folder text files. The IT Glue record `MISYS 6.3` (asset 17096940) had
12/17 fields empty — including Wulf Application Champion and Vendor
Maintenance/Support — so the next tech with this issue would re-discover
everything.

**Delivered**

- `migrations/075_itglue_audit.sql` — two new tables:
  - `itglue_asset_audits` — one row per audit run with full LLM context
    snapshot (asset traits at audit time, redacted), the gaps/promotions/
    contradictions output, and cost.
  - `itglue_writes` — one row per PATCH attempt; before/after diff, who, when,
    status pending → committed | failed | reverted, audit_id provenance,
    raw IT Glue API response, source_evidence (tickets that prompted the gap).
- `lib/services/itglue-client.ts`:
  - `updateFlexibleAsset(id, traits)` — PATCH /flexible_assets/:id with
    JSON:API body.
  - `refreshFlexibleAsset(id)` thin wrapper around getFlexibleAsset.
  - `getRawSingle(path, params)` — for callers that need raw attributes
    (created-at/updated-at) for upserts.
  - `isITGlueConfigured()` helper.
  - Internal `patch(path, body)` mirrors the existing `request` pattern.
- `lib/services/itglue-sync-service.ts`:
  - `refreshFlexibleAssetById(id)` per-record sync helper. Avoids running
    the full 27-entity `fullSync()` after every write.
- `lib/permissions.ts`:
  - New `itglue: ['read', 'write']` permission. Admin + super-admin get write;
    user gets read-only.
- `lib/services/analyzer/asset-audit/`:
  - `data-builder.ts` — collects all six context arms: asset snapshot,
    field schema with hints, peer exemplars same-client (top 5 by trait
    fill count), peer exemplars across all clients (top 3), per-field
    fill-rate stats (per-client + global), recent ticket fingerprints
    matching the asset's name. Redacts asset traits + every peer.
  - `prompt.ts` — single Sonnet/V4 Pro call; system prompt categorizes
    findings into field_gaps / notes_promotions / contradictions; refuses
    to suggest credential-shaped fields. Payload cap 80KB; trims peer_global
    first, then oldest tickets.
  - `runner.ts` — `runAssetAudit({assetId, generatedByUserId, provider})`.
    Provider-aware via `stageModelsFor(provider).deep_analysis`. Persists
    `itglue_asset_audits` row (or `failed` row on throw).
  - `persistence.ts` — typed read/write of both tables; `fieldNameToTraitKey()`
    helper matches IT Glue's `lower-hyphen-strip` convention.
  - `runner.test.ts` — 12 unit tests covering fillCount semantics, trait-key
    conversion, AssetAuditResponse Zod validation, payload trimming.
- API routes:
  - `GET /api/analyzer/itglue/applications` — list of all Application records
    joined to latest audit, ordered worst-score-first.
  - `GET /api/analyzer/itglue/applications/[id]` — asset detail with field
    schema (the renderer uses field order + populated state).
  - `GET /api/analyzer/itglue/applications/[id]/audit?history=1` — latest
    audit + history.
  - `POST /api/analyzer/itglue/applications/[id]/audit` — runs a fresh audit;
    cost-guard via `recordCostAuditDecision({action:'itglue_audit'})`.
  - `POST /api/analyzer/itglue/applications/[id]/apply` — admin-only; inserts
    pending row, calls IT Glue PATCH, marks committed/failed, refreshes
    mirror, writes generic audit_log row.
  - `POST /api/analyzer/itglue/applications/[id]/revert/[writeId]` — admin-only;
    inserts a new write row with reversed before/after, applies, marks
    original status='reverted'.
  - `GET /api/analyzer/itglue/applications/[id]/writes` — auth-only per-asset
    history.
  - `GET /api/analyzer/itglue/writes` — admin-only cross-asset write log.
- UI:
  - `/analyzer/itglue/applications` — list with score badges + filter input.
  - `/analyzer/itglue/applications/[id]` — asset header (with link to IT Glue),
    audit panel (gaps with severity-toned cards, notes promotions,
    contradictions), current fields rendered with hints for empty ones,
    write history with revert button, audit history with score timeline.
    `<ProviderToggle/>` reused from Phase 3.
  - `/admin/itglue-writes` — admin-only global write log with status filters.
  - Navigation: new "IT Glue audit" entry under the Analyzer dropdown.

**Audit-trail design**

Three layers of trail, all permanent:

1. `itglue_asset_audits` — every audit run with full LLM context.
2. `itglue_writes` — every write attempt. Before/after, who, when, status,
   audit provenance. Reverts produce a new row with reversed diff; original
   row → `status='reverted'`. The chain is always traceable.
3. Generic `audit_log` (existing migration 014) — written in parallel via
   `audit.log()`. Action `itglue.write` / `itglue.revert`, resource
   `flexible_asset`, resourceId = asset_id, details = `{ field_name, before,
   after, audit_id }`. Surfaces in `/admin/audit-log` next to every other
   admin action.

**Decisions worth flagging**

- **Two domain-specific tables, not one generic events table.** Audits
  carry full LLM context (heavy, infrequent). Writes are atomic per-field
  decisions with hard-typed before/after diffs. The generic `audit_log`'s
  free-form JSONB doesn't model the diff cleanly — but we still write to it
  so admins see a unified feed.
- **Admin-direct write, no two-step approval.** Per the user's call. The
  audit log is the safety net. We left `approval_requests` as a possible v2
  if mistakes start happening.
- **Per-record sync helper instead of `fullSync()` after every write.**
  `refreshFlexibleAssetById()` does one GET + one upsert. Keeping
  `fullSync()` available for ops + scheduler; bypassing it on the write
  path keeps Apply latency under a second after the IT Glue PATCH lands.
- **Credential refusal at three layers.** Prompt instructs the LLM not to
  suggest password/secret/key/token/credential fields. The Apply endpoint
  also regex-blocks any field name matching that pattern. The `redact()`
  utility from `itglue-redact.ts` strips matching keys from any payload
  flowing into the LLM in the first place.
- **Trait-key derivation in code, not hard-coded.** IT Glue's convention is
  field-name lowercased, non-alphanum → single hyphen, stripped. We compute
  this from each field's `name` (verified against the live Hynes MISYS 6.3
  trait map). If a future field doesn't match the rule, it'd surface as an
  unmatched fill-rate / value-not-applied — easy to spot.
- **Fill-rate computation in JS, not SQL.** Avoids one query per field. At
  the example data volume (~92 active Hynes assets, ~few-thousand globally
  per type) this stays sub-100ms; can revisit if it grows.
- **Peer-exemplar ranking by populated-key count.** Cheap proxy for
  "well-documented." Doesn't penalize asset types whose fields are
  legitimately optional. If the LLM starts producing strange suggestions
  we can refine to require/expected-field weighting.
- **Asset detail page renders from local mirror, not IT Glue API.** Means a
  user could see a stale value for a few seconds between Apply and the
  per-record sync landing. Acceptable for a read view; the API response
  from Apply returns the freshly-PATCH'd asset so the UI can immediately
  reflect the new state.

**Deliberately left out**

- v1 covers Applications only (`flexible_asset_type_id = 3790`). The schema
  generalizes (`asset_type` is a column), but Configurations / Procedures /
  Domains have different shapes and prompts. One type at a time.
- No bulk-apply. Admin clicks each suggestion. If a single audit produces 10
  gaps that's 10 clicks — fine for v1; bulk-apply is an easy follow-on.
- No two-step approval workflow.
- No auto-create of new asset records — Apply only updates existing.
- No inline editor for suggested values — admin sees the LLM's suggestion
  verbatim and clicks Apply, then edits in IT Glue if they want to tweak.
- Passwords / Secrets / Keys / Tokens / Credentials: never written via
  this surface, ever. Refused at prompt + endpoint + redaction layers.

## Status after Phase 4

| Phase | Tests | tsc | Notes |
|---|---|---|---|
| 4 | 158 | clean | IT Glue asset audit (075), runner + 6 endpoints + 3 pages, write-back with revert |

---

## Phase 4.1 — Ticket-first capture + Configurations + cross-reference index

**Why**

Phase 4 was asset-first (admin browses worst-scoring records). Phase 4.1
flips perspective: every time we analyze a ticket, learn whether *this
ticket* taught us something documentable. Plus extends write-back to IT
Glue **Configurations** (servers, workstations, devices) — the prior
flexible-asset-only scope missed records like MISYS-SQL where the
T20260502.0033 root cause actually lived. Plus a cross-reference table so
both perspectives become one-query lookups, and the future RAG automation
has its lookup index.

**Delivered**

- `migrations/076_itglue_ticket_xrefs.sql`:
  - `triggered_by_ticket_number` + `triggered_by_analysis_id` on
    `itglue_asset_audits`; `triggered_by_ticket_number` on `itglue_writes`
    (denormalized per user's call so "every write a ticket drove" is a
    direct query).
  - asset_type CHECK extended to include `'configuration'` on both audit +
    write tables.
  - New `itglue_ticket_xrefs` table — ticket↔asset linkage with
    relationship type (`referenced` | `updated` | `should_have_referenced`),
    source (`analyzer_referenced` | `audit_write` | `manual`), unique
    constraint preventing dup ingestion.
- `lib/services/itglue-client.ts`:
  - `updateConfiguration(id, attributes)` — PATCH /configurations/:id with
    flat JSON:API attributes (no traits blob).
  - `refreshConfiguration(id)` thin wrapper.
- `lib/services/itglue-sync-service.ts`:
  - `refreshConfigurationById(id)` per-record refresh (mirrors the bulk
    syncConfigurations 33-column upsert).
- `lib/services/analyzer/asset-audit/`:
  - `data-builder.ts` generalized: dispatches on `assetType`, supports
    `ticketScopeAnalysisId` for ticket-first audits. Configurations get a
    hand-curated 16-field schema with hints (since IT Glue Configurations
    don't have a `_fields` table). Synthesizes a "traits" map from flat
    columns so the prompt stays type-agnostic.
  - `prompt.ts` — two system prompts (Application-flavored vs
    Configuration-flavored, the latter focused on hostname/FQDN, OS
    currency, named services, IP/MAC, contact ownership). Ticket-scoped
    suffix when an analysis is the source so the LLM frames findings as
    "what did this ticket teach us?"
  - `runner.ts` accepts `assetType`, `ticketScopeAnalysisId`; persists
    `triggered_by_*` columns.
  - `persistence.ts` — `asset_type` union extended; new `getLatestTicketScopedAudit`
    helper for the analysis-page panel; `createPendingWrite` accepts asset_type
    + triggered_by_ticket_number.
  - `xrefs.ts` (new) — bulk-insert helpers: `insertReferencedXrefsFromAnalysis`
    (post-analysis hook), `insertUpdatedXref` (post-apply hook), with
    listXrefsForAsset / listXrefsForTicket queries.
  - `asset-matcher.ts` (new) — given an analysis_id, returns matched
    flexible_assets + configurations for the ticket's client based on
    fingerprint terms (applications_involved, device_classes, vendors_involved).
    Score = exact (3) > word-boundary (2) > substring (1); top 5 per kind.
- `lib/services/analyzer/worker.ts` — post-analysis hook calls
  `insertReferencedXrefsFromAnalysis` for every doc the LLM cited;
  best-effort, never fails the job.
- API routes:
  - `GET /api/analyzer/analyses/[id]/itglue-suggestions` — match assets +
    return any existing ticket-scoped audits keyed by (assetType, assetId).
  - `POST /api/analyzer/analyses/[id]/itglue-suggestions` — body
    `{ assetType, assetId, provider }`, runs a ticket-scoped audit.
  - Full Configurations route tree mirroring Applications: list, detail,
    audit (GET/POST), apply (admin), revert (admin), writes, xrefs.
  - `GET /api/analyzer/applications/[id]/xrefs` (new) and
    `GET /api/analyzer/tickets/[ticketNumber]/itglue-xrefs` (new).
- UI:
  - `<ItglueSuggestionsPanel/>` rendered on the analysis detail page.
    Opt-in trigger ("Check IT Glue documentation"); shows matched
    Applications + Configurations grouped, per-asset ticket-scoped audit
    buttons, inline gap cards with Apply (admin-only), score badges.
    Reuses `<ProviderToggle/>` from Phase 3.
  - `/analyzer/itglue/configurations` — list mirroring Applications.
  - `/analyzer/itglue/configurations/[id]` — detail mirroring Applications,
    plus the new "Tickets that touched this configuration" section.
  - Application detail page — added the same xref section.
  - Navigation split into "IT Glue — Applications" + "IT Glue — Configurations".

**Decisions worth flagging**

- **Two separate Configuration write methods + two route trees instead of
  one polymorphic surface.** The codebase has no other `[assetType]`-style
  polymorphism; existing patterns favor parallel resource paths. Added
  ~80 LOC duplication on the page side, but each surface is independently
  testable + obvious in URL routing.
- **Configuration field schema is hand-curated**, not loaded from IT Glue.
  IT Glue exposes flexible-asset field metadata via `/flexible_asset_fields`
  but Configurations have no equivalent endpoint. The 16 hand-written
  hints (in `data-builder.ts`) are what the LLM sees as field documentation.
  Versioned in code; PR review is the change control.
- **Apply on Configurations is column-allowlisted.** Even with the audit
  pipeline picking `field_name`, the apply route refuses anything outside
  `name | hostname | primary_ip | mac_address | serial_number | asset_tag |
  position | notes | operating_system_notes`. Stops the LLM from suggesting
  edits to read-only/derived fields like `manufacturer_id` (which is an FK
  resolved by IT Glue, not a free-text field).
- **xref ingestion happens in the worker after a successful analysis**,
  not as a separate batch job. Best-effort wrap means a transient DB
  hiccup never fails the analysis itself. The unique index on the xref
  table ensures retries are idempotent.
- **ticketScopeAnalysisId narrows ticket evidence to one row.** This is
  the key prompt-shaping decision for Phase 4.1: the LLM sees just the
  one analysis the user clicked from, plus the asset state + schema + peer
  exemplars. Findings frame as "what *this ticket* revealed" rather than
  all-time history.
- **No backfill of existing analyses.** Per user's call. The xref table
  fills forward; backfill is a future opt-in script if needed.
- **Asset matching is loose** — substring + word-boundary. A ticket
  mentioning "MISYS" matches both `MISYS 6.3` (the Application) and
  `MISYS-SQL` (the Configuration), and the user picks per-asset which to
  audit. Less false-negative-y than strict matching; user controls
  confirmation.
- **Configuration audits don't write to manufacturer/model/OS-name/contact/location**
  — those are FK fields IT Glue resolves by id, not free-text. The
  audit prompt can suggest changes but Apply blocks them. Future iteration
  could resolve names → ids via the IT Glue manufacturers/models endpoints.

**Deliberately left out**

- **Datto RMM script execution** (Phase 4.2 — separate plan). Ability to
  run PowerShell via Datto RMM Overshell on Wulf Nurse endpoints to gather
  fresh evidence (DHCP scopes, DNS zones, AD info, named services) and
  feed it into the audit pipeline. Decisions logged: generic Overshell
  component + Pulse-managed scripts; admin-direct with audit log; new
  `rmm.execute` permission.
- No backfill of the xref table.
- No bulk-apply across multiple gaps; admin clicks each one.
- No two-step approval workflow. Audit log + role gating remain the
  safety net.
- No Configuration write for FK-shaped fields (manufacturer, model, OS,
  contact, location) — only flat editable columns.

## Status after Phase 4.1

| Phase | Tests | tsc | Notes |
|---|---|---|---|
| 4.1 | 160 | clean | xref table (076), Configurations parity, ticket-first capture, analysis-page panel |

---

## Phase 4.2 — Datto RMM Overshell evidence pipeline

**Why**

Phase 4.1 wires ticket history + IT Glue field schemas into LLM-driven
documentation suggestions. The next leverage point is **fresh evidence
from the live environment** — service lists, AD health, DHCP scopes, DNS
zones, event logs — that ticket history can't surface. Without it, audits
flag "the named service that processes BarTender scan-folder text files
isn't documented" but can't suggest the actual service name. With it, we
suggest the literal value pulled from the running server seconds ago.

The proven test case: openclaw produced an AD health summary at Hynes
around 2026-04-25 (IP conflicts, ZR006 missing trust account, DNS
forwarders timing out, Hendricks site missing site-links) by orchestrating
Datto RMM Overshell. Phase 4.2 lets Pulse produce the same intel directly
from a button on the asset page, store it, and feed it back into audits.

**Delivered**

- `migrations/077_rmm_overshell.sql`:
  - `rmm_settings` singleton — caches the discovered Overshell `component_uid`,
    `component_name`, `variable_name` (default `CommandLine`).
  - `rmm_executions` — full lifecycle row per dispatch: queued → running →
    complete | failed | timeout. Captures `target_device_uid`,
    `target_hostname`, `target_company_id`, optional audit/asset linkage,
    `job_uid`, raw stdout/stderr (redacted), `parsed_evidence`, exit code,
    `timeout_at`. 8 indexes covering all query paths the audit pipeline +
    UI need.
- `lib/services/rmm/scripts/`:
  - 7 v1 scripts, all read-only. Each is a typed `RmmScript` exporting
    `body` (PowerShell), `target_type`, `parseOutput`, `expected_runtime_seconds`,
    `version`. Bodies end with `ConvertTo-Json -Depth … -Compress` so the
    parser is just `JSON.parse`. Registry validates uniqueness at load.
  - asset_self: `get-services`, `get-installed-software`, `get-event-log-recent`.
  - site_anchor: `get-ad-health` (mirrors the openclaw test case),
    `get-dhcp-scopes`, `get-dns-zones`, `get-network-discovery` (catches
    the IP-conflict pattern from the proven test case).
- `lib/services/rmm/target-resolver.ts`:
  - `resolveSiteAnchorTarget(companyId)` — looks up `datto_rmm_sites`
    where `autotask_company_id = $1`, finds devices matching
    `^[A-Z]{3}[A-Z]{3}WNP\d{2}$`, picks online + lowest numeric suffix.
  - `resolveAssetSelfTarget(deviceUid)` — direct lookup.
  - `resolveDeviceByHostname(hostname)` — fallback when an IT Glue
    Configuration's `rmm_id` doesn't resolve cleanly.
- `lib/services/rmm/settings.ts`:
  - `discoverOvershellComponent()` — calls
    `client.findOvershellComponent(/overshell/i)` and persists the uid.
  - `resolveOvershellComponent()` — read-cache-or-discover; throws if
    nothing matches.
- `lib/services/rmm/executor.ts`:
  - `queueExecution({ scriptId, target, performedByUserId, triggeredByAuditId? })`
    — validates registry, resolves target, runs cost-guard rate limit
    (50/user/24h, decision logged to `analyzer_cost_audit`), inserts
    pending row, calls `runQuickJob`, captures `jobUid`, flips to
    `running`. Generic `audit.log` entry on success.
- `lib/services/rmm/worker.ts`:
  - 5-second poll loop, self-init pattern matching `analyzerWorker`.
  - Sweeps timed-out rows first (status → `timeout`).
  - Polls `running` rows via `client.getJobResults` per `target_device_uid`.
    On terminal status: redacts stdout/stderr, runs script's `parseOutput`,
    persists. Parse errors are non-fatal — raw output still kept.
- `lib/services/rmm/persistence.ts`:
  - Typed `RmmExecutionRow` + status helpers, plus the audit-pipeline
    queries `listLatestEvidenceForCompany(companyId, days)` and
    `listLatestEvidenceForAsset(assetType, assetId)`.
- `lib/services/datto-rmm-client.ts` — added `findOvershellComponent(pattern)`.
- `lib/services/analyzer/asset-audit/data-builder.ts`:
  - 7th LLM context arm `rmm_evidence` populated from
    `listLatestEvidenceForCompany` (site-anchored, last 7 days) +
    `listLatestEvidenceForAsset` (asset-self, all-time).
  - Joins via `companies → itg_organizations` on case-insensitive
    `company_name` match (same join the ticket-evidence loader uses).
- `lib/services/analyzer/asset-audit/prompt.ts`:
  - New `=== LIVE RMM EVIDENCE ===` section emits when
    `ctx.rmm_evidence.length > 0`. Trim path drops it last (highest-value
    section).
  - `LIVE_EVIDENCE_NOTE` injected into the system prompt: *"Treat parsed
    contents as authoritative current state … Cite execution_id alongside
    ticket numbers."*
- `lib/permissions.ts` — new `rmm: ['read','execute']`. Admin + super-admin
  get both; user gets read.
- API routes:
  - `GET/PATCH /api/admin/rmm/settings` — admin-only, view + edit variable name.
  - `POST /api/admin/rmm/settings/discover` — admin-only, force component scan.
  - `GET /api/rmm/scripts` — auth, library catalog (no bodies).
  - `GET/POST /api/rmm/executions` — list (auth) + queue (`rmm.execute`).
  - `GET /api/rmm/executions/[id]` — auth, polls one execution.
  - `GET /api/analyzer/itglue/sites/[companyId]` — site-discovery summary.
- UI:
  - `<RmmScriptPicker filter='site_anchor'|'asset_self' …/>` — popover
    listing applicable scripts, dispatches on click, disables for
    non-admins.
  - `<RmmExecutionStream/>` — polls every 3s, shows status + parsed
    evidence + raw stdout (collapsible).
  - `/admin/rmm-overshell` — settings + recent execution log.
  - `/analyzer/itglue/sites/[companyId]` — site-discovery view.
  - Embedded picker on Application detail (site-anchor with parent
    client) and Configuration detail (asset-self if `rmm_id` resolves to
    a Datto device).
  - Nav entry: Admin → "RMM Overshell".

**Decisions worth flagging**

- **Component discovery is automatic and cached.** Pulse scans for any
  component matching `/overshell/i` on first dispatch, persists the uid,
  and never re-scans unless an admin clicks "Re-discover". The variable
  name defaults to `CommandLine` (Datto's "Run Command" component). If
  Wulf's Overshell uses a different variable, admin sets it once via
  `/admin/rmm-overshell`.
- **Script bodies live in code, not the DB.** Three reasons: PR review is
  the change-control mechanism; nothing in the database is treated as
  executable PowerShell; the 7 scripts are already curated and we don't
  need (or want) ad-hoc paste-a-script UX.
- **WNP-only target resolution.** Site-anchored scripts hit the Wulf
  Nurse Production endpoint (`LLLCCCWNPNN`); PowerShell uses native AD
  cmdlets to reach the DC over the network. Direct-to-DC role detection
  is a fast-follow.
- **5-minute hard timeout + 50/user/24h rate limit.** Both enforced
  server-side in the executor. The cost-guard rows in `analyzer_cost_audit`
  give admins a unified view of LLM and RMM activity per user.
- **Output is redacted before persistence.** Same `redact()` from the
  IT Glue redaction module; strips any password/secret/key/token/credential
  keyed values from stdout/stderr before the parser sees them.
- **Live RMM evidence trims last.** When the audit prompt overflows the
  80KB cap, peer_global → ticket_evidence → rmm_evidence (in that order).
  Live evidence is the most novel signal; it's worth keeping.
- **Worker is in-process, not a separate service.** Same auto-start
  pattern as `analyzerWorker`. `RMM_WORKER_AUTOSTART=1` opt-in for dev.
  Multiple Next.js workers are safe — each row's `jobUid` is set once and
  the poll loop is idempotent.
- **`getJobResults` response shape is variable across Datto tenants.** The
  worker handles both top-level and `results[*]` payloads, picks the
  per-device result when present, and falls back to the first array entry.

**Deliberately left out**

- **No backfill of existing Overshell jobs.** Per user's call. Pulse
  starts capturing from the first dispatch.
- **No DC-role detection.** WNP-only. Add later if AD scripts that need
  native DC execution become important.
- **No ad-hoc PowerShell paste-in.** Only registry-listed scripts run.
- **No openclaw integration.** Phase 4.2 talks directly to Datto RMM.
- **No audit-driven auto-execution.** v1 is admin-clicks-button. The
  audit panel will gain a "Run Get-Services to fill this gap?" prompt in
  a fast-follow once we trust the safety layers.
- **No Overshell write operations.** All scripts are read-only / discovery.
  Configuration changes happen via IT Glue (Phase 4) or manually.
- **No per-script per-user permissions.** Anyone with `rmm.execute` can
  run any script. Per-script gating is a fast-follow if needed.
- **No credential output ever.** Three-layer refusal:
  1. Script library has no credential-handling scripts; tests verify
     bodies don't reference `$plaintext` password patterns.
  2. `redact()` strips matching keys from output before persistence.
  3. The audit prompt's existing credential refusal applies to anything
     that does sneak through.

## Status after Phase 4.2

| Phase | Tests | tsc | Notes |
|---|---|---|---|
| 4.2 | 174 | clean | RMM Overshell pipeline (077), 7 scripts, executor + worker, audit-context arm |

## Phase 4.3 — LogLift event-log ingestion

### Why

Overshell stdout caps around ~50KB practical — fine for service lists
or installed-software dumps, too small for full Windows event logs
across critical/error/warning levels. Wulf already runs a richer
collector via n8n: PowerShell on each endpoint gathers logs + system
context, gzips it, uploads to a Backblaze B2 bucket
(`wulf-audits` / `us-west-002`), then POSTs metadata. n8n decompresses,
runs an LLM analysis, and posts a Telegram summary.

Phase 4.3 makes Pulse the receiver instead of n8n so:

- LogLift evidence lands in the same `rmm_executions` table 4.2 introduced.
- The audit pipeline's `rmm_evidence` arm picks it up automatically.
- Admins can dispatch a LogLift run directly from the Configuration page.
- Successful uploads matched to a unique IT Glue Configuration auto-fire
  an asset-first audit so documentation suggestions surface immediately.

### Shape

`migrations/078_loglift_uploads.sql` adds three columns to
`rmm_executions` (`transport`, `evidence_object_key`, `run_id` — with a
unique index on `run_id`), and three to `rmm_settings`
(`loglift_component_uid`, `loglift_component_name`,
`loglift_discovered_at`). The transport column has a CHECK constraint
restricting it to `overshell_stdout` | `b2_upload`.

`lib/services/b2/client.ts` is a from-scratch SigV4 implementation
ported from `docs/LogLift Review.json`: presigned GET + PUT (different
expiries), 25MB hard download cap, path-traversal-safe object key regex,
and a `B2NotConfiguredError` when env vars are missing. 8 tests cover
the regex + signature stability + signing-key derivation.

`lib/services/rmm/scripts/loglift-eventlogs.ts` registers the script:
`target_type='asset_self'`, `transport='b2_upload'`, empty body (the
collector PowerShell lives in the Datto-registered LogLift component, not
in Pulse). The registry's body-length sanity test skips `b2_upload`
scripts.

### Dispatch path

`executor.ts` forks on `script.transport`:

- `overshell_stdout` (default) — unchanged 4.2 path: resolve Overshell
  component, dispatch with `{Variable: body}`, worker polls for stdout.
- `b2_upload` — new fork. Resolves the Datto site uid from the device,
  resolves the LogLift component (discover-on-demand), generates a
  `runId` (`pulse_<hex>_<ms>`), inserts an `rmm_executions` row with
  `transport='b2_upload'`, dispatches the Quick Job with variables
  `RunId`, `ClientId`, `WebhookUrl`, `WebhookSecret`. The persisted
  `variables` column strips `WebhookSecret` so admins can read the row
  without exposing the OPENCLAW key.

### Receive path

`POST /api/rmm/loglift/upload` (public per `middleware.ts`,
`x-openclaw-key` validated):

1. Zod validate body + object-key regex.
2. Resolve `clientId` (Datto site uid) → `datto_rmm_sites.id` →
   `autotask_company_id` (FK or name fallback — same as 4.2 multi-site
   work).
3. Resolve `computerName` → Datto device uid (case-insensitive).
4. Resolve `computerName` + company → `itg_configurations.id`. Two-pass
   (count + fetch) sets `single_match=true` only when exactly one
   Configuration matches.
5. Correlate to a Pulse-dispatched execution by `run_id`. If no match
   (out-of-band collector), insert a fresh `running` row.
6. Download from B2 (25MB cap), gunzip with zip-bomb guard
   (refuse > 100MB inflated, checked via gzip ISIZE before decompression
   and again after).
7. Slim: keep `system_context` + `summary` + top 100 events sorted by
   severity (Critical → Error → Warning → Info), then recency. Drop the
   raw `events` array; the full gzip stays in B2 forever.
8. `redact()` the slim object, persist with `markExecutionFromB2Upload`.
9. Auto-audit hook: if Configuration matched single, fire
   `runAssetAudit({assetType:'configuration', assetId})` synchronously
   (still in the webhook handler — the LLM call is the bottleneck but
   the agent doesn't care about webhook latency past ~30s). On failure,
   log + continue — webhook still 200s.

`audit_log` actions: `rmm.loglift.dispatched`, `rmm.loglift.received`,
`rmm.loglift.matched`, `rmm.loglift.audit_triggered`.

### Worker change

`worker.ts` filters `transport='b2_upload'` rows out of the running
poll list — no stdout to fetch. The 5-minute timeout sweep still
applies; stuck rows get marked `timeout`.

### Prompt update

`LIVE_EVIDENCE_NOTE` extended to teach the LLM about the LogLift slim
shape: cite events as `event:<EventId>` or `execution:<id>`,
`event_count_total` is the original count (top 100 only in the prompt),
and `system_context` is authoritative for OS / hardware / disk / memory
facts on the matched Configuration.

### UI surfaces

- `/admin/rmm-overshell` gets a second "LogLift component" block with a
  "Re-discover LogLift" button next to the existing Overshell discovery.
  `discoverLogliftComponent()` matches `/loglift|eventlog/i`.
- Configuration page picker (filtered by `target_type='asset_self'`)
  surfaces the LogLift entry automatically — Phase 4.2's executor + UI
  scaffolding handles it through the new dispatch fork.

### Files

**New:** `migrations/078_loglift_uploads.sql`, `lib/services/b2/client.ts`
(+ test), `lib/services/rmm/scripts/loglift-eventlogs.ts`,
`lib/services/rmm/loglift-matcher.ts`,
`lib/services/rmm/loglift-receiver.ts`,
`app/api/rmm/loglift/upload/route.ts`,
`app/api/admin/rmm/settings/discover-loglift/route.ts`,
`docs/loglift-eventlog-pipeline-spec.md`.

**Modified:** `lib/services/datto-rmm-client.ts` (generalized
`findOvershellComponent` → `findComponentByName`),
`lib/services/rmm/settings.ts` (LogLift discover/resolve),
`lib/services/rmm/persistence.ts` (transport + run_id + new
`findExecutionByRunId`, `createOutOfBandUploadExecution`,
`markExecutionFromB2Upload`), `lib/services/rmm/executor.ts` (b2_upload
fork), `lib/services/rmm/worker.ts` (skip b2_upload poll),
`lib/services/rmm/scripts/index.ts` (register), `…/scripts/types.ts`
(transport field), `…/scripts/registry.test.ts` (8-script expectation +
b2_upload body skip), `lib/services/analyzer/asset-audit/prompt.ts`
(LIVE_EVIDENCE_NOTE), `app/admin/rmm-overshell/page.tsx`
(LogLift block + button), `middleware.ts` (`/api/rmm/loglift` public).

### Refusals + guards

1. Object-key regex (`^[A-Za-z0-9_-]+/[A-Za-z0-9_.-]+/eventlogs_[0-9_]+\.json\.gz$`).
2. B2 25MB download cap.
3. Decompress 100MB cap (gzip ISIZE pre-check + post-inflate re-check).
4. `redact()` on slim payload before persistence.
5. Auto-audit only on single-match Configurations — multiple matches
   logged + skipped.
6. Webhook secret stripped from persisted `variables` column.

### Status after Phase 4.3

| Phase | Tests | tsc | Notes |
|---|---|---|---|
| 4.3 | TBD (target ~182) | TBD | LogLift pipeline (078), B2 SigV4, b2_upload transport, slim + auto-audit |