@cuzfrog/pi-module-gates 0.17.0 → 0.17.1

package/README.md

@@ -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
-- `sealed` — files where no new exports are allowed (body still editable)
+- `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.
@@ -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?
-     **Sealed gate** — would the change add new exports to a file in the `sealed` list?
+     **Fronzen gate** — is there any surface change to the target file?
    - **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.
 ```
 
-### Sealed constraints
+### Frozen constraints
 
 ```yaml
-sealed: [mod.rs]
+frozen: [mod.rs]
 ```
-Sealed files cannot change their surface size: no new exports or public entries are allowed. The file body is still editable.
+Frozen files cannot change their surface size: no new exports or public entries are allowed.
 
-A skill [module-seal-all](skills/module-seal-all) has been included to auto-seal modules.
+A skill [module-freeze-all](src/skills/module-freeze-all) has been included to auto-freeze modules.
 
 ### Visibility whitelist (under redesign)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cuzfrog/pi-module-gates",
-  "version": "0.17.0",
+  "version": "0.17.1",
   "description": "pi extension that controls the entropy of the codebase by enforcing code module boundaries.",
   "keywords": [
     "pi-package"

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

@@ -1,6 +1,6 @@
 ---
-name: module-seal-all
-description: Auto-seal all files in module descriptors so their module surface area cannot be increased.
+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>
 ---
@@ -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 `sealed` entries with code files in each module directory.
+- Call the script to scans the source tree for module descriptors and auto-populates their `frozen` entries with code files in each module directory.
 
 ## Script Usage
 
 ```bash
-node skills/module-seal-all/scripts/seal-all.mjs [options]
+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 `sealed` only)
+- `--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 `sealed` frontmatter field
-4. Preserves existing `sealed` entries, other fields in the frontmatter, and body prose
+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.d.mts

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

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

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
 /**
- * Auto-seal all files in module descriptors.
+ * Auto-freeze all files in module descriptors.
  *
  * Scans module descriptor files under a source root and populates each
- * descriptor's `sealed` field with every direct code file in the module
+ * descriptor's `frozen` 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 = sealModule(modDir, modFile, descriptorName, allModuleDirs);
+    const result = freezeModule(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}: seal [${r.files.join(", ") || "(none)"}]`);
+      console.log(`  ${rel}: freeze [${r.files.join(", ") || "(none)"}]`);
     }
     return;
   }
@@ -169,7 +169,7 @@ function walkDir(dir, visitor) {
 // Module processing
 // ---------------------------------------------------------------------------
 
-function sealModule(modDir, descriptorFileName, descriptorName, allModuleDirs) {
+function freezeModule(modDir, descriptorFileName, descriptorName, allModuleDirs) {
   const modPath = join(modDir, descriptorFileName);
   let raw;
   try {
@@ -179,15 +179,15 @@ function sealModule(modDir, descriptorFileName, descriptorName, allModuleDirs) {
   }
 
   const parsed = parseFrontmatter(raw);
-  const existingSealed = normalizeSealed(parsed.frontmatter.sealed);
+  const existingFrozen = normalizeFrozen(parsed.frontmatter.frozen);
   const directFiles = listDirectFiles(modDir, descriptorName, allModuleDirs);
-  const mergedSealed = mergePreservingOrder(existingSealed, directFiles);
+  const mergedFrozen = mergePreservingOrder(existingFrozen, directFiles);
 
-  if (arraysEqual(existingSealed, mergedSealed)) return undefined;
+  if (arraysEqual(existingFrozen, mergedFrozen)) return undefined;
 
-  const newContent = serializeModule(parsed, mergedSealed);
+  const newContent = serializeModule(parsed, mergedFrozen);
 
-  return { path: modPath, content: newContent, files: mergedSealed };
+  return { path: modPath, content: newContent, files: mergedFrozen };
 }
 
 function createModuleDescriptor(dir, descriptorName) {
@@ -283,8 +283,8 @@ function parseInlineList(raw) {
   return inner.split(",").map((s) => s.trim().replace(/^['"]|['"]$/g, ""));
 }
 
-function serializeModule(parsed, sealed) {
-  const fm = { ...parsed.frontmatter, sealed };
+function serializeModule(parsed, frozen) {
+  const fm = { ...parsed.frontmatter, frozen };
 
   let yaml = parsed.prelude;
   for (const [key, value] of Object.entries(fm)) {
@@ -344,7 +344,7 @@ function listDirectFiles(modDir, descriptorName, allModuleDirs) {
 // Helpers
 // ---------------------------------------------------------------------------
 
-function normalizeSealed(value) {
+function normalizeFrozen(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,5 +1,6 @@
 ---
-sealed:
+frozen:
   - config.ts
   - index.ts
----
+---
+

package/src/context/MODULE.md

@@ -1,5 +1,6 @@
 ---
-sealed:
+frozen:
   - 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 sealed 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 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.
@@ -9,9 +9,9 @@ A `{{descriptorFileName}}` with a `visible` list means only entries in the list
 {{#if moduleInterfaceImportGate}}- {{moduleInterfaceImportGate}}{{/if}}
 
 ### Glossary
-- `module`: a directory containing code;
-- `external files`: files not in the module directory;
+- `module`: a directory containing code, all files in its recursive subdirectories are internal files of the module;
+- `external files`: files not in the module directory and subdirectories;
 - `module interface`: the file representing the module surface, e.g. `index.ts` in Typescript, `mod.rs` in Rust;
 - `readonly`: files are readonly;
-- `sealed`: files cannot add new exports, but the body is still editable; the export surface is sealed;
+- `frozen`: files cannot add new exports, but still editable;
 - `visible`: visible from outside the module; files not in the module directory are outside the module;

package/src/gates/MODULE.md

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

package/src/gates/checkers/MODULE.md

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

package/src/gates/{sealed-gate.ts → frozen-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 SealedCheckResult =
+export type FrozenCheckResult =
   | { blocked: true; reason: string }
   | { blocked: false };
 
-export function checkSealed(
+export function checkFrozen(
   filePath: string,
   beforeContent: string,
   afterContent: string,
   index: ModuleIndex,
   cwd: string,
   descriptorFileName: string,
-): SealedCheckResult {
+): FrozenCheckResult {
   const absFile = path.resolve(cwd, filePath);
 
   const checker = getChecker(absFile);
@@ -23,7 +23,7 @@ export function checkSealed(
   const ancestors = getAncestorContracts(absFile, index);
 
   for (const contract of ancestors) {
-    for (const pattern of contract.sealed) {
+    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 };
@@ -32,11 +32,11 @@ export function checkSealed(
         const names = newExports.map((s) => s.name).join(", ");
         return {
           blocked: true,
-          reason: `Sealed rule: file is sealed in ${relModuleMd}. Cannot add new exports: ${names}`,
+          reason: `Frozen rule: file is frozen in ${relModuleMd}. Cannot add new exports: ${names}`,
         };
       }
     }
   }
 
   return { blocked: false };
-}
+}

package/src/gates/index.ts

@@ -1,4 +1,4 @@
 export { checkReadonly } from "./readonly-gate.ts";
-export { checkSealed } from "./sealed-gate.ts";
+export { checkFrozen } from "./frozen-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

@@ -5,7 +5,7 @@ import type { ModuleGateConfig } from "../config.ts";
 import { readFileSafe, applyEdits, isWithinSourceRoot, findOwningModule } from "../utils.ts";
 import {
   checkReadonly,
-  checkSealed,
+  checkFrozen,
   checkExports,
   checkModuleInterfaceImports,
 } from "./index.ts";
@@ -57,9 +57,9 @@ export function runGates(
     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 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);

package/src/graph/MODULE.md

@@ -1,7 +1,9 @@
 ---
-sealed:
+frozen:
   - 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[];
-  sealed?: string[];
+  frozen?: string[];
 };
 
 export function parseVisibleEntry(raw: VisibleEntryRaw): Signature {

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

@@ -70,7 +70,7 @@ function buildContracts(
           ? frontmatter.visible.map(parseVisibleEntry)
           : null,
       readonly: readonlyEntries,
-      sealed: frontmatter.sealed ?? [],
+      frozen: frontmatter.frozen ?? [],
       prose: body.trim(),
     });
   }

package/src/types.ts

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

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[]; sealed: string[] }[] {
+): { modulePath: string; readonly: string[]; frozen: string[] }[] {
   return index.contracts
     .filter((c) => absFile.startsWith(c.modulePath + path.sep) || absFile === c.modulePath)
-    .map(({ modulePath, readonly, sealed }) => ({ modulePath, readonly, sealed }));
+    .map(({ modulePath, readonly, frozen }) => ({ modulePath, readonly, frozen }));
 }
 
 export function matchesPattern(

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

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