@mmerterden/multi-agent-pipeline 8.6.0

package/pipeline/skills/figma-common/figma-iteration-commit/SKILL.md

@@ -0,0 +1,1015 @@
+# /figma-iteration-commit — Validate & Commit to iteration/develop + PR to develop
+
+## Guardrails
+
+> **NEVER create branches on the main repo (REPO_ROOT).** Do not create `iteration/develop` or any other branch on the main repo. Do not commit to the main repo. This skill only commits to submodules (common, uicomponents, wiki). Main repo submodule refs are updated separately — not by this skill.
+
+> **NEVER use `json.dumps()` default formatting on JSON files.** When editing JSON files (e.g., `ui-testing-identifiers.json`), preserve the existing file format. Do not reformat, re-indent, or change separators. The canonical format for `ui-testing-identifiers.json` is `" : "` (space-colon-space), not `": "`. If you must write JSON programmatically, post-process the output to match the existing format.
+
+> **NEVER manually edit `ui-testing-identifiers.json`.** Format corruption on this file is most likely caused by conflict resolution. When a rebase conflict occurs on this file:
+> 1. Check what keys we added — look at `Shared/Figma/Components/{nodeId}.json` (has the key list) or `git show HEAD:Shared/UITestingIdentifiers/ui-testing-identifiers.json`
+> 2. Take the remote version: `git checkout --ours Shared/UITestingIdentifiers/ui-testing-identifiers.json` (during rebase, `--ours` = upstream/remote)
+> 3. Re-add our keys via `/common-utility` (`utility-add-key`) — this writes in the correct `" : "` format
+> 4. `git add Shared/UITestingIdentifiers/ui-testing-identifiers.json` + `git rebase --continue`
+>
+> Never resolve JSON conflicts by hand-editing or `json.dumps()` — it reformats the entire file.
+
+> **ALWAYS validate `ui-testing-identifiers.json` key count after every rebase — even when there were no conflicts.** The implement agent regenerates this file from `identifier-keys.json` only, which means an auto-merge can silently drop keys that exist on `iteration/develop` but not in the local metadata. After every rebase (or cherry-pick), before staging and continuing, run:
+>
+> ```bash
+> REMOTE_KEY_COUNT=$(git show origin/iteration/develop:Shared/UITestingIdentifiers/ui-testing-identifiers.json 2>/dev/null | grep -c '".*" : "' || echo 0)
+> LOCAL_KEY_COUNT=$(grep -c '".*" : "' Shared/UITestingIdentifiers/ui-testing-identifiers.json 2>/dev/null || echo 0)
+> if [ "$LOCAL_KEY_COUNT" -lt "$REMOTE_KEY_COUNT" ]; then
+>   echo "⚠️  INTEGRITY VIOLATION: ui-testing-identifiers.json lost $((REMOTE_KEY_COUNT - LOCAL_KEY_COUNT)) keys vs origin/iteration/develop"
+>   echo "   Remote: ${REMOTE_KEY_COUNT} keys, Local: ${LOCAL_KEY_COUNT} keys"
+>   echo "   Restoring from origin/iteration/develop and re-adding component keys..."
+>   git show origin/iteration/develop:Shared/UITestingIdentifiers/ui-testing-identifiers.json \
+>     > Shared/UITestingIdentifiers/ui-testing-identifiers.json
+>   # Re-add our component's keys (they are in identifier-keys.json — tool will merge them in)
+>   .build/debug/UITestingIdentifierTool generate \
+>     --config Shared/UITestingIdentifiers/Config/identifier-config.json
+>   git add Shared/UITestingIdentifiers/ui-testing-identifiers.json
+>   git add iOS/Sources/UITestingIdentifiers/Generated/UITestingIdentifierKeys.swift
+> fi
+> ```
+>
+> This guard runs even when `ui-testing-identifiers.json` was NOT in the conflict list. Silent key loss from auto-merge is the most common failure mode.
+
+> **ALWAYS validate Generated Swift key files after every rebase — even when there were no conflicts.** The codegen tool (`UnifiedCodeGenerationTool`) regenerates `LocalizationStringKeys.swift` and `LocalizedAccessibilityStringKeys.swift` from config JSONs that reference `Sources/Suggested/*.json` files. An auto-merge (or accepting either side during conflict resolution) can silently drop enum blocks if the suggested-key files from another developer's component are not present locally. After every rebase (or cherry-pick), before rebuilding, run:
+>
+> ```bash
+> LOC_FILE="iOS/Sources/LocalizationStringKeys/Generated/LocalizationStringKeys.swift"
+> A11Y_FILE="iOS/Sources/AccessibilityStringKeys/Generated/LocalizedAccessibilityStringKeys.swift"
+> for GEN_FILE in "$LOC_FILE" "$A11Y_FILE"; do
+>   REMOTE_ENUMS=$(git show origin/iteration/develop:"${GEN_FILE}" 2>/dev/null | grep -oE 'enum [A-Za-z0-9_]+' | sort -u || true)
+>   LOCAL_ENUMS=$(grep -oE 'enum [A-Za-z0-9_]+' "${GEN_FILE}" 2>/dev/null | sort -u || true)
+>   MISSING=$(comm -23 <(echo "$REMOTE_ENUMS") <(echo "$LOCAL_ENUMS"))
+>   if [ -n "$MISSING" ]; then
+>     echo "⚠️  INTEGRITY VIOLATION: ${GEN_FILE##*/} lost enum blocks vs origin/iteration/develop:"
+>     echo "$MISSING"
+>     echo "   Restoring remote version (rebuild will re-add our component's keys)..."
+>     git show origin/iteration/develop:"${GEN_FILE}" > "${GEN_FILE}"
+>     git add "${GEN_FILE}"
+>   fi
+> done
+> ```
+>
+> This guard runs even when the Generated files were NOT in the conflict list. Silent enum loss from auto-merge or "accept either side" resolution is a known failure mode — the rebuild script's codegen step (3.5) will re-add our component's keys on top of the restored remote file.
+
+> **ALWAYS validate `Sources/Suggested/*.json` file count after every rebase, cherry-pick, AND before every commit — even when there were no conflicts.** The implement agent only creates source JSONs for the current component. A rebase, cherry-pick, or `git add -A` can silently drop source JSON files belonging to OTHER components (e.g., a tool run deletes files, or a workspace reset loses them). These per-key source files are the ground truth for localization and accessibility code generation — losing them means generated code silently loses keys for other components. After every rebase (or cherry-pick), AND before every `git add -A` in the commit step, run:
+>
+> ```bash
+> for SUGGESTED_DIR in \
+>   "Shared/Localization/LocalizationStrings/Sources/Suggested" \
+>   "Shared/Localization/AccessibilityStrings/Sources/Suggested"; do
+>
+>   REMOTE_FILES=$(git ls-tree --name-only origin/iteration/develop -- "${SUGGESTED_DIR}/" 2>/dev/null | sed "s|${SUGGESTED_DIR}/||" | sort)
+>   LOCAL_FILES=$(ls -1 "${SUGGESTED_DIR}/" 2>/dev/null | sort)
+>   MISSING_FILES=$(comm -23 <(echo "$REMOTE_FILES") <(echo "$LOCAL_FILES"))
+>
+>   if [ -n "$MISSING_FILES" ]; then
+>     MISSING_COUNT=$(echo "$MISSING_FILES" | wc -l | tr -d ' ')
+>     echo "⚠️  INTEGRITY VIOLATION: ${SUGGESTED_DIR} lost ${MISSING_COUNT} source JSON file(s) vs origin/iteration/develop:"
+>     echo "$MISSING_FILES" | head -20
+>     echo "   Restoring missing files from origin/iteration/develop..."
+>     while IFS= read -r FILE; do
+>       git show "origin/iteration/develop:${SUGGESTED_DIR}/${FILE}" > "${SUGGESTED_DIR}/${FILE}"
+>       git add "${SUGGESTED_DIR}/${FILE}"
+>     done <<< "$MISSING_FILES"
+>     echo "✅ Restored ${MISSING_COUNT} missing source JSON file(s) in ${SUGGESTED_DIR##*/}."
+>   fi
+> done
+> ```
+>
+> This guard catches the most dangerous form of silent data loss: source JSON files from OTHER components being deleted by the current component's pipeline. Unlike generated files (which can be rebuilt), source JSONs contain the original translations and cannot be re-derived.
+
+> **NEVER call `common-rebuild-derived-artifacts.sh` blindly after conflict resolution when `ui-testing-identifiers.json` may have been touched.** The rebuild script calls `UITestingIdentifierTool generate --swift-only` which only writes the Swift file — but the JSON may already be corrupt from a bad auto-merge. Always run the key-count integrity check BEFORE the rebuild script, and fix the JSON FIRST if the count decreased.
+
+## Conflict File Classification (common submodule)
+
+When a cherry-pick or rebase conflict occurs in the common submodule, classify each conflicted file and resolve automatically by pattern:
+
+| File Pattern | Strategy | Reason |
+|-------------|----------|--------|
+| `iOS/Sources/*/Generated/*` | Accept either side | Will regenerate |
+| `Shared/Figma/Generated/*` | Accept either side | Gitignored, will regenerate |
+| `iOS/Sources/LocalizationAssets/Resources/*.xcstrings` | Accept either side | Will regenerate |
+| `iOS/Sources/AccessibilityAssets/Resources/*.xcstrings` | Accept either side | Will regenerate |
+| `Shared/Localization/*/Metadata/*` | Accept either side | Gitignored, will regenerate |
+| `Shared/UITestingIdentifiers/Metadata/*` | Accept either side | Gitignored, will regenerate |
+| `Sources/Suggested/*.json` | Our version wins | Per-key files, we created them |
+| `Shared/Figma/Components/*.json` | Our version wins | We created/modified it |
+| `Shared/UITestingIdentifiers/ui-testing-identifiers.json` | Take remote + re-add keys via tool | See Guardrails — never hand-edit |
+| `Shared/UIAssets/Colors/*.json` | Take remote + manually insert new entries | Match existing format exactly |
+
+**After resolving all conflicts, ALWAYS rebuild derived artifacts:**
+
+```bash
+bash "${REPO_ROOT}/.instructions/common/scripts/common-rebuild-derived-artifacts.sh"
+```
+
+This regenerates all merged data, metadata, keys indexes, UI assets, token registries, and Figma catalogs.
+
+---
+
+## Purpose
+
+Validates a component implementation, commits directly to `iteration/develop` in submodules, and handles issue housekeeping (comment, phase update, auto-unblock dependents).
+
+## Parameters
+
+| Parameter | Required | Default | Description |
+|-----------|----------|---------|-------------|
+| `<ComponentName>` | Yes | — | PascalCase component name |
+| `--gh` | No | — | GitHub issue number (auto-detected if on a tracked issue) |
+
+```
+/figma-iteration-commit ModalsTitle
+/figma-iteration-commit ModalsTitle --gh 107
+```
+
+---
+
+## Constants
+
+```
+REPO_ROOT       = git repo root (auto-detect)
+GH_REPO         = {github.componentsRepo}
+MAIN_REPO       = ${REPO_ROOT}
+COMMON          = ${REPO_ROOT}/{repos.common.path}
+UICOMPONENTS    = ${REPO_ROOT}/{repos.components.path}
+WIKI            = ${REPO_ROOT}/{repos.wiki.path}
+DEFAULT_JIRA    = {jira.projectKey}-124692
+```
+
+---
+
+## STEP 0 — Resolve
+
+1. Parse `ComponentName`. Convert to kebab-case.
+2. If `--gh` provided, read the issue to get Jira key. Otherwise search for the issue:
+   ```bash
+   gh issue list --repo ${GH_REPO} --state open --label component --search "{ComponentName}" --json number,body --jq '.[0]'
+   ```
+3. Extract Jira key from issue body (or use `DEFAULT_JIRA`).
+4. Ensure submodules are on `iteration/develop`. For each submodule (common, uicomponents):
+
+   **If already on `iteration/develop`** → continue.
+
+   **If on a feature branch with commits** → rebase onto `iteration/develop` with backup:
+
+   ```
+   a. Record the feature branch name and HEAD SHA
+   b. Create a backup branch: backup/{feature-branch-name}
+   c. Fetch latest iteration/develop from origin
+   d. Checkout iteration/develop
+   e. Cherry-pick (or rebase) the feature branch commits onto iteration/develop
+   f. Run build (STEP 1a) to verify nothing broke after rebase
+   g. If build succeeds:
+      - Delete the local feature branch
+      - Delete the remote feature branch (origin)
+      - Delete the local backup branch
+   h. If build fails:
+      - Reset iteration/develop to its previous state
+      - Restore the feature branch from the backup
+      - HALT: "Rebase broke the build. Feature branch preserved at {branch-name}."
+      - Do NOT delete the backup — leave it for manual resolution
+   ```
+
+   ```bash
+   cd ${SUBMODULE}
+   FEATURE_BRANCH=$(git branch --show-current)
+
+   if [ "${FEATURE_BRANCH}" != "iteration/develop" ]; then
+     FEATURE_SHA=$(git rev-parse HEAD)
+     ITER_BASE=$(git merge-base ${FEATURE_BRANCH} origin/iteration/develop)
+
+     # Backup
+     git branch backup/${FEATURE_BRANCH}
+
+     # Collect feature commits (from where it diverged from iteration/develop)
+     COMMITS=$(git log --oneline ${ITER_BASE}..${FEATURE_BRANCH} --reverse --format="%H")
+
+     # Switch to iteration/develop
+     git fetch origin iteration/develop
+     git checkout iteration/develop
+     git reset --hard origin/iteration/develop
+
+     # Cherry-pick feature commits
+     for COMMIT in ${COMMITS}; do
+       git cherry-pick ${COMMIT} || {
+         # CONFLICT HANDLING — do NOT abort or delete any changes
+         echo "⚠️  Cherry-pick conflict at ${COMMIT}."
+         echo "Conflicting files:"
+         CONFLICTED_FILES=$(git diff --name-only --diff-filter=U)
+         echo "${CONFLICTED_FILES}"
+
+         # Auto-resolve by file classification (see "Conflict File Classification" section)
+         AUTO_RESOLVED=()
+         MANUAL_NEEDED=()
+
+         for FILE in ${CONFLICTED_FILES}; do
+           case "${FILE}" in
+             iOS/Sources/*/Generated/*|Shared/Figma/Generated/*|iOS/Sources/LocalizationAssets/Resources/*.xcstrings|iOS/Sources/AccessibilityAssets/Resources/*.xcstrings|Shared/Localization/*/Metadata/*|Shared/UITestingIdentifiers/Metadata/*)
+               # Accept remote (will regenerate)
+               git checkout --ours "${FILE}" && git add "${FILE}"
+               AUTO_RESOLVED+=("${FILE} → accepted remote (will regenerate)")
+               ;;
+             Sources/Suggested/*.json|Shared/Figma/Components/*.json)
+               # Our version wins (we created these)
+               git checkout --theirs "${FILE}" && git add "${FILE}"
+               AUTO_RESOLVED+=("${FILE} → kept ours (we created it)")
+               ;;
+             Shared/UITestingIdentifiers/ui-testing-identifiers.json)
+               # Take remote + re-add keys via tool (see Guardrails)
+               git checkout --ours "${FILE}" && git add "${FILE}"
+               AUTO_RESOLVED+=("${FILE} → accepted remote (will re-add keys via tool after)")
+               ;;
+             Shared/UIAssets/Colors/*.json)
+               # Take remote + manually insert new entries
+               git checkout --ours "${FILE}" && git add "${FILE}"
+               AUTO_RESOLVED+=("${FILE} → accepted remote (will insert new entries after)")
+               ;;
+             *)
+               MANUAL_NEEDED+=("${FILE}")
+               ;;
+           esac
+         done
+
+         if [ ${#AUTO_RESOLVED[@]} -gt 0 ]; then
+           echo "\n✅ Auto-resolved files:"
+           for ENTRY in "${AUTO_RESOLVED[@]}"; do echo "  - ${ENTRY}"; done
+         fi
+
+         # If ui-testing-identifiers.json was conflicted, re-add our keys via /common-utility
+         if echo "${CONFLICTED_FILES}" | grep -q 'ui-testing-identifiers.json'; then
+           echo "\n📋 Re-adding our keys to ui-testing-identifiers.json via /common-utility (utility-add-key)..."
+           # Agent: use /common-utility utility-add-key for each key from Shared/Figma/Components/{nodeId}.json
+         fi
+
+         # If all files were auto-resolved, rebuild and continue
+         if [ ${#MANUAL_NEEDED[@]} -eq 0 ]; then
+           echo "\n✅ All conflicts auto-resolved."
+
+           # ── ui-testing-identifiers.json integrity guard (ALWAYS run before rebuild) ──
+           # The implement agent regenerates this file from identifier-keys.json only.
+           # An auto-merge can silently drop keys that exist on iteration/develop but not locally.
+           REMOTE_KEY_COUNT=$(git show origin/iteration/develop:Shared/UITestingIdentifiers/ui-testing-identifiers.json 2>/dev/null | grep -c '".*" : "' || echo 0)
+           LOCAL_KEY_COUNT=$(grep -c '".*" : "' Shared/UITestingIdentifiers/ui-testing-identifiers.json 2>/dev/null || echo 0)
+           if [ "${LOCAL_KEY_COUNT}" -lt "${REMOTE_KEY_COUNT}" ]; then
+             MISSING=$((REMOTE_KEY_COUNT - LOCAL_KEY_COUNT))
+             echo "⚠️  INTEGRITY FIX: ui-testing-identifiers.json lost ${MISSING} keys vs origin/iteration/develop. Restoring..."
+             git show origin/iteration/develop:Shared/UITestingIdentifiers/ui-testing-identifiers.json \
+               > Shared/UITestingIdentifiers/ui-testing-identifiers.json
+             .build/debug/UITestingIdentifierTool generate \
+               --config Shared/UITestingIdentifiers/Config/identifier-config.json
+             git add Shared/UITestingIdentifiers/ui-testing-identifiers.json
+             git add iOS/Sources/UITestingIdentifiers/Generated/UITestingIdentifierKeys.swift
+             echo "✅ Restored ${REMOTE_KEY_COUNT} remote keys + re-added component keys."
+           fi
+           # ─────────────────────────────────────────────────────────────────────────────
+
+           # ── Generated Swift keys integrity guard (ALWAYS run before rebuild) ──
+           # The codegen tool regenerates from config JSONs + Sources/Suggested/*.json.
+           # An auto-merge can silently drop enum blocks from other developers' components.
+           LOC_FILE="iOS/Sources/LocalizationStringKeys/Generated/LocalizationStringKeys.swift"
+           A11Y_FILE="iOS/Sources/AccessibilityStringKeys/Generated/LocalizedAccessibilityStringKeys.swift"
+           for GEN_FILE in "$LOC_FILE" "$A11Y_FILE"; do
+             REMOTE_ENUMS=$(git show origin/iteration/develop:"${GEN_FILE}" 2>/dev/null | grep -oE 'enum [A-Za-z0-9_]+' | sort -u || true)
+             LOCAL_ENUMS=$(grep -oE 'enum [A-Za-z0-9_]+' "${GEN_FILE}" 2>/dev/null | sort -u || true)
+             MISSING_ENUMS=$(comm -23 <(echo "$REMOTE_ENUMS") <(echo "$LOCAL_ENUMS"))
+             if [ -n "$MISSING_ENUMS" ]; then
+               echo "⚠️  INTEGRITY FIX: ${GEN_FILE##*/} lost enum blocks vs origin/iteration/develop:"
+               echo "$MISSING_ENUMS"
+               echo "   Restoring remote version (rebuild will re-add our component's keys)..."
+               git show origin/iteration/develop:"${GEN_FILE}" > "${GEN_FILE}"
+               git add "${GEN_FILE}"
+             fi
+           done
+           # ─────────────────────────────────────────────────────────────────────────────
+
+
+            # ── Sources/Suggested/*.json integrity guard (ALWAYS run before rebuild) ──
+            # The implement agent only creates source JSONs for the current component.
+            # A cherry-pick or git add -A can silently drop source JSONs from other components.
+            for SUGGESTED_DIR in \
+              "Shared/Localization/LocalizationStrings/Sources/Suggested" \
+              "Shared/Localization/AccessibilityStrings/Sources/Suggested"; do
+
+              REMOTE_FILES=$(git ls-tree --name-only origin/iteration/develop -- "${SUGGESTED_DIR}/" 2>/dev/null | sed "s|${SUGGESTED_DIR}/||" | sort)
+              LOCAL_FILES=$(ls -1 "${SUGGESTED_DIR}/" 2>/dev/null | sort)
+              MISSING_FILES=$(comm -23 <(echo "$REMOTE_FILES") <(echo "$LOCAL_FILES"))
+
+              if [ -n "$MISSING_FILES" ]; then
+                MISSING_COUNT=$(echo "$MISSING_FILES" | wc -l | tr -d ' ')
+                echo "⚠️  INTEGRITY FIX: ${SUGGESTED_DIR##*/} lost ${MISSING_COUNT} source JSON file(s) vs origin/iteration/develop:"
+                echo "$MISSING_FILES" | head -20
+                echo "   Restoring missing files from origin/iteration/develop..."
+                while IFS= read -r FILE; do
+                  git show "origin/iteration/develop:${SUGGESTED_DIR}/${FILE}" > "${SUGGESTED_DIR}/${FILE}"
+                  git add "${SUGGESTED_DIR}/${FILE}"
+                done <<< "$MISSING_FILES"
+                echo "✅ Restored ${MISSING_COUNT} missing source JSON file(s)."
+              fi
+            done
+            # ─────────────────────────────────────────────────────────────────────────────
+
+           echo "Rebuilding derived artifacts..."
+           bash "${REPO_ROOT}/.instructions/common/scripts/common-rebuild-derived-artifacts.sh"
+           git add -A
+           git cherry-pick --continue
+         else
+           # Show remaining conflicts that need manual resolution
+           echo "\n⚠️  Files needing manual resolution:"
+           for FILE in "${MANUAL_NEEDED[@]}"; do
+             echo "\n--- Conflict in: ${FILE} ---"
+             grep -n '<<<<<<<\|=======\|>>>>>>>' "${FILE}" || true
+           done
+
+           echo "\n📋 Suggested resolution:"
+           echo "  - Review the conflict markers above"
+           echo "  - Both local (feature) and remote (iteration/develop) changes are preserved in the conflict markers"
+           echo "  - Edit the conflicting files to keep the desired changes from both sides"
+           echo "  - Then run: git add <resolved-files> && git cherry-pick --continue"
+           echo "  - After resolving, rebuild: bash \"${REPO_ROOT}/.instructions/common/scripts/common-rebuild-derived-artifacts.sh\""
+           echo "  - Backup branch is available at: backup/${FEATURE_BRANCH}"
+
+           # ASK the user whether to continue
+           # The agent MUST use the ask-questions tool here:
+           #   Question: "Cherry-pick conflict detected. Auto-resolved N files, M need manual resolution.
+           #              Would you like to: (a) resolve manually and continue, or (b) abort the commit?"
+           #   If user chooses (b): git cherry-pick --abort && git checkout ${FEATURE_BRANCH} && exit 1
+           #   If user chooses (a): wait for user to resolve, then rebuild derived artifacts, then git cherry-pick --continue
+           #
+           # IMPORTANT: Do NOT auto-abort. Do NOT delete the feature branch.
+           # Leave all changes intact and let the user decide.
+         fi
+       }
+     done
+
+     # Build validation after rebase (STEP 1a will run fully later, this is a quick gate)
+     # If build fails, restore from backup
+     # If build succeeds, clean up branches (after full STEP 1 passes and push succeeds in STEP 3b)
+   fi
+   ```
+
+   **Important:** Do NOT delete feature branches until STEP 3b push succeeds. Track them for cleanup:
+   ```
+   BRANCHES_TO_CLEANUP=("common:${FEATURE_BRANCH}" ...)
+   ```
+   After successful push in STEP 3b, delete each:
+   ```bash
+   git branch -D ${FEATURE_BRANCH}
+   git push origin --delete ${FEATURE_BRANCH}
+   git branch -D backup/${FEATURE_BRANCH}
+   ```
+
+---
+
+## STEP 1 — Validate
+
+### 1a. Build
+
+```bash
+xcodebuild build -project "${REPO_ROOT}/{build.xcodeproj}" \
+    -scheme {build.scheme} -destination 'generic/platform=iOS' \
+    CODE_SIGNING_ALLOWED=NO -quiet
+```
+
+If build fails → HALT. Fix before committing.
+
+### 1b. Tests
+
+Run component tests:
+
+```bash
+xcodebuild test -project "${REPO_ROOT}/{build.xcodeproj}" \
+    -scheme {build.scheme} -destination 'platform=iOS Simulator,name=iPhone 16 Pro' \
+    -only-testing:"UIComponentsTests/${ComponentName}ViewInspectorTests" \
+    -only-testing:"UIComponentsTests/${ComponentName}SnapshotTests" \
+    CODE_SIGNING_ALLOWED=NO -quiet
+```
+
+If tests fail → HALT. Fix before committing.
+
+### 1c. Key Sync Validation
+
+Verify localization, accessibility, and testing identifier keys are in sync:
+
+```bash
+cd ${COMMON}
+python3 .instructions/figma/figma-to-swiftui/scripts/validate-localization-sync.py \
+    --component "{ComponentName}"
+```
+
+If out of sync → HALT. Regenerate with `update-*-dev` (NOT `generate-*-code` — see common-utility docs):
+```bash
+swift package plugin --allow-writing-to-package-directory update-localizations-dev
+swift package plugin --allow-writing-to-package-directory update-accessibility-dev
+swift run UITestingIdentifierTool generate
+```
+
+### 1d. Code Review (lightweight)
+
+Read `.instructions/figma/figma-commit/REVIEW.md` and run the full 13-point checklist.
+
+- **Auto-fix** any fixable violations (magic numbers, missing identifiers, wrong patterns).
+- If auto-fixes applied, re-run build (STEP 1a) to verify.
+- If unfixable violations remain → print them, ask user whether to proceed or abort.
+
+Print validation result:
+
+```
+Validation: PASS / FAIL
+  Build:      ✅
+  Tests:      ✅ (N passed)
+  Key Sync:   ✅
+  Review:     ✅ / ⚠️ (N warnings)
+```
+
+---
+
+## STEP 2 — Detect Changes
+
+```bash
+HAS_COMMON=$(cd "${COMMON}" && git status --porcelain | head -1)
+HAS_UICOMPONENTS=$(cd "${UICOMPONENTS}" && git status --porcelain | head -1)
+HAS_WIKI=$(cd "${WIKI}" && git status --porcelain | head -1)
+```
+
+---
+
+## STEP 3 — Commit Locally
+
+Commit to local `iteration/develop` in submodules. Do NOT push yet — pushing happens in STEP 3b after validation confirms the build is clean.
+
+### 3a. Commit (local only)
+
+**Common (if HAS_COMMON):**
+
+> ⚠️ **Before `git add -A`**, run the Sources/Suggested integrity guard (see Guardrails). This prevents silently staging deletions of other components' source JSON files.
+
+```bash
+cd ${COMMON}
+
+# ── Pre-commit Sources/Suggested integrity guard ──
+for SUGGESTED_DIR in \
+  "Shared/Localization/LocalizationStrings/Sources/Suggested" \
+  "Shared/Localization/AccessibilityStrings/Sources/Suggested"; do
+
+  REMOTE_FILES=$(git ls-tree --name-only origin/iteration/develop -- "${SUGGESTED_DIR}/" 2>/dev/null | sed "s|${SUGGESTED_DIR}/||" | sort)
+  LOCAL_FILES=$(ls -1 "${SUGGESTED_DIR}/" 2>/dev/null | sort)
+  MISSING_FILES=$(comm -23 <(echo "$REMOTE_FILES") <(echo "$LOCAL_FILES"))
+
+  if [ -n "$MISSING_FILES" ]; then
+    MISSING_COUNT=$(echo "$MISSING_FILES" | wc -l | tr -d ' ')
+    echo "⚠️  PRE-COMMIT FIX: ${SUGGESTED_DIR##*/} missing ${MISSING_COUNT} source JSON file(s) vs origin. Restoring..."
+    while IFS= read -r FILE; do
+      git show "origin/iteration/develop:${SUGGESTED_DIR}/${FILE}" > "${SUGGESTED_DIR}/${FILE}"
+    done <<< "$MISSING_FILES"
+    echo "✅ Restored ${MISSING_COUNT} file(s). They will be included in the commit."
+  fi
+done
+# ──────────────────────────────────────────────────
+
+git add -A
+git commit -m "feat(common): [${JIRA_ISSUE}] add ${COMPONENT_PASCAL} tokens and keys
+
+Refs: ${JIRA_ISSUE}"
+```
+
+**UIComponents (if HAS_UICOMPONENTS):**
+
+```bash
+cd ${UICOMPONENTS}
+git add -A
+git commit -m "feat(uicomponents): [${JIRA_ISSUE}] add ${COMPONENT_PASCAL} component
+
+Refs: ${JIRA_ISSUE}"
+```
+
+**Wiki (if HAS_WIKI):**
+
+```bash
+cd ${WIKI}
+git add -A
+git commit -m "docs: [${JIRA_ISSUE}] add ${COMPONENT_PASCAL} wiki documentation
+
+Refs: ${JIRA_ISSUE}"
+```
+
+---
+
+### ⛔ 3a-gate — Pre-Push Approval (required HARD STOP)
+
+> **Do NOT proceed to STEP 3b until the user explicitly approves.**
+> Use the `ask-questions` tool here. A silent "yes" assumption is a pipeline violation.
+
+**Print the following push summary for every submodule that has local commits:**
+
+```
+╔══════════════════════════════════════════════════════════════════╗
+║  PRE-PUSH SUMMARY — iteration/develop                           ║
+╠══════════════════════════════════════════════════════════════════╣
+║  common (if HAS_COMMON):                                        ║
+║    Branch : iteration/develop                                    ║
+║    Ahead  : N commits ahead of origin/iteration/develop          ║
+║    Commits: (list each SHA + title)                              ║
+║    Files  : +X insertions, -Y deletions                         ║
+╠══════════════════════════════════════════════════════════════════╣
+║  uicomponents (if HAS_UICOMPONENTS):                            ║
+║    Branch : iteration/develop                                    ║
+║    Ahead  : N commits ahead of origin/iteration/develop          ║
+║    Commits: (list each SHA + title)                              ║
+║    Files  : +X insertions, -Y deletions                         ║
+╠══════════════════════════════════════════════════════════════════╣
+║  wiki (if HAS_WIKI):                                            ║
+║    Branch : master                                               ║
+║    Ahead  : N commits ahead of origin/master                     ║
+║    Commits: (list each SHA + title)                              ║
+║    Files  : +X insertions, -Y deletions                         ║
+╚══════════════════════════════════════════════════════════════════╝
+```
+
+Generate this summary with:
+
+```bash
+# For each submodule with commits — adapt branch name per repo:
+cd ${SUBMODULE}
+echo "Ahead: $(git rev-list origin/${PUSH_BRANCH}..HEAD --count) commits"
+git log origin/${PUSH_BRANCH}..HEAD --oneline
+git diff origin/${PUSH_BRANCH}..HEAD --stat | tail -1
+```
+
+**Then ask the user:**
+
+> ✅ All validations passed. The commits above are ready to push to `origin/iteration/develop`.
+>
+> **Ready to push? Reply `yes` to push, or `no` to stop here and leave local commits intact.**
+
+**Branching logic:**
+
+- If user replies **`yes`** (or `ok`, `go`, `approved`, `looks good`) → proceed to STEP 3b.
+- If user replies **`no`** (or `stop`, `cancel`, `wait`) → print:
+
+  ```
+  Push cancelled. Local commits preserved:
+    common       : <SHA>
+    uicomponents : <SHA>
+    wiki         : <SHA>
+
+  Run /figma-iteration-commit again when ready to push.
+  ```
+
+  Then **HALT** — do not revert any local commits, do not push anything.
+
+---
+
+### 3b. Push with Rebase-Retry Loop
+
+For each submodule (common, uicomponents), push with this logic:
+
+```
+1. Attempt push
+2. If push succeeds → done
+3. If push rejected (remote has new commits):
+   a. Fetch latest from origin
+   b. Rebase local commits onto updated remote
+   c. Re-run build (STEP 1a) to verify nothing broke after rebase
+   d. If build passes → retry push (go to 1)
+   e. If build fails → HALT, report conflict
+```
+
+**Per submodule:**
+
+```bash
+cd ${SUBMODULE}
+PUSH_BRANCH="iteration/develop"  # or "master" for wiki
+
+MAX_RETRIES=3
+for i in $(seq 1 $MAX_RETRIES); do
+  git push origin ${PUSH_BRANCH} && break
+
+  echo "Push rejected — remote updated. Rebasing (attempt $i)..."
+  git fetch origin ${PUSH_BRANCH}
+  git rebase origin/${PUSH_BRANCH}
+
+  if [ $? -ne 0 ]; then
+    # CONFLICT HANDLING — do NOT abort or delete any changes
+    echo "⚠️  Rebase conflict detected during push retry."
+    echo "Conflicting files:"
+    CONFLICTED_FILES=$(git diff --name-only --diff-filter=U)
+    echo "${CONFLICTED_FILES}"
+
+    # Auto-resolve by file classification (see "Conflict File Classification" section)
+    AUTO_RESOLVED=()
+    MANUAL_NEEDED=()
+
+    for FILE in ${CONFLICTED_FILES}; do
+      case "${FILE}" in
+        iOS/Sources/*/Generated/*|Shared/Figma/Generated/*|iOS/Sources/LocalizationAssets/Resources/*.xcstrings|iOS/Sources/AccessibilityAssets/Resources/*.xcstrings|Shared/Localization/*/Metadata/*|Shared/UITestingIdentifiers/Metadata/*)
+          # Accept remote (will regenerate)
+          git checkout --ours "${FILE}" && git add "${FILE}"
+          AUTO_RESOLVED+=("${FILE} → accepted remote (will regenerate)")
+          ;;
+        Sources/Suggested/*.json|Shared/Figma/Components/*.json)
+          # Our version wins (we created these)
+          git checkout --theirs "${FILE}" && git add "${FILE}"
+          AUTO_RESOLVED+=("${FILE} → kept ours (we created it)")
+          ;;
+        Shared/UITestingIdentifiers/ui-testing-identifiers.json)
+          # Take remote + re-add keys via tool (see Guardrails)
+          git checkout --ours "${FILE}" && git add "${FILE}"
+          AUTO_RESOLVED+=("${FILE} → accepted remote (will re-add keys via tool after)")
+          ;;
+        Shared/UIAssets/Colors/*.json)
+          # Take remote + manually insert new entries
+          git checkout --ours "${FILE}" && git add "${FILE}"
+          AUTO_RESOLVED+=("${FILE} → accepted remote (will insert new entries after)")
+          ;;
+        *)
+          MANUAL_NEEDED+=("${FILE}")
+          ;;
+      esac
+    done
+
+    if [ ${#AUTO_RESOLVED[@]} -gt 0 ]; then
+      echo "\n✅ Auto-resolved files:"
+      for ENTRY in "${AUTO_RESOLVED[@]}"; do echo "  - ${ENTRY}"; done
+    fi
+
+    # If ui-testing-identifiers.json was conflicted, re-add our keys via /common-utility
+    if echo "${CONFLICTED_FILES}" | grep -q 'ui-testing-identifiers.json'; then
+      echo "\n📋 Re-adding our keys to ui-testing-identifiers.json via /common-utility (utility-add-key)..."
+      # Agent: use /common-utility utility-add-key for each key from Shared/Figma/Components/{nodeId}.json
+    fi
+
+    # If all files were auto-resolved, rebuild and continue
+    if [ ${#MANUAL_NEEDED[@]} -eq 0 ]; then
+      echo "\n✅ All conflicts auto-resolved."
+
+      # ── ui-testing-identifiers.json integrity guard (ALWAYS run before rebuild) ──
+      # The implement agent regenerates this file from identifier-keys.json only.
+      # An auto-merge can silently drop keys that exist on iteration/develop but not locally.
+      REMOTE_KEY_COUNT=$(git show origin/iteration/develop:Shared/UITestingIdentifiers/ui-testing-identifiers.json 2>/dev/null | grep -c '".*" : "' || echo 0)
+      LOCAL_KEY_COUNT=$(grep -c '".*" : "' Shared/UITestingIdentifiers/ui-testing-identifiers.json 2>/dev/null || echo 0)
+      if [ "${LOCAL_KEY_COUNT}" -lt "${REMOTE_KEY_COUNT}" ]; then
+        MISSING=$((REMOTE_KEY_COUNT - LOCAL_KEY_COUNT))
+        echo "⚠️  INTEGRITY FIX: ui-testing-identifiers.json lost ${MISSING} keys vs origin/iteration/develop. Restoring..."
+        git show origin/iteration/develop:Shared/UITestingIdentifiers/ui-testing-identifiers.json \
+          > Shared/UITestingIdentifiers/ui-testing-identifiers.json
+        .build/debug/UITestingIdentifierTool generate \
+          --config Shared/UITestingIdentifiers/Config/identifier-config.json
+        git add Shared/UITestingIdentifiers/ui-testing-identifiers.json
+        git add iOS/Sources/UITestingIdentifiers/Generated/UITestingIdentifierKeys.swift
+        echo "✅ Restored ${REMOTE_KEY_COUNT} remote keys + re-added component keys."
+      fi
+      # ─────────────────────────────────────────────────────────────────────────────
+
+      # ── Generated Swift keys integrity guard (ALWAYS run before rebuild) ──
+      # The codegen tool regenerates from config JSONs + Sources/Suggested/*.json.
+      # An auto-merge can silently drop enum blocks from other developers' components.
+      LOC_FILE="iOS/Sources/LocalizationStringKeys/Generated/LocalizationStringKeys.swift"
+      A11Y_FILE="iOS/Sources/AccessibilityStringKeys/Generated/LocalizedAccessibilityStringKeys.swift"
+      for GEN_FILE in "$LOC_FILE" "$A11Y_FILE"; do
+        REMOTE_ENUMS=$(git show origin/iteration/develop:"${GEN_FILE}" 2>/dev/null | grep -oE 'enum [A-Za-z0-9_]+' | sort -u || true)
+        LOCAL_ENUMS=$(grep -oE 'enum [A-Za-z0-9_]+' "${GEN_FILE}" 2>/dev/null | sort -u || true)
+        MISSING_ENUMS=$(comm -23 <(echo "$REMOTE_ENUMS") <(echo "$LOCAL_ENUMS"))
+        if [ -n "$MISSING_ENUMS" ]; then
+          echo "⚠️  INTEGRITY FIX: ${GEN_FILE##*/} lost enum blocks vs origin/iteration/develop:"
+          echo "$MISSING_ENUMS"
+          echo "   Restoring remote version (rebuild will re-add our component's keys)..."
+          git show origin/iteration/develop:"${GEN_FILE}" > "${GEN_FILE}"
+          git add "${GEN_FILE}"
+        fi
+      done
+      # ─────────────────────────────────────────────────────────────────────────────
+
+      # ── Sources/Suggested/*.json integrity guard (ALWAYS run before rebuild) ──
+      for SUGGESTED_DIR in \
+        "Shared/Localization/LocalizationStrings/Sources/Suggested" \
+        "Shared/Localization/AccessibilityStrings/Sources/Suggested"; do
+
+        REMOTE_FILES=$(git ls-tree --name-only origin/iteration/develop -- "${SUGGESTED_DIR}/" 2>/dev/null | sed "s|${SUGGESTED_DIR}/||" | sort)
+        LOCAL_FILES=$(ls -1 "${SUGGESTED_DIR}/" 2>/dev/null | sort)
+        MISSING_FILES=$(comm -23 <(echo "$REMOTE_FILES") <(echo "$LOCAL_FILES"))
+
+        if [ -n "$MISSING_FILES" ]; then
+          MISSING_COUNT=$(echo "$MISSING_FILES" | wc -l | tr -d ' ')
+          echo "⚠️  INTEGRITY FIX: ${SUGGESTED_DIR##*/} lost ${MISSING_COUNT} source JSON file(s) vs origin/iteration/develop:"
+          echo "$MISSING_FILES" | head -20
+          echo "   Restoring missing files from origin/iteration/develop..."
+          while IFS= read -r FILE; do
+            git show "origin/iteration/develop:${SUGGESTED_DIR}/${FILE}" > "${SUGGESTED_DIR}/${FILE}"
+            git add "${SUGGESTED_DIR}/${FILE}"
+          done <<< "$MISSING_FILES"
+          echo "✅ Restored ${MISSING_COUNT} missing source JSON file(s)."
+        fi
+      done
+      # ─────────────────────────────────────────────────────────────────────────────
+
+      echo "Rebuilding derived artifacts..."
+      bash "${REPO_ROOT}/.instructions/common/scripts/common-rebuild-derived-artifacts.sh"
+      git add -A
+      git rebase --continue
+    else
+      # Show remaining conflicts that need manual resolution
+      echo "\n⚠️  Files needing manual resolution:"
+      for FILE in "${MANUAL_NEEDED[@]}"; do
+        echo "\n--- Conflict in: ${FILE} ---"
+        grep -n '<<<<<<<\|=======\|>>>>>>>' "${FILE}" || true
+      done
+
+      echo "\n📋 Suggested resolution:"
+      echo "  - Review the conflict markers above"
+      echo "  - Both local and remote changes are preserved in the conflict markers"
+      echo "  - Edit the conflicting files to keep the desired changes from both sides"
+      echo "  - After resolving, rebuild: bash \"${REPO_ROOT}/.instructions/common/scripts/common-rebuild-derived-artifacts.sh\""
+      echo "  - Then run: git add <resolved-files> && git rebase --continue"
+
+      # ASK the user whether to continue
+      # The agent MUST use the ask-questions tool here:
+      #   Question: "Rebase conflict detected during push. Auto-resolved N files, M need manual resolution.
+      #              Would you like to: (a) resolve manually and continue pushing, or (b) abort the rebase and stop?"
+      #   If user chooses (b): git rebase --abort && HALT
+      #   If user chooses (a): wait for user to resolve, then rebuild derived artifacts, then git rebase --continue and re-validate build
+      #
+      # IMPORTANT: Do NOT auto-abort. Do NOT delete any committed changes.
+      # Leave all changes intact and let the user decide.
+    fi
+  fi
+
+  # Re-validate build after rebase
+  xcodebuild build -project "${REPO_ROOT}/{build.xcodeproj}" \
+      -scheme {build.scheme} -destination 'generic/platform=iOS' \
+      CODE_SIGNING_ALLOWED=NO -quiet
+
+  if [ $? -ne 0 ]; then
+    echo "HALT: Build failed after rebase. Fix before pushing."
+    exit 1
+  fi
+done
+```
+
+### 3c. Fetch all remotes
+
+After successful push, sync all local branches:
+
+```bash
+cd ${MAIN_REPO} && git fetch origin develop
+cd ${COMMON} && git fetch origin iteration/develop
+cd ${UICOMPONENTS} && git fetch origin iteration/develop
+```
+
+---
+
+## STEP 4 — Issue Housekeeping
+
+### 4a. Comment on issue
+
+If issue was found/provided:
+
+```bash
+COMMON_SHA=$(git -C ${COMMON} rev-parse --short HEAD)
+UICOMP_SHA=$(git -C ${UICOMPONENTS} rev-parse --short HEAD)
+
+gh issue comment <N> --repo ${GH_REPO} --body "$(cat <<'EOF'
+Committed to iteration/develop (submodules):
+- common: ${COMMON_SHA}
+- uicomponents: ${UICOMP_SHA}
+
+Ready for review.
+EOF
+)"
+```
+
+### 4b. Sync issue from registry
+
+Phase state is tracked per-flag in the component registry
+(`status.ios.{implemented,tested,codeConnect,wiki}`), written by the
+phase finalize scripts during STEP 2 of `/figma-cli-iterate`. The
+issue's labels and Progress table are projections of that state — no
+filesystem inference anymore.
+
+Run the registry sync once, after the commit succeeds:
+
+```bash
+python3 .instructions/figma/figma-to-swiftui/scripts/update-issue-from-registry.py \
+    --node-id "<NODE_ID>" \
+    --platform ios
+```
+
+This call is idempotent:
+
+- Adds/removes `impl:*`/`test:*`/`cc:*`/`wiki:*` labels to match
+  registry state (green when current, yellow when stale or against an
+  older impl.version).
+- Rewrites the `### Progress` table in the issue body.
+- Strips any legacy `phase:*` labels.
+- If zero open issues reference this node-id, creates a new one with
+  `team:core` as default.
+- If multiple open issues reference the node-id, closes all but the
+  lowest-numbered one with a "Duplicate of #N" comment.
+
+If the call fails (gh not authenticated, rate limit, etc.), log the
+error but don't fail the commit — the sync can always be re-run
+manually or via `bulk-sync-issues.py`.
+
+### 4c. Link wiki to issue
+
+If wiki was committed (HAS_WIKI), add or update the **Wiki** section in the issue body:
+
+```
+WIKI_URL=https://github.com/${GH_REPO}/wiki/${COMPONENT_PASCAL}
+```
+
+Read the current issue body, then:
+- If a `### Wiki` section already exists, replace its content with the new link.
+- If no `### Wiki` section exists, insert it before `### Notes`.
+
+The Wiki section format:
+
+```markdown
+### Wiki
+
+[${COMPONENT_PASCAL}](${WIKI_URL})
+```
+
+Use a Python script written to a temp file to avoid shell quoting issues with `gh issue edit --body-file`:
+
+```python
+import subprocess, json, re
+
+COMPONENT = "${COMPONENT_PASCAL}"
+GH_REPO = "${GH_REPO}"
+ISSUE_N = <N>
+WIKI_URL = f"https://github.com/{GH_REPO}/wiki/{COMPONENT}"
+WIKI_SECTION = f"### Wiki\n\n[{COMPONENT}]({WIKI_URL})"
+
+result = subprocess.run(
+    ["gh", "issue", "view", str(ISSUE_N), "--repo", GH_REPO, "--json", "body"],
+    capture_output=True, text=True)
+body = json.loads(result.stdout)["body"]
+
+if "### Wiki" in body:
+    body = re.sub(r"### Wiki\n\n.*?\n(\n###|\Z)", lambda m: WIKI_SECTION + "\n" + m.group(1), body, flags=re.DOTALL)
+else:
+    body = body.replace("### Notes", WIKI_SECTION + "\n\n### Notes")
+
+with open("/tmp/issue_body_update.md", "w") as f:
+    f.write(body)
+
+subprocess.run(["gh", "issue", "edit", str(ISSUE_N), "--repo", GH_REPO, "--body-file", "/tmp/issue_body_update.md"])
+```
+
+### 4d. Link Sub-Component Issues
+
+Read the nested components artifact to find which sub-components this component uses:
+
+```bash
+# Get artifactPath from registry
+ARTIFACT_PATH=$(cd ${COMMON} && .build/debug/FigmaRegistryUtility lookup --node-id "${NODE_ID}" 2>/dev/null | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('suggestedArtifactPath',''))" 2>/dev/null || echo "")
+
+NESTED_FILE="${REPO_ROOT}/${ARTIFACT_PATH}/pass3/03_nested_components.md"
+```
+
+If `NESTED_FILE` does not exist → skip this step silently.
+
+If it exists, parse connected components:
+
+```bash
+# Extract component names from the Connected Components table in 03_nested_components.md
+# Lines look like: | ComponentName | Sources/... | `Init...` |
+CONNECTED_COMPONENTS=$(grep '^\| [A-Z]' "${NESTED_FILE}" | awk -F'|' '{print $2}' | tr -d ' ')
+```
+
+For each connected component name, find its GitHub issue and add as sub-issue:
+
+```python
+import subprocess, json, re
+
+GH_REPO = "${GH_REPO}"
+PARENT_ISSUE_N = <N>
+
+# Read connected components from nested file
+nested_path = "${NESTED_FILE}"
+connected = []
+in_connected_section = False
+
+with open(nested_path) as f:
+    for line in f:
+        if line.strip() == "## Connected Components":
+            in_connected_section = True
+            continue
+        if in_connected_section and line.startswith("## "):
+            break
+        if in_connected_section and line.startswith("| "):
+            parts = [p.strip() for p in line.split("|")]
+            # parts[1] = component name, skip header and separator rows
+            if len(parts) > 2 and parts[1] and not parts[1].startswith("-") and parts[1] != "Component":
+                connected.append(parts[1])
+
+sub_issues_added = []
+
+for comp_name in connected:
+    # Search for the sub-component's issue
+    result = subprocess.run(
+        ["gh", "issue", "list", "--repo", GH_REPO, "--state", "open",
+         "--label", "component", "--search", comp_name,
+         "--json", "number,title"],
+        capture_output=True, text=True
+    )
+    if result.returncode != 0:
+        print(f"  ⚠️  Could not search issue for {comp_name}")
+        continue
+
+    issues = json.loads(result.stdout)
+    # Find closest match (title contains exact component name)
+    match = next((i for i in issues if comp_name.lower() in i["title"].lower()), None)
+    if not match:
+        print(f"  ⚠️  No open issue found for sub-component: {comp_name}")
+        continue
+
+    sub_issue_n = match["number"]
+
+    # Add as sub-issue via GitHub API
+    api_result = subprocess.run(
+        ["gh", "api", "--method", "POST",
+         f"repos/{GH_REPO}/issues/{PARENT_ISSUE_N}/sub_issues",
+         "--field", f"sub_issue_id={sub_issue_n}"],
+        capture_output=True, text=True
+    )
+
+    if api_result.returncode == 0:
+        sub_issues_added.append(f"#{sub_issue_n} ({comp_name})")
+        print(f"  ✅ Linked sub-issue #{sub_issue_n} ({comp_name})")
+    else:
+        # May already be linked — not a fatal error
+        print(f"  ℹ️  Could not link #{sub_issue_n} ({comp_name}): {api_result.stderr.strip()}")
+
+if sub_issues_added:
+    print(f"\nSub-issues linked: {', '.join(sub_issues_added)}")
+else:
+    print("No sub-issues linked (no matching open issues found).")
+```
+
+> **Non-fatal:** If this step fails (artifact missing, gh API error, no matching issues), log and continue — it must never block the commit.
+ 
+
+---
+
+## STEP 5 — Auto-Unblock Dependents
+
+Scan all open issues with `blocked` label:
+
+```bash
+gh issue list --repo ${GH_REPO} --state open --label blocked --json number,title,body
+```
+
+For each blocked issue:
+1. Read the issue body or sub-issue comments to find what it's blocked by (component names).
+2. For each blocking component, check if `{ComponentName}.swift` exists:
+   ```bash
+   find ${UICOMPONENTS}/Sources -name "{BlockingComponent}.swift" -type f | head -1
+   ```
+3. If ALL blocking components now have Swift files → unblock:
+   ```bash
+   gh issue edit <BLOCKED_N> --repo ${GH_REPO} --remove-label "blocked"
+   gh issue comment <BLOCKED_N> --repo ${GH_REPO} --body "Auto-unblocked: all dependencies now implemented."
+   ```
+
+Print any unblocked issues.
+
+---
+
+## STEP 6 — Summary
+
+```
+Iteration Commit: ${COMPONENT_PASCAL}
+
+| Repo | Commit | Status |
+|------|--------|--------|
+| common | ${COMMON_SHA} | ✅ pushed |
+| uicomponents | ${UICOMP_SHA} | ✅ pushed |
+| wiki | ${WIKI_SHA} | ✅ pushed |
+| main | ${MAIN_SHA} | ✅ pushed / PR created |
+
+Validation: PASS
+Issue: #N — commented + phase updated
+Sub-issues: #X (ComponentA), #Y (ComponentB) (or "none")
+Unblocked: #M, #K (or "none")
+Jira: ${JIRA_ISSUE}
+```
+
+---
+
+## Error Handling
+
+- **Submodules not on iteration/develop**: Checkout automatically (rebase-merge if commits exist).
+- **Build fails**: HALT — fix before committing.
+- **Tests fail**: HALT — fix before committing.
+- **Key sync fails**: HALT — regenerate keys first.
+- **Push rejected**: Report error, do NOT force-push.
+- **No changes**: Print "Nothing to commit" and exit.
+- **Issue not found**: Commit without issue housekeeping, print warning.
+- **Rebase/cherry-pick conflict**: Do NOT abort or delete any changes. Show conflicting files and conflict markers, suggest resolution steps, and ASK the user whether to (a) resolve and continue or (b) abort. Preserve all local and remote changes in conflict markers until the user decides. For `ui-testing-identifiers.json` conflicts, always suggest the take-remote + re-add-keys approach (see Guardrails).