sinapse-ai 1.21.0 → 1.22.0

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/validate-all.js

@@ -55,6 +55,11 @@ 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-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();

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

@@ -63,7 +63,7 @@ function scanWrittenFiles(dir, depth = 0) {
       if (EXCLUDED_DIRS.has(entry.name)) continue;
       out.push(
         ...scanWrittenFiles(path.join(dir, entry.name), depth + 1).map((f) =>
-          path.join(entry.name, f)
+          path.join(entry.name, f),
         ),
       );
       continue;

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