@mmerterden/multi-agent-pipeline 8.6.0

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

@@ -0,0 +1,711 @@
+# /performance-iteration-commit-all — Batch Validate & Push All Tour Components
+
+> Reads `_tour_tracker.json`, validates all reviewed components in a single build+test
+> cycle, pushes all local commits in a single push per submodule, then handles issue
+> housekeeping for each component individually.
+
+## Guardrails
+
+> **NEVER create branches on the main repo (REPO_ROOT).** Same guardrail as `figma-iteration-commit`.
+
+> **NEVER use `json.dumps()` default formatting on JSON files.** Preserve existing format.
+> `ui-testing-identifiers.json` uses `" : "` (space-colon-space).
+
+> **NEVER manually edit `ui-testing-identifiers.json` during rebase conflict resolution.**
+> Follow the conflict resolution protocol from `figma-iteration-commit`.
+
+## Parameters
+
+No arguments — reads `_tour_tracker.json`.
+
+```
+/performance-iteration-commit-all
+```
+
+---
+
+## Constants
+
+```
+REPO_ROOT       = git repo root (auto-detect)
+GH_REPO         = {github.componentsRepo}
+COMMON          = ${REPO_ROOT}/{repos.common.path}
+UICOMPONENTS    = ${REPO_ROOT}/{repos.components.path}
+WIKI            = ${REPO_ROOT}/{repos.wiki.path}
+TRACKER_FILE    = ${REPO_ROOT}/_tour_tracker.json
+```
+
+---
+
+## STEP 0 — Read Tracker & Verify State
+
+Read `_tour_tracker.json`.
+
+Verify:
+- `current_step` is `"STEP_3"` — if not, HALT: "Review not complete. Run /performance-review-next first."
+- `reviewed_components` has at least 1 entry
+- All reviewed components have local commits (check with `git log`)
+
+Collect reviewed component data:
+
+```python
+reviewed = [tracker["components"][str(issue)] for issue in tracker["reviewed_components"]]
+lean_mode = tracker.get("lean_mode", False)
+```
+
+Print:
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  BATCH COMMIT — PRE-FLIGHT                                   ║
+╠══════════════════════════════════════════════════════════════╣
+║                                                              ║
+║  Components to commit:                                       ║
+║  1. ComponentA (#1000) — reviewed ✅                         ║
+║  2. ComponentC (#1002) — reviewed ✅                         ║
+║                                                              ║
+║  Dropped (will NOT be committed):                            ║
+║  ❌ ComponentB (#1001) — halted, dropped                     ║
+║                                                              ║
+╚══════════════════════════════════════════════════════════════╝
+
+Proceed with validation and push? (yes/no)
+```
+
+Wait for user confirmation.
+
+---
+
+## STEP 1 — Validate (SINGLE PASS)
+
+### 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 (Combined)
+
+> **LEAN MODE:** If `lean_mode` is `true` in the tracker, **SKIP this entire substep.**
+> Tests were not generated during production. Print `Tests: ⏭️ skipped (lean mode)` and proceed to 1c.
+
+Run tests for ALL reviewed components in a single xcodebuild invocation:
+
+```bash
+xcodebuild test -project "${REPO_ROOT}/{build.xcodeproj}" \
+    -scheme {build.scheme} \
+    -destination 'platform=iOS Simulator,name=iPhone 16 Pro' \
+    -only-testing:"UIComponentsTests/ComponentAViewInspectorTests" \
+    -only-testing:"UIComponentsTests/ComponentASnapshotTests" \
+    -only-testing:"UIComponentsTests/ComponentCViewInspectorTests" \
+    -only-testing:"UIComponentsTests/ComponentCSnapshotTests" \
+    CODE_SIGNING_ALLOWED=NO -quiet
+```
+
+Build the `-only-testing` flags dynamically from the reviewed components list.
+
+If tests fail → HALT. Identify failing component and fix.
+
+### 1c. Key Sync Validation
+
+For each reviewed component:
+
+```bash
+cd ${COMMON}
+python3 .instructions/figma/figma-to-swiftui/scripts/validate-localization-sync.py \
+    --component "${COMPONENT_NAME}"
+```
+
+If out of sync → regenerate:
+```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
+```
+
+If regeneration creates new changes → commit them:
+```bash
+cd ${COMMON}
+git add -A
+git commit -m "fix(common): sync keys after tour validation
+
+Tour: performance-tour $(date +%Y%m%d)"
+```
+
+### 1d. Code Review (Lightweight)
+
+Read `.instructions/figma/figma-commit/REVIEW.md` and run the 13-point checklist
+across ALL reviewed components.
+
+- Auto-fix any fixable violations
+- If auto-fixes applied, commit:
+  ```bash
+  cd ${UICOMPONENTS}
+  git add -A
+  git commit -m "fix(uicomponents): auto-fix review violations
+
+  Tour: performance-tour review fixes"
+  ```
+- Re-run build (STEP 1a) to verify auto-fixes didn't break anything
+- If unfixable violations remain → print them, ask user to proceed or abort
+
+Print validation result:
+
+```
+Validation Summary:
+  Build:      ✅
+  Tests:      ✅ (ComponentA: 12 passed, ComponentC: 8 passed)    # or: ⏭️ skipped (lean mode)
+  Key Sync:   ✅
+  Review:     ✅ / ⚠️ (N warnings, M auto-fixed)
+```
+
+---
+
+## STEP 2 — Push (SINGLE PUSH per submodule)
+
+### 2a. Push with Rebase-Retry Loop
+
+For each submodule that has commits (common, uicomponents, wiki):
+
+```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
+    # Rebase conflict — attempt auto-resolution for generated files
+    # See "Generated File Conflict Resolution" below
+    # If auto-resolution fails → HALT
+  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
+```
+
+**Push order matters:** common → uicomponents → wiki (dependencies flow this direction).
+In **lean mode**, wiki submodule has no commits — skip the wiki push entirely.
+
+#### Generated File Conflict Resolution (common submodule)
+
+During rebase, conflicts in generated files are **expected** when others have pushed to
+`iteration/develop` concurrently. **NEVER resolve these by picking a side — always
+accept remote then regenerate.**
+
+**Conflict resolution table:**
+
+| File | Resolution |
+|------|-----------|
+| `ui-testing-identifiers.json` | 1. `git checkout --ours` (upstream=remote during rebase) 2. Re-add our keys from `Shared/Figma/Components/{nodeId}.json` using Python with `" : "` format 3. `git add` |
+| `LocalizationStringKeys.swift` | 1. `git checkout --ours` 2. Run `swift package plugin --allow-writing-to-package-directory update-localizations-dev` 3. `git add` |
+| `UIAssetsGeneratedTokens.swift` | 1. `git checkout --ours` (timestamp-only conflict) 2. `git add` |
+| `UITestingIdentifierKeys.swift` | 1. `git checkout --ours` 2. Run `swift run UITestingIdentifierTool generate` 3. `git add` |
+| `Localizable.xcstrings` | 1. `git checkout --ours` 2. Already regenerated by `update-localizations-dev` above 3. `git add` |
+
+**Procedure per conflicted commit during rebase:**
+
+```
+1. List conflicted files:  git diff --name-only --diff-filter=U
+2. For each conflicted file:
+   a. If in table above → apply resolution (accept remote + regenerate)
+   b. If NOT in table → HALT, ask user to resolve manually
+3. git add <resolved files>
+4. git rebase --continue
+5. If next commit also conflicts → repeat from step 1
+```
+
+**Post-rebase verification:** After all conflicts resolved and rebase completes,
+verify our keys survived:
+```bash
+grep -c "ComponentName" iOS/Sources/LocalizationStringKeys/Generated/LocalizationStringKeys.swift
+grep -c "ComponentName" Shared/UITestingIdentifiers/ui-testing-identifiers.json
+```
+If count is 0 for any component → regenerate again before pushing.
+
+#### Wiki Conflict Resolution
+
+Wiki status pages (`ComponentImplementationStatus*.md`) are auto-generated dashboards.
+When conflicts occur:
+1. `git checkout --ours` (accept remote counts)
+2. `git add` + `git rebase --continue`
+3. Status dashboard will be regenerated in STEP 3e
+
+### 2b. Record Push SHAs
+
+After successful push:
+
+```bash
+COMMON_SHA=$(git -C ${COMMON} rev-parse --short HEAD)
+UICOMP_SHA=$(git -C ${UICOMPONENTS} rev-parse --short HEAD)
+WIKI_SHA=$(git -C ${WIKI} rev-parse --short HEAD)   # only if not lean_mode
+```
+
+Update tracker: record SHAs for each component.
+
+### 2c. Fetch All Remotes
+
+```bash
+cd ${COMMON} && git fetch origin iteration/develop
+cd ${UICOMPONENTS} && git fetch origin iteration/develop
+# Wiki fetch — skip in lean mode
+if [ "$LEAN_MODE" != "true" ]; then
+  cd ${WIKI} && git fetch origin master
+fi
+```
+
+### 2d. Post-Push Build Verification
+
+After all submodules are pushed, verify that the **remote dependency chain** builds
+correctly. This catches issues where generated files lost entries during rebase
+conflict resolution (e.g., `LocalizationStringKeys.swift` missing component keys).
+
+1. Ensure `Package.swift` in uicomponents points to **remote** common (not local path):
+   ```
+   .package(url: "...{project.slug}-common.git", branch: "iteration/develop")
+   ```
+   If it has a local `path:` override, revert it first.
+
+2. Resolve packages to pick up the freshly pushed common:
+   ```bash
+   cd ${UICOMPONENTS}
+   swift package resolve
+   ```
+
+3. Run a quick build:
+   ```bash
+   xcodebuild build -project "${REPO_ROOT}/{build.xcodeproj}" \
+       -scheme {build.scheme} -destination 'generic/platform=iOS' \
+       CODE_SIGNING_ALLOWED=NO -skipMacroValidation -quiet
+   ```
+
+4. If build fails:
+   - Check for `has no member` errors → indicates generated file lost keys during rebase
+   - For `LocalizationStringKeys`: `cd ${COMMON} && swift package plugin --allow-writing-to-package-directory update-localizations-dev`
+   - For `UITestingIdentifierKeys`: `cd ${COMMON} && swift run UITestingIdentifierTool generate`
+   - Commit fix: `git add -A && git commit -m "fix(common): regenerate keys after rebase"`
+   - Push: `git push origin iteration/develop`
+   - Re-run this step to confirm
+
+5. If build succeeds → print `Post-Push Build: ✅`
+
+---
+
+## STEP 3 — Issue Housekeeping (Per Component)
+
+> **(strict) NONE of these substeps may be skipped.** Each substep prints a
+> status line (`✅` or `❌`). The Completion Gate at the end (3g) verifies ALL
+> substeps executed. If any critical substep is missing → HALT.
+
+Initialise a per-component result tracker:
+
+```python
+housekeeping = {}  # { issue_number: { "3a": bool, "3b": bool, "3c": bool, "3d": bool, "3e": bool, "3f": bool } }
+for comp in reviewed:
+    housekeeping[comp["issue"]] = {k: False for k in ["3a","3b","3c","3d","3e","3f"]}
+```
+
+For EACH reviewed component:
+
+### 3a. Comment on Issue
+
+```bash
+gh issue comment <N> --repo ${GH_REPO} --body "$(cat <<EOF
+Committed to iteration/develop (submodules) via performance-tour:
+- common: ${COMMON_SHA}
+- uicomponents: ${UICOMP_SHA}
+$(if [ "$LEAN_MODE" != "true" ]; then echo "- wiki: ${WIKI_SHA}"; fi)
+$(if [ "$LEAN_MODE" = "true" ]; then echo "\nMode: lean (tests & wiki skipped)"; fi)
+
+Tour batch: $(date +%Y-%m-%d)
+Ready for review.
+EOF
+)"
+```
+
+Verify: `gh issue view <N> --repo ${GH_REPO} --json comments --jq '.comments[-1].body' | grep -q 'performance-tour'`
+
+Print: `  #<N> 3a Comment: ✅` or `❌`
+
+### 3b. Update Issue Phase + Labels
+
+Determine completed phases from committed files:
+- Has Swift view file → phase:implementation done
+- Has test files → phase:testing done (**skip check in lean mode — always false**)
+- Has .figma.swift → phase:code-connect done
+- Has wiki markdown → phase:documentation done (**skip check in lean mode — always false**)
+
+**Add phase labels to issue (adjust for lean mode):**
+
+```bash
+# Full mode: add all completed phase labels
+# Lean mode: only add phase:code-connect (no testing or documentation labels)
+if [ "$LEAN_MODE" = "true" ]; then
+  gh issue edit <N> --repo ${GH_REPO} \
+      --add-label "phase:code-connect"
+else
+  gh issue edit <N> --repo ${GH_REPO} \
+      --add-label "phase:testing" \
+      --add-label "phase:code-connect" \
+      --add-label "phase:documentation"
+fi
+```
+
+**Update Phase field on Projects V2 board** to the LAST completed phase
+(same GraphQL mutations as `figma-iteration-commit` STEP 4b):
+
+```bash
+# Phase option IDs:
+#   Implementation = 0577dcda
+#   Testing        = 106b64ce
+#   Code Connect   = 5384b1e1
+#   Documentation  = 7307fb8f
+#
+# In lean mode, last phase = Code Connect (5384b1e1)
+# In full mode, last phase = Documentation (7307fb8f)
+
+ISSUE_NODE_ID=$(gh api graphql -f query='{ repository(owner: "{github.org}", name: "{project.slug}-components") { issue(number: <N>) { id } } }' --jq '.data.repository.issue.id')
+
+ITEM_ID=$(gh api graphql -f query='mutation { addProjectV2ItemById(input: { projectId: "{github.projectV2Id}", contentId: "'"$ISSUE_NODE_ID"'" }) { item { id } } }' --jq '.data.addProjectV2ItemById.item.id')
+
+# Set Phase = Documentation (last completed) — or Code Connect in lean mode
+LAST_PHASE_ID="7307fb8f"  # Documentation
+if [ "$LEAN_MODE" = "true" ]; then
+  LAST_PHASE_ID="5384b1e1"  # Code Connect
+fi
+gh api graphql -f query='mutation { updateProjectV2ItemFieldValue(input: { projectId: "{github.projectV2Id}", itemId: "'"$ITEM_ID"'", fieldId: "{github.projectV2Fields.phase}", value: { singleSelectOptionId: "'"$LAST_PHASE_ID"'" } }) { projectV2Item { id } } }'
+```
+
+Verify: `gh api graphql` query confirms Phase field updated.
+
+Print: `  #<N> 3b Phase: ✅ → Documentation` or `  #<N> 3b Phase: ✅ → Code Connect (lean)` or `❌`
+
+### 3c. Link Wiki to Issue
+
+> **LEAN MODE:** If `lean_mode` is `true`, **SKIP this substep.** Wiki was not generated.
+> Print `  #<N> 3c Wiki Link: ⏭ (lean mode)` and proceed.
+
+If wiki was committed, add/update `### Wiki` section in issue body
+(same logic as `figma-iteration-commit` STEP 4c).
+
+```bash
+# Get current body
+BODY=$(gh issue view <N> --repo ${GH_REPO} --json body --jq '.body')
+
+# Construct wiki URL
+WIKI_URL="https://github.com/${GH_REPO}/wiki/<WIKI_RELATIVE_PATH>/<COMPONENT_NAME>"
+
+# Append wiki section if not already present
+if ! echo "$BODY" | grep -q '### Wiki'; then
+    NEW_BODY="${BODY}
+
+### Wiki
+
+[${COMPONENT_NAME}](${WIKI_URL})"
+    gh issue edit <N> --repo ${GH_REPO} --body "$NEW_BODY"
+fi
+```
+
+Verify: `gh issue view <N> --repo ${GH_REPO} --json body --jq '.body' | grep -q 'Wiki'`
+
+Print: `  #<N> 3c Wiki Link: ✅` or `⏭ (no wiki)` or `❌`
+
+### 3d. Auto-Unblock Dependents
+
+After ALL components are pushed, scan blocked issues:
+
+```bash
+gh issue list --repo ${GH_REPO} --state open --label blocked --json number,title,body
+```
+
+For each blocked issue, check if all blocking dependencies now have implementations.
+If yes → remove `blocked` label + comment.
+
+Print: `  3d Unblock: ✅ (N unblocked)` or `⏭ (none blocked)`
+
+### 3e. Regenerate Status Dashboard
+
+> **LEAN MODE:** If `lean_mode` is `true`, **SKIP this substep.** No wiki changes were made.
+> Print `  3e Dashboard: ⏭ (lean mode)` and proceed.
+
+Wiki status pages (`ComponentImplementationStatus.md`, `-DSC.md`, `-MAC.md`) contain
+component counts that may have been lost during rebase conflict resolution. Regenerate
+them after all pushes are complete.
+
+```bash
+# Run the status update skill logic:
+cd ${WIKI}
+
+# Option A: If figma-to-swift-ui-status-update is available as a command
+# /figma-to-swift-ui-status-update
+
+# Option B: Manual regeneration using the registry
+cd ${COMMON}
+python3 ${REPO_ROOT}/.instructions/figma/figma-to-swiftui/scripts/update-status-dashboard.py \
+    --wiki-path "${WIKI}" \
+    --common-path "${COMMON}" \
+    --uicomponents-path "${UICOMPONENTS}"
+```
+
+If the script is not available, skip with a warning:
+```
+⚠️  Status dashboard regeneration skipped — script not found.
+     Run /figma-to-swift-ui-status-update manually to update counts.
+```
+
+If regeneration produces changes:
+```bash
+cd ${WIKI}
+git add ComponentImplementationStatus*.md
+git commit -m "docs(wiki): regenerate status dashboard after tour batch
+
+Tour: performance-tour $(date +%Y-%m-%d)"
+git push origin master
+```
+
+Print: `  3e Dashboard: ✅ regenerated` or `⏭ (no script)`
+
+### 3f. Jira Assignment & Content Update
+
+> This step is a **safety net** for `performance-start` STEP 4. In tour mode,
+> `performance-start` should assign Jira issues, but subagents may skip it.
+> This step verifies and fixes any gaps.
+
+For EACH reviewed component that has a Jira key (from issue body, field `### Jira Issue`):
+
+```bash
+# Extract Jira key from issue body
+JIRA_KEY=$(gh issue view <N> --repo ${GH_REPO} --json body --jq '.body' | grep -oE '{jira.projectKey}-[0-9]+')
+```
+
+If `JIRA_KEY` is empty or `_No response_` → skip with `⏭ (no Jira)`.
+
+Otherwise, run the Jira update via **Python urllib** (same approach as `performance-start` STEP 4):
+
+```python
+# /tmp/jira_housekeeping_<JIRA_KEY>.py
+import subprocess, urllib.request, json
+
+token = subprocess.check_output(
+    ["security", "find-generic-password", "-a",
+     subprocess.check_output(["whoami"]).decode().strip(),
+     "-s", "JIRA_TOKEN", "-w"],
+    stderr=subprocess.DEVNULL
+).decode().strip()
+
+JIRA_KEY = "<JIRA_KEY>"
+
+# 1. Get current user
+req = urllib.request.Request(
+    "{jira.baseUrl}/rest/api/2/myself",
+    headers={"Authorization": f"Bearer {token}"}
+)
+resp = urllib.request.urlopen(req, timeout=15)
+username = json.loads(resp.read().decode())["name"]
+
+# 2. Check if already assigned
+req2 = urllib.request.Request(
+    f"{jira.baseUrl}/rest/api/2/issue/{JIRA_KEY}?fields=assignee",
+    headers={"Authorization": f"Bearer {token}"}
+)
+resp2 = urllib.request.urlopen(req2, timeout=15)
+assignee = json.loads(resp2.read().decode()).get("fields",{}).get("assignee")
+
+if assignee and assignee.get("name") == username:
+    print(f"ALREADY_ASSIGNED {JIRA_KEY}")
+else:
+    # 3. Assign
+    data = json.dumps({"name": username}).encode()
+    req3 = urllib.request.Request(
+        f"{jira.baseUrl}/rest/api/2/issue/{JIRA_KEY}/assignee",
+        data=data,
+        headers={"Authorization": f"Bearer {token}", "Content-Type": "application/json"},
+        method="PUT"
+    )
+    try:
+        urllib.request.urlopen(req3, timeout=15)
+        print(f"ASSIGNED {JIRA_KEY}")
+    except urllib.error.HTTPError as e:
+        print(f"ASSIGN_FAILED {JIRA_KEY} {e.code}")
+
+# 4. Update Jira content (summary, description, labels)
+description = (
+    "h3. Figma\n"
+    "[<COMPONENT>|<FIGMA_URL>]\n\n"
+    "h3. GitHub Issue\n"
+    "[#<N>|https://github.com/<GH_REPO>/issues/<N>]\n\n"
+    "h3. Component\n"
+    "* *Registry Name:* <REGISTRY>\n"
+    "* *Component Name:* <COMPONENT>\n"
+    "* *Page:* <PAGE>\n\n"
+    "h3. Status\n"
+    "* (/) Implementation\n"
+    "* (/) Testing\n"
+    "* (/) Code Connect\n"
+    "* (/) Documentation"
+)
+summary = "Implement <COMPONENT> iOS UI Component"
+update_data = json.dumps({
+    "fields": {
+        "summary": summary,
+        "description": description,
+        "labels": ["redesign_ios_ui_component", "MobRedesign"],
+        "components": [{"name": "TKMOB IOS"}],
+        "fixVersions": [{"name": "no-version"}],
+        "customfield_22025": {"value": "YOK"},
+        "customfield_21400": ["no-version"]
+    }
+}).encode()
+req4 = urllib.request.Request(
+    f"{jira.baseUrl}/rest/api/2/issue/{JIRA_KEY}",
+    data=update_data,
+    headers={"Authorization": f"Bearer {token}", "Content-Type": "application/json"},
+    method="PUT"
+)
+try:
+    urllib.request.urlopen(req4, timeout=15)
+    print(f"UPDATED {JIRA_KEY}")
+except urllib.error.HTTPError as e:
+    print(f"UPDATE_FAILED {JIRA_KEY} {e.code}")
+```
+
+Print: `  #<N> 3f Jira (<JIRA_KEY>): ✅ assigned + updated` or `⏭ (no Jira)` or `⚠️ (VPN/token issue)`
+
+### 3g. Required Completion Gate
+
+> **This gate is NON-NEGOTIABLE. Do NOT proceed to STEP 4 without passing it.**
+
+Print the housekeeping checklist for ALL components:
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  HOUSEKEEPING COMPLETION GATE                                ║
+╠══════════════════════════════════════════════════════════════╣
+║                                                              ║
+║  #308 MilesSmilesInviteInviteList                            ║
+║    3a Comment:    ✅                                         ║
+║    3b Phase:      ✅ → Documentation                        ║
+║    3c Wiki Link:  ✅                                         ║
+║    3d Unblock:    ⏭ (none blocked)                          ║
+║    3e Dashboard:  ✅ regenerated                             ║
+║    3f Jira:       ✅ {jira.projectKey}-132507                          ║
+║                                                              ║
+║  #309 MilesSmilesMenuVoucherRightsGroup                      ║
+║    3a Comment:    ✅                                         ║
+║    3b Phase:      ✅ → Documentation                        ║
+║    3c Wiki Link:  ✅                                         ║
+║    3d Unblock:    ⏭ (none blocked)                          ║
+║    3e Dashboard:  ⏭ (covered above)                         ║
+║    3f Jira:       ✅ {jira.projectKey}-132508                          ║
+║                                                              ║
+║  CRITICAL CHECK:                                             ║
+║    3a (Comment):  ALL ✅                                     ║
+║    3b (Phase):    ALL ✅    ← MUST pass                     ║
+║    3c (Wiki):     ALL ✅    ← MUST pass (if wiki exists)    ║
+║                   (or ⏭ lean for all in lean mode)          ║
+║    3f (Jira):     ALL ✅    ← MUST pass (if Jira exists)    ║
+║                                                              ║
+║  GATE: ✅ PASSED                                             ║
+╚══════════════════════════════════════════════════════════════╝
+```
+
+**Critical substeps** (MUST pass or have valid skip reason):
+- **3a** — Comment on issue
+- **3b** — Phase + labels updated
+- **3c** — Wiki linked (if wiki committed)
+- **3f** — Jira assigned (if Jira key exists)
+
+**Non-critical substeps** (warn but continue):
+- **3d** — Auto-unblock (best effort)
+- **3e** — Status dashboard (best effort)
+
+If ANY critical substep shows `❌`:
+1. Print which substeps failed and for which components
+2. **Retry the failed substep** (1 retry per substep)
+3. If retry also fails → HALT with: `"Housekeeping incomplete. Fix manually before marking tour done."`
+
+If gate passes → proceed to STEP 4.
+
+---
+
+## STEP 4 — Final Report
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  TOUR COMPLETE — FINAL REPORT                                ║
+╠══════════════════════════════════════════════════════════════╣
+║                                                              ║
+║  ┌───┬────────┬──────────────┬──────────┬────────────────┐  ║
+║  │ # │ Issue  │ Component    │ Status   │ SHA            │  ║
+║  ├───┼────────┼──────────────┼──────────┼────────────────┤  ║
+║  │ 1 │ #1000  │ ComponentA   │ ✅ Pushed │ abc1234       │  ║
+║  │ 2 │ #1002  │ ComponentC   │ ✅ Pushed │ def5678       │  ║
+║  │ 3 │ #1001  │ ComponentB   │ ❌ Dropped│ —             │  ║
+║  └───┴────────┴──────────────┴──────────┴────────────────┘  ║
+║                                                              ║
+║  Validation:                                                 ║
+║    Build:      ✅                                            ║
+║    Tests:      ✅ (20 passed)                                ║
+║    Review:     ✅                                            ║
+║    Post-Push:  ✅ (remote dep build verified)                ║
+║                                                              ║
+║  Push:                                                       ║
+║    common:       ✅ pushed (2 commits)                       ║
+║    uicomponents: ✅ pushed (2 commits)                       ║
+║    wiki:         ✅ pushed (2 commits) / ⏭ lean             ║
+║                                                              ║
+║  Issues Updated: #1000, #1002                                ║
+║  Jira Updated:   {jira.projectKey}-132507, {jira.projectKey}-132508              ║
+║  Unblocked:      #1050 (was blocked by ComponentA)           ║
+║  Dashboard:      ✅ regenerated                              ║
+║  Housekeeping:   ✅ gate passed (all 6 substeps)             ║
+║                                                              ║
+║  Tour Duration: 1h 23m                                       ║
+║  Components:    2 committed, 1 dropped                       ║
+╚══════════════════════════════════════════════════════════════╝
+```
+
+### Cleanup
+
+```bash
+# Remove tour tracker (tour is complete)
+rm -f ${TRACKER_FILE}
+```
+
+---
+
+## Error Handling
+
+| Error | Action |
+|-------|--------|
+| Tracker not found | HALT: "No tour in progress" |
+| current_step not STEP_3 | HALT: "Review not complete" |
+| No reviewed components | HALT: "Nothing to commit" |
+| Build fails | HALT — fix, then re-run |
+| Tests fail | HALT — fix failing component, then re-run |
+| Push rejected (after 3 retries) | HALT — manual conflict resolution needed |
+| Rebase conflict (generated file) | Auto-resolve: accept remote + regenerate (see 2a table) |
+| Rebase conflict (non-generated) | HALT — print conflict file, ask user to resolve |
+| Post-push build fails | Regenerate generated files in common, commit + push fix |
+| Status dashboard script missing | Warn + skip — not blocking |
+| Issue housekeeping fails (critical: 3a/3b/3c/3f) | Retry once → if still fails, HALT |
+| Issue housekeeping fails (non-critical: 3d/3e) | Warn but continue |
+| Jira unreachable | ⚠️ warn — mark 3f as skipped with reason, pass gate |
+| Completion gate fails | HALT: print failed substeps, retry once, then abort |