Fixes#7514 — the prefix-validation piece of the #5456 auto-linker
404-storm umbrella. The remaining pieces (404 retry guard, word-boundary
tightening, comment edit/soft-delete) stay open under #5456.
Part of #5456.
## Thinking Path
> - Paperclip orchestrates AI agents for zero-human companies
> - Agents and humans cross-reference work in markdown — issue
descriptions, comments, documents — which the UI renders through a
shared `MarkdownBody`
> - That renderer auto-links any `IDENT-123`-shaped token to an internal
`/issues/IDENT-123` link
> - But foreign tracker keys share that exact shape: a Jira `TREE-604`
(or any external `ORG-123`) mentioned in prose becomes a link to a
Paperclip issue that does not exist — it 404s, and the renderer also
fires a wasted issue-fetch for the bogus identifier
> - The set of real issue prefixes is already in the browser: every
company carries an `issuePrefix`, exposed via `CompanyContext`
> - This PR gates bare-token auto-linking to known company prefixes,
leaving explicit `issue://` / `/issues/` references and real markdown
links untouched
> - The benefit is no dead internal links from foreign keys, with no new
query, cache, or server change — and zero regression when prefixes
aren't yet known
## What Changed
- **`ui/src/lib/issue-reference.ts`** — `parseIssueReferenceFromHref`
takes an optional `knownPrefixes` set and rejects a bare `IDENT-123`
token whose prefix isn't in it; threaded through
`remarkLinkIssueReferences(options)` → tree rewrite → text and
inline-code paths. An omitted/empty set keeps the legacy permissive
behavior. Explicit `issue://` scheme and `/issues/` path forms are never
gated.
- **`ui/src/context/CompanyContext.tsx`** — adds `useOptionalCompany()`,
a non-throwing variant of `useCompany()` (returns `null` outside a
provider).
- **`ui/src/components/MarkdownBody.tsx`** — reads company prefixes via
`useOptionalCompany()` and passes them to the linkifier. The
non-throwing read keeps `MarkdownBody` renderable in provider-less
surfaces (e.g. standalone/exported markdown).
- Tests extended in `issue-reference.test.ts` (gating + remark-plugin
cases) and `MarkdownBody.test.tsx` (gating, empty-companies permissive,
explicit-path bypass).
## Verification
- `pnpm --filter @paperclipai/ui exec vitest run
src/lib/issue-reference.test.ts src/components/MarkdownBody.test.tsx` —
green (17 + 40 tests).
- Full UI suite: `pnpm --filter @paperclipai/ui exec vitest run` —
**1161 passed / 183 files**; pre-existing `MarkdownBody` link tests pass
unmodified (they hit the permissive `null`-context path), confirming no
regression.
- `pnpm --filter @paperclipai/ui run typecheck` — clean.
- _Screenshots pending — opening as draft; before/after images to follow
before marking ready._
- Manual (before/after): in an issue description containing both a real
Paperclip identifier and a Jira key — _before_ both render as
`/issues/...` links (the Jira one dead); _after_ only the real
identifier links and the Jira key is plain text.
## Risks
- **Low risk.** No server/API/migration change; pure client rendering
logic.
- A referenced issue whose company isn't in the viewer's `companies`
list stops auto-linking — acceptable, since that internal link wouldn't
resolve for that viewer anyway; explicit `/issues/IDENT` references
still render.
- During initial load (companies not yet fetched) behavior is identical
to today (permissive), so no new flicker.
## Model Used
- **Anthropic Claude Opus 4.8** (`claude-opus-4-8`), 1M-token context,
extended thinking + tool use. Plan authored and implemented with the
model; all decisions reviewed by the human contributor.
## Checklist
- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [ ] If this change affects the UI, I have included before/after
screenshots
- [x] I have updated relevant documentation to reflect my changes (no
doc changes required — behavior gated, no public API/doc surface
affected)
- [x] I have considered and documented any risks above
- [x] I will address all Greptile and reviewer comments before
requesting merge
---------
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Pat Newell
bc0a076e13