ma-agents 3.6.2 → 3.8.0

package/lib/bmad.js

@@ -30,6 +30,267 @@ function buildChildSpawnEnv(parentEnv = process.env) {
 const BMAD_DIR = '_bmad';
 const CONFIG_DIR = path.join(BMAD_DIR, '_config', 'agents');
 
+// ── Canonical config paths (Story 22.7) ─────────────────────────────────────
+//
+// BMAD v6.3.0 (PR #2159) removed the `bmad-init` skill and moved the canonical
+// project config from `_bmad/_config/manifest.yaml` to `_bmad/bmm/config.yaml`.
+// All ma-agents code paths and skills MUST read from CANONICAL_CONFIG_REL.
+//
+// LEGACY_MANIFEST_REL is kept ONLY as a detection marker for the migration
+// shim in ensureCanonicalConfigLocation() below — it is NEVER read silently
+// as a value source. The stale-module surgery in runUpdateStep() still
+// references it because that code cleans up pre-6.3 install artifacts before
+// handing control to bmad-method; the cleanup is a write-path, not a
+// canonical-config read.
+const CANONICAL_CONFIG_REL = path.join(BMAD_DIR, 'bmm', 'config.yaml');
+const LEGACY_MANIFEST_REL = path.join(BMAD_DIR, '_config', 'manifest.yaml');
+
+/**
+ * Project-relative directory name used to stage the bundled plugin
+ * (`lib/bmad-extension-plugin/`) before invoking `bmad-method install
+ * --custom-source <stage-path>`.
+ *
+ * Kept as a module-level constant (not an env-var) so the path is stable
+ * across runs and easy for operators to inspect after a failed install.
+ * See Story 22.8 (adds this path to the ma-agents-managed .gitignore).
+ */
+const PLUGIN_STAGE_DIR_NAME = '.ma-agents-plugin-stage';
+
+/**
+ * Copy the bundled plugin (`lib/bmad-extension-plugin/`) into the target
+ * project at `<projectRoot>/.ma-agents-plugin-stage/` so that bmad-method
+ * 6.3.0's PluginResolver (local-file strategy) can install it via
+ * `--custom-source <stage-path>`.
+ *
+ * Contract (Story 22.6 AC 2, AC 3):
+ *   - Produces a fresh byte-identical copy of the source tree (not a symlink,
+ *     not a hardlink). fs-extra's `copySync` performs a recursive file copy;
+ *     combined with the pre-copy wipe below it guarantees the stage is a
+ *     clean snapshot of the build output.
+ *   - Any pre-existing stage directory (left over from a prior failed install)
+ *     is removed first so content never merges across runs. This mirrors
+ *     `scripts/build-plugin.js`'s own wipe-and-recreate pattern and defends
+ *     against cross-version skill bleed (the skill catalog renamed in 22.2).
+ *   - On platforms where the source contains symlinks, they are dereferenced
+ *     by `fs-extra.copySync` (`dereference: true`) — the stage is a flat copy
+ *     so a BMAD installer that writes into the stage never touches repo source.
+ *
+ * Return shape:
+ *   `{ stagePath, customSourceArg }` — where `stagePath` is the absolute path
+ *   used for filesystem work (remove on cleanup, surface on failure) and
+ *   `customSourceArg` is what to pass to bmad-method's `--custom-source`.
+ *   Why split them: bmad-method 6.3.0's `parseSource()` only treats strings
+ *   starting with `/`, `./`, `../`, or `~` as local paths; a Windows
+ *   absolute like `D:\path\...` falls through to "Not a valid Git URL or
+ *   local path" and the plugin silently fails to resolve. We pass the
+ *   relative form `./<dir>` (the installer runs with cwd = projectRoot, so
+ *   it resolves to the same absolute path) to stay cross-platform safe.
+ *
+ * @param {string} projectRoot - Absolute path to the target project
+ * @returns {{ stagePath: string, customSourceArg: string }}
+ * @throws {Error} If the source plugin bundle is missing (build was skipped)
+ */
+function stagePlugin(projectRoot) {
+    // Edge-case #2 — normalize to absolute FIRST. Callers may pass a relative
+    // `./some-project` path; downstream `fs.statSync` / `path.join` then
+    // resolve against the current cwd, which differs between the ma-agents
+    // CLI process and the bmad-method child (runCommand sets cwd = projectRoot).
+    // Resolving here once keeps every subsequent path op unambiguous.
+    // path.resolve does NOT require the path to exist, so it's safe to run
+    // before the existence check below.
+    projectRoot = path.resolve(projectRoot);
+    // Import inside the function so unit-tests can exercise the helper without
+    // the build-plugin.js require-chain loading the full pipeline.
+    const { OUT_DIR: pluginBundlePath } = require('../scripts/build-plugin');
+    if (!fs.existsSync(pluginBundlePath)) {
+        throw new Error(
+            `Bundled plugin not found at ${pluginBundlePath} — run \`npm run build:plugin\` before installing.`
+        );
+    }
+    // Edge-case #1 — the bundle directory may exist but be empty (half-built
+    // or a partially wiped prior `scripts/build-plugin.js` run). Verify the
+    // two load-bearing manifests are present before we copy anything; without
+    // these, bmad-method's PluginResolver would either silently install a
+    // no-op or throw deep in its pipeline with a less diagnosable message.
+    const requiredBundleEntries = [
+        path.join('.claude-plugin', 'marketplace.json'),
+        path.join('skills', 'module.yaml'),
+    ];
+    for (const rel of requiredBundleEntries) {
+        const abs = path.join(pluginBundlePath, rel);
+        if (!fs.existsSync(abs)) {
+            throw new Error(
+                `Bundled plugin at ${pluginBundlePath} is missing required file ` +
+                `"${rel}" — run \`npm run build:plugin\` to regenerate a complete bundle.`
+            );
+        }
+    }
+    if (!fs.existsSync(projectRoot)) {
+        throw new Error(
+            `Cannot stage plugin — projectRoot does not exist: ${projectRoot}`
+        );
+    }
+    // Edge-case #3 — projectRoot must be a directory. A caller passing a file
+    // path would otherwise surface as a confusing EEXIST/ENOTDIR deep inside
+    // the fs.copySync call. Fail fast with a clear message.
+    if (!fs.statSync(projectRoot).isDirectory()) {
+        throw new Error(
+            `Cannot stage plugin — projectRoot is not a directory: ${projectRoot}`
+        );
+    }
+    const stagePath = path.join(projectRoot, PLUGIN_STAGE_DIR_NAME);
+    // Remove any stale stage left behind by a previous failed install.
+    // Merging old and new content would risk shipping retired skill IDs
+    // (Story 22.2) and break the byte-identical guarantee in AC 3.
+    //
+    // Security: reject a stage path that IS a symlink before removing it.
+    // Without this check, fs.removeSync follows the link and could delete
+    // content outside the project (e.g., if an attacker or a careless user
+    // pre-created `.ma-agents-plugin-stage` as a symlink to a home dir).
+    if (fs.existsSync(stagePath)) {
+        const stageLstat = fs.lstatSync(stagePath);
+        if (stageLstat.isSymbolicLink()) {
+            throw new Error(
+                `Refusing to stage plugin — ${stagePath} is a symbolic link. ` +
+                `Remove it manually and re-run; ma-agents will not follow symlinks ` +
+                `inside the project root for safety.`
+            );
+        }
+        // Edge-case #5 — on Windows, a prior install may still hold file
+        // handles (EBUSY/EPERM). Re-throw with context so the operator knows
+        // which path failed and can close the offending process.
+        try {
+            fs.removeSync(stagePath);
+        } catch (err) {
+            throw new Error(
+                `Cannot wipe stale stage ${stagePath}: ${err.message}`
+            );
+        }
+    }
+    // `dereference: true` copies symlink targets as regular files — we never
+    // want a symlink inside the stage pointing back into repo source, because
+    // bmad-method may write into the staged plugin during install.
+    //
+    // Edge-case #6 — if the copy aborts mid-tree (disk full, permission flip,
+    // user Ctrl+C at the OS layer), the partial stage would be merged on next
+    // run and break AC 3's byte-identical guarantee. Best-effort remove the
+    // half-populated stage, then rethrow with a contextual message.
+    try {
+        fs.copySync(pluginBundlePath, stagePath, { overwrite: true, dereference: true });
+    } catch (err) {
+        try { fs.removeSync(stagePath); } catch { /* swallow — primary error wins */ }
+        throw new Error(`Stage copy failed: ${err.message}`);
+    }
+    // POSIX-style `./<dir>` satisfies BMAD's parseSource() local-path detector
+    // on both Linux/macOS and Windows. The installer's cwd is always
+    // projectRoot (see runCommand calls below), so this resolves identically
+    // to `stagePath`.
+    const customSourceArg = `./${PLUGIN_STAGE_DIR_NAME}`;
+    console.log(chalk.gray(`  Staged plugin: ${stagePath}`));
+    return { stagePath, customSourceArg };
+}
+
+/**
+ * Remove the plugin stage directory produced by {@link stagePlugin}.
+ *
+ * Call this only after the bmad-method install succeeds. On failure we
+ * deliberately leave the stage in place (Story 22.6 AC 6) so operators can
+ * inspect exactly what was about to be installed and re-run BMAD directly
+ * with `--custom-source <stage>` as a bypass.
+ *
+ * @param {string} stagePath - Absolute path returned by stagePlugin()
+ * @returns {void}
+ */
+function cleanupStage(stagePath) {
+    if (!stagePath) return;
+    try {
+        // Edge-case #4 — if the path is (now) a symlink, unlink ONLY the link.
+        // `fs.removeSync` on a symlink-to-directory would recurse into the
+        // target and could delete files outside the project root (e.g., if a
+        // concurrent process replaced the stage with a symlink between
+        // stagePlugin() and cleanupStage()). `lstatSync` does not follow the
+        // link; `unlinkSync` removes the link entry without touching the
+        // target.
+        if (fs.existsSync(stagePath)) {
+            const lst = fs.lstatSync(stagePath);
+            if (lst.isSymbolicLink()) {
+                fs.unlinkSync(stagePath);
+                console.log(chalk.gray(`  Removed plugin stage symlink: ${stagePath}`));
+                return;
+            }
+        }
+        fs.removeSync(stagePath);
+        console.log(chalk.gray(`  Removed plugin stage directory: ${stagePath}`));
+    } catch (err) {
+        // Non-fatal — surface a warning so the operator can clean up manually.
+        // We do not rethrow because the install itself succeeded; leaving the
+        // stage on disk is a cosmetic issue compared to breaking an otherwise
+        // green install.
+        console.warn(
+            chalk.yellow(
+                `  Warning: failed to remove plugin stage directory at ${stagePath}: ${err.message}`
+            )
+        );
+    }
+}
+
+/**
+ * F2a — Ensure the **project-root** `.gitignore` lists the plugin-stage
+ * directory exactly once. The single canonical write site for the Story 22.8
+ * policy: every BMAD orchestrator that calls `stagePlugin(projectRoot)` must
+ * call this immediately afterwards (or beforehand) with the same `projectRoot`.
+ *
+ * Why this lives here, not in the installer:
+ *   - The reason the entry exists is `stagePlugin()` writing
+ *     `<projectRoot>/.ma-agents-plugin-stage/`. The two operations belong
+ *     together so a future maintainer sees them as one unit.
+ *   - The pre-F2a placement (inside `installSkill()` per-agent loop) wrote
+ *     per-skill-dir `.gitignore` files because `installPath` is the agent's
+ *     skills directory, not the project root. Moving the call here makes
+ *     the project-root contract self-evident.
+ *
+ * Lazy-require — `lib/installer.js` requires `./bmad` for `PLUGIN_STAGE_DIR_NAME`
+ * at module top, so a top-level require of installer here would create a
+ * load-order circular dependency. The runtime `require('./installer')` below
+ * is safe because installer's exports object is fully populated by the time
+ * this function is invoked (after CLI startup).
+ *
+ * Failure policy — gitignore management is cosmetic relative to the install.
+ * If writing the file fails (permission denied, read-only fs, ENOSPC), we
+ * surface a warning and continue rather than aborting an otherwise-green
+ * install. The install will have produced no observable side effect under
+ * the project's `.gitignore` policy in that case, which is the same outcome
+ * as a project that already lists the entry.
+ *
+ * @param {string} projectRoot - Absolute path to the target project root
+ *   (the directory containing the project's top-level `.gitignore`).
+ * @returns {void}
+ */
+function ensurePluginStageGitignoredForProject(projectRoot) {
+    if (typeof projectRoot !== 'string' || projectRoot.length === 0) return;
+    let installer;
+    try {
+        installer = require('./installer');
+    } catch (err) {
+        // Installer module failed to load — should never happen in a valid
+        // install, but if it does we cannot do anything useful here.
+        console.warn(chalk.yellow(`  Warning: could not load installer for gitignore policy: ${err.message}`));
+        return;
+    }
+    if (typeof installer.ensurePluginStageIgnored !== 'function') return;
+    try {
+        installer.ensurePluginStageIgnored(projectRoot);
+    } catch (err) {
+        // EACCES on read-only `.gitignore`, EROFS on read-only filesystem, etc.
+        // Logged so the operator can fix it manually; never fatal to the install.
+        console.warn(
+            chalk.yellow(
+                `  Warning: could not update ${path.join(projectRoot, '.gitignore')} with plugin-stage entry: ${err.message}`
+            )
+        );
+    }
+}
+
 /**
  * Run a shell command, relaying output to stdout/stderr.
  * Always uses pipe mode so that on failure, error.stdout and error.stderr
@@ -52,14 +313,33 @@ function runCommand(command, options = {}) {
 }
 
 function getBmadCommand(args) {
-    try {
-        const wrapperPath = require.resolve('bmad-method/tools/bmad-npx-wrapper.js');
-        return `node "${wrapperPath}" ${args}`;
-    } catch (err) {
-        const wrapped = new Error('bmad-method not found in node_modules — run "npm install" first');
-        wrapped.cause = err;
-        throw wrapped;
+    // bmad-method 6.3.0 replaced the `tools/bmad-npx-wrapper.js` entry point
+    // with `tools/installer/bmad-cli.js` (see `bin.bmad-method` in the
+    // upstream package.json). Prefer the new entry; fall back to the legacy
+    // wrapper path only to keep older local checkouts working during a
+    // partial upgrade (defensive — the test suite pins the installed version).
+    const candidates = [
+        'bmad-method/tools/installer/bmad-cli.js',
+        'bmad-method/tools/bmad-npx-wrapper.js',
+    ];
+    let lastError = null;
+    for (const candidate of candidates) {
+        try {
+            const resolved = require.resolve(candidate);
+            return `node "${resolved}" ${args}`;
+        } catch (err) {
+            // Remember the last failure so diagnostics can chain back to the
+            // actual MODULE_NOT_FOUND / ENOENT from require.resolve.
+            lastError = err;
+        }
+    }
+    const wrapped = new Error(
+        'bmad-method CLI entry point not found in node_modules — run "npm install" first'
+    );
+    if (lastError) {
+        wrapped.cause = lastError;
     }
+    throw wrapped;
 }
 
 function isBmadInstalled(projectRoot = process.cwd()) {
@@ -258,6 +538,45 @@ function classifyRecompileFailure(error, opts = {}) {
     };
 }
 
+/**
+ * Resolve the correct CLI flag for passing extension/custom-module sources.
+ *
+ * bmad-method 6.3.0 renamed `--custom-content` to `--custom-source`. To keep
+ * the builder working across both versions (and to survive local downgrades),
+ * grep the installed install command for the newer flag first and fall back
+ * to the legacy name. We read once and cache the result because buildBmadArgs
+ * can be called repeatedly during a single install flow.
+ *
+ * @returns {'--custom-source' | '--custom-content'}
+ */
+let _cachedCustomContentFlag = null;
+function resolveCustomContentFlag() {
+    if (_cachedCustomContentFlag) return _cachedCustomContentFlag;
+    const candidates = [
+        { path: 'bmad-method/tools/installer/commands/install.js', flags: ['--custom-source', '--custom-content'] },
+        { path: 'bmad-method/tools/cli/commands/install.js', flags: ['--custom-source', '--custom-content'] },
+    ];
+    for (const { path: relPath, flags } of candidates) {
+        try {
+            const resolved = require.resolve(relPath);
+            const content = fs.readFileSync(resolved, 'utf8');
+            for (const flag of flags) {
+                if (content.includes(flag)) {
+                    _cachedCustomContentFlag = flag;
+                    return flag;
+                }
+            }
+        } catch {
+            // try next
+        }
+    }
+    // Defensive default — keep older behavior if we cannot inspect the installed
+    // package. The installer will fail loudly with an unknown-flag error, which
+    // is a safer failure mode than silently dropping the extension.
+    _cachedCustomContentFlag = '--custom-content';
+    return _cachedCustomContentFlag;
+}
+
 /**
  * Build a complete bmad-method CLI command from an install context object.
  * Replaces ad-hoc string concatenation with a single authoritative builder.
@@ -272,6 +591,11 @@ function classifyRecompileFailure(error, opts = {}) {
  * @param {string} [ctx.commLang] - Communication language
  * @param {string} [ctx.docLang] - Document output language
  * @param {string} [ctx.outputFolder] - Output folder relative to project root
+ * @param {string} [ctx.customSource] - Absolute path to a staged plugin
+ *   directory (Story 22.6). When provided, this is appended as
+ *   `--custom-source <path>`; when omitted no extension flag is added.
+ *   The legacy fallback to `lib/bmad-extension/` was removed when the
+ *   stage-and-invoke flow replaced applyCustomizations().
  * @returns {string} Complete command string ready for execSync
  */
 function buildBmadArgs(ctx) {
@@ -299,13 +623,15 @@ function buildBmadArgs(ctx) {
         parts.push('--output-folder', `"${ctx.outputFolder}"`);
     }
 
-    // Extension module — always pass on both install and update.
-    // bmad-method 6.2.2 detects _bmad/_config/custom/ on update and tries
-    // to reinstall the cached module, but fails with "Source for module
-    // 'custom' is not available" unless the source path is provided.
-    const extensionPath = path.join(__dirname, 'bmad-extension');
-    if (fs.existsSync(extensionPath)) {
-        parts.push('--custom-content', `"${extensionPath}"`);
+    // Story 22.6 — stage-and-invoke. When callers pass an explicit customSource
+    // (the project-local `.ma-agents-plugin-stage/` directory produced by
+    // stagePlugin()), we append it via the 6.3.0 `--custom-source` flag (with a
+    // downgrade path to the legacy `--custom-content` name for local checkouts
+    // that still run bmad-method 6.2.x). The hand-parsed `lib/bmad-extension/`
+    // fallback that lived here was removed alongside applyCustomizations().
+    if (ctx.customSource) {
+        const flag = resolveCustomContentFlag();
+        parts.push(flag, `"${ctx.customSource}"`);
     }
 
     if (ctx.action === 'update') {
@@ -315,7 +641,52 @@ function buildBmadArgs(ctx) {
     return getBmadCommand(parts.join(' '));
 }
 
+/**
+ * Common pre-install hook invoked at the top of every BMAD entry point
+ * (installBmad, updateBmad, runMigration). Centralizing this makes it
+ * obvious which actions every entry point shares, and lets us add new
+ * shared pre-checks in one place rather than tracking N call sites.
+ *
+ * F3 Section 6 — added so updateBmad() and runMigration() also get the
+ * canonical-config-location drift signal that installBmad() already has.
+ *
+ * Idempotency: ensureCanonicalConfigLocation is read-mostly (only writes
+ * is a notice log when both legacy and canonical config exist, and only
+ * sets the migration-needed flag in its return value when the legacy
+ * file is the only one present). Calling it twice in a single entry-
+ * point invocation (e.g. installBmad → runMigration) re-emits the same
+ * notice, but:
+ *   - The notice is informational, not destructive.
+ *   - Operators upgrading from pre-6.3 see at most two identical lines,
+ *     which is acceptable for a one-shot migration path.
+ *   - Steady-state installs (canonical-only or fresh) emit zero notices.
+ *
+ * @param {string} projectRoot - Absolute path to the project root.
+ * @returns {ReturnType<typeof ensureCanonicalConfigLocation>} The drift
+ *   detection result so callers that need the `needsRegeneration` flag
+ *   (e.g. installBmad's migration check) can use it without a second call.
+ */
+function preInstallHooks(projectRoot) {
+    // Edge-case-hunter E6: guard against undefined / empty projectRoot
+    // because path.join('', anything) silently resolves to a relative path
+    // against the caller's cwd, which would surface the drift signal for
+    // the WRONG project. Caller error must surface loud, not silently.
+    if (!projectRoot || typeof projectRoot !== 'string') {
+        throw new Error(
+            `preInstallHooks: projectRoot must be a non-empty string (got ${JSON.stringify(projectRoot)})`
+        );
+    }
+    // Story 22.7 AC #6 — normalize the config location BEFORE any read that
+    // assumes the canonical v6.3.0 path. This runs ahead of
+    // detectMigrationNeed() so operators upgrading from a pre-6.3 install get
+    // a clear message that legacy config is NOT used as a fallback; the
+    // downstream bmad-method install will regenerate the new layout.
+    return ensureCanonicalConfigLocation(projectRoot);
+}
+
 async function installBmad(modules = ['bmm', 'bmb'], tools = [], projectRoot = process.cwd(), force = false, { userName = '', commLang = '', docLang = '', outputFolder = '' } = {}) {
+    preInstallHooks(projectRoot);
+
     // Detect migration need
     const detection = detectMigrationNeed(projectRoot);
 
@@ -325,6 +696,29 @@ async function installBmad(modules = ['bmm', 'bmb'], tools = [], projectRoot = p
         return await runMigration(modules, tools, projectRoot, force, { userName, commLang, docLang, outputFolder });
     }
 
+    // Story 22.6 — stage-and-invoke. Copy the bundled plugin into the project
+    // and hand its path to bmad-method via --custom-source so BMAD's own
+    // PluginResolver places the skills (no more post-install manifest surgery).
+    //
+    // Edge-case #7 — stagePlugin() can throw (missing bundle, invalid
+    // projectRoot, stale-stage wipe EBUSY, half-populated copy). The CLI
+    // caller (bin/cli.js) treats this function's return value as a
+    // success/failure boolean and does not try/catch around it, so an
+    // uncaught throw here would bubble out as a crash. Catch staging errors
+    // explicitly, log them, and propagate as `return false` like the other
+    // failure branches.
+    let stagePath;
+    let customSourceArg;
+    try {
+        ({ stagePath, customSourceArg } = stagePlugin(projectRoot));
+    } catch (error) {
+        console.error(chalk.red(`  Plugin staging failed: ${error.message}`));
+        return false;
+    }
+    // F2a — Story 22.8 gitignore policy. Apply at the project root next to
+    // stagePlugin() so the two operations are co-located. Idempotent and
+    // non-fatal (see ensurePluginStageGitignoredForProject() for details).
+    ensurePluginStageGitignoredForProject(projectRoot);
     const command = buildBmadArgs({
         projectRoot,
         modules,
@@ -334,18 +728,51 @@ async function installBmad(modules = ['bmm', 'bmb'], tools = [], projectRoot = p
         commLang,
         docLang,
         outputFolder,
+        customSource: customSourceArg,
     });
 
     await prePopulateBmadCache(force);
 
+    console.log(chalk.cyan(`  Invoking bmad-method with --tools ${(tools && tools.length > 0) ? tools.join(',') : 'none'}`));
     console.log(chalk.gray(`  Running: ${command}`));
+    // Edge-case #8 — track bmad-method success and post-step (deployMethodology)
+    // success SEPARATELY. The stage must only be cleaned up when BOTH succeed;
+    // otherwise the operator loses the exact bundle that was handed to
+    // bmad-method when a post-install step fails, making diagnosis harder.
+    let bmadInvokeSucceeded = false;
+    let postStepsSucceeded = false;
     try {
         runCommand(command, { cwd: projectRoot, env: buildChildSpawnEnv() });
+        bmadInvokeSucceeded = true;
+        // F1a — on-prem persona phase-prefix pass. Runs BEFORE
+        // deployMethodology so a methodology-deploy failure doesn't prevent
+        // the prefix from being applied (they are independent concerns).
+        // No-op for standard profile; reads profile from `.ma-agents.json`
+        // if present (the same signal setProfile() / Story 21.10 writes).
+        const profile = require('./profile').getProfile(projectRoot);
+        await applyOnPremPhasePrefixToDeployedSkills(projectRoot, profile);
         await deployMethodology(projectRoot, force);
+        postStepsSucceeded = true;
         return true;
     } catch (error) {
+        // Edge-case #7 — surface stagePlugin errors (or any downstream error)
+        // as a clean non-zero outcome rather than an uncaught exception. The
+        // existing try/catch already satisfies this; the explicit
+        // `bmadInvokeSucceeded` check below distinguishes pre-invoke failures
+        // (stage never created / already left in place by stagePlugin's own
+        // error paths) from runtime bmad/deploy failures.
         console.error(chalk.red(`  BMAD installation failed: ${error.message}`));
         return false;
+    } finally {
+        if (bmadInvokeSucceeded && postStepsSucceeded) {
+            cleanupStage(stagePath);
+        } else {
+            // AC 6 — leave the stage for diagnostics so the operator can
+            // re-run bmad-method manually against the same bundle. This fires
+            // for BOTH bmad-method failure and post-step failure (e.g.,
+            // deployMethodology throwing after a green bmad install).
+            console.error(chalk.yellow(`  Install failed — plugin stage left in place for inspection: ${stagePath}`));
+        }
     }
 }
 
@@ -354,12 +781,41 @@ async function installBmad(modules = ['bmm', 'bmb'], tools = [], projectRoot = p
  * Rolls back on failure (NFR29).
  */
 async function runMigration(modules, tools, projectRoot, force, { userName, commLang, docLang, outputFolder }) {
+    // F3 Section 6 — invoke shared pre-install hooks. When runMigration is
+    // called from installBmad() this is a re-call (installBmad already ran
+    // the hook); the duplicate is intentional so runMigration is correct
+    // when invoked from any future entry point. ensureCanonicalConfigLocation
+    // is idempotent — see preInstallHooks() docstring.
+    preInstallHooks(projectRoot);
+
     // Step 1: Backup existing customizations
     console.log(chalk.cyan('  Step 1/4: Backing up existing customizations...'));
     const backedUpFiles = await backupCustomizations(projectRoot);
 
     // Step 2: Run bmad-method with --action update
     console.log(chalk.cyan('  Step 2/4: Updating BMAD-METHOD...'));
+    // Story 22.6 — migration path also uses stage-and-invoke so the plugin
+    // rides in on --custom-source instead of the retired manifest-surgery path.
+    //
+    // Edge-case #7 — catch stagePlugin() errors so the migration surfaces as
+    // a clean `return false` rather than an uncaught exception bubbling out
+    // of installBmad() into the CLI.
+    let stagePath;
+    let customSourceArg;
+    try {
+        ({ stagePath, customSourceArg } = stagePlugin(projectRoot));
+    } catch (error) {
+        console.error(chalk.red(`  Plugin staging failed: ${error.message}`));
+        if (backedUpFiles.length > 0) {
+            console.log(chalk.yellow('  Rolling back — restoring backed-up customizations...'));
+            await restoreCustomizations(projectRoot);
+        }
+        return false;
+    }
+    // F2a — Story 22.8 gitignore policy on the migration path. Same rationale
+    // as installBmad(): co-locate with stagePlugin() so the project-root write
+    // happens once per pipeline pass.
+    ensurePluginStageGitignoredForProject(projectRoot);
     const command = buildBmadArgs({
         projectRoot,
         modules,
@@ -369,15 +825,19 @@ async function runMigration(modules, tools, projectRoot, force, { userName, comm
         commLang,
         docLang,
         outputFolder,
+        customSource: customSourceArg,
     });
 
     await prePopulateBmadCache(force);
 
+    console.log(chalk.cyan(`  Invoking bmad-method with --tools ${(tools && tools.length > 0) ? tools.join(',') : 'none'}`));
     console.log(chalk.gray(`  Running: ${command}`));
     try {
         runCommand(command, { cwd: projectRoot, env: buildChildSpawnEnv() });
     } catch (error) {
-        // Rollback on failure
+        // Rollback on failure — leave the stage in place (AC 6) so the
+        // operator can re-run BMAD manually with `--custom-source <stage>`
+        // as a bypass, and inspect what was about to be installed.
         console.error(chalk.red(`  BMAD update failed: ${error.message}`));
         if (backedUpFiles.length > 0) {
             console.log(chalk.yellow('  Rolling back — restoring backed-up customizations...'));
@@ -385,6 +845,7 @@ async function runMigration(modules, tools, projectRoot, force, { userName, comm
         }
         console.error(chalk.red('  Migration aborted. Your project remains on the previous version.'));
         console.error(chalk.yellow('  Suggestion: Run "npm update bmad-method" manually, then retry installation.'));
+        console.error(chalk.yellow(`  Plugin stage left in place for inspection: ${stagePath}`));
         return false;
     }
 
@@ -400,13 +861,55 @@ async function runMigration(modules, tools, projectRoot, force, { userName, comm
     console.log(chalk.cyan('  Step 4/4: Cleaning up legacy artifacts...'));
     await cleanupLegacyArtifacts(projectRoot);
 
+    // F1a — on-prem persona phase-prefix pass. Migrations can flip profile
+    // or re-stage skills, so the pass runs here too. Identical no-op
+    // semantics for standard profile.
+    const profile = require('./profile').getProfile(projectRoot);
+    await applyOnPremPhasePrefixToDeployedSkills(projectRoot, profile);
+
     await deployMethodology(projectRoot, force);
 
+    // All migration steps succeeded — safe to clean up the stage now.
+    // Cleaning up earlier would remove diagnostics if any of steps 3-4 or
+    // deployMethodology failed after a successful bmad-method invocation.
+    cleanupStage(stagePath);
+
     console.log(chalk.green(`  Migration to BMAD ${BMAD_TARGET_VERSION} complete!`));
     return true;
 }
 
 async function updateBmad(modules = ['bmm', 'bmb'], tools = [], projectRoot = process.cwd(), force = false, { userName = '', commLang = '', docLang = '', outputFolder = '' } = {}) {
+    // F3 Section 6 — invoke shared pre-install hooks so operators using the
+    // update entry point also receive the canonical-config-location drift
+    // signal. Previously only installBmad() ran this check, meaning a
+    // pre-6.3 → 6.3+ upgrade triggered via `--action update` (skipping the
+    // install path) would silently miss the drift notice.
+    preInstallHooks(projectRoot);
+
+    // Story 22.6 — stage-and-invoke replaces the legacy manifest-surgery block
+    // that used to live here (hand-parsing of BMAD-internal registry files,
+    // hardcoded stale-module whitelist, CSV column indexing, and physical
+    // directory removal). bmad-method 6.3.0's PluginResolver handles update
+    // semantics natively via --custom-source, so we only need to stage the
+    // bundled plugin and invoke the installer.
+    //
+    // Edge-case #7 — catch stagePlugin() errors so the CLI caller receives a
+    // false return rather than an uncaught exception (same rationale as
+    // installBmad). Without this, a broken bundle or stale stage with held
+    // file handles would crash the CLI instead of logging a diagnosable
+    // message.
+    let stagePath;
+    let customSourceArg;
+    try {
+        ({ stagePath, customSourceArg } = stagePlugin(projectRoot));
+    } catch (error) {
+        console.error(chalk.red(`  Plugin staging failed: ${error.message}`));
+        return false;
+    }
+    // F2a — Story 22.8 gitignore policy on the update path. Idempotent re-runs
+    // are the explicit AC #4 contract; calling here on every update keeps the
+    // entry present even if the project's `.gitignore` was reset between runs.
+    ensurePluginStageGitignoredForProject(projectRoot);
     const command = buildBmadArgs({
         projectRoot,
         modules,
@@ -416,98 +919,46 @@ async function updateBmad(modules = ['bmm', 'bmb'], tools = [], projectRoot = pr
         commLang,
         docLang,
         outputFolder,
+        customSource: customSourceArg,
     });
 
     await prePopulateBmadCache(force);
 
-    // bmad-method 6.2.2 installs the custom extension as module "custom" in _bmad/
-    // but caches it as "ma-skills" (the code from module.yaml). On update it reads
-    // the files-manifest, finds module "custom", and fails because it can't locate
-    // the source for a module named "custom". Fix: strip stale "custom" module
-    // entries from the manifest so the module gets cleanly reinstalled via --custom-content.
-    // bmad-method 6.2.2 bug: on --action update --yes, the installer reads
-    // manifest.yaml to discover previously installed modules, then preserves them
-    // all (non-interactive default). It then tries to reinstall each one.
-    // "custom" fails because there's no source under that name (it's "ma-skills"),
-    // and "bmb" fails due to a broken directory structure in 6.2.2.
-    //
-    // Fix: before running bmad-method, clean all three persistence layers:
-    //   1. manifest.yaml   — remove stale module entries
-    //   2. files-manifest.csv — remove stale file tracking entries
-    //   3. physical directories — remove _bmad/bmb/ and _bmad/_config/custom/
-
-    const staleModules = ['custom', 'bmb'];
-
-    // 1. Clean manifest.yaml (the primary trigger for the re-install loop)
-    const yamlManifestPath = path.join(projectRoot, BMAD_DIR, '_config', 'manifest.yaml');
-    if (fs.existsSync(yamlManifestPath)) {
-        try {
-            const yamlContent = await fs.readFile(yamlManifestPath, 'utf-8');
-            const manifest = yaml.parse(yamlContent);
-            if (manifest?.modules && Array.isArray(manifest.modules)) {
-                const before = manifest.modules.length;
-                manifest.modules = manifest.modules.filter(
-                    m => !staleModules.includes(typeof m === 'string' ? m : m.name)
-                );
-                const removed = before - manifest.modules.length;
-                if (removed > 0) {
-                    await fs.writeFile(yamlManifestPath, yaml.stringify(manifest), 'utf-8');
-                    console.log(chalk.gray(`  Cleaned ${removed} stale module(s) from manifest.yaml`));
-                }
-            }
-        } catch (err) {
-            // Non-fatal
-        }
-    }
-
-    // 2. Clean files-manifest.csv (prevents stale file-tracking references)
-    const filesManifestPath = path.join(projectRoot, BMAD_DIR, '_config', 'files-manifest.csv');
-    if (fs.existsSync(filesManifestPath)) {
-        try {
-            let csv = await fs.readFile(filesManifestPath, 'utf-8');
-            const before = csv.split('\n').length;
-            csv = csv.split('\n').filter(line => {
-                const fields = line.split(',');
-                const mod = fields[2] && fields[2].replace(/"/g, '');
-                return !staleModules.includes(mod);
-            }).join('\n');
-            const after = csv.split('\n').length;
-            if (after < before) {
-                await fs.writeFile(filesManifestPath, csv, 'utf-8');
-                console.log(chalk.gray(`  Cleaned ${before - after} stale entries from files-manifest.csv`));
-            }
-        } catch (err) {
-            // Non-fatal
-        }
-    }
-
-    // 3. Remove physical directories so bmad-method's manifest-generator
-    //    doesn't re-discover them via scanInstalledModules().
-    //    _bmad/custom/ is safe to remove — applyCustomizations() recreates it after.
-    const staleDirs = [
-        path.join(projectRoot, BMAD_DIR, 'bmb'),
-        path.join(projectRoot, BMAD_DIR, 'custom'),
-        path.join(projectRoot, BMAD_DIR, '_config', 'custom'),
-    ];
-    for (const dir of staleDirs) {
-        if (fs.existsSync(dir)) {
-            try {
-                await fs.remove(dir);
-                console.log(chalk.gray(`  Removed stale directory: ${path.relative(projectRoot, dir)}`));
-            } catch (err) {
-                // Non-fatal
-            }
-        }
-    }
-
+    // Story 22.6 — the legacy manifest-surgery block that used to live here
+    // (hand-parsing of BMAD-internal registry files, hardcoded stale-module
+    // whitelist, physical directory removal) has been removed. bmad-method
+    // 6.3.0's PluginResolver handles update semantics natively via
+    // --custom-source against the staged plugin bundle. Story 22.7's
+    // "legacy-WRITE" annotation was retired along with the block it
+    // annotated — canonical config reads still go through
+    // readCanonicalBmadConfig() (see exports below).
+    console.log(chalk.cyan(`  Invoking bmad-method with --tools ${(tools && tools.length > 0) ? tools.join(',') : 'none'}`));
     console.log(chalk.gray(`  Running: ${command}`));
+    // Edge-case #8 — same split-tracking as installBmad(): the stage must
+    // survive a deployMethodology failure so the operator can inspect what
+    // was handed to bmad-method.
+    let bmadInvokeSucceeded = false;
+    let postStepsSucceeded = false;
     try {
         runCommand(command, { cwd: projectRoot, env: buildChildSpawnEnv() });
+        bmadInvokeSucceeded = true;
+        // F1a — on-prem persona phase-prefix pass; identical call to
+        // installBmad(). Runs on every update so a profile flipped since
+        // the last install gets re-stamped (Story 21.10 reconfigure).
+        const profile = require('./profile').getProfile(projectRoot);
+        await applyOnPremPhasePrefixToDeployedSkills(projectRoot, profile);
         await deployMethodology(projectRoot, force);
+        postStepsSucceeded = true;
         return true;
     } catch (error) {
         console.error(chalk.red(`  BMAD update failed: ${error.message}`));
         return false;
+    } finally {
+        if (bmadInvokeSucceeded && postStepsSucceeded) {
+            cleanupStage(stagePath);
+        } else {
+            console.error(chalk.yellow(`  Update failed — plugin stage left in place for inspection: ${stagePath}`));
+        }
     }
 }
 
@@ -617,297 +1068,252 @@ async function applyPersonaPhasePrefix(customizeSourceDir, configTargetDir, prof
     }
 }
 
-async function applyCustomizations(projectRoot = process.cwd(), modules = ['bmm', 'bmb'], tools = [], selectedAgentIds = [], force = false, { userName = '', commLang = '', docLang = '', outputFolder = '' } = {}) {
-    const sourceDir = path.join(__dirname, 'bmad-customizations');
-    const workflowSourceDir = path.join(__dirname, 'bmad-workflows');
-    const configTargetDir = path.join(projectRoot, CONFIG_DIR);
-    const agentTargetDir = path.join(projectRoot, BMAD_DIR, 'custom', 'agents');
-    const workflowTargetDir = path.join(projectRoot, BMAD_DIR, 'bmm', 'workflows');
-    const templateSourceDir = path.join(__dirname, 'mil498-templates');
-    const templateTargetDir = path.join(projectRoot, BMAD_DIR, 'bmm', 'templates', 'mil498');
-
-    // Mapping from BMAD agent IDs to their .md template filenames
-    const agentMdMap = {
-        'bmm-sre': 'sre.md',
-        'bmm-devops': 'devops.md',
-        'bmm-cyber': 'cyber.md',
-        'bmm-mil498': 'mil498.md',
-        'bmm-demerzel': 'demerzel.md'
-    };
-
-    // 1. Apply YAML customizations (filtered by selected agents)
-    // These must be in place BEFORE recompile so BMAD can use them during compilation
-    if (fs.existsSync(sourceDir)) {
-        await fs.ensureDir(configTargetDir);
-        const files = await fs.readdir(sourceDir);
-        for (const file of files) {
-            if (file.endsWith('.customize.yaml')) {
-                const agentId = file.replace('.customize.yaml', '');
-                // Always copy generic; filter others by selected agents
-                if (agentId === 'generic' || selectedAgentIds.length === 0 || selectedAgentIds.includes(agentId)) {
-                    await fs.copy(path.join(sourceDir, file), path.join(configTargetDir, file));
-                    console.log(chalk.cyan(`    + Applied customization: ${file}`));
-                }
-            }
-        }
-    }
-
-    // 2. Apply detailed agent templates to custom dir (.md files, filtered by selected agents)
-    // These go to _bmad/custom/agents/ for BMAD's custom agent resolution
-    if (fs.existsSync(sourceDir)) {
-        await fs.ensureDir(agentTargetDir);
-        const files = await fs.readdir(sourceDir);
-        for (const file of files) {
-            if (file.endsWith('.md')) {
-                const matchingAgentId = Object.entries(agentMdMap).find(([, mdFile]) => mdFile === file)?.[0];
-                if (!matchingAgentId || selectedAgentIds.length === 0 || selectedAgentIds.includes(matchingAgentId)) {
-                    await fs.copy(path.join(sourceDir, file), path.join(agentTargetDir, file));
-                    console.log(chalk.cyan(`    + Applied agent template: ${file}`));
-                }
-            }
-        }
-    }
-
-    // STAGE:RECOMPILE — Recompile agents to apply YAML customizations
-    // IMPORTANT: Steps 3-5 must run AFTER recompile because the recompile regenerates
-    // the _bmad/bmm/ tree and would wipe any files placed there beforehand.
-    const command = buildBmadArgs({
-        projectRoot,
-        modules,
-        tools,
-        action: 'install',
-        userName,
-        commLang,
-        docLang,
-        outputFolder,
-    });
-    await prePopulateBmadCache(force);
+// ─── F1a — on-prem persona phase-prefix restoration ──────────────────────────
+//
+// Pre-22.6, the phase-prefix pass ran against `.customize.yaml` files in
+// `_bmad/_config/agents/` via the now-retired `applyCustomizations()` flow.
+// Under the stage-and-invoke architecture those YAML files are no longer
+// deployed — bmad-method 6.3.0's PluginResolver emits per-tool persona SKILL.md
+// files under each tool's skills directory (e.g. `.claude/skills/bmad-agent-pm/
+// SKILL.md`). The persona content that used to live in YAML `critical_actions`
+// now lives inline in markdown.
+//
+// This helper walks the deployed tool trees after the install succeeds and
+// injects the `on_prem_phase_prefix` text (read from the canonical
+// `lib/bmad-customize/bmm-<persona>.customize.yaml` source) into each persona
+// SKILL.md using a marker-delimited block for idempotency. Only runs when
+// profile === 'on-prem'; no-op in every other case.
+//
+// Marker convention: `<!-- BEGIN:ma-on-prem-phase-prefix -->` …
+// `<!-- END:ma-on-prem-phase-prefix -->`. A second run replaces the existing
+// block byte-for-byte; removing/reverting is a manifest-uninstall concern
+// (Story 21.11) owned elsewhere.
+
+const ON_PREM_PREFIX_MARKER_BEGIN = '<!-- BEGIN:ma-on-prem-phase-prefix -->';
+const ON_PREM_PREFIX_MARKER_END = '<!-- END:ma-on-prem-phase-prefix -->';
+
+// ma-agents persona-id → deployed SKILL directory name. The deployed name
+// mirrors the BMAD plugin's skill manifest (Story 22.2 renamed these from
+// `bmad-ma-agent-*` to `bmad-agent-*`; keep the mapping explicit so future
+// upstream renames surface here as a contained change rather than a silent
+// no-op across every tool tree).
+const PERSONA_SKILL_MAP = Object.freeze({
+    'bmm-pm':           'bmad-agent-pm',
+    'bmm-architect':    'bmad-agent-architect',
+    'bmm-dev':          'bmad-agent-dev',
+    'bmm-analyst':      'bmad-agent-analyst',
+    'bmm-tech-writer':  'bmad-agent-tech-writer',
+    'bmm-ux-designer':  'bmad-agent-ux-designer',
+    'bmm-sm':           'bmad-agent-sm',
+    'bmm-qa':           'bmad-agent-qa',
+});
+
+// Tool skill-dir roots. Kept in sync with `lib/agents.js` canonical
+// `skillsDir` values — duplicated here (not imported) to avoid pulling the
+// agents module into install-time code paths that don't need it. The five
+// IDE tools listed are the only targets that receive `bmad-agent-*` persona
+// skills post-22.6 (verified 2026-04-23 via scratch install).
+// F2b — copilot's skills directory was realigned from `.github/copilot/skills`
+// to `.github/skills` so it matches bmad-method 6.3.0's `github-copilot`
+// platform target_dir. Without this update F1a's prefix pass would walk a
+// directory that no longer receives the persona SKILL.md files.
+const TOOL_SKILL_DIRS = Object.freeze([
+    path.join('.claude', 'skills'),
+    path.join('.github', 'skills'),
+    path.join('.cline', 'skills'),
+    path.join('.roo', 'skills'),
+    path.join('.kilocode', 'skills'),
+]);
 
-    console.log(chalk.gray(`  Running: ${command}`));
-    try {
-        runCommand(command, { cwd: projectRoot, env: buildChildSpawnEnv() });
-    } catch (error) {
-        // Air-gapped / offline classification (bug-bmad-recompile-fails-on-airgapped-network).
-        // bmad-method 6.2.2 unconditionally performs `git fetch` / `git clone` / `npm install`
-        // against external module repos; on a disconnected host those calls throw and we used
-        // to swallow the error with a one-line red banner. Instead: classify the failure,
-        // downgrade to a warning when the vendored cache is intact, or surface an actionable
-        // error listing the missing modules and the remediation command.
-        const diagnosis = classifyRecompileFailure(error);
-        if (diagnosis.action === 'warn') {
-            console.warn(chalk.yellow(`  BMAD recompile warning (offline): ${diagnosis.message}`));
-        } else if (diagnosis.action === 'error') {
-            console.error(chalk.red(`  BMAD recompile failed: ${diagnosis.message}`));
-        } else {
-            console.error(chalk.red(`  BMAD recompile failed: ${diagnosis.message}`));
-        }
-    }
-
-    // STAGE:EXTENSION — Deploy BMAD extension module (AFTER recompile — extensions/ survives recompile)
-    // NOTE: Stage 1 deploys persona/menu customize.yaml to _bmad/_config/agents/ (consumed
-    // by BMAD's agent compilation). This stage deploys the extension module to
-    // _bmad/extensions/ma-agents-skills/ which adds critical_actions for skill loading.
-    // These are complementary paths: _config/agents/ drives agent recompilation (persona/menu),
-    // while extensions/ adds runtime behavior (critical_actions). BMAD does NOT merge them —
-    // they are consumed by different mechanisms. The 4 custom agents have persona/menu in both
-    // locations; this is intentional for backward compatibility during transition (Story 8.3).
-    const extensionSource = path.join(__dirname, 'bmad-extension');
-    const extensionTarget = path.join(projectRoot, BMAD_DIR, 'extensions', 'ma-agents-skills');
-    if (fs.existsSync(extensionSource)) {
-        await fs.ensureDir(extensionTarget);
-        await fs.copy(extensionSource, extensionTarget);
-        console.log(chalk.cyan('    + Deployed BMAD extension module: ma-agents-skills'));
-    }
-
-    // STAGE:CUSTOMIZE — Deploy built-in agent customizations from lib/bmad-customize/
-    // These add critical_actions to the 8 built-in BMM agents (pm, architect, dev, qa,
-    // sm, tech-writer, ux-designer, bmad-master) so they load project skills at startup.
-    // Runs AFTER --custom-content (extension module) and BEFORE quick-update.
-    // Post-deploy: phase:/on_prem_phase_prefix: keys are stripped for standard profile;
-    // for on-prem profile the prefix is injected as critical_actions[0] instead.
-    const customizeSource = path.join(__dirname, 'bmad-customize');
-    if (fs.existsSync(customizeSource)) {
-        await fs.ensureDir(configTargetDir);
-        const customizeFiles = (await fs.readdir(customizeSource)).filter(f => f.endsWith('.customize.yaml'));
-        for (const file of customizeFiles) {
-            await fs.copy(path.join(customizeSource, file), path.join(configTargetDir, file));
-            console.log(chalk.cyan(`    + Applied built-in customization: ${file}`));
-        }
-        const profile = require('./profile').getProfile(projectRoot) ?? 'standard';
-        await applyPersonaPhasePrefix(customizeSource, configTargetDir, profile);
-    }
-
-    // STAGE:WORKFLOWS — Apply workflows (AFTER recompile so they persist)
-    if (fs.existsSync(workflowSourceDir)) {
-        await fs.ensureDir(workflowTargetDir);
-        await fs.copy(workflowSourceDir, workflowTargetDir);
-        console.log(chalk.cyan(`    + Applied BMAD workflows`));
-    }
-
-    // 5. Apply MIL-STD-498 templates (AFTER recompile so they persist)
-    if (fs.existsSync(templateSourceDir)) {
-        await fs.ensureDir(templateTargetDir);
-        await fs.copy(templateSourceDir, templateTargetDir);
-        console.log(chalk.cyan(`    + Applied MIL-STD-498 templates`));
-    }
-
-    // 6. Copy agent templates to compiled location (AFTER recompile)
-    // BMAD recompile doesn't generate custom agents (mil498, cyber) in _bmad/bmm/agents/.
-    // Without this, updateAgentInstructions() creates the file with only the MA-AGENTS block.
-    if (fs.existsSync(sourceDir)) {
-        const compiledAgentDir = path.join(projectRoot, BMAD_DIR, 'bmm', 'agents');
-        await fs.ensureDir(compiledAgentDir);
-        const files = await fs.readdir(sourceDir);
-        for (const file of files) {
-            if (file.endsWith('.md')) {
-                const matchingAgentId = Object.entries(agentMdMap).find(([, mdFile]) => mdFile === file)?.[0];
-                if (!matchingAgentId || selectedAgentIds.length === 0 || selectedAgentIds.includes(matchingAgentId)) {
-                    await fs.copy(path.join(sourceDir, file), path.join(compiledAgentDir, file));
-                    console.log(chalk.cyan(`    + Applied compiled agent: ${file}`));
-                }
-            }
-        }
-    }
-
-    // 7. Register custom workflows in BMAD CSV registries (after recompile)
-    if (selectedAgentIds.length === 0 || selectedAgentIds.includes('bmm-mil498')) {
-        await registerMilWorkflows(projectRoot);
-    }
-
-    // 8. Register ML workflows
-    if (selectedAgentIds.length === 0 || selectedAgentIds.includes('bmm-demerzel')) {
-        await registerMlWorkflows(projectRoot);
-    }
+/**
+ * Build the marker-wrapped block that is injected into a persona SKILL.md.
+ * Kept as a single-source helper so the test assertions and the production
+ * code match byte-for-byte.
+ *
+ * @param {string} prefixText  The `on_prem_phase_prefix` from the customize YAML
+ * @returns {string}           Multi-line block with markers and trailing newline
+ */
+function buildOnPremPrefixBlock(prefixText) {
+    return [
+        ON_PREM_PREFIX_MARKER_BEGIN,
+        '## On-Prem Phase Prefix',
+        '',
+        prefixText,
+        ON_PREM_PREFIX_MARKER_END,
+        '',
+    ].join('\n');
 }
 
 /**
- * Append MIL-STD-498 workflow entries to the BMAD CSV registries
- * so they appear as available slash commands.
+ * Inject-or-replace the on-prem prefix block inside `skillContent`. Idempotent:
+ * a second call with the same prefix returns identical content.
+ *
+ * Placement rule:
+ *   - If an existing marker block is present, replace it in place (byte-stable).
+ *   - Otherwise, insert the new block immediately AFTER the YAML frontmatter
+ *     (the second `---` line) and BEFORE the rest of the markdown body.
+ *   - If no frontmatter exists, prepend the block.
+ *
+ * @param {string} skillContent  Current SKILL.md contents
+ * @param {string} prefixText    Prefix text to inject
+ * @returns {string}             Updated content
  */
-async function registerMilWorkflows(projectRoot) {
-    const milEntries = [
-        {
-            name: 'Generate SRS', code: 'GS',
-            file: '_bmad/bmm/workflows/mil498/srs/workflow.yaml',
-            command: 'bmad-mil-generate-srs',
-            description: 'Generate a MIL-STD-498 Software Requirements Specification from BMAD project artifacts'
-        },
-        {
-            name: 'Generate SDD', code: 'GD',
-            file: '_bmad/bmm/workflows/mil498/sdd/workflow.yaml',
-            command: 'bmad-mil-generate-sdd',
-            description: 'Generate a MIL-STD-498 Software Design Description from architecture and design docs'
-        },
-        {
-            name: 'Generate SDP', code: 'GP',
-            file: '_bmad/bmm/workflows/mil498/sdp/workflow.yaml',
-            command: 'bmad-mil-generate-sdp',
-            description: 'Generate a MIL-STD-498 Software Development Plan from project planning artifacts'
-        },
-        {
-            name: 'Generate OCD', code: 'GO',
-            file: '_bmad/bmm/workflows/mil498/ocd/workflow.yaml',
-            command: 'bmad-mil-generate-ocd',
-            description: 'Generate a MIL-STD-498 Operational Concept Description from PRD and architecture'
-        },
-        {
-            name: 'Generate SSS', code: 'SS',
-            file: '_bmad/bmm/workflows/mil498/sss/workflow.yaml',
-            command: 'bmad-mil-generate-sss',
-            description: 'Generate a MIL-STD-498 System/Subsystem Specification from project requirements'
-        },
-        {
-            name: 'Generate STD', code: 'GT',
-            file: '_bmad/bmm/workflows/mil498/std/workflow.yaml',
-            command: 'bmad-mil-generate-std',
-            description: 'Generate a MIL-STD-498 Software Test Description from epics stories and architecture'
-        },
-        {
-            name: 'Generate SSDD', code: 'SD',
-            file: '_bmad/bmm/workflows/mil498/ssdd/workflow.yaml',
-            command: 'bmad-mil-generate-ssdd',
-            description: 'Generate a MIL-STD-498 System/Subsystem Design Description from architecture and PRD'
-        }
-    ];
-
-    // Append or update entries in module-help.csv
-    const moduleHelpPath = path.join(projectRoot, BMAD_DIR, 'bmm', 'module-help.csv');
-    if (fs.existsSync(moduleHelpPath)) {
-        let content = await fs.readFile(moduleHelpPath, 'utf-8');
-        for (const entry of milEntries) {
-            const row = `bmm,anytime,${entry.name},${entry.code},,${entry.file},${entry.command},false,mil498,Create Mode,${entry.description},planning_artifacts,document,`;
-            // Remove any existing line for this command, then append the current one
-            const lines = content.split('\n').filter(line => !line.includes(entry.command));
-            content = lines.join('\n').trimEnd() + '\n' + row + '\n';
+function injectOnPremPrefixBlock(skillContent, prefixText) {
+    const block = buildOnPremPrefixBlock(prefixText);
+    const beginIdx = skillContent.indexOf(ON_PREM_PREFIX_MARKER_BEGIN);
+    if (beginIdx !== -1) {
+        const endIdx = skillContent.indexOf(ON_PREM_PREFIX_MARKER_END, beginIdx);
+        if (endIdx !== -1) {
+            const afterEnd = endIdx + ON_PREM_PREFIX_MARKER_END.length;
+            // Swallow the single trailing newline that belongs to the existing
+            // block so we don't accumulate blank lines on repeated runs.
+            const tail = skillContent[afterEnd] === '\n'
+                ? skillContent.slice(afterEnd + 1)
+                : skillContent.slice(afterEnd);
+            return skillContent.slice(0, beginIdx) + block + tail;
         }
-        await fs.writeFile(moduleHelpPath, content, 'utf-8');
-        console.log(chalk.cyan(`    + Registered MIL-STD-498 workflows in module-help.csv`));
-    }
-
-    // Append or update entries in bmad-help.csv
-    const bmadHelpPath = path.join(projectRoot, BMAD_DIR, '_config', 'bmad-help.csv');
-    if (fs.existsSync(bmadHelpPath)) {
-        let content = await fs.readFile(bmadHelpPath, 'utf-8');
-        for (const entry of milEntries) {
-            const row = `bmm,anytime,${entry.name},${entry.code},,${entry.file},${entry.command},false,mil498,bmad:MIL-STD-498 compliance:agent:mil498,Joseph,📜 MIL-STD-498 Expert,Create Mode,${entry.description},planning_artifacts,document`;
-            // Remove any existing line for this command, then append the current one
-            const lines = content.split('\n').filter(line => !line.includes(entry.command));
-            content = lines.join('\n').trimEnd() + '\n' + row + '\n';
+        // Malformed half-block (begin without end). Treat as fresh-insert below
+        // rather than silently corrupting the file further.
+    }
+
+    // Fresh insert. Place after frontmatter when present. Accept both LF
+    // and CRLF line endings — BMAD-deployed SKILL.md files are LF today
+    // (verified 2026-04-23), but operators on Windows may hand-edit with
+    // editors that rewrite to CRLF; we shouldn't corrupt their file.
+    const fmMatch = skillContent.match(/^---\r?\n/);
+    if (fmMatch) {
+        const searchFrom = fmMatch[0].length;
+        // Close delimiter may be `\n---\n` or `\r\n---\r\n`; match either.
+        const closeMatch = skillContent.slice(searchFrom).match(/\r?\n---\r?\n/);
+        if (closeMatch) {
+            const insertAt = searchFrom + closeMatch.index + closeMatch[0].length;
+            return skillContent.slice(0, insertAt) + '\n' + block + skillContent.slice(insertAt);
         }
-        await fs.writeFile(bmadHelpPath, content, 'utf-8');
-        console.log(chalk.cyan(`    + Registered MIL-STD-498 workflows in bmad-help.csv`));
     }
+    return block + skillContent;
 }
 
 /**
- * Append ML lifecycle workflow entries to the BMAD CSV registries
- * so they appear as available slash commands for Demerzel.
+ * F1a — post-install on-prem phase-prefix pass.
+ *
+ * For each persona with an `on_prem_phase_prefix` in the canonical customize
+ * source, locate the deployed `SKILL.md` in every tool skill-dir that exists
+ * under `projectRoot`, and inject the prefix block. No-op when `profile` is
+ * not `'on-prem'` so standard-profile installs never see on-prem content
+ * (NFR44 — bug spec edge-case 1).
+ *
+ * Invariants:
+ *   - Never creates a tool directory that the install didn't create first
+ *     (bug spec edge-case 2): missing dirs are skipped.
+ *   - Malformed YAML in the source is logged and that persona is skipped
+ *     (bug spec edge-case 3) — other personas still get their prefix.
+ *   - A persona skill that hasn't been deployed (e.g. copilot's per-bug-A
+ *     routing gap, or personas consolidated upstream) is a silent skip —
+ *     we don't invent files the deployer didn't emit (bug spec edge-case 4).
+ *   - Re-running against an already-prefixed file replaces the existing
+ *     marker block rather than stacking a second one (bug spec edge-case 5).
+ *
+ * @param {string} projectRoot        Absolute path to the install target
+ * @param {string} [profile]          Resolved profile value; only 'on-prem' acts
+ * @param {string} [customizeSourceDir]  Override for tests. Defaults to
+ *                                      `lib/bmad-customize/`.
+ * @returns {Promise<{ tool: string, persona: string, injected: boolean }[]>}
+ *          Per-file outcome list — useful for test assertions and operator logs
  */
-async function registerMlWorkflows(projectRoot) {
-    const mlEntries = [
-        { name: 'ML Ideation & PRD', code: 'MLI', command: 'ml-ideation', description: 'Frame ML research problem, define requirements, and produce Research Thesis and PRD' },
-        { name: 'ML EDA & Research', code: 'MLE', command: 'ml-eda', description: 'Perform exploratory data analysis, establish baselines, and produce EDA report' },
-        { name: 'ML Architecture Design', code: 'MLA', command: 'ml-architecture', description: 'Design model architecture, stack, and experiment tracking strategy' },
-        { name: 'ML Detailed Design', code: 'MLD', command: 'ml-detailed-design', description: 'Break down infrastructure and experiment tasks from architecture' },
-        { name: 'ML TechSpec (Contract)', code: 'MLS', command: 'ml-techspec', description: 'Lock experiment parameters and performance tiers before training' },
-        { name: 'ML Infra & Sync', code: 'MLNF', command: 'ml-infra', description: 'Build ML infrastructure, manage dependencies, and run smoke tests' },
-        { name: 'ML Experiment', code: 'MLX', command: 'ml-experiment', description: 'Execute training experiments against locked TechSpec and log metrics' },
-        { name: 'ML Results Analysis', code: 'MLAN', command: 'ml-analysis', description: 'Evaluate experiment outcomes against TechSpec success tiers' },
-        { name: 'ML HPO (Tuning)', code: 'MLH', command: 'ml-hparam', description: 'Perform automated hyperparameter optimization' },
-        { name: 'ML Iterative Revision', code: 'MLR', command: 'ml-revision', description: 'Amend hypothesis and requirements based on experiment findings' },
-        { name: 'ML Advise & Search', code: 'MLAD', command: 'ml-advise', description: 'Search past experiments and surface findings or failure warnings' },
-        { name: 'ML Retrospective', code: 'MLRT', command: 'ml-retrospective', description: 'Capture session learnings and update project context' }
-    ];
+async function applyOnPremPhasePrefixToDeployedSkills(
+    projectRoot,
+    profile,
+    customizeSourceDir = path.join(__dirname, 'bmad-customize'),
+) {
+    if (profile !== 'on-prem') {
+        return [];
+    }
+    if (!projectRoot || typeof projectRoot !== 'string') {
+        return [];
+    }
+    if (!fs.existsSync(customizeSourceDir)) {
+        return [];
+    }
 
-    // Append or update entries in module-help.csv
-    const moduleHelpPath = path.join(projectRoot, BMAD_DIR, 'bmm', 'module-help.csv');
-    if (fs.existsSync(moduleHelpPath)) {
-        let content = await fs.readFile(moduleHelpPath, 'utf-8');
-        for (const entry of mlEntries) {
-            const row = `bmm,anytime,${entry.name},${entry.code},,skills/${entry.command}/SKILL.md,${entry.command},false,bmm-demerzel,Create Mode,${entry.description},planning_artifacts,document,`;
-            // Remove any existing line for this command, then append the current one
-            const lines = content.split('\n').filter(line => !line.includes(entry.command));
-            content = lines.join('\n').trimEnd() + '\n' + row + '\n';
+    // Build the persona → prefix map once. Malformed sources are logged and
+    // skipped (bug spec edge-case 3).
+    const personaPrefix = new Map();
+    for (const [personaId, skillDirName] of Object.entries(PERSONA_SKILL_MAP)) {
+        const sourceFile = path.join(customizeSourceDir, `${personaId}.customize.yaml`);
+        if (!fs.existsSync(sourceFile)) continue;
+        let doc;
+        try {
+            doc = jsYaml.load(await fs.readFile(sourceFile, 'utf8'));
+        } catch (err) {
+            console.warn(chalk.yellow(
+                `  on-prem prefix: skipping ${personaId} — malformed source YAML: ${err.message}`
+            ));
+            continue;
         }
-        await fs.writeFile(moduleHelpPath, content, 'utf-8');
-        console.log(chalk.cyan(`    + Registered ML workflows in module-help.csv`));
-    }
-
-    // Append or update entries in bmad-help.csv
-    const bmadHelpPath = path.join(projectRoot, BMAD_DIR, '_config', 'bmad-help.csv');
-    if (fs.existsSync(bmadHelpPath)) {
-        let content = await fs.readFile(bmadHelpPath, 'utf-8');
-        for (const entry of mlEntries) {
-            const row = `bmm,anytime,${entry.name},${entry.code},,skills/${entry.command}/SKILL.md,${entry.command},false,bmm-demerzel,bmad:Machine Learning Lifecycle:agent:demerzel,Demerzel,🧪 ML Scientist,Create Mode,${entry.description},planning_artifacts,document`;
-            // Remove any existing line for this command, then append the current one
-            const lines = content.split('\n').filter(line => !line.includes(entry.command));
-            content = lines.join('\n').trimEnd() + '\n' + row + '\n';
+        if (!doc || typeof doc !== 'object') continue;
+        const prefix = doc.on_prem_phase_prefix;
+        if (typeof prefix !== 'string' || !prefix.trim()) continue;
+        personaPrefix.set(skillDirName, prefix);
+    }
+    if (personaPrefix.size === 0) return [];
+
+    const results = [];
+    for (const toolRel of TOOL_SKILL_DIRS) {
+        const toolSkillsDir = path.join(projectRoot, toolRel);
+        if (!fs.existsSync(toolSkillsDir)) continue; // tool not installed
+
+        for (const [skillDirName, prefix] of personaPrefix) {
+            const skillDir = path.join(toolSkillsDir, skillDirName);
+            const skillFile = path.join(skillDir, 'SKILL.md');
+            if (!fs.existsSync(skillFile)) {
+                // Persona not deployed for this tool — e.g. copilot routing gap
+                // (tracked separately). Do not invent files.
+                continue;
+            }
+            let content;
+            try {
+                content = await fs.readFile(skillFile, 'utf8');
+            } catch (err) {
+                console.warn(chalk.yellow(
+                    `  on-prem prefix: could not read ${skillFile}: ${err.message}`
+                ));
+                continue;
+            }
+            const updated = injectOnPremPrefixBlock(content, prefix);
+            if (updated === content) {
+                results.push({ tool: toolRel, persona: skillDirName, injected: false });
+                continue;
+            }
+            try {
+                await fs.writeFile(skillFile, updated, 'utf8');
+                results.push({ tool: toolRel, persona: skillDirName, injected: true });
+            } catch (err) {
+                console.warn(chalk.yellow(
+                    `  on-prem prefix: could not write ${skillFile}: ${err.message}`
+                ));
+            }
         }
-        await fs.writeFile(bmadHelpPath, content, 'utf-8');
-        console.log(chalk.cyan(`    + Registered ML workflows in bmad-help.csv`));
     }
+
+    if (results.some(r => r.injected)) {
+        const count = results.filter(r => r.injected).length;
+        console.log(chalk.cyan(`    + Injected on-prem phase prefix into ${count} persona SKILL.md file(s)`));
+    }
+    return results;
 }
 
+// Story 22.6 — `applyCustomizations()` removed. Its responsibilities are now
+// handled by bmad-method 6.3.0's PluginResolver, invoked via --custom-source
+// against the staged plugin bundle (see stagePlugin() above). The supporting
+// `registerMilWorkflows()` and `registerMlWorkflows()` helpers were removed
+// alongside it — their CSV registrations now ship in the plugin's own
+// `module-help.csv` and are merged by BMAD's installer.
+//
+// The ~290 lines of manifest-surgery, custom-agent-YAML staging, and CSV
+// rewriting that used to live here are gone — BMAD owns placement now.
+// Remaining helpers below (deployMethodology, prePopulateBmadCache, etc.) are
+// independent concerns invoked from installBmad()/updateBmad() directly.
+
 /**
  * Deploy the methodology presentation to the target project's _bmad-output/methodology/ directory.
  * Version-aware: skips if target is same or newer; overwrites only with --force.
@@ -1023,9 +1429,109 @@ async function prePopulateBmadCache(force = false) {
     }
 }
 
+// ── Canonical config helpers (Story 22.7) ───────────────────────────────────
+
+/**
+ * Read and parse the canonical v6.3.0 project config at `_bmad/bmm/config.yaml`.
+ *
+ * This is the ONLY sanctioned read path for BMAD-canonical values in ma-agents
+ * code. If the file is absent, this returns `null` — callers MUST NOT fall
+ * back silently to the legacy `_bmad/_config/manifest.yaml`. Callers that need
+ * to handle a legacy install should invoke `ensureCanonicalConfigLocation()`
+ * BEFORE reading so that the layout is normalized first.
+ *
+ * Malformed YAML logs a warning and returns `null` rather than throwing — the
+ * caller decides whether to error out or fall back to defaults.
+ *
+ * @param {string} projectRoot - Absolute path to the project root
+ * @returns {object|null} Parsed config object, or `null` when the file is
+ *   missing or unreadable.
+ */
+function readCanonicalBmadConfig(projectRoot) {
+    const configPath = path.join(projectRoot, CANONICAL_CONFIG_REL);
+    if (!fs.existsSync(configPath)) {
+        return null;
+    }
+    try {
+        const raw = fs.readFileSync(configPath, 'utf-8');
+        if (!raw.trim()) {
+            // Empty file — treat as "present but has no values".
+            return {};
+        }
+        const parsed = yaml.parse(raw);
+        // yaml.parse returns null for `{}` / empty-like content; normalize.
+        return parsed === null || parsed === undefined ? {} : parsed;
+    } catch (err) {
+        console.log(chalk.yellow(
+            `  Warning: failed to parse ${CANONICAL_CONFIG_REL}: ${err.message}`
+        ));
+        return null;
+    }
+}
+
+/**
+ * Migration shim: normalize the project layout so that canonical config lives
+ * at `_bmad/bmm/config.yaml` (v6.3.0) instead of `_bmad/_config/manifest.yaml`
+ * (legacy pre-6.3 location).
+ *
+ * Behavior (idempotent):
+ *  - Both files present:       PREFER_NEW — log that legacy exists, do nothing.
+ *      The new path already wins; operators can delete the legacy file at
+ *      their discretion. We never read it silently.
+ *  - Only new path present:    no-op (normal 6.3+ install).
+ *  - Only legacy path present: flag for migration — return the signal so the
+ *      caller can invoke bmad-method's installer to regenerate the new
+ *      layout. We deliberately DO NOT translate-in-place: the legacy manifest
+ *      schema differs from the new config schema (module list vs. shared
+ *      core+module sections), and a faithful translation requires upstream
+ *      knowledge we don't own.
+ *  - Neither present:          no-op (fresh install — bmad-method will create
+ *      the new layout).
+ *
+ * This function NEVER writes to the new path from legacy content and NEVER
+ * reads legacy content as a value source. Its sole job is to surface the
+ * drift signal so the caller can trigger regeneration via the normal install
+ * flow, which writes `_bmad/bmm/config.yaml` directly.
+ *
+ * @param {string} projectRoot - Absolute path to the project root
+ * @returns {{
+ *   newExists: boolean,
+ *   legacyExists: boolean,
+ *   needsRegeneration: boolean,
+ * }}
+ */
+function ensureCanonicalConfigLocation(projectRoot) {
+    const newPath = path.join(projectRoot, CANONICAL_CONFIG_REL);
+    const legacyPath = path.join(projectRoot, LEGACY_MANIFEST_REL);
+    const newExists = fs.existsSync(newPath);
+    const legacyExists = fs.existsSync(legacyPath);
+
+    if (newExists && legacyExists) {
+        // Drift state. New wins; warn once so operators notice the legacy
+        // file still lingering in `_bmad/_config/`. Story 22.6 removes the
+        // manifest-surgery code that was writing there, so this file becomes
+        // a non-participant after upgrade.
+        console.log(chalk.yellow(
+            `  Notice: legacy ${LEGACY_MANIFEST_REL} still present alongside ${CANONICAL_CONFIG_REL}. ` +
+            `The canonical v6.3.0 path is used; the legacy file is ignored and may be removed.`
+        ));
+        return { newExists: true, legacyExists: true, needsRegeneration: false };
+    }
+
+    if (!newExists && legacyExists) {
+        console.log(chalk.yellow(
+            `  Detected legacy BMAD config at ${LEGACY_MANIFEST_REL} with no ${CANONICAL_CONFIG_REL}. ` +
+            `bmad-method will regenerate the canonical v6.3.0 layout during install — legacy file is NOT read as a fallback.`
+        ));
+        return { newExists: false, legacyExists: true, needsRegeneration: true };
+    }
+
+    return { newExists, legacyExists: false, needsRegeneration: false };
+}
+
 // ── Migration constants ─────────────────────────────────────────────────────
 
-const BMAD_TARGET_VERSION = '6.2.2';
+const BMAD_TARGET_VERSION = '6.5.0';
 const BMAD_MIGRATION_THRESHOLD = '6.2.0'; // versions below this need migration
 const BACKUP_DIR_NAME = '.backup-pre-migration';
 
@@ -1255,12 +1761,440 @@ function parseCustomizeYaml(content) {
     return result;
 }
 
+// ─── F1b: Legacy→plugin-bundle translation for upgrade migration ────────────
+//
+// Pre-6.3.0 ma-agents deployed `*.customize.yaml` files to `_bmad/_config/agents/`
+// where BMAD's agent-compilation read persona/memories/critical_actions and
+// injected them into the compiled agent prompts. Story 22.6 removed that
+// compilation step and now delegates placement to bmad-method 6.3.0's
+// PluginResolver via `--custom-source`. Result: `_bmad/_config/agents/` is no
+// longer a deployment target — the deployed LLM-readable skills live at
+// `<tool-skillsDir>/bmad-agent-<name>/SKILL.md` (for bmm-* personas BMAD
+// itself deploys) and `<tool-skillsDir>/ma-agent-<name>/SKILL.md` (for the
+// ma-agents-owned custom agents bundled in our plugin).
+//
+// Consequence: on upgrade from pre-6.3, simply merging user edits back into
+// `_bmad/_config/agents/` silently strands them. This translator bridges the
+// gap by parsing legacy `.customize.yaml` backups and appending user-edited
+// content to the deployed `SKILL.md` files with idempotency markers so
+// repeated runs do not duplicate content.
+
+/**
+ * Block marker used to delimit translated user customizations inside a
+ * deployed SKILL.md file. Stable across runs so the translator can detect
+ * a prior apply and replace the block rather than appending a second copy.
+ * Public so tests can locate the block deterministically.
+ */
+const MA_CUSTOMIZATIONS_MARKER_START = '<!-- ma-agents:user-customizations:start -->';
+const MA_CUSTOMIZATIONS_MARKER_END = '<!-- ma-agents:user-customizations:end -->';
+
+/**
+ * Diagnostic directory where legacy `.customize.yaml` files are preserved when
+ * they contain fields that cannot be translated to the plugin-bundle format.
+ * Kept under `_bmad/` so it survives across installs and is discoverable by
+ * users looking for their pre-upgrade customizations.
+ *
+ * Stored as a forward-slash string (not `path.join`) so it is stable across
+ * Windows and POSIX in user-facing log output; callers that need a
+ * filesystem path should still pass it through `path.join`/`path.resolve`
+ * which normalize mixed separators on Windows.
+ */
+const LEGACY_CUSTOMIZATIONS_DIR = '_bmad/.ma-agents-customizations-legacy';
+
+/**
+ * Map a legacy `.customize.yaml` filename (e.g. `bmm-pm.customize.yaml`) to the
+ * set of candidate deployed skill directory names. Legacy files targeted the
+ * pre-6.3 BMAD persona IDs (`bmm-<name>`); v6.3.0 deploys those personas as
+ * plugin skills named `bmad-agent-<name>` and ma-agents-owned personas as
+ * `ma-agent-<name>`. Both candidates are returned so the translator can
+ * overlay whichever the upstream installer actually produced.
+ *
+ * @param {string} customizeFilename - e.g. `bmm-pm.customize.yaml`
+ * @returns {string[]} Candidate skill directory names ordered by preference
+ */
+function getCandidateSkillDirNames(customizeFilename) {
+    const base = customizeFilename.replace(/\.customize\.yaml$/, '');
+    // `generic.customize.yaml` targeted a non-persona umbrella file that
+    // BMAD 6.3.0 does not deploy — no skill candidate.
+    if (base === 'generic') return [];
+    // `bmm-<name>` legacy → `bmad-agent-<name>` (BMAD core) or `ma-agent-<name>`
+    // (ma-agents plugin, for cyber/devops/sqa/sre/ml which used bmm-<name>
+    // legacy filenames but are now owned by our plugin).
+    if (base.startsWith('bmm-')) {
+        const suffix = base.slice('bmm-'.length);
+        return [`bmad-agent-${suffix}`, `ma-agent-${suffix}`];
+    }
+    // Already in `ma-agent-*` form → pass through.
+    if (base.startsWith('ma-agent-')) return [base];
+    // Unknown prefix — try as-is and as a `ma-agent-<id>` variant.
+    return [base, `ma-agent-${base}`];
+}
+
+/**
+ * Enumerate the IDE/BMAD tool skill directories that may contain deployed
+ * persona skills. Reads from `lib/agents.js` so the list stays in lockstep
+ * with the installer's own fan-out (Story 22.10). Returns absolute paths to
+ * directories that actually exist on disk; non-existent tool dirs are
+ * silently skipped (the tool was not selected for install).
+ *
+ * @param {string} projectRoot - Absolute path to the project root
+ * @returns {string[]} Absolute skills-dir paths that exist
+ */
+function getDeployedSkillsRoots(projectRoot) {
+    const agentsModule = require('./agents');
+    const roots = new Set();
+    for (const agent of agentsModule.getAllAgents()) {
+        if (!agent || !agent.skillsDir) continue;
+        const abs = path.resolve(projectRoot, agent.skillsDir);
+        if (fs.existsSync(abs) && fs.statSync(abs).isDirectory()) {
+            roots.add(abs);
+        }
+    }
+    return [...roots];
+}
+
+/**
+ * Build the translated markdown block to append to a deployed SKILL.md.
+ * Encodes legacy user edits as a clearly-labelled section between the
+ * ma-customizations markers. Pure string building — no filesystem access.
+ *
+ * Translation policy:
+ *   - `memories[]` → bullet list under "### User Memories"
+ *   - `critical_actions[]` (non-standard only) → numbered list under
+ *     "### Additional Critical Actions (from pre-6.3 customization)"
+ *   - `persona.*` lines (raw YAML child lines) → fenced YAML block under
+ *     "### User Persona Overrides" so users can re-apply manually; we do
+ *     NOT rewrite the deployed persona narrative (bmad-method v6.3.0 owns
+ *     that content in SKILL.md's Identity/Communication Style sections).
+ *
+ * @param {object} parsed - Output of parseCustomizeYaml()
+ * @param {string} sourceFilename - Original `.customize.yaml` name, for trace
+ * @returns {{ block: string, droppedFields: string[] }}
+ */
+function buildCustomizationsMarkdownBlock(parsed, sourceFilename) {
+    // Defang our own marker literals inside user-originated text BEFORE
+    // interpolating it into the block template. A user memory/critical-
+    // action/persona line that contains the literal marker would otherwise
+    // let an attacker (or accidental copy-paste) break out of the block
+    // and either swallow content during idempotent replace or inject
+    // instructions outside the "this is user-migrated content" region.
+    // A zero-width space inside the `ma-agents:` prefix is invisible to the
+    // LLM's reader but disambiguates the string from our real markers.
+    const defang = (s) => {
+        if (typeof s !== 'string') return s;
+        return s.replace(
+            /<!--\s*ma-agents:user-customizations:(start|end)\s*-->/g,
+            '<!-- ma-agents\u200B:user-customizations:$1 -->'
+        );
+    };
+
+    const lines = [];
+    lines.push(MA_CUSTOMIZATIONS_MARKER_START);
+    lines.push('');
+    lines.push(`## User Customizations (migrated from ${defang(sourceFilename)})`);
+    lines.push('');
+    lines.push('> Auto-migrated by ma-agents on upgrade to plugin-bundle format.');
+    lines.push('> Edit this block directly or re-run `ma-agents install` after');
+    lines.push(`> updating \`${defang(sourceFilename)}\` in \`${LEGACY_CUSTOMIZATIONS_DIR}/\`.`);
+    lines.push('');
+
+    // User-added memories (always user content).
+    if (parsed.memories && parsed.memories.length > 0) {
+        lines.push('### User Memories');
+        lines.push('');
+        for (const memory of parsed.memories) {
+            lines.push(`- ${defang(memory)}`);
+        }
+        lines.push('');
+    }
+
+    // Non-standard critical_actions — filter out the standard ma-agents set
+    // so upgrade does not duplicate what bmad-method already ships.
+    const userCriticalActions = (parsed.criticalActions || []).filter(
+        ca => !isStandardCriticalAction(ca)
+    );
+    if (userCriticalActions.length > 0) {
+        lines.push('### Additional Critical Actions');
+        lines.push('');
+        userCriticalActions.forEach((ca, idx) => {
+            lines.push(`${idx + 1}. ${defang(ca)}`);
+        });
+        lines.push('');
+    }
+
+    // Persona overrides — preserve as raw YAML because we cannot safely
+    // rewrite the persona narrative without breaking the bmad-method-owned
+    // SKILL.md structure. Users can read and re-apply as needed.
+    const droppedFields = [];
+    if (parsed.personaLines && parsed.personaLines.length > 0) {
+        lines.push('### User Persona Overrides');
+        lines.push('');
+        lines.push('> NOTE: v6.3.0 deploys persona text directly in SKILL.md above.');
+        lines.push('> These legacy overrides are preserved verbatim — review and');
+        lines.push('> edit the persona sections above if you want them active.');
+        lines.push('');
+        lines.push('```yaml');
+        lines.push('persona:');
+        for (const ln of parsed.personaLines) {
+            lines.push(defang(ln));
+        }
+        lines.push('```');
+        lines.push('');
+        droppedFields.push('persona (preserved as read-only YAML; v6.3.0 persona schema differs)');
+    }
+
+    lines.push(MA_CUSTOMIZATIONS_MARKER_END);
+    return { block: lines.join('\n'), droppedFields };
+}
+
+/**
+ * Apply the translated block to a single SKILL.md file. Idempotent: if the
+ * file already contains a marker block, it is replaced in place; otherwise
+ * the block is appended with a single blank line of separation. Writes are
+ * skipped when the existing block byte-matches the incoming block (repeated
+ * runs do not bump mtime).
+ *
+ * @param {string} skillFile - Absolute path to the SKILL.md
+ * @param {string} block - Translated markdown block (with markers)
+ * @returns {Promise<boolean>} true if the file was written, false if no-op
+ */
+async function applyCustomizationsBlockToSkill(skillFile, block) {
+    const existing = await fs.readFile(skillFile, 'utf-8');
+    const startIdx = existing.indexOf(MA_CUSTOMIZATIONS_MARKER_START);
+    const endIdx = existing.indexOf(MA_CUSTOMIZATIONS_MARKER_END);
+    let next;
+    if (startIdx !== -1 && endIdx !== -1 && endIdx > startIdx) {
+        // Replace existing block (idempotent on second run).
+        const before = existing.slice(0, startIdx);
+        const after = existing.slice(endIdx + MA_CUSTOMIZATIONS_MARKER_END.length);
+        next = `${before.trimEnd()}\n\n${block}\n${after.trimStart() ? '\n' + after.trimStart() : ''}`;
+    } else {
+        // Append with separation.
+        next = `${existing.trimEnd()}\n\n${block}\n`;
+    }
+    if (next === existing) return false;
+    await fs.writeFile(skillFile, next, 'utf-8');
+    return true;
+}
+
+/**
+ * Translate user-edited legacy `.customize.yaml` files into appended blocks
+ * on the deployed SKILL.md files across every tool skills-dir. Non-destructive
+ * (wraps edits in marker block), idempotent (re-runs replace the block), and
+ * preserves the original legacy file alongside so users can diff/inspect.
+ *
+ * @param {string} projectRoot - Absolute path to the project root
+ * @returns {Promise<{
+ *   translated: Array<{ file: string, skillFiles: string[] }>,
+ *   preserved: string[],
+ *   warnings: string[],
+ *   noTargetFound: string[],
+ * }>}
+ */
+async function translateUserCustomizations(projectRoot) {
+    const backupDir = path.join(projectRoot, CONFIG_DIR, BACKUP_DIR_NAME);
+    const legacyPreserveDir = path.join(projectRoot, LEGACY_CUSTOMIZATIONS_DIR);
+    const result = {
+        translated: [],
+        preserved: [],
+        warnings: [],
+        noTargetFound: [],
+    };
+
+    if (!fs.existsSync(backupDir)) {
+        return result;
+    }
+
+    // Enumerate `.customize.yaml` entries but verify each is a regular file.
+    // A directory or symlink-to-directory named with the suffix would otherwise
+    // trigger a spurious "malformed" warning and pointless preservation on
+    // every run — skip silently at the source.
+    const backupEntries = await fs.readdir(backupDir, { withFileTypes: true });
+    const backupFiles = backupEntries
+        .filter(d => d.isFile() && d.name.endsWith('.customize.yaml'))
+        .map(d => d.name);
+    if (backupFiles.length === 0) {
+        return result;
+    }
+
+    /**
+     * Recognized top-level keys in a legacy `.customize.yaml`. Anything else
+     * the user added (e.g. `extra_config`) cannot be translated without a
+     * field-level mapping and is surfaced as a drop warning.
+     */
+    const KNOWN_TOP_LEVEL_KEYS = new Set([
+        'memories', 'critical_actions', 'persona',
+        // Epic 21 / Story 21.7 keys (handled by F1a, safe to ignore here):
+        'phase', 'on_prem_phase_prefix',
+    ]);
+
+    const deployedSkillsRoots = getDeployedSkillsRoots(projectRoot);
+    if (deployedSkillsRoots.length === 0) {
+        result.warnings.push(
+            'No deployed tool skills directories found under projectRoot — ' +
+            'customizations preserved for manual reapplication.'
+        );
+    }
+
+    // Resolve shipped customize defaults so we can tell which legacy files
+    // represent actual user edits vs. verbatim-shipped defaults that the
+    // user never touched. If the user never edited the file, we skip
+    // translation entirely (no noise on the deployed SKILL.md).
+    const shippedDir = path.join(__dirname, 'bmad-customize');
+
+    for (const file of backupFiles) {
+        const backupPath = path.join(backupDir, file);
+        let parsed;
+        try {
+            const backupContent = await fs.readFile(backupPath, 'utf-8');
+            parsed = parseCustomizeYaml(backupContent);
+        } catch (err) {
+            // Edge-case: legacy file malformed — log and continue so other
+            // files still migrate. Preserves user data by copying the raw
+            // file to the diagnostic directory.
+            result.warnings.push(
+                `Skipped malformed legacy file ${file}: ${err.message}`
+            );
+            try {
+                await fs.ensureDir(legacyPreserveDir);
+                await fs.copy(backupPath, path.join(legacyPreserveDir, file), { overwrite: true });
+                result.preserved.push(file);
+            } catch { /* best-effort preservation */ }
+            continue;
+        }
+
+        // Scan the raw YAML for unknown top-level keys (user added a custom
+        // field that cannot be translated). Surface as a non-blocking warning
+        // so the user knows to re-apply manually from the preserved file.
+        const unknownKeys = [];
+        for (const line of (parsed.raw || '').split('\n')) {
+            const m = line.match(/^([a-z_][a-z0-9_]*)\s*:/);
+            if (m && !KNOWN_TOP_LEVEL_KEYS.has(m[1])) {
+                if (!unknownKeys.includes(m[1])) unknownKeys.push(m[1]);
+            }
+        }
+
+        // Detect user content vs. shipped defaults.
+        const userMemories = parsed.memories || [];
+        const userCriticalActions = (parsed.criticalActions || []).filter(
+            ca => !isStandardCriticalAction(ca)
+        );
+        let hasPersonaOverride = false;
+        const shippedPath = path.join(shippedDir, file);
+        if (fs.existsSync(shippedPath)) {
+            try {
+                const shippedContent = await fs.readFile(shippedPath, 'utf-8');
+                const shippedParsed = parseCustomizeYaml(shippedContent);
+                if (
+                    parsed.personaLines.join('\n').trim() !==
+                        shippedParsed.personaLines.join('\n').trim() &&
+                    parsed.personaLines.length > 0
+                ) {
+                    hasPersonaOverride = true;
+                }
+            } catch {
+                // If shipped default unreadable, treat any persona content as user edit.
+                if (parsed.personaLines.length > 0) hasPersonaOverride = true;
+            }
+        } else if (parsed.personaLines.length > 0) {
+            hasPersonaOverride = true;
+        }
+
+        const hasUserContent =
+            userMemories.length > 0 ||
+            userCriticalActions.length > 0 ||
+            hasPersonaOverride ||
+            unknownKeys.length > 0;
+        if (!hasUserContent) continue;
+
+        // Build the translated block using only user-originated content.
+        const userParsed = {
+            memories: userMemories,
+            criticalActions: userCriticalActions,
+            // Only attach personaLines if the user actually overrode them,
+            // so unchanged shipped persona defaults don't leak into the block.
+            personaLines: hasPersonaOverride ? parsed.personaLines : [],
+        };
+        const { block, droppedFields } = buildCustomizationsMarkdownBlock(userParsed, file);
+
+        // Fan out to every candidate skill dir across every installed tool.
+        const candidates = getCandidateSkillDirNames(file);
+        const skillFilesTouched = [];
+        for (const root of deployedSkillsRoots) {
+            for (const skillDirName of candidates) {
+                const skillFile = path.join(root, skillDirName, 'SKILL.md');
+                if (!fs.existsSync(skillFile)) continue;
+                try {
+                    // Return value (changed/no-op) is intentionally ignored —
+                    // for the summary we report coverage, not mtime bumps.
+                    // Idempotent re-runs report the same skill file list.
+                    await applyCustomizationsBlockToSkill(skillFile, block);
+                    skillFilesTouched.push(skillFile);
+                } catch (err) {
+                    result.warnings.push(
+                        `Failed to apply translation to ${skillFile}: ${err.message}`
+                    );
+                }
+            }
+        }
+
+        // Always preserve the legacy file so the user can diff/re-apply, and
+        // emit a dropped-field warning if any field could not translate 1:1.
+        try {
+            await fs.ensureDir(legacyPreserveDir);
+            await fs.copy(backupPath, path.join(legacyPreserveDir, file), { overwrite: true });
+            if (!result.preserved.includes(file)) result.preserved.push(file);
+        } catch (err) {
+            result.warnings.push(
+                `Could not preserve legacy file ${file} at ${legacyPreserveDir}: ${err.message}`
+            );
+        }
+
+        if (droppedFields.length > 0) {
+            result.warnings.push(
+                `${file}: ${droppedFields.length} field(s) need manual review — ` +
+                `${droppedFields.join(', ')} — see ${LEGACY_CUSTOMIZATIONS_DIR}/${file}`
+            );
+        }
+
+        if (unknownKeys.length > 0) {
+            result.warnings.push(
+                `${file}: unknown top-level key(s) [${unknownKeys.join(', ')}] ` +
+                `have no plugin-bundle equivalent — original preserved at ` +
+                `${LEGACY_CUSTOMIZATIONS_DIR}/${file}`
+            );
+        }
+
+        if (skillFilesTouched.length === 0) {
+            // No deployed target matched this legacy file — user customizations
+            // could not reach any live skill. Non-blocking but visible.
+            result.noTargetFound.push(file);
+            result.warnings.push(
+                `${file}: no deployed SKILL.md matched candidates ` +
+                `[${candidates.join(', ')}] — reapply manually from ` +
+                `${LEGACY_CUSTOMIZATIONS_DIR}/${file}`
+            );
+        } else {
+            result.translated.push({ file, skillFiles: skillFilesTouched });
+        }
+    }
+
+    return result;
+}
+
 /**
  * Merge user customizations from backed-up files into new customize.yaml files.
  * Detects user-added memories, extra critical_actions, and persona overrides.
  *
+ * As of F1b: after the legacy-format merge, also invokes
+ * {@link translateUserCustomizations} so the user's edits reach the deployed
+ * plugin-bundle SKILL.md files. The legacy-format write is retained for
+ * backward compatibility with installs that still read `_bmad/_config/agents/`
+ * (e.g. the hash-comparison path in bmad-method 6.3.0's installer.js@2706)
+ * and for diagnostic visibility.
+ *
  * @param {string} projectRoot - Absolute path to the project root
- * @returns {Promise<{ merged: string[], skipped: string[] }>}
+ * @returns {Promise<{ merged: string[], skipped: string[], translation?: object }>}
  */
 async function mergeUserCustomizations(projectRoot) {
     const configDir = path.join(projectRoot, CONFIG_DIR);
@@ -1412,6 +2346,49 @@ async function mergeUserCustomizations(projectRoot) {
         console.log(chalk.gray(`  ${result.skipped.length} file(s) had no user customizations to merge`));
     }
 
+    // F1b: translate user edits to the plugin-bundle format so they reach the
+    // deployed SKILL.md files. The legacy merge above keeps
+    // `_bmad/_config/agents/` consistent (for bmad-method's own hash-compare
+    // path) but the LLM-readable skills live in `<tool>/skills/`; this is the
+    // load-bearing step on upgrade.
+    try {
+        const translation = await translateUserCustomizations(projectRoot);
+        result.translation = translation;
+
+        if (translation.translated.length > 0) {
+            const totalSkillFiles = translation.translated.reduce(
+                (acc, t) => acc + t.skillFiles.length, 0
+            );
+            console.log(chalk.green(
+                `  Translated ${translation.translated.length} customization(s) ` +
+                `to ${totalSkillFiles} deployed SKILL.md file(s)`
+            ));
+        }
+        if (translation.preserved.length > 0) {
+            console.log(chalk.gray(
+                `  Preserved ${translation.preserved.length} legacy customize.yaml ` +
+                `file(s) at ${LEGACY_CUSTOMIZATIONS_DIR}/ for manual review`
+            ));
+        }
+        for (const warning of translation.warnings) {
+            console.log(chalk.yellow(`  ! ${warning}`));
+        }
+        if (translation.noTargetFound.length > 0) {
+            console.log(chalk.yellow(
+                `  Summary: ${translation.translated.length} customization(s) migrated; ` +
+                `${translation.noTargetFound.length} require manual reapplication — ` +
+                `see ${LEGACY_CUSTOMIZATIONS_DIR}/`
+            ));
+        }
+    } catch (err) {
+        // Translation failures are non-blocking: the legacy merge already ran,
+        // and the preserved backup gives the user a path to re-apply by hand.
+        console.log(chalk.yellow(
+            `  ! Customization translation failed: ${err.message} — ` +
+            `legacy files preserved at ${BACKUP_DIR_NAME}/`
+        ));
+    }
+
     return result;
 }
 
@@ -1509,11 +2486,24 @@ function restoreGitDir(moduleDir) {
 module.exports = {
     isBmadInstalled,
     buildBmadArgs,
+    resolveCustomContentFlag,
     installBmad,
     updateBmad,
-    applyCustomizations,
     prePopulateBmadCache,
     deployMethodology,
+    // Story 22.7 — canonical config (_bmad/bmm/config.yaml) helpers
+    readCanonicalBmadConfig,
+    ensureCanonicalConfigLocation,
+    CANONICAL_CONFIG_REL,
+    LEGACY_MANIFEST_REL,
+    // Story 22.6 — stage-and-invoke helpers (exported for unit tests)
+    stagePlugin,
+    cleanupStage,
+    PLUGIN_STAGE_DIR_NAME,
+    // F2a — Story 22.8 gitignore policy (project-root only). Exported so the
+    // regression test can invoke it directly without spinning up the full
+    // CLI / bmad-method pipeline.
+    ensurePluginStageGitignoredForProject,
     // Migration functions (exported for testing)
     detectMigrationNeed,
     compareVersions,
@@ -1522,9 +2512,26 @@ module.exports = {
     mergeUserCustomizations,
     cleanupLegacyArtifacts,
     parseCustomizeYaml,
-    registerMlWorkflows,
+    // F1b — exported for unit/integration tests
+    translateUserCustomizations,
+    buildCustomizationsMarkdownBlock,
+    applyCustomizationsBlockToSkill,
+    getCandidateSkillDirNames,
+    getDeployedSkillsRoots,
+    MA_CUSTOMIZATIONS_MARKER_START,
+    MA_CUSTOMIZATIONS_MARKER_END,
+    LEGACY_CUSTOMIZATIONS_DIR,
     // Story 21.7 — phase-aware persona prefix (exported for testing)
     applyPersonaPhasePrefix,
+    // F1a — on-prem persona phase-prefix restoration post-22.6
+    // (exported for integration testing)
+    applyOnPremPhasePrefixToDeployedSkills,
+    injectOnPremPrefixBlock,
+    buildOnPremPrefixBlock,
+    PERSONA_SKILL_MAP,
+    TOOL_SKILL_DIRS,
+    ON_PREM_PREFIX_MARKER_BEGIN,
+    ON_PREM_PREFIX_MARKER_END,
     // Offline-safe recompile helpers (exported for testing — see bug
     // bug-bmad-recompile-fails-on-airgapped-network)
     isOfflineModeDeclared,