@arcbridge/core 0.2.0 → 0.3.0

package/dist/index.d.ts

@@ -933,6 +933,13 @@ declare function deleteTaskFromYaml(projectRoot: string, phaseId: string, taskId
     success: boolean;
     warning?: string;
 };
+/**
+ * Delete a phase from phases.yaml and its associated task file.
+ */
+declare function deletePhaseFromYaml(projectRoot: string, phaseId: string): {
+    success: boolean;
+    warning?: string;
+};
 
 /**
  * Generate sync loop trigger files based on configured platforms.
@@ -1137,4 +1144,4 @@ declare function loadConfig(projectRoot: string): {
     error: string | null;
 };
 
-export { type ActivityRow, type AdrFrontmatter, AdrFrontmatterSchema, type AgentRole, AgentRoleSchema, type AggregatedRow, type ArcBridgeConfig, ArcBridgeConfigSchema, type BuildingBlock, BuildingBlockSchema, type BuildingBlocksFrontmatter, BuildingBlocksFrontmatterSchema, CURRENT_SCHEMA_VERSION, type ChangedFile, type Database, type DotnetProjectInfo, type DriftEntry, type DriftKind, type DriftOptions, type DriftSeverity, type ExportFormat, type ExtractedSymbol, type GenerateDatabaseResult, type GitRef, type IndexResult, type IndexerOptions, type InitProjectInput, type InsertActivityParams, type LatestQualitySnapshot, type LoadRolesResult, type MetricsResult, type Phase, PhaseSchema, type PhasesFile, PhasesFileSchema, type ProjectLanguage, QualityCategorySchema, QualityPrioritySchema, type QualityScenario, QualityScenarioSchema, QualityScenarioStatusSchema, type QualityScenariosFile, QualityScenariosFileSchema, type QueryMetricsParams, type ScenarioTestResult, type Service, type SessionTotals, type SymbolKind, type Task, type TaskFile, TaskFileSchema, type TaskInferenceResult, TaskSchema, type TestOutcome, type VerifyResult, addPhaseToYaml, addTaskToYaml, applyInferences, deleteTaskFromYaml, detectDrift, detectProjectLanguage, discoverDotnetServices, exportMetrics, generateAgentRoles, generateArc42, generateConfig, generateDatabase, generatePlan, generateSyncFiles, getChangedFiles, getHeadSha, getSessionTotals, getUncommittedChanges, indexPackageDependencies, indexProject, inferTaskStatuses, initializeSchema, insertActivity, loadConfig, loadRole, loadRoles, migrate, openDatabase, openMemoryDatabase, queryMetrics, refreshFromDocs, resolveRef, scopeToProject, setSyncCommit, suppressSqliteWarning, syncPhaseToYaml, syncScenarioToYaml, syncTaskToYaml, transaction, verifyScenarios, writeDriftLog };
+export { type ActivityRow, type AdrFrontmatter, AdrFrontmatterSchema, type AgentRole, AgentRoleSchema, type AggregatedRow, type ArcBridgeConfig, ArcBridgeConfigSchema, type BuildingBlock, BuildingBlockSchema, type BuildingBlocksFrontmatter, BuildingBlocksFrontmatterSchema, CURRENT_SCHEMA_VERSION, type ChangedFile, type Database, type DotnetProjectInfo, type DriftEntry, type DriftKind, type DriftOptions, type DriftSeverity, type ExportFormat, type ExtractedSymbol, type GenerateDatabaseResult, type GitRef, type IndexResult, type IndexerOptions, type InitProjectInput, type InsertActivityParams, type LatestQualitySnapshot, type LoadRolesResult, type MetricsResult, type Phase, PhaseSchema, type PhasesFile, PhasesFileSchema, type ProjectLanguage, QualityCategorySchema, QualityPrioritySchema, type QualityScenario, QualityScenarioSchema, QualityScenarioStatusSchema, type QualityScenariosFile, QualityScenariosFileSchema, type QueryMetricsParams, type ScenarioTestResult, type Service, type SessionTotals, type SymbolKind, type Task, type TaskFile, TaskFileSchema, type TaskInferenceResult, TaskSchema, type TestOutcome, type VerifyResult, addPhaseToYaml, addTaskToYaml, applyInferences, deletePhaseFromYaml, deleteTaskFromYaml, detectDrift, detectProjectLanguage, discoverDotnetServices, exportMetrics, generateAgentRoles, generateArc42, generateConfig, generateDatabase, generatePlan, generateSyncFiles, getChangedFiles, getHeadSha, getSessionTotals, getUncommittedChanges, indexPackageDependencies, indexProject, inferTaskStatuses, initializeSchema, insertActivity, loadConfig, loadRole, loadRoles, migrate, openDatabase, openMemoryDatabase, queryMetrics, refreshFromDocs, resolveRef, scopeToProject, setSyncCommit, suppressSqliteWarning, syncPhaseToYaml, syncScenarioToYaml, syncTaskToYaml, transaction, verifyScenarios, writeDriftLog };

package/dist/index.js

@@ -832,6 +832,41 @@ ${input.quality_priorities.map((q, i) => `| ${i + 1} | ${q} | *Describe what ${q
   };
 }
 
+// src/templates/arc42/02-constraints.ts
+function constraintsTemplate(input) {
+  return {
+    frontmatter: {
+      section: "constraints",
+      schema_version: 1
+    },
+    body: `# Architecture Constraints
+
+Document the constraints that shape architectural decisions for ${input.name}. Constraints are non-negotiable requirements from the environment \u2014 they are not chosen, they are given.
+
+## Technical Constraints
+
+| Constraint | Description |
+|-----------|-------------|
+| *e.g., Must run on Node.js 22+* | *Explain why this constraint exists* |
+| *e.g., No native dependencies* | *Required for CI/CD compatibility* |
+
+## Organizational Constraints
+
+| Constraint | Description |
+|-----------|-------------|
+| *e.g., Team of 1-2 developers* | *Impacts architecture complexity budget* |
+| *e.g., Must ship MVP in 4 weeks* | *Impacts scope and technology choices* |
+
+## Legal / Compliance Constraints
+
+| Constraint | Description |
+|-----------|-------------|
+| *e.g., GDPR compliance required* | *Impacts data storage and processing* |
+| *e.g., MIT-compatible dependencies only* | *Impacts library selection* |
+`
+  };
+}
+
 // src/templates/arc42/03-context.ts
 function techStack(template) {
   switch (template) {
@@ -887,6 +922,47 @@ ${techStack(input.template)}
   };
 }
 
+// src/templates/arc42/04-solution-strategy.ts
+function solutionStrategyTemplate(input) {
+  return {
+    frontmatter: {
+      section: "solution-strategy",
+      schema_version: 1
+    },
+    body: `# Solution Strategy
+
+Document the fundamental decisions and solution approaches that drive the architecture of ${input.name}. This section explains *why* the architecture looks the way it does \u2014 connecting quality goals to technical decisions.
+
+## Technology Decisions
+
+| Decision | Rationale | Quality Goal |
+|----------|-----------|-------------|
+| *e.g., Use TypeScript* | *Type safety reduces runtime errors* | *Reliability, Maintainability* |
+| *e.g., Use SQLite for local storage* | *Zero-config, no external service dependency* | *Maintainability* |
+
+## Architecture Approach
+
+*Describe the high-level architecture pattern and why it was chosen.*
+
+- *e.g., Layered architecture with clear module boundaries (enforced by ArcBridge building blocks)*
+- *e.g., YAML as source of truth, DB as queryable cache \u2014 enables version control and human readability*
+
+## Quality Goal Strategies
+
+| Quality Goal | Strategy |
+|-------------|----------|
+${input.quality_priorities.map((q) => `| ${q} | *How will you achieve ${q}?* |`).join("\n")}
+
+## Decomposition Approach
+
+*How is the system broken down into building blocks? What principles guide the decomposition?*
+
+- *e.g., Feature-based: each major feature is a building block with clear interfaces*
+- *e.g., Layer-based: presentation, business logic, data access*
+`
+  };
+}
+
 // src/templates/arc42/05-building-blocks.ts
 import { existsSync as existsSync2, readdirSync } from "fs";
 import { join as join3 } from "path";
@@ -2297,7 +2373,9 @@ function generateArc42(targetDir, input) {
   mkdirSync2(decisionsDir, { recursive: true });
   const sections = [
     { file: "01-introduction.md", template: introductionTemplate },
+    { file: "02-constraints.md", template: constraintsTemplate },
     { file: "03-context.md", template: contextTemplate },
+    { file: "04-solution-strategy.md", template: solutionStrategyTemplate },
     { file: "05-building-blocks.md", template: buildingBlocksTemplate },
     { file: "06-runtime-views.md", template: runtimeViewsTemplate },
     { file: "07-deployment.md", template: deploymentTemplate },
@@ -2335,7 +2413,7 @@ function phasePlanTemplate(_input) {
       id: "phase-0-setup",
       name: "Project Setup",
       phase_number: 0,
-      status: "in-progress",
+      status: "planned",
       description: "Initialize project structure, install dependencies, configure tooling",
       gate_requirements: [
         "Project builds successfully",
@@ -2600,7 +2678,7 @@ function phasePlanTemplate2(_input) {
       id: "phase-0-setup",
       name: "Project Setup",
       phase_number: 0,
-      status: "in-progress",
+      status: "planned",
       description: "Initialize Vite + React project, configure TypeScript, install dependencies",
       gate_requirements: [
         "Project builds successfully with Vite",
@@ -2866,7 +2944,7 @@ function phasePlanTemplate3(_input) {
       id: "phase-0-setup",
       name: "Project Setup",
       phase_number: 0,
-      status: "in-progress",
+      status: "planned",
       description: "Initialize API service, configure TypeScript, set up database and middleware",
       gate_requirements: [
         "Project builds successfully",
@@ -3049,7 +3127,7 @@ function phasePlanTemplate4(_input) {
       id: "phase-0-setup",
       name: "Project Setup",
       phase_number: 0,
-      status: "in-progress",
+      status: "planned",
       description: "Initialize ASP.NET Core project, configure DI, set up database and middleware pipeline",
       gate_requirements: [
         "Project builds and runs successfully",
@@ -3248,7 +3326,7 @@ function phasePlanTemplate5(_input) {
       id: "phase-0-setup",
       name: "Project Setup",
       phase_number: 0,
-      status: "in-progress",
+      status: "planned",
       description: "Initialize Unity project structure, configure input system, core game loop, and assembly definitions",
       gate_requirements: [
         "Unity project opens and runs without errors",
@@ -3533,7 +3611,9 @@ You are responsible for maintaining these sections in \`.arcbridge/arc42/\`. Upd
 | Section | File | When to update |
 |---------|------|----------------|
 | **01 Introduction & Goals** | \`01-introduction.md\` | When project scope, stakeholders, or key goals change |
+| **02 Architecture Constraints** | \`02-constraints.md\` | When new constraints are discovered (technical, organizational, legal) |
 | **03 Context & Scope** | \`03-context.md\` | When adding/removing external systems, APIs, or integrations |
+| **04 Solution Strategy** | \`04-solution-strategy.md\` | When fundamental technology or architecture decisions change |
 | **05 Building Blocks** | \`05-building-blocks.md\` | When adding new modules, changing responsibilities, or restructuring layers |
 | **06 Runtime Views** | \`06-runtime-views.md\` | When adding key workflows (e.g., auth flow, order processing, data sync) |
 | **07 Deployment** | \`07-deployment.md\` | When changing infrastructure, environments, or deployment strategy |
@@ -3557,14 +3637,41 @@ You are responsible for maintaining these sections in \`.arcbridge/arc42/\`. Upd
 - All ADRs and their status
 - Building block \u2192 code mapping
 
+## Post-Init Tailoring (CRITICAL \u2014 Do This Before Writing Code)
+
+The building blocks, quality scenarios, and phase tasks generated during init are a **generic starting template**, not a project-specific plan. Before writing any code, systematically tailor the generated content to the actual project:
+
+1. **Building blocks:** Review each generated block against the project description. Delete blocks that don't apply (e.g., "API Client" for a client-only app). Add blocks for the real modules/features you'll build. **Declare interfaces between blocks** to specify dependencies \u2014 drift detection and phase gates rely on this.
+2. **Quality scenarios:** Review each scenario against the project's quality priorities. Delete irrelevant ones (e.g., "API response time" for a localStorage-only app). Add scenarios that reflect the actual requirements.
+3. **Phase tasks:** Phase 0-1 tasks are ready to use. **Phase 2+ tasks are examples \u2014 delete them** and create tasks that match the features you're actually building. Keep phases small and focused (3-6 tasks per phase). Add more phases if needed using \`arcbridge_create_phase\` \u2014 6, 8, or 10 phases is fine for larger projects.
+4. **Reindex** after making changes so drift detection picks up your tailored architecture.
+
+The goal is that by the time you start Phase 0, the building blocks describe your architecture, the quality scenarios test your requirements, and the tasks reflect your build plan.
+
+### Building Block interfaces
+
+Each building block in \`05-building-blocks.md\` should declare its dependencies on other blocks using the \`interfaces\` field. This is required for drift detection to catch undeclared cross-block dependencies at phase gates.
+
+Format \u2014 within the \`blocks:\` array, list the IDs of other blocks this block depends on:
+\`\`\`yaml
+blocks:
+  - id: canvas-engine
+    name: Canvas Engine
+    level: 1
+    responsibility: "Render and manage collaborative canvas state"
+    service: main
+    code_paths:
+      - "src/canvas/"
+    interfaces:
+      - workflow-model
+      - shared-types
+\`\`\`
+
+If your code imports across block boundaries without declaring the interface, \`arcbridge_check_drift\` will flag it and \`arcbridge_complete_phase\` will block the gate.
+
 ## 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** using \`arcbridge_create_phase\`. Split "Core Features" into multiple phases if needed (e.g., "Auth & Users", "Core Business Logic", "Integrations", "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
+- Review the phase plan with \`arcbridge_get_phase_plan\`
 - 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
@@ -7171,7 +7278,7 @@ function safeParseJson(value, fallback) {
 
 // src/sync/yaml-writer.ts
 import { join as join15 } from "path";
-import { existsSync as existsSync8, readFileSync as readFileSync8, writeFileSync as writeFileSync5, mkdirSync as mkdirSync5 } from "fs";
+import { existsSync as existsSync8, readFileSync as readFileSync8, writeFileSync as writeFileSync5, mkdirSync as mkdirSync5, unlinkSync } from "fs";
 import { parse as parse2, stringify as stringify4 } from "yaml";
 function syncTaskToYaml(projectRoot, phaseId, taskId, status, completedAt) {
   const taskPath = join15(
@@ -7355,6 +7462,41 @@ function deleteTaskFromYaml(projectRoot, phaseId, taskId) {
     };
   }
 }
+function deletePhaseFromYaml(projectRoot, phaseId) {
+  try {
+    const phasesPath = join15(projectRoot, ".arcbridge", "plan", "phases.yaml");
+    if (!existsSync8(phasesPath)) {
+      return { success: false, warning: "phases.yaml not found" };
+    }
+    const raw = readFileSync8(phasesPath, "utf-8");
+    const result = PhasesFileSchema.safeParse(parse2(raw));
+    if (!result.success) {
+      return {
+        success: false,
+        warning: "Could not parse phases.yaml \u2014 phase may reappear after reindex"
+      };
+    }
+    const phasesFile = result.data;
+    const before = phasesFile.phases.length;
+    phasesFile.phases = phasesFile.phases.filter((p) => p.id !== phaseId);
+    if (phasesFile.phases.length === before) {
+      return { success: false, warning: `Phase '${phaseId}' not found in phases.yaml` };
+    }
+    writeFileSync5(phasesPath, stringify4(phasesFile), "utf-8");
+    const taskFilePath = join15(projectRoot, ".arcbridge", "plan", "tasks", `${phaseId}.yaml`);
+    try {
+      unlinkSync(taskFilePath);
+    } catch (e) {
+      if (e.code !== "ENOENT") throw e;
+    }
+    return { success: true };
+  } catch (err) {
+    return {
+      success: false,
+      warning: `YAML update failed: ${err instanceof Error ? err.message : String(err)}`
+    };
+  }
+}
 
 // src/sync/task-inference.ts
 function inferTaskStatuses(db, phaseId) {
@@ -8332,6 +8474,7 @@ export {
   addPhaseToYaml,
   addTaskToYaml,
   applyInferences,
+  deletePhaseFromYaml,
   deleteTaskFromYaml,
   detectDrift,
   detectProjectLanguage,