wizz-method 2.1.0 → 2.2.0

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

@@ -78,11 +78,35 @@ function detectKeyedMergeField(items) {
   return null;
 }
 
+/**
+ * Warn when a team/user override REPLACES a base review layer (matched by
+ * `id`/`code`) but omits `tiers` or `max_calls` the base layer had.
+ * `mergeByKey` replaces the whole matched item — it never merges an
+ * override item field-by-field against its base counterpart (Python
+ * parity) — so dropping those fields silently loses the base layer's
+ * scaling: the layer now runs on every tier and/or with no call cap.
+ * No-op when `opts.warnings`/`opts.layerLabel` are not supplied, so callers
+ * that don't care about this (e.g. direct `deepMerge` calls in tests) pay
+ * nothing for it.
+ */
+function warnOverrideDropsLayerScaling({ warnings, layerLabel, key, matchedBase, item }) {
+  if (!warnings || !layerLabel) return;
+  const missing = ['tiers', 'max_calls'].filter((field) => hasOwn(matchedBase, field) && !hasOwn(item, field));
+  if (missing.length === 0) return;
+  const consequence = missing.map((field) => (field === 'tiers' ? 'every tier' : 'uncapped')).join(' and ');
+  warnings.push(
+    `${layerLabel} override: "${key}" replaces the whole base layer and omits ${missing.join(' and ')} — it now runs on ${consequence}`,
+  );
+}
+
 /**
  * Keyed merge: matching identifiers replace in place, new ones append.
  * Non-table items in the override are appended (Python parity).
+ * @param {object} [opts] - `{ warnings, layerLabel }` to collect the
+ *   dropped-scaling warning above; omit for warning-free merges (tests,
+ *   internal recomputation).
  */
-function mergeByKey(base, override, keyName) {
+function mergeByKey(base, override, keyName, opts) {
   const result = [];
   const indexByKey = new Map();
   for (const item of base) {
@@ -99,7 +123,9 @@ function mergeByKey(base, override, keyName) {
     }
     const key = item[keyName];
     if (key !== undefined && key !== null && indexByKey.has(key)) {
-      result[indexByKey.get(key)] = { ...item };
+      const matchedIndex = indexByKey.get(key);
+      if (opts) warnOverrideDropsLayerScaling({ ...opts, key, matchedBase: result[matchedIndex], item });
+      result[matchedIndex] = { ...item };
     } else {
       if (key !== undefined && key !== null) indexByKey.set(key, result.length);
       result.push({ ...item });
@@ -112,30 +138,33 @@ function mergeByKey(base, override, keyName) {
  * Shape-aware array merge: keyed merge when every item (base + override)
  * shares `code` or `id`, else append.
  */
-function mergeArrays(base, override) {
+function mergeArrays(base, override, opts) {
   const baseArr = Array.isArray(base) ? base : [];
   const overrideArr = Array.isArray(override) ? override : [];
   const keyedField = detectKeyedMergeField([...baseArr, ...overrideArr]);
-  if (keyedField) return mergeByKey(baseArr, overrideArr, keyedField);
+  if (keyedField) return mergeByKey(baseArr, overrideArr, keyedField, opts);
   return [...baseArr, ...overrideArr];
 }
 
 /**
  * Structural deep merge. Tables deep-merge, arrays shape-merge,
  * everything else: override wins. Python `deep_merge` parity.
+ * @param {object} [opts] - `{ warnings, layerLabel }`, threaded down to
+ *   every `mergeByKey` call reached while walking `base`/`override`; see
+ *   `warnOverrideDropsLayerScaling`.
  */
-function deepMerge(base, override) {
+function deepMerge(base, override, opts) {
   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);
+      safeSet(result, key, hasOwn(result, key) ? deepMerge(result[key], overVal, opts) : overVal);
     }
     return result;
   }
-  if (Array.isArray(base) && Array.isArray(override)) return mergeArrays(base, override);
+  if (Array.isArray(base) && Array.isArray(override)) return mergeArrays(base, override, opts);
   return override;
 }
 
@@ -455,16 +484,35 @@ async function resolveSkillSnapshot({ customizePath, customDir, resolvedDir, pro
   // 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).
+  // findUnknownKeys() returns structured { path, kind, detail? } entries:
+  // `kind` says "unknown key" vs "invalid value" directly, so this loop
+  // never has to sniff the rendered path text (a quoted TOML key can itself
+  // contain a space, which broke the old `includes(' ')` heuristic).
   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)`);
+    for (const { path: keyPath, kind, detail } of findUnknownKeys(layer)) {
+      warnings.push(
+        kind === 'invalid'
+          ? `${layerName} override: invalid ${keyPath}${detail ? ` (${detail})` : ''} — check customize.toml docs`
+          : `${layerName} override: unknown key "${keyPath}" (not a recognized workflow field — typo? check customize.toml docs)`,
+      );
     }
   }
 
-  const merged = deepMerge(deepMerge(defaults, team), user);
+  // Audit item 24 follow-up: a team/user override that REPLACES a base
+  // review layer (matched by id/code) but drops the base's `tiers`/
+  // `max_calls` silently loses that scaling — see
+  // warnOverrideDropsLayerScaling. Two separate deepMerge calls (rather
+  // than the previous deepMerge(deepMerge(defaults, team), user)) so each
+  // one can be labeled with the layer that is doing the overriding; a user
+  // override is checked against the team-adjusted result, which is the
+  // layer it actually replaces.
+  const overrideWarnings = [];
+  const afterTeam = deepMerge(defaults, team, { warnings: overrideWarnings, layerLabel: 'team' });
+  const merged = deepMerge(afterTeam, user, { warnings: overrideWarnings, layerLabel: 'user' });
+  warnings.push(...overrideWarnings);
   const body = `${JSON.stringify(merged, null, 2)}\n`;
   // Atomic write via fs-native (tmp + rename), consistent with every other
   // config file the installer writes.

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

@@ -3,7 +3,8 @@
  *
  * 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.
+ * merges — it takes ONE parsed layer and reports the keys/values no code
+ * consumes or that are structurally invalid.
  *
  * "additionalProperties: false" in spirit. The BASE layer (shipped,
  * code-reviewed) is exempt: it may legitimately carry LLM-only fields
@@ -14,6 +15,12 @@
  * is a warning (not an error: fail-open, the snapshot is still written).
  * `include` is the documented extension point and is validated by
  * `resolveIncludes`.
+ *
+ * Findings are structured `{ path, kind: 'unknown' | 'invalid', detail? }`
+ * entries — never plain strings. `kind` is how a caller tells "this key
+ * doesn't exist" from "this key exists but its value is wrong"; sniffing the
+ * rendered path text (e.g. for a space) breaks the moment a dotted path or a
+ * quoted TOML key legitimately contains one.
  */
 
 const { isPlainObject } = require('./resolved-includes');
@@ -72,31 +79,56 @@ const WORKFLOW_KEYS = new Set([
   // item keys are validated against REVIEW_LAYER_KEYS below.
   'review_layers',
   'oneshot_review_layers',
+  // review economy (review-economy.md): diff cleaning excludes/critical paths.
+  'review_exclude',
+  'review_critical_paths',
 ]);
 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']);
+// Exactly the keys the shipped `[[workflow.*review_layers]]` entries use
+// (src/bmm-skills/4-implementation/wizz-code-review + wizz-quick-dev), plus
+// `tiers`/`max_calls` for the review-economy tier scaling (review-economy.md).
+const REVIEW_LAYER_KEYS = new Set(['id', 'name', 'instruction', 'when', 'tiers', 'max_calls']);
+// The only valid values for a review_layers/oneshot_review_layers `tiers`
+// entry (review-economy.md tier scaling). A typo (`"crtical"`) used to load
+// silently and drop the layer on every tier — nothing ever matched it.
+const VALID_REVIEW_TIERS = new Set(['small', 'normal', 'critical']);
 // 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']);
 
+/** `value` is an array whose every element is a string. */
+function isArrayOfStrings(value) {
+  return Array.isArray(value) && value.every((item) => typeof item === 'string');
+}
+
 /**
- * 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
+ * Collect unknown/invalid entries under `[workflow]`: unknown fields by
+ * name, invalid values for the two review-economy string-array fields, and
+ * — for the arrays-of-tables we own (party members/groups, review layers) —
+ * the unknown keys and invalid values of each item.
+ *
+ * Every array-of-tables item is validated on its own, even when the array
+ * also holds non-object elements: a non-object item is flagged (invalid)
+ * instead of skipping validation for the whole array, which used to let a
+ * stray non-table entry hide typos in every OTHER entry.
+ * @returns {Array<{path: string, kind: 'unknown'|'invalid', detail?: string}>}
  */
 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);
+      unknown.push({ path: wfPath, kind: 'unknown' });
       continue;
     }
-    if (!Array.isArray(v2) || v2.length === 0 || !v2.every((it) => isPlainObject(it))) continue;
+    if (k2 === 'review_exclude' || k2 === 'review_critical_paths') {
+      if (!isArrayOfStrings(v2)) {
+        unknown.push({ path: wfPath, kind: 'invalid', detail: `expected an array of strings, got ${JSON.stringify(v2)}` });
+      }
+      continue;
+    }
+    if (!Array.isArray(v2) || v2.length === 0) continue;
     const allowed =
       k2 === 'party_members'
         ? PARTY_MEMBER_KEYS
@@ -106,30 +138,93 @@ function findUnknownWorkflowKeys(workflow) {
             ? REVIEW_LAYER_KEYS
             : null;
     if (!allowed) continue;
+    const isOneshot = k2 === 'oneshot_review_layers';
     for (const item of v2) {
+      if (!isPlainObject(item)) {
+        unknown.push({ path: `${wfPath}[]`, kind: 'invalid', detail: `expected a table, got ${JSON.stringify(item)}` });
+        continue;
+      }
       for (const k3 of Object.keys(item)) {
-        if (!allowed.has(k3)) unknown.push(`${wfPath}[].${k3}`);
+        if (!allowed.has(k3)) unknown.push({ path: `${wfPath}[].${k3}`, kind: 'unknown' });
       }
+      if (allowed === REVIEW_LAYER_KEYS) unknown.push(...findInvalidReviewLayerValues(item, wfPath, isOneshot));
     }
   }
   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.
+ * Validate the VALUES of a review_layers/oneshot_review_layers item (item
+ * keys themselves are already checked by the caller against
+ * REVIEW_LAYER_KEYS). A typo in `tiers` (`"crtical"`), an empty `tiers`
+ * array, a non-positive `max_calls`, or a `tiers` entry on an
+ * `oneshot_review_layers` item (that step ignores tiers — it always runs)
+ * all load silently today: deepMerge applies them, nothing catches the
+ * mistake, the layer misbehaves. Warnings, same shape as unknown keys —
+ * fail-open, the snapshot is still written.
+ * @param {object} item
+ * @param {string} wfPath
+ * @param {boolean} isOneshot - true for an `oneshot_review_layers` item
+ * @returns {Array<{path: string, kind: 'invalid', detail: string}>}
+ */
+function findInvalidReviewLayerValues(item, wfPath, isOneshot) {
+  const invalid = [];
+  if ('tiers' in item) {
+    if (isOneshot) {
+      invalid.push({
+        path: `${wfPath}[].tiers`,
+        kind: 'invalid',
+        detail: 'oneshot_review_layers always runs regardless of tier — tiers has no effect here',
+      });
+    } else if (!Array.isArray(item.tiers)) {
+      invalid.push({
+        path: `${wfPath}[].tiers`,
+        kind: 'invalid',
+        detail: `expected an array of "small"/"normal"/"critical", got ${JSON.stringify(item.tiers)}`,
+      });
+    } else if (item.tiers.length === 0) {
+      invalid.push({
+        path: `${wfPath}[].tiers`,
+        kind: 'invalid',
+        detail: 'empty — the layer would never run on any tier',
+      });
+    } else {
+      for (const tier of item.tiers) {
+        if (!VALID_REVIEW_TIERS.has(tier)) {
+          invalid.push({
+            path: `${wfPath}[].tiers[]`,
+            kind: 'invalid',
+            detail: `invalid tier "${tier}" — expected one of "small", "normal", "critical"`,
+          });
+        }
+      }
+    }
+  }
+  if ('max_calls' in item && !(Number.isInteger(item.max_calls) && item.max_calls > 0)) {
+    invalid.push({
+      path: `${wfPath}[].max_calls`,
+      kind: 'invalid',
+      detail: `expected a positive integer, got ${JSON.stringify(item.max_calls)}`,
+    });
+  }
+  return invalid;
+}
+
+/**
+ * Walk a loaded TOML layer and collect unknown/invalid entries: unknown
+ * TOP-level tables/scalars (anything outside `workflow`, `agent`, `include`)
+ * plus the `[workflow]` fields and array-of-table item keys/values.
+ * `[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)
+ * @returns {Array<{path: string, kind: 'unknown'|'invalid', detail?: string}>} 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);
+      unknown.push({ path: key, kind: 'unknown' });
       continue;
     }
     if (key === 'workflow' && isPlainObject(value)) unknown.push(...findUnknownWorkflowKeys(value));
@@ -140,9 +235,12 @@ function findUnknownKeys(data) {
 module.exports = {
   findUnknownKeys,
   findUnknownWorkflowKeys,
+  findInvalidReviewLayerValues,
+  isArrayOfStrings,
   WORKFLOW_KEYS,
   PARTY_MEMBER_KEYS,
   PARTY_GROUP_KEYS,
   REVIEW_LAYER_KEYS,
+  VALID_REVIEW_TIERS,
   TOP_LEVEL_KEYS,
 };