@aicoffe/ai-native-sdlc-mcp 0.1.0

package/README.md

@@ -0,0 +1,40 @@
+# ai-native-sdlc-mcp
+
+MCP workflow state-machine server for the AI-native SDLC flow — harness-agnostic, runs over stdio.
+
+## Tools
+
+| Tool | Input | Returns |
+|---|---|---|
+| `workflow_start` | `{title, description?}` | Creates a workflow and returns the current stage view (`llm_generate` / `gate_wait` / processing). |
+| `workflow_stage_completed` | `{workflow_id, stage_id, output[]}` | Records the stage output and returns the next stage view. |
+| `workflow_gate_decision` | `{workflow_id, stage_id, decision, changes?, approved_by?}` | Records `approved`/`rejected`/`modified` and returns the next stage view. |
+| `workflow_get_active` | `{}` | Summaries of all running (non-completed/blocked) workflows, for session-restore. |
+| `workflow_get_state` | `{workflow_id}` | Full persisted state of one workflow. |
+| `workflow_get_gate_prompt` | `{workflow_id}` | Current gate's prompt template, checklist, decisions, and collected artifacts. |
+
+## State layout (under `REPO_ROOT`)
+
+`.workflow/workflows/{id}.json`, `.workflow/index.json`, `.workflow/events/{id}.jsonl`
+
+## Configuration
+
+```json
+{
+  "mcpServers": {
+    "ai-native-sdlc": {
+      "command": "node",
+      "args": ["<repo>/mcp-server/dist/main.js"],
+      "env": { "REPO_ROOT": "<repo>" }
+    }
+  }
+}
+```
+
+## Development
+
+```bash
+npm install && npm run build && npm test && npm start
+```
+
+PR-related stages (`create-pr` / `merge-pr`) require the GitHub `gh` CLI; without it the workflow transitions to `blocked` with a clear error. stdout carries only the MCP protocol; logs go to stderr.

package/dist/main.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/main.js

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+// mcp-server/src/main.ts — thin stdio entry. All wiring lives in server.ts.
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { buildWorkflowServer } from './server.js';
+async function main() {
+    const repoRoot = process.env.REPO_ROOT || process.cwd();
+    const { mcpServer, recover } = buildWorkflowServer(repoRoot);
+    await recover();
+    await mcpServer.connect(new StdioServerTransport());
+    console.error(`ai-native-sdlc-mcp running on stdio (repo: ${repoRoot})`);
+    const shutdown = async () => {
+        try {
+            await mcpServer.close();
+        }
+        finally {
+            process.exit(0);
+        }
+    };
+    process.on('SIGINT', () => void shutdown());
+    process.on('SIGTERM', () => void shutdown());
+}
+main().catch((error) => {
+    console.error('ai-native-sdlc-mcp fatal:', error instanceof Error ? error.message : error);
+    process.exit(1);
+});

package/dist/server.d.ts

@@ -0,0 +1,16 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { WorkflowEventBus } from './workflow/event-bus.js';
+import { WorkflowStore } from './workflow/store.js';
+import { WorkflowStateMachine } from './workflow/state-machine.js';
+export interface WorkflowServer {
+    mcpServer: McpServer;
+    store: WorkflowStore;
+    bus: WorkflowEventBus;
+    machine: WorkflowStateMachine;
+    recover: () => Promise<void>;
+}
+export declare function buildWorkflowServer(repoRoot: string): WorkflowServer;
+export declare function createTestPair(): [InMemoryTransport, InMemoryTransport];
+export type McpClient = Client;

package/dist/server.js

@@ -0,0 +1,21 @@
+// mcp-server/src/server.ts
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js';
+import { WORKFLOW_DEFINITION } from './workflow/definition.js';
+import { WorkflowEventBus } from './workflow/event-bus.js';
+import { WorkflowStore } from './workflow/store.js';
+import { WorkflowStateMachine } from './workflow/state-machine.js';
+import { ExecFileGhAdapter } from './workflow/handlers/gh.js';
+import { buildActionHandlers } from './workflow/handlers/index.js';
+import { registerWorkflowTools } from './tools/workflow-tools.js';
+export function buildWorkflowServer(repoRoot) {
+    const mcpServer = new McpServer({ name: 'ai-native-sdlc-mcp', version: '0.1.0' });
+    const store = new WorkflowStore(repoRoot);
+    const bus = new WorkflowEventBus(repoRoot);
+    const machine = new WorkflowStateMachine(WORKFLOW_DEFINITION, store, bus, buildActionHandlers({ repoRoot, gh: new ExecFileGhAdapter(repoRoot) }));
+    registerWorkflowTools(mcpServer, { store, bus, machine, definition: WORKFLOW_DEFINITION });
+    return { mcpServer, store, bus, machine, recover: () => machine.recoverWorkflows() };
+}
+export function createTestPair() {
+    return InMemoryTransport.createLinkedPair();
+}

package/dist/tools/workflow-tools.d.ts

@@ -0,0 +1,14 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { WorkflowEventBus } from '../workflow/event-bus.js';
+import { WorkflowStore } from '../workflow/store.js';
+import { WorkflowStateMachine } from '../workflow/state-machine.js';
+import type { WorkflowDefinition, WorkflowState } from '../workflow/types.js';
+export interface WorkflowToolDeps {
+    store: WorkflowStore;
+    bus: WorkflowEventBus;
+    machine: WorkflowStateMachine;
+    definition: WorkflowDefinition;
+}
+/** Doc §6 view for a state: llm_generate / gate_wait / processing. */
+export declare function buildToolResponse(state: WorkflowState, machine: WorkflowStateMachine): Record<string, unknown>;
+export declare function registerWorkflowTools(mcpServer: McpServer, deps: WorkflowToolDeps): void;

package/dist/tools/workflow-tools.js

@@ -0,0 +1,171 @@
+import { z } from 'zod';
+import { KeyedMutex } from '../workflow/mutex.js';
+import { dateCompact, dateIso, generateIds, nextDailyCount } from '../workflow/ids.js';
+import { gateDecisionEvent, stageCompletedEvent, workflowStartedEvent } from '../workflow/events.js';
+/** F1: workflow_id is filesystem-derived — strict pattern, no traversal. */
+const workflowIdSchema = z.string().regex(/^WF-\d{8}-\d{3}$/);
+/** Doc §6 view for a state: llm_generate / gate_wait / processing. */
+export function buildToolResponse(state, machine) {
+    return machine.getCurrentStageView(state);
+}
+function ok(payload) {
+    return { content: [{ type: 'text', text: JSON.stringify(payload) }] };
+}
+// D11: tools NEVER throw; errors come back as isError JSON.
+function fail(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+        content: [{ type: 'text', text: JSON.stringify({ error: message }) }],
+        isError: true,
+    };
+}
+// F4: ALL mutating tools serialize on ONE repo-level key — action handlers
+// share the single git working tree, so per-workflow keys would let one
+// workflow's checkout/commit race another's.
+const REPO_MUTEX_KEY = '$repo';
+export function registerWorkflowTools(mcpServer, deps) {
+    const { store, bus, machine, definition } = deps;
+    const mutex = new KeyedMutex();
+    mcpServer.registerTool('workflow_start', {
+        description: '启动一个新的工作流。由 /new-intent 命令或用户意图触发。',
+        inputSchema: z.object({
+            title: z.string(),
+            description: z.string().optional(),
+        }),
+    }, async ({ title, description }) => {
+        try {
+            const state = await mutex.run(REPO_MUTEX_KEY, async () => {
+                const now = new Date();
+                const states = await store.listAll();
+                const count = nextDailyCount(states.map((s) => s.workflow_id), dateCompact(now));
+                const ids = generateIds(title, now, count);
+                const state = {
+                    workflow_id: ids.workflow_id,
+                    intent_id: ids.intent_id,
+                    title,
+                    current_stage: definition.initial_stage,
+                    status: 'running',
+                    stages: {},
+                    context: {
+                        date: dateIso(now),
+                        slug: ids.slug,
+                        title,
+                        domain: 'default',
+                        ...(description !== undefined ? { description } : {}),
+                    },
+                    created_at: now.toISOString(),
+                    last_active: now.toISOString(),
+                };
+                await store.save(state);
+                // Audit trail: every workflow's event log starts with workflow.started.
+                await bus.emitWorkflowEvent(workflowStartedEvent(state.workflow_id, title));
+                return state;
+            });
+            return ok(buildToolResponse(state, machine));
+        }
+        catch (error) {
+            return fail(error);
+        }
+    });
+    mcpServer.registerTool('workflow_stage_completed', {
+        description: '当完成当前阶段的内容生成后调用。通知状态机推进。',
+        inputSchema: z.object({
+            workflow_id: workflowIdSchema,
+            stage_id: z.string(),
+            output: z.array(z.string()),
+        }),
+    }, async ({ workflow_id, stage_id, output }) => {
+        try {
+            const state = await mutex.run(REPO_MUTEX_KEY, async () => {
+                await bus.emitWorkflowEvent(stageCompletedEvent(workflow_id, stage_id, output));
+                const reloaded = await store.load(workflow_id);
+                if (!reloaded)
+                    throw new Error(`Unknown workflow: ${workflow_id}`);
+                return reloaded;
+            });
+            return ok(buildToolResponse(state, machine));
+        }
+        catch (error) {
+            return fail(error);
+        }
+    });
+    mcpServer.registerTool('workflow_gate_decision', {
+        description: '当用户在 gate 点做出决定后调用。',
+        inputSchema: z.object({
+            workflow_id: workflowIdSchema,
+            stage_id: z.string(),
+            decision: z.enum(['approved', 'rejected', 'modified']),
+            changes: z.string().optional(),
+            approved_by: z.string().optional(),
+        }),
+    }, async ({ workflow_id, stage_id, decision, changes, approved_by }) => {
+        try {
+            const state = await mutex.run(REPO_MUTEX_KEY, async () => {
+                await bus.emitWorkflowEvent(gateDecisionEvent({
+                    workflow_id,
+                    stage_id,
+                    decision,
+                    ...(changes !== undefined ? { changes } : {}),
+                    approved_by: approved_by ?? 'unknown',
+                }));
+                const reloaded = await store.load(workflow_id);
+                if (!reloaded)
+                    throw new Error(`Unknown workflow: ${workflow_id}`);
+                return reloaded;
+            });
+            return ok(buildToolResponse(state, machine));
+        }
+        catch (error) {
+            return fail(error);
+        }
+    });
+    mcpServer.registerTool('workflow_get_active', {
+        description: '获取所有进行中的工作流。会话启动时调用，用于恢复上下文。',
+        inputSchema: z.object({}),
+    }, async () => {
+        try {
+            return ok({ active: await store.getActiveSummaries() });
+        }
+        catch (error) {
+            return fail(error);
+        }
+    });
+    mcpServer.registerTool('workflow_get_state', {
+        description: '获取指定工作流的完整状态。',
+        inputSchema: z.object({ workflow_id: workflowIdSchema }),
+    }, async ({ workflow_id }) => {
+        try {
+            const state = await store.load(workflow_id);
+            if (!state)
+                throw new Error(`Unknown workflow: ${workflow_id}`);
+            return ok(state);
+        }
+        catch (error) {
+            return fail(error);
+        }
+    });
+    mcpServer.registerTool('workflow_get_gate_prompt', {
+        description: '获取当前 gate 的提示模板和检查清单。',
+        inputSchema: z.object({ workflow_id: workflowIdSchema }),
+    }, async ({ workflow_id }) => {
+        try {
+            const state = await store.load(workflow_id);
+            if (!state)
+                throw new Error(`Unknown workflow: ${workflow_id}`);
+            const stage = machine.getStage(state.current_stage);
+            if (stage.type !== 'gate') {
+                throw new Error(`Current stage ${stage.id} is not a gate`);
+            }
+            return ok({
+                gate_id: stage.id,
+                checklist: stage.checklist ?? [],
+                gate_prompt: machine.renderPrompt(stage.gate_prompt, state),
+                decisions: stage.decisions ?? [],
+                artifacts: machine.collectArtifacts(state),
+            });
+        }
+        catch (error) {
+            return fail(error);
+        }
+    });
+}

package/dist/workflow/definition.d.ts

@@ -0,0 +1,2 @@
+import type { WorkflowDefinition } from './types.js';
+export declare const WORKFLOW_DEFINITION: WorkflowDefinition;

package/dist/workflow/definition.js

@@ -0,0 +1,252 @@
+export const WORKFLOW_DEFINITION = {
+    id: 'ai-native-sdlc',
+    version: '1.0.0',
+    name: 'AI Native SDLC',
+    initial_stage: 'stage0_intent',
+    context_schema: {
+        date: { type: 'date', required: true, source: 'generated' },
+        slug: { type: 'slug', required: true, source: 'generated' },
+        title: { type: 'string', required: true, source: 'user_input' },
+        domain: { type: 'string', required: true, source: 'derived' },
+        repos: { type: 'array', required: false, source: 'derived' },
+    },
+    stages: [
+        // ========== 阶段0：意图孵化 ==========
+        {
+            id: 'stage0_intent',
+            name: '意图孵化',
+            type: 'llm_generation',
+            skill: 'intent-capture-skill',
+            prompt_template: `
+        引导用户描述：
+        1. 想解决什么问题
+        2. 谁受影响
+        3. 期望的结果
+        4. 硬性约束
+        5. 开放性问题
+        生成 intent.md 草稿。
+      `,
+            outputs: ['intent/{date}-{slug}.md'],
+            next: 'gate1_intent_review',
+        },
+        // ========== Gate1：意图审查 ==========
+        {
+            id: 'gate1_intent_review',
+            name: '意图审查',
+            type: 'gate',
+            checklist: ['问题描述清晰', '预期结果可衡量', '约束明确', '开放性问题已记录'],
+            gate_prompt: 'intent.md 已生成，请审查。确认后进入设计阶段。',
+            decisions: ['approved', 'rejected', 'modified'],
+            next: 'action_create_spec_dir',
+            on_reject: 'stage0_intent',
+        },
+        // ========== Action：创建规格目录 ==========
+        {
+            id: 'action_create_spec_dir',
+            name: '创建规格目录',
+            type: 'action',
+            handler: 'create-spec-dir',
+            handler_params: {
+                create_subdirs: ['reviews/code-review', 'reviews/task-verification', 'design'],
+                write_files: ['reviews/intent-review.md'],
+                git_commit: true,
+            },
+            next: 'stage2_spec',
+            on_error: 'blocked',
+        },
+        // ========== 阶段2：规格生成 ==========
+        {
+            id: 'stage2_spec',
+            name: '规格生成',
+            type: 'llm_generation',
+            skill: 'spec-generation-skill',
+            prompt_template: `
+        读取 intent.md 和活状态索引，生成 spec.md。
+        必须包含 Areas of Concern 章节，列出所有无法自动解决的冲突。
+      `,
+            inputs: ['intent/{date}-{slug}.md', 'specs/_current/{domain}.md'],
+            outputs: ['specs/{date}-{slug}/spec.md'],
+            next: 'gate2_spec_review',
+        },
+        // ========== Gate2：规格审查 + 冲突裁决 ==========
+        {
+            id: 'gate2_spec_review',
+            name: '规格审查与冲突裁决',
+            type: 'gate',
+            checklist: ['业务逻辑完整', '接口定义清晰', 'Areas of Concern 已列出'],
+            gate_prompt: 'spec.md 已生成，发现 {conflict_count} 个冲突需裁决：{conflicts}',
+            decisions: ['approved', 'rejected', 'modified'],
+            next: 'stage3_design',
+            on_reject: 'stage2_spec',
+        },
+        // ========== 阶段3：UE设计 ==========
+        {
+            id: 'stage3_design',
+            name: 'UE设计',
+            type: 'llm_generation',
+            skill: 'ui-ux-pro-max-skill',
+            prompt_template: '基于 spec.md 生成高保真设计产物。',
+            inputs: ['specs/{date}-{slug}/spec.md'],
+            outputs: ['specs/{date}-{slug}/design/pages/*.html', 'specs/{date}-{slug}/design/tokens/*.json'],
+            next: 'gate3_design_review',
+        },
+        // ========== Gate3：设计审查 ==========
+        {
+            id: 'gate3_design_review',
+            name: '设计审查',
+            type: 'gate',
+            checklist: ['视觉符合品牌', '交互符合预期'],
+            gate_prompt: '高保真设计已生成，请审查：{artifacts}',
+            decisions: ['approved', 'modified'],
+            next: 'stage4_plan',
+            on_reject: 'stage3_design',
+        },
+        // ========== 阶段4：计划生成 ==========
+        {
+            id: 'stage4_plan',
+            name: '计划生成',
+            type: 'llm_generation',
+            skill: 'plan-generation-skill',
+            prompt_template: '读取 spec.md + design/ + codebase-context.md，生成 plan.md。',
+            inputs: ['specs/{date}-{slug}/spec.md', 'specs/{date}-{slug}/design/'],
+            outputs: ['specs/{date}-{slug}/plan.md'],
+            next: 'gate4_plan_review',
+        },
+        // ========== Gate4：计划审查 ==========
+        {
+            id: 'gate4_plan_review',
+            name: '计划审查',
+            type: 'gate',
+            checklist: ['变更范围与 spec 一致', '风险已识别', '回滚预案明确'],
+            gate_prompt: 'plan.md 已生成，请审查实施步骤和风险。',
+            decisions: ['approved', 'modified'],
+            next: 'stage5_tasks',
+            on_reject: 'stage4_plan',
+        },
+        // ========== 阶段5：任务拆解 ==========
+        {
+            id: 'stage5_tasks',
+            name: '任务拆解',
+            type: 'llm_generation',
+            skill: 'task-decomposition-skill',
+            prompt_template: '基于 plan.md 拆解为原子任务，生成 tasks.md。',
+            inputs: ['specs/{date}-{slug}/plan.md'],
+            outputs: ['specs/{date}-{slug}/tasks.md'],
+            next: 'gate5_tasks_review',
+        },
+        // ========== Gate5：任务审查 ==========
+        {
+            id: 'gate5_tasks_review',
+            name: '任务审查',
+            type: 'gate',
+            checklist: ['任务粒度合理', '依赖关系清晰', '验证标准可执行'],
+            gate_prompt: 'tasks.md 已生成，共 {task_count} 个任务。确认后开始执行。',
+            decisions: ['approved', 'modified'],
+            next: 'action_create_branch',
+            on_reject: 'stage5_tasks',
+        },
+        // ========== Action：创建分支 ==========
+        {
+            id: 'action_create_branch',
+            name: '创建特性分支',
+            type: 'action',
+            handler: 'create-feature-branch',
+            handler_params: {
+                branch_pattern: 'feature/{date}-{slug}',
+            },
+            next: 'stage6_codegen',
+            on_error: 'blocked',
+        },
+        // ========== 阶段6：代码生成 ==========
+        {
+            id: 'stage6_codegen',
+            name: '代码生成',
+            type: 'llm_generation',
+            skill: 'code-generation-skill',
+            prompt_template: '在特性分支上逐 Task 执行，每个 Task 完成后运行验证命令。',
+            inputs: ['specs/{date}-{slug}/tasks.md', 'specs/{date}-{slug}/design/'],
+            outputs: ['src/**', 'specs/{date}-{slug}/reviews/task-verification/*.json'],
+            next: 'action_create_pr',
+        },
+        // ========== Action：创建 PR ==========
+        {
+            id: 'action_create_pr',
+            name: '创建 PR',
+            type: 'action',
+            handler: 'create-pr',
+            handler_params: {
+                title_pattern: 'feat: {title}',
+                base_branch: 'main',
+                trigger_ai_review: true,
+            },
+            next: 'gate6_pr_review',
+            on_error: 'blocked',
+        },
+        // ========== Gate6：PR 审查 ==========
+        {
+            id: 'gate6_pr_review',
+            name: 'PR 审查',
+            type: 'gate',
+            checklist: ['AI findings 已处理', '测试通过', '代码 Owner 批准'],
+            gate_prompt: 'PR #{pr_number} 已创建，AI Review 发现 {findings_summary}。',
+            decisions: ['approved', 'rejected', 'modified'],
+            next: 'action_merge_pr',
+            on_reject: 'stage6_codegen',
+        },
+        // ========== Action：合并 PR ==========
+        {
+            id: 'action_merge_pr',
+            name: '合并 PR',
+            type: 'action',
+            handler: 'merge-pr',
+            handler_params: {
+                require_approvals: true,
+                delete_branch: true,
+            },
+            next: 'action_update_current_index',
+            on_error: 'blocked',
+        },
+        // ========== Action：更新活状态索引 ==========
+        {
+            id: 'action_update_current_index',
+            name: '更新活状态索引',
+            type: 'action',
+            handler: 'update-current-index',
+            handler_params: {
+                target: 'specs/_current/{domain}.md',
+                git_commit: true,
+            },
+            next: 'action_close_intent',
+        },
+        // ========== Action：关闭 intent ==========
+        {
+            id: 'action_close_intent',
+            name: '关闭意图',
+            type: 'action',
+            handler: 'close-intent',
+            handler_params: {
+                update_status: 'implemented',
+            },
+            next: 'completed',
+        },
+        // ========== 终态 ==========
+        {
+            id: 'completed',
+            name: '已完成',
+            type: 'action',
+            handler: 'noop',
+            next: 'completed',
+        },
+        // ========== 异常态 ==========
+        {
+            id: 'blocked',
+            name: '阻塞',
+            type: 'action',
+            handler: 'notify-blocked',
+            handler_params: {
+                notify: ['architect', 'owner'],
+            },
+            next: 'blocked',
+        },
+    ],
+};

package/dist/workflow/event-bus.d.ts

@@ -0,0 +1,16 @@
+import type { WorkflowEvent, WorkflowEventType } from './types.js';
+export type EventListener = (event: WorkflowEvent) => void | Promise<void>;
+export declare class WorkflowEventBus {
+    private readonly listeners;
+    private readonly eventsDir;
+    constructor(repoRoot: string);
+    /** Registers a listener; returns an unsubscribe function. */
+    on(eventType: WorkflowEventType | '*', listener: EventListener): () => void;
+    /**
+     * (1) persist the event as a JSON line in {repoRoot}/.workflow/events/{id}.jsonl,
+     * (2) dispatch to typed + '*' listeners and AWAIT ALL of them via Promise.all.
+     * Listener errors reject the returned promise (propagate to the emit caller).
+     */
+    emitWorkflowEvent(event: WorkflowEvent): Promise<void>;
+    private persistEvent;
+}

package/dist/workflow/event-bus.js

@@ -0,0 +1,46 @@
+// mcp-server/src/workflow/event-bus.ts
+//
+// Deliberately NOT EventEmitter-based: EventEmitter cannot await async
+// listeners, and the tool layer needs emit() to resolve only after every
+// listener (e.g. the state machine) has fully finished, so state can be
+// reloaded deterministically afterwards.
+import { appendFile, mkdir } from 'node:fs/promises';
+import path from 'node:path';
+import { resolveUnderBase } from './paths.js';
+export class WorkflowEventBus {
+    listeners = new Map();
+    eventsDir;
+    constructor(repoRoot) {
+        this.eventsDir = path.join(repoRoot, '.workflow', 'events');
+    }
+    /** Registers a listener; returns an unsubscribe function. */
+    on(eventType, listener) {
+        const list = this.listeners.get(eventType) ?? [];
+        list.push(listener);
+        this.listeners.set(eventType, list);
+        return () => {
+            const current = this.listeners.get(eventType) ?? [];
+            const idx = current.indexOf(listener);
+            if (idx >= 0)
+                current.splice(idx, 1);
+        };
+    }
+    /**
+     * (1) persist the event as a JSON line in {repoRoot}/.workflow/events/{id}.jsonl,
+     * (2) dispatch to typed + '*' listeners and AWAIT ALL of them via Promise.all.
+     * Listener errors reject the returned promise (propagate to the emit caller).
+     */
+    async emitWorkflowEvent(event) {
+        await this.persistEvent(event);
+        const targets = [
+            ...(this.listeners.get(event.type) ?? []),
+            ...(this.listeners.get('*') ?? []),
+        ];
+        await Promise.all(targets.map((listener) => listener(event)));
+    }
+    async persistEvent(event) {
+        const target = resolveUnderBase(this.eventsDir, `${event.workflow_id}.jsonl`);
+        await mkdir(this.eventsDir, { recursive: true });
+        await appendFile(target, JSON.stringify(event) + '\n', 'utf8');
+    }
+}

package/dist/workflow/events.d.ts

@@ -0,0 +1,12 @@
+import type { ActionCompletedEvent, ActionFailedEvent, GateDecision, GateDecisionEvent, StageCompletedEvent, WorkflowStartedEvent } from './types.js';
+export declare function workflowStartedEvent(workflow_id: string, title: string): WorkflowStartedEvent;
+export declare function stageCompletedEvent(workflow_id: string, stage_id: string, output: string[]): StageCompletedEvent;
+export declare function gateDecisionEvent(args: {
+    workflow_id: string;
+    stage_id: string;
+    decision: GateDecision;
+    changes?: string;
+    approved_by: string;
+}): GateDecisionEvent;
+export declare function actionCompletedEvent(workflow_id: string, stage_id: string, result: Record<string, unknown>): ActionCompletedEvent;
+export declare function actionFailedEvent(workflow_id: string, stage_id: string, error: string, retryable: boolean): ActionFailedEvent;