vault-maintain

What this skill does

# 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
  preser