@cuzfrog/pi-module-gates 0.6.0 → 0.10.0

package/README.md

@@ -3,18 +3,6 @@
 pi cli extension that controls the entropy of the codebase by enforcing code module boundaries.
 It helps combat slop generation and code architecture degradation.
 
-## Installation
-
-```bash
-pi install npm:@cuzfrog/pi-module-gates
-```
-
-Or load directly for a single session:
-
-```bash
-pi -e npm:@cuzfrog/pi-module-gates
-```
-
 ## Problem
 
 AI coding agents produce edits with limited context knowledge (myopia) — their changes may leak implementation details, and break architectural contracts (slop).
@@ -23,8 +11,9 @@ AI coding agents produce edits with limited context knowledge (myopia) — their
 
 **Module contracts as guardrails.** Each directory can contain a descriptor file that declares:
 
-- `visible` — the set of exports allowed to be added or modified in that module
 - `readonly` — files and directories the agent must not touch
+- `frozen` — files where no new exports are allowed
+- `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.
 
@@ -34,26 +23,27 @@ The extension intercepts agent `write`/`edit` operations and enforces these cont
 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?
    - **Export gate** — would the change introduce an export not in the `visible` list?
    - **Import gate** (not implemented yet) — would the change introduce an import violating visibility scope?
 
-System prompt:
-```markdown
-## Module gates (boundary enforcement)
-   This project uses `module.md` files to declare visibility and readonly rules that you should follow.
-   If you cannot comply, reconsider your design, if impossible, raise to the user with tradeoffs.
-   Each `module.md` gates its branching point in the tree.
-   A `module.md` with a `visible` list means only entries in the list are allowed to be visible outside the module.
-   A `module.md` and its mentioned `readonly` files are readonly.
-   Violations will be blocked.
+- System prompt: [system-prompt.md](src/context/system-prompt.ts)
+- Currently [supported languages](src/gates/checkers/index.ts): **TypeScript/JavaScript**, **Rust**, **Java**, **Go**, **Kotlin**, **Scala**
+
+## Installation
+```bash
+pi install npm:@cuzfrog/pi-module-gates
+```
+Or load directly for a single session:
+```bash
+pi -e npm:@cuzfrog/pi-module-gates
 ```
-`module.md` filename is configurable.
 
 ## Module Descriptor Semantics
 
 A module descriptor is a Markdown file (default name: `MODULE.md`) placed in a directory. You can piggy-back on your module context file for example `CONTEXT.md`.
 
-### Simple readonly constraints
+### Readonly constraints
 
 ```markdown
 ---
@@ -63,7 +53,16 @@ readonly: [mod.rs]
 Any prose for the agent to better understand the module.
 ```
 
-### Visibility whitelist
+### Frozen constraints
+
+```yaml
+frozen: [mod.rs]
+```
+Frozen files cannot change their surface size: no new exports or public entries are allowed.
+
+A skill [module-freeze-all](src/skills/module-freeze-all) has been included to auto-freeze modules.
+
+### Visibility whitelist (under redesign)
 
 ```yaml
 visible:

package/package.json

@@ -1,8 +1,10 @@
 {
   "name": "@cuzfrog/pi-module-gates",
-  "version": "0.6.0",
+  "version": "0.10.0",
   "description": "pi extension that controls the entropy of the codebase by enforcing code module boundaries.",
-  "keywords": ["pi-package"],
+  "keywords": [
+    "pi-package"
+  ],
   "type": "module",
   "scripts": {
     "check": "tsc --noEmit",
@@ -11,6 +13,9 @@
   "pi": {
     "extensions": [
       "./src/index.ts"
+    ],
+    "skills": [
+      "./skills"
     ]
   },
   "peerDependencies": {
@@ -32,7 +37,12 @@
   "homepage": "https://github.com/cuzfrog/pi-module-gate#readme",
   "license": "MIT",
   "author": "Cause Chung (cuzfrog@gmail.com)",
-  "files": ["src/", "README.md", "LICENSE"],
+  "files": [
+    "src/",
+    "skills/",
+    "README.md",
+    "LICENSE"
+  ],
   "engines": {
     "node": ">=18"
   },

package/skills/module-freeze-all/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: module-freeze-all
+description: Auto-freeze all files in module descriptors so their module surface area cannot be increased.
+disable-model-invocation: true
+argument-hint: <user-instructions>
+---
+
+## What you do
+- 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 all files in each module directory.
+
+## Script Usage
+
+```bash
+node skills/module-freeze-all/scripts/freeze-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)
+- `--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
+
+
+## Extra user instructions:
+"$ARGUMENTS"

package/skills/module-freeze-all/scripts/freeze-all.mjs

@@ -0,0 +1,354 @@
+#!/usr/bin/env node
+/**
+ * Auto-freeze all files in module descriptors.
+ *
+ * Scans module descriptor files under a source root and populates each
+ * descriptor's `frozen` field with every direct file in the module directory.
+ * Files in nested sub-modules (directories with their own descriptor) are
+ * excluded from the parent.
+ */
+import { readFileSync, writeFileSync, readdirSync, existsSync } from "node:fs";
+import { resolve, relative, join, dirname } from "node:path";
+import { parseArgs } from "node:util";
+
+function main() {
+  const { values } = parseArgs({
+    options: {
+      root: { type: "string", default: "src" },
+      "dry-run": { type: "boolean", default: false },
+      create: { type: "boolean", default: false },
+      "descriptor-name": { type: "string", default: "module.md" },
+    },
+  });
+
+  const cwd = process.cwd();
+  const root = resolve(cwd, values.root);
+
+  if (!existsSync(root)) {
+    console.error(`Root directory not found: ${root}`);
+    process.exit(1);
+  }
+
+  const descriptorName = values["descriptor-name"];
+
+  const allModuleDirs = findModuleDirs(root, descriptorName);
+  const results = [];
+
+  for (const [modDir, modFile] of allModuleDirs) {
+    const result = freezeModule(modDir, modFile, descriptorName, allModuleDirs);
+    if (result) results.push(result);
+  }
+
+  if (values.create) {
+    const allDirs = findAllDirsWithFiles(root);
+    const dirsWithoutModule = allDirs.filter((d) => !allModuleDirs.has(d));
+    for (const dir of dirsWithoutModule) {
+      const result = createModuleDescriptor(dir, descriptorName);
+      if (result) results.push(result);
+    }
+  }
+
+  if (results.length === 0) {
+    console.log("All module descriptors are up to date.");
+    return;
+  }
+
+  if (values["dry-run"]) {
+    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)"}]`);
+    }
+    return;
+  }
+
+  for (const r of results) {
+    writeFileSync(r.path, r.content, "utf-8");
+    console.log(`Updated: ${relative(cwd, r.path)}`);
+  }
+  console.log(`Done. ${results.length} module descriptor(s) processed.`);
+}
+
+// ---------------------------------------------------------------------------
+// File system scanning
+// ---------------------------------------------------------------------------
+
+function findModuleDirs(root, descriptorName) {
+  const map = new Map();
+  const lowerName = descriptorName.toLowerCase();
+  walkDir(root, (fullPath, entry) => {
+    if (entry.isFile() && entry.name.toLowerCase() === lowerName) {
+      map.set(dirname(fullPath), entry.name);
+      return "prune";
+    }
+    return "continue";
+  });
+  return map;
+}
+
+function findAllDirsWithFiles(root) {
+  const dirHasFiles = new Map();
+
+  function collectFileDirs(dir) {
+    let entries;
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (entry.name === "node_modules" || entry.name === ".git") continue;
+      const fullPath = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        collectFileDirs(fullPath);
+      } else {
+        dirHasFiles.set(dir, true);
+      }
+    }
+  }
+  collectFileDirs(root);
+
+  const dirs = [];
+  function collectAllDirs(dir) {
+    let entries;
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (entry.name === "node_modules" || entry.name === ".git") continue;
+      const fullPath = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        collectAllDirs(fullPath);
+      }
+    }
+    if (dirHasFiles.has(dir)) {
+      dirs.push(dir);
+    }
+  }
+  collectAllDirs(root);
+  return dirs;
+}
+
+function walkDir(dir, visitor) {
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    if (entry.name === "node_modules" || entry.name === ".git") continue;
+    const fullPath = join(dir, entry.name);
+    const action = visitor(fullPath, {
+      name: entry.name,
+      isFile: () => entry.isFile(),
+      isDirectory: () => entry.isDirectory(),
+    });
+    if (action === "prune") continue;
+    if (entry.isDirectory()) {
+      walkDir(fullPath, visitor);
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Module processing
+// ---------------------------------------------------------------------------
+
+function freezeModule(modDir, descriptorFileName, descriptorName, allModuleDirs) {
+  const modPath = join(modDir, descriptorFileName);
+  let raw;
+  try {
+    raw = readFileSync(modPath, "utf-8");
+  } catch {
+    return undefined;
+  }
+
+  const parsed = parseFrontmatter(raw);
+  const existingFrozen = normalizeFrozen(parsed.frontmatter.frozen);
+  const directFiles = listDirectFiles(modDir, descriptorName, allModuleDirs);
+  const mergedFrozen = mergePreservingOrder(existingFrozen, directFiles);
+
+  if (arraysEqual(existingFrozen, mergedFrozen)) return undefined;
+
+  const newContent = serializeModule(parsed, mergedFrozen);
+
+  return { path: modPath, content: newContent, files: mergedFrozen };
+}
+
+function createModuleDescriptor(dir, descriptorName) {
+  const directFiles = listDirectFiles(dir, descriptorName, new Map());
+  if (directFiles.length === 0) return undefined;
+
+  const content = serializeModule(
+    { prelude: "---\n", frontmatter: {}, body: "\n" },
+    directFiles,
+  );
+
+  const modPath = join(dir, descriptorName);
+
+  return { path: modPath, content, files: directFiles };
+}
+
+// ---------------------------------------------------------------------------
+// Frontmatter parsing & serialization
+// ---------------------------------------------------------------------------
+
+function parseFrontmatter(raw) {
+  const trimmed = raw.trimStart();
+  if (!trimmed.startsWith("---")) {
+    return { prelude: "", frontmatter: {}, body: raw };
+  }
+
+  const endIdx = trimmed.indexOf("\n---", 3);
+  const actualEnd = endIdx === -1 ? trimmed.indexOf("---", 3) : endIdx;
+
+  if (actualEnd === -1) {
+    return { prelude: "", frontmatter: {}, body: raw };
+  }
+
+  const prelude = "---\n";
+  const fmBlock = trimmed.slice(3, actualEnd).trim();
+  const body = trimmed.slice(actualEnd + (trimmed[actualEnd] === "\n" ? 4 : 3));
+
+  const frontmatter = parseYamlBlock(fmBlock);
+
+  return { prelude, frontmatter, body };
+}
+
+function parseYamlBlock(block) {
+  const result = {};
+  if (block.length === 0) return result;
+
+  const lines = block.split("\n");
+  let currentKey = null;
+  let currentList = [];
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (trimmed.length === 0) continue;
+
+    const listMatch = trimmed.match(/^\s*-\s+(.+)$/);
+    if (listMatch && currentKey) {
+      currentList.push(listMatch[1].trim());
+      continue;
+    }
+
+    if (currentKey) {
+      result[currentKey] = currentList;
+      currentKey = null;
+      currentList = [];
+    }
+
+    const kvMatch = trimmed.match(/^(\w[\w-]*)\s*:\s*(.*)$/);
+    if (kvMatch) {
+      const key = kvMatch[1];
+      const value = kvMatch[2].trim();
+
+      if (value === "" || value === "[]") {
+        currentKey = key;
+        currentList = [];
+      } else if (value.startsWith("[") && value.endsWith("]")) {
+        result[key] = parseInlineList(value);
+      } else {
+        result[key] = value;
+      }
+    }
+  }
+
+  if (currentKey) {
+    result[currentKey] = currentList;
+  }
+
+  return result;
+}
+
+function parseInlineList(raw) {
+  const inner = raw.slice(1, -1).trim();
+  if (inner.length === 0) return [];
+  return inner.split(",").map((s) => s.trim().replace(/^['"]|['"]$/g, ""));
+}
+
+function serializeModule(parsed, frozen) {
+  const fm = { ...parsed.frontmatter, frozen };
+
+  let yaml = parsed.prelude;
+  for (const [key, value] of Object.entries(fm)) {
+    if (Array.isArray(value)) {
+      yaml += `${key}:\n`;
+      for (const item of value) {
+        yaml += `  - ${item}\n`;
+      }
+    } else if (typeof value === "string") {
+      yaml += `${key}: ${value}\n`;
+    }
+  }
+  yaml += "---\n";
+  yaml += parsed.body;
+
+  if (!parsed.body.endsWith("\n")) {
+    yaml += "\n";
+  }
+
+  return yaml;
+}
+
+// ---------------------------------------------------------------------------
+// File listing
+// ---------------------------------------------------------------------------
+
+function listDirectFiles(modDir, descriptorName, allModuleDirs) {
+  const lowerDesc = descriptorName.toLowerCase();
+  const files = [];
+
+  let entries;
+  try {
+    entries = readdirSync(modDir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+
+  for (const entry of entries) {
+    if (entry.name === "node_modules" || entry.name === ".git") continue;
+
+    if (entry.isDirectory()) {
+      const subDir = join(modDir, entry.name);
+      if (allModuleDirs.has(subDir)) continue;
+      // Skip directory entries entirely — sub-modules handle their own
+      // Non-module subdirs are skipped too to avoid granularity issues
+    } else {
+      if (entry.name.toLowerCase() === lowerDesc) continue;
+      files.push(entry.name);
+    }
+  }
+
+  return files;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function normalizeFrozen(value) {
+  if (Array.isArray(value)) return value.map(String);
+  return [];
+}
+
+function mergePreservingOrder(existing, newFiles) {
+  const result = [...existing];
+  for (const f of newFiles) {
+    if (!existing.includes(f)) result.push(f);
+  }
+  return result;
+}
+
+function arraysEqual(a, b) {
+  if (a.length !== b.length) return false;
+  const sortedA = [...a].sort();
+  const sortedB = [...b].sort();
+  return sortedA.every((v, i) => v === sortedB[i]);
+}
+
+main();

package/src/MODULE.md

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

package/src/config.ts

@@ -3,19 +3,19 @@ import * as path from "node:path";
 
 export type ModuleGateConfig = {
   moduleDescriptorFileName: string;
-  moduleDescriptorReadonly: boolean;
+  moduleDescriptorReadonly: "file" | "frontmatter" | "off";
   sourceRoot: string;
 };
 
 const DEFAULTS: ModuleGateConfig = {
   moduleDescriptorFileName: "module.md",
-  moduleDescriptorReadonly: true,
+  moduleDescriptorReadonly: "file",
   sourceRoot: "src/",
 };
 
 export function loadConfig(cwd: string): ModuleGateConfig {
   const settingsPath = path.join(cwd, ".pi", "settings.json");
-  let userConfig: Partial<ModuleGateConfig> = {};
+  let userConfig: Partial<Omit<ModuleGateConfig, "moduleDescriptorReadonly"> & { moduleDescriptorReadonly?: ModuleGateConfig["moduleDescriptorReadonly"] | boolean }> = {};
   try {
     const raw = fs.readFileSync(settingsPath, "utf-8");
     const settings = JSON.parse(raw);
@@ -25,5 +25,13 @@ export function loadConfig(cwd: string): ModuleGateConfig {
   } catch {
     // file doesn't exist or invalid — use defaults
   }
-  return { ...DEFAULTS, ...userConfig };
+  const merged = { ...DEFAULTS, ...userConfig };
+  merged.moduleDescriptorReadonly = normalizeReadonly(merged.moduleDescriptorReadonly);
+  return merged as ModuleGateConfig;
+}
+
+function normalizeReadonly(value: ModuleGateConfig["moduleDescriptorReadonly"] | boolean): ModuleGateConfig["moduleDescriptorReadonly"] {
+  if (value === true || value === "file") return "file";
+  if (value === false || value === "off") return "off";
+  return value;
 }

package/src/context/MODULE.md

@@ -0,0 +1,5 @@
+---
+frozen:
+  - system-prompt.ts
+---
+

package/src/context/system-prompt.ts

@@ -1,19 +1,28 @@
 import type { ModuleIndex } from "../types.ts";
+import type { ModuleGateConfig } from "../config.ts";
 
 export function buildSystemPromptHint(
   index: ModuleIndex,
   systemPrompt: string,
   descriptorFileName: string,
+  moduleDescriptorReadonly: ModuleGateConfig["moduleDescriptorReadonly"],
 ): string {
   if (index.contracts.length === 0) return systemPrompt;
 
+  const descriptorNote =
+    moduleDescriptorReadonly === "frontmatter"
+      ? ` The frontmatter of \`${descriptorFileName}\` is readonly.`
+      : moduleDescriptorReadonly === "file"
+        ? ` The \`${descriptorFileName}\` file itself is readonly.`
+        : "";
+
   return systemPrompt + `
 
 ## Module gates (boundary enforcement)
-This project uses \`${descriptorFileName}\`(case-insensitive) files to declare visibility and readonly rules that you should follow.
+This project uses \`${descriptorFileName}\`(case-insensitive) files to declare visibility, readonly and frozen rules that you should follow.
 If you cannot comply, reconsider your design, if impossible, raise to the user with tradeoffs.
 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.
-A \`${descriptorFileName}\` and its mentioned \`readonly\` files are readonly.
+\`readonly\` files are readonly; \`frozen\` files cannot grow their surface size (no new exports).${descriptorNote}
 Violations will be blocked.`;
 }

package/src/gates/MODULE.md

@@ -0,0 +1,7 @@
+---
+frozen:
+  - export-gate.ts
+  - frozen-gate.ts
+  - readonly-gate.ts
+---
+

package/src/gates/checkers/MODULE.md

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

package/src/gates/checkers/go.ts

@@ -0,0 +1,19 @@
+import { registerChecker } from "./registry.ts";
+import type { ExportChecker } from "./registry.ts";
+import type { Signature } from "../../types.ts";
+
+const goChecker: ExportChecker = {
+  extensions: [".go"],
+  getNewExports(before: string, after: string): Signature[] {
+    const beforeNames = new Set(extractExports(before).map((s) => s.name));
+    return extractExports(after).filter((sig) => !beforeNames.has(sig.name));
+  },
+};
+
+registerChecker(goChecker);
+
+function extractExports(src: string): Signature[] {
+  return [...src.matchAll(
+    /^(?:func\s+(?!\()|type\s+|var\s+|const\s+)([\p{Lu}]\w*)/gmu,
+  )].map((m) => ({ name: m[1] }));
+}

package/src/gates/checkers/index.ts

@@ -1,2 +1,6 @@
 import "./typescript.ts";
 import "./rust.ts";
+import "./java.ts";
+import "./go.ts";
+import "./kotlin.ts";
+import "./scala.ts";

package/src/gates/checkers/java.ts

@@ -0,0 +1,19 @@
+import { registerChecker } from "./registry.ts";
+import type { ExportChecker } from "./registry.ts";
+import type { Signature } from "../../types.ts";
+
+const javaChecker: ExportChecker = {
+  extensions: [".java"],
+  getNewExports(before: string, after: string): Signature[] {
+    const beforeNames = new Set(extractExports(before).map((s) => s.name));
+    return extractExports(after).filter((sig) => !beforeNames.has(sig.name));
+  },
+};
+
+registerChecker(javaChecker);
+
+function extractExports(src: string): Signature[] {
+  return [...src.matchAll(
+    /^public\s+(?:class|interface|enum|@interface|record)\s+(\w+)/gm,
+  )].map((m) => ({ modifier: "public", name: m[1] }));
+}

package/src/gates/checkers/kotlin.ts

@@ -0,0 +1,26 @@
+import { registerChecker } from "./registry.ts";
+import type { ExportChecker } from "./registry.ts";
+import type { Signature } from "../../types.ts";
+
+const kotlinChecker: ExportChecker = {
+  extensions: [".kt", ".kts"],
+  getNewExports(before: string, after: string): Signature[] {
+    const beforeNames = new Set(extractExports(before).map((s) => s.name));
+    return extractExports(after).filter((sig) => !beforeNames.has(sig.name));
+  },
+};
+
+registerChecker(kotlinChecker);
+
+function extractExports(src: string): Signature[] {
+  const re = /^(?:(public|internal|protected|private)\s+)?(?:(?:data|sealed|enum|abstract|open)\s+)?(?:class|interface|object|fun|val|var|typealias)\s+(\w+)/gm;
+  const results: Signature[] = [];
+  for (const m of src.matchAll(re)) {
+    if (m[1] === "private") continue;
+    results.push({
+      modifier: m[1] || undefined,
+      name: m[2],
+    });
+  }
+  return results;
+}

package/src/gates/checkers/scala.ts

@@ -0,0 +1,26 @@
+import { registerChecker } from "./registry.ts";
+import type { ExportChecker } from "./registry.ts";
+import type { Signature } from "../../types.ts";
+
+const scalaChecker: ExportChecker = {
+  extensions: [".scala", ".sc"],
+  getNewExports(before: string, after: string): Signature[] {
+    const beforeNames = new Set(extractExports(before).map((s) => s.name));
+    return extractExports(after).filter((sig) => !beforeNames.has(sig.name));
+  },
+};
+
+registerChecker(scalaChecker);
+
+function extractExports(src: string): Signature[] {
+  const re = /^(?:(private(?:\[[^\]]*\])?|protected(?:\[[^\]]*\])?)\s+)?(?:class|object|trait|def|val|var|type|given|extension)\s+(\w+)/gm;
+  const results: Signature[] = [];
+  for (const m of src.matchAll(re)) {
+    if (m[1] === "private" || m[1] === "protected") continue;
+    results.push({
+      modifier: m[1] || undefined,
+      name: m[2],
+    });
+  }
+  return results;
+}

package/src/gates/frozen-gate.ts

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

package/src/gates/readonly-gate.ts

@@ -1,5 +1,6 @@
 import * as path from "node:path";
 import type { ModuleIndex } from "../types.ts";
+import { getAncestorContracts, matchesPattern } from "../utils.ts";
 
 export type ReadonlyCheckResult =
   | { blocked: true; reason: string }
@@ -16,7 +17,7 @@ export function checkReadonly(
 
   for (const contract of ancestors) {
     for (const pattern of contract.readonly) {
-      if (matchesReadonlyPattern(absFile, pattern, contract.modulePath)) {
+      if (matchesPattern(absFile, pattern, contract.modulePath)) {
         const relModuleMd = path.relative(cwd, path.join(contract.modulePath, descriptorFileName));
         return {
           blocked: true,
@@ -28,26 +29,3 @@ export function checkReadonly(
 
   return { blocked: false };
 }
-
-function getAncestorContracts(absFile: string, index: ModuleIndex) {
-  return index.contracts.filter((c) => absFile.startsWith(c.modulePath + path.sep) || absFile === c.modulePath);
-}
-
-function matchesReadonlyPattern(
-  absFile: string,
-  pattern: string,
-  modulePath: string,
-): boolean {
-  const resolved = path.resolve(modulePath, pattern);
-
-  if (pattern.endsWith("*")) {
-    const prefix = path.resolve(modulePath, pattern.slice(0, -1));
-    return absFile.startsWith(prefix);
-  }
-
-  if (absFile === resolved) return true;
-
-  if (absFile.startsWith(resolved + path.sep)) return true;
-
-  return false;
-}

package/src/graph/MODULE.md

@@ -1,4 +1,8 @@
 ---
-visible: [buildModuleIndex]
+frozen:
+  - frontmatter-parser.ts
+  - module-index-builder.ts
+  - validation.ts
 ---
 
+

package/src/graph/frontmatter-parser.ts

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

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

@@ -4,6 +4,8 @@ import { readdir } from "node:fs/promises";
 import { parseFrontmatter } from "@earendil-works/pi-coding-agent";
 import type { ModuleContract, ModuleIndex } from "../types.ts";
 import type { ModuleGateConfig } from "../config.ts";
+
+type ModuleDescriptorReadonly = ModuleGateConfig["moduleDescriptorReadonly"];
 import type { Dirent } from "node:fs";
 import { validateVisibleEntries } from "./validation.ts";
 import { parseVisibleEntry, type VisibleEntryRaw, type ModuleFrontmatter } from "./frontmatter-parser.ts";
@@ -35,7 +37,7 @@ function buildContracts(
   moduleFiles: string[],
   onInfo: (message: string) => void,
   descriptorFileName: string,
-  moduleDescriptorReadonly: boolean,
+  moduleDescriptorReadonly: ModuleDescriptorReadonly,
 ): ModuleContract[] {
   const contracts: ModuleContract[] = [];
 
@@ -57,7 +59,7 @@ function buildContracts(
     }
 
     const readonlyEntries = frontmatter.readonly ?? [];
-    if (moduleDescriptorReadonly) {
+    if (moduleDescriptorReadonly !== "off") {
       readonlyEntries.push(descriptorFileName);
     }
 
@@ -68,6 +70,7 @@ function buildContracts(
           ? frontmatter.visible.map(parseVisibleEntry)
           : null,
       readonly: readonlyEntries,
+      frozen: frontmatter.frozen ?? [],
       prose: body.trim(),
     });
   }

package/src/index.ts

@@ -4,7 +4,7 @@ import type {
   ToolCallEventResult,
   BeforeAgentStartEventResult,
 } from "@earendil-works/pi-coding-agent";
-import { isToolCallEventType } from "@earendil-works/pi-coding-agent";
+import { isToolCallEventType, parseFrontmatter } from "@earendil-works/pi-coding-agent";
 import type { ModuleIndex } from "./types.ts";
 import { loadConfig } from "./config.ts";
 import type { ModuleGateConfig } from "./config.ts";
@@ -12,6 +12,7 @@ import { buildModuleIndex } from "./graph/module-index-builder.ts";
 import { findOwningModule, readFileSafe, applyEdits, isWithinSourceRoot } from "./utils.ts";
 import { checkReadonly } from "./gates/readonly-gate.ts";
 import { checkExports } from "./gates/export-gate.ts";
+import { checkFrozen } from "./gates/frozen-gate.ts";
 import { buildSystemPromptHint } from "./context/system-prompt.ts";
 import "./gates/checkers/index.ts";
 
@@ -33,7 +34,7 @@ export default function (pi: ExtensionAPI): void {
   pi.on("before_agent_start", async (event): Promise<BeforeAgentStartEventResult | void> => {
     if (index.contracts.length === 0) return;
     return {
-      systemPrompt: buildSystemPromptHint(index, event.systemPrompt, config.moduleDescriptorFileName),
+      systemPrompt: buildSystemPromptHint(index, event.systemPrompt, config.moduleDescriptorFileName, config.moduleDescriptorReadonly),
     };
   });
 
@@ -42,7 +43,9 @@ export default function (pi: ExtensionAPI): void {
       return handleEdit(event.input.path, event.input.edits, ctx.cwd, index, config);
     }
     if (isToolCallEventType("write", event)) {
-      return handleWrite(event.input.path, event.input.content, ctx.cwd, index, config);
+      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);
     }
   });
 }
@@ -55,46 +58,45 @@ function handleEdit(
   config: ModuleGateConfig,
 ): ToolCallEventResult | undefined {
   const absPath = path.resolve(cwd, filePath);
-  const resolvedRoot = path.resolve(cwd, config.sourceRoot);
-
-  if (!isWithinSourceRoot(absPath, resolvedRoot)) return undefined;
-
-  const readonlyResult = checkReadonly(filePath, index, cwd, config.moduleDescriptorFileName);
-  if (readonlyResult.blocked) {
-    return { block: true, reason: formatDenial(filePath, readonlyResult.reason, absPath, index, cwd, config.moduleDescriptorFileName) };
-  }
 
   const before = readFileSafe(absPath);
   const after = applyEdits(before, edits);
+  const srcRoot = path.resolve(cwd, config.sourceRoot);
 
-  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) };
-  }
-
-  return undefined;
-}
-
-function handleWrite(
-  filePath: string,
-  content: string,
-  cwd: string,
-  index: ModuleIndex,
-  config: ModuleGateConfig,
-): ToolCallEventResult | undefined {
-  const absPath = path.resolve(cwd, filePath);
-  const resolvedRoot = path.resolve(cwd, config.sourceRoot);
-
-  if (!isWithinSourceRoot(absPath, resolvedRoot)) return undefined;
+  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 before = readFileSafe(absPath);
+  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, content, 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) };
   }
@@ -124,3 +126,16 @@ function formatDenial(
 
   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

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

package/src/utils.ts

@@ -38,3 +38,31 @@ export function applyEdits(content: string, edits: { oldText: string; newText: s
 export function isWithinSourceRoot(absPath: string, resolvedRoot: string): boolean {
   return absPath.startsWith(resolvedRoot + path.sep) || absPath === resolvedRoot;
 }
+
+export function getAncestorContracts(
+  absFile: string,
+  index: ModuleIndex,
+): { modulePath: string; readonly: string[]; frozen: string[] }[] {
+  return index.contracts
+    .filter((c) => absFile.startsWith(c.modulePath + path.sep) || absFile === c.modulePath)
+    .map(({ modulePath, readonly, frozen }) => ({ modulePath, readonly, frozen }));
+}
+
+export function matchesPattern(
+  absFile: string,
+  pattern: string,
+  modulePath: string,
+): boolean {
+  const resolved = path.resolve(modulePath, pattern);
+
+  if (pattern.endsWith("*")) {
+    const prefix = path.resolve(modulePath, pattern.slice(0, -1));
+    return absFile.startsWith(prefix);
+  }
+
+  if (absFile === resolved) return true;
+
+  if (absFile.startsWith(resolved + path.sep)) return true;
+
+  return false;
+}