@sponsio/sdk 0.1.0-alpha.3 → 0.2.0-alpha.4

package/dist/render/tokens.js.map

@@ -1 +1 @@
-{"version":3,"file":"tokens.js","sourceRoot":"","sources":["../../src/render/tokens.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,CAAC,MAAM,OAAO,GAAG;IACrB,KAAK,EAAE,IAAI,EAAE,OAAO;IACpB,IAAI,EAAE,MAAM,EAAE,WAAW;IACzB,EAAE,EAAE,IAAI,EAAE,qBAAqB;IAC/B,QAAQ,EAAE,GAAG,EAAE,MAAM;IACrB,EAAE,EAAE,IAAI,EAAE,QAAQ;IAClB,OAAO,EAAE,IAAI,EAAE,MAAM;IACrB,IAAI,EAAE,IAAI,EAAE,SAAS;IACrB,MAAM,EAAE,IAAI,EAAE,QAAQ;IACtB,KAAK,EAAE,IAAI,EAAE,SAAS;IACtB,QAAQ,EAAE,GAAG,EAAE,MAAM;CACtB,CAAC;AAEF,MAAM,CAAC,MAAM,MAAM,GAAG;IACpB,MAAM,EAAE,OAAO,CAAC,MAAM;IACtB,KAAK,EAAE,OAAO,CAAC,KAAK;IACpB,OAAO,EAAE,OAAO,CAAC,OAAO;IACxB,aAAa,EAAE,OAAO,CAAC,IAAI;IAC3B,OAAO,EAAE,OAAO,CAAC,EAAE;IACnB,MAAM,EAAE,OAAO,CAAC,EAAE;IAClB,KAAK,EAAE,OAAO,CAAC,IAAI;CACM,CAAC;AAE5B,MAAM,CAAC,MAAM,OAAO,GAAG;IACrB,IAAI,EAAE,IAAI;IACV,SAAS,EAAE,GAAG;IACd,SAAS,EAAE,GAAG;IACd,OAAO,EAAE,IAAI;IACb,OAAO,EAAE,IAAI;IACb,UAAU,EAAE,GAAG;IACf,WAAW,EAAE,GAAG;IAChB,MAAM,EAAE,GAAG;IACX,KAAK,EAAE,GAAG;IACV,KAAK,EAAE,GAAG;IACV,MAAM,EAAE,GAAG;IACX,MAAM,EAAE,GAAG;IACX,IAAI,EAAE,GAAG;CACV,CAAC;AAEF,MAAM,UAAU,IAAI,CAAC,IAAY,EAAE,IAAY,EAAE,QAAiB;IAChE,IAAI,CAAC,QAAQ,IAAI,CAAC,IAAI;QAAE,OAAO,IAAI,CAAC;IACpC,OAAO,QAAQ,IAAI,IAAI,IAAI,SAAS,CAAC;AACvC,CAAC;AAED,MAAM,UAAU,cAAc;IAC5B,IAAI,OAAO,CAAC,GAAG,CAAC,gBAAgB;QAAE,OAAO,KAAK,CAAC;IAC/C,IAAI,OAAO,CAAC,GAAG,CAAC,QAAQ;QAAE,OAAO,KAAK,CAAC;IACvC,IAAI,OAAO,CAAC,GAAG,CAAC,WAAW;QAAE,OAAO,IAAI,CAAC;IACzC,OAAO,CAAC,CAAE,OAAO,CAAC,MAAyC,CAAC,KAAK,CAAC;AACpE,CAAC;AAED,gEAAgE;AAChE,MAAM,UAAU,QAAQ,CAAC,CAAS,EAAE,GAAW;IAC7C,IAAI,CAAC,CAAC,MAAM,IAAI,GAAG;QAAE,OAAO,CAAC,CAAC;IAC9B,OAAO,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,GAAG,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC;AAChD,CAAC;AAED,uEAAuE;AACvE,MAAM,UAAU,GAAG,CAAC,CAAS,EAAE,KAAa;IAC1C,IAAI,CAAC,CAAC,MAAM,IAAI,KAAK;QAAE,OAAO,CAAC,CAAC;IAChC,OAAO,CAAC,GAAG,GAAG,CAAC,MAAM,CAAC,KAAK,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC;AAC1C,CAAC"}
+{"version":3,"file":"tokens.js","sourceRoot":"","sources":["../../src/render/tokens.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,CAAC,MAAM,OAAO,GAAG;IACrB,KAAK,EAAE,IAAI,EAAE,OAAO;IACpB,IAAI,EAAE,MAAM,EAAE,WAAW;IACzB,EAAE,EAAE,IAAI,EAAE,qBAAqB;IAC/B,QAAQ,EAAE,GAAG,EAAE,MAAM;IACrB,EAAE,EAAE,IAAI,EAAE,QAAQ;IAClB,OAAO,EAAE,IAAI,EAAE,MAAM;IACrB,IAAI,EAAE,IAAI,EAAE,SAAS;IACrB,MAAM,EAAE,IAAI,EAAE,QAAQ;IACtB,KAAK,EAAE,IAAI,EAAE,SAAS;IACtB,QAAQ,EAAE,GAAG,EAAE,MAAM;CACtB,CAAC;AAEF,MAAM,CAAC,MAAM,MAAM,GAAG;IACpB,MAAM,EAAE,OAAO,CAAC,MAAM;IACtB,KAAK,EAAE,OAAO,CAAC,KAAK;IACpB,OAAO,EAAE,OAAO,CAAC,OAAO;IACxB,aAAa,EAAE,OAAO,CAAC,IAAI;IAC3B,QAAQ,EAAE,OAAO,CAAC,IAAI;IACtB,OAAO,EAAE,OAAO,CAAC,EAAE;IACnB,MAAM,EAAE,OAAO,CAAC,EAAE;IAClB,KAAK,EAAE,OAAO,CAAC,IAAI;CACM,CAAC;AAE5B,MAAM,CAAC,MAAM,OAAO,GAAG;IACrB,IAAI,EAAE,IAAI;IACV,SAAS,EAAE,GAAG;IACd,SAAS,EAAE,GAAG;IACd,OAAO,EAAE,IAAI;IACb,OAAO,EAAE,IAAI;IACb,UAAU,EAAE,GAAG;IACf,WAAW,EAAE,GAAG;IAChB,MAAM,EAAE,GAAG;IACX,KAAK,EAAE,GAAG;IACV,KAAK,EAAE,GAAG;IACV,MAAM,EAAE,GAAG;IACX,MAAM,EAAE,GAAG;IACX,IAAI,EAAE,GAAG;CACV,CAAC;AAEF,MAAM,UAAU,IAAI,CAAC,IAAY,EAAE,IAAY,EAAE,QAAiB;IAChE,IAAI,CAAC,QAAQ,IAAI,CAAC,IAAI;QAAE,OAAO,IAAI,CAAC;IACpC,OAAO,QAAQ,IAAI,IAAI,IAAI,SAAS,CAAC;AACvC,CAAC;AAED,MAAM,UAAU,cAAc;IAC5B,IAAI,OAAO,CAAC,GAAG,CAAC,gBAAgB;QAAE,OAAO,KAAK,CAAC;IAC/C,IAAI,OAAO,CAAC,GAAG,CAAC,QAAQ;QAAE,OAAO,KAAK,CAAC;IACvC,IAAI,OAAO,CAAC,GAAG,CAAC,WAAW;QAAE,OAAO,IAAI,CAAC;IACzC,OAAO,CAAC,CAAE,OAAO,CAAC,MAAyC,CAAC,KAAK,CAAC;AACpE,CAAC;AAED,gEAAgE;AAChE,MAAM,UAAU,QAAQ,CAAC,CAAS,EAAE,GAAW;IAC7C,IAAI,CAAC,CAAC,MAAM,IAAI,GAAG;QAAE,OAAO,CAAC,CAAC;IAC9B,OAAO,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,GAAG,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC;AAChD,CAAC;AAED,uEAAuE;AACvE,MAAM,UAAU,GAAG,CAAC,CAAS,EAAE,KAAa;IAC1C,IAAI,CAAC,CAAC,MAAM,IAAI,KAAK;QAAE,OAAO,CAAC,CAAC;IAChC,OAAO,CAAC,GAAG,GAAG,CAAC,MAAM,CAAC,KAAK,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC;AAC1C,CAAC"}

package/package.json

@@ -1,8 +1,21 @@
 {
   "name": "@sponsio/sdk",
-  "version": "0.1.0-alpha.3",
+  "version": "0.2.0-alpha.4",
   "description": "Runtime contract enforcement for LLM agents — native TypeScript",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SponsioLabs/Sponsio.git",
+    "directory": "ts/packages/sdk"
+  },
+  "bugs": {
+    "url": "https://github.com/SponsioLabs/Sponsio/issues"
+  },
+  "homepage": "https://github.com/SponsioLabs/Sponsio#readme",
   "type": "module",
+  "sideEffects": [
+    "./dist/cli/**"
+  ],
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "exports": {
@@ -35,29 +48,42 @@
       "default": "./dist/integrations/langchain.js"
     }
   },
+  "bin": {
+    "sponsio": "bin/sponsio.cjs"
+  },
   "files": [
     "dist/",
     "!dist/__tests__/**",
+    "!dist/cli/__tests__/**",
+    "bin/",
     "contracts/",
+    "prompts/",
+    "skills/",
     "README.md"
   ],
   "scripts": {
-    "build": "tsc",
+    "build": "tsc && tsc -p tsconfig.cli.json && node -e \"require('fs').writeFileSync('dist/cli/package.json', '{\\\"type\\\":\\\"commonjs\\\"}\\n')\"",
     "test": "node --test dist/__tests__/*.test.js",
+    "test:cli": "node --test dist/cli/__tests__/*.test.js",
     "test:src": "npx tsx src/__tests__/core.test.ts",
     "test:parity": "npx tsx src/__tests__/parity.test.ts && npx tsx src/__tests__/parity.scenarios.test.ts"
   },
   "dependencies": {
-    "yaml": "^2.7.0"
+    "fast-glob": "^3.3.0",
+    "js-yaml": "^5.2.3",
+    "ts-morph": "^28.0.0",
+    "yaml": "^2.9.0"
   },
   "devDependencies": {
-    "@types/node": "^25.6.0",
-    "tsx": "^4.0.0",
+    "@types/js-yaml": "^4.0.5",
+    "@types/node": "^26.1.2",
+    "esbuild": "^0.28.1",
+    "tsx": "^4.23.5",
     "typescript": "^5.5.0"
   },
   "peerDependencies": {
-    "@langchain/core": ">=0.3.0",
     "@google/adk": ">=0.2.0",
+    "@langchain/core": ">=0.3.0",
     "ai": ">=4.0.0",
     "claude-agent-sdk": ">=0.1.0",
     "openai": ">=4.0.0"
@@ -79,5 +105,7 @@
       "optional": true
     }
   },
-  "license": "Apache-2.0"
+  "publishConfig": {
+    "access": "public"
+  }
 }

package/prompts/onboard.md

@@ -0,0 +1,246 @@
+# Contract authoring prompt — sponsio onboard
+
+You are a security engineer authoring a `sponsio.yaml` for a project
+the user just installed Sponsio in.  The CLI has already done the
+deterministic work (framework detection, AST-based tool inventory,
+auto-selected packs).  Your job is the **semantic gap**: rules a
+name-heuristic can't see.
+
+## Input
+
+A JSON object from `sponsio onboard --emit-context`:
+
+```json
+{
+  "framework": {"name": "...", "evidence": "..."},
+  "agent_id": "...",
+  "tool_inventory": [
+    {"name": "...", "description": "...", "params": {...}, "source_file": "..."}
+  ],
+  "auto_selected_packs": ["sponsio:core/universal", ...],
+  "existing_yaml": "<current sponsio.yaml content if any>",
+  "policy_docs": [
+    {"path": "security.md", "content": "..."}
+  ],
+  "pre_existing_contracts": [
+    {"pattern": "...", "args": [...], "source": "..."}
+  ],
+  "health": "ok | tools_only | empty",
+  "health_detail": "..."
+}
+```
+
+## Hard rules (apply before authoring anything)
+
+- **Deterministic atoms only.**  Use ONLY pattern names from the
+  *Pattern vocabulary* section below.  The engine is
+  deterministic-only; any pattern name outside that vocabulary will
+  fail to parse.
+
+- **Dedupe against `pre_existing_contracts`.**  The CLI already
+  emitted starter rules (likely `idempotent`, generic
+  `arg_blacklist`, `tool_allowlist`, `loop_detection`).  Skip any
+  `(pattern, primary_arg)` already present.  Add only what's new.
+
+- **Pack rules go in `include:`, not inline.**  Every entry in
+  `auto_selected_packs` belongs in the agent's `include:` block.
+  Do NOT inline what the pack already covers — duplicate noise
+  the user has to clean up.
+
+- **Source tagging.**  Every contract YOU author carries
+  `source: agent-extracted` so later tooling can distinguish your
+  additions from pack rules and from CLI-emitted starter rules.
+
+- **One contract per concrete failure mode.**  Plain-English
+  `desc:` so the user can review by reading.  No omnibus rules.
+
+- **Strip `extractor:` / `judge:` blocks.**  The engine does not use
+  them; they only add noise to the file.
+
+- **Placeholders only as last resort.**  Use `___AGENT_ID___`,
+  `___WORKSPACE___`, `___ALLOWED_HOST___` etc. ONLY when no
+  concrete value can be inferred from `policy_docs`,
+  `tool_inventory`, or the threat model.  Concrete values from
+  the inputs always win — placeholders force the user to fill
+  in by hand, so they're a tax on the user, not a default.
+
+- **`health == "empty"` means stop.**  When the CLI flagged the
+  inputs as empty (no framework, no tools, no policy), don't
+  fabricate rules.  Tell the user the inputs were empty and ask
+  what they want — usually it means the wrong path was scanned.
+
+## Read beyond the JSON — that's where you earn your keep
+
+The CLI already gave you the deterministic surface (tool inventory,
+auto-selected packs, policy_docs).  AST extraction can't see
+intent — that's why the host agent is in this loop instead of an
+LLM-extractor subprocess.  Before you propose anything, also read:
+
+- **README.md / SECURITY.md / POLICY.md / docs/*.md** for the rules
+  the user wrote in prose ("we never delete prod snapshots", "AML
+  must complete before loan funding").  These map to
+  ``arg_blacklist`` / ``must_precede`` / ``rate_limit`` more
+  faithfully than tool-name heuristics ever will.
+- **The agent entry file + the modules its tools call into.**
+  KPI strings in the system prompt ("cut storage 20%") tell you
+  what the agent will be tempted to do; you can pre-emptively
+  block the unsafe shortcut.
+- **Existing tests.**  They often encode invariants ("balance
+  must never go negative", "report must list every deletion").
+- **``git log -p`` on the agent files.**  Recent patches that
+  fix bugs labelled "agent did <X> we didn't want" hint at
+  rules the user already wishes existed.
+
+Cite the source in each contract's ``desc:`` field — ``"never
+delete /snapshots/prod/* (policy.md L18)"`` is a 5-second review;
+``"safety rule for delete_snapshot"`` is theatre.
+
+## Output — render as a diff for the user to pick
+
+Don't auto-write the whole sponsio.yaml in one go.  The starter
+yaml on disk (already produced by ``sponsio onboard`` /
+``sponsio init``) is your baseline.  Compute the DIFF — 5 to 10
+new contracts — and render it as YAML next to a one-sentence
+``rationale:`` per contract:
+
+```yaml
+# Proposed additions — review and tell me which to merge.
+agents:
+  <agent_id>:
+    contracts:
+      - desc: "delete_snapshot must not touch /snapshots/prod/"
+        G:
+          pattern: arg_blacklist
+          args: [delete_snapshot, path, ["^/snapshots/prod/"]]
+          source: agent-extracted
+        # rationale: policy.md L18 — "Production snapshots are
+        # off-site DR backups and MUST NEVER be deleted"
+      - desc: "delete_snapshot age_days within 30-day rotation"
+        G:
+          pattern: arg_value_range
+          args: [delete_snapshot, age_days, 0, 30]
+          source: agent-extracted
+        # rationale: policy.md L24 — age_days <= 30 retention
+```
+
+Then WAIT for the user to pick which proposals to merge into
+``sponsio.yaml``.  Don't auto-write.  Onboarding ends when the
+user tells you which ones land.
+
+## What you produce
+
+A single YAML document — the new (or revised) `sponsio.yaml`.
+Structure:
+
+```yaml
+version: "1"
+mode: observe
+agents:
+  <agent_id>:
+    include:
+      - <pack from auto_selected_packs>
+      - ...
+    contracts:
+      - desc: "..."
+        G:
+          pattern: ...
+          args: [...]
+        A:
+          # optional — when conditional
+          pattern: ...
+          args: [...]
+```
+
+## Rules of thumb (apply in this order)
+
+1. **Pack first** — every pack in `auto_selected_packs` goes in
+   `include:`.  Don't try to inline what the pack already covers;
+   redundant rules just clutter review.
+2. **Tool-specific contracts** — for each tool the inventory shows:
+   - **Destructive verbs** (`delete_*`, `remove_*`, `transfer_*`,
+     `force_*`) → `irreversible_once` if irreversible, otherwise
+     tight `rate_limit`.
+   - **Outbound side-effects** (`send_email`, `post_*`,
+     `create_*_comment`) → `rate_limit` 5–10 + `arg_blacklist` for
+     target identifiers if you can constrain them.
+   - **Path / URL params** → `arg_blacklist` for sensitive paths
+     (`\.env`, `\.aws/credentials`, `\.ssh/`) and internal hosts.
+   - **Read tools** → skip unless they touch credentials.
+3. **Policy doc** — if `policy_docs` is non-empty, lift specific
+   rules from them.  Each one becomes a contract with
+   `source: policy`.
+4. **Existing YAML** — if `existing_yaml` is non-empty, **merge**:
+   keep all user-written contracts intact, add new ones for tools
+   that aren't covered.  Never silently delete.
+
+## Pattern vocabulary
+
+(Same as plugin scan — `arg_blacklist`, `arg_value_range`,
+`arg_length_limit`, `rate_limit`, `loop_detection`,
+`irreversible_once`, `must_precede`.  See
+``sponsio plugin prompt mcp-bare`` for full signatures.)
+
+## Source tagging
+
+Every contract YOU author should carry `source: agent-extracted` so
+later tooling knows they were agent-generated.  Don't tag
+pack-included rules; those have their own source from the pack.
+
+## What to do after
+
+You produce **two** edits, in this order:
+
+### 1. Write `sponsio.yaml`
+
+Write the YAML you authored above to the path in `out_path` (default:
+project root). Use the host's Edit/Write tool. If `existing_yaml`
+was non-empty, merge — don't clobber.
+
+### 2. Patch the agent entry file
+
+`wrap_snippet` shows the imports and guard construction. Your job is
+to splice those into the actual entry file so Sponsio is wired into
+the runtime, not just printed in the docs.
+
+**Locate the entry file** (use `entry_file_candidates` if present in
+the context — the CLI's deterministic scan flagged files that import
+the framework). If absent, fall back to:
+
+  - Python: files that instantiate the framework's agent class
+    (e.g. `Agent(...)`, `LangGraph(...)`, `ClaudeAgent(...)`),
+    pointed at by `pyproject.toml`'s entry points or the project's
+    run script.
+  - TypeScript: files that call `generateText` / construct the
+    Anthropic / OpenAI client / build a LangChain ToolNode, pointed
+    at by `package.json`'s `main` / `bin` / `scripts.start`.
+
+If multiple candidates remain after that filter, **stop and ask the
+user** rather than guessing — picking wrong creates a duplicate
+guard or a partial wire-up that's worse than nothing.
+
+**Apply the wrap** (framework-specific):
+
+  - **Vercel AI SDK**: change every `model: <provider>("...")` site
+    to `model: wrapLanguageModel({ model: <provider>("..."),
+    middleware: sponsioMiddleware(guard) })`. Add the imports at the
+    top.
+  - **LangChain / LangGraph**: replace `tools` arrays passed to
+    `ToolNode` / `createReactAgent` with `wrapTools(tools, guard)`.
+  - **Claude Agent SDK / OpenAI Agents SDK**: wrap the underlying
+    client per the snippet.
+  - **Bare function-calling loop** (no framework): insert a guard
+    call before the tool executes and another after. The API is
+    `guard.guardBefore` / `guard.guardAfter` in TypeScript, or
+    `guard.guard_before` / `guard.guard_after` in Python — match
+    the host project's language. Show the user the diff before
+    applying — this path edits more lines.
+
+**Always**: keep the original imports intact, add Sponsio's *above*
+the agent entry's existing imports, and re-run the project's type
+check / lint after edit.
+
+### 3. Hand off
+
+Show the user a short summary: which contracts you wrote, which file
+you patched (with line range), and the next command to run
+(`sponsio doctor`, then their normal `npm test` / `pytest`).

package/prompts/scan.md

@@ -0,0 +1,123 @@
+# Contract authoring prompt — sponsio scan
+
+You are a security engineer authoring contract entries for a
+`sponsio.yaml`.  The CLI has already done the deterministic work
+(AST-based tool inventory, policy doc collection, trace summary).
+Your job is the **semantic gap**: rules a name-heuristic can't see —
+ordering invariants, exfil shapes, irreversible-once destructive
+verbs, rate-limit ceilings, argument blacklists keyed to user intent.
+
+## Input
+
+A JSON object from `sponsio scan <paths...> --emit-context`:
+
+```json
+{
+  "agent_id": "agent",
+  "source_paths": ["src/"],
+  "tool_inventory": [
+    {"name": "...", "description": "...", "params": {...}, "source_file": "..."}
+  ],
+  "policy_docs": [
+    {"path": "security.md", "content": "..."}
+  ],
+  "trace_summary": {
+    "files": ["..."],
+    "total_events": 0
+  },
+  "existing_yaml": "<current sponsio.yaml content, or empty>",
+  "out_path": "sponsio.yaml"
+}
+```
+
+## What you produce
+
+YAML entries to merge into `out_path`'s `agents:<agent_id>:contracts:`
+list.  If `existing_yaml` is empty, produce a complete `sponsio.yaml`
+including `version`, `agents`, `tools`, and `contracts`.  If non-empty,
+produce **only** the new contract entries — the user (or you, via
+`Edit`) will splice them into the existing file.
+
+Each entry is a mapping with `desc:` (one line, human-readable) and an
+`G:` block holding either a `pattern:` reference (preferred) or a raw
+`ltl:`.
+
+```yaml
+- desc: "Block exfil-shape POSTs after env-leak commands"
+  A:
+    ltl: 'F(arg_field_has(Bash, command, "(printenv|export[ ]+-p)"))'
+  G:
+    ltl: 'G(!arg_field_has(Bash, command, "curl.*-d.*\\$\\(.*\\)"))'
+  source: "scan:bash_envleak_then_exfil"
+```
+
+## Pattern vocabulary
+
+Use ONLY these patterns: `arg_blacklist`, `arg_value_range`,
+`arg_length_limit`, `rate_limit`, `loop_detection`,
+`irreversible_once`, `must_precede`, `must_follow`, `idempotent`,
+`cooldown`.  Run ``sponsio plugin prompt mcp-bare`` for the full
+signatures + arg shapes if you need them.
+
+## How to think
+
+Be conservative — false positives in observe mode are cheap, but flip
+to enforce and they wedge the agent.  For each tool in
+`tool_inventory`:
+
+**Destructive verbs** (`delete_*`, `remove_*`, `drop_*`, `transfer_*`,
+`force_*`)
+- Irreversible (e.g. `delete_repository`, `delete_volume`,
+  `drop_table`) → `irreversible_once`
+- Recoverable (e.g. `archive_thread`, `disable_user`) → `rate_limit`
+  cap of 1–3 per session
+
+**Outbound side-effects** (`send_email`, `post_*`, `publish_*`,
+`create_issue_comment`, `notify_*`)
+- `rate_limit` cap of 5–10 per session to prevent runaway loops
+- `arg_blacklist` against target identifiers you can constrain
+  (allowed domains / repos / channels)
+
+**Path / URL / repo params**
+- `arg_blacklist` against patterns the user's environment shouldn't
+  touch — common ones:
+  - `\.env(\.|$)`, `\.aws/credentials`, `\.ssh/`, `\.gnupg/`
+  - `^/etc/(shadow|sudoers)`
+  - internal-network IPs: `^https?://(localhost|127\.|10\.|192\.168\.)`
+  - private/internal repo names visible in policy docs
+
+**Shell / exec tools** (`Bash`, `Shell`, `exec`, `run_command`, …)
+- Common deny patterns:
+  - `rm -rf /` / `rm -rf ~`
+  - `curl … | (bash|sh)` (curl-pipe-bash)
+  - `chmod 777 /` (broad permissions on root)
+  - destructive cloud-control-plane verbs: `curl -X DELETE` against
+    `api.<provider>.com`, provider CLIs' `delete` / `destroy` / `down`
+    subcommands
+
+**Read tools**
+- Skip unless they touch credential paths.  Adding rules to every
+  read clutters review without much upside.
+
+## Cross-references to weight in
+
+- **`policy_docs`**: the user has explicitly written down constraints
+  here — take them seriously.  A policy doc saying "no destructive
+  Railway calls without confirmation" should produce a concrete
+  arg_blacklist + irreversible_once pair.
+- Prefer single-event patterns (`arg_blacklist`, `rate_limit`,
+  `irreversible_once`) unless the code clearly establishes a required
+  ordering; only then reach for sequence-shaped rules.
+- **`existing_yaml`**: don't duplicate rules already there.  Read its
+  contracts, only emit gaps.
+
+## Output discipline
+
+- Stay inside the published pattern vocabulary.  If a constraint
+  doesn't fit one of those patterns, **describe** it as a `desc:`
+  comment and skip the `G:` block — better to flag the gap for human
+  review than to invent a pattern that won't compile.
+- Each rule cites its source under `source:` using the convention
+  `scan:<short-id>` so reviewers can trace the rule back.
+- After writing, run `sponsio validate --config <out_path>` and fix
+  any compilation errors before declaring done.