propose_sensor
Convert a captured gotcha into a discriminating sensor that blocks faulty code by matching the mistake pattern while ignoring correct usage via an absent regex. Validates the proposal against real examples before it becomes a reliable gate.
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). 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; `absent` is a sub-pattern that must be missing INSIDE the match (requires the optional @ast-grep/napi 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. | |
| 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. | |
| 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. |