cap-pro 1.0.0

package/commands/cap/memory.md

@@ -0,0 +1,275 @@
+---
+name: cap:memory
+description: "Manage project memory — bootstrap, run pipeline, pin/unpin annotations, view status, migrate to V6."
+argument-hint: "[init|status|pin|unpin|prune|migrate] [--dry-run|--apply]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+---
+
+<!-- @cap-feature(feature:F-030) Memory command — bootstrap, manual trigger, pin/unpin/status management -->
+<!-- @cap-decision /cap:memory init processes ALL sessions for the current project — one-time bootstrap to build initial memory. -->
+<!-- @cap-decision /cap:memory with no args runs incremental only (sessions since last run). -->
+
+<objective>
+Manage project memory — bootstrap from existing sessions, run incremental pipeline, or manage annotations.
+
+**Subcommands:**
+- `init` — **Bootstrap**: process ALL sessions for this project, build initial memory (run once per project)
+- `(no args)` — run incremental pipeline (only sessions since last run)
+- `status` — show memory summary (annotation counts, stale, pinned, last run)
+- `pin <file> <content-prefix>` — mark a @cap-pitfall as pinned:true
+- `unpin <file> <content-prefix>` — remove pinned:true from annotation
+- `prune [--apply]` — decay stale entries, archive very-stale low-confidence ones, purge old raw-logs (default dry-run)
+- `migrate [--apply] [--interactive=false]` — **F-077**: one-shot migration from V5 monolith files (`decisions.md`, `pitfalls.md`, etc.) to V6 per-feature layout under `.cap/memory/features/`. Default is dry-run; `--apply` requires a confirm prompt unless `--interactive=false` is passed.
+- `--switch-layout=v6` — **F-095**: lightweight V5→V6 layout activation. Reads existing V5 entries, persists `.cap/config.json: { memory: { layout: 'v6' } }`, triggers one `writeMemoryDirectory` call so the V6 dispatch produces per-feature/platform files + Index. No session reprocess. Idempotent (V6→V6 no-op).
+- `--dry-run` — show what would change without writing
+</objective>
+
+<process>
+
+## Subcommand: init (Bootstrap)
+
+One-time full processing of all sessions for this project. Run this when setting up memory for an existing project.
+
+```bash
+node "$HOME/.claude/hooks/cap-memory.js" init
+```
+
+This will:
+1. Find all session JSONL files for the current project directory
+2. Parse every session — extract decisions, pitfalls, patterns, file edit history
+3. Write @cap-history, @cap-pitfall, @cap-pattern annotations into source files
+4. Generate .cap/memory/ directory (decisions.md, hotspots.md, patterns.md, pitfalls.md)
+5. Save timestamp to .cap/memory/.last-run (future hook runs are incremental from here)
+
+Display the output to the user. Then show:
+
+```
+Bootstrap complete.
+
+Memory directory: .cap/memory/
+  - decisions.md
+  - hotspots.md
+  - patterns.md
+  - pitfalls.md
+
+From now on, the Stop hook will run incrementally after each session.
+Run /cap:memory status to see what was accumulated.
+```
+
+## Default (no args): Run incremental pipeline
+
+```bash
+node "$HOME/.claude/hooks/cap-memory.js"
+```
+
+Only processes sessions newer than .cap/memory/.last-run timestamp.
+If .last-run doesn't exist, processes all sessions (same as init).
+
+<!-- @cap-decision(F-079/iter1) Stage-2 #1 fix: processSnapshots wired into memory-pipeline. -->
+The pipeline also walks `.cap/snapshots/` and updates the `linked_snapshots` auto-block in every
+per-feature / platform memory file the snapshots route to (F-079/AC-4). Re-running the pipeline
+on the same set of snapshots is byte-identical (idempotent contract pinned by F-079 tests).
+
+## Subcommand: status
+
+```bash
+node -e "
+const fs = require('node:fs');
+const path = require('node:path');
+const memDir = path.join(process.cwd(), '.cap', 'memory');
+const lastRunPath = path.join(memDir, '.last-run');
+const lastRun = fs.existsSync(lastRunPath) ? fs.readFileSync(lastRunPath, 'utf8').trim() : 'never';
+const categories = ['decisions.md', 'hotspots.md', 'patterns.md', 'pitfalls.md'];
+const stats = { lastRun };
+for (const f of categories) {
+  const fp = path.join(memDir, f);
+  if (fs.existsSync(fp)) {
+    const content = fs.readFileSync(fp, 'utf8');
+    const entries = (content.match(/^###/gm) || []).length;
+    const pinned = (content.match(/\[pinned\]/g) || []).length;
+    const tableRows = (content.match(/^\| \d/gm) || []).length;
+    stats[f] = { entries: entries + tableRows, pinned };
+  } else {
+    stats[f] = { entries: 0, pinned: 0 };
+  }
+}
+console.log(JSON.stringify(stats, null, 2));
+"
+```
+
+Display as summary table:
+```
+Project Memory Status
+  Last run: {timestamp or "never — run /cap:memory init to bootstrap"}
+  decisions.md:  {N} entries ({P} pinned)
+  hotspots.md:   {N} entries
+  patterns.md:   {N} entries
+  pitfalls.md:   {N} entries ({P} pinned)
+```
+
+## Subcommand: pin `<file>` `<content-prefix>`
+
+<!-- @cap-todo(ac:F-030/AC-4) /cap:memory pin adds pinned:true to the matching @cap-pitfall annotation. -->
+
+```bash
+node -e "
+const pin = require('./cap/bin/lib/cap-memory-pin.cjs');
+const file = process.argv[1];
+const prefix = process.argv[2];
+const result = pin.pin(file, prefix);
+console.log(pin.formatResult(result));
+process.exit(result.changed || result.status === 'already-pinned' ? 0 : 1);
+" '<FILE>' '<PREFIX>'
+```
+
+Argument usage:
+
+- `<file>` — path to the source file that carries the `@cap-pitfall` annotation (absolute or relative to the project root).
+- `<content-prefix>` — a prefix of the pitfall description (case-sensitive). Use enough to disambiguate if multiple pitfalls live in the same file.
+
+On `ambiguous` status the command prints the candidate descriptions; rerun with a longer prefix to select one.
+
+## Subcommand: unpin `<file>` `<content-prefix>`
+
+<!-- @cap-todo(ac:F-030/AC-5) /cap:memory unpin removes pinned:true from the matching annotation. -->
+
+```bash
+node -e "
+const pin = require('./cap/bin/lib/cap-memory-pin.cjs');
+const file = process.argv[1];
+const prefix = process.argv[2];
+const result = pin.unpin(file, prefix);
+console.log(pin.formatResult(result));
+process.exit(result.changed || result.status === 'not-pinned' ? 0 : 1);
+" '<FILE>' '<PREFIX>'
+```
+
+Same argument semantics as `pin`. An already-unpinned annotation exits 0 with a no-op message.
+
+## Subcommand: prune `[--apply] [--gitignored]`
+
+<!-- @cap-todo(ac:F-056/AC-1) /cap:memory prune is the F-056 subcommand for decay + archive + raw-log purge. -->
+<!-- @cap-todo(ac:F-056/AC-2) Default is dry-run; --apply is required to mutate files. -->
+<!-- @cap-todo(ac:F-056/AC-6) Prune emits a human report and appends .cap/memory/prune-log.jsonl. -->
+<!-- @cap-todo(ac:F-086/AC-3) --gitignored mode runs the scope-filter pass (gitignored entries + bundle-paths). -->
+
+```bash
+node -e "
+const prune = require('./cap/bin/lib/cap-memory-prune.cjs');
+const args = process.argv.slice(1);
+const applyFlag = args.includes('--apply');
+const gitignoredMode = args.includes('--gitignored');
+if (gitignoredMode) {
+  const result = prune.pruneGitignored(process.cwd(), { apply: applyFlag });
+  console.log(prune.formatGitignoredReport(result));
+  process.exit(result.errors && result.errors.length > 0 ? 1 : 0);
+} else {
+  const result = prune.prune(process.cwd(), { apply: applyFlag });
+  console.log(prune.formatReport(result));
+  process.exit(result.errors && result.errors.length > 0 ? 1 : 0);
+}
+" -- {ARGS}
+```
+
+What prune does (default mode):
+
+- **Decay** (AC-3): entries with `last_seen > 90 days` lose `-0.05` confidence per additional 30 days of inactivity, floored at `0.0`. Pinned entries are never decayed.
+- **Archive** (AC-4): entries with `confidence < 0.2` AND `last_seen > 180 days` move to `.cap/memory/archive/{YYYY-MM}.md` (the archival month, not the entry's own month). Decay runs first — an entry can cross the threshold via decay and get archived in the same run. Pinned entries are never archived.
+- **Purge** (AC-5): raw event logs under `.cap/memory/raw/tag-events-YYYY-MM-DD.jsonl` older than 30 days are hard-deleted.
+- **Report + log** (AC-6): a console report is emitted. On `--apply`, a single JSONL line `{timestamp, dryRun, decayed, archived, purged}` is appended to `.cap/memory/prune-log.jsonl`.
+
+What `--gitignored` does (F-086/AC-3):
+
+- Runs the **shared scope filter** (`cap-scope-filter.cjs`) against each existing memory entry's referenced files.
+- Removes V5 entries (`decisions.md` / `pitfalls.md` / `patterns.md` / `hotspots.md`) whose ALL related files are now out-of-scope (gitignored, plugin-mirror, build-output bundle).
+- Removes V6 bullet lines (`features/*.md`, `platform/*.md`) whose backtick-wrapped path would be excluded.
+- Useful for projects bootstrapped on a pre-F-085 CAP version that accumulated build-output decisions and bundle-artefact references.
+
+Default behaviour is **dry-run** — no files are touched and no prune-log entry is written. Pass `--apply` explicitly to commit the changes. The two modes (`--gitignored` and the default decay/archive flow) cannot be combined; pick one per run.
+
+## Subcommand: migrate `[--apply] [--interactive=false]`
+
+<!-- @cap-feature(feature:F-077) /cap:memory migrate — V6 per-feature memory migration entry point. -->
+<!-- @cap-todo(ac:F-077/AC-4) Default is dry-run; --apply requires explicit confirm in interactive mode. -->
+
+```bash
+node -e "
+const m = require('./cap/bin/lib/cap-memory-migrate.cjs');
+const args = process.argv.slice(1);
+const apply = args.includes('--apply');
+const interactive = !args.includes('--interactive=false');
+m.migrateMemory(process.cwd(), { apply, interactive }).then(r => {
+  if (r.report) {
+    console.log('Migration report written to .cap/memory/.archive/');
+    console.log('  Total entries:', r.report.counts.total);
+    console.log('  Assigned:    ', r.report.counts.assigned);
+    console.log('  Platform:    ', r.report.counts.platform);
+    console.log('  Skipped:     ', r.report.counts.skipped);
+  }
+  process.exit(r.exitCode);
+}).catch(e => { console.error('migrate failed:', e.message); process.exit(1); });
+" -- {ARGS}
+```
+
+What migrate does (one-shot V5 -> V6):
+
+1. **Parses** `decisions.md`, `pitfalls.md`, `patterns.md`, `hotspots.md` and (for hotspots fallback) `graph.json`.
+2. **Backs up** the V5 files to `.cap/memory/.archive/<name>-pre-v6-<YYYY-MM-DD>.<ext>` (idempotent on same date).
+3. **Classifies** each entry by priority: tag-metadata (`@cap-decision(feature:F-NNN)`) -> `key_files` path-match -> F-NNN body mention. Confidence >= 0.7 auto-routes; lower = ambiguous.
+4. **Routes** snapshots from `.cap/snapshots/` by frontmatter `feature:` field, then date proximity to FEATURE-MAP transitions, then title keyword.
+5. **Prompts interactively** for ambiguous entries (top-3 candidates + skip + auto-all + quit) when `--apply` is set with default `--interactive=true`.
+6. **Atomically writes** V6 files under `.cap/memory/features/F-NNN-<topic>.md` and `.cap/memory/platform/<topic>.md` (write-temp-then-rename, F-074 pattern).
+7. **Writes a migration report** at `.cap/memory/.archive/migration-report-<YYYY-MM-DD>.md` summarising counts and ambiguity resolutions.
+
+Default is **dry-run** -- no files touched. The dry-run output is sent to stderr and lists the planned writes, backup status, and ambiguity counts. Pass `--apply` to execute. Add `--interactive=false` to skip the confirm prompt and auto-resolve every ambiguity to its highest-confidence candidate (CI-friendly).
+
+Exit codes: `0` success, `1` errors during apply, `2` user-initiated quit (declined confirm or `q` in ambiguity prompt).
+
+After a successful migration, the user commits `.cap/memory/features/`, `.cap/memory/platform/`, and `.cap/memory/.archive/` to git themselves -- the tool deliberately does NOT touch git.
+
+## Subcommand: --switch-layout=v6
+
+<!-- @cap-feature(feature:F-095) /cap:memory --switch-layout=v6 — lightweight V5→V6 activation. -->
+<!-- @cap-decision(F-095) write-then-rollback statt config-first: writeMemoryDirectory wird zuerst aufgerufen, config.json erst nach success persistiert. Bei error bleiben V5-Files + alte config unverändert. -->
+
+```bash
+node -e "
+const dir = require('./cap/bin/lib/cap-memory-dir.cjs');
+try {
+  const r = dir.switchLayout(process.cwd(), 'v6');
+  if (r.status === 'noop') {
+    console.log('cap-memory: layout already v6 — no changes.');
+  } else {
+    console.log('cap-memory: switched to v6 layout');
+    console.log('  source entries:    ', r.sourceEntries);
+    console.log('  files written:     ', r.written);
+    console.log('  config persisted:  ', r.configPath);
+    console.log('  V5 backups present:', r.archives.length);
+  }
+} catch (e) {
+  console.error('switch-layout failed:', e.message);
+  console.error('config.json not modified, V5 files unchanged.');
+  process.exit(1);
+}
+"
+```
+
+What --switch-layout=v6 does:
+
+1. **Reads** existing V5 entries from `decisions.md` and `pitfalls.md` via `readMemoryFile()`.
+2. **Calls** `writeMemoryDirectory(projectRoot, entries, { layout: 'v6' })` — V6 dispatch creates `features/F-XXX-<topic>.md`, `platform/<topic>.md`, top-level Index files, and archives V5 monoliths to `.cap/memory/.archive/`.
+3. **Persists** `.cap/config.json: { memory: { layout: 'v6' } }` — only after step 2 succeeds. Existing keys in config.json are preserved.
+4. **Reports** source-entry count, files-written count, config-path, archive-paths.
+
+**Idempotency:** If `decisions.md` already has the `(V6 Index)` marker, the call is a no-op (`status: 'noop'`).
+
+**Difference vs. `migrate`:** `migrate` is a one-shot **deep migration** (interactive disambiguation prompts, classification reports, snapshot routing, prompt-for-ambiguous). `--switch-layout=v6` is the **lightweight activation step** for projects that already migrated (or are happy with auto-classification). No session reprocess, <1s on typical project size.
+
+**Use when:** You have a Bestandsprojekt with V5 monolithic memory, want V6 token-cost-of-read benefits, and don't need the deep migration ceremony. Or after `/cap:memory migrate --apply` if the writeMemoryDirectory dispatch never triggered (e.g. Stop-Hook returns early without new sessions).
+
+</process>

package/commands/cap/migrate-feature-map.md

@@ -0,0 +1,91 @@
+---
+name: cap:migrate-feature-map
+description: "Shard a monolithic FEATURE-MAP.md into Index + per-feature files (F-089). Spawns cap-migrator (MODE: FEATURE-MAP)."
+argument-hint: "[--apply] [--app=<path>] [--force]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Task
+---
+
+<!-- @cap-feature(feature:F-089, primary:true) /cap:migrate-feature-map — thin wrapper around cap-migrator (MODE: FEATURE-MAP). -->
+<!-- @cap-decision Wrapper pattern. Byte-lossless extraction (raw bytes, no parse → serialize) and atomic backup + rollback live in cap-migrator. -->
+<!-- @cap-decision Argument compat: --apply, --app=<path>, --force preserved. Dry-run remains the default. -->
+
+<objective>
+Shard the monolithic `FEATURE-MAP.md` into the F-089 layout:
+
+```
+FEATURE-MAP.md          ← index file (one line per feature)
+features/F-001.md       ← full feature block
+features/F-002.md
+features/F-Hub-Spotlight.md
+...
+FEATURE-MAP.md.backup-pre-F-089   ← byte-identical backup of the original
+```
+
+**Why:** A FEATURE-MAP that grew to 4,000+ lines costs 30–50k tokens for every agent read. Sharded mode makes agents load just the index (~100 chars per feature) plus the active feature's per-feature file — typically a 10–50× token reduction on large projects.
+
+The migration is **byte-lossless** for feature blocks (raw extraction). Once migrated, all CAP commands continue to work via the read/write dispatchers — no agent prompts need to change.
+
+**Flags (backwards-compatible):**
+- `--apply` — write the migration to disk. Without it, dry-run only.
+- `--app=<path>` — operate on a sub-app's `FEATURE-MAP.md` instead of the root (e.g. `--app=apps/hub`).
+- `--force` — proceed even when the planner flagged duplicate IDs or other issues. NOT recommended for duplicates.
+
+**Idempotency:** Re-running on an already-sharded project is a no-op. Backwards-compat: projects without `features/` continue to work in monolithic mode.
+</objective>
+
+<context>
+$ARGUMENTS
+</context>
+
+<process>
+
+## Step 1: Parse flags
+
+From `$ARGUMENTS`:
+- `apply = $ARGUMENTS contains "--apply"`
+- `app_path = value after --app=` (or null)
+- `force = $ARGUMENTS contains "--force"`
+
+## Step 2: Spawn cap-migrator (MODE: FEATURE-MAP)
+
+Use the Task tool to spawn `cap-migrator`. Forward `$ARGUMENTS` verbatim.
+
+```
+**MODE: FEATURE-MAP**
+
+$ARGUMENTS
+
+**Flags resolved by /cap:migrate-feature-map:**
+- apply: {apply}
+- app_path: {app_path or root}
+- force: {force}
+
+**Pipeline obligations (MODE: FEATURE-MAP):**
+1. Plan via `cap-feature-map-migrate.cjs::planMigration(projectRoot, app_path)`.
+2. Render verbatim using `formatPlan`. Source-mode handling:
+   - `missing` — abort, nothing to migrate.
+   - `sharded` — already done; emit `=== PLAN-ONLY ===` and exit.
+   - `monolithic` — proceed.
+   - `monolithic` with skips (duplicate IDs etc.) — surface skips, ask user to resolve OR pass --force to proceed without those features.
+3. If --apply: AskUserQuestion → "Migrate FEATURE-MAP.md to sharded layout? Will write N per-feature files + backup + new index. (yes/no)" — skip the prompt only if --apply was passed AND the plan has zero skips.
+4. On apply success, stage + verify + promote per the shared pipeline. Verify obligations:
+   - `readFeatureMap()` loads the same feature count as the planner.
+   - Every feature ID in the index has a matching `features/F-<id>.md`.
+   - The `FEATURE-MAP.md.backup-pre-F-089` matches the original by byte-length and sha256.
+
+**Output contract:** preserve `formatPlan` output verbatim, then append the `=== MIGRATION RESULTS ===` block.
+```
+
+## Step 3: Post-apply guidance
+
+After a successful apply, point the user to the next step:
+
+- "Sharded layout active. Index file: `FEATURE-MAP.md`. Per-feature files: `features/F-*.md`. Backup: `FEATURE-MAP.md.backup-pre-F-089`."
+- "All CAP commands (`/cap:scan`, `/cap:reconcile`, `/cap:status`, etc.) continue to work transparently."
+- "If anything looks wrong, restore via the migrator backup at `.cap/migrations/<tx_id>/backup/` or via: `cp FEATURE-MAP.md.backup-pre-F-089 FEATURE-MAP.md && rm -rf features/`"
+
+</process>

package/commands/cap/migrate-memory.md

@@ -0,0 +1,108 @@
+---
+name: cap:migrate-memory
+description: "Migrate V5 monolithic project memory (.cap/memory/{decisions,pitfalls,patterns,hotspots}.md) to V6 per-feature layout (F-077). Spawns cap-migrator (MODE: MEMORY)."
+argument-hint: "[--apply] [--interactive=false] [--allow-large-diff]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Task
+  - AskUserQuestion
+---
+
+<!-- @cap-feature(feature:F-077, primary:true) /cap:migrate-memory — thin wrapper around cap-migrator (MODE: MEMORY). -->
+<!-- @cap-decision New top-level command (sibling to /cap:migrate-tags and /cap:migrate-feature-map). The legacy `/cap:memory migrate` subcommand remains as an alias for backwards compatibility — both ultimately route through cap-migrator (MODE: MEMORY). -->
+<!-- @cap-decision Argument compat: --apply and --interactive=false mirror the existing /cap:memory migrate flags. --allow-large-diff is added for parity with the other migrators. -->
+
+<objective>
+Migrate V5 monolithic project memory to the V6 per-feature layout (F-077).
+
+**V5 (legacy):** monolithic `.cap/memory/decisions.md`, `pitfalls.md`, `patterns.md`, `hotspots.md` plus `graph.json`. Detected as V5 when the top-level files lack the `(V6 Index)` marker.
+
+**V6 (target):** per-feature files under `.cap/memory/features/F-NNN-<topic>.md`, cross-cutting topics under `.cap/memory/platform/<topic>.md`, ambiguous entries pooled in `.cap/memory/snapshots-unassigned.md`. The top-level `decisions.md` / `pitfalls.md` become thin `(V6 Index)` index tables (`Destination | Count | File`).
+
+**Why:** V6 lets agents load only the index plus the active feature's memory file — typically a 10–50× token reduction over reading the full V5 monolith on every Read.
+
+This command is a thin wrapper that spawns the `cap-migrator` agent in **MODE: MEMORY**. The agent owns the atomic Plan→Diff→Apply→Verify pipeline with backup + rollback under `.cap/migrations/<id>/`. The agent reuses the existing `cap-memory-migrate.cjs::migrateMemory()` pipeline (classification, snapshot routing, ambiguity prompts) — no logic is reimplemented.
+
+**Flags:**
+- `--apply` — execute the migration. Without it, dry-run only (default).
+- `--interactive=false` — auto-resolve every ambiguity to its highest-confidence candidate (CI-friendly). Default is interactive.
+- `--allow-large-diff` — bypass the 100 KB / 500-file safety gate after a clean dry-run review.
+</objective>
+
+<context>
+$ARGUMENTS
+</context>
+
+<process>
+
+## Step 1: Parse flags
+
+From `$ARGUMENTS`:
+- `apply = $ARGUMENTS contains "--apply"`
+- `interactive = NOT ($ARGUMENTS contains "--interactive=false")`
+- `allow_large_diff = $ARGUMENTS contains "--allow-large-diff"`
+
+## Step 2: Spawn cap-migrator (MODE: MEMORY)
+
+Use the Task tool to spawn `cap-migrator`. Forward `$ARGUMENTS` verbatim.
+
+```
+**MODE: MEMORY**
+
+$ARGUMENTS
+
+**Flags resolved by /cap:migrate-memory:**
+- apply: {apply}
+- interactive: {interactive}
+- allow_large_diff: {allow_large_diff}
+
+**Pipeline obligations (MODE: MEMORY):**
+1. Detect V5 vs V6 by reading `.cap/memory/decisions.md`. If it already contains `(V6 Index)`, emit `=== PLAN-ONLY ===` (already migrated) and stop.
+2. Plan via `cap-memory-migrate.cjs::planMigration(projectRoot)` (or `migrateMemory(projectRoot, { apply: false, interactive })` for full classification dry-run).
+3. Render the plan with classification counts: total, assigned (per-feature), platform, unassigned, ambiguous-needing-prompt.
+4. If --apply AND interactive: prompt for each ambiguous entry (top-3 candidates + skip + auto-all + quit) using AskUserQuestion. If --interactive=false, auto-resolve all to highest-confidence candidate.
+5. Stage + verify + promote per the shared pipeline. V5 source files are backed up to BOTH `.cap/migrations/<tx_id>/backup/` (migrator) AND `.cap/memory/.archive/<date>/` (memory-pipeline convention).
+6. Stage rewritten top-level `decisions.md` / `pitfalls.md` as `(V6 Index)` index tables.
+7. Stage migration report at `.cap/memory/.archive/migration-report-<date>.md`.
+
+**Verify obligations:**
+- Every V5 entry has exactly one V6 destination (no loss, no duplication).
+- Each `(V6 Index)` table count matches the file scan count.
+- All staged Markdown parses without error.
+- On any failure: roll back via `.cap/migrations/<tx_id>/backup/` AND restore from `.cap/memory/.archive/<date>/`.
+
+**Output contract:** preserve the `migrateMemory()` report counters (total / assigned / platform / skipped) AND emit the standard `=== MIGRATION RESULTS ===` block.
+```
+
+## Step 3: Post-apply guidance
+
+After a successful apply, point the user to the next step:
+
+```
+V6 layout active.
+
+Index files (root):    .cap/memory/decisions.md, pitfalls.md  ← (V6 Index) tables
+Per-feature memory:    .cap/memory/features/F-NNN-<topic>.md
+Platform memory:       .cap/memory/platform/<topic>.md
+Migration report:      .cap/memory/.archive/migration-report-<date>.md
+Migrator backup:       .cap/migrations/<tx_id>/backup/
+
+The agent rule at .claude/rules/cap-memory.md auto-detects the (V6 Index) marker
+and reads only the relevant per-feature file. No agent prompts need to change.
+
+If anything looks wrong, the rollback paths are preserved in BOTH backup locations.
+Commit .cap/memory/features/, .cap/memory/platform/, and .cap/memory/.archive/ to git when satisfied.
+```
+
+If only a dry-run was requested:
+
+```
+Dry-run complete. No files were modified.
+
+Run /cap:migrate-memory --apply to execute.
+For CI: /cap:migrate-memory --apply --interactive=false
+```
+
+</process>

package/commands/cap/migrate-tags.md

@@ -0,0 +1,91 @@
+---
+name: cap:migrate-tags
+description: "Migrate fragmented @cap-feature / @cap-todo(ac:…) tags to unified @cap anchor blocks (F-047, additive). Spawns cap-migrator (MODE: TAGS)."
+argument-hint: "[--apply] [--json] [--include=<glob>] [--exclude=<glob>] [--allow-large-diff] [--force]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Task
+---
+
+<!-- @cap-feature(feature:F-047, primary:true) /cap:migrate-tags — thin wrapper around cap-migrator (MODE: TAGS). -->
+<!-- @cap-feature(feature:F-085) Scope-filter (gitignore + plugin-mirror + 500-file safety gate) is enforced by the agent. -->
+<!-- @cap-decision Wrapper pattern. Plan→Diff→Apply→Verify with atomic backup + rollback lives in cap-migrator. -->
+<!-- @cap-decision Argument compat: --apply, --json, --include=, --exclude=, --allow-large-diff, --force are all preserved. Dry-run remains the default. -->
+
+<objective>
+Plan and optionally apply the migration from fragmented `@cap-*` tags to the unified anchor block format introduced by F-047.
+
+The migration is **additive** — legacy fragmented tags are preserved alongside the new unified block so the two formats can coexist while the ecosystem converts. A future cleanup pass can remove the fragmented tags once the unified block is universal.
+
+**Opt-in gate (F-047):** requires `.cap/config.json → unifiedAnchors.enabled = true`. Without it, `--apply` is refused; `--force` permits a dry-run preview only.
+
+**Scope (F-085):** the migrator shares `cap-scope-filter.cjs` with `cap-tag-scanner`, skipping by default:
+- everything matched by the project's top-level `.gitignore` (typically `.claude/`, `node_modules/`, `dist/`, `coverage/`, …);
+- agent worktrees under `.claude/worktrees/`;
+- the plugin-self-mirror at `.claude/cap/`;
+- test fixtures under `tests/fixtures/` and `**/fixtures/polyglot/`.
+
+A built-in safety gate refuses to apply the migration to more than 500 files in a single run; bypass with `--allow-large-diff` after verifying the dry-run report.
+
+**Flags (backwards-compatible):**
+- `--apply` — write the migration to disk after explicit confirmation. Without it, dry-run only.
+- `--json` — emit the structured migration plan as JSON for downstream tools.
+- `--include=<glob>` — restrict the scan to paths matching the pattern (additive, repeatable).
+- `--exclude=<glob>` — additionally skip paths matching the pattern (additive, repeatable).
+- `--allow-large-diff` — permit `--apply` to write more than 500 files.
+- `--force` — ignore the F-047 opt-in gate (dry-run preview only).
+</objective>
+
+<context>
+$ARGUMENTS
+</context>
+
+<process>
+
+## Step 1: Parse flags
+
+From `$ARGUMENTS`:
+- `apply`, `json`, `force`, `allow_large_diff` — boolean flags
+- `include`, `exclude` — collected glob lists (repeatable)
+
+## Step 2: Spawn cap-migrator (MODE: TAGS)
+
+Use the Task tool to spawn `cap-migrator`. Forward `$ARGUMENTS` verbatim.
+
+```
+**MODE: TAGS**
+
+$ARGUMENTS
+
+**Flags resolved by /cap:migrate-tags:**
+- apply: {apply}
+- json: {json}
+- force: {force}
+- allow_large_diff: {allow_large_diff}
+- include: {include or none}
+- exclude: {exclude or none}
+
+**Pipeline obligations (MODE: TAGS):**
+1. Gate on `.cap/config.json → unifiedAnchors.enabled === true` (F-047 opt-in). On gate-fail without --force, refuse and print:
+   "F-047 (unified anchors) is opt-in and not enabled for this project.
+    To enable: add { \"unifiedAnchors\": { \"enabled\": true } } to .cap/config.json
+    You can still run the migration with --force (dry-run) to preview the diff."
+2. Plan via `cap-migrate-tags.cjs::planProjectMigration` honoring include/exclude globs.
+3. Render the plan with `cap-migrate-tags.cjs::formatMigrationReport`. If --json, emit the plan JSON instead.
+4. If --apply AND gate passed: AskUserQuestion → "Apply the unified-anchor migration to the listed files? (yes/no)" — abort on no.
+5. On yes: stage + verify + promote via the MODE: TAGS pipeline. The 500-file ceiling raises `CAP_MIGRATE_LARGE_DIFF` unless --allow-large-diff.
+6. Legacy fragmented tags MUST be preserved (additive migration).
+
+**Output contract:** preserve `cap-migrate-tags.cjs::formatMigrationReport` output verbatim, then append the `=== MIGRATION RESULTS ===` block.
+```
+
+## Step 3: Suggest next action (based on agent results)
+
+- If dry-run completed with changes: "Run `/cap:migrate-tags --apply` to persist the anchors. Legacy tags remain in place; a future cleanup pass can remove them."
+- If the F-047 gate blocked the run: "Enable F-047 via `.cap/config.json → unifiedAnchors.enabled=true`, then re-run."
+- If `CAP_MIGRATE_LARGE_DIFF` fired: "Verify the dry-run scope, then re-run with `--allow-large-diff` to override."
+- If nothing to change: "Project is already migrated or has no fragmented tags."
+
+</process>