preflight-dev 3.1.0

package/src/lib/triage.ts

@@ -0,0 +1,255 @@
+/**
+ * Smart triage classification system for preflight MCP server.
+ * Classifies incoming prompts into categories and returns recommended action.
+ *
+ * Pure function, no side effects, no external dependencies.
+ *
+ * Example classifications:
+ *   "commit"                                                → trivial
+ *   "fix the null check in src/auth/jwt.ts line 42"         → clear
+ *   "fix the auth bug"                                      → ambiguous
+ *   "add tiered rewards" (with rewards-api related)         → cross-service
+ *   "refactor auth to OAuth2 and update all API consumers"  → multi-step
+ */
+
+// ── Types ──────────────────────────────────────────────────────────────────
+
+export type TriageLevel =
+  | 'trivial'
+  | 'clear'
+  | 'ambiguous'
+  | 'cross-service'
+  | 'multi-step';
+
+export interface TriageResult {
+  level: TriageLevel;
+  confidence: number;        // 0–1
+  reasons: string[];
+  recommended_tools: string[];
+  cross_service_hits?: string[];
+}
+
+export interface TriageConfig {
+  alwaysCheck?: string[];
+  skip?: string[];
+  crossServiceKeywords?: string[];
+  strictness?: string;       // 'relaxed' | 'standard' | 'strict'
+  relatedAliases?: string[];
+}
+
+// ── Constants ──────────────────────────────────────────────────────────────
+
+const TRIVIAL_COMMANDS = [
+  'commit', 'format', 'lint', 'run tests', 'push', 'pull',
+  'status', 'build', 'test', 'deploy', 'start', 'stop', 'restart',
+];
+
+const VAGUE_PRONOUNS = /\b(it|them|the thing|those|these)\b/i;
+
+const VAGUE_VERBS = ['fix', 'update', 'change'];
+
+const CROSS_SERVICE_TERMS = [
+  'schema', 'contract', 'interface', 'event',
+];
+
+const FILE_PATH_RE = /(?:^|[\s,:(])([.\w\-/\\]+\.\w{1,6})\b/;
+const LINE_NUMBER_RE = /\bline\s+\d+|:\d+\b/;
+
+const MULTI_STEP_SEQUENTIAL = /\b(then|after that|first\b.*\bthen|finally)\b/i;
+
+// ── Helpers ────────────────────────────────────────────────────────────────
+
+function lower(s: string): string {
+  return s.toLowerCase().trim();
+}
+
+function isTrivialCommand(prompt: string): boolean {
+  const p = lower(prompt);
+  return TRIVIAL_COMMANDS.some(
+    (cmd) => p === cmd || p.startsWith(cmd + ' '),
+  );
+}
+
+function hasFileRefs(prompt: string): boolean {
+  return FILE_PATH_RE.test(prompt);
+}
+
+function hasLineNumbers(prompt: string): boolean {
+  return LINE_NUMBER_RE.test(prompt);
+}
+
+function hasVaguePronouns(prompt: string): boolean {
+  return VAGUE_PRONOUNS.test(prompt);
+}
+
+/** Returns true when a vague verb appears without a concrete target after it. */
+function hasVagueVerbs(prompt: string): boolean {
+  const words = lower(prompt).split(/\s+/);
+  return VAGUE_VERBS.some((verb) => {
+    const idx = words.indexOf(verb);
+    if (idx === -1) return false;
+    // Look at the next few words for something concrete
+    const tail = words.slice(idx + 1, idx + 4);
+    const hasTarget = tail.some(
+      (w) => /\.\w+/.test(w) || w.length > 6 || /[A-Z]/.test(w),
+    );
+    return !hasTarget;
+  });
+}
+
+function detectCrossService(
+  prompt: string,
+  config: TriageConfig,
+): string[] {
+  const p = lower(prompt);
+  const hits: string[] = [];
+
+  for (const kw of config.crossServiceKeywords ?? []) {
+    if (p.includes(lower(kw))) hits.push(`keyword: ${kw}`);
+  }
+
+  for (const alias of config.relatedAliases ?? []) {
+    if (p.includes(lower(alias))) hits.push(`project: ${alias}`);
+  }
+
+  for (const term of CROSS_SERVICE_TERMS) {
+    if (p.includes(term)) hits.push(`term: ${term}`);
+  }
+
+  return hits;
+}
+
+function isMultiStep(prompt: string): boolean {
+  const p = lower(prompt);
+
+  // "and" connecting distinct clauses (heuristic: split and check length)
+  if (p.includes(' and ') && p.split(' and ').length > 1) {
+    const parts = p.split(' and ');
+    // Both sides should be non-trivial (> 2 words each)
+    if (parts.every((part) => part.trim().split(/\s+/).length >= 2)) {
+      return true;
+    }
+  }
+
+  // Sequential language
+  if (MULTI_STEP_SEQUENTIAL.test(prompt)) return true;
+
+  // Numbered / bulleted lists
+  if (/\n\s*[1-9][.)]\s/.test(prompt) || /\n\s*[-*]\s/.test(prompt)) {
+    return true;
+  }
+
+  // Multiple file refs in different directories
+  const files = prompt.match(/[\w\-./\\]+\.\w{1,6}/g) ?? [];
+  if (files.length > 1) {
+    const dirs = new Set(files.map((f) => f.split('/')[0]));
+    if (dirs.size > 1) return true;
+  }
+
+  return false;
+}
+
+// ── Main ───────────────────────────────────────────────────────────────────
+
+export function triagePrompt(
+  prompt: string,
+  config?: TriageConfig,
+): TriageResult {
+  const cfg: TriageConfig = config ?? {};
+  const len = prompt.trim().length;
+  const reasons: string[] = [];
+  const tools: string[] = [];
+
+  // 1. Skip keywords → trivial immediately
+  for (const kw of cfg.skip ?? []) {
+    if (lower(prompt).includes(lower(kw))) {
+      return {
+        level: 'trivial',
+        confidence: 0.95,
+        reasons: [`matches skip keyword: "${kw}"`],
+        recommended_tools: [],
+      };
+    }
+  }
+
+  // 2. Multi-step (check early — highest complexity)
+  if (isMultiStep(prompt)) {
+    reasons.push('contains multi-step indicators');
+    tools.push('clarify-intent', 'scope-work', 'sequence-tasks');
+    return { level: 'multi-step', confidence: 0.85, reasons, recommended_tools: tools };
+  }
+
+  // 3. Cross-service
+  const csHits = detectCrossService(prompt, cfg);
+  if (csHits.length > 0) {
+    reasons.push(`cross-service indicators: ${csHits.join(', ')}`);
+    tools.push('clarify-intent', 'scope-work', 'search-related-projects');
+    return {
+      level: 'cross-service',
+      confidence: 0.8,
+      reasons,
+      recommended_tools: tools,
+      cross_service_hits: csHits,
+    };
+  }
+
+  // 4. always_check keywords → at least ambiguous
+  for (const kw of cfg.alwaysCheck ?? []) {
+    if (lower(prompt).includes(lower(kw))) {
+      reasons.push(`matches always_check keyword: "${kw}"`);
+      tools.push('clarify-intent', 'scope-work');
+      return { level: 'ambiguous', confidence: 0.8, reasons, recommended_tools: tools };
+    }
+  }
+
+  // 5. Trivial: short common commands
+  if (len < 20 && isTrivialCommand(prompt)) {
+    return {
+      level: 'trivial',
+      confidence: 0.9,
+      reasons: ['short common command'],
+      recommended_tools: [],
+    };
+  }
+
+  // 6. Ambiguous signals
+  const ambiguousReasons: string[] = [];
+  if (len < 50 && !hasFileRefs(prompt)) {
+    ambiguousReasons.push('short prompt without file references');
+  }
+  if (hasVaguePronouns(prompt)) {
+    ambiguousReasons.push('contains vague pronouns');
+  }
+  if (hasVagueVerbs(prompt)) {
+    ambiguousReasons.push('contains vague verbs without specific targets');
+  }
+
+  if (ambiguousReasons.length > 0) {
+    return {
+      level: 'ambiguous',
+      confidence: 0.7,
+      reasons: ambiguousReasons,
+      recommended_tools: ['clarify-intent', 'scope-work'],
+    };
+  }
+
+  // 7. Clear — specific, well-formed prompt
+  if (hasFileRefs(prompt)) reasons.push('references specific file paths');
+  if (hasLineNumbers(prompt)) reasons.push('references specific line numbers');
+  if (len > 50) reasons.push('detailed prompt with concrete nouns');
+  if (reasons.length === 0) reasons.push('well-formed prompt with clear intent');
+
+  const clearTools: string[] = hasFileRefs(prompt) ? ['verify-files-exist'] : [];
+
+  // Strictness adjustment
+  if (cfg.strictness === 'strict' && clearTools.length === 0) {
+    clearTools.push('verify-files-exist');
+  }
+
+  return {
+    level: 'clear',
+    confidence: cfg.strictness === 'strict' ? 0.8 : 0.85,
+    reasons,
+    recommended_tools: clearTools,
+  };
+}

package/src/profiles.ts

@@ -0,0 +1,70 @@
+// =============================================================================
+// Profile system — controls which tools are registered
+// =============================================================================
+// minimal:  No vectors. Pure JSONL parsing + git state. ~5MB install.
+// standard: Local embeddings (Xenova) + LanceDB. Auto-downloads model on
+//           first use. Zero config. ~200MB after model download. DEFAULT.
+// full:     Everything in standard + OpenAI option for higher quality embeddings.
+// =============================================================================
+
+import { getConfig, type Profile } from "./lib/config.js";
+
+const MINIMAL_TOOLS = new Set([
+  "preflight_check",
+  "clarify_intent",
+  "check_session_health",
+  "session_stats",
+  "prompt_score",
+]);
+
+// Standard IS the default — includes embeddings + timeline.
+// LanceDB is embedded (no server), Xenova downloads model silently on first use.
+const STANDARD_TOOLS = new Set([
+  // Main entry point
+  "preflight_check",
+  // All 14 prompt discipline tools
+  "scope_work",
+  "clarify_intent",
+  "enrich_agent_task",
+  "sharpen_followup",
+  "token_audit",
+  "sequence_tasks",
+  "checkpoint",
+  "check_session_health",
+  "log_correction",
+  "audit_workspace",
+  "session_handoff",
+  "what_changed",
+  "verify_completion",
+  // Lightweight tools
+  "session_stats",
+  "prompt_score",
+  "generate_scorecard",
+  // Timeline tools — local embeddings, zero config
+  "onboard_project",
+  "search_history",
+  "timeline_view",
+  "scan_sessions",
+]);
+
+// Full = standard + OpenAI embedding option (needs API key)
+// Identical tool set — the difference is config, not features.
+const FULL_TOOLS = new Set([
+  ...STANDARD_TOOLS,
+]);
+
+export function getProfile(): Profile {
+  return getConfig().profile;
+}
+
+export function isToolEnabled(toolName: string): boolean {
+  const profile = getProfile();
+  switch (profile) {
+    case "minimal":
+      return MINIMAL_TOOLS.has(toolName);
+    case "standard":
+      return STANDARD_TOOLS.has(toolName);
+    case "full":
+      return FULL_TOOLS.has(toolName);
+  }
+}

package/src/templates/config.yml

@@ -0,0 +1,23 @@
+# Preflight Configuration
+# =============================================================================
+
+# Profile: minimal | standard | full
+profile: standard
+
+# Related projects for cross-service context
+related_projects:
+  # - path: /Users/jack/Developer/auth-service
+  #   alias: auth-service
+  # - path: /Users/jack/Developer/notifications-service
+  #   alias: notifications-service
+
+# Thresholds
+thresholds:
+  session_stale_minutes: 30
+  max_tool_calls_before_checkpoint: 100
+  correction_pattern_threshold: 3  # corrections before pattern triggers
+
+# Embedding provider: local | openai
+embeddings:
+  provider: local  # or openai
+  # openai_api_key: from env var OPENAI_API_KEY

package/src/templates/triage.yml

@@ -0,0 +1,27 @@
+# Preflight Triage Rules
+# =============================================================================
+
+# Custom triage classification rules
+rules:
+  # Always full-check prompts mentioning these keywords
+  always_check:
+    - rewards
+    - permissions
+    - migration
+    - schema
+  
+  # Never check these (pass-through)
+  skip:
+    - commit
+    - format
+    - lint
+  
+  # Cross-service keywords (trigger related project search)
+  cross_service_keywords:
+    - auth
+    - notification
+    - event
+    - webhook
+
+# Default strictness: relaxed | standard | strict
+strictness: standard

package/src/tools/audit-workspace.ts

@@ -0,0 +1,97 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { run } from "../lib/git.js";
+import { readIfExists, findWorkspaceDocs } from "../lib/files.js";
+
+/** Extract top-level work areas from file paths generically */
+function detectWorkAreas(files: string[]): Set<string> {
+  const areas = new Set<string>();
+  for (const f of files) {
+    if (!f || f.startsWith(".")) continue;
+
+    // Use first 1-2 path segments as the area
+    const parts = f.split("/");
+    if (parts.length >= 2) {
+      // For test-like directories, just use "tests"
+      if (/^(tests?|__tests__|spec)$/i.test(parts[0])) {
+        areas.add("tests");
+      } else if (parts.length >= 3) {
+        // e.g. app/api/foo → "app/api", src/components/Bar → "src/components"
+        areas.add(`${parts[0]}/${parts[1]}`);
+      } else {
+        areas.add(parts[0]);
+      }
+    } else {
+      // Root-level files: group by extension category
+      if (/\.(json|ya?ml|toml|lock)$/.test(f)) areas.add("config");
+      else areas.add("root");
+    }
+  }
+  return areas;
+}
+
+export function registerAuditWorkspace(server: McpServer): void {
+  server.tool(
+    "audit_workspace",
+    `Audit workspace documentation freshness vs actual project state. Compares .claude/ workspace docs against recent git commits to find stale or missing documentation. Call after completing a batch of work or at session end.`,
+    {},
+    async () => {
+      const docs = findWorkspaceDocs();
+      const recentFiles = run("git diff --name-only HEAD~10 2>/dev/null || echo ''").split("\n").filter(Boolean);
+      const sections: string[] = [];
+
+      // Doc freshness
+      const docStatus: { name: string; ageHours: number; stale: boolean; size: number }[] = [];
+      const currentTime = Date.now();
+      for (const [name, info] of Object.entries(docs)) {
+        const ageHours = Math.round((currentTime - info.mtime.getTime()) / 3600000);
+        const stale = ageHours > 4;
+        docStatus.push({ name, ageHours, stale, size: info.size });
+      }
+
+      // Use bullet list format (renders everywhere)
+      sections.push(`## Workspace Doc Freshness\n${docStatus.length > 0
+        ? docStatus.map(d =>
+          `- .claude/${d.name} — ${d.ageHours}h old ${d.stale ? "🔴 STALE" : "🟢 Fresh"}`
+        ).join("\n")
+        : "No workspace docs found."
+      }`);
+
+      // Detect work areas generically from git diffs
+      const workAreas = detectWorkAreas(recentFiles);
+
+      // Check which areas lack docs
+      const docNames = Object.keys(docs).join(" ").toLowerCase();
+      const undocumented = [...workAreas].filter(area => {
+        const areaLower = area.toLowerCase();
+        // Check if any doc name contains the area name (or key parts)
+        const keywords = areaLower.split("/").filter(Boolean);
+        return !keywords.some(kw => docNames.includes(kw));
+      });
+
+      if (undocumented.length > 0) {
+        sections.push(`## Undocumented Work Areas\nRecent commits touched these areas but no workspace docs cover them:\n${undocumented.map(a => `- ❌ **${a}**`).join("\n")}`);
+      }
+
+      // Check for gap trackers or similar tracking docs
+      const trackingDocs = Object.entries(docs).filter(([n]) => /gap|track|progress/i.test(n));
+      if (trackingDocs.length > 0) {
+        const testFilesCount = parseInt(run("find tests -name '*.spec.ts' -o -name '*.test.ts' 2>/dev/null | wc -l").trim()) || 0;
+        sections.push(`## Tracking Docs\n${trackingDocs.map(([n]) => {
+          const age = docStatus.find(d => d.name === n)?.ageHours ?? "?";
+          return `- .claude/${n} — last updated ${age}h ago`;
+        }).join("\n")}\nTest files on disk: ${testFilesCount}`);
+      }
+
+      // Summary
+      const staleCount = docStatus.filter(d => d.stale).length;
+      const recs: string[] = [];
+      if (staleCount > 0) recs.push(`⚠️ ${staleCount} docs are stale. Update them before ending this session.`);
+      else recs.push("✅ Workspace docs are fresh.");
+      if (undocumented.length > 0) recs.push(`⚠️ ${undocumented.length} work areas have no docs. Consider creating docs for: ${undocumented.join(", ")}`);
+
+      sections.push(`## Recommendation\n${recs.join("\n")}`);
+
+      return { content: [{ type: "text" as const, text: sections.join("\n\n") }] };
+    }
+  );
+}

package/src/tools/checkpoint.ts

@@ -0,0 +1,119 @@
+import { z } from "zod";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { writeFileSync, existsSync, mkdirSync } from "fs";
+import { join, dirname } from "path";
+import { run, getBranch, getStatus, getLastCommit, getStagedFiles } from "../lib/git.js";
+import { PROJECT_DIR } from "../lib/files.js";
+import { appendLog, now } from "../lib/state.js";
+
+export function registerCheckpoint(server: McpServer): void {
+  server.tool(
+    "checkpoint",
+    `Save a session checkpoint before context compaction hits. Commits current work, writes session state to workspace docs, and creates a resumption note. Call this proactively when session is getting long, or when the session-health hook warns about turn count. This is your "save game" before compaction wipes context.`,
+    {
+      summary: z.string().describe("What was accomplished so far in this session"),
+      next_steps: z.string().describe("What still needs to be done"),
+      current_blockers: z.string().optional().describe("Any issues or blockers encountered"),
+      commit_mode: z.enum(["staged", "tracked", "all"]).optional().describe("What to commit: 'staged' (only staged files), 'tracked' (modified tracked files), 'all' (git add -A). Default: 'tracked'"),
+    },
+    async ({ summary, next_steps, current_blockers, commit_mode }) => {
+      const mode = commit_mode || "tracked";
+      const branch = getBranch();
+      const dirty = getStatus();
+      const lastCommit = getLastCommit();
+      const timestamp = now();
+
+      // Write checkpoint file
+      const checkpointDir = join(PROJECT_DIR, ".claude");
+      if (!existsSync(checkpointDir)) mkdirSync(checkpointDir, { recursive: true });
+
+      const checkpointFile = join(checkpointDir, "last-checkpoint.md");
+      const checkpointContent = `# Session Checkpoint
+**Time**: ${timestamp}
+**Branch**: ${branch}
+**Last Commit**: ${lastCommit}
+
+## Accomplished
+${summary}
+
+## Next Steps
+${next_steps}
+
+${current_blockers ? `## Blockers\n${current_blockers}\n` : ""}
+## Uncommitted Work (at checkpoint time)
+\`\`\`
+${dirty || "clean"}
+\`\`\`
+`;
+      writeFileSync(checkpointFile, checkpointContent);
+
+      appendLog("checkpoint-log.jsonl", {
+        timestamp,
+        branch,
+        summary,
+        next_steps,
+        blockers: current_blockers || null,
+        dirty_files: dirty ? dirty.split("\n").filter(Boolean).length : 0,
+        commit_mode: mode,
+      });
+
+      // Commit based on mode
+      let commitResult = "no uncommitted changes";
+      if (dirty) {
+        const shortSummary = summary.split("\n")[0].slice(0, 72);
+        const commitMsg = `checkpoint: ${shortSummary}`;
+
+        let addCmd: string = "git add -u";
+        switch (mode) {
+          case "staged": {
+            const staged = getStagedFiles();
+            if (!staged) {
+              commitResult = "nothing staged — skipped commit (use 'tracked' or 'all' mode, or stage files first)";
+            }
+            addCmd = "true"; // noop, already staged
+            break;
+          }
+          case "all":
+            addCmd = "git add -A";
+            break;
+          case "tracked":
+          default:
+            addCmd = "git add -u";
+            break;
+        }
+
+        if (commitResult === "no uncommitted changes") {
+          // Stage the checkpoint file too
+          run(`git add "${checkpointFile}"`);
+          const result = run(`${addCmd} && git commit -m "${commitMsg.replace(/"/g, '\\"')}" 2>&1`);
+          if (result.includes("commit failed") || result.includes("nothing to commit")) {
+            // Rollback: unstage if commit failed
+            run("git reset HEAD 2>/dev/null");
+            commitResult = `commit failed: ${result}`;
+          } else {
+            commitResult = result;
+          }
+        }
+      }
+
+      return {
+        content: [{
+          type: "text" as const,
+          text: `## Checkpoint Saved ✅
+**File**: .claude/last-checkpoint.md
+**Branch**: ${branch}
+**Commit mode**: ${mode}
+**Commit**: ${commitResult}
+
+### What's saved:
+- Summary of work done
+- Next steps for continuation
+${current_blockers ? "- Current blockers\n" : ""}- Working tree state at checkpoint time
+
+### To resume after compaction:
+Tell the next session/continuation: "Read .claude/last-checkpoint.md for where I left off"`,
+        }],
+      };
+    }
+  );
+}