to-triggers

# To-Triggers — Author Vault Gate Triggers from Intent Convert a stated rule into a trigger entry in `vault.yaml`. The division of labor is fixed: the user owns the intent ("never let a tag happen before the retro"); the agent owns the matching sophistication. A mis-authored trigger either never fires (silent protocol decay) or fails the `vault.yaml` load (fail-loud: one invalid trigger takes down every tool). Never hand the user a regex question they didn't ask for. ## Source of truth The trigger schema is read at use time, never from memory: - The `wiki` skill's `references/vault-yaml.md` § Harness gate triggers (ships alongside these skills) — field vocabulary and examples. - The vault's own `vault.schema.json` (vault root) and `kmd validate` — the runtime authority. When the reference file is unavailable, these suffice. ## Interview flow — recommend first Draft a complete trigger from the user's sentence, present it, and ask only what could not be inferred. Never open the interview with questions the intent already answers. 1. **Intent class.** Map the sentence: | The user wants | Class | Event | |---|---|---| | a reminder when a topic comes up | `inject` | `prompt` | | a nudge alongside a risky tool call | `inject` or `warn` | `pretool` | | an action denied until a precondition holds | `block` | `pretool` | Only `pretool` can block. A prompt-time rule that sounds like a gate ("never tag before the retro") is really a pretool block on the tagging command plus, optionally, a prompt-time reminder — propose both, let the user drop one. 2. **Matching draft.** Author the mechanics (rules below) with the trigger `id` (descriptive kebab-case; duplicate ids keep the first occurrence). 3. **Payload register.** `text` (inject) and `reason` (block) are read by an agent mid-session: one ASCII line naming the protocol pointer, no banners. A block `reason` tells the denied agent what to do instead, not just why. 4. **Scope.** Propose where it lands: the active scope's `triggers_extra` (additive), or `triggers_extra._all` for vault-wide. A full-replace `triggers` section only on explicit request — it drops the engine defaults and the compiled file source too. 5. **Precondition.** When the rule is state-dependent ("until the retro is newer than the release note"), attach `when: newer-than {fresh, than}` — the trigger fires when the predicate is FALSE, is suppressed when true, and is skipped loudly when unevaluable. The clock is frontmatter `updated`; an empty `than` set passes vacuously. Globs select the two page sets; each scope names its own retro/release conventions. ## Matching mechanics — the part the user never writes **Keywords (prompt inject).** The engine matches through a stemmed, word-boundary FTS5 porter table. Consequences: - Two or three distinctive keywords beat a long list. Never enumerate word forms — `release` already matches "releasing", "released". - Word-boundary matching kills substring false positives ("prerelease" does not match `release`); don't defend against them with regex. - `intent` regexes are the escape hatch for phrasings stemming cannot reach, not the default. **Pretool matchers.** AND-composed, deterministic: - `tool` equals the event's tool name. - `args_match` is an authored, anchored regex over the serialized tool input (compound commands included). Draft it against real command shapes — for "block force pushes": matches `git push --force origin main` and `git push -f`, does not match `echo "force push"`. Write the near-miss counterexamples down; they become the dry-run cases. - `files` globs are cwd-relativized: `**` crosses directories (`**/` may match empty), `*` stays within a segment, `?` is one character. **Noise budget.** Name the cost of a broad draft before accepting it: inject-class dedup defaults to once per session per trigger, so a broad keyword still fires in every session; block-class is exempt from dedup and fires on every matching event. Propose the narrower match first, with the broad one as the explicit fallback. Two consequences worth designing for: - One id sharing broad keywords and a sharp intent regex shares one dedup budget — an early keyword hit silences the sharp moment. Split into two triggers when the sharp match must survive keyword noise. - The `dedup` field overrides the default per trigger: `never` (every match — pair only with sharp matchers), `{minutes: N}` (re-fires each bucket within a session — for long sessions that outlive their context). The schema rejects `dedup` on block triggers. ## Test before write — the dry-run loop No draft touches `vault.yaml` untested. Write the candidate entries to a temp file as a bare YAML list (exactly the entries, not nested under a scope key) and pipe synthetic events through the engine: ```bash cat > /tmp/triggers-draft.yaml <<'EOF' - id: release-protocol-reminder on: prompt enforce: inject keywords: [tagging, releasing] text: "Release protocol: ops-publish-kmd is the release chain." EOF ``` **Synthetic events** — one JSON object on stdin per run, always with `--explain`: ```bash # prompt event: {"session_id": "...", "prompt": "...", "cwd": "..."} printf '%s' '{"session_id":"dry-1","prompt":"thinking about releasing tomorrow","cwd":"/tmp"}' \ | kmd hook prompt <vault-root> --explain --triggers /tmp/triggers-draft.yaml # pretool event: {"session_id": "...", "tool_name": "...", "tool_input": {...}, "cwd": "..."} printf '%s' '{"session_id":"dry-2","tool_name":"Bash","tool_input":{"command":"git push --force origin main"},"cwd":"/tmp"}' \ | kmd hook pretool <vault-root> --explain --triggers /tmp/triggers-draft.yaml ``` **Reading the trace.** `--explain` prints one JSON object naming the resolved scope and, per trigger: the matcher verdict (`hit`, or which stage missed — `tool-miss`/`args-miss`/`files-miss`/`payload-miss`; prompt triggers carry `keywords`/`intent` evidence instead), the typed predicate verdict (`satisfied`/`unmet`/`vacuous`/`unknown`), the dedup verdict (`exempt`/`never`/`fresh`/`suppressed`), whether it fired, and the exact outcome the harness would receive. Diagnose a near-miss from the trace, never from empty output. Hook events always exit 0 — the trace is the only signal. **No state spent.** `--explain` never writes dedup state: probes repeat stably, and a probe never silences the trigger for a live session. A `dedup: "suppressed"` verdict means existing session state already carries the key — retest under a throwaway `session_id` (`dry-1`, `dry-2`, …) to see the fresh path. **Fire + near-miss discipline.** Every matcher runs at least one intended-fire case and one near-miss counterexample, and the user sees both results. The near-misses were written down while drafting the matcher — "prerelease" against `keywords: [releasing]` (word boundary holds), `echo "force push"` against the force-push regex (no match). A matcher proven only on its fire case is untested. **Predicate drafts.** A `when: newer-than` candidate is tested against the real vault filesystem read-only — the vault-root argument points at the real vault so the globs select real pages. Never fabricate retro or release fixtures inside a real vault to make a predicate evaluate. ## Write gate 1. Show the exact YAML block and its target key. 2. Write only on explicit approval — `vault.yaml` is a controlled-vocabulary surface. 3. Run `kmd validate` after the write. Red means revert before anything else: an invalid config fails the load for every tool, not just the new trigger.