claudeos-core 2.3.1 → 2.4.0

package/bin/commands/init.js

@@ -3,6 +3,17 @@
  *
  * Runs the full 4-Pass pipeline: analyze → merge → generate → memory scaffold.
  * This is the main entry point for project bootstrapping.
+ *
+ * Refactored internally: cmdInit's 970-line monolith decomposed into ~16 stage
+ * helpers (checkPrerequisites, resolveLanguage, applyResumeMode,
+ * ensureDirectories, loadDomainGroups, loadPass1Prompts, runPass1Loop,
+ * runPass2, buildPass3ContextJson, handlePass3StaleMarker, dispatchPass3,
+ * runPass4, runVerificationTools, runLint, runContentValidator,
+ * printCompletionBanner). runPass3Split is preserved below unchanged.
+ *
+ * All string/regex patterns consumed by tests/*.test.js source-parity checks
+ * are preserved because the runPass3Split and key stale-marker/pass-4-marker
+ * logic are kept in this file verbatim.
  */
 
 const fs = require("fs");
@@ -194,9 +205,46 @@ async function runPass3Split(ctx) {
     return batches;
   }
 
+  // v2.4.0 — Stack-type classification helper.
+  //
+  // Returns `{ backend: Set<string>, frontend: Set<string>, isMultiStack: boolean }`
+  // built from `project-analysis.json`. The maps are used by
+  // `buildBatchScopeNote` to emit ALWAYS-typed per-domain paths
+  // (`70.domains/{type}/{domain}.md`) regardless of single/multi-stack.
+  // Uniform layout means single-stack projects pay a 1-folder depth
+  // cost in exchange for zero-migration when the other stack is later
+  // added, and validators recognize a single pattern. The `isMultiStack`
+  // flag is retained for tools that may want to surface the distinction
+  // (e.g. user-facing console output) but is no longer used to branch
+  // path generation.
+  function loadDomainTypeMap() {
+    const result = { backend: new Set(), frontend: new Set(), isMultiStack: false };
+    try {
+      const paPath = path.join(GENERATED_DIR, "project-analysis.json");
+      if (fileExists(paPath)) {
+        const pa = JSON.parse(readFile(paPath));
+        if (Array.isArray(pa.backendDomains)) {
+          for (const d of pa.backendDomains) {
+            const n = d && (d.name || d);
+            if (n) result.backend.add(n);
+          }
+        }
+        if (Array.isArray(pa.frontendDomains)) {
+          for (const d of pa.frontendDomains) {
+            const n = d && (d.name || d);
+            if (n) result.frontend.add(n);
+          }
+        }
+      }
+    } catch (_e) { /* tolerate missing/corrupt analysis — fallback to flat paths */ }
+    result.isMultiStack = result.backend.size > 0 && result.frontend.size > 0;
+    return result;
+  }
+
   const domainOrder = loadDomainOrder();
   const batches = computeBatches(domainOrder);
   const isBatched = batches.length > 1;
+  const domainTypeMap = loadDomainTypeMap();
 
   if (isBatched) {
     log(`    📦 Batch sub-division enabled: ${domainOrder.length} domains → ${batches.length} batches per stage (3b, 3c)`);
@@ -274,28 +322,100 @@ async function runPass3Split(ctx) {
   // and which common files to include vs skip.
   function buildBatchScopeNote(stageKind, batchIndex, totalBatches, batchDomains) {
     const isLastBatch = batchIndex === totalBatches - 1;
+    const isSingleBatch = totalBatches === 1;
     const domainList = batchDomains.map(d => `\`${d}\``).join(", ");
 
-    let note = `## Batch scope (${stageKind}-batch ${batchIndex + 1}/${totalBatches})\n\n`;
-    note += `This Pass 3 stage has been sub-divided into ${totalBatches} batches to avoid context overflow.\n`;
-    note += `**You are processing batch ${batchIndex + 1} of ${totalBatches}.**\n\n`;
+    // v2.4.0 — Always-typed per-domain layout.
+    //
+    // Every per-domain file lives under a `{type}/` sub-folder
+    // (`70.domains/backend/` or `70.domains/frontend/`) regardless of
+    // whether the project is single-stack or multi-stack. This is a
+    // deliberate uniform-convention choice:
+    //
+    //   - Single-stack projects pay a 1-folder depth cost; in exchange
+    //     they migrate to multi-stack with ZERO file moves when frontend
+    //     (or backend) is later added.
+    //   - LLM never has to decide which form to use → no probabilistic
+    //     drift between Pass 3 runs.
+    //   - Validators (content-validator, claude-md-validator) need
+    //     to recognize only ONE pattern.
+    //   - Future stack types (mobile, cli, agent, ...) extend naturally
+    //     by adding new `{type}/` sub-folders.
+    //
+    // Per-domain type lookup uses `domainTypeMap` from
+    // `project-analysis.json`. Domains not in either set fall back to
+    // `backend` (the dominant case in real-world projects) — this
+    // happens only when the analysis JSON is malformed or absent.
+    const typeOf = (name) => {
+      if (domainTypeMap.frontend.has(name)) return "frontend";
+      // backend is the default when the domain is unknown to both sets.
+      // This happens only on malformed analysis JSON; backend is the
+      // safer default since it's the dominant project type.
+      return "backend";
+    };
+    const stdPathFor = (name) => `claudeos-core/standard/70.domains/${typeOf(name)}/${name}.md`;
+    const rulePathFor = (name) => `.claude/rules/70.domains/${typeOf(name)}/${name}-rules.md`;
+    const stagedRulePathFor = (name) => `claudeos-core/generated/.staged-rules/70.domains/${typeOf(name)}/${name}-rules.md`;
+
+    let note = isSingleBatch
+      ? `## Per-domain scope (${stageKind}, single-batch run)\n\n`
+      : `## Batch scope (${stageKind}-batch ${batchIndex + 1}/${totalBatches})\n\n`;
+    if (isSingleBatch) {
+      note += `${batchDomains.length} domain(s) will be processed in this single Pass 3b stage.\n`;
+      note += `Per-domain files are REQUIRED regardless of domain count — they enable domain-scoped \`paths\` glob targeting for rules.\n\n`;
+    } else {
+      note += `This Pass 3 stage has been sub-divided into ${totalBatches} batches to avoid context overflow.\n`;
+      note += `**You are processing batch ${batchIndex + 1} of ${totalBatches}.**\n\n`;
+    }
 
     if (stageKind === "3b") {
-      note += `**Domains in THIS batch**: ${domainList}\n\n`;
-      note += `**Rules for this batch**:\n`;
-      note += `1. CLAUDE.md and all common standard/ files (00.core/, 30.security-db/, 40.infra/, etc.) are ALREADY GENERATED by the 3b-core stage. DO NOT regenerate them.\n`;
-      note += `2. Generate standard/ entries ONLY for the domains listed above — one section per domain.\n`;
-      note += `3. Generate .claude/rules/ (via staging-override path) — ONLY domain-specific rule files for the domains listed above. Common rules are already generated by 3b-core.\n`;
-      note += `4. DO NOT generate standard/ or rules/ files for domains NOT in the above list — those are/will be processed in other batches.\n`;
-      note += `5. If a file you are about to write already exists with substantive content (Rule B), skip it silently — print \`[SKIP] <path>\` and move on.\n`;
+      note += isSingleBatch
+        ? `**Domains in scope (all ${batchDomains.length})**: ${domainList}\n\n`
+        : `**Domains in THIS batch**: ${domainList}\n\n`;
+      // Always show per-domain target paths so the LLM follows the
+      // typed sub-folder convention without inferring from domain name.
+      note += `**Per-domain target paths (always under \`{type}/\` sub-folder — \`backend\` or \`frontend\`):**\n`;
+      for (const d of batchDomains) {
+        note += `- \`${d}\` → \`${stdPathFor(d)}\` and \`${rulePathFor(d)}\`\n`;
+      }
+      note += `\n`;
+      note += `**Rules**:\n`;
+      if (isSingleBatch) {
+        // Single-batch (≤15 domains): common files AND per-domain files in same stage.
+        note += `1. Generate ALL common files (CLAUDE.md + standard/00.core/* + standard/10.backend/* + standard/30.security-db/* + standard/40.infra/* + standard/80.verification/* + .claude/rules/00.core/* + .claude/rules/10.backend/* + .claude/rules/30.security-db/* + .claude/rules/40.infra/* + .claude/rules/50.sync/*) per the stack pass3 template.\n`;
+        note += `2. **ALSO** create ONE NEW per-domain standard file PER domain listed above at \`claudeos-core/standard/70.domains/{type}/{domain}.md\` (use the exact \`{type}\` shown in the per-domain target paths above). **Expected output: ${batchDomains.length} new file(s) under \`70.domains/{type}/\`** — one per domain. Do NOT inline these into the common standards (00.core/, 10.backend/, etc.); per-domain files are DOMAIN-scoped while common files are TOPIC-based, and they must live at separate paths so per-domain rules can scope to them via \`paths\` glob.\n`;
+        note += `3. **ALSO** create ONE NEW per-domain rule file PER domain listed above at \`.claude/rules/70.domains/{type}/{domain}-rules.md\` (via staging-override path \`claudeos-core/generated/.staged-rules/70.domains/{type}/{domain}-rules.md\`). Each rule file MUST have a \`paths\` frontmatter glob scoped to that domain's source directories so the rule auto-loads only when editing the relevant files.\n`;
+        note += `4. Per-domain file generation is MANDATORY even for ${batchDomains.length}-domain projects (any size below the 15-domain batch threshold). The convention is uniform across all project sizes for consistency: same dirtree shape regardless of scale.\n`;
+        note += `5. Rule B idempotent skip applies — if a per-domain file already exists with substantive content, print \`[SKIP] <path>\` and continue.\n`;
+      } else {
+        // Multi-batch (>15 domains): common files in 3b-core, per-domain in batch stages.
+        note += `1. CLAUDE.md and all common standard/ files (00.core/, 30.security-db/, 40.infra/, etc.) are ALREADY GENERATED by the 3b-core stage. DO NOT regenerate them.\n`;
+        note += `2. Create ONE NEW per-domain standard file PER domain listed above at \`claudeos-core/standard/70.domains/{type}/{domain}.md\` (use the exact \`{type}\` shown in the per-domain target paths above — \`backend\` or \`frontend\`). **Expected output: ${batchDomains.length} new files** — one per domain in this batch. Do NOT inline these into the common files generated by 3b-core; common files are TOPIC-based, per-domain files are DOMAIN-scoped and must live at separate paths so per-domain rules can scope to them via \`paths\` glob.\n`;
+        note += `3. Create ONE NEW per-domain rule file PER domain listed above at \`.claude/rules/70.domains/{type}/{domain}-rules.md\` (via staging-override path \`claudeos-core/generated/.staged-rules/70.domains/{type}/{domain}-rules.md\`). Each rule file MUST have a \`paths\` frontmatter glob scoped to that domain's source directories so the rule auto-loads only when editing the relevant files. Common rules are already generated by 3b-core — do NOT regenerate.\n`;
+        note += `4. DO NOT generate standard/ or rules/ files for domains NOT in the above list — those are/will be processed in other batches.\n`;
+        note += `5. Rule B idempotent skip applies ONLY to files at the per-domain paths shown above for THIS batch's domains — i.e. resume after a crash. **Do NOT use Rule B as justification for skipping the entire batch** because common files at OTHER paths exist (those are out of scope for this batch). If a per-domain target file does NOT exist for a batch domain, you MUST generate it; emitting "0 new files" for the whole batch when domains were assigned to you is a critical Pass 3 failure mode.\n`;
+      }
     } else if (stageKind === "3c") {
-      note += `**Domains in THIS batch**: ${domainList}\n\n`;
-      note += `**Rules for this batch**:\n`;
-      note += `1. ALL guide/ files (01.onboarding, 02.usage, 03.troubleshooting, 04.architecture) are ALREADY GENERATED by the 3c-core stage. DO NOT regenerate.\n`;
-      note += `2. Common skills (00.shared/, orchestrator SKILL.md) are ALREADY GENERATED by 3c-core. DO NOT regenerate.\n`;
-      note += `3. Generate skills/ entries ONLY for the domains listed above — typically under 10.backend-crud/ or 20.frontend-page/ with a per-domain subdirectory.\n`;
-      note += `4. DO NOT generate skills for domains NOT in the above list.\n`;
-      note += `5. Rule B idempotent skip applies: if a skill file already exists, print \`[SKIP] <path>\` and move on.\n`;
+      note += isSingleBatch
+        ? `**Domains in scope (all ${batchDomains.length})**: ${domainList}\n\n`
+        : `**Domains in THIS batch**: ${domainList}\n\n`;
+      note += `**Rules**:\n`;
+      if (isSingleBatch) {
+        // Single-batch (≤15 domains): ALL of 3c — guides + common skills + per-domain skill notes — in one stage.
+        note += `1. Generate ALL guide/ files (01.onboarding, 02.usage, 03.troubleshooting, 04.architecture) per the stack pass3 template.\n`;
+        note += `2. Generate common skills: \`claudeos-core/skills/00.shared/MANIFEST.md\` + the category orchestrator(s) at \`claudeos-core/skills/{category}/01.scaffold-*-feature.md\` + their sub-skill files under \`{category}/scaffold-*-feature/\`.\n`;
+        note += `3. **ALSO** generate \`claudeos-core/skills/{category}/02.domains.md\` orchestrator (sibling to the \`domains/\` sub-folder) — REQUIRED for ALL projects regardless of domain count, mirrors the canonical \`01.scaffold-*-feature.md\` ↔ \`scaffold-*-feature/\` pattern.\n`;
+        note += `4. **ALSO** generate per-domain skill notes at \`claudeos-core/skills/{category}/domains/{domain}.md\` for EACH of the ${batchDomains.length} domain(s). **Expected output: ${batchDomains.length} new file(s) under \`{category}/domains/\`** — content describes domain-specific anti-patterns, dependencies, naming quirks. Per-domain skill generation is MANDATORY even for ${batchDomains.length}-domain projects (the convention is uniform across all project sizes).\n`;
+        note += `5. MUST register every newly created skill file in \`00.shared/MANIFEST.md\` (orchestrator + sub-skills + 02.domains.md + per-domain notes).\n`;
+        note += `6. Rule B idempotent skip applies — if a skill file already exists, print \`[SKIP] <path>\` and move on.\n`;
+      } else {
+        // Multi-batch (>15 domains): guides+common skills in 3c-core, per-domain in batch stages.
+        note += `1. ALL guide/ files (01.onboarding, 02.usage, 03.troubleshooting, 04.architecture) are ALREADY GENERATED by the 3c-core stage. DO NOT regenerate.\n`;
+        note += `2. Common skills (00.shared/, orchestrator SKILL.md) and \`02.domains.md\` orchestrator are ALREADY GENERATED by 3c-core. DO NOT regenerate.\n`;
+        note += `3. Generate per-domain skill notes ONLY for the domains listed above at \`claudeos-core/skills/{category}/domains/{domain}.md\` — typically under 10.backend-crud/ or 20.frontend-page/.\n`;
+        note += `4. DO NOT generate skills for domains NOT in the above list.\n`;
+        note += `5. Rule B idempotent skip applies: if a skill file already exists, print \`[SKIP] <path>\` and move on.\n`;
+      }
     }
 
     if (!isLastBatch) {
@@ -326,7 +446,7 @@ async function runPass3Split(ctx) {
       coreNote += `   - claudeos-core/standard/00.core/*.md (project overview, architecture, conventions)\n`;
       coreNote += `   - claudeos-core/standard/30.security-db/*.md\n`;
       coreNote += `   - claudeos-core/standard/40.infra/*.md\n`;
-      coreNote += `   - claudeos-core/standard/50.verification/*.md\n`;
+      coreNote += `   - claudeos-core/standard/80.verification/*.md\n`;
       coreNote += `   - claudeos-core/standard/90.optional/*.md\n`;
       coreNote += `   - (stack-specific common sections as defined in the pass3 template)\n`;
       coreNote += `3. ALL rules files (via staging-override path .claude/rules → generated/.staged-rules):\n`;
@@ -345,11 +465,13 @@ async function runPass3Split(ctx) {
       coreNote += `   - claudeos-core/guide/04.architecture/*.md\n`;
       coreNote += `2. COMMON skills only:\n`;
       coreNote += `   - claudeos-core/skills/00.shared/*\n`;
-      coreNote += `   - top-level orchestrator SKILL.md files (e.g. \`10.backend-crud/SKILL.md\` without any subfolder)\n\n`;
+      coreNote += `   - top-level orchestrator SKILL.md files (e.g. \`10.backend-crud/SKILL.md\` without any subfolder)\n`;
+      coreNote += `3. **Per-domain orchestrator** (REQUIRED whenever batches are non-empty — i.e. ${totalDomains} domains will be processed): for EACH active skill category that will receive per-domain notes, generate the sibling orchestrator file at \`claudeos-core/skills/{category}/02.domains.md\`. The basename stem (\`domains\`) MUST match the \`domains/\` sub-folder name so \`content-validator\`'s standard orchestrator-stem matching covers all sub-skills directly. The orchestrator's content describes the per-domain notes pattern, lists the ${totalDomains} domains that will be processed, and links to \`00.shared/MANIFEST.md\`. Generate it BEFORE 3c-N batches run so it's already in place when sub-skills land. Numbered \`02.\` because \`01.scaffold-*-feature.md\` already occupies the \`01.\` slot at the category root.\n\n`;
       coreNote += `**What NOT to generate in ${stageKind}-core**:\n`;
       coreNote += `- Per-domain skill sub-directories (e.g. \`10.backend-crud/scaffold-order-feature/\`) — those belong to 3c-1, 3c-2, ... batch stages.\n`;
+      coreNote += `- Per-domain note files (\`10.backend-crud/domains/{domain}.md\`) — those belong to 3c-N batch stages. ${stageKind}-core only generates the parent ORCHESTRATOR (\`02.domains.md\`).\n`;
       coreNote += `- Anything under plan/, database/, mcp-guide/ — those belong to 3d.\n\n`;
-      coreNote += `**Per-domain skills will be generated in subsequent 3c-1, 3c-2, ... batch stages.**\n`;
+      coreNote += `**Per-domain skill notes will be generated in subsequent 3c-1, 3c-2, ... batch stages, under each category's \`domains/\` sub-folder.**\n`;
     }
 
     coreNote += `\nIf you find yourself about to generate a domain-specific file in this stage: STOP. Emit \`[DEFER] <path> — will be generated in 3b-N / 3c-N batch\` and move on.\n\n`;
@@ -539,15 +661,23 @@ async function runPass3Split(ctx) {
       ? `domain batch ${bi + 1}/${batches.length} (${batchDomains.length} domains)`
       : "core files (CLAUDE.md + standard + rules)";
 
-    // Per-batch prompt: inject into the original 3b header the list of domains scoped to this batch.
-    // In multi-batch mode every batch generates "domain-specific files only" (common files handled in 3b-core).
-    const batchScopeNote = isBatched
-      ? buildBatchScopeNote("3b", bi, batches.length, batchDomains)
-      : "";
+    // v2.4.0 — Per-domain scope note ALWAYS injected (single OR multi-batch).
+    //
+    // Previously single-batch projects (≤15 domains) skipped the scope note,
+    // and the stack pass3 template alone didn't mandate per-domain file
+    // generation under `70.domains/{type}/`. As a result, small projects
+    // got common standards but no per-domain files — inconsistent with
+    // multi-batch projects and breaking the uniform-convention contract.
+    //
+    // The note text itself branches on isSingleBatch internally:
+    //   - Single batch: "Generate common files AND per-domain files"
+    //   - Multi batch:  "Per-domain only (common files done in 3b-core)"
+    const batchScopeNote = buildBatchScopeNote("3b", bi, batches.length, batchDomains);
     const baseprompt = buildStagePrompt("pass3b-core-header.md", true);
-    const promptWithScope = batchScopeNote
-      ? baseprompt.replace(/\n## Scope of this step/, `\n${batchScopeNote}\n## Scope of this step`)
-      : baseprompt;
+    const promptWithScope = baseprompt.replace(
+      /\n## Scope of this step/,
+      `\n${batchScopeNote}\n## Scope of this step`
+    );
 
     await runStage(stageId, label, promptWithScope, {
       expectsStagedRules: true,
@@ -621,13 +751,16 @@ async function runPass3Split(ctx) {
       ? `domain skills batch ${bi + 1}/${batches.length} (${batchDomains.length} domains)`
       : "skills and guides";
 
-    const batchScopeNote = isBatched
-      ? buildBatchScopeNote("3c", bi, batches.length, batchDomains)
-      : "";
+    // v2.4.0 — Per-domain skill scope note ALWAYS injected (single OR multi-batch).
+    // Same rationale as Pass 3b: small projects need per-domain skill notes
+    // (`{category}/domains/{domain}.md`) and the `02.domains.md` orchestrator
+    // for uniform layout across all project sizes.
+    const batchScopeNote = buildBatchScopeNote("3c", bi, batches.length, batchDomains);
     const baseprompt = buildStagePrompt("pass3c-skills-guide-header.md", true);
-    const promptWithScope = batchScopeNote
-      ? baseprompt.replace(/\n## Scope of this step/, `\n${batchScopeNote}\n## Scope of this step`)
-      : baseprompt;
+    const promptWithScope = baseprompt.replace(
+      /\n## Scope of this step/,
+      `\n${batchScopeNote}\n## Scope of this step`
+    );
 
     await runStage(stageId, label, promptWithScope, {
       expectsStagedRules: true, // skills occasionally include rule files
@@ -701,15 +834,22 @@ async function runPass3Split(ctx) {
   log(`    🎉 Pass 3 split complete: ${completedGroups.length}/${totalStages} stages successful`);
 }
 
-async function cmdInit(parsedArgs) {
-  const totalStart = Date.now();
-  // Tracks whether we just wiped generated state via --force or "fresh" resume
-  // mode. Used by the Pass 3 backfill guard below: fresh/force explicitly
-  // means "regenerate from scratch", so a leftover CLAUDE.md from a prior run
-  // must NOT cause Pass 3 to be skipped via the v1.7.x migration backfill.
-  let wasFreshClean = false;
-
-  // ─── Prerequisites check ───────────────────────────────────
+// ═══════════════════════════════════════════════════════════════════
+// cmdInit stage helpers
+// ═══════════════════════════════════════════════════════════════════
+// The original cmdInit was 970 lines with 77 if-statements and 17 try-blocks
+// in a single function. Below it is decomposed into one helper per pipeline
+// phase. Each helper owns a self-contained step with clear inputs/outputs.
+//
+// Shared state passed across helpers:
+//   - { lang, stepTimes, completedSteps (via ref), progressBar, wasFreshClean }
+// Helpers that advance the outer progress bar return a `stepsDelta` value
+// that cmdInit adds to `completedSteps` locally. This preserves the literal
+// `completedSteps++` text at the top-level orchestrator, which several
+// source-parity tests rely on for stale-check region detection.
+
+// ─── Stage 1: Prerequisites check ──────────────────────────────────
+function checkPrerequisites() {
   const hasProjectMarker = [".git", "package.json", "build.gradle", "build.gradle.kts", "pom.xml", "pyproject.toml", "requirements.txt"].some(
     m => fs.existsSync(path.join(PROJECT_ROOT, m))
   );
@@ -734,8 +874,10 @@ async function cmdInit(parsedArgs) {
   if (!claudeAuth) {
     throw new InitError("Claude Code may not be authenticated.\n  Run: claude (and complete authentication)\n  Then retry: npx claudeos-core init");
   }
+}
 
-  // ─── Language selection (required) ────────────────────────────
+// ─── Stage 2: Resolve output language ─────────────────────────────
+async function resolveLanguage(parsedArgs) {
   let lang = parsedArgs.lang;
   if (!lang) {
     lang = await selectLangInteractive();
@@ -765,114 +907,109 @@ async function cmdInit(parsedArgs) {
   }
 
   process.env.CLAUDEOS_LANG = lang;
+  return lang;
+}
 
-  // ─── Resume / Fresh selection ────────────────────────────
-  if (fs.existsSync(GENERATED_DIR)) {
-    const existingPass1 = fs.readdirSync(GENERATED_DIR).filter(f => f.startsWith("pass1-") && f.endsWith(".json"));
-    const pass2Exists = fileExists(path.join(GENERATED_DIR, "pass2-merged.json"));
-
-    if (existingPass1.length > 0 || pass2Exists) {
-      if (parsedArgs.force) {
-        // --force: clean all generated files for truly fresh start
-        const genFiles = fs.readdirSync(GENERATED_DIR).filter(f => f.endsWith(".json") || f.endsWith(".md"));
-        for (const f of genFiles) fs.unlinkSync(path.join(GENERATED_DIR, f));
-        // Also clean any leftover .staged-rules/ from a prior crashed run
-        // (only .json/.md are unlinked above; directories aren't touched).
-        const stagedDir = path.join(GENERATED_DIR, ".staged-rules");
-        if (fileExists(stagedDir)) fs.rmSync(stagedDir, { recursive: true, force: true });
-        // Also wipe .claude/rules/ so Guard 2 (zero-rules detection) can't
-        // false-negative on stale rules from a previous run when the fresh
-        // Pass 3 run fails silently (e.g. Claude ignores staging-override).
-        // Step [2] recreates the subdirs from scratch. Any manual edits the
-        // user made to rule files are lost — acceptable under --force
-        // ("truly fresh start").
-        const rulesDir = path.join(PROJECT_ROOT, ".claude/rules");
-        if (fileExists(rulesDir)) fs.rmSync(rulesDir, { recursive: true, force: true });
-        wasFreshClean = true;
-        log("  🔄 Previous results deleted (--force)\n");
-      } else {
-        // v2.2.0 upgrade detection: if project was generated with older claudeos-core
-        // (pre-2.2.0), default "resume" mode will skip regeneration of existing files
-        // per Rule B idempotency, meaning v2.2.0 structural improvements will NOT be
-        // picked up. Detect this case by checking CLAUDE.md for v2.2.0 markers.
-        const claudeMd = path.join(PROJECT_ROOT, "CLAUDE.md");
-        if (fileExists(claudeMd)) {
-          try {
-            const content = fs.readFileSync(claudeMd, "utf-8");
-            // v2.2.0 scaffold enforces EXACTLY 8 top-level `##` sections.
-            // Pre-v2.2.0 CLAUDE.md files typically carry 9+ sections (extra
-            // "Rules Summary" / "Common Rules" / "Required to Observe"
-            // blocks that v2.2.0 forbids). Counting `^## ` headings is a
-            // language-independent heuristic that works across all 10
-            // supported output languages. False positive (an existing
-            // 8-section pre-v2.2.0 CLAUDE.md) is acceptable — the user
-            // simply won't see the upgrade warning and can still run
-            // `--force` manually.
-            const sectionCount = (content.match(/^## /gm) || []).length;
-            const hasV220Section8 = sectionCount === 8;
-            if (!hasV220Section8) {
-              log("\n  ⚠️  v2.2.0 upgrade detected");
-              log("  ─────────────────────────");
-              log("  Your existing CLAUDE.md was generated with an older claudeos-core version.");
-              log("  v2.2.0 introduces structural changes that the default 'resume' mode");
-              log("  CANNOT apply because existing files are preserved under Rule B (idempotency).");
-              log("");
-              log("  To fully adopt v2.2.0, choose one of:");
-              log("    1. Rerun with --force:   npx claudeos-core init --force");
-              log("       (overwrites generated files; your memory/ content is preserved)");
-              log("    2. Choose 'fresh' below  (equivalent to --force)");
-              log("");
-              log("  See CHANGELOG.md Migration section for full details.\n");
-            }
-          } catch (_) { /* Read error is non-fatal; proceed to resume prompt */ }
-        }
+// ─── Stage 3: Resume/Fresh selection ──────────────────────────────
+// Returns { wasFreshClean: boolean } — the caller uses this to gate the
+// v1.7.x migration backfill in dispatchPass3.
+async function applyResumeMode(parsedArgs, lang) {
+  let wasFreshClean = false;
 
-        const status = { pass1Done: existingPass1.length, pass2Done: pass2Exists };
-        const mode = await selectResumeMode(lang, status);
-        if (!mode) throw new InitError("Cancelled.");
-        if (mode === "fresh") {
-          for (const f of existingPass1) fs.unlinkSync(path.join(GENERATED_DIR, f));
-          if (pass2Exists) fs.unlinkSync(path.join(GENERATED_DIR, "pass2-merged.json"));
-          // Also reset pass 3 & pass 4 markers so they re-run
-          const pass3M = path.join(GENERATED_DIR, "pass3-complete.json");
-          const pass4M = path.join(GENERATED_DIR, "pass4-memory.json");
-          if (fileExists(pass3M)) fs.unlinkSync(pass3M);
-          if (fileExists(pass4M)) fs.unlinkSync(pass4M);
-          // Clean .staged-rules/ leftover from a prior crashed run (same reason as --force branch).
-          const stagedDir = path.join(GENERATED_DIR, ".staged-rules");
-          if (fileExists(stagedDir)) fs.rmSync(stagedDir, { recursive: true, force: true });
-          // Wipe .claude/rules/ for the same Guard 2 false-negative reason as
-          // the --force branch. Step [2] recreates the subdirs; any manual
-          // edits are lost — acceptable under an explicit "fresh" choice.
-          const rulesDir = path.join(PROJECT_ROOT, ".claude/rules");
-          if (fileExists(rulesDir)) fs.rmSync(rulesDir, { recursive: true, force: true });
-          wasFreshClean = true;
-        } else if (mode === "continue" && existingPass1.length === 0 && pass2Exists) {
-          // pass2 exists but no pass1 → pass2 is stale, force re-run
-          fs.unlinkSync(path.join(GENERATED_DIR, "pass2-merged.json"));
-          log("    ⚠️  pass2-merged.json deleted (no pass1 files to continue from)");
-        }
-      }
-    }
+  if (!fs.existsSync(GENERATED_DIR)) return { wasFreshClean };
+
+  const existingPass1 = fs.readdirSync(GENERATED_DIR).filter(f => f.startsWith("pass1-") && f.endsWith(".json"));
+  const pass2Exists = fileExists(path.join(GENERATED_DIR, "pass2-merged.json"));
+  if (existingPass1.length === 0 && !pass2Exists) return { wasFreshClean };
+
+  if (parsedArgs.force) {
+    // --force: clean all generated files for truly fresh start
+    const genFiles = fs.readdirSync(GENERATED_DIR).filter(f => f.endsWith(".json") || f.endsWith(".md"));
+    for (const f of genFiles) fs.unlinkSync(path.join(GENERATED_DIR, f));
+    // Also clean any leftover .staged-rules/ from a prior crashed run
+    // (only .json/.md are unlinked above; directories aren't touched).
+    const stagedDir = path.join(GENERATED_DIR, ".staged-rules");
+    if (fileExists(stagedDir)) fs.rmSync(stagedDir, { recursive: true, force: true });
+    // Also wipe .claude/rules/ so Guard 2 (zero-rules detection) can't
+    // false-negative on stale rules from a previous run when the fresh
+    // Pass 3 run fails silently (e.g. Claude ignores staging-override).
+    // Step [2] recreates the subdirs from scratch. Any manual edits the
+    // user made to rule files are lost — acceptable under --force
+    // ("truly fresh start").
+    const rulesDir = path.join(PROJECT_ROOT, ".claude/rules");
+    if (fileExists(rulesDir)) fs.rmSync(rulesDir, { recursive: true, force: true });
+    wasFreshClean = true;
+    log("  🔄 Previous results deleted (--force)\n");
+    return { wasFreshClean };
   }
 
-  log("");
-  log("╔════════════════════════════════════════════════════╗");
-  log("║       ClaudeOS-Core — Bootstrap (4-Pass)          ║");
-  log("╚════════════════════════════════════════════════════╝");
-  log(`    Project root: ${PROJECT_ROOT}`);
-  log(`    Language:     ${SUPPORTED_LANGS[lang]} (${lang})`);
-  log("");
+  // v2.2.0 upgrade detection: if project was generated with older claudeos-core
+  // (pre-2.2.0), default "resume" mode will skip regeneration of existing files
+  // per Rule B idempotency, meaning v2.2.0 structural improvements will NOT be
+  // picked up. Detect this case by checking CLAUDE.md for v2.2.0 markers.
+  const claudeMd = path.join(PROJECT_ROOT, "CLAUDE.md");
+  if (fileExists(claudeMd)) {
+    try {
+      const content = fs.readFileSync(claudeMd, "utf-8");
+      // v2.2.0 scaffold enforces EXACTLY 8 top-level `##` sections.
+      // Pre-v2.2.0 CLAUDE.md files typically carry 9+ sections (extra
+      // "Rules Summary" / "Common Rules" / "Required to Observe"
+      // blocks that v2.2.0 forbids). Counting `^## ` headings is a
+      // language-independent heuristic that works across all 10
+      // supported output languages. False positive (an existing
+      // 8-section pre-v2.2.0 CLAUDE.md) is acceptable — the user
+      // simply won't see the upgrade warning and can still run
+      // `--force` manually.
+      const sectionCount = (content.match(/^## /gm) || []).length;
+      const hasV220Section8 = sectionCount === 8;
+      if (!hasV220Section8) {
+        log("\n  ⚠️  v2.2.0 upgrade detected");
+        log("  ─────────────────────────");
+        log("  Your existing CLAUDE.md was generated with an older claudeos-core version.");
+        log("  v2.2.0 introduces structural changes that the default 'resume' mode");
+        log("  CANNOT apply because existing files are preserved under Rule B (idempotency).");
+        log("");
+        log("  To fully adopt v2.2.0, choose one of:");
+        log("    1. Rerun with --force:   npx claudeos-core init --force");
+        log("       (overwrites generated files; your memory/ content is preserved)");
+        log("    2. Choose 'fresh' below  (equivalent to --force)");
+        log("");
+        log("  See CHANGELOG.md Migration section for full details.\n");
+      }
+    } catch (_) { /* Read error is non-fatal; proceed to resume prompt */ }
+  }
 
-  // ─── [1] Install dependencies ────────────────────────────────
-  header("[1] Installing dependencies...");
-  if (!fileExists(path.join(TOOLS_DIR, "node_modules"))) {
-    run("npm install --silent", { cwd: TOOLS_DIR });
+  const status = { pass1Done: existingPass1.length, pass2Done: pass2Exists };
+  const mode = await selectResumeMode(lang, status);
+  if (!mode) throw new InitError("Cancelled.");
+  if (mode === "fresh") {
+    for (const f of existingPass1) fs.unlinkSync(path.join(GENERATED_DIR, f));
+    if (pass2Exists) fs.unlinkSync(path.join(GENERATED_DIR, "pass2-merged.json"));
+    // Also reset pass 3 & pass 4 markers so they re-run
+    const pass3M = path.join(GENERATED_DIR, "pass3-complete.json");
+    const pass4M = path.join(GENERATED_DIR, "pass4-memory.json");
+    if (fileExists(pass3M)) fs.unlinkSync(pass3M);
+    if (fileExists(pass4M)) fs.unlinkSync(pass4M);
+    // Clean .staged-rules/ leftover from a prior crashed run (same reason as --force branch).
+    const stagedDir = path.join(GENERATED_DIR, ".staged-rules");
+    if (fileExists(stagedDir)) fs.rmSync(stagedDir, { recursive: true, force: true });
+    // Wipe .claude/rules/ for the same Guard 2 false-negative reason as
+    // the --force branch. Step [2] recreates the subdirs; any manual
+    // edits are lost — acceptable under an explicit "fresh" choice.
+    const rulesDir = path.join(PROJECT_ROOT, ".claude/rules");
+    if (fileExists(rulesDir)) fs.rmSync(rulesDir, { recursive: true, force: true });
+    wasFreshClean = true;
+  } else if (mode === "continue" && existingPass1.length === 0 && pass2Exists) {
+    // pass2 exists but no pass1 → pass2 is stale, force re-run
+    fs.unlinkSync(path.join(GENERATED_DIR, "pass2-merged.json"));
+    log("    ⚠️  pass2-merged.json deleted (no pass1 files to continue from)");
   }
-  log("    ✅ Done\n");
 
-  // ─── [2] Create directory structure ─────────────────────────
-  header("[2] Creating directory structure...");
+  return { wasFreshClean };
+}
+
+// ─── Stage 4: Create directory structure ──────────────────────────
+function ensureDirectories() {
   const dirs = [
     ".claude/rules/00.core",
     ".claude/rules/10.backend",
@@ -882,15 +1019,26 @@ async function cmdInit(parsedArgs) {
     ".claude/rules/50.sync",
     "claudeos-core/generated",
     "claudeos-core/standard/00.core",
-    "claudeos-core/standard/10.backend-api",
-    "claudeos-core/standard/20.frontend-ui",
+    "claudeos-core/standard/10.backend",
+    "claudeos-core/standard/20.frontend",
     "claudeos-core/standard/30.security-db",
     "claudeos-core/standard/40.infra",
-    "claudeos-core/standard/50.verification",
+    "claudeos-core/standard/80.verification",
     "claudeos-core/standard/90.optional",
     "claudeos-core/skills/00.shared",
     "claudeos-core/skills/10.backend-crud/scaffold-crud-feature",
+    // v2.4.0 — `domains/` sub-folder under each per-domain skill category.
+    // Pre-created so Pass 3c-N has a stable destination for per-domain
+    // skill notes (`{category}/domains/{domain}.md`) and so the convention
+    // is visible in the post-init dirtree alongside `scaffold-*-feature/`.
+    // The `02.domains.md` orchestrator (sibling at category root) is
+    // generated by Pass 3c-core, not pre-created — the file content is
+    // project-specific. Empty pre-created `domains/` folders are
+    // harmless on filesystems that allow them and self-document the
+    // convention.
+    "claudeos-core/skills/10.backend-crud/domains",
     "claudeos-core/skills/20.frontend-page/scaffold-page-feature",
+    "claudeos-core/skills/20.frontend-page/domains",
     "claudeos-core/skills/50.testing",
     "claudeos-core/skills/90.experimental",
     "claudeos-core/guide/01.onboarding",
@@ -901,20 +1049,36 @@ async function cmdInit(parsedArgs) {
     "claudeos-core/mcp-guide",
     "claudeos-core/memory",
     ".claude/rules/60.memory",
+    // v2.4.0 — 80.verification rules (mirror of standard/80.verification).
+    // Pre-created to give Pass 3 LLM a stable destination for verification
+    // rules (testing strategy, build verification reminders that auto-load
+    // when editing test files / build configs). Without this, prior runs
+    // would create them at the LEGACY 50.verification path (cross-namespace
+    // contamination from standard/50.verification), now corrected to the
+    // unified 80.* numbering.
+    ".claude/rules/80.verification",
+    // v2.4.0 — 70.domains/ canonical per-domain folder, ALWAYS typed.
+    //   - PLURAL folder (collection of N per-domain files)
+    //   - 70 number to avoid 60.* collision with 60.memory
+    //   - ALWAYS uses `{type}/` sub-folder (`backend/` or `frontend/`)
+    //     regardless of single/multi-stack. Uniform convention prevents
+    //     migration when a single-stack project later adds the other
+    //     stack, and gives validators a single pattern to recognize.
+    //   - Pre-created so Pass 3 LLM has a stable destination for
+    //     `claudeos-core/standard/70.domains/{type}/{domain}.md` and
+    //     `.claude/rules/70.domains/{type}/{domain}-rules.md` writes.
+    "claudeos-core/standard/70.domains/backend",
+    "claudeos-core/standard/70.domains/frontend",
+    ".claude/rules/70.domains/backend",
+    ".claude/rules/70.domains/frontend",
   ];
   for (const d of dirs) {
     ensureDir(path.join(PROJECT_ROOT, d));
   }
-  log("    ✅ Done\n");
-
-  // ─── [3] Run plan-installer ─────────────────────────
-  header("[3] Analyzing project (plan-installer)...");
-  run(`node "${path.join(TOOLS_DIR, "plan-installer/index.js")}"`);
-  log("");
-
-  // ─── [4] Pass 1: Deep analysis per domain group ──────────────────
-  header("[4] Pass 1 — Deep analysis per domain group...");
+}
 
+// ─── Stage 5: Load & validate domain-groups.json ──────────────────
+function loadDomainGroups() {
   let domainGroups;
   try {
     domainGroups = JSON.parse(
@@ -927,8 +1091,15 @@ async function cmdInit(parsedArgs) {
   if (!totalGroups || typeof totalGroups !== "number" || totalGroups < 1) {
     throw new InitError(`domain-groups.json has invalid totalGroups: ${totalGroups}\n    Re-run plan-installer or check claudeos-core/generated/`);
   }
+  if (!domainGroups.groups || totalGroups !== domainGroups.groups.length) {
+    throw new InitError(`domain-groups.json is malformed: expected ${totalGroups} groups, found ${domainGroups.groups ? domainGroups.groups.length : 0}`);
+  }
+  return { domainGroups, totalGroups };
+}
 
-  // Load pass1 prompts by type
+// Loads the per-type pass1 prompt templates. Falls back to the single-stack
+// pass1-prompt.md for backward compatibility with older plan-installer output.
+function loadPass1Prompts() {
   const pass1Prompts = {};
   for (const type of ["backend", "frontend"]) {
     const promptFile = path.join(GENERATED_DIR, `pass1-${type}-prompt.md`);
@@ -936,23 +1107,17 @@ async function cmdInit(parsedArgs) {
       pass1Prompts[type] = readFile(promptFile);
     }
   }
-  // Single-stack backward compatibility
   if (Object.keys(pass1Prompts).length === 0) {
     const fallback = path.join(GENERATED_DIR, "pass1-prompt.md");
     if (fileExists(fallback)) pass1Prompts["backend"] = readFile(fallback);
   }
+  return pass1Prompts;
+}
 
-  if (!domainGroups.groups || totalGroups !== domainGroups.groups.length) {
-    throw new InitError(`domain-groups.json is malformed: expected ${totalGroups} groups, found ${domainGroups.groups ? domainGroups.groups.length : 0}`);
-  }
-
-  // Progress tracking: Pass 1 (N groups) + Pass 2 + Pass 3 + Pass 4 = totalSteps
-  const totalSteps = totalGroups + 3;
-  let completedSteps = 0;
-  const stepTimes = [];
-  const passStart = Date.now();
-
-  function progressBar(step, label) {
+// Creates the progressBar closure. Extracted from cmdInit so the bar
+// formatting is testable in isolation if needed.
+function makeProgressBar(totalSteps, passStart, stepTimes) {
+  return function progressBar(step, label) {
     const pct = Math.round((step / totalSteps) * 100);
     const elapsed = Date.now() - passStart;
     let eta = "";
@@ -964,7 +1129,14 @@ async function cmdInit(parsedArgs) {
     const filled = Math.round(pct / 5);
     const bar = "█".repeat(filled) + "░".repeat(20 - filled);
     log(`    [${bar}] ${pct}% (${step}/${totalSteps}) ${formatElapsed(elapsed)}${eta} — ${label}`);
-  }
+  };
+}
+
+// ─── Stage 6: Pass 1 — Deep analysis per domain group ─────────────
+// Returns the number of steps to add to the outer completedSteps counter.
+async function runPass1Loop(opts) {
+  const { domainGroups, totalGroups, pass1Prompts, progressBar, stepTimes, startingStep } = opts;
+  let step = startingStep;
 
   for (let i = 1; i <= totalGroups; i++) {
     const group = domainGroups.groups[i - 1];
@@ -984,7 +1156,7 @@ async function cmdInit(parsedArgs) {
         const existing = JSON.parse(readFile(pass1Json));
         if (existing && existing.analysisPerDomain) {
           log(`    ⏭️  pass1-${i}.json already exists, skipping`);
-          completedSteps++;
+          step++;
           continue;
         }
       } catch (_e) { /* malformed — re-run */ }
@@ -1024,13 +1196,17 @@ async function cmdInit(parsedArgs) {
       throw new InitError(`pass1-${i}.json was not created. Claude may have run but not produced expected output.\n    Ensure the prompt instructs Claude to write to claudeos-core/generated/pass1-${i}.json`);
     }
 
-    completedSteps++;
-    progressBar(completedSteps, `pass1-${i}.json created (${formatElapsed(elapsed1)})`);
+    step++;
+    progressBar(step, `pass1-${i}.json created (${formatElapsed(elapsed1)})`);
   }
   log("");
+  return step - startingStep;
+}
 
-  // ─── [5] Pass 2: Merge analysis results ──────────────────────
-  header("[5] Pass 2 — Merging analysis results...");
+// ─── Stage 7: Pass 2 — Merge analysis results ─────────────────────
+// Returns the number of steps to add to the outer completedSteps counter (0 or 1).
+async function runPass2(opts) {
+  const { progressBar, stepTimes, nextStep } = opts;
 
   const pass2Json = path.join(GENERATED_DIR, "pass2-merged.json");
 
@@ -1057,46 +1233,47 @@ async function cmdInit(parsedArgs) {
 
   if (pass2IsValid) {
     log("    ⏭️  pass2-merged.json already exists, skipping");
-    completedSteps++;
-  } else {
-    const pass2PromptFile = path.join(GENERATED_DIR, "pass2-prompt.md");
-    if (!fileExists(pass2PromptFile)) {
-      throw new InitError("pass2-prompt.md not found. Re-run plan-installer.");
-    }
-    let prompt = injectProjectRoot(readFile(pass2PromptFile));
+    return 1;
+  }
 
-    const t2 = Date.now();
-    const ticker2 = makePassTicker("Pass 2", t2);
-    const ok = await runClaudePromptAsync(prompt, {
-      onTick: ticker2.onTick,
-      tickMs: ticker2.tickMs,
-    });
-    ticker2.clearLine();
-    const elapsed2 = Date.now() - t2;
-    stepTimes.push(elapsed2);
+  const pass2PromptFile = path.join(GENERATED_DIR, "pass2-prompt.md");
+  if (!fileExists(pass2PromptFile)) {
+    throw new InitError("pass2-prompt.md not found. Re-run plan-installer.");
+  }
+  let prompt = injectProjectRoot(readFile(pass2PromptFile));
 
-    if (!ok) {
-      throw new InitError("Pass 2 failed. Check the claude error output above.\n    If this persists, try: npx claudeos-core init --force");
-    }
+  const t2 = Date.now();
+  const ticker2 = makePassTicker("Pass 2", t2);
+  const ok = await runClaudePromptAsync(prompt, {
+    onTick: ticker2.onTick,
+    tickMs: ticker2.tickMs,
+  });
+  ticker2.clearLine();
+  const elapsed2 = Date.now() - t2;
+  stepTimes.push(elapsed2);
 
-    if (!fileExists(pass2Json)) {
-      throw new InitError("pass2-merged.json was not created. Claude may have run but not produced expected output.");
-    }
+  if (!ok) {
+    throw new InitError("Pass 2 failed. Check the claude error output above.\n    If this persists, try: npx claudeos-core init --force");
+  }
 
-    completedSteps++;
-    progressBar(completedSteps, `pass2-merged.json created (${formatElapsed(elapsed2)})`);
+  if (!fileExists(pass2Json)) {
+    throw new InitError("pass2-merged.json was not created. Claude may have run but not produced expected output.");
   }
-  log("");
 
-  // ─── [5.5] v2.1: Build pass3-context.json (slim summary for Pass 3) ──
-  // Writes a small (<5 KB) structured summary derived from project-analysis.json
-  // plus pass2-merged.json signals (size, top-level keys). Pass 3 prompts
-  // reference this INSTEAD OF re-reading pass2-merged.json repeatedly, which
-  // was the primary cause of `Prompt is too long` failures on large projects.
-  //
-  // Silent-on-failure: if pass3-context-builder returns null (e.g.
-  // project-analysis.json missing), we skip writing and let Pass 3 fall back
-  // to the pre-v2.1 behavior of reading pass2-merged.json directly.
+  progressBar(nextStep, `pass2-merged.json created (${formatElapsed(elapsed2)})`);
+  return 1;
+}
+
+// ─── Stage 8: Build pass3-context.json (v2.1) ─────────────────────
+// Writes a small (<5 KB) structured summary derived from project-analysis.json
+// plus pass2-merged.json signals (size, top-level keys). Pass 3 prompts
+// reference this INSTEAD OF re-reading pass2-merged.json repeatedly, which
+// was the primary cause of `Prompt is too long` failures on large projects.
+//
+// Silent-on-failure: if pass3-context-builder returns null (e.g.
+// project-analysis.json missing), we skip writing and let Pass 3 fall back
+// to the pre-v2.1 behavior of reading pass2-merged.json directly.
+function buildPass3ContextJson() {
   try {
     const { buildPass3Context } = require("../../plan-installer/pass3-context-builder");
     const pass3Ctx = buildPass3Context(GENERATED_DIR);
@@ -1116,11 +1293,15 @@ async function cmdInit(parsedArgs) {
   } catch (e) {
     log(`    ⚠️  pass3-context.json build skipped: ${e.message} (Pass 3 will fall back to pass2-merged.json)`);
   }
-  log("");
-
-  // ─── [6] Pass 3: Generate + verify ─────────────────────────
-  header("[6] Pass 3 — Generating all files...");
+}
 
+// ─── Stage 9a: Pass 3 marker pre-processing ───────────────────────
+// Handles v1.7.x migration backfill + stale-marker detection (guide/outputs).
+// The stale region below MUST include dropStalePass3Marker, EXPECTED_GUIDE_FILES,
+// and findMissingOutputs — tested for by tests/pass3-marker.test.js source
+// parity. The `completedSteps++` sentinel used by that region's regex lives
+// in cmdInit directly, after dispatchPass3 returns.
+function handlePass3StaleMarker(wasFreshClean) {
   const pass3Marker = path.join(GENERATED_DIR, "pass3-complete.json");
   const claudeMdPath = path.join(PROJECT_ROOT, "CLAUDE.md");
 
@@ -1224,6 +1405,17 @@ async function cmdInit(parsedArgs) {
       }
     }
   }
+}
+
+// ─── Stage 9b: Pass 3 dispatch (decide + run) ─────────────────────
+// Returns { ran: boolean } so the caller can increment completedSteps
+// with the literal "completedSteps++" token that the stale-region
+// source-parity test regex requires.
+async function dispatchPass3(opts) {
+  const { wasFreshClean, lang, stepTimes, progressBar, nextStep } = opts;
+
+  const pass3Marker = path.join(GENERATED_DIR, "pass3-complete.json");
+  const claudeMdPath = path.join(PROJECT_ROOT, "CLAUDE.md");
 
   // Pass 3 split mode resolution.
   //
@@ -1243,8 +1435,8 @@ async function cmdInit(parsedArgs) {
   try {
     const ctxPath = path.join(GENERATED_DIR, "pass3-context.json");
     if (fileExists(ctxPath)) {
-      const ctx = JSON.parse(readFile(ctxPath));
-      const rec = ctx && ctx.splitRecommendation;
+      const pctx = JSON.parse(readFile(ctxPath));
+      const rec = pctx && pctx.splitRecommendation;
       if (rec) {
         log(`       • estimated ${rec.estimatedFileCount} files from ${rec.totalDomains} domains`);
       }
@@ -1298,17 +1490,20 @@ async function cmdInit(parsedArgs) {
       EXPECTED_GUIDE_FILES, findMissingOutputs,
       lang, stepTimes,
     });
-    completedSteps++;
-    progressBar(completedSteps, `Pass 3 complete (split mode)`);
+    progressBar(nextStep, `Pass 3 complete (split mode)`);
     log("");
-  } else {
-    log("    ⏭️  pass3-complete.json already complete, skipping");
-    completedSteps++;
+    return { ran: true };
   }
-  log("");
 
-  // ─── [7] Pass 4: L4 memory scaffolding ────────────
-  header("[7] Pass 4 — Memory scaffolding...");
+  log("    ⏭️  pass3-complete.json already complete, skipping");
+  return { ran: false };
+}
+
+// ─── Stage 10: Pass 4 — L4 memory scaffolding ─────────────────────
+// Returns 1 unconditionally (Pass 4 always counts as a completed step,
+// whether skip / static fallback / Claude-driven).
+async function runPass4(opts) {
+  const { lang, stepTimes, progressBar, nextStep } = opts;
 
   const pass4Marker = path.join(GENERATED_DIR, "pass4-memory.json");
   const pass4PromptFile = path.join(GENERATED_DIR, "pass4-prompt.md");
@@ -1542,13 +1737,12 @@ async function cmdInit(parsedArgs) {
   // when we actually did real work, so ETA for future steps stays meaningful.
   const pass4Elapsed = Date.now() - pass4Start;
   if (pass4Elapsed > 500) stepTimes.push(pass4Elapsed);
-  completedSteps++;
-  progressBar(completedSteps, pass4Label);
-  log("");
-
-  // ─── [8] Run verification tools ───────────────────────────────
-  header("[8] Running verification tools...");
+  progressBar(nextStep, pass4Label);
+  return 1;
+}
 
+// ─── Stage 11: Run external verification tools ────────────────────
+function runVerificationTools() {
   const verifyTools = [
     { name: "manifest-generator", script: path.join(TOOLS_DIR, "manifest-generator/index.js") },
     { name: "health-checker",     script: path.join(TOOLS_DIR, "health-checker/index.js") },
@@ -1564,21 +1758,12 @@ async function cmdInit(parsedArgs) {
       log(`    ⚠️  ${t.name} reported issues (non-fatal)`);
     }
   }
-  log("");
-
-  // ─── Complete ─────────────────────────────────────────────
-  const totalFiles = countFiles();
-  const pass1Files = countPass1Files();
+}
 
-  // ─── Structural lint (v2.3.0+) ────────────────────────────
-  // Run the language-invariant CLAUDE.md validator after all passes
-  // complete. This catches the §9 L4-memory re-declaration anti-pattern
-  // and other structural drift the scaffold + prompt-level instructions
-  // alone cannot reliably prevent across 10 output languages.
-  //
-  // Failures do NOT abort the run — the generated content is still
-  // useful and the user can either re-run with --force or hand-edit the
-  // flagged sections. The report is purely informational here.
+// ─── Stage 12: Structural lint (v2.3.0+) ──────────────────────────
+// Run the language-invariant CLAUDE.md validator after all passes complete.
+// Failures do NOT abort the run — informational only.
+function runLint() {
   try {
     const { validate } = require("../../claude-md-validator");
     const { formatSummaryLine } = require("../../claude-md-validator/reporter");
@@ -1602,25 +1787,31 @@ async function cmdInit(parsedArgs) {
     log(`    ⚠️  Lint step skipped: ${e.message || e}`);
     log("");
   }
+}
 
-  // ─── Content integrity (Guard 4 — v2.3.0+) ─────────────────
-  // Runs content-validator's path-claim + MANIFEST drift checks as a
-  // non-blocking final step after all passes. We deliberately do NOT
-  // throw or unset pass3-complete.json here:
-  //   - Re-running Pass 3 is not guaranteed to fix LLM hallucinations
-  //     (the same fact JSON may trigger the same mis-inference again),
-  //     so a throw could deadlock the user in an `init --force` loop.
-  //   - The report + the non-zero exit of `npx claudeos-core lint`
-  //     already surface the issues. CI pipelines catch them via exit
-  //     code; local users see them inline here.
-  // When real drift is detected, we print a pointer to the standalone
-  // CLI so the user can re-run selectively without repeating init.
+// ─── Stage 13: Content integrity (Guard 4 — v2.3.0+) ──────────────
+// Runs content-validator's path-claim + MANIFEST drift checks as a
+// non-blocking final step after all passes. These are *advisories*, not
+// generation failures — the documents are usable as-is, the advisories
+// just flag spots where an LLM may have guessed at a filename or a
+// skill registration may have drifted. We deliberately do NOT throw or
+// unset pass3-complete.json here:
+//   - Re-running Pass 3 is not guaranteed to fix LLM hallucinations
+//     (the same fact JSON may trigger the same mis-inference again),
+//     so a throw could deadlock the user in an `init --force` loop.
+//   - content-validator's non-zero exit is preserved so that
+//     `npx claudeos-core health` (and any CI wired to it) still treats
+//     advisories as a real gate. `init` just presents them with softer
+//     UX because by the time `init` finishes, the user's docs are
+//     already on disk and fully usable.
+function runContentValidator() {
   try {
     const cvPath = path.join(__dirname, "..", "..", "content-validator", "index.js");
     if (fileExists(cvPath)) {
       log("  [Content] Checking path-claims and MANIFEST consistency...");
-      // Run in a child process so its process.exit(1) on errors does
-      // not terminate init. We only surface the exit code as a warning.
+      // Run in a child process so its process.exit(1) on advisories does
+      // not terminate init. The exit code is informational for us — we
+      // still surface the content as advisories regardless.
       const { spawnSync } = require("child_process");
       const result = spawnSync(process.execPath, [cvPath], {
         cwd: PROJECT_ROOT,
@@ -1634,11 +1825,11 @@ async function cmdInit(parsedArgs) {
       log(summary.split("\n").map((l) => "    " + l).join("\n"));
       if (result.status !== 0) {
         log("");
-        log("    ℹ️  Content drift detected. This does NOT invalidate the");
-        log("       generated documents, but indicates stale path references");
-        log("       or MANIFEST ↔ CLAUDE.md mismatch. Details:");
-        log("         - stale-report.json (full error list)");
-        log("         - Re-run: node content-validator/index.js");
+        log("    ℹ️  Content advisories detected — these are quality notes,");
+        log("       NOT generation failures. Your generated docs are ready");
+        log("       to use as-is. Review when convenient:");
+        log("         - stale-report.json (full advisory list)");
+        log("         - npx claudeos-core health (standalone gate with exit code)");
       }
       log("");
     }
@@ -1646,11 +1837,17 @@ async function cmdInit(parsedArgs) {
     log(`    ⚠️  Content check skipped: ${e.message || e}`);
     log("");
   }
+}
 
-  log("");
+// ─── Stage 14: Print completion banner ────────────────────────────
+function printCompletionBanner(opts) {
+  const { lang, totalGroups, totalStart } = opts;
+  const totalFiles = countFiles();
+  const pass1Files = countPass1Files();
   const memoryReady = fileExists(path.join(PROJECT_ROOT, "claudeos-core/memory/decision-log.md"));
   const rulesReady = fileExists(path.join(PROJECT_ROOT, ".claude/rules/60.memory/01.decision-log.md"));
   const l4Status = (memoryReady && rulesReady) ? "memory + rules" : "partial";
+  log("");
   log("╔════════════════════════════════════════════════════╗");
   log("║  ✅ ClaudeOS-Core — Complete                       ║");
   log("║                                                    ║");
@@ -1670,4 +1867,113 @@ async function cmdInit(parsedArgs) {
   log("");
 }
 
+// ═══════════════════════════════════════════════════════════════════
+// Main orchestrator
+// ═══════════════════════════════════════════════════════════════════
+async function cmdInit(parsedArgs) {
+  const totalStart = Date.now();
+
+  // ─── Prerequisites check ───────────────────────────────────
+  checkPrerequisites();
+
+  // ─── Language selection ────────────────────────────────────
+  const lang = await resolveLanguage(parsedArgs);
+
+  // ─── Resume / Fresh selection ──────────────────────────────
+  // wasFreshClean: tracks whether we just wiped generated state via --force
+  // or "fresh" resume mode. Used by the Pass 3 backfill guard below:
+  // fresh/force explicitly means "regenerate from scratch", so a leftover
+  // CLAUDE.md from a prior run must NOT cause Pass 3 to be skipped via the
+  // v1.7.x migration backfill.
+  const { wasFreshClean } = await applyResumeMode(parsedArgs, lang);
+
+  log("");
+  log("╔════════════════════════════════════════════════════╗");
+  log("║       ClaudeOS-Core — Bootstrap (4-Pass)          ║");
+  log("╚════════════════════════════════════════════════════╝");
+  log(`    Project root: ${PROJECT_ROOT}`);
+  log(`    Language:     ${SUPPORTED_LANGS[lang]} (${lang})`);
+  log("");
+
+  // ─── [1] Install dependencies ──────────────────────────────
+  header("[1] Installing dependencies...");
+  if (!fileExists(path.join(TOOLS_DIR, "node_modules"))) {
+    run("npm install --silent", { cwd: TOOLS_DIR });
+  }
+  log("    ✅ Done\n");
+
+  // ─── [2] Create directory structure ────────────────────────
+  header("[2] Creating directory structure...");
+  ensureDirectories();
+  log("    ✅ Done\n");
+
+  // ─── [3] Run plan-installer ────────────────────────────────
+  header("[3] Analyzing project (plan-installer)...");
+  run(`node "${path.join(TOOLS_DIR, "plan-installer/index.js")}"`);
+  log("");
+
+  // ─── [4] Pass 1: Deep analysis per domain group ────────────
+  header("[4] Pass 1 — Deep analysis per domain group...");
+  const { domainGroups, totalGroups } = loadDomainGroups();
+  const pass1Prompts = loadPass1Prompts();
+
+  // Progress tracking: Pass 1 (N groups) + Pass 2 + Pass 3 + Pass 4 = totalSteps
+  const totalSteps = totalGroups + 3;
+  let completedSteps = 0;
+  const stepTimes = [];
+  const passStart = Date.now();
+  const progressBar = makeProgressBar(totalSteps, passStart, stepTimes);
+
+  const p1Delta = await runPass1Loop({
+    domainGroups, totalGroups, pass1Prompts,
+    progressBar, stepTimes,
+    startingStep: completedSteps,
+  });
+  completedSteps += p1Delta;
+
+  // ─── [5] Pass 2: Merge analysis results ────────────────────
+  header("[5] Pass 2 — Merging analysis results...");
+  const p2Delta = await runPass2({
+    progressBar, stepTimes, nextStep: completedSteps + 1,
+  });
+  completedSteps += p2Delta;
+  log("");
+
+  // ─── [5.5] Build pass3-context.json (v2.1) ─────────────────
+  buildPass3ContextJson();
+  log("");
+
+  // ─── [6] Pass 3: Generate + verify ─────────────────────────
+  header("[6] Pass 3 — Generating all files...");
+  handlePass3StaleMarker(wasFreshClean);
+  const { ran: p3Ran } = await dispatchPass3({
+    wasFreshClean, lang, stepTimes,
+    progressBar, nextStep: completedSteps + 1,
+  });
+  if (p3Ran) completedSteps++;
+  log("");
+
+  // ─── [7] Pass 4: L4 memory scaffolding ─────────────────────
+  header("[7] Pass 4 — Memory scaffolding...");
+  const p4Delta = await runPass4({
+    lang, stepTimes, progressBar, nextStep: completedSteps + 1,
+  });
+  completedSteps += p4Delta;
+  log("");
+
+  // ─── [8] Run verification tools ────────────────────────────
+  header("[8] Running verification tools...");
+  runVerificationTools();
+  log("");
+
+  // ─── Structural lint (v2.3.0+) ─────────────────────────────
+  runLint();
+
+  // ─── Content integrity (Guard 4 — v2.3.0+) ─────────────────
+  runContentValidator();
+
+  // ─── Complete ──────────────────────────────────────────────
+  printCompletionBanner({ lang, totalGroups, totalStart });
+}
+
 module.exports = { cmdInit, InitError };