gsd-pi 2.33.0-dev.bafba33 → 2.33.1-dev.235d83a

package/dist/resources/extensions/gsd/complexity-classifier.js

@@ -0,0 +1,257 @@
+// GSD Extension — Complexity Classifier
+// Classifies unit complexity for dynamic model routing.
+// Pure heuristics + adaptive learning — no LLM calls. Sub-millisecond classification.
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { gsdRoot } from "./paths.js";
+import { getAdaptiveTierAdjustment } from "./routing-history.js";
+import { parseUnitId } from "./unit-id.js";
+// ─── Unit Type → Default Tier Mapping ────────────────────────────────────────
+const UNIT_TYPE_TIERS = {
+    // Tier 1 — Light: structured summaries, completion, UAT
+    "complete-slice": "light",
+    "run-uat": "light",
+    // Tier 2 — Standard: research, routine planning
+    "research-milestone": "standard",
+    "research-slice": "standard",
+    "plan-milestone": "standard",
+    "plan-slice": "standard",
+    // Tier 3 — Heavy: execution, replanning (requires deep reasoning)
+    "execute-task": "standard", // default standard, upgraded by metadata
+    "replan-slice": "heavy",
+    "reassess-roadmap": "heavy",
+};
+// ─── Public API ──────────────────────────────────────────────────────────────
+/**
+ * Classify unit complexity to determine which model tier to use.
+ *
+ * @param unitType    The type of unit being dispatched
+ * @param unitId      The unit ID (e.g. "M001/S01/T01")
+ * @param basePath    Project base path (for reading task plans)
+ * @param budgetPct   Current budget usage as fraction (0.0-1.0+), or undefined if no budget
+ * @param metadata    Optional pre-parsed task metadata
+ */
+export function classifyUnitComplexity(unitType, unitId, basePath, budgetPct, metadata) {
+    // Hook units default to light
+    if (unitType.startsWith("hook/")) {
+        const result = { tier: "light", reason: "hook unit", downgraded: false };
+        return applyBudgetPressure(result, budgetPct);
+    }
+    // Start with the default tier for this unit type
+    let tier = UNIT_TYPE_TIERS[unitType] ?? "standard";
+    let reason = `unit type: ${unitType}`;
+    // For execute-task, analyze task metadata for complexity signals
+    if (unitType === "execute-task") {
+        const taskAnalysis = analyzeTaskComplexity(unitId, basePath, metadata);
+        tier = taskAnalysis.tier;
+        reason = taskAnalysis.reason;
+    }
+    // For plan-slice, check if the slice has many tasks (complex planning)
+    if (unitType === "plan-slice" || unitType === "plan-milestone") {
+        const planAnalysis = analyzePlanComplexity(unitId, basePath);
+        if (planAnalysis) {
+            tier = planAnalysis.tier;
+            reason = planAnalysis.reason;
+        }
+    }
+    // Adaptive learning: check if history suggests bumping the tier
+    const tags = metadata?.tags ?? extractTaskMetadata(unitId, basePath).tags;
+    const adaptiveAdjustment = getAdaptiveTierAdjustment(unitType, tier, tags);
+    if (adaptiveAdjustment && tierOrdinal(adaptiveAdjustment) > tierOrdinal(tier)) {
+        reason = `${reason} (adaptive: high failure rate at ${tier})`;
+        tier = adaptiveAdjustment;
+    }
+    const result = { tier, reason, downgraded: false };
+    return applyBudgetPressure(result, budgetPct);
+}
+/**
+ * Get a short label for the tier (for dashboard display).
+ */
+export function tierLabel(tier) {
+    switch (tier) {
+        case "light": return "L";
+        case "standard": return "S";
+        case "heavy": return "H";
+    }
+}
+/**
+ * Get the tier ordering value (for comparison).
+ */
+export function tierOrdinal(tier) {
+    switch (tier) {
+        case "light": return 0;
+        case "standard": return 1;
+        case "heavy": return 2;
+    }
+}
+function analyzeTaskComplexity(unitId, basePath, metadata) {
+    // Try to read task plan for complexity signals
+    const meta = metadata ?? extractTaskMetadata(unitId, basePath);
+    // Heavy signals
+    if (meta.dependencyCount && meta.dependencyCount >= 3) {
+        return { tier: "heavy", reason: `${meta.dependencyCount} dependencies` };
+    }
+    if (meta.fileCount && meta.fileCount >= 6) {
+        return { tier: "heavy", reason: `${meta.fileCount} files to modify` };
+    }
+    if (meta.estimatedLines && meta.estimatedLines >= 500) {
+        return { tier: "heavy", reason: `~${meta.estimatedLines} lines estimated` };
+    }
+    // Heavy signals from complexity keywords (Phase 4)
+    if (meta.complexityKeywords && meta.complexityKeywords.length >= 2) {
+        return { tier: "heavy", reason: `complex: ${meta.complexityKeywords.join(", ")}` };
+    }
+    if (meta.codeBlockCount && meta.codeBlockCount >= 5) {
+        return { tier: "heavy", reason: `${meta.codeBlockCount} code blocks in plan` };
+    }
+    // Standard signals from single complexity keyword
+    if (meta.complexityKeywords && meta.complexityKeywords.length === 1) {
+        return { tier: "standard", reason: `${meta.complexityKeywords[0]} task` };
+    }
+    // Light signals (simple tasks)
+    if (meta.tags?.some(t => /^(docs?|readme|comment|config|typo|rename)$/i.test(t))) {
+        return { tier: "light", reason: `simple task: ${meta.tags.join(", ")}` };
+    }
+    if (meta.fileCount !== undefined && meta.fileCount <= 1 && !meta.isNewFile) {
+        return { tier: "light", reason: "single file modification" };
+    }
+    // Standard by default
+    return { tier: "standard", reason: "standard execution task" };
+}
+function analyzePlanComplexity(unitId, basePath) {
+    // Check if this is a milestone-level plan (more complex) vs single slice
+    const { milestone: mid, slice: sid } = parseUnitId(unitId);
+    if (!sid) {
+        // Milestone-level planning is always at least standard
+        return { tier: "standard", reason: "milestone-level planning" };
+    }
+    // For slice planning, try to read the context/research to gauge complexity
+    // If research exists and is large, bump to heavy
+    const researchPath = join(gsdRoot(basePath), mid, "slices", sid, "RESEARCH.md");
+    try {
+        if (existsSync(researchPath)) {
+            const content = readFileSync(researchPath, "utf-8");
+            const lineCount = content.split("\n").length;
+            if (lineCount > 200) {
+                return { tier: "heavy", reason: `complex slice: ${lineCount}-line research` };
+            }
+        }
+    }
+    catch {
+        // Non-fatal
+    }
+    return null; // Use default tier
+}
+/**
+ * Extract task metadata from the task plan file on disk.
+ */
+function extractTaskMetadata(unitId, basePath) {
+    const meta = {};
+    const { milestone: mid, slice: sid, task: tid } = parseUnitId(unitId);
+    if (!mid || !sid || !tid)
+        return meta;
+    const taskPlanPath = join(gsdRoot(basePath), mid, "slices", sid, "tasks", `${tid}-PLAN.md`);
+    try {
+        if (!existsSync(taskPlanPath))
+            return meta;
+        const content = readFileSync(taskPlanPath, "utf-8");
+        const lines = content.split("\n");
+        // Count files mentioned in "Files:" or "- Files:" lines
+        const fileLines = lines.filter(l => /^\s*-?\s*files?\s*:/i.test(l));
+        if (fileLines.length > 0) {
+            // Count comma-separated or bullet-pointed files
+            const allFiles = new Set();
+            for (const line of fileLines) {
+                const filesStr = line.replace(/^\s*-?\s*files?\s*:\s*/i, "");
+                const files = filesStr.split(/[,;]/).map(f => f.trim()).filter(Boolean);
+                files.forEach(f => allFiles.add(f));
+            }
+            meta.fileCount = allFiles.size;
+        }
+        // Check for "new file" or "create" keywords
+        meta.isNewFile = lines.some(l => /\b(create|new file|scaffold|bootstrap)\b/i.test(l));
+        // Look for tags/labels in frontmatter or content
+        const tags = [];
+        if (content.match(/\b(refactor|migration|architect)/i))
+            tags.push("refactor");
+        if (content.match(/\b(test|spec|coverage)\b/i))
+            tags.push("test");
+        if (content.match(/\b(doc|readme|comment|jsdoc)\b/i))
+            tags.push("docs");
+        if (content.match(/\b(config|env|setting)\b/i))
+            tags.push("config");
+        if (content.match(/\b(rename|typo|spelling)\b/i))
+            tags.push("rename");
+        meta.tags = tags;
+        // Try to extract estimated lines from content
+        const estimateMatch = content.match(/~?\s*(\d+)\s*lines?\b/i);
+        if (estimateMatch) {
+            meta.estimatedLines = parseInt(estimateMatch[1], 10);
+        }
+        // Phase 4: Deeper introspection signals
+        // Count fenced code blocks (```) — more code blocks = more complex implementation
+        const codeBlockMatches = content.match(/^```/gm);
+        meta.codeBlockCount = codeBlockMatches ? Math.floor(codeBlockMatches.length / 2) : 0;
+        // Detect complexity keywords that suggest harder tasks
+        const complexityKeywords = [];
+        if (content.match(/\b(migration|migrate|schema change)\b/i))
+            complexityKeywords.push("migration");
+        if (content.match(/\b(architect|design pattern|system design)\b/i))
+            complexityKeywords.push("architecture");
+        if (content.match(/\b(security|auth|encrypt|credential|vulnerability)\b/i))
+            complexityKeywords.push("security");
+        if (content.match(/\b(performance|optimize|cache|index)\b/i))
+            complexityKeywords.push("performance");
+        if (content.match(/\b(concurrent|parallel|race condition|mutex|lock)\b/i))
+            complexityKeywords.push("concurrency");
+        if (content.match(/\b(backward.?compat|breaking change|deprecat)\b/i))
+            complexityKeywords.push("compatibility");
+        meta.complexityKeywords = complexityKeywords;
+    }
+    catch {
+        // Non-fatal — metadata extraction is best-effort
+    }
+    return meta;
+}
+// ─── Budget Pressure ─────────────────────────────────────────────────────────
+/**
+ * Apply budget pressure to a classification result.
+ * As budget usage increases, more aggressively downgrade tiers.
+ *
+ * - <50%:   Normal classification (no change)
+ * - 50-75%: Tier 2 → Tier 1 where possible
+ * - 75-90%: Only heavy tasks keep configured model
+ * - >90%:   Everything except replan-slice gets cheapest model
+ */
+function applyBudgetPressure(result, budgetPct) {
+    if (budgetPct === undefined || budgetPct < 0.5)
+        return result;
+    const original = result.tier;
+    if (budgetPct >= 0.9) {
+        // >90%: almost everything goes to light
+        if (result.tier !== "heavy") {
+            result.tier = "light";
+        }
+        else {
+            // Even heavy gets downgraded to standard
+            result.tier = "standard";
+        }
+    }
+    else if (budgetPct >= 0.75) {
+        // 75-90%: only heavy stays, everything else goes to light
+        if (result.tier === "standard") {
+            result.tier = "light";
+        }
+    }
+    else {
+        // 50-75%: standard → light
+        if (result.tier === "standard") {
+            result.tier = "light";
+        }
+    }
+    if (result.tier !== original) {
+        result.downgraded = true;
+        result.reason = `${result.reason} (budget pressure: ${Math.round(budgetPct * 100)}%)`;
+    }
+    return result;
+}

package/dist/resources/extensions/gsd/{constants.ts → constants.js}

@@ -3,19 +3,13 @@
  *
  * Centralized timeout and cache-size constants used across the GSD extension.
  */
-
 // ─── Timeouts ─────────────────────────────────────────────────────────────────
-
 /** Default timeout for verification-gate commands (ms). */
 export const DEFAULT_COMMAND_TIMEOUT_MS = 120_000;
-
 /** Default timeout for the dynamic bash tool (seconds). */
 export const DEFAULT_BASH_TIMEOUT_SECS = 120;
-
 // ─── Cache Sizes ──────────────────────────────────────────────────────────────
-
 /** Max directory-listing cache entries before eviction (#611). */
 export const DIR_CACHE_MAX = 200;
-
 /** Max parse-cache entries before eviction. */
 export const CACHE_MAX = 50;

package/dist/resources/extensions/gsd/context-budget.js

@@ -0,0 +1,187 @@
+/**
+ * Context budget engine — proportional allocation, section-boundary truncation,
+ * and executor context window resolution.
+ *
+ * All functions are pure or near-pure (dependency-injected). No global state, no I/O.
+ * Budget ratios are module-level constants for easy tuning.
+ *
+ * @see D001 (module location), D002 (200K fallback), D003 (section-boundary truncation)
+ */
+import { getCharsPerToken } from "./token-counter.js";
+import { compressToTarget } from "./prompt-compressor.js";
+// ─── Budget ratio constants ──────────────────────────────────────────────────
+// Percentages of total context window allocated to each budget category.
+// These are applied after tokens→chars conversion.
+/** Proportion of context window for dependency/prior-task summaries */
+const SUMMARY_RATIO = 0.15;
+/** Proportion of context window for inline context (plans, decisions, code) */
+const INLINE_CONTEXT_RATIO = 0.40;
+/** Proportion of context window for verification sections in prompts */
+const VERIFICATION_RATIO = 0.10;
+/** Approximate chars-per-token conversion factor */
+const CHARS_PER_TOKEN = 4;
+/** Default context window when none can be resolved (D002) */
+const DEFAULT_CONTEXT_WINDOW = 200_000;
+/** Percentage of context consumed before suggesting a continue-here checkpoint */
+const CONTINUE_THRESHOLD_PERCENT = 70;
+// ─── Task count bounds ───────────────────────────────────────────────────────
+// Task count range scales with context window. Smaller windows get fewer tasks
+// to avoid overloading the executor.
+const TASK_COUNT_MIN = 2;
+/** Task count ceiling tiers: [contextWindowThreshold, maxTasks] */
+const TASK_COUNT_TIERS = [
+    [500_000, 8], // 500K+ tokens → up to 8 tasks
+    [200_000, 6], // 200K+ tokens → up to 6 tasks
+    [128_000, 5], // 128K+ tokens → up to 5 tasks
+    [0, 3], // anything smaller → up to 3 tasks
+];
+// ─── Public API ──────────────────────────────────────────────────────────────
+/**
+ * Compute proportional budget allocations from a context window size (in tokens).
+ *
+ * Returns deterministic output for any given input. Invalid inputs (≤ 0)
+ * silently default to 200K (D002).
+ */
+export function computeBudgets(contextWindow, provider) {
+    const effectiveWindow = contextWindow > 0 ? contextWindow : DEFAULT_CONTEXT_WINDOW;
+    const charsPerToken = provider ? getCharsPerToken(provider) : CHARS_PER_TOKEN;
+    const totalChars = effectiveWindow * charsPerToken;
+    return {
+        summaryBudgetChars: Math.floor(totalChars * SUMMARY_RATIO),
+        inlineContextBudgetChars: Math.floor(totalChars * INLINE_CONTEXT_RATIO),
+        verificationBudgetChars: Math.floor(totalChars * VERIFICATION_RATIO),
+        continueThresholdPercent: CONTINUE_THRESHOLD_PERCENT,
+        taskCountRange: {
+            min: TASK_COUNT_MIN,
+            max: resolveTaskCountMax(effectiveWindow),
+        },
+    };
+}
+/**
+ * Truncate content at markdown section boundaries to fit within a character budget.
+ *
+ * Splits on `### ` headings and `---` dividers. Keeps whole sections that fit.
+ * Appends `[...truncated N sections]` when content is dropped.
+ * Returns content unchanged when it fits within budget.
+ *
+ * @see D003 — section-boundary truncation is mandatory; mid-section cuts are unacceptable.
+ */
+export function truncateAtSectionBoundary(content, budgetChars) {
+    if (!content || content.length <= budgetChars) {
+        return { content, droppedSections: 0 };
+    }
+    // Split on section markers: ### headings or --- dividers (on their own line)
+    const sections = splitIntoSections(content);
+    if (sections.length <= 1) {
+        // No section markers — keep as much as fits from the start
+        const truncated = content.slice(0, budgetChars);
+        return { content: truncated + "\n\n[...truncated 1 sections]", droppedSections: 1 };
+    }
+    // Greedily keep sections that fit
+    let usedChars = 0;
+    let keptCount = 0;
+    for (const section of sections) {
+        const sectionLen = section.length;
+        if (usedChars + sectionLen > budgetChars && keptCount > 0) {
+            break;
+        }
+        // Always keep at least the first section (even if it exceeds budget)
+        usedChars += sectionLen;
+        keptCount++;
+        if (usedChars >= budgetChars)
+            break;
+    }
+    const droppedCount = sections.length - keptCount;
+    if (droppedCount === 0) {
+        return { content, droppedSections: 0 };
+    }
+    const kept = sections.slice(0, keptCount).join("");
+    return {
+        content: kept.trimEnd() + `\n\n[...truncated ${droppedCount} sections]`,
+        droppedSections: droppedCount,
+    };
+}
+/**
+ * Resolve the executor model's context window size using a fallback chain:
+ *
+ * 1. Look up the configured executor model ID in preferences → find in registry → return contextWindow
+ * 2. Fall back to sessionContextWindow if provided
+ * 3. Fall back to 200K default (D002)
+ *
+ * Supports "provider/model" format in preferences for explicit provider targeting.
+ */
+export function resolveExecutorContextWindow(registry, preferences, sessionContextWindow) {
+    // Step 1: Try configured executor model
+    if (preferences?.models?.execution && registry) {
+        const executionConfig = preferences.models.execution;
+        const modelId = typeof executionConfig === "string"
+            ? executionConfig
+            : executionConfig.model;
+        if (modelId) {
+            const model = findModelById(registry, modelId);
+            if (model && model.contextWindow > 0) {
+                return model.contextWindow;
+            }
+        }
+    }
+    // Step 2: Fall back to session context window
+    if (sessionContextWindow && sessionContextWindow > 0) {
+        return sessionContextWindow;
+    }
+    // Step 3: Fall back to default (D002)
+    return DEFAULT_CONTEXT_WINDOW;
+}
+/**
+ * Smart context reduction: compress first, then truncate if still over budget.
+ * Returns the content within budget with maximum information preservation.
+ */
+export function reduceToFit(content, budgetChars) {
+    if (!content || content.length <= budgetChars) {
+        return { content, droppedSections: 0 };
+    }
+    // Step 1: Try compression
+    const compressed = compressToTarget(content, budgetChars);
+    if (compressed.compressedChars <= budgetChars) {
+        return { content: compressed.content, droppedSections: 0 };
+    }
+    // Step 2: Truncate the compressed content at section boundaries
+    return truncateAtSectionBoundary(compressed.content, budgetChars);
+}
+// ─── Internal helpers ────────────────────────────────────────────────────────
+/**
+ * Resolve task count ceiling from context window size.
+ * Larger windows support more tasks per slice.
+ */
+function resolveTaskCountMax(contextWindow) {
+    for (const [threshold, max] of TASK_COUNT_TIERS) {
+        if (contextWindow >= threshold)
+            return max;
+    }
+    return 3; // fallback — unreachable given tiers include 0
+}
+/**
+ * Split content into sections at `### ` headings or `---` dividers.
+ * Each section includes its leading marker.
+ */
+function splitIntoSections(content) {
+    // Match section boundaries: ### heading or --- divider at start of line
+    const pattern = /^(?=### |\-{3,}\s*$)/m;
+    const parts = content.split(pattern).filter(p => p.length > 0);
+    return parts;
+}
+/**
+ * Find a model in the registry by ID string.
+ * Supports "provider/model" format for explicit provider targeting,
+ * or bare model ID (first match wins).
+ */
+function findModelById(registry, modelId) {
+    const allModels = registry.getAll();
+    const slashIdx = modelId.indexOf("/");
+    if (slashIdx !== -1) {
+        const provider = modelId.substring(0, slashIdx).toLowerCase();
+        const id = modelId.substring(slashIdx + 1).toLowerCase();
+        return allModels.find(m => m.provider.toLowerCase() === provider && m.id.toLowerCase() === id);
+    }
+    // Bare ID — first match
+    return allModels.find(m => m.id === modelId);
+}

package/dist/resources/extensions/gsd/context-store.js

@@ -0,0 +1,165 @@
+// GSD Context Store — Query Layer & Formatters
+//
+// Typed query functions for decisions and requirements from the DB views,
+// with optional filtering. Format functions produce prompt-injectable markdown.
+// All functions degrade gracefully: return empty results when DB unavailable, never throw.
+import { isDbAvailable, _getAdapter } from './gsd-db.js';
+/**
+ * Query active (non-superseded) decisions with optional filters.
+ * - milestoneId: filters where when_context LIKE '%milestoneId%'
+ * - scope: filters where scope = :scope (exact match)
+ *
+ * Returns [] if DB is not available. Never throws.
+ */
+export function queryDecisions(opts) {
+    if (!isDbAvailable())
+        return [];
+    const adapter = _getAdapter();
+    if (!adapter)
+        return [];
+    try {
+        const clauses = ['superseded_by IS NULL'];
+        const params = {};
+        if (opts?.milestoneId) {
+            clauses.push('when_context LIKE :milestone_pattern');
+            params[':milestone_pattern'] = `%${opts.milestoneId}%`;
+        }
+        if (opts?.scope) {
+            clauses.push('scope = :scope');
+            params[':scope'] = opts.scope;
+        }
+        const sql = `SELECT * FROM decisions WHERE ${clauses.join(' AND ')} ORDER BY seq`;
+        const rows = adapter.prepare(sql).all(params);
+        return rows.map(row => ({
+            seq: row['seq'],
+            id: row['id'],
+            when_context: row['when_context'],
+            scope: row['scope'],
+            decision: row['decision'],
+            choice: row['choice'],
+            rationale: row['rationale'],
+            revisable: row['revisable'],
+            superseded_by: null,
+        }));
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Query active (non-superseded) requirements with optional filters.
+ * - sliceId: filters where primary_owner LIKE '%sliceId%' OR supporting_slices LIKE '%sliceId%'
+ * - status: filters where status = :status (exact match)
+ *
+ * Returns [] if DB is not available. Never throws.
+ */
+export function queryRequirements(opts) {
+    if (!isDbAvailable())
+        return [];
+    const adapter = _getAdapter();
+    if (!adapter)
+        return [];
+    try {
+        const clauses = ['superseded_by IS NULL'];
+        const params = {};
+        if (opts?.sliceId) {
+            clauses.push('(primary_owner LIKE :slice_pattern OR supporting_slices LIKE :slice_pattern)');
+            params[':slice_pattern'] = `%${opts.sliceId}%`;
+        }
+        if (opts?.status) {
+            clauses.push('status = :status');
+            params[':status'] = opts.status;
+        }
+        const sql = `SELECT * FROM requirements WHERE ${clauses.join(' AND ')} ORDER BY id`;
+        const rows = adapter.prepare(sql).all(params);
+        return rows.map(row => ({
+            id: row['id'],
+            class: row['class'],
+            status: row['status'],
+            description: row['description'],
+            why: row['why'],
+            source: row['source'],
+            primary_owner: row['primary_owner'],
+            supporting_slices: row['supporting_slices'],
+            validation: row['validation'],
+            notes: row['notes'],
+            full_content: row['full_content'],
+            superseded_by: null,
+        }));
+    }
+    catch {
+        return [];
+    }
+}
+// ─── Format Functions ──────────────────────────────────────────────────────
+/**
+ * Format decisions as a markdown table matching DECISIONS.md format.
+ * Returns empty string for empty input.
+ */
+export function formatDecisionsForPrompt(decisions) {
+    if (decisions.length === 0)
+        return '';
+    const header = '| # | When | Scope | Decision | Choice | Rationale | Revisable? |';
+    const separator = '|---|------|-------|----------|--------|-----------|------------|';
+    const rows = decisions.map(d => `| ${d.id} | ${d.when_context} | ${d.scope} | ${d.decision} | ${d.choice} | ${d.rationale} | ${d.revisable} |`);
+    return [header, separator, ...rows].join('\n');
+}
+/**
+ * Format requirements as structured H3 sections matching REQUIREMENTS.md format.
+ * Returns empty string for empty input.
+ */
+export function formatRequirementsForPrompt(requirements) {
+    if (requirements.length === 0)
+        return '';
+    return requirements.map(r => {
+        const lines = [
+            `### ${r.id}: ${r.description}`,
+            '',
+            `- **Class:** ${r.class}`,
+            `- **Status:** ${r.status}`,
+            `- **Why:** ${r.why}`,
+            `- **Source:** ${r.source}`,
+            `- **Primary Owner:** ${r.primary_owner}`,
+        ];
+        if (r.supporting_slices) {
+            lines.push(`- **Supporting Slices:** ${r.supporting_slices}`);
+        }
+        lines.push(`- **Validation:** ${r.validation}`);
+        if (r.notes) {
+            lines.push(`- **Notes:** ${r.notes}`);
+        }
+        return lines.join('\n');
+    }).join('\n\n');
+}
+// ─── Artifact Query Functions ──────────────────────────────────────────────
+/**
+ * Query a hierarchy artifact by its relative path.
+ * Returns the full_content string or null if not found/unavailable.
+ * Never throws.
+ */
+export function queryArtifact(path) {
+    if (!isDbAvailable())
+        return null;
+    const adapter = _getAdapter();
+    if (!adapter)
+        return null;
+    try {
+        const row = adapter.prepare('SELECT full_content FROM artifacts WHERE path = :path').get({ ':path': path });
+        if (!row)
+            return null;
+        const content = row['full_content'];
+        return content || null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Query PROJECT.md content from the artifacts table.
+ * PROJECT.md is stored with the relative path 'PROJECT.md' by the importer.
+ * Returns the content string or null if not found/unavailable.
+ * Never throws.
+ */
+export function queryProject() {
+    return queryArtifact('PROJECT.md');
+}