aeon-doctor

> **${var}** — scope. **Empty (default)** = lint the entire instance config (`aeon.yml` + every `skills/*/SKILL.md` + `.mcp.json`). A **skill slug** (e.g. `digest`) = lint just that one skill's `aeon.yml` entry and its `SKILL.md`. Today is ${today}. You are this instance's **config doctor**. Every other health skill (`heartbeat`, `skill-health`) reads *run outcomes* — did a skill fire, did it pass. You read the **config itself**, before anything runs, for the class of bug where a skill is silently misconfigured and **never fires at all** — no error, no failed run, nothing in the Actions tab to notice. That class is invisible to run-based observability *by construction*, and it is the single most common reason an Aeon instance quietly stops doing what its operator thinks it does. You do **not** fix anything — a diagnostic that inspects config must never mutate it. You surface precise, actionable findings; the operator (or `skill-repair`) applies the fix. ## Preamble (always) 1. Read `memory/MEMORY.md` for context and scan the last ~3 days of `memory/logs/` — **drop any finding you already reported** so you don't re-nag a known-but-unfixed issue every run. (A finding is "the same" if it's the same check on the same skill.) 2. Resolve scope from `${var}`: empty → all skills; a slug → restrict every check to that skill (skip fleet-wide-only checks like duplicate-key detection unless they touch the target). 3. Every check below is a **pure local file read** — `grep`, `comm`, `node scripts/*.js`, `bash scripts/*.sh`. No network, no secrets, no GitHub API. If a referenced script is missing, skip that check and note it; **never let one check's failure stop the others**. ## Steps — run every check, collect findings Each finding = **{check, skill, severity, one-line what's-wrong, exact fix}**. Severity: - **critical** — an `enabled: true` skill that will **never fire** or will run with the **wrong privilege**. Live breakage. - **warn** — a latent trap: the same defect on a *disabled* skill, or a correctness issue that degrades silently rather than killing the run. ### 1 · Unquoted `schedule:` — the #1 silent killer (critical / warn) `scheduler.yml` matches schedules with the bash regex `schedule: *"([^"]+)"`. An unquoted value doesn't match, is read as empty, and the skill is **skipped every tick, forever** — the file is still valid YAML, so nothing else notices. ```bash grep -nE '^\s+[a-z0-9-]+:\s*\{[^}]*schedule:' aeon.yml | grep -vE 'schedule: *"' ``` Each printed line is an entry whose `schedule:` isn't double-quoted. **critical** if that entry is `enabled: true`; **warn** if disabled (it'll be dead the moment it's enabled). Fix: add the quotes — `schedule: "0 12 * * *"`. ### 2 · Duplicate skill keys — silent shadow (critical) A repeated skill name under the `skills:` map silently disables the first copy (last-wins YAML). ```bash node scripts/validate-config.js # authoritative — dup keys + checkout ordering grep -oE '^ [a-z0-9-]+:' aeon.yml | sort | uniq -d # names appearing more than once ``` Any name from `uniq -d` (or a dup-key error from the validator) is a finding. **critical** if either copy is enabled. Fix: remove the shadow copy. ### 3 · On disk but unconfigured — invisible skills (warn) A skill with a `SKILL.md` but no `aeon.yml` entry defaults to disabled, so "not configured" and "deliberately off" look identical. ```bash comm -23 <(ls skills/*/SKILL.md | cut -d/ -f2 | sort) \ <(grep -oE '^ [a-z0-9-]+:' aeon.yml | tr -d ' :' | sort) ``` Each printed name exists on disk but has no config entry. **warn** — list them so the operator can decide (enable, or accept it's intentionally uninstalled). ### 4 · Enabled skill with no `SKILL.md` — broken entry (critical) The inverse: an `aeon.yml` entry pointing at a skill dir that doesn't exist. For every `enabled: true` key, confirm `skills/<key>/SKILL.md` is present. Missing → **critical** (the run fails or no-ops). ### 5 · `requires:` entry the allowlist silently drops (warn) Both list forms parse — inline (`requires: [KEY?]`) and block (`- KEY` on its own line), top-level or nested under `metadata:`. What still bites is the *value*: `scripts/skill_requires.sh` injects only names matching `^[A-Z][A-Z0-9_]{2,}$` (a trailing `?` = "works better with" is allowed). An entry that fails the filter — lowercase, fewer than 3 chars, a leading digit, or stray punctuation — is silently dropped, so the skill declares a credential it never receives and fails or degrades with a confusing auth error. ```bash for f in skills/*/SKILL.md; do awk ' /^---$/{n++; next} n!=1{next} function chk(x){ sub(/\?$/,"",x); if(x!="" && x !~ /^[A-Z][A-Z0-9_]{2,}$/) print FILENAME": requires entry \""x"\" is dropped by the allowlist filter" } collecting { if ($0 ~ /^[ \t]*-[ \t]*/){ it=$0; sub(/^[ \t]*-[ \t]*/,"",it); sub(/[ \t]*#.*/,"",it); gsub(/[ \t]/,"",it); chk(it); next } collecting=0 } /^[^ \t]/{im=0} /^metadata:/{im=1} /^requires:/ || (im && /^[ \t]+requires:/){ if ($0 ~ /\[/){ line=$0; sub(/.*\[/,"",line); sub(/\].*/,"",line); k=split(line,a,","); for(i=1;i<=k;i++){gsub(/[ \t]/,"",a[i]); chk(a[i])} } else collecting=1 }' "$f"; done ``` Flag any entry that fails the filter. **warn**. Fix: use the exact env-var name (uppercase, `^[A-Z][A-Z0-9_]{2,}$`), with a trailing `?` only to mark it optional. ### 6 · `mode:` typo — silent write grant (critical) An unknown `mode:` value falls back to **`write`**, never to the safer tier. The only valid strings are `read-only` and `write`. ```bash grep -rnE '^[[:space:]]*mode:' skills/*/SKILL.md | grep -vE ':\s*(read-only|write)\s*$' ``` `mode:` is nested under `metadata:` (spec form), so the pattern allows leading indent. Any printed line is a typo (`readonly`, `read only`, `readOnly`, …) that silently grants full write / `gh` / `git`. **critical** — least-privilege is broken. Fix: the exact string `read-only`. (A skill with *no* `mode:` line is intentionally `write` — not a finding.) ### 7 · `.mcp.json` unresolved `${VAR}` — kills ALL MCP (warn) On the Claude harness a **single** `${VAR}` in `.mcp.json` that resolves to no secret disables **every** MCP server that run (`Skipping MCP this run.`), not just the broken one. List the referenced vars so the operator can confirm each is set: ```bash [ -f .mcp.json ] && grep -oE '\$\{[A-Z0-9_]+\}' .mcp.json | sort -u ``` Report the list as **warn** with the note: verify each with `./aeon secrets ls --set`; any one unset silently blacks out MCP for skills that rely on it. (You can't read secret values in read-only mode — surface the vars, don't try to resolve them.) ### 8 · Multi-line `aeon.yml` entry — override ignored (warn) Per-skill `model:` / `harness:` overrides are read by a single-line grep. An entry split across lines (its `{` and `}` on different lines) takes the **global default** instead — no error, and the run's `model=` line looks normal. ```bash grep -nE '^\s+[a-z0-9-]+:\s*\{[^}]*$' aeon.yml # opens { with no closing } on the same line ``` Each hit is a split entry → **warn**. Fix: collapse it to one inline `{ … }` line. ### 9 · Misleading `schedule:` / `cron:` in SKILL.md frontmatter (warn) Schedules live in `aeon.yml` only; `scheduler.yml` never reads `SKILL.md`. A `schedule:` / `cron:` line in frontmatter looks load-bearing but does nothing — a trap for anyone editing the skill. ```bash grep -rnE '^[[:space:]]*(schedule|cron):' skills/*/SKILL.md ``` Report as **warn** (informational): these lines are inert; the real schedule is the `aeon.yml` entry (the pattern allows leading indent, since spec-form frontmatter nests these under `metadata:`). ### 10 · Unquoted per-skill `harness:` / `model:` override (warn) Same quoting rule as `schedule:` — the override grep requires double quotes. An unquoted `harness: grok` or `model: …` is silently ignored and the skill keeps running the global default. ```bash grep -nE '\{[^}]*(harness|model):' aeon.yml | grep -vE '(harness|model): *"' ``` Each printed line has an unquoted override → **warn**. Fix: quote it (`harness: "grok"`). ### 11 · Category not one of the six — trips CI (warn) Every skill's `category:` must be one of `core evolution basics dev crypto productivity` or the catalog CI gate goes red. ```bash [ -x scripts/check-skill-categories.sh ] && bash scripts/check-skill-categories.sh ``` Report any offender as **warn**. ### 12 · Daily-log heading not `### <slug>` — health loop can't key it (warn) `CLAUDE.md` mandates each skill append its daily-log entry under a **`### <slug>`** heading — "the health loop parses this shape", and `skill-health` / `heartbeat` key skills by **slug**. A skill that logs under `## <Display Name>` (wrong level *and* wrong identifier) still runs, but its narrative log is harder for the health view to attribute and for the cross-skill dedup ("read the last 3 days of logs") to match — a silent degrade, never an error. ```bash for f in skills/*/SKILL.md; do s=$(basename "$(dirname "$f")"); grep -qE 'memory/logs/\$\{today\}' "$f" || continue # only log-writers grep -qE '###[[:space:]]+'"$s"'\b' "$f" && continue # compliant name=$(awk -F': *' '/^name:/{print $2; exit}' "$f" | sed 's/ *$//') hit=$(grep -oE '^##[[:space:]]+('"$s"'|'"${name:-$s}"')\b' "$f" | head -1) [ -n "$hit" ] && echo "$s logs under '$hit' — should be '### $s'" done ``` Each hit → **warn**. Fix: change the Log-section heading (the instruction line *and* the example block) to `### <slug>`, and demote any sub-sections inside the block to `####`. ## Report - **No findings → send nothing and exit.** A clean config is the common case; silence is correct and keeps this channel trustworthy. - **Findings → one consolidated `./notify`**, most-severe first. Write the body to a scratch file and send with `-f` (never a long argv): ```bash ./notify -f <file> \ --title "aeon-doctor: <N> config issue(s)" \ --severity <critical if any critical else warn> \ --mute-key "aeon-doctor" ``` Group by severity. For each finding give: the skill, one line on what breaks (and that it's **silent** — the operator won't see it in the Actions tab), and the exact one-command fix. If a `critical` exists, lead with it — an enabled skill that never fires is the whole reason this skill exists. - Do **not** open a PR or edit any file. Point mechanical fixes at `skill-repair` / the `./aeon` CLI; leave the fix to the operator. ## Constraints - Read-only by contract — inspect config, never mutate it. No `Write` / `Edit` / `git` / `gh`. - Every finding must cite the **exact** file + line and a **copy-pasteable** fix. A config finding with no fix is noise. - Don't invent problems: only report what a check actually matched. If every check is clean, say nothing. - Fully local — no network, no secrets, no GitHub API. Run-outcome health is `skill-health`'s job; live attention is `heartbeat`'s. Stay in your lane: the **static config**. ## Log Append to `memory/logs/${today}.md` under a `### aeon-doctor` heading (the health loop parses this shape), as bullets: checks run, findings by severity (or `clean`), and whether a notification was sent. End-states: `AEON_DOCTOR_CLEAN`, `AEON_DOCTOR_FINDINGS`, `AEON_DOCTOR_ERROR`.