snappy-verify

Audit the live system state and report health. Reads evals, dispatch log, recent threads, running agents, artifact count, git status. Returns structured findings: errors, stale processes, incomplete runs, configuration drift. Failure mode: silent degradation (agents running fine but audit is broken, changes ship unverified).

Observed user requests

These are the prompts that triggered this skill being scaffolded:

• "verify that the system is working correctly"
• "verify the state of all components"
• "verify that changes were applied successfully"

The Steps section below is a first-draft response to this cluster - refine as eval scores accumulate.

Steps

1. Read system state (scope-only, no side effects)

Read evals.ndjson (last 50 rows), dispatch-chat.ndjson (last 30 rows), state/agents/.json (all), state/log/threads/.json (count), git status (clean?), running procs (server.ts PID, LaunchAgent daemons).

2. Gate

All log files readable? Git repo accessible? No permissions failures. If gate fails, emit error code with specific path.

3. Audit - structured report

Parse logs for patterns:

• Errors: RUN_FINISHED.error entries, backend spawn failures, TDZ crashes, unhandledRejection
• Staleness: evals.ndjson last entry >1h old, threads >3d old, server.ts PID stale
• Completeness: recent dispatch runs with toolCalls vs empty, artifact count vs recent saves
• Drift: server.ts newer than server.mjs (AOT stale), git status "modified" flags (unsaved work)

4. Emit report + eval

Structure: {ok: boolean, errors: [], warnings: [], recommendations: [], timestamp}. Score = 1.0 if ok + no warnings, 0.5 if warnings, 0.0 if errors.

import { score } from "../../lib/eval";
score("snappy-verify", run_id, { score: report.ok ? 1.0 : 0.0, primary_issue: report.errors[0] || null });

Eval

Actor: the thing that produces the output (a dispatch model, a CLI, or the state/lib/snappy-verify.ts library if one exists). Auditor: the thing that judges (must be different - see CONSTITUTION invariant #3). Name both explicitly.

Score convention:

If you cannot name a deterministic auditor, switch the frontmatter to eval: manual and log to state/log/pending-eval.ndjson - but fight to avoid manual. Manual is the escape hatch that leaks the thesis.

Gotchas

• mtime check fragile: git status "modified" can appear transiently (file write still in flight). Use git diff --quiet for true test.
• eval ndjson tail: tail -n50 won't work on NDJSON without line buffering; use grep -o ".*" | tail -50 or jq array slicing.
• LaunchAgent daemons: launchctl list | grep snappy works, but doesn't distinguish enabled/disabled. Check ~/Library/LaunchAgents/ for plist existence.
• Stale process cwd: pgrep -af server.ts may show old /tmp build paths even if new process exists at /Applications. Verify PIDs and start times, not paths.

snappy-verify - loader

Per-turn rules for snappy-verify. Full reference: state/skills/snappy-verify/SKILL.md.

Critical Rules

1. Scope-only by default. No side effects. Preview findings; require explicit apply: true before any write. (CONSTITUTION invariant #3.)
2. One eval row per run. score("snappy-verify", run_id, {score, primary_issue}). Score: 1.0 = ok+no warnings, 0.5 = warnings only, 0.0 = errors found. (CONSTITUTION invariant #4.)
3. Actor ≠ Auditor. Agent reads state; log tailing / pgrep / git diff are the auditors. Do not self-grade.
4. git diff --quiet for drift check. git status shows transient flags mid-write; git diff --quiet is the reliable dirty-worktree gate.
5. Safe NDJSON tail. tail -n50 evals.ndjson can buffer incorrectly; use grep -o ".*" | tail -50 or jq -s '.[-50:]' instead.
6. LaunchAgent daemons. launchctl list | grep snappy - also verify plist exists in ~/Library/LaunchAgents/ to distinguish enabled vs disabled.
7. Stale process cwd. pgrep -af server.ts may show old /tmp paths from previous builds. Verify PID + start time, not path string alone.

Commands

Report Structure

{
  ok: boolean;
  errors: string[];   // RUN_FINISHED.error, spawn failures, TDZ crashes, unhandledRejection
  warnings: string[]; // evals.ndjson last entry >1h, threads >3d old, stale server PID
  recommendations: string[];
  timestamp: string;
}

Self-Test

• [ ] Scope-only by default (no writes without apply: true)?
• [ ] One eval row per run, correct score (1.0/0.5/0.0)?
• [ ] Use git diff --quiet, not git status, for dirty-tree check?
• [ ] Use safe NDJSON tail (not raw tail -n)?
• [ ] Report shape: {ok, errors[], warnings[], recommendations[], timestamp}?

<!-- kernel-ok: historical attribution for the PID-loader pattern. -->

Self-correcting loader (PID feedback)

This is the rule that makes loaders learn. Ported from snappy-kernel, where it demonstrably worked: the snappy-dom-cartographer skill mapped Skool admin UI once, every later ship-agent inherited the full map for free.

Before you finish, do two things:

1. Fix gaps (P - proportional). MANDATORY. If this loader didn't cover your case - if you had to read another file, run an undocumented command, work around a wrong selector, or discover a quirk - you MUST attempt an Edit to this AGENTS.md before you log.

• Default action: edit this file. Surgical. Add the missing line, table

row, or code example where it belongs. No restructuring.

• Only LOGGED is allowed when: the fix needs >10 lines, spans multiple

files, or requires a structural rewrite. In that case the state/regen/drain.sh queue picks it up asynchronously.

• "I didn't have time" / "it's minor" / "the next agent will figure it out"

are NOT valid reasons. Minor gaps compound - that's the whole point of this loop.

• Concrete example of a valid P-fix: discover agent-browser screenshot

takes path positionally not as --output <path>. One line in a table. Edit it in. Do not just log it.

• The goal: the next agent never has to leave the loader.

2. Log the result.

echo "[$(date -u +%FT%TZ)] snappy-verify: <what was missing or fixed> [FIXED|LOGGED] action_kind=<kind>" >> state/log/loader-feedback.log

• FIXED = you patched this loader inline (P-fix).
• LOGGED = too large for inline; the PostToolUse enqueue + Stop-hook drain

will rewrite the loader from scratch on next session-end.

• action_kind: shape-ok | skill-ran | loader-rewritten | pattern-elevated

Do not skip this. Every agent run must leave the system better than it found it. The loader is the setpoint; you are the sensor; the gap is the error signal; closing the gap is the correction.