fix: replace shell syntax in run() calls across 8 tools

README.md

@@ -500,6 +500,8 @@ Manual contract definitions that supplement auto-extraction:
 
 Environment variables are **fallbacks** — `.preflight/` config takes precedence when present.
 
+> 💡 **Ready-to-use examples:** Copy [`examples/.preflight/`](examples/.preflight/) into your project root for a working starter config with detailed comments.
+
 ---
 
 ## Embedding Providers

examples/.preflight/config.yml

@@ -0,0 +1,35 @@
+# .preflight/config.yml — Drop this in your project root
+#
+# This is an example config for a typical Next.js + microservices setup.
+# Every field is optional — preflight works with sensible defaults out of the box.
+# Commit this to your repo so the whole team gets the same preflight behavior.
+
+# Profile controls how much detail preflight returns.
+#   "minimal"  — only flags ambiguous+ prompts, skips clarification detail
+#   "standard" — balanced (default)
+#   "full"     — maximum detail on every non-trivial prompt
+profile: standard
+
+# Related projects for cross-service awareness.
+# Preflight will search these for shared types, routes, and contracts
+# so it can warn you when a change might break a consumer.
+related_projects:
+  - path: /Users/you/code/auth-service
+    alias: auth
+  - path: /Users/you/code/billing-api
+    alias: billing
+  - path: /Users/you/code/shared-types
+    alias: types
+
+# Behavioral thresholds — tune these to your workflow
+thresholds:
+  session_stale_minutes: 30                # Warn if no activity for this long
+  max_tool_calls_before_checkpoint: 100    # Suggest a checkpoint after N tool calls
+  correction_pattern_threshold: 3          # Min corrections before flagging a pattern
+
+# Embedding provider for semantic search over session history.
+# "local" uses Xenova transformers (no API key needed, runs on CPU).
+# "openai" uses text-embedding-3-small (faster, needs OPENAI_API_KEY).
+embeddings:
+  provider: local
+  # openai_api_key: sk-...               # Uncomment if using openai provider

examples/.preflight/contracts/api.yml

@@ -0,0 +1,58 @@
+# .preflight/contracts/api.yml — Manual contract definitions
+#
+# Define shared types and interfaces that preflight should know about.
+# These supplement auto-extracted contracts from your codebase.
+# Manual definitions win on name conflicts with auto-extracted ones.
+#
+# Why manual contracts?
+#   - Document cross-service interfaces that live in docs, not code
+#   - Define contracts for external APIs your services consume
+#   - Pin down types that are implicit (e.g., event payloads)
+
+- name: User
+  kind: interface
+  description: Core user model shared across all services
+  fields:
+    - name: id
+      type: string
+      required: true
+    - name: email
+      type: string
+      required: true
+    - name: tier
+      type: "'free' | 'pro' | 'enterprise'"
+      required: true
+    - name: createdAt
+      type: Date
+      required: true
+
+- name: AuthToken
+  kind: interface
+  description: JWT payload structure from auth-service
+  fields:
+    - name: userId
+      type: string
+      required: true
+    - name: permissions
+      type: string[]
+      required: true
+    - name: expiresAt
+      type: number
+      required: true
+
+- name: WebhookPayload
+  kind: interface
+  description: Standard webhook envelope for inter-service events
+  fields:
+    - name: event
+      type: string
+      required: true
+    - name: timestamp
+      type: string
+      required: true
+    - name: data
+      type: Record<string, unknown>
+      required: true
+    - name: source
+      type: string
+      required: true

examples/.preflight/triage.yml

@@ -0,0 +1,45 @@
+# .preflight/triage.yml — Controls how preflight classifies your prompts
+#
+# The triage engine routes prompts into categories:
+#   TRIVIAL       → pass through (commit, format, lint)
+#   CLEAR         → well-specified, no intervention needed
+#   AMBIGUOUS     → needs clarification before proceeding
+#   MULTI-STEP    → complex task, preflight suggests a plan
+#   CROSS-SERVICE → touches multiple projects, pulls in contracts
+#
+# Customize the keywords below to match your domain.
+
+rules:
+  # Prompts containing these words are always flagged as AMBIGUOUS.
+  # Add domain-specific terms that tend to produce vague prompts.
+  always_check:
+    - rewards
+    - permissions
+    - migration
+    - schema
+    - pricing          # example: your billing domain
+    - onboarding       # example: multi-step user flows
+
+  # Prompts containing these words skip checks entirely (TRIVIAL).
+  # These are safe, mechanical tasks that don't need guardrails.
+  skip:
+    - commit
+    - format
+    - lint
+    - prettier
+    - "git push"
+
+  # Prompts containing these words trigger CROSS-SERVICE classification.
+  # Preflight will search related_projects for relevant types and routes.
+  cross_service_keywords:
+    - auth
+    - notification
+    - event
+    - webhook
+    - billing          # matches the related_project alias
+
+# How aggressively to classify prompts.
+#   "relaxed"  — more prompts pass as clear (experienced users)
+#   "standard" — balanced (default)
+#   "strict"   — more prompts flagged as ambiguous (new teams, complex codebases)
+strictness: standard

examples/README.md

@@ -0,0 +1,35 @@
+# Examples
+
+## `.preflight/` Config Directory
+
+The `.preflight/` directory contains example configuration files you can copy into your project root:
+
+```
+.preflight/
+├── config.yml              # Main config — profile, related projects, thresholds
+├── triage.yml              # Triage rules — keywords, strictness
+└── contracts/
+    └── api.yml             # Manual contract definitions for cross-service types
+```
+
+### Quick setup
+
+```bash
+# From your project root:
+cp -r /path/to/preflight/examples/.preflight .preflight
+
+# Edit paths in config.yml to match your setup:
+$EDITOR .preflight/config.yml
+```
+
+Then commit `.preflight/` to your repo — your whole team gets the same preflight behavior.
+
+### What each file does
+
+| File | Purpose | Required? |
+|------|---------|-----------|
+| `config.yml` | Profile, related projects, thresholds, embedding config | No — sensible defaults |
+| `triage.yml` | Keyword rules for prompt classification | No — sensible defaults |
+| `contracts/*.yml` | Manual type/interface definitions for cross-service awareness | No — auto-extraction works without it |
+
+All files are optional. Preflight works out of the box with zero config — these files let you tune it to your codebase.

src/lib/git.ts

@@ -1,4 +1,4 @@
-import { execFileSync } from "child_process";
+import { execFileSync, execSync } from "child_process";
 import { PROJECT_DIR } from "./files.js";
 import type { RunError } from "../types.js";
 
@@ -35,6 +35,29 @@ function gitCmd(cmdStr: string, opts?: { timeout?: number }): string {
   return run(cmdStr.split(/\s+/), opts);
 }
 
+/**
+ * Run an arbitrary shell command (with pipes, redirects, etc.).
+ * Use sparingly — only for non-git commands that genuinely need shell features.
+ * Returns stdout on success, descriptive error string on failure.
+ */
+export function shell(cmd: string, opts: { timeout?: number } = {}): string {
+  try {
+    return execSync(cmd, {
+      cwd: PROJECT_DIR,
+      encoding: "utf-8",
+      timeout: opts.timeout || 10000,
+      maxBuffer: 1024 * 1024,
+      stdio: ["pipe", "pipe", "pipe"],
+    }).trim();
+  } catch (e: any) {
+    const timedOut = e.killed === true || e.signal === "SIGTERM";
+    if (timedOut) return `[timed out after ${opts.timeout || 10000}ms]`;
+    const output = e.stdout?.trim() || e.stderr?.trim();
+    if (output) return output;
+    return `[command failed: ${cmd} (exit ${e.status ?? "?"})]`;
+  }
+}
+
 /** Get the current branch name. */
 export function getBranch(): string {
   return run(["branch", "--show-current"]);

src/tools/audit-workspace.ts

@@ -1,5 +1,5 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { run } from "../lib/git.js";
+import { run, shell } from "../lib/git.js";
 import { readIfExists, findWorkspaceDocs } from "../lib/files.js";
 
 /** Extract top-level work areas from file paths generically */
@@ -36,7 +36,7 @@ export function registerAuditWorkspace(server: McpServer): void {
     {},
     async () => {
       const docs = findWorkspaceDocs();
-      const recentFiles = run("git diff --name-only HEAD~10 2>/dev/null || echo ''").split("\n").filter(Boolean);
+      const recentFiles = run(["diff", "--name-only", "HEAD~10"]).split("\n").filter(Boolean);
       const sections: string[] = [];
 
       // Doc freshness
@@ -75,7 +75,7 @@ export function registerAuditWorkspace(server: McpServer): void {
       // 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;
+        const testFilesCount = parseInt(shell("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`;

src/tools/checkpoint.ts

@@ -84,11 +84,14 @@ ${dirty || "clean"}
 
         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`);
+          run(["add", checkpointFile]);
+          // Stage files based on scope
+          if (addCmd === "git add -A") run(["add", "-A"]);
+          else if (addCmd === "git add -u") run(["add", "-u"]);
+          const result = run(["commit", "-m", commitMsg]);
           if (result.includes("commit failed") || result.includes("nothing to commit")) {
             // Rollback: unstage if commit failed
-            run("git reset HEAD 2>/dev/null");
+            run(["reset", "HEAD"]);
             commitResult = `commit failed: ${result}`;
           } else {
             commitResult = result;

src/tools/clarify-intent.ts

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { run, getBranch, getStatus, getRecentCommits, getDiffFiles, getStagedFiles } from "../lib/git.js";
+import { run, shell, getBranch, getStatus, getRecentCommits, getDiffFiles, getStagedFiles } from "../lib/git.js";
 import { findWorkspaceDocs, PROJECT_DIR } from "../lib/files.js";
 import { searchSemantic } from "../lib/timeline-db.js";
 import { getRelatedProjects } from "../lib/config.js";
@@ -152,10 +152,10 @@ export function registerClarifyIntent(server: McpServer): void {
       let hasTestFailures = false;
 
       if (!area || area.includes("test") || area.includes("fix") || area.includes("ui") || area.includes("api")) {
-        const typeErrors = run("pnpm tsc --noEmit 2>&1 | grep -c 'error TS' || echo '0'");
+        const typeErrors = shell("pnpm tsc --noEmit 2>&1 | grep -c 'error TS' || echo '0'");
         hasTypeErrors = parseInt(typeErrors, 10) > 0;
 
-        const testFiles = run("find tests -name '*.spec.ts' -maxdepth 4 2>/dev/null | head -20");
+        const testFiles = shell("find tests -name '*.spec.ts' -maxdepth 4 2>/dev/null | head -20");
         const failingTests = getTestFailures();
         hasTestFailures = failingTests !== "all passing" && failingTests !== "no test report found";
 

src/tools/enrich-agent-task.ts

@@ -21,39 +21,52 @@ function detectPackageManager(): string {
   return "npm";
 }
 
+/** Get all git-tracked files (cached for multiple calls) */
+function getGitFiles(): string[] {
+  return run(["ls-files"]).split("\n").filter(Boolean);
+}
+
+const TEST_RE = /\.(spec|test)\.(ts|tsx|js|jsx)$/;
+
 /** Find files in a target area using git-tracked files (project-agnostic) */
 function findAreaFiles(area: string): string {
   if (!area) return getDiffFiles("HEAD~3");
 
-  const safeArea = shellEscape(area);
+  const allFiles = getGitFiles();
 
-  // If area looks like a path, search directly
+  // If area looks like a path, search by prefix
   if (area.includes("/")) {
-    return run(`git ls-files -- '${safeArea}*' 2>/dev/null | head -20`);
+    const safeArea = shellEscape(area);
+    return allFiles.filter(f => f.startsWith(safeArea)).slice(0, 20).join("\n") || getDiffFiles("HEAD~3");
   }
 
-  // Search for area keyword in git-tracked file paths
-  const files = run(`git ls-files 2>/dev/null | grep -i '${safeArea}' | head -20`);
-  if (files && !files.startsWith("[command failed")) return files;
-
-  // Fallback to recently changed files
-  return getDiffFiles("HEAD~3");
+  // Search for area keyword in file paths
+  const pattern = new RegExp(shellEscape(area), "i");
+  const matched = allFiles.filter(f => pattern.test(f)).slice(0, 20).join("\n");
+  return matched || getDiffFiles("HEAD~3");
 }
 
 /** Find related test files for an area */
 function findRelatedTests(area: string): string {
-  if (!area) return run("git ls-files 2>/dev/null | grep -E '\\.(spec|test)\\.(ts|tsx|js|jsx)$' | head -10");
+  const allFiles = getGitFiles();
+  const testFiles = allFiles.filter(f => TEST_RE.test(f));
+
+  if (!area) return testFiles.slice(0, 10).join("\n");
 
   const safeArea = shellEscape(area.split(/\s+/)[0]);
-  const tests = run(`git ls-files 2>/dev/null | grep -E '\\.(spec|test)\\.(ts|tsx|js|jsx)$' | grep -i '${safeArea}' | head -10`);
-  return tests || run("git ls-files 2>/dev/null | grep -E '\\.(spec|test)\\.(ts|tsx|js|jsx)$' | head -10");
+  const pattern = new RegExp(safeArea, "i");
+  const matched = testFiles.filter(f => pattern.test(f)).slice(0, 10).join("\n");
+  return matched || testFiles.slice(0, 10).join("\n");
 }
 
 /** Get an example pattern from the first matching file */
 function getExamplePattern(files: string): string {
   const firstFile = files.split("\n").filter(Boolean)[0];
   if (!firstFile) return "no pattern available";
-  return run(`head -30 '${shellEscape(firstFile)}' 2>/dev/null || echo 'could not read file'`);
+  try {
+    const content = readFileSync(join(PROJECT_DIR, firstFile), "utf-8");
+    return content.split("\n").slice(0, 30).join("\n");
+  } catch { return "could not read file"; }
 }
 
 // ---------------------------------------------------------------------------

src/tools/scope-work.ts

@@ -17,11 +17,6 @@ const STOP_WORDS = new Set([
   "like", "some", "each", "only", "need", "want", "please", "update", "change",
 ]);
 
-/** Shell-escape a string for use inside single quotes */
-function shellEscape(s: string): string {
-  return s.replace(/'/g, "'\\''");
-}
-
 /** Safely parse git porcelain status lines */
 function parsePortelainFiles(porcelain: string): string[] {
   if (!porcelain.trim()) return [];
@@ -93,9 +88,9 @@ export function registerScopeWork(server: McpServer): void {
       const timestamp = now();
       const currentBranch = branch ?? getBranch();
       const recentCommits = getRecentCommits(10);
-      const porcelain = run("git status --porcelain");
+      const porcelain = run(["status", "--porcelain"]);
       const dirtyFiles = parsePortelainFiles(porcelain);
-      const diffStat = dirtyFiles.length > 0 ? run("git diff --stat") : "(clean working tree)";
+      const diffStat = dirtyFiles.length > 0 ? run(["diff", "--stat"]) : "(clean working tree)";
 
       // Scan for relevant files based on task keywords
       const keywords = task.toLowerCase().split(/\s+/);
@@ -127,8 +122,10 @@ export function registerScopeWork(server: McpServer): void {
         .filter((k) => k.length > 2)
         .slice(0, 5);
       if (grepTerms.length > 0) {
-        const pattern = shellEscape(grepTerms.join("|"));
-        matchedFiles = run(`git ls-files | head -500 | grep -iE '${pattern}' | head -30`);
+        const allFiles = run(["ls-files"]);
+        const pattern = new RegExp(grepTerms.join("|"), "i");
+        matchedFiles = allFiles.split("\n").filter(Boolean).slice(0, 500)
+          .filter(f => pattern.test(f)).slice(0, 30).join("\n");
       }
 
       // Check which relevant dirs actually exist (with path traversal protection)

src/tools/sequence-tasks.ts

@@ -90,7 +90,8 @@ export function registerSequenceTasks(server: McpServer): void {
       // For locality: infer directories from path-like tokens in task text
       if (strategy === "locality") {
         // Use git ls-files with a depth limit instead of find for performance
-        const gitFiles = run("git ls-files 2>/dev/null | head -1000");
+        const gitFilesRaw = run(["ls-files"]);
+        const gitFiles = gitFilesRaw.split("\n").slice(0, 1000).join("\n");
         const knownDirs = new Set<string>();
         for (const f of gitFiles.split("\n").filter(Boolean)) {
           const parts = f.split("/");