ai-spec-dev 0.1.0 → 0.14.1

package/core/frontend-context-loader.ts

@@ -0,0 +1,602 @@
+import * as fs from "fs-extra";
+import * as path from "path";
+import { glob } from "glob";
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+export type FrontendFramework = "react" | "next" | "vue" | "react-native" | "unknown";
+
+export interface FrontendContext {
+  framework: FrontendFramework;
+  /** e.g. ['zustand', 'redux', 'jotai'] */
+  stateManagement: string[];
+  /** e.g. 'axios', 'fetch', 'swr', 'react-query' */
+  httpClient: string;
+  /** e.g. 'tailwind', 'antd', 'shadcn' */
+  uiLibrary: string;
+  /** e.g. 'react-router', 'next-app-router' */
+  routingPattern: string;
+  /** Whether tests use React Testing Library */
+  testFramework: "rtl" | "cypress" | "jest" | "vitest" | "unknown";
+  /** api/ or services/ file paths */
+  existingApiFiles: string[];
+  /** First 60 lines of up to 2 existing API wrapper files */
+  apiWrapperContent: string[];
+  /** Custom hook files (use*.ts/tsx) — relative paths */
+  hookFiles: string[];
+  /** First 30 lines of up to 2 hook files */
+  hookPatterns: string[];
+  /** State slice / store files — relative paths */
+  storeFiles: string[];
+  /** First 60 lines of up to 2 existing store files — shows the real store pattern */
+  storePatterns: string[];
+  /**
+   * The exact HTTP client import line found in an existing API file.
+   * e.g. "import request from '@/utils/http'"
+   * Extracted from real code — use this verbatim, never invent a different import path.
+   */
+  httpClientImport?: string;
+  /**
+   * Reusable components found in src/components/ — relative paths.
+   * AI must check this list before creating any new component.
+   */
+  reusableComponents: string[];
+  /**
+   * First 60 lines of up to 2 existing page/view files.
+   * Shows how UI library components and shared components are actually imported and used.
+   */
+  pageExamples: string[];
+  /** Sample component structures (first 40 lines of up to 3 components) */
+  componentPatterns: string[];
+  /**
+   * The exact layout component import line found in an existing route module.
+   * e.g. "const Layout = () => import('@/layout/index.vue')"
+   * Extracted from real code — must be copied verbatim when creating new route modules.
+   */
+  layoutImport?: string;
+  /**
+   * Full content of one existing route module file — use as a copy-paste template.
+   * Relative path + content.
+   */
+  routeModuleExample?: { path: string; content: string };
+  /**
+   * A real paginated API function extracted from the existing codebase.
+   * Shows the exact pagination parameter names (e.g. pageIndex/pageSize vs page/size)
+   * and how they are passed (POST body vs GET query params).
+   * COPY THIS PATTERN exactly for all new paginated list APIs.
+   */
+  paginationExample?: string;
+}
+
+// ─── Detection Maps ────────────────────────────────────────────────────────────
+
+const STATE_MANAGEMENT_LIBS = [
+  "zustand",
+  "redux",
+  "@reduxjs/toolkit",
+  "jotai",
+  "recoil",
+  "mobx",
+  "mobx-react",
+  "valtio",
+  "pinia",
+  "vuex",
+];
+
+const HTTP_CLIENT_LIBS: Array<[string, string]> = [
+  ["swr", "swr"],
+  ["@tanstack/react-query", "react-query"],
+  ["react-query", "react-query"],
+  ["axios", "axios"],
+  ["ky", "ky"],
+];
+
+const UI_LIBRARY_LIBS: Array<[string, string]> = [
+  ["antd", "antd"],
+  ["@ant-design/pro-components", "antd-pro"],
+  ["@mui/material", "mui"],
+  ["@chakra-ui/react", "chakra-ui"],
+  ["shadcn-ui", "shadcn"],
+  ["@radix-ui/react-primitive", "radix-ui"],
+  ["element-plus", "element-plus"],
+  ["vant", "vant"],
+  ["tailwindcss", "tailwind"],
+  ["@tailwindcss/vite", "tailwind"],
+  ["react-native-paper", "react-native-paper"],
+];
+
+const ROUTING_LIBS: Array<[string, string]> = [
+  ["react-router-dom", "react-router"],
+  ["react-router", "react-router"],
+  ["@tanstack/react-router", "tanstack-router"],
+  ["react-navigation", "react-navigation"],
+  ["expo-router", "expo-router"],
+  ["vue-router", "vue-router"],
+];
+
+// ─── Main function ─────────────────────────────────────────────────────────────
+
+/**
+ * Load frontend-specific project context (framework, state mgmt, HTTP client, etc.)
+ * Never throws — returns partial results on failure.
+ */
+export async function loadFrontendContext(
+  projectRoot: string
+): Promise<FrontendContext> {
+  const ctx: FrontendContext = {
+    framework: "unknown",
+    stateManagement: [],
+    httpClient: "fetch",
+    uiLibrary: "unknown",
+    routingPattern: "unknown",
+    testFramework: "unknown",
+    existingApiFiles: [],
+    apiWrapperContent: [],
+    hookFiles: [],
+    hookPatterns: [],
+    storeFiles: [],
+    storePatterns: [],
+    reusableComponents: [],
+    pageExamples: [],
+    componentPatterns: [],
+  };
+
+  try {
+    const pkgPath = path.join(projectRoot, "package.json");
+    if (!(await fs.pathExists(pkgPath))) return ctx;
+
+    const pkg = await fs.readJson(pkgPath);
+    const allDeps: Record<string, string> = {
+      ...(pkg.dependencies ?? {}),
+      ...(pkg.devDependencies ?? {}),
+    };
+    const depKeys = Object.keys(allDeps);
+    const has = (name: string) => depKeys.includes(name);
+
+    // Framework
+    if (has("react-native") || has("expo")) {
+      ctx.framework = "react-native";
+    } else if (has("next")) {
+      ctx.framework = "next";
+    } else if (has("react")) {
+      ctx.framework = "react";
+    } else if (has("vue")) {
+      ctx.framework = "vue";
+    }
+
+    // State management (may have multiple)
+    ctx.stateManagement = STATE_MANAGEMENT_LIBS.filter((lib) => has(lib));
+
+    // HTTP client (first match wins)
+    for (const [lib, label] of HTTP_CLIENT_LIBS) {
+      if (has(lib)) {
+        ctx.httpClient = label;
+        break;
+      }
+    }
+
+    // UI library (first match wins)
+    for (const [lib, label] of UI_LIBRARY_LIBS) {
+      if (has(lib)) {
+        ctx.uiLibrary = label;
+        break;
+      }
+    }
+    if (ctx.uiLibrary === "unknown") {
+      ctx.uiLibrary = "none";
+    }
+
+    // Routing
+    if (ctx.framework === "next") {
+      // Detect app router vs pages router
+      const hasAppDir = await fs.pathExists(path.join(projectRoot, "app"));
+      ctx.routingPattern = hasAppDir ? "next-app-router" : "next-pages-router";
+    } else {
+      for (const [lib, label] of ROUTING_LIBS) {
+        if (has(lib)) {
+          ctx.routingPattern = label;
+          break;
+        }
+      }
+    }
+
+    // Test framework detection
+    if (depKeys.includes("@testing-library/react") || depKeys.includes("@testing-library/vue")) {
+      ctx.testFramework = "rtl";
+    } else if (depKeys.includes("cypress")) {
+      ctx.testFramework = "cypress";
+    } else if (depKeys.includes("vitest")) {
+      ctx.testFramework = "vitest";
+    } else if (depKeys.includes("jest") || depKeys.includes("@jest/core")) {
+      ctx.testFramework = "jest";
+    }
+
+    // Existing API files
+    const apiFilePatterns = [
+      "src/api/**/*.{ts,js}",
+      "src/apis/**/*.{ts,js}",
+      "src/services/**/*.{ts,js}",
+      "src/lib/api/**/*.{ts,js}",
+      "src/utils/api/**/*.{ts,js}",
+      "api/**/*.{ts,js}",
+      "services/**/*.{ts,js}",
+    ];
+    for (const pattern of apiFilePatterns) {
+      const files = await glob(pattern, {
+        cwd: projectRoot,
+        ignore: ["**/*.test.*", "**/*.spec.*", "node_modules/**"],
+      });
+      ctx.existingApiFiles.push(...files);
+    }
+    ctx.existingApiFiles = [...new Set(ctx.existingApiFiles)].slice(0, 20);
+
+    // API wrapper content preview — first 60 lines of up to 2 files
+    for (const relPath of ctx.existingApiFiles.slice(0, 2)) {
+      try {
+        const content = await fs.readFile(path.join(projectRoot, relPath), "utf-8");
+        const preview = content.split("\n").slice(0, 60).join("\n");
+        ctx.apiWrapperContent.push(`// ${relPath}\n${preview}`);
+      } catch {
+        // skip
+      }
+    }
+
+    // Hook files — use*.ts/tsx
+    const hookPatterns = [
+      "src/hooks/use*.{ts,tsx}",
+      "src/**/hooks/use*.{ts,tsx}",
+      "hooks/use*.{ts,tsx}",
+    ];
+    for (const pattern of hookPatterns) {
+      const files = await glob(pattern, {
+        cwd: projectRoot,
+        ignore: ["**/*.test.*", "**/*.spec.*", "node_modules/**"],
+      });
+      ctx.hookFiles.push(...files);
+    }
+    ctx.hookFiles = [...new Set(ctx.hookFiles)].slice(0, 15);
+
+    // Hook content preview — first 30 lines of up to 2 hook files
+    for (const relPath of ctx.hookFiles.slice(0, 2)) {
+      try {
+        const content = await fs.readFile(path.join(projectRoot, relPath), "utf-8");
+        const preview = content.split("\n").slice(0, 30).join("\n");
+        ctx.hookPatterns.push(`// ${relPath}\n${preview}`);
+      } catch {
+        // skip
+      }
+    }
+
+    // Store / slice files (Redux slices, Zustand stores, Pinia stores)
+    const storeFilePatterns = [
+      "src/store/**/*.{ts,js}",
+      "src/stores/**/*.{ts,js}",
+      "src/**/slice*.{ts,js}",
+      "src/**/*slice.{ts,js}",
+      "src/**/*store.{ts,js}",
+      "src/**/*Store.{ts,js}",
+      "store/**/*.{ts,js}",
+      "stores/**/*.{ts,js}",
+    ];
+    for (const pattern of storeFilePatterns) {
+      const files = await glob(pattern, {
+        cwd: projectRoot,
+        ignore: ["**/*.test.*", "**/*.spec.*", "node_modules/**"],
+      });
+      ctx.storeFiles.push(...files);
+    }
+    ctx.storeFiles = [...new Set(ctx.storeFiles)].slice(0, 10);
+
+    // Store content preview — first 60 lines of up to 2 store files
+    // (shows the AI what stores actually do: state + actions that call API layer, NOT HTTP directly)
+    for (const relPath of ctx.storeFiles.slice(0, 2)) {
+      try {
+        const content = await fs.readFile(path.join(projectRoot, relPath), "utf-8");
+        const preview = content.split("\n").slice(0, 60).join("\n");
+        ctx.storePatterns.push(`// ${relPath}\n${preview}`);
+      } catch {
+        // skip
+      }
+    }
+
+    // Extract the exact HTTP client import line from an existing API file
+    // e.g. "import request from '@/utils/http'" or "import axios from 'axios'"
+    // This is ground truth — prevents the AI from inventing a different import path.
+    const httpImportRegex = /^import\s+(?:\w+|\{[^}]+\})\s+from\s+['"](@\/[^'"]+|axios|ky)['"]/m;
+    for (const relPath of ctx.existingApiFiles.slice(0, 5)) {
+      try {
+        const content = await fs.readFile(path.join(projectRoot, relPath), "utf-8");
+        const match = content.match(httpImportRegex);
+        if (match) {
+          ctx.httpClientImport = match[0].trim();
+          break;
+        }
+      } catch {
+        // skip
+      }
+    }
+
+    // Pagination pattern extraction — find a real paginated list function from the existing codebase.
+    // Scans API files for interfaces/params that contain pagination field names,
+    // then extracts the matching function as ground truth for the AI to copy.
+    const paginationFieldNames = ["pageIndex", "pageSize", "pageNum", "current", "page", "size", "offset", "limit"];
+    const paginationInterfaceRegex = new RegExp(
+      `(?:interface|type)\\s+(\\w*(?:Params|Query|Request|Filter|Page)\\w*)\\s*\\{[^}]*\\b(?:${paginationFieldNames.join("|")})\\b[^}]*\\}`,
+      "s"
+    );
+    const apiExportFnRegex = /export\s+(?:async\s+)?function\s+\w+\s*\([^)]*\)[^{]*\{[\s\S]*?\n\}/g;
+    for (const relPath of ctx.existingApiFiles) {
+      // Skip type-only and index files
+      if (/types?\.ts$|index\.ts$/.test(relPath)) continue;
+      try {
+        const content = await fs.readFile(path.join(projectRoot, relPath), "utf-8");
+        // Only process files that have pagination field names at all
+        if (!paginationFieldNames.some((f) => content.includes(f))) continue;
+        // Check this file has an interface with pagination fields
+        const interfaceMatch = content.match(paginationInterfaceRegex);
+        if (!interfaceMatch) continue;
+        // Find the first exported function that uses this interface
+        const interfaceName = interfaceMatch[1];
+        const fnRegex = new RegExp(
+          `export\\s+(?:async\\s+)?function\\s+\\w+\\s*\\(\\s*\\w+\\s*:\\s*${interfaceName}[^)]*\\)[\\s\\S]*?\\n\\}`,
+          ""
+        );
+        const fnMatch = content.match(fnRegex);
+        if (fnMatch) {
+          ctx.paginationExample = `// From ${relPath}\n${interfaceMatch[0]}\n\n${fnMatch[0]}`;
+          break;
+        }
+      } catch {
+        // skip
+      }
+    }
+
+    // Reusable components — scan src/components/ (the shared component library)
+    const sharedComponentDirs = ["src/components", "components"];
+    for (const dir of sharedComponentDirs) {
+      const absDir = path.join(projectRoot, dir);
+      if (!(await fs.pathExists(absDir))) continue;
+      const files = await glob("**/*.{vue,tsx,jsx}", {
+        cwd: absDir,
+        ignore: ["**/*.test.*", "**/*.spec.*", "node_modules/**"],
+        maxDepth: 4,
+      });
+      ctx.reusableComponents.push(...files.map((f) => path.join(dir, f)));
+    }
+    ctx.reusableComponents = [...new Set(ctx.reusableComponents)].slice(0, 40);
+
+    // Page examples — read 2 existing view/page files to show component usage patterns
+    const viewDirs = ["src/views", "src/pages", "views", "pages"];
+    const viewFiles: string[] = [];
+    for (const dir of viewDirs) {
+      const absDir = path.join(projectRoot, dir);
+      if (!(await fs.pathExists(absDir))) continue;
+      const files = await glob("**/*.{vue,tsx,jsx}", {
+        cwd: absDir,
+        ignore: ["**/*.test.*", "**/*.spec.*", "node_modules/**"],
+        maxDepth: 3,
+      });
+      viewFiles.push(...files.map((f) => path.join(dir, f)));
+      if (viewFiles.length >= 6) break;
+    }
+    for (const relPath of viewFiles.slice(0, 2)) {
+      try {
+        const content = await fs.readFile(path.join(projectRoot, relPath), "utf-8");
+        // Read up to 80 lines — enough to see the template section with component usage
+        const preview = content.split("\n").slice(0, 80).join("\n");
+        ctx.pageExamples.push(`// ${relPath}\n${preview}`);
+      } catch {
+        // skip
+      }
+    }
+
+    // Component patterns — sample a few component files (generic structure reference)
+    const componentFiles: string[] = [];
+    for (const dir of sharedComponentDirs) {
+      const absDir = path.join(projectRoot, dir);
+      if (!(await fs.pathExists(absDir))) continue;
+      const files = await glob("**/*.{tsx,vue,jsx}", {
+        cwd: absDir,
+        ignore: ["**/*.test.*", "**/*.spec.*", "node_modules/**"],
+        maxDepth: 2,
+      });
+      componentFiles.push(...files.map((f) => path.join(dir, f)));
+      if (componentFiles.length >= 5) break;
+    }
+
+    // Read first 40 lines of up to 3 component files
+    for (const relPath of componentFiles.slice(0, 3)) {
+      try {
+        const content = await fs.readFile(path.join(projectRoot, relPath), "utf-8");
+        const preview = content.split("\n").slice(0, 40).join("\n");
+        ctx.componentPatterns.push(`// ${relPath}\n${preview}`);
+      } catch {
+        // skip unreadable files
+      }
+    }
+    // Route module example + layout import extraction
+    await extractRouteModuleContext(projectRoot, ctx);
+
+  } catch {
+    // Graceful degradation — return whatever we've collected so far
+  }
+
+  return ctx;
+}
+
+/**
+ * Scan existing router module files to extract:
+ * 1. The exact layout component import line (ground truth, not guessed)
+ * 2. A full route module file as a copy-paste template
+ */
+async function extractRouteModuleContext(
+  projectRoot: string,
+  ctx: FrontendContext
+): Promise<void> {
+  const modulePatterns = [
+    "src/router/modules/**/*.{ts,js}",
+    "src/routes/modules/**/*.{ts,js}",
+    "src/router/**/*.{ts,js}",
+  ];
+
+  const moduleFiles: string[] = [];
+  for (const pattern of modulePatterns) {
+    const files = await glob(pattern, {
+      cwd: projectRoot,
+      ignore: ["**/index.{ts,js}", "node_modules/**", "**/*.test.*"],
+    });
+    moduleFiles.push(...files);
+  }
+
+  if (moduleFiles.length === 0) return;
+
+  // Layout import regex — matches common patterns:
+  //   const Layout = () => import('@/layout/index.vue')
+  //   import Layout from '@/layouts/default/index.vue'
+  //   const Layout = defineAsyncComponent(() => import('@/layout/index.vue'))
+  const layoutImportRegex =
+    /^(?:const\s+Layout\s*=.*import\(['"][^'"]+['"]\)|import\s+Layout\s+from\s+['"][^'"]+['"])/m;
+
+  for (const relPath of moduleFiles) {
+    try {
+      const content = await fs.readFile(path.join(projectRoot, relPath), "utf-8");
+      const match = content.match(layoutImportRegex);
+      if (match) {
+        ctx.layoutImport = match[0].trim();
+        // Use this file as the route module template (cap at 100 lines)
+        const preview = content.split("\n").slice(0, 100).join("\n");
+        ctx.routeModuleExample = { path: relPath, content: preview };
+        break; // first match is enough
+      }
+    } catch {
+      // skip
+    }
+  }
+}
+
+/**
+ * Build a concise context section from FrontendContext for prompt injection.
+ */
+export function buildFrontendContextSection(ctx: FrontendContext): string {
+  const lines: string[] = [
+    "=== Frontend Project Context ===",
+    `Framework        : ${ctx.framework}`,
+    `State Management : ${ctx.stateManagement.join(", ") || "none detected"}`,
+    `HTTP Client      : ${ctx.httpClient}`,
+    `UI Library       : ${ctx.uiLibrary}`,
+    `Routing          : ${ctx.routingPattern}`,
+    `Test Framework   : ${ctx.testFramework}`,
+  ];
+
+  // Layout import — most critical for correct route module generation
+  if (ctx.layoutImport) {
+    lines.push(
+      `\nLayout component import (COPY THIS EXACTLY in every new route module — do NOT invent a different path):`,
+      `  ${ctx.layoutImport}`
+    );
+  }
+
+  // Route module template — shows exact file structure to replicate
+  if (ctx.routeModuleExample) {
+    lines.push(
+      `\nExisting route module template (${ctx.routeModuleExample.path}) — use this as the structural template for new route modules:`,
+      "```",
+      ctx.routeModuleExample.content,
+      "```"
+    );
+  }
+
+  if (ctx.existingApiFiles.length > 0) {
+    lines.push(`\nExisting API/service files (${ctx.existingApiFiles.length}):`);
+    ctx.existingApiFiles.slice(0, 10).forEach((f) => lines.push(`  - ${f}`));
+  }
+
+  // HTTP client import — must be copied verbatim
+  if (ctx.httpClientImport) {
+    lines.push(
+      `\nHTTP client import (COPY THIS EXACTLY in every new API file — do NOT import from any other path):`,
+      `  ${ctx.httpClientImport}`
+    );
+  }
+
+  // Pagination example — the most critical ground truth for list APIs
+  if (ctx.paginationExample) {
+    lines.push(
+      `\nPagination pattern (COPY THIS EXACTLY for all paginated list APIs — use IDENTICAL parameter names, HTTP method, and call style):`,
+      "```typescript",
+      ctx.paginationExample,
+      "```"
+    );
+  }
+
+  if (ctx.apiWrapperContent.length > 0) {
+    lines.push(`\nAPI file patterns (new API functions must follow this exact structure):`);
+    ctx.apiWrapperContent.forEach((p) => {
+      lines.push("```");
+      lines.push(p);
+      lines.push("```");
+    });
+  }
+
+  if (ctx.hookFiles.length > 0) {
+    lines.push(`\nExisting custom hooks (${ctx.hookFiles.length}):`);
+    ctx.hookFiles.slice(0, 8).forEach((f) => lines.push(`  - ${f}`));
+  }
+
+  if (ctx.hookPatterns.length > 0) {
+    lines.push(`\nHook patterns (follow same structure):`);
+    ctx.hookPatterns.forEach((p) => {
+      lines.push("```");
+      lines.push(p);
+      lines.push("```");
+    });
+  }
+
+  if (ctx.storeFiles.length > 0) {
+    lines.push(`\nState store files (${ctx.storeFiles.length}):`);
+    ctx.storeFiles.slice(0, 8).forEach((f) => lines.push(`  - ${f}`));
+  }
+
+  if (ctx.storePatterns.length > 0) {
+    lines.push(
+      `\nExisting store patterns (CRITICAL — stores in this project call API layer functions, they do NOT make HTTP requests directly):`,
+      `Follow this exact structure for new stores:`
+    );
+    ctx.storePatterns.forEach((p) => {
+      lines.push("```");
+      lines.push(p);
+      lines.push("```");
+    });
+  }
+
+  if (ctx.reusableComponents.length > 0) {
+    lines.push(
+      `\nExisting reusable components in src/components/ (${ctx.reusableComponents.length} files):`,
+      `ALWAYS check this list before creating a new component. Import and reuse existing ones instead of reinventing.`
+    );
+    ctx.reusableComponents.forEach((f) => lines.push(`  - ${f}`));
+  }
+
+  if (ctx.pageExamples.length > 0) {
+    lines.push(
+      `\nExisting page examples (shows which UI library components and shared components are used — follow the same import and usage patterns):`
+    );
+    ctx.pageExamples.forEach((p) => {
+      lines.push("```");
+      lines.push(p);
+      lines.push("```");
+    });
+  }
+
+  if (ctx.componentPatterns.length > 0) {
+    lines.push(`\nShared component structure patterns:`);
+    ctx.componentPatterns.forEach((p) => {
+      lines.push("```");
+      lines.push(p.slice(0, 500));
+      lines.push("```");
+    });
+  }
+
+  lines.push("=== End of Frontend Context ===");
+  return lines.join("\n");
+}

package/core/global-constitution.ts

@@ -0,0 +1,88 @@
+import * as fs from "fs-extra";
+import * as path from "path";
+import * as os from "os";
+
+// ─── Constants ────────────────────────────────────────────────────────────────
+
+export const GLOBAL_CONSTITUTION_FILE = ".ai-spec-global-constitution.md";
+
+/**
+ * Search order for global constitution:
+ *  1. Workspace root (for monorepo-level shared rules)
+ *  2. User home directory (for personal cross-project rules)
+ */
+const SEARCH_ROOTS = [
+  // Workspace root is injected at runtime — see loadGlobalConstitution()
+  os.homedir(),
+];
+
+// ─── Load ─────────────────────────────────────────────────────────────────────
+
+/**
+ * Search for a global constitution file.
+ * @param extraRoots Additional directories to check first (e.g. workspace root).
+ * Returns the content string, or null if not found anywhere.
+ */
+export async function loadGlobalConstitution(
+  extraRoots: string[] = []
+): Promise<{ content: string; source: string } | null> {
+  const roots = [...extraRoots, ...SEARCH_ROOTS];
+
+  for (const root of roots) {
+    const filePath = path.join(root, GLOBAL_CONSTITUTION_FILE);
+    if (await fs.pathExists(filePath)) {
+      const content = await fs.readFile(filePath, "utf-8");
+      return { content, source: filePath };
+    }
+  }
+
+  return null;
+}
+
+// ─── Merge ────────────────────────────────────────────────────────────────────
+
+/**
+ * Merge global and project constitutions.
+ *
+ * Injection order (from lowest to highest priority):
+ *   1. Global constitution  — team/personal baseline rules
+ *   2. Project constitution — project-specific overrides (wins on conflict)
+ *
+ * The merged text is what gets injected into Spec/codegen prompts.
+ */
+export function mergeConstitutions(
+  globalContent: string,
+  projectContent: string | undefined
+): string {
+  const parts: string[] = [
+    "<!-- BEGIN GLOBAL CONSTITUTION (team baseline — lower priority) -->",
+    globalContent.trim(),
+    "<!-- END GLOBAL CONSTITUTION -->",
+  ];
+
+  if (projectContent && projectContent.trim()) {
+    parts.push(
+      "",
+      "<!-- BEGIN PROJECT CONSTITUTION (project-specific — HIGHER priority, overrides global) -->",
+      projectContent.trim(),
+      "<!-- END PROJECT CONSTITUTION -->"
+    );
+  }
+
+  return parts.join("\n");
+}
+
+// ─── Save ─────────────────────────────────────────────────────────────────────
+
+/**
+ * Write a global constitution to disk.
+ * @param targetDir Directory to write to. Defaults to user home directory.
+ */
+export async function saveGlobalConstitution(
+  content: string,
+  targetDir: string = os.homedir()
+): Promise<string> {
+  const filePath = path.join(targetDir, GLOBAL_CONSTITUTION_FILE);
+  await fs.writeFile(filePath, content, "utf-8");
+  return filePath;
+}