ifcommand -v ao &>/dev/null; then
ao metrics flywheel status 2>/dev/null || echo"ao metrics flywheel status unavailable"
ao status 2>/dev/null || echo"ao status unavailable"
ao maturity --scan 2>/dev/null || echo"ao maturity unavailable"
ao anti-patterns 2>/dev/null || echo"ao anti-patterns unavailable"
ao badge 2>/dev/null || echo"ao badge unavailable"# Knowledge maintenance
ao dedup --merge 2>/dev/null || true
ao contradict 2>/dev/null || true
ao constraint review 2>/dev/null || true
ao curate status 2>/dev/null || true
ao metrics health 2>/dev/null || true
ao metrics cite-report --days 30 2>/dev/null || true# Active pruning: archive stale, evict low-utility, and curate noisy uncited learnings
ao maturity --expire --archive 2>/dev/null || true
ao maturity --evict --archive 2>/dev/null || true
ao maturity --curate --archive 2>/dev/null || true# Retrieval quality: use the representative live corpus when it existsif [ -d cli/cmd/ao/testdata/retrieval-bench-live ]; then
ao retrieval-bench --live --corpus cli/cmd/ao/testdata/retrieval-bench-live --json 2>/dev/null || truefielseecho"ao CLI not available — using file-based metrics"echo"Pool depths:"for pool in learnings patterns forge knowledge research retros; doecho" $pool: $(ls .agents/${pool}/*.md 2>/dev/null | wc -l | tr -d ' ')"doneecho" global patterns: $(ls ~/.claude/patterns/*.md 2>/dev/null | wc -l | tr -d ' ')"echo"See references/promotion-tiers.md for tier definitions"fi
Step 4.5: Process Metrics (from skill telemetry)
If .agents/ao/skill-telemetry.jsonl exists, use jq to extract: invocations by skill, average cycle time per skill, gate failure rates. Include in health report (Step 6) under ## Process Metrics.
Step 5: Validate Artifact Consistency
Cross-reference validation: scan knowledge artifacts for broken internal references.
Use scripts/artifact-consistency.sh (method documented in references/artifact-consistency.md).
Default allowlist lives at references/artifact-consistency-allowlist.txt; use --no-allowlist for a full raw audit.
Read references/cache-eviction.md for the full eviction pipeline (passive tracking → confidence decay → maturity scan → archive).
Hub Budget & Phase 4 Hardening
Phase 4 (soc-ytpq) governance for ~/.agents/learnings/ — all advisory, none block by default. Full details in references/hub-budget.md.
Size budget: target ≤ 250 MB / ≤ 5,000 files. Restore via ao maturity --evict --target-size=250M (lowest-utility-first; respects lifecycle.IsEvictionEligible so canonical / high-confidence files are protected).
Volume gate:ao harvest WARNs when promotions exceed --max-promotions=N (default 500; AO_MAX_PROMOTIONS=N env as fallback; ≤0 disables). WARN-only — the 2,638-promotion soc-ujls drain proves a hard gate would falsely block legitimate runs.
Provenance: every promoted file carries source_rig: in its frontmatter (empty writers serialize as source_rig: unknown). Both harvest.Promote and pool.(*Pool).Promote content-dedup against the same hub via ~/.agents/pool/promoted-index.jsonl.
Re-bloat triage: check SkipGlobalHub defaults to true (the agentops-b3v / soc-ujls fix), then grep -h '^source_rig:' ~/.agents/learnings/*.md | sort | uniq -c | sort -rn to identify the regressed writer. Use --target-size, never raw rm.
Key Rules
Monitor regularly - flywheel needs attention; address bottlenecks early
Feed the flywheel - run /retro and /post-mortem
Prune stale knowledge - archive old artifacts
Examples
User says:/flywheel — Counts pool depths, checks recent activity, validates artifact consistency, writes health report to .agents/flywheel-status.md.
Hook trigger: After /post-mortem — Compares current vs historical metrics, flags velocity drops and friction points.
Troubleshooting
Problem
Cause
Solution
All pool counts zero
.agents/ directory missing or empty
Run /post-mortem or /retro to seed knowledge pools
Velocity always zero
No recent extractions (last 7 days)
Run /retro or /post-mortem to extract and index learnings
"ao CLI not available"
ao command not installed or not in PATH
Install ao CLI or use manual pool counting fallback
Stale artifacts >50%
Long time since last session or inactive repo
Run /provenance --stale to audit and archive old artifacts