Backed by: state/bin/brain/growth.ts (reads state/log/{evals,parity,sync-events,pid-trends,breakage-report}.ndjson + state/skills/*AGENTS.md + ~/.claude/projects/*/memory/*.md)

brain-growth

Answers the "how does it show that to us" question. Once per day (cron at 04:00 local) the script computes a snapshot of every metric that reflects the system getting better and appends one row to state/log/growth.ndjson. With --deltas it renders a today vs. 7d-ago vs. 30d-ago table so regressions are visible. Pod 24's Brain view consumes this log directly.

Steps

1. Scope - read the logs and skill directories. No writes, no API calls.
2. Compute - 17 metrics:

• skills_total / skills_graduated / skills_prose from frontmatter
• loader_pitfalls_total from ## Known Pitfalls blocks in every *AGENTS.md
• evals_total, evals_last_24h, rolling_mean_100, rolling_mean_1000
• open_breakage_p0, open_breakage_p1 (status: open)
• parity_means per runtime (claude, codex, gemini, openclaw) from last 24h
• sync_drift_count_7d (sync-events rows with mode=integrity-fail | error)
• recurring_areas_7d from pid-trends
• memory_files_total across ~/.claude/projects/*/memory/*.md

1. Persist - append one row per day to state/log/growth.ndjson.

Idempotent: re-running the same day is a no-op unless --force.

1. Deltas - with --deltas, print a table: today vs the nearest snapshot

on or before (now − 7d) vs the nearest snapshot on or before (now − 30d). Icons: UP = improved, DN = regressed, - = unchanged, blank = no baseline.

1. Log + eval - append to chain.ndjson, score to evals.ndjson.

Eval

Actor: state/bin/brain/growth.ts - the metric computer. Auditor: shape-gate in the same script - different concern. The computer produces numbers; the auditor asserts the row shape (core counts are non-negative integers, rolling_mean_100 ∈ [0,1] ∪ null). The auditor never judges whether the numbers are "good" - that's the job of Pod 24's Brain view comparing deltas over time.

score:
  1.0 if every core count is a non-negative integer AND rolling_mean_100
       is null or in [0,1];
  0.0 otherwise.

Manual Brain-view review is orthogonal: Robert reads the deltas table and decides whether the system is actually learning. That is the point of this skill - it is the surface where self-improvement is visible.

Gotchas

• Missing logs (fresh machine, empty parity.ndjson) must degrade to null,

not crash. All reads go through parseJsonLines which tolerates absent files.

• The same-day row is overwritten with --force, appended fresh otherwise.

Without --force a second invocation on the same day returns { wrote: false, reason: "already-logged-today" } - not an error.

• loader_pitfalls_total counts bullet lines inside ## Known Pitfalls

blocks only. Other bulleted lists in the sidecar don't count.

• Parity means prefer the last 24h of rows; if fewer than 4 rows landed in

24h (e.g. parity-test.ts hasn't run today), it falls back to the most recent 20 rows so the number stays meaningful.

Graduation

Already graduated - script at state/bin/brain/growth.ts. Future work: deterministic change-detection for the "What got better since last snapshot" section so the wiki page can be regenerated automatically each day instead of being a human-edited artifact per snapshot day.

Rubric

criteria:
  - name: metrics_computed_correctly
    kind: deterministic
    check: "The `evals.ndjson` for the skill confirms all core counts are non-negative integers and rolling_mean_100 is null or within [0,1]."
  - name: growth_log_appended
    kind: deterministic
    check: "A new entry for the current day is appended to `state/log/growth.ndjson` when the skill runs after 04:00 local time, or `wrote: false` and `reason: \"already-logged-today\"` is returned on subsequent runs for the same day without `--force`."
  - name: deltas_table_present
    kind: judge
    check: "When `--deltas` is provided, a well-formatted table comparing today's snapshot to 7-day-ago and 30-day-ago snapshots is displayed with appropriate Up/Down/Unchanged indicators."
  - name: no_crashes_on_missing_logs
    kind: deterministic
    check: "The script completes execution without crashing when expected log files (e.g., `parity.ndjson`) are absent, defaulting to nulls as appropriate for metrics."

brain-growth - loader

Per-turn rules for the brain-growth skill. Full reference: state/skills/brain-growth/SKILL.md. Do not skip these.

Critical Rules

• Never crash on missing logs - parity.ndjson, sync-events.ndjson, pid-trends.ndjson all degrade to null / 0. Defensive file reads are the whole point on a fresh machine.
• The snapshot row is idempotent per day. Re-running without --force returns {wrote:false,reason:"already-logged-today"} and that IS the success path, not a failure.
• rolling_mean_100 must be null or ∈ [0,1] - shape-gate eval fires 0.0 otherwise.
• loader_pitfalls_total only counts bullet lines under ## Known Pitfalls headings in */AGENTS.md. Do not rewrite the script to count every - line in the sidecar - that double-counts Critical Rules and Commands.
• Never report as "growing" / "learning" based on a single day's data - at least one baseline snapshot (7d or 30d earlier) must be present before deltas are meaningful.

Commands

| ui dashboard | state/skills/brain-growth/resources/ui.openui | |invoke: npx tsx state/bin/brain/growth.ts (snapshot + log, idempotent per day) |deltas: npx tsx state/bin/brain/growth.ts --deltas |overwrite: npx tsx state/bin/brain/growth.ts --force |output log: state/log/growth.ndjson (one row per day) |eval log: state/log/evals.ndjson (skill: "brain-growth")

OpenUI Resource

• Skill-owned OpenUI Lang resource: state/skills/brain-growth/resources/ui.openui. Read it before rendering or editing this skill's generated component surface.
• Treat this resource as a first-class artifact of the skill, not a generic chat response. Improve it when the skill's user-facing output needs to become richer.
• System resources compose OpenUI primitives and inherit SnappyChat tokens. Use ui_contract: branded in SKILL.md only for deliberate platform or client visuals.

Known Pitfalls

• Running on a fresh machine with no evals / parity data yields rolling_mean_100: null and parity_means.*: null - this is correct, not a bug
• Cron at 04:00 local is intentional - it captures the state at quiet-hours boundary so deltas line up day-to-day
• Memory files are counted across every project under ~/.claude/projects/*/memory/, not just this repo's own memory

Self-Test

An agent reading this should correctly:

1. [ ] Treat "already-logged-today" as success, not an error?
2. [ ] Degrade missing logs to null/0 instead of crashing?
3. [ ] Only count pitfalls inside ## Known Pitfalls blocks?
4. [ ] Require a baseline snapshot before claiming the system is getting better?

Self-report

If this loader fell short, append a line:

echo "[$(date -u +%FT%TZ)] brain-growth: <what was missing>" >> state/log/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)] brain-growth: <what was missing or fixed> [FIXED|LOGGED]" >> 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.

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.