@codeyam/codeyam-cli 0.1.0-staging.dbc742d → 0.1.0-staging.e057775

package/analyzer-template/.build-info.json

@@ -1,10 +1,10 @@
 {
-  "buildTimestamp": "2026-03-11T23:48:31.827Z",
-  "buildTime": 1773272911827,
-  "gitCommit": "dbc742d16ca0f4ce4f172093f89fa5dfdcaebd9e",
+  "buildTimestamp": "2026-03-12T17:48:53.671Z",
+  "buildTime": 1773337733671,
+  "gitCommit": "e05777544c54b403dfcde166b28b6ec249aec06a",
   "nodeVersion": "v20.20.0",
   "contentHash": "c6e453b5eb8471fdcb3e34085216f7d6523809504f12ddb1c6ee11665149d827",
-  "buildNumber": 952,
-  "semanticVersion": "0.1.952",
-  "version": "0.1.952 (2026-03-11T23:48+c6e453b)"
+  "buildNumber": 962,
+  "semanticVersion": "0.1.962",
+  "version": "0.1.962 (2026-03-12T17:48+c6e453b)"
 }

package/analyzer-template/log.txt

@@ -1,7 +1,7 @@
 
-[3/11/2026, 11:48:31 PM] > codeyam-combo@1.0.0 mergeDependencies
-[3/11/2026, 11:48:31 PM] > node ./scripts/mergePackageJsonFiles.cjs
+[3/12/2026, 5:48:53 PM] > codeyam-combo@1.0.0 mergeDependencies
+[3/12/2026, 5:48:53 PM] > node ./scripts/mergePackageJsonFiles.cjs
 
 
-[3/11/2026, 11:48:31 PM] Merged dependencies into root package.json
+[3/12/2026, 5:48:53 PM] Merged dependencies into root package.json
 

package/codeyam-cli/src/commands/__tests__/editor.stepDispatch.test.js

@@ -0,0 +1,45 @@
+import fs from 'fs';
+import path from 'path';
+/**
+ * Structural test: the CLI dispatch switch in editor.ts must have case labels
+ * for every step 1–16. Without this test, it's easy to add new steps
+ * (e.g. 14, 15, 16) to the printStep functions and STEP_LABELS but forget
+ * to add matching case labels to the switch statement — causing `codeyam editor N`
+ * to silently do nothing for the missing steps.
+ *
+ * This test reads the source file and parses the switch block that dispatches
+ * step numbers to their handlers.
+ */
+describe('editor CLI step dispatch', () => {
+    const editorSource = fs.readFileSync(path.join(__dirname, '..', 'editor.ts'), 'utf8');
+    it('should have switch case labels for all steps 1–16', () => {
+        // Find the switch(step) block in the CLI dispatch section.
+        // There are two stepFns definitions in editor.ts:
+        //   1. Test/debug scenario generator (~line 4658) — uses a for-loop, not a switch
+        //   2. CLI dispatch (~line 5263) — uses switch(step) { case N: ... }
+        //
+        // We need to verify the second one (CLI dispatch) has cases for all 16 steps.
+        // Find all `case N:` labels in the file. The CLI dispatch switch is the
+        // only switch on `step` that uses numbered cases.
+        const switchMatch = editorSource.match(/switch\s*\(step\)\s*\{([\s\S]*?)\n\s{4}\}/);
+        expect(switchMatch).not.toBeNull();
+        const switchBody = switchMatch[1];
+        for (let step = 1; step <= 16; step++) {
+            const casePattern = new RegExp(`case\\s+${step}\\s*[:{]`);
+            expect(switchBody).toMatch(casePattern);
+        }
+    });
+    it('should have STEP_LABELS entries for all steps 1–16', () => {
+        for (let step = 1; step <= 16; step++) {
+            const labelPattern = new RegExp(`${step}:\\s*'[^']+'`);
+            expect(editorSource).toMatch(labelPattern);
+        }
+    });
+    it('should have printStep functions defined for all steps 1–16', () => {
+        for (let step = 1; step <= 16; step++) {
+            const fnPattern = new RegExp(`function\\s+printStep${step}\\s*\\(`);
+            expect(editorSource).toMatch(fnPattern);
+        }
+    });
+});
+//# sourceMappingURL=editor.stepDispatch.test.js.map

package/codeyam-cli/src/commands/__tests__/editor.stepDispatch.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"editor.stepDispatch.test.js","sourceRoot":"","sources":["../../../../../src/commands/__tests__/editor.stepDispatch.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,IAAI,CAAC;AACpB,OAAO,IAAI,MAAM,MAAM,CAAC;AAExB;;;;;;;;;GASG;AACH,QAAQ,CAAC,0BAA0B,EAAE,GAAG,EAAE;IACxC,MAAM,YAAY,GAAG,EAAE,CAAC,YAAY,CAClC,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,EAAE,WAAW,CAAC,EACvC,MAAM,CACP,CAAC;IAEF,EAAE,CAAC,mDAAmD,EAAE,GAAG,EAAE;QAC3D,2DAA2D;QAC3D,kDAAkD;QAClD,kFAAkF;QAClF,qEAAqE;QACrE,EAAE;QACF,8EAA8E;QAE9E,wEAAwE;QACxE,kDAAkD;QAClD,MAAM,WAAW,GAAG,YAAY,CAAC,KAAK,CACpC,2CAA2C,CAC5C,CAAC;QACF,MAAM,CAAC,WAAW,CAAC,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC;QAEnC,MAAM,UAAU,GAAG,WAAY,CAAC,CAAC,CAAC,CAAC;QAEnC,KAAK,IAAI,IAAI,GAAG,CAAC,EAAE,IAAI,IAAI,EAAE,EAAE,IAAI,EAAE,EAAE,CAAC;YACtC,MAAM,WAAW,GAAG,IAAI,MAAM,CAAC,WAAW,IAAI,UAAU,CAAC,CAAC;YAC1D,MAAM,CAAC,UAAU,CAAC,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;QAC1C,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,oDAAoD,EAAE,GAAG,EAAE;QAC5D,KAAK,IAAI,IAAI,GAAG,CAAC,EAAE,IAAI,IAAI,EAAE,EAAE,IAAI,EAAE,EAAE,CAAC;YACtC,MAAM,YAAY,GAAG,IAAI,MAAM,CAAC,GAAG,IAAI,cAAc,CAAC,CAAC;YACvD,MAAM,CAAC,YAAY,CAAC,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC;QAC7C,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,4DAA4D,EAAE,GAAG,EAAE;QACpE,KAAK,IAAI,IAAI,GAAG,CAAC,EAAE,IAAI,IAAI,EAAE,EAAE,IAAI,EAAE,EAAE,CAAC;YACtC,MAAM,SAAS,GAAG,IAAI,MAAM,CAAC,wBAAwB,IAAI,SAAS,CAAC,CAAC;YACpE,MAAM,CAAC,YAAY,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;QAC1C,CAAC;IACH,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/codeyam-cli/src/commands/editor.js

@@ -11,7 +11,7 @@ import { IS_INTERNAL_BUILD } from "../utils/buildFlags.js";
 import { startBackgroundServer } from "../utils/backgroundServer.js";
 import { installClaudeCodeSkills } from "../utils/install-skills.js";
 import { setupClaudeCodeSettings } from "../utils/setupClaudeCodeSettings.js";
-import { getAnalyzerTemplatePath, isAnalyzerFinalized, } from "../utils/analyzer.js";
+import { ensureAnalyzerFinalized } from "../utils/analyzerFinalization.js";
 import { APP_FORMATS, TECH_STACKS } from "../data/techStacks.js";
 import { getProjectRoot as getStateProjectRoot } from "../state.js";
 import initCommand from "./init.js";
@@ -36,6 +36,9 @@ const STEP_LABELS = {
     11: 'Journal',
     12: 'Review',
     13: 'Present',
+    14: 'Commit',
+    15: 'Finalize',
+    16: 'Push',
 };
 /**
  * Append a JSONL log entry to .codeyam/logs/editor-log.jsonl
@@ -161,13 +164,13 @@ function stepHeader(step, title, feature) {
     console.log();
 }
 /**
- * Print a colored progress tracker showing all 13 steps.
+ * Print a colored progress tracker showing all 16 steps.
  * Steps before `current` are green ✓, `current` is bold cyan →, future steps are dim ○.
  */
 function printProgressTracker(current) {
     console.log();
     console.log(chalk.dim('  ┌─────────────────────────────────────┐'));
-    for (let i = 1; i <= 13; i++) {
+    for (let i = 1; i <= 16; i++) {
         const label = STEP_LABELS[i];
         const num = i < 10 ? ` ${i}` : `${i}`;
         const content = `${num}. ${label.padEnd(28)}`;
@@ -205,7 +208,7 @@ function stopGate(current, opts) {
     console.log(chalk.yellow('For the CURRENT step (→), show each checklist item with ✓ (done) or ✗ (skipped + reason).'));
     console.log(chalk.yellow('If any items are ✗, explain why and ask if the user wants to address them.'));
     console.log();
-    if (current < 13) {
+    if (current < 16) {
         console.log(chalk.green('When done, run: ') +
             chalk.bold(`codeyam editor ${current + 1}`));
     }
@@ -249,6 +252,14 @@ function printResumptionHeader(step) {
         ],
         12: ['Re-verify is safe to repeat — just re-run the checks'],
         13: ['Check if commit already made:\n      `git log --oneline -3`'],
+        14: ['Check if commit already made:\n      `git log --oneline -3`'],
+        15: [
+            'Check if journal was already updated with commit SHA:\n      `codeyam editor journal-list`',
+            'Check if commit was already amended:\n      `git log --oneline -3`',
+        ],
+        16: [
+            'Check if already pushed:\n      `git remote -v && git log --oneline origin/HEAD..HEAD 2>/dev/null`',
+        ],
     };
     const label = STEP_LABELS[step] || 'Unknown';
     console.log(chalk.bold.yellow(`━━━ RESUMING Step ${step}: ${label} ━━━`));
@@ -353,7 +364,7 @@ function parseDebugTargets(target) {
         }
         if (entry.startsWith('step-')) {
             const num = parseInt(entry.replace('step-', ''), 10);
-            if (!isNaN(num) && num >= 1 && num <= 13) {
+            if (!isNaN(num) && num >= 1 && num <= 16) {
                 valid.add(`step-${num}`);
                 continue;
             }
@@ -541,7 +552,7 @@ function printCycleOverview(root, state) {
         console.log(chalk.yellow('This applies even after committing — always use the change workflow.'));
     }
     else {
-        console.log('Each feature follows 13 steps. You MUST run each command in order:');
+        console.log('Each feature follows 16 steps. You MUST run each command in order:');
         console.log();
         console.log(`  ${chalk.bold.yellow(' 1')} ${chalk.bold('Plan')}            — Plan the feature, confirm with user`);
         console.log(`  ${chalk.bold.yellow(' 2')} ${chalk.bold('Prototype')}       — Build a working prototype fast`);
@@ -556,6 +567,9 @@ function printCycleOverview(root, state) {
         console.log(`  ${chalk.bold.yellow('11')} ${chalk.bold('Journal')}         — Create/update journal entry`);
         console.log(`  ${chalk.bold.yellow('12')} ${chalk.bold('Review')}          — Verify screenshots and audit`);
         console.log(`  ${chalk.bold.yellow('13')} ${chalk.bold('Present')}         — Present summary, get approval`);
+        console.log(`  ${chalk.bold.yellow('14')} ${chalk.bold('Commit')}          — Commit all changes`);
+        console.log(`  ${chalk.bold.yellow('15')} ${chalk.bold('Finalize')}        — Journal update + amend commit`);
+        console.log(`  ${chalk.bold.yellow('16')} ${chalk.bold('Push')}            — Push to remote`);
         console.log();
         console.log(chalk.green('Start now: ') + chalk.bold('codeyam editor 1'));
         console.log(chalk.dim('  If the user already described what they want, pass it: codeyam editor 1 --prompt "their message"'));
@@ -570,19 +584,19 @@ function printStep1(root, feature, options, userPrompt) {
     if (!isResuming) {
         clearState(root);
     }
-    // If feature is provided, save initial state so step 2 can pick it up
-    if (feature) {
-        const now = new Date().toISOString();
-        writeState(root, {
-            feature,
-            step: 1,
-            label: STEP_LABELS[1],
-            startedAt: isResuming ? prevState.startedAt : now,
-            featureStartedAt: isResuming ? prevState.featureStartedAt : now,
-            appFormats: options?.appFormats || prevState?.appFormats,
-            techStackId: options?.techStackId || prevState?.techStackId,
-        });
-    }
+    // Always persist state so step 2's validation sees that step 1 ran.
+    // The feature name may not be known yet (it's an output of planning) —
+    // use an empty string as placeholder; step 2 requires --feature anyway.
+    const now = new Date().toISOString();
+    writeState(root, {
+        feature: feature || prevState?.feature || '',
+        step: 1,
+        label: STEP_LABELS[1],
+        startedAt: isResuming ? prevState.startedAt : now,
+        featureStartedAt: isResuming ? prevState.featureStartedAt : now,
+        appFormats: options?.appFormats || prevState?.appFormats,
+        techStackId: options?.techStackId || prevState?.techStackId,
+    });
     // Save the user's original prompt to a separate file
     if (userPrompt) {
         const promptPath = path.join(root, '.codeyam', 'editor-user-prompt.txt');
@@ -818,7 +832,7 @@ function printStep3(root, feature) {
     console.log(chalk.bold('Present a selection menu to the user (use AskUserQuestion with these EXACT option labels):'));
     console.log(chalk.green('    Option 1 label: "The live preview is displaying what I expected"') + chalk.dim(' — proceed to step 4'));
     console.log(chalk.yellow('    Option 2 label: "I\'d like some changes"') +
-        chalk.dim(' — user describes changes, you make them, then re-present'));
+        chalk.dim(' — make changes, refresh preview, re-run `codeyam editor 3`'));
     console.log();
     console.log(chalk.dim('Wait for user approval before moving on. Refactoring and scenarios happen in later steps.'));
     stopGate(3, { confirm: true });
@@ -1325,32 +1339,98 @@ function printStep13(root, feature) {
         chalk.dim(' — describe changes, then re-verify'));
     console.log();
     console.log(chalk.bold('If the user chooses "Save & commit":'));
-    checkbox(`Hide the results panel first: \`codeyam editor hide-results\``);
+    checkbox('Advance to the commit step: `codeyam editor 14`');
+    console.log();
+    console.log(chalk.bold('If the user chooses "Make changes" (or asks for ANY change, even as a question):'));
+    checkbox(`Hide the results panel: \`codeyam editor hide-results\``);
+    checkbox('Ask what changes the user wants (if not already clear)');
+    checkbox(`Run: \`codeyam editor change "${feature}"\` — this gives you the change checklist`);
+    checkbox('THEN make the requested changes and follow the checklist');
+    console.log(chalk.red.bold('  IMPORTANT: Always run the change command BEFORE writing any code.'));
+    stopGate(13, { confirm: true });
+}
+// ─── Step 14: Commit ─────────────────────────────────────────────────
+function printStep14(root, feature) {
+    const prevState = readState(root);
+    const isResuming = prevState?.step === 14;
+    const now = new Date().toISOString();
+    writeState(root, {
+        feature,
+        step: 14,
+        label: STEP_LABELS[14],
+        startedAt: isResuming ? prevState.startedAt : now,
+        featureStartedAt: prevState?.featureStartedAt || now,
+    });
+    logEvent(root, 'step', { step: 14, label: 'Commit', feature });
+    stepHeader(14, 'Commit', feature);
+    if (isResuming) {
+        printResumptionHeader(14);
+    }
+    console.log('Commit all changes for this feature.');
+    console.log();
+    console.log(chalk.bold('Checklist:'));
+    checkbox(`Hide the results panel: \`codeyam editor hide-results\``);
     checkbox(`Git commit using the journal description: \`codeyam editor commit '{"message":"feat: <title>\\n\\n<journal description>"}'\``);
     console.log(chalk.dim('    The commit message body MUST match the journal description exactly'));
+    stopGate(14);
+}
+// ─── Step 15: Finalize ───────────────────────────────────────────────
+function printStep15(root, feature) {
+    const prevState = readState(root);
+    const isResuming = prevState?.step === 15;
+    const now = new Date().toISOString();
+    writeState(root, {
+        feature,
+        step: 15,
+        label: STEP_LABELS[15],
+        startedAt: isResuming ? prevState.startedAt : now,
+        featureStartedAt: prevState?.featureStartedAt || now,
+    });
+    logEvent(root, 'step', { step: 15, label: 'Finalize', feature });
+    stepHeader(15, 'Finalize', feature);
+    if (isResuming) {
+        printResumptionHeader(15);
+    }
+    console.log('Update the journal with the commit SHA and amend the commit.');
+    console.log();
+    console.log(chalk.bold('Checklist:'));
     checkbox(`Update journal with commit SHA: \`codeyam editor journal-update '{"time":"<journal entry time>","commitSha":"<sha>","commitMessage":"feat: <title>"}'\``);
     checkbox('Amend the commit to include the journal update: `git add .codeyam/journal/ && git commit --amend --no-edit`');
     console.log(chalk.dim('    The journal-update modifies journal files after the commit — amend to keep the tree clean.'));
+    stopGate(15);
+}
+// ─── Step 16: Push ───────────────────────────────────────────────────
+function printStep16(root, feature) {
+    const prevState = readState(root);
+    const isResuming = prevState?.step === 16;
+    const now = new Date().toISOString();
+    writeState(root, {
+        feature,
+        step: 16,
+        label: STEP_LABELS[16],
+        startedAt: isResuming ? prevState.startedAt : now,
+        featureStartedAt: prevState?.featureStartedAt || now,
+    });
+    logEvent(root, 'step', { step: 16, label: 'Push', feature });
+    stepHeader(16, 'Push', feature);
+    if (isResuming) {
+        printResumptionHeader(16);
+    }
+    console.log('Push the commit to the remote repository.');
+    console.log();
+    console.log(chalk.bold('Checklist:'));
     checkbox('Check if a git remote is configured: `git remote -v`');
-    console.log(chalk.dim('    If a remote exists, ask the user: "Would you like me to push this commit to the remote?"'));
+    checkbox("Offer to push to remote (AskUserQuestion — STOP and wait for the user's answer before proceeding):");
+    console.log(chalk.dim('    If a remote exists, ask (AskUserQuestion): "Would you like me to push this commit to the remote?" with options "Yes, push" and "No, skip"'));
     console.log(chalk.dim('    If the user says yes, run: `git push`'));
-    console.log(chalk.dim('    If NO remote exists, ask: "This project doesn\'t have a git remote yet. Would you like help setting one up? I can walk you through creating a GitHub repository."'));
+    console.log(chalk.dim('    If NO remote exists, ask (AskUserQuestion): "This project doesn\'t have a git remote yet. Would you like help setting one up? I can walk you through creating a GitHub repository." with options "Yes, set up remote" and "No, skip"'));
     console.log(chalk.dim('    If the user wants help, guide them through `gh repo create` or manual GitHub setup, then push.'));
-    console.log(chalk.green('  Then run: ') +
-        chalk.bold('codeyam editor steps') +
-        chalk.green(' to start the next feature'));
+    checkbox('After the user responds, run: `codeyam editor steps` to start the next feature');
     console.log();
     console.log(chalk.red.bold('  If the user reports a bug or requests a fix after committing:'));
     console.log(chalk.red.bold('  You MUST still run `codeyam editor change` before making any changes.'));
     console.log(chalk.red.bold('  The change workflow applies to ALL changes — post-commit fixes are not an exception.'));
-    console.log();
-    console.log(chalk.bold('If the user chooses "Make changes" (or asks for ANY change, even as a question):'));
-    checkbox(`Hide the results panel: \`codeyam editor hide-results\``);
-    checkbox('Ask what changes the user wants (if not already clear)');
-    checkbox(`Run: \`codeyam editor change "${feature}"\` — this gives you the change checklist`);
-    checkbox('THEN make the requested changes and follow the checklist');
-    console.log(chalk.red.bold('  IMPORTANT: Always run the change command BEFORE writing any code.'));
-    stopGate(13, { confirm: true });
+    stopGate(16, { confirm: true });
 }
 // ─── Command definition ───────────────────────────────────────────────
 // ─── Analyze-imports subcommand ────────────────────────────────────────
@@ -1876,15 +1956,15 @@ async function handleDependents(entityName) {
  * `codeyam editor change <feature>`
  *
  * Prints a condensed post-change checklist that guides Claude through
- * re-verifying after user-requested modifications. This is the "change
- * loop" — it replaces the freeform "make changes" path with structured
- * instructions that always loop back to step 13 present.
+ * re-verifying after user-requested modifications. When called from
+ * step 13+, this loops back to step 13 (present). When called from an
+ * earlier step, it returns to that step so the normal flow continues.
  */
 function handleChange(feature) {
     const root = getProjectRoot();
+    const state = readState(root);
     if (!feature) {
         // Try to read feature from state
-        const state = readState(root);
         if (state?.feature) {
             feature = state.feature;
         }
@@ -1894,6 +1974,7 @@ function handleChange(feature) {
             process.exit(1);
         }
     }
+    const currentStep = state?.step ?? 13;
     const port = getServerPort();
     console.log();
     console.log(chalk.bold.cyan('━━━ Change Loop ━━━'));
@@ -1961,12 +2042,24 @@ function handleChange(feature) {
     console.log(chalk.dim('    Always update the existing uncommitted entry — do NOT create a new one.'));
     console.log(chalk.dim('    Only create a new entry (POST) if no uncommitted entry exists for this feature.'));
     console.log();
-    console.log(chalk.red('  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━'));
-    console.log(chalk.red.bold('  REQUIRED: Show Results'));
-    console.log(chalk.red.bold('  When all checks pass, you MUST run: ') +
-        chalk.bold(`codeyam editor 13`));
-    console.log(chalk.red.bold('  The user ALWAYS expects to see results after changes. DO NOT skip this step.'));
-    console.log(chalk.red('  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━'));
+    // If the change was initiated from a step before 13, return to that step
+    // instead of jumping to step 13. The change workflow should only loop to
+    // step 13 when changes are requested FROM step 13.
+    if (currentStep < 13) {
+        console.log(chalk.red('  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━'));
+        console.log(chalk.red.bold('  REQUIRED: Return to current step'));
+        console.log(chalk.red.bold('  When all checks pass, you MUST run: ') +
+            chalk.bold(`codeyam editor ${currentStep}`));
+        console.log(chalk.red('  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━'));
+    }
+    else {
+        console.log(chalk.red('  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━'));
+        console.log(chalk.red.bold('  REQUIRED: Show Results'));
+        console.log(chalk.red.bold('  When all checks pass, you MUST run: ') +
+            chalk.bold(`codeyam editor 13`));
+        console.log(chalk.red.bold('  The user ALWAYS expects to see results after changes. DO NOT skip this step.'));
+        console.log(chalk.red('  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━'));
+    }
     console.log();
 }
 // ─── Audit gate ─────────────────────────────────────────────────────
@@ -2359,6 +2452,9 @@ async function handleTemplate() {
             // Config parse error is non-fatal
         }
     }
+    // 5b. Write a fresh prototypeId so the proxy clears stale localStorage
+    const activeScenarioPath = path.join(root, '.codeyam', 'active-scenario.json');
+    fs.writeFileSync(activeScenarioPath, JSON.stringify({ prototypeId: Date.now().toString() }), 'utf-8');
     // 6. Trigger editor-refresh so the server picks up the new project
     console.log(chalk.bold('Refreshing editor...'));
     try {
@@ -2570,8 +2666,11 @@ function handleEditorDebug(args) {
         11: printStep11,
         12: printStep12,
         13: printStep13,
+        14: printStep14,
+        15: printStep15,
+        16: printStep16,
     };
-    for (let step = 1; step <= 13; step++) {
+    for (let step = 1; step <= 16; step++) {
         const stepId = `step-${step}`;
         if (!wants(stepId))
             continue;
@@ -2650,8 +2749,8 @@ const editorCommand = {
     describe: 'Editor mode guided workflow',
     builder: (yargs) => {
         const stepDescription = IS_INTERNAL_BUILD
-            ? 'Step number (1-13) or subcommand (template, register, isolate, analyze-imports, dependents, audit, scenarios, scenario-coverage, change, sync, debug, preview, show-results, hide-results, commit, journal, journal-list, journal-update, dev-server, client-errors)'
-            : 'Step number (1-13) or subcommand (template, register, isolate, analyze-imports, dependents, audit, scenarios, scenario-coverage, change, sync, preview, show-results, hide-results, commit, journal, journal-list, journal-update, dev-server, client-errors)';
+            ? 'Step number (1-16) or subcommand (template, register, isolate, analyze-imports, dependents, audit, scenarios, scenario-coverage, change, sync, debug, preview, show-results, hide-results, commit, journal, journal-list, journal-update, dev-server, client-errors)'
+            : 'Step number (1-16) or subcommand (template, register, isolate, analyze-imports, dependents, audit, scenarios, scenario-coverage, change, sync, preview, show-results, hide-results, commit, journal, journal-list, journal-update, dev-server, client-errors)';
         let builder = yargs
             .positional('step', {
             type: 'string',
@@ -2687,7 +2786,7 @@ const editorCommand = {
             builder = builder
                 .option('target', {
                 type: 'string',
-                describe: 'Debug target (setup, overview, overview-with-state, step-1..step-13, or comma-separated list)',
+                describe: 'Debug target (setup, overview, overview-with-state, step-1..step-16, or comma-separated list)',
             })
                 .option('resume', {
                 type: 'boolean',
@@ -2819,9 +2918,9 @@ const editorCommand = {
             }
             else {
                 const state = readState(root);
-                // Clear prompt file when feature is done (step 13) so the hook
+                // Clear prompt file when feature is done (step 16) so the hook
                 // can capture the next feature request from the user.
-                if (state?.step === 13) {
+                if (state?.step === 16) {
                     clearEditorUserPrompt(root);
                 }
                 printCycleOverview(root, state);
@@ -2829,8 +2928,8 @@ const editorCommand = {
             return;
         }
         const step = argv.step ? parseInt(argv.step, 10) : undefined;
-        if (step != null && (isNaN(step) || step < 1 || step > 13)) {
-            console.error(chalk.red(`Error: Invalid step "${argv.step}". Must be 1-13.`));
+        if (step != null && (isNaN(step) || step < 1 || step > 16)) {
+            console.error(chalk.red(`Error: Invalid step "${argv.step}". Must be 1-16.`));
             process.exit(1);
         }
         if (step == null) {
@@ -2970,29 +3069,15 @@ const editorCommand = {
                     editorMode,
                 });
                 // Auto-finalize analyzer so codeyam analyze works
-                if (editorMode && !isAnalyzerFinalized()) {
-                    try {
-                        const { execSync } = await import('child_process');
-                        const templatePath = getAnalyzerTemplatePath();
-                        if (fs.existsSync(templatePath)) {
-                            console.log('  Setting up simulations (first time only)...');
-                            execSync('npm install --include=dev', {
-                                cwd: templatePath,
-                                stdio: 'pipe',
-                            });
-                            execSync('npx playwright install chromium', {
-                                cwd: templatePath,
-                                stdio: 'pipe',
-                            });
-                            execSync('npm run build', {
-                                cwd: templatePath,
-                                stdio: 'pipe',
-                            });
-                            fs.writeFileSync(path.join(templatePath, '.finalized'), new Date().toISOString());
-                        }
+                if (editorMode) {
+                    const finalization = ensureAnalyzerFinalized();
+                    if (finalization.needed) {
+                        console.log(`  Setting up simulations (${finalization.stepsRun.join(', ')})...`);
                     }
-                    catch {
-                        // Non-fatal
+                    if (finalization.errors.length > 0) {
+                        for (const err of finalization.errors) {
+                            console.warn(`  Warning: ${err.step} failed: ${err.message}`);
+                        }
                     }
                 }
                 // Start background server (handles killing existing servers internally)
@@ -3043,11 +3128,17 @@ const editorCommand = {
             return;
         }
         const state = readState(root);
-        // Validate step transition — prevent skipping steps
-        const stepError = validateStepTransition(step, state?.step ?? null);
-        if (stepError) {
-            console.error(chalk.red(`Error: ${stepError}`));
-            process.exit(1);
+        // Validate step transition — prevent skipping steps.
+        // Exception: step 2 with --feature is always allowed because step 1's
+        // instructions explicitly tell Claude to run `codeyam editor 2 --feature "..."`.
+        // Step 1 is planning-only and may not persist state (no --feature flag).
+        const skipValidation = step === 2 && argv.feature;
+        if (!skipValidation) {
+            const stepError = validateStepTransition(step, state?.step ?? null);
+            if (stepError) {
+                console.error(chalk.red(`Error: ${stepError}`));
+                process.exit(1);
+            }
         }
         switch (step) {
             case 1: {
@@ -3080,7 +3171,10 @@ const editorCommand = {
             case 10:
             case 11:
             case 12:
-            case 13: {
+            case 13:
+            case 14:
+            case 15:
+            case 16: {
                 const feature = argv.feature || state?.feature;
                 if (!feature) {
                     console.error(chalk.red('Error: No feature in progress. Run codeyam editor 1 first.'));
@@ -3107,6 +3201,9 @@ const editorCommand = {
                     11: printStep11,
                     12: printStep12,
                     13: printStep13,
+                    14: printStep14,
+                    15: printStep15,
+                    16: printStep16,
                 };
                 stepFns[step](root, feature);
                 break;