@hongmaple0820/med-scale-research-os 0.43.0

package/dist/api/quickstart.js

@@ -0,0 +1,291 @@
+// SCALE Engine — Quick Start / One-Click Install
+// 自动检测平台、配置物理约束、可选安装知识图谱
+import { existsSync, mkdirSync, writeFileSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { execSync } from 'node:child_process';
+import { bootstrapDependencies } from '../bootstrap/DependencyBootstrap.js';
+import { inspectCodeIntelligence } from '../codegraph/CodeIntelligence.js';
+import { getBootstrapPlanForProfile } from '../config/profiles.js';
+import { inspectToolCapabilities } from '../tools/ToolCapabilityRegistry.js';
+import { writeGovernanceTemplates } from '../workflow/GovernanceTemplates.js';
+// Auto-detect the best governance pack based on project files
+export function autoDetectGovernancePack(projectDir) {
+    const pkgPath = join(projectDir, 'package.json');
+    if (existsSync(pkgPath)) {
+        try {
+            const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+            const scripts = Object.keys(pkg.scripts ?? {});
+            const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+            // Check for frontend frameworks
+            if (deps.react || deps.next || deps.vue || deps['@angular/core'] ||
+                (pkg.scripts?.build ?? '').includes('vite') || (pkg.scripts?.build ?? '').includes('webpack')) {
+                return 'frontend-app';
+            }
+            // Check for library
+            if (pkg.main || pkg.module || pkg.exports) {
+                return 'node-library';
+            }
+        }
+        catch { }
+    }
+    if (existsSync(join(projectDir, 'go.mod')))
+        return 'go-service-matrix';
+    if (existsSync(join(projectDir, 'pyproject.toml')) || existsSync(join(projectDir, 'requirements.txt')))
+        return 'standard';
+    // Check for monorepo
+    if (existsSync(join(projectDir, 'lerna.json')) || existsSync(join(projectDir, 'nx.json')) ||
+        existsSync(join(projectDir, 'turbo.json'))) {
+        const pkgPath = join(projectDir, 'package.json');
+        if (existsSync(pkgPath)) {
+            try {
+                const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+                if (pkg.workspaces)
+                    return 'moe-workspace';
+            }
+            catch { }
+        }
+        return 'project-scaffold';
+    }
+    return 'standard';
+}
+// Auto-classify project structure
+export function classifyProject(projectDir) {
+    const result = {
+        language: 'unknown',
+        isMonorepo: false,
+        isLibrary: false,
+        recommendedPack: 'standard',
+        recommendedProfile: 'standard',
+    };
+    const pkgPath = join(projectDir, 'package.json');
+    if (existsSync(pkgPath)) {
+        result.language = 'node';
+        try {
+            const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+            const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+            if (pkg.workspaces || existsSync(join(projectDir, 'lerna.json')) || existsSync(join(projectDir, 'nx.json'))) {
+                result.isMonorepo = true;
+                result.recommendedPack = 'moe-workspace';
+            }
+            if (deps.react) {
+                result.framework = 'react';
+                result.recommendedPack = 'frontend-app';
+            }
+            else if (deps.next) {
+                result.framework = 'next';
+                result.recommendedPack = 'frontend-app';
+            }
+            else if (deps.vue) {
+                result.framework = 'vue';
+                result.recommendedPack = 'frontend-app';
+            }
+            else if (deps.express || deps.fastify || deps.koa) {
+                result.framework = 'express';
+                result.recommendedPack = 'node-library';
+            }
+            if (!result.framework && (pkg.main || pkg.module || pkg.exports)) {
+                result.isLibrary = true;
+                result.recommendedPack = 'node-library';
+            }
+            const scripts = pkg.scripts ?? {};
+            const hasTest = Object.keys(scripts).some(k => k.includes('test'));
+            const hasLint = Object.keys(scripts).some(k => k.includes('lint'));
+            if (!hasTest || !hasLint)
+                result.recommendedProfile = 'minimal';
+        }
+        catch { }
+    }
+    if (existsSync(join(projectDir, 'go.mod'))) {
+        result.language = 'go';
+        result.recommendedPack = 'go-service-matrix';
+    }
+    if (existsSync(join(projectDir, 'pyproject.toml'))) {
+        result.language = 'python';
+        result.recommendedPack = 'standard';
+    }
+    return result;
+}
+export function detectPlatform(projectDir = '.') {
+    const checks = [
+        { platform: 'claude-code', paths: [join(projectDir, '.claude', 'settings.json')] },
+        { platform: 'codex', paths: [join(projectDir, '.codex', 'config.toml')] },
+        { platform: 'cursor', paths: [join(projectDir, '.cursorrules')] },
+        { platform: 'gemini', paths: [join(projectDir, '.gemini', 'settings.json')] },
+        { platform: 'qoder', paths: [join(projectDir, '.qoder', 'settings.json')] },
+        { platform: 'jcode', paths: [join(projectDir, '.jcode', 'settings.json')] },
+        { platform: 'aider', paths: [join(projectDir, '.aider.conf.yml')] },
+        { platform: 'deepseek-tui', paths: [join(projectDir, '.deepseek', 'instructions.md')] },
+        { platform: 'windsurf', paths: [join(projectDir, '.windsurf', 'settings.json'), join(projectDir, '.windsurfrc')] },
+        { platform: 'kimi', paths: [join(projectDir, '.kimi', 'settings.json')] },
+        { platform: 'doubao', paths: [join(projectDir, '.doubao', 'settings.json')] },
+        { platform: 'kiro', paths: [join(projectDir, '.kiro', 'settings.json')] },
+        { platform: 'cline', paths: [join(projectDir, '.cline', 'settings.json'), join(projectDir, '.clinerules')] },
+        { platform: 'kilocode', paths: [join(projectDir, '.kilocode', 'settings.json')] },
+        { platform: 'antigravity', paths: [join(projectDir, '.agents', 'hooks.json'), join(projectDir, '.agents', 'rules')] },
+    ];
+    for (const check of checks) {
+        for (const p of check.paths)
+            if (existsSync(p))
+                return { platform: check.platform, confidence: 1.0, suggestions: [] };
+    }
+    return { platform: null, confidence: 0, suggestions: ['claude-code', 'cursor', 'qoder', 'cline', 'windsurf'] };
+}
+export const PHYSICAL_CONSTRAINTS = [
+    { id: 'block-dangerous', severity: 'critical', matcher: 'Bash', command: 'scale guard dangerous' },
+    { id: 'block-secrets', severity: 'critical', matcher: 'Edit|Write', command: 'scale guard secrets' },
+    { id: 'detect-retry', severity: 'high', matcher: '', command: 'scale guard retry' },
+];
+export function governanceNextSteps(options = {}) {
+    const steps = [];
+    const bootstrapPlan = getBootstrapPlanForProfile(options.profileId ?? 'standard', options.governancePack);
+    if (options.includeAgentInit) {
+        steps.push('scale init --agent <platform>  # optional: add agent-specific hooks later');
+    }
+    if (options.includeDependencyBootstrap !== false) {
+        steps.push(`${bootstrapPlan.inspectCommand}  # inspect/install third-party skills and CLI dependencies explicitly`);
+    }
+    steps.push('scale doctor', 'scale create Spec "<feature>"', 'edit .scale/product-smoke.json and enable a real product-path probe', 'scale preflight --profile productSmoke --json', 'scale runtime final-check --level M --json');
+    return steps;
+}
+export async function quickStart(projectDir = '.', options) {
+    const bootstrapPlan = getBootstrapPlanForProfile(options?.profileId ?? 'standard', options?.governancePack);
+    const result = {
+        success: false, platform: null, created: [], skipped: [],
+        constraintsApplied: 0,
+        workflowCapabilities: ['browser', 'search', 'computer'],
+        capabilitiesEnabled: ['browser', 'search', 'computer'],
+        dependencyBootstrapCommand: bootstrapPlan.inspectCommand,
+        nextSteps: [],
+    };
+    const detection = detectPlatform(projectDir);
+    result.platform = detection.platform;
+    const governanceOnly = !detection.platform && Boolean(options?.governancePack);
+    if (!detection.platform && !governanceOnly) {
+        result.nextSteps.push('scale init --agent <platform>');
+        return result;
+    }
+    const scaleDir = join(projectDir, '.scale');
+    for (const dir of ['events', 'artifacts', 'rules', 'hooks', 'checkpoints']) {
+        const fullDir = join(scaleDir, dir);
+        if (!existsSync(fullDir)) {
+            mkdirSync(fullDir, { recursive: true });
+            result.created.push(fullDir);
+        }
+        else {
+            result.skipped.push(fullDir);
+        }
+    }
+    const gitignorePath = join(scaleDir, '.gitignore');
+    if (!existsSync(gitignorePath)) {
+        writeFileSync(gitignorePath, '*.db\n*.db-journal\nevents/\ncheckpoints/\nevidence/\nstate/\nhooks/*.sh\n');
+        result.created.push(gitignorePath);
+    }
+    result.constraintsApplied = detection.platform ? PHYSICAL_CONSTRAINTS.length : 0;
+    const projectName = projectDir.split(/[/\\]/).pop() || 'Project';
+    const governance = writeGovernanceTemplates(projectDir, { mode: 'standard', projectName, pack: options?.governancePack });
+    result.created.push(...governance.created);
+    result.skipped.push(...governance.skipped);
+    // Optional: Install governed knowledge dependencies (codegraph/graphify)
+    if (options?.installKnowledgeGraph) {
+        result.knowledgeGraph = await installKnowledgeGraph(projectDir, { scaleDir: '.scale' });
+        if (result.knowledgeGraph.available) {
+            if (result.knowledgeGraph.codegraphInstalled) {
+                result.nextSteps.push('codegraph init -i .  # Build local CodeGraph index');
+            }
+            if (result.knowledgeGraph.graphifyInstalled) {
+                result.nextSteps.push('scale graphify .  # Build code knowledge graph');
+            }
+        }
+    }
+    else {
+        result.knowledgeGraph = checkKnowledgeGraphAvailability(projectDir, { scaleDir: '.scale' });
+    }
+    result.success = true;
+    result.nextSteps.push(...governanceNextSteps({
+        includeAgentInit: !detection.platform,
+        includeDependencyBootstrap: true,
+        profileId: options?.profileId ?? 'standard',
+        governancePack: options?.governancePack,
+    }));
+    return result;
+}
+/**
+ * Check if CodeGraph or Graphify are available (without installing)
+ */
+export function checkKnowledgeGraphAvailability(projectDir = '.', deps = {}) {
+    const inspectTools = deps.inspectToolCapabilitiesImpl ?? inspectToolCapabilities;
+    const inspectCode = deps.inspectCodeIntelligenceImpl ?? inspectCodeIntelligence;
+    const execSyncImpl = deps.execSyncImpl ?? execSync;
+    const toolReport = inspectTools({
+        projectDir,
+        toolIds: ['codegraph', 'graphify'],
+    });
+    const codeReport = inspectCode({
+        projectDir,
+        scaleDir: deps.scaleDir,
+    });
+    const codegraphTool = toolReport.tools.find(tool => tool.id === 'codegraph');
+    const graphifyTool = toolReport.tools.find(tool => tool.id === 'graphify');
+    const graphifyProvider = codeReport.providers.find(provider => provider.id === 'graphify');
+    const result = {
+        available: false,
+        graphifyInstalled: Boolean(graphifyTool?.installed),
+        graphifyVersion: graphifyTool?.version,
+        codegraphInstalled: Boolean(codegraphTool?.installed),
+        codegraphVersion: codegraphTool?.version,
+        codegraphProjectInitialized: codeReport.projectIndexExists,
+        graphifyArtifactPresent: Boolean(graphifyProvider?.available),
+    };
+    try {
+        result.pythonVersion = execSyncImpl('python3 --version', { encoding: 'utf-8', timeout: 5000 }).trim();
+    }
+    catch {
+        try {
+            result.pythonVersion = execSyncImpl('python --version', { encoding: 'utf-8', timeout: 5000 }).trim();
+        }
+        catch {
+            // Python is optional when Graphify is already installed.
+        }
+    }
+    const instructions = [];
+    if (!result.codegraphInstalled || !result.graphifyInstalled) {
+        instructions.push('scale bootstrap deps --pack knowledge --json');
+        instructions.push('scale bootstrap deps --pack knowledge --apply');
+    }
+    if (!result.pythonVersion && !result.graphifyInstalled && !result.graphifyArtifactPresent) {
+        instructions.push('Install Python 3.10+ to enable Graphify CLI installation.');
+    }
+    if (result.codegraphInstalled && !result.codegraphProjectInitialized) {
+        instructions.push('codegraph init -i .');
+    }
+    if (result.graphifyInstalled && !result.graphifyArtifactPresent) {
+        instructions.push('Generate graphify-out/graph.json before relying on graph-backed knowledge recall.');
+    }
+    result.available = result.graphifyInstalled || Boolean(result.codegraphInstalled);
+    result.instructions = instructions.length > 0 ? uniqueStrings(instructions) : undefined;
+    return result;
+}
+/**
+ * Attempt to install knowledge graph dependencies through the governed bootstrap path.
+ */
+export async function installKnowledgeGraph(projectDir = '.', deps = {}) {
+    const bootstrap = deps.bootstrapDependenciesImpl ?? bootstrapDependencies;
+    const bootstrapReport = await bootstrap({
+        projectDir,
+        scaleDir: deps.scaleDir,
+        packIds: ['knowledge'],
+        apply: true,
+    });
+    const result = checkKnowledgeGraphAvailability(projectDir, deps);
+    const instructions = uniqueStrings([
+        ...(result.instructions ?? []),
+        ...bootstrapReport.recommendations,
+        ...bootstrapReport.postCheckCommands,
+    ]);
+    result.instructions = instructions.length > 0 ? instructions : undefined;
+    return result;
+}
+function uniqueStrings(values) {
+    return [...new Set(values.filter(Boolean))];
+}
+//# sourceMappingURL=quickstart.js.map

package/dist/api/quickstart.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"quickstart.js","sourceRoot":"","sources":["../../src/api/quickstart.ts"],"names":[],"mappings":"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"}

package/dist/artifact/fsm.d.ts

@@ -0,0 +1,41 @@
+/**
+ * SCALE Engine — FSM (Finite State Machine) Engine
+ *
+ * 系统的"宪法执行者"。
+ * 所有 Artifact 状态变化必须通过 fsm.transition()，禁止任何代码绕过。
+ *
+ * 设计参考：docs/02-DATA-MODEL.md §三、docs/03-CORE-MODULES.md §3.2
+ */
+import type { ArtifactType, FSMDefinition, TransitionContext, TransitionResult, GuardFailure } from './types.js';
+import type { IArtifactStore } from './store.js';
+import type { IEventBus } from '../core/eventBus.js';
+export interface IFSM {
+    register(definition: FSMDefinition): void;
+    canTransition(artifactId: string, action: string): Promise<{
+        allowed: boolean;
+        blockedBy?: GuardFailure[];
+    }>;
+    transition(artifactId: string, action: string, context: TransitionContext): Promise<TransitionResult>;
+    availableActions(artifactId: string): Promise<string[]>;
+    getDefinition(type: ArtifactType): FSMDefinition | undefined;
+}
+export declare class FSM implements IFSM {
+    private store;
+    private eventBus;
+    private registry;
+    /** Per-artifact lock chain to prevent concurrent transitions */
+    private locks;
+    constructor(store: IArtifactStore, eventBus: IEventBus);
+    register(definition: FSMDefinition): void;
+    getDefinition(type: ArtifactType): FSMDefinition | undefined;
+    canTransition(artifactId: string, action: string): Promise<{
+        allowed: boolean;
+        blockedBy?: GuardFailure[];
+    }>;
+    transition(artifactId: string, action: string, context: TransitionContext): Promise<TransitionResult>;
+    private executeTransition;
+    /** Number of artifacts with pending lock chains (for testing/monitoring) */
+    get pendingLocks(): number;
+    availableActions(artifactId: string): Promise<string[]>;
+}
+export declare const SpecFSM: FSMDefinition;

package/dist/artifact/fsm.js

@@ -0,0 +1,221 @@
+/**
+ * SCALE Engine — FSM (Finite State Machine) Engine
+ *
+ * 系统的"宪法执行者"。
+ * 所有 Artifact 状态变化必须通过 fsm.transition()，禁止任何代码绕过。
+ *
+ * 设计参考：docs/02-DATA-MODEL.md §三、docs/03-CORE-MODULES.md §3.2
+ */
+import { InvalidTransitionError, ArtifactNotFoundError, } from './types.js';
+import { logger } from '../core/logger.js';
+export class FSM {
+    constructor(store, eventBus) {
+        this.store = store;
+        this.eventBus = eventBus;
+        this.registry = new Map();
+        /** Per-artifact lock chain to prevent concurrent transitions */
+        this.locks = new Map();
+    }
+    register(definition) {
+        if (this.registry.has(definition.type)) {
+            throw new Error(`FSM already registered for type: ${definition.type}`);
+        }
+        this.registry.set(definition.type, definition);
+        logger.debug({ type: definition.type, states: definition.states }, 'FSM registered');
+    }
+    getDefinition(type) {
+        return this.registry.get(type);
+    }
+    async canTransition(artifactId, action) {
+        const artifact = await this.store.get(artifactId);
+        if (!artifact)
+            throw new ArtifactNotFoundError(artifactId);
+        const def = this.registry.get(artifact.type);
+        if (!def)
+            throw new Error(`No FSM registered for type: ${artifact.type}`);
+        const tx = def.transitions.find((t) => t.from === artifact.status && t.action === action);
+        if (!tx)
+            return { allowed: false, blockedBy: [{ guard: 'transition', message: `No transition from '${artifact.status}' via '${action}'` }] };
+        const failures = [];
+        for (const guard of tx.guards ?? []) {
+            try {
+                const passed = await guard.check(artifact, {
+                    actor: { kind: 'system', component: 'FSM.canTransition' },
+                });
+                if (!passed)
+                    failures.push({ guard: guard.name, message: guard.errorMessage });
+            }
+            catch (e) {
+                failures.push({ guard: guard.name, message: `Guard threw: ${e.message}` });
+            }
+        }
+        return { allowed: failures.length === 0, blockedBy: failures.length > 0 ? failures : undefined };
+    }
+    async transition(artifactId, action, context) {
+        // Concurrency lock: serialize transitions per artifact
+        const prev = this.locks.get(artifactId) ?? Promise.resolve();
+        let releaseLock;
+        const acquired = new Promise((resolve) => { releaseLock = resolve; });
+        this.locks.set(artifactId, prev.then(() => acquired));
+        await prev;
+        try {
+            return await this.executeTransition(artifactId, action, context);
+        }
+        finally {
+            releaseLock();
+            // Clean up lock entry if no pending chain
+            if (this.locks.get(artifactId) === prev.then(() => acquired)) {
+                this.locks.delete(artifactId);
+            }
+        }
+    }
+    async executeTransition(artifactId, action, context) {
+        const artifact = await this.store.get(artifactId);
+        if (!artifact)
+            throw new ArtifactNotFoundError(artifactId);
+        const def = this.registry.get(artifact.type);
+        if (!def)
+            throw new Error(`No FSM registered for type: ${artifact.type}`);
+        const tx = def.transitions.find((t) => t.from === artifact.status && t.action === action);
+        if (!tx)
+            throw new InvalidTransitionError(artifact.status, action);
+        // Phase 1: 检查所有 guards
+        const failures = [];
+        for (const guard of tx.guards ?? []) {
+            try {
+                const passed = await guard.check(artifact, context);
+                if (!passed) {
+                    failures.push({ guard: guard.name, message: guard.errorMessage });
+                }
+            }
+            catch (e) {
+                failures.push({
+                    guard: guard.name,
+                    message: `Guard threw: ${e.message}`,
+                });
+            }
+        }
+        if (failures.length > 0) {
+            logger.info({ artifactId, action, failures }, 'Transition blocked by guards');
+            return { success: false, blockedBy: failures, effectsExecuted: [] };
+        }
+        // Phase 2: 写状态历史 + 更新状态（事件先发，后落 DB）
+        const event = this.eventBus.emit('artifact.transitioned', {
+            artifactId,
+            from: artifact.status,
+            to: tx.to,
+            reason: context.reason,
+        }, {
+            sessionId: 'system',
+            actor: context.actor,
+            artifactId,
+        });
+        const updated = await this.store.update(artifactId, {
+            status: tx.to,
+            statusHistory: [
+                ...artifact.statusHistory,
+                {
+                    from: artifact.status,
+                    to: tx.to,
+                    at: Date.now(),
+                    by: context.actor,
+                    reason: context.reason,
+                    eventId: event.id,
+                },
+            ],
+            updatedAt: Date.now(),
+            ...(def.terminal.includes(tx.to) ? { closedAt: Date.now() } : {}),
+        });
+        logger.info({ artifactId, from: artifact.status, to: tx.to, by: context.actor }, 'Transition completed');
+        // Phase 3: 异步执行 effects（不阻塞返回，但记录失败）
+        const effectsExecuted = [];
+        for (const effect of tx.effects ?? []) {
+            try {
+                await effect.run(updated, context);
+                effectsExecuted.push(effect.name);
+            }
+            catch (e) {
+                logger.error({ artifactId, effect: effect.name, error: e.message }, 'Effect execution failed');
+                // Effect 失败不回滚状态迁移（事件已发出，下游可补偿）
+            }
+        }
+        return { success: true, artifact: updated, effectsExecuted };
+    }
+    /** Number of artifacts with pending lock chains (for testing/monitoring) */
+    get pendingLocks() {
+        return this.locks.size;
+    }
+    async availableActions(artifactId) {
+        const artifact = await this.store.get(artifactId);
+        if (!artifact)
+            throw new ArtifactNotFoundError(artifactId);
+        const def = this.registry.get(artifact.type);
+        if (!def)
+            return [];
+        return def.transitions
+            .filter((t) => t.from === artifact.status)
+            .map((t) => t.action);
+    }
+}
+// ============================================================================
+// 内置 FSM 定义（11 种 Artifact）
+// 这些定义在 src/artifact/fsmDefinitions/ 下完整实现
+// 此处只列 Spec 作为示例
+// ============================================================================
+export const SpecFSM = {
+    type: 'Spec',
+    states: ['DRAFT', 'REVIEWING', 'FROZEN', 'REVISING', 'OBSOLETED'],
+    initial: 'DRAFT',
+    terminal: ['OBSOLETED'],
+    transitions: [
+        {
+            from: 'DRAFT',
+            action: 'refine',
+            to: 'REVIEWING',
+        },
+        {
+            from: 'REVIEWING',
+            action: 'reject',
+            to: 'DRAFT',
+        },
+        {
+            from: 'REVIEWING',
+            action: 'approve',
+            to: 'FROZEN',
+            guards: [
+                {
+                    name: 'ambiguity_below_threshold',
+                    check: (a) => {
+                        const payload = a.payload;
+                        return (payload.ambiguityScore ?? 1) <= 0.2;
+                    },
+                    errorMessage: 'Spec 模糊度必须 ≤ 0.2 才能 FROZEN',
+                },
+            ],
+        },
+        {
+            from: 'FROZEN',
+            action: 'challenge',
+            to: 'REVISING',
+            // effects 在运行时由 Engine 注入（避免循环依赖）
+        },
+        {
+            from: 'REVISING',
+            action: 'finalize',
+            to: 'FROZEN',
+        },
+        {
+            from: 'FROZEN',
+            action: 'supersede',
+            to: 'OBSOLETED',
+        },
+    ],
+};
+// 其他 FSM 定义占位（W2 完整实现）
+// export const NeedFSM: FSMDefinition = { ... }
+// export const PlanFSM: FSMDefinition = { ... }
+// export const TaskFSM: FSMDefinition = { ... }
+// export const ChangeFSM: FSMDefinition = { ... }
+// export const DefectFSM: FSMDefinition = { ... }
+// ...
+//# sourceMappingURL=fsm.js.map

package/dist/artifact/fsm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fsm.js","sourceRoot":"","sources":["../../src/artifact/fsm.ts"],"names":[],"mappings":"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"}

package/dist/artifact/fsmDefinitions.d.ts

@@ -0,0 +1,18 @@
+import type { FSMDefinition } from './types.js';
+export declare const NeedFSM: FSMDefinition;
+export declare const InsightFSM: FSMDefinition;
+export declare const SpecFSM: FSMDefinition;
+export declare const PlanFSM: FSMDefinition;
+export declare const TestPlanFSM: FSMDefinition;
+export declare const TaskFSM: FSMDefinition;
+export declare const ChangeFSM: FSMDefinition;
+export declare const EvidenceFSM: FSMDefinition;
+export declare const DefectFSM: FSMDefinition;
+export declare const LessonFSM: FSMDefinition;
+export declare const ReleaseFSM: FSMDefinition;
+export declare const ALL_FSMS: readonly [FSMDefinition<string, string>, FSMDefinition<string, string>, FSMDefinition<string, string>, FSMDefinition<string, string>, FSMDefinition<string, string>, FSMDefinition<string, string>, FSMDefinition<string, string>, FSMDefinition<string, string>, FSMDefinition<string, string>, FSMDefinition<string, string>, FSMDefinition<string, string>];
+import type { IFSM } from './fsm.js';
+import type { ArtifactType } from './types.js';
+export declare function registerAllFSMs(fsm: IFSM): void;
+/** 各 Artifact 类型的初始状态查询表 */
+export declare const INITIAL_STATES: Record<ArtifactType, string>;