sinapse-ai 1.6.1 → 1.8.0

package/.claude/CLAUDE.md

@@ -31,6 +31,8 @@ docs/stories/          # Development stories
 packages/              # Shared packages
 squads/                # Squad expansions
 tests/                 # Tests
+governance/            # Framework evolution pipeline
+audits/                # Framework-level AuditFindings
 ```
 
 ## Framework Boundary (L1-L4)
@@ -38,7 +40,7 @@ tests/                 # Tests
 | Layer | Mutability | Key Paths |
 |-------|-----------|-----------|
 | L1 Core | NEVER | `.sinapse-ai/core/`, `bin/sinapse*.js` |
-| L2 Templates | NEVER | `.sinapse-ai/development/{tasks,templates,checklists,workflows}/` |
+| L2 Templates | NEVER | `.sinapse-ai/development/{tasks,templates,checklists,workflows,external-executors}/` |
 | L3 Config | Mutable | `.sinapse-ai/data/`, `core-config.yaml` |
 | L4 Runtime | ALWAYS | `docs/stories/`, `packages/`, `squads/`, `tests/` |
 
@@ -88,17 +90,9 @@ Use Grep (not grep), Read (not cat), Edit (not sed), Glob (not find). Prefer nat
 - Agent memory in `.sinapse-ai/development/agents/{id}/MEMORY.md`
 - **Memory as hints:** Memory entries are hints, NOT ground truth. Always verify against actual codebase before acting on remembered facts.
 
-## Token Economy & Response Format (NON-NEGOTIABLE)
+## Token Economy & Delegation (NON-NEGOTIABLE)
 
-Auto-applied to all agents: `~/.claude/rules/token-economy.md` + `~/.claude/rules/response-format.md`. Compact at 60%, model route haiku/sonnet/opus, no preamble, no trailing summary.
-
-## Delegation & Anti-Hallucination
-
-- Persona switch for sequential work, sub-agent only for parallel (20K+ tokens each)
-- Model routing: `haiku` routine, `sonnet` standard, `opus` complex
-- Sub-agents announce their model for visual verification via statusline
-- `npm view {pkg}` before adding deps. Cite file:line for claims.
-- Mark uncertain claims with [NEEDS VERIFICATION]. Compact at 60%.
+Rules: `~/.claude/rules/token-economy.md` + `response-format.md`. Compact at 60%, no preamble/trailing summary. Model routing: `haiku` routine, `sonnet` standard, `opus` complex; sub-agents announce model via statusline (sub-agent only for parallel, 20K+ each). Persona switch for sequential work. `npm view {pkg}` before deps; cite file:line; mark uncertain with [NEEDS VERIFICATION].
 
 ---
 *SINAPSE v6.0 — CLI First | Observability Second | UI Third*

package/.claude/hooks/README.md

@@ -10,7 +10,8 @@ UserPromptSubmit Hooks
 
 PreToolUse Hooks
 ├── Read          → read-protection.py
-├── Write|Edit    → enforce-architecture-first.cjs
+├── Write|Edit    → enforce-framework-boundary.cjs
+│                 → enforce-architecture-first.cjs
 │                 → write-path-validation.cjs
 │                 → enforce-story-gate.cjs
 │                 → enforce-nsn-guard.cjs
@@ -110,6 +111,17 @@ Impede criação de mind clones sem DNA extraído previamente.
 1. Execute o pipeline de extração de DNA: `/squad-creator` → `*collect-sources` → `*extract-voice-dna` → `*extract-thinking-dna`
 2. OU se é agent funcional, renomeie com sufixo apropriado
 
+### 7. enforce-framework-boundary.cjs
+**Trigger:** `Write|Edit` (cobre `Write`, `Edit` e `NotebookEdit` internamente)
+**Comportamento:** BLOQUEIA (exit 2)
+
+Camada runtime de defesa em profundidade do boundary L1-L4. Lê o bloco `boundary` de `.sinapse-ai/core-config.yaml` dinamicamente a cada Write/Edit e bloqueia edições em paths protegidos (núcleo intocável L1/L2) quando `boundary.frameworkProtection: true`.
+
+- **Exceptions vencem:** se o path casa um glob de `exceptions`, libera (exit 0) mesmo dentro de dir protegido.
+- **Toggle respeitado:** com `frameworkProtection: false` (modo contribuidor), nunca bloqueia.
+- **Fail-open total:** js-yaml ausente, config ausente/ilegível, YAML malformado, bloco `boundary` ausente, ou path ausente/escapando a raiz → exit 0.
+- **Independente** do gerador estático `generate-settings-json.js` (que assa deny/allow no settings.json no install). Os dois leem a MESMA fonte (bloco `boundary`).
+
 ## Exit Codes
 
 | Code | Significado |
@@ -157,6 +169,7 @@ Hooks são registrados em `.claude/settings.json` (framework, commitado) ou `.cl
 | `synapse-engine.cjs` | `UserPromptSubmit` | — | SYNAPSE context engine |
 | `code-intel-pretool.cjs` | `PreToolUse` | `Write\|Edit` | Code intelligence injection |
 | `precompact-session-digest.cjs` | `PreCompact` | — | Session digest capture |
+| `enforce-framework-boundary.cjs` | `PreToolUse` | `Write\|Edit` | Boundary L1-L4 (BLOCK quando `frameworkProtection=true`) |
 
 ### Exemplo de Configuração
 

package/.claude/hooks/code-intel-pretool.cjs

@@ -0,0 +1,115 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Code Intelligence Hook Entry Point — PreToolUse (Write|Edit)
+ *
+ * Thin wrapper that reads the PreToolUse JSON from stdin, resolves code
+ * intelligence for the file being written/edited, and injects an
+ * <code-intel-context> block as additionalContext so the model sees the
+ * existing entity, its references, and dependencies before editing.
+ *
+ * Design (mirrors synapse-engine.cjs + hook-governance.md):
+ * - Fail-open: any error or missing data → empty stdout, exit 0 (never blocks)
+ * - Fast: the runtime resolver targets < 500ms; 5s hard safety timeout here
+ * - Silent on no-data: empty stdout is a valid "no context"
+ *
+ * @module code-intel-pretool-hook
+ */
+
+const path = require('path');
+const {
+  resolveCodeIntel,
+  formatAsXml,
+} = require(
+  path.join(__dirname, '..', '..', '.sinapse-ai', 'core', 'code-intel', 'hook-runtime.js'),
+);
+
+/** Safety timeout (ms) — defense-in-depth; Claude Code also manages hook timeout. */
+const HOOK_TIMEOUT_MS = 5000;
+
+/**
+ * Read all data from stdin as a JSON object.
+ * @returns {Promise<object>} Parsed JSON input
+ */
+function readStdin() {
+  return new Promise((resolve, reject) => {
+    let data = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('error', (e) => reject(e));
+    process.stdin.on('data', (chunk) => { data += chunk; });
+    process.stdin.on('end', () => {
+      try { resolve(JSON.parse(data)); }
+      catch (e) { reject(e); }
+    });
+  });
+}
+
+/** Write to stdout robustly across real and mocked (Jest) streams. */
+function writeStdout(output) {
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    const finish = (err) => {
+      if (settled) return;
+      settled = true;
+      if (err) reject(err); else resolve();
+    };
+    try {
+      const flushed = process.stdout.write(output, (err) => finish(err));
+      if (flushed) setImmediate(() => finish());
+      else if (typeof process.stdout.once === 'function') process.stdout.once('drain', () => finish());
+    } catch (err) {
+      finish(err);
+    }
+  });
+}
+
+/** Main hook execution pipeline. */
+async function main() {
+  const input = await readStdin();
+
+  // PreToolUse payload: the target path lives in tool_input.file_path
+  // (Write/Edit). Bail silently if absent — nothing to enrich.
+  const toolInput = input && input.tool_input ? input.tool_input : {};
+  const filePath = toolInput.file_path || toolInput.path || '';
+  const cwd = input.cwd || process.cwd();
+  if (!filePath) return;
+
+  const intel = await resolveCodeIntel(filePath, cwd);
+  if (!intel) return;
+
+  const xml = formatAsXml(intel, filePath);
+  // Empty/insufficient intel → formatAsXml returns null → valid "no context".
+  if (!xml) return;
+
+  const output = JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      additionalContext: xml,
+    },
+  });
+  await writeStdout(output);
+}
+
+/** Entry point runner — lets Node exit naturally after stdout flush. */
+function run() {
+  const timer = setTimeout(() => {
+    // Enforce the hard limit even if stdout backpressure leaves handles open.
+    process.exit(0);
+  }, HOOK_TIMEOUT_MS);
+  timer.unref();
+  main()
+    .then(() => {
+      clearTimeout(timer);
+      process.exitCode = 0;
+    })
+    .catch(() => {
+      clearTimeout(timer);
+      // Silent exit — stderr would surface as a "hook error" in the Claude Code UI.
+      process.exitCode = 0;
+    });
+}
+
+if (require.main === module) run();
+
+module.exports = { readStdin, main, run, HOOK_TIMEOUT_MS };

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

@@ -11,7 +11,23 @@
  *   exit 0  → allow
  *   exit 2  → block (message shown to model via stderr)
  *
- * Fail-open: if session state is unreadable or agent is unknown, allow.
+ * Fail-open: if the active agent is unknown, allow (Hook Design Principle #1).
+ *
+ * Active-agent signal (first match wins):
+ *   1. process.env.SINAPSE_ACTIVE_AGENT — explicit signal set by the
+ *      orchestration layer when it activates/spawns an agent. This is the
+ *      reliable channel; the session-state file is a secondary fallback.
+ *   2. .sinapse/session-state.json → { lastAgent } — written by the session
+ *      lifecycle when available.
+ *   Neither present → unknown agent → fail-open (allow).
+ *
+ * NOTE (audit 2026-06-11, Article VIII): the AUTONOMOUS path now populates the
+ * signal — the SubagentDispatcher sets SINAPSE_ACTIVE_AGENT in the env of every
+ * agent it spawns, so this hook enforces correctly when the engine spawns an
+ * orchestrator. The INTERACTIVE path (a human typing `@some-orqx` in chat) is
+ * intentionally NOT wired here: enforcing it would block a solo operator's own
+ * edits, so it stays opt-in (set SINAPSE_ACTIVE_AGENT yourself, or add a
+ * prompt-parsing writer) rather than changing chat behavior by default.
  *
  * Exception: sinapse-orqx is allowed Write/Edit in .sinapse-ai/ paths
  *            (framework governance — operates above the story layer).
@@ -56,11 +72,23 @@ function relativize(filePath, root) {
 }
 
 /**
- * Read the active agent from session state.
- * Returns the agent ID string or null if unknown.
+ * Resolve the active agent id. Explicit env signal wins; session-state file is
+ * the fallback. Returns the agent ID string or null if unknown (fail-open).
+ * @param {string} root - Project root
+ * @returns {string|null}
  */
 function getActiveAgent(root) {
+  // 1. Explicit, reliable signal from the orchestration layer.
+  const envAgent = (process.env.SINAPSE_ACTIVE_AGENT || '').trim();
+  if (envAgent) return envAgent;
+
+  // 2. Session-state file fallback. Validate the resolved path stays within the
+  //    project (defense-in-depth against a manipulated root — P2-003).
   const sessionStatePath = path.join(root, '.sinapse', 'session-state.json');
+  const resolvedRoot = path.resolve(root);
+  if (!path.resolve(sessionStatePath).startsWith(resolvedRoot)) {
+    return null;
+  }
   try {
     const state = JSON.parse(fs.readFileSync(sessionStatePath, 'utf8'));
     return state.lastAgent || null;

package/.claude/hooks/enforce-framework-boundary.cjs

@@ -0,0 +1,324 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Hook: Enforce Framework Boundary — PreToolUse Write|Edit guard
+ *
+ * RULE: When boundary.frameworkProtection is true in core-config.yaml, Write/Edit
+ *       operations on L1/L2 framework paths ('protected' globs) are BLOCKED —
+ *       UNLESS the path also matches an 'exceptions' glob (exceptions WIN).
+ *
+ * This is the RUNTIME defense-in-depth layer for the framework boundary. The
+ * static deny-rule generator (.sinapse-ai/infrastructure/scripts/generate-settings-json.js)
+ * bakes deny/allow into .claude/settings.json at install time; this hook reads
+ * the boundary config DYNAMICALLY at every Write/Edit, so it stays correct even
+ * if settings.json was never regenerated. The two layers are independent and
+ * read the SAME single source of truth (boundary block in core-config.yaml).
+ *
+ * Protocol (Claude Code PreToolUse):
+ *   exit 0  → allow (operation proceeds; silent on allow)
+ *   exit 2  → block (message shown to model via stderr)
+ *
+ * Fail-open policy (per hook-governance.md principle #1):
+ *   - Only acts on Write / Edit / NotebookEdit; any other tool → exit 0.
+ *   - Missing/unreadable core-config.yaml → exit 0.
+ *   - Missing js-yaml dependency → exit 0.
+ *   - Missing/invalid boundary block → exit 0.
+ *   - frameworkProtection !== true → exit 0 (toggle respected).
+ *   - No file_path → exit 0.
+ *   - Any unexpected error → exit 0.
+ *
+ * Design constraints: < 5s, deterministic, no side effects (read-only).
+ *
+ * @module enforce-framework-boundary
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const CORE_CONFIG_FILE = path.join('.sinapse-ai', 'core-config.yaml');
+const WRITE_TOOLS = ['Write', 'Edit', 'NotebookEdit'];
+
+// ---------------------------------------------------------------------------
+// Project root resolution
+// ---------------------------------------------------------------------------
+
+function projectRoot() {
+  return process.env.CLAUDE_PROJECT_DIR || process.cwd();
+}
+
+// ---------------------------------------------------------------------------
+// Boundary config loader (js-yaml in try/catch; fail-open if absent)
+// ---------------------------------------------------------------------------
+
+/**
+ * Read the boundary block from core-config.yaml.
+ * Returns null on any failure (missing file, missing js-yaml, parse error,
+ * absent boundary section) so the caller can fail-open.
+ *
+ * @param {string} root project root
+ * @returns {{ frameworkProtection: boolean, protected: string[], exceptions: string[] } | null}
+ */
+function loadBoundary(root) {
+  let yaml;
+  try {
+    // js-yaml is a repo dependency; in installed user projects it resolves via
+    // the sinapse-ai node_modules. If unavailable for any reason → fail-open.
+    yaml = require('js-yaml');
+  } catch {
+    return null;
+  }
+
+  const configPath = path.join(root, CORE_CONFIG_FILE);
+
+  let content;
+  try {
+    // Cap size before reading/parsing (P3-003): a pathological core-config.yaml
+    // (e.g. 10k nested keys) shouldn't be able to stall this PreToolUse hook.
+    const stat = fs.statSync(configPath);
+    if (stat.size > 1024 * 1024) {
+      return null; // > 1 MB → treat as unreadable rather than risk a parse DoS
+    }
+    content = fs.readFileSync(configPath, 'utf8');
+  } catch {
+    return null; // missing or unreadable
+  }
+
+  let config;
+  try {
+    config = yaml.load(content);
+  } catch {
+    return null; // malformed YAML
+  }
+
+  if (!config || typeof config !== 'object' || !config.boundary) {
+    return null;
+  }
+
+  const b = config.boundary;
+  return {
+    // Strictly require === true; anything else (false, undefined, "true"
+    // string, etc.) is treated as "not protected" → fail-open at the caller.
+    frameworkProtection: b.frameworkProtection === true,
+    protected: Array.isArray(b.protected) ? b.protected : [],
+    exceptions: Array.isArray(b.exceptions) ? b.exceptions : [],
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Path normalization (absolute → relative-to-root, POSIX, traversal-safe)
+// ---------------------------------------------------------------------------
+
+/**
+ * Normalize a tool file_path into a clean project-relative POSIX path.
+ *
+ * Steps:
+ *   - If absolute, make it relative to the project root.
+ *   - Convert backslashes to forward slashes.
+ *   - Collapse a leading "./" and any leading "/".
+ *   - Reject traversal: if the resolved path escapes the root (leading "..")
+ *     we return null (caller fails-open — we don't block paths we can't
+ *     confidently place inside the project).
+ *
+ * @param {string} filePath raw file_path from tool_input
+ * @param {string} root project root
+ * @returns {string | null} clean relative POSIX path, or null if unresolvable/escaping
+ */
+function toRelativePosix(filePath, root) {
+  if (!filePath || typeof filePath !== 'string') return null;
+
+  let rel;
+  if (path.isAbsolute(filePath)) {
+    rel = path.relative(root, filePath);
+  } else {
+    rel = filePath;
+  }
+
+  // Normalize OS separators and collapse "." / ".." segments deterministically.
+  rel = path.normalize(rel).replace(/\\/g, '/');
+
+  // Strip leading "./"
+  rel = rel.replace(/^\.\//, '');
+  // Strip leading slash (defensive)
+  rel = rel.replace(/^\/+/, '');
+
+  // Traversal: a normalized relative path that still starts with ".." escapes
+  // the project root. We cannot confidently classify it → signal fail-open.
+  if (rel === '..' || rel.startsWith('../')) {
+    return null;
+  }
+
+  return rel;
+}
+
+// ---------------------------------------------------------------------------
+// Glob matcher (** and *) — own implementation, NO minimatch
+// ---------------------------------------------------------------------------
+
+/**
+ * Convert a glob (supporting ** and *) into an anchored RegExp.
+ *
+ * Semantics (matching generate-settings-json + Claude permission globs):
+ *   **  → matches any characters across any depth, INCLUDING path separators
+ *         (and zero characters).
+ *   *   → matches any characters within a single path segment (no "/").
+ *   All other regex-special characters are escaped literally.
+ *
+ * Examples:
+ *   ".sinapse-ai/core/**"        matches ".sinapse-ai/core/a/b.js"
+ *   ".sinapse-ai/development/agents/<seg>/MEMORY.md"
+ *                                matches ".sinapse-ai/development/agents/dev/MEMORY.md"
+ *                                but NOT ".sinapse-ai/development/agents/a/b/MEMORY.md"
+ *   ".sinapse-ai/constitution.md" matches itself exactly.
+ *
+ * @param {string} glob
+ * @returns {RegExp}
+ */
+function globToRegExp(glob) {
+  let re = '';
+  for (let i = 0; i < glob.length; i++) {
+    const c = glob[i];
+    if (c === '*') {
+      if (glob[i + 1] === '*') {
+        // "**" → any chars, any depth (including separators), zero or more.
+        re += '.*';
+        i++; // consume the second '*'
+        // Swallow an immediate "/" after "**" so that "a/**/b" also matches
+        // "a/b" (zero intermediate segments).
+        if (glob[i + 1] === '/') {
+          re += '(?:/)?';
+          i++;
+        }
+      } else {
+        // single "*" → any chars except path separator
+        re += '[^/]*';
+      }
+    } else {
+      // Escape regex-special characters
+      re += c.replace(/[.+?^${}()|[\]\\]/g, '\\$&');
+    }
+  }
+  return new RegExp('^' + re + '$');
+}
+
+/**
+ * Does a normalized relative path match ANY glob in the list?
+ *
+ * @param {string} relPath project-relative POSIX path
+ * @param {string[]} globs
+ * @returns {string | null} the first matching glob, or null
+ */
+function firstMatch(relPath, globs) {
+  for (const g of globs) {
+    if (typeof g !== 'string' || g.length === 0) continue;
+    try {
+      if (globToRegExp(g).test(relPath)) return g;
+    } catch {
+      // A malformed glob never blocks — skip it (fail-open per-glob).
+    }
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+function main() {
+  // Parse stdin — fail-open on any parse error
+  let input;
+  try {
+    input = JSON.parse(fs.readFileSync(0, 'utf8'));
+  } catch {
+    process.exit(0);
+  }
+
+  const toolName = (input && input.tool_name ? String(input.tool_name) : '').trim();
+  const toolInput = (input && input.tool_input) || {};
+
+  // Only enforce on write-class tools. Everything else → allow.
+  if (!WRITE_TOOLS.includes(toolName)) {
+    process.exit(0);
+  }
+
+  const root = projectRoot();
+
+  // Load boundary — fail-open if anything is off.
+  let boundary;
+  try {
+    boundary = loadBoundary(root);
+  } catch {
+    process.exit(0);
+  }
+  if (!boundary) {
+    process.exit(0);
+  }
+
+  // Toggle respected: only enforce when explicitly enabled.
+  if (boundary.frameworkProtection !== true) {
+    process.exit(0);
+  }
+
+  if (boundary.protected.length === 0) {
+    process.exit(0);
+  }
+
+  // Resolve the target file path.
+  // NotebookEdit uses notebook_path; Write/Edit use file_path.
+  const rawPath = toolInput.file_path || toolInput.notebook_path;
+
+  let relPath;
+  try {
+    relPath = toRelativePosix(rawPath, root);
+  } catch {
+    process.exit(0);
+  }
+  if (!relPath) {
+    // No path or unresolvable/escaping path → fail-open.
+    process.exit(0);
+  }
+
+  // Exceptions WIN: if the path matches any exception, allow.
+  let exceptionHit = null;
+  try {
+    exceptionHit = firstMatch(relPath, boundary.exceptions);
+  } catch {
+    process.exit(0);
+  }
+  if (exceptionHit) {
+    process.exit(0);
+  }
+
+  // Protected check.
+  let protectedHit = null;
+  try {
+    protectedHit = firstMatch(relPath, boundary.protected);
+  } catch {
+    process.exit(0);
+  }
+
+  if (!protectedHit) {
+    // Not a protected path → allow.
+    process.exit(0);
+  }
+
+  // BLOCK — exit 2 with a clear message.
+  process.stderr.write(
+    '\nFRAMEWORK-BOUNDARY BLOCK [L1/L2 protected]\n' +
+    `Tool: ${toolName}\n` +
+    `File: ${relPath}\n` +
+    `Matched protected rule: ${protectedHit}\n` +
+    '\n' +
+    'This path is a protected framework artifact (Constitution Art. II —\n' +
+    'Agent Authority / L1-L2 boundary). Direct edits are blocked while\n' +
+    'boundary.frameworkProtection is enabled.\n' +
+    '\n' +
+    'To change it:\n' +
+    '  - Edit it through a story (the proper SDC flow), OR\n' +
+    '  - If you are a framework contributor, set\n' +
+    '    boundary.frameworkProtection: false in .sinapse-ai/core-config.yaml.\n',
+  );
+  process.exit(2);
+}
+
+main();