sinapse-ai 7.5.2 → 7.7.0

package/.claude/hooks/enforce-architecture-first.cjs

@@ -0,0 +1,144 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Hook: Enforce Architecture-First Development (CJS port)
+ *
+ * RULE: Code in protected paths can only be created/edited if prior
+ *       architecture documentation exists.
+ *
+ * Protocol (Claude Code PreToolUse):
+ *   exit 0  → allow
+ *   exit 2  → block (message shown to model via stderr)
+ *
+ * Fail-open: if parsing fails or project root is unresolvable, allow.
+ *
+ * @module enforce-architecture-first
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// ---------------------------------------------------------------------------
+// Configuration: paths that REQUIRE prior documentation
+// ---------------------------------------------------------------------------
+
+const PROTECTED_PATHS = [
+  {
+    pattern: 'supabase/functions/',
+    docPatterns: [
+      'docs/architecture/{name}.md',
+      'docs/architecture/{name}-architecture.md',
+      'docs/approved-plans/{name}.md',
+    ],
+    extractName(p) {
+      const idx = p.indexOf('supabase/functions/');
+      if (idx === -1) return null;
+      return p.slice(idx + 'supabase/functions/'.length).split('/')[0] || null;
+    },
+  },
+  {
+    pattern: 'supabase/migrations/',
+    docPatterns: [
+      'docs/approved-plans/migration-{name}.md',
+      'docs/architecture/database-changes.md',
+    ],
+    extractName(p) {
+      const idx = p.indexOf('supabase/migrations/');
+      if (idx === -1) return null;
+      return path.basename(p, path.extname(p));
+    },
+    allowIfExists: true,
+  },
+];
+
+const ALWAYS_ALLOWED = [
+  '.claude/', 'docs/', 'outputs/', 'squads/', '.sinapse-ai/',
+  '.sinapse-custom/', 'node_modules/', '.git/',
+  'package.json', 'package-lock.json', 'tsconfig.json', '.env', 'README.md',
+];
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function projectRoot() {
+  return process.env.CLAUDE_PROJECT_DIR || process.cwd();
+}
+
+function relativize(filePath, root) {
+  if (filePath.startsWith(root)) {
+    return filePath.slice(root.length).replace(/^[/\\]+/, '');
+  }
+  return filePath;
+}
+
+function isAlwaysAllowed(rel) {
+  return ALWAYS_ALLOWED.some((a) => rel.includes(a));
+}
+
+function findProtection(rel) {
+  return PROTECTED_PATHS.find((p) => rel.includes(p.pattern)) || null;
+}
+
+function docExists(rel, protection, root) {
+  const name = protection.extractName(rel);
+  if (!name) return true;
+
+  for (const dp of protection.docPatterns) {
+    const docPath = path.join(root, dp.replace('{name}', name));
+    if (fs.existsSync(docPath)) return true;
+  }
+
+  if (protection.allowIfExists) {
+    const full = path.isAbsolute(rel) ? rel : path.join(root, rel);
+    if (fs.existsSync(full)) return true;
+  }
+
+  return false;
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+function main() {
+  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') {
+    process.exit(0);
+  }
+
+  const filePath = (input.tool_input || {}).file_path || '';
+  if (!filePath) process.exit(0);
+
+  const root = projectRoot();
+  const rel = relativize(filePath, root);
+
+  if (isAlwaysAllowed(rel)) process.exit(0);
+
+  const protection = findProtection(rel);
+  if (!protection) process.exit(0);
+
+  if (docExists(rel, protection, root)) process.exit(0);
+
+  // BLOCK
+  const name = protection.extractName(rel) || 'unknown';
+  const accepted = protection.docPatterns.map((d) => `  - ${d.replace('{name}', name)}`).join('\n');
+
+  process.stderr.write(
+    `\nARCHITECTURE-FIRST BLOCK: Documentation required before code.\n` +
+    `File: ${rel}\n` +
+    `Create one of:\n${accepted}\n` +
+    `Then retry the operation.\n`,
+  );
+  process.exit(2);
+}
+
+main();

package/.claude/hooks/enforce-delegation.cjs

@@ -0,0 +1,142 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Hook: Enforce Mandatory Delegation — Constitution Article VIII
+ *
+ * RULE: Orchestrator agents (*-orqx) must NEVER execute domain work directly.
+ *       They can only read, search, and delegate via Agent/SendMessage.
+ *
+ * Protocol (Claude Code PreToolUse):
+ *   exit 0  → allow
+ *   exit 2  → block (message shown to model via stderr)
+ *
+ * Fail-open: if session state is unreadable or agent is unknown, allow.
+ *
+ * Exception: sinapse-orqx is allowed Write/Edit in .sinapse-ai/ paths
+ *            (framework governance — operates above the story layer).
+ *
+ * @module enforce-delegation
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// ---------------------------------------------------------------------------
+// Configuration
+// ---------------------------------------------------------------------------
+
+/** Agent IDs that are orchestrators (must delegate, never execute). */
+const ORCHESTRATOR_PATTERN = /-orqx$/;
+
+/** Tools that orchestrators are NOT allowed to use. */
+const BLOCKED_TOOLS = ['Write', 'Edit', 'Bash', 'NotebookEdit'];
+
+/** Paths where sinapse-orqx IS allowed to Write/Edit (framework governance). */
+const FRAMEWORK_GOVERNANCE_PATHS = [
+  '.sinapse-ai/', '.claude/', '.sinapse/', 'bin/',
+  'package.json', 'core-config.yaml',
+];
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+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;
+}
+
+/**
+ * Read the active agent from session state.
+ * Returns the agent ID string or null if unknown.
+ */
+function getActiveAgent(root) {
+  const sessionStatePath = path.join(root, '.sinapse', 'session-state.json');
+  try {
+    const state = JSON.parse(fs.readFileSync(sessionStatePath, 'utf8'));
+    return state.lastAgent || null;
+  } catch {
+    return null; // fail-open
+  }
+}
+
+function isOrchestrator(agentId) {
+  return ORCHESTRATOR_PATTERN.test(agentId);
+}
+
+function isFrameworkGovernancePath(rel) {
+  return FRAMEWORK_GOVERNANCE_PATHS.some((fp) => rel.startsWith(fp) || rel === fp);
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+function main() {
+  let input;
+  try {
+    input = JSON.parse(fs.readFileSync(0, 'utf8'));
+  } catch {
+    process.exit(0); // fail-open
+  }
+
+  const toolName = input.tool_name || '';
+
+  // Only intercept domain-execution tools
+  if (!BLOCKED_TOOLS.includes(toolName)) {
+    process.exit(0);
+  }
+
+  const root = projectRoot();
+  const agentId = getActiveAgent(root);
+
+  // If no agent tracked or not an orchestrator, allow
+  if (!agentId || !isOrchestrator(agentId)) {
+    process.exit(0);
+  }
+
+  // Special case: sinapse-orqx allowed for framework governance
+  if (agentId === 'sinapse-orqx') {
+    if (toolName === 'Write' || toolName === 'Edit') {
+      const filePath = (input.tool_input || {}).file_path || '';
+      if (filePath) {
+        const rel = relativize(filePath, root);
+        if (isFrameworkGovernancePath(rel)) {
+          process.exit(0); // Framework governance exception
+        }
+      }
+    }
+    // sinapse-orqx blocked for non-governance Write/Edit and all Bash
+    // (it should delegate to @developer or @devops)
+  }
+
+  // BLOCK
+  const delegationMap = {
+    Write: '@developer (Dex)',
+    Edit: '@developer (Dex)',
+    Bash: '@developer (Dex) or @devops (Gage)',
+    NotebookEdit: '@developer (Dex)',
+  };
+
+  const delegate = delegationMap[toolName] || '@developer';
+
+  process.stderr.write(
+    `\nMANDATORY DELEGATION BLOCK (Constitution Article VIII)\n` +
+    `Agent: ${agentId} (orchestrator)\n` +
+    `Tool: ${toolName}\n` +
+    `Orchestrators NEVER execute domain work directly.\n` +
+    `Delegate to ${delegate} for this operation.\n`,
+  );
+  process.exit(2);
+}
+
+main();

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

@@ -0,0 +1,194 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Hook: Enforce Story Gate — Constitution Article III (Documentation-First)
+ *
+ * RULE: Code files in implementation paths cannot be created/edited unless
+ *       a story exists in docs/stories/ with status >= Ready.
+ *
+ * Protocol (Claude Code PreToolUse):
+ *   exit 0  → allow
+ *   exit 2  → block (message shown to model via stderr)
+ *
+ * Fail-open: if session state is unreadable or story status is indeterminate,
+ *            the hook allows the operation (never blocks productive work).
+ *
+ * @module enforce-story-gate
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// ---------------------------------------------------------------------------
+// Configuration
+// ---------------------------------------------------------------------------
+
+/** Paths that require an active story before code changes. */
+const CODE_PATHS = [
+  'packages/', 'src/', 'app/', 'lib/', 'bin/',
+  'components/', 'pages/', 'api/', 'services/',
+];
+
+/** Paths always exempt from story requirement. */
+const EXEMPT_PATHS = [
+  '.claude/', '.sinapse-ai/', '.sinapse/', '.sinapse-custom/',
+  'docs/', 'tests/', '__tests__/', 'test/',
+  'node_modules/', '.git/', 'squads/', 'outputs/',
+];
+
+/** Config files always exempt. */
+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',
+];
+
+/** Story statuses that allow implementation. */
+const VALID_STATUSES = ['ready', 'inprogress', 'in progress', 'in_progress', 'inreview', 'in review', 'in_review', 'done'];
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+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) {
+  const basename = path.basename(rel);
+  if (EXEMPT_FILES.includes(basename)) return true;
+  return EXEMPT_PATHS.some((ep) => rel.startsWith(ep));
+}
+
+function isCodePath(rel) {
+  return CODE_PATHS.some((cp) => rel.startsWith(cp));
+}
+
+/**
+ * Check if there's an active story with valid status.
+ * Reads .sinapse/session-state.json for story context,
+ * then scans docs/stories/ for any story with status >= Ready.
+ */
+function hasActiveStory(root) {
+  // Strategy 1: Check session state for active story
+  const sessionStatePath = path.join(root, '.sinapse', 'session-state.json');
+  try {
+    const state = JSON.parse(fs.readFileSync(sessionStatePath, 'utf8'));
+    if (state.activeStory && state.activeStory.status) {
+      const status = state.activeStory.status.toLowerCase().replace(/[\s_-]+/g, '');
+      if (VALID_STATUSES.some((vs) => vs.replace(/[\s_-]+/g, '') === status)) {
+        return true;
+      }
+    }
+  } catch {
+    // No session state or invalid — continue to Strategy 2
+  }
+
+  // Strategy 2: Scan docs/stories/ for any story file
+  const storiesDir = path.join(root, 'docs', 'stories');
+  try {
+    if (!fs.existsSync(storiesDir)) return false;
+
+    // Recursively find .md files
+    const files = walkSync(storiesDir, '.md');
+    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);
+        if (statusMatch) {
+          const status = statusMatch[1].toLowerCase().replace(/[\s_-]+/g, '');
+          if (VALID_STATUSES.some((vs) => vs.replace(/[\s_-]+/g, '') === status)) {
+            return true;
+          }
+        }
+      } catch {
+        // Skip unreadable files
+      }
+    }
+  } catch {
+    // Can't scan — fail-open
+    return true;
+  }
+
+  return false;
+}
+
+/** Simple recursive file walker. */
+function walkSync(dir, ext) {
+  const results = [];
+  try {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        results.push(...walkSync(full, ext));
+      } else if (entry.name.endsWith(ext)) {
+        results.push(full);
+      }
+    }
+  } catch {
+    // Skip inaccessible dirs
+  }
+  return results;
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+function main() {
+  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') {
+    process.exit(0);
+  }
+
+  const filePath = (input.tool_input || {}).file_path || '';
+  if (!filePath) process.exit(0);
+
+  const root = projectRoot();
+  const rel = relativize(filePath, root);
+
+  // Exempt paths and files
+  if (isExempt(rel)) process.exit(0);
+
+  // Only enforce on code paths
+  if (!isCodePath(rel)) process.exit(0);
+
+  // Check for active story
+  if (hasActiveStory(root)) process.exit(0);
+
+  // BLOCK
+  process.stderr.write(
+    `\nDOCUMENTATION-FIRST BLOCK (Constitution Article III)\n` +
+    `File: ${rel}\n` +
+    `No active story found with status >= Ready in docs/stories/.\n` +
+    `Create a story first: @sprint-lead *draft\n` +
+    `Then validate it: @product-lead *validate\n` +
+    `Only then can implementation proceed.\n`,
+  );
+  process.exit(2);
+}
+
+main();

package/.claude/hooks/secret-scanning.cjs

@@ -0,0 +1,155 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Hook: Secret Scanning
+ *
+ * RULE: Detect and block potential secrets/credentials from being written to files.
+ *
+ * Protocol (Claude Code PreToolUse):
+ *   exit 0  → allow
+ *   exit 2  → block (message shown to model via stderr)
+ *
+ * Fail-open: if parsing fails, allow.
+ *
+ * @module secret-scanning
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// ---------------------------------------------------------------------------
+// Secret Patterns — ordered by severity
+// ---------------------------------------------------------------------------
+
+const SECRET_PATTERNS = [
+  // API Keys & Tokens
+  { name: 'AWS Access Key', pattern: /AKIA[0-9A-Z]{16}/ },
+  { name: 'AWS Secret Key', pattern: /(?:aws_secret_access_key|secret_key)\s*[=:]\s*['"]?[A-Za-z0-9/+=]{40}['"]?/i },
+  { name: 'GitHub Token', pattern: /gh[ps]_[A-Za-z0-9_]{36,}/ },
+  { name: 'GitHub OAuth', pattern: /gho_[A-Za-z0-9_]{36,}/ },
+  { name: 'Slack Token', pattern: /xox[bpors]-[0-9]{10,}-[A-Za-z0-9-]+/ },
+  { name: 'Stripe Key', pattern: /[sr]k_(live|test)_[A-Za-z0-9]{20,}/ },
+  { name: 'OpenAI Key', pattern: /sk-[A-Za-z0-9]{20,}/ },
+  { name: 'Anthropic Key', pattern: /sk-ant-[A-Za-z0-9-]{20,}/ },
+  { name: 'Supabase Key', pattern: /eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9\.[A-Za-z0-9_-]{50,}/ },
+  { name: 'Google API Key', pattern: /AIza[0-9A-Za-z_-]{35}/ },
+  { name: 'Vercel Token', pattern: /vercel_[A-Za-z0-9]{20,}/ },
+
+  // Private Keys
+  { name: 'RSA Private Key', pattern: /-----BEGIN RSA PRIVATE KEY-----/ },
+  { name: 'SSH Private Key', pattern: /-----BEGIN OPENSSH PRIVATE KEY-----/ },
+  { name: 'PGP Private Key', pattern: /-----BEGIN PGP PRIVATE KEY BLOCK-----/ },
+  { name: 'EC Private Key', pattern: /-----BEGIN EC PRIVATE KEY-----/ },
+
+  // Connection Strings
+  { name: 'DB Connection String', pattern: /(?:postgres|mysql|mongodb|redis):\/\/[^:]+:[^@]+@[^/\s]+/i },
+  { name: 'Supabase DB URL', pattern: /postgresql:\/\/postgres\.[A-Za-z0-9]+:[^@]+@/i },
+
+  // Generic Patterns (broader, lower confidence)
+  { name: 'Hardcoded Password', pattern: /(?:password|passwd|pwd)\s*[=:]\s*['"][^'"]{8,}['"]/i },
+  { name: 'Bearer Token', pattern: /[Bb]earer\s+[A-Za-z0-9_\-.]{20,}/ },
+  { name: 'Basic Auth', pattern: /[Bb]asic\s+[A-Za-z0-9+/=]{20,}/ },
+];
+
+/** Files that are expected to contain secret-like patterns */
+const EXEMPT_PATHS = [
+  '.env.example', '.env.template', '.env.sample',
+  'node_modules/', '.git/',
+  '.claude/hooks/',       // Hook scripts may reference patterns
+  'test/', 'tests/', '__tests__/',
+  '.sinapse-ai/core/',    // Framework core may have validators
+];
+
+/** File extensions to scan */
+const SCANNABLE_EXTENSIONS = [
+  '.ts', '.tsx', '.js', '.jsx', '.cjs', '.mjs',
+  '.json', '.yaml', '.yml', '.toml',
+  '.env', '.sh', '.bash', '.py',
+  '.md', '.txt', '.cfg', '.conf', '.ini',
+];
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+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) {
+  return EXEMPT_PATHS.some((ep) => rel.includes(ep));
+}
+
+function isScannable(rel) {
+  return SCANNABLE_EXTENSIONS.some((ext) => rel.endsWith(ext));
+}
+
+function scanForSecrets(content) {
+  const findings = [];
+  for (const { name, pattern } of SECRET_PATTERNS) {
+    if (pattern.test(content)) {
+      findings.push(name);
+    }
+  }
+  return findings;
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+function main() {
+  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') {
+    process.exit(0);
+  }
+
+  const toolInput = input.tool_input || {};
+  const filePath = toolInput.file_path || '';
+  if (!filePath) process.exit(0);
+
+  const root = projectRoot();
+  const rel = relativize(filePath, root);
+
+  if (isExempt(rel)) process.exit(0);
+  if (!isScannable(rel)) process.exit(0);
+
+  // Scan content being written
+  const content = toolInput.content || toolInput.new_string || '';
+  if (!content) process.exit(0);
+
+  const findings = scanForSecrets(content);
+  if (findings.length === 0) process.exit(0);
+
+  // BLOCK
+  process.stderr.write(
+    `\nSECRET SCANNING BLOCK: Potential secrets detected!\n` +
+    `File: ${rel}\n` +
+    `Found: ${findings.join(', ')}\n` +
+    `\n` +
+    `DO NOT commit secrets to code. Instead:\n` +
+    `  - Use environment variables (.env) for local dev\n` +
+    `  - Use .env.example with placeholder values for templates\n` +
+    `  - Use secret managers for production (Supabase Vault, etc.)\n`,
+  );
+  process.exit(2);
+}
+
+main();