@mmerterden/multi-agent-pipeline 11.2.0 → 11.3.0

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

@@ -1,716 +0,0 @@
----
-name: performance-iteration-commit-all
-description: 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.
----
-
-# /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 FeatureXInviteList                                     ║
-║    3a Comment:    ✅                                         ║
-║    3b Phase:      ✅ → Documentation                        ║
-║    3c Wiki Link:  ✅                                         ║
-║    3d Unblock:    ⏭ (none blocked)                          ║
-║    3e Dashboard:  ✅ regenerated                             ║
-║    3f Jira:       ✅ {jira.projectKey}-132507                          ║
-║                                                              ║
-║  #309 FeatureXVoucherGroup                                   ║
-║    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 |