@jaimevalasek/aioson 1.30.2 → 1.36.0

package/src/commands/audit-code.js

@@ -0,0 +1,344 @@
+'use strict';
+
+/**
+ * aioson audit:code [path] [--changed] [--category=TODO,ANTI_PATTERN,DUPLICATION,DEAD_CODE]
+ *   [--json] [--strict] — deterministic, build-free code-quality scan.
+ *
+ * The non-security half of a categorized code-quality audit, written in pure
+ * Node so it runs cross-platform with no python/grep/tsc dependency. SECURITY is
+ * NOT re-implemented here — `aioson security:audit` owns secrets/logs/controls.
+ *
+ * Categories (each a separate concern @qa can consume one at a time, one
+ * category cleared per pass):
+ *
+ *   TODO          residual TODO/FIXME/XXX/placeholder/not-implemented        MED
+ *   ANTI_PATTERN  eval / new Function / innerHTML / `: any` / coerce.boolean HIGH·MED
+ *   DEAD_CODE     unused named imports (build-free TS6133 heuristic)         MED
+ *   DUPLICATION   a string literal repeated 3+ times across 2+ files         LOW
+ *
+ * Exit code: a HIGH finding sets exit 1 (blocking); MED/LOW
+ * are advisory and never fail the exit. Pass `suppressExitCode` for programmatic
+ * callers (the workflow gate / @qa dispatch), matching security:audit.
+ */
+
+const path = require('node:path');
+const fs = require('node:fs');
+
+const { gitChangedFiles } = require('../harness/detect-runtime-feature');
+
+const VERSION = '1.0.0';
+const GENERATOR = `aioson audit:code@${VERSION}`;
+
+const ALL_CATEGORIES = Object.freeze(['TODO', 'ANTI_PATTERN', 'DEAD_CODE', 'DUPLICATION']);
+
+const IGNORE_DIRS = new Set([
+  'node_modules', '.git', 'dist', 'build', 'out', 'coverage',
+  '.next', '.nuxt', '.svelte-kit', 'vendor', '.aioson', '.venv', '__pycache__'
+]);
+
+const CODE_EXTS = new Set([
+  '.js', '.jsx', '.mjs', '.cjs', '.ts', '.tsx',
+  '.py', '.rb', '.go', '.java', '.php', '.vue', '.svelte', '.css', '.scss', '.html'
+]);
+const JS_TS_EXTS = new Set(['.js', '.jsx', '.mjs', '.cjs', '.ts', '.tsx']);
+const TS_EXTS = new Set(['.ts', '.tsx']);
+
+const MAX_FILE_BYTES = 512 * 1024;
+
+// ─── TODO / placeholder ───────────────────────────────────────────────────────
+
+const TODO_PATTERNS = [
+  /\bTODO\b/,
+  /\bFIXME\b/,
+  /\bXXX\b/,
+  /\bHACK\b/,
+  /\bplaceholder\b/i,
+  /not\s+implemented/i,
+  /throw\s+new\s+Error\s*\(\s*['"`]not\s+impl/i
+];
+
+// ─── Anti-patterns (JS/TS unless noted) ───────────────────────────────────────
+
+const ANTI_PATTERNS = [
+  { re: /\beval\s*\(/,                 sev: 'HIGH', msg: 'eval() in code', ext: JS_TS_EXTS },
+  { re: /\bnew\s+Function\s*\(/,       sev: 'HIGH', msg: 'new Function() (dynamic code)', ext: JS_TS_EXTS },
+  { re: /\.innerHTML\s*=/,             sev: 'HIGH', msg: 'innerHTML assignment (use textContent / safe DOM API)', ext: JS_TS_EXTS },
+  { re: /dangerouslySetInnerHTML/,     sev: 'HIGH', msg: 'dangerouslySetInnerHTML', ext: JS_TS_EXTS },
+  { re: /z\.coerce\.boolean\s*\(/,     sev: 'HIGH', msg: 'z.coerce.boolean() ("false" coerces to true — use z.enum)', ext: JS_TS_EXTS },
+  { re: /:\s*any\b/,                   sev: 'MED',  msg: '`: any` type (use unknown or an explicit type; // any-ok to allow)', ext: TS_EXTS, skip: (line) => line.includes('any-ok') },
+  { re: /\bconsole\.(log|debug|trace)\s*\(/, sev: 'MED', msg: 'console.log/debug/trace left in code', ext: JS_TS_EXTS, prodOnly: true }
+];
+
+// ─── helpers ──────────────────────────────────────────────────────────────────
+
+const SEVERITY_RANK = Object.freeze({ HIGH: 3, MED: 2, LOW: 1 });
+
+function isProdFile(rel) {
+  const lower = rel.toLowerCase();
+  return !(
+    /(^|[\\/])(test|tests|__tests__|spec|scripts|examples?|fixtures?|mocks?)([\\/]|$)/.test(lower) ||
+    /\.(test|spec)\.[a-z]+$/.test(lower) ||
+    /\.config\.[a-z]+$/.test(lower)
+  );
+}
+
+function listSourceFiles(root) {
+  const out = [];
+  const stack = [root];
+  while (stack.length) {
+    const dir = stack.pop();
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (!IGNORE_DIRS.has(entry.name)) stack.push(full);
+      } else if (entry.isFile() && CODE_EXTS.has(path.extname(entry.name).toLowerCase())) {
+        out.push(full);
+      }
+    }
+  }
+  return out;
+}
+
+function readText(abs) {
+  try {
+    const stat = fs.statSync(abs);
+    if (stat.size > MAX_FILE_BYTES) return null;
+    return fs.readFileSync(abs, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+function isCommentLine(stripped) {
+  return stripped.startsWith('//') || stripped.startsWith('*') || stripped.startsWith('#') || stripped.startsWith('/*');
+}
+
+// ─── category scanners ─────────────────────────────────────────────────────────
+
+function scanTodo(rel, ext, lines, push) {
+  lines.forEach((line, i) => {
+    for (const re of TODO_PATTERNS) {
+      if (re.test(line)) {
+        push({ category: 'TODO', severity: 'MED', message: 'TODO/FIXME/placeholder/not-implemented residual', file: rel, line: i + 1, snippet: line.trim().slice(0, 120) });
+        break;
+      }
+    }
+  });
+}
+
+function scanAntiPatterns(rel, ext, lines, push) {
+  const prod = isProdFile(rel);
+  lines.forEach((line, i) => {
+    const stripped = line.trim();
+    if (isCommentLine(stripped)) return;
+    for (const ap of ANTI_PATTERNS) {
+      if (ap.ext && !ap.ext.has(ext)) continue;
+      if (ap.prodOnly && !prod) continue;
+      if (ap.skip && ap.skip(line)) continue;
+      if (ap.re.test(line)) {
+        push({ category: 'ANTI_PATTERN', severity: ap.sev, message: ap.msg, file: rel, line: i + 1, snippet: stripped.slice(0, 120) });
+      }
+    }
+  });
+}
+
+/**
+ * DEAD_CODE — unused named imports, build-free. For each named import / require
+ * destructure, the local name must appear more than once in the file (the import
+ * itself is occurrence #1). A barrel re-export (`export { X } from`) suppresses
+ * the flag. This is the static analogue of tsc TS6133 without needing a build.
+ */
+function scanDeadCode(rel, ext, content, lines, push) {
+  if (!JS_TS_EXTS.has(ext) || rel.endsWith('.d.ts')) return;
+  const specs = [];
+  const importRe = /import\s+(?:type\s+)?(?:[A-Za-z0-9_$]+\s*,\s*)?\{([^}]*)\}\s*from\s*['"][^'"]+['"]/gs;
+  const requireRe = /(?:const|let|var)\s*\{([^}]*)\}\s*=\s*require\(/gs;
+  for (const re of [importRe, requireRe]) {
+    let m;
+    while ((m = re.exec(content)) !== null) {
+      for (const raw of m[1].split(',')) {
+        const part = raw.trim().replace(/^type\s+/, '');
+        if (!part) continue;
+        const local = (part.includes(' as ') ? part.split(/\s+as\s+/)[1] : part).trim();
+        if (/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(local)) specs.push(local);
+      }
+    }
+  }
+  if (!specs.length) return;
+  for (const name of [...new Set(specs)]) {
+    // Re-exported names are "used" (barrel files).
+    if (new RegExp(`export\\s*\\{[^}]*\\b${name}\\b`).test(content)) continue;
+    const occurrences = (content.match(new RegExp(`\\b${name}\\b`, 'g')) || []).length;
+    if (occurrences <= 1) {
+      const idx = lines.findIndex((l) => new RegExp(`\\b${name}\\b`).test(l));
+      push({ category: 'DEAD_CODE', severity: 'MED', message: `unused import "${name}" (declared, never used)`, file: rel, line: idx >= 0 ? idx + 1 : 1, snippet: idx >= 0 ? lines[idx].trim().slice(0, 120) : '' });
+    }
+  }
+}
+
+/**
+ * DUPLICATION — a string literal (12..80 chars) that appears 3+ times across 2+
+ * files is a constant waiting to drift. Pure text; comments and URLs ignored.
+ */
+function scanDuplication(files, push) {
+  const literalRe = /["'`]([^"'`\n]{12,80})["'`]/g;
+  const ignore = new Set(['use strict', 'application/json', 'text/plain', 'Content-Type', 'utf-8', 'utf8']);
+  const occ = new Map(); // literal -> [{file,line}]
+  for (const { rel, lines } of files) {
+    lines.forEach((line, i) => {
+      const stripped = line.trim();
+      if (isCommentLine(stripped)) return;
+      let m;
+      literalRe.lastIndex = 0;
+      while ((m = literalRe.exec(line)) !== null) {
+        const lit = m[1];
+        if (ignore.has(lit) || lit.startsWith('http://') || lit.startsWith('https://') || /^[\s./\\-]+$/.test(lit)) continue;
+        if (!occ.has(lit)) occ.set(lit, []);
+        occ.get(lit).push({ file: rel, line: i + 1 });
+      }
+    });
+  }
+  for (const [lit, places] of occ) {
+    const files2 = new Set(places.map((p) => p.file));
+    if (places.length >= 3 && files2.size >= 2) {
+      push({
+        category: 'DUPLICATION', severity: 'LOW',
+        message: `literal "${lit.slice(0, 50)}" repeated ${places.length}x across ${files2.size} files (extract a constant)`,
+        file: places[0].file, line: places[0].line,
+        snippet: places.slice(0, 4).map((p) => `${p.file}:${p.line}`).join(', ')
+      });
+    }
+  }
+}
+
+// ─── core scan ──────────────────────────────────────────────────────────────────
+
+/**
+ * @param {object} params
+ * @param {string} params.targetDir
+ * @param {string[]} [params.fileList] — absolute paths to scan; default = full walk
+ * @param {Set<string>} params.categories
+ * @returns {{ findings: Array, scanned: number }}
+ */
+function scanCodeQuality({ targetDir, fileList, categories }) {
+  const abs = Array.isArray(fileList) && fileList.length
+    ? fileList.filter((f) => CODE_EXTS.has(path.extname(f).toLowerCase()))
+    : listSourceFiles(targetDir);
+
+  const findings = [];
+  const push = (f) => findings.push(f);
+  const loaded = []; // { rel, ext, content, lines } for duplication pass
+
+  for (const file of abs) {
+    const content = readText(file);
+    if (content === null) continue;
+    const rel = path.relative(targetDir, file).split(path.sep).join('/');
+    const ext = path.extname(file).toLowerCase();
+    const lines = content.split('\n');
+    loaded.push({ rel, ext, content, lines });
+
+    if (categories.has('TODO')) scanTodo(rel, ext, lines, push);
+    if (categories.has('ANTI_PATTERN')) scanAntiPatterns(rel, ext, lines, push);
+    if (categories.has('DEAD_CODE')) scanDeadCode(rel, ext, content, lines, push);
+  }
+  if (categories.has('DUPLICATION')) scanDuplication(loaded, push);
+
+  findings.sort((a, b) =>
+    (SEVERITY_RANK[b.severity] - SEVERITY_RANK[a.severity]) ||
+    a.category.localeCompare(b.category) ||
+    a.file.localeCompare(b.file) ||
+    (a.line - b.line)
+  );
+  return { findings, scanned: loaded.length };
+}
+
+function parseCategories(option) {
+  if (!option) return new Set(ALL_CATEGORIES);
+  const wanted = String(option).split(',').map((s) => s.trim().toUpperCase()).filter(Boolean);
+  const valid = wanted.filter((c) => ALL_CATEGORIES.includes(c));
+  return new Set(valid.length ? valid : ALL_CATEGORIES);
+}
+
+async function runAuditCode({ args, options = {}, logger }) {
+  const targetDir = path.resolve(process.cwd(), args?.[0] || '.');
+  const suppressExitCode = Boolean(options.suppressExitCode);
+  const setExitCode = (code) => { if (!suppressExitCode) process.exitCode = code; };
+  const categories = parseCategories(options.category);
+
+  let fileList = null;
+  if (options.changed) {
+    fileList = gitChangedFiles(targetDir).map((rel) => path.resolve(targetDir, rel));
+  }
+
+  const { findings, scanned } = scanCodeQuality({ targetDir, fileList, categories });
+
+  const bySeverity = { HIGH: 0, MED: 0, LOW: 0 };
+  const byCategory = {};
+  for (const f of findings) {
+    bySeverity[f.severity] = (bySeverity[f.severity] || 0) + 1;
+    byCategory[f.category] = (byCategory[f.category] || 0) + 1;
+  }
+
+  const strict = Boolean(options.strict);
+  const blocking = bySeverity.HIGH > 0 || (strict && bySeverity.MED > 0);
+
+  const report = {
+    generator: GENERATOR,
+    root: targetDir,
+    scanned_files: scanned,
+    categories: [...categories],
+    scope: options.changed ? 'changed' : 'full',
+    total: findings.length,
+    by_severity: bySeverity,
+    by_category: byCategory,
+    ok: !blocking,
+    findings
+  };
+
+  // Persist for @qa to consume by category across invocations.
+  try {
+    const ctxDir = path.join(targetDir, '.aioson', 'context');
+    fs.mkdirSync(ctxDir, { recursive: true });
+    fs.writeFileSync(path.join(ctxDir, 'audit-code.json'), JSON.stringify(report, null, 2), 'utf8');
+  } catch {
+    // best-effort persistence — never fail the scan
+  }
+
+  if (options.json) {
+    logger.log(JSON.stringify(report, null, 2));
+    setExitCode(blocking ? 1 : 0);
+    return report;
+  }
+
+  logger.log(`Code audit — ${scanned} file(s) scanned (${report.scope}) — ${findings.length} finding(s)`);
+  if (bySeverity.HIGH || bySeverity.MED || bySeverity.LOW) {
+    logger.log(`  HIGH: ${bySeverity.HIGH}  MED: ${bySeverity.MED}  LOW: ${bySeverity.LOW}`);
+  }
+  for (const cat of ALL_CATEGORIES) {
+    if (byCategory[cat]) logger.log(`  ${cat}: ${byCategory[cat]}`);
+  }
+  for (const f of findings.slice(0, 50)) {
+    logger.log(`  [${f.severity}] ${f.category} ${f.file}:${f.line} — ${f.message}`);
+  }
+  if (findings.length > 50) logger.log(`  … and ${findings.length - 50} more (see .aioson/context/audit-code.json)`);
+  logger.log(blocking ? '  AUDIT=FAIL (HIGH findings present)' : '  AUDIT=OK (no blocking findings)');
+
+  setExitCode(blocking ? 1 : 0);
+  return report;
+}
+
+module.exports = {
+  runAuditCode,
+  scanCodeQuality,
+  parseCategories,
+  ALL_CATEGORIES,
+  // exported for tests
+  scanDeadCode,
+  scanDuplication
+};

package/src/commands/classify.js

@@ -116,44 +116,80 @@ const COMPLEXITY_SOME_PATTERNS = [
   /\b(notification|trigger|event)\b/gi
 ];
 
+// Fold diacritics so the surface detectors match a localized PRD the same way in
+// any supported language: "cartões"->"cartoes", "gestão"->"gestao",
+// "autenticação"->"autenticacao". Patterns below stay ASCII and run against the
+// folded text, so EN and pt-BR phrasings of the same surface are detected
+// identically. The detector recognizes the surface from the words present in the
+// text — it does NOT depend on the configured interaction_language.
+function foldDiacritics(content) {
+  return String(content || '').normalize('NFD').replace(/\p{Diacritic}/gu, '');
+}
+
 // Sensitive-surface floor (Gap 3B): a feature touching any of these surfaces is
 // never MICRO. Mirrors the secure-tdd sensitive list in @dev. The floor can only
 // RAISE the tier (MICRO -> SMALL); it never lowers it. Keep patterns tight — a
-// false positive needlessly costs the SMALL chain. Tune as the project learns.
+// false positive needlessly costs the SMALL chain. Patterns are bilingual
+// (EN + pt-BR) and matched against diacritic-folded text. Tune as the project learns.
 const SENSITIVE_SURFACE_PATTERNS = [
-  { surface: 'money', re: /\b(money|stripe|paypal|braintree|square|payments?|payouts?|refunds?|subscriptions?|billing|invoices?|credit card)\b/i },
-  { surface: 'auth', re: /\b(oauth|jwt|saml|sso|auth0|firebase auth|log[- ]?in|sign[- ]?in|sign[- ]?up|passwords?|authenticat\w*|2fa|mfa)\b/i },
-  { surface: 'authz', re: /\b(authoriz\w*|access control|role[- ]based|rbac|ownership|owner[- ]only|only the owner)\b/i },
-  { surface: 'uploads', re: /\b(file uploads?|uploads?|attachments?)\b/i },
-  { surface: 'external_url', re: /\b(webhooks?|callback urls?|ssrf|user[- ]?supplied urls?)\b/i },
-  { surface: 'secrets', re: /\b(secrets?|api keys?|credentials?|private key|access tokens?)\b/i },
-  { surface: 'sensitive_storage', re: /\b(pii|personal data|ssn|sensitive (data|storage|information))\b/i }
+  { surface: 'money', re: /\b(money|stripe|paypal|braintree|square|payments?|payouts?|refunds?|subscriptions?|billing|invoices?|credit card|pagamentos?|pagar|cobran[cç]as?|faturas?|assinaturas?|reembolsos?|cartao de credito|boleto|pix)\b/i },
+  { surface: 'auth', re: /\b(oauth|jwt|saml|sso|auth0|firebase auth|log[- ]?in|sign[- ]?in|sign[- ]?up|passwords?|authenticat\w*|2fa|mfa|autentica\w*|senhas?|cadastr(o|os|ar))\b/i },
+  { surface: 'authz', re: /\b(authoriz\w*|access control|role[- ]based|rbac|ownership|owner[- ]only|only the owner|autoriza(cao|r)|controle de acesso|apenas o dono|somente o dono)\b/i },
+  { surface: 'uploads', re: /\b(file uploads?|uploads?|attachments?|anexos?|envio de arquivos?|upload de arquivos?)\b/i },
+  { surface: 'external_url', re: /\b(webhooks?|callback urls?|ssrf|user[- ]?supplied urls?|url de retorno|urls? fornecidas?)\b/i },
+  { surface: 'secrets', re: /\b(secrets?|api keys?|credentials?|private key|access tokens?|segredos?|chaves? de api|credenciais|chave privada|tokens? de acesso)\b/i },
+  { surface: 'sensitive_storage', re: /\b(pii|personal data|ssn|sensitive (data|storage|information)|dados (pessoais|sensiveis)|cpf|informac\w* sensivel)\b/i }
 ];
 
 function detectSensitiveSurfaces(content) {
+  const c = foldDiacritics(content);
   const found = [];
   for (const { surface, re } of SENSITIVE_SURFACE_PATTERNS) {
-    if (re.test(content)) found.push(surface);
+    if (re.test(c)) found.push(surface);
   }
   return found;
 }
 
+// Operational-surface floor: a rich operational surface (workspaces, boards +
+// cards, Kanban/CRM pipelines, explicit CRUD/admin management) is never MICRO —
+// it needs management screens, so it must get at least the SMALL chain so
+// @analyst/@architect/the prototype are not skipped. Patterns are bilingual
+// (EN + pt-BR), matched against diacritic-folded text, and kept tight to avoid
+// flooring genuinely simple features. Bare "dashboard"/"quadro" is intentionally
+// NOT a signal (too common); only admin/management surfaces and board+card pairs count.
+function detectRichSurfaces(content) {
+  const c = foldDiacritics(content);
+  const found = [];
+  if (/\b(kanban|trello|scrum board|task board|quadro kanban|quadro de tarefas)\b/i.test(c)) found.push('kanban');
+  if (/\bworkspaces?\b/i.test(c) || /\bespacos? de trabalho\b/i.test(c)) found.push('workspace');
+  if ((/\bboards?\b/i.test(c) && /\bcards?\b/i.test(c))
+    || (/\bquadros?\b/i.test(c) && /\bcart(ao|oes)\b/i.test(c))) found.push('board_cards');
+  if (/\b(crm|sales pipeline|deals? pipeline|leads? pipeline|funil de vendas|pipeline de (vendas|negocios|leads))\b/i.test(c)) found.push('crm_pipeline');
+  if (/\bcrud\b/i.test(c)
+    || /\badmin (panel|dashboard|area|console)\b/i.test(c)
+    || /\bmanagement (screen|page|panel|dashboard|interface|surface)\b/i.test(c)
+    || /\barea administrativa\b/i.test(c)
+    || /\bpainel (de )?admin(istracao)?\b/i.test(c)
+    || /\b(painel|tela|pagina|area|console) de (administracao|gestao|gerenciamento)\b/i.test(c)) found.push('crud_admin');
+  return [...new Set(found)];
+}
+
 // Explicit `sensitive_surfaces:` frontmatter override — additive, can only force
 // the floor when content detection misses. Supports inline (`[a, b]` / `a, b`)
 // and YAML block list forms.
-function parseSensitiveSurfacesOverride(content) {
+function parseSurfacesOverride(content, key) {
   const fm = String(content || '').match(/^---\r?\n([\s\S]*?)\r?\n---/);
   if (!fm) return [];
   const body = fm[1];
   const items = [];
-  const inline = body.match(/^sensitive_surfaces:[ \t]*(.+)$/m);
+  const inline = body.match(new RegExp(`^${key}:[ \\t]*(.+)$`, 'm'));
   if (inline) {
     inline[1].trim().replace(/^\[|\]$/g, '').split(',').forEach((s) => {
       const v = s.trim().replace(/^["']|["']$/g, '');
       if (v) items.push(v);
     });
   }
-  const block = body.match(/^sensitive_surfaces:[ \t]*\r?\n((?:[ \t]*-[ \t]*.+\r?\n?)+)/m);
+  const block = body.match(new RegExp(`^${key}:[ \\t]*\\r?\\n((?:[ \\t]*-[ \\t]*.+\\r?\\n?)+)`, 'm'));
   if (block) {
     block[1].split(/\r?\n/).forEach((line) => {
       const m = line.match(/^[ \t]*-[ \t]*(.+)$/);
@@ -276,7 +312,7 @@ async function runClassify({ args, options = {}, logger }) {
 
   // Gap 3B — sensitive-surface floor (deterministic; raises MICRO -> SMALL only).
   const detectedSurfaces = content ? detectSensitiveSurfaces(content) : [];
-  const declaredSurfaces = content ? parseSensitiveSurfacesOverride(content) : [];
+  const declaredSurfaces = content ? parseSurfacesOverride(content, 'sensitive_surfaces') : [];
   const sensitiveSurfaces = [...new Set([...detectedSurfaces, ...declaredSurfaces])];
   let floored = false;
   if (sensitiveSurfaces.length > 0) {
@@ -285,8 +321,26 @@ async function runClassify({ args, options = {}, logger }) {
     floored = classification !== scored;
   }
 
+  // Operational-surface floor (deterministic; raises MICRO -> SMALL only). A rich
+  // operational surface needs management screens, so a Trello/Kanban/CRM/workspace
+  // feature can't take the MICRO shortcut that skips @analyst/@architect/prototype.
+  const detectedOps = content ? detectRichSurfaces(content) : [];
+  const declaredOps = content ? parseSurfacesOverride(content, 'operational_surfaces') : [];
+  const operationalSurfaces = [...new Set([...detectedOps, ...declaredOps])];
+  if (operationalSurfaces.length > 0) {
+    const scored = classification;
+    classification = applySensitiveFloor(classification);
+    floored = floored || classification !== scored;
+  }
+
   const phaseDepth = classificationToPhaseDepth(classification);
 
+  // A rich operational surface is exactly the case a clickable prototype is meant
+  // to de-risk (management screens + interactions before the PRD). Emit the
+  // recommendation from the deterministic tool so it does not rely on agent prose
+  // alone — @product/@briefing-refiner key off this flag.
+  const recommendPrototype = operationalSurfaces.length > 0;
+
   const result = {
     ok: true,
     feature_slug: slug,
@@ -295,7 +349,9 @@ async function runClassify({ args, options = {}, logger }) {
     scores: { user_types: utScore, integrations: intScore, complexity: cxScore, total: totalScore },
     classification,
     sensitive_surfaces: sensitiveSurfaces,
+    operational_surfaces: operationalSurfaces,
     floored,
+    recommend_prototype: recommendPrototype,
     phase_depth: phaseDepth
   };
 
@@ -314,6 +370,12 @@ async function runClassify({ args, options = {}, logger }) {
   if (sensitiveSurfaces.length > 0) {
     logger.log(`Sensitive surfaces: ${sensitiveSurfaces.join(', ')}${floored ? ' → floored to SMALL' : ''}`);
   }
+  if (operationalSurfaces.length > 0) {
+    logger.log(`Operational surfaces: ${operationalSurfaces.join(', ')}${floored ? ' → floored to at least SMALL' : ''}`);
+  }
+  if (recommendPrototype) {
+    logger.log('Recommendation: generate a clickable prototype in @briefing-refiner before @product (surfaces management screens + interactions early).');
+  }
   logger.log('');
   logger.log('Phase depth:');
   for (const [phase, desc] of Object.entries(phaseDepth)) {

package/src/commands/feature-close.js

@@ -22,10 +22,14 @@ const { emitDossierEvent } = require('../lib/dossier-telemetry');
 const { appendScoutToFeatureDossier } = require('../dossier/scout-section');
 const { emitSubTaskEvent } = require('../sub-task-telemetry');
 const { loadConfig } = require('../sub-task-engine');
-const { runDistillation, readFeatureClassification } = require('../learning-loop-engine');
-const { openRuntimeDb } = require('../runtime-store');
-const { runNotify } = require('./notify');
-const { splitCurrentState, buildArchiveContent, parseActiveSlugs } = require('../current-state-trim');
+const { runDistillation, readFeatureClassification } = require('../learning-loop-engine');
+const { openRuntimeDb } = require('../runtime-store');
+const { runNotify } = require('./notify');
+const { splitCurrentState, buildArchiveContent, parseActiveSlugs } = require('../current-state-trim');
+const {
+  evaluateContractIntegrityGate,
+  formatContractIntegrityGateError
+} = require('../harness/contract-integrity-gate');
 
 // P0 agent-loading-contract: a feature closing is the natural cadence to roll
 // aged-out current-state.md entries into the cold archive. Conservative window
@@ -322,18 +326,40 @@ async function runFeatureClose({ args, options = {}, logger }) {
   const updates = [];
 
   // 0a. Harness Done Gate (AC-HD-11 refined)
-  // Only enforced on PASS — FAIL means QA already rejected and we want the
-  // closure to record that. Without `harness-contract.json` for the feature,
-  // behavior is unchanged (zero impact on MICRO/SMALL or any feature that
-  // never opted into the harness).
+  // Only enforced on PASS — FAIL means QA already rejected and we want the
+  // closure to record that. Runtime features the CLI can detect (prototype or
+  // migration/Prisma evidence) must have a valid contract even on MICRO/SMALL;
+  // non-runtime features without a contract keep the historical lightweight path.
   if (verdict === 'PASS') {
     const planDir = path.join(targetDir, '.aioson', 'plans', slug);
-    const contractPath = path.join(planDir, 'harness-contract.json');
-    const progressPath = path.join(planDir, 'progress.json');
-    const contractContent = await readFileSafe(contractPath);
-    const progressContent = await readFileSafe(progressPath);
-
-    // REQ-13 (loop-guardrails): tema `publish` é gate de COMANDO — intercepta
+    const contractPath = path.join(planDir, 'harness-contract.json');
+    const progressPath = path.join(planDir, 'progress.json');
+    const contractContent = await readFileSafe(contractPath);
+    const progressContent = await readFileSafe(progressPath);
+    const force = options.force === true;
+
+    const integrityGate = await evaluateContractIntegrityGate(targetDir, slug, {
+      runChecks: Boolean(contractContent)
+    });
+    if (!integrityGate.ok) {
+      if (!force) {
+        const errMsg = formatContractIntegrityGateError(integrityGate);
+        if (options.json) {
+          return {
+            ok: false,
+            reason: 'harness_contract_gate_blocked',
+            feature: slug,
+            error: errMsg,
+            errors: integrityGate.errors
+          };
+        }
+        logger.log(errMsg);
+        return { ok: false, reason: 'harness_contract_gate_blocked' };
+      }
+      updates.push('harness contract gate: BYPASSED via --force');
+    }
+
+    // REQ-13 (loop-guardrails): tema `publish` é gate de COMANDO — intercepta
     // o feature:close quando o contrato ativo o exige e não há gate publish
     // aprovado. Nunca detectado por diff. `--force` NÃO bypassa: a aprovação
     // humana é o propósito do gate (decisão registrada no spec da feature).
@@ -372,10 +398,9 @@ async function runFeatureClose({ args, options = {}, logger }) {
         }
       } catch { /* contrato ilegível — o done gate abaixo lida com o estado */ }
     }
-
-    if (contractContent && progressContent) {
-      const force = options.force === true;
-      let progress = null;
+
+    if (contractContent && progressContent) {
+      let progress = null;
       try {
         progress = JSON.parse(progressContent);
       } catch (err) {