ai-spec-dev 0.31.0 → 0.35.0

package/core/dsl-feedback.ts

@@ -0,0 +1,285 @@
+/**
+ * dsl-feedback.ts — Two pipeline feedback loops for ai-spec create
+ *
+ * Loop 1 (DSL → Spec):  after DSL extraction, detect sparse/incomplete DSL
+ *   and offer a targeted spec refinement pass before codegen starts.
+ *
+ * Loop 2 (Review → DSL): after 3-pass review, detect design-level findings
+ *   (as opposed to implementation issues) and offer to amend the spec + DSL
+ *   so the next update/regen starts from a corrected contract.
+ *
+ * Design constraints:
+ *  - Both loops are SKIPPED in --auto / --fast / --skip-dsl modes.
+ *  - Zero extra AI calls until the user explicitly opts in.
+ *  - Non-blocking: user can always skip.
+ */
+
+import chalk from "chalk";
+import { SpecDSL } from "./dsl-types";
+
+// ─── Loop 1 Types ─────────────────────────────────────────────────────────────
+
+export interface DslGap {
+  /** Short machine key for RunLog serialisation */
+  code: "sparse_model" | "missing_errors" | "generic_endpoint_desc" | "no_models_no_endpoints";
+  /** Human-readable message shown to the user */
+  message: string;
+  /** Concrete suggestion injected into the refinement prompt */
+  hint: string;
+}
+
+// ─── Loop 1: DSL Richness Assessment ─────────────────────────────────────────
+
+/**
+ * Inspect a freshly-extracted DSL for common completeness gaps.
+ * Returns a list of DslGap objects (empty = DSL looks adequate).
+ *
+ * All checks are pure heuristics — zero AI calls.
+ */
+export function assessDslRichness(dsl: SpecDSL): DslGap[] {
+  const gaps: DslGap[] = [];
+
+  // ── No endpoints AND no models ────────────────────────────────────────────
+  if (dsl.endpoints.length === 0 && dsl.models.length === 0) {
+    gaps.push({
+      code: "no_models_no_endpoints",
+      message: "DSL has no endpoints and no models — spec may be too abstract for structured extraction",
+      hint: "Please add explicit API endpoint definitions (method, path, request/response) and any data models that this feature requires.",
+    });
+    return gaps; // no point checking the rest
+  }
+
+  // ── Endpoints with very generic / short descriptions ─────────────────────
+  const GENERIC_DESC_KEYWORDS = ["handles", "processes", "manages", "操作", "处理", "管理"];
+  const GENERIC_DESC_MIN_LEN  = 15;
+
+  for (const ep of dsl.endpoints) {
+    const desc = (ep.description ?? "").trim();
+    const isGeneric =
+      desc.length < GENERIC_DESC_MIN_LEN ||
+      GENERIC_DESC_KEYWORDS.some((kw) => desc.toLowerCase().startsWith(kw));
+
+    if (isGeneric) {
+      gaps.push({
+        code: "generic_endpoint_desc",
+        message: `Endpoint ${ep.method} ${ep.path} has a vague description: "${desc}"`,
+        hint: `Clarify what ${ep.method} ${ep.path} does: what inputs are required, what the success response contains, and what business rule it enforces.`,
+      });
+    }
+  }
+
+  // ── Endpoints with no error definitions (but spec text likely mentions them) ──
+  const endpointsWithoutErrors = dsl.endpoints.filter(
+    (ep) => !ep.errors || ep.errors.length === 0
+  );
+  if (endpointsWithoutErrors.length > 0 && dsl.endpoints.length >= 2) {
+    gaps.push({
+      code: "missing_errors",
+      message: `${endpointsWithoutErrors.length}/${dsl.endpoints.length} endpoints have no error definitions`,
+      hint: `For each endpoint, specify at least the main error cases: e.g. 400 validation errors, 401 auth failures, 404 not found, 409 conflict. Include an error code (e.g. INVALID_INPUT) and description for each.`,
+    });
+  }
+
+  // ── Models with fewer than 2 fields ──────────────────────────────────────
+  for (const model of dsl.models) {
+    if (!model.fields || model.fields.length < 2) {
+      gaps.push({
+        code: "sparse_model",
+        message: `Model "${model.name}" has only ${model.fields?.length ?? 0} field(s) — likely incomplete`,
+        hint: `List all fields for "${model.name}" with their types and whether they are required. Include at minimum an id, created_at, and the core domain fields this model needs.`,
+      });
+    }
+  }
+
+  return gaps;
+}
+
+// ─── Loop 1: Targeted Spec Refinement Prompt ─────────────────────────────────
+
+/**
+ * Build a targeted AI refinement prompt that focuses the LLM on filling
+ * only the specific gaps detected by `assessDslRichness`.
+ */
+export function buildDslGapRefinementPrompt(spec: string, gaps: DslGap[]): string {
+  const gapList = gaps
+    .map((g, i) => `${i + 1}. [${g.code}] ${g.message}\n   → ${g.hint}`)
+    .join("\n\n");
+
+  return `The following feature spec has been structurally analysed. The DSL extracted from it was found to be incomplete in these specific areas:
+
+${gapList}
+
+Your task: revise the spec below to address ONLY the gaps listed above.
+- Do NOT change the overall feature scope or business logic.
+- Do NOT rewrite sections that are already complete.
+- Add missing error cases, clarify vague endpoint descriptions, complete sparse model field lists.
+- Output ONLY the complete revised Markdown spec. No preamble, no explanation.
+
+=== Current Spec ===
+${spec}`;
+}
+
+// ─── Loop 2 Types ─────────────────────────────────────────────────────────────
+
+export interface StructuralFinding {
+  /** Short label for display + RunLog */
+  category: "auth_design" | "model_design" | "api_contract" | "layer_violation" | "other_design";
+  description: string;
+}
+
+// ─── Loop 2: Review Structural Issue Classifier ───────────────────────────────
+
+/**
+ * Parse a 3-pass review text to extract Pass 1 (architecture) findings
+ * that indicate design-level issues in the Spec/DSL — as opposed to
+ * implementation-level issues that belong in §9 knowledge.
+ *
+ * Primary path: parse the structured JSON block emitted by the updated
+ * reviewArchitectureSystemPrompt (## 🔍 结构性发现 JSON section).
+ * Fallback: legacy regex approach for review texts generated before the
+ * structured output format was introduced.
+ *
+ * Returns an empty array if no structural issues are found or if the
+ * review score for Pass 1 is high (≥ 8), indicating overall approval.
+ */
+export function extractStructuralFindings(reviewText: string): StructuralFinding[] {
+  // Split by the separator used between passes ("─────...")
+  const parts = reviewText.split(/─{20,}/);
+  // Pass 1 is always the first section
+  const pass1Text = parts[0] ?? "";
+
+  // If Pass 1 scored well, treat as no structural issues
+  const pass1Score = extractPassScore(pass1Text);
+  if (pass1Score !== null && pass1Score >= 8) return [];
+
+  // ── Primary path: parse structured JSON block ─────────────────────────────
+  // Look for the JSON block within the "🔍 结构性发现 JSON" section of Pass 1.
+  // The block is delimited by ```json ... ``` and always contains a
+  // { structuralFindings: [...] } object.
+  const jsonBlockMatch = pass1Text.match(/```json\s*(\{[\s\S]*?\})\s*```/);
+  if (jsonBlockMatch) {
+    try {
+      const parsed = JSON.parse(jsonBlockMatch[1]);
+      if (Array.isArray(parsed.structuralFindings)) {
+        return parsed.structuralFindings.filter(
+          (f: unknown): f is StructuralFinding =>
+            typeof f === "object" &&
+            f !== null &&
+            typeof (f as StructuralFinding).category === "string" &&
+            typeof (f as StructuralFinding).description === "string"
+        );
+      }
+    } catch {
+      // JSON parse failed — fall through to regex fallback
+    }
+  }
+
+  // ── Fallback: legacy regex approach ──────────────────────────────────────
+  // Used when review text was generated before the structured JSON format
+  // was added to reviewArchitectureSystemPrompt.
+  const findings: StructuralFinding[] = [];
+
+  // Auth / 认证 design issues
+  if (
+    /缺少认证|missing auth|auth.*false|未加认证|鉴权.*缺|endpoint.*public.*should/i.test(pass1Text)
+  ) {
+    const match = pass1Text.match(/[^。\n]*(?:缺少认证|missing auth|auth.*false|未加认证|鉴权.*缺|endpoint.*public.*should)[^。\n]*/i);
+    findings.push({
+      category: "auth_design",
+      description: match ? match[0].trim() : "One or more endpoints may have incorrect authentication requirements",
+    });
+  }
+
+  // API contract / 接口设计 issues
+  if (
+    /接口设计.*问题|接口.*不合理|API design|response.*missing|request.*missing|接口.*缺少/i.test(pass1Text)
+  ) {
+    const match = pass1Text.match(/[^。\n]*(?:接口设计.*问题|接口.*不合理|API design|response.*missing|接口.*缺少)[^。\n]*/i);
+    findings.push({
+      category: "api_contract",
+      description: match ? match[0].trim() : "API contract design may have issues",
+    });
+  }
+
+  // Model / 数据模型 design issues
+  if (
+    /模型.*缺少字段|model.*missing field|数据结构.*问题|schema.*incomplete|字段.*missing/i.test(pass1Text)
+  ) {
+    const match = pass1Text.match(/[^。\n]*(?:模型.*缺少字段|model.*missing field|数据结构.*问题|schema.*incomplete)[^。\n]*/i);
+    findings.push({
+      category: "model_design",
+      description: match ? match[0].trim() : "Data model design may be incomplete",
+    });
+  }
+
+  // Layer separation / 层级分离 violations
+  if (
+    /层级.*违反|layer.*violation|business logic.*controller|controller.*service.*混|分层.*问题/i.test(pass1Text)
+  ) {
+    const match = pass1Text.match(/[^。\n]*(?:层级.*违反|layer.*violation|business logic.*controller|分层.*问题)[^。\n]*/i);
+    findings.push({
+      category: "layer_violation",
+      description: match ? match[0].trim() : "Layer separation may be violated in the generated code",
+    });
+  }
+
+  return findings;
+}
+
+/** Extract the numeric score from a single pass section. */
+function extractPassScore(text: string): number | null {
+  const m = text.match(/Score:\s*(\d+(?:\.\d+)?)\s*\/\s*10/i);
+  return m ? parseFloat(m[1]) : null;
+}
+
+// ─── Loop 2: Spec Amendment Prompt ────────────────────────────────────────────
+
+/**
+ * Build a prompt asking the AI to produce a minimal spec amendment
+ * that addresses the structural findings from the review.
+ *
+ * The amendment is a targeted addition/correction — NOT a full rewrite.
+ */
+export function buildStructuralAmendmentPrompt(
+  spec: string,
+  findings: StructuralFinding[]
+): string {
+  const findingList = findings
+    .map((f, i) => `${i + 1}. [${f.category}] ${f.description}`)
+    .join("\n");
+
+  return `A code review of the feature built from this spec found the following DESIGN-LEVEL issues.
+These are problems in the spec/contract itself, not in the implementation.
+
+=== Structural Findings ===
+${findingList}
+
+Your task:
+- Revise the spec below to correct the design issues listed above.
+- Do NOT change the feature scope, business logic, or sections unrelated to these findings.
+- Be minimal: only change what is necessary to fix the design issues.
+- Output ONLY the complete revised Markdown spec. No preamble, no explanation.
+
+=== Current Spec ===
+${spec}`;
+}
+
+// ─── Display Helpers ──────────────────────────────────────────────────────────
+
+export function printDslGaps(gaps: DslGap[]): void {
+  console.log(chalk.yellow("\n  ⚠ DSL Completeness Check — gaps detected:"));
+  for (const gap of gaps) {
+    console.log(chalk.yellow(`    · ${gap.message}`));
+  }
+  console.log(chalk.gray("    → A targeted spec refinement can fill these gaps before codegen."));
+}
+
+export function printStructuralFindings(findings: StructuralFinding[]): void {
+  console.log(chalk.yellow("\n  ⚠ Review — structural (design-level) issues found:"));
+  for (const f of findings) {
+    const label = chalk.gray(`[${f.category}]`);
+    console.log(`    ${label} ${f.description}`);
+  }
+  console.log(chalk.gray("    → These are contract issues in the Spec/DSL, not just implementation problems."));
+  console.log(chalk.gray("    → Fixing the spec now means the next run generates correct code from the start."));
+}

package/core/error-feedback.ts

@@ -22,6 +22,22 @@ interface FixResult {
   explanation: string;
 }
 
+// ─── Budgets ────────────────────────────────────────────────────────────────────
+
+/**
+ * Maximum characters captured from a single command's output before parsing.
+ * ~10K tokens — enough for any realistic error listing; prevents a pathological
+ * build output (e.g. 10MB of warnings) from ballooning the AI context.
+ */
+const MAX_COMMAND_OUTPUT_CHARS = 50_000;
+
+/**
+ * Maximum characters of an existing file sent to the AI for auto-fix.
+ * ~12K tokens — covers large files; content beyond this is truncated with a
+ * notice so the AI knows it may be seeing an incomplete file.
+ */
+const MAX_FIX_FILE_CHARS = 60_000;
+
 // ─── Error Detection ────────────────────────────────────────────────────────────
 
 function runCommand(cmd: string, cwd: string): { success: boolean; output: string } {
@@ -30,7 +46,13 @@ function runCommand(cmd: string, cwd: string): { success: boolean; output: strin
     return { success: true, output };
   } catch (err) {
     const e = err as { stdout?: string; stderr?: string; message?: string };
-    return { success: false, output: e.stdout || e.stderr || e.message || "" };
+    const raw = e.stdout || e.stderr || e.message || "";
+    // Apply output budget: cap before parsing to prevent huge outputs from
+    // filling up the AI context on subsequent fix cycles.
+    const output = raw.length > MAX_COMMAND_OUTPUT_CHARS
+      ? raw.slice(0, MAX_COMMAND_OUTPUT_CHARS) + `\n... [output truncated at ${MAX_COMMAND_OUTPUT_CHARS} chars]`
+      : raw;
+    return { success: false, output };
   }
 }
 
@@ -328,6 +350,13 @@ async function attemptFix(
     const dslSection = dsl ? `\n${buildDslContextSection(dsl)}\n` : "";
     const errorSummary = fileErrors.map((e) => `[${e.source}] ${e.message}`).join("\n");
 
+    // Apply file content budget — very large files are truncated with a notice.
+    // The AI still has enough context to fix the errors (which reference specific lines).
+    const fileContent = existingContent.length > MAX_FIX_FILE_CHARS
+      ? existingContent.slice(0, MAX_FIX_FILE_CHARS) +
+        `\n\n// ... [file truncated at ${MAX_FIX_FILE_CHARS} chars — fix only the error lines above]`
+      : existingContent;
+
     const prompt = `Fix the following errors in the file.
 
 File: ${file}
@@ -336,7 +365,7 @@ ${dslSection}
 ${errorSummary}
 
 === Current File Content ===
-${existingContent}
+${fileContent}
 
 Output ONLY the complete fixed file content. No markdown fences, no explanations.`;
 
@@ -394,6 +423,8 @@ export async function runErrorFeedback(
 
   if (buildCmd) console.log(chalk.gray(`  Type-check: ${buildCmd}`));
 
+  let prevErrorCount = Infinity; // circuit-breaker: tracks error count from previous cycle
+
   for (let cycle = 1; cycle <= maxCycles; cycle++) {
     const allErrors: ErrorEntry[] = [];
 
@@ -462,6 +493,19 @@ export async function runErrorFeedback(
       return true;
     }
 
+    // Circuit breaker: if the fix cycle made no progress (error count did not
+    // decrease), stop immediately rather than spending another AI cycle.
+    if (allErrors.length >= prevErrorCount) {
+      console.log(
+        chalk.yellow(
+          `\n  ⚠ Auto-fix made no progress (${allErrors.length} error(s) before and after). Stopping early.`
+        )
+      );
+      console.log(chalk.gray("    Manual intervention needed."));
+      return false;
+    }
+    prevErrorCount = allErrors.length;
+
     if (cycle < maxCycles) {
       console.log(chalk.cyan(`\n  Attempting auto-fix (${allErrors.length} error(s))...`));
       await attemptFix(provider, allErrors, workingDir, dsl);

package/core/project-index.ts

@@ -0,0 +1,301 @@
+/**
+ * project-index.ts — Persistent project discovery & index.
+ *
+ * Scans a root directory for sub-projects (any dir with a recognisable
+ * project manifest), and maintains an incremental JSON index file at
+ * .ai-spec-index.json in the scan root.
+ *
+ * Incremental rules:
+ *  - New project found   → added with firstSeen = now
+ *  - Existing project    → techStack / type / role / hasConstitution refreshed, lastSeen = now
+ *  - Previously indexed but directory gone → marked missing:true, NOT deleted
+ *
+ * The index is intentionally lightweight — no AI calls, pure filesystem scan.
+ */
+
+import * as fs from "fs-extra";
+import * as path from "path";
+import { detectRepoType, RepoType, RepoRole, WORKSPACE_CONFIG_FILE } from "./workspace-loader";
+import { CONSTITUTION_FILE } from "./constitution-generator";
+
+export const INDEX_FILE = ".ai-spec-index.json";
+
+// ─── Key dependency lists for tech-stack extraction ──────────────────────────
+
+const KEY_DEPS: string[] = [
+  // Frameworks
+  "express", "fastify", "koa", "@nestjs/core", "hapi",
+  "next", "react", "vue", "nuxt", "svelte",
+  "react-native", "expo",
+  // DB / ORM
+  "prisma", "@prisma/client", "mongoose", "typeorm", "sequelize", "drizzle-orm",
+  // Auth
+  "jsonwebtoken", "passport", "next-auth", "@clerk/nextjs",
+  // Build / Lang
+  "typescript", "vite", "webpack", "esbuild", "turbo",
+  // Testing
+  "jest", "vitest", "mocha", "cypress", "playwright",
+  // Infra
+  "redis", "bull", "socket.io", "graphql", "@trpc/server",
+];
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+export interface ProjectEntry {
+  /** Directory name */
+  name: string;
+  /** Path relative to scanRoot */
+  path: string;
+  type: RepoType;
+  role: RepoRole;
+  /** Key dependencies detected (subset of package.json deps or language markers) */
+  techStack: string[];
+  /** Whether .ai-spec-constitution.md exists */
+  hasConstitution: boolean;
+  /** Whether .ai-spec-workspace.json exists (this repo is a workspace root) */
+  hasWorkspace: boolean;
+  /** ISO timestamp of first discovery */
+  firstSeen: string;
+  /** ISO timestamp of last successful scan */
+  lastSeen: string;
+  /** true when the directory no longer exists on disk */
+  missing?: boolean;
+}
+
+export interface ProjectIndex {
+  /** Absolute path of the directory that was scanned */
+  scanRoot: string;
+  /** ISO timestamp of last scan */
+  lastScanned: string;
+  projects: ProjectEntry[];
+}
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+/** Directories to always skip during scan */
+const SKIP_DIRS = new Set([
+  "node_modules", ".git", ".svn", "dist", "build", "out", ".next",
+  ".nuxt", "coverage", ".turbo", ".cache", "__pycache__", "vendor",
+  ".ai-spec-vcr", ".ai-spec-logs", "specs",
+]);
+
+/** Manifest files that identify a directory as a project root */
+const MANIFEST_FILES = [
+  "package.json",
+  "go.mod",
+  "Cargo.toml",
+  "pom.xml",
+  "build.gradle",
+  "build.gradle.kts",
+  "requirements.txt",
+  "pyproject.toml",
+  "setup.py",
+  "composer.json",
+];
+
+async function isProjectRoot(absPath: string): Promise<boolean> {
+  for (const manifest of MANIFEST_FILES) {
+    if (await fs.pathExists(path.join(absPath, manifest))) return true;
+  }
+  return false;
+}
+
+async function extractTechStack(absPath: string, type: RepoType): Promise<string[]> {
+  const stack: string[] = [];
+
+  // Language marker for non-Node projects
+  if (type === "go")     stack.push("go");
+  if (type === "rust")   stack.push("rust");
+  if (type === "java")   stack.push("java");
+  if (type === "python") stack.push("python");
+  if (type === "php")    stack.push("php");
+
+  const pkgPath = path.join(absPath, "package.json");
+  if (!(await fs.pathExists(pkgPath))) return stack;
+
+  let pkg: Record<string, unknown> = {};
+  try { pkg = await fs.readJson(pkgPath); } catch { return stack; }
+
+  const allDeps = {
+    ...((pkg.dependencies as Record<string, string>) ?? {}),
+    ...((pkg.devDependencies as Record<string, string>) ?? {}),
+  };
+  const depKeys = new Set(Object.keys(allDeps));
+
+  for (const dep of KEY_DEPS) {
+    if (depKeys.has(dep)) stack.push(dep);
+  }
+
+  return stack;
+}
+
+// ─── Scan ─────────────────────────────────────────────────────────────────────
+
+/**
+ * Discover all project roots under `rootDir` up to `maxDepth` levels deep.
+ * Returns paths relative to rootDir.
+ */
+async function discoverProjects(
+  rootDir: string,
+  maxDepth: number
+): Promise<string[]> {
+  const found: string[] = [];
+
+  async function walk(absDir: string, depth: number): Promise<void> {
+    if (depth > maxDepth) return;
+
+    let entries: fs.Dirent[];
+    try {
+      entries = await fs.readdir(absDir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      if (SKIP_DIRS.has(entry.name) || entry.name.startsWith(".")) continue;
+
+      const childAbs = path.join(absDir, entry.name);
+
+      // Skip git worktrees — they have a .git *file* (not directory)
+      const gitPath = path.join(childAbs, ".git");
+      if (await fs.pathExists(gitPath)) {
+        const gitStat = await fs.stat(gitPath);
+        if (gitStat.isFile()) continue; // git worktree — skip
+      }
+
+      if (await isProjectRoot(childAbs)) {
+        found.push(path.relative(rootDir, childAbs));
+        // Don't recurse into a project root — avoids picking up nested node_modules etc.
+      } else {
+        await walk(childAbs, depth + 1);
+      }
+    }
+  }
+
+  await walk(rootDir, 0);
+  return found;
+}
+
+// ─── Index load / save ────────────────────────────────────────────────────────
+
+export async function loadIndex(scanRoot: string): Promise<ProjectIndex | null> {
+  const filePath = path.join(scanRoot, INDEX_FILE);
+  try {
+    return await fs.readJson(filePath);
+  } catch {
+    return null;
+  }
+}
+
+export async function saveIndex(scanRoot: string, index: ProjectIndex): Promise<string> {
+  const filePath = path.join(scanRoot, INDEX_FILE);
+  await fs.writeJson(filePath, index, { spaces: 2 });
+  return filePath;
+}
+
+// ─── Incremental merge ────────────────────────────────────────────────────────
+
+export interface ScanResult {
+  index: ProjectIndex;
+  added: ProjectEntry[];
+  updated: ProjectEntry[];
+  unchanged: ProjectEntry[];
+  nowMissing: ProjectEntry[];
+}
+
+/**
+ * Run an incremental scan of `scanRoot`, merge with the existing index, and
+ * return the updated index along with a change summary.
+ */
+export async function runScan(
+  scanRoot: string,
+  maxDepth = 2
+): Promise<ScanResult> {
+  const now = new Date().toISOString();
+  const existing = await loadIndex(scanRoot);
+  const existingMap = new Map<string, ProjectEntry>(
+    (existing?.projects ?? []).map((p) => [p.path, p])
+  );
+
+  const discoveredPaths = await discoverProjects(scanRoot, maxDepth);
+
+  const added: ProjectEntry[] = [];
+  const updated: ProjectEntry[] = [];
+  const unchanged: ProjectEntry[] = [];
+  const seenPaths = new Set<string>();
+
+  for (const relPath of discoveredPaths) {
+    const absPath = path.join(scanRoot, relPath);
+    seenPaths.add(relPath);
+
+    const { type, role } = await detectRepoType(absPath);
+    const techStack = await extractTechStack(absPath, type);
+    const hasConstitution = await fs.pathExists(path.join(absPath, CONSTITUTION_FILE));
+    const hasWorkspace = await fs.pathExists(path.join(absPath, WORKSPACE_CONFIG_FILE));
+    const name = path.basename(relPath);
+
+    const prev = existingMap.get(relPath);
+    if (!prev) {
+      const entry: ProjectEntry = {
+        name,
+        path: relPath,
+        type,
+        role,
+        techStack,
+        hasConstitution,
+        hasWorkspace,
+        firstSeen: now,
+        lastSeen: now,
+      };
+      added.push(entry);
+      existingMap.set(relPath, entry);
+    } else {
+      // Check if anything changed
+      const changed =
+        prev.type !== type ||
+        prev.role !== role ||
+        prev.hasConstitution !== hasConstitution ||
+        prev.hasWorkspace !== hasWorkspace ||
+        JSON.stringify(prev.techStack.sort()) !== JSON.stringify(techStack.sort());
+
+      const entry: ProjectEntry = {
+        ...prev,
+        type,
+        role,
+        techStack,
+        hasConstitution,
+        hasWorkspace,
+        lastSeen: now,
+        missing: undefined, // clear missing flag if it came back
+      };
+      existingMap.set(relPath, entry);
+
+      if (changed) {
+        updated.push(entry);
+      } else {
+        unchanged.push(entry);
+      }
+    }
+  }
+
+  // Mark previously known projects as missing if their directory is gone
+  const nowMissing: ProjectEntry[] = [];
+  for (const [relPath, entry] of existingMap) {
+    if (!seenPaths.has(relPath) && !entry.missing) {
+      const gone: ProjectEntry = { ...entry, missing: true };
+      existingMap.set(relPath, gone);
+      nowMissing.push(gone);
+    }
+  }
+
+  const projects = [...existingMap.values()].sort((a, b) => a.path.localeCompare(b.path));
+
+  const index: ProjectIndex = {
+    scanRoot,
+    lastScanned: now,
+    projects,
+  };
+
+  return { index, added, updated, unchanged, nowMissing };
+}