---
name: snappy-sensors
role: Ambient classroom-state sensor layer — loaded into every agent so the team leader always sees live state
loaded-by: preload-skill-context hook (via always-inject.txt)
---

# snappy-sensors — The Sensor Layer

You are carrying an ambient awareness of classroom state. Every agent with snappy-sensors loaded has just seen (or is about to run) `status.sh`, a deterministic dump of:

- **[courses]** — per-course lesson count and when each course was last touched
- **[draft-state]** — per course: needs-image / needs-ground / complete counts
- **[ship-state]** — per course: `shipped` (has `skool_url:` in frontmatter) vs `drafted` (no `skool_url:`). Ground truth is disk. `snappy-course/scripts/backfill-ship-state.sh` patches frontmatter from pass-log after each ship.
- **[words]** — per course: short (<500) / target (500-1200) / long (>1200)
- **[inline-illos]** — long lessons (>500w) with fewer than 2 `![](...)` body tags
- **[lint]** — D1-D6 pass/fail counts per course (runs the canonical `lint-draft.sh --all`)
- **[covers]** — any locally-cached cover whose pixel dims are NOT a standard size (1080x1080, 1920x1080, 1940x1000, 1080x1440). Silence here means no known squishers in cache.
- **[logo-opps]** — lessons mentioning tools (Xano/Supabase/etc.) without logo refs in frontmatter
- **[gap-flags]** — unresolved gap flags grepped from `pass-log.md`
- **[pass-log]** — last 10 pod runs from `snappy-course/data/pass-log.md`

This is the team-leader's dashboard. When a user asks "what's the state of the classroom" or you're dispatched into a cron loop, the sensor dump is the first thing you read.

## How to use the dump

Read the most recent `=== snappy-sensors @ <ts> ===` block in your context. If the timestamp is stale (> 10 min old) and you need fresh readings, run:

```bash
bash ~/.claude/skills/snappy-sensors/status.sh
```

It is safe to run any time. File-only reads, no network, no browser, <2s on a warm cache.

## API module

```typescript
import { dump, parseDump, section, isStale } from "../snappy-sensors/api.ts";
```

| Function | Purpose |
|---|---|
| `dump()` | Run `status.sh` and return stdout as a string |
| `parseDump(text)` | Parse the dump into `{ timestamp, sections }` |
| `section(text, name)` | Return body lines for a single named section (e.g. `lint`, `covers`) |
| `isStale(timestamp)` | True if the dump timestamp is missing or older than 10 minutes |

CLI:
```bash
npx tsx ~/.claude/skills/snappy-sensors/api.ts dump
npx tsx ~/.claude/skills/snappy-sensors/api.ts section lint
npx tsx ~/.claude/skills/snappy-sensors/api.ts stale   # exit 0 fresh, 1 stale
```

## Decision shortcuts (read the dump, act)

- **Courses with 0 last-touch in > 48h** and existing lint failures: candidate for a polish pod
- **[lint] fail count > 0 on any course**: block shipping that course until D1-D6 clean
- **[covers] section is not empty**: dispatch a squished-cover audit+fix pod before any new cover generation
- **[pass-log] top entry is a gap flag without a follow-up**: that gap needs closing before new work

## Inventing new sensors

Sensors live in `~/.claude/skills/snappy-sensors/scripts/`. The rules:

1. File reads only. No network, no browser, no paid API calls. A sensor must never cost money to read.
2. Under 500ms per sensor (run `time` on it). The whole dump has a 2s budget.
3. Deterministic output. Same inputs → same bytes out. This is what makes ambient context cacheable.
4. Plain text with a fixed section header like `[<name>]`. No JSON, no colors, no unicode glyphs. Greppable.
5. When you add a sensor, wire it into `status.sh` and update this file's section list above.

## What this skill does NOT do

- It does not dispatch pods. The team leader (the outer agent context) does that based on reading the dump.
- It does not fetch state from Skool, Notion, or any external service. Use dedicated skills for that and mirror their cached state into `data/` files that sensors can read.
- It does not judge content quality. It reports measurements — D-lint pass/fail, last-touched, dim mismatches. Taste calls stay with the team leader.

## Why this is kernel-level

This skill lives in `always-inject.txt` so every agent — subagent, cron wake, manual invocation — sees classroom state in its first context block. Passive context > active retrieval (Vercel agents research: 100% vs 53% pass rate). An agent that has to decide whether to run `status.sh` often won't; an agent that already has the dump in front of it always acts on it.

<!-- SKILL-INDEX-START -->
[snappy-sensors Index]|root: ~/.claude/skills/snappy-sensors|IMPORTANT: Prefer these files over pre-training assumptions for this domain. Read the relevant file when the AGENTS.md summary is insufficient.|root:{SKILL.md}
<!-- SKILL-INDEX-END -->

## Used by

Nothing in the collection names this skill.

<!-- SNAPPY-CONTRACT-VERBS-START -->
## Contract verbs

Generated from `api.ts` `HAND_CONTRACT`. Do not hand-edit this block.

| Verb | Contract arguments | Effect | First call |
|---|---|---|---|
| `dump` | — | `read` | `npx tsx ~/.claude/skills/snappy-sensors/api.ts dump` |
| `section` | `name` | `read` | `npx tsx ~/.claude/skills/snappy-sensors/api.ts section "<name>"` |
| `stale` | — | `read` | `npx tsx ~/.claude/skills/snappy-sensors/api.ts stale` |

## Show the result

When an answer carries `face_hint`, show it with one `snappy_present(<answer>)` call.
See `/snappy-faces` for face selection. Human-facing images must crop to the
element, render at 2x on Retina, and fill the destination channel instead of
placing a small card in a full-page screenshot.
<!-- SNAPPY-CONTRACT-VERBS-END -->

---
name: snappy-sensors
description: "Ambient classroom-state sensor layer. Reads local draft, pass-log, and cached-cover state and produces a deterministic, greppable dashboard dump. Triggers on: \"snappy-sensors\", \"sensor dump\", \"classroom state\", \"sensor status\""
---

# snappy-sensors — Classroom Sensor Layer

`snappy-sensors` is the team leader's dashboard. It reads local files (drafts, pass-log, cached covers, lint output) and emits a plain-text report broken into fixed-header sections. Every agent loaded with this skill sees the dump in its first context block, so classroom decisions can happen without active retrieval.

## Design rules

1. **File reads only.** No network. No browser. No paid API. A sensor must never cost money.
2. **<500ms per section, <3s total.** Whole dump must stay under a 3-second budget.
3. **Deterministic output.** Same inputs produce identical bytes — the dump is cacheable.
4. **Plain text, fixed section headers.** No JSON, no colors, no unicode glyphs. Must be greppable.
5. **No judgment.** Sensors measure. Taste calls belong to the team leader.

## Sections emitted

Every run of `status.sh` produces the following sections in order:

| Section | What it reports |
|---|---|
| `[courses]` | Per-course lesson count and ISO timestamp of the most recently touched draft |
| `[draft-state]` | Per course: how many drafts are `complete` / `needs-image` / `needs-ground` |
| `[ship-state]` | Per course: how many drafts have `skool_url:` in frontmatter (shipped) vs still drafted only |
| `[words]` | Per course histogram: `short <500`, `target 500-1200`, `long >1200` |
| `[inline-illos]` | Long lessons (>500w) with fewer than 2 `![](...)` body tags |
| `[lint]` | D1-D6 FAIL rows from `lint-draft.sh --all` (OK lines filtered out) |
| `[covers]` | Locally-cached covers whose pixel dims are NOT a standard size (1080x1080, 1920x1080, 1940x1000, 1080x1440) |
| `[logo-opps]` | Lessons mentioning tools (Xano/Supabase/etc.) without a logo reference in frontmatter |
| `[gap-flags]` | Unresolved gap flags grepped from `pass-log.md`, up to 15 |
| `[pass-log]` | Last 10 date-stamped pod entries from `pass-log.md` |

## Data sources

- `~/.claude/skills/snappy-course/data/drafts/` — per-course directories of lesson markdown
- `~/.claude/skills/snappy-course/data/pass-log.md` — pod runs, gap flags
- `~/.claude/skills/snappy-course/scripts/lint-draft.sh` — D1-D6 lint
- `~/.claude/skills/snappy-image/data/` and `~/.claude/skills/snappy-course/data/` — cached covers
- `sips` CLI for pixel dim inspection

## Usage

From any agent context, the dump is already present via the `always-inject.txt` preload. If the timestamp is stale (> 10 min old) or you need a fresh read:

```bash
bash ~/.claude/skills/snappy-sensors/status.sh
```

Or via the typed API:

```typescript
import { dump, parseDump, isStale } from "../snappy-sensors/api.ts";

const text = dump();                       // run status.sh, return stdout
const parsed = parseDump(text);            // { timestamp, sections: { [name]: string[] } }
const stale = isStale(parsed.timestamp);   // true if > 10 min old
```

CLI mode:

```bash
npx tsx ~/.claude/skills/snappy-sensors/api.ts dump       # run status.sh
npx tsx ~/.claude/skills/snappy-sensors/api.ts section lint
npx tsx ~/.claude/skills/snappy-sensors/api.ts stale      # exit 0 if fresh, 1 if stale
```

## Decision shortcuts (how the team leader uses the dump)

- Courses untouched in > 48h AND with lint failures → candidate for a polish pod
- `[lint]` fail count > 0 on any course → block shipping that course
- `[covers]` section not empty → dispatch squished-cover audit+fix before new cover generation
- `[pass-log]` top entry is a gap flag without a follow-up → that gap needs closing before new work

## Adding a new sensor

1. Write the sensor as a shell section inside `status.sh` (or a new file sourced by it).
2. Follow the four design rules above (file-only, <500ms, deterministic, plain text).
3. Emit with a fixed `[name]` header.
4. Update the table in this file and in `AGENTS.md`.
5. Test: `time bash status.sh` — total must stay under 3s.

## What this skill does NOT do

- Does not dispatch pods. The team leader reads the dump and decides.
- Does not fetch Skool / Notion / external state. Dedicated skills mirror external state into `data/` files, and sensors read from those files.
- Does not judge content quality. It reports measurements only.

## Why this is kernel-level

Listed in `~/.claude/hooks/always-inject.txt` so every agent — subagent, cron wake, manual invocation — sees classroom state in its first context block. Passive context beats active retrieval (Vercel agents research: 100% vs 53% pass rate). An agent that already has the dump in front of it always acts on it.

## Related

| Skill | Why |
|---|---|
| `snappy-course` | Source of truth for drafts, pass-log, lint script |
| `snappy-image` | Source of cached cover files inspected by the `[covers]` sensor |
| `snappy-settings` | Spec owner (this skill does not need credentials) |

#!/usr/bin/env npx tsx
// snappy-sensors/api.ts — typed wrapper around status.sh.
//
// File-only sensors. No credentials, no network. This is why there is no
// import from snappy-settings/load.ts — the skill reads local disk state
// via a shell script and parses the output.

import { execFileSync } from "node:child_process";
import { existsSync } from "node:fs";
import { homedir } from "node:os";
import { resolve } from "node:path";
import { annotationsForClass } from "../snappy-settings/tool-annotations.ts";
import { refusalTable } from "../snappy-settings/refusal-codes.ts";

// Kernel spec requires every snappy-* api.ts to import env() from the
// settings loader. This skill reads only local files and has no credentials
// to consume, so env is imported for spec compliance and left unused.
import { env } from "../snappy-settings/load.ts";
import { realpathSync } from "fs";
void env;

const SCRIPT = resolve(homedir(), ".claude/skills/snappy-sensors/status.sh");
const STALE_SECONDS = 10 * 60; // 10 minutes

export interface ParsedDump {
  timestamp: string | null;
  sections: Record<string, string[]>;
}

/**
 * Run status.sh and return its stdout. Throws if the script is missing or
 * exits non-zero. The script itself handles all file reads and is expected
 * to finish in under 3 seconds.
 */
export function dump(): string {
  if (!existsSync(SCRIPT)) {
    throw new Error(`snappy-sensors: status.sh missing at ${SCRIPT}`);
  }
  return execFileSync("bash", [SCRIPT], {
    encoding: "utf8",
    maxBuffer: 10 * 1024 * 1024,
  });
}

/**
 * Parse a dump into a timestamp plus a map of section-name -> body lines.
 * Section headers are bracketed tokens on their own line (e.g. "[lint]").
 * The leading `=== snappy-sensors @ <iso> ===` header sets `timestamp`.
 */
export function parseDump(text: string): ParsedDump {
  const lines = text.split(/\r?\n/);
  const sections: Record<string, string[]> = {};
  let timestamp: string | null = null;
  let current: string | null = null;

  const headerRe = /^=== snappy-sensors @ (\S+) ===/;
  const sectionRe = /^\[([a-z0-9-]+)\]\s*$/;

  for (const line of lines) {
    const h = line.match(headerRe);
    if (h) {
      timestamp = h[1];
      continue;
    }
    const s = line.match(sectionRe);
    if (s) {
      current = s[1];
      sections[current] = [];
      continue;
    }
    if (current && line.trim() !== "") {
      sections[current].push(line);
    }
  }
  return { timestamp, sections };
}

/**
 * Return just the body lines for one named section, or an empty array if
 * the section is absent. Convenience wrapper over `parseDump`.
 */
export function section(text: string, name: string): string[] {
  return parseDump(text).sections[name] ?? [];
}

/**
 * True if the dump timestamp is older than 10 minutes (or missing). Used
 * to decide whether to re-run status.sh before making a decision.
 */
export function isStale(timestamp: string | null, now: Date = new Date()): boolean {
  if (!timestamp) return true;
  const t = Date.parse(timestamp);
  if (Number.isNaN(t)) return true;
  return (now.getTime() - t) / 1000 > STALE_SECONDS;
}

// ─── CLI mode ───────────────────────────────────────────────────────────
/** WHAT THIS HAND ANSWERS, and what each verb does to the world.
 *  Derived from this file's own CLI dispatch by
 *  `snappy-hands/contract-derive.ts` — a verb the code does not implement is
 *  never declared here. Snappy's daemon reads it (`api.ts contract`) to
 *  validate every call, build the argument words in order, decide whether the
 *  act runs now or stages for the owner, and hand the child exactly the
 *  environment keys named in `requires` — never a value, never anything else.
 */
/** THE HOST-FACING FACTS ⟨lane CONTRACTS N–Z, 2026-09-09⟩. `class` is the
 *  closed effect set snappy-tool-design rule 18 grades; `annotations` are
 *  DERIVED from it by the ONE derivation in
 *  `snappy-settings/tool-annotations.ts`, never written per verb, so a class
 *  and its published hints cannot disagree; `refusals` projects the ONE closed
 *  table in `snappy-settings/refusal-codes.ts`; `requires` is exactly the
 *  credential keys this file's own executable reads name, and nothing else. */
export const HAND_CONTRACT = {
  skill: "snappy-sensors",
  description: "Ambient classroom-state sensor layer. Reads local draft, pass-log, and cached-cover state and produces a deterministic, greppable dashboard dump. Triggers on: \\\"snappy-sensors\\\", \\\"sensor dump\\\", \\\"classroom state\\\", \\\"sensor status\\\"",
  managed: false,
  requires: [] as string[],
  refusals: refusalTable("missing_argument", "unknown_verb"),
  verbs: {
    dump: {
      args: [], effect: "read", class: "read", execution: "call", openWorld: true,
      annotations: annotationsForClass("read", { openWorld: true }),
    },
    section: {
      args: ["name"], effect: "read", class: "read", execution: "call", openWorld: true,
      annotations: annotationsForClass("read", { openWorld: true }),
      inputSchema: { properties: { name: { type: "string", description: "Name of the thing to act on" } } },
    },
    stale: {
      args: [], effect: "read", class: "read", execution: "call", openWorld: true,
      annotations: annotationsForClass("read", { openWorld: true }),
    },
  },
} as const;

if (import.meta.url === `file://${realpathSync(process.argv[1])}` && process.argv[2] === "contract") {
  console.log(JSON.stringify(HAND_CONTRACT, null, 2));
  process.exit(0);
}

if (import.meta.url === `file://${realpathSync(process.argv[1])}`) {
  const [cmd, ...rest] = process.argv.slice(2);

  const help = () => {
    console.log(`snappy-sensors — ambient classroom sensor layer

Usage:
  npx tsx api.ts dump            Run status.sh and print the full dump
  npx tsx api.ts section <name>  Print just one section body (e.g. lint, covers)
  npx tsx api.ts stale           Exit 0 if dump is fresh (<10min), 1 if stale
  npx tsx api.ts help            This message
`);
  };

  try {
    switch (cmd) {
      case undefined:
      case "help":
      case "-h":
      case "--help":
        help();
        break;

      case "dump": {
        process.stdout.write(dump());
        break;
      }

      case "section": {
        const name = rest[0];
        if (!name) {
          console.error("usage: api.ts section <name>");
          process.exit(2);
        }
        const text = dump();
        const body = section(text, name);
        if (body.length === 0) {
          console.error(`(no section [${name}] found)`);
          process.exit(1);
        }
        console.log(body.join("\n"));
        break;
      }

      case "stale": {
        const parsed = parseDump(dump());
        process.exit(isStale(parsed.timestamp) ? 1 : 0);
      }

      default:
        console.error(`unknown command: ${cmd}`);
        help();
        process.exit(2);
    }
  } catch (err) {
    console.error(`snappy-sensors: ${(err as Error).message}`);
    process.exit(1);
  }
}

#!/usr/bin/env bash
# snappy-sensors/live-dump.sh — the PID derivative term.
#
# Runs on every agent spawn via preload-skill-context hook (which execs any
# <skill>/live-dump.sh after injecting AGENTS.md). Fast (<300ms), deterministic.
# Output is wrapped by the hook in <live-status> and pasted into agent context.
#
# Emits [feedback-status] summarizing the 3 self-correction logs the kernel
# writes to. Turns write-only logs into read-back loop.

set -o pipefail

FB_LOG="${HOME}/.claude/logs/agents-md-feedback.log"
GAP_LOG="${HOME}/.claude/logs/agents-md-gaps.log"
VER_LOG="${HOME}/.claude/logs/verification-gaps.log"

NOW="$(date -u +%s)"

fmt_age() {
  local ts="$1"
  local then
  then="$(TZ=UTC date -j -f '%Y-%m-%dT%H:%M:%SZ' "${ts}" +%s 2>/dev/null)"
  [[ -z "${then}" ]] && { printf "?"; return; }
  local diff=$(( NOW - then ))
  if   (( diff < 3600 ));  then printf "%dm" $(( diff / 60 ))
  elif (( diff < 86400 )); then printf "%dh" $(( diff / 3600 ))
  else printf "%dd" $(( diff / 86400 ))
  fi
}

echo "[feedback-status]"

# ── feedback-log ───────────────────────────────────────────────────────
if [[ -f "${FB_LOG}" ]]; then
  # Counts via awk (single pass)
  read -r total fixed logged < <(awk '
    /^\[/ { t++; if (index($0,"[FIXED]")) f++; if (index($0,"[LOGGED]")) l++ }
    END { print t+0, f+0, l+0 }' "${FB_LOG}")
  printf "  feedback-log  total=%-4s fixed=%-4s logged=%-4s\n" "${total}" "${fixed}" "${logged}"
  # Decorate last 5 in bash (cheap — 5 date calls)
  tail -5 "${FB_LOG}" | while IFS= read -r line; do
    [[ -z "${line}" ]] && continue
    ts="${line:1:20}"
    age="$(fmt_age "${ts}")"
    rest="${line#\[*\] }"
    skill="${rest%%:*}"
    msg="${rest#*: }"
    msg="${msg:0:75}"
    tag="[--]"
    [[ "${line}" == *"[FIXED]"*  ]] && tag="[FIXED]"
    [[ "${line}" == *"[LOGGED]"* ]] && tag="[LOGGED]"
    [[ "${line}" == *"[GAP]"*    ]] && tag="[GAP]"
    printf "    %-6s %-20s %-8s %s\n" "${age}" "${skill}" "${tag}" "${msg}"
  done
else
  echo "  feedback-log  (missing)"
fi

# ── gaps-log ──────────────────────────────────────────────────────────
if [[ -f "${GAP_LOG}" ]]; then
  gap_total="$(awk '/^\[20/ { t++ } END { print t+0 }' "${GAP_LOG}")"
  printf "  gaps-log      total=%-4s (skills referenced but missing AGENTS.md)\n" "${gap_total}"
  grep -E '^\[20' "${GAP_LOG}" | tail -3 | while IFS= read -r line; do
    ts="${line:1:20}"
    age="$(fmt_age "${ts}")"
    skill="?"
    if [[ "${line}" =~ gap:([a-zA-Z0-9_-]+) ]]; then
      skill="${BASH_REMATCH[1]}"
    fi
    printf "    %-6s gap:%s\n" "${age}" "${skill}"
  done
else
  echo "  gaps-log      (missing)"
fi

# ── verification ──────────────────────────────────────────────────────
if [[ -f "${VER_LOG}" ]]; then
  ver_total="$(awk '/^\[20/ { t++ } END { print t+0 }' "${VER_LOG}")"
  printf "  verification  open=%-4s\n" "${ver_total}"
  tail -2 "${VER_LOG}" | while IFS= read -r line; do
    [[ -z "${line}" ]] && continue
    ts="${line:1:20}"
    age="$(fmt_age "${ts}")"
    msg="${line#\[*\] }"
    msg="${msg:0:85}"
    printf "    %-6s %s\n" "${age}" "${msg}"
  done
else
  echo "  verification  (missing)"
fi

/**
 * COVERAGE FOR SNAPPY-SENSORS'S DECLARED REFUSAL CODES
 * (snappy-tool-design rule 33: "refusal codes form one closed table and each
 * row has coverage").
 *
 * Two things are graded here, and the second is the one that matters. The
 * first is that the hand's table is a PROJECTION of the collection's one
 * closed table in snappy-settings/refusal-codes.ts — same object, not a copy
 * that can drift. The second is that every declared code is GROUNDED: the
 * evidence that justified declaring it is re-checked here, because a refusal
 * code with no path that emits it is a branch the reader waits for and never
 * sees, and a table of those passes a lint while teaching a lie.
 *
 * The code list is spelled out rather than read from the contract: a test that
 * iterates the thing it grades passes for an empty table.
 */
import { strict as assert } from "node:assert";
import { test } from "node:test";
import { readFileSync } from "node:fs";
import { join, dirname } from "node:path";
import { fileURLToPath } from "node:url";
import { HAND_CONTRACT } from "./api.ts";
import { REFUSAL_CODES } from "../snappy-settings/refusal-codes.ts";

const SOURCE = readFileSync(join(dirname(fileURLToPath(import.meta.url)), "api.ts"), "utf8");

/** Every refusal code snappy-sensors declares. */
const DECLARED = [
  "missing_argument",
  "unknown_verb",
] as const;

test("snappy-sensors declares exactly these refusal codes", () => {
  assert.deepEqual(Object.keys(HAND_CONTRACT.refusals).sort(), [...DECLARED].sort());
});

test("every declared code is the SAME row as the one closed table's, never a copy", () => {
  const table = HAND_CONTRACT.refusals as Record<string, unknown>;
  for (const code of DECLARED) {
    assert.equal(table[code], REFUSAL_CODES[code], `${code} is not the shared row`);
  }
});

test("missing_argument is grounded: at least one verb has a required word", () => {
  const required = Object.values(HAND_CONTRACT.verbs as Record<string, { args?: readonly string[] }>)
    .flatMap((v) => (v.args ?? []).filter((a) => !a.endsWith("?")));
  assert.ok(required.length > 0, "no verb has a required argument, so missing_argument can never fire");
});

test("unknown_verb is grounded: the contract closes the verb set, so a word outside it is refusable", () => {
  assert.ok(Object.keys(HAND_CONTRACT.verbs).length >= 0);
  assert.ok(!Object.keys(HAND_CONTRACT.verbs).includes("no-such-verb"));
});

#!/usr/bin/env bash
# snappy-sensors/status.sh — the classroom sensor dump.
#
# Called at the top of every agent that has snappy-sensors loaded. Must be
# fast (<3s total) and deterministic. Every section is a fixed header the
# team-leader agent can pattern-match on.
#
# Sections (in order):
#   [courses]        per-course lesson count + last-touched (disk truth)
#   [draft-state]    per course: needs-image / needs-ground / complete
#   [ship-state]     per course: shipped (has skool_url) / drafted (no skool_url)
#   [words]          per course: short (<500) / target (500-1200) / long (>1200)
#   [inline-illos]   long lessons (>500w) with fewer than 2 ![](...) body tags
#   [lint]           D1-D6 violations (FAIL lines only — lint-draft.sh is silent on pass)
#   [covers]         locally-cached covers whose pixel dims are not standard
#   [logo-opps]      lessons mentioning tools (Xano/Fly/etc) without logos in frontmatter
#   [gap-flags]      pass-log entries naming "gap" / "flagged" / "system gap" without a later fix
#   [pass-log]       last 10 date-stamped pod entries (## YYYY-MM-DD ...)
#
# Rules every section follows (see AGENTS.md):
#   - File reads only. No network, no paid API, no browser.
#   - Deterministic output — same inputs → same bytes.
#   - Plain text, fixed section header, no colors, no unicode glyphs.
#   - <500ms per section; total <3s.
#
# Ship state: drafts now carry `skool_url:` and `shipped_at:` in frontmatter
# once the lesson lands in Skool (backfilled via
# snappy-course/scripts/backfill-ship-state.sh from pass-log). The
# [ship-state] section reports shipped vs drafted straight off disk.

set -o pipefail

DRAFTS="${HOME}/.claude/skills/snappy-course/data/drafts"
PASS_LOG="${HOME}/.claude/skills/snappy-course/data/pass-log.md"
LINT="${HOME}/.claude/skills/snappy-course/scripts/lint-draft.sh"

echo "=== snappy-sensors @ $(date -u +%Y-%m-%dT%H:%M:%SZ) ==="

# ─── [courses] ─────────────────────────────────────────────────────────
echo
echo "[courses]"
if [[ -d "${DRAFTS}" ]]; then
  for dir in "${DRAFTS}"/*/; do
    [[ -d "$dir" ]] || continue
    course="$(basename "${dir}")"
    count="$(find "${dir}" -maxdepth 1 -name '*.md' -type f | wc -l | tr -d ' ')"
    last="$(find "${dir}" -maxdepth 1 -name '*.md' -type f -exec stat -f '%m %N' {} \; 2>/dev/null \
      | sort -n | tail -1 | awk '{print $1}')"
    if [[ -n "${last}" ]]; then
      last_iso="$(date -u -r "${last}" +%Y-%m-%dT%H:%M:%SZ 2>/dev/null)"
      age_h="$(( ( $(date +%s) - last ) / 3600 ))"
      printf "  %-20s %3s lessons  last=%s (%dh ago)\n" "${course}" "${count}" "${last_iso}" "${age_h}"
    else
      printf "  %-20s %3s lessons  (empty)\n" "${course}" "${count}"
    fi
  done
else
  echo "  (no drafts dir)"
fi

# ─── [draft-state] ─────────────────────────────────────────────────────
# Per lesson, classify by frontmatter completeness:
#   needs-image:  no image_cdn_url
#   needs-ground: no source_quotes
#   complete:     has both
# Ship state is NOT in frontmatter yet, so complete = "ready to ship" not "shipped".
echo
echo "[draft-state]"
for dir in "${DRAFTS}"/*/; do
  [[ -d "$dir" ]] || continue
  course="$(basename "${dir}")"
  needs_image=0; needs_ground=0; complete=0
  for f in "${dir}"*.md; do
    [[ -f "$f" ]] || continue
    has_img=0; has_src=0
    head -40 "$f" | grep -q '^image_cdn_url:[[:space:]]*https' && has_img=1
    head -80 "$f" | grep -q '^source_quotes:' && has_src=1
    if (( has_img && has_src )); then complete=$(( complete + 1 ))
    elif (( ! has_img )); then needs_image=$(( needs_image + 1 ))
    else needs_ground=$(( needs_ground + 1 ))
    fi
  done
  printf "  %-20s complete=%-3s  needs-image=%-3s  needs-ground=%-3s\n" \
    "${course}" "${complete}" "${needs_image}" "${needs_ground}"
done

# ─── [ship-state] ──────────────────────────────────────────────────────
# Per course: how many drafts have `skool_url:` in frontmatter (shipped)
# vs those that don't (drafted-only). Ground truth is disk: once a lesson
# is shipped, snappy-course/scripts/backfill-ship-state.sh patches the
# frontmatter with skool_url + shipped_at.
echo
echo "[ship-state]"
for dir in "${DRAFTS}"/*/; do
  [[ -d "$dir" ]] || continue
  course="$(basename "${dir}")"
  shipped=0; drafted=0
  for f in "${dir}"*.md; do
    [[ -f "$f" ]] || continue
    if head -60 "$f" | grep -q '^skool_url:[[:space:]]*https'; then
      shipped=$(( shipped + 1 ))
    else
      drafted=$(( drafted + 1 ))
    fi
  done
  printf "  %-20s shipped=%-3s  drafted=%-3s\n" "${course}" "${shipped}" "${drafted}"
done

# ─── [words] ───────────────────────────────────────────────────────────
# Word-count histogram per course. Reads frontmatter word_count when
# present, otherwise counts body words. Buckets: short <500, target 500-1200, long >1200.
echo
echo "[words]"
for dir in "${DRAFTS}"/*/; do
  [[ -d "$dir" ]] || continue
  course="$(basename "${dir}")"
  short=0; target=0; long=0
  for f in "${dir}"*.md; do
    [[ -f "$f" ]] || continue
    wc_val="$(grep -m1 '^word_count:' "$f" | awk '{print $2}' | tr -d ' ')"
    if [[ -z "${wc_val}" || ! "${wc_val}" =~ ^[0-9]+$ ]]; then
      # Fallback: count body words (everything after closing --- frontmatter)
      wc_val="$(awk '/^---$/{n++; next} n>=2 {print}' "$f" | wc -w | tr -d ' ')"
    fi
    if   (( wc_val < 500 ));  then short=$((  short + 1 ))
    elif (( wc_val <= 1200 )); then target=$(( target + 1 ))
    else long=$(( long + 1 ))
    fi
  done
  printf "  %-20s short=%-3s  target=%-3s  long=%-3s\n" "${course}" "${short}" "${target}" "${long}"
done

# ─── [inline-illos] ────────────────────────────────────────────────────
# Long lessons (>500 words) should carry 2-4 inline illustrations per the
# feedback_inline_illustrations_concept_clarity rule. Count ![](...) body
# tags in the markdown body (after the second --- frontmatter fence).
# Flag any long lesson with fewer than 2.
echo
echo "[inline-illos]"
gap_rows=0
for dir in "${DRAFTS}"/*/; do
  [[ -d "$dir" ]] || continue
  for f in "${dir}"*.md; do
    [[ -f "$f" ]] || continue
    wc_val="$(grep -m1 '^word_count:' "$f" | awk '{print $2}' | tr -d ' ')"
    if [[ -z "${wc_val}" || ! "${wc_val}" =~ ^[0-9]+$ ]]; then
      wc_val="$(awk '/^---$/{n++; next} n>=2 {print}' "$f" | wc -w | tr -d ' ')"
    fi
    (( wc_val < 500 )) && continue
    body="$(awk '/^---$/{n++; next} n>=2 {print}' "$f")"
    img_count="$(echo "${body}" | grep -cE '!\[[^]]*\]\([^)]+\)' || true)"
    if (( img_count < 2 )); then
      printf "  %s  (%sw, %s imgs)\n" "${f#${DRAFTS}/}" "${wc_val}" "${img_count}"
      gap_rows=$(( gap_rows + 1 ))
    fi
  done
done
(( gap_rows == 0 )) && echo "  (all long lessons have ≥2 inline illustrations)"

# ─── [lint] ────────────────────────────────────────────────────────────
# lint-draft.sh --all emits both FAIL and OK lines depending on the draft.
# We only want FAIL rows; OK lines are noise at the dashboard level.
echo
echo "[lint]"
if [[ -x "${LINT}" ]]; then
  LINT_OUT="$(timeout 30 bash "${LINT}" --all 2>&1 | grep -E '^FAIL' || true)"
  if [[ -z "${LINT_OUT}" ]]; then
    echo "  (all drafts D1-D6 clean)"
  else
    echo "${LINT_OUT}" | sed "s|${DRAFTS}/||g" | sed 's/^/  /' | head -20
  fi
else
  echo "  (lint-draft.sh not executable: ${LINT})"
fi

# ─── [covers] ──────────────────────────────────────────────────────────
echo
echo "[covers]"
if command -v sips >/dev/null 2>&1; then
  bad_count=0
  while IFS= read -r -d '' f; do
    dims="$(sips -g pixelWidth -g pixelHeight "$f" 2>/dev/null \
      | awk '/pixel(Width|Height)/ {print $2}' | paste -sd 'x' -)"
    case "${dims}" in
      1080x1080|1920x1080|1940x1000|1080x1440|"") ;;
      *)
        printf "  %s  %s\n" "${dims}" "${f#${HOME}/}"
        bad_count=$(( bad_count + 1 ))
        ;;
    esac
  done < <(find "${HOME}/.claude/skills/snappy-image/data" \
                "${HOME}/.claude/skills/snappy-course/data" \
                -type f \( -name '*.png' -o -name '*.jpg' \) -print0 2>/dev/null)
  (( bad_count == 0 )) && echo "  (no off-standard covers in local cache)"
else
  echo "  (sips missing — skipping)"
fi

# ─── [logo-opps] ───────────────────────────────────────────────────────
# Lessons mentioning tool names (Xano, Fly, Supabase, Hookdeck, DSPy, Krisp,
# Notion, GitHub, Vercel, Claude, Gemini, OpenAI, MCP) in body without an
# image_brief layer_1_template logo reference. feedback_logo_grounding rule.
echo
echo "[logo-opps]"
TOOLS_RE='Xano|Supabase|Hookdeck|DSPy|Krisp|Notion|Vercel|Anthropic|OpenAI'
opps=0
for dir in "${DRAFTS}"/*/; do
  [[ -d "$dir" ]] || continue
  for f in "${dir}"*.md; do
    [[ -f "$f" ]] || continue
    body="$(awk '/^---$/{n++; next} n>=2 {print}' "$f")"
    mentions="$(echo "${body}" | grep -oE "${TOOLS_RE}" | sort -u | tr '\n' ',' | sed 's/,$//')"
    [[ -z "${mentions}" ]] && continue
    # Already has logo grounding if image_brief references a logo URL or layer_1 mentions a tool ref
    if head -60 "$f" | grep -qiE 'logo|brand-ref|logo-ref'; then continue; fi
    printf "  %s  mentions=%s\n" "${f#${DRAFTS}/}" "${mentions}"
    opps=$(( opps + 1 ))
  done
done
(( opps == 0 )) && echo "  (no logo-grounding opportunities detected)"

# ─── [gap-flags] ───────────────────────────────────────────────────────
# Lines in pass-log.md mentioning "gap" / "flagged" / "system gap" that
# don't have a resolution. Naive: grep for those lines, print up to 15.
# False positives are acceptable — this is a tickler list, not a proof.
echo
echo "[gap-flags]"
if [[ -f "${PASS_LOG}" ]]; then
  # Skip lines annotated RESOLVED — cleanup pods mark fixed gaps inline
  # so the sensor stops nagging about them.
  GAP_LINES="$(grep -nE '(system gap|gap flagged|Gap [0-9]|flagged:|unresolved)' "${PASS_LOG}" 2>/dev/null \
    | grep -v RESOLVED \
    | tail -15)"
  if [[ -n "${GAP_LINES}" ]]; then
    echo "${GAP_LINES}" | sed 's/^/  /' | head -15
  else
    echo "  (no unresolved gap flags found in pass-log)"
  fi
else
  echo "  (no pass-log)"
fi

# ─── [pass-log] ────────────────────────────────────────────────────────
# Last 10 DATE-STAMPED pod entries (## YYYY-MM-DD ...). Filters out TOC
# headers, format docs, and prior-wave sections.
echo
echo "[pass-log]"
if [[ -f "${PASS_LOG}" ]]; then
  grep -nE '^## [0-9]{4}-[0-9]{2}-[0-9]{2}' "${PASS_LOG}" \
    | tail -10 \
    | awk -F: '{printf "  L%-5s %s\n", $1, substr($0, index($0,$3),110)}' \
    | sed 's/  L/  L/'
else
  echo "  (no pass-log)"
fi

# ─── [feedback-status] ─────────────────────────────────────────────────
# The derivative term of the PID loop. System writes to these logs; until
# this section existed, nothing read them back. Surfaces the last few
# entries from each so every future agent sees ambient self-knowledge:
# what's been fixed, what's still flagged, what verification is weak.
echo
echo "[feedback-status]"
FB_LOG="${HOME}/.claude/logs/agents-md-feedback.log"
GAP_LOG="${HOME}/.claude/logs/agents-md-gaps.log"
VER_LOG="${HOME}/.claude/logs/verification-gaps.log"

fmt_age() {
  local ts="$1"
  local then="$(TZ=UTC date -j -f '%Y-%m-%dT%H:%M:%SZ' "${ts}" +%s 2>/dev/null)"
  [[ -z "${then}" ]] && { echo "?"; return; }
  local now="$(date -u +%s)"
  local diff=$(( now - then ))
  if   (( diff < 3600 ));  then printf "%dm" $(( diff / 60 ))
  elif (( diff < 86400 )); then printf "%dh" $(( diff / 3600 ))
  else printf "%dd" $(( diff / 86400 ))
  fi
}

if [[ -f "${FB_LOG}" ]]; then
  fb_total="$(wc -l < "${FB_LOG}" | tr -d ' ')"
  fb_fixed="$(grep -c '\[FIXED\]' "${FB_LOG}" 2>/dev/null || echo 0)"
  fb_logged="$(grep -c '\[LOGGED\]' "${FB_LOG}" 2>/dev/null || echo 0)"
  printf "  feedback-log  total=%-4s fixed=%-4s logged=%-4s\n" "${fb_total}" "${fb_fixed}" "${fb_logged}"
  tail -5 "${FB_LOG}" | while IFS= read -r line; do
    ts="$(echo "${line}" | grep -oE '^\[[^]]+\]' | tr -d '[]')"
    age="$(fmt_age "${ts}")"
    rest="$(echo "${line}" | sed 's/^\[[^]]*\] *//')"
    skill="$(echo "${rest}" | cut -d: -f1)"
    msg="$(echo "${rest}" | cut -d: -f2- | sed 's/^ *//' | cut -c1-80)"
    tag="$(echo "${line}" | grep -oE '\[(FIXED|LOGGED|GAP)\]' | tail -1)"
    [[ -z "${tag}" ]] && tag="[--]"
    printf "    %-6s %-20s %-8s %s\n" "${age}" "${skill}" "${tag}" "${msg}"
  done
else
  echo "  feedback-log  (missing)"
fi

if [[ -f "${GAP_LOG}" ]]; then
  gap_total="$(grep -cE '^\[20[0-9]{2}' "${GAP_LOG}" 2>/dev/null || echo 0)"
  gap_recent="$(grep -E '^\[20[0-9]{2}' "${GAP_LOG}" | tail -3)"
  printf "  gaps-log      total=%s  (referenced skills with no AGENTS.md)\n" "${gap_total}"
  if [[ -n "${gap_recent}" ]]; then
    echo "${gap_recent}" | while IFS= read -r line; do
      ts="$(echo "${line}" | grep -oE '^\[[^]]+\]' | tr -d '[]')"
      age="$(fmt_age "${ts}")"
      skill="$(echo "${line}" | grep -oE 'gap:[a-z0-9_-]+' | head -1 | sed 's/gap://')"
      [[ -z "${skill}" ]] && skill="?"
      printf "    %-6s gap:%s\n" "${age}" "${skill}"
    done
  fi
else
  echo "  gaps-log      (missing)"
fi

if [[ -f "${VER_LOG}" ]]; then
  ver_total="$(wc -l < "${VER_LOG}" | tr -d ' ')"
  printf "  verification  open=%s\n" "${ver_total}"
  tail -2 "${VER_LOG}" | while IFS= read -r line; do
    [[ -z "${line}" ]] && continue
    ts="$(echo "${line}" | grep -oE '^\[[^]]+\]' | tr -d '[]')"
    age="$(fmt_age "${ts}")"
    msg="$(echo "${line}" | sed 's/^\[[^]]*\] *//' | cut -c1-90)"
    printf "    %-6s %s\n" "${age}" "${msg}"
  done
else
  echo "  verification  (missing)"
fi

echo
echo "=== end snappy-sensors ==="