wizz-method 2.0.0 → 2.1.0

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

@@ -0,0 +1,262 @@
+/**
+ * Include expansion for customize.toml layers.
+ *
+ * Extracted from `resolved-customizations.js` (2026-09-11) to keep that file
+ * under the 800-line cap and to give the `_shared/` fallback a home. Kept in
+ * lock-step with `src/scripts/resolve_customization.py`: the two resolvers
+ * must produce byte-identical JSON, and `test/test-resolved-customizations.js`
+ * diffs them on every run.
+ *
+ * The `_shared/` fallback (bug found 2026-09-11): the verbatim pipeline moves
+ * each skill directory OUT of `_wizz/` into the IDE folder, e.g.
+ * `.claude/skills/wizz-maestro/customize.toml`, while that file keeps its
+ * shipped `include = ["../../_shared/communication-rules.md"]`. From the
+ * deployed location that relative path resolves to `.claude/_shared/...`,
+ * which does not exist, so every included paragraph was dropped silently.
+ * The real shared files live at `<project-root>/_wizz/<module>/_shared/`.
+ * So: when the base-relative path is missing AND the include mentions
+ * `_shared/`, the segment after the LAST `_shared/` is looked up under
+ * `<project-root>/_wizz/<module>/_shared/` for every module that has one,
+ * in sorted order, first hit wins. Nothing else is guessed.
+ *
+ * Containment (hardening, 2026-09-11): when a project root is known, an
+ * include whose base-relative path escapes that root (`../../../../x.md`) is
+ * refused before it is ever read — a customize.toml must not pull arbitrary
+ * files from the user's home or from a sibling checkout into an agent's
+ * activation steps. The `_shared/` fallback candidates are built under
+ * `<project-root>/_wizz/` by construction, so they always pass. A standalone
+ * skill (no project root resolvable) keeps the old unrestricted behaviour —
+ * there is no root to be outside of. `resolve_customization.py` implements
+ * the identical rule with the identical wording.
+ */
+
+const path = require('node:path');
+const nodeFs = require('node:fs');
+const { WIZZ_FOLDER_NAME } = require('../ide/shared/path-utils');
+
+const INCLUDE_TARGET_FIELD = 'activation_steps_append';
+const SHARED_DIR_NAME = '_shared';
+
+// Keys that JavaScript treats specially on assignment: writing
+// `obj.__proto__ = x` walks the Object.prototype setter (mutating the
+// prototype chain) instead of creating an own property, so `[agent.__proto__]`
+// in a customize.toml silently disappeared from the snapshot. smol-toml
+// itself parses into null-prototype objects, so the only unsafe step was
+// ours — every write goes through `safeSet`.
+const DANGEROUS_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
+
+/**
+ * Define `key` on `target` as a plain own data property, bypassing the
+ * `__proto__` setter and any inherited accessor. Parity with Python dicts,
+ * where these are ordinary keys.
+ */
+function safeSet(target, key, value) {
+  if (DANGEROUS_KEYS.has(key)) {
+    Object.defineProperty(target, key, { value, writable: true, enumerable: true, configurable: true });
+  } else {
+    target[key] = value;
+  }
+  return target;
+}
+
+function hasOwn(obj, key) {
+  return Object.prototype.hasOwnProperty.call(obj, key);
+}
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function isFile(absPath) {
+  try {
+    return nodeFs.statSync(absPath).isFile();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Split an included markdown file into instruction strings: blocks
+ * separated by a blank line, internal newlines collapsed to single
+ * spaces, blocks made only of `#` lines dropped. Python
+ * `_split_include_paragraphs` parity.
+ */
+function splitIncludeParagraphs(text) {
+  const paragraphs = [];
+  for (const block of text.trim().split(/\n\s*\n/)) {
+    const lines = block
+      .split('\n')
+      .map((line) => line.trim())
+      .filter((line) => line.length > 0);
+    if (lines.every((line) => line.startsWith('#'))) continue;
+    paragraphs.push(lines.join(' '));
+  }
+  return paragraphs;
+}
+
+/**
+ * Absolute candidates for an include whose base-relative path is missing.
+ * Empty unless `relPath` mentions `_shared/` and a project root is known.
+ * Deterministic: modules sorted by name, first existing hit wins upstream.
+ * Python `_shared_fallback_candidates` parity.
+ * @param {string} relPath - the include as written in the TOML
+ * @param {string|null} projectRoot
+ * @returns {string[]}
+ */
+function sharedFallbackCandidates(relPath, projectRoot) {
+  if (!projectRoot || typeof relPath !== 'string') return [];
+  const posix = relPath.split('\\').join('/');
+  const marker = `${SHARED_DIR_NAME}/`;
+  const index = posix.lastIndexOf(marker);
+  if (index === -1) return [];
+  const segment = posix.slice(index + marker.length);
+  const parts = segment.split('/');
+  if (segment.length === 0 || parts.some((part) => part === '' || part === '..' || part === '.')) return [];
+
+  const wizzRoot = path.join(projectRoot, WIZZ_FOLDER_NAME);
+  let modules;
+  try {
+    modules = nodeFs
+      .readdirSync(wizzRoot, { withFileTypes: true })
+      .filter((entry) => entry.isDirectory())
+      .map((entry) => entry.name)
+      .sort();
+  } catch {
+    return [];
+  }
+  const candidates = [];
+  for (const name of modules) {
+    const sharedDir = path.join(wizzRoot, name, SHARED_DIR_NAME);
+    let stat;
+    try {
+      stat = nodeFs.statSync(sharedDir);
+    } catch {
+      continue;
+    }
+    if (!stat.isDirectory()) continue;
+    candidates.push(path.join(sharedDir, ...parts));
+  }
+  return candidates;
+}
+
+/**
+ * True when the base-relative include escapes the project root. Lexical
+ * (`path.resolve` normalizes `..` without touching the filesystem), so a
+ * missing file is judged the same way an existing one is. No project root →
+ * never outside. Python `_is_outside_project_root` parity.
+ * @param {string} baseDir
+ * @param {string} relPath
+ * @param {string|null} projectRoot
+ * @returns {boolean}
+ */
+function isOutsideProjectRoot(baseDir, relPath, projectRoot) {
+  if (!projectRoot) return false;
+  const primary = path.resolve(baseDir, relPath);
+  const rel = path.relative(path.resolve(projectRoot), primary);
+  if (rel === '') return false;
+  return rel === '..' || rel.startsWith(`..${path.sep}`) || path.isAbsolute(rel);
+}
+
+/** The one escaped-include sentence, worded identically in both resolvers. */
+function outsideRootMessage(relPath, skillName) {
+  return `include outside the project root, skipping: "${relPath}" (skill: ${skillName || '?'})`;
+}
+
+/**
+ * Absolute path of the file an `include` entry actually points at, or null.
+ * Base-relative first, then the `_shared/` fallback. Python
+ * `_find_include_file` parity.
+ */
+function findIncludeFile(baseDir, relPath, projectRoot) {
+  const primary = path.resolve(baseDir, relPath);
+  if (isFile(primary)) return primary;
+  for (const candidate of sharedFallbackCandidates(relPath, projectRoot)) {
+    if (isFile(candidate)) return candidate;
+  }
+  return null;
+}
+
+/** The one missing-include sentence, worded identically in both resolvers. */
+function missingIncludeMessage(relPath, skillName, primary) {
+  return `include not found, skipping: "${relPath}" (skill: ${skillName || '?'}; tried ${primary} and every ${WIZZ_FOLDER_NAME}/*/${SHARED_DIR_NAME}/)`;
+}
+
+/**
+ * Expand `include = [...]` in any table: each referenced file's
+ * paragraphs are PREPENDED onto that table's `activation_steps_append`
+ * (created if absent), the `include` key itself removed, recursion into
+ * nested tables. Paths resolve relative to the declaring TOML's
+ * directory, with the `_shared/` fallback above when that misses.
+ * Missing/unreadable files warn and are skipped (fail-open).
+ * Python `resolve_includes` parity.
+ *
+ * @param {object} data
+ * @param {string} baseDir - directory of the TOML that declared the include
+ * @param {string[]} warnings - sink for fail-open warnings
+ * @param {string[]} [inputs] - optional sink: every include file actually
+ *   read is pushed here (absolute path, the FALLBACK path when that is what
+ *   was used) so the caller can hash it into `_resolved/.index.json`.
+ * @param {{projectRoot?: string, skillName?: string}} [context]
+ */
+function resolveIncludes(data, baseDir, warnings, inputs, context = {}) {
+  if (!isPlainObject(data)) return data;
+  const projectRoot = context.projectRoot || null;
+  const skillName = context.skillName || '';
+
+  const includedParagraphs = [];
+  if (Array.isArray(data.include)) {
+    for (const relPath of data.include) {
+      if (typeof relPath !== 'string') {
+        warnings.push(`include entries must be strings, got: ${JSON.stringify(relPath)}`);
+        continue;
+      }
+      if (isOutsideProjectRoot(baseDir, relPath, projectRoot)) {
+        warnings.push(outsideRootMessage(relPath, skillName));
+        continue;
+      }
+      const fullPath = findIncludeFile(baseDir, relPath, projectRoot);
+      let text = null;
+      if (fullPath === null) {
+        warnings.push(missingIncludeMessage(relPath, skillName, path.resolve(baseDir, relPath)));
+      } else {
+        try {
+          text = nodeFs.readFileSync(fullPath, 'utf8');
+        } catch {
+          warnings.push(`include not readable, skipping: ${fullPath}`);
+        }
+      }
+      if (text !== null) {
+        if (inputs) inputs.push(fullPath);
+        includedParagraphs.push(...splitIncludeParagraphs(text));
+      }
+    }
+  } else if ('include' in data) {
+    warnings.push(`'include' must be an array of strings, got: ${JSON.stringify(data.include)}`);
+  }
+
+  const result = {};
+  for (const [key, value] of Object.entries(data)) {
+    if (key === 'include') continue;
+    safeSet(result, key, isPlainObject(value) ? resolveIncludes(value, baseDir, warnings, inputs, context) : value);
+  }
+
+  if (includedParagraphs.length > 0) {
+    const existing = Array.isArray(result[INCLUDE_TARGET_FIELD]) ? result[INCLUDE_TARGET_FIELD] : [];
+    result[INCLUDE_TARGET_FIELD] = [...includedParagraphs, ...existing];
+  }
+  return result;
+}
+
+module.exports = {
+  resolveIncludes,
+  splitIncludeParagraphs,
+  sharedFallbackCandidates,
+  findIncludeFile,
+  isOutsideProjectRoot,
+  outsideRootMessage,
+  safeSet,
+  hasOwn,
+  isPlainObject,
+  INCLUDE_TARGET_FIELD,
+  SHARED_DIR_NAME,
+};

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

@@ -0,0 +1,148 @@
+/**
+ * Closed key sets for `customize.toml` (audit item 24, 2026-09-11).
+ *
+ * Extracted from `resolved-customizations.js` (2026-09-11) to keep that file
+ * under the 800-line cap. Validation only: nothing here writes, parses or
+ * merges — it takes ONE parsed layer and reports the keys no code consumes.
+ *
+ * "additionalProperties: false" in spirit. The BASE layer (shipped,
+ * code-reviewed) is exempt: it may legitimately carry LLM-only fields
+ * (door/rel/not_when-style prose the agents read but no code consumes) and
+ * new experimental fields. TEAM/USER layers are user-authored, where a typo'd
+ * key (`persistant_facts`) merges into silence today — deepMerge applies it,
+ * nothing reads it, the user believes the knob turned. Each unknown key there
+ * is a warning (not an error: fail-open, the snapshot is still written).
+ * `include` is the documented extension point and is validated by
+ * `resolveIncludes`.
+ */
+
+const { isPlainObject } = require('./resolved-includes');
+
+const WORKFLOW_KEYS = new Set([
+  // steps & facts
+  'activation_steps_prepend',
+  'activation_steps_append',
+  'persistent_facts',
+  'on_complete',
+  'include',
+  // output & templates
+  'output_dir',
+  'output_folder_name',
+  'run_folder_pattern',
+  'ux_output_path',
+  'prd_template',
+  'prd_output_path',
+  'validation_report_template',
+  'validation_checklist_template',
+  'spec_template',
+  'spec_filename',
+  'spec_output_path',
+  'spine_template',
+  'spine_output_path',
+  'brief_template',
+  'brief_output_path',
+  'case_file_template',
+  'case_file_subdir',
+  'case_file_filename',
+  'forge_output_path',
+  'methods_file',
+  'brain_methods',
+  // examples & handoffs
+  'design_md_examples',
+  'experience_md_examples',
+  'design_handoffs',
+  'external_sources',
+  'external_handoffs',
+  'finalize_reviewers',
+  'creative_tools',
+  'doc_standards',
+  // techniques & preferences
+  'favorite_techniques',
+  'additional_techniques',
+  'preferences',
+  'additional_methods',
+  // party mode
+  'default_party',
+  'party_mode',
+  'party_memory',
+  'memory_dir',
+  'party_members',
+  'party_groups',
+  // review layers (wizz-code-review, wizz-quick-dev): arrays of tables whose
+  // item keys are validated against REVIEW_LAYER_KEYS below.
+  'review_layers',
+  'oneshot_review_layers',
+]);
+const PARTY_MEMBER_KEYS = new Set(['code', 'name', 'icon', 'title', 'persona', 'capabilities', 'model']);
+const PARTY_GROUP_KEYS = new Set(['id', 'name', 'scene', 'members', 'memory']);
+// Exactly the keys the 8 shipped `[[workflow.*review_layers]]` entries use
+// (src/bmm-skills/4-implementation/wizz-code-review + wizz-quick-dev).
+const REVIEW_LAYER_KEYS = new Set(['id', 'name', 'instruction', 'when']);
+// The only top-level keys any of the 47 shipped customize.toml carry. A
+// top-level typo (`[workflw]`) or a stray scalar merged into silence before.
+const TOP_LEVEL_KEYS = new Set(['workflow', 'agent', 'include']);
+
+/**
+ * Collect unknown keys under `[workflow]`: unknown fields by name, and for
+ * the arrays-of-tables we own (party members/groups, review layers) the
+ * unknown keys of each item.
+ * @returns {string[]} dotted paths
+ */
+function findUnknownWorkflowKeys(workflow) {
+  const unknown = [];
+  for (const [k2, v2] of Object.entries(workflow)) {
+    const wfPath = `workflow.${k2}`;
+    if (!WORKFLOW_KEYS.has(k2)) {
+      unknown.push(wfPath);
+      continue;
+    }
+    if (!Array.isArray(v2) || v2.length === 0 || !v2.every((it) => isPlainObject(it))) continue;
+    const allowed =
+      k2 === 'party_members'
+        ? PARTY_MEMBER_KEYS
+        : k2 === 'party_groups'
+          ? PARTY_GROUP_KEYS
+          : k2.includes('review_layers')
+            ? REVIEW_LAYER_KEYS
+            : null;
+    if (!allowed) continue;
+    for (const item of v2) {
+      for (const k3 of Object.keys(item)) {
+        if (!allowed.has(k3)) unknown.push(`${wfPath}[].${k3}`);
+      }
+    }
+  }
+  return unknown;
+}
+
+/**
+ * Walk a loaded TOML layer and collect unknown keys: unknown TOP-level
+ * tables/scalars (anything outside `workflow`, `agent`, `include`) plus the
+ * `[workflow]` fields and array-of-table item keys. `[agent]` is prose the
+ * LLM reads, not a code-consumed schema, so its keys are open by design;
+ * `include` is validated by resolveIncludes.
+ * @param {object} data - a single layer, as parsed (never a merged tree)
+ * @returns {string[]} dotted paths (caller prefixes with layer info)
+ */
+function findUnknownKeys(data) {
+  const unknown = [];
+  if (!isPlainObject(data)) return unknown;
+  for (const [key, value] of Object.entries(data)) {
+    if (!TOP_LEVEL_KEYS.has(key)) {
+      unknown.push(key);
+      continue;
+    }
+    if (key === 'workflow' && isPlainObject(value)) unknown.push(...findUnknownWorkflowKeys(value));
+  }
+  return unknown;
+}
+
+module.exports = {
+  findUnknownKeys,
+  findUnknownWorkflowKeys,
+  WORKFLOW_KEYS,
+  PARTY_MEMBER_KEYS,
+  PARTY_GROUP_KEYS,
+  REVIEW_LAYER_KEYS,
+  TOP_LEVEL_KEYS,
+};

package/tools/installer/core/user-file-preservation.js

@@ -39,6 +39,13 @@ async function detectCustomFiles(wizzDir, existingFilesManifest, { manifest }) {
     manifestHasHashes = existingFilesManifest.some((f) => f.hash);
   }
 
+  // Persistent stat → hash cache (audit item 23, written by
+  // manifest-generator alongside files-manifest.csv). Fail-open: absent or
+  // corrupt cache = every file falls through to the full hash below.
+  const { loadHashCache, getCachedHash } = require('./hash-cache');
+  const hashCache = await loadHashCache(path.join(wizzDir, '_config'));
+  const relPathOf = (fullPath) => path.relative(wizzDir, fullPath).replaceAll('\\', '/');
+
   // Build map of previously installed files from files-manifest.csv with their hashes
   const installedFilesMap = new Map();
   for (const fileEntry of existingFilesManifest) {
@@ -97,6 +104,15 @@ async function detectCustomFiles(wizzDir, existingFilesManifest, { manifest }) {
             continue;
           }
 
+          // Skip _resolved/ — generated snapshots of resolved customizations
+          // (_wizz/_resolved/<skill>.json + .index.json, item 19), gitignored,
+          // not in the manifest, regenerated at update. Same treatment as
+          // _config/ above, minus the exception: these are pure build output,
+          // never something a user hand-edits.
+          if (relativePath.startsWith('_resolved/') || relativePath.startsWith('_resolved\\')) {
+            continue;
+          }
+
           if (wizzMemoryPaths.some((mp) => relativePath === mp || relativePath.startsWith(mp + '/'))) {
             continue;
           }
@@ -114,14 +130,30 @@ async function detectCustomFiles(wizzDir, existingFilesManifest, { manifest }) {
               customFiles.push(fullPath);
             }
           } else if (manifestHasHashes && fileInfo.hash) {
-            // File in manifest with hash - check if it was modified
-            const currentHash = await manifest.calculateFileHash(fullPath);
-            if (currentHash && currentHash !== fileInfo.hash) {
-              // Hash changed = file was modified
-              modifiedFiles.push({
-                path: fullPath,
-                relativePath: fileInfo.relativePath,
-              });
+            // File in manifest with hash - check if it was modified.
+            // Incremental (audit item 23): consult the persistent
+            // size+mtime → hash cache first; a stat match proves the file
+            // is byte-identical to the last install, skipping the read
+            // entirely. Cache miss falls through to the full hash.
+            let unchangedByCache = false;
+            try {
+              const stat = await fs.stat(fullPath);
+              const cachedHash = getCachedHash(hashCache, relPathOf(fullPath), stat);
+              if (cachedHash !== null) {
+                unchangedByCache = true;
+              }
+            } catch {
+              // stat failed — hash below will handle the missing file
+            }
+            if (!unchangedByCache) {
+              const currentHash = await manifest.calculateFileHash(fullPath);
+              if (currentHash && currentHash !== fileInfo.hash) {
+                // Hash changed = file was modified
+                modifiedFiles.push({
+                  path: fullPath,
+                  relativePath: fileInfo.relativePath,
+                });
+              }
             }
           }
         }

package/tools/installer/core/wizz-dir.js

@@ -0,0 +1,117 @@
+/**
+ * Resolução do diretório de instalação `_wizz/` — dono único (item 20,
+ * auditoria 2026-09-11).
+ *
+ * Antes deste módulo havia quatro `findWizzDir` espalhados
+ * (core/installer.js, modules/module-catalog.js, ide/_config-driven.js e
+ * tools/migrate-custom-module-paths.js) e eles NÃO eram equivalentes: dois
+ * devolviam `null` quando o diretório não existe, um varria o projeto atrás
+ * de `<dir>/_config/manifest.yaml` (instalação V6+ com nome de pasta
+ * customizado) e um era só um `path.join`. Em vez de apagar comportamento, as
+ * quatro variantes moram aqui, nomeadas pelo que cada uma promete; os callers
+ * passam a importar a que já usavam.
+ *
+ * Módulo folha de propósito: além de `node:path` só importa `fs-native` e o
+ * `path-utils` do IDE (que por sua vez não importa nada), então não pode
+ * entrar em ciclo de require.
+ */
+
+const path = require('node:path');
+const fs = require('../fs-native');
+const { WIZZ_FOLDER_NAME } = require('../ide/shared/path-utils');
+
+/**
+ * Pure helper: compute the `_wizz` directory path for a project. No I/O, no
+ * instance state — callers that only need this path-join should call it
+ * directly instead of constructing a full `Installer` (which also builds an
+ * ExternalModuleManager, Manifest, IdeManager, ...) just to reach it (audit
+ * 2026-09-11, IC-F03).
+ * @param {string} projectDir - Project directory
+ * @returns {{wizzDir: string}}
+ */
+function findWizzDir(projectDir) {
+  return { wizzDir: path.join(projectDir, WIZZ_FOLDER_NAME) };
+}
+
+/**
+ * The same path as `findWizzDir`, unwrapped. For callers that want the string
+ * and not the `{ wizzDir }` envelope.
+ * @param {string} projectDir - Project directory
+ * @returns {string}
+ */
+function wizzDirPath(projectDir) {
+  return path.join(projectDir, WIZZ_FOLDER_NAME);
+}
+
+/**
+ * `_wizz/` path when it already exists on disk, else null. Used by the IDE
+ * handlers' `detect()`, where "no install here" must stay distinguishable
+ * from "install at this path".
+ * @param {string} projectDir - Project directory
+ * @returns {Promise<string|null>} Path to wizz dir or null
+ */
+async function findExistingWizzDir(projectDir) {
+  const wizzDir = path.join(projectDir, WIZZ_FOLDER_NAME);
+  return (await fs.pathExists(wizzDir)) ? wizzDir : null;
+}
+
+/**
+ * Synchronous variant of `findExistingWizzDir`, for the one-shot migration
+ * scripts that run outside the installer's async pipeline.
+ * @param {string} [projectDir] - Project directory (defaults to cwd)
+ * @returns {string|null} Path to wizz dir or null
+ */
+function findExistingWizzDirSync(projectDir = process.cwd()) {
+  const wizzDir = path.join(projectDir, WIZZ_FOLDER_NAME);
+  return fs.existsSync(wizzDir) ? wizzDir : null;
+}
+
+/**
+ * Locate the wizz installation directory of a project by its V6+ marker.
+ *
+ * V6+ installations can use ANY folder name but ALWAYS have
+ * `_config/manifest.yaml`, so this scans the project's direct children for
+ * that file instead of assuming `_wizz`. Falls back to `<projectDir>/wizz`
+ * (the historical default of this code path — note: no leading underscore,
+ * unlike WIZZ_FOLDER_NAME) when nothing is found, which is what new
+ * installations get.
+ * @param {string} projectDir - Project directory
+ * @returns {Promise<string>} Path to wizz directory
+ */
+async function detectWizzDir(projectDir) {
+  // Check if project directory exists
+  if (!(await fs.pathExists(projectDir))) {
+    // Project doesn't exist yet, return default
+    return path.join(projectDir, 'wizz');
+  }
+
+  // V6+ strategy: Look for ANY directory with _config/manifest.yaml
+  // This is the definitive marker of a V6+ installation
+  try {
+    const entries = await fs.readdir(projectDir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        const manifestPath = path.join(projectDir, entry.name, '_config', 'manifest.yaml');
+        if (await fs.pathExists(manifestPath)) {
+          // Found a V6+ installation
+          return path.join(projectDir, entry.name);
+        }
+      }
+    }
+  } catch {
+    // Ignore errors, fall through to default
+  }
+
+  // No V6+ installation found, return default
+  // This will be used for new installations
+  return path.join(projectDir, 'wizz');
+}
+
+module.exports = {
+  WIZZ_FOLDER_NAME,
+  findWizzDir,
+  wizzDirPath,
+  findExistingWizzDir,
+  findExistingWizzDirSync,
+  detectWizzDir,
+};