{
  "markdown": "![KWIK-E-GATE — your local convenience code review. Don’t forget the receipt.](docs/assets/kwik-e-gate-header.jpg)\n\n# Quick Gate JS\n\n> **Existing Quick Gate users:** This repository stays at its original URL.\n> Published `quick-gate` 0.3.2, historical tags and SHA pins, the root and nested\n> Actions, plugin installs, issues, and releases remain here. The active\n> [Kwik-e-gate product source](https://github.com/hermes-labs-ai/kwik-e-gate)\n> is a new repository. Its 0.4.0 packages are not yet published.\n\n**Fast local checks for coding agents. PASS / FAIL. Don't forget the receipt.**\n\nInterpret the change against your repository’s declared gates, record what ran, and verify the\nreceipt before treating the work as checked. Free, local, no daemon, no model or API\nrequired. Python 3.11+ and Git; zero runtime Python dependencies.\n\nDeveloped by [Hermes Labs](https://hermes-labs.ai).\n\n> **Unreleased 0.4.0 consolidation.** Public PyPI `hermes-gate` is 0.1.7; npm\n> `quick-gate` is 0.3.2. Install this checkout to use the new commands. The distribution remains\n> `hermes-gate`; `hermes-gate` and `kwik-gate` use the same engine.\n\n## Start here\n\nFrom this source checkout:\n\n```bash\npython3 -m venv /tmp/kwik-gate-venv\n/tmp/kwik-gate-venv/bin/python -m pip install .\n# Use the installed executable in the repository you want to check:\ncd /path/to/your/git-repository\n/tmp/kwik-gate-venv/bin/kwik-gate init\n# Review .hermes/gate.toml: choose the checks that matter for this project.\n/tmp/kwik-gate-venv/bin/kwik-gate run\n/tmp/kwik-gate-venv/bin/kwik-gate verify\n```\n\nAfter 0.4.0 is published, `pip install hermes-gate==0.4.0` provides both commands.\nExisting users can continue using `hermes-gate fast` and `hermes-gate full`.\n\n| Command | Result |\n| --- | --- |\n| `kwik-gate plan` | Explain gate selection without executing checks; returns PLANNED, never a checked PASS |\n| `kwik-gate run` | Automatically select applicable fast checks or escalate broader changes to full; issue a receipt |\n| `kwik-gate run --mode fast` | Explicit fast checks; cached only with a matching input/contract identity |\n| `kwik-gate run --mode full` | Every declared full stage, including file-driven checks on clean CI checkouts |\n| `kwik-gate run --output /external/path/receipt.json` | Run plus an exported copy of the receipt |\n| `kwik-gate verify` | Read-only verification of the latest run receipt, fast or full |\n| `kwik-gate verify --kind full` | Verify the current full receipt |\n| `kwik-gate verify --receipt /external/path/receipt.json` | Verify an exported receipt against this same local checkout |\n\nRun exits **0 for PASS, 1 for FAIL**. Stdout is JSON containing `status`, `receipt`,\n`receipt_path`, `routing`, `cached`, and elapsed time. Every started run issues a receipt,\nincluding missing/invalid configuration, unavailable tools, timeouts and no-check\noutcomes. A non-Git run stores its failure receipt in the user cache. If storage is\nunavailable, stdout still contains a failure receipt; it cannot report PASS.\nHelp and argument-parser failures are not check executions.\n\nReceipt files live under the worktree's Git directory, outside tracked source.\nExports must be outside the repository. `verify` runs no checks or reviewer and\nexits 1 for missing, failed, stale or incomplete evidence. Receipts are intentionally\nlocal to their checkout; copying a receipt to a different checkout does not prove\nthat checkout was checked.\n\n## Choose the right gate locally\n\nThe default `auto` mode interprets changed paths and repository policy. Ordinary\nsource changes use matching fast stages. Dependency/project contracts, tests, CI,\ngate configuration and sensitive auth/schema/migration paths escalate to full.\nThe receipt records the decision, evidence, selected/skipped stages and review advice.\n`kwik-gate plan` previews that choice; it runs no tool, writes nothing and reports\nPLANNED. It does not claim that checks have passed.\n\nThe selector reads no source files and calls no subprocess or model. Git discovery,\ninput hashing, process startup and the checks themselves take additional time.\nThis is an explainable path/policy interpretation, not semantic code comprehension.\nExtend the policy with `[routing].full_globs` and `.review_globs` for project-specific\nrisk. `--mode fast` / `--mode full` explicitly select a contract.\n\nAn agent or human can use the plan with an LLM when available. `kwik-gate review`\nadds the installed provider’s semantic judgment; it is separate evidence. Sensitive\nchanges can recommend review while deterministic checks still work without it.\nExisting repository boundary policy remains authoritative.\n\n## Declare the checks\n\n`init` writes a reviewable `.hermes/gate.toml`, a stdlib runner, and a CI workflow.\nIt refuses to overwrite existing integration files without `--force`. It never\ninstalls project tools. Detection is a starting point; adapt the profile for a\nmonorepo or any custom build system.\n\nA minimal profile:\n\n```toml\nversion = 1\n\n[gate]\nfast_budget_seconds = 8.0\nexclusions = [\".git/**\", \"node_modules/**\", \"dist/**\", \"build/**\"]\n\n[[fast]]\nname = \"lint\"\nargv = [\"npm\", \"run\", \"lint\"]\ntimeout_seconds = 6.0\nglobs = [\"**/*\"]\n\n[[full]]\nname = \"test\"\nargv = [\"npm\", \"test\"]\ntimeout_seconds = 180.0\n```\n\nUse argv arrays, not shell strings. `{files}` expands to the selected paths for\nfile-aware tools. Fast stages run only when their globs match; full stages receive\nall included repository inputs. Missing or wholly skipped checks never establish a\nchecked PASS. The fast command budget defaults to eight seconds; hashing inputs\nand recording executable identities add overhead proportional to input size.\n\nSee [configuration](docs/CONFIGURATION.md) for adapters, exclusions and optional\nreview/boundary policy.\n\n## Optional Python diagnostics\n\nFor normalized Ruff/Pyright/pytest findings, use\n[Quick Gate Python (PyGate)](https://github.com/hermes-labs-ai/quick-gate-python):\n\n```bash\npython -m pip install pygate-ci==0.3.2 ruff pyright pytest pytest-json-report\nkwik-gate init --adapter pygate\n```\n\nThis explicitly uses the installed `pygate` executable. Fast maps to its `canary`\ncontract; full includes pytest. PyGate has its own native API and existing users\nkeep `pygate-ci` / `pygate`. Its optional Pydantic/tool dependencies never become\ncore dependencies. Both adapters produce diagnostics; the core issues the receipt.\n\n## Optional JS/TS diagnostics\n\nNative commands work with any language. For normalized JS/TS findings, use the\nexisting [Quick Gate adapter](https://github.com/hermes-labs-ai/quick-gate-js):\n\n```bash\n# Explicitly install the adapter in the target project's dependencies.\nnpm install --save-dev quick-gate@0.3.2\nkwik-gate init --adapter quick-gate\n```\n\nThe generated adapter argv is `npx --no-install quick-gate`: run never downloads\nit. Review `quick-gate.config.json` and disable inapplicable gates explicitly.\nLegacy Quick Gate quick mode includes Lighthouse; for a library or fast local\nloop, set `gates.lighthouse` to `false`. Its `gate-result/v1` diagnostics are\nvalidated by the core before issuing a completion receipt. npm users can still\nuse its standalone CLI/API without installing Python.\n\n## CI and coding agents\n\nGenerated CI runs the same `kwik-gate run --mode full` command and preserves the\nreceipt as an artifact even when checks fail. Fresh workflows require the matching\nCLI version to be published. The copied runner remains a compatible check executor;\nit is not a second receipt authority.\n\nThe consolidated core Action runs the source selected by its Git ref, with no PyPI\ninstallation. In this checkout use `./.github/actions/kwik-e-gate`; after integration,\npin its reviewed commit. The existing root Action keeps the standalone JS interface.\n\n```yaml\n- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1\n  with:\n    fetch-depth: 0\n    persist-credentials: false\n- uses: hermes-labs-ai/kwik-e-gate/.github/actions/kwik-e-gate@5d6b486791a084bc312055e350983881dacbf512\n  id: gate\n  with:\n    mode: full\n- uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a\n  if: always()\n  with:\n    name: kwik-e-gate-receipt\n    path: ${{ steps.gate.outputs.receipt-path }}\n```\n\nThe pinned commit is the accepted source import in the new repository; the 0.4.0\npackages remain unpublished. The core Action exposes `status` and `receipt-path`, including\nfailing runs. For an ambiguous detached/merge checkout, supply its `base` input.\nOld JS Action users retain their original inputs/outputs; see the\n[standalone JS guide](docs/QUICK-GATE-JS.md).\n\n[Five native readiness examples](docs/CI-ADMISSION.md) cover MCP Python,\nPydantic AI, Hermes Agent, pipx and PyPA packaging. Each declares its check scope and setup;\n`full` executes that profile, not every upstream matrix job. The evidence includes\na sixth, MCP TypeScript E2E failure that remains FAIL despite passing test cases. Local compatibility\ndoes not imply upstream adoption or approval.\n\nThe repository's [Agent Skill](.agents/skills/hermes-gate/SKILL.md) works in\ncompatible Agent Skills hosts. The self-contained [Claude/portable plugin](claude-plugin/)\nand `hermes-gate install-codex` retain their installed hook contracts. Hooks and\nlegacy Git boundaries can require a separate review receipt: this advanced policy\nis independent of the deterministic run/verify workflow. Installing hooks is an\nexplicit user choice; `run` does not install them.\n\n## What PASS means\n\nA PASS means at least one declared check ran successfully and the bound inputs and\ncontract stayed unchanged. Receipts bind HEAD, selected diff scope, all included\ntracked/unignored inputs, profile/runner bytes, executable bytes/execution bits,\ncore implementation, check argv/results, tool version observations and time.\nChanging an unrelated included input conservatively invalidates reuse.\n\nThis is evidence of declared checks, not proof of correctness, complete coverage,\nhermetic execution, authenticity, or authorization to merge/release. Receipts are\nunsigned; someone who can write local state can forge evidence. Commands retain\ntheir own side effects, network access and flakiness. Ignored/excluded dependencies,\nexternal services, environment variables, clock and imported tool dependencies are\nnot fully bound. Directory inputs (including gitlinks and directory symlinks) fail\nclosed until represented as explicit ordinary files or handled in a separate gate.\nOutput can be truncated; the receipt records that fact.\n\n`run` never repairs source or invokes a model. Explicit `repair` remains available;\n`review` is an optional semantic extension that uses the configured installed\nprovider. API/model review being unavailable does not prevent local run/verify.\n\n## Migration, development and release\n\n- [Configuration and receipt contracts](docs/CONFIGURATION.md)\n- [Standalone Quick Gate JS adapter](docs/QUICK-GATE-JS.md)\n- [Changelog](CHANGELOG.md), [security](SECURITY.md), [contributing](CONTRIBUTING.md)\n\n```bash\npython -m pip install -e '.[test]'\nruff check .\npytest\npython -m build\n```\n\nThe real JS adapter roundtrip also runs in CI. To run it locally, set\n`KWIK_QUICK_GATE_CLI` to an installed checkout's `src/cli.js`, then run\n`pytest tests/test_workflow.py -k real_js_adapter_roundtrip`.\n\nThe real PyGate roundtrip is also exercised in adapter CI. Set `KWIK_PYGATE_CLI`\nto an installed `pygate` and run `pytest tests/test_routing.py -k real_pygate`.\n",
  "bytes": 11411,
  "sha": "446f3c08b34929459fed496992d005ba0d410dab58e29098fb1bd1fb122a2923",
  "repo_slug": "roli-lpci/quick-gate-js",
  "fonte": "repo",
  "truncated": false,
  "api": "https://api.agentalog.com/api/listings/plg_roli_lpci_quick_gate_js_758501a3/readme"
}