feat: link #Heading section references in annotation text, and a skill that uses them

[centraldogma99]

You have probably hit this

You are reading a review in Plannotator. A comment says:

This contradicts 3.1.

So you hold that sentence in your head, scroll off to find 3.1, read it, scroll back, and reconstruct what the comment meant. Then the next comment mentions 3.2 and you do it again.

Every other part of this surface exists to spare you exactly that. An inline annotation is a pointer — click it in the panel and the document scrolls to the phrase. But the moment a comment refers to a different section, the pointer stops at the comment's own anchor and the rest is manual. Comment text renders as a bare string (<p>{annotation.text}</p>), so 3.1 is inert.

It bites hardest on GLOBAL_COMMENT, which by definition is anchored to no phrase at all, and on any remark whose whole point is that two sections disagree — the case where you most need both ends and have neither.

What this does

Writing # followed by a heading's exact text in a comment renders it as a link that scrolls the document to that heading.

#3.1 Single source of truth contradicts this.

Resolution is exact match against the document's own headings. That is the whole design: there is no grammar of section numbers to define, so 3.1, A., IV. and an unnumbered ## Authentication are all just heading text, and nothing has to be taught about numbering schemes that vary per document.

It is also what keeps the common non-references inert, without a denylist:

Input	Result
#fff, #123	plain — needs a heading literally named fff / 123
C#	plain — a # welded to a word is part of that word
# Heading	plain — space after # is markdown heading intent
`#Overview`	plain — backtick spans are never scanned
duplicate heading title	plain — a reference that could mean either is not a reference

Longest match wins, so a document with both 3.1 and 3.1 Scope resolves #3.1 Scope to the longer one. Trailing text stays outside the link, which is what makes agglutinative languages work without tokenizing (#3.1 단일 진실 원천의 전제 → the 의 is not part of the link).

Full heading text is deliberate over a bare number: if the link ever fails to resolve, the sentence still reads. 3.1 alone does not.

Host compatibility

Additive, and inert unless opted into:

• AnnotationPanel onNavigateAnchor?: (hash: string) => void — the panel parses only when this AND a non-empty heading index are both present. A host passing nothing renders the same single <p> as before. The panel already received blocks, so the index costs the host nothing.
• ViewerHandle.scrollToAnchor(hash) => boolean — exposes the callback Viewer already had internally for in-document anchor links. Required rather than optional on purpose: the interface is implemented only inside this package (Viewer, HtmlViewer) and consumed everywhere else through a ref, so requiring it costs no host anything while forcing both implementations to stay in step. HtmlViewer implements it as () => false — raw HTML pages have no markdown heading blocks to resolve against.
• utils/sectionRefs — buildSectionRefIndex / parseSectionRefs, both pure and DOM-free.

CodeAnnotationCard is untouched: review annotations address files and lines, and a review surface has no heading blocks.

Documented in packages/ui/README.md and packages/ui/HANDOFF.md following the existing seam convention. No version bump — I left that to the maintainer; nothing under packages/core changed, so it should be a ui-only publish.

Second commit: the plannotator-markup extra skill

The same problem from the other end. An agent that wants to answer as markup on a document has to drive the external-annotations API, and three of its properties fail silently today:

• plannotator annotate blocks until the human decides, so an agent that launches it in the foreground can never post into the session it just started.
• plannotator sessions prints the base URL to stderr, so a pipe without 2>&1 reads empty and the flow stalls at step 2.
• DELETION discards its text (the export writes a fixed sentence), so an agent that puts a suggested replacement there watches it disappear.

The skill is only that contract — launch, discover, read, POST, clean up on re-run. What to say about a document stays with the request that asked for it; there is no review checklist or perspective baked in.

Conventions followed:

• apps/skills/extra/, not core/ — opt-in, not default-installed.
• Shipped locked (disable-model-invocation: true) like every other skill here, per the locked-by-default rule stated in apps/skills/core/plannotator/agents/openai.yaml.
• Registered in the live extras list in all three installers (EXTRA_SKILL_NAMES, $extraSkillNames, the .cmd picker) so the "Make any skills callable by the model?" prompt offers it. The two historical cleanup lists are deliberately untouched — a name in those is a name the installer deletes.
• SKILL.test.ts, following the freshness-guard pattern plannotator-skill-reference.test.ts uses for the core skill. It pins the endpoint path, the annotation types transformPlanInput accepts, and the fact that the export still drops DELETION's text, each against its source. Mutation-checked: removing the DELETION warning, or inventing a fourth annotation type, each fails exactly one test.
• Listed in AGENTS.md's project structure (CLAUDE.md is a symlink to it).

Verification

Local run of the CI steps:

Step	Result
bun run check:release-version	pass (v0.27.9)
bash apps/pi-extension/vendor.sh	pass, no extra files
bun run typecheck (10 tsconfigs, incl. strict-consumer)	pass
bun test	4044 pass / 0 fail across 428 files
DOM_TESTS=1 seam batch	see note below

New unit tests (packages/ui/utils/sectionRefs.test.ts, 11 cases) pin every row of the table above plus longest-match, unicode headings, and the trailing-text rule. Mutation-checked: dropping the duplicate-title guard, flipping longest-match to shortest, and removing code-span protection each fail exactly one test.

Verified in a real browser on an annotate session, not just in tests:

• All branches render correctly — resolved references as links, #없는섹션 / #fff as plain text, trailing particle outside the link.
• On a long document, clicking a reference to a far section moved the target heading's getBoundingClientRect().top from 2781px → 417px, with the section visible on screen afterwards.
• The click does not also select the annotation card (the link stops propagation), so navigating never doubles as a scroll to the annotation's own highlight.

Pre-existing test failure, unrelated to this change

packages/ui/components/Viewer.consumer.test.tsx → "readOnly fenced code never opens composers or mutates the rendered code" fails under DOM_TESTS=1. It asserts code.innerHTML equals the plain source, but Shiki has highlighted it into token spans by then.

I confirmed this is pre-existing by stashing this branch and running the same test on a clean tree — it fails identically there. Not touched here.