{"_id":"@amrishkhan05/hallpass","_rev":"6-080a9ab5c20f8cf7526593f853482887","name":"@amrishkhan05/hallpass","dist-tags":{"latest":"0.2.0"},"versions":{"0.1.1":{"name":"@amrishkhan05/hallpass","version":"0.1.1","keywords":["ai","coding-agent","agents-md","claude-code","codex","cursor","copilot","policy","guardrails","developer-tools","cli","architecture"],"license":"MIT","_id":"@amrishkhan05/hallpass@0.1.1","maintainers":[{"name":"amrishkhan05","email":"amrishkhan05@gmail.com"}],"homepage":"https://github.com/amrishkhan05/hallpass#readme","bugs":{"url":"https://github.com/amrishkhan05/hallpass/issues"},"bin":{"hallpass":"dist/cli/index.js"},"dist":{"shasum":"e21fbdc2122530667899d572c25dc80b5bda6480","tarball":"https://registry.npmjs.org/@amrishkhan05/hallpass/-/hallpass-0.1.1.tgz","fileCount":62,"integrity":"sha512-jUq64YJ+YZhAwCuFR2t6UuXOQxUHeCJdICqHiU6gE+KJTsH1N0RZe7LLjhlu9nRmDfCE0F6y789tGoW9a3lESg==","signatures":[{"sig":"MEYCIQCpfLhLKMJy5v2UzksITqlPjBdYmV/KX8SNp6bkNy78RAIhAJ6t2Lu0GqcWotiVbKyp0n8/GGtdoACtmkFUd2pX7DhO","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":1053763},"type":"module","engines":{"node":">=20.19"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"0d7267aa7d89db403662eb22ff015a873c275679","scripts":{"lint":"eslint .","test":"npm run build && node --test tests/*.test.js","build":"npm run clean && tsc -p tsconfig.json && node scripts/make-executable.mjs","check":"npm run typecheck && npm run lint && npm test","clean":"node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"","typecheck":"tsc --noEmit","pack:check":"npm pack --dry-run","test:coverage":"npm run build && node --test --experimental-test-coverage tests/*.test.js","prepublishOnly":"npm run check","validate:package":"node scripts/validate-package.mjs"},"_npmUser":{"name":"amrishkhan05","email":"amrishkhan05@gmail.com"},"repository":{"url":"git+https://github.com/amrishkhan05/hallpass.git","type":"git"},"_npmVersion":"10.9.3","description":"Runtime policy enforcement for AI coding agents.","directories":{},"_nodeVersion":"22.19.0","dependencies":{"yaml":"^2.9.0","commander":"^14.0.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"eslint":"^10.9.1","@eslint/js":"^10.0.1","typescript":"^5.9.2","@types/node":"^24.3.0","typescript-eslint":"^8.69.0"},"_npmOperationalInternal":{"tmp":"tmp/hallpass_0.1.1_1788284381028_0.26431737404261435","host":"s3://npm-registry-packages-npm-production"}},"0.1.2":{"name":"@amrishkhan05/hallpass","version":"0.1.2","keywords":["ai","coding-agent","agents-md","claude-code","codex","cursor","copilot","policy","guardrails","developer-tools","cli","architecture"],"license":"MIT","_id":"@amrishkhan05/hallpass@0.1.2","maintainers":[{"name":"amrishkhan05","email":"amrishkhan05@gmail.com"}],"homepage":"https://github.com/amrishkhan05/hallpass#readme","bugs":{"url":"https://github.com/amrishkhan05/hallpass/issues"},"bin":{"hallpass":"dist/cli/index.js"},"dist":{"shasum":"5849406001b23f0892c8a83ee6a701183b4322e6","tarball":"https://registry.npmjs.org/@amrishkhan05/hallpass/-/hallpass-0.1.2.tgz","fileCount":62,"integrity":"sha512-+tLzw1Sah2PSLlSL8szFJPHXnTtNWZrYBDdpmPM5c2SertZWzwXc2whpu3nfqNWFfyZ7qFibtcSpLBAe25KYcw==","signatures":[{"sig":"MEUCIHPhGewPfuLCpLS2sz7pUrzAujgBL6i17Hj12HDrt4LxAiEA1Qsgsw0j95L8nbn0WUhHxvlODj7PQS6MMoyw4h7nYiA=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"sig":"MEQCIAsNtMbKR1gAlYurpxXBY0D+P92qktUhRerpca1RkM2BAiBjPPXVPT2K5+ik2alOtckBc6qpwCRVOCdbNajrLMTMkg==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":1053763},"type":"module","engines":{"node":">=20.19"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"61330c601a8267bd3fb98147b2a208861017ca86","scripts":{"lint":"eslint .","test":"npm run build && node --test tests/*.test.js","build":"npm run clean && tsc -p tsconfig.json && node scripts/make-executable.mjs","check":"npm run typecheck && npm run lint && npm test","clean":"node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"","typecheck":"tsc --noEmit","pack:check":"npm pack --dry-run","test:coverage":"npm run build && node --test --experimental-test-coverage tests/*.test.js","prepublishOnly":"npm run check","validate:package":"node scripts/validate-package.mjs"},"_npmUser":{"name":"amrishkhan05","email":"amrishkhan05@gmail.com"},"repository":{"url":"git+https://github.com/amrishkhan05/hallpass.git","type":"git"},"_npmVersion":"10.9.3","description":"Runtime policy enforcement for AI coding agents.","directories":{},"_nodeVersion":"22.19.0","dependencies":{"yaml":"^2.9.0","commander":"^14.0.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"readmeFilename":"README.md","devDependencies":{"eslint":"^10.9.1","@eslint/js":"^10.0.1","typescript":"^5.9.2","@types/node":"^24.3.0","typescript-eslint":"^8.69.0"},"_npmOperationalInternal":{"tmp":"tmp/hallpass_0.1.2_1788284705663_0.47433881387633625","host":"s3://npm-registry-packages-npm-production"}},"0.1.3":{"name":"@amrishkhan05/hallpass","version":"0.1.3","keywords":["ai","coding-agent","agents-md","claude-code","codex","cursor","copilot","policy","guardrails","developer-tools","cli","architecture"],"license":"MIT","_id":"@amrishkhan05/hallpass@0.1.3","maintainers":[{"name":"amrishkhan05","email":"amrishkhan05@gmail.com"}],"homepage":"https://github.com/amrishkhan05/hallpass#readme","bugs":{"url":"https://github.com/amrishkhan05/hallpass/issues"},"bin":{"hallpass":"dist/cli/index.js"},"dist":{"shasum":"40d4781d39234631df844bd6579b24ebb5aa3327","tarball":"https://registry.npmjs.org/@amrishkhan05/hallpass/-/hallpass-0.1.3.tgz","fileCount":62,"integrity":"sha512-ovBXw9k0KPujZs4Qyz3iWQl+LlriIxkVSMNckB5s3FmO6NoLg8yMuh1kcP9ETK3tboqx3JYjNnrwLZntrMW5Lg==","signatures":[{"sig":"MEUCIHdCYjqryvZq+J+2S5bByK/Xg9vdQqYWo6c2oO41aje5AiEAuuWslkBMslvUzELVstxekfTDidlkcCHbiqMuDouSauQ=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"sig":"MEUCIDcAAF+Rrp4LVPG+R/uXdBpb3dbx/AcEs2R7OsXfgtF/AiEAi1rHKNCIEYE4ilMb109M5PfOjH6wXDOn/df8SamKC1Y=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":1053763},"type":"module","engines":{"node":">=20.19"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"d866a60955f61a3bf7591fe2e69ebee4ad5a7f26","scripts":{"lint":"eslint .","test":"npm run build && node --test tests/*.test.js","build":"npm run clean && tsc -p tsconfig.json && node scripts/make-executable.mjs","check":"npm run typecheck && npm run lint && npm test","clean":"node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"","typecheck":"tsc --noEmit","pack:check":"npm pack --dry-run","test:coverage":"npm run build && node --test --experimental-test-coverage tests/*.test.js","prepublishOnly":"npm run check","validate:package":"node scripts/validate-package.mjs"},"_npmUser":{"name":"amrishkhan05","email":"amrishkhan05@gmail.com"},"repository":{"url":"git+https://github.com/amrishkhan05/hallpass.git","type":"git"},"_npmVersion":"10.9.3","description":"Runtime policy enforcement for AI coding agents.","directories":{},"_nodeVersion":"22.19.0","dependencies":{"yaml":"^2.9.0","commander":"^14.0.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"eslint":"^10.9.1","@eslint/js":"^10.0.1","typescript":"^5.9.2","@types/node":"^24.3.0","typescript-eslint":"^8.69.0"},"_npmOperationalInternal":{"tmp":"tmp/hallpass_0.1.3_1788284834313_0.5892605542448475","host":"s3://npm-registry-packages-npm-production"}},"0.1.4":{"name":"@amrishkhan05/hallpass","version":"0.1.4","keywords":["ai","coding-agent","agents-md","claude-code","codex","cursor","copilot","policy","guardrails","developer-tools","cli","architecture"],"license":"MIT","_id":"@amrishkhan05/hallpass@0.1.4","maintainers":[{"name":"amrishkhan05","email":"amrishkhan05@gmail.com"}],"homepage":"https://github.com/amrishkhan05/hallpass#readme","bugs":{"url":"https://github.com/amrishkhan05/hallpass/issues"},"bin":{"hallpass":"dist/cli/index.js"},"dist":{"shasum":"d5076f0b4690cbb3fc63b090c87a08069c2af714","tarball":"https://registry.npmjs.org/@amrishkhan05/hallpass/-/hallpass-0.1.4.tgz","fileCount":62,"integrity":"sha512-NKfgpwLtB1vDgdzscGdIM8lCDXqqgQPSJbBEyDMcskJvf7Xe8EVgbAZ7k9VGWYc4vSt0UEXnk3UcYt4g0YwChQ==","signatures":[{"sig":"MEUCIBOsZQF5HQrk6vAd+aIGQa1eTROWy0M57W6FSPPinQpxAiEAyJ5/mY48StQUP67KELbDxzmqaKc1ynQLHVhFHPlzHDE=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"sig":"MEUCICoHq1oNQDu1wr4QFETHbp1tkq9/mC1B25fF2pqnJzeOAiEAufWa9Z191dPMqVPt4UimxsgKwLDmZdF2trCFISjI2eo=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@amrishkhan05%2fhallpass@0.1.4","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":1053285},"type":"module","engines":{"node":">=20.19"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"3f06d2cf8c8a63d119cdd700514ec50b052b2f12","scripts":{"lint":"eslint .","test":"npm run build && node --test tests/*.test.js","build":"npm run clean && tsc -p tsconfig.json && node scripts/make-executable.mjs","check":"npm run typecheck && npm run lint && npm test","clean":"node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"","typecheck":"tsc --noEmit","pack:check":"npm pack --dry-run","test:coverage":"npm run build && node --test --experimental-test-coverage tests/*.test.js","prepublishOnly":"npm run check","validate:package":"node scripts/validate-package.mjs"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:c857cbee-2fd6-4657-b6e8-a840166b1250"}},"repository":{"url":"git+https://github.com/amrishkhan05/hallpass.git","type":"git"},"_npmVersion":"12.0.2","description":"Runtime policy enforcement for AI coding agents.","directories":{},"_nodeVersion":"22.23.2","dependencies":{"yaml":"^2.9.0","commander":"^15.0.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"eslint":"^10.9.1","@eslint/js":"^10.0.1","typescript":"^5.9.2","@types/node":"^26.4.0","typescript-eslint":"^8.69.0"},"_npmOperationalInternal":{"tmp":"tmp/hallpass_0.1.4_1788288402516_0.9635029432638009","host":"s3://npm-registry-packages-npm-production"}},"0.1.5":{"name":"@amrishkhan05/hallpass","version":"0.1.5","keywords":["ai","coding-agent","agents-md","claude-code","codex","cursor","copilot","policy","guardrails","developer-tools","cli","architecture"],"license":"MIT","_id":"@amrishkhan05/hallpass@0.1.5","maintainers":[{"name":"amrishkhan05","email":"amrishkhan05@gmail.com"}],"homepage":"https://github.com/amrishkhan05/hallpass#readme","bugs":{"url":"https://github.com/amrishkhan05/hallpass/issues"},"bin":{"hallpass":"dist/cli/index.js"},"dist":{"shasum":"9a7a1e527b63485e5ba72616d4c45aac9757caef","tarball":"https://registry.npmjs.org/@amrishkhan05/hallpass/-/hallpass-0.1.5.tgz","fileCount":81,"integrity":"sha512-tM79Kc0yUH86wvjm5fZYbPYNemvUNhvuum11IVBI1vuWgkxmyAepDnsZgSrQmSPUzs3hWjDNcJvyZ4qF9nQgsQ==","signatures":[{"sig":"MEYCIQDV5AeC+v3pUrRBDOTKZvyzAHNH5lMsmPmPj/er+KXBNAIhANaDUMetw5ZodOVGO5zksni5OdWjgABRdsmuUuOEvQSy","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"sig":"MEQCIHu4z0a2PfZgAG0HJpvw1aLWf3SicnDglESmJ2EaX6brAiAntl0/XTo4+cnBLVYJjI6npgqVMdjM5pFe9j3QNMpnAA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@amrishkhan05%2fhallpass@0.1.5","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":1139579},"type":"module","engines":{"node":">=20.19"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"b372ca236d326d0ac792aebc9df9377d07ea61f6","scripts":{"lint":"eslint .","test":"npm run build && node --test tests/*.test.js","build":"npm run clean && tsc -p tsconfig.json && node scripts/make-executable.mjs","check":"npm run typecheck && npm run lint && npm test","clean":"node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"","typecheck":"tsc --noEmit","pack:check":"npm pack --dry-run","test:coverage":"npm run build && node --test --experimental-test-coverage tests/*.test.js","prepublishOnly":"npm run check","validate:package":"node scripts/validate-package.mjs"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:c857cbee-2fd6-4657-b6e8-a840166b1250"}},"repository":{"url":"git+https://github.com/amrishkhan05/hallpass.git","type":"git"},"_npmVersion":"12.0.2","description":"Runtime policy enforcement for AI coding agents.","directories":{},"_nodeVersion":"22.23.2","dependencies":{"yaml":"^2.9.0","commander":"^15.0.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"eslint":"^10.9.1","@eslint/js":"^10.0.1","typescript":"^5.9.2","@types/node":"^26.4.0","typescript-eslint":"^8.69.0"},"_npmOperationalInternal":{"tmp":"tmp/hallpass_0.1.5_1788327213232_0.08713869429820909","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"_id":"@amrishkhan05/hallpass@0.2.0","bin":{"hallpass":"dist/cli/index.js"},"bugs":{"url":"https://github.com/amrishkhan05/hallpass/issues"},"dist":{"shasum":"9fab0fb85b202859d1692e72d01d3f0e72930207","tarball":"https://registry.npmjs.org/@amrishkhan05/hallpass/-/hallpass-0.2.0.tgz","fileCount":108,"integrity":"sha512-zrs7NwklMVL2gKRowlOFeSA+5YvkgmDEzOz9XJ+NnnnNwPe3R7EVnGwGpQiinpI0outWEEI8+16fYJ8HGLqngw==","signatures":[{"sig":"MEUCIQDV6NyfpouMzE7iSfIWbtJ1rrRbtnoy0wUSNqdxoo1T5QIgdaidYTKmjH4yjdHG27XnZ5hzuW6WLnjskjsusq949s4=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIHEPwmjHKZodWYb/MdenSo5q2bhav53WBKGL33euGeduAiBeyFx9V5hJppShjYbXk+CB/jcBFvVNA+m4lZM+6N1llQ=="}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@amrishkhan05%2fhallpass@0.2.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":1252694},"name":"@amrishkhan05/hallpass","type":"module","author":{"url":"https://www.amrishkhan.dev","name":"Amrish Khan"},"engines":{"node":">=20.19"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"fcbfa01afd3e2171d4a8868673fe2c6622e5b4e4","license":"MIT","scripts":{"lint":"eslint .","test":"npm run build && node --test tests/*.test.js","build":"npm run clean && node scripts/generate-version.mjs && tsc -p tsconfig.json && node scripts/make-executable.mjs","check":"npm run typecheck && npm run lint && npm test","clean":"node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"","typecheck":"tsc --noEmit","pack:check":"npm pack --dry-run","test:coverage":"npm run build && node --test --experimental-test-coverage tests/*.test.js","prepublishOnly":"npm run check","validate:package":"node scripts/validate-package.mjs"},"version":"0.2.0","_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:c857cbee-2fd6-4657-b6e8-a840166b1250"}},"homepage":"https://github.com/amrishkhan05/hallpass#readme","keywords":["ai","coding-agent","agents-md","claude-code","codex","cursor","copilot","policy","guardrails","developer-tools","cli","architecture"],"repository":{"url":"git+https://github.com/amrishkhan05/hallpass.git","type":"git"},"_npmVersion":"12.0.2","description":"Runtime policy enforcement for AI coding agents.","directories":{},"maintainers":[{"name":"amrishkhan05","email":"amrishkhan05@gmail.com"}],"_nodeVersion":"24.19.0","dependencies":{"yaml":"^2.9.0","commander":"^15.0.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"eslint":"^10.9.1","@eslint/js":"^10.0.1","typescript":"^5.9.2","@types/node":"^26.4.0","typescript-eslint":"^8.69.0"},"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/hallpass_0.2.0_1788344457590_0.351875519503539"}}},"time":{"created":"2026-09-01T17:39:40.851Z","modified":"2026-09-02T10:20:58.167Z","0.1.1":"2026-09-01T17:39:41.194Z","0.1.2":"2026-09-01T17:45:05.831Z","0.1.3":"2026-09-01T17:47:14.435Z","0.1.4":"2026-09-01T18:46:42.658Z","0.1.5":"2026-09-02T05:33:33.356Z","0.2.0":"2026-09-02T10:20:57.759Z"},"bugs":{"url":"https://github.com/amrishkhan05/hallpass/issues"},"license":"MIT","homepage":"https://github.com/amrishkhan05/hallpass#readme","keywords":["ai","coding-agent","agents-md","claude-code","codex","cursor","copilot","policy","guardrails","developer-tools","cli","architecture"],"repository":{"url":"git+https://github.com/amrishkhan05/hallpass.git","type":"git"},"description":"Runtime policy enforcement for AI coding agents.","maintainers":[{"name":"amrishkhan05","email":"amrishkhan05@gmail.com"}],"readme":"# Hallpass 🎉\n\n> **Because apparently AI agents need adult supervision.**\n\n![Hallpass Mascot](https://raw.githubusercontent.com/amrishkhan05/hallpass/main/assets/hallpass_mascot.jpg)\n\nYour new best friend for keeping AI‑generated code in check. Hallpass snoops around your repo, remembers where every rule came from, and makes sure the AI doesn’t go rogue. Think of it as the hall monitor who actually knows the rules.\n\n> **Prompts tell the story. Policies keep it honest.**  \n> **Your AI has a brain; Hallpass gives it a conscience.**\n\n---\n\n## 🚀 Install\n\n```bash\nnpm install -g @amrishkhan05/hallpass\nhallpass init\n```\n\n`AGENTS.md` is optional. Interactive initialization offers to create a concise starter; non-interactive runs create it only with `hallpass init --create-agents` (add `--force` to replace an existing file).\n\nOr, if you hate installing globals (who doesn’t?), just run it on the fly:\n\n```bash\nnpx @amrishkhan05/hallpass init\n```\n\n`hallpass init` scans instruction files, activates deterministic policies, and records the compiled policy in `.hallpass/compiled.json`. Semantic and ambiguous guidance remains non-blocking; the [example config](hallpass.config.example.yml) shows the supported rule shape.\n\n---\n\n## 👤 Author\n\n**AmrishKhan** – [website](https://www.amrishkhan.dev)\n\nEmail: [amrishkhan05@gmail.com](mailto:amrishkhan05@gmail.com)\n\n## ⚡ Quick start (no PhD required)\n\n```bash\nhallpass scan          # Gather every instruction we can find\nhallpass agents suggest # Preview evidence-backed AGENTS.md suggestions\nhallpass agents init    # Review and create AGENTS.md explicitly\nhallpass rules         # Turn them into policies\nhallpass check         # See if your changes pass the test\nhallpass check --staged\nhallpass ci --base origin/main   # CI‑friendly mode\nhallpass explain ARCH-001       # Deep dive on a rule\nhallpass context src/users/users.controller.ts   # Why did this rule fire?\nhallpass doctor        # Give the engine a health check\nhallpass conflicts     # Spot any rule clashes\n```\n\nAdd `--json` to any command for machine‑readable output. Exit codes are our way of saying “All good” or “Uh‑oh”:\n- `0` – pass\n- `1` – violation\n- `2` – config error\n- `3` – engine failure\n- `4` – approval needed\n- `5` – unresolved conflict\n\n---\n\n## 🛡️ What v0.1 actually enforces\n\n---\n\n## ✨ New Features & Commands\n\n- **Plugin installation**: `hallpass install claude`, `hallpass install cursor`, `hallpass install all` – wires native pre‑tool hooks for Claude Code, Cursor, etc.\n- **Additional CLI commands**:\n  - `hallpass scan` – discovers all instruction files in the repo.\n  - `hallpass rules` – compiles and lists enforced policies.\n  - `hallpass check` – validates current changes against policies.\n  - `hallpass ci --base <ref>` – CI‑friendly mode for CI pipelines.\n  - `hallpass explain <RULE>` – deep‑dive into a specific rule.\n  - `hallpass context <path>` – shows why a rule fired for a file.\n  - `hallpass doctor` – health check of the Hallpass engine.\n  - `hallpass conflicts` – detects rule clashes.\n- **Skill file**: The repository includes a `skills/hallpass/SKILL.md` that describes Hallpass capabilities for AI agents, enabling agents to invoke Hallpass automatically when relevant.\n- **Trusted Publishing**: Publishing now uses npm Trusted Publishing with OIDC; the workflow checks for existing versions before publishing.\n\n---\n\n## 🛡️ What v0.1 actually enforces\n\n- **Path rules** – protect, forbid, or generate files.\n- **Governance changes** – watch dependency adds/removes.\n- **Deny‑lists & forbidden imports** – keep bad libs out.\n- **Architecture boundaries** – simple but effective.\n- **Explicit `any`, `@ts‑ignore`, `eslint‑disable`** – no sneaky escapes.\n- **Test deletions & required commands** – keep your test suite alive.\n- **Max changed files / LOC** – avoid massive accidental rewrites.\n- **Shell‑command policies** – keep dangerous shells in check.\n\nAll checks are diff‑aware (working tree, staged, single commit, or base‑ref). Untracked, renamed, deleted, and binary files are normalized as events. Existing debt stays hidden unless the current diff touches it.\n\nOur scanner tags instructions as deterministic, structural, semantic, advisory, or ambiguous. Deterministic and structural rules are enforced; heuristic and semantic interpretations remain warnings.\n\n---\n\n## 📚 Evidence & approvals (the paperwork you actually want to read)\n\nEvery finding comes with a nice package:\n- Rule ID, classification, decision, and location.\n- Evidence, remediation steps, and a stable fingerprint.\n- A little persona blurb generated from that fingerprint (turn it off with `persona.intensity=0` or use `hallpass ci` for a corporate tone).\n\nRecord a human approval outside the policy file like this:\n\n```bash\nhallpass allow DEP-001 --reason \"Approved Zod migration\" --expires 2026-12-31\n```\n\nApprovals live under `.hallpass/` with reason, time, scope, and expiry. A repo edit can’t grant itself an approval—CI stays the ultimate gatekeeper.\n\n> **Pro tip:** Keep the `hallpass allow` command out of the agent allow‑list. Local enforcement can’t stop a rogue process that already has full filesystem access.\n\n---\n\n## 🔎 Where Hallpass looks for instructions\n\nIt recursively hunts for:\n- `AGENTS.md`, `AGENTS.override.md`, `CLAUDE.md`\n- `.cursor/rules/**/*.md` & `.cursor/rules/**/*.mdc`\n- `.github/copilot-instructions.md`\n- `.github/instructions/**/*.instructions.md`\n\n`hallpass scan` reports policy as `CONFIGURED` when Hallpass config exists, `INFERRED` when only supported instruction files contain usable guidance, and `UNCONFIGURED` otherwise. Built-in safety remains active in every state; generated suggestions are not active policy until a human explicitly adopts them.\n\nWe keep the source file, line, original text, compiler version, and a fingerprint for every proposal. If two rules clash, `hallpass conflicts` will point it out—Hallpass never picks a winner in secret.\n\n---\n\n## 🤖 Agent adapters (the nice people who talk to Hallpass)\n\nThe core is agent‑agnostic. `hallpass hook <adapter>` accepts native hook JSON on stdin, normalizes it, runs our policies, and spits out the adapter‑specific permission response.\n\n**One‑command install (Claude Code, Cursor):**\n```bash\nhallpass install all      # or: hallpass install claude / hallpass install cursor\n```\nThis merges the hook wiring below into `.claude/settings.json` / `.cursor/hooks.json` without touching any other settings, and is safe to re-run.\n\n**Claude’s pre‑tool hook:**\n```json\n{\n  \"hooks\": {\n    \"PreToolUse\": [{\n      \"matcher\": \"Bash\",\n      \"hooks\": [{ \"type\": \"command\", \"command\": \"hallpass hook claude\" }]\n    }]\n  }\n}\n```\n\n**Cursor’s project hook (`.cursor/hooks.json`):**\n```json\n{\n  \"version\": 1,\n  \"hooks\": {\n    \"beforeShellExecution\": [{\n      \"command\": \"hallpass hook cursor\",\n      \"failClosed\": true\n    }]\n  }\n}\n```\n\nClaude and Cursor have native pre‑shell responses. Generic Git/CI provides the ultimate diff verification. Codex and Copilot metadata are there, but we don’t claim native lifecycle installation in v0.1 — instead Hallpass ships a [`skills/hallpass/SKILL.md`](skills/hallpass/SKILL.md) that any skill‑aware agent (Copilot, Codex, Claude) can discover, telling it to run `hallpass check`/`hallpass ci` itself.\n\n**Installing Hallpass as a plugin:**\n- **Claude Code**: `/plugin marketplace add amrishkhan05/hallpass` then `/plugin install hallpass` — wires the `PreToolUse` hook above automatically via [`.claude-plugin/`](.claude-plugin).\n- **Cursor**: the [`.cursor/rules/hallpass.mdc`](.cursor/rules/hallpass.mdc) rule is picked up automatically once the repo is cloned; run `hallpass install cursor` for the enforced pre‑shell hook.\n- **Codex / Copilot / any agent**: point it at [`skills/hallpass/SKILL.md`](skills/hallpass/SKILL.md) (or just keep `AGENTS.md`/`.github/copilot-instructions.md` in the repo — Hallpass already scans those).\n\n---\n\n## 🏗️ CI integration (because automation is cool)\n\n```yaml\n- run: npx @amrishkhan05/hallpass ci --base origin/main\n```\n\nGit hooks are optional shortcuts; protected‑branch CI is the real enforcer. Hallpass is a policy‑enforcer, not a sandbox for your OS.\n\n---\n\n## 🛠️ Development & release (how to ship this thing)\n\n```bash\nnpm ci\nnpm run check\nnpm pack\n```\n\nWhen `package.json` contains a version missing from either registry, a push to `main` publishes it to **npm** and **GitHub Packages**. npm uses Trusted Publishing for repository `amrishkhan05/hallpass` and workflow `publish.yml`; GitHub Packages uses the workflow's `GITHUB_TOKEN`.\n\nRelease steps:\n```bash\nnpm version patch\ngit push origin main\n```\n\n---\n\n## 📖 Further reading (because you love docs)\n\n- See [SECURITY.md](SECURITY.md) for the trust model.\n- See [CONTRIBUTING.md](CONTRIBUTING.md) for how to help out.\n\n> **The AI can forget your rules. Hallpass doesn’t.**\n\n\n> **Because apparently AI agents need adult supervision.**\n\n![Hallpass Mascot](https://raw.githubusercontent.com/amrishkhan05/hallpass/main/hallpass_mascot.jpg)\n\nYour trusty **policy‑as‑code sidekick** for AI‑generated software changes. Hallpass discovers repository instructions, preserves their provenance, and evaluates deterministic constraints against real Git changes. Think of it as a vigilant hall monitor for your code‑base—ensuring AI agents stay in line.\n\n> **Prompts express intent. Policies enforce invariants.**  \n> **Your AI has instructions. Hallpass gives them teeth.**\n\n\n### Because apparently AI agents need adult supervision.\n\nYour coding agent read `AGENTS.md`. It also read `CLAUDE.md`, your Cursor rules, and your Copilot instructions. Then it ignored one of them. **Hallpass noticed.**\n\nHallpass is local-first policy-as-code for AI-generated software changes. It discovers repository instructions, preserves their provenance, and evaluates approved deterministic constraints against real Git changes.\n\n> **Prompts express intent. Policies enforce invariants.**\n\n> **Your AI has instructions. Hallpass gives them teeth.**\n\n## Install\n\n```bash\nnpm install -g @amrishkhan05/hallpass\nhallpass init\n```\n\nOr run it without installing:\n\n```bash\nnpx @amrishkhan05/hallpass init\n```\n\n`init` discovers instruction sources, activates deterministic policies, and writes the compiled state to `.hallpass/compiled.json`. Ambiguous prose remains non-blocking; [the example config](hallpass.config.example.yml) documents the supported shape.\n\n## Quick start\n\n```bash\nhallpass scan\nhallpass rules\nhallpass check\nhallpass check --staged\nhallpass ci --base origin/main\nhallpass explain ARCH-001\nhallpass context src/users/users.controller.ts\nhallpass doctor\nhallpass conflicts\n```\n## 📊 Project analysis & missing pieces\n\n> **What’s cooking?** Hallpass already packs a punch, but there’s room for extra flavor:\n\n- **Feature completeness**: Core policy enforcement is solid, but a **web UI dashboard** for visual rule inspection is not yet bundled.\n- **Language support**: Currently tuned for JavaScript/TypeScript projects; extending to Python, Go, or Rust would broaden appeal.\n- **Integration hooks**: We have adapters for Claude and Cursor; adding generic LLM hooks (e.g., GitHub Copilot, Bard) could simplify adoption.\n- **Documentation**: The README now shines, but a **quick‑start video** or animated GIF would help newcomers get up‑to‑speed.\n- **Testing suite**: Automated tests for rule parsing and engine behavior exist, yet **end‑to‑end CI examples** across multiple CI providers (GitHub Actions, GitLab CI) would be valuable.\n\nThese are **opportunities**, not deficiencies—Hallpass works great out‑of‑the‑box, and the community can help grow it.\n\nMachine-readable output is available with `--json` on the primary commands. Stable exit codes are `0` pass, `1` violation, `2` configuration error, `3` engine failure, `4` approval required, and `5` unresolved conflict.\n\n## What v0.1 enforces\n\nThe engine supports protected/forbidden/generated paths, governance changes, dependency additions/removals and deny lists, forbidden imports and simple architecture boundaries, explicit TypeScript `any`, `@ts-ignore`, `eslint-disable`, test deletion, required commands, maximum changed files/LOC, and shell command policies.\n\nChecks are diff-aware and understand working-tree, staged, single-commit, and base-ref comparisons. Untracked, renamed, deleted, and binary files are normalized as events. Existing repository debt is not reported unless the current diff touches it.\n\nNatural-language scanning classifies instructions as deterministic, structural, semantic, advisory, or ambiguous. Deterministic and structural rules enforce outcomes; heuristic and semantic interpretation remains non-blocking.\n\n## Evidence and approvals\n\nEvery finding includes a rule ID, classification, decision, location, evidence, remediation, and stable fingerprint. Persona text is selected deterministically from that fingerprint and never changes the policy result. Set `persona.intensity` to `0`, disable it entirely, or use `hallpass ci` for professional output.\n\nRecord a human approval outside the policy file:\n\n```bash\nhallpass allow DEP-001 --reason \"Approved Zod migration\" --expires 2026-12-31\n```\n\nApprovals are stored locally under `.hallpass/` with reason, time, scope, and expiry. A repository edit cannot grant itself an approval. CI should remain the authoritative final gate.\n\nAgent shell hooks always deny `hallpass allow` and direct writes to the approval store. Keep the approval command outside agent allowlists; local enforcement cannot protect against a process that already has unrestricted access to the user's filesystem.\n\n## Instruction sources\n\nHallpass recursively discovers `AGENTS.md`, `AGENTS.override.md`, `CLAUDE.md`, `.cursor/rules/**/*.md`, `.cursor/rules/**/*.mdc`, `.github/copilot-instructions.md`, and `.github/instructions/**/*.instructions.md`. Source file, line, original text, compiler version, and fingerprints are retained in compiled proposals.\n\nPossible contradictions are surfaced by `hallpass conflicts`; Hallpass never silently chooses a winner.\n\n## Agent adapters\n\nThe core is agent-independent. `hallpass hook <adapter>` accepts native hook JSON on stdin, normalizes it into a Hallpass event, evaluates shell policies, and emits the adapter's native permission response.\n\nClaude Code `PreToolUse` command hook:\n\n```json\n{\n  \"hooks\": {\n    \"PreToolUse\": [{\n      \"matcher\": \"Bash\",\n      \"hooks\": [{ \"type\": \"command\", \"command\": \"hallpass hook claude\" }]\n    }]\n  }\n}\n```\n\nCursor project hook in `.cursor/hooks.json`:\n\n```json\n{\n  \"version\": 1,\n  \"hooks\": {\n    \"beforeShellExecution\": [{\n      \"command\": \"hallpass hook cursor\",\n      \"failClosed\": true\n    }]\n  }\n}\n```\n\nClaude and Cursor have native pre-shell responses. Generic Git/CI provides authoritative diff verification. Codex and Copilot capability metadata and event normalization are present, but native lifecycle installation is not claimed in v0.1.\n\nRun `hallpass install claude`, `hallpass install cursor`, or `hallpass install all` to wire these hooks automatically instead of editing the files by hand.\n\n## CI\n\n```yaml\n- run: npx @amrishkhan05/hallpass ci --base origin/main\n```\n\nGit hooks are optional convenience gates and can be bypassed; protected branch CI is the reliable final boundary. Hallpass is policy enforcement, not an operating-system sandbox.\n\n## Development and release\n\n```bash\nnpm ci\nnpm run check\nnpm pack\n```\n\nThe publish workflow sends a version missing from either registry to npm and GitHub Packages on pushes to `main`. npm Trusted Publishing must first be configured on npmjs.com for repository `amrishkhan05/hallpass` and workflow `publish.yml`; GitHub Packages uses the workflow's `GITHUB_TOKEN`.\n\nRelease:\n\n```bash\nnpm version patch\ngit push origin main\n```\n\nSee [SECURITY.md](SECURITY.md) for the trust model and [CONTRIBUTING.md](CONTRIBUTING.md) for development guidance.\n\n> **The AI can forget your rules. Hallpass doesn't.**\n","readmeFilename":"README.md","author":{"url":"https://www.amrishkhan.dev","name":"Amrish Khan"}}