@shomra/agent 0.3.17 → 0.3.18

package/NOTICE

@@ -7,4 +7,4 @@ Licensed under the Apache License, Version 2.0. See the LICENSE file for the
 full terms.
 
 The detection rules, signatures, and analyzers in this package are intended for
-authorized security use — scanning your own AI artifacts, code, and machines.
+authorized security use - scanning your own AI artifacts, code, and machines.

package/README.md

@@ -2,13 +2,13 @@
 
 **Adversarial assurance for AI agents**, as a local-first CLI. It sits inside
 your coding agent and CI and blocks dangerous tool-calls, shell commands and
-data exfiltration *before they run* — on your machine, even offline. Enrolled,
+data exfiltration *before they run* - on your machine, even offline. Enrolled,
 it also attacks your org’s own guardrails (`shomra admin redteam`) and turns
 each breach into a false-positive-gated control (`shomra harden`). It also vets AI
 artifacts (MCP configs, Skills, slash commands, hooks, rules files) before they
-install. Start with a free on-machine scan — no signup.
+install. Start with a free on-machine scan - no signup.
 
-Zero dependencies — Node ≥ 18 built-ins only.
+Zero dependencies - Node ≥ 18 built-ins only.
 
 ## Install
 
@@ -29,22 +29,22 @@ npx @shomra/agent gate .mcp.json
 
 ## Auth (optional)
 
-Shomra is **local-first** — there is no built-in backend and no telemetry. `gate`,
+Shomra is **local-first** - there is no built-in backend and no telemetry. `gate`,
 `check`, `models`, `secrets`, and the runtime firewall all run fully on your
 machine with no key and no network. You only connect to a Shomra org to layer on
 your **org policy**, cloud/deep scans, AI fixes, and the Model Security Index.
 
 - **Dev machine:** `shomra init --key shm_live_… --url https://shomra.your-co.com` (writes `~/.shomra/config.json`).
-- **CI / headless:** set env vars instead — no `init` needed:
-  - `SHOMRA_API_KEY` — your org key
-  - `SHOMRA_URL` — your backend URL
+- **CI / headless:** set env vars instead - no `init` needed:
+  - `SHOMRA_API_KEY` - your org key
+  - `SHOMRA_URL` - your backend URL
 
 Without either, every backend-only feature degrades cleanly to the on-machine result.
 
 ## Quickstart
 
 ```bash
-shomra check                           # "is my repo safe?" — gate every AI artifact at once
+shomra check                           # "is my repo safe?" - gate every AI artifact at once
 shomra check --staged                  # only what's git-staged (pre-commit / editor-on-save)
 shomra check --fix                     # gate, then remediate what isn't clean, in place
 shomra fix .mcp.json --apply           # AI-fix one artifact and write it back
@@ -58,17 +58,17 @@ shomra status                          # config + firewall health
 shomra help                            # full command list
 ```
 
-`check`, `fix` and `why` are the verbs a developer lives in — everything below is
+`check`, `fix` and `why` are the verbs a developer lives in - everything below is
 CI, governance, or one-time setup. Findings carry a **file:line**, so `check --json`
 drives precise editor squiggles and `why`/`fix` point at the exact offending line.
 
 - **`check`** is the developer front door: it finds every AI artifact in the tree
   (MCP configs, Skills, slash commands, hooks, rules files) and gates them in one
-  shot, **local-first** — a real on-machine verdict with no backend or key, org
+  shot, **local-first** - a real on-machine verdict with no backend or key, org
   policy layered on when enrolled. It's `gate --all` with dev ergonomics
   (`--staged` / `--changed` scoping, `--fix`, clean `--json` for an IDE extension).
 - **`fix`** generates a minimal fix for what the gate flags and (with `--apply`)
-  writes it back to your working tree — the fix is produced on the platform with
+  writes it back to your working tree - the fix is produced on the platform with
   your org's AI key, so no provider key sits on the dev machine. Nothing is
   committed or pushed. Without AI on the server it prints deterministic guidance.
 
@@ -87,7 +87,7 @@ shomra new agent triage-bot            # a project that starts compliant
 
 Guard enforcing on every model call, an egress allowlist in code rather than in
 the prompt, untrusted input kept out of the system prompt, secrets referenced
-from the environment, and the gate wired into CI — from commit zero. Remediating
+from the environment, and the gate wired into CI - from commit zero. Remediating
 a project into this shape later means changing decisions that have already been
 built on.
 
@@ -104,23 +104,23 @@ on top.
 | Code | Meaning |
 |------|---------|
 | `0` | clean / pass |
-| `1` | hard fail — BLOCK, vulnerable model, secret found, FAIL verdict, below `--min`, regression (also `--strict` + backend outage) |
-| `2` | soft fail — FLAG under `--strict` (REVIEW when strict) |
-| `3` | usage / config error — not configured, bad flags, unknown command |
+| `1` | hard fail - BLOCK, vulnerable model, secret found, FAIL verdict, below `--min`, regression (also `--strict` + backend outage) |
+| `2` | soft fail - FLAG under `--strict` (REVIEW when strict) |
+| `3` | usage / config error - not configured, bad flags, unknown command |
 
 **Backend outage:** by default it falls back to the on-machine verdict (org
 policy not applied). `--strict` fails closed (exit 1) because org policy can't be
 verified. Every backend call is bounded by `SHOMRA_API_TIMEOUT_MS` (default 30s),
 so a job never hangs.
 
-### GitHub Actions — the reusable action
+### GitHub Actions - the reusable action
 
 ```yaml
 - uses: actions/checkout@v4
 - uses: shomra-org/agent@v0
   with:
     args: check           # --strict is appended unless fail-on-flag: 'false'
-    api-key: ${{ secrets.SHOMRA_API_KEY }}   # optional — the gate is local-first
+    api-key: ${{ secrets.SHOMRA_API_KEY }}   # optional - the gate is local-first
     url: ${{ secrets.SHOMRA_URL }}
 ```
 
@@ -131,7 +131,7 @@ self-hosted Git and GitHub Enterprise, `shomra install-precommit --pre-receive`
 
 The hand-written workflow below still works and shows what the action does.
 
-### GitHub Actions — by hand
+### GitHub Actions - by hand
 
 ```yaml
 name: Shomra AI-artifact gate
@@ -153,11 +153,11 @@ jobs:
 CI provider, repo, branch and commit are auto-detected and recorded, so security
 sees local-vs-CI gate activity in the dashboard.
 
-### GitHub PR reviewer — inline annotations (`shomra pr`)
+### GitHub PR reviewer - inline annotations (`shomra pr`)
 
 `shomra pr` is a richer PR-native path: on a `pull_request` it gates only the AI
 artifacts **changed vs the base branch** and posts a **GitHub Check Run with
-inline annotations** on the offending lines — no GitHub App or extra backend
+inline annotations** on the offending lines - no GitHub App or extra backend
 required, just the workflow's `GITHUB_TOKEN`. Scaffold it in one shot:
 
 ```bash
@@ -183,8 +183,8 @@ jobs:
       - run: npx @shomra/agent pr
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          SHOMRA_API_KEY: ${{ secrets.SHOMRA_API_KEY }}   # optional — applies org policy
-          SHOMRA_URL: ${{ secrets.SHOMRA_URL }}           # optional — your backend
+          SHOMRA_API_KEY: ${{ secrets.SHOMRA_API_KEY }}   # optional - applies org policy
+          SHOMRA_URL: ${{ secrets.SHOMRA_URL }}           # optional - your backend
 ```
 
 The check-run **conclusion** mirrors the gate: `failure` on any BLOCK, `neutral`
@@ -192,7 +192,7 @@ on FLAG (or `failure` with `--strict`), `success` when clean. `--dry-run`/`--jso
 print the computed check-run without posting. Without `SHOMRA_API_KEY` it still
 runs local-first; with a key, your **org policy** (below) drives the verdict.
 
-### SARIF — native code-scanning annotations
+### SARIF - native code-scanning annotations
 
 `gate`/`gate --all`/`check` accept `--sarif` to emit SARIF 2.1.0, which GitHub
 (and GitLab) render as inline code-scanning annotations without a custom parser:
@@ -210,14 +210,14 @@ runs local-first; with a key, your **org policy** (below) drives the verdict.
 
 When enrolled, the same **org policy** that governs the dashboard decides the CI
 verdict (worst-wins across your org + project rules), so a build blocks on the
-policies you defined — not just a fixed severity threshold. Two things follow:
+policies you defined - not just a fixed severity threshold. Two things follow:
 
 - **Findings you've triaged away don't re-block the build.** If a security owner
   has **accepted the risk** or **ignored** a finding in the platform, the gate
   records the policy hit for transparency but no longer counts it toward
   BLOCK/FLAG. Matching is per file+line and survives across scan sources, and an
   accepted-risk that has **expired** re-blocks automatically.
-- **Mandatory guardrails are exempt** — a finding that trips a policy marked
+- **Mandatory guardrails are exempt** - a finding that trips a policy marked
   *mandatory* still blocks even if someone accepted the risk. Use a policy
   exception for those.
 
@@ -244,12 +244,12 @@ A pre-commit hook is a courtesy: it lives on the developer's machine, it is one
 at all. A pre-receive hook runs on the **server**, on every push, for every
 developer. Same check; the difference between a reminder and a control.
 
-It **fails closed** — the opposite of the client hook. Blocking a local commit
+It **fails closed** - the opposite of the client hook. Blocking a local commit
 because a binary is missing is hostile; waving a push through for the same reason
 makes deleting the binary the bypass.
 
 Available on self-hosted Git (GitLab, Gitea, Bitbucket DC, plain bare repos) and
-GitHub Enterprise. GitHub.com does not run server-side hooks — use the action as
+GitHub Enterprise. GitHub.com does not run server-side hooks - use the action as
 a required status check instead.
 
 ### pre-commit (local, blocks risky artifacts before they land)
@@ -274,7 +274,7 @@ Add `--json` anywhere to get machine-readable output for custom reporting.
 wires Shomra into a coding agent's own hooks. It is **tiered**: catastrophic tool
 calls (`curl|sh`, reverse shells, base64 RCE, live secrets, injection) are
 blocked on-machine with zero network; only policy-relevant calls escalate to the
-backend, behind a short timeout + circuit breaker — so a slow or down backend
+backend, behind a short timeout + circuit breaker - so a slow or down backend
 never freezes the agent. Fail-open by default; `SHOMRA_GUARD_STRICT=1` fails
 closed on the server tier.
 
@@ -285,12 +285,12 @@ Three channels are screened:
 | **Tool call** | PreToolUse / `beforeShellExecution` | the shell command, artifact write or MCP call, before it runs |
 | **Tool result** | PostToolUse / `afterMCPExecution` | injection, exfil sinks and hidden payloads in what a fetch/read brings *back* |
 | **Prompt** | `UserPromptSubmit` (Claude Code) / `beforeSubmitPrompt` (Cursor) | what **you** paste, before it leaves the machine |
-| **Plan** | `PreToolUse` on `ExitPlanMode` (Claude Code) | nothing — it *informs*. See [`shomra plan`](#shomra-plan--threat-model-what-the-agent-is-about-to-build) |
+| **Plan** | `PreToolUse` on `ExitPlanMode` (Claude Code) | nothing - it *informs*. See [`shomra plan`](#shomra-plan--threat-model-what-the-agent-is-about-to-build) |
 
 The prompt channel is the one a person controls, and the only one where the leak
 is a paste rather than a tool call. A live credential in a prompt is refused;
 pasted text that reads as an instruction to an agent is passed through but
-flagged **to the model** as untrusted data rather than blocked — you meant to
+flagged **to the model** as untrusted data rather than blocked - you meant to
 send it, the risk is that you did not read it. Backtick-quoted payloads are
 down-ranked, so asking *why does `<pattern>` get flagged* is never blocked.
 `SHOMRA_PROMPT_GUARD_OFF=1` disables just this channel. Only the two vendors with
@@ -310,10 +310,10 @@ shomra rules --check       # CI: fail when the block goes stale
 shomra mcp install         # let the agent gate its own content before writing it
 ```
 
-### `shomra design` — threat-model the ticket, not the repo
+### `shomra design` - threat-model the ticket, not the repo
 
-Every other command needs an artifact. This one reads a **description** — an RFC,
-a design doc, a Jira/Linear ticket, a PR body — and answers the only question
+Every other command needs an artifact. This one reads a **description** - an RFC,
+a design doc, a Jira/Linear ticket, a PR body - and answers the only question
 worth asking before anyone writes code: does the thing being described hand an
 attacker a path from untrusted input to a consequence?
 
@@ -327,7 +327,7 @@ shomra design docs/rfc-042.md --checklist | gh issue comment 42 -F -
 It uses the platform's own model: capabilities split into **sources** (untrusted
 input, sensitive data, filesystem) and **sinks** (network egress, execution,
 destructive action). A closed source→sink pair is an attack path. That model does
-not care whether the capabilities came from a scan or from a sentence — here they
+not care whether the capabilities came from a scan or from a sentence - here they
 come from a sentence, and each one cites the line that evidenced it so you can
 disagree with the machine's reading.
 
@@ -336,7 +336,7 @@ anyone actually acts on: paste it into the ticket as acceptance criteria.
 
 > **It reads prose, so it sees only what was written down.** There is deliberately
 > no clean verdict. `NOT_DESCRIBED` means the document did not describe
-> capabilities in a way this matched — it is **not** a statement that the system
+> capabilities in a way this matched - it is **not** a statement that the system
 > has none. A threat model that reads as a clean bill of health is worse than
 > none, because it is consumed exactly when the design is still cheap to change.
 
@@ -344,7 +344,7 @@ Exit codes: `1` when untrusted input reaches execution or a destructive action
 (the shape where the attacker picks the action), `2` for any other closed path
 under `--strict`.
 
-### `shomra plan` — threat-model what the agent is about to build
+### `shomra plan` - threat-model what the agent is about to build
 
 `design` reads a document a human remembered to write. Coding agents produce a
 **plan** before every non-trivial task, constantly and automatically, and nothing
@@ -357,11 +357,11 @@ refuse it three tool calls later.
 
 Three ways in, deliberately redundant, strongest first:
 
-1. **`shomra_review_plan`** — an MCP tool, so any MCP-capable agent can call it
+1. **`shomra_review_plan`** - an MCP tool, so any MCP-capable agent can call it
    mid-task with no vendor hook. Register it with `shomra mcp install`.
 2. **The rules block asks the agent to call it.** Once the MCP server is
    registered, `shomra rules --write` adds a *Before you implement a plan*
-   section — so `mcp install` and `rules --write` compose into a closed loop.
+   section - so `mcp install` and `rules --write` compose into a closed loop.
 3. **A Claude Code `PreToolUse` hook on `ExitPlanMode`**, wired by
    `install-hook`. Zero-effort, but that tool name is not in the published hook
    docs, so it is the optional path and never the only one.
@@ -371,22 +371,22 @@ shomra plan plan.md            # or: … | shomra plan -
 ```
 
 **A plan is a proposal, so the default is to inform, never refuse.** Denying a
-plan spends a turn and tells the model only that it was wrong, not how — the
+plan spends a turn and tells the model only that it was wrong, not how - the
 controls are the useful payload. Only untrusted-input-reaches-a-hard-sink
 escalates to *ask*, and only under `SHOMRA_GUARD_STRICT=1`.
 `SHOMRA_PLAN_GUARD_OFF=1` disables just this channel.
 
-### `shomra corpus` — screen the index, not the retrieval
+### `shomra corpus` - screen the index, not the retrieval
 
 The result firewall screens what a retrieval brings *back*. Nothing screened what
-went **in** — so a poisoned document sits in the vector store indefinitely,
+went **in** - so a poisoned document sits in the vector store indefinitely,
 clean-until-retrieved, and is judged for the first time at the worst possible
 moment: as one chunk, stripped of its document, inside a request a user is
 waiting on.
 
 Index time wins on all three counts. The whole document is present, so a payload
 split across paragraphs is visible. The cost is paid once per document instead of
-once per retrieval. And a document that fails is simply never embedded — a
+once per retrieval. And a document that fails is simply never embedded - a
 control rather than a detection.
 
 ```bash
@@ -398,8 +398,8 @@ shomra corpus ./kb --manifest .shomra/corpus.json
     HIGH     Injected instruction: "ignore all previous" (line 243 · chunk 19)
   ✗ QUARANTINE hidden.md
     CRITICAL Invisible / bidirectional characters
-  ⚠ 2 files could not be read — they are NOT covered by the result above:
-      2 × binary format — no text extractor
+  ⚠ 2 files could not be read - they are NOT covered by the result above:
+      2 × binary format - no text extractor
 ```
 
 Findings carry the **chunk index**, not just the line, because retrieval returns
@@ -408,16 +408,16 @@ point of the command: feed it to your ingestion job so a quarantined document is
 never embedded.
 
 > **Absence accounting is load-bearing.** Real corpora are mostly PDF, DOCX and
-> PPTX — formats this cannot read. A screen that silently skips them and prints
+> PPTX - formats this cannot read. A screen that silently skips them and prints
 > "clean" is a lie about the majority of the corpus, so every unreadable file is
 > counted and reported next to the verdict, and `--strict` fails on them:
 > *we could not check it* is not *it is fine*.
 
-Fenced code blocks are down-ranked — a docs corpus is full of examples, and an
+Fenced code blocks are down-ranked - a docs corpus is full of examples, and an
 example is not a live instruction. A directive in prose is the real threat and
 survives the down-rank.
 
-### `shomra add` — vet at acquisition, not after
+### `shomra add` - vet at acquisition, not after
 
 `mcp add` gated one channel. An agent acquires from four, and the other three had
 no gate at all: a skill copied out of a gist, a model pulled from the Hub, a
@@ -436,11 +436,11 @@ the question changes from *should we take this?* to *is it safe to remove?*,
 which is a much worse question to be asked.
 
 **Unknown is never clean.** An unreachable Model Index, an unscanned model, and a
-package the AI catalog does not recognise all return **FLAG**, not ALLOW —
+package the AI catalog does not recognise all return **FLAG**, not ALLOW -
 "we could not check" and "it is fine" are different answers.
 
-**`shomra rules`** compiles what Shomra actually enforces — plus what *this repo*
-already trips, plus your org's policy when enrolled — into the agent's own
+**`shomra rules`** compiles what Shomra actually enforces - plus what *this repo*
+already trips, plus your org's policy when enrolled - into the agent's own
 context files:
 
 | Agent | File |
@@ -465,7 +465,7 @@ The generated block is itself an AI rules file, so `shomra rules` gates its own
 output and refuses to write anything its own checker would block.
 
 **`shomra mcp install`** registers Shomra *as* an MCP server with your agents, so
-the model can call it in its own loop — most usefully `shomra_review_change`,
+the model can call it in its own loop - most usefully `shomra_review_change`,
 which takes proposed file content plus its intended path and returns a verdict
 **without writing anything to disk**. A BLOCK there costs nothing; the same
 content on disk costs a blocked tool call and a wasted turn. `shomra_rules`,
@@ -476,21 +476,21 @@ prefer to wire it by hand.
 ## Adopting Shomra on an existing repo
 
 A brand-new gate on a repo with history will flag things. Three layers make
-adoption friction-free — all of them re-grade the artifact, so a fully
+adoption friction-free - all of them re-grade the artifact, so a fully
 suppressed file drops to ALLOW and never fails the build:
 
 - **`shomra baseline`** records every current finding (line-independent
-  fingerprints) in `.shomra/baseline.json` — commit it so the whole team shares
+  fingerprints) in `.shomra/baseline.json` - commit it so the whole team shares
   it. From then on only findings introduced *after* the baseline fail; re-run it
   to refresh after cleanups. Skip it per-run with `--no-baseline`.
-- **`.shomraignore`** — a repo file of `path/glob` lines (skip the file) or
+- **`.shomraignore`** - a repo file of `path/glob` lines (skip the file) or
   `path/glob :: title-substring` lines (skip one finding class in those files).
   The runtime firewall honors it too, so test fixtures and detection source
   aren't withheld. Silence a single finding inline with `// shomra-ignore` (or
   `# shomra-ignore`) on the finding's line or the line above, or opt a whole
   file out with `shomra-ignore-file` in its first lines (works in JSON as a
   `"_shomra": "shomra-ignore-file"` key). `--no-suppress` ignores all of this.
-- **`.shomra/policy.yml`** — policy-as-code, reviewed in PRs like any code:
+- **`.shomra/policy.yml`** - policy-as-code, reviewed in PRs like any code:
 
   ```yaml
   block: high              # min severity that BLOCKS (critical|high|medium|low|none)
@@ -500,7 +500,7 @@ suppressed file drops to ALLOW and never fails the build:
   ```
 
   For a local verdict the repo policy fully re-grades; when the backend
-  returned an org decision it can only make it *stricter* (worst-wins) — repo
+  returned an org decision it can only make it *stricter* (worst-wins) - repo
   config never loosens org enforcement. `--no-policy` skips it.
 
 ## Environment variables
@@ -511,7 +511,7 @@ suppressed file drops to ALLOW and never fails the build:
 | `SHOMRA_URL` | Backend URL (overrides config) |
 | `SHOMRA_API_TIMEOUT_MS` | Per-request backend timeout (default 30000) |
 | `SHOMRA_AGENT` | Agent-identity handle presented to `llm-proxy` + firewall |
-| `SHOMRA_GATE_CONCURRENCY` | Parallel backend calls in batch gate / model lookups (default 8, 1–32) |
+| `SHOMRA_GATE_CONCURRENCY` | Parallel backend calls in batch gate / model lookups (default 8, 1-32) |
 | `SHOMRA_GH_TOKEN` | GitHub token for `shomra pr` (falls back to `GITHUB_TOKEN`) |
 | `SHOMRA_GUARD_STRICT` | `1` = firewall fails closed on the server tier |
 | `SHOMRA_GUARD_LOCAL` | `0` = disable the on-machine Tier-0 guard |

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@shomra/agent",
-  "version": "0.3.17",
-  "description": "Shomra — adversarial assurance for AI agents, as a local-first CLI. Blocks dangerous tool-calls before they run, attacks your own guardrails to prove they hold, and gates AI artifacts in your editor and CI.",
+  "version": "0.3.18",
+  "description": "Shomra - adversarial assurance for AI agents, as a local-first CLI. Blocks dangerous tool-calls before they run, attacks your own guardrails to prove they hold, and gates AI artifacts in your editor and CI.",
   "type": "module",
   "bin": {
     "shomra": "./shomra.mjs"
@@ -14,13 +14,7 @@
   },
   "files": [
     "shomra.mjs",
-    "discovery.mjs",
-    "guard-signals.mjs",
-    "guard-ledger.mjs",
-    "code-sast.mjs",
-    "model-refs.mjs",
-    "ai-usage.mjs",
-    "design.mjs",
+    "src",
     "README.md",
     "LICENSE",
     "NOTICE"