@jokerized/getresearchdone 0.4.1

package/dist/lib/parallel.js

@@ -0,0 +1,349 @@
+'use strict';
+Object.defineProperty(exports, "__esModule", { value: true });
+const { output, loadConfig, findPhaseInternal, getMilestoneInfo, } = require('./utils');
+const { detectBackend, getBackendCapabilities, } = require('./backend');
+const { worktreePath, } = require('./worktree');
+const { buildDependencyGraph, } = require('./deps');
+const { analyzeRoadmap, } = require('./roadmap');
+const { runPreflightGates, } = require('./gates');
+// ─── validateIndependentPhases ──────────────────────────────────────────────
+/**
+ * Validate that requested phases have no direct dependency edges between them.
+ *
+ * Only checks DIRECT edges (not transitive paths). This is correct because the
+ * command template already receives parallel_groups from deps analysis for ordering.
+ * The validation here prevents the user from requesting two phases where one
+ * directly depends on the other.
+ * @param graph - Dependency graph containing all phase edges
+ * @param requestedPhases - Array of phase number strings to validate
+ * @returns Validation result indicating whether phases are independent, with any conflict pairs
+ */
+function validateIndependentPhases(graph, requestedPhases) {
+    if (requestedPhases.length <= 1) {
+        return { valid: true, phases: requestedPhases };
+    }
+    const requestedSet = new Set(requestedPhases);
+    const conflicts = [];
+    for (const edge of graph.edges) {
+        if (requestedSet.has(edge.from) && requestedSet.has(edge.to)) {
+            conflicts.push({ from: edge.from, to: edge.to });
+        }
+    }
+    if (conflicts.length > 0) {
+        return { valid: false, conflicts, phases: requestedPhases };
+    }
+    return { valid: true, phases: requestedPhases };
+}
+// ─── buildParallelContext ───────────────────────────────────────────────────
+/**
+ * Build structured JSON context for parallel execution of multiple phases.
+ *
+ * Loads config, detects backend capabilities, resolves per-phase info (directory,
+ * plans, worktree paths), and selects parallel vs sequential mode. Returns a
+ * context object consumed by the execute-phase command template.
+ * @param cwd - Absolute path to the working directory (project root)
+ * @param phaseNumbers - Array of phase number strings to build context for
+ * @param options - Optional configuration for native worktree availability
+ * @returns Full parallel execution context, or an error object if a phase is not found
+ */
+function buildParallelContext(cwd, phaseNumbers, options) {
+    const { nativeWorktreeAvailable = false } = options || {};
+    const config = loadConfig(cwd);
+    const backend = detectBackend(cwd);
+    const capabilities = getBackendCapabilities(backend);
+    const milestone = getMilestoneInfo(cwd);
+    // Determine mode: parallel only if backend supports teams AND config allows it
+    const mode = capabilities.teams === true && config.use_teams !== false ? 'parallel' : 'sequential';
+    // Build fallback note for sequential mode
+    const fallback_note = mode === 'sequential'
+        ? 'Parallel execution available on Claude Code backend with teams enabled'
+        : null;
+    // Build per-phase context objects
+    const phaseContexts = [];
+    for (const phaseNum of phaseNumbers) {
+        const phaseInfo = findPhaseInternal(cwd, phaseNum);
+        if (!phaseInfo) {
+            return { error: `Phase ${phaseNum} not found` };
+        }
+        const template = config.phase_branch_template || 'grd/{milestone}/{phase}-{slug}';
+        const worktree_branch = template
+            .replace('{milestone}', milestone.version)
+            .replace('{phase}', phaseInfo.phase_number)
+            .replace('{slug}', phaseInfo.phase_slug || 'phase');
+        // When native isolation is available, skip worktree_path pre-computation
+        // Claude Code creates worktrees natively via its isolation: worktree mechanism
+        const wt_path = nativeWorktreeAvailable
+            ? null
+            : worktreePath(cwd, milestone.version, phaseInfo.phase_number);
+        phaseContexts.push({
+            phase_number: phaseInfo.phase_number,
+            phase_name: phaseInfo.phase_name,
+            phase_slug: phaseInfo.phase_slug,
+            phase_dir: phaseInfo.directory,
+            worktree_path: wt_path,
+            worktree_branch,
+            native_isolation: nativeWorktreeAvailable,
+            plans: phaseInfo.plans,
+            incomplete_plans: phaseInfo.incomplete_plans,
+            plan_count: phaseInfo.plans ? phaseInfo.plans.length : 0,
+        });
+    }
+    // Build status tracker with per-phase pending state
+    const status_tracker = { phases: {} };
+    for (const ctx of phaseContexts) {
+        status_tracker.phases[ctx.phase_number] = { status: 'pending' };
+    }
+    return {
+        mode,
+        fallback_note,
+        backend,
+        backend_capabilities: capabilities,
+        use_teams: config.use_teams,
+        team_timeout_minutes: config.team_timeout_minutes,
+        max_concurrent_teammates: config.max_concurrent_teammates,
+        milestone_version: milestone.version,
+        milestone_name: milestone.name,
+        phases: phaseContexts,
+        phase_count: phaseNumbers.length,
+        status_tracker,
+    };
+}
+/**
+ * Assign plans to execution waves using a combined dependency model.
+ *
+ * Merges two dependency mechanisms into a single constraint set per plan:
+ * 1. Explicit `depends_on` field in PLAN.md frontmatter (coarse phase-level gates).
+ * 2. Fine-grained artifact DAG: for each plan's `requires` entries, look up the
+ *    provider plan in `artifactDAG.providers` and treat it as a hard dependency.
+ *
+ * Kahn's level-based topological sort assigns each plan to the earliest wave where
+ * all its dependencies have been satisfied. Plans without `provides`/`requires`
+ * fields (empty arrays) are backward compatible — they only respect `depends_on`.
+ *
+ * If a cycle is detected (remaining plans with unresolvable dependencies), all
+ * remaining plans are placed in the last wave and a warning is written to stderr.
+ *
+ * @param plans - Plan artifacts parsed from PLAN.md frontmatter
+ * @param options - Optional config including a pre-built ArtifactDAG
+ * @returns Array of WaveAssignment objects sorted by wave number
+ */
+function buildWaves(plans, options) {
+    if (plans.length === 0) {
+        return [];
+    }
+    const artifactDAG = options?.artifactDAG;
+    // Build plan ID for each plan using the same format as buildArtifactDAG
+    const planIdOf = (p) => `${p.phase}-${String(p.plan).padStart(2, '0')}`;
+    // Build a set of all valid plan IDs for membership checks
+    const planIds = new Set(plans.map(planIdOf));
+    // Build combined dependency set for each plan
+    // combined deps: Set<planId> that must be completed before this plan
+    const combinedDeps = new Map();
+    for (const plan of plans) {
+        const id = planIdOf(plan);
+        const deps = new Set();
+        // 1. Explicit depends_on: these are plan IDs like "94-01" directly
+        for (const dep of plan.depends_on) {
+            if (planIds.has(dep)) {
+                deps.add(dep);
+            }
+        }
+        // 2. Artifact DAG requires: look up each required artifact's provider plan
+        if (artifactDAG !== undefined) {
+            for (const artifact of plan.requires) {
+                const providerPlanId = artifactDAG.providers[artifact];
+                if (providerPlanId !== undefined && providerPlanId !== id && planIds.has(providerPlanId)) {
+                    deps.add(providerPlanId);
+                }
+            }
+        }
+        combinedDeps.set(id, deps);
+    }
+    // Build in-degree and adjacency for Kahn's algorithm
+    // Edge: dependency → dependent (dep must run before dependent)
+    const adjacency = new Map(); // dep → [dependents]
+    const inDegree = new Map();
+    for (const id of planIds) {
+        adjacency.set(id, []);
+        inDegree.set(id, 0);
+    }
+    for (const [id, deps] of combinedDeps) {
+        for (const dep of deps) {
+            adjacency.get(dep).push(id);
+            inDegree.set(id, inDegree.get(id) + 1);
+        }
+    }
+    // Level-based Kahn's — each iteration yields one wave
+    const waves = [];
+    const remaining = new Set(planIds);
+    let waveNumber = 1;
+    while (remaining.size > 0) {
+        const batch = [];
+        for (const id of remaining) {
+            if (inDegree.get(id) === 0) {
+                batch.push(id);
+            }
+        }
+        if (batch.length === 0) {
+            // Cycle detected — place all remaining plans in the last wave and warn
+            process.stderr.write(`[buildWaves] Warning: cycle detected among plans [${Array.from(remaining).join(', ')}]; placing all in wave ${waveNumber}\n`);
+            batch.push(...Array.from(remaining));
+            batch.sort();
+            waves.push({ wave: waveNumber, plans: batch });
+            break;
+        }
+        // Sort lexicographically for deterministic output
+        batch.sort();
+        waves.push({ wave: waveNumber, plans: batch });
+        // Decrement in-degree for dependents and remove from remaining
+        for (const id of batch) {
+            remaining.delete(id);
+            for (const dependent of adjacency.get(id)) {
+                if (remaining.has(dependent)) {
+                    inDegree.set(dependent, inDegree.get(dependent) - 1);
+                }
+            }
+        }
+        waveNumber++;
+    }
+    return waves;
+}
+// ─── cmdInitExecuteParallel ─────────────────────────────────────────────────
+/**
+ * CLI command: Validate phase independence and build parallel execution context.
+ *
+ * Follows the established cmdInit* pattern: validates inputs, runs preflight gates,
+ * checks roadmap for requested phases, validates independence via dependency graph,
+ * builds context, and outputs structured JSON.
+ * @param cwd - Absolute path to the working directory (project root)
+ * @param phaseNumbers - Array of phase number strings requested for parallel execution
+ * @param _includes - Unused set of include filters (reserved for future use)
+ * @param raw - Whether to output plain text instead of JSON
+ * @returns void (outputs JSON or error to stdout)
+ */
+function cmdInitExecuteParallel(cwd, phaseNumbers, _includes, raw) {
+    // Validate at least one phase requested
+    if (!phaseNumbers || phaseNumbers.length === 0) {
+        output({ error: 'At least one phase number is required' }, raw);
+        return;
+    }
+    // Run preflight gates (reuse execute-phase gates with first phase)
+    const gates = runPreflightGates(cwd, 'execute-phase', {
+        phase: phaseNumbers[0],
+    });
+    if (!gates.passed) {
+        output({ gate_failed: true, gate_errors: gates.errors, gate_warnings: gates.warnings }, raw);
+        return;
+    }
+    // Analyze roadmap to get all phases
+    const roadmapResult = analyzeRoadmap(cwd);
+    if (roadmapResult.error || !roadmapResult.phases || roadmapResult.phases.length === 0) {
+        output({ error: roadmapResult.error || 'ROADMAP.md not found or empty' }, raw);
+        return;
+    }
+    // Verify all requested phases exist in roadmap
+    const roadmapPhaseNumbers = new Set(roadmapResult.phases.map((p) => p.number));
+    const missing = phaseNumbers.filter((pn) => !roadmapPhaseNumbers.has(pn));
+    if (missing.length > 0) {
+        output({ error: `Phase(s) not found in roadmap: ${missing.join(', ')}` }, raw);
+        return;
+    }
+    // Build dependency graph and validate independence
+    const graph = buildDependencyGraph(roadmapResult.phases);
+    const validation = validateIndependentPhases(graph, phaseNumbers);
+    if (!validation.valid) {
+        const conflictStr = validation
+            .conflicts.map((c) => `Phase ${c.from} -> Phase ${c.to}`)
+            .join(', ');
+        output({
+            error: `Phases are not independent: ${conflictStr}`,
+            conflicts: validation.conflicts,
+        }, raw);
+        return;
+    }
+    // Build parallel context with native isolation awareness
+    const backend = detectBackend(cwd);
+    const capabilities = getBackendCapabilities(backend);
+    const context = buildParallelContext(cwd, phaseNumbers, {
+        nativeWorktreeAvailable: capabilities.native_worktree_isolation,
+    });
+    if (context.error) {
+        output(context, raw, `Error: ${context.error}`);
+        return;
+    }
+    // Add independence validation flag
+    context.independence_validated = true;
+    // Include gate warnings if any
+    if (gates.warnings && gates.warnings.length > 0) {
+        context.gate_warnings = gates.warnings;
+    }
+    output(context, raw, `Backend: ${context.backend}, ${context.phase_count} phases, mode: ${context.mode}`);
+}
+// ─── formatProgressBar ──────────────────────────────────────────────────────
+/**
+ * Format a progress bar string like `[####______] 40%`
+ */
+function formatProgressBar(current, total, width) {
+    const barWidth = width || 20;
+    const pct = total === 0 ? 0 : Math.min(1, current / total);
+    const filled = Math.round(pct * barWidth);
+    const empty = barWidth - filled;
+    const bar = '#'.repeat(filled) + '_'.repeat(empty);
+    const pctLabel = Math.round(pct * 100) + '%';
+    return `[${bar}] ${pctLabel}`;
+}
+// ─── streamPhaseProgress ────────────────────────────────────────────────────
+/**
+ * Write formatted phase progress to stderr.
+ */
+function streamPhaseProgress(phaseNum, current, total, status) {
+    const padded = String(phaseNum).padStart(2, '0');
+    const bar = formatProgressBar(current, total);
+    const statusPart = status ? ` [${status}]` : '';
+    const line = `Phase ${padded}: ${current} of ${total} ${bar}${statusPart}\n`;
+    process.stderr.write(line);
+}
+// ─── cmdParallelProgress ────────────────────────────────────────────────────
+/**
+ * CLI command for progress updates during parallel execution.
+ * Accepts --phase, --plan, --total-plans, --status args.
+ */
+function cmdParallelProgress(args, raw) {
+    // Parse args
+    let phase = null;
+    let plan = null;
+    let totalPlans = null;
+    let status = null;
+    for (let i = 0; i < args.length; i++) {
+        if (args[i] === '--phase' && args[i + 1])
+            phase = args[++i];
+        else if (args[i] === '--plan' && args[i + 1])
+            plan = parseInt(args[++i], 10);
+        else if (args[i] === '--total-plans' && args[i + 1])
+            totalPlans = parseInt(args[++i], 10);
+        else if (args[i] === '--status' && args[i + 1])
+            status = args[++i];
+    }
+    if (phase === null || plan === null || totalPlans === null) {
+        output({ error: 'Usage: parallel-progress --phase N --plan M --total-plans T [--status label]' }, raw);
+        return;
+    }
+    const bar = formatProgressBar(plan, totalPlans);
+    if (raw) {
+        output({ phase, plan, total_plans: totalPlans, bar, status }, raw);
+    }
+    else {
+        streamPhaseProgress(phase, plan, totalPlans, status || undefined);
+    }
+}
+// ─── Exports ──────────────────────────────────────────────────────────────────
+module.exports = {
+    validateIndependentPhases,
+    buildParallelContext,
+    buildWaves,
+    cmdInitExecuteParallel,
+    formatProgressBar,
+    streamPhaseProgress,
+    cmdParallelProgress,
+};
+//# sourceMappingURL=parallel.js.map

package/dist/lib/parallel.js.map

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

package/dist/lib/paths.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=paths.d.ts.map

package/dist/lib/paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../../lib/paths.ts"],"names":[],"mappings":""}

package/dist/lib/paths.js

@@ -0,0 +1,254 @@
+'use strict';
+Object.defineProperty(exports, "__esModule", { value: true });
+const fs = require('fs');
+const path = require('path');
+// ─── Milestone Detection ────────────────────────────────────────────────────
+/**
+ * Read the current milestone version from STATE.md.
+ *
+ * Reads the **Milestone:** field from .planning/STATE.md and extracts
+ * the version string (e.g., 'v0.2.1'). Returns 'anonymous' when
+ * STATE.md is missing, unreadable, has no Milestone field, or the
+ * field value contains no version string.
+ * @param cwd - Absolute path to the working directory (project root)
+ * @returns Current milestone version string (e.g., 'v0.2.1'), or 'anonymous' if not found
+ */
+function currentMilestone(cwd) {
+    const statePath = path.join(cwd, '.planning', 'STATE.md');
+    let content;
+    try {
+        content = fs.readFileSync(statePath, 'utf-8');
+    }
+    catch {
+        return inferMilestoneFromDisk(cwd);
+    }
+    // Extract the **Milestone:** field value
+    const fieldMatch = content.match(/\*\*Milestone:\*\*\s*(.+)/i);
+    if (!fieldMatch)
+        return inferMilestoneFromDisk(cwd);
+    const fieldValue = fieldMatch[1].trim();
+    if (!fieldValue)
+        return inferMilestoneFromDisk(cwd);
+    // Extract just the version string (vX.Y or vX.Y.Z etc.)
+    const versionMatch = fieldValue.match(/(v[\d.]+)/);
+    if (!versionMatch)
+        return inferMilestoneFromDisk(cwd);
+    return versionMatch[1];
+}
+/**
+ * Fallback: infer milestone from ROADMAP.md and .planning/milestones/ directory.
+ *
+ * Mirrors the 4-strategy approach from getMilestoneInfo() in utils.js
+ * (duplicated here to avoid circular dependency: utils.js imports paths.js).
+ * Falls back to scanning milestones/ directory if ROADMAP.md parsing fails.
+ */
+function inferMilestoneFromDisk(cwd) {
+    // Collect active milestone directories on disk
+    const msDir = path.join(cwd, '.planning', 'milestones');
+    let activeDirs = [];
+    try {
+        const entries = fs.readdirSync(msDir, { withFileTypes: true });
+        activeDirs = entries
+            .filter((e) => e.isDirectory() && !e.name.endsWith('-phases') && e.name !== 'anonymous')
+            .map((e) => e.name);
+    }
+    catch {
+        // milestones dir doesn't exist
+    }
+    // If exactly one active milestone dir, use it directly
+    if (activeDirs.length === 1)
+        return activeDirs[0];
+    // If multiple dirs exist, disambiguate via ROADMAP.md
+    if (activeDirs.length > 1) {
+        const fromRoadmap = parseRoadmapMilestone(cwd);
+        if (fromRoadmap && activeDirs.includes(fromRoadmap))
+            return fromRoadmap;
+    }
+    return 'anonymous';
+}
+/**
+ * Parse ROADMAP.md for the active milestone version string.
+ * Mirrors strategies 1-3 from getMilestoneInfo() in utils.js.
+ * (Duplicated here to avoid circular dependency: utils.js imports paths.js.)
+ */
+function parseRoadmapMilestone(cwd) {
+    try {
+        const raw = fs.readFileSync(path.join(cwd, '.planning', 'ROADMAP.md'), 'utf-8');
+        const roadmap = raw.replace(/<details>[\s\S]*?<\/details>/gi, '');
+        // Strategy 1: "(in progress)" milestone bullet
+        const inProgress = roadmap.match(/-\s+(v[\d.]+)\s+[^\n(]+?\s*\(in progress\)/im);
+        if (inProgress)
+            return inProgress[1];
+        // Strategy 2: Last non-shipped milestone bullet
+        const bulletRegex = /-\s+(v[\d.]+)\s+[^\n(]+?(?:\s*\(([^)]*)\))?\s*$/gim;
+        let lastNonShipped = null;
+        let m;
+        while ((m = bulletRegex.exec(roadmap)) !== null) {
+            if (!/shipped/i.test(m[2] || ''))
+                lastNonShipped = m[1];
+        }
+        if (lastNonShipped)
+            return lastNonShipped;
+        // Strategy 3: Heading format "## vX.Y.Z: Name"
+        const headingMatch = roadmap.match(/^##\s+(?!#).*?(v\d+\.\d+(?:\.\d+)?)\s*[:\s]+([^\n(]+)/m);
+        if (headingMatch)
+            return headingMatch[1];
+    }
+    catch {
+        // ROADMAP.md doesn't exist
+    }
+    return null;
+}
+// ─── Internal Helper ────────────────────────────────────────────────────────
+/**
+ * Return the milestone root directory path.
+ */
+function milestoneRoot(cwd, milestone) {
+    return path.join(cwd, '.planning', 'milestones', milestone);
+}
+// ─── Directory Path Functions ───────────────────────────────────────────────
+/**
+ * Root milestones container directory.
+ */
+function milestonesDir(cwd) {
+    return path.join(cwd, '.planning', 'milestones');
+}
+/**
+ * Milestone-scoped phases directory.
+ *
+ * Always returns the milestone-scoped path (.planning/milestones/{milestone}/phases/).
+ * Callers should use fs.mkdirSync({ recursive: true }) to ensure the directory exists.
+ * @param cwd - Absolute path to the working directory (project root)
+ * @param milestone - Milestone version string (e.g., 'v0.2.1'); defaults to current milestone if omitted
+ * @returns Absolute path to the milestone-scoped phases directory
+ */
+function phasesDir(cwd, milestone) {
+    if (milestone == null) {
+        milestone = currentMilestone(cwd);
+    }
+    const milestonesBase = path.join(cwd, '.planning', 'milestones');
+    const resolved = path.join(milestoneRoot(cwd, milestone), 'phases');
+    if (!resolved.startsWith(milestonesBase + path.sep) && resolved !== milestonesBase) {
+        throw new Error(`Invalid milestone: path would escape .planning directory`);
+    }
+    return resolved;
+}
+/**
+ * Specific phase subdirectory within a milestone.
+ *
+ * Uses phasesDir() for the base path, inheriting its backward-compatible fallback.
+ */
+function phaseDir(cwd, milestone, phaseDirName) {
+    const base = phasesDir(cwd, milestone);
+    const resolved = path.join(base, phaseDirName);
+    if (!resolved.startsWith(base + path.sep) && resolved !== base) {
+        throw new Error(`Invalid phase directory: path would escape phases directory`);
+    }
+    return resolved;
+}
+/**
+ * Milestone-scoped research directory.
+ */
+function researchDir(cwd, milestone) {
+    if (milestone == null) {
+        milestone = currentMilestone(cwd);
+    }
+    return path.join(milestoneRoot(cwd, milestone), 'research');
+}
+/**
+ * Project-level codebase analysis directory.
+ *
+ * Always returns .planning/codebase/ -- codebase maps are project-wide,
+ * not scoped to a specific milestone.
+ * @param cwd - Absolute path to the working directory (project root)
+ * @returns Absolute path to the .planning/codebase/ directory
+ */
+function codebaseDir(cwd) {
+    return path.join(cwd, '.planning', 'codebase');
+}
+/**
+ * Milestone-scoped todos directory.
+ */
+function todosDir(cwd, milestone) {
+    if (milestone == null) {
+        milestone = currentMilestone(cwd);
+    }
+    return path.join(milestoneRoot(cwd, milestone), 'todos');
+}
+/**
+ * Milestone-scoped discussions directory.
+ * Created at runtime by runDiscussion() via mkdirSync({ recursive: true }).
+ */
+function discussionsDir(cwd, milestone) {
+    if (milestone == null) {
+        milestone = currentMilestone(cwd);
+    }
+    const milestonesBase = path.join(cwd, '.planning', 'milestones');
+    const resolved = path.join(milestoneRoot(cwd, milestone), 'discussions');
+    if (!resolved.startsWith(milestonesBase + path.sep) && resolved !== milestonesBase) {
+        throw new Error('Invalid milestone: path would escape .planning directory');
+    }
+    return resolved;
+}
+/**
+ * Milestone-scoped quick tasks directory.
+ */
+function quickDir(cwd, milestone) {
+    if (milestone == null) {
+        milestone = currentMilestone(cwd);
+    }
+    return path.join(milestoneRoot(cwd, milestone), 'quick');
+}
+/**
+ * Archived phases directory for a completed milestone.
+ *
+ * Matches the existing archive layout where completed milestone phases
+ * are stored as {version}-phases/ directories.
+ * @param cwd - Absolute path to the working directory (project root)
+ * @param version - Milestone version string used to form the archive directory name (e.g., 'v0.2.1')
+ * @returns Absolute path to the archived phases directory (e.g., .planning/milestones/v0.2.1-phases/)
+ */
+function archivedPhasesDir(cwd, version) {
+    const milestonesBase = path.join(cwd, '.planning', 'milestones');
+    const resolved = path.join(milestonesBase, version + '-phases');
+    if (!resolved.startsWith(milestonesBase + path.sep) && resolved !== milestonesBase) {
+        throw new Error(`Invalid version: path would escape .planning directory`);
+    }
+    return resolved;
+}
+/**
+ * Milestone-scoped standards directory.
+ */
+function standardsDir(cwd, milestone) {
+    if (milestone == null) {
+        milestone = currentMilestone(cwd);
+    }
+    return path.join(milestoneRoot(cwd, milestone), 'standards');
+}
+// ─── Exports ────────────────────────────────────────────────────────────────
+/**
+ * Root .planning directory path.
+ *
+ * Single source of truth for the .planning/ directory location.
+ * Use this instead of hardcoding path.join(cwd, '.planning', ...) constructions.
+ * @param cwd - Absolute path to the working directory (project root)
+ * @returns Absolute path to the .planning/ directory
+ */
+function planningDir(cwd) {
+    return path.join(cwd, '.planning');
+}
+module.exports = {
+    currentMilestone,
+    planningDir,
+    milestonesDir,
+    phasesDir,
+    phaseDir,
+    researchDir,
+    codebaseDir,
+    todosDir,
+    discussionsDir,
+    quickDir,
+    standardsDir,
+    archivedPhasesDir,
+};
+//# sourceMappingURL=paths.js.map

package/dist/lib/paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.js","sourceRoot":"","sources":["../../lib/paths.ts"],"names":[],"mappings":"AAAA,YAAY,CAAC;;AAiBb,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AACzB,MAAM,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;AAE7B,+EAA+E;AAE/E;;;;;;;;;GASG;AACH,SAAS,gBAAgB,CAAC,GAAW;IACnC,MAAM,SAAS,GAAW,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,WAAW,EAAE,UAAU,CAAC,CAAC;IAElE,IAAI,OAAe,CAAC;IACpB,IAAI,CAAC;QACH,OAAO,GAAG,EAAE,CAAC,YAAY,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;IAChD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,sBAAsB,CAAC,GAAG,CAAC,CAAC;IACrC,CAAC;IAED,yCAAyC;IACzC,MAAM,UAAU,GAA4B,OAAO,CAAC,KAAK,CAAC,4BAA4B,CAAC,CAAC;IACxF,IAAI,CAAC,UAAU;QAAE,OAAO,sBAAsB,CAAC,GAAG,CAAC,CAAC;IAEpD,MAAM,UAAU,GAAW,UAAU,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IAChD,IAAI,CAAC,UAAU;QAAE,OAAO,sBAAsB,CAAC,GAAG,CAAC,CAAC;IAEpD,wDAAwD;IACxD,MAAM,YAAY,GAA4B,UAAU,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC;IAC5E,IAAI,CAAC,YAAY;QAAE,OAAO,sBAAsB,CAAC,GAAG,CAAC,CAAC;IAEtD,OAAO,YAAY,CAAC,CAAC,CAAC,CAAC;AACzB,CAAC;AAED;;;;;;GAMG;AACH,SAAS,sBAAsB,CAAC,GAAW;IACzC,+CAA+C;IAC/C,MAAM,KAAK,GAAW,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,WAAW,EAAE,YAAY,CAAC,CAAC;IAChE,IAAI,UAAU,GAAa,EAAE,CAAC;IAC9B,IAAI,CAAC;QACH,MAAM,OAAO,GAAa,EAAE,CAAC,WAAW,CAAC,KAAK,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;QACzE,UAAU,GAAG,OAAO;aACjB,MAAM,CACL,CAAC,CAAS,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,IAAI,KAAK,WAAW,CACxF;aACA,GAAG,CAAC,CAAC,CAAS,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;IAChC,CAAC;IAAC,MAAM,CAAC;QACP,+BAA+B;IACjC,CAAC;IAED,uDAAuD;IACvD,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,UAAU,CAAC,CAAC,CAAC,CAAC;IAElD,sDAAsD;IACtD,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC1B,MAAM,WAAW,GAAkB,qBAAqB,CAAC,GAAG,CAAC,CAAC;QAC9D,IAAI,WAAW,IAAI,UAAU,CAAC,QAAQ,CAAC,WAAW,CAAC;YAAE,OAAO,WAAW,CAAC;IAC1E,CAAC;IAED,OAAO,WAAW,CAAC;AACrB,CAAC;AAED;;;;GAIG;AACH,SAAS,qBAAqB,CAAC,GAAW;IACxC,IAAI,CAAC;QACH,MAAM,GAAG,GAAW,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,WAAW,EAAE,YAAY,CAAC,EAAE,OAAO,CAAC,CAAC;QACxF,MAAM,OAAO,GAAW,GAAG,CAAC,OAAO,CAAC,gCAAgC,EAAE,EAAE,CAAC,CAAC;QAE1E,+CAA+C;QAC/C,MAAM,UAAU,GAA4B,OAAO,CAAC,KAAK,CACvD,8CAA8C,CAC/C,CAAC;QACF,IAAI,UAAU;YAAE,OAAO,UAAU,CAAC,CAAC,CAAC,CAAC;QAErC,gDAAgD;QAChD,MAAM,WAAW,GAAG,oDAAoD,CAAC;QACzE,IAAI,cAAc,GAAkB,IAAI,CAAC;QACzC,IAAI,CAAyB,CAAC;QAC9B,OAAO,CAAC,CAAC,GAAG,WAAW,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC;YAChD,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;gBAAE,cAAc,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;QAC1D,CAAC;QACD,IAAI,cAAc;YAAE,OAAO,cAAc,CAAC;QAE1C,+CAA+C;QAC/C,MAAM,YAAY,GAA4B,OAAO,CAAC,KAAK,CACzD,wDAAwD,CACzD,CAAC;QACF,IAAI,YAAY;YAAE,OAAO,YAAY,CAAC,CAAC,CAAC,CAAC;IAC3C,CAAC;IAAC,MAAM,CAAC;QACP,2BAA2B;IAC7B,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,+EAA+E;AAE/E;;GAEG;AACH,SAAS,aAAa,CAAC,GAAW,EAAE,SAAiB;IACnD,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,WAAW,EAAE,YAAY,EAAE,SAAS,CAAC,CAAC;AAC9D,CAAC;AAED,+EAA+E;AAE/E;;GAEG;AACH,SAAS,aAAa,CAAC,GAAW;IAChC,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,WAAW,EAAE,YAAY,CAAC,CAAC;AACnD,CAAC;AAED;;;;;;;;GAQG;AACH,SAAS,SAAS,CAAC,GAAW,EAAE,SAAyB;IACvD,IAAI,SAAS,IAAI,IAAI,EAAE,CAAC;QACtB,SAAS,GAAG,gBAAgB,CAAC,GAAG,CAAC,CAAC;IACpC,CAAC;IACD,MAAM,cAAc,GAAW,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,WAAW,EAAE,YAAY,CAAC,CAAC;IACzE,MAAM,QAAQ,GAAW,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC,GAAG,EAAE,SAAS,CAAC,EAAE,QAAQ,CAAC,CAAC;IAC5E,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,cAAc,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,QAAQ,KAAK,cAAc,EAAE,CAAC;QACnF,MAAM,IAAI,KAAK,CAAC,0DAA0D,CAAC,CAAC;IAC9E,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;GAIG;AACH,SAAS,QAAQ,CAAC,GAAW,EAAE,SAA6B,EAAE,YAAoB;IAChF,MAAM,IAAI,GAAW,SAAS,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;IAC/C,MAAM,QAAQ,GAAW,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,YAAY,CAAC,CAAC;IACvD,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,QAAQ,KAAK,IAAI,EAAE,CAAC;QAC/D,MAAM,IAAI,KAAK,CAAC,6DAA6D,CAAC,CAAC;IACjF,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;GAEG;AACH,SAAS,WAAW,CAAC,GAAW,EAAE,SAAyB;IACzD,IAAI,SAAS,IAAI,IAAI,EAAE,CAAC;QACtB,SAAS,GAAG,gBAAgB,CAAC,GAAG,CAAC,CAAC;IACpC,CAAC;IACD,OAAO,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC,GAAG,EAAE,SAAS,CAAC,EAAE,UAAU,CAAC,CAAC;AAC9D,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,WAAW,CAAC,GAAW;IAC9B,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,WAAW,EAAE,UAAU,CAAC,CAAC;AACjD,CAAC;AAED;;GAEG;AACH,SAAS,QAAQ,CAAC,GAAW,EAAE,SAAyB;IACtD,IAAI,SAAS,IAAI,IAAI,EAAE,CAAC;QACtB,SAAS,GAAG,gBAAgB,CAAC,GAAG,CAAC,CAAC;IACpC,CAAC;IACD,OAAO,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC,GAAG,EAAE,SAAS,CAAC,EAAE,OAAO,CAAC,CAAC;AAC3D,CAAC;AAED;;;GAGG;AACH,SAAS,cAAc,CAAC,GAAW,EAAE,SAAyB;IAC5D,IAAI,SAAS,IAAI,IAAI,EAAE,CAAC;QACtB,SAAS,GAAG,gBAAgB,CAAC,GAAG,CAAC,CAAC;IACpC,CAAC;IACD,MAAM,cAAc,GAAW,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,WAAW,EAAE,YAAY,CAAC,CAAC;IACzE,MAAM,QAAQ,GAAW,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC,GAAG,EAAE,SAAS,CAAC,EAAE,aAAa,CAAC,CAAC;IACjF,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,cAAc,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,QAAQ,KAAK,cAAc,EAAE,CAAC;QACnF,MAAM,IAAI,KAAK,CAAC,0DAA0D,CAAC,CAAC;IAC9E,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;GAEG;AACH,SAAS,QAAQ,CAAC,GAAW,EAAE,SAAyB;IACtD,IAAI,SAAS,IAAI,IAAI,EAAE,CAAC;QACtB,SAAS,GAAG,gBAAgB,CAAC,GAAG,CAAC,CAAC;IACpC,CAAC;IACD,OAAO,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC,GAAG,EAAE,SAAS,CAAC,EAAE,OAAO,CAAC,CAAC;AAC3D,CAAC;AAED;;;;;;;;GAQG;AACH,SAAS,iBAAiB,CAAC,GAAW,EAAE,OAAe;IACrD,MAAM,cAAc,GAAW,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,WAAW,EAAE,YAAY,CAAC,CAAC;IACzE,MAAM,QAAQ,GAAW,IAAI,CAAC,IAAI,CAAC,cAAc,EAAE,OAAO,GAAG,SAAS,CAAC,CAAC;IACxE,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,cAAc,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,QAAQ,KAAK,cAAc,EAAE,CAAC;QACnF,MAAM,IAAI,KAAK,CAAC,wDAAwD,CAAC,CAAC;IAC5E,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;GAEG;AACH,SAAS,YAAY,CAAC,GAAW,EAAE,SAAyB;IAC1D,IAAI,SAAS,IAAI,IAAI,EAAE,CAAC;QACtB,SAAS,GAAG,gBAAgB,CAAC,GAAG,CAAC,CAAC;IACpC,CAAC;IACD,OAAO,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC,GAAG,EAAE,SAAS,CAAC,EAAE,WAAW,CAAC,CAAC;AAC/D,CAAC;AAED,+EAA+E;AAE/E;;;;;;;GAOG;AACH,SAAS,WAAW,CAAC,GAAW;IAC9B,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,WAAW,CAAC,CAAC;AACrC,CAAC;AAED,MAAM,CAAC,OAAO,GAAG;IACf,gBAAgB;IAChB,WAAW;IACX,aAAa;IACb,SAAS;IACT,QAAQ;IACR,WAAW;IACX,WAAW;IACX,QAAQ;IACR,cAAc;IACd,QAAQ;IACR,YAAY;IACZ,iBAAiB;CAClB,CAAC"}

package/dist/lib/phase-complete-llm.d.ts

@@ -0,0 +1,22 @@
+import type { GateViolation, PhaseCompleteResult } from './types';
+import type { Scheduler } from './scheduler';
+export declare function _verifyFallbackOutput(cwd: string, phaseNum: string): {
+    ok: boolean;
+    checks: {
+        name: string;
+        passed: boolean;
+    }[];
+};
+/**
+ * Attempts to recover from a mechanical phase-completion failure by
+ * asking Claude to perform the ROADMAP.md and STATE.md edits directly.
+ * Returns a synthetic PhaseCompleteResult on success, null on any
+ * failure or when the scheduler is null.
+ *
+ * Retries up to `phase_complete_llm_fallback_retries` times (default 0)
+ * with exponential backoff: 2^attempt seconds between retries (2s, 4s, …).
+ */
+export declare function attemptLlmFallbackCompletion(cwd: string, phaseNum: string, scheduler: Scheduler | null, failure: Error | {
+    gate_errors?: GateViolation[];
+}): Promise<PhaseCompleteResult | null>;
+//# sourceMappingURL=phase-complete-llm.d.ts.map