@shipfast-ai/shipfast 1.1.0 → 1.3.1

package/brain/index.cjs

@@ -8,12 +8,9 @@
 const fs = require('fs');
 const path = require('path');
 const { execFileSync } = require('child_process');
+const { DB_NAME } = require('../core/constants.cjs');
 
-const DB_NAME = '.shipfast/brain.db';
-
-// ============================================================
-// Database initialization
-// ============================================================
+// --- Database initialization ---
 
 function getBrainPath(cwd) {
   return path.join(cwd || process.cwd(), DB_NAME);
@@ -41,9 +38,7 @@ function brainExists(cwd) {
   return fs.existsSync(getBrainPath(cwd));
 }
 
-// ============================================================
-// Query helpers (all zero-LLM-cost)
-// ============================================================
+// --- Query helpers ---
 
 function query(cwd, sql) {
   const dbPath = getBrainPath(cwd);
@@ -55,7 +50,10 @@ function query(cwd, sql) {
       stdio: ['pipe', 'pipe', 'pipe']
     });
     return result.trim() ? JSON.parse(result) : [];
-  } catch {
+  } catch (err) {
+    if (process.env.SF_DEBUG) {
+      console.error('[brain] query error:', err.message, '\n  SQL:', sql.slice(0, 200));
+    }
     return [];
   }
 }
@@ -65,9 +63,7 @@ function run(cwd, sql) {
   execFileSync('sqlite3', [dbPath, sql], { stdio: ['pipe', 'pipe', 'pipe'] });
 }
 
-// ============================================================
-// Codebase graph operations
-// ============================================================
+// --- Codebase graph ---
 
 function upsertNode(cwd, node) {
   const { id, kind, name, file_path, line_start, line_end, signature, hash, metadata } = node;
@@ -83,7 +79,7 @@ function addEdge(cwd, source, target, kind, weight = 1.0) {
 
 function getBlastRadius(cwd, filePaths, maxDepth = 3) {
   const fileList = filePaths.map(f => `'file:${esc(f)}'`).join(',');
-  return query(cwd, `
+  const sql = `
     WITH RECURSIVE affected(id, depth) AS (
       SELECT id, 0 FROM nodes WHERE id IN (${fileList})
       UNION
@@ -96,7 +92,35 @@ function getBlastRadius(cwd, filePaths, maxDepth = 3) {
     WHERE n.signature IS NOT NULL AND n.signature != ''
     ORDER BY a.depth ASC
     LIMIT 30
-  `);
+  `;
+
+  const local = query(cwd, sql);
+
+  // Cross-repo blast radius: query linked repos too
+  const linkedConfig = getConfig(cwd, 'linked_repos');
+  if (linkedConfig) {
+    try {
+      const linkedPaths = JSON.parse(linkedConfig);
+      for (const repoPath of linkedPaths) {
+        const linkedDb = path.join(repoPath, '.shipfast', 'brain.db');
+        if (fs.existsSync(linkedDb)) {
+          try {
+            const result = execFileSync('sqlite3', ['-json', linkedDb, sql], {
+              encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe']
+            }).trim();
+            if (result) {
+              const parsed = JSON.parse(result);
+              const repoName = path.basename(repoPath);
+              parsed.forEach(row => { row._repo = repoName; });
+              local.push(...parsed);
+            }
+          } catch { /* linked repo query failed */ }
+        }
+      }
+    } catch { /* linked_repos not valid JSON */ }
+  }
+
+  return local.slice(0, 30);
 }
 
 function getSignaturesForFile(cwd, filePath) {
@@ -112,9 +136,7 @@ function getStaleNodes(cwd) {
   return query(cwd, `SELECT id, file_path, hash FROM nodes WHERE kind = 'file'`);
 }
 
-// ============================================================
 // Context operations (replaces STATE.md / REQUIREMENTS.md)
-// ============================================================
 
 function setContext(cwd, scope, key, value) {
   const val = typeof value === 'string' ? value : JSON.stringify(value);
@@ -134,9 +156,7 @@ function getAllContext(cwd, scope) {
   return query(cwd, `SELECT key, value FROM context WHERE scope = '${esc(scope)}'`);
 }
 
-// ============================================================
 // Decision operations
-// ============================================================
 
 function addDecision(cwd, { question, decision, reasoning, phase, tags }) {
   run(cwd, `INSERT INTO decisions (question, decision, reasoning, phase, tags)
@@ -148,9 +168,7 @@ function getDecisions(cwd, phase) {
   return query(cwd, `SELECT question, decision, reasoning, phase FROM decisions ${where} ORDER BY created_at DESC LIMIT 20`);
 }
 
-// ============================================================
 // Task operations
-// ============================================================
 
 function addTask(cwd, task) {
   const { id, phase, description, plan_text } = task;
@@ -170,9 +188,7 @@ function getTasks(cwd, phase) {
   return query(cwd, `SELECT * FROM tasks ${where} ORDER BY created_at`);
 }
 
-// ============================================================
 // Learnings (self-improving memory)
-// ============================================================
 
 function addLearning(cwd, { pattern, problem, solution, domain, source }) {
   run(cwd, `INSERT INTO learnings (pattern, problem, solution, domain, source)
@@ -193,9 +209,7 @@ function pruneOldLearnings(cwd, daysOld = 30) {
   run(cwd, `DELETE FROM learnings WHERE confidence < 0.3 AND times_used = 0 AND created_at < strftime('%s', 'now') - ${daysOld * 86400}`);
 }
 
-// ============================================================
 // Checkpoints
-// ============================================================
 
 function createCheckpoint(cwd, id, description) {
   let gitRef = '';
@@ -218,9 +232,7 @@ function rollbackCheckpoint(cwd, id) {
   run(cwd, `DELETE FROM checkpoints WHERE id = '${esc(id)}'`);
 }
 
-// ============================================================
 // Token budget
-// ============================================================
 
 function getTokenBudget(cwd) {
   const rows = query(cwd, `SELECT value FROM config WHERE key = 'token_budget'`);
@@ -241,9 +253,7 @@ function getTokensByAgent(cwd, sessionId) {
   return query(cwd, `SELECT agent, SUM(input_tokens + output_tokens) as total FROM token_usage WHERE session_id = '${esc(sessionId)}' GROUP BY agent`);
 }
 
-// ============================================================
 // Hot files (git-derived)
-// ============================================================
 
 function updateHotFiles(cwd, limit = 100) {
   try {
@@ -264,9 +274,7 @@ function getHotFiles(cwd, limit = 20) {
   return query(cwd, `SELECT file_path, change_count FROM hot_files ORDER BY change_count DESC LIMIT ${limit}`);
 }
 
-// ============================================================
 // Config
-// ============================================================
 
 function getConfig(cwd, key) {
   const rows = query(cwd, `SELECT value FROM config WHERE key = '${esc(key)}'`);
@@ -277,9 +285,7 @@ function setConfig(cwd, key, value) {
   run(cwd, `INSERT OR REPLACE INTO config (key, value) VALUES ('${esc(key)}', '${esc(String(value))}')`);
 }
 
-// ============================================================
 // Context builder for agents (the key token-saving function)
-// ============================================================
 
 function buildAgentContext(cwd, { agent, taskDescription, affectedFiles, phase, domain }) {
   const parts = [];
@@ -322,18 +328,14 @@ function buildAgentContext(cwd, { agent, taskDescription, affectedFiles, phase,
   return parts.join('\n\n');
 }
 
-// ============================================================
 // Model Performance (feedback loop)
-// ============================================================
 
 function recordModelOutcome(cwd, { agent, model, domain, taskId, outcome }) {
   run(cwd, `INSERT INTO model_performance (agent, model, domain, task_id, outcome)
     VALUES ('${esc(agent)}', '${esc(model)}', '${esc(domain || '')}', '${esc(taskId || '')}', '${esc(outcome)}')`);
 }
 
-// ============================================================
 // Seeds (forward ideas captured during work)
-// ============================================================
 
 function addSeed(cwd, { idea, sourceTask, domain, priority }) {
   run(cwd, `INSERT INTO seeds (idea, source_task, domain, priority)
@@ -357,9 +359,7 @@ function dismissSeed(cwd, seedId) {
   run(cwd, `UPDATE seeds SET status = 'dismissed' WHERE id = ${parseInt(seedId)}`);
 }
 
-// ============================================================
 // Utils
-// ============================================================
 
 function esc(s) {
   if (s == null) return '';
@@ -408,46 +408,4 @@ module.exports = {
   getSeeds,
   promoteSeed,
   dismissSeed,
-  // Requirements
-  addRequirement,
-  getRequirements,
-  updateRequirement,
-  getRequirementCoverage
 };
-
-// ============================================================
-// Requirements (REQ-ID tracing)
-// ============================================================
-
-function addRequirement(cwd, { id, category, description, priority, phase }) {
-  run(cwd, `INSERT OR REPLACE INTO requirements (id, category, description, priority, phase)
-    VALUES ('${esc(id)}', '${esc(category)}', '${esc(description)}', '${esc(priority || 'v1')}', '${esc(phase || '')}')`);
-}
-
-function getRequirements(cwd, opts = {}) {
-  const conditions = [];
-  if (opts.phase) conditions.push(`phase = '${esc(opts.phase)}'`);
-  if (opts.category) conditions.push(`category = '${esc(opts.category)}'`);
-  if (opts.status) conditions.push(`status = '${esc(opts.status)}'`);
-  if (opts.priority) conditions.push(`priority = '${esc(opts.priority)}'`);
-  const where = conditions.length ? 'WHERE ' + conditions.join(' AND ') : '';
-  return query(cwd, `SELECT * FROM requirements ${where} ORDER BY category, id`);
-}
-
-function updateRequirement(cwd, id, updates) {
-  const sets = Object.entries(updates).map(([k, v]) => `${k} = '${esc(String(v))}'`).join(', ');
-  run(cwd, `UPDATE requirements SET ${sets} WHERE id = '${esc(id)}'`);
-}
-
-function getRequirementCoverage(cwd) {
-  const total = query(cwd, "SELECT COUNT(*) as c FROM requirements WHERE priority = 'v1'");
-  const mapped = query(cwd, "SELECT COUNT(*) as c FROM requirements WHERE priority = 'v1' AND phase IS NOT NULL AND phase != ''");
-  const done = query(cwd, "SELECT COUNT(*) as c FROM requirements WHERE priority = 'v1' AND status = 'done'");
-  const verified = query(cwd, "SELECT COUNT(*) as c FROM requirements WHERE priority = 'v1' AND verified = 1");
-  return {
-    total: total[0] ? total[0].c : 0,
-    mapped: mapped[0] ? mapped[0].c : 0,
-    done: done[0] ? done[0].c : 0,
-    verified: verified[0] ? verified[0].c : 0
-  };
-}

package/brain/indexer.cjs

@@ -152,13 +152,10 @@ function hashContent(content) {
 }
 
 // ============================================================
-// SQL escaping (for batch mode)
+// SQL escaping — use brain.esc() as single source of truth
 // ============================================================
 
-function esc(s) {
-  if (s == null) return '';
-  return String(s).replace(/'/g, "''");
-}
+const esc = brain.esc;
 
 // ============================================================
 // Batch SQL collector
@@ -461,7 +458,7 @@ function indexCodebase(cwd, opts = {}) {
     execFileSync('sqlite3', [dbPath], { input: sql, stdio: ['pipe', 'pipe', 'pipe'] });
   }
 
-  // FIX #1: Clean orphan nodes (deleted/renamed/moved files)
+  // Clean orphan nodes: remove entries for files that no longer exist on disk
   let cleaned = 0;
   if (!changedOnly) {
     const discoveredPaths = new Set(files.map(f => path.relative(cwd, f).replace(/\\/g, '/')));
@@ -483,10 +480,10 @@ function indexCodebase(cwd, opts = {}) {
     }
   }
 
-  // FIX #6: Update hot files on every index
+  // Update hot files from git history on every index
   brain.updateHotFiles(cwd);
 
-  // FIX #11: Run co-change analysis
+  // Run co-change analysis from git history to detect files that change together
   try {
     const gitIntelPath = path.join(__dirname, '..', 'core', 'git-intel.cjs');
     if (fs.existsSync(gitIntelPath)) {
@@ -517,7 +514,7 @@ if (require.main === module) {
   const fresh = args.includes('--fresh');
   const cwd = args.find(a => !a.startsWith('-')) || process.cwd();
 
-  // FIX #8: --fresh flag deletes brain.db first
+  // --fresh flag: delete existing brain.db for full reindex
   if (fresh) {
     const dbPath = path.join(cwd, '.shipfast', 'brain.db');
     if (fs.existsSync(dbPath)) {

package/brain/schema.sql

@@ -7,7 +7,7 @@
 
 CREATE TABLE IF NOT EXISTS nodes (
   id          TEXT PRIMARY KEY,       -- 'file:src/auth.ts', 'fn:validateToken', 'type:User'
-  kind        TEXT NOT NULL,          -- file | function | type | component | route | class | variable | export
+  kind        TEXT NOT NULL CHECK (kind IN ('file','function','type','component','route','class','variable','export')),
   name        TEXT NOT NULL,          -- human-readable name
   file_path   TEXT,                   -- relative file path
   line_start  INTEGER,
@@ -25,7 +25,7 @@ CREATE INDEX IF NOT EXISTS idx_nodes_name ON nodes(name);
 CREATE TABLE IF NOT EXISTS edges (
   source  TEXT NOT NULL,
   target  TEXT NOT NULL,
-  kind    TEXT NOT NULL,               -- imports | calls | implements | depends | mutates | exports | extends
+  kind    TEXT NOT NULL CHECK (kind IN ('imports','calls','implements','depends','mutates','exports','extends','co_changes')),
   weight  REAL DEFAULT 1.0,
   PRIMARY KEY (source, target, kind),
   FOREIGN KEY (source) REFERENCES nodes(id) ON DELETE CASCADE,
@@ -52,6 +52,7 @@ CREATE TABLE IF NOT EXISTS context (
 );
 
 CREATE INDEX IF NOT EXISTS idx_context_scope ON context(scope);
+CREATE INDEX IF NOT EXISTS idx_context_scope_key ON context(scope, key);
 
 -- ============================================================
 -- DECISIONS (replaces decision sections in STATE.md)
@@ -270,3 +271,4 @@ CREATE TABLE IF NOT EXISTS _migrations (
 INSERT OR IGNORE INTO _migrations (version, name) VALUES (1, 'initial_schema');
 INSERT OR IGNORE INTO _migrations (version, name) VALUES (2, 'add_seeds_table');
 INSERT OR IGNORE INTO _migrations (version, name) VALUES (3, 'add_model_performance_table');
+INSERT OR IGNORE INTO _migrations (version, name) VALUES (4, 'add_context_index_and_cleanup');

package/commands/sf/brain.md

@@ -10,6 +10,10 @@ allowed-tools:
 <objective>
 Direct interface to brain.db for querying the codebase knowledge graph,
 decisions, learnings, and task history.
+
+This is the CANONICAL reference for brain.db queries. Other commands that need
+brain data should use MCP tools (brain_decisions, brain_learnings, brain_search, etc.)
+or reference the SQL patterns below — do not invent new queries.
 </objective>
 
 <process>

package/commands/sf/check-plan.md

@@ -17,10 +17,9 @@ Catches scope creep, missing consumers, broken dependencies, and uncovered must-
 
 ## Step 1: Load tasks and must-haves
 
-```bash
-sqlite3 -json .shipfast/brain.db "SELECT id, description, plan_text FROM tasks WHERE status = 'pending' ORDER BY created_at;" 2>/dev/null
-sqlite3 -json .shipfast/brain.db "SELECT value FROM context WHERE key LIKE 'must_haves:%' LIMIT 1;" 2>/dev/null
-```
+Use the `brain_tasks` MCP tool with: `{ "action": "list", "status": "pending" }` — returns pending tasks ordered by created_at.
+
+Use the `brain_context` MCP tool with: `{ "action": "get", "key_like": "must_haves:%", "limit": 1 }` — returns the most recent must-haves entry.
 
 ## Step 2: Check each task
 

package/commands/sf/config.md

@@ -42,6 +42,7 @@ Parse `key value` from arguments. Valid keys:
 - `model-scribe` -> `model_tier_scribe`
 - `auto-checkpoint` -> `auto_checkpoint` (true/false)
 - `auto-learn` -> `auto_learn` (true/false)
+- `post-ship-hook` -> `post_ship_hook` (shell command to run after /sf-ship)
 
 Update brain.db config table. Confirm the change:
 

package/commands/sf/cost.md

@@ -0,0 +1,83 @@
+---
+name: sf:cost
+description: "Show token usage breakdown by agent, domain, and model."
+allowed-tools:
+  - Bash
+---
+
+<objective>
+Analyze token spending to identify expensive patterns and optimize model selection.
+</objective>
+
+<process>
+
+## Query token_usage and model_performance tables
+
+### By agent
+```sql
+SELECT agent, SUM(input_tokens + output_tokens) as total_tokens, COUNT(*) as calls
+FROM token_usage GROUP BY agent ORDER BY total_tokens DESC;
+```
+
+### By model
+```sql
+SELECT model, SUM(input_tokens + output_tokens) as total_tokens, COUNT(*) as calls
+FROM token_usage WHERE model != '' GROUP BY model ORDER BY total_tokens DESC;
+```
+
+### By domain (from model_performance)
+```sql
+SELECT domain, COUNT(*) as tasks,
+  SUM(CASE WHEN outcome='success' THEN 1 ELSE 0 END) as successes,
+  SUM(CASE WHEN outcome='failure' THEN 1 ELSE 0 END) as failures
+FROM model_performance WHERE domain != '' GROUP BY domain ORDER BY tasks DESC;
+```
+
+### Model success rates
+```sql
+SELECT agent, model, outcome, COUNT(*) as count
+FROM model_performance GROUP BY agent, model, outcome ORDER BY agent, model;
+```
+
+### Budget status
+```sql
+SELECT value FROM config WHERE key = 'token_budget';
+```
+```sql
+SELECT COALESCE(SUM(input_tokens + output_tokens), 0) as used FROM token_usage;
+```
+
+## Format report
+
+```
+Token Cost Analysis
+===================
+
+Budget: [used]/[total] ([pct]%)
+
+By Agent:
+  builder   [tokens] tokens  ([calls] calls)
+  scout     [tokens] tokens  ([calls] calls)
+  architect [tokens] tokens  ([calls] calls)
+  critic    [tokens] tokens  ([calls] calls)
+  scribe    [tokens] tokens  ([calls] calls)
+
+By Model:
+  sonnet  [tokens] tokens  ([calls] calls)
+  haiku   [tokens] tokens  ([calls] calls)
+  opus    [tokens] tokens  ([calls] calls)
+
+By Domain:
+  auth      [tasks] tasks  [successes]✓ [failures]✗
+  database  [tasks] tasks  [successes]✓ [failures]✗
+
+Model Success Rates:
+  builder/haiku:   [success]/[total] ([pct]%)
+  builder/sonnet:  [success]/[total] ([pct]%)
+```
+
+</process>
+
+<context>
+$ARGUMENTS
+</context>

package/commands/sf/diff.md

@@ -0,0 +1,53 @@
+---
+name: sf:diff
+description: "Smart diff viewer — changes grouped by task with file stats."
+allowed-tools:
+  - Bash
+---
+
+<objective>
+Show recent changes organized by task, not by commit. Maps each file change
+to the task that caused it, making it easy to review what was done.
+</objective>
+
+<process>
+
+## Step 1: Get recent passed tasks
+
+Use the `brain_tasks` MCP tool with: `{ "action": "list", "status": "passed", "has_commit_sha": true, "limit": 10 }` — returns passed tasks with commits ordered by finished_at descending.
+
+## Step 2: For each task, get the diff stats
+
+```bash
+git show --stat --format='' [commit_sha]
+```
+
+## Step 3: Format as grouped report
+
+```
+Recent Changes by Task
+======================
+
+Task: [description]
+  Commit: [sha] ([date])
+  Files:
+    M src/auth/login.ts       (+15 -3)
+    A src/auth/validate.ts    (+42)
+    M src/types/user.ts       (+5 -1)
+
+Task: [description]
+  Commit: [sha] ([date])
+  Files:
+    M src/api/billing.ts      (+28 -12)
+    A src/hooks/usePayment.ts (+35)
+
+Summary: [N] tasks | [M] files changed | +[additions] -[deletions]
+```
+
+If $ARGUMENTS contains a task ID or description, filter to show only that task's diff in full detail (`git show [sha]`).
+
+</process>
+
+<context>
+$ARGUMENTS
+</context>