@onlooker-community/ecosystem 0.28.0 → 0.29.0

package/plugins/inspector/README.md

@@ -0,0 +1,155 @@
+# Inspector
+
+Per-edit lint and typecheck gate for the Onlooker ecosystem — runs the project's
+configured checks on **just the touched file** after every `Write`, `Edit`, and
+`MultiEdit`, so the agent sees its own lint and type errors before it claims
+success.
+
+Inspector is a sibling plugin to [`ecosystem`](../../) and assumes the Onlooker
+observability substrate (`~/.onlooker/`) is present.
+
+## Why it exists
+
+The ecosystem already has plugins that judge agent output after the fact and
+plugins that gate ambiguous writes before they happen. What it didn't have until
+now is a fast feedback loop that runs after every edit and tells the agent
+*whether the code it just wrote actually compiles*. Inspector is that loop.
+
+- **Not [proctor]** (planned) — proctor runs the project's full verification
+  command at `Stop`. Inspector runs only on touched files, only on `PostToolUse`.
+  Cheaper, fires far more often, narrower scope.
+- **Not [assayer]** — assayer parses the agent's final message for testable
+  claims and cross-checks them against actual exit codes in the transcript.
+  Assayer catches the agent *lying* about claims. Inspector ensures the agent
+  has *accurate ground truth* to make claims from. They compose: inspector
+  emits real pass/fail signals; assayer can later confirm the agent's claims
+  line up with those signals.
+- **Not a build system** — inspector runs the configured command, captures the
+  result, emits an event, exits. No cross-file caching, no dependency graphs.
+
+## How it works
+
+| Hook | Matcher | What Inspector does |
+|------|---------|---------------------|
+| `PostToolUse` | `Edit`, `Write`, `MultiEdit` | Resolves the touched file from `tool_input.file_path`, looks up the configured checks for the file's extension, runs each check with a per-check timeout, and emits `inspector.check.passed` / `.failed` / `.skipped` plus a single `inspector.run.completed` summary. Bounded by `total_timeout_seconds`. Always exits 0 — inspector is advisory and never blocks the tool call. |
+
+The hook's stdout (the additional-context channel for `PostToolUse` hooks) is
+the agent-facing summary. By default it's quiet on clean runs:
+
+```
+inspector: src/cart.ts
+  ✗ biome (3 issues, exit 1)
+      src/cart.ts:42:5 — Unused variable 'subtotal'
+      src/cart.ts:51:3 — Missing return type annotation
+      src/cart.ts:64:9 — Unreachable code
+  ✗ tsc (1 issue(s), exit 2)
+      src/cart.ts:42:5 — Type 'string | undefined' is not assignable to 'string'
+```
+
+Set `inspector.show_clean_runs: true` to surface the file header on passing
+checks too. The agent sees this on its next turn.
+
+## Activation
+
+Inspector ships disabled. Opt in per project (or globally) by adding the
+`inspector` block to `.claude/settings.json`:
+
+```jsonc
+{
+  "inspector": {
+    "enabled": true,
+    "checks": {
+      ".ts":  [{ "name": "biome",      "kind": "lint",      "argv": ["biome", "check", "${file}"] },
+               { "name": "tsc",        "kind": "typecheck", "argv": ["tsc",   "--noEmit"] }],
+      ".tsx": [{ "name": "biome",      "kind": "lint",      "argv": ["biome", "check", "${file}"] },
+               { "name": "tsc",        "kind": "typecheck", "argv": ["tsc",   "--noEmit"] }],
+      ".py":  [{ "name": "ruff",       "kind": "lint",      "argv": ["ruff",  "check", "${file}"] }],
+      ".sh":  [{ "name": "shellcheck", "kind": "lint",      "argv": ["shellcheck", "${file}"] }]
+    }
+  }
+}
+```
+
+Each check is an `{ name, kind, argv }` object. `kind` is one of `lint` or
+`typecheck` (used for downstream grouping). `argv` is the literal argv array;
+the following placeholders are expanded before exec:
+
+| Placeholder       | Resolves to                                |
+|-------------------|--------------------------------------------|
+| `${file}`         | absolute path to the touched file          |
+| `${file_relative}`| path relative to the repo root             |
+| `${repo_root}`    | the repo's `git rev-parse --show-toplevel` |
+
+A bare argv array (`["shellcheck", "${file}"]`) is also accepted as a shorthand
+— inspector treats the first entry as the check name and the kind as `lint`.
+
+## Config
+
+| Field | Default | Meaning |
+|---|---|---|
+| `enabled` | `false` | Master switch. |
+| `timeout_seconds_per_check` | `10` | Wall-clock cap per check. Exceeded → `inspector.check.skipped` with `reason: "timeout"`. |
+| `total_timeout_seconds` | `30` | Wall-clock cap for the whole run. Remaining checks emit `.skipped` with `reason: "total_budget_exhausted"`. |
+| `output_excerpt_max_bytes` | `4096` | Cap on captured output, both in the event and shown to the agent. Excess is replaced with `…[truncated]`. |
+| `show_clean_runs` | `false` | If `true`, the agent-facing summary includes passing checks too. Off by default to keep token usage low. |
+| `exclude_paths` | `["node_modules", ".git", "vendor", ".venv", "dist", ".next", ".nuxt", "build", "__pycache__", "target", "coverage"]` | Containment match against the file's path relative to the repo root. A match emits `inspector.check.skipped` with `reason: "excluded_path"` and runs no checks. |
+| `checks` | `{}` | Map of file extension (with leading dot) to an array of check definitions. Empty by default — opt in per project. |
+
+Config precedence: plugin defaults < `~/.claude/settings.json` (`.inspector`) <
+`<repo>/.claude/settings.json` (`.inspector`). Each layer fully replaces the
+`checks` array for a given extension; per-entry deep-merge is intentionally not
+supported because the override behavior would be unpredictable.
+
+## Events
+
+All events are registered in `@onlooker-community/schema`.
+
+| Event | When | Notable payload fields |
+|---|---|---|
+| `inspector.check.passed` | A check returned exit 0 | `file_path`, `tool_name`, `check_name`, `check_kind`, `argv`, `duration_ms` |
+| `inspector.check.failed` | A check returned non-zero | `exit_code`, `issue_count` (best-effort, may be `null`), `output_excerpt`, `output_truncated` |
+| `inspector.check.skipped` | A check or whole file was not run | `reason`: one of `disabled`, `excluded_path`, `no_extension_match`, `not_in_repo`, `tool_missing`, `timeout`, `total_budget_exhausted` |
+| `inspector.run.completed` | Once per hook fire after all checks | `checks_run`, `checks_passed`, `checks_failed`, `checks_skipped`, `duration_ms` |
+
+Downstream consumers that just want "did this edit produce broken code?" read
+`inspector.run.completed` and check `checks_failed > 0`. Consumers that want
+per-tool detail subscribe to `inspector.check.*`.
+
+## Whole-project checks (tsc, mypy, …)
+
+TypeScript's typecheck is project-scoped: `tsc --noEmit` checks every file, not
+just the touched one. There is no meaningful "tsc on one file." The supported
+pattern is to run the full project tsc and rely on its incremental cache
+(`tsBuildInfoFile`) to keep latency down. Same applies to mypy, cargo check,
+and golangci-lint.
+
+The downside is that `tsc --noEmit` reports errors in *every* file. Inspector's
+v1 surfaces all of them to the agent. A follow-up will add an opt-in filter
+that shows only errors mentioning the touched file plus a collateral-error
+count.
+
+## Failure modes
+
+Inspector is advisory — it never blocks the tool call. Specifically:
+
+- Missing tool on PATH → `.skipped` event, no agent-facing output
+- Timeout → `.skipped` event, one-line note to the agent
+- Hook script error → exit 0 with no event (last-resort path)
+- Schema validation error → logged to stderr, hook continues
+
+## Compatibility
+
+- bash 3.2+ (the macOS system bash is supported; no `mapfile` / `readarray` /
+  associative arrays)
+- `jq` is required (already a hard requirement for the ecosystem substrate)
+- `timeout` from coreutils is used when present; falls back to no-timeout mode
+  when absent (and emits a warning to the inspector hook log)
+
+## Design
+
+See [`docs/design.md`](docs/design.md) for the full design record, including
+the rationale for project-wide check semantics, output filtering, and open
+questions.
+
+[proctor]: https://github.com/onlooker-community/ecosystem#planned
+[assayer]: ../assayer

package/plugins/inspector/config.json

@@ -0,0 +1,25 @@
+{
+  "plugin_name": "inspector",
+  "storage_path": "~/.onlooker",
+  "inspector": {
+    "enabled": false,
+    "timeout_seconds_per_check": 10,
+    "total_timeout_seconds": 30,
+    "output_excerpt_max_bytes": 4096,
+    "show_clean_runs": false,
+    "exclude_paths": [
+      "node_modules",
+      ".git",
+      "vendor",
+      ".venv",
+      "dist",
+      ".next",
+      ".nuxt",
+      "build",
+      "__pycache__",
+      "target",
+      "coverage"
+    ],
+    "checks": {}
+  }
+}

package/plugins/inspector/docs/design.md

@@ -0,0 +1,286 @@
+# Inspector — Design
+
+**Layer:** verification / execution
+**Hook surface:** `PostToolUse` for `Write`, `Edit`, `MultiEdit`
+**Status:** initial design — first implementation under this doc
+
+Inspector is the per-edit lint and typecheck gate. Every time the agent writes
+to a file, inspector runs the project's configured checks on **just that file**
+and surfaces the result back to the agent before its next turn. The agent sees
+its own type errors immediately and self-corrects, instead of claiming success
+on broken code and getting caught later by [assayer] or a human reviewer.
+
+## What inspector is — and isn't
+
+- **Inspector is not proctor.** Proctor (planned) runs the project's full
+  verification command (`npm test`, `mise run check`, …) at `Stop`. Inspector
+  runs only on touched files, only on `PostToolUse`. Cheaper, fires far more
+  often, narrower scope.
+- **Inspector is not assayer.** Assayer (shipped) parses the agent's final
+  message for testable claims ("the build passes", "I ran the tests") and
+  cross-checks them against actual exit codes in the transcript. Assayer catches
+  the agent *lying* about claims. Inspector ensures the agent has *accurate
+  ground truth* to make claims from. They compose: inspector emits real
+  pass/fail signals; assayer can later confirm the agent's claims line up with
+  those signals.
+- **Inspector is not a build system.** It does not chain dependencies, cache
+  intermediate results, or share state across invocations beyond timeouts. It
+  runs the configured check, captures the result, emits an event, exits. If
+  configuration says "run tsc on a single file," it does that — even though
+  tsc's per-file mode loses project context. Choosing the right command for a
+  given language is the user's job; inspector executes what it is told.
+
+## Hook flow
+
+```
+PostToolUse(Write|Edit|MultiEdit)
+  → inspector-post-write.sh
+    → resolve touched file from tool_input.file_path
+    → load merged config (plugin defaults < home < repo)
+    → if disabled OR excluded path OR no extension match → emit .skipped, exit 0
+    → for each configured check matching the extension:
+        → expand ${file}, ${file_relative}, ${repo_root} in the command
+        → run with per-check timeout
+        → emit inspector.check.passed / .failed / .skipped
+    → exit 0 (never blocks the tool call)
+```
+
+The hook always exits 0. Inspector is advisory — it never blocks the agent's
+write. It surfaces what it found in the additional-context channel of the
+PostToolUse hook reply so the agent sees the result on its next turn.
+
+## Configuration
+
+The minimum useful configuration is a map from file extension to a list of
+commands to run. Each command is an argv array; `${file}` substitutes the
+canonical absolute path to the touched file.
+
+```jsonc
+{
+  "inspector": {
+    "enabled": false,
+    "timeout_seconds_per_check": 10,
+    "total_timeout_seconds": 30,
+    "exclude_paths": ["node_modules", ".git", "vendor", "dist", "build",
+                       ".next", "__pycache__", ".venv"],
+    "checks": {
+      ".ts":  [{ "name": "biome",      "argv": ["biome", "check", "${file}"] },
+               { "name": "tsc",        "argv": ["tsc",   "--noEmit"] }],
+      ".tsx": [{ "name": "biome",      "argv": ["biome", "check", "${file}"] },
+               { "name": "tsc",        "argv": ["tsc",   "--noEmit"] }],
+      ".py":  [{ "name": "ruff",       "argv": ["ruff",  "check", "${file}"] }],
+      ".sh":  [{ "name": "shellcheck", "argv": ["shellcheck", "${file}"] }]
+    }
+  }
+}
+```
+
+Merging follows the standard ecosystem precedence (plugin defaults < home <
+repo). Each layer can fully replace `checks` for a given extension by setting
+the array; deep-merge of individual entries within an extension is intentionally
+not supported — it makes the override behavior unpredictable.
+
+`config.json` ships with `enabled: false` to match the rest of the ecosystem.
+The first PR that ships inspector also adds an opt-in path in the README.
+
+## Path handling
+
+- `file_path` is resolved via `realpath` where available, falling back to
+  `readlink -f`, falling back to the raw input.
+- The file must be inside the current repo root (`git rev-parse --show-toplevel`
+  from `cwd`). Out-of-tree writes are skipped — inspector is per-project.
+- `exclude_paths` is matched against the file's path relative to the repo root.
+  Match semantics are *containment* (`vendor/foo.ts` matches `vendor`), not
+  glob. Compass uses globs; inspector uses containment because the use case is
+  "skip this whole directory tree."
+
+## Per-check execution
+
+Each check runs in the repo root (`cwd`) with the following environment:
+
+- inherited PATH plus any `mise`-shimmed bins (already set up at session start)
+- `INSPECTOR_FILE` — absolute path to the touched file
+- `INSPECTOR_FILE_RELATIVE` — relative to repo root
+- `INSPECTOR_REPO_ROOT` — the repo root
+- `INSPECTOR_PROJECT_KEY` — the project key
+
+`timeout_seconds_per_check` is enforced via the `timeout` command (or a
+fallback bash trap on systems that lack it). On timeout, inspector emits
+`inspector.check.skipped` with `reason: "timeout"`.
+
+If the command's first argv entry is not on PATH, inspector emits
+`inspector.check.skipped` with `reason: "tool_missing"`. This is the dominant
+"new project, lint not installed yet" case and must be quiet — no error in the
+hook output, just the skipped event in the log.
+
+## What the agent sees
+
+The hook's stdout (the additional-context channel for PostToolUse hooks)
+contains a compact, one-line-per-finding summary:
+
+```
+inspector: src/cart.ts
+  ✗ biome (3 issues)
+      src/cart.ts:42:5 — Unused variable 'subtotal'
+      src/cart.ts:51:3 — Missing return type annotation
+      src/cart.ts:64:9 — Unreachable code
+  ✗ tsc (1 error)
+      src/cart.ts:42:5 — Type 'string | undefined' is not assignable to 'string'
+```
+
+On clean runs, inspector either emits nothing to stdout (the silent case) or a
+single confirmation line, controlled by `inspector.show_clean_runs`
+(default `false`). Default silence avoids token spam on every edit.
+
+Output capture per check is bounded by `inspector.output_excerpt_max_bytes`
+(default 4096) — beyond that, inspector truncates with a `…[truncated]` marker
+both in the agent-facing output and in the event payload.
+
+## tsc and other whole-project checks
+
+TypeScript's typecheck is project-scoped: `tsc --noEmit` checks every file in
+the project, not just the touched one. Inspector cannot meaningfully run "tsc
+on a single file" — `tsc --noEmit src/foo.ts` runs in a degraded mode that
+loses project context (imports, references, lib types).
+
+The right behavior is to run `tsc --noEmit -p tsconfig.json` (full project)
+and filter the output to errors that mention the touched file. The first
+implementation runs the full project tsc and post-filters. This is more
+expensive than the lint case but cached by tsc's incremental compilation
+(`tsBuildInfoFile`). Users who care about latency can disable the tsc check
+per-project.
+
+Other languages with similar whole-project semantics (mypy, cargo check,
+golangci-lint) follow the same pattern: run the project-wide command, filter
+results to the touched file. Users opt into these in `config.json` because the
+cost is higher than per-file lint.
+
+## Events
+
+All four events are registered in `@onlooker-community/schema` under
+`plugins-verification.json`.
+
+### `inspector.check.passed`
+
+Emitted once per check that passed cleanly.
+
+```jsonc
+{
+  "file_path": "/abs/path/to/src/cart.ts",
+  "file_path_relative": "src/cart.ts",
+  "tool_name": "Edit",            // Write | Edit | MultiEdit
+  "check_name": "biome",
+  "check_kind": "lint",           // lint | typecheck
+  "argv": ["biome", "check", "/abs/path/to/src/cart.ts"],
+  "duration_ms": 124
+}
+```
+
+### `inspector.check.failed`
+
+Emitted once per check that returned a non-zero exit code.
+
+```jsonc
+{
+  "file_path": "/abs/path/to/src/cart.ts",
+  "file_path_relative": "src/cart.ts",
+  "tool_name": "Edit",
+  "check_name": "tsc",
+  "check_kind": "typecheck",
+  "argv": ["tsc", "--noEmit"],
+  "duration_ms": 980,
+  "exit_code": 2,
+  "issue_count": 3,
+  "output_excerpt": "src/cart.ts:42:5 — Type 'string | undefined' is not assignable to 'string'\n…"
+}
+```
+
+`issue_count` is best-effort: inspector parses common output formats (one
+issue per non-empty line, ignoring obvious headers/footers) where possible
+and falls back to `null` when the format is unknown.
+
+### `inspector.check.skipped`
+
+Emitted when a check did not run.
+
+```jsonc
+{
+  "file_path": "/abs/path/to/src/cart.ts",
+  "file_path_relative": "src/cart.ts",
+  "tool_name": "Edit",
+  "check_name": "tsc",            // optional — absent for whole-file skips
+  "reason": "tool_missing"        // tool_missing | disabled | excluded_path
+                                  //   | no_extension_match | timeout
+                                  //   | not_in_repo | total_budget_exhausted
+}
+```
+
+### `inspector.run.completed`
+
+Emitted once per hook invocation, after all per-check events for that file.
+
+```jsonc
+{
+  "file_path": "/abs/path/to/src/cart.ts",
+  "file_path_relative": "src/cart.ts",
+  "tool_name": "Edit",
+  "checks_run": 2,
+  "checks_passed": 0,
+  "checks_failed": 2,
+  "checks_skipped": 0,
+  "duration_ms": 1104
+}
+```
+
+Downstream consumers that just want "did this edit produce broken code?" read
+`inspector.run.completed` and check `checks_failed > 0`. Consumers that want
+per-tool detail subscribe to `inspector.check.*`.
+
+## Project-key derivation
+
+Same algorithm as the rest of the ecosystem:
+
+```
+SHA256("remote:" + git remote get-url origin) → first 12 hex chars
+  → fall back to SHA256("root:" + git rev-parse --show-toplevel)[:12]
+  → fall back to SHA256("cwd:" + pwd)[:12]
+```
+
+Implemented in `plugins/inspector/scripts/lib/inspector-project-key.sh`,
+mirroring the equivalent helper in cartographer.
+
+## Failure modes and fail-soft behavior
+
+Inspector is advisory. It never blocks the tool call. Specifically:
+
+- Missing tool on PATH → `.skipped` event, no agent-facing output
+- Timeout → `.skipped` event, agent sees `inspector: src/foo.ts — biome timed out`
+- Hook script error → exit 0 with no event (last-resort; logged to
+  `~/.onlooker/inspector/<project>/hook.log`)
+- Schema validation error → logged to stderr, hook continues
+- Concurrent invocation → no lock; each check runs independently. tsc's own
+  incremental cache handles concurrent invocations safely
+
+The "exit 0 with no event" path is the only case where inspector goes silent.
+This is deliberate: inspector is a noticeably new behavior surface; bugs in the
+hook script must not block writes.
+
+## Open questions
+
+These are deferred to a follow-up ADR after first real-world use.
+
+1. **Output filtering for whole-project checks.** Filtering tsc/mypy output to
+   the touched file is necessary for "only what you broke just now" UX. But
+   compile errors in unrelated files often *are* caused by this edit (a removed
+   export breaks five importers). Showing only the touched-file errors hides
+   real damage; showing all errors floods the channel. Tentative: show only
+   touched-file errors by default; add `inspector.show_collateral_errors`
+   config knob if requests come in.
+2. **Caching.** Repeated edits to the same file within seconds will re-run all
+   checks. Worth caching at the level of "skip identical file content"? Not
+   for v1.
+3. **Parallel checks.** Checks for the same file run sequentially today. Worth
+   parallelizing? Not for v1 — most lints finish in <500ms and bash-level
+   parallelism with timeouts is fiddly.
+
+[assayer]: ../../assayer/docs/design.md

package/plugins/inspector/hooks/hooks.json

@@ -0,0 +1,33 @@
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PLUGIN_ROOT\"/scripts/hooks/inspector-post-write.sh"
+          }
+        ]
+      },
+      {
+        "matcher": "Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PLUGIN_ROOT\"/scripts/hooks/inspector-post-write.sh"
+          }
+        ]
+      },
+      {
+        "matcher": "MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PLUGIN_ROOT\"/scripts/hooks/inspector-post-write.sh"
+          }
+        ]
+      }
+    ]
+  }
+}

package/plugins/inspector/scripts/hooks/inspector-post-write.sh

@@ -0,0 +1,124 @@
+#!/usr/bin/env bash
+# inspector-post-write.sh — PostToolUse hook for Write / Edit / MultiEdit.
+#
+# Runs the project's configured lint and typecheck commands on just the
+# touched file. Emits inspector.check.* and inspector.run.completed events.
+# Surfaces a compact summary on stdout for the agent's next turn.
+# Always exits 0 — inspector is advisory.
+
+set -uo pipefail
+
+# Recursion guard — prevents inspector from re-triggering itself if a check
+# command happens to write to a watched file via its own tooling.
+[[ "${INSPECTOR_NESTED:-0}" == "1" ]] && exit 0
+export INSPECTOR_NESTED=1
+
+PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-$(cd "$(dirname "$0")/../.." && pwd)}"
+export CLAUDE_PLUGIN_ROOT="$PLUGIN_ROOT"
+
+source "$PLUGIN_ROOT/scripts/lib/inspector-config.sh"
+source "$PLUGIN_ROOT/scripts/lib/inspector-project-key.sh"
+source "$PLUGIN_ROOT/scripts/lib/inspector-events.sh"
+source "$PLUGIN_ROOT/scripts/lib/inspector-run.sh"
+
+HOOK_INPUT=$(cat)
+CWD=$(printf '%s' "$HOOK_INPUT" | jq -r '.cwd // empty' 2>/dev/null)
+_HOOK_SESSION_ID=$(printf '%s' "$HOOK_INPUT" | jq -r '.session_id // empty' 2>/dev/null)
+TOOL_NAME=$(printf '%s' "$HOOK_INPUT" | jq -r '.tool_name // empty' 2>/dev/null)
+export _HOOK_SESSION_ID
+
+# Bail on missing input — never block the tool call.
+[[ -z "$CWD" ]] && exit 0
+case "$TOOL_NAME" in
+	Write|Edit|MultiEdit) ;;
+	*) exit 0 ;;
+esac
+export INSPECTOR_TOOL_NAME="$TOOL_NAME"
+
+# Resolve touched file from tool input.
+TOOL_TARGET=$(printf '%s' "$HOOK_INPUT" \
+	| jq -r '.tool_input.file_path // .tool_input.path // empty' 2>/dev/null)
+[[ -z "$TOOL_TARGET" ]] && exit 0
+
+# Canonicalize.
+if command -v realpath &>/dev/null; then
+	CANONICAL=$(realpath "$TOOL_TARGET" 2>/dev/null) || CANONICAL="$TOOL_TARGET"
+elif command -v readlink &>/dev/null; then
+	CANONICAL=$(readlink -f "$TOOL_TARGET" 2>/dev/null) || CANONICAL="$TOOL_TARGET"
+else
+	CANONICAL="$TOOL_TARGET"
+fi
+export INSPECTOR_FILE="$CANONICAL"
+
+REPO_ROOT=$(inspector_project_repo_root "$CWD")
+export INSPECTOR_REPO_ROOT="$REPO_ROOT"
+
+# Project-key derivation — always succeeds (falls back to cwd hash).
+PROJECT_KEY=$(inspector_project_key "$CWD")
+export INSPECTOR_PROJECT_KEY="$PROJECT_KEY"
+
+# File must live under repo root.
+if [[ "$CANONICAL" != "$REPO_ROOT"/* && "$CANONICAL" != "$REPO_ROOT" ]]; then
+	export INSPECTOR_FILE_RELATIVE="$CANONICAL"
+	inspector_config_load "$REPO_ROOT"
+	inspector_config_enabled || exit 0
+	inspector_emit_whole_file_skipped "not_in_repo"
+	exit 0
+fi
+export INSPECTOR_FILE_RELATIVE="${CANONICAL#"$REPO_ROOT"/}"
+
+inspector_config_load "$REPO_ROOT"
+
+if ! inspector_config_enabled; then
+	# Silent skip — do not even emit an event when disabled. Disabled means
+	# "this plugin is dormant," not "this file was uninteresting."
+	exit 0
+fi
+
+# Excluded path containment check.
+EXCLUDES=$(inspector_config_exclude_paths)
+if [[ -n "$EXCLUDES" && "$EXCLUDES" != "null" && "$EXCLUDES" != "[]" ]]; then
+	if jq -e --arg rel "$INSPECTOR_FILE_RELATIVE" \
+		'any(.[]; . as $p | $rel | startswith($p + "/") or . == $p or (("/" + $rel) | contains("/" + $p + "/")))' \
+		<<<"$EXCLUDES" >/dev/null 2>&1; then
+		inspector_emit_whole_file_skipped "excluded_path"
+		exit 0
+	fi
+fi
+
+# Look up checks for this file's extension. Use the *longest* matching suffix
+# so `.test.ts` matches before `.ts`. For now this is a simple two-step:
+# first the multi-dot suffix, then the simple extension.
+FILE_BASE=$(basename "$CANONICAL")
+EXT_LONG=""
+EXT_SHORT=""
+if [[ "$FILE_BASE" == *.*.* ]]; then
+	EXT_LONG=".${FILE_BASE#*.}"
+fi
+if [[ "$FILE_BASE" == *.* ]]; then
+	EXT_SHORT=".${FILE_BASE##*.}"
+fi
+
+CHECKS="[]"
+if [[ -n "$EXT_LONG" ]]; then
+	CANDIDATE=$(inspector_config_checks_for_extension "$EXT_LONG")
+	if [[ -n "$CANDIDATE" && "$CANDIDATE" != "[]" ]]; then
+		CHECKS="$CANDIDATE"
+	fi
+fi
+if [[ "$CHECKS" == "[]" && -n "$EXT_SHORT" ]]; then
+	CANDIDATE=$(inspector_config_checks_for_extension "$EXT_SHORT")
+	if [[ -n "$CANDIDATE" && "$CANDIDATE" != "[]" ]]; then
+		CHECKS="$CANDIDATE"
+	fi
+fi
+
+if [[ "$CHECKS" == "[]" ]]; then
+	inspector_emit_whole_file_skipped "no_extension_match"
+	exit 0
+fi
+
+# Execute. Always exit 0 regardless of check outcomes.
+inspector_run "$CHECKS" || true
+
+exit 0