repo-maintenance

• --report-only → Generate report but make no changes
• --fix → Auto-fix all fixable issues
• Default: Report issues and prompt before fixing

2. Structural Audit

2.1 Domain Folder Completeness

Do not hard-code the expected domain set — it drifts the moment a domain is added, and a stale list defeats the entire purpose of this audit. Instead, build the two sets dynamically and diff them:

Set A — documented domains (the source of truth): parse the domain and subdomain tables in root CLAUDE.md (every | **Name** | \path/` | ... |` row under "## Domains" and each "### ... Subdomains" heading). Extract the backtick-quoted paths.

Set B — domains on disk: discover every folder that contains a context.md:

find . -name context.md -not -path './.git/*' -not -path './logs/*' | sed 's|/context.md$||;s|^\./||' | sort

(The root ./context.md maps to the repo root and is exempt from per-domain checks.)

For each path in Set A ∩ Set B (documented and present), check:

• Folder exists ✓ (it does, by construction)
• CLAUDE.md exists
• context.md exists (working memory — should be <100 lines)
• reference.md exists where appropriate (not required for every domain; flag only if context.md is bloated and no reference.md exists)

2.2 Drift Between Documentation and Disk

The diff of Set A and Set B is the highest-value output of this audit:

• In B but not A (undocumented folders) — a domain exists on disk but isn't in root CLAUDE.md. Flag each one. Action: add it to the appropriate root CLAUDE.md table (and to .claude/skills/index.md if it ships a skill), or remove the folder if orphaned.
• In A but not B (documented but missing) — root CLAUDE.md lists a domain that has no context.md on disk. Flag it. Action: create the missing files, or remove the stale row from CLAUDE.md.

Also confirm the skills referenced in the root CLAUDE.md "### Skills" table match the actual skill folders:

ls -d .claude/skills/*/ | xargs -n1 basename | sort

Flag any skill folder missing from the CLAUDE.md table or from .claude/skills/index.md, and any table/index entry with no corresponding folder.

3. Cross-Reference Audit

3.1 Multi-Domain Matrix Validation

Read root CLAUDE.md "Multi-Domain Conversations" table. For each mapping, verify:

• All referenced domains exist
• Paths are correct
• No domains missing from the matrix that should be connected

3.2 Domain CLAUDE.md Cross-References

For each domain CLAUDE.md, check the cross-reference section:

• All referenced paths exist
• Descriptions match what those domains actually contain
• No obvious missing connections

Common cross-reference patterns to verify:

3.3 Trigger Pattern Consistency

Verify trigger patterns in root CLAUDE.md match:

• Actual content in domain CLAUDE.md files
• Keywords that would reasonably activate that domain
• No duplicate triggers across domains (unless intentional)

4. Context Health Audit

4.1 Three-Tier Memory Health Check

For each domain, verify the three-tier memory system:

Working Memory — context.md (target: <100 lines)

• Count lines
• Flag if >100 lines (should offload stable facts to reference.md)
• Should contain only: current status, active decisions, recent session history
• Session History Cap (protocols/memory.md): flag session history exceeding ~5 entries / ~1 month → graduate older entries to {domain}/archive/sessions-{year}.md
• Archive After Decision: flag option-comparison working docs whose pick has been made → graduate to {domain}/archive/

Reference — reference.md (no hard limit)

• Check if reference.md exists where it should (domains with stable facts, inventories, specs)
• Verify it contains stable, rarely-changing facts (not session history or transient status)

Archive — archive/ (permanent history)

• Check if archive/ exists for domains with older session history
• Verify old session history is being moved here, not accumulating in context.md

4.2 Session History Freshness

Check last session history entry date:

• 6 months old → Flag as potentially stale

• Parse most recent ### YYYY-MM-DD or ## Month YYYY header

4.3 Tier Completeness Check

For each domain:

• Check if context.md exists (required — working memory)
• Check if reference.md exists where appropriate (stable facts, inventories, specs)
• Check if {domain}/archive/ exists for domains with session history older than 3 months
• Flag domains where context.md is bloated but reference.md doesn't exist (needs tier split)

4.4 Content Duplication & Tier Misplacement

Look for information that appears in multiple files or is in the wrong tier:

• Personal details (should be in root context.md only)
• Cross-cutting dates/events
• Stable facts sitting in context.md that belong in reference.md (e.g., inventories, specs, historical lists)
• Transient/session data sitting in reference.md that belongs in context.md or archive/
• Flag duplicates and misplacements for consolidation

5. Documentation Drift

5.1 Root CLAUDE.md Accuracy

Verify root CLAUDE.md matches actual repo state:

• Domain table lists all domains
• Trigger patterns are complete
• Multi-domain matrix is current
• Behavior protocols still apply

5.2 Decision Journal Health

Check decisions.md (root):

• Exists and is non-empty
• Active decisions have review dates where appropriate
• No decisions with passed review dates that haven't been addressed
• Decisions referenced in domain context.md files match journal entries
• No duplicate rationale between journal and context files

5.3 Skills Documentation

Check .claude/skills/ subdirectories:

• Each skill has SKILL.md
• Skills are referenced appropriately (if needed in root)

6. Generate Report

Output a structured report:

# Repo Maintenance Report
**Date**: YYYY-MM-DD
**Status**: [Healthy | Needs Attention | Issues Found]

## Summary
- Domains audited: X
- Issues found: Y
- Auto-fixable: Z

## Structural Issues
[List missing files, undocumented folders]

## Cross-Reference Issues
[List broken or missing cross-references]

## Context Health (Three-Tier Memory)
[List bloated context.md files, missing reference.md, tier misplacements, stale data]

## Recommendations
[Prioritized action items]

7. Apply Fixes (if --fix or user confirms)

Auto-Fixable Issues:

• Add missing folders to root CLAUDE.md domain tables
• Add missing trigger patterns
• Update multi-domain matrix with missing connections
• Create placeholder CLAUDE.md for undocumented subdomains

Manual Fixes Required:

• Splitting bloated context.md into context.md + reference.md (needs content review)
• Archiving old session history to archive/ (needs content review)
• Writing substantial CLAUDE.md content
• Resolving content duplication and tier misplacements
• Major restructuring

8. Update Maintenance Log

After running, add entry to projects/ai-assistant/context.md:

### YYYY-MM-DD
- Ran repo maintenance audit
- Issues found: [count]
- Fixed: [list]
- Pending: [list]