Make search output self-describing for LLM consumers

[pinkhasn]

Six output-informativeness features for LLM-facing modes, from the idea list discussed in-session. All are additive; the only default-output changes are deliberate (new footers, role tags), and every feature has an opt-out or is opt-in.

Query legend (-desc) and zero-match footer

• -desc <text> names a pattern's meaning (also description in -patterns-from rules). When any pattern has one, -llm/-elide/-rollup output opens with an echo of the interpreted query plus a one-line legend per pattern — result blocks survive transcript summarization on their own.
• A batched pattern with zero kept matches is named in a trailing --- no matches: ghost (1 of 2 patterns) --- footer instead of vanishing silently. Whole-scan, post-filter counts; qualified with (scan stopped early) when a limit cut the scan.

Per-match role tags

• New lexer module (src/roles.cpp): single-pass, escape-aware comment/string span index per matched file (7 scope-pack languages + py/sh/rb/yaml/toml), plus import-line marking.
• Surfaces: "role" field in JSONL, [comment]/[string]/[import] tags in -llm, $ROLE in -format. With -scope active, a hit on a signature line renders [def func X] instead of the misleading [in func X].
• Position-accurate roles win (a trailing comment on a signature line is a comment). Built lazily only for files that produce output; -no-roles disables.

Scope rollup (-rollup)

• New output mode: one line per innermost enclosing scope — line range, kind/name, count-descending per-pattern breakdown, first matched line as representative. Scopeless matches group as (top level), so files without a scope pack collapse to per-file summaries. Implies -scope auto.

Co-occurrence footer

• With ≥2 matching patterns, -llm/-elide/-rollup end with per-pattern distinct-file counts and the overlap: exact both: crosstab for two patterns, multi-pattern: file list with pattern sets for more. both: 0 is stated explicitly.

Stable refs and the expand verb

• hprscript expand <file:line[@hash]> prints a hit's full enclosing scope — the drill-down half of the search → expand loop; batches refs, falls back to a marked context window for scopeless lines, honors -max-block-bytes.
• -refs appends a 6-hex trimmed-line content hash to -llm/-rollup line numbers. expand verifies it: moved lines are recovered by content (ref line moved: 6 → 7), vanished ones report stale in-band with exit 3 — never silently the wrong code.

Testing

• ~110 new assertions in tests/run.sh (620 total, all passing), including literal FNV-1a hash values, moved-ref recovery, footer qualifiers, precedence cases, and mode-conflict validation.
• Docs updated throughout: HPRSCRIPT.md sections for each feature, flag tables, --help, and both agent skills.

🤖 Generated with Claude Code