@lumenflow/core 3.1.3 → 3.2.1

package/dist/wu-yaml-fixer.js

@@ -0,0 +1,273 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * WU YAML Auto-Fixer
+ *
+ * Detects and auto-repairs common YAML validation issues that would fail at wu:done.
+ * Part of WU-1359: Early YAML validation at wu:claim.
+ *
+ * Common issues fixed:
+ * - ISO timestamp dates → YYYY-MM-DD format
+ * - Username → email format (with configurable domain)
+ * - docs → documentation (type field)
+ * - String numbers → number (phase field)
+ *
+ * @see {@link packages/@lumenflow/cli/src/lib/wu-schema.ts} - WU schema definition
+ * @see {@link packages/@lumenflow/cli/src/wu-claim.ts} - Consumer
+ */
+import { readFileSync, writeFileSync, copyFileSync } from 'node:fs';
+import { parseYAML, stringifyYAML } from './wu-yaml.js';
+import { DEFAULTS, STRING_LITERALS } from './wu-constants.js';
+// Valid type values from wu-schema.ts
+const VALID_TYPES = ['feature', 'bug', 'documentation', 'process', 'tooling', 'chore', 'refactor'];
+// Common type aliases that should be auto-fixed
+const TYPE_ALIASES = {
+    docs: 'documentation',
+    doc: 'documentation',
+    feat: 'feature',
+    fix: 'bug',
+    bugfix: 'bug',
+    tool: 'tooling',
+    tools: 'tooling',
+    ref: 'refactor',
+    proc: 'process',
+};
+/**
+ * Default email domain for username -> email conversion
+ * WU-1068: Changed from hardcoded 'exampleapp.co.uk' to configurable default
+ */
+const DEFAULT_EMAIL_DOMAIN = DEFAULTS.EMAIL_DOMAIN;
+/**
+ * Issue types that can be detected and auto-fixed
+ */
+export const FIXABLE_ISSUES = {
+    DATE_ISO_TIMESTAMP: 'DATE_ISO_TIMESTAMP',
+    USERNAME_NOT_EMAIL: 'USERNAME_NOT_EMAIL',
+    TYPE_ALIAS: 'TYPE_ALIAS',
+    PHASE_STRING: 'PHASE_STRING',
+    PRIORITY_LOWERCASE: 'PRIORITY_LOWERCASE',
+};
+/**
+ * Check created field for ISO timestamp issues
+ * @param {object} doc - Parsed WU YAML data
+ * @returns {object|null} Issue object or null
+ */
+function checkCreatedField(doc) {
+    if (!doc.created)
+        return null;
+    const createdStr = String(doc.created);
+    // Match ISO 8601 timestamp (2025-12-02T00:00:00.000Z or similar)
+    if (/^\d{4}-\d{2}-\d{2}T/.test(createdStr)) {
+        const dateOnly = createdStr.slice(0, 10);
+        return {
+            type: FIXABLE_ISSUES.DATE_ISO_TIMESTAMP,
+            field: 'created',
+            current: createdStr,
+            suggested: dateOnly,
+            description: `ISO timestamp should be YYYY-MM-DD: ${createdStr} → ${dateOnly}`,
+        };
+    }
+    // Handle Date objects that YAML parser may create
+    if (doc.created instanceof Date) {
+        const dateOnly = doc.created.toISOString().slice(0, 10);
+        return {
+            type: FIXABLE_ISSUES.DATE_ISO_TIMESTAMP,
+            field: 'created',
+            current: doc.created.toISOString(),
+            suggested: dateOnly,
+            description: `Date object should be YYYY-MM-DD string: ${doc.created.toISOString()} → ${dateOnly}`,
+        };
+    }
+    return null;
+}
+/**
+ * Check assigned_to field for username without email domain
+ * @param {object} doc - Parsed WU YAML data
+ * @returns {object|null} Issue object or null
+ */
+function checkAssignedToField(doc) {
+    if (!doc.assigned_to || typeof doc.assigned_to !== 'string')
+        return null;
+    const assignee = doc.assigned_to.trim();
+    if (assignee && !assignee.includes('@')) {
+        const suggested = `${assignee}@${DEFAULT_EMAIL_DOMAIN}`;
+        return {
+            type: FIXABLE_ISSUES.USERNAME_NOT_EMAIL,
+            field: 'assigned_to',
+            current: assignee,
+            suggested,
+            description: `Username should be email format: ${assignee} → ${suggested}`,
+        };
+    }
+    return null;
+}
+/**
+ * Check type field for common aliases or typos
+ * @param {object} doc - Parsed WU YAML data
+ * @returns {object|null} Issue object or null
+ */
+function checkTypeField(doc) {
+    if (!doc.type || typeof doc.type !== 'string')
+        return null;
+    const typeLower = doc.type.toLowerCase();
+    const alias = TYPE_ALIASES[typeLower];
+    if (alias) {
+        return {
+            type: FIXABLE_ISSUES.TYPE_ALIAS,
+            field: 'type',
+            current: doc.type,
+            suggested: alias,
+            description: `Type alias should use canonical form: ${doc.type} → ${alias}`,
+        };
+    }
+    // Check for invalid type not in aliases - try fuzzy match
+    if (!VALID_TYPES.includes(typeLower)) {
+        const closest = VALID_TYPES.find((t) => t.startsWith(typeLower.slice(0, 3)) || typeLower.startsWith(t.slice(0, 3)));
+        if (closest) {
+            return {
+                type: FIXABLE_ISSUES.TYPE_ALIAS,
+                field: 'type',
+                current: doc.type,
+                suggested: closest,
+                description: `Invalid type "${doc.type}" - did you mean "${closest}"?`,
+            };
+        }
+    }
+    return null;
+}
+/**
+ * Check phase field for string instead of number
+ * @param {object} doc - Parsed WU YAML data
+ * @returns {object|null} Issue object or null
+ */
+function checkPhaseField(doc) {
+    if (doc.phase == null || typeof doc.phase !== 'string')
+        return null;
+    const num = parseInt(doc.phase, 10);
+    if (!isNaN(num) && num > 0) {
+        return {
+            type: FIXABLE_ISSUES.PHASE_STRING,
+            field: 'phase',
+            current: doc.phase,
+            suggested: num,
+            description: `Phase should be number: "${doc.phase}" → ${num}`,
+        };
+    }
+    return null;
+}
+/**
+ * Check priority field for lowercase
+ * @param {object} doc - Parsed WU YAML data
+ * @returns {object|null} Issue object or null
+ */
+function checkPriorityField(doc) {
+    if (!doc.priority || typeof doc.priority !== 'string')
+        return null;
+    const upper = doc.priority.toUpperCase();
+    if (doc.priority !== upper && /^P[0-3]$/i.test(doc.priority)) {
+        return {
+            type: FIXABLE_ISSUES.PRIORITY_LOWERCASE,
+            field: 'priority',
+            current: doc.priority,
+            suggested: upper,
+            description: `Priority should be uppercase: ${doc.priority} → ${upper}`,
+        };
+    }
+    return null;
+}
+/**
+ * Detects fixable issues in WU YAML data
+ *
+ * @param {object} doc - Parsed WU YAML data
+ * @returns {Array<{type: string, field: string, current: unknown, suggested: unknown, description: string}>}
+ */
+export function detectFixableIssues(doc) {
+    const checks = [
+        checkCreatedField,
+        checkAssignedToField,
+        checkTypeField,
+        checkPhaseField,
+        checkPriorityField,
+    ];
+    return checks.map((check) => check(doc)).filter((issue) => issue !== null);
+}
+/**
+ * Applies fixes to WU YAML data in-place
+ *
+ * @param {object} doc - Parsed WU YAML data (will be modified)
+ * @param {Array<{type: string, field: string, suggested: unknown}>} issues - Issues to fix
+ * @returns {number} Number of fixes applied
+ */
+export function applyFixes(doc, issues) {
+    let fixed = 0;
+    for (const issue of issues) {
+        switch (issue.type) {
+            case FIXABLE_ISSUES.DATE_ISO_TIMESTAMP:
+                doc[issue.field] = issue.suggested;
+                fixed++;
+                break;
+            case FIXABLE_ISSUES.USERNAME_NOT_EMAIL:
+                doc[issue.field] = issue.suggested;
+                fixed++;
+                break;
+            case FIXABLE_ISSUES.TYPE_ALIAS:
+                doc[issue.field] = issue.suggested;
+                fixed++;
+                break;
+            case FIXABLE_ISSUES.PHASE_STRING:
+                doc[issue.field] = issue.suggested;
+                fixed++;
+                break;
+            case FIXABLE_ISSUES.PRIORITY_LOWERCASE:
+                doc[issue.field] = issue.suggested;
+                fixed++;
+                break;
+        }
+    }
+    return fixed;
+}
+/**
+ * Auto-fix WU YAML file
+ *
+ * @param {string} wuPath - Path to WU YAML file
+ * @param {AutoFixWUYamlOptions} options - Options
+ * @returns {{fixed: number, issues: Array, backupPath?: string}}
+ */
+export function autoFixWUYaml(wuPath, options = {}) {
+    const { dryRun = false, backup = true } = options;
+    // Read and parse
+    const text = readFileSync(wuPath, { encoding: 'utf-8' });
+    const doc = parseYAML(text);
+    // Detect issues
+    const issues = detectFixableIssues(doc);
+    if (issues.length === 0) {
+        return { fixed: 0, issues: [] };
+    }
+    if (dryRun) {
+        return { fixed: 0, issues, wouldFix: issues.length };
+    }
+    // Create backup if requested
+    let backupPath;
+    if (backup) {
+        backupPath = `${wuPath}.bak`;
+        copyFileSync(wuPath, backupPath);
+    }
+    // Apply fixes
+    const fixed = applyFixes(doc, issues);
+    // Write back
+    const newText = stringifyYAML(doc);
+    writeFileSync(wuPath, newText, { encoding: 'utf-8' });
+    return { fixed, issues, backupPath };
+}
+/**
+ * Format issues for CLI output
+ *
+ * @param {Array<{field: string, description: string}>} issues
+ * @returns {string}
+ */
+export function formatIssues(issues) {
+    return issues
+        .map((issue) => `  - ${issue.field}: ${issue.description}`)
+        .join(STRING_LITERALS.NEWLINE);
+}
+//# sourceMappingURL=wu-yaml-fixer.js.map

package/dist/wu-yaml-fixer.js.map

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

package/dist/wu-yaml.d.ts

@@ -0,0 +1,110 @@
+/**
+ * WU-1352: Standardized YAML stringify options.
+ *
+ * Ensures consistent output across all WU tools:
+ * - lineWidth: 100 (wrap long lines)
+ * - singleQuote: true (prefer 'single' over "double")
+ * - defaultKeyType: PLAIN (unquoted keys when safe)
+ *
+ * @type {import('yaml').ToStringOptions}
+ */
+export declare const YAML_STRINGIFY_OPTIONS: Readonly<{
+    lineWidth: 100;
+    singleQuote: true;
+    defaultKeyType: "PLAIN";
+}>;
+/**
+ * Read and parse WU YAML file.
+ *
+ * Validates:
+ * - File exists
+ * - YAML is valid
+ * - WU ID matches expected ID
+ *
+ * @param {string} wuPath - Path to WU YAML file
+ * @param {string} expectedId - Expected WU ID (e.g., 'WU-123')
+ * @returns {object} Parsed YAML document
+ * @throws {Error} If file not found, YAML invalid, or ID mismatch
+ */
+export declare function readWU(wuPath: string, expectedId: string): UnsafeAny;
+/**
+ * Read and parse WU YAML file asynchronously.
+ *
+ * Validates:
+ * - File exists
+ * - YAML is valid
+ * - WU ID matches expected ID
+ *
+ * @param {string} wuPath - Path to WU YAML file
+ * @param {string} expectedId - Expected WU ID (e.g., 'WU-123')
+ * @returns {Promise<object>} Parsed YAML document
+ * @throws {Error} If file not found, YAML invalid, or ID mismatch
+ */
+export declare function readWUAsync(wuPath: string, expectedId: string): Promise<UnsafeAny>;
+/**
+ * Parse YAML string to object.
+ * WU-1352: Centralized YAML parsing for consistency.
+ *
+ * @param {string} text - YAML string to parse
+ * @returns {object} Parsed object
+ * @throws {Error} If YAML is invalid
+ */
+export declare function parseYAML(text: string): UnsafeAny;
+/**
+ * Stringify object to YAML with standardized options.
+ * WU-1352: Centralized YAML serialization for consistency.
+ *
+ * @param {object} doc - Object to stringify
+ * @param {object} [options] - Additional stringify options (merged with YAML_STRINGIFY_OPTIONS)
+ * @returns {string} YAML string
+ */
+export declare function stringifyYAML(doc: UnsafeAny, options?: Record<string, unknown>): string;
+/**
+ * Read and parse YAML file without ID validation.
+ * WU-1352: For cases where you don't know/need to validate the WU ID.
+ *
+ * @param {string} yamlPath - Path to YAML file
+ * @returns {object} Parsed YAML document
+ * @throws {Error} If file not found or YAML invalid
+ */
+export declare function readWURaw(yamlPath: string): UnsafeAny;
+/**
+ * Read and parse YAML file without ID validation asynchronously.
+ * WU-1352: For cases where you don't know/need to validate the WU ID.
+ *
+ * @param {string} yamlPath - Path to YAML file
+ * @returns {Promise<object>} Parsed YAML document
+ * @throws {Error} If file not found or YAML invalid
+ */
+export declare function readWURawAsync(yamlPath: string): Promise<UnsafeAny>;
+/**
+ * Write WU YAML file with consistent formatting.
+ * WU-1352: Uses YAML_STRINGIFY_OPTIONS for consistent output.
+ *
+ * @param {string} wuPath - Path to WU YAML file
+ * @param {object} doc - YAML document to write
+ */
+export declare function writeWU(wuPath: string, doc: UnsafeAny): void;
+/**
+ * Append note to WU document's notes field.
+ *
+ * Always outputs a string (Zod schema requires string type).
+ * Handles various input formats:
+ * - undefined/null/empty: Set note directly as string
+ * - string: Append with newline separator
+ * - array: Convert to newline-separated string, then append
+ * - other: Replace with note
+ *
+ * @param {object} doc - WU document
+ * @param {string} note - Note to append
+ */
+export declare function appendNote(doc: UnsafeAny, note: string): void;
+/**
+ * Append an agent session entry to a WU's agent_sessions[] array
+ *
+ * @param {string} wuId - WU ID (e.g., "WU-1234")
+ * @param {object} sessionData - Session summary from endSession()
+ * @throws {Error} if WU file not found
+ */
+export declare function appendAgentSession(wuId: string, sessionData: UnsafeAny): void;
+//# sourceMappingURL=wu-yaml.d.ts.map

package/dist/wu-yaml.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wu-yaml.d.ts","sourceRoot":"","sources":["../src/wu-yaml.ts"],"names":[],"mappings":"AA6DA;;;;;;;;;GASG;AACH,eAAO,MAAM,sBAAsB;;;;EAIjC,CAAC;AAEH;;;;;;;;;;;;GAYG;AACH,wBAAgB,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,SAAS,CA8BpE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,CAqCxF;AAED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAEjD;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,SAAS,EAAE,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GAAG,MAAM,CAE3F;AAED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAqBrD;AAED;;;;;;;GAOG;AACH,wBAAsB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,CAwBzE;AAED;;;;;;GAMG;AACH,wBAAgB,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,SAAS,GAAG,IAAI,CAG5D;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAqB7D;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,SAAS,GAAG,IAAI,CAqB7E"}

package/dist/wu-yaml.js

@@ -0,0 +1,300 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { existsSync, readFileSync, writeFileSync, promises as fs } from 'node:fs';
+import { parse, stringify } from 'yaml';
+import { createError, ErrorCodes } from './error-handler.js';
+import { STRING_LITERALS } from './wu-constants.js';
+import { createWuPaths } from './wu-paths.js';
+/**
+ * Unified WU YAML I/O module.
+ *
+ * Replaces 4 duplicate read/write functions scattered across wu-claim, wu-done,
+ * wu-block, and wu-unblock. Single source of truth for WU YAML operations.
+ *
+ * WU-1352: Standardized on yaml v2.8.1 (eemeli) with consistent stringify options.
+ *
+ * Functions:
+ * - readWU(path, id): Read and validate WU YAML
+ * - readWURaw(path): Read YAML without ID validation
+ * - parseYAML(text): Parse YAML string to object
+ * - writeWU(path, doc): Write WU YAML with consistent formatting
+ * - stringifyYAML(doc): Stringify object to YAML with consistent formatting
+ * - appendNote(doc, note): Append note to doc.notes field
+ *
+ * @example
+ * import { readWU, writeWU, appendNote } from './lib/wu-yaml.js';
+ *
+ * // Read WU
+ * const doc = readWU('docs/04-operations/tasks/wu/WU-123.yaml', 'WU-123');
+ *
+ * // Modify doc
+ * doc.status = 'in_progress';
+ * appendNote(doc, 'Started work on this WU');
+ *
+ * // Write back
+ * writeWU('docs/04-operations/tasks/wu/WU-123.yaml', doc);
+ */
+/**
+ * WU-1352: YAML scalar type constants (from yaml library).
+ * These match the string values expected by the yaml package.
+ * @see https://github.com/eemeli/yaml/blob/main/docs/03_options.md
+ */
+const YAML_SCALAR_TYPES = Object.freeze({
+    /** Unquoted string (when safe) */
+    PLAIN: 'PLAIN',
+    /** Single-quoted string */
+    QUOTE_SINGLE: 'QUOTE_SINGLE',
+    /** Double-quoted string */
+    QUOTE_DOUBLE: 'QUOTE_DOUBLE',
+    /** Block literal (|) */
+    BLOCK_LITERAL: 'BLOCK_LITERAL',
+    /** Block folded (>) */
+    BLOCK_FOLDED: 'BLOCK_FOLDED',
+});
+/** Standard line width for WU YAML files */
+const YAML_LINE_WIDTH = 100;
+/**
+ * WU-1352: Standardized YAML stringify options.
+ *
+ * Ensures consistent output across all WU tools:
+ * - lineWidth: 100 (wrap long lines)
+ * - singleQuote: true (prefer 'single' over "double")
+ * - defaultKeyType: PLAIN (unquoted keys when safe)
+ *
+ * @type {import('yaml').ToStringOptions}
+ */
+export const YAML_STRINGIFY_OPTIONS = Object.freeze({
+    lineWidth: YAML_LINE_WIDTH,
+    singleQuote: true,
+    defaultKeyType: YAML_SCALAR_TYPES.PLAIN,
+});
+/**
+ * Read and parse WU YAML file.
+ *
+ * Validates:
+ * - File exists
+ * - YAML is valid
+ * - WU ID matches expected ID
+ *
+ * @param {string} wuPath - Path to WU YAML file
+ * @param {string} expectedId - Expected WU ID (e.g., 'WU-123')
+ * @returns {object} Parsed YAML document
+ * @throws {Error} If file not found, YAML invalid, or ID mismatch
+ */
+export function readWU(wuPath, expectedId) {
+    if (!existsSync(wuPath)) {
+        throw createError(ErrorCodes.FILE_NOT_FOUND, `WU file not found: ${wuPath}`, {
+            path: wuPath,
+            expectedId,
+        });
+    }
+    const text = readFileSync(wuPath, { encoding: 'utf-8' });
+    let doc;
+    try {
+        doc = parse(text);
+    }
+    catch (e) {
+        throw createError(ErrorCodes.YAML_PARSE_ERROR, `Failed to parse YAML ${wuPath}: ${e.message}`, {
+            path: wuPath,
+            originalError: e.message,
+        });
+    }
+    // Validate ID matches
+    if (!doc || doc.id !== expectedId) {
+        throw createError(ErrorCodes.WU_NOT_FOUND, `WU YAML id mismatch. Expected ${expectedId}, found ${doc && doc.id}`, { path: wuPath, expectedId, foundId: doc && doc.id });
+    }
+    return doc;
+}
+/**
+ * Read and parse WU YAML file asynchronously.
+ *
+ * Validates:
+ * - File exists
+ * - YAML is valid
+ * - WU ID matches expected ID
+ *
+ * @param {string} wuPath - Path to WU YAML file
+ * @param {string} expectedId - Expected WU ID (e.g., 'WU-123')
+ * @returns {Promise<object>} Parsed YAML document
+ * @throws {Error} If file not found, YAML invalid, or ID mismatch
+ */
+export async function readWUAsync(wuPath, expectedId) {
+    try {
+        const text = await fs.readFile(wuPath, { encoding: 'utf-8' });
+        let doc;
+        try {
+            doc = parse(text);
+        }
+        catch (e) {
+            throw createError(ErrorCodes.YAML_PARSE_ERROR, `Failed to parse YAML ${wuPath}: ${e.message}`, {
+                path: wuPath,
+                originalError: e.message,
+            });
+        }
+        // Validate ID matches
+        if (!doc || doc.id !== expectedId) {
+            throw createError(ErrorCodes.WU_NOT_FOUND, `WU YAML id mismatch. Expected ${expectedId}, found ${doc && doc.id}`, { path: wuPath, expectedId, foundId: doc && doc.id });
+        }
+        return doc;
+    }
+    catch (err) {
+        if (err.code === 'ENOENT') {
+            throw createError(ErrorCodes.FILE_NOT_FOUND, `WU file not found: ${wuPath}`, {
+                path: wuPath,
+                expectedId,
+            });
+        }
+        throw err;
+    }
+}
+/**
+ * Parse YAML string to object.
+ * WU-1352: Centralized YAML parsing for consistency.
+ *
+ * @param {string} text - YAML string to parse
+ * @returns {object} Parsed object
+ * @throws {Error} If YAML is invalid
+ */
+export function parseYAML(text) {
+    return parse(text);
+}
+/**
+ * Stringify object to YAML with standardized options.
+ * WU-1352: Centralized YAML serialization for consistency.
+ *
+ * @param {object} doc - Object to stringify
+ * @param {object} [options] - Additional stringify options (merged with YAML_STRINGIFY_OPTIONS)
+ * @returns {string} YAML string
+ */
+export function stringifyYAML(doc, options = {}) {
+    return stringify(doc, { ...YAML_STRINGIFY_OPTIONS, ...options });
+}
+/**
+ * Read and parse YAML file without ID validation.
+ * WU-1352: For cases where you don't know/need to validate the WU ID.
+ *
+ * @param {string} yamlPath - Path to YAML file
+ * @returns {object} Parsed YAML document
+ * @throws {Error} If file not found or YAML invalid
+ */
+export function readWURaw(yamlPath) {
+    if (!existsSync(yamlPath)) {
+        throw createError(ErrorCodes.FILE_NOT_FOUND, `YAML file not found: ${yamlPath}`, {
+            path: yamlPath,
+        });
+    }
+    const text = readFileSync(yamlPath, { encoding: 'utf-8' });
+    try {
+        return parse(text);
+    }
+    catch (e) {
+        throw createError(ErrorCodes.YAML_PARSE_ERROR, `Failed to parse YAML ${yamlPath}: ${e.message}`, {
+            path: yamlPath,
+            originalError: e.message,
+        });
+    }
+}
+/**
+ * Read and parse YAML file without ID validation asynchronously.
+ * WU-1352: For cases where you don't know/need to validate the WU ID.
+ *
+ * @param {string} yamlPath - Path to YAML file
+ * @returns {Promise<object>} Parsed YAML document
+ * @throws {Error} If file not found or YAML invalid
+ */
+export async function readWURawAsync(yamlPath) {
+    try {
+        const text = await fs.readFile(yamlPath, { encoding: 'utf-8' });
+        try {
+            return parse(text);
+        }
+        catch (e) {
+            throw createError(ErrorCodes.YAML_PARSE_ERROR, `Failed to parse YAML ${yamlPath}: ${e.message}`, {
+                path: yamlPath,
+                originalError: e.message,
+            });
+        }
+    }
+    catch (err) {
+        if (err.code === 'ENOENT') {
+            throw createError(ErrorCodes.FILE_NOT_FOUND, `YAML file not found: ${yamlPath}`, {
+                path: yamlPath,
+            });
+        }
+        throw err;
+    }
+}
+/**
+ * Write WU YAML file with consistent formatting.
+ * WU-1352: Uses YAML_STRINGIFY_OPTIONS for consistent output.
+ *
+ * @param {string} wuPath - Path to WU YAML file
+ * @param {object} doc - YAML document to write
+ */
+export function writeWU(wuPath, doc) {
+    const out = stringify(doc, YAML_STRINGIFY_OPTIONS);
+    writeFileSync(wuPath, out, { encoding: 'utf-8' });
+}
+/**
+ * Append note to WU document's notes field.
+ *
+ * Always outputs a string (Zod schema requires string type).
+ * Handles various input formats:
+ * - undefined/null/empty: Set note directly as string
+ * - string: Append with newline separator
+ * - array: Convert to newline-separated string, then append
+ * - other: Replace with note
+ *
+ * @param {object} doc - WU document
+ * @param {string} note - Note to append
+ */
+export function appendNote(doc, note) {
+    // Do nothing if note is falsy
+    if (!note)
+        return;
+    const existing = doc.notes;
+    if (existing === undefined || existing === null || existing === '') {
+        // No existing notes: set directly as string
+        doc.notes = note;
+    }
+    else if (Array.isArray(existing)) {
+        // Array notes: convert to string first (schema requires string), then append
+        const joined = existing.filter(Boolean).join(STRING_LITERALS.NEWLINE).trimEnd();
+        doc.notes = joined ? `${joined}${STRING_LITERALS.NEWLINE}${note}` : note;
+    }
+    else if (typeof existing === 'string') {
+        // String notes: append with newline
+        const trimmed = existing.trimEnd();
+        doc.notes = trimmed ? `${trimmed}${STRING_LITERALS.NEWLINE}${note}` : note;
+    }
+    else {
+        // Invalid type: replace with note
+        doc.notes = note;
+    }
+}
+/**
+ * Append an agent session entry to a WU's agent_sessions[] array
+ *
+ * @param {string} wuId - WU ID (e.g., "WU-1234")
+ * @param {object} sessionData - Session summary from endSession()
+ * @throws {Error} if WU file not found
+ */
+export function appendAgentSession(wuId, sessionData) {
+    const paths = createWuPaths();
+    const wuPath = paths.WU(wuId);
+    if (!existsSync(wuPath)) {
+        throw new Error(`WU file not found: ${wuPath}`);
+    }
+    // Parse WU YAML
+    const doc = readWU(wuPath, wuId);
+    // Initialize agent_sessions array if needed
+    if (!Array.isArray(doc.agent_sessions)) {
+        doc.agent_sessions = [];
+    }
+    // Append session
+    doc.agent_sessions.push(sessionData);
+    // Write back
+    writeWU(wuPath, doc);
+}
+//# sourceMappingURL=wu-yaml.js.map