sinapse-ai 1.16.0 → 1.17.0

package/.sinapse-ai/core/atlas/flows-pt.js

@@ -0,0 +1,253 @@
+/**
+ * Framework Operating Flows — PT-BR translations.
+ *
+ * Portuguese rendering of FRAMEWORK_FLOWS (flows.js), keyed by flow id. Used by
+ * the research-card render target so the SINAPSE case-study card in the
+ * engineering-software research reads in the same language as the rest of that
+ * corpus. flows.js stays the single source of *which* flows exist and their
+ * structure; this file is the translation layer.
+ *
+ * Drift guard: a test asserts every id in FRAMEWORK_FLOWS has an entry here, so
+ * adding a flow without translating it fails CI.
+ *
+ * @module core/atlas/flows-pt
+ */
+
+'use strict';
+
+/** @type {Record<string,{titulo:string,proposito:string,mermaid:string}>} */
+const FRAMEWORK_FLOWS_PT = {
+  lifecycle: {
+    titulo: 'Ciclo de ponta a ponta',
+    proposito:
+      'A espinha completa que um pedido percorre: do briefing ao código entregue, com o pipeline doc-first e os gates no meio.',
+    mermaid: `flowchart TD
+    U[Briefing do usuário] --> C{Classifica intenção + tipo de projeto}
+    C -->|projeto novo| GF[Workflow greenfield]
+    C -->|projeto existente| BF[Descoberta brownfield]
+    C -->|bug / ajuste| SDC[Ciclo de dev da story - YOLO]
+    GF --> DOC[Pipeline doc-first]
+    BF --> DOC
+    DOC --> PRD[PRD] --> EPIC[Épico] --> STORY[Story - validada >= Ready] --> SPEC[Spec]
+    SPEC --> GATE{{Gate doc-first}}
+    SDC --> GATE
+    GATE -->|faltam docs| BLOCK[Bloqueado - produza os docs antes]
+    GATE -->|satisfeito| IMPL[Implementação - desenvolvedor]
+    IMPL --> QA[Gate de QA + loop de QA]
+    QA -->|passa| SHIP[Push / PR - só devops]
+    QA -->|falha| IMPL`,
+  },
+  'agent-routing': {
+    titulo: 'Roteamento de agente (delegação)',
+    proposito:
+      'Como um briefing chega no especialista certo. Orquestradores roteiam e coordenam; nunca executam o trabalho de domínio (Artigo VIII).',
+    mermaid: `sequenceDiagram
+    participant U as Usuário
+    participant I as Imperator (master -orqx)
+    participant S as Squad -orqx
+    participant A as Agente especialista
+    U->>I: briefing (linguagem natural)
+    I->>I: diagnostica domínio + tipo de projeto
+    alt trabalho de domínio
+        I->>S: delega (anuncia o plano, espera o "pode ir")
+        S->>A: roteia pro especialista
+        A-->>S: artefato / resultado
+        S-->>I: consolidado
+    else dev do framework
+        I->>A: roteia pro agente de framework (pm / architect / dev / qa)
+    end
+    I-->>U: resultado em linguagem de negócio (sem jargão interno)`,
+  },
+  'model-routing': {
+    titulo: 'Roteamento de modelo (o mais barato que resolve)',
+    proposito:
+      'Como cada tarefa escolhe o tier de modelo. O raciocínio pesado vai pra spec; a execução depois quase só lê um doc pronto, então economia de token é consequência.',
+    mermaid: `flowchart TD
+    T[Tarefa] --> K{Tipo?}
+    K -->|lint / rename / yaml / massa| H[haiku - esforço baixo]
+    K -->|feature da spec / review / bug / testes| SO[sonnet - alto]
+    K -->|arquivo único / factual| SM[sonnet - médio]
+    K -->|arquitetura cross-system / debug complexo| OP[opus - xhigh]
+    K -->|Spec Pipeline COMPLEX score >= 16| OM[opus - max]
+    H --> SP{>= 8 tool calls ou fan-out real?}
+    SO --> SP
+    SM --> SP
+    OP --> SP
+    OM --> SP
+    SP -->|sim| SUB[Spawna sub-agente]
+    SP -->|não| INLINE[Roda inline]`,
+  },
+  'doc-first': {
+    titulo: 'Enforcement doc-first',
+    proposito:
+      'O que torna impossível começar um projeto novo sem docs. O resolver responde o que falta; hooks bloqueiam escrita de código até existir PRD + épico + story.',
+    mermaid: `flowchart TD
+    W[Escreve/edita arquivo de código] --> EX{Path isento ou repo do framework?}
+    EX -->|sim| ALLOW[Libera]
+    EX -->|não| RES[doc-first-resolver: tipo, workflow, gate]
+    RES --> GF{Greenfield + gate não satisfeito?}
+    GF -->|não| STORY{Existe story Ready? - story-gate}
+    GF -->|sim, sem PRD/épico/story| DENY[BLOQUEIA - rode o fluxo greenfield antes]
+    STORY -->|sim| ALLOW
+    STORY -->|não| DENY2[BLOQUEIA - crie uma story]
+    DENY -.->|escape: SINAPSE_SKIP_DOCFIRST=1| ALLOW
+    OBS["sinapse route dá a mesma resposta (observabilidade)"]:::note
+    RES -. compartilha a lógica .- OBS
+    classDef note fill:#1c1c1c,stroke:#555,color:#aaa`,
+  },
+  'constitution-gates': {
+    titulo: 'Gates constitucionais por fase',
+    proposito:
+      'Onde cada artigo inegociável dispara ao longo do ciclo — a camada de enforcement que bloqueia violações automaticamente.',
+    mermaid: `flowchart LR
+    subgraph PLAN[Planejar]
+      A3[III Documentação-Primeiro]
+      A4[IV Sem Invenção]
+    end
+    subgraph BUILD[Construir]
+      A6[VI Imports Absolutos]
+      A8[VIII Delegação Obrigatória]
+      A10[X Segurança & Dados]
+    end
+    subgraph SHIP[Entregar]
+      A2[II Autoridade de Agente - só devops]
+      A5[V Qualidade Primeiro]
+      A9[IX Colaboração Segura]
+    end
+    subgraph ALWAYS[Transversais]
+      A1[I CLI Primeiro]
+      A7[VII Exatidão de Métricas]
+      A11[XI Default Conservador]
+    end
+    PLAN --> BUILD --> SHIP`,
+  },
+  'project-classification': {
+    titulo: 'Classificação de projeto para workflow',
+    proposito:
+      'Como a intenção mapeia pro workflow certo: site/lp/app vs plataforma/saas vs api/serviço, greenfield vs brownfield, ou um ajuste leve.',
+    mermaid: `flowchart TD
+    B[Briefing] --> N{Novo ou existente?}
+    N -->|existente, desconhecido| BD[brownfield-discovery]
+    N -->|existente, conhecido| FIX{Tamanho da mudança?}
+    N -->|novo| TYPE{Tipo de projeto?}
+    TYPE -->|site / lp / app| GUI[greenfield-ui]
+    TYPE -->|plataforma / saas| GFS[greenfield-fullstack]
+    TYPE -->|api / serviço| GSV[greenfield-service]
+    BD --> BTYPE{Tipo?}
+    BTYPE -->|ui| BUI[brownfield-ui]
+    BTYPE -->|fullstack| BFS[brownfield-fullstack]
+    BTYPE -->|serviço| BSV[brownfield-service]
+    FIX -->|bug / ajuste| YOLO[SDC - YOLO]
+    FIX -->|feature| SDCI[SDC - interativo]
+    FIX -->|complexo score >= 16| SPEC[Spec Pipeline antes]`,
+  },
+  'prompt-lifecycle': {
+    titulo: 'Cada prompt (o que dispara em toda mensagem)',
+    proposito:
+      'O que acontece em toda mensagem do usuário antes mesmo do modelo responder: hooks injetam grounding e a constituição, então cada turno já começa ciente da base de conhecimento do projeto, do design system, das leis de engenharia e das regras ativas.',
+    mermaid: `flowchart TD
+    P[Usuário envia um prompt] --> H[Hooks UserPromptSubmit disparam]
+    H --> VG[Grounding de conhecimento - contexto do projeto por domínio]
+    H --> DS[Grounding do design system - DS resolver por cwd]
+    H --> EG[Grounding de engenharia - leis + KIT por tema]
+    H --> SG[Grounding de squad - contexto curado da squad]
+    H --> CR[Constituição + bracket de contexto injetados]
+    VG --> M[Modelo recebe contexto enriquecido]
+    DS --> M
+    EG --> M
+    SG --> M
+    CR --> M
+    M --> ACT[Age: responde ou roteia pro especialista]`,
+  },
+  'session-start': {
+    titulo: 'Cada sessão (início seguro)',
+    proposito:
+      'A rede de segurança que roda antes de qualquer trabalho na sessão: sincroniza com o remoto, nunca toca na main, audita o que já existe para nunca sobrescrever trabalho parcial (Colaboração Segura + Inteligência de Projeto).',
+    mermaid: `flowchart TD
+    S[Sessão inicia] --> F[git fetch origin]
+    F --> SY{Main local atrasada?}
+    SY -->|sim, limpa| PULL[Pull fast-forward]
+    SY -->|divergiu| STOP[Para - resolve com segurança]
+    PULL --> BR[Cria feature branch automática - user/type/desc]
+    STOP --> BR
+    BR --> AUD[Auditoria de estado inicial - 8 dimensões]
+    AUD --> MAT{Maturidade?}
+    MAT -->|vazio| GREEN[Workflow greenfield]
+    MAT -->|parcial| CONT[Continua - nunca sobrescreve]
+    MAT -->|maduro| BROWN[Descoberta brownfield]
+    MAT -->|gerido-pelo-sinapse| RESUME[Retoma story ativa - SDC]`,
+  },
+  'orchestration-handoff': {
+    titulo: 'Cada orquestração (plano + handoff)',
+    proposito:
+      'Como o controle passa entre agentes sem inchar o contexto: o orquestrador planeja e então espera o "pode ir", e cada troca de agente compacta a persona anterior num artefato mínimo de handoff (~379 tokens) em vez de carregar tudo adiante.',
+    mermaid: `sequenceDiagram
+    participant U as Usuário
+    participant O as Orquestrador
+    participant A1 as Agente A (saindo)
+    participant A2 as Agente B (entrando)
+    O->>O: diagnostica + monta plano de orquestração
+    O->>U: apresenta o plano
+    U-->>O: pode ir
+    O->>A1: atribui trabalho (contexto isolado e mínimo)
+    A1->>A1: escreve artefato de handoff + scratchpad
+    A1-->>A2: handoff (story id, decisões, arquivos, próxima ação)
+    Note over A1,A2: persona completa descartada, ~379 tok mantidos
+    A2->>A2: lê o scratchpad, continua
+    A2-->>O: resultado destilado
+    O-->>U: síntese`,
+  },
+  'execution-cycle': {
+    titulo: 'Cada execução (ciclo de dev da story)',
+    proposito:
+      'O ciclo de vida da story depois que o gate doc-first é satisfeito: de rascunho a validada a implementada a revisada a entregue, com CodeRabbit se autocorrigindo no dev e o loop de QA antes do push (só @devops entrega).',
+    mermaid: `flowchart TD
+    D[Rascunho - sprint-lead] --> V{Valida - product-lead 10pt}
+    V -->|NÃO-VAI| D
+    V -->|VAI| R[Ready]
+    R --> IMP[InProgress - desenvolvedor]
+    IMP --> CRB[Autocorreção CodeRabbit - máx 2 iter]
+    CRB --> REV[InReview - quality-gate]
+    REV --> QL{Veredito do loop de QA}
+    QL -->|FALHA| IMP
+    QL -->|RESSALVAS| DOC[Documenta dívida]
+    QL -->|PASSA| PUSH[Push / PR - só devops]
+    DOC --> PUSH
+    PUSH --> DONE[Done]`,
+  },
+  'security-enforcement': {
+    titulo: 'Enforcement de segurança (transversal)',
+    proposito:
+      'Os guardrails sempre-ativos do commit à produção: segredos nunca são commitados, o acesso a dados é de menor privilégio e parametrizado, e nada chega na main sem PR (Artigos IX + X).',
+    mermaid: `flowchart TD
+    C[Pré-commit] --> SS{Varredura de segredos}
+    SS -->|segredo encontrado| BLK[Bloqueia - remove do staging]
+    SS -->|limpo| CM[Commit]
+    CM --> MRG[Merge origin/main - resolve conflitos]
+    MRG --> PR[PR obrigatório - branch protection]
+    PR --> CHK{Status checks + review}
+    CHK -->|falha| FIXS[Volta pra correção]
+    CHK -->|passa| SHIP[Merge]
+    DATA[Camada de dados] --> RLS[RLS em toda tabela de usuário]
+    DATA --> PAR[Só queries parametrizadas]
+    DATA --> ENV[Segredos no env, nunca no código]`,
+  },
+  'knowledge-memory': {
+    titulo: 'Conhecimento & memória (como se mantém atual)',
+    proposito:
+      'Como o framework se mantém grounded e autodocumentado: fontes de grounding alimentam cada turno, fatos duráveis persistem como dicas de memória, e o Atlas se regenera do disco para o mapa nunca divergir da realidade.',
+    mermaid: `flowchart TD
+    SRC[Fontes de grounding] --> VLT[Base de conhecimento - fonte de verdade do projeto]
+    SRC --> DSY[Design systems - DS do projeto]
+    SRC --> ENG[Pesquisa de engenharia - 60 domínios]
+    VLT --> TURN[Injetado a cada turno]
+    DSY --> TURN
+    ENG --> TURN
+    MEM[Arquivos de memória - dicas, não verdade] --> VERIFY[Verifica contra o código antes de agir]
+    ATL[sinapse atlas] --> SCAN[Varre o repo do disco - contagens exatas]
+    SCAN --> OUT[Regenera o mapa - md + html + json]
+    OUT --> NODRIFT[Fonte única, nunca diverge]`,
+  },
+};
+
+module.exports = { FRAMEWORK_FLOWS_PT };

package/.sinapse-ai/core/atlas/flows.js

@@ -0,0 +1,266 @@
+/**
+ * Framework Operating Flows — the meta-workflows of how SINAPSE itself runs.
+ *
+ * These are NOT development workflows (those live in docs/sinapse-workflows/).
+ * They are the framework's own mechanisms — agent routing, model routing, the
+ * doc-first enforcement chain, constitutional gates, project classification —
+ * authored as Mermaid diagrams. Both the markdown atlas and the HTML dashboard
+ * render them, so "how the framework works" is shown visually in one place.
+ *
+ * Kept as data (id, title, purpose, mermaid) so renderers stay dumb and the set
+ * is easy to extend. Mermaid is hand-written and kept simple (plain node labels,
+ * no reserved chars) so it renders everywhere.
+ *
+ * @module core/atlas/flows
+ */
+
+'use strict';
+
+/** @type {Array<{id:string,title:string,purpose:string,mermaid:string}>} */
+const FRAMEWORK_FLOWS = [
+  {
+    id: 'lifecycle',
+    title: 'End-to-end lifecycle',
+    purpose:
+      'The full spine a request travels: from briefing to shipped code, with the doc-first pipeline and gates in the middle.',
+    mermaid: `flowchart TD
+    U[User briefing] --> C{Classify intent + project type}
+    C -->|new project| GF[Greenfield workflow]
+    C -->|existing project| BF[Brownfield discovery]
+    C -->|bug / tweak| SDC[Story dev cycle - YOLO]
+    GF --> DOC[Doc-first pipeline]
+    BF --> DOC
+    DOC --> PRD[PRD] --> EPIC[Epic] --> STORY[Story - validated >= Ready] --> SPEC[Spec]
+    SPEC --> GATE{{Doc-first gate}}
+    SDC --> GATE
+    GATE -->|missing docs| BLOCK[Blocked - produce docs first]
+    GATE -->|satisfied| IMPL[Implementation - @developer]
+    IMPL --> QA[QA gate + QA loop]
+    QA -->|pass| SHIP[Push / PR - @devops only]
+    QA -->|fail| IMPL`,
+  },
+  {
+    id: 'agent-routing',
+    title: 'Agent routing (delegation)',
+    purpose:
+      'How a briefing reaches the right specialist. Orchestrators route and coordinate; they never execute domain work themselves (Article VIII).',
+    mermaid: `sequenceDiagram
+    participant U as User
+    participant I as Imperator (master -orqx)
+    participant S as Squad -orqx
+    participant A as Specialist agent
+    U->>I: briefing (natural language)
+    I->>I: diagnose domain + project type
+    alt domain work
+        I->>S: delegate (announce plan, await go)
+        S->>A: route to specialist
+        A-->>S: artifact / result
+        S-->>I: consolidated
+    else framework dev
+        I->>A: route to framework agent (pm / architect / dev / qa)
+    end
+    I-->>U: business-language result (no internal jargon)`,
+  },
+  {
+    id: 'model-routing',
+    title: 'Model routing (cheapest that solves it)',
+    purpose:
+      'How each task picks a model tier. Heavy thinking goes into the spec; execution then mostly reads a finished doc, so token economy is a consequence.',
+    mermaid: `flowchart TD
+    T[Task] --> K{Kind?}
+    K -->|lint / rename / yaml / bulk| H[haiku - low effort]
+    K -->|feature from spec / review / bug / tests| SO[sonnet - high]
+    K -->|single-file / factual| SM[sonnet - medium]
+    K -->|cross-system arch / complex debug / multi-file| OP[opus - xhigh]
+    K -->|Spec Pipeline COMPLEX score >= 16| OM[opus - max]
+    H --> SP{>= 8 tool calls or real fan-out?}
+    SO --> SP
+    SM --> SP
+    OP --> SP
+    OM --> SP
+    SP -->|yes| SUB[Spawn sub-agent]
+    SP -->|no| INLINE[Run inline]`,
+  },
+  {
+    id: 'doc-first',
+    title: 'Doc-first enforcement',
+    purpose:
+      'What makes it impossible to start a new project without docs. The resolver answers what is missing; hooks block code writes until PRD + epic + story exist.',
+    mermaid: `flowchart TD
+    W[Write/Edit a code file] --> EX{Exempt path or framework repo?}
+    EX -->|yes| ALLOW[Allow]
+    EX -->|no| RES[doc-first-resolver: type, workflow, gate]
+    RES --> GF{Greenfield + gate unsatisfied?}
+    GF -->|no| STORY{Ready story exists? - story-gate}
+    GF -->|yes, no PRD/epic/story| DENY[BLOCK - run greenfield flow first]
+    STORY -->|yes| ALLOW
+    STORY -->|no| DENY2[BLOCK - create a story]
+    DENY -.->|escape: SINAPSE_SKIP_DOCFIRST=1| ALLOW
+    OBS["sinapse route gives the same answer (observability)"]:::note
+    RES -. shares logic .- OBS
+    classDef note fill:#1c1c1c,stroke:#555,color:#aaa`,
+  },
+  {
+    id: 'constitution-gates',
+    title: 'Constitutional gates by phase',
+    purpose:
+      'Where each non-negotiable article fires across the lifecycle — the enforcement layer that blocks violations automatically.',
+    mermaid: `flowchart LR
+    subgraph PLAN[Plan]
+      A3[III Documentation-First]
+      A4[IV No Invention]
+    end
+    subgraph BUILD[Build]
+      A6[VI Absolute Imports]
+      A8[VIII Mandatory Delegation]
+      A10[X Security & Data]
+    end
+    subgraph SHIP[Ship]
+      A2[II Agent Authority - devops only]
+      A5[V Quality First]
+      A9[IX Safe Collaboration]
+    end
+    subgraph ALWAYS[Cross-cutting]
+      A1[I CLI First]
+      A7[VII Metrics Accuracy]
+      A11[XI Conservative Default]
+    end
+    PLAN --> BUILD --> SHIP`,
+  },
+  {
+    id: 'project-classification',
+    title: 'Project classification to workflow',
+    purpose:
+      'How intent maps to the right workflow: site/lp/app vs platform/saas vs api/service, greenfield vs brownfield, or a light fix.',
+    mermaid: `flowchart TD
+    B[Briefing] --> N{New or existing?}
+    N -->|existing, unknown| BD[brownfield-discovery]
+    N -->|existing, known| FIX{Change size?}
+    N -->|new| TYPE{Project type?}
+    TYPE -->|site / lp / app| GUI[greenfield-ui]
+    TYPE -->|platform / saas| GFS[greenfield-fullstack]
+    TYPE -->|api / service| GSV[greenfield-service]
+    BD --> BTYPE{Type?}
+    BTYPE -->|ui| BUI[brownfield-ui]
+    BTYPE -->|fullstack| BFS[brownfield-fullstack]
+    BTYPE -->|service| BSV[brownfield-service]
+    FIX -->|bug / tweak| YOLO[SDC - YOLO]
+    FIX -->|feature| SDCI[SDC - interactive]
+    FIX -->|complex score >= 16| SPEC[Spec Pipeline first]`,
+  },
+  {
+    id: 'prompt-lifecycle',
+    title: 'Every prompt (what fires on each message)',
+    purpose:
+      'What happens on every single user message before the model even answers: hooks inject grounding and the constitution, so each turn starts already aware of the project knowledge base, design system, engineering laws and the active rules.',
+    mermaid: `flowchart TD
+    P[User sends a prompt] --> H[UserPromptSubmit hooks fire]
+    H --> VG[Knowledge grounding - project context by domain]
+    H --> DS[Design system grounding - DS resolver by cwd]
+    H --> EG[Engineering grounding - laws + KIT by topic]
+    H --> SG[Squad grounding - curated squad context]
+    H --> CR[Constitution + context bracket injected]
+    VG --> M[Model receives enriched context]
+    DS --> M
+    EG --> M
+    SG --> M
+    CR --> M
+    M --> ACT[Act: answer or route to specialist]`,
+  },
+  {
+    id: 'session-start',
+    title: 'Every session (safe start)',
+    purpose:
+      'The safety net that runs before any work in a session: sync with remote, never touch main, audit what already exists so partial work is never overwritten (Safe Collaboration + Project Intelligence).',
+    mermaid: `flowchart TD
+    S[Session starts] --> F[git fetch origin]
+    F --> SY{Local main behind?}
+    SY -->|yes, clean| PULL[Fast-forward pull]
+    SY -->|diverged| STOP[Stop - resolve safely]
+    PULL --> BR[Auto-create feature branch - user/type/desc]
+    STOP --> BR
+    BR --> AUD[Initial state audit - 8 dimensions]
+    AUD --> MAT{Maturity?}
+    MAT -->|empty| GREEN[Greenfield workflow]
+    MAT -->|partial| CONT[Continue - never overwrite]
+    MAT -->|mature| BROWN[Brownfield discovery]
+    MAT -->|sinapse-managed| RESUME[Resume active story - SDC]`,
+  },
+  {
+    id: 'orchestration-handoff',
+    title: 'Every orchestration (plan + handoff)',
+    purpose:
+      'How control passes between agents without context bloat: the orchestrator plans then waits for go, and each agent switch compacts the previous persona into a tiny handoff artifact (~379 tokens) instead of carrying it all forward.',
+    mermaid: `sequenceDiagram
+    participant U as User
+    participant O as Orchestrator
+    participant A1 as Agent A (outgoing)
+    participant A2 as Agent B (incoming)
+    O->>O: diagnose + build orchestration plan
+    O->>U: present plan
+    U-->>O: go
+    O->>A1: assign work (isolated, minimal context)
+    A1->>A1: write handoff artifact + scratchpad
+    A1-->>A2: handoff (story id, decisions, files, next action)
+    Note over A1,A2: full persona discarded, ~379 tok kept
+    A2->>A2: read scratchpad, continue
+    A2-->>O: distilled result
+    O-->>U: synthesis`,
+  },
+  {
+    id: 'execution-cycle',
+    title: 'Every execution (story dev cycle)',
+    purpose:
+      'The story lifecycle once the doc-first gate is satisfied: draft to validated to implemented to reviewed to shipped, with CodeRabbit self-healing in dev and the QA loop before push (only @devops ships).',
+    mermaid: `flowchart TD
+    D[Draft - sprint-lead] --> V{Validate - product-lead 10pt}
+    V -->|NO-GO| D
+    V -->|GO| R[Ready]
+    R --> IMP[InProgress - developer]
+    IMP --> CRB[CodeRabbit self-heal - max 2 iter]
+    CRB --> REV[InReview - quality-gate]
+    REV --> QL{QA loop verdict}
+    QL -->|FAIL| IMP
+    QL -->|CONCERNS| DOC[Document debt]
+    QL -->|PASS| PUSH[Push / PR - devops only]
+    DOC --> PUSH
+    PUSH --> DONE[Done]`,
+  },
+  {
+    id: 'security-enforcement',
+    title: 'Security enforcement (cross-cutting)',
+    purpose:
+      'The always-on guardrails from commit to production: secrets never get committed, data access is least-privilege and parameterized, and nothing reaches main without a PR (Articles IX + X).',
+    mermaid: `flowchart TD
+    C[Pre-commit] --> SS{Secret scan}
+    SS -->|secret found| BLK[Block - remove from staging]
+    SS -->|clean| CM[Commit]
+    CM --> MRG[Merge origin/main - resolve conflicts]
+    MRG --> PR[PR required - branch protection]
+    PR --> CHK{Status checks + review}
+    CHK -->|fail| FIXS[Return for fixes]
+    CHK -->|pass| SHIP[Merge]
+    DATA[Data layer] --> RLS[RLS on every user table]
+    DATA --> PAR[Parameterized queries only]
+    DATA --> ENV[Secrets in env, never in code]`,
+  },
+  {
+    id: 'knowledge-memory',
+    title: 'Knowledge & memory (how it stays current)',
+    purpose:
+      'How the framework keeps itself grounded and self-documenting: grounding sources feed every turn, durable facts persist as memory hints, and the Atlas regenerates from disk so the map never drifts from reality.',
+    mermaid: `flowchart TD
+    SRC[Grounding sources] --> VLT[Knowledge base - project source of truth]
+    SRC --> DSY[Design systems - project DS]
+    SRC --> ENG[Engineering research - 60 domains]
+    VLT --> TURN[Injected every turn]
+    DSY --> TURN
+    ENG --> TURN
+    MEM[Memory files - hints, not truth] --> VERIFY[Verify vs codebase before acting]
+    ATL[sinapse atlas] --> SCAN[Scan repo from disk - exact counts]
+    SCAN --> OUT[Regenerate map - md + html + json]
+    OUT --> NODRIFT[Single source, never drifts]`,
+  },
+];
+
+module.exports = { FRAMEWORK_FLOWS };

package/.sinapse-ai/core/atlas/index.js

@@ -0,0 +1,62 @@
+/**
+ * Atlas — generate the Framework Operating Atlas (data + LLM-readable markdown).
+ *
+ * One source of truth (atlas-data) → multiple renderings. This module writes:
+ *   - docs/framework/atlas/atlas-data.json   (structured data; HTML dashboard + tooling consume it)
+ *   - docs/framework/atlas/OPERATING-ATLAS.md (LLM-readable atlas)
+ *
+ * CLI-first (Article I): exposed as `sinapse atlas`.
+ *
+ * @module core/atlas
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const { buildAtlasData } = require('./atlas-data');
+const { renderAtlasMarkdown } = require('./render-markdown');
+const { renderAtlasHtml } = require('./render-html');
+
+const OUT_DIR = path.join('docs', 'framework', 'atlas');
+
+/**
+ * Generate the atlas artifacts.
+ * @param {object} [opts]
+ * @param {string} [opts.root=process.cwd()] - Repo root.
+ * @param {string} [opts.generatedAt] - ISO timestamp to stamp into outputs.
+ * @param {boolean} [opts.write=true] - Write files to disk.
+ * @returns {{ data: object, markdown: string, paths: {json:string, md:string} }}
+ */
+function generateAtlas(opts = {}) {
+  const root = opts.root || process.cwd();
+  const data = buildAtlasData({ root, generatedAt: opts.generatedAt || null });
+  const markdown = renderAtlasMarkdown(data);
+  const html = renderAtlasHtml(data);
+
+  const outDir = path.join(root, OUT_DIR);
+  const jsonPath = path.join(outDir, 'atlas-data.json');
+  const mdPath = path.join(outDir, 'OPERATING-ATLAS.md');
+  const htmlPath = path.join(outDir, 'atlas.html');
+
+  if (opts.write !== false) {
+    fs.mkdirSync(outDir, { recursive: true });
+    fs.writeFileSync(jsonPath, JSON.stringify(data, null, 2) + '\n');
+    fs.writeFileSync(mdPath, markdown);
+    fs.writeFileSync(htmlPath, html);
+  }
+
+  return {
+    data,
+    markdown,
+    html,
+    paths: {
+      json: path.relative(root, jsonPath),
+      md: path.relative(root, mdPath),
+      html: path.relative(root, htmlPath),
+    },
+  };
+}
+
+module.exports = { generateAtlas, buildAtlasData, renderAtlasMarkdown };