sinapse-ai 1.20.1 → 1.21.0

package/CHANGELOG.md

@@ -1,22 +1,17 @@
-## [1.20.1](https://github.com/caioimori/sinapse-ai/compare/1.20.0...1.20.1) (2026-07-03)
+## [1.21.0](https://github.com/caioimori/sinapse-ai/compare/1.20.1...1.21.0) (2026-07-04)
 
-### Bug Fixes
-
-* **security:** Onda A da triagem AF-20260703 — 4 fixes cirúrgicos ([#337](https://github.com/caioimori/sinapse-ai/issues/337)) ([39f3338](https://github.com/caioimori/sinapse-ai/commit/39f33384aea83df4f609c91eec1ef25acce30d29)), closes [#1](https://github.com/caioimori/sinapse-ai/issues/1) [524-#528](https://github.com/caioimori/524-/issues/528) [#332](https://github.com/caioimori/sinapse-ai/issues/332) [#511](https://github.com/caioimori/sinapse-ai/issues/511) [#32](https://github.com/caioimori/sinapse-ai/issues/32)
-* **security:** Onda B1 — TOCTOU na cadeia de confiança do instalador + git sem shell ([#340](https://github.com/caioimori/sinapse-ai/issues/340)) ([6f0a72b](https://github.com/caioimori/sinapse-ai/commit/6f0a72b89f8a72df741d5e7c94e89c2d3bd7bfd8)), closes [19/#20](https://github.com/19/sinapse-ai/issues/20) [15-#18](https://github.com/caioimori/15-/issues/18) [#22](https://github.com/caioimori/sinapse-ai/issues/22) [#507](https://github.com/caioimori/sinapse-ai/issues/507)
-* **security:** Onda B2 — escrita atômica em todo o caminho de instalação ([#341](https://github.com/caioimori/sinapse-ai/issues/341)) ([0c90216](https://github.com/caioimori/sinapse-ai/commit/0c9021628526ff7cf5ef3dcf41efae3dc629e20a))
-
-### Documentation
+### Features
 
-* **decisions:** registra Onda A de segurança executada (PR [#337](https://github.com/caioimori/sinapse-ai/issues/337)) ([#338](https://github.com/caioimori/sinapse-ai/issues/338)) ([c2dbe72](https://github.com/caioimori/sinapse-ai/commit/c2dbe72e2c686a9f2db01a85f4e02e444d4eea24))
-* **decisions:** registra Ondas B/C de segurança + rollout da ativação enxuta executados ([#343](https://github.com/caioimori/sinapse-ai/issues/343)) ([0500b56](https://github.com/caioimori/sinapse-ai/commit/0500b56411e44f25cb1729126a3de828ef3f251d))
+* **constitution:** Artigo IV ganha dente determinístico — traceability arquivo→AC ([#346](https://github.com/caioimori/sinapse-ai/issues/346)) ([9c0f991](https://github.com/caioimori/sinapse-ai/commit/9c0f991fda8e456d85e9338c904575fda13a907b))
+* **evals:** golden set comportamental do gate de épicos + eval:e2e no gate de merge [Story onda3-s4-behavioral-eval-regression] ([#349](https://github.com/caioimori/sinapse-ai/issues/349)) ([4c22695](https://github.com/caioimori/sinapse-ai/commit/4c226958bfa830f83c813f1ccf28bdf46f161c35))
+* **orchestration:** brownfield discovery ganha progresso determinístico + gate QA em código [Story onda3-s3-brownfield-progress-gate] ([#348](https://github.com/caioimori/sinapse-ai/issues/348)) ([8b3930e](https://github.com/caioimori/sinapse-ai/commit/8b3930e0b27a4431b6d21ad60832759bbd7ce74d))
+* **orchestration:** gates determinísticos de artefato na Phase 1 do greenfield ([#347](https://github.com/caioimori/sinapse-ai/issues/347)) ([ca61c0f](https://github.com/caioimori/sinapse-ai/commit/ca61c0f8c65d89a5cd8e2ff0c381330f25ee3c6f)), closes [#317](https://github.com/caioimori/sinapse-ai/issues/317)
+* **orchestration:** wave-gate executável + piloto medido de epic waves — REPROVADO pelo critério pré-registrado [Story onda3-s5-epic-waves-wrapper-pilot] ([#350](https://github.com/caioimori/sinapse-ai/issues/350)) ([172cd86](https://github.com/caioimori/sinapse-ai/commit/172cd86004adfb796c8e4eea18d992940c42aca3))
 
 ### Maintenance
 
-* **agents:** rollout da ativação enxuta — pós-piloto aprovado por avaliação ([#342](https://github.com/caioimori/sinapse-ai/issues/342)) ([6815e51](https://github.com/caioimori/sinapse-ai/commit/6815e511e13fb1fa146f0a866d054073075c9212)), closes [#332](https://github.com/caioimori/sinapse-ai/issues/332)
-* **cleanup:** DEC-03 — remove cluster multi-story órfão + split DEC-02 ([#344](https://github.com/caioimori/sinapse-ai/issues/344)) ([359b2fa](https://github.com/caioimori/sinapse-ai/commit/359b2fa2e905eee9be30ea5cac2d7a8bb305a0bd))
-* **release:** sync da main pós-release v1.20.0 ([#336](https://github.com/caioimori/sinapse-ai/issues/336)) ([b3973f0](https://github.com/caioimori/sinapse-ai/commit/b3973f0223173ce570b9ae49878f2d278dc257f8)), closes [#277](https://github.com/caioimori/sinapse-ai/issues/277)
-* **security:** Onda C — higiene do code scanning + 5 fixes de qualidade em produção ([#339](https://github.com/caioimori/sinapse-ai/issues/339)) ([13ae8dd](https://github.com/caioimori/sinapse-ai/commit/13ae8ddd314d2ab923ab019b4e0994be4e1627a1)), closes [#515](https://github.com/caioimori/sinapse-ai/issues/515) [#2](https://github.com/caioimori/sinapse-ai/issues/2) [#409](https://github.com/caioimori/sinapse-ai/issues/409) [#226](https://github.com/caioimori/sinapse-ai/issues/226) [401/#402](https://github.com/401/sinapse-ai/issues/402) [#228](https://github.com/caioimori/sinapse-ai/issues/228)
+* regenera manifests pós-consolidação da Onda 3 (S1-S5 na main) [Story onda3-s5-epic-waves-wrapper-pilot] ([#351](https://github.com/caioimori/sinapse-ai/issues/351)) ([302e99f](https://github.com/caioimori/sinapse-ai/commit/302e99fdcbca44bf8ec56064632e01ffd66fd40e)), closes [346-#350](https://github.com/caioimori/346-/issues/350)
+* **release:** sync da main pós-release 1.20.1 ([#345](https://github.com/caioimori/sinapse-ai/issues/345)) ([4bd61b4](https://github.com/caioimori/sinapse-ai/commit/4bd61b4c7cbdc06b76b0dec6b300a8fb3be5f06a)), closes [#277](https://github.com/caioimori/sinapse-ai/issues/277)
 
 # Changelog
 
@@ -27,6 +22,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.20.1] — 2026-07-03 — 🛡️ Segurança em 3 ondas + ativação enxuta + corte do cluster órfão (DEC-03)
+
+> Patch. Atualização segura via `npx sinapse-ai update`. Fecha a execução da mesa de decisões da otimização: PRs #337–#344.
+
+### Bug Fixes
+
+- **security:** Onda A da triagem AF-20260703 — 4 fixes cirúrgicos: CodeQL volta a analisar `actions`, escape de HTML na fonte geradora do atlas, âncoras agrupadas no secret-scan (equivalência validada com 20.030 casos), sanitização de log no updater (#337)
+- **security:** Onda B1 — TOCTOU eliminado na cadeia de confiança do instalador (manifest-signature/file-hasher/post-install-validator em file descriptor único) + git sem shell no gate do Artigo XI (#340)
+- **security:** Onda B2 — escrita atômica (tmp+rename) em ~30 pontos/21 arquivos de todo o caminho de instalação (#341)
+
+### Maintenance
+
+- **security:** Onda C — higiene do code scanning (`paths-ignore` de testes fecha ~366 alertas de teste na análise da main) + 2 falso-positivos dismissados com evidência + os 5 únicos fixes de qualidade fora de testes (#339)
+- **agents:** rollout da ativação enxuta pós-piloto — 22 arquivos (9 núcleo + 8 mastery + 4 locais + template), −717/+374 linhas, zero coerção restante (#342)
+- **cleanup:** DEC-03 — remoção do cluster multi-story órfão (~4,4k linhas de código morto shipped: wave-executor, parallel-monitor, context-injector, semantic-merge-engine, parallel-executor de execution/, wave-analyzer + task `*waves`) com split DEC-02 preservando suggestion-engine/learning; registries e manifests regenerados (#344)
+
+### Documentation
+
+- **decisions:** mesa de decisões registra Ondas A/B/C de segurança, rollout da ativação enxuta e execução de DEC-02/DEC-03 (#338, #343)
+
 ## [1.20.0] — 2026-07-03 — 🧠 Ciclo Fable 5: dieta de contexto, spec/plan de 1ª classe, era de modelo sincronizada
 
 > Minor. Atualização segura via `npx sinapse-ai update`. Consolida o ciclo de upgrade Fable 5 (auditoria AF-20260702 → Onda 1 → Onda 2 → mesa de decisões): 15 PRs (#321–#335).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sinapse-ai",
-  "version": "1.20.1",
+  "version": "1.21.0",
   "description": "SINAPSE AI: Framework de orquestracao de IA — 17 squads, 172 agentes especializados",
   "bin": {
     "sinapse": "bin/sinapse.js",
@@ -86,6 +86,7 @@
     "test:coverage": "jest --coverage",
     "test:health-check": "jest tests/health-check",
     "eval": "node scripts/eval-runner.js",
+    "eval:e2e": "node scripts/eval-e2e.js",
     "validate:evals": "node scripts/validate-evals.js",
     "validate:schemas": "node scripts/validate-schemas.js",
     "lint": "eslint . --cache --cache-location .eslintcache",
@@ -97,6 +98,7 @@
     "validate:article-vii": "node scripts/validate-article-vii.js",
     "validate:article-viii": "node scripts/validate-article-viii.js",
     "validate:article-xi": "node scripts/validate-article-xi.js",
+    "validate:article-iv": "node scripts/validate-article-iv.js",
     "reconcile:squads": "node scripts/reconcile-squad-manifests.js",
     "apply:persona-disclaimer": "node scripts/apply-persona-disclaimer.js",
     "validate:manifest": "node scripts/validate-manifest.js",

package/scripts/eval-e2e.js

@@ -0,0 +1,149 @@
+#!/usr/bin/env node
+
+/**
+ * eval-e2e.js — behavioral regression eval for the epic GateEvaluator.
+ *
+ * Story onda3-s4-behavioral-eval-regression (AF-20260702 item 3.1).
+ *
+ * Two layers:
+ *
+ *   DETERMINISTIC (always runs, merge gate): replays the versioned golden set
+ *   (tests/evals/epic-gates/cases.json) against the REAL orchestration
+ *   GateEvaluator with the DEFAULT gate config pinned (repo-local overrides in
+ *   core-config.yaml never bend the baseline). Every case is a measured bug
+ *   from the 2026-06-30 checkpoints — or a control case. Any mismatch = exit 1.
+ *
+ *   LLM ARM PREFLIGHT (opt-in: --llm or SINAPSE_EVAL_LLM=1): verifies that a
+ *   `claude` binary is spawnable and prints the exact 2-arm measurement
+ *   protocol commands (tests/evals/epic-gates/PROTOCOL.md). When the spawn is
+ *   unavailable (known Windows nested-spawn limitation, KNOWN-LIMITATIONS of
+ *   epic-orchestration-consolidation) it reports EVAL_LLM_SKIPPED with the
+ *   reason — an explicit skip, never a fake pass.
+ *
+ * Usage:
+ *   npm run eval:e2e
+ *   node scripts/eval-e2e.js [--llm]
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+const ROOT = path.resolve(__dirname, '..');
+const CASES_PATH = path.join(ROOT, 'tests', 'evals', 'epic-gates', 'cases.json');
+const PROTOCOL_PATH = path.join('tests', 'evals', 'epic-gates', 'PROTOCOL.md');
+
+const {
+  GateEvaluator,
+  DEFAULT_GATE_CONFIG,
+} = require(path.join(ROOT, '.sinapse-ai', 'core', 'orchestration', 'gate-evaluator'));
+
+/**
+ * Assert one golden case against a live gate result.
+ * @returns {string[]} List of mismatch descriptions (empty = pass)
+ */
+function assertCase(caseObj, result) {
+  const failures = [];
+  const expect = caseObj.expect || {};
+
+  if (expect.verdict && result.verdict !== expect.verdict) {
+    failures.push(`verdict: expected "${expect.verdict}", got "${result.verdict}"`);
+  }
+
+  if (typeof expect.scoreEquals === 'number' && Math.abs(result.score - expect.scoreEquals) > 0.01) {
+    failures.push(`score: expected ${expect.scoreEquals}, got ${result.score}`);
+  }
+
+  for (const name of expect.failedChecks || []) {
+    const check = result.checks.find((c) => c.name === name);
+    if (!check) failures.push(`failed check "${name}": not evaluated at all`);
+    else if (check.passed) failures.push(`failed check "${name}": expected FAIL, got PASS`);
+  }
+
+  for (const name of expect.passedChecks || []) {
+    const check = result.checks.find((c) => c.name === name);
+    if (!check) failures.push(`passed check "${name}": not evaluated at all`);
+    else if (!check.passed) failures.push(`passed check "${name}": expected PASS, got FAIL (${check.message})`);
+  }
+
+  for (const name of expect.issues || []) {
+    if (!result.issues.some((i) => i.check === name)) {
+      failures.push(`issue "${name}": expected present, not found`);
+    }
+  }
+
+  return failures;
+}
+
+async function runDeterministicLayer() {
+  const suite = JSON.parse(fs.readFileSync(CASES_PATH, 'utf8'));
+  console.log(`=== eval:e2e — ${suite.suite} (${suite.cases.length} cases) ===`);
+
+  let failedCases = 0;
+  for (const caseObj of suite.cases) {
+    // Fresh evaluator per case; DEFAULT config pinned so repo-local
+    // core-config.yaml overrides can never bend the behavioral baseline.
+    const evaluator = new GateEvaluator({
+      projectRoot: ROOT,
+      strictMode: Boolean(caseObj.strictMode),
+      gateConfig: DEFAULT_GATE_CONFIG,
+    });
+
+    const result = await evaluator.evaluate(caseObj.gate.from, caseObj.gate.to, caseObj.epicResult);
+    const failures = assertCase(caseObj, result);
+
+    if (failures.length === 0) {
+      console.log(`  PASS  ${caseObj.id}`);
+    } else {
+      failedCases += 1;
+      console.log(`  FAIL  ${caseObj.id}`);
+      for (const f of failures) console.log(`        - ${f}`);
+    }
+  }
+
+  console.log('');
+  if (failedCases > 0) {
+    console.log(`eval:e2e: FAIL — ${failedCases}/${suite.cases.length} behavioral case(s) regressed.`);
+    return false;
+  }
+  console.log(`eval:e2e: OK — all ${suite.cases.length} behavioral cases passed.`);
+  return true;
+}
+
+function runLlmArmPreflight() {
+  console.log('');
+  console.log('=== eval:e2e — LLM arm preflight ===');
+  try {
+    const version = execFileSync('claude', ['--version'], {
+      encoding: 'utf8',
+      timeout: 30000,
+      shell: process.platform === 'win32',
+    }).trim();
+    console.log(`claude spawnable: ${version}`);
+    console.log(`Protocolo de medição 2 braços: ${PROTOCOL_PATH}`);
+    console.log('Execute os braços conforme o protocolo e registre o scoreboard no checkpoint.');
+    return true;
+  } catch (error) {
+    console.log(`EVAL_LLM_SKIPPED: claude não spawnável daqui (${error.message.split('\n')[0]}).`);
+    console.log('Motivo conhecido no Windows: spawn aninhado falha (KNOWN-LIMITATIONS,');
+    console.log('epic-orchestration-consolidation). Rode o braço LLM via harness ou em');
+    console.log(`ambiente com spawn direto, seguindo ${PROTOCOL_PATH}.`);
+    return true; // skip explícito não é falha — mas nunca é reportado como PASS do braço
+  }
+}
+
+async function main() {
+  const wantLlm = process.argv.includes('--llm') || process.env.SINAPSE_EVAL_LLM === '1';
+
+  const deterministicOk = await runDeterministicLayer();
+  if (wantLlm) runLlmArmPreflight();
+
+  process.exit(deterministicOk ? 0 : 1);
+}
+
+main().catch((error) => {
+  console.error(`eval:e2e crashed: ${error.message}`);
+  process.exit(1);
+});

package/scripts/validate-all.js

@@ -55,6 +55,9 @@ const GUARDS = [
   { name: 'squad-yaml', script: 'validate:squad-yaml' },
   { name: 'squad-orqx', script: 'validate:squad-orqx' },
   { name: 'agent-codenames', script: 'validate:agent-codenames' },
+  // Article IV traceability — WARN-only during calibration: the script itself
+  // exits 0 on orphans unless ARTICLE_IV_STRICT=1 (see validate-article-iv.js).
+  { name: 'article-iv', script: 'validate:article-iv' },
 ];
 
 /**

package/scripts/validate-article-iv.js

@@ -0,0 +1,289 @@
+#!/usr/bin/env node
+
+/**
+ * validate-article-iv.js — Constitution Article IV (No Invention) traceability check.
+ *
+ * Story onda3-s1-article-iv-traceability (AF-20260702 item 3.2).
+ *
+ * What it does (deterministic, no LLM):
+ *   1. Resolves the push range: merge-base(HEAD, origin/main)..HEAD.
+ *   2. Extracts story refs ("[Story xyz]") from commit messages in the range.
+ *   3. Locates each referenced story under docs/stories/ and extracts its
+ *      acceptance criteria ("- [ ] ACn:") and its "## File List" section.
+ *   4. Compares changed PRODUCT files against the union of the stories'
+ *      File Lists. A changed product file mapped by no story is an ORPHAN.
+ *
+ * Calibration mode (default): orphans are WARNINGS, exit 0. Pass --strict
+ * (or ARTICLE_IV_STRICT=1) to turn orphans into a failure (exit 1). The
+ * warning phase exists to calibrate the matcher before it gets teeth —
+ * mirrors the rollout the audit prescribed ("órfão começa como warning").
+ *
+ * Why this runs at pre-push and NOT in GitHub CI: docs/stories/ is local-only
+ * (gitignored by design — stories are working artifacts). CI has no stories
+ * to trace against, so the only honest home for this check is the developer
+ * machine, where the stories exist. When stories are unavailable the check
+ * reports ARTICLE_IV_SKIPPED and exits 0 — an explicit skip, never a fake pass.
+ *
+ * Usage:
+ *   npm run validate:article-iv
+ *   node scripts/validate-article-iv.js [--strict] [--base <ref>]
+ */
+
+'use strict';
+
+const { execFileSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+const ROOT = path.resolve(__dirname, '..');
+
+// Prefixes that count as product surface for traceability purposes.
+// Aligned with enforce-story-gate.cjs CODE_PATHS plus the framework tree
+// (.sinapse-ai) and scripts/, which are product in this repo.
+const PRODUCT_PREFIXES = [
+  'packages/',
+  'src/',
+  'app/',
+  'lib/',
+  'bin/',
+  'components/',
+  'pages/',
+  'api/',
+  'services/',
+  'scripts/',
+  '.sinapse-ai/',
+];
+
+// Never traced: docs, tests, mirrors, CI plumbing and generated artifacts —
+// they either have their own governance or are regenerated mechanically.
+const EXCLUDED_PREFIXES = [
+  'docs/',
+  'tests/',
+  '.claude/',
+  '.codex/',
+  '.github/',
+  'audits/',
+  'governance/',
+];
+
+const GENERATED_FILES = [
+  '.sinapse-ai/install-manifest.yaml',
+  '.sinapse-ai/data/entity-registry.yaml',
+  '.sinapse-ai/manifests/agents.csv',
+  '.sinapse-ai/manifests/workers.csv',
+  '.sinapse-ai/manifests/tasks.csv',
+];
+
+const STORY_REF_RE = /\[story\s+([^\]]+)\]/gi;
+const AC_RE = /^- \[( |x)\] (AC\d+):\s*(.*)$/gim;
+
+/** Extract unique story refs ("[Story 2.1]" → "2.1") from free text. */
+function extractStoryRefs(text) {
+  const refs = new Set();
+  let m;
+  STORY_REF_RE.lastIndex = 0;
+  while ((m = STORY_REF_RE.exec(text)) !== null) {
+    const ref = m[1].trim();
+    if (ref) refs.add(ref);
+  }
+  return [...refs];
+}
+
+/** Extract acceptance criteria from story markdown. */
+function extractAcceptanceCriteria(storyContent) {
+  const acs = [];
+  let m;
+  AC_RE.lastIndex = 0;
+  while ((m = AC_RE.exec(storyContent)) !== null) {
+    acs.push({ id: m[2].toUpperCase(), checked: m[1] === 'x', text: m[3].trim() });
+  }
+  return acs;
+}
+
+/**
+ * Extract path-ish entries from the story's "## File List" section.
+ * Accepts list items like "- path/to/file.js (novo)" — the first
+ * whitespace-delimited token of each bullet is taken as the path.
+ */
+function extractFileList(storyContent) {
+  const lines = storyContent.split(/\r?\n/);
+  const entries = [];
+  let inSection = false;
+  for (const line of lines) {
+    if (/^##\s+file list\s*$/i.test(line.trim())) {
+      inSection = true;
+      continue;
+    }
+    if (inSection && /^##\s+/.test(line.trim())) break;
+    if (!inSection) continue;
+    const bullet = line.trim().match(/^[-*]\s+(.*)$/);
+    if (!bullet) continue;
+    const token = bullet[1].trim().split(/\s+/)[0];
+    if (token) entries.push(token.replace(/\\/g, '/').replace(/[,;]$/, ''));
+  }
+  return entries;
+}
+
+/** True when a changed path counts as traceable product surface. */
+function isProductFile(rel) {
+  const norm = rel.replace(/\\/g, '/');
+  if (GENERATED_FILES.includes(norm)) return false;
+  if (EXCLUDED_PREFIXES.some((p) => norm.startsWith(p))) return false;
+  return PRODUCT_PREFIXES.some((p) => norm.startsWith(p));
+}
+
+/**
+ * Match changed product files against File List entries.
+ * A file is mapped when some entry equals it, is a prefix directory of it,
+ * or the file path ends with the entry (tolerates entries written relative).
+ */
+function matchFilesToStory(changedProductFiles, fileListEntries) {
+  const norm = (s) => s.replace(/\\/g, '/').toLowerCase();
+  const entries = fileListEntries.map(norm);
+  const mapped = [];
+  const orphans = [];
+  for (const file of changedProductFiles) {
+    const f = norm(file);
+    const hit = entries.some(
+      (e) => e === f || f.startsWith(e.endsWith('/') ? e : `${e}/`) || f.endsWith(e),
+    );
+    (hit ? mapped : orphans).push(file);
+  }
+  return { mapped, orphans };
+}
+
+/** Recursively collect .md files under a directory. */
+function walkMarkdown(dir) {
+  const out = [];
+  let items = [];
+  try {
+    items = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return out;
+  }
+  for (const item of items) {
+    const full = path.join(dir, item.name);
+    if (item.isDirectory()) out.push(...walkMarkdown(full));
+    else if (item.name.endsWith('.md')) out.push(full);
+  }
+  return out;
+}
+
+/**
+ * Find the story file for a ref: filename containing the slugged ref, or
+ * story content containing the literal "[Story <ref>]".
+ */
+function findStoryFile(storiesDir, ref) {
+  const slug = ref.toLowerCase().replace(/\s+/g, '-');
+  const files = walkMarkdown(storiesDir);
+  for (const file of files) {
+    const base = path.basename(file, '.md').toLowerCase();
+    if (base.includes(slug)) return file;
+  }
+  const needle = `[story ${ref.toLowerCase()}]`;
+  for (const file of files) {
+    try {
+      if (fs.readFileSync(file, 'utf8').toLowerCase().includes(needle)) return file;
+    } catch {
+      /* unreadable file — keep scanning */
+    }
+  }
+  return null;
+}
+
+function git(args) {
+  return execFileSync('git', args, { cwd: ROOT, encoding: 'utf8' });
+}
+
+function main() {
+  const argv = process.argv.slice(2);
+  const strict = argv.includes('--strict') || process.env.ARTICLE_IV_STRICT === '1';
+  const baseIdx = argv.indexOf('--base');
+  const baseRef = baseIdx !== -1 ? argv[baseIdx + 1] : process.env.ARTICLE_IV_BASE || 'origin/main';
+
+  let mergeBase;
+  try {
+    mergeBase = git(['merge-base', 'HEAD', baseRef]).trim();
+  } catch {
+    console.log(`ARTICLE_IV_SKIPPED: cannot resolve merge-base with ${baseRef} (no remote?).`);
+    process.exit(0);
+  }
+
+  const changed = git(['diff', '--name-only', `${mergeBase}..HEAD`])
+    .split(/\r?\n/)
+    .filter(Boolean);
+  const commitText = git(['log', '--format=%B', `${mergeBase}..HEAD`]);
+
+  const refs = extractStoryRefs(commitText);
+  if (refs.length === 0) {
+    console.log('article-iv: no story refs in push range — nothing to trace.');
+    process.exit(0);
+  }
+
+  const storiesDir = path.join(ROOT, 'docs', 'stories');
+  if (!fs.existsSync(storiesDir)) {
+    console.log('ARTICLE_IV_SKIPPED: docs/stories unavailable (local-only artifact).');
+    process.exit(0);
+  }
+
+  const fileListUnion = [];
+  const foundStories = [];
+  const missingRefs = [];
+  for (const ref of refs) {
+    const storyFile = findStoryFile(storiesDir, ref);
+    if (!storyFile) {
+      missingRefs.push(ref);
+      continue;
+    }
+    const content = fs.readFileSync(storyFile, 'utf8');
+    foundStories.push({ ref, file: path.relative(ROOT, storyFile), acs: extractAcceptanceCriteria(content).length });
+    fileListUnion.push(...extractFileList(content));
+  }
+
+  if (foundStories.length === 0) {
+    console.log(
+      `ARTICLE_IV_SKIPPED: no referenced story found locally (refs: ${refs.join(', ')}).`,
+    );
+    process.exit(0);
+  }
+
+  const productChanged = changed.filter(isProductFile);
+  const { mapped, orphans } = matchFilesToStory(productChanged, fileListUnion);
+
+  console.log('=== article-iv traceability ===');
+  for (const s of foundStories) {
+    console.log(`story [${s.ref}] -> ${s.file} (${s.acs} ACs)`);
+  }
+  if (missingRefs.length) {
+    console.log(`refs without local story (skipped): ${missingRefs.join(', ')}`);
+  }
+  console.log(`product files changed: ${productChanged.length} | mapped: ${mapped.length} | orphans: ${orphans.length}`);
+
+  if (orphans.length > 0) {
+    console.log('');
+    console.log('ORPHAN product files (changed but absent from every referenced File List):');
+    for (const f of orphans) console.log(`  WARN  ${f}`);
+    console.log('');
+    console.log('Fix: add the file to the story\'s "## File List", or move the change to its own story.');
+    if (strict) {
+      console.log('article-iv: FAIL (strict mode).');
+      process.exit(1);
+    }
+    console.log('article-iv: WARN-only (calibration mode) — not blocking.');
+    process.exit(0);
+  }
+
+  console.log('article-iv: OK — full traceability.');
+  process.exit(0);
+}
+
+module.exports = {
+  extractStoryRefs,
+  extractAcceptanceCriteria,
+  extractFileList,
+  isProductFile,
+  matchFilesToStory,
+  findStoryFile,
+};
+
+if (require.main === module) main();

package/scripts/validate-evals.js

@@ -146,7 +146,14 @@ function isPlainObject(v) {
   return v !== null && typeof v === 'object' && !Array.isArray(v);
 }
 
-/** Discover gate folders under tests/evals/ (every dir except _lib / _*). */
+/**
+ * Suites that follow their OWN contract (not the IDS evals.json/triggers.json
+ * one) and have their own runner + jest wrapper. Onda3-S4: epic-gates uses
+ * cases.json validated by scripts/eval-e2e.js.
+ */
+const NON_IDS_SUITES = new Set(['epic-gates']);
+
+/** Discover gate folders under tests/evals/ (every dir except _lib / _* / non-IDS suites). */
 function discoverGateDirs() {
   let entries;
   try {
@@ -156,7 +163,7 @@ function discoverGateDirs() {
     process.exit(2);
   }
   return entries
-    .filter((d) => d.isDirectory() && !d.name.startsWith('_'))
+    .filter((d) => d.isDirectory() && !d.name.startsWith('_') && !NON_IDS_SUITES.has(d.name))
     .map((d) => path.join(EVALS_ROOT, d.name))
     .sort();
 }