sinapse-ai 1.6.1 → 1.8.0

package/docs/framework/collaboration-autonomy-plan.md

@@ -13,9 +13,9 @@ The previous "safe collaboration" suggestions should be **partially approved**,
 
 ### Approved now
 
-- Standardize how Caio and Soier work in parallel inside the same repository
+- Standardize how two collaborators work in parallel inside the same repository
 - Create a clear contributor operating model for framework changes
-- Define which changes Soier can make autonomously without waiting for Caio
+- Define which changes a contributor can make autonomously without waiting for the maintainer
 - Reuse the existing SINAPSE infrastructure already present in the repository
 
 ### Not approved now
@@ -33,8 +33,8 @@ The core need is **not only Git safety**.
 
 The real requirement is:
 
-1. Caio and Soier must be able to work in sync without overwriting each other.
-2. Soier must be able to add framework features without depending on Caio to explain where things go or how to wire them in.
+1. Two collaborators must be able to work in sync without overwriting each other.
+2. A contributor must be able to add framework features without depending on the maintainer to explain where things go or how to wire them in.
 
 The repository already contains strong building blocks for this:
 
@@ -59,14 +59,14 @@ What is missing is a **single operating model** that tells a collaborator:
 
 ## Why Scope Reduction Is Correct
 
-If the team prioritizes generic template hardening first, it will improve portability but **not solve the immediate bottleneck**: Soier still may not know when a framework change is autonomous, coordinated, or blocked.
+If the team prioritizes generic template hardening first, it will improve portability but **not solve the immediate bottleneck**: a contributor still may not know when a framework change is autonomous, coordinated, or blocked.
 
 If the team prioritizes contributor autonomy first, the outcome is immediately useful inside the active repository and can later be extracted into a stronger reusable template.
 
 Therefore the correct order is:
 
 1. Fix the operating model inside `sinapse-ai`
-2. Prove it with Caio + Soier
+2. Prove it with both collaborators
 3. Only then generalize it into the reusable template
 
 ---
@@ -77,7 +77,7 @@ Therefore the correct order is:
 
 There are two branch models in the repository context:
 
-- Safe collaboration rule suggests human prefixes like `caio/feat/...` and `soier/fix/...`
+- Safe collaboration rule suggests human prefixes like `alice/feat/...` and `bob/fix/...`
 - Worktree infrastructure currently creates `auto-claude/{storyId}`
 
 This divergence creates ambiguity and weakens adoption.
@@ -86,7 +86,7 @@ This divergence creates ambiguity and weakens adoption.
 
 The repo has generators, tasks, workflows, and standards, but there is no short operational guide saying:
 
-- "Soier can do these classes of framework changes alone"
+- "A contributor can do these classes of framework changes alone"
 - "These paths require coordination first"
 - "After this type of change, run these sync commands"
 
@@ -102,9 +102,9 @@ Reviewer auto-assignment is documented, but `auto_assign_reviewers` is still `fa
 
 ## Orchestration Objective
 
-Create a **framework contributor mode** for Caio and Soier with these outcomes:
+Create a **framework contributor mode** for two collaborators with these outcomes:
 
-- Soier can add supported framework features end-to-end without waiting for Caio
+- A contributor can add supported framework features end-to-end without waiting for the maintainer
 - Git collisions are minimized by isolation plus coordination rules
 - Core-risk edits are routed through a tighter review path
 - Sync steps are deterministic for agent, workflow, template, and manifest changes
@@ -128,7 +128,7 @@ Create a **framework contributor mode** for Caio and Soier with these outcomes:
 
 ### Exit Criteria
 
-- Caio and Soier can classify any proposed change in under 1 minute
+- Two collaborators can classify any proposed change in under 1 minute
 - Both know whether they can proceed alone or need coordination
 - No feature work starts directly on `main`
 
@@ -142,7 +142,7 @@ Create a **framework contributor mode** for Caio and Soier with these outcomes:
 
 ### Autonomous Lane
 
-Changes Soier should be able to make without waiting for Caio, as long as the story and quality gates are respected:
+Changes a contributor should be able to make without waiting for the maintainer, as long as the story and quality gates are respected:
 
 - new or updated agent definitions
 - new or updated tasks
@@ -172,7 +172,7 @@ Changes that should stay under explicit authority:
 
 ### Exit Criteria
 
-- Soier can add a framework feature from story to PR inside the Autonomous Lane without asking where things belong
+- A contributor can add a framework feature from story to PR inside the Autonomous Lane without asking where things belong
 - Coordinated Lane is clearly documented and followed
 
 ---
@@ -186,7 +186,7 @@ Changes that should stay under explicit authority:
 ### Recommended hardening now
 
 - enforce "no work on main" as team habit and documented rule
-- make reviewer routing explicit for Caio/Soier handoff
+- make reviewer routing explicit for the maintainer/contributor handoff
 - standardize when to use worktrees versus plain feature branches
 - ensure manifest and sync steps are part of the contribution workflow
 
@@ -200,7 +200,7 @@ Changes that should stay under explicit authority:
 ### Exit Criteria
 
 - daily collaboration no longer depends on ad hoc verbal coordination
-- PR handoff between Caio and Soier is predictable
+- PR handoff between two collaborators is predictable
 - no accidental drift in agent/config sync for framework changes
 
 ---
@@ -219,9 +219,9 @@ Changes that should stay under explicit authority:
 
 ## Success Metrics
 
-- Soier can independently ship a framework feature inside the Autonomous Lane
+- A contributor can independently ship a framework feature inside the Autonomous Lane
 - Fewer edits start on `main`
-- Fewer handoffs depend on Caio explaining structure manually
+- Fewer handoffs depend on the maintainer explaining structure manually
 - Reduced accidental omissions in `sync:ide`, skills sync, and manifest updates
 - PR review becomes the coordination point instead of synchronous chat
 
@@ -233,7 +233,7 @@ Approve the initiative, but with this narrowed scope:
 
 **Do not start by polishing the generic safe-collab template.**
 
-Start by formalizing the contributor operating model inside `sinapse-ai`, because that is the shortest path to real autonomy for Soier and safe parallel optimization for both of you.
+Start by formalizing the contributor operating model inside `sinapse-ai`, because that is the shortest path to real autonomy for contributors and safe parallel optimization for the team.
 
 ---
 

package/docs/guides/parallel-workflow.md

@@ -1,4 +1,4 @@
-# Trabalhando em Paralelo — Guia para Caio e Matheus
+# Trabalhando em Paralelo — Guia para dois colaboradores
 
 ## TL;DR
 
@@ -42,12 +42,12 @@ Para evitar que os dois mexam no mesmo arquivo ao mesmo tempo:
 
 | Area | Responsavel |
 |------|-------------|
-| Installer, CLI, hooks | Caio |
-| Squads, agents, tasks | Matheus |
+| Installer, CLI, hooks | Colaborador A |
+| Squads, agents, tasks | Colaborador B |
 | Docs, stories | Quem estiver trabalhando naquela feature |
 | Tests | Quem escreveu o codigo |
 
-Se precisar mexer na area do outro: **avisem antes no WhatsApp/Discord**.
+Se precisar mexer na area do outro: **avisem antes no canal combinado do time**.
 
 ## Regra #2: Mudancas pequenas e frequentes
 
@@ -98,7 +98,7 @@ Em vez de comandos tecnicos, fale normalmente:
 | Voce diz | O agente entende |
 |----------|------------------|
 | "salva meu trabalho" | git add + commit |
-| "envia pro Soier revisar" | push + criar PR |
+| "envia pro outro revisar" | push + criar PR |
 | "atualiza meu projeto" | git fetch + pull + merge |
-| "o que o Caio mudou?" | git log + diff |
+| "o que o outro mudou?" | git log + diff |
 | "desfaz isso" | git revert (seguro) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sinapse-ai",
-  "version": "1.6.1",
+  "version": "1.8.0",
   "description": "SINAPSE AI: Framework de orquestracao de IA — 18 squads, 189 agentes especializados",
   "bin": {
     "sinapse": "bin/sinapse.js",
@@ -43,17 +43,28 @@
     "docs/framework/",
     "docs/en/",
     "docs/pt/",
-    "docs/*.md",
-    "CHROME-BRAIN-INSTALL.md",
+    "docs/README.md",
+    "docs/getting-started.md",
+    "docs/troubleshooting.md",
+    "docs/ide-integration.md",
+    "docs/agent-reference-guide.md",
+    "docs/codex-integration-process.md",
+    "docs/codex-parity-program.md",
+    "docs/TELEMETRY.md",
     "README.md",
     "LICENSE"
   ],
   "scripts": {
     "format": "prettier --write \"**/*.md\"",
+    "generate:synapse": "node scripts/generate-synapse-runtime.js",
+    "pretest": "node scripts/generate-synapse-runtime.js",
     "test": "jest",
     "test:watch": "jest --watch",
     "test:coverage": "jest --coverage",
     "test:health-check": "mocha tests/health-check/**/*.test.js --timeout 30000",
+    "eval": "node scripts/eval-runner.js",
+    "validate:evals": "node scripts/validate-evals.js",
+    "validate:schemas": "node scripts/validate-schemas.js",
     "lint": "eslint . --cache --cache-location .eslintcache",
     "typecheck": "tsc --noEmit",
     "release": "semantic-release",
@@ -74,6 +85,11 @@
     "sync:ide:claude": "node .sinapse-ai/infrastructure/scripts/ide-sync/index.js sync --ide claude-code",
     "sync:ide:codex": "node .sinapse-ai/infrastructure/scripts/sync-codex-local-first.js",
     "validate:claude-sync": "node .sinapse-ai/infrastructure/scripts/ide-sync/index.js validate --ide claude-code --strict",
+    "validate:gemini-sync": "node .sinapse-ai/infrastructure/scripts/ide-sync/index.js validate --ide gemini --strict",
+    "validate:cursor-sync": "node .sinapse-ai/infrastructure/scripts/ide-sync/index.js validate --ide cursor --strict",
+    "validate:antigravity-sync": "node .sinapse-ai/infrastructure/scripts/ide-sync/index.js validate --ide antigravity --strict",
+    "validate:copilot-sync": "node .sinapse-ai/infrastructure/scripts/ide-sync/index.js validate --ide github-copilot --strict",
+    "validate:kimi-sync": "node .sinapse-ai/infrastructure/scripts/ide-sync/index.js validate --ide kimi --strict",
     "validate:claude-integration": "node .sinapse-ai/infrastructure/scripts/validate-claude-integration.js",
     "validate:squad-schema": "node scripts/validate-squad-yaml.js",
     "validate:squad-schema:strict": "node scripts/validate-squad-yaml.js --strict",
@@ -106,7 +122,7 @@
     "validate:publish": "node bin/utils/validate-publish.js",
     "brand": "node scripts/sinapse-patch.js",
     "prepublishOnly": "node bin/utils/validate-publish.js && npm run generate:manifest && npm run validate:manifest",
-    "postinstall": "node bin/postinstall.js",
+    "setup": "node bin/postinstall.js",
     "prepare": "husky"
   },
   "dependencies": {
@@ -118,6 +134,7 @@
     "chokidar": "^3.5.3",
     "cli-progress": "^3.12.0",
     "commander": "^12.1.0",
+    "cross-spawn": "^7.0.6",
     "execa": "^5.1.1",
     "fast-glob": "^3.3.3",
     "fs-extra": "^11.3.2",
@@ -198,7 +215,7 @@
     "diff": "^8.0.3",
     "serialize-javascript": "^7.0.5",
     "picomatch": "^4.0.4",
-    "brace-expansion": "^5.0.5",
+    "brace-expansion": "^5.0.6",
     "fast-uri": "^3.1.2",
     "ip-address": "^10.1.1"
   }

package/packages/installer/src/installer/git-hooks-installer.js

@@ -0,0 +1,384 @@
+/**
+ * SINAPSE Git Hooks Installer (Stream B — Frente 4.2)
+ *
+ * Propagates the SINAPSE secret-scan guard into every project the framework
+ * creates or clones. Instead of relying on husky (which the target project may
+ * not have), it uses git's native `core.hooksPath` mechanism: a managed hooks
+ * directory under `.sinapse-ai/git-hooks/` with Node `.js` hook scripts.
+ *
+ * Cross-platform by construction:
+ *   - Hooks are `.js` files with `#!/usr/bin/env node` shebang. Git on every
+ *     platform invokes the file as an executable; the shebang routes it to node.
+ *     We NEVER emit `.sh` or `.py` (they would not run on Caio's Windows).
+ *   - Execute bit is set via `fs.chmodSync(path, 0o755)` on unix; on win32 the
+ *     filesystem has no execute bit so chmod is a tolerated no-op.
+ *   - `core.hooksPath` is set via `runSafe` (cross-spawn, argv-based, never
+ *     `shell: true`) — no shell metacharacter interpolation, injection-proof.
+ *
+ * Idempotent: running install twice does not duplicate hooks or chaining. The
+ * managed hook is overwritten with the canonical content each run, and the
+ * husky chain is detected at runtime (not baked in), so it always reflects the
+ * current state of the target project.
+ *
+ * Husky / existing-hooks safety: the generated pre-commit detects an existing
+ * `.husky/pre-commit` (or a prior `core.hooksPath` hook backed up during
+ * takeover) and CHAINS to it — it never silently discards the project's own
+ * hooks.
+ *
+ * Callers (Article XI — no orphan):
+ *   - installSinapseCore() in sinapse-ai-installer.js (the `sinapse init` flow)
+ *   - GreenfieldHandler._ensureGitHooks() in greenfield-handler.js (Phase 0)
+ *
+ * @module installer/git-hooks-installer
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+// runSafe lives in the framework core. Resolve it relative to this file so the
+// module works both inside the sinapse-ai repo and inside an installed package.
+// packages/installer/src/installer -> repo root -> .sinapse-ai/core/utils
+const { runSafe } = require('../../../../.sinapse-ai/core/utils/spawn-safe');
+
+/**
+ * Name of the managed hooks directory, relative to the project root.
+ * Kept under `.sinapse-ai/` so it travels with the framework install and is
+ * obviously framework-owned.
+ * @constant {string}
+ */
+const MANAGED_HOOKS_DIRNAME = path.join('.sinapse-ai', 'git-hooks');
+
+/**
+ * Source scanner files copied into `<hooksDir>/lib/` so the generated hook can
+ * `require` them with a stable relative path regardless of where the project
+ * lives. `staged-secret-scan.js` is self-contained (only `child_process`).
+ * @constant {Array<{from: string, to: string}>}
+ */
+const SCANNER_SOURCES = [
+  {
+    from: path.join(__dirname, '..', '..', '..', '..', 'bin', 'utils', 'staged-secret-scan.js'),
+    to: 'staged-secret-scan.js',
+  },
+  // staged-secret-scan.js requires secret-scanner-core.js via __dirname, so the
+  // core must travel with it into the lib/ bundle. Both files use only Node built-ins.
+  {
+    from: path.join(__dirname, '..', '..', '..', '..', 'bin', 'utils', 'secret-scanner-core.js'),
+    to: 'secret-scanner-core.js',
+  },
+];
+
+/**
+ * Marker comment written into managed hooks so we can recognize (and safely
+ * overwrite) our own hooks without clobbering a user-authored one.
+ * @constant {string}
+ */
+const MANAGED_MARKER = 'SINAPSE-MANAGED-GIT-HOOK';
+
+/**
+ * Detect whether the target project already has a husky pre-commit hook.
+ *
+ * @param {string} projectDir - Absolute path to the project root.
+ * @returns {{ hasHusky: boolean, huskyPreCommit: string|null }}
+ */
+function detectHusky(projectDir) {
+  const huskyPreCommit = path.join(projectDir, '.husky', 'pre-commit');
+  const hasHusky = fs.existsSync(huskyPreCommit);
+  return { hasHusky, huskyPreCommit: hasHusky ? huskyPreCommit : null };
+}
+
+/**
+ * Read the currently-configured `core.hooksPath` for a project (if any).
+ *
+ * @param {string} projectDir - Absolute path to the project root.
+ * @returns {Promise<string|null>} Configured value, or null if unset/error.
+ */
+async function getCoreHooksPath(projectDir) {
+  try {
+    const result = await runSafe('git', ['-C', projectDir, 'config', '--get', 'core.hooksPath']);
+    if (result.success) {
+      const value = (result.stdout || '').trim();
+      return value || null;
+    }
+  } catch {
+    // git unavailable / not a repo — fall through to null.
+  }
+  return null;
+}
+
+/**
+ * Set `core.hooksPath` for a project using argv-safe spawning (no shell).
+ *
+ * @param {string} projectDir - Absolute path to the project root.
+ * @param {string} hooksPathValue - Path to write into core.hooksPath (relative
+ *   to projectDir is preferred so the repo stays portable).
+ * @returns {Promise<{ success: boolean, error: (string|null) }>}
+ */
+async function setCoreHooksPath(projectDir, hooksPathValue) {
+  try {
+    const result = await runSafe('git', ['-C', projectDir, 'config', 'core.hooksPath', hooksPathValue]);
+    if (result.success) {
+      return { success: true, error: null };
+    }
+    return { success: false, error: (result.stderr || '').trim() || `git exited with code ${result.code}` };
+  } catch (error) {
+    return { success: false, error: error.message };
+  }
+}
+
+/**
+ * Write a managed hook file with the node shebang and set the execute bit.
+ *
+ * @param {string} hooksDir - Absolute path to the managed hooks directory.
+ * @param {string} hookName - Hook name (e.g. 'pre-commit').
+ * @param {string} scriptContent - Full file content (must start with shebang).
+ * @returns {string} Absolute path to the written hook.
+ */
+function writeManagedHook(hooksDir, hookName, scriptContent) {
+  fs.mkdirSync(hooksDir, { recursive: true });
+  const hookPath = path.join(hooksDir, hookName);
+  fs.writeFileSync(hookPath, scriptContent, 'utf8');
+  try {
+    // 0o755 = rwxr-xr-x. No-op effect on win32 (no execute bit), tolerated.
+    fs.chmodSync(hookPath, 0o755);
+  } catch {
+    // chmod can fail on exotic filesystems; the shebang still routes to node
+    // and on Windows the bit is irrelevant. Non-fatal.
+  }
+  return hookPath;
+}
+
+/**
+ * Copy the scanner library files into `<hooksDir>/lib/` so the hook can require
+ * them with a stable relative path. Idempotent (overwrites).
+ *
+ * @param {string} hooksDir - Absolute path to the managed hooks directory.
+ * @returns {string[]} Relative names of the copied scanner files.
+ */
+function copyScannerLib(hooksDir) {
+  const libDir = path.join(hooksDir, 'lib');
+  fs.mkdirSync(libDir, { recursive: true });
+
+  const copied = [];
+  for (const source of SCANNER_SOURCES) {
+    if (fs.existsSync(source.from)) {
+      fs.copyFileSync(source.from, path.join(libDir, source.to));
+      copied.push(source.to);
+    }
+  }
+  return copied;
+}
+
+/**
+ * Build the content of the managed `pre-commit` Node hook.
+ *
+ * The hook:
+ *   1. Runs the bundled staged-secret-scan against the staged index.
+ *   2. Blocks the commit (exit 1) on any finding, printing redacted reasons.
+ *   3. Fail-CLOSED: if the scanner cannot be loaded/run, the commit is blocked
+ *      (a broken guard must never silently allow secrets through).
+ *   4. Chains to a pre-existing `.husky/pre-commit` (or a backed-up prior hook)
+ *      so the project's own hooks still run.
+ *
+ * @param {Object} [options]
+ * @param {string|null} [options.chainHookRel] - Relative path (from project
+ *   root) of a prior hook to chain to after the scan passes. When null, the
+ *   hook auto-detects `.husky/pre-commit` at runtime.
+ * @returns {string} Hook file content.
+ */
+function buildPreCommitHook(options = {}) {
+  const chainHookRel = options.chainHookRel || null;
+  const chainLiteral = chainHookRel ? JSON.stringify(chainHookRel) : 'null';
+
+  return `#!/usr/bin/env node
+'use strict';
+/* ${MANAGED_MARKER} — Auto-generated by SINAPSE git-hooks-installer. Do not edit manually. */
+/* Re-run \`sinapse init\` (or the greenfield bootstrap) to regenerate. */
+
+const path = require('path');
+const fs = require('fs');
+const { spawnSync } = require('child_process');
+
+const projectRoot = process.cwd();
+
+// --- 1. SINAPSE staged secret scan (fail-CLOSED) ----------------------------
+let scanStagedFiles;
+let getStagedFiles;
+try {
+  // The scanner is bundled next to this hook under ./lib so the require path is
+  // stable no matter where the project lives.
+  ({ scanStagedFiles, getStagedFiles } = require(path.join(__dirname, 'lib', 'staged-secret-scan.js')));
+} catch (loadErr) {
+  process.stderr.write('SINAPSE Secret Scan: scanner could not be loaded — blocking commit (fail-closed).\\n');
+  process.stderr.write('  ' + (loadErr && loadErr.message ? loadErr.message : String(loadErr)) + '\\n');
+  process.exit(1);
+}
+
+try {
+  const files = getStagedFiles();
+  const findings = scanStagedFiles(files);
+  if (findings.length > 0) {
+    process.stderr.write('\\nSINAPSE Secret Scan: commit blocked.\\n\\n');
+    for (const f of findings) {
+      process.stderr.write('  - ' + f.filePath + ': ' + f.reason + '\\n');
+    }
+    process.stderr.write('\\nRemove the sensitive content before committing.\\n\\n');
+    process.exit(1);
+  }
+} catch (scanErr) {
+  process.stderr.write('SINAPSE Secret Scan: scan failed — blocking commit (fail-closed).\\n');
+  process.stderr.write('  ' + (scanErr && scanErr.message ? scanErr.message : String(scanErr)) + '\\n');
+  process.exit(1);
+}
+
+// --- 2. Chain to a pre-existing hook (husky or backed-up prior hook) --------
+const explicitChain = ${chainLiteral};
+const candidates = [];
+if (explicitChain) {
+  candidates.push(path.resolve(projectRoot, explicitChain));
+}
+candidates.push(path.join(projectRoot, '.husky', 'pre-commit'));
+
+const selfPath = __filename;
+for (const candidate of candidates) {
+  if (!candidate || !fs.existsSync(candidate)) continue;
+  if (path.resolve(candidate) === path.resolve(selfPath)) continue; // never recurse into self
+
+  const isJs = candidate.endsWith('.js') || candidate.endsWith('.cjs');
+  const cmd = isJs ? process.execPath : candidate;
+  const args = isJs ? [candidate] : [];
+  const res = spawnSync(cmd, args, { stdio: 'inherit', cwd: projectRoot });
+
+  if (res.error) {
+    // A shell-script hook (.husky uses sh) may not be directly executable via
+    // spawnSync on Windows. Try 'sh' as an interpreter before giving up.
+    if (!isJs) {
+      const shRes = spawnSync('sh', [candidate], { stdio: 'inherit', cwd: projectRoot });
+      if (!shRes.error) {
+        if (typeof shRes.status === 'number' && shRes.status !== 0) process.exit(shRes.status);
+        break;
+      }
+    }
+    process.stderr.write('SINAPSE pre-commit: failed to run chained hook ' + candidate + ': ' + res.error.message + '\\n');
+    process.exit(1);
+  }
+  if (typeof res.status === 'number' && res.status !== 0) {
+    process.exit(res.status);
+  }
+  break; // only chain to the first existing prior hook
+}
+
+process.exit(0);
+`;
+}
+
+/**
+ * Install the SINAPSE git guard into a project.
+ *
+ * Steps:
+ *   1. Verify the target is a git repo (best-effort; we still write the hooks
+ *      so a later `git init` picks them up via core.hooksPath).
+ *   2. If a non-SINAPSE `core.hooksPath` is already set, preserve it by chaining
+ *      (we do not blow away a project's existing managed hooks dir).
+ *   3. Create `.sinapse-ai/git-hooks/`, bundle the scanner lib, write pre-commit.
+ *   4. Point `core.hooksPath` at the managed dir.
+ *
+ * Idempotent. Multiplatform. No shell.
+ *
+ * @param {Object} options
+ * @param {string} options.projectDir - Absolute path to the project root.
+ * @returns {Promise<{
+ *   success: boolean,
+ *   hooksDir: string,
+ *   huskyDetected: boolean,
+ *   chainedTo: (string|null),
+ *   coreHooksPathSet: boolean,
+ *   skipped: boolean,
+ *   error: (string|null),
+ * }>}
+ */
+async function installGitHooks(options = {}) {
+  const projectDir = options.projectDir;
+
+  const result = {
+    success: false,
+    hooksDir: null,
+    huskyDetected: false,
+    chainedTo: null,
+    coreHooksPathSet: false,
+    skipped: false,
+    error: null,
+  };
+
+  if (!projectDir || typeof projectDir !== 'string') {
+    result.error = 'installGitHooks requires options.projectDir (absolute string path)';
+    return result;
+  }
+
+  try {
+    const hooksDir = path.join(projectDir, MANAGED_HOOKS_DIRNAME);
+    result.hooksDir = hooksDir;
+
+    // Detect husky so we can chain to it (and report it).
+    const { hasHusky } = detectHusky(projectDir);
+    result.huskyDetected = hasHusky;
+    if (hasHusky) {
+      result.chainedTo = path.join('.husky', 'pre-commit');
+    }
+
+    // Detect a pre-existing non-SINAPSE core.hooksPath. If the project already
+    // routes hooks somewhere that ISN'T ours, chain to that dir's pre-commit so
+    // we never silently disable the project's existing guard.
+    const existingHooksPath = await getCoreHooksPath(projectDir);
+    let explicitChain = null;
+    if (existingHooksPath) {
+      const resolvedExisting = path.resolve(projectDir, existingHooksPath);
+      const resolvedOurs = path.resolve(hooksDir);
+      if (resolvedExisting !== resolvedOurs) {
+        const existingPreCommit = path.join(resolvedExisting, 'pre-commit');
+        if (fs.existsSync(existingPreCommit)) {
+          // Store as a project-relative path for portability.
+          explicitChain = path.relative(projectDir, existingPreCommit);
+          result.chainedTo = explicitChain;
+        }
+      }
+    }
+
+    // Bundle the scanner lib and write the managed pre-commit hook.
+    copyScannerLib(hooksDir);
+    writeManagedHook(hooksDir, 'pre-commit', buildPreCommitHook({ chainHookRel: explicitChain }));
+
+    // Point core.hooksPath at our managed dir (project-relative for portability).
+    const relHooksDir = MANAGED_HOOKS_DIRNAME.split(path.sep).join('/');
+    const set = await setCoreHooksPath(projectDir, relHooksDir);
+    result.coreHooksPathSet = set.success;
+
+    if (!set.success) {
+      // Hooks are on disk; only the git config wiring failed. Surface a soft
+      // error but keep the artifacts so a later retry / manual `git config`
+      // completes the wiring. Not fatal to the overall install.
+      result.error = set.error;
+      result.success = false;
+      return result;
+    }
+
+    result.success = true;
+    return result;
+  } catch (error) {
+    result.error = error.message;
+    return result;
+  }
+}
+
+module.exports = {
+  installGitHooks,
+  detectHusky,
+  getCoreHooksPath,
+  setCoreHooksPath,
+  writeManagedHook,
+  copyScannerLib,
+  buildPreCommitHook,
+  MANAGED_HOOKS_DIRNAME,
+  MANAGED_MARKER,
+};

package/packages/installer/src/installer/sinapse-ai-installer.js

@@ -335,6 +335,22 @@ async function installSinapseCore(options = {}) {
       }
     }
 
+    // Stream B (Frente 4.2): propagate the SINAPSE secret-scan guard into the
+    // target project via git core.hooksPath + a managed Node pre-commit hook.
+    // Best-effort: a hooks-wiring failure must not abort a successful install.
+    spinner.text = 'Installing git secret-scan guard...';
+    result.gitHooksInstalled = false;
+    try {
+      const { installGitHooks } = require('./git-hooks-installer');
+      const hooksResult = await installGitHooks({ projectDir: targetDir });
+      result.gitHooksInstalled = hooksResult.success;
+      if (!hooksResult.success && hooksResult.error) {
+        result.errors.push(`Git hooks warning: ${hooksResult.error}`);
+      }
+    } catch (hooksError) {
+      result.errors.push(`Git hooks warning: ${hooksError.message}`);
+    }
+
     result.success = true;
     spinner.succeed(`SINAPSE core installed (${result.installedFiles.length} files)`);