convoke-agents 3.1.0 → 3.2.1

package/CHANGELOG.md

@@ -7,6 +7,37 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [3.2.0] - 2026-04-11
+
+### Added
+
+- **Portability System** — Export BMAD skills to portable, LLM-agnostic format with platform adapters for Claude, Copilot, and Cursor. New CLI command `convoke-export` and 4 new skills: `bmad-export-skill`, `bmad-generate-catalog`, `bmad-seed-catalog`, `bmad-validate-exports`.
+- **Portability Export Engine** (`scripts/portability/export-engine.js`) — Transforms skill workflows into standalone instructions documents with persona, sections, and configurable warning types. Supports tier classification (standalone, light-deps, pipeline).
+- **Catalog Generator** — Generates a decision-tree skill catalog README from manifest data for the public catalog repository.
+- **Seed Catalog** — Seeds a complete catalog repository staging directory with all exportable skills, adapters, and catalog README.
+- **Export Validation** — Validates exported skill staging directories for structural correctness and BMAD-internal leaks.
+- **Platform Adapters** — Generates Claude (CLAUDE.md commands), GitHub Copilot (`.github/copilot-instructions.md`), and Cursor (`.cursor/rules/`) adapter files from exported skills.
+- **Team Factory module** — Now ships in the npm package (`_bmad/bme/_team-factory/`). Factory workflows for industrializing team, agent, and skill addition.
+
+### Changed
+
+- **Test infrastructure recovery** — Resolved the C1 phantom-test bug class discovered in the 2026-04-08 astonishment report. 22 test files in `tests/lib/` converted from Jest API to `node:test` + `node:assert/strict`. Test gate grew from 408 to 1,123 verified-passing tests.
+- **`npm test` glob** — Replaced 8 literal file paths with `tests/lib/*.test.js` glob. New test files in `tests/lib/` are now automatically discovered by CI.
+- **eslint config** — Removed Jest globals (`test`, `expect`, `jest`, `beforeEach`, `afterEach`, `beforeAll`, `afterAll`) from `tests/**/*.js` block. This is the structural fix that prevents future phantom tests from passing lint.
+- **`test:all` script** — Rewritten to compose `npm test && npm run test:integration && npm run test:p0` instead of a broken `tests/**/*.test.js` glob.
+- **`test:p0:gate`** — Now delegates to `test:p0` instead of duplicating the command.
+- **Definition of Done checklist** — Added Phantom Test Guard and Test Wiring Verified items to prevent AI-generated phantom tests from passing story completion.
+- **Golden fixture protection** — `tests/**/golden/` directories excluded from eslint with explanatory README documenting the byte-exact contract.
+
+### Infrastructure
+
+- **1,123 tests** across unit, integration, p0, team-factory, and lib suites (was 320+ in v3.1.0)
+- **`tests/mock-cp.js` helper** — Shared child_process mock helper for `node:test` suites. Handles module-cache reset, per-spy restoration, and explicit caller-dirname resolution.
+- **New dependency:** `yaml` ^2.8.3 (for YAML comment preservation in portability exports)
+- **Published modules:** Added `_bmad/bme/_portability/` and `_bmad/bme/_team-factory/` to npm package files
+
+---
+
 ## [3.1.0] - 2026-04-06
 
 ### Added

package/README.md

@@ -10,7 +10,7 @@
                 Agent teams for complex systems
 ```
 
-[![Version](https://img.shields.io/badge/version-3.0.4-blue)](https://github.com/amalik/convoke-agents)
+[![Version](https://img.shields.io/badge/version-3.2.0-blue)](https://github.com/amalik/convoke-agents)
 [![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
 
 </div>
@@ -22,11 +22,11 @@ Convoke extends AI agents with two types of installable modules: **Teams** bring
 | **Vortex** | 7 agents, 22 workflows | Product discovery — from user insight to evidence-based decisions |
 | **Gyre** | 4 agents, 7 workflows | Production readiness — from stack detection to gap analysis |
 
-### What's New
+### What's New in 3.2
 
-- **Gyre team** — 4 agents analyze your project's production readiness: detect your stack, model what "ready" looks like, find what's missing, and help you act on it
-- **Team Factory** — guided workflow for creating new BMAD-compliant teams from scratch (`/bmad-team-factory`)
-- **Skill Validator** — new `validateSkill()` quality gate in the update system for factory-generated skills ([development docs](docs/development.md))
+- **Portable skills** — export any BMAD skill to a standalone format with platform adapters for Claude, Copilot, and Cursor (`npx convoke-export <skill>`)
+- **Team Factory ships** — the module for creating new BMAD-compliant teams is now included in the npm package
+- **1,123 tests** — test infrastructure recovery resolved a phantom-test bug class; test gate tripled from 320+ to 1,123 verified-passing tests
 - See the [CHANGELOG](CHANGELOG.md) for the full release details
 
 ---
@@ -221,6 +221,26 @@ Three capabilities:
 - **Add Agent** — extend an existing team with a new agent
 - **Add Skill** — give an existing agent a new workflow
 
+### Portability — Export Skills Anywhere
+
+Take any BMAD skill and export it to a standalone, LLM-agnostic format that works outside Claude Code:
+
+```bash
+npx convoke-export bmad-brainstorming --output ./exported
+```
+
+The export engine transforms skill workflows into self-contained instruction documents, then generates platform-specific adapter files:
+
+| Platform | Adapter output (written inside the export target) |
+|----------|---------------|
+| Claude | `{target}/CLAUDE.md` commands |
+| GitHub Copilot | `{target}/.github/copilot-instructions.md` |
+| Cursor | `{target}/.cursor/rules/` |
+
+Skills are classified by tier: **standalone** skills export cleanly, **light-deps** skills include dependency notes, and **pipeline** skills (multi-step orchestration) are flagged as non-portable.
+
+Four skills support the workflow: `bmad-export-skill` (export), `bmad-validate-exports` (validate), `bmad-generate-catalog` (catalog README), `bmad-seed-catalog` (full catalog repo).
+
 ### Enhance — Agent Skills
 
 Skills give existing agents new workflows — installed via menu patching, not agent modification. The first skill adds RICE-scored backlog management to the PM agent:
@@ -349,11 +369,17 @@ your-project/
 │   │   ├── contracts/        # Artifact contract schemas (GC1-GC4)
 │   │   ├── guides/           # User guides (all 4 agents)
 │   │   └── config.yaml       # Configuration
-│   └── _enhance/             # Skill: Agent Capability Upgrades
-│       ├── workflows/        # Skill workflows (initiatives-backlog)
-│       ├── extensions/       # Agent menu patch descriptors
-│       ├── guides/           # Module author guide
-│       └── config.yaml       # Configuration
+│   ├── _enhance/             # Skill: Agent Capability Upgrades
+│   │   ├── workflows/        # Skill workflows (initiatives-backlog)
+│   │   ├── extensions/       # Agent menu patch descriptors
+│   │   ├── guides/           # Module author guide
+│   │   └── config.yaml       # Configuration
+│   ├── _portability/         # Skill: Export skills to other platforms
+│   │   └── skills/           # Export, validate, catalog, seed workflows
+│   ├── _team-factory/        # Skill: Create new BMAD-compliant teams
+│   │   └── lib/              # Factory generators and validators
+│   └── _artifacts/           # Skill: Artifact governance & portfolio
+│       └── workflows/        # Migrate artifacts, portfolio status
 └── _bmad-output/
     ├── vortex-artifacts/     # Vortex generated artifacts
     └── gyre-artifacts/       # Gyre generated artifacts
@@ -419,6 +445,7 @@ See [UPDATE-GUIDE.md](UPDATE-GUIDE.md) for migration paths and troubleshooting.
 - **v1.x** — Vortex foundation: 7 agents, 22 workflows, update system, CI/CD
 - **v2.0** — Product renamed to Convoke. CLI commands: `convoke-*`. Package: `convoke-agents`
 - **v2.x** — Enhance module (Skills architecture, RICE initiatives-backlog), Gyre team (production readiness, 4 agents), Team Factory
+- **v3.x** — Artifact governance, portfolio intelligence, portability system (export to Claude/Copilot/Cursor), 1,123 tests
 - **Next** — Forge (domain knowledge extraction for enterprise brownfield engagements)
 - **Future** — Additional teams, Forge-Gyre integration, cross-team workflows
 

package/_bmad/bme/_artifacts/config.yaml

@@ -0,0 +1,15 @@
+name: artifacts
+version: 1.0.0
+description: "Artifacts module — operator-facing skills for the Convoke artifact system (migration, portfolio status, future Experience Contract validation)"
+# Workflows in this module are STANDALONE (operator invokes them directly via slash command),
+# unlike _enhance workflows which patch into a target_agent's menu. The `standalone: true`
+# flag is consumed by refresh-installation.js (Story 6.6) to skip menu-patching and only
+# generate a Claude Code skill wrapper. Without this flag, refresh-installation would treat
+# the workflow as a menu-patch workflow (the Enhance default) and fail to find a target_agent.
+workflows:
+  - name: bmad-migrate-artifacts
+    entry: workflows/bmad-migrate-artifacts/workflow.md
+    standalone: true
+  - name: bmad-portfolio-status
+    entry: workflows/bmad-portfolio-status/workflow.md
+    standalone: true

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

@@ -0,0 +1,6 @@
+---
+name: bmad-migrate-artifacts
+description: Migrate artifact governance metadata to conform to taxonomy. Use when the user says "run artifact migration" or "migrate artifacts".
+---
+
+IT IS CRITICAL THAT YOU FOLLOW THIS COMMAND: LOAD the FULL {project-root}/_bmad/bme/_artifacts/workflows/bmad-migrate-artifacts/workflow.md, READ its entire contents and follow its directions exactly!

package/_bmad/bme/_artifacts/workflows/bmad-migrate-artifacts/steps/step-01-scope.md

@@ -0,0 +1,138 @@
+# Step 1: Scope Selection
+
+## STEP GOAL:
+
+To explain to the operator what artifact migration does, present the default scan scope, and confirm or adjust which directories the migration should cover.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER execute the migration without explicit user confirmation
+- 📖 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, not a script runner
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+### Role Reinforcement:
+
+- ✅ You are a guided-migration assistant — your job is to make a CLI tool feel like a conversation
+- ✅ You explain what is about to happen in plain language, then defer to the operator's decisions
+- ✅ The CLI does the work; you orchestrate the conversation around it
+
+### Step-Specific Rules:
+
+- 🎯 Focus ONLY on scope selection in this step
+- 🚫 FORBIDDEN to invoke the migration CLI in this step (Step 2 does that)
+- 🚫 FORBIDDEN to ask about ambiguous file resolutions yet (Step 3 does that)
+- 💬 Capture the operator's chosen scope as `{{scope}}` for downstream steps
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Start with a 2-sentence explanation of what artifact migration does
+- 💾 Hold scope selection in working memory (no file persisted in this step)
+- 🚫 FORBIDDEN to load next step until the operator selects 'C' AND scope is confirmed
+
+## CONTEXT BOUNDARIES:
+
+- Available context: project root, default scan directories
+- Focus: presenting scope, capturing operator confirmation
+- Limits: no CLI invocation, no manifest generation
+- 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 in two sentences:
+
+> "Artifact migration scans your `_bmad-output/` directories, infers the right initiative + type for each file, and renames everything to follow the governance convention `{initiative}-{type}-{qualifier}-{date}.md`. It runs in dry-run mode first so you can review every proposed change before anything is touched."
+
+### 2. Count files in default scope directories
+
+Run these shell commands and capture the counts:
+
+```
+ls _bmad-output/planning-artifacts | wc -l
+ls _bmad-output/vortex-artifacts | wc -l
+ls _bmad-output/gyre-artifacts | wc -l
+```
+
+If any directory does not exist, report `0` for it (do not error out).
+
+### 3. Present the default scope
+
+Present:
+
+> **Default scan scope:**
+>
+> - `planning-artifacts` ({N1} files)
+> - `vortex-artifacts` ({N2} files)
+> - `gyre-artifacts` ({N3} files)
+>
+> **Total: {N1+N2+N3} files**
+
+### 4. Ask for confirmation or override
+
+Display this menu and HALT for input:
+
+```
+[C] Continue with default scope
+[O] Override — specify a custom comma-separated list of directory names
+[X] Exit — abort the migration entirely
+```
+
+### 5. Handle the operator's response
+
+**IF the operator chose `[C]`:**
+- Set `{{scope}}` = `planning-artifacts,vortex-artifacts,gyre-artifacts`
+- Proceed to step 6 below.
+
+**IF the operator chose `[O]`:**
+- Ask: `"Specify a comma-separated list of directory names (relative to _bmad-output/):"`
+- HALT for input.
+- When the operator responds, validate the input:
+  - Must be comma-separated
+  - Each name must match `^[a-zA-Z0-9_-]+$` (no path traversal, no spaces, no special chars)
+  - At least one name must exist as a directory under `_bmad-output/`
+- If validation fails, explain WHY (which name is invalid or missing) and re-ask. Loop until valid or until the operator chooses to abort.
+- Set `{{scope}}` = the validated comma-separated list.
+- Proceed to step 6 below.
+
+**IF the operator chose `[X]`:**
+- Reply: `"Migration aborted. No changes made."`
+- HALT permanently. Do NOT load step 2.
+
+### 6. Confirm and transition
+
+Show:
+
+> ✅ **Scope confirmed:** `{{scope}}`
+>
+> Ready to generate the dry-run manifest. Type `C` to continue.
+
+HALT for input. When the operator types `C`, read fully and follow `./step-02-dryrun.md`.
+
+## CRITICAL STEP COMPLETION NOTE
+
+ONLY when the operator has confirmed scope and typed `C` will you read fully and follow `./step-02-dryrun.md`. Do NOT auto-proceed.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Operator understands what migration does
+- File counts shown for default scope
+- `{{scope}}` captured (default or custom) and validated
+- Operator typed `C` to proceed
+
+### ❌ SYSTEM FAILURE:
+
+- Invoking the migration CLI in this step
+- Auto-proceeding without `C`
+- Accepting an unvalidated custom scope
+- Skipping the file count display
+
+**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/steps/step-02-dryrun.md

@@ -0,0 +1,199 @@
+# Step 2: Dry-Run Review
+
+## STEP GOAL:
+
+To run the migration in dry-run mode, parse the manifest output into 5 categories, and present them to the operator in a structured format (instead of dumping the raw CLI wall of text).
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER skip the dry-run — every migration MUST go through this step
+- 📖 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 presenting categorized results, not a content generator
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+### Role Reinforcement:
+
+- ✅ You parse the CLI's output into buckets and present them clearly
+- ✅ The operator should never see a raw 70-line wall of text — group by category
+
+### Step-Specific Rules:
+
+- 🎯 Focus ONLY on dry-run + categorization in this step
+- 🚫 FORBIDDEN to invoke `--apply` (Step 4 does that)
+- 🚫 FORBIDDEN to ask for resolutions yet (Step 3 does that)
+- 💬 Hold the parsed bucket data in working memory for Step 3 to consume
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Shell out to the CLI in dry-run mode
+- 💾 Parse output into 7 buckets via simple substring matching (NOT regex)
+- 🚫 FORBIDDEN to load next step until the operator selects 'C' or 'X'
+
+## CONTEXT BOUNDARIES:
+
+- Available context: `{{scope}}` from Step 1
+- Focus: dry-run execution + output parsing + bucket presentation
+- Limits: no resolution prompts, no apply
+- Dependencies: Step 1 must have set `{{scope}}`
+
+## Sequence of Instructions (Do not deviate, skip, or optimize)
+
+### 1. Run the migration in dry-run mode
+
+Shell out to:
+
+```
+node scripts/migrate-artifacts.js --include {{scope}}
+```
+
+Capture stdout in full. **Note:** the CLI returns immediately after printing the manifest in dry-run mode (no `--apply`) — it does NOT enter the interactive ambiguity prompt. That only fires in apply mode. So this shell-out cannot hang on operator input. The CLI will output a manifest in this format (defined in `scripts/lib/artifact-utils.js` `formatManifest()`):
+
+```
+[SKIP] dir/file.md -- already governed
+[INJECT] dir/file.md -- frontmatter needed
+dir/old.md -> dir/new.md
+  Initiative: name (confidence: high, source: inferred)
+  Type: name (confidence: high, source: prefix)
+  [!] COLLISION: same target as dir/other.md
+  Suggested rename: dir/new-with-suffix.md
+[!] dir/file.md -> CONFLICT (filename says X, frontmatter says Y)
+  ACTION REQUIRED: Resolve initiative conflict before migration
+[!] dir/file.md -> ??? (ambiguous -- type: prd, initiative unknown)
+  Line 1: "..."
+  Line 2: "..."
+  Line 3: "..."
+  Git author: Name (date)
+  Suggested: convoke (source: folder-default, confidence: low)
+  REVIEW SUGGESTION: Accept 'convoke' or specify initiative
+[!] dir/file.md -> ??? (ambiguous -- type: prd, initiative unknown)
+  Line 1: "..."
+  ACTION REQUIRED: Specify initiative for this file
+
+--- Manifest Summary ---
+Total: 73 | Rename: 42 | Skip: 0 | Inject: 0 | Conflict: 0 | Ambiguous: 31
+[!] 1 filename collision(s) detected -- resolve before executing
+```
+
+### 2. Parse the output into 7 buckets
+
+Use **simple substring matching**, not regex. Walk the output line by line and bucket each entry by its action label:
+
+| Bucket | Detection rule |
+|--------|---------------|
+| **SKIP** | Line starts with `[SKIP] ` |
+| **INJECT_ONLY** | Line starts with `[INJECT] ` |
+| **CLEAN RENAME** | Line contains ` -> ` AND does NOT start with `[!] ` (i.e., the rename arrow appears, the line is not flagged ambiguous/conflict) AND no `[!] COLLISION` appears in the next 2–4 lines |
+| **COLLISION** | A line matching the CLEAN RENAME shape but with `[!] COLLISION:` in one of its 2–4 follow-up lines (categorized as COLLISION instead of CLEAN RENAME) |
+| **CONFLICT** | Line starts with `[!] ` and contains `-> CONFLICT (` |
+| **REVIEW SUGGESTION** | Line starts with `[!] ` and contains `??? (ambiguous` AND a subsequent `Suggested:` line exists before the next entry |
+| **PURE AMBIGUOUS** | Line starts with `[!] ` and contains `??? (ambiguous` AND NO `Suggested:` line follows before the next entry |
+
+For each entry, store in working memory:
+- `oldPath` (the full `dir/filename.md`)
+- `category` (one of the 7 above)
+- For RENAMEs: `newPath`, `initiative`, `type`
+- For COLLISIONs: `suggestedNewPath`, `collisionWith`
+- For REVIEW SUGGESTIONs: `suggestedInitiative`, `suggestedFrom`, `suggestedConfidence`, `firstLines` (the 3 context lines), `gitAuthor`
+- For PURE AMBIGUOUS: `firstLines`, `gitAuthor`, `candidates`
+
+This bucket data structure becomes `{{buckets}}` for Step 3.
+
+### 3. Present the categorized results
+
+Display in this order, with clear visual separation:
+
+> ### 📊 Dry-Run Summary
+>
+> **Total entries:** {total}
+>
+> ---
+>
+> ✅ **{N} clean renames** (no operator action needed)
+>
+> First 5 examples:
+> - `{old1}` → `{new1}`
+> - `{old2}` → `{new2}`
+> - ... (truncate after 5; show "_+ {N-5} more_" if there are more)
+>
+> ---
+>
+> 💡 **{N} review suggestions** (the engine has a default — you can accept or override)
+>
+> Each entry on its own line:
+> - `{old}` → suggested `{initiative}` (`{source}`, confidence `{confidence}`)
+> - ...
+>
+> ---
+>
+> ❗ **{N} pure ambiguous** (no suggestion — operator must specify)
+>
+> Each entry with first content line:
+> - `{old}` — _line 1: "{first_line}"_
+> - ...
+>
+> ---
+>
+> ⚠️ **{N} collisions** (auto-suggested differentiator if available)
+>
+> Each entry on its own line:
+> - `{old}` → collides with `{other}`. Suggested: `{suggestedNewPath}`
+>
+> ---
+>
+> 🚨 **{N} conflicts** (filename ↔ frontmatter mismatch — must resolve manually before migration)
+>
+> Each entry with the conflict description.
+>
+> ---
+>
+> 📁 **{N} skip** / 💉 **{N} inject-only** (no action needed)
+
+If a bucket is empty, omit its section entirely (don't show "0 collisions").
+
+### 4. Present continuation menu
+
+Display this menu and HALT for input:
+
+```
+[C] Continue to resolution (Step 3)
+[X] Exit — abort the migration entirely
+```
+
+### 5. Handle the operator's response
+
+**IF the operator chose `[C]`:**
+- If both `REVIEW SUGGESTION` and `PURE AMBIGUOUS` buckets are EMPTY: skip Step 3 entirely and go directly to Step 4 (nothing to resolve).
+- Otherwise: read fully and follow `./step-03-resolve.md`.
+
+**IF the operator chose `[X]`:**
+- Reply: `"Migration aborted at dry-run stage. No changes made."`
+- HALT permanently.
+
+## CRITICAL STEP COMPLETION NOTE
+
+ONLY when the operator has typed `C` and the bucket data is captured will you read fully and follow the next step. Do NOT auto-proceed.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Dry-run CLI invoked with `{{scope}}`
+- All entries parsed into the correct bucket
+- Categories presented in the correct visual order
+- Bucket data held in working memory for Step 3
+- Operator typed `C` or `X`
+
+### ❌ SYSTEM FAILURE:
+
+- Dumping the raw CLI output without parsing
+- Skipping the bucket presentation
+- Auto-proceeding without `C`
+- Invoking `--apply` in this step
+- Asking resolution questions in this step
+
+**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/steps/step-03-resolve.md

@@ -0,0 +1,174 @@
+# Step 3: Interactive Resolution
+
+## STEP GOAL:
+
+To walk the operator through the REVIEW SUGGESTION and PURE AMBIGUOUS entries from Step 2 conversationally, capturing each decision into the `{{resolutions}}` map that Step 4 will write to the resolution-file JSON.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER skip an entry without explicit operator input (or batch shortcut)
+- 📖 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 — present each decision, capture the answer, move on
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+### Role Reinforcement:
+
+- ✅ You are walking the operator through one decision at a time
+- ✅ Operator decisions are AUTHORITATIVE — never override or "fix" them
+- ✅ Use the batch shortcut (`all <initiative>`) to keep the loop manageable
+
+### Step-Specific Rules:
+
+- 🎯 Focus ONLY on resolution capture in this step
+- 🚫 FORBIDDEN to invoke the migration CLI in this step (Step 4 does that)
+- 🚫 FORBIDDEN to skip an entry without operator input
+- 💬 Operator overrides MUST be honored — never silently dropped
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Iterate REVIEW SUGGESTION first, then PURE AMBIGUOUS
+- 💾 Build `{{resolutions}}` map keyed by `oldPath` with `{ action, initiative? }` values
+- 🚫 FORBIDDEN to load next step until the operator selects 'C' or all entries are resolved/skipped
+
+## CONTEXT BOUNDARIES:
+
+- Available context: `{{scope}}` from Step 1, `{{buckets}}` from Step 2
+- Focus: capturing operator decisions for ambiguous entries
+- Limits: no CLI invocation, no apply
+- Dependencies: Step 2 must have parsed entries into `REVIEW SUGGESTION` and `PURE AMBIGUOUS` buckets
+
+## Sequence of Instructions (Do not deviate, skip, or optimize)
+
+### 1. Initialize the resolutions map
+
+In working memory, create:
+
+```
+{{resolutions}} = {}    // keyed by oldPath, values: { action: 'rename'|'skip', initiative?: string }
+```
+
+Counters (separate per loop so REVIEW SUGGESTION skips don't bleed into PURE AMBIGUOUS counts):
+
+- For the REVIEW SUGGESTION loop: `accepted = 0`, `overriddenSuggestions = 0`, `skippedSuggestions = 0`
+- For the PURE AMBIGUOUS loop: `resolvedAmbiguous = 0`, `skippedAmbiguous = 0`
+
+The final summary aggregates these as: `accepted` + `overriddenSuggestions` + `resolvedAmbiguous` = total renames; `skippedSuggestions` + `skippedAmbiguous` = total skipped.
+
+### 2. Walk REVIEW SUGGESTION entries
+
+For EACH entry in `{{buckets}}.REVIEW_SUGGESTION` (in order), do:
+
+1. Display:
+   ```
+   📄 {oldPath}
+      First lines: "{firstLines[0]}"
+                   "{firstLines[1]}"
+                   "{firstLines[2]}"
+      Git author: {gitAuthor}
+      Suggested: {suggestedInitiative} (source: {suggestedFrom}, confidence: {suggestedConfidence})
+
+   Accept '{suggestedInitiative}'? [y/n/specify <initiative>/skip]
+   ```
+
+2. HALT for input.
+
+3. Parse the response:
+   - **`y` (or yes, accept)** → `{{resolutions}}[oldPath] = { action: 'rename', initiative: '{suggestedInitiative}' }`. Increment `accepted`.
+   - **`n` (or no)** → ask `"Specify initiative or 'skip':"` and HALT. Then:
+     - If `skip` → `{{resolutions}}[oldPath] = { action: 'skip' }`. Increment `skippedSuggestions`.
+     - If a valid initiative ID (in taxonomy) → `{{resolutions}}[oldPath] = { action: 'rename', initiative: '{specified}' }`. Increment `overriddenSuggestions`.
+     - If invalid → re-ask, looping until valid.
+   - **`specify <initiative>`** → if the initiative is valid, treat as override. Increment `overriddenSuggestions`.
+   - **`skip`** → `{{resolutions}}[oldPath] = { action: 'skip' }`. Increment `skippedSuggestions`.
+
+4. Move to the next entry.
+
+After all REVIEW SUGGESTION entries are processed, summarize:
+
+> ✅ Review suggestions: {accepted} accepted, {overriddenSuggestions} overridden, {skippedSuggestions} skipped.
+
+### 3. Walk PURE AMBIGUOUS entries
+
+For EACH entry in `{{buckets}}.PURE_AMBIGUOUS` (in order), do:
+
+1. Display:
+   ```
+   📄 {oldPath}
+      First lines: "{firstLines[0]}"
+                   "{firstLines[1]}"
+                   "{firstLines[2]}"
+      Git author: {gitAuthor}
+      Candidates: {candidates joined or 'none'}
+
+   Specify initiative for this file [<initiative>/skip/all <initiative>]
+   ```
+
+2. HALT for input.
+
+3. Parse the response:
+   - **`<initiative>`** → if valid (in taxonomy), `{{resolutions}}[oldPath] = { action: 'rename', initiative: '{specified}' }`. Increment `resolvedAmbiguous`.
+   - **`skip`** → `{{resolutions}}[oldPath] = { action: 'skip' }`. Increment `skippedAmbiguous`.
+   - **`all <initiative>`** → BATCH SHORTCUT. Apply `{ action: 'rename', initiative: '{specified}' }` to THIS entry AND every remaining PURE AMBIGUOUS entry in the SAME directory as this one. Increment `resolvedAmbiguous` for each. Tell the operator: `"Applied '{initiative}' to N files in {dir}/."`. Then continue iterating from where the batch ended.
+   - **invalid** → re-ask, looping until valid.
+
+4. Move to the next entry (unless batch-applied).
+
+After all PURE AMBIGUOUS entries are processed, summarize:
+
+> ❗ Pure ambiguous: {resolvedAmbiguous} resolved, {skippedAmbiguous} skipped.
+
+### 4. Final summary and continuation menu
+
+Display:
+
+> ### 🎯 Resolution Summary
+>
+> - **Accepted suggestions:** {accepted}
+> - **Operator overrides:** {overriddenSuggestions + resolvedAmbiguous}
+> - **Skipped:** {skippedSuggestions + skippedAmbiguous}
+> - **Total entries in resolution map:** {Object.keys(resolutions).length}
+>
+> ---
+>
+> [C] Continue to confirm & execute (Step 4)
+> [X] Exit — abort the migration entirely
+
+HALT for input.
+
+### 5. Handle the operator's response
+
+**IF the operator chose `[C]`:**
+- Read fully and follow `./step-04-execute.md`.
+
+**IF the operator chose `[X]`:**
+- Reply: `"Migration aborted at resolution stage. No changes made. Resolutions discarded."`
+- HALT permanently.
+
+## CRITICAL STEP COMPLETION NOTE
+
+ONLY when every REVIEW SUGGESTION and PURE AMBIGUOUS entry has been processed AND the operator has typed `C` will you read fully and follow `./step-04-execute.md`. Do NOT auto-proceed.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Every REVIEW SUGGESTION entry processed (accept/override/skip)
+- Every PURE AMBIGUOUS entry processed (specify/skip/batch)
+- `{{resolutions}}` map populated with `{ action, initiative? }` per entry
+- Counters accurate
+- Operator typed `C` to proceed
+
+### ❌ SYSTEM FAILURE:
+
+- Skipping an entry without operator input
+- Silently changing the operator's specified initiative
+- Auto-proceeding without `C`
+- Forgetting to capture the resolution into the map
+- Invoking the CLI in this step
+
+**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.