sinapse-ai 9.3.0 → 9.5.0

package/scripts/validate-no-external-refs.js

@@ -0,0 +1,376 @@
+#!/usr/bin/env node
+
+/**
+ * validate-no-external-refs.js
+ *
+ * Story 10.17 — Authorial Hygiene & Competitive Reference Guard.
+ *
+ * Scans the repository for any reference to a competing framework name and
+ * fails (exit 1) if any match is found outside an explicit allow-list.
+ *
+ * The guard keeps the SINAPSE codebase in a 100% authorial voice: the only
+ * places in the entire repo where competitive names may legally appear are
+ * the MIT `LICENSE` file (legal attribution requirement), the historical
+ * process document `docs/research-synthesis-for-upgrade.md`, and a small set
+ * of pre-existing upstream-attribution files inherited from the BMAD fork
+ * lineage (flagged for future per-file review — see follow-up backlog in
+ * `.sinapse-ai/internal/aiox-feature-map.md`).
+ *
+ * === Source of truth: `git ls-files` (QA v1.1 fix) ===
+ *
+ * The original implementation parsed `.gitignore` with a custom (naive)
+ * matcher. That matcher was too aggressive: because artifact-ignore rules
+ * (e.g. `.test.cache/`, `coverage/`) happened to match prefixes that also
+ * appeared inside legitimate tracked directories, entire trees like
+ * `squads/`, `tests/`, and `scripts/` were incorrectly pruned from the scan.
+ * Out of 4493 files tracked by git, the scanner only visited ~1623 (36 %)
+ * — which means it was silently blind to the real repo state and missed
+ * pre-existing upstream references that QA later caught by hand.
+ *
+ * The fix replaces the custom walker with a single call to `git ls-files`,
+ * which is the exact set of files that will be published to GitHub / npm.
+ * This is correct for three reasons:
+ *
+ *   1. Publishability — `git ls-files` is EXACTLY what ships. Any file we
+ *      miss there cannot reach a user, so scanning it is meaningless.
+ *   2. Zero parser bugs — git does gitignore resolution natively; we don't
+ *      need to approximate it.
+ *   3. Deterministic — no filesystem walk, no binary sniffing of files that
+ *      aren't even tracked, no accidental inclusion of `node_modules/`.
+ *
+ * Behavior:
+ *   - Shells out to `git ls-files` in `rootDir` to get the tracked set.
+ *   - Skips the hardcoded allow-list paths.
+ *   - Scans only text files (binary files and a small set of known-binary
+ *     extensions are skipped).
+ *   - Applies the regex `\b(aiox|synkra|synkraai|bmad)\b` (case-insensitive)
+ *     line-by-line so the reporter can point at the exact file:line:match.
+ *   - Returns a structured result for unit tests; the CLI wraps it.
+ *
+ * Output on violation (one block per match, matches AC 4 exactly):
+ *
+ *   ❌ External reference detected
+ *   File: <path>
+ *   Line: <num>
+ *   Match: <text>
+ *
+ *   Fix: Remove the reference. This repo uses authorial SINAPSE voice only.
+ *   Only LICENSE may contain these references (legal requirement).
+ *
+ * Usage:
+ *   node scripts/validate-no-external-refs.js [--root <dir>]
+ *
+ * Exit codes:
+ *   0 = clean
+ *   1 = at least one violation
+ *   2 = usage / filesystem / git error
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+// ── Configuration ───────────────────────────────────────────────────────────
+
+/**
+ * Case-insensitive regex for any forbidden reference word. Uses `\b` to avoid
+ * matching inside longer identifiers (e.g., `sinapse-ai` must not hit even
+ * though it contains `ai`).
+ */
+const FORBIDDEN_REGEX = /\b(aiox|synkra|synkraai|bmad)\b/gi;
+
+/**
+ * Hardcoded allow-list. Every entry is a POSIX-style path relative to the
+ * repo root. These paths are skipped by the scanner.
+ *
+ *   - LICENSE: MIT attribution may legally require naming upstream authors.
+ *   - docs/research-synthesis-for-upgrade.md: historical process document.
+ *   - squads/claude-code-mastery/agents/skill-craftsman.md: PERMANENT.
+ *     The agent's documented purpose is to study and adapt external
+ *     agile-AI methodologies, so the references serve the framework
+ *     rather than inheriting from a fork. Story 10.23 audited the file
+ *     and decided to keep it allow-listed indefinitely.
+ *
+ * Each entry is an EXACT path match. Directory prefixes are NOT used — this
+ * forces future files under `squads/claude-code-mastery/` to be BLOCKED
+ * until they are explicitly added, which is what we want: a new file with a
+ * forbidden literal should fail the validator loudly.
+ */
+const HARDCODED_ALLOW_LIST = [
+  'LICENSE', // MIT legal requirement
+  'docs/research-synthesis-for-upgrade.md', // Historical process doc
+
+  // ── The validator itself + its tests ─────────────────────────────────
+  // These files MUST literally contain the forbidden strings: the script
+  // defines the regex that matches them, and the test suite builds fixtures
+  // that assert the regex catches each term. Without this exemption the
+  // validator would fail on its own source code.
+  'scripts/validate-no-external-refs.js',
+  'tests/scripts/validate-no-external-refs.test.js',
+
+  // ── PERMANENT: skill-craftsman methodology study ─────────────────────
+  // Story 10.23 audited the 6 pre-existing fork attribution files from
+  // Story 10.17. Five were rewritten in authorial voice and removed from
+  // the allow-list. This one stays: the agent's identity is built around
+  // studying external agile-AI methodologies and the references are
+  // load-bearing, not inherited noise.
+  'squads/claude-code-mastery/agents/skill-craftsman.md',
+];
+
+/**
+ * File extensions we treat as binary and never scan. A line-by-line regex
+ * scan on binary content is slow, noisy, and can produce false positives
+ * (e.g. a byte sequence that happens to spell a forbidden word).
+ */
+const BINARY_EXTENSIONS = new Set([
+  '.png', '.jpg', '.jpeg', '.gif', '.webp', '.svg', '.ico', '.bmp',
+  '.pdf', '.zip', '.tar', '.gz', '.tgz', '.7z', '.rar',
+  '.mp3', '.mp4', '.mov', '.avi', '.webm', '.ogg',
+  '.woff', '.woff2', '.ttf', '.otf', '.eot',
+  '.exe', '.dll', '.so', '.dylib',
+  '.lock', '.lockb',
+]);
+
+/**
+ * Maximum file size we scan (8 MB). Anything larger is almost certainly a
+ * binary blob or a generated artifact and is not worth the IO cost.
+ */
+const MAX_SCAN_BYTES = 8 * 1024 * 1024;
+
+// ── Allow-list matching ─────────────────────────────────────────────────────
+
+/**
+ * Exact-match allow-list check. Directory prefixes are NOT supported by
+ * design: see the comment on HARDCODED_ALLOW_LIST.
+ */
+function isAllowListed(relPath) {
+  const normalized = relPath.replace(/\\/g, '/');
+  return HARDCODED_ALLOW_LIST.indexOf(normalized) !== -1;
+}
+
+// ── File discovery ──────────────────────────────────────────────────────────
+
+/**
+ * Return the list of files tracked by git in `rootDir`, as POSIX-style
+ * relative paths. This is the exact set of files that will be published.
+ *
+ * We use `git ls-files -z` (null-delimited) so filenames with spaces or
+ * other special chars are handled correctly on Windows and Unix.
+ *
+ * @param {string} rootDir absolute path to a git repository root
+ * @returns {string[]}
+ * @throws if `git ls-files` cannot be run (no git, not a repo, etc.)
+ */
+function listTrackedFiles(rootDir) {
+  let raw;
+  try {
+    raw = execSync('git ls-files -z', {
+      cwd: rootDir,
+      encoding: 'utf8',
+      maxBuffer: 64 * 1024 * 1024, // 64 MB — plenty for any repo we care about
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+  } catch (err) {
+    const msg = err && err.message ? err.message : String(err);
+    throw new Error(
+      'git ls-files failed in ' + rootDir + ': ' + msg +
+        '\n(The validator requires a git repository as its root.)',
+    );
+  }
+  // Split on NUL; drop the trailing empty entry that `-z` always leaves.
+  return raw
+    .split('\0')
+    .filter((entry) => entry.length > 0)
+    .map((entry) => entry.replace(/\\/g, '/'));
+}
+
+// ── Scanner ─────────────────────────────────────────────────────────────────
+
+/**
+ * Detect whether a file is likely binary by checking its extension and a
+ * quick sniff of the first 4 KB for null bytes.
+ */
+function isBinaryFile(absPath) {
+  const ext = path.extname(absPath).toLowerCase();
+  if (BINARY_EXTENSIONS.has(ext)) return true;
+  try {
+    const fd = fs.openSync(absPath, 'r');
+    const buf = Buffer.alloc(4096);
+    const n = fs.readSync(fd, buf, 0, 4096, 0);
+    fs.closeSync(fd);
+    for (let i = 0; i < n; i++) {
+      if (buf[i] === 0) return true;
+    }
+  } catch {
+    return true; // unreadable → treat as binary
+  }
+  return false;
+}
+
+/**
+ * Scan a single file. Returns an array of violation objects; empty if clean.
+ */
+function scanFile(rootDir, relPath) {
+  if (isAllowListed(relPath)) return [];
+  const absPath = path.join(rootDir, relPath);
+  let stat;
+  try {
+    stat = fs.statSync(absPath);
+  } catch {
+    return [];
+  }
+  if (!stat.isFile()) return [];
+  if (stat.size > MAX_SCAN_BYTES) return [];
+  if (isBinaryFile(absPath)) return [];
+
+  let content;
+  try {
+    content = fs.readFileSync(absPath, 'utf8');
+  } catch {
+    return [];
+  }
+
+  const lines = content.split(/\r?\n/);
+  const violations = [];
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    // Reset regex state for each line; /g keeps lastIndex sticky.
+    FORBIDDEN_REGEX.lastIndex = 0;
+    let match;
+    while ((match = FORBIDDEN_REGEX.exec(line)) !== null) {
+      violations.push({
+        file: relPath,
+        line: i + 1,
+        match: match[0],
+      });
+    }
+  }
+  return violations;
+}
+
+/**
+ * Public API: scan the repository rooted at `rootDir` and return
+ *   { ok, scanned, violations }
+ *
+ * The function uses `git ls-files` to determine the scan set, so `rootDir`
+ * MUST be a git repository root (or a directory inside one). Tests should
+ * create a fixture with `git init` + `git add` to exercise this.
+ *
+ * @param {string} rootDir
+ * @returns {{ok: boolean, scanned: string[], violations: Array<{file: string, line: number, match: string}>}}
+ */
+function validateNoExternalRefs(rootDir) {
+  const files = listTrackedFiles(rootDir);
+  const violations = [];
+  for (const relPath of files) {
+    violations.push(...scanFile(rootDir, relPath));
+  }
+  return { ok: violations.length === 0, scanned: files, violations };
+}
+
+// ── Reporter ────────────────────────────────────────────────────────────────
+
+/**
+ * Format a violation block exactly as AC 4 specifies.
+ */
+function formatViolation(v) {
+  return [
+    '❌ External reference detected',
+    'File: ' + v.file,
+    'Line: ' + v.line,
+    'Match: ' + v.match,
+    '',
+    'Fix: Remove the reference. This repo uses authorial SINAPSE voice only.',
+    'Only LICENSE may contain these references (legal requirement).',
+    '',
+  ].join('\n');
+}
+
+function formatReport(result) {
+  if (result.ok) {
+    return (
+      '\n=== validate-no-external-refs ===\n' +
+      'Scanned ' + result.scanned.length + ' file(s).\n' +
+      'OK — no external references detected.\n\n'
+    );
+  }
+  const blocks = result.violations.map(formatViolation);
+  return (
+    '\n=== validate-no-external-refs ===\n' +
+    'Scanned ' + result.scanned.length + ' file(s).\n' +
+    'FAIL — ' + result.violations.length + ' external reference(s):\n\n' +
+    blocks.join('\n')
+  );
+}
+
+// ── CLI entry point ─────────────────────────────────────────────────────────
+
+function parseArgs(argv) {
+  const args = { root: process.cwd() };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--root' || a === '-r') {
+      args.root = argv[++i];
+    } else if (a === '--help' || a === '-h') {
+      args.help = true;
+    }
+  }
+  return args;
+}
+
+function printUsage() {
+  process.stdout.write(
+    [
+      'Usage: node scripts/validate-no-external-refs.js [--root <dir>]',
+      '',
+      'Scans the repo for any competitive framework reference and fails if',
+      'any match is found outside the hardcoded allow-list (LICENSE, historical',
+      'process doc, pre-existing upstream fork attribution). Uses `git ls-files`',
+      'as the source of truth so only publishable tracked files are scanned.',
+      '',
+      'Options:',
+      '  --root, -r <dir>   Root directory to scan (defaults to cwd).',
+      '  --help, -h         Show this help.',
+      '',
+    ].join('\n'),
+  );
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.help) {
+    printUsage();
+    process.exit(0);
+  }
+  try {
+    const rootAbs = path.resolve(args.root);
+    if (!fs.existsSync(rootAbs)) {
+      process.stderr.write('error: root directory not found: ' + rootAbs + '\n');
+      process.exit(2);
+    }
+    const result = validateNoExternalRefs(rootAbs);
+    process.stdout.write(formatReport(result));
+    process.exit(result.ok ? 0 : 1);
+  } catch (err) {
+    process.stderr.write('error: ' + (err && err.message ? err.message : err) + '\n');
+    process.exit(2);
+  }
+}
+
+// Exports for unit testing.
+module.exports = {
+  FORBIDDEN_REGEX,
+  HARDCODED_ALLOW_LIST,
+  isAllowListed,
+  listTrackedFiles,
+  scanFile,
+  validateNoExternalRefs,
+  formatViolation,
+  formatReport,
+};
+
+if (require.main === module) {
+  main();
+}

package/scripts/validate-squad-orqx.js

@@ -0,0 +1,302 @@
+#!/usr/bin/env node
+/**
+ * validate-squad-orqx — Story 10.28
+ *
+ * Verifies that every squad under `squads/` exposes a reachable
+ * orchestrator agent (`*-orqx.md`) with the minimum required YAML
+ * metadata block. Companion to the existing scripts/validate-agents.js
+ * which validates the 12 core framework agents under
+ * `.sinapse-ai/development/agents/`.
+ *
+ * Checks per orqx file:
+ *   1. File exists at squads/{squad}/agents/{name}-orqx.md
+ *   2. Contains a YAML code block with `agent:` mapping
+ *   3. agent.name is a non-empty string
+ *   4. agent.id is a non-empty string and matches `{squad}/{name}-orqx`
+ *   5. agent.title is a non-empty string
+ *   6. persona.role exists
+ *
+ * Squad-level checks:
+ *   - Every directory under squads/ that has agents/ MUST have at least
+ *     one *-orqx.md file inside.
+ *
+ * Exit codes:
+ *   0  all squads have reachable orqx agents with valid metadata
+ *   1  any squad missing an orqx OR any orqx fails metadata checks
+ *
+ * Usage:
+ *   node scripts/validate-squad-orqx.js
+ *   node scripts/validate-squad-orqx.js --json
+ *   node scripts/validate-squad-orqx.js --quiet
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const PROJECT_ROOT = path.resolve(__dirname, '..');
+const SQUADS_DIR = path.join(PROJECT_ROOT, 'squads');
+
+function parseArgs(argv = process.argv.slice(2)) {
+  const args = new Set(argv);
+  return {
+    quiet: args.has('--quiet') || args.has('-q'),
+    json: args.has('--json'),
+  };
+}
+
+function listSquads(squadsDir = SQUADS_DIR) {
+  if (!fs.existsSync(squadsDir)) return [];
+  return fs
+    .readdirSync(squadsDir, { withFileTypes: true })
+    .filter((d) => d.isDirectory())
+    .map((d) => d.name)
+    .sort();
+}
+
+function findOrqxFiles(squadName, squadsDir = SQUADS_DIR) {
+  const agentsDir = path.join(squadsDir, squadName, 'agents');
+  if (!fs.existsSync(agentsDir)) return [];
+  return fs
+    .readdirSync(agentsDir)
+    .filter((f) => f.endsWith('-orqx.md'))
+    .map((f) => path.join(agentsDir, f));
+}
+
+// parseOrqxFormat detects either of the two valid orqx file formats:
+//   1. YAML block (`\`\`\`yaml ... \`\`\``) with agent: + persona: keys
+//   2. Markdown headings (`# Agent: ...`, `## Identidade`, `## Role`)
+// Returns { format, agent, persona } or null if neither shape recognized.
+function parseOrqxFormat(content) {
+  // Format 0: YAML frontmatter (--- ... ---)
+  const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/);
+  if (frontmatterMatch) {
+    const block = frontmatterMatch[1];
+    const data = { format: 'frontmatter', agent: {}, persona: {} };
+    const nameMatch = block.match(/^name:\s*"?([^"\n]+?)"?\s*$/m);
+    if (nameMatch) {
+      data.agent.id = nameMatch[1].trim();
+      data.agent.name = nameMatch[1].trim();
+    }
+    const descMatch = block.match(/^description:\s*\|?\s*\n((?:\s{2}.+\n?)+)/);
+    if (descMatch) {
+      data.agent.title = descMatch[1].trim().split('\n')[0].trim();
+      data.persona.role = descMatch[1].trim().split('\n')[0].trim();
+    } else {
+      const inlineDescMatch = block.match(/^description:\s*(.+)$/m);
+      if (inlineDescMatch) {
+        data.agent.title = inlineDescMatch[1].trim();
+        data.persona.role = inlineDescMatch[1].trim();
+      }
+    }
+    if (Object.keys(data.agent).length > 0) return data;
+  }
+
+  const yamlMatch = content.match(/```yaml\n([\s\S]*?)\n```/);
+  if (yamlMatch) {
+    const block = yamlMatch[1];
+    const data = { format: 'yaml', agent: {}, persona: {} };
+    const agentMatch = block.match(/agent:\s*\n((?:\s{2}.+\n?)+)/);
+    if (agentMatch) {
+      const lines = agentMatch[1].split('\n');
+      for (const line of lines) {
+        const m = line.match(/^\s{2}(\w+):\s*"?([^"\n]+?)"?\s*$/);
+        if (m) data.agent[m[1]] = m[2];
+      }
+    }
+    const roleMatch = block.match(/persona:[\s\S]*?role:\s*"?([^"\n]+?)"?$/m);
+    if (roleMatch) data.persona.role = roleMatch[1].trim();
+    // Fall through to markdown branch if YAML extraction yielded nothing.
+    if (Object.keys(data.agent).length > 0) return data;
+  }
+
+  // Markdown-headings format (squad-design and friends)
+  if (/^#\s+Agent:\s/m.test(content) || /\*\*ID:\*\*/.test(content)) {
+    const data = { format: 'markdown', agent: {}, persona: {} };
+    const titleMatch = content.match(/^#\s+(?:Agent:\s+)?(.+?)$/m);
+    if (titleMatch) data.agent.title = titleMatch[1].trim();
+
+    const idMatch = content.match(/\*\*ID:\*\*\s*`?([^\s`]+)`?/);
+    if (idMatch) data.agent.id = idMatch[1].trim();
+
+    const nameMatch = content.match(/\*\*Nome:\*\*\s*([^\n]+)/);
+    if (nameMatch) data.agent.name = nameMatch[1].trim();
+
+    const roleHeadingMatch = content.match(/^##\s+Role\s*\n+([\s\S]+?)(?:\n##|\n$)/m);
+    if (roleHeadingMatch) data.persona.role = roleHeadingMatch[1].trim().split('\n')[0];
+
+    return data;
+  }
+
+  // Table-based identity format (squad-claude orqx files)
+  if (/\*\*Agent ID\*\*/.test(content) || /\*\*Name\*\*\s*\|/.test(content)) {
+    const data = { format: 'markdown-table', agent: {}, persona: {} };
+    const titleMatch = content.match(/^#\s+(.+?)$/m);
+    if (titleMatch) data.agent.title = titleMatch[1].trim();
+
+    const nameMatch = content.match(/\*\*Name\*\*\s*\|\s*([^|\n]+)/);
+    if (nameMatch) data.agent.name = nameMatch[1].trim();
+
+    const idMatch = content.match(/\*\*Agent ID\*\*\s*\|\s*`?@?([^|`\n]+?)`?\s*\|/);
+    if (idMatch) data.agent.id = idMatch[1].trim();
+
+    const roleHeadingMatch = content.match(/^##\s+Role\s*\n+([\s\S]+?)(?:\n##|\n$)/m);
+    if (roleHeadingMatch) data.persona.role = roleHeadingMatch[1].trim().split('\n')[0];
+
+    return data;
+  }
+
+  return null;
+}
+
+function validateOrqxFile(filePath) {
+  const findings = [];
+  const fileName = path.basename(filePath);
+  const relPath = path.relative(PROJECT_ROOT, filePath).replace(/\\/g, '/');
+  const squadName = relPath.split('/')[1];
+  const expectedId = `${squadName}/${fileName.replace('.md', '')}`;
+
+  let content;
+  try {
+    content = fs.readFileSync(filePath, 'utf8');
+  } catch (err) {
+    findings.push({ level: 'error', rule: 'read', message: `cannot read: ${err.message}` });
+    return findings;
+  }
+
+  const data = parseOrqxFormat(content);
+  if (!data) {
+    findings.push({
+      level: 'error',
+      rule: 'unrecognized-format',
+      message: 'no YAML block and no Markdown identity heading found',
+    });
+    return findings;
+  }
+
+  // At least one of name/id/title must be present so the agent is reachable.
+  const hasIdentity = Boolean(data.agent.name || data.agent.id || data.agent.title);
+  if (!hasIdentity) {
+    findings.push({
+      level: 'error',
+      rule: 'agent-identity',
+      message: 'no agent.name / agent.id / agent.title found in either format',
+    });
+    return findings;
+  }
+
+  // ID match is a soft check — Markdown format often uses bare ID like
+  // "design-orqx" without the squad prefix. Warn but don't error.
+  if (data.agent.id && data.agent.id !== expectedId) {
+    const fileBaseId = path.basename(filePath, '.md');
+    if (data.agent.id !== fileBaseId) {
+      findings.push({
+        level: 'warn',
+        rule: 'id-mismatch',
+        message: `agent.id="${data.agent.id}" does not match "${expectedId}" or "${fileBaseId}"`,
+      });
+    }
+  }
+
+  if (!data.persona || !data.persona.role) {
+    findings.push({
+      level: 'warn',
+      rule: 'persona-role',
+      message: 'persona.role / Role section is missing',
+    });
+  }
+
+  return findings;
+}
+
+function validateAllSquads(squadsDir = SQUADS_DIR) {
+  const squads = listSquads(squadsDir);
+  const results = [];
+  for (const squad of squads) {
+    const orqxFiles = findOrqxFiles(squad, squadsDir);
+    if (orqxFiles.length === 0) {
+      // Some squad directories don't have agents/ at all (legacy/utility),
+      // skip those silently. Only flag as ERROR if agents/ exists but no orqx.
+      const agentsDir = path.join(squadsDir, squad, 'agents');
+      if (fs.existsSync(agentsDir)) {
+        results.push({
+          squad,
+          orqxFiles: [],
+          findings: [
+            { level: 'error', rule: 'no-orqx', message: 'squad has agents/ but no *-orqx.md' },
+          ],
+        });
+      }
+      continue;
+    }
+    for (const filePath of orqxFiles) {
+      results.push({ squad, orqxFile: filePath, findings: validateOrqxFile(filePath) });
+    }
+  }
+  return results;
+}
+
+function summarize(results) {
+  const summary = { total: results.length, pass: 0, warn: 0, error: 0 };
+  for (const r of results) {
+    const hasError = r.findings.some((f) => f.level === 'error');
+    const hasWarn = r.findings.some((f) => f.level === 'warn');
+    if (hasError) summary.error += 1;
+    else if (hasWarn) summary.warn += 1;
+    else summary.pass += 1;
+  }
+  return summary;
+}
+
+function formatReport(results, summary) {
+  const lines = [];
+  for (const r of results) {
+    const tag = r.findings.some((f) => f.level === 'error')
+      ? 'ERROR'
+      : r.findings.some((f) => f.level === 'warn')
+        ? 'WARN '
+        : 'PASS ';
+    const label = r.orqxFile ? path.relative(PROJECT_ROOT, r.orqxFile).replace(/\\/g, '/') : `${r.squad} (no orqx)`;
+    lines.push(`${tag} ${label}`);
+    for (const f of r.findings) {
+      lines.push(`  [${f.level}] ${f.rule}: ${f.message}`);
+    }
+  }
+  lines.push('');
+  lines.push(
+    `Summary: ${summary.total} orqx file(s) — ${summary.pass} pass, ${summary.warn} warn, ${summary.error} error`,
+  );
+  return lines.join('\n');
+}
+
+function main() {
+  const args = parseArgs();
+  const results = validateAllSquads();
+  const summary = summarize(results);
+
+  if (args.json) {
+    console.log(JSON.stringify({ results, summary }, null, 2));
+  } else if (!args.quiet) {
+    console.log('=== validate-squad-orqx ===');
+    console.log(formatReport(results, summary));
+  }
+
+  return summary.error > 0 ? 1 : 0;
+}
+
+if (require.main === module) {
+  process.exitCode = main();
+}
+
+module.exports = {
+  parseArgs,
+  listSquads,
+  findOrqxFiles,
+  parseOrqxFormat,
+  validateOrqxFile,
+  validateAllSquads,
+  summarize,
+  formatReport,
+  main,
+};