vigiles 12.1.0 → 12.2.0

package/README.md

@@ -3,6 +3,15 @@
   This file is the FRONT DOOR + a marketing asset for someone who already lives
   in Claude Code / Codex. Optimize for a phone-skimmer.
 
+  TAGLINE = VERIFY-FIRST (decided 2026-07): "Catch the silent breakage in your
+  Claude Code & Codex setup" + subhead "verify your CLAUDE.md, skills, and hooks
+  are real — and prove they actually work." Lead with references-are-real (the
+  unique catch only vigiles makes); test/observe fold in AFTER. Do NOT revert to
+  the old test-first "tests your skills never had" tagline. Stay coding-scoped
+  (name CC/Codex + CLAUDE.md/skills/hooks) so it's never mistaken for a
+  general-agent tool. NOT "observability" as the headline (it undersells verify +
+  reads as the general-app category).
+
   SPINE = CONCEPT 5 (proof/demo-led). Lead with REAL, screenshotable catches on
   plugins people actually ship, THEN explain the mechanism. The proofs are not
   illustrative — every block traces to a real dogfood run captured in
@@ -83,7 +92,11 @@
 <h1 align="center">vigiles</h1>
 
 <p align="center">
-  <strong>The tests your agent's skills and hooks never had.</strong>
+  <strong>Catch the silent breakage in your Claude Code &amp; Codex setup.</strong>
+</p>
+
+<p align="center">
+  Verify your CLAUDE.md, skills, and hooks are real — and prove they actually work.
 </p>
 
 <p align="center">
@@ -94,14 +107,11 @@
 
 ---
 
-**You installed some plugins and wrote a few skills. Do they actually work?**
+**Your skills, hooks, and instructions are your agent's harness — the half you wrote, and the half nothing checks.**
 
-Your skills, hooks, and instructions are your agent's **harness** — the half you wrote
-and own, and the half nothing checks. A skill that never fires. Two skills the agent
-confuses. A subagent wired to a tool that doesn't exist. It breaks silently, and you
-find out mid-task.
+A subagent wired to a tool that doesn't exist. A hook that looks like it blocks and doesn't. Two skills the agent can't tell apart. It all looks fine, and it breaks silently mid-task.
 
-It's a library with no tests. This runs them:
+vigiles checks your harness is _real_, not just well-formed:
 
 ```bash
 npx vigiles audit
@@ -160,9 +170,10 @@ This subagent — a helper your main agent hands a task to — declares a tool t
 doesn't exist. The harness drops it silently, so the agent loses a capability it
 thinks it has. vigiles catches it and gives you the **one-line fix**.
 
-That's the whole idea — it checks your harness against reality, not style. Every path,
-script, code symbol, and linter rule, verified to exist _and_ be enabled across 7
-catalogs (ESLint, Ruff, Clippy + four more).
+That's the whole idea — it checks your harness against reality, not style. Every
+referenced tool, hook, file, script, and skill is verified to actually resolve — and
+where you name a linter rule, it's checked to exist _and_ be enabled (ESLint, Ruff,
+Clippy and more).
 **[Full guide →](docs/verifying-instruction-files.md)**
 
 All three catches are free and need no model — and vigiles **prevents** other whole

package/action.yml

@@ -38,6 +38,18 @@ inputs:
     description: "On pull_request events, post/update a sticky PR comment with the result ('true' or 'false'). Requires `pull-requests: write`."
     required: false
     default: "true"
+  capability-diff:
+    description: >
+      On pull_request events, compare the agent's capability surface (the
+      subagents' tool/effect blast radius) against the PR base and fold the diff
+      into the sticky comment (maps to `audit --capability-diff`). Requires
+      `fetch-depth: 0` on checkout so the base commit is present. 'true' or 'false'.
+    required: false
+    default: "false"
+  fail-on-widen:
+    description: "With capability-diff, fail the run when the PR WIDENS the blast radius (maps to the CLI's --fail-on-widen). 'true' or 'false'."
+    required: false
+    default: "false"
   github-token:
     description: "Token used to post the PR comment. Defaults to the workflow token."
     required: false
@@ -64,6 +76,8 @@ runs:
         VIGILES_CATALOG_ONLY: ${{ inputs.catalog-only }}
         VIGILES_ACTION_PATH: ${{ github.action_path }}
         VIGILES_COMMENT: ${{ inputs.comment }}
+        VIGILES_CAPABILITY_DIFF: ${{ inputs.capability-diff }}
+        VIGILES_FAIL_ON_WIDEN: ${{ inputs.fail-on-widen }}
         GH_TOKEN: ${{ inputs.github-token }}
       run: |
         set -euo pipefail
@@ -114,6 +128,57 @@ runs:
         status="${PIPESTATUS[0]}"
         set -e
 
+        # Capability diff (moat #2): did this PR WIDEN the agent's blast radius?
+        # Runs orthogonally to the main command — it's an additive PR-comment
+        # section, so it works whatever `command` gated above. The BEFORE tree is
+        # a detached worktree of the PR base; the AFTER tree is this checkout.
+        capdiff=""       # markdown appended to the sticky comment
+        capstatus=0
+        if [[ "${VIGILES_CAPABILITY_DIFF:-false}" == "true" \
+              && "${GITHUB_EVENT_NAME:-}" == "pull_request" ]]; then
+          base_sha="$(jq -r '.pull_request.base.sha // empty' "${GITHUB_EVENT_PATH:-/dev/null}")"
+          if [[ -z "$base_sha" ]]; then
+            echo "::warning::capability-diff: no PR base sha in the event payload"
+          else
+            # A shallow checkout may not carry the base commit — fetch it first.
+            git fetch --no-tags --depth=1 origin "$base_sha" >/dev/null 2>&1 \
+              || git fetch --no-tags origin "$base_sha" >/dev/null 2>&1 || true
+            base_dir="$(mktemp -d)"
+            # Materialize the base tree with `git archive` (NOT a worktree): it
+            # exports stored blobs WITHOUT running checkout/smudge filters, so it's
+            # light and can't trip a required filter (e.g. git-crypt) the runner
+            # lacks. The agent surface (unencrypted) lands as plaintext to diff.
+            if git archive "$base_sha" 2>/dev/null | tar -x -C "$base_dir" 2>/dev/null; then
+              # Diff the SAME relative dir in both trees (support a subdir working-directory).
+              rel="$(git rev-parse --show-prefix 2>/dev/null || echo '')"
+              before="${base_dir%/}/${rel}"; before="${before%/}"
+              capout="$(mktemp)"
+              fail_flag=(); [[ "${VIGILES_FAIL_ON_WIDEN:-false}" == "true" ]] && fail_flag=(--fail-on-widen)
+              # --no-html --no-json: this run is for the diff only, so skip the
+              # report artifacts. The full audit still streams to the CI log; only
+              # the capability-diff paragraph is extracted for the sticky comment.
+              set +e
+              "${runner[@]}" audit . --capability-diff="$before" --no-html --no-json "${fail_flag[@]}" 2>&1 | tee "$capout"
+              capstatus="${PIPESTATUS[0]}"
+              set -e
+              # Pull out just the "Capability surface …" paragraph (a self-contained
+              # block with no internal blank lines), then drop the no-change case
+              # so a PR that touches nothing capability-relevant gets no section.
+              capdiff="$(awk '/Capability surface/{f=1} f&&NF{print} f&&!NF{exit}' "$capout")"
+              case "$capdiff" in *"unchanged"*) capdiff="" ;; esac
+            else
+              echo "::warning::capability-diff: could not materialize PR base ${base_sha} (need fetch-depth: 0?)"
+            fi
+            rm -rf "$base_dir" 2>/dev/null || true
+          fi
+        fi
+
+        # A capability WIDENING (fail-on-widen → exit 1) flips an otherwise-green
+        # run to failed, so the gate is visible in the output + PR comment.
+        if [[ "$capstatus" -ne 0 && "$status" -eq 0 ]]; then
+          status="$capstatus"
+        fi
+
         if [[ "$status" -eq 0 ]]; then
           echo "valid=true" >> "$GITHUB_OUTPUT"
           headline="✅ \`vigiles ${cmd}\` passed"
@@ -130,6 +195,14 @@ runs:
           echo
           echo "$headline"
           echo
+          if [[ -n "$capdiff" ]]; then
+            echo "### Capability diff"
+            echo
+            echo '```'
+            echo "$capdiff"
+            echo '```'
+            echo
+          fi
           echo '<details><summary>Output</summary>'
           echo
           echo '```'

package/dist/audit-report.d.ts

@@ -13,6 +13,7 @@
  */
 import { type AuditScore } from "./audit-score.js";
 import { type Recommendation } from "./optimize.js";
+import type { LedgerSummary } from "./observe.js";
 import type { AdoptabilityResult } from "./adoptability.js";
 import type { ScanReport, MarketplaceInfo } from "./scan.js";
 import type { PluginScore } from "./leaderboard.js";
@@ -95,10 +96,20 @@ export interface AuditReport {
      * at least one adoptable surface. Additive/optional — schema version unchanged.
      */
     readonly adoptable?: Adoptable;
+    /**
+     * The flight-recorder summary — what the harness actually DID in real sessions
+     * (hook/agent decisions, counts, recent denials), read off `.vigiles/runs.jsonl`.
+     * Present only when the local ledger has records. Additive/optional — schema
+     * version unchanged. The CLI reads + summarizes the ledger and passes it in, so
+     * the pure builder stays fs-free.
+     */
+    readonly observations?: LedgerSummary;
 }
 export interface BuildAuditReportOptions {
     readonly harness: string;
     readonly vigilesVersion: string;
+    /** The flight-recorder summary from the local ledger (omit when empty). */
+    readonly observations?: LedgerSummary;
     /**
      * The repo-relative paths of surfaces that exist but have no `.spec.ts` yet,
      * computed by the CLI's layout-aware `discoverAdoptableSurfaces` (so the pure

package/dist/audit-report.js

@@ -70,6 +70,7 @@ function buildAuditReport(report, opts) {
             untested: report.untested,
         },
         ...(adoptable ? { adoptable } : {}),
+        ...(opts.observations ? { observations: opts.observations } : {}),
     };
 }
 /** Assemble the versioned {@link LeaderboardReport} — pure, no clock. */