@sunaiva/gate 1.1.0 → 1.1.2

package/README.md

@@ -1,451 +1,451 @@
-# @sunaiva/gate
-
-**Stop documenting rules your agents ignore. Start enforcing them.**
-
-`@sunaiva/gate` is an MCP server that intercepts AI agent actions before they
-execute and blocks the ones that violate your rules. It runs locally, in
-process, with zero external dependencies on the Free tier — the rules are baked
-into the package and enforced by a deterministic engine.
-
-```bash
-npx @sunaiva/gate
-```
-
-> **Status**: `1.1.0` "Foundation Release" — first publicly-supported release.
-> Closes all 7 CRITICAL findings from the signed Ship-Confidence verdict on
-> `1.0.1`. Full changelog: [`CHANGELOG.md`](./CHANGELOG.md). Roadmap that led
-> here: [`ROADMAP_1_1_0.md`](./ROADMAP_1_1_0.md).
-
----
-
-## 60-second quickstart
-
-```bash
-# 1. Install (no signup, no API key, no DNS records)
-npx @sunaiva/gate
-
-# 2. Verify it loaded
-npx @sunaiva/gate --smoke-test
-# → ✓ Gate loaded — 100 rules
-# → ✓ Constitutional rules — 32 (cannot be disabled, enforced locally)
-# → ✓ Premium rules — 68 (require backend service)
-# → Status: HEALTHY
-# → Version: 1.1.0
-
-# 3. Add to your MCP client (Claude Code, Cursor, Windsurf, Cline)
-#    settings — see "MCP configuration" below.
-```
-
-That is the entire onboarding. The 32 constitutional rules are active on first
-boot; no other configuration is required.
-
----
-
-## What's free, forever
-
-The 1.1.0 Free tier (BUSL-1.1) ships with everything below baked into the npm
-package. No backend, no telemetry, no API key required.
-
-- **32 constitutional rules enforced locally** across five categories —
-  financial-safety, data-protection, action-governance, security, and
-  communication-safety. Detection patterns ship intact inside the package at
-  `dist/rules/rules.json`.
-- **Severity ladder**: `block` / `warn-then-block` / `warn`.
-- **Approval-token workflow** — drop a JSON token at
-  `data/deploy_queue/APPROVAL_TOKENS/<artifact>.json` and the gate honours it
-  once, within a 1-hour TTL. This is the free-tier escape valve for one-shot
-  manual unblocks.
-- **Local audit log** at `~/.sunaiva/audit/audit.jsonl` (lifetime, no rotation
-  cap). Every entry records `tier`, `audit_status`, `evidence`, and
-  `event_type` for queryable history.
-- **Kill-switch** — `DISABLE_SUNAIVA_GATE=1` short-circuits every
-  `validate_action` to `allowed: true` with unconditional stderr disclosure.
-- **Dry-run mode** — `SUNAIVA_GATE_DRY_RUN=1` evaluates rules normally and
-  records `would_have_blocked: [...]` without ever blocking.
-- **Constitutional immutability** — the 32 rules cannot be disabled via
-  `update_rules` and cannot be bypassed via `log_bypass`, even if
-  `~/.sunaiva/gate-config.json` is hand-edited (the loader re-merges on every
-  read).
-- **Fail-CLOSED by default** — uncaught exceptions exit 3, malformed input
-  exits 4. Both write a structured audit entry. Opt-in legacy fail-open via
-  `SUNAIVA_GATE_FAIL_OPEN_ON_ERROR=1`.
-- **MCP integration** — Claude Code, Cursor, Copilot, Windsurf, Cline via the
-  standard `mcpServers` config.
-
-The Free tier is BUSL-1.1 licensed and converts to **Apache-2.0** on
-**2030-05-10**. You can fork it, modify it, embed it in internal CI, and ship
-it in non-production workflows today — no contract, no signup, no credit card.
-
----
-
-## What you get with Pro — `$79/mo` recommended, BYOK
-
-Pro adds the things a deterministic local engine cannot do on its own. Full
-tier matrix and pricing rationale: [`TIER_DEFINITIONS.md`](./TIER_DEFINITIONS.md).
-
-- **68 additional premium rules** (100 total) evaluated server-side via the
-  premium backend at `https://gate.sunaiva.dev/api/v1/match`. Detection
-  patterns are proprietary and stay in our infrastructure.
-- **Signed Ship-Confidence verdicts** — HMAC-SHA256, 60-minute freshness
-  window. The `ship_confidence_check` MCP tool verifies the signature in
-  constant time and returns `allowed: true` only when the verdict is
-  `GREEN`, fresh, and untampered.
-- **`sunaiva-ship-confidence` skill integration** — three independent
-  verification layers (cross-provider spec verification, property-based
-  testing with Hypothesis, adversarial audit via garak + DeepTeam) that
-  emit signed verdicts the Gate honours automatically in CI.
-- **Dashboard** — rules tab, audit tab, settings tab, billing tab. Cloud
-  audit sync with 90-day retention.
-- **BYOK** — bring your own `ANTHROPIC_API_KEY` and `OPENROUTER_API_KEY`.
-  You pay your own inference bill. We never see your tokens.
-- **Email support** — `support@sunaivadigital.com`, 2-business-day SLA
-  target.
-- **Stripe-managed billing** with the founders coupon `KINANFOUNDER2026`
-  (100% off, first 10 redemptions, per Rule 30).
-
-Enterprise (SSO, on-prem, multi-tenant org dashboard, named CSM) is
-quote-to-cash — see [`TIER_DEFINITIONS.md`](./TIER_DEFINITIONS.md) §3.
-
----
-
-## Architecture
-
-```
-┌────────────────────────────────────────────────────────────────┐
-│  Your project (Claude Code / Cursor / Windsurf / Cline)        │
-│                                                                │
-│   ┌──────────────────────────────────────────────────────┐    │
-│   │  MCP client invokes a tool                            │    │
-│   │     e.g. Bash("git push origin main")                 │    │
-│   └────────────────────────┬─────────────────────────────┘    │
-└────────────────────────────┼───────────────────────────────────┘
-                             ▼
-┌────────────────────────────────────────────────────────────────┐
-│  @sunaiva/gate  (MCP server, stdio transport)                  │
-│                                                                │
-│   ┌──────────────────────────────────────────────────────┐    │
-│   │  validate_action                                      │    │
-│   │     │                                                  │    │
-│   │     ├─►  Constitutional rules (32) — pattern matched  │    │
-│   │     │     LOCALLY against dist/rules/rules.json       │    │
-│   │     │     ─────────────────────────────► block/warn   │    │
-│   │     │                                                  │    │
-│   │     └─►  Premium rules (68) — only if backend set      │    │
-│   │            POST https://gate.sunaiva.dev/api/v1/match   │    │
-│   │            (JWT auth via SUNAIVA_GATE_API_TOKEN)       │    │
-│   │            ─────────────────────────────► block/warn   │    │
-│   │            (fail-OPEN per-rule on backend error)       │    │
-│   └──────────────────────────────────────────────────────┘    │
-│                                                                │
-│   audit log ─►  ~/.sunaiva/audit/audit.jsonl                  │
-└────────────────────────────────────────────────────────────────┘
-```
-
-The Free tier path (constitutional rules) has zero network dependencies. The
-Pro path is opt-in — set `SUNAIVA_GATE_BACKEND_URL` and the engine starts
-POSTing actions to the backend for the premium-rule subset; without it, those
-rules are skipped (recorded as `skipped_premium` in the audit, surfaced once
-per session as a stderr notice).
-
----
-
-## MCP configuration
-
-Add to your client's MCP settings:
-
-```json
-{
-  "mcpServers": {
-    "sunaiva-gate": {
-      "command": "npx",
-      "args": ["@sunaiva/gate"]
-    }
-  }
-}
-```
-
-Restart your MCP client. The first tool call will trigger the gate.
-
----
-
-## MCP tool reference
-
-| Tool | What it does |
-|------|--------------|
-| `validate_action` | Check a proposed action against all active rules. Returns `{allowed, violations[], warnings[], skipped_premium[], dry_run?, would_have_blocked?, stamp}`. The workhorse — every PreToolUse hook calls this. |
-| `log_bypass` | Record an intentional rule bypass for the audit log. **Rejects constitutional rules** with a structured `CONSTITUTIONAL_RULE_CANNOT_BE_BYPASSED` error. |
-| `get_rules` | List active rules; supports filtering by `category` or `preset`. |
-| `update_rules` | Enable / disable rules. **Rejects disable attempts against constitutional rules** with a structured `CONSTITUTIONAL_RULE_IMMUTABLE` error. |
-| `get_audit_log` | Return recent gate decisions from `~/.sunaiva/audit/audit.jsonl` with `tier`, `audit_status`, `evidence`, `event_type` fields. |
-| `ship_confidence_check` | **Paid-tier production-deploy gate.** Accepts a signed verdict path or artifact ID; verifies HMAC-SHA256 against `SHIP_CONFIDENCE_SIGNING_KEY`; returns `{allowed, tier: "paid"\|"free", reason, evidence}`. Tagged in the audit ledger so you can measure the free-→paid upgrade funnel. |
-
-Total: **6 MCP tools**. The `ship_confidence_check` tool is the ported
-TypeScript implementation of `.claude/hooks/ship_confidence_gate.py` v1.2.0,
-byte-compatible with the Python skill's canonical-JSON HMAC format.
-
----
-
-## Environment variables
-
-| Variable | Default | Purpose |
-|----------|---------|---------|
-| `DISABLE_SUNAIVA_GATE` | unset | Set to `1` to short-circuit every `validate_action` to `allowed: true`. Unconditionally logs to stderr. |
-| `SUNAIVA_GATE_DRY_RUN` | unset | Set to `1` to evaluate rules normally but never block. Response includes `dry_run: true` and `would_have_blocked: [...]`. |
-| `SUNAIVA_GATE_BACKEND_URL` | unset | Premium backend endpoint. Default for Pro customers: `https://gate.sunaiva.dev/api/v1/match`. When unset, premium rules are skipped (recorded as `skipped_premium`). |
-| `SUNAIVA_GATE_API_TOKEN` | unset | Bearer token (JWT) for the premium backend. Required when `SUNAIVA_GATE_BACKEND_URL` is set. |
-| `SUNAIVA_GATE_BACKEND_TIMEOUT_MS` | `3000` | Backend request timeout. Backend errors fail-OPEN per-rule (logged as `skipped_premium_backend_error`). |
-| `SUNAIVA_GATE_FAIL_OPEN_ON_ERROR` | unset | Set to `1` to restore the 1.0.x fail-open behaviour on uncaught exceptions and malformed input. Default is fail-CLOSED. |
-| `SHIP_CONFIDENCE_SIGNING_KEY` | unset | HMAC-SHA256 key for verifying signed `sunaiva-ship-confidence` verdicts. Required by the `ship_confidence_check` tool. |
-| `SUNAIVA_GATE_AUDIT_PATH` | `~/.sunaiva/audit/audit.jsonl` | Override the audit log path. |
-
----
-
-## Exit codes
-
-| Code | Meaning |
-|------|---------|
-| `0`  | Allow / success / smoke-test HEALTHY |
-| `1`  | Generic test failure (legacy `--test` flag, smoke-test DEGRADED) |
-| `2`  | Block (Claude Code convention) |
-| `3`  | Fail-CLOSED internal error (uncaught exception). Opt-in fail-open via `SUNAIVA_GATE_FAIL_OPEN_ON_ERROR=1`. |
-| `4`  | Fail-CLOSED invalid input (malformed JSON, empty stdin). Same opt-in escape hatch. |
-| `5`  | Smoke-test DEGRADED with missing required files (e.g. `dist/rules/rules.json` absent). |
-
----
-
-## Killing the gate (and why we tell you how)
-
-`@sunaiva/gate` discloses its kill-switch in every block and warn message:
-
-```
-[sunaiva-gate v1.1.0] BLOCK — rule: dat-001 (recursive root deletion)
-Escape: export DISABLE_SUNAIVA_GATE=1
-Audit: ~/.sunaiva/audit/audit.jsonl
-```
-
-The escape hint is a deliberate security-disclosure design. An enforcement
-product that hides its own bypass is one that gets routed around in production
-without anyone knowing. The kill-switch invocation is itself logged to the
-audit ledger as `decision: 'bypass_kill_switch'`, so disabling the gate is
-visible to anyone who reads the audit.
-
-```bash
-export DISABLE_SUNAIVA_GATE=1   # All actions allowed (logged)
-unset DISABLE_SUNAIVA_GATE      # Back to normal enforcement
-```
-
-Use dry-run instead of the kill-switch when you want to *measure* what the
-gate would block without actually blocking anything:
-
-```bash
-export SUNAIVA_GATE_DRY_RUN=1
-# → response.dry_run: true
-# → response.would_have_blocked: [{rule_id, name, severity}, ...]
-```
-
----
-
-## Decision model — warn-then-block escalation
-
-Constitutional rules block on the first match. Standard rules (the
-non-constitutional subset) implement a session-state escalation:
-
-- **First match in a session** → `warn` (action allowed, message printed).
-- **Subsequent matches in the same session** → `block`.
-
-This avoids one-time false-positive noise while still catching repeated
-violations. The session counter is reset when the MCP server process restarts.
-Confidence is derived from keyword-count thresholds: `≥3` keywords matched →
-`high`, `1-2` → `medium`, `0` → `low` (low confidence is filtered out before
-the response).
-
----
-
-## Smoke test
-
-```bash
-$ npx @sunaiva/gate --smoke-test
-✓ Gate loaded — 100 rules
-✓ Constitutional rules — 32 (cannot be disabled, enforced locally)
-✓ Premium rules — 68 (require backend service)
-✓ Presets file — 5 presets available
-✓ Live eval (git push origin main) — HARD block via gov-001
-✓ Live eval (ls -la) — ALLOW
-✓ Live eval (rm -rf /) — HARD block via dat-001
-✓ Live eval (stripe.charges.create) — HARD block via fin-001
-✓ Immutability guard — ACTIVE (32 constitutional rules pinned)
-✓ MCP server — ready (not started in smoke test)
-Status: HEALTHY
-Version: 1.1.0
-Issues: https://github.com/Kinan27/sunaiva-gate/issues
-```
-
-Exit codes: `0` = HEALTHY, `1` = DEGRADED, `5` = missing required files.
-
----
-
-## Presets
-
-`get_rules` accepts a `preset` argument that filters the active set:
-
-| Preset | Rules | Use case |
-|--------|-------|----------|
-| `minimal` | 5 | Absolute non-negotiables only |
-| `essential` | 15 | Recommended starting point |
-| `developer-safety` | 25 | AI coding agents (Cursor / Windsurf / Cline / Aider) |
-| `financial-protection` | 24 | All financial + resource rules |
-| `full-suite` | 100 | Everything — Free constitutional set + Pro premium set |
-
-Presets read from `dist/rules/presets.json`. Premium presets require
-`SUNAIVA_GATE_BACKEND_URL` to be set; without it the premium rules are skipped
-with a `skipped_premium` audit entry.
-
----
-
-## Ship Confidence Gate (paid tier)
-
-The `ship_confidence_check` MCP tool is the deploy-time gate for high-blast-
-radius commands (`npm publish`, `wrangler deploy`, `gh repo create --public`,
-`netlify deploy --prod`). It checks for authorization in two tiers:
-
-### Paid path — signed verdict
-1. The `sunaiva-ship-confidence` Python skill runs three verification layers
-   against your product (spec verification, property-based testing,
-   adversarial audit).
-2. It emits a signed verdict at
-   `data/ship_confidence_verdicts/<artifact>.signed.json`.
-3. The `ship_confidence_check` tool verifies:
-   - HMAC-SHA256 signature is valid (constant-time compare, byte-compatible
-     with the Python skill's canonical-JSON encoding).
-   - `level == "GREEN"` (YELLOW and RED hard-block).
-   - Signed within the last 60 minutes
-     (configurable via `VERDICT_MAX_AGE_MINUTES`).
-4. On all-pass: returns `{allowed: true, tier: "paid", ...}` and writes an
-   audit entry tagged `tier: "paid"` with the verdict ID and evidence.
-
-### Free fallback — approval token
-If no signed verdict is found (or `SHIP_CONFIDENCE_SIGNING_KEY` is not set),
-the tool falls back to a one-time approval token at
-`data/deploy_queue/APPROVAL_TOKENS/<artifact>.json` written within the last
-hour. Tagged `tier: "free"` in the audit ledger with an upgrade hint pointing
-at the paid skill.
-
-```bash
-# CLI form for use in CI:
-npx @sunaiva/gate --ship-confidence @sunaiva/gate@1.1.0
-# Exit 0 = allow, 2 = block, 3 = internal error (fail-OPEN logged)
-```
-
----
-
-## Constitutional rules cannot be disabled or bypassed
-
-This is the package's hard guarantee. The 32 constitutional rules are
-re-merged into `active_rules` on every config load — even if
-`~/.sunaiva/gate-config.json` is hand-edited to remove them — and:
-
-- `update_rules({disable: ['fin-001']})` returns
-  `{error: "CONSTITUTIONAL_RULE_IMMUTABLE", rule_ids: [...]}`. No state
-  change.
-- `log_bypass({rule_id: 'fin-001'})` returns
-  `{error: "CONSTITUTIONAL_RULE_CANNOT_BE_BYPASSED", rule_id: ...}`. Nothing
-  written to the bypass log.
-
-The kill-switch (`DISABLE_SUNAIVA_GATE=1`) is the only way to disable
-constitutional enforcement, and it is loud — stderr disclosure on every
-block, audit-ledger entry on every short-circuit. There are no quiet
-bypasses.
-
----
-
-## Known limitations — what 1.1.0 does NOT have
-
-We shipped `1.0.1` with seven CRITICAL gaps flagged by our own signed
-Ship-Confidence verdict on our own commit (`01KRDBCEYF2CAB21G6Y3E9VVH5`, RED).
-1.1.0 closes all seven. What is honestly **not** in 1.1.0 yet:
-
-- **Sunaiva-Managed inference** — no flat-fee tier that includes LLM calls.
-  BYOK only in v1. Revisit at 50+ Pro customers.
-- **UI verification layer** (Playwright walkthroughs / computer-use) —
-  designed in
-  `data/ship_confidence_skill_upgrade_2026_05_11.md`, not yet shipped.
-  Folded into Pro at no extra cost when it lands.
-- **Multi-tenant dashboard / "Pro Team" tier** — Pro is single-seat in v1.
-  Team management is Enterprise. A self-serve "Pro Team" tier waits until
-  10+ customers ask for it.
-- **On-prem / VPC deployment** — Enterprise-only roadmap item. Helm chart
-  and Terraform module designs exist; not yet packaged.
-- **Per-call / metered pricing** — abandoned. Subscription wins.
-- **On-chain attestation (ERC-8004)** — aspirational. Deferred to v2.x.
-
-Full deferred-feature list:
-[`TIER_DEFINITIONS.md` §4](./TIER_DEFINITIONS.md).
-
----
-
-## Cross-platform
-
-- **Linux** — native.
-- **WSL** — native.
-- **macOS** — native.
-- **Windows** — native Node, plus a Python shim for clients that invoke the
-  legacy `hooks/sunaiva_gate_hook.py` PreToolUse path.
-
----
-
-## Privacy
-
-Your data stays where you choose. The Free tier makes **zero** external network
-calls — constitutional rules are evaluated locally against patterns shipped
-inside the package. The Pro path is opt-in: when you set
-`SUNAIVA_GATE_BACKEND_URL`, the engine POSTs only the proposed action text
-and rule IDs to the backend; we never see your code, your secrets, or your
-filesystem. BYOK means your `ANTHROPIC_API_KEY` and `OPENROUTER_API_KEY` go
-direct from your machine to those providers — they do not transit Sunaiva.
-
----
-
-## License
-
-[BUSL-1.1](./BUSINESS_LICENSE.md) — free for evaluation, internal development,
-hobby and academic use. Commercial license required if you embed the Gate in
-the critical path of a third-party paying-customer product before the
-**Change Date of 2030-05-10**, after which the wrapper converts to
-**Apache-2.0** automatically. The premium backend stays proprietary regardless
-of the Change Date.
-
-- Licensor: Sunaiva Digital
-- Change Date: **2030-05-10**
-- Change License: **Apache License, Version 2.0**
-
----
-
-## Support
-
-| Need | Where |
-|------|-------|
-| Bug or crash | [Open an issue](https://github.com/Kinan27/sunaiva-gate/issues/new?template=bug.yml) |
-| Feature request | [Open an issue](https://github.com/Kinan27/sunaiva-gate/issues/new?template=feature.yml) |
-| Security vulnerability | Email `security@sunaivadigital.com` (do not file publicly) |
-| Licensing | `kinan@sunaiva.ai` |
-| Commercial / paid tier | `support@sunaivadigital.com` |
-| General discussion | [GitHub Discussions](https://github.com/Kinan27/sunaiva-gate/discussions) |
-
-Full support guide: [`SUPPORT.md`](./SUPPORT.md).
-
-When reporting bugs, include the output of `npx @sunaiva/gate --smoke-test`
-and `node --version`.
-
----
-
-## Contributing
-
-Pull requests welcome. For substantial changes, please open an issue first to
-discuss the proposal. Constitutional rule additions require a corresponding
-test fixture in `tests/bundle.test.ts` and a passing dogfood Ship-Confidence
-verdict on the change.
-
----
-
-*Built by a team whose own hooks killed their development for nine hours.
-We fixed it. Then we shipped the fix. Then we signed the proof.*
+# @sunaiva/gate
+
+**Stop documenting rules your agents ignore. Start enforcing them.**
+
+`@sunaiva/gate` is an MCP server that intercepts AI agent actions before they
+execute and blocks the ones that violate your rules. It runs locally, in
+process, with zero external dependencies on the Free tier — the rules are baked
+into the package and enforced by a deterministic engine.
+
+```bash
+npx @sunaiva/gate
+```
+
+> **Status**: `1.1.0` "Foundation Release" — first publicly-supported release.
+> Closes all 7 CRITICAL findings from the signed Ship-Confidence verdict on
+> `1.0.1`. Full changelog: [`CHANGELOG.md`](./CHANGELOG.md). Roadmap that led
+> here: [`ROADMAP_1_1_0.md`](./ROADMAP_1_1_0.md).
+
+---
+
+## 60-second quickstart
+
+```bash
+# 1. Install (no signup, no API key, no DNS records)
+npx @sunaiva/gate
+
+# 2. Verify it loaded
+npx @sunaiva/gate --smoke-test
+# → ✓ Gate loaded — 100 rules
+# → ✓ Constitutional rules — 32 (cannot be disabled, enforced locally)
+# → ✓ Premium rules — 68 (require backend service)
+# → Status: HEALTHY
+# → Version: 1.1.0
+
+# 3. Add to your MCP client (Claude Code, Cursor, Windsurf, Cline)
+#    settings — see "MCP configuration" below.
+```
+
+That is the entire onboarding. The 32 constitutional rules are active on first
+boot; no other configuration is required.
+
+---
+
+## What's free, forever
+
+The 1.1.0 Free tier (BUSL-1.1) ships with everything below baked into the npm
+package. No backend, no telemetry, no API key required.
+
+- **32 constitutional rules enforced locally** across five categories —
+  financial-safety, data-protection, action-governance, security, and
+  communication-safety. Detection patterns ship intact inside the package at
+  `dist/rules/rules.json`.
+- **Severity ladder**: `block` / `warn-then-block` / `warn`.
+- **Approval-token workflow** — drop a JSON token at
+  `data/deploy_queue/APPROVAL_TOKENS/<artifact>.json` and the gate honours it
+  once, within a 1-hour TTL. This is the free-tier escape valve for one-shot
+  manual unblocks.
+- **Local audit log** at `~/.sunaiva/audit/audit.jsonl` (lifetime, no rotation
+  cap). Every entry records `tier`, `audit_status`, `evidence`, and
+  `event_type` for queryable history.
+- **Kill-switch** — `DISABLE_SUNAIVA_GATE=1` short-circuits every
+  `validate_action` to `allowed: true` with unconditional stderr disclosure.
+- **Dry-run mode** — `SUNAIVA_GATE_DRY_RUN=1` evaluates rules normally and
+  records `would_have_blocked: [...]` without ever blocking.
+- **Constitutional immutability** — the 32 rules cannot be disabled via
+  `update_rules` and cannot be bypassed via `log_bypass`, even if
+  `~/.sunaiva/gate-config.json` is hand-edited (the loader re-merges on every
+  read).
+- **Fail-CLOSED by default** — uncaught exceptions exit 3, malformed input
+  exits 4. Both write a structured audit entry. Opt-in legacy fail-open via
+  `SUNAIVA_GATE_FAIL_OPEN_ON_ERROR=1`.
+- **MCP integration** — Claude Code, Cursor, Copilot, Windsurf, Cline via the
+  standard `mcpServers` config.
+
+The Free tier is BUSL-1.1 licensed and converts to **Apache-2.0** on
+**2030-05-10**. You can fork it, modify it, embed it in internal CI, and ship
+it in non-production workflows today — no contract, no signup, no credit card.
+
+---
+
+## What you get with Pro (recommended, BYOK)
+
+Pro adds the things a deterministic local engine cannot do on its own. Full
+tier matrix in [`TIER_DEFINITIONS.md`](./TIER_DEFINITIONS.md). Current pricing
+at **https://sunaivacore.io/pricing** (canonical source of truth across all
+Sunaiva Core products).
+
+- **68 additional premium rules** (100 total) evaluated server-side via the
+  premium backend at `https://mcp.sunaivacore.io/v1/gatehooks`. Detection
+  patterns are proprietary and stay in our infrastructure.
+- **Signed Ship-Confidence verdicts** — HMAC-SHA256, 60-minute freshness
+  window. The `ship_confidence_check` MCP tool verifies the signature in
+  constant time and returns `allowed: true` only when the verdict is
+  `GREEN`, fresh, and untampered.
+- **`sunaiva-ship-confidence` skill integration** — three independent
+  verification layers (cross-provider spec verification, property-based
+  testing with Hypothesis, adversarial audit via garak + DeepTeam) that
+  emit signed verdicts the Gate honours automatically in CI.
+- **Dashboard** — rules tab, audit tab, settings tab, billing tab. Cloud
+  audit sync with 90-day retention.
+- **BYOK** — bring your own `ANTHROPIC_API_KEY` and `OPENROUTER_API_KEY`.
+  You pay your own inference bill. We never see your tokens.
+- **Email support** — `support@sunaiva.ai`, 2-business-day SLA
+  target.
+- **Stripe-managed billing** with the founders coupon `KINANFOUNDER2026`
+  (100% off, first 10 redemptions, per Rule 30).
+
+Enterprise (SSO, on-prem, multi-tenant org dashboard, named CSM) is
+quote-to-cash — see the [Enterprise tier in `TIER_DEFINITIONS.md`](./TIER_DEFINITIONS.md#enterprise--contact-sales).
+
+---
+
+## Architecture
+
+```
+┌────────────────────────────────────────────────────────────────┐
+│  Your project (Claude Code / Cursor / Windsurf / Cline)        │
+│                                                                │
+│   ┌──────────────────────────────────────────────────────┐    │
+│   │  MCP client invokes a tool                            │    │
+│   │     e.g. Bash("git push origin main")                 │    │
+│   └────────────────────────┬─────────────────────────────┘    │
+└────────────────────────────┼───────────────────────────────────┘
+                             ▼
+┌────────────────────────────────────────────────────────────────┐
+│  @sunaiva/gate  (MCP server, stdio transport)                  │
+│                                                                │
+│   ┌──────────────────────────────────────────────────────┐    │
+│   │  validate_action                                      │    │
+│   │     │                                                  │    │
+│   │     ├─►  Constitutional rules (32) — pattern matched  │    │
+│   │     │     LOCALLY against dist/rules/rules.json       │    │
+│   │     │     ─────────────────────────────► block/warn   │    │
+│   │     │                                                  │    │
+│   │     └─►  Premium rules (68) — only if backend set      │    │
+│   │            POST https://mcp.sunaivacore.io/v1/gatehooks   │    │
+│   │            (JWT auth via SUNAIVA_GATE_API_TOKEN)       │    │
+│   │            ─────────────────────────────► block/warn   │    │
+│   │            (fail-OPEN per-rule on backend error)       │    │
+│   └──────────────────────────────────────────────────────┘    │
+│                                                                │
+│   audit log ─►  ~/.sunaiva/audit/audit.jsonl                  │
+└────────────────────────────────────────────────────────────────┘
+```
+
+The Free tier path (constitutional rules) has zero network dependencies. The
+Pro path is opt-in — set `SUNAIVA_GATE_BACKEND_URL` and the engine starts
+POSTing actions to the backend for the premium-rule subset; without it, those
+rules are skipped (recorded as `skipped_premium` in the audit, surfaced once
+per session as a stderr notice).
+
+---
+
+## MCP configuration
+
+Add to your client's MCP settings:
+
+```json
+{
+  "mcpServers": {
+    "sunaiva-gate": {
+      "command": "npx",
+      "args": ["@sunaiva/gate"]
+    }
+  }
+}
+```
+
+Restart your MCP client. The first tool call will trigger the gate.
+
+---
+
+## MCP tool reference
+
+| Tool | What it does |
+|------|--------------|
+| `validate_action` | Check a proposed action against all active rules. Returns `{allowed, violations[], warnings[], skipped_premium[], dry_run?, would_have_blocked?, stamp}`. The workhorse — every PreToolUse hook calls this. |
+| `log_bypass` | Record an intentional rule bypass for the audit log. **Rejects constitutional rules** with a structured `CONSTITUTIONAL_RULE_CANNOT_BE_BYPASSED` error. |
+| `get_rules` | List active rules; supports filtering by `category` or `preset`. |
+| `update_rules` | Enable / disable rules. **Rejects disable attempts against constitutional rules** with a structured `CONSTITUTIONAL_RULE_IMMUTABLE` error. |
+| `get_audit_log` | Return recent gate decisions from `~/.sunaiva/audit/audit.jsonl` with `tier`, `audit_status`, `evidence`, `event_type` fields. |
+| `ship_confidence_check` | **Paid-tier production-deploy gate.** Accepts a signed verdict path or artifact ID; verifies HMAC-SHA256 against `SHIP_CONFIDENCE_SIGNING_KEY`; returns `{allowed, tier: "paid"\|"free", reason, evidence}`. Tagged in the audit ledger so you can measure the free-→paid upgrade funnel. |
+
+Total: **6 MCP tools**. The `ship_confidence_check` tool is the ported
+TypeScript implementation of `.claude/hooks/ship_confidence_gate.py` v1.2.0,
+byte-compatible with the Python skill's canonical-JSON HMAC format.
+
+---
+
+## Environment variables
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `DISABLE_SUNAIVA_GATE` | unset | Set to `1` to short-circuit every `validate_action` to `allowed: true`. Unconditionally logs to stderr. |
+| `SUNAIVA_GATE_DRY_RUN` | unset | Set to `1` to evaluate rules normally but never block. Response includes `dry_run: true` and `would_have_blocked: [...]`. |
+| `SUNAIVA_GATE_BACKEND_URL` | unset | Premium backend endpoint. Default for Pro customers: `https://mcp.sunaivacore.io/v1/gatehooks`. When unset, premium rules are skipped (recorded as `skipped_premium`). |
+| `SUNAIVA_GATE_API_TOKEN` | unset | Bearer token (JWT) for the premium backend. Required when `SUNAIVA_GATE_BACKEND_URL` is set. |
+| `SUNAIVA_GATE_BACKEND_TIMEOUT_MS` | `3000` | Backend request timeout. Backend errors fail-OPEN per-rule (logged as `skipped_premium_backend_error`). |
+| `SUNAIVA_GATE_FAIL_OPEN_ON_ERROR` | unset | Set to `1` to restore the 1.0.x fail-open behaviour on uncaught exceptions and malformed input. Default is fail-CLOSED. |
+| `SHIP_CONFIDENCE_SIGNING_KEY` | unset | HMAC-SHA256 key for verifying signed `sunaiva-ship-confidence` verdicts. Required by the `ship_confidence_check` tool. |
+| `SUNAIVA_GATE_AUDIT_PATH` | `~/.sunaiva/audit/audit.jsonl` | Override the audit log path. |
+
+---
+
+## Exit codes
+
+| Code | Meaning |
+|------|---------|
+| `0`  | Allow / success / smoke-test HEALTHY |
+| `1`  | Generic test failure (legacy `--test` flag, smoke-test DEGRADED) |
+| `2`  | Block (Claude Code convention) |
+| `3`  | Fail-CLOSED internal error (uncaught exception). Opt-in fail-open via `SUNAIVA_GATE_FAIL_OPEN_ON_ERROR=1`. |
+| `4`  | Fail-CLOSED invalid input (malformed JSON, empty stdin). Same opt-in escape hatch. |
+| `5`  | Smoke-test DEGRADED with missing required files (e.g. `dist/rules/rules.json` absent). |
+
+---
+
+## Killing the gate (and why we tell you how)
+
+`@sunaiva/gate` discloses its kill-switch in every block and warn message:
+
+```
+[sunaiva-gate v1.1.0] BLOCK — rule: dat-001 (recursive root deletion)
+Escape: export DISABLE_SUNAIVA_GATE=1
+Audit: ~/.sunaiva/audit/audit.jsonl
+```
+
+The escape hint is a deliberate security-disclosure design. An enforcement
+product that hides its own bypass is one that gets routed around in production
+without anyone knowing. The kill-switch invocation is itself logged to the
+audit ledger as `decision: 'bypass_kill_switch'`, so disabling the gate is
+visible to anyone who reads the audit.
+
+```bash
+export DISABLE_SUNAIVA_GATE=1   # All actions allowed (logged)
+unset DISABLE_SUNAIVA_GATE      # Back to normal enforcement
+```
+
+Use dry-run instead of the kill-switch when you want to *measure* what the
+gate would block without actually blocking anything:
+
+```bash
+export SUNAIVA_GATE_DRY_RUN=1
+# → response.dry_run: true
+# → response.would_have_blocked: [{rule_id, name, severity}, ...]
+```
+
+---
+
+## Decision model — warn-then-block escalation
+
+Constitutional rules block on the first match. Standard rules (the
+non-constitutional subset) implement a session-state escalation:
+
+- **First match in a session** → `warn` (action allowed, message printed).
+- **Subsequent matches in the same session** → `block`.
+
+This avoids one-time false-positive noise while still catching repeated
+violations. The session counter is reset when the MCP server process restarts.
+Confidence is derived from keyword-count thresholds: `≥3` keywords matched →
+`high`, `1-2` → `medium`, `0` → `low` (low confidence is filtered out before
+the response).
+
+---
+
+## Smoke test
+
+```bash
+$ npx @sunaiva/gate --smoke-test
+✓ Gate loaded — 100 rules
+✓ Constitutional rules — 32 (cannot be disabled, enforced locally)
+✓ Premium rules — 68 (require backend service)
+✓ Presets file — 5 presets available
+✓ Live eval (git push origin main) — HARD block via gov-001
+✓ Live eval (ls -la) — ALLOW
+✓ Live eval (rm -rf /) — HARD block via dat-001
+✓ Live eval (stripe.charges.create) — HARD block via fin-001
+✓ Immutability guard — ACTIVE (32 constitutional rules pinned)
+✓ MCP server — ready (not started in smoke test)
+Status: HEALTHY
+Version: 1.1.1
+Support: support@sunaiva.ai
+```
+
+Exit codes: `0` = HEALTHY, `1` = DEGRADED, `5` = missing required files.
+
+---
+
+## Presets
+
+`get_rules` accepts a `preset` argument that filters the active set:
+
+| Preset | Rules | Use case |
+|--------|-------|----------|
+| `minimal` | 5 | Absolute non-negotiables only |
+| `essential` | 15 | Recommended starting point |
+| `developer-safety` | 25 | AI coding agents (Cursor / Windsurf / Cline / Aider) |
+| `financial-protection` | 24 | All financial + resource rules |
+| `full-suite` | 100 | Everything — Free constitutional set + Pro premium set |
+
+Presets read from `dist/rules/presets.json`. Premium presets require
+`SUNAIVA_GATE_BACKEND_URL` to be set; without it the premium rules are skipped
+with a `skipped_premium` audit entry.
+
+---
+
+## Ship Confidence Gate (paid tier)
+
+The `ship_confidence_check` MCP tool is the deploy-time gate for high-blast-
+radius commands (`npm publish`, `wrangler deploy`, `gh repo create --public`,
+`netlify deploy --prod`). It checks for authorization in two tiers:
+
+### Paid path — signed verdict
+1. The `sunaiva-ship-confidence` Python skill runs three verification layers
+   against your product (spec verification, property-based testing,
+   adversarial audit).
+2. It emits a signed verdict at
+   `data/ship_confidence_verdicts/<artifact>.signed.json`.
+3. The `ship_confidence_check` tool verifies:
+   - HMAC-SHA256 signature is valid (constant-time compare, byte-compatible
+     with the Python skill's canonical-JSON encoding).
+   - `level == "GREEN"` (YELLOW and RED hard-block).
+   - Signed within the last 60 minutes
+     (configurable via `VERDICT_MAX_AGE_MINUTES`).
+4. On all-pass: returns `{allowed: true, tier: "paid", ...}` and writes an
+   audit entry tagged `tier: "paid"` with the verdict ID and evidence.
+
+### Free fallback — approval token
+If no signed verdict is found (or `SHIP_CONFIDENCE_SIGNING_KEY` is not set),
+the tool falls back to a one-time approval token at
+`data/deploy_queue/APPROVAL_TOKENS/<artifact>.json` written within the last
+hour. Tagged `tier: "free"` in the audit ledger with an upgrade hint pointing
+at the paid skill.
+
+```bash
+# CLI form for use in CI:
+npx @sunaiva/gate --ship-confidence @sunaiva/gate@1.1.0
+# Exit 0 = allow, 2 = block, 3 = internal error (fail-OPEN logged)
+```
+
+---
+
+## Constitutional rules cannot be disabled or bypassed
+
+This is the package's hard guarantee. The 32 constitutional rules are
+re-merged into `active_rules` on every config load — even if
+`~/.sunaiva/gate-config.json` is hand-edited to remove them — and:
+
+- `update_rules({disable: ['fin-001']})` returns
+  `{error: "CONSTITUTIONAL_RULE_IMMUTABLE", rule_ids: [...]}`. No state
+  change.
+- `log_bypass({rule_id: 'fin-001'})` returns
+  `{error: "CONSTITUTIONAL_RULE_CANNOT_BE_BYPASSED", rule_id: ...}`. Nothing
+  written to the bypass log.
+
+The kill-switch (`DISABLE_SUNAIVA_GATE=1`) is the only way to disable
+constitutional enforcement, and it is loud — stderr disclosure on every
+block, audit-ledger entry on every short-circuit. There are no quiet
+bypasses.
+
+---
+
+## Known limitations — what 1.1.0 does NOT have
+
+We shipped `1.0.1` with seven CRITICAL gaps flagged by our own signed
+Ship-Confidence verdict on our own commit (`01KRDBCEYF2CAB21G6Y3E9VVH5`, RED).
+1.1.0 closes all seven. What is honestly **not** in 1.1.0 yet:
+
+- **Sunaiva-Managed inference** — no flat-fee tier that includes LLM calls.
+  BYOK only in v1. Revisit at 50+ Pro customers.
+- **UI verification layer** (Playwright walkthroughs / computer-use) —
+  designed in
+  `data/ship_confidence_skill_upgrade_2026_05_11.md`, not yet shipped.
+  Folded into Pro at no extra cost when it lands.
+- **Multi-tenant dashboard / "Pro Team" tier** — Pro is single-seat in v1.
+  Team management is Enterprise. A self-serve "Pro Team" tier waits until
+  10+ customers ask for it.
+- **On-prem / VPC deployment** — Enterprise-only roadmap item. Helm chart
+  and Terraform module designs exist; not yet packaged.
+- **Per-call / metered pricing** — abandoned. Subscription wins.
+- **On-chain attestation (ERC-8004)** — aspirational. Deferred to v2.x.
+
+Full deferred-feature list: see `STRATEGIC_PRIORITIES.md` Phase 3
+(in-repo, not shipped in the tarball — internal-facing roadmap).
+
+---
+
+## Cross-platform
+
+- **Linux** — native.
+- **WSL** — native.
+- **macOS** — native.
+- **Windows** — native Node, plus a Python shim for clients that invoke the
+  legacy `hooks/sunaiva_gate_hook.py` PreToolUse path.
+
+---
+
+## Privacy
+
+Your data stays where you choose. The Free tier makes **zero** external network
+calls — constitutional rules are evaluated locally against patterns shipped
+inside the package. The Pro path is opt-in: when you set
+`SUNAIVA_GATE_BACKEND_URL`, the engine POSTs only the proposed action text
+and rule IDs to the backend; we never see your code, your secrets, or your
+filesystem. BYOK means your `ANTHROPIC_API_KEY` and `OPENROUTER_API_KEY` go
+direct from your machine to those providers — they do not transit Sunaiva.
+
+---
+
+## License
+
+[BUSL-1.1](./BUSINESS_LICENSE.md) — free for evaluation, internal development,
+hobby and academic use. Commercial license required if you embed the Gate in
+the critical path of a third-party paying-customer product before the
+**Change Date of 2030-05-10**, after which the wrapper converts to
+**Apache-2.0** automatically. The premium backend stays proprietary regardless
+of the Change Date.
+
+- Licensor: Sunaiva Digital
+- Change Date: **2030-05-10**
+- Change License: **Apache License, Version 2.0**
+
+---
+
+## Support
+
+| Need | Where |
+|------|-------|
+| Bug or crash | Email `support@sunaiva.ai` with `--smoke-test` output + `node --version` |
+| Feature request | Email `support@sunaiva.ai` with subject `[feature-request]` |
+| Security vulnerability | Email `support@sunaiva.ai` (do not file publicly) |
+| Licensing | `support@sunaiva.ai` |
+| Commercial / paid tier | `support@sunaiva.ai` |
+| Product page | `https://sunaivacore.io/products/gate` |
+
+When reporting bugs, include the output of `npx @sunaiva/gate --smoke-test`
+and `node --version`.
+
+---
+
+## Contributing
+
+Pull requests welcome. For substantial changes, please open an issue first to
+discuss the proposal. Constitutional rule additions require a corresponding
+test fixture in `tests/bundle.test.ts` and a passing dogfood Ship-Confidence
+verdict on the change.
+
+---
+
+*Built by a team whose own hooks killed their development for nine hours.
+We fixed it. Then we shipped the fix. Then we signed the proof.*