feat(skills): voyage:annotating, the operator-annotation loop as one skill (order B)

The three producing commands name voyage:annotating where they build the page; the description of the page and the freehand revision left them. The skill: the person writes every note, Fix/Change edit only the quoted text, a Question is answered and changes nothing, the approval an edit costs is said before the edit, the page is rebuilt. Research documents on request (decision 62). Red baseline 3 runs per scenario without and with the skill; six eval cases; 11 pins.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

skills/annotating/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: annotating
+description: "The operator's own annotation loop for a Voyage brief, plan or review (a research document too, when asked): build the page with scripts/annotate.mjs so the person writes every note, take the pasted Copy Prompt back, and revise note by note. Fix and Change edit only the text the note points at; a Question is answered and changes nothing unless the person says so; nothing the notes did not ask for is edited. A note on ## Intent or ## Goal of an approved brief makes the approval stale, and a changed plan needs a new approval, said before the edit. The page is built again on the revised file. Use when someone wants to comment on, annotate or mark up a brief, plan, review or research document in the browser, or pastes back the notes from that page (Fix, Change, Question)."
+---
+
+# Annotating
+
+## Overview
+
+The annotation page lets the person read a Voyage artifact in the browser, click a line and write
+their own note, then copy every note back as one prompt. The loop is theirs: Claude builds the page,
+and later does what the notes say, no more. Two things go wrong without this skill. A Question gets
+answered and then written into the text as if it were a change. And the revision spreads: the same
+"fix" applied to parts no note named, a section rewritten to match, a new criterion added. Every such
+edit is a decision the person did not make, and on an approved brief or plan it also throws away an
+approval.
+
+## When to use
+
+- A `/trek*` command has just written a brief, plan or review and builds the page.
+- Someone says "let me comment on the plan", "I want to mark up the brief", "annotate this".
+- Someone asks to annotate a research document under `research/`. `/trekresearch` does not build
+  the page itself; build it on request.
+- The person pastes a prompt that starts "Please revise the voyage artifact at" and lists notes as
+  `[Fix]`, `[Change]` or `[Question]`.
+- Not for: someone who asks for Claude's own review of the artifact. That is a review
+  (`voyage:reviewing-adversarially`, `/trekreview`), not annotation.
+
+## Process
+
+1. **Build the page.** Run the script on the file and keep its stdout, the absolute path of the
+   page:
+
+   ```bash
+   ANNOT_HTML=$(node ${CLAUDE_PLUGIN_ROOT}/scripts/annotate.mjs "<path to the .md>" 2>&1)
+   ```
+
+   Print `file://<path>` and the line `open file://<path>`. If the script exits non-zero, say so in
+   one line and go on: the page is a convenience, never a gate.
+2. **The person writes the notes. Claude writes none.** Next to the link, say only how the page works:
+   click a line (or select a phrase first), pick Fix, Change or Question, write the note, and press
+   "Copy Prompt" when done; the notes stay in the browser if the tab is closed. No list of "points I
+   would look at", no summary of weaknesses, no suggested notes. Those would steer the notes the
+   person writes. If they want Claude's view as well, they ask for a review.
+3. **Read the pasted notes.** Each note has a number, a type, the section, the quoted text it is
+   anchored to, and the comment. Work from the quote and the comment, one note at a time.
+4. **Before any edit, check what the edit costs.**
+   - A brief with `intent_approved_hash` in its frontmatter, and a Fix or Change in `## Intent` or
+     `## Goal`: say in one line, before the edit, that the edit makes the approval stale, that
+     `/trekplan` halts until the new text is approved, and how to approve it
+     (`/trekbrief --approve <project dir>`). Then edit.
+   - A plan the person approved: any edit gives it a new sha256, the approval log no longer covers it,
+     and `/trekexecute` refuses it until the plan is approved again. Say that before the edit.
+   - Never stamp, log or commit an approval in this loop. Only the person's explicit answer approves.
+5. **Fix and Change: edit the text the note points at, and only that.** The quote marks the place.
+   If the comment cannot be done without touching other text (a summary that now disagrees, the same
+   gap in another step, a new criterion the change seems to need), do not edit that text. List it in
+   the reply as a question with a recommended answer. A validator error that was already there before
+   the notes is reported, not fixed in passing.
+6. **Question: answer it in the reply. The text stays as it was.** No new row under alternatives, no
+   new rule, no rewording to "make the answer visible". End the answer with one line offering to write
+   it in if the person wants that. Only their yes turns a Question into a change.
+7. **Build the page again** on the revised file, and print the new link, so the person reads the
+   revised text where they wrote the notes. The page keeps notes per file path, so last round's notes
+   still show in its sidebar: tell the person that "Clear all" empties it before the next round.
+8. **Reply note by note:** for each number, "edited" (with the new wording) or "answered" (with the
+   answer); then the approval consequence from step 4, the open questions from step 5, and the link.
+
+## Red flags
+
+| Thought | What it means |
+|---|---|
+| "I'll add a few points of my own next to the link, to help" | The notes are the person's. Your points steer theirs. Offer a review instead. |
+| "The Question shows a gap, so I'll fix the gap too" | Answer it. The gap is theirs to turn into a Change. |
+| "I'll record the answer under alternatives, so it isn't lost" | That is an edit nobody asked for, and on an approved plan it costs the approval. |
+| "The same fix applies to steps 2 to 4 as well" | Then ask. The note named one step. |
+| "The summary no longer matches the new intent, I'll update it" | Ask, with a recommended answer. The person approves the words. |
+| "The brief fails the validator anyway, I'll fix the frontmatter while I'm here" | Report it. A fix in passing is still a change the person did not ask for. |
+| "I'll mention the approval is stale at the end" | Say it before the edit. It is the price of the edit. |
+| "I'll re-stamp it so planning can go on" | Only the person's explicit approval stamps. |
+
+## Enforced by
+
+- `tests/lib/doc-consistency.test.mjs` and `tests/lib/skills-annotating-prose-pins.test.mjs` (in
+  `npm test`): the script `scripts/annotate.mjs` exists, the three producing commands call it, print
+  the `file://` link and the `open` line, and name this skill. Deterministic, but only at test time.
+- `lib/validators/intent-approval.mjs` (inside `/trekplan`): an edit to `## Intent` or `## Goal`
+  after approval makes the approval stale, and planning halts until the new text is approved.
+- `lib/util/approval-log.mjs` (inside `/trekexecute`, K2): a plan whose current sha256 the approval
+  log does not cover is refused. Both checks hold whether or not the edit's cost was said.
+- prose only: that the person writes every note and Claude none, that a Question changes nothing,
+  that only what the notes ask for is edited, that the cost of the edit is said before it, and that
+  the page is built again.
+
+## Credits
+
+Voyage's own content: the page (`scripts/annotate.mjs`), the loop and its rules come from Voyage's
+pipeline and from the red baseline run for this skill. Nothing here is borrowed.