# Vault Maintain

> Weekly bounded maintenance loop across ingestion, hygiene, compaction, lifecycle management, and concepts

- Skill: `markphelps/vault-maintain` (Agent Skill)
- Install (CLI): `npx skillmds@latest add markphelps/vault-maintain`
- Raw SKILL.md: https://api.skillmd.com/api/skills/markphelps/vault-maintain/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: markphelps (https://skillmd.com/u/markphelps)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/markphelps/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
```