@shomra/agent 0.3.1 → 0.3.3

package/README.md

@@ -12,6 +12,15 @@ Zero dependencies — Node ≥ 18 built-ins only.
 
 ## Install
 
+Also available as a [Dev Container Feature](devcontainer-feature/) (the guard
+exists before the first keystroke in Codespaces / Gitpod / a local rebuild) and a
+[GitHub Action](action.yml).
+
+**There is no `curl … | sh` installer, deliberately.** Shomra's own Tier-0 guard
+blocks piping a downloaded script into a shell, and the rules block it writes
+tells coding agents never to do it. Shipping that one-liner would be the product
+contradicting its own control in its own README.
+
 ```bash
 npm i -g @shomra/agent      # global `shomra`
 # or run without installing:
@@ -42,6 +51,8 @@ shomra fix .mcp.json --apply           # AI-fix one artifact and write it back
 shomra why .mcp.json                   # why each finding matters + is-it-a-false-positive
 shomra install-precommit               # block risky staged AI artifacts on git commit
 shomra install-hook --agent claude     # wire the runtime firewall into Claude Code
+shomra rules --write                   # teach the agent what gets blocked, so it never writes it
+shomra mcp install                     # let the agent gate its own content BEFORE writing it
 shomra scan                            # discover AI tooling on this machine
 shomra status                          # config + firewall health
 shomra help                            # full command list
@@ -68,6 +79,18 @@ shomra gate my-skill/SKILL.md          # vet ONE artifact (auto-classified from
 shomra gate --all .                    # vet every AI artifact in the repo (the CI form)
 ```
 
+### Starting a new agent project
+
+```bash
+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
+a project into this shape later means changing decisions that have already been
+built on.
+
 ## `gate` in CI
 
 `gate`/`gate --all` are **local-first**: real static analysis (dangerous shell,
@@ -90,7 +113,25 @@ policy not applied). `--strict` fails closed (exit 1) because org policy can't b
 verified. Every backend call is bounded by `SHOMRA_API_TIMEOUT_MS` (default 30s),
 so a job never hangs.
 
-### GitHub Actions
+### 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
+    url: ${{ secrets.SHOMRA_URL }}
+```
+
+Wire it as a **required status check** on a protected branch and it becomes the
+un-bypassable control on GitHub.com, which has no server-side hooks. On
+self-hosted Git and GitHub Enterprise, `shomra install-precommit --pre-receive`
+(below) refuses the push itself.
+
+The hand-written workflow below still works and shows what the action does.
+
+### GitHub Actions — by hand
 
 ```yaml
 name: Shomra AI-artifact gate
@@ -192,6 +233,25 @@ shomra-gate:
     SHOMRA_URL: $SHOMRA_URL
 ```
 
+### pre-receive (server-side, cannot be skipped)
+
+```bash
+shomra install-precommit --pre-receive /srv/git/your-repo.git
+```
+
+A pre-commit hook is a courtesy: it lives on the developer's machine, it is one
+`--no-verify` away, and a machine that never ran `install-precommit` has no gate
+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
+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
+a required status check instead.
+
 ### pre-commit (local, blocks risky artifacts before they land)
 
 `.git/hooks/pre-commit` (or a [pre-commit](https://pre-commit.com) `local` hook):
@@ -218,6 +278,201 @@ 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.
 
+Three channels are screened:
+
+| Channel | Hook | What it stops |
+|---|---|---|
+| **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) |
+
+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
+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
+a documented pre-submit hook that can stop a submission are wired; the rest get
+nothing rather than a guessed event name that would silently never fire.
+
+## Prevention: get in front of the model
+
+Everything above intercepts *after* the model has written something. These run
+before it.
+
+```bash
+shomra design docs/rfc.md  # threat-model a system that does not exist yet
+shomra add model owner/m   # vet anything before it lands on the machine
+shomra rules --write       # teach the agent what gets blocked here
+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
+
+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?
+
+```bash
+shomra design docs/rfc-042.md
+shomra design docs/ --strict                       # every design doc, fail on any closed path
+gh issue view 42 --json body -q .body | shomra design -
+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
+come from a sentence, and each one cites the line that evidenced it so you can
+disagree with the machine's reading.
+
+`--checklist` emits the conditions as a markdown task list, which is the form
+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
+> 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.
+
+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
+
+`design` reads a document a human remembered to write. Coding agents produce a
+**plan** before every non-trivial task, constantly and automatically, and nothing
+looks at it. Same analysis, a hundred times the frequency, zero human effort.
+
+The loop: agent proposes a plan → Shomra threat-models it → the controls land in
+the agent's context **before it writes line one**. The agent builds the guarded
+version first, instead of building the unguarded one and having the firewall
+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
+   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.
+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.
+
+```bash
+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
+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
+
+The result firewall screens what a retrieval brings *back*. Nothing screened what
+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
+control rather than a detection.
+
+```bash
+shomra corpus ./kb --manifest .shomra/corpus.json
+```
+
+```
+  ✗ QUARANTINE escalation.md
+    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
+```
+
+Findings carry the **chunk index**, not just the line, because retrieval returns
+chunks and the chunk is what actually reaches the model. The manifest is the
+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
+> "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
+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
+
+`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
+package installed because an agent suggested the name.
+
+```bash
+shomra add mcp files npx -y @modelcontextprotocol/server-filesystem /tmp
+shomra add skill ./downloaded-skill      # manifest AND the scripts it bundles
+shomra add model openai-community/gpt2   # against the Model Index, before any weights download
+shomra add package langchian --type pypi # → BLOCK: 2 edits from langchain
+```
+
+One verdict vocabulary (ALLOW / FLAG / BLOCK), one exit-code contract, `--force`
+to override a BLOCK deliberately rather than by accident. After something lands
+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 —
+"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
+context files:
+
+| Agent | File |
+|---|---|
+| Claude Code | `CLAUDE.md` |
+| Codex CLI (and the cross-vendor default) | `AGENTS.md` |
+| Cursor | `.cursor/rules/shomra.mdc` |
+| GitHub Copilot | `.github/copilot-instructions.md` |
+| Gemini CLI | `GEMINI.md` |
+| Windsurf | `.windsurfrules` |
+| Cline | `.clinerules/shomra.md` |
+
+It writes inside a `<!-- BEGIN SHOMRA MANAGED BLOCK -->` marker pair and **never
+touches a line outside it**, so your own rules are safe and re-running is a
+no-op. The block is derived, not boilerplate: sections switch on according to
+what the repo holds (MCP configs, skills, model loads, agent-calling code), and
+an **"Already present in this repo"** section names the findings a local gate
+pass actually found, with paths. Commit the result and keep it honest with
+`shomra rules --check`, which exits 1 when the block is missing or stale.
+
+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`,
+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`,
+`shomra_check`, `shomra_explain`, `shomra_fix` and `shomra_scan_models` are
+exposed too. `shomra mcp serve` runs the server directly (stdio JSON-RPC) if you
+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
@@ -266,6 +521,8 @@ suppressed file drops to ALLOW and never fails the build:
 | `SHOMRA_GUARD_BREAKER_MS` | Skip the server this long after a failure (default 30000; `0` disables) |
 | `SHOMRA_LLM_PROXY_BASE` | Proxy base URL `install-hook` writes for Aider (default `http://127.0.0.1:4141/openai/v1`) |
 | `SHOMRA_MODEL_GUARD` | `0` = disable the model-load screen in the PreToolUse hook |
+| `SHOMRA_PROMPT_GUARD_OFF` | `1` = disable the prompt channel only (tool-call and tool-result guards stay on) |
+| `SHOMRA_PLAN_GUARD_OFF` | `1` = disable the plan channel only |
 | `SHOMRA_MODEL_CACHE` | `0` = disable the on-machine model-index verdict cache |
 | `SHOMRA_MODEL_CACHE_TTL_MS` | Model-cache freshness window (default 7 days) |
 

package/ai-usage.mjs

@@ -60,6 +60,35 @@ const PROVIDERS = [
   { id: 'llama-cpp', label: 'llama.cpp', category: 'local-runtime', npm: ['node-llama-cpp'], py: ['llama_cpp'], call: [/\bLlama\s*\(\s*model_path\s*=/] },
 ];
 
+/**
+ * Every AI package name this catalog knows, flattened for name comparison at
+ * ACQUISITION time (`shomra add package`). A typosquat is only detectable
+ * against a list of the real names, and this catalog is already that list —
+ * maintaining a second copy is how the two drift and the check quietly stops
+ * matching the packages people actually install.
+ *
+ * `ecosystem` matters: `openai` exists on both npm and PyPI, but `crewai` is
+ * PyPI-only, so `npm i crewai` is a different and more suspicious event than
+ * `pip install crewai`.
+ */
+export const KNOWN_AI_PACKAGES = (() => {
+  const out = [];
+  const seen = new Set();
+  const add = (name, ecosystem, p) => {
+    const key = `${ecosystem}:${name}`;
+    if (!name || seen.has(key)) return;
+    seen.add(key);
+    out.push({ name, ecosystem, provider: p.id, label: p.label, category: p.category });
+  };
+  for (const p of PROVIDERS) {
+    for (const n of p.npm ?? []) add(n, 'npm', p);
+    for (const n of p.npmPrefix ?? []) add(n.replace(/\/$/, ''), 'npm', p);
+    for (const n of p.py ?? []) add(n, 'pypi', p);
+    for (const n of p.pyRoot ?? []) add(n, 'pypi', p);
+  }
+  return out;
+})();
+
 const MODEL_ON_LINE = /\bmodel(?:_?id|_?name)?\s*[=:]\s*['"]([A-Za-z0-9][\w.:\/-]{1,80})['"]/;
 const MAX_CODE_LEN = 240;
 const clipLine = (s) => (s.length > MAX_CODE_LEN ? s.slice(0, MAX_CODE_LEN) + '…' : s);

package/design.mjs

@@ -0,0 +1,313 @@
+/**
+ * shomra design — threat-model a system that does not exist yet.
+ *
+ * Every other Shomra surface needs an artifact: a file to gate, a call to
+ * screen, a repo to scan. This one reads a DESCRIPTION — a design doc, an RFC, a
+ * Jira/Linear ticket, a PR body — and answers the only question worth asking
+ * before the first line is written: does the thing being described hand an
+ * attacker a path from untrusted input to a consequence?
+ *
+ * The engine is the platform's, not a new one. `attack-graph.ts` models an
+ * entity as six capability flags split into SOURCES (untrusted input, sensitive
+ * reads, filesystem) and SINKS (network egress, execution, destructive action),
+ * and calls a closed source→sink pair an attack path. That model does not care
+ * whether the capabilities came from a scan or from a sentence. Here they come
+ * from a sentence.
+ *
+ * ⚠ THE INVARIANT THAT MATTERS: absence of a described capability is NOT absence
+ * of the capability. Prose is written by people who leave things out. Every
+ * verdict this module can return names what it FOUND; none of them says the
+ * design is safe, and `NOT_DESCRIBED` is not a pass. Getting this wrong would
+ * turn a thinking aid into false assurance at the exact moment — before the
+ * build — when false assurance is cheapest to act on and most expensive to
+ * discover.
+ *
+ * Zero dependencies (Node built-ins only), like every other module here.
+ */
+
+// The capability vocabulary, mirroring `Caps` in the backend's attack-graph.ts.
+// Keep the split identical: a divergence here would produce a CLI threat model
+// that disagrees with the platform's for the same system.
+export const SOURCE_CAPS = ['injection', 'readsSensitive', 'filesystem'];
+export const SINK_CAPS = ['network', 'exec', 'destructive'];
+
+export const CAP_LABEL = {
+  injection: 'untrusted input',
+  readsSensitive: 'sensitive data',
+  filesystem: 'filesystem access',
+  network: 'network egress',
+  exec: 'code execution',
+  destructive: 'destructive action',
+};
+
+/**
+ * Prose → capability. Each rule carries the phrasing a designer actually uses,
+ * not the phrasing a scanner would emit. `what` is the human noun that goes into
+ * the attack story, so a path reads as a sentence about the system rather than a
+ * list of flags.
+ *
+ * Rules are matched per line so the evidence can cite one.
+ *
+ * ⚠ A line that DISCLAIMS a capability must not grant it. This originally said
+ * the opposite — that a "we will not do X" sentence was a design decision worth
+ * surfacing — and that was wrong: granting the flag from a disclaimer invents a
+ * phantom attack path out of the one sentence that rules it out, which is the
+ * most misleading output this tool can produce. "The tool has no access to
+ * customer data" is the designer telling you the source does not exist.
+ */
+const DISCLAIMER_RE = /\b(no|never|not|without|excludes?|excluding|neither|nor)\b[^.\n]{0,30}\b(access|read|write|permission|abilit|able|connection|integration)\w*|\b(does |do |will |can |must )(not|n't)\b|\bout of scope\b|\bnon-goals?\b|\bis not (able|permitted|allowed)\b/i;
+const CAP_RULES = [
+  // ── SOURCES ────────────────────────────────────────────────────────────────
+  { cap: 'injection', what: 'end-user or customer text', re: /\b(user|customer|client|end[- ]user)[- ]?(input|message|text|query|prompt|request|content|submission)\b/i },
+  { cap: 'injection', what: 'inbound email', re: /\b(inbound |incoming |receiv\w+ )?e-?mails?\b|\bmailbox\b|\bimap\b|\bsupport inbox\b/i },
+  { cap: 'injection', what: 'support tickets', re: /\b(support |help[- ]?desk |zendesk |intercom |freshdesk )?tickets?\b|\bcase notes?\b/i },
+  { cap: 'injection', what: 'issues and PR descriptions', re: /\b(github |gitlab |jira |linear )?(issues?|pull[- ]requests?|PR) (body|description|comments?)\b|\bissue tracker\b/i },
+  // Document nouns are plural far more often than not in a design doc ("ingests
+  // uploaded PDFs"), and an `\bpdf\b` that cannot match "PDFs" is a rule that
+  // misses the common phrasing while looking correct in a unit test.
+  { cap: 'injection', what: 'uploaded documents', re: /\b(upload(ed|s)?|attach(ed|ment)s?)\b.{0,30}\b(files?|documents?|pdfs?|images?|csvs?|spreadsheets?)\b|\b(pdf|docx|csv)s? (upload|ingest|pars\w+)/i },
+  // Provenance, not format: content ACCEPTED FROM a party outside the trust
+  // boundary is untrusted whatever shape it arrives in. Anchored on a receiving
+  // verb + "from" + the party, so ordinary prose about customers does not fire.
+  { cap: 'injection', what: 'content received from outside', re: /\b(ingest|receiv|accept|import|process|pull|collect|read|fetch)\w*\b[^.\n]{0,40}\bfrom\b[^.\n]{0,25}\b(customers?|users?|clients?|end[- ]users?|the public|third[- ]part\w+|external|partners?|vendors?|suppliers?)\b/i },
+  { cap: 'injection', what: 'scraped or fetched web content', re: /\b(scrap\w+|crawl\w+|fetch\w+|browse\w*)\b.{0,30}\b(web|site|page|url|internet)\b|\bweb (page|content|search results?)\b/i },
+  { cap: 'injection', what: 'retrieved documents (RAG)', re: /\bRAG\b|\bretrieval[- ]augmented\b|\b(retriev\w+|search\w*) (documents?|chunks?|context|corpus)\b|\bvector (store|db|database|search)\b|\bknowledge base\b/i },
+  { cap: 'injection', what: 'third-party API responses', re: /\bthird[- ]party\b.{0,30}\b(api|response|data|feed|service)\b|\bexternal (api|service|feed) (response|data|content)\b/i },
+  { cap: 'injection', what: 'public form submissions', re: /\bpublic\b.{0,25}\b(form|endpoint|api|submission|chat|widget)\b|\bunauthenticated (user|request|caller)\b/i },
+  { cap: 'injection', what: 'chat or comment history', re: /\b(chat|conversation|comment|review|forum|slack|discord|teams) (history|thread|messages?|log)\b/i },
+  { cap: 'injection', what: 'MCP tool results', re: /\bMCP\b.{0,40}\b(tool|server|response|result)\b|\btool (result|response|output)s?\b.{0,20}\b(back into|into (the )?context)\b/i },
+
+  { cap: 'readsSensitive', what: 'customer records', re: /\b(customer|user|client|member|patient|employee)s?[- ]?(data|records?|profiles?|list|database|table|pii)\b|\bPII\b|\bpersonal(ly)?[- ]identifiab\w+/i },
+  { cap: 'readsSensitive', what: 'credentials or secrets', re: /\b(secret|credential|api[- ]?key|access[- ]?token|password|private[- ]?key|service[- ]account)s?\b|\bvault\b|\bkeychain\b|\b\.env\b/i },
+  { cap: 'readsSensitive', what: 'regulated data', re: /\b(PHI|HIPAA|GDPR|PCI([- ]DSS)?|SOC ?2|health (records?|data)|medical|financial (records?|data)|payroll|salar(y|ies)|SSN|social security|tax)\b/i },
+  { cap: 'readsSensitive', what: 'the production database', re: /\bprod(uction)?\b.{0,25}\b(database|db|data|warehouse|replica|store)\b|\b(database|db|warehouse) (read|query|access|connection)\b|\bread[- ]replica\b/i },
+  { cap: 'readsSensitive', what: 'private source code', re: /\bprivate (repo|repositor\w+|source|code)\b|\bproprietary (code|source)\b|\binternal (repo|codebase|wiki|docs?)\b/i },
+  { cap: 'readsSensitive', what: 'object storage', re: /\bS3 bucket\b|\b(blob|object) storage\b|\bGCS bucket\b|\bdata lake\b/i },
+
+  // Plurals throughout: "writes the generated files to the repo" is the normal
+  // phrasing, and `\bfile\b` cannot match it. Same blind spot as `\bpdf\b` vs
+  // "PDFs" — assume every noun here arrives plural at least half the time.
+  { cap: 'filesystem', what: 'file writes', re: /\bwrit\w+\b[^.\n]{0,25}\b(files?|disks?|filesystems?|director(y|ies)|folders?|repos?|repositor(y|ies))\b|\b(file ?system|local files?) (access|write)\b|\bcommits? (code|files?|changes?)\b/i },
+  { cap: 'filesystem', what: 'workspace or repo checkout', re: /\b(clones?|checks? out|checkout)\b.{0,25}\b(repo|repositor\w+)\b|\bworkspace (access|mount|volume)\b/i },
+
+  // ── SINKS ──────────────────────────────────────────────────────────────────
+  { cap: 'network', what: 'outbound API calls', re: /\bcalls?\b.{0,30}\b(external|third[- ]party|public|remote|partner)\b.{0,20}\bapi\b|\boutbound (request|call|http|traffic)\b|\begress\b/i },
+  { cap: 'network', what: 'webhooks', re: /\bwebhooks?\b|\bpost(s|ing|ed)?\b[^.\n]{0,30}\bto\b[^.\n]{0,25}\b(endpoints?|urls?|callbacks?|apis?|services?|partners?|systems?)\b/i },
+  { cap: 'network', what: 'sending email or messages', re: /\bsends?\b.{0,25}\b(e-?mail|message|notification|sms|slack|dm)\b|\bnotif(y|ies|ication)\b.{0,25}\b(user|customer|channel|slack|teams|email)\b|\bsmtp\b/i },
+  { cap: 'network', what: 'publishing or uploading data', re: /\b(publish|upload|export|sync|push)\w*\b.{0,30}\b(to|into)\b.{0,25}\b(external|third[- ]party|cloud|bucket|service|partner|crm|warehouse)\b/i },
+  { cap: 'network', what: 'a model provider call', re: /\b(openai|anthropic|gemini|bedrock|azure openai|mistral|cohere|hugging ?face)\b|\bLLM (api|provider|call)\b|\bmodel (provider|endpoint|api)\b/i },
+
+  { cap: 'exec', what: 'running shell commands', re: /\b(runs?|execut\w+|invok\w+|spawn\w+)\b.{0,25}\b(command|shell|bash|script|binary|subprocess|terminal)\b|\bshell access\b|\barbitrary code\b/i },
+  { cap: 'exec', what: 'code interpretation', re: /\b(code (interpreter|execution|sandbox)|eval\b|exec\b|repl\b|jupyter|notebook execution)\b/i },
+  { cap: 'exec', what: 'deployments or migrations', re: /\b(deploy|rollout|release|migrat\w+|provision\w*|terraform|helm|kubectl)\b/i },
+  { cap: 'exec', what: 'agent tool calls', re: /\b(tool[- ]call|function[- ]call|tool use|agentic loop|autonomous(ly)?)\b|\bagent (executes?|acts?|takes? actions?)\b/i },
+
+  { cap: 'destructive', what: 'deleting data', re: /\bdelet\w+|\bremov\w+\b.{0,20}\b(record|row|file|user|account|data)\b|\bpurge\b|\bdrop (table|database)\b|\btruncat\w+/i },
+  // A money NOUN alone is not a capability — "the dashboard displays the refund
+  // history" is a read. The line has to name an act that MOVES the money, so the
+  // verb is required and read-only verbs are not on the list.
+  { cap: 'destructive', what: 'moving money', re: /\b(issues?|issuing|processes|processing|triggers?|initiates?|creates?|approves?|grants?|sends?|makes?|charges?|refunds?|voids?|cancels?)\b[^.\n]{0,30}\b(refunds?|payments?|charges?|invoices?|payouts?|transfers?|subscriptions?|purchases?|orders?)\b|\bmoves? money\b|\bthrough stripe\b|\bvia stripe\b/i },
+  { cap: 'destructive', what: 'changing access or state', re: /\b(revok\w+|disabl\w+|suspend\w+|deactivat\w+|cancel\w*|ban\w*)\b.{0,25}\b(user|account|access|key|token|subscription|service)\b|\bgrants? (access|permission|role)\b/i },
+  { cap: 'destructive', what: 'writing to production', re: /\bwrit\w+\b.{0,25}\bprod(uction)?\b|\bprod(uction)?\b.{0,20}\bwrite (access|path)\b|\bmutat\w+\b.{0,25}\b(prod|live|customer) (data|state)\b/i },
+];
+
+/** Lines that are headings, code fences or list scaffolding carry no design intent. */
+function isSkippableLine(line) {
+  const t = line.trim();
+  return !t || t === '---' || /^```/.test(t) || /^\|[\s-:|]+\|$/.test(t);
+}
+
+/**
+ * Extract the capability set a document DESCRIBES, with the line and phrase that
+ * evidenced each — the evidence is the point: a reader has to be able to check
+ * the machine's reading against their own words and disagree with it.
+ */
+export function capsFromProse(text) {
+  const caps = { injection: false, readsSensitive: false, filesystem: false, network: false, exec: false, destructive: false };
+  const evidence = {};
+  const lines = String(text ?? '').split(/\r?\n/);
+  let inFence = false;
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (/^\s*```/.test(line)) { inFence = !inFence; continue; }
+    // Code blocks in a design doc are illustrative snippets, not statements of
+    // intent — and they are exactly where a scanner's vocabulary produces noise.
+    if (inFence || isSkippableLine(line)) continue;
+    // A disclaimer names the capability in order to rule it out. Granting the
+    // flag here would invent an attack path from the sentence that removes it.
+    if (DISCLAIMER_RE.test(line)) continue;
+
+    for (const r of CAP_RULES) {
+      const m = r.re.exec(line);
+      if (!m) continue;
+      caps[r.cap] = true;
+      const list = (evidence[r.cap] = evidence[r.cap] || []);
+      if (list.some((e) => e.what === r.what)) continue; // one citation per distinct capability phrasing
+      list.push({ what: r.what, line: i + 1, quote: line.trim().slice(0, 160), match: m[0].slice(0, 60), score: evidenceScore(line) });
+    }
+  }
+  // Rank each capability's citations so the one the attack story quotes is the
+  // line that DESCRIBES the behaviour, not the first line the word appeared on.
+  // "Reduce first-response time on support tickets" (a goal) and "polls the
+  // support inbox and reads inbound emails" (the design) both mention tickets;
+  // quoting the goal makes the finding look like a keyword hit and is the
+  // fastest way for a reader to stop trusting the output.
+  for (const k of Object.keys(evidence)) evidence[k].sort((a, b) => b.score - a.score || a.line - b.line);
+  return { caps, evidence };
+}
+
+// A line that says what the system DOES, rather than what it is for. Used only
+// to order evidence — never to grant or withhold a capability.
+const ACTION_LINE_RE = /\b(reads?|writes?|polls?|fetch\w*|calls?|sends?|runs?|executes?|issues?|looks? up|quer\w+|retriev\w+|ingest\w*|receiv\w+|access\w*|store[sd]?|upload\w*|post\w*|delet\w+|creat\w+|updat\w+|has|have|will|can|must)\b/i;
+const GOAL_LINE_RE = /^\s{0,3}#{1,6}\s|^\s*(goal|motivation|background|summary|context|out of scope|non-goals?)\b/i;
+
+function evidenceScore(line) {
+  let s = 0;
+  if (ACTION_LINE_RE.test(line)) s += 3;
+  if (GOAL_LINE_RE.test(line)) s -= 3;
+  if (line.trim().length > 60) s += 1; // a full sentence beats a heading fragment
+  return s;
+}
+
+/** Severity of a closed path. Mirrors chainSeverity() in attack-graph.ts:
+ *  untrusted input reaching a hard sink is the worst case in the model. */
+function pathSeverity(source, sink) {
+  const hardSink = sink === 'exec' || sink === 'destructive';
+  if (hardSink && source === 'injection') return 'CRITICAL';
+  if (hardSink) return 'HIGH';
+  if (sink === 'network' && (source === 'readsSensitive' || source === 'injection')) return 'HIGH';
+  return 'MEDIUM';
+}
+
+// What has to be true for a given source→sink pair to be safe to build. These
+// are stated as testable conditions rather than advice, because their job is to
+// become the acceptance criteria on the ticket that describes the system.
+const CONTROLS = {
+  'injection→exec': [
+    'The set of commands the agent can run is a fixed allowlist in code. Model output selects WHICH allowlisted action runs, never the command string itself.',
+    'Untrusted text is passed as a labelled data parameter, never concatenated into a command, a prompt template, or a tool argument that reaches a shell.',
+    'The runtime firewall is wired on this path (`shomra protect`), so a command assembled at runtime is refused rather than logged.',
+  ],
+  'injection→destructive': [
+    'Every destructive or money-moving action requires an approval step that a human performs outside the agent loop.',
+    'The action is idempotent and reversible, with an audit record naming the input that triggered it.',
+    'Per-action limits (amount, row count, blast radius) are enforced server-side, not by the prompt.',
+  ],
+  'injection→network': [
+    'Outbound destinations come from an allowlist. A URL that appears in untrusted content can never become a request target.',
+    'The agent cannot include content it read into an outbound request to a destination named by that same content.',
+  ],
+  'readsSensitive→network': [
+    'Splitting the trust boundary: the component that reads the sensitive data and the component that makes the outbound call do not share one context or one credential.',
+    'Outbound payloads are field-allowlisted — what may leave is enumerated, rather than what may not.',
+    'The sensitive read is scoped to the minimum rows/fields the task needs, per-request, not a standing broad grant.',
+  ],
+  'readsSensitive→exec': [
+    'Secrets are injected at the point of use from a broker with short-lived leases, never placed in the environment of a process the agent can influence.',
+    'The executing context cannot read the credential store it does not need.',
+  ],
+  'readsSensitive→destructive': [
+    'The identity that reads and the identity that mutates are different, each scoped to its own job.',
+    'Destructive actions are gated on a human approval that shows the operator exactly which records are affected.',
+  ],
+  'filesystem→exec': [
+    'Files the agent writes cannot land anywhere on an execution path (no hooks, no startup dirs, no CI config, no agent rules files) without passing the gate.',
+    '`shomra check` runs over agent-authored artifacts before they are committed.',
+  ],
+  'filesystem→network': [
+    'The agent cannot write a file and then cause that file to be uploaded to a destination it chose.',
+  ],
+  'filesystem→destructive': [
+    'Writes are confined to a working directory, with deletes scoped to paths the agent itself created.',
+  ],
+};
+
+const GENERIC_CONTROLS = [
+  'Give the agent its own identity with its own credentials, so its actions are attributable and revocable independently of a human user.',
+  'Record every tool call the agent makes, with the input that caused it, so an incident can be reconstructed.',
+  'Decide now what the agent must NOT be able to do, and enforce it in code rather than in the prompt — a prompt is a request, not a control.',
+];
+
+/**
+ * Threat-model a described system.
+ *
+ * `verdict` deliberately has no clean value:
+ *   OPEN_PATH     — a source and a sink are both described; the path is closed.
+ *   PARTIAL       — only one side is described. Not safety: the other side may
+ *                   simply be unwritten, or may arrive in the next sprint.
+ *   NOT_DESCRIBED — neither side was recognised. The likeliest reading is that
+ *                   the document does not describe capabilities in a way this
+ *                   matched, NOT that the system has none.
+ */
+export function analyzeDesign(text, { name = 'design' } = {}) {
+  const { caps, evidence } = capsFromProse(text);
+  const sources = SOURCE_CAPS.filter((c) => caps[c]);
+  const sinks = SINK_CAPS.filter((c) => caps[c]);
+
+  const paths = [];
+  for (const s of sources) {
+    for (const k of sinks) {
+      const severity = pathSeverity(s, k);
+      const srcEv = (evidence[s] || [])[0];
+      const sinkEv = (evidence[k] || [])[0];
+      paths.push({
+        source: s,
+        sink: k,
+        severity,
+        key: `${s}→${k}`,
+        story:
+          `${cap(srcEv ? srcEv.what : CAP_LABEL[s])} reaches ${sinkEv ? sinkEv.what : CAP_LABEL[k]}` +
+          `${s === 'injection' ? ' — whoever writes that input is choosing what the agent does' : ''}` +
+          `${s === 'readsSensitive' && k === 'network' ? ' — the data and the way out are held by the same component' : ''}.`,
+        sourceEvidence: srcEv || null,
+        sinkEvidence: sinkEv || null,
+        controls: CONTROLS[`${s}→${k}`] || [],
+      });
+    }
+  }
+  paths.sort((a, b) => SEV_RANK[b.severity] - SEV_RANK[a.severity]);
+
+  const verdict = paths.length ? 'OPEN_PATH' : sources.length || sinks.length ? 'PARTIAL' : 'NOT_DESCRIBED';
+  const worst = paths.length ? paths[0].severity : null;
+
+  // Deduplicate controls across paths, worst-severity first, then append the
+  // ones that apply to any agent with a consequence.
+  const seen = new Set();
+  const controls = [];
+  for (const p of paths) for (const c of p.controls) if (!seen.has(c)) { seen.add(c); controls.push({ text: c, from: p.key, severity: p.severity }); }
+  if (paths.length) for (const c of GENERIC_CONTROLS) if (!seen.has(c)) { seen.add(c); controls.push({ text: c, from: 'any-agent', severity: 'MEDIUM' }); }
+
+  return { name, caps, evidence, sources, sinks, paths, controls, verdict, worst };
+}
+
+const SEV_RANK = { CRITICAL: 4, HIGH: 3, MEDIUM: 2, LOW: 1 };
+
+function cap(s) {
+  return String(s || '').charAt(0).toUpperCase() + String(s || '').slice(1);
+}
+
+/** The result as a markdown task list — the form that becomes the ticket's
+ *  acceptance criteria, which is the only form anyone acts on. */
+export function designChecklist(result) {
+  const out = [];
+  out.push(`## Security acceptance criteria — ${result.name}`);
+  out.push('');
+  if (result.verdict !== 'OPEN_PATH') {
+    out.push(
+      result.verdict === 'PARTIAL'
+        ? `Only one side of an attack path is described here (${[...result.sources, ...result.sinks].map((c) => CAP_LABEL[c]).join(', ')}). Re-run this when the design names what the agent can *do* with it.`
+        : 'No capabilities were recognised in this document. That is a statement about the document, not about the system — if the agent will read anything untrusted or take any action, write that down and re-run.',
+    );
+    out.push('');
+    return out.join('\n') + '\n';
+  }
+  out.push(`This design closes ${result.paths.length} attack path${result.paths.length === 1 ? '' : 's'}. Each item below is a condition to satisfy before it ships.`);
+  out.push('');
+  for (const p of result.paths.slice(0, 6)) out.push(`- **${p.severity} · ${CAP_LABEL[p.source]} → ${CAP_LABEL[p.sink]}** — ${p.story}`);
+  out.push('');
+  for (const c of result.controls) out.push(`- [ ] ${c.text}`);
+  out.push('');
+  out.push('_Derived by `shomra design` from the description above. It reads prose, so it sees only what was written down — a capability nobody documented is not a capability you do not have._');
+  return out.join('\n') + '\n';
+}