{"id":50489210,"url":"https://github.com/cuzfrog/pi-module-gates","last_synced_at":"2026-06-02T01:02:56.684Z","repository":{"id":359702923,"uuid":"1246226032","full_name":"cuzfrog/pi-module-gates","owner":"cuzfrog","description":"pi cli extension that controls the entropy of the codebase by enforcing code module boundaries.","archived":false,"fork":false,"pushed_at":"2026-05-27T23:47:27.000Z","size":114,"stargazers_count":1,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-28T01:22:43.001Z","etag":null,"topics":["agent","ai-agents","code-architecture","entropy","harness","module-boundaries","pi","slop"],"latest_commit_sha":null,"homepage":"https://github.com/cuzfrog/pi-module-gate","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cuzfrog.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-05-22T01:59:34.000Z","updated_at":"2026-05-27T23:47:31.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/cuzfrog/pi-module-gates","commit_stats":null,"previous_names":["cuzfrog/pi-module-gate","cuzfrog/pi-module-gates"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/cuzfrog/pi-module-gates","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cuzfrog%2Fpi-module-gates","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cuzfrog%2Fpi-module-gates/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cuzfrog%2Fpi-module-gates/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cuzfrog%2Fpi-module-gates/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cuzfrog","download_url":"https://codeload.github.com/cuzfrog/pi-module-gates/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cuzfrog%2Fpi-module-gates/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33800676,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-01T02:00:06.963Z","response_time":115,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent","ai-agents","code-architecture","entropy","harness","module-boundaries","pi","slop"],"created_at":"2026-06-02T01:02:55.665Z","updated_at":"2026-06-02T01:02:56.664Z","avatar_url":"https://github.com/cuzfrog.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# pi-module-gates - Constraints liberate, liberties constrain.\n\nExpirimental pi cli extension that controls the entropy of the codebase by enforcing code module boundaries.\nIt helps combat slop generation and code architecture degradation.\n\n## Problem\n\nAI coding agents produce edits with limited context knowledge (myopia) — their changes may leak implementation details, and break architectural contracts (slop).\n\n### Approach\n\n**Module contracts as guardrails.** Each directory can contain a descriptor file that declares:\n\n- `readonly` — files and directories the agent must not touch\n- `frozen` — files where no new exports are allowed\n- `visible` — the set of exports allowed to be added or modified in that module\n\nThe extension intercepts agent `write`/`edit` operations and enforces these contracts. Violations are blocked with a clear reason.\n\n### How it works\n\n1. **Indexing** — On session start, scans the project tree for descriptor files and builds a module index.\n2. **System prompt** — Injects a hint so the agent knows to respect descriptor file conventions.\n3. **Gating** — On every write/edit, checks:\n   - **Readonly gate** — is the target file locked?\n     **Fronzen gate** — is there any surface change to the target file?\n   - **Export gate** — would the change introduce an export not in the `visible` list?\n   - **Import gate** (not implemented yet) — would the change introduce an import violating visibility scope?\n\n- System prompt: [system-prompt.md](src/context/system-prompt.ts)\n- Currently [supported languages](src/gates/checkers/index.ts): **TypeScript/JavaScript**, **Rust**, **Java**, **Go**, **Kotlin**, **Scala**\n\n## Installation\n```bash\npi install npm:@cuzfrog/pi-module-gates\n```\nOr load directly for a single session:\n```bash\npi -e npm:@cuzfrog/pi-module-gates\n```\n\n## Module Descriptor Semantics\n\nA 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`.\n\n### Readonly constraints\n\n```markdown\n---\nreadonly: [mod.rs]\n---\n\nAny prose for the agent to better understand the module.\n```\n\n### Frozen constraints\n\n```yaml\nfrozen: [mod.rs]\n```\nFrozen files cannot change their surface size: no new exports or public entries are allowed.\n\nA skill [module-freeze-all](src/skills/module-freeze-all) has been included to auto-freeze modules.\n\n### Visibility whitelist (under redesign)\n\n```yaml\nvisible:\n  - greet # equivalent to `path: ./greet`\n  - sub/mod1/Foo\n```\nor:\n```yaml\nvisible:\n  - path: my_function\n    modifier: pub(crate) # (optional) demands an exact match\n```\n\n| Scenario | Behavior |\n|----------|----------|\n| `visible` key absent or no `MODULE.md` | Module is unconstrained — exports are not gated. Equivalent to `null` internally. |\n| `visible: []` | Module is fully closed — no new exports may be added. Editing existing exports is still allowed. |\n| Malformed YAML frontmatter | The module is left unguarded and an info notification is emitted. |\n\n### Export gating\n\n```\nproject/\n  MODULE.md          visible: [Foo, Bar]\n  src/\n    MODULE.md        visible: [Bar, Baz]\n    app.ts           ← checked against `src/MODULE.md` only\n```\nA `MODULE.md` only enforces exports within its immediate directory.\n\n### Import gating (not implemented yet)\n\n```yaml\n# parent/MODULE.md\nvisible:\n  - sub/Tool # type Tool is allowed to be imported from parent\n\n# parent/sub/MODULE.md (before complement pass)\nvisible:\n  - Bar # type Bar is allowed to be imported from parent/sub within parent, but not outside parent\n```\nA `MODULE.md` semantically gates exposures at the module level it resides.\n\n## Configuration\n\nAdd a `module-gate` entry to `.pi/settings.json`:\n\n```json\n{\n  \"module-gate\": {\n    \"moduleDescriptorFileName\": \"MODULE.md\",\n    \"moduleDescriptorReadonly\": true,\n    \"sourceRoot\": \"src/\"\n  }\n}\n```\n\n| Option | Default | Description |\n|--------|---------|-------------|\n| `moduleDescriptorFileName` | `\"MODULE.md\"` | File name used for module descriptors (case-insensitive) |\n| `moduleDescriptorReadonly` | `true` | When `true`, descriptor files are readonly.|\n| `sourceRoot` | `\"src/\"` | Directory to scan for descriptor files and enforce gates. Set to `\"\"` to scan from project root. |\n\nWhen no settings file exists or no `module-gate` key is present, defaults apply.\n\n## License\n\nMIT\n\n## Author\nCause Chung (cuzfrog@gmail.com)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcuzfrog%2Fpi-module-gates","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcuzfrog%2Fpi-module-gates","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcuzfrog%2Fpi-module-gates/lists"}