@vascend/talos 0.1.0

package/dist/vascend/user-profile.d.ts

@@ -0,0 +1,44 @@
+export interface UserFact {
+    readonly id: string;
+    readonly text: string;
+    readonly kind: string;
+    readonly createdAt: number;
+    readonly updatedAt: number;
+    readonly hits: number;
+}
+export interface UserProfile {
+    readonly version: number;
+    readonly facts: readonly UserFact[];
+}
+export declare function readUserProfile(sessionDir: string): UserProfile;
+/**
+ * Aggiunge (o rinforza) un fatto. Un fatto ripetuto non si duplica: sale il
+ * contatore, che e' anche il segnale di quanto conta davvero.
+ */
+export declare function rememberUserFact(sessionDir: string, text: string, kind?: string, now?: number): {
+    readonly ok: boolean;
+    readonly reinforced: boolean;
+    readonly profile: UserProfile;
+};
+export declare function forgetUserFact(sessionDir: string, needle: string): {
+    readonly ok: boolean;
+    readonly removed: number;
+};
+/**
+ * Blocco per il system prompt. Ordine per rinforzo: i fatti che la persona ha
+ * ripetuto stanno in cima. Resta corto per scelta: e' un prefisso, non un
+ * archivio.
+ */
+export declare function formatUserProfile(profile: UserProfile, max?: number): string;
+/**
+ * Nudge deterministico a fine giro: se il lavoro ha prodotto decisioni e in
+ * memoria non e' finito NIENTE, lo si dice una volta. Sperare che il modello si
+ * ricordi da solo di persistere non ha funzionato: la memoria si popolava solo
+ * quando qualcuno la nominava.
+ */
+export declare function persistNudge(input: {
+    readonly memoryWrites: number;
+    readonly editedFiles: number;
+    readonly turns: number;
+    readonly profileFacts?: number;
+}): string;

package/dist/vascend/user-profile.js

@@ -0,0 +1,131 @@
+// Profilo dell'utente: i fatti DUREVOLI che non vanno riscoperti ogni volta.
+//
+// La memoria di progetto risponde a "com'e' fatto questo repo"; le stanze a
+// "cosa ho fatto ieri". Nessuna delle due tiene "chi e' la persona con cui
+// lavoro": come preferisce le risposte, quali decisioni ha gia' preso e non va
+// ridiscusse, quali vincoli valgono sempre. Senza questo strato l'agente
+// ricomincia da zero a ogni sessione e la persona ripete le stesse istruzioni.
+//
+// Vive in un file JSON accanto alle sessioni, e viene iniettato nel PREFISSO del
+// system prompt: sta nella parte cacheabile, quindi costa una volta.
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+const PROFILE_FILE = "user-profile.json";
+const PROFILE_VERSION = 1;
+const MAX_FACTS = 48;
+const MAX_FACT_CHARS = 300;
+const MAX_INJECTED = 14;
+const EMPTY = { version: PROFILE_VERSION, facts: [] };
+function normalize(text) {
+    return String(text || "")
+        .normalize("NFKD")
+        .replace(/[̀-ͯ]/g, "")
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, " ")
+        .trim();
+}
+function profilePath(sessionDir) {
+    return join(sessionDir, PROFILE_FILE);
+}
+export function readUserProfile(sessionDir) {
+    if (!sessionDir)
+        return EMPTY;
+    const file = profilePath(sessionDir);
+    if (!existsSync(file))
+        return EMPTY;
+    try {
+        const parsed = JSON.parse(readFileSync(file, "utf8"));
+        if (!parsed || parsed.version !== PROFILE_VERSION || !Array.isArray(parsed.facts))
+            return EMPTY;
+        return parsed;
+    }
+    catch {
+        return EMPTY;
+    }
+}
+function save(sessionDir, profile) {
+    try {
+        const file = profilePath(sessionDir);
+        mkdirSync(dirname(file), { recursive: true });
+        writeFileSync(file, JSON.stringify(profile), "utf8");
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Aggiunge (o rinforza) un fatto. Un fatto ripetuto non si duplica: sale il
+ * contatore, che e' anche il segnale di quanto conta davvero.
+ */
+export function rememberUserFact(sessionDir, text, kind = "preference", now = Date.now()) {
+    const clean = String(text || "").replace(/\s+/g, " ").trim().slice(0, MAX_FACT_CHARS);
+    if (!clean)
+        return { ok: false, reinforced: false, profile: readUserProfile(sessionDir) };
+    const current = readUserProfile(sessionDir);
+    const key = normalize(clean);
+    const existing = current.facts.find((fact) => normalize(fact.text) === key);
+    const facts = existing
+        ? current.facts.map((fact) => (fact === existing
+            ? { ...fact, text: clean, kind: kind || fact.kind, updatedAt: now, hits: fact.hits + 1 }
+            : fact))
+        : [
+            ...current.facts,
+            { id: `u${now.toString(36)}`, text: clean, kind: kind || "preference", createdAt: now, updatedAt: now, hits: 1 },
+        ];
+    // Quando si sfora il tetto cade il fatto meno rinforzato e piu' vecchio.
+    const pruned = facts.length <= MAX_FACTS
+        ? facts
+        : [...facts].sort((a, b) => b.hits - a.hits || b.updatedAt - a.updatedAt).slice(0, MAX_FACTS);
+    const profile = { version: PROFILE_VERSION, facts: pruned };
+    return { ok: save(sessionDir, profile), reinforced: !!existing, profile };
+}
+export function forgetUserFact(sessionDir, needle) {
+    const key = normalize(needle);
+    if (!key)
+        return { ok: false, removed: 0 };
+    const current = readUserProfile(sessionDir);
+    const facts = current.facts.filter((fact) => !normalize(fact.text).includes(key) && fact.id !== needle);
+    const removed = current.facts.length - facts.length;
+    if (!removed)
+        return { ok: true, removed: 0 };
+    return { ok: save(sessionDir, { version: PROFILE_VERSION, facts }), removed };
+}
+/**
+ * Blocco per il system prompt. Ordine per rinforzo: i fatti che la persona ha
+ * ripetuto stanno in cima. Resta corto per scelta: e' un prefisso, non un
+ * archivio.
+ */
+export function formatUserProfile(profile, max = MAX_INJECTED) {
+    const facts = [...profile.facts]
+        .sort((a, b) => b.hits - a.hits || b.updatedAt - a.updatedAt)
+        .slice(0, Math.max(1, max));
+    if (!facts.length)
+        return "";
+    const lines = facts.map((fact) => `- ${fact.text}`);
+    return [
+        "Chi hai davanti (fatti durevoli, non riscoprirli e non richiederli):",
+        ...lines,
+    ].join("\n");
+}
+/**
+ * Nudge deterministico a fine giro: se il lavoro ha prodotto decisioni e in
+ * memoria non e' finito NIENTE, lo si dice una volta. Sperare che il modello si
+ * ricordi da solo di persistere non ha funzionato: la memoria si popolava solo
+ * quando qualcuno la nominava.
+ */
+export function persistNudge(input) {
+    const { memoryWrites, editedFiles, turns } = input;
+    if (memoryWrites > 0)
+        return "";
+    const worked = editedFiles > 0 || turns >= 6;
+    if (!worked)
+        return "";
+    const what = editedFiles > 0
+        ? `Hai toccato ${editedFiles} file`
+        : `Questo giro e' durato ${turns} turni`;
+    return `${what} e in memoria non e' finito niente. Se resta una decisione che vale domani `
+        + "(perche' una strada e' stata scartata, un vincolo scoperto, una preferenza espressa), "
+        + "scrivila prima di chiudere: vascend_note per il lavoro, user_profile per cio' che riguarda la persona. "
+        + "Se non c'e' nulla da ricordare, procedi senza dirlo.";
+}

package/dist/vascend/vision.d.ts

@@ -0,0 +1,94 @@
+export type FeatureStatus = "proposed" | "agreed" | "built" | "dropped";
+export type FeaturePriority = "core" | "important" | "optional";
+export interface VisionFeature {
+    readonly id: string;
+    readonly title: string;
+    readonly description?: string;
+    readonly priority: FeaturePriority;
+    readonly status: FeatureStatus;
+}
+export interface ReadinessCriterion {
+    readonly id: string;
+    readonly text: string;
+    readonly met: boolean;
+}
+export interface VisionValue {
+    readonly statement: string;
+    readonly beneficiary?: string;
+    readonly metric?: string;
+}
+export interface Vision {
+    readonly version: 1;
+    readonly taskId: string;
+    readonly goal: string;
+    readonly value: VisionValue;
+    readonly features: readonly VisionFeature[];
+    readonly readiness: readonly ReadinessCriterion[];
+    readonly createdAt: string;
+    readonly updatedAt: string;
+}
+export interface VisionDraft {
+    readonly taskId: string;
+    readonly goal: string;
+    readonly value: string | VisionValue;
+    readonly features?: ReadonlyArray<Partial<VisionFeature> & {
+        readonly title: string;
+    }>;
+    readonly readiness?: ReadonlyArray<Partial<ReadinessCriterion> & {
+        readonly text: string;
+    }>;
+}
+export declare const VISION_SCHEMA_VERSION: 1;
+export interface VisionIssue {
+    readonly field: string;
+    readonly message: string;
+}
+export declare function validateVision(v: Vision): readonly VisionIssue[];
+export declare function isVisionValid(v: Vision): boolean;
+export declare function createVision(draft: VisionDraft, opts?: {
+    readonly now?: string;
+}): Vision;
+export declare function parseVision(text: string, opts?: {
+    readonly now?: string;
+}): Vision | null;
+export declare function updateVision(v: Vision, patch: Partial<Pick<Vision, "goal" | "value" | "features" | "readiness">>, opts?: {
+    readonly now?: string;
+}): Vision;
+export declare function visionToJSON(v: Vision): string;
+export declare function visionFromJSON(json: string, opts?: {
+    readonly now?: string;
+}): Vision | null;
+export declare class VascendVisionStore {
+    private readonly file;
+    private readonly memory;
+    private visions;
+    private constructor();
+    static open(sessionDir: string, sessionId: string): VascendVisionStore;
+    has(taskId: string): boolean;
+    get(taskId: string): Vision | undefined;
+    all(): readonly Vision[];
+    set(v: Vision): Vision;
+    update(taskId: string, patch: Partial<Pick<Vision, "goal" | "value" | "features" | "readiness">>, opts?: {
+        readonly now?: string;
+    }): Vision | undefined;
+    remove(taskId: string): boolean;
+    private persist;
+}
+export interface VisionSummary {
+    readonly features: number;
+    readonly coreFeatures: number;
+    readonly builtFeatures: number;
+    readonly readiness: number;
+    readonly readinessMet: number;
+}
+export declare function visionSummary(v: Vision): VisionSummary;
+export interface VisionCompleteness {
+    readonly ratio: number;
+    readonly productionReady: boolean;
+    readonly coreBuilt: number;
+    readonly coreTotal: number;
+    readonly readinessMet: number;
+    readonly readinessTotal: number;
+}
+export declare function visionCompleteness(v: Vision): VisionCompleteness;
+export declare function buildVisionBlock(v: Vision): string;

package/dist/vascend/vision.js

@@ -0,0 +1,375 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { MemoryStore } from "./memory-store.js";
+export const VISION_SCHEMA_VERSION = 1;
+const FEATURE_PRIORITIES = new Set(["core", "important", "optional"]);
+const FEATURE_STATUSES = new Set(["proposed", "agreed", "built", "dropped"]);
+// Tetto anti-esplosione (parita' con requirements).
+const MAX_FEATURES = 30;
+const MAX_READINESS = 30;
+// ---------------------------------------------------------------------------
+// 2. NORMALIZZAZIONE + VALIDAZIONE
+// ---------------------------------------------------------------------------
+function nowIso() {
+    return new Date().toISOString();
+}
+function asString(v) {
+    return typeof v === "string" ? v : v == null ? "" : String(v);
+}
+function normalizeFeaturePriority(v) {
+    const s = asString(v).trim().toLowerCase();
+    return FEATURE_PRIORITIES.has(s) ? s : "core";
+}
+function normalizeFeatureStatus(v) {
+    const s = asString(v).trim().toLowerCase();
+    return FEATURE_STATUSES.has(s) ? s : "agreed";
+}
+function normalizeFeatures(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    const out = [];
+    for (const f of raw) {
+        const obj = (f ?? {});
+        const title = asString(obj["title"]).trim();
+        if (!title)
+            continue;
+        const id = asString(obj["id"]).trim() || `F${out.length + 1}`;
+        const description = asString(obj["description"]).trim();
+        out.push({
+            id,
+            title,
+            ...(description ? { description } : {}),
+            priority: normalizeFeaturePriority(obj["priority"]),
+            status: normalizeFeatureStatus(obj["status"]),
+        });
+        if (out.length >= MAX_FEATURES)
+            break;
+    }
+    return out;
+}
+function normalizeReadiness(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    const out = [];
+    for (const c of raw) {
+        const obj = (c ?? {});
+        const text = asString(obj["text"]).trim();
+        if (!text)
+            continue;
+        const id = asString(obj["id"]).trim() || `RP${out.length + 1}`;
+        out.push({ id, text, met: obj["met"] === true });
+        if (out.length >= MAX_READINESS)
+            break;
+    }
+    return out;
+}
+function normalizeValue(raw) {
+    if (typeof raw === "string")
+        return { statement: raw.trim() };
+    const obj = (raw ?? {});
+    const statement = asString(obj["statement"]).trim();
+    const beneficiary = asString(obj["beneficiary"]).trim();
+    const metric = asString(obj["metric"]).trim();
+    return {
+        statement,
+        ...(beneficiary ? { beneficiary } : {}),
+        ...(metric ? { metric } : {}),
+    };
+}
+// Valida una Vision gia' normalizzata: ritorna la lista (vuota = valida) dei
+// problemi BLOCCANTI. Una Vision e' valida sse ha taskId, goal e value.statement
+// non vuoti; gli id di feature e criteri devono essere univoci.
+export function validateVision(v) {
+    const issues = [];
+    if (!v.taskId.trim())
+        issues.push({ field: "taskId", message: "taskId mancante" });
+    if (!v.goal.trim())
+        issues.push({ field: "goal", message: "goal (obiettivo finale) mancante" });
+    if (!v.value.statement.trim()) {
+        issues.push({ field: "value.statement", message: "valore (perche' conta) mancante" });
+    }
+    if (v.version !== VISION_SCHEMA_VERSION) {
+        issues.push({ field: "version", message: `versione schema attesa ${VISION_SCHEMA_VERSION}` });
+    }
+    const featIds = new Set();
+    for (const f of v.features) {
+        if (featIds.has(f.id))
+            issues.push({ field: `features.${f.id}`, message: "id funzionalita' duplicato" });
+        featIds.add(f.id);
+    }
+    const rpIds = new Set();
+    for (const c of v.readiness) {
+        if (rpIds.has(c.id))
+            issues.push({ field: `readiness.${c.id}`, message: "id criterio duplicato" });
+        rpIds.add(c.id);
+    }
+    return issues;
+}
+export function isVisionValid(v) {
+    return validateVision(v).length === 0;
+}
+// Costruisce una Vision normalizzata e completa a partire da un draft morbido.
+// Applica default, genera gli id mancanti e i timestamp. NON lancia: produce
+// sempre un oggetto Vision (eventualmente non valido, da controllare con
+// validateVision).
+export function createVision(draft, opts) {
+    const ts = opts?.now ?? nowIso();
+    return {
+        version: VISION_SCHEMA_VERSION,
+        taskId: asString(draft.taskId).trim(),
+        goal: asString(draft.goal).trim(),
+        value: normalizeValue(draft.value),
+        features: normalizeFeatures(draft.features),
+        readiness: normalizeReadiness(draft.readiness),
+        createdAt: ts,
+        updatedAt: ts,
+    };
+}
+// Parsing robusto da testo/JSON: estrae il primo blocco {...}, normalizza tutto.
+// Mai lancia: su input non valido ritorna null. Conserva i timestamp se presenti,
+// altrimenti li genera.
+export function parseVision(text, opts) {
+    const m = /\{[\s\S]*\}/.exec(text);
+    if (!m)
+        return null;
+    let root;
+    try {
+        root = JSON.parse(m[0]);
+    }
+    catch {
+        return null;
+    }
+    const ts = opts?.now ?? nowIso();
+    const createdAt = asString(root["createdAt"]).trim() || ts;
+    const updatedAt = asString(root["updatedAt"]).trim() || ts;
+    return {
+        version: VISION_SCHEMA_VERSION,
+        taskId: asString(root["taskId"]).trim(),
+        goal: asString(root["goal"]).trim(),
+        value: normalizeValue(root["value"]),
+        features: normalizeFeatures(root["features"]),
+        readiness: normalizeReadiness(root["readiness"]),
+        createdAt,
+        updatedAt,
+    };
+}
+// Aggiornamento immutabile: applica una patch e rinfresca updatedAt. I campi
+// passati sostituiscono quelli esistenti (le liste vanno gia' normalizzate dal
+// chiamante o passate come draft-like e ri-normalizzate qui).
+export function updateVision(v, patch, opts) {
+    return {
+        ...v,
+        ...(patch.goal !== undefined ? { goal: asString(patch.goal).trim() } : {}),
+        ...(patch.value !== undefined ? { value: normalizeValue(patch.value) } : {}),
+        ...(patch.features !== undefined ? { features: normalizeFeatures(patch.features) } : {}),
+        ...(patch.readiness !== undefined ? { readiness: normalizeReadiness(patch.readiness) } : {}),
+        updatedAt: opts?.now ?? nowIso(),
+    };
+}
+// ---------------------------------------------------------------------------
+// 3. SERIALIZZAZIONE + STORE PERSISTENTE
+// ---------------------------------------------------------------------------
+// Serializza in stringa JSON stabile (chiavi in ordine deterministico, indentata).
+export function visionToJSON(v) {
+    const ordered = {
+        version: v.version,
+        taskId: v.taskId,
+        goal: v.goal,
+        value: {
+            statement: v.value.statement,
+            ...(v.value.beneficiary ? { beneficiary: v.value.beneficiary } : {}),
+            ...(v.value.metric ? { metric: v.value.metric } : {}),
+        },
+        features: v.features.map((f) => ({
+            id: f.id,
+            title: f.title,
+            ...(f.description ? { description: f.description } : {}),
+            priority: f.priority,
+            status: f.status,
+        })),
+        readiness: v.readiness.map((c) => ({ id: c.id, text: c.text, met: c.met })),
+        createdAt: v.createdAt,
+        updatedAt: v.updatedAt,
+    };
+    return JSON.stringify(ordered, null, 2);
+}
+// Deserializza da JSON. Alias semantico di parseVision per simmetria con toJSON.
+export function visionFromJSON(json, opts) {
+    return parseVision(json, opts);
+}
+// Store persistente per sessione: una Vision per task, file
+// `<sessionId>.vision.json` -> mappa { [taskId]: Vision }. Stesso stile di
+// VascendPlanStore: API immutabile verso l'esterno, persistenza su mutazione.
+export class VascendVisionStore {
+    file;
+    memory;
+    visions = {};
+    constructor(file, memory) {
+        this.file = file;
+        this.memory = memory;
+    }
+    static open(sessionDir, sessionId) {
+        const store = new VascendVisionStore(join(sessionDir, `${sessionId}.vision.json`), MemoryStore.open(sessionDir, sessionId));
+        if (existsSync(store.file)) {
+            try {
+                const raw = JSON.parse(readFileSync(store.file, "utf8"));
+                const out = {};
+                for (const [taskId, val] of Object.entries(raw ?? {})) {
+                    const parsed = parseVision(JSON.stringify(val));
+                    if (parsed)
+                        out[taskId] = { ...parsed, taskId: parsed.taskId || taskId };
+                }
+                store.visions = out;
+            }
+            catch {
+                // file corrotto: si riparte vuoti
+            }
+        }
+        return store;
+    }
+    has(taskId) {
+        return Boolean(this.visions[taskId.trim()]);
+    }
+    get(taskId) {
+        return this.visions[taskId.trim()];
+    }
+    all() {
+        return Object.values(this.visions);
+    }
+    // Salva (crea o sostituisce) la Vision di un task. Ritorna la Vision salvata.
+    set(v) {
+        const taskId = v.taskId.trim();
+        this.visions = { ...this.visions, [taskId]: { ...v, taskId } };
+        this.persist();
+        this.memory.append(visionEvent("vision.updated", this.visions[taskId]));
+        return this.visions[taskId];
+    }
+    // Aggiorna immutabilmente la Vision di un task con una patch. No-op (ritorna
+    // undefined) se non esiste.
+    update(taskId, patch, opts) {
+        const cur = this.visions[taskId.trim()];
+        if (!cur)
+            return undefined;
+        return this.set(updateVision(cur, patch, opts));
+    }
+    remove(taskId) {
+        const id = taskId.trim();
+        if (!this.visions[id])
+            return false;
+        const { [id]: _drop, ...rest } = this.visions;
+        this.visions = rest;
+        this.persist();
+        this.memory.append({
+            type: "vision.removed",
+            domain: "vision",
+            subject: id,
+            summary: `Vision rimossa: ${id}`,
+            body: "",
+            terms: [id, "vision", "rimossa"],
+            payload: { taskId: id },
+        });
+        return true;
+    }
+    persist() {
+        mkdirSync(dirname(this.file), { recursive: true });
+        const ordered = {};
+        for (const [taskId, v] of Object.entries(this.visions)) {
+            ordered[taskId] = JSON.parse(visionToJSON(v));
+        }
+        writeFileSync(this.file, JSON.stringify(ordered, null, 2) + "\n", "utf8");
+    }
+}
+function visionEvent(type, vision) {
+    const features = vision.features.filter((f) => f.status !== "dropped");
+    const readiness = vision.readiness;
+    return {
+        type,
+        domain: "vision",
+        subject: vision.taskId,
+        summary: vision.goal,
+        body: buildVisionBlock(vision),
+        terms: [
+            vision.taskId,
+            vision.goal,
+            vision.value.statement,
+            ...features.flatMap((f) => [f.id, f.title, f.priority, f.status]),
+            ...readiness.flatMap((r) => [r.id, r.text, r.met ? "met" : "todo"]),
+        ],
+        links: [
+            ...features.map((f) => ({ rel: "requires", target: f.id, domain: "vision" })),
+            ...readiness.map((r) => ({ rel: "readiness", target: r.id, domain: "vision" })),
+        ],
+        payload: { vision },
+    };
+}
+export function visionSummary(v) {
+    const active = v.features.filter((f) => f.status !== "dropped");
+    return {
+        features: active.length,
+        coreFeatures: active.filter((f) => f.priority === "core").length,
+        builtFeatures: active.filter((f) => f.status === "built").length,
+        readiness: v.readiness.length,
+        readinessMet: v.readiness.filter((c) => c.met).length,
+    };
+}
+export function visionCompleteness(v) {
+    const core = v.features.filter((f) => f.priority === "core" && f.status !== "dropped");
+    const coreBuilt = core.filter((f) => f.status === "built").length;
+    const readinessMet = v.readiness.filter((c) => c.met).length;
+    const total = core.length + v.readiness.length;
+    const done = coreBuilt + readinessMet;
+    const ratio = total === 0 ? 1 : done / total;
+    return {
+        ratio,
+        productionReady: coreBuilt === core.length && readinessMet === v.readiness.length,
+        coreBuilt,
+        coreTotal: core.length,
+        readinessMet,
+        readinessTotal: v.readiness.length,
+    };
+}
+const FEATURE_PRIORITY_TAG = {
+    core: "CORE",
+    important: "IMPORTANT",
+    optional: "OPTIONAL",
+};
+function q(s, max = 200) {
+    return s.replace(/"/g, "'").slice(0, max);
+}
+// Formatta la Vision in notazione Danilov: blocco di contesto (steer) da
+// iniettare all'agente, parita' con buildRequirementsBlock. Ritorna "" se la
+// Vision e' priva di goal.
+export function buildVisionBlock(v) {
+    if (!v.goal.trim())
+        return "";
+    const featDefs = v.features
+        .filter((f) => f.status !== "dropped")
+        .map((f) => {
+        const desc = f.description ? ` -> ${q(f.description, 120)}` : "";
+        return `@${f.id}[${FEATURE_PRIORITY_TAG[f.priority]}/${f.status}]: ${q(f.title, 160)}${desc}`;
+    });
+    const rpDefs = v.readiness.map((c) => `@${c.id}[${c.met ? "MET" : "TODO"}]: ${q(c.text, 160)}`);
+    const valLine = [v.value.statement, v.value.beneficiary && `per ${v.value.beneficiary}`, v.value.metric && `(metrica: ${v.value.metric})`]
+        .filter(Boolean)
+        .join(" ");
+    const comp = visionCompleteness(v);
+    return `[VASCEND_VISION]
+INDICE
+1 = obiettivo
+2 = valore
+3 = funzionalita
+4 = pronto-produzione
+
+DEFINIZIONI
+@obiettivo[finale]: "${q(v.goal)}"
+@valore[perche]: "${q(valLine || "(non specificato)")}"
+${featDefs.length ? featDefs.join("\n") : "@funzionalita[nessuna]: -"}
+${rpDefs.length ? rpDefs.join("\n") : "@pronto[nessun-criterio]: -"}
+
+RELAZIONI
+@R-goal: @obiettivo[finale] -> @valore[perche]  [ il lavoro esiste per realizzare questo valore ]
+@R-feat: funzionalita[CORE] -> @obiettivo[finale]  [ le core sono indispensabili all'obiettivo ]
+@R-rp: @pronto -> consegna  [ spedibile sse ogni CORE e' built e ogni criterio e' MET ]
+
+OUTPUT: questa e' la Vision condivisa del task; pronto-per-produzione=${comp.productionReady} (core ${comp.coreBuilt}/${comp.coreTotal}, readiness ${comp.readinessMet}/${comp.readinessTotal}).`;
+}

package/dist/vascend/work-agent.d.ts

@@ -0,0 +1,12 @@
+import { type AgentDeps } from "../core/agent.js";
+import type { AgentEvent } from "../core/types.js";
+import type { ItemOutcome } from "./work-runner.js";
+import type { WorkItem } from "./work-queue.js";
+export declare function briefFor(item: WorkItem): string;
+export declare function parseOutcome(text: string): ItemOutcome;
+export interface FreshAgentOptions {
+    readonly memoryScopeId?: string;
+    readonly planStoreId?: string;
+    readonly onEvent?: (item: WorkItem, event: AgentEvent) => void;
+}
+export declare function createFreshAgentRunner(base: AgentDeps, options?: FreshAgentOptions): (item: WorkItem, signal: AbortSignal) => Promise<ItemOutcome>;