sinapse-ai 1.6.1 → 1.8.0

package/.sinapse-ai/development/scripts/squad/squad-downloader.js

@@ -33,6 +33,39 @@ const GITHUB_API_BASE =
  */
 const DEFAULT_SQUADS_PATH = './squads';
 
+/**
+ * Allowlist of HTTPS hosts permitted when following HTTP redirects.
+ * Prevents SSRF / redirect-based exfiltration to arbitrary hosts.
+ * @constant {Set<string>}
+ */
+const ALLOWED_REDIRECT_HOSTS = new Set([
+  'raw.githubusercontent.com',
+  'api.github.com',
+  'github.com',
+  'objects.githubusercontent.com',
+  'codeload.github.com',
+]);
+
+/**
+ * Maximum number of redirects to follow before aborting a fetch.
+ * @constant {number}
+ */
+const MAX_REDIRECTS = 5;
+
+/**
+ * Per-request timeout (ms). Aborts a hung/slow remote so a compromised or
+ * unresponsive host can't stall the installer indefinitely (P3-001).
+ * @constant {number}
+ */
+const REQUEST_TIMEOUT_MS = 30000;
+
+/**
+ * Maximum response size (bytes). Caps a single download so a malicious/
+ * misconfigured host can't exhaust memory (10 MB is ample for a squad).
+ * @constant {number}
+ */
+const MAX_RESPONSE_BYTES = 10 * 1024 * 1024;
+
 /**
  * Error codes for SquadDownloaderError
  * @enum {string}
@@ -370,6 +403,51 @@ class SquadDownloader {
     this._log(`Downloaded ${contents.length} items to ${targetPath}`);
   }
 
+  /**
+   * Resolve and validate that an item lands strictly inside the target path.
+   * Defends against zip-slip / path traversal when `item.name` originates from
+   * an untrusted remote source (GitHub API / registry).
+   *
+   * @private
+   * @param {string} targetPath - Trusted base directory
+   * @param {string} itemName - Untrusted entry name from remote response
+   * @returns {string} Safe, resolved item path contained within targetPath
+   * @throws {SquadDownloaderError} VALIDATION_ERROR if traversal is detected
+   */
+  _safeResolve(targetPath, itemName) {
+    // Reject names that are missing, contain path separators, or use '..'.
+    if (
+      typeof itemName !== 'string' ||
+      itemName.length === 0 ||
+      itemName === '.' ||
+      itemName === '..' ||
+      itemName.includes('/') ||
+      itemName.includes('\\') ||
+      itemName.includes('\0')
+    ) {
+      throw new SquadDownloaderError(
+        DownloaderErrorCodes.VALIDATION_ERROR,
+        `Unsafe item name from remote response: "${itemName}"`,
+        'Squad entries must be plain file/directory names without path separators or ".."',
+      );
+    }
+
+    const itemPath = path.join(targetPath, itemName);
+    const resolved = path.resolve(itemPath);
+    const base = path.resolve(targetPath);
+
+    // Resolved path must be strictly inside the base directory.
+    if (resolved !== base && !resolved.startsWith(base + path.sep)) {
+      throw new SquadDownloaderError(
+        DownloaderErrorCodes.VALIDATION_ERROR,
+        `Path traversal detected: "${itemName}" escapes target directory`,
+        'Squad entries must stay within the download directory',
+      );
+    }
+
+    return itemPath;
+  }
+
   /**
    * Download contents recursively
    * @private
@@ -378,7 +456,8 @@ class SquadDownloader {
    */
   async _downloadContents(contents, targetPath) {
     for (const item of contents) {
-      const itemPath = path.join(targetPath, item.name);
+      // Validate containment BEFORE any filesystem write (zip-slip guard).
+      const itemPath = this._safeResolve(targetPath, item.name);
 
       if (item.type === 'file') {
         // Download file - Buffer is written directly (supports binary files)
@@ -400,9 +479,10 @@ class SquadDownloader {
    * @private
    * @param {string} url - URL to fetch
    * @param {boolean} [useApi=false] - Whether to use GitHub API headers
+   * @param {number} [redirectCount=0] - Current redirect depth (internal)
    * @returns {Promise<Buffer>} Response body as Buffer (supports binary files)
    */
-  _fetch(url, useApi = false) {
+  _fetch(url, useApi = false, redirectCount = 0) {
     return new Promise((resolve, reject) => {
       const options = {
         headers: {
@@ -417,8 +497,7 @@ class SquadDownloader {
         }
       }
 
-      https
-        .get(url, options, (res) => {
+      const req = https.get(url, options, (res) => {
           // Check for rate limiting
           if (res.statusCode === 403) {
             const rateLimitRemaining = res.headers['x-ratelimit-remaining'];
@@ -438,7 +517,53 @@ class SquadDownloader {
 
           // Check for redirect
           if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
-            this._fetch(res.headers.location, useApi).then(resolve).catch(reject);
+            // Drain the redirect response to free the socket.
+            res.resume();
+
+            // Cap redirect depth to prevent redirect loops.
+            if (redirectCount >= MAX_REDIRECTS) {
+              reject(
+                new SquadDownloaderError(
+                  DownloaderErrorCodes.NETWORK_ERROR,
+                  `Too many redirects (>${MAX_REDIRECTS}) while fetching ${url}`,
+                  'The remote server may be misconfigured or attempting a redirect loop',
+                ),
+              );
+              return;
+            }
+
+            // Resolve the Location against the current URL and enforce an
+            // HTTPS host allowlist (SSRF / exfiltration guard).
+            let redirectUrl;
+            try {
+              redirectUrl = new URL(res.headers.location, url);
+            } catch {
+              reject(
+                new SquadDownloaderError(
+                  DownloaderErrorCodes.NETWORK_ERROR,
+                  `Invalid redirect URL: ${res.headers.location}`,
+                ),
+              );
+              return;
+            }
+
+            if (
+              redirectUrl.protocol !== 'https:' ||
+              !ALLOWED_REDIRECT_HOSTS.has(redirectUrl.hostname)
+            ) {
+              reject(
+                new SquadDownloaderError(
+                  DownloaderErrorCodes.VALIDATION_ERROR,
+                  `Refusing redirect to disallowed host: ${redirectUrl.protocol}//${redirectUrl.hostname}`,
+                  'Redirects are restricted to trusted GitHub HTTPS hosts',
+                ),
+              );
+              return;
+            }
+
+            this._fetch(redirectUrl.toString(), useApi, redirectCount + 1)
+              .then(resolve)
+              .catch(reject);
             return;
           }
 
@@ -453,25 +578,55 @@ class SquadDownloader {
             return;
           }
 
-          // Collect chunks as Buffer objects to support binary files
+          // Collect chunks as Buffer objects to support binary files, capping
+          // total size to prevent a malicious host from exhausting memory.
           const chunks = [];
+          let total = 0;
           res.on('data', (chunk) => {
+            total += chunk.length;
+            if (total > MAX_RESPONSE_BYTES) {
+              const err = new SquadDownloaderError(
+                DownloaderErrorCodes.NETWORK_ERROR,
+                `Response exceeded ${MAX_RESPONSE_BYTES} bytes — aborting`,
+                'The remote file is unexpectedly large; verify the source',
+              );
+              if (typeof req.destroy === 'function') req.destroy(err);
+              else reject(err);
+              return;
+            }
             chunks.push(chunk);
           });
           res.on('end', () => {
             // Concatenate all chunks into a single Buffer
             resolve(Buffer.concat(chunks));
           });
-        })
-        .on('error', (error) => {
-          reject(
-            new SquadDownloaderError(
-              DownloaderErrorCodes.NETWORK_ERROR,
-              `Network error: ${error.message}`,
-              'Check internet connection',
-            ),
+        });
+
+      // Abort hung requests (P3-001) — destroy() surfaces via the 'error' handler.
+      // Guarded: test doubles for https.get may not implement setTimeout/destroy.
+      if (typeof req.setTimeout === 'function') {
+        req.setTimeout(REQUEST_TIMEOUT_MS, () => {
+          const err = new SquadDownloaderError(
+            DownloaderErrorCodes.NETWORK_ERROR,
+            `Request timed out after ${REQUEST_TIMEOUT_MS}ms fetching ${url}`,
+            'Check internet connection or try again later',
           );
+          if (typeof req.destroy === 'function') req.destroy(err);
+          else reject(err);
         });
+      }
+
+      req.on('error', (error) => {
+        reject(
+          error instanceof SquadDownloaderError
+            ? error
+            : new SquadDownloaderError(
+                DownloaderErrorCodes.NETWORK_ERROR,
+                `Network error: ${error.message}`,
+                'Check internet connection',
+              ),
+        );
+      });
     });
   }
 

package/.sinapse-ai/development/tasks/delegate-to-external-executor.md

@@ -0,0 +1,152 @@
+# delegate-to-external-executor.md
+
+**Task**: Delegate Implementation to External Executor
+
+**Purpose**: Standardize the orchestrator/executor split for SINAPSE workflows. The active SINAPSE runtime keeps authority over story interpretation, acceptance criteria validation, constitutional gates, review, and story updates while a separate CLI runtime performs only the implementation attempt.
+
+**When to use**: Use only for `@developer` implementation work where the story scope is clear enough to hand to another runtime. Do not use for @product-lead, @quality-gate, @sprint-lead, @devops, architecture approval, or release authority.
+
+## Task Definition
+
+```yaml
+task: delegateToExternalExecutor()
+responsavel: Orchestrating agent
+responsavel_type: Agente
+atomic_layer: Organism
+
+inputs:
+  - campo: prompt
+    tipo: string
+    obrigatorio: true
+    validacao: Must cite acceptance criteria, story path, file scope, and explicit non-goals
+  - campo: slug
+    tipo: string
+    obrigatorio: true
+    validacao: Stable filesystem-safe run slug
+  - campo: story_id
+    tipo: string
+    obrigatorio: false
+  - campo: story_path
+    tipo: string
+    obrigatorio: false
+  - campo: workdir
+    tipo: string
+    obrigatorio: false
+    default: Current project root
+  - campo: provider
+    tipo: string
+    obrigatorio: false
+    default: codex
+
+outputs:
+  - campo: run_dir
+    tipo: string
+    destino: Orchestrator
+  - campo: output
+    tipo: file
+    destino: <run_dir>/output.md
+  - campo: log
+    tipo: file
+    destino: <run_dir>/<provider>.log
+  - campo: diff
+    tipo: git-diff
+    destino: Orchestrator review
+```
+
+## Configuration
+
+Delegation is disabled by default.
+
+```yaml
+dev:
+  execution_mode: native       # native | delegate
+  delegate_to: codex
+  auto_review: true
+
+external_executors:
+  enabled: false
+  default_sandbox: workspace-write   # read-only | workspace-write | full-auto | danger-full-access
+  run_dir: .sinapse/external-runs
+```
+
+## Pre-Conditions
+
+```yaml
+pre_conditions:
+  - [ ] External executor provider is installed and available on PATH.
+  - [ ] Working tree is clean, or existing intentional changes are already committed.
+  - [ ] Prompt cites the story path and acceptance criteria.
+  - [ ] Prompt lists allowed file scope and explicit non-goals.
+  - [ ] Delegated work is implementation work owned by @developer.
+  - [ ] Orchestrator has enough context to review the resulting diff.
+```
+
+## Execution
+
+### 1. Build the Prompt
+
+The orchestrator writes a prompt that contains:
+
+- Story ID and story path
+- Acceptance criteria copied or summarized from the story
+- Allowed file paths or modules
+- Testing expectations
+- Constraints from Constitution and project rules
+- Explicit instruction that the executor must not update story status, checkboxes, File List, PRs, or releases
+
+### 2. Start the Delegate Run
+
+Use the wrapper:
+
+```bash
+sinapse-delegate codex -t <slug> -f <prompt_file> -d <workdir>
+```
+
+The wrapper prints:
+
+```text
+STATUS=started
+RUN_DIR=.sinapse/external-runs/<timestamp>-<slug>
+PID=<pid>
+LOG=<run_dir>/codex.log
+OUTPUT=<run_dir>/output.md
+PROMPT=<run_dir>/prompt.md
+COMMAND=<provider command>
+```
+
+### 3. Monitor Completion
+
+The orchestrator may tail the log or wait for the PID. Do not mark story progress while the external executor is still running.
+
+### 4. Review Output and Diff
+
+The orchestrator must read:
+
+- `<run_dir>/output.md`
+- `<run_dir>/<provider>.log`
+- `git diff`
+
+Then validate:
+
+```yaml
+review_checklist:
+  - [ ] Every acceptance criterion is satisfied.
+  - [ ] Diff scope matches the story and prompt.
+  - [ ] Article IV No Invention: every change traces to a requirement.
+  - [ ] Tests were added or updated when behavior changed.
+  - [ ] Lint, typecheck, and relevant tests pass.
+  - [ ] No story state was mutated before review approval.
+```
+
+### 5. Accept or Iterate
+
+- **Approved**: orchestrator updates story checkboxes, File List, status, and final validation evidence.
+- **Rejected**: orchestrator writes specific feedback and may start a new run with a new slug or iteration suffix.
+
+## Anti-Patterns
+
+- Marking a story done by trusting the executor summary without reading the diff.
+- Delegating @product-lead, @quality-gate, @sprint-lead, or @devops authority to an external runtime.
+- Letting the executor create PRs, push, release, or mutate story state.
+- Delegating vague work without acceptance criteria and file scope.
+- Running with `danger-full-access` unless the surrounding environment is externally sandboxed.

package/.sinapse-ai/development/tasks/github-devops-pre-push-quality-gate.md

@@ -318,45 +318,64 @@ If conflicts detected, fail with message:
 Resolve conflicts before pushing.
 ```
 
-### 4. Run npm run lint (if script exists)
+### 4. Run Layer 1 Quality Gate (lint + test + typecheck) — CANONICAL
 
-```javascript
-function runNpmScript(scriptName, projectRoot) {
-  const packageJsonPath = path.join(projectRoot, 'package.json');
-  const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+> **Do NOT reimplement lint/test/typecheck here.** The framework already ships
+> the canonical Layer 1 pre-commit gate (`core/quality-gates/layer1-precommit.js`),
+> exposed via the CLI. Calling it keeps a single source of truth for the quality
+> checks (Constitution Art. I — CLI First) instead of forking the logic.
 
-  if (!packageJson.scripts || !packageJson.scripts[scriptName]) {
-    console.log(`⚠️  Script "${scriptName}" not found - skipping`);
-    return { skipped: true };
-  }
+```bash
+sinapse qa run --layer=1
+```
 
+Layer 1 runs **lint (ESLint), unit tests (Jest), and typecheck** — fast local
+checks — and gracefully skips any check whose npm script is absent. Exit code:
+`0` = PASS, non-zero = FAIL.
+
+```javascript
+const { execSync } = require('child_process');
+
+function runLayer1QualityGate(projectRoot) {
   try {
-    execSync(`npm run ${scriptName}`, {
-      cwd: projectRoot,
-      stdio: 'inherit'
-    });
-    console.log(`✓ ${scriptName} PASSED`);
+    // The canonical 3-check Layer 1 gate. stdio:'inherit' streams its report.
+    execSync('sinapse qa run --layer=1', { cwd: projectRoot, stdio: 'inherit' });
+    console.log('✓ Layer 1 (lint + test + typecheck) PASSED');
     return { passed: true };
   } catch (error) {
-    console.error(`❌ ${scriptName} FAILED`);
+    console.error('❌ Layer 1 quality gate FAILED');
     return { passed: false, error };
   }
 }
 ```
 
-### 5. Run npm test (if script exists)
+### 5. Run npm run build (if script exists)
 
-Same logic as lint, but for `npm test`.
+Build is outside Layer 1's scope (Layer 1 is the fast lint/test/typecheck pass),
+so it stays a separate step. Skips gracefully when the `build` script is absent.
 
-### 6. Run npm run typecheck (if script exists)
-
-Same logic as lint, but for `npm run typecheck`.
+```javascript
+function runBuild(projectRoot) {
+  const packageJsonPath = path.join(projectRoot, 'package.json');
+  const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
 
-### 7. Run npm run build (if script exists)
+  if (!packageJson.scripts || !packageJson.scripts.build) {
+    console.log('⚠️  Script "build" not found - skipping');
+    return { skipped: true };
+  }
 
-Same logic as lint, but for `npm run build`.
+  try {
+    execSync('npm run build', { cwd: projectRoot, stdio: 'inherit' });
+    console.log('✓ build PASSED');
+    return { passed: true };
+  } catch (error) {
+    console.error('❌ build FAILED');
+    return { passed: false, error };
+  }
+}
+```
 
-### 8. Run CodeRabbit CLI Review (TR-3.14.12)
+### 6. Run CodeRabbit CLI Review (TR-3.14.12)
 
 ```javascript
 const { execSync } = require('child_process');
@@ -503,7 +522,7 @@ if (coderabbitResult.gateImpact === 'CONCERNS') {
 }
 ```
 
-### 9. Run Security Scan (TR-3.14.11)
+### 7. Run Security Scan (TR-3.14.11)
 
 ```javascript
 const { execSync } = require('child_process');
@@ -630,7 +649,7 @@ function determineSecurityGate(results) {
 }
 ```
 
-### 9.1 Impact Analysis (Code Intelligence — Advisory Only)
+### 7.1 Impact Analysis (Code Intelligence — Advisory Only)
 
 > **Added by:** Story NOG-7 (DevOps Pre-Push Impact Analysis)
 > **Behavior:** Advisory only — NEVER blocks push. Auto-skips if code intelligence unavailable.
@@ -688,7 +707,7 @@ Impact Analysis:
 
 ---
 
-### 10. Verify Story Status (Optional - if using story-driven workflow)
+### 8. Verify Story Status (Optional - if using story-driven workflow)
 
 ```javascript
 function checkStoryStatus(storyPath) {
@@ -735,9 +754,7 @@ Mode:        {framework-development | project-development}
 Quality Checks:
   ✓ No uncommitted changes
   ✓ No merge conflicts
-  ✓ npm run lint         PASSED
-  ✓ npm test             PASSED
-  ✓ npm run typecheck    PASSED
+  ✓ Layer 1 (lint+test+typecheck)  PASSED   (via `sinapse qa run --layer=1`)
   ✓ npm run build        PASSED
   ✓ Security scan        PASSED
   ⚠️ Story status         SKIPPED (no story file)

package/.sinapse-ai/development/tasks/update-sinapse.md

@@ -1,11 +1,11 @@
 # Task: Update SINAPSE Framework
 
-> **Version:** 4.0.0
+> **Version:** 5.2.0
 > **Created:** 2026-01-29
-> **Updated:** 2026-01-31
+> **Updated:** 2026-06-15
 > **Type:** SYNC (git-native framework synchronization)
 > **Agent:** @devops (Pipeline) or @sinapse (Orion)
-> **Execution:** Simple bash script (~15 lines)
+> **Execution:** Bash script (~150 lines)
 
 ## Purpose
 

package/.sinapse-ai/hooks/sinapse-brand-grounding.cjs

@@ -39,15 +39,12 @@ function readStdin() {
   });
 }
 
+// Story 10.47: delegate to the shared grounding config loader instead of
+// duplicating the read+parse. The require is guarded so the hook stays
+// fail-open even if the shared module is somehow absent at runtime.
 function loadConfig() {
   try {
-    if (!fs.existsSync(CONFIG_PATH)) return null;
-    const raw = fs.readFileSync(CONFIG_PATH, 'utf8');
-    let yaml;
-    try { yaml = require('js-yaml'); } catch { return null; }
-    const parsed = yaml.load(raw);
-    if (!parsed || typeof parsed !== 'object') return null;
-    return parsed;
+    return require('../core/grounding/config-loader.cjs').loadGroundingConfig(CONFIG_PATH);
   } catch {
     return null;
   }

package/.sinapse-ai/hooks/sinapse-ds-grounding.cjs

@@ -11,7 +11,7 @@
  * (PT + EN). Injects the first 3000 chars of the DS law file as
  * `<ds-grounding>` context.
  *
- * Coexistence: Caio's personal `~/.claude/hooks/design-system-grounding.cjs`
+ * Coexistence: the user's personal `~/.claude/hooks/design-system-grounding.cjs` (if present)
  * reads `ds-routing.json` and is unaffected by this file.
  */
 
@@ -66,15 +66,12 @@ function readStdin() {
   });
 }
 
+// Story 10.47: delegate to the shared grounding config loader instead of
+// duplicating the read+parse. The require is guarded so the hook stays
+// fail-open even if the shared module is somehow absent at runtime.
 function loadConfig() {
   try {
-    if (!fs.existsSync(CONFIG_PATH)) return null;
-    const raw = fs.readFileSync(CONFIG_PATH, 'utf8');
-    let yaml;
-    try { yaml = require('js-yaml'); } catch { return null; }
-    const parsed = yaml.load(raw);
-    if (!parsed || typeof parsed !== 'object') return null;
-    return parsed;
+    return require('../core/grounding/config-loader.cjs').loadGroundingConfig(CONFIG_PATH);
   } catch {
     return null;
   }

package/.sinapse-ai/hooks/sinapse-vault-grounding.cjs

@@ -13,8 +13,8 @@
  *
  * Coexistence with personal hooks: this file lives at
  *   .sinapse-ai/hooks/sinapse-vault-grounding.cjs
- * and reads `sinapse-ai-config.yaml`. Caio's personal
- * `~/.claude/hooks/vault-grounding.cjs` reads `vault-routing.json`. The two
+ * and reads `sinapse-ai-config.yaml`. The user's personal
+ * `~/.claude/hooks/vault-grounding.cjs` (if present) reads `vault-routing.json`. The two
  * files do not collide (different filenames, different config sources, and
  * fail-open guarantees that running both is safe).
  *
@@ -54,15 +54,12 @@ function readStdin() {
   });
 }
 
+// Story 10.47: delegate to the shared grounding config loader instead of
+// duplicating the read+parse. The require is guarded so the hook stays
+// fail-open even if the shared module is somehow absent at runtime.
 function loadConfig() {
   try {
-    if (!fs.existsSync(CONFIG_PATH)) return null;
-    const raw = fs.readFileSync(CONFIG_PATH, 'utf8');
-    let yaml;
-    try { yaml = require('js-yaml'); } catch { return null; }
-    const parsed = yaml.load(raw);
-    if (!parsed || typeof parsed !== 'object') return null;
-    return parsed;
+    return require('../core/grounding/config-loader.cjs').loadGroundingConfig(CONFIG_PATH);
   } catch {
     return null;
   }

package/.sinapse-ai/infrastructure/integrations/ai-providers/ai-provider-factory.js

@@ -42,7 +42,10 @@ const DEFAULT_CONFIG = {
     },
   },
   claude: {
-    model: 'claude-3-5-sonnet',
+    // No hardcoded model: stale IDs get rejected by the CLI ("model may not
+    // exist"). null → omit --model and use the user's CLI default, which is
+    // always a valid, current model.
+    model: null,
     timeout: 300000,
     dangerouslySkipPermissions: false,
   },