sinapse-ai 1.20.1 → 1.22.0

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();
 }

package/scripts/validate-story-acs.js

@@ -0,0 +1,174 @@
+#!/usr/bin/env node
+/**
+ * Advisory guard: acceptance criteria in executable Given/When/Then form
+ * (Story mesa2-acs-gwt-guard, AF-20260704 Mesa #3).
+ *
+ * GWT is the documented "preferred" AC format (story-lifecycle.md), but stories
+ * historically copy free-form numbered lists from the epic. This guard flags ACs
+ * that are NOT in GWT so authors can tighten them — it is advisory by design:
+ *
+ *   - Exit 0 always (WARN-only), mirroring validate-article-iv, UNLESS
+ *     STORY_ACS_STRICT=1 is set and at least one non-GWT AC is found.
+ *   - `docs/stories/` is gitignored (local, unversioned), so in CI there are
+ *     typically no story files — the guard degrades gracefully to a PASS with
+ *     "nothing to lint" instead of failing.
+ *
+ * The core is a pure function (`lintStoryAcs`) so tests can drive it with
+ * fixtures; the CLI wrapper walks the default story dir.
+ *
+ * @module scripts/validate-story-acs
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const ROOT = process.cwd();
+
+/** Default lint target: local story files (gitignored — may be absent in CI). */
+const DEFAULT_STORIES_DIR = 'docs/stories';
+
+/** Heading that opens the acceptance-criteria section (case-insensitive). */
+const AC_HEADING = /^#{1,6}\s+acceptance\s+criteria\b/i;
+
+/** Any markdown heading — closes the AC section. */
+const ANY_HEADING = /^#{1,6}\s+/;
+
+/** A list item (bullet `-`/`*` with optional checkbox, or `N.` numbered). */
+const LIST_ITEM = /^\s*(?:[-*]\s+(?:\[[ xX]\]\s+)?|\d+[.)]\s+)(.+)$/;
+
+/**
+ * True when a single AC's text is in executable Given/When/Then form — it must
+ * mention all three keywords (order-agnostic, case-insensitive).
+ *
+ * @param {string} text
+ * @returns {boolean}
+ */
+function isGwt(text) {
+  const t = text.toLowerCase();
+  return /\bgiven\b/.test(t) && /\bwhen\b/.test(t) && /\bthen\b/.test(t);
+}
+
+/**
+ * Extract the acceptance-criteria list items from a story's markdown body and
+ * classify each as GWT or not.
+ *
+ * @param {string} content - full markdown of a story file
+ * @returns {{ total: number, gwt: number, nonGwt: Array<{ text: string }> }}
+ */
+function lintStoryAcs(content) {
+  const lines = String(content).split(/\r?\n/);
+  const items = [];
+
+  let inSection = false;
+  let current = null; // accumulates a multi-line AC item
+
+  const flush = () => {
+    if (current !== null) {
+      items.push(current.trim());
+      current = null;
+    }
+  };
+
+  for (const line of lines) {
+    if (!inSection) {
+      if (AC_HEADING.test(line)) inSection = true;
+      continue;
+    }
+    // A new heading ends the AC section.
+    if (ANY_HEADING.test(line)) {
+      flush();
+      break;
+    }
+    const m = line.match(LIST_ITEM);
+    if (m) {
+      flush();
+      current = m[1];
+    } else if (current !== null && line.trim() !== '') {
+      // continuation line of the current AC item
+      current += ' ' + line.trim();
+    } else if (current !== null && line.trim() === '') {
+      flush();
+    }
+  }
+  flush();
+
+  const nonGwt = items.filter((t) => !isGwt(t)).map((text) => ({ text }));
+  return { total: items.length, gwt: items.length - nonGwt.length, nonGwt };
+}
+
+/** Recursively collect `.md` files under a directory. */
+function walkMarkdown(dir, out = []) {
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return out;
+  }
+  for (const e of entries) {
+    const p = path.join(dir, e.name);
+    if (e.isDirectory()) walkMarkdown(p, out);
+    else if (e.name.endsWith('.md')) out.push(p);
+  }
+  return out;
+}
+
+/** CLI entry point. */
+function main() {
+  const strict = process.env.STORY_ACS_STRICT === '1';
+  const dir = path.join(ROOT, DEFAULT_STORIES_DIR);
+  const files = walkMarkdown(dir);
+
+  if (files.length === 0) {
+    console.log(
+      `story-acs: no story files under ${DEFAULT_STORIES_DIR}/ (gitignored) — nothing to lint. PASS.`,
+    );
+    process.exit(0);
+  }
+
+  let totalAcs = 0;
+  let totalNonGwt = 0;
+  const report = [];
+
+  for (const file of files) {
+    let content;
+    try {
+      content = fs.readFileSync(file, 'utf8');
+    } catch {
+      continue;
+    }
+    const { total, nonGwt } = lintStoryAcs(content);
+    if (total === 0) continue; // not an AC-bearing story
+    totalAcs += total;
+    if (nonGwt.length > 0) {
+      totalNonGwt += nonGwt.length;
+      report.push({ file: path.relative(ROOT, file), nonGwt });
+    }
+  }
+
+  if (totalNonGwt === 0) {
+    console.log(`story-acs: ${totalAcs} AC(s) across ${files.length} file(s), all GWT-shaped. PASS.`);
+    process.exit(0);
+  }
+
+  const level = strict ? 'FAIL' : 'WARN';
+  console.log(`story-acs [${level}]: ${totalNonGwt}/${totalAcs} AC(s) are not in Given/When/Then form:`);
+  for (const r of report) {
+    console.log(`  ${r.file}`);
+    for (const { text } of r.nonGwt) {
+      const preview = text.length > 90 ? text.slice(0, 87) + '...' : text;
+      console.log(`    - ${preview}`);
+    }
+  }
+  console.log(
+    strict
+      ? '\nSTORY_ACS_STRICT=1 → failing. Rewrite the ACs above as "Given <ctx>, When <action>, Then <outcome>."'
+      : '\nAdvisory only (exit 0). Prefer "Given <ctx>, When <action>, Then <outcome>." Set STORY_ACS_STRICT=1 to enforce.',
+  );
+  process.exit(strict ? 1 : 0);
+}
+
+if (require.main === module) main();
+
+module.exports = { lintStoryAcs, isGwt };

package/scripts/validate-tool-descriptions.js

@@ -0,0 +1,128 @@
+#!/usr/bin/env node
+/**
+ * Lint guard: tool/command descriptions (Story M2-mesa M3, AF-20260704 #9a).
+ *
+ * A command an agent exposes IS a tool, and its `description:` is the contract
+ * that drives selection (KIT-ai-engineering, Tool Use). A vague, empty, or
+ * placeholder description silently degrades routing. This guard enforces a
+ * minimal clarity contract on every `description:` field in the agent
+ * definitions, and is wired into `validate:all`.
+ *
+ * Exit 0 = all descriptions valid · Exit 1 = one or more violate the contract.
+ *
+ * The core is a pure function (`lintDescriptions`) so tests can drive it with
+ * fixtures; the CLI wrapper globs the default targets.
+ *
+ * @module scripts/validate-tool-descriptions
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const ROOT = process.cwd();
+
+/** Default lint targets: the framework agent definitions (source of truth). */
+const DEFAULT_TARGET_DIRS = ['.sinapse-ai/development/agents'];
+
+/** Minimum characters for a meaningful description (smallest real one is 12). */
+const MIN_LEN = 8;
+
+/** Values that are placeholders, not real descriptions. */
+const PLACEHOLDER = /^(todo|tbd|fixme|x{2,}|placeholder|custom|n\/?a|desc|description|\.\.\.|-+|\?+)$/i;
+
+/**
+ * The WHOLE value is nothing but a template token — e.g. `{description}` or
+ * `<desc>`. Inline braces documenting command args (e.g. "Build story
+ * (*build {story-id})") are legitimate and must NOT be flagged.
+ */
+const TEMPLATE_ONLY = /^[{<][^}>]*[}>]$/;
+
+/** A YAML block-scalar indicator — the real text follows on indented lines. */
+const BLOCK_SCALAR = /^[|>][+-]?\d*$/;
+
+/** Recursively collect `.md` files under a directory. */
+function walkMarkdown(dir, out = []) {
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return out;
+  }
+  for (const e of entries) {
+    const p = path.join(dir, e.name);
+    if (e.isDirectory()) walkMarkdown(p, out);
+    else if (e.name.toLowerCase().endsWith('.md')) out.push(p);
+  }
+  return out;
+}
+
+/** Strip a single layer of matching quotes from a YAML scalar. */
+function unquote(s) {
+  const t = s.trim();
+  if ((t.startsWith("'") && t.endsWith("'")) || (t.startsWith('"') && t.endsWith('"'))) {
+    return t.slice(1, -1).trim();
+  }
+  return t;
+}
+
+/**
+ * Lint `description:` fields in the given files.
+ * @param {string[]} files
+ * @returns {Array<{file:string, line:number, value:string, reason:string}>}
+ */
+function lintDescriptions(files) {
+  const violations = [];
+  for (const file of files) {
+    let content;
+    try {
+      content = fs.readFileSync(file, 'utf8');
+    } catch {
+      continue;
+    }
+    const lines = content.split(/\r?\n/);
+    lines.forEach((raw, i) => {
+      const m = raw.match(/^\s*description:\s*(.*)$/);
+      if (!m) return;
+      const rawValue = m[1].trim();
+      // Block scalars (`description: |`) carry the text on the following indented
+      // lines — treat as valid rather than flag the indicator itself.
+      if (BLOCK_SCALAR.test(rawValue)) return;
+      const value = unquote(rawValue);
+      let reason = null;
+      if (value === '') reason = 'descrição vazia';
+      else if (PLACEHOLDER.test(value)) reason = `placeholder ("${value}")`;
+      else if (TEMPLATE_ONLY.test(value)) reason = `template não preenchido ("${value}")`;
+      else if (value.length < MIN_LEN) reason = `curta demais (<${MIN_LEN} chars): "${value}"`;
+      if (reason) {
+        violations.push({ file: path.relative(ROOT, file), line: i + 1, value, reason });
+      }
+    });
+  }
+  return violations;
+}
+
+/** Resolve the files to lint: explicit args, or the default target dirs. */
+function collectFiles(args) {
+  if (args.length) return args;
+  return DEFAULT_TARGET_DIRS.flatMap((d) => walkMarkdown(path.join(ROOT, d)));
+}
+
+function main() {
+  const files = collectFiles(process.argv.slice(2));
+  const violations = lintDescriptions(files);
+  if (violations.length === 0) {
+    console.log(`OK — tool/command descriptions valid (${files.length} files scanned).`);
+    process.exit(0);
+  }
+  console.error(`FAIL — ${violations.length} description(s) violate the clarity contract:`);
+  for (const v of violations) {
+    console.error(`  ${v.file}:${v.line} — ${v.reason}`);
+  }
+  process.exit(1);
+}
+
+if (require.main === module) main();
+
+module.exports = { lintDescriptions, unquote, walkMarkdown, MIN_LEN };

package/scripts/wave-gate.js

@@ -0,0 +1,207 @@
+#!/usr/bin/env node
+
+/**
+ * wave-gate.js — deterministic wave gate for harness-based epic waves.
+ *
+ * Story onda3-s5-epic-waves-wrapper-pilot (AF-20260702 item 3.5).
+ *
+ * The HÍBRIDO verdict (2026-06-30) killed the homegrown multi-story engine.
+ * The wave path that remains viable is a THIN WRAPPER over the harness:
+ * fan-out per story into isolated workdirs/worktrees, then THIS gate decides
+ * whether the wave may advance — by measurement, not by claim:
+ *
+ *   1. TESTS GREEN: the story's test command exits 0 (default `node --test`).
+ *   2. FILES ACTUALLY WRITTEN: the story dir contains real product files
+ *      (excluding plan/, docs/, node_modules, dotfiles and markdown) — the
+ *      echo of the empty-build honesty fix: a wave never advances on a story
+ *      that produced zero code.
+ *
+ * Verdict per story and for the wave: APPROVED / NEEDS_WORK (exit 0 / 1).
+ *
+ * Usage:
+ *   node scripts/wave-gate.js --stories <dir1> <dir2> [...] \
+ *     [--test-cmd "node --test"] [--json]
+ *
+ * Adoption status: utility + pilot instrument. Whether the wave wrapper
+ * becomes product is decided EXCLUSIVELY by the pre-registered measurement
+ * (tests/evals/epic-gates/PROTOCOL.md) — see the checkpoint in
+ * docs/epics/epic-onda3-estrutural/.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+const DEFAULT_TEST_CMD = 'node --test';
+
+/** Directory/file names that never count as written product files. */
+const EXCLUDED_DIRS = new Set(['node_modules', '.git', 'plan', 'docs', '.sinapse']);
+
+/**
+ * Recursively list product files written in a story dir.
+ * Markdown and dotfiles are not product; plan/ and docs/ are artifacts of
+ * planning, not implementation (a plan is not an implementation).
+ *
+ * @param {string} dir
+ * @param {number} [depth]
+ * @returns {string[]} Relative paths of product files
+ */
+function scanWrittenFiles(dir, depth = 0) {
+  if (depth > 6) return [];
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const out = [];
+  for (const entry of entries) {
+    if (entry.name.startsWith('.')) continue;
+    if (entry.isDirectory()) {
+      if (EXCLUDED_DIRS.has(entry.name)) continue;
+      out.push(
+        ...scanWrittenFiles(path.join(dir, entry.name), depth + 1).map((f) =>
+          path.join(entry.name, f),
+        ),
+      );
+      continue;
+    }
+    if (entry.name.endsWith('.md')) continue;
+    out.push(entry.name);
+  }
+  return out;
+}
+
+/**
+ * Parse a `node --test` (TAP-ish) summary out of test output. Best effort —
+ * the EXIT CODE is the source of truth; counts are telemetry.
+ *
+ * @param {string} output
+ * @returns {{pass: ?number, fail: ?number}}
+ */
+function parseNodeTestSummary(output) {
+  const grab = (re) => {
+    const m = String(output).match(re);
+    return m ? parseInt(m[1], 10) : null;
+  };
+  return {
+    pass: grab(/^#\s*pass\s+(\d+)/im),
+    fail: grab(/^#\s*fail\s+(\d+)/im),
+  };
+}
+
+/**
+ * Evaluate one story dir: run its tests and verify real files were written.
+ *
+ * @param {string} storyDir
+ * @param {{testCmd?: string}} [options]
+ * @returns {{story: string, verdict: string, filesWritten: number, files: string[], tests: {exitCode: ?number, pass: ?number, fail: ?number, skipped?: boolean}, reasons: string[]}}
+ */
+function evaluateStory(storyDir, options = {}) {
+  const testCmd = options.testCmd || DEFAULT_TEST_CMD;
+  const reasons = [];
+
+  const files = scanWrittenFiles(storyDir);
+  if (files.length === 0) {
+    reasons.push('zero product files written (a plan is not an implementation)');
+  }
+
+  let tests = { exitCode: null, pass: null, fail: null };
+  if (files.length === 0) {
+    // Nothing to test — do not mask the real failure with a confusing test error.
+    tests = { exitCode: null, pass: null, fail: null, skipped: true };
+  } else {
+    try {
+      const output = execSync(testCmd, {
+        cwd: storyDir,
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'pipe'],
+        timeout: 120000,
+      });
+      tests = { exitCode: 0, ...parseNodeTestSummary(output) };
+    } catch (error) {
+      const output = `${error.stdout || ''}\n${error.stderr || ''}`;
+      tests = {
+        exitCode: typeof error.status === 'number' ? error.status : 1,
+        ...parseNodeTestSummary(output),
+      };
+      reasons.push(`tests failed (exit ${tests.exitCode}${tests.fail != null ? `, ${tests.fail} failing` : ''})`);
+    }
+  }
+
+  return {
+    story: storyDir,
+    verdict: reasons.length === 0 ? 'APPROVED' : 'NEEDS_WORK',
+    filesWritten: files.length,
+    files,
+    tests,
+    reasons,
+  };
+}
+
+/**
+ * Evaluate a whole wave (list of story dirs).
+ *
+ * @param {string[]} storyDirs
+ * @param {{testCmd?: string}} [options]
+ * @returns {{verdict: string, stories: Array}}
+ */
+function evaluateWave(storyDirs, options = {}) {
+  const stories = storyDirs.map((dir) => evaluateStory(dir, options));
+  return {
+    verdict: stories.every((s) => s.verdict === 'APPROVED') ? 'APPROVED' : 'NEEDS_WORK',
+    stories,
+  };
+}
+
+function main() {
+  const argv = process.argv.slice(2);
+  const json = argv.includes('--json');
+
+  const testCmdIdx = argv.indexOf('--test-cmd');
+  const testCmd = testCmdIdx !== -1 ? argv[testCmdIdx + 1] : DEFAULT_TEST_CMD;
+
+  const storiesIdx = argv.indexOf('--stories');
+  if (storiesIdx === -1) {
+    console.error('Usage: node scripts/wave-gate.js --stories <dir1> [dir2 ...] [--test-cmd "..."] [--json]');
+    process.exit(2);
+  }
+  const storyDirs = [];
+  for (let i = storiesIdx + 1; i < argv.length && !argv[i].startsWith('--'); i += 1) {
+    storyDirs.push(path.resolve(argv[i]));
+  }
+  if (storyDirs.length === 0) {
+    console.error('wave-gate: --stories requires at least one directory.');
+    process.exit(2);
+  }
+
+  const wave = evaluateWave(storyDirs, { testCmd });
+
+  if (json) {
+    console.log(JSON.stringify(wave, null, 2));
+  } else {
+    console.log(`=== wave-gate (${storyDirs.length} story(ies)) ===`);
+    for (const s of wave.stories) {
+      const testInfo = s.tests.skipped
+        ? 'tests skipped (nothing to test)'
+        : `tests exit ${s.tests.exitCode}${s.tests.pass != null ? ` (${s.tests.pass} pass/${s.tests.fail} fail)` : ''}`;
+      console.log(`  ${s.verdict.padEnd(10)} ${path.basename(s.story)} — ${s.filesWritten} file(s), ${testInfo}`);
+      for (const r of s.reasons) console.log(`             - ${r}`);
+    }
+    console.log('');
+    console.log(`wave verdict: ${wave.verdict}`);
+  }
+
+  process.exit(wave.verdict === 'APPROVED' ? 0 : 1);
+}
+
+module.exports = {
+  scanWrittenFiles,
+  parseNodeTestSummary,
+  evaluateStory,
+  evaluateWave,
+};
+
+if (require.main === module) main();

package/squads/claude-code-mastery/agents/project-integrator.md

@@ -651,6 +651,9 @@ dependencies:
 
   coderabbit_integration:
     enabled: true
+    # CodeRabbit mechanics (WSL execution, timeout, commands, report location) are
+    # single-sourced in .sinapse-ai/core-config.yaml + .claude/rules/coderabbit-integration.md.
+    # Only this agent's review focus/policy lives here — see Story rodada2-m6.
     focus: Integration patterns, configuration consistency, CLAUDE.md quality, hook coverage
 
     when_to_use:
@@ -659,16 +662,6 @@ dependencies:
       - Validating CI/CD workflow configurations
       - Checking settings.json deny/allow rules
 
-    execution_guidelines: |
-      CRITICAL: CodeRabbit CLI is installed in WSL, not Windows.
-
-      **How to Execute:**
-      1. Use 'wsl bash -c' wrapper for all commands
-      2. Navigate to project directory in WSL path format (/mnt/c/...)
-      3. Use full path to coderabbit binary (~/.local/bin/coderabbit)
-
-      **Timeout:** 15 minutes (900000ms) - CodeRabbit reviews take 7-30 min
-
 # =========================================================================
 # INTEGRATION ALGORITHM
 # =========================================================================

package/squads/claude-code-mastery/knowledge-base/context-window-optimization.md

@@ -19,7 +19,7 @@ The context window is the scarcest resource in agentic systems. Every token has
 ### Claude Code Session Anatomy
 
 ```
-TOTAL WINDOW: ~200,000 tokens (Sonnet/Opus)
+TOTAL WINDOW: ~200,000 tokens (example — current frontier windows reach 1M; see .claude/rules/token-economy.md)
   ├── System Prompt (static):   ~2,000 tokens (1%)       [CACHED]
   ├── CLAUDE.md hierarchy:      1-10,000 tokens (0.5-5%) [CACHED]
   ├── Rules files (loaded):     500-5,000 tokens (0.25-2.5%) [CACHED]
@@ -253,7 +253,7 @@ Parent system prompt (cached):
 For SINAPSE agents, recommended allocation:
 
 ```
-200K token session:
+200K-window session (example — current frontier windows reach 1M):
   Agent persona (CLAUDE.md + rules): ~5K (2.5%)
   HOT memory (current task): ~20K (10%)
   WARM memory (retrieved context): ~30K (15%)

package/squads/claude-code-mastery/knowledge-base/memory-systems-reference.md

@@ -43,7 +43,7 @@ The context window is the scarcest resource in agentic systems. A well-designed
 ### Token Budget Management
 
 ```
-TOTAL WINDOW: 200,000 tokens (example)
+TOTAL WINDOW: 200,000 tokens (example — current frontier windows reach 1M)
   |- System Prompt:      ~2,000 tokens (1%)
   |- Agent Persona:      ~1,500 tokens (0.75%)
   |- Memory Context:    ~50,000 tokens (25%)     ← MANAGED

package/squads/squad-copy/knowledge-base/ai-copy-human-loop-canon.md

@@ -195,7 +195,7 @@ Every AI-assisted copy deliverable MUST record:
 
 1. **Gate used** — which of the 4 gates (Trust / Light / Heavy / Scrap)
 2. **Prompt template(s) used** — from the library in §6
-3. **Model used** — GPT-5, Claude Opus 4.6, Gemini 2.5 Pro, etc.
+3. **Model used** — e.g. GPT-5, Claude (Opus/Fable family), Gemini 2.5 Pro
 4. **Final edit depth** — rough % AI vs human in the shipped version
 5. **Conversion outcome** (if tracked) — linked to the attribution system