@lumenflow/core 2.1.1 → 2.2.0

package/dist/backlog-generator.d.ts

@@ -16,6 +16,10 @@
  * @see {@link tools/__tests__/status-date-from-event.test.mjs} - Date tests
  * @see {@link tools/lib/wu-state-store.mjs} - State store
  */
+interface BacklogYamlOptions {
+    wuDir?: string;
+    projectRoot?: string;
+}
 /**
  * Generates backlog.md markdown from WUStateStore
  *
@@ -26,6 +30,9 @@
  * - Placeholder text for empty sections
  *
  * @param {import('./wu-state-store.js').WUStateStore} store - State store to read from
+ * @param {object} [options] - Optional settings
+ * @param {string} [options.wuDir] - Absolute or repo-relative path to WU YAML directory
+ * @param {string} [options.projectRoot] - Project root override for path resolution
  * @returns {Promise<string>} Markdown content for backlog.md
  *
  * @example
@@ -34,25 +41,7 @@
  * const markdown = await generateBacklog(store);
  * await fs.writeFile('backlog.md', markdown, 'utf-8');
  */
-export declare function generateBacklog(store: any): Promise<string>;
-/**
- * Generates status.md markdown from WUStateStore
- *
- * Format matches current status.md exactly:
- * - Header with last updated timestamp
- * - In Progress section
- * - Completed section with dates
- * - Placeholder for empty sections
- *
- * @param {import('./wu-state-store.js').WUStateStore} store - State store to read from
- * @returns {Promise<string>} Markdown content for status.md
- *
- * @example
- * const store = new WUStateStore('/path/to/state');
- * await store.load();
- * const markdown = await generateStatus(store);
- * await fs.writeFile('status.md', markdown, 'utf-8');
- */
+export declare function generateBacklog(store: any, options?: BacklogYamlOptions): Promise<string>;
 export declare function generateStatus(store: any): Promise<string>;
 /**
  * WU-2244: Get completion date for a WU from state store
@@ -109,3 +98,4 @@ export declare function validateBacklogConsistency(store: any, markdown: any): P
     valid: boolean;
     errors: any[];
 }>;
+export {};

package/dist/backlog-generator.js

@@ -17,6 +17,82 @@
  * @see {@link tools/lib/wu-state-store.mjs} - State store
  */
 import { createHash } from 'node:crypto';
+import { existsSync, readdirSync } from 'node:fs';
+import path from 'node:path';
+import { readWURaw } from './wu-yaml.js';
+import { WU_STATUS, WU_STATUS_GROUPS } from './wu-constants.js';
+import { createWuPaths, resolveFromProjectRoot } from './wu-paths.js';
+const WU_FILENAME_PATTERN = /^WU-\d+\.yaml$/;
+function normalizeYamlScalar(value) {
+    if (value === undefined || value === null) {
+        return '';
+    }
+    return typeof value === 'string' ? value : String(value);
+}
+function normalizeYamlStatus(value) {
+    const normalized = normalizeYamlScalar(value).trim().toLowerCase();
+    return normalized === '' ? WU_STATUS.READY : normalized;
+}
+function mapYamlStatusToSection(status) {
+    if (WU_STATUS_GROUPS.UNCLAIMED.includes(status)) {
+        return WU_STATUS.READY;
+    }
+    if (status === WU_STATUS.IN_PROGRESS) {
+        return WU_STATUS.IN_PROGRESS;
+    }
+    if (status === WU_STATUS.BLOCKED) {
+        return WU_STATUS.BLOCKED;
+    }
+    if (WU_STATUS_GROUPS.TERMINAL.includes(status)) {
+        return WU_STATUS.DONE;
+    }
+    return WU_STATUS.READY;
+}
+function compareWuIds(a, b) {
+    const numA = Number.parseInt(a.replace(/^WU-/, ''), 10);
+    const numB = Number.parseInt(b.replace(/^WU-/, ''), 10);
+    if (!Number.isNaN(numA) && !Number.isNaN(numB) && numA !== numB) {
+        return numA - numB;
+    }
+    return a.localeCompare(b);
+}
+function resolveWuDir(options = {}) {
+    const paths = createWuPaths({ projectRoot: options.projectRoot });
+    const configured = options.wuDir || paths.WU_DIR();
+    return path.isAbsolute(configured) ? configured : resolveFromProjectRoot(configured);
+}
+function loadYamlWuEntries(wuDir) {
+    if (!existsSync(wuDir)) {
+        return new Map();
+    }
+    const files = readdirSync(wuDir).filter((file) => WU_FILENAME_PATTERN.test(file));
+    files.sort((a, b) => compareWuIds(a.replace(/\.yaml$/, ''), b.replace(/\.yaml$/, '')));
+    const entries = new Map();
+    for (const file of files) {
+        const wuId = file.replace(/\.yaml$/, '');
+        const doc = readWURaw(path.join(wuDir, file));
+        if (!doc || typeof doc !== 'object') {
+            continue;
+        }
+        entries.set(wuId, {
+            status: normalizeYamlStatus(doc.status),
+            title: normalizeYamlScalar(doc.title),
+            lane: normalizeYamlScalar(doc.lane),
+        });
+    }
+    return entries;
+}
+function getMergedBacklogEntry(store, yamlEntries, wuId) {
+    const state = typeof store.getWUState === 'function' ? store.getWUState(wuId) : store.wuState.get(wuId);
+    if (state) {
+        return { title: state.title, lane: state.lane };
+    }
+    const yamlEntry = yamlEntries.get(wuId);
+    if (!yamlEntry) {
+        return null;
+    }
+    return { title: yamlEntry.title, lane: yamlEntry.lane };
+}
 /**
  * Generates backlog.md markdown from WUStateStore
  *
@@ -27,6 +103,9 @@ import { createHash } from 'node:crypto';
  * - Placeholder text for empty sections
  *
  * @param {import('./wu-state-store.js').WUStateStore} store - State store to read from
+ * @param {object} [options] - Optional settings
+ * @param {string} [options.wuDir] - Absolute or repo-relative path to WU YAML directory
+ * @param {string} [options.projectRoot] - Project root override for path resolution
  * @returns {Promise<string>} Markdown content for backlog.md
  *
  * @example
@@ -36,7 +115,7 @@ import { createHash } from 'node:crypto';
  * await fs.writeFile('backlog.md', markdown, 'utf-8');
  */
 // eslint-disable-next-line sonarjs/cognitive-complexity -- Pre-existing complexity, refactor tracked separately
-export async function generateBacklog(store) {
+export async function generateBacklog(store, options = {}) {
     // Start with frontmatter
     const frontmatter = `---
 sections:
@@ -54,25 +133,60 @@ sections:
     insertion: after_heading_blank_line
 ---
 
-> Agent: Read **docs/04-operations/_frameworks/lumenflow/agent/onboarding/starting-prompt.md** first, then follow **docs/04-operations/\\_frameworks/lumenflow/lumenflow-complete.md** for execution.
+> Agent: Read **docs/04-operations/_frameworks/lumenflow/agent/onboarding/starting-prompt.md** first, then follow **docs/04-operations/\_frameworks/lumenflow/lumenflow-complete.md** for execution.
 
 # Backlog (single source of truth)
 
 `;
+    const yamlEntries = loadYamlWuEntries(resolveWuDir(options));
+    const storeReady = Array.from(store.getByStatus('ready'));
+    const storeInProgress = Array.from(store.getByStatus('in_progress'));
+    const storeBlocked = Array.from(store.getByStatus('blocked'));
+    const storeDone = Array.from(store.getByStatus('done'));
+    const storeIds = new Set([...storeReady, ...storeInProgress, ...storeBlocked, ...storeDone]);
+    const yamlReady = [];
+    const yamlInProgress = [];
+    const yamlBlocked = [];
+    const yamlDone = [];
+    for (const [wuId, entry] of yamlEntries.entries()) {
+        if (storeIds.has(wuId)) {
+            continue;
+        }
+        const status = mapYamlStatusToSection(entry.status);
+        if (status === WU_STATUS.IN_PROGRESS) {
+            yamlInProgress.push(wuId);
+        }
+        else if (status === WU_STATUS.BLOCKED) {
+            yamlBlocked.push(wuId);
+        }
+        else if (status === WU_STATUS.DONE) {
+            yamlDone.push(wuId);
+        }
+        else {
+            yamlReady.push(wuId);
+        }
+    }
+    yamlReady.sort(compareWuIds);
+    yamlInProgress.sort(compareWuIds);
+    yamlBlocked.sort(compareWuIds);
+    yamlDone.sort(compareWuIds);
+    const ready = [...storeReady, ...yamlReady];
+    const inProgress = [...storeInProgress, ...yamlInProgress];
+    const blocked = [...storeBlocked, ...yamlBlocked];
+    const done = [...storeDone, ...yamlDone];
     // Generate sections
     const sections = [];
     // Ready section (WUs with status: ready)
     sections.push('## 🚀 Ready (pull from here)');
     sections.push('');
-    const ready = store.getByStatus('ready');
-    if (ready.size === 0) {
+    if (ready.length === 0) {
         sections.push('(No items ready)');
     }
     else {
         for (const wuId of ready) {
-            const state = store.wuState.get(wuId);
-            if (state) {
-                sections.push(`- [${wuId} — ${state.title}](wu/${wuId}.yaml) — ${state.lane}`);
+            const entry = getMergedBacklogEntry(store, yamlEntries, wuId);
+            if (entry) {
+                sections.push(`- [${wuId} — ${entry.title}](wu/${wuId}.yaml) — ${entry.lane}`);
             }
         }
     }
@@ -80,15 +194,14 @@ sections:
     sections.push('');
     sections.push('## 🔧 In progress');
     sections.push('');
-    const inProgress = store.getByStatus('in_progress');
-    if (inProgress.size === 0) {
+    if (inProgress.length === 0) {
         sections.push('(No items currently in progress)');
     }
     else {
         for (const wuId of inProgress) {
-            const state = store.wuState.get(wuId);
-            if (state) {
-                sections.push(`- [${wuId} — ${state.title}](wu/${wuId}.yaml) — ${state.lane}`);
+            const entry = getMergedBacklogEntry(store, yamlEntries, wuId);
+            if (entry) {
+                sections.push(`- [${wuId} — ${entry.title}](wu/${wuId}.yaml) — ${entry.lane}`);
             }
         }
     }
@@ -96,15 +209,14 @@ sections:
     sections.push('');
     sections.push('## ⛔ Blocked');
     sections.push('');
-    const blocked = store.getByStatus('blocked');
-    if (blocked.size === 0) {
+    if (blocked.length === 0) {
         sections.push('(No items currently blocked)');
     }
     else {
         for (const wuId of blocked) {
-            const state = store.wuState.get(wuId);
-            if (state) {
-                sections.push(`- [${wuId} — ${state.title}](wu/${wuId}.yaml) — ${state.lane}`);
+            const entry = getMergedBacklogEntry(store, yamlEntries, wuId);
+            if (entry) {
+                sections.push(`- [${wuId} — ${entry.title}](wu/${wuId}.yaml) — ${entry.lane}`);
             }
         }
     }
@@ -112,39 +224,19 @@ sections:
     sections.push('');
     sections.push('## ✅ Done');
     sections.push('');
-    const done = store.getByStatus('done');
-    if (done.size === 0) {
+    if (done.length === 0) {
         sections.push('(No completed items)');
     }
     else {
         for (const wuId of done) {
-            const state = store.wuState.get(wuId);
-            if (state) {
-                sections.push(`- [${wuId} — ${state.title}](wu/${wuId}.yaml)`);
+            const entry = getMergedBacklogEntry(store, yamlEntries, wuId);
+            if (entry) {
+                sections.push(`- [${wuId} — ${entry.title}](wu/${wuId}.yaml)`);
             }
         }
     }
     return frontmatter + sections.join('\n');
 }
-/**
- * Generates status.md markdown from WUStateStore
- *
- * Format matches current status.md exactly:
- * - Header with last updated timestamp
- * - In Progress section
- * - Completed section with dates
- * - Placeholder for empty sections
- *
- * @param {import('./wu-state-store.js').WUStateStore} store - State store to read from
- * @returns {Promise<string>} Markdown content for status.md
- *
- * @example
- * const store = new WUStateStore('/path/to/state');
- * await store.load();
- * const markdown = await generateStatus(store);
- * await fs.writeFile('status.md', markdown, 'utf-8');
- */
-// eslint-disable-next-line sonarjs/cognitive-complexity -- Pre-existing complexity, refactor tracked separately
 export async function generateStatus(store) {
     const today = new Date().toISOString().split('T')[0]; // YYYY-MM-DD
     // Header

package/dist/index.d.ts

@@ -22,6 +22,7 @@ export * from './wu-yaml.js';
 export { getAssignedEmail } from './wu-claim-helpers.js';
 export * from './wu-done-worktree.js';
 export * from './wu-done-validators.js';
+export * from './wu-done-concurrent-merge.js';
 export * from './wu-helpers.js';
 export * from './wu-schema.js';
 export * from './wu-validator.js';
@@ -31,6 +32,7 @@ export * from './spawn-tree.js';
 export * from './spawn-recovery.js';
 export * from './spawn-monitor.js';
 export * from './spawn-escalation.js';
+export { SPAWN_SENTINEL, SPAWN_PROMPT_VERSION, SpawnPromptSchema, computeChecksum, createSpawnPrompt, validateSpawnPrompt, parseSpawnPrompt, serializeSpawnPrompt, checkSentinel, type SpawnPrompt, type SpawnPromptValidationResult, type ParseResult as SpawnPromptParseResult, } from './spawn-prompt-schema.js';
 export * from './backlog-generator.js';
 export * from './backlog-parser.js';
 export * from './backlog-editor.js';

package/dist/index.js

@@ -37,6 +37,8 @@ export * from './wu-yaml.js';
 export { getAssignedEmail } from './wu-claim-helpers.js';
 export * from './wu-done-worktree.js';
 export * from './wu-done-validators.js';
+// WU-1145: Concurrent backlog merge utilities
+export * from './wu-done-concurrent-merge.js';
 export * from './wu-helpers.js';
 export * from './wu-schema.js';
 export * from './wu-validator.js';
@@ -47,6 +49,9 @@ export * from './spawn-tree.js';
 export * from './spawn-recovery.js';
 export * from './spawn-monitor.js';
 export * from './spawn-escalation.js';
+// WU-1142: Spawn prompt schema for truncation-resistant prompts
+// Explicit exports to avoid ValidationResult conflict with validation/index.js
+export { SPAWN_SENTINEL, SPAWN_PROMPT_VERSION, SpawnPromptSchema, computeChecksum, createSpawnPrompt, validateSpawnPrompt, parseSpawnPrompt, serializeSpawnPrompt, checkSentinel, } from './spawn-prompt-schema.js';
 // Backlog management
 export * from './backlog-generator.js';
 export * from './backlog-parser.js';

package/dist/lumenflow-config-schema.d.ts

@@ -162,6 +162,7 @@ export declare const ClientBlockSchema: z.ZodObject<{
 export declare const ClientSkillsSchema: z.ZodObject<{
     instructions: z.ZodOptional<z.ZodString>;
     recommended: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    byLane: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>>;
 }, z.core.$strip>;
 /**
  * Client configuration (per-client settings)
@@ -176,6 +177,7 @@ export declare const ClientConfigSchema: z.ZodObject<{
     skills: z.ZodOptional<z.ZodObject<{
         instructions: z.ZodOptional<z.ZodString>;
         recommended: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        byLane: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
 /**
@@ -193,6 +195,7 @@ export declare const AgentsConfigSchema: z.ZodObject<{
         skills: z.ZodOptional<z.ZodObject<{
             instructions: z.ZodOptional<z.ZodString>;
             recommended: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            byLane: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>>;
         }, z.core.$strip>>;
     }, z.core.$strip>>>;
     methodology: z.ZodDefault<z.ZodObject<{
@@ -346,6 +349,7 @@ export declare const LumenFlowConfigSchema: z.ZodObject<{
             skills: z.ZodOptional<z.ZodObject<{
                 instructions: z.ZodOptional<z.ZodString>;
                 recommended: z.ZodDefault<z.ZodArray<z.ZodString>>;
+                byLane: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>>;
             }, z.core.$strip>>;
         }, z.core.$strip>>>;
         methodology: z.ZodDefault<z.ZodObject<{
@@ -509,6 +513,7 @@ export declare function validateConfig(data: unknown): z.ZodSafeParseResult<{
             skills?: {
                 recommended: string[];
                 instructions?: string;
+                byLane?: Record<string, string[]>;
             };
         }>;
         methodology: {

package/dist/lumenflow-config-schema.js

@@ -256,6 +256,15 @@ export const ClientSkillsSchema = z.object({
     instructions: z.string().optional(),
     /** Recommended skills to load for this client */
     recommended: z.array(z.string()).default([]),
+    /**
+     * WU-1142: Lane-specific skills to recommend
+     * Maps lane names to arrays of skill names
+     * @example
+     * byLane:
+     *   'Framework: Core': ['tdd-workflow', 'lumenflow-gates']
+     *   'Content: Documentation': ['worktree-discipline']
+     */
+    byLane: z.record(z.string(), z.array(z.string())).optional(),
 });
 /**
  * Client configuration (per-client settings)

package/dist/spawn-prompt-schema.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Spawn Prompt Schema (WU-1142)
+ *
+ * Zod schema for truncation-resistant spawn prompts.
+ * Implements a YAML envelope format with:
+ * - SHA256 checksums for integrity validation
+ * - Sentinel values for truncation detection
+ * - Schema validation for agent consumers
+ *
+ * Three-Layer Defense:
+ * 1. YAML Envelope - head/tail truncation breaks YAML parse
+ * 2. Checksum - validates content integrity
+ * 3. Sentinel - confirms complete transmission
+ *
+ * @module spawn-prompt-schema
+ */
+import { z } from 'zod';
+/**
+ * Sentinel value that marks complete spawn prompt transmission
+ */
+export declare const SPAWN_SENTINEL = "LUMENFLOW_SPAWN_COMPLETE";
+/**
+ * Current schema version
+ */
+export declare const SPAWN_PROMPT_VERSION = "1.0.0";
+/**
+ * Zod schema for spawn prompt envelope
+ */
+export declare const SpawnPromptSchema: z.ZodObject<{
+    wu_id: z.ZodString;
+    version: z.ZodDefault<z.ZodString>;
+    checksum: z.ZodString;
+    content: z.ZodString;
+    sentinel: z.ZodLiteral<"LUMENFLOW_SPAWN_COMPLETE">;
+}, z.core.$strip>;
+/**
+ * Type for a valid spawn prompt
+ */
+export type SpawnPrompt = z.infer<typeof SpawnPromptSchema>;
+/**
+ * Compute SHA256 checksum of content
+ *
+ * @param content - Content to checksum
+ * @returns Hex-encoded SHA256 hash
+ */
+export declare function computeChecksum(content: string): string;
+/**
+ * Create a spawn prompt envelope with computed checksum
+ *
+ * @param wuId - WU ID for the spawn prompt
+ * @param content - The spawn prompt content
+ * @returns Valid spawn prompt envelope
+ */
+export declare function createSpawnPrompt(wuId: string, content: string): SpawnPrompt;
+/**
+ * Spawn prompt validation result type
+ */
+export interface SpawnPromptValidationResult {
+    valid: boolean;
+    error?: string;
+}
+/**
+ * Validate a spawn prompt, checking both schema and checksum
+ *
+ * @param data - Data to validate
+ * @returns Validation result with error message if invalid
+ */
+export declare function validateSpawnPrompt(data: unknown): SpawnPromptValidationResult;
+/**
+ * Parse result type
+ */
+export interface ParseResult {
+    success: boolean;
+    data?: SpawnPrompt;
+    error?: string;
+}
+/**
+ * Parse a YAML spawn prompt string
+ *
+ * This function handles:
+ * 1. YAML parsing (head/tail truncation breaks parse)
+ * 2. Schema validation
+ * 3. Checksum validation (detects content corruption)
+ *
+ * @param yamlString - YAML string to parse
+ * @returns Parse result with data or error
+ */
+export declare function parseSpawnPrompt(yamlString: string): ParseResult;
+/**
+ * Serialize a spawn prompt to YAML format
+ *
+ * @param prompt - Spawn prompt to serialize
+ * @returns YAML string
+ */
+export declare function serializeSpawnPrompt(prompt: SpawnPrompt): string;
+/**
+ * Quick validation check for truncated output
+ *
+ * This is a fast check that can be used before full parsing:
+ * - Checks if sentinel appears at the end of the string
+ * - Does not validate checksum (use parseSpawnPrompt for full validation)
+ *
+ * @param yamlString - String to check
+ * @returns true if sentinel found near end, false otherwise
+ */
+export declare function checkSentinel(yamlString: string): boolean;

package/dist/spawn-prompt-schema.js

@@ -0,0 +1,160 @@
+/**
+ * Spawn Prompt Schema (WU-1142)
+ *
+ * Zod schema for truncation-resistant spawn prompts.
+ * Implements a YAML envelope format with:
+ * - SHA256 checksums for integrity validation
+ * - Sentinel values for truncation detection
+ * - Schema validation for agent consumers
+ *
+ * Three-Layer Defense:
+ * 1. YAML Envelope - head/tail truncation breaks YAML parse
+ * 2. Checksum - validates content integrity
+ * 3. Sentinel - confirms complete transmission
+ *
+ * @module spawn-prompt-schema
+ */
+import { z } from 'zod';
+import { createHash } from 'node:crypto';
+import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
+/**
+ * Sentinel value that marks complete spawn prompt transmission
+ */
+export const SPAWN_SENTINEL = 'LUMENFLOW_SPAWN_COMPLETE';
+/**
+ * Current schema version
+ */
+export const SPAWN_PROMPT_VERSION = '1.0.0';
+/**
+ * Zod schema for spawn prompt envelope
+ */
+export const SpawnPromptSchema = z.object({
+    /** WU ID for this spawn prompt */
+    wu_id: z.string().regex(/^WU-\d+$/i, 'Invalid WU ID format'),
+    /** Schema version */
+    version: z.string().default(SPAWN_PROMPT_VERSION),
+    /** SHA256 checksum of content field */
+    checksum: z.string().length(64, 'Checksum must be 64 hex characters'),
+    /** The actual spawn prompt content */
+    content: z.string().min(1, 'Content cannot be empty'),
+    /** Sentinel value confirming complete transmission */
+    sentinel: z.literal(SPAWN_SENTINEL),
+});
+/**
+ * Compute SHA256 checksum of content
+ *
+ * @param content - Content to checksum
+ * @returns Hex-encoded SHA256 hash
+ */
+export function computeChecksum(content) {
+    return createHash('sha256').update(content, 'utf8').digest('hex');
+}
+/**
+ * Create a spawn prompt envelope with computed checksum
+ *
+ * @param wuId - WU ID for the spawn prompt
+ * @param content - The spawn prompt content
+ * @returns Valid spawn prompt envelope
+ */
+export function createSpawnPrompt(wuId, content) {
+    const checksum = computeChecksum(content);
+    return {
+        wu_id: wuId,
+        version: SPAWN_PROMPT_VERSION,
+        checksum,
+        content,
+        sentinel: SPAWN_SENTINEL,
+    };
+}
+/**
+ * Validate a spawn prompt, checking both schema and checksum
+ *
+ * @param data - Data to validate
+ * @returns Validation result with error message if invalid
+ */
+export function validateSpawnPrompt(data) {
+    // First, validate schema
+    const schemaResult = SpawnPromptSchema.safeParse(data);
+    if (!schemaResult.success) {
+        // Zod v4: use schemaResult.error.issues instead of .errors
+        const errorMessages = schemaResult.error.issues
+            .map((e) => `${e.path.join('.')}: ${e.message}`)
+            .join('; ');
+        return {
+            valid: false,
+            error: `Schema validation failed: ${errorMessages}`,
+        };
+    }
+    // Then, validate checksum matches content
+    const prompt = schemaResult.data;
+    const computedChecksum = computeChecksum(prompt.content);
+    if (computedChecksum !== prompt.checksum) {
+        return {
+            valid: false,
+            error: `Checksum mismatch: expected ${prompt.checksum}, computed ${computedChecksum}. Content may be corrupted or truncated.`,
+        };
+    }
+    return { valid: true };
+}
+/**
+ * Parse a YAML spawn prompt string
+ *
+ * This function handles:
+ * 1. YAML parsing (head/tail truncation breaks parse)
+ * 2. Schema validation
+ * 3. Checksum validation (detects content corruption)
+ *
+ * @param yamlString - YAML string to parse
+ * @returns Parse result with data or error
+ */
+export function parseSpawnPrompt(yamlString) {
+    // Step 1: Parse YAML
+    let parsed;
+    try {
+        parsed = parseYaml(yamlString);
+    }
+    catch (e) {
+        return {
+            success: false,
+            error: `YAML parse failed: ${e instanceof Error ? e.message : 'Unknown error'}. Output may be truncated.`,
+        };
+    }
+    // Step 2: Validate schema and checksum
+    const validationResult = validateSpawnPrompt(parsed);
+    if (!validationResult.valid) {
+        return {
+            success: false,
+            error: validationResult.error,
+        };
+    }
+    // Safe cast since validation passed
+    return {
+        success: true,
+        data: parsed,
+    };
+}
+/**
+ * Serialize a spawn prompt to YAML format
+ *
+ * @param prompt - Spawn prompt to serialize
+ * @returns YAML string
+ */
+export function serializeSpawnPrompt(prompt) {
+    return stringifyYaml(prompt, {
+        lineWidth: 0, // Don't wrap lines
+    });
+}
+/**
+ * Quick validation check for truncated output
+ *
+ * This is a fast check that can be used before full parsing:
+ * - Checks if sentinel appears at the end of the string
+ * - Does not validate checksum (use parseSpawnPrompt for full validation)
+ *
+ * @param yamlString - String to check
+ * @returns true if sentinel found near end, false otherwise
+ */
+export function checkSentinel(yamlString) {
+    const trimmed = yamlString.trim();
+    return trimmed.endsWith(SPAWN_SENTINEL) || trimmed.includes(`sentinel: ${SPAWN_SENTINEL}`);
+}