@shipfast-ai/shipfast 1.0.2 → 1.1.0

package/README.md

@@ -20,20 +20,20 @@ Works on Mac, Windows, and Linux.
 
 ## Why ShipFast?
 
-AI dev tools fight context rot by generating **more** context — 15+ markdown files per phase, 31 agents, 50+ commands. That's bureaucracy.
+Context rot kills AI coding quality. As the context window fills up, output degrades.
 
-ShipFast flips the model: **compute context on-demand from a SQLite knowledge graph.** Zero markdown files. Each phase gets fresh agent context. The brain gets smarter every session.
+ShipFast fixes this with a **SQLite knowledge graph** that gives each agent fresh context and gets smarter every session.
 
-| | Alternatives | ShipFast |
-|---|---|---|
-| **Commands** | 50+ | 14 |
-| **Agents** | 31 specialized | 5 composable |
-| **Context storage** | ~15 markdown files per phase | 1 SQLite database |
-| **Tokens per feature** | 95K-150K | 3K-40K |
-| **Complex execution** | Per-plan agents (fresh context) | Per-task agents (fresh context) |
-| **Cross-session memory** | Flat STATE.md (manual) | brain.db decisions + learnings (automatic) |
-| **Learning from mistakes** | None | Self-improving with confidence scoring |
-| **Codebase indexing** | 4 parallel agents, minutes | Batch indexer, <1 second |
+- **17 commands, 5 composable agents** — simple to learn, covers the full workflow
+- **SQLite brain** — queryable knowledge graph, no per-task state files
+- **3K-40K tokens per feature** — 70-90% less than typical AI dev workflows
+- **Fresh context per task** — no accumulated garbage between tasks
+- **Cross-session learning** — records decisions and patterns, gets cheaper over time
+- **Codebase indexing in <1 second** — 973 files indexed in 636ms
+- **Graph-derived architecture** — auto-detects layers from import graph
+- **Cross-repo linking** — search across multiple repos with `shipfast link`
+- **17 MCP tools** — structured brain access, no SQL improvisation
+- **Works with 14 AI coding tools** — auto-detects and installs for all
 
 ---
 
@@ -77,7 +77,7 @@ shipfast help           # Show all commands
 
 ## How It Works
 
-Already have code? `shipfast init` indexes your codebase in under 1 second — functions, types, imports, git history. No parallel agents, no markdown files. Just a SQLite database.
+Already have code? `shipfast init` indexes your codebase in under 1 second — functions, types, imports, git history. All stored in a SQLite database.
 
 ### 1. Plan Phase
 
@@ -168,7 +168,7 @@ Creates branch, generates PR description from brain.db (decisions, tasks, change
 /sf-milestone new v2.0
 ```
 
-Or for simple tasks, skip the ceremony:
+Or for simple tasks, just run directly:
 
 ```
 /sf-do fix the login bug
@@ -244,7 +244,7 @@ All exposed as MCP tools: `brain_arch_layers`, `brain_arch_folders`, `brain_arch
 
 ## Agents
 
-5 composable agents replace 31 specialized ones. Same behavioral rules, 90% fewer tokens.
+5 composable agents with compressed behavioral rules.
 
 | Agent | Role | Model | Key Rules |
 |---|---|---|---|

package/agents/builder.md

@@ -59,6 +59,11 @@ Track every deviation: `[Tier N] Fixed: [what] in [file]`
 Only fix issues DIRECTLY caused by your current task.
 Pre-existing problems in other files → do NOT fix. Output:
 `OUT_OF_SCOPE: [file:line] [issue]`
+
+For each out-of-scope issue, also record it as a seed for future work:
+```bash
+sqlite3 .shipfast/brain.db "INSERT INTO seeds (idea, source_task, domain, priority) VALUES ('[improvement idea]', '[current task id]', '[domain]', 'someday');"
+```
 </deviation_tiers>
 
 <patterns>
@@ -149,17 +154,31 @@ Check if your changes introduced:
 - New external service calls
 - Schema changes at trust boundaries
 
+- Schema/model changes without corresponding migrations
+
 If found: `THREAT_FLAG: [type] in [file] — [description]`
+If schema drift: `DRIFT_WARNING: [model file] changed without migration. Run: [migrate command]`
 </threat_scan>
 
 <tdd_mode>
-## TDD (when --tdd flag set)
-
-RED: Write failing test → commit `test(scope): ...`
-GREEN: Minimal code to pass → commit `feat(scope): ...`
-REFACTOR: Optional cleanup → commit `refactor(scope): ...`
-
-Test passes before implementation? STOP — test is wrong. Investigate.
+## TDD (when --tdd flag or MODE: TDD is in context)
+
+**THIS OVERRIDES THE NORMAL EXECUTION ORDER.** When TDD mode is active, follow this sequence strictly:
+
+**Step 1: READ** — Understand what to test. Read relevant files and existing test patterns.
+**Step 2: WRITE TEST** — Write a failing test. Test ONLY, no implementation code.
+**Step 3: RUN TEST** — Run the test. It MUST fail. If it passes, STOP — the test is wrong. Investigate.
+**Step 4: COMMIT RED** — `git add <test files only>` → `test(scope): red - [description]`
+**Step 5: IMPLEMENT** — Write the minimal code to make the test pass. Implementation files only.
+**Step 6: RUN TEST** — Run the test. It MUST pass.
+**Step 7: COMMIT GREEN** — `git add <implementation files only>` → `feat(scope): green - [description]`
+**Step 8: REFACTOR** (optional) — Clean up. Commit as `refactor(scope): [description]`
+
+**NON-NEGOTIABLE RULES:**
+- You MUST NOT write implementation code before committing a failing test
+- Test commits MUST contain only test/spec files
+- Feat commits MUST contain only implementation files (no test files)
+- If you cannot write a meaningful failing test, report: `TDD_BLOCKED: [reason]`
 </tdd_mode>
 
 <context>

package/brain/index.cjs

@@ -322,6 +322,41 @@ 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)
+    VALUES ('${esc(idea)}', '${esc(sourceTask || '')}', '${esc(domain || '')}', '${esc(priority || 'someday')}')`);
+}
+
+function getSeeds(cwd, opts = {}) {
+  const conditions = [];
+  if (opts.status) conditions.push(`status = '${esc(opts.status)}'`);
+  if (opts.domain) conditions.push(`domain = '${esc(opts.domain)}'`);
+  if (opts.priority) conditions.push(`priority = '${esc(opts.priority)}'`);
+  const where = conditions.length ? 'WHERE ' + conditions.join(' AND ') : '';
+  return query(cwd, `SELECT * FROM seeds ${where} ORDER BY created_at DESC LIMIT 30`);
+}
+
+function promoteSeed(cwd, seedId, taskId) {
+  run(cwd, `UPDATE seeds SET status = 'promoted', promoted_to = '${esc(taskId)}' WHERE id = ${parseInt(seedId)}`);
+}
+
+function dismissSeed(cwd, seedId) {
+  run(cwd, `UPDATE seeds SET status = 'dismissed' WHERE id = ${parseInt(seedId)}`);
+}
+
 // ============================================================
 // Utils
 // ============================================================
@@ -366,6 +401,13 @@ module.exports = {
   setConfig,
   buildAgentContext,
   esc,
+  // Model Performance
+  recordModelOutcome,
+  // Seeds
+  addSeed,
+  getSeeds,
+  promoteSeed,
+  dismissSeed,
   // Requirements
   addRequirement,
   getRequirements,

package/brain/schema.sql

@@ -222,6 +222,41 @@ CREATE INDEX IF NOT EXISTS idx_req_category ON requirements(category);
 CREATE INDEX IF NOT EXISTS idx_req_phase ON requirements(phase);
 CREATE INDEX IF NOT EXISTS idx_req_status ON requirements(status);
 
+-- ============================================================
+-- MODEL PERFORMANCE (feedback loop for smart model selection)
+-- ============================================================
+
+CREATE TABLE IF NOT EXISTS model_performance (
+  id          INTEGER PRIMARY KEY AUTOINCREMENT,
+  agent       TEXT NOT NULL,              -- scout | architect | builder | critic | scribe
+  model       TEXT NOT NULL,              -- haiku | sonnet | opus
+  domain      TEXT,                       -- auth, database, ui, etc.
+  task_id     TEXT,                       -- which task this was for
+  outcome     TEXT NOT NULL,              -- success | failure | retry
+  created_at  INTEGER NOT NULL DEFAULT (strftime('%s', 'now'))
+);
+
+CREATE INDEX IF NOT EXISTS idx_model_perf_agent ON model_performance(agent);
+CREATE INDEX IF NOT EXISTS idx_model_perf_domain ON model_performance(domain);
+
+-- ============================================================
+-- SEEDS (forward ideas captured during work)
+-- ============================================================
+
+CREATE TABLE IF NOT EXISTS seeds (
+  id          INTEGER PRIMARY KEY AUTOINCREMENT,
+  idea        TEXT NOT NULL,              -- the improvement, feature, or tech debt idea
+  source_task TEXT,                       -- which task surfaced this idea
+  domain      TEXT,                       -- relevant domain (auth, ui, database, etc.)
+  priority    TEXT DEFAULT 'someday',     -- someday | next | urgent
+  status      TEXT DEFAULT 'open',        -- open | promoted | dismissed
+  promoted_to TEXT,                       -- task_id if promoted to a real task
+  created_at  INTEGER NOT NULL DEFAULT (strftime('%s', 'now'))
+);
+
+CREATE INDEX IF NOT EXISTS idx_seeds_status ON seeds(status);
+CREATE INDEX IF NOT EXISTS idx_seeds_domain ON seeds(domain);
+
 -- ============================================================
 -- MIGRATIONS TRACKING
 -- ============================================================
@@ -233,3 +268,5 @@ 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');

package/commands/sf/brain.md

@@ -49,6 +49,14 @@ WHERE confidence > 0.3 ORDER BY confidence DESC LIMIT 10
 SELECT file_path, change_count FROM hot_files ORDER BY change_count DESC LIMIT 15
 ```
 
+### "seeds" or "ideas" or "future work"
+```sql
+SELECT id, idea, source_task, domain, priority, status FROM seeds
+WHERE status = 'open'
+ORDER BY CASE priority WHEN 'urgent' THEN 0 WHEN 'next' THEN 1 ELSE 2 END, created_at DESC
+LIMIT 20
+```
+
 ### "stats"
 Show counts: nodes, edges, decisions, learnings, tasks, checkpoints
 

package/commands/sf/discuss.md

@@ -89,7 +89,32 @@ Resolved [N] ambiguities:
 Ready for planning. Run /sf-do to continue.
 ```
 
-If `--auto` flag was passed, auto-select recommended defaults instead of asking.
+## Assumptions Mode (when `--assume` flag is set)
+
+Instead of asking questions, auto-resolve ambiguities using codebase patterns:
+
+1. For each detected ambiguity, query brain.db for matching patterns:
+   - **WHERE**: Search nodes table for files matching task keywords
+   - **HOW**: Reuse past HOW decisions or domain learnings
+   - **WHAT**: Infer from task description
+   - **RISK**: Auto-confirm if `.env.local` or `.env.development` exists
+   - **SCOPE**: Default to "tackle all at once" for medium complexity
+
+2. Each auto-resolution has a confidence score (0-1):
+   - Confidence >= 0.5: Accept and lock as decision
+   - Confidence < 0.5: Fall back to asking the user
+
+3. Present assumptions to user before proceeding:
+```
+Assuming (based on codebase patterns):
+  WHERE: src/auth/login.ts, src/auth/session.ts (confidence: 0.8)
+  HOW: Follow existing pattern: jwt-auth (confidence: 0.7)
+  RISK: Confirmed — development environment detected (confidence: 0.7)
+
+Say 'no' to override any of these, or press Enter to continue.
+```
+
+4. Lock accepted assumptions as decisions in brain.db.
 
 </process>
 

package/commands/sf/do.md

@@ -21,6 +21,31 @@ Every step is skippable — trivial tasks burn 3K tokens, complex tasks burn 30K
 
 <pipeline>
 
+## STEP 0: PARSE FLAGS (0 LLM tokens — string matching)
+
+Extract flags from `$ARGUMENTS` before processing. Flags start with `--` and are composable.
+
+**Supported flags:**
+- `--discuss` — Force discuss step (Step 3) even for trivial tasks
+- `--research` — Force Scout agent to run (override skip-scout heuristics)
+- `--verify` — Force full verification (Step 7) even for trivial tasks
+- `--tdd` — Enable TDD mode: Builder writes failing test first, verification checks commit sequence
+- `--no-plan` — Skip discuss (Step 3) and plan (Step 4), go straight to execute
+- `--cheap` — Force ALL agents to use haiku (fastest, cheapest, ~80% cost reduction)
+- `--quality` — Force builder/architect to sonnet, architect to opus for complex tasks
+
+**Parse procedure:**
+1. Extract all `--flag` tokens from the input
+2. Remove them from the task description (remaining text = task)
+3. Store flags as a set for downstream steps to check
+
+Example: `/sf-do --tdd --research add user avatars`
+→ flags: `{tdd, research}`, task: `add user avatars`
+
+If no flags provided, all steps use their default heuristic-based behavior.
+
+---
+
 ## STEP 1: ANALYZE (0 LLM tokens — rule-based)
 
 Classify the user's input using these heuristics:
@@ -51,6 +76,44 @@ Classify the user's input using these heuristics:
 
 ---
 
+## STEP 1.5: OPTIMIZE PIPELINE (0 tokens — brain.db queries only)
+
+Call `applyGuardrails()` from `core/guardrails.cjs` to optimize the entire pipeline in one shot.
+
+**Input**: Build a task object from Step 1's analysis:
+```javascript
+task = { intent, complexity, domain, affectedFiles, areas, input: taskDescription }
+```
+
+**What applyGuardrails() does** (already implemented):
+1. **Skip logic** — Decides which agents to skip based on brain.db knowledge
+2. **Learning acceleration** — If 3+ high-confidence learnings exist, skip scout+architect+critic
+3. **Budget adjustment** — If budget low (<60%), downgrade models; if critical (<20%), builder-only + haiku
+4. **Model selection** — Dynamic per-agent model based on task characteristics:
+   - Builder → haiku when domain has 2+ high-confidence learnings, or trivial single-file fix
+   - Architect → opus for complex multi-area tasks with no prior patterns
+   - Critic → sonnet for security/auth tasks
+5. **Predictive context** — Pre-loads co-change file signatures into context
+
+**Output**: `{ pipeline, models, outputLevel, predictedContext, acceleration, budgetNotes }`
+
+**Report model plan to user** (for medium/complex tasks):
+```
+Models: Scout=haiku, Architect=sonnet, Builder=sonnet, Critic=haiku
+Pipeline: scout → architect → builder → critic (acceleration: partial, 35% cheaper)
+```
+
+**Flag overrides for model selection:**
+- If `--cheap` flag: Override ALL models to `haiku` regardless of guardrails output
+- If `--quality` flag: Override `builder` to `sonnet`, `architect` to `opus` (for complex) or `sonnet` (for medium)
+
+**Use the output for ALL downstream steps:**
+- Steps 3-4: Use `pipeline` to decide which agents run (replaces scattered skip-if checks)
+- Step 6: Use `models[agent]` when spawning each agent
+- Step 9: Use `outputLevel` for report format
+
+---
+
 ## STEP 2: CONTEXT GATHERING (0 tokens)
 
 **FIX #5: Git diff awareness** — Run `git diff --name-only HEAD` to see what files changed since last commit. Pass this list to Scout so it focuses on recent changes instead of searching blindly.
@@ -63,7 +126,8 @@ If `.shipfast/brain.db` does not exist, tell user to run `shipfast init` first.
 
 ## STEP 3: DISCUSS (0-3K tokens) — Complex or ambiguous tasks only
 
-**Skip if**: trivial tasks, or if all ambiguity types already have locked decisions in brain.db.
+**Skip if**: `--no-plan` flag is set, OR (trivial tasks AND `--discuss` flag is NOT set), OR all ambiguity types already have locked decisions in brain.db.
+**Force if**: `--discuss` flag is set, regardless of complexity.
 
 **Detect ambiguity** (zero tokens — rule-based):
 - **WHERE**: No file paths or component names mentioned
@@ -74,14 +138,15 @@ If `.shipfast/brain.db` does not exist, tell user to run `shipfast init` first.
 
 **For each detected ambiguity**:
 1. Check brain.db for existing locked decisions
-2. If unanswered, ask the user (prefer multiple choice to save typing)
-3. Store answer as locked decision in brain.db (never asked again)
+2. If `--discuss` flag is set explicitly, ask the user interactively
+3. For medium tasks (auto-triggered discuss), use assumptions mode: auto-resolve using brain.db patterns, present assumptions, fall back to asking only if confidence < 0.5
+4. Store answer as locked decision in brain.db (never asked again)
 
 ---
 
 ## STEP 4: PLAN (0-5K tokens) — Medium/complex only
 
-**Skip if**: trivial tasks (go directly to Step 6)
+**Skip if**: `--no-plan` flag is set (go directly to Step 6), OR trivial tasks (go directly to Step 6)
 
 **Get plan template** based on intent:
 - `fix` → locate, diagnose, fix, verify
@@ -89,7 +154,7 @@ If `.shipfast/brain.db` does not exist, tell user to run `shipfast init` first.
 - `refactor` → identify, extract, update callers, verify
 - etc. (14 templates pre-computed in core/templates.cjs)
 
-**Skip Scout if**:
+**Skip Scout if** (`--research` flag overrides — if set, Scout always runs):
 - All affected files already indexed in brain.db AND
 - We have high-confidence learnings for this domain AND
 - Intent is `fix` with explicit file paths
@@ -99,9 +164,9 @@ If `.shipfast/brain.db` does not exist, tell user to run `shipfast init` first.
 - Intent is fix/remove/docs/style
 - Task description is under 15 words
 
-**If Scout runs**: Launch Scout agent with brain context. Get compact findings (~3K tokens max).
+**If Scout runs**: Launch Scout agent with brain context and `model: models.scout` from Step 1.5. Get compact findings (~3K tokens max).
 
-**If Architect runs**: Launch Architect agent with Scout findings + template. Get task list (~3K tokens max).
+**If Architect runs**: Launch Architect agent with Scout findings + template and `model: models.architect` from Step 1.5. Get task list (~3K tokens max).
 - Architect uses goal-backward methodology: define "done" first, derive tasks from that
 - Maximum 6 tasks. Each with specific file paths and verify steps.
 - Flag scope creep and irreversible operations.
@@ -141,11 +206,12 @@ Execute inline. No planning, no Scout, no Architect, no Critic.
 **Redirect**: if work exceeds 3 file edits or needs research → upgrade to medium workflow.
 
 ### Medium workflow (1 Builder agent):
-Launch ONE Builder agent with ALL tasks batched:
+Launch ONE Builder agent with ALL tasks batched and `model: models.builder` from Step 1.5:
 - Agent gets: base prompt + brain context + all task descriptions
+- If `--tdd` flag is set, prepend to Builder context: `MODE: TDD (red→green→refactor). Write failing test FIRST. See <tdd_mode> in builder prompt.`
 - Agent executes tasks sequentially within its context
 - One agent call instead of one per task = token savings
-- If Critic is not skipped, launch Critic after Builder completes
+- If Critic is not skipped, launch Critic with `model: models.critic` after Builder completes
 
 ### Complex workflow (per-task agents, fresh context each):
 
@@ -158,16 +224,18 @@ If tasks found in brain.db, execute them. If not, run inline planning first.
 
 **Per-task execution (fresh context per task):**
 For each pending task in brain.db:
-1. Launch a SEPARATE sf-builder agent with ONLY that task + brain context
+1. Launch a SEPARATE sf-builder agent with ONLY that task + brain context + `model: models.builder` from Step 1.5. If `--tdd` flag is set, prepend `MODE: TDD (red→green→refactor). Write failing test FIRST.` to the task context.
 2. Builder gets fresh context — no accumulated garbage from previous tasks
 3. Builder executes: read → grep consumers → implement → build → verify → commit
-4. After Builder completes, update task status in brain.db:
+4. After Builder completes, update task status and record model outcome:
    ```bash
    sqlite3 .shipfast/brain.db "UPDATE tasks SET status='passed', commit_sha='[sha]' WHERE id='[id]';"
+   sqlite3 .shipfast/brain.db "INSERT INTO model_performance (agent, model, domain, task_id, outcome) VALUES ('builder', '[model used]', '[domain]', '[id]', 'success');"
    ```
 5. If Builder fails after 3 attempts:
    ```bash
    sqlite3 .shipfast/brain.db "UPDATE tasks SET status='failed', error='[error]' WHERE id='[id]';"
+   sqlite3 .shipfast/brain.db "INSERT INTO model_performance (agent, model, domain, task_id, outcome) VALUES ('builder', '[model used]', '[domain]', '[id]', 'failure');"
    ```
 6. Continue to next task regardless
 
@@ -177,8 +245,8 @@ For each pending task in brain.db:
 - Tasks touching same files → sequential (never parallel)
 
 **After all tasks:**
-- Launch Critic agent (fresh context) to review ALL changes: `git diff HEAD~N`
-- Launch Scribe agent (fresh context) to record decisions + learnings to brain.db
+- Launch Critic agent (fresh context) with `model: models.critic` to review ALL changes: `git diff HEAD~N`
+- Launch Scribe agent (fresh context) with `model: models.scribe` to record decisions + learnings to brain.db
 - Save session state for `/sf-resume`
 
 **After execution, run `/sf-verify` for thorough verification.**
@@ -197,7 +265,8 @@ Send the issue back to Builder for fix (1 additional agent call, not a full re-r
 
 ## STEP 7: VERIFY (0-3K tokens)
 
-**Skip if**: trivial tasks with passing build
+**Skip if**: trivial tasks with passing build, UNLESS `--verify` flag is set
+**Force if**: `--verify` flag is set, regardless of complexity
 
 Run goal-backward verification:
 1. Extract done-criteria from the original request + plan
@@ -250,7 +319,12 @@ If you encountered and fixed any errors, record the pattern:
 sqlite3 .shipfast/brain.db "INSERT INTO learnings (pattern, problem, solution, domain, source, confidence) VALUES ('[short pattern name]', '[what went wrong]', '[what fixed it]', '[domain]', 'auto', 0.5);"
 ```
 
-**These are not optional.** If decisions were made or errors were fixed, you MUST record them. This is how ShipFast gets smarter over time.
+If any improvement ideas, future features, or tech debt were surfaced during this task (including OUT_OF_SCOPE items), record them as seeds:
+```bash
+sqlite3 .shipfast/brain.db "INSERT INTO seeds (idea, source_task, domain, priority) VALUES ('[idea]', '[current task]', '[domain]', 'someday');"
+```
+
+**These are not optional.** If decisions were made, errors were fixed, or ideas were surfaced, you MUST record them. This is how ShipFast gets smarter over time.
 
 ---
 

package/commands/sf/milestone.md

@@ -11,7 +11,7 @@ allowed-tools:
 <objective>
 Manage project milestones. Complete the current milestone (archive phases, tag release)
 or start a new one (reset phases, increment version).
-All state tracked in brain.db — no markdown files.
+All state tracked in brain.db.
 </objective>
 
 <process>

package/commands/sf/verify.md

@@ -71,6 +71,29 @@ Check each for:
 - debugger statements
 - Commented-out code blocks
 
+## Step 5.5: Schema drift detection
+
+Check if ORM model/schema files were changed without a corresponding migration:
+
+1. Get changed files: `git diff --name-only HEAD~5`
+2. Detect ORM type by file pattern:
+   - Prisma: `*.prisma` files
+   - Drizzle: files containing `pgTable`/`sqliteTable`/`mysqlTable`
+   - TypeORM: files containing `@Entity`/`@Column` decorators
+   - Django: `models.py` files
+   - Rails: `app/models/` files
+   - Knex: `models/*.ts` or `models/*.js`
+3. Check if migration files also changed in the same diff
+4. If model changed without migration → **DRIFT WARNING** (not FAIL)
+
+```
+Schema: [ORM type] model changed: [files]
+Migration: MISSING
+Suggest: Run [migration command] to generate migration
+```
+
+This check can be suppressed by setting `schema_drift_check = false` in brain.db config.
+
 ## Step 6: Build verification
 
 ```bash

package/core/ambiguity.cjs

@@ -195,6 +195,111 @@ function buildDiscussionPrompt(input, ambiguities, brainContext) {
   return parts.join('\n');
 }
 
+/**
+ * Auto-resolve ambiguities using codebase patterns from brain.db.
+ * Used by --assume flag to skip interactive questioning.
+ * Returns array of { type, decision, confidence, reasoning }.
+ * Falls back to asking the user if confidence < 0.5.
+ */
+function autoResolveAmbiguity(cwd, ambiguities, taskInput) {
+  const resolved = [];
+
+  for (const a of ambiguities) {
+    let decision = null;
+    let confidence = 0;
+    let reasoning = '';
+
+    switch (a.type) {
+      case 'WHERE': {
+        // Search brain.db nodes for files matching task keywords
+        const keywords = taskInput.split(/\s+/).filter(w => w.length > 3);
+        for (const kw of keywords) {
+          const matches = brain.query(cwd,
+            `SELECT file_path, name FROM nodes WHERE kind = 'file' AND (name LIKE '%${brain.esc(kw)}%' OR file_path LIKE '%${brain.esc(kw)}%') LIMIT 5`
+          );
+          if (matches.length > 0) {
+            decision = matches.map(m => m.file_path).join(', ');
+            confidence = matches.length === 1 ? 0.8 : 0.6;
+            reasoning = 'Matched ' + matches.length + ' file(s) by keyword "' + kw + '"';
+            break;
+          }
+        }
+        if (!decision) {
+          confidence = 0.2;
+          reasoning = 'No matching files found in brain.db';
+        }
+        break;
+      }
+
+      case 'HOW': {
+        // Reuse past HOW decisions in the same domain
+        const pastDecisions = brain.getDecisions(cwd);
+        const howDecision = pastDecisions.find(d => d.tags && d.tags.includes('HOW'));
+        if (howDecision) {
+          decision = howDecision.decision;
+          confidence = 0.7;
+          reasoning = 'Reusing previous HOW decision: ' + howDecision.question;
+        } else {
+          // Check learnings for the domain
+          const words = taskInput.toLowerCase().split(/\s+/);
+          const domains = ['auth', 'database', 'ui', 'api', 'frontend', 'backend', 'cache', 'search', 'payment'];
+          const domain = domains.find(d => words.includes(d));
+          if (domain) {
+            const learnings = brain.findLearnings(cwd, domain, 1);
+            if (learnings.length > 0) {
+              decision = 'Follow existing pattern: ' + learnings[0].pattern;
+              confidence = learnings[0].confidence;
+              reasoning = 'Based on learning with confidence ' + learnings[0].confidence;
+            }
+          }
+          if (!decision) { confidence = 0.3; reasoning = 'No prior decisions or learnings found'; }
+        }
+        break;
+      }
+
+      case 'WHAT': {
+        // Use task description as-is for short inputs
+        decision = 'Inferred from task description';
+        confidence = 0.6;
+        reasoning = 'Task description used as behavior spec';
+        break;
+      }
+
+      case 'RISK': {
+        // Auto-confirm in dev environment
+        const isDevEnv = require('fs').existsSync(require('path').join(cwd, '.env.local'))
+          || require('fs').existsSync(require('path').join(cwd, '.env.development'));
+        if (isDevEnv) {
+          decision = 'Confirmed — development environment detected';
+          confidence = 0.7;
+          reasoning = '.env.local or .env.development found';
+        } else {
+          confidence = 0.3;
+          reasoning = 'No dev environment indicators — needs user confirmation';
+        }
+        break;
+      }
+
+      case 'SCOPE': {
+        decision = 'Tackle all at once';
+        confidence = 0.5;
+        reasoning = 'Default: single pass unless complexity warrants phasing';
+        break;
+      }
+    }
+
+    resolved.push({
+      type: a.type,
+      question: a.question,
+      decision: decision || 'Could not auto-resolve',
+      confidence,
+      reasoning
+    });
+  }
+
+  return resolved;
+}
+
 module.exports = {
   detectAmbiguity,
   ambiguityScore,
@@ -202,5 +307,6 @@ module.exports = {
   lockDecision,
   shouldDiscuss,
   buildDiscussionPrompt,
+  autoResolveAmbiguity,
   AMBIGUITY_RULES
 };

package/core/guardrails.cjs

@@ -255,9 +255,12 @@ function formatReport(results, outputLevel) {
  * Apply all guardrails to a pipeline.
  * Returns the optimized pipeline with all adjustments.
  */
-function applyGuardrails(cwd, sessionId, task, basePipeline) {
+/**
+ * @param {object} [flags] - Composable flags from parseFlags() (--cheap, --quality, etc.)
+ */
+function applyGuardrails(cwd, sessionId, task, basePipeline, flags = {}) {
   // 1. Skip logic (brain.db knowledge)
-  let pipeline = skipLogic.getAgentPipeline(cwd, task);
+  let pipeline = skipLogic.getAgentPipeline(cwd, task, flags);
 
   // 2. Learning acceleration
   const accel = accelerateFromLearnings(cwd, task, pipeline);
@@ -273,10 +276,25 @@ function applyGuardrails(cwd, sessionId, task, basePipeline) {
     models[agent] = budgetAdj.models[agent] || modelSelector.selectModel(cwd, agent, task);
   }
 
-  // 5. Output level
+  // 5. Flag overrides (--cheap / --quality take precedence)
+  if (flags.cheap) {
+    for (const agent of pipeline) {
+      models[agent] = 'haiku';
+    }
+  } else if (flags.quality) {
+    for (const agent of pipeline) {
+      if (agent === 'architect') {
+        models[agent] = task.complexity === 'complex' ? 'opus' : 'sonnet';
+      } else if (agent === 'builder') {
+        models[agent] = 'sonnet';
+      }
+    }
+  }
+
+  // 6. Output level
   const outputLevel = getOutputLevel(task.complexity);
 
-  // 6. Predictive context
+  // 7. Predictive context
   const predictedContext = buildPredictiveContext(cwd, task);
 
   return {

package/core/model-selector.cjs

@@ -41,8 +41,23 @@ function selectScoutModel(cwd, task) {
 }
 
 function selectArchitectModel(cwd, task) {
-  // Complex multi-area tasks need better reasoning
-  if (task.complexity === 'complex' && task.areas && task.areas.length > 2) {
+  // Complex multi-area tasks with no prior patterns → Opus
+  // Opus costs 25x but is used rarely; pays for itself in fewer revision cycles
+  if (task.complexity === 'complex' && task.areas && task.areas.length > 3) {
+    if (task.domain) {
+      const learnings = brain.findLearnings(cwd, task.domain, 3);
+      const highConfidence = learnings.filter(l => l.confidence > 0.8 && l.solution);
+      if (highConfidence.length === 0) {
+        return 'opus'; // uncharted territory + complex = worth the cost
+      }
+    } else {
+      return 'opus'; // no domain = no learnings = needs best reasoning
+    }
+    return 'sonnet';
+  }
+
+  // Complex but fewer areas → Sonnet
+  if (task.complexity === 'complex') {
     return 'sonnet';
   }
 
@@ -55,6 +70,18 @@ function selectArchitectModel(cwd, task) {
 }
 
 function selectBuilderModel(cwd, task) {
+  // Check feedback loop: if haiku failed recently for this domain, upgrade
+  if (task.domain) {
+    const stats = getModelSuccessRate(cwd, 'builder', task.domain);
+    if (stats.haikuRate !== null && stats.haikuRate < 0.6) {
+      return 'sonnet'; // haiku struggling in this domain → upgrade
+    }
+    if (stats.sonnetRate !== null && stats.sonnetRate > 0.9 && stats.sonnetTotal >= 3) {
+      // Sonnet consistently succeeds here → try haiku next time to save cost
+      return 'haiku';
+    }
+  }
+
   // Key insight: if we've solved similar problems before, Haiku can replicate
   if (task.domain) {
     const learnings = brain.findLearnings(cwd, task.domain, 3);
@@ -78,6 +105,36 @@ function selectBuilderModel(cwd, task) {
   return 'sonnet';
 }
 
+/**
+ * Get model success rate for an agent+domain combo from the feedback table.
+ * Returns { haikuRate, sonnetRate, haikuTotal, sonnetTotal } (null if no data).
+ */
+function getModelSuccessRate(cwd, agent, domain) {
+  const rows = brain.query(cwd,
+    `SELECT model, outcome, COUNT(*) as c FROM model_performance
+     WHERE agent = '${brain.esc(agent)}' AND domain = '${brain.esc(domain)}'
+     GROUP BY model, outcome`
+  );
+
+  const stats = { haikuRate: null, sonnetRate: null, haikuTotal: 0, sonnetTotal: 0 };
+  const haikuSuccess = rows.find(r => r.model === 'haiku' && r.outcome === 'success');
+  const haikuFailure = rows.find(r => r.model === 'haiku' && r.outcome === 'failure');
+  const sonnetSuccess = rows.find(r => r.model === 'sonnet' && r.outcome === 'success');
+  const sonnetFailure = rows.find(r => r.model === 'sonnet' && r.outcome === 'failure');
+
+  const hS = haikuSuccess ? haikuSuccess.c : 0;
+  const hF = haikuFailure ? haikuFailure.c : 0;
+  const sS = sonnetSuccess ? sonnetSuccess.c : 0;
+  const sF = sonnetFailure ? sonnetFailure.c : 0;
+
+  stats.haikuTotal = hS + hF;
+  stats.sonnetTotal = sS + sF;
+  if (stats.haikuTotal > 0) stats.haikuRate = hS / stats.haikuTotal;
+  if (stats.sonnetTotal > 0) stats.sonnetRate = sS / stats.sonnetTotal;
+
+  return stats;
+}
+
 function selectCriticModel(cwd, task) {
   // Security-related reviews need better reasoning
   if (task.intent === 'security' || (task.areas && task.areas.includes('auth'))) {

package/core/skip-logic.cjs

@@ -10,8 +10,12 @@ const brain = require('../brain/index.cjs');
 /**
  * Should we skip Scout (research agent)?
  * Skip if: all files are indexed AND we have relevant learnings
+ * @param {object} [flags] - Composable flags from /sf-do (--research, --discuss, etc.)
  */
-function shouldSkipScout(cwd, task) {
+function shouldSkipScout(cwd, task, flags = {}) {
+  // --research flag forces Scout to run
+  if (flags.research) return false;
+
   // Always need Scout for complex tasks
   if (task.complexity === 'complex') return false;
 
@@ -41,8 +45,12 @@ function shouldSkipScout(cwd, task) {
 /**
  * Should we skip Architect (planning agent)?
  * Skip if: single-file change OR known template with high confidence
+ * @param {object} [flags] - Composable flags from /sf-do
  */
-function shouldSkipArchitect(cwd, task) {
+function shouldSkipArchitect(cwd, task, flags = {}) {
+  // --no-plan flag skips Architect
+  if (flags.noPlan) return true;
+
   // Never skip for complex tasks
   if (task.complexity === 'complex') return false;
 
@@ -61,8 +69,11 @@ function shouldSkipArchitect(cwd, task) {
 /**
  * Should we skip Critic (review agent)?
  * Skip if: trivial change OR docs-only OR test-only
+ * @param {object} [flags] - Composable flags from /sf-do
  */
-function shouldSkipCritic(cwd, task) {
+function shouldSkipCritic(cwd, task, flags = {}) {
+  // --verify flag forces Critic to run
+  if (flags.verify) return false;
   // Always review complex tasks
   if (task.complexity === 'complex') return false;
 
@@ -89,25 +100,55 @@ function shouldSkipScribe(cwd, task) {
   return false;
 }
 
+/**
+ * Parse composable flags from user input.
+ * Returns { flags, task } where task is the input with flags stripped.
+ */
+function parseFlags(input) {
+  const flags = {};
+  const flagMap = {
+    '--discuss': 'discuss',
+    '--research': 'research',
+    '--verify': 'verify',
+    '--tdd': 'tdd',
+    '--no-plan': 'noPlan',
+    '--cheap': 'cheap',
+    '--quality': 'quality'
+  };
+
+  let task = input;
+  for (const [flag, key] of Object.entries(flagMap)) {
+    if (task.includes(flag)) {
+      flags[key] = true;
+      task = task.replace(flag, '').trim();
+    }
+  }
+
+  // Clean up extra whitespace
+  task = task.replace(/\s+/g, ' ').trim();
+  return { flags, task };
+}
+
 /**
  * Get the optimized agent pipeline for a task.
  * Returns only the agents that should run.
+ * @param {object} [flags] - Composable flags from parseFlags()
  */
-function getAgentPipeline(cwd, task) {
+function getAgentPipeline(cwd, task, flags = {}) {
   const pipeline = [];
 
-  if (!shouldSkipScout(cwd, task)) {
+  if (!shouldSkipScout(cwd, task, flags)) {
     pipeline.push('scout');
   }
 
-  if (!shouldSkipArchitect(cwd, task)) {
+  if (!shouldSkipArchitect(cwd, task, flags)) {
     pipeline.push('architect');
   }
 
   // Builder always runs
   pipeline.push('builder');
 
-  if (!shouldSkipCritic(cwd, task)) {
+  if (!shouldSkipCritic(cwd, task, flags)) {
     pipeline.push('critic');
   }
 
@@ -142,6 +183,7 @@ function estimateSavings(fullPipeline, optimizedPipeline) {
 }
 
 module.exports = {
+  parseFlags,
   shouldSkipScout,
   shouldSkipArchitect,
   shouldSkipCritic,

package/core/verify.cjs

@@ -400,9 +400,14 @@ function verifyWithAutoFix(cwd, criteria, executeFixFn) {
 /**
  * Verify TDD commit sequence: test(...) → feat(...) → optional refactor(...)
  */
+/**
+ * Verify TDD commit sequence: test(...) → feat(...) → optional refactor(...)
+ * Enhanced: also checks that test commits contain only test files and feat commits
+ * contain only implementation files.
+ */
 function verifyTddSequence(cwd, numCommits) {
   try {
-    const log = safeRun('git', ['log', '--oneline', '-' + (numCommits || 10)], {
+    const log = safeExec('git', ['log', '--oneline', '-' + (numCommits || 10)], {
       cwd, encoding: 'utf8'
     }).trim().split('\n');
 
@@ -418,7 +423,40 @@ function verifyTddSequence(cwd, numCommits) {
 
     // test commit should come BEFORE feat commit (higher index = older in git log)
     if (featCommit && testIdx < featIdx) {
-      return { passed: true, detail: 'TDD sequence valid: test → feat' };
+      // Verify test commit contains only test files
+      const violations = [];
+      const testSha = testCommit.split(' ')[0];
+      const featSha = featCommit.split(' ')[0];
+
+      try {
+        const testFiles = safeExec('git', ['diff-tree', '--no-commit-id', '--name-only', '-r', testSha], {
+          cwd, encoding: 'utf8'
+        }).trim().split('\n').filter(Boolean);
+
+        const nonTestFiles = testFiles.filter(f =>
+          !f.includes('test') && !f.includes('spec') && !f.includes('__tests__')
+        );
+        if (nonTestFiles.length > 0) {
+          violations.push('RED commit contains non-test files: ' + nonTestFiles.join(', '));
+        }
+
+        const featFiles = safeExec('git', ['diff-tree', '--no-commit-id', '--name-only', '-r', featSha], {
+          cwd, encoding: 'utf8'
+        }).trim().split('\n').filter(Boolean);
+
+        const testInFeat = featFiles.filter(f =>
+          f.includes('test') || f.includes('spec') || f.includes('__tests__')
+        );
+        if (testInFeat.length > 0) {
+          violations.push('GREEN commit contains test files: ' + testInFeat.join(', '));
+        }
+      } catch { /* git diff-tree may fail for initial commits */ }
+
+      if (violations.length > 0) {
+        return { passed: false, detail: 'TDD sequence valid but file separation violated:\n' + violations.join('\n') };
+      }
+
+      return { passed: true, detail: 'TDD sequence valid: test → feat (file separation OK)' };
     }
 
     if (!featCommit) {
@@ -431,9 +469,94 @@ function verifyTddSequence(cwd, numCommits) {
   }
 }
 
+// ============================================================
+// Schema Drift Detection
+// ============================================================
+
+/**
+ * ORM/schema file patterns and their corresponding migration directories.
+ * Detects when model files change without a corresponding migration.
+ */
+const SCHEMA_PATTERNS = [
+  // Prisma
+  { model: /\.prisma$/, migration: /prisma\/migrations\//, name: 'Prisma', migrateCmd: 'npx prisma migrate dev' },
+  // Drizzle
+  { model: /pgTable|sqliteTable|mysqlTable/, migration: /drizzle\/|migrations\/\d/, name: 'Drizzle', migrateCmd: 'npx drizzle-kit generate' },
+  // TypeORM
+  { model: /@Entity|@Column|@ManyToOne|@OneToMany/, migration: /migrations\/\d/, name: 'TypeORM', migrateCmd: 'npx typeorm migration:generate' },
+  // Django
+  { model: /models\.py$/, migration: /\/migrations\/\d/, name: 'Django', migrateCmd: 'python manage.py makemigrations' },
+  // Rails
+  { model: /app\/models\//, migration: /db\/migrate\//, name: 'Rails', migrateCmd: 'rails generate migration' },
+  // Knex
+  { model: /models\/.*\.(js|ts)$/, migration: /migrations\/\d/, name: 'Knex', migrateCmd: 'npx knex migrate:make' },
+];
+
+/**
+ * Detect schema drift: model/schema files changed without corresponding migrations.
+ * Returns { hasDrift, modelChanges, migrationChanges, ormType, migrateCmd }
+ */
+function detectSchemaDrift(cwd, numCommits) {
+  let changedFiles;
+  try {
+    changedFiles = safeExec('git', ['diff', '--name-only', 'HEAD~' + (numCommits || 5)], {
+      cwd, encoding: 'utf8'
+    }).trim().split('\n').filter(Boolean);
+  } catch {
+    return { hasDrift: false, detail: 'Could not read git diff' };
+  }
+
+  if (changedFiles.length === 0) {
+    return { hasDrift: false, detail: 'No changed files' };
+  }
+
+  // Check file contents for ORM patterns (for content-based detection like Drizzle/TypeORM)
+  function fileMatchesContentPattern(filePath, pattern) {
+    if (pattern.source.includes('/') || pattern.source.endsWith('$')) {
+      // Path-based pattern
+      return pattern.test(filePath);
+    }
+    // Content-based pattern — read the file
+    const fullPath = path.join(cwd, filePath);
+    if (!fs.existsSync(fullPath)) return false;
+    try {
+      const content = fs.readFileSync(fullPath, 'utf8').slice(0, 5000);
+      return pattern.test(content);
+    } catch { return false; }
+  }
+
+  for (const schema of SCHEMA_PATTERNS) {
+    const modelChanges = changedFiles.filter(f => {
+      if (schema.model.source.includes('/') || schema.model.source.endsWith('$')) {
+        return schema.model.test(f);
+      }
+      return fileMatchesContentPattern(f, schema.model);
+    });
+
+    if (modelChanges.length === 0) continue;
+
+    const migrationChanges = changedFiles.filter(f => schema.migration.test(f));
+
+    if (migrationChanges.length === 0) {
+      return {
+        hasDrift: true,
+        ormType: schema.name,
+        modelChanges,
+        migrationChanges: [],
+        migrateCmd: schema.migrateCmd,
+        detail: schema.name + ' model files changed without migration: ' + modelChanges.join(', ')
+          + '. Run: ' + schema.migrateCmd
+      };
+    }
+  }
+
+  return { hasDrift: false, detail: 'No schema drift detected' };
+}
+
 module.exports = {
   extractDoneCriteria, runVerification, scoreResults, recordVerification, formatResults,
   verifyBuild, verifyNoStubs, verifyNoStubsDeep, detectBuildCommand,
   verifyArtifact3Level, verifyDataFlow,
-  generateFixTasks, verifyWithAutoFix, verifyTddSequence
+  generateFixTasks, verifyWithAutoFix, verifyTddSequence,
+  detectSchemaDrift
 };

package/mcp/server.cjs

@@ -103,7 +103,8 @@ const TOOLS = {
         "UNION ALL SELECT 'learnings', COUNT(*) FROM learnings " +
         "UNION ALL SELECT 'tasks', COUNT(*) FROM tasks " +
         "UNION ALL SELECT 'checkpoints', COUNT(*) FROM checkpoints " +
-        "UNION ALL SELECT 'hot_files', COUNT(*) FROM hot_files"
+        "UNION ALL SELECT 'hot_files', COUNT(*) FROM hot_files " +
+        "UNION ALL SELECT 'seeds', COUNT(*) FROM seeds WHERE status = 'open'"
       );
       const stats = {};
       rows.forEach(r => stats[r.metric] = r.count);
@@ -245,6 +246,46 @@ const TOOLS = {
     }
   },
 
+  brain_seeds: {
+    description: 'List, add, promote, or dismiss forward ideas (seeds). Seeds capture improvement ideas surfaced during work for future milestones.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        action: { type: 'string', description: 'list, add, promote, or dismiss', enum: ['list', 'add', 'promote', 'dismiss'] },
+        idea: { type: 'string', description: 'The idea text (required for add)' },
+        source_task: { type: 'string', description: 'Which task surfaced this idea (optional)' },
+        domain: { type: 'string', description: 'Domain: frontend, backend, database, auth, etc. (optional)' },
+        priority: { type: 'string', description: 'someday, next, or urgent (optional, default: someday)', enum: ['someday', 'next', 'urgent'] },
+        seed_id: { type: 'number', description: 'Seed ID (required for promote/dismiss)' },
+        task_id: { type: 'string', description: 'Task ID to promote seed to (required for promote)' }
+      },
+      required: ['action']
+    },
+    handler({ action, idea, source_task, domain, priority, seed_id, task_id }) {
+      if (action === 'add') {
+        if (!idea) return { error: 'idea is required' };
+        const ok = run(
+          `INSERT INTO seeds (idea, source_task, domain, priority) ` +
+          `VALUES ('${esc(idea)}', '${esc(source_task || '')}', '${esc(domain || '')}', '${esc(priority || 'someday')}')`
+        );
+        return ok ? { status: 'recorded', idea, domain, priority: priority || 'someday' } : { error: 'failed to insert' };
+      }
+      if (action === 'promote') {
+        if (!seed_id || !task_id) return { error: 'seed_id and task_id are required' };
+        const ok = run(`UPDATE seeds SET status = 'promoted', promoted_to = '${esc(task_id)}' WHERE id = ${parseInt(seed_id)}`);
+        return ok ? { status: 'promoted', seed_id, task_id } : { error: 'failed to update' };
+      }
+      if (action === 'dismiss') {
+        if (!seed_id) return { error: 'seed_id is required' };
+        const ok = run(`UPDATE seeds SET status = 'dismissed' WHERE id = ${parseInt(seed_id)}`);
+        return ok ? { status: 'dismissed', seed_id } : { error: 'failed to update' };
+      }
+      // list
+      const filter = domain ? `AND domain = '${esc(domain)}'` : '';
+      return query(`SELECT id, idea, source_task, domain, priority, status, created_at FROM seeds WHERE status = 'open' ${filter} ORDER BY CASE priority WHEN 'urgent' THEN 0 WHEN 'next' THEN 1 ELSE 2 END, created_at DESC LIMIT 30`);
+    }
+  },
+
   // Feature #6: Graph traversal tools
 
   brain_graph_traverse: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shipfast-ai/shipfast",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "description": "Autonomous context-engineered development system with SQLite brain. 5 agents, 14 commands, per-task fresh context, 70-90% fewer tokens.",
   "bin": {
     "shipfast": "bin/install.js"