@s_s/harmonia 1.2.0 → 1.4.0

package/build/core/reviews.d.ts

@@ -1,26 +1,26 @@
 /**
- * Document review state management — <data_dir>/<project_name>/iter-<n>/reviews.json
+ * Artifact review state management — <context_dir>/reviews.json
  *
- * Tracks which documents are pending review, approved, or rejected.
+ * Tracks which artifacts are pending review, approved, or rejected.
  */
-import type { DocReviewState } from './types.js';
+import type { ReviewState } from './types.js';
 /**
- * Read the reviews state for a project iteration.
+ * Read the reviews state for a project context.
  */
-export declare function readReviews(projectName: string, iteration: number): Promise<Record<string, DocReviewState>>;
+export declare function readReviews(projectName: string, iteration: number, contextDir?: string): Promise<Record<string, ReviewState>>;
 /**
- * Submit a document for review. Sets status to "pending".
+ * Submit an artifact for review. Sets status to "pending".
  */
-export declare function submitForReview(projectName: string, iteration: number, docId: string): Promise<DocReviewState>;
+export declare function submitForReview(projectName: string, iteration: number, artifactId: string, contextDir?: string): Promise<ReviewState>;
 /**
- * Approve or reject a document review.
+ * Approve or reject an artifact review.
  */
-export declare function resolveReview(projectName: string, iteration: number, docId: string, status: 'approved' | 'rejected', comment?: string): Promise<DocReviewState>;
+export declare function resolveReview(projectName: string, iteration: number, artifactId: string, status: 'approved' | 'rejected', comment?: string, contextDir?: string): Promise<ReviewState>;
 /**
- * Get the review state for a specific document.
+ * Get the review state for a specific artifact.
  */
-export declare function getDocReview(projectName: string, iteration: number, docId: string): Promise<DocReviewState | null>;
+export declare function getArtifactReview(projectName: string, iteration: number, artifactId: string, contextDir?: string): Promise<ReviewState | null>;
 /**
- * Get all pending reviews for a project iteration.
+ * Get all pending reviews for a project context.
  */
-export declare function getPendingReviews(projectName: string, iteration: number): Promise<DocReviewState[]>;
+export declare function getPendingReviews(projectName: string, iteration: number, contextDir?: string): Promise<ReviewState[]>;

package/build/core/reviews.js

@@ -1,23 +1,22 @@
 /**
- * Document review state management — <data_dir>/<project_name>/iter-<n>/reviews.json
+ * Artifact review state management — <context_dir>/reviews.json
  *
- * Tracks which documents are pending review, approved, or rejected.
+ * Tracks which artifacts are pending review, approved, or rejected.
  */
 import { readFile, writeFile, mkdir } from 'node:fs/promises';
 import { join, dirname } from 'node:path';
-import { getIterationDir } from './registry.js';
 const REVIEWS_FILE = 'reviews.json';
-function reviewsPath(projectName, iteration) {
-    return join(getIterationDir(projectName, iteration), REVIEWS_FILE);
+function reviewsPath(projectName, iteration, contextDir) {
+    return join(contextDir, REVIEWS_FILE);
 }
 /**
- * Read the reviews state for a project iteration.
+ * Read the reviews state for a project context.
  */
-export async function readReviews(projectName, iteration) {
+export async function readReviews(projectName, iteration, contextDir) {
     try {
-        const content = await readFile(reviewsPath(projectName, iteration), 'utf-8');
+        const content = await readFile(reviewsPath(projectName, iteration, contextDir), 'utf-8');
         const data = JSON.parse(content);
-        return data.docs ?? {};
+        return data.artifacts ?? {};
     }
     catch {
         return {};
@@ -26,58 +25,58 @@ export async function readReviews(projectName, iteration) {
 /**
  * Write reviews state to disk.
  */
-async function writeReviews(projectName, iteration, docs) {
-    const filePath = reviewsPath(projectName, iteration);
+async function writeReviews(projectName, iteration, artifacts, contextDir) {
+    const filePath = reviewsPath(projectName, iteration, contextDir);
     await mkdir(dirname(filePath), { recursive: true });
-    const data = { docs };
+    const data = { artifacts };
     await writeFile(filePath, JSON.stringify(data, null, 2) + '\n', 'utf-8');
 }
 /**
- * Submit a document for review. Sets status to "pending".
+ * Submit an artifact for review. Sets status to "pending".
  */
-export async function submitForReview(projectName, iteration, docId) {
-    const reviews = await readReviews(projectName, iteration);
+export async function submitForReview(projectName, iteration, artifactId, contextDir) {
+    const reviews = await readReviews(projectName, iteration, contextDir);
     const state = {
-        docId,
+        artifactId,
         status: 'pending',
         submittedAt: new Date().toISOString(),
     };
-    reviews[docId] = state;
-    await writeReviews(projectName, iteration, reviews);
+    reviews[artifactId] = state;
+    await writeReviews(projectName, iteration, reviews, contextDir);
     return state;
 }
 /**
- * Approve or reject a document review.
+ * Approve or reject an artifact review.
  */
-export async function resolveReview(projectName, iteration, docId, status, comment) {
-    const reviews = await readReviews(projectName, iteration);
-    const existing = reviews[docId];
+export async function resolveReview(projectName, iteration, artifactId, status, comment, contextDir) {
+    const reviews = await readReviews(projectName, iteration, contextDir);
+    const existing = reviews[artifactId];
     if (!existing) {
-        throw new Error(`No review pending for document "${docId}". Submit it for review first.`);
+        throw new Error(`No review pending for artifact "${artifactId}". Submit it for review first.`);
     }
     if (existing.status !== 'pending') {
-        throw new Error(`Document "${docId}" review is already ${existing.status}.`);
+        throw new Error(`Artifact "${artifactId}" review is already ${existing.status}.`);
     }
     existing.status = status;
     existing.reviewedAt = new Date().toISOString();
     if (comment) {
         existing.comment = comment;
     }
-    await writeReviews(projectName, iteration, reviews);
+    await writeReviews(projectName, iteration, reviews, contextDir);
     return existing;
 }
 /**
- * Get the review state for a specific document.
+ * Get the review state for a specific artifact.
  */
-export async function getDocReview(projectName, iteration, docId) {
-    const reviews = await readReviews(projectName, iteration);
-    return reviews[docId] ?? null;
+export async function getArtifactReview(projectName, iteration, artifactId, contextDir) {
+    const reviews = await readReviews(projectName, iteration, contextDir);
+    return reviews[artifactId] ?? null;
 }
 /**
- * Get all pending reviews for a project iteration.
+ * Get all pending reviews for a project context.
  */
-export async function getPendingReviews(projectName, iteration) {
-    const reviews = await readReviews(projectName, iteration);
+export async function getPendingReviews(projectName, iteration, contextDir) {
+    const reviews = await readReviews(projectName, iteration, contextDir);
     return Object.values(reviews).filter((r) => r.status === 'pending');
 }
 //# sourceMappingURL=reviews.js.map

package/build/core/reviews.js.map

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

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,36 +1,43 @@
 /**
- * Project state management — manages <data_dir>/<project_name>/iter-<n>/state.json
+ * Workflow state management — manages state.json within iteration/patch directories.
+ *
+ * Rewritten for the new node-based architecture. State now tracks individual
+ * workflow nodes instead of linear phases.
  */
-import type { 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.
+ * Initialize a new workflow state file.
+ *
+ * Creates initial NodeState records for all nodes in the workflow definition.
+ * All nodes start as 'pending'.
+ *
+ * @param contextDir - Directory containing state.json
  */
-export declare class ScaleNotSetError extends Error {
-    constructor(projectName: string);
-}
+export declare function initWorkflowState(projectName: string, projectDir: string, workflow: WorkflowPlugin, iteration: number, type?: ContextType, contextDir?: string): Promise<WorkflowState>;
 /**
- * Initialize a new project state file for a specific iteration.
- * Note: directory creation is handled by registry.startIteration().
- * This only writes the state.json.
+ * Read the current workflow state.
  */
-export declare function initProjectState(projectName: string, projectDir: string, workflow: LoadedWorkflow, iteration: number): Promise<ProjectState>;
+export declare function readState(projectName: string, iteration: number, contextDir?: string): Promise<WorkflowState>;
 /**
- * Read the current project state for a specific iteration.
+ * Write workflow state to disk.
  */
-export declare function readState(projectName: string, iteration: number): Promise<ProjectState>;
+export declare function writeState(projectName: string, iteration: number, state: WorkflowState, contextDir?: string): Promise<void>;
 /**
- * Write project state to disk for a specific iteration.
+ * Update a specific node's state. Reads current state, applies the partial update,
+ * and writes back.
+ *
+ * @returns The updated full WorkflowState
  */
-export declare function writeState(projectName: string, iteration: number, state: ProjectState): Promise<void>;
+export declare function updateNodeState(projectName: string, iteration: number, nodeId: string, update: Partial<NodeState>, contextDir?: string): Promise<WorkflowState>;
 /**
- * Update a specific phase's status.
+ * 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 updatePhaseStatus(projectName: string, iteration: number, phaseId: string, status: PhaseStatus, blockedReason?: string): Promise<ProjectState>;
+export declare function persistState(projectName: string, iteration: number, state: WorkflowState, contextDir?: string): Promise<void>;
 /**
- * Check if a project state file exists for a specific iteration.
+ * Check if a workflow state file exists.
  */
-export declare function projectStateExists(projectName: string, iteration: number): Promise<boolean>;
-/**
- * Set the project scale. Scale is immutable once set.
- */
-export declare function setScale(projectName: string, iteration: number, scale: ProjectScale): Promise<ProjectState>;
+export declare function stateExists(projectName: string, iteration: number, contextDir?: string): Promise<boolean>;