npm - sinapse-ai - Versions diffs - 1.15.0 → 1.17.0 - Mend

sinapse-ai 1.15.0 → 1.17.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (39) hide show

package/.claude/hooks/doc-first-gate.cjs +156 -0
package/.claude/hooks/enforce-story-gate.cjs +6 -2
package/.claude/rules/hook-governance.md +1 -0
package/.sinapse-ai/constitution.md +1 -1
package/.sinapse-ai/core/atlas/atlas-data.js +278 -0
package/.sinapse-ai/core/atlas/flows-pt.js +253 -0
package/.sinapse-ai/core/atlas/flows.js +266 -0
package/.sinapse-ai/core/atlas/index.js +62 -0
package/.sinapse-ai/core/atlas/render-html.js +216 -0
package/.sinapse-ai/core/atlas/render-markdown.js +313 -0
package/.sinapse-ai/core/atlas/render-research-card.js +164 -0
package/.sinapse-ai/core/orchestration/build-command.js +136 -0
package/.sinapse-ai/core/orchestration/doc-first-resolver.js +322 -0
package/.sinapse-ai/core/orchestration/route-command.js +97 -0
package/.sinapse-ai/data/entity-registry.yaml +113 -16
package/.sinapse-ai/development/agents/snps-orqx.md +9 -0
package/.sinapse-ai/development/tasks/create-doc.md +1 -1
package/.sinapse-ai/development/tasks/create-next-story.md +2 -3
package/.sinapse-ai/development/tasks/spec-analyze.md +460 -0
package/.sinapse-ai/development/tasks/spec-clarify.md +374 -0
package/.sinapse-ai/development/tasks/spec-gather-requirements.md +11 -0
package/.sinapse-ai/development/templates/approval-table.md +106 -0
package/.sinapse-ai/development/workflows/spec-pipeline.yaml +122 -7
package/.sinapse-ai/install-manifest.yaml +70 -18
package/.sinapse-ai/product/templates/prd-tmpl.yaml +6 -2
package/.sinapse-ai/product/templates/spec-tmpl.md +18 -0
package/AGENTS.md +1 -1
package/CHANGELOG.md +18 -3
package/bin/sinapse.js +121 -0
package/docs/framework/atlas/OPERATING-ATLAS.md +537 -0
package/docs/framework/atlas/README.md +34 -0
package/docs/framework/atlas/atlas-data.json +2810 -0
package/docs/framework/atlas/atlas.html +392 -0
package/package.json +1 -1
package/packages/installer/src/wizard/ide-config-generator.js +6 -0
package/scripts/install-chrome-brain.sh +2 -2
package/scripts/validate-no-personal-leaks.js +24 -9
package/squads/squad-copy/knowledge-base/consequence-headline-patterns.md +2 -2
package/docs/guides/hooks-two-layers.md +0 -66

package/.sinapse-ai/core/atlas/render-html.js ADDED Viewed

@@ -0,0 +1,216 @@
+/**
+ * Atlas → HTML dashboard renderer (visual).
+ *
+ * Produces a single self-contained HTML file (data embedded) with the same
+ * atlas data as the markdown atlas: at-a-glance counts, the operating-model
+ * Mermaid diagram, and searchable/filterable tables for workflows, agents,
+ * squads, the constitution, and rules. SINAPSE B&W aesthetic. No build step,
+ * no server — open the file.
+ *
+ * @module core/atlas/render-html
+ */
+'use strict';
+function esc(s) {
+  return String(s == null ? '' : s)
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}
+function renderAtlasHtml(d) {
+  const c = d.counts;
+  const stamp = d.generatedAt ? `Generated ${esc(d.generatedAt)}` : '';
+  const dataJson = JSON.stringify(d).replace(/</g, '\\u003c');
+  const stat = (n, label) => `<div class="stat"><b>${n}</b><span>${label}</span></div>`;
+  const flowsSection = (d.flows || [])
+    .map(
+      (f) => `<h3 style="margin:1.6rem 0 .3rem">${esc(f.title)}</h3>
+    <p class="lead">${esc(f.purpose)}</p>
+    <div class="mermaid">
+${esc(f.mermaid)}
+    </div>`,
+    )
+    .join('\n');
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<title>SINAPSE · Framework Operating Atlas</title>
+<script src="https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.min.js"></script>
+<style>
+  :root{
+    --bg:#0a0a0a; --fg:#f5f5f0; --mut:#8a8a85; --line:#222; --card:#121212; --accent:#f5f5f0;
+    --font:'Inter',system-ui,-apple-system,Segoe UI,Roboto,sans-serif;
+    --mono:'JetBrains Mono',ui-monospace,SFMono-Regular,Menlo,monospace;
+  }
+  *{box-sizing:border-box}
+  body{margin:0;background:var(--bg);color:var(--fg);font-family:var(--font);line-height:1.5;
+    background-image:radial-gradient(rgba(255,255,255,.025) 1px,transparent 1px);background-size:3px 3px}
+  .wrap{max-width:min(1400px,94vw);margin:0 auto;padding:clamp(1.5rem,4vw,3rem) 0 5rem}
+  h1{font-size:clamp(1.6rem,4vw,2.6rem);font-weight:800;letter-spacing:-.02em;margin:0 0 .25rem}
+  .sub{color:var(--mut);font-family:var(--mono);font-size:.8rem;margin-bottom:2rem}
+  .stats{display:flex;flex-wrap:wrap;gap:.6rem;margin-bottom:2rem}
+  .stat{background:var(--card);border:1px solid var(--line);border-radius:10px;padding:.7rem 1rem;min-width:96px}
+  .stat b{display:block;font-size:1.5rem;font-weight:800;font-family:var(--mono)}
+  .stat span{color:var(--mut);font-size:.72rem;text-transform:uppercase;letter-spacing:.06em}
+  nav{display:flex;flex-wrap:wrap;gap:.4rem;margin-bottom:1.5rem;position:sticky;top:0;
+    background:linear-gradient(var(--bg),var(--bg) 70%,transparent);padding:.6rem 0;z-index:5}
+  nav button{background:transparent;color:var(--mut);border:1px solid var(--line);border-radius:999px;
+    padding:.35rem .9rem;font-family:var(--mono);font-size:.78rem;cursor:pointer;transition:.15s}
+  nav button:hover{color:var(--fg);border-color:#444}
+  nav button.on{background:var(--fg);color:var(--bg);border-color:var(--fg)}
+  section{display:none;animation:fade .2s ease}
+  section.on{display:block}
+  @keyframes fade{from{opacity:0;transform:translateY(4px)}to{opacity:1;transform:none}}
+  h2{font-size:1.2rem;font-weight:700;margin:0 0 1rem;letter-spacing:-.01em}
+  .mermaid{background:var(--card);border:1px solid var(--line);border-radius:12px;padding:1.5rem;margin-bottom:1.5rem}
+  .ctrl{display:flex;gap:.6rem;flex-wrap:wrap;margin-bottom:1rem}
+  input,select{background:var(--card);color:var(--fg);border:1px solid var(--line);border-radius:8px;
+    padding:.5rem .8rem;font-family:var(--mono);font-size:.82rem}
+  input{flex:1;min-width:200px}
+  table{width:100%;border-collapse:collapse;font-size:.82rem}
+  th,td{text-align:left;padding:.55rem .7rem;border-bottom:1px solid var(--line);vertical-align:top}
+  th{color:var(--mut);font-family:var(--mono);font-size:.7rem;text-transform:uppercase;letter-spacing:.06em;
+    position:sticky;top:3.4rem;background:var(--bg);cursor:pointer}
+  td code{font-family:var(--mono);font-size:.78rem;color:var(--fg);background:#1c1c1c;padding:.1rem .35rem;border-radius:4px}
+  .tag{font-family:var(--mono);font-size:.68rem;padding:.1rem .45rem;border-radius:999px;border:1px solid var(--line);color:var(--mut)}
+  .nn{color:#fff;border-color:#555}
+  .count{color:var(--mut);font-family:var(--mono);font-size:.75rem;margin-bottom:.6rem}
+  p.lead{color:var(--mut);max-width:70ch;margin:0 0 1.2rem}
+  a{color:var(--fg)}
+</style>
+</head>
+<body>
+<div class="wrap">
+  <h1>SINAPSE · Framework Operating Atlas</h1>
+  <div class="sub">How the framework works — routing, models, constitution, workflows, agents, squads. ${stamp}</div>
+  <div class="stats">
+    ${stat(c.squads, 'squads')}
+    ${stat(c.agentsTotal, 'agents')}
+    ${stat(c.orqx, 'orchestrators')}
+    ${stat(c.workflowsTotal, 'workflows')}
+    ${stat(c.articles, 'articles')}
+    ${stat(c.rules, 'rules')}
+  </div>
+  <nav id="nav"></nav>
+  <section id="s-model" class="on">
+    <h2>Operating model</h2>
+    <p class="lead">Every briefing flows through the same spine: the Imperator routes to a squad orchestrator or framework agent, the doc-first pipeline turns intent into PRD → Epic → Story → Spec, gates block code without docs, then implementation → QA → ship.</p>
+    <div class="mermaid">
+flowchart TD
+    U[User briefing] --> I[Imperator · master orchestrator]
+    I -->|classify intent + project type| R{Route}
+    R -->|domain work| SQ[Squad orchestrator -orqx]
+    R -->|framework dev| FW[Framework agents]
+    SQ --> SP[Squad specialist]
+    FW --> DOC[Doc-first pipeline]
+    SP --> DOC
+    DOC -->|PRD - Epic - Story - Spec| GATE{{Gates}}
+    GATE -->|pass| EXEC[Implementation]
+    GATE -->|fail| BLOCK[Blocked: produce docs first]
+    EXEC --> QA[Quality gate] --> SHIP[Push / PR]
+    </div>
+  </section>
+  <section id="s-flows">
+    <h2>Framework flows</h2>
+    <p class="lead">How each mechanism of the framework runs — routing, models, doc-first enforcement, gates, project classification. The meta-workflows behind the machine.</p>
+    ${flowsSection}
+  </section>
+  <section id="s-constitution"><h2>Constitution · ${c.articles} articles</h2><div id="t-constitution"></div></section>
+  <section id="s-workflows"><h2>Workflows · ${c.workflowsTotal}</h2>
+    <div class="ctrl"><input id="q-workflows" placeholder="search workflows…"><select id="f-workflows-src"><option value="">all sources</option><option value="framework">framework</option><option value="squad">squad</option></select></div>
+    <div class="count" id="c-workflows"></div><div id="t-workflows"></div></section>
+  <section id="s-agents"><h2>Agents · ${c.agentsTotal}</h2>
+    <div class="ctrl"><input id="q-agents" placeholder="search agents…"><select id="f-agents-squad"></select><label style="color:var(--mut);font-family:var(--mono);font-size:.78rem;display:flex;align-items:center;gap:.4rem"><input type="checkbox" id="f-agents-orqx" style="flex:none">orchestrators only</label></div>
+    <div class="count" id="c-agents"></div><div id="t-agents"></div></section>
+  <section id="s-squads"><h2>Squads · ${c.squads}</h2><div id="t-squads"></div></section>
+  <section id="s-rules"><h2>Rules · ${c.rules}</h2><div id="t-rules"></div></section>
+</div>
+<script id="atlas-data" type="application/json">${dataJson}</script>
+<script>
+const D = JSON.parse(document.getElementById('atlas-data').textContent);
+// startOnLoad:false — Mermaid renders diagrams in display:none sections at zero
+// width. We render each section's diagrams the first time its tab is shown.
+try{ mermaid.initialize({startOnLoad:false,theme:'dark',themeVariables:{background:'#121212',primaryColor:'#1c1c1c',primaryTextColor:'#f5f5f0',lineColor:'#555'}}); }catch(e){}
+function renderDiagrams(sectionId){
+  try{
+    const nodes=[...document.querySelectorAll('#'+sectionId+' .mermaid:not([data-processed])')];
+    if(nodes.length&&window.mermaid&&mermaid.run) mermaid.run({nodes});
+  }catch(e){}
+}
+const TABS=[['s-model','Operating model'],['s-flows','Flows'],['s-constitution','Constitution'],['s-workflows','Workflows'],['s-agents','Agents'],['s-squads','Squads'],['s-rules','Rules']];
+const nav=document.getElementById('nav');
+TABS.forEach(([id,label],i)=>{const b=document.createElement('button');b.textContent=label;if(i===0)b.className='on';
+  b.onclick=()=>{document.querySelectorAll('nav button').forEach(x=>x.classList.remove('on'));b.classList.add('on');
+    document.querySelectorAll('section').forEach(s=>s.classList.remove('on'));document.getElementById(id).classList.add('on');
+    renderDiagrams(id);};
+  nav.appendChild(b);});
+renderDiagrams('s-model'); // initial visible tab
+function tbl(cols,rows){return '<table><thead><tr>'+cols.map(c=>'<th>'+c+'</th>').join('')+'</tr></thead><tbody>'+
+  rows.map(r=>'<tr>'+r.map(c=>'<td>'+c+'</td>').join('')+'</tr>').join('')+'</tbody></table>';}
+const code=s=>'<code>'+(s||'')+'</code>';
+const sev=s=>'<span class="tag'+(/NON-NEGOTIABLE/.test(s)?' nn':'')+'">'+s+'</span>';
+document.getElementById('t-constitution').innerHTML=tbl(['Art.','Principle','Severity'],
+  D.articles.map(a=>[a.number,a.title,sev(a.severity)]));
+document.getElementById('t-squads').innerHTML=tbl(['Squad','Name','Agents','Workflows','Orchestrators'],
+  D.squads.map(s=>[code(s.id),s.name,s.agents,s.workflows,(s.orqx||[]).map(code).join(' ')||'—']));
+document.getElementById('t-rules').innerHTML=tbl(['Rule','Governs'],
+  D.rules.map(r=>[code(r.id),r.title]));
+// Workflows (search + source filter)
+function renderWorkflows(){
+  const q=(document.getElementById('q-workflows').value||'').toLowerCase();
+  const src=document.getElementById('f-workflows-src').value;
+  const rows=D.workflows.filter(w=>{
+    const isFw=w.source==='framework';
+    if(src==='framework'&&!isFw)return false; if(src==='squad'&&isFw)return false;
+    return !q||(w.id+' '+w.name+' '+(w.description||'')+' '+(w.squad||'')).toLowerCase().includes(q);
+  });
+  document.getElementById('c-workflows').textContent=rows.length+' of '+D.workflows.length;
+  document.getElementById('t-workflows').innerHTML=tbl(['Workflow','Source','Type','Description'],
+    rows.map(w=>[code(w.id),w.squad?code(w.squad):'<span class="tag">framework</span>',w.type||'—',w.description||'—']));
+}
+['q-workflows','f-workflows-src'].forEach(id=>document.getElementById(id).addEventListener('input',renderWorkflows));
+// Agents (search + squad filter + orqx toggle)
+const squads=[...new Set(D.agents.map(a=>a.squad))].sort();
+const sel=document.getElementById('f-agents-squad');
+sel.innerHTML='<option value="">all squads</option>'+squads.map(s=>'<option>'+s+'</option>').join('');
+function renderAgents(){
+  const q=(document.getElementById('q-agents').value||'').toLowerCase();
+  const sq=sel.value; const onlyOrqx=document.getElementById('f-agents-orqx').checked;
+  const rows=D.agents.filter(a=>{
+    if(sq&&a.squad!==sq)return false; if(onlyOrqx&&!a.isOrqx)return false;
+    return !q||(a.id+' '+(a.persona||'')+' '+(a.role||a.title||'')+' '+a.squad).toLowerCase().includes(q);
+  });
+  document.getElementById('c-agents').textContent=rows.length+' of '+D.agents.length;
+  document.getElementById('t-agents').innerHTML=tbl(['Agent','Persona','Squad','Role',''],
+    rows.map(a=>[code(a.id),a.persona||'—',code(a.squad),a.role||a.title||'—',a.isOrqx?'<span class="tag nn">orqx</span>':'']));
+}
+['q-agents','f-agents-orqx'].forEach(id=>document.getElementById(id).addEventListener('input',renderAgents));
+sel.addEventListener('change',renderAgents);
+renderWorkflows();renderAgents();
+</script>
+</body>
+</html>`;
+}
+module.exports = { renderAtlasHtml };

package/.sinapse-ai/core/atlas/render-markdown.js ADDED Viewed

@@ -0,0 +1,313 @@
+/**
+ * Atlas → Markdown renderer (LLM-readable).
+ *
+ * Produces a single, dense, navigable document describing how the SINAPSE
+ * framework operates — optimized to be read top-to-bottom by an LLM or a human.
+ * The narrative "operating model" sections are authored here; the catalogs
+ * (constitution, workflows, agents, squads, rules) are generated from the live
+ * atlas data so counts and lists never drift (Article VII).
+ *
+ * @module core/atlas/render-markdown
+ */
+'use strict';
+function h(s) {
+  return String(s == null ? '' : s).replace(/\|/g, '\\|').replace(/\r?\n/g, ' ').trim();
+}
+// ───────────────────────────────────────────────────────────────────────────
+// Operating-model narrative (authored — the connective tissue)
+// ───────────────────────────────────────────────────────────────────────────
+function operatingModel(d) {
+  const c = d.counts;
+  return `## 1. How SINAPSE works (operating model)
+SINAPSE is a **meta-framework**: it does not run application code itself — it
+orchestrates AI agents (inside Claude Code / Codex) through a governed pipeline.
+Every user request flows through the same spine:
+\`\`\`mermaid
+flowchart TD
+    U[User briefing] --> I[Imperator · master orchestrator]
+    I -->|classify intent + project type| R{Route}
+    R -->|domain work| SQ[Squad orchestrator -orqx]
+    R -->|framework dev| FW[Framework agents pm/architect/dev/qa/...]
+    SQ --> SP[Squad specialist agent]
+    FW --> DOC[Doc-first pipeline]
+    SP --> DOC
+    DOC -->|PRD -> Epic -> Story -> Spec| GATE{{Gates}}
+    GATE -->|pass| EXEC[Implementation]
+    GATE -->|fail| BLOCK[Blocked — produce docs first]
+    EXEC --> QA[Quality gate] --> SHIP[Push / PR · devops only]
+\`\`\`
+**Two routing decisions happen up front, both deterministic in spirit:**
+1. **Agent routing** — the Imperator (master \`-orqx\`) absorbs the briefing,
+   diagnoses the domain, and **delegates** to the right squad orchestrator,
+   which in turn routes to a specialist. Orchestrators never execute domain work
+   themselves (Article VIII — Mandatory Delegation). There are **${c.orqx}
+   orchestrators** (${c.squads} squad + 1 master) fronting **${c.agentsTotal}
+   agents** across **${c.squads} squads**.
+2. **Model routing** — each task picks the cheapest model that solves it
+   (haiku → sonnet → opus), escalating only when needed. Documentation/spec work
+   spends the tokens; execution then just reads the finished doc (see §4).
+**Documentation-First is the law** (Article III). No project reaches code without
+its planning documents. A briefing like "build a site" is forced through:
+\`\`\`
+brief → PRD → Epic → Story (validated, status ≥ Ready) → Spec → implementation
+\`\`\`
+The pipeline produces scannable approval tables in the terminal (requirements,
+epics, stories) and is guarded so that a brand-new project cannot start coding
+with no PRD / epic / story. Observability: \`sinapse route "<brief>"\` prints,
+for any project, its type → workflow → which documents are missing → whether the
+gate is satisfied — i.e. *exactly where it is breaking*.
+This atlas is itself generated by \`sinapse atlas\`; its counts are read from disk,
+so they are always exact.`;
+}
+function modelRouting() {
+  return `## 4. Model routing (cheapest model that solves it)
+The token economy is a consequence of the pipeline: heavy thinking goes into the
+PRD/spec, so execution mostly *reads a finished document* instead of reasoning.
+| Task | Model | Effort |
+|---|---|---|
+| Cross-system architecture, complex debug, multi-file refactor | **opus** | xhigh |
+| Spec Pipeline COMPLEX (score ≥ 16) | **opus** | max |
+| Feature from spec, code review, bug fix, tests, stories | **sonnet** | high |
+| Single-file analysis, factual question | **sonnet** | medium |
+| Lint, rename, YAML, lookup, bulk | **haiku** | low |
+Rule of thumb: when in doubt, drop a tier and escalate only on failure. A
+sub-agent is only spawned for real parallel fan-out (≥ 8 tool calls), otherwise
+work runs inline. *(Source of truth: \`.claude/rules/token-economy.md\`.)*`;
+}
+// ───────────────────────────────────────────────────────────────────────────
+// Generated catalogs
+// ───────────────────────────────────────────────────────────────────────────
+function constitutionTable(d) {
+  const rows = d.articles
+    .map((a) => `| ${a.number} | ${h(a.title)} | ${h(a.severity)} |`)
+    .join('\n');
+  return `## 3. Constitution — the ${d.counts.articles} articles
+Gates automatically block violations of NON-NEGOTIABLE / MUST articles.
+*(Source of truth: \`.sinapse-ai/constitution.md\`.)*
+| Art. | Principle | Severity |
+|---|---|---|
+${rows}`;
+}
+function rulesTable(d) {
+  const rows = d.rules.map((r) => `| \`${h(r.id)}\` | ${h(r.title)} |`).join('\n');
+  return `## 5. Non-negotiable rules (${d.counts.rules})
+Loaded automatically by the harness. *(Source: \`.claude/rules/\`.)*
+| Rule | What it governs |
+|---|---|
+${rows}`;
+}
+function workflowCatalog(d) {
+  const fw = d.workflows.filter((w) => w.source === 'framework');
+  const sq = d.workflows.filter((w) => w.source !== 'framework');
+  const fwRows = fw
+    .map((w) => `| \`${h(w.id)}\` | ${h(w.type) || '—'} | ${h(w.description) || '—'} |`)
+    .join('\n');
+  // group squad workflows by squad
+  const bySquad = {};
+  for (const w of sq) (bySquad[w.squad] = bySquad[w.squad] || []).push(w);
+  const sqRows = Object.keys(bySquad)
+    .sort()
+    .map((s) => `| \`${h(s)}\` | ${bySquad[s].map((w) => `\`${h(w.id)}\``).join(', ')} |`)
+    .join('\n');
+  return `## 6. Workflow catalog (${d.counts.workflowsTotal} total)
+**${d.counts.frameworkWorkflows} framework workflows** + **${d.counts.squadWorkflows}
+squad workflows**. The 13 primary framework workflows have detailed docs in
+\`docs/sinapse-workflows/\`.
+### Framework workflows (${fw.length})
+| Workflow | Type | Description |
+|---|---|---|
+${fwRows}
+### Squad workflows (${sq.length}, grouped by squad)
+| Squad | Workflows |
+|---|---|
+${sqRows}`;
+}
+function agentsSquadsMap(d) {
+  const orqxRows = d.agents
+    .filter((a) => a.isOrqx)
+    .sort((a, b) => a.squad.localeCompare(b.squad))
+    .map((a) => `| \`${h(a.id)}\` | ${h(a.persona) || '—'} | ${h(a.squad)} | ${h(a.role || a.title) || '—'} |`)
+    .join('\n');
+  const squadRows = d.squads
+    .map((s) => `| \`${h(s.id)}\` | ${h(s.name)} | ${s.agents} | ${s.workflows} | ${s.orqx.map((o) => `\`${h(o)}\``).join(', ') || '—'} |`)
+    .join('\n');
+  return `## 7. Agents & squads map
+**${d.counts.agentsTotal} agents** = ${d.counts.frameworkAgents} framework +
+${d.counts.squadAgents} squad, fronted by **${d.counts.orqx} orchestrators**.
+### Orchestrators (${d.counts.orqx}) — the routing layer
+| Orchestrator | Persona | Squad | Role |
+|---|---|---|---|
+${orqxRows}
+### Squads (${d.counts.squads})
+| Squad | Name | Agents | Workflows | Orchestrator(s) |
+|---|---|---|---|---|
+${squadRows}
+> The full ${d.counts.agentsTotal}-agent index is in the generated
+> \`atlas-data.json\` (one object per agent, with file path and role).`;
+}
+// ───────────────────────────────────────────────────────────────────────────
+// Routing detail (authored §2)
+// ───────────────────────────────────────────────────────────────────────────
+function routingDetail() {
+  return `## 2. Agent routing — briefing to specialist
+\`\`\`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: classify intent + project type (deterministic)
+    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)
+\`\`\`
+Rules that make this deterministic, not improvised:
+- **Article VIII — Mandatory Delegation:** an orchestrator that does domain work
+  itself is a constitutional violation. Even "just do it yourself" → delegate.
+- **Auto-routing:** the user never types an agent name; the system detects the
+  domain and routes. Acknowledgement is business language, never \`@agent-id\`.
+- **Project-type gate:** site / lp / app / platform / saas / api / service with
+  no epic → the greenfield workflow is invoked *before* any code.`;
+}
+// ───────────────────────────────────────────────────────────────────────────
+// Framework flows (authored data → diagrams)
+// ───────────────────────────────────────────────────────────────────────────
+function frameworkFlows(d) {
+  const flows = d.flows || [];
+  if (!flows.length) return '';
+  const blocks = flows
+    .map(
+      (f) => `### ${f.title}
+${f.purpose}
+\`\`\`mermaid
+${f.mermaid}
+\`\`\``,
+    )
+    .join('\n\n');
+  return `## 2b. Framework flows — how each mechanism runs
+The meta-workflows of the framework itself (not the development workflows in
+\`docs/sinapse-workflows/\`). Each is a single diagram you can read at a glance.
+${blocks}`;
+}
+// ───────────────────────────────────────────────────────────────────────────
+// Public
+// ───────────────────────────────────────────────────────────────────────────
+/**
+ * Render the full LLM-readable atlas markdown from atlas data.
+ * @param {object} d - Output of buildAtlasData.
+ * @returns {string} Markdown.
+ */
+function renderAtlasMarkdown(d) {
+  const stamp = d.generatedAt ? `\n> Generated: ${d.generatedAt}` : '';
+  return `# SINAPSE — Framework Operating Atlas
+> Single, generated map of how the SINAPSE framework works: routing, models,
+> constitution, workflows, agents, squads. Regenerate with \`sinapse atlas\`.
+> Counts are read from disk (Article VII — always exact).${stamp}
+**At a glance:** ${d.counts.squads} squads · ${d.counts.agentsTotal} agents
+(${d.counts.frameworkAgents} framework + ${d.counts.squadAgents} squad) ·
+${d.counts.orqx} orchestrators · ${d.counts.workflowsTotal} workflows
+(${d.counts.frameworkWorkflows} framework + ${d.counts.squadWorkflows} squad) ·
+${d.counts.articles} constitutional articles · ${d.counts.rules} rules.
+---
+${operatingModel(d)}
+---
+${routingDetail()}
+---
+${frameworkFlows(d)}
+---
+${constitutionTable(d)}
+---
+${modelRouting()}
+---
+${rulesTable(d)}
+---
+${workflowCatalog(d)}
+---
+${agentsSquadsMap(d)}
+---
+*Generated by \`.sinapse-ai/core/atlas\` · data: \`docs/framework/atlas/atlas-data.json\`.*
+`;
+}
+module.exports = { renderAtlasMarkdown };