@mmerterden/multi-agent-pipeline 11.2.0 → 11.3.1

package/pipeline/skills/figma-ios/figma-to-component/scripts/phase1-gather.py

@@ -1,1298 +0,0 @@
-#!/usr/bin/env python3
-"""
-Phase 1 Data Gathering Script
-Replaces the LLM subagent with deterministic Python calls.
-Expected runtime: ~5-15 seconds (vs ~20 minutes with subagent).
-
-Usage:
-    python3 phase1-gather.py \
-        --file-key "ps4xrJzhn7WNbfkZs895Bi" \
-        --node-id "9047:349" \
-        --artifact-path "path/to/ComponentName/" \
-        --component-name "AvatarPassengers" \
-        [--figma-token TOKEN] \
-        [--mcp-token TOKEN] \
-        [--mcp-url "http://127.0.0.1:3845/mcp"]
-
-Exit 0 = success (prints JSON summary to stdout)
-Exit 1 = failure (prints JSON error to stdout)
-"""
-
-import argparse
-import concurrent.futures
-import http.client
-import json
-import os
-import re
-import ssl
-import subprocess
-import sys
-import time
-from datetime import datetime
-from pathlib import Path
-from urllib.error import HTTPError, URLError
-from urllib.parse import urlparse
-from urllib.request import Request, urlopen
-
-# ─── Globals ─────────────────────────────────────────────────────────────────
-MCP_MODE = None       # "remote" or "local"
-MCP_URL = None        # local MCP URL (http://127.0.0.1:3845/mcp)
-MCP_TOKEN = None      # OAuth token for remote MCP
-SESSION_ID = None     # local MCP session ID
-FIGMA_TOKEN = None
-FILE_KEY = None
-NODE_ID = None
-COMPONENT_NAME = None
-ARTIFACT_PATH = None
-
-SUBLAYER_CAP = 20     # max sublayers to fetch for get_design_context
-
-
-def log(msg):
-    """Log to stderr so stdout stays clean for JSON output."""
-    print(f"[phase1] {msg}", file=sys.stderr)
-
-
-def halt(gate, reason, completed_gates, artifacts, user_action=""):
-    """Print HALT JSON and exit 1."""
-    print(json.dumps({
-        "status": "HALT",
-        "phase": "phase-1",
-        "gate": gate,
-        "reason": reason,
-        "completed_gates": completed_gates,
-        "artifacts_created": artifacts,
-        "user_action_required": user_action,
-    }, indent=2))
-    sys.exit(1)
-
-
-# ─── HTTP Helpers ────────────────────────────────────────────────────────────
-
-def figma_get(endpoint):
-    """GET from Figma REST API. Returns parsed JSON."""
-    url = f"https://api.figma.com/v1/{endpoint}"
-    req = Request(url, headers={"X-Figma-Token": FIGMA_TOKEN})
-    with urlopen(req, timeout=30) as resp:
-        return json.loads(resp.read().decode())
-
-
-def download_file(url, dest):
-    """Download a URL to a local file path. Returns True on success."""
-    try:
-        req = Request(url)
-        with urlopen(req, timeout=60) as resp:
-            Path(dest).parent.mkdir(parents=True, exist_ok=True)
-            with open(dest, "wb") as f:
-                f.write(resp.read())
-        return True
-    except (URLError, HTTPError) as exc:
-        log(f"Download failed ({dest}): {exc}")
-        return False
-
-
-# ─── MCP Token Resolution ────────────────────────────────────────────────────
-
-def get_mcp_token(cli_token=None):
-    """Resolve MCP OAuth token: CLI arg > Keychain FIGMA_MCP_TOKEN > Claude Code credentials."""
-    if cli_token:
-        return cli_token
-    # Keychain: dedicated entry
-    try:
-        token = subprocess.check_output(
-            ["security", "find-generic-password", "-a", os.environ["USER"],
-             "-s", "FIGMA_MCP_TOKEN", "-w"],
-            stderr=subprocess.DEVNULL,
-        ).decode().strip()
-        if token:
-            log("MCP token from Keychain: FIGMA_MCP_TOKEN")
-            return token
-    except (subprocess.CalledProcessError, KeyError):
-        pass
-    # Keychain: extract from Claude Code credentials
-    try:
-        raw = subprocess.check_output(
-            ["security", "find-generic-password", "-s", "Claude Code-credentials",
-             "-a", os.environ["USER"], "-w"],
-            stderr=subprocess.DEVNULL,
-        ).decode()
-        match = re.search(
-            r'"figma-remote\|[^"]+":\{[^}]*"accessToken":"([^"]+)"', raw
-        )
-        if match:
-            log("MCP token extracted from Claude Code credentials")
-            return match.group(1)
-    except (subprocess.CalledProcessError, KeyError):
-        pass
-    return None
-
-
-def _try_refresh_mcp_token():
-    """Attempt to refresh MCP token using stored refresh_token and fetch-mcp-token.py."""
-    global MCP_TOKEN
-    script = Path(__file__).parent.parent.parent / "figma-setup" / "scripts" / "fetch-mcp-token.py"
-    if not script.exists():
-        # Try relative to repo root
-        script = Path(__file__).resolve()
-        for _ in range(10):
-            script = script.parent
-            candidate = script / ".instructions" / "figma" / "figma-setup" / "scripts" / "fetch-mcp-token.py"
-            if candidate.exists():
-                script = candidate
-                break
-        else:
-            return False
-    try:
-        result = subprocess.run(
-            [sys.executable, str(script), "--verify", "--save-keychain", "--quiet"],
-            capture_output=True, text=True, timeout=30,
-        )
-        if result.returncode == 0 and result.stdout.strip():
-            MCP_TOKEN = result.stdout.strip()
-            log("MCP token auto-refreshed via fetch-mcp-token.py")
-            return True
-        else:
-            log(f"MCP token refresh failed (exit {result.returncode})")
-    except Exception as exc:
-        log(f"MCP token refresh error: {exc}")
-    return False
-
-
-# ─── MCP Helpers ─────────────────────────────────────────────────────────────
-
-def _parse_sse_json(raw):
-    """Parse JSON from SSE response. Handles multiline data payloads."""
-    # Find the "data: " prefix
-    data_start = raw.find("\ndata: ")
-    if data_start == -1:
-        data_start = raw.find("data: ")
-    if data_start == -1:
-        return None
-
-    json_str = raw[raw.index("data: ", data_start) + 6:].strip()
-    try:
-        return json.loads(json_str)
-    except json.JSONDecodeError:
-        # JSON may have trailing SSE noise  -  find balanced braces
-        depth = 0
-        end = 0
-        for i, ch in enumerate(json_str):
-            if ch == "{":
-                depth += 1
-            elif ch == "}":
-                depth -= 1
-                if depth == 0:
-                    end = i + 1
-                    break
-        if end > 0:
-            try:
-                return json.loads(json_str[:end])
-            except json.JSONDecodeError:
-                pass
-    return None
-
-
-def _mcp_post_local(body_dict):
-    """POST to local MCP (HTTP, session-based)."""
-    parsed = urlparse(MCP_URL)
-    conn = http.client.HTTPConnection(parsed.hostname, parsed.port, timeout=120)
-    headers = {
-        "Content-Type": "application/json",
-        "Accept": "application/json, text/event-stream",
-    }
-    if SESSION_ID:
-        headers["mcp-session-id"] = SESSION_ID
-
-    conn.request("POST", parsed.path, body=json.dumps(body_dict), headers=headers)
-    resp = conn.getresponse()
-    session = resp.getheader("mcp-session-id")
-    raw = resp.read().decode()
-    conn.close()
-
-    result_json = _parse_sse_json(raw)
-    return result_json, session
-
-
-def _mcp_post_remote(body_dict):
-    """POST to remote MCP (HTTPS, Bearer auth, stateless)."""
-    conn = http.client.HTTPSConnection("mcp.figma.com", timeout=120)
-    headers = {
-        "Content-Type": "application/json",
-        "Accept": "application/json, text/event-stream",
-        "Authorization": f"Bearer {MCP_TOKEN}",
-    }
-
-    conn.request("POST", "/mcp", body=json.dumps(body_dict), headers=headers)
-    resp = conn.getresponse()
-    raw = resp.read().decode()
-    conn.close()
-
-    if resp.status != 200:
-        raise RuntimeError(f"Remote MCP HTTP {resp.status}: {raw[:200]}")
-
-    result_json = _parse_sse_json(raw)
-    return result_json, None
-
-
-def _mcp_post(body_dict):
-    """Route to remote or local MCP based on MCP_MODE."""
-    if MCP_MODE == "remote":
-        return _mcp_post_remote(body_dict)
-    else:
-        return _mcp_post_local(body_dict)
-
-
-def mcp_init():
-    """Initialize MCP connection. Tries remote first, falls back to local."""
-    global MCP_MODE, MCP_TOKEN, SESSION_ID
-
-    init_body = {
-        "jsonrpc": "2.0",
-        "method": "initialize",
-        "params": {
-            "capabilities": {},
-            "clientInfo": {"name": "phase1-gather", "version": "1.0.0"},
-            "protocolVersion": "2025-03-26",
-        },
-        "id": 1,
-    }
-
-    # Try remote first
-    if MCP_TOKEN:
-        try:
-            log("MCP: trying remote (mcp.figma.com)...")
-            result, _ = _mcp_post_remote(init_body)
-            if result:
-                MCP_MODE = "remote"
-                log("MCP: remote connected")
-                return
-        except Exception as exc:
-            log(f"MCP: remote failed ({exc}), attempting token refresh...")
-            # Try auto-refresh before falling back to local
-            if _try_refresh_mcp_token():
-                try:
-                    result, _ = _mcp_post_remote(init_body)
-                    if result:
-                        MCP_MODE = "remote"
-                        log("MCP: remote connected (after token refresh)")
-                        return
-                except Exception as exc2:
-                    log(f"MCP: remote still failed after refresh ({exc2}), trying local...")
-
-    # Fall back to local
-    try:
-        log(f"MCP: trying local ({MCP_URL})...")
-        result, session = _mcp_post_local(init_body)
-        if session:
-            SESSION_ID = session
-            MCP_MODE = "local"
-            log(f"MCP: local connected (session: {SESSION_ID[:12]}...)")
-            return
-    except Exception as exc:
-        raise RuntimeError(f"MCP init failed  -  remote and local both unavailable. Local error: {exc}")
-
-    raise RuntimeError("MCP init failed  -  no session from local, no response from remote")
-
-
-_MCP_CALL_ID = 10  # auto-increment per call
-
-
-def mcp_call(tool_name, arguments):
-    """Call an MCP tool. Returns the text content from the result."""
-    global _MCP_CALL_ID
-    _MCP_CALL_ID += 1
-
-    # Remote MCP requires fileKey in every call
-    if MCP_MODE == "remote" and "fileKey" not in arguments:
-        arguments = {**arguments, "fileKey": FILE_KEY}
-
-    body = {
-        "jsonrpc": "2.0",
-        "method": "tools/call",
-        "params": {"name": tool_name, "arguments": arguments},
-        "id": _MCP_CALL_ID,
-    }
-    result_json, _ = _mcp_post(body)
-    if not result_json:
-        raise RuntimeError(f"MCP {tool_name}: empty response")
-    if "error" in result_json:
-        raise RuntimeError(f"MCP {tool_name}: {result_json['error']}")
-
-    # Extract text from content array
-    content_items = (result_json.get("result") or {}).get("content", [])
-    texts = [item.get("text", "") for item in content_items if item.get("type") == "text"]
-    return "\n".join(texts)
-
-
-# ─── Batch 1: Parallel Fetchers ─────────────────────────────────────────────
-
-def fetch_screenshot_url():
-    """Figma REST -> screenshot image URL."""
-    log("REST: fetching screenshot URL...")
-    data = figma_get(f"images/{FILE_KEY}?ids={NODE_ID}&format=png&scale=2")
-    url = (data.get("images") or {}).get(NODE_ID)
-    if not url:
-        raise RuntimeError("No screenshot URL returned from images API")
-    log("REST: screenshot URL obtained")
-    return url
-
-
-def fetch_node_data():
-    """Figma REST -> full node document (for component properties + variants)."""
-    log("REST: fetching node data...")
-    data = figma_get(f"files/{FILE_KEY}/nodes?ids={NODE_ID}")
-    node = (data.get("nodes") or {}).get(NODE_ID, {}).get("document")
-    if not node:
-        raise RuntimeError("No document in nodes response")
-    log(f"REST: node type={node.get('type')}")
-    return node
-
-
-def fetch_metadata():
-    log("MCP: get_metadata...")
-    text = mcp_call("get_metadata", {
-        "nodeId": NODE_ID,
-        "clientLanguages": "swift",
-        "clientFrameworks": "swiftui",
-    })
-    log(f"MCP: metadata {len(text)} chars")
-    return text
-
-
-def _is_too_large_response(text):
-    """Check if MCP returned XML metadata instead of code (design too large)."""
-    return "too large" in text.lower() and "<frame" in text[:300]
-
-
-def _parse_sublayer_ids(text):
-    """Extract sublayer node IDs from the XML metadata response."""
-    # Match <symbol id="X:Y" ...> or <frame id="X:Y" ...> (children only)
-    ids = re.findall(r'<(?:symbol|frame)\s+id="([^"]+)"', text)
-    # Skip the root frame (first match is the container itself)
-    root_match = re.search(r'<frame\s+id="([^"]+)"', text)
-    root_id = root_match.group(1) if root_match else None
-    return [nid for nid in ids if nid != root_id]
-
-
-def _build_design_context_args(node_id, assets_dir=None):
-    """Build arguments for get_design_context. Skips dirForAssetWrites on remote."""
-    args = {
-        "nodeId": node_id,
-        "clientLanguages": "swift",
-        "clientFrameworks": "swiftui",
-        # Disable Code Connect in design context  -  when Code Connect is enabled,
-        # the returned snippets override the original Tailwind reference code we
-        # need for layout/style extraction. We fetch Code Connect separately
-        # via get_code_connect_map.
-        "disableCodeConnect": True,
-    }
-    if assets_dir and MCP_MODE == "local":
-        args["dirForAssetWrites"] = assets_dir
-    return args
-
-
-def _fetch_sublayer_context(node_id, assets_dir, depth=0):
-    """Fetch design context for a single sublayer. Recurses if also too large."""
-    if depth > 3:
-        log(f"  sublayer {node_id}: max recursion depth, returning raw")
-        return {"nodeId": node_id, "error": "max_recursion_depth"}
-
-    text = mcp_call("get_design_context", _build_design_context_args(node_id, assets_dir))
-
-    if _is_too_large_response(text):
-        log(f"  sublayer {node_id}: also too large, splitting further (depth={depth+1})")
-        child_ids = _parse_sublayer_ids(text)
-        if not child_ids:
-            return {"nodeId": node_id, "response": text}
-        child_responses = {}
-        for cid in child_ids:
-            child_responses[cid] = _fetch_sublayer_context(cid, assets_dir, depth + 1)
-        return {"nodeId": node_id, "sublayers": True, "responses": child_responses}
-
-    log(f"  sublayer {node_id}: {len(text)} chars")
-    return {"nodeId": node_id, "response": text}
-
-
-def _fetch_sublayers_parallel(sublayer_ids, assets_dir, max_workers=10):
-    """Fetch all sublayer design contexts in parallel using a thread pool."""
-    results = {}
-    with concurrent.futures.ThreadPoolExecutor(max_workers=max_workers) as pool:
-        future_to_sid = {
-            pool.submit(_fetch_sublayer_context, sid, assets_dir): sid
-            for sid in sublayer_ids
-        }
-        for future in concurrent.futures.as_completed(future_to_sid):
-            sid = future_to_sid[future]
-            try:
-                results[sid] = future.result()
-            except Exception as e:
-                log(f"  sublayer {sid}: ERROR {e}")
-                results[sid] = {"nodeId": sid, "error": str(e)}
-    return results
-
-
-def fetch_design_context():
-    assets_dir = str((Path(ARTIFACT_PATH) / "pass1" / "assets").resolve())
-    Path(assets_dir).mkdir(parents=True, exist_ok=True)
-
-    log("MCP: get_design_context...")
-    text = mcp_call("get_design_context", _build_design_context_args(NODE_ID, assets_dir))
-    log(f"MCP: design_context {len(text)} chars")
-
-    if _is_too_large_response(text):
-        sublayer_ids = _parse_sublayer_ids(text)
-
-        # Cap check: if too many sublayers, defer to manual resolution
-        if len(sublayer_ids) > SUBLAYER_CAP:
-            log(f"MCP: {len(sublayer_ids)} sublayers exceeds cap ({SUBLAYER_CAP})  -  deferring")
-            return {
-                "__deferred": True,
-                "__sublayer_count": len(sublayer_ids),
-                "__sublayer_ids": sublayer_ids,
-                "__metadata_xml": text,
-                "__cap": SUBLAYER_CAP,
-            }
-
-        log(f"MCP: design too large  -  fetching {len(sublayer_ids)} sublayers in parallel")
-        if sublayer_ids:
-            sublayer_responses = _fetch_sublayers_parallel(sublayer_ids, assets_dir)
-            total = sum(
-                len(r.get("response", "")) for r in sublayer_responses.values()
-                if isinstance(r, dict) and "response" in r
-            )
-            log(f"MCP: sublayer design_context total {total} chars across {len(sublayer_ids)} sublayers")
-            return {
-                "__sublayers": True,
-                "__sublayer_ids": sublayer_ids,
-                "__metadata_xml": text,
-                "__responses": sublayer_responses,
-            }
-
-    return text
-
-
-def fetch_variable_defs():
-    log("MCP: get_variable_defs...")
-    text = mcp_call("get_variable_defs", {
-        "nodeId": NODE_ID,
-        "clientLanguages": "swift",
-        "clientFrameworks": "swiftui",
-    })
-    log(f"MCP: variable_defs {len(text)} chars")
-    return text
-
-
-def fetch_code_connect_map():
-    log("MCP: get_code_connect_map...")
-    # Filter by SwiftUI label  -  without this, MCP returns all platforms
-    # (e.g. Compose) and we get Android snippets instead of iOS ones.
-    text = mcp_call("get_code_connect_map", {
-        "nodeId": NODE_ID,
-        "codeConnectLabel": "SwiftUI",
-    })
-    log(f"MCP: code_connect_map {len(text)} chars")
-    return text
-
-
-# ─── Batch 2: Downloads & Post-Processing ───────────────────────────────────
-
-def download_screenshot(screenshot_url):
-    dest = str(Path(ARTIFACT_PATH) / "pass1" / "screenshot.png")
-    log("Downloading screenshot PNG...")
-    if not download_file(screenshot_url, dest):
-        raise RuntimeError("Screenshot PNG download failed")
-    log("Screenshot saved")
-    return dest
-
-
-def download_variant_screenshots(node_data):
-    """Batch-download variant screenshots. Returns list of variant info dicts."""
-    if node_data.get("type") != "COMPONENT_SET":
-        log("Not COMPONENT_SET -- skipping variants")
-        return []
-
-    children = [c for c in node_data.get("children", []) if c.get("type") == "COMPONENT"]
-    if not children:
-        log("No COMPONENT children found")
-        return []
-
-    log(f"Found {len(children)} variants -- batch fetching image URLs...")
-
-    # Single batch API call for all variant IDs
-    all_ids = ",".join(c["id"] for c in children)
-    data = figma_get(f"images/{FILE_KEY}?ids={all_ids}&format=png&scale=2")
-    image_urls = data.get("images") or {}
-
-    screenshots_dir = Path(ARTIFACT_PATH) / "pass1" / "screenshots"
-    screenshots_dir.mkdir(parents=True, exist_ok=True)
-
-    # Build download list
-    downloads = []
-    for child in children:
-        url = image_urls.get(child["id"])
-        if not url:
-            continue
-        name = child.get("name", child["id"])
-        # Single-property: "State=Success" -> "Success"
-        # Multi-property: "Size=Large, Loyalty Type=Classic" -> "Size=Large_LoyaltyType=Classic"
-        parts = [p.strip() for p in name.split(",")]
-        if len(parts) == 1 and "=" in parts[0]:
-            safe = parts[0].split("=", 1)[1].strip()
-        else:
-            # "Size=Large, Loyalty Type=Classic Plus" -> "Size=Large_LoyaltyType=Classic_Plus"
-            formatted = []
-            for p in parts:
-                if "=" in p:
-                    k, v = p.split("=", 1)
-                    k = k.strip().replace(" ", "")       # remove spaces in key
-                    v = v.strip().replace(" ", "_")       # spaces -> underscores in value
-                    formatted.append(f"{k}={v}")
-                else:
-                    formatted.append(p.replace(" ", ""))
-            safe = "_".join(formatted)
-        safe = re.sub(r"[/\\:]", "_", safe)
-        downloads.append({
-            "id": child["id"],
-            "name": name,
-            "safe_name": safe,
-            "file": f"{safe}.png",
-            "url": url,
-            "dest": str(screenshots_dir / f"{safe}.png"),
-        })
-
-    # Parallel download
-    results = []
-    with concurrent.futures.ThreadPoolExecutor(max_workers=10) as pool:
-        futs = {pool.submit(download_file, d["url"], d["dest"]): d for d in downloads}
-        for fut in concurrent.futures.as_completed(futs):
-            info = futs[fut]
-            if fut.result():
-                results.append(info)
-                log(f"  variant: {info['safe_name']}")
-
-    # Write variants.md
-    results.sort(key=lambda x: x["name"])
-    lines = [
-        "# Variant Screenshots\n",
-        "| Variant | Node ID | File |",
-        "|---------|---------|------|",
-    ]
-    for r in results:
-        lines.append(f"| {r['name']} | {r['id']} | {r['file']} |")
-    lines += ["", "## Usage", "- Confluence documentation", "- Snapshot testing reference", ""]
-    (screenshots_dir / "variants.md").write_text("\n".join(lines))
-
-    log(f"Downloaded {len(results)}/{len(downloads)} variant screenshots")
-    return results
-
-
-def sanitize_svgs():
-    """Remove Xcode-incompatible attributes from downloaded SVGs."""
-    assets_dir = Path(ARTIFACT_PATH) / "pass1" / "assets"
-    if not assets_dir.exists():
-        return 0
-
-    count = 0
-    for svg in assets_dir.glob("*.svg"):
-        content = svg.read_text()
-        original = content
-        content = re.sub(r' width="100%"', "", content)
-        content = re.sub(r' height="100%"', "", content)
-        content = re.sub(r' preserveAspectRatio="none"', "", content)
-        content = re.sub(r' style="display: block;"', "", content)
-        content = re.sub(r' overflow="visible"', "", content)
-        content = re.sub(r"var\(--fill-0, ([^)]*)\)", r"\1", content)
-        content = re.sub(r"var\(--stroke-0, ([^)]*)\)", r"\1", content)
-        if content != original:
-            svg.write_text(content)
-            count += 1
-    if count:
-        log(f"Sanitized {count} SVGs")
-    return count
-
-
-# ─── File Writers ────────────────────────────────────────────────────────────
-
-def save_mcp_text(filename, text, try_json=True):
-    """Write MCP text output to a file in pass1/."""
-    dest = Path(ARTIFACT_PATH) / "pass1" / filename
-    if try_json:
-        try:
-            parsed = json.loads(text)
-            dest.write_text(json.dumps(parsed, indent=2, ensure_ascii=False) + "\n")
-            return
-        except (json.JSONDecodeError, TypeError):
-            pass
-    dest.write_text(text)
-
-
-def write_design_context_deferred(data):
-    """Write deferred artifact when sublayer count exceeds cap."""
-    pass1 = Path(ARTIFACT_PATH) / "pass1"
-
-    # Write design_context_response.json with metadata XML only
-    envelope = {
-        "rootNodeId": NODE_ID,
-        "source": MCP_MODE,
-        "deferred": True,
-        "sublayers": True,
-        "sublayerCount": data["__sublayer_count"],
-        "cap": data["__cap"],
-        "sublayerNodeIds": data["__sublayer_ids"],
-        "metadataXml": data["__metadata_xml"],
-        "responses": {},
-    }
-    (pass1 / "design_context_response.json").write_text(
-        json.dumps(envelope, indent=2, ensure_ascii=False) + "\n"
-    )
-
-    # Write design_context_deferred.json  -  resolution instructions
-    cmd_template = (
-        f"python3 .instructions/figma/figma-to-swiftui/scripts/phase1-gather.py "
-        f"--fetch-deferred "
-        f"--file-key {FILE_KEY} "
-        f"--node-id {NODE_ID} "
-        f"--artifact-path {ARTIFACT_PATH} "
-        f"--component-name {COMPONENT_NAME} "
-        f"--sublayer-ids \"{{comma_separated_ids}}\""
-    )
-    deferred = {
-        "status": "deferred",
-        "reason": "sublayer_count_exceeds_cap",
-        "sublayerCount": data["__sublayer_count"],
-        "cap": data["__cap"],
-        "sublayerIds": data["__sublayer_ids"],
-        "fileKey": FILE_KEY,
-        "rootNodeId": NODE_ID,
-        "instruction": (
-            "Design context has too many sublayers to fetch automatically. "
-            "Use --fetch-deferred mode with selected sublayer IDs to resolve."
-        ),
-        "commandTemplate": cmd_template,
-    }
-    (pass1 / "design_context_deferred.json").write_text(
-        json.dumps(deferred, indent=2, ensure_ascii=False) + "\n"
-    )
-    log(f"design_context_deferred.json written ({data['__sublayer_count']} sublayers)")
-
-
-def write_design_context_file(data):
-    """Save design context -- handles normal text, sublayer dict, and deferred."""
-    dest = Path(ARTIFACT_PATH) / "pass1" / "design_context_response.json"
-
-    # Deferred case: sublayer count exceeded cap
-    if isinstance(data, dict) and data.get("__deferred"):
-        write_design_context_deferred(data)
-        return
-
-    # Sublayer case: data is a dict with __sublayers=True
-    if isinstance(data, dict) and data.get("__sublayers"):
-        sublayer_ids = data["__sublayer_ids"]
-        responses = {}
-        for sid, resp in data["__responses"].items():
-            if isinstance(resp, dict) and "response" in resp:
-                responses[sid] = resp["response"]
-            else:
-                responses[sid] = resp  # nested sublayer or error
-        envelope = {
-            "rootNodeId": NODE_ID,
-            "source": MCP_MODE,
-            "sublayers": True,
-            "sublayerNodeIds": sublayer_ids,
-            "responses": responses,
-        }
-        dest.write_text(json.dumps(envelope, indent=2, ensure_ascii=False) + "\n")
-        return
-
-    # Normal case: data is a text string
-    text = data
-    try:
-        parsed = json.loads(text)
-        dest.write_text(json.dumps(parsed, indent=2, ensure_ascii=False) + "\n")
-    except (json.JSONDecodeError, TypeError):
-        envelope = {
-            "rootNodeId": NODE_ID,
-            "source": MCP_MODE,
-            "sublayers": False,
-            "response": text,
-        }
-        dest.write_text(json.dumps(envelope, indent=2, ensure_ascii=False) + "\n")
-
-
-def write_design_context_assets():
-    """List downloaded assets in design_context_assets.txt."""
-    dest = Path(ARTIFACT_PATH) / "pass1" / "design_context_assets.txt"
-    assets_dir = Path(ARTIFACT_PATH) / "pass1" / "assets"
-    files = sorted(assets_dir.glob("*")) if assets_dir.exists() else []
-    files = [f for f in files if f.is_file()]
-
-    if files:
-        lines = [
-            "# Asset References from Design Context",
-            f"# {len(files)} assets downloaded by MCP",
-            "",
-        ]
-        for f in files:
-            lines.append(f"{f.name} | local:{f}")
-    else:
-        lines = [
-            "# Asset References from Design Context",
-            "# No assets referenced in design context response.",
-        ]
-    dest.write_text("\n".join(lines) + "\n")
-    return len(files)
-
-
-def write_screenshot_response():
-    dest = Path(ARTIFACT_PATH) / "pass1" / "screenshot_response.md"
-    today = datetime.now().strftime("%Y-%m-%d")
-    dest.write_text(
-        f"# Screenshot Response\n\n"
-        f"## Screenshot File\n"
-        f"- File: screenshot.png\n"
-        f"- Node ID: {NODE_ID}\n"
-        f"- Source: local\n"
-        f"- Scale: 2x\n"
-        f"- Timestamp: {today}\n"
-    )
-
-
-def generate_component_properties(node_data):
-    """Build component_properties.json from the REST API node document."""
-    node_type = node_data.get("type", "UNKNOWN")
-    is_component = node_type in ("COMPONENT", "COMPONENT_SET")
-    prop_defs = node_data.get("componentPropertyDefinitions") or {}
-
-    variants_list = []
-    boolean_props = []
-    text_slots = []
-    nested_comps = []
-    cc_mappings = {}
-
-    for key, defn in prop_defs.items():
-        ptype = defn.get("type")
-        # Display name: "Text#6893:1" -> "Text",  "\u21aa Left Icon#13152:11" -> "\u21aa Left Icon"
-        display = key.split("#")[0]
-        clean = display.lstrip("\u21aa ").strip()
-
-        if ptype == "VARIANT":
-            values = defn.get("variantOptions", [])
-            variants_list.append({"property": display, "values": values, "type": "VARIANT"})
-            if values:
-                pairs = ", ".join(
-                    f'"{v}": .{v.lower().replace(" ", "")}' for v in values
-                )
-                cc_mappings[key] = f'@FigmaEnum("{display}", mapping: [{pairs}])'
-
-        elif ptype == "BOOLEAN":
-            boolean_props.append({
-                "property": clean,
-                "default": defn.get("defaultValue", False),
-                "figmaKey": key,
-            })
-            cc_mappings[key] = f'@FigmaBoolean("{clean}")'
-
-        elif ptype == "TEXT":
-            text_slots.append({
-                "name": clean,
-                "defaultValue": defn.get("defaultValue", ""),
-                "figmaKey": key,
-            })
-            cc_mappings[key] = f'@FigmaString("{clean}")'
-
-        elif ptype == "INSTANCE_SWAP":
-            nested_comps.append({
-                "name": clean,
-                "nodeId": defn.get("defaultValue", ""),
-                "figmaKey": key,
-                "type": "INSTANCE_SWAP",
-            })
-            cc_mappings[key] = f'@FigmaInstance("{display}")'
-
-    result = {
-        "componentName": COMPONENT_NAME,
-        "nodeId": NODE_ID,
-        "nodeType": node_type,
-        "isComponent": is_component,
-        "componentPropertyDefinitions": prop_defs,
-        "variants": variants_list,
-        "booleanProperties": boolean_props,
-        "textSlots": text_slots,
-        "nestedComponents": nested_comps,
-        "codeConnectStrategy": {
-            "isComponent": is_component,
-            "hasPropertyDefinitions": bool(prop_defs),
-            "mappings": cc_mappings,
-        },
-    }
-    dest = Path(ARTIFACT_PATH) / "pass1" / "component_properties.json"
-    dest.write_text(json.dumps(result, indent=2, ensure_ascii=False) + "\n")
-    log("component_properties.json written")
-    return result
-
-
-def write_component_summary(comp_props, node_data):
-    """Condensed summary (~100 lines) for downstream phases."""
-    prop_defs = comp_props.get("componentPropertyDefinitions") or {}
-    properties = []
-    for key, defn in prop_defs.items():
-        ptype = defn.get("type")
-        name = key.split("#")[0].lstrip("\u21aa ").strip()
-        prop = {"name": name, "type": ptype, "figmaKey": key, "default": defn.get("defaultValue")}
-        if ptype == "VARIANT":
-            prop["values"] = defn.get("variantOptions", [])
-        properties.append(prop)
-
-    children = node_data.get("children", [])
-    variant_count = len([c for c in children if c.get("type") == "COMPONENT"])
-    bbox = node_data.get("absoluteBoundingBox") or {}
-
-    assets_dir = Path(ARTIFACT_PATH) / "pass1" / "assets"
-    svgs = sorted(assets_dir.glob("*.svg")) if assets_dir.exists() else []
-    screenshots_dir = Path(ARTIFACT_PATH) / "pass1" / "screenshots"
-    pngs = sorted(screenshots_dir.glob("*.png")) if screenshots_dir.exists() else []
-
-    ntype = node_data.get("type", "UNKNOWN")
-    layer_line = (
-        f"{ntype} > COMPONENT({variant_count} variants)"
-        if variant_count
-        else ntype
-    )
-
-    summary = {
-        "componentName": COMPONENT_NAME,
-        "nodeId": NODE_ID,
-        "fileKey": FILE_KEY,
-        "nodeType": ntype,
-        "variantCount": variant_count,
-        "dimensions": {"width": bbox.get("width", 0), "height": bbox.get("height", 0)},
-        "properties": properties,
-        "layerSummary": [layer_line],
-        "variableBindingCount": 0,
-        "variableBindingSummary": [],
-        "assets": {
-            "svgCount": len(svgs),
-            "screenshotCount": len(pngs),
-            "fileList": [s.name for s in svgs],
-        },
-        "hasExistingCodeConnect": False,
-    }
-
-    dest = Path(ARTIFACT_PATH) / "pass1" / "component_summary.json"
-    dest.write_text(json.dumps(summary, indent=2, ensure_ascii=False) + "\n")
-    log("component_summary.json written")
-    return summary
-
-
-def write_index(variant_results, asset_count):
-    today = datetime.now().strftime("%Y-%m-%d")
-    screenshots_dir = Path(ARTIFACT_PATH) / "pass1" / "screenshots"
-    var_count = len(list(screenshots_dir.glob("*.png"))) if screenshots_dir.exists() else 0
-    assets_dir = Path(ARTIFACT_PATH) / "pass1" / "assets"
-    svg_count = len(list(assets_dir.glob("*.svg"))) if assets_dir.exists() else 0
-
-    content = f"""# Pass 1 -- Data Gathering Output
-
-Component: {COMPONENT_NAME}
-Node ID: {NODE_ID}
-File Key: {FILE_KEY}
-Gathered: {today}
-
-## Files
-
-| File | Description |
-|------|-------------|
-| `pass1/screenshot.png` | Component screenshot (2x scale) |
-| `pass1/screenshot_response.md` | Screenshot metadata |
-| `pass1/screenshots/` | Variant screenshots ({var_count} variants) |
-| `pass1/screenshots/variants.md` | Variant screenshot index |
-| `pass1/metadata_response.xml` | Layer hierarchy (XML) |
-| `pass1/design_context_response.json` | Generated code + structure |
-| `pass1/design_context_assets.txt` | Asset download URLs ({svg_count} vectors) |
-| `pass1/assets/` | Downloaded SVG assets (sanitized for Xcode) |
-| `pass1/variable_defs_response.json` | Design tokens / variables |
-| `pass1/component_properties.json` | Variant properties, booleans, text slots, Code Connect strategy |
-| `pass1/code_connect_map_response.json` | Existing Code Connect mappings |
-| `pass1/component_summary.json` | **Condensed summary -- read this FIRST** |
-
-## Read Instructions
-
-**All downstream phases: read `component_summary.json` FIRST.** It contains a condensed view of the component's properties, structure, and assets in ~100 lines. Only read raw artifacts (design_context_response.json, etc.) if you need detail the summary does not provide.
-
-- Phase 2A (Testing Identifiers): `component_summary.json`, then `design_context_response.json` if needed, `component_properties.json`
-- Phase 2B (Localization): `component_summary.json`, then `design_context_response.json` if needed, `component_properties.json`
-- Phase 2C (Accessibility): `component_summary.json`, then `screenshot_response.md`, `design_context_response.json` if needed
-- Phase 2D (Analytics): `component_summary.json`, then `design_context_response.json` if needed
-- Phase 3 sub-phases: `component_summary.json` FIRST, then phase-specific raw artifacts as needed
-- Phase 4 sub-phases: `component_summary.json` for cross-reference, pass3/ analysis files as primary input
-"""
-    (Path(ARTIFACT_PATH) / "pass1" / "_index.md").write_text(content)
-    log("_index.md written")
-
-
-def update_implementation_history(variant_count, svg_count):
-    hist = Path(ARTIFACT_PATH) / "IMPLEMENTATION_HISTORY.md"
-    if not hist.exists():
-        log("WARNING: IMPLEMENTATION_HISTORY.md not found -- skipping update")
-        return
-
-    text = hist.read_text()
-
-    phase1_block = f"""
-## Phase 1 Data
-- Screenshot: pass1/screenshot_response.md
-- Screenshot PNG: pass1/screenshot.png
-- Metadata: pass1/metadata_response.xml
-- Design Context: pass1/design_context_response.json
-- Design Assets: pass1/design_context_assets.txt
-- Variable Defs: pass1/variable_defs_response.json
-- Component Properties: pass1/component_properties.json (for Code Connect)
-- Code Connect: pass1/code_connect_map_response.json
-- Assets: pass1/assets/ (SVGs sanitized)
-- Variant Screenshots: pass1/screenshots/ ({variant_count} variants)
-- Component Summary: pass1/component_summary.json
-"""
-
-    if "## Phase 1 Data" in text:
-        text = re.sub(r"\n## Phase 1 Data.*?(?=\n## |\Z)", "", text, flags=re.DOTALL)
-
-    text = text.rstrip() + "\n" + phase1_block
-    hist.write_text(text)
-    log("IMPLEMENTATION_HISTORY.md updated")
-
-
-# ─── Deferred Resolution ─────────────────────────────────────────────────────
-
-def fetch_deferred(sublayer_ids):
-    """Fetch design context for selected sublayer IDs and merge into standard format."""
-    t0 = time.time()
-    log(f"Deferred resolution: fetching {len(sublayer_ids)} sublayers...")
-
-    pass1 = Path(ARTIFACT_PATH) / "pass1"
-    assets_dir = str((pass1 / "assets").resolve())
-    Path(assets_dir).mkdir(parents=True, exist_ok=True)
-
-    # Read existing deferred JSON to get all sublayer IDs
-    deferred_path = pass1 / "design_context_deferred.json"
-    if deferred_path.exists():
-        deferred = json.loads(deferred_path.read_text())
-        all_sublayer_ids = deferred.get("sublayerIds", [])
-    else:
-        all_sublayer_ids = sublayer_ids
-
-    # Fetch each sublayer in parallel (reuses existing infrastructure)
-    sublayer_responses = _fetch_sublayers_parallel(sublayer_ids, assets_dir)
-
-    # Build responses dict (text only, same format as normal sublayer path)
-    responses = {}
-    for sid, resp in sublayer_responses.items():
-        if isinstance(resp, dict) and "response" in resp:
-            responses[sid] = resp["response"]
-        elif isinstance(resp, dict) and "error" in resp:
-            responses[sid] = f"<!-- Error: {resp['error']} -->"
-            log(f"  WARNING: sublayer {sid} had error: {resp['error']}")
-        else:
-            responses[sid] = str(resp)
-
-    # Build merged design_context_response.json  -  same format as non-deferred
-    envelope = {
-        "rootNodeId": NODE_ID,
-        "source": MCP_MODE,
-        "sublayers": True,
-        "representativeSelection": True,
-        "sublayerNodeIds": all_sublayer_ids,
-        "selectedNodeIds": sublayer_ids,
-        "responses": responses,
-        # Flat concatenated response for Phase 2 NORMALIZE_DESIGN_CONTEXT compatibility
-        "response": "\n\n".join(
-            f"// --- Sublayer: {sid} ---\n{text}"
-            for sid, text in responses.items()
-            if not text.startswith("<!-- Error")
-        ),
-    }
-
-    dest = pass1 / "design_context_response.json"
-    dest.write_text(json.dumps(envelope, indent=2, ensure_ascii=False) + "\n")
-    log(f"design_context_response.json written ({len(responses)} sublayers, {len(envelope['response'])} chars)")
-
-    # Update component_summary.json
-    summary_path = pass1 / "component_summary.json"
-    if summary_path.exists():
-        summary = json.loads(summary_path.read_text())
-        summary["designContextStatus"] = "representative"
-        summary["selectedSublayerCount"] = len(sublayer_ids)
-        summary_path.write_text(json.dumps(summary, indent=2, ensure_ascii=False) + "\n")
-        log("component_summary.json updated with designContextStatus")
-
-    # Sanitize any new SVGs
-    sanitize_svgs()
-
-    # Update asset list
-    write_design_context_assets()
-
-    duration = time.time() - t0
-    log(f"=== DEFERRED COMPLETE in {duration:.1f}s (MCP: {MCP_MODE}) ===")
-
-    result = {
-        "status": "COMPLETE",
-        "phase": "phase-1-deferred",
-        "mcpMode": MCP_MODE,
-        "sublayersFetched": len(sublayer_ids),
-        "sublayersSucceeded": len([v for v in responses.values() if not v.startswith("<!-- Error")]),
-        "responseChars": len(envelope["response"]),
-        "duration_seconds": round(duration, 1),
-    }
-    print(json.dumps(result, indent=2))
-    sys.exit(0)
-
-
-# ─── Main ────────────────────────────────────────────────────────────────────
-
-def main():
-    global MCP_URL, MCP_TOKEN, FIGMA_TOKEN, FILE_KEY, NODE_ID, COMPONENT_NAME, ARTIFACT_PATH
-
-    parser = argparse.ArgumentParser(description="Phase 1 -- Data Gathering")
-    parser.add_argument("--file-key", required=True)
-    parser.add_argument("--node-id", required=True, help="colon-separated, e.g. 6893:6879")
-    parser.add_argument("--artifact-path", required=True)
-    parser.add_argument("--component-name", required=True)
-    parser.add_argument("--figma-token", help="REST API token (falls back to macOS Keychain)")
-    parser.add_argument("--mcp-token", help="MCP OAuth token (falls back to Keychain/Claude Code creds)")
-    parser.add_argument("--mcp-url", default="http://127.0.0.1:3845/mcp")
-    parser.add_argument("--fetch-deferred", action="store_true",
-                        help="Deferred resolution mode: fetch design context for selected sublayer IDs")
-    parser.add_argument("--sublayer-ids", help="Comma-separated sublayer node IDs (requires --fetch-deferred)")
-    args = parser.parse_args()
-
-    FILE_KEY = args.file_key
-    NODE_ID = args.node_id
-    COMPONENT_NAME = args.component_name
-    ARTIFACT_PATH = args.artifact_path
-    MCP_URL = args.mcp_url
-
-    # ─── Deferred Resolution Mode ───
-    if args.fetch_deferred:
-        if not args.sublayer_ids:
-            halt("PRE_CHECK", "--fetch-deferred requires --sublayer-ids", [], [],
-                 "Pass comma-separated sublayer node IDs: --sublayer-ids 'id1,id2,id3'")
-        sublayer_ids = [sid.strip() for sid in args.sublayer_ids.split(",") if sid.strip()]
-        if not sublayer_ids:
-            halt("PRE_CHECK", "No valid sublayer IDs provided", [], [],
-                 "Pass comma-separated sublayer node IDs: --sublayer-ids 'id1,id2,id3'")
-        # Need MCP token for fetching
-        MCP_TOKEN = get_mcp_token(args.mcp_token)
-        try:
-            mcp_init()
-        except Exception as exc:
-            halt("PRE_CHECK", f"MCP init failed: {exc}", [], [],
-                 "Ensure Figma Desktop is running or run /figma-setup for remote MCP")
-        fetch_deferred(sublayer_ids)
-        return  # fetch_deferred calls sys.exit(0)
-
-    # Resolve Figma REST API token
-    FIGMA_TOKEN = args.figma_token
-    if not FIGMA_TOKEN:
-        try:
-            FIGMA_TOKEN = subprocess.check_output(
-                ["security", "find-generic-password", "-a", os.environ["USER"],
-                 "-s", "FIGMA_ACCESS_TOKEN", "-w"],
-                stderr=subprocess.DEVNULL,
-            ).decode().strip()
-        except (subprocess.CalledProcessError, KeyError):
-            halt("PRE_CHECK", "FIGMA_ACCESS_TOKEN not found", [], [],
-                 "Pass --figma-token or: "$HOME/.claude/lib/credential-store.sh" set \1 \2
-
-    # Resolve MCP OAuth token (for remote MCP)
-    MCP_TOKEN = get_mcp_token(args.mcp_token)
-
-    t0 = time.time()
-    log(f"Phase 1: {COMPONENT_NAME}  node={NODE_ID}  file={FILE_KEY}")
-
-    # Ensure directories
-    pass1 = Path(ARTIFACT_PATH) / "pass1"
-    pass1.mkdir(parents=True, exist_ok=True)
-    (pass1 / "assets").mkdir(exist_ok=True)
-    (pass1 / "screenshots").mkdir(exist_ok=True)
-
-    gates = ["PRE_CHECK"]
-    artifacts = []
-
-    # -- MCP Init (remote first, local fallback) --
-    try:
-        mcp_init()
-    except Exception as exc:
-        halt("PRE_CHECK", f"MCP init failed: {exc}", [], [],
-             "Ensure Figma Desktop is running or run /figma-setup for remote MCP")
-
-    # -- Batch 1: parallel data fetching --
-    log("=== Batch 1: parallel data fetching ===")
-    b1 = {}
-    b1_err = {}
-
-    with concurrent.futures.ThreadPoolExecutor(max_workers=6) as pool:
-        jobs = {
-            pool.submit(fetch_screenshot_url): "screenshot_url",
-            pool.submit(fetch_node_data): "node_data",
-            pool.submit(fetch_metadata): "metadata",
-            pool.submit(fetch_design_context): "design_context",
-            pool.submit(fetch_variable_defs): "variable_defs",
-            pool.submit(fetch_code_connect_map): "code_connect_map",
-        }
-        for fut in concurrent.futures.as_completed(jobs):
-            key = jobs[fut]
-            try:
-                b1[key] = fut.result()
-            except Exception as exc:
-                b1_err[key] = str(exc)
-                log(f"  ERROR {key}: {exc}")
-
-    # Critical checks
-    if "screenshot_url" in b1_err:
-        halt("SCREENSHOT", b1_err["screenshot_url"], gates, artifacts,
-             "Check FIGMA_ACCESS_TOKEN and node ID")
-    if "node_data" in b1_err:
-        halt("COMPONENT_PROPERTIES", b1_err["node_data"], gates, artifacts,
-             "Check FIGMA_ACCESS_TOKEN and node ID")
-
-    # -- Batch 2: downloads + processing --
-    log("=== Batch 2: downloads & processing ===")
-
-    # Screenshot
-    try:
-        download_screenshot(b1["screenshot_url"])
-        gates.append("SCREENSHOT")
-        artifacts.append("pass1/screenshot.png")
-    except Exception as exc:
-        halt("SCREENSHOT", str(exc), gates, artifacts)
-
-    write_screenshot_response()
-    artifacts.append("pass1/screenshot_response.md")
-
-    # Variant screenshots
-    node_data = b1["node_data"]
-    try:
-        variant_results = download_variant_screenshots(node_data)
-        gates.append("VARIANT_SCREENSHOTS")
-        if variant_results:
-            artifacts.extend(["pass1/screenshots/", "pass1/screenshots/variants.md"])
-    except Exception as exc:
-        log(f"WARNING: variant screenshots failed: {exc}")
-        variant_results = []
-        gates.append("VARIANT_SCREENSHOTS")
-
-    # Metadata
-    if "metadata" in b1:
-        save_mcp_text("metadata_response.xml", b1["metadata"], try_json=False)
-        gates.append("METADATA")
-        artifacts.append("pass1/metadata_response.xml")
-    elif "metadata" in b1_err:
-        (pass1 / "metadata_response.xml").write_text(f"<!-- Error: {b1_err['metadata']} -->\n")
-        gates.append("METADATA")
-        artifacts.append("pass1/metadata_response.xml")
-
-    # Design context
-    design_context_deferred = False
-    if "design_context" in b1:
-        dc_data = b1["design_context"]
-        write_design_context_file(dc_data)
-        gates.append("DESIGN_CONTEXT")
-        artifacts.append("pass1/design_context_response.json")
-        if isinstance(dc_data, dict) and dc_data.get("__deferred"):
-            design_context_deferred = True
-            artifacts.append("pass1/design_context_deferred.json")
-    elif "design_context" in b1_err:
-        halt("DESIGN_CONTEXT", b1_err["design_context"], gates, artifacts,
-             "Check Figma connection and node ID")
-
-    # Sanitize SVGs
-    sanitize_svgs()
-    gates.append("SANITIZE_SVGS")
-
-    # Asset list
-    asset_count = write_design_context_assets()
-    artifacts.append("pass1/design_context_assets.txt")
-
-    # Variable defs
-    if "variable_defs" in b1:
-        save_mcp_text("variable_defs_response.json", b1["variable_defs"])
-    else:
-        # REST API fallback (requires Enterprise plan  -  may 403)
-        log("MCP variable_defs failed  -  trying REST API fallback...")
-        try:
-            rest_vars = figma_get(f"files/{FILE_KEY}/variables/local")
-            (pass1 / "variable_defs_response.json").write_text(
-                json.dumps(rest_vars, indent=2, ensure_ascii=False) + "\n"
-            )
-            log("REST API variable_defs fallback succeeded")
-        except HTTPError as exc:
-            if exc.code == 403:
-                log("REST API variable_defs: 403 (requires Enterprise plan)  -  skipping")
-            else:
-                log(f"REST API variable_defs fallback failed: {exc}")
-            (pass1 / "variable_defs_response.json").write_text(json.dumps({
-                "error": "variable_defs_unavailable",
-                "source": "none",
-                "note": "Variable definitions could not be retrieved. MCP unavailable, REST API returned 403 (Enterprise plan required).",
-            }, indent=2) + "\n")
-        except Exception as exc:
-            log(f"REST API variable_defs fallback failed: {exc}")
-            (pass1 / "variable_defs_response.json").write_text(json.dumps({
-                "error": "variable_defs_unavailable",
-                "source": "none",
-                "note": f"Variable definitions could not be retrieved via MCP or REST API: {exc}",
-            }, indent=2) + "\n")
-    gates.append("VARIABLE_DEFS")
-    artifacts.append("pass1/variable_defs_response.json")
-
-    # Component properties
-    comp_props = generate_component_properties(node_data)
-    gates.append("COMPONENT_PROPERTIES")
-    artifacts.append("pass1/component_properties.json")
-
-    # Code connect map
-    if "code_connect_map" in b1:
-        save_mcp_text("code_connect_map_response.json", b1["code_connect_map"])
-    else:
-        (pass1 / "code_connect_map_response.json").write_text("{}\n")
-    gates.append("CODE_CONNECT_MAP")
-    artifacts.append("pass1/code_connect_map_response.json")
-
-    # -- Finalize --
-    log("=== Finalize ===")
-
-    write_component_summary(comp_props, node_data)
-    artifacts.append("pass1/component_summary.json")
-
-    write_index(variant_results, asset_count)
-    artifacts.append("pass1/_index.md")
-
-    update_implementation_history(
-        len(variant_results),
-        len(list((pass1 / "assets").glob("*.svg"))) if (pass1 / "assets").exists() else 0,
-    )
-
-    gates.append("FINALIZE")
-    duration = time.time() - t0
-
-    # -- Success --
-    status = "COMPLETE_WITH_DEFERRED" if design_context_deferred else "COMPLETE"
-    log(f"=== {status} in {duration:.1f}s (MCP: {MCP_MODE}) ===")
-    summary = {
-        "status": status,
-        "phase": "phase-1",
-        "mcpMode": MCP_MODE,
-        "gates_passed": gates,
-        "artifacts_created": artifacts,
-        "duration_seconds": round(duration, 1),
-    }
-    if design_context_deferred:
-        summary["deferred"] = {
-            "artifact": "pass1/design_context_deferred.json",
-            "reason": "sublayer_count_exceeds_cap",
-        }
-    print(json.dumps(summary, indent=2))
-    sys.exit(0)
-
-
-if __name__ == "__main__":
-    main()