@codeyam/codeyam-cli 0.1.0-staging.415103 → 0.1.0-staging.435c1ad

package/codeyam-cli/templates/design-systems/neo-brutalist-design-system.md

@@ -0,0 +1,294 @@
+# Neo-Brutalist Design System
+
+> Hard-edged, warm, editorial UI. Offset shadows, bold borders, hot pink accent. For any web or mobile app.
+
+## Philosophy
+
+Heavy black borders and offset box shadows create a "printed" feel. Warm off-white base (never pure white or grey). Typography is heavy and confident. No gradients. No rounded corners over 18px.
+
+**Rules:**
+
+1. Cards always have `border: 2px solid` + offset box shadow
+2. Interactive elements "press" on hover/active (`translate(2px, 2px)`, shadow removed)
+3. Dark mode inverts backgrounds but keeps accent colors identical
+4. Dark cards/sidebar stay dark in both modes
+
+---
+
+## Colors
+
+### Light Mode
+
+```css
+[data-theme='light'] {
+  --bg-base: #f5f0e8; /* warm off-white page bg */
+  --bg-surface: #ffffff; /* cards, panels */
+  --bg-muted: #ede8de; /* subtle sections, table headers */
+  --bg-inverse: #0d0d0d; /* dark surfaces */
+
+  --text-primary: #0d0d0d;
+  --text-secondary: #666666;
+  --text-muted: #999999;
+  --text-inverse: #ffffff;
+
+  --border: #0d0d0d;
+  --border-light: #e5ddd0; /* internal dividers */
+
+  --shadow-sm: 2px 2px 0px #0d0d0d;
+  --shadow-md: 4px 4px 0px #0d0d0d;
+  --shadow-lg: 6px 6px 0px #0d0d0d;
+  --shadow-accent: 4px 4px 0px #ff90e8;
+}
+```
+
+### Dark Mode
+
+```css
+[data-theme='dark'] {
+  --bg-base: #111111;
+  --bg-surface: #1a1a1a;
+  --bg-muted: #222222;
+  --text-primary: #f5f0e8;
+  --text-secondary: #aaaaaa;
+  --text-muted: #666666;
+  --text-inverse: #0d0d0d;
+  --border: #f5f0e8;
+  --border-light: #2a2a2a;
+  --shadow-sm: 2px 2px 0px #f5f0e8;
+  --shadow-md: 4px 4px 0px #f5f0e8;
+  --shadow-lg: 6px 6px 0px #f5f0e8;
+  /* Accents unchanged. Dark cards/sidebar unchanged. */
+}
+```
+
+Respect `@media (prefers-color-scheme: dark)` on `:root:not([data-theme="light"])`.
+
+### Accents
+
+```css
+/* These don't change between modes */
+--pink: #ff90e8; /* primary: CTAs, active nav, highlights */
+--pink-light: #ffe4f8;
+--teal: #14b8a6; /* secondary: success states, live data */
+--teal-light: #ccfbf1;
+--teal-dark: #0f766e;
+--yellow: #facc15; /* tertiary: alerts, featured labels */
+--yellow-light: #fef9c3;
+--yellow-dark: #ca8a04;
+--orange: #fb923c; /* quaternary: warnings */
+```
+
+### Semantic
+
+```css
+--success-bg: #d1fae5;
+--success-text: #065f46;
+--danger-bg: #fee2e2;
+--danger-text: #991b1b;
+--warning-bg: #fef9c3;
+--warning-text: #854d0e;
+/* Dark mode: --success-bg: #052e16; --success-text: #86efac; etc. */
+```
+
+### Ordered Palette
+
+```css
+/* For any categorical sequence: tags, categories, avatars, etc. */
+--palette-1: #ff90e8; /* pink */
+--palette-2: #14b8a6; /* teal */
+--palette-3: #facc15; /* yellow */
+--palette-4: #fb923c; /* orange */
+--palette-5: #818cf8; /* purple */
+```
+
+---
+
+## Typography
+
+**Font stack:** `'DM Sans', sans-serif` (body), `'DM Serif Display', serif` (display/h1), `'DM Mono', monospace` (code)
+
+| Style       | Size                     | Weight              | Notes                                                 |
+| ----------- | ------------------------ | ------------------- | ----------------------------------------------------- |
+| Display     | `clamp(28px, 4vw, 48px)` | 400 (Serif Display) | `letter-spacing: -1.5px; line-height: 1.1`            |
+| H1          | `clamp(22px, 3vw, 36px)` | 900                 | `letter-spacing: -1px`                                |
+| H2          | 20px                     | 900                 | `letter-spacing: -0.5px`                              |
+| H3          | 15px                     | 700                 |                                                       |
+| Label       | 11px                     | 700                 | `uppercase; letter-spacing: 1px; color: --text-muted` |
+| Body        | 14px                     | 400                 | `line-height: 1.6`                                    |
+| Body SM     | 13px                     | 400                 | `line-height: 1.5`                                    |
+| Large Value | `clamp(22px, 3vw, 32px)` | 900                 | `letter-spacing: -1px` — for emphasized numbers       |
+
+**Common pattern — eyebrow + title:** Label above H2 in almost every section.
+
+---
+
+## Spacing & Radius
+
+Base unit: 4px. Scale: 4, 8, 12, 16, 20, 24, 28, 32, 40, 48px.
+
+| Context                | Value       |
+| ---------------------- | ----------- |
+| Card padding (compact) | `16px 18px` |
+| Card padding (default) | `22px 24px` |
+| Card padding (large)   | `28px 28px` |
+| Grid gap               | 18px        |
+
+```css
+--radius-sm: 8px;
+--radius-md: 12px;
+--radius-lg: 18px; /* cards — max radius in the system */
+--radius-pill: 999px; /* badges, avatars */
+```
+
+---
+
+## Layout
+
+### Common Patterns
+
+- **Sidebar:** 220px fixed left, `--bg-inverse`, always dark in both modes
+- **Top nav:** Sticky, 64px height, `--bg-base`, bottom border
+- **Bottom nav (mobile):** Fixed, 64px, `--pink-light` active bg. Add `env(safe-area-inset-bottom)` padding
+- **Main content:** flex-1, `--bg-base`, padding `36px 40px`
+
+### Navigation States
+
+- Logo mark: 36px accent square + bold name
+- Nav items: 14px, `10px 14px` padding, rounded 10px. Hover/active → `--pink` bg + dark text
+- Top nav active link: inverse bg pill
+
+### Mobile / Small Viewport
+
+- Single column, 16px padding
+- Cards stack vertically, buttons full-width in forms
+- Reduce shadows to `--shadow-sm`
+
+---
+
+## Components
+
+### Card
+
+```css
+.card {
+  background: var(--bg-surface);
+  border: 2px solid var(--border);
+  border-radius: var(--radius-lg);
+  padding: 22px 24px;
+  box-shadow: var(--shadow-md);
+  position: relative;
+  overflow: hidden;
+}
+```
+
+**Variants:** `default` (white), `dark` (inverse bg + accent shadow), `pink`, `teal`, `yellow`, `muted` (base bg).
+
+**Interactive states:** hover → `translateY(-3px)` + `shadow-lg`. Active → `translate(2px, 2px)` + `shadow-sm`.
+
+### Value Card
+
+Card with: decorative accent circle (top-right, 64px, 20% opacity), icon box (40px, accent bg, 2px border, rounded 10px), label (eyebrow), emphasized value (Large Value style), optional trend badge (pill, success/danger colors).
+
+### Button
+
+```css
+.btn {
+  padding: 11px 22px;
+  border-radius: var(--radius-md);
+  font-weight: 700;
+  font-size: 14px;
+  border: 2px solid var(--border);
+}
+.btn:hover {
+  transform: translate(-1px, -1px);
+}
+.btn:active {
+  transform: translate(2px, 2px);
+  box-shadow: none;
+}
+```
+
+| Variant   | Background     | Text             | Border/Shadow             |
+| --------- | -------------- | ---------------- | ------------------------- |
+| Primary   | `--pink`       | `--text-primary` | `--shadow-md`             |
+| Secondary | `--bg-surface` | `--text-primary` | `--shadow-sm`             |
+| Teal      | `--teal`       | `--text-primary` | `--shadow-md`             |
+| Yellow    | `--yellow`     | `--text-primary` | `--shadow-md`             |
+| Dark      | `--bg-inverse` | `--text-inverse` | `--shadow-accent`         |
+| Ghost     | transparent    | `--text-primary` | none; hover: `--bg-muted` |
+
+| Size         | Padding     | Font Size |
+| ------------ | ----------- | --------- |
+| SM           | `7px 14px`  | 12px      |
+| MD (default) | `11px 22px` | 14px      |
+| LG           | `15px 30px` | 16px      |
+
+Icon-only: 40x40, no padding, `--radius-sm`.
+
+### Badge / Pill
+
+`padding: 3px 10px; border-radius: 999px; font-size: 11px; font-weight: 700; border: 1.5px solid currentColor`. Semantic variants: success, danger, warning, pink, teal, yellow, neutral. Solid variant: inverse bg+text.
+
+### Input
+
+`padding: 11px 16px; border: 2px solid var(--border); border-radius: var(--radius-md); font-size: 14px`. Focus: `box-shadow: 0 0 0 3px var(--pink)`. Input-group: input + button joined with zero'd inner radii.
+
+### Table
+
+Container: card shell (border, radius-lg, shadow-md, overflow hidden). Header: `--bg-muted`, 11px uppercase labels. Rows: `16px 28px` padding, `--border-light` divider, hover → muted bg.
+
+### Progress Bar
+
+Track: 12px height, `--bg-muted`, pill radius, 2px border. Fill: pill radius, accent color. Animate: `width 0.8s cubic-bezier(0.34, 1.56, 0.64, 1)`.
+
+### Avatar
+
+Square-ish (`--radius-sm`), 2px border. Sizes: 28/36/48px. Cycle through ordered palette colors.
+
+### Tag / Chip
+
+`padding: 5px 12px; border-radius: 999px; border: 2px solid var(--border); font-size: 13px; font-weight: 600`. Hover → pink bg. Active → inverse bg+text.
+
+### Tooltip
+
+`background: --bg-inverse; border: 2px solid --pink; border-radius: --radius-md; padding: 10px 16px; color: --text-inverse; font-size: 13px`. Bold label + bold value.
+
+---
+
+## Motion
+
+```css
+--transition-fast: 120ms ease; /* button press */
+--transition-base: 180ms ease; /* card hover, general */
+```
+
+Bouncy and tactile — elements lift and press. Staggered fade-up on page load:
+
+```css
+@keyframes fadeUp {
+  from {
+    opacity: 0;
+    transform: translateY(12px);
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+/* animation: fadeUp 0.4s ease forwards; delay: n * 0.05s */
+```
+
+---
+
+## Checklist
+
+- [ ] Background is `#F5F0E8` (light) or `#111111` (dark) — never pure white or grey
+- [ ] Every card has 2px border + offset box shadow
+- [ ] Interactive elements press-shift on :active
+- [ ] DM Sans (body) + DM Serif Display (headlines) + DM Mono (code)
+- [ ] At least one pink element visible on every screen
+- [ ] Labels: 11px uppercase, letter-spacing 1px
+- [ ] Badges are pill-shaped with border
+- [ ] Dark sidebar/cards unchanged in dark mode
+- [ ] No gradients anywhere
+- [ ] Spacing follows 4px grid

package/codeyam-cli/templates/editor-step-hook.py

@@ -1,6 +1,6 @@
 #!/usr/bin/env python3
 """
-PostToolUse + Stop hook for editor mode step tracking.
+PostToolUse + Stop + UserPromptSubmit hook for editor mode step tracking.
 
 Reads .codeyam/editor-step.json and prints a reminder about the current step.
 Logs each firing to .codeyam/logs/editor-log.jsonl.
@@ -15,28 +15,70 @@ from datetime import datetime, timezone
 
 STEP_LABELS = {
     1: "Plan",
-    2: "Prototype",
-    3: "Confirm",
-    4: "Deconstruct",
-    5: "Glossary",
-    6: "Analyze",
-    7: "App Scenarios",
-    8: "User Scenarios",
-    9: "Verify",
-    10: "Review",
+    2: "Prepare",
+    3: "Prototype",
+    4: "Verify Prototype",
+    5: "Confirm",
+    6: "Deconstruct",
+    7: "Extract",
+    8: "Glossary",
+    9: "Analyze",
+    10: "App Scenarios",
+    11: "User Scenarios",
+    12: "Verify",
+    13: "Journal",
+    14: "Review",
+    15: "Present",
+    16: "Commit",
+    17: "Finalize",
+    18: "Push",
 }
 
 STEP_RESTRICTIONS = {
     1: "Do NOT write any code. Plan and describe only. Wait for user confirmation.",
-    2: "Do NOT create scenarios or run codeyam analyze. Build fast — working prototype with real data.",
-    3: "Present a selection menu (AskUserQuestion) for confirmation. Do NOT refactor or create scenarios until approved.",
-    4: "Do NOT create scenarios. Write a failing test FIRST, then extract. TDD only.",
-    5: "Do NOT write application code or scenarios. Update the glossary only.",
-    6: "Run codeyam analyze for each file. Verify all pass. Fix any failures before proceeding.",
-    7: "Do NOT modify application code. Create and register app-level scenarios only.",
-    8: "Do NOT modify application code. Create user-persona scenarios only (or skip if no users).",
-    9: "Verify entity screenshots (/api/editor-entity-status) AND editor scenarios. After ANY code fix, re-run codeyam analyze on affected files. Fix only — do NOT add features.",
-    10: "Verify ALL screenshots exist and NO client-side errors (/api/editor-client-errors), then present selection menu (AskUserQuestion): Save or make changes.",
+    2: "Do NOT write any code or build features. Set up the project and prepare the database only.",
+    3: "Do NOT create scenarios or run codeyam analyze. Build fast — working prototype with real data.",
+    4: "Verify the prototype works. Do NOT add features — only fix broken functionality.",
+    5: "Present a selection menu (AskUserQuestion) for confirmation. Do NOT refactor or create scenarios until approved.",
+    6: "Do NOT write any code. Read every file, identify all extractable pieces, write a numbered plan. Planning only.",
+    7: "Execute the extraction plan from step 6. Components first (no tests), then library functions via TDD. Page files must contain ZERO direct JSX.",
+    8: "Do NOT write application code or scenarios. Update the glossary only.",
+    9: "Create isolation routes for visual components, run tests for library functions. Register component scenarios via codeyam editor register.",
+    10: "Do NOT modify application code. Create and register app-level scenarios only.",
+    11: "Do NOT modify application code. Create user-persona scenarios only (or skip if no users).",
+    12: "Verify component isolation screenshots AND editor scenarios. After ANY code fix, re-register affected components. Fix only — do NOT add features.",
+    13: "Create or update the journal entry for this feature. Do NOT create a duplicate — check if one exists first.",
+    14: "Verify ALL screenshots exist and NO client-side errors (/api/editor-client-errors). Run codeyam editor audit. Do not proceed until all checks pass.",
+    15: "Show the results panel, present summary, then selection menu (AskUserQuestion): Save or make changes.",
+    16: "Hide the results panel and commit all changes. Do NOT push — that happens in step 18.",
+    17: "Update the journal entry with the commit SHA and amend the commit to include the journal update.",
+    18: "Check for a git remote and offer to push. WAIT for the user's answer before starting the next feature.",
+}
+
+MIGRATION_STEP_LABELS = {
+    1: "Survey",
+    2: "App Scenarios",
+    3: "Component Scenarios",
+    4: "Preview",
+    5: "Discuss",
+    6: "Decompose",
+    7: "Extract",
+    8: "Recapture",
+    9: "Journal",
+    10: "Present",
+}
+
+MIGRATION_STEP_RESTRICTIONS = {
+    1: "Survey the page and start the dev server. Read all files and map data flow. Do NOT register scenarios yet.",
+    2: "Set up seed adapter if needed, then register application scenarios for the ACTUAL page route with seed data.",
+    3: "Create isolation routes and register component scenarios for individual visual components.",
+    4: "Verify screenshots and show results to the user. Do NOT modify application code.",
+    5: "Assess complexity and ask user about decomposition. Wait for user decision before proceeding.",
+    6: "Plan-only. Identify all extractions, mark existing components as REUSE. Do NOT write code.",
+    7: "Execute the extraction plan. Components first, then functions via TDD.",
+    8: "Update glossary, re-register scenarios after code changes, verify screenshots. Fix issues only.",
+    9: "Create the journal entry for this page's migration.",
+    10: "Show results, present summary, commit or make changes. After commit run `codeyam editor migrate complete` then `codeyam editor migrate next`.",
 }
 
 
@@ -56,25 +98,67 @@ def log_event(project_dir, event, data=None):
 
 
 def detect_event():
-    """Detect whether this is a PostToolUse or Stop hook from stdin."""
+    """Detect whether this is a PostToolUse, Stop, or UserPromptSubmit hook from stdin."""
     try:
         raw = sys.stdin.read()
         if not raw.strip():
             return "unknown", {}
         data = json.loads(raw)
-        # PostToolUse has tool_name; Stop has stop_hook_active
+        # PostToolUse has tool_name; Stop has stop_hook_active; UserPromptSubmit has prompt
         if "tool_name" in data:
             return "post_tool_use", data
         elif "stop_hook_active" in data:
             return "stop", data
+        elif "prompt" in data:
+            return "user_prompt", data
         return "unknown", data
     except Exception:
         return "unknown", {}
 
 
 def main():
+    # Only run in editor Build sessions. The env var is set by the terminal
+    # server when launching Claude in editor mode. Without this guard, hooks
+    # fire in every Claude session in the project (scenario editing, bare
+    # claude, etc.) and inject unwanted step restrictions.
+    if not os.environ.get("CODEYAM_EDITOR_ACTIVE"):
+        return
+
     project_dir = os.environ.get("CLAUDE_PROJECT_DIR", os.getcwd())
     state_path = os.path.join(project_dir, ".codeyam", "editor-step.json")
+    prompt_path = os.path.join(project_dir, ".codeyam", "editor-user-prompt.txt")
+
+    # Detect event early so we can capture the user prompt even before state exists
+    event_type, event_data = detect_event()
+
+    # Capture the user's feature request prompt.
+    # Write when: (a) no prompt file yet, (b) no state file (between features),
+    # or (c) previous feature is done (step >= 18). This ensures the prompt
+    # is refreshed for each new feature instead of persisting stale text.
+    # Skip slash commands (e.g. /codeyam-editor) — they aren't user prompts.
+    if event_type == "user_prompt":
+        prompt_text = event_data.get("prompt", "").strip()
+        if prompt_text and not prompt_text.startswith("/"):
+            should_capture = not os.path.exists(prompt_path)
+            if not should_capture:
+                # Overwrite stale prompt when between features
+                if not os.path.exists(state_path):
+                    should_capture = True
+                else:
+                    try:
+                        with open(state_path, "r") as f:
+                            prev = json.load(f)
+                        if prev.get("step", 0) >= 18:
+                            should_capture = True
+                    except Exception:
+                        pass
+            if should_capture:
+                try:
+                    os.makedirs(os.path.dirname(prompt_path), exist_ok=True)
+                    with open(prompt_path, "w") as f:
+                        f.write(prompt_text)
+                except Exception:
+                    pass  # Best-effort
 
     if not os.path.exists(state_path):
         return
@@ -88,23 +172,115 @@ def main():
     step = state.get("step")
     label = state.get("label", "Unknown")
     feature = state.get("feature", "")
+    migration = state.get("migration")  # Optional migration context
 
     if not step:
         return
 
-    event_type, event_data = detect_event()
+    # ── Task tracking ──────────────────────────────────────────────────
+    # Track whether TaskCreate was called between step transitions.
+    # If Claude advances to the next step without creating a task, block it.
+    task_tracking_path = os.path.join(project_dir, ".codeyam", "editor-task-tracking.json")
+
+    if event_type == "post_tool_use":
+        tool_name = event_data.get("tool_name", "")
+
+        # Record when TaskCreate is called
+        if tool_name == "TaskCreate":
+            try:
+                tracking = {}
+                if os.path.exists(task_tracking_path):
+                    with open(task_tracking_path, "r") as f:
+                        tracking = json.load(f)
+                tracking["taskCreated"] = True
+                with open(task_tracking_path, "w") as f:
+                    json.dump(tracking, f)
+            except Exception:
+                pass
 
     # Log the hook firing
     log_data = {"step": step, "label": label, "feature": feature, "hook": event_type}
+    if migration:
+        log_data["migration"] = True
     if event_type == "post_tool_use":
         log_data["tool"] = event_data.get("tool_name", "")
     log_event(project_dir, "hook", log_data)
 
-    restriction = STEP_RESTRICTIONS.get(step, "")
-    next_cmd = f"codeyam editor {step + 1}" if step < 10 else "codeyam editor 1"
+    # Use migration-specific labels/restrictions when in migration mode
+    if migration:
+        restriction = MIGRATION_STEP_RESTRICTIONS.get(step, "")
+        next_cmd = f"codeyam editor migrate {step + 1}" if step < 10 else "codeyam editor migrate next"
+    else:
+        restriction = STEP_RESTRICTIONS.get(step, "")
+        next_cmd = f"codeyam editor {step + 1}" if step < 18 else "codeyam editor 1"
 
+    # UserPromptSubmit: concise workflow reminder injected before Claude processes the user's message
+    if event_type == "user_prompt":
+        mode_label = "Migration Mode" if migration else "Editor Mode"
+        page_info = ""
+        if migration:
+            page_name = migration.get("pageName", "")
+            page_idx = migration.get("pageIndex", 0)
+            total = migration.get("totalPages", 0)
+            page_info = f" — Page {page_idx + 1}/{total} ({page_name})"
+
+        lines = [
+            f'<user-prompt-submit-hook>',
+            f'{mode_label} — Step {step} ({label}): "{feature}"{page_info}',
+        ]
+
+        # Include the active scenario so Claude knows what the user is looking at
+        active_scenario_path = os.path.join(project_dir, ".codeyam", "active-scenario.json")
+        try:
+            with open(active_scenario_path, "r") as f:
+                active = json.load(f)
+            scenario_name = (
+                active.get("scenarioName")
+                or active.get("scenarioSlug", "").replace("_", " ")
+            )
+            if scenario_name:
+                lines.append(
+                    f'The user is currently viewing scenario: "{scenario_name}". '
+                    "Assume any feedback refers to this scenario unless they say otherwise."
+                )
+        except (IOError, json.JSONDecodeError):
+            pass
+
+        if migration and step == 8:
+            lines.append(
+                "If the user is requesting changes (even indirectly), "
+                "run `codeyam editor change` BEFORE making any modifications. "
+                "The change workflow ensures Working Session Results are shown to the user. "
+                "If the user chose to commit, run `codeyam editor migrate next` to advance to the next page."
+            )
+        elif step in (15, 16, 17, 18) and not migration:
+            lines.append(
+                "If the user is requesting changes (even indirectly), "
+                "run `codeyam editor change` BEFORE making any modifications "
+                "(code, scenarios, data, styles — everything). "
+                "The change command gives you the post-change checklist. "
+                "The change workflow ensures Working Session Results are shown to the user. "
+                "If the user chose to commit, run `codeyam editor 16` to advance to the commit step."
+            )
+        elif migration:
+            lines.append(
+                f"You are on migration step {step}. Follow the `codeyam editor migrate` workflow. "
+                f"Do NOT skip ahead or make changes outside the current step."
+            )
+        else:
+            lines.append(
+                f"You are on step {step}. Follow the `codeyam editor` workflow. "
+                f"Do NOT skip ahead or make changes outside the current step."
+            )
+        if restriction:
+            lines.append(restriction)
+        lines.append('</user-prompt-submit-hook>')
+        print("\n".join(lines))
+        return
+
+    mode_label = "Migration Mode" if migration else "Editor Mode"
     lines = [
-        f'Editor Mode \u2014 Step {step} ({label}): "{feature}"',
+        f'{mode_label} \u2014 Step {step} ({label}): "{feature}"',
     ]
     if restriction:
         lines.append(restriction)
@@ -115,18 +291,40 @@ def main():
         BOLD_CYAN = "\033[1;36m"
         DIM = "\033[2m"
         RESET = "\033[0m"
-        tracker = [f"{DIM}  \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510{RESET}"]
-        for i in range(1, 11):
-            lbl = STEP_LABELS[i].ljust(28)
-            num = f" {i}" if i < 10 else f"{i}"
-            content = f"{num}. {lbl}"
-            if i < step:
-                tracker.append(f"{DIM}  \u2502{RESET}{GREEN}  \u2713  {content}{RESET}{DIM}\u2502{RESET}")
-            elif i == step:
-                tracker.append(f"{DIM}  \u2502{RESET}{BOLD_CYAN}  \u2192  {content}{RESET}{DIM}\u2502{RESET}")
-            else:
-                tracker.append(f"{DIM}  \u2502  \u25cb  {content}\u2502{RESET}")
-        tracker.append(f"{DIM}  \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518{RESET}")
+
+        if migration:
+            # Migration progress tracker (10 steps)
+            page_name = migration.get("pageName", "")
+            page_idx = migration.get("pageIndex", 0)
+            total = migration.get("totalPages", 0)
+            tracker = [f"{DIM}  Migration: Page {page_idx + 1}/{total} ({page_name}){RESET}"]
+            tracker.append(f"{DIM}  \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510{RESET}")
+            for i in range(1, 11):
+                lbl = MIGRATION_STEP_LABELS[i].ljust(28)
+                num = f" {i}" if i < 10 else f"{i}"
+                cntnt = f"{num}. {lbl}"
+                if i < step:
+                    tracker.append(f"{DIM}  \u2502{RESET}{GREEN}  \u2713  {cntnt}{RESET}{DIM}\u2502{RESET}")
+                elif i == step:
+                    tracker.append(f"{DIM}  \u2502{RESET}{BOLD_CYAN}  \u2192  {cntnt}{RESET}{DIM}\u2502{RESET}")
+                else:
+                    tracker.append(f"{DIM}  \u2502  \u25cb  {cntnt}\u2502{RESET}")
+            tracker.append(f"{DIM}  \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518{RESET}")
+        else:
+            # Standard progress tracker (18 steps)
+            tracker = [f"{DIM}  \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510{RESET}"]
+            for i in range(1, 19):
+                lbl = STEP_LABELS[i].ljust(28)
+                num = f" {i}" if i < 10 else f"{i}"
+                content = f"{num}. {lbl}"
+                if i < step:
+                    tracker.append(f"{DIM}  \u2502{RESET}{GREEN}  \u2713  {content}{RESET}{DIM}\u2502{RESET}")
+                elif i == step:
+                    tracker.append(f"{DIM}  \u2502{RESET}{BOLD_CYAN}  \u2192  {content}{RESET}{DIM}\u2502{RESET}")
+                else:
+                    tracker.append(f"{DIM}  \u2502  \u25cb  {content}\u2502{RESET}")
+            tracker.append(f"{DIM}  \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518{RESET}")
+
         lines.append("Present this progress tracker to the user (copy verbatim):")
         lines.extend(tracker)
         lines.append(
@@ -134,6 +332,33 @@ def main():
             "\u2713 (done) or \u2717 (skipped + reason)."
         )
 
+    if event_type == "stop" and ((step in (15, 16) and not migration) or (step == 8 and migration)):
+        import subprocess as _sp
+        try:
+            _result = _sp.run(
+                ["git", "status", "--porcelain"],
+                cwd=project_dir,
+                capture_output=True, text=True, timeout=5
+            )
+            has_uncommitted = bool(_result.stdout.strip())
+        except Exception:
+            has_uncommitted = False
+
+        if has_uncommitted:
+            lines.append(
+                "\n\033[1;31m⚠️  You have uncommitted changes but haven't shown Working Session Results.\033[0m"
+            )
+            lines.append(
+                f"\033[31mRun `codeyam editor change` if you haven't already, then complete the "
+                f"checklist and run `{'codeyam editor migrate 8' if migration else 'codeyam editor 15'}` to show results to the user.\033[0m"
+            )
+
+    if event_type == "stop":
+        lines.append(
+            f"\n\033[2mReminder: Only use `codeyam editor` subcommands in the Build terminal. "
+            f"Follow `codeyam editor steps` when changing code.\033[0m"
+        )
+
     lines.append(f"When this step is complete, run: {next_cmd}")
 
     print("\n".join(lines))