sinapse-ai 1.11.3 → 1.12.1

package/.sinapse-ai/development/agents/snps-orqx.md

@@ -44,9 +44,102 @@ After the greeting, check if the user already provided briefing/context with the
 
 If the user asks about SINAPSE, how it works, or how to use it, execute the `*onboard` task from `tasks/onboard-user.md` to provide a guided walkthrough of the ecosystem, available squads, commands, and workflows.
 
+## NON-NEGOTIABLE: INITIAL STATE AUDIT (RUNS FIRST OF ALL)
+
+> **This step runs BEFORE bootstrap classification, BEFORE routing, BEFORE anything.**
+> Without it, Imperator treats every directory as greenfield and ignores existing partial work (brand assets, half-written PRD, components, abandoned epics, brownfield code without `package.json`).
+
+On every briefing that mentions creating, building, or working on a project, run the **Initial State Audit** (full spec in `~/.claude/rules/project-intelligence.md` § Initial State Audit):
+
+1. Silently check the 8 dimensions (Docs, Brand, Design system, Components, Code, Tests, Infra, Git history)
+2. Compute maturity level: `EMPTY` / `BOOTSTRAPPED` / `PARTIAL` / `MATURE` / `SINAPSE_MANAGED`
+3. **Present a structured report to the user (PT-BR) BEFORE proposing any plan:**
+   ```
+   Estado detectado: {maturity_level}
+   Já existe: {list of artifacts found}
+   Faltando: {list of gaps relative to user's goal}
+   Recomendação: {workflow + first step}
+   ```
+4. Only after this report (and any user correction) proceed to bootstrap classification
+
+### Why this exists
+
+Caio's runtime test (2026-05-07) showed the framework treating fresh installs as "create from scratch" without ever checking what already lived in the directory. A user often has brand assets, an old PRD, half-finished components, or an abandoned epic — and the framework was overwriting / duplicating that work instead of continuing from it.
+
+### Anti-patterns (FORBIDDEN)
+
+- Skipping the audit "because it looks empty"
+- Routing to greenfield workflows without first reporting what already exists
+- Overwriting partial work (brand assets, components, docs) without listing it to the user
+- Ignoring `docs/epics/` or `docs/stories/` from a previous session
+- Treating a directory with brand assets but no code as `EMPTY`
+- Treating a directory with `package.json` as `MATURE` when it's actually just bootstrapped infra
+
+## NON-NEGOTIABLE: PROJECT BOOTSTRAP CLASSIFICATION (RUNS AFTER AUDIT, BEFORE ROUTING)
+
+> **This step runs AFTER the Initial State Audit, BEFORE the routing decision. No exceptions.**
+> Without it, Imperator routes large-project requests directly to a domain orchestrator and skips the doc-first pipeline (Article III violation).
+
+After the audit reports the maturity level, classify the request **before** consulting the routing table:
+
+### Step 1 — Detect intent
+
+| Intent | Trigger keywords (PT/EN) |
+|---|---|
+| `new_project_bootstrap` | criar / novo / build / montar / fazer um(a) [site, plataforma, app, API, ...] |
+| `feature_in_existing_project` | implementa / adiciona / add (with `docs/epics/` already present) |
+| `fix` | corrige / conserta / ajusta / fix / bug |
+| `tweak` | troca / muda / altera (small surface, single file) |
+| `domain_consult` | qualquer pergunta de branding, copy, growth, etc. (no code change implied) |
+
+### Step 2 — If `new_project_bootstrap`, sub-classify project_type
+
+| project_type | Triggers | Required workflow |
+|---|---|---|
+| `site` | site, website, institutional, página | `greenfield-ui.yaml` |
+| `lp` | landing page, LP, captura, sales page | `greenfield-ui.yaml` |
+| `app` | app mobile, app nativo, ios, android, react native | `greenfield-ui.yaml` |
+| `platform` | plataforma, dashboard, admin, portal interno | `greenfield-fullstack.yaml` |
+| `saas` | SaaS, software as a service, app web com login | `greenfield-fullstack.yaml` |
+| `api` | API, backend, microservice, serviço REST/GraphQL | `greenfield-service.yaml` |
+| `service` | worker, integration, automation, ETL, cron job | `greenfield-service.yaml` |
+
+### Step 3 — Apply the gate (NON-NEGOTIABLE)
+
+```
+IF intent == new_project_bootstrap
+   AND project_type ∈ [site, lp, app, platform, saas, api, service]
+   AND no epic exists in docs/epics/
+THEN
+   BLOCK any direct routing to domain orchestrators
+   INVOKE the required greenfield workflow (see table)
+   PRODUCE upstream artifacts FIRST: project-brief.md → prd.md → architecture.md (and front-end-spec.md for UI)
+   ONLY AFTER artifacts validated → shard → stories → route to domain orqx for execution
+```
+
+### Step 4 — Complexity gate
+
+If the briefing scores ≥ 16 on the 5 complexity dimensions (scope, integration, infrastructure, knowledge, risk), run the **Spec Pipeline** (`spec-pipeline.yaml`) BEFORE the greenfield workflow:
+
+```
+@project-lead gather → @architect assess → @analyst research →
+@project-lead spec → @quality-gate critique → @architect plan
+```
+
+Only after spec is APPROVED, the greenfield workflow runs.
+
+### Anti-patterns (FORBIDDEN — these violate Article III)
+
+- Routing "criar um site" directly to `@design-orqx` / `@brand-orqx` without first running greenfield-ui.yaml
+- Routing "monta uma plataforma SaaS" to a domain orqx without Spec Pipeline + greenfield-fullstack.yaml
+- Skipping Phase 1 Discovery (5-agent: analyst → project-lead → ux-design-expert → architect → product-lead) on a new UI project
+- Treating "rapidinho" / "simples" as a license to skip doc-first when the project type requires it
+- Generating UI without DS grounding (see `~/.claude/rules/design-system-grounding.md`)
+
 ## NON-NEGOTIABLE: ORCHESTRATION PLAN ON EVERY BRIEFING
 
 > **This is an absolute, non-negotiable rule. No exceptions. No waiting to be asked.**
+> **It runs AFTER the bootstrap classification above.** If the gate routed to a greenfield workflow, the orchestration plan describes that workflow (its phases, agents, handoffs) — not a domain-orqx routing.
 
 When the user provides ANY briefing, request, or initiative (regardless of complexity), Imperator MUST **immediately and autonomously**:
 
@@ -610,6 +703,22 @@ framework_compatibility:
 
 ## How Imperator Operates
 
+### -1. Initial State Audit (ABSOLUTE FIRST)
+Before anything else, Imperator runs the Initial State Audit described above:
+- Silently checks 8 dimensions (Docs, Brand, DS, Components, Code, Tests, Infra, Git)
+- Computes maturity level: `EMPTY` / `BOOTSTRAPPED` / `PARTIAL` / `MATURE` / `SINAPSE_MANAGED`
+- Presents structured PT-BR report to user listing what exists, what's missing, what's recommended
+- Only proceeds when the user has seen what's already there
+
+### 0. Bootstrap Classification (after audit)
+Imperator runs the Project Bootstrap Classification described above:
+- Detects intent: `new_project_bootstrap` / `feature` / `fix` / `tweak` / `domain_consult`
+- Sub-classifies project_type if bootstrap: `site` / `lp` / `app` / `platform` / `saas` / `api` / `service`
+- Applies the gate: large-project bootstrap with no epic → invokes the required greenfield workflow
+- Triggers the Spec Pipeline if complexity score ≥ 16
+- Routes to Continuation Behavior when audit detected `PARTIAL` maturity (never overwrite existing work)
+- Only proceeds to step 1 (routing) when this gate is satisfied
+
 ### 1. Diagnose First
 Every request gets classified before routing. Imperator identifies:
 - **Domain(s):** Which squad(s) own this work?

package/.sinapse-ai/development/scripts/agent-config-loader.js

@@ -12,6 +12,10 @@ const path = require('path');
 const yaml = require('js-yaml');
 const { globalConfigCache } = require('../../core/config/config-cache');
 const { trackConfigLoad } = require('../../infrastructure/scripts/performance-tracker');
+// Canonical short-form → file-id alias map (single source of truth). Without this,
+// short ids like 'dev'/'qa'/'sinapse-orqx' resolve to '<id>.md' which does not exist
+// (files are developer.md / quality-gate.md / snps-orqx.md), degrading the greeting.
+const { ALIASES: AGENT_ID_ALIASES } = require('../../core/registry/squad-agent-resolver');
 
 /**
  * Agent configuration requirements cache
@@ -317,8 +321,10 @@ class AgentConfigLoader {
       }
     }
     
-    // Load from file
-    const agentPath = path.join(process.cwd(), '.sinapse-ai', 'development', 'agents', `${this.agentId}.md`);
+    // Load from file. Resolve short-form aliases (dev→developer, qa→quality-gate,
+    // sinapse-orqx→snps-orqx, ...) to the canonical file id before building the path.
+    const fileId = AGENT_ID_ALIASES[this.agentId] || this.agentId;
+    const agentPath = path.join(process.cwd(), '.sinapse-ai', 'development', 'agents', `${fileId}.md`);
     
     try {
       const content = await fs.readFile(agentPath, 'utf8');

package/.sinapse-ai/development/templates/sinapse-doc-template.md

@@ -65,7 +65,7 @@ _Last Updated: {{DATE}} | SINAPSE Framework Team_
 ```markdown
 # {{TITLE}}
 
-> **EN** | [PT](../pt/path/{{FILENAME}}) | [ES](../es/path/{{FILENAME}})
+> **EN** | [PT](../pt/path/{{FILENAME}})
 
 ---
 
@@ -169,7 +169,7 @@ _Last Updated: {{DATE}} | SINAPSE Framework Team_
 ```markdown
 # ADR-{{NUMBER}}: {{TITLE}}
 
-> **EN** | [PT](../../pt/architecture/adr/{{FILENAME}}) | [ES](../../es/architecture/adr/{{FILENAME}})
+> **EN** | [PT](../../pt/architecture/adr/{{FILENAME}})
 
 ---
 
@@ -224,7 +224,7 @@ _Decision made as part of {{STORY_ID}}._
 ```markdown
 # {{TITLE}} Guide
 
-> **EN** | [PT](../pt/guides/{{FILENAME}}) | [ES](../es/guides/{{FILENAME}})
+> **EN** | [PT](../pt/guides/{{FILENAME}})
 
 ---
 
@@ -311,7 +311,7 @@ _Last Updated: {{DATE}} | SINAPSE Framework Team_
 ```markdown
 # {{COMPONENT}} Reference
 
-> **EN** | [PT](../pt/reference/{{FILENAME}}) | [ES](../es/reference/{{FILENAME}})
+> **EN** | [PT](../pt/reference/{{FILENAME}})
 
 ---
 
@@ -396,7 +396,7 @@ docs/
 Always include the language navigation header:
 
 ```markdown
-> **EN** | [PT](../pt/path/file.md) | [ES](../es/path/file.md)
+> **EN** | [PT](../pt/path/file.md)
 ```
 
 ### Translation Notes
@@ -445,7 +445,7 @@ Always include the language navigation header:
 ```markdown
 # Creating Custom Agents
 
-> **EN** | [PT](../pt/guides/creating-agents.md) | [ES](../es/guides/creating-agents.md)
+> **EN** | [PT](../pt/guides/creating-agents.md)
 
 ---
 

package/.sinapse-ai/git-hooks/lib/framework-guard.js

@@ -54,6 +54,7 @@ function globToRegex(glob) {
   pattern = pattern.replace(/\*/g, '[^/]+');
 
   // 4. Restore ** placeholder to any-depth matcher
+  // eslint-disable-next-line no-control-regex -- internal placeholder char (set above), never user input
   pattern = pattern.replace(/\u0000/g, '.+');
 
   // If pattern ends with .+ (was **), match prefix

package/.sinapse-ai/git-hooks/lib/staged-protected-files-guard.js

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * staged-protected-files-guard — blocks a commit that DELETES (or untracks) a
+ * protected, committed-but-critical framework file.
+ *
+ * Why: on 2026-06-20 a "snapshot migracao notebook" sweep (`git add -A`) untracked
+ * `.sinapse-ai/core/registry/service-registry.json` (the committed registry drift
+ * detector, ~12k lines), bundled it with unrelated work, and pushed it. The
+ * framework-boundary guard is a no-op in contributor mode
+ * (boundary.frameworkProtection=false), so nothing stopped the deletion. This guard
+ * is ALWAYS on and narrowly targets that class of damage — it never touches normal
+ * edits, only the removal of a curated set of protected paths.
+ *
+ * Intentional removal (done in a story) bypasses with: git commit --no-verify
+ *
+ * Self-contained: Node built-ins + `git` only (matches the other lib guards so it
+ * bundles into <hooksDir>/lib/ with no extra deps).
+ */
+
+const { spawnSync } = require('child_process');
+
+// Curated, high-signal list. Keep small to guarantee zero false positives on
+// normal work. These files are committed on purpose and must never be removed by
+// an automated sweep without an explicit story.
+const PROTECTED = ['.sinapse-ai/core/registry/service-registry.json'];
+
+function stagedDeletions() {
+  // --no-renames forces a rename-away of a protected file to surface as a real
+  // deletion (D) of the old path, so moving the file out also trips the guard.
+  const res = spawnSync('git', ['diff', '--cached', '--name-status', '--no-renames'], {
+    encoding: 'utf8',
+  });
+  if (!res || res.status !== 0 || typeof res.stdout !== 'string') return [];
+  const deleted = [];
+  for (const line of res.stdout.split('\n')) {
+    if (!line) continue;
+    const parts = line.split('\t');
+    const status = parts[0];
+    const file = (parts[parts.length - 1] || '').replace(/\\/g, '/');
+    if (status === 'D') deleted.push(file);
+  }
+  return deleted;
+}
+
+const offenders = stagedDeletions().filter((f) => PROTECTED.includes(f));
+
+if (offenders.length > 0) {
+  process.stderr.write(
+    'SINAPSE Protected Files: blocking commit — it deletes/untracks a protected file:\n',
+  );
+  for (const f of offenders) process.stderr.write('  - ' + f + '\n');
+  process.stderr.write(
+    '\nThese files are committed on purpose (e.g. service-registry.json is the registry\n' +
+      'drift detector). They must not be removed by an automated sweep (git add -A) or a\n' +
+      'machine-migration snapshot. If this removal is intentional, do it in a story and\n' +
+      'bypass once with:  git commit --no-verify\n',
+  );
+  process.exit(1);
+}
+
+process.exit(0);

package/.sinapse-ai/git-hooks/pre-commit

@@ -11,12 +11,14 @@ const projectRoot = process.cwd();
 const libDir = path.join(__dirname, 'lib');
 
 // --- 1-3. SINAPSE staged guards (each fail-CLOSED) ---------------------------
-// Order: secret scan, then destructive-SQL guard, then framework-boundary guard.
+// Order: secret scan, destructive-SQL guard, framework-boundary guard, then
+// protected-files guard (always-on anti-sweep; does NOT respect frameworkProtection).
 // framework-guard self-disables when boundary.frameworkProtection is false.
 const GUARDS = [
   { file: 'staged-secret-scan.js', label: 'Secret Scan' },
   { file: 'staged-sql-guard.js',   label: 'SQL Guard' },
   { file: 'framework-guard.js',    label: 'Framework Boundary' },
+  { file: 'staged-protected-files-guard.js', label: 'Protected Files' },
 ];
 
 for (const guard of GUARDS) {

package/.sinapse-ai/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Type declarations for the SINAPSE programmatic API (CommonJS + ESM entry points).
+ *
+ * The underlying modules are authored in JavaScript, so these declarations expose
+ * the public constructors only — enough for `import { MetaAgent } from 'sinapse-ai'`
+ * to resolve. Member signatures are intentionally permissive (the JS implementation
+ * is the source of truth); this file does NOT fabricate detailed types it cannot
+ * guarantee. The framework is CLI-first; the programmatic API is a secondary surface.
+ */
+
+/** A JS class/constructor exposed by the framework, with an unconstrained surface. */
+type FrameworkConstructor = new (...args: unknown[]) => unknown;
+
+export const MetaAgent: FrameworkConstructor;
+export const TaskManager: FrameworkConstructor;
+export const ElicitationEngine: FrameworkConstructor;
+export const TemplateEngine: FrameworkConstructor;
+export const ComponentSearch: FrameworkConstructor;
+export const DependencyAnalyzer: FrameworkConstructor;

package/.sinapse-ai/infrastructure/scripts/validate-agents.js

@@ -35,6 +35,18 @@ const DATA_DIR = path.join(ROOT_DIR, 'development', 'data');
 const UTILS_DIR = path.join(ROOT_DIR, 'development', 'utils');
 const WORKFLOWS_DIR = path.join(ROOT_DIR, 'development', 'workflows');
 const SCRIPTS_DIR = path.join(ROOT_DIR, 'development', 'scripts');
+// Additional canonical homes — the framework stores agent artifacts across
+// development/, product/, data/ and infrastructure/, not only development/.
+const KNOWLEDGE_BASE_DIR = path.join(ROOT_DIR, 'development', 'knowledge-base');
+const PRODUCT_TEMPLATES_DIR = path.join(ROOT_DIR, 'product', 'templates');
+const PRODUCT_CHECKLISTS_DIR = path.join(ROOT_DIR, 'product', 'checklists');
+const PRODUCT_DATA_DIR = path.join(ROOT_DIR, 'product', 'data');
+const ROOT_DATA_DIR = path.join(ROOT_DIR, 'data');
+const INFRA_SCRIPTS_DIR = path.join(ROOT_DIR, 'infrastructure', 'scripts');
+const INFRA_SCHEMAS_DIR = path.join(ROOT_DIR, 'infrastructure', 'schemas');
+const SCHEMAS_DIR = path.join(ROOT_DIR, 'schemas');
+const CORE_EXECUTION_DIR = path.join(ROOT_DIR, 'core', 'execution');
+const CORE_MEMORY_DIR = path.join(ROOT_DIR, 'core', 'memory');
 
 // Commands that are allowed to be shared by multiple agents
 // These are utility/infrastructure commands, not domain-specific
@@ -187,14 +199,18 @@ async function validateDependencies(agents) {
   const errors = [];
   const warnings = [];
 
+  // Each dependency type resolves against one or more candidate directories —
+  // an artifact is considered present if it exists in ANY of them.
   const depDirs = {
-    tasks: TASKS_DIR,
-    templates: TEMPLATES_DIR,
-    checklists: CHECKLISTS_DIR,
-    data: DATA_DIR,
-    utils: UTILS_DIR,
-    workflows: WORKFLOWS_DIR,
-    scripts: SCRIPTS_DIR,
+    tasks: [TASKS_DIR],
+    templates: [TEMPLATES_DIR, PRODUCT_TEMPLATES_DIR],
+    checklists: [CHECKLISTS_DIR, PRODUCT_CHECKLISTS_DIR],
+    data: [DATA_DIR, ROOT_DATA_DIR, PRODUCT_DATA_DIR],
+    utils: [UTILS_DIR, SCRIPTS_DIR, INFRA_SCRIPTS_DIR, CORE_EXECUTION_DIR, CORE_MEMORY_DIR],
+    workflows: [WORKFLOWS_DIR],
+    scripts: [SCRIPTS_DIR, INFRA_SCRIPTS_DIR, CORE_EXECUTION_DIR, CORE_MEMORY_DIR],
+    knowledge_bases: [KNOWLEDGE_BASE_DIR],
+    schemas: [SCHEMAS_DIR, INFRA_SCHEMAS_DIR],
   };
 
   // Dependency types that are not file-based (external tools, integrations)
@@ -208,8 +224,8 @@ async function validateDependencies(agents) {
       if (skipDepTypes.has(depType)) continue;
       if (!Array.isArray(depList)) continue;
 
-      const depDir = depDirs[depType];
-      if (!depDir) {
+      const candidateDirs = depDirs[depType];
+      if (!candidateDirs) {
         warnings.push({
           type: 'UNKNOWN_DEP_TYPE',
           agent: agent.id,
@@ -219,9 +235,23 @@ async function validateDependencies(agents) {
         continue;
       }
 
-      for (const depFile of depList) {
-        const depPath = path.join(depDir, depFile);
-        const exists = await fileExists(depPath);
+      for (const depFile2 of depList) {
+        // Bare references (no extension) may be listed without their suffix —
+        // try the common framework extensions before declaring them missing.
+        const extCandidates = path.extname(depFile2)
+          ? ['']
+          : ['', '.js', '.cjs', '.md', '.yaml', '.yml'];
+
+        let exists = false;
+        for (const dir of candidateDirs) {
+          for (const ext of extCandidates) {
+            if (await fileExists(path.join(dir, depFile2 + ext))) {
+              exists = true;
+              break;
+            }
+          }
+          if (exists) break;
+        }
 
         if (!exists) {
           // Missing dependencies are warnings, not errors (pre-existing technical debt)
@@ -229,10 +259,10 @@ async function validateDependencies(agents) {
             type: 'MISSING_DEPENDENCY',
             agent: agent.id,
             depType,
-            depFile,
-            expectedPath: depPath,
-            message: `Missing dependency: @${agent.id} → ${depType}/${depFile}`,
-            suggestion: `Create the file at ${depPath} or remove from agent dependencies.`,
+            depFile: depFile2,
+            expectedPath: path.join(candidateDirs[0], depFile2),
+            message: `Missing dependency: @${agent.id} → ${depType}/${depFile2}`,
+            suggestion: `Create the file under one of [${candidateDirs.join(', ')}] or remove from agent dependencies.`,
           });
         }
       }