@codyswann/lisa 2.174.1 → 2.175.0

package/package.json

@@ -91,7 +91,7 @@
     "ws": ">=8.20.1"
   },
   "name": "@codyswann/lisa",
-  "version": "2.174.1",
+  "version": "2.175.0",
   "description": "Claude Code governance framework that applies guardrails, guidance, and automated enforcement to projects",
   "main": "dist/index.js",
   "exports": {

package/plugins/lisa/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa",
-  "version": "2.174.1",
+  "version": "2.175.0",
   "description": "Universal governance — agents, skills, commands, hooks, and rules for all projects",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa",
-  "version": "2.174.1",
+  "version": "2.175.0",
   "description": "Universal governance: agents, skills, commands, hooks, and rules for all projects.",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa/commands/monitor.md

@@ -1,6 +1,6 @@
 ---
-description: "Monitor application health across environments. Health endpoints, recent logs, error-rate spikes, performance, optional browser UAT. Routes to the stack-specific ops-specialist."
-argument-hint: "[environment]"
+description: "Monitor application health AND audit observability completeness for the current repo, then file build-ready tickets for anomalies and instrumentation gaps. Health/logs/errors/performance via the stack ops-specialist or stack-agnostic base probing; repo-scoped, idempotent, capped; files by default, --dry-run previews."
+argument-hint: "[environment] [--dry-run] [--report-only] [--all-gaps] [max_candidates=<n>]"
 ---
 
-Use the /lisa:monitor skill to check application health, logs, errors, and performance for the named environment. $ARGUMENTS
+Use the /lisa:monitor skill to check application health, logs, errors, and performance for the named environment, audit observability completeness, and file build-ready tickets for the anomalies and gaps it finds. Use `--dry-run` to preview without filing, `--report-only` for a health/audit summary with no filing, or `--all-gaps` to also file recommended-tier gaps (session replay, product analytics). $ARGUMENTS

package/plugins/lisa/rules/eager/observability-audit.md

@@ -0,0 +1,15 @@
+# Observability Audit (load-bearing)
+
+The **audit + file** arm of `lisa:monitor`. On top of its existing live-signal sweep, `monitor` audits how well the **current repo** is instrumented and files build-ready tickets for what it finds. `monitor` is **manual** (no cron) and **files only** — it never fixes; the `intake` / `tracker-build-intake` cron implements what it files.
+
+## Invariants
+
+- **Repo-scoped two ways.** Audit only the rubric dimensions in scope for the repo's detected profile (`frontend` / `backend` / `infra` — a frontend repo never evaluates backend tracing), and stamp every filed ticket `repo:<CURRENT_REPO>` as a single-repo leaf (resolve the repo via the `config-resolution` ladder; cannot resolve → report, do not file).
+- **Two finding types → build-ready leaves.** A live signal over the conservative bar → a `Bug` leaf; an in-scope MISSING instrumentation dimension (gap, e.g. "no DB/query analytics") → a `Task`/`Improvement` leaf. Always via `lisa:tracker-write` with `build_ready: true` (never a vendor write skill directly); never an Epic/container (gate S15).
+- **Conservative by default.** Only high-signal anomalies (over the documented thresholds) and `core` missing dimensions are filed. `--all-gaps` widens gap filing to `recommended` tiers; nothing lowers the anomaly bar.
+- **Idempotent.** Every ticket carries a `<!-- lisa-monitor-finding: <fingerprint> -->` sentinel; search-before-create (including closed tickets) means a re-run never duplicates a live or just-resolved finding.
+- **Capped.** At most `monitor.maxCandidates` tickets per run (default 20), highest-severity first; report filed-vs-dropped (and list the dropped) — never silently truncate.
+- **Gate-passing.** Each ticket is a real authored artifact: three-audience description, Gherkin AC, single-repo, Target Backend Environment, and a Validation Journey with a unique kebab-case `[EVIDENCE: <name>]` marker — so `tracker-validate` (S1–S15) accepts it. A finding that cannot be made into a credible ticket is reported, not filed.
+- **Verify guard.** When `monitor` is the post-deploy step of `lisa:verify` it runs **report-only** — Verify invokes it as `lisa:monitor <env> --report-only`, so it never files there. Filing is a standalone-only action.
+
+Full reference (profile detection, the rubric table, anomaly thresholds, ticket templates, idempotency contract, the cap, dry-run/report-only semantics): [reference/observability-audit.md](../reference/observability-audit.md).

package/plugins/lisa/rules/reference/config-resolution.md

@@ -156,6 +156,18 @@ fi
       "staleAfterHours": 2,
       "maxCandidates": 100
     }
+  },
+
+  "monitor": {
+    "maxCandidates": 20,
+    "gapTiers": "core",
+    "backoffHours": 24,
+    "thresholds": {
+      "sentryMinEvents24h": 10,
+      "errorRateSpikeMultiplier": 2,
+      "p95LatencyMs": 1000,
+      "xrayFaultRatePct": 5
+    }
   }
 }
 ```
@@ -360,6 +372,29 @@ documented defaults, so existing projects need no config change.
 | `intake.repair.staleAfterHours` | no | `2` | How long an in-progress item (build `claimed`, PRD `in_review`) may show no observable activity before repair-intake treats it as stalled and resumes it. `blocked` items are judged on blocker/answer state, not this threshold. Overridable per-run via `stale_after=<dur>` in `$ARGUMENTS` (which always wins). The same value is the default backoff window for loop-prevention notes. |
 | `intake.repair.maxCandidates` | no | `100` | Upper bound on how many stuck items repair-intake enumerates while searching for the first actionable one. Bounds scan cost. Overridable per-run via `max_candidates=<n>`. |
 
+### Monitor audit config (`monitor`)
+
+`lisa:monitor`'s audit-and-file arm reads an optional top-level `monitor` block. Every key is
+**optional** — a missing block inherits the documented defaults, so existing projects need no
+config change. The role SEMANTICS (what counts as an anomaly or gap, how findings become tickets)
+are fixed like every other lifecycle behavior; only these thresholds and caps are tunable. Full
+contract: the `observability-audit` rule.
+
+| Key | Required | Default | Notes |
+|-----|----------|---------|-------|
+| `monitor.maxCandidates` | no | `20` | Cap on tickets filed per standalone run (`core`/high-severity first). Overridable per-run via `max_candidates=<n>` in `$ARGUMENTS`, which always wins. |
+| `monitor.gapTiers` | no | `core` | Which gap tier files tickets by default: `core` (operationally load-bearing dimensions only) or `all` (also `recommended`). The `--all-gaps` run flag forces `all` for that invocation. |
+| `monitor.backoffHours` | no | `24` | How long after a finding's ticket is closed/resolved to keep suppressing a re-file (the recently-resolved dedup window), so a just-fixed regression isn't re-filed before its signal drains. Distinct from `intake.repair.staleAfterHours` (2h). |
+| `monitor.thresholds.sentryMinEvents24h` | no | `10` | Minimum 24h event count for an unresolved Sentry error to be fileable. |
+| `monitor.thresholds.errorRateSpikeMultiplier` | no | `2` | Error rate must be ≥ this × the prior-window baseline (and above an absolute floor) to file. |
+| `monitor.thresholds.p95LatencyMs` | no | `1000` | p95 latency at/above this (or up ≥ 50% vs prior window) is a fileable regression. |
+| `monitor.thresholds.xrayFaultRatePct` | no | `5` | X-Ray fault traces above this % of traces in the window is a fileable anomaly. |
+
+Resolution order matches every other key: `$ARGUMENTS` override → `.lisa.config.local.json` →
+`.lisa.config.json` → built-in default. `monitor` files only within the current repo (type-scoped
+rubric + `repo:<name>` single-repo leaves); it never fixes — the `intake` cron implements what it
+files.
+
 ### Intake assignee filter (`intake.assignee`)
 
 The optional intake assignee filter narrows **ready-item selection only**. It never assigns or

package/plugins/lisa/rules/reference/intent-routing.md

@@ -314,11 +314,16 @@ Sequence:
 
 ### Monitor
 
-Purpose: Check application health and operational status. Can be invoked standalone or as part of Verify.
+Purpose: Check application health and operational status, **audit observability completeness**, and (standalone only) **file build-ready tickets** for anomalies and instrumentation gaps. Repo-scoped and manual — there is no cron for Monitor. Can be invoked standalone or as the post-deploy step of Verify.
 
 Sequence:
-1. `ops-specialist` -- health checks, log inspection, error monitoring, performance analysis
-2. Report findings, escalate if action needed
+1. **Discover** -- stack-agnostic detection of the repo's observability profile (`frontend` / `backend` / `infra`) and which observability tools are actually wired (read manifests/config; probe only with available credentials). See the `observability-audit` rule.
+2. **Collect live signals** -- `ops-specialist` (Expo/Rails) or inline base probing (Sentry CLI/REST, CloudWatch, X-Ray, Playwright MCP) for health, logs, errors, performance. An observation is a fileable **anomaly** only when it clears the conservative thresholds in `observability-audit`.
+3. **Audit completeness** -- score the repo against the `observability-audit` rubric for its profile; each in-scope MISSING dimension is a **gap** finding (`core` always; `recommended` only with `--all-gaps`).
+4. **Report** -- health/anomaly summary + audit table. Always produced.
+5. **File (standalone only; SKIP under `--report-only`/`--dry-run` and when invoked from Verify)** -- for each anomaly and gap, dedupe by fingerprint (sentinel + search-before-create incl. closed tickets), then file a single-repo build-ready leaf via `tracker-write` (`build_ready: true`) — a `Bug` for an anomaly, a `Task`/`Improvement` for a gap — stamped `repo:<current>`, capped at `max_candidates` (default 20, `core`/high-severity first; list any dropped). Default files; `--dry-run` previews without filing. `lisa:verify` invokes monitor as `lisa:monitor <env> --report-only`, so the post-deploy check never files. Escalate anything not made into a ticket.
+
+The `observability-audit` rule owns the profile detection, rubric, anomaly thresholds, ticket templates (gate-passing), fingerprint/idempotency contract, the cap, and the Verify report-only guard. Monitor **files only** — the `intake` / `tracker-build-intake` cron implements what it files.
 
 ## Tracker Entry Point (JIRA, GitHub Issues, or Linear)
 

package/plugins/lisa/rules/reference/observability-audit.md

@@ -0,0 +1,122 @@
+# Observability Audit (load-bearing)
+
+This rule is the single source of truth for the **audit + file** arm of the `lisa:monitor` skill. The `monitor` skill collects live signals (errors, logs, performance, health) via the stack `ops-specialist` exactly as before; this rule adds two things on top, both **repo-scoped**:
+
+1. **Audit** — score the repo against an observability-completeness rubric for its detected type, so a frontend repo is never dinged for missing backend tracing.
+2. **File** — turn both *anomalies* (a real bad live signal) and *gaps* (an in-scope observability dimension that isn't wired) into **build-ready leaf tickets** so the existing `intake` / `tracker-build-intake` cron picks them up and fixes them. `monitor` files only; it never fixes.
+
+`monitor` is **manual** — there is no cron for it. It is run by a human against a named environment.
+
+## Scope discipline (why this is repo-scoped)
+
+`monitor` runs **inside one repo** and audits/files **only for that repo**. Two mechanisms enforce it:
+
+- **Type-scoped rubric.** Only the dimensions in-scope for the detected repo type are audited (table below). A frontend-only repo never evaluates X-Ray tracing or DB-query analytics; a backend repo never evaluates Web Vitals or session replay.
+- **`repo:<name>` stamping.** Every filed ticket is a single-repo leaf stamped `repo:<CURRENT_REPO>` (per `repo-scope-split`). Resolve `CURRENT_REPO` with the standard ladder from `config-resolution` ("Current-repo resolution"): config `repo` → `github.repo` → `basename` of the git remote. If it cannot be resolved, **report and skip filing** rather than filing un-scoped tickets.
+
+## Repo-type detection (stack-agnostic)
+
+`monitor` is a base skill that ships to every project, so detection must not assume a stack plugin is present. Detect the repo's observability **profile** by reading manifests and key files — never by assuming. Classify into one or more of `frontend`, `backend`, `infra`. A repo may be more than one (a Rails or Next.js app is `frontend`+`backend` = "fullstack"); audit the union of the matched profiles' in-scope dimensions.
+
+| Profile | Positive signals (any) |
+|---|---|
+| `frontend` | `package.json` deps incl. `expo`, `react-native`, `next`, `react`, `vue`, `@angular/core`, `svelte`, `vite`; an `app.json` / `app/` route dir / `public/index.html`; a web/mobile build script |
+| `backend` | `package.json` deps incl. `@nestjs/core`, `express`, `fastify`, `koa`, `@apollo/server`; a `serverless.yml` / Lambda handlers; a `Gemfile` with `rails`; a `Procfile`; an API/server entrypoint |
+| `infra` | `aws-cdk-lib` + `cdk.json`; Terraform `*.tf`; Pulumi; a `serverless.yml` with no application code; a deploy-only repo |
+
+When the Lisa stack overlay is present its mapping is a strong prior (`expo`→frontend, `nestjs`→backend, `cdk`→infra, `rails`→frontend+backend, `typescript`→infer from the signals above), but always confirm against the actual files — the overlay is a hint, the files are truth.
+
+## The observability-completeness rubric
+
+Each dimension is **in scope** (`●`) or **out of scope** (`–`) per profile, and carries a **tier**: `core` (a blind spot here is a real operational risk → file when missing) or `recommended` (valuable but optional → file only when `--all-gaps` is passed; otherwise report as a WARN row, do not ticket).
+
+| Dimension | Tier | FE | BE | Infra | Detect via (presence ⇒ wired) |
+|---|---|:--:|:--:|:--:|---|
+| Error monitoring | core | ● | ● | – | `@sentry/*`, `.sentryclirc`, Sentry DSN in `.env*`; Bugsnag/Rollbar deps |
+| Structured logging | core | ● | ● | ● | `pino`/`winston`/`bunyan`; Rails `lograge`; CloudWatch log groups exist |
+| Distributed tracing | core | – | ● | ● | `aws-xray-sdk*`, OpenTelemetry deps/gems; X-Ray traces present |
+| Metrics & alarms | core | – | ● | ● | CloudWatch custom metrics + `describe-alarms` returns alarms; Datadog/Prometheus |
+| Health checks | core | ● | ● | – | a `/health`/`/up` endpoint; NestJS Terminus; uptime check config |
+| RUM / Web Vitals | recommended | ● | – | – | Sentry performance/browser tracing, `web-vitals`, Firebase Performance |
+| Product analytics | recommended | ● | – | – | `posthog-js`/`posthog-node`, Firebase Analytics, Amplitude, Segment |
+| Session replay / frustration | recommended | ● | – | – | Jam, PostHog session replay, LogRocket, Sentry replay |
+| DB / query analytics | recommended | – | ● | ● | slow-query logging, RDS/Aurora Performance Insights, query-timing middleware |
+| Synthetic / smoke UAT | recommended | ● | ● | – | Playwright/Cypress e2e, k6/Artillery load scripts, synthetic canaries |
+
+**Detection is read-then-probe, never assume.** For each in-scope dimension: read `package.json` deps + scripts (and `Gemfile`, `serverless.yml`, `docker-compose.yml`, `config/initializers/*`, `.env*`, `.sentryclirc`, `cdk.json`), then — only when credentials/tooling are already available — probe the live source (`command -v sentry-cli`, `aws sts get-caller-identity` before any `aws` call). Mirror the `ops-specialist` "Project Discovery" table where the stack overlay exists. **Absence of every signal for an in-scope dimension is the gap finding.** A dimension that is present but unreachable this run (e.g. PostHog wired but no API key available) is reported `PRESENT (unverified)`, **not** a gap.
+
+### Tools Lisa does not wire
+
+PostHog, Jam, and Firebase have **no Lisa MCP**. Detect them statically (deps/config) and pull their data only where a first-party API + credentials are already present in the environment (e.g. the PostHog API with a project key). Never invent credentials, and never treat "Lisa has no MCP for it" as "the repo lacks it" — judge by the repo's own deps/config.
+
+## Live-signal anomalies (conservative thresholds)
+
+Collect live signals via the stack `ops-specialist` when present (Expo/Rails), else via inline base probing (Sentry CLI/REST, `aws logs`, `aws cloudwatch`, `aws xray`, the Playwright MCP for client-side console/network). An observation becomes a **fileable anomaly** only when it clears the conservative bar — high-signal only, to keep the Ready queue clean. Defaults below (the keys live under `monitor.thresholds.*` in `config-resolution`; per-run nothing overrides them — tune in config):
+
+| Signal | Fileable when |
+|---|---|
+| Sentry issue | `is:unresolved` **and** `level:error|fatal` **and** events in last 24h ≥ `sentryMinEvents24h` (default 10). Skip resolved/ignored/muted and below-floor noise. |
+| Error-rate spike | error rate ≥ `errorRateSpikeMultiplier`× (default 2×) the prior-window baseline **and** above an absolute floor (not 1-of-2 requests). |
+| Latency regression | p95 ≥ `p95LatencyMs` (default 1000ms) sustained, **or** p95 up ≥ 50% vs the prior window. |
+| CloudWatch alarm | any alarm in `ALARM` state. |
+| X-Ray fault rate | fault traces > `xrayFaultRatePct` (default 5%) of traces in the window. |
+| Client-side (Playwright) | repeated console `error` or a 5xx network response on a smoke flow. |
+
+Everything below the bar is reported (so the human sees it) but **not** ticketed. `--all-gaps` does not lower anomaly thresholds — it only widens *gap* tiers.
+
+## Two finding types → build-ready leaf tickets
+
+Both finding types are filed through the vendor-neutral `lisa:tracker-write` shim with `build_ready: true` (never a vendor write skill directly — that is what keeps the destination switchable). Both are **leaf** work units (`Bug` for anomalies, `Task`/`Improvement` for gaps) — never an Epic or container (gate S15). Each must pass the `tracker-validate` gates S1–S15, so each ticket is a real authored artifact, not a template dump.
+
+### Required fields (so the gates pass)
+
+- **Three-audience description** (S3): coding-assistant (technical: stack trace / Sentry link / occurrence count / the missing dimension and how to wire it), developer (where it surfaces, suspected cause/affected files, the fix skill to reach for), stakeholder (user/SLO impact).
+- **Gherkin acceptance criteria** (S4).
+- **Single repo** (S10): stamped `repo:<CURRENT_REPO>`; scope the description to this repo only.
+- **Target Backend Environment** (S8) + **Validation Journey** carrying at least one unique kebab-case `[EVIDENCE: <name>]` marker (S11/S14) — both anomaly fixes and gap wiring are runtime changes, so both need an env and a journey that proves the fix. The bracketed `[EVIDENCE: <name>]` form is what the validator scans for; a bare `EVIDENCE:` line fails S14. Prefer two markers (a success and an error/edge case).
+- **Relationship search before write** (S13) — doubles as the dedup guard (next section).
+- **No parent/Epic required.** These are build-ready standalone leaves; S7's parent requirement is waived for a `build_ready: true` leaf (the leaf carve-out in `leaf-only-lifecycle` / `tracker-validate`). Do not fabricate an Epic parent.
+- A **priority** ordered by tier and severity: `core` gap / high-event anomaly → higher; `recommended` gap → lower.
+
+### Anomaly ticket (type: Bug)
+
+Title: `[observability] <signal summary> (<source>)` — e.g. `[observability] Unhandled TypeError in CheckoutScreen (Sentry)`. The coding-assistant section carries the Sentry/CloudWatch/X-Ray link, fingerprint, first/last seen, and occurrence count. AC: *Given* the repro context, *When* the action runs, *Then* the source reports zero new events for the fingerprint. The fix-skill hint points at `root-cause-analysis` / `reproduce-bug`.
+
+### Gap ticket (type: Task or Improvement)
+
+Title: `[observability-gap] Add <dimension> (<profile>)` — e.g. `[observability-gap] Add distributed tracing (backend)`. The description states which dimension is missing, **why the audit needed it** (the blind spot it leaves), and how to wire it — chaining the existing fix skills where they apply (`parity-sentry-sdk-setup` for error monitoring; the nestjs `typeorm-patterns` skill's `observability-patterns` reference for X-Ray/CloudWatch DB-query tracing; OTel→X-Ray for tracing). AC: *Given* the app runs in `<env>`, *When* the relevant signal occurs, *Then* the newly-wired dimension captures it (dashboard/endpoint/trace shows data).
+
+## Idempotency (do not re-file the same finding)
+
+A manual re-run next week must not duplicate last week's tickets. Mirror the `repair-intake` marker discipline:
+
+1. **Stable fingerprint per finding.**
+   - Anomaly: `sha1("<source>:<stable-signature>:<CURRENT_REPO>")` (12 hex chars). `stable-signature` is the Sentry issue short-id (or culprit), the CloudWatch alarm name, or `errorType@location` — something that survives between runs, **never** the human title or occurrence count.
+   - Gap: the literal `gap:<dimension>:<CURRENT_REPO>` (a dimension is missing-or-not; no hash needed).
+2. **Sentinel in the body.** Embed `<!-- lisa-monitor-finding: <fingerprint> -->` in every filed ticket.
+3. **Search before create** (this IS gate S13). Before filing, search the tracker for the fingerprint string. The search **MUST include closed/resolved tickets** (`gh issue list --search <fp> --state all` for GitHub; JQL with no status filter for JIRA; all states for Linear) — otherwise a just-closed match is invisible and the backoff below can't fire. If an **open** ticket carries the fingerprint → skip (optionally link). If a ticket carrying it was closed **within the recently-resolved backoff window** (`monitor.backoffHours`, default **24h** — matching the 24h Sentry event window; this is **not** the 2h `intake.repair.staleAfterHours`) → skip, to avoid re-filing a just-fixed regression before its signal has drained. Only file when no live or recently-resolved match exists.
+
+## The cap
+
+File **at most `max_candidates` tickets per run** (default **20**; config `monitor.maxCandidates`; per-run `max_candidates=<n>` always wins). Rank candidates before applying the cap — `core` gaps and highest-occurrence anomalies first — so the cap drops the least-important findings, never the most. When the cap truncates, **list every dropped finding** in the report (title + fingerprint, not just a count) — silent truncation reads as "all clear" when it isn't, and a high-signal anomaly that fell just below the cap must still be visible to the human.
+
+## Filing modes and the Verify guard
+
+- **Default (standalone `monitor <env>`): files.** A plain manual run audits, reports, dedupes, and files up to the cap.
+- **`--dry-run`:** does everything except call `tracker-write` — prints exactly which tickets *would* be filed (title, type, fingerprint, dedup verdict) so the human can preview.
+- **`--report-only`:** produces the health/audit summary only — no filing and no would-file analysis. This is the mode Verify uses (below).
+- **Invoked as `lisa:verify`'s post-deploy step: never files — enforced mechanically, not inferred.** `lisa:verify` step 6 invokes monitor as `lisa:monitor <env> --report-only`; monitor must never file when `--report-only` (or `--dry-run`) is set. This is load-bearing **today** — Verify already routes its remote verification through the `monitor` skill, so without the passed flag the new file-by-default behavior would create tickets during every verify run. As a belt-and-suspenders default, if monitor is invoked via the Skill tool from within a Verify flow and no filing flag was passed, treat it as `--report-only` rather than filing.
+
+## Output
+
+A single report: the health/anomaly summary (existing monitor behavior) + an audit table (each in-scope dimension with `OK` / `WARN` / `MISSING` / `PRESENT (unverified)`) + a filing summary (tickets filed with their refs and fingerprints, tickets skipped as duplicates, and the dropped count if the cap truncated). In `--dry-run`, the filing summary lists would-file tickets instead.
+
+## Rules
+
+- File only — never fix. The `intake` / `tracker-build-intake` cron implements what `monitor` files.
+- Always through `tracker-write` with `build_ready: true`; never a vendor write skill directly.
+- Conservative by default — high-signal anomalies and `core` missing dimensions only. `--all-gaps` widens gap tiers; nothing lowers the anomaly bar.
+- Repo-scoped always — type-scoped rubric + `repo:<CURRENT_REPO>` single-repo leaves. Cannot resolve the repo → report, do not file.
+- Idempotent always — fingerprint sentinel + search-before-create; a re-run never duplicates a live or just-resolved finding.
+- Never file without a real, gate-passing description and Validation Journey. A finding that cannot be made into a credible ticket is reported, not filed.
+- Read config with `jq` (local-overrides-global) per `config-resolution`; never hand-parse JSON. Never run an `aws`/`sentry-cli` probe without first confirming credentials.

package/plugins/lisa/skills/monitor/SKILL.md

@@ -1,12 +1,19 @@
 ---
 name: monitor
-description: "Monitor application health across environments. Checks health endpoints, recent logs (CloudWatch / Sentry / browser console), error-rate spikes, performance hotspots, pending migrations, and runs Playwright smoke flows when relevant. Routes to the stack-specific ops-specialist agent (Expo, Rails, etc.). Also invoked as the post-deploy step of the lisa:verify skill."
-allowed-tools: ["Skill", "Bash", "Read", "Grep"]
+description: "Monitor application health AND audit observability completeness for the current repo, then file build-ready tickets for what it finds. Checks health endpoints, recent logs (CloudWatch / Sentry / browser console), error-rate spikes, performance hotspots, pending migrations, and Playwright smoke flows via the stack-specific ops-specialist (Expo, Rails) or stack-agnostic base probing (any stack, incl. NestJS / CDK). Audits the repo against an observability-completeness rubric scoped to its type (frontend / backend / infra) and flags instrumentation gaps (e.g. no distributed tracing, no DB/query analytics). For each high-signal anomaly and each in-scope missing dimension it files a single-repo, build-ready leaf ticket via tracker-write (idempotent, capped, repo-scoped) so the intake cron implements it — monitor files only, it never fixes. Manual (no cron); files by default, `--dry-run` previews. Conservative by default. Also invoked as the post-deploy step of lisa:verify, where it runs report-only (never files)."
+allowed-tools: ["Skill", "Bash", "Read", "Grep", "Glob"]
 ---
 
 # Monitor: $ARGUMENTS
 
-Spot-check application health in the named environment (`dev` / `staging` / `prod`). Useful both reactively (after a deploy, after a Sentry alert, before pushing a hot change) and as the post-deploy verification step inside `lisa:verify`.
+Spot-check application health, **audit observability completeness**, and **file build-ready tickets** for the problems and instrumentation gaps it finds — all scoped to the current repo. Useful reactively (after a deploy, after a Sentry alert, before pushing a hot change), as a periodic manual observability sweep, and as the post-deploy verification step inside `lisa:verify`.
+
+**Arguments:** `<environment>` (`dev` / `staging` / `prod`) `[--dry-run] [--report-only] [--all-gaps] [max_candidates=<n>]`.
+
+- `--dry-run` — audit and report which tickets *would* be filed, but create nothing.
+- `--report-only` — health/audit summary only; no filing and no would-file analysis. This is the mode `lisa:verify` passes for its post-deploy check, so monitor never files during a verify run.
+- `--all-gaps` — also file `recommended`-tier gaps (session replay, product analytics, etc.), not just `core`. Does not change anomaly thresholds.
+- `max_candidates=<n>` — cap tickets filed this run (default 20; config `monitor.maxCandidates`).
 
 ## Orchestration: agent team
 
@@ -31,7 +38,9 @@ Treat the first successful lead-spawn request (or, on the Codex fallback, the fi
 
 ## Flow
 
-Execute the **Monitor** sub-flow as defined in the `intent-routing` rule (loaded via the lisa plugin). The Monitor sub-flow delegates to a stack-specific `ops-specialist` agent (Expo, Rails, etc.), which composes the underlying ops skills:
+Execute the **Monitor** sub-flow as defined in the `intent-routing` rule (loaded via the lisa plugin): **discover → collect live signals → audit completeness → report → file (standalone only)**. The `observability-audit` rule owns the profile detection, the completeness rubric, the conservative anomaly thresholds, the gate-passing ticket templates, the fingerprint/idempotency contract, the cap, and the Verify report-only guard — follow it; do not restate it here.
+
+**Live-signal collection** delegates to a stack-specific `ops-specialist` agent when the stack overlay ships one. The **Expo** ops-specialist composes the full set below:
 
 - `ops-verify-health` — health endpoints
 - `ops-check-logs` — CloudWatch / browser console / device / Serverless logs
@@ -41,8 +50,20 @@ Execute the **Monitor** sub-flow as defined in the `intent-routing` rule (loaded
 - `ops-db-ops` — pending migrations, replication lag
 - `ops-deploy` — deploy status / rollback readiness
 
-The agent decides which subset to run based on the env, the situation, and any extra context provided. The rule contains the canonical decision logic.
+The **Rails** ops-specialist composes a different subset (`ops-run-local`, `ops-deploy`, `ops-check-logs`, `ops-verify-jobs`, `ops-verify-telemetry` — X-Ray/CloudWatch traces and metrics via `ops-verify-telemetry`). When no `ops-specialist` overlay is present (e.g. NestJS, CDK, or a generic TypeScript repo), fall back to **stack-agnostic base probing** — read manifests/config to discover what's wired, then probe live sources directly (Sentry CLI/REST, `aws logs` / `aws cloudwatch` / `aws xray`, the Playwright MCP for client-side console/network), exactly as the `observability-audit` "read-then-probe" detection prescribes. The agent decides which subset to run based on the env, the repo profile, and any extra context.
+
+## Ticket filing (standalone only)
+
+After report, file what was found — **only when run standalone**, never under `--report-only`/`--dry-run` and never when nested inside `lisa:verify` (which passes `--report-only`):
+
+- **Anomalies** (live signals over the conservative bar) → `Bug` leaves. **Gaps** (in-scope MISSING rubric dimensions) → `Task`/`Improvement` leaves.
+- Every ticket is filed via the vendor-neutral `lisa:tracker-write` shim with `build_ready: true` (never a vendor write skill directly), as a **single-repo leaf** stamped `repo:<current>`, with a real three-audience description, Gherkin AC, Target Backend Environment, and a Validation Journey + `EVIDENCE:` marker so it passes the `tracker-validate` gates.
+- **Idempotent:** embed the `<!-- lisa-monitor-finding: <fingerprint> -->` sentinel and search-before-create; never duplicate a live or just-resolved finding.
+- **Capped** at `max_candidates` (default 20), `core`/high-severity first; report how many were filed vs dropped.
+- **`--dry-run`** previews would-file tickets and creates nothing. **`--all-gaps`** widens gap filing to `recommended` tiers.
+
+`monitor` files only. The `intake` / `tracker-build-intake` cron picks the ready tickets up and implements them.
 
 ## Output
 
-A health summary with the relevant findings (failures, warnings, no-issue confirmations). For post-deploy verification (when called from `lisa:verify`), the summary becomes evidence on the originating work item.
+A single report: the health/anomaly summary (failures, warnings, no-issue confirmations) + the observability audit table (each in-scope dimension as `OK` / `WARN` / `MISSING` / `PRESENT (unverified)`) + the filing summary (tickets filed with refs + fingerprints, duplicates skipped, dropped count if the cap truncated; or would-file tickets under `--dry-run`). For post-deploy verification (when called from `lisa:verify`), the report-only summary becomes evidence on the originating work item.

package/plugins/lisa/skills/monitor/agents/openai.yaml

@@ -1,4 +1,4 @@
 display_name: "Monitor"
-short_description: "Monitor application health across environments"
+short_description: "Monitor application health AND audit observability completeness for the current repo, then file build-ready tickets for what it finds"
 default_prompt:
-  - "Use $monitor: Monitor application health across environments."
+  - "Use $monitor: Monitor application health AND audit observability completeness for the current repo, then file build-ready tickets for what it finds."

package/plugins/lisa/skills/verify/SKILL.md

@@ -38,7 +38,7 @@ Execute the **Verify** flow as defined in the `intent-routing` rule (loaded via
 3. **Push and PR** via `lisa:git-submit-pr`
 4. **Review loop** — handle CodeRabbit / human review comments via `lisa:pull-request-review`
 5. **Merge** when CI is green
-6. **Remote verification** — invoke the `lisa:monitor` skill against the target environment to confirm the deploy actually works (health endpoints, recent logs/errors, Validation Journey replay if defined). If remote verification surfaces a behavioral gap that the existing codified tests do not guard, invoke `codify-verification` to add coverage and open a follow-up PR.
+6. **Remote verification** — invoke the `lisa:monitor` skill against the target environment **in report-only mode** (`lisa:monitor <env> --report-only`) to confirm the deploy actually works (health endpoints, recent logs/errors, Validation Journey replay if defined). `--report-only` is required here: it keeps the post-deploy check a pure health/audit report and prevents monitor's standalone ticket-filing from creating issues during a verify run. If remote verification surfaces a behavioral gap that the existing codified tests do not guard, invoke `codify-verification` to add coverage and open a follow-up PR.
    - When remote verification needs credentials, follow the shared `verification-lifecycle` credential lookup order before declaring them missing: project e2e / Playwright config and fixtures first, then `.lisa.config.local.json` / environment variables, then documented ticket credentials such as a `Sign-in Required` section.
    - Should credentials remain genuinely unavailable after those sources are exhausted, do not complete the item on artifact-only evidence. Post a tracker comment stating what could not be verified and why, transition the work item to the configured blocked state, and apply the configured `needs-human` / `human-review` label, creating it if the tracker supports label creation and it is missing.
    - Evidence must explicitly distinguish `verified empirically` from `artifact-only / verification deferred`.

package/plugins/lisa-agy/commands/monitor.md

@@ -1,6 +1,6 @@
 ---
-description: "Monitor application health across environments. Health endpoints, recent logs, error-rate spikes, performance, optional browser UAT. Routes to the stack-specific ops-specialist."
-argument-hint: "[environment]"
+description: "Monitor application health AND audit observability completeness for the current repo, then file build-ready tickets for anomalies and instrumentation gaps. Health/logs/errors/performance via the stack ops-specialist or stack-agnostic base probing; repo-scoped, idempotent, capped; files by default, --dry-run previews."
+argument-hint: "[environment] [--dry-run] [--report-only] [--all-gaps] [max_candidates=<n>]"
 ---
 
-Use the /lisa:monitor skill to check application health, logs, errors, and performance for the named environment. $ARGUMENTS
+Use the /lisa:monitor skill to check application health, logs, errors, and performance for the named environment, audit observability completeness, and file build-ready tickets for the anomalies and gaps it finds. Use `--dry-run` to preview without filing, `--report-only` for a health/audit summary with no filing, or `--all-gaps` to also file recommended-tier gaps (session replay, product analytics). $ARGUMENTS

package/plugins/lisa-agy/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa",
-  "version": "2.174.1",
+  "version": "2.175.0",
   "description": "Universal governance — agents, skills, commands, hooks, and rules for all projects",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-agy/skills/monitor/SKILL.md

@@ -1,12 +1,19 @@
 ---
 name: monitor
-description: "Monitor application health across environments. Checks health endpoints, recent logs (CloudWatch / Sentry / browser console), error-rate spikes, performance hotspots, pending migrations, and runs Playwright smoke flows when relevant. Routes to the stack-specific ops-specialist agent (Expo, Rails, etc.). Also invoked as the post-deploy step of the lisa:verify skill."
-allowed-tools: ["Skill", "Bash", "Read", "Grep"]
+description: "Monitor application health AND audit observability completeness for the current repo, then file build-ready tickets for what it finds. Checks health endpoints, recent logs (CloudWatch / Sentry / browser console), error-rate spikes, performance hotspots, pending migrations, and Playwright smoke flows via the stack-specific ops-specialist (Expo, Rails) or stack-agnostic base probing (any stack, incl. NestJS / CDK). Audits the repo against an observability-completeness rubric scoped to its type (frontend / backend / infra) and flags instrumentation gaps (e.g. no distributed tracing, no DB/query analytics). For each high-signal anomaly and each in-scope missing dimension it files a single-repo, build-ready leaf ticket via tracker-write (idempotent, capped, repo-scoped) so the intake cron implements it — monitor files only, it never fixes. Manual (no cron); files by default, `--dry-run` previews. Conservative by default. Also invoked as the post-deploy step of lisa:verify, where it runs report-only (never files)."
+allowed-tools: ["Skill", "Bash", "Read", "Grep", "Glob"]
 ---
 
 # Monitor: $ARGUMENTS
 
-Spot-check application health in the named environment (`dev` / `staging` / `prod`). Useful both reactively (after a deploy, after a Sentry alert, before pushing a hot change) and as the post-deploy verification step inside `lisa:verify`.
+Spot-check application health, **audit observability completeness**, and **file build-ready tickets** for the problems and instrumentation gaps it finds — all scoped to the current repo. Useful reactively (after a deploy, after a Sentry alert, before pushing a hot change), as a periodic manual observability sweep, and as the post-deploy verification step inside `lisa:verify`.
+
+**Arguments:** `<environment>` (`dev` / `staging` / `prod`) `[--dry-run] [--report-only] [--all-gaps] [max_candidates=<n>]`.
+
+- `--dry-run` — audit and report which tickets *would* be filed, but create nothing.
+- `--report-only` — health/audit summary only; no filing and no would-file analysis. This is the mode `lisa:verify` passes for its post-deploy check, so monitor never files during a verify run.
+- `--all-gaps` — also file `recommended`-tier gaps (session replay, product analytics, etc.), not just `core`. Does not change anomaly thresholds.
+- `max_candidates=<n>` — cap tickets filed this run (default 20; config `monitor.maxCandidates`).
 
 ## Orchestration: agent team
 
@@ -31,7 +38,9 @@ Treat the first successful lead-spawn request (or, on the Codex fallback, the fi
 
 ## Flow
 
-Execute the **Monitor** sub-flow as defined in the `intent-routing` rule (loaded via the lisa plugin). The Monitor sub-flow delegates to a stack-specific `ops-specialist` agent (Expo, Rails, etc.), which composes the underlying ops skills:
+Execute the **Monitor** sub-flow as defined in the `intent-routing` rule (loaded via the lisa plugin): **discover → collect live signals → audit completeness → report → file (standalone only)**. The `observability-audit` rule owns the profile detection, the completeness rubric, the conservative anomaly thresholds, the gate-passing ticket templates, the fingerprint/idempotency contract, the cap, and the Verify report-only guard — follow it; do not restate it here.
+
+**Live-signal collection** delegates to a stack-specific `ops-specialist` agent when the stack overlay ships one. The **Expo** ops-specialist composes the full set below:
 
 - `ops-verify-health` — health endpoints
 - `ops-check-logs` — CloudWatch / browser console / device / Serverless logs
@@ -41,8 +50,20 @@ Execute the **Monitor** sub-flow as defined in the `intent-routing` rule (loaded
 - `ops-db-ops` — pending migrations, replication lag
 - `ops-deploy` — deploy status / rollback readiness
 
-The agent decides which subset to run based on the env, the situation, and any extra context provided. The rule contains the canonical decision logic.
+The **Rails** ops-specialist composes a different subset (`ops-run-local`, `ops-deploy`, `ops-check-logs`, `ops-verify-jobs`, `ops-verify-telemetry` — X-Ray/CloudWatch traces and metrics via `ops-verify-telemetry`). When no `ops-specialist` overlay is present (e.g. NestJS, CDK, or a generic TypeScript repo), fall back to **stack-agnostic base probing** — read manifests/config to discover what's wired, then probe live sources directly (Sentry CLI/REST, `aws logs` / `aws cloudwatch` / `aws xray`, the Playwright MCP for client-side console/network), exactly as the `observability-audit` "read-then-probe" detection prescribes. The agent decides which subset to run based on the env, the repo profile, and any extra context.
+
+## Ticket filing (standalone only)
+
+After report, file what was found — **only when run standalone**, never under `--report-only`/`--dry-run` and never when nested inside `lisa:verify` (which passes `--report-only`):
+
+- **Anomalies** (live signals over the conservative bar) → `Bug` leaves. **Gaps** (in-scope MISSING rubric dimensions) → `Task`/`Improvement` leaves.
+- Every ticket is filed via the vendor-neutral `lisa:tracker-write` shim with `build_ready: true` (never a vendor write skill directly), as a **single-repo leaf** stamped `repo:<current>`, with a real three-audience description, Gherkin AC, Target Backend Environment, and a Validation Journey + `EVIDENCE:` marker so it passes the `tracker-validate` gates.
+- **Idempotent:** embed the `<!-- lisa-monitor-finding: <fingerprint> -->` sentinel and search-before-create; never duplicate a live or just-resolved finding.
+- **Capped** at `max_candidates` (default 20), `core`/high-severity first; report how many were filed vs dropped.
+- **`--dry-run`** previews would-file tickets and creates nothing. **`--all-gaps`** widens gap filing to `recommended` tiers.
+
+`monitor` files only. The `intake` / `tracker-build-intake` cron picks the ready tickets up and implements them.
 
 ## Output
 
-A health summary with the relevant findings (failures, warnings, no-issue confirmations). For post-deploy verification (when called from `lisa:verify`), the summary becomes evidence on the originating work item.
+A single report: the health/anomaly summary (failures, warnings, no-issue confirmations) + the observability audit table (each in-scope dimension as `OK` / `WARN` / `MISSING` / `PRESENT (unverified)`) + the filing summary (tickets filed with refs + fingerprints, duplicates skipped, dropped count if the cap truncated; or would-file tickets under `--dry-run`). For post-deploy verification (when called from `lisa:verify`), the report-only summary becomes evidence on the originating work item.

package/plugins/lisa-agy/skills/verify/SKILL.md

@@ -38,7 +38,7 @@ Execute the **Verify** flow as defined in the `intent-routing` rule (loaded via
 3. **Push and PR** via `lisa:git-submit-pr`
 4. **Review loop** — handle CodeRabbit / human review comments via `lisa:pull-request-review`
 5. **Merge** when CI is green
-6. **Remote verification** — invoke the `lisa:monitor` skill against the target environment to confirm the deploy actually works (health endpoints, recent logs/errors, Validation Journey replay if defined). If remote verification surfaces a behavioral gap that the existing codified tests do not guard, invoke `codify-verification` to add coverage and open a follow-up PR.
+6. **Remote verification** — invoke the `lisa:monitor` skill against the target environment **in report-only mode** (`lisa:monitor <env> --report-only`) to confirm the deploy actually works (health endpoints, recent logs/errors, Validation Journey replay if defined). `--report-only` is required here: it keeps the post-deploy check a pure health/audit report and prevents monitor's standalone ticket-filing from creating issues during a verify run. If remote verification surfaces a behavioral gap that the existing codified tests do not guard, invoke `codify-verification` to add coverage and open a follow-up PR.
    - When remote verification needs credentials, follow the shared `verification-lifecycle` credential lookup order before declaring them missing: project e2e / Playwright config and fixtures first, then `.lisa.config.local.json` / environment variables, then documented ticket credentials such as a `Sign-in Required` section.
    - Should credentials remain genuinely unavailable after those sources are exhausted, do not complete the item on artifact-only evidence. Post a tracker comment stating what could not be verified and why, transition the work item to the configured blocked state, and apply the configured `needs-human` / `human-review` label, creating it if the tracker supports label creation and it is missing.
    - Evidence must explicitly distinguish `verified empirically` from `artifact-only / verification deferred`.

package/plugins/lisa-cdk/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "2.174.1",
+  "version": "2.175.0",
   "description": "AWS CDK-specific plugin",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-cdk/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "2.174.1",
+  "version": "2.175.0",
   "description": "AWS CDK-specific Lisa plugin.",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-cdk-agy/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "2.174.1",
+  "version": "2.175.0",
   "description": "AWS CDK-specific plugin",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-cdk-copilot/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "2.174.1",
+  "version": "2.175.0",
   "description": "AWS CDK-specific plugin",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-cdk-cursor/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "2.174.1",
+  "version": "2.175.0",
   "description": "AWS CDK-specific plugin",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-copilot/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa",
-  "version": "2.174.1",
+  "version": "2.175.0",
   "description": "Universal governance — agents, skills, commands, hooks, and rules for all projects",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-copilot/commands/monitor.md

@@ -1,6 +1,6 @@
 ---
-description: "Monitor application health across environments. Health endpoints, recent logs, error-rate spikes, performance, optional browser UAT. Routes to the stack-specific ops-specialist."
-argument-hint: "[environment]"
+description: "Monitor application health AND audit observability completeness for the current repo, then file build-ready tickets for anomalies and instrumentation gaps. Health/logs/errors/performance via the stack ops-specialist or stack-agnostic base probing; repo-scoped, idempotent, capped; files by default, --dry-run previews."
+argument-hint: "[environment] [--dry-run] [--report-only] [--all-gaps] [max_candidates=<n>]"
 ---
 
-Use the /lisa:monitor skill to check application health, logs, errors, and performance for the named environment. $ARGUMENTS
+Use the /lisa:monitor skill to check application health, logs, errors, and performance for the named environment, audit observability completeness, and file build-ready tickets for the anomalies and gaps it finds. Use `--dry-run` to preview without filing, `--report-only` for a health/audit summary with no filing, or `--all-gaps` to also file recommended-tier gaps (session replay, product analytics). $ARGUMENTS

package/plugins/lisa-copilot/rules/eager/observability-audit.md

@@ -0,0 +1,15 @@
+# Observability Audit (load-bearing)
+
+The **audit + file** arm of `lisa:monitor`. On top of its existing live-signal sweep, `monitor` audits how well the **current repo** is instrumented and files build-ready tickets for what it finds. `monitor` is **manual** (no cron) and **files only** — it never fixes; the `intake` / `tracker-build-intake` cron implements what it files.
+
+## Invariants
+
+- **Repo-scoped two ways.** Audit only the rubric dimensions in scope for the repo's detected profile (`frontend` / `backend` / `infra` — a frontend repo never evaluates backend tracing), and stamp every filed ticket `repo:<CURRENT_REPO>` as a single-repo leaf (resolve the repo via the `config-resolution` ladder; cannot resolve → report, do not file).
+- **Two finding types → build-ready leaves.** A live signal over the conservative bar → a `Bug` leaf; an in-scope MISSING instrumentation dimension (gap, e.g. "no DB/query analytics") → a `Task`/`Improvement` leaf. Always via `lisa:tracker-write` with `build_ready: true` (never a vendor write skill directly); never an Epic/container (gate S15).
+- **Conservative by default.** Only high-signal anomalies (over the documented thresholds) and `core` missing dimensions are filed. `--all-gaps` widens gap filing to `recommended` tiers; nothing lowers the anomaly bar.
+- **Idempotent.** Every ticket carries a `<!-- lisa-monitor-finding: <fingerprint> -->` sentinel; search-before-create (including closed tickets) means a re-run never duplicates a live or just-resolved finding.
+- **Capped.** At most `monitor.maxCandidates` tickets per run (default 20), highest-severity first; report filed-vs-dropped (and list the dropped) — never silently truncate.
+- **Gate-passing.** Each ticket is a real authored artifact: three-audience description, Gherkin AC, single-repo, Target Backend Environment, and a Validation Journey with a unique kebab-case `[EVIDENCE: <name>]` marker — so `tracker-validate` (S1–S15) accepts it. A finding that cannot be made into a credible ticket is reported, not filed.
+- **Verify guard.** When `monitor` is the post-deploy step of `lisa:verify` it runs **report-only** — Verify invokes it as `lisa:monitor <env> --report-only`, so it never files there. Filing is a standalone-only action.
+
+Full reference (profile detection, the rubric table, anomaly thresholds, ticket templates, idempotency contract, the cap, dry-run/report-only semantics): [reference/observability-audit.md](../reference/observability-audit.md).

package/plugins/lisa-copilot/rules/reference/config-resolution.md

@@ -156,6 +156,18 @@ fi
       "staleAfterHours": 2,
       "maxCandidates": 100
     }
+  },
+
+  "monitor": {
+    "maxCandidates": 20,
+    "gapTiers": "core",
+    "backoffHours": 24,
+    "thresholds": {
+      "sentryMinEvents24h": 10,
+      "errorRateSpikeMultiplier": 2,
+      "p95LatencyMs": 1000,
+      "xrayFaultRatePct": 5
+    }
   }
 }
 ```
@@ -360,6 +372,29 @@ documented defaults, so existing projects need no config change.
 | `intake.repair.staleAfterHours` | no | `2` | How long an in-progress item (build `claimed`, PRD `in_review`) may show no observable activity before repair-intake treats it as stalled and resumes it. `blocked` items are judged on blocker/answer state, not this threshold. Overridable per-run via `stale_after=<dur>` in `$ARGUMENTS` (which always wins). The same value is the default backoff window for loop-prevention notes. |
 | `intake.repair.maxCandidates` | no | `100` | Upper bound on how many stuck items repair-intake enumerates while searching for the first actionable one. Bounds scan cost. Overridable per-run via `max_candidates=<n>`. |
 
+### Monitor audit config (`monitor`)
+
+`lisa:monitor`'s audit-and-file arm reads an optional top-level `monitor` block. Every key is
+**optional** — a missing block inherits the documented defaults, so existing projects need no
+config change. The role SEMANTICS (what counts as an anomaly or gap, how findings become tickets)
+are fixed like every other lifecycle behavior; only these thresholds and caps are tunable. Full
+contract: the `observability-audit` rule.
+
+| Key | Required | Default | Notes |
+|-----|----------|---------|-------|
+| `monitor.maxCandidates` | no | `20` | Cap on tickets filed per standalone run (`core`/high-severity first). Overridable per-run via `max_candidates=<n>` in `$ARGUMENTS`, which always wins. |
+| `monitor.gapTiers` | no | `core` | Which gap tier files tickets by default: `core` (operationally load-bearing dimensions only) or `all` (also `recommended`). The `--all-gaps` run flag forces `all` for that invocation. |
+| `monitor.backoffHours` | no | `24` | How long after a finding's ticket is closed/resolved to keep suppressing a re-file (the recently-resolved dedup window), so a just-fixed regression isn't re-filed before its signal drains. Distinct from `intake.repair.staleAfterHours` (2h). |
+| `monitor.thresholds.sentryMinEvents24h` | no | `10` | Minimum 24h event count for an unresolved Sentry error to be fileable. |
+| `monitor.thresholds.errorRateSpikeMultiplier` | no | `2` | Error rate must be ≥ this × the prior-window baseline (and above an absolute floor) to file. |
+| `monitor.thresholds.p95LatencyMs` | no | `1000` | p95 latency at/above this (or up ≥ 50% vs prior window) is a fileable regression. |
+| `monitor.thresholds.xrayFaultRatePct` | no | `5` | X-Ray fault traces above this % of traces in the window is a fileable anomaly. |
+
+Resolution order matches every other key: `$ARGUMENTS` override → `.lisa.config.local.json` →
+`.lisa.config.json` → built-in default. `monitor` files only within the current repo (type-scoped
+rubric + `repo:<name>` single-repo leaves); it never fixes — the `intake` cron implements what it
+files.
+
 ### Intake assignee filter (`intake.assignee`)
 
 The optional intake assignee filter narrows **ready-item selection only**. It never assigns or