wizz-method 2.0.0 → 2.1.1

package/tools/installer/core/installer.js

@@ -1,3 +1,4 @@
+const os = require('node:os');
 const path = require('node:path');
 const fs = require('../fs-native');
 const { Manifest } = require('./manifest');
@@ -8,7 +9,6 @@ const { promptMissingEnvVars, mcpsWithMissingRequiredEnv } = require('../modules
 const { installClis, renderInstallCommand } = require('../modules/cli-config');
 const { writeDepsCache, readPreviousMcpPins } = require('../modules/deps-cache');
 const { IdeManager } = require('../ide/manager');
-const { FileOps } = require('../file-ops');
 const { Config } = require('./config');
 const { ManifestGenerator } = require('./manifest-generator');
 const prompts = require('../prompts');
@@ -16,6 +16,7 @@ const { WIZZ_FOLDER_NAME } = require('../ide/shared/path-utils');
 const { InstallPaths } = require('./install-paths');
 const { ExternalModuleManager } = require('../modules/external-manager');
 const { resolveModuleVersion } = require('../modules/version-resolver');
+const { buildHookEntries, filterHooksRegisteredGlobally, mergeHooksIntoSettings } = require('./hooks-settings');
 
 const { ExistingInstall } = require('./existing-install');
 const { warnPreNativeSkillsLegacy } = require('./legacy-warnings');
@@ -24,12 +25,15 @@ const moduleConfigWriter = require('./module-config-writer');
 const helpCatalog = require('./help-catalog');
 const quickUpdateModule = require('./quick-update');
 
+// `findWizzDir` lives in core/wizz-dir.js (single owner of `_wizz` resolution,
+// item 20 of the 2026-09-11 audit). Re-exported below for existing callers.
+const { findWizzDir } = require('./wizz-dir');
+
 class Installer {
   constructor() {
     this.externalModuleManager = new ExternalModuleManager();
     this.manifest = new Manifest();
     this.ideManager = new IdeManager();
-    this.fileOps = new FileOps();
     this.installedFiles = new Set(); // Track all installed files
     this.wizzFolderName = WIZZ_FOLDER_NAME;
   }
@@ -294,17 +298,43 @@ class Installer {
     // failure — never inferred from path shape (updates and fresh-but-
     // never-swapped both have `paths.isTmp === false` for different reasons).
     let swapped = false;
+    // Populated by the "Installing hooks" task below; read inside configTask
+    // to build the settings.json entries once the copy has actually happened.
+    let installedHookFiles = [];
 
     const installTasks = [];
 
-    installTasks.push({
-      title: 'Installing shared scripts',
-      task: async () => {
-        await this._installSharedScripts(paths);
-        addResult('Shared scripts', 'ok');
-        return 'Shared scripts installed';
+    installTasks.push(
+      {
+        title: 'Installing shared scripts',
+        task: async () => {
+          await this._installSharedScripts(paths);
+          addResult('Shared scripts', 'ok');
+          return 'Shared scripts installed';
+        },
       },
-    });
+      // RT-C1: copia tools/hooks/* → _wizz/hooks/. Runs against
+      // `paths.wizzDir` (the A14 tmp scaffold on a fresh install) so it moves
+      // with the rest of the scaffold on the atomic swap below — same
+      // reasoning as shared scripts. The actual settings.json registration
+      // happens later, inside configTask, deferred until AFTER the swap
+      // (same treatment as .mcp.json): it lives outside `_wizz/`, so writing
+      // it before a fresh install fully succeeds would leave it mutated even
+      // if the install as a whole later fails. `installedHookFiles` (outer
+      // scope) carries the basenames actually copied over to that later step.
+      {
+        title: 'Installing hooks',
+        task: async () => {
+          installedHookFiles = await this._installHooks(paths);
+          const detail =
+            installedHookFiles.length > 0
+              ? `${installedHookFiles.length} hook file(s) → _wizz/hooks/`
+              : 'nenhum hook encontrado em tools/hooks/';
+          addResult('Hooks', installedHookFiles.length > 0 ? 'ok' : 'warn', detail);
+          return detail;
+        },
+      },
+    );
 
     if (allModules.length > 0) {
       installTasks.push({
@@ -375,6 +405,30 @@ class Installer {
         await this.generateModuleConfigs(paths.wizzDir, moduleConfigs);
         addResult('Configurations', 'ok', 'generated');
 
+        // Audit item 19: snapshot every skill's resolved customization
+        // (base + team/user layers merged) into `_wizz/_resolved/`, so agent
+        // activation is a single file read instead of a Python spawn or a
+        // 3-layer TOML walk. Runs inside the tmp scaffold on a fresh install
+        // so the snapshots ride the A14 atomic swap; team/user layers are
+        // read from the REAL project's `_wizz/custom/` (user customizations
+        // survive a fresh install). Fail-open: a broken customize.toml
+        // warns and never blocks the install.
+        try {
+          const { generateResolvedCustomizations } = require('./resolved-customizations');
+          const resolvedCount = await generateResolvedCustomizations({
+            wizzDir: paths.wizzDir,
+            projectRoot: paths.projectRoot,
+            trackFile: (p) => this.installedFiles.add(p),
+            warn: async (msg) => await prompts.log.warn(msg),
+          });
+          if (resolvedCount > 0) {
+            addResult('Resolved customizations', 'ok', `${resolvedCount} snapshot(s) → _wizz/_resolved/`);
+          }
+        } catch (error) {
+          await prompts.log.warn(`Falha ao gerar _wizz/_resolved/ (fail-open): ${error.message}`);
+          addResult('Resolved customizations', 'warn', error.message);
+        }
+
         this.installedFiles.add(paths.manifestFile());
         this.installedFiles.add(paths.centralConfig());
         this.installedFiles.add(paths.centralUserConfig());
@@ -612,6 +666,76 @@ class Installer {
           );
         }
 
+        // RT-C1 (item 3): registra os hooks copiados acima em
+        // `.claude/settings.json` do projeto — merge puro (hooks-settings.js),
+        // NUNCA em settings.local.json. `.claude/settings.json` vive fora de
+        // `_wizz/`, então — mesmo motivo do .mcp.json/pendingMcpWrite acima —
+        // a escrita real fica adiada para depois do swap A14 num fresh
+        // install (senão um install que falha depois daqui deixaria o
+        // settings.json mutado sem nenhum `_wizz/` correspondente).
+        let pendingHooksSettingsWrite = null;
+        try {
+          const rtkOnPath = this._isCommandOnPath('rtk');
+          const allHookEntries = buildHookEntries(installedHookFiles, { rtkOnPath });
+
+          // Decisão do dono (2026-09-11): pula qualquer hook nosso que já
+          // esteja registrado no settings.json GLOBAL do usuário
+          // (~/.claude/settings.json) — evita o mesmo hook rodar 2x (global +
+          // projeto) numa máquina onde o mantenedor já fez o registro global.
+          // JSON global inválido/ausente = `{}`, o que faz o filtro não
+          // remover nada (mesmo comportamento de "não sei, então registra").
+          const { settings: globalSettings } = await this._readSettingsJson(this._globalSettingsFile());
+          const { entries: hookEntries, skipped: skippedGlobalHooks } = filterHooksRegisteredGlobally(allHookEntries, globalSettings);
+          if (skippedGlobalHooks.length > 0) {
+            await prompts.log.info(
+              `Hook(s) já registrados no settings.json global (~/.claude/settings.json), pulando no projeto para não rodar 2x: ${skippedGlobalHooks.join(', ')}.`,
+            );
+          }
+
+          if (hookEntries.length > 0) {
+            const settingsFile = path.join(paths.projectRoot, '.claude', 'settings.json');
+            const { settings: existingSettings, invalidJson } = await this._readSettingsJson(settingsFile);
+            if (invalidJson) {
+              await prompts.log.warn(
+                `${settingsFile} existe mas não é JSON válido — hooks copiados para _wizz/hooks/, mas NÃO registrados em settings.json. Corrija o arquivo e rode o install de novo.`,
+              );
+              addResult('Hooks settings', 'warn', 'settings.json inválido, hooks não registrados');
+            } else {
+              const newSettings = mergeHooksIntoSettings(existingSettings, hookEntries);
+              pendingHooksSettingsWrite = {
+                file: settingsFile,
+                settings: newSettings,
+                count: hookEntries.length,
+                skipped: skippedGlobalHooks,
+              };
+              if (!paths.isTmp) {
+                // Update (or an install with no tmp scaffold): no swap will
+                // happen below, so write immediately.
+                await this._writeSettingsJson(settingsFile, newSettings);
+                const skippedDetail =
+                  skippedGlobalHooks.length > 0 ? `, ${skippedGlobalHooks.length} pulado(s) por já estar no global` : '';
+                addResult('Hooks settings', 'ok', `${hookEntries.length} hook(s) → .claude/settings.json${skippedDetail}`);
+                pendingHooksSettingsWrite = null;
+              }
+            }
+          } else if (skippedGlobalHooks.length > 0) {
+            addResult(
+              'Hooks settings',
+              'ok',
+              `0 hook(s) → .claude/settings.json (${skippedGlobalHooks.length} pulado(s) por já estar no global)`,
+            );
+          }
+          if (!rtkOnPath && installedHookFiles.includes('rtk-rewrite.sh')) {
+            addResult('Hooks settings', 'warn', 'rtk não encontrado no PATH: rtk-rewrite.sh copiado mas não registrado (opcional)');
+            await prompts.log.info(
+              'rtk não encontrado no PATH: rtk-rewrite.sh foi copiado para _wizz/hooks/ mas NÃO registrado em settings.json (rtk é opcional). Instale rtk e rode o install de novo para ativá-lo.',
+            );
+          }
+        } catch (error) {
+          await prompts.log.warn(`Falha ao registrar hooks em .claude/settings.json: ${error.message}`);
+          addResult('Hooks settings', 'warn', error.message);
+        }
+
         message('Generating manifests...');
         const manifestGen = new ManifestGenerator();
         const preservedModules = originalConfig._preserveModules || [];
@@ -673,6 +797,17 @@ class Installer {
           });
         }
 
+        // Perform the .claude/settings.json hooks write deferred above (RT-C1,
+        // item 3), same reasoning as the .mcp.json deferral right above.
+        if (pendingHooksSettingsWrite) {
+          await this._writeSettingsJson(pendingHooksSettingsWrite.file, pendingHooksSettingsWrite.settings);
+          const skippedDetail =
+            pendingHooksSettingsWrite.skipped.length > 0
+              ? `, ${pendingHooksSettingsWrite.skipped.length} pulado(s) por já estar no global`
+              : '';
+          addResult('Hooks settings', 'ok', `${pendingHooksSettingsWrite.count} hook(s) → .claude/settings.json${skippedDetail}`);
+        }
+
         await this._appendPreservedSkillManifestRows(paths.wizzDir, previousSkillManifestRows, preservedModules);
 
         // Apply post-install --set TOML patches. Runs after writeCentralConfig
@@ -688,6 +823,25 @@ class Installer {
           }
         }
 
+        // Audit item 29: `_wizz/_resolved/_config.json`, the central config
+        // already merged across its four layers, so a skill reads one JSON
+        // instead of spawning `python3 resolve_config.py`. It has to run
+        // HERE, not with the skill snapshots above: on a fresh install those
+        // are generated inside the tmp scaffold, before writeCentralConfig
+        // wrote `_wizz/config.toml` at all — and before the `--set` patches
+        // just applied. Only the central-config half is redone; the skill
+        // snapshots and their index entries stay as they are. Fail-open: a
+        // miss here degrades to `wizz resolve`, never to a broken install.
+        try {
+          const { refreshResolvedConfig } = require('./resolved-config');
+          const centralConfig = await refreshResolvedConfig({ projectRoot: paths.projectRoot, wizzDir: paths.wizzDir });
+          for (const warning of centralConfig.warnings) {
+            await prompts.log.warn(`_resolved/_config.json: ${warning}`);
+          }
+        } catch (error) {
+          await prompts.log.warn(`Falha ao gerar _wizz/_resolved/_config.json (fail-open): ${error.message}`);
+        }
+
         message('Generating help catalog...');
         await this.mergeModuleHelpCatalogs(paths.wizzDir, manifestGen.agents);
         addResult('Help catalog', 'ok');
@@ -930,8 +1084,10 @@ class Installer {
    * Excludes dev-only tests and Python caches so they don't ship to users.
    * Wipes the destination first so files removed or renamed in source
    * don't linger and get recorded as installed. Also seeds
-   * _wizz/custom/.gitignore on fresh installs so *.user.toml overrides
-   * stay out of version control.
+   * _wizz/custom/.gitignore (so *.user.toml overrides stay out of version
+   * control) and _wizz/_config/.gitignore (so hash-cache.json, a local
+   * perf cache with no reason to be committed, item 23/bug 13 fase3
+   * review, stays out too).
    */
   async _installSharedScripts(paths) {
     const srcScriptsDir = path.join(paths.srcDir, 'src', 'scripts');
@@ -954,6 +1110,133 @@ class Installer {
       await fs.writeFile(customGitignore, '*.user.toml\n', 'utf8');
       this.installedFiles.add(customGitignore);
     }
+
+    await this._seedGitignoreLine(paths.configDir, 'hash-cache.json');
+  }
+
+  /**
+   * Idempotently make sure a .gitignore in `dir` contains `line`, without
+   * clobbering any user content already there (bug 13/item 23 gap, fase3
+   * review 2026-09-11: hash-cache.json in _wizz/_config/ is committed by
+   * default because that directory otherwise holds only tracked config).
+   * Creates the file if absent; appends the line if the file exists but is
+   * missing it; does nothing if the line is already present.
+   * @param {string} dir - Directory whose .gitignore should list `line`
+   * @param {string} line - Pattern to ensure is present
+   */
+  async _seedGitignoreLine(dir, line) {
+    const gitignorePath = path.join(dir, '.gitignore');
+    if (!(await fs.pathExists(gitignorePath))) {
+      await fs.writeFile(gitignorePath, `${line}\n`, 'utf8');
+      this.installedFiles.add(gitignorePath);
+      return;
+    }
+    const existing = await fs.readFile(gitignorePath, 'utf8');
+    const hasLine = existing.split('\n').some((l) => l.trim() === line);
+    if (!hasLine) {
+      const withNewline = existing.endsWith('\n') ? existing : `${existing}\n`;
+      await fs.writeFile(gitignorePath, `${withNewline}${line}\n`, 'utf8');
+      this.installedFiles.add(gitignorePath);
+    }
+  }
+
+  /**
+   * RT-C1 (auditoria 2026-09-11): sem isto, `tools/hooks/*` nunca chegava ao
+   * usuário final do pacote publicado — só existiam na máquina do
+   * mantenedor via `npm run sync:global`. Copia os 5 hooks de
+   * `tools/hooks/` (fonte de verdade única — mesma lista que
+   * `tools/sync-global.mjs` usa para `~/.claude/hooks/`, via
+   * `tools/lib/sync-targets.mjs`, para as duas rotas nunca driftarem) para
+   * `_wizz/hooks/` dentro do projeto alvo. Wipes o destino primeiro (mesmo
+   * padrão de `_installSharedScripts`) e preserva o bit de execução do
+   * `.sh` — ele é invocado direto por path em settings.json, não via
+   * `bash file.sh`, então perder +x quebraria silenciosamente.
+   * @param {import('./install-paths').InstallPaths} paths
+   * @returns {Promise<string[]>} basenames copiados (vazio se a fonte não existir)
+   */
+  async _installHooks(paths) {
+    // tools/lib/sync-targets.mjs é ESM; installer.js é CJS — dynamic import
+    // é o jeito padrão de consumir um módulo ESM de dentro de CJS no Node.
+    const { hooksSrcDir, listHookFiles } = await import('../../lib/sync-targets.mjs');
+    const srcDir = hooksSrcDir(paths.srcDir);
+    const hookFiles = listHookFiles(paths.srcDir);
+    if (hookFiles.length === 0) return [];
+
+    const destDir = path.join(paths.wizzDir, 'hooks');
+    await fs.remove(destDir);
+    await fs.ensureDir(destDir);
+    for (const file of hookFiles) {
+      const from = path.join(srcDir, file);
+      const to = path.join(destDir, file);
+      await fs.copyFile(from, to);
+      const stat = await fs.stat(from);
+      await fs.chmod(to, stat.mode);
+    }
+    await this._trackFilesRecursive(destDir);
+    return hookFiles;
+  }
+
+  /**
+   * Detecção síncrona, sem subprocesso, de um binário no PATH — usada para o
+   * gate "só registra rtk-rewrite.sh se rtk estiver instalado" (item 4,
+   * RT-C1: rtk é opcional). Varre `process.env.PATH` procurando um arquivo
+   * executável com esse nome, igual ao que `command -v` faria em shells
+   * POSIX, mas sem pagar o custo/risco de um `exec`.
+   * @param {string} cmd
+   * @returns {boolean}
+   */
+  _isCommandOnPath(cmd) {
+    const pathEnv = process.env.PATH || process.env.Path || '';
+    if (!pathEnv) return false;
+    const dirs = pathEnv.split(path.delimiter).filter(Boolean);
+    const exts = process.platform === 'win32' ? (process.env.PATHEXT || '.EXE;.CMD;.BAT;.COM').split(';') : [''];
+    for (const dir of dirs) {
+      for (const ext of exts) {
+        try {
+          fs.accessSync(path.join(dir, cmd + ext), fs.constants.X_OK);
+          return true;
+        } catch {
+          // não está aqui — segue procurando
+        }
+      }
+    }
+    return false;
+  }
+
+  /**
+   * Path do settings.json GLOBAL do usuário, usado só para o gate "pula hook
+   * já registrado globalmente" (decisão do dono, 2026-09-11). Mesmo padrão de
+   * override que `WIZZ_GLOBAL_SKILLS_DIR` usa em `tools/hooks/wizz-router-
+   * enforce.js`: a env var existe para os testes injetarem um arquivo
+   * temporário em vez de tocar o `~/.claude/settings.json` real da máquina
+   * rodando os testes.
+   * @returns {string}
+   */
+  _globalSettingsFile() {
+    return process.env.WIZZ_GLOBAL_SETTINGS_FILE || path.join(os.homedir(), '.claude', 'settings.json');
+  }
+
+  /**
+   * Lê `.claude/settings.json` do projeto alvo. Arquivo ausente vira `{}`
+   * (nada a preservar). JSON inválido nunca é sobrescrito — devolve
+   * `invalidJson: true` para o chamador avisar e pular (item 3, RT-C1).
+   * @param {string} file
+   * @returns {Promise<{settings: object, invalidJson: boolean}>}
+   */
+  async _readSettingsJson(file) {
+    if (!(await fs.pathExists(file))) return { settings: {}, invalidJson: false };
+    try {
+      const raw = await fs.readFile(file, 'utf8');
+      if (!raw.trim()) return { settings: {}, invalidJson: false };
+      return { settings: JSON.parse(raw), invalidJson: false };
+    } catch {
+      return { settings: {}, invalidJson: true };
+    }
+  }
+
+  async _writeSettingsJson(file, settings) {
+    await fs.ensureDir(path.dirname(file));
+    await fs.writeJson(file, settings, { spaces: 2 });
   }
 
   async _trackFilesRecursive(dir) {
@@ -1221,7 +1504,7 @@ class Installer {
       `    2. Not sure what to do? Invoke the ${color.cyan('wizz-help')} skill and ask it what to do!`,
       '',
       `    Docs and Guides: ${color.blue('https://method.wizzcomms.com/')}`,
-      `    Source: ${color.blue('https://github.com/wizzcomms/wizz-method/')}`,
+      `    Support: ${color.blue('support@wizzcomms.com')}`,
     );
 
     await prompts.box(lines.join('\n'), 'Wizz Method is ready to use!', {
@@ -1417,8 +1700,7 @@ class Installer {
    * @returns {Promise<Object>} { wizzDir: string }
    */
   async findWizzDir(projectDir) {
-    const wizzDir = path.join(projectDir, WIZZ_FOLDER_NAME);
-    return { wizzDir };
+    return findWizzDir(projectDir);
   }
 
   /**
@@ -1495,4 +1777,4 @@ class Installer {
   }
 }
 
-module.exports = { Installer };
+module.exports = { Installer, findWizzDir };

package/tools/installer/core/legacy-warnings.js

@@ -144,8 +144,4 @@ async function warnPreNativeSkillsLegacy({ projectRoot, existingVersion } = {})
 
 module.exports = {
   warnPreNativeSkillsLegacy,
-  findStaleLegacyDirs,
-  isPreNativeSkillsVersion,
-  LEGACY_PATHS,
-  MIN_NATIVE_SKILLS_VERSION,
 };

package/tools/installer/core/manifest-generator.js

@@ -1,13 +1,20 @@
 const path = require('node:path');
 const fs = require('../fs-native');
 const yaml = require('yaml');
-const crypto = require('node:crypto');
 const { resolveInstalledModuleYaml } = require('../project-root');
 const prompts = require('../prompts');
 
 // Load package.json for version info
 const packageJson = require('../../../package.json');
 
+// Concurrency cap for the files-manifest hashing pass (F05 in the
+// 2026-09-11 audit): hundreds/thousands of installed files hashed one at a
+// time was the dominant cost of "Generating manifests" on large trees
+// (e.g. src/skills-lib/). Batched via fs.batchMap, which also memoizes
+// (path+size+mtime) so a file already hashed elsewhere in this same process
+// (e.g. user-file-preservation's "before" pass, F10) isn't re-read.
+const HASH_BATCH_SIZE = 32;
+
 /**
  * Generates manifest files for installed skills and agents
  */
@@ -345,6 +352,14 @@ class ManifestGenerator {
 
     // Fetch fresh version info for all modules
     const { Manifest } = require('./manifest');
+    // Item 8 fase 2 (auditoria 2026-09-11, EXT-02 / IM-ACH-06): the SHA the
+    // user requested via `--pin CODE=TAG@SHA` isn't part of
+    // Manifest#getModuleVersionInfo's return shape (that lives in
+    // manifest.js, out of scope for this change) — read it straight from
+    // ExternalModuleManager's in-process resolution cache instead, the same
+    // source getModuleVersionInfo itself reads `sha`/`channel` from.
+    const { ExternalModuleManager } = require('../modules/external-manager');
+    const externalModuleManager = new ExternalModuleManager();
     const manifestObj = new Manifest();
     const updatedModules = [];
 
@@ -370,6 +385,12 @@ class ManifestGenerator {
       const sha = versionInfo.sha ?? existing?.sha;
       if (channel) moduleEntry.channel = channel;
       if (sha) moduleEntry.sha = sha;
+      // shaRequested: the SHA half of a `--pin CODE=TAG@SHA`, when the user
+      // supplied one. Absent for modules pinned by tag alone (or not pinned
+      // at all) — never written in that case, so older manifests without
+      // this field stay valid and round-trip unchanged.
+      const shaRequested = externalModuleManager.getResolution(moduleName)?.expectedSha ?? existing?.shaRequested;
+      if (shaRequested) moduleEntry.shaRequested = shaRequested;
       if (versionInfo.localPath || existing?.localPath) {
         moduleEntry.localPath = versionInfo.localPath || existing.localPath;
       }
@@ -677,17 +698,17 @@ class ManifestGenerator {
    * Write files manifest CSV
    */
   /**
-   * 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. This wrapper keeps
+   * this class's historical contract of resolving to '' (not null) when the
+   * file can't be read, since that's the value written into files-manifest.csv.
    * @param {string} filePath - Path to file
-   * @returns {string} SHA256 hash
+   * @returns {string} SHA256 hash, or '' 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 '';
-    }
+    const hash = await fs.calculateFileHash(filePath);
+    return hash ?? '';
   }
 
   /**
@@ -696,49 +717,106 @@ class ManifestGenerator {
   async writeFilesManifest(cfgDir) {
     const csvPath = path.join(cfgDir, 'files-manifest.csv');
 
+    // Incremental hashing (audit item 23): load the previous run's
+    // size+mtime → hash cache; files whose stat matches skip the read+hash
+    // entirely. Fail-open: missing/corrupt cache = cold start.
+    const { loadHashCache, getCachedHash, buildHashCache, saveHashCache } = require('./hash-cache');
+    const previousCache = await loadHashCache(cfgDir);
+    const freshHashes = [];
+
     // Create CSV header with hash column
     let csv = 'type,name,module,path,hash\n';
 
     // If we have ALL installed files, use those instead of just workflows/agents/tasks
-    const allFiles = [];
+    // Hashing every installed file is I/O-bound and independent per file, so
+    // batch it with bounded concurrency (F05) instead of one file at a time.
+    // The final list is sorted below regardless of resolution order, so the
+    // written CSV stays byte-for-byte identical to the sequential version.
+    let allFiles;
     if (this.allInstalledFiles && this.allInstalledFiles.length > 0) {
-      // Process all installed files
-      for (const filePath of this.allInstalledFiles) {
-        // Store paths relative to wizzDir (no folder prefix)
-        const relativePath = filePath.replace(this.wizzDir, '').replaceAll('\\', '/').replace(/^\//, '');
-        const ext = path.extname(filePath).toLowerCase();
-        const fileName = path.basename(filePath, ext);
-
-        // Determine module from path (first directory component)
-        const pathParts = relativePath.split('/');
-        const module = pathParts.length > 0 ? pathParts[0] : 'unknown';
-
-        // Calculate hash
-        const hash = await this.calculateFileHash(filePath);
-
-        allFiles.push({
-          type: ext.slice(1) || 'file',
-          name: fileName,
-          module: module,
-          path: relativePath,
-          hash: hash,
-        });
-      }
+      allFiles = await fs.batchMap(
+        [...this.allInstalledFiles],
+        async (filePath) => {
+          // Store paths relative to wizzDir (no folder prefix)
+          const relativePath = filePath.replace(this.wizzDir, '').replaceAll('\\', '/').replace(/^\//, '');
+          const ext = path.extname(filePath).toLowerCase();
+          const fileName = path.basename(filePath, ext);
+
+          // Determine module from path (first directory component)
+          const pathParts = relativePath.split('/');
+          const module = pathParts.length > 0 ? pathParts[0] : 'unknown';
+
+          // Incremental (item 23): reuse the cached hash when size+mtime
+          // match the previous run, else hash and record the new stat.
+          let hash = null;
+          try {
+            const stat = await fs.stat(filePath);
+            hash = getCachedHash(previousCache, relativePath, stat);
+            if (hash === null) {
+              hash = await this.calculateFileHash(filePath);
+              if (hash)
+                freshHashes.push({
+                  relPath: relativePath,
+                  size: stat.size,
+                  mtimeMs: stat.mtimeMs,
+                  ctimeMs: stat.ctimeMs,
+                  hash,
+                });
+            }
+          } catch {
+            hash = await this.calculateFileHash(filePath);
+          }
+
+          return {
+            type: ext.slice(1) || 'file',
+            name: fileName,
+            module: module,
+            path: relativePath,
+            hash: hash,
+          };
+        },
+        HASH_BATCH_SIZE,
+      );
     } else {
       // Fallback: use the collected workflows/agents/tasks
-      for (const file of this.files) {
-        // Strip the folder prefix if present (for consistency)
-        const relPath = file.path.replace(this.wizzFolderName + '/', '');
-        const filePath = path.join(this.wizzDir, relPath);
-        const hash = await this.calculateFileHash(filePath);
-        allFiles.push({
-          ...file,
-          path: relPath,
-          hash: hash,
-        });
-      }
+      allFiles = await fs.batchMap(
+        this.files,
+        async (file) => {
+          // Strip the folder prefix if present (for consistency)
+          const relPath = file.path.replace(this.wizzFolderName + '/', '');
+          const filePath = path.join(this.wizzDir, relPath);
+
+          // Incremental (item 23): same cache shortcut as the full path above.
+          let hash = null;
+          try {
+            const stat = await fs.stat(filePath);
+            hash = getCachedHash(previousCache, relPath, stat);
+            if (hash === null) {
+              hash = await this.calculateFileHash(filePath);
+              if (hash) freshHashes.push({ relPath, size: stat.size, mtimeMs: stat.mtimeMs, ctimeMs: stat.ctimeMs, hash });
+            }
+          } catch {
+            hash = await this.calculateFileHash(filePath);
+          }
+          return {
+            ...file,
+            path: relPath,
+            hash: hash,
+          };
+        },
+        HASH_BATCH_SIZE,
+      );
     }
 
+    // Persist the cache next to the CSV (best-effort), pruned to exactly the
+    // paths this run wrote — a file dropped from the install (removed
+    // module, rename) drops out of the cache too instead of lingering.
+    // Fresh installs (A14) call this while wizzDir is still the tmp
+    // scaffold, so the cache lands inside the scaffold and is renamed into
+    // place with the swap — the next update starts warm.
+    const currentPaths = allFiles.map((file) => file.path);
+    await saveHashCache(cfgDir, buildHashCache(previousCache, freshHashes, currentPaths));
+
     // Sort files by module, then type, then name
     allFiles.sort((a, b) => {
       if (a.module !== b.module) return a.module.localeCompare(b.module);