specweave 0.28.68 → 0.29.0

package/dist/src/hooks/processor.js

@@ -0,0 +1,317 @@
+#!/usr/bin/env node
+/**
+ * Background Event Processor (Cross-Platform)
+ *
+ * Processes queued events asynchronously, routes to specialized handlers.
+ * Works on Windows, macOS, and Linux without WSL requirement.
+ *
+ * Usage: node processor.js [--daemon]
+ *
+ * Event routing:
+ * - increment.created/done/archived/reopened -> living-specs-handler
+ * - user-story.completed/reopened -> status-line-handler
+ * - task.updated/spec.updated -> living-docs-handler (legacy)
+ *
+ * Self-terminates after 60s of idle
+ *
+ * @module hooks/processor
+ */
+import * as path from 'path';
+import * as fs from 'fs';
+import { spawn } from 'child_process';
+import { findProjectRoot, FileLock, appendLog, isWindows, } from './platform.js';
+// Configuration
+const IDLE_TIMEOUT = 60; // seconds before self-termination
+const HANDLER_TIMEOUT = 30000; // ms per handler call
+const STALE_LOCK_SECONDS = 300; // 5 minutes
+/**
+ * Initialize processor state
+ */
+function initState(projectRoot, daemonMode) {
+    const specweavePath = path.join(projectRoot, '.specweave');
+    return {
+        projectRoot,
+        queueDir: path.join(specweavePath, 'state', 'event-queue'),
+        handlerDir: path.join(projectRoot, 'plugins', 'specweave', 'hooks', 'v2', 'handlers'),
+        logFile: path.join(specweavePath, 'logs', 'processor.log'),
+        pidFile: path.join(specweavePath, 'state', '.processor.pid'),
+        lock: new FileLock(path.join(specweavePath, 'state', '.processor')),
+        daemonMode,
+        idleCount: 0,
+    };
+}
+/**
+ * Dequeue an event from the queue directory
+ */
+function dequeue(state) {
+    try {
+        if (!fs.existsSync(state.queueDir)) {
+            return null;
+        }
+        // Get oldest event file
+        const files = fs.readdirSync(state.queueDir)
+            .filter((f) => f.endsWith('.json'))
+            .sort(); // Oldest first (timestamp-based naming)
+        if (files.length === 0) {
+            return null;
+        }
+        const eventFile = path.join(state.queueDir, files[0]);
+        const content = fs.readFileSync(eventFile, 'utf-8');
+        // Delete after reading
+        fs.unlinkSync(eventFile);
+        return JSON.parse(content);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Run a handler script with timeout
+ */
+async function runHandler(handlerPath, eventType, eventData, state) {
+    if (!fs.existsSync(handlerPath)) {
+        return;
+    }
+    return new Promise((resolve) => {
+        let child;
+        let timeoutId;
+        const cleanup = () => {
+            clearTimeout(timeoutId);
+            try {
+                child?.kill();
+            }
+            catch {
+                // Ignore kill errors
+            }
+            resolve();
+        };
+        try {
+            if (isWindows()) {
+                // On Windows, run bash scripts via Git Bash if available, or skip
+                const gitBashPath = findGitBash();
+                if (gitBashPath) {
+                    child = spawn(gitBashPath, [handlerPath, eventType, eventData], {
+                        cwd: state.projectRoot,
+                        stdio: 'ignore',
+                        windowsHide: true,
+                    });
+                }
+                else {
+                    // No Git Bash - try to run via WSL if available (FALLBACK only)
+                    const wslPath = path.join(process.env.SYSTEMROOT || 'C:\\Windows', 'System32', 'wsl.exe');
+                    if (fs.existsSync(wslPath)) {
+                        // Convert Windows path to WSL path:
+                        // 1. Backslashes to forward slashes: C:\path\file -> C:/path/file
+                        // 2. Drive letter to /mnt/: C:/path/file -> /mnt/c/path/file
+                        // NOTE: Handle BOTH uppercase and lowercase drive letters (C: and c:)
+                        const wslHandlerPath = handlerPath
+                            .replace(/\\/g, '/')
+                            .replace(/^([A-Za-z]):/, (_, drive) => `/mnt/${drive.toLowerCase()}`);
+                        child = spawn('wsl', ['bash', wslHandlerPath, eventType, eventData], {
+                            cwd: state.projectRoot,
+                            stdio: 'ignore',
+                            windowsHide: true,
+                        });
+                    }
+                    else {
+                        // No bash available - skip handler
+                        appendLog(state.logFile, `Skipped handler (no bash): ${path.basename(handlerPath)}`);
+                        resolve();
+                        return;
+                    }
+                }
+            }
+            else {
+                // POSIX - run directly
+                child = spawn('bash', [handlerPath, eventType, eventData], {
+                    cwd: state.projectRoot,
+                    stdio: 'ignore',
+                });
+            }
+            // Set timeout
+            timeoutId = setTimeout(() => {
+                appendLog(state.logFile, `Handler timeout: ${path.basename(handlerPath)}`);
+                cleanup();
+            }, HANDLER_TIMEOUT);
+            child.on('exit', cleanup);
+            child.on('error', cleanup);
+        }
+        catch (err) {
+            appendLog(state.logFile, `Handler error: ${err}`);
+            resolve();
+        }
+    });
+}
+/**
+ * Cached Git Bash path (computed once at module load)
+ * undefined = not yet checked, null = checked and not found, string = path found
+ */
+let gitBashPathCache = undefined;
+/**
+ * Find Git Bash on Windows (with caching)
+ *
+ * Caches the result to avoid repeated filesystem checks.
+ * On Windows, checks common Git installation locations.
+ */
+function findGitBash() {
+    // Return cached result if available
+    if (gitBashPathCache !== undefined) {
+        return gitBashPathCache;
+    }
+    if (!isWindows()) {
+        gitBashPathCache = null;
+        return null;
+    }
+    const possiblePaths = [
+        // Standard Git for Windows installation paths
+        path.join(process.env.PROGRAMFILES || 'C:\\Program Files', 'Git', 'bin', 'bash.exe'),
+        path.join(process.env['PROGRAMFILES(X86)'] || 'C:\\Program Files (x86)', 'Git', 'bin', 'bash.exe'),
+        // User-specific installation
+        path.join(process.env.LOCALAPPDATA || '', 'Programs', 'Git', 'bin', 'bash.exe'),
+        // Portable Git / custom installation
+        'C:\\Git\\bin\\bash.exe',
+    ];
+    for (const bashPath of possiblePaths) {
+        if (bashPath && fs.existsSync(bashPath)) {
+            gitBashPathCache = bashPath;
+            return bashPath;
+        }
+    }
+    gitBashPathCache = null;
+    return null;
+}
+/**
+ * Process a single event
+ */
+async function processEvent(event, state) {
+    const { type, data } = event;
+    appendLog(state.logFile, `Processing: ${type} (${data})`);
+    const handlers = [
+        // EDA Event Routing (new architecture)
+        {
+            pattern: /^increment\.(created|done|archived|reopened)$/,
+            handlers: ['living-specs-handler.sh', 'status-line-handler.sh'],
+        },
+        {
+            pattern: /^user-story\.(completed|reopened)$/,
+            handlers: ['status-line-handler.sh'],
+        },
+        // Legacy event routing (backward compat)
+        {
+            pattern: /^(task|spec)\.updated$/,
+            handlers: ['living-docs-handler.sh', 'ac-validation-handler.sh'],
+        },
+        {
+            pattern: /^metadata\.changed$/,
+            handlers: ['github-sync-handler.sh'],
+        },
+    ];
+    for (const route of handlers) {
+        if (route.pattern.test(type)) {
+            for (const handlerName of route.handlers) {
+                const handlerPath = path.join(state.handlerDir, handlerName);
+                await runHandler(handlerPath, type, data, state);
+            }
+            return;
+        }
+    }
+    appendLog(state.logFile, `Unknown event type: ${type}`);
+}
+/**
+ * Main processing loop
+ */
+async function mainLoop(state) {
+    appendLog(state.logFile, `Processor started (PID: ${process.pid}, timeout: ${IDLE_TIMEOUT}s)`);
+    // Write PID file
+    fs.mkdirSync(path.dirname(state.pidFile), { recursive: true });
+    fs.writeFileSync(state.pidFile, String(process.pid), 'utf-8');
+    // Ensure queue directory exists
+    fs.mkdirSync(state.queueDir, { recursive: true });
+    while (true) {
+        const event = dequeue(state);
+        if (event) {
+            state.idleCount = 0;
+            await processEvent(event, state);
+        }
+        else {
+            state.idleCount++;
+            if (state.idleCount >= IDLE_TIMEOUT) {
+                appendLog(state.logFile, `Idle timeout (${IDLE_TIMEOUT}s), exiting`);
+                break;
+            }
+            // In non-daemon mode, exit after 3s of idle
+            if (!state.daemonMode && state.idleCount >= 3) {
+                break;
+            }
+            // Wait 1 second before checking again
+            await new Promise((resolve) => setTimeout(resolve, 1000));
+        }
+    }
+    // Cleanup
+    state.lock.release();
+    try {
+        fs.unlinkSync(state.pidFile);
+    }
+    catch {
+        // Ignore cleanup errors
+    }
+}
+/**
+ * Main entry point
+ */
+async function main() {
+    // Check if hooks disabled
+    if (process.env.SPECWEAVE_DISABLE_HOOKS === '1') {
+        return;
+    }
+    // Parse arguments
+    const daemonMode = process.argv.includes('--daemon');
+    // Find project root
+    const projectRoot = findProjectRoot();
+    if (!projectRoot) {
+        return;
+    }
+    // Initialize state
+    const state = initState(projectRoot, daemonMode);
+    // Try to acquire lock
+    if (!state.lock.acquire(STALE_LOCK_SECONDS)) {
+        // Another processor is running
+        return;
+    }
+    // Check PID file for extra safety
+    if (fs.existsSync(state.pidFile)) {
+        try {
+            const oldPid = parseInt(fs.readFileSync(state.pidFile, 'utf-8').trim(), 10);
+            if (!isNaN(oldPid)) {
+                try {
+                    process.kill(oldPid, 0);
+                    // Process is running - exit
+                    state.lock.release();
+                    return;
+                }
+                catch {
+                    // Process not running - continue
+                }
+            }
+        }
+        catch {
+            // Ignore PID file errors
+        }
+    }
+    // Run main loop
+    try {
+        await mainLoop(state);
+    }
+    catch (err) {
+        appendLog(state.logFile, `Processor error: ${err}`);
+    }
+    finally {
+        state.lock.release();
+    }
+}
+// Run if executed directly
+main().catch((err) => {
+    console.error('Processor fatal error:', err);
+    process.exit(1);
+});
+//# sourceMappingURL=processor.js.map

package/dist/src/hooks/processor.js.map

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

package/dist/src/hooks/scheduler-startup.d.ts

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+/**
+ * Scheduler Startup Check (Cross-Platform)
+ *
+ * Checks for due scheduled jobs on session start.
+ * Returns system message if jobs are ready to run.
+ *
+ * @module hooks/scheduler-startup
+ */
+/**
+ * Check for due scheduled jobs
+ *
+ * @param projectRoot - Project root directory
+ * @returns Object with systemMessage if jobs are due
+ */
+export declare function checkScheduledJobs(projectRoot?: string): Promise<{
+    systemMessage?: string;
+} | null>;
+//# sourceMappingURL=scheduler-startup.d.ts.map

package/dist/src/hooks/scheduler-startup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scheduler-startup.d.ts","sourceRoot":"","sources":["../../../src/hooks/scheduler-startup.ts"],"names":[],"mappings":";AACA;;;;;;;GAOG;AA4CH;;;;;GAKG;AACH,wBAAsB,kBAAkB,CACtC,WAAW,CAAC,EAAE,MAAM,GACnB,OAAO,CAAC;IAAE,aAAa,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAAC,CA0D5C"}

package/dist/src/hooks/scheduler-startup.js

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+/**
+ * Scheduler Startup Check (Cross-Platform)
+ *
+ * Checks for due scheduled jobs on session start.
+ * Returns system message if jobs are ready to run.
+ *
+ * @module hooks/scheduler-startup
+ */
+import * as path from 'path';
+import * as fs from 'fs';
+import { findProjectRoot, readJsonSafe, appendLog, outputHookResult } from './platform.js';
+/**
+ * Check for due scheduled jobs
+ *
+ * @param projectRoot - Project root directory
+ * @returns Object with systemMessage if jobs are due
+ */
+export async function checkScheduledJobs(projectRoot) {
+    const root = projectRoot || findProjectRoot();
+    if (!root) {
+        return null;
+    }
+    const configFile = path.join(root, '.specweave', 'config.json');
+    const scheduledJobsFile = path.join(root, '.specweave', 'state', 'scheduled-jobs.json');
+    const logFile = path.join(root, '.specweave', 'logs', 'scheduler.log');
+    // Check if scheduler is enabled
+    const config = readJsonSafe(configFile);
+    const schedulerEnabled = config?.sync?.orchestration?.scheduler?.enabled ?? false;
+    if (!schedulerEnabled) {
+        return null;
+    }
+    // Check if scheduled jobs file exists
+    if (!fs.existsSync(scheduledJobsFile)) {
+        return null;
+    }
+    // Read and parse scheduled jobs
+    const jobsData = readJsonSafe(scheduledJobsFile);
+    if (!jobsData?.jobs || !Array.isArray(jobsData.jobs)) {
+        return null;
+    }
+    // Find due jobs
+    const now = Date.now();
+    const dueJobs = jobsData.jobs.filter((job) => {
+        // Job must be enabled and idle
+        if (!job.schedule.enabled || job.status !== 'idle') {
+            return false;
+        }
+        // No nextRun means it should run now
+        if (!job.schedule.nextRun) {
+            return true;
+        }
+        // Check if nextRun has passed
+        const nextRunTime = new Date(job.schedule.nextRun).getTime();
+        return nextRunTime <= now;
+    });
+    if (dueJobs.length === 0) {
+        return null;
+    }
+    // Log due jobs
+    const dueJobIds = dueJobs.map((j) => j.id);
+    appendLog(logFile, `Due sync jobs: ${JSON.stringify(dueJobIds)}`);
+    return {
+        systemMessage: `Scheduled sync jobs ready to run. Use /specweave:sync-now to execute.`,
+    };
+}
+/**
+ * Main entry point (when run directly)
+ */
+async function main() {
+    // Check if hooks disabled
+    if (process.env.SPECWEAVE_DISABLE_HOOKS === '1') {
+        outputHookResult({ continue: true });
+        return;
+    }
+    const result = await checkScheduledJobs();
+    if (result?.systemMessage) {
+        outputHookResult({ continue: true, systemMessage: result.systemMessage });
+    }
+    else {
+        outputHookResult({ continue: true });
+    }
+}
+// Run if executed directly
+const isMainModule = import.meta.url === `file://${process.argv[1]}`;
+if (isMainModule) {
+    main().catch((err) => {
+        console.error(JSON.stringify({ continue: true, error: String(err) }));
+        process.exit(0);
+    });
+}
+//# sourceMappingURL=scheduler-startup.js.map

package/dist/src/hooks/scheduler-startup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scheduler-startup.js","sourceRoot":"","sources":["../../../src/hooks/scheduler-startup.ts"],"names":[],"mappings":";AACA;;;;;;;GAOG;AAEH,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAC7B,OAAO,KAAK,EAAE,MAAM,IAAI,CAAC;AACzB,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAwC3F;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,WAAoB;IAEpB,MAAM,IAAI,GAAG,WAAW,IAAI,eAAe,EAAE,CAAC;IAC9C,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,YAAY,EAAE,aAAa,CAAC,CAAC;IAChE,MAAM,iBAAiB,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,YAAY,EAAE,OAAO,EAAE,qBAAqB,CAAC,CAAC;IACxF,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,YAAY,EAAE,MAAM,EAAE,eAAe,CAAC,CAAC;IAEvE,gCAAgC;IAChC,MAAM,MAAM,GAAG,YAAY,CAAa,UAAU,CAAC,CAAC;IACpD,MAAM,gBAAgB,GAAG,MAAM,EAAE,IAAI,EAAE,aAAa,EAAE,SAAS,EAAE,OAAO,IAAI,KAAK,CAAC;IAElF,IAAI,CAAC,gBAAgB,EAAE,CAAC;QACtB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,sCAAsC;IACtC,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,iBAAiB,CAAC,EAAE,CAAC;QACtC,OAAO,IAAI,CAAC;IACd,CAAC;IAED,gCAAgC;IAChC,MAAM,QAAQ,GAAG,YAAY,CAAoB,iBAAiB,CAAC,CAAC;IACpE,IAAI,CAAC,QAAQ,EAAE,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QACrD,OAAO,IAAI,CAAC;IACd,CAAC;IAED,gBAAgB;IAChB,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IACvB,MAAM,OAAO,GAAG,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE;QAC3C,+BAA+B;QAC/B,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,OAAO,IAAI,GAAG,CAAC,MAAM,KAAK,MAAM,EAAE,CAAC;YACnD,OAAO,KAAK,CAAC;QACf,CAAC;QAED,qCAAqC;QACrC,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,OAAO,EAAE,CAAC;YAC1B,OAAO,IAAI,CAAC;QACd,CAAC;QAED,8BAA8B;QAC9B,MAAM,WAAW,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,OAAO,EAAE,CAAC;QAC7D,OAAO,WAAW,IAAI,GAAG,CAAC;IAC5B,CAAC,CAAC,CAAC;IAEH,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,eAAe;IACf,MAAM,SAAS,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IAC3C,SAAS,CAAC,OAAO,EAAE,kBAAkB,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;IAElE,OAAO;QACL,aAAa,EAAE,uEAAuE;KACvF,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,KAAK,UAAU,IAAI;IACjB,0BAA0B;IAC1B,IAAI,OAAO,CAAC,GAAG,CAAC,uBAAuB,KAAK,GAAG,EAAE,CAAC;QAChD,gBAAgB,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;QACrC,OAAO;IACT,CAAC;IAED,MAAM,MAAM,GAAG,MAAM,kBAAkB,EAAE,CAAC;IAE1C,IAAI,MAAM,EAAE,aAAa,EAAE,CAAC;QAC1B,gBAAgB,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,aAAa,EAAE,MAAM,CAAC,aAAa,EAAE,CAAC,CAAC;IAC5E,CAAC;SAAM,CAAC;QACN,gBAAgB,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;IACvC,CAAC;AACH,CAAC;AAED,2BAA2B;AAC3B,MAAM,YAAY,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,KAAK,UAAU,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;AACrE,IAAI,YAAY,EAAE,CAAC;IACjB,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;QACnB,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;QACtE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/src/hooks/session-start.d.ts

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+/**
+ * Session Start Hook (Cross-Platform)
+ *
+ * Launches background processor on session start.
+ * Works on Windows, macOS, and Linux without WSL requirement.
+ *
+ * Windows Support Strategy:
+ * 1. Git Bash (PRIMARY - required for production use)
+ * 2. WSL (FALLBACK - for development/emergency only)
+ * 3. Graceful degradation (skip bash handlers if neither available)
+ *
+ * @module hooks/session-start
+ */
+export {};
+//# sourceMappingURL=session-start.d.ts.map

package/dist/src/hooks/session-start.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-start.d.ts","sourceRoot":"","sources":["../../../src/hooks/session-start.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;GAYG"}

package/dist/src/hooks/session-start.js

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+/**
+ * Session Start Hook (Cross-Platform)
+ *
+ * Launches background processor on session start.
+ * Works on Windows, macOS, and Linux without WSL requirement.
+ *
+ * Windows Support Strategy:
+ * 1. Git Bash (PRIMARY - required for production use)
+ * 2. WSL (FALLBACK - for development/emergency only)
+ * 3. Graceful degradation (skip bash handlers if neither available)
+ *
+ * @module hooks/session-start
+ */
+import * as path from 'path';
+import * as fs from 'fs';
+import { fileURLToPath } from 'url';
+import { findProjectRoot, spawnNodeBackground, outputHookResult, consumeStdin, appendLog, } from './platform.js';
+// Proper cross-platform URL-to-path conversion
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+/**
+ * Check if hooks are disabled
+ */
+function isHooksDisabled() {
+    return process.env.SPECWEAVE_DISABLE_HOOKS === '1';
+}
+/**
+ * Main entry point
+ */
+async function main() {
+    // Check if hooks disabled
+    if (isHooksDisabled()) {
+        outputHookResult({ continue: true });
+        return;
+    }
+    // Find project root
+    const projectRoot = findProjectRoot();
+    if (!projectRoot) {
+        outputHookResult({ continue: true });
+        return;
+    }
+    // Consume stdin (required by hook protocol)
+    await consumeStdin();
+    const logFile = path.join(projectRoot, '.specweave', 'logs', 'session-start.log');
+    const distHooksDir = path.join(projectRoot, 'node_modules', 'specweave', 'dist', 'hooks');
+    // Check for processor script
+    // First try: built hooks in dist (production)
+    // Fallback: development mode - hooks relative to this file
+    let processorScript = path.join(distHooksDir, 'processor.js');
+    if (!fs.existsSync(processorScript)) {
+        // Development mode - use fileURLToPath for correct cross-platform path
+        processorScript = path.join(__dirname, 'processor.js');
+    }
+    // Launch processor in background (daemon mode)
+    if (fs.existsSync(processorScript)) {
+        const child = spawnNodeBackground(processorScript, ['--daemon'], projectRoot);
+        if (child) {
+            appendLog(logFile, `Processor started (PID: ${child.pid})`);
+        }
+    }
+    // Check for scheduler startup
+    let schedulerScript = path.join(distHooksDir, 'scheduler-startup.js');
+    if (!fs.existsSync(schedulerScript)) {
+        // Development mode - use fileURLToPath for correct cross-platform path
+        schedulerScript = path.join(__dirname, 'scheduler-startup.js');
+    }
+    // Run scheduler check (synchronously for hook response)
+    if (fs.existsSync(schedulerScript)) {
+        try {
+            // Dynamic import to run scheduler check
+            const schedulerModule = await import(schedulerScript);
+            if (typeof schedulerModule.checkScheduledJobs === 'function') {
+                const result = await schedulerModule.checkScheduledJobs(projectRoot);
+                if (result && result.systemMessage) {
+                    outputHookResult({ continue: true, systemMessage: result.systemMessage });
+                    return;
+                }
+            }
+        }
+        catch (err) {
+            appendLog(logFile, `Scheduler check failed: ${err}`);
+        }
+    }
+    outputHookResult({ continue: true });
+}
+// Run main
+main().catch((err) => {
+    console.error(JSON.stringify({ continue: true, error: String(err) }));
+    process.exit(0); // Don't block Claude Code on hook errors
+});
+//# sourceMappingURL=session-start.js.map

package/dist/src/hooks/session-start.js.map

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

package/dist/src/importers/duplicate-detector.d.ts

@@ -6,6 +6,7 @@
  */
 /**
  * External ID reference found in living docs
+ * CRITICAL (2025-12-01): Includes parent tracking for re-import hierarchy updates
  */
 export interface ExternalIdReference {
     /** User Story ID (e.g., US-001E) */
@@ -16,6 +17,14 @@ export interface ExternalIdReference {
     externalId: string;
     /** External platform (github, jira, ado) */
     platform?: string;
+    /** Feature ID this item belongs to (e.g., FS-001E) */
+    featureId?: string;
+    /** Parent work item ID in external tool (e.g., ADO-123) */
+    parentId?: string;
+    /** Whether this item was imported as orphan (no parent) */
+    isOrphan?: boolean;
+    /** ADO work item type (e.g., User Story, Bug) */
+    adoWorkItemType?: string;
 }
 /**
  * Options for duplicate detection
@@ -71,10 +80,12 @@ export declare class DuplicateDetector {
      */
     private findUserStoryFiles;
     /**
-     * Extract external_id from a User Story file
+     * Extract external_id and parent tracking info from a User Story file
+     *
+     * CRITICAL (2025-12-01): Also extracts parent info for re-import hierarchy updates
      *
      * @param filePath - Path to User Story markdown file
-     * @returns External ID reference if found, null otherwise
+     * @returns External ID reference with parent info if found, null otherwise
      */
     private extractExternalIdFromFile;
     /**

package/dist/src/importers/duplicate-detector.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"duplicate-detector.d.ts","sourceRoot":"","sources":["../../../src/importers/duplicate-detector.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAOH;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,oCAAoC;IACpC,IAAI,EAAE,MAAM,CAAC;IAEb,4CAA4C;IAC5C,QAAQ,EAAE,MAAM,CAAC;IAEjB,wBAAwB;IACxB,UAAU,EAAE,MAAM,CAAC;IAEnB,4CAA4C;IAC5C,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC,0CAA0C;IAC1C,QAAQ,EAAE,MAAM,CAAC;IAEjB,yCAAyC;IACzC,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED;;;;;GAKG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,OAAO,CAA2B;IAC1C,OAAO,CAAC,KAAK,CAAiD;gBAElD,OAAO,EAAE,wBAAwB;IAO7C;;;;;OAKG;IACG,uBAAuB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAKnE;;;;;OAKG;IACG,uBAAuB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,GAAG,IAAI,CAAC;IAUtF;;;;OAIG;IACG,iBAAiB,IAAI,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC;IAIpE;;OAEG;YACW,kBAAkB;IA4BhC;;;;;;;;OAQG;YACW,kBAAkB;IAYhC;;;;;OAKG;YACW,yBAAyB;IAkCvC;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAiB3B;;;;;;;;;;OAUG;IACH,OAAO,CAAC,mBAAmB;IAY3B;;OAEG;IACH,UAAU,IAAI,IAAI;IAIlB;;OAEG;IACH,aAAa,IAAI;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE;CAMpD;AAED;;;;;;GAMG;AACH,wBAAsB,uBAAuB,CAC3C,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,OAAO,CAAC,CAGlB"}
+{"version":3,"file":"duplicate-detector.d.ts","sourceRoot":"","sources":["../../../src/importers/duplicate-detector.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAOH;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,oCAAoC;IACpC,IAAI,EAAE,MAAM,CAAC;IAEb,4CAA4C;IAC5C,QAAQ,EAAE,MAAM,CAAC;IAEjB,wBAAwB;IACxB,UAAU,EAAE,MAAM,CAAC;IAEnB,4CAA4C;IAC5C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAGlB,sDAAsD;IACtD,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,2DAA2D;IAC3D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB,2DAA2D;IAC3D,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB,iDAAiD;IACjD,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC,0CAA0C;IAC1C,QAAQ,EAAE,MAAM,CAAC;IAEjB,yCAAyC;IACzC,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED;;;;;GAKG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,OAAO,CAA2B;IAC1C,OAAO,CAAC,KAAK,CAAiD;gBAElD,OAAO,EAAE,wBAAwB;IAO7C;;;;;OAKG;IACG,uBAAuB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAKnE;;;;;OAKG;IACG,uBAAuB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,GAAG,IAAI,CAAC;IAUtF;;;;OAIG;IACG,iBAAiB,IAAI,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC;IAIpE;;OAEG;YACW,kBAAkB;IA4BhC;;;;;;;;OAQG;YACW,kBAAkB;IAYhC;;;;;;;OAOG;YACW,yBAAyB;IAoDvC;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAiB3B;;;;;;;;;;OAUG;IACH,OAAO,CAAC,mBAAmB;IAY3B;;OAEG;IACH,UAAU,IAAI,IAAI;IAIlB;;OAEG;IACH,aAAa,IAAI;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE;CAMpD;AAED;;;;;;GAMG;AACH,wBAAsB,uBAAuB,CAC3C,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,OAAO,CAAC,CAGlB"}

package/dist/src/importers/duplicate-detector.js

@@ -97,10 +97,12 @@ export class DuplicateDetector {
         return files;
     }
     /**
-     * Extract external_id from a User Story file
+     * Extract external_id and parent tracking info from a User Story file
+     *
+     * CRITICAL (2025-12-01): Also extracts parent info for re-import hierarchy updates
      *
      * @param filePath - Path to User Story markdown file
-     * @returns External ID reference if found, null otherwise
+     * @returns External ID reference with parent info if found, null otherwise
      */
     async extractExternalIdFromFile(filePath) {
         try {
@@ -114,15 +116,32 @@ export class DuplicateDetector {
                     filePath,
                     externalId: String(parsed.data.external_id),
                     platform: parsed.data.external_platform,
+                    // Parent tracking from frontmatter
+                    featureId: parsed.data.feature_id,
+                    parentId: parsed.data.parent_id,
+                    isOrphan: parsed.data.is_orphan,
+                    adoWorkItemType: parsed.data.ado_work_item_type,
                 };
             }
             // Fallback: Parse external metadata section in content
             const externalIdMatch = content.match(/^-\s+\*\*External ID\*\*:\s+(.+)$/m);
             if (externalIdMatch) {
+                // Extract parent tracking info from content body
+                const featureIdMatch = content.match(/^-\s+\*\*Feature ID\*\*:\s+(.+)$/m);
+                const parentIdMatch = content.match(/^-\s+\*\*Parent ID\*\*:\s+(.+)$/m);
+                const orphanMatch = content.match(/^-\s+\*\*Orphan\*\*:\s+true/m);
+                const adoTypeMatch = content.match(/^-\s+\*\*ADO Work Item Type\*\*:\s+(.+)$/m);
+                const platformMatch = content.match(/^-\s+\*\*Platform\*\*:\s+(.+)$/m);
                 return {
                     usId: this.extractUsIdFromFile(filePath, content),
                     filePath,
                     externalId: externalIdMatch[1].trim(),
+                    platform: platformMatch?.[1]?.trim()?.toLowerCase(),
+                    // Parent tracking from content body
+                    featureId: featureIdMatch?.[1]?.trim(),
+                    parentId: parentIdMatch?.[1]?.trim(),
+                    isOrphan: !!orphanMatch,
+                    adoWorkItemType: adoTypeMatch?.[1]?.trim(),
                 };
             }
             return null;