propose_sensor
Propose a code pattern to catch a specific mistake, validate it against correct usage to ensure it only fires on the bug, and get an acceptance decision to enforce the rule.
Instructions
Propose a discriminating sensor for a gotcha/attempt — YOU write the pattern (you understand the code), Hivelore validates it before trusting it to block. This is how a captured lesson becomes a RELIABLE block instead of an advisory note.
USE THIS right after mem_tried / mem_save on a gotcha whose mistake is detectable in code, to upgrade the auto-suggested (warn) sensor into a precise, promotable one.
Write a pattern that matches the FAULTY usage, and — crucially — an absent regex for the
CORRECT-usage marker so it fires on the bug only, not every call (e.g. pattern=the API call,
absent=the required option).
VALIDATION (a block proposal is accepted ONLY if): the pattern is not brittle, stays SILENT on
the current (correct) anchored code, and FIRES on the bad example. A rejected proposal is NOT
written — the returned reason/guidance tells you how to revise; then call propose_sensor again.
PARAMETERS: memory_id — the gotcha/attempt to protect pattern — regex matching the faulty usage absent — regex for the correct-usage marker (makes it discriminate) — strongly recommended bad_example— a snippet that SHOULD match (else examples are read from the lesson) severity — 'block' (default) | 'warn'
RETURNS: { accepted, reason?, guidance?, self_check, file_path? }
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| kind | No | regex = pattern matched on added diff lines (default; comments are stripped before matching, but string literals are NOT — so a regex can still target a bad literal in a string). ast = an ast-grep STRUCTURAL pattern (e.g. 'stripe.paymentIntents.create($$$)') matched on the AST of changed files — comments AND strings can never false-positive, so PREFER ast for a parseable language (JS/TS, Python, Go, Java, Rust, …) when the @ast-grep/napi engine is available; `absent` is a sub-pattern that must be missing INSIDE the match (requires that optional engine). shell|test = a COMMAND the gate runs when the diff touches the sensor's paths — routes the team's own oracle (an existing test, an invariant script) to this lesson. Command sensors only execute where enforcement.runCommandSensors=true. | regex |
| rule | No | kind=ast: full ast-grep Rule object (kind/inside/has/not/all/any/etc.). May be used alone or combined with pattern. | |
| flags | No | Optional regex flags (e.g. 'i' for case-insensitive). | |
| paths | No | Override scope paths. Defaults to the memory's anchor paths. | |
| absent | No | Regex for the CORRECT-usage marker (e.g. 'idempotencyKey'). When it appears in the window around a match, the catch is suppressed — this is what makes the sensor discriminate the faulty call from the correct one. STRONGLY recommended for 'X without Y' lessons. | |
| command | No | kind=shell|test: command to execute (e.g. 'npx vitest run tests/payments/refund.spec.ts'). Non-zero exit = the lesson fires. | |
| exclude | No | Glob-ish paths the sensor must NOT fire on, even inside `paths`. Set this for a PRODUCTION-ONLY lesson so it skips test doubles/fixtures — e.g. exclude ['**/*.test.*','**/*.spec.*','**/__tests__/**','**/*.stories.*','**/*.d.ts']. Leave empty for a lesson that IS about tests (it should still fire there). Documentation files (.md/.rst/…) are already skipped automatically. | |
| message | No | LLM-facing fix message shown when it fires. Defaults to one derived from the lesson. | |
| pattern | No | kind=regex: regex matching the faulty usage; kind=ast: optional structural pattern (may be combined with `rule`). | |
| red_ref | No | kind=shell|test: prove the oracle actually catches the incident. A git ref (commit/branch) of the PRE-FIX state; validation replays it in a scratch worktree and requires the command to FAIL there (RED) in addition to passing on the current tree (GREEN). On success the sensor records red_proven: true — 'the test demonstrably catches the incident', shown in the prevention receipt. | |
| replace | No | Set true to DELIBERATELY replace a sensor already hand-authored on this memory. Without it, a second proposal onto a memory that already carries a validated sensor is REFUSED — otherwise the second call silently destroys the first while still answering accepted:true. One memory holds one sensor; use a separate memory for a second, distinct symptom. | |
| incident | No | Provenance: the real incident this sensor guards — a ticket/prod ref ('prod #442', 'INC-1029', '2026-06 refund overcharge'). Turns 'a test failed' into 'this reproduces the incident the test exists to prevent'. Surfaced in the block message and the prevention receipt. Strongly recommended for command/test sensors routed from a post-incident test. | |
| language | No | kind=ast: explicit built-in/dynamic language name for non-standard file extensions. | |
| severity | No | block = hard-fail the gate (accepted ONLY if it passes self-validation). warn = advisory. | block |
| memory_id | Yes | Id of the gotcha/attempt memory this sensor protects. | |
| timeout_ms | No | kind=shell|test: max runtime before the executor kills the command (default 120000). | |
| bad_example | No | A code snippet that SHOULD match — proves the sensor catches the mistake. If omitted, examples are read from the lesson body. | |
| require_present | No | kind=regex: make this a REQUIRED-PRESENCE invariant instead of a forbidden-pattern one. `pattern` then names a line that must REMAIN in the anchored file; the sensor FIRES when a change REMOVES it. Use for 'do not delete this critical line' lessons a diff-of-added-lines sensor cannot see. Validated by requiring the pattern to be PRESENT in the current anchored code (there must be something to guard). |