valent-pipeline 0.2.5 → 0.2.7

package/bin/cli.js

@@ -75,4 +75,150 @@ dbCmd
     await dbRebuild();
   });
 
+dbCmd
+  .command('index-handoff')
+  .description('Index a single handoff artifact into the database')
+  .requiredOption('--file <path>', 'Path to the artifact file')
+  .requiredOption('--story-id <id>', 'Story identifier')
+  .requiredOption('--agent <name>', 'Agent that produced the artifact')
+  .requiredOption('--artifact-type <type>', 'Artifact type (e.g., reqs-brief)')
+  .option('--db-path <path>', 'Database path (defaults to config)')
+  .action(async (options) => {
+    const { dbIndexHandoff } = await import('../src/commands/db-index.js');
+    await dbIndexHandoff(options);
+  });
+
+dbCmd
+  .command('index-working')
+  .description('Index an artifact into the grooming working table')
+  .requiredOption('--file <path>', 'Path to the artifact file')
+  .requiredOption('--story-id <id>', 'Story identifier')
+  .requiredOption('--agent <name>', 'Agent that produced the artifact')
+  .requiredOption('--artifact-type <type>', 'Artifact type')
+  .option('--sprint-id <id>', 'Sprint identifier')
+  .option('--db-path <path>', 'Database path (defaults to config)')
+  .action(async (options) => {
+    const { dbIndexWorking } = await import('../src/commands/db-index.js');
+    await dbIndexWorking(options);
+  });
+
+dbCmd
+  .command('flush-working')
+  .description('Flush working table to main artifacts table')
+  .option('--sprint-id <id>', 'Sprint identifier')
+  .option('--db-path <path>', 'Database path (defaults to config)')
+  .action(async (options) => {
+    const { dbFlushWorking } = await import('../src/commands/db-index.js');
+    await dbFlushWorking(options);
+  });
+
+dbCmd
+  .command('query-working')
+  .description('Query artifacts from the grooming working table')
+  .option('--sprint-id <id>', 'Sprint identifier')
+  .option('--exclude-story <id>', 'Exclude this story from results')
+  .option('--db-path <path>', 'Database path (defaults to config)')
+  .action(async (options) => {
+    const { dbQueryWorking } = await import('../src/commands/db-index.js');
+    await dbQueryWorking(options);
+  });
+
+dbCmd
+  .command('record-calibration')
+  .description('Record story calibration data for estimation accuracy')
+  .requiredOption('--story-id <id>', 'Story identifier')
+  .option('--story-points <n>', 'Fibonacci story points', parseInt)
+  .option('--ac-count <n>', 'Number of acceptance criteria', parseInt)
+  .option('--surface <type>', 'Surface area (backend, full-stack, etc.)')
+  .option('--estimated-points <n>', 'Estimated points', parseInt)
+  .option('--actual-mins <n>', 'Actual execution minutes', parseFloat)
+  .option('--rework-cycles <n>', 'Number of rework cycles', parseInt)
+  .option('--sprint-id <id>', 'Sprint identifier')
+  .option('--db-path <path>', 'Database path (defaults to config)')
+  .action(async (options) => {
+    const { dbRecordCalibration } = await import('../src/commands/db-index.js');
+    await dbRecordCalibration(options);
+  });
+
+dbCmd
+  .command('query-velocity')
+  .description('Query sprint velocity history for estimation')
+  .option('--db-path <path>', 'Database path (defaults to config)')
+  .action(async (options) => {
+    const { dbQueryVelocity } = await import('../src/commands/db-index.js');
+    await dbQueryVelocity(options);
+  });
+
+dbCmd
+  .command('embed')
+  .description('Process embed-instructions.md from retrospective')
+  .requiredOption('--file <path>', 'Path to embed-instructions.md')
+  .option('--curated-path <path>', 'Path to curated knowledge files')
+  .option('--db-path <path>', 'Database path (defaults to config)')
+  .action(async (options) => {
+    const { dbEmbed } = await import('../src/commands/db-index.js');
+    await dbEmbed(options);
+  });
+
+// db query commands
+dbCmd
+  .command('query-artifact')
+  .description('Get a specific artifact from the database')
+  .requiredOption('--story <id>', 'Story identifier')
+  .requiredOption('--type <type>', 'Artifact type')
+  .option('--db-path <path>', 'Database path (defaults to config)')
+  .action(async (options) => {
+    const { dbQueryArtifact } = await import('../src/commands/db-query.js');
+    await dbQueryArtifact(options);
+  });
+
+dbCmd
+  .command('query-directives')
+  .description('Get active correction directives')
+  .option('--agent <name>', 'Filter by target agent')
+  .option('--db-path <path>', 'Database path (defaults to config)')
+  .action(async (options) => {
+    const { dbQueryDirectives } = await import('../src/commands/db-query.js');
+    await dbQueryDirectives(options);
+  });
+
+dbCmd
+  .command('search')
+  .description('Full-text search across all artifacts')
+  .requiredOption('--query <text>', 'Search query')
+  .option('--db-path <path>', 'Database path (defaults to config)')
+  .action(async (options) => {
+    const { dbQuerySearch } = await import('../src/commands/db-query.js');
+    await dbQuerySearch(options);
+  });
+
+dbCmd
+  .command('query-list')
+  .description('List all artifacts for a story')
+  .requiredOption('--story <id>', 'Story identifier')
+  .option('--db-path <path>', 'Database path (defaults to config)')
+  .action(async (options) => {
+    const { dbQueryList } = await import('../src/commands/db-query.js');
+    await dbQueryList(options);
+  });
+
+dbCmd
+  .command('query-stories')
+  .description('List all stories in the database')
+  .option('--db-path <path>', 'Database path (defaults to config)')
+  .action(async (options) => {
+    const { dbQueryStories } = await import('../src/commands/db-query.js');
+    await dbQueryStories(options);
+  });
+
+dbCmd
+  .command('query-bugs-since')
+  .description('Get bugs filed since a date')
+  .requiredOption('--since <date>', 'Date in YYYY-MM-DD format')
+  .option('--db-path <path>', 'Database path (defaults to config)')
+  .action(async (options) => {
+    const { dbQueryBugsSince } = await import('../src/commands/db-query.js');
+    await dbQueryBugsSince(options);
+  });
+
 program.parse();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "valent-pipeline",
-  "version": "0.2.5",
+  "version": "0.2.7",
   "description": "v3 multi-agent AI pipeline for software development lifecycle",
   "type": "module",
   "bin": {

package/pipeline/prompts/embed.md

@@ -30,8 +30,7 @@ Verify `{story_output_dir}/embed-instructions.md` exists. If missing, send `[BLO
 **If `{knowledge_mode}` is `sqlite` (recommended):**
 
 ```bash
-npx tsx .valent-pipeline/scripts/embed-sqlite.ts {story_output_dir}/embed-instructions.md \
-  --db-path {sqlite_db_path} \
+node .valent-pipeline/bin/cli.js db embed {story_output_dir}/embed-instructions.md \
   --curated-path {curated_files_path}
 ```
 

package/pipeline/prompts/knowledge.md

@@ -38,7 +38,7 @@ Read all files in `{curated_files_path}`. Build in-memory index of file names, s
 **If `{knowledge_mode}` is `sqlite`:**
 Verify the database is accessible by running:
 ```bash
-npx tsx .valent-pipeline/scripts/query-kb.ts --stories
+node .valent-pipeline/bin/cli.js db query-stories
 ```
 If it returns results or "No stories in database", the DB is accessible. If the command fails, operate in curated-only mode.
 
@@ -53,12 +53,12 @@ For each incoming query:
 1. Search correction directives for relevant entries
 2. Search curated knowledge files for matching sections
 3. If database connected (SQLite mode): query using the CLI tool and read stdout for results:
-   - Fetch a specific artifact: `npx tsx .valent-pipeline/scripts/query-kb.ts --artifact --story KANBAN-001 --type reqs-brief`
-   - Fetch directives for an agent: `npx tsx .valent-pipeline/scripts/query-kb.ts --directives --agent BEND`
-   - Full-text search: `npx tsx .valent-pipeline/scripts/query-kb.ts --search "acceptance criteria"`
-   - List artifacts for a story: `npx tsx .valent-pipeline/scripts/query-kb.ts --list --story KANBAN-001`
-   - List all stories: `npx tsx .valent-pipeline/scripts/query-kb.ts --stories`
-   - Cross-story bug search: `npx tsx .valent-pipeline/scripts/query-kb.ts --bugs-since 2026-03-01`
+   - Fetch a specific artifact: `node .valent-pipeline/bin/cli.js db query-artifact --story KANBAN-001 --type reqs-brief`
+   - Fetch directives for an agent: `node .valent-pipeline/bin/cli.js db query-directives --agent BEND`
+   - Full-text search: `node .valent-pipeline/bin/cli.js db search --query "acceptance criteria"`
+   - List artifacts for a story: `node .valent-pipeline/bin/cli.js db query-list --story KANBAN-001`
+   - List all stories: `node .valent-pipeline/bin/cli.js db query-stories`
+   - Cross-story bug search: `node .valent-pipeline/bin/cli.js db query-bugs-since --since 2026-03-01`
    If ChromaDB mode: use collection query (ChromaDB)
 4. Compose response: targeted, SHORT (aim ~200 tokens, max 500)
 5. Include source reference: `Source: curated/{file}#section` or `Source: sqlite:artifacts/{story_id}/{type}` or `Source: correction-directives#{directive-id}`

package/pipeline/prompts/lead.md

@@ -493,8 +493,7 @@ This runs PMCP in parallel with QA-B's test execution, removing it from the crit
 When `{knowledge_mode}` is `sqlite` and you receive a `[HANDOFF]` from an agent that produces an output file, index the artifact into the SQLite database so downstream agents can query it via Knowledge:
 
 ```bash
-npx tsx .valent-pipeline/scripts/embed-sqlite.ts --index-handoff {story_output_dir}/{artifact_file} \
-  --db-path {sqlite_db_path} \
+node .valent-pipeline/bin/cli.js db index-handoff --file {story_output_dir}/{artifact_file} \
   --story-id {story_id} \
   --agent {agent_name} \
   --artifact-type {type}
@@ -589,8 +588,7 @@ Tear down all per-story teammates. Send `shutdown_request` to each individually.
 If `{knowledge_mode}` is `sqlite`, record story actuals to the calibration table for future estimation accuracy:
 
 ```bash
-npx tsx .valent-pipeline/scripts/embed-sqlite.ts --record-calibration \
-  --db-path {sqlite_db_path} \
+node .valent-pipeline/bin/cli.js db record-calibration \
   --story-id {story_id} \
   --ac-count {ac_count_from_reqs_brief} \
   --surface {project_type} \

package/pipeline/steps/orchestration/sprint-groom.md

@@ -20,8 +20,7 @@ For each story in grooming candidates (up to `{groom_target}` from sprint-init):
 4. On UXA handoff → update status to `test-case-development` → QA-A writes `qa-test-spec.md`
 5. On QA-A handoff → index all artifacts to SQLite **working table**:
    ```bash
-   npx tsx .valent-pipeline/scripts/embed-sqlite.ts --index-working \
-     --db-path {sqlite_db_path} \
+   node .valent-pipeline/bin/cli.js db index-working \
      --story-id {story_id} \
      --sprint-id {current_sprint_id}
    ```
@@ -47,8 +46,7 @@ After every `{sprint_max_groom_batch}` stories (default: 10), kill and respawn P
 After all stories groomed:
 
 ```bash
-npx tsx .valent-pipeline/scripts/embed-sqlite.ts --flush-working \
-  --db-path {sqlite_db_path} \
+node .valent-pipeline/bin/cli.js db flush-working \
   --sprint-id {current_sprint_id}
 ```
 

package/pipeline/steps/orchestration/sprint-init.md

@@ -15,8 +15,7 @@ Sprint ID format:
 Query the calibration table for historical velocity data:
 
 ```bash
-npx tsx .valent-pipeline/scripts/embed-sqlite.ts --query-velocity \
-  --db-path {sqlite_db_path}
+node .valent-pipeline/bin/cli.js db query-velocity
 ```
 
 **Velocity rules:**

package/pipeline/steps/orchestration/sprint-review.md

@@ -34,8 +34,7 @@ Update `sprint-{n}-status.yaml`:
 For each shipped story, ensure the calibration table has complete data:
 
 ```bash
-npx tsx .valent-pipeline/scripts/embed-sqlite.ts --update-calibration \
-  --db-path {sqlite_db_path} \
+node .valent-pipeline/bin/cli.js db record-calibration \
   --story-id {story_id} \
   --story-points {fibonacci_estimate} \
   --estimated-points {fibonacci_estimate} \

package/pipeline/steps/readiness/sprint-review.md

@@ -9,8 +9,7 @@ These steps run AFTER the standalone review (Steps 1-8) passes. If the standalon
 Query the SQLite working table for specs from other stories groomed in this sprint batch:
 
 ```bash
-npx tsx .valent-pipeline/scripts/embed-sqlite.ts --query-working \
-  --db-path {sqlite_db_path} \
+node .valent-pipeline/bin/cli.js db query-working \
   --sprint-id {current_sprint_id} \
   --exclude-story {story_id}
 ```

package/skills/valent-setup-backlog/SKILL.md

@@ -173,8 +173,8 @@ If the repo is empty or brand new (no source code yet), skip the subagents and c
 ### Step 7b: Initialize and Populate Knowledge Database
 
 After writing the curated knowledge files:
-1. Run `valent-pipeline db init` to create the SQLite database if it doesn't exist
-2. Run `npx tsx .valent-pipeline/scripts/embed-sqlite.ts --rebuild --db-path .valent-pipeline/pipeline.db --stories-dir ./stories` to index any existing story artifacts
+1. Run `node .valent-pipeline/bin/cli.js db init` to create the SQLite database if it doesn't exist
+2. Run `node .valent-pipeline/bin/cli.js db rebuild` to index any existing story artifacts
 3. The database is now ready for the Knowledge Agent to query during story execution
 
 ## Step 8: Report

package/src/commands/db-index.js

@@ -0,0 +1,254 @@
+import { join, dirname } from 'path';
+import { readFileSync, existsSync, appendFileSync, mkdirSync, readdirSync, statSync } from 'fs';
+
+const ARTIFACT_MAP = {
+  'reqs-brief.md': { type: 'reqs-brief', agent: 'REQS' },
+  'uxa-spec.md': { type: 'uxa-spec', agent: 'UXA' },
+  'qa-test-spec.md': { type: 'qa-test-spec', agent: 'QA-A' },
+  'bend-handoff.md': { type: 'bend-handoff', agent: 'BEND' },
+  'fend-handoff.md': { type: 'fend-handoff', agent: 'FEND' },
+  'critic-review.md': { type: 'critic-review', agent: 'CRITIC' },
+  'execution-report.md': { type: 'execution-report', agent: 'QA-B' },
+  'bugs.md': { type: 'bugs', agent: 'QA-B' },
+  'traceability-matrix.md': { type: 'traceability-matrix', agent: 'QA-B' },
+  'readiness-review.md': { type: 'readiness-review', agent: 'READINESS' },
+  'judge-review.md': { type: 'judge-review', agent: 'JUDGE' },
+  'judge-decision.md': { type: 'judge-decision', agent: 'JUDGE' },
+  'story-report.md': { type: 'story-report', agent: 'JUDGE' },
+  'pmcp-evidence.md': { type: 'pmcp-evidence', agent: 'PMCP' },
+  'visual-validation-checklist.md': { type: 'visual-validation-checklist', agent: 'QA-A' },
+};
+
+function getDb(dbPath) {
+  const Database = require(join(process.cwd(), '.valent-pipeline', 'node_modules', 'better-sqlite3'));
+  return new Database(dbPath);
+}
+
+function resolveDbPath(options) {
+  if (options.dbPath) return options.dbPath;
+  const configPath = join(process.cwd(), '.valent-pipeline', 'pipeline-config.yaml');
+  if (existsSync(configPath)) {
+    const content = readFileSync(configPath, 'utf-8');
+    const match = content.match(/sqlite_db_path:\s*"?([^"\n]+)"?/);
+    if (match) return join(process.cwd(), match[1].trim());
+  }
+  return join(process.cwd(), '.valent-pipeline', 'pipeline.db');
+}
+
+export async function dbIndexHandoff(options) {
+  const dbPath = resolveDbPath(options);
+  const { file, storyId, agent, artifactType } = options;
+
+  if (!existsSync(file)) {
+    console.error(`File not found: ${file}`);
+    process.exit(1);
+  }
+
+  const content = readFileSync(file, 'utf-8');
+  if (content.includes('status: skipped')) {
+    console.log(`Skipping pass-through artifact: ${file}`);
+    return;
+  }
+
+  const db = getDb(dbPath);
+  const id = `${storyId}:${artifactType}`;
+  db.prepare(`
+    INSERT OR REPLACE INTO artifacts (id, story_id, agent, artifact_type, content, metadata)
+    VALUES (?, ?, ?, ?, ?, ?)
+  `).run(id, storyId, agent, artifactType, content, JSON.stringify({ source: 'handoff', file }));
+  db.close();
+  console.log(`Indexed ${id} (${content.length} chars)`);
+}
+
+export async function dbIndexWorking(options) {
+  const dbPath = resolveDbPath(options);
+  const { file, storyId, agent, artifactType, sprintId } = options;
+
+  if (!existsSync(file)) {
+    console.error(`File not found: ${file}`);
+    process.exit(1);
+  }
+
+  const content = readFileSync(file, 'utf-8');
+  const db = getDb(dbPath);
+  db.prepare(`
+    INSERT OR REPLACE INTO artifacts_working (story_id, agent, artifact_type, content, metadata)
+    VALUES (?, ?, ?, ?, ?)
+  `).run(storyId, agent, artifactType, content, JSON.stringify({ sprint_id: sprintId, file }));
+  db.close();
+  console.log(`Indexed to working table: ${storyId}:${artifactType}`);
+}
+
+export async function dbFlushWorking(options) {
+  const dbPath = resolveDbPath(options);
+  const { sprintId } = options;
+
+  const db = getDb(dbPath);
+  const rows = db.prepare('SELECT * FROM artifacts_working').all();
+
+  const insert = db.prepare(`
+    INSERT OR REPLACE INTO artifacts (id, story_id, agent, artifact_type, content, metadata)
+    VALUES (?, ?, ?, ?, ?, ?)
+  `);
+
+  const flush = db.transaction(() => {
+    for (const row of rows) {
+      const id = `${row.story_id}:${row.artifact_type}`;
+      insert.run(id, row.story_id, row.agent, row.artifact_type, row.content, row.metadata);
+    }
+    db.prepare('DELETE FROM artifacts_working').run();
+  });
+
+  flush();
+  db.close();
+  console.log(`Flushed ${rows.length} artifacts from working table to main table`);
+}
+
+export async function dbQueryWorking(options) {
+  const dbPath = resolveDbPath(options);
+  const { sprintId, excludeStory } = options;
+
+  const db = getDb(dbPath);
+  let rows;
+  if (excludeStory) {
+    rows = db.prepare(
+      'SELECT story_id, agent, artifact_type, content FROM artifacts_working WHERE story_id != ?'
+    ).all(excludeStory);
+  } else {
+    rows = db.prepare('SELECT story_id, agent, artifact_type, content FROM artifacts_working').all();
+  }
+  db.close();
+
+  if (rows.length === 0) {
+    console.log('No artifacts in working table');
+  } else {
+    for (const r of rows) {
+      console.log(`--- ${r.story_id}:${r.artifact_type} (${r.agent}) ---`);
+      console.log(r.content);
+    }
+  }
+}
+
+export async function dbRecordCalibration(options) {
+  const dbPath = resolveDbPath(options);
+  const { storyId, storyPoints, acCount, surface, estimatedPoints, actualMins, reworkCycles, sprintId } = options;
+
+  const db = getDb(dbPath);
+  db.prepare(`
+    INSERT OR REPLACE INTO calibration (story_id, story_points, ac_count, surface, estimated_points, actual_mins, rework_cycles, sprint_id)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+  `).run(storyId, storyPoints ?? null, acCount ?? null, surface ?? null, estimatedPoints ?? null, actualMins ?? null, reworkCycles ?? 0, sprintId ?? null);
+  db.close();
+  console.log(`Recorded calibration data for ${storyId}`);
+}
+
+export async function dbQueryVelocity(options) {
+  const dbPath = resolveDbPath(options);
+  const db = getDb(dbPath);
+
+  const rows = db.prepare(`
+    SELECT sprint_id, SUM(story_points) as points_shipped
+    FROM calibration
+    WHERE sprint_id IS NOT NULL AND story_points IS NOT NULL
+    GROUP BY sprint_id
+    ORDER BY created_at DESC
+    LIMIT 5
+  `).all();
+
+  db.close();
+
+  if (rows.length === 0) {
+    console.log('No sprint velocity data available');
+  } else {
+    console.log('Sprint velocity history (most recent first):');
+    for (const r of rows) {
+      console.log(`  ${r.sprint_id}: ${r.points_shipped} points`);
+    }
+    const avg = rows.reduce((sum, r) => sum + r.points_shipped, 0) / rows.length;
+    console.log(`  SMA-${rows.length}: ${Math.round(avg)} points`);
+  }
+}
+
+export async function dbEmbed(options) {
+  const dbPath = resolveDbPath(options);
+  const { file, curatedPath } = options;
+
+  if (!existsSync(file)) {
+    console.error(`File not found: ${file}`);
+    process.exit(1);
+  }
+
+  const content = readFileSync(file, 'utf-8');
+  const items = parseEmbedInstructions(content);
+  console.log(`Parsed ${items.length} embed instructions`);
+
+  const db = getDb(dbPath);
+  let indexed = 0;
+  let curatedCount = 0;
+
+  for (const item of items) {
+    if (item.target.startsWith('curated/')) {
+      const targetFile = join(curatedPath || './knowledge/curated', item.target.replace('curated/', ''));
+      mkdirSync(dirname(targetFile), { recursive: true });
+
+      if (item.metadata?.append_section && existsSync(targetFile)) {
+        const existing = readFileSync(targetFile, 'utf-8');
+        if (existing.includes(`## ${item.metadata.append_section}`)) {
+          console.log(`  Skipped duplicate section: ${item.metadata.append_section}`);
+          continue;
+        }
+      }
+
+      const section = item.metadata?.append_section
+        ? `\n## ${item.metadata.append_section}\n\n${item.content}\n`
+        : `\n${item.content}\n`;
+      appendFileSync(targetFile, section, 'utf-8');
+      curatedCount++;
+    } else {
+      const id = `embed:${Date.now()}:${indexed}`;
+      db.prepare(`
+        INSERT OR REPLACE INTO artifacts (id, story_id, agent, artifact_type, content, metadata)
+        VALUES (?, ?, ?, ?, ?, ?)
+      `).run(id, item.metadata?.stories?.[0] || 'batch', 'Retrospective', item.metadata?.category || 'pattern', item.content, JSON.stringify(item.metadata || {}));
+      indexed++;
+    }
+  }
+
+  db.close();
+  console.log(`Complete: ${indexed} items indexed, ${curatedCount} curated files updated`);
+}
+
+function parseEmbedInstructions(content) {
+  const items = [];
+  const sections = content.split(/^### \d+\./m).filter(s => s.trim());
+
+  for (const section of sections) {
+    const yamlMatch = section.match(/```yaml\n([\s\S]*?)```/);
+    if (!yamlMatch) continue;
+
+    const yamlContent = yamlMatch[1];
+    const contentMatch = yamlContent.match(/content:\s*>\s*\n([\s\S]*?)(?=\n\s+target:|$)/);
+    const targetMatch = yamlContent.match(/target:\s*"?([^"\n]+)"?/);
+
+    if (contentMatch && targetMatch) {
+      const itemContent = contentMatch[1].split('\n').map(l => l.trim()).join('\n').trim();
+      const target = targetMatch[1].trim();
+      const metadata = {};
+      const metadataMatch = yamlContent.match(/metadata:\n([\s\S]*?)(?=\n\S|$)/);
+      if (metadataMatch) {
+        for (const line of metadataMatch[1].split('\n')) {
+          const kv = line.match(/^\s+(\w+):\s+(.+)$/);
+          if (kv) {
+            let val = kv[2].trim();
+            if (val.startsWith('[') && val.endsWith(']')) {
+              val = val.slice(1, -1).split(',').map(s => s.trim());
+            }
+            metadata[kv[1]] = val;
+          }
+        }
+      }
+      items.push({ content: itemContent, target, metadata });
+    }
+  }
+  return items;
+}

package/src/commands/db-query.js

@@ -0,0 +1,140 @@
+import { join } from 'path';
+import { readFileSync, existsSync } from 'fs';
+
+function resolveDbPath(options) {
+  if (options.dbPath) return options.dbPath;
+  const configPath = join(process.cwd(), '.valent-pipeline', 'pipeline-config.yaml');
+  if (existsSync(configPath)) {
+    const content = readFileSync(configPath, 'utf-8');
+    const match = content.match(/sqlite_db_path:\s*"?([^"\n]+)"?/);
+    if (match) return join(process.cwd(), match[1].trim());
+  }
+  return join(process.cwd(), '.valent-pipeline', 'pipeline.db');
+}
+
+function getDb(dbPath) {
+  const Database = require(join(process.cwd(), '.valent-pipeline', 'node_modules', 'better-sqlite3'));
+  return new Database(dbPath, { readonly: true });
+}
+
+export async function dbQueryArtifact(options) {
+  const dbPath = resolveDbPath(options);
+  const { story, type } = options;
+
+  const db = getDb(dbPath);
+  const row = db.prepare(
+    'SELECT content, agent, created_at FROM artifacts WHERE story_id = ? AND artifact_type = ?'
+  ).get(story, type);
+  db.close();
+
+  if (row) {
+    console.log(`--- ${type} for ${story} (by ${row.agent}, ${row.created_at}) ---`);
+    console.log(row.content);
+  } else {
+    console.log(`No artifact found: story=${story}, type=${type}`);
+  }
+}
+
+export async function dbQueryDirectives(options) {
+  const dbPath = resolveDbPath(options);
+  const { agent } = options;
+
+  const db = getDb(dbPath);
+  let rows;
+  if (agent) {
+    rows = db.prepare(
+      "SELECT id, directive, reason FROM correction_directives WHERE target_agent = ? AND status = 'active'"
+    ).all(agent);
+  } else {
+    rows = db.prepare(
+      "SELECT id, target_agent, directive, reason FROM correction_directives WHERE status = 'active'"
+    ).all();
+  }
+  db.close();
+
+  if (rows.length === 0) {
+    console.log(agent ? `No active directives for ${agent}` : 'No active correction directives');
+  } else {
+    for (const r of rows) {
+      const target = r.target_agent ? ` [${r.target_agent}]` : '';
+      console.log(`${r.id}${target}: ${r.directive}`);
+      if (r.reason) console.log(`  Reason: ${r.reason}`);
+    }
+  }
+}
+
+export async function dbQuerySearch(options) {
+  const dbPath = resolveDbPath(options);
+  const { query } = options;
+
+  const db = getDb(dbPath);
+  const rows = db.prepare(
+    "SELECT story_id, agent, artifact_type, snippet(artifacts_fts, 0, '>>>', '<<<', '...', 40) as snippet FROM artifacts_fts WHERE artifacts_fts MATCH ? ORDER BY rank LIMIT 10"
+  ).all(query);
+  db.close();
+
+  if (rows.length === 0) {
+    console.log(`No results for: ${query}`);
+  } else {
+    for (const r of rows) {
+      console.log(`[${r.story_id}] ${r.artifact_type} (${r.agent}): ${r.snippet}`);
+    }
+  }
+}
+
+export async function dbQueryList(options) {
+  const dbPath = resolveDbPath(options);
+  const { story } = options;
+
+  const db = getDb(dbPath);
+  const rows = db.prepare(
+    'SELECT artifact_type, agent, length(content) as size, created_at FROM artifacts WHERE story_id = ? ORDER BY created_at'
+  ).all(story);
+  db.close();
+
+  if (rows.length === 0) {
+    console.log(`No artifacts for story ${story}`);
+  } else {
+    console.log(`Artifacts for ${story}:`);
+    for (const r of rows) {
+      console.log(`  ${r.artifact_type} (${r.agent}, ${r.size} chars, ${r.created_at})`);
+    }
+  }
+}
+
+export async function dbQueryStories(options) {
+  const dbPath = resolveDbPath(options);
+  const db = getDb(dbPath);
+  const rows = db.prepare(
+    'SELECT DISTINCT story_id, COUNT(*) as artifact_count FROM artifacts GROUP BY story_id ORDER BY story_id'
+  ).all();
+  db.close();
+
+  if (rows.length === 0) {
+    console.log('No stories in database');
+  } else {
+    for (const r of rows) {
+      console.log(`${r.story_id}: ${r.artifact_count} artifacts`);
+    }
+  }
+}
+
+export async function dbQueryBugsSince(options) {
+  const dbPath = resolveDbPath(options);
+  const { since } = options;
+
+  const db = getDb(dbPath);
+  const rows = db.prepare(
+    "SELECT story_id, content FROM artifacts WHERE artifact_type = 'bugs' AND created_at > ? ORDER BY created_at"
+  ).all(since);
+  db.close();
+
+  if (rows.length === 0) {
+    console.log(`No bugs filed since ${since}`);
+  } else {
+    for (const r of rows) {
+      console.log(`--- Bugs from ${r.story_id} ---`);
+      console.log(r.content);
+    }
+  }
+}