project-iris 0.6.7 → 0.6.9

package/flows/aidlc/skills/construction/bolt-start.md

@@ -195,363 +195,12 @@ Scan the bolt's unit name, story titles, and story descriptions for these signal
 
 This is not a hard requirement - use judgment on which principles apply to the current task.
 
-### 4c. Figma Frames (Conditional - Per Story)
+### 4c. Figma Design Integration (Conditional - Per Story)
 
-**Check each story's `figma_frames` field in frontmatter.**
+**⛔ HARD GATE**: UI stories with `figma_frames` MUST have design specs extracted before coding. Figma scope MUST be enforced per-story.
 
-If a story has `figma_frames` (array of Figma URLs), use Figma MCP to fetch design specs and interaction flows before implementing.
-
-**Supported Figma URL format:**
-
-- Design file: `https://www.figma.com/design/{file-id}/{file-name}?node-id={node-id}&t={token}`
-
-**When `figma_frames` is present:**
-
-```text
-┌─────────────────────────────────────────────────────────────┐
-│  FIGMA FRAMES DETECTED                                       │
-│                                                              │
-│  Story: {story-id}                                          │
-│  Frames: {count} Figma frame(s)                             │
-│                                                              │
-│  Action: Use Figma MCP to fetch design and flow data        │
-└─────────────────────────────────────────────────────────────┘
-```
-
-**Figma MCP Integration:**
-
-Use the Figma MCP tool to read design specifications. The MCP server is configured via:
-`claude mcp add --transport http figma https://mcp.figma.com/mcp`
-
-### 4c-1. Extract Design Specs (Per Frame)
-
-For EACH Figma frame URL, extract:
-
-```text
-┌─────────────────────────────────────────────────────────────┐
-│  DESIGN SPECS EXTRACTION                                     │
-│                                                              │
-│  For each frame, extract:                                    │
-│                                                              │
-│  1. Layout & Structure                                       │
-│     - Component hierarchy (parent/child relationships)       │
-│     - Spacing values (padding, margins, gaps)                │
-│     - Alignment and positioning                              │
-│                                                              │
-│  2. Visual Styling                                           │
-│     - Colors (exact hex values, opacity)                     │
-│     - Typography (font family, size, weight, line height)    │
-│     - Border radius, shadows, effects                        │
-│                                                              │
-│  3. Component States                                         │
-│     - Default, hover, active, disabled, focus states         │
-│     - Loading states and skeletons                           │
-│     - Error and success states                               │
-│                                                              │
-│  4. Responsive Variants (if defined)                         │
-│     - Mobile, tablet, desktop variations                     │
-│     - Breakpoint-specific layouts                            │
-└─────────────────────────────────────────────────────────────┘
-```
-
-### 4c-2. Extract Interaction Flows
-
-**Figma prototype connections MAY define interaction flows - but many designs don't have them.**
-
-**Step 1: Check for prototype connections via Figma MCP**
-
-```text
-┌─────────────────────────────────────────────────────────────┐
-│  PROTOTYPE CONNECTION CHECK                                  │
-│                                                              │
-│  Query Figma MCP for prototype data on each frame.           │
-│  Prototype connections include:                              │
-│  - Navigation triggers (which element → which frame)         │
-│  - Transition types (push, overlay, swap)                    │
-│  - Overlay settings (dismiss on click outside, etc.)         │
-└─────────────────────────────────────────────────────────────┘
-```
-
-**Step 2: Determine flow source (in priority order)**
-
-```text
-┌─────────────────────────────────────────────────────────────┐
-│  FLOW SOURCE PRIORITY                                        │
-│                                                              │
-│  1. Figma prototype connections (if they exist)              │
-│     → Extract automatically from Figma MCP                   │
-│                                                              │
-│  2. Manual flow definition in story (if provided)            │
-│     → Read from story's `interaction_flows` field            │
-│                                                              │
-│  3. No flow information available                            │
-│     → Ask user OR infer from button labels                   │
-└─────────────────────────────────────────────────────────────┘
-```
-
-### 4c-2a. If Prototype Connections Exist in Figma
-
-Extract interaction data:
-
-- Navigation actions (which element → destination frame)
-- Overlay triggers (modals, bottom sheets, tooltips)
-- Transition types and animations
-- Dismiss behaviors
-
-### 4c-2b. If NO Prototype Connections in Figma
-
-**Check story for manual `interaction_flows` definition:**
-
-```yaml
-# In story frontmatter or body
-interaction_flows:
-  - screen: login-form
-    interactions:
-      - element: "Sign Up button"
-        action: navigate
-        target: registration-form
-      - element: "Forgot Password link"
-        action: overlay
-        target: forgot-password-modal
-```
-
-**If manual flows exist:** Use them to build the interaction map.
-
-**If NO flows defined anywhere:**
-
-```text
-┌─────────────────────────────────────────────────────────────┐
-│  NO INTERACTION FLOW DEFINED                                 │
-│                                                              │
-│  Story: {story-id}                                          │
-│  Figma frames: {count} (no prototype connections found)     │
-│  Manual flows: Not defined                                   │
-│                                                              │
-│  Options:                                                    │
-│  1 - Define interactions now (I'll ask about each button)   │
-│  2 - Infer from button labels (best guess)                  │
-│  3 - Implement as static screens (no navigation wiring)     │
-└─────────────────────────────────────────────────────────────┘
-```
-
-**Option 1 - Define interactions:** Ask user about each interactive element:
-
-```text
-I found these interactive elements in the Figma frames:
-- "Sign Up" button
-- "Forgot Password" link
-- "Login" button
-
-For each element, what should happen on click?
-```
-
-**Option 2 - Infer from labels:** Make reasonable assumptions:
-
-- "Submit", "Save", "Login" → form submission
-- "Cancel", "Close", "X" → close/go back
-- "Sign Up", "Register" → navigate to registration
-- "Learn More", "View Details" → navigate to detail screen
-
-**Option 3 - Static screens:** Implement visuals only, user wires navigation later.
-
-### 4c-2c. Output: Interaction Map
-
-After determining flows (from any source), build the interaction map:
-
-```markdown
-### Interaction Map: {story-id}
-
-**Flow Source:** {Figma prototype | Manual definition | Inferred | Static}
-
-#### Screen: {frame-name-1}
-| Element | Action | Target | Type |
-|---------|--------|--------|------|
-| "Sign Up" button | on-click | registration-form | navigate |
-| "Forgot Password" link | on-click | forgot-password-modal | overlay |
-
-#### Navigation Flow
-
-    login-screen
-    ├── "Sign Up" → registration-form
-    ├── "Forgot Password" → forgot-password-modal (overlay)
-    └── "Login" → dashboard (on success)
-```
-
-### 4c-3. If Figma MCP is not available
-
-```text
-⚠️ Figma MCP not configured - cannot fetch design specs
-   Story {story-id} has figma_frames but Figma MCP is unavailable.
-
-   Options:
-   1 - Continue using ui-patterns.md guidelines (design may not match)
-   2 - Stop and configure Figma MCP first
-
-   To configure: Run `claude mcp add --transport http figma https://mcp.figma.com/mcp`
-   Then authenticate via `/mcp` in Claude Code.
-```
-
-### 4c-4. Design-First Implementation Rule
-
-**⛔ HARD GATE - UI FIDELITY ENFORCEMENT**
-
-```text
-┌─────────────────────────────────────────────────────────────┐
-│  UI FIDELITY - NON-NEGOTIABLE                               │
-│                                                              │
-│  ⛔ FORBIDDEN: Approximating colors (use exact hex values)  │
-│  ⛔ FORBIDDEN: Guessing spacing (use exact px/rem values)   │
-│  ⛔ FORBIDDEN: Substituting fonts (use exact font family)   │
-│  ⛔ FORBIDDEN: Changing layout structure from Figma         │
-│  ⛔ FORBIDDEN: Adding/removing elements not in design       │
-│                                                              │
-│  The implementation MUST be pixel-perfect to the Figma.     │
-│  If deviation is required, STOP and ask the user first.     │
-└─────────────────────────────────────────────────────────────┘
-```
-
-When a story has `figma_frames`:
-
-1. **Fetch ALL frames for THIS story FIRST** before writing any UI code
-2. **Build the interaction map** to understand the complete flow
-3. **Extract EXACT values** from Figma MCP response:
-   - Colors: Use exact hex values (e.g., `#1A1A1A`, not "dark gray")
-   - Spacing: Use exact pixel/rem values (e.g., `16px`, not "some padding")
-   - Typography: Use exact font-family, font-size, font-weight, line-height
-   - Border radius: Use exact values (e.g., `8px`, not "rounded")
-   - Shadows: Use exact shadow values from design
-4. **Match the design exactly** - Figma specs override ui-patterns.md defaults
-5. **Implement navigation** - wire up all interactions as defined in Figma
-6. **If you MUST deviate** from design:
-   - STOP and ask the user first
-   - Document the deviation and reason in code comments
-   - Get explicit approval before proceeding
-
-**Post-Implementation Fidelity Check:**
-
-After implementing UI code, verify against Figma:
-
-```text
-┌─────────────────────────────────────────────────────────────┐
-│  FIDELITY CHECKLIST                                          │
-│                                                              │
-│  □ Colors match exactly (compare hex values)                │
-│  □ Spacing matches exactly (padding, margin, gap)           │
-│  □ Typography matches exactly (font, size, weight)          │
-│  □ Layout structure matches (flexbox/grid arrangement)      │
-│  □ Component hierarchy matches (nesting, order)             │
-│  □ Interactive states implemented (hover, focus, active)    │
-│  □ Responsive behavior matches (if defined in Figma)        │
-└─────────────────────────────────────────────────────────────┘
-```
-
-### 4c-5. When NO `figma_frames` Exists (Story-Level Collection)
-
-**⛔ HARD GATE - DO NOT SKIP FOR UI STORIES**
-
-If a story has UI signals (detected in Step 4b) but NO `figma_frames` in frontmatter:
-
-```text
-┌─────────────────────────────────────────────────────────────┐
-│  UI STORY WITHOUT FIGMA FRAMES                              │
-│                                                              │
-│  Story: {story-id} - {title}                                │
-│  UI Detected: {signal found}                                │
-│  Figma Frames: Not defined in story frontmatter             │
-│                                                              │
-│  Would you like to provide Figma design for THIS story?     │
-│                                                              │
-│  1 - Yes, I'll provide Figma frame URL(s) for this story   │
-│  2 - No, continue without Figma (use ui-patterns.md)       │
-└─────────────────────────────────────────────────────────────┘
-```
-
-**If user selects "Yes":**
-
-```text
-Please provide Figma frame URL(s) for story: {story-id}
-
-⚠️  IMPORTANT: Only provide frames relevant to THIS story's scope:
-    {list acceptance criteria titles from story}
-
-Supported format:
-- Design file: https://www.figma.com/design/{file-id}/{name}?node-id={node-id}&t={token}
-
-Enter URL(s) (one per line, empty line to finish):
-```
-
-**After collecting URLs:**
-
-1. Update the story file's `figma_frames` frontmatter with provided URLs
-2. Proceed with Figma MCP integration (Step 4c-1 onwards)
-
-**If user selects "No":**
-
-Fall back to ui-patterns.md guidelines (Step 4b). Generate UI based on:
-
-1. Acceptance criteria in the story
-2. Project's ux-guide.md (component library, styling approach)
-3. ui-patterns.md design principles
-
-### 4c-6. Figma Scope Enforcement (CRITICAL)
-
-**⛔ HARD GATE - STORY SCOPE BOUNDARY**
-
-```text
-┌─────────────────────────────────────────────────────────────┐
-│  FIGMA SCOPE ENFORCEMENT - NON-NEGOTIABLE                   │
-│                                                              │
-│  ⛔ FORBIDDEN: Implementing screens beyond current story    │
-│  ⛔ FORBIDDEN: Building "all screens" from a Figma file     │
-│  ⛔ FORBIDDEN: Assuming Figma file scope = story scope      │
-│                                                              │
-│  Each story has its own scope. Figma frames provided for a  │
-│  story ONLY apply to that story's acceptance criteria.      │
-└─────────────────────────────────────────────────────────────┘
-```
-
-**When user provides a Figma URL:**
-
-**Step 1: Check if URL has multiple distinct screens/frames**
-
-**Step 2: If multiple screens detected**, ask user to map them:
-
-```text
-┌─────────────────────────────────────────────────────────────┐
-│  MULTIPLE SCREENS DETECTED                                   │
-│                                                              │
-│  The Figma URL contains {n} distinct screens/frames.        │
-│  Current story: {story-id} - {title}                        │
-│                                                              │
-│  Which screen(s) apply to THIS story?                       │
-│                                                              │
-│  Detected frames:                                            │
-│  1. {frame-name-1} (node-id: {id})                          │
-│  2. {frame-name-2} (node-id: {id})                          │
-│  3. {frame-name-3} (node-id: {id})                          │
-│  ...                                                         │
-│                                                              │
-│  Enter frame numbers for this story (e.g., "1, 2"):         │
-└─────────────────────────────────────────────────────────────┘
-```
-
-**Step 3: Only implement the selected frames** for current story
-
-**Step 4: Other frames belong to other stories** - do NOT implement them now
-
-**Scope Validation Before Implementation:**
-
-Before writing any UI code, verify:
-
-```text
-Story: {story-id}
-Acceptance Criteria: {list from story file}
-Figma Frames Selected: {list selected frames}
-
-✓ All selected frames relate to this story's acceptance criteria
-✓ No frames selected that belong to other stories
-✓ Scope is bounded to THIS story only
-```
+> **Read `.iris/aidlc/skills/construction/refs/figma-integration.md` and follow its instructions.**
+> This covers: frame extraction, design specs, interaction flows, UI fidelity, scope enforcement.
 
 ### 5. Determine Current Stage
 
@@ -681,165 +330,12 @@ Each bolt type specifies its own stages and required artifacts. Refer to:
 
 ### 7b. Story-by-Story Execution (Code Generation Stages) - HARD GATE
 
-**⛔ HARD GATE - SEQUENTIAL STORY EXECUTION REQUIRED**
-
-```text
-┌─────────────────────────────────────────────────────────────┐
-│  STORY-BY-STORY EXECUTION - NON-NEGOTIABLE                  │
-│                                                              │
-│  ⛔ FORBIDDEN: Implementing multiple stories at once         │
-│  ⛔ FORBIDDEN: Skipping story file reads                     │
-│  ⛔ FORBIDDEN: Not updating stories_progress in bolt file    │
-│                                                              │
-│  You MUST process stories ONE AT A TIME in sequence.         │
-│  Each story requires its own announce → read → implement →   │
-│  update cycle. Batch implementation = broken traceability.   │
-└─────────────────────────────────────────────────────────────┘
-```
-
-**For EACH story in bolt's stories array, execute this exact sequence:**
-
-```text
-┌─────────────────────────────────────────────────────────────┐
-│  STORY EXECUTION LOOP (repeat for each story)               │
-│                                                              │
-│  STEP A: Announce start                                      │
-│  Output: "⏳ Story {n}/{total}: {story-id} - {title}"       │
-│                                                              │
-│  STEP B: Read story file (MANDATORY)                         │
-│  Action: Read {intent}/units/{unit}/stories/{story-id}.md   │
-│  Purpose: Extract acceptance criteria for implementation     │
-│                                                              │
-│  STEP C: Implement code for THIS story only                  │
-│  Action: Create/modify code to satisfy acceptance criteria   │
-│  Add traceability: // Story: {story-id}                      │
-│                                                              │
-│  STEP D: Update bolt file stories_progress (MANDATORY)       │
-│  Action: Edit bolt.md to mark story progress                 │
-│                                                              │
-│  STEP E: Update story FILE status (MANDATORY)                │
-│  Action: Edit story file frontmatter                         │
-│  Path: {intent}/units/{unit}/stories/{story-id}.md           │
-│  Update: status: {current} → implemented                     │
-│  ⚠️ This is the STORY FILE, not bolt.md                     │
-│                                                              │
-│  STEP F: Announce completion                                 │
-│  Output: "✅ Story {story-id}: Implemented → `{files}`"     │
-│                                                              │
-│  STEP G: Show updated progress list                          │
-│  Then proceed to next story (back to STEP A)                 │
-└─────────────────────────────────────────────────────────────┘
-```
-
-**Story Progress Display (show after EACH story completion):**
-
-```markdown
-### Story Progress ({completed}/{total})
-
-1. ✅ **{SSS}-{story-slug}**: Implemented → `{files}`
-2. ✅ **{SSS}-{story-slug}**: Implemented → `{files}`
-3. ⏳ **{SSS}-{story-slug}**: In Progress
-4. [ ] **{SSS}-{story-slug}**: Pending
-5. [ ] **{SSS}-{story-slug}**: Pending
-6. [ ] **{SSS}-{story-slug}**: Pending
-```
-
-### 7b-1. Story File Update (HARD GATE)
-
-**⛔ HARD GATE - STORY FILE UPDATE REQUIRED AFTER EACH STORY**
-
-```text
-┌─────────────────────────────────────────────────────────────┐
-│  STORY FILE UPDATE - NON-NEGOTIABLE                          │
-│                                                              │
-│  After implementing code for a story, you MUST:              │
-│  1. Use Edit tool to update the STORY FILE (not bolt.md)     │
-│  2. Change frontmatter: status: {current} → implemented      │
-│  3. Verify the edit was applied                              │
-│                                                              │
-│  Path: {intent}/units/{unit}/stories/{story-id}.md           │
-│                                                              │
-│  ⛔ FORBIDDEN: Moving to next story without updating file    │
-│  ⛔ FORBIDDEN: Only updating bolt.md, not story file         │
-│  ⛔ FORBIDDEN: Batch updating at stage end                   │
-└─────────────────────────────────────────────────────────────┘
-```
-
-**Story status values during code generation:**
+**⛔ HARD GATE**: Stories MUST be executed one-by-one with progress tracking. Batch implementation is FORBIDDEN.
 
-- `draft` / `generated` / `approved` → Initial status (varies)
-- `implemented` → After code is written for this story
-
-**Verification Output (after each story file update):**
-
-```text
-✅ Story file updated: {story-id}.md
-   - status: {old-status} → implemented
-```
-
-### 7b-2. Bolt File Update (After Story File)
-
-**Update bolt file after EACH story (not at the end):**
-
-```yaml
-stories_progress:
-  - id: 001-database-init
-    status: complete
-    implemented_at: {timestamp}
-  - id: 002-schema-tables
-    status: complete
-    implemented_at: {timestamp}
-  - id: 003-crud-operations
-    status: in-progress
-  - id: 004-query-helpers
-    status: pending
-```
-
-**Why This Pattern Exists:**
-
-1. **Traceability**: Each piece of code maps to a specific story
-2. **Resumability**: If interrupted, we know exactly where to continue
-3. **Verification**: We can validate that ALL stories were addressed
-4. **Visibility**: User sees clear progress through the work
-5. **Quality**: Reading acceptance criteria prevents missed requirements
-
-### 7c. Final Regression Check (After All Stories Implemented)
-
-**⛔ REQUIRED: After implementing all stories, verify no regressions**
-
-```text
-┌─────────────────────────────────────────────────────────────┐
-│  REGRESSION CHECK - BEFORE STAGE CHECKPOINT                  │
-│                                                              │
-│  After ALL stories are implemented, you MUST verify:         │
-│  1. Re-read acceptance criteria from FIRST story             │
-│  2. Verify the implementation still satisfies those ACs      │
-│  3. Repeat for each story in order                           │
-│  4. Report any regressions found                             │
-│                                                              │
-│  Later stories may have broken earlier implementations.      │
-│  Catch this BEFORE moving to Testing stage.                  │
-└─────────────────────────────────────────────────────────────┘
-```
-
-**Regression Check Output:**
-
-```text
-### Regression Check ({stories_count} stories)
-
-1. ✅ **{story-1}**: All ACs still valid
-2. ✅ **{story-2}**: All ACs still valid
-3. ⚠️ **{story-3}**: AC2 regression - {description} → FIX REQUIRED
-4. ✅ **{story-4}**: All ACs still valid
-
-{If regressions found: Fix before proceeding to checkpoint}
-```
-
-**Why This Check Exists:**
-
-- Story N implementation may modify shared code
-- Changes could invalidate Story 1-N-1 acceptance criteria
-- Catching regressions early prevents cascade failures in Testing stage
+> **Read `.iris/aidlc/skills/construction/refs/story-execution.md` and follow its instructions exactly.**
+> Covers: sequential story loop (announce → read → implement → update), story file updates, bolt progress updates, and regression check.
+>
+> ⚠️ You MUST use the Read tool to load this file NOW. Do not proceed to Step 8 without completing the story execution loop defined in that file.
 
 ### 8. Handle Checkpoints (As Defined by Bolt Type)
 
@@ -1018,156 +514,19 @@ After running the command, verify the changes were applied correctly:
 
 ## Update Construction Log (HARD GATE)
 
-**⛔ HARD GATE - CONSTRUCTION LOG UPDATES REQUIRED**
-
-```text
-┌─────────────────────────────────────────────────────────────┐
-│  CONSTRUCTION LOG - NON-NEGOTIABLE                          │
-│                                                              │
-│  You MUST update the construction log at these points:       │
-│  1. On first bolt start → Create log using template         │
-│  2. On bolt start → Add "started" entry                     │
-│  3. On stage completion → Add "stage-complete" entry        │
-│  4. On bolt completion → Add "completed" entry              │
-│                                                              │
-│  ⛔ FORBIDDEN: Starting bolt work without log entry         │
-│  ⛔ FORBIDDEN: Completing stage without log entry           │
-│  ⛔ FORBIDDEN: Completing bolt without log entry            │
-│                                                              │
-│  The construction log provides audit trail for the unit.    │
-│  No log entry = no evidence the work happened.              │
-└─────────────────────────────────────────────────────────────┘
-```
-
-### Location
-
-`{unit-path}/construction-log.md`
-
-### On First Bolt Start
-
-If construction log doesn't exist, create it using template:
-`.iris/aidlc/templates/construction/construction-log-template.md`
-
-### On Bolt Start
-
-```markdown
-- **{ISO-8601-timestamp}**: {bolt-id} started - Stage 1: {stage-name}
-```
+**⛔ HARD GATE**: You MUST update the construction log on bolt start, stage completion, and bolt completion. No log entry = no evidence the work happened.
 
-### On Stage Completion
-
-```markdown
-- **{ISO-8601-timestamp}**: {bolt-id} stage-complete - {stage-name} → {next-stage}
-```
-
-### On Bolt Completion
-
-```markdown
-- **{ISO-8601-timestamp}**: {bolt-id} completed - All {n} stages done
-```
+> **Read `.iris/aidlc/skills/construction/refs/construction-log.md` and follow its instructions.**
+>
+> ⚠️ You MUST use the Read tool to load this file. Missing log entries = no audit trail of work done.
 
 ---
 
-## Output (Stage Execution)
-
-```markdown
-## Executing Bolt: {bolt-id}
-
-### Current Stage: {stage-name}
-**Type**: {bolt-type}
-**Progress**: Stage {n} of {total}
-
-### Story Progress ({completed}/{total})
+## Output & Completion
 
-1. ✅ **{SSS}-{story-slug}**: Implemented → `{files}`
-2. ✅ **{SSS}-{story-slug}**: Implemented → `{files}`
-3. ⏳ **{SSS}-{story-slug}**: In Progress
-4. [ ] **{SSS}-{story-slug}**: Pending
+> **Read `.iris/aidlc/skills/construction/refs/bolt-output.md`** for output templates (stage execution + bolt completed), post-bolt action menu, and completion checklist.
 
-### Activities Performed
-1. ✅ {activity 1}
-2. ✅ {activity 2}
-3. ⏳ {activity 3 - in progress}
-
-### Artifacts Created
-- `{path/to/artifact}` - {description}
-
----
-
-### Checkpoint (if defined by bolt type)
-> "{checkpoint prompt from bolt type definition}"
-```
-
----
-
-## Output (Bolt Completed)
-
-```markdown
-## Bolt Complete: {bolt-id}
-
-### Summary
-- **Type**: {bolt-type}
-- **Duration**: {time elapsed}
-- **Stages Completed**: {all stages from bolt type}
-
-### Artifacts Produced
-{List artifacts as defined by bolt type}
-
-### Stories Delivered
-- ✅ **{SSS}-{story-slug}**: Complete
-- ✅ **{SSS}-{story-slug}**: Complete
-
-### Actions
-
-1 - **next**: Start next bolt
-2 - **list**: Review all bolts for this unit
-3 - **operations**: Proceed to Operations (if all complete)
-
-**Type a number or press Enter for suggested action.**
-```
-
----
-
-## CRITICAL: Post-Bolt Options (NEVER SKIP)
-
-**After EVERY bolt completion, you MUST present the Actions menu above.**
-
-```text
-┌─────────────────────────────────────────────────────────────┐
-│  BOLT COMPLETED                                              │
-│  → You MUST show the Actions menu (1-next, 2-list, 3-ops)   │
-│  → Do NOT just ask "approve to continue?"                    │
-│  → Let the user CHOOSE their next action                     │
-└─────────────────────────────────────────────────────────────┘
-```
-
-**Failure Mode**: Asking "Ready to proceed to next bolt?" without showing options
-**Correct Behavior**: Always show numbered Actions list and wait for user choice
-
----
-
-## Bolt Completion Checklist
-
-**Use this checklist to verify all completion tasks are done:**
-
-```text
-□ Bolt file updated:
-  □ status: complete
-  □ completed: {timestamp}
-  □ current_stage: null
-
-□ Stories updated (Step 10):
-  □ Each story in bolt's stories array:
-    □ status: complete
-    □ implemented: true
-
-□ Status cascade checked (Step 11):
-  □ Unit status updated if all bolts complete
-  □ Intent status updated if all units complete
-
-□ Construction log updated:
-  □ "{bolt-id} completed" entry added
-```
+**CRITICAL**: After EVERY bolt completion, present the Actions menu (1-next, 2-list, 3-ops). Do NOT skip.
 
 ---