Hyalo Tidy — Knowledgebase Consolidation for pi

You are performing a tidy — a reflective pass over a knowledgebase. Your job is to detect issues, fix what you can, and report what needs human attention. Think of this as a librarian doing a periodic shelf-read: checking that everything is filed correctly, cross-references work, and nothing is gathering dust in the wrong place.

For pi sessions, use --format text for agent-facing Hyalo output. The optional helper uses JSON internally for reliable machine processing.

This process has 5 phases. Take your time — a thorough tidy is worth more than a fast one. A few minutes is fine.

Before you start

Locate the hyalo binary:

which hyalo 2>/dev/null || echo "target/release/hyalo"

Confirm .hyalo.toml exists in the project root to determine the KB directory. If it doesn't exist, ask the user which directory to consolidate.

Optional Jev assistance and audit scope

Only when the user explicitly requests Jev, read references/jev.md and follow that branch before loading full document bodies. A key or repository setting never enables it. Ordinary tidy needs no JavaScript runtime or network. Jev failure leaves the usual local workflow available.

An audit or health question is read-only: omit --index throughout, skip index creation/removal, and return Phase 4 repairs as proposals only. Jev-assisted runs also skip indexes and follow the reference's scope and review rules. A request to tidy or repair authorizes relevant edits, preserving unrelated content and metadata.

Command examples below omit --index. Add it only for a repair run without Jev after creating its snapshot. Audits and every Jev-assisted run use live reads.

Phase 1 — Orient and snapshot

Get the lay of the land. Create an index only for a repair run without Jev; for audits and Jev-assisted runs, omit the index step and all --index flags.

# 1. High-level overview (baseline for the final health dashboard)
hyalo summary --format text

# 2. Repair runs without Jev only: create snapshot index
hyalo create-index --format text

# 3. Inspect existing saved views without rewriting configuration
hyalo views list --format text

# Use a matching saved view when present; otherwise keep diagnostics inline
hyalo find --property status=in-progress --fields tasks --format text
hyalo find --property '!status' --format text
hyalo find --property '!type' --format text
hyalo find --orphan --fields backlinks --format text
hyalo find --property status=completed --task todo --fields tasks --format text

Do not create or replace saved views during a tidy unless the user explicitly asks; the diagnostic phase must leave existing definitions byte-for-byte unchanged.

The snapshot index captures every file's metadata in a binary file (.hyalo-index). For repair runs without Jev, add --index to Phase 2 and Phase 3 queries to avoid repeated disk scans. Otherwise keep it omitted. For complex reshaping, combine Hyalo filtering with --jq.

Also grab the tag vocabulary for inconsistency detection:

hyalo tags summary --format text

Phase 2 — Gather recent signal

Before looking for issues, understand what happened recently. This context is what makes the tidy valuable — it tells you what should have changed in the KB, so you can spot what didn't.

Git history

# What branches were merged recently? What iteration branches shipped?
git log --oneline --merges --since="4 weeks ago"

# What areas of code changed? (helps identify which features shipped)
git log --oneline --since="4 weeks ago" -- "*.rs" | head -30

Extract non-completed iterations and their branches from the index:

hyalo find --property type=iteration --jq '.results | map(select(.properties.status != "completed" and .properties.status != "superseded" and .properties.status != "wont-do")) | map({file, branch: .properties.branch, status: .properties.status})'

For each non-completed iteration that has a branch, check if that branch was merged:

git log --oneline --merges --all | grep "<branch-name>"

Claude's auto-memory

Check what was recently worked on from Claude's perspective:

MEMORY_FILE=$(find ~/.claude/projects/ -path "*/memory/MEMORY.md" -print -quit 2>/dev/null)
if [ -n "$MEMORY_FILE" ]; then
  MEMORY_DIR=$(dirname "$MEMORY_FILE")
fi

If found, query it with hyalo (memory files are outside the vault, so no --index here):

hyalo --dir "$MEMORY_DIR" find --property type=project --format text
hyalo --dir "$MEMORY_DIR" find --property type=feedback --format text

Look for:

• Project memories mentioning iterations/features that shipped — cross-reference with KB
• Stale project memories that reference outdated plans (note for the report, but don't modify memory files — that's Claude's own territory)

Recent KB changes

git log --oneline --since="4 weeks ago" -- "hyalo-knowledgebase/" | head -20
git log --diff-filter=A --name-only --since="4 weeks ago" -- "hyalo-knowledgebase/"

Phase 3 — Detect structural issues

Queries below use live reads and inline selectors, so they work without saved views. Only repair runs without Jev may add --index.

Schema & lint

Check if type schemas are defined, then run lint in strict mode. hyalo lint covers both frontmatter schema and the markdown body (stock mdbook-lint rules + HYALO native rules for things like bare [] checkboxes and status: completed with open tasks). --strict promotes the "no type property" and "undeclared property in frontmatter" warnings and HYALO003/004/006/007/008 (dates, datetimes, broken links, non-scalar titles, broken anchors) to errors so a tidy pass fails fast on schema and link drift:

hyalo types list --format text
hyalo lint --strict --format text

If hyalo types list returns zero types but files have a type property, propose creating type schemas. Use hyalo properties summary to discover common property values, then suggest hyalo types set <name> --required ... commands for the user's most common document types. Don't create them unilaterally — report the suggestion in Phase 5.

Note the lint summary's per-rule counts. If one rule dominates the noise (e.g. MD013 line-length on prose-heavy KBs), that's a signal the rule may not fit the KB — flag it for Phase 5 as a candidate to disable via hyalo lint-rules. Track fixable counts for Phase 4.

Lint also validates [views.*] in .hyalo.toml. A view whose only narrowing key is fields (display columns, not a filter) is surfaced as a warning — suggest adding an explicit filter like orphan = true, dead_end = true, or tag = [...] when you see one in Phase 5.

Broken links

# Dry-run shows broken links with proposed fixes and confidence scores
hyalo links fix --format text

This categorizes links as fixable (fuzzy match found) vs unfixable (no match). Note the counts for the health dashboard. Actual fixes happen in Phase 4.

Orphan files

hyalo find --orphan --fields backlinks --jq '.results | map(select(.backlinks | length == 0)) | map(.file)'

Not all orphans are problems. Expect these to be legitimately orphaned:

• Top-level files (SEED.md, project-pitch.md, decision-log.md)
• Research documents (standalone reports)
• Older completed items in done/ directories

Focus on actionable orphans: active/planned items that should be cross-referenced.

Dead-end files

hyalo find --dead-end --jq '.results | map(.file)'

Dead-end files have inbound links but no outbound links — often stubs or leaf nodes that could benefit from cross-references. Not always a problem, but worth reviewing.

Stale statuses

# In-progress items — should any be completed?
hyalo find --property status=in-progress --fields properties --jq '.results | map({file, date: .properties.date, branch: .properties.branch})'

# Planned items where all tasks are done
hyalo find --property status=planned --fields tasks --jq '.results | map(select((.tasks | length > 0) and ([.tasks[] | select(.status != "x")] | length) == 0)) | map(.file)'

# In-progress items sorted by date (oldest first — possibly stale)
hyalo find --property status=in-progress --fields properties --jq '.results | map(select(.properties.date != null)) | sort_by(.properties.date) | map({file, date: .properties.date})'

Cross-reference with git merges from Phase 2. If the branch was merged, update status.

Stale backlog items

hyalo find --property status=planned --property type=backlog --jq '.results | map({file, title})'

Compare each planned backlog item against merged iterations and recent git history. If the feature clearly shipped (in a different iteration or under a different name), flag it.

Missing metadata

hyalo find --property '!status' --jq '.results | map(.file)'
hyalo find --property '!type' --jq '.results | map(.file)'

Tag inconsistencies

Review the hyalo tags summary output from Phase 1. Look for near-duplicates: singular/plural (filter/filters), hyphenation variants (bugfix/bug-fix), abbreviations (perf/performance). The canonical form should be the one used by more files.

Task completion vs status mismatch

The HYALO002 rule from the lint pass already flags status: completed files with open tasks (fires only when [schema.types.*].properties.status is declared as an enum containing "completed"). If you want a per-file breakdown with open/total counts, use this inline query:

hyalo find --property status=completed --task todo --fields tasks --jq '.results | map({file, open: ([.tasks[] | select(.status != "x")] | length), total: (.tasks | length)})'

If many completed items have unchecked tasks, this is a workflow pattern — note it once in the report rather than listing every file.

Phase 4 — Consolidate

Apply these changes only within an authorized repair request. For an audit, report the proposed changes. Be conservative — prefer fixing metadata over deleting files. For each change, note what you did and why.

For repair runs without Jev, add --index to mutations to keep the snapshot current. Jev-assisted repairs omit it from every command. Audits propose changes without applying them; neither audits nor Jev runs create or remove indexes.

Fix lint violations

If lint reported fixable violations in Phase 3, auto-fix them. --fix covers both passes — frontmatter (defaults, typos, dates, types) and body (e.g. HYALO001 bare brackets, trailing whitespace). Always preview with --dry-run first:

hyalo lint --fix --dry-run --format text
hyalo lint --fix --format text

If you only want to fix specific rules (e.g. body fixes only, leaving frontmatter alone), use --fix-rule or --rule-prefix HYALO — see hyalo lint --help.

Unfixable violations (missing required properties, open tasks under HYALO002) are reported in Phase 5 for human attention.

Fix broken links

Use hyalo links fix to auto-repair broken links. It uses fuzzy matching to find the correct target (handles moves to done/, case changes, extension mismatches, etc.).

# Preview what will be fixed
hyalo links fix --format text

# Apply fixes
hyalo links fix --apply --format text

Review the dry-run output first. For any links it can't resolve (reported as unfixable), leave them and report them in Phase 5.

Update stale statuses

If an iteration's branch was merged:

hyalo set <path> --property status=completed --format text

If a backlog item's feature clearly shipped:

hyalo set <path> --property status=completed --format text

Only update when the evidence is clear. When uncertain, flag it in the report.

Archive completed items

If completed items are in a top-level directory and a done/ subfolder exists:

hyalo mv <old-path> --to <done-subdir/filename> --dry-run --format text

Review the dry-run output. If correct, execute without --dry-run.

Normalize tags

hyalo tags rename --from <variant> --to <canonical> --format text

Add missing cross-references

If a backlog item was implemented by an iteration but neither links to the other, add a [[wikilink]]. Only where the relationship is clear and useful.

Phase 5 — Report

Summarize everything. Structure as:

Changes made

One line per change with reasoning:

- Set status=completed on iteration-43.md (branch iter-43/data-quality merged in abc1234)
- Moved iteration-46.md to iterations/done/ (completed, all tasks verified)
- Renamed tag: bugfix → bug-fix (2 files, matching existing convention)
- Fixed 5 broken links in research/dogfooding-v0.4.1-consolidated.md (same-dir targets)

Issues requiring human attention

Things you detected but couldn't (or shouldn't) fix unilaterally. Keep it concise — one line per issue with enough context to act on.

If a single lint rule produced an outsized share of the noise (or if a rule fired only on legitimate exceptions), suggest tuning it via hyalo lint-rules rather than silently leaving the warnings in place.

KB health dashboard

Re-run hyalo summary --format text (fresh scan after mutations — no --index) and compare with Phase 1 baseline. Report the delta: statuses changed, links fixed, tags normalized, files moved.

Ground rules

• Conservative by default: when in doubt, report rather than change.
• Never delete files or body content: update frontmatter, fix links, move files, suggest changes — but the user decides what to throw away.
• Explain every change: include the evidence (commit hash, task counts, etc.).
• Don't modify Claude's memory files: report stale memories but don't edit them.
• Use hyalo for mutations: hyalo set/remove for frontmatter, hyalo tags rename for tags, hyalo mv for moves. Fall back to Edit only for body content (fixing wikilink text in prose, adding cross-reference lines).
• Batch similar findings: if 15 completed items have unchecked tasks, say that once with the count. The report should be scannable in 30 seconds.
• Minimize disk scans in repair runs without Jev: use --index for queries and mutations. Mutations automatically patch the index in-place — no need to drop and recreate. Only drop the index at the very end when the session is complete.