sinapse-ai 7.5.2 → 7.6.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/write-path-validation.cjs

@@ -0,0 +1,132 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Hook: Write Path Validation (CJS port)
+ *
+ * RULE: Documentation files should go to the correct paths per conventions.
+ *       This hook WARNS (never blocks) when a doc path looks wrong.
+ *
+ * Protocol: always exit 0 (warn-only, never blocks).
+ *
+ * @module write-path-validation
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// ---------------------------------------------------------------------------
+// Configuration
+// ---------------------------------------------------------------------------
+
+const PATH_RULES = [
+  {
+    namePatterns: [/session/i, /handoff/i, /^2\d{3}-\d{2}-\d{2}/],
+    expectedPath: 'docs/sessions/',
+    description: 'Session logs e handoffs → docs/sessions/YYYY-MM/',
+  },
+  {
+    namePatterns: [/architecture/i, /system-design/i, /infra/i],
+    expectedPath: 'docs/architecture/',
+    description: 'Docs de arquitetura → docs/architecture/',
+    excludePatterns: [/ARCHITECTURE_RULES/i],
+  },
+  {
+    namePatterns: [/guide/i, /tutorial/i, /how-to/i],
+    expectedPath: 'docs/guides/',
+    description: 'Guias e tutoriais → docs/guides/',
+  },
+  {
+    namePatterns: [/prd\.md$/i, /epic.*\.md$/i, /story.*\.md$/i],
+    expectedPath: 'docs/projects/',
+    description: 'PRDs, Epics, Stories → docs/projects/{project}/',
+  },
+  {
+    namePatterns: [/mind.*specific/i, /mind.*validation/i],
+    expectedPath: 'outputs/minds/',
+    description: 'Docs de mind → outputs/minds/{slug}/docs/',
+  },
+];
+
+const ALWAYS_VALID = [
+  '.claude/', '.sinapse-ai/', '.sinapse-upstream/', 'squads/',
+  'node_modules/', '.git/', 'app/', 'supabase/', 'outputs/',
+];
+
+const DOC_EXTENSIONS = ['.md', '.mdx', '.txt', '.rst'];
+
+// ---------------------------------------------------------------------------
+// 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 isAlwaysValid(rel) {
+  return ALWAYS_VALID.some((v) => rel.startsWith(v));
+}
+
+function isDocFile(rel) {
+  return DOC_EXTENSIONS.some((ext) => rel.endsWith(ext));
+}
+
+function checkRules(rel) {
+  const filename = path.basename(rel);
+  for (const rule of PATH_RULES) {
+    const matchesName = rule.namePatterns.some((p) => p.test(filename));
+    if (!matchesName) continue;
+
+    if (rule.excludePatterns && rule.excludePatterns.some((p) => p.test(filename))) continue;
+
+    if (!rel.startsWith(rule.expectedPath)) {
+      return { currentPath: rel, expectedPath: rule.expectedPath, description: rule.description };
+    }
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+function main() {
+  let input;
+  try {
+    input = JSON.parse(fs.readFileSync(0, 'utf8'));
+  } catch {
+    process.exit(0);
+  }
+
+  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 (isAlwaysValid(rel)) process.exit(0);
+  if (!isDocFile(rel)) process.exit(0);
+
+  const violation = checkRules(rel);
+  if (!violation) process.exit(0);
+
+  // WARN only — never block
+  process.stderr.write(
+    `\nPATH WARNING: Document may be in the wrong location.\n` +
+    `  File:     ${violation.currentPath}\n` +
+    `  Expected: ${violation.expectedPath}\n` +
+    `  Rule:     ${violation.description}\n` +
+    `  NOTE: This is a WARNING only — the operation will proceed.\n`,
+  );
+  process.exit(0);
+}
+
+main();

package/.claude/rules/agent-handoff.md

@@ -44,6 +44,18 @@ The incoming agent receives:
 2. The **handoff artifact** from the previous agent (compact summary)
 3. **NOT** the previous agent's full persona/instructions/tool definitions
 
+### Scratchpad Protocol (v1.1)
+
+**Before starting work**, the incoming agent MUST:
+1. Check if `.sinapse/scratchpad/{story-id}/` exists
+2. If yes, read ALL files in that directory (discoveries from previous agents)
+3. Use those insights to inform decisions (avoid rediscovering known issues)
+
+**Before handing off**, the outgoing agent SHOULD:
+1. Write key discoveries to `.sinapse/scratchpad/{story-id}/{agent-id}.md`
+2. Include the scratchpad path in the handoff artifact `scratchpad_path` field
+3. Keep each file under 2KB (focused insights, not logs)
+
 ### Compaction Limits
 
 | Limit | Value |

package/.sinapse-ai/development/templates/agent-handoff-tmpl.yaml

@@ -40,6 +40,9 @@ handoff:
   # What the incoming agent should do next (max 2 sentences)
   next_action: ""         # e.g., "Run QA gate on TOK-4A. Verify handoff preserves story context."
 
+  # Cross-agent knowledge sharing (v1.1)
+  scratchpad_path: ""     # e.g., ".sinapse/scratchpad/TOK-4A/" — read before starting work
+
 # --- Compaction Limits (AC 9) ---
 # Max artifact size: 500 tokens (~375 words)
 # Max retained summaries: 3 (oldest discarded on 4th switch)

package/.sinapse-ai/install-manifest.yaml

@@ -7,8 +7,8 @@
 # - SHA256 hashes for change detection
 # - File types for categorization
 #
-version: 7.5.2
-generated_at: "2026-03-31T19:58:02.055Z"
+version: 7.6.0
+generated_at: "2026-04-01T02:05:35.822Z"
 generator: scripts/generate-install-manifest.js
 file_count: 1104
 files:
@@ -2565,9 +2565,9 @@ files:
     type: task
     size: 2254
   - path: development/templates/agent-handoff-tmpl.yaml
-    hash: sha256:abb8d46dce28abb9cd140931db4283202d7c2b89220c43283c6518813a0911ad
+    hash: sha256:9b28cc790c81960acf9c8393555d6d5474afa724e152784f8983bbf70be89b3a
     type: template
-    size: 1988
+    size: 2124
   - path: development/templates/chrome-brain/knowledge-base/chrome-brain.md
     hash: sha256:ed47917601edfe48153290ea57b3d367220ceba6b976e7222c2451af6b4a6566
     type: template

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sinapse-ai",
-  "version": "7.5.2",
+  "version": "7.6.0",
   "description": "SINAPSE AI: Framework de orquestracao de IA — 18 squads, 175 agentes especializados",
   "bin": {
     "sinapse": "bin/sinapse.js",