@gordon.gan/specflow 1.0.0

package/dist/cli/commands/validate.js

@@ -0,0 +1,46 @@
+/**
+ * CLI command: specflow validate <file>
+ *
+ * Validates a spec file for structural correctness.
+ */
+import { promises as fs } from 'node:fs';
+import { validateSpec } from '../../core/validation/validator.js';
+/**
+ * Validates a spec file at the given path.
+ *
+ * Reads the file and runs the spec validator, returning structured results.
+ *
+ * @param filePath - Absolute path to the spec file
+ * @returns Validation result with valid flag and any errors
+ * @throws When the file cannot be read
+ */
+export async function validateSpecFile(filePath) {
+    const content = await fs.readFile(filePath, 'utf-8');
+    return validateSpec(content);
+}
+/**
+ * Registers the `validate` command with Commander.
+ */
+export function registerValidateCommand(program) {
+    program
+        .command('validate <file>')
+        .description('Validate a spec file for structural correctness')
+        .option('--json', 'Output as JSON')
+        .action(async (file, opts) => {
+        const result = await validateSpecFile(file);
+        if (opts.json) {
+            console.info(JSON.stringify(result, null, 2));
+        }
+        else if (result.valid) {
+            console.info('Valid: no errors found.');
+        }
+        else {
+            console.error(`Found ${result.errors.length} error(s):`);
+            for (const err of result.errors) {
+                const lineInfo = err.line ? ` (line ${err.line})` : '';
+                console.error(`  - ${err.message}${lineInfo}`);
+            }
+            process.exitCode = 1;
+        }
+    });
+}

package/dist/cli/index.d.ts

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

package/dist/cli/index.js

@@ -0,0 +1,52 @@
+import { Command } from 'commander';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { registerChangeNewCommand } from './commands/change-new.js';
+import { registerChangeStatusCommand } from './commands/change-status.js';
+import { registerChangeArchiveCommand } from './commands/change-archive.js';
+import { registerChangePhaseCommand } from './commands/change-phase.js';
+import { registerInstructionsCommand } from './commands/instructions.js';
+import { registerValidateCommand } from './commands/validate.js';
+import { registerInitCommand } from './commands/init.js';
+import { registerSyncCommand } from './commands/sync.js';
+import { registerDoctorCommand } from './commands/doctor.js';
+import { registerParityReportCommand } from './commands/parity-report.js';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const pkg = JSON.parse(readFileSync(join(__dirname, '../../package.json'), 'utf-8'));
+const program = new Command();
+program
+    .name('specflow')
+    .description('Unified spec-driven development: OpenSpec planning + Superpowers execution')
+    .version(pkg.version);
+// Group command: specflow change <new|status|archive>
+const changeCmd = program
+    .command('change')
+    .description('Manage changes (new, status, archive)');
+registerChangeNewCommand(changeCmd);
+registerChangeStatusCommand(changeCmd);
+registerChangeArchiveCommand(changeCmd);
+registerChangePhaseCommand(changeCmd);
+// Top-level commands
+registerInstructionsCommand(program);
+registerValidateCommand(program);
+registerInitCommand(program);
+registerSyncCommand(program);
+registerDoctorCommand(program);
+registerParityReportCommand(program);
+program.exitOverride();
+try {
+    await program.parseAsync();
+}
+catch (error) {
+    if (error instanceof Error && 'code' in error) {
+        const code = error.code;
+        if (code === 'commander.helpDisplayed' || code === 'commander.version') {
+            process.exit(0);
+        }
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`错误: ${message}`);
+    process.exit(1);
+}

package/dist/core/archive.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Archive module.
+ *
+ * Archives a completed change by:
+ * 1. Validating all delta specs in the change
+ * 2. Applying deltas to their corresponding main specs
+ * 3. Moving the change directory to the archive
+ */
+export interface ArchiveResult {
+    readonly success: boolean;
+    readonly errors: readonly string[];
+    readonly archivePath?: string;
+}
+export interface ArchiveOptions {
+    /**
+     * If true, archive even when the change is not in phase=built.
+     * A warning is emitted to stderr when force is applied.
+     */
+    readonly force?: boolean;
+}
+/**
+ * Archive a completed change.
+ *
+ * Steps:
+ * 0. Validate phase gate: require phase=built unless options.force is true
+ * 1. Find all delta spec files in `specflow/changes/<name>/specs/`
+ * 2. Validate each delta spec
+ * 3. For each delta spec, find the corresponding main spec in `specflow/specs/`
+ * 4. Apply deltas to main specs
+ * 5. Move the change directory to `specflow/changes/archive/<date>-<name>/`
+ * 6. Update archived .specflow.yaml with phase=archived
+ * 7. Return success/failure with details
+ *
+ * @param changeName - The name of the change to archive
+ * @param projectRoot - Absolute path to the project root
+ * @param options - Optional archive options (e.g. force)
+ * @returns An ArchiveResult with success flag, errors, and archive path
+ */
+export declare function archiveChange(changeName: string, projectRoot: string, options?: ArchiveOptions): Promise<ArchiveResult>;

package/dist/core/archive.js

@@ -0,0 +1,154 @@
+/**
+ * Archive module.
+ *
+ * Archives a completed change by:
+ * 1. Validating all delta specs in the change
+ * 2. Applying deltas to their corresponding main specs
+ * 3. Moving the change directory to the archive
+ */
+import { promises as fs } from 'node:fs';
+import { join, relative } from 'node:path';
+import { validateSpec } from './validation/validator.js';
+import { applyDeltaSpec } from './specs-apply.js';
+import { readChangeMetadata, writeChangeMetadata, } from '../utils/change-metadata.js';
+/**
+ * Recursively list all `.md` files in a directory, returning paths relative to the base dir.
+ */
+async function listMarkdownFiles(dir, base) {
+    const root = base ?? dir;
+    try {
+        const entries = await fs.readdir(dir, { withFileTypes: true });
+        const results = [];
+        for (const entry of entries) {
+            const fullPath = join(dir, entry.name);
+            if (entry.isDirectory()) {
+                const nested = await listMarkdownFiles(fullPath, root);
+                results.push(...nested);
+            }
+            else if (entry.isFile() && entry.name.endsWith('.md')) {
+                results.push(relative(root, fullPath));
+            }
+        }
+        return results;
+    }
+    catch (error) {
+        if (error instanceof Error &&
+            'code' in error &&
+            error.code === 'ENOENT') {
+            return [];
+        }
+        throw error;
+    }
+}
+/**
+ * Get today's date as YYYY-MM-DD string.
+ */
+function todayDatePrefix() {
+    const now = new Date();
+    const year = now.getFullYear();
+    const month = String(now.getMonth() + 1).padStart(2, '0');
+    const day = String(now.getDate()).padStart(2, '0');
+    return `${year}-${month}-${day}`;
+}
+/**
+ * Archive a completed change.
+ *
+ * Steps:
+ * 0. Validate phase gate: require phase=built unless options.force is true
+ * 1. Find all delta spec files in `specflow/changes/<name>/specs/`
+ * 2. Validate each delta spec
+ * 3. For each delta spec, find the corresponding main spec in `specflow/specs/`
+ * 4. Apply deltas to main specs
+ * 5. Move the change directory to `specflow/changes/archive/<date>-<name>/`
+ * 6. Update archived .specflow.yaml with phase=archived
+ * 7. Return success/failure with details
+ *
+ * @param changeName - The name of the change to archive
+ * @param projectRoot - Absolute path to the project root
+ * @param options - Optional archive options (e.g. force)
+ * @returns An ArchiveResult with success flag, errors, and archive path
+ */
+export async function archiveChange(changeName, projectRoot, options = {}) {
+    const changeDir = join(projectRoot, 'specflow', 'changes', changeName);
+    const deltaSpecsDir = join(changeDir, 'specs');
+    const mainSpecsDir = join(projectRoot, 'specflow', 'specs');
+    // 0. Phase gate: require phase=built unless --force
+    const metadata = await readChangeMetadata(changeDir);
+    const currentPhase = metadata?.phase;
+    if (currentPhase !== 'built' && !options.force) {
+        const phaseLabel = currentPhase ?? 'unknown';
+        return {
+            success: false,
+            errors: [
+                `Cannot archive: change '${changeName}' is in phase '${phaseLabel}', expected 'built'. Complete '/specflow:build' first, or pass '--force' to archive anyway.`,
+            ],
+        };
+    }
+    if (options.force && currentPhase !== 'built') {
+        const phaseLabel = currentPhase ?? 'unknown';
+        console.warn(`Warning: archiving "${changeName}" in phase ${phaseLabel} with --force. ` +
+            `Consider running /specflow:build first.`);
+    }
+    // 1. Find delta spec files
+    const deltaFiles = await listMarkdownFiles(deltaSpecsDir);
+    if (deltaFiles.length === 0) {
+        return {
+            success: false,
+            errors: [`No delta spec files found in ${deltaSpecsDir}`],
+        };
+    }
+    // 2. Validate each delta spec
+    const allErrors = [];
+    for (const file of deltaFiles) {
+        const deltaContent = await fs.readFile(join(deltaSpecsDir, file), 'utf-8');
+        const validation = validateSpec(deltaContent);
+        if (!validation.valid) {
+            for (const err of validation.errors) {
+                allErrors.push(`${file}: ${err.message}`);
+            }
+        }
+    }
+    if (allErrors.length > 0) {
+        return { success: false, errors: allErrors };
+    }
+    // 3 & 4. Apply each delta to its corresponding main spec
+    for (const file of deltaFiles) {
+        const deltaContent = await fs.readFile(join(deltaSpecsDir, file), 'utf-8');
+        const mainSpecPath = join(mainSpecsDir, file);
+        const mainSpecDir = join(mainSpecPath, '..');
+        await fs.mkdir(mainSpecDir, { recursive: true });
+        let mainContent;
+        try {
+            mainContent = await fs.readFile(mainSpecPath, 'utf-8');
+        }
+        catch (error) {
+            if (error instanceof Error &&
+                'code' in error &&
+                error.code === 'ENOENT') {
+                // If main spec doesn't exist yet, start with empty content
+                mainContent = '';
+            }
+            else {
+                throw error;
+            }
+        }
+        const updatedContent = applyDeltaSpec(mainContent, deltaContent);
+        await fs.writeFile(mainSpecPath, updatedContent, 'utf-8');
+    }
+    // 5. Move change directory to archive
+    const datePrefix = todayDatePrefix();
+    const archiveDir = join(projectRoot, 'specflow', 'changes', 'archive');
+    const archiveDest = join(archiveDir, `${datePrefix}-${changeName}`);
+    await fs.mkdir(archiveDir, { recursive: true });
+    await fs.rename(changeDir, archiveDest);
+    // 6. Update archived metadata to phase=archived (preserve other fields)
+    const archivedMeta = await readChangeMetadata(archiveDest);
+    if (archivedMeta !== null) {
+        await writeChangeMetadata(archiveDest, { ...archivedMeta, phase: 'archived' });
+    }
+    return {
+        success: true,
+        errors: [],
+        archivePath: archiveDest,
+    };
+}

package/dist/core/artifact-graph/graph.d.ts

@@ -0,0 +1,60 @@
+import type { Artifact, SchemaYaml, CompletedSet, BlockedArtifacts } from './types.js';
+/**
+ * Represents an artifact dependency graph.
+ * Provides methods for querying build order, ready artifacts, and completion status.
+ *
+ * Immutable: all query methods return new arrays/objects, never mutate internal state.
+ */
+export declare class ArtifactGraph {
+    private readonly artifacts;
+    private readonly schema;
+    private constructor();
+    /**
+     * Creates an ArtifactGraph from a YAML file path.
+     */
+    static fromYaml(filePath: string): ArtifactGraph;
+    /**
+     * Creates an ArtifactGraph from YAML content string.
+     */
+    static fromYamlContent(yamlContent: string): ArtifactGraph;
+    /**
+     * Creates an ArtifactGraph from a pre-validated schema object.
+     */
+    static fromSchema(schema: SchemaYaml): ArtifactGraph;
+    /**
+     * Gets a single artifact by ID.
+     */
+    getArtifact(id: string): Artifact | undefined;
+    /**
+     * Gets all artifacts in the graph (returns a new array).
+     */
+    getAllArtifacts(): readonly Artifact[];
+    /**
+     * Gets the schema name.
+     */
+    getName(): string;
+    /**
+     * Gets the schema version.
+     */
+    getVersion(): number;
+    /**
+     * Computes the topological build order using Kahn's algorithm.
+     * Returns artifact IDs in a valid order: dependencies before dependents.
+     * Ties are broken alphabetically for deterministic output.
+     */
+    getBuildOrder(): string[];
+    /**
+     * Gets artifacts that are ready to be created (all dependencies in completed set).
+     * Excludes already-completed artifacts.
+     */
+    getNextArtifacts(completed: CompletedSet): string[];
+    /**
+     * Checks if all artifacts in the graph are completed.
+     */
+    isComplete(completed: CompletedSet): boolean;
+    /**
+     * Gets blocked artifacts and their unmet dependencies.
+     * Returns a mapping of artifact ID to array of missing dependency IDs.
+     */
+    getBlocked(completed: CompletedSet): BlockedArtifacts;
+}

package/dist/core/artifact-graph/graph.js

@@ -0,0 +1,141 @@
+import { loadSchema, parseSchema } from './schema.js';
+/**
+ * Represents an artifact dependency graph.
+ * Provides methods for querying build order, ready artifacts, and completion status.
+ *
+ * Immutable: all query methods return new arrays/objects, never mutate internal state.
+ */
+export class ArtifactGraph {
+    artifacts;
+    schema;
+    constructor(schema) {
+        this.schema = schema;
+        this.artifacts = new Map(schema.artifacts.map(a => [a.id, a]));
+    }
+    /**
+     * Creates an ArtifactGraph from a YAML file path.
+     */
+    static fromYaml(filePath) {
+        const schema = loadSchema(filePath);
+        return new ArtifactGraph(schema);
+    }
+    /**
+     * Creates an ArtifactGraph from YAML content string.
+     */
+    static fromYamlContent(yamlContent) {
+        const schema = parseSchema(yamlContent);
+        return new ArtifactGraph(schema);
+    }
+    /**
+     * Creates an ArtifactGraph from a pre-validated schema object.
+     */
+    static fromSchema(schema) {
+        return new ArtifactGraph(schema);
+    }
+    /**
+     * Gets a single artifact by ID.
+     */
+    getArtifact(id) {
+        return this.artifacts.get(id);
+    }
+    /**
+     * Gets all artifacts in the graph (returns a new array).
+     */
+    getAllArtifacts() {
+        return Array.from(this.artifacts.values());
+    }
+    /**
+     * Gets the schema name.
+     */
+    getName() {
+        return this.schema.name;
+    }
+    /**
+     * Gets the schema version.
+     */
+    getVersion() {
+        return this.schema.version;
+    }
+    /**
+     * Computes the topological build order using Kahn's algorithm.
+     * Returns artifact IDs in a valid order: dependencies before dependents.
+     * Ties are broken alphabetically for deterministic output.
+     */
+    getBuildOrder() {
+        const inDegree = new Map();
+        const dependents = new Map();
+        for (const artifact of this.artifacts.values()) {
+            inDegree.set(artifact.id, artifact.requires.length);
+            dependents.set(artifact.id, []);
+        }
+        for (const artifact of this.artifacts.values()) {
+            for (const req of artifact.requires) {
+                dependents.get(req).push(artifact.id);
+            }
+        }
+        // Start with roots (in-degree 0), sorted for determinism
+        const queue = [...this.artifacts.keys()]
+            .filter(id => inDegree.get(id) === 0)
+            .sort();
+        const result = [];
+        while (queue.length > 0) {
+            const current = queue.shift();
+            result.push(current);
+            const newlyReady = [];
+            for (const dep of dependents.get(current)) {
+                const newDegree = inDegree.get(dep) - 1;
+                inDegree.set(dep, newDegree);
+                if (newDegree === 0) {
+                    newlyReady.push(dep);
+                }
+            }
+            queue.push(...newlyReady.sort());
+        }
+        return result;
+    }
+    /**
+     * Gets artifacts that are ready to be created (all dependencies in completed set).
+     * Excludes already-completed artifacts.
+     */
+    getNextArtifacts(completed) {
+        const ready = [];
+        for (const artifact of this.artifacts.values()) {
+            if (completed.has(artifact.id)) {
+                continue;
+            }
+            const allDepsCompleted = artifact.requires.every(req => completed.has(req));
+            if (allDepsCompleted) {
+                ready.push(artifact.id);
+            }
+        }
+        return ready.sort();
+    }
+    /**
+     * Checks if all artifacts in the graph are completed.
+     */
+    isComplete(completed) {
+        for (const artifact of this.artifacts.values()) {
+            if (!completed.has(artifact.id)) {
+                return false;
+            }
+        }
+        return true;
+    }
+    /**
+     * Gets blocked artifacts and their unmet dependencies.
+     * Returns a mapping of artifact ID to array of missing dependency IDs.
+     */
+    getBlocked(completed) {
+        const blocked = {};
+        for (const artifact of this.artifacts.values()) {
+            if (completed.has(artifact.id)) {
+                continue;
+            }
+            const unmetDeps = artifact.requires.filter(req => !completed.has(req));
+            if (unmetDeps.length > 0) {
+                blocked[artifact.id] = [...unmetDeps].sort();
+            }
+        }
+        return blocked;
+    }
+}

package/dist/core/artifact-graph/index.d.ts

@@ -0,0 +1,10 @@
+export { ArtifactSchema, ApplyPhaseSchema, SchemaYamlSchema, } from './types.js';
+export type { Artifact, ApplyPhase, SchemaYaml, CompletedSet, BlockedArtifacts, } from './types.js';
+export { loadSchema, parseSchema, SchemaValidationError, } from './schema.js';
+export { resolveSchema, getSchemaDir, getPackageSchemasDir, getProjectSchemasDir, listSchemas, SchemaLoadError, } from './resolver.js';
+export { ArtifactGraph } from './graph.js';
+export { getCompletedArtifacts } from './state.js';
+export { loadInstructions } from './instruction-loader.js';
+export type { ArtifactInstructions, DependencyInfo, ProjectConfig, } from './instruction-loader.js';
+export { formatStatus, formatStatusHuman } from './outputs.js';
+export type { ArtifactStatusEntry, StatusOutput } from './outputs.js';

package/dist/core/artifact-graph/index.js

@@ -0,0 +1,7 @@
+export { ArtifactSchema, ApplyPhaseSchema, SchemaYamlSchema, } from './types.js';
+export { loadSchema, parseSchema, SchemaValidationError, } from './schema.js';
+export { resolveSchema, getSchemaDir, getPackageSchemasDir, getProjectSchemasDir, listSchemas, SchemaLoadError, } from './resolver.js';
+export { ArtifactGraph } from './graph.js';
+export { getCompletedArtifacts } from './state.js';
+export { loadInstructions } from './instruction-loader.js';
+export { formatStatus, formatStatusHuman } from './outputs.js';

package/dist/core/artifact-graph/instruction-loader.d.ts

@@ -0,0 +1,45 @@
+import type { SchemaYaml } from './types.js';
+/**
+ * Dependency information included in artifact instructions.
+ */
+export interface DependencyInfo {
+    /** Artifact ID */
+    readonly id: string;
+    /** File path pattern this dependency generates */
+    readonly generates: string;
+    /** Description of the dependency artifact */
+    readonly description: string;
+}
+/**
+ * Loaded instructions for creating an artifact.
+ */
+export interface ArtifactInstructions {
+    /** The artifact's instruction text from the schema */
+    readonly instruction: string | undefined;
+    /** Project context from the config */
+    readonly context: string | undefined;
+    /** Dependencies with their metadata */
+    readonly dependencies: readonly DependencyInfo[];
+    /** The artifact's generates path */
+    readonly generates: string;
+    /** The artifact's description */
+    readonly description: string;
+}
+/**
+ * Optional project config with context for instruction loading.
+ */
+export interface ProjectConfig {
+    readonly context?: string;
+    readonly [key: string]: unknown;
+}
+/**
+ * Loads enriched instructions for creating an artifact.
+ *
+ * @param artifactId - The artifact ID to load instructions for
+ * @param changeDir - Path to the change directory
+ * @param schema - The workflow schema
+ * @param config - Optional project configuration with context
+ * @returns The loaded artifact instructions
+ * @throws Error if the artifact ID is not found in the schema
+ */
+export declare function loadInstructions(artifactId: string, changeDir: string, schema: SchemaYaml, config?: ProjectConfig): ArtifactInstructions;

package/dist/core/artifact-graph/instruction-loader.js

@@ -0,0 +1,37 @@
+/**
+ * Loads enriched instructions for creating an artifact.
+ *
+ * @param artifactId - The artifact ID to load instructions for
+ * @param changeDir - Path to the change directory
+ * @param schema - The workflow schema
+ * @param config - Optional project configuration with context
+ * @returns The loaded artifact instructions
+ * @throws Error if the artifact ID is not found in the schema
+ */
+export function loadInstructions(artifactId, changeDir, schema, config) {
+    const artifact = schema.artifacts.find(a => a.id === artifactId);
+    if (!artifact) {
+        throw new Error(`Artifact '${artifactId}' not found in schema '${schema.name}'`);
+    }
+    const dependencies = buildDependencyInfo(artifact, schema);
+    return {
+        instruction: artifact.instruction,
+        context: config?.context ?? undefined,
+        dependencies,
+        generates: artifact.generates,
+        description: artifact.description,
+    };
+}
+/**
+ * Builds dependency information for an artifact's requirements.
+ */
+function buildDependencyInfo(artifact, schema) {
+    return artifact.requires.map(reqId => {
+        const depArtifact = schema.artifacts.find(a => a.id === reqId);
+        return {
+            id: reqId,
+            generates: depArtifact?.generates ?? reqId,
+            description: depArtifact?.description ?? '',
+        };
+    });
+}

package/dist/core/artifact-graph/outputs.d.ts

@@ -0,0 +1,35 @@
+import type { Artifact } from './types.js';
+/**
+ * Status of a single artifact.
+ */
+export interface ArtifactStatusEntry {
+    readonly id: string;
+    readonly status: 'done' | 'ready' | 'blocked';
+    readonly missingDeps?: readonly string[];
+}
+/**
+ * JSON-friendly status object for all artifacts.
+ */
+export interface StatusOutput {
+    readonly artifacts: readonly ArtifactStatusEntry[];
+}
+/**
+ * Formats artifact statuses as a structured JSON-friendly object.
+ *
+ * @param artifacts - The artifact definitions from the schema
+ * @param completed - Array of completed artifact IDs
+ * @returns Structured status with each artifact's state
+ */
+export declare function formatStatus(artifacts: readonly Artifact[], completed: readonly string[]): StatusOutput;
+/**
+ * Formats artifact statuses as human-readable checkbox text.
+ *
+ * Output format:
+ *   [x] proposal
+ *   [ ] specs (blocked by: proposal)
+ *
+ * @param artifacts - The artifact definitions from the schema
+ * @param completed - Array of completed artifact IDs
+ * @returns Checkbox-style text string
+ */
+export declare function formatStatusHuman(artifacts: readonly Artifact[], completed: readonly string[]): string;

package/dist/core/artifact-graph/outputs.js

@@ -0,0 +1,48 @@
+/**
+ * Formats artifact statuses as a structured JSON-friendly object.
+ *
+ * @param artifacts - The artifact definitions from the schema
+ * @param completed - Array of completed artifact IDs
+ * @returns Structured status with each artifact's state
+ */
+export function formatStatus(artifacts, completed) {
+    const completedSet = new Set(completed);
+    const statuses = artifacts.map(artifact => {
+        if (completedSet.has(artifact.id)) {
+            return { id: artifact.id, status: 'done' };
+        }
+        const missingDeps = artifact.requires.filter(req => !completedSet.has(req));
+        if (missingDeps.length === 0) {
+            return { id: artifact.id, status: 'ready' };
+        }
+        return {
+            id: artifact.id,
+            status: 'blocked',
+            missingDeps,
+        };
+    });
+    return { artifacts: statuses };
+}
+/**
+ * Formats artifact statuses as human-readable checkbox text.
+ *
+ * Output format:
+ *   [x] proposal
+ *   [ ] specs (blocked by: proposal)
+ *
+ * @param artifacts - The artifact definitions from the schema
+ * @param completed - Array of completed artifact IDs
+ * @returns Checkbox-style text string
+ */
+export function formatStatusHuman(artifacts, completed) {
+    const completedSet = new Set(completed);
+    const lines = artifacts.map(artifact => {
+        const checkbox = completedSet.has(artifact.id) ? '[x]' : '[ ]';
+        const missingDeps = artifact.requires.filter(req => !completedSet.has(req));
+        const suffix = missingDeps.length > 0
+            ? ` (blocked by: ${missingDeps.join(', ')})`
+            : '';
+        return `${checkbox} ${artifact.id}${suffix}`;
+    });
+    return lines.join('\n');
+}