@arcbridge/mcp-server 0.2.0 → 0.3.0

package/dist/index.js

@@ -189,15 +189,17 @@ Use \`arcbridge_get_project_status\` to see the current state.`
           ...allWarnings.map((w) => `- ${w}`)
         ] : [],
         "",
-        "## Next Steps \u2014 PLAN FIRST, BUILD SECOND",
+        "## Next Steps \u2014 TAILOR FIRST, BUILD SECOND",
         "",
-        "**Do not start implementing yet.** First plan the full project roadmap:",
+        "**Do not start implementing yet.** The generated building blocks, quality scenarios, and phase tasks are a generic starting template. Tailor them to this project first:",
         "",
         "1. **Activate the architect role** \u2014 run `arcbridge_activate_role` with role `architect`",
         "2. **Review the spec** \u2014 read `.arcbridge/spec.md` (if provided) and understand the full scope",
-        "3. **Review and adapt the phase plan** \u2014 run `arcbridge_get_phase_plan`. The 4 generated phases are a starting template. For larger projects, add more phases by editing `.arcbridge/plan/phases.yaml` and running `arcbridge_reindex`.",
-        "4. **Plan real tasks for ALL phases** \u2014 Phase 0-1 tasks are ready to use. Phase 2+ tasks are examples only \u2014 replace them with real tasks from the project's requirements using `arcbridge_create_task`.",
-        "5. **Only then start building** \u2014 use `arcbridge_get_current_tasks` to see what to do next",
+        "3. **Tailor building blocks** \u2014 edit `.arcbridge/arc42/05-building-blocks.md`: delete blocks that don't apply, add blocks for your real modules, and declare `interfaces` between blocks (drift detection depends on this)",
+        "4. **Tailor quality scenarios** \u2014 edit `.arcbridge/arc42/10-quality-scenarios.yaml`: delete irrelevant scenarios, add ones that match your actual requirements",
+        "5. **Tailor phase tasks** \u2014 Phase 0-1 tasks are ready to use. Phase 2+ tasks are examples only \u2014 **delete them** (edit `.arcbridge/plan/tasks/<phase>.yaml` or use `arcbridge_delete_task`) and create real tasks from the project's requirements using `arcbridge_create_task`. Add more phases with `arcbridge_create_phase` if needed.",
+        "6. **Reindex** \u2014 run `arcbridge_reindex` to pick up your changes",
+        "7. **Then start building** \u2014 use `arcbridge_get_current_tasks` to see what to do next",
         "",
         "Use `arcbridge_get_project_status` to see the full project status."
       ];
@@ -754,7 +756,7 @@ import { refreshFromDocs as refreshFromDocs3 } from "@arcbridge/core";
 function registerGetCurrentTasks(server, ctx) {
   server.tool(
     "arcbridge_get_current_tasks",
-    "Get tasks for the current in-progress phase, with their building blocks, quality scenarios, and acceptance criteria.",
+    "Get tasks for the current phase (in-progress, or first planned if none is in-progress), with their building blocks, quality scenarios, and acceptance criteria.",
     {
       target_dir: z7.string().describe("Absolute path to the project directory"),
       status: z7.enum(["todo", "in-progress", "done", "blocked"]).optional().describe("Filter tasks by status")
@@ -763,15 +765,20 @@ function registerGetCurrentTasks(server, ctx) {
       const db = ensureDb(ctx, params.target_dir);
       if (!db) return notInitialized();
       refreshFromDocs3(db, params.target_dir);
-      const currentPhase = db.prepare(
+      let currentPhase = db.prepare(
         "SELECT id, name FROM phases WHERE status = 'in-progress' ORDER BY phase_number LIMIT 1"
       ).get();
+      if (!currentPhase) {
+        currentPhase = db.prepare(
+          "SELECT id, name FROM phases WHERE status = 'planned' ORDER BY phase_number LIMIT 1"
+        ).get();
+      }
       if (!currentPhase) {
         return {
           content: [
             {
               type: "text",
-              text: "No phase is currently in-progress. Use `arcbridge_get_phase_plan` to see all phases."
+              text: "No active or planned phases found. Use `arcbridge_get_phase_plan` to see all phases."
             }
           ]
         };
@@ -1073,40 +1080,62 @@ If you need a new block, add it to \`.arcbridge/arc42/05-building-blocks.md\` an
 
 // src/tools/delete-task.ts
 import { z as z10 } from "zod";
-import { deleteTaskFromYaml } from "@arcbridge/core";
+import { deleteTaskFromYaml, refreshFromDocs as refreshFromDocs4 } from "@arcbridge/core";
 function registerDeleteTask(server, ctx) {
   server.tool(
     "arcbridge_delete_task",
-    "Delete a task permanently. Use this to remove example/template tasks or duplicates. For tasks that were planned but are no longer relevant, prefer `arcbridge_update_task` with status 'cancelled' instead \u2014 this preserves the decision trail.",
+    "Delete one or more tasks permanently. Use this to remove example/template tasks or duplicates. Pass task_ids (array) for batch deletion, or task_id (string) for a single task. For tasks that were planned but are no longer relevant, prefer `arcbridge_update_task` with status 'cancelled' instead \u2014 this preserves the decision trail.",
     {
       target_dir: z10.string().describe("Absolute path to the project directory"),
-      task_id: z10.string().describe("Task ID to delete")
+      task_id: z10.string().optional().describe("Single task ID to delete (deprecated \u2014 use task_ids)"),
+      task_ids: z10.array(z10.string()).optional().describe("Task IDs to delete (preferred)")
     },
     async (params) => {
       const db = ensureDb(ctx, params.target_dir);
       if (!db) return notInitialized();
-      const task = db.prepare("SELECT id, title, phase_id FROM tasks WHERE id = ?").get(params.task_id);
-      if (!task) {
-        return textResult(
-          `Task '${params.task_id}' not found. Use \`arcbridge_get_current_tasks\` to see available tasks.`
-        );
+      const ids = params.task_ids ?? (params.task_id ? [params.task_id] : []);
+      if (ids.length === 0) {
+        return textResult("Provide `task_ids` (array) or `task_id` (string) to delete.");
+      }
+      const results = [];
+      const warnings = [];
+      for (const id of ids) {
+        const task = db.prepare("SELECT id, title, phase_id FROM tasks WHERE id = ?").get(id);
+        if (!task) {
+          warnings.push(`Task '${id}' not found \u2014 skipped`);
+          continue;
+        }
+        const yamlResult = deleteTaskFromYaml(params.target_dir, task.phase_id, id);
+        if (yamlResult.success === false) {
+          warnings.push(`${task.id}: ${yamlResult.warning ?? "YAML delete failed"}`);
+        } else {
+          results.push(`- **${task.id}**: "${task.title}"`);
+          if (yamlResult.warning) {
+            warnings.push(`${task.id}: ${yamlResult.warning}`);
+          }
+        }
       }
-      const yamlResult = deleteTaskFromYaml(params.target_dir, task.phase_id, params.task_id);
-      db.prepare("DELETE FROM tasks WHERE id = ?").run(params.task_id);
-      const msg = `Task **${task.id}** deleted: "${task.title}"`;
-      if (yamlResult.warning) {
-        return textResult(`${msg}
-
-**Warning:** ${yamlResult.warning}`);
+      if (results.length > 0) {
+        refreshFromDocs4(db, params.target_dir);
+      }
+      const lines = [];
+      if (results.length > 0) {
+        lines.push(`Deleted ${results.length} task${results.length === 1 ? "" : "s"}:`, "", ...results);
+      }
+      if (warnings.length > 0) {
+        lines.push("", "**Warnings:**", ...warnings.map((w) => `- ${w}`));
+      }
+      if (results.length === 0 && warnings.length > 0) {
+        lines.unshift("No tasks were deleted.");
       }
-      return textResult(msg);
+      return textResult(lines.join("\n"));
     }
   );
 }
 
 // src/tools/create-phase.ts
 import { z as z11 } from "zod";
-import { addPhaseToYaml, refreshFromDocs as refreshFromDocs4 } from "@arcbridge/core";
+import { addPhaseToYaml, refreshFromDocs as refreshFromDocs5 } from "@arcbridge/core";
 function registerCreatePhase(server, ctx) {
   server.tool(
     "arcbridge_create_phase",
@@ -1121,7 +1150,7 @@ function registerCreatePhase(server, ctx) {
     async (params) => {
       const db = ensureDb(ctx, params.target_dir);
       if (!db) return notInitialized();
-      refreshFromDocs4(db, params.target_dir);
+      refreshFromDocs5(db, params.target_dir);
       const maxPhase = db.prepare("SELECT MAX(phase_number) as max FROM phases").get();
       const phaseNumber = params.phase_number ?? (maxPhase.max ?? -1) + 1;
       const existing = db.prepare("SELECT id FROM phases WHERE phase_number = ?").get(phaseNumber);
@@ -1144,7 +1173,7 @@ function registerCreatePhase(server, ctx) {
           `Failed to create phase: ${yamlResult.warning ?? "YAML update failed"}`
         );
       }
-      refreshFromDocs4(db, params.target_dir);
+      refreshFromDocs5(db, params.target_dir);
       const lines = [
         `Phase created: **${phaseId}**`,
         "",
@@ -1168,16 +1197,60 @@ function registerCreatePhase(server, ctx) {
   );
 }
 
-// src/tools/get-relevant-adrs.ts
+// src/tools/delete-phase.ts
 import { z as z12 } from "zod";
+import { deletePhaseFromYaml, refreshFromDocs as refreshFromDocs6 } from "@arcbridge/core";
+function registerDeletePhase(server, ctx) {
+  server.tool(
+    "arcbridge_delete_phase",
+    "Delete a phase and all its tasks permanently. Use this to remove template phases that don't apply to this project. Phases with status 'in-progress' or 'done' cannot be deleted \u2014 change their status first if you really need to remove them.",
+    {
+      target_dir: z12.string().describe("Absolute path to the project directory"),
+      phase_id: z12.string().describe("Phase ID to delete")
+    },
+    async (params) => {
+      const db = ensureDb(ctx, params.target_dir);
+      if (!db) return notInitialized();
+      const phase = db.prepare("SELECT id, name, phase_number, status FROM phases WHERE id = ?").get(params.phase_id);
+      if (!phase) {
+        return textResult(
+          `Phase '${params.phase_id}' not found. Use \`arcbridge_get_phase_plan\` to see available phases.`
+        );
+      }
+      if (phase.status !== "planned") {
+        return textResult(
+          `Cannot delete phase **${phase.id}** (status: ${phase.status}). Only phases with status 'planned' can be deleted.`
+        );
+      }
+      const taskCount = db.prepare("SELECT COUNT(*) as count FROM tasks WHERE phase_id = ?").get(params.phase_id);
+      const yamlResult = deletePhaseFromYaml(params.target_dir, params.phase_id);
+      if (!yamlResult.success) {
+        return textResult(
+          `Failed to delete phase: ${yamlResult.warning ?? "Unknown error"}`
+        );
+      }
+      refreshFromDocs6(db, params.target_dir);
+      const lines = [
+        `Phase **${phase.id}** deleted: "${phase.name}" (phase ${phase.phase_number})`
+      ];
+      if (taskCount.count > 0) {
+        lines.push(`${taskCount.count} task${taskCount.count === 1 ? "" : "s"} removed.`);
+      }
+      return textResult(lines.join("\n"));
+    }
+  );
+}
+
+// src/tools/get-relevant-adrs.ts
+import { z as z13 } from "zod";
 function registerGetRelevantAdrs(server, ctx) {
   server.tool(
     "arcbridge_get_relevant_adrs",
     "Get architectural decision records (ADRs) relevant to a specific file path or building block.",
     {
-      target_dir: z12.string().describe("Absolute path to the project directory"),
-      file_path: z12.string().optional().describe("File path to find relevant ADRs for"),
-      building_block: z12.string().optional().describe("Building block ID to find relevant ADRs for")
+      target_dir: z13.string().describe("Absolute path to the project directory"),
+      file_path: z13.string().optional().describe("File path to find relevant ADRs for"),
+      building_block: z13.string().optional().describe("Building block ID to find relevant ADRs for")
     },
     async (params) => {
       const db = ensureDb(ctx, params.target_dir);
@@ -1261,24 +1334,24 @@ function formatAdrs(adrs, title) {
 }
 
 // src/tools/reindex.ts
-import { z as z13 } from "zod";
-import { indexProject as indexProject2, refreshFromDocs as refreshFromDocs5 } from "@arcbridge/core";
+import { z as z14 } from "zod";
+import { indexProject as indexProject2, refreshFromDocs as refreshFromDocs7 } from "@arcbridge/core";
 function registerReindex(server, ctx) {
   server.tool(
     "arcbridge_reindex",
     "Re-index the project: refreshes architecture docs from arc42/YAML files, then reindexes code symbols (TypeScript & C#/.NET). This is the first step of the sync pipeline \u2014 use it to pick up manual doc edits and code changes.",
     {
-      target_dir: z13.string().describe("Absolute path to the project directory"),
-      tsconfig_path: z13.string().optional().describe("Override tsconfig.json path (default: auto-detect). Only used for TypeScript projects."),
-      service: z13.string().optional().describe("Service name for monorepo projects (default: 'main')"),
-      language: z13.enum(["typescript", "csharp", "auto"]).optional().describe("Project language. 'auto' detects from project files (default: 'auto')")
+      target_dir: z14.string().describe("Absolute path to the project directory"),
+      tsconfig_path: z14.string().optional().describe("Override tsconfig.json path (default: auto-detect). Only used for TypeScript projects."),
+      service: z14.string().optional().describe("Service name for monorepo projects (default: 'main')"),
+      language: z14.enum(["typescript", "csharp", "auto"]).optional().describe("Project language. 'auto' detects from project files (default: 'auto')")
     },
     async (params) => {
       const start = Date.now();
       const db = ensureDb(ctx, params.target_dir);
       if (!db) return notInitialized();
       try {
-        const docWarnings = refreshFromDocs5(db, params.target_dir);
+        const docWarnings = refreshFromDocs7(db, params.target_dir);
         const result = await indexProject2(db, {
           projectRoot: params.target_dir,
           tsconfigPath: params.tsconfig_path,
@@ -1317,16 +1390,16 @@ function registerReindex(server, ctx) {
 }
 
 // src/tools/search-symbols.ts
-import { z as z14 } from "zod";
+import { z as z15 } from "zod";
 function registerSearchSymbols(server, ctx) {
   server.tool(
     "arcbridge_search_symbols",
     "Search code symbols by name, kind, file path, or building block. Supports TypeScript and C#. Returns matching symbols with type signatures.",
     {
-      target_dir: z14.string().describe("Absolute path to the project directory"),
-      query: z14.string().optional().describe("Search term to match against symbol names"),
-      service: z14.string().optional().describe("Filter by service name (for multi-project solutions). Omit to search all services."),
-      kind: z14.enum([
+      target_dir: z15.string().describe("Absolute path to the project directory"),
+      query: z15.string().optional().describe("Search term to match against symbol names"),
+      service: z15.string().optional().describe("Filter by service name (for multi-project solutions). Omit to search all services."),
+      kind: z15.enum([
         "function",
         "class",
         "type",
@@ -1338,10 +1411,10 @@ function registerSearchSymbols(server, ctx) {
         "hook",
         "context"
       ]).optional().describe("Filter by symbol kind"),
-      file_path: z14.string().optional().describe("Filter by file path (prefix match)"),
-      is_exported: z14.boolean().optional().describe("Filter by export status"),
-      building_block: z14.string().optional().describe("Filter by building block ID (matches against code_paths)"),
-      limit: z14.number().int().min(1).max(200).default(50).describe("Maximum results to return (default: 50)")
+      file_path: z15.string().optional().describe("Filter by file path (prefix match)"),
+      is_exported: z15.boolean().optional().describe("Filter by export status"),
+      building_block: z15.string().optional().describe("Filter by building block ID (matches against code_paths)"),
+      limit: z15.number().int().min(1).max(200).default(50).describe("Maximum results to return (default: 50)")
     },
     async (params) => {
       const db = ensureDb(ctx, params.target_dir);
@@ -1428,7 +1501,7 @@ function registerSearchSymbols(server, ctx) {
 }
 
 // src/tools/get-symbol.ts
-import { z as z15 } from "zod";
+import { z as z16 } from "zod";
 import { readFileSync, existsSync as existsSync3 } from "fs";
 import { join as join3 } from "path";
 function registerGetSymbol(server, ctx) {
@@ -1436,11 +1509,11 @@ function registerGetSymbol(server, ctx) {
     "arcbridge_get_symbol",
     "Get detailed information about a specific TypeScript symbol including its source code, type signature, and relationships.",
     {
-      target_dir: z15.string().describe("Absolute path to the project directory"),
-      symbol_id: z15.string().describe(
+      target_dir: z16.string().describe("Absolute path to the project directory"),
+      symbol_id: z16.string().describe(
         "Symbol ID (e.g. 'src/utils.ts::formatName#function')"
       ),
-      include_source: z15.boolean().default(true).describe("Include source code snippet (default: true)")
+      include_source: z16.boolean().default(true).describe("Include source code snippet (default: true)")
     },
     async (params) => {
       const db = ensureDb(ctx, params.target_dir);
@@ -1538,21 +1611,21 @@ Use \`arcbridge_search_symbols\` to find symbols by name.`
 }
 
 // src/tools/get-dependency-graph.ts
-import { z as z16 } from "zod";
+import { z as z17 } from "zod";
 function registerGetDependencyGraph(server, ctx) {
   server.tool(
     "arcbridge_get_dependency_graph",
     "Get the dependency graph for a module or file. Shows imports, calls, type usage, and inheritance relationships between symbols.",
     {
-      target_dir: z16.string().describe("Absolute path to the project directory"),
-      module: z16.string().describe(
+      target_dir: z17.string().describe("Absolute path to the project directory"),
+      module: z17.string().describe(
         "Module path relative to project root (e.g. 'src/lib/auth')"
       ),
-      direction: z16.enum(["dependencies", "dependents", "both"]).default("both").describe(
+      direction: z17.enum(["dependencies", "dependents", "both"]).default("both").describe(
         "Graph direction: 'dependencies' (what this module uses), 'dependents' (what uses this module), or 'both'"
       ),
-      depth: z16.number().int().min(1).max(5).default(1).describe("How many levels to traverse (default: 1, max: 5)"),
-      service: z16.string().optional().describe("Filter by service name (for multi-project solutions). Omit to search all services.")
+      depth: z17.number().int().min(1).max(5).default(1).describe("How many levels to traverse (default: 1, max: 5)"),
+      service: z17.string().optional().describe("Filter by service name (for multi-project solutions). Omit to search all services.")
     },
     async (params) => {
       const maybeDb = ensureDb(ctx, params.target_dir);
@@ -1699,16 +1772,16 @@ function formatEdges(edges, modulePath, direction) {
 }
 
 // src/tools/get-component-graph.ts
-import { z as z17 } from "zod";
+import { z as z18 } from "zod";
 function registerGetComponentGraph(server, ctx) {
   server.tool(
     "arcbridge_get_component_graph",
     "Get the React component graph: component hierarchy, props, state, context usage, and server/client boundaries.",
     {
-      target_dir: z17.string().describe("Absolute path to the project directory"),
-      file_path: z17.string().optional().describe("Filter to components in a specific file or directory prefix"),
-      client_only: z17.boolean().optional().describe("Only show client components ('use client')"),
-      with_state: z17.boolean().optional().describe("Only show components that use state (useState/useReducer)")
+      target_dir: z18.string().describe("Absolute path to the project directory"),
+      file_path: z18.string().optional().describe("Filter to components in a specific file or directory prefix"),
+      client_only: z18.boolean().optional().describe("Only show client components ('use client')"),
+      with_state: z18.boolean().optional().describe("Only show components that use state (useState/useReducer)")
     },
     async (params) => {
       const db = ensureDb(ctx, params.target_dir);
@@ -1812,16 +1885,16 @@ function registerGetComponentGraph(server, ctx) {
 }
 
 // src/tools/get-route-map.ts
-import { z as z18 } from "zod";
+import { z as z19 } from "zod";
 function registerGetRouteMap(server, ctx) {
   server.tool(
     "arcbridge_get_route_map",
     "Get the route map: pages, layouts, API routes, and their hierarchy. Works with Next.js, ASP.NET controllers, and minimal APIs.",
     {
-      target_dir: z18.string().describe("Absolute path to the project directory"),
-      kind: z18.enum(["page", "layout", "loading", "error", "not-found", "api-route", "middleware"]).optional().describe("Filter by route kind"),
-      route_prefix: z18.string().optional().describe("Filter by route path prefix (e.g. '/dashboard' or '/api/orders')"),
-      service: z18.string().optional().describe("Filter by service name (for multi-project solutions). Omit to show all services.")
+      target_dir: z19.string().describe("Absolute path to the project directory"),
+      kind: z19.enum(["page", "layout", "loading", "error", "not-found", "api-route", "middleware"]).optional().describe("Filter by route kind"),
+      route_prefix: z19.string().optional().describe("Filter by route path prefix (e.g. '/dashboard' or '/api/orders')"),
+      service: z19.string().optional().describe("Filter by service name (for multi-project solutions). Omit to show all services.")
     },
     async (params) => {
       const db = ensureDb(ctx, params.target_dir);
@@ -1897,13 +1970,13 @@ function registerGetRouteMap(server, ctx) {
 }
 
 // src/tools/get-boundary-analysis.ts
-import { z as z19 } from "zod";
+import { z as z20 } from "zod";
 function registerGetBoundaryAnalysis(server, ctx) {
   server.tool(
     "arcbridge_get_boundary_analysis",
     "Analyze server/client boundaries in a Next.js project. Identifies client components, server components, server actions, and potential boundary violations.",
     {
-      target_dir: z19.string().describe("Absolute path to the project directory")
+      target_dir: z20.string().describe("Absolute path to the project directory")
     },
     async (params) => {
       const db = ensureDb(ctx, params.target_dir);
@@ -2007,15 +2080,15 @@ function registerGetBoundaryAnalysis(server, ctx) {
 }
 
 // src/tools/check-drift.ts
-import { z as z20 } from "zod";
+import { z as z21 } from "zod";
 import { detectDrift, writeDriftLog } from "@arcbridge/core";
 function registerCheckDrift(server, ctx) {
   server.tool(
     "arcbridge_check_drift",
     "Detect architecture drift: undocumented modules, missing code paths, cross-block dependency violations, and stale ADR references.",
     {
-      target_dir: z20.string().describe("Absolute path to the project directory"),
-      persist: z20.boolean().default(true).describe("Write findings to drift_log table (default: true)")
+      target_dir: z21.string().describe("Absolute path to the project directory"),
+      persist: z21.boolean().default(true).describe("Write findings to drift_log table (default: true)")
     },
     async (params) => {
       const start = Date.now();
@@ -2087,16 +2160,16 @@ function registerCheckDrift(server, ctx) {
 }
 
 // src/tools/get-guidance.ts
-import { z as z21 } from "zod";
+import { z as z22 } from "zod";
 import { loadConfig as loadConfig3 } from "@arcbridge/core";
 function registerGetGuidance(server, ctx) {
   server.tool(
     "arcbridge_get_guidance",
     "Get context-aware architectural guidance for a code change. Surfaces relevant quality scenarios, patterns, constraints, and questions to consider.",
     {
-      target_dir: z21.string().describe("Absolute path to the project directory"),
-      file_path: z21.string().optional().describe("File path you're working on (to determine building block and context)"),
-      action: z21.enum([
+      target_dir: z22.string().describe("Absolute path to the project directory"),
+      file_path: z22.string().optional().describe("File path you're working on (to determine building block and context)"),
+      action: z22.enum([
         "adding-component",
         "adding-api-route",
         "adding-hook",
@@ -2294,14 +2367,14 @@ function getActionGuidance(action, projectType) {
 }
 
 // src/tools/get-open-questions.ts
-import { z as z22 } from "zod";
+import { z as z23 } from "zod";
 function registerGetOpenQuestions(server, ctx) {
   server.tool(
     "arcbridge_get_open_questions",
     "Surface architectural gaps: untested quality scenarios, building blocks without boundaries, unresolved drift, and tasks missing acceptance criteria.",
     {
-      target_dir: z22.string().describe("Absolute path to the project directory"),
-      scope: z22.string().optional().describe("Focus scope: 'current-phase', 'building-block:<id>', or omit for project-wide")
+      target_dir: z23.string().describe("Absolute path to the project directory"),
+      scope: z23.string().optional().describe("Focus scope: 'current-phase', 'building-block:<id>', or omit for project-wide")
     },
     async (params) => {
       const db = ensureDb(ctx, params.target_dir);
@@ -2411,7 +2484,7 @@ function registerGetOpenQuestions(server, ctx) {
 }
 
 // src/tools/propose-arc42-update.ts
-import { z as z23 } from "zod";
+import { z as z24 } from "zod";
 import {
   resolveRef,
   getChangedFiles,
@@ -2423,9 +2496,9 @@ function registerProposeArc42Update(server, ctx) {
     "arcbridge_propose_arc42_update",
     "Analyze code changes since a reference point and generate specific, actionable proposals for updating arc42 documentation.",
     {
-      target_dir: z23.string().describe("Absolute path to the project directory"),
-      changes_since: z23.string().default("last-sync").describe("Reference point: 'last-commit', 'last-sync', 'last-phase', or a git ref"),
-      update_sync_point: z23.boolean().default(false).describe("Update the stored sync commit to HEAD after generating proposals")
+      target_dir: z24.string().describe("Absolute path to the project directory"),
+      changes_since: z24.string().default("last-sync").describe("Reference point: 'last-commit', 'last-sync', 'last-phase', or a git ref"),
+      update_sync_point: z24.boolean().default(false).describe("Update the stored sync commit to HEAD after generating proposals")
     },
     async (params) => {
       const db = ensureDb(ctx, params.target_dir);
@@ -2613,7 +2686,7 @@ function findCrossBlockConsumers(db, symbolId, sourceBlockId, blocks) {
 }
 
 // src/tools/get-practice-review.ts
-import { z as z24 } from "zod";
+import { z as z25 } from "zod";
 import {
   resolveRef as resolveRef2,
   getChangedFiles as getChangedFiles2,
@@ -2625,8 +2698,8 @@ function registerGetPracticeReview(server, ctx) {
     "arcbridge_get_practice_review",
     "Structured, practice-aware review of recent code changes across 5 dimensions: Architecture, Security, Testing, Documentation, and Complexity.",
     {
-      target_dir: z24.string().describe("Absolute path to the project directory"),
-      since: z24.string().default("last-commit").describe("Reference point: 'last-commit', 'last-session', or 'last-phase'")
+      target_dir: z25.string().describe("Absolute path to the project directory"),
+      since: z25.string().default("last-commit").describe("Reference point: 'last-commit', 'last-session', or 'last-phase'")
     },
     async (params) => {
       const db = ensureDb(ctx, params.target_dir);
@@ -2942,7 +3015,7 @@ function reviewComplexity(db, changedFiles, findings) {
 }
 
 // src/tools/complete-phase.ts
-import { z as z25 } from "zod";
+import { z as z26 } from "zod";
 import {
   detectDrift as detectDrift3,
   writeDriftLog as writeDriftLog2,
@@ -2952,7 +3025,7 @@ import {
   applyInferences,
   verifyScenarios,
   loadConfig as loadConfig4,
-  refreshFromDocs as refreshFromDocs6,
+  refreshFromDocs as refreshFromDocs8,
   syncPhaseToYaml,
   transaction
 } from "@arcbridge/core";
@@ -2961,17 +3034,17 @@ function registerCompletePhase(server, ctx) {
     "arcbridge_complete_phase",
     "Attempt to complete a phase by validating all gates: tasks done, no critical drift, quality scenarios passing. Transitions the phase to 'complete' if all gates pass.",
     {
-      target_dir: z25.string().describe("Absolute path to the project directory"),
-      phase_id: z25.string().optional().describe("Phase ID to complete (defaults to current in-progress phase)"),
-      notes: z25.string().optional().describe("Optional notes about this phase completion"),
-      auto_infer: z25.boolean().default(true).describe("Automatically infer task statuses from code state before checking gates"),
-      run_tests: z25.boolean().default(false).describe("Run linked tests for quality scenarios before checking the quality gate")
+      target_dir: z26.string().describe("Absolute path to the project directory"),
+      phase_id: z26.string().optional().describe("Phase ID to complete (defaults to current in-progress phase)"),
+      notes: z26.string().optional().describe("Optional notes about this phase completion"),
+      auto_infer: z26.boolean().default(true).describe("Automatically infer task statuses from code state before checking gates"),
+      run_tests: z26.boolean().default(false).describe("Run linked tests for quality scenarios before checking the quality gate")
     },
     async (params) => {
       const start = Date.now();
       const db = ensureDb(ctx, params.target_dir);
       if (!db) return notInitialized();
-      refreshFromDocs6(db, params.target_dir);
+      refreshFromDocs8(db, params.target_dir);
       let phase;
       if (params.phase_id) {
         phase = db.prepare("SELECT id, name, phase_number, status, gate_status FROM phases WHERE id = ?").get(params.phase_id);
@@ -3180,18 +3253,18 @@ function registerCompletePhase(server, ctx) {
 }
 
 // src/tools/activate-role.ts
-import { z as z26 } from "zod";
+import { z as z27 } from "zod";
 import { loadRole, loadRoles } from "@arcbridge/core";
 function registerActivateRole(server, ctx) {
   server.tool(
     "arcbridge_activate_role",
     "Activate an agent role: loads the role's system prompt, required tools, quality focus, and pre-loaded architectural context.",
     {
-      target_dir: z26.string().describe("Absolute path to the project directory"),
-      role: z26.string().describe(
+      target_dir: z27.string().describe("Absolute path to the project directory"),
+      role: z27.string().describe(
         "Role ID to activate (e.g., 'architect', 'implementer', 'security-reviewer')"
       ),
-      building_block: z26.string().optional().describe("Focus on a specific building block (for implementer/code-reviewer roles)")
+      building_block: z27.string().optional().describe("Focus on a specific building block (for implementer/code-reviewer roles)")
     },
     async (params) => {
       const db = ensureDb(ctx, params.target_dir);
@@ -3493,18 +3566,18 @@ function getRoleDefinition(roleId) {
 }
 
 // src/tools/verify-scenarios.ts
-import { z as z27 } from "zod";
+import { z as z28 } from "zod";
 import { verifyScenarios as verifyScenarios2, loadConfig as loadConfig5 } from "@arcbridge/core";
 function registerVerifyScenarios(server, ctx) {
   server.tool(
     "arcbridge_verify_scenarios",
     "Run linked tests for quality scenarios and update their pass/fail status. Only runs scenarios with verification='automatic' or 'semi-automatic' and non-empty linked_tests.",
     {
-      target_dir: z27.string().describe("Absolute path to the project directory"),
-      scenario_ids: z27.array(z27.string()).optional().describe(
+      target_dir: z28.string().describe("Absolute path to the project directory"),
+      scenario_ids: z28.array(z28.string()).optional().describe(
         "Specific scenario IDs to verify (e.g., ['SEC-01', 'PERF-01']). If omitted, verifies all automatic scenarios."
       ),
-      test_command: z27.string().optional().describe(
+      test_command: z28.string().optional().describe(
         "Override the test command from config (e.g., 'npx jest'). File paths are appended as arguments."
       )
     },
@@ -3571,7 +3644,7 @@ function registerVerifyScenarios(server, ctx) {
 }
 
 // src/tools/run-role-check.ts
-import { z as z28 } from "zod";
+import { z as z29 } from "zod";
 import {
   loadRole as loadRole2,
   loadRoles as loadRoles2,
@@ -3586,11 +3659,11 @@ function registerRunRoleCheck(server, ctx) {
     "arcbridge_run_role_check",
     "Run a role-specific architectural analysis: resolves the role and executes relevant checks (drift, quality scenarios, boundaries, changed files) based on the role's focus areas.",
     {
-      target_dir: z28.string().describe("Absolute path to the project directory"),
-      role: z28.string().describe(
+      target_dir: z29.string().describe("Absolute path to the project directory"),
+      role: z29.string().describe(
         "Role ID to run checks for (e.g., 'security-reviewer', 'quality-guardian', 'architect', 'phase-manager', 'code-reviewer')"
       ),
-      scope: z28.enum(SCOPE_VALUES).default("current-phase").describe(
+      scope: z29.enum(SCOPE_VALUES).default("current-phase").describe(
         "Scope of analysis: 'last-commit' (recent changes), 'current-phase' (since phase start), 'full-project' (everything)"
       )
     },
@@ -4011,17 +4084,17 @@ function runCustomRoleCheck(db, lines, roleDef) {
 }
 
 // src/tools/update-scenario-status.ts
-import { z as z29 } from "zod";
+import { z as z30 } from "zod";
 import { syncScenarioToYaml, transaction as transaction2 } from "@arcbridge/core";
 function registerUpdateScenarioStatus(server, ctx) {
   server.tool(
     "arcbridge_update_scenario_status",
     "Update a quality scenario's status and optionally link test files. Use this to mark scenarios as passing/failing after manual verification, or to link test files so `arcbridge_verify_scenarios` can run them automatically.",
     {
-      target_dir: z29.string().describe("Absolute path to the project directory"),
-      scenario_id: z29.string().describe("Quality scenario ID (e.g., 'SEC-01', 'PERF-01')"),
-      status: z29.enum(["passing", "failing", "untested", "partial"]).describe("New status for the scenario"),
-      linked_tests: z29.array(z29.string()).optional().describe(
+      target_dir: z30.string().describe("Absolute path to the project directory"),
+      scenario_id: z30.string().describe("Quality scenario ID (e.g., 'SEC-01', 'PERF-01')"),
+      status: z30.enum(["passing", "failing", "untested", "partial"]).describe("New status for the scenario"),
+      linked_tests: z30.array(z30.string()).optional().describe(
         "Test file paths to link to this scenario (e.g., ['src/__tests__/auth.test.ts']). Once linked, `arcbridge_verify_scenarios` can run them automatically. Also sets verification to 'semi-automatic' if currently 'manual'."
       )
     },
@@ -4102,33 +4175,33 @@ ${invalid.map((p) => `  - ${p}`).join("\n")}`
 }
 
 // src/tools/record-activity.ts
-import { z as z30 } from "zod";
+import { z as z31 } from "zod";
 import { insertActivity as insertActivity2, getSessionTotals } from "@arcbridge/core";
 function registerRecordActivity(server, ctx) {
   server.tool(
     "arcbridge_record_activity",
     "Record agent activity \u2014 model, tokens, cost, duration, and optional quality snapshot. Use this to track what work was done and measure agent performance.",
     {
-      target_dir: z30.string().describe("Absolute path to the project directory"),
-      tool_name: z30.string().describe("Name of the tool or action performed (e.g., 'arcbridge_update_task', 'code_edit')"),
-      action: z30.string().optional().describe("Human-readable label (e.g., 'implement login form')"),
-      model: z30.string().optional().describe("Model identifier (e.g., 'claude-sonnet-4-20250514')"),
-      agent_role: z30.string().optional().describe("Active ArcBridge role (e.g., 'implementer')"),
-      task_id: z30.string().optional().describe("Associated task ID"),
-      phase_id: z30.string().optional().describe("Associated phase ID"),
-      input_tokens: z30.number().int().nonnegative().optional().describe("Input/prompt tokens"),
-      output_tokens: z30.number().int().nonnegative().optional().describe("Output/completion tokens"),
-      total_tokens: z30.number().int().nonnegative().optional().describe("Total tokens (auto-computed if input+output given)"),
-      cost_usd: z30.number().nonnegative().optional().describe("Estimated cost in USD"),
-      duration_ms: z30.number().int().nonnegative().optional().describe("Wall-clock duration in ms"),
-      drift_count: z30.number().int().nonnegative().optional().describe("Current drift count"),
-      drift_errors: z30.number().int().nonnegative().optional().describe("Current drift errors"),
-      test_pass_count: z30.number().int().nonnegative().optional().describe("Passing tests"),
-      test_fail_count: z30.number().int().nonnegative().optional().describe("Failing tests"),
-      lint_clean: z30.boolean().optional().describe("Whether lint passes cleanly"),
-      typecheck_clean: z30.boolean().optional().describe("Whether typecheck passes cleanly"),
-      notes: z30.string().optional().describe("Free-form notes"),
-      metadata: z30.record(z30.unknown()).optional().describe("Additional key-value metadata")
+      target_dir: z31.string().describe("Absolute path to the project directory"),
+      tool_name: z31.string().describe("Name of the tool or action performed (e.g., 'arcbridge_update_task', 'code_edit')"),
+      action: z31.string().optional().describe("Human-readable label (e.g., 'implement login form')"),
+      model: z31.string().optional().describe("Model identifier (e.g., 'claude-sonnet-4-20250514')"),
+      agent_role: z31.string().optional().describe("Active ArcBridge role (e.g., 'implementer')"),
+      task_id: z31.string().optional().describe("Associated task ID"),
+      phase_id: z31.string().optional().describe("Associated phase ID"),
+      input_tokens: z31.number().int().nonnegative().optional().describe("Input/prompt tokens"),
+      output_tokens: z31.number().int().nonnegative().optional().describe("Output/completion tokens"),
+      total_tokens: z31.number().int().nonnegative().optional().describe("Total tokens (auto-computed if input+output given)"),
+      cost_usd: z31.number().nonnegative().optional().describe("Estimated cost in USD"),
+      duration_ms: z31.number().int().nonnegative().optional().describe("Wall-clock duration in ms"),
+      drift_count: z31.number().int().nonnegative().optional().describe("Current drift count"),
+      drift_errors: z31.number().int().nonnegative().optional().describe("Current drift errors"),
+      test_pass_count: z31.number().int().nonnegative().optional().describe("Passing tests"),
+      test_fail_count: z31.number().int().nonnegative().optional().describe("Failing tests"),
+      lint_clean: z31.boolean().optional().describe("Whether lint passes cleanly"),
+      typecheck_clean: z31.boolean().optional().describe("Whether typecheck passes cleanly"),
+      notes: z31.string().optional().describe("Free-form notes"),
+      metadata: z31.record(z31.unknown()).optional().describe("Additional key-value metadata")
     },
     async (params) => {
       const db = ensureDb(ctx, params.target_dir);
@@ -4183,23 +4256,23 @@ function registerRecordActivity(server, ctx) {
 }
 
 // src/tools/get-metrics.ts
-import { z as z31 } from "zod";
+import { z as z32 } from "zod";
 import { queryMetrics } from "@arcbridge/core";
 function registerGetMetrics(server, ctx) {
   server.tool(
     "arcbridge_get_metrics",
     "Query agent activity metrics \u2014 filter by model, task, phase, or time range. Group by model/task/phase/tool/day for aggregated views.",
     {
-      target_dir: z31.string().describe("Absolute path to the project directory"),
-      task_id: z31.string().optional().describe("Filter by task ID"),
-      phase_id: z31.string().optional().describe("Filter by phase ID"),
-      model: z31.string().optional().describe("Filter by model name"),
-      agent_role: z31.string().optional().describe("Filter by agent role"),
-      tool_name: z31.string().optional().describe("Filter by tool name"),
-      since: z31.string().optional().describe("ISO 8601 timestamp \u2014 activity after this time"),
-      until: z31.string().optional().describe("ISO 8601 timestamp \u2014 activity before this time"),
-      group_by: z31.enum(["model", "task", "phase", "tool", "day", "none"]).default("none").describe("Group results for aggregation"),
-      limit: z31.number().int().min(1).max(500).default(50).describe("Max rows in detail view (group_by=none)")
+      target_dir: z32.string().describe("Absolute path to the project directory"),
+      task_id: z32.string().optional().describe("Filter by task ID"),
+      phase_id: z32.string().optional().describe("Filter by phase ID"),
+      model: z32.string().optional().describe("Filter by model name"),
+      agent_role: z32.string().optional().describe("Filter by agent role"),
+      tool_name: z32.string().optional().describe("Filter by tool name"),
+      since: z32.string().optional().describe("ISO 8601 timestamp \u2014 activity after this time"),
+      until: z32.string().optional().describe("ISO 8601 timestamp \u2014 activity before this time"),
+      group_by: z32.enum(["model", "task", "phase", "tool", "day", "none"]).default("none").describe("Group results for aggregation"),
+      limit: z32.number().int().min(1).max(500).default(50).describe("Max rows in detail view (group_by=none)")
     },
     async (params) => {
       const db = ensureDb(ctx, params.target_dir);
@@ -4282,23 +4355,23 @@ function mdCell(val) {
 }
 
 // src/tools/export-metrics.ts
-import { z as z32 } from "zod";
+import { z as z33 } from "zod";
 import { exportMetrics } from "@arcbridge/core";
 function registerExportMetrics(server, ctx) {
   server.tool(
     "arcbridge_export_metrics",
     "Export agent activity metrics to a file (JSON, CSV, or Markdown) in .arcbridge/metrics/ for git commits or reporting.",
     {
-      target_dir: z32.string().describe("Absolute path to the project directory"),
-      format: z32.enum(["json", "csv", "markdown"]).default("json").describe("Export format"),
-      task_id: z32.string().optional().describe("Filter by task ID"),
-      phase_id: z32.string().optional().describe("Filter by phase ID"),
-      model: z32.string().optional().describe("Filter by model name"),
-      agent_role: z32.string().optional().describe("Filter by agent role"),
-      tool_name: z32.string().optional().describe("Filter by tool name"),
-      since: z32.string().optional().describe("ISO 8601 \u2014 activity after this time"),
-      until: z32.string().optional().describe("ISO 8601 \u2014 activity before this time"),
-      max_rows: z32.number().int().min(1).default(1e5).describe("Maximum rows to export (default: 100,000)")
+      target_dir: z33.string().describe("Absolute path to the project directory"),
+      format: z33.enum(["json", "csv", "markdown"]).default("json").describe("Export format"),
+      task_id: z33.string().optional().describe("Filter by task ID"),
+      phase_id: z33.string().optional().describe("Filter by phase ID"),
+      model: z33.string().optional().describe("Filter by model name"),
+      agent_role: z33.string().optional().describe("Filter by agent role"),
+      tool_name: z33.string().optional().describe("Filter by tool name"),
+      since: z33.string().optional().describe("ISO 8601 \u2014 activity after this time"),
+      until: z33.string().optional().describe("ISO 8601 \u2014 activity before this time"),
+      max_rows: z33.number().int().min(1).default(1e5).describe("Maximum rows to export (default: 100,000)")
     },
     async (params) => {
       const db = ensureDb(ctx, params.target_dir);
@@ -4327,6 +4400,103 @@ You can commit this file to preserve the activity record in git.`
   );
 }
 
+// src/tools/update-arc42-section.ts
+import { z as z34 } from "zod";
+import { join as join4 } from "path";
+import { existsSync as existsSync4, readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "fs";
+function splitFrontmatter(raw) {
+  if (!raw.startsWith("---")) {
+    return { frontmatterBlock: "", body: raw };
+  }
+  const endIndex = raw.indexOf("\n---", 3);
+  if (endIndex < 0) {
+    return { frontmatterBlock: "", body: raw };
+  }
+  const fmEnd = endIndex + 4;
+  return {
+    frontmatterBlock: raw.slice(0, fmEnd),
+    body: raw.slice(fmEnd).replace(/^\n/, "")
+  };
+}
+var VALID_SECTIONS = [
+  "01-introduction",
+  "02-constraints",
+  "03-context",
+  "04-solution-strategy",
+  "06-runtime-views",
+  "07-deployment",
+  "08-crosscutting",
+  "11-risks-debt"
+];
+var SECTION_LABELS = {
+  "01-introduction": "Introduction & Goals",
+  "02-constraints": "Architecture Constraints",
+  "03-context": "Context & Scope",
+  "04-solution-strategy": "Solution Strategy",
+  "06-runtime-views": "Runtime Views",
+  "07-deployment": "Deployment View",
+  "08-crosscutting": "Crosscutting Concepts",
+  "11-risks-debt": "Risks & Technical Debt"
+};
+function registerUpdateArc42Section(server, ctx) {
+  server.tool(
+    "arcbridge_update_arc42_section",
+    "Read or update an arc42 documentation section. Omit `content` to read the current section. Provide `content` to replace the markdown body (frontmatter is preserved automatically). Use this for sections without dedicated tools: introduction, constraints, context, solution strategy, runtime views, deployment, crosscutting concepts, risks & debt. For building blocks use `arcbridge_get_building_blocks`, for quality scenarios use `arcbridge_get_quality_scenarios`.",
+    {
+      target_dir: z34.string().describe("Absolute path to the project directory"),
+      section: z34.enum(VALID_SECTIONS).describe(
+        "Arc42 section to read or update: " + VALID_SECTIONS.map((s) => `${s} (${SECTION_LABELS[s]})`).join(", ")
+      ),
+      content: z34.string().optional().describe(
+        "New markdown content for the section body. Omit to read the current content. Frontmatter is preserved automatically \u2014 only provide the markdown body."
+      )
+    },
+    async (params) => {
+      const db = ensureDb(ctx, params.target_dir);
+      if (!db) return notInitialized();
+      const filePath = join4(
+        params.target_dir,
+        ".arcbridge",
+        "arc42",
+        `${params.section}.md`
+      );
+      if (!existsSync4(filePath)) {
+        return textResult(
+          `Section file \`${params.section}.md\` not found. Run \`arcbridge_init_project\` first.`
+        );
+      }
+      if (params.content === void 0) {
+        const raw2 = readFileSync2(filePath, "utf-8");
+        const { body } = splitFrontmatter(raw2);
+        const label2 = SECTION_LABELS[params.section];
+        const trimmedBody = body.trim();
+        const startsWithHeading = /^#\s+/.test(trimmedBody);
+        const outputLines = [];
+        if (!startsWithHeading) {
+          outputLines.push(`# ${label2}`, "");
+        }
+        outputLines.push(
+          `**File:** \`.arcbridge/arc42/${params.section}.md\``,
+          "",
+          trimmedBody
+        );
+        return textResult(outputLines.join("\n"));
+      }
+      const raw = readFileSync2(filePath, "utf-8");
+      const { frontmatterBlock } = splitFrontmatter(raw);
+      const updated = frontmatterBlock ? `${frontmatterBlock}
+${params.content}
+` : `${params.content}
+`;
+      writeFileSync2(filePath, updated, "utf-8");
+      const label = SECTION_LABELS[params.section];
+      return textResult(
+        `Updated **${label}** (\`${params.section}.md\`). Frontmatter preserved.`
+      );
+    }
+  );
+}
+
 // src/server.ts
 var require2 = createRequire(import.meta.url);
 var { version } = require2("../package.json");
@@ -4348,6 +4518,7 @@ function createArcBridgeServer() {
   registerCreateTask(server, ctx);
   registerDeleteTask(server, ctx);
   registerCreatePhase(server, ctx);
+  registerDeletePhase(server, ctx);
   registerReindex(server, ctx);
   registerSearchSymbols(server, ctx);
   registerGetSymbol(server, ctx);
@@ -4365,6 +4536,7 @@ function createArcBridgeServer() {
   registerVerifyScenarios(server, ctx);
   registerUpdateScenarioStatus(server, ctx);
   registerRunRoleCheck(server, ctx);
+  registerUpdateArc42Section(server, ctx);
   registerRecordActivity(server, ctx);
   registerGetMetrics(server, ctx);
   registerExportMetrics(server, ctx);