skill-freshness

name	skill-freshness
description	Audit every enabled skill's upstream file dependencies for staleness — flags chained skills about to consume yesterday's article or a long-dead topic file
var
tags	["meta","dev"]

${var} — Optional. Pass dry-run to skip the notification (article still writes, log still appends). Pass a single skill name to scope the audit to that one consumer (e.g. var=tweet-allocator). Empty = audit every enabled skill in aeon.yml.

Today is ${today}. Walk every enabled skill in aeon.yml, parse the file dependencies it declares (explicit chains: consume: edges + implicit articles/, .outputs/, memory/topics/, memory/state/ references inside each SKILL.md), check the on-disk freshness of each dependency against a per-class threshold, and surface a single decision-ready report: which enabled consumer is about to read a file that's older than its expected freshness window.

The skill answers a question the existing health stack cannot: a chained skill that runs on schedule, with no API errors, and a 100% pass rate, can still silently act on stale upstream data if the producer skill failed earlier and nothing replaced its output. Today there is no check that tweet-allocator reading articles/token-report-*.md is reading today's version rather than last Tuesday's. This skill closes that gap.

Why this exists

Aeon's reliability story has three layers — heartbeat (per-run pulse), skill-analytics (per-skill ranking over time), skill-health (per-skill failure detection) — and one gap. None of them catches the case where a producer skill's last successful run was N days ago and a downstream consumer is still happily reading the cached file as if it were fresh. The output of tweet-allocator looks normal. The output of repo-pulse looks normal. The aggregate verdict from operator-scorecard looks normal. The only signal something is wrong is that the upstream articles/token-report-*.md mtime drifted past its freshness window — and nobody is looking.

This skill looks. It's a watchdog for silent staleness, not for failures. It does not duplicate skill-health's job (which catches consecutive failures by reading run history) or skill-update-check's job (which catches upstream SKILL.md drift in imported skills). Its scope is narrow: file-on-disk freshness vs the consumer that's about to read it.

Config

No new secrets. No new env vars. No new state file beyond memory/topics/skill-freshness-state.json for prior-run dedup.

Reads:

• aeon.yml — enabled skill list, chains: blocks (steps, consume, parallel), per-skill schedule (used to derive expected freshness windows).
• Every skills/*/SKILL.md whose corresponding aeon.yml entry has enabled: true — for implicit file-reference extraction.
• articles/, .outputs/, memory/topics/, memory/state/ — directory listings + mtimes only (no content reads beyond what's needed for fingerprinting).

Writes:

• articles/skill-freshness-${today}.md — the report.
• memory/topics/skill-freshness-state.json — fingerprint + last-verdict for run-to-run dedup.
• memory/logs/${today}.md — log block.

No outbound HTTP. No gh api calls. No env-var-in-headers. Pure local file I/O.

Freshness thresholds

The threshold for a dependency depends on its path class:

Path class	Threshold	Rationale
articles/{skill}-*.md	28 hours	Daily skills run once per day; 28h gives a 4h grace window for clock skew + run delays.
articles/{skill}-*.md produced by a weekly skill (cron starts with 0 _ * * 0-6 only)	8 days (192h)	Weekly producers have a 24h grace window.
.outputs/{skill}.md (chain runner outputs)	4 hours	Chain steps run minutes apart; a 4h-old .outputs/ file is a stale chain run.
memory/topics/{name}.md	7 days (168h)	Topic files are reference material, edited on memory-flush cycles (~weekly).
memory/state/{name}.json	30 days (720h)	State files are append/update-on-write; 30 days is a "skill hasn't run at all" signal.

Per-class thresholds are computed at runtime — not hardcoded per dependency. The skill discovers the producer's schedule from aeon.yml and picks the daily-vs-weekly bucket automatically.

Severity bands per dependency:

• OK — file mtime within threshold.
• WARN — file mtime past threshold but ≤ 2× threshold.
• STALE — file mtime past 2× threshold (real degradation, not a one-day blip).
• MISSING — referenced file does not exist on disk at all.

MISSING only fires for explicit dependencies (chains: consume: entries + canonical articles/{producer}-${today}.md patterns). Implicit grep-discovered references that simply never existed are not flagged — many SKILL.md files mention paths in pseudocode or comments that aren't real reads.

Steps

1. Parse var and resolve scope

• If ${var} matches ^dry-run → MODE=dry-run. Strip the prefix; remainder treated as scope override.
• Otherwise MODE=execute.
• If the remaining var is a non-empty string that matches an aeon.yml skill key → SCOPE=single, SCOPED_SKILL=$var. If it doesn't match any key, log SKILL_FRESHNESS_NO_MATCH: ${var} not in aeon.yml and exit (no notify, no article).
• Otherwise SCOPE=fleet and audit every enabled skill.

2. Load enabled-skill list and build the producer index

Parse aeon.yml. Build two maps:

• ENABLED — set of skill names where enabled: true. (Skills with enabled: false are not audited as consumers — their dependencies don't matter until they're turned on. They CAN appear as producers though, and their freshness is still tracked since other consumers may depend on them.)
• PRODUCER_CADENCE — map skill_name → daily | weekly | on_demand derived from the cron expression:
  • cron with * * * in days/months/weekdays → daily
  • cron whose weekday field matches ^[0-6]$ (single weekday) → weekly
  • workflow_dispatch or empty → on_demand (skipped from freshness audit; on-demand outputs have no expected cadence)

3. Gather explicit dependencies (chains: consume:)

Walk aeon.yml chains: blocks. For each step with a consume: [...] list, the consuming skill depends on .outputs/{producer}.md for each named producer. Record these as explicit edges with class outputs (4h threshold).

Also record any step with parallel: [...] followed by a downstream consume: reference as the same class.

4. Gather implicit dependencies (grep over enabled SKILL.md files)

For each skill in ENABLED, read its SKILL.md and extract every reference to:

articles/[a-zA-Z0-9_-]+(-\$\{today\}|-[0-9]{4}-[0-9]{2}-[0-9]{2})?\.md
\.outputs/[a-zA-Z0-9_-]+\.md
memory/topics/[a-zA-Z0-9_.-]+\.md
memory/state/[a-zA-Z0-9_.-]+\.json

Filter out:

• References inside fenced code blocks marked bash or text that are clearly examples (e.g. # example: articles/foo-2026-01-01.md).
• References to the consumer's own output paths (a producer self-reading its prior file is not a freshness gap; that's its own state-keeping). Detected when the producer prefix matches the consuming skill name.
• References inside the comment marker <!-- skill-freshness:ignore --> and the next line (escape hatch for SKILL.md authors who cite a path in prose without actually reading it).

Each surviving reference becomes an implicit edge with the appropriate path class.

5. Resolve canonical "today's article" patterns

For every articles/{producer}-${today}.md reference (or the date-suffixed equivalent), resolve to the actual most-recent file on disk: ls -1t articles/{producer}-*.md 2>/dev/null | head -1. Record the resolved path AND the producer's expected cadence (from step 2's PRODUCER_CADENCE map).

If no file matches the pattern at all, record as MISSING (only counted if the producer has cadence daily or weekly — on_demand producers may legitimately have never run).

6. Score each dependency

For every (consumer, dependency) pair:

mtime_age_hours = (now - file.mtime) in hours
threshold_hours = lookup_threshold(path_class, producer_cadence)

severity = OK     if mtime_age_hours <= threshold_hours
         | WARN   if mtime_age_hours <= 2 * threshold_hours
         | STALE  if mtime_age_hours >  2 * threshold_hours
         | MISSING if file does not exist (and edge is explicit OR pattern-canonical)

Aggregate per-consumer:

consumer_verdict = WORST severity across all its dependencies

MISSING > STALE > WARN > OK for the rollup.

7. Roll up to the fleet verdict

fleet_verdict = WORST consumer_verdict across all enabled consumers

Translation to exit status:

fleet_verdict	exit_status
OK across the board	FRESHNESS_OK
At least one WARN, no STALE / MISSING	FRESHNESS_WARN
At least one STALE OR MISSING	FRESHNESS_STALE

8. Dedup vs prior run

Compute a stable verdict fingerprint: sha1sum of the sorted list of consumer:dep:severity triples (excluding OK rows — only flagged rows count toward the fingerprint).

Compare against memory/topics/skill-freshness-state.json last_flagged_fingerprint. If identical AND today's fleet_verdict is the same as last_verdict:

• Article still writes (idempotent same-day overwrite).
• memory/topics/skill-freshness-state.json updates the last_run_at timestamp.
• Notify is suppressed with status FRESHNESS_NO_CHANGE — no point pinging the operator about the same stale file two days running. The state expires after 7 days; if nothing has changed for a week, the next run will re-emit the notification as a periodic reminder.

If different (a new flag appeared, an old one cleared, or the verdict band changed): notify normally.

9. Write the article

Path: articles/skill-freshness-${today}.md. Overwrite if exists.

# Skill Freshness — ${today}

**Verdict:** ${verdict_emoji} ${fleet_verdict} — ${one_line_summary}

*Audited ${enabled_count} enabled skills · ${dependency_count} dependencies checked · ${flagged_count} flagged*

## Flagged dependencies

| Consumer | Dependency | Class | Age | Severity |
|----------|-----------|-------|-----|----------|
| ${consumer} | `${path}` | ${class} | ${age_human} | ${severity_emoji} ${severity} |
| ... | | | | |

(Sorted by severity desc, then consumer name. Omit OK rows entirely — they are noise.)

## What this means per consumer

For every consumer whose verdict ≠ OK, one paragraph:

> **${consumer}** — depends on ${N} files; ${flagged_count} flagged. Worst: `${worst_path}` last updated ${age} ago (threshold ${threshold}h, class ${class}). The producer `${producer}` last successful run: ${producer_last_run_or_unknown}. Suggested action: ${one_line_suggestion}.

`one_line_suggestion` is a small lookup:
- `MISSING` + producer is `daily`/`weekly` → "Check `${producer}` run history with `./scripts/skill-runs --skill ${producer} --hours 168`."
- `STALE` → "Verify `${producer}` is still on schedule; if so, the producer ran but did not write a new article."
- `WARN` → "Monitor — one missed run, expected to clear on next producer cadence."

## Healthy consumers

A one-line per consumer with verdict OK: `- ${consumer} — ${dep_count} deps, all fresh.`

Cap at 8 entries; collapse the rest into `+ N more all-fresh consumers.` to keep the article scannable.

## Source status

- `aeon.yml`: ${parsed_skill_count} entries, ${enabled_count} enabled
- Implicit references discovered: ${implicit_count}
- Explicit `chains: consume:` edges: ${explicit_count}
- Files not yet on disk (skipped — implicit references that never existed): ${ignored_count}

---
*Companion to `skill-health` (per-skill failure detection) and `heartbeat` (per-run pulse). This skill catches the silent-staleness gap those two cannot: a consumer reading a stale file with no API errors and a 100% pass rate. Methodology: every age and threshold is computed from on-disk mtimes — this skill measures nothing it does not also report.*

10. Persist state

Write memory/topics/skill-freshness-state.json:

{
  "last_run_at": "${ISO timestamp}",
  "last_verdict": "${fleet_verdict}",
  "last_flagged_fingerprint": "${sha1}",
  "consumer_count": ${enabled_count},
  "dependency_count": ${dependency_count},
  "flagged_count": ${flagged_count},
  "first_seen_at": {
    "${consumer}:${path}": "${ISO timestamp}"
  }
}

first_seen_at records when each currently-flagged dep first crossed its threshold. Reused on the next run to detect "this has been stale for >7 days" — escalate one severity band in that case (WARN → STALE if persistent).

Cap first_seen_at to 200 entries; drop oldest by timestamp.

11. Send notification

If MODE == dry-run: skip notify, log FRESHNESS_DRY_RUN, exit.

If fleet_verdict == FRESHNESS_OK: log FRESHNESS_OK, do not notify (no news is good news; a green daily ping is noise).

If fleet_verdict ∈ {WARN, STALE} AND fingerprint changed since last run: notify.

If fingerprint identical to last run AND last run was within 7 days: log FRESHNESS_NO_CHANGE, do not notify.

Notification body:

*Skill Freshness — ${today}*
${verdict_emoji} ${fleet_verdict} — ${flagged_count} of ${dependency_count} deps flagged across ${affected_consumer_count} of ${enabled_count} enabled consumers

Worst:
- ${consumer_1} ← ${path_1} (${age_1} old, class ${class_1}, sev ${sev_1})
- ${consumer_2} ← ${path_2} (${age_2} old, class ${class_2}, sev ${sev_2})
- ${consumer_3} ← ${path_3} (${age_3} old, class ${class_3}, sev ${sev_3})

Action: ${one_line_action_for_worst_consumer}
Full: articles/skill-freshness-${today}.md

Cap message at ~3500 chars. Drop "Worst" entries 4+ if exceeded.

12. Log to memory/logs/${today}.md

## Skill Freshness
- **Skill**: skill-freshness
- **Verdict**: ${verdict_emoji} ${fleet_verdict}
- **Audited**: ${enabled_count} enabled consumers · ${dependency_count} deps · ${flagged_count} flagged
- **Worst**: ${consumer_with_worst_severity} — ${worst_path} (${worst_age} old, ${worst_severity})
- **Article**: articles/skill-freshness-${today}.md
- **Notification sent**: ${yes|no — FRESHNESS_OK|no — FRESHNESS_NO_CHANGE|no — dry-run}
- **Status**: ${FRESHNESS_OK|FRESHNESS_WARN|FRESHNESS_STALE|FRESHNESS_NO_CHANGE|FRESHNESS_DRY_RUN}

Exit taxonomy

Status	Meaning	Notify?
FRESHNESS_OK	every enabled consumer's deps are fresh	No (silence is the signal)
FRESHNESS_WARN	at least one dep past 1× threshold but no STALE/MISSING	Yes (only on fingerprint change)
FRESHNESS_STALE	at least one dep past 2× threshold OR a canonical-pattern dep MISSING	Yes (only on fingerprint change)
FRESHNESS_NO_CHANGE	flagged set identical to prior run, last run < 7 days ago	No (re-emits after 7d)
FRESHNESS_DRY_RUN	var=dry-run mode	No (article still writes)
SKILL_FRESHNESS_NO_MATCH	${var} named a skill not in aeon.yml	No

Sandbox note

Pure local file I/O — no curl, no gh api, no env-var-in-headers, no prefetch script. Every read is a directory listing or an mtime call; every write is to articles/, memory/topics/, or memory/logs/. Works in the GitHub Actions sandbox without any of the network workarounds other skills need. The only outbound call is ./notify itself, which is already sandbox-safe (postprocess-notify pattern).

Constraints

• Read-only across producers. This skill never re-runs a producer to refresh its output, never deletes stale files, never edits another skill's SKILL.md. It reports; the operator (or skill-repair) acts.
• Enabled consumers only. A skill with enabled: false does not need its dependencies audited — it isn't going to consume them. This keeps the report scoped to what's actually live in the schedule.
• Implicit dependencies are best-effort. Grep-based discovery is heuristic. False positives are tolerated (consumer paragraph clarifies why); false negatives are accepted (an explicit chains: consume: edge is the source of truth for chain runs). The goal is to surface the worst-case staleness, not to prove formally complete coverage.
• Per-class thresholds, not per-skill. The threshold for articles/token-report-*.md is the same as for articles/repo-pulse-*.md: the path class drives the window, derived from the producer's cadence in aeon.yml. This keeps the table maintainable as the fleet grows.
• Fingerprint-based dedup. A stale file flagged today and still stale tomorrow does not re-notify. The 7-day re-emit window handles the case where a chronic stale file has been forgotten about.
• No issue filing. Anomalies surface in the verdict and the article. Persistence and resolution belong to skill-health. This skill is read-only across memory/issues/.
• Idempotent. Same-day reruns overwrite the article and state file. The log entry appends one block per run.