@mmerterden/multi-agent-pipeline 8.6.0

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

@@ -0,0 +1,1089 @@
+#!/usr/bin/env python3
+"""Phase 3 scriptable sub-phases: 3B (tokens), 3E (assets), 3F (utilities), 3G (coverage).
+
+Usage:
+    python3 phase3-scripts.py 3b --artifact-path /path/to/artifacts
+    python3 phase3-scripts.py 3e --artifact-path /path/to/artifacts
+    python3 phase3-scripts.py 3f --artifact-path /path/to/artifacts
+    python3 phase3-scripts.py 3g --artifact-path /path/to/artifacts
+    python3 phase3-scripts.py wave1 --artifact-path /path/to/artifacts  # runs 3b+3e+3f
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import subprocess
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Optional
+
+# --- Constants ---
+
+SCRIPT_DIR = Path(__file__).parent
+REPO_ROOT = SCRIPT_DIR.parent.parent.parent.parent  # .instructions/figma/figma-to-swiftui/scripts -> repo root
+CONFIG_PKG = REPO_ROOT / "{repos.packagesContainer}" / "Packages" / "{project.slug}-common"
+CLI_BINARY = CONFIG_PKG / ".build" / "debug" / "FigmaRegistryUtility"
+ASSET_CATALOG_ROOT = CONFIG_PKG / "iOS" / "Sources" / "UIAssets" / "Generated" / "Resources" / "Images"
+
+ISO_DATE = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+DATE_SHORT = datetime.now(timezone.utc).strftime("%Y-%m-%d")
+
+
+# --- CLI helpers ---
+
+def run_cli(command: str, args: list[str]) -> dict | None:
+    """Run FigmaRegistryUtility command from config package dir."""
+    cmd = [str(CLI_BINARY), command] + args
+    try:
+        result = subprocess.run(
+            cmd, capture_output=True, text=True, timeout=30,
+            cwd=str(CONFIG_PKG)
+        )
+        if result.returncode == 0 and result.stdout.strip():
+            return json.loads(result.stdout)
+    except (subprocess.TimeoutExpired, json.JSONDecodeError, FileNotFoundError) as e:
+        print(f"  [warn] CLI {command} failed: {e}", file=sys.stderr)
+    return None
+
+
+def ensure_cli():
+    """Build CLI if binary doesn't exist."""
+    if not CLI_BINARY.exists():
+        print("  Building FigmaRegistryUtility...", file=sys.stderr)
+        subprocess.run(
+            ["swift", "build", "--product", "FigmaRegistryUtility"],
+            cwd=str(CONFIG_PKG), capture_output=True, timeout=120
+        )
+
+
+# --- 3B: Token Mapping ---
+
+def classify_variable(name: str, value: str) -> str | None:
+    """Classify a variable_defs entry by type."""
+    if value.startswith("#") and len(value) in (4, 7, 9):
+        return "color"
+    if value.startswith("Font("):
+        return "typography_composite"
+    if name.startswith("Font/") or name.startswith("[TBD]Font/"):
+        return "font_primitive"
+    if name.startswith("Spacing/"):
+        return "spacing"
+    if name.startswith("Radius/"):
+        return "radius"
+    # Try to parse as number
+    try:
+        float(value)
+        return "number"
+    except ValueError:
+        pass
+    # String values (font family names etc)
+    if not value.startswith("{") and not value.startswith("["):
+        return "font_family"
+    return None
+
+
+def run_3b(artifact_path: str) -> bool:
+    """Phase 3B: Variable Token Mapping."""
+    print("Phase 3B: Token Mapping")
+    ap = Path(artifact_path)
+
+    # Read inputs
+    var_defs_path = ap / "pass1" / "variable_defs_response.json"
+    if not var_defs_path.exists():
+        print("  [error] variable_defs_response.json not found", file=sys.stderr)
+        return False
+
+    with open(var_defs_path) as f:
+        var_defs = json.load(f)
+
+    # Get component name from component_properties.json
+    comp_name = "(from artifacts)"
+    comp_props_path = ap / "pass1" / "component_properties.json"
+    if comp_props_path.exists():
+        with open(comp_props_path) as f:
+            comp_name = json.load(f).get("componentName", comp_name)
+
+    # Classify variables
+    colors, spacings, radii, font_prims, typo_composites, font_families = [], [], [], [], [], []
+    lookup_vars = []
+
+    for name, value in var_defs.items():
+        vtype = classify_variable(name, value)
+        if vtype == "color":
+            colors.append(name)
+            lookup_vars.append(name)
+        elif vtype == "spacing":
+            spacings.append(name)
+            lookup_vars.append(name)
+        elif vtype == "radius":
+            radii.append(name)
+            lookup_vars.append(name)
+        elif vtype == "number":
+            lookup_vars.append(name)
+        elif vtype == "typography_composite":
+            typo_composites.append(name)
+        elif vtype == "font_primitive":
+            font_prims.append(name)
+            lookup_vars.append(name)
+        elif vtype == "font_family":
+            font_families.append(name)
+
+    # Batch CLI lookup for all non-composite variables
+    token_map = {}
+    if lookup_vars:
+        result = run_cli("ui-token-lookup", ["--variables", ",".join(lookup_vars), "--json"])
+        if result:
+            token_map = result
+
+    # Typography lookup for composite styles — pass the raw Figma variable names
+    # through untransformed. Resolution is the CLI's job, not ours.
+    typo_map = {}
+    if typo_composites:
+        result = run_cli("typography-lookup", ["--styles", ",".join(typo_composites), "--json"])
+        if result:
+            typo_map = result
+
+    # Build output sections
+    lines = [
+        f"# Token Mapping\n",
+        f"Component: {comp_name}",
+        f"Generated: {ISO_DATE}",
+        f"Source: pass1/variable_defs_response.json, pass1/design_context_response.json\n",
+    ]
+
+    # Typography section
+    lines.append("## Typography\n")
+    typo_count = 0
+    lines.append("| Figma Style | Token Type | Swift Modifier | Swift Font |")
+    lines.append("|-------------|------------|----------------|------------|")
+    for tc_name in typo_composites:
+        entry = typo_map.get(tc_name)
+        if entry and entry.get("status") == "found":
+            swift_token = entry["swiftToken"]  # e.g. ".smallBold"
+            lines.append(f"| {tc_name} | typography | `.typographyStyle({swift_token})` | `Font{swift_token}` |")
+            typo_count += 1
+        else:
+            lines.append(f"| {tc_name} | typography | ⚠️ not found | ⚠️ not found |")
+    if not typo_composites:
+        lines.append("| (none) | — | — | — |")
+    lines.append("")
+
+    # Colors section
+    lines.append("## Colors\n")
+    lines.append("| Figma Variable | Token Type | Swift Usage |")
+    lines.append("|----------------|------------|-------------|")
+    color_count = 0
+    for var_name in colors:
+        token = token_map.get(var_name)
+        if token:
+            # token format: "color:.Text.textSuccess"
+            type_prefix, swift_path = token.split(":", 1)
+            lines.append(f"| {var_name} | {type_prefix} | `Color{swift_path}` |")
+            color_count += 1
+        else:
+            lines.append(f"| {var_name} | color | ⚠️ not found |")
+    if not colors:
+        lines.append("| (none) | — | — |")
+    lines.append("")
+
+    # Spacing section
+    lines.append("## Spacing\n")
+    lines.append("| Figma Variable | Token Type | Swift Token |")
+    lines.append("|----------------|------------|-------------|")
+    spacing_count = 0
+    for var_name in spacings:
+        token = token_map.get(var_name)
+        if token:
+            type_prefix, swift_path = token.split(":", 1)
+            lines.append(f"| {var_name} | {type_prefix} | `{swift_path}` |")
+            spacing_count += 1
+        else:
+            lines.append(f"| {var_name} | number | ⚠️ not found |")
+    if not spacings:
+        lines.append("| (none) | — | — |")
+    lines.append("")
+
+    # Radius section
+    lines.append("## Radius\n")
+    lines.append("| Figma Variable | Token Type | Swift Token |")
+    lines.append("|----------------|------------|-------------|")
+    radius_count = 0
+    for var_name in radii:
+        token = token_map.get(var_name)
+        if token:
+            type_prefix, swift_path = token.split(":", 1)
+            lines.append(f"| {var_name} | {type_prefix} | `{swift_path}` |")
+            radius_count += 1
+        else:
+            lines.append(f"| {var_name} | number | ⚠️ not found |")
+    if not radii:
+        lines.append("| (none) | — | — |")
+    lines.append("")
+
+    # Images section
+    lines.append("## Images / Icons\n")
+    lines.append("None detected in variable definitions.\n")
+
+    # Font primitives section
+    if font_prims:
+        lines.append("## Font Primitives (Sub-tokens)\n")
+        lines.append("These are typography sub-properties. Not used directly — encapsulated by composite typography tokens above.\n")
+        lines.append("| Figma Variable | Token Type | Swift Token | Note |")
+        lines.append("|----------------|------------|-------------|------|")
+        for var_name in font_prims:
+            token = token_map.get(var_name)
+            if token:
+                type_prefix, swift_path = token.split(":", 1)
+                lines.append(f"| {var_name} | {type_prefix} | `{swift_path}` | Font primitive (use composite token instead) |")
+            else:
+                lines.append(f"| {var_name} | — | N/A | Font primitive — not a standalone token |")
+        lines.append("")
+
+    # Font families
+    if font_families:
+        lines.append("## Font Families\n")
+        for name in font_families:
+            lines.append(f"- `{name}`: \"{var_defs[name]}\" — font family reference, not a standalone token\n")
+
+    # Missing tokens — exclude font primitives and font families (encapsulated by composite)
+    missing = []
+    for var_name in lookup_vars:
+        token = token_map.get(var_name)
+        if token is None:
+            vtype = classify_variable(var_name, var_defs[var_name])
+            # Font family refs and font primitives are encapsulated by composite typography
+            if vtype in ("font_family", "font_primitive"):
+                continue
+            missing.append((var_name, vtype or "unknown"))
+    for tc_name in typo_composites:
+        entry = typo_map.get(tc_name)
+        if not entry or entry.get("status") != "found":
+            missing.append((tc_name, "typography"))
+
+    # Font primitives/families that returned null are NOT missing — they're encapsulated
+    font_null_note = []
+    for var_name in lookup_vars:
+        token = token_map.get(var_name)
+        if token is None:
+            vtype = classify_variable(var_name, var_defs[var_name])
+            if vtype in ("font_family", "font_primitive"):
+                font_null_note.append((var_name, vtype))
+
+    lines.append("## Missing Tokens\n")
+    if missing:
+        lines.append("| Token | Type | Resolution |")
+        lines.append("|-------|------|------------|")
+        for name, ttype in missing:
+            lines.append(f"| {name} | {ttype} | See reference/missing-tokens.md |")
+    else:
+        if font_null_note:
+            lines.append(f"All tokens resolved. ({len(font_null_note)} font primitive/family references excluded — encapsulated by composite typography token.)\n")
+        else:
+            lines.append("All tokens resolved.\n")
+
+    # Summary
+    mapped_prims = sum(1 for v in font_prims if token_map.get(v) is not None)
+    actionable_missing = [m for m in missing if m[1] != "font_family"]
+
+    lines.append("## Summary\n")
+    lines.append(f"- Typography: {typo_count} mapped")
+    lines.append(f"- Colors: {color_count} mapped")
+    lines.append(f"- Spacing: {spacing_count} mapped")
+    lines.append(f"- Radius: {radius_count} mapped")
+    lines.append(f"- Images: 0 mapped")
+    if font_prims:
+        lines.append(f"- Font Primitives: {mapped_prims} mapped (sub-tokens of typography)")
+    lines.append(f"- Missing: {len(actionable_missing)} actionable")
+
+    # Write
+    os.makedirs(ap / "pass3", exist_ok=True)
+    out_path = ap / "pass3" / "02_token_mapping.md"
+    with open(out_path, "w") as f:
+        f.write("\n".join(lines) + "\n")
+
+    print(f"  ✅ {out_path} ({typo_count + color_count + spacing_count + radius_count} tokens mapped, {len(actionable_missing)} missing)")
+    return True
+
+
+# --- 3E: Asset Inventory ---
+
+def parse_asset_filename(filename: str) -> str:
+    """Try to identify an asset from its filename (hash or named)."""
+    # Strip extension
+    stem = Path(filename).stem
+    # If it's a hex hash, we need to inspect SVG content or check code_connect_map
+    if re.match(r'^[a-f0-9]{30,}$', stem):
+        return stem  # hash-named, needs further resolution
+    return stem
+
+
+def run_3e(artifact_path: str) -> bool:
+    """Phase 3E: Asset Inventory."""
+    print("Phase 3E: Asset Inventory")
+    ap = Path(artifact_path)
+
+    assets_txt = ap / "pass1" / "design_context_assets.txt"
+    if not assets_txt.exists() or assets_txt.stat().st_size == 0:
+        # Write placeholder
+        os.makedirs(ap / "pass3", exist_ok=True)
+        out_path = ap / "pass3" / "06_assets.md"
+        with open(out_path, "w") as f:
+            f.write(f"# Asset Inventory\n\nNo downloadable assets found for this component.\nGenerated: {ISO_DATE}\n")
+        print(f"  ⏭️  No assets — placeholder written")
+        return True
+
+    # Parse asset entries
+    assets = []
+    with open(assets_txt) as f:
+        for line in f:
+            line = line.strip()
+            if not line or line.startswith("#"):
+                continue
+            # Format: "filename | url" or "filename | local:path"
+            parts = line.split("|", 1)
+            filename = parts[0].strip()
+            url = parts[1].strip() if len(parts) > 1 else ""
+            assets.append({"filename": filename, "url": url})
+
+    if not assets:
+        os.makedirs(ap / "pass3", exist_ok=True)
+        out_path = ap / "pass3" / "06_assets.md"
+        with open(out_path, "w") as f:
+            f.write(f"# Asset Inventory\n\nNo downloadable assets found for this component.\nGenerated: {ISO_DATE}\n")
+        print(f"  ⏭️  No assets — placeholder written")
+        return True
+
+    # Try to identify assets via code_connect_map (for icon names)
+    # Icon entries have snippet like "Image.plusCircle" with empty source
+    icon_names = set()
+    ccm_path = ap / "pass1" / "code_connect_map_response.json"
+    if ccm_path.exists():
+        with open(ccm_path) as f:
+            ccm = json.load(f)
+        for entry in ccm.values():
+            # Check componentName field
+            name = entry.get("componentName", "")
+            if name.startswith("Image."):
+                icon_names.add(name.replace("Image.", ""))
+            # Also check snippet field for "Image.xxx" patterns (icon entries use this)
+            snippet = entry.get("snippet", "")
+            m = re.match(r'^Image\.(\w+)$', snippet.strip())
+            if m:
+                icon_names.add(m.group(1))
+
+    # Check each asset against registry and catalog
+    results = []
+    for asset in assets:
+        filename = asset["filename"]
+        stem = parse_asset_filename(filename)
+        ext = Path(filename).suffix.lstrip(".")
+
+        # Check SVG content for icon identification (if local file exists)
+        local_path = asset["url"].replace("local:", "") if asset["url"].startswith("local:") else None
+        svg_identified_name = None
+
+        # Try registry lookup for known icon names from code_connect_map
+        status = "Unknown"
+        target = "N/A"
+        identified_name = stem
+        swift_accessor = None
+
+        for icon_name in icon_names:
+            lookup = run_cli("ui-token-lookup", ["--variables", icon_name, "--json"])
+            if lookup:
+                val = lookup.get(icon_name)
+                if val and val.startswith("image:"):
+                    swift_path = val.split(":", 1)[1]
+                    identified_name = icon_name
+                    swift_accessor = f"Image{swift_path}"
+                    status = "Existing"
+                    break
+
+        # Also search asset catalog directly if hash-named
+        if status == "Unknown" and re.match(r'^[a-f0-9]{30,}$', stem):
+            # Check if any icon from code_connect_map exists in catalog
+            for icon_name in icon_names:
+                # Convert camelCase to kebab-case for catalog search
+                kebab = re.sub(r'([A-Z])', r'-\1', icon_name).lower().lstrip("-")
+                matches = list(ASSET_CATALOG_ROOT.rglob(f"*{kebab}*")) if ASSET_CATALOG_ROOT.exists() else []
+                if matches:
+                    identified_name = kebab
+                    status = "Existing"
+                    target = str(matches[0].relative_to(CONFIG_PKG))
+                    break
+
+        results.append({
+            "filename": filename,
+            "ext": ext,
+            "identified_name": identified_name,
+            "status": status,
+            "target": target,
+            "swift_accessor": swift_accessor,
+        })
+
+    # Write output
+    new_count = sum(1 for r in results if r["status"] == "New")
+    existing_count = sum(1 for r in results if r["status"] == "Existing")
+    unknown_count = sum(1 for r in results if r["status"] == "Unknown")
+
+    lines = [
+        f"# Asset Inventory\n",
+        f"Generated: {ISO_DATE}",
+        f"Source: pass1/design_context_assets.txt\n",
+        "## Assets\n",
+        "| File | Type | Identified As | Status | Swift Accessor |",
+        "|------|------|---------------|--------|----------------|",
+    ]
+
+    for r in results:
+        accessor = r["swift_accessor"] or "—"
+        lines.append(f"| {r['filename']} | {r['ext']} | {r['identified_name']} | {r['status']} | `{accessor}` |" if r["swift_accessor"] else
+                     f"| {r['filename']} | {r['ext']} | {r['identified_name']} | {r['status']} | — |")
+
+    lines.extend([
+        "",
+        "## Summary\n",
+        f"- Total assets: {len(results)}",
+        f"- New (to add): {new_count}",
+        f"- Existing (no action): {existing_count}",
+        f"- Unknown (check manually): {unknown_count}",
+    ])
+
+    if new_count > 0:
+        lines.extend(["", "## Action Items\n"])
+        for r in results:
+            if r["status"] == "New":
+                lines.append(f"- [ ] Add `{r['identified_name']}` to asset catalog")
+
+    if new_count == 0:
+        lines.extend(["", "## Action Items\n", "No new assets need to be added."])
+
+    os.makedirs(ap / "pass3", exist_ok=True)
+    out_path = ap / "pass3" / "06_assets.md"
+    with open(out_path, "w") as f:
+        f.write("\n".join(lines) + "\n")
+
+    print(f"  ✅ {out_path} ({new_count} new, {existing_count} existing, {unknown_count} unknown)")
+    return True
+
+
+# --- 3F: Utility Integration ---
+
+def run_3f(artifact_path: str) -> bool:
+    """Phase 3F: Utility Integration Summary."""
+    print("Phase 3F: Utility Integration")
+    ap = Path(artifact_path)
+
+    # Primary source: component-utilities.json (structured, from Phase 2)
+    utils_json = ap / "pass2" / "component-utilities.json"
+    if not utils_json.exists():
+        print(f"  [error] pass2/component-utilities.json not found", file=sys.stderr)
+        return False
+
+    with open(utils_json) as f:
+        utils = json.load(f)
+
+    component_name = utils.get("componentName", "Unknown")
+    if isinstance(component_name, dict):
+        component_name = component_name.get("ios", "Unknown")
+
+    testing_ids = utils.get("testingIdentifiers", [])
+    loc_keys = utils.get("localizationKeys", [])
+    a11y_keys = utils.get("accessibilityKeys", [])
+    analytics = utils.get("analyticsEvents", [])
+
+    # Build element-to-utility mapping table
+    # Collect all unique elements from all utility categories
+    elements = {}  # element_name -> {testing, localization, accessibility, analytics}
+
+    for tid in testing_ids:
+        key = tid.get("key", "")
+        elem = tid.get("usage", key.split(".")[-1] if "." in key else key)
+        if elem not in elements:
+            elements[elem] = {"testing": None, "localization": None, "accessibility": None, "analytics": None}
+        elements[elem]["testing"] = f"`.{key}`"
+
+    for lk in loc_keys:
+        key = lk.get("key", "")
+        elem = lk.get("usage", key.split(".")[-1] if "." in key else key)
+        if elem not in elements:
+            elements[elem] = {"testing": None, "localization": None, "accessibility": None, "analytics": None}
+        elements[elem]["localization"] = f"`.{key}`"
+
+    for ak in a11y_keys:
+        key = ak.get("key", "")
+        elem = ak.get("usage", ak.get("purpose", key.split(".")[-1] if "." in key else key))
+        if elem not in elements:
+            elements[elem] = {"testing": None, "localization": None, "accessibility": None, "analytics": None}
+        elements[elem]["accessibility"] = f"`.{key}`"
+
+    for ae in analytics:
+        elem = ae.get("element", "unknown")
+        if elem not in elements:
+            elements[elem] = {"testing": None, "localization": None, "accessibility": None, "analytics": None}
+        elements[elem]["analytics"] = ae.get("event", "—")
+
+    lines = [
+        f"# Utility Integration\n",
+        f"Component: {component_name}",
+        f"Generated: {ISO_DATE}",
+        f"Source: pass2/component-utilities.json\n",
+    ]
+
+    # Element mapping table
+    if elements:
+        lines.append("## Element-to-Utility Mapping\n")
+        lines.append("| Element | Testing ID | Localization Key | Accessibility | Analytics |")
+        lines.append("|---------|------------|------------------|---------------|-----------|")
+        for elem, utils_map in elements.items():
+            t = utils_map["testing"] or "—"
+            l = utils_map["localization"] or "—"
+            a = utils_map["accessibility"] or "—"
+            an = utils_map["analytics"] or "—"
+            lines.append(f"| {elem} | {t} | {l} | {a} | {an} |")
+        lines.append("")
+
+    # Testing Identifiers
+    lines.append("## Testing Identifiers\n")
+    if testing_ids:
+        lines.append("| Key | Value | Usage |")
+        lines.append("|-----|-------|-------|")
+        for tid in testing_ids:
+            lines.append(f"| {tid.get('key', '')} | {tid.get('value', '')} | `.accessibilityIdentifier(.{tid.get('key', '')})` |")
+    else:
+        lines.append("No testing identifiers.")
+    lines.append("")
+
+    # Localization Keys
+    lines.append("## Localization Keys\n")
+    if loc_keys:
+        lines.append("| Key | Pattern |")
+        lines.append("|-----|---------|")
+        for lk in loc_keys:
+            lines.append(f"| {lk.get('key', '')} | {lk.get('pattern', '')} |")
+    else:
+        lines.append("No localization keys (dynamic text only).")
+    lines.append("")
+
+    # Accessibility
+    lines.append("## Accessibility\n")
+    if a11y_keys:
+        lines.append("| Key | Purpose |")
+        lines.append("|-----|---------|")
+        for ak in a11y_keys:
+            lines.append(f"| {ak.get('key', '')} | {ak.get('purpose', '')} |")
+    else:
+        lines.append("No dedicated keys — using runtime accessibility patterns.")
+    lines.append("")
+
+    # Analytics
+    lines.append("## Analytics Events\n")
+    if analytics:
+        lines.append("| Element | Event | Identifier Key |")
+        lines.append("|---------|-------|----------------|")
+        for ae in analytics:
+            lines.append(f"| {ae.get('element', '')} | {ae.get('event', '')} | {ae.get('identifierKey', '')} |")
+    else:
+        lines.append("No analytics events (no interactive elements).")
+    lines.append("")
+
+    # Summary
+    lines.append("## Summary\n")
+    lines.append("| Category | Count |")
+    lines.append("|----------|-------|")
+    lines.append(f"| Testing Identifiers | {len(testing_ids)} |")
+    lines.append(f"| Localization Keys | {len(loc_keys)} |")
+    lines.append(f"| Accessibility Keys | {len(a11y_keys)} |")
+    lines.append(f"| Analytics Events | {len(analytics)} |")
+
+    os.makedirs(ap / "pass3", exist_ok=True)
+    out_path = ap / "pass3" / "08_utility_integration.md"
+    with open(out_path, "w") as f:
+        f.write("\n".join(lines) + "\n")
+
+    print(f"  ✅ {out_path} ({len(testing_ids)} testing, {len(loc_keys)} loc, {len(a11y_keys)} a11y, {len(analytics)} analytics)")
+    return True
+
+
+# --- 3G: Property Coverage ---
+
+def run_3g(artifact_path: str) -> bool:
+    """Phase 3G: Property Coverage Verification."""
+    print("Phase 3G: Property Coverage")
+    ap = Path(artifact_path)
+
+    # Read component_properties.json (Phase 1 output)
+    comp_props_path = ap / "pass1" / "component_properties.json"
+    if not comp_props_path.exists():
+        print(f"  [error] component_properties.json not found", file=sys.stderr)
+        return False
+
+    with open(comp_props_path) as f:
+        comp_props = json.load(f)
+
+    # Read 3D's structured JSON output
+    arch_json_path = ap / "pass3" / "04b_component_architecture.json"
+    if not arch_json_path.exists():
+        print(f"  [error] 04b_component_architecture.json not found (3D must emit this)", file=sys.stderr)
+        return False
+
+    with open(arch_json_path) as f:
+        arch = json.load(f)
+
+    # Extract all Figma properties
+    prop_defs = comp_props.get("componentPropertyDefinitions", {})
+    arch_props = {p["figmaKey"]: p for p in arch.get("properties", [])}
+
+    component_name = comp_props.get("componentName", "Unknown")
+
+    # Match each Figma property against architecture
+    properties = []
+    unmapped = []
+
+    for figma_key, figma_def in prop_defs.items():
+        prop_type = figma_def.get("type", "UNKNOWN")
+        # Clean display name from figma_key (remove #nodeId suffix)
+        display_name = re.sub(r'#\d+:\d+$', '', figma_key).strip()
+        # Remove leading arrow for instance swaps
+        display_name_clean = display_name.lstrip("↪ ").strip()
+
+        if figma_key in arch_props:
+            ap_entry = arch_props[figma_key]
+            properties.append({
+                "name": display_name,
+                "type": prop_type,
+                "figmaKey": figma_key,
+                "status": ap_entry.get("status", "IMPLEMENT"),
+                "swiftType": ap_entry.get("swiftType"),
+                "reason": ap_entry.get("reason"),
+            })
+        else:
+            # Not found in architecture — unmapped
+            unmapped.append({
+                "name": display_name,
+                "type": prop_type,
+                "figmaKey": figma_key,
+            })
+
+    # Include LAYER_TEXT entries from architecture (dynamic layer texts not in Figma properties)
+    for arch_prop in arch.get("properties", []):
+        if arch_prop.get("type") == "LAYER_TEXT" and arch_prop.get("status") == "IMPLEMENT":
+            properties.append({
+                "name": arch_prop["name"],
+                "type": "LAYER_TEXT",
+                "figmaKey": None,
+                "status": "IMPLEMENT",
+                "swiftType": arch_prop.get("swiftType"),
+                "reason": None,
+            })
+
+    # Counts
+    implemented = sum(1 for p in properties if p["status"] == "IMPLEMENT")
+    skipped = sum(1 for p in properties if p["status"] == "SKIP")
+    deferred = sum(1 for p in properties if p["status"] == "DEFER")
+    total = len(properties)
+
+    # Validate
+    if unmapped:
+        print(f"  [error] {len(unmapped)} unmapped properties:", file=sys.stderr)
+        for u in unmapped:
+            print(f"    - {u['name']} ({u['type']}): {u['figmaKey']}", file=sys.stderr)
+        # Still write the file but include unmapped
+
+    # Validate SKIP/DEFER have reasons
+    missing_reasons = [p for p in properties if p["status"] in ("SKIP", "DEFER") and not p.get("reason")]
+    if missing_reasons:
+        print(f"  [warn] {len(missing_reasons)} SKIP/DEFER properties missing reasons", file=sys.stderr)
+
+    # Write output
+    output = {
+        "componentName": component_name,
+        "generated": DATE_SHORT,
+        "totalProperties": total,
+        "implemented": implemented,
+        "skipped": skipped,
+        "deferred": deferred,
+        "properties": properties,
+        "unmapped": unmapped,
+    }
+
+    os.makedirs(ap / "pass3", exist_ok=True)
+    out_path = ap / "pass3" / "00_property_coverage.json"
+    with open(out_path, "w") as f:
+        json.dump(output, f, indent=2, ensure_ascii=False)
+
+    status = "✅" if not unmapped else "⚠️"
+    print(f"  {status} {out_path} ({implemented} implement, {skipped} skip, {deferred} defer, {len(unmapped)} unmapped)")
+    return len(unmapped) == 0
+
+
+# --- spec: Implementation Spec Compilation ---
+
+def extract_md_value(filepath: Path, field: str) -> str:
+    """Extract a value from a markdown table row like '| Field | Value |'."""
+    if not filepath.exists():
+        return ""
+    with open(filepath) as f:
+        for line in f:
+            if f"| {field} |" in line or f"| {field.lower()} |" in line.lower():
+                parts = [p.strip() for p in line.split("|")]
+                if len(parts) >= 3:
+                    return parts[2]
+    return ""
+
+
+def extract_md_section_lines(filepath: Path, heading: str) -> list[str]:
+    """Extract lines under a markdown ## heading until next heading."""
+    if not filepath.exists():
+        return []
+    lines = []
+    in_section = False
+    with open(filepath) as f:
+        for line in f:
+            if line.startswith("## ") and heading.lower() in line.lower():
+                in_section = True
+                continue
+            elif line.startswith("## ") and in_section:
+                break
+            elif in_section:
+                lines.append(line.rstrip())
+    return lines
+
+
+def generate_api_shape_code(arch: dict) -> str:
+    """Generate Swift API shape code from architecture JSON."""
+    lines = []
+    lines.append("```swift")
+
+    # Enums
+    for enum in arch.get("enums", []):
+        cases = ", ".join(f".{c}" for c in enum["cases"])
+        lines.append(f"public enum {enum['name']}: String, CaseIterable, Sendable {{")
+        for case in enum["cases"]:
+            lines.append(f"    case {case}")
+        lines.append("}")
+        lines.append("")
+
+    # Configuration struct (if COMPLEX)
+    api = arch.get("apiDesign", {})
+    config = api.get("configurationStruct")
+    if config:
+        lines.append(f"public struct {config['name']}: Sendable {{")
+        for prop in config.get("properties", []):
+            lines.append(f"    public let {prop['name']}: {prop['swiftType']}")
+        lines.append("")
+        # Init
+        init_params = []
+        for prop in config.get("properties", []):
+            default = prop.get("default")
+            if default:
+                init_params.append(f"        {prop['name']}: {prop['swiftType']} = {default}")
+            else:
+                init_params.append(f"        {prop['name']}: {prop['swiftType']}")
+        lines.append("    public init(")
+        lines.append(",\n".join(init_params))
+        lines.append("    ) { ... }")
+        lines.append("}")
+        lines.append("")
+
+    # Component struct
+    comp = api.get("componentStruct", {})
+    comp_name = comp.get("name", arch.get("componentName", "Component"))
+    lines.append(f"public struct {comp_name}: View {{")
+    if config:
+        lines.append(f"    private let configuration: {config['name']}")
+        lines.append("")
+        lines.append(f"    public init(configuration: {config['name']}) {{")
+        lines.append("        self.configuration = configuration")
+        lines.append("    }")
+    else:
+        # SIMPLE — direct init params
+        for param in comp.get("initParameters", []):
+            lines.append(f"    private let {param['name']}: {param['swiftType']}")
+    lines.append("}")
+    lines.append("```")
+
+    return "\n".join(lines)
+
+
+def run_spec(artifact_path: str) -> bool:
+    """Compile 07_implementation_spec.md from pass3 structured files."""
+    print("Phase 3 Spec: Compiling implementation spec")
+    ap = Path(artifact_path)
+
+    # Read architecture JSON (primary data source)
+    arch_path = ap / "pass3" / "04b_component_architecture.json"
+    if not arch_path.exists():
+        print("  [error] 04b_component_architecture.json not found", file=sys.stderr)
+        return False
+
+    with open(arch_path) as f:
+        arch = json.load(f)
+
+    comp_name = arch.get("componentName", "Unknown")
+    complexity = arch.get("complexity", "SIMPLE")
+    prop_count = arch.get("propertyCount", 0)
+
+    # Read component_summary.json for dimensions
+    summary_path = ap / "pass1" / "component_summary.json"
+    dimensions = "unknown"
+    node_id = ""
+    if summary_path.exists():
+        with open(summary_path) as f:
+            summary = json.load(f)
+        w = summary.get("dimensions", {}).get("width", "?")
+        h = summary.get("dimensions", {}).get("height", "?")
+        dimensions = f"{w} x {h} (component set)"
+        node_id = summary.get("nodeId", "")
+
+    # Read component location
+    loc_path = ap / "pass3" / "01_component_location.md"
+    comp_location = extract_md_value(loc_path, "Location")
+    if not comp_location:
+        comp_location = "(see 01_component_location.md)"
+
+    # Read property coverage
+    cov_path = ap / "pass3" / "00_property_coverage.json"
+    if cov_path.exists():
+        with open(cov_path) as f:
+            cov = json.load(f)
+    else:
+        cov = {}
+
+    # Generate API shape code
+    api_code = generate_api_shape_code(arch)
+
+    # Build variant mapping table
+    variant_lines = []
+    variant_lines.append("| Figma Property | Swift Property | Type |")
+    variant_lines.append("|----------------|---------------|------|")
+
+    all_props = arch.get("properties", []) + arch.get("implicitProperties", [])
+    for prop in all_props:
+        status = prop.get("status", "IMPLEMENT")
+        if status == "SKIP":
+            # Show merged info
+            reason = prop.get("reason", "")
+            swift_type = "—"
+            swift_name = "—"
+            if "merged" in reason.lower():
+                # Find the implicit property this was merged into
+                for ip in arch.get("implicitProperties", []):
+                    if ip.get("figmaKey") == prop.get("figmaKey"):
+                        swift_name = ip["name"]
+                        swift_type = f"{ip['swiftType']} (merged — nil = hidden)"
+                        break
+            variant_lines.append(f"| {prop['name']} ({prop['type']}) | {swift_name} | {swift_type} |")
+        else:
+            swift_type = prop.get("swiftType", "?")
+            figma_key = prop.get("figmaKey", prop.get("name", ""))
+            # Swift property name
+            swift_name = prop.get("name", "")
+            # camelCase the name
+            if swift_name and " " in swift_name:
+                parts = swift_name.split()
+                swift_name = parts[0].lower() + "".join(p.capitalize() for p in parts[1:])
+            elif swift_name:
+                swift_name = swift_name[0].lower() + swift_name[1:]
+
+            if prop.get("type") == "BOOLEAN_MERGED":
+                continue  # Already shown via the SKIP entry
+            type_desc = f"{swift_type} enum" if prop.get("values") else swift_type
+            if prop.get("values"):
+                vals = "/".join(f".{v}" for v in (arch.get("enums", [{}])[0].get("cases", []) if False else []))
+                # Find the matching enum
+                for e in arch.get("enums", []):
+                    if e.get("name") == swift_type:
+                        vals = "/".join(f".{c}" for c in e["cases"])
+                        type_desc = f"{swift_type} enum ({vals})"
+                        break
+            if swift_type == "Bool" and prop.get("values"):
+                type_desc = "Bool (Yes→true, No→false)"
+
+            variant_lines.append(f"| {prop['name']} ({prop['type']}) | {swift_name} | {type_desc} |")
+
+    # Nested dependencies
+    nested_path = ap / "pass3" / "03_nested_components.md"
+    nested_lines = extract_md_section_lines(nested_path, "Connected")
+    if not nested_lines or all(not l.strip() or l.startswith("|--") for l in nested_lines):
+        nested_section = "Self-contained component. No nested dependencies."
+    else:
+        nested_section = "\n".join(nested_lines)
+
+    # Check for inline elements mention
+    nested_full = ""
+    if nested_path.exists():
+        with open(nested_path) as f:
+            nested_full = f.read()
+    inline_mention = ""
+    if "inline" in nested_full.lower():
+        for line in nested_full.split("\n"):
+            if "inline" in line.lower() and not line.startswith("#"):
+                inline_mention = line.strip().lstrip("- ")
+                break
+
+    # Assets
+    assets_path = ap / "pass3" / "06_assets.md"
+    asset_summary_lines = extract_md_section_lines(assets_path, "Summary")
+    asset_summary = "\n".join(l for l in asset_summary_lines if l.strip())
+    if not asset_summary:
+        asset_summary = "No assets."
+
+    # Token summary
+    token_path = ap / "pass3" / "02_token_mapping.md"
+    token_summary_lines = extract_md_section_lines(token_path, "Summary")
+    token_summary = "\n".join(l for l in token_summary_lines if l.strip())
+
+    # Missing tokens
+    missing_lines = extract_md_section_lines(token_path, "Missing Tokens")
+    missing_count = sum(1 for l in missing_lines if l.strip().startswith("|") and "⚠️" not in l and "Token" not in l and "---" not in l)
+    # Parse from summary
+    token_mapped = 0
+    token_missing = 0
+    for l in token_summary_lines:
+        if "mapped" in l.lower():
+            m = re.search(r'(\d+)\s+mapped', l)
+            if m:
+                token_mapped += int(m.group(1))
+        if "missing" in l.lower():
+            m = re.search(r'(\d+)\s+(?:actionable|missing)', l)
+            if m:
+                token_missing += int(m.group(1))
+
+    # Data models
+    api_design = arch.get("apiDesign", {})
+    sub_configs = api_design.get("subConfigurations", [])
+    list_types = api_design.get("listTypes", [])
+    if not sub_configs and not list_types:
+        data_models = "No list inference. No sub-configurations. All properties are flat within the configuration struct."
+    else:
+        parts = []
+        if sub_configs:
+            parts.append(f"Sub-configurations: {', '.join(sc.get('name', '?') for sc in sub_configs)}")
+        if list_types:
+            parts.append(f"List types: {', '.join(lt.get('name', '?') for lt in list_types)}")
+        data_models = " ".join(parts)
+
+    # Files to create
+    files_to_create = [f"- `{comp_name}.swift` (main view)"]
+    if complexity == "COMPLEX":
+        config_name = arch.get("configurationStruct", f"{comp_name}Configuration")
+        files_to_create.append(f"- `{config_name}.swift` (configuration struct + enums)")
+    files_to_create.append("- `FIGMA.md` (documentation)")
+
+    # Workflow
+    if complexity == "COMPLEX":
+        config_name = arch.get("configurationStruct", f"{comp_name}Configuration")
+        workflow = f"COMPLEX → Configuration struct pattern. {config_name} wraps all {prop_count} parameters."
+    else:
+        workflow = f"SIMPLE → Direct init parameters. {prop_count} parameters passed to init."
+
+    # --- COMPILE SPEC ---
+    spec = f"""# Implementation Spec
+
+Component: {comp_name}
+Generated: {DATE_SHORT}
+
+## Component
+
+| Field | Value |
+|-------|-------|
+| Name | {comp_name} |
+| Path | {comp_location} |
+| Node ID | {node_id} |
+| Dimensions | {dimensions} |
+| Complexity | {complexity} |
+| Properties | {prop_count} (after pattern reduction) |
+
+## Files to Create
+
+{chr(10).join(files_to_create)}
+
+## API Shape
+
+{api_code}
+
+## Variant Mapping
+
+{chr(10).join(variant_lines)}
+
+## Data Models
+
+{data_models}
+
+## Nested Dependencies
+
+{nested_section}
+{f'{chr(10)}{inline_mention}' if inline_mention else ''}
+
+## New Assets
+
+{asset_summary}
+
+## Token Mapping
+
+- Mapped: {token_mapped}
+- Missing: {token_missing}
+
+## Workflow
+
+{workflow}
+"""
+
+    out_path = ap / "pass3" / "07_implementation_spec.md"
+    with open(out_path, "w") as f:
+        f.write(spec)
+
+    print(f"  ✅ {out_path}")
+    return True
+
+
+# --- Main ---
+
+def main():
+    parser = argparse.ArgumentParser(description="Phase 3 scriptable sub-phases")
+    parser.add_argument("subphase", choices=["3b", "3e", "3f", "3g", "spec", "wave1", "all"],
+                        help="Which sub-phase to run")
+    parser.add_argument("--artifact-path", required=True, help="Path to artifact directory")
+
+    args = parser.parse_args()
+
+    ensure_cli()
+
+    results = {}
+
+    if args.subphase in ("3b", "wave1", "all"):
+        results["3b"] = run_3b(args.artifact_path)
+
+    if args.subphase in ("3e", "wave1", "all"):
+        results["3e"] = run_3e(args.artifact_path)
+
+    if args.subphase in ("3f", "wave1", "all"):
+        results["3f"] = run_3f(args.artifact_path)
+
+    if args.subphase in ("3g", "all"):
+        results["3g"] = run_3g(args.artifact_path)
+
+    if args.subphase in ("spec", "all"):
+        results["spec"] = run_spec(args.artifact_path)
+
+    # Summary
+    print(f"\n{'='*50}")
+    for phase, ok in results.items():
+        status = "✅ PASS" if ok else "❌ FAIL"
+        print(f"  {phase}: {status}")
+
+    if all(results.values()):
+        print(f"\nAll sub-phases complete.")
+    else:
+        failed = [k for k, v in results.items() if not v]
+        print(f"\nFailed: {', '.join(failed)}", file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()