sinapse-ai 1.20.1 → 1.22.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sinapse-ai",
-  "version": "1.20.1",
+  "version": "1.22.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",
@@ -132,6 +134,10 @@
     "validate:cross-refs": "node scripts/validate-cross-refs.js",
     "validate:agents-md": "node scripts/validate-agents-md.js",
     "validate:agents-md:fix": "node scripts/validate-agents-md.js --fix",
+    "validate:tool-descriptions": "node scripts/validate-tool-descriptions.js",
+    "validate:story-acs": "node scripts/validate-story-acs.js",
+    "calibrate:judge": "node scripts/calibrate-judge.js",
+    "validate:constitution": "node scripts/validate-constitution.js",
     "validate:all": "node scripts/validate-all.js",
     "sync:squad-yaml": "node scripts/sync-squad-yaml-components.js",
     "validate:squad-yaml": "node scripts/sync-squad-yaml-components.js --check",

package/scripts/calibrate-judge.js

@@ -0,0 +1,134 @@
+#!/usr/bin/env node
+/**
+ * LLM-judge calibration harness (Story mesa2-llm-judge-calibration, AF-20260704 Mesa #2).
+ *
+ * The judge that decides "Done" is the @quality-gate agent: it emits free-form
+ * prose ending in `VERDICT: X`, and Epic6Executor._parseVerdict turns that prose
+ * into the binary verdict (APPROVED → Done). This harness calibrates that
+ * DETERMINISTIC seam against a human-labeled golden set:
+ *
+ *   - It runs the REAL _parseVerdict (imported, never re-implemented) over each
+ *     golden output and checks it agrees with the human-assigned verdict.
+ *   - _parseVerdict is deterministic, so the gate is 100%: any disagreement means
+ *     the parser regressed OR a golden label is wrong — both demand action.
+ *
+ * This does NOT calibrate the LLM's semantic judgment (non-deterministic, costly)
+ * — that is the documented LIVE procedure (feed the golden scenarios to the real
+ * @quality-gate and compare). See .sinapse-ai/quality/judge-calibration/README.md.
+ *
+ * `scoreCalibration` is pure so tests can drive it with any parse function.
+ *
+ * Exit 0 = full agreement · Exit 1 = one or more disagreements.
+ *
+ * @module scripts/calibrate-judge
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const ROOT = path.resolve(__dirname, '..');
+const GOLDEN_SET_PATH = path.join(
+  ROOT,
+  '.sinapse-ai/quality/judge-calibration/golden-set.json',
+);
+
+/**
+ * The REAL verdict-decision logic under calibration. `_parseVerdict` uses only
+ * its `output` argument and the module-level QAVerdict constants (no `this`), so
+ * it can be invoked detached via the prototype — using the exact production
+ * function, never a copy.
+ *
+ * @returns {(output: string) => string}
+ */
+function loadRealParseVerdict() {
+  const Epic6Executor = require('../.sinapse-ai/core/orchestration/executors/epic-6-executor.js');
+  const fn = Epic6Executor.prototype._parseVerdict;
+  return (output) => fn.call(null, output);
+}
+
+/**
+ * Score a parse function against golden cases.
+ *
+ * @param {Array<{ id: string, output: string, expected: string }>} cases
+ * @param {(output: string) => string} parseFn
+ * @returns {{
+ *   total: number,
+ *   agreed: number,
+ *   agreementRate: number,
+ *   disagreements: Array<{ id: string, expected: string, predicted: string }>,
+ *   confusion: Record<string, Record<string, number>>
+ * }}
+ */
+function scoreCalibration(cases, parseFn) {
+  const disagreements = [];
+  const confusion = {};
+  let agreed = 0;
+
+  for (const c of cases) {
+    const predicted = parseFn(c.output);
+    confusion[c.expected] = confusion[c.expected] || {};
+    confusion[c.expected][predicted] = (confusion[c.expected][predicted] || 0) + 1;
+    if (predicted === c.expected) {
+      agreed += 1;
+    } else {
+      disagreements.push({ id: c.id, expected: c.expected, predicted });
+    }
+  }
+
+  const total = cases.length;
+  return {
+    total,
+    agreed,
+    agreementRate: total === 0 ? 1 : agreed / total,
+    disagreements,
+    confusion,
+  };
+}
+
+/** CLI entry point. */
+function main() {
+  let golden;
+  try {
+    golden = JSON.parse(fs.readFileSync(GOLDEN_SET_PATH, 'utf8'));
+  } catch (err) {
+    console.error(`calibrate-judge: cannot read golden set at ${GOLDEN_SET_PATH}: ${err.message}`);
+    process.exit(1);
+  }
+
+  const cases = Array.isArray(golden.cases) ? golden.cases : [];
+  if (cases.length === 0) {
+    console.error('calibrate-judge: golden set has no cases.');
+    process.exit(1);
+  }
+
+  const parseFn = loadRealParseVerdict();
+  const result = scoreCalibration(cases, parseFn);
+
+  const pct = (result.agreementRate * 100).toFixed(1);
+  console.log(`judge calibration: ${result.agreed}/${result.total} agree with the human golden set (${pct}%).`);
+  console.log('confusion (expected → predicted):');
+  for (const expected of Object.keys(result.confusion)) {
+    const preds = result.confusion[expected];
+    const parts = Object.keys(preds).map((p) => `${p}:${preds[p]}`).join(', ');
+    console.log(`  ${expected} → ${parts}`);
+  }
+
+  if (result.disagreements.length === 0) {
+    console.log('PASS — deterministic verdict extraction is calibrated to the human baseline.');
+    process.exit(0);
+  }
+
+  console.log('');
+  console.log(`FAIL — ${result.disagreements.length} case(s) disagree with the human label:`);
+  for (const d of result.disagreements) {
+    console.log(`  ${d.id}: expected ${d.expected}, parser produced ${d.predicted}`);
+  }
+  console.log('\nEither _parseVerdict regressed or the golden label is wrong. Fix the code or the label — do not loosen the gate.');
+  process.exit(1);
+}
+
+if (require.main === module) main();
+
+module.exports = { scoreCalibration, loadRealParseVerdict, GOLDEN_SET_PATH };

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,14 @@ const GUARDS = [
   { name: 'squad-yaml', script: 'validate:squad-yaml' },
   { name: 'squad-orqx', script: 'validate:squad-orqx' },
   { name: 'agent-codenames', script: 'validate:agent-codenames' },
+  { name: 'tool-descriptions', script: 'validate:tool-descriptions' },
+  { name: 'constitution', script: 'validate:constitution' },
+  // ACs in Given/When/Then — WARN-only (exits 0 unless STORY_ACS_STRICT=1) and
+  // a no-op PASS in CI where docs/stories/ (gitignored) is absent.
+  { name: 'story-acs', script: 'validate:story-acs' },
+  // 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-constitution.js

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+/**
+ * Lint guard: Constitution consistency across CLAUDE.md ⇄ AGENTS.md (+ source,
+ * install template, rules). Story rodada2-m5 (AF-20260704 Mesa #7).
+ *
+ * The Mesa item framed CLAUDE.md and AGENTS.md as "twins that drift" and asked
+ * to generate both from one source. Verification REFUTED that premise: the two
+ * files serve different surfaces (Claude Code vs Codex), share almost no verbatim
+ * body, and their only shared canon — the ecosystem counts and the Constitution
+ * article set — is already single-sourced. Counts are guarded by
+ * `validate:agents-md`; the article agreement is validated by the
+ * `constitution-consistency` doctor check.
+ *
+ * The real, narrow gap this guard closes: that doctor check ran only under
+ * `sinapse doctor` and the install matrix — NOT on the PR gate. So article drift
+ * between CLAUDE.md and AGENTS.md could merge unnoticed. This wraps the SAME
+ * existing check (no new logic, no twin-generator) so it runs on every push/PR.
+ *
+ * Exit 0 = consistent (PASS/WARN) · Exit 1 = FAIL (a consumer is missing a
+ * canonical article, or the source/rules are missing).
+ *
+ * @module scripts/validate-constitution
+ */
+
+'use strict';
+
+const path = require('path');
+
+const check = require('../.sinapse-ai/core/doctor/checks/constitution-consistency');
+
+async function main() {
+  const projectRoot = path.resolve(__dirname, '..');
+  let result;
+  try {
+    result = await check.run({ projectRoot });
+  } catch (err) {
+    // The check declares onError:'fail' — a thrown error is a real problem.
+    console.error(`FAIL — constitution-consistency threw: ${err.message}`);
+    process.exit(1);
+  }
+
+  const status = result.status || 'FAIL';
+  if (status === 'PASS') {
+    console.log(`OK — ${result.message}`);
+    process.exit(0);
+  }
+  if (status === 'WARN') {
+    // Minor divergence (≤2 issues) — surface it but do not block (matches the
+    // doctor severity gradation; Art. XI, avoid over-tightening the gate).
+    console.warn(`WARN — ${result.message}`);
+    process.exit(0);
+  }
+  console.error(`FAIL — ${result.message}`);
+  if (result.fixCommand) console.error(`  fix: ${result.fixCommand}`);
+  process.exit(1);
+}
+
+main();