vault-maintain

name	vault-maintain
description	Weekly bounded maintenance loop across ingestion, hygiene, compaction, lifecycle management, and concepts

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

# 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