@sweny-ai/core 0.1.26 → 0.1.28

package/dist/__tests__/executor.test.js

@@ -66,7 +66,7 @@ describe("executor", () => {
             },
         });
         const events = [];
-        const results = await execute(linearWorkflow, { alert: "test" }, {
+        const { results } = await execute(linearWorkflow, { alert: "test" }, {
             skills: createSkillMap([fileSkill]),
             claude,
             observer: (e) => events.push(e),
@@ -92,7 +92,7 @@ describe("executor", () => {
             },
             routes: { check: "high" },
         });
-        const results = await execute(branchingWorkflow, { alert: "cpu" }, {
+        const { results } = await execute(branchingWorkflow, { alert: "cpu" }, {
             skills: createSkillMap([]),
             claude,
             config: {},
@@ -111,7 +111,7 @@ describe("executor", () => {
             },
             routes: { check: "low" },
         });
-        const results = await execute(branchingWorkflow, { alert: "minor" }, {
+        const { results } = await execute(branchingWorkflow, { alert: "minor" }, {
             skills: createSkillMap([]),
             claude,
             config: {},
@@ -154,7 +154,7 @@ describe("executor", () => {
                 c: { data: {} },
             },
         });
-        const results = await execute(linearWorkflow, {}, {
+        const { results } = await execute(linearWorkflow, {}, {
             skills: createSkillMap([]),
             claude,
             observer: () => {
@@ -193,7 +193,7 @@ describe("executor", () => {
         const claude = new MockClaude({
             responses: { only: { data: { result: "done" } } },
         });
-        const results = await execute(singleNode, {}, {
+        const { results } = await execute(singleNode, {}, {
             skills: createSkillMap([]),
             claude,
             config: {},
@@ -252,7 +252,7 @@ describe("executor", () => {
             claude,
         })).rejects.toThrow("Missing required config");
         // Should succeed with override
-        const results = await execute(linearWorkflow, {}, {
+        const { results } = await execute(linearWorkflow, {}, {
             skills: createSkillMap([skillWithConfig]),
             claude,
             config: { MY_KEY: "provided" },
@@ -267,7 +267,7 @@ describe("executor", () => {
                 c: { data: {} },
             },
         });
-        const results = await execute(linearWorkflow, {}, {
+        const { results } = await execute(linearWorkflow, {}, {
             skills: createSkillMap([]),
             claude,
             config: {},
@@ -316,13 +316,20 @@ describe("executor", () => {
                 return opts.choices[0].id;
             },
         };
-        const results = await execute(retryWorkflow, {}, { skills: createSkillMap([]), claude: mockClaude, config: {} });
+        const { results, trace } = await execute(retryWorkflow, {}, { skills: createSkillMap([]), claude: mockClaude, config: {} });
         // extract ran twice (initial + 1 retry), judge ran twice, done ran once
         expect(extractCount).toBe(2);
         expect(judgeCount).toBe(2);
         expect(results.has("done")).toBe(true);
         // The second extract result overwrites the first
         expect(results.get("extract")?.data.attempt).toBe(2);
+        // Trace captures the full execution path including loops
+        expect(trace.steps).toHaveLength(5); // extract, judge, extract(retry), judge, done
+        expect(trace.steps[0]).toEqual({ node: "extract", status: "success", iteration: 1 });
+        expect(trace.steps[2]).toEqual({ node: "extract", status: "success", iteration: 2 });
+        // Trace edges include the retry loop
+        const retryEdge = trace.edges.find((e) => e.from === "judge" && e.to === "extract");
+        expect(retryEdge).toBeDefined();
     });
     it("respects max_iterations=1 as single retry", async () => {
         const singleRetry = {
@@ -356,7 +363,7 @@ describe("executor", () => {
                 return opts.choices[0].id;
             },
         };
-        const results = await execute(singleRetry, {}, { skills: createSkillMap([]), claude: mockClaude, config: {} });
+        const { results } = await execute(singleRetry, {}, { skills: createSkillMap([]), claude: mockClaude, config: {} });
         // A runs twice (once initially, once via retry), then edge is exhausted → falls to "end"
         expect(aCount).toBe(2);
         expect(results.has("end")).toBe(true);
@@ -371,7 +378,7 @@ describe("executor", () => {
                 return "nonexistent_node"; // invalid target
             },
         };
-        const results = await execute(branchingWorkflow, {}, {
+        const { results } = await execute(branchingWorkflow, {}, {
             skills: createSkillMap([]),
             claude: badRouteClaude,
             config: {},

package/dist/__tests__/integration/e2e-workflow.integration.test.js

@@ -47,7 +47,7 @@ describe.runIf(available.claude)("e2e workflow with real Claude", () => {
             maxTurns: 3,
         });
         const events = [];
-        const results = await execute(analysisWorkflow, {
+        const { results } = await execute(analysisWorkflow, {
             alert: "CPU usage at 98% for 15 minutes on production server web-03",
             service: "api-gateway",
             timestamp: "2025-03-25T08:00:00Z",

package/dist/cli/main.d.ts

@@ -4,6 +4,7 @@ export declare function loadWorkflowFile(filePath: string): Workflow;
 export declare function workflowRunAction(file: string, options: Record<string, unknown> & {
     json?: boolean;
     stream?: boolean;
+    mermaid?: boolean;
 }): Promise<void>;
 export declare function workflowExportAction(name: string): void;
 export declare function workflowValidateAction(file: string, options: {

package/dist/cli/main.js

@@ -16,6 +16,7 @@ import { loadAdditionalContext } from "../templates.js";
 import { validateWorkflow as validateWorkflowSchema } from "../schema.js";
 import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
 import { buildWorkflow, refineWorkflow } from "../workflow-builder.js";
+import { toMermaid, toMermaidBlock } from "../mermaid.js";
 import { DagRenderer } from "./renderer.js";
 import * as readline from "node:readline";
 import { loadDotenv, loadConfigFile, STARTER_CONFIG } from "./config-file.js";
@@ -357,7 +358,7 @@ triageCmd.action(async (options) => {
         contextUrls,
     };
     try {
-        const results = await execute(triageWorkflow, workflowInput, {
+        const { results } = await execute(triageWorkflow, workflowInput, {
             skills,
             claude,
             observer,
@@ -473,7 +474,7 @@ implementCmd.action(async (issueId, options) => {
         contextUrls,
     };
     try {
-        const results = await execute(implementWorkflow, workflowInput, {
+        const { results } = await execute(implementWorkflow, workflowInput, {
             skills,
             claude,
             observer,
@@ -623,7 +624,7 @@ export async function workflowRunAction(file, options) {
         };
     }
     try {
-        const results = await execute(workflow, workflowInput, {
+        const { results, trace } = await execute(workflow, workflowInput, {
             skills,
             claude,
             observer,
@@ -635,6 +636,14 @@ export async function workflowRunAction(file, options) {
             process.exit(hasFailed ? 1 : 0);
             return;
         }
+        // Mermaid diagram with execution state
+        if (options.mermaid) {
+            const state = {};
+            for (const [nodeId, result] of results) {
+                state[nodeId] = result.status === "success" ? "success" : result.status === "failed" ? "failed" : "skipped";
+            }
+            process.stdout.write(toMermaidBlock(workflow, { state, trace, title: workflow.name }) + "\n");
+        }
         const hasFailed = [...results.values()].some((r) => r.status === "failed");
         if (hasFailed) {
             console.error(chalk.red(`  Workflow failed\n`));
@@ -722,8 +731,43 @@ workflowCmd
     .option("--dry-run", "Validate workflow without running")
     .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")
     .option("--input <json>", "JSON string of input data to pass to the workflow")
     .action(workflowRunAction);
+workflowCmd
+    .command("diagram <file>")
+    .description("Render a workflow as a Mermaid diagram")
+    .option("--direction <dir>", "Graph direction: TB (top-bottom) or LR (left-right)", "TB")
+    .option("--title <title>", "Diagram title (defaults to workflow name)")
+    .option("--block", "Wrap in ```mermaid fenced code block (default)", true)
+    .option("--no-block", "Output raw Mermaid without code fence")
+    .action((file, options) => {
+    let workflow;
+    // Support builtin workflow names
+    if (file === "triage") {
+        workflow = triageWorkflow;
+    }
+    else if (file === "implement") {
+        workflow = implementWorkflow;
+    }
+    else if (file === "seed-content") {
+        workflow = seedContentWorkflow;
+    }
+    else {
+        try {
+            workflow = loadWorkflowFile(file);
+        }
+        catch (err) {
+            console.error(chalk.red(`  Error: ${err instanceof Error ? err.message : String(err)}`));
+            process.exit(1);
+            return;
+        }
+    }
+    const direction = (options.direction === "LR" ? "LR" : "TB");
+    const title = options.title ?? workflow.name;
+    const render = options.block !== false ? toMermaidBlock : toMermaid;
+    process.stdout.write(render(workflow, { direction, title }) + "\n");
+});
 workflowCmd
     .command("export <name>")
     .description("Print a built-in workflow as YAML (triage or implement)")

package/dist/executor.d.ts

@@ -12,7 +12,7 @@
  *
  * This replaces ~8k lines of engine + recipe step code.
  */
-import type { Workflow, Skill, Claude, Observer, NodeResult, Logger } from "./types.js";
+import type { Workflow, Skill, Claude, Observer, Logger, ExecutionResult } from "./types.js";
 export interface ExecuteOptions {
     /** Registered skills (id → Skill) */
     skills: Map<string, Skill>;
@@ -28,6 +28,8 @@ export interface ExecuteOptions {
 /**
  * Execute a workflow from entry to completion.
  *
- * Returns a map of node ID → result for every node that ran.
+ * Returns an ExecutionResult with:
+ * - `results`: map of node ID → final result (last execution if retried)
+ * - `trace`: full ordered execution trace including loops and routing decisions
  */
-export declare function execute(workflow: Workflow, input: unknown, options: ExecuteOptions): Promise<Map<string, NodeResult>>;
+export declare function execute(workflow: Workflow, input: unknown, options: ExecuteOptions): Promise<ExecutionResult>;

package/dist/executor.js

@@ -16,7 +16,9 @@ import { consoleLogger } from "./types.js";
 /**
  * Execute a workflow from entry to completion.
  *
- * Returns a map of node ID → result for every node that ran.
+ * Returns an ExecutionResult with:
+ * - `results`: map of node ID → final result (last execution if retried)
+ * - `trace`: full ordered execution trace including loops and routing decisions
  */
 export async function execute(workflow, input, options) {
     const { skills, claude, observer } = options;
@@ -24,6 +26,8 @@ export async function execute(workflow, input, options) {
     const logger = options.logger ?? consoleLogger;
     const results = new Map();
     const edgeCounts = new Map(); // "from→to" → times followed
+    const nodeRunCounts = new Map(); // node → times executed
+    const trace = { steps: [], edges: [] };
     validate(workflow, skills);
     safeObserve(observer, { type: "workflow:start", workflow: workflow.id }, logger);
     let currentId = workflow.entry;
@@ -31,6 +35,8 @@ export async function execute(workflow, input, options) {
         const node = workflow.nodes[currentId];
         if (!node)
             throw new Error(`Unknown node: "${currentId}"`);
+        const iteration = (nodeRunCounts.get(currentId) ?? 0) + 1;
+        nodeRunCounts.set(currentId, iteration);
         safeObserve(observer, { type: "node:enter", node: currentId, instruction: node.instruction }, logger);
         logger.info(`→ ${node.name}`, { node: currentId });
         // Gather tools from the node's skills
@@ -64,6 +70,7 @@ export async function execute(workflow, input, options) {
             },
         });
         results.set(currentId, result);
+        trace.steps.push({ node: currentId, status: result.status, iteration });
         safeObserve(observer, { type: "node:exit", node: currentId, result }, logger);
         logger.info(`  ✓ ${result.status}`, { node: currentId, toolCalls: result.toolCalls.length });
         // Dry run hard gate — stop at the first conditional routing decision.
@@ -80,13 +87,20 @@ export async function execute(workflow, input, options) {
             }
         }
         // Resolve next node via edge conditions
-        currentId = await resolveNext(workflow, currentId, results, input, claude, observer, edgeCounts);
+        const prevId = currentId;
+        currentId = await resolveNext(workflow, currentId, results, input, claude, observer, edgeCounts, logger);
+        // Record the routing decision in the trace
+        if (currentId) {
+            const edgeKey = `${prevId}→${currentId}`;
+            const reason = workflow.edges.find((e) => e.from === prevId && e.to === currentId)?.when ?? "only path";
+            trace.edges.push({ from: prevId, to: currentId, reason });
+        }
     }
     safeObserve(observer, {
         type: "workflow:end",
         results: Object.fromEntries(results),
     }, logger);
-    return results;
+    return { results, trace };
 }
 // ─── Internals ───────────────────────────────────────────────────
 /**
@@ -119,7 +133,12 @@ function buildNodeInstruction(baseInstruction, input) {
         return baseInstruction;
     return `${sections.join("\n\n")}\n\n---\n\n${baseInstruction}`;
 }
-/** Call observer without letting exceptions crash the workflow */
+/**
+ * Call observer without letting exceptions crash the workflow.
+ *
+ * Accepts a typed ExecutionEvent so TypeScript catches mistakes in
+ * event construction at compile time rather than silently at runtime.
+ */
 function safeObserve(observer, event, logger) {
     if (!observer)
         return;
@@ -168,7 +187,7 @@ function resolveConfig(skills, overrides) {
  *
  * Edges with max_iterations are filtered out once exhausted.
  */
-async function resolveNext(workflow, current, results, input, claude, observer, edgeCounts) {
+async function resolveNext(workflow, current, results, input, claude, observer, edgeCounts, logger) {
     // Filter out edges that have exceeded their max_iterations
     const outEdges = workflow.edges.filter((e) => {
         if (e.from !== current)
@@ -189,7 +208,7 @@ async function resolveNext(workflow, current, results, input, claude, observer,
             const key = `${current}→${outEdges[0].to}`;
             edgeCounts.set(key, (edgeCounts.get(key) ?? 0) + 1);
         }
-        safeObserve(observer, { type: "route", from: current, to: outEdges[0].to, reason: "only path" });
+        safeObserve(observer, { type: "route", from: current, to: outEdges[0].to, reason: "only path" }, logger);
         return outEdges[0].to;
     }
     // Check for a default (unconditional) edge among conditionals
@@ -226,7 +245,7 @@ async function resolveNext(workflow, current, results, input, claude, observer,
         from: current,
         to: resolved,
         reason: choices.find((c) => c.id === resolved)?.description ?? "default",
-    });
+    }, logger);
     return resolved;
 }
 /**

package/dist/executor.test.js

@@ -167,7 +167,7 @@ describe("executor", () => {
             },
         });
         const events = [];
-        const results = await execute(simpleWorkflow, { alert: "test" }, {
+        const { results } = await execute(simpleWorkflow, { alert: "test" }, {
             skills,
             claude,
             observer: (e) => events.push(e),
@@ -202,7 +202,7 @@ describe("executor", () => {
                 check: "handle_high", // Route to high severity handler
             },
         });
-        const results = await execute(branchingWorkflow, { alert: "cpu spike" }, {
+        const { results } = await execute(branchingWorkflow, { alert: "cpu spike" }, {
             skills,
             claude,
             config: {},
@@ -224,7 +224,7 @@ describe("executor", () => {
                 check: "handle_low",
             },
         });
-        const results = await execute(branchingWorkflow, { alert: "minor" }, {
+        const { results } = await execute(branchingWorkflow, { alert: "minor" }, {
             skills,
             claude,
             config: {},

package/dist/index.d.ts

@@ -21,7 +21,7 @@
  * })
  * ```
  */
-export type { Skill, SkillCategory, Tool, ToolContext, ConfigField, JSONSchema, Workflow, Node, Edge, NodeResult, ToolCall, ExecutionEvent, Observer, Claude, Logger, } from "./types.js";
+export type { Skill, SkillCategory, Tool, ToolContext, ConfigField, JSONSchema, Workflow, Node, Edge, NodeResult, ToolCall, ExecutionEvent, Observer, Claude, Logger, TraceStep, TraceEdge, ExecutionTrace, ExecutionResult, } from "./types.js";
 export { consoleLogger } from "./types.js";
 export { execute } from "./executor.js";
 export type { ExecuteOptions } from "./executor.js";
@@ -38,5 +38,7 @@ export { buildWorkflow, refineWorkflow } from "./workflow-builder.js";
 export type { BuildWorkflowOptions } from "./workflow-builder.js";
 export { resolveTemplates, loadAdditionalContext, loadTemplate } from "./templates.js";
 export type { Templates } from "./templates.js";
+export { toMermaid, toMermaidBlock } from "./mermaid.js";
+export type { MermaidOptions, NodeStatus } from "./mermaid.js";
 export { loadConfigFile } from "./cli/config-file.js";
 export type { FileConfig } from "./cli/config-file.js";

package/dist/index.js

@@ -36,5 +36,7 @@ export { buildAutoMcpServers, buildProviderContext } from "./mcp.js";
 export { buildWorkflow, refineWorkflow } from "./workflow-builder.js";
 // Templates
 export { resolveTemplates, loadAdditionalContext, loadTemplate } from "./templates.js";
+// Mermaid export
+export { toMermaid, toMermaidBlock } from "./mermaid.js";
 // Config file
 export { loadConfigFile } from "./cli/config-file.js";

package/dist/mermaid.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Mermaid diagram export
+ *
+ * Converts a Workflow into a Mermaid flowchart string.
+ * Renders natively in GitHub (job summaries, READMEs, issues, PRs),
+ * VS Code preview, documentation sites, and anywhere Mermaid is supported.
+ *
+ * Accepts optional execution state to color nodes by status
+ * (current/success/failed/skipped) and optional execution trace
+ * to highlight which edges were taken and show loop iterations.
+ */
+import type { Workflow, ExecutionTrace } from "./types.js";
+export type NodeStatus = "current" | "success" | "failed" | "skipped";
+export interface MermaidOptions {
+    /** Execution state — nodes not in this map render as default (pending) */
+    state?: Record<string, NodeStatus>;
+    /** Execution trace — highlights taken/not-taken edges and loop counts */
+    trace?: ExecutionTrace;
+    /** Graph direction: TB (top-bottom) or LR (left-right). Default: TB */
+    direction?: "TB" | "LR";
+    /** Title rendered above the diagram */
+    title?: string;
+}
+/**
+ * Convert a Workflow to a Mermaid flowchart diagram string.
+ *
+ * @example
+ * ```ts
+ * import { toMermaid } from '@sweny-ai/core';
+ *
+ * const md = toMermaid(workflow, {
+ *   state: { triage: 'success', investigate: 'current' },
+ *   trace: executionResult.trace,
+ * });
+ * // Wrap in ```mermaid fence for GitHub rendering
+ * ```
+ */
+export declare function toMermaid(workflow: Workflow, options?: MermaidOptions): string;
+/**
+ * Convenience: wrap toMermaid output in a fenced code block
+ * ready for GitHub markdown.
+ */
+export declare function toMermaidBlock(workflow: Workflow, options?: MermaidOptions): string;

package/dist/mermaid.js

@@ -0,0 +1,158 @@
+/**
+ * Mermaid diagram export
+ *
+ * Converts a Workflow into a Mermaid flowchart string.
+ * Renders natively in GitHub (job summaries, READMEs, issues, PRs),
+ * VS Code preview, documentation sites, and anywhere Mermaid is supported.
+ *
+ * Accepts optional execution state to color nodes by status
+ * (current/success/failed/skipped) and optional execution trace
+ * to highlight which edges were taken and show loop iterations.
+ */
+/**
+ * Convert a Workflow to a Mermaid flowchart diagram string.
+ *
+ * @example
+ * ```ts
+ * import { toMermaid } from '@sweny-ai/core';
+ *
+ * const md = toMermaid(workflow, {
+ *   state: { triage: 'success', investigate: 'current' },
+ *   trace: executionResult.trace,
+ * });
+ * // Wrap in ```mermaid fence for GitHub rendering
+ * ```
+ */
+export function toMermaid(workflow, options = {}) {
+    const { state = {}, trace, direction = "TB", title } = options;
+    const lines = [];
+    if (title) {
+        lines.push("---");
+        lines.push(`title: ${title}`);
+        lines.push("---");
+    }
+    lines.push(`graph ${direction}`);
+    // Build node iteration counts from trace
+    const nodeIterations = new Map();
+    if (trace) {
+        for (const step of trace.steps) {
+            nodeIterations.set(step.node, Math.max(nodeIterations.get(step.node) ?? 0, step.iteration));
+        }
+    }
+    // Nodes
+    for (const [id, node] of Object.entries(workflow.nodes)) {
+        let label = escapeLabel(node.name);
+        const isEntry = id === workflow.entry;
+        const entryTag = isEntry ? " \\u25B6" : "";
+        // Show iteration count for nodes that ran multiple times
+        const iterations = nodeIterations.get(id);
+        const iterTag = iterations && iterations > 1 ? ` ×${iterations}` : "";
+        if (isEntry) {
+            lines.push(`    ${sanitizeId(id)}([${label}${entryTag}${iterTag}])`);
+        }
+        else {
+            lines.push(`    ${sanitizeId(id)}[${label}${iterTag}]`);
+        }
+    }
+    lines.push("");
+    // Build set of taken edges from trace for lookup
+    const takenEdges = new Set();
+    const edgeTakenCounts = new Map();
+    if (trace) {
+        for (const te of trace.edges) {
+            const key = `${te.from}→${te.to}`;
+            takenEdges.add(key);
+            edgeTakenCounts.set(key, (edgeTakenCounts.get(key) ?? 0) + 1);
+        }
+    }
+    // Edges — track index for linkStyle directives
+    const takenIndices = [];
+    const notTakenIndices = [];
+    let edgeIndex = 0;
+    for (const edge of workflow.edges) {
+        const from = sanitizeId(edge.from);
+        const to = sanitizeId(edge.to);
+        const key = `${edge.from}→${edge.to}`;
+        const taken = takenEdges.has(key);
+        const takenCount = edgeTakenCounts.get(key) ?? 0;
+        // Build label parts
+        const labelParts = [];
+        if (edge.when)
+            labelParts.push(edge.when);
+        if (edge.max_iterations)
+            labelParts.push(`max ${edge.max_iterations}x`);
+        // Show how many times this edge was actually followed
+        if (takenCount > 1)
+            labelParts.push(`taken ${takenCount}x`);
+        if (labelParts.length > 0) {
+            const label = escapeLabel(labelParts.join(" · "));
+            lines.push(`    ${from} -->|"${label}"| ${to}`);
+        }
+        else {
+            lines.push(`    ${from} --> ${to}`);
+        }
+        // Track edge indices for styling
+        if (trace) {
+            if (taken) {
+                takenIndices.push(edgeIndex);
+            }
+            else {
+                notTakenIndices.push(edgeIndex);
+            }
+        }
+        edgeIndex++;
+    }
+    // Node status styling
+    const statusNodes = groupByStatus(state);
+    if (statusNodes.size > 0) {
+        lines.push("");
+        lines.push("    classDef current fill:#3b82f6,stroke:#2563eb,color:#fff,stroke-width:2px");
+        lines.push("    classDef success fill:#22c55e,stroke:#16a34a,color:#fff,stroke-width:2px");
+        lines.push("    classDef failed fill:#ef4444,stroke:#dc2626,color:#fff,stroke-width:2px");
+        lines.push("    classDef skipped fill:#6b7280,stroke:#4b5563,color:#fff,stroke-dasharray:5 5");
+        for (const [status, ids] of statusNodes) {
+            const sanitized = ids.map(sanitizeId).join(",");
+            lines.push(`    class ${sanitized} ${status}`);
+        }
+    }
+    // Edge styling — taken edges bold green, not-taken edges dashed gray
+    if (trace) {
+        lines.push("");
+        if (takenIndices.length > 0) {
+            lines.push(`    linkStyle ${takenIndices.join(",")} stroke:#22c55e,stroke-width:3px`);
+        }
+        if (notTakenIndices.length > 0) {
+            lines.push(`    linkStyle ${notTakenIndices.join(",")} stroke:#6b7280,stroke-width:1px,stroke-dasharray:5 5`);
+        }
+    }
+    return lines.join("\n");
+}
+/**
+ * Convenience: wrap toMermaid output in a fenced code block
+ * ready for GitHub markdown.
+ */
+export function toMermaidBlock(workflow, options = {}) {
+    return "```mermaid\n" + toMermaid(workflow, options) + "\n```";
+}
+// ─── Helpers ───────────────────────────────────────────────────────
+/** Mermaid node IDs must be alphanumeric + underscores + hyphens */
+function sanitizeId(id) {
+    return id.replace(/[^a-zA-Z0-9_-]/g, "_");
+}
+/** Escape characters that break Mermaid labels */
+function escapeLabel(text) {
+    return text.replace(/"/g, """).replace(/\[/g, "[").replace(/\]/g, "]");
+}
+/** Group node IDs by their status */
+function groupByStatus(state) {
+    const groups = new Map();
+    for (const [id, status] of Object.entries(state)) {
+        let list = groups.get(status);
+        if (!list) {
+            list = [];
+            groups.set(status, list);
+        }
+        list.push(id);
+    }
+    return groups;
+}

package/dist/mermaid.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/mermaid.test.js

@@ -0,0 +1,254 @@
+import { describe, it, expect } from "vitest";
+import { toMermaid, toMermaidBlock } from "./mermaid.js";
+import { triageWorkflow, implementWorkflow } from "./workflows/index.js";
+// ─── Fixtures ──────────────────────────────────────────────────────
+const simple = {
+    id: "simple",
+    name: "Simple",
+    description: "A→B→C",
+    entry: "a",
+    nodes: {
+        a: { name: "Triage", instruction: "Triage the alert", skills: ["github"] },
+        b: { name: "Investigate", instruction: "Investigate the issue", skills: ["sentry"] },
+        c: { name: "Report", instruction: "Write report", skills: ["slack"] },
+    },
+    edges: [
+        { from: "a", to: "b" },
+        { from: "b", to: "c" },
+    ],
+};
+const branching = {
+    id: "branching",
+    name: "Branching",
+    description: "Conditional routing",
+    entry: "triage",
+    nodes: {
+        triage: { name: "Triage", instruction: "Classify severity", skills: [] },
+        investigate: { name: "Investigate", instruction: "Deep dive", skills: [] },
+        notify: { name: "Notify", instruction: "Send alert", skills: [] },
+        close: { name: "Close", instruction: "Close ticket", skills: [] },
+    },
+    edges: [
+        { from: "triage", to: "investigate", when: "severity is high or critical" },
+        { from: "triage", to: "notify", when: "severity is low" },
+        { from: "investigate", to: "close" },
+        { from: "notify", to: "close" },
+    ],
+};
+const withLoop = {
+    id: "loop",
+    name: "Loop",
+    description: "Retry loop",
+    entry: "a",
+    nodes: {
+        a: { name: "Try", instruction: "Attempt fix", skills: [] },
+        b: { name: "Done", instruction: "Wrap up", skills: [] },
+    },
+    edges: [
+        { from: "a", to: "a", when: "needs retry", max_iterations: 3 },
+        { from: "a", to: "b" },
+    ],
+};
+// ─── Tests ─────────────────────────────────────────────────────────
+describe("toMermaid", () => {
+    it("renders a simple linear workflow", () => {
+        const result = toMermaid(simple);
+        expect(result).toContain("graph TB");
+        // Entry node gets stadium shape
+        expect(result).toContain("a([Triage \\u25B6])");
+        // Non-entry nodes get default shape
+        expect(result).toContain("b[Investigate]");
+        expect(result).toContain("c[Report]");
+        // Edges
+        expect(result).toContain("a --> b");
+        expect(result).toContain("b --> c");
+    });
+    it("renders conditional edges with labels", () => {
+        const result = toMermaid(branching);
+        expect(result).toContain('triage -->|"severity is high or critical"| investigate');
+        expect(result).toContain('triage -->|"severity is low"| notify');
+        expect(result).toContain("investigate --> close");
+        expect(result).toContain("notify --> close");
+    });
+    it("renders max_iterations on edges", () => {
+        const result = toMermaid(withLoop);
+        expect(result).toContain('a -->|"needs retry · max 3x"| a');
+        expect(result).toContain("a --> b");
+    });
+    it("renders max_iterations without condition", () => {
+        const wf = {
+            ...simple,
+            edges: [
+                { from: "a", to: "b", max_iterations: 5 },
+                { from: "b", to: "c" },
+            ],
+        };
+        const result = toMermaid(wf);
+        expect(result).toContain('a -->|"max 5x"| b');
+    });
+    it("applies execution state styling", () => {
+        const result = toMermaid(simple, {
+            state: {
+                a: "success",
+                b: "current",
+            },
+        });
+        expect(result).toContain("classDef current fill:#3b82f6");
+        expect(result).toContain("classDef success fill:#22c55e");
+        expect(result).toContain("class a success");
+        expect(result).toContain("class b current");
+        // c has no state — no class applied
+        expect(result).not.toContain("class c");
+    });
+    it("applies failed and skipped styling", () => {
+        const result = toMermaid(simple, {
+            state: {
+                a: "success",
+                b: "failed",
+                c: "skipped",
+            },
+        });
+        expect(result).toContain("classDef failed fill:#ef4444");
+        expect(result).toContain("classDef skipped fill:#6b7280");
+        expect(result).toContain("class b failed");
+        expect(result).toContain("class c skipped");
+    });
+    it("omits style block when no state provided", () => {
+        const result = toMermaid(simple);
+        expect(result).not.toContain("classDef");
+        expect(result).not.toContain("class ");
+    });
+    it("supports LR direction", () => {
+        const result = toMermaid(simple, { direction: "LR" });
+        expect(result).toContain("graph LR");
+    });
+    it("supports title", () => {
+        const result = toMermaid(simple, { title: "My Workflow" });
+        expect(result).toContain("---");
+        expect(result).toContain("title: My Workflow");
+    });
+    it("sanitizes node IDs with special characters", () => {
+        const wf = {
+            id: "special",
+            name: "Special",
+            description: "",
+            entry: "step.one",
+            nodes: {
+                "step.one": { name: "Step One", instruction: "Do it", skills: [] },
+                "step two": { name: "Step Two", instruction: "Do it", skills: [] },
+            },
+            edges: [{ from: "step.one", to: "step two" }],
+        };
+        const result = toMermaid(wf);
+        expect(result).toContain("step_one");
+        expect(result).toContain("step_two");
+        expect(result).not.toContain("step.one");
+        expect(result).not.toContain("step two");
+    });
+    it("escapes special characters in labels", () => {
+        const wf = {
+            id: "escape",
+            name: "Escape",
+            description: "",
+            entry: "a",
+            nodes: {
+                a: { name: 'Say "hello"', instruction: "x", skills: [] },
+                b: { name: "Done", instruction: "x", skills: [] },
+            },
+            edges: [{ from: "a", to: "b" }],
+        };
+        const result = toMermaid(wf);
+        expect(result).toContain(""");
+        expect(result).not.toContain('Say "hello"');
+    });
+    it("groups multiple nodes with same status", () => {
+        const result = toMermaid(simple, {
+            state: { a: "success", b: "success", c: "current" },
+        });
+        expect(result).toContain("class a,b success");
+        expect(result).toContain("class c current");
+    });
+    it("highlights taken edges and dims not-taken edges with trace", () => {
+        const trace = {
+            steps: [
+                { node: "triage", status: "success", iteration: 1 },
+                { node: "investigate", status: "success", iteration: 1 },
+                { node: "close", status: "success", iteration: 1 },
+            ],
+            edges: [
+                { from: "triage", to: "investigate", reason: "severity is high or critical" },
+                { from: "investigate", to: "close", reason: "only path" },
+            ],
+        };
+        const result = toMermaid(branching, { trace });
+        // Taken edges get green bold styling (edges 0 and 2 in the workflow)
+        expect(result).toContain("linkStyle");
+        expect(result).toContain("stroke:#22c55e,stroke-width:3px");
+        // Not-taken edges get dashed gray
+        expect(result).toContain("stroke:#6b7280,stroke-width:1px,stroke-dasharray:5 5");
+    });
+    it("shows iteration count on nodes and edges from trace", () => {
+        const trace = {
+            steps: [
+                { node: "a", status: "success", iteration: 1 },
+                { node: "a", status: "success", iteration: 2 },
+                { node: "b", status: "success", iteration: 1 },
+            ],
+            edges: [
+                { from: "a", to: "a", reason: "needs retry" },
+                { from: "a", to: "b", reason: "only path" },
+            ],
+        };
+        const result = toMermaid(withLoop, { trace });
+        // Node a ran twice — should show ×2
+        expect(result).toContain("×2");
+        // Node b ran once — no iteration tag
+        expect(result).not.toContain("Done ×");
+    });
+});
+describe("builtin workflows", () => {
+    it("renders triage workflow", () => {
+        const result = toMermaid(triageWorkflow);
+        expect(result).toContain("graph TB");
+        // Every node should appear
+        for (const [id, node] of Object.entries(triageWorkflow.nodes)) {
+            expect(result).toContain(node.name);
+        }
+        // Every edge should appear
+        for (const edge of triageWorkflow.edges) {
+            expect(result).toContain(edge.from);
+            expect(result).toContain(edge.to);
+        }
+    });
+    it("renders implement workflow", () => {
+        const result = toMermaid(implementWorkflow);
+        expect(result).toContain("graph TB");
+        for (const node of Object.values(implementWorkflow.nodes)) {
+            expect(result).toContain(node.name);
+        }
+    });
+    it("renders triage with execution state", () => {
+        const ids = Object.keys(triageWorkflow.nodes);
+        const state = {};
+        state[ids[0]] = "success";
+        if (ids[1])
+            state[ids[1]] = "current";
+        const result = toMermaid(triageWorkflow, { state, title: triageWorkflow.name });
+        expect(result).toContain("classDef success");
+        expect(result).toContain("classDef current");
+        expect(result).toContain(`class ${ids[0]} success`);
+    });
+});
+describe("toMermaidBlock", () => {
+    it("wraps in fenced code block", () => {
+        const result = toMermaidBlock(simple);
+        expect(result).toMatch(/^```mermaid\n/);
+        expect(result).toMatch(/\n```$/);
+        expect(result).toContain("graph TB");
+    });
+    it("passes options through", () => {
+        const result = toMermaidBlock(simple, { direction: "LR", state: { a: "success" } });
+        expect(result).toContain("graph LR");
+        expect(result).toContain("class a success");
+    });
+});

package/dist/schema.d.ts

@@ -109,12 +109,12 @@ export declare const nodeZ: z.ZodObject<{
     output: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
 }, "strip", z.ZodTypeAny, {
     skills: string[];
-    name: string;
     instruction: string;
+    name: string;
     output?: Record<string, unknown> | undefined;
 }, {
-    name: string;
     instruction: string;
+    name: string;
     skills?: string[] | undefined;
     output?: Record<string, unknown> | undefined;
 }>;
@@ -124,13 +124,13 @@ export declare const edgeZ: z.ZodObject<{
     when: z.ZodOptional<z.ZodString>;
     max_iterations: z.ZodOptional<z.ZodNumber>;
 }, "strip", z.ZodTypeAny, {
-    from: string;
     to: string;
+    from: string;
     when?: string | undefined;
     max_iterations?: number | undefined;
 }, {
-    from: string;
     to: string;
+    from: string;
     when?: string | undefined;
     max_iterations?: number | undefined;
 }>;
@@ -145,12 +145,12 @@ export declare const workflowZ: z.ZodObject<{
         output: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     }, "strip", z.ZodTypeAny, {
         skills: string[];
-        name: string;
         instruction: string;
+        name: string;
         output?: Record<string, unknown> | undefined;
     }, {
-        name: string;
         instruction: string;
+        name: string;
         skills?: string[] | undefined;
         output?: Record<string, unknown> | undefined;
     }>>;
@@ -160,13 +160,13 @@ export declare const workflowZ: z.ZodObject<{
         when: z.ZodOptional<z.ZodString>;
         max_iterations: z.ZodOptional<z.ZodNumber>;
     }, "strip", z.ZodTypeAny, {
-        from: string;
         to: string;
+        from: string;
         when?: string | undefined;
         max_iterations?: number | undefined;
     }, {
-        from: string;
         to: string;
+        from: string;
         when?: string | undefined;
         max_iterations?: number | undefined;
     }>, "many">;
@@ -177,13 +177,13 @@ export declare const workflowZ: z.ZodObject<{
     description: string;
     nodes: Record<string, {
         skills: string[];
-        name: string;
         instruction: string;
+        name: string;
         output?: Record<string, unknown> | undefined;
     }>;
     edges: {
-        from: string;
         to: string;
+        from: string;
         when?: string | undefined;
         max_iterations?: number | undefined;
     }[];
@@ -192,14 +192,14 @@ export declare const workflowZ: z.ZodObject<{
     id: string;
     name: string;
     nodes: Record<string, {
-        name: string;
         instruction: string;
+        name: string;
         skills?: string[] | undefined;
         output?: Record<string, unknown> | undefined;
     }>;
     edges: {
-        from: string;
         to: string;
+        from: string;
         when?: string | undefined;
         max_iterations?: number | undefined;
     }[];
@@ -213,20 +213,20 @@ export declare function parseWorkflow(raw: unknown): {
     description: string;
     nodes: Record<string, {
         skills: string[];
-        name: string;
         instruction: string;
+        name: string;
         output?: Record<string, unknown> | undefined;
     }>;
     edges: {
-        from: string;
         to: string;
+        from: string;
         when?: string | undefined;
         max_iterations?: number | undefined;
     }[];
     entry: string;
 };
 export interface WorkflowError {
-    code: "MISSING_ENTRY" | "UNKNOWN_EDGE_SOURCE" | "UNKNOWN_EDGE_TARGET" | "UNREACHABLE_NODE" | "UNKNOWN_SKILL" | "SELF_LOOP" | "UNBOUNDED_CYCLE" | "NO_OUTGOING_EDGE";
+    code: "MISSING_ENTRY" | "UNKNOWN_EDGE_SOURCE" | "UNKNOWN_EDGE_TARGET" | "UNREACHABLE_NODE" | "UNKNOWN_SKILL" | "SELF_LOOP" | "UNBOUNDED_CYCLE";
     message: string;
     nodeId?: string;
 }
@@ -238,8 +238,11 @@ export interface WorkflowError {
  * - All edge sources and targets reference existing nodes
  * - No self-loops
  * - All nodes are reachable from entry
- * - All non-terminal nodes have at least one outgoing edge
+ * - Unbounded cycles (cycles with no max_iterations guard)
  * - (optional) All referenced skills exist in the provided skill set
+ *
+ * Note: nodes with no outgoing edges are valid terminal nodes — the executor
+ * returns null when it reaches one, ending the workflow cleanly.
  */
 export declare function validateWorkflow(workflow: z.infer<typeof workflowZ>, knownSkills?: Set<string>): WorkflowError[];
 /**

package/dist/schema.js

@@ -65,8 +65,11 @@ export function parseWorkflow(raw) {
  * - All edge sources and targets reference existing nodes
  * - No self-loops
  * - All nodes are reachable from entry
- * - All non-terminal nodes have at least one outgoing edge
+ * - Unbounded cycles (cycles with no max_iterations guard)
  * - (optional) All referenced skills exist in the provided skill set
+ *
+ * Note: nodes with no outgoing edges are valid terminal nodes — the executor
+ * returns null when it reaches one, ending the workflow cleanly.
  */
 export function validateWorkflow(workflow, knownSkills) {
     const errors = [];

package/dist/skills/github.js

@@ -123,15 +123,29 @@ export const github = {
                 },
                 required: ["repo", "title", "head"],
             },
-            handler: async (input, ctx) => gh(`/repos/${input.repo}/pulls`, ctx, {
-                method: "POST",
-                body: JSON.stringify({
-                    title: input.title,
-                    body: input.body,
-                    head: input.head,
-                    base: input.base ?? "main",
-                }),
-            }),
+            handler: async (input, ctx) => {
+                const pr = (await gh(`/repos/${input.repo}/pulls`, ctx, {
+                    method: "POST",
+                    body: JSON.stringify({
+                        title: input.title,
+                        body: input.body,
+                        head: input.head,
+                        base: input.base ?? "main",
+                    }),
+                }));
+                try {
+                    if (pr.number) {
+                        await gh(`/repos/${input.repo}/issues/${pr.number}/labels`, ctx, {
+                            method: "POST",
+                            body: JSON.stringify({ labels: ["sweny"] }),
+                        });
+                    }
+                }
+                catch {
+                    // Label failure is non-fatal
+                }
+                return pr;
+            },
         },
         {
             name: "github_list_recent_commits",

package/dist/types.d.ts

@@ -107,6 +107,36 @@ export type ExecutionEvent = {
     results: Record<string, NodeResult>;
 };
 export type Observer = (event: ExecutionEvent) => void;
+/** A single node execution within the trace */
+export interface TraceStep {
+    /** Node ID */
+    node: string;
+    /** Outcome of this execution */
+    status: "success" | "failed" | "skipped";
+    /** 1-based iteration count (2 = second time this node ran) */
+    iteration: number;
+}
+/** A routing decision between nodes */
+export interface TraceEdge {
+    from: string;
+    to: string;
+    /** Why this edge was chosen (condition text or "only path") */
+    reason: string;
+}
+/** Full execution trace — ordered steps + edges taken */
+export interface ExecutionTrace {
+    /** Ordered list of node executions (includes repeats from retry loops) */
+    steps: TraceStep[];
+    /** Ordered list of routing decisions */
+    edges: TraceEdge[];
+}
+/** Result of execute() — final node results + full execution trace */
+export interface ExecutionResult {
+    /** Final result per node (last execution if retried) */
+    results: Map<string, NodeResult>;
+    /** Full execution trace including loops and routing decisions */
+    trace: ExecutionTrace;
+}
 export interface Claude {
     /** Run a node: give Claude an instruction, context, and tools */
     run(opts: {

package/dist/workflows/browser.js

@@ -1,3 +1,3 @@
-export const triageWorkflow = {"id":"triage","name":"Alert Triage","description":"Investigate a production alert, determine root cause, create an issue, implement a fix, and notify the team","entry":"prepare","nodes":{"prepare":{"name":"Load Rules & Context","instruction":"You are preparing for a triage workflow. Your job is to fetch and review any knowledge documents listed in the input.\n\n1. Check input for `rulesUrls`, `contextUrls`, `rules_urls`, and `context_urls` arrays (any of these may be present).\n2. For each URL, fetch its content:\n   - Linear document URLs → use the Linear MCP tools (get_document or search_documentation)\n   - Other HTTP URLs → fetch directly\n3. Summarize the key rules and context that downstream workflow nodes should follow.\n4. Output the consolidated information so it's available to all subsequent steps.\n\nIf there are no URLs to fetch, just pass through — this step is a no-op.","skills":["linear"]},"gather":{"name":"Gather Context","instruction":"You are investigating a production alert. Gather all relevant context using the available tools:\n\n1. **Observability**: Pull error details, stack traces, recent logs, metrics, and active incidents around the time of the alert. Use whichever observability tools are available to you.\n2. **Source control**: Check recent commits, pull requests, and deploys that might be related.\n3. **Issue tracker**: Search for similar past issues or known problems.\n\nBe thorough — the investigation step depends on complete context. Use every tool available to you.","skills":["github","sentry","datadog","betterstack","linear"]},"investigate":{"name":"Root Cause Analysis","instruction":"Based on the gathered context, classify every distinct issue you found into one of two buckets: **novel** or **duplicate**.\n\nFor EACH issue found:\n1. Identify the root cause and affected code/service.\n2. Assess severity: critical (service down), high (major feature broken), medium (degraded), low (cosmetic/minor).\n3. Assess fix complexity: \"simple\" (a few lines, clear change), \"moderate\" (multiple files but well-understood), or \"complex\" (architectural, risky, or unclear).\n4. **Novelty check (REQUIRED):** Search the issue tracker for existing issues (BOTH open AND closed) that cover the same root cause, error pattern, or affected service. Use github_search_issues and/or linear_search_issues with multiple keyword variations.\n   - A match = same root cause, same error message/pattern, or a human would call it \"the same bug.\"\n   - If matched → it's a **duplicate**. Record the existing issue ID.\n   - If no match → it's **novel**.\n\n**Output rules:**\n- `findings`: array of ALL issues found (both novel and duplicate).\n- `novel_count`: how many findings are novel (not duplicates).\n- `highest_severity`: the highest severity across ALL findings.\n- `recommendation`: what should happen next.\n\nDownstream nodes will act ONLY on novel findings. Duplicates will be +1'd automatically.","skills":["github","linear"],"output":{"type":"object","properties":{"findings":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string","description":"Short description of the issue"},"root_cause":{"type":"string"},"severity":{"type":"string","enum":["critical","high","medium","low"]},"affected_services":{"type":"array","items":{"type":"string"}},"is_duplicate":{"type":"boolean"},"duplicate_of":{"type":"string","description":"Existing issue ID/URL if duplicate"},"fix_approach":{"type":"string"},"fix_complexity":{"type":"string","enum":["simple","moderate","complex"]}},"required":["title","root_cause","severity","is_duplicate"]}},"novel_count":{"type":"number","description":"Count of novel (non-duplicate) findings"},"highest_severity":{"type":"string","enum":["critical","high","medium","low"]},"recommendation":{"type":"string"}},"required":["findings","novel_count","highest_severity","recommendation"]}},"create_issue":{"name":"Create Issues & Triage Duplicates","instruction":"Process ALL findings from the investigation. The findings array contains both novel and duplicate issues.\n\n**For each NOVEL finding** (is_duplicate = false):\n1. Create a new issue with a clear, actionable title.\n2. Include: root cause, severity, affected services, reproduction steps, and recommended fix.\n3. Add appropriate labels (bug, severity level, affected service).\n4. Link to relevant commits, PRs, or existing issues.\n\n**For each DUPLICATE finding** (is_duplicate = true):\n1. Find the existing issue (check duplicate_of field).\n2. Check the issue's comments — if the most recent comment is already from SWEny (contains \"+1\") within the last 24 hours, skip adding another comment.\n3. Otherwise add a SHORT comment: \"+1 — seen again {UTC timestamp}. {one sentence of new context}.\" (Keep it under 2 lines. No markdown headers, no emoji, no formatting.)\n4. If the existing issue is closed/done, reopen it.\n\nIf context.issueTemplate is provided, use it as the format for new issue bodies. Otherwise use a clear structure with: Summary, Root Cause, Impact, Steps to Reproduce, and Recommended Fix.\n\nUse the issue tracker specified in context (e.g. Linear, Jira, or GitHub Issues) — do NOT fall back to a different tracker. Output the created/updated issue identifiers.","skills":["linear","github"]},"skip":{"name":"Skip — All Duplicates or Low Priority","instruction":"Every finding from the investigation was either a duplicate or low-priority. No new issues need to be created.\n\nFor each **duplicate** finding (check the findings array for items where is_duplicate = true):\n1. Find the existing issue (check duplicate_of field).\n2. Check the issue's comments — if the most recent comment is already from SWEny (contains \"+1\") within the last 24 hours, skip adding another comment.\n3. Otherwise add a SHORT comment: \"+1 — seen again {UTC timestamp}. {one sentence of new context}.\" (Keep it under 2 lines. No markdown headers, no emoji, no formatting.)\n4. If the issue is closed/done, reopen it.\n\nFor **low priority** findings, log a brief note about why they were skipped.","skills":["linear","github"]},"implement":{"name":"Implement Fix","instruction":"Implement the fix identified during investigation:\n\n1. Create a feature branch from the base branch (check context for baseBranch, default \"main\").\n2. Read the relevant source files to understand the current code.\n3. Make the necessary code changes — fix the bug, nothing more.\n4. Run any existing tests if available to verify the fix doesn't break anything.\n5. Stage and commit with a clear commit message referencing the issue.\n\nKeep changes minimal and focused. Do not refactor surrounding code or add unrelated improvements.\n\nIf the fix turns out to be more complex than expected, stop and explain why — do not force a bad fix.","skills":["github"]},"create_pr":{"name":"Open Pull Request","instruction":"Open a pull request for the fix:\n\n1. Push the branch to the remote.\n2. Create a PR with a clear title referencing the issue (e.g. \"[OFF-1020] fix: guard empty pdf_texts before access\").\n3. In the PR body, include: summary of the bug, what the fix does, and a link to the issue.\n4. Add appropriate labels if available.\n\nIf context.prTemplate is provided, use it as the format for the PR body. Otherwise use a clear structure with: Summary, Changes, Testing, and Related Issues.\n\nReturn the PR URL and number.","skills":["github"]},"notify":{"name":"Notify Team","instruction":"Send a notification summarizing the triage result:\n\n1. Include: alert summary, severity, root cause (1-2 sentences), and links to any created issues or PRs.\n2. For critical/high severity, make the notification urgent.\n3. For medium/low, a standard notification is fine.\n\nUse whichever notification channel is available to you.","skills":["slack","notification"]}},"edges":[{"from":"prepare","to":"gather"},{"from":"gather","to":"investigate"},{"from":"investigate","to":"create_issue","when":"novel_count is greater than 0 AND highest_severity is medium or higher"},{"from":"investigate","to":"skip","when":"novel_count is 0, OR highest_severity is low"},{"from":"create_issue","to":"implement","when":"at least one novel finding has fix_complexity simple or moderate AND fix_approach is provided"},{"from":"create_issue","to":"notify","when":"all novel findings have fix_complexity complex, OR no clear fix_approach"},{"from":"skip","to":"notify"},{"from":"implement","to":"create_pr"},{"from":"create_pr","to":"notify"}]};
-export const implementWorkflow = {"id":"implement","name":"Implement Fix","description":"Implement a code fix for an issue and open a pull request","entry":"analyze","nodes":{"analyze":{"name":"Analyze Issue","instruction":"Read the issue details and understand what needs to be fixed:\n\n1. Fetch the issue from the tracker (GitHub or Linear).\n2. Read the relevant source files to understand the current code.\n3. Identify the exact files and lines that need to change.\n4. Plan the fix approach.\n\nOutput a clear analysis of what needs to change and why.","skills":["github","linear"],"output":{"type":"object","properties":{"issue_summary":{"type":"string"},"files_to_change":{"type":"array","items":{"type":"string"}},"fix_plan":{"type":"string"},"risk_level":{"type":"string","enum":["low","medium","high"]}},"required":["issue_summary","fix_plan"]}},"implement":{"name":"Implement Fix","instruction":"Implement the planned fix:\n\n1. Create a feature branch.\n2. Make the necessary code changes.\n3. Ensure changes are minimal and focused — fix the bug, nothing more.\n4. Stage and commit with a clear commit message referencing the issue.\n\nIf the fix is too risky or complex, explain why and skip.","skills":["github"]},"create_pr":{"name":"Open Pull Request","instruction":"Open a pull request for the fix:\n\n1. Push the branch to the remote.\n2. Create a PR with a clear title and description.\n3. Reference the original issue in the PR body.\n4. Add appropriate reviewers or labels if possible.\n\nIf context.prTemplate is provided, use it as the format for the PR body. Otherwise use a clear structure with: Summary, Changes, Testing, and Related Issues.\n\nReturn the PR URL.","skills":["github"]},"notify":{"name":"Notify","instruction":"Send a notification about the implementation result:\n\n1. Include: issue reference, PR link, brief summary of changes.\n2. Keep it concise — one message, not a wall of text.","skills":["slack","notification"]},"skip":{"name":"Skip — Too Complex","instruction":"The fix was determined to be too complex or risky for automated implementation.\nAdd a comment to the issue explaining what was found and why it needs manual attention.","skills":["github","linear"]}},"edges":[{"from":"analyze","to":"implement","when":"Fix risk level is low or medium and a clear plan exists"},{"from":"analyze","to":"skip","when":"Fix is too complex, risky, or unclear"},{"from":"implement","to":"create_pr"},{"from":"skip","to":"notify"},{"from":"create_pr","to":"notify"}]};
+export const triageWorkflow = {"id":"triage","name":"Alert Triage","description":"Investigate a production alert, determine root cause, create an issue, implement a fix, and notify the team","entry":"prepare","nodes":{"prepare":{"name":"Load Rules & Context","instruction":"You are preparing for a triage workflow. Your job is to fetch and review any knowledge documents listed in the input.\n\n1. Check input for `rulesUrls`, `contextUrls`, `rules_urls`, and `context_urls` arrays (any of these may be present).\n2. For each URL, fetch its content:\n   - Linear document URLs → use the Linear MCP tools (get_document or search_documentation)\n   - Other HTTP URLs → fetch directly\n3. Summarize the key rules and context that downstream workflow nodes should follow.\n4. Output the consolidated information so it's available to all subsequent steps.\n\nIf there are no URLs to fetch, just pass through — this step is a no-op.","skills":["linear"]},"gather":{"name":"Gather Context","instruction":"You are investigating a production alert. Gather all relevant context using the available tools:\n\n1. **Observability**: Pull error details, stack traces, recent logs, metrics, and active incidents around the time of the alert. Use whichever observability tools are available to you.\n2. **Source control**: Check recent commits, pull requests, and deploys that might be related.\n3. **Issue tracker**: Search for similar past issues or known problems.\n\nBe thorough — the investigation step depends on complete context. Use every tool available to you.","skills":["github","sentry","datadog","betterstack","linear"]},"investigate":{"name":"Root Cause Analysis","instruction":"Based on the gathered context, classify every distinct issue you found into one of two buckets: **novel** or **duplicate**.\n\nFor EACH issue found:\n1. Identify the root cause and affected code/service.\n2. Assess severity: critical (service down), high (major feature broken), medium (degraded), low (cosmetic/minor).\n3. Assess fix complexity: \"simple\" (a few lines, clear change), \"moderate\" (multiple files but well-understood), or \"complex\" (architectural, risky, or unclear).\n4. **Novelty check (REQUIRED):** Search the issue tracker for existing issues (BOTH open AND closed) that cover the same root cause, error pattern, or affected service. Use github_search_issues and/or linear_search_issues with multiple keyword variations.\n   - A match = same root cause, same error message/pattern, or a human would call it \"the same bug.\"\n   - If matched → it's a **duplicate**. Record the existing issue ID.\n   - If no match → it's **novel**.\n\n**Output rules:**\n- `findings`: array of ALL issues found (both novel and duplicate).\n- `novel_count`: how many findings are novel (not duplicates).\n- `highest_severity`: the highest severity across ALL findings.\n- `recommendation`: what should happen next.\n\nDownstream nodes will act ONLY on novel findings. Duplicates will be +1'd automatically.","skills":["github","linear"],"output":{"type":"object","properties":{"findings":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string","description":"Short description of the issue"},"root_cause":{"type":"string"},"severity":{"type":"string","enum":["critical","high","medium","low"]},"affected_services":{"type":"array","items":{"type":"string"}},"is_duplicate":{"type":"boolean"},"duplicate_of":{"type":"string","description":"Existing issue ID/URL if duplicate"},"fix_approach":{"type":"string"},"fix_complexity":{"type":"string","enum":["simple","moderate","complex"]}},"required":["title","root_cause","severity","is_duplicate"]}},"novel_count":{"type":"number","description":"Count of novel (non-duplicate) findings"},"highest_severity":{"type":"string","enum":["critical","high","medium","low"]},"recommendation":{"type":"string"}},"required":["findings","novel_count","highest_severity","recommendation"]}},"create_issue":{"name":"Create Issues & Triage Duplicates","instruction":"Process ALL findings from the investigation. The findings array contains both novel and duplicate issues.\n\n**For each NOVEL finding** (is_duplicate = false):\n1. Create a new issue with a clear, actionable title.\n2. Include: root cause, severity, affected services, reproduction steps, and recommended fix.\n3. Add appropriate labels (bug, severity level, affected service).\n4. Link to relevant commits, PRs, or existing issues.\n\n**For each DUPLICATE finding** (is_duplicate = true):\n1. Find the existing issue (check duplicate_of field).\n2. Check the issue's comments — if the most recent comment is already from SWEny (contains \"+1\") within the last 24 hours, skip adding another comment.\n3. Otherwise add a SHORT comment: \"+1 — seen again {UTC timestamp}. {one sentence of new context}.\" (Keep it under 2 lines. No markdown headers, no emoji, no formatting.)\n4. If the existing issue is closed/done, reopen it.\n\nIf context.issueTemplate is provided, use it as the format for new issue bodies. Otherwise use a clear structure with: Summary, Root Cause, Impact, Steps to Reproduce, and Recommended Fix.\n\nUse the issue tracker specified in context (e.g. Linear, Jira, or GitHub Issues) — do NOT fall back to a different tracker. Output the created/updated issue identifiers.","skills":["linear","github"]},"skip":{"name":"Skip — All Duplicates or Low Priority","instruction":"Every finding from the investigation was either a duplicate or low-priority. No new issues need to be created.\n\nFor each **duplicate** finding (check the findings array for items where is_duplicate = true):\n1. Find the existing issue (check duplicate_of field).\n2. Check the issue's comments — if the most recent comment is already from SWEny (contains \"+1\") within the last 24 hours, skip adding another comment.\n3. Otherwise add a SHORT comment: \"+1 — seen again {UTC timestamp}. {one sentence of new context}.\" (Keep it under 2 lines. No markdown headers, no emoji, no formatting.)\n4. If the issue is closed/done, reopen it.\n\nFor **low priority** findings, log a brief note about why they were skipped.","skills":["linear","github"]},"implement":{"name":"Implement Fix","instruction":"Implement the fix identified during investigation:\n\n1. Create a feature branch from the base branch (check context for baseBranch, default \"main\").\n2. Read the relevant source files to understand the current code.\n3. Make the necessary code changes — fix the bug, nothing more.\n4. Run any existing tests if available to verify the fix doesn't break anything.\n5. Stage and commit with a clear commit message referencing the issue.\n\nKeep changes minimal and focused. Do not refactor surrounding code or add unrelated improvements.\n\nIf the fix turns out to be more complex than expected, stop and explain why — do not force a bad fix.","skills":["github"]},"create_pr":{"name":"Open Pull Request","instruction":"Open a pull request for the fix:\n\n1. Push the branch to the remote.\n2. Create a PR with a clear title referencing the issue (e.g. \"[OFF-1020] fix: guard empty pdf_texts before access\").\n3. In the PR body, include: summary of the bug, what the fix does, and a link to the issue.\n4. Add appropriate labels if available.\n\nIf context.prTemplate is provided, use it as the format for the PR body. Otherwise use a clear structure with: Summary, Changes, Testing, and Related Issues.\n\nIf context.cloudRunId is provided, append this HTML comment to the end of the PR body: <!-- sweny:run_id:{context.cloudRunId} -->\n\nReturn the PR URL and number.","skills":["github"]},"notify":{"name":"Notify Team","instruction":"Send a notification summarizing the triage result:\n\n1. Include: alert summary, severity, root cause (1-2 sentences), and links to any created issues or PRs.\n2. For critical/high severity, make the notification urgent.\n3. For medium/low, a standard notification is fine.\n\nUse whichever notification channel is available to you.","skills":["slack","notification"]}},"edges":[{"from":"prepare","to":"gather"},{"from":"gather","to":"investigate"},{"from":"investigate","to":"create_issue","when":"novel_count is greater than 0 AND highest_severity is medium or higher"},{"from":"investigate","to":"skip","when":"novel_count is 0, OR highest_severity is low"},{"from":"create_issue","to":"implement","when":"at least one novel finding has fix_complexity simple or moderate AND fix_approach is provided"},{"from":"create_issue","to":"notify","when":"all novel findings have fix_complexity complex, OR no clear fix_approach"},{"from":"skip","to":"notify"},{"from":"implement","to":"create_pr"},{"from":"create_pr","to":"notify"}]};
+export const implementWorkflow = {"id":"implement","name":"Implement Fix","description":"Implement a code fix for an issue and open a pull request","entry":"analyze","nodes":{"analyze":{"name":"Analyze Issue","instruction":"Read the issue details and understand what needs to be fixed:\n\n1. Fetch the issue from the tracker (GitHub or Linear).\n2. Read the relevant source files to understand the current code.\n3. Identify the exact files and lines that need to change.\n4. Plan the fix approach.\n\nOutput a clear analysis of what needs to change and why.","skills":["github","linear"],"output":{"type":"object","properties":{"issue_summary":{"type":"string"},"files_to_change":{"type":"array","items":{"type":"string"}},"fix_plan":{"type":"string"},"risk_level":{"type":"string","enum":["low","medium","high"]}},"required":["issue_summary","fix_plan"]}},"implement":{"name":"Implement Fix","instruction":"Implement the planned fix:\n\n1. Create a feature branch.\n2. Make the necessary code changes.\n3. Ensure changes are minimal and focused — fix the bug, nothing more.\n4. Stage and commit with a clear commit message referencing the issue.\n\nIf the fix is too risky or complex, explain why and skip.","skills":["github"]},"create_pr":{"name":"Open Pull Request","instruction":"Open a pull request for the fix:\n\n1. Push the branch to the remote.\n2. Create a PR with a clear title and description.\n3. Reference the original issue in the PR body.\n4. Add appropriate reviewers or labels if possible.\n\nIf context.prTemplate is provided, use it as the format for the PR body. Otherwise use a clear structure with: Summary, Changes, Testing, and Related Issues.\n\nIf context.cloudRunId is provided, append this HTML comment to the end of the PR body: <!-- sweny:run_id:{context.cloudRunId} -->\n\nReturn the PR URL.","skills":["github"]},"notify":{"name":"Notify","instruction":"Send a notification about the implementation result:\n\n1. Include: issue reference, PR link, brief summary of changes.\n2. Keep it concise — one message, not a wall of text.","skills":["slack","notification"]},"skip":{"name":"Skip — Too Complex","instruction":"The fix was determined to be too complex or risky for automated implementation.\nAdd a comment to the issue explaining what was found and why it needs manual attention.","skills":["github","linear"]}},"edges":[{"from":"analyze","to":"implement","when":"Fix risk level is low or medium and a clear plan exists"},{"from":"analyze","to":"skip","when":"Fix is too complex, risky, or unclear"},{"from":"implement","to":"create_pr"},{"from":"skip","to":"notify"},{"from":"create_pr","to":"notify"}]};
 export const seedContentWorkflow = {"id":"seed-content","name":"Content Generation Pipeline","description":"Audit content gaps, generate educational content, validate quality, and publish to Supabase","entry":"audit","nodes":{"audit":{"name":"Audit Content Gaps","instruction":"You are auditing an educational platform's content library.\n\nUse supabase_count to check how many items exist for each combination of:\n- Content types: worksheets, games, lessons\n- Subjects: math, science, english, history, geography, economics, music, art, life-skills, foreign-language\n- Difficulties: beginner, easy, medium, hard\n\nAlso check the input parameters — if the user specified a subject, topic, difficulty, and count,\nskip the full audit and just report what they want generated.\n\nReturn a structured content plan: what to generate, how many, at what difficulty and grade level.\nPrioritize gaps where a subject has ZERO content of a given type.","skills":["supabase"],"output":{"type":"object","properties":{"plan":{"type":"array","items":{"type":"object","properties":{"contentType":{"type":"string"},"subject":{"type":"string"},"topic":{"type":"string"},"difficulty":{"type":"string"},"gradeLevel":{"type":"string"},"count":{"type":"number"},"reason":{"type":"string"}},"required":["contentType","subject","topic","difficulty","count"]}},"summary":{"type":"string"}},"required":["plan","summary"]}},"generate":{"name":"Generate Content","instruction":"You are an expert educator creating content for children ages 5-14.\n\nFor each item in the content plan from the previous step, generate the content directly.\nThe content must be high-quality, engaging, age-appropriate, and educationally sound.\n\n**For worksheets:**\nGenerate a JSON array of problems. Each problem needs: \"problem\", \"answer\", \"format\" (answer-line | multiple-choice | write-on).\nRequirements:\n- Every answer MUST be correct. Double-check math, facts, spelling.\n- Problems must progress in difficulty within the set.\n- Use at least 2 different problem structures (e.g., equations + word problems for math).\n- Vary phrasing — no two problems should feel copy-pasted.\n- For the target grade level, use appropriate vocabulary and complexity.\n\n**For lessons:**\nGenerate complete HTML + CSS + JS for an interactive lesson.\nRequirements:\n- Must have substantial educational content (not just a shell with navigation).\n- Include interactive elements: quizzes, click-to-reveal, drag-and-drop.\n- Must be visually engaging with colors, icons, and clear typography.\n- Include practice exercises with immediate feedback.\n- Minimum 5 teaching sections plus 2 practice activities.\n\n**For games:**\nGenerate a description and educational requirements only (actual game code is generated\nby the platform's Phaser-based generator).\n\nUse supabase_insert to write each piece of content to the appropriate table.\n\nTable schemas:\n- worksheets: id (auto), title, subject, topic, difficulty, grade_level, num_questions, problems (jsonb), status='published', source='ai-seed'\n- lessons: id (auto), title, subject, difficulty, grade_level, lesson_type, html_code, css_code, js_code, status='published', source='ai-seed'\n- games: id (auto), title, subject, difficulty, grade_level, game_type, html_code, css_code, js_code, status='published', source='ai-seed'\n\nReturn a summary of what was generated and inserted.","skills":["supabase"],"output":{"type":"object","properties":{"generated":{"type":"array","items":{"type":"object","properties":{"contentType":{"type":"string"},"title":{"type":"string"},"subject":{"type":"string"},"id":{"type":"string"},"status":{"type":"string"}}}},"totalGenerated":{"type":"number"},"errors":{"type":"array","items":{"type":"string"}}},"required":["generated","totalGenerated"]}},"validate":{"name":"Validate Content Quality","instruction":"Review the content that was just generated and inserted.\n\nFor each item, use supabase_query to fetch it back and verify:\n\n**Worksheets:**\n- Parse the problems JSON — are all answers correct?\n- Are problems diverse (not repetitive)?\n- Is difficulty appropriate for the stated grade level?\n- Are there the right number of questions?\n\n**Lessons:**\n- Is the HTML substantial (> 500 characters)?\n- Does it contain actual educational content (not just navigation shells)?\n- Are there interactive elements?\n\n**Games:**\n- Does the HTML contain a working game structure?\n\nFlag any issues. If critical issues are found (wrong answers, empty content),\nuse supabase_update to set status='draft' and add a note.\n\nReturn a quality report.","skills":["supabase"],"output":{"type":"object","properties":{"totalReviewed":{"type":"number"},"passed":{"type":"number"},"flagged":{"type":"number"},"issues":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"issue":{"type":"string"},"severity":{"type":"string"},"action":{"type":"string"}}}},"summary":{"type":"string"}},"required":["totalReviewed","passed","flagged","summary"]}},"report":{"name":"Generate Report","instruction":"Compile a final report of the content generation run.\n\nInclude:\n- Total content generated by type and subject\n- Quality validation results\n- Any issues found and actions taken\n- Recommendations for next content generation run (what gaps remain)\n\nFormat as a clean markdown summary that a solo operator can scan in 30 seconds.","skills":[],"output":{"type":"object","properties":{"markdown":{"type":"string"},"nextPriorities":{"type":"array","items":{"type":"string"}}},"required":["markdown"]}}},"edges":[{"from":"audit","to":"generate"},{"from":"generate","to":"validate"},{"from":"validate","to":"report"}]};

package/dist/workflows/implement.yml

@@ -69,6 +69,10 @@ nodes:
       Summary, Changes, Testing, and Related Issues.
 
 
+      If context.cloudRunId is provided, append this HTML comment to the end of the PR body: <!--
+      sweny:run_id:{context.cloudRunId} -->
+
+
       Return the PR URL.
     skills:
       - github

package/dist/workflows/triage.yml

@@ -239,6 +239,10 @@ nodes:
       Summary, Changes, Testing, and Related Issues.
 
 
+      If context.cloudRunId is provided, append this HTML comment to the end of the PR body: <!--
+      sweny:run_id:{context.cloudRunId} -->
+
+
       Return the PR URL and number.
     skills:
       - github

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sweny-ai/core",
-  "version": "0.1.26",
+  "version": "0.1.28",
   "type": "module",
   "bin": {
     "sweny": "./dist/cli/main.js"