@jaimevalasek/aioson 1.5.1 → 1.7.0

package/docs/pt/spec-learnings-pipeline.md

@@ -0,0 +1,265 @@
+# Spec & Learnings Pipeline
+
+> Sincroniza specs Markdown com o SQLite e exporta learnings para memória procedural do projeto.
+
+O AIOSON mantém duas representações do estado de desenvolvimento: os arquivos `spec-{slug}.md` em `.aioson/context/` (editados pelos agentes) e o banco SQLite `aios.sqlite` (lido pelo dashboard). Este pipeline conecta os dois automaticamente.
+
+---
+
+## Visão geral do fluxo
+
+```
+@dev escreve spec-checkout.md
+  └─ ## Session Learnings: [process] commit por step
+  └─ frontmatter: phase_gates: {plan: approved}
+  └─ last_checkpoint: "Criando migration cart_items — step 3 de 5"
+
+aioson spec:sync .
+  └─ project_learnings ← learnings upserted (frequency++)
+  └─ plan_phases ← phase_gates mapeadas para status
+
+aioson spec:status .
+  └─ tabela de features com fase, agente, checkpoint
+
+aioson learning:export . --min-frequency=2
+  └─ .aioson/brains/process-commit-por-step.md  ← node Zettelkasten
+
+aioson learning:evolve .
+  └─ genome ← learnings com frequency ≥ 5 promovidos
+```
+
+---
+
+## `aioson spec:sync`
+
+Sincroniza learnings e phase gates de todos os specs para o SQLite.
+
+```bash
+aioson spec:sync [path] [opções]
+```
+
+**Opções:**
+
+| Opção | Descrição |
+|---|---|
+| `--json` | Retorna JSON com contagem de learnings e fases sincronizadas |
+| `--verbose` | Mostra detalhes de cada arquivo processado |
+
+**Exemplo:**
+
+```bash
+aioson spec:sync .
+```
+
+Saída:
+
+```
+Spec Sync — meu-projeto
+──────────────────────────────────────────────────
+spec-checkout.md
+  Learnings synced: 3
+  Plan phases updated: 1
+  last_checkpoint: "Criando migration cart_items"
+spec.md
+  Learnings synced: 2
+──────────────────────────────────────────────────
+Summary: 5 learnings synced, 1 plan phases updated
+```
+
+**Formato dos learnings no spec:**
+
+```markdown
+## Session Learnings
+- [process] Fazer commit após cada step atômico, não só no final
+- [domain] cart_items deve ter UNIQUE(cart_id, product_id)
+- [quality] Rodar testes com --filter isola o módulo rapidamente
+```
+
+Prefixos aceitos: `[process]`, `[domain]`, `[quality]`, `[preference]`.  
+Linhas sem prefixo são classificadas automaticamente como `[process]`.
+
+**Idempotência:** rodar `spec:sync` duas vezes no mesmo spec não duplica learnings. Se o título já existe em `project_learnings`, o campo `frequency` é incrementado (`frequency++`).
+
+---
+
+## `aioson spec:status`
+
+Exibe o estado atual de todas as features com dados do SQLite.
+
+```bash
+aioson spec:status [path] [opções]
+```
+
+**Opções:**
+
+| Opção | Descrição |
+|---|---|
+| `--json` | Retorna JSON com array de features e contagem de learnings |
+
+**Exemplo:**
+
+```bash
+aioson spec:status .
+```
+
+Saída:
+
+```
+Project Status — meu-projeto
+────────────────────────────────────────────────────────────────────────────────
+Feature             Phase     Status          Last Agent      Checkpoint
+────────────────────────────────────────────────────────────────────────────────
+checkout            2/5       in_progress     dev             Criando migration...
+auth                5/5       done            qa              QA sign-off 2026-03-28
+onboarding          0/5       not_started     —               —
+────────────────────────────────────────────────────────────────────────────────
+Active learnings: 12  |  Promotable (freq≥3): 4
+```
+
+---
+
+## `aioson spec:checkpoint`
+
+Registra manualmente o `last_checkpoint` de um spec no SQLite. Útil quando a sessão caiu sem `agent:done`.
+
+```bash
+aioson spec:checkpoint [path] --feature=<slug> [--agent=<agent>]
+```
+
+**Opções:**
+
+| Opção | Descrição |
+|---|---|
+| `--feature=<slug>` | Feature cujo spec será lido (obrigatório) |
+| `--agent=<name>` | Agente da run ativa (padrão: `dev`) |
+| `--json` | Retorna JSON com run_key e checkpoint registrado |
+
+**Exemplo:**
+
+```bash
+# Sessão do @dev em checkout caiu sem agent:done
+aioson spec:checkpoint . --feature=checkout
+```
+
+Saída:
+
+```
+Reading spec-checkout.md...
+last_checkpoint: "Criando migration cart_items — step 3 of 5"
+phase_gates: {"plan":"approved","requirements":"approved","design":"pending"}
+
+Checkpoint registered:
+  run_key: dev-1711234567890
+  summary: "Criando migration cart_items — step 3 of 5"
+  status: in_progress (checkpoint only — use agent:done to close)
+
+Next: continue with /dev — start from last_checkpoint
+```
+
+O comando procura a run mais recente do agente no SQLite e registra um evento `plan_checkpoint` nela. O run permanece `in_progress` — use `agent:done` para fechá-la quando terminar.
+
+---
+
+## `aioson learning:export`
+
+Exporta `project_learnings` do SQLite para `.aioson/brains/` como nodes no formato Zettelkasten.
+
+```bash
+aioson learning:export [path] [--min-frequency=N] [--json]
+```
+
+**Opções:**
+
+| Opção | Descrição |
+|---|---|
+| `--min-frequency=N` | Exporta apenas learnings com `frequency >= N` (padrão: 1) |
+| `--json` | Retorna JSON com lista de nodes exportados |
+
+**Exemplos:**
+
+```bash
+# Exportar todos os learnings ativos
+aioson learning:export .
+
+# Apenas learnings reforçados em 2+ sessões
+aioson learning:export . --min-frequency=2
+```
+
+Saída:
+
+```
+Learning Export — min-frequency: 2
+──────────────────────────────────────────────────
+  process-commit-por-step.md ✓ (frequency: 4)
+  domain-cart-uniqueness.md ✓ (frequency: 3)
+  process-test-isolation.md ✓ (frequency: 2)
+──────────────────────────────────────────────────
+3 nodes written to .aioson/brains/
+2 learning(s) with frequency ≥ 5 — run: aioson learning:evolve to promote to genome
+```
+
+**Formato do node exportado** (`.aioson/brains/process-commit-por-step.md`):
+
+```markdown
+---
+id: process-commit-por-step
+type: process
+title: Fazer commit após cada step atômico, não só no final
+frequency: 4
+last_reinforced: 2026-04-01
+source_feature: checkout
+promoted_to: null
+created_at: 2026-03-15
+---
+
+# Fazer commit após cada step atômico
+
+**Evidence:** Detected in 4 session(s).
+
+## Applications
+- Review and apply this learning in future sessions of type: process
+
+## Links
+<!-- Add cross-references here -->
+```
+
+---
+
+## Fluxo recomendado após cada sessão do @dev
+
+```bash
+# 1. Sincronizar spec com o SQLite
+aioson spec:sync .
+
+# 2. Ver estado atual das features
+aioson spec:status .
+
+# 3. Quando learnings se acumularem (≥ 2 sessões), exportar para brains
+aioson learning:export . --min-frequency=2
+
+# 4. Quando um learning atingir frequency ≥ 5, promover para genome
+aioson learning:evolve .
+```
+
+---
+
+## Integração com o spec.md
+
+O `spec:sync` procura esses elementos em cada `spec-{slug}.md`:
+
+| Elemento | Onde fica | O que faz |
+|---|---|---|
+| `## Session Learnings` | Corpo do arquivo | Cria/atualiza `project_learnings` |
+| `phase_gates` | Frontmatter YAML | Atualiza `plan_phases.status` |
+| `last_checkpoint` | Frontmatter ou seção | Exibido em `spec:status` |
+
+**Exemplo de frontmatter de spec:**
+
+```markdown
+---
+feature: checkout
+status: in_progress
+phase_gates: {"plan": "approved", "requirements": "approved", "design": "pending"}
+last_checkpoint: "Criando migration cart_items — step 3 de 5"
+---
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jaimevalasek/aioson",
-  "version": "1.5.1",
+  "version": "1.7.0",
   "description": "AI operating framework for hyper-personalized software.",
   "keywords": [
     "ai",

package/src/a2a/client.js

@@ -0,0 +1,165 @@
+'use strict';
+
+/**
+ * A2A Client — Plan 81, Phase 3.2
+ *
+ * HTTP client for sending tasks/events to A2A-compatible agents
+ * (including other AIOSON squads in different projects).
+ *
+ * Implements Google A2A v1.0 JSON-RPC 2.0 protocol.
+ */
+
+const http = require('node:http');
+const https = require('node:https');
+const { randomUUID } = require('node:crypto');
+
+const DEFAULT_TIMEOUT = 30000;
+
+/**
+ * Send a JSON-RPC 2.0 request to an A2A endpoint.
+ *
+ * @param {string} url  — A2A endpoint URL
+ * @param {string} method  — JSON-RPC method
+ * @param {object} params  — Method parameters
+ * @param {object} [options]  — { timeout }
+ * @returns {Promise<object>}  — JSON-RPC response
+ */
+function rpcRequest(url, method, params, options = {}) {
+  const { timeout = DEFAULT_TIMEOUT } = options;
+  const requestId = randomUUID();
+
+  const body = JSON.stringify({
+    jsonrpc: '2.0',
+    id: requestId,
+    method,
+    params
+  });
+
+  return new Promise((resolve, reject) => {
+    const parsedUrl = new URL(url);
+    const transport = parsedUrl.protocol === 'https:' ? https : http;
+
+    const req = transport.request({
+      hostname: parsedUrl.hostname,
+      port: parsedUrl.port,
+      path: parsedUrl.pathname,
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Content-Length': Buffer.byteLength(body)
+      },
+      timeout
+    }, (res) => {
+      let data = '';
+      res.on('data', (chunk) => { data += chunk; });
+      res.on('end', () => {
+        try {
+          resolve(JSON.parse(data));
+        } catch {
+          resolve({ error: { code: -32700, message: 'Parse error', data } });
+        }
+      });
+    });
+
+    req.on('error', (err) => {
+      resolve({ error: { code: -32000, message: err.message } });
+    });
+
+    req.on('timeout', () => {
+      req.destroy();
+      resolve({ error: { code: -32000, message: `Request timed out after ${timeout}ms` } });
+    });
+
+    req.write(body);
+    req.end();
+  });
+}
+
+/**
+ * Discover an A2A agent by fetching its Agent Card.
+ *
+ * @param {string} baseUrl  — Agent's base URL
+ * @returns {Promise<object|null>}  — Agent Card or null
+ */
+async function discoverAgent(baseUrl) {
+  const cardUrl = `${baseUrl.replace(/\/$/, '')}/.well-known/agent.json`;
+
+  return new Promise((resolve) => {
+    const parsedUrl = new URL(cardUrl);
+    const transport = parsedUrl.protocol === 'https:' ? https : http;
+
+    const req = transport.get(cardUrl, { timeout: 10000 }, (res) => {
+      let data = '';
+      res.on('data', (chunk) => { data += chunk; });
+      res.on('end', () => {
+        try {
+          resolve(JSON.parse(data));
+        } catch {
+          resolve(null);
+        }
+      });
+    });
+
+    req.on('error', () => resolve(null));
+    req.on('timeout', () => { req.destroy(); resolve(null); });
+  });
+}
+
+/**
+ * Send a task to an A2A agent.
+ *
+ * @param {string} agentUrl  — Agent's A2A endpoint URL
+ * @param {object} task  — { id, title, description, input }
+ * @returns {Promise<object>}  — { ok, taskId, result, error }
+ */
+async function sendTask(agentUrl, task) {
+  const taskId = task.id || randomUUID();
+
+  const response = await rpcRequest(agentUrl, 'tasks/send', {
+    id: taskId,
+    message: {
+      role: 'user',
+      parts: [
+        { type: 'text', text: task.description || task.title }
+      ]
+    },
+    metadata: {
+      title: task.title,
+      input: task.input || null
+    }
+  });
+
+  if (response.error) {
+    return { ok: false, taskId, error: response.error.message };
+  }
+
+  return { ok: true, taskId, result: response.result };
+}
+
+/**
+ * Publish an event to an A2A peer.
+ *
+ * @param {string} peerUrl  — Peer's A2A endpoint URL
+ * @param {object} event  — { fromSquad, event, payload }
+ * @returns {Promise<object>}
+ */
+async function publishEvent(peerUrl, event) {
+  const response = await rpcRequest(peerUrl, 'events/publish', {
+    source: event.fromSquad,
+    type: event.event,
+    data: event.payload || {}
+  });
+
+  if (response.error) {
+    return { ok: false, error: response.error.message };
+  }
+
+  return { ok: true, id: response.result?.id };
+}
+
+module.exports = {
+  rpcRequest,
+  discoverAgent,
+  sendTask,
+  publishEvent
+};

package/src/a2a/server.js

@@ -0,0 +1,223 @@
+'use strict';
+
+/**
+ * A2A Server — Plan 81, Phase 3.2
+ *
+ * Micro HTTP server that exposes squad capabilities via A2A protocol.
+ * Receives tasks from external A2A agents and routes them to local squads.
+ *
+ * Endpoints:
+ *   POST /a2a/{squad-slug}         — JSON-RPC 2.0 task handler
+ *   GET  /.well-known/agent.json   — Agent Card discovery
+ *   GET  /a2a/{squad-slug}/status  — Squad status
+ */
+
+const http = require('node:http');
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const { randomUUID } = require('node:crypto');
+
+const SQUADS_DIR = path.join('.aioson', 'squads');
+
+/**
+ * Create an A2A server for a project.
+ *
+ * @param {string} projectDir
+ * @param {object} [options]  — { port, host }
+ * @returns {{ server, start, stop }}
+ */
+function createA2AServer(projectDir, options = {}) {
+  const { port = 3847, host = '127.0.0.1' } = options;
+  const pendingTasks = new Map();
+
+  const server = http.createServer(async (req, res) => {
+    const url = new URL(req.url, `http://${host}:${port}`);
+
+    // CORS headers
+    res.setHeader('Access-Control-Allow-Origin', '*');
+    res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
+    res.setHeader('Access-Control-Allow-Headers', 'Content-Type');
+
+    if (req.method === 'OPTIONS') {
+      res.writeHead(200);
+      res.end();
+      return;
+    }
+
+    // Agent Card discovery
+    if (req.method === 'GET' && url.pathname === '/.well-known/agent.json') {
+      return handleAgentCardDiscovery(projectDir, res);
+    }
+
+    // Squad status
+    const statusMatch = url.pathname.match(/^\/a2a\/([a-z0-9-]+)\/status$/);
+    if (req.method === 'GET' && statusMatch) {
+      return handleSquadStatus(projectDir, statusMatch[1], res);
+    }
+
+    // A2A JSON-RPC endpoint
+    const a2aMatch = url.pathname.match(/^\/a2a\/([a-z0-9-]+)$/);
+    if (req.method === 'POST' && a2aMatch) {
+      return handleJsonRpc(projectDir, a2aMatch[1], req, res, pendingTasks);
+    }
+
+    res.writeHead(404, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ error: 'Not Found' }));
+  });
+
+  return {
+    server,
+    start() {
+      return new Promise((resolve) => {
+        server.listen(port, host, () => resolve({ port, host }));
+      });
+    },
+    stop() {
+      return new Promise((resolve) => {
+        server.close(() => resolve());
+      });
+    },
+    pendingTasks
+  };
+}
+
+// ─── Handlers ────────────────────────────────────────────────────────────────
+
+async function handleAgentCardDiscovery(projectDir, res) {
+  // Return a composite card for all squads
+  const squadsDir = path.join(projectDir, SQUADS_DIR);
+  const cards = [];
+
+  try {
+    const entries = await fs.readdir(squadsDir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      const manifestPath = path.join(squadsDir, entry.name, 'squad.manifest.json');
+      try {
+        const manifest = JSON.parse(await fs.readFile(manifestPath, 'utf8'));
+        cards.push({
+          slug: entry.name,
+          name: manifest.name || entry.name,
+          description: manifest.mission || manifest.goal || ''
+        });
+      } catch { /* no valid manifest */ }
+    }
+  } catch { /* no squads dir */ }
+
+  const compositeCard = {
+    name: 'AIOSON Project',
+    description: `AIOSON project with ${cards.length} squad(s)`,
+    version: '1.0.0',
+    squads: cards,
+    capabilities: {
+      streaming: false,
+      pushNotifications: false
+    }
+  };
+
+  res.writeHead(200, { 'Content-Type': 'application/json' });
+  res.end(JSON.stringify(compositeCard, null, 2));
+}
+
+async function handleSquadStatus(projectDir, squadSlug, res) {
+  const statePath = path.join(projectDir, SQUADS_DIR, squadSlug, 'STATE.md');
+
+  try {
+    const content = await fs.readFile(statePath, 'utf8');
+    res.writeHead(200, { 'Content-Type': 'text/markdown' });
+    res.end(content);
+  } catch {
+    res.writeHead(404, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ error: `Squad "${squadSlug}" not found` }));
+  }
+}
+
+async function handleJsonRpc(projectDir, squadSlug, req, res, pendingTasks) {
+  let body = '';
+  for await (const chunk of req) body += chunk;
+
+  let rpc;
+  try {
+    rpc = JSON.parse(body);
+  } catch {
+    res.writeHead(400, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({
+      jsonrpc: '2.0',
+      error: { code: -32700, message: 'Parse error' },
+      id: null
+    }));
+    return;
+  }
+
+  const { method, params, id } = rpc;
+
+  if (method === 'tasks/send') {
+    const taskId = params?.id || randomUUID();
+    pendingTasks.set(taskId, {
+      id: taskId,
+      squadSlug,
+      params,
+      status: 'pending',
+      createdAt: new Date().toISOString()
+    });
+
+    res.writeHead(200, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({
+      jsonrpc: '2.0',
+      result: {
+        id: taskId,
+        status: { state: 'submitted' },
+        message: `Task queued for squad "${squadSlug}"`
+      },
+      id
+    }));
+    return;
+  }
+
+  if (method === 'tasks/get') {
+    const task = pendingTasks.get(params?.id);
+    res.writeHead(200, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({
+      jsonrpc: '2.0',
+      result: task || { error: 'Task not found' },
+      id
+    }));
+    return;
+  }
+
+  if (method === 'events/publish') {
+    // Route to local inter-squad-events
+    try {
+      const { publish } = require('../squad/inter-squad-events');
+      const eventId = await publish(projectDir, {
+        fromSquad: params?.source || 'a2a-external',
+        event: params?.type || 'a2a.event',
+        payload: params?.data
+      });
+
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({
+        jsonrpc: '2.0',
+        result: { id: eventId, status: 'published' },
+        id
+      }));
+    } catch (err) {
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({
+        jsonrpc: '2.0',
+        error: { code: -32603, message: err.message },
+        id
+      }));
+    }
+    return;
+  }
+
+  res.writeHead(200, { 'Content-Type': 'application/json' });
+  res.end(JSON.stringify({
+    jsonrpc: '2.0',
+    error: { code: -32601, message: `Method not found: ${method}` },
+    id
+  }));
+}
+
+module.exports = { createA2AServer };