sinapse-ai 1.16.0 → 1.19.0

package/.claude/hooks/doc-first-gate.cjs

@@ -0,0 +1,156 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Hook: Doc-First Gate — Constitution Article III (Documentation-First), hard floor
+ *
+ * Strengthens `enforce-story-gate.cjs`. The story-gate blocks code writes when no
+ * Ready story exists — but a single stray Ready story unlocks everything, and it
+ * never requires a PRD or an epic. This gate closes that hole for the case that
+ * matters most: a BRAND-NEW project being coded with zero planning ("criar um
+ * site" → straight to code).
+ *
+ * Rule (deterministic, reuses doc-first-resolver):
+ *   Block a code-path Write/Edit when ALL of:
+ *     - it is NOT the SINAPSE framework's own repo (framework dev is above the
+ *       story layer — Art. III exception), AND
+ *     - the project is GREENFIELD (no package.json, no app code yet), AND
+ *     - the doc-first gate is NOT satisfied (missing PRD / epic / Ready story).
+ *   Existing projects are deferred to enforce-story-gate (no over-blocking).
+ *
+ * Escape hatch: set SINAPSE_SKIP_DOCFIRST=1 for a legitimate exception. The gate
+ * is never a prison — it makes you conscious, not stuck.
+ *
+ * Protocol (Claude Code PreToolUse): exit 0 = allow, exit 2 = block.
+ * Fail-OPEN: any parse/require/uncertainty error → allow (never blocks on a bug).
+ *
+ * @module doc-first-gate
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/** Paths that require doc-first before code changes (mirror enforce-story-gate). */
+const CODE_PATHS = [
+  'packages/', 'src/', 'app/', 'lib/', 'bin/',
+  'components/', 'pages/', 'api/', 'services/',
+];
+
+/** Paths always exempt. */
+const EXEMPT_PATHS = [
+  '.claude/', '.sinapse-ai/', '.sinapse/', '.sinapse-custom/',
+  'docs/', 'tests/', '__tests__/', 'test/',
+  'node_modules/', '.git/', 'squads/', 'outputs/',
+];
+
+/** Config files always exempt (scaffolding a project is allowed pre-docs). */
+const EXEMPT_FILES = [
+  'package.json', 'package-lock.json', 'tsconfig.json',
+  '.env', '.env.local', '.env.example',
+  '.gitignore', '.eslintrc', '.prettierrc',
+  'README.md', 'CHANGELOG.md',
+  'jest.config.js', 'jest.config.ts',
+  'vite.config.ts', 'next.config.js', 'next.config.mjs',
+  'tailwind.config.js', 'tailwind.config.ts',
+  'postcss.config.js', 'postcss.config.cjs',
+];
+
+function projectRoot() {
+  return process.env.CLAUDE_PROJECT_DIR || process.cwd();
+}
+
+function relativize(filePath, root) {
+  const normalized = filePath.replace(/\\/g, '/');
+  const normalizedRoot = root.replace(/\\/g, '/');
+  if (normalized.startsWith(normalizedRoot)) {
+    return normalized.slice(normalizedRoot.length).replace(/^\/+/, '');
+  }
+  return normalized;
+}
+
+function isExempt(rel) {
+  if (EXEMPT_FILES.includes(path.basename(rel))) return true;
+  return EXEMPT_PATHS.some((ep) => rel.startsWith(ep));
+}
+
+function isCodePath(rel) {
+  return CODE_PATHS.some((cp) => rel.startsWith(cp));
+}
+
+function main() {
+  // Escape hatch — explicit, honest, never a prison.
+  if (process.env.SINAPSE_SKIP_DOCFIRST) process.exit(0);
+
+  let input;
+  try {
+    input = JSON.parse(fs.readFileSync(0, 'utf8'));
+  } catch {
+    process.exit(0); // fail-open
+  }
+
+  const toolName = input.tool_name || '';
+  if (toolName !== 'Write' && toolName !== 'Edit' && toolName !== 'MultiEdit') {
+    process.exit(0);
+  }
+
+  const filePath = (input.tool_input || {}).file_path || '';
+  if (!filePath) process.exit(0);
+
+  const root = projectRoot();
+  const rel = relativize(filePath, root);
+
+  if (isExempt(rel)) process.exit(0);
+  if (!isCodePath(rel)) process.exit(0);
+
+  // Load the shared resolver (single source of truth with `sinapse route`).
+  // Try the project's installed copy first; fall back to the copy next to this
+  // hook (same path in a real install — `.claude/hooks` and `.sinapse-ai` are
+  // siblings — but lets the gate work when the project root is being created).
+  let resolveDocFirstState;
+  const resolverCandidates = [
+    path.join(root, '.sinapse-ai', 'core', 'orchestration', 'doc-first-resolver.js'),
+    path.join(__dirname, '..', '..', '.sinapse-ai', 'core', 'orchestration', 'doc-first-resolver.js'),
+  ];
+  for (const candidate of resolverCandidates) {
+    try {
+      ({ resolveDocFirstState } = require(candidate));
+      break;
+    } catch {
+      // try next candidate
+    }
+  }
+  if (typeof resolveDocFirstState !== 'function') {
+    process.exit(0); // resolver not installed / unreadable → fail-open
+  }
+
+  let state;
+  try {
+    state = resolveDocFirstState({ projectRoot: root });
+  } catch {
+    process.exit(0); // fail-open
+  }
+
+  // Framework's own repo: development is above the story layer (Art. III exception).
+  if (state.maturity && state.maturity.isFrameworkRepo) process.exit(0);
+
+  // Gate already satisfied → allow.
+  if (state.gate && state.gate.satisfied) process.exit(0);
+
+  // Existing project (has code) → defer to enforce-story-gate; don't over-block.
+  if (!state.maturity || !state.maturity.isGreenfield) process.exit(0);
+
+  // Greenfield + unsatisfied gate → BLOCK.
+  const missing = (state.gate && state.gate.missing) || ['PRD', 'epic', 'story'];
+  process.stderr.write(
+    '\nDOCUMENTATION-FIRST BLOCK (Constitution Article III) — new project\n' +
+      `File: ${rel}\n` +
+      `Missing before any code: ${missing.join(', ')}.\n` +
+      'A brand-new project must have its planning documents first:\n' +
+      `  • run the ${state.workflow || 'greenfield'} flow → project brief → PRD → epic → stories\n` +
+      '  • see exactly what is missing: sinapse route "<what you are building>"\n' +
+      'Legitimate exception (rare): set SINAPSE_SKIP_DOCFIRST=1.\n',
+  );
+  process.exit(2);
+}
+
+main();

package/.claude/hooks/enforce-story-gate.cjs

@@ -109,8 +109,12 @@ function hasActiveStory(root) {
     for (const file of files) {
       try {
         const content = fs.readFileSync(file, 'utf8');
-        // Look for status field in YAML frontmatter or markdown
-        const statusMatch = content.match(/status:\s*["']?(\w[\w\s]*\w?)["']?/i);
+        // Look for status field in YAML frontmatter or markdown.
+        // Bounded capture (non-greedy + line-anchored): a greedy `[\w\s]*` used
+        // to cross the newline and swallow the next frontmatter key (e.g.
+        // `status: Ready\ntype: fix` → "readytypefix"), wrongly rejecting valid
+        // unquoted stories. Aligned with doc-first-resolver's matcher.
+        const statusMatch = content.match(/status:\s*["']?([A-Za-z][A-Za-z ]*?)["']?\s*(?:\r?\n|$)/i);
         if (statusMatch) {
           const status = statusMatch[1].toLowerCase().replace(/[\s_-]+/g, '');
           if (VALID_STATUSES.some((vs) => vs.replace(/[\s_-]+/g, '') === status)) {

package/.claude/rules/documentation-first.md

@@ -44,6 +44,12 @@ No implementation proceeds without ALL of these:
 
 **Attempting to write code without a valid story → BLOCKED.**
 
+## Enforcement model — floor-reactive by design (honest)
+
+Doc-first is enforced by a **deterministic reactive floor**, not by proactive prose: on a build request, `sinapse route` classifies the project type and **blocks** when the required artifacts are missing (story `Ready`; epic/PRD/architecture for large projects). This floor holds even if the agent forgets the rule, and it is covered by passing tests.
+
+Audit AF-20260629 **refuted** the earlier "prose without enforcement" hypothesis — the floor genuinely classifies and blocks. What is *not* wired into the prompt is the proactive **layer-2 conduction** (auto-walking the user through PRD → epic → story turn by turn). That layer is intentional **roadmap**, not a missing guardrail: no new always-on hook is added here by design (a reactive floor is lower-risk than a proactive prompt injector).
+
 ## Project Type Gate (NON-NEGOTIABLE)
 
 > **Why this exists:** A bare `epic + story` pipeline is necessary but not sufficient for **large projects**. A site, landing page, SaaS platform, mobile app, or backend service needs *upstream* artifacts (project brief, PRD, architecture, design spec) **before** stories can be written meaningfully. Without this gate, the framework writes stories from a vague verbal description and produces generic / off-brand output.

package/.claude/rules/hook-governance.md

@@ -25,6 +25,7 @@ paths:
 | `enforce-architecture-first.cjs` | Art. III — Docs before protected code | BLOCK (exit 2) |
 | `write-path-validation.cjs` | Convention — Warn wrong doc paths | WARN (exit 0) |
 | `enforce-story-gate.cjs` | Art. III — Story required for code | BLOCK (exit 2) |
+| `doc-first-gate.cjs` | Art. III — New projects need PRD + epic + story before code (greenfield only; framework repo & existing projects exempt; `SINAPSE_SKIP_DOCFIRST=1` override) | BLOCK (exit 2) |
 | `enforce-nsn-guard.cjs` | NSN Mode — Warn on "open dashboard / follow steps manually" anti-patterns in .md/.mdx/.txt | WARN (exit 0) |
 | `slug-validation.py` | Convention — Validate naming | WARN (exit 0) |
 | `mind-clone-governance.py` | Cloning — DNA required | BLOCK (exit 2) |

package/.sinapse-ai/constitution.md

@@ -115,7 +115,7 @@ Qualidade não é negociável. Todo código passa por múltiplos gates antes de
 - MUST: Story status é "Done" ou "Ready for Review"
 - SHOULD: Cobertura de testes não diminui
 
-**Gate:** `pre-push.md` - BLOCK se qualquer check falhar
+**Gate:** `.sinapse-ai/git-hooks/pre-push` - BLOCK se qualquer check falhar (executa `npm run validate:all`, fail-closed)
 
 ---
 
@@ -155,7 +155,7 @@ Métricas do ecossistema (contagem de squads, agentes, tasks, orqx) DEVEM ser es
 - **18 comandos orqx** (17 squad orqx + 1 master sinapse-orqx)
 - **1200 tasks** (em `squads/*/tasks/`)
 
-*Last synced: 2026-06-18T04:58:21.153Z*
+*Last synced: 2026-06-25T17:24:32.697Z*
 <!-- END AUTO-GENERATED COUNTS -->
 
 
@@ -389,5 +389,5 @@ Resultado: nada foi fundido. Dual register preservado. Article XI formalizado pr
 
 ---
 
-*SINAPSE Constitution v1.0.0*
+*SINAPSE Constitution v2.2.0*
 *CLI First | Agent-Driven | Quality First*

package/.sinapse-ai/core/atlas/atlas-data.js

@@ -0,0 +1,278 @@
+/**
+ * Atlas Data — the single source of truth for the Framework Operating Atlas.
+ *
+ * Scans the repository ONCE and returns a structured object describing how the
+ * SINAPSE framework is composed: workflows, agents, squads, orchestrators,
+ * constitutional articles, and non-negotiable rules. Both renderings — the
+ * LLM-readable markdown atlas and the visual HTML dashboard — consume this same
+ * object, so they can never drift from each other or from the repo.
+ *
+ * Pure of side effects except filesystem reads. Defensive per-file (a malformed
+ * file is skipped, never throws). Counts are derived from disk, so the atlas is
+ * always accurate (Constitution Article VII — Ecosystem Metrics Accuracy).
+ *
+ * @module core/atlas/atlas-data
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+let yaml;
+try {
+  yaml = require('js-yaml');
+} catch {
+  yaml = null;
+}
+
+const { FRAMEWORK_FLOWS } = require('./flows');
+
+// ───────────────────────────────────────────────────────────────────────────
+// Low-level fs helpers (defensive)
+// ───────────────────────────────────────────────────────────────────────────
+
+function readText(file) {
+  try {
+    return fs.readFileSync(file, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+function listDir(dir, kind /* 'file' | 'dir' | undefined */) {
+  try {
+    return fs
+      .readdirSync(dir, { withFileTypes: true })
+      .filter((e) => (kind === 'file' ? e.isFile() : kind === 'dir' ? e.isDirectory() : true))
+      .map((e) => e.name);
+  } catch {
+    return [];
+  }
+}
+
+function firstMatch(content, re) {
+  const m = content.match(re);
+  return m ? m[1].trim() : null;
+}
+
+function truncate(s, n = 160) {
+  if (!s) return '';
+  const flat = String(s).replace(/\s+/g, ' ').trim();
+  return flat.length > n ? `${flat.slice(0, n - 1)}…` : flat;
+}
+
+// ───────────────────────────────────────────────────────────────────────────
+// Workflows
+// ───────────────────────────────────────────────────────────────────────────
+
+function parseWorkflow(file, source) {
+  const content = readText(file);
+  const base = path.basename(file).replace(/\.ya?ml$/i, '');
+  const entry = { id: base, name: base, description: '', type: '', source, file: relFromRoot(file) };
+  if (!content) return entry;
+
+  if (yaml) {
+    try {
+      const doc = yaml.load(content) || {};
+      const wf = doc.workflow || doc;
+      if (wf && typeof wf === 'object') {
+        entry.id = String(wf.id || base);
+        entry.name = String(wf.name || wf.id || base);
+        entry.description = truncate(wf.description || '');
+        entry.type = String(wf.type || '');
+      }
+      return entry;
+    } catch {
+      // fall through to regex
+    }
+  }
+  entry.id = firstMatch(content, /^\s*id:\s*["']?([^"'\n]+)/m) || base;
+  entry.name = firstMatch(content, /^\s*name:\s*["']?([^"'\n]+)/m) || entry.id;
+  entry.description = truncate(firstMatch(content, /^\s*description:\s*["']?([^\n]+)/m) || '');
+  return entry;
+}
+
+function collectWorkflows(root) {
+  const out = [];
+  const fwDir = path.join(root, '.sinapse-ai', 'development', 'workflows');
+  for (const f of listDir(fwDir, 'file').filter((n) => /\.ya?ml$/i.test(n))) {
+    out.push(parseWorkflow(path.join(fwDir, f), 'framework'));
+  }
+  const squadsDir = path.join(root, 'squads');
+  for (const squad of listDir(squadsDir, 'dir')) {
+    const wfDir = path.join(squadsDir, squad, 'workflows');
+    for (const f of listDir(wfDir, 'file').filter((n) => /\.ya?ml$/i.test(n))) {
+      const wf = parseWorkflow(path.join(wfDir, f), `squad:${squad}`);
+      wf.squad = squad;
+      out.push(wf);
+    }
+  }
+  return out;
+}
+
+// ───────────────────────────────────────────────────────────────────────────
+// Agents
+// ───────────────────────────────────────────────────────────────────────────
+
+function parseAgent(file, squad) {
+  const content = readText(file) || '';
+  const base = path.basename(file).replace(/\.md$/i, '');
+
+  // Agent files come in two shapes: a YAML block (agent:/persona:) and a
+  // markdown-prose card (# Agent: Name — Title, "- **ID:** ...", "- **Nome:** ...").
+  // Parse both so the atlas covers every agent.
+  const headingTitle = firstMatch(content, /^#\s*Agent:\s*[^\n—–-]+[—–-]\s*([^\n]+)/m);
+
+  const id =
+    firstMatch(content, /^\s*id:\s*["']?([A-Za-z0-9_-]+)/m) ||
+    firstMatch(content, /\*\*ID:\*\*\s*([A-Za-z0-9_-]+)/i) ||
+    base;
+  const title =
+    firstMatch(content, /^\s*title:\s*["']?([^\n"']+)/m) || headingTitle || '';
+  const role =
+    firstMatch(content, /^\s*role:\s*["']?([^\n"']+)/m) || headingTitle || '';
+  const persona =
+    firstMatch(content, /^\s*name:\s*["']?([^\n"']+)/m) ||
+    firstMatch(content, /\*\*Nome:\*\*\s*([^\n]+)/i) ||
+    '';
+  // Match the canonical counter: an orchestrator is an agent whose id/file ends
+  // in `-orqx` (the 17 squad orqx + the master). Chief/triage agents that say
+  // "Orchestrator" in their title are NOT counted (they are not -orqx files).
+  const isOrqx = /-orqx$/.test(id) || /-orqx$/.test(base);
+  return {
+    id,
+    persona: persona.trim(),
+    title: truncate(title, 80),
+    role: truncate(role, 110),
+    squad: squad || 'framework',
+    isOrqx,
+    file: relFromRoot(file),
+  };
+}
+
+function collectAgents(root) {
+  const out = [];
+  const fwDir = path.join(root, '.sinapse-ai', 'development', 'agents');
+  for (const f of listDir(fwDir, 'file').filter((n) => n.endsWith('.md') && !n.includes('.backup') && !n.startsWith('test-'))) {
+    out.push(parseAgent(path.join(fwDir, f), 'framework'));
+  }
+  const squadsDir = path.join(root, 'squads');
+  for (const squad of listDir(squadsDir, 'dir')) {
+    const aDir = path.join(squadsDir, squad, 'agents');
+    for (const f of listDir(aDir, 'file').filter((n) => n.endsWith('.md') && !n.includes('.backup') && !n.startsWith('test-'))) {
+      out.push(parseAgent(path.join(aDir, f), squad));
+    }
+  }
+  return out;
+}
+
+// ───────────────────────────────────────────────────────────────────────────
+// Squads, Articles, Rules
+// ───────────────────────────────────────────────────────────────────────────
+
+function collectSquads(root, agents, workflows) {
+  const squadsDir = path.join(root, 'squads');
+  return listDir(squadsDir, 'dir').map((squad) => {
+    const readme = readText(path.join(squadsDir, squad, 'README.md')) || '';
+    const heading = firstMatch(readme, /^#\s+(.+)$/m) || squad;
+    return {
+      id: squad,
+      name: heading.trim(),
+      agents: agents.filter((a) => a.squad === squad).length,
+      workflows: workflows.filter((w) => w.squad === squad).length,
+      orqx: agents.filter((a) => a.squad === squad && a.isOrqx).map((a) => a.id),
+    };
+  });
+}
+
+function collectArticles(root) {
+  const content = readText(path.join(root, '.sinapse-ai', 'constitution.md'));
+  if (!content) return [];
+  const out = [];
+  // Articles are headings like "### III. Documentation-First Development (NON-NEGOTIABLE)"
+  // The roman numeral followed by "." distinguishes articles from other headings
+  // (e.g. "### Amendment Process").
+  const re = /^#{2,4}\s+([IVXLC]+)\.\s+([^\n(]+?)\s*(?:\(([^)]+)\))?\s*$/gim;
+  let m;
+  while ((m = re.exec(content)) !== null) {
+    out.push({
+      number: m[1].trim(),
+      title: m[2].trim(),
+      severity: (m[3] || '').trim() || 'MUST',
+    });
+  }
+  return out;
+}
+
+function collectRules(root) {
+  const dir = path.join(root, '.claude', 'rules');
+  return listDir(dir, 'file')
+    .filter((n) => n.endsWith('.md'))
+    .map((n) => {
+      const content = readText(path.join(dir, n)) || '';
+      const heading = firstMatch(content, /^#\s+(.+)$/m) || n.replace(/\.md$/, '');
+      return { id: n.replace(/\.md$/, ''), title: truncate(heading.replace(/\s*\(.*$/, ''), 90) };
+    });
+}
+
+// ───────────────────────────────────────────────────────────────────────────
+// Root helper
+// ───────────────────────────────────────────────────────────────────────────
+
+let ROOT = process.cwd();
+function relFromRoot(file) {
+  return path.relative(ROOT, file).replace(/\\/g, '/');
+}
+
+// ───────────────────────────────────────────────────────────────────────────
+// Public API
+// ───────────────────────────────────────────────────────────────────────────
+
+/**
+ * Build the full atlas data object from the repository.
+ * @param {object} [opts]
+ * @param {string} [opts.root=process.cwd()] - Repo root.
+ * @param {string} [opts.generatedAt] - ISO timestamp to stamp (pass in; the
+ *   module never calls Date.now itself so output stays deterministic for tests).
+ * @returns {object} Structured atlas data.
+ */
+function buildAtlasData(opts = {}) {
+  ROOT = opts.root || process.cwd();
+
+  const workflows = collectWorkflows(ROOT);
+  const agents = collectAgents(ROOT);
+  const squads = collectSquads(ROOT, agents, workflows);
+  const articles = collectArticles(ROOT);
+  const rules = collectRules(ROOT);
+
+  const frameworkAgents = agents.filter((a) => a.squad === 'framework');
+  const squadAgents = agents.filter((a) => a.squad !== 'framework');
+  const orqx = agents.filter((a) => a.isOrqx);
+
+  const counts = {
+    squads: squads.length,
+    agentsTotal: agents.length,
+    frameworkAgents: frameworkAgents.length,
+    squadAgents: squadAgents.length,
+    orqx: orqx.length,
+    workflowsTotal: workflows.length,
+    frameworkWorkflows: workflows.filter((w) => w.source === 'framework').length,
+    squadWorkflows: workflows.filter((w) => w.source !== 'framework').length,
+    articles: articles.length,
+    rules: rules.length,
+  };
+
+  return {
+    generatedAt: opts.generatedAt || null,
+    counts,
+    flows: FRAMEWORK_FLOWS,
+    workflows,
+    agents,
+    squads,
+    articles,
+    rules,
+  };
+}
+
+module.exports = { buildAtlasData };