@lumenflow/initiatives 1.0.0

package/dist/initiative-paths.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Centralized path constants for Initiative management scripts.
+ *
+ * Mirrors wu-paths.mjs pattern. Single source of truth for all
+ * initiative-related file paths.
+ *
+ * @example
+ * import { INIT_PATHS } from './lib/initiative-paths.js';
+ * const initPath = INIT_PATHS.INITIATIVE('INIT-001'); // 'docs/04-operations/tasks/initiatives/INIT-001.yaml'
+ */
+export declare const INIT_PATHS: {
+    /**
+     * Get path to Initiative YAML file
+     * @param {string} id - Initiative ID (e.g., 'INIT-001')
+     * @returns {string} Path to Initiative YAML file
+     */
+    INITIATIVE: (id: string) => string;
+    /**
+     * Get path to initiatives directory
+     * @returns {string} Path to initiatives directory
+     */
+    INITIATIVES_DIR: () => string;
+    /**
+     * Get path to WU directory (for scanning WUs by initiative)
+     * @returns {string} Path to WU directory
+     */
+    WU_DIR: () => string;
+};

package/dist/initiative-paths.js

@@ -0,0 +1,29 @@
+import path from 'node:path';
+/**
+ * Centralized path constants for Initiative management scripts.
+ *
+ * Mirrors wu-paths.mjs pattern. Single source of truth for all
+ * initiative-related file paths.
+ *
+ * @example
+ * import { INIT_PATHS } from './lib/initiative-paths.js';
+ * const initPath = INIT_PATHS.INITIATIVE('INIT-001'); // 'docs/04-operations/tasks/initiatives/INIT-001.yaml'
+ */
+export const INIT_PATHS = {
+    /**
+     * Get path to Initiative YAML file
+     * @param {string} id - Initiative ID (e.g., 'INIT-001')
+     * @returns {string} Path to Initiative YAML file
+     */
+    INITIATIVE: (id) => path.join('docs', '04-operations', 'tasks', 'initiatives', `${id}.yaml`),
+    /**
+     * Get path to initiatives directory
+     * @returns {string} Path to initiatives directory
+     */
+    INITIATIVES_DIR: () => path.join('docs', '04-operations', 'tasks', 'initiatives'),
+    /**
+     * Get path to WU directory (for scanning WUs by initiative)
+     * @returns {string} Path to WU directory
+     */
+    WU_DIR: () => path.join('docs', '04-operations', 'tasks', 'wu'),
+};

package/dist/initiative-schema.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Initiative YAML Schema (WU-1246)
+ *
+ * Zod schema for runtime validation of Initiative YAML structure.
+ * Part of the Initiative System Phase 1 - Schema & Validation Foundation.
+ *
+ * @see {@link tools/validate.mjs} - Consumer (CI validation)
+ * @see {@link tools/lib/initiative-validator.mjs} - Consumer (dependency graph validation)
+ * @see {@link docs/04-operations/tasks/initiatives/} - Initiative YAML files
+ */
+import { z } from 'zod';
+/**
+ * Zod schema for Initiative Phase
+ *
+ * Phases are optional subdivisions within an initiative.
+ * Sequence matters - phases are ordered by id.
+ */
+export declare const InitiativePhaseSchema: z.ZodObject<{
+    id: z.ZodNumber;
+    title: z.ZodString;
+    status: z.ZodEnum<{
+        in_progress: "in_progress";
+        done: "done";
+        pending: "pending";
+        blocked: "blocked";
+    }>;
+}, z.core.$strip>;
+/**
+ * Zod schema for Initiative YAML structure
+ *
+ * Initiatives group related WUs for visualization, progress tracking,
+ * and dependency management.
+ */
+export declare const InitiativeSchema: z.ZodObject<{
+    id: z.ZodString;
+    slug: z.ZodString;
+    title: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    status: z.ZodEnum<{
+        draft: "draft";
+        open: "open";
+        in_progress: "in_progress";
+        done: "done";
+        archived: "archived";
+    }>;
+    priority: z.ZodOptional<z.ZodEnum<{
+        P0: "P0";
+        P1: "P1";
+        P2: "P2";
+        P3: "P3";
+    }>>;
+    owner: z.ZodOptional<z.ZodString>;
+    created: z.ZodString;
+    target_date: z.ZodOptional<z.ZodString>;
+    phases: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodNumber;
+        title: z.ZodString;
+        status: z.ZodEnum<{
+            in_progress: "in_progress";
+            done: "done";
+            pending: "pending";
+            blocked: "blocked";
+        }>;
+    }, z.core.$strip>>>;
+    success_metrics: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    labels: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    wus: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+/**
+ * TypeScript type inferred from schema
+ *
+ * @typedef {import('zod').z.infer<typeof InitiativeSchema>} Initiative
+ * @typedef {import('zod').z.infer<typeof InitiativePhaseSchema>} InitiativePhase
+ */
+/**
+ * Validates Initiative data against schema
+ *
+ * @param {unknown} data - Parsed YAML data to validate
+ * @returns {z.SafeParseReturnType<Initiative, Initiative>} Validation result
+ *
+ * @example
+ * const result = validateInitiative(yamlData);
+ * if (!result.success) {
+ *   result.error.issues.forEach(issue => {
+ *     console.error(`${issue.path.join('.')}: ${issue.message}`);
+ *   });
+ * }
+ */
+export declare function validateInitiative(data: unknown): z.ZodSafeParseResult<{
+    id: string;
+    slug: string;
+    title: string;
+    status: "draft" | "open" | "in_progress" | "done" | "archived";
+    created: string;
+    description?: string;
+    priority?: "P0" | "P1" | "P2" | "P3";
+    owner?: string;
+    target_date?: string;
+    phases?: {
+        id: number;
+        title: string;
+        status: "in_progress" | "done" | "pending" | "blocked";
+    }[];
+    success_metrics?: string[];
+    labels?: string[];
+    wus?: string[];
+}>;

package/dist/initiative-schema.js

@@ -0,0 +1,103 @@
+/**
+ * Initiative YAML Schema (WU-1246)
+ *
+ * Zod schema for runtime validation of Initiative YAML structure.
+ * Part of the Initiative System Phase 1 - Schema & Validation Foundation.
+ *
+ * @see {@link tools/validate.mjs} - Consumer (CI validation)
+ * @see {@link tools/lib/initiative-validator.mjs} - Consumer (dependency graph validation)
+ * @see {@link docs/04-operations/tasks/initiatives/} - Initiative YAML files
+ */
+import { z } from 'zod';
+import { INIT_STATUSES, PHASE_STATUSES, PRIORITIES, INIT_PATTERNS, } from './initiative-constants.js';
+/**
+ * Date format pattern (YYYY-MM-DD)
+ * Note: Kept local as it's only used in schema validation, not elsewhere
+ */
+const DATE_PATTERN = INIT_PATTERNS.DATE;
+/**
+ * Zod schema for Initiative Phase
+ *
+ * Phases are optional subdivisions within an initiative.
+ * Sequence matters - phases are ordered by id.
+ */
+export const InitiativePhaseSchema = z.object({
+    /** Phase number (non-negative integer, determines sequence; 0 valid for foundation phases) */
+    id: z.number().int().nonnegative({ message: 'Phase id must be a non-negative integer' }),
+    /** Phase title */
+    title: z.string().min(1, { message: 'Phase title is required' }),
+    /** Phase status */
+    status: z.enum(PHASE_STATUSES, {
+        error: `Status must be one of: ${PHASE_STATUSES.join(', ')}`,
+    }),
+});
+/**
+ * Zod schema for Initiative YAML structure
+ *
+ * Initiatives group related WUs for visualization, progress tracking,
+ * and dependency management.
+ */
+export const InitiativeSchema = z.object({
+    /** Initiative identifier (INIT-NNN or INIT-NAME format) */
+    id: z
+        .string()
+        .regex(INIT_PATTERNS.INIT_ID, { message: 'ID must match pattern INIT-NNN or INIT-NAME' }),
+    /** Kebab-case unique identifier for URLs and references */
+    slug: z
+        .string()
+        .regex(INIT_PATTERNS.SLUG, { message: 'Slug must be kebab-case (e.g., shock-protocol)' }),
+    /** Initiative title */
+    title: z.string().min(1, { message: 'Title is required' }),
+    /** Detailed description (optional) */
+    description: z.string().optional(),
+    /** Initiative lifecycle status */
+    status: z.enum(INIT_STATUSES, {
+        error: `Status must be one of: ${INIT_STATUSES.join(', ')}`,
+    }),
+    /** Priority level (optional) */
+    priority: z
+        .enum(PRIORITIES, {
+        error: `Priority must be one of: ${PRIORITIES.join(', ')}`,
+    })
+        .optional(),
+    /** Owner (team or individual, optional) */
+    owner: z.string().optional(),
+    /** Creation date (YYYY-MM-DD) */
+    created: z.string().regex(DATE_PATTERN, { message: 'Created must be YYYY-MM-DD format' }),
+    /** Target completion date (optional, YYYY-MM-DD) */
+    target_date: z
+        .string()
+        .regex(DATE_PATTERN, { message: 'Target date must be YYYY-MM-DD format' })
+        .optional(),
+    /** Ordered phases within the initiative (optional) */
+    phases: z.array(InitiativePhaseSchema).optional(),
+    /** Success metrics for completion (optional) */
+    success_metrics: z.array(z.string()).optional(),
+    /** Labels for cross-cutting concerns (optional) */
+    labels: z.array(z.string()).optional(),
+    /** Linked WU IDs (optional, bidirectional link with WU.initiative field) */
+    wus: z.array(z.string()).optional(),
+});
+/**
+ * TypeScript type inferred from schema
+ *
+ * @typedef {import('zod').z.infer<typeof InitiativeSchema>} Initiative
+ * @typedef {import('zod').z.infer<typeof InitiativePhaseSchema>} InitiativePhase
+ */
+/**
+ * Validates Initiative data against schema
+ *
+ * @param {unknown} data - Parsed YAML data to validate
+ * @returns {z.SafeParseReturnType<Initiative, Initiative>} Validation result
+ *
+ * @example
+ * const result = validateInitiative(yamlData);
+ * if (!result.success) {
+ *   result.error.issues.forEach(issue => {
+ *     console.error(`${issue.path.join('.')}: ${issue.message}`);
+ *   });
+ * }
+ */
+export function validateInitiative(data) {
+    return InitiativeSchema.safeParse(data);
+}

package/dist/initiative-validator.d.ts

@@ -0,0 +1,143 @@
+/**
+ * Initiative Validator (WU-1246, WU-2319)
+ *
+ * Validates WU dependency graphs for cycles, orphan references,
+ * initiative consistency, and bidirectional WU-Initiative references.
+ *
+ * Part of the Initiative System Phase 1 - Schema & Validation Foundation.
+ * WU-2319: Added bidirectional validation for WU<->Initiative references.
+ *
+ * @see {@link tools/validate.mjs} - Consumer (CI validation)
+ * @see {@link tools/lib/initiative-schema.mjs} - Initiative schema
+ */
+/**
+ * WU object interface for validation
+ */
+interface WUObject {
+    id?: string;
+    blocks?: string[];
+    blocked_by?: string[];
+    initiative?: string;
+    phase?: number;
+    [key: string]: unknown;
+}
+/**
+ * Initiative object interface for validation
+ */
+interface InitiativeObject {
+    id?: string;
+    slug?: string;
+    wus?: string[];
+    phases?: Array<{
+        id: number;
+    }>;
+    [key: string]: unknown;
+}
+/**
+ * Orphan reference result
+ */
+interface OrphanRef {
+    wuId: string;
+    field: string;
+    ref: string;
+}
+/**
+ * Detects circular dependencies in WU dependency graph using DFS
+ *
+ * Uses standard cycle detection: tracks visited nodes and nodes in current
+ * recursion stack. If we encounter a node already in the recursion stack,
+ * we've found a cycle.
+ *
+ * @param {Map<string, Object>} wuMap - Map of WU ID to WU object
+ * @returns {{hasCycle: boolean, cycles: string[][]}} Cycle detection result
+ *
+ * @example
+ * const wuMap = new Map([
+ *   ['WU-001', { id: 'WU-001', blocks: ['WU-002'] }],
+ *   ['WU-002', { id: 'WU-002', blocks: ['WU-001'] }],
+ * ]);
+ * const result = detectCycles(wuMap);
+ * // result.hasCycle === true
+ * // result.cycles contains the cycle path
+ */
+export declare function detectCycles(wuMap: Map<string, WUObject>): {
+    hasCycle: boolean;
+    cycles: string[][];
+};
+export declare function detectOrphanRefs(wuMap: Map<string, WUObject>, allWuIds: Set<string>): {
+    orphans: OrphanRef[];
+};
+/**
+ * Validates initiative references in WUs
+ *
+ * Checks that:
+ * - Initiative field references exist (by ID or slug)
+ * - Phase numbers are defined in parent initiative
+ *
+ * Returns warnings (not errors) for soft enforcement.
+ *
+ * @param {Map<string, Object>} wuMap - Map of WU ID to WU object
+ * @param {Map<string, Object>} initiatives - Map of Initiative ID to Initiative object
+ * @returns {{warnings: string[]}} Validation warnings
+ *
+ * @example
+ * const wuMap = new Map([['WU-001', { id: 'WU-001', initiative: 'INIT-999' }]]);
+ * const initiatives = new Map();
+ * const result = validateInitiativeRefs(wuMap, initiatives);
+ * // result.warnings contains warning about missing initiative
+ */
+export declare function validateInitiativeRefs(wuMap: Map<string, WUObject>, initiatives: Map<string, InitiativeObject>): {
+    warnings: string[];
+};
+/**
+ * Validates bidirectional references between WUs and Initiatives (WU-2319)
+ *
+ * Checks two directions:
+ * 1. WU->Initiative: If WU has initiative: INIT-XXX, the initiative.wus must list the WU
+ * 2. Initiative->WU: If initiative.wus lists a WU, the WU should have initiative: field
+ *
+ * Also delegates to validateInitiativeRefs for phase mismatch detection.
+ *
+ * Note: All bidirectional mismatches are returned as ERRORS (not warnings).
+ * The caller (validateDependencyGraph) may choose to treat these as warnings
+ * for backward compatibility with pre-existing data inconsistencies.
+ *
+ * @param {Map<string, Object>} wuMap - Map of WU ID to WU object
+ * @param {Map<string, Object>} initiatives - Map of Initiative ID to Initiative object
+ * @returns {{errors: string[], warnings: string[]}} Validation results
+ *
+ * @example
+ * const wuMap = new Map([['WU-001', { id: 'WU-001', initiative: 'INIT-001' }]]);
+ * const initiatives = new Map([['INIT-001', { id: 'INIT-001', wus: ['WU-001'] }]]);
+ * const result = validateBidirectionalRefs(wuMap, initiatives);
+ * // result.errors === [] (all refs match)
+ */
+export declare function validateBidirectionalRefs(wuMap: Map<string, WUObject>, initiatives: Map<string, InitiativeObject>): {
+    errors: string[];
+    warnings: string[];
+};
+/**
+ * Validates the complete WU dependency graph
+ *
+ * Orchestrates all validation checks:
+ * 1. Cycle detection (error)
+ * 2. Orphan reference detection (error)
+ * 3. Initiative reference validation (warning)
+ * 4. Bidirectional WU-Initiative validation (error) [WU-2319]
+ *
+ * @param {Map<string, Object>} wuMap - Map of WU ID to WU object
+ * @param {Set<string>} allWuIds - Set of all known WU IDs
+ * @param {Map<string, Object>} initiatives - Map of Initiative ID to Initiative object
+ * @returns {{errors: string[], warnings: string[]}} Validation results
+ *
+ * @example
+ * const result = validateDependencyGraph(wuMap, allWuIds, initiatives);
+ * if (result.errors.length > 0) {
+ *   console.error('Validation failed:', result.errors);
+ * }
+ */
+export declare function validateDependencyGraph(wuMap: Map<string, WUObject>, allWuIds: Set<string>, initiatives: Map<string, InitiativeObject>): {
+    errors: string[];
+    warnings: string[];
+};
+export {};