@cuzfrog/pi-module-gates 0.15.0 → 0.17.0

package/README.md

@@ -1,6 +1,6 @@
 # pi-module-gates - Constraints liberate, liberties constrain.
 
-Expirimental pi cli extension that controls the entropy of the codebase by enforcing code module boundaries.
+Experimental pi cli extension that controls the entropy of the codebase by enforcing code module boundaries.
 It helps combat slop generation and code architecture degradation.
 
 ## Problem
@@ -12,7 +12,7 @@ AI coding agents produce edits with limited context knowledge (myopia) — their
 **Module contracts as guardrails.** Each directory can contain a descriptor file that declares:
 
 - `readonly` — files and directories the agent must not touch
-- `frozen` — files where no new exports are allowed
+- `sealed` — files where no new exports are allowed (body still editable)
 - `visible` — the set of exports allowed to be added or modified in that module
 
 The extension intercepts agent `write`/`edit` operations and enforces these contracts. Violations are blocked with a clear reason.
@@ -26,7 +26,7 @@ The attempt to add 2 public helper functions is blocked, forcing the agent to re
 2. **System prompt** — Injects a hint so the agent knows to respect descriptor file conventions.
 3. **Gating** — On every write/edit, checks:
    - **Readonly gate** — is the target file locked?
-     **Fronzen gate** — is there any surface change to the target file?
+     **Sealed gate** — would the change add new exports to a file in the `sealed` list?
    - **Export gate** — would the change introduce an export not in the `visible` list?
    - **Module interface import gate** — external files can only import from the module not internal files, i.e. re-exports from `index.ts` or `mod.rs`. A child module may import from a parent module's internal files (not recommended but allowed). (Only Typescript/JavaScript and Rust are supported)
    - **Import gate** (not implemented yet) — would the change introduce an import violating visibility scope?
@@ -57,14 +57,14 @@ readonly: [mod.rs]
 Any prose for the agent to better understand the module.
 ```
 
-### Frozen constraints
+### Sealed constraints
 
 ```yaml
-frozen: [mod.rs]
+sealed: [mod.rs]
 ```
-Frozen files cannot change their surface size: no new exports or public entries are allowed.
+Sealed files cannot change their surface size: no new exports or public entries are allowed. The file body is still editable.
 
-A skill [module-freeze-all](src/skills/module-freeze-all) has been included to auto-freeze modules.
+A skill [module-seal-all](skills/module-seal-all) has been included to auto-seal modules.
 
 ### Visibility whitelist (under redesign)
 
@@ -134,6 +134,47 @@ Add a `module-gates` entry to `.pi/settings.json`:
 
 When no settings file exists or no `module-gates` key is present, defaults apply.
 
+## Claude Code Support
+
+### Install
+Add the following to `.claude/settings.json` in the current project, pointing the `PreToolUse` hook at the installed binary.
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Edit|MultiEdit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bun ${CLAUDE_PROJECT_DIR}/node_modules/@cuzfrog/pi-module-gates/src/claude/pre-tool-use.ts",
+            "statusMessage": "Module gate checking edit..."
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+If `pi-module-gates` is already installed in pi global dir, you can use below path instead:
+```
+~/.pi/agent/npm/node_modules/@cuzfrog/pi-module-gates/src/claude/pre-tool-use.ts
+```
+
+### System prompt
+You need to add [system-prompt.md](src/context/system-prompt.template.md) manually to your context.
+
+### Configuration
+
+Claude Code uses the same `.pi/settings.json#module-gates` block as the pi extension. See the Configuration section above.
+
+### Troubleshooting
+Prompt:
+```
+Check if PreToolUse hook `pi-module-gates` is triggered and runs expectedly.
+```
+
 ## License
 
 MIT

package/bin/pi-module-gates.mjs

@@ -0,0 +1,80 @@
+#!/usr/bin/env bun
+// Bin entrypoint: executed by `bun` (see package.json#bin) and dispatches to
+// src/cli/*.ts modules. Lives in .mjs for npm-install shebang compatibility on
+// platforms that resolve `bin` to a file path directly; `bun` will load this as
+// JavaScript since it has no TypeScript-specific syntax.
+import { resolve, isAbsolute } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const PKG_ROOT = resolve(fileURLToPath(new URL(".", import.meta.url)), "..");
+
+function printUsage() {
+  process.stderr.write(`Usage: pi-module-gates <command> [...args]
+
+Commands:
+  install-claude [--project-dir <dir>]    Install Claude Code PreToolUse hooks into <dir>/.claude/settings.json
+  uninstall-claude [--project-dir <dir>]  Remove Claude Code PreToolUse hooks from <dir>/.claude/settings.json
+
+Environment:
+  CLAUDE_PROJECT_DIR    Default --project-dir when running inside Claude Code.
+
+Examples:
+  pi-module-gates install-claude
+  pi-module-gates install-claude --project-dir /path/to/project
+  pi-module-gates uninstall-claude
+`);
+}
+
+function parseProjectDir(argv) {
+  let projectDir = process.env.CLAUDE_PROJECT_DIR ?? process.cwd();
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === "--project-dir" && i + 1 < argv.length) {
+      projectDir = argv[++i];
+    }
+  }
+  return isAbsolute(projectDir) ? projectDir : resolve(process.cwd(), projectDir);
+}
+
+async function main() {
+  const [cmd, ...rest] = process.argv.slice(2);
+  if (!cmd) {
+    printUsage();
+    process.exit(1);
+  }
+  if (cmd === "-h" || cmd === "--help") {
+    printUsage();
+    process.exit(0);
+  }
+
+  const projectDir = parseProjectDir(rest);
+
+  if (cmd === "install-claude") {
+    const mod = await import(resolve(PKG_ROOT, "src/cli/install-claude.ts"));
+    const result = mod.installClaude({ projectDir });
+    if (!result.ok) {
+      process.stderr.write(`${result.reason}\n`);
+      process.exit(1);
+    }
+    process.exit(0);
+  }
+
+  if (cmd === "uninstall-claude") {
+    const mod = await import(resolve(PKG_ROOT, "src/cli/uninstall-claude.ts"));
+    const result = mod.uninstallClaude({ projectDir });
+    if (!result.ok) {
+      process.stderr.write(`${result.reason}\n`);
+      process.exit(1);
+    }
+    process.exit(0);
+  }
+
+  process.stderr.write(`Unknown command: ${cmd}\n`);
+  printUsage();
+  process.exit(2);
+}
+
+main().catch((err) => {
+  const message = err instanceof Error ? err.message : String(err);
+  process.stderr.write(`[pi-module-gates] Unexpected error: ${message}\n`);
+  process.exit(1);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cuzfrog/pi-module-gates",
-  "version": "0.15.0",
+  "version": "0.17.0",
   "description": "pi extension that controls the entropy of the codebase by enforcing code module boundaries.",
   "keywords": [
     "pi-package"
@@ -10,6 +10,9 @@
     "check": "tsc --noEmit",
     "test": "vitest run"
   },
+  "bin": {
+    "pi-module-gates": "./bin/pi-module-gates.mjs"
+  },
   "pi": {
     "extensions": [
       "./src/index.ts"
@@ -18,12 +21,16 @@
       "./skills"
     ]
   },
+  "dependencies": {
+    "yaml": "2.8.1"
+  },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "*"
   },
   "devDependencies": {
     "@earendil-works/pi-coding-agent": "0.79.8",
     "@types/node": "22.19.19",
+    "bun-types": "1.3.14",
     "typescript": "5.9.3",
     "vitest": "4.1.7"
   },
@@ -40,11 +47,12 @@
   "files": [
     "src/",
     "skills/",
+    "bin/",
     "README.md",
     "LICENSE"
   ],
   "engines": {
-    "node": ">=18"
+    "bun": ">=1.3.0"
   },
   "publishConfig": {
     "access": "public",

package/skills/{module-freeze-all → module-seal-all}/SKILL.md

@@ -1,6 +1,6 @@
 ---
-name: module-freeze-all
-description: Auto-freeze all files in module descriptors so their module surface area cannot be increased.
+name: module-seal-all
+description: Auto-seal all files in module descriptors so their module surface area cannot be increased.
 disable-model-invocation: true
 argument-hint: <user-instructions>
 ---
@@ -9,26 +9,26 @@ argument-hint: <user-instructions>
 - Find out module descriptor filename in the context.
 - Find out source root in the context or from configurations.
 - Derive scripts args from user instructions.
-- Call the script to scans the source tree for module descriptors and auto-populates their `frozen` entries with code files in each module directory.
+- Call the script to scans the source tree for module descriptors and auto-populates their `sealed` entries with code files in each module directory.
 
 ## Script Usage
 
 ```bash
-node skills/module-freeze-all/scripts/freeze-all.mjs [options]
+node skills/module-seal-all/scripts/seal-all.mjs [options]
 ```
 
 Options:
 - `--root <dir>` - Source root directory (default: `src`)
 - `--dry-run` - Show what would change without writing files
-- `--create` - Create module descriptor files for directories without one (adds `frozen` only)
+- `--create` - Create module descriptor files for directories without one (adds `sealed` only)
 - `--descriptor-name <name>` - Module descriptor filename (default: `module.md`)
 
 ### Behavior
 
 1. Finds all module descriptor files under the source root.
 2. For each module directory, lists all direct files (not subdirectories, not module descriptor file itself)
-3. Adds those files to the `frozen` frontmatter field
-4. Preserves existing `frozen` entries, other fields in the frontmatter, and body prose
+3. Adds those files to the `sealed` frontmatter field
+4. Preserves existing `sealed` entries, other fields in the frontmatter, and body prose
 
 ## Extra user instructions:
 "$ARGUMENTS"

package/skills/module-seal-all/scripts/seal-all.d.mts

@@ -0,0 +1 @@
+export declare const SUPPORTED_EXTENSIONS: Set<string>;

package/skills/{module-freeze-all/scripts/freeze-all.mjs → module-seal-all/scripts/seal-all.mjs}

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
 /**
- * Auto-freeze all files in module descriptors.
+ * Auto-seal all files in module descriptors.
  *
  * Scans module descriptor files under a source root and populates each
- * descriptor's `frozen` field with every direct code file in the module
+ * descriptor's `sealed` field with every direct code file in the module
  * directory. Files in nested sub-modules (directories with their own
  * descriptor) are excluded from the parent.
  */
@@ -47,7 +47,7 @@ function main() {
   const results = [];
 
   for (const [modDir, modFile] of allModuleDirs) {
-    const result = freezeModule(modDir, modFile, descriptorName, allModuleDirs);
+    const result = sealModule(modDir, modFile, descriptorName, allModuleDirs);
     if (result) results.push(result);
   }
 
@@ -69,7 +69,7 @@ function main() {
     console.log("Dry run — would modify:");
     for (const r of results) {
       const rel = relative(cwd, r.path);
-      console.log(`  ${rel}: freeze [${r.files.join(", ") || "(none)"}]`);
+      console.log(`  ${rel}: seal [${r.files.join(", ") || "(none)"}]`);
     }
     return;
   }
@@ -169,7 +169,7 @@ function walkDir(dir, visitor) {
 // Module processing
 // ---------------------------------------------------------------------------
 
-function freezeModule(modDir, descriptorFileName, descriptorName, allModuleDirs) {
+function sealModule(modDir, descriptorFileName, descriptorName, allModuleDirs) {
   const modPath = join(modDir, descriptorFileName);
   let raw;
   try {
@@ -179,15 +179,15 @@ function freezeModule(modDir, descriptorFileName, descriptorName, allModuleDirs)
   }
 
   const parsed = parseFrontmatter(raw);
-  const existingFrozen = normalizeFrozen(parsed.frontmatter.frozen);
+  const existingSealed = normalizeSealed(parsed.frontmatter.sealed);
   const directFiles = listDirectFiles(modDir, descriptorName, allModuleDirs);
-  const mergedFrozen = mergePreservingOrder(existingFrozen, directFiles);
+  const mergedSealed = mergePreservingOrder(existingSealed, directFiles);
 
-  if (arraysEqual(existingFrozen, mergedFrozen)) return undefined;
+  if (arraysEqual(existingSealed, mergedSealed)) return undefined;
 
-  const newContent = serializeModule(parsed, mergedFrozen);
+  const newContent = serializeModule(parsed, mergedSealed);
 
-  return { path: modPath, content: newContent, files: mergedFrozen };
+  return { path: modPath, content: newContent, files: mergedSealed };
 }
 
 function createModuleDescriptor(dir, descriptorName) {
@@ -283,8 +283,8 @@ function parseInlineList(raw) {
   return inner.split(",").map((s) => s.trim().replace(/^['"]|['"]$/g, ""));
 }
 
-function serializeModule(parsed, frozen) {
-  const fm = { ...parsed.frontmatter, frozen };
+function serializeModule(parsed, sealed) {
+  const fm = { ...parsed.frontmatter, sealed };
 
   let yaml = parsed.prelude;
   for (const [key, value] of Object.entries(fm)) {
@@ -344,7 +344,7 @@ function listDirectFiles(modDir, descriptorName, allModuleDirs) {
 // Helpers
 // ---------------------------------------------------------------------------
 
-function normalizeFrozen(value) {
+function normalizeSealed(value) {
   if (Array.isArray(value)) return value.map(String);
   return [];
 }
@@ -366,4 +366,4 @@ function arraysEqual(a, b) {
 
 if (import.meta.url === pathToFileURL(resolve(process.argv[1] ?? "")).href) {
   main();
-}
+}

package/src/MODULE.md

@@ -1,6 +1,5 @@
 ---
-frozen:
+sealed:
   - config.ts
   - index.ts
----
-
+---

package/src/claude/index-loader.ts

@@ -0,0 +1,40 @@
+import type { ModuleIndex } from "../types.ts";
+import type { ModuleGateConfig } from "../config.ts";
+import { loadConfig } from "../config.ts";
+import { buildModuleIndex } from "../graph/index.ts";
+
+export type IndexContext = {
+  cwd: string;
+  ui: { notify: (msg: string) => void };
+};
+
+export type LoadIndexResult = {
+  index: ModuleIndex;
+  config: ModuleGateConfig;
+};
+
+export async function loadIndexForHook(cwd: string): Promise<LoadIndexResult> {
+  const config = loadConfig(cwd);
+  const ctx: IndexContext = {
+    cwd,
+    ui: {
+      notify: (m) => process.stderr.write(`[Module Gate] ${m}\n`),
+    },
+  };
+
+  try {
+    const index = await buildModuleIndex(ctx, config);
+    return { index, config };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`[Module Gate] index build failed: ${message}\n`);
+    return {
+      index: { contracts: [], dirToModule: new Map() },
+      config,
+    };
+  }
+}
+
+export function notifyNoContracts(ctx: IndexContext): void {
+  ctx.ui.notify("No module descriptor files found. Gates are not active.");
+}

package/src/claude/pre-tool-use.ts

@@ -0,0 +1,99 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { applyEdits, readFileSafe } from "../utils.ts";
+import { runGates, type GateEdit } from "../gates/run-gates.ts";
+import { loadIndexForHook, notifyNoContracts } from "./index-loader.ts";
+import "../gates/checkers/index.ts";
+
+type HookEvent = {
+  hook_event_name?: string;
+  tool_name?: string;
+  tool_input?: {
+    file_path?: string;
+    old_string?: string;
+    new_string?: string;
+    edits?: { old_string?: string; new_string?: string }[];
+    content?: string;
+  };
+  cwd?: string;
+};
+
+const notifyCtx = (): { cwd: string; ui: { notify: (m: string) => void } } => ({
+  cwd: process.cwd(),
+  ui: {
+    notify: (m) => process.stderr.write(`[Module Gate] ${m}\n`),
+  },
+});
+
+async function main(): Promise<void> {
+  let raw: string;
+  try {
+    raw = fs.readFileSync(0, "utf-8");
+  } catch {
+    process.exit(0);
+  }
+
+  let event: HookEvent;
+  try {
+    event = JSON.parse(raw);
+  } catch {
+    process.stderr.write("[Module Gate] hook: invalid JSON input; allowing tool call.\n");
+    process.exit(0);
+  }
+
+  if (event.hook_event_name !== "PreToolUse") process.exit(0);
+  if (
+    event.tool_name !== "Edit" &&
+    event.tool_name !== "MultiEdit" &&
+    event.tool_name !== "Write"
+  ) {
+    process.exit(0);
+  }
+
+  const cwd: string = event.cwd ?? process.env.CLAUDE_PROJECT_DIR ?? process.cwd();
+  const toolInput = event.tool_input ?? {};
+  const filePath: string | undefined = toolInput.file_path;
+  if (!filePath) process.exit(0);
+
+  const absPath = path.resolve(cwd, filePath);
+  const before = readFileSafe(absPath);
+  let after: string;
+
+  if (event.tool_name === "Edit") {
+    after = applyEdits(before, [
+      { oldText: toolInput.old_string ?? "", newText: toolInput.new_string ?? "" },
+    ]);
+  } else if (event.tool_name === "MultiEdit") {
+    const edits: GateEdit[] = Array.isArray(toolInput.edits)
+      ? toolInput.edits.map((e) => ({
+          oldText: e.old_string ?? "",
+          newText: e.new_string ?? "",
+        }))
+      : [];
+    after = applyEdits(before, edits);
+  } else {
+    after = toolInput.content ?? "";
+  }
+
+  const { index, config } = await loadIndexForHook(cwd);
+
+  if (index.contracts.length === 0) {
+    notifyNoContracts(notifyCtx());
+    process.exit(0);
+  }
+
+  const result = runGates(filePath, [{ oldText: before, newText: after }], cwd, index, config, before);
+
+  if (result?.block) {
+    process.stderr.write(`${result.reason}\n`);
+    process.exit(2);
+  }
+
+  process.exit(0);
+}
+
+main().catch((err) => {
+  const message = err instanceof Error ? err.message : String(err);
+  process.stderr.write(`[Module Gate] hook internal error: ${message}\n`);
+  process.exit(0);
+});

package/src/claude/settings-writer.ts

@@ -0,0 +1,91 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+export const HOOK_MARKER = "@cuzfrog/pi-module-gates";
+export const PRE_TOOL_USE_MATCHER = "Edit|MultiEdit|Write";
+
+export type ClaudeHookCommand = {
+  type: "command";
+  command: string;
+  statusMessage?: string;
+};
+
+export type ClaudeHook = ClaudeHookCommand | {
+  type: string;
+  command?: string;
+  statusMessage?: string;
+  [key: string]: unknown;
+};
+
+export type HookMatcher = {
+  matcher: string;
+  hooks: ClaudeHook[];
+};
+
+export type ClaudeSettings = {
+  hooks?: Record<string, HookMatcher[]>;
+  [key: string]: unknown;
+};
+
+export function readSettings(projectDir: string): ClaudeSettings {
+  const settingsPath = path.join(projectDir, ".claude", "settings.json");
+  try {
+    const raw = fs.readFileSync(settingsPath, "utf-8");
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+      return parsed as ClaudeSettings;
+    }
+    return {};
+  } catch {
+    return {};
+  }
+}
+
+export function buildPreToolUseEntry(): HookMatcher {
+  return {
+    matcher: PRE_TOOL_USE_MATCHER,
+    hooks: [
+      {
+        type: "command",
+        command: `bun \${CLAUDE_PROJECT_DIR}/node_modules/@cuzfrog/pi-module-gates/src/claude/pre-tool-use.ts`,
+        statusMessage: "Module gate checking edit...",
+      },
+    ],
+  };
+}
+
+export function upsertPreToolUse(settings: ClaudeSettings): ClaudeSettings {
+  const next: ClaudeSettings = JSON.parse(JSON.stringify(settings));
+  next.hooks = next.hooks ?? {};
+  const existing = next.hooks.PreToolUse ?? [];
+  next.hooks.PreToolUse = existing.filter(
+    (m) => !m.hooks.some((h) => typeof h.command === "string" && h.command.includes(HOOK_MARKER)),
+  );
+  next.hooks.PreToolUse.push(buildPreToolUseEntry());
+  return next;
+}
+
+export function removePreToolUse(settings: ClaudeSettings): ClaudeSettings {
+  const next: ClaudeSettings = JSON.parse(JSON.stringify(settings));
+  if (!next.hooks?.PreToolUse) return next;
+  const filtered = next.hooks.PreToolUse.filter(
+    (m) => !m.hooks.some((h) => typeof h.command === "string" && h.command.includes(HOOK_MARKER)),
+  );
+  if (filtered.length === 0) {
+    delete next.hooks.PreToolUse;
+    if (Object.keys(next.hooks).length === 0) {
+      delete next.hooks;
+    }
+  } else {
+    next.hooks.PreToolUse = filtered;
+  }
+  return next;
+}
+
+export function writeSettings(projectDir: string, settings: ClaudeSettings): string {
+  const claudeDir = path.join(projectDir, ".claude");
+  fs.mkdirSync(claudeDir, { recursive: true });
+  const target = path.join(claudeDir, "settings.json");
+  fs.writeFileSync(target, JSON.stringify(settings, null, 2) + "\n", "utf-8");
+  return target;
+}

package/src/cli/install-claude.ts

@@ -0,0 +1,54 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import {
+  readSettings,
+  upsertPreToolUse,
+  writeSettings,
+  HOOK_MARKER,
+  PRE_TOOL_USE_MATCHER,
+} from "../claude/settings-writer.ts";
+
+export type InstallClaudeOptions = {
+  projectDir: string;
+};
+
+export type InstallClaudeResult =
+  | { ok: true; written: string }
+  | { ok: false; reason: string };
+
+export function installClaude(opts: InstallClaudeOptions): InstallClaudeResult {
+  const projectDir = path.resolve(opts.projectDir);
+  if (!fs.existsSync(projectDir) || !fs.statSync(projectDir).isDirectory()) {
+    return { ok: false, reason: `Project directory does not exist: ${projectDir}` };
+  }
+
+  const settingsPath = path.join(projectDir, ".pi", "settings.json");
+  if (!fs.existsSync(settingsPath)) {
+    process.stderr.write(
+      `[Module Gate] No .pi/settings.json found at ${settingsPath} — using defaults.\n`,
+    );
+  }
+
+  const settings = readSettings(projectDir);
+  const updated = upsertPreToolUse(settings);
+  const written = writeSettings(projectDir, updated);
+
+  const relPath = path.relative(projectDir, written) || written;
+  process.stdout.write(`Wrote ${relPath}\n\n`);
+  process.stdout.write("Hook entry inserted under hooks.PreToolUse:\n");
+  const matcher = updated.hooks?.PreToolUse?.find((m) =>
+    m.hooks.some((h) => typeof h.command === "string" && h.command.includes(HOOK_MARKER)),
+  );
+  if (matcher) {
+    process.stdout.write(`  matcher: "${matcher.matcher}"\n`);
+    for (const h of matcher.hooks) {
+      if (typeof h.command === "string") {
+        process.stdout.write(`  command: ${h.command}\n`);
+      }
+      if (h.statusMessage) process.stdout.write(`  status:  ${h.statusMessage}\n`);
+    }
+  }
+  process.stdout.write(`\nMatcher targets: ${PRE_TOOL_USE_MATCHER}\n`);
+
+  return { ok: true, written };
+}

package/src/cli/uninstall-claude.ts

@@ -0,0 +1,40 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import {
+  readSettings,
+  removePreToolUse,
+  writeSettings,
+  HOOK_MARKER,
+} from "../claude/settings-writer.ts";
+
+export type UninstallClaudeOptions = {
+  projectDir: string;
+};
+
+export type UninstallClaudeResult =
+  | { ok: true; removed: boolean; written: string }
+  | { ok: false; reason: string };
+
+export function uninstallClaude(opts: UninstallClaudeOptions): UninstallClaudeResult {
+  const projectDir = path.resolve(opts.projectDir);
+  const settingsPath = path.join(projectDir, ".claude", "settings.json");
+
+  if (!fs.existsSync(settingsPath)) {
+    process.stdout.write(`No .claude/settings.json found at ${settingsPath} — nothing to do.\n`);
+    return { ok: true, removed: false, written: settingsPath };
+  }
+
+  const before = readSettings(projectDir);
+  const beforeHadMarker = JSON.stringify(before).includes(HOOK_MARKER);
+  const after = removePreToolUse(before);
+  const afterHasMarker = JSON.stringify(after).includes(HOOK_MARKER);
+
+  if (beforeHadMarker && !afterHasMarker) {
+    writeSettings(projectDir, after);
+    process.stdout.write(`Removed pi-module-gates hooks from ${settingsPath}.\n`);
+    return { ok: true, removed: true, written: settingsPath };
+  }
+
+  process.stdout.write(`No pi-module-gates hooks found in ${settingsPath}.\n`);
+  return { ok: true, removed: false, written: settingsPath };
+}

package/src/context/MODULE.md

@@ -1,6 +1,5 @@
 ---
-frozen:
+sealed:
   - system-prompt.ts
   - index.ts
----
-
+---

package/src/context/system-prompt.template.md

@@ -1,5 +1,5 @@
 ## Module gates (boundary enforcement)
-This project uses `{{descriptorFileName}}`(case-insensitive) files to declare visibility, readonly and frozen rules that you should follow.
+This project uses `{{descriptorFileName}}`(case-insensitive) files to declare visibility, readonly and sealed rules that you should follow.
 If you cannot comply, reconsider your design or raise to the user with tradeoffs if necessary.
 Each `{{descriptorFileName}}` gates its branching point in the tree.
 A `{{descriptorFileName}}` with a `visible` list means only entries in the list are allowed to be visible outside the module.
@@ -13,5 +13,5 @@ A `{{descriptorFileName}}` with a `visible` list means only entries in the list
 - `external files`: files not in the module directory;
 - `module interface`: the file representing the module surface, e.g. `index.ts` in Typescript, `mod.rs` in Rust;
 - `readonly`: files are readonly;
-- `frozen`: files cannot add new exports, but still editable;
+- `sealed`: files cannot add new exports, but the body is still editable; the export surface is sealed;
 - `visible`: visible from outside the module; files not in the module directory are outside the module;

package/src/gates/MODULE.md

@@ -1,8 +1,7 @@
 ---
-frozen:
+sealed:
   - export-gate.ts
-  - frozen-gate.ts
+  - sealed-gate.ts
   - readonly-gate.ts
   - index.ts
----
-
+---

package/src/gates/checkers/MODULE.md

@@ -1,8 +1,7 @@
 ---
-frozen:
+sealed:
   - index.ts
   - registry.ts
   - rust.ts
   - typescript.ts
----
-
+---

package/src/gates/checkers/index.ts

@@ -5,4 +5,5 @@ import "./go.ts";
 import "./kotlin.ts";
 import "./scala.ts";
 
-export { registerChecker, getChecker, ExportChecker } from "./registry.ts";
+export { registerChecker, getChecker } from "./registry.ts";
+export type { ExportChecker } from "./registry.ts";

package/src/gates/index.ts

@@ -1,4 +1,4 @@
 export { checkReadonly } from "./readonly-gate.ts";
-export { checkFrozen } from "./frozen-gate.ts";
+export { checkSealed } from "./sealed-gate.ts";
 export { checkExports } from "./export-gate.ts";
-export { checkModuleInterfaceImports } from "./module-interface-import-gate.ts";
+export { checkModuleInterfaceImports } from "./module-interface-import-gate.ts";

package/src/gates/run-gates.ts

@@ -0,0 +1,112 @@
+import * as path from "node:path";
+import { parseFrontmatter } from "../utils/frontmatter.ts";
+import type { ModuleIndex } from "../types.ts";
+import type { ModuleGateConfig } from "../config.ts";
+import { readFileSafe, applyEdits, isWithinSourceRoot, findOwningModule } from "../utils.ts";
+import {
+  checkReadonly,
+  checkSealed,
+  checkExports,
+  checkModuleInterfaceImports,
+} from "./index.ts";
+import "./checkers/index.ts";
+
+export type GateEdit = { oldText: string; newText: string };
+
+export type GateDenial = { block: true; reason: string };
+
+export function runGates(
+  filePath: string,
+  edits: GateEdit[],
+  cwd: string,
+  index: ModuleIndex,
+  config: ModuleGateConfig,
+  beforeOverride?: string,
+): GateDenial | undefined {
+  const absPath = path.resolve(cwd, filePath);
+
+  const before = beforeOverride ?? readFileSafe(absPath);
+  const after = applyEdits(before, edits);
+  const srcRoot = path.resolve(cwd, config.sourceRoot);
+
+  if (!isWithinSourceRoot(absPath, srcRoot)) return undefined;
+
+  const readonlyResult = checkReadonly(filePath, index, cwd, config.moduleDescriptorFileName);
+  if (readonlyResult.blocked) {
+    if (
+      config.moduleDescriptorReadonly === "frontmatter" &&
+      isDescriptorFile(absPath, config.moduleDescriptorFileName)
+    ) {
+      const fmBefore = extractFrontmatter(before);
+      const fmAfter = extractFrontmatter(after);
+      if (JSON.stringify(fmBefore) === JSON.stringify(fmAfter)) {
+        return undefined;
+      }
+      return {
+        block: true,
+        reason: formatDenial(
+          filePath,
+          `Readonly rule: frontmatter of ${config.moduleDescriptorFileName} is readonly`,
+          absPath,
+          index,
+          cwd,
+          config.moduleDescriptorFileName,
+        ),
+      };
+    }
+    return { block: true, reason: formatDenial(filePath, readonlyResult.reason, absPath, index, cwd, config.moduleDescriptorFileName) };
+  }
+
+  const sealedResult = checkSealed(filePath, before, after, index, cwd, config.moduleDescriptorFileName);
+  if (sealedResult.blocked) {
+    return { block: true, reason: formatDenial(filePath, sealedResult.reason, absPath, index, cwd, config.moduleDescriptorFileName) };
+  }
+
+  const exportResult = checkExports(filePath, before, after, index, cwd, config.moduleDescriptorFileName);
+  if (exportResult.blocked) {
+    return { block: true, reason: formatDenial(filePath, exportResult.reason, absPath, index, cwd, config.moduleDescriptorFileName) };
+  }
+
+  const importResult = checkModuleInterfaceImports(filePath, after, index, cwd, config.disableModuleInterfaceImportGate, config.sourceRoot);
+  if (importResult.blocked) {
+    return { block: true, reason: formatDenial(filePath, importResult.reason, absPath, index, cwd, config.moduleDescriptorFileName) };
+  }
+
+  return undefined;
+}
+
+export function formatDenial(
+  relPath: string,
+  reason: string,
+  absPath: string,
+  index: ModuleIndex,
+  cwd: string,
+  descriptorFileName: string,
+): string {
+  const modulePath = findOwningModule(absPath, index);
+  const contract = modulePath
+    ? index.contracts.find((c) => c.modulePath === modulePath)
+    : undefined;
+
+  let message = `[Module Gate] Write blocked — ${relPath}\n\n${reason}`;
+
+  if (contract && contract.prose) {
+    const relModuleMd = path.relative(cwd, path.join(contract.modulePath, descriptorFileName));
+    message += `\n\nModule contract (${relModuleMd}):\n${contract.prose}`;
+  }
+
+  return message;
+}
+
+export function isDescriptorFile(absPath: string, descriptorFileName: string): boolean {
+  const basename = path.basename(absPath);
+  return basename.toLowerCase() === descriptorFileName.toLowerCase();
+}
+
+export function extractFrontmatter(content: string): Record<string, unknown> {
+  try {
+    return parseFrontmatter(content).frontmatter;
+  } catch {
+    return {};
+  }
+}

package/src/gates/{frozen-gate.ts → sealed-gate.ts}

@@ -3,18 +3,18 @@ import type { ModuleIndex } from "../types.ts";
 import { getAncestorContracts, matchesPattern } from "../utils.ts";
 import { getChecker } from "./checkers/registry.ts";
 
-export type FrozenCheckResult =
+export type SealedCheckResult =
   | { blocked: true; reason: string }
   | { blocked: false };
 
-export function checkFrozen(
+export function checkSealed(
   filePath: string,
   beforeContent: string,
   afterContent: string,
   index: ModuleIndex,
   cwd: string,
   descriptorFileName: string,
-): FrozenCheckResult {
+): SealedCheckResult {
   const absFile = path.resolve(cwd, filePath);
 
   const checker = getChecker(absFile);
@@ -23,7 +23,7 @@ export function checkFrozen(
   const ancestors = getAncestorContracts(absFile, index);
 
   for (const contract of ancestors) {
-    for (const pattern of contract.frozen) {
+    for (const pattern of contract.sealed) {
       if (matchesPattern(absFile, pattern, contract.modulePath)) {
         const newExports = checker.getNewExports(beforeContent, afterContent);
         if (newExports.length === 0) return { blocked: false };
@@ -32,11 +32,11 @@ export function checkFrozen(
         const names = newExports.map((s) => s.name).join(", ");
         return {
           blocked: true,
-          reason: `Frozen rule: file is frozen in ${relModuleMd}. Cannot add new exports: ${names}`,
+          reason: `Sealed rule: file is sealed in ${relModuleMd}. Cannot add new exports: ${names}`,
         };
       }
     }
   }
 
   return { blocked: false };
-}
+}

package/src/graph/MODULE.md

@@ -1,9 +1,7 @@
 ---
-frozen:
+sealed:
   - frontmatter-parser.ts
   - module-index-builder.ts
   - validation.ts
   - index.ts
----
-
-
+---

package/src/graph/frontmatter-parser.ts

@@ -5,7 +5,7 @@ export type VisibleEntryRaw = string | { path: string; modifier?: string };
 export type ModuleFrontmatter = {
   visible?: VisibleEntryRaw[];
   readonly?: string[];
-  frozen?: string[];
+  sealed?: string[];
 };
 
 export function parseVisibleEntry(raw: VisibleEntryRaw): Signature {

package/src/graph/module-index-builder.ts

@@ -1,7 +1,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { readdir } from "node:fs/promises";
-import { parseFrontmatter } from "@earendil-works/pi-coding-agent";
+import { parseFrontmatter } from "../utils/frontmatter.ts";
 import type { ModuleContract, ModuleIndex } from "../types.ts";
 import type { ModuleGateConfig } from "../config.ts";
 
@@ -70,7 +70,7 @@ function buildContracts(
           ? frontmatter.visible.map(parseVisibleEntry)
           : null,
       readonly: readonlyEntries,
-      frozen: frontmatter.frozen ?? [],
+      sealed: frontmatter.sealed ?? [],
       prose: body.trim(),
     });
   }

package/src/index.ts

@@ -4,18 +4,13 @@ import type {
   ToolCallEventResult,
   BeforeAgentStartEventResult,
 } from "@earendil-works/pi-coding-agent";
-import { isToolCallEventType, parseFrontmatter } from "@earendil-works/pi-coding-agent";
+import { isToolCallEventType } from "@earendil-works/pi-coding-agent";
 import type { ModuleIndex } from "./types.ts";
 import { loadConfig } from "./config.ts";
 import type { ModuleGateConfig } from "./config.ts";
 import { buildModuleIndex } from "./graph/index.ts";
-import { findOwningModule, readFileSafe, applyEdits, isWithinSourceRoot } from "./utils.ts";
-import {
-  checkReadonly,
-  checkExports,
-  checkFrozen,
-  checkModuleInterfaceImports,
-} from "./gates/index.ts";
+import { readFileSafe } from "./utils.ts";
+import { runGates, type GateEdit } from "./gates/run-gates.ts";
 import { buildSystemPromptHint } from "./context/index.ts";
 import "./gates/checkers/index.ts";
 
@@ -43,107 +38,13 @@ export default function (pi: ExtensionAPI): void {
 
   pi.on("tool_call", async (event, ctx): Promise<ToolCallEventResult | void> => {
     if (isToolCallEventType("edit", event)) {
-      return handleEdit(event.input.path, event.input.edits, ctx.cwd, index, config);
+      return runGates(event.input.path, event.input.edits, ctx.cwd, index, config);
     }
     if (isToolCallEventType("write", event)) {
       const absPath = path.resolve(ctx.cwd, event.input.path);
       const before = readFileSafe(absPath);
-      return handleEdit(event.input.path, [{ oldText: before, newText: event.input.content }], ctx.cwd, index, config);
+      const edits: GateEdit[] = [{ oldText: before, newText: event.input.content }];
+      return runGates(event.input.path, edits, ctx.cwd, index, config);
     }
   });
-}
-
-function handleEdit(
-  filePath: string,
-  edits: { oldText: string; newText: string }[],
-  cwd: string,
-  index: ModuleIndex,
-  config: ModuleGateConfig,
-): ToolCallEventResult | undefined {
-  const absPath = path.resolve(cwd, filePath);
-
-  const before = readFileSafe(absPath);
-  const after = applyEdits(before, edits);
-  const srcRoot = path.resolve(cwd, config.sourceRoot);
-
-  if (!isWithinSourceRoot(absPath, srcRoot)) return undefined;
-
-  const readonlyResult = checkReadonly(filePath, index, cwd, config.moduleDescriptorFileName);
-  if (readonlyResult.blocked) {
-    if (
-      config.moduleDescriptorReadonly === "frontmatter" &&
-      isDescriptorFile(absPath, config.moduleDescriptorFileName)
-    ) {
-      const fmBefore = extractFrontmatter(before);
-      const fmAfter = extractFrontmatter(after);
-      if (JSON.stringify(fmBefore) === JSON.stringify(fmAfter)) {
-        return undefined;
-      }
-      return {
-        block: true,
-        reason: formatDenial(
-          filePath,
-          `Readonly rule: frontmatter of ${config.moduleDescriptorFileName} is readonly`,
-          absPath,
-          index,
-          cwd,
-          config.moduleDescriptorFileName,
-        ),
-      };
-    }
-    return { block: true, reason: formatDenial(filePath, readonlyResult.reason, absPath, index, cwd, config.moduleDescriptorFileName) };
-  }
-
-  const frozenResult = checkFrozen(filePath, before, after, index, cwd, config.moduleDescriptorFileName);
-  if (frozenResult.blocked) {
-    return { block: true, reason: formatDenial(filePath, frozenResult.reason, absPath, index, cwd, config.moduleDescriptorFileName) };
-  }
-
-  const exportResult = checkExports(filePath, before, after, index, cwd, config.moduleDescriptorFileName);
-  if (exportResult.blocked) {
-    return { block: true, reason: formatDenial(filePath, exportResult.reason, absPath, index, cwd, config.moduleDescriptorFileName) };
-  }
-
-  const importResult = checkModuleInterfaceImports(filePath, after, index, cwd, config.disableModuleInterfaceImportGate, config.sourceRoot);
-  if (importResult.blocked) {
-    return { block: true, reason: formatDenial(filePath, importResult.reason, absPath, index, cwd, config.moduleDescriptorFileName) };
-  }
-
-  return undefined;
-}
-
-function formatDenial(
-  relPath: string,
-  reason: string,
-  absPath: string,
-  index: ModuleIndex,
-  cwd: string,
-  descriptorFileName: string,
-): string {
-  const modulePath = findOwningModule(absPath, index);
-  const contract = modulePath
-    ? index.contracts.find((c) => c.modulePath === modulePath)
-    : undefined;
-
-  let message = `[Module Gate] Write blocked — ${relPath}\n\n${reason}`;
-
-  if (contract && contract.prose) {
-    const relModuleMd = path.relative(cwd, path.join(contract.modulePath, descriptorFileName));
-    message += `\n\nModule contract (${relModuleMd}):\n${contract.prose}`;
-  }
-
-  return message;
-}
-
-function isDescriptorFile(absPath: string, descriptorFileName: string): boolean {
-  const basename = path.basename(absPath);
-  return basename.toLowerCase() === descriptorFileName.toLowerCase();
-}
-
-function extractFrontmatter(content: string): Record<string, unknown> {
-  try {
-    return parseFrontmatter(content).frontmatter;
-  } catch {
-    return {};
-  }
-}
+}

package/src/types.ts

@@ -9,7 +9,7 @@ export type ModuleContract = {
   modulePath: string;
   visible: Signature[] | null;
   readonly: string[];
-  frozen: string[];
+  sealed: string[];
   prose: string;
 };
 

package/src/utils/frontmatter.ts

@@ -0,0 +1,41 @@
+import { parse } from "yaml";
+
+type ParsedFrontmatter<T extends Record<string, unknown>> = {
+  frontmatter: T;
+  body: string;
+};
+
+const normalizeNewlines = (value: string): string =>
+  value.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+
+const extractFrontmatter = (
+  content: string,
+): { yamlString: string | null; body: string } => {
+  const normalized = normalizeNewlines(content);
+  if (!normalized.startsWith("---")) {
+    return { yamlString: null, body: normalized };
+  }
+  const endIndex = normalized.indexOf("\n---", 3);
+  if (endIndex === -1) {
+    return { yamlString: null, body: normalized };
+  }
+  return {
+    yamlString: normalized.slice(4, endIndex),
+    body: normalized.slice(endIndex + 4).trim(),
+  };
+};
+
+export function parseFrontmatter<T extends Record<string, unknown> = Record<string, unknown>>(
+  content: string,
+): ParsedFrontmatter<T> {
+  const { yamlString, body } = extractFrontmatter(content);
+  if (!yamlString) {
+    return { frontmatter: {} as T, body };
+  }
+  const parsed = parse(yamlString) as T | null | undefined;
+  return { frontmatter: (parsed ?? ({} as T)), body };
+}
+
+export function stripFrontmatter(content: string): string {
+  return parseFrontmatter(content).body;
+}

package/src/utils.ts

@@ -42,10 +42,10 @@ export function isWithinSourceRoot(absPath: string, resolvedRoot: string): boole
 export function getAncestorContracts(
   absFile: string,
   index: ModuleIndex,
-): { modulePath: string; readonly: string[]; frozen: string[] }[] {
+): { modulePath: string; readonly: string[]; sealed: string[] }[] {
   return index.contracts
     .filter((c) => absFile.startsWith(c.modulePath + path.sep) || absFile === c.modulePath)
-    .map(({ modulePath, readonly, frozen }) => ({ modulePath, readonly, frozen }));
+    .map(({ modulePath, readonly, sealed }) => ({ modulePath, readonly, sealed }));
 }
 
 export function matchesPattern(

package/skills/module-freeze-all/scripts/freeze-all.d.mts

@@ -1 +0,0 @@
-export declare const SUPPORTED_EXTENSIONS: Set<string>;