@s_s/harmonia 1.3.0 → 1.4.0

package/build/core/schema.d.ts

@@ -1,18 +1,18 @@
 /**
- * Document schema loader and validator.
+ * Artifact schema loader and validator.
  *
  * Loads schema definitions from the resolved workflow directory's schemas/ subdirectory
- * and validates document content against them before writing.
+ * and validates artifact content against them before writing.
  */
-import type { DocSchema, ProjectScale } from './types.js';
+import type { ArtifactSchema } from './types.js';
 /**
- * Load a document schema from the workflow's schemas directory.
- * Returns undefined if no schema file exists for this doc_id.
+ * Load an artifact schema from the workflow's schemas directory.
+ * Returns undefined if no schema file exists for this artifact_id.
  *
  * For step schemas, pass a composite id like "prd.requirements".
  */
-export declare function loadDocSchema(builtinDir: string, customDir: string, workflowName: string, docId: string): Promise<DocSchema | undefined>;
-export interface ValidationError {
+export declare function loadArtifactSchema(workflowsDir: string, workflowName: string, artifactId: string): Promise<ArtifactSchema | undefined>;
+export interface ArtifactValidationError {
     /** Error type */
     type: 'missing_section' | 'missing_html_tag' | 'content_too_short' | 'empty_content' | 'missing_json_field' | 'invalid_json' | 'wrong_json_type' | 'json_array_too_short';
     /** Human-readable message */
@@ -20,19 +20,47 @@ export interface ValidationError {
 }
 export interface ValidationResult {
     valid: boolean;
-    errors: ValidationError[];
+    errors: ArtifactValidationError[];
 }
 /**
- * Validate document content against a schema.
+ * Validate artifact content against a schema.
  *
- * @param content  - Document content (markdown, HTML, or JSON)
+ * @param content  - Artifact content (markdown, HTML, or JSON)
  * @param schema   - Schema definition
- * @param scale    - Project scale (affects which sections are required). When null, scale-dependent checks are skipped.
- * @param isHtml   - Whether the document is HTML format
- * @param isJson   - Whether the document is JSON format (for step artifacts)
+ * @param isHtml   - Whether the artifact is HTML format
+ * @param isJson   - Whether the artifact is JSON format (for step artifacts)
  */
-export declare function validateDoc(content: string, schema: DocSchema, scale: ProjectScale | null, isHtml?: boolean, isJson?: boolean): ValidationResult;
+export declare function validateArtifact(content: string, schema: ArtifactSchema, isHtml?: boolean, isJson?: boolean): ValidationResult;
+/**
+ * Step schema entry for formatSchemaGuidance.
+ * Each entry pairs a step definition with its loaded schema (if any).
+ */
+export interface StepSchemaEntry {
+    step: {
+        id: string;
+        name: string;
+        format: 'json' | 'md';
+        description: string;
+    };
+    schema: ArtifactSchema | undefined;
+}
+/**
+ * Format an artifact schema into human-readable writing guidance.
+ *
+ * Used by:
+ * - role_dispatch: inject Artifact Requirements into the dispatch data package
+ * - artifact_schema tool: return guidance on demand for coordinator
+ *
+ * @param artifactId    Artifact ID (e.g. "prd", "tech-design")
+ * @param artifactDef   Artifact definition from workflow.json
+ * @param schema        Main artifact schema (may be undefined if no schema file exists)
+ * @param stepSchemas   Step schemas (only relevant when artifact has steps)
+ */
+export declare function formatSchemaGuidance(artifactId: string, artifactDef: {
+    name: string;
+    format?: 'md' | 'html' | 'json';
+}, schema: ArtifactSchema | undefined, stepSchemas?: StepSchemaEntry[]): string;
 /**
  * Format validation errors into a human-readable string for tool response.
  */
-export declare function formatValidationErrors(errors: ValidationError[]): string;
+export declare function formatValidationErrors(errors: ArtifactValidationError[]): string;

package/build/core/schema.js

@@ -1,22 +1,22 @@
 /**
- * Document schema loader and validator.
+ * Artifact schema loader and validator.
  *
  * Loads schema definitions from the resolved workflow directory's schemas/ subdirectory
- * and validates document content against them before writing.
+ * and validates artifact content against them before writing.
  */
 import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
-import { resolveWorkflowDir } from './workflow.js';
+import { resolveWorkflowDir } from './plugin.js';
 // ─── Schema Loading ───
 /**
- * Load a document schema from the workflow's schemas directory.
- * Returns undefined if no schema file exists for this doc_id.
+ * Load an artifact schema from the workflow's schemas directory.
+ * Returns undefined if no schema file exists for this artifact_id.
  *
  * For step schemas, pass a composite id like "prd.requirements".
  */
-export async function loadDocSchema(builtinDir, customDir, workflowName, docId) {
-    const workflowDir = await resolveWorkflowDir(builtinDir, customDir, workflowName);
-    const schemaPath = join(workflowDir, 'schemas', `${docId}.json`);
+export async function loadArtifactSchema(workflowsDir, workflowName, artifactId) {
+    const workflowDir = await resolveWorkflowDir(workflowsDir, workflowName);
+    const schemaPath = join(workflowDir, 'schemas', `${artifactId}.json`);
     try {
         const raw = await readFile(schemaPath, 'utf-8');
         return JSON.parse(raw);
@@ -69,15 +69,14 @@ function sectionPresent(section, headings) {
     return false;
 }
 /**
- * Validate document content against a schema.
+ * Validate artifact content against a schema.
  *
- * @param content  - Document content (markdown, HTML, or JSON)
+ * @param content  - Artifact content (markdown, HTML, or JSON)
  * @param schema   - Schema definition
- * @param scale    - Project scale (affects which sections are required). When null, scale-dependent checks are skipped.
- * @param isHtml   - Whether the document is HTML format
- * @param isJson   - Whether the document is JSON format (for step artifacts)
+ * @param isHtml   - Whether the artifact is HTML format
+ * @param isJson   - Whether the artifact is JSON format (for step artifacts)
  */
-export function validateDoc(content, schema, scale, isHtml = false, isJson = false) {
+export function validateArtifact(content, schema, isHtml = false, isJson = false) {
     const errors = [];
     // Empty content check
     const trimmed = content.trim();
@@ -98,9 +97,7 @@ export function validateDoc(content, schema, scale, isHtml = false, isJson = fal
     if (schema.sections && !isHtml && !isJson) {
         const headings = extractHeadings(content);
         for (const section of schema.sections) {
-            // When scale is null, skip scale-dependent section requirements
-            const isRequired = scale !== null ? section.required[scale] : false;
-            if (isRequired && !sectionPresent(section, headings)) {
+            if (section.required && !sectionPresent(section, headings)) {
                 const aliasList = section.aliases?.length ? `（或: ${section.aliases.join(', ')}）` : '';
                 errors.push({
                     type: 'missing_section',
@@ -136,9 +133,7 @@ export function validateDoc(content, schema, scale, isHtml = false, isJson = fal
         }
         if (parsed) {
             for (const fieldDef of schema.jsonFields) {
-                // When scale is null, skip scale-dependent field requirements
-                const isRequired = scale !== null ? fieldDef.required[scale] : false;
-                if (!isRequired)
+                if (!fieldDef.required)
                     continue;
                 const value = parsed[fieldDef.field];
                 if (value === undefined || value === null) {
@@ -174,6 +169,115 @@ export function validateDoc(content, schema, scale, isHtml = false, isJson = fal
         errors,
     };
 }
+/**
+ * Format an artifact schema into human-readable writing guidance.
+ *
+ * Used by:
+ * - role_dispatch: inject Artifact Requirements into the dispatch data package
+ * - artifact_schema tool: return guidance on demand for coordinator
+ *
+ * @param artifactId    Artifact ID (e.g. "prd", "tech-design")
+ * @param artifactDef   Artifact definition from workflow.json
+ * @param schema        Main artifact schema (may be undefined if no schema file exists)
+ * @param stepSchemas   Step schemas (only relevant when artifact has steps)
+ */
+export function formatSchemaGuidance(artifactId, artifactDef, schema, stepSchemas) {
+    const lines = [];
+    lines.push(`## 文档要求: ${artifactDef.name} (${artifactId})`);
+    lines.push('');
+    // Format
+    const format = artifactDef.format === 'html' ? 'HTML' : artifactDef.format === 'json' ? 'JSON' : 'Markdown';
+    lines.push(`格式: ${format}`);
+    // Min length
+    if (schema?.minLength) {
+        lines.push(`最小长度: ${schema.minLength} 字符`);
+    }
+    // Guidance
+    if (schema?.guidance) {
+        lines.push(`内容指引: ${schema.guidance}`);
+    }
+    // Required sections (markdown docs)
+    if (schema?.sections) {
+        const required = schema.sections.filter((s) => s.required);
+        if (required.length > 0) {
+            lines.push('');
+            lines.push('### 必需章节');
+            for (const section of required) {
+                // Strip leading ## from heading for display
+                const heading = section.heading.replace(/^#+\s*/, '');
+                lines.push(`- ${heading}`);
+            }
+        }
+    }
+    // Required HTML tags
+    if (schema?.htmlTags && schema.htmlTags.length > 0) {
+        lines.push('');
+        lines.push('### 必需 HTML 标签');
+        for (const tag of schema.htmlTags) {
+            lines.push(`- <${tag}>`);
+        }
+    }
+    // Required JSON fields (for top-level JSON docs without steps)
+    if (schema?.jsonFields) {
+        const required = schema.jsonFields.filter((f) => f.required);
+        if (required.length > 0) {
+            lines.push('');
+            lines.push('### 必需 JSON 字段');
+            for (const field of required) {
+                let desc = `- ${field.field}`;
+                if (field.type)
+                    desc += ` (${field.type})`;
+                if (field.minItems)
+                    desc += `, ≥${field.minItems} 项`;
+                lines.push(desc);
+            }
+        }
+    }
+    // Step schemas
+    if (stepSchemas && stepSchemas.length > 0) {
+        lines.push('');
+        lines.push('### 分步写入');
+        for (let i = 0; i < stepSchemas.length; i++) {
+            const { step, schema: stepSchema } = stepSchemas[i];
+            const formatLabel = step.format === 'json' ? 'JSON 格式' : 'Markdown 格式';
+            lines.push(`${i + 1}. ${step.id}（${step.name}）— ${formatLabel}`);
+            if (stepSchema) {
+                // Step-level required JSON fields
+                if (stepSchema.jsonFields) {
+                    const reqFields = stepSchema.jsonFields.filter((f) => f.required);
+                    if (reqFields.length > 0) {
+                        const fieldDescs = reqFields.map((f) => {
+                            let d = f.field;
+                            if (f.type)
+                                d += ` (${f.type})`;
+                            if (f.minItems)
+                                d += `, ≥${f.minItems} 项`;
+                            return d;
+                        });
+                        lines.push(`   必需字段: ${fieldDescs.join(', ')}`);
+                    }
+                }
+                // Step-level required sections
+                if (stepSchema.sections) {
+                    const reqSections = stepSchema.sections.filter((s) => s.required);
+                    if (reqSections.length > 0) {
+                        const sectionNames = reqSections.map((s) => s.heading.replace(/^#+\s*/, ''));
+                        lines.push(`   必需章节: ${sectionNames.join(', ')}`);
+                    }
+                }
+                // Step-level min length
+                if (stepSchema.minLength) {
+                    lines.push(`   最小长度: ${stepSchema.minLength} 字符`);
+                }
+                // Step-level guidance
+                if (stepSchema.guidance) {
+                    lines.push(`   指引: ${stepSchema.guidance}`);
+                }
+            }
+        }
+    }
+    return lines.join('\n');
+}
 /**
  * Format validation errors into a human-readable string for tool response.
  */

package/build/core/schema.js.map

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

package/build/core/state.d.ts

@@ -1,44 +1,43 @@
 /**
- * Project state management — manages state.json within iteration/patch directories.
+ * Workflow state management — manages state.json within iteration/patch directories.
  *
- * All functions accept an optional `contextDir` parameter. When provided, it is used
- * directly as the directory containing state.json. When omitted, the directory is
- * resolved from `getIterationDir(projectName, iteration)` for backward compatibility.
+ * Rewritten for the new node-based architecture. State now tracks individual
+ * workflow nodes instead of linear phases.
  */
-import type { ContextType, PhaseStatus, ProjectScale, ProjectState, LoadedWorkflow } from './types.js';
+import type { ContextType, WorkflowState, WorkflowPlugin, NodeState } from './types.js';
 /**
- * Error thrown when a tool requires scale but it hasn't been set yet.
- */
-export declare class ScaleNotSetError extends Error {
-    constructor(projectName: string);
-}
-/**
- * Initialize a new project state file.
+ * Initialize a new workflow state file.
  *
- * For iteration mode (default): all phases start normally (first = in_progress, rest = pending).
- * For patch mode: clarify/design are marked as "skipped", first non-skipped phase is in_progress,
- * scale is set to "small" automatically.
+ * Creates initial NodeState records for all nodes in the workflow definition.
+ * All nodes start as 'pending'.
  *
- * @param contextDir - Optional explicit directory. If omitted, uses getIterationDir().
+ * @param contextDir - Directory containing state.json
  */
-export declare function initProjectState(projectName: string, projectDir: string, workflow: LoadedWorkflow, iteration: number, type?: ContextType, contextDir?: string): Promise<ProjectState>;
+export declare function initWorkflowState(projectName: string, projectDir: string, workflow: WorkflowPlugin, iteration: number, type?: ContextType, contextDir?: string): Promise<WorkflowState>;
 /**
- * Read the current project state.
+ * Read the current workflow state.
  */
-export declare function readState(projectName: string, iteration: number, contextDir?: string): Promise<ProjectState>;
+export declare function readState(projectName: string, iteration: number, contextDir?: string): Promise<WorkflowState>;
 /**
- * Write project state to disk.
+ * Write workflow state to disk.
  */
-export declare function writeState(projectName: string, iteration: number, state: ProjectState, contextDir?: string): Promise<void>;
+export declare function writeState(projectName: string, iteration: number, state: WorkflowState, contextDir?: string): Promise<void>;
 /**
- * Update a specific phase's status.
+ * Update a specific node's state. Reads current state, applies the partial update,
+ * and writes back.
+ *
+ * @returns The updated full WorkflowState
  */
-export declare function updatePhaseStatus(projectName: string, iteration: number, phaseId: string, status: PhaseStatus, blockedReason?: string, contextDir?: string): Promise<ProjectState>;
+export declare function updateNodeState(projectName: string, iteration: number, nodeId: string, update: Partial<NodeState>, contextDir?: string): Promise<WorkflowState>;
 /**
- * Check if a project state file exists.
+ * Persist engine-computed state changes. After the workflow engine computes
+ * a new state (via computeNextAction or startWorkflow), call this to persist it.
+ *
+ * This is the preferred way to save state changes from the engine,
+ * as it replaces the entire state atomically.
  */
-export declare function projectStateExists(projectName: string, iteration: number, contextDir?: string): Promise<boolean>;
+export declare function persistState(projectName: string, iteration: number, state: WorkflowState, contextDir?: string): Promise<void>;
 /**
- * Set the project scale. Scale is immutable once set.
+ * Check if a workflow state file exists.
  */
-export declare function setScale(projectName: string, iteration: number, scale: ProjectScale, contextDir?: string): Promise<ProjectState>;
+export declare function stateExists(projectName: string, iteration: number, contextDir?: string): Promise<boolean>;

package/build/core/state.js

@@ -1,64 +1,35 @@
 /**
- * Project state management — manages state.json within iteration/patch directories.
+ * Workflow state management — manages state.json within iteration/patch directories.
  *
- * All functions accept an optional `contextDir` parameter. When provided, it is used
- * directly as the directory containing state.json. When omitted, the directory is
- * resolved from `getIterationDir(projectName, iteration)` for backward compatibility.
+ * Rewritten for the new node-based architecture. State now tracks individual
+ * workflow nodes instead of linear phases.
  */
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import { join, dirname } from 'node:path';
-import { getIterationDir } from './registry.js';
-/**
- * Error thrown when a tool requires scale but it hasn't been set yet.
- */
-export class ScaleNotSetError extends Error {
-    constructor(projectName) {
-        super(`项目 "${projectName}" 尚未设定 scale。请先完成 PRD 审批，然后调用 project_set_scale 设定项目规模。`);
-        this.name = 'ScaleNotSetError';
-    }
-}
+import { initNodeStates } from './workflow-engine.js';
 const STATE_FILE = 'state.json';
-function resolveDir(projectName, iteration, contextDir) {
-    return contextDir ?? getIterationDir(projectName, iteration);
-}
 function statePath(projectName, iteration, contextDir) {
-    return join(resolveDir(projectName, iteration, contextDir), STATE_FILE);
+    return join(contextDir, STATE_FILE);
 }
-/** Phases to skip in patch mode (clarify and design) */
-const PATCH_SKIP_PHASES = new Set(['clarify', 'design']);
 /**
- * Initialize a new project state file.
+ * Initialize a new workflow state file.
  *
- * For iteration mode (default): all phases start normally (first = in_progress, rest = pending).
- * For patch mode: clarify/design are marked as "skipped", first non-skipped phase is in_progress,
- * scale is set to "small" automatically.
+ * Creates initial NodeState records for all nodes in the workflow definition.
+ * All nodes start as 'pending'.
  *
- * @param contextDir - Optional explicit directory. If omitted, uses getIterationDir().
+ * @param contextDir - Directory containing state.json
  */
-export async function initProjectState(projectName, projectDir, workflow, iteration, type = 'iteration', contextDir) {
+export async function initWorkflowState(projectName, projectDir, workflow, iteration, type = 'iteration', contextDir) {
     const now = new Date().toISOString();
-    const phases = workflow.definition.phases;
-    const isPatch = type === 'patch';
-    // Find the first non-skipped phase
-    const firstActiveIndex = isPatch ? phases.findIndex((p) => !PATCH_SKIP_PHASES.has(p.id)) : 0;
-    const firstPhaseId = phases[firstActiveIndex]?.id ?? phases[0]?.id ?? '';
+    const nodes = initNodeStates(workflow.definition);
     const state = {
         projectName,
         projectDir,
         workflow: workflow.definition.name,
         type,
         iteration,
-        scale: isPatch ? 'small' : null,
-        currentPhase: firstPhaseId,
-        phases: phases.map((p, i) => {
-            if (isPatch && PATCH_SKIP_PHASES.has(p.id)) {
-                return { id: p.id, status: 'skipped' };
-            }
-            if (i === firstActiveIndex) {
-                return { id: p.id, status: 'in_progress', startedAt: now };
-            }
-            return { id: p.id, status: 'pending' };
-        }),
+        activeNodeId: null,
+        nodes,
         createdAt: now,
         updatedAt: now,
     };
@@ -66,14 +37,14 @@ export async function initProjectState(projectName, projectDir, workflow, iterat
     return state;
 }
 /**
- * Read the current project state.
+ * Read the current workflow state.
  */
 export async function readState(projectName, iteration, contextDir) {
     const content = await readFile(statePath(projectName, iteration, contextDir), 'utf-8');
     return JSON.parse(content);
 }
 /**
- * Write project state to disk.
+ * Write workflow state to disk.
  */
 export async function writeState(projectName, iteration, state, contextDir) {
     const filePath = statePath(projectName, iteration, contextDir);
@@ -82,48 +53,35 @@ export async function writeState(projectName, iteration, state, contextDir) {
     await writeFile(filePath, JSON.stringify(state, null, 2) + '\n', 'utf-8');
 }
 /**
- * Update a specific phase's status.
+ * Update a specific node's state. Reads current state, applies the partial update,
+ * and writes back.
+ *
+ * @returns The updated full WorkflowState
  */
-export async function updatePhaseStatus(projectName, iteration, phaseId, status, blockedReason, contextDir) {
+export async function updateNodeState(projectName, iteration, nodeId, update, contextDir) {
     const state = await readState(projectName, iteration, contextDir);
-    const phase = state.phases.find((p) => p.id === phaseId);
-    if (!phase) {
-        throw new Error(`Phase "${phaseId}" not found in project state`);
-    }
-    const now = new Date().toISOString();
-    phase.status = status;
-    if (status === 'in_progress' && !phase.startedAt) {
-        phase.startedAt = now;
-    }
-    if (status === 'completed') {
-        phase.completedAt = now;
-        delete phase.blockedReason;
-    }
-    if (status === 'blocked' && blockedReason) {
-        phase.blockedReason = blockedReason;
-    }
-    // If advancing to in_progress, update currentPhase
-    if (status === 'in_progress') {
-        state.currentPhase = phaseId;
-    }
-    // If completing a phase, auto-advance currentPhase to the next pending one
-    // (skip over phases that are already "skipped")
-    if (status === 'completed') {
-        const idx = state.phases.findIndex((p) => p.id === phaseId);
-        const next = state.phases.find((p, i) => i > idx && p.status === 'pending');
-        if (next) {
-            next.status = 'in_progress';
-            next.startedAt = now;
-            state.currentPhase = next.id;
-        }
+    const existing = state.nodes[nodeId];
+    if (!existing) {
+        throw new Error(`Node "${nodeId}" not found in workflow state for project "${projectName}"`);
     }
+    state.nodes[nodeId] = { ...existing, ...update };
     await writeState(projectName, iteration, state, contextDir);
     return state;
 }
 /**
- * Check if a project state file exists.
+ * Persist engine-computed state changes. After the workflow engine computes
+ * a new state (via computeNextAction or startWorkflow), call this to persist it.
+ *
+ * This is the preferred way to save state changes from the engine,
+ * as it replaces the entire state atomically.
+ */
+export async function persistState(projectName, iteration, state, contextDir) {
+    await writeState(projectName, iteration, state, contextDir);
+}
+/**
+ * Check if a workflow state file exists.
  */
-export async function projectStateExists(projectName, iteration, contextDir) {
+export async function stateExists(projectName, iteration, contextDir) {
     try {
         await readFile(statePath(projectName, iteration, contextDir), 'utf-8');
         return true;
@@ -132,16 +90,4 @@ export async function projectStateExists(projectName, iteration, contextDir) {
         return false;
     }
 }
-/**
- * Set the project scale. Scale is immutable once set.
- */
-export async function setScale(projectName, iteration, scale, contextDir) {
-    const state = await readState(projectName, iteration, contextDir);
-    if (state.scale !== null) {
-        throw new Error(`Scale 已设定为 "${state.scale}"，不可更改。如需调整规模，请重新评估 PRD。`);
-    }
-    state.scale = scale;
-    await writeState(projectName, iteration, state, contextDir);
-    return state;
-}
 //# sourceMappingURL=state.js.map

package/build/core/state.js.map

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

package/build/core/steps.d.ts

@@ -1,35 +1,34 @@
 /**
  * Step state management — manages <context_dir>/steps.json
  *
- * Tracks which sequential steps have been completed for each document,
+ * Tracks which sequential steps have been completed for each artifact,
  * supporting the P3 Sequential mode feature.
- * All public functions accept an optional contextDir parameter.
  */
-import type { DocStepState } from './types.js';
+import type { ArtifactStepState } from './types.js';
 /**
  * Read the steps state for a project context.
  */
-export declare function readSteps(projectName: string, iteration: number, contextDir?: string): Promise<Record<string, DocStepState>>;
+export declare function readSteps(projectName: string, iteration: number, contextDir?: string): Promise<Record<string, ArtifactStepState>>;
 /**
- * Get the step state for a specific document.
+ * Get the step state for a specific artifact.
  */
-export declare function getDocStepState(projectName: string, iteration: number, docId: string, contextDir?: string): Promise<DocStepState | null>;
+export declare function getArtifactStepState(projectName: string, iteration: number, artifactId: string, contextDir?: string): Promise<ArtifactStepState | null>;
 /**
- * Get the set of completed step IDs for a document.
+ * Get the set of completed step IDs for an artifact.
  */
-export declare function getCompletedStepIds(state: DocStepState | null): Set<string>;
+export declare function getCompletedStepIds(state: ArtifactStepState | null): Set<string>;
 /**
  * Record a step as completed. If the step was already completed,
  * it is overwritten and all subsequent steps are cleared (rollback).
  *
- * @returns The updated DocStepState
+ * @returns The updated ArtifactStepState
  */
-export declare function recordStepCompletion(projectName: string, iteration: number, docId: string, stepId: string, artifactPath: string, allStepIds: string[], contextDir?: string): Promise<DocStepState>;
+export declare function recordStepCompletion(projectName: string, iteration: number, artifactId: string, stepId: string, artifactPath: string, allStepIds: string[], contextDir?: string): Promise<ArtifactStepState>;
 /**
- * Mark a document as finalized (all steps completed + final doc written).
+ * Mark an artifact as finalized (all steps completed + final artifact written).
  */
-export declare function markFinalized(projectName: string, iteration: number, docId: string, contextDir?: string): Promise<DocStepState>;
+export declare function markFinalized(projectName: string, iteration: number, artifactId: string, contextDir?: string): Promise<ArtifactStepState>;
 /**
- * Check if a document's sequential process is finalized.
+ * Check if an artifact's sequential process is finalized.
  */
-export declare function isDocFinalized(projectName: string, iteration: number, docId: string, contextDir?: string): Promise<boolean>;
+export declare function isArtifactFinalized(projectName: string, iteration: number, artifactId: string, contextDir?: string): Promise<boolean>;