@multileaf/ai-workflow 0.2.1 → 0.3.0

package/CHANGELOG.md

@@ -4,6 +4,19 @@ All notable changes to this project are documented in this file. The format foll
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-10-08
+
+### Added
+
+- Optional semantic mapping in `aiw scan`: when `.aiw/semantic.yml` enables a local embedding model (for example Ollama `embeddinggemma-2`), the scan verifies model availability, embeds line-aligned file chunks, and writes a versioned index to `.aiw/semantic/index.json`.
+- `aiw semantic query` and `aiw semantic status` commands for cosine-similarity retrieval over the semantic index, gated by the same configuration flag.
+- Advisory decision triage via a local decision model (`jev/clef-flash` through Ollama `/v1/systemone`): flag-gated by `.aiw/decision.yml`, `aiw decision status` and `aiw decision triage --artifact=<path>` return advisory evidence-completeness and gate decisions with confidence, never replacing human approval.
+- Documentation for semantic mapping and an evaluation of the `jev/clef` decision model for advisory flow decisions.
+
+### Fixed
+
+- Removed high-severity transitive vulnerabilities (`brace-expansion`, `source-map-js`) reported by `npm audit`.
+
 ## [0.2.1] - 2026-09-13
 
 ### Changed

package/dist/decision.d.ts

@@ -0,0 +1,49 @@
+import type { FileSystem } from "./types.js";
+export type DecisionConfig = {
+    enabled: boolean;
+    model: string;
+    baseUrl: string;
+};
+export type DecisionQuestion = {
+    type: "noul";
+    instructions: string;
+    criteria?: {
+        true: string;
+        false: string;
+    };
+} | {
+    type: "choice";
+    instructions: string;
+    criteria: Record<string, string | null>;
+} | {
+    type: "score";
+    instructions: string;
+    criteria: string[];
+};
+export type DecisionAnswer = {
+    type: "noul" | "choice" | "score";
+    noul?: number;
+    choice?: string;
+    score?: number;
+    probabilities?: Record<string, number>;
+    confidence?: number;
+};
+export type DecisionRequest = {
+    state: string;
+    questions: Record<string, DecisionQuestion>;
+};
+export type DecisionResponse = {
+    model: string;
+    answers: Record<string, DecisionAnswer>;
+};
+export type DecisionProvider = {
+    available(): Promise<boolean>;
+    decide(request: DecisionRequest): Promise<DecisionResponse>;
+};
+export declare const DECISION_CONFIG_PATH = "decision.yml";
+export declare const DEFAULT_DECISION_CONFIG: DecisionConfig;
+export declare function parseDecisionConfig(text: string): DecisionConfig;
+export declare function loadDecisionConfig(fs: FileSystem, aiwPath: string): DecisionConfig | undefined;
+export declare function parseDecisionResponse(text: string): DecisionResponse;
+export declare function createOllamaDecisionProvider(config: DecisionConfig): DecisionProvider;
+export declare function buildEvidenceTriageRequest(artifact: string): DecisionRequest;

package/dist/decision.js

@@ -0,0 +1,105 @@
+import { parseDocument } from "yaml";
+export const DECISION_CONFIG_PATH = "decision.yml";
+export const DEFAULT_DECISION_CONFIG = {
+    enabled: false,
+    model: "clef-flash:latest",
+    baseUrl: "http://localhost:11434",
+};
+export function parseDecisionConfig(text) {
+    const document = parseDocument(text);
+    const node = document.get("decision");
+    if (document.errors.length > 0 || !node || typeof node !== "object")
+        throw new Error("Decision configuration must be a YAML object with a `decision` mapping");
+    const raw = node.toJSON();
+    const enabled = raw.enabled;
+    const model = raw.model;
+    const baseUrl = raw.baseUrl;
+    if (typeof enabled !== "boolean")
+        throw new Error("decision.enabled must be a boolean");
+    if (!enabled)
+        return { ...DEFAULT_DECISION_CONFIG, enabled: false };
+    if (typeof model !== "string" || model.trim() === "")
+        throw new Error("decision.model must be a non-empty string when decision mapping is enabled");
+    if (typeof baseUrl !== "string" || !/^https?:\/\//i.test(baseUrl))
+        throw new Error("decision.baseUrl must be an http(s) URL when decision mapping is enabled");
+    return { enabled: true, model, baseUrl };
+}
+export function loadDecisionConfig(fs, aiwPath) {
+    const configPath = `${aiwPath}/${DECISION_CONFIG_PATH}`;
+    if (!fs.exists(configPath))
+        return undefined;
+    return parseDecisionConfig(fs.read(configPath));
+}
+function parseAnswer(value) {
+    if (!value || typeof value !== "object")
+        throw new Error("Invalid decision answer");
+    const raw = value;
+    if (raw.type !== "noul" && raw.type !== "choice" && raw.type !== "score")
+        throw new Error("Invalid decision answer type");
+    return { ...raw, type: raw.type };
+}
+export function parseDecisionResponse(text) {
+    const parsed = JSON.parse(text);
+    const answers = parsed.answers;
+    if (typeof parsed.model !== "string" || !answers || typeof answers !== "object")
+        throw new Error("Invalid decision response");
+    const result = {};
+    for (const [key, value] of Object.entries(answers))
+        result[key] = parseAnswer(value);
+    return { model: parsed.model, answers: result };
+}
+export function createOllamaDecisionProvider(config) {
+    return {
+        async available() {
+            try {
+                const response = await fetch(`${config.baseUrl}/api/tags`);
+                if (!response.ok)
+                    return false;
+                const body = (await response.json());
+                const names = new Set((body.models ?? []).flatMap((entry) => typeof entry?.name === "string" && typeof entry?.model === "string"
+                    ? [entry.name, entry.model]
+                    : []));
+                return names.has(config.model);
+            }
+            catch {
+                return false;
+            }
+        },
+        async decide(request) {
+            const questionCount = Object.keys(request.questions).length;
+            if (questionCount === 0 || questionCount > 64)
+                throw new Error("Decision requests must contain between 1 and 64 questions");
+            const response = await fetch(`${config.baseUrl}/v1/systemone`, {
+                method: "POST",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify({
+                    model: config.model,
+                    state: request.state,
+                    questions: request.questions,
+                }),
+            });
+            if (!response.ok)
+                throw new Error(`Decision request failed for model ${config.model}: ${await response.text()}`);
+            return parseDecisionResponse(await response.text());
+        },
+    };
+}
+export function buildEvidenceTriageRequest(artifact) {
+    return {
+        state: artifact,
+        questions: {
+            evidence_complete: {
+                type: "noul",
+                instructions: "Does this artifact include concrete verification evidence for every stated requirement?",
+            },
+            gate: {
+                type: "choice",
+                instructions: "Should this artifact advance to human review?",
+                criteria: {
+                    ready: "Every requirement has matching evidence and validation commands",
+                    "needs-work": "Evidence is missing, incomplete, or does not cover all requirements",
+                },
+            },
+        },
+    };
+}

package/dist/semantic.d.ts

@@ -0,0 +1,39 @@
+import type { FileSystem } from "./types.js";
+export type SemanticConfig = {
+    enabled: boolean;
+    model: string;
+    baseUrl: string;
+    chunkChars: number;
+    topK: number;
+};
+export type SemanticIndexChunk = {
+    file: string;
+    text: string;
+    vector: number[];
+};
+export type SemanticIndex = {
+    schema: 1;
+    model: string;
+    chunks: SemanticIndexChunk[];
+};
+export type SemanticMatch = {
+    file: string;
+    score: number;
+    excerpt: string;
+};
+export type EmbeddingProvider = {
+    available(): Promise<boolean>;
+    embed(texts: string[]): Promise<number[][]>;
+};
+export declare const SEMANTIC_CONFIG_PATH = "semantic.yml";
+export declare const SEMANTIC_INDEX_PATH = "semantic/index.json";
+export declare const DEFAULT_SEMANTIC_CONFIG: SemanticConfig;
+export declare function parseSemanticConfig(text: string): SemanticConfig;
+export declare function loadSemanticConfig(fs: FileSystem, aiwPath: string): SemanticConfig | undefined;
+export declare function createOllamaEmbeddingProvider(config: SemanticConfig): EmbeddingProvider;
+export declare function chunkText(content: string, chunkChars: number): string[];
+export declare function cosineSimilarity(a: number[], b: number[]): number;
+export declare function buildSemanticIndex(files: string[], readContent: (file: string) => Promise<string | undefined>, provider: EmbeddingProvider, config: SemanticConfig): Promise<SemanticIndex>;
+export declare function serializeSemanticIndex(index: SemanticIndex): string;
+export declare function parseSemanticIndex(text: string): SemanticIndex;
+export declare function querySemanticIndex(index: SemanticIndex, query: string, provider: EmbeddingProvider, config: SemanticConfig): Promise<SemanticMatch[]>;

package/dist/semantic.js

@@ -0,0 +1,160 @@
+import { parseDocument } from "yaml";
+export const SEMANTIC_CONFIG_PATH = "semantic.yml";
+export const SEMANTIC_INDEX_PATH = "semantic/index.json";
+export const DEFAULT_SEMANTIC_CONFIG = {
+    enabled: false,
+    model: "embeddinggemma-2:latest",
+    baseUrl: "http://localhost:11434",
+    chunkChars: 1200,
+    topK: 8,
+};
+export function parseSemanticConfig(text) {
+    const document = parseDocument(text);
+    const node = document.get("semantic");
+    if (document.errors.length > 0 || !node || typeof node !== "object")
+        throw new Error("Semantic configuration must be a YAML object with a `semantic` mapping");
+    const raw = node.toJSON();
+    const enabled = raw.enabled;
+    const model = raw.model;
+    const baseUrl = raw.baseUrl;
+    const chunkChars = raw.chunkChars;
+    const topK = raw.topK;
+    if (typeof enabled !== "boolean")
+        throw new Error("semantic.enabled must be a boolean");
+    if (!enabled)
+        return { ...DEFAULT_SEMANTIC_CONFIG, enabled: false };
+    if (typeof model !== "string" || model.trim() === "")
+        throw new Error("semantic.model must be a non-empty string when semantic mapping is enabled");
+    if (typeof baseUrl !== "string" || !/^https?:\/\//i.test(baseUrl))
+        throw new Error("semantic.baseUrl must be an http(s) URL when semantic mapping is enabled");
+    const parsedChunk = chunkChars === undefined ? DEFAULT_SEMANTIC_CONFIG.chunkChars : chunkChars;
+    const parsedTopK = topK === undefined ? DEFAULT_SEMANTIC_CONFIG.topK : topK;
+    if (typeof parsedChunk !== "number" || !Number.isInteger(parsedChunk) || parsedChunk < 200)
+        throw new Error("semantic.chunkChars must be an integer of at least 200");
+    if (typeof parsedTopK !== "number" || !Number.isInteger(parsedTopK) || parsedTopK < 1)
+        throw new Error("semantic.topK must be a positive integer");
+    return { enabled: true, model, baseUrl, chunkChars: parsedChunk, topK: parsedTopK };
+}
+export function loadSemanticConfig(fs, aiwPath) {
+    const configPath = `${aiwPath}/${SEMANTIC_CONFIG_PATH}`;
+    if (!fs.exists(configPath))
+        return undefined;
+    return parseSemanticConfig(fs.read(configPath));
+}
+export function createOllamaEmbeddingProvider(config) {
+    const fetchImpl = (url, init) => fetch(url, init);
+    return {
+        async available() {
+            try {
+                const response = await fetchImpl(`${config.baseUrl}/api/tags`);
+                if (!response.ok)
+                    return false;
+                const body = (await response.json());
+                const names = new Set((body.models ?? []).flatMap((entry) => typeof entry?.name === "string" && typeof entry?.model === "string"
+                    ? [entry.name, entry.model]
+                    : []));
+                return names.has(config.model);
+            }
+            catch {
+                return false;
+            }
+        },
+        async embed(texts) {
+            const vectors = [];
+            for (const text of texts) {
+                const response = await fetchImpl(`${config.baseUrl}/api/embeddings`, {
+                    method: "POST",
+                    headers: { "content-type": "application/json" },
+                    body: JSON.stringify({ model: config.model, prompt: text }),
+                });
+                if (!response.ok)
+                    throw new Error(`Embedding request failed for model ${config.model}`);
+                const body = (await response.json());
+                if (!Array.isArray(body.embedding) || body.embedding.some((v) => typeof v !== "number"))
+                    throw new Error(`Embedding model ${config.model} returned an invalid vector`);
+                vectors.push(body.embedding);
+            }
+            return vectors;
+        },
+    };
+}
+export function chunkText(content, chunkChars) {
+    const lines = content.split("\n");
+    const chunks = [];
+    let current = [];
+    let length = 0;
+    for (const line of lines) {
+        if (length + line.length + 1 > chunkChars && current.length > 0) {
+            chunks.push(current.join("\n"));
+            current = [];
+            length = 0;
+        }
+        current.push(line);
+        length += line.length + 1;
+    }
+    if (current.length > 0 && current.join("").trim().length > 0)
+        chunks.push(current.join("\n"));
+    return chunks;
+}
+export function cosineSimilarity(a, b) {
+    let dot = 0;
+    let normA = 0;
+    let normB = 0;
+    for (let index = 0; index < a.length && index < b.length; index += 1) {
+        dot += a[index] * b[index];
+        normA += a[index] * a[index];
+        normB += b[index] * b[index];
+    }
+    if (normA === 0 || normB === 0)
+        return 0;
+    return dot / (Math.sqrt(normA) * Math.sqrt(normB));
+}
+export async function buildSemanticIndex(files, readContent, provider, config) {
+    const entries = [];
+    for (const file of files) {
+        const content = await readContent(file);
+        if (content === undefined)
+            continue;
+        for (const chunk of chunkText(content, config.chunkChars))
+            entries.push({ file, text: chunk });
+    }
+    if (entries.length === 0)
+        return { schema: 1, model: config.model, chunks: [] };
+    const vectors = await provider.embed(entries.map((entry) => entry.text));
+    return {
+        schema: 1,
+        model: config.model,
+        chunks: entries.map((entry, index) => ({ ...entry, vector: vectors[index] })),
+    };
+}
+export function serializeSemanticIndex(index) {
+    return JSON.stringify(index);
+}
+export function parseSemanticIndex(text) {
+    const parsed = JSON.parse(text);
+    if (parsed.schema !== 1 || typeof parsed.model !== "string" || !Array.isArray(parsed.chunks))
+        throw new Error("Invalid semantic index");
+    for (const chunk of parsed.chunks) {
+        if (typeof chunk.file !== "string" ||
+            typeof chunk.text !== "string" ||
+            !Array.isArray(chunk.vector) ||
+            chunk.vector.some((value) => typeof value !== "number"))
+            throw new Error("Invalid semantic index chunk");
+    }
+    return parsed;
+}
+export async function querySemanticIndex(index, query, provider, config) {
+    if (index.model !== config.model)
+        throw new Error(`Semantic index was built with ${index.model} but the active semantic model is ${config.model}`);
+    if (index.chunks.length === 0)
+        return [];
+    const [vector] = await provider.embed([query]);
+    return index.chunks
+        .map((chunk) => ({
+        file: chunk.file,
+        score: cosineSimilarity(vector, chunk.vector),
+        excerpt: chunk.text.split("\n").slice(0, 3).join("\n").slice(0, 200),
+    }))
+        .sort((a, b) => b.score - a.score)
+        .slice(0, config.topK);
+}

package/dist/telemetry.js

@@ -13,6 +13,7 @@ const TELEMETRY_COMMANDS = new Set([
     "context",
     "context-quality",
     "context-summary",
+    "decision",
     "doctor",
     "gate",
     "generate",
@@ -29,6 +30,7 @@ const TELEMETRY_COMMANDS = new Set([
     "rollback",
     "scan",
     "self-validate",
+    "semantic",
     "skills",
     "spec",
     "status",

package/dist/workflow.js

@@ -21,6 +21,8 @@ import { validatePackageContract } from "./package-contract.js";
 import { parseLock, resolvePackage, serializeLock } from "./lockfile.js";
 import { executeVercelSkills, installVercelSkill, nodeCommandExecutor } from "./vercel-skills.js";
 import { scanProject } from "./scanner.js";
+import { buildEvidenceTriageRequest, createOllamaDecisionProvider, loadDecisionConfig, DECISION_CONFIG_PATH, } from "./decision.js";
+import { buildSemanticIndex, createOllamaEmbeddingProvider, loadSemanticConfig, parseSemanticIndex, querySemanticIndex, SEMANTIC_INDEX_PATH, serializeSemanticIndex, } from "./semantic.js";
 import { assertKnownPermissions, assertPermissions, assertPackagePermissions, serializePermissionReview, } from "./package-audit.js";
 import { planPackageUpdate } from "./package-updates.js";
 import { searchRegistry, serializeRegistry } from "./registry.js";
@@ -426,8 +428,126 @@ export async function runCommand(args, root, fs, services = {}) {
                 .map((fact) => `  - key: ${fact.key}\n    value: ${fact.value}\n    state: ${fact.state}\n    method: ${fact.method}\n    confidence: ${fact.confidence}${fact.requiresConfirmation === undefined ? "" : `\n    requires_confirmation: ${fact.requiresConfirmation}`}\n    evidence: [${fact.evidence.map((item) => `"${item.source}"`).join(", ")}]`)
                 .join("\n");
             fs.write(join(aiw, "profile.yml"), `schema: 1\nstatus: scanned\nfacts:\n${evidence}\nruntime:\n  languages: [${profile.runtime.languages.join(", ")}]\nframeworks: [${profile.frameworks.join(", ")}]\npackage_manager: ${profile.packageManager}\nquality:\n  linter: ${profile.quality.linter?.name ?? "unknown"}\n  linter_command: ${profile.quality.linter?.command ?? "unknown"}\n  formatter: ${profile.quality.formatter?.name ?? "unknown"}\n  formatter_command: ${profile.quality.formatter?.command ?? "unknown"}\n  typecheck: ${profile.quality.typecheck?.name ?? "unknown"}\n  typecheck_command: ${profile.quality.typecheck?.command ?? "unknown"}\ntesting: ${profile.testing?.name ?? "unknown"}\ntesting_command: ${profile.testing?.command ?? "unknown"}\nci: [${profile.ci.join(", ")}]\nworkspaces: [${profile.workspaces.join(", ")}]\nproject_modules: ${JSON.stringify(profile.modules ?? [])}\npolicies:\n  artifact_language: en\n`);
+            const semanticConfig = loadSemanticConfig(fs, aiw);
+            if (semanticConfig?.enabled) {
+                const provider = createOllamaEmbeddingProvider(semanticConfig);
+                if (!(await provider.available()))
+                    return {
+                        exitCode: 1,
+                        error: `Semantic model ${semanticConfig.model} is not available at ${semanticConfig.baseUrl}.`,
+                    };
+                const scanFiles = await (services.scanner?.scan(root) ?? scanProject(root));
+                const index = await buildSemanticIndex(scanFiles.files, async (file) => {
+                    const absolute = join(root, file);
+                    try {
+                        return new TextDecoder("utf-8", { fatal: true }).decode(fs.readBytes?.(absolute) ?? Buffer.from(fs.read(absolute), "utf8"));
+                    }
+                    catch {
+                        return undefined;
+                    }
+                }, provider, semanticConfig);
+                fs.mkdir(join(aiw, "semantic"));
+                fs.write(join(aiw, SEMANTIC_INDEX_PATH), serializeSemanticIndex(index));
+            }
             return { exitCode: 0, output: "Project profile generated." };
         }
+        if (command === "decision") {
+            const usage = "Usage: aiw decision triage --artifact=<path> | aiw decision status";
+            const action = args[1];
+            const config = loadDecisionConfig(fs, aiw);
+            if (action === "status") {
+                if (!config)
+                    return {
+                        exitCode: 0,
+                        output: `Decision model is not configured. Create .aiw/${DECISION_CONFIG_PATH} to enable it.`,
+                    };
+                return {
+                    exitCode: 0,
+                    output: `Decision model ${config.enabled ? "enabled" : "disabled"}: ${config.model} at ${config.baseUrl}`,
+                };
+            }
+            if (action === "triage") {
+                const parsed = parseNamedOptions(args.slice(2), ["artifact"]);
+                if (!parsed?.artifact)
+                    return { exitCode: 1, error: usage };
+                if (!config?.enabled)
+                    return {
+                        exitCode: 1,
+                        error: "Decision model is disabled. Set decision.enabled=true in .aiw/decision.yml.",
+                    };
+                const artifactPath = safeProjectFile(root, parsed.artifact, fs);
+                if (!fs.exists(artifactPath))
+                    return { exitCode: 1, error: `Artifact not found: ${parsed.artifact}` };
+                const provider = createOllamaDecisionProvider(config);
+                if (!(await provider.available()))
+                    return {
+                        exitCode: 1,
+                        error: `Decision model ${config.model} is not available at ${config.baseUrl}.`,
+                    };
+                const decision = await provider.decide(buildEvidenceTriageRequest(fs.read(artifactPath)));
+                const gate = decision.answers.gate;
+                const evidence = decision.answers.evidence_complete;
+                return {
+                    exitCode: 0,
+                    output: [
+                        "Advisory decision (never replaces human approval):",
+                        `  gate: ${gate?.choice ?? "unknown"} (confidence ${formatConfidence(gate?.confidence)})`,
+                        `  evidence_complete: ${formatNoul(evidence?.noul)}`,
+                    ].join("\n"),
+                };
+            }
+            return { exitCode: 1, error: usage };
+        }
+        if (command === "semantic") {
+            const usage = "Usage: aiw semantic query --text=<query> | aiw semantic status";
+            const action = args[1];
+            if (action === "status") {
+                const config = loadSemanticConfig(fs, aiw);
+                if (!config)
+                    return {
+                        exitCode: 0,
+                        output: `Semantic mapping is not configured. Create .aiw/${"semantic.yml"} to enable it.`,
+                    };
+                const indexPath = join(aiw, SEMANTIC_INDEX_PATH);
+                const built = fs.exists(indexPath)
+                    ? `indexed chunks: ${parseSemanticIndex(fs.read(indexPath)).chunks.length}`
+                    : "index: not built (run aiw scan)";
+                return {
+                    exitCode: 0,
+                    output: `Semantic mapping ${config.enabled ? "enabled" : "disabled"}: model ${config.model} at ${config.baseUrl}\n${built}`,
+                };
+            }
+            if (action === "query") {
+                const parsed = parseNamedOptions(args.slice(2), ["text"]);
+                if (!parsed?.text)
+                    return { exitCode: 1, error: usage };
+                const config = loadSemanticConfig(fs, aiw);
+                if (!config?.enabled)
+                    return {
+                        exitCode: 1,
+                        error: "Semantic mapping is disabled. Set semantic.enabled=true in .aiw/semantic.yml.",
+                    };
+                const indexPath = join(aiw, SEMANTIC_INDEX_PATH);
+                if (!fs.exists(indexPath))
+                    return { exitCode: 1, error: "Semantic index is missing. Run `aiw scan` first." };
+                const provider = createOllamaEmbeddingProvider(config);
+                if (!(await provider.available()))
+                    return {
+                        exitCode: 1,
+                        error: `Semantic model ${config.model} is not available at ${config.baseUrl}.`,
+                    };
+                const matches = await querySemanticIndex(parseSemanticIndex(fs.read(indexPath)), parsed.text, provider, config);
+                return {
+                    exitCode: 0,
+                    output: matches.length === 0
+                        ? "No semantic matches."
+                        : matches
+                            .map((match) => `- ${match.file} (score ${match.score.toFixed(3)})\n  ${match.excerpt}`)
+                            .join("\n"),
+                };
+            }
+            return { exitCode: 1, error: usage };
+        }
         if (command === "target") {
             const target = args[1];
             if (!target)
@@ -1586,7 +1706,7 @@ export async function runCommand(args, root, fs, services = {}) {
         }
         return {
             exitCode: 0,
-            output: "aiw install [--target target] | workflow <start|status|complete> [--id=id] | approve <stage> | reject <stage> --reason=text | skip <optional-stage> --reason=text | ui [--port=number] | orchestrate --plan=path [--execute] [--max-parallel=number] | telemetry <status|enable|disable> [privacy options] | plugin <create|validate> [options] | scan | self-validate --ticket=TYPE-000 | organization-policy --file=path [--replace] | policy-check --package=path [--package=path] | preset --file=path [--replace] | context | context-summary | context-quality | capabilities [--target=target] | token-usage [--stage=name --budget=number --used=number] | registry [--search=query] [--private=name] | registry configure --file=path [--replace] | skills <search|inspect|install|check|update> [options] | audit-package --package=path | verify-package --package=path --checksum=sha256 | brainstorm [--title=title] | spec [--title=title] | adr [--id=id --title=title] | plan [--title=title] | verify | trace | gate <stage> | recommend [--select=id,id] | status | doctor | repair | uninstall [--dry-run] | target <target> | rollback | confirm | resolve --package=path | update --package=path --target=target | validate [--package=path]",
+            output: "aiw install [--target target] | workflow <start|status|complete> [--id=id] | approve <stage> | reject <stage> --reason=text | skip <optional-stage> --reason=text | ui [--port=number] | orchestrate --plan=path [--execute] [--max-parallel=number] | telemetry <status|enable|disable> [privacy options] | plugin <create|validate> [options] | scan | semantic <status|query> | decision <status|triage> | self-validate --ticket=TYPE-000 | organization-policy --file=path [--replace] | policy-check --package=path [--package=path] | preset --file=path [--replace] | context | context-summary | context-quality | capabilities [--target=target] | token-usage [--stage=name --budget=number --used=number] | registry [--search=query] [--private=name] | registry configure --file=path [--replace] | skills <search|inspect|install|check|update> [options] | audit-package --package=path | verify-package --package=path --checksum=sha256 | brainstorm [--title=title] | spec [--title=title] | adr [--id=id --title=title] | plan [--title=title] | verify | trace | gate <stage> | recommend [--select=id,id] | status | doctor | repair | uninstall [--dry-run] | target <target> | rollback | confirm | resolve --package=path | update --package=path --target=target | validate [--package=path]",
         };
     }
     catch (error) {
@@ -1661,6 +1781,12 @@ function approvalArtifactPath(aiw, stage) {
     };
     return resolve(aiw, paths[stage]);
 }
+function formatConfidence(confidence) {
+    return confidence === undefined ? "unknown" : confidence.toFixed(3);
+}
+function formatNoul(noul) {
+    return noul === undefined ? "unknown" : noul.toFixed(3);
+}
 function parseNamedOptions(args, allowed) {
     const entries = args.map((arg) => arg.match(/^--([a-z-]+)=(.+)$/)?.slice(1));
     if (args.some((arg) => arg.indexOf("=") !== arg.lastIndexOf("=")) ||

package/docs/backlog.md

@@ -68,6 +68,8 @@ Priority levels: **P0** blocks the product or makes it unsafe; **P1** is require
 
 ## Context and cost — P2
 
+- [x] **SEM-001** Add flag-gated semantic mapping to scan and retrieval. _Acceptance:_ `.aiw/semantic.yml` with `enabled: true` verifies model availability before indexing, builds a versioned chunk index during `aiw scan`, and `aiw semantic query` returns ranked matches; missing or disabled configuration keeps scans fully deterministic and offline; semantic results are retrieval aids, never confirmed facts.
+- [x] **SEM-002** Integrate a decision model (jev/clef-flash via Ollama `/v1/systemone`) for advisory gate triage. _Acceptance:_ `.aiw/decision.yml` with `enabled: true` verifies model availability before use; `aiw decision triage` returns advisory `evidence_complete` and `gate` decisions with confidence; disabled or missing configuration makes no network request; advisory output never replaces human approval. See `docs/decision-model-evaluation.md`.
 - [x] **CTX-001** Build layered project context store.
 - [x] **CTX-002** Add task-scoped context retrieval and delta loading.
 - [x] **CTX-003** Add summary cache and freshness invalidation.

package/docs/decision-model-evaluation.md

@@ -0,0 +1,42 @@
+# Decision Model Evaluation: jev/clef (clef-flash)
+
+Status: implemented 2026-10-08 as an advisory triage layer behind a flag (`.aiw/decision.yml`, commands `aiw decision status` / `aiw decision triage`). It uses the `/v1/systemone` endpoint.
+
+## What the model offers
+
+Local inspection (`ollama show clef-flash:latest`, Ollama 0.40.1, MLX runner):
+
+| Property                  | Value                                        |
+| ------------------------- | -------------------------------------------- |
+| Architecture              | `clef` (purpose-built decision model by jev) |
+| Parameters / quantization | 9.5B, mxfp8, ~12 GB                          |
+| Context                   | 262,144 tokens                               |
+| Capabilities              | `decision`, `vision`                         |
+| License                   | Apache 2.0                                   |
+
+A dedicated decision model is architecturally attractive for AI Workflow: the SDD flow already separates automated quality gates from human approval, and an advisory triage layer between them could pre-screen evidence completeness, rank recommendations, and classify drift before a human reviews it.
+
+## API
+
+Clef Flash answers typed questions over a supplied state in a single non-autoregressive forward pass (Ollama `/v1/systemone`). Question types used by AI Workflow:
+
+- `noul` — yes/no with the probability that the answer is true (`evidence_complete`).
+- `choice` — ordered options with per-option probabilities (`gate`: `ready` / `needs-work`).
+
+## Implemented integration
+
+The earlier blocker (no exposed endpoint in Ollama 0.40.1) is resolved by the `/v1/systemone` endpoint documented at <https://ollama.com/library/clef-flash>. AI Workflow now ships the advisory layer:
+
+- `src/decision.ts`: `DecisionConfig` (`.aiw/decision.yml`, flag-gated: `enabled` / `model` / `baseUrl`), a `DecisionProvider` with availability verification (`/api/tags`), typed question/response contracts, and `buildEvidenceTriageRequest` for pre-gate triage.
+- `aiw decision status` and `aiw decision triage --artifact=<path>`: advisory `evidence_complete` (noul) and `gate` (`ready` / `needs-work`) decisions over any project artifact, with explicit confidence reporting.
+
+Observed behavior on real plans: an evidence-free plan scored `gate: ready` with confidence 0.044 and `evidence_complete` 0.260, while a fully evidenced plan scored confidence 0.718 and `evidence_complete` 0.924 — low confidence signals an inconclusive decision rather than approval.
+
+## Future integration points (advisory)
+
+- **Recommendation ranking**: order capability recommendations by decision-model relevance to the confirmed profile.
+- **Semantic re-ranking**: combine embedding recall (`aiw semantic query`) with clef re-ranking for sharper context selection during interpretation.
+
+## Hard boundary (unchanged)
+
+Decision-model output is `inferred` evidence with confidence, never `confirmed`. It can move an artifact to _pending review_, never to _approved_, and cannot replace the fingerprinted human approval ledger. This matches the existing approval contract and keeps the audit trail human-owned.

package/docs/semantic-mapping.md

@@ -0,0 +1,39 @@
+# Semantic Mapping
+
+AI Workflow can build a semantic index of the scanned project with a local embedding model such as `embeddinggemma-2` served by Ollama. Semantic mapping is opt-in and flag-gated: it activates only when a valid configuration exists, and every scan and flow query re-reads the flag.
+
+## Configuration
+
+Create `.aiw/semantic.yml`:
+
+```yaml
+semantic:
+  enabled: true
+  model: embeddinggemma-2:latest
+  baseUrl: http://localhost:11434
+  chunkChars: 1200 # optional, minimum 200
+  topK: 8 # optional, results per query
+```
+
+- `enabled: false` (or a missing file) disables semantic mapping entirely; scans stay deterministic and make no network request.
+- When enabled, `aiw scan` verifies that `model` is present at `baseUrl` (`GET /api/tags`) before indexing. A missing model fails the scan with an actionable error instead of producing a partial index.
+
+## Indexing during scan
+
+When semantic mapping is enabled, `aiw scan` additionally:
+
+1. Reads the scanned files with strict UTF-8 decoding (unreadable files are skipped).
+2. Splits each file into line-aligned chunks of at most `chunkChars` characters.
+3. Embeds each chunk with `POST /api/embeddings`.
+4. Writes the versioned index to `.aiw/semantic/index.json` (`schema: 1`).
+
+The index stores the model name; queries against an index built with a different model fail explicitly.
+
+## Queries during the flow
+
+`aiw semantic query --text="<natural language>"` ranks indexed chunks by cosine similarity and returns the top `topK` matches with file, score, and excerpt. `aiw semantic status` reports whether mapping is configured and whether the index is built.
+
+## Boundaries
+
+- Semantic results are retrieval aids, not evidence. They never create confirmed project facts and never bypass human approval gates.
+- The index is derived state; delete and rebuild it with `aiw scan` after structural changes.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@multileaf/ai-workflow",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Portable spec-driven development workflow for AI coding agents",
   "license": "MIT",
   "repository": {