septum 0.1.5 → 0.1.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "septum",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "Deterministic Bounded-Context, Structural File Catalog & Anti-Poisoning Partition for AI Agents",
   "type": "module",
   "main": "src/index.ts",

package/src/cli/commands/hook.ts

@@ -8,14 +8,26 @@ import { ASTParserEngine } from "../../core/parser/tree-sitter.ts";
 import { SessionManager } from "../../core/session/session-manager.ts";
 
 export interface ToolPayload {
-  tool_name: string;
-  tool_input: {
+  tool_name?: string;
+  tool_input?: {
     TargetFile?: string;
     file_path?: string;
+    filePath?: string;
+    path?: string;
     ReplacementContent?: string;
     CodeContent?: string;
+    new_string?: string;
+    content?: string;
+    ReplacementChunks?: Array<{ ReplacementContent?: string }>;
     feature_key?: string;
   };
+  arguments?: Record<string, unknown>;
+  TargetFile?: string;
+  file_path?: string;
+  filePath?: string;
+  path?: string;
+  ReplacementContent?: string;
+  CodeContent?: string;
 }
 
 export async function handleHookCommand(args: string[]): Promise<void> {
@@ -49,9 +61,20 @@ async function runPreWriteHook(): Promise<void> {
     process.exit(0);
   }
 
-  const toolInput = payload.tool_input || {};
-  const targetFile = toolInput.TargetFile || toolInput.file_path;
-  const content = toolInput.ReplacementContent || toolInput.CodeContent || "";
+  const toolInput: Record<string, any> =
+    payload.tool_input || payload.arguments || (payload as Record<string, any>) || {};
+  const targetFile: string | undefined =
+    toolInput.TargetFile || toolInput.file_path || toolInput.filePath || toolInput.path;
+  const chunkContent = Array.isArray(toolInput.ReplacementChunks)
+    ? toolInput.ReplacementChunks.map((c: any) => c?.ReplacementContent || "").join("\n")
+    : "";
+  const content: string =
+    toolInput.ReplacementContent ||
+    toolInput.CodeContent ||
+    toolInput.new_string ||
+    toolInput.content ||
+    chunkContent ||
+    "";
 
   if (!targetFile) {
     process.exit(0);
@@ -77,7 +100,12 @@ async function runPreWriteHook(): Promise<void> {
       if (fs.existsSync(accessLogPath)) {
         try {
           const rawAccess = JSON.parse(fs.readFileSync(accessLogPath, "utf-8"));
-          const domainAccessedAt = rawAccess.domains?.[sourceDomain];
+          const domainsMap: Record<string, string> = rawAccess.domains || {};
+          const lowerSource = sourceDomain.toLowerCase();
+          const domainAccessedAt =
+            domainsMap[sourceDomain] ||
+            domainsMap[lowerSource] ||
+            Object.entries(domainsMap).find(([k]) => k.toLowerCase() === lowerSource)?.[1];
           if (domainAccessedAt) {
             hasConsulted = true;
           }
@@ -90,8 +118,8 @@ async function runPreWriteHook(): Promise<void> {
         console.error(
           `\n[SEPTUM GATE 3 VIOLATION - Mandatory Consultation Required]\n` +
             `✕ Operation blocked: You are attempting to write to domain '${sourceDomain}' (${targetFile}) ` +
-            `without inspecting its authoritative catalog first.\n` +
-            `▶ REQUIRED ACTION: Call tool 'septum_get_domain_catalog(domain: "${sourceDomain}")' ` +
+            `without inspecting its authoritative symbol & file-connection catalog first.\n` +
+            `▶ REQUIRED ACTION: Call tool 'septum_get_domain_catalog({ domain: "${sourceDomain}", detail_level: "compact" })' ` +
             `or 'septum_get_feature_context' before writing code.\n`
         );
         db.close();

package/src/cli/commands/init.ts

@@ -9,20 +9,22 @@ import {
 import { SEPTUM_RULES_TEMPLATE } from "../templates/rules.ts";
 import { SEPTUM_MAP_SKILL_TEMPLATE } from "../templates/skill.ts";
 import { TopologyDetector } from "../../core/discovery/topology-detector.ts";
+import { EnvironmentDetector } from "../../core/topology/environment-detector.ts";
 import { SeptumDatabase } from "../../core/database/client.ts";
 import { SeptumRepository } from "../../core/database/repository.ts";
 
 export async function handleInitCommand(force: boolean = false): Promise<void> {
-  console.log("[Septum] Initializing Septum bounded-context environment (Zero-Config)...\n");
+  console.log("[Septum] Initializing Septum bounded-context & AST environment (Zero-Config SQLite SSOT)...\n");
 
   const cwd = process.cwd();
   const dbPath = ".septum/septum.db";
 
   // 1. Auto-discover project topology and persist to SQLite SSOT
-  console.log("  • Analyzing codebase topology and modular boundaries...");
+  console.log("  • Analyzing codebase topology, modular boundaries, and 6-layer environment plane...");
   const db = new SeptumDatabase(dbPath);
   const repo = new SeptumRepository(db.raw);
   const domains = TopologyDetector.discoverAndPersist(repo, cwd);
+  EnvironmentDetector.detect(cwd, repo);
   const domainNames = Object.keys(domains);
   console.log(`  ✓ Discovered and registered ${domainNames.length} domains directly in SQLite (${dbPath}):`);
   for (const name of domainNames) {
@@ -40,12 +42,12 @@ export async function handleInitCommand(force: boolean = false): Promise<void> {
   scaffoldAgentCustomizations(cwd);
 
   // 5. Run initial codebase ingestion
-  console.log("\n[Septum] Running initial ingestion to build deterministic structural catalog...");
+  console.log("\n[Septum] Running initial Tree-Sitter WASM ingestion to build symbol & file-connection catalog...");
   try {
     await handleIngestCommand();
     console.log("\n✓ Septum successfully initialized and ready for production use!");
     console.log("  • Pre-commit hook is active (runs 'septum check --staged' before each commit).");
-    console.log("  • AI Agent skill '/septum-map' and boundary hooks installed in '.agents/'.");
+    console.log("  • AI Agent skill '/septum-map', anti-duplication rules, and boundary hooks installed in '.agents/'.");
     console.log("  • MCP server is ready for AI coding agents via 'septum serve'.\n");
   } catch (err: unknown) {
     const message = err instanceof Error ? err.message : String(err);

package/src/cli/commands/query.ts

@@ -1,8 +1,29 @@
 import { ConfigLoader } from "../../core/config/loader.ts";
 import { SeptumDatabase } from "../../core/database/client.ts";
 import { SeptumRepository } from "../../core/database/repository.ts";
+import type { DomainCatalogResponse } from "../../types/index.ts";
+
+export interface QueryCommandOptions {
+  json?: boolean;
+  full?: boolean;
+  file?: string;
+}
+
+export async function handleQueryCommand(
+  domainName?: string,
+  archetype?: string,
+  jsonOutputOrOptions?: boolean | QueryCommandOptions,
+  extraOptions?: QueryCommandOptions
+): Promise<void> {
+  const options: QueryCommandOptions =
+    typeof jsonOutputOrOptions === "boolean"
+      ? { json: jsonOutputOrOptions, ...extraOptions }
+      : { ...jsonOutputOrOptions, ...extraOptions };
+
+  const jsonOutput = Boolean(options.json);
+  const detailLevel: "compact" | "full" = options.full ? "full" : "compact";
+  const fileFilter = options.file;
 
-export async function handleQueryCommand(domainName?: string, archetype?: string, jsonOutput?: boolean): Promise<void> {
   const config = ConfigLoader.load();
   const db = new SeptumDatabase(config.settings.db_path);
   const repo = new SeptumRepository(db.raw);
@@ -23,7 +44,11 @@ export async function handleQueryCommand(domainName?: string, archetype?: string
     return;
   }
 
-  const catalog = repo.getDomainCatalog(domainName, archetype);
+  const catalog: DomainCatalogResponse | null = (repo.getDomainCatalog as any)(
+    domainName,
+    archetype,
+    { detailLevel, fileFilter }
+  );
   if (!catalog) {
     console.error(`[Septum Error] Domain '${domainName}' not found in database. Run 'septum ingest' first.`);
     db.close();
@@ -36,15 +61,26 @@ export async function handleQueryCommand(domainName?: string, archetype?: string
     console.log(`=================================================`);
     console.log(`  Domain: ${catalog.domain.toUpperCase()} (Root: ${catalog.root})`);
     console.log(`=================================================`);
+    console.log(`  Detail Level:            ${catalog.detail_level ?? detailLevel}`);
     console.log(`  Allowed Dependencies:    [${catalog.allowed_dependencies.join(", ")}]`);
     console.log(`  Forbidden Dependencies:  [${catalog.forbidden_dependencies.join(", ")}]`);
-    console.log(`  Total Files Cataloged:   ${catalog.files.length}`);
+    console.log(`  Total Files Cataloged:   ${catalog.total_files ?? catalog.files.length} (Showing: ${catalog.showing_files ?? catalog.files.length})`);
     console.log(`-------------------------------------------------`);
 
     for (const file of catalog.files) {
-      console.log(`\n  File: ${file.path} [archetype: ${file.archetype}]`);
+      const lineInfo = file.line_count ? `, ${file.line_count} lines` : "";
+      console.log(`\n  File: ${file.path} [archetype: ${file.archetype}${lineInfo}]`);
+      if (file.connections) {
+        const importsStr = file.connections.imports_from.length > 0 ? file.connections.imports_from.join(", ") : "none";
+        console.log(`    ↔ Connections: imports [${importsStr}] | imported by ${file.connections.imported_by_count} file(s)`);
+      }
       for (const sym of file.symbols) {
-        console.log(`    • ${sym.kind.toUpperCase()} ${sym.name}`);
+        const spanStr = sym.line_span ? ` (L${sym.line_span})` : "";
+        const countsStr =
+          sym.methods_count !== undefined
+            ? ` [${sym.methods_count} methods${sym.properties_count ? `, ${sym.properties_count} props` : ""}]`
+            : "";
+        console.log(`    • ${sym.kind.toUpperCase()} ${sym.name}${spanStr}${countsStr}`);
         if (sym.methods && sym.methods.length > 0) {
           for (const m of sym.methods) {
             console.log(`        - ${m}`);
@@ -57,8 +93,12 @@ export async function handleQueryCommand(domainName?: string, archetype?: string
         }
       }
     }
+    if (catalog.agent_hint) {
+      console.log(`\n  💡 ${catalog.agent_hint}`);
+    }
     console.log(`\n=================================================`);
   }
 
   db.close();
 }
+

package/src/cli/commands/slice.ts

@@ -5,15 +5,16 @@ import { VerticalSliceTracer } from "../../core/resolver/vertical-slice-tracer.t
 
 export async function handleSliceCommand(
   query: string,
-  options?: { json?: boolean }
+  options?: { json?: boolean; maxDepth?: number }
 ): Promise<void> {
   const config = ConfigLoader.load();
   const db = new SeptumDatabase(config.settings.db_path);
   const repo = new SeptumRepository(db.raw);
 
   try {
+    const maxDepth = Math.min(Math.max(Math.trunc(Number(options?.maxDepth ?? 5)), 1), 8);
     const tracer = new VerticalSliceTracer(repo);
-    const result = tracer.trace(query);
+    const result = (tracer.trace as any)(query, maxDepth);
 
     if (options?.json) {
       console.log(JSON.stringify(result, null, 2));
@@ -46,3 +47,4 @@ export async function handleSliceCommand(
     db.close();
   }
 }
+

package/src/cli/index.ts

@@ -22,9 +22,12 @@ export async function runCLI(argv: string[]): Promise<void> {
         version: { type: "boolean", short: "v" },
         force: { type: "boolean", short: "f" },
         json: { type: "boolean" },
+        full: { type: "boolean" },
+        file: { type: "string" },
         strict: { type: "boolean" },
         staged: { type: "boolean" },
         domain: { type: "string", short: "d" },
+        "max-depth": { type: "string" },
         archetype: { type: "string", short: "a" },
         feature: { type: "string" },
       },
@@ -73,7 +76,9 @@ export async function runCLI(argv: string[]): Promise<void> {
         const domainName = positionals[1];
         const archetype = typeof flags.archetype === "string" ? flags.archetype : undefined;
         const jsonOutput = Boolean(flags.json);
-        await handleQueryCommand(domainName, archetype, jsonOutput);
+        const full = Boolean(flags.full);
+        const file = typeof flags.file === "string" ? flags.file : undefined;
+        await handleQueryCommand(domainName, archetype, { json: jsonOutput, full, file });
         break;
       }
 
@@ -92,11 +97,16 @@ export async function runCLI(argv: string[]): Promise<void> {
       case "slice": {
         const query = positionals[1];
         if (!query) {
-          console.error("Usage: septum slice <route-or-intent> [--json]");
+          console.error("Usage: septum slice <route-or-intent> [-d|--max-depth <number>] [--json]");
           process.exit(1);
         }
         const json = Boolean(flags.json);
-        await handleSliceCommand(query, { json });
+        const rawDepth = flags["max-depth"] ?? flags.domain;
+        const parsedDepth = rawDepth !== undefined ? Number(rawDepth) : 5;
+        const maxDepth = !Number.isNaN(parsedDepth)
+          ? Math.min(Math.max(Math.trunc(parsedDepth), 1), 8)
+          : 5;
+        await handleSliceCommand(query, { json, maxDepth });
         break;
       }
 
@@ -183,11 +193,11 @@ COMMANDS:
 
   Structural Discovery:
     query [domain]        Query structural catalog for a domain or whole project
-                          Flags: -a, --archetype <name>, --json
+                          Flags: -a, --archetype <name>, --full, --file <filter>, --json
     locate <query>        Locate symbol, class, interface, method, or error source
                           Flags: -d, --domain <name>, --json
     slice <route|intent>  Trace end-to-end vertical execution slice for route/intent
-                          Flags: --json
+                          Flags: -d, --max-depth <number>, --json
 
   Boundary & Enforcement:
     check                 Audit codebase for cross-domain boundary violations

package/src/cli/templates/hooks.ts

@@ -2,7 +2,7 @@ export const SEPTUM_HOOKS_CONFIG = {
   "septum-boundary-guard": {
     "PreToolUse": [
       {
-        "matcher": "write_to_file|replace_file_content",
+        "matcher": "write_to_file|replace_file_content|multi_replace_file_content|Write|Edit|MultiEdit",
         "hooks": [
           {
             "type": "command",
@@ -14,7 +14,7 @@ export const SEPTUM_HOOKS_CONFIG = {
     ],
     "PostToolUse": [
       {
-        "matcher": "write_to_file|replace_file_content",
+        "matcher": "write_to_file|replace_file_content|multi_replace_file_content|Write|Edit|MultiEdit",
         "hooks": [
           {
             "type": "command",
@@ -61,13 +61,13 @@ fi
 
 # Trigger background incremental sync
 if command -v bun >/dev/null 2>&1 && [ -f "$ROOT_DIR/bin/septum.ts" ]; then
-  bun run "$ROOT_DIR/bin/septum.ts" sync --json >/dev/null 2>&1 &
+  bun run "$ROOT_DIR/bin/septum.ts" sync >/dev/null 2>&1 &
 elif command -v septum >/dev/null 2>&1; then
-  septum sync --json >/dev/null 2>&1 &
+  septum sync >/dev/null 2>&1 &
 elif [ -f "$ROOT_DIR/node_modules/.bin/septum" ]; then
-  "$ROOT_DIR/node_modules/.bin/septum" sync --json >/dev/null 2>&1 &
+  "$ROOT_DIR/node_modules/.bin/septum" sync >/dev/null 2>&1 &
 elif command -v bunx >/dev/null 2>&1; then
-  bunx septum sync --json >/dev/null 2>&1 &
+  bunx septum sync >/dev/null 2>&1 &
 fi
 
 exit 0

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*.
 `;
+