vault-maintain

# Vault Maintain Run a comprehensive weekly maintenance sweep across the active vault surface. This is the unified entry point for periodic vault care, coordinating ingestion, hygiene, semantic compaction, project lifecycle management, and concept promotion into a single bounded workflow. Portent reference: `../references/portent-knowledge-base-spec.md`. ## Recency Priority Work the active surface newest-first, ranked by each object's `updated` frontmatter date (fall back to file modification time when `updated` is absent). Concentrate scrutiny on the freshest material — recently-touched objects are where active thinking lives and where new mismatches, overlaps, and gaps appear. Long-untouched objects are assumed settled and rank lower, but are never excluded: they remain valid link targets, merge destinations, and canonical homes, and still get a structural check (broken links, orphaning). Every sub-audit below inherits this newest-first ordering, and the weekly summary leads with findings on recently-updated objects. ## Command ``` vault-maintain [--mode report|apply-safe|apply] ``` ## Parameters - `--mode report|apply-safe|apply` (default: `report`) - `report`: audit and preview all findings (read-only) - `apply-safe`: apply high-confidence, low-risk updates only - `apply`: include medium-confidence actions when evidence is clear ## Weekly Sequence Run these steps in order to produce a complete weekly maintenance report: ### 1. Ingest Audit Run `vault-ingest --mode report` to: - Scan `raw/sources/` for unprocessed captures - Preview source categories and destination paths - Show high-confidence source moves ready to apply - Identify ambiguous captures needing user direction ### 2. Portent Object Audit Run a report-mode pass over active objects to find: - missing or invalid `type` - missing or invalid `status` - organized objects without useful relationships - captured objects that should be organized, deleted, or left in inbox - archived objects still shown in active views - Operations without a Responsibility or Project parent - Projects without a clear Responsibility or Topic relationship when one is obvious ### 3. Hygiene Audit Run `vault-lint --mode report` to: - Detect contradictions across related notes - Find orphan pages and stale content - Find connection candidates for knowledge graph growth - Find duplicate or overlapping notes, ideas, and projects - Identify missing concept pages - Flag broken or ambiguous wikilinks - Surface promotion candidates from drift reports ### 4. Lifecycle Audit Run `vault-tracker --mode report` to: - Audit Portent metadata vs filesystem and active navigation state - Detect mismatches and stale navigation entries - Detect duplicate ideas/projects that should be merged - Propose lifecycle transitions - Identify active Projects missing from active navigation ### 5. Idea Pressure Audit Run an aggressive report-mode review of `ideas/fleeting/` and `ideas/incubating/`: - List every fleeting idea and ask whether it should be promoted, rejected, compacted into an existing idea/concept, or deleted. - List every incubating idea with its age, last update, next action, and linked research. - Flag incubating files that are not actually ideas, such as tech research, source records, orphan research folders, or implementation specs. - Flag missing idea entry points, such as research folders without a root idea note or index links pointing to absent files. - Flag idea folders whose research has already been synthesized and can be compacted or deleted from the active idea surface. - Prompt the user with concrete decisions: - `keep incubating` - `promote to project` - `move to notes` - `compact into <canonical>` - `reject` - `delete absorbed curated files` Default recommendation should be opinionated. Do not leave stale ideas as "maybe" when the evidence supports a clear cleanup action. ### 6. Compaction Audit Run `vault-compact --mode report` to: - Review merge candidates found by `vault-lint` - Detect semantic overlap where multiple passages do the same job - Propose canonical destinations for duplicated claims, project materials, and shipped-project launch artifacts - Identify curated files that could be deleted after absorption - Distinguish collapse/route/link-only actions from true file merges - Include idea-pressure candidates from step 5 as compact/reject/delete inputs ### 7. Concept Audit Run `vault-concepts --mode report` to: - Scan for recurring themes across curated areas - Detect duplicate or overlapping concept pages - Detect candidate concept pages - Propose updates to existing concepts - Surface new concept creation candidates ### 8. Weekly Summary Production Compile findings into a weekly summary including: - Pending ingestions (count, source types, routing decisions) - Source routing proposals (category, destination, confidence) - Portent object audit findings (type/status validity, relationship gaps, captured/archived drift) - Hygiene issues by severity (contradictions, orphans, stale) - Connection candidates (source, target, confidence, relationship) - Merge candidates (target, sources, confidence, required link rewrites) - Idea queue decisions needed (keep/promote/move/compact/reject/delete) - Compact candidates (canonical destination, absorbed files, preserved unique content, delete eligibility) - Synthesis archive checks (summaries link to complete sources in `raw/processed/YYYY-MM-DD/`) - External tag checks (clipped notes tagged `external`, owned notes not tagged `external`) - Lifecycle transitions proposed (state changes, promotions) - Concept candidates (updates, creations deferred) - Unresolved decisions requiring user input ### 9. Maintenance Record Append the maintenance entry to `log.md` manually when the vault uses one: - Operation: `vault-maintain` - Summary: date range and completion status - Key actions: counts of items processed in each category - Touched files: moved sources plus metadata, link, index, or concept updates ## Mode Behavior ### `report` (Default) - Run all audits in read-only mode - Compile findings without any modifications - Present weekly summary and proposals - List unresolved decisions ### `apply-safe` Apply only high-confidence, low-risk changes: - **Link normalization**: Fix broken or ambiguous wikilinks - **Graph links**: Add high-confidence contextual wikilinks discovered by `vault-lint` - **Lifecycle updates**: Unambiguous Portent metadata and index/navigation changes - **Idea queue cleanup prep**: Fix broken idea links, add canonical links, and mark obvious decision prompts without moving or deleting idea content - **Merge prep**: Add backlinks or aliases for high-confidence merge candidates without moving content - **Compact prep**: Add canonical links or aliases for high-confidence compact candidates without deleting or rewriting substantial content - **Synthesis link repair**: Add missing links from summaries to archived source records when the archive path is unambiguous - **Maintenance record**: Append a concise manual entry to `log.md` if present Excluded from `apply-safe`: - Source moves requiring link rewrites - Content merges - Idea rejection/deletion - New concept page creation - Ingestion pipeline execution (stays in `report`) ### `apply` Additionally allow medium-confidence actions: - **Source moves**: Deterministic file moves with automatic link rewrites - **Content merges**: High-confidence duplicate notes, ideas, projects, or concepts through `vault-compact` when provenance, unique content, and links can be preserved - **Absorbed curated file deletion**: Delete non-raw files after `vault-compact` merges their unique content into a canonical destination and rewrites inbound links - **Idea queue pruning**: Reject, move, compact, or delete fleeting/incubating idea files when the user confirms the specific action and unique content is preserved where needed - **Synthesis archive repair**: Move complete external source records into `raw/processed/YYYY-MM-DD/` when a summary exists without an immutable source archive - **Concept creation**: New concept pages when promotion thresholds are met (theme appears in 3+ unrelated notes, evidence is concrete and linkable) ## Safety - **Never delete raw content** — `raw/` is immutable - **Curated deletion only through compaction**: `vault-compact` may delete curated files after absorption into a canonical destination; list every deleted file and its canonical replacement - **Idea deletion requires explicit decision**: deleting a fleeting/incubating idea is allowed only after the user chooses delete or confirms that the idea was absorbed into another canonical note/project - **Do not archive ambiguous live projects** without explicit instruction - **Keep changes reviewable**: List all touched files with relative paths - **Preserve hand-written content**: Favor additive updates over rewrites - **Merge conservatively**: When two items are related but distinct, link them instead of merging - **Graph links need evidence**: Add only links with a clear relationship and natural context - **Synthesis requires sources**: Summaries and briefs must cite complete archived source records - **Exclude `archive/`** from active maintenance unless explicitly scoped - **Never mutate existing** `raw/processed/*` files; additive archived source copies are allowed for synthesis archive repair - **Confirm before execution** unless running in `--mode report` ## Compose Existing Skills This skill orchestrates the following specialized skills: | Step | Skill | Purpose | | ---- | ---------------- | --------------------------------- | | 1 | `vault-ingest` | Source classification and routing | | 2 | `vault-lint` | Portent object and hygiene audit | | 3 | `vault-tracker` | PORT lifecycle management | | 4 | `vault-compact` | Semantic merge and absorption | | 5 | `vault-concepts` | Topic promotion and creation | ## Output Return: - **Applied changes**: What was modified (by mode) - **Deferred/proposed changes**: Pending items for future cycles - **Merge report**: Merges applied/proposed, canonical targets, retained provenance - **Compact report**: Collapses applied/proposed, absorbed files, deleted curated files, and canonical replacements - **Idea pressure report**: Fleeting/incubating decisions requested, stale ideas, broken idea entry points, non-idea files in `ideas/`, and recommended action - **Portent object report**: Missing/invalid types and statuses, relationship gaps, captured-object decisions, and archived visibility drift - **Graph report**: Links added/proposed and relationship evidence - **Confidence notes**: High/medium/low confidence per category - **Unresolved decisions**: Items requiring explicit user input - **Touched files**: List of all modified files with relative paths - **Weekly summary**: Compact overview of vault state and progress ## Example Usage ```bash # Preview weekly maintenance (read-only) vault-maintain --mode report # Apply safe updates only vault-maintain --mode apply-safe # Full maintenance with source moves and concept creation vault-maintain --mode apply ```