aigate-lite 0.5.0__tar.gz

aigate_lite-0.5.0/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Hitarth Khatiwala
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

aigate_lite-0.5.0/NOTICE

@@ -0,0 +1,5 @@
+aigate-lite
+Copyright 2026 Hitarth Khatiwala
+
+This product includes software developed by Hitarth Khatiwala
+(https://github.com/hitarth1812/AI-Gate).

aigate_lite-0.5.0/PKG-INFO

@@ -0,0 +1,371 @@
+Metadata-Version: 2.4
+Name: aigate-lite
+Version: 0.5.0
+Summary: Free, local commit-time gate that checks AI-written code before it is committed or pushed
+Author-email: Hitarth Khatiwala <hitarthkhatiwala@gmail.com>
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/hitarth1812/AI-Gate
+Project-URL: Repository, https://github.com/hitarth1812/AI-Gate
+Keywords: git-hooks,pre-commit,ai,code-review,security,supply-chain
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Dynamic: license-file
+
+# aigate-lite
+
+A free, local "CI gate" that runs when you commit. It checks only what the commit adds, looking for
+the mistakes AI coding tools make most often, and stops the commit if it finds a serious one.
+
+- **Cost:** none. One Python file, standard library only. No account, server, API key or LLM.
+- **Network:** only free public lookups (PyPI, npm, OSV), cached on disk. `--offline` skips them.
+- **Speed:** measured, not estimated: see [docs/PERF.md](docs/PERF.md) (generated by `bench/bench.py`).
+- **Needs:** Python 3.11+ and git.
+- **Tested on:** by hand (the full test suite) on Windows 11 and on Ubuntu under WSL2, each with Python 3.11, 3.12, 3.13
+  and 3.14. macOS is covered only by CI (`.github/workflows/ci.yml`: Ubuntu, macOS and Windows on 3.11-3.14, on every push to
+  main and every pull request; the results are in the repository's Actions tab). The runs done by hand are listed in
+  [PROGRESS.md](PROGRESS.md).
+
+It is the lightweight, local version of the AI Code Trust Gate plan. It uses the same rule names,
+actions and risk score.
+
+## Install
+
+After the first release (not published to PyPI yet: until then use the file itself, as in the next section):
+
+```bash
+pip install aigate-lite          # adds the commands `aigate-lite` and `aigate`
+pipx install aigate-lite         # the same, in its own environment (recommended for a command-line tool)
+uvx aigate-lite review           # run once without installing
+```
+
+Maintainers: how a release is published (PyPI Trusted Publishing, no token) is in [docs/RELEASING.md](docs/RELEASING.md).
+
+## First success in a few commands
+
+```bash
+cd your-project                                    # any git repo; needs Python 3.11+ and git
+python3 /path/to/aigate_lite.py setup              # hooks + a copy of the gate in .aigate/ + a starter config
+python3 .aigate/aigate_lite.py audit               # see what is already in the repo
+python3 -c "print('KEY = \"AKIA' + 'QWERTYUIOPASDFGH\"')" > leak.py  # a fake key, to see a block
+git add leak.py && git commit -m "try it"          # stopped: secrets.hardcoded
+git rm --cached -q leak.py && rm leak.py           # clean up
+```
+
+`setup` is `install` plus `init`; it never overwrites an existing `.aigate/lite.toml`. Run from a loose `aigate_lite.py` (as
+above) it vendors the gate into `.aigate/`, because a loose file cannot be found again by name; run from an installed package
+(`pipx install aigate-lite`) the hooks run the installed tool instead (`--mode installed|vendored` chooses explicitly). A
+repository that already has `.aigate/aigate_lite.py` stays vendored. `audit` is `check --all`.
+After `pip install .` the command is also available as `aigate` (same as `aigate-lite`).
+
+On Windows use `py -3` instead of `python3`; the installed hooks use the interpreter that ran `install` (pinned in `.git/hooks`, never committed) and, if
+that is gone, look for `python3`, `python`, `python3.14`..`python3.11`, `py -3.14`..`py -3.11`, then `py -3`.
+
+## Quick start
+
+```bash
+# inside your project
+python3 /path/to/aigate_lite.py setup              # copies itself to .aigate/, adds both hooks, writes lite.toml
+python3 .aigate/aigate_lite.py audit               # see what is already in the repo
+python3 .aigate/aigate_lite.py baseline            # optional: accept today's findings so only new ones block
+git add .aigate && git commit -m "add aigate-lite"
+```
+
+**Manual setup** (what `setup` does, step by step):
+
+```bash
+python3 /path/to/aigate_lite.py install --vendor   # copies itself to .aigate/ and adds both hooks
+python3 .aigate/aigate_lite.py init                # optional: starter .aigate/lite.toml
+git add .aigate && git commit -m "add aigate-lite"
+```
+
+From then on:
+
+| When | What runs | Checks |
+|---|---|---|
+| `git commit` | `pre-commit` hook | The staged changes |
+| `git push` | `pre-push` hook | Every commit being pushed, one by one for secrets. This catches commits made with `--no-verify`. |
+| Any time | `aigate-lite check` | Staged changes, or `--range origin/main..HEAD` |
+| Audit | `aigate-lite audit` (same as `check --all`) | Every tracked file in HEAD, including the root commit (not used by hooks) |
+
+`--vendor` makes the hooks portable: they run `.aigate/aigate_lite.py` with whatever `python3` is on
+the PATH, so teammates only need to run `python3 .aigate/aigate_lite.py install --vendor`.
+Without `--vendor`, the hooks point at the script's current location.
+
+**Existing hooks.** If you already use husky or the pre-commit framework, `install` prints the line or
+YAML snippet to add instead. `--force` installs anyway; your old hook is kept as `<hook>.local` and
+still runs first.
+
+## What it catches
+
+**Actions:** `block` and `fix` stop the commit; `warn` only reports.
+
+| Mistake | Rules (default action) |
+|---|---|
+| Exposed secrets | `secrets.hardcoded`: provider keys and private keys (block). `secrets.env_file`: `.env`, key and credential files (block). `secrets.generic`: credential-like literals and JWTs (fix). `secrets.env_not_ignored` (warn). |
+| Hallucinated or risky packages | `deps.hallucinated`: package or version not on PyPI/npm, in a manifest or an import (block). `deps.untrusted_source`: git/URL deps, custom indexes, odd lockfile URLs (block). `deps.new_package`: first release under 30 days (fix). `deps.version_cooldown`: version under 5 days (fix), with security bumps exempt. `deps.vulnerable`: OSV advisories for the pinned version (fix). `deps.undeclared` (fix). `deps.removed_stdlib`, e.g. `distutils` or `cgi` (fix). `deps.typosquat`, `deps.outdated` and `deps.deprecated` (warn). |
+| Weakened tests | Assertions or cases removed, skip/xfail added, tests deleted (renames are detected), `.only` focus, trivial asserts, test-config narrowing (all fix). `sitecustomize.py`, `.pth` files and `pytest11` entry points (block). Result-changing pytest hooks (fix). Expected values changed alongside source (warn). |
+| Placeholder or unsafe code | `... rest of the code` comments, `...` bodies, swallowed exceptions, debugger leftovers, syntax errors (fix). `eval`/`exec`, `shell=True`, pickle and unsafe YAML, SQL built with f-strings, `verify=False` (fix). Debug mode, wildcard CORS, weak crypto, raw HTML (warn). |
+| Silenced checkers | `# nosec`, `# type: ignore`, `@ts-ignore`, `# pragma: no cover`, whole-file disables (fix). `# noqa`, `eslint-disable-line` (warn). In `[paths] sensitive` these are one step stricter. |
+| Bloat and time complexity | Long or complex functions, long files, big diffs, duplicated blocks, unused imports (warn). Loops nested 3 or more deep, nested loops over the same list, `x in list` / `.pop(0)` / sorting inside loops, network or DB calls inside loops, branching recursion without a cache (warn). |
+| Scope creep | `scope.forbidden_path` (block). `scope.out_of_scope` against a declared task scope (fix). `gate.config_changed` (warn). |
+
+`aigate-lite explain` lists all 75 rules. `aigate-lite explain <rule>` shows how to change or allow one.
+
+**Language coverage.** Python gets every check, using its AST. Go and JavaScript/TypeScript are read with a lexer
+(strings and comments are never mistaken for code) and get secrets, dependencies, tests, suppressions,
+placeholders, function length, complexity and loop nesting (estimated from brace structure, not parsed), duplicated
+blocks, and the reviewer rules below (each rule says which languages it covers). Unused imports and the
+quadratic-pattern, call-in-loop and exponential-recursion checks are Python-only. Other languages get secrets,
+placeholders, TODOs and suppressions.
+
+**Size and copy-paste advice is off for people by default.** `size.*` (long functions and files, complexity, big
+diffs), `perf.*` (loop findings) and `code.duplicate_block` are the "core" exception: they are not reported for a
+person's change unless you name them in `[rules]` (`"size.*" = "warn"`) or use `preset = "strict"`. AI agents always get
+them, and so does `aigate-lite audit --strict` (or `check --strict`). On a large existing repository these rules were
+most of what `audit` reported, which is why they are off.
+
+### Declaring a task scope (scope creep)
+
+```bash
+aigate-lite scope set 'src/auth/**' 'tests/auth/**'   # before you start the AI on a task
+aigate-lite scope show
+aigate-lite scope clear                                # when the task is done
+```
+
+The scope is stored inside `.git/`, so it is per-clone and never committed.
+
+## AI agents
+
+When an AI agent runs `git commit` itself, the gate notices it and becomes stricter. It detects agents
+through `CLAUDECODE`, `AI_AGENT`, `GEMINI_CLI` or `AIGATE_AGENT` in the environment, an `(aider)`
+author name, or AI co-author trailers in pushed commits. You can add your own variables under
+`[provenance] agent_env`. For agent commits:
+
+- `forbidden_for_agents` paths are blocked: `.aigate/`, CI workflows and hook configs.
+- The config is read from the last commit, so an agent cannot loosen the gate in the same commit.
+- `AIGATE_ALLOW` and `AIGATE_SKIP` are ignored.
+
+Detection is best effort. An agent that runs with none of these signals looks like a human.
+
+### Using with AI coding agents
+
+`--format agent` prints a short, ASCII-only, stable report an agent can act on line by line:
+
+    AIGATE verdict=fix risk=30 exit=1
+    FIX security.eval app/a.py:7 eval() runs code built at runtime | fix: Avoid eval/exec; parse the input explicitly (ast.literal_eval, JSON.parse).
+    TOOL aigate-lite 0.5.0 https://github.com/hitarth1812/AI-Gate
+    END
+
+At most 50 block/fix lines and 20 warn lines are listed; a `MORE <n>` line says how many were left out.
+The first line and `END` are the contract; `TOOL` (which tool wrote the report) always sits directly before `END`
+and a reader may ignore it.
+Add instructions like these to your agent's instruction file (`CLAUDE.md`, a `.cursor/rules` file,
+`.github/copilot-instructions.md`, …):
+
+```text
+Before every commit, run: python3 .aigate/aigate_lite.py check --format agent
+Fix every BLOCK and FIX line it prints, then run it again until the first line says exit=0.
+Never use `git commit --no-verify` and never edit files under .aigate/ (the gate's config and baseline).
+If a finding looks wrong, stop and tell the user instead of working around it.
+```
+
+These instructions ask; the hooks enforce. Keep the hooks installed (`aigate-lite install`) and run the gate in
+CI, because an agent can ignore instructions.
+
+## The reviewer: `aigate-lite review`
+
+The gate asks "may this commit go in?". The reviewer reads the same change the way a careful senior reviewer would and
+answers "what changed, what must be fixed, what should I look at, what looks good":
+
+```bash
+aigate-lite review                       # what is staged
+aigate-lite review --range origin/main..HEAD
+aigate-lite review --pr                  # the pull request in CI: range against its target branch, plus its title and text
+aigate-lite review --format md           # or text (default), json (versioned schema), agent
+aigate-lite check --deep                 # the gate's normal report, with the reviewer's findings added
+```
+
+It runs the gate's checks and six more that look at the rest of the repository, not only the changed lines:
+
+| rule | catches | people / AI agents |
+|---|---|---|
+| `api.unknown_symbol` | `from app.utils import parse_date` when there is no `parse_date`; a missing module; `pkg.DoThing()` with no such function (Python, Go, relative JS/TS imports) | warn / fix |
+| `api.bad_call` | a call with an unknown keyword or the wrong number of arguments to a function defined in the repo (Python, Go) | warn / fix |
+| `api.broken_caller` | a function's parameters changed and callers elsewhere were not updated (reported at each stale caller) | warn / fix |
+| `tests.missing_for_change` | functions changed with no related test changed (`[review] test_map` maps your layout) | warn / fix |
+| `review.claim_mismatch` | the commit message or PR text says "add tests", "fix `parse_date`" or "no behaviour change" and the diff says otherwise | warn / warn |
+| `code.error_check_removed` | an `if err != nil` removed, `except ValueError` turned into `except Exception: pass`, a `.catch` or `await` dropped, `_ = f()` where `f` returns an error | warn / fix |
+
+How much to trust it:
+
+- Everything is read with `ast` (Python) or the lexer (Go, JS/TS). Your code is never imported or run.
+- A file that does not parse, or a module that is dynamic (`__getattr__`, star imports, `getattr`/`hasattr` on the module,
+  `globals()`, `__dict__`, `exec`), produces no claim: the reviewer says nothing it cannot prove from the source.
+- Only names inside this repository are judged. Standard library, installed packages and path aliases are left alone.
+- These checks run only in `review` and `check --deep`, never in the commit hook, so a commit is not slower.
+  Measured costs are in [PROGRESS.md](PROGRESS.md).
+- The symbol index is cached by git blob id next to the result cache (`symbols-v1.json`, signed); `--no-cache` skips it.
+
+```toml
+[review]
+# source glob = where its tests live ({stem}, {dir}, {ext}); added to the usual names (test_x.py, x_test.go, x.test.ts)
+test_map = { "app/**/*.py" = "checks/{stem}_spec.py" }
+```
+
+## Existing project? Accept today's findings with `baseline`
+
+```bash
+python3 .aigate/aigate_lite.py check --all           # see what is already there
+python3 .aigate/aigate_lite.py baseline              # record non-secret findings in .aigate/baseline.json
+git add .aigate/baseline.json && git commit -m "baseline"
+```
+
+Fingerprints do not depend on line numbers, so unrelated edits do not resurrect old findings. Secrets are never
+baselined unless you pass `--include-secrets` (rotate them instead), and a baseline never hides *new* copies of an old finding.
+
+## Presets
+
+`preset = "relaxed" | "balanced" | "strict"` in `.aigate/lite.toml` (default `balanced`); `init` picks one for you.
+Your own `[rules]` settings always win (this includes turning the "core" rules above on for people). `strict` turns
+them on. The full table of what each preset changes is in
+[docs/RULES.md](docs/RULES.md) (generated by `scripts/gen_docs.py`).
+
+## Troubleshooting
+
+Run `python3 .aigate/aigate_lite.py doctor`. It checks git and Python versions, the hooks, the config and the
+registry reachability, and prints a one-line fix for anything wrong. Errors from other commands also end in a
+`fix:` line.
+
+## Configuration: `.aigate/lite.toml`
+
+See `examples/lite.toml` for every key. The most useful ones:
+
+```toml
+[rules]
+"suppress.type" = "warn"        # block | fix | warn | off; globs like "perf.*" work
+
+[deps]
+private = ["acme-*", "@acme/*"]                       # internal packages: skip public lookups
+trusted_sources = ["https://pypi.acme.dev/simple"]
+import_map = { mylib = "my-lib-dist" }                # import name -> package name
+
+[[commands]]                    # your own checks, e.g. run tests before every push
+name = "tests"
+run = "python -m pytest -q"
+stage = "push"                  # commit | push | both
+                                # then approve them once: aigate-lite trust
+
+[[allow]]                       # a known false positive
+rule = "secrets.generic"
+path = "tests/fixtures/**"      # blocking rules need a path or a fingerprint (see `check -v`)
+reason = "fake credentials used by tests"
+expires = 2027-06-30
+```
+
+To allow a fix- or warn-level finding for one commit: `AIGATE_ALLOW=tests.deleted git commit ...`.
+Blocking findings can only be allowed through `[[allow]]`.
+
+Result cache (off by default): `--cache` or `[gate] cache = true` remembers which files the per-file checks
+found clean, so an unchanged file is not checked again. Only clean verdicts are stored (no finding text),
+signed, in two 0600 files in your user cache dir. `--no-cache` turns it off even when the config turns it
+on, and also skips the registry lookup cache. It helps large changes and not small ones: compare the `C`
+and `C-cache` rows (300 files) with `A` and `A-cache` (1 file) in docs/PERF.md.
+
+## Output and exit codes
+
+- `--format text` (default), `json` (stable schema), `github` (annotations for Actions) or `sarif`
+  (SARIF 2.1.0, for code-scanning uploads).
+- `-q` prints only what stops the commit; `-v` adds hints, fingerprints and allowed findings. A text report that prints
+  a finding ends with a one-line credit (see "Credit and usage").
+- Exit codes: `0` pass or warnings only, `1` fix or block, `2` usage or git error.
+- The verdict is the strongest action found. A Fix verdict becomes Block when the risk score is 60 or
+  higher; the score uses the same formula as the full gate.
+
+## Enforce it in CI (hooks can be skipped)
+
+Hooks run on the developer's machine, so `--no-verify` (or an agent that commits that way) skips them.
+The check that cannot be skipped is a required CI status on the pull request.
+
+**GitHub Actions** — `examples/github-actions.yml`:
+
+1. Copy it to `.github/workflows/aigate-lite.yml` and commit `.aigate/aigate_lite.py`
+   (`aigate-lite install --vendor` copies it for you).
+2. Open a pull request once so the check runs and GitHub learns its name (the job is called `gate`).
+3. Settings → Branches (or Rules → Rulesets) → protect your default branch → **Require status checks to
+   pass** → add `gate`. If you use a merge queue, the workflow already listens to `merge_group`.
+4. **Required for this to mean anything:** GitHub runs the workflow file from the pull request itself, so
+   a pull request that edits `.github/workflows/aigate-lite.yml` can change what runs. Put
+   `.github/workflows/**` and `.aigate/**` in CODEOWNERS and turn on **Require review from Code Owners**
+   (or make the workflow a ruleset-required workflow). Without that, CI is a safety net, not a boundary.
+
+The workflow pins every action to a full commit SHA, runs the gate **and its config from the base
+branch** (a pull request cannot loosen the script or `.aigate/lite.toml` that judge it; the first PR that
+adds the gate uses its own copy, with a warning), writes annotations with `--format github`, and uploads
+`--format sarif` to code scanning (Security → Code scanning; the upload is skipped without failing the
+job where code scanning is not enabled). `--no-commands` keeps `[[commands]]` from the pull request from
+running in CI. The gate runs twice (annotations, then SARIF); only the first run decides the result.
+
+**GitLab CI** — `examples/gitlab-ci.yml` runs on merge-request pipelines and keeps `aigate.sarif` as an
+artifact. Make it blocking with Settings → Merge requests → **Pipelines must succeed**, and run fork
+merge-request pipelines in the parent project (otherwise a fork is checked against its own copy).
+
+**Other CI:** run `python .aigate/aigate_lite.py check --range "origin/main..HEAD" --no-commands` and fail
+the job on exit code 1. `--format json` (schema 1) and `--format sarif` (SARIF 2.1.0) are stable outputs.
+
+## Limits (read these)
+
+- **Hooks are bypassable.** `git commit --no-verify` and `git push --no-verify` skip them, and some
+  agents commit that way. The pre-push hook catches what the commit hook missed, but only a
+  server-side check is enforceable: see "Enforce it in CI" above.
+- **Static heuristics, not proof.** Time complexity is flagged from code shape, not measured. Test
+  tampering for JS/TS is line-based.
+- **Not covered in lite:** calls to functions or attributes that don't exist (that needs a type
+  checker, which you can add as a `[[commands]]` entry), sandboxed test runs, mutation testing, and
+  LLM review.
+- **Commands in `.aigate/lite.toml` need your approval.** A cloned or pulled config can't run code on your
+  next commit: `[[commands]]` stay off (one `commands.untrusted` warning says so; a repo's `[rules]` can't
+  change that rule) until a person runs
+  `aigate-lite trust`, which prints every command with hidden characters escaped and records exactly that
+  list in `.git/aigate/trusted`. Any change to any command needs a new approval; `trust --rev <branch>`
+  approves a config you push but have not checked out; AI agents can't approve. `--config FILE` on the
+  command line counts as your own choice and is trusted (so don't point it at a file a pull request controls).
+- **A vendored gate is code from the repo too.** With `install --vendor` the hook runs
+  `.aigate/aigate_lite.py` as committed; review changes to that file like any other code you execute.
+- **Offline:** if PyPI/npm can't be reached, dependency findings become `deps.unverified` warnings.
+  Set `[gate] offline = "block"` to stop instead.
+
+## License & credit
+
+aigate-lite is licensed under the [Apache License 2.0](LICENSE). You may use, modify and redistribute it, but you
+must keep the copyright header, the [NOTICE](NOTICE) file and credit to Hitarth Khatiwala (Apache-2.0, Section 4).
+Suggested credit line: "Uses aigate-lite by Hitarth Khatiwala" (https://github.com/hitarth1812/AI-Gate).
+
+`aigate-lite doctor` warns (it never fails) if the copyright header in the running file was removed or changed.
+Nothing in the gate depends on it: check results, exit codes and hooks behave the same either way.
+
+## Credit and usage
+
+Every place the tool names itself is visible text, documented here, and never changes a result or an exit code.
+
+| Where | What you see | When it is absent |
+|---|---|---|
+| `check` / `audit` text report | one last line: `aigate-lite by Hitarth Khatiwala · Apache-2.0 · <url>` (ASCII separators on a console that cannot show `·`) | on a clean pass, with `-q`, and in `--format json`, `agent`, `sarif` and `github` |
+| `review` text report | the same line, always | never absent |
+| `review --format md` | a last line `Reviewed by [aigate-lite](<url>) <version>` | never absent |
+| JSON (`check`, `audit`, `review`) | `"author"` and `"url"` next to `"tool"` and `"version"` (`"schema"` is unchanged; nothing was removed or retyped) | |
+| `--format agent` | one line `TOOL aigate-lite <version> <url>` directly before `END` | |
+| SARIF | the tool driver's `name`, `version`, `informationUri` and `organization` | |
+
+The credit is credit, not proof: nothing in the tool or in the CI examples trusts it, and nothing is hidden (there are no
+invisible characters or encoded marks anywhere; a test scans the repository for them). The footer is a plain line of
+text; the tool is Apache-2.0, so keep the copyright header and NOTICE when you redistribute it (Section 4).
+
+## Development
+
+```bash
+python3 -m pytest -q                                   # registry calls use tests/registry_fixture.json
+python3 bench/bench.py --compare bench/baseline.json   # perf gates (same machine as the baseline)
+python3 bench/bench.py --compare bench/baseline.json --markdown docs/PERF.md   # regenerate docs/PERF.md
+```