septum 0.1.7 → 0.1.8

package/README.md

@@ -2,7 +2,7 @@
 
 > **Deterministic Bounded-Context & Anti-Poisoning Architecture Guard for AI Coding Agents.**
 
-[![Version: 0.1.7](https://img.shields.io/badge/Version-0.1.7-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/)
@@ -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` | Incremental synchronization of modified files 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,29 +81,22 @@ 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.
 
 ---
 
@@ -104,22 +104,3 @@ bun run build
 
 [MIT](LICENSE) © shironim
 
-## Reliability and Scope
-
-`septum check --strict` enables strict dependency rules before evaluating the codebase. A full check synchronizes the index first. CLI and MCP staged checks read Git index blobs, so unstaged edits cannot hide a violation in the proposed commit. Staged checks also evaluate dependency cycles using indexed dependencies with staged imports overlaid.
-
-Domain ownership uses the most specific normalized root in both full and single-file ingestion. Feature touchpoints are normalized against the workspace; `/*` permits immediate children and `/**` permits descendants.
-
-Each active MCP workspace has a watcher. Changes to multiple files are batched without dropping earlier paths; deletion and directory moves reconcile the catalog. If a native watcher is unavailable, Septum falls back to polling and synchronizes before answering queries. Catalog responses expose `index_status.watcher_mode` and `index_status.unsupported_files`. Single-file updates invalidate cached execution slices; the next trace rebuilds them.
-
-Tree-sitter grammars are runtime dependencies and are embedded in compiled executables. The active extractors cover TypeScript/JavaScript, PHP/Blade, Python, Go, and script extraction from Vue/Svelte/Astro. Rust, Java, C#, and Ruby do not yet have active extractors. Unsupported files are reported explicitly; an incomplete audit does not receive a clean approval. Unindexed symbols return `risk_level: "unknown"`.
-
-Feature sessions have a single owner per workspace. The default owner is the MCP process; set `SEPTUM_SESSION_ID` when several commands intentionally share the same owner. Another owner cannot replace or release the active session. Use `septum feature clear --force` for explicit recovery after a process exits or for a legacy session without ownership metadata.
-
-Run the real-server integration checks with Python 3:
-
-```bash
-bun run test:integration
-```
-
-These checks exercise live rule changes, Git staged blobs, multiple workspaces, rapid edits, directory moves, and unsupported-file diagnostics. The normal `bun test` suite includes a standalone-binary regression for forbidden multiline imports.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "septum",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "description": "Deterministic Bounded-Context, Structural File Catalog & Anti-Poisoning Partition for AI Agents",
   "type": "module",
   "main": "src/index.ts",
@@ -19,7 +19,8 @@
     "test": "bun test",
     "build": "bun build ./bin/septum.ts --compile --outfile dist/septum",
     "typecheck": "tsc --noEmit",
-    "test:integration": "python3 tests/integration/mcp-reliability.py"
+    "test:integration": "python3 tests/integration/mcp-reliability.py",
+    "postinstall": "bun run scripts/postinstall.ts || true"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.5.0",

package/src/cli/commands/check.ts

@@ -41,6 +41,8 @@ export async function handleCheckCommand(
       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);
     }
 

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,15 +158,14 @@ 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);
       }
     }
 
@@ -145,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);
       }
     }
 
@@ -176,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` +
@@ -184,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();