feat(query): resolve --pipeline names client-side in audit/snapshot (v1.6.2)

[alexskatell]

Why

query audit and query snapshot in v1.6.1 only accept opaque 20-char pipeline IDs. Passing a human-readable name (e.g. 'Sales - Flex - Triage') silently returned rows: [] because the literal string got jammed into WHERE pipeline_id = '...', which never matches.

Live failure trace (Paul, 2026-05-14):

1. topline --agent query doctor ✓
2. topline --agent query audit --pipeline 'Sales - Flex - Triage' --since this-week-et → rows: []
3. topline --agent query sql --sql "SELECT id, name FROM pipelines WHERE LOWER(name) LIKE '%flex%' OR LOWER(name) LIKE '%triage%'" — the agent correctly diagnoses "wrong identifier" and writes raw SQL to translate the name
4. topline --agent query audit --pipeline bna6e9DoPgRchNsjeYS3 --since this-week-et — now it works

That third call is the loophole shape: a primitive gap that forces a raw-SQL wrapper round-trip the skill rules can't bind. Per the auto-memory rule of thumb that landed during the earlier audit-contract work — after three failed skill iterations, build the primitive instead of writing another rule — we're moving the lookup into the CLI rather than tightening pitfall #N+1.

What

• New resolvePipelineID() runs before the audit/snapshot SQL:
  • Opaque 20-char ID (e.g. CLUy1QapsrEeBiNrmQiL) passes through unchanged.
  • Otherwise tokens are AND'd as case-insensitive LIKEs against pipelines.name.
  • 1 match → use it; surface pipelineResolution: {input, matchedId, matchedName, matchedBy: "name"} in the JSON envelope.
  • 0 matches → error lists every available pipeline (Available pipelines: A (id), B (id), …).
  • >1 matches → error lists the candidates and asks for a more specific name.
• Audit and snapshot JSON gain pipelineResolution, so agents (and humans) see exactly how --pipeline was matched.
• Skill docs (skills/hermes/SKILL.md + skills/claude-code/SKILL.md) bumped to v1.6.2:
  • --pipeline now reads as PIPELINE_ID_OR_NAME.
  • New banned-in-default-flow rule: don't run raw query sql to resolve a pipeline name to its ID — query audit/snapshot handle it.
  • Pitfall #17 documents the v1.6.1 failure trace and the v1.6.2 fix.

Tests

• TestQueryAuditResolvesPipelineByName — 'flex triage' resolves to the Triage opaque ID; pipelineResolution.matchedId/matchedName/matchedBy are echoed; audit SQL uses the resolved ID.
• TestQueryAuditUnknownPipelineListsCandidates — 'no such pipeline' errors with the available-pipelines list.
• TestQueryAuditAmbiguousPipelineErrors — 'flex' errors listing both Flex pipelines with an "ambiguous" hint.
• TestQuerySnapshotResolvesPipelineByName — same resolver path for query snapshot.
• All existing tests still pass; go build ./... clean; full go test ./... green.

Expected agent trace after this lands

For What activity happened this week in our flex triage pipeline?:

skill_view topline-os-cli
skill_view topline-os-crm-audits
topline --agent query doctor
topline --agent query audit --pipeline 'flex triage' --since this-week-et --status open
answer (citing pipelineResolution.matchedName: "Sales - Flex - Triage")

No intermediate query sql, no python3 -<<'PY', no bash heredoc. The third tool call is gone.

Non-goals

• Doesn't change the on-the-wire query API or os-mcp views.
• Doesn't add bind-parameter support to query sql (separate, larger change).
• Doesn't try to fuzzy-match opaque IDs against names — IDs always pass through.