3-Phase Migration Plan

## §5 Migration Phases

Migration is additive. No existing file is moved. No existing convention is broken. Each phase adds structure; nothing removes it.

### Phase 1 — Week 1: Tool exists, new invocations opt in

**Deliverable:** `~/system/tools/output-path.js` exists and is tested. Documentation page on BookStack (Agentic OS shelf). Release note in HiveMind.

**Behavior change:** New skill invocations that are aware of the helper call `output-path.js resolve` to get their run directory. Old invocations continue to write to `/tmp/-evidence/` or wherever they currently write. Both paths coexist.

**Migration bar:** Zero. No skill is forced to change. No existing output moves.

**Success signal:** At least one skill uses the new convention and the resulting directory exists under `~/projects/`.

### Phase 2 — Week 2-3: Three highest-volume skills opt in

**Target skills (by observed invocation frequency):**

1. `task-postflight` — runs after every MC completion
2. `codecraft` sub-agent — runs for every build/design task dispatched to CodeCraft
3. `proveo` sub-agent — runs for every validation task

**Changes per skill:**

- `brief.md` written at invocation start (from MC description).
- Outcome written to `/outcome.md` instead of terminal-only report.
- Evidence written to `/evidence/` instead of `/tmp/-evidence/`.
- `.provenance.json` written by `output-path.js` on first call.

**Backward compat:** Skills also write a symlink at the old `/tmp/-evidence/` location pointing to the new canonical path, for a 2-week grace period. After grace period, symlinks are removed (not the targets).

**Migration bar:** Opt-in. Each skill's maintainer (or the dispatching orchestrator) adds one `output-path.js resolve` call to the skill's preamble.

### Phase 3 — Deferred (month+): Linter and audit

**Deferred until Phases 1-2 are stable (≥2 weeks of clean runs).**

- **Audit script:** `~/system/tools/output-audit.js` scans /tmp/ for `*-evidence` directories older than 7 days. Reports count and size. Does NOT move or delete. Runs as a weekly LaunchAgent.
- **Lint hook:** A `pre-mc-ready` hook checks evidence references in the MC outcome field. If any reference points to `/tmp/` or `~/Public/` instead of `~/projects/`, hook emits a warning (stderr). NOT a block. Warning only.
- **Scope:** Phase 3 is intentionally deferred. Do not build it during Phase 1 or 2. Its value depends on Phase 2 adoption proving the convention stable.

### What NEVER happens

- Auto-move of any existing file or directory.
- Destructive consolidation of `/tmp/` contents.
- Breaking changes to any skill that does not opt in.
- Forced migration of `~/Public/` deliverables (CEO-facing files stay where CEO puts them).

---