gdd-migrate-context

name	gdd-migrate-context
description	Migrates a pre-Phase-52 project from the flat .design/map/*.md mapper notes to the typed DesignContext graph at .design/context-graph.json. Reads the old map notes, runs the deterministic extract-*.mjs passes to build mapper fragments, merges them with merge-fragments.mjs, validates the result with validate-design-context.cjs, and flags every low-confidence transform for human review before anything is trusted. Read-first and reversible; --dry-run previews the plan without writing. Use when upgrading a project to the DesignContext graph and .design/map/*.md still holds the only structured design notes. Activates for requests involving migrating design maps, building the context graph from old notes, or DesignContext graph migration.
argument-hint	[--dry-run]
tools	Read, Write, Bash
user-invocable	true

{{command_prefix}}migrate-context

Closes the pre-graph gap: before Phase 52 a project recorded its structured design knowledge as flat .design/map/*.md mapper notes (token map, component taxonomy, motion map, a11y map, visual-hierarchy map). Phase 52 introduced the typed DesignContext graph at .design/context-graph.json. This skill carries a project across that boundary: it reads the old map notes, rebuilds the graph deterministically from source, validates it, and surfaces anything it could not transform with confidence so a human can confirm it. It never trusts a low-confidence guess silently.

Contracts: ../../reference/design-context-schema.md (the Node / Edge / Fragment / Graph shapes) and ../../reference/design-context-tag-vocab.md (the controlled tags[] vocabulary).

Invocation

Command	Behavior
{{command_prefix}}migrate-context	Run the full migration: read old maps, extract fragments, merge, validate, then report the low-confidence items for review.
{{command_prefix}}migrate-context --dry-run	Preview only. Print the migration plan and what each step would write, change nothing on disk.

Step 1 - Detect the pre-52 state

Read the project layout before touching anything.

1. List .design/map/*.md. These are the pre-52 mapper notes (for example token-map.md, component-taxonomy.md, motion-map.md, a11y-map.md, visual-hierarchy.md). If the directory is absent or empty, there is nothing to migrate: print No .design/map/*.md notes found; nothing to migrate. and stop.
2. Check whether .design/context-graph.json already exists. If it does, this is a re-run: keep the existing graph as a backup reference and report that the migration will rebuild it. Do not delete it.
3. In --dry-run, print the file list and the planned outputs (.design/fragments/<mapper>.json per mapper, then .design/context-graph.json) and stop before Step 2.

Step 2 - Rebuild fragments deterministically

The graph topology comes from the source tree, not from prose. Run each deterministic extractor over the configured source roots (default src/; read source_roots from .design/STATE.md if present). Each extractor is pure, dependency-free, and prints a schema-valid Fragment to stdout.

mkdir -p .design/fragments
for mapper in tokens components motion a11y visual-hierarchy; do
  node "${CLAUDE_PLUGIN_ROOT:-.}/scripts/lib/design-context/extract-${mapper}.mjs" src/ \
    > ".design/fragments/extract-${mapper}.json"
done

The extractors fill id / type / name / subtype / tags / complexity and every edge they can prove; they leave each node summary empty for the summary pass. Use the old .design/map/*.md notes as the source of the human-authored summary text and any tags the extractor could not infer: for each node whose name matches a map entry, copy that note's one-line description into the node summary and add any vocabulary tags it implies. This is the only place prose feeds the graph.

Step 3 - Merge into the canonical graph

Merge the fragments into the single graph. The merger dedupes nodes by id, unions tags, prefers a non-stub summary over the empty stub, and keeps an edge only when both endpoints resolve to a node in some fragment. Dropped dangling edges are reported on stderr as could-not-fix: lines.

node "${CLAUDE_PLUGIN_ROOT:-.}/scripts/lib/design-context/merge-fragments.mjs" \
  .design/fragments --out .design/context-graph.json

Capture the stderr could-not-fix: lines. Each one is a transform the merge could not complete (a map note referenced an entity the extractor never found in source). These are low-confidence items for Step 5, not silent drops.

Step 4 - Validate

Validate the merged graph. The validator checks structure, referential integrity (no dangling edges), unique ids, non-stub summaries (soft warning), and the controlled tag vocabulary (soft warning).

node "${CLAUDE_PLUGIN_ROOT:-.}/scripts/validate-design-context.cjs" .design/context-graph.json

Exit 0 is clean, 1 is warnings only (stub summaries or unknown tags to tidy later), 2 is a hard error (a dangling edge or duplicate id) that must be fixed before the graph is trusted. On exit 2, do not present the graph as migrated: report the errors and stop so a human can resolve them.

Step 5 - Flag low-confidence transforms

Collect everything that needs human eyes and present it as one review list rather than applying it:

• every could-not-fix: line from the merge (an unresolved or dropped edge);
• every node still carrying an empty summary after Step 2 (a map note had no matching entity, or no note existed);
• every validator WARN (stub summary, tag outside the controlled vocabulary).

Print the list with a clear heading and ask the user to confirm or correct each item. Do not auto-resolve a low-confidence transform: a wrong edge or a mislabeled node poisons every later graph query.

Step 6 - Deprecate the old map notes

The flat .design/map/*.md notes stay readable for one minor version so nothing breaks mid-upgrade. Add a one-line deprecation banner to the top of each migrated map note (do not delete the file):

> Deprecated: superseded by the DesignContext graph (.design/context-graph.json) as of Phase 52.
> Read-only for one minor version; regenerate the graph with {{command_prefix}}migrate-context.

In --dry-run, describe this banner instead of writing it. Announce that the next minor version may remove the .design/map/*.md notes, and that the graph is now the source of truth.

Do Not

• Do not trust a low-confidence transform silently. Every could-not-fix: line and every stub goes on the Step 5 review list.
• Do not delete .design/map/*.md. Add the deprecation banner and keep the notes for one minor version.
• Do not hand-edit .design/context-graph.json to force validation green. Fix the fragment or the source, then re-merge.
• Do not edit the extractors, the merger, or the validator. This skill only calls them.

MIGRATE-CONTEXT COMPLETE