[ryanlindsey]

Closes #98

The adapter half of item_link. It adds linkItem in server/providers/github/items.ts, which adds and removes blockers on an existing item and sets, replaces or clears its parent. It then brings every canonical Depends on line into step with the resulting blockers, including drift the call did not name. Each phase is verified by its own read-back. This PR only adds the adapter; wiring it into the provider, dispatch, TOOLS, the contract suite and the README is #99.

Stacked on #103 (issue-97-item-update-tool).

What's in it

• Types LinkChange and LinkedItem in server/providers/types.ts.
• Documents REMOVE_BLOCKED_BY, SET_PARENT (addSubIssue with replaceParent: true) and REMOVE_SUB_ISSUE.
• One more document than the plan named: ISSUE_IDENTITY. It resolves a target's node id together with GitHub's own spelling of its owner and repo. That keeps the dry run, the written Depends on line and the read-back on one spelling, so Acme/Web#3 is written as acme/web#3. Without it, the dry-run prediction and the real result disagreed on spelling. PARENT_ID is unchanged, so createItem is unaffected.
• Errors, one for each end state:
  • ConflictingLinkError: raised before any read.
  • MissingLinkTargetError: raised before any write, dry run included.
  • PartialLinkError: some link writes did not show on read-back. The prose is not touched. Its opening sentence states only what was observed: in part, none confirmed, or links moved while this call sent nothing.
  • ProseOutOfStepError: every link is confirmed but the prose is in doubt.
• UnclosedFenceError placement: syncDependsOn(before.body, desired) runs before any link mutation, dry run included. A body that can never take a new line is refused with nothing written, so it is never left half-linked. If the fence appears only after the links land, the error is restated as ProseOutOfStepError, because the original error's "nothing was changed" is no longer true.
• The prose sync is computed from the read taken after the links land, not the first read, so a person's concurrent edit survives.
• Not version-guarded, as the issue specifies.

Acceptance receipt

• linkItem adds and removes blockers and sets, replaces and clears a parent, each verified by read-back. Evidence: tests/items-link.test.ts covers add, remove, set-over-existing (SET_PARENT, replaceParent) and clear (REMOVE_SUB_ISSUE, current parent's id). Each test scripts the read-back. The suite is green.
• After a successful call, the item's canonical Depends on set equals its blockedBy, including blockers the call did not name. Evidence: the "repairs drift on blockers the call did not name" test. The step-9 check raises ProseOutOfStepError otherwise, and a test covers that too.
• Each partial end state raises its own named error, and a concurrent body edit survives. Evidence: tests for PartialLinkError (missing add, refused write, failed read-back, concurrent blocker change, no-op with moved links), for ProseOutOfStepError (prose mismatch, fence opened since, refused body write, links moved after confirmation), and for the person's edit surviving.
• All three new documents are in the integration query suite. Evidence: tests/integration/queries.integration.test.ts, run against the live schema with ARMATURE_INTEGRATION=1 ARMATURE_IT_OWNER=ryanlindsey ARMATURE_IT_BOARD=1 ARMATURE_IT_REPO=armature: 13/13 passed. That includes the three new mutations and ISSUE_IDENTITY.
• dist/server.js rebuilt; npm test and npm run typecheck pass. Evidence: npm run build ran and the bundle is byte-identical, because nothing imports linkItem until feat(item_link): expose blocker and parent changes as a tool #99 wires it in. npm test passed (688, 18 skipped) and npm run typecheck is clean.

Review

One review round and one re-review. No Critical findings. The Important findings were fixed before this PR:

• PartialLinkError wording overclaimed what had landed.
• The dry run and the real path reported different spellings.
• Test gaps, including a test that runs the same change through dry run and the real path and compares the results.

Minor findings left open:

• The dry run returns the old version, and its blockedBy order may differ from GitHub's.
• ISSUE_IDENTITY follows the redirect for a transferred issue. Naming such an issue by its old location can send one extra add, which is idempotent and verified by the read-back. An old ref that redirects to the item itself gets past the self-reference check, and GitHub refuses the write, which raises PartialLinkError.
• The up-front fence check syncs against the whole desired set, so unnamed drift in a fenced-off body refuses even a parent-only change. This is intentional and commented.

Board repairs

none

🤖 Generated with Claude Code

https://claude.ai/code/session_014YX1awC8SkssEro6XoXTaE