wizz-method 2.1.1 → 2.3.0

package/src/skills-lib/wizz-web-security/references/headers-rate-limit-cors.md

@@ -1,10 +1,10 @@
-# Headers de Segurança, Rate Limiting, CORS, e Vazamento de Dados
+# Security Headers, Rate Limiting, CORS, and Data Leakage
 
-Carregue este arquivo ao implementar/revisar headers de segurança, rate limiting, CORS, ou o formato de resposta de uma API (over-fetch/PII).
+Load this file when implementing/reviewing security headers, rate limiting, CORS, or an API's response shape (over-fetch/PII).
 
-## Headers de segurança obrigatórios
+## Mandatory security headers
 
-`X-Frame-Options: DENY` + `frame-ancestors 'none'` no CSP mata **clickjacking** (o site não pode ser embutido em `<iframe>` de outro domínio). Fix de 1 minuto, sempre presente.
+`X-Frame-Options: DENY` + `frame-ancestors 'none'` in the CSP kills **clickjacking** (the site can't be embedded in an `<iframe>` from another domain). A 1-minute fix, always present.
 
 ```
 Content-Security-Policy: default-src 'self'; frame-ancestors 'none'
@@ -15,7 +15,7 @@ Referrer-Policy: strict-origin-when-cross-origin
 Permissions-Policy: camera=(), microphone=(), geolocation=()
 ```
 
-Como adicionar em Next.js (`next.config.ts`):
+How to add it in Next.js (`next.config.ts`):
 ```ts
 async headers() {
   return [
@@ -44,46 +44,46 @@ async headers() {
 },
 ```
 
-> **Cuidado:** CSP errada quebra o app. Teste sempre em dev antes de subir. Ajuste os domínios (`script-src`, `connect-src`) conforme os serviços reais do projeto.
+> **Careful:** a wrong CSP breaks the app. Always test in dev before deploying. Adjust the domains (`script-src`, `connect-src`) to the project's real services.
 
 ## Rate Limiting
-- Login: limite por IP **e** por conta (só por IP não segura brute force distribuído; só por conta não segura scan de vários e-mails)
-- APIs públicas: limite por IP e por token
-- Endpoints de reset de senha: especialmente restritivos
-- Endpoints de cobrança (checkout, portal): sempre com rate limit
-- Next.js: `@upstash/ratelimit` no route handler, ou WAF da Vercel para regras por rota
-- Fail closed: se o backend do rate limit cair (ex: Redis fora), rotas de escrita devem negar a request, não deixar passar
-- Comparações de token/secret: `crypto.timingSafeEqual`, nunca `!==` (detalhe em wizz-auth-and-secrets)
-- Sem rate limit = brute force de graça. Somar lockout/CAPTCHA após N falhas no login
+- Login: limit per IP **and** per account (IP-only doesn't protect against distributed brute force; account-only doesn't protect against scanning many emails)
+- Public APIs: limit per IP and per token
+- Password reset endpoints: especially restrictive
+- Billing endpoints (checkout, portal): always with rate limiting
+- Next.js: `@upstash/ratelimit` in the route handler, or Vercel's WAF for per-route rules
+- Fail closed: if the rate-limit backend goes down (e.g. Redis is out), write routes should deny the request, not let it through
+- Token/secret comparisons: `crypto.timingSafeEqual`, never `!==` (details in wizz-auth-and-secrets)
+- No rate limit = free brute force. Add lockout/CAPTCHA after N failed login attempts
 
-### Origem do IP atrás de proxy/CDN
-Se o app roda atrás de Vercel/Cloudflare/qualquer proxy, o IP do socket é o do proxy, não o do cliente. Ler o socket direto faz **o mundo inteiro contar como um IP só** e o rate limit deixa de existir na prática.
-- Vercel: use `x-forwarded-for` (ou `req.ip` no runtime que já resolve). Pegue o **primeiro** IP da lista, mas só confie na cadeia que vem do seu proxy.
-- Nunca confie em `x-forwarded-for` cru vindo de origem não-proxy (o cliente falsifica o header). Configure a lib de rate limit para o número certo de proxies à frente.
+### IP origin behind a proxy/CDN
+If the app runs behind Vercel/Cloudflare/any proxy, the socket's IP is the proxy's, not the client's. Reading the raw socket makes **the entire world count as a single IP** and the rate limit effectively stops existing.
+- Vercel: use `x-forwarded-for` (or `req.ip` in the runtime that already resolves it). Take the **first** IP in the list, but only trust the chain that comes from your own proxy.
+- Never trust a raw `x-forwarded-for` coming from a non-proxy origin (the client can spoof the header). Configure the rate-limit library for the correct number of proxies in front.
 
-### Custo por chamada (rota que gasta dinheiro real)
-Toda rota que chama modelo de linguagem, dispara SMS, envia e-mail, processa arquivo ou bate em API paga de terceiro precisa de rate limit **e** quota por conta. Rota de agente de IA exposta sem limitador é crítica mesmo sem vazar dado nenhum: 10.000 chamadas em loop viram conta de centenas a milhares de reais/dólares. Estime o custo unitário e multiplique por 10k ao avaliar a rota.
+### Per-call cost (a route that spends real money)
+Every route that calls a language model, sends an SMS, sends an email, processes a file, or hits a paid third-party API needs rate limiting **and** a per-account quota. An AI agent route exposed without a limiter is critical even without leaking any data at all: 10,000 calls in a loop turn into a bill of hundreds to thousands of dollars. Estimate the unit cost and multiply by 10k when assessing the route.
 
-### Extração por paginação
-Rota que devolve um registro por vez e, chamada em sequência, entrega a base inteira. Barre com: filtro por dono na query (o mesmo do IDOR), limite máximo de página, e detecção de varredura (muitos ids sequenciais do mesmo cliente).
+### Extraction via pagination
+A route that returns one record at a time and, called in sequence, hands over the entire database. Block it with: an owner filter in the query (the same as for IDOR), a maximum page size, and scan detection (many sequential IDs from the same client).
 
 ## CORS
-- **Nunca reflita o header `Origin` recebido** de volta em `Access-Control-Allow-Origin` (isso libera qualquer site a chamar sua API com credenciais)
-- Use uma **allowlist explícita** de origens: compare o `Origin` recebido contra a lista e só então ecoe o valor exato daquela origem
-- `Access-Control-Allow-Credentials: true` NUNCA junto de `Access-Control-Allow-Origin: *`
-- Padrão = negar: origem desconhecida → sem headers CORS (o browser bloqueia sozinho)
+- **Never reflect the received `Origin` header** back in `Access-Control-Allow-Origin` (this lets any site call your API with credentials)
+- Use an explicit **allowlist** of origins: compare the received `Origin` against the list and only then echo back that exact origin's value
+- `Access-Control-Allow-Credentials: true` NEVER together with `Access-Control-Allow-Origin: *`
+- Default = deny: unknown origin → no CORS headers (the browser blocks it on its own)
 ```ts
 const ALLOWED = new Set(["https://app.exemplo.com", "https://exemplo.com"])
 const origin = req.headers.get("origin")
 if (origin && ALLOWED.has(origin)) {
-  res.headers.set("Access-Control-Allow-Origin", origin) // valor exato, nunca "*" com credentials
+  res.headers.set("Access-Control-Allow-Origin", origin) // exact value, never "*" with credentials
   res.headers.set("Vary", "Origin")
 }
 ```
 
-## Vazamento de dados na resposta (over-fetch / PII)
-- Retorne **só os campos que a tela precisa**: monte um DTO/allowlist de saída, nunca devolva a row inteira do banco
-- NUNCA inclua `password`, `password_hash`, tokens, secrets ou colunas internas na resposta de API (é a falha mais grave da lista de PII)
-- Supabase: `.select('id, name, email')` explícito, nunca `.select('*')` em endpoint que responde ao cliente
-- Objeto do usuário logado: serialize por um mapper que só expõe campos públicos
-- Erros: não vaze stack trace, SQL nem nome de tabela pro cliente. Mensagem genérica no response, detalhe só no log do servidor
+## Data leakage in the response (over-fetch / PII)
+- Return **only the fields the screen needs**: build an output DTO/allowlist, never return the whole database row
+- NEVER include `password`, `password_hash`, tokens, secrets, or internal columns in an API response (this is the most serious failure on the PII list)
+- Supabase: explicit `.select('id, name, email')`, never `.select('*')` on an endpoint that responds to the client
+- Logged-in user object: serialize it through a mapper that only exposes public fields
+- Errors: don't leak stack traces, SQL, or table names to the client. Generic message in the response, detail only in the server log

package/src/skills-lib/wizz-web-security/references/owasp-top5-detalhado.md

@@ -1,14 +1,14 @@
-# OWASP — Detalhe das 5 categorias mais comuns
+# OWASP — Detail of the 5 most common categories
 
-Carregue este arquivo ao aprofundar numa das falhas do triage rápido (seções 1-5 referenciadas na tabela do SKILL.md).
+Load this file when digging deeper into one of the failures from the quick triage (sections 1-5 referenced in the SKILL.md table).
 
 ## 1. Broken Access Control
-- Verifique permissões no servidor, nunca apenas no frontend
-- IDOR (Insecure Direct Object Reference): valide se o usuário tem acesso ao recurso pelo ID
-- Princípio do menor privilégio em todas as rotas
-- Next.js: middleware não é a única barreira. Re-verifique auth dentro do route handler, Server Action ou página (bypass de middleware já teve CVE)
+- Check permissions on the server, never only on the frontend
+- IDOR (Insecure Direct Object Reference): validate that the user has access to the resource by ID
+- Principle of least privilege on every route
+- Next.js: middleware isn't the only barrier. Re-check auth inside the route handler, Server Action, or page (a middleware bypass has already had a CVE)
 
-Exemplo anti-IDOR (Next.js + Clerk + Supabase):
+Anti-IDOR example (Next.js + Clerk + Supabase):
 ```ts
 // app/api/projects/[id]/route.ts
 import { auth } from "@clerk/nextjs/server"
@@ -21,63 +21,63 @@ export async function GET(req: Request, { params }: { params: Promise<{ id: stri
     .from("projects")
     .select("id, name")
     .eq("id", id)
-    .eq("user_id", userId) // posse verificada na query, além do RLS
+    .eq("user_id", userId) // ownership verified in the query, in addition to RLS
     .single()
-  if (!data) return new Response("Not found", { status: 404 }) // 404, não 403 (não confirma que o recurso existe)
+  if (!data) return new Response("Not found", { status: 404 }) // 404, not 403 (doesn't confirm the resource exists)
   return Response.json(data)
 }
 ```
 
-### RLS: policy permissiva é pior que policy nenhuma
-Ler os arquivos de migration/policy versionados e checar:
-- Toda tabela de domínio tem `ENABLE ROW LEVEL SECURITY`?
-- Nenhuma policy é permissiva: `USING (true)` ou `WITH CHECK (true)` libera geral, mas o painel do Supabase mostra a trava como "ativa". Amarre sempre ao dono: `USING (auth.uid() = user_id)`.
-- Tabela criada em migration recente **sem** policy correspondente = exposta.
+### RLS: a permissive policy is worse than no policy
+Read the versioned migration/policy files and check:
+- Does every domain table have `ENABLE ROW LEVEL SECURITY`?
+- Is no policy permissive: `USING (true)` or `WITH CHECK (true)` opens it to everyone, but the Supabase dashboard shows the lock as "active." Always tie it to the owner: `USING (auth.uid() = user_id)`.
+- A table created in a recent migration **without** a corresponding policy = exposed.
 
 ```sql
--- ERRADO: mostra RLS ativo no painel, mas libera qualquer um
+-- WRONG: shows RLS active in the dashboard, but opens it to anyone
 create policy "read" on projects for select using (true);
 
--- CERTO: amarra o dono
+-- RIGHT: ties it to the owner
 alter table projects enable row level security;
 create policy "own rows" on projects
   for select using (auth.uid() = user_id);
 ```
 
-> RLS de verdade é estado do banco, não arquivo. O que está no repo é ponto de partida: confirme o estado real no dashboard/`\d+` do Postgres.
+> Real RLS is database state, not a file. What's in the repo is a starting point: confirm the real state in the dashboard/`\d+` of Postgres.
 
-## 6. Mass Assignment (atribuição em massa)
-O corpo da requisição inteiro repassado para o banco (`spread` do objeto, `update`/`create` com o payload completo) deixa o atacante setar qualquer coluna, mesmo as que não estão no formulário. Alvos clássicos: `role`, `is_admin`, `plan`, `balance`, `payment_status`, `user_id`/`owner_id`.
+## 6. Mass Assignment
+Passing the entire request body through to the database (`spread` of the object, `update`/`create` with the full payload) lets an attacker set any column, even ones not in the form. Classic targets: `role`, `is_admin`, `plan`, `balance`, `payment_status`, `user_id`/`owner_id`.
 
 ```ts
-// ERRADO: o cliente manda { name: "x", role: "admin" } e vira admin
+// WRONG: the client sends { name: "x", role: "admin" } and becomes admin
 await supabase.from("users").update({ ...body }).eq("id", userId)
 
-// CERTO: allowlist explícita, só os campos do formulário
-const { name, bio } = updateSchema.parse(body) // Zod com só os campos permitidos
+// RIGHT: explicit allowlist, only the form's fields
+const { name, bio } = updateSchema.parse(body) // Zod with only the allowed fields
 await supabase.from("users").update({ name, bio }).eq("id", userId)
 ```
 
-Regra: **nunca** `...body` / `...req.body` num write. Sempre desestruture (ou valide com um schema que só contém os campos editáveis). Campos de papel, permissão, plano, saldo, status de pagamento e id de dono nunca vêm do cliente.
+Rule: **never** `...body` / `...req.body` in a write. Always destructure (or validate with a schema that only contains the editable fields). Role, permission, plan, balance, payment status, and owner id fields never come from the client.
 
 ## 2. Cryptographic Failures
-- HTTPS em tudo, sem exceção
-- HSTS header com includeSubDomains
-- Não exponha dados sensíveis em URLs (query strings ficam em logs)
+- HTTPS everywhere, no exceptions
+- HSTS header with includeSubDomains
+- Don't expose sensitive data in URLs (query strings end up in logs)
 
 ## 3. Injection
-- SQL: queries parametrizadas sempre
+- SQL: always parameterized queries
 - XSS: sanitize outputs, use Content-Security-Policy
-- Command injection: nunca execute input do usuário como comando shell
+- Command injection: never execute user input as a shell command
 
 ## 4. Cross-Site Scripting (XSS)
-- Escape HTML em todo output de dado do usuário
-- React/Next.js escapa JSX por padrão. O risco real está em `dangerouslySetInnerHTML`: sanitize antes com DOMPurify (ou não use)
-- URLs vindas do usuário em `href`/`src`: bloqueie esquemas `javascript:` e `data:` (valide que começa com `https://` ou caminho relativo)
-- Content-Security-Policy: bloqueie inline scripts
-- HttpOnly e Secure flags nos cookies de sessão
+- Escape HTML on every piece of user-generated output
+- React/Next.js escapes JSX by default. The real risk is in `dangerouslySetInnerHTML`: sanitize with DOMPurify first (or don't use it)
+- User-supplied URLs in `href`/`src`: block `javascript:` and `data:` schemes (validate that it starts with `https://` or a relative path)
+- Content-Security-Policy: block inline scripts
+- HttpOnly and Secure flags on session cookies
 
 ## 5. CSRF
-- SameSite=Strict ou Lax nos cookies de sessão
-- CSRF token em formulários state-changing
-- Verifique Origin/Referer em requests sensíveis
+- SameSite=Strict or Lax on session cookies
+- CSRF token on state-changing forms
+- Check Origin/Referer on sensitive requests

package/tools/hooks/session-rules.js

@@ -4,9 +4,9 @@
 //
 // Três responsabilidades, um processo só (SessionStart roda 1x por sessão):
 //
-//   1. Regras de comunicação, injetadas UMA vez por sessão (antes:
-//      no-narration-enforce repetia ~80 tokens em TODO prompt via
-//      UserPromptSubmit). Mesmo conteúdo, custo fixo por sessão.
+//   1. Communication rules, injected ONCE per session (before: no-narration-enforce
+//      repeated ~80 tokens on EVERY prompt via UserPromptSubmit). Same content,
+//      fixed cost per session.
 //
 //   2. Feature ativa: resolve o `active_feature` SOZINHO, sem o usuário
 //      precisar invocar `wizz-set-feature` e responder duas perguntas. Ordem:
@@ -26,15 +26,18 @@ const fs = require('node:fs');
 const os = require('node:os');
 const path = require('node:path');
 
-// Cópia comprimida e INTENCIONAL da regra de comunicação. A fonte é
-// src/modules/wizz/_shared/communication-rules.md; este hook precisa ser
-// autocontido porque roda de ~/.claude/hooks, longe do repo. Editou lá,
-// edite aqui: test/test-feature-context.js falha se as duas divergirem.
+// Compressed and INTENTIONAL copy of the communication rule. The source is
+// src/modules/wizz/_shared/communication-rules.md; this hook needs to be
+// self-contained because it runs from ~/.claude/hooks, far from the repo. Edit
+// it there, edit it here too: test/test-feature-context.js fails if the two diverge.
 const RULES =
-  'REGRA DE COMUNICAÇÃO (permanente, não-negociável): não narrar o passo a passo ' +
-  'enquanto trabalha; pausar e perguntar SÓ em decisão do usuário ou risco ' +
-  'irreversível; fechar SEMPRE com resumo curto em tópicos, linguagem simples, ' +
-  'sem jargão; sem em-dashes; comunicação enxuta por default, expandir só sob demanda.';
+  'COMMUNICATION RULE (permanent, non-negotiable): do not narrate the step-by-step ' +
+  'while working; pause and ask ONLY for a user decision or irreversible risk; ' +
+  'always close with a short summary in bullet points, plain language, no jargon; ' +
+  'no em-dashes only in text a third party reads (public page, copy, UI), ' +
+  'code comments, commits, and internal notes are exempt from this check; ' +
+  'concise communication by default, expand only on request; ' +
+  'reply to the user in Brazilian Portuguese.';
 
 // Branches que NUNCA viram feature: são linha principal, não trabalho nomeado.
 const TRUNK = new Set(['main', 'master', 'develop', 'dev', 'staging', 'stage', 'prod', 'production', 'trunk', 'default', 'release']);

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,
 };