gsd-pi 2.46.0-dev.f45e6dc → 2.46.1-dev.79664f2

package/README.md

@@ -9,6 +9,7 @@
 [![GitHub stars](https://img.shields.io/github/stars/gsd-build/GSD-2?style=for-the-badge&logo=github&color=181717)](https://github.com/gsd-build/GSD-2)
 [![Discord](https://img.shields.io/badge/Discord-Join%20us-5865F2?style=for-the-badge&logo=discord&logoColor=white)](https://discord.gg/gsd)
 [![License](https://img.shields.io/badge/license-MIT-blue?style=for-the-badge)](LICENSE)
+[![$GSD Token](https://img.shields.io/badge/$GSD-Dexscreener-1C1C1C?style=for-the-badge&logo=data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMjQiIGhlaWdodD0iMjQiIHZpZXdCb3g9IjAgMCAyNCAyNCIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj48Y2lyY2xlIGN4PSIxMiIgY3k9IjEyIiByPSIxMCIgZmlsbD0iIzAwRkYwMCIvPjwvc3ZnPg==&logoColor=00FF00)](https://dexscreener.com/solana/dwudwjvan7bzkw9zwlbyv6kspdlvhwzrqy6ebk8xzxkv)
 
 The original GSD went viral as a prompt framework for Claude Code. It worked, but it was fighting the tool — injecting prompts through slash commands, hoping the LLM would follow instructions, with no actual control over context windows, sessions, or execution.
 

package/dist/resources/extensions/claude-code-cli/index.js

@@ -0,0 +1,25 @@
+/**
+ * Claude Code CLI Provider Extension
+ *
+ * Registers a model provider that delegates inference to the user's
+ * locally-installed Claude Code CLI via the official Agent SDK.
+ *
+ * Users with a Claude Code subscription (Pro/Max/Team) get access to
+ * subsidized inference through GSD's UI — no API key required.
+ *
+ * TOS-compliant: uses Anthropic's official `@anthropic-ai/claude-agent-sdk`,
+ * never touches credentials, never offers a login flow.
+ */
+import { CLAUDE_CODE_MODELS } from "./models.js";
+import { isClaudeCodeReady } from "./readiness.js";
+import { streamViaClaudeCode } from "./stream-adapter.js";
+export default function claudeCodeCli(pi) {
+    pi.registerProvider("claude-code", {
+        authMode: "externalCli",
+        api: "anthropic-messages",
+        baseUrl: "local://claude-code",
+        isReady: isClaudeCodeReady,
+        streamSimple: streamViaClaudeCode,
+        models: CLAUDE_CODE_MODELS,
+    });
+}

package/dist/resources/extensions/claude-code-cli/models.js

@@ -0,0 +1,40 @@
+/**
+ * Model definitions for the Claude Code CLI provider.
+ *
+ * Costs are zero because inference is covered by the user's Claude Code
+ * subscription. The SDK's `result` message still provides token counts
+ * for display in the TUI.
+ *
+ * Context windows and max tokens match the Anthropic API definitions
+ * in models.generated.ts.
+ */
+const ZERO_COST = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 };
+export const CLAUDE_CODE_MODELS = [
+    {
+        id: "claude-opus-4-6",
+        name: "Claude Opus 4.6 (via Claude Code)",
+        reasoning: true,
+        input: ["text", "image"],
+        cost: ZERO_COST,
+        contextWindow: 1_000_000,
+        maxTokens: 128_000,
+    },
+    {
+        id: "claude-sonnet-4-6",
+        name: "Claude Sonnet 4.6 (via Claude Code)",
+        reasoning: true,
+        input: ["text", "image"],
+        cost: ZERO_COST,
+        contextWindow: 1_000_000,
+        maxTokens: 64_000,
+    },
+    {
+        id: "claude-haiku-4-5",
+        name: "Claude Haiku 4.5 (via Claude Code)",
+        reasoning: true,
+        input: ["text", "image"],
+        cost: ZERO_COST,
+        contextWindow: 200_000,
+        maxTokens: 64_000,
+    },
+];

package/dist/resources/extensions/claude-code-cli/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "@gsd/claude-code-cli",
+  "private": true,
+  "version": "1.0.0",
+  "type": "module",
+  "pi": {
+    "extensions": [
+      "./index.js"
+    ]
+  }
+}

package/dist/resources/extensions/claude-code-cli/partial-builder.js

@@ -0,0 +1,223 @@
+/**
+ * Content-block mapping helpers and streaming state tracker.
+ *
+ * Translates the Claude Agent SDK's `BetaRawMessageStreamEvent` sequence
+ * into GSD's `AssistantMessageEvent` deltas for incremental TUI rendering.
+ */
+// ---------------------------------------------------------------------------
+// Content-block mapping helpers
+// ---------------------------------------------------------------------------
+/**
+ * Convert a single BetaContentBlock to the corresponding GSD content type.
+ */
+export function mapContentBlock(block) {
+    switch (block.type) {
+        case "text":
+            return { type: "text", text: block.text };
+        case "thinking":
+            return {
+                type: "thinking",
+                thinking: block.thinking,
+                ...(block.signature ? { thinkingSignature: block.signature } : {}),
+            };
+        case "tool_use":
+            return {
+                type: "toolCall",
+                id: block.id,
+                name: block.name,
+                arguments: block.input,
+            };
+        case "server_tool_use":
+            return {
+                type: "serverToolUse",
+                id: block.id,
+                name: block.name,
+                input: block.input,
+            };
+        case "web_search_tool_result":
+            return {
+                type: "webSearchResult",
+                toolUseId: block.tool_use_id,
+                content: block.content,
+            };
+        default: {
+            const unknown = block;
+            return { type: "text", text: `[unknown content block: ${JSON.stringify(unknown)}]` };
+        }
+    }
+}
+export function mapStopReason(reason) {
+    switch (reason) {
+        case "end_turn":
+        case "stop_sequence":
+            return "stop";
+        case "max_tokens":
+            return "length";
+        case "tool_use":
+            return "toolUse";
+        default:
+            return "stop";
+    }
+}
+/**
+ * Convert SDK usage + total_cost_usd into GSD's Usage shape.
+ *
+ * The SDK does not break cost down per-bucket, so all cost is
+ * attributed to `cost.total`.
+ */
+export function mapUsage(sdkUsage, totalCostUsd) {
+    return {
+        input: sdkUsage.input_tokens,
+        output: sdkUsage.output_tokens,
+        cacheRead: sdkUsage.cache_read_input_tokens,
+        cacheWrite: sdkUsage.cache_creation_input_tokens,
+        totalTokens: sdkUsage.input_tokens +
+            sdkUsage.output_tokens +
+            sdkUsage.cache_read_input_tokens +
+            sdkUsage.cache_creation_input_tokens,
+        cost: {
+            input: 0,
+            output: 0,
+            cacheRead: 0,
+            cacheWrite: 0,
+            total: totalCostUsd,
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Zero-cost usage constant
+// ---------------------------------------------------------------------------
+export const ZERO_USAGE = {
+    input: 0,
+    output: 0,
+    cacheRead: 0,
+    cacheWrite: 0,
+    totalTokens: 0,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+};
+// ---------------------------------------------------------------------------
+// Streaming partial-message state tracker
+// ---------------------------------------------------------------------------
+/**
+ * Mutable accumulator that tracks the partial AssistantMessage being built
+ * from a sequence of stream_event messages. Produces AssistantMessageEvent
+ * deltas that the TUI can render incrementally.
+ */
+export class PartialMessageBuilder {
+    partial;
+    /** Map from stream-event `index` to our content array index. */
+    indexMap = new Map();
+    /** Accumulated JSON input string per tool_use block (keyed by stream index). */
+    toolJsonAccum = new Map();
+    constructor(model) {
+        this.partial = {
+            role: "assistant",
+            content: [],
+            api: "anthropic-messages",
+            provider: "claude-code",
+            model,
+            usage: { ...ZERO_USAGE },
+            stopReason: "stop",
+            timestamp: Date.now(),
+        };
+    }
+    get message() {
+        return this.partial;
+    }
+    /**
+     * Feed a BetaRawMessageStreamEvent and return the corresponding
+     * AssistantMessageEvent (or null if the event is not mapped).
+     */
+    handleEvent(event) {
+        const streamIndex = event.index ?? 0;
+        switch (event.type) {
+            // ---- Block start ----
+            case "content_block_start": {
+                const block = event.content_block;
+                if (!block)
+                    return null;
+                const contentIndex = this.partial.content.length;
+                this.indexMap.set(streamIndex, contentIndex);
+                if (block.type === "text") {
+                    this.partial.content.push({ type: "text", text: "" });
+                    return { type: "text_start", contentIndex, partial: this.partial };
+                }
+                if (block.type === "thinking") {
+                    this.partial.content.push({ type: "thinking", thinking: "" });
+                    return { type: "thinking_start", contentIndex, partial: this.partial };
+                }
+                if (block.type === "tool_use") {
+                    this.toolJsonAccum.set(streamIndex, "");
+                    this.partial.content.push({
+                        type: "toolCall",
+                        id: block.id,
+                        name: block.name,
+                        arguments: {},
+                    });
+                    return { type: "toolcall_start", contentIndex, partial: this.partial };
+                }
+                if (block.type === "server_tool_use") {
+                    this.partial.content.push({
+                        type: "serverToolUse",
+                        id: block.id,
+                        name: block.name,
+                        input: block.input,
+                    });
+                    return { type: "server_tool_use", contentIndex, partial: this.partial };
+                }
+                return null;
+            }
+            // ---- Block delta ----
+            case "content_block_delta": {
+                const contentIndex = this.indexMap.get(streamIndex);
+                if (contentIndex === undefined)
+                    return null;
+                const delta = event.delta;
+                if (!delta)
+                    return null;
+                if (delta.type === "text_delta" && typeof delta.text === "string") {
+                    const existing = this.partial.content[contentIndex];
+                    existing.text += delta.text;
+                    return { type: "text_delta", contentIndex, delta: delta.text, partial: this.partial };
+                }
+                if (delta.type === "thinking_delta" && typeof delta.thinking === "string") {
+                    const existing = this.partial.content[contentIndex];
+                    existing.thinking += delta.thinking;
+                    return { type: "thinking_delta", contentIndex, delta: delta.thinking, partial: this.partial };
+                }
+                if (delta.type === "input_json_delta" && typeof delta.partial_json === "string") {
+                    const accum = (this.toolJsonAccum.get(streamIndex) ?? "") + delta.partial_json;
+                    this.toolJsonAccum.set(streamIndex, accum);
+                    return { type: "toolcall_delta", contentIndex, delta: delta.partial_json, partial: this.partial };
+                }
+                return null;
+            }
+            // ---- Block stop ----
+            case "content_block_stop": {
+                const contentIndex = this.indexMap.get(streamIndex);
+                if (contentIndex === undefined)
+                    return null;
+                const block = this.partial.content[contentIndex];
+                if (block.type === "text") {
+                    return { type: "text_end", contentIndex, content: block.text, partial: this.partial };
+                }
+                if (block.type === "thinking") {
+                    return { type: "thinking_end", contentIndex, content: block.thinking, partial: this.partial };
+                }
+                if (block.type === "toolCall") {
+                    const jsonStr = this.toolJsonAccum.get(streamIndex) ?? "{}";
+                    try {
+                        block.arguments = JSON.parse(jsonStr);
+                    }
+                    catch {
+                        block.arguments = { _raw: jsonStr };
+                    }
+                    return { type: "toolcall_end", contentIndex, toolCall: block, partial: this.partial };
+                }
+                return null;
+            }
+            default:
+                return null;
+        }
+    }
+}

package/dist/resources/extensions/claude-code-cli/readiness.js

@@ -0,0 +1,26 @@
+/**
+ * Readiness check for the Claude Code CLI provider.
+ *
+ * Verifies the `claude` binary is installed and responsive.
+ * Result is cached for 30 seconds to avoid shelling out on every
+ * model-availability check.
+ */
+import { execSync } from "node:child_process";
+let cachedReady = null;
+let lastCheckMs = 0;
+const CHECK_INTERVAL_MS = 30_000;
+export function isClaudeCodeReady() {
+    const now = Date.now();
+    if (cachedReady !== null && now - lastCheckMs < CHECK_INTERVAL_MS) {
+        return cachedReady;
+    }
+    try {
+        execSync("claude --version", { timeout: 5_000, stdio: "pipe" });
+        cachedReady = true;
+    }
+    catch {
+        cachedReady = false;
+    }
+    lastCheckMs = now;
+    return cachedReady;
+}

package/dist/resources/extensions/claude-code-cli/sdk-types.js

@@ -0,0 +1,8 @@
+/**
+ * Lightweight type mirrors for the Claude Agent SDK.
+ *
+ * These stubs allow the extension to compile without a hard dependency on
+ * `@anthropic-ai/claude-agent-sdk`. The real SDK is imported dynamically
+ * at runtime in stream-adapter.ts.
+ */
+export {};

package/dist/resources/extensions/claude-code-cli/stream-adapter.js

@@ -0,0 +1,293 @@
+/**
+ * Stream adapter: bridges the Claude Agent SDK into GSD's streamSimple contract.
+ *
+ * The SDK runs the full agentic loop (multi-turn, tool execution, compaction)
+ * in one call. This adapter translates the SDK's streaming output into
+ * AssistantMessageEvents for TUI rendering, then strips tool-call blocks from
+ * the final AssistantMessage so GSD's agent loop doesn't try to dispatch them.
+ */
+import { EventStream } from "@gsd/pi-ai";
+import { execSync } from "node:child_process";
+import { PartialMessageBuilder, ZERO_USAGE, mapUsage } from "./partial-builder.js";
+// ---------------------------------------------------------------------------
+// Stream factory
+// ---------------------------------------------------------------------------
+/**
+ * Construct an AssistantMessageEventStream using EventStream directly.
+ * (The class itself is only re-exported as a type from the @gsd/pi-ai barrel.)
+ */
+function createAssistantStream() {
+    return new EventStream((event) => event.type === "done" || event.type === "error", (event) => {
+        if (event.type === "done")
+            return event.message;
+        if (event.type === "error")
+            return event.error;
+        throw new Error("Unexpected event type for final result");
+    });
+}
+// ---------------------------------------------------------------------------
+// Claude binary resolution
+// ---------------------------------------------------------------------------
+let cachedClaudePath = null;
+/**
+ * Resolve the path to the system-installed `claude` binary.
+ * The SDK defaults to a bundled cli.js which doesn't exist when
+ * installed as a library — we need to point it at the real CLI.
+ */
+function getClaudePath() {
+    if (cachedClaudePath)
+        return cachedClaudePath;
+    try {
+        cachedClaudePath = execSync("which claude", { timeout: 5_000, stdio: "pipe" })
+            .toString()
+            .trim();
+    }
+    catch {
+        cachedClaudePath = "claude"; // fall back to PATH resolution
+    }
+    return cachedClaudePath;
+}
+// ---------------------------------------------------------------------------
+// Prompt extraction
+// ---------------------------------------------------------------------------
+/**
+ * Extract the last user prompt text from GSD's context messages.
+ * The SDK manages its own conversation history — we only send
+ * the latest user message as the prompt.
+ */
+function extractLastUserPrompt(context) {
+    for (let i = context.messages.length - 1; i >= 0; i--) {
+        const msg = context.messages[i];
+        if (msg.role === "user") {
+            if (typeof msg.content === "string")
+                return msg.content;
+            if (Array.isArray(msg.content)) {
+                const textParts = msg.content
+                    .filter((part) => part.type === "text")
+                    .map((part) => part.text);
+                if (textParts.length > 0)
+                    return textParts.join("\n");
+            }
+        }
+    }
+    return "";
+}
+// ---------------------------------------------------------------------------
+// Error helper
+// ---------------------------------------------------------------------------
+function makeErrorMessage(model, errorMsg) {
+    return {
+        role: "assistant",
+        content: [{ type: "text", text: `Claude Code error: ${errorMsg}` }],
+        api: "anthropic-messages",
+        provider: "claude-code",
+        model,
+        usage: { ...ZERO_USAGE },
+        stopReason: "error",
+        errorMessage: errorMsg,
+        timestamp: Date.now(),
+    };
+}
+// ---------------------------------------------------------------------------
+// streamSimple implementation
+// ---------------------------------------------------------------------------
+/**
+ * GSD streamSimple function that delegates to the Claude Agent SDK.
+ *
+ * Emits AssistantMessageEvent deltas for real-time TUI rendering
+ * (thinking, text, tool calls). The final AssistantMessage has tool-call
+ * blocks stripped so the agent loop ends the turn without local dispatch.
+ */
+export function streamViaClaudeCode(model, context, options) {
+    const stream = createAssistantStream();
+    void pumpSdkMessages(model, context, options, stream);
+    return stream;
+}
+async function pumpSdkMessages(model, context, options, stream) {
+    const modelId = model.id;
+    let builder = null;
+    /** Track the last text content seen across all assistant turns for the final message. */
+    let lastTextContent = "";
+    let lastThinkingContent = "";
+    try {
+        // Dynamic import — the SDK is an optional dependency.
+        const sdkModule = "@anthropic-ai/claude-agent-sdk";
+        const sdk = (await import(/* webpackIgnore: true */ sdkModule));
+        // Bridge GSD's AbortSignal to SDK's AbortController
+        const controller = new AbortController();
+        if (options?.signal) {
+            options.signal.addEventListener("abort", () => controller.abort(), { once: true });
+        }
+        const prompt = extractLastUserPrompt(context);
+        const queryResult = sdk.query({
+            prompt,
+            options: {
+                pathToClaudeCodeExecutable: getClaudePath(),
+                model: modelId,
+                includePartialMessages: true,
+                persistSession: false,
+                abortController: controller,
+                cwd: process.cwd(),
+                permissionMode: "bypassPermissions",
+                allowDangerouslySkipPermissions: true,
+                settingSources: ["project"],
+                systemPrompt: { type: "preset", preset: "claude_code" },
+                betas: modelId.includes("sonnet") ? ["context-1m-2025-08-07"] : [],
+            },
+        });
+        // Emit start with an empty partial
+        const initialPartial = {
+            role: "assistant",
+            content: [],
+            api: "anthropic-messages",
+            provider: "claude-code",
+            model: modelId,
+            usage: { ...ZERO_USAGE },
+            stopReason: "stop",
+            timestamp: Date.now(),
+        };
+        stream.push({ type: "start", partial: initialPartial });
+        for await (const msg of queryResult) {
+            if (options?.signal?.aborted)
+                break;
+            switch (msg.type) {
+                // -- Init --
+                case "system": {
+                    // Nothing to emit — the stream is already started.
+                    break;
+                }
+                // -- Streaming partial messages --
+                case "stream_event": {
+                    const partial = msg;
+                    if (partial.parent_tool_use_id !== null)
+                        break; // skip subagent
+                    const event = partial.event;
+                    // New assistant turn starts with message_start
+                    if (event.type === "message_start") {
+                        builder = new PartialMessageBuilder(event.message?.model ?? modelId);
+                        break;
+                    }
+                    if (!builder)
+                        break;
+                    const assistantEvent = builder.handleEvent(event);
+                    if (assistantEvent) {
+                        stream.push(assistantEvent);
+                    }
+                    break;
+                }
+                // -- Complete assistant message (non-streaming fallback) --
+                case "assistant": {
+                    const sdkAssistant = msg;
+                    if (sdkAssistant.parent_tool_use_id !== null)
+                        break;
+                    // Capture text content from complete messages
+                    for (const block of sdkAssistant.message.content) {
+                        if (block.type === "text") {
+                            lastTextContent = block.text;
+                        }
+                        else if (block.type === "thinking") {
+                            lastThinkingContent = block.thinking;
+                        }
+                    }
+                    break;
+                }
+                // -- User message (synthetic tool result — signals turn boundary) --
+                case "user": {
+                    const userMsg = msg;
+                    if (userMsg.parent_tool_use_id !== null)
+                        break;
+                    // Capture accumulated text from the builder before resetting
+                    if (builder) {
+                        for (const block of builder.message.content) {
+                            if (block.type === "text" && block.text) {
+                                lastTextContent = block.text;
+                            }
+                            else if (block.type === "thinking" && block.thinking) {
+                                lastThinkingContent = block.thinking;
+                            }
+                        }
+                    }
+                    builder = null;
+                    break;
+                }
+                // -- Result (terminal) --
+                case "result": {
+                    const result = msg;
+                    // Build final message with text/thinking only (strip tool calls)
+                    const finalContent = [];
+                    // Use builder's accumulated content if available, falling back to captured text
+                    if (builder) {
+                        for (const block of builder.message.content) {
+                            if (block.type === "text" && block.text) {
+                                lastTextContent = block.text;
+                            }
+                            else if (block.type === "thinking" && block.thinking) {
+                                lastThinkingContent = block.thinking;
+                            }
+                        }
+                    }
+                    if (lastThinkingContent) {
+                        finalContent.push({ type: "thinking", thinking: lastThinkingContent });
+                    }
+                    if (lastTextContent) {
+                        finalContent.push({ type: "text", text: lastTextContent });
+                    }
+                    // Fallback: use the SDK's result text if we have no content
+                    if (finalContent.length === 0 && result.subtype === "success" && result.result) {
+                        finalContent.push({ type: "text", text: result.result });
+                    }
+                    const finalMessage = {
+                        role: "assistant",
+                        content: finalContent,
+                        api: "anthropic-messages",
+                        provider: "claude-code",
+                        model: modelId,
+                        usage: mapUsage(result.usage, result.total_cost_usd),
+                        stopReason: result.is_error ? "error" : "stop",
+                        timestamp: Date.now(),
+                    };
+                    if (result.is_error) {
+                        const errText = "errors" in result
+                            ? result.errors?.join("; ")
+                            : result.subtype;
+                        finalMessage.errorMessage = errText;
+                        stream.push({ type: "error", reason: "error", error: finalMessage });
+                    }
+                    else {
+                        stream.push({ type: "done", reason: "stop", message: finalMessage });
+                    }
+                    return;
+                }
+                default:
+                    break;
+            }
+        }
+        // Generator exhausted without a result message (unexpected)
+        const fallbackContent = [];
+        if (lastTextContent) {
+            fallbackContent.push({ type: "text", text: lastTextContent });
+        }
+        if (fallbackContent.length === 0) {
+            fallbackContent.push({ type: "text", text: "(Claude Code session ended without a response)" });
+        }
+        const fallback = {
+            role: "assistant",
+            content: fallbackContent,
+            api: "anthropic-messages",
+            provider: "claude-code",
+            model: modelId,
+            usage: { ...ZERO_USAGE },
+            stopReason: "stop",
+            timestamp: Date.now(),
+        };
+        stream.push({ type: "done", reason: "stop", message: fallback });
+    }
+    catch (err) {
+        const errorMsg = err instanceof Error ? err.message : String(err);
+        stream.push({
+            type: "error",
+            reason: "error",
+            error: makeErrorMessage(modelId, errorMsg),
+        });
+    }
+}

package/dist/resources/extensions/gsd/prompts/complete-slice.md

@@ -32,6 +32,6 @@ Then:
 11. Do not run git commands — the system commits your changes and handles any merge after this unit succeeds.
 12. Update `.gsd/PROJECT.md` if it exists — refresh current state if needed.
 
-**You MUST do ALL THREE before finishing: (1) write `{{sliceSummaryPath}}`, (2) write `{{sliceUatPath}}`, (3) call `gsd_complete_slice`. The unit will not be marked complete if any of these are missing.**
+**You MUST call `gsd_complete_slice` with the slice summary and UAT content before finishing. The tool persists to both DB and disk and renders `{{sliceSummaryPath}}` and `{{sliceUatPath}}` automatically.**
 
 When done, say: "Slice {{sliceId}} complete."

package/dist/resources/extensions/gsd/prompts/guided-plan-milestone.md

@@ -10,10 +10,10 @@ Plan milestone {{milestoneId}} ("{{milestoneTitle}}"). Read `.gsd/DECISIONS.md`
 ## Planning Doctrine
 
 - **Risk-first means proof-first.** The earliest slices should prove the hardest thing works by shipping the real feature through the uncertain path. If auth is the risk, the first slice ships a real login page with real session handling that a user can actually use — not a CLI command that returns "authenticated: true". Proof is the shipped feature working. There is no separate "proof" artifact. Do not plan spikes, proof-of-concept slices, or validation-only slices — the proof is the real feature, built through the risky path.
-- **Every slice is vertical, demoable, and shippable.** Every slice ships real, user-facing functionality. "Demoable" means you could show a stakeholder and they'd see real product progress — not a developer showing a terminal command. If the only way to demonstrate the slice is through a test runner or a curl command, the slice is missing its UI/UX surface. Add it. A slice that only proves something but doesn't ship real working code is not a slice — restructure it.
+- **Every slice is vertical, demoable, and shippable.** Every slice ships real, user-facing functionality. "Demoable" means the intended user can exercise the capability through its real interface — for a web app that's the UI, for a CLI tool that's the terminal, for an API that's a consuming client or curl. The test is: can someone *use* it, not just *assert* it passes. A slice that only proves something but doesn't ship real working code is not a slice — restructure it.
 - **Brownfield bias.** When planning against an existing codebase, ground slices in existing modules, conventions, and seams. Prefer extending real patterns over inventing new ones.
 - **Each slice should establish something downstream slices can depend on.** Think about what stable surface this slice creates for later work — an API, a data shape, a proven integration path.
-- **Avoid foundation-only slices.** If a slice doesn't produce something demoable end-to-end, it's probably a layer, not a vertical slice. Restructure it.
+- **Avoid foundation-only slices.** If a slice doesn't produce something demoable end-to-end, it's probably a layer, not a vertical slice. Restructure it. Exception: if the infrastructure *is* the product surface (a new protocol, extension API, or provider interface), the slice is vertical by definition — the downstream consumer is the demo.
 - **Verification-first.** When planning slices, know what "done" looks like before detailing implementation. Each slice's demo line should describe concrete, verifiable evidence — not vague "it works" claims.
 - **Plan for integrated reality, not just local proof.** Distinguish contract proof from live integration proof. If the milestone involves multiple runtime boundaries, one slice must explicitly prove the assembled system through the real entrypoint or runtime path.
 - **Truthful demo lines only.** If a slice is proven by fixtures or tests only, say so. Do not phrase harness-level proof as if the user can already perform the live end-to-end behavior unless that has actually been exercised.