09 · Maintenance & Meta

← Docs home · Keeping the repo, its memory, and its agents healthy.

These are the cross-cutting procedures that aren’t about producing a page — they keep the project navigable and the agent system honest.

Project memory

Always-on memory lives in .agents/memory/MEMORY.md (the index, loaded at session start), pointing to active/ (hot tier, cap 20) and long-term/ (archive). Architecture: docs/plans/2026-05-09-agents-memory-system.md.

• memory-hygiene skill — prune active/: archive entries unused >60 days or over the cap-20 limit into long-term/<topic>/, then update the index. Trigger: “memory hygiene” / “prune memory”.
• /migrate-memory — consolidate the user-global type:project entries into the project-local store (idempotent). There’s a coexistence note in MEMORY.md until that runs.

Session reflection & handoff

• session-reflector — at session end, capture learnings to .agents/memory/pending/<date>-<slug>.md; or write/rotate a HANDOFF.md for resuming across context boundaries (archives to .agents/handoffs/).
• session-end-wrap — the orchestrator the user runs manually at the end of a substantive session: runs memory-hygiene → session-reflector → the evolver(s) in sequence. Never auto-invoked; a Stop-hook only nudges you to type /session-end-wrap. Failures isolate (one phase failing doesn’t block the next).

Agent / skill evolution

• /evolve (skill evolution) — modify-mode (the user-global evolver) + create-mode (project-local bookshelf-evolver). Reads session metrics, proposes surgical edits to agent/skill descriptions and triggers. Honors .agents/.evolve_snooze.
• /snooze N — disable the auto-fire /evolve hook for N hours.
• Meta-evolution (memory project_meta_evolution): evolver-meta is the frozen watchdog and the sole writer of calibration.md; a metrics-capture hook logs corrections to events.jsonl. The meta pass runs in /evolve Step 3.5 and in session-end-wrap phase 5.

Safety & validation

• safe-deletion-audit — run before deleting or moving any file, module, or skill. Checks recent commits, live call-sites (grep), and hardcoded path/hook references, then gives a safe/unsafe verdict. Cheap insurance against the “deleted a thing something still imports” class of break.
• skill-doctor — validate inter-skill .md references and .claude/skills/… paths embedded in hook scripts; flags links broken by renames/moves. Trigger: “skill doctor” / “validate skills”.

Knowledge graph (graphify)

A persistent graph of the whole repo lives in graphify-out/:

• Read graphify-out/GRAPH_REPORT.md first for god nodes, communities, and surprising connections before grepping for cross-file questions (“where is X used”, “trace this concept”).
• /graphify --update only when files in .agents/, docs/, or scripts/ look stale vs. the manifest, or when explicitly asked. Code-only changes re-index via AST (free); doc/markdown changes spawn LLM subagents (slow, costs tokens).
• Deeper: /graphify query "<q>", /graphify path "<A>" "<B>", /graphify explain "<concept>".

Current graph (2026-06-09): ~9,742 nodes / 20,553 edges / 179 communities. Top god nodes: js(), ProgressReporter, AIClient, Layout, FigureEntry.

Source-extraction healing

• openstax-audit-heal — when a re-extract drops figures / examples / exercises: audit the extracted MD+JSON against the SSR page slice, classify the gap, propose a fix to to_markdown.py, re-extract, and author any missing figures. Output: _workspace/openstax_audit/.

Commit conduct (project convention)

Commits use Conventional-Commit subjects (≤50 chars) + structured trailers (Constraint:, Rejected:, Directive:, Confidence:, Scope-risk:, Not-tested:) when they preserve decision context; trailers are skipped for trivial commits.

Scope discipline (memory feedback_scope_discipline): do only the verb asked. “commit” ≠ “commit and push.” Don’t chain actions the user didn’t request.

Skill index (by job)

Each skill’s SKILL.md under .claude/skills/<name>/ is its authoritative spec.