Backed by: git log + filesystem mtime. No lib needed.

repo-heat

Reads the last-commit date for each state/skills/*.md file (skipping .agents.md and _template.md). Buckets them:

• hot - touched in the last 7 days
• warm - 7-30 days
• cold - >30 days

Emits a report at state/log/repo-heat/<date>.md with bucket counts and the full cold list. The cold list is the signal: skills that haven't moved in a month are either done, dormant, or forgotten.

Steps

1. List every state/skills/*.md (skip .agents.md, skip _template.md).
2. For each, run git log -1 --format=%cI -- <file> to get last-commit ISO

date. If the file is untracked, fall back to filesystem mtime.

1. Bucket by age: hot <7d, warm 7-30d, cold >30d. Sort the cold list by

oldest first.

1. Write state/log/repo-heat/<date>.md: header with counts, then the

cold list as a table | slug | last_touch | age_days |.

Eval

Actor: the bucket pass. Auditor: re-sum the buckets and confirm hot + warm + cold === total skills scanned (no row lost).

const total = hot.length + warm.length + cold.length;
const conserved = total === scanned;

score("repo-heat", run_id, {
  score: conserved ? 1.0 : 0.0,
  hot_count: hot.length,
  warm_count: warm.length,
  cold_count: cold.length,
  scanned,
  primary_issue: conserved ? null : "bucket-count-mismatch",
});

Gotchas

• A freshly-generated .agents.md loader will show as "hot" even if the

underlying skill hasn't moved - filter it out before scanning, or the report inflates hot count with noise.

• git log on a file that was renamed returns the rename commit, not the

original creation. That's fine for heat purposes - rename is a touch.

• If state/skills/ has files other than *.md (e.g. .bak), skip

them. Only the .md skill sheets count.

repo-heat - loader

Per-turn rules for the repo-heat skill. Full reference: state/skills/repo-heat.md. Do not skip these.

Critical Rules

• A freshly-generated .agents.md loader will show as "hot" even if the

Commands

|invoke: see state/skills/repo-heat.md Steps section |eval log: state/log/evals.ndjson (skill: "repo-heat")

Self-Test

An agent reading this should correctly:

1. [ ] Know which lib/bin artifact backs this skill (or that it is prose-only)
2. [ ] Know what to write to state/log/evals.ndjson after invoking
3. [ ] Know the eval mode (auto / shape / manual) from the .md frontmatter

Self-report

If this loader fell short, append a line:

echo "[$(date -u +%FT%TZ)] repo-heat: <what was missing>" >> ~/.claude/logs/snappy-os-loader-feedback.log

<!-- 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)] <skill-name>: <what was missing or fixed> [FIXED|LOGGED]" >> state/log/agents-md-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.

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.