wizz-method 2.0.0 → 2.1.0

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

@@ -0,0 +1,736 @@
+/**
+ * Resolved customizations generator (audit item 19, 2026-09-11).
+ *
+ * After the modules are installed, walks the freshly written `_wizz/` tree
+ * for every `customize.toml`, applies the same three-layer merge the
+ * runtime resolver (`src/scripts/resolve_customization.py`) applies, and
+ * writes the merged result to `_wizz/_resolved/<skill-name>.json`.
+ *
+ * Why: agent activation today spawns Python and/or reads all three TOML
+ * layers on every skill activation (48 SKILL.md call sites). With a
+ * resolved snapshot on disk, activation is a single file read and NOTHING
+ * else — no mtime check, no stat, no spawn. The Python resolver is the
+ * fallback for one case only: the snapshot file is missing (never
+ * generated, or skipped because the base `customize.toml` is broken).
+ *
+ * Staleness is therefore a WRITE-time concern, not a read-time one: the
+ * snapshots are regenerated by `wizz install`/`wizz update`, by the new
+ * `wizz resolve [--skill <name>]`, and by the wizz-customize skill after
+ * it edits a layer. `wizz doctor` detects a snapshot that fell behind by
+ * comparing `_resolved/.index.json` (sha256 of every input that fed each
+ * snapshot: base customize.toml, its includes, the team/user layers and
+ * their includes) with the files on disk.
+ *
+ * The merge here must stay byte-for-byte SEMANTICALLY identical to the
+ * Python one (same rules, same precedence, same `include` expansion) so
+ * that a resolved snapshot and a fresh `resolve_customization.py --skill`
+ * run agree. `test/test-resolved-customizations.js` enforces exactly that
+ * parity by running both against fixture fixtures and diffing the JSON.
+ *
+ * Nothing here prompts; failures are fail-open (warn + skip) so a broken
+ * customization file never blocks an install — same philosophy as the
+ * Python resolver itself.
+ *
+ * `_resolved/` is a GENERATED, gitignored artifact and stays OUT of
+ * `files-manifest.csv`: nothing here calls the installer's `trackFile`. The
+ * manifest exists to tell an installed file from a user-authored one so an
+ * update can preserve user edits and detect drift; a snapshot has no user
+ * edits to preserve (editing one is pointless — the next `wizz resolve`
+ * overwrites it) and its hash changes on every regeneration, so tracking it
+ * would report drift on every single run. Drift detection therefore ignores
+ * `_resolved/` entirely; staleness is `.index.json`'s job, not the
+ * manifest's.
+ */
+
+const path = require('node:path');
+const nodeFs = require('node:fs');
+const crypto = require('node:crypto');
+const fs = require('../fs-native');
+const { parse: parseToml } = require('smol-toml');
+const { WIZZ_FOLDER_NAME } = require('../ide/shared/path-utils');
+const { resolveIncludes, splitIncludeParagraphs, safeSet, hasOwn, isPlainObject } = require('./resolved-includes');
+// Audit item 24 — closed key sets for the user-authored team/user layers.
+const { findUnknownKeys } = require('./resolved-schema');
+
+const KEYED_MERGE_FIELDS = ['code', 'id'];
+
+// Names inside `_resolved/` that are NOT skill snapshots (never pruned).
+const INDEX_FILE = '.index.json';
+const GITIGNORE_FILE = '.gitignore';
+// `_resolved/` holds generated artifacts only: ignore everything but the
+// ignore file itself, so a `wizz update` never shows up as 340 KB of diff.
+const GITIGNORE_BODY = '*\n!.gitignore\n';
+const INDEX_VERSION = 1;
+
+// ─── Merge rules (ported 1:1 from resolve_customization.py) ───
+
+/**
+ * Return 'code' or 'id' if every item in the array carries that same
+ * identifier field; otherwise null (append semantics). Mixed code/id
+ * arrays intentionally fall through to append.
+ */
+function detectKeyedMergeField(items) {
+  if (!Array.isArray(items) || items.length === 0) return null;
+  if (!items.every((item) => item !== null && typeof item === 'object' && !Array.isArray(item))) return null;
+  for (const candidate of KEYED_MERGE_FIELDS) {
+    if (items.every((item) => item[candidate] !== undefined && item[candidate] !== null)) return candidate;
+  }
+  return null;
+}
+
+/**
+ * Keyed merge: matching identifiers replace in place, new ones append.
+ * Non-table items in the override are appended (Python parity).
+ */
+function mergeByKey(base, override, keyName) {
+  const result = [];
+  const indexByKey = new Map();
+  for (const item of base) {
+    if (item === null || typeof item !== 'object' || Array.isArray(item)) continue;
+    if (item[keyName] !== undefined && item[keyName] !== null) {
+      indexByKey.set(item[keyName], result.length);
+    }
+    result.push({ ...item });
+  }
+  for (const item of override) {
+    if (item === null || typeof item !== 'object' || Array.isArray(item)) {
+      result.push(item);
+      continue;
+    }
+    const key = item[keyName];
+    if (key !== undefined && key !== null && indexByKey.has(key)) {
+      result[indexByKey.get(key)] = { ...item };
+    } else {
+      if (key !== undefined && key !== null) indexByKey.set(key, result.length);
+      result.push({ ...item });
+    }
+  }
+  return result;
+}
+
+/**
+ * Shape-aware array merge: keyed merge when every item (base + override)
+ * shares `code` or `id`, else append.
+ */
+function mergeArrays(base, override) {
+  const baseArr = Array.isArray(base) ? base : [];
+  const overrideArr = Array.isArray(override) ? override : [];
+  const keyedField = detectKeyedMergeField([...baseArr, ...overrideArr]);
+  if (keyedField) return mergeByKey(baseArr, overrideArr, keyedField);
+  return [...baseArr, ...overrideArr];
+}
+
+/**
+ * Structural deep merge. Tables deep-merge, arrays shape-merge,
+ * everything else: override wins. Python `deep_merge` parity.
+ */
+function deepMerge(base, override) {
+  if (isPlainObject(base) && isPlainObject(override)) {
+    const result = { ...base };
+    for (const [key, overVal] of Object.entries(override)) {
+      // hasOwn, not `in`: `'constructor' in result` is true via the
+      // prototype chain even when the base layer never declared it, which
+      // would deep-merge the override into Object's constructor function.
+      safeSet(result, key, hasOwn(result, key) ? deepMerge(result[key], overVal) : overVal);
+    }
+    return result;
+  }
+  if (Array.isArray(base) && Array.isArray(override)) return mergeArrays(base, override);
+  return override;
+}
+
+/**
+ * Load and parse a TOML layer. Missing file → null (layer absent).
+ * Parse/read failure → null + warning (fail-open, Python parity where
+ * optional layers warn and degrade to {}).
+ */
+function loadTomlLayer(filePath, warnings) {
+  let raw;
+  try {
+    raw = nodeFs.readFileSync(filePath, 'utf8');
+  } catch {
+    return null;
+  }
+  try {
+    const parsed = parseToml(raw);
+    return isPlainObject(parsed) ? parsed : null;
+  } catch (error) {
+    warnings.push(`failed to parse ${filePath}: ${error.message}`);
+    return null;
+  }
+}
+
+// ─── Generator ───
+
+/**
+ * Recursively collect paths of every customize.toml under rootDir.
+ * Skips `_resolved` itself and hidden dirs.
+ */
+function findCustomizeTomls(rootDir) {
+  const found = [];
+  const stack = [rootDir];
+  while (stack.length > 0) {
+    const dir = stack.pop();
+    let entries;
+    try {
+      entries = nodeFs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      if (entry.name.startsWith('.') || entry.name === 'node_modules') continue;
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (full === path.join(rootDir, '_resolved')) continue;
+        stack.push(full);
+      } else if (entry.name === 'customize.toml') {
+        found.push(full);
+      }
+    }
+  }
+  return found.sort();
+}
+
+/**
+ * Names of every skill under `wizzDir` that ships a `customize.toml`
+ * (i.e. every skill the generator will snapshot).
+ * @param {string} wizzDir
+ * @returns {string[]} sorted, de-duplicated skill names
+ */
+function listSkillNames(wizzDir) {
+  const names = new Set(findCustomizeTomls(wizzDir).map((p) => path.basename(path.dirname(p))));
+  return [...names].sort();
+}
+
+/**
+ * Every `customize.toml` a project carries, by skill name — the `_wizz/`
+ * tree AND the deployed copies in each IDE's skills folder
+ * (`<projectRoot>/.<ide>/skills/<skill>/customize.toml`). They are not the
+ * same set: the verbatim pipeline moves each skill directory OUT of
+ * `_wizz/` into the IDE folders, so after an install the file the user is
+ * told to edit lives at `.claude/skills/<skill>/customize.toml` while
+ * `_wizz/` keeps only the shared includes. Shallow scan on purpose.
+ *
+ * Deterministic by construction: every readdir is sorted, so the order of
+ * the paths a skill maps to never depends on the order the filesystem
+ * happens to hand back its entries (`_wizz/` staged copy first, then the
+ * deployed copies with the IDE directories sorted by name).
+ * @param {object} args
+ * @param {string} args.projectRoot
+ * @param {string} args.wizzDir
+ * @returns {Map<string, string[]>} skill name → absolute paths, `_wizz/` first
+ */
+function discoverSkillCustomizeTomls({ projectRoot, wizzDir }) {
+  const found = new Map();
+  const add = (filePath) => {
+    const name = path.basename(path.dirname(filePath));
+    if (!found.has(name)) found.set(name, []);
+    const list = found.get(name);
+    if (!list.includes(filePath)) list.push(filePath);
+  };
+
+  for (const filePath of findCustomizeTomls(wizzDir)) add(filePath);
+
+  let dotDirs = [];
+  try {
+    dotDirs = nodeFs
+      .readdirSync(projectRoot, { withFileTypes: true })
+      .filter((e) => e.isDirectory() && e.name.startsWith('.') && e.name !== '.git')
+      .map((e) => e.name)
+      .sort();
+  } catch {
+    return found;
+  }
+  for (const dot of dotDirs) {
+    const skillsDir = path.join(projectRoot, dot, 'skills');
+    let entries;
+    try {
+      entries = nodeFs
+        .readdirSync(skillsDir, { withFileTypes: true })
+        .filter((e) => e.isDirectory())
+        .map((e) => e.name)
+        .sort();
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      const candidate = path.join(skillsDir, entry, 'customize.toml');
+      if (nodeFs.existsSync(candidate)) add(candidate);
+    }
+  }
+  return found;
+}
+
+/** The IDE directory `.claude/skills/<skill>/customize.toml` is deployed from. */
+const PRIMARY_IDE_DIR = '.claude';
+
+/**
+ * Rank a deployed copy: `.claude/` first (the canonical IDE folder — it is
+ * what wizz-customize points the user at and what the docs name), then every
+ * other IDE folder alphabetically. Never filesystem order.
+ */
+function deployedRank(projectRoot, filePath) {
+  const rel = path.relative(projectRoot, filePath);
+  const ideDir = rel.split(path.sep)[0];
+  return [ideDir === PRIMARY_IDE_DIR ? 0 : 1, rel];
+}
+
+/**
+ * ONE customize.toml per skill, DEPLOYED copy preferred over the `_wizz/`
+ * staged copy. After an install the file the user edits (and the one
+ * wizz-customize points at) is `.claude/skills/<skill>/customize.toml`; the
+ * staged copy under `_wizz/` is only what shipped. `wizz resolve` must
+ * regenerate from what the user edits, so it asks for this list.
+ *
+ * The choice is deterministic, never filesystem order: a project that
+ * deploys to several IDE folders (`.claude/`, `.agents/`, `.cline/`, …)
+ * carries the same skill several times, and picking "whichever readdir
+ * returned first" made `wizz resolve` resolve from a different copy on a
+ * different machine. Order is: `.claude/skills/<skill>/customize.toml`, then
+ * the other deployed copies by path, then the `_wizz/` staged copy. When two
+ * or more deployed copies exist AND their bytes differ, that is a real
+ * divergence (one IDE folder was edited and the others were not) and it
+ * warns, naming both paths and the one that won.
+ *
+ * @param {object} args
+ * @param {string} args.projectRoot
+ * @param {string} args.wizzDir
+ * @param {string[]} [args.warnings] - sink for divergence warnings
+ * @returns {string[]} absolute paths, ordered by skill name
+ */
+function preferredCustomizePaths({ projectRoot, wizzDir, warnings }) {
+  const byName = discoverSkillCustomizeTomls({ projectRoot, wizzDir });
+  const chosen = [];
+  for (const name of [...byName.keys()].sort()) {
+    const paths = byName.get(name);
+    const deployed = paths
+      .filter((p) => {
+        const rel = path.relative(wizzDir, p);
+        return rel.startsWith('..') || path.isAbsolute(rel);
+      })
+      .sort((a, b) => {
+        const [rankA, relA] = deployedRank(projectRoot, a);
+        const [rankB, relB] = deployedRank(projectRoot, b);
+        if (rankA !== rankB) return rankA - rankB;
+        return relA < relB ? -1 : relA > relB ? 1 : 0;
+      });
+    const winner = deployed[0] || paths[0];
+    chosen.push(winner);
+
+    if (warnings && deployed.length > 1) {
+      const winnerHash = sha256File(winner);
+      const divergent = deployed.slice(1).filter((p) => sha256File(p) !== winnerHash);
+      if (divergent.length > 0) {
+        warnings.push(
+          `skill ${name}: deployed customize.toml copies diverge — ${[winner, ...divergent].join(' vs ')}; ` +
+            `resolved from ${winner} (run wizz update to redeploy the others)`,
+        );
+      }
+    }
+  }
+  return chosen;
+}
+
+/** Human-readable locations `wizz resolve` looked in, for the not-found message. */
+function searchedLocations({ projectRoot, wizzDir, skillName }) {
+  return [path.join(wizzDir, '**', skillName, 'customize.toml'), path.join(projectRoot, '.<ide>', 'skills', skillName, 'customize.toml')];
+}
+
+// ─── Inputs index (staleness detection, audit item 19 / bug 4) ───
+
+/**
+ * sha256 of a file's bytes, or null when it can't be read. Same digest the
+ * installer's `calculateFileHash` produces, so doctor can compare either way.
+ */
+function sha256File(absPath) {
+  try {
+    return crypto.createHash('sha256').update(nodeFs.readFileSync(absPath)).digest('hex');
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Path as recorded in `.index.json`: POSIX, relative to the PROJECT root,
+ * with anything inside the install rewritten under `_wizz/` so a fresh
+ * install (which resolves inside a throwaway `_wizz.tmp-<pid>/` scaffold)
+ * records the path the file will have after the atomic swap.
+ */
+function indexRelativePath(projectRoot, wizzDir, absPath) {
+  const toPosix = (p) => p.split(path.sep).join('/');
+  const relToWizz = path.relative(wizzDir, absPath);
+  if (relToWizz && !relToWizz.startsWith('..') && !path.isAbsolute(relToWizz)) {
+    return `${WIZZ_FOLDER_NAME}/${toPosix(relToWizz)}`;
+  }
+  return toPosix(path.relative(projectRoot, absPath));
+}
+
+/**
+ * Hash every input that exists into `{ "<relative path>": "<sha256>" }`,
+ * sorted by path so the index is byte-stable across runs. Pure: no writes,
+ * no warnings. Inputs that do not exist are omitted — a layer the user has
+ * not created yet has nothing to hash, so `wizz doctor` cannot see a
+ * brand-new team override (install/update/resolve regenerate regardless).
+ * @param {object} args
+ * @param {string} args.projectRoot
+ * @param {string} args.wizzDir
+ * @param {string[]} args.inputPaths - absolute paths
+ * @returns {Object<string, string>}
+ */
+function computeInputsIndex({ projectRoot, wizzDir, inputPaths }) {
+  const pairs = [];
+  const seen = new Set();
+  for (const abs of inputPaths) {
+    if (seen.has(abs)) continue;
+    seen.add(abs);
+    const hash = sha256File(abs);
+    if (hash === null) continue;
+    pairs.push([indexRelativePath(projectRoot, wizzDir, abs), hash]);
+  }
+  pairs.sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0));
+  return Object.fromEntries(pairs);
+}
+
+/**
+ * Read `_resolved/.index.json`. Missing/unreadable/malformed → null (the
+ * caller treats that as "never generated"), never throws.
+ * @param {string} resolvedDir
+ * @returns {object|null}
+ */
+function readIndex(resolvedDir) {
+  try {
+    const parsed = JSON.parse(nodeFs.readFileSync(path.join(resolvedDir, INDEX_FILE), 'utf8'));
+    return isPlainObject(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+// ─── Snapshot writing ───
+
+/**
+ * Resolve and write ONE skill's snapshot.
+ *
+ * The base layer is load-bearing: a snapshot written from a `{}` base would
+ * be a fresh, valid-looking file with no persona and no persistent_facts,
+ * and the runtime reads it unconditionally — the agent would activate empty
+ * with no signal. So a broken base is a SKIP: any stale snapshot is
+ * deleted, the runtime falls back to `resolve_customization.py`, and the
+ * user is warned. Team/user layers stay fail-open (losing an override
+ * degrades to the shipped defaults, a safe state).
+ *
+ * @returns {Promise<{skillName: string, status: 'written'|'skipped', warnings: string[], entry: object|null}>}
+ */
+async function resolveSkillSnapshot({ customizePath, customDir, resolvedDir, projectRoot, wizzDir }) {
+  const skillName = path.basename(path.dirname(customizePath));
+  const warnings = [];
+  const outPath = path.join(resolvedDir, `${skillName}.json`);
+
+  const baseRaw = loadTomlLayer(customizePath, warnings);
+  if (!isPlainObject(baseRaw)) {
+    warnings.push(
+      `base customize.toml inválido ou ilegível (${customizePath}) — snapshot NÃO gravado; ` +
+        `a ativação cai no fallback resolve_customization.py até você corrigir o arquivo e rodar wizz resolve`,
+    );
+    await fs.remove(outPath);
+    return { skillName, status: 'skipped', warnings, entry: null };
+  }
+
+  const inputPaths = [customizePath];
+  const teamPath = path.join(customDir, `${skillName}.toml`);
+  const userPath = path.join(customDir, `${skillName}.user.toml`);
+  inputPaths.push(teamPath, userPath);
+
+  // `context` carries the `_shared/` fallback: a skill deployed to
+  // `.claude/skills/<skill>/` keeps `include = ["../../_shared/x.md"]`, which
+  // from there points at a directory that does not exist. See resolved-includes.js.
+  const context = { projectRoot, skillName };
+  const defaults = resolveIncludes(baseRaw, path.dirname(customizePath), warnings, inputPaths, context);
+  const teamRaw = loadTomlLayer(teamPath, warnings);
+  const userRaw = loadTomlLayer(userPath, warnings);
+  const team = resolveIncludes(teamRaw || {}, customDir, warnings, inputPaths, context);
+  const user = resolveIncludes(userRaw || {}, customDir, warnings, inputPaths, context);
+
+  // Audit item 24: closed-key warnings for user-authored layers. The base
+  // layer is exempt (it owns the LLM-only fields and new experimental
+  // keys); a typo here is exactly the silent-merge the audit flagged.
+  // Warnings, never errors — the snapshot is still written (fail-open).
+  for (const [layerName, layer] of [
+    ['team', teamRaw],
+    ['user', userRaw],
+  ]) {
+    for (const unknown of findUnknownKeys(layer)) {
+      warnings.push(`${layerName} override: unknown key "${unknown}" (not a recognized workflow field — typo? check customize.toml docs)`);
+    }
+  }
+
+  const merged = deepMerge(deepMerge(defaults, team), user);
+  const body = `${JSON.stringify(merged, null, 2)}\n`;
+  // Atomic write via fs-native (tmp + rename), consistent with every other
+  // config file the installer writes.
+  await fs.writeFile(outPath, body, 'utf8');
+
+  return {
+    skillName,
+    status: 'written',
+    warnings,
+    entry: {
+      inputs: computeInputsIndex({ projectRoot, wizzDir, inputPaths }),
+      output: crypto.createHash('sha256').update(body).digest('hex'),
+    },
+  };
+}
+
+/**
+ * Remove `_resolved/*.json` snapshots whose skill no longer exists (a
+ * module uninstalled, a skill renamed). `.index.json` and `.gitignore`
+ * are never touched here.
+ * @returns {Promise<string[]>} names of the pruned files
+ */
+async function pruneOrphanSnapshots(resolvedDir, keepNames) {
+  let entries;
+  try {
+    entries = nodeFs.readdirSync(resolvedDir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const pruned = [];
+  for (const entry of entries) {
+    if (!entry.isFile()) continue;
+    if (entry.name === INDEX_FILE || entry.name === GITIGNORE_FILE) continue;
+    if (!entry.name.endsWith('.json')) continue;
+    if (keepNames.has(entry.name)) continue;
+    await fs.remove(path.join(resolvedDir, entry.name));
+    pruned.push(entry.name);
+  }
+  return pruned;
+}
+
+/** Write `_resolved/.gitignore` (generated artifacts stay out of git). */
+async function writeResolvedGitignore(resolvedDir) {
+  await fs.writeFile(path.join(resolvedDir, GITIGNORE_FILE), GITIGNORE_BODY, 'utf8');
+}
+
+/**
+ * Write `_resolved/.index.json` — the staleness oracle. Activation never
+ * reads it (it reads the snapshot and nothing else); `wizz doctor` does,
+ * comparing each recorded input hash against the file on disk.
+ *
+ * `config` carries the same shape for `_config.json` (the central-config
+ * snapshot, item 29); null when that snapshot could not be written.
+ */
+async function writeResolvedIndex(resolvedDir, skills, config = null) {
+  const sorted = Object.fromEntries(Object.entries(skills).sort((a, b) => (a[0] < b[0] ? -1 : 1)));
+  const index = { version: INDEX_VERSION, generated_at: new Date().toISOString(), skills: sorted, config };
+  await fs.writeFile(path.join(resolvedDir, INDEX_FILE), `${JSON.stringify(index, null, 2)}\n`, 'utf8');
+}
+
+/**
+ * Generate `_wizz/_resolved/<skill-name>.json` for every skill dir under
+ * `wizzDir` that carries a `customize.toml`, plus `.index.json` (input
+ * hashes for staleness detection) and `.gitignore`.
+ *
+ * The base layer comes from the freshly written tree (`wizzDir`, which may
+ * be the A14 tmp scaffold on a fresh install), but the team/user layers
+ * are read from the REAL project's `_wizz/custom/` — user customizations
+ * survive a fresh install, so the snapshot must reflect them even when
+ * `wizzDir` is a throwaway scaffold that never saw them.
+ *
+ * Nothing written here is tracked in `files-manifest.csv` — see the header.
+ *
+ * @param {Object} options
+ * @param {string} options.wizzDir - The (freshly written) `_wizz/` dir.
+ * @param {string} options.projectRoot - Real project root (for `_wizz/custom/`).
+ * @param {Function} [options.warn] - Async warn sink (defaults to console).
+ * @returns {Promise<{written: number, skipped: number, pruned: string[], warnings: string[]}>}
+ */
+async function resolveAll({ wizzDir, projectRoot, warn, includeDeployed = false }) {
+  const warnSink = warn || (async (msg) => console.warn(msg));
+  const customDir = path.join(projectRoot, WIZZ_FOLDER_NAME, 'custom');
+  const resolvedDir = path.join(wizzDir, '_resolved');
+  const emitted = [];
+  const emit = async (line) => {
+    emitted.push(line);
+    await warnSink(line);
+  };
+  // Install/update stay on the staged tree (`wizzDir` may be the A14 tmp
+  // scaffold, and the deployed copies still belong to the PREVIOUS install).
+  // `wizz resolve` opts into the deployed copies, which is what the user edits.
+  const discoveryWarnings = [];
+  const customizePaths = includeDeployed
+    ? preferredCustomizePaths({ projectRoot, wizzDir, warnings: discoveryWarnings })
+    : findCustomizeTomls(wizzDir);
+  for (const warning of discoveryWarnings) await emit(`_resolved: ${warning}`);
+
+  // NO early return on an empty list: a project that just lost its last
+  // customize.toml still needs its orphan snapshots pruned and an empty
+  // index written, otherwise `_resolved/` keeps serving stale snapshots for
+  // skills that no longer exist and doctor compares against an old index.
+  await fs.mkdir(resolvedDir, { recursive: true });
+  let written = 0;
+  let skipped = 0;
+  const skills = {};
+  const keepNames = new Set();
+
+  for (const customizePath of customizePaths) {
+    const skillName = path.basename(path.dirname(customizePath));
+    keepNames.add(`${skillName}.json`);
+    let result;
+    try {
+      result = await resolveSkillSnapshot({ customizePath, customDir, resolvedDir, projectRoot, wizzDir });
+    } catch (error) {
+      // Fail-open: one broken skill never blocks the install.
+      result = { skillName, status: 'skipped', warnings: [`skill ${skillName}: ${error.message}`], entry: null };
+    }
+    if (result.status === 'written') {
+      written++;
+      skills[result.skillName] = result.entry;
+    } else {
+      skipped++;
+    }
+    for (const warning of result.warnings) await emit(`_resolved/${result.skillName}: ${warning}`);
+  }
+
+  // Conservador de propósito: só é órfão o snapshot de uma skill que não
+  // tem customize.toml em lugar nenhum do projeto. O pipeline verbatim move
+  // os diretórios de skill de `_wizz/` para as pastas dos IDEs, então "não
+  // está no wizzDir" NÃO significa "foi desinstalada" — podar por esse
+  // critério apagaria snapshots válidos.
+  for (const name of discoverSkillCustomizeTomls({ projectRoot, wizzDir }).keys()) keepNames.add(`${name}.json`);
+
+  // Central config (item 29): `_resolved/_config.json` replaces the runtime
+  // `python3 resolve_config.py` call. Lazy require — resolved-config.js
+  // imports this module's merge rules, so a top-level require here would
+  // close the cycle and hand it a half-built exports object.
+  const { writeResolvedConfig, CONFIG_SNAPSHOT } = require('./resolved-config');
+  keepNames.add(CONFIG_SNAPSHOT);
+  const config = await writeResolvedConfig({ projectRoot, wizzDir, resolvedDir });
+  for (const warning of config.warnings) await emit(`_resolved/${CONFIG_SNAPSHOT}: ${warning}`);
+
+  const pruned = await pruneOrphanSnapshots(resolvedDir, keepNames);
+  await writeResolvedGitignore(resolvedDir);
+  await writeResolvedIndex(resolvedDir, skills, config.entry);
+
+  return { written, skipped, pruned, warnings: emitted, config: config.written };
+}
+
+/**
+ * Regenerate ONE skill's snapshot in place, preserving every other entry of
+ * `.index.json`. Used by `wizz resolve --skill <name>` (and by anything that
+ * edits a single customize layer, e.g. the wizz-customize skill).
+ * @param {string} projectRoot
+ * @param {string} wizzDir
+ * @param {string} skillName
+ * When `.index.json` is missing, unreadable or malformed there is no "every
+ * other entry" left to preserve: rewriting it with only this skill would
+ * silently drop every other skill from the staleness oracle, and doctor
+ * would then report them as "sem snapshot" forever. So that case falls back
+ * to the all-skills path (`resolveAll`), which rebuilds the FULL index.
+ *
+ * @param {string} projectRoot
+ * @param {string} wizzDir
+ * @param {string} skillName
+ * @param {object} [options] - { warn, includeDeployed }
+ * @returns {Promise<{written: number, skipped: number, warnings: string[], found: boolean}>}
+ */
+async function resolveOne(projectRoot, wizzDir, skillName, options = {}) {
+  const warnSink = options.warn || (async (msg) => console.warn(msg));
+  const customDir = path.join(projectRoot, WIZZ_FOLDER_NAME, 'custom');
+  const resolvedDir = path.join(wizzDir, '_resolved');
+  const discoveryWarnings = [];
+  const candidates = options.includeDeployed
+    ? preferredCustomizePaths({ projectRoot, wizzDir, warnings: discoveryWarnings })
+    : findCustomizeTomls(wizzDir);
+  const customizePath = candidates.find((p) => path.basename(path.dirname(p)) === skillName);
+  const emitted = [];
+  if (!customizePath) {
+    return { written: 0, skipped: 0, warnings: emitted, found: false, searched: searchedLocations({ projectRoot, wizzDir, skillName }) };
+  }
+  await fs.mkdir(resolvedDir, { recursive: true });
+
+  const previous = readIndex(resolvedDir);
+  if (!previous || !isPlainObject(previous.skills)) {
+    // (the fallback below re-derives the discovery warnings itself)
+    // No usable index: regenerate ALL of it rather than replacing it with a
+    // one-entry index that erases every other skill.
+    const all = await resolveAll({ wizzDir, projectRoot, warn: options.warn, includeDeployed: options.includeDeployed });
+    const wrote = nodeFs.existsSync(path.join(resolvedDir, `${skillName}.json`));
+    return {
+      written: wrote ? 1 : 0,
+      skipped: wrote ? 0 : 1,
+      warnings: [...emitted, ...all.warnings],
+      found: true,
+      customizePath,
+      regeneratedIndex: true,
+    };
+  }
+
+  // Only the divergence warning for THIS skill is relevant to a --skill run.
+  for (const warning of discoveryWarnings.filter((w) => w.startsWith(`skill ${skillName}:`))) {
+    const line = `_resolved: ${warning}`;
+    emitted.push(line);
+    await warnSink(line);
+  }
+
+  let result;
+  try {
+    result = await resolveSkillSnapshot({ customizePath, customDir, resolvedDir, projectRoot, wizzDir });
+  } catch (error) {
+    result = { skillName, status: 'skipped', warnings: [`skill ${skillName}: ${error.message}`], entry: null };
+  }
+
+  const skills = { ...previous.skills };
+  if (result.status === 'written') {
+    skills[skillName] = result.entry;
+  } else {
+    delete skills[skillName];
+  }
+  await writeResolvedGitignore(resolvedDir);
+  // A --skill run touches one snapshot: the central-config entry of the
+  // index it is patching must survive untouched, not be dropped to null.
+  await writeResolvedIndex(resolvedDir, skills, previous.config || null);
+
+  for (const warning of result.warnings) {
+    const line = `_resolved/${skillName}: ${warning}`;
+    emitted.push(line);
+    await warnSink(line);
+  }
+  return {
+    written: result.status === 'written' ? 1 : 0,
+    skipped: result.status === 'skipped' ? 1 : 0,
+    warnings: emitted,
+    found: true,
+    customizePath,
+  };
+}
+
+/**
+ * Back-compat wrapper kept for the installer call site: same behaviour as
+ * `resolveAll`, but returns just the number of snapshots written.
+ * @returns {Promise<number>}
+ */
+async function generateResolvedCustomizations(options) {
+  const { written } = await resolveAll(options);
+  return written;
+}
+
+module.exports = {
+  generateResolvedCustomizations,
+  resolveAll,
+  resolveOne,
+  deepMerge,
+  loadTomlLayer,
+  resolveIncludes,
+  splitIncludeParagraphs,
+  findUnknownKeys,
+  listSkillNames,
+  discoverSkillCustomizeTomls,
+  preferredCustomizePaths,
+  computeInputsIndex,
+  indexRelativePath,
+  readIndex,
+  writeResolvedIndex,
+  sha256File,
+  INDEX_FILE,
+  GITIGNORE_FILE,
+};