vault-tracker

What this skill does

# Vault Tracker

Unified PORT object lifecycle management: track Projects, Operations,
Responsibilities, and externally tracked Task references; detect mismatches
between filesystem location, Portent metadata, and active navigation; propose
transitions; and coordinate archival.

Manage lifecycle and navigation for PORT objects: `Project`, `Operation`,
`Responsibility`, and externally tracked `Task` references.

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).

Surface recently-touched objects' metadata and navigation mismatches first when
reporting and proposing transitions.

## Command

```
vault-tracker [--mode report|apply-safe|apply] [--project NAME] [transition]
```

## Parameters

- `--mode report|apply-safe|apply` (default: `report`)
- `--project NAME` optional project name/path to scope operation
- `transition` optional explicit transition intent (e.g., `mark shipped`,
  `archive now`)

## Lifecycle States

- `active` — currently executing project
- `exploring` — early investigation, not fully committed
- `paused` — temporarily on hold
- `shipped` — completed/delivered
- `archived` — moved to `archive/`
- `fleeting` — rough idea fragment (in `ideas/fleeting/`)
- `incubating` — idea stage (in `ideas/incubating/`)
- `someday` — intentionally parked idea (in `ideas/someday/`)
- `rejected` — explicitly declined idea (in `ideas/rejected/`)

Portent frontmatter is authoritative for object meaning:

- Project transitions update `stage` and `status` before file moves.
- Operations should usually `belongs_to` a Responsibility or Project.
- Responsibilities should collect related Projects and Operations.
- Ideas promoted to active work become `type: Project`, `status: organized`, and
  `stage: active` before or during any folder movement.

## Valid Transitions

| From                                    | To            | Conditions         |
| --------------------------------------- | ------------- | ------------------ |
| `active` ↔ `exploring`                  | Bidirectional | Reclassification   |
| `active\|exploring` → `paused`          | One-way       | Needs break point  |
| `paused` → `active`                     | One-way       | Resuming work      |
| `exploring` → `incubating`              | One-way       | Back to idea stage |
| `active\|exploring\|paused` → `shipped` | One-way       | Completion         |
| `shipped` → `archived`                  | One-way       | Final archival     |
| `fleeting` → `incubating`               | One-way       | Idea has shape     |
| `incubating` → `someday`                | One-way       | Park for later     |
| `fleeting\|incubating` → `rejected`     | One-way       | Declined idea      |

## Mode Behavior

- `report`: audit Portent metadata vs filesystem/navigation state, detect
  mismatches, propose transitions
- `apply-safe`: apply unambiguous metadata and navigation updates only (no file
  moves)
- `apply`: apply confirmed transitions including file moves and link rewrites

## Workflow

1. **Scan active navigation**: Read `index.md` when present to discover active
   project and idea entry points.
2. **Scan projects/**: Discover project directories and their lifecycle
   location.
3. **Scan PORT metadata**:
   - Projects in `projects/`, shaped project candidates in `ideas/`
   - Operations under `notes/operations/` or equivalent local convention
   - Responsibilities under `notes/responsibilities/` or equivalent local
     convention
   - Task references that live outside the vault but relate back to Portent
     objects
4. **Detect mismatches**:
   - Portent `type`, `status`, and `stage` vs folder location
   - Active `index.md` entries vs archived or inactive object metadata
   - Active Projects missing from `index.md` when local convention uses an
     active catalog
   - Operations without a Responsibility or Project parent
   - Responsibilities without related Projects or Operations when obvious
   - Duplicate idea or project directories that should be one lifecycle item
5. **Propose transitions and merges**:
   - Smallest valid state change per mismatch
   - Canonical merge target for duplicate ideas/projects
   - Link rewrites and index/navigation updates required by the merge
6. **Handle idea promotion paths**:
   - `ideas/incubating/` → `projects/active/` (promote to project)
   - `ideas/fleeting/` → `ideas/incubating/` (promote idea)
   - `ideas/incubating/` → `ideas/someday/` (park idea)
   - `ideas/incubating/` → `ideas/rejected/` (decline idea)
7. **Apply by mode**:
   - `report`: return proposals with evidence and confidence
   - `apply-safe`: update Portent frontmatter, index links, and obvious
     backlinks when unambiguous, no merges
   - `apply`: perform confirmed file moves, high-confidence merges, and inbound
     link rewrites
8. **Shipped compaction**: When a project transitions to `shipped`, immediately
   run or propose
   `vault-compact --scope projects --project <name> --mode apply --aggression aggressive`
   to merge launch artifacts, drafts, research, and stale execution notes into
   one canonical shipped project record. Absorbed curated files may be deleted
   after unique content is preserved. Never delete `raw/`.
9. **Log operation**: Append concise entry to `log.md`

## Merge Rules

Merge idea or project directories only when they represent the same underlying
thing, not just similar domains. Prefer the more advanced lifecycle state as the
canonical destination (`active` over `incubating`, `incubating` over `fleeting`)
unless the user says otherwise.

- Preserve all files by moving them into the canonical directory or appending
  sections into the canonical note.
- Preserve former names as aliases or backlinks when useful.
- Rewrite inbound links to the canonical path.
- In `report` mode, show both the canonical destination and what would be moved.
- In `apply` mode, require clear evidence or explicit user instruction.

## Example Operations

```
# Report on all projects
vault-tracker --mode report

# Promote an incubating idea to active project
vault-tracker --mode apply --project my-idea promote-to-project

# Mark project as shipped
vault-tracker --mode apply-safe --project my-project mark shipped

# Archive a shipped project
vault-tracker --mode apply --project my-project archive now
```

## Safety

- **Never delete project files** — archive moves only
- **Never discard duplicate project or idea material** — merge or move it
- **Confirmation required** for destructive moves (archive transitions)
- **Link integrity**: Check/rewrite inbound links before archival
- **Metadata and docs are source of truth**: Keep Portent frontmatter and
  project docs aligned
- **Skip archive operations** for `active/exploring` without explicit evidence
- **Never touch** `raw/processed/*` or hidden/system directories

## Report Scope

Default scope is live surface only (`active`, `exploring`, `paused`). Include
`shipped`/`archived` only when explicitly requested via `--project` or explicit
transition.

## Compose Existing Skills

- `vault-lint` for stale/orphan detection and wikilink issues
- `vault-compact` for post-shipping project document consolidation
- `vault-concepts` for recurring theme promotion
- `vault-maintain` for periodic full-vault upkeep

## Output

Return:

- Transitions applied/proposed with evidence and confidence
- Mismatches detected (metadata vs filesystem/navigation)
- Files moved/renamed and link rewrite