@multileaf/ai-workflow 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -4,6 +4,26 @@ 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
+
+- Require host-native blocking question widgets for onboarding decisions and every SDD approval gate when available, with explicit unselected choices and a safe chat fallback.
+- Clarify that the CLI persists approval state but cannot prove that a host widget was used or verify respondent identity.
+
 ## [0.2.0] - 2026-09-13
 
 ### Added

package/README.md

@@ -230,7 +230,7 @@ npx @multileaf/ai-workflow approve traceability
 npx @multileaf/ai-workflow workflow complete
 ```
 
-Scaffold commands write deterministic files at fixed paths and a repeated invocation replaces that scaffold. Each applicable workflow stage requires two separate checks: its automated quality gate (when available), then explicit human approval. After presenting the artifact or evidence, the agent must stop and wait for the human before invoking the next skill, command, scaffold, or implementation action. A passing `aiw gate` validates artifact completeness only; it never records or implies human approval. Requirements use stable identifiers and Given/When/Then acceptance criteria. Plans link tasks to requirements, tests, risks, dependencies, and expected evidence. `verify` checks that the specification has acceptance criteria and the plan links requirements to validation; it does not execute project test commands. `trace` records declared links between requirements, decisions, tasks, code, tests, and evidence. Code review is performed with the `code-review` skill when installed; there is no separate review gate command, but the human must accept the review outcome before completion.
+Scaffold commands write deterministic files at fixed paths and a repeated invocation replaces that scaffold. Each applicable workflow stage requires two separate checks: its automated quality gate (when available), then explicit human approval. When the host provides a blocking question widget, the agent must use it with unselected approve, request-changes, and reject choices; it must wait for an actual submission before invoking the next skill, command, scaffold, or implementation action. A numbered chat prompt is only the fallback when no blocking widget exists. A passing `aiw gate` validates artifact completeness only; it never records or implies human approval. Requirements use stable identifiers and Given/When/Then acceptance criteria. Plans link tasks to requirements, tests, risks, dependencies, and expected evidence. `verify` checks that the specification has acceptance criteria and the plan links requirements to validation; it does not execute project test commands. `trace` records declared links between requirements, decisions, tasks, code, tests, and evidence. Code review is performed with the `code-review` skill when installed; there is no separate review gate command, but the human must accept the review outcome before completion.
 
 ## Project intelligence
 

package/dist/adapter.js

@@ -42,14 +42,16 @@ This skill is the bootstrap for AI Workflow. The installer intentionally install
 
 ### Mandatory interaction checkpoints
 
-This setup is gated by explicit user replies. A question is a blocking checkpoint, not narration: ask it, end your current response/turn immediately, and do no further analysis, tool calls, commands, or file changes until the user replies in a later turn. Never answer your own question, infer an answer from silence, or continue because a widget has a preselected value. If the host cannot pause for an answer, stop and ask the user to continue the setup after replying.
+This setup is gated by explicit user replies. At every human decision, call the host's native blocking question widget/tool; do not replace it with a prose question when the widget is available. Use the selection widget for multi-select decisions. Leave every choice unselected by default. Do not continue, call tools, run commands, or change files while a widget is awaiting submission. Only its actual submitted response is consent; never answer your own question or infer consent from silence, ambiguity, cancellation, or a preselected value. If the host has no blocking question widget, ask one concise numbered question in chat, end the turn, and wait for an explicit reply in a later turn. This is an interaction requirement for the agent; the AI Workflow CLI cannot independently verify which UI produced an approval.
 
-1. Before scanning, recommend that the user switch to a cheaper model. Ask whether they switched or explicitly want to continue with the current model; never change model settings yourself. Explain that analysis is read-only and optional resources will not be installed without their selection. Then stop the turn and wait. Do not launch analysis agents or run \`aiw scan\` until the user replies. If the reply is unclear, ask again and stop; proceed only after an explicit answer to continue (including an explicit choice to keep the current model).
+Use that widget for the model choice, confirmation of uncertain scan findings, all/custom/none recommendation selection, approval of the exact sync preview, external network or remote-skill consent, and each separate MCP configuration/execution/credential permission. For a single decision, offer explicit choices with no default; for “request changes,” “correct this finding,” or “other,” collect the user's free-text details in a follow-up widget before acting.
+
+1. Before scanning, recommend that the user switch to a cheaper model. Use a blocking question widget with no default choice to offer “I switched; continue”, “Keep this model; continue”, or “Stop setup”; never change model settings yourself. Explain that analysis is read-only and optional resources will not be installed without their selection. Wait for and evaluate the widget’s explicit response. Do not launch analysis agents or run \`aiw scan\` until the widget returns an explicit continue choice. If the widget is dismissed or the reply is unclear, ask again with the widget and stop; proceed only after an explicit answer to continue (including an explicit choice to keep the current model).
 2. Use the host's native subagent mechanism to launch these read-only analyses in parallel: (a) technologies, root and nested manifests, workspaces, and monorepo boundaries; (b) architecture, modules, entry points, and recurring code patterns; (c) tests, quality commands, CI, and developer tools. Keep the main agent as orchestrator. Wait for all results, verify important claims against cited project files, reconcile disagreements, and consolidate one evidence-backed project profile. Do not inspect secrets, ignored files, dependency directories such as \`node_modules\`, or generated output; inspect declared dependencies in project manifests. If subagents are unavailable, perform the same analyses directly and disclose the fallback.
 3. Run \`npx --yes --package=@multileaf/ai-workflow -- aiw scan\` and read \`.aiw/profile.yml\`. Treat this deterministic scan as another evidence source, not as a replacement for workspace-level analysis. Summarize each workspace separately; do not assume root dependencies or commands apply to every module. Ask the user to confirm uncertain or conflicting facts before using them as project policy. Add confirmed architecture and recurring patterns to the matching entries in the \`project_modules\` JSON array in \`.aiw/profile.yml\`, including file-path evidence; create a root-level entry when only the root project exists. Preserve existing detected fields and never store secrets or source-code excerpts there.
 4. Run \`npx --yes --package=@multileaf/ai-workflow -- aiw recommend\` and read \`.aiw/recommendations.yml\`. Combine catalog results with the consolidated project profile. Recommend matching skills, rules, agents, hooks, templates, and MCP servers. For every MCP, disclose its publisher/source, purpose, capabilities, permissions, transport, and credential needs; verify them against current official host and server documentation. Recommend only integrations supported by project evidence and never invent credentials.
 5. Present recommendations as concise tables grouped by category: skills, rules, agents, hooks, templates, and MCPs. Include one row per recommended item and columns for the item, a short project-specific reason for the recommendation, and relevant evidence. For MCP rows, also summarize purpose, source, permissions, transport, and credential needs (use a separate table if needed). Do not show a flat list without category headings or generic reasons such as “useful for this project.” After the tables, use the host's native selection widget to offer three explicit choices: install all recommendations, customize, or install none. The widget must start with no choice selected; never accept a default or preselected value as the user's answer. If the user customizes, show selectable category blocks and individual items, keeping each item's short reason and declared prerequisites visible. Read \`requires\` from \`.aiw/recommendations.yml\`; explain that choosing a stage auto-selects its prerequisite capabilities and their resources. If the host lacks a multi-select widget, ask a numbered all/custom/none question and stop the turn to wait for the reply. Do not run a selection command or install anything until a reply/explicit widget submission arrives in a later turn. A dismissed widget, empty answer, silence, or ambiguous answer means no consent; ask again or stop without installing. MCP selection does not grant permission to execute the server or use external access; ask separately for those permissions.
-6. Only after receiving the user's explicit all/custom/none choice, record it: use \`npx --yes --package=@multileaf/ai-workflow -- aiw recommend --select=all\` for an explicit all choice; for customized item-level choices, pass only the selected resource references such as \`skills/verification,rules/tdd-policy,agents/test-engineer\`; use \`npx --yes --package=@multileaf/ai-workflow -- aiw recommend --select=\` for an explicit none choice. Before syncing a non-empty selection, show the exact selected resources and their prerequisites. Run \`npx --yes --package=@multileaf/ai-workflow -- aiw sync --preview\` and show the complete plan, including additions, updates, preserved files, conflicts, and any external permissions. Ask the user to approve this exact plan and stop the turn. Run sync only after that confirmation arrives in a later turn. Only after a later explicit approval, rerun preview if selection or project files changed, then run \`npx --yes --package=@multileaf/ai-workflow -- aiw sync --approve-plan=<fingerprint>\` using the fingerprint from the approved preview. A changed plan or conflict must stop without writes. Remote skills are not installed by sync: ask separately for network access and installation approval, then use \`npx --yes --package=@multileaf/ai-workflow -- aiw skills install --source=vercel-labs/agent-skills --skill=vercel-react-best-practices --allow=network:external\`. MCP configuration, server execution, and credentials each require separate consent. Install only confirmed selected resources and declared dependencies. Tailor instructions only where project evidence changes their usefulness (such as test commands, workspace boundaries, framework patterns, or module architecture). Preserve existing files, configuration, and secrets; report conflicts rather than overwriting them.
+6. Only after receiving the user's explicit all/custom/none choice, record it: use \`npx --yes --package=@multileaf/ai-workflow -- aiw recommend --select=all\` for an explicit all choice; for customized item-level choices, pass only the selected resource references such as \`skills/verification,rules/tdd-policy,agents/test-engineer\`; use \`npx --yes --package=@multileaf/ai-workflow -- aiw recommend --select=\` for an explicit none choice. Before syncing a non-empty selection, show the exact selected resources and their prerequisites. Run \`npx --yes --package=@multileaf/ai-workflow -- aiw sync --preview\` and show the complete plan, including additions, updates, preserved files, conflicts, and any external permissions. Use the blocking question widget to approve this exact plan, request changes, or cancel. Run sync only after that confirmation arrives from an explicit widget submission. Only after a later explicit approval, rerun preview if selection or project files changed, then run \`npx --yes --package=@multileaf/ai-workflow -- aiw sync --approve-plan=<fingerprint>\` using the fingerprint from the approved preview. A changed plan or conflict must stop without writes. Remote skills are not installed by sync: ask separately for network access and installation approval, then use \`npx --yes --package=@multileaf/ai-workflow -- aiw skills install --source=vercel-labs/agent-skills --skill=vercel-react-best-practices --allow=network:external\`. MCP configuration, server execution, and credentials each require separate consent. Install only confirmed selected resources and declared dependencies. Tailor instructions only where project evidence changes their usefulness (such as test commands, workspace boundaries, framework patterns, or module architecture). Preserve existing files, configuration, and secrets; report conflicts rather than overwriting them.
 7. For selected MCPs, add only the selected servers to the host's supported project configuration. Check current official host and server documentation for the configuration format, merge existing settings without replacing unrelated entries, and use environment-variable references instead of literal credentials. Do not run server install/start/authentication commands without separate approval. If the target requires user-level changes or safe configuration cannot be validated, give the user exact manual steps and report the MCP as pending rather than installed.
 8. Report installed resources by block, project-specific changes, skipped recommendations, MCP trust/authentication steps, and conflicts. Recommend restarting or reloading the coding-agent session so it discovers newly installed resources; follow known host behavior if it reloads changes automatically. Introduce only the gates supported by installed resources: brainstorming → specification → architecture decision when needed → implementation plan → implementation with tests → verification → code review → traceability.
 
@@ -59,7 +61,9 @@ If the user declines all recommendations, leave the project with only the bootst
 
 ### Mandatory human gates between stages
 
-For every CLI command below, use \`npx --yes --package=@multileaf/ai-workflow -- aiw <command>\`; do not assume a global \`aiw\` binary exists. Start each feature request with \`npx --yes --package=@multileaf/ai-workflow -- aiw workflow start\` and check progress with \`npx --yes --package=@multileaf/ai-workflow -- aiw workflow status\`. Complete it with \`npx --yes --package=@multileaf/ai-workflow -- aiw workflow complete\` only after all stages resolve. The \`aiw gate <stage>\` command checks evidence and records a pending review; a passing result is not human approval. At every stage boundary—brainstorming, specification, technical design, plan, implementation, verification, code review, and traceability—present the exact artifact/evidence, ask whether the user approves proceeding, end the turn, and wait for an explicit reply in a later turn. On approval, record it with \`npx --yes --package=@multileaf/ai-workflow -- aiw approve <stage>\`; if the user asks for changes, record the rejection first with \`npx --yes --package=@multileaf/ai-workflow -- aiw reject <stage> --reason=<feedback>\`, then revise and rerun the gate. Do not invoke the next skill, create its scaffold, run its commands, or edit its artifacts before approval is recorded or the pending stage is rejected. Silence, an ambiguous reply, an automated gate pass, or earlier approval never counts. Brainstorming and technical design may be skipped only after explaining why and receiving explicit human acceptance; record each skip with \`npx --yes --package=@multileaf/ai-workflow -- aiw skip <stage> --reason=<accepted reason>\`.
+At every stage gate, use the host's native blocking question widget and present the exact evidence with these unselected choices: “Approve and continue”, “Request changes”, and “Reject/stop”. For optional brainstorming or technical-design skips, use a separate widget with “Accept this skip” and “Do not skip”; collect the reason before recording an accepted skip. Do not run \`aiw approve\`, \`aiw reject\`, or \`aiw skip\` until the relevant widget has returned an explicit submission. A request for changes must collect the feedback in a follow-up question widget, record rejection, then revise and rerun the gate. If no blocking question widget exists, use a numbered chat prompt and end the turn until an explicit reply arrives. A widget submission is the agent's required interaction signal; the CLI cannot prove the widget was used.
+
+For every CLI command below, use \`npx --yes --package=@multileaf/ai-workflow -- aiw <command>\`; do not assume a global \`aiw\` binary exists. Start each feature request with \`npx --yes --package=@multileaf/ai-workflow -- aiw workflow start\` and check progress with \`npx --yes --package=@multileaf/ai-workflow -- aiw workflow status\`. Complete it with \`npx --yes --package=@multileaf/ai-workflow -- aiw workflow complete\` only after all stages resolve. The \`aiw gate <stage>\` command checks evidence and records a pending review; a passing result is not human approval. At every stage boundary—brainstorming, specification, technical design, plan, implementation, verification, code review, and traceability—present the exact artifact/evidence, ask using the blocking question widget and wait for its explicit submission before proceeding; end the turn only when the widget is unavailable. On approval, record it with \`npx --yes --package=@multileaf/ai-workflow -- aiw approve <stage>\`; if the user asks for changes, record the rejection first with \`npx --yes --package=@multileaf/ai-workflow -- aiw reject <stage> --reason=<feedback>\`, then revise and rerun the gate. Do not invoke the next skill, create its scaffold, run its commands, or edit its artifacts before approval is recorded or the pending stage is rejected. Silence, an ambiguous reply, an automated gate pass, or earlier approval never counts. Brainstorming and technical design may be skipped only after explaining why and receiving explicit human acceptance; record each skip with \`npx --yes --package=@multileaf/ai-workflow -- aiw skip <stage> --reason=<accepted reason>\`.
 
 - Use the brainstorming skill when scope, users, constraints, or assumptions are unclear; create its artifact with \`npx --yes --package=@multileaf/ai-workflow -- aiw brainstorm\`, validate it with \`npx --yes --package=@multileaf/ai-workflow -- aiw gate brainstorming\`, present it, wait, then record the reply with \`npx --yes --package=@multileaf/ai-workflow -- aiw approve brainstorming\` before specification. If unnecessary, ask to skip and record explicit acceptance with \`npx --yes --package=@multileaf/ai-workflow -- aiw skip brainstorming --reason=...\`.
 - Create a specification with stable requirement IDs and Given/When/Then acceptance criteria; pass \`npx --yes --package=@multileaf/ai-workflow -- aiw gate specification\`, present it, wait, and record approval before design or planning.

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/ai-init-workflow-spec.md

@@ -6,13 +6,13 @@ Make `/ai-init` a guided, evidence-backed onboarding flow. The initial `npx` ins
 
 ## User flow
 
-1. **Model and consent.** Before repository analysis, recommend switching to a lower-cost model. Do not change model settings. Ask whether the user switched or explicitly wants to continue with the current model. End the agent turn after asking and wait for a reply before scanning, launching subagents, or calling tools. Silence, ambiguity, or a preselected widget value is not consent.
+1. **Model and consent.** Before repository analysis, recommend switching to a lower-cost model. Do not change model settings. Use the host's native blocking question widget, with no preselected value, to ask whether the user switched, wants to continue with the current model, or wants to stop. Do not scan or launch subagents until the widget has an explicit continue response. Silence, ambiguity, dismissal, or a default value is not consent.
 2. **Parallel project analysis.** Use the host's native subagent mechanism to start independent read-only scans in parallel. Assign separate work to (a) technologies and package/workspace topology, (b) architecture, modules, and code patterns, and (c) tests, quality tools, and CI. The initiating agent is the orchestrator: it consolidates findings, resolves conflicts using repository evidence, and records paths for every material conclusion. If the host cannot start subagents, do the same scans directly and say so.
 3. **Monorepo coverage.** Discover root and nested project manifests, workspace definitions, package boundaries, framework configs, tests, and module entry points. Analyze each workspace separately, then summarize shared tooling and cross-workspace relationships. Never infer that root dependencies apply to every workspace.
-4. **Scan record.** Run the deterministic AI Workflow scan and combine it with the parallel analysis. Present technologies, architecture, patterns, modules, tests, quality commands, workspace topology, confidence, and source evidence. Do not include secret values. Ask for confirmation where conflicting or uncertain findings would affect installed guidance.
+4. **Scan record.** Run the deterministic AI Workflow scan and combine it with the parallel analysis. Present technologies, architecture, patterns, modules, tests, quality commands, workspace topology, confidence, and source evidence. Do not include secret values. Use the native blocking question widget to confirm, correct, or leave unresolved any conflicting or uncertain finding that would affect installed guidance.
 5. **Recommendations.** Match catalog capabilities to the consolidated project profile. Show concise tables grouped by resource category (skills, rules, agents, hooks, templates, and MCPs), with one row per item and a short, project-specific reason plus supporting evidence. Include resource types, required permissions, and project-specific configuration steps where relevant. Recommend an MCP only when repository evidence supports its use; disclose its publisher/source, capabilities, access, transport, and credential needs. Never invent credentials or silently enable an MCP.
 6. **Selection.** After the recommendation tables, use the coding host's native selection widget when it supports one. First offer: install all recommendations, customize, or install none. No option may be preselected or inferred. Wait for an explicit submission; a dismissed widget, blank response, silence, or ambiguity must stop progress without selecting or installing anything. For customization, show selectable blocks grouped by resource type, then the individual recommended items in each selected block; retain each item's concise reason and evidence in the selection details. Include MCPs as a separate block. Keep dependencies visible and select required dependencies together. If the host has no selection widget, ask an equivalent numbered prompt, end the turn, and wait for an explicit all/custom/none reply.
-7. **Install and personalize.** After an explicit non-empty selection, show the exact resources and prerequisite capabilities that will be installed, ask for confirmation, end the turn, and wait. Install only after that confirmation arrives in a later turn. For “all”, install every recommendation that does not require an unapproved external permission. A missing external permission must not block independent bundled resources; report the external item as pending and give the user the exact retry command. For custom selection, install only selected items and their declared dependencies. Personalize resources only when project evidence materially changes their instructions (for example, test commands, workspace/module layout, framework patterns, or architectural boundaries). Preserve existing files and secrets; report conflicts rather than overwriting. MCP setup must use the selected host's supported project-level configuration, preserve existing configuration, use environment-variable references for secrets, and request separate approval for permissions or external execution.
+7. **Install and personalize.** After an explicit non-empty selection, show the exact resources and prerequisite capabilities that will be installed. Use the native blocking question widget with no default choice to approve the exact preview, request changes, or cancel. Do not sync while the widget is unanswered. For “all”, install every recommendation that does not require an unapproved external permission. A missing external permission must not block independent bundled resources; report the external item as pending and give the user the exact retry command. For custom selection, install only selected items and their declared dependencies. Personalize resources only when project evidence materially changes their instructions (for example, test commands, workspace/module layout, framework patterns, or architectural boundaries). Preserve existing files and secrets; report conflicts rather than overwriting. Use separate blocking question widgets to authorize MCP configuration, server execution, external access, and credentials; never combine these permissions.
 8. **Completion.** Report installed resources by block, project-specific changes, skipped recommendations, conflicts, MCP authentication/trust steps, and validation performed. Recommend restarting/reloading the coding-agent session so newly installed resources are discovered. Do not claim a restart is required when the host loads changes immediately; distinguish host behavior where known.
 
 ## Safety and compatibility
@@ -23,6 +23,7 @@ Make `/ai-init` a guided, evidence-backed onboarding flow. The initial `npx` ins
 - Selection and external permissions are separate decisions. Selecting an MCP is not permission to execute it or to expose credentials.
 - Resource writes use target adapters, ownership tracking, safe paths, atomic updates, and conflict reporting.
 - Host-specific capabilities (subagents, selection widgets, MCP configuration, restart semantics) are detected or described accurately; provide a safe manual fallback where unavailable.
+- Every human decision uses the host's native blocking question widget when available, with no default choice; a prose prompt is permitted only as a documented fallback when the host has no blocking widget.
 
 ## Acceptance criteria
 
@@ -39,9 +40,10 @@ Make `/ai-init` a guided, evidence-backed onboarding flow. The initial `npx` ins
 - **AIINIT-010:** CLI tests cover mixed-stack monorepos, all/custom/none selection, permission gating, MCP config merging, personalization, conflicts, and completion output.
 - **AIINIT-011:** Custom selections can choose individual resource references by block, while `--select=all` selects every recommended capability and `--select=` selects none.
 - **AIINIT-013:** Sync previews exact additions, updates, preserved files, conflicts, and external permissions without writing; apply is bound to the approved plan fingerprint and is transactional. External skills and MCP actions require separate approvals, so network denial cannot partially apply local resources.
-- **AIINIT-014:** The bootstrap pauses the agent turn at the model choice, recommendation selection, and final install confirmation; no scan or install proceeds from silence, ambiguity, cancellation, or a default/preselected choice.
-- **AIINIT-015:** Every applicable SDD stage has a mandatory human approval checkpoint before the next stage; automated quality gates are explicitly distinct from human approval, and the agent must stop the turn until an explicit decision arrives.
+- **AIINIT-014:** The bootstrap uses a blocking question widget for model choice, uncertain scan facts, recommendation selection, and final install confirmation; no scan or install proceeds from silence, ambiguity, cancellation, or a default/preselected choice.
+- **AIINIT-015:** Every applicable SDD stage has a mandatory human approval checkpoint before the next stage; the agent uses the native blocking question widget with explicit approve/request-changes/reject choices, and automated quality gates remain distinct from human approval.
 - **AIINIT-016:** A versioned per-workflow approval ledger binds each human decision to the exact evidence fingerprint, blocks out-of-order commands, invalidates downstream approvals when evidence changes, and explains the next action in workflow status.
+- **AIINIT-017:** Every human checkpoint uses the host's native blocking question widget when available, leaves choices unselected, and acts only after an explicit submission. If unavailable, the agent uses a numbered chat prompt and waits for a later explicit reply. The CLI must describe that it cannot independently prove which UI produced an approval.
 
 ## Delivery slices
 

package/docs/architecture.md

@@ -47,7 +47,7 @@ Project analysis is hybrid: deterministic detectors establish observable facts,
 
 The SDD approval contract models the ordered stages brainstorming, specification, technical design, plan, implementation, verification, review, and traceability. Brainstorming and technical design are optional; skipping either requires a human-accepted reason. Every other stage must be approved. Automated quality-gate results are stored separately from human decisions and can only move an artifact to pending review, never directly to approved.
 
-Each approval is scoped to one workflow ID and bound to a SHA-256 fingerprint of the exact artifact reviewed, so a later feature cannot reuse earlier approvals. A content change or rejection makes that stage and its descendants stale. The CLI persists the versioned ledger in `.aiw/approvals.yml`, blocks stage commands when prerequisites are unresolved, and keeps passing quality gates distinct from human approval. Approval records provide an audit trail but cannot prove the identity of a person who responded in a host conversation.
+Each approval is scoped to one workflow ID and bound to a SHA-256 fingerprint of the exact artifact reviewed, so a later feature cannot reuse earlier approvals. A content change or rejection makes that stage and its descendants stale. The CLI persists the versioned ledger in `.aiw/approvals.yml`, blocks stage commands when prerequisites are unresolved, and keeps passing quality gates distinct from human approval. The generated bootstrap and stage skills require the host's native blocking question widget for human decisions when available, with a waiting chat prompt as fallback. Approval records provide an audit trail but cannot prove the identity of a respondent or independently verify that the host widget was used.
 
 Every stage has a stable evidence path and an automated completeness gate. Design, implementation, review, and traceability use explicit report templates; a passing completeness check still leaves the stage pending until a human accepts the exact evidence.
 

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.0",
+  "version": "0.3.0",
   "description": "Portable spec-driven development workflow for AI coding agents",
   "license": "MIT",
   "repository": {

package/resources/skills/brainstorming.md

@@ -5,6 +5,8 @@ description: Turn an early product idea into structured goals, assumptions, cons
 
 # Brainstorming
 
+For every approval or optional skip, use the host's native blocking question widget, not a prose-only prompt when the widget is available. Leave choices unselected and offer “Approve and continue”, “Request changes”, and “Reject/stop”; for a skip, offer “Accept skip” or “Do not skip”. Wait for an actual submission before running `aiw approve`, `aiw reject`, or `aiw skip` or proceeding. Collect revision/skip reasons in a follow-up free-text widget. If the host has no blocking widget, use a numbered chat prompt and end the turn until an explicit reply arrives. The CLI records the decision but cannot verify that a widget was used.
+
 Separate facts, hypotheses, decisions, and open questions. Identify users, desired outcomes, constraints, risks, and non-goals. Do not prematurely prescribe implementation. Produce a versioned brainstorm artifact in English.
 
 Start an AI Workflow session for each feature with `npx --yes --package=@multileaf/ai-workflow -- aiw workflow start` unless one is already active. When the request is already clear, explain why brainstorming can be skipped, ask the human to accept the skip, stop, and record only an explicit acceptance with `aiw skip brainstorming --reason=<accepted reason>`. Otherwise create `.aiw/generated/specs/brainstorm.md`, run `aiw gate brainstorming`, present the exact artifact and a concise summary, and ask whether to proceed to requirements. Stop the turn and wait. Only after an explicit approval, record it with `aiw approve brainstorming`; do not start or scaffold requirements before that command succeeds. If changes are requested, first record `aiw reject brainstorming --reason=<feedback>`, then revise the artifact, rerun its gate, and ask again. Use `npx --yes --package=@multileaf/ai-workflow -- aiw <command>` when no global CLI is available.

package/resources/skills/code-review.md

@@ -5,6 +5,8 @@ description: Review code for correctness, maintainability, design quality, and r
 
 # Code Review
 
+For every approval, rejection, or optional skip, use the host's native blocking question widget, not a prose-only prompt when the widget is available. Leave choices unselected and offer “Approve and continue”, “Request changes”, and “Reject/stop”; for a skip, offer “Accept skip” or “Do not skip”. Wait for an actual submission before running `aiw approve`, `aiw reject`, or `aiw skip` or proceeding. Collect revision/skip reasons in a follow-up free-text widget. If the host has no blocking widget, use a numbered chat prompt and end the turn until an explicit reply arrives. The CLI records the decision but cannot verify that a widget was used.
+
 Review behavior, boundaries, cohesion, naming, types, error handling, duplication, complexity, tests, and documentation. Prioritize actionable findings with severity and evidence.
 
 Write `.aiw/generated/reports/code-review.md` with the scope, findings (including an explicit `None` when clear), checks, residual risks, and decision. Run `aiw gate review`, present the exact report, and ask whether to address findings or accept the residual risk. Stop and wait for an explicit decision. Only after approval, record it with `aiw approve review`; do not start traceability before it succeeds. If changes are requested, first record `aiw reject review --reason=<feedback>`, return to implementation, and require verification and review again. Review completeness is an automated gate; it does not replace human approval. Invoke commands through `npx --yes --package=@multileaf/ai-workflow -- aiw <command>` when no global binary exists.

package/resources/skills/implementation-planning.md

@@ -5,6 +5,8 @@ description: Break an approved design into independently verifiable implementati
 
 # Implementation Planning
 
+For every approval, rejection, or optional skip, use the host's native blocking question widget, not a prose-only prompt when the widget is available. Leave choices unselected and offer “Approve and continue”, “Request changes”, and “Reject/stop”; for a skip, offer “Accept skip” or “Do not skip”. Wait for an actual submission before running `aiw approve`, `aiw reject`, or `aiw skip` or proceeding. Collect revision/skip reasons in a follow-up free-text widget. If the host has no blocking widget, use a numbered chat prompt and end the turn until an explicit reply arrives. The CLI records the decision but cannot verify that a widget was used.
+
 Create small ordered tasks. Each task must reference requirements, affected modules, tests, commands, dependencies, and completion evidence.
 
 Write `.aiw/generated/plans/implementation-plan.md` with ordered tasks, requirement links, affected modules, tests, validation, dependencies, risks, and completion evidence. After `aiw gate plan` passes, present the exact plan to the human and ask for explicit approval. Stop and wait; a gate pass is not approval. Do not edit implementation files until approval arrives and `aiw approve plan` succeeds. If changes are requested, first record `aiw reject plan --reason=<feedback>`, then revise the plan, rerun its gate, and ask again. After approval, implement in task order. Use `tdd-development` when installed and the project has a test workflow; otherwise use existing validation. When implementation is complete, write `.aiw/generated/reports/implementation-report.md` with changed files, tests, validation results, and deviations; run `aiw gate implementation`, present the diff and evidence to the human, stop, and wait for explicit approval. Record approval with `aiw approve implementation` before verification. Invoke CLI commands through `npx --yes --package=@multileaf/ai-workflow -- aiw <command>` when no global binary exists.

package/resources/skills/project-init.md

@@ -5,4 +5,6 @@ description: Inspect a repository, build a project profile, and prepare AI Workf
 
 # Project Initialization
 
+Use the host's native blocking question widget for uncertain project facts and setup decisions when available. Leave choices unselected; offer to confirm the evidence, correct it, or leave it unresolved. Do not make an uncertain inference project policy until the widget is explicitly submitted. If the host has no blocking widget, ask one numbered question in chat and wait for an explicit response before proceeding.
+
 Inspect structure and configuration safely. Detect languages, frameworks, package managers, scripts, tests, quality tools, CI, and conventions. Record evidence and confidence in `.aiw/profile.yml`. Ask for confirmation before treating uncertain inferences as facts. Recommend capabilities with rationale, permissions, and conflicts.

package/resources/skills/requirements-specification.md

@@ -5,6 +5,8 @@ description: Convert a product idea into testable, traceable requirements.
 
 # Requirements Specification
 
+For every approval, rejection, or optional skip, use the host's native blocking question widget, not a prose-only prompt when the widget is available. Leave choices unselected and offer “Approve and continue”, “Request changes”, and “Reject/stop”; for a skip, offer “Accept skip” or “Do not skip”. Wait for an actual submission before running `aiw approve`, `aiw reject`, or `aiw skip` or proceeding. Collect revision/skip reasons in a follow-up free-text widget. If the host has no blocking widget, use a numbered chat prompt and end the turn until an explicit reply arrives. The CLI records the decision but cannot verify that a widget was used.
+
 Give each requirement a stable identifier. Define observable behavior, acceptance criteria, constraints, and unresolved questions. Link requirements to their source brainstorm and distinguish confirmed facts from assumptions. Do not approve ambiguous critical requirements.
 
 Create `.aiw/generated/specs/specification.md` and run `aiw gate specification`. Present the exact requirements and unresolved questions to the human and ask for explicit approval. Stop the turn and wait; a passing gate is not approval. Only after approval, run `aiw approve specification`; do not create design or plan artifacts before it succeeds. If changes are requested, first record `aiw reject specification --reason=<feedback>`, then revise the specification, rerun its gate, and ask again. After approval, use `technical-design` when the change affects architecture or has consequential design choices. Otherwise explain why design can be skipped, ask the human to accept, stop, and record an explicit acceptance with `aiw skip technical-design --reason=<accepted reason>` before planning. Invoke commands through `npx --yes --package=@multileaf/ai-workflow -- aiw <command>` if `aiw` is not installed globally.

package/resources/skills/tdd-development.md

@@ -5,6 +5,8 @@ description: Implement repository changes through test-first development.
 
 # TDD Development
 
+For implementation approval or rejection, use the host's native blocking question widget, not a prose-only prompt when the widget is available. Leave choices unselected and offer “Approve and continue”, “Request changes”, and “Reject/stop”. Wait for an actual submission before running `aiw approve` or `aiw reject` or starting verification. Collect requested changes in a follow-up free-text widget. If the host has no blocking widget, use a numbered chat prompt and end the turn until an explicit reply arrives. The CLI records the decision but cannot verify that a widget was used.
+
 Follow Red, Green, Refactor, Verify. Write a failing behavioral test first, implement the smallest change, refactor for clarity and design quality, then run the relevant quality gate. Never weaken a test to make an implementation pass.
 
 After implementation tasks are green and refactored, write `.aiw/generated/reports/implementation-report.md` with changed files, tests, validation results, and deviations. Run `aiw gate implementation`, present the diff, changed requirements, test commands, and exact evidence to the human. Ask for explicit approval to proceed to verification, end the turn, and wait. Do not invoke verification until the human approves and `aiw approve implementation` succeeds. If changes are requested, first record `aiw reject implementation --reason=<feedback>`, remain in implementation, repeat relevant tests, update the report, rerun its gate, and ask again. Invoke CLI commands through `npx --yes --package=@multileaf/ai-workflow -- aiw <command>` when no global binary exists.

package/resources/skills/technical-design.md

@@ -5,6 +5,8 @@ description: Design modular technical solutions from approved requirements.
 
 # Technical Design
 
+For every approval, rejection, or optional skip, use the host's native blocking question widget, not a prose-only prompt when the widget is available. Leave choices unselected and offer “Approve and continue”, “Request changes”, and “Reject/stop”; for a skip, offer “Accept skip” or “Do not skip”. Wait for an actual submission before running `aiw approve`, `aiw reject`, or `aiw skip` or proceeding. Collect revision/skip reasons in a follow-up free-text widget. If the host has no blocking widget, use a numbered chat prompt and end the turn until an explicit reply arrives. The CLI records the decision but cannot verify that a widget was used.
+
 Map requirements to components, interfaces, data flows, and validation strategy. Compare meaningful alternatives and record decisions with rationale, risks, and consequences. Prefer small cohesive modules, explicit contracts, dependency inversion, and reversible changes.
 
 Write the reviewable design to `.aiw/generated/reports/technical-design.md` using the technical-design template. Link each design and ADR to affected requirements. Run `aiw gate technical-design`, present the exact design and decisions to the human, and ask for explicit approval. Stop and wait; do not create an implementation plan until approval arrives. Only after approval, record it with `aiw approve technical-design`. If changes are requested, first record `aiw reject technical-design --reason=<feedback>`, then revise the design/ADRs, rerun the gate, and ask again. If no technical design is needed, obtain explicit human acceptance and record `aiw skip technical-design --reason=<accepted reason>`. Use `npx --yes --package=@multileaf/ai-workflow -- aiw <command>` when no global CLI is available.

package/resources/skills/verification.md

@@ -5,6 +5,8 @@ description: Verify implementation against requirements and produce traceable ev
 
 # Verification
 
+For every approval or rejection, use the host's native blocking question widget, not a prose-only prompt when the widget is available. Leave choices unselected and offer “Approve and continue”, “Request changes”, and “Reject/stop”. Wait for an actual submission before running `aiw approve` or `aiw reject` or proceeding to the next stage. Collect requested changes in a follow-up free-text widget. If the host has no blocking widget, use a numbered chat prompt and end the turn until an explicit reply arrives. The CLI records the decision but cannot verify that a widget was used.
+
 Check every acceptance criterion, quality gate, security requirement, and affected adapter. Report passed checks, missing evidence, failures, and residual risks. A task is not complete when required evidence is missing.
 
 Write `.aiw/generated/reports/verification-report.md` using the verification-report template and validate it with `npx --yes --package=@multileaf/ai-workflow -- aiw gate verification`. Present the exact report, checks, missing evidence, and residual risks to the human. Ask for explicit approval to proceed, end the turn, and wait; an automated gate pass is not human acceptance. Only after approval, record it with `aiw approve verification`. Do not start code review or final traceability before that command succeeds. If verification fails or changes are requested, record `aiw reject verification --reason=<feedback>` before editing the report or returning to implementation, then repeat verification, update the report, rerun the gate, and ask again. Use npx package invocation for other `aiw` commands when no global binary exists.