@vascend/talos 0.1.0

package/dist/vascend/code-graph-types.js

@@ -0,0 +1,50 @@
+// Tipi del dominio CODE GRAPH (metodo Danilov, Memory OS).
+//
+// CodeGraphMemory indicizza la STRUTTURA del codice del repository:
+//   - simboli (funzioni, classi, interfacce, tipi, costanti esportate o no)
+//   - import / dipendenze tra file (grafo orientato)
+//   - API pubbliche (export) e contratti (signature di funzioni/metodi pubblici)
+//   - test mapping (quali file di test coprono quali file/simboli sorgente)
+//   - feature areas (raggruppamenti logici di file/simboli per area funzionale)
+//
+// Da queste viste emette eventi del dominio "code", consumati dal Context
+// Window Compiler per portare in finestra il "code graph caldo": cio' che e'
+// cambiato di recente, le API toccate, i test rotti, i contratti modificati.
+//
+// Modulo PURO: solo tipi ed helper deterministici, nessun side-effect, zero
+// dipendenze a runtime. Combacia per struttura con MemoryEvent senza dipenderne
+// rigidamente (un CodeEvent si converte in MemoryEvent nel sink).
+// --- helper deterministici --------------------------------------------------
+// Costruisce l'id stabile di un simbolo.
+export function symbolId(file, name) {
+    return `${file}#${name}`;
+}
+// Etichetta umana breve del tipo evento (azione Danilov).
+export function codeActionLabel(type) {
+    switch (type) {
+        case "code.symbol.changed": return "simbolo-cambiato";
+        case "code.file.touched": return "file-toccato";
+        case "code.import.added": return "import-aggiunto";
+        case "code.api.changed": return "api-cambiata";
+        case "code.contract.changed": return "contratto-cambiato";
+        case "code.test.failed": return "test-fallito";
+        case "code.test.passed": return "test-passato";
+    }
+}
+// Vero se un export e' parte di un'API pubblica "vera" (nome non interno).
+export function isPublicName(name) {
+    return !!name && !name.startsWith("_");
+}
+// Deriva un id di feature area dal path relativo (prima cartella significativa
+// sotto src/, altrimenti la cartella di primo livello). Deterministico.
+export function featureAreaOf(file) {
+    const norm = file.replace(/\\/g, "/").replace(/^\.\//, "");
+    const parts = norm.split("/").filter(Boolean);
+    if (parts.length <= 1)
+        return "root";
+    // Salta una "src" iniziale per usare la cartella di dominio.
+    let i = 0;
+    if (parts[0] === "src")
+        i = 1;
+    return parts[i] ?? "root";
+}

package/dist/vascend/code-parser.d.ts

@@ -0,0 +1,4 @@
+import { type ParsedFile } from "./code-graph-types.js";
+export declare function isTestFile(file: string): boolean;
+export declare function parseSource(file: string, source: string): ParsedFile;
+export declare function publicApiOf(parsed: ParsedFile): readonly string[];

package/dist/vascend/code-parser.js

@@ -0,0 +1,257 @@
+// Parser/scanner leggero per TS/JS (metodo Danilov, Memory OS).
+//
+// Estrae simboli, import ed export da un file SENZA AST e SENZA dipendenze:
+// regex robuste, line-by-line, tolleranti. Non e' un compilatore: e' un
+// indicizzatore "best effort" pensato per alimentare il code graph. Preferisce
+// falsi negativi (perde qualche caso esotico) ai falsi positivi rumorosi.
+//
+// Modulo PURO: input stringa -> ParsedFile. Nessuna lettura su disco qui;
+// l'orchestrazione (leggere i file) sta in CodeGraphMemory.
+import { symbolId, } from "./code-graph-types.js";
+// Vero se il path indica un file di test per convenzione comune.
+export function isTestFile(file) {
+    const f = file.replace(/\\/g, "/").toLowerCase();
+    return (/\.(test|spec)\.[cm]?[jt]sx?$/.test(f) ||
+        /(^|\/)(test|tests|__tests__|spec)\//.test(f));
+}
+// Rimuove commenti di riga e di blocco (best effort) e le stringhe template
+// multilinea non vengono toccate: ci interessa solo ridurre il rumore dei
+// commenti che contengono parole chiave come "export" o "import".
+function stripComments(source) {
+    // Blocchi /* ... */ (non greedy, multilinea).
+    let s = source.replace(/\/\*[\s\S]*?\*\//g, "");
+    // Commenti di riga // ... (evita di toccare "://" negli URL in modo grezzo).
+    s = s.replace(/(^|[^:])\/\/[^\n]*/g, "$1");
+    return s;
+}
+// Estrae il blocco import: gestisce
+//   import X from "m"; import { a, b as c } from "m"; import * as ns from "m";
+//   import "m"; import type { T } from "m";
+const IMPORT_RE = /import\s+(?:type\s+)?(?:([\w$]+)\s*,?\s*)?(?:\{([^}]*)\})?\s*(?:\*\s+as\s+([\w$]+))?\s*(?:from\s*)?["']([^"']+)["']/g;
+// Re-export: export { a, b } from "m";  / export * from "m";
+const REEXPORT_RE = /export\s+(?:\*|\{([^}]*)\})\s+from\s+["']([^"']+)["']/g;
+function parseImports(source) {
+    const out = [];
+    const seen = new Set();
+    const pushImport = (module, names) => {
+        const key = `${module}::${names.join(",")}`;
+        if (seen.has(key))
+            return;
+        seen.add(key);
+        out.push({
+            file: "", // riempito dal chiamante
+            module,
+            names: dedupe(names),
+            external: !module.startsWith("."),
+        });
+    };
+    for (const m of source.matchAll(IMPORT_RE)) {
+        const def = m[1];
+        const braced = m[2];
+        const ns = m[3];
+        const module = m[4] ?? "";
+        if (!module)
+            continue;
+        const names = [];
+        if (def)
+            names.push(def);
+        if (ns)
+            names.push(ns);
+        if (braced) {
+            for (const part of braced.split(",")) {
+                const name = part.trim().split(/\s+as\s+/)[0]?.trim();
+                if (name)
+                    names.push(name.replace(/^type\s+/, ""));
+            }
+        }
+        pushImport(module, names);
+    }
+    for (const m of source.matchAll(REEXPORT_RE)) {
+        const braced = m[1];
+        const module = m[2] ?? "";
+        if (!module)
+            continue;
+        const names = [];
+        if (braced) {
+            for (const part of braced.split(",")) {
+                const name = part.trim().split(/\s+as\s+/)[0]?.trim();
+                if (name)
+                    names.push(name);
+            }
+        }
+        pushImport(module, names);
+    }
+    return out;
+}
+const SYMBOL_PATTERNS = [
+    { re: /^\s*(?:export\s+)?(?:default\s+)?(?:async\s+)?function\s*\*?\s*([\w$]+)/, kind: "function" },
+    { re: /^\s*(?:export\s+)?(?:default\s+)?(?:abstract\s+)?class\s+([\w$]+)/, kind: "class" },
+    { re: /^\s*(?:export\s+)?interface\s+([\w$]+)/, kind: "interface" },
+    { re: /^\s*(?:export\s+)?type\s+([\w$]+)\s*[=<]/, kind: "type" },
+    { re: /^\s*(?:export\s+)?(?:const\s+)?enum\s+([\w$]+)/, kind: "enum" },
+    // const arrow function: const foo = (...) => / const foo = async (...) =>
+    { re: /^\s*(?:export\s+)?const\s+([\w$]+)\s*(?::[^=]+)?=\s*(?:async\s*)?(?:function|\([^)]*\)\s*(?::[^=]*)?=>|[\w$]+\s*=>)/, kind: "function" },
+    // const generico (non funzione)
+    { re: /^\s*(?:export\s+)?const\s+([\w$]+)\s*[:=]/, kind: "const" },
+    { re: /^\s*(?:export\s+)?(?:let|var)\s+([\w$]+)\s*[:=]/, kind: "variable" },
+];
+// Cattura una firma sintetica della riga di definizione (troncata).
+function signatureOf(line) {
+    const trimmed = line.trim().replace(/\s+/g, " ");
+    // Tronca all'inizio del corpo ({ oppure =>) per tenere solo la firma.
+    const body = trimmed.search(/[{]/);
+    const sig = body > 0 ? trimmed.slice(0, body).trim() : trimmed;
+    return sig.replace(/\s*=\s*$/, "").slice(0, 200);
+}
+function isExportedLine(line) {
+    return /^\s*export\b/.test(line);
+}
+// Variante "anywhere" dei pattern: stesso corpo ma senza ancora ^\s* e con
+// flag globale, per catturare piu' definizioni sulla stessa riga (es.
+// `export function a(){} export function b(){}`). Manteniamo SYMBOL_PATTERNS
+// (ancorati) per il riconoscimento per-riga di const/var/type che richiedono
+// l'inizio riga, e usiamo questi per function/class/interface/enum.
+const GLOBAL_PATTERNS = [
+    { re: /(export\s+)?(?:default\s+)?(?:async\s+)?function\s*\*?\s*([\w$]+)/g, kind: "function" },
+    { re: /(export\s+)?(?:default\s+)?(?:abstract\s+)?class\s+([\w$]+)/g, kind: "class" },
+    { re: /(export\s+)?interface\s+([\w$]+)/g, kind: "interface" },
+    { re: /(export\s+)?(?:const\s+)?enum\s+([\w$]+)/g, kind: "enum" },
+];
+// Arrow/funzione assegnata: per distinguere const-funzione da const-dato.
+const ARROW_OR_FN = /=\s*(?:async\s*)?(?:function\b|\([^)]*\)\s*(?::[^=]*)?=>|[\w$]+\s*=>)/;
+function parseSymbols(file, source) {
+    const lines = source.split("\n");
+    const out = [];
+    const seen = new Set();
+    const lineOf = (offset) => {
+        let n = 1;
+        for (let i = 0; i < offset && i < source.length; i++)
+            if (source[i] === "\n")
+                n++;
+        return n;
+    };
+    // 1) function/class/interface/enum: scansione globale (piu' match per riga).
+    for (const p of GLOBAL_PATTERNS) {
+        for (const m of source.matchAll(p.re)) {
+            const name = m[2];
+            if (!name)
+                continue;
+            const id = symbolId(file, name);
+            if (seen.has(id))
+                continue;
+            seen.add(id);
+            const line = lineOf(m.index ?? 0);
+            // Firma: dal punto del match fino a fine firma (apertura corpo/blocco).
+            // Usa il source dall'offset del match per includere i parametri completi.
+            const tail = source.slice(m.index ?? 0);
+            out.push({
+                id,
+                name,
+                kind: p.kind,
+                file,
+                // l'export e' significativo solo se immediatamente prima della keyword
+                // (gruppo m[1]); evita falsi positivi con piu' def sulla stessa riga.
+                exported: !!m[1],
+                line,
+                signature: signatureOf(tail),
+            });
+        }
+    }
+    // 2) const/var/type: riconoscimento per-riga (richiedono l'inizio riga).
+    const LINE_PATTERNS = SYMBOL_PATTERNS.filter((p) => p.kind === "type" || p.kind === "const" || p.kind === "variable" || p.kind === "function");
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i] ?? "";
+        for (const p of LINE_PATTERNS) {
+            const m = p.re.exec(line);
+            if (!m)
+                continue;
+            const name = m[1];
+            if (!name)
+                continue;
+            const id = symbolId(file, name);
+            if (seen.has(id))
+                break;
+            seen.add(id);
+            out.push({
+                id,
+                name,
+                kind: p.kind,
+                file,
+                exported: isExportedLine(line),
+                line: i + 1,
+                signature: signatureOf(line),
+            });
+            break;
+        }
+    }
+    // 3) export const/let/var globali (multi-def sulla stessa riga). Dopo il
+    // passo per-riga, cosi' le arrow-function gia' catturate restano "function".
+    for (const m of source.matchAll(/(export\s+)(?:const|let|var)\s+([\w$]+)/g)) {
+        const name = m[2];
+        if (!name)
+            continue;
+        const id = symbolId(file, name);
+        if (seen.has(id))
+            continue;
+        seen.add(id);
+        const line = lineOf(m.index ?? 0);
+        const tail = source.slice(m.index ?? 0);
+        out.push({
+            id,
+            name,
+            kind: ARROW_OR_FN.test(tail.slice(0, 200)) ? "function" : "const",
+            file,
+            exported: true,
+            line,
+            signature: signatureOf(tail),
+        });
+    }
+    out.sort((a, b) => a.line - b.line);
+    // export { a, b } esplicito: marca come exported i simboli gia' trovati.
+    for (const m of source.matchAll(/export\s+\{([^}]*)\}\s*;?/g)) {
+        const inner = m[1] ?? "";
+        if (/\bfrom\b/.test(source.slice(m.index ?? 0, (m.index ?? 0) + (m[0]?.length ?? 0) + 20))) {
+            // gestito da re-export, non sono definizioni locali
+        }
+        for (const part of inner.split(",")) {
+            const name = part.trim().split(/\s+as\s+/)[0]?.trim();
+            if (!name)
+                continue;
+            const id = symbolId(file, name);
+            const found = out.find((s) => s.id === id);
+            if (found && !found.exported) {
+                const idx = out.indexOf(found);
+                out[idx] = { ...found, exported: true };
+            }
+        }
+    }
+    return out;
+}
+// Parsa un file sorgente in ParsedFile. `file` e' il path relativo (per gli id).
+export function parseSource(file, source) {
+    const clean = stripComments(source);
+    const symbols = parseSymbols(file, clean);
+    const imports = parseImports(clean).map((i) => ({ ...i, file }));
+    return {
+        file,
+        symbols,
+        imports,
+        isTest: isTestFile(file),
+    };
+}
+// API pubblica di un file = nomi dei simboli esportati.
+export function publicApiOf(parsed) {
+    return dedupe(parsed.symbols.filter((s) => s.exported).map((s) => s.name));
+}
+function dedupe(values) {
+    const out = [];
+    const seen = new Set();
+    for (const v of values) {
+        const t = (v ?? "").trim();
+        if (!t || seen.has(t))
+            continue;
+        seen.add(t);
+        out.push(t);
+    }
+    return out;
+}

package/dist/vascend/competitor-knowledge.d.ts

@@ -0,0 +1,53 @@
+export type Category = "auth" | "data-model" | "crud" | "ui" | "api" | "observability" | "security" | "billing" | "testing" | "docs" | "deployment" | (string & {});
+export type Importance = "must" | "should" | "nice";
+export interface Competitor {
+    readonly id: string;
+    readonly name: string;
+    readonly domain: string;
+    readonly summary: string;
+    readonly features: readonly string[];
+    readonly reference?: string;
+}
+export interface BestPractice {
+    readonly id: string;
+    readonly title: string;
+    readonly category: Category;
+    readonly domain: string;
+    readonly importance: Importance;
+    readonly expectation: string;
+    readonly adoptedBy?: readonly string[];
+    readonly reference?: string;
+}
+export interface MarketStandard {
+    readonly domain: string;
+    readonly practices: readonly BestPractice[];
+    readonly competitors: readonly Competitor[];
+}
+export interface ComparisonVerdict {
+    readonly domain: string;
+    readonly score: number;
+    readonly met: readonly BestPractice[];
+    readonly gaps: readonly BestPractice[];
+    readonly extras: readonly string[];
+    readonly summary: string;
+}
+export declare class KnowledgeBase {
+    private readonly competitors;
+    private readonly practices;
+    constructor(opts?: {
+        readonly competitors?: readonly Competitor[];
+        readonly practices?: readonly BestPractice[];
+    });
+    static default(): KnowledgeBase;
+    allCompetitors(): readonly Competitor[];
+    competitor(id: string): Competitor | undefined;
+    competitorsByDomain(domain: string): readonly Competitor[];
+    allPractices(): readonly BestPractice[];
+    practice(id: string): BestPractice | undefined;
+    practicesByDomain(domain: string): readonly BestPractice[];
+    practicesByCategory(category: Category): readonly BestPractice[];
+    domains(): readonly string[];
+    marketStandard(domain: string): MarketStandard;
+    compareToMarket(domain: string, outputFeatures: readonly string[]): ComparisonVerdict;
+}
+export declare const knowledgeBase: KnowledgeBase;

package/dist/vascend/competitor-knowledge.js

@@ -0,0 +1,262 @@
+// Knowledge base dei concorrenti e delle best practice di settore.
+//
+// Scopo: raccogliere riferimenti su prodotti concorrenti e standard di mercato
+// per il dominio del task, ed esporre un'API per CONFRONTARE l'output prodotto
+// (un insieme di feature/capabilities) con gli standard attesi, ritornando i
+// gap e uno score. Modulo PURO e a zero dipendenze: dati statici + funzioni di
+// query e confronto. Coerente con lo stile degli altri moduli vascend/.
+// ---------------------------------------------------------------------------
+// Dataset (Piano istanze) - concorrenti di riferimento.
+// Curato e conciso: rappresenta gli standard di mercato per i domini comuni in
+// cui un agente di coding produce output (SaaS, piattaforme dev, auth, ecc.).
+// ---------------------------------------------------------------------------
+const COMPETITORS = [
+    {
+        id: "stripe",
+        name: "Stripe",
+        domain: "billing",
+        summary: "Piattaforma di pagamenti con API-first, idempotenza e webhook robusti.",
+        features: ["billing.subscriptions", "billing.idempotency", "billing.webhooks", "api.versioning", "docs.api-reference"],
+        reference: "https://stripe.com/docs",
+    },
+    {
+        id: "auth0",
+        name: "Auth0",
+        domain: "auth",
+        summary: "Identity provider con OAuth2/OIDC, MFA e gestione sessioni.",
+        features: ["auth.oauth2", "auth.mfa", "auth.sessions", "auth.rbac", "security.token-rotation"],
+        reference: "https://auth0.com/docs",
+    },
+    {
+        id: "clerk",
+        name: "Clerk",
+        domain: "auth",
+        summary: "Auth as-a-service con UI components pronte e gestione utenti.",
+        features: ["auth.oauth2", "auth.mfa", "auth.sessions", "ui.prebuilt-components"],
+        reference: "https://clerk.com/docs",
+    },
+    {
+        id: "supabase",
+        name: "Supabase",
+        domain: "saas-backend",
+        summary: "Backend open-source: Postgres, auth, storage, realtime, RLS.",
+        features: ["auth.oauth2", "data-model.relational", "crud.rest", "crud.realtime", "security.row-level"],
+        reference: "https://supabase.com/docs",
+    },
+    {
+        id: "vercel",
+        name: "Vercel",
+        domain: "deployment",
+        summary: "Piattaforma di deploy con preview, edge e osservabilita' integrata.",
+        features: ["deployment.preview", "deployment.edge", "observability.logs", "observability.analytics"],
+        reference: "https://vercel.com/docs",
+    },
+    {
+        id: "datadog",
+        name: "Datadog",
+        domain: "observability",
+        summary: "Osservabilita' end-to-end: metriche, tracing, log correlati e alert.",
+        features: ["observability.metrics", "observability.tracing", "observability.logs", "observability.alerts"],
+        reference: "https://docs.datadoghq.com",
+    },
+    {
+        id: "linear",
+        name: "Linear",
+        domain: "saas-b2b",
+        summary: "SaaS B2B con UX rapida, keyboard-first, API GraphQL e webhooks.",
+        features: ["ui.keyboard-first", "ui.optimistic", "api.graphql", "billing.subscriptions", "docs.api-reference"],
+        reference: "https://linear.app/docs",
+    },
+];
+// ---------------------------------------------------------------------------
+// Dataset - best practice / standard di mercato.
+// ---------------------------------------------------------------------------
+const PRACTICES = [
+    // --- auth ---
+    { id: "auth.oauth2", title: "OAuth2/OIDC login", category: "auth", domain: "auth", importance: "must",
+        expectation: "Login federato (Google/GitHub) via OAuth2/OIDC, non solo password.", adoptedBy: ["auth0", "clerk", "supabase"] },
+    { id: "auth.mfa", title: "Multi-factor auth", category: "auth", domain: "auth", importance: "should",
+        expectation: "Secondo fattore (TOTP/WebAuthn) opzionale per gli account.", adoptedBy: ["auth0", "clerk"] },
+    { id: "auth.sessions", title: "Gestione sessioni sicura", category: "auth", domain: "auth", importance: "must",
+        expectation: "Sessioni con scadenza, refresh e revoca; cookie httpOnly/secure.", adoptedBy: ["auth0", "clerk", "supabase"] },
+    { id: "auth.rbac", title: "Ruoli e permessi (RBAC)", category: "security", domain: "auth", importance: "should",
+        expectation: "Controllo accessi basato su ruoli per le risorse protette.", adoptedBy: ["auth0"] },
+    { id: "security.token-rotation", title: "Rotazione dei token", category: "security", domain: "auth", importance: "should",
+        expectation: "Refresh token a rotazione con rilevamento riuso.", adoptedBy: ["auth0"] },
+    { id: "security.row-level", title: "Row-level security", category: "security", domain: "saas-backend", importance: "should",
+        expectation: "Isolamento dei dati per tenant/utente a livello di riga.", adoptedBy: ["supabase"] },
+    // --- data-model / crud ---
+    { id: "data-model.relational", title: "Modello dati relazionale", category: "data-model", domain: "saas-backend", importance: "must",
+        expectation: "Schema normalizzato con vincoli e relazioni esplicite.", adoptedBy: ["supabase"] },
+    { id: "crud.rest", title: "API CRUD REST", category: "crud", domain: "saas-backend", importance: "must",
+        expectation: "Operazioni CRUD complete via REST con paginazione e filtri.", adoptedBy: ["supabase"] },
+    { id: "crud.realtime", title: "Aggiornamenti realtime", category: "crud", domain: "saas-backend", importance: "nice",
+        expectation: "Subscribe alle modifiche dei dati (websocket/SSE).", adoptedBy: ["supabase"] },
+    // --- api ---
+    { id: "api.versioning", title: "Versionamento API", category: "api", domain: "api", importance: "should",
+        expectation: "API versionata con politica di deprecazione chiara.", adoptedBy: ["stripe"] },
+    { id: "api.graphql", title: "API GraphQL", category: "api", domain: "api", importance: "nice",
+        expectation: "Endpoint GraphQL tipizzato per query flessibili.", adoptedBy: ["linear"] },
+    // --- ui ---
+    { id: "ui.prebuilt-components", title: "Componenti UI pronti", category: "ui", domain: "ui", importance: "nice",
+        expectation: "Componenti riusabili e accessibili per i flussi comuni.", adoptedBy: ["clerk"] },
+    { id: "ui.keyboard-first", title: "Navigazione keyboard-first", category: "ui", domain: "ui", importance: "nice",
+        expectation: "Scorciatoie da tastiera per le azioni principali.", adoptedBy: ["linear"] },
+    { id: "ui.optimistic", title: "UI ottimistica", category: "ui", domain: "ui", importance: "nice",
+        expectation: "Aggiornamenti ottimistici con rollback su errore.", adoptedBy: ["linear"] },
+    // --- billing ---
+    { id: "billing.subscriptions", title: "Abbonamenti ricorrenti", category: "billing", domain: "billing", importance: "must",
+        expectation: "Piani/abbonamenti con prove, upgrade/downgrade e proration.", adoptedBy: ["stripe", "linear"] },
+    { id: "billing.idempotency", title: "Idempotenza dei pagamenti", category: "billing", domain: "billing", importance: "must",
+        expectation: "Chiavi di idempotenza per evitare doppi addebiti.", adoptedBy: ["stripe"] },
+    { id: "billing.webhooks", title: "Webhook affidabili", category: "billing", domain: "billing", importance: "should",
+        expectation: "Webhook firmati con retry e gestione degli eventi duplicati.", adoptedBy: ["stripe"] },
+    // --- observability ---
+    { id: "observability.logs", title: "Log strutturati", category: "observability", domain: "observability", importance: "must",
+        expectation: "Log strutturati e ricercabili con correlazione richiesta.", adoptedBy: ["vercel", "datadog"] },
+    { id: "observability.metrics", title: "Metriche", category: "observability", domain: "observability", importance: "should",
+        expectation: "Metriche di sistema e business esportate.", adoptedBy: ["datadog"] },
+    { id: "observability.tracing", title: "Tracing distribuito", category: "observability", domain: "observability", importance: "should",
+        expectation: "Tracce distribuite end-to-end fra servizi.", adoptedBy: ["datadog"] },
+    { id: "observability.alerts", title: "Alerting", category: "observability", domain: "observability", importance: "should",
+        expectation: "Alert su soglie e anomalie con notifiche.", adoptedBy: ["datadog"] },
+    { id: "observability.analytics", title: "Analytics d'uso", category: "observability", domain: "observability", importance: "nice",
+        expectation: "Analisi d'uso e performance per le pagine/endpoint.", adoptedBy: ["vercel"] },
+    // --- deployment ---
+    { id: "deployment.preview", title: "Deploy di preview", category: "deployment", domain: "deployment", importance: "should",
+        expectation: "Ambiente di anteprima per ogni branch/PR.", adoptedBy: ["vercel"] },
+    { id: "deployment.edge", title: "Esecuzione edge", category: "deployment", domain: "deployment", importance: "nice",
+        expectation: "Distribuzione su edge per bassa latenza globale.", adoptedBy: ["vercel"] },
+    // --- testing / docs (trasversali) ---
+    { id: "testing.automated", title: "Test automatici", category: "testing", domain: "*", importance: "must",
+        expectation: "Suite di test automatici (unit/integration) nella CI." },
+    { id: "docs.api-reference", title: "Documentazione API", category: "docs", domain: "*", importance: "should",
+        expectation: "Reference API completo con esempi.", adoptedBy: ["stripe", "linear"] },
+];
+// ---------------------------------------------------------------------------
+// KnowledgeBase (Piano RELAZIONI) - API di query e confronto.
+// Classe immutabile: i dati restano interni, i metodi ritornano copie.
+// ---------------------------------------------------------------------------
+const IMPORTANCE_WEIGHT = { must: 3, should: 2, nice: 1 };
+function norm(s) {
+    return s.trim().toLowerCase();
+}
+// Domini noti che si applicano "a tutti" (le best practice con domain "*").
+function appliesToDomain(p, domain) {
+    return p.domain === "*" || norm(p.domain) === norm(domain);
+}
+export class KnowledgeBase {
+    competitors;
+    practices;
+    constructor(opts) {
+        this.competitors = opts?.competitors ?? COMPETITORS;
+        this.practices = opts?.practices ?? PRACTICES;
+    }
+    // Istanza con il dataset di default.
+    static default() {
+        return new KnowledgeBase();
+    }
+    // --- Query: concorrenti ---
+    allCompetitors() {
+        return this.competitors;
+    }
+    competitor(id) {
+        return this.competitors.find((c) => norm(c.id) === norm(id));
+    }
+    competitorsByDomain(domain) {
+        return this.competitors.filter((c) => norm(c.domain) === norm(domain));
+    }
+    // --- Query: best practice ---
+    allPractices() {
+        return this.practices;
+    }
+    practice(id) {
+        return this.practices.find((p) => norm(p.id) === norm(id));
+    }
+    practicesByDomain(domain) {
+        return this.practices.filter((p) => appliesToDomain(p, domain));
+    }
+    practicesByCategory(category) {
+        return this.practices.filter((p) => norm(p.category) === norm(String(category)));
+    }
+    // Elenco dei domini coperti dalla knowledge base.
+    domains() {
+        const set = new Set();
+        for (const c of this.competitors)
+            set.add(c.domain);
+        for (const p of this.practices)
+            if (p.domain !== "*")
+                set.add(p.domain);
+        return [...set].sort();
+    }
+    // --- Standard di mercato aggregato ---
+    marketStandard(domain) {
+        return {
+            domain,
+            practices: this.practicesByDomain(domain),
+            competitors: this.competitorsByDomain(domain),
+        };
+    }
+    // --- Confronto con il mercato ---
+    // Confronta un output (insieme di feature/capabilities prodotte) con lo
+    // standard di mercato di un dominio. Le feature possono essere id di best
+    // practice (es. "auth.oauth2") o testo libero; il match e' per id o per
+    // contenimento sul titolo/categoria.
+    compareToMarket(domain, outputFeatures) {
+        const standard = this.practicesByDomain(domain);
+        const have = outputFeatures.map(norm);
+        const matches = (p) => have.some((f) => f === norm(p.id) ||
+            f.includes(norm(p.id)) ||
+            norm(p.id).includes(f) ||
+            f.includes(norm(p.title)) ||
+            norm(p.title).includes(f));
+        const met = [];
+        const gaps = [];
+        for (const p of standard)
+            (matches(p) ? met : gaps).push(p);
+        // Feature dell'output che non corrispondono a nessuno standard del dominio.
+        const matchedIds = new Set(met.map((p) => norm(p.id)));
+        const matchedTitles = met.map((p) => norm(p.title));
+        const extras = outputFeatures.filter((f) => {
+            const nf = norm(f);
+            if (matchedIds.has(nf))
+                return false;
+            return !met.some((p) => nf.includes(norm(p.id)) || norm(p.id).includes(nf) ||
+                nf.includes(norm(p.title)) || matchedTitles.some((t) => t.includes(nf)));
+        });
+        // Score pesato per importanza.
+        const totWeight = standard.reduce((s, p) => s + IMPORTANCE_WEIGHT[p.importance], 0);
+        const metWeight = met.reduce((s, p) => s + IMPORTANCE_WEIGHT[p.importance], 0);
+        const score = totWeight === 0 ? 100 : Math.round((metWeight / totWeight) * 100);
+        const order = { must: 0, should: 1, nice: 2 };
+        const sortedGaps = [...gaps].sort((a, b) => order[a.importance] - order[b.importance]);
+        return {
+            domain,
+            score,
+            met,
+            gaps: sortedGaps,
+            extras,
+            summary: buildComparisonSummary(domain, score, met, sortedGaps, extras),
+        };
+    }
+}
+// Sintesi in notazione Danilov del confronto.
+function buildComparisonSummary(domain, score, met, gaps, extras) {
+    const lines = [];
+    lines.push(`@confronto[${domain}]: score=${score}/100, coperte=${met.length}, gap=${gaps.length}, extra=${extras.length}`);
+    if (gaps.length) {
+        const mustGaps = gaps.filter((g) => g.importance === "must");
+        if (mustGaps.length) {
+            lines.push(`@gap[critici]: ${mustGaps.map((g) => g.title).join(" ; ")}`);
+        }
+        lines.push(`@gap[tutti]: ${gaps.map((g) => `${g.title}(${g.importance})`).join(" ; ")}`);
+    }
+    else {
+        lines.push(`@gap[nessuno]: output allineato allo standard del dominio`);
+    }
+    if (extras.length)
+        lines.push(`@extra[oltre_standard]: ${extras.join(" ; ")}`);
+    return lines.join("\n");
+}
+// Istanza condivisa pronta all'uso.
+export const knowledgeBase = KnowledgeBase.default();

package/dist/vascend/completeness.d.ts

@@ -0,0 +1,16 @@
+import type { Harness } from "../core/bootstrap.js";
+export interface CompletenessVerdict {
+    readonly complete: boolean;
+    readonly missing: readonly string[];
+    readonly uncertain?: boolean;
+    readonly reason?: string;
+}
+export declare function completenessEnabled(env: NodeJS.ProcessEnv): boolean;
+export declare function completenessRounds(env: NodeJS.ProcessEnv): number;
+export declare function judgeCompleteness(opts: {
+    readonly harness: Harness;
+    readonly goal: string;
+    readonly evidence: string;
+    readonly signal: AbortSignal;
+}): Promise<CompletenessVerdict>;
+export declare function buildCompletenessSteer(goal: string, missing: readonly string[]): string;