convoke-agents 3.0.4 → 3.2.0

package/_bmad/bme/_artifacts/workflows/bmad-migrate-artifacts/steps/step-04-execute.md

@@ -0,0 +1,213 @@
+# Step 4: Confirm & Execute
+
+## STEP GOAL:
+
+To present the final migration plan, get explicit operator confirmation, write the resolutions JSON file, invoke the migration CLI in non-interactive mode, and report the results (success or failure).
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER apply the migration without explicit `y` from the operator
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: If the CLI fails, present the raw error and offer retry — do NOT swallow it
+- 📋 YOU ARE A FACILITATOR running the final step, not a content generator
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+### Role Reinforcement:
+
+- ✅ This is the only step that mutates the repo
+- ✅ Operator confirmation is the gate — never skip it
+- ✅ Errors must be surfaced verbatim, not interpreted
+
+### Step-Specific Rules:
+
+- 🎯 Final summary → confirmation → write resolutions file → invoke CLI → report
+- 🚫 FORBIDDEN to apply without `y`
+- 🚫 FORBIDDEN to forget cleanup of the temp resolutions file (success path)
+- 💬 Operator overrides MUST be passed to the CLI via `--resolution-file`
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Build the resolutions JSON in schema-versioned envelope
+- 💾 Write to a recognizable temp path; clean up on success
+- 🚫 FORBIDDEN to invoke `--apply` without `--force --resolution-file <path>`
+
+## CONTEXT BOUNDARIES:
+
+- Available context: `{{scope}}` from Step 1, `{{buckets}}` from Step 2, `{{resolutions}}` from Step 3
+- Focus: confirmation + execution + reporting
+- Limits: this is the final step; no further routing
+- Dependencies: Steps 1-3 must have run
+
+## Sequence of Instructions (Do not deviate, skip, or optimize)
+
+### 1. Build the final plan summary
+
+From `{{buckets}}` and `{{resolutions}}`, compute:
+
+- **Clean renames:** count from `{{buckets}}.CLEAN_RENAME`
+- **Operator-resolved renames:** count of `{{resolutions}}` entries with `action === 'rename'`
+- **Operator-skipped:** count of `{{resolutions}}` entries with `action === 'skip'`
+- **Collisions auto-suggested:** count from `{{buckets}}.COLLISION` where `suggestedNewPath` is not null
+- **Conflicts (still blocking):** count from `{{buckets}}.CONFLICT`
+
+Display:
+
+> ### 🎯 Final Migration Plan
+>
+> - ✅ **{N} clean renames** (engine inferences, no operator action)
+> - 👤 **{M} operator-resolved renames** (from your Step 3 decisions)
+> - ⏭️ **{K} operator-skipped** files
+> - ⚠️ **{C} collisions** with suggested differentiators
+> - 🚨 **{X} conflicts** — these BLOCK the migration. Resolve manually before re-running.
+>
+> Total files that will be modified: **{N + M + C}**
+
+If `{X}` (conflicts) > 0:
+- Display: `🚨 Migration BLOCKED by {X} unresolved conflict(s). Aborting. Please resolve manually and re-run.`
+- HALT permanently. Do NOT proceed to step 2.
+
+### 2. Ask for confirmation
+
+Display this menu and HALT for input:
+
+```
+Apply migration? [y/n]
+```
+
+### 3. Handle the operator's response
+
+**IF the operator typed `n` (or 'no', 'abort', 'cancel'):**
+- Reply: `"Migration aborted at confirmation. No changes made."`
+- Do NOT write the temp resolutions file.
+- HALT permanently.
+
+**IF the operator typed `y` (or 'yes', 'apply', 'go'):**
+- Proceed to step 4 below.
+
+**IF the response is anything else:**
+- Re-ask. Loop until valid.
+
+### 4. Write the resolutions JSON file
+
+Build the schema-versioned envelope:
+
+```json
+{
+  "schemaVersion": 1,
+  "resolutions": { ... contents of {{resolutions}} ... }
+}
+```
+
+Write it to the **OS temp directory** (NOT under `_bmad-output/`, which would otherwise be picked up by the next migration scan as an artifact and could end up committed). On macOS/Linux this is typically `/tmp/`; portably you can use the result of `mktemp -t convoke-migration-resolutions.json`. The exact path doesn't matter — it just needs to be writable, outside the project tree, and unique enough to avoid collisions with concurrent runs.
+
+Capture the chosen path as `{{resolutionFilePath}}`.
+
+If the resolutions map is EMPTY (Step 3 was skipped because no entries needed resolving), do NOT write a resolutions file. Skip the `--resolution-file` flag in step 5.
+
+### 5. Invoke the migration CLI
+
+Shell out to:
+
+```
+node scripts/migrate-artifacts.js --apply --force --include "{{scope}}" --resolution-file "{{resolutionFilePath}}"
+```
+
+**Always quote `{{scope}}` and `{{resolutionFilePath}}`** — the resolution file lives in `os.tmpdir()` which on macOS may resolve to a path containing spaces, and unquoted shell expansion will split on whitespace and break the command. Quote both arguments unconditionally.
+
+(Omit `--resolution-file` only if step 4 didn't write a resolutions file because the resolutions map was empty.)
+
+Capture stdout and stderr. The CLI will produce three commits on success:
+1. `chore: rename artifacts to governance convention` (rename phase)
+2. `chore: inject frontmatter metadata and update links` (injection phase)
+3. `chore: generate governance convention ADR` (ADR phase)
+
+### 6. Handle the CLI result
+
+**IF the CLI exited with code 0 (success):**
+
+Parse stdout for the three commit SHAs. Look for lines like:
+- `Rename phase complete. N files renamed. Commit: <sha>`
+- `Injection phase complete. N files injected, M links updated, K conflicts skipped. Commit: <sha>`
+- `ADR generated: adr-artifact-governance-convention-<date>.md`
+
+Display:
+
+> ### ✅ Migration Complete
+>
+> - **Renamed:** {N} files (commit `{rename_sha}`)
+> - **Frontmatter injected:** {M} files (commit `{inject_sha}`)
+> - **Links updated:** {K}
+> - **ADR generated:** `{adr_filename}`
+>
+> The rename map has been written to `_bmad-output/planning-artifacts/artifact-rename-map.md` and is included in the rename commit.
+
+Then clean up the temp resolutions file:
+
+```
+rm {{resolutionFilePath}}
+```
+
+(Only if it was written in step 4. Failures here are non-fatal — the file is recognizable by its `.migration-resolutions-` prefix and can be removed manually.)
+
+End the workflow with:
+
+> 🎉 Done. Run `bmad-portfolio-status` to see the updated portfolio view.
+
+**IF the CLI exited with non-zero (failure):**
+
+Display the raw stderr verbatim:
+
+> ### 🚨 Migration Failed
+>
+> The CLI returned an error:
+>
+> ```
+> {raw stderr}
+> ```
+>
+> The temp resolutions file is preserved at `{{resolutionFilePath}}` for inspection.
+
+Then offer the operator a choice:
+
+```
+[R] Retry from Step 1 (Scope Selection)
+[X] Exit (manual recovery required)
+```
+
+HALT for input.
+
+- **IF `[R]`:** Read fully and follow `./step-01-scope.md` to restart. Note: the existing temp file is left in place; the operator can delete it manually.
+- **IF `[X]`:** Reply with recovery guidance:
+  > "Recovery hint: check `git status` to see if any rename or commit completed partially. The CLI is designed to roll back on failure (`git reset --hard HEAD`), but if rollback failed the working tree may be dirty. Resolve manually before re-running."
+  > HALT permanently.
+
+## CRITICAL STEP COMPLETION NOTE
+
+This is the final step. There is no `next step` to load. The workflow ends here in all paths (success, failure, abort). Do NOT auto-load any other file.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Final plan summary presented
+- Operator confirmed with `y`
+- Temp resolutions file written (if needed)
+- CLI invoked with `--apply --force` and (if applicable) `--resolution-file`
+- Operator overrides honored end-to-end
+- Three commit SHAs reported on success
+- Temp file cleaned up on success
+
+### ❌ SYSTEM FAILURE:
+
+- Applying without operator `y`
+- Forgetting `--resolution-file` when resolutions exist
+- Swallowing CLI errors
+- Hiding the raw stderr from the operator
+- Auto-retrying without operator input
+- Forgetting to handle the conflict-blocked case in step 1
+
+**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.

package/_bmad/bme/_artifacts/workflows/bmad-migrate-artifacts/workflow.md

@@ -0,0 +1,85 @@
+---
+main_config: '{project-root}/_bmad/bmm/config.yaml'
+---
+
+# Migrate Artifacts (Guided)
+
+**Goal:** Run artifact governance migration through a guided 4-step conversation: scope selection → dry-run review → interactive resolution of ambiguous files → confirm and execute. The skill wraps `scripts/migrate-artifacts.js` so the operator gets a guided experience instead of a raw CLI dump.
+
+**Your Role:** In addition to your name, communication_style, and persona, you are a guided-migration assistant for the Convoke artifact governance system. You orchestrate a conversation around an existing CLI tool — the CLI does the actual work, you frame the decisions and present the results in a structured way. You are NOT a content generator; you are NOT making engineering decisions; you are facilitating the operator's review and capturing their answers. When the operator overrides a suggestion, that override is authoritative — never silently dropped.
+
+---
+
+## WORKFLOW ARCHITECTURE
+
+This uses **step-file architecture** for disciplined execution:
+
+### Core Principles
+
+- **Micro-file Design**: Each step of the overall goal is a self-contained instruction file that you will adhere to one file at a time as directed
+- **Just-In-Time Loading**: Only one current step file will be loaded and followed to completion — never load future step files until told to do so
+- **Sequential Enforcement**: Sequence within the step files must be completed in order, no skipping or optimization allowed
+- **Working-Memory State**: Unlike most BMAD workflows, this skill produces NO output artifact (the migration mutates the repo directly via git commits). State (`{{scope}}`, `{{buckets}}`, `{{resolutions}}`) is held in the agent's working memory across step boundaries, NOT persisted to a file. See "No Output Artifact" below.
+- **Operator Authority**: When the operator overrides an engine suggestion or specifies an initiative, that decision is authoritative. The skill writes the resolutions to a temp JSON file in Step 4 and passes it to the CLI via `--resolution-file` so overrides survive end-to-end.
+
+### Step Processing Rules
+
+1. **READ COMPLETELY**: Always read the entire step file before taking any action
+2. **FOLLOW SEQUENCE**: Execute all numbered sections in order, never deviate
+3. **WAIT FOR INPUT**: If a menu is presented, halt and wait for user selection
+4. **CHECK CONTINUATION**: If the step has a menu with Continue as an option, only proceed to next step when user selects 'C' (Continue)
+5. **HOLD STATE IN MEMORY**: Capture `{{scope}}`, `{{buckets}}`, `{{resolutions}}` in working memory across step boundaries
+6. **LOAD NEXT**: When directed, read fully and follow the next step file
+
+### Critical Rules (NO EXCEPTIONS)
+
+- 🛑 **NEVER** load multiple step files simultaneously
+- 📖 **ALWAYS** read entire step file before execution
+- 🚫 **NEVER** skip steps or optimize the sequence
+- 🎯 **ALWAYS** follow the exact instructions in the step file
+- ⏸️ **ALWAYS** halt at menus and wait for user input
+- 📋 **NEVER** create mental todo lists from future steps
+- 🚫 **NEVER** invoke the CLI in `--apply` mode without operator confirmation in Step 4
+- 👤 **NEVER** silently drop an operator override — overrides are authoritative
+
+### No Output Artifact
+
+This skill is structurally different from most BMAD workflow skills (e.g. `bmad-create-prd`, `bmad-create-epics-and-stories`) which produce a markdown document built up across step boundaries. Migration mutates the repo directly via git commits — there is nothing to "build up" in an output file. As a consequence:
+
+- The workflow has NO `outputFile:` frontmatter field
+- The workflow has NO `templates/` directory
+- The workflow does NOT use the standard `stepsCompleted[]` frontmatter pattern for resumability
+- State is held in the agent's working memory only
+
+**Resumability limitation:** if the workflow is interrupted between Step 3 and Step 4, the operator loses their resolutions and must restart from Step 1. This is acceptable in v1 because the dry-run is fast (< 10 seconds) and the resolution loop is the only manual phase.
+
+---
+
+## INITIALIZATION SEQUENCE
+
+### 1. Configuration Loading
+
+Load and read full config from `{project-root}/_bmad/bmm/config.yaml` and resolve:
+
+- `project_name`, `output_folder`, `user_name`, `communication_language`, `document_output_language`
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+### 2. Pre-flight Check
+
+Verify that `_bmad/_config/taxonomy.yaml` exists. If it does NOT exist, display:
+
+> 🚨 **Taxonomy missing**
+>
+> The artifact governance taxonomy file is not yet bootstrapped. The migration CLI will create it on the first run, but you can also create it manually by running:
+>
+> ```
+> node scripts/migrate-artifacts.js
+> ```
+>
+> Once the taxonomy exists, run this skill again.
+
+Then HALT permanently — do NOT proceed to Step 1.
+
+### 3. First Step EXECUTION
+
+Read fully and follow: `./steps/step-01-scope.md` to begin the workflow.

package/_bmad/bme/_artifacts/workflows/bmad-portfolio-status/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: bmad-portfolio-status
+description: Show a portfolio view of all initiatives with phase, status, and next actions through a guided 3-step conversation. Use when the user says "show portfolio" or "portfolio status".
+---
+
+IT IS CRITICAL THAT YOU FOLLOW THIS COMMAND: LOAD the FULL {project-root}/_bmad/bme/_artifacts/workflows/bmad-portfolio-status/workflow.md, READ its entire contents and follow its directions exactly!

package/_bmad/bme/_artifacts/workflows/bmad-portfolio-status/steps/step-01-scan.md

@@ -0,0 +1,131 @@
+# Step 1: Scan & Present
+
+## STEP GOAL:
+
+To run the portfolio engine, capture the markdown output, and present it to the operator with a brief explanation of what the table shows. Hold the raw output in working memory for Steps 2 and 3 to consume.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER reformat or filter the engine output — present it verbatim
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
+- 📋 YOU ARE A FACILITATOR — the engine produces the data, you frame it
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+### Role Reinforcement:
+
+- ✅ You are a portfolio status assistant — your job is to make a CLI tool feel like a guided exploration
+- ✅ The engine does the work; you orchestrate the conversation around it
+- ✅ Read-only: this skill never mutates the repo
+
+### Step-Specific Rules:
+
+- 🎯 Focus ONLY on running the engine and presenting its output
+- 🚫 FORBIDDEN to filter, reformat, or "interpret" engine output in this step
+- 💬 Hold the raw stdout in working memory as `{{scanOutput}}` for downstream steps
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Shell out to the portfolio engine in markdown mode
+- 💾 Capture stdout in full and store as `{{scanOutput}}`
+- 🚫 FORBIDDEN to load next step until presentation completes — auto-transition to Step 2 (no menu HALT here)
+
+## CONTEXT BOUNDARIES:
+
+- Available context: project root (the engine reads it from `findProjectRoot()`)
+- Focus: engine invocation + verbatim presentation
+- Limits: no filtering, no exploration menu, no recommendations
+- Dependencies: none (this is the first step)
+
+## Sequence of Instructions (Do not deviate, skip, or optimize)
+
+### 1. Welcome and brief explanation
+
+Greet `{user_name}` and explain what's about to happen in two sentences:
+
+> "I'll generate a portfolio view of all your initiatives — phase, status, next action, and a context re-entry hint for each one. The data is inferred from the artifacts in your `_bmad-output/` directories, so the view reflects your real working state with zero manual upkeep."
+
+### 2. Run the portfolio engine
+
+Shell out to:
+
+```
+node scripts/lib/portfolio/portfolio-engine.js --markdown
+```
+
+Capture stdout in full as `{{scanOutput}}`. The engine returns immediately — there's no interactive prompt to handle.
+
+### 3. Handle engine errors
+
+**If the engine exited with a non-zero code:**
+
+Display the raw stderr verbatim:
+
+> ### 🚨 Portfolio Engine Failed
+>
+> The engine returned an error:
+>
+> ```
+> {raw stderr}
+> ```
+
+The engine produces clear errors (e.g. "taxonomy.yaml not found — run convoke-migrate-artifacts or convoke-update to create"). Do NOT swallow them or rephrase them.
+
+Then HALT permanently — do NOT proceed to Step 2.
+
+### 4. Present the engine output
+
+Display:
+
+> ### 📊 Portfolio
+>
+> The table below shows each initiative with:
+>
+> - **Phase** — discovery, planning, build, complete, or unknown (inferred from artifact chain)
+> - **Status** — explicit (from frontmatter) or inferred (from git activity + chain analysis)
+> - **Next Action / Context** — chain-gap analysis or last artifact touched
+>
+> ---
+>
+> {{scanOutput}}
+
+The output already contains all the lines that matter:
+- The markdown table with one row per initiative
+- WIP radar line (if active initiatives exceed the threshold)
+- `Total: N artifacts | Governed: G | Ungoverned: U | Unattributed: X`
+- `Governance: G/T artifacts governed (P%)`
+- `N files attributable to existing initiatives but ungoverned — run convoke-migrate-artifacts to govern them` (if N > 0)
+- `N unattributed files (run with --show-unattributed to see details)` (if N > 0)
+
+Forward all of them. Do NOT filter or reformat.
+
+### 5. Auto-transition to Step 2
+
+There is NO menu in this step. After presenting the output, immediately read fully and follow `./step-02-explore.md` to enter the exploration loop.
+
+## CRITICAL STEP COMPLETION NOTE
+
+Auto-transition is intentional: the operator needs to see the data BEFORE being asked what to explore. Steps 2 and 3 own the menu HALTs.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Engine invoked with `--markdown`
+- `{{scanOutput}}` captured in working memory
+- All engine output forwarded verbatim to the operator
+- Operator sees the table, WIP radar (if any), governance health, attributable-but-ungoverned line (if any), and unattributed summary (if any)
+- Auto-transitioned to Step 2
+
+### ❌ SYSTEM FAILURE:
+
+- Filtering, reformatting, or "improving" the engine output
+- Swallowing engine errors
+- Stopping for a menu HALT in this step
+- Forgetting to capture `{{scanOutput}}` for Step 3
+
+**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.

package/_bmad/bme/_artifacts/workflows/bmad-portfolio-status/steps/step-02-explore.md

@@ -0,0 +1,131 @@
+# Step 2: Explore Loop
+
+## STEP GOAL:
+
+To present a numbered exploration menu and let the operator drill into specific aspects of the portfolio (initiative trace, filter, sort, unattributed details). The loop is open-ended — operators can chain as many explorations as they want until they pick `[5] Done`.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER exit the loop without operator input (`[5]` or an exit phrase)
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step with `5`, ensure entire file is read
+- 📋 YOU ARE A FACILITATOR running an exploration loop, not a content generator
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+### Role Reinforcement:
+
+- ✅ Each menu pick re-invokes the engine with different flags and presents the new output
+- ✅ The original `{{scanOutput}}` from Step 1 is preserved across the loop — Step 3 uses it for recommendations, NOT any filtered re-runs
+- ✅ The loop is bounded only by the operator's choice — never auto-exit
+
+### Step-Specific Rules:
+
+- 🎯 Focus ONLY on the exploration loop in this step
+- 🚫 FORBIDDEN to mutate `{{scanOutput}}` (it's the source of truth for Step 3)
+- 🚫 FORBIDDEN to "improve" or summarize engine re-run output
+- 💬 Re-display the menu after every iteration
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Present menu → HALT for input → re-invoke engine with the picked flag → present → loop
+- 💾 Hold `{{scanOutput}}` from Step 1 unchanged across the loop
+- 🚫 FORBIDDEN to load next step until the operator picks `[5] Done`
+
+## CONTEXT BOUNDARIES:
+
+- Available context: `{{scanOutput}}` from Step 1
+- Focus: interactive exploration of the portfolio
+- Limits: no recommendations (Step 3 owns those), no mutations
+- Dependencies: Step 1 must have set `{{scanOutput}}`
+
+## Sequence of Instructions (Do not deviate, skip, or optimize)
+
+### 1. Present the menu
+
+Display:
+
+> ### 🔍 Explore the Portfolio
+>
+> Pick an option to drill in. You can chain as many explorations as you want — the loop only ends when you pick `[5] Done`.
+>
+> ```
+> [1] Explain a specific initiative's status (verbose inference trace)
+> [2] Filter to a single initiative prefix
+> [3] Sort by last activity instead of alpha
+> [4] Show details for each unattributed file
+> [5] Done — proceed to recommendations
+> ```
+
+HALT for input.
+
+### 2. Handle the operator's choice
+
+**`[1]` — Explain initiative**
+
+1. Ask: `"Which initiative? (e.g. gyre, forge, helm, convoke)"` and HALT.
+2. On response, validate the initiative is one shown in `{{scanOutput}}`'s table. If not, reply `"Initiative '{name}' not in current portfolio. Try one of: {list}."` and re-ask.
+3. Shell out to: `node scripts/lib/portfolio/portfolio-engine.js --markdown --verbose`
+4. The verbose flag adds an `--- Inference Trace ---` block at the bottom showing per-initiative `phase: ... (source, confidence) | status: ...`
+5. Extract just the lines for the chosen initiative from the trace block and present them along with that initiative's row from the table.
+6. Loop back to step 1 (re-display the menu).
+
+**`[2]` — Filter by prefix**
+
+1. Ask: `"Initiative prefix to filter by? (e.g. 'gyre' to show just gyre)"` and HALT.
+2. On response, shell out to: `node scripts/lib/portfolio/portfolio-engine.js --markdown --filter "{prefix}"`
+3. Present the filtered output verbatim.
+4. Loop back to step 1.
+
+**`[3]` — Sort by last activity**
+
+1. Shell out to: `node scripts/lib/portfolio/portfolio-engine.js --markdown --sort last-activity`
+2. Present the re-sorted output verbatim.
+3. Loop back to step 1.
+
+**`[4]` — Show unattributed details**
+
+1. Shell out to: `node scripts/lib/portfolio/portfolio-engine.js --markdown --show-unattributed`
+2. The output will include a `--- Unattributed Files (N) ---` block followed by per-file lines with reasons.
+3. Present the output verbatim.
+4. Loop back to step 1.
+
+**`[5]` — Done (or any exit phrase: `done`, `exit`, `quit`)**
+
+1. Reply: `"Generating recommendations..."`
+2. Read fully and follow `./step-03-recommend.md`.
+
+**Invalid input** (anything else)
+
+1. Reply: `"Pick [1]–[5] or type 'done'."`
+2. Re-display the menu and HALT.
+
+### 3. The loop is explicit, not bounded
+
+After each iteration of options [1]–[4], ALWAYS return to step 1 of this file (re-display the menu). The operator may want to chain explorations (e.g. filter to gyre, then explain gyre, then sort by activity, then show unattributed). There is NO maximum iteration count — the loop only exits on `[5]`.
+
+## CRITICAL STEP COMPLETION NOTE
+
+ONLY when the operator picks `[5]` (or types an exit phrase) will you read fully and follow `./step-03-recommend.md`. Do NOT auto-exit after some number of iterations.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Menu presented with all 5 options
+- Each option correctly maps to its CLI flag
+- Engine output forwarded verbatim each iteration
+- Loop continues until operator picks `[5]`
+- `{{scanOutput}}` from Step 1 is unchanged
+
+### ❌ SYSTEM FAILURE:
+
+- Auto-exiting after a fixed number of iterations
+- Mutating `{{scanOutput}}`
+- Filtering or reformatting engine re-run output
+- Skipping the menu re-display between iterations
+
+**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.