@arcbridge/core 0.1.3 → 0.1.5

package/dist/index.js

@@ -130,7 +130,8 @@ var TaskStatusSchema = z4.enum([
   "todo",
   "in-progress",
   "done",
-  "blocked"
+  "blocked",
+  "cancelled"
 ]);
 var PhaseSchema = z4.object({
   id: z4.string().min(1),
@@ -300,7 +301,7 @@ function transaction(db, fn) {
 }
 
 // src/db/schema.ts
-var CURRENT_SCHEMA_VERSION = 2;
+var CURRENT_SCHEMA_VERSION = 3;
 var SCHEMA_SQL = `
 -- Metadata
 CREATE TABLE IF NOT EXISTS arcbridge_meta (
@@ -447,7 +448,7 @@ CREATE TABLE IF NOT EXISTS tasks (
   phase_id TEXT NOT NULL REFERENCES phases(id),
   title TEXT NOT NULL,
   description TEXT,
-  status TEXT NOT NULL DEFAULT 'todo' CHECK(status IN ('todo','in-progress','done','blocked')),
+  status TEXT NOT NULL DEFAULT 'todo' CHECK(status IN ('todo','in-progress','done','blocked','cancelled')),
   building_block TEXT REFERENCES building_blocks(id),
   quality_scenarios TEXT NOT NULL DEFAULT '[]',
   acceptance_criteria TEXT NOT NULL DEFAULT '[]',
@@ -545,6 +546,29 @@ var migrations = [
         CREATE INDEX IF NOT EXISTS idx_activity_phase ON agent_activity(phase_id);
       `);
     }
+  },
+  {
+    version: 3,
+    up: (db) => {
+      db.exec(`
+        CREATE TABLE tasks_new (
+          id TEXT PRIMARY KEY,
+          phase_id TEXT NOT NULL REFERENCES phases(id),
+          title TEXT NOT NULL,
+          description TEXT,
+          status TEXT NOT NULL DEFAULT 'todo' CHECK(status IN ('todo','in-progress','done','blocked','cancelled')),
+          building_block TEXT REFERENCES building_blocks(id),
+          quality_scenarios TEXT NOT NULL DEFAULT '[]',
+          acceptance_criteria TEXT NOT NULL DEFAULT '[]',
+          created_at TEXT NOT NULL,
+          completed_at TEXT
+        );
+        INSERT INTO tasks_new (id, phase_id, title, description, status, building_block, quality_scenarios, acceptance_criteria, created_at, completed_at)
+          SELECT id, phase_id, title, description, status, building_block, quality_scenarios, acceptance_criteria, created_at, completed_at FROM tasks;
+        DROP TABLE tasks;
+        ALTER TABLE tasks_new RENAME TO tasks;
+      `);
+    }
   }
 ];
 function migrate(db) {
@@ -738,7 +762,7 @@ function generateConfig(targetDir, input) {
 
 // src/generators/arc42-generator.ts
 import { mkdirSync as mkdirSync2, writeFileSync as writeFileSync2 } from "fs";
-import { join as join3 } from "path";
+import { join as join4 } from "path";
 import matter from "gray-matter";
 import { stringify as stringify2 } from "yaml";
 
@@ -826,6 +850,10 @@ ${techStack(input.template)}
   };
 }
 
+// src/templates/arc42/05-building-blocks.ts
+import { existsSync as existsSync2, readdirSync } from "fs";
+import { join as join3 } from "path";
+
 // src/templates/arc42/detect-layout.ts
 import { existsSync } from "fs";
 import { join as join2 } from "path";
@@ -959,13 +987,31 @@ function buildingBlocksTemplate(input) {
     }
     return blocks;
   }
-  function buildDotnetBlocks(_inp) {
+  function buildDotnetBlocks(inp) {
+    const root = inp.projectRoot ?? ".";
+    let prefix = "";
+    try {
+      const primaryService = inp.dotnetServices?.find((s) => !s.path.includes("Test"));
+      if (primaryService && primaryService.path !== ".") {
+        prefix = primaryService.path.endsWith("/") ? primaryService.path : `${primaryService.path}/`;
+      } else {
+        const srcDir = join3(root, "src");
+        if (existsSync2(srcDir)) {
+          const entries = readdirSync(srcDir).sort();
+          const projDir = entries.find(
+            (e) => existsSync2(join3(srcDir, e, `${e}.csproj`)) || existsSync2(join3(srcDir, e, "Program.cs"))
+          );
+          if (projDir) prefix = `src/${projDir}/`;
+        }
+      }
+    } catch {
+    }
     const blocks = [
       {
         id: "api-host",
         name: "API Host",
         level: 1,
-        code_paths: ["Program.cs", "Extensions/"],
+        code_paths: [`${prefix}Program.cs`, `${prefix}Extensions/`],
         interfaces: [],
         quality_scenarios: [],
         adrs: [],
@@ -976,7 +1022,7 @@ function buildingBlocksTemplate(input) {
         id: "controllers",
         name: "Controllers / Endpoints",
         level: 1,
-        code_paths: ["Controllers/", "Endpoints/"],
+        code_paths: [`${prefix}Controllers/`, `${prefix}Endpoints/`],
         interfaces: [],
         quality_scenarios: ["SEC-03"],
         adrs: [],
@@ -987,7 +1033,7 @@ function buildingBlocksTemplate(input) {
         id: "domain",
         name: "Domain",
         level: 1,
-        code_paths: ["Domain/", "Models/"],
+        code_paths: [`${prefix}Domain/`, `${prefix}Models/`],
         interfaces: [],
         quality_scenarios: [],
         adrs: [],
@@ -998,7 +1044,7 @@ function buildingBlocksTemplate(input) {
         id: "services",
         name: "Application Services",
         level: 1,
-        code_paths: ["Services/"],
+        code_paths: [`${prefix}Services/`],
         interfaces: ["controllers"],
         quality_scenarios: [],
         adrs: [],
@@ -1009,7 +1055,7 @@ function buildingBlocksTemplate(input) {
         id: "middleware",
         name: "Middleware",
         level: 1,
-        code_paths: ["Middleware/"],
+        code_paths: [`${prefix}Middleware/`],
         interfaces: [],
         quality_scenarios: ["REL-01"],
         adrs: [],
@@ -1021,7 +1067,7 @@ function buildingBlocksTemplate(input) {
       id: "auth-module",
       name: "Authentication & Authorization",
       level: 1,
-      code_paths: ["Auth/"],
+      code_paths: [`${prefix}Auth/`],
       interfaces: [],
       quality_scenarios: ["SEC-01", "SEC-02"],
       adrs: [],
@@ -1032,7 +1078,7 @@ function buildingBlocksTemplate(input) {
       id: "data-access",
       name: "Data Access",
       level: 1,
-      code_paths: ["Data/", "Repositories/", "Migrations/"],
+      code_paths: [`${prefix}Data/`, `${prefix}Repositories/`, `${prefix}Migrations/`],
       interfaces: ["domain"],
       quality_scenarios: [],
       adrs: [],
@@ -1140,10 +1186,16 @@ ${input.template === "dotnet-webapi" ? `| Platform | Description | Notes |
 // src/templates/arc42/09-decisions.ts
 function firstAdrTemplate(input) {
   const now = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
-  if (input.template === "dotnet-webapi") {
-    return dotnetAdr(input, now);
+  switch (input.template) {
+    case "dotnet-webapi":
+      return dotnetAdr(input, now);
+    case "react-vite":
+      return reactViteAdr(input, now);
+    case "api-service":
+      return apiServiceAdr(input, now);
+    default:
+      return nextjsAdr(input, now);
   }
-  return nextjsAdr(input, now);
 }
 function nextjsAdr(input, date) {
   const { appPrefix } = detectProjectLayout(input.projectRoot, input.template);
@@ -1178,6 +1230,73 @@ Use Next.js with the App Router (introduced in Next.js 13+) as the application f
 `
   };
 }
+function reactViteAdr(input, date) {
+  const { srcPrefix } = detectProjectLayout(input.projectRoot, input.template);
+  return {
+    filename: "001-react-vite.md",
+    frontmatter: {
+      id: "001-react-vite",
+      title: "Use React with Vite",
+      status: "accepted",
+      date,
+      affected_blocks: ["app-shell"],
+      affected_files: [srcPrefix || "./"],
+      quality_scenarios: []
+    },
+    body: `# ADR-001: Use React with Vite
+
+## Context
+
+${input.name} needs a fast, modern frontend framework for building a single-page application (SPA) with TypeScript.
+
+## Decision
+
+Use React with Vite as the build tool and development server.
+
+## Consequences
+
+- **Positive:** Extremely fast dev server with hot module replacement (HMR)
+- **Positive:** Optimized production builds with tree shaking and code splitting
+- **Positive:** Simple configuration, no SSR complexity
+- **Positive:** Large React ecosystem of libraries and components
+- **Negative:** Client-side only \u2014 no built-in server-side rendering (add later if needed)
+- **Negative:** Requires separate backend service for API endpoints
+`
+  };
+}
+function apiServiceAdr(input, date) {
+  const { srcPrefix } = detectProjectLayout(input.projectRoot, input.template);
+  return {
+    filename: "001-api-service.md",
+    frontmatter: {
+      id: "001-api-service",
+      title: "Use Node.js API Service",
+      status: "accepted",
+      date,
+      affected_blocks: ["app-shell"],
+      affected_files: [srcPrefix || "./"],
+      quality_scenarios: []
+    },
+    body: `# ADR-001: Use Node.js API Service
+
+## Context
+
+${input.name} needs a backend API service with TypeScript support, good performance, and a simple architecture.
+
+## Decision
+
+Use a Node.js HTTP framework (Express, Fastify, or Hono) as the API service foundation.
+
+## Consequences
+
+- **Positive:** TypeScript-first with full type safety
+- **Positive:** Rich middleware ecosystem for auth, validation, logging
+- **Positive:** Easy to deploy to containers, serverless, or traditional hosts
+- **Negative:** Single-threaded \u2014 CPU-intensive operations need worker threads or external services
+- **Negative:** No built-in ORM \u2014 need to choose data access strategy
+`
+  };
+}
 function dotnetAdr(input, date) {
   return {
     filename: "001-aspnet-core-webapi.md",
@@ -1774,8 +1893,8 @@ function writeMarkdownWithFrontmatter(filePath, frontmatter, body) {
   writeFileSync2(filePath, content, "utf-8");
 }
 function generateArc42(targetDir, input) {
-  const arc42Dir = join3(targetDir, ".arcbridge", "arc42");
-  const decisionsDir = join3(arc42Dir, "09-decisions");
+  const arc42Dir = join4(targetDir, ".arcbridge", "arc42");
+  const decisionsDir = join4(arc42Dir, "09-decisions");
   mkdirSync2(arc42Dir, { recursive: true });
   mkdirSync2(decisionsDir, { recursive: true });
   const sections = [
@@ -1790,17 +1909,17 @@ function generateArc42(targetDir, input) {
   const inputWithRoot = { ...input, projectRoot: targetDir };
   for (const { file, template } of sections) {
     const { frontmatter, body } = template(inputWithRoot);
-    writeMarkdownWithFrontmatter(join3(arc42Dir, file), frontmatter, body);
+    writeMarkdownWithFrontmatter(join4(arc42Dir, file), frontmatter, body);
   }
   const adr = firstAdrTemplate(inputWithRoot);
   writeMarkdownWithFrontmatter(
-    join3(decisionsDir, adr.filename),
+    join4(decisionsDir, adr.filename),
     adr.frontmatter,
     adr.body
   );
   const qualityScenarios = qualityScenariosTemplate(input);
   writeFileSync2(
-    join3(arc42Dir, "10-quality-scenarios.yaml"),
+    join4(arc42Dir, "10-quality-scenarios.yaml"),
     stringify2(qualityScenarios),
     "utf-8"
   );
@@ -1808,7 +1927,7 @@ function generateArc42(targetDir, input) {
 
 // src/generators/plan-generator.ts
 import { mkdirSync as mkdirSync3, writeFileSync as writeFileSync3 } from "fs";
-import { join as join4 } from "path";
+import { join as join5 } from "path";
 import { stringify as stringify3 } from "yaml";
 
 // src/templates/phases/nextjs-app-router.ts
@@ -1961,6 +2080,116 @@ function phaseTasksTemplate(_input, phaseId) {
           ]
         }
       ]
+    },
+    "phase-2-features": {
+      schema_version: 1,
+      phase_id: "phase-2-features",
+      tasks: [
+        {
+          id: "task-2.1-core-pages",
+          title: "Implement core application pages",
+          status: "todo",
+          quality_scenarios: ["PERF-01"],
+          acceptance_criteria: [
+            "Core pages created with proper data fetching",
+            "Server/client components properly separated",
+            "Loading and error states handled"
+          ]
+        },
+        {
+          id: "task-2.2-api-routes",
+          title: "Implement API routes",
+          status: "todo",
+          quality_scenarios: ["SEC-01", "PERF-02"],
+          acceptance_criteria: [
+            "API routes created for core operations",
+            "Input validation on all endpoints",
+            "Error responses standardized"
+          ]
+        },
+        {
+          id: "task-2.3-data-layer",
+          title: "Set up data access layer",
+          status: "todo",
+          quality_scenarios: ["MAINT-01"],
+          acceptance_criteria: [
+            "Data fetching patterns established",
+            "Caching strategy implemented",
+            "Type-safe data access"
+          ]
+        },
+        {
+          id: "task-2.4-integration-tests",
+          title: "Write integration tests for core flows",
+          status: "todo",
+          quality_scenarios: ["MAINT-02"],
+          acceptance_criteria: [
+            "Happy path tested for each core feature",
+            "API route tests written",
+            "Test coverage meets threshold"
+          ]
+        },
+        {
+          id: "task-2.5-document-decisions",
+          title: "Document Phase 2 architectural decisions",
+          status: "todo",
+          quality_scenarios: [],
+          acceptance_criteria: [
+            "ADRs for data fetching and API design choices",
+            "Building blocks updated with new code paths"
+          ]
+        }
+      ]
+    },
+    "phase-3-polish": {
+      schema_version: 1,
+      phase_id: "phase-3-polish",
+      tasks: [
+        {
+          id: "task-3.1-error-handling",
+          title: "Implement comprehensive error handling",
+          status: "todo",
+          quality_scenarios: ["SEC-01"],
+          acceptance_criteria: [
+            "Error boundaries at route level",
+            "Custom error.tsx and not-found.tsx pages",
+            "API error responses standardized"
+          ]
+        },
+        {
+          id: "task-3.2-accessibility",
+          title: "Accessibility audit and fixes",
+          status: "todo",
+          quality_scenarios: ["A11Y-01", "A11Y-02"],
+          acceptance_criteria: [
+            "Keyboard navigation works for all interactive elements",
+            "Screen reader compatible (ARIA labels, roles)",
+            "WCAG 2.1 AA compliance verified"
+          ]
+        },
+        {
+          id: "task-3.3-performance",
+          title: "Performance optimization",
+          status: "todo",
+          quality_scenarios: ["PERF-01"],
+          acceptance_criteria: [
+            "Bundle size optimized (dynamic imports, tree shaking)",
+            "Core Web Vitals meet thresholds (LCP < 2.5s)",
+            "Server-side rendering verified for SEO pages"
+          ]
+        },
+        {
+          id: "task-3.4-deployment",
+          title: "Configure production deployment",
+          status: "todo",
+          quality_scenarios: [],
+          acceptance_criteria: [
+            "Production build configuration verified",
+            "Environment variables documented",
+            "Deployment to Vercel/hosting configured"
+          ]
+        }
+      ]
     }
   };
   return tasksByPhase[phaseId] ?? null;
@@ -2128,6 +2357,105 @@ function phaseTasksTemplate2(_input, phaseId) {
           ]
         }
       ]
+    },
+    "phase-2-features": {
+      schema_version: 1,
+      phase_id: "phase-2-features",
+      tasks: [
+        {
+          id: "task-2.1-core-feature",
+          title: "Implement primary feature",
+          status: "todo",
+          quality_scenarios: ["PERF-01"],
+          acceptance_criteria: [
+            "Core user flow works end-to-end",
+            "Unit and component tests written",
+            "Meets performance budgets"
+          ]
+        },
+        {
+          id: "task-2.2-state-management",
+          title: "Set up state management for complex data",
+          status: "todo",
+          quality_scenarios: ["MAINT-01"],
+          acceptance_criteria: [
+            "State management pattern established",
+            "Data fetching/caching strategy implemented",
+            "Loading and error states handled"
+          ]
+        },
+        {
+          id: "task-2.3-integration-tests",
+          title: "Write integration tests for core flows",
+          status: "todo",
+          quality_scenarios: ["MAINT-02"],
+          acceptance_criteria: [
+            "Happy path tested for each core feature",
+            "Error scenarios tested",
+            "Test coverage meets threshold"
+          ]
+        },
+        {
+          id: "task-2.4-document-decisions",
+          title: "Document Phase 2 architectural decisions",
+          status: "todo",
+          quality_scenarios: [],
+          acceptance_criteria: [
+            "ADRs for state management and data fetching choices",
+            "Building blocks updated with new code paths"
+          ]
+        }
+      ]
+    },
+    "phase-3-polish": {
+      schema_version: 1,
+      phase_id: "phase-3-polish",
+      tasks: [
+        {
+          id: "task-3.1-error-handling",
+          title: "Implement comprehensive error handling",
+          status: "todo",
+          quality_scenarios: ["SEC-01"],
+          acceptance_criteria: [
+            "Error boundaries at route level",
+            "User-friendly error messages",
+            "Error logging configured"
+          ]
+        },
+        {
+          id: "task-3.2-accessibility",
+          title: "Accessibility audit and fixes",
+          status: "todo",
+          quality_scenarios: ["A11Y-01", "A11Y-02"],
+          acceptance_criteria: [
+            "Keyboard navigation works for all interactive elements",
+            "Screen reader compatible (ARIA labels, roles)",
+            "WCAG 2.1 AA compliance verified"
+          ]
+        },
+        {
+          id: "task-3.3-performance",
+          title: "Performance optimization",
+          status: "todo",
+          quality_scenarios: ["PERF-01"],
+          acceptance_criteria: [
+            "Bundle size optimized (code splitting, tree shaking)",
+            "Lighthouse performance score >= 90",
+            "No unnecessary re-renders in hot paths"
+          ]
+        },
+        {
+          id: "task-3.4-deployment",
+          title: "Configure production build and deployment",
+          status: "todo",
+          quality_scenarios: [],
+          acceptance_criteria: [
+            "Production build configuration verified",
+            "Deployment pipeline configured",
+            "Environment variables documented"
+          ]
+        }
+      ]
     }
   };
   return tasksByPhase[phaseId] ?? null;
@@ -2523,25 +2851,25 @@ var planTemplates = {
   "dotnet-webapi": { plan: phasePlanTemplate4, tasks: phaseTasksTemplate4 }
 };
 function generatePlan(targetDir, input) {
-  const planDir = join4(targetDir, ".arcbridge", "plan");
-  const tasksDir = join4(planDir, "tasks");
+  const planDir = join5(targetDir, ".arcbridge", "plan");
+  const tasksDir = join5(planDir, "tasks");
   mkdirSync3(planDir, { recursive: true });
   mkdirSync3(tasksDir, { recursive: true });
   const tmpl = planTemplates[input.template] ?? planTemplates["nextjs-app-router"];
   const phasePlan = tmpl.plan(input);
-  writeFileSync3(join4(planDir, "phases.yaml"), stringify3(phasePlan), "utf-8");
+  writeFileSync3(join5(planDir, "phases.yaml"), stringify3(phasePlan), "utf-8");
   for (const phase of phasePlan.phases) {
     const taskFile = tmpl.tasks(input, phase.id);
     if (taskFile) {
       writeFileSync3(
-        join4(tasksDir, `${phase.id}.yaml`),
+        join5(tasksDir, `${phase.id}.yaml`),
         stringify3(taskFile),
         "utf-8"
       );
     }
   }
   writeFileSync3(
-    join4(planDir, "sync-log.md"),
+    join5(planDir, "sync-log.md"),
     `# Sync Log
 
 Architecture sync events are recorded here.
@@ -2552,7 +2880,7 @@ Architecture sync events are recorded here.
 
 // src/generators/agent-generator.ts
 import { mkdirSync as mkdirSync4, writeFileSync as writeFileSync4 } from "fs";
-import { join as join5 } from "path";
+import { join as join6 } from "path";
 import matter2 from "gray-matter";
 
 // src/templates/agents/architect.ts
@@ -2646,6 +2974,19 @@ You are responsible for maintaining these sections in \`.arcbridge/arc42/\`. Upd
 - All ADRs and their status
 - Building block \u2192 code mapping
 
+## Project Planning
+
+At the start of a project (after init), plan the full roadmap:
+- **ArcBridge generates 4 phases as a starting template** (Setup, Foundation, Features, Polish). These are a baseline \u2014 adapt them to your project's actual scope and complexity.
+- **For larger projects, add more phases** by editing \`.arcbridge/plan/phases.yaml\` and running \`arcbridge_reindex\`. Split "Core Features" into multiple phases if needed (e.g., "Phase 2: Auth & Users", "Phase 3: Core Business Logic", "Phase 4: Integrations", "Phase 5: Polish").
+- **Phase 0-1 tasks are ready to use** \u2014 they cover setup and foundation for this template
+- **Phase 2+ tasks are examples** \u2014 replace them with real tasks derived from the project's requirements and specifications
+- Review the phase plan with \`arcbridge_get_phase_plan\` and replace example tasks with project-specific ones
+- Create tasks using \`arcbridge_create_task\` with the phase ID shown in the plan
+- Keep each phase reasonably scoped \u2014 3-6 tasks per phase is ideal
+- Map tasks to building blocks so drift detection tracks coverage
+- Link tasks to quality scenarios so gate checks are meaningful
+
 ## Working Style
 
 Think at the system level. Before making changes, consider:
@@ -2795,11 +3136,13 @@ function qualityGuardianTemplate() {
       "arcbridge_search_symbols",
       "arcbridge_get_symbol",
       "arcbridge_get_component_graph",
-      "arcbridge_get_boundary_analysis"
-      // Phase 3+: "arcbridge_run_role_check"
+      "arcbridge_get_boundary_analysis",
+      "arcbridge_update_scenario_status",
+      "arcbridge_verify_scenarios",
+      "arcbridge_run_role_check"
     ],
     denied_tools: [],
-    read_only: true,
+    read_only: false,
     quality_focus: [
       "performance",
       "accessibility",
@@ -2830,6 +3173,23 @@ function qualityGuardianTemplate() {
 - Every quality scenario with status "untested" needs attention
 - Performance budgets are hard limits, not guidelines
 
+## Linking Tests to Quality Scenarios
+
+Quality scenarios need \`linked_tests\` to be verifiable via \`arcbridge_verify_scenarios\`. To link tests:
+
+1. Edit \`.arcbridge/arc42/10-quality-scenarios.yaml\`
+2. Add test file paths to the \`linked_tests\` array for each scenario:
+   \`\`\`yaml
+   - id: SEC-01
+     linked_tests:
+       - "src/__tests__/auth.test.ts"
+       - "src/__tests__/middleware.test.ts"
+   \`\`\`
+3. Use glob patterns for broader matching: \`"src/**/*.security.test.ts"\`
+4. After linking, run \`arcbridge_verify_scenarios\` to execute the tests and update scenario status
+
+Without \`linked_tests\`, scenarios remain "untested" \u2014 so link tests early, ideally when creating the test file.
+
 ## Review Checklist
 
 1. **Performance:** Bundle size, LCP, API latency against defined budgets
@@ -2851,7 +3211,11 @@ function phaseManagerTemplate() {
       "arcbridge_get_phase_plan",
       "arcbridge_get_current_tasks",
       "arcbridge_update_task",
+      "arcbridge_delete_task",
+      "arcbridge_create_task",
       "arcbridge_check_drift",
+      "arcbridge_verify_scenarios",
+      "arcbridge_update_scenario_status",
       "arcbridge_get_open_questions",
       "arcbridge_propose_arc42_update"
     ],
@@ -2883,13 +3247,28 @@ function phaseManagerTemplate() {
 - Tasks must be "done" before a phase can complete
 - Quality scenarios linked to phase tasks must be verified
 
+## Task Planning
+
+Before starting any phase, ensure proper task planning:
+- **ArcBridge generates 4 phases as a starting template.** For larger projects, add more phases by editing \`.arcbridge/plan/phases.yaml\` and running \`arcbridge_reindex\`.
+- **Phase 0-1 tasks are concrete** \u2014 they cover project setup and foundation. Follow them as-is.
+- **Phase 2+ tasks are examples only** \u2014 they show the *shape* of later phases but must be replaced with real tasks derived from the project's actual requirements and specs.
+- **At project start, plan ALL phases** \u2014 review \`arcbridge_get_phase_plan\`, delete example tasks in Phase 2+ using \`arcbridge_delete_task\`, and create real tasks based on the product spec.
+- **Delete vs cancel** \u2014 use \`arcbridge_delete_task\` for example/template tasks that should be removed. Use \`arcbridge_update_task\` with status \`cancelled\` for planned tasks that turned out to be unnecessary (preserves the decision trail).
+- **Keep phases small and focused** \u2014 if a phase has more than 6-8 tasks, split it into sub-phases
+- **Tasks should be concrete and verifiable** \u2014 each task needs clear acceptance criteria
+- **Link tasks to building blocks** \u2014 this enables drift detection and progress tracking
+- **Use \`arcbridge_create_task\` with the phase ID** shown in \`arcbridge_get_phase_plan\` output (e.g., \`phase-2-features\`)
+
 ## Phase Transition Process
 
 1. Verify all tasks in current phase are "done"
-2. Run drift detection (check_drift)
-3. Propose arc42 updates if drift is detected
-4. Check quality gate requirements
-5. Mark phase complete or report blockers`
+2. Review task coverage for the NEXT phase \u2014 create tasks if empty
+3. Run drift detection (\`arcbridge_check_drift\`)
+4. Propose arc42 updates if drift is detected
+5. Ensure quality scenarios have \`linked_tests\` \u2014 edit \`10-quality-scenarios.yaml\` to add test file paths so \`arcbridge_verify_scenarios\` can run them
+6. Check quality gate requirements
+7. Mark phase complete or report blockers`
   };
 }
 
@@ -3116,10 +3495,10 @@ var UI_TEMPLATES = /* @__PURE__ */ new Set(["nextjs-app-router", "react-vite"]);
 function writeAgentRole(dir, role) {
   const { system_prompt, ...frontmatter } = role;
   const content = matter2.stringify(system_prompt, frontmatter);
-  writeFileSync4(join5(dir, `${role.role_id}.md`), content, "utf-8");
+  writeFileSync4(join6(dir, `${role.role_id}.md`), content, "utf-8");
 }
 function generateAgentRoles(targetDir, template) {
-  const agentsDir = join5(targetDir, ".arcbridge", "agents");
+  const agentsDir = join6(targetDir, ".arcbridge", "agents");
   mkdirSync4(agentsDir, { recursive: true });
   const roles = [
     architectTemplate(),
@@ -3140,19 +3519,19 @@ function generateAgentRoles(targetDir, template) {
 }
 
 // src/generators/db-generator.ts
-import { join as join6 } from "path";
-import { existsSync as existsSync2, readFileSync, readdirSync, appendFileSync } from "fs";
+import { join as join7 } from "path";
+import { existsSync as existsSync3, readFileSync, readdirSync as readdirSync2, appendFileSync } from "fs";
 import { parse } from "yaml";
 import matter3 from "gray-matter";
 function populateBuildingBlocks(db, targetDir) {
   const warnings = [];
-  const filePath = join6(
+  const filePath = join7(
     targetDir,
     ".arcbridge",
     "arc42",
     "05-building-blocks.md"
   );
-  if (!existsSync2(filePath)) {
+  if (!existsSync3(filePath)) {
     warnings.push("Building blocks file not found, skipping");
     return warnings;
   }
@@ -3161,7 +3540,7 @@ function populateBuildingBlocks(db, targetDir) {
   const result = BuildingBlocksFrontmatterSchema.safeParse(data);
   if (!result.success) {
     warnings.push(
-      `Invalid building blocks frontmatter: ${result.error.issues.map((i) => i.message).join(", ")}`
+      `Invalid building blocks frontmatter: ${result.error.issues.map((i) => i.path.length ? `${i.path.join(".")}: ${i.message}` : i.message).join(", ")}`
     );
     return warnings;
   }
@@ -3188,13 +3567,13 @@ function populateBuildingBlocks(db, targetDir) {
 }
 function populateQualityScenarios(db, targetDir) {
   const warnings = [];
-  const filePath = join6(
+  const filePath = join7(
     targetDir,
     ".arcbridge",
     "arc42",
     "10-quality-scenarios.yaml"
   );
-  if (!existsSync2(filePath)) {
+  if (!existsSync3(filePath)) {
     warnings.push("Quality scenarios file not found, skipping");
     return warnings;
   }
@@ -3203,7 +3582,7 @@ function populateQualityScenarios(db, targetDir) {
   const result = QualityScenariosFileSchema.safeParse(parsed);
   if (!result.success) {
     warnings.push(
-      `Invalid quality scenarios: ${result.error.issues.map((i) => i.message).join(", ")}`
+      `Invalid quality scenarios: ${result.error.issues.map((i) => i.path.length ? `${i.path.join(".")}: ${i.message}` : i.message).join(", ")}`
     );
     return warnings;
   }
@@ -3230,8 +3609,8 @@ function populateQualityScenarios(db, targetDir) {
 }
 function populatePhases(db, targetDir) {
   const warnings = [];
-  const phasesPath = join6(targetDir, ".arcbridge", "plan", "phases.yaml");
-  if (!existsSync2(phasesPath)) {
+  const phasesPath = join7(targetDir, ".arcbridge", "plan", "phases.yaml");
+  if (!existsSync3(phasesPath)) {
     warnings.push("Phases file not found, skipping");
     return warnings;
   }
@@ -3240,7 +3619,7 @@ function populatePhases(db, targetDir) {
   const result = PhasesFileSchema.safeParse(parsed);
   if (!result.success) {
     warnings.push(
-      `Invalid phases file: ${result.error.issues.map((i) => i.message).join(", ")}`
+      `Invalid phases file: ${result.error.issues.map((i) => i.path.length ? `${i.path.join(".")}: ${i.message}` : i.message).join(", ")}`
     );
     return warnings;
   }
@@ -3264,20 +3643,20 @@ function populatePhases(db, targetDir) {
       phase.started_at ?? null,
       phase.completed_at ?? null
     );
-    const taskPath = join6(
+    const taskPath = join7(
       targetDir,
       ".arcbridge",
       "plan",
       "tasks",
       `${phase.id}.yaml`
     );
-    if (!existsSync2(taskPath)) continue;
+    if (!existsSync3(taskPath)) continue;
     const taskRaw = readFileSync(taskPath, "utf-8");
     const taskParsed = parse(taskRaw);
     const taskResult = TaskFileSchema.safeParse(taskParsed);
     if (!taskResult.success) {
       warnings.push(
-        `Invalid task file for ${phase.id}: ${taskResult.error.issues.map((i) => i.message).join(", ")}`
+        `Invalid task file for ${phase.id}: ${taskResult.error.issues.map((i) => i.path.length ? `${i.path.join(".")}: ${i.message}` : i.message).join(", ")}`
       );
       continue;
     }
@@ -3299,27 +3678,27 @@ function populatePhases(db, targetDir) {
 }
 function populateAdrs(db, targetDir) {
   const warnings = [];
-  const decisionsDir = join6(
+  const decisionsDir = join7(
     targetDir,
     ".arcbridge",
     "arc42",
     "09-decisions"
   );
-  if (!existsSync2(decisionsDir)) {
+  if (!existsSync3(decisionsDir)) {
     return warnings;
   }
-  const files = readdirSync(decisionsDir).filter((f) => f.endsWith(".md"));
+  const files = readdirSync2(decisionsDir).filter((f) => f.endsWith(".md"));
   const insert = db.prepare(`
     INSERT OR IGNORE INTO adrs (id, title, status, date, context, decision, consequences, affected_blocks, affected_files, quality_scenarios)
     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
   `);
   for (const file of files) {
-    const raw = readFileSync(join6(decisionsDir, file), "utf-8");
+    const raw = readFileSync(join7(decisionsDir, file), "utf-8");
     const { data, content } = matter3(raw);
     const result = AdrFrontmatterSchema.safeParse(data);
     if (!result.success) {
       warnings.push(
-        `Invalid ADR ${file}: ${result.error.issues.map((i) => i.message).join(", ")}`
+        `Invalid ADR ${file}: ${result.error.issues.map((i) => i.path.length ? `${i.path.join(".")}: ${i.message}` : i.message).join(", ")}`
       );
       continue;
     }
@@ -3353,6 +3732,7 @@ function refreshFromDocs(db, targetDir) {
   const scenarioStatusMap = new Map(
     existingScenarios.map((s) => [s.id, s.status])
   );
+  db.exec("PRAGMA foreign_keys = OFF");
   const refresh = () => transaction(db, () => {
     db.prepare("DELETE FROM tasks").run();
     db.prepare("DELETE FROM phases").run();
@@ -3365,6 +3745,16 @@ function refreshFromDocs(db, targetDir) {
     warnings.push(...populateQualityScenarios(db, targetDir));
     warnings.push(...populatePhases(db, targetDir));
     warnings.push(...populateAdrs(db, targetDir));
+    const orphaned = db.prepare(`
+      UPDATE tasks SET building_block = NULL
+      WHERE building_block IS NOT NULL
+        AND building_block NOT IN (SELECT id FROM building_blocks)
+    `).run();
+    if (orphaned.changes > 0) {
+      warnings.push(
+        `${orphaned.changes} task(s) referenced removed building blocks (references cleared)`
+      );
+    }
     const restoreTask = db.prepare(
       "UPDATE tasks SET status = ?, completed_at = ? WHERE id = ?"
     );
@@ -3390,11 +3780,15 @@ function refreshFromDocs(db, targetDir) {
       }
     }
   });
-  refresh();
+  try {
+    refresh();
+  } finally {
+    db.exec("PRAGMA foreign_keys = ON");
+  }
   return warnings;
 }
 function generateDatabase(targetDir, input) {
-  const dbPath = join6(targetDir, ".arcbridge", "index.db");
+  const dbPath = join7(targetDir, ".arcbridge", "index.db");
   const db = openDatabase(dbPath);
   initializeSchema(db);
   const allWarnings = [];
@@ -3414,9 +3808,9 @@ function generateDatabase(targetDir, input) {
   return { db, warnings: allWarnings };
 }
 function ensureGitignore(targetDir) {
-  const gitignorePath = join6(targetDir, ".gitignore");
+  const gitignorePath = join7(targetDir, ".gitignore");
   const marker = ".arcbridge/index.db";
-  if (existsSync2(gitignorePath)) {
+  if (existsSync3(gitignorePath)) {
     const content = readFileSync(gitignorePath, "utf-8");
     if (content.includes(marker)) return;
   }
@@ -3430,14 +3824,14 @@ function ensureGitignore(targetDir) {
 }
 
 // src/indexer/index.ts
-import { relative as relative5, join as join13 } from "path";
-import { existsSync as existsSync6, readFileSync as readFileSync7 } from "fs";
+import { relative as relative5, join as join14 } from "path";
+import { existsSync as existsSync7, readFileSync as readFileSync7 } from "fs";
 import { execFileSync as execFileSync2 } from "child_process";
 import YAML from "yaml";
 
 // src/indexer/program.ts
 import ts from "typescript";
-import { join as join7 } from "path";
+import { join as join8, dirname } from "path";
 function createTsProgram(options) {
   const projectRoot = options.projectRoot;
   const configPath = options.tsconfigPath ?? ts.findConfigFile(projectRoot, ts.sys.fileExists, "tsconfig.json");
@@ -3446,7 +3840,7 @@ function createTsProgram(options) {
       `No tsconfig.json found in ${projectRoot}. TypeScript indexing requires a tsconfig.json.`
     );
   }
-  const configFile = ts.readConfigFile(configPath, ts.sys.readFile);
+  let configFile = ts.readConfigFile(configPath, ts.sys.readFile);
   if (configFile.error) {
     const message = ts.flattenDiagnosticMessageText(
       configFile.error.messageText,
@@ -3454,12 +3848,45 @@ function createTsProgram(options) {
     );
     throw new Error(`Failed to read tsconfig.json: ${message}`);
   }
+  let resolvedConfigPath = configPath;
+  const config = configFile.config;
+  const hasOwnFiles = config.include && config.include.length > 0 || config.files && config.files.length > 0;
+  if (config.references && !hasOwnFiles) {
+    for (const ref of config.references) {
+      const refRelPath = typeof ref === "string" ? ref : ref.path;
+      if (!refRelPath) continue;
+      const refFullPath = join8(dirname(configPath), refRelPath);
+      const refConfigPath = refFullPath.endsWith(".json") ? refFullPath : join8(refFullPath, "tsconfig.json");
+      if (ts.sys.fileExists(refConfigPath)) {
+        const refConfig = ts.readConfigFile(refConfigPath, ts.sys.readFile);
+        const rc = refConfig.config;
+        if (!refConfig.error && (rc.include?.length > 0 || rc.files?.length > 0)) {
+          configFile = refConfig;
+          resolvedConfigPath = refConfigPath;
+          break;
+        }
+      }
+    }
+    if (resolvedConfigPath === configPath) {
+      for (const candidate of ["tsconfig.app.json", "tsconfig.src.json"]) {
+        const refPath = ts.findConfigFile(projectRoot, ts.sys.fileExists, candidate);
+        if (refPath) {
+          const refConfig = ts.readConfigFile(refPath, ts.sys.readFile);
+          if (!refConfig.error) {
+            configFile = refConfig;
+            resolvedConfigPath = refPath;
+            break;
+          }
+        }
+      }
+    }
+  }
   const parsed = ts.parseJsonConfigFileContent(
     configFile.config,
     ts.sys,
-    join7(projectRoot),
+    join8(projectRoot),
     { noEmit: true },
-    configPath
+    resolvedConfigPath
   );
   const program = ts.createProgram({
     rootNames: parsed.fileNames,
@@ -3467,7 +3894,7 @@ function createTsProgram(options) {
   });
   const checker = program.getTypeChecker();
   const sourceFiles = program.getSourceFiles().filter(
-    (sf) => !sf.isDeclarationFile && !sf.fileName.includes("node_modules")
+    (sf) => !sf.isDeclarationFile && !sf.fileName.includes("node_modules") && !sf.fileName.includes(".next/") && !sf.fileName.includes(".next\\")
   );
   return { program, checker, sourceFiles, projectRoot };
 }
@@ -4225,8 +4652,8 @@ function writeComponents(db, components) {
 }
 
 // src/indexer/route-analyzer.ts
-import { existsSync as existsSync3, readdirSync as readdirSync2, readFileSync as readFileSync2, statSync } from "fs";
-import { join as join8, relative as relative3 } from "path";
+import { existsSync as existsSync4, readdirSync as readdirSync3, readFileSync as readFileSync2, statSync } from "fs";
+import { join as join9, relative as relative3 } from "path";
 var FILE_KIND_MAP = {
   "page": "page",
   "layout": "layout",
@@ -4237,15 +4664,22 @@ var FILE_KIND_MAP = {
 };
 var TS_EXTENSIONS = [".tsx", ".ts", ".jsx", ".js"];
 function analyzeRoutes(projectRoot, db, service = "main") {
-  const appDir = join8(projectRoot, "app");
-  if (!existsSync3(appDir) || !statSync(appDir).isDirectory()) {
+  let appDir = join9(projectRoot, "app");
+  try {
+    if (!existsSync4(appDir) || !statSync(appDir).isDirectory()) {
+      appDir = join9(projectRoot, "src", "app");
+      if (!existsSync4(appDir) || !statSync(appDir).isDirectory()) {
+        return 0;
+      }
+    }
+  } catch {
     return 0;
   }
   const routes = [];
   const layoutStack = [];
   for (const ext of TS_EXTENSIONS) {
-    const middlewarePath = join8(projectRoot, `middleware${ext}`);
-    if (existsSync3(middlewarePath)) {
+    const middlewarePath = join9(projectRoot, `middleware${ext}`);
+    if (existsSync4(middlewarePath)) {
       routes.push({
         id: `route::middleware`,
         routePath: "/",
@@ -4265,15 +4699,15 @@ function analyzeRoutes(projectRoot, db, service = "main") {
 function walkAppDir(dir, routePath, routes, layoutStack, service, projectRoot) {
   let entries;
   try {
-    entries = readdirSync2(dir);
+    entries = readdirSync3(dir);
   } catch {
     return;
   }
   const currentLayout = layoutStack.length > 0 ? layoutStack[layoutStack.length - 1] : null;
   for (const [convention, kind] of Object.entries(FILE_KIND_MAP)) {
     for (const ext of TS_EXTENSIONS) {
-      const filePath = join8(dir, `${convention}${ext}`);
-      if (existsSync3(filePath)) {
+      const filePath = join9(dir, `${convention}${ext}`);
+      if (existsSync4(filePath)) {
         const relPath = relative3(projectRoot, dir);
         const routeId = `route::${relPath}/${convention}`;
         const route = {
@@ -4297,7 +4731,7 @@ function walkAppDir(dir, routePath, routes, layoutStack, service, projectRoot) {
     }
   }
   for (const entry of entries.sort()) {
-    const fullPath = join8(dir, entry);
+    const fullPath = join9(dir, entry);
     try {
       if (!statSync(fullPath).isDirectory()) continue;
     } catch {
@@ -4463,16 +4897,16 @@ function writeDependencies(db, dependencies) {
 
 // src/indexer/dotnet-indexer.ts
 import { execFileSync } from "child_process";
-import { resolve, join as join9, dirname, relative as relative4, basename } from "path";
-import { readdirSync as readdirSync3, readFileSync as readFileSync3, existsSync as existsSync4, accessSync, constants } from "fs";
+import { resolve, join as join10, dirname as dirname2, relative as relative4, basename } from "path";
+import { readdirSync as readdirSync4, readFileSync as readFileSync3, existsSync as existsSync5, accessSync, constants } from "fs";
 import { fileURLToPath } from "url";
 function findDotnetProject(projectRoot) {
   try {
-    const entries = readdirSync3(projectRoot);
+    const entries = readdirSync4(projectRoot);
     const sln = entries.find((e) => e.endsWith(".sln"));
-    if (sln) return join9(projectRoot, sln);
+    if (sln) return join10(projectRoot, sln);
     const csproj = entries.find((e) => e.endsWith(".csproj"));
-    if (csproj) return join9(projectRoot, csproj);
+    if (csproj) return join10(projectRoot, csproj);
     return null;
   } catch {
     return null;
@@ -4480,16 +4914,16 @@ function findDotnetProject(projectRoot) {
 }
 function parseSolutionProjects(slnPath) {
   const content = readFileSync3(slnPath, "utf-8");
-  const slnDir = dirname(slnPath);
+  const slnDir = dirname2(slnPath);
   const projects = [];
   const projectPattern = /Project\("\{[^}]+\}"\)\s*=\s*"([^"]+)",\s*"([^"]+\.csproj)"/g;
   let match;
   while ((match = projectPattern.exec(content)) !== null) {
     const name = match[1];
     const relativeCsprojPath = match[2].replace(/\\/g, "/");
-    const fullCsprojPath = resolve(join9(slnDir, relativeCsprojPath));
-    if (!existsSync4(fullCsprojPath)) continue;
-    const projectDir = relative4(slnDir, dirname(fullCsprojPath)).replace(/\\/g, "/") || ".";
+    const fullCsprojPath = resolve(join10(slnDir, relativeCsprojPath));
+    if (!existsSync5(fullCsprojPath)) continue;
+    const projectDir = relative4(slnDir, dirname2(fullCsprojPath)).replace(/\\/g, "/") || ".";
     const isTestProject = /[.\x2d]tests?$/i.test(name) || /[.\x2d](unit|integration|functional|e2e)tests?$/i.test(name);
     projects.push({
       name,
@@ -4524,7 +4958,7 @@ function hasGlobalTool() {
     if (!dir) continue;
     for (const ext of extensions) {
       try {
-        accessSync(join9(dir, `${name}${ext}`), constants.X_OK);
+        accessSync(join10(dir, `${name}${ext}`), constants.X_OK);
         return true;
       } catch {
         continue;
@@ -4534,14 +4968,14 @@ function hasGlobalTool() {
   return false;
 }
 function resolveIndexerProject() {
-  const currentDir2 = dirname(fileURLToPath(import.meta.url));
+  const currentDir2 = dirname2(fileURLToPath(import.meta.url));
   const candidates = [
     resolve(currentDir2, "../../../../dotnet-indexer/ArcBridge.DotnetIndexer.csproj"),
     resolve(currentDir2, "../../../dotnet-indexer/ArcBridge.DotnetIndexer.csproj"),
     resolve(currentDir2, "../../dotnet-indexer/ArcBridge.DotnetIndexer.csproj")
   ];
   for (const candidate of candidates) {
-    if (existsSync4(candidate)) return candidate;
+    if (existsSync5(candidate)) return candidate;
   }
   return null;
 }
@@ -4683,15 +5117,15 @@ function indexDotnetProjectRoslyn(db, options) {
 
 // src/indexer/csharp/indexer.ts
 import { readFileSync as readFileSync4 } from "fs";
-import { join as join10 } from "path";
+import { join as join11 } from "path";
 import { globbySync } from "globby";
 
 // src/indexer/csharp/parser.ts
 import { accessSync as accessSync2, constants as constants2 } from "fs";
-import { dirname as dirname2, resolve as resolve2 } from "path";
+import { dirname as dirname3, resolve as resolve2 } from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 import "web-tree-sitter";
-var currentDir = dirname2(fileURLToPath2(import.meta.url));
+var currentDir = dirname3(fileURLToPath2(import.meta.url));
 var cachedParser = null;
 var initPromise = null;
 function resolveGrammarPath() {
@@ -5535,7 +5969,7 @@ async function indexCSharpTreeSitter(db, options) {
   for (const filePath of csFiles) {
     const relPath = filePath.replace(/\\/g, "/");
     currentPaths.add(relPath);
-    const fullPath = join10(projectRoot, relPath);
+    const fullPath = join11(projectRoot, relPath);
     const content = readFileSync4(fullPath, "utf-8");
     const hash = hashContent(content);
     const tree = parseCSharp(content);
@@ -5611,12 +6045,12 @@ async function indexCSharpTreeSitter(db, options) {
 }
 
 // src/indexer/package-deps.ts
-import { join as join11 } from "path";
-import { existsSync as existsSync5, readFileSync as readFileSync5, readdirSync as readdirSync4 } from "fs";
+import { join as join12 } from "path";
+import { existsSync as existsSync6, readFileSync as readFileSync5, readdirSync as readdirSync5 } from "fs";
 function indexPackageDependencies(db, projectRoot, service = "main") {
   const deps = [];
-  const pkgJsonPath = join11(projectRoot, "package.json");
-  if (existsSync5(pkgJsonPath)) {
+  const pkgJsonPath = join12(projectRoot, "package.json");
+  if (existsSync6(pkgJsonPath)) {
     deps.push(...parsePackageJson(pkgJsonPath));
   }
   const csprojFiles = findCsprojFiles(projectRoot);
@@ -5678,10 +6112,10 @@ function findCsprojFiles(dir, maxDepth = 4) {
   function walk(currentDir2, depth) {
     if (depth > maxDepth) return;
     try {
-      const entries = readdirSync4(currentDir2, { withFileTypes: true });
+      const entries = readdirSync5(currentDir2, { withFileTypes: true });
       for (const entry of entries) {
         if (entry.name === "bin" || entry.name === "obj" || entry.name === "node_modules" || entry.name === ".git") continue;
-        const fullPath = join11(currentDir2, entry.name);
+        const fullPath = join12(currentDir2, entry.name);
         if (entry.isFile() && entry.name.endsWith(".csproj")) {
           results.push(fullPath);
         } else if (entry.isDirectory()) {
@@ -5697,10 +6131,10 @@ function findCsprojFiles(dir, maxDepth = 4) {
 
 // src/config/loader.ts
 import { readFileSync as readFileSync6 } from "fs";
-import { join as join12 } from "path";
+import { join as join13 } from "path";
 import yaml from "yaml";
 function loadConfig(projectRoot) {
-  const configPath = join12(projectRoot, ".arcbridge", "config.yaml");
+  const configPath = join13(projectRoot, ".arcbridge", "config.yaml");
   try {
     const raw = readFileSync6(configPath, "utf-8");
     const parsed = ArcBridgeConfigSchema.safeParse(yaml.parse(raw));
@@ -5719,8 +6153,8 @@ function loadConfig(projectRoot) {
 
 // src/indexer/index.ts
 function detectProjectLanguage(projectRoot) {
-  if (existsSync6(join13(projectRoot, "tsconfig.json"))) return "typescript";
-  if (existsSync6(join13(projectRoot, "package.json"))) return "typescript";
+  if (existsSync7(join14(projectRoot, "tsconfig.json"))) return "typescript";
+  if (existsSync7(join14(projectRoot, "package.json"))) return "typescript";
   if (findDotnetProject(projectRoot)) return "csharp";
   return "typescript";
 }
@@ -5748,7 +6182,7 @@ function resolveCSharpBackend(projectRoot) {
   let setting = config?.indexing?.csharp_indexer;
   if (!setting && error) {
     try {
-      const raw = readFileSync7(join13(projectRoot, ".arcbridge", "config.yaml"), "utf-8");
+      const raw = readFileSync7(join14(projectRoot, ".arcbridge", "config.yaml"), "utf-8");
       const parsed = YAML.parse(raw);
       const rawSetting = parsed?.indexing?.csharp_indexer;
       if (rawSetting === "roslyn" || rawSetting === "tree-sitter") {
@@ -6047,7 +6481,17 @@ function detectNewDependencies(db, entries) {
   const adrs = db.prepare("SELECT id, title, context, decision FROM adrs WHERE status != 'superseded'").all();
   const adrText = adrs.map((a) => `${a.title} ${a.context ?? ""} ${a.decision ?? ""}`.toLowerCase()).join(" ");
   const trivialPackages = /* @__PURE__ */ new Set([
-    // npm
+    // npm — frameworks (core deps that don't need ADRs)
+    "react",
+    "react-dom",
+    "next",
+    "vite",
+    "@vitejs/plugin-react",
+    "express",
+    "fastify",
+    "hono",
+    "koa",
+    // npm — dev tooling
     "typescript",
     "eslint",
     "prettier",
@@ -6055,15 +6499,28 @@ function detectNewDependencies(db, entries) {
     "jest",
     "@types/node",
     "@types/react",
+    "@types/react-dom",
     "tsup",
     "tsx",
-    // nuget
+    "ts-node",
+    "nodemon",
+    "@eslint/js",
+    "typescript-eslint",
+    // npm — build/bundler
+    "esbuild",
+    "rollup",
+    "webpack",
+    "postcss",
+    "tailwindcss",
+    "autoprefixer",
+    // nuget — test
     "microsoft.net.test.sdk",
     "xunit",
     "xunit.runner.visualstudio",
     "nunit",
     "nunit3testadapter",
     "coverlet.collector",
+    // nuget — framework
     "microsoft.aspnetcore.openapi",
     "swashbuckle.aspnetcore"
   ]);
@@ -6101,18 +6558,18 @@ function safeParseJson(value, fallback) {
 }
 
 // src/sync/yaml-writer.ts
-import { join as join14 } from "path";
-import { existsSync as existsSync7, readFileSync as readFileSync8, writeFileSync as writeFileSync5, mkdirSync as mkdirSync5 } from "fs";
+import { join as join15 } from "path";
+import { existsSync as existsSync8, readFileSync as readFileSync8, writeFileSync as writeFileSync5, mkdirSync as mkdirSync5 } from "fs";
 import { parse as parse2, stringify as stringify4 } from "yaml";
 function syncTaskToYaml(projectRoot, phaseId, taskId, status, completedAt) {
-  const taskPath = join14(
+  const taskPath = join15(
     projectRoot,
     ".arcbridge",
     "plan",
     "tasks",
     `${phaseId}.yaml`
   );
-  if (!existsSync7(taskPath)) return;
+  if (!existsSync8(taskPath)) return;
   const raw = readFileSync8(taskPath, "utf-8");
   const parsed = parse2(raw);
   const result = TaskFileSchema.safeParse(parsed);
@@ -6129,11 +6586,11 @@ function syncTaskToYaml(projectRoot, phaseId, taskId, status, completedAt) {
   writeFileSync5(taskPath, stringify4(taskFile), "utf-8");
 }
 function addTaskToYaml(projectRoot, phaseId, task) {
-  const tasksDir = join14(projectRoot, ".arcbridge", "plan", "tasks");
-  const taskPath = join14(tasksDir, `${phaseId}.yaml`);
+  const tasksDir = join15(projectRoot, ".arcbridge", "plan", "tasks");
+  const taskPath = join15(tasksDir, `${phaseId}.yaml`);
   mkdirSync5(tasksDir, { recursive: true });
   let taskFile;
-  if (existsSync7(taskPath)) {
+  if (existsSync8(taskPath)) {
     const raw = readFileSync8(taskPath, "utf-8");
     const parsed = parse2(raw);
     const result = TaskFileSchema.safeParse(parsed);
@@ -6151,13 +6608,13 @@ function addTaskToYaml(projectRoot, phaseId, task) {
   writeFileSync5(taskPath, stringify4(taskFile), "utf-8");
 }
 function syncPhaseToYaml(projectRoot, phaseId, status, startedAt, completedAt) {
-  const phasesPath = join14(
+  const phasesPath = join15(
     projectRoot,
     ".arcbridge",
     "plan",
     "phases.yaml"
   );
-  if (!existsSync7(phasesPath)) return;
+  if (!existsSync8(phasesPath)) return;
   const raw = readFileSync8(phasesPath, "utf-8");
   const parsed = parse2(raw);
   const result = PhasesFileSchema.safeParse(parsed);
@@ -6170,14 +6627,14 @@ function syncPhaseToYaml(projectRoot, phaseId, status, startedAt, completedAt) {
   if (completedAt) phase.completed_at = completedAt;
   writeFileSync5(phasesPath, stringify4(phasesFile), "utf-8");
 }
-function syncScenarioToYaml(projectRoot, scenarioId, status) {
-  const scenarioPath = join14(
+function syncScenarioToYaml(projectRoot, scenarioId, status, linkedTests, verification) {
+  const scenarioPath = join15(
     projectRoot,
     ".arcbridge",
     "arc42",
     "10-quality-scenarios.yaml"
   );
-  if (!existsSync7(scenarioPath)) return;
+  if (!existsSync8(scenarioPath)) return;
   const raw = readFileSync8(scenarioPath, "utf-8");
   const parsed = parse2(raw);
   const result = QualityScenariosFileSchema.safeParse(parsed);
@@ -6186,14 +6643,55 @@ function syncScenarioToYaml(projectRoot, scenarioId, status) {
   const scenario = scenariosFile.scenarios.find((s) => s.id === scenarioId);
   if (!scenario) return;
   scenario.status = status;
+  if (linkedTests) {
+    scenario.linked_tests = linkedTests;
+  }
+  if (verification) {
+    scenario.verification = verification;
+  }
   writeFileSync5(scenarioPath, stringify4(scenariosFile), "utf-8");
 }
+function deleteTaskFromYaml(projectRoot, phaseId, taskId) {
+  try {
+    const taskPath = join15(
+      projectRoot,
+      ".arcbridge",
+      "plan",
+      "tasks",
+      `${phaseId}.yaml`
+    );
+    if (!existsSync8(taskPath)) {
+      return { success: true };
+    }
+    const raw = readFileSync8(taskPath, "utf-8");
+    const result = TaskFileSchema.safeParse(parse2(raw));
+    if (!result.success) {
+      return {
+        success: false,
+        warning: `Could not parse ${phaseId}.yaml \u2014 task may reappear after reindex`
+      };
+    }
+    const taskFile = result.data;
+    const before = taskFile.tasks.length;
+    taskFile.tasks = taskFile.tasks.filter((t) => t.id !== taskId);
+    if (taskFile.tasks.length === before) {
+      return { success: true };
+    }
+    writeFileSync5(taskPath, stringify4(taskFile), "utf-8");
+    return { success: true };
+  } catch (err) {
+    return {
+      success: false,
+      warning: `YAML update failed: ${err instanceof Error ? err.message : String(err)} \u2014 task may reappear after reindex`
+    };
+  }
+}
 
 // src/sync/task-inference.ts
 function inferTaskStatuses(db, phaseId) {
   const results = [];
   const tasks = db.prepare(
-    "SELECT id, title, status, building_block, quality_scenarios, acceptance_criteria FROM tasks WHERE phase_id = ? AND status != 'done'"
+    "SELECT id, title, status, building_block, quality_scenarios, acceptance_criteria FROM tasks WHERE phase_id = ? AND status NOT IN ('done', 'cancelled')"
   ).all(phaseId);
   for (const task of tasks) {
     const inference = inferSingleTask(db, task);
@@ -6318,7 +6816,7 @@ function safeParseJson2(value, fallback) {
 
 // src/generators/sync-generator.ts
 import { mkdirSync as mkdirSync6, writeFileSync as writeFileSync6 } from "fs";
-import { join as join15, dirname as dirname3 } from "path";
+import { join as join16, dirname as dirname4 } from "path";
 
 // src/templates/sync/claude-skill.ts
 function claudeSkillTemplate(config) {
@@ -6496,21 +6994,21 @@ To enable automatic sync:
 function generateSyncFiles(targetDir, config) {
   const generated = [];
   const action = githubActionTemplate(config);
-  const actionPath = join15(targetDir, action.relativePath);
-  mkdirSync6(dirname3(actionPath), { recursive: true });
+  const actionPath = join16(targetDir, action.relativePath);
+  mkdirSync6(dirname4(actionPath), { recursive: true });
   writeFileSync6(actionPath, action.content, "utf-8");
   generated.push(action.relativePath);
   if (config.platforms.includes("claude")) {
     const skill = claudeSkillTemplate(config);
-    const skillPath = join15(targetDir, skill.relativePath);
-    mkdirSync6(dirname3(skillPath), { recursive: true });
+    const skillPath = join16(targetDir, skill.relativePath);
+    mkdirSync6(dirname4(skillPath), { recursive: true });
     writeFileSync6(skillPath, skill.content, "utf-8");
     generated.push(skill.relativePath);
   }
   if (config.platforms.includes("copilot")) {
     const hook = copilotHookTemplate(config);
-    const hookPath = join15(targetDir, hook.relativePath);
-    mkdirSync6(dirname3(hookPath), { recursive: true });
+    const hookPath = join16(targetDir, hook.relativePath);
+    mkdirSync6(dirname4(hookPath), { recursive: true });
     writeFileSync6(hookPath, hook.content, "utf-8");
     generated.push(hook.relativePath);
   }
@@ -6519,7 +7017,7 @@ function generateSyncFiles(targetDir, config) {
 
 // src/metrics/activity.ts
 import { writeFileSync as writeFileSync7, mkdirSync as mkdirSync7 } from "fs";
-import { join as join16 } from "path";
+import { join as join17 } from "path";
 function insertActivity(db, params) {
   const totalTokens = params.totalTokens ?? (params.inputTokens != null && params.outputTokens != null ? params.inputTokens + params.outputTokens : null);
   const stmt = db.prepare(`
@@ -6677,7 +7175,7 @@ function exportMetrics(db, projectRoot, format, params, maxRows = 1e5) {
   });
   const rows = result.rows;
   const timestamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-").slice(0, 19);
-  const dir = join16(projectRoot, ".arcbridge", "metrics");
+  const dir = join17(projectRoot, ".arcbridge", "metrics");
   mkdirSync7(dir, { recursive: true });
   let content;
   let filename;
@@ -6774,7 +7272,7 @@ function exportMetrics(db, projectRoot, format, params, maxRows = 1e5) {
       break;
     }
   }
-  const filePath = join16(dir, filename);
+  const filePath = join17(dir, filename);
   writeFileSync7(filePath, content, "utf-8");
   return filePath;
 }
@@ -6842,6 +7340,8 @@ function esc(val) {
 
 // src/git/helpers.ts
 import { execFileSync as execFileSync3 } from "child_process";
+import { realpathSync } from "fs";
+import { relative as relative6 } from "path";
 function resolveRef(projectRoot, since, db) {
   switch (since) {
     case "last-commit":
@@ -6866,6 +7366,7 @@ function resolveRef(projectRoot, since, db) {
   }
 }
 function getChangedFiles(projectRoot, ref) {
+  const byPath = /* @__PURE__ */ new Map();
   try {
     execFileSync3("git", ["rev-parse", "--verify", ref], {
       cwd: projectRoot,
@@ -6878,16 +7379,24 @@ function getChangedFiles(projectRoot, ref) {
       ["diff", "--name-status", "--no-renames", ref, "HEAD"],
       { cwd: projectRoot, encoding: "utf-8", timeout: 1e4 }
     ).trim();
-    if (!output) return [];
-    return output.split("\n").map((line) => {
-      const [statusCode, ...pathParts] = line.split("	");
-      const path = pathParts.join("	");
-      const status = parseStatusCode(statusCode ?? "M");
-      return { status, path };
-    });
+    if (output) {
+      for (const line of output.split("\n")) {
+        const [statusCode, ...pathParts] = line.split("	");
+        const path = pathParts.join("	");
+        byPath.set(path, { status: parseStatusCode(statusCode ?? "M"), path });
+      }
+    }
   } catch {
-    return getUncommittedChanges(projectRoot);
   }
+  for (const change of getUncommittedChanges(projectRoot)) {
+    const existing = byPath.get(change.path);
+    if (!existing) {
+      byPath.set(change.path, change);
+    } else if (change.status === "deleted") {
+      byPath.set(change.path, change);
+    }
+  }
+  return Array.from(byPath.values());
 }
 function getUncommittedChanges(projectRoot) {
   try {
@@ -6895,11 +7404,12 @@ function getUncommittedChanges(projectRoot) {
       "git",
       ["status", "--porcelain", "-uno"],
       { cwd: projectRoot, encoding: "utf-8", timeout: 5e3 }
-    ).trim();
-    if (!output) return [];
-    return output.split("\n").map((line) => {
+    );
+    const lines = output.split("\n").filter((l) => l.length >= 3);
+    if (lines.length === 0) return [];
+    return lines.map((line) => {
       const statusCode = line.slice(0, 2).trim();
-      const path = line.slice(3);
+      const path = line.slice(3).replace(/\r$/, "");
       const status = statusCode === "D" ? "deleted" : statusCode === "A" ? "added" : "modified";
       return { status, path };
     });
@@ -6923,6 +7433,33 @@ function setSyncCommit(db, key, sha) {
     "INSERT OR REPLACE INTO arcbridge_meta (key, value) VALUES (?, ?)"
   ).run(key, sha);
 }
+function getRepoRoot(projectRoot) {
+  try {
+    return execFileSync3(
+      "git",
+      ["rev-parse", "--show-toplevel"],
+      { cwd: projectRoot, encoding: "utf-8", timeout: 5e3 }
+    ).trim();
+  } catch {
+    return null;
+  }
+}
+function scopeToProject(changedFiles, projectRoot) {
+  const repoRoot = getRepoRoot(projectRoot);
+  if (!repoRoot) return changedFiles;
+  let projectRel;
+  try {
+    projectRel = relative6(realpathSync(repoRoot), realpathSync(projectRoot));
+  } catch {
+    return changedFiles;
+  }
+  if (!projectRel || projectRel === "." || projectRel.startsWith("..")) return changedFiles;
+  const prefix = projectRel.replace(/\\/g, "/");
+  return changedFiles.filter((f) => f.path.startsWith(prefix + "/") || f.path === prefix).map((f) => ({
+    ...f,
+    path: f.path.startsWith(prefix + "/") ? f.path.slice(prefix.length + 1) : f.path
+  }));
+}
 function parseStatusCode(code) {
   switch (code.charAt(0)) {
     case "A":
@@ -6938,7 +7475,7 @@ function parseStatusCode(code) {
 
 // src/testing/runner.ts
 import { execFileSync as execFileSync4 } from "child_process";
-import { existsSync as existsSync8 } from "fs";
+import { existsSync as existsSync9 } from "fs";
 import { resolve as resolve3 } from "path";
 function verifyScenarios(db, projectRoot, options) {
   const results = [];
@@ -6976,7 +7513,7 @@ function verifyScenarios(db, projectRoot, options) {
     }
     if (testPaths.length === 0) continue;
     const missingPaths = testPaths.filter(
-      (tp) => !existsSync8(resolve3(projectRoot, tp))
+      (tp) => !existsSync9(resolve3(projectRoot, tp))
     );
     if (missingPaths.length === testPaths.length) {
       results.push({
@@ -6991,7 +7528,7 @@ function verifyScenarios(db, projectRoot, options) {
       continue;
     }
     const existingPaths = testPaths.filter(
-      (tp) => existsSync8(resolve3(projectRoot, tp))
+      (tp) => existsSync9(resolve3(projectRoot, tp))
     );
     const start = Date.now();
     let passed;
@@ -7045,21 +7582,21 @@ ${output}`;
 }
 
 // src/roles/loader.ts
-import { readdirSync as readdirSync5, readFileSync as readFileSync9 } from "fs";
-import { join as join17 } from "path";
+import { readdirSync as readdirSync6, readFileSync as readFileSync9 } from "fs";
+import { join as join18 } from "path";
 import matter4 from "gray-matter";
 function loadRoles(projectRoot) {
-  const agentsDir = join17(projectRoot, ".arcbridge", "agents");
+  const agentsDir = join18(projectRoot, ".arcbridge", "agents");
   const roles = [];
   const errors = [];
   let files;
   try {
-    files = readdirSync5(agentsDir).filter((f) => f.endsWith(".md")).sort();
+    files = readdirSync6(agentsDir).filter((f) => f.endsWith(".md")).sort();
   } catch {
     return { roles: [], errors: [`Agent directory not found: ${agentsDir}`] };
   }
   for (const file of files) {
-    const filePath = join17(agentsDir, file);
+    const filePath = join18(agentsDir, file);
     try {
       const raw = readFileSync9(filePath, "utf-8");
       const parsed = matter4(raw);
@@ -7086,7 +7623,7 @@ function loadRole(projectRoot, roleId) {
   if (!/^[a-z0-9-]+$/.test(roleId)) {
     return { role: null, error: `Invalid role ID: "${roleId}" (must be kebab-case)` };
   }
-  const filePath = join17(projectRoot, ".arcbridge", "agents", `${roleId}.md`);
+  const filePath = join18(projectRoot, ".arcbridge", "agents", `${roleId}.md`);
   try {
     const raw = readFileSync9(filePath, "utf-8");
     const parsed = matter4(raw);
@@ -7125,6 +7662,7 @@ export {
   TaskSchema,
   addTaskToYaml,
   applyInferences,
+  deleteTaskFromYaml,
   detectDrift,
   detectProjectLanguage,
   discoverDotnetServices,
@@ -7153,6 +7691,7 @@ export {
   queryMetrics,
   refreshFromDocs,
   resolveRef,
+  scopeToProject,
   setSyncCommit,
   suppressSqliteWarning,
   syncPhaseToYaml,