wizz-method 2.0.0 → 2.1.0

package/tools/installer/core/manifest.js

@@ -3,7 +3,6 @@ const https = require('node:https');
 const { execFile } = require('node:child_process');
 const { promisify } = require('node:util');
 const fs = require('../fs-native');
-const crypto = require('node:crypto');
 const { resolveModuleVersion } = require('../modules/version-resolver');
 const prompts = require('../prompts');
 
@@ -317,17 +316,14 @@ class Manifest {
   }
 
   /**
-   * Calculate SHA256 hash of a file
+   * Calculate SHA256 hash of a file. Delegates to the single canonical
+   * implementation in fs-native.js (memoized by path+size+mtime within the
+   * same process) — see F06/F10 in the 2026-09-11 audit.
    * @param {string} filePath - Path to file
-   * @returns {string} SHA256 hash
+   * @returns {string|null} SHA256 hash, or null if the file can't be read
    */
   async calculateFileHash(filePath) {
-    try {
-      const content = await fs.readFile(filePath);
-      return crypto.createHash('sha256').update(content).digest('hex');
-    } catch {
-      return null;
-    }
+    return fs.calculateFileHash(filePath);
   }
 
   /**
@@ -445,33 +441,41 @@ class Manifest {
   async checkForUpdates(wizzDir) {
     const semver = require('semver');
     const modules = await this.getAllModuleVersions(wizzDir);
-    const updates = [];
 
-    for (const module of modules) {
-      if (!module.npmPackage) {
-        continue; // Skip modules without npm package (built-in)
-      }
-
-      const latestVersion = await this.fetchNpmVersion(module.npmPackage);
-      if (!latestVersion) {
-        continue;
-      }
+    // One npm lookup per module (subprocess + HTTPS fallback, 10s timeout
+    // each) has no dependency between iterations, so resolve them all
+    // concurrently instead of N sequential round-trips (F04). fetchNpmVersion
+    // never throws — it already resolves to null on any per-module failure —
+    // so a single module's error can't sink the others, and Promise.all
+    // preserves `modules` order in `results` regardless of resolution timing.
+    const results = await Promise.all(
+      modules.map(async (module) => {
+        if (!module.npmPackage) {
+          return null; // Skip modules without npm package (built-in)
+        }
 
-      const installedVersion = semver.valid(module.version) || semver.valid(semver.coerce(module.version || ''));
-      const availableVersion = semver.valid(latestVersion) || semver.valid(semver.coerce(latestVersion));
+        const latestVersion = await this.fetchNpmVersion(module.npmPackage);
+        if (!latestVersion) {
+          return null;
+        }
 
-      if (installedVersion && availableVersion && semver.gt(availableVersion, installedVersion)) {
-        updates.push({
-          name: module.name,
-          installedVersion: module.version,
-          latestVersion: latestVersion,
-          npmPackage: module.npmPackage,
-          updateAvailable: true,
-        });
-      }
-    }
+        const installedVersion = semver.valid(module.version) || semver.valid(semver.coerce(module.version || ''));
+        const availableVersion = semver.valid(latestVersion) || semver.valid(semver.coerce(latestVersion));
+
+        if (installedVersion && availableVersion && semver.gt(availableVersion, installedVersion)) {
+          return {
+            name: module.name,
+            installedVersion: module.version,
+            latestVersion: latestVersion,
+            npmPackage: module.npmPackage,
+            updateAvailable: true,
+          };
+        }
+        return null;
+      }),
+    );
 
-    return updates;
+    return results.filter(Boolean);
   }
 }
 

package/tools/installer/core/module-config-writer.js

@@ -25,7 +25,10 @@ async function generateModuleConfigs(wizzDir, moduleConfigs, { trackFile }) {
 
   // Get all installed module directories
   const entries = await fs.readdir(wizzDir, { withFileTypes: true });
-  const nonModuleDirs = new Set(['_config', '_memory', 'memory', 'docs', 'scripts', 'custom']);
+  // 'hooks' (RT-C1, tools/hooks/* copied here by Installer#_installHooks) is
+  // infra, not a module — without this exclusion this scanner treated it as
+  // one and wrote a spurious _wizz/hooks/config.yaml.
+  const nonModuleDirs = new Set(['_config', '_memory', 'memory', 'docs', 'scripts', 'custom', 'hooks']);
   const installedModules = entries.filter((entry) => entry.isDirectory() && !nonModuleDirs.has(entry.name)).map((entry) => entry.name);
 
   // Generate config.yaml for each installed module

package/tools/installer/core/python-check.js

@@ -1,16 +1,27 @@
 const { spawnSync } = require('node:child_process');
 const prompts = require('../prompts');
 
-// Python 3.11 added stdlib `tomllib` (PEP 680), which the shared scripts in
-// src/scripts/ (resolve_config.py, resolve_customization.py) require to read
-// WIZZ's TOML config files. memlog.py is more lenient and runs on 3.8+.
+// Since audit item 29 (2026-09-12) Node 20.12+ is the ONLY prerequisite of the
+// Wizz core: memlog is Node (src/scripts/memlog.js), and every TOML merge the
+// core needs is resolved at install time into `_wizz/_resolved/` by the
+// installer's own smol-toml resolver. Python is now optional and belongs to
+// the BMAD skills that ship their own Python scripts.
+//
+// The version bands stay as they are because those skill-owned scripts still
+// read TOML: Python 3.11 added stdlib `tomllib` (PEP 680), and the older
+// scripts run on 3.8+.
 const PYTHON_FULL_SUPPORT = { major: 3, minor: 11 };
 const PYTHON_PARTIAL_SUPPORT = { major: 3, minor: 8 };
 
-// Every runtime call site (skill steps, on_complete hooks) invokes a literal
-// `python3`, so only that command's version vouches for WIZZ features. The
-// fallback probes exist to tell the user "Python is installed, but not under
-// the name WIZZ uses" instead of a misleading "No Python found".
+// The skills that stop working without `python3` — named explicitly so the
+// warning says what the user loses instead of a vague "some features".
+const PYTHON_ONLY_SKILLS =
+  'wizz-brainstorming, wizz-retrospective, wizz-sprint-planning, wizz-architecture, wizz-party-mode, wizz-forge-idea, wizz-advanced-elicitation, wizz-customize';
+
+// Every skill-owned call site invokes a literal `python3`, so only that
+// command's version vouches for those skills. The fallback probes exist to
+// tell the user "Python is installed, but not under the name WIZZ uses"
+// instead of a misleading "No Python found".
 const RUNTIME_COMMAND = 'python3';
 const PROBE_CANDIDATES =
   process.platform === 'win32'
@@ -108,7 +119,7 @@ function detectPython() {
 
 function upgradeHints() {
   return [
-    'How to get Python 3.11+ (as `python3`):',
+    'How to get Python 3.11+ (as `python3`), if you want those skills:',
     '  macOS:        brew install python3',
     '  Windows:      winget install Python.Python.3.12  (then ensure `python3` resolves, e.g. enable the python3 alias)',
     '  Linux/WSL:    sudo apt install python3  (Ubuntu 24.04+ ships 3.12; older distros: use pyenv or deadsnakes)',
@@ -117,83 +128,69 @@ function upgradeHints() {
 }
 
 /**
- * Check the local Python environment and warn about degraded WIZZ features.
+ * One line saying exactly what a degraded Python means, per detection case.
+ * @param {'full'|'partial'|'unsupported'|'none'} status
+ * @param {Object|null} detected
+ * @returns {string}
+ */
+function degradedMessage(status, detected) {
+  if (detected && !detected.isRuntimeCommand) {
+    return (
+      `Python ${detected.version.raw} found via \`${detected.command}\`, but the skill scripts invoke \`python3\`, which is not on PATH.\n` +
+      `The Wizz core is unaffected (Node only). These skills stay unavailable until \`python3\` resolves: ${PYTHON_ONLY_SKILLS}.`
+    );
+  }
+  if (status === 'partial') {
+    return (
+      `Python ${detected.version.raw} detected (${detected.command}) — the skill scripts that read TOML need Python 3.11+ (stdlib tomllib).\n` +
+      `The Wizz core is unaffected (Node only). Partially available: ${PYTHON_ONLY_SKILLS}.`
+    );
+  }
+  const found =
+    status === 'unsupported' ? `Python ${detected.version.raw} detected (${detected.command}) — too old.` : 'No Python found on PATH.';
+  return (
+    `${found} That is fine: Node is the only prerequisite of the Wizz core.\n` +
+    `Only these skills need Python 3.11+ and stay unavailable until it is: ${PYTHON_ONLY_SKILLS}.`
+  );
+}
+
+/**
+ * Check the local Python environment and report which skills it costs.
+ *
+ * Informational only: since item 29 nothing in the core needs Python, so this
+ * never blocks, never prompts and never asks for an acknowledgement — it logs
+ * one line and the install moves on. The installer runs in the destination
+ * environment, so probing PATH here tests the right machine.
  *
- * Warn-don't-block: most of WIZZ works without Python, so the install always
- * may proceed — but the user must explicitly acknowledge the warning so it
- * can't scroll past unseen. In non-interactive runs (--yes, or stdin is not
- * a TTY) the warning is logged and the install continues without a prompt.
+ * `options.nonInteractive` is kept for call-site compatibility and is not read.
  *
  * @param {Object} [options]
- * @param {boolean} [options.nonInteractive=false] - Skip the ack prompt (--yes, or no TTY)
  * @returns {Promise<{status: string, detected: Object|null}>}
  */
-async function checkPythonEnvironment({ nonInteractive = false } = {}) {
+async function checkPythonEnvironment() {
   // Called via module.exports so tests can stub detection.
   const detected = module.exports.detectPython();
   const status = classifyPython(detected ? detected.version : null);
 
   if (status === 'full' && detected.isRuntimeCommand) {
-    await prompts.log.success(`Python ${detected.version.raw} detected (${detected.command}) — all Wizz features supported.`);
-    return { status, detected };
-  }
-
-  if (detected && !detected.isRuntimeCommand) {
-    await prompts.log.warn(
-      `Python ${detected.version.raw} found via \`${detected.command}\`, but Wizz scripts invoke \`python3\`, which is not on PATH.\n` +
-        `Python-powered features (memlog session memory, TOML config resolution) won't run until \`python3\` resolves —\n` +
-        `add a python3 alias/shim, or reinstall Python with the python3 launcher enabled.`,
-    );
-  } else if (status === 'partial') {
-    await prompts.log.warn(
-      `Python ${detected.version.raw} detected (${detected.command}) — Wizz's TOML config tools need Python 3.11+ (stdlib tomllib).\n` +
-        `Works: memlog session memory. Won't work: config/customization resolution scripts.`,
-    );
-  } else {
-    const found =
-      status === 'unsupported' ? `Python ${detected.version.raw} detected (${detected.command}) — too old.` : 'No Python found on PATH.';
-    await prompts.log.warn(
-      `${found} Wizz installs fine without it, but Python-powered features\n` +
-        `(memlog session memory, TOML config resolution) won't run until Python 3.11+ is available.`,
+    await prompts.log.success(
+      `Python ${detected.version.raw} detected (${detected.command}) — the optional Python-backed skills are available too.`,
     );
-  }
-  await prompts.note(upgradeHints(), 'Python 3.11+ recommended');
-
-  if (nonInteractive) {
-    await prompts.log.info('Continuing anyway (non-interactive run). You can fix Python later — no reinstall needed.');
     return { status, detected };
   }
 
-  const choice = await prompts.select({
-    message: "Wizz's Python-powered features won't work yet. How do you want to proceed?",
-    choices: [
-      {
-        name: 'Continue install',
-        value: 'continue',
-        hint: 'Wizz works without Python — you can fix Python later, no reinstall needed',
-      },
-      {
-        name: 'Quit and fix Python first',
-        value: 'quit',
-        hint: 'make Python 3.11+ available as python3, then re-run the installer',
-      },
-    ],
-    default: 'continue',
-  });
-
-  if (choice === 'quit') {
-    await prompts.cancel('Make Python 3.11+ available as `python3` (see hints above), then re-run the installer.');
-    process.exit(0);
-  }
-
+  await prompts.log.info(degradedMessage(status, detected));
+  await prompts.note(upgradeHints(), 'Python 3.11+ optional');
   return { status, detected };
 }
 
 module.exports = {
   checkPythonEnvironment,
+  degradedMessage,
   detectPython,
   parsePythonVersion,
   classifyPython,
   PYTHON_FULL_SUPPORT,
   PYTHON_PARTIAL_SUPPORT,
+  PYTHON_ONLY_SKILLS,
 };

package/tools/installer/core/quick-update.js

@@ -14,6 +14,80 @@ const { OfficialModules } = require('../modules/official-modules');
 const { ExistingInstall } = require('./existing-install');
 const { getProjectRoot } = require('../project-root');
 const prompts = require('../prompts');
+// Item 10 (review da fase 3, 2026-09-11): rebuild TAG@SHA pins from a
+// manifest entry's version + shaRequested. pin-spec.js is a leaf module
+// (no requires of its own), safe to pull in at top level here.
+const { formatPinValue } = require('../modules/pin-spec');
+
+/**
+ * Build channelOptions (pins/nextSet) from the existing manifest's recorded
+ * per-module channel, so the config collector and clone steps that follow
+ * don't silently redecide a module's channel.
+ *
+ * Item 10 (review da fase 3, 2026-09-11): rebuilds `TAG@SHA`, not just
+ * `TAG`, whenever the manifest entry carries `shaRequested` — the SHA half
+ * of the `--pin CODE=TAG@SHA` that produced it (manifest-generator.js).
+ * Dropping that half here silently downgraded the pin to tag-only on every
+ * quick-update, so a tag force-moved on the remote between installs would
+ * pass unnoticed on the single most common reinstall path.
+ *
+ * Extracted from `quickUpdate` as its own function (rather than inlined) so
+ * it can be exercised directly in tests without mocking the whole
+ * `Installer` — see test/test-pin-sha.js.
+ *
+ * @param {Object|null} manifestData - `installer.manifest.read(wizzDir)` result
+ * @param {Object} [deps] - Injectable seams for tests
+ * @param {Function} [deps.warn] - Defaults to `prompts.log.warn`
+ * @param {{fetchStableTags: Function, classifyUpgrade: Function, parseGitHubRepo: Function}} [deps.channelResolver]
+ *   Defaults to requiring `../modules/channel-resolver` (real GitHub tag lookups).
+ * @returns {Promise<{global: null, nextSet: Set<string>, pins: Map<string,string>, warnings: string[]}>}
+ */
+async function buildChannelOptionsFromManifest(manifestData, deps = {}) {
+  const warn = deps.warn || prompts.log.warn;
+  const channelOptions = { global: null, nextSet: new Set(), pins: new Map(), warnings: [] };
+  if (!manifestData?.modulesDetailed) return channelOptions;
+
+  const { fetchStableTags, classifyUpgrade, parseGitHubRepo } = deps.channelResolver || require('../modules/channel-resolver');
+  for (const entry of manifestData.modulesDetailed) {
+    if (!entry?.name || !entry?.channel) continue;
+    if (entry.channel === 'pinned' && entry.version) {
+      channelOptions.pins.set(entry.name, formatPinValue(entry.version, entry.shaRequested));
+      continue;
+    }
+    if (entry.channel === 'next') {
+      channelOptions.nextSet.add(entry.name);
+      continue;
+    }
+    // Stable: classify the available upgrade. Patches and minors fall
+    // through (stable default picks up the top tag). A major upgrade
+    // requires opt-in, so under quick-update's non-interactive semantics
+    // we pin to the current version to prevent a silent breaking jump.
+    if (entry.channel === 'stable' && entry.version && entry.repoUrl) {
+      const parsed = parseGitHubRepo(entry.repoUrl);
+      if (!parsed) continue;
+      try {
+        const tags = await fetchStableTags(parsed.owner, parsed.repo);
+        if (tags.length === 0) continue;
+        const topTag = tags[0].tag;
+        const cls = classifyUpgrade(entry.version, topTag);
+        if (cls === 'major') {
+          channelOptions.pins.set(entry.name, formatPinValue(entry.version, entry.shaRequested));
+          await warn(
+            `${entry.name} ${entry.version} → ${topTag} is a new major release; staying on ${entry.version}. ` +
+              `Run \`wizz install\` (Modify) with \`--pin ${entry.name}=${topTag}\` to accept.`,
+          );
+        }
+      } catch (error) {
+        // Tag lookup failed (offline, rate-limited). Stay on the current
+        // version rather than guessing — the existing cache is already
+        // at that ref, so re-using it keeps the install stable.
+        channelOptions.pins.set(entry.name, formatPinValue(entry.version, entry.shaRequested));
+        await warn(`Could not check ${entry.name} for updates (${error.message}); staying on ${entry.version}.`);
+      }
+    }
+  }
+  return channelOptions;
+}
 
 /**
  * Quick update: preserves all settings and only prompts for new config fields.
@@ -97,48 +171,7 @@ async function quickUpdate(installer, config) {
   // 'pinned' would trigger a stable-channel tag lookup at config-collection
   // time, burning GitHub API quota and potentially failing.
   const manifestData = await installer.manifest.read(wizzDir);
-  const channelOptions = { global: null, nextSet: new Set(), pins: new Map(), warnings: [] };
-  if (manifestData?.modulesDetailed) {
-    const { fetchStableTags, classifyUpgrade, parseGitHubRepo } = require('../modules/channel-resolver');
-    for (const entry of manifestData.modulesDetailed) {
-      if (!entry?.name || !entry?.channel) continue;
-      if (entry.channel === 'pinned' && entry.version) {
-        channelOptions.pins.set(entry.name, entry.version);
-        continue;
-      }
-      if (entry.channel === 'next') {
-        channelOptions.nextSet.add(entry.name);
-        continue;
-      }
-      // Stable: classify the available upgrade. Patches and minors fall
-      // through (stable default picks up the top tag). A major upgrade
-      // requires opt-in, so under quick-update's non-interactive semantics
-      // we pin to the current version to prevent a silent breaking jump.
-      if (entry.channel === 'stable' && entry.version && entry.repoUrl) {
-        const parsed = parseGitHubRepo(entry.repoUrl);
-        if (!parsed) continue;
-        try {
-          const tags = await fetchStableTags(parsed.owner, parsed.repo);
-          if (tags.length === 0) continue;
-          const topTag = tags[0].tag;
-          const cls = classifyUpgrade(entry.version, topTag);
-          if (cls === 'major') {
-            channelOptions.pins.set(entry.name, entry.version);
-            await prompts.log.warn(
-              `${entry.name} ${entry.version} → ${topTag} is a new major release; staying on ${entry.version}. ` +
-                `Run \`wizz install\` (Modify) with \`--pin ${entry.name}=${topTag}\` to accept.`,
-            );
-          }
-        } catch (error) {
-          // Tag lookup failed (offline, rate-limited). Stay on the current
-          // version rather than guessing — the existing cache is already
-          // at that ref, so re-using it keeps the install stable.
-          channelOptions.pins.set(entry.name, entry.version);
-          await prompts.log.warn(`Could not check ${entry.name} for updates (${error.message}); staying on ${entry.version}.`);
-        }
-      }
-    }
-  }
+  const channelOptions = await buildChannelOptionsFromManifest(manifestData);
 
   // Load existing configs and collect new fields (if any)
   await prompts.log.info('Checking for new configuration options...');
@@ -206,4 +239,4 @@ async function quickUpdate(installer, config) {
   };
 }
 
-module.exports = { quickUpdate };
+module.exports = { quickUpdate, buildChannelOptionsFromManifest };

package/tools/installer/core/resolved-config.js

@@ -0,0 +1,168 @@
+/**
+ * Resolved central config generator (audit item 29, 2026-09-12).
+ *
+ * Sibling of `resolved-customizations.js`. Where that one snapshots each
+ * skill's `customize.toml`, this one snapshots Wizz's CENTRAL config — the
+ * four-layer merge that `src/scripts/resolve_config.py` performs at runtime:
+ *
+ *   1. `_wizz/config.toml`               (installer-owned team)
+ *   2. `_wizz/config.user.toml`          (installer-owned user)
+ *   3. `_wizz/custom/config.toml`        (human-authored team, committed)
+ *   4. `_wizz/custom/config.user.toml`   (human-authored user, gitignored)
+ *
+ * The merged result is written to `_wizz/_resolved/_config.json`, so a skill
+ * that needs `core.user_name`, `core.communication_language` or
+ * `core.output_folder` reads ONE json file instead of spawning `python3`.
+ * That is what makes Node the only prerequisite for activating an agent:
+ * Python stays only for the BMAD skills that ship their own Python scripts.
+ *
+ * Merge rules are not re-implemented here — `deepMerge` from
+ * `resolved-customizations.js` is already the 1:1 port of the Python rules
+ * (scalars override, tables deep-merge, arrays of tables keyed by `code`/`id`
+ * merge by that key, every other array appends). One motor, one behaviour.
+ *
+ * Layer sourcing mirrors `resolveAll`: the two base layers come from the
+ * freshly written tree (`wizzDir`, possibly the A14 tmp scaffold), the two
+ * `custom/` layers from the REAL project root, so a fresh install still sees
+ * the user's overrides.
+ *
+ * Fail-open, like every other generator here: a missing or broken base
+ * `config.toml` means NO snapshot (a stale one is removed) and a warning —
+ * never a thrown install. Callers that find no `_config.json` fall back to
+ * `resolve_config.py` (where Python exists) or to neutral defaults.
+ */
+
+const path = require('node:path');
+const nodeFs = require('node:fs');
+const fs = require('../fs-native');
+const { WIZZ_FOLDER_NAME } = require('../ide/shared/path-utils');
+const { deepMerge, loadTomlLayer, computeInputsIndex } = require('./resolved-customizations');
+
+// Name of the central-config snapshot inside `_resolved/`. Leading underscore
+// keeps it out of the `<skill-name>.json` namespace (skills are `wizz-*`).
+const CONFIG_SNAPSHOT = '_config.json';
+
+const BASE_TEAM = 'config.toml';
+const BASE_USER = 'config.user.toml';
+
+/**
+ * Absolute paths of the four config layers, in merge order (lowest first).
+ * @param {{projectRoot: string, wizzDir: string}} args
+ * @returns {string[]}
+ */
+function configLayerPaths({ projectRoot, wizzDir }) {
+  const customDir = path.join(projectRoot, WIZZ_FOLDER_NAME, 'custom');
+  return [path.join(wizzDir, BASE_TEAM), path.join(wizzDir, BASE_USER), path.join(customDir, BASE_TEAM), path.join(customDir, BASE_USER)];
+}
+
+/**
+ * Merge the four layers into one object.
+ *
+ * The base layer (`_wizz/config.toml`) is load-bearing: without it there is
+ * no `core` table at all, and a snapshot written from `{}` would look valid
+ * while telling every skill the user has no name and no language. So a
+ * missing/broken base is reported as `{ config: null }`, not as `{}`.
+ *
+ * `absent` separates the two reasons, because they deserve different noise:
+ * a base that does not exist YET is the normal state during a fresh install
+ * (the resolver runs before `writeCentralConfig`) and must stay silent; a
+ * base that exists and does not parse is a real problem and warns.
+ *
+ * @param {{projectRoot: string, wizzDir: string}} args
+ * @returns {{config: object|null, absent: boolean, warnings: string[], inputs: string[]}}
+ */
+function resolveCentralConfig({ projectRoot, wizzDir }) {
+  const warnings = [];
+  const layers = configLayerPaths({ projectRoot, wizzDir });
+  const [baseTeamPath] = layers;
+
+  if (!nodeFs.existsSync(baseTeamPath)) {
+    return { config: null, absent: true, warnings, inputs: [] };
+  }
+
+  const baseTeam = loadTomlLayer(baseTeamPath, warnings);
+  if (baseTeam === null) {
+    warnings.push(`base config not readable (${baseTeamPath}): no _config.json written`);
+    return { config: null, absent: false, warnings, inputs: [] };
+  }
+
+  let merged = baseTeam;
+  for (const layerPath of layers.slice(1)) {
+    const layer = loadTomlLayer(layerPath, warnings);
+    if (layer !== null) merged = deepMerge(merged, layer);
+  }
+  return { config: merged, absent: false, warnings, inputs: layers.filter((p) => nodeFs.existsSync(p)) };
+}
+
+/**
+ * Write `_resolved/_config.json`, or remove a stale one when the central
+ * config cannot be resolved.
+ *
+ * @param {object} args
+ * @param {string} args.projectRoot
+ * @param {string} args.wizzDir
+ * @param {string} args.resolvedDir - `{wizzDir}/_resolved`, already created
+ * @returns {Promise<{written: boolean, absent: boolean, warnings: string[], entry: object|null}>}
+ */
+async function writeResolvedConfig({ projectRoot, wizzDir, resolvedDir }) {
+  const snapshotPath = path.join(resolvedDir, CONFIG_SNAPSHOT);
+  const { config, absent, warnings, inputs } = resolveCentralConfig({ projectRoot, wizzDir });
+
+  if (config === null) {
+    await fs.remove(snapshotPath);
+    return { written: false, absent, warnings, entry: null };
+  }
+
+  await fs.writeFile(snapshotPath, `${JSON.stringify(config, null, 2)}\n`, 'utf8');
+  return {
+    written: true,
+    absent: false,
+    warnings,
+    entry: { inputs: computeInputsIndex({ projectRoot, wizzDir, inputPaths: inputs }) },
+  };
+}
+
+/**
+ * Second pass for the installer: write `_config.json` AFTER the central
+ * config exists, patching only the `config` key of an `.index.json` that is
+ * already on disk.
+ *
+ * Why a second pass at all: on a fresh install the snapshot generator runs
+ * inside the tmp scaffold, before `writeCentralConfig` (and before
+ * `--set` overrides) have produced `_wizz/config.toml`. Resolving the
+ * central config there would snapshot a file that does not exist yet. So
+ * the installer calls this once more on the REAL `_wizz/`, after the swap
+ * and after the overrides, and only the central-config half is redone —
+ * the skill snapshots are already correct and are not touched.
+ *
+ * Fail-open like everything else here: any failure returns `written: false`
+ * with the reason, and the caller degrades to `wizz resolve` later.
+ *
+ * @param {object} args
+ * @param {string} args.projectRoot
+ * @param {string} args.wizzDir - the REAL `_wizz/`, post-swap
+ * @returns {Promise<{written: boolean, absent: boolean, warnings: string[]}>}
+ */
+async function refreshResolvedConfig({ projectRoot, wizzDir }) {
+  const resolvedDir = path.join(wizzDir, '_resolved');
+  await fs.mkdir(resolvedDir, { recursive: true });
+  const result = await writeResolvedConfig({ projectRoot, wizzDir, resolvedDir });
+
+  // Patch the index in place: `skills` was written by the first pass and is
+  // still valid, so re-deriving it here would be wasted work and a chance to
+  // get it wrong.
+  const { readIndex, writeResolvedIndex } = require('./resolved-customizations');
+  const index = readIndex(resolvedDir);
+  if (index && index.skills) {
+    await writeResolvedIndex(resolvedDir, index.skills, result.entry);
+  }
+  return { written: result.written, absent: result.absent, warnings: result.warnings };
+}
+
+module.exports = {
+  resolveCentralConfig,
+  writeResolvedConfig,
+  refreshResolvedConfig,
+  configLayerPaths,
+  CONFIG_SNAPSHOT,
+};