septum 0.1.5 → 0.1.7

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.7](https://img.shields.io/badge/Version-0.1.7-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.
 
 ---
 
@@ -59,7 +59,7 @@ Add Septum to your MCP client (`mcp.json` or `claude_desktop_config.json`):
 |---|---|
 | `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 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 |
@@ -103,3 +103,23 @@ bun run build
 ## License
 
 [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.5",
+  "version": "0.1.7",
   "description": "Deterministic Bounded-Context, Structural File Catalog & Anti-Poisoning Partition for AI Agents",
   "type": "module",
   "main": "src/index.ts",
@@ -18,13 +18,15 @@
     "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"
   },
   "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 +58,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,47 @@ 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(", ")}`);
+      }
+      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

@@ -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();
@@ -102,12 +130,14 @@ async function runPreWriteHook(): Promise<void> {
     // -------------------------------------------------------------
     // 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,
@@ -133,6 +163,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(

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;
       }
 
@@ -122,7 +132,7 @@ export async function runCLI(argv: string[]): Promise<void> {
       case "feature": {
         const sub = positionals[1];
         if (sub === "clear") {
-          const cleared = SessionManager.clearActiveSession(process.cwd());
+          const cleared = SessionManager.clearActiveSession(process.cwd(), undefined, Boolean(flags.force));
           if (cleared) {
             console.log("✓ Active feature session successfully cleared.");
           } else {
@@ -183,16 +193,17 @@ 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
                           Flags: --strict, --staged, --feature <name>
     feature [status|clear] View or release active feature context session lock
+                          Flags: --force (explicit recovery of another owner's session)
     hook [subhook]        Internal pre-tool guardrail hook (e.g. pre-write)
 
   Environment & Topology:

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