fix(plan): drop low-relevance citations + word-boundary snippets

[rsnodgrass]

What broke

A rendered enriched plan (/ox-plan) surfaced low-quality citations: snippets clipped mid-word at both ends ("...HLS retry semantics", "...ive intelligence_1"), an unfilled ox starter template (glossary.md — "Define your team's critical domain-specific terms…") cited as a DISCUSSION, and the raw context[] bundle pasted verbatim as a flat card list with no provenance affordance. Investigation confirmed the "garbage" was real ledger content, badly retrieved and badly rendered — not a test fixture (e.g. scribe-y7r8 is a real beads issue ID), so the fix is relevance + snippet quality + render discipline, not a blocklist.

What this PR ships

Two independent layers — stop the noise at the source (CLI), and stop dumping it (render spec).

flowchart TB
  JSON["ox plan --json"] --> RET["context bundle retriever"]
  RET -->|"A1 score floor 0.55"| F1["drop weak single-token + barely-matched items"]
  RET -->|"A2 scaffold filter"| F2["drop unfilled ox starter templates"]
  RET -->|"A3 word-boundary snippet"| F3["snap edges to whole words, UTF-8 safe"]
  RET -->|"A4 dedup kind,ref"| F4["collapse duplicate sources"]
  F1 --> BUNDLE["clean bundle"]
  F2 --> BUNDLE
  F3 --> BUNDLE
  F4 --> BUNDLE
  BUNDLE --> AGENT["agent reasons to CITED badges, never pastes raw bundle"]
  AGENT --> HTML["render: per-kind provenance chip + (i) hover popover"]

Loading

A — CLI retrieval quality

• A1 score floor (internal/plan/context_bundle.go): minBundleScore = 0.55 applied in rankAndCap. Drops single-token team-doc matches (~0.43) and barely-relevant sessions (~0.48); a topic-only murmur (0.60) and solid session/doc hits still clear.
• A2 scaffold filter (internal/teamdocs/discover.go, frontmatter.go): skip unedited ox starter docs via a template: true frontmatter flag (forward-compatible) and body sentinel detection. Guarded so a filled-in doc survives.
• A3 word-boundary snippets (internal/ledgersearch/ledgersearch.go): snippetAround now snaps both edges to whole-word boundaries; cutting only at ASCII whitespace is inherently UTF-8 safe, with a rune-aligned fallback for over-long single tokens.
• A4 dedup: rankAndCap collapses duplicate (kind, ref) items, keeping the highest score.

B — render spec (extensions/claude/commands/ox-plan.md)

• B1: explicit "NEVER paste the context[] bundle verbatim" rule + a worked bundle-item to cited-badge example. The bundle is reasoning input, not render output.
• B2: per-kind provenance chip table (ADR / decision / team context / ledger·session / commit / active-work, palette-colored) and a keyboard-accessible (i) hover popover — pure CSS + tiny vanilla JS, file://-safe, theme-aware — showing source kind, author, when, cleaned snippet, and resolved link.

Test Plan

• New table-driven tests, all green (internal/plan, internal/ledgersearch, internal/teamdocs):
  • A1: sub-floor items dropped; A4: duplicate (kind,ref) collapsed to highest score.
  • A2: sentinel scaffold + template:true excluded; filled glossary survives.
  • A3: no mid-word truncation; UTF-8 never split; elision markers only where text was cut.
• make lint → 0 issues. make format clean (unrelated repo-wide gofmt drift reverted to keep this PR focused).

---

Checklist (expand if needed)

• Tests added
• CHANGELOG entry — N/A (internal retrieval/render quality, no user-facing CLI surface change)
• Breaking change — none
• /security-review — N/A (no internal/auth/, internal/mcp/, raw_writer.go, prepush_scan.go, internal/upgrade/, or go.sum touched)

Co-Authored-By: SageOx

[coderabbitai]

Warning

Review limit reached

@rsnodgrass, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 93 minutes and 1 second. Learn how PR review limits work.

Your organization has run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 73d101ad-4141-499e-83ad-281329eb7fdd

📥 Commits

Reviewing files that changed from the base of the PR and between 25500f0 and 5b14201.

📒 Files selected for processing (9)

• .gitignore
• extensions/claude/commands/ox-plan.md
• internal/ledgersearch/ledgersearch.go
• internal/ledgersearch/ledgersearch_test.go
• internal/plan/context_bundle.go
• internal/plan/context_bundle_test.go
• internal/teamdocs/discover.go
• internal/teamdocs/discover_test.go
• internal/teamdocs/frontmatter.go

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch ryan/ox-plan-command-vs-skill

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}