loki-guardrails 0.1.0__tar.gz

loki_guardrails-0.1.0/.gitignore

@@ -0,0 +1,24 @@
+.coverage
+.mutmut-cache/
+.pytest_cache/
+.venv/
+mutants/
+__pycache__/
+.ruff_cache/
+node_modules/
+
+# Local agent installations, session state, and working notes.
+/.agents/
+/.claude/
+/.completion-loop/
+/handoff.md
+/research.md
+/research-addendum.md
+/skills-lock.json
+/artifacts/tmp/
+
+# Local credentials.
+.env
+.env.*
+!.env.example
+dist/

loki_guardrails-0.1.0/LICENSE

@@ -0,0 +1,24 @@
+MIT License
+
+Copyright (c) 2026 Bryan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+The vendored anti-slop Oxlint plugin in vendor/anti-slop is MIT licensed by
+Dillon Mulroy; see vendor/anti-slop/LICENSE.

loki_guardrails-0.1.0/PKG-INFO

@@ -0,0 +1,237 @@
+Metadata-Version: 2.5
+Name: loki-guardrails
+Version: 0.1.0
+Summary: Deterministic guardrails for AI coding agents: blocks unsafe edits before they land
+Project-URL: Homepage, https://github.com/alfredosdpiii/loki
+Project-URL: Documentation, https://github.com/alfredosdpiii/loki/blob/main/docs/reference.md
+Project-URL: Issues, https://github.com/alfredosdpiii/loki/issues
+Author: Bryan
+License-Expression: MIT
+License-File: LICENSE
+License-File: vendor/anti-slop/LICENSE
+Keywords: ai-agents,claude-code,codex,guardrails,hooks,linting,static-analysis
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+# Loki
+
+**Deterministic guardrails for AI coding agents.**
+
+Loki checks every edit your agent makes with real analyzers and precise rules. It
+blocks the dangerous ones before the file changes, tells the agent exactly what
+to fix, and does all of this without calling a model.
+
+![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-3776ab?logo=python&logoColor=white)
+![Runtime dependencies: none](https://img.shields.io/badge/runtime%20dependencies-none-2ea44f)
+![Agents](https://img.shields.io/badge/agents-Claude%20Code%20%C2%B7%20Codex%20%C2%B7%20Factory%20%C2%B7%20Pi%20%C2%B7%20OMP-8a63d2)
+![Languages](https://img.shields.io/badge/languages-Python%20%C2%B7%20TS%2FJS%20%C2%B7%20Go%20%C2%B7%20Rust%20%C2%B7%20Elixir-e36209)
+
+<img src="https://raw.githubusercontent.com/alfredosdpiii/loki/main/docs/demo/demo.gif" alt="Loki blocking an XSS write, a leaked API key and a cross-file type error, then allowing the fix and flagging a complexity hotspot" width="820">
+
+<sub>Real hook output from <a href="https://github.com/alfredosdpiii/loki/blob/main/docs/demo/demo.sh">docs/demo/demo.sh</a>. Only the typing is simulated.</sub>
+
+</div>
+
+## Why Loki
+
+- **It stops problems before they land.** Content rules, Ruff and a full
+  TypeScript type check run on the proposed file before the write. XSS, leaked
+  keys and broken callers never reach disk.
+- **It only complains about what the edit changed.** Findings are compared
+  against the committed file by rule and source line. Existing debt and shifted
+  lines pass, so agents aren't blocked by code they didn't touch.
+- **It uses real analyzers.** mypy, `tsc`, golangci-lint, Clippy, Credo and
+  Sobelow run on every write, all net-new. Twenty-six tool-free rules cover
+  what linters miss: SSRF, open redirects, request-trusted authorization, shell
+  `-c` injection, ReDoS, zip slip, prototype pollution, GitHub Actions
+  injection and more.
+- **It's fast when it matters.** A per-repository daemon keeps the TypeScript
+  checker, `dmypy` and build caches warm. A TypeScript check takes about 40 ms
+  warm instead of 500 ms.
+- **It measures structural sloppiness too.** `loki.py slop` scores complexity,
+  duplication and import cycles in six languages and flags new hotspots as the
+  agent writes them.
+
+## How it compares
+
+Head to head with [Interlinked CLI](https://github.com/QuentinCody/interlinked-cli)
+(`82307ea`), both installed as Claude Code hooks. Each ran in a fresh sandboxed
+repository per case and repetition. A defect counts only if the right diagnostic
+appears on every repetition.
+
+| Suite | Loki caught | Interlinked caught | Loki prevented before write | Loki false blocks | Interlinked false blocks |
+| --- | ---: | ---: | ---: | ---: | ---: |
+| **Blind holdout** (60 unseen cases, before any tuning) | **33** | 12 | **19** | 3 | 2 |
+| Development corpus | **46/47** | 20/47 | **36** | **0** | 1 |
+| Missing project-local JS tools | **17/17** | 13/17 | **17** | **0** | 1 |
+| Holdout 1 (tuned) | **41/48** | 11/48 | **26** | **0** | 1 |
+| Holdout 2 (tuned) | **42/60** | 12/60 | **29** | **0** | 2 |
+
+Median hook latency is on par (402 ms vs 389 ms) with a much shorter tail
+(p95 1.6 s vs 6.4 s). Without project-local JS tools, Loki takes 334 ms against
+Interlinked's 10.8 s. Every holdout defect Interlinked catches, Loki catches too.
+
+These are synthetic cases, not production sessions. The blind holdout was written
+by an agent that could not see either product. Read the
+[full results](https://github.com/alfredosdpiii/loki/blob/main/artifacts/comprehensive-summary-2026-09-26.md) and the
+[benchmark protocol](https://github.com/alfredosdpiii/loki/blob/main/benchmarks/README.md).
+
+## Quick start
+
+Loki needs Python 3.11 or newer and has no runtime dependencies. Install the
+`loki` command, then point it at a Git repository:
+
+```bash
+uv tool install loki-guardrails     # or: pipx install loki-guardrails
+loki init --dir /path/to/your/repo
+```
+
+To try it without installing anything, run `uvx --from loki-guardrails loki init --dir .`.
+You can also clone this repository and run `python3 loki.py init --dir /path/to/repo`.
+
+That installs Loki into `.loki/`, registers hooks for every supported agent, and
+adds starter configuration for Ruff, Oxlint, golangci-lint and a GitHub Actions
+check. Existing configuration is merged or left alone.
+
+Then, inside the repository:
+
+```bash
+loki scan                                # check the working tree
+loki scan --strict --base origin/main    # CI: missing tools fail
+loki slop                                # structural sloppiness report
+```
+
+The installed hooks don't use the global `loki` command. `init` copies the
+engine into `.loki/loki.py`, so every repository runs the exact version its
+policy was reviewed against. CI runs the same file, and upgrades happen only
+through `loki init --force` and a reviewed commit. `loki --version` and
+`python3 .loki/loki.py --version` show which version each one is.
+
+Codex needs a one-time `/hooks` approval and Pi a trust prompt. The
+[install guide](https://github.com/alfredosdpiii/loki/blob/main/docs/reference.md#install) covers each host.
+
+## How it works
+
+```mermaid
+flowchart LR
+    A[Agent proposes a write] --> B{Pre-write}
+    B -->|path, policy, secrets,<br/>security rules, Ruff,<br/>TypeScript types| C[Deny with the exact finding]
+    B -->|clean| D[File is written]
+    D --> E{Post-write}
+    E -->|mypy, golangci-lint, Clippy,<br/>Credo, Sobelow, Oxlint| F[Report net-new findings]
+    E --> G[Advisory: new hotspots,<br/>clones, import cycles]
+    H[(Warm daemon)] -. keeps analyzers warm .-> B
+    H -.-> E
+```
+
+1. **Before the write,** Loki reconstructs the file the agent is about to
+   produce. It checks the path against protected policy, runs the tool-free
+   content rules, and, where supported, runs Ruff and a TypeScript type check on
+   the proposed content. A denial carries the precise diagnostic.
+2. **After the write,** the language's analyzers run on what actually landed.
+   New findings go back to the agent, while existing debt stays quiet.
+3. **In CI,** `scan` repeats the checks against a base revision, including test
+   integrity, dependency policy and lockfile consistency.
+
+Loki blocks its own policy files, hook registration and CI workflow from agent
+edits, so an agent can't switch it off.
+
+## What it catches
+
+| Language | On every write | Tool-free rules |
+| --- | --- | --- |
+| **Python** | Net-new Ruff and mypy (annotated code), import and AST checks | request-trusted authorization, SSRF, path traversal, shell `-c`, timing-unsafe compares, ReDoS, tautological tests |
+| **TypeScript / JS** | Oxlint, project type check (pre-write), floating promises, numeric `.sort()` | XSS sinks, open redirects, `eval`, command and SQL injection, SSRF, prototype pollution, `postMessage` origin, timer leaks, ReDoS, disabled TLS |
+| **Go** | gofmt, go vet, golangci-lint with gosec on changed lines | zip slip |
+| **Rust** | rustfmt, net-new Clippy and compiler errors | placeholders, unchecked `get_unchecked`, unflushed `BufWriter`, shell `-c` |
+| **Elixir / Phoenix** | mix format, net-new Credo and Sobelow | request-trusted authorization, SSRF, open redirects, structural `DateTime` sorts, unhandled `File` results, leaked handles |
+| **Any file** | protected paths, root confinement | hardcoded credentials, merge-conflict markers, GitHub Actions script injection |
+
+Missing analyzers are reported as `NOT CHECKED`, never as clean, and
+`LOKI_STRICT=1` turns them into failures. The [reference](https://github.com/alfredosdpiii/loki/blob/main/docs/reference.md)
+documents every rule, threshold and limitation.
+
+## Structural sloppiness
+
+`loki.py slop` puts a single number on how hard code is to change. It combines
+the erosion metric from
+[Measuring code sloppiness](https://earendil.com/posts/measuring-code-sloppiness/)
+with [trellis](https://github.com/jayminwest/trellis)'s scoring:
+
+```text
+$ python3 .loki/loki.py slop
+Sloppiness index: 26/100 (lower is better; trellis 0.2.0-provisional weights)
+  complexity-erosion  26.2  eroded share 0.94, 1 of 4 functions with CC > 10
+  duplication          0.0  density 0.00, 0 clone groups
+  import-cycle         0.0  density 0.00, 0 cycles
+hotspot src/discounts.ts:1 discount CC 17, 15 SLOC, mass 65.8
+```
+
+Complexity is exact for Python, TypeScript/JavaScript, Go and Elixir using each
+language's own parser. It is approximated structurally for Rust, Java, Kotlin, C#,
+C/C++, Swift, Scala, PHP and Ruby. Clones are detected on normalized tokens, so
+renamed copies count. `--base` compares against a revision, and `max_index` or
+`max_index_increase` can gate CI.
+
+## Configuration
+
+Policy lives in `.loki/loki.json` and is always read from the committed base, so
+an agent can't loosen it mid-session:
+
+```json
+{
+  "rule_packs": ["core", "python", "typescript", "phoenix", "shell"],
+  "shell_commands": [
+    {"command": "npm test", "cwd": ".", "inputs": ["package.json", "package-lock.json"]}
+  ],
+  "slop": {"max_index": 40, "max_index_increase": 2, "block": false},
+  "elixir_security": {"sobelow": {"block": "high", "warn": "medium"}}
+}
+```
+
+| Setting | Default | Effect |
+| --- | --- | --- |
+| `typescript_check` | on when `tsconfig.json` exists | `false` disables it; `true` makes setup problems block |
+| `slop.block` | `false` | Turns new hotspots, clones and cycles from advice into failures |
+| `shell_commands` | none | Exact, reviewed shell commands the shell guard admits |
+| `LOKI_STRICT=1` | off | Missing analyzers fail instead of reporting `NOT CHECKED` |
+| `LOKI_DAEMON=0` | on | Runs every hook in-process |
+
+## Supported agents
+
+| Agent | Integration |
+| --- | --- |
+| Claude Code | `.claude/settings.json` hooks |
+| Codex | `.codex/hooks.json` hooks |
+| Factory Droid | `.factory/hooks.json` hooks |
+| Pi | `.pi/extensions/loki.ts` |
+| OMP | `.omp/extensions/loki.ts` |
+
+## Documentation
+
+- [Reference](https://github.com/alfredosdpiii/loki/blob/main/docs/reference.md): every check, rule, threshold and limitation
+- [Benchmark protocol](https://github.com/alfredosdpiii/loki/blob/main/benchmarks/README.md) and the
+  [latest results](https://github.com/alfredosdpiii/loki/blob/main/artifacts/comprehensive-summary-2026-09-26.md)
+- [Blind holdout cases](https://github.com/alfredosdpiii/loki/blob/main/benchmarks/holdout2_cases.json) and the
+  [runner](https://github.com/alfredosdpiii/loki/blob/main/benchmarks/holdout.py)
+
+## Development
+
+```bash
+uv run --frozen pytest -q
+bun test ./tests/loki-shim.test.ts ./tests/loki-omp.test.ts
+ruff check --config templates/.ruff.toml loki.py tests benchmarks
+```
+
+Regenerate the demo with `asciinema rec -c "bash docs/demo/demo.sh" docs/demo/demo.cast`
+followed by `agg docs/demo/demo.cast docs/demo/demo.gif`.

loki_guardrails-0.1.0/README.md

@@ -0,0 +1,214 @@
+<div align="center">
+
+# Loki
+
+**Deterministic guardrails for AI coding agents.**
+
+Loki checks every edit your agent makes with real analyzers and precise rules. It
+blocks the dangerous ones before the file changes, tells the agent exactly what
+to fix, and does all of this without calling a model.
+
+![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-3776ab?logo=python&logoColor=white)
+![Runtime dependencies: none](https://img.shields.io/badge/runtime%20dependencies-none-2ea44f)
+![Agents](https://img.shields.io/badge/agents-Claude%20Code%20%C2%B7%20Codex%20%C2%B7%20Factory%20%C2%B7%20Pi%20%C2%B7%20OMP-8a63d2)
+![Languages](https://img.shields.io/badge/languages-Python%20%C2%B7%20TS%2FJS%20%C2%B7%20Go%20%C2%B7%20Rust%20%C2%B7%20Elixir-e36209)
+
+<img src="https://raw.githubusercontent.com/alfredosdpiii/loki/main/docs/demo/demo.gif" alt="Loki blocking an XSS write, a leaked API key and a cross-file type error, then allowing the fix and flagging a complexity hotspot" width="820">
+
+<sub>Real hook output from <a href="https://github.com/alfredosdpiii/loki/blob/main/docs/demo/demo.sh">docs/demo/demo.sh</a>. Only the typing is simulated.</sub>
+
+</div>
+
+## Why Loki
+
+- **It stops problems before they land.** Content rules, Ruff and a full
+  TypeScript type check run on the proposed file before the write. XSS, leaked
+  keys and broken callers never reach disk.
+- **It only complains about what the edit changed.** Findings are compared
+  against the committed file by rule and source line. Existing debt and shifted
+  lines pass, so agents aren't blocked by code they didn't touch.
+- **It uses real analyzers.** mypy, `tsc`, golangci-lint, Clippy, Credo and
+  Sobelow run on every write, all net-new. Twenty-six tool-free rules cover
+  what linters miss: SSRF, open redirects, request-trusted authorization, shell
+  `-c` injection, ReDoS, zip slip, prototype pollution, GitHub Actions
+  injection and more.
+- **It's fast when it matters.** A per-repository daemon keeps the TypeScript
+  checker, `dmypy` and build caches warm. A TypeScript check takes about 40 ms
+  warm instead of 500 ms.
+- **It measures structural sloppiness too.** `loki.py slop` scores complexity,
+  duplication and import cycles in six languages and flags new hotspots as the
+  agent writes them.
+
+## How it compares
+
+Head to head with [Interlinked CLI](https://github.com/QuentinCody/interlinked-cli)
+(`82307ea`), both installed as Claude Code hooks. Each ran in a fresh sandboxed
+repository per case and repetition. A defect counts only if the right diagnostic
+appears on every repetition.
+
+| Suite | Loki caught | Interlinked caught | Loki prevented before write | Loki false blocks | Interlinked false blocks |
+| --- | ---: | ---: | ---: | ---: | ---: |
+| **Blind holdout** (60 unseen cases, before any tuning) | **33** | 12 | **19** | 3 | 2 |
+| Development corpus | **46/47** | 20/47 | **36** | **0** | 1 |
+| Missing project-local JS tools | **17/17** | 13/17 | **17** | **0** | 1 |
+| Holdout 1 (tuned) | **41/48** | 11/48 | **26** | **0** | 1 |
+| Holdout 2 (tuned) | **42/60** | 12/60 | **29** | **0** | 2 |
+
+Median hook latency is on par (402 ms vs 389 ms) with a much shorter tail
+(p95 1.6 s vs 6.4 s). Without project-local JS tools, Loki takes 334 ms against
+Interlinked's 10.8 s. Every holdout defect Interlinked catches, Loki catches too.
+
+These are synthetic cases, not production sessions. The blind holdout was written
+by an agent that could not see either product. Read the
+[full results](https://github.com/alfredosdpiii/loki/blob/main/artifacts/comprehensive-summary-2026-09-26.md) and the
+[benchmark protocol](https://github.com/alfredosdpiii/loki/blob/main/benchmarks/README.md).
+
+## Quick start
+
+Loki needs Python 3.11 or newer and has no runtime dependencies. Install the
+`loki` command, then point it at a Git repository:
+
+```bash
+uv tool install loki-guardrails     # or: pipx install loki-guardrails
+loki init --dir /path/to/your/repo
+```
+
+To try it without installing anything, run `uvx --from loki-guardrails loki init --dir .`.
+You can also clone this repository and run `python3 loki.py init --dir /path/to/repo`.
+
+That installs Loki into `.loki/`, registers hooks for every supported agent, and
+adds starter configuration for Ruff, Oxlint, golangci-lint and a GitHub Actions
+check. Existing configuration is merged or left alone.
+
+Then, inside the repository:
+
+```bash
+loki scan                                # check the working tree
+loki scan --strict --base origin/main    # CI: missing tools fail
+loki slop                                # structural sloppiness report
+```
+
+The installed hooks don't use the global `loki` command. `init` copies the
+engine into `.loki/loki.py`, so every repository runs the exact version its
+policy was reviewed against. CI runs the same file, and upgrades happen only
+through `loki init --force` and a reviewed commit. `loki --version` and
+`python3 .loki/loki.py --version` show which version each one is.
+
+Codex needs a one-time `/hooks` approval and Pi a trust prompt. The
+[install guide](https://github.com/alfredosdpiii/loki/blob/main/docs/reference.md#install) covers each host.
+
+## How it works
+
+```mermaid
+flowchart LR
+    A[Agent proposes a write] --> B{Pre-write}
+    B -->|path, policy, secrets,<br/>security rules, Ruff,<br/>TypeScript types| C[Deny with the exact finding]
+    B -->|clean| D[File is written]
+    D --> E{Post-write}
+    E -->|mypy, golangci-lint, Clippy,<br/>Credo, Sobelow, Oxlint| F[Report net-new findings]
+    E --> G[Advisory: new hotspots,<br/>clones, import cycles]
+    H[(Warm daemon)] -. keeps analyzers warm .-> B
+    H -.-> E
+```
+
+1. **Before the write,** Loki reconstructs the file the agent is about to
+   produce. It checks the path against protected policy, runs the tool-free
+   content rules, and, where supported, runs Ruff and a TypeScript type check on
+   the proposed content. A denial carries the precise diagnostic.
+2. **After the write,** the language's analyzers run on what actually landed.
+   New findings go back to the agent, while existing debt stays quiet.
+3. **In CI,** `scan` repeats the checks against a base revision, including test
+   integrity, dependency policy and lockfile consistency.
+
+Loki blocks its own policy files, hook registration and CI workflow from agent
+edits, so an agent can't switch it off.
+
+## What it catches
+
+| Language | On every write | Tool-free rules |
+| --- | --- | --- |
+| **Python** | Net-new Ruff and mypy (annotated code), import and AST checks | request-trusted authorization, SSRF, path traversal, shell `-c`, timing-unsafe compares, ReDoS, tautological tests |
+| **TypeScript / JS** | Oxlint, project type check (pre-write), floating promises, numeric `.sort()` | XSS sinks, open redirects, `eval`, command and SQL injection, SSRF, prototype pollution, `postMessage` origin, timer leaks, ReDoS, disabled TLS |
+| **Go** | gofmt, go vet, golangci-lint with gosec on changed lines | zip slip |
+| **Rust** | rustfmt, net-new Clippy and compiler errors | placeholders, unchecked `get_unchecked`, unflushed `BufWriter`, shell `-c` |
+| **Elixir / Phoenix** | mix format, net-new Credo and Sobelow | request-trusted authorization, SSRF, open redirects, structural `DateTime` sorts, unhandled `File` results, leaked handles |
+| **Any file** | protected paths, root confinement | hardcoded credentials, merge-conflict markers, GitHub Actions script injection |
+
+Missing analyzers are reported as `NOT CHECKED`, never as clean, and
+`LOKI_STRICT=1` turns them into failures. The [reference](https://github.com/alfredosdpiii/loki/blob/main/docs/reference.md)
+documents every rule, threshold and limitation.
+
+## Structural sloppiness
+
+`loki.py slop` puts a single number on how hard code is to change. It combines
+the erosion metric from
+[Measuring code sloppiness](https://earendil.com/posts/measuring-code-sloppiness/)
+with [trellis](https://github.com/jayminwest/trellis)'s scoring:
+
+```text
+$ python3 .loki/loki.py slop
+Sloppiness index: 26/100 (lower is better; trellis 0.2.0-provisional weights)
+  complexity-erosion  26.2  eroded share 0.94, 1 of 4 functions with CC > 10
+  duplication          0.0  density 0.00, 0 clone groups
+  import-cycle         0.0  density 0.00, 0 cycles
+hotspot src/discounts.ts:1 discount CC 17, 15 SLOC, mass 65.8
+```
+
+Complexity is exact for Python, TypeScript/JavaScript, Go and Elixir using each
+language's own parser. It is approximated structurally for Rust, Java, Kotlin, C#,
+C/C++, Swift, Scala, PHP and Ruby. Clones are detected on normalized tokens, so
+renamed copies count. `--base` compares against a revision, and `max_index` or
+`max_index_increase` can gate CI.
+
+## Configuration
+
+Policy lives in `.loki/loki.json` and is always read from the committed base, so
+an agent can't loosen it mid-session:
+
+```json
+{
+  "rule_packs": ["core", "python", "typescript", "phoenix", "shell"],
+  "shell_commands": [
+    {"command": "npm test", "cwd": ".", "inputs": ["package.json", "package-lock.json"]}
+  ],
+  "slop": {"max_index": 40, "max_index_increase": 2, "block": false},
+  "elixir_security": {"sobelow": {"block": "high", "warn": "medium"}}
+}
+```
+
+| Setting | Default | Effect |
+| --- | --- | --- |
+| `typescript_check` | on when `tsconfig.json` exists | `false` disables it; `true` makes setup problems block |
+| `slop.block` | `false` | Turns new hotspots, clones and cycles from advice into failures |
+| `shell_commands` | none | Exact, reviewed shell commands the shell guard admits |
+| `LOKI_STRICT=1` | off | Missing analyzers fail instead of reporting `NOT CHECKED` |
+| `LOKI_DAEMON=0` | on | Runs every hook in-process |
+
+## Supported agents
+
+| Agent | Integration |
+| --- | --- |
+| Claude Code | `.claude/settings.json` hooks |
+| Codex | `.codex/hooks.json` hooks |
+| Factory Droid | `.factory/hooks.json` hooks |
+| Pi | `.pi/extensions/loki.ts` |
+| OMP | `.omp/extensions/loki.ts` |
+
+## Documentation
+
+- [Reference](https://github.com/alfredosdpiii/loki/blob/main/docs/reference.md): every check, rule, threshold and limitation
+- [Benchmark protocol](https://github.com/alfredosdpiii/loki/blob/main/benchmarks/README.md) and the
+  [latest results](https://github.com/alfredosdpiii/loki/blob/main/artifacts/comprehensive-summary-2026-09-26.md)
+- [Blind holdout cases](https://github.com/alfredosdpiii/loki/blob/main/benchmarks/holdout2_cases.json) and the
+  [runner](https://github.com/alfredosdpiii/loki/blob/main/benchmarks/holdout.py)
+
+## Development
+
+```bash
+uv run --frozen pytest -q
+bun test ./tests/loki-shim.test.ts ./tests/loki-omp.test.ts
+ruff check --config templates/.ruff.toml loki.py tests benchmarks
+```
+
+Regenerate the demo with `asciinema rec -c "bash docs/demo/demo.sh" docs/demo/demo.cast`
+followed by `agg docs/demo/demo.cast docs/demo/demo.gif`.

loki_guardrails-0.1.0/benchmarks/README.md

@@ -0,0 +1,161 @@
+# Benchmark protocol
+
+The earlier pre-write comparison does not establish an overall winner. It leaves
+out checks that run after edits, whole-project analysis, and ordinary repair work.
+
+`comprehensive.py` invokes the installed Claude command hooks for both products.
+It writes an admitted source edit into a disposable repository, then invokes the
+installed post-write handlers. It never executes proposed shell commands or
+application code. Explicit audit commands may compile the controlled fixtures.
+
+## Cases and scoring
+
+`corpus.py` contains paired defects and controls, exact replacements, cross-file
+contract changes, existing-debt shifts, break/repair sequences, protected-path
+attempts, and 10/1,000/10,000-file workloads. Languages are Python, TypeScript,
+JavaScript, Go, Rust, and Elixir/Phoenix.
+
+The corpus deliberately includes semantic security cases that neither product may
+recognize. SSRF and request-controlled authorization stay in the denominator.
+Cases reflect the author's knowledge of both products. They are synthetic, not an
+independent holdout or a representative sample of production changes.
+
+Before running, the runner saves the complete case list, its hash, the randomized
+schedule, tool versions, command line, and source hashes. Each result uses an
+exclusive file creation. Existing evidence cannot be replaced by another run.
+Source identity is checked again when the run finishes.
+
+The scorecard distinguishes:
+
+- **Prevention:** a pre-hook denies the operation and emits a matching diagnostic.
+- **Post-write detection:** a matching diagnostic reaches the host after source
+  bytes land. This is not prevention, rollback, or an OS security boundary.
+- **Unrelated blocking:** denial without evidence of the intended defect.
+- **False blocking:** a control is blocked in any repetition, before or after writing.
+- **Unavailable checks:** reported separately, even if the overall hook admits the edit.
+- **Infrastructure failure:** remains in the denominator and earns no detection credit.
+
+An accuracy result needs the same successful detection on every repetition.
+Three repetitions are three timing/stability samples, not three independent cases.
+Exit-zero native JSON denials count as denials. Exit-zero stderr alone does not
+count as feedback delivered to Claude. Audit scoring examines actual diagnostic
+entries, not the names of checks that reported zero findings.
+
+The scorecard also decodes JSON feedback before matching individual diagnostic
+lines. Otherwise a regex can span escaped `\n` sequences and mistake unrelated
+advice for a compiler finding. Node module-format notices do not count as syntax
+detection. Raw records retain provisional outcomes; the scorecard lists every
+correction and hashes the final scorer.
+
+Control feedback includes missing-tool notices and advisory messages. It is not
+automatically a false positive. The report preserves the raw output for review.
+Cold and startup-warmed timings are separate. Each repetition gets a fresh
+repository, home, and daemon, avoiding leaked reservations and diagnostic caches.
+The first trial has no warmup. Later trials send two git-status pre-hook envelopes
+before the case, without executing the commands. That warms startup, not compiler
+result caches. "Cold" does not mean flushed OS caches. Latency includes process
+and sandbox startup.
+
+## Isolation and tool parity
+
+Each product/case/profile gets a new repository and home. Bubblewrap denies
+network access, mounts the host filesystem read-only, and allows writes only to
+the fixture tree and private temporary storage. There is no unsandboxed fallback.
+The runner starts only known local binaries and uses an environment allowlist.
+It uses the user's existing Git identity for fixture commits.
+
+Repositories live under the ignored `artifacts/tmp/b/` directory by default,
+outside OS temporary roots. Interlinked applies a distinct scratchpad policy to
+paths under `/tmp`; measuring that policy would not represent ordinary repository
+edits. `--work-dir` overrides the fixture parent. Keep its path short enough for
+Unix domain sockets.
+
+Both products receive the same analyzer paths. The shared profile supplies
+TypeScript, Oxlint, Biome with its recommended lint config, Ruff, mypy,
+golangci-lint, Go, Rust, and prepared Phoenix dependencies. This does not mean
+both products invoke every available analyzer.
+
+Loki's shell guard and a committed exact `npm test` permission are enabled.
+Interlinked uses its balanced project installation. Other Loki settings remain
+at their shipped values, including its disabled-by-default project type checker.
+`configured.py` repeats the TypeScript cases with `"typescript_check": true`.
+Keep that result separate from the ordinary installation.
+
+The `missing-js` profile omits project-local JS analyzer links. It does not remove
+system-wide tools or the competitor's own packaged dependencies. It measures that
+specific degradation, not a completely tool-free machine.
+
+Go/Rust audit results use `loki scan --base HEAD` and `interlinked verify --json`.
+These have different product-defined scopes. Their findings are never added to
+the ordinary-hook detection total.
+
+The shared-scaffolding matrix places a JS package manifest in every fixture to
+support its shell-grant controls. That can affect project discovery in non-JS
+repositories. `native_projects.py` is a separate sensitivity run: Python gets
+`pyproject.toml` with Ruff and mypy sections, and Go/Rust/Phoenix retain only their
+native manifests. It omits the irrelevant npm grant for those fixtures. Do not
+pool its observations with the shared-scaffolding results.
+
+## Reproduce
+
+Prepare the toolchains first, outside the network-isolated run. The competitor
+checkout must be clean at `207330d8131c5203ecc74e9fd4c24ba416463718`, with its
+`dist/` build present. The Phoenix project must use
+`fixtures/phoenix/mix.exs` and `mix.lock`, with dependencies compiled under
+Elixir 1.17.3 and a compatible OTP 27 installation. Provide a compatible Hex
+archive as well. No global toolchain setting needs to change.
+
+Run from the Loki checkout, substituting absolute paths:
+
+```sh
+ERL_FLAGS='+S 4:4' /usr/bin/python3 benchmarks/comprehensive.py \
+  --interlinked /path/to/interlinked \
+  --node /path/to/node-23/bin/node \
+  --oxlint /path/to/oxlint-tools/node_modules/.bin/oxlint \
+  --typescript /path/to/typescript-tools/node_modules/typescript \
+  --biome /path/to/biome-tools/node_modules/.bin/biome \
+  --python-tools /path/to/mypy-venv/bin \
+  --golangci /path/to/golangci-lint \
+  --phoenix /path/to/prepared-phoenix \
+  --hex-archive /path/to/hex-archive \
+  --erlang-bin /path/to/otp-27/bin \
+  --runs 3 --seed 20260921 --profiles shared missing-js --scan \
+  --output /path/to/new-evidence-directory
+
+python3 -m benchmarks.report_comprehensive /path/to/new-evidence-directory
+```
+
+Use an actual Python executable, rather than a toolchain shim that might rewrite
+`PATH` during startup. The explicit `--erlang-bin` also prevents that environment
+problem inside fixtures.
+
+For the type-check-enabled run, replace `comprehensive.py` with `configured.py`,
+use `--profiles shared --case typescript`, and choose a new output directory.
+That entry point changes only accepted fixture policy, not either product's code.
+Its own hash is included in the evidence identity.
+
+For native project discovery, use `native_projects.py --profiles shared` and
+`--case '(^python/|^go/|^rust/|^elixir/|/python/)'`, with the same tool arguments
+and a new output directory. This tests configuration sensitivity without changing
+either product or the defect/control source.
+
+## Separate integration and regression suites
+
+- `host_context.py`: real installed hosts with fresh homes and a loopback model
+  stub, with hooks enabled and disabled. This proves startup discovery/context
+  delivery, not live-model tool enforcement.
+- `phoenix.py`: installed ordinary hooks plus project-tier compilation and HEEx
+  checks under multiple Sobelow confidence thresholds.
+- `language_rules.py`: targeted analyzer defect/repair regressions. These were
+  developed with Loki's policies and are not independent comparison cases.
+- `tests/loki-shim.test.ts` and `tests/loki-omp.test.ts`: actual checker subprocesses
+  through adapter callbacks, not running host inference sessions.
+
+The smoke-run directories preserve setup failures. They are not merged into the
+final comparison. Do not silently discard failures from a completed final run or
+change cases and then reuse its manifest.
+
+This protocol still does not measure long-running autonomous sessions, production
+incident prevention, online dependency checks, all supported host write formats,
+or unknown attacks. Those require separate experiments and explicit authorization
+before using private repositories or paid model endpoints.