Migrating from .clan-alpha/ to .canopy/

A 1-hour walkthrough for clans on the old format moving to canonical v2.0. No data loss. Reversible (the old .clan-alpha/ directory is never deleted).

Why Migrate

.clan-alpha/ is the early-2026 format used by 14 portfolio clans. .canopy/ is the canonical structure as of Canopy v2.0 (2026-05-24). The new format:

• Adds first-class slots for the v2.0 primitives (Invariants, Initiatives, CrossClanDependencies, LivingProcesses)
• Aligns with the methodology docs in docs/methodology/ — same vocabulary, same structure
• Is what the team-adoption CLI (Phase 19) will scaffold
• Is what downstream tooling (vocabulary lint, drift checks, Signal reporting) expects

Migration is voluntary but recommended before Phase 19's CLI ships, which assumes .canopy/.

Time Budget

• Pre-flight: 5 minutes (back up, inventory)
• Helper script: 1 minute (mechanical moves)
• Manual re-expression: 30-45 minutes (PROJECT.md, STATE.md, CrossClanDependency triage)
• Verification: 10 minutes (checklists)

Total: ~45-60 minutes for a clan with moderate state. Larger clans (Cortex-scale) may take longer; the under-1-hour target assumes a typical mid-size clan.

Pre-flight Checklist

• Back up the existing .clan-alpha/ directory (cp -r .clan-alpha/ .clan-alpha.backup-$(date +%Y%m%d)/)
• Confirm the repo is clean (git status shows no uncommitted changes you care about)
• Read VOCABULARY.md so you can spot any old vocabulary in your files that needs updating during the manual step
• Identify Alpha / clan-specific bits that should NOT migrate (clan identity in .clan-alpha/identity.md is Jungle-owned; project bits go to PROJECT.md but Alpha bits stay in .jungle/ or .brain/)
• Skim docs/methodology/validation/VALIDATION.md to remember which v2.0 primitives apply to your clan (do you have Invariants? Initiatives? Cross-clan dependencies?)

Mapping Table

What the script handles automatically:

What the user creates by hand (no equivalent in .clan-alpha/):

Step-by-Step

Step 1: Pre-flight (5 min)

Complete the checklist above. Most important: back up .clan-alpha/ before touching anything.

Step 2: Run the helper script (1 min)

Dry-run first to see the plan:

node scripts/migrate-clan-alpha.cjs --source .clan-alpha --dest .canopy --dry-run

Review the planned moves. If anything looks wrong, stop and ask before proceeding. If it all looks right:

node scripts/migrate-clan-alpha.cjs --source .clan-alpha --dest .canopy --execute

The script:

• Copies .clan-alpha/knowledge/*.md to .canopy/context/
• Copies .clan-alpha/decisions/DEC-*.md to .canopy/decisions/
• Copies legacy tracker files to .canopy/inbox/ (flagged for human triage)
• Routes the ambiguous state files to .canopy/inbox/ for re-expression
• Writes .canopy/MIGRATION-NOTES.md listing everything it did and what's left for you

The original .clan-alpha/ directory is untouched. Reversible: delete .canopy/, you're back to where you started.

Step 3: Re-express project metadata (10-15 min)

Open .canopy/inbox/IDENTITY-MIGRATION.md. Extract the project bits (name, core value, status, owner) into a new .canopy/PROJECT.md — use this Canopy project's .canopy/PROJECT.md as a template.

DO NOT migrate clan / Alpha identity bits to PROJECT.md. Those belong in Jungle's territory (.jungle/ or .brain/) and are Jungle-owned. The Canopy method scaffolds project intelligence, not clan registration. See docs/methodology/validation/VALIDATION.md for the clan / Jungle separation rationale.

Once PROJECT.md is written, delete .canopy/inbox/IDENTITY-MIGRATION.md.

Step 4: Re-express state (10-15 min)

Open .canopy/inbox/STATE-MIGRATION.md (formerly state/open-items.md). Re-express as:

• Current position, decisions, blockers → .canopy/STATE.md (use this project's STATE.md as template)
• Open Outcomes → individual Outcome entries (when your platform supports them) or in the relevant phase's PLAN.md
• Open Decisions → already migrated to .canopy/decisions/ by the script
• Open Issues → flagged in .canopy/inbox/ from the legacy-tracker migration; reclassify

Delete the inbox migration files as you process them.

Step 5: Re-express cross-clan dependencies (5-10 min)

Open .canopy/inbox/CROSS-CLAN-INCOMING.md and .canopy/inbox/CROSS-CLAN-OUTGOING.md. For each entry, create a CrossClanDependency entity per CROSS-CLAN.md. If your platform doesn't yet support CrossClanDependency (Phase 16 implements), capture the entries in .canopy/inbox/CROSS-CLAN-PENDING.md for later — they'll be ready to file when Phase 16 ships.

Step 6: Triage legacy tracker entries (5-10 min)

Open each .canopy/inbox/*.md (the migrated legacy-tracker entries). For each, decide:

• Is this a result statement ("Users can do X")? It's an Outcome. Move it (or create the proper Outcome record).
• Is this a bug? It's an Issue. Move it to .canopy/issues/ (or your platform's Issue tracker) using the BUGS.md vocabulary.
• Is this an open question? It's a Decision. Move it to .canopy/decisions/.
• Is it a piece of knowledge? It's Context. Move it to .canopy/context/.

Use the v2.0 vocabulary: kind / diagnostic_state / owner_uncertain as appropriate.

Step 7: Run verification checklist (10 min)

See "Verification" below.

Verification (Post-Migration)

• .canopy/PROJECT.md exists with project metadata
• .canopy/STATE.md exists with current position
• .canopy/context/ has all migrated knowledge entries
• .canopy/decisions/ has all migrated DEC-* files
• .canopy/inbox/ is EMPTY (or contains only files you've explicitly deferred with a note)
• Every Outcome from .clan-alpha/state/open-items.md is accounted for (either migrated to a new Outcome record or explicitly closed)
• Every cross-clan dependency from state/incoming.md and state/outgoing.md is either a CrossClanDependency entity (Phase 16+) or captured in inbox/CROSS-CLAN-PENDING.md
• Vocabulary check passes: node scripts/check-vocabulary.cjs --paths .canopy exits 0
• Original .clan-alpha/ directory still exists untouched (rollback safety)

If all checks pass, the migration is complete. The .clan-alpha/ directory can be archived or deleted at your discretion (recommend keeping for at least one milestone cycle).

Rollback

If something went wrong:

rm -rf .canopy
# .clan-alpha/ is untouched; you're back to the pre-migration state

The helper script never modifies .clan-alpha/. Rollback is always one rm -rf .canopy away.

Special Cases

Coalition repos (multi-Alpha)

Three audit clans (Jungle's .brains/{nexus,obsidian,webmaster}, Pocket, Trellis) run multiple Alphas per repo. For coalition repos:

• One .canopy/ per repo (not per Alpha)
• PROJECT.md documents the coalition explicitly (list participating Alphas)
• STATE.md references all participating Alphas in the "current position" section
• See DECISIONS.md's "Multi-Alpha Coalition Decisions" variant

Council-tier clans with LivingProcess

Council-tier clans (Cortex, Jungle Obsidian / Nexus / Webmaster) have always-on processes. During migration, capture each LivingProcess in .canopy/inbox/LIVING-PROCESSES-PENDING.md for filing as proper LivingProcess entities when Phase 15 ships. See LIVING-PROCESS.md.

Clans with significant Invariants

If your .clan-alpha/knowledge/ contains standing constraints (HIPAA, brand-voice, audit-trail, etc.), don't just migrate them as Context. Re-classify as Invariants per INVARIANTS.md. Capture in .canopy/inbox/INVARIANTS-PENDING.md for filing when Phase 13 ships.

Clans with cross-cutting subsystems (Initiatives)

If your .clan-alpha/tickets/ shows clusters of related work tracked individually (a telephony bridge, a plugin system, an analyzer-pass program), capture each cluster as a candidate Initiative in .canopy/inbox/INITIATIVES-PENDING.md for filing when Phase 14 ships. See INITIATIVES.md.

Cross-refs

• METHOD.md — the methodology being migrated to
• VOCABULARY.md — preferred terms for the re-expressed content
• INVARIANTS.md, INITIATIVES.md, CROSS-CLAN.md, LIVING-PROCESS.md, BUGS.md — v2.0 primitives to re-express into
• PORTFOLIO.md — the 14 portfolio clans this guide is written for
• scripts/migrate-clan-alpha.cjs — the helper script
• docs/methodology/validation/VALIDATION.md — context on why migration matters

Source

Migration guide written for v7.0 Phase 11. Origin: METH-08 requirement in .canopy/REQUIREMENTS.md.