septum 0.1.5 → 0.1.7

package/src/cli/templates/rules.ts

@@ -1,38 +1,50 @@
-export const SEPTUM_RULES_TEMPLATE = `# Septum Bounded-Context & Anti-Poisoning Partition Rules
+export const SEPTUM_RULES_TEMPLATE = `# Septum Bounded-Context, Anti-Duplication & File Connectivity Rules
 
-> **Prinsip Utama:** Proyek ini menggunakan **Septum** untuk menegakkan batasan arsitektur (bounded-context) secara deterministik. Setiap AI Coding Agent wajib mematuhi aturan batas domain dan touchpoint berikut.
+> **Prinsip Utama:** Proyek ini menggunakan **Septum** (\`.septum/septum.db\`) sebagai Single Source of Truth (SSOT) untuk memetakan seluruh class, fungsi, method, struct/interface, dan variabel/konstanta beserta keterhubungan antar-file. Setiap AI Coding Agent **dilarang membuat simbol duplikat** dan wajib mematuhi batas domain.
 
 ---
 
-## 1. Single Source of Truth (SSOT) via Septum MCP
-
-Sebelum menulis atau mengedit file backend/domain:
-1. **Dilarang Menebak Kontrak Domain:**
-   Gunakan tool MCP \`septum_get_domain_catalog(domain: "...")\` untuk memeriksa file, arketipe, dan signature publik yang sah di dalam domain tersebut.
-2. **Kunci Scope pada Fitur Aktif:**
-   Jika sedang mengerjakan fitur spesifik yang terdaftar di katalog Septum, panggil \`septum_get_feature_context(feature: "...")\`.
-   * **Wajib patuhi \`allowed_touchpoints\`:** Jangan menyentuh atau memodifikasi file di luar daftar yang diizinkan untuk fitur tersebut.
-   * **Wajib gunakan ulang \`reuse_symbols\`:** Jangan membuat fungsi atau helper duplikat jika simbol tersebut sudah terdaftar di \`reuse_symbols\`.
+## 1. Anti-Duplikasi Simbol & Peta Keterhubungan File (Wajib Sebelum Coding)
+
+Sebelum membuat class, fungsi, method, tipe, atau variabel/konstanta baru di file backend:
+1. **Periksa Peta Domain & Koneksi File (Compact Mode < 400 Token):**
+   Panggil \`septum_get_domain_catalog({ domain: "<nama_domain>", detail_level: "compact" })\` (atau tanpa \`domain\` untuk *Macro Semantic Map*).
+   * Perhatikan daftar simbol eksisting (\`class\`, \`interface\`, \`struct\`, \`function\`, \`type\`, \`constant\`, \`variable\`) beserta \`line_span\`-nya.
+   * Perhatikan \`connections.imports_from\` (file mana saja yang diimpor oleh file tersebut) dan \`connections.imported_by_count\` (berapa file lain yang bergantung padanya).
+   * Jika membutuhkan daftar signature method lengkap pada satu file, panggil \`septum_get_symbol({ symbol: "<NamaSimbol>" })\` atau \`septum_get_domain_catalog({ domain: "<nama_domain>", detail_level: "full", file_filter: "<nama_file>" })\`.
+2. **Cari Simbol Lintas-Domain Sebelum Membuat Baru:**
+   Panggil \`septum_locate_symbol({ query: "<kata_kunci>" })\` untuk memastikan fungsi/helper/class yang ingin dibuat belum ada di codebase.
+3. **Kunci Scope pada Fitur Aktif:**
+   Jika mengerjakan fitur terdaftar, panggil \`septum_get_feature_context({ feature_key: "<nama_fitur>" })\`:
+   * **Patuhi \`allowed_touchpoints\`:** Jangan memodifikasi file di luar daftar touchpoint fitur aktif.
+   * **Gunakan ulang \`reuse_symbols\`:** Wajib mengimpor dan memakai kembali simbol yang terdaftar di \`reuse_symbols\`.
 
 ---
 
-## 2. Pre-Flight Boundary Check Sebelum Menulis Kode
+## 2. Audit Blast Radius & Alur Eksekusi Sebelum Refactoring
 
-Sebelum mengeksekusi penulisan file (\`write_to_file\` atau \`replace_file_content\`):
-1. Panggil tool MCP:
+1. **Cek Dampak Simbol (\`inbound_callers\`):**
+   Sebelum mengubah parameter/return signature atau menghapus class/fungsi/method publik, wajib panggil:
    \`\`\`json
-   septum_check_boundary({
-     "file_path": "path/ke/file.ts",
-     "proposed_imports": ["target_import_statement"],
-     "feature_key": "nama_fitur_opsional"
-   })
+   septum_get_symbol_impact({ "symbol": "NamaClassAtauFungsi" })
    \`\`\`
-2. **Rejection Handling:** Jika Septum mengembalikan status \`rejected\` (\`forbidden_dependency\`, \`disallowed_dependency\`, atau \`touchpoint_violation\`), **BATALKAN** rencana penulisan tersebut dan cari rute arsitektur yang sah (misal melalui Interface/Shared-Kernel yang diizinkan).
+   Periksa seluruh \`inbound_callers\` (termasuk *named imports* lintas file) agar tidak memutus kontrak file pemanggil.
+2. **Telusuri Vertical Slice (Default Depth 5, Max Depth 8):**
+   Gunakan \`septum_trace_vertical_slice({ query: "<route|command|handler>", max_depth: 5 })\` (naikkan hingga \`max_depth: 8\` untuk alur Event/Job/Queue berlapis) guna memahami rantai eksekusi dari Ingress hingga Repository/Entity.
 
 ---
 
-## 3. Anti Local Scope Myopia
+## 3. Pre-Flight Boundary & Circular Dependency Check
 
-* Dilarang menghapus fungsi publik atau mengubah signature class hanya karena fungsi tersebut tidak terlihat dipanggil di file lokal yang sedang diedit.
-* Pastikan seluruh dependensi inbound/outbound mematuhi batasan domain yang terdaftar di database Septum (\`.septum/septum.db\`).
+1. **Sebelum Menulis Import Lintas-Domain (\`write_to_file\` / \`replace_file_content\`):**
+   \`\`\`json
+   septum_check_boundary({
+     "file_path": "path/ke/file.ts",
+     "proposed_imports": ["../other-domain/service"],
+     "feature_key": "opsional_feature_key"
+   })
+   \`\`\`
+2. **Audit Menyeluruh & Deteksi Siklus (\`circular_dependency\`):**
+   Jalankan \`septum_check_boundary({ scope: "staged" })\` atau \`septum_check_boundary({ scope: "all" })\` setelah menyelesaikan perubahan multi-file. Jika status \`rejected\` (\`forbidden_dependency\`, \`disallowed_dependency\`, \`touchpoint_violation\`, atau \`circular_dependency\`), batalkan/perbaiki arsitektur import sebelum melakukan commit.
 `;
+

package/src/cli/templates/skill.ts

@@ -1,69 +1,65 @@
 export const SEPTUM_MAP_SKILL_TEMPLATE = `---
 name: septum-map
-description: Framework-agnostic codebase discovery, architectural domain mapping, and bounded-context initialization for Septum. Uses AI reasoning to map unknown project topologies (JS/TS, PHP, Python, Go), auto-registers bounded contexts into Septum's SQLite catalog, and enforces deterministic architectural boundaries.
+description: Framework-agnostic codebase discovery, multi-language AST symbol & file-connection mapping, and bounded-context governance for Septum. Uses Tree-Sitter WASM (TS/JS/TSX, PHP, Python, Go, Rust, Java, C#, Ruby + Vue/Svelte/Astro/Blade) and SQLite SSOT (.septum/septum.db) to prevent symbol duplication, map file integrations, and enforce architectural boundaries.
 ---
 
-# \`septum-map\` — Framework-Agnostic Semantic Discovery & Bounded-Context Initialization
+# \`septum-map\` — Multi-Language AST Discovery, File Connectivity & Bounded-Context Governance
 
-> **Prinsip Utama:** AI Agent berperan sebagai *The Architect* untuk membedah topologi arsitektur proyek apa pun tanpa terikat pada framework tertentu, merumuskan batas bounded-context, dan mendaftarkannya langsung ke database deterministik (.septum/septum.db via septum_register_domain) agar AI coding berikutnya tidak mengalami context poisoning atau over-editing.
+> **Prinsip Utama:** Septum memetakan setiap fungsi, class, method, struct/interface, dan variabel/konstanta di file backend beserta keterhubungan dua arah antar-file (\`imports_from\` & \`imported_by\`) ke dalam SQLite SSOT (\`.septum/septum.db\`). Dengan peta deterministik ini, AI Agent **tidak boleh menduplikasi simbol yang sudah ada** dan wajib menjaga integritas batas domain (*bounded-context*) serta mencegah *circular dependency*.
 
 ---
 
-## 1. Landasan Riset & Filosofi Desain
+## 1. Landasan Arsitektur & Pencegahan Duplikasi
 
-Skill ini berakar langsung pada riset rekayasa perangkat lunak terkemuka:
-1. **Software Reflexion Models (Murphy, Notkin, & Sullivan, IEEE TSE):**
-   Membedakan model arsitektur tingkat tinggi yang dirancang (*high-level intention*) dengan implementasi fisik di kode sumber. Septum mendeteksi *Divergences* (pelanggaran baru) dan *Absences* sebelum kode di-merge.
-2. **Eliminasi Over-Editing (SWE-bench, RepoCoder - NeurIPS / ICLR):**
-   Akar kegagalan agen AI terbesar adalah mengedit file di luar lokus tugas (*local scope myopia*). \`septum-map\` menetapkan *bounded context* dan *allowed touchpoints* sejak awal.
-3. **Principle of Least Privilege & Object-Capabilities (Miller):**
-   Agen hanya diberikan kapabilitas membaca dan mengubah file dalam domain/fitur aktif, memangkas *blast radius* kesalahan hingga mendekati nol.
-4. **Hybrid Defense (SynCode / NeMo Guardrails):**
-   Probabilistic AI digunakan untuk penalaran awal (*discovery & blueprinting*), sementara eksekusi dan penegakannya 100% deterministik (*Tree-sitter WASM, SQLite WAL, Pre-Commit Hooks*).
+1. **Anti-Symbol Duplication (Peta Simbol & Keterhubungan File):**
+   Setiap file yang diindeks oleh mesin \`web-tree-sitter\` Septum memiliki daftar simbol terstruktur (\`class\`, \`interface\`, \`struct\`, \`trait\`, \`enum\`, \`function\`, \`method\`, \`type\`, \`constant\`, \`variable\`) serta graf koneksi dua arah (\`connections.imports_from\` dan \`connections.imported_by_count\`). Agen wajib memeriksa peta ini sebelum membuat fungsi, class, atau variabel baru.
+2. **Software Reflexion Models & Boundary Enforcement:**
+   Septum memvalidasi rencana perubahan kode terhadap aturan \`allowed_dependencies\`, \`forbidden_dependencies\`, \`allowed_touchpoints\`, dan mendeteksi siklus dependensi (\`circular_dependency\`) baik per-file maupun lintas-domain.
+3. **Token-Budgeted Context (< 400 Tokens Default):**
+   Katalog domain secara default disajikan dalam mode ringkas (\`detail_level: "compact"\`) agar agen memperoleh topologi file, rentang baris (\`line_span\`), jumlah method/property, dan koneksi antar-file tanpa membanjiri jendela konteks.
 
 ---
 
-## 2. Kapan Wajib Menggunakan (Trigger Moments)
+## 2. Referensi Cepat 12 Tool MCP Septum (Standardized \`snake_case\` Contracts)
+
+| Tool MCP | Parameter Utama (\`snake_case\`) | Fungsi & Kapan Digunakan |
+|---|---|---|
+| **\`septum_get_domain_catalog\`** | \`{ domain?, detail_level?: "compact"\\|"full", archetype_filter?, file_filter? }\` | Tanpa \`domain\`: menampilkan *Macro Semantic Map* seluruh proyek. Dengan \`domain\`: menampilkan daftar file, \`connections\` (\`imports_from\`, \`imported_by_count\`), dan simbol di domain tersebut (\`compact\` default < 400 token). |
+| **\`septum_locate_symbol\`** | \`{ query, domain?, limit?: 10 }\` | Mencari lokasi file dan baris (\`line_start\`-\`line_end\`) dari class, fungsi, method (\`Class::method\`), struct, atau konstanta. |
+| **\`septum_get_symbol\`** | \`{ symbol, domain?, include_dependencies?: true }\` | Mengekstrak detail kontrak simbol: signature, \`exact_range\`, \`dependencies_injected\`, \`outbound_calls\`, \`sibling_methods\`, dan \`connected_files\`. |
+| **\`septum_get_symbol_impact\`** | \`{ symbol }\` | Menghitung *blast radius* (\`inbound_callers\`, \`total_dependents\`, \`risk_level\`) termasuk pelacakan *named imports* lintas file sebelum mengubah signature. |
+| **\`septum_trace_vertical_slice\`** | \`{ query, max_depth?: 5 }\` | Menelusuri alur eksekusi end-to-end (\`Ingress ➔ Validation ➔ Controller ➔ Service ➔ Repository ➔ Entity\`). \`max_depth\` default \`5\`, rentang \`1..8\` (gunakan \`6..8\` untuk deep trace Event/Job/Queue). |
+| **\`septum_check_boundary\`** | \`{ file_path?, file_paths?, proposed_imports?, feature_key?, scope?: "file"\\|"all"\\|"staged"\\|"domain", domain? }\` | **Pre-Write:** memvalidasi \`proposed_imports\` pada \`file_path\`. **Macro Audit:** panggil dengan \`{ scope: "all" }\` atau \`{ scope: "staged" }\` untuk mengaudit seluruh batas domain & *circular dependencies*. |
+| **\`septum_get_symbol_hotspots\`** | \`{ domain?, min_lines?: 30, min_nesting?, kind?, limit?: 30, sort_by?: "risk_score" }\` | Mengidentifikasi fungsi/class paling kompleks berdasarkan \`risk_score\` (\`line_count\` $\\times$ \`nesting_depth\`). |
+| **\`septum_get_feature_context\`** | \`{ feature_key? }\` | Mengambil konteks fitur aktif (\`allowed_touchpoints\`, \`reuse_symbols\`, input/output contract). |
+| **\`septum_clear_feature_context\`** | \`{}\` | Melepaskan kunci sesi fitur aktif di \`.septum/session.json\`. |
+| **\`septum_register_domain\`** | \`{ domain, root, description?, allowed_dependencies?, forbidden_dependencies?, archetypes?, ingest_now?: true }\` | Mendaftarkan atau memperbarui bounded-context domain langsung ke SQLite SSOT (\`.septum/septum.db\`). |
+| **\`septum_register_feature\`** | \`{ feature_key, domain, description?, allowed_touchpoints?, reuse_symbols?, input_contract?, output_contract? }\` | Mendaftarkan kontrak fitur baru ke SQLite SSOT dan mengaktifkan sesi *touchpoint lock*. |
+| **\`septum_get_environment_topology\`** | \`{ resolve?, resolveNode?, refresh? }\` | Memetakan 6-layer topologi infrastruktur (\`EDGE\`, \`GATEWAY\`, \`HOST\`, \`RUNTIME\`, \`STORAGE\`, \`TELEMETRY\`) beserta invarian lintas-layer. |
+
+---
+
+## 3. Alur Kerja Pemetaan & Inisialisasi Domain (The 4-Step Lifecycle)
 
 > [!NOTE] Zero-Config Default (\`septum init\`)
-> Untuk mayoritas proyek (library kecil/menengah, layered monolith standar, MVC, CLI, MCP tools), pengguna atau agen **cukup menjalankan \`septum init\`** di terminal. Perintah \`septum init\` secara default berjalan 100% otomatis tanpa wawancara manual (zero-config heuristic auto-detect & auto-ingest).
+> Menjalankan \`septum init\` di terminal secara otomatis mendeteksi bahasa & framework (TS/JS, PHP/Laravel, Python, Go, Rust, Java, C#, Ruby), mendaftarkan domain ke \`.septum/septum.db\`, mengindeks AST via Tree-Sitter WASM, dan memasang hook di \`.agents/\`.
 
-Gunakan alur 4 langkah skill ini HANYA saat:
-1. Memetakan domain bisnis kustom / modular DDD enterprise yang kompleks di mana batasan dependency non-standar perlu disepakati bersama Tech Lead.
-2. Memetakan ulang domain bisnis setelah terjadi refactoring arsitektur besar (*re-mapping*).
-3. Mengonfigurasi sesi fitur baru (\`features\` session) untuk mengunci daftar file yang boleh dimodifikasi (*allowed_touchpoints*) dan simbol yang wajib dipakai ulang (*reuse_symbols*).
-4. Pengguna secara eksplisit meminta konsultasi desain domain boundary interaktif.
+Gunakan alur 4 langkah ini saat merancang domain baru, melakukan *re-mapping* arsitektur, atau mengunci kontrak fitur:
 
----
+### Langkah 1: Topological & Connectivity Scan (Maksimal 2 Tool Call)
+1. Panggil \`septum_get_domain_catalog({})\` untuk memeriksa *Telescope View* dan daftar domain yang terdaftar.
+2. Panggil \`septum_get_domain_catalog({ domain: "<target>", detail_level: "compact" })\` untuk memetakan file, simbol yang sudah ada, dan koneksi \`imports_from\` / \`imported_by_count\`.
+
+### Langkah 2: Perumusan Kontrak Domain & Anti-Duplikasi Simbol
+* **\`domain\` & \`root\`:** Nama domain dan direktori kanonikalnya.
+* **\`allowed_dependencies\` & \`forbidden_dependencies\`:** Whitelist dan blacklist dependensi lintas-domain.
+* **\`reuse_symbols\`:** Daftar class, service, repository, atau konstanta eksisting yang **wajib digunakan kembali** agar agen tidak membuat kode duplikat.
 
-## 3. Alur Kerja 4 Langkah (The 4-Step Discovery Lifecycle)
-
-### Langkah 1: Topological Scan (Maksimal 2 Tool Call)
-Analisis karakteristik proyek secara framework-agnostic:
-1. **Periksa Manifest & Config Root:**
-   * JS/TS: \`package.json\`, \`tsconfig.json\` (baca dependencies, path aliases).
-   * PHP: \`composer.json\` (baca \`autoload.psr-4\`, framework dependencies).
-   * Python: \`pyproject.toml\`, \`requirements.txt\`, \`setup.py\` (baca modules & framework).
-   * Go: \`go.mod\` (baca module path).
-2. **Petakan Direktori Tingkat Atas:**
-   Identifikasi apakah proyek menggunakan pola:
-   * *Domain-Driven / Vertical Slice:* \`src/domains/\`, \`app/Domain/\`, \`features/\`.
-   * *Layered / Clean Architecture:* \`core/\`, \`infrastructure/\`, \`application/\`, \`interfaces/\`.
-   * *Framework Conventional:* NestJS modules, Laravel app folders, FastAPI routers, Next.js route groups.
-
-### Langkah 2: Semantic Blueprint Drafting & Domain Boundary Formulation
-Rumuskan spesifikasi domain dengan prinsip **Contract & Invariants (Bukan Prosedural)**:
-* **\`root\`:** Direktori fisik domain (gunakan path kanonikal).
-* **\`allowed_dependencies\`:** Domain mana saja yang sah diimpor (inbound whitelist).
-* **\`forbidden_dependencies\`:** Domain yang dilarang keras diimpor (outbound blacklist).
-* **\`archetypes\`:** Pola glob penamaan layer (\`service: "*Service.*"\`, \`model: "*Model.*"\`).
-
-### Langkah 3: Human-in-the-Loop Approval Gate
-Tampilkan ringkasan domain boundary yang dirumuskan kepada pengguna / Tech Lead untuk disetujui atau disesuaikan sebelum didaftarkan.
-
-### Langkah 4: Deterministic Registration & Ingestion
-Setelah disetujui:
-1. Daftarkan domain secara langsung via tool MCP \`septum_register_domain(domain_name, root, ...)\` dengan opsi \`ingest_now: true\`.
-2. Atau jalankan CLI \`septum ingest\` untuk mengekstrak seluruh simbol AST dan menyimpannya ke database SQLite \`.septum/septum.db\`.
-3. Pastikan hook pre-commit terpasang aktif di \`.git/hooks/pre-commit\`.
+### Langkah 3: Registrasi Deterministik ke SQLite SSOT
+1. Gunakan \`septum_register_domain({ domain, root, allowed_dependencies, forbidden_dependencies, ingest_now: true })\` untuk menyimpan batas domain.
+2. Gunakan \`septum_register_feature({ feature_key, domain, allowed_touchpoints, reuse_symbols })\` untuk mengunci fokus pengerjaan fitur.
+
+### Langkah 4: Verifikasi Boundary & Siklus Dependensi
+Jalankan \`septum_check_boundary({ scope: "all" })\` (atau CLI \`septum check --staged\`) untuk memastikan 0 pelanggaran batas domain dan 0 *circular dependency*.
 `;
+

package/src/core/boundary/evaluator.ts

@@ -1,3 +1,4 @@
+import { posix, relative, resolve, isAbsolute } from "node:path";
 import type { BoundaryViolation } from "../../types/index.ts";
 import type { ValidatedSeptumConfig } from "../config/schema.ts";
 import { ConfigLoader } from "../config/loader.ts";
@@ -23,7 +24,14 @@ export class BoundaryEvaluator {
     featureKey?: string,
     config?: ValidatedSeptumConfig
   ): BoundaryViolation[] {
-    const activeConfig = config ?? ConfigLoader.loadFromDatabaseOrDefaults();
+    let activeConfig = config;
+    if (!activeConfig) {
+      const fromRepo = ConfigLoader.loadFromRepository(this.repo);
+      activeConfig =
+        Object.keys(fromRepo.domains).length > 0
+          ? fromRepo
+          : ConfigLoader.loadFromDatabaseOrDefaults();
+    }
     const violations: BoundaryViolation[] = [];
 
     if (featureKey) {
@@ -83,6 +91,202 @@ export class BoundaryEvaluator {
       }
     }
 
+    violations.push(...this.detectCircularDependencies(config, allDependencies));
+
+    return violations;
+  }
+
+  public detectCircularDependencies(
+    config: ValidatedSeptumConfig,
+    preloadedDeps?: Array<{
+      source_file: string;
+      source_domain: string;
+      line_number: number;
+      target: string;
+      statement: string;
+      is_external: boolean;
+    }>,
+    relevantFiles?: ReadonlySet<string>
+  ): BoundaryViolation[] {
+    const violations: BoundaryViolation[] = [];
+    const allDependencies = preloadedDeps ?? this.repo.getAllDependenciesWithDomains();
+
+    // Prepare file lookup maps for internal file-to-file resolution
+    const fileByNormPath = new Map<string, string>();
+    const fileByNoExtPath = new Map<string, string>();
+
+    const registerKnownFile = (rawPath: string) => {
+      const norm = rawPath.replace(/\\/g, "/").replace(/^\.\//, "");
+      fileByNormPath.set(norm.toLowerCase(), rawPath);
+      const noExt = norm.replace(/\.[^/.]+$/, "").toLowerCase();
+      fileByNoExtPath.set(noExt, rawPath);
+      if (noExt.endsWith("/index")) {
+        fileByNoExtPath.set(noExt.slice(0, -"/index".length), rawPath);
+      }
+    };
+
+    if (typeof this.repo.getAllFiles === "function") {
+      for (const f of this.repo.getAllFiles()) {
+        registerKnownFile(f.path);
+      }
+    }
+    for (const d of allDependencies) {
+      registerKnownFile(d.source_file);
+    }
+
+    const resolveTargetFile = (sourceFile: string, rawTarget: string): string | null => {
+      const cleaned = rawTarget.trim().replace(/^['"]|['"]$/g, "").replace(/\\/g, "/");
+      if (!cleaned) return null;
+
+      if (cleaned.startsWith(".")) {
+        const srcDir = posix.dirname(sourceFile.replace(/\\/g, "/"));
+        const joined = posix.normalize(posix.join(srcDir, cleaned)).replace(/^\.\//, "");
+        const lowerJoined = joined.toLowerCase();
+        const exact =
+          fileByNormPath.get(lowerJoined) ??
+          fileByNoExtPath.get(lowerJoined.replace(/\.[^/.]+$/, ""));
+        if (exact) return exact;
+      }
+
+      const aliasClean = cleaned.replace(/^@\//, "src/").replace(/^\.\//, "");
+      const lowerAlias = aliasClean.toLowerCase();
+      const byAlias =
+        fileByNormPath.get(lowerAlias) ??
+        fileByNoExtPath.get(lowerAlias.replace(/\.[^/.]+$/, ""));
+      if (byAlias) return byAlias;
+
+      return null;
+    };
+
+    type EdgeMeta = {
+      files: Set<string>;
+      file: string;
+      line: number;
+      source_domain: string;
+      target_domain: string;
+      target: string;
+    };
+
+    const fileGraph = new Map<string, Map<string, EdgeMeta>>();
+    const domainGraph = new Map<string, Map<string, EdgeMeta>>();
+
+    for (const dep of allDependencies) {
+      if (dep.is_external) continue;
+
+      const targetDomain = this.resolveTargetDomain(dep.target, config, dep.source_file);
+
+      // 1. Domain-to-domain edge
+      if (targetDomain && targetDomain !== dep.source_domain) {
+        let outMap = domainGraph.get(dep.source_domain);
+        if (!outMap) {
+          outMap = new Map();
+          domainGraph.set(dep.source_domain, outMap);
+        }
+        if (!outMap.has(targetDomain)) {
+          outMap.set(targetDomain, {
+            files: new Set([dep.source_file]),
+            file: dep.source_file,
+            line: dep.line_number,
+            source_domain: dep.source_domain,
+            target_domain: targetDomain,
+            target: dep.target,
+          });
+        }
+        outMap.get(targetDomain)!.files.add(dep.source_file);
+      }
+
+      // 2. File-to-file edge
+      const targetFile = resolveTargetFile(dep.source_file, dep.target);
+      if (targetFile && targetFile !== dep.source_file) {
+        let outMap = fileGraph.get(dep.source_file);
+        if (!outMap) {
+          outMap = new Map();
+          fileGraph.set(dep.source_file, outMap);
+        }
+        if (!outMap.has(targetFile)) {
+          outMap.set(targetFile, {
+            files: new Set([dep.source_file]),
+            file: dep.source_file,
+            line: dep.line_number,
+            source_domain: dep.source_domain,
+            target_domain: targetDomain ?? dep.source_domain,
+            target: dep.target,
+          });
+        }
+      }
+    }
+
+    const findCycles = (
+      graph: Map<string, Map<string, EdgeMeta>>,
+      kindLabel: "file" | "domain"
+    ) => {
+      const visited = new Set<string>();
+      const inStack = new Set<string>();
+      const stack: string[] = [];
+      const reportedCycles = new Set<string>();
+
+      const canonicalizeCycle = (nodes: string[]): string => {
+        if (nodes.length === 0) return "";
+        let minIdx = 0;
+        for (let i = 1; i < nodes.length; i++) {
+          if (nodes[i] < nodes[minIdx]) minIdx = i;
+        }
+        const rotated = [...nodes.slice(minIdx), ...nodes.slice(0, minIdx)];
+        return rotated.join("->");
+      };
+
+      const dfs = (node: string) => {
+        visited.add(node);
+        inStack.add(node);
+        stack.push(node);
+
+        const neighbors = graph.get(node);
+        if (neighbors) {
+          for (const [nextNode, edgeMeta] of neighbors.entries()) {
+            if (!visited.has(nextNode)) {
+              dfs(nextNode);
+            } else if (inStack.has(nextNode)) {
+              const cycleStartIndex = stack.indexOf(nextNode);
+              if (cycleStartIndex !== -1) {
+                const cycleNodes = stack.slice(cycleStartIndex);
+                const sig = canonicalizeCycle(cycleNodes);
+                const cycleEdges = cycleNodes.map((source, index) => graph.get(source)?.get(cycleNodes[(index + 1) % cycleNodes.length]));
+                if (relevantFiles && !cycleEdges.some(edge => edge && [...edge.files].some(file => relevantFiles.has(file)))) continue;
+                if (!reportedCycles.has(sig)) {
+                  reportedCycles.add(sig);
+                  const firstNode = cycleNodes[0];
+                  const secondNode = cycleNodes[1] ?? nextNode;
+                  const firstEdge = graph.get(firstNode)?.get(secondNode) ?? edgeMeta;
+                  const cycleDisplay = [...cycleNodes, cycleNodes[0]].join(" -> ");
+                  violations.push({
+                    file: firstEdge.file,
+                    line: firstEdge.line,
+                    source_domain: firstEdge.source_domain,
+                    target_domain: firstEdge.target_domain,
+                    imported_target: firstEdge.target,
+                    rule: "circular_dependency",
+                    message: `Circular ${kindLabel} dependency detected: ${cycleDisplay}.`,
+                  });
+                }
+              }
+            }
+          }
+        }
+
+        stack.pop();
+        inStack.delete(node);
+      };
+
+      for (const startNode of graph.keys()) {
+        if (!visited.has(startNode)) {
+          dfs(startNode);
+        }
+      }
+    };
+
+    findCycles(fileGraph, "file");
+    findCycles(domainGraph, "domain");
+
     return violations;
   }
 
@@ -181,39 +385,28 @@ export class BoundaryEvaluator {
       return violations;
     }
 
-    const normalizedTarget = targetFilePath.replace(/\\/g, "/").replace(/^\.\//, "");
+    const root = this.resolver.getProjectRoot();
+    const normalizedTarget = relative(root, resolve(root, targetFilePath.replace(/\\/g, "/"))).replace(/\\/g, "/");
     const allowedTouchpoints = featureConfig.allowed_touchpoints.map((tp) =>
-      tp.replace(/\\/g, "/").replace(/^\.\//, "")
+      isAbsolute(tp) ? relative(root, tp).replace(/\\/g, "/") : posix.normalize(tp.replace(/\\/g, "/"))
     );
 
     const domainCfg = config.domains[featureConfig.domain];
     const domainRoot = domainCfg?.root ? domainCfg.root.replace(/\\/g, "/").replace(/^\.\//, "") : "";
 
-    const isAllowed = allowedTouchpoints.some((pattern) => {
+    const matches = (pattern: string): boolean => {
       if (pattern.endsWith("/**")) {
-        const prefix = pattern.slice(0, -3);
-        return normalizedTarget.startsWith(prefix);
+        return normalizedTarget.startsWith(pattern.slice(0, -3) + "/");
       }
       if (pattern.endsWith("/*")) {
-        const prefix = pattern.slice(0, -2);
-        return normalizedTarget.startsWith(prefix);
-      }
-      if (normalizedTarget === pattern) return true;
-
-      if (
-        domainRoot &&
-        (normalizedTarget === `${domainRoot}/${pattern}` ||
-          normalizedTarget.startsWith(`${domainRoot}/${pattern}`))
-      ) {
-        return true;
+        const prefix = pattern.slice(0, -2) + "/";
+        return normalizedTarget.startsWith(prefix) && !normalizedTarget.slice(prefix.length).includes("/");
       }
-
-      if (pattern.includes("/") && normalizedTarget.endsWith("/" + pattern)) {
-        return true;
-      }
-
-      return false;
-    });
+      return normalizedTarget === pattern;
+    };
+    const isAllowed = allowedTouchpoints.some(pattern =>
+      matches(pattern) || Boolean(domainRoot && matches(posix.normalize(`${domainRoot}/${pattern}`)))
+    );
 
     if (!isAllowed) {
       violations.push({

package/src/core/boundary/staged-auditor.ts

@@ -0,0 +1,47 @@
+import { execFileSync } from "node:child_process";
+import { resolve } from "node:path";
+import type { BoundaryViolation } from "../../types/index.ts";
+import type { ValidatedSeptumConfig } from "../config/schema.ts";
+import { ASTParserEngine } from "../parser/tree-sitter.ts";
+import type { SeptumRepository } from "../database/repository.ts";
+import type { BoundaryEvaluator } from "./evaluator.ts";
+
+export async function auditStagedFiles(
+  evaluator: BoundaryEvaluator,
+  config: ValidatedSeptumConfig,
+  workspaceRoot: string,
+  featureKey?: string,
+  repo?: SeptumRepository
+): Promise<{ files: string[]; violations: BoundaryViolation[] }> {
+  const output = execFileSync("git", ["diff", "--cached", "--name-only", "--diff-filter=ACMR", "-z"], {
+    cwd: workspaceRoot, encoding: "utf-8", timeout: 5000, maxBuffer: 10 * 1024 * 1024,
+  });
+  const files = output.split("\0").filter(Boolean);
+  const deletedOutput = execFileSync("git", ["diff", "--cached", "--name-only", "--diff-filter=D", "-z"], {
+    cwd: workspaceRoot, encoding: "utf-8", timeout: 5000, maxBuffer: 10 * 1024 * 1024,
+  });
+  const deleted = deletedOutput.split("\0").filter(Boolean);
+  const violations: BoundaryViolation[] = [];
+  if (featureKey) for (const file of deleted) violations.push(...evaluator.checkFeatureTouchpoints(featureKey, file, config));
+  const stagedDependencies: ReturnType<SeptumRepository["getAllDependenciesWithDomains"]> = [];
+  const parser = new ASTParserEngine();
+  for (const file of files) {
+    if (featureKey) violations.push(...evaluator.checkFeatureTouchpoints(featureKey, file, config));
+    if (!ASTParserEngine.isSourceFile(file) || !evaluator.resolveSourceDomain(file, config)) continue;
+    const content = execFileSync("git", ["show", `:${file}`], {
+      cwd: workspaceRoot, encoding: "utf-8", timeout: 5000, maxBuffer: 10 * 1024 * 1024,
+    });
+    const parsed = await parser.parseFile(resolve(workspaceRoot, file), content);
+    if (parsed.status === "unsupported" || parsed.status === "degraded") {
+      throw new Error(`Cannot reliably parse staged file '${file}': ${parsed.status}.`);
+    }
+    for (const dependency of parsed.dependencies) {
+      stagedDependencies.push({ source_file: file, source_domain: evaluator.resolveSourceDomain(file, config)!, target: dependency.target, statement: dependency.statement, line_number: dependency.line_number, is_external: dependency.is_external });
+      violations.push(...evaluator.checkProposedChanges(file, [dependency.target], config).map(violation => ({ ...violation, line: dependency.line_number })));
+    }
+  }
+  const staged = new Set([...files, ...deleted]);
+  const baseline = (repo?.getAllDependenciesWithDomains() || []).filter(dependency => !staged.has(dependency.source_file));
+  violations.push(...evaluator.detectCircularDependencies(config, [...baseline, ...stagedDependencies], staged));
+  return { files, violations };
+}

package/src/core/config/loader.ts

@@ -62,6 +62,29 @@ export class ConfigLoader {
     };
   }
 
+  public static loadFromRepository(repo: SeptumRepository): ValidatedSeptumConfig {
+    const config = ConfigLoader.getDefaultConfig();
+    if (repo && typeof repo.getAllDomains === "function") {
+      const rows = repo.getAllDomains();
+      for (const row of rows) {
+        config.domains[row.name] = {
+          root: row.root_path,
+          allowed_dependencies: JSON.parse(row.allowed_deps_json || "[]"),
+          forbidden_dependencies: JSON.parse(row.forbidden_deps_json || "[]"),
+          archetypes: JSON.parse(row.archetypes_json || "{}"),
+        };
+      }
+    }
+
+    if (typeof repo?.getMeta === "function") {
+      const features = repo.getMeta("features_json");
+      if (features) config.features = JSON.parse(features);
+      const settings = repo.getMeta("settings_json");
+      if (settings) Object.assign(config.settings, JSON.parse(settings));
+    }
+    return config;
+  }
+
   public static loadFromDatabaseOrDefaults(dbPath: string = ".septum/septum.db"): ValidatedSeptumConfig {
     const config = ConfigLoader.getDefaultConfig();
     config.settings.db_path = dbPath;
@@ -75,20 +98,14 @@ export class ConfigLoader {
           )
           .get("domains");
 
-        if (tables) {
-          const rows = db.query<any, []>("SELECT * FROM domains").all();
-          for (const r of rows) {
-            config.domains[r.name] = {
-              root: r.root_path,
-              allowed_dependencies: JSON.parse(r.allowed_deps_json || "[]"),
-              forbidden_dependencies: JSON.parse(r.forbidden_deps_json || "[]"),
-              archetypes: JSON.parse(r.archetypes_json || "{}"),
-            };
-          }
+        try {
+          if (tables) Object.assign(config, ConfigLoader.loadFromRepository(new SeptumRepository(db)));
+          config.settings.db_path = dbPath;
+        } finally {
+          db.close();
         }
-        db.close();
       } catch {
-        // Fallback gracefully to default config
+        throw new Error(`Cannot load Septum configuration from '${dbPath}'.`);
       }
     }