fix(ui): stop linking foreign tracker keys as Paperclip issues (#7511)

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>

ui/src/components/MarkdownBody.test.tsx

@@ -2,7 +2,7 @@
 
 import type { ComponentProps, ReactNode } from "react";
 import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
-import { describe, expect, it, vi } from "vitest";
+import { afterEach, describe, expect, it, vi } from "vitest";
 import { renderToStaticMarkup } from "react-dom/server";
 import {
   buildAgentMentionHref,
@@ -34,6 +34,18 @@ vi.mock("../api/issues", () => ({
   issuesApi: mockIssuesApi,
 }));
 
+// Defaults to null (no provider) so the existing suite exercises the permissive
+// path unchanged. Gating tests override the return value per-case.
+const mockUseOptionalCompany = vi.hoisted(() => vi.fn<() => { companies: Array<{ issuePrefix: string }> } | null>(() => null));
+
+vi.mock("../context/CompanyContext", () => ({
+  useOptionalCompany: mockUseOptionalCompany,
+}));
+
+afterEach(() => {
+  mockUseOptionalCompany.mockReturnValue(null);
+});
+
 function renderMarkdown(
   children: string,
   seededIssues: Array<{ identifier: string; status: string; title?: string }> = [],
@@ -486,4 +498,38 @@ describe("MarkdownBody", () => {
     expect(html).toContain("paperclip-markdown-issue-ref");
     expect(html).not.toContain("paperclip-mention-chip--issue");
   });
+
+  it("gates bare-identifier auto-linking to known company prefixes", () => {
+    mockUseOptionalCompany.mockReturnValue({ companies: [{ issuePrefix: "PAP" }] });
+
+    const html = renderMarkdown("Depends on PAP-1271 and blocked by JIRA-2.", [
+      { identifier: "PAP-1271", status: "done" },
+      { identifier: "JIRA-2", status: "done" },
+    ]);
+
+    // Known prefix links; foreign tracker key stays as plain text.
+    expect(html).toContain('href="/issues/PAP-1271"');
+    expect(html).not.toContain('href="/issues/JIRA-2"');
+    expect(html).toContain("blocked by JIRA-2.");
+  });
+
+  it("stays permissive when companies are loaded but the list is empty", () => {
+    mockUseOptionalCompany.mockReturnValue({ companies: [] });
+
+    const html = renderMarkdown("See JIRA-2 for context.", [
+      { identifier: "JIRA-2", status: "done" },
+    ]);
+
+    expect(html).toContain('href="/issues/JIRA-2"');
+  });
+
+  it("never gates explicit internal issue paths, even for unknown prefixes", () => {
+    mockUseOptionalCompany.mockReturnValue({ companies: [{ issuePrefix: "PAP" }] });
+
+    const html = renderMarkdown("See /ACME/issues/ACME-1 for the writeup.", [
+      { identifier: "ACME-1", status: "done" },
+    ]);
+
+    expect(html).toContain('href="/issues/ACME-1"');
+  });
 });

ui/src/components/MarkdownBody.tsx

@@ -6,6 +6,7 @@ import remarkGfm from "remark-gfm";
 import { cn } from "../lib/utils";
 import { Link } from "@/lib/router";
 import { useTheme } from "../context/ThemeContext";
+import { useOptionalCompany } from "../context/CompanyContext";
 import { mentionChipInlineStyle, parseMentionChipHref } from "../lib/mention-chips";
 import { issuesApi } from "../api/issues";
 import { queryKeys } from "../lib/queryKeys";
@@ -570,12 +571,19 @@ export function MarkdownBody({
   onImageClick,
 }: MarkdownBodyProps) {
   const { theme } = useTheme();
+  // Read company prefixes non-throwingly: MarkdownBody renders in surfaces that
+  // may lack a CompanyProvider. A null context (or no companies yet) leaves
+  // knownPrefixes undefined, which keeps issue auto-linking permissive.
+  const company = useOptionalCompany();
+  const knownPrefixes = company?.companies.length
+    ? company.companies.map((c) => c.issuePrefix)
+    : undefined;
   const remarkPlugins: NonNullable<Options["remarkPlugins"]> = [remarkGfm];
   if (enableWikiLinks) {
     remarkPlugins.push(createRemarkWikiLinks({ wikiLinkRoot, resolveWikiLinkHref }));
   }
   if (linkIssueReferences) {
-    remarkPlugins.push(remarkLinkIssueReferences);
+    remarkPlugins.push([remarkLinkIssueReferences, { knownPrefixes }]);
   }
   if (softBreaks) {
     remarkPlugins.push(remarkSoftBreaks);

ui/src/context/CompanyContext.tsx

@@ -176,3 +176,13 @@ export function useCompany() {
   }
   return ctx;
 }
+
+/**
+ * Non-throwing variant of {@link useCompany}. Returns null when called outside a
+ * CompanyProvider instead of throwing, so components that may render in
+ * provider-less surfaces (e.g. exported/standalone markdown) can read company
+ * state without crashing.
+ */
+export function useOptionalCompany(): CompanyContextValue | null {
+  return useContext(CompanyContext);
+}

ui/src/lib/issue-reference.test.ts

@@ -1,5 +1,15 @@
 import { describe, expect, it } from "vitest";
-import { parseIssuePathIdFromPath, parseIssueReferenceFromHref } from "./issue-reference";
+import { parseIssuePathIdFromPath, parseIssueReferenceFromHref, remarkLinkIssueReferences } from "./issue-reference";
+
+type TreeNode = { type: string; value?: string; url?: string; children?: TreeNode[] };
+
+function paragraph(value: string): TreeNode {
+  return { type: "root", children: [{ type: "paragraph", children: [{ type: "text", value }] }] };
+}
+
+function paragraphChildren(tree: TreeNode): TreeNode[] {
+  return tree.children?.[0]?.children ?? [];
+}
 
 describe("issue-reference", () => {
   it("extracts issue ids from company-scoped issue paths", () => {
@@ -66,4 +76,74 @@ describe("issue-reference", () => {
     expect(parseIssueReferenceFromHref("/issues/:id")).toBeNull();
     expect(parseIssueReferenceFromHref("http://localhost:3100/api/issues/:id")).toBeNull();
   });
+
+  describe("known-prefix gating", () => {
+    it("links a bare identifier whose prefix is known", () => {
+      expect(parseIssueReferenceFromHref("PAP-1271", new Set(["PAP"]))).toEqual({
+        issuePathId: "PAP-1271",
+        href: "/issues/PAP-1271",
+      });
+    });
+
+    it("matches the prefix case-insensitively", () => {
+      expect(parseIssueReferenceFromHref("pap-12", new Set(["PAP"]))).toEqual({
+        issuePathId: "PAP-12",
+        href: "/issues/PAP-12",
+      });
+    });
+
+    it("does not link a bare identifier whose prefix is unknown (e.g. a Jira key)", () => {
+      expect(parseIssueReferenceFromHref("JIRA-456", new Set(["PAP"]))).toBeNull();
+    });
+
+    it("stays permissive when no prefix set is supplied", () => {
+      expect(parseIssueReferenceFromHref("FOO-1")).toEqual({
+        issuePathId: "FOO-1",
+        href: "/issues/FOO-1",
+      });
+    });
+
+    it("stays permissive when the prefix set is empty", () => {
+      expect(parseIssueReferenceFromHref("FOO-1", new Set())).toEqual({
+        issuePathId: "FOO-1",
+        href: "/issues/FOO-1",
+      });
+    });
+
+    it("never gates explicit issue:// scheme references", () => {
+      expect(parseIssueReferenceFromHref("issue://ACME-9", new Set(["PAP"]))).toEqual({
+        issuePathId: "ACME-9",
+        href: "/issues/ACME-9",
+      });
+    });
+
+    it("never gates explicit /issues/ path references", () => {
+      expect(parseIssueReferenceFromHref("/ACME/issues/ACME-9", new Set(["PAP"]))).toEqual({
+        issuePathId: "ACME-9",
+        href: "/issues/ACME-9",
+      });
+    });
+  });
+
+  describe("remarkLinkIssueReferences", () => {
+    it("links only known-prefix tokens and leaves foreign keys as text", () => {
+      const tree = paragraph("See PAP-1 and JIRA-2 today.");
+      remarkLinkIssueReferences({ knownPrefixes: ["PAP"] })(tree);
+
+      const children = paragraphChildren(tree);
+      expect(children).toEqual([
+        { type: "text", value: "See " },
+        { type: "link", url: "/issues/PAP-1", children: [{ type: "text", value: "PAP-1" }] },
+        { type: "text", value: " and JIRA-2 today." },
+      ]);
+    });
+
+    it("links every identifier when no prefixes are supplied (legacy permissive)", () => {
+      const tree = paragraph("See PAP-1 and JIRA-2.");
+      remarkLinkIssueReferences()(tree);
+
+      const links = paragraphChildren(tree).filter((node) => node.type === "link");
+      expect(links.map((node) => node.url)).toEqual(["/issues/PAP-1", "/issues/JIRA-2"]);
+    });
+  });
 });

ui/src/lib/issue-reference.ts

@@ -23,7 +23,10 @@ export function parseIssuePathIdFromPath(pathOrUrl: string | null | undefined):
   return BARE_ISSUE_IDENTIFIER_RE.test(issuePathId) ? issuePathId.toUpperCase() : issuePathId;
 }
 
-export function parseIssueReferenceFromHref(href: string | null | undefined) {
+export function parseIssueReferenceFromHref(
+  href: string | null | undefined,
+  knownPrefixes?: Set<string>,
+) {
   if (!href) return null;
   const trimmed = href.trim();
   const issueSchemeMatch = trimmed.match(ISSUE_SCHEME_RE);
@@ -45,6 +48,15 @@ export function parseIssueReferenceFromHref(href: string | null | undefined) {
 
   if (!BARE_ISSUE_IDENTIFIER_RE.test(trimmed)) return null;
   const normalized = trimmed.toUpperCase();
+  // Only auto-link a bare IDENT-123 token when its prefix belongs to a known
+  // company. An empty or omitted set means "prefixes unknown" -> stay permissive
+  // (preserves behavior during initial load and in provider-less render
+  // surfaces). The issue:// scheme and /issues/ path forms handled above are
+  // never gated -- they are deliberate references, not accidental foreign keys.
+  if (knownPrefixes && knownPrefixes.size > 0) {
+    const prefix = normalized.split("-")[0];
+    if (!prefix || !knownPrefixes.has(prefix)) return null;
+  }
   return {
     issuePathId: normalized,
     href: `/issues/${encodeURIComponent(normalized)}`,
@@ -83,7 +95,7 @@ function createIssueLinkNode(value: string, href: string, childType: "text" | "i
   };
 }
 
-function linkifyIssueReferencesInText(value: string): MarkdownNode[] | null {
+function linkifyIssueReferencesInText(value: string, knownPrefixes?: Set<string>): MarkdownNode[] | null {
   const nodes: MarkdownNode[] = [];
   let cursor = 0;
   let matched = false;
@@ -95,7 +107,7 @@ function linkifyIssueReferencesInText(value: string): MarkdownNode[] | null {
     const start = match.index ?? 0;
     const end = start + raw.length;
     const { core, trailing } = splitTrailingPunctuation(raw);
-    const issueRef = parseIssueReferenceFromHref(core);
+    const issueRef = parseIssueReferenceFromHref(core, knownPrefixes);
     if (!issueRef) continue;
 
     matched = true;
@@ -116,7 +128,7 @@ function linkifyIssueReferencesInText(value: string): MarkdownNode[] | null {
   return nodes;
 }
 
-function rewriteMarkdownTree(node: MarkdownNode) {
+function rewriteMarkdownTree(node: MarkdownNode, knownPrefixes?: Set<string>) {
   if (!Array.isArray(node.children) || node.children.length === 0) return;
   if (node.type === "link" || node.type === "linkReference" || node.type === "code" || node.type === "definition" || node.type === "html") {
     return;
@@ -125,7 +137,7 @@ function rewriteMarkdownTree(node: MarkdownNode) {
   const nextChildren: MarkdownNode[] = [];
   for (const child of node.children) {
     if (child.type === "inlineCode" && typeof child.value === "string") {
-      const issueRef = parseIssueReferenceFromHref(child.value);
+      const issueRef = parseIssueReferenceFromHref(child.value, knownPrefixes);
       if (issueRef) {
         nextChildren.push(createIssueLinkNode(child.value, issueRef.href, "inlineCode"));
         continue;
@@ -133,21 +145,35 @@ function rewriteMarkdownTree(node: MarkdownNode) {
     }
 
     if (child.type === "text" && typeof child.value === "string") {
-      const linked = linkifyIssueReferencesInText(child.value);
+      const linked = linkifyIssueReferencesInText(child.value, knownPrefixes);
       if (linked) {
         nextChildren.push(...linked);
         continue;
       }
     }
 
-    rewriteMarkdownTree(child);
+    rewriteMarkdownTree(child, knownPrefixes);
     nextChildren.push(child);
   }
   node.children = nextChildren;
 }
 
-export function remarkLinkIssueReferences() {
+export interface RemarkLinkIssueReferencesOptions {
+  /**
+   * Company issue prefixes that are eligible for auto-linking. When provided
+   * and non-empty, a bare IDENT-123 token only becomes an issue link if its
+   * prefix is in this set -- this keeps foreign tracker keys (e.g. a Jira
+   * "TREE-604") from linking to non-existent Paperclip issues. Omit or pass an
+   * empty list to keep the legacy permissive behavior (link any IDENT-123).
+   */
+  knownPrefixes?: string[];
+}
+
+export function remarkLinkIssueReferences(options?: RemarkLinkIssueReferencesOptions) {
+  const knownPrefixes = options?.knownPrefixes && options.knownPrefixes.length > 0
+    ? new Set(options.knownPrefixes.map((prefix) => prefix.toUpperCase()))
+    : undefined;
   return (tree: MarkdownNode) => {
-    rewriteMarkdownTree(tree);
+    rewriteMarkdownTree(tree, knownPrefixes);
   };
 }