septum 0.1.6 → 0.1.8

package/README.md

@@ -2,13 +2,13 @@
 
 > **Deterministic Bounded-Context & Anti-Poisoning Architecture Guard for AI Coding Agents.**
 
-[![Version: 0.1.5](https://img.shields.io/badge/Version-0.1.5-blue)](package.json)
+[![Version: 0.1.8](https://img.shields.io/badge/Version-0.1.8-blue)](package.json)
 [![Runtime: Bun](https://img.shields.io/badge/Runtime-Bun-black?logo=bun)](https://bun.sh)
 [![Protocol: Model Context Protocol](https://img.shields.io/badge/Protocol-MCP-green)](https://modelcontextprotocol.io/)
 [![Database: SQLite WAL](https://img.shields.io/badge/Database-SQLite%20(bun:sqlite)-003B57?logo=sqlite)](https://sqlite.org/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue)](LICENSE)
 
-Septum stops **context poisoning** in AI coding agents. It indexes your codebase into an embedded SQLite SSOT (`.septum/septum.db`), enforces strict bounded-context domains, and intercepts unauthorized cross-domain edits before they hit disk.
+Septum helps AI coding agents navigate code and respect declared architectural boundaries. It indexes your codebase into an embedded SQLite SSOT (`.septum/septum.db`), enforces strict bounded-context domains, and intercepts unauthorized cross-domain edits before they hit disk.
 
 ---
 
@@ -28,16 +28,26 @@ bun add -g septum
 
 ### 1. Initialize in Any Project
 
+Run `septum init` in your project root:
+
 ```bash
 septum init
 # or zero-install via bunx:
 bunx septum init
 ```
-*Auto-detects project topology (Monorepos, Laravel, Next.js, Go, NestJS), registers domains, and ingests AST symbols into `.septum/septum.db`.*
 
-### 2. Connect to AI Agent (MCP Server)
+Septum automatically:
+1. **Detects Architecture & Topology:** Discovers bounded domains across Monorepos, Laravel, Next.js, Go, NestJS, and more.
+2. **Builds AST Symbol SSOT:** Ingests symbols, interfaces, and dependencies into `.septum/septum.db`.
+3. **Scaffolds AI Agent Harnesses:** Interactively configures MCP servers, guardrail rules, and pre-write boundary hooks for your favorite agent environments:
+   - **Claude Code** (`.mcp.json`, `.claude/settings.json`)
+   - **Antigravity** (`.gemini/`)
+   - **Cursor** (`.cursor/mcp.json`, `.cursor/hooks.json`)
+   - **Opencode** (`opencode.json`)
+
+### 2. Manual MCP Client Configuration (Optional)
 
-Add Septum to your MCP client (`mcp.json` or `claude_desktop_config.json`):
+If your MCP client is not configured via `septum init`, add Septum manually (`mcp.json` or `claude_desktop_config.json`):
 
 ```json
 {
@@ -57,15 +67,12 @@ Add Septum to your MCP client (`mcp.json` or `claude_desktop_config.json`):
 
 | Command | Description |
 |---|---|
-| `septum init` | Detect topology, scaffold boundary guards, and build initial catalog |
-| `septum ingest` | Full AST re-indexing into `.septum/septum.db` |
-| `septum sync` | Fast incremental delta sync (< 15ms) for modified files |
-| `septum check --strict` | CI/CD gate: verify boundary integrity & fail on violations |
-| `septum query [domain]` | Inspect domain catalog, archetypes, and public signatures |
-| `septum locate <query>` | Locate symbol, class, interface, method, or error source |
-| `septum slice <route\|intent>` | Trace end-to-end vertical execution slice for route/intent |
-| `septum topology [action]` | Inspect 6-layer environment topology plane & distributed nodes |
-| `septum feature status\|clear` | Manage active feature lease and editing scope |
+| `septum init [--force]` | Detect topology, scaffold boundary guards, and build initial catalog. `--force` regenerates Septum-owned hooks and harness artifacts while strictly preserving SQLite DB, manual domain policies, and user Git hooks |
+| `septum sync [--json]` | AST synchronization and catalog update into `.septum/septum.db` (full or incremental) |
+| `septum check [--strict] [--staged] [--feature <name>] [--json]` | CI/CD gate & pre-commit hook: verify boundary integrity & fail on cross-domain violations |
+| `septum feature [status|clear] [--force]` | View or release active feature lease and editing scope (`--force` for other owner's session) |
+| `septum hook [subhook]` | Internal pre-tool guardrail hook (e.g. pre-write, post-write) for AI agent tools |
+| `septum topology [subcommand]` | Inspect 6-layer environment topology plane & distributed nodes (`env` alias available). Subcommands: `resolve <layer> <platform>`, `add-node`, `remove-node`, `clear` |
 | `septum serve` | Launch stdio MCP server for AI coding agents |
 
 ---
@@ -74,32 +81,26 @@ Add Septum to your MCP client (`mcp.json` or `claude_desktop_config.json`):
 
 All tools expose typed schemas automatically via the Model Context Protocol:
 
-- **Self-Aware Environment Topology (`septum_get_environment_topology`):** Maps and verifies the 6-layer production architecture (Edge/WAF, Gateway/Web Server, Host, Runtime, Storage/Cache, Telemetry) and distributed entities with cross-layer invariants.
-- **Whole-Project Telescope (`septum_get_domain_catalog`):** Returns macro architecture maps in < 400 tokens.
-- **Omni-Trigger Vertical Slice Tracer (`septum_trace_vertical_slice`):** Traces execution chains across HTTP routes, queue jobs, console commands, and event listeners (*Ingress ➔ Validation ➔ Orchestration ➔ Domain ➔ Egress*).
-- **Pre-Flight Boundary Guard (`septum_check_boundary`):** Validates proposed edits and imports against bounded-context rules.
-- **Scope Locking (`septum_get_feature_context` / `septum_clear_feature_context`):** Locks active feature scope to eliminate context drift.
-- **Symbol & Blast Radius (`septum_locate_symbol`, `septum_get_symbol`, `septum_get_symbol_impact`):** Resolves call chains, signatures, and refactoring impact.
-- **God Function & Nesting Detector (`septum_get_symbol_hotspots`):** Surfaces oversized functions/methods ranked by physical lines, cyclomatic nesting depth, and composite risk score.
-- **Dynamic Topology (`septum_register_domain`):** Registers or updates domains and boundary rules on-the-fly.
-
----
-
-## Development & Contributing
-
-```bash
-# Clone and install dependencies
-git clone https://github.com/shironim/septum.git
-cd septum
-bun install
-
-# Run test suite & build
-bun test
-bun run build
-```
+- **Domain Catalog, Registration & Environment Topology (`septum_domain`):**
+  - `action: "catalog"`: Whole-project macro architecture map and file connections in < 400 tokens (`detail_level: "compact" | "full"`).
+  - `action: "register"`: Dynamically registers or updates bounded-context domains with allowed/forbidden dependencies and layer archetypes.
+  - `action: "topology"`: Maps and verifies the 6-layer production architecture (Edge/WAF, Gateway/Web Server, Host, Runtime, Storage/Cache, Telemetry) and distributed nodes with cross-layer invariants.
+- **Unified Symbol Engine (`septum_symbol`):**
+  - `action: "locate"`: Fast fuzzy search and error log resolution to pinpoint symbols across workspaces.
+  - `action: "inspect"`: Deep inspection of physical coordinates, declarations, and full typed signatures.
+  - `action: "impact"`: Refactoring blast radius, call graphs, and inbound/outbound dependency analysis.
+  - `action: "hotspots"`: God function and Single Responsibility Principle (SRP) detector ranked by physical lines, cyclomatic nesting depth, and composite risk score.
+- **Omni-Trigger Vertical Slice Tracer (`septum_slice`):**
+  - Traces end-to-end execution flow (*Ingress ➔ Validation ➔ Controller ➔ Service ➔ Repository ➔ Entity*) from route URIs, controller actions, or high-level intent across HTTP routes, queue jobs, console commands, and events up to 8 levels deep.
+- **Architecture Guard & Circular Dependency Gate (`septum_boundary`):**
+  - Validates proposed edits, additions, and imports against domain rules and feature touchpoints before files are modified on disk (`scope: "file"`).
+  - Audits staged files (`scope: "staged"`), domain boundaries (`scope: "domain"`), or the entire repository (`scope: "all"`) for cross-domain leaks and dependency cycles.
+- **Active Touchpoint & Scope Lock Engine (`septum_feature`):**
+  - Locks active feature task context, touchpoints, and contracts (`action: "lock"` / `action: "get"` / `action: "release"`) via `.septum/session.json` to eliminate AI context drift and unintended edits.
 
 ---
 
 ## License
 
 [MIT](LICENSE) © shironim
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "septum",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "Deterministic Bounded-Context, Structural File Catalog & Anti-Poisoning Partition for AI Agents",
   "type": "module",
   "main": "src/index.ts",
@@ -18,13 +18,16 @@
     "check": "bun run bin/septum.ts check",
     "test": "bun test",
     "build": "bun build ./bin/septum.ts --compile --outfile dist/septum",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "test:integration": "python3 tests/integration/mcp-reliability.py",
+    "postinstall": "bun run scripts/postinstall.ts || true"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.5.0",
     "web-tree-sitter": "^0.24.0",
     "yaml": "^2.7.0",
-    "zod": "^3.24.2"
+    "zod": "^3.24.2",
+    "tree-sitter-wasms": "^0.1.13"
   },
   "license": "MIT",
   "repository": {
@@ -56,8 +59,6 @@
   "devDependencies": {
     "@types/bun": "latest",
     "@types/node": "^22.13.4",
-    "tree-sitter-wasms": "^0.1.13",
     "typescript": "^5.7.3"
   }
 }
-

package/src/cli/commands/check.ts

@@ -1,13 +1,10 @@
-import { execSync } from "node:child_process";
-import * as fs from "node:fs";
-import * as path from "node:path";
 import { BoundaryEvaluator } from "../../core/boundary/evaluator.ts";
-import type { ValidatedSeptumConfig } from "../../core/config/schema.ts";
 import { ConfigLoader } from "../../core/config/loader.ts";
 import { SeptumDatabase } from "../../core/database/client.ts";
 import { SeptumRepository } from "../../core/database/repository.ts";
-import { ASTParserEngine } from "../../core/parser/tree-sitter.ts";
 import type { BoundaryViolation } from "../../types/index.ts";
+import { IngestionPipeline } from "../../core/ingestion/pipeline.ts";
+import { auditStagedFiles } from "../../core/boundary/staged-auditor.ts";
 
 export interface CheckCommandOptions {
   strict?: boolean;
@@ -28,134 +25,49 @@ export async function handleCheckCommand(
   );
 
   const config = ConfigLoader.load();
+  if (options.strict) config.settings.enforcement = "strict";
   const db = new SeptumDatabase(config.settings.db_path);
   const repo = new SeptumRepository(db.raw);
   const evaluator = new BoundaryEvaluator(repo);
 
-  let violations: BoundaryViolation[] = [];
-
-  if (options.staged) {
-    violations = await auditStagedFiles(evaluator, config, options.feature);
-  } else {
-    violations = evaluator.auditCodebase(config);
-  }
-
-  if (violations.length === 0) {
-    console.log("✓ All domain boundaries are clean. Zero cross-domain leaks detected.");
-    db.close();
-    return;
-  }
-
-  console.error(`\n[Septum Boundary Violation] Found ${violations.length} boundary violation(s):\n`);
-
-  for (const v of violations) {
-    console.error(`  ✕ [${v.rule.toUpperCase()}] at ${v.file}:${v.line}`);
-    console.error(`    Source Domain:  ${v.source_domain}`);
-    console.error(`    Target Domain:  ${v.target_domain}`);
-    console.error(`    Import Target:  ${v.imported_target}`);
-    console.error(`    Message:        ${v.message}\n`);
-  }
-
-  db.close();
-
-  const isStrict = options.strict || config.settings.enforcement === "strict";
-  if (isStrict) {
-    console.error("[Septum Failure] Process terminated with exit code 1 due to boundary violations.");
-    process.exit(1);
-  }
-}
-
-async function auditStagedFiles(
-  evaluator: BoundaryEvaluator,
-  config: ValidatedSeptumConfig,
-  featureKey?: string
-): Promise<BoundaryViolation[]> {
-  const violations: BoundaryViolation[] = [];
-  let stagedFiles: string[] = [];
-
   try {
-    const gitOutput = execSync("git diff --cached --name-only --diff-filter=ACM", {
-      encoding: "utf-8",
-      timeout: 5000,
-      maxBuffer: 10 * 1024 * 1024,
-    });
-    stagedFiles = gitOutput
-      .split("\n")
-      .map((f) => f.trim())
-      .filter(Boolean);
-  } catch (err) {
-    const msg = err instanceof Error ? err.message : String(err);
-    console.warn(`[Septum Warning] Could not retrieve git staged files: ${msg}`);
-    return violations;
-  }
-
-  if (stagedFiles.length === 0) {
-    console.log("  Notice: No staged files found in git repository.");
-    return violations;
-  }
-
-  const astEngine = new ASTParserEngine();
-
-  for (const relPath of stagedFiles) {
-    const fullPath = path.resolve(process.cwd(), relPath);
-    if (!fs.existsSync(fullPath)) continue;
-
-    // 1. Feature touchpoint check if featureKey provided
-    if (featureKey) {
-      const tpViolations = evaluator.checkFeatureTouchpoints(featureKey, relPath, config);
-      violations.push(...tpViolations);
+    let violations: BoundaryViolation[] = [];
+
+    if (options.staged) {
+      violations = (await auditStagedFiles(evaluator, config, process.cwd(), options.feature, repo)).violations;
+    } else {
+      await new IngestionPipeline(repo).run(config, { verifyContent: true });
+      const unsupported = JSON.parse(repo.getMeta("unsupported_files") || "[]") as string[];
+      if (unsupported.length > 0) {
+        throw new Error(`Cannot complete boundary audit: unsupported source files: ${unsupported.join(", ")}`);
+      }
+      const skipped = JSON.parse(repo.getMeta("skipped_files") || "[]") as {path: string}[];
+      if (skipped.length) throw new Error(`Cannot complete boundary audit: files exceed resource limits: ${skipped.map(file => file.path).join(", ")}`);
+      violations = evaluator.auditCodebase(config);
     }
 
-    const sourceDomain = evaluator.resolveSourceDomain(relPath, config);
-    if (!sourceDomain) continue;
-
-    const sourceConfig = config.domains[sourceDomain];
-    if (!sourceConfig) continue;
-
-    const forbidden = sourceConfig.forbidden_dependencies ?? [];
-    const allowed = sourceConfig.allowed_dependencies ?? [];
-
-    try {
-      const content = fs.readFileSync(fullPath, "utf-8");
-      const parsed = await astEngine.parseFile(fullPath, content);
+    if (violations.length === 0) {
+      console.log("✓ All domain boundaries are clean. Zero cross-domain leaks detected.");
+      return;
+    }
 
-      for (const dep of parsed.dependencies) {
-        if (dep.is_external) continue;
+    console.error(`\n[Septum Boundary Violation] Found ${violations.length} boundary violation(s):\n`);
 
-        const targetDomain = evaluator.resolveTargetDomain(
-          dep.target,
-          config,
-          relPath
-        );
+    for (const v of violations) {
+      console.error(`  ✕ [${v.rule.toUpperCase()}] at ${v.file}:${v.line}`);
+      console.error(`    Source Domain:  ${v.source_domain}`);
+      console.error(`    Target Domain:  ${v.target_domain}`);
+      console.error(`    Import Target:  ${v.imported_target}`);
+      console.error(`    Message:        ${v.message}\n`);
+    }
 
-        if (!targetDomain || targetDomain === sourceDomain) continue;
 
-        if (forbidden.includes(targetDomain)) {
-          violations.push({
-            file: relPath,
-            line: dep.line_number,
-            source_domain: sourceDomain,
-            target_domain: targetDomain,
-            imported_target: dep.target,
-            rule: "forbidden_dependency",
-            message: `Illegal import: Domain '${sourceDomain}' is strictly prohibited from importing domain '${targetDomain}'.`,
-          });
-        } else if (config.settings.enforcement === "strict" && !allowed.includes(targetDomain)) {
-          violations.push({
-            file: relPath,
-            line: dep.line_number,
-            source_domain: sourceDomain,
-            target_domain: targetDomain,
-            imported_target: dep.target,
-            rule: "disallowed_dependency",
-            message: `Disallowed dependency: '${targetDomain}' is not declared in allowed_dependencies for domain '${sourceDomain}'.`,
-          });
-        }
-      }
-    } catch {
-      // Ignore unparseable files
+    const isStrict = options.strict || config.settings.enforcement === "strict";
+    if (isStrict) {
+      console.error("[Septum Failure] Process terminated with exit code 1 due to boundary violations.");
+      process.exitCode = 1;
     }
+  } finally {
+    db.close();
   }
-
-  return violations;
 }

package/src/cli/commands/hook.ts

@@ -7,8 +7,14 @@ import { SeptumRepository } from "../../core/database/repository.ts";
 import { ASTParserEngine } from "../../core/parser/tree-sitter.ts";
 import { SessionManager } from "../../core/session/session-manager.ts";
 
+interface ToolCallInfo {
+  name?: string;
+  args?: Record<string, unknown>;
+}
+
 export interface ToolPayload {
   tool_name?: string;
+  toolCall?: ToolCallInfo;
   tool_input?: {
     TargetFile?: string;
     file_path?: string;
@@ -30,8 +36,13 @@ export interface ToolPayload {
   CodeContent?: string;
 }
 
+let configuredExitCode = 1;
+
 export async function handleHookCommand(args: string[]): Promise<void> {
   const subHook = args[1] || "pre-write";
+  if (args.includes("--exit-code-2") || args.includes("--claude") || args.includes("--cursor")) {
+    configuredExitCode = 2;
+  }
 
   if (subHook === "pre-write") {
     await runPreWriteHook();
@@ -40,6 +51,34 @@ export async function handleHookCommand(args: string[]): Promise<void> {
   }
 }
 
+function blockHook(db: SeptumDatabase | null, reason: string): never {
+  if (db) {
+    try {
+      db.close();
+    } catch {
+      // ignore
+    }
+  }
+
+  // Print readable error to stderr for humans and Claude/Cursor/Codex
+  console.error(reason);
+
+  // Print JSON contract to stdout for Antigravity hook engine
+  try {
+    process.stdout.write(
+      JSON.stringify({
+        decision: "deny",
+        reason: reason.trim(),
+      }) + "\n"
+    );
+  } catch {
+    // ignore
+  }
+
+  // Exit code: 1 by default (Unix standard), or 2 if specified for Claude Code / Cursor hooks
+  process.exit(configuredExitCode);
+}
+
 async function runPreWriteHook(): Promise<void> {
   // If .septum/septum.db does not exist, pass through
   const dbPath = path.resolve(process.cwd(), ".septum", "septum.db");
@@ -62,7 +101,11 @@ async function runPreWriteHook(): Promise<void> {
   }
 
   const toolInput: Record<string, any> =
-    payload.tool_input || payload.arguments || (payload as Record<string, any>) || {};
+    payload.tool_input ||
+    payload.arguments ||
+    payload.toolCall?.args ||
+    (payload as Record<string, any>) ||
+    {};
   const targetFile: string | undefined =
     toolInput.TargetFile || toolInput.file_path || toolInput.filePath || toolInput.path;
   const chunkContent = Array.isArray(toolInput.ReplacementChunks)
@@ -115,27 +158,28 @@ async function runPreWriteHook(): Promise<void> {
       }
 
       if (!hasConsulted) {
-        console.error(
+        blockHook(
+          db,
           `\n[SEPTUM GATE 3 VIOLATION - Mandatory Consultation Required]\n` +
             `✕ Operation blocked: You are attempting to write to domain '${sourceDomain}' (${targetFile}) ` +
             `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`
+            `▶ REQUIRED ACTION: Call tool 'septum_domain({ action: "catalog", domain: "${sourceDomain}", detail_level: "compact" })' ` +
+            `or 'septum_feature({ action: "get" })' before writing code.\n`
         );
-        db.close();
-        process.exit(1);
       }
     }
 
     // -------------------------------------------------------------
     // GATE 1: Hard Touchpoint Lock (if features are defined)
     // -------------------------------------------------------------
-    const features = config.features ?? {};
     const session = SessionManager.getActiveSession(process.cwd());
-    const activeFeatureKey =
-      toolInput.feature_key || process.env.SEPTUM_ACTIVE_FEATURE || session?.feature_key;
+    const requestedFeatureKey = toolInput.feature_key || process.env.SEPTUM_ACTIVE_FEATURE;
+    if (session && requestedFeatureKey && requestedFeatureKey !== session.feature_key) {
+      throw new Error(`Requested feature '${requestedFeatureKey}' does not own the active scope '${session.feature_key}'.`);
+    }
+    const activeFeatureKey = session?.feature_key || requestedFeatureKey;
 
-    if (activeFeatureKey && features[activeFeatureKey]) {
+    if (activeFeatureKey) {
       const touchpointViolations = evaluator.checkFeatureTouchpoints(
         activeFeatureKey,
         targetFile,
@@ -143,14 +187,13 @@ async function runPreWriteHook(): Promise<void> {
       );
 
       if (touchpointViolations.length > 0) {
-        console.error(
+        blockHook(
+          db,
           `\n[SEPTUM GATE 1 VIOLATION - Scope Touchpoint Lock]\n` +
             `✕ Operation blocked: File '${targetFile}' is outside the declared allowed_touchpoints for feature '${activeFeatureKey}'.\n` +
             `▶ REASON: ${touchpointViolations[0].message}\n` +
             `▶ REQUIRED ACTION: Only modify files declared in allowed_touchpoints for this feature.\n`
         );
-        db.close();
-        process.exit(1);
       }
     }
 
@@ -161,6 +204,9 @@ async function runPreWriteHook(): Promise<void> {
     if (content && sourceDomain) {
       const astEngine = new ASTParserEngine();
       const parsed = await astEngine.parseFile(targetFile, content);
+      if (ASTParserEngine.isSourceFile(targetFile) && (parsed.status === "unsupported" || parsed.status === "degraded")) {
+        throw new Error(`Cannot reliably check imports in '${targetFile}': parser status is ${parsed.status}.`);
+      }
 
       const proposedImports = parsed.dependencies.map((d) => d.target);
       const boundaryViolations = evaluator.checkProposedChanges(
@@ -171,7 +217,8 @@ async function runPreWriteHook(): Promise<void> {
 
       if (boundaryViolations.length > 0) {
         const v = boundaryViolations[0];
-        console.error(
+        blockHook(
+          db,
           `\n[SEPTUM GATE 2 VIOLATION - Forbidden Cross-Domain Import]\n` +
             `✕ Operation blocked: Proposed code imports forbidden domain '${v.target_domain}' from '${v.source_domain}'.\n` +
             `▶ OFFENDING IMPORT: ${v.imported_target}\n` +
@@ -179,12 +226,17 @@ async function runPreWriteHook(): Promise<void> {
             `▶ MESSAGE: ${v.message}\n` +
             `▶ REQUIRED ACTION: Decouple this dependency. Use an authorized Interface, Event, or Shared Kernel.\n`
         );
-        db.close();
-        process.exit(1);
       }
     }
 
     db.close();
+
+    // If running in Antigravity or standard JSON IPC mode, emit allow decision
+    try {
+      process.stdout.write(JSON.stringify({ decision: "allow" }) + "\n");
+    } catch {
+      // ignore
+    }
     process.exit(0);
   } catch (err) {
     db.close();