Add a detection signature

Detection is pure, versioned, public data: a match maps added diff lines to a slug from the closed vocabulary in taxonomy.json — locally, deterministically, zero network. Adding a signature means adding data, not code. The authoritative contract is docs/signatures.md; this skill is the step-by-step path through it.

Step 1 — does the slug exist?

Check taxonomy.json for the slug you want to map to. If it's missing, adding it is a separate PR first, with a short rationale for the new vocabulary — a signature naming a slug outside taxonomy.json fails at load time, and new vocabulary is reviewed on its own before anything depends on it. Never bundle a new slug into the signature PR that needs it.

Step 2 — pick the tier

Tier 1 (a one-line entry in signatures/package-map.json) when the bare import unambiguously identifies the technology: importing stripe means using Stripe, full stop.

Tier 2 (a JSON file at signatures/<category>/<name>.json) when:

• there is no import at all (Docker, Terraform, CI workflows — detected by file path), or
• the import is ambiguous (@supabase/supabase-js serves both auth and db; only the API shape disambiguates), or
• detection is by inheritance, not declaration (class X < ApplicationRecord).

Step 3a — Tier 1 entry

Add "package-name": "category/slug" to signatures/package-map.json. The key must be the name as the import extractor actually produces it (src/import-detect.ts) — the classic dead-key traps:

• Python/Ruby: the key is the IMPORT name, not the distribution name (bs4, never beautifulsoup4).
• JVM: the key is the real import root, never the Maven/Gradle groupId when they differ (lombok, never org.projectlombok).
• Rust: hyphens normalize to underscores (actix_web, not actix-web).
• Dotted keys (JVM/C#): no key may be a strict prefix of another dotted key — test/package-map.test.ts enforces this; pick the depth that distinguishes the library (com.google.gson at 3) or umbrellas it (org.springframework at 2).

Step 3b — Tier 2 file

{
  "slug": "category/slug",
  "importPatterns": ["from\\s+[\"']thing[\"']"],
  "apiPatterns": ["\\bthing\\.(verb1|verb2)\\b"],
  "configFilePatterns": [],
  "fixtures": {
    "positive": [{ "path": "src/lib/thing.ts", "diff": "+import thing from \"thing\"" }],
    "negative": [{ "path": "README.md", "diff": "+We evaluated thing and chose otherthing" }]
  }
}

• One signature file per slug, maximum — the test suite rejects a slug claimed by two files.
• Patterns are OR'd: any one of the three arrays matching is enough. Each array may be [], but at least one pattern must exist overall.
• configFilePatterns match the touched file's PATH; importPatterns/apiPatterns match the commit's ADDED lines only.
• Patterns are regexes inside JSON — escape backslashes twice (\\b).
• Pattern discipline: match the library's own unmistakable surface, never a generic shape (extends Model is too generic; the specific use Illuminate\\Database\\Eloquent\\Model; import is not).

Step 4 — fixtures (the tests will hold you to this)

test/skill-detect.test.ts runs every signature file against its own fixtures and fails the suite unless:

• at least one positive AND one negative fixture exist;
• every positive fixture actually matches the signature;
• no negative fixture matches (it must be a near-miss, not noise);
• every declared pattern is exercised by at least one positive fixture (dead or typo'd patterns fail);
• at least one negative fixture is a genuine near-miss that mentions the library by name — a comment, a doc line, a string literal — not an unrelated diff.

Step 5 — close out

npm test   # picks up new map entries and signature files automatically

Add a line to CHANGELOG.md under [Unreleased], then open the PR. If your change is a Tier 1 map entry with an existing slug, no discussion issue is needed — it's taxonomy-valid public data, the most welcome one-line PR this repo has.

Privacy gate

This repo's product is trust: the CLI promises that source code never leaves the machine and that everything which does leave is bounded, reviewable, and enumerable. Every PR is reviewed against that promise. This skill is the same review, run by you (or your agent) first, so the PR arrives already clean.

Authoritative sources — this skill summarizes them, they win on conflict: docs/principles.md, docs/privacy-tests.md, CONTRIBUTING.md ("The privacy rule").

Step 1 — the boundary question (before anything else)

Does the diff change WHAT data leaves the user's machine, or WHERE it is sent? Tripwires — any one means YES:

• A new or changed field in the bundle (anything under schema/).
• Any edit to taxonomy.json, or to hashing/salting (src/hash.ts, src/salt.ts).
• A new network call anywhere, or any edit to src/login.ts, src/submit.ts, src/submit-command.ts, src/http-client.ts.
• Any edit to src/secret-scan.ts or src/public-remote.ts.

If YES: stop before writing more code. The repo requires a prior discussion issue (the "Data boundary change" issue template) where the schema version bump and docs/schema.md/CHANGELOG.md entries are agreed first. A PR in these areas without a prior issue will not be merged, regardless of quality.

Step 2 — run the contract

npm test           # includes test/privacy/ — the contract
npx tsc --noEmit

If a test under test/privacy/ fails, the change is wrong, not the test. Do not adjust a privacy test to make a change pass; that inverts the whole model.

Step 3 — mechanical sweeps over the diff

Run each against your branch's diff (git diff main...HEAD):

# Network surface: scan/explain must make ZERO network calls. Direct network
# primitives are allowed in exactly three files (test/privacy/zero-network.test.ts):
# http-client.ts, login.ts, submit.ts; submit-command.ts only imports them.
git diff main...HEAD -- src ':(exclude)src/login.ts' ':(exclude)src/submit.ts' \
  ':(exclude)src/submit-command.ts' ':(exclude)src/http-client.ts' \
  | grep -nE '^\+.*(fetch\(|https?://|net\.|dgram|WebSocket)'

# Closed vocabulary: skill slugs live in taxonomy.json and signatures/, never in
# src/. The alternation mirrors taxonomy.json's full category set — if a new
# category lands there, add it here too.
git diff main...HEAD -- src | grep -nE '^\+.*"(auth|payments|ai|db|backend|frontend|infra|data|queues|testing|observability|email|realtime|storage)/'

# Supply chain: any new dependency requires written justification in the PR.
git diff main...HEAD -- package.json

# No postinstall scripts, ever.
grep -n 'postinstall' package.json

An empty result on each sweep is the expected state. A hit is not automatically a violation — but it must be explained in the PR description, in writing.

Step 4 — if the diff touches detection

Signature changes have their own contract (fixtures, near-miss negatives, dead-pattern checks) — run the add-signature skill in this directory, or read docs/signatures.md.

Step 5 — report in the PR

Paste a short block in the PR description:

Privacy gate: run
- Boundary question: NO (or: YES — prior issue #NN)
- npm test / tsc: green
- Sweeps: clean (or: hit in <file>, explained below)

A PR that arrives with this block gets reviewed faster, because it answers the reviewer's first four questions up front.