@sweny-ai/core 0.1.76 → 0.1.78

package/dist/browser.d.ts

@@ -1,14 +1,20 @@
 /**
  * Browser-safe entry point for @sweny-ai/core
  *
- * Re-exports everything EXCEPT ClaudeClient (which depends on
- * @anthropic-ai/claude-agent-sdk, a Node-only package). Use this entry point
- * in browser environments (Vite, webpack, Astro, etc.).
+ * Exports only APIs that bundle cleanly in browser environments (Vite,
+ * webpack, Astro, etc.). Anything that pulls `node:fs`, `node:path`, or the
+ * Claude Code SDK lives in the Node entry (`@sweny-ai/core`).
+ *
+ * Not exported from here:
+ *   - `ClaudeClient` — depends on `@anthropic-ai/claude-agent-sdk` (Node-only).
+ *   - `execute` / `ExecuteOptions` — `executor.ts` → `source-resolver.ts`
+ *     imports `node:fs/promises` for URL/file Source fetching. Import from
+ *     the Node entry when you need to run a workflow.
+ *   - `buildWorkflow` / `refineWorkflow` — depend on the Claude interface.
+ *   - Testing helpers — `MockClaude`, `createFileSkill` use `node:fs`.
  */
 export type { Skill, SkillCategory, Tool, ToolContext, ConfigField, JSONSchema, Workflow, Node, Edge, NodeResult, ToolCall, ExecutionEvent, Observer, Claude, Logger, } from "./types.js";
 export { consoleLogger } from "./types.js";
-export { execute } from "./executor.js";
-export type { ExecuteOptions } from "./executor.js";
 export { github, linear, slack, sentry, datadog, notification, builtinSkills, createSkillMap, allSkills, isSkillConfigured, configuredBuiltinSkills, validateWorkflowSkills, } from "./skills/index.js";
 export type { SkillValidationResult } from "./skills/index.js";
 export { workflowZ, nodeZ, edgeZ, skillZ, parseWorkflow, validateWorkflow, workflowJsonSchema } from "./schema.js";

package/dist/browser.js

@@ -1,22 +1,22 @@
 /**
  * Browser-safe entry point for @sweny-ai/core
  *
- * Re-exports everything EXCEPT ClaudeClient (which depends on
- * @anthropic-ai/claude-agent-sdk, a Node-only package). Use this entry point
- * in browser environments (Vite, webpack, Astro, etc.).
+ * Exports only APIs that bundle cleanly in browser environments (Vite,
+ * webpack, Astro, etc.). Anything that pulls `node:fs`, `node:path`, or the
+ * Claude Code SDK lives in the Node entry (`@sweny-ai/core`).
+ *
+ * Not exported from here:
+ *   - `ClaudeClient` — depends on `@anthropic-ai/claude-agent-sdk` (Node-only).
+ *   - `execute` / `ExecuteOptions` — `executor.ts` → `source-resolver.ts`
+ *     imports `node:fs/promises` for URL/file Source fetching. Import from
+ *     the Node entry when you need to run a workflow.
+ *   - `buildWorkflow` / `refineWorkflow` — depend on the Claude interface.
+ *   - Testing helpers — `MockClaude`, `createFileSkill` use `node:fs`.
  */
 export { consoleLogger } from "./types.js";
-// Executor
-export { execute } from "./executor.js";
 // Skills (browser-safe — no filesystem access, no `process.env` reads)
 export { github, linear, slack, sentry, datadog, notification, builtinSkills, createSkillMap, allSkills, isSkillConfigured, configuredBuiltinSkills, validateWorkflowSkills, } from "./skills/index.js";
 // Schema & validation
 export { workflowZ, nodeZ, edgeZ, skillZ, parseWorkflow, validateWorkflow, workflowJsonSchema } from "./schema.js";
 // Studio adapter
 export { workflowToFlow, flowToWorkflow, applyExecutionEvent, exportAsTypescript, getSkillCatalog } from "./studio.js";
-// Workflow builder — NOT included in browser entry.
-// buildWorkflow/refineWorkflow depend on the Claude interface (Node-only).
-// Import from "@sweny-ai/core" in Node environments.
-// Testing utilities — NOT included in browser entry.
-// MockClaude and createFileSkill depend on node:fs.
-// Import from "@sweny-ai/core/testing" in Node environments.

package/dist/claude.d.ts

@@ -53,4 +53,24 @@ export declare class ClaudeClient implements Claude {
             description: string;
         }[];
     }): Promise<string>;
+    ask(opts: {
+        instruction: string;
+        context: Record<string, unknown>;
+    }): Promise<string>;
 }
+/**
+ * Best-effort recovery of typed output from a tool_result's `content`.
+ *
+ * The MCP protocol sends tool results as string content. Our in-process
+ * wrapper JSON-stringifies structured output before returning; external
+ * MCP servers generally do the same for JSON payloads. If the string
+ * looks like a JSON object or array and parses, return the parsed value
+ * so verify's output-path walks work against typed data.
+ *
+ * Raw strings are preserved verbatim. JSON-primitive strings (e.g. the
+ * literal four characters `"42"`) are intentionally NOT parsed — we
+ * cannot distinguish a tool that returned the number 42 (wrapper sends
+ * `"42"`) from a tool that returned the string "42" (wrapper also sends
+ * `"42"`). Preserving the string is safer than guessing.
+ */
+export declare function parseToolResultContent(content: unknown): unknown;

package/dist/claude.js

@@ -41,9 +41,28 @@ export class ClaudeClient {
     }
     async run(opts) {
         const { instruction, context, tools, outputSchema, onProgress, maxTurns } = opts;
+        // Tool-call accounting (Fix #1).
+        //
+        // Stream-driven recording, correlated by tool_use_id:
+        //   - `assistant` message with tool_use block → create a pending ToolCall
+        //     and register it in `pendingByUseId` under its tool_use_id.
+        //   - `user` message with tool_result block → look up by tool_use_id, set
+        //     `status` from `is_error`, and recover the typed output by parsing
+        //     the stringified `content` field (our wrapper JSON-stringifies it
+        //     before returning; external MCP servers also return structured
+        //     content).
+        //
+        // Keying by tool_use_id (not by tool name) avoids mis-pairing when
+        // Claude invokes the same tool in parallel — the self-review test
+        // `pairs parallel same-named in-process tool outputs correctly` shows
+        // why FIFO-by-name is wrong.
         const toolCalls = [];
-        // Convert core tools to SDK MCP tools
-        const sdkTools = tools.map((t) => coreToolToSdkTool(t, this.defaultContext, toolCalls));
+        const pendingByUseId = new Map();
+        // Convert core tools to SDK MCP tools. The wrapper invokes the user's
+        // handler and returns `content` via the MCP transport. We do not push
+        // to toolCalls from the wrapper — the stream's tool_result is the sole
+        // signal of completion, which keeps pairing correct under parallelism.
+        const sdkTools = tools.map((t) => coreToolToSdkTool(t, this.defaultContext));
         // Create in-process MCP server
         const mcpServer = createSdkMcpServer({
             name: "sweny-core",
@@ -96,19 +115,51 @@ export class ClaudeClient {
                     }
                 }
                 else if (message.type === "assistant") {
-                    // Extract tool_use blocks from assistant messages (MCP tool calls)
+                    // Tool_use blocks start a ToolCall record. Status + output are
+                    // filled in when the matching user tool_result arrives.
                     const am = message;
                     if (am.message?.content && Array.isArray(am.message.content)) {
                         for (const block of am.message.content) {
                             if (block.type === "tool_use") {
-                                toolCalls.push({
+                                const call = {
                                     tool: stripMcpPrefix(block.name ?? ""),
                                     input: block.input,
-                                });
+                                };
+                                toolCalls.push(call);
+                                if (typeof block.id === "string")
+                                    pendingByUseId.set(block.id, call);
                             }
                         }
                     }
                 }
+                else if (message.type === "user") {
+                    // Tool_result blocks close the loop. Pair to the pending ToolCall
+                    // by tool_use_id — NOT by name, which would break parallel calls
+                    // of the same tool (see regression test).
+                    //
+                    // Output handling is unified across in-process and external tools:
+                    // our wrapper JSON-stringifies structured output before returning,
+                    // and external MCP servers also send structured content as string.
+                    // We parse the content back into a value so verify's output-path
+                    // checks work against typed data.
+                    const um = message;
+                    if (um.message?.content && Array.isArray(um.message.content)) {
+                        for (const block of um.message.content) {
+                            if (block.type !== "tool_result" || typeof block.tool_use_id !== "string")
+                                continue;
+                            const call = pendingByUseId.get(block.tool_use_id);
+                            if (!call)
+                                continue;
+                            // Delete after first match so a duplicate tool_result (SDK
+                            // retry, malformed stream) cannot overwrite a completed call.
+                            pendingByUseId.delete(block.tool_use_id);
+                            const isError = block.is_error === true;
+                            call.status = isError ? "error" : "success";
+                            const parsed = parseToolResultContent(block.content);
+                            call.output = isError ? { error: parsed } : parsed;
+                        }
+                    }
+                }
                 else if (message.type === "result") {
                     const resultMsg = message;
                     if (resultMsg.subtype === "success" && "result" in resultMsg) {
@@ -202,26 +253,72 @@ export class ClaudeClient {
         this.logger.warn(`Could not parse route choice from: "${text.slice(0, 100)}". Falling back to first choice.`);
         return validIds[0];
     }
+    async ask(opts) {
+        const { instruction, context } = opts;
+        const prompt = [
+            instruction,
+            Object.keys(context).length > 0 ? `\nContext:\n\`\`\`json\n${JSON.stringify(context, null, 2)}\n\`\`\`` : "",
+        ]
+            .filter(Boolean)
+            .join("\n");
+        const env = this.buildEnv();
+        let response = "";
+        try {
+            const stream = query({
+                prompt,
+                options: {
+                    maxTurns: 1,
+                    cwd: this.cwd,
+                    env,
+                    permissionMode: "bypassPermissions",
+                    allowDangerouslySkipPermissions: true,
+                    stderr: (data) => this.logger.debug(`[claude-code] ${data}`),
+                    ...(this.model ? { model: this.model } : {}),
+                },
+            });
+            for await (const message of stream) {
+                if (message.type === "result") {
+                    const resultMsg = message;
+                    if (resultMsg.subtype === "success" && "result" in resultMsg) {
+                        response = resultMsg.result;
+                    }
+                    else {
+                        this.logger.warn(`claude.ask: SDK returned non-success subtype "${resultMsg.subtype}" — returning empty string`);
+                    }
+                }
+            }
+        }
+        catch (err) {
+            this.logger.warn(`Ask query failed: ${err.message}`);
+            return "";
+        }
+        return response.trim();
+    }
 }
 // ─── Tool conversion ────────────────────────────────────────────
 /**
  * Convert a core Tool to an SDK MCP tool definition.
- * Bridges JSON Schema → Zod and wraps the handler to return CallToolResult.
+ *
+ * The wrapper runs the user's handler and returns the MCP `CallToolResult`.
+ * Output bookkeeping happens on the stream side (see the tool_result
+ * handler in `run()`), keyed by `tool_use_id` — never from inside the
+ * wrapper. Keeping the wrapper stateless means parallel calls to the same
+ * tool cannot mis-pair outputs.
  */
-function coreToolToSdkTool(coreTool, defaultCtx, toolCalls) {
+function coreToolToSdkTool(coreTool, defaultCtx) {
     const zodShape = jsonSchemaToZodShape(coreTool.input_schema);
     return sdkTool(coreTool.name, coreTool.description, zodShape, async (args) => {
         try {
             // The executor wraps handlers to inject ToolContext.
             // When used standalone, defaultCtx is the fallback.
             const output = await coreTool.handler(args, defaultCtx);
-            toolCalls.push({ tool: coreTool.name, input: args, output });
+            // JSON-stringify structured output so the tool_result handler can
+            // recover it via parseToolResultContent. Strings pass through.
             return {
                 content: [{ type: "text", text: typeof output === "string" ? output : JSON.stringify(output) }],
             };
         }
         catch (err) {
-            toolCalls.push({ tool: coreTool.name, input: args, output: { error: err.message } });
             return {
                 content: [{ type: "text", text: `Error: ${err.message}` }],
                 isError: true,
@@ -229,6 +326,39 @@ function coreToolToSdkTool(coreTool, defaultCtx, toolCalls) {
         }
     });
 }
+/**
+ * Best-effort recovery of typed output from a tool_result's `content`.
+ *
+ * The MCP protocol sends tool results as string content. Our in-process
+ * wrapper JSON-stringifies structured output before returning; external
+ * MCP servers generally do the same for JSON payloads. If the string
+ * looks like a JSON object or array and parses, return the parsed value
+ * so verify's output-path walks work against typed data.
+ *
+ * Raw strings are preserved verbatim. JSON-primitive strings (e.g. the
+ * literal four characters `"42"`) are intentionally NOT parsed — we
+ * cannot distinguish a tool that returned the number 42 (wrapper sends
+ * `"42"`) from a tool that returned the string "42" (wrapper also sends
+ * `"42"`). Preserving the string is safer than guessing.
+ */
+export function parseToolResultContent(content) {
+    if (typeof content !== "string")
+        return content;
+    const trimmed = content.trim();
+    if (trimmed.length === 0)
+        return content;
+    const first = trimmed[0];
+    // Only objects and arrays are unambiguous to parse. Strings, numbers,
+    // booleans, and null would all corrupt or discard information.
+    if (first !== "{" && first !== "[")
+        return content;
+    try {
+        return JSON.parse(trimmed);
+    }
+    catch {
+        return content;
+    }
+}
 // ─── JSON Schema → Zod conversion ───────────────────────────────
 /**
  * Convert a JSON Schema object to a Zod raw shape for the agent SDK.

package/dist/cli/config.d.ts

@@ -76,6 +76,28 @@ export declare function parseCliInputs(options: Record<string, unknown>, fileCon
  */
 export declare const SUPPORTED_WORKSPACE_TOOLS: Set<string>;
 export declare function validateInputs(config: CliConfig): string[];
+/**
+ * Parse a value as a positive integer (>= 1).
+ *
+ * Returns:
+ *   - the parsed integer when the input represents a positive finite one
+ *   - the fallback when the input is null/undefined/empty (unset flag)
+ *   - NaN for any malformed or non-positive input, so validateInputs can
+ *     surface a field-specific error
+ *
+ * Name enforces the contract: non-positive values (0, -5) return NaN so
+ * validation rejects them loudly rather than quietly passing through as
+ * `0` and breaking downstream invariants.
+ *
+ * Why zero is rejected: every current caller (max-investigate-turns,
+ * max-implement-turns, cache-ttl) uses the result as a positive count or
+ * timeout. There is no "zero means disabled" semantics anywhere — a
+ * cache-ttl of 0 wouldn't disable cache, it would expire entries
+ * immediately, which is broken. If a future flag wants "0 = disabled",
+ * use a sibling helper (parseNonNegativeInt) rather than weakening this
+ * one's contract.
+ */
+export declare function parsePositiveInt(raw: unknown, fallback: number): number;
 /**
  * Returns non-fatal warnings about the configuration.
  * These are surfaced before the spinner starts but do not abort the run.

package/dist/cli/config.js

@@ -116,8 +116,8 @@ export function parseCliInputs(options, fileConfig = {}) {
         severityFocus: options.severityFocus || f("severity-focus") || "errors",
         serviceFilter: options.serviceFilter || f("service-filter") || "*",
         investigationDepth: options.investigationDepth || f("investigation-depth") || "standard",
-        maxInvestigateTurns: parseInt(String(options.maxInvestigateTurns || f("max-investigate-turns") || "50"), 10),
-        maxImplementTurns: parseInt(String(options.maxImplementTurns || f("max-implement-turns") || "30"), 10),
+        maxInvestigateTurns: parsePositiveInt(options.maxInvestigateTurns ?? f("max-investigate-turns"), 50),
+        maxImplementTurns: parsePositiveInt(options.maxImplementTurns ?? f("max-implement-turns"), 30),
         baseBranch: options.baseBranch || f("base-branch") || "main",
         prLabels: (options.prLabels || f("pr-labels") || "agent,triage,needs-review")
             .split(",")
@@ -165,7 +165,7 @@ export function parseCliInputs(options, fileConfig = {}) {
         stream: Boolean(options.stream),
         bell: Boolean(options.bell),
         cacheDir: options.cacheDir || env.SWENY_CACHE_DIR || f("cache-dir") || ".sweny/cache",
-        cacheTtl: parseInt(String(options.cacheTtl || f("cache-ttl") || "86400"), 10),
+        cacheTtl: parsePositiveInt(options.cacheTtl ?? f("cache-ttl"), 86400),
         noCache: options.cache === false,
         outputDir: options.outputDir || env.SWENY_OUTPUT_DIR || f("output-dir") || ".sweny/output",
         mcpServers: parseMcpServers(env.SWENY_MCP_SERVERS || f("mcp-servers-json") || ""),
@@ -424,14 +424,61 @@ export function validateInputs(config) {
     if (!["auto", "review"].includes(config.reviewMode)) {
         errors.push("--review-mode must be one of: auto, review");
     }
-    // Integer bounds
-    if (config.maxInvestigateTurns < 1 || config.maxInvestigateTurns > 500) {
-        errors.push("--max-investigate-turns must be between 1 and 500");
+    // Integer bounds — reject NaN and Infinity first (parseInt can yield NaN
+    // silently and NaN compares false to both < min and > max, so the old
+    // bounds check let junk through).
+    validateIntegerBound(errors, "--max-investigate-turns", config.maxInvestigateTurns, 1, 500);
+    validateIntegerBound(errors, "--max-implement-turns", config.maxImplementTurns, 1, 500);
+    return errors;
+}
+function validateIntegerBound(errors, flag, value, min, max) {
+    if (!Number.isFinite(value)) {
+        errors.push(`${flag} must be a finite integer between ${min} and ${max} (got "${value}")`);
+        return;
     }
-    if (config.maxImplementTurns < 1 || config.maxImplementTurns > 500) {
-        errors.push("--max-implement-turns must be between 1 and 500");
+    if (value < min || value > max) {
+        errors.push(`${flag} must be between ${min} and ${max}`);
     }
-    return errors;
+}
+/**
+ * Parse a value as a positive integer (>= 1).
+ *
+ * Returns:
+ *   - the parsed integer when the input represents a positive finite one
+ *   - the fallback when the input is null/undefined/empty (unset flag)
+ *   - NaN for any malformed or non-positive input, so validateInputs can
+ *     surface a field-specific error
+ *
+ * Name enforces the contract: non-positive values (0, -5) return NaN so
+ * validation rejects them loudly rather than quietly passing through as
+ * `0` and breaking downstream invariants.
+ *
+ * Why zero is rejected: every current caller (max-investigate-turns,
+ * max-implement-turns, cache-ttl) uses the result as a positive count or
+ * timeout. There is no "zero means disabled" semantics anywhere — a
+ * cache-ttl of 0 wouldn't disable cache, it would expire entries
+ * immediately, which is broken. If a future flag wants "0 = disabled",
+ * use a sibling helper (parseNonNegativeInt) rather than weakening this
+ * one's contract.
+ */
+export function parsePositiveInt(raw, fallback) {
+    if (raw === undefined || raw === null || raw === "")
+        return fallback;
+    if (typeof raw === "number") {
+        if (!Number.isFinite(raw))
+            return Number.NaN;
+        const truncated = Math.trunc(raw);
+        return truncated >= 1 ? truncated : Number.NaN;
+    }
+    const asString = String(raw).trim();
+    if (asString.length === 0)
+        return fallback;
+    // Number() is stricter than parseInt — "5o" → NaN rather than 5.
+    const parsed = Number(asString);
+    if (!Number.isFinite(parsed))
+        return Number.NaN;
+    const truncated = Math.trunc(parsed);
+    return truncated >= 1 ? truncated : Number.NaN;
 }
 const DEFAULT_SERVICE_MAP_PATH = ".github/service-map.yml";
 /**

package/dist/cli/main.d.ts

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import type { Workflow } from "../types.js";
-export declare function loadWorkflowFile(filePath: string): Workflow;
+export declare function loadWorkflowFile(filePath: string, knownSkills?: Set<string>): Workflow;
 export declare function workflowRunAction(file: string, options: Record<string, unknown> & {
     json?: boolean;
     stream?: boolean;

package/dist/cli/main.js

@@ -11,11 +11,11 @@ import { triageWorkflow, implementWorkflow, seedContentWorkflow } from "../workf
 import { consoleLogger } from "../types.js";
 import { ClaudeClient } from "../claude.js";
 import { createSkillMap, validateWorkflowSkills } from "../skills/index.js";
-import { configuredSkills } from "../skills/custom-loader.js";
+import { configuredSkills, configuredSkillsWithDiagnostics } from "../skills/custom-loader.js";
 import { buildAutoMcpServers, buildSkillMcpServers, buildProviderContext } from "../mcp.js";
 import { loadAdditionalContext } from "../templates.js";
-import { validateWorkflow as validateWorkflowSchema } from "../schema.js";
-import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+import { loadAndValidateWorkflow } from "../loader.js";
+import { stringify as stringifyYaml } from "yaml";
 import { buildWorkflow, refineWorkflow } from "../workflow-builder.js";
 import { toMermaidBlock } from "../mermaid.js";
 import { runWorkflowDiagram } from "./diagram.js";
@@ -140,11 +140,20 @@ function buildProviderCtx(config, mcpServers) {
 /**
  * Resolve rules and context from config into structured workflow input fields.
  * All source kinds (inline, file, URL) are resolved eagerly.
+ *
+ * `offline` and `fetchAuth` are threaded through so CLI-preloaded rules/context
+ * honor the same policy as Sources resolved later by the executor (Fix #16).
  */
 async function resolveRulesAndContext(config) {
+    const loadOptions = {
+        cwd: process.cwd(),
+        offline: config.offline,
+        fetchAuth: config.fetchAuth,
+        env: process.env,
+    };
     const [rulesResult, contextResult] = await Promise.all([
-        loadAdditionalContext(config.rules),
-        loadAdditionalContext(config.context),
+        loadAdditionalContext(config.rules, loadOptions),
+        loadAdditionalContext(config.context, loadOptions),
     ]);
     return {
         rules: rulesResult.resolved,
@@ -172,7 +181,11 @@ triageCmd.action(async (options) => {
         console.log(formatBanner(config, version));
     }
     // ── Build skill map + MCP servers + Claude client ──────────
-    const skills = createSkillMap(configuredSkills(process.env, process.cwd()));
+    const triageSkillDiscovery = configuredSkillsWithDiagnostics(process.env, process.cwd());
+    for (const w of triageSkillDiscovery.warnings) {
+        console.error(chalk.yellow(`  ⚠  ${w.message}`));
+    }
+    const skills = createSkillMap(triageSkillDiscovery.skills);
     const mcpAutoConfig = buildMcpAutoConfig(config);
     const mcpServers = buildAutoMcpServers(mcpAutoConfig);
     const claude = new ClaudeClient({
@@ -423,7 +436,11 @@ implementCmd.action(async (issueId, options) => {
             fileConfig["output-dir"] ||
             ".sweny/output",
     };
-    const skills = createSkillMap(configuredSkills(process.env, process.cwd()));
+    const implementSkillDiscovery = configuredSkillsWithDiagnostics(process.env, process.cwd());
+    for (const w of implementSkillDiscovery.warnings) {
+        console.error(chalk.yellow(`  ⚠  ${w.message}`));
+    }
+    const skills = createSkillMap(implementSkillDiscovery.skills);
     const mcpAutoConfig = buildMcpAutoConfig(config);
     const mcpServers = buildAutoMcpServers(mcpAutoConfig);
     const claude = new ClaudeClient({
@@ -532,31 +549,36 @@ function promptUser(question) {
     });
 }
 const workflowCmd = program.command("workflow").description("Manage and run workflow files");
-/** Reads and parses a workflow file (YAML or JSON). Throws on I/O or parse error. */
-function parseWorkflowFileContent(filePath) {
-    const content = fs.readFileSync(filePath, "utf-8");
-    const ext = path.extname(filePath).toLowerCase();
-    return ext === ".yaml" || ext === ".yml" ? parseYaml(content) : JSON.parse(content);
-}
-export function loadWorkflowFile(filePath) {
-    const raw = parseWorkflowFileContent(filePath);
-    const errors = validateWorkflowSchema(raw);
-    if (errors.length > 0) {
-        throw new Error(`Invalid workflow file:\n${errors.map((e) => `  ${e.message}`).join("\n")}`);
+export function loadWorkflowFile(filePath, knownSkills) {
+    const result = loadAndValidateWorkflow(filePath, { knownSkills });
+    if (!result.ok) {
+        throw new Error(`Invalid workflow file:\n${result.errors.map((e) => `  ${e.message}`).join("\n")}`);
     }
-    return raw;
+    return result.workflow;
 }
 export async function workflowRunAction(file, options) {
+    // Discover skills first so the loader can flag UNKNOWN_SKILL at parse
+    // time. validateWorkflowSkills below still runs for richer category /
+    // env-var diagnostics, but the loader's structural check fires earlier
+    // and gives users a clear "you typed `gtihub`" pointer before any other
+    // validation noise.
+    const earlySkillDiscovery = configuredSkillsWithDiagnostics(process.env, process.cwd());
+    for (const w of earlySkillDiscovery.warnings) {
+        console.error(chalk.yellow(`  ⚠  ${w.message}`));
+    }
+    const knownSkillIds = new Set(earlySkillDiscovery.skills.map((s) => s.id));
     let workflow;
     try {
-        workflow = loadWorkflowFile(file);
+        workflow = loadWorkflowFile(file, knownSkillIds);
     }
     catch (err) {
         console.error(chalk.red(`  Error loading workflow file: ${err instanceof Error ? err.message : String(err)}`));
         process.exit(1);
         return;
     }
-    if (options.dryRun) {
+    // --list-nodes: lightweight static inspection, no execution. Used to be
+    // the behavior of --dry-run before Fix #6.
+    if (options.listNodes) {
         console.log(chalk.green(`  Workflow "${workflow.name}" is valid (${Object.keys(workflow.nodes).length} nodes)`));
         for (const [id, node] of Object.entries(workflow.nodes)) {
             console.log(chalk.dim(`    ${id}: ${node.name}${node.skills.length ? ` skills=[${node.skills.join(",")}]` : ""}`));
@@ -568,11 +590,13 @@ export async function workflowRunAction(file, options) {
     const config = parseCliInputs(options, fileConfig);
     const isJson = Boolean(options.json);
     const isTTY = !isJson && (process.stderr.isTTY ?? false);
-    const skills = createSkillMap(configuredSkills(process.env, process.cwd()));
+    // Reuse the discovery pulled before workflow load (above). Diagnostics
+    // already surfaced; just turn the skill list into a map for the executor.
+    const skills = createSkillMap(earlySkillDiscovery.skills);
     // Hard-fail at startup if the workflow references skills that aren't available.
     // Each node lists alternatives by category (e.g. [sentry, datadog, betterstack]);
     // we require at least one configured skill per category.
-    const validation = validateWorkflowSkills(workflow, skills);
+    const validation = validateWorkflowSkills(workflow, skills, workflow.skills);
     if (validation.errors.length > 0) {
         console.error(chalk.red(`\n  Workflow cannot run — missing required skills:\n`));
         for (const err of validation.errors)
@@ -743,47 +767,21 @@ export function workflowExportAction(name) {
     process.stdout.write(stringifyYaml(workflow, { indent: 2, lineWidth: 120 }));
 }
 export function workflowValidateAction(file, options) {
-    let raw;
-    try {
-        raw = parseWorkflowFileContent(file);
-    }
-    catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        if (options.json) {
-            process.stderr.write(JSON.stringify({ valid: false, errors: [{ message }] }, null, 2) + "\n");
-        }
-        else {
-            console.error(chalk.red(`  Cannot read "${file}": ${message}`));
-        }
-        process.exit(1);
-        return;
-    }
-    if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
-        const kind = raw === null ? "null" : Array.isArray(raw) ? "array" : typeof raw;
-        const message = `Expected a YAML/JSON object, got ${kind}`;
-        if (options.json) {
-            process.stderr.write(JSON.stringify({ valid: false, errors: [{ message }] }, null, 2) + "\n");
-        }
-        else {
-            console.error(chalk.red(`  \u2717 ${file}: ${message}`));
-        }
-        process.exit(1);
-        return;
-    }
-    const errors = validateWorkflowSchema(raw);
+    const result = loadAndValidateWorkflow(file);
     if (options.json) {
-        process.stdout.write(JSON.stringify({ valid: errors.length === 0, errors }, null, 2) + "\n");
+        const errs = result.ok ? [] : result.errors;
+        process.stdout.write(JSON.stringify({ valid: result.ok, errors: errs }, null, 2) + "\n");
     }
-    else if (errors.length === 0) {
+    else if (result.ok) {
         console.log(chalk.green(`  \u2713 ${file} is valid`));
     }
     else {
-        console.error(chalk.red(`  \u2717 ${file} has ${errors.length} validation error${errors.length > 1 ? "s" : ""}:`));
-        for (const err of errors) {
+        console.error(chalk.red(`  \u2717 ${file} has ${result.errors.length} validation error${result.errors.length > 1 ? "s" : ""}:`));
+        for (const err of result.errors) {
             console.error(chalk.dim(`    ${err.message}`));
         }
     }
-    process.exit(errors.length === 0 ? 0 : 1);
+    process.exit(result.ok ? 0 : 1);
 }
 workflowCmd
     .command("validate <file>")
@@ -793,7 +791,8 @@ workflowCmd
 workflowCmd
     .command("run <file>")
     .description("Run a workflow from a YAML or JSON file")
-    .option("--dry-run", "Validate workflow without running")
+    .option("--dry-run", "Execute until the first conditional routing decision, then stop (no side effects past that point). NOTE: behavior changed in this release — previously --dry-run only printed the node list. For that behavior use --list-nodes.")
+    .option("--list-nodes", "Validate, print nodes/skills, and exit without running. (Replaces the pre-Fix-#6 --dry-run behavior.)")
     .option("--json", "Output result as JSON on stdout; suppress progress output")
     .option("--stream", "Stream NDJSON events to stdout (for Studio / automation)")
     .option("--mermaid", "Output a Mermaid diagram with execution state after run")