feat(issues): add protocol-gated typed consolidated issue tools

[SamMorrowDrums]

Summary

Add concrete Go input/output contracts to IssueRead, IssueWrite, and SubIssueWrite, exposing accurate output schemas and structured content for protocol 2026-07-28 and newer while preserving legacy text and exported raw-result helper signatures. Preserve explicit MCP App awaiting statuses for modern clients without exposing SDK-generated error fallbacks.

Why

Next file-focused typed MCP stack layer; no linked issue. This draft targets sammorrowdrums-typed-repository-tools at verified base 7e864d1e6c4eaadc2050c9d7d973d123471e4ea8 (ancestor 7b0c05e0eae079b0a973d44ea73f6244a491b2a0).

What changed

• Typed all five issue-read methods (get, get_comments, get_sub_issues, get_parent, get_labels), issue create/update including atomic parent creation, and sub-issue add/remove/reprioritize. Strict output unions retain actual empty/null response shapes and exact JSON text ordering.
• Added typed custom-field scalars, mutation optionality coverage, modern/legacy/unknown wire tests, strict schema conformance checks, enriched/lockdown output checks, and six scoped tool snapshots.
• Added a generic inventory distinction between explicitly supplied structured statuses and SDK-generated zero/error output, with regression coverage for protocol gating, output validation, and unchanged InputRequests. Updated error-handling documentation.

MCP impact

• No tool or API changes
• Tool schema or behavior changed
• New tool added

Modern clients receive concrete output schemas and matching structured content; older/unknown protocols retain the original text without output schemas or structured content. Existing exported helper APIs, scopes, feature gates, sanitization, IFC labeling, and lockdown filtering are preserved.

Prompts tested (tool changes only)

Mocked MCP wire equivalents, not live GitHub calls:

• "Get issue 1, its comments, sub-issues, parent, and labels."
• "Create an issue under parent issue 7."
• "Update an issue, clear its labels/assignees/type, and set its text, number, date, and single-select fields."
• "Clear the last custom field on an issue."
• "Reopen an issue, close it as completed/not planned, or close it as a duplicate."
• "Add or remove a sub-issue, or reorder it before/after another sub-issue."
• "Open the issue form, wait for submission, then execute the submitted create/update."

Security / limits

• No security or limits impact
• Auth / permissions considered
• Data exposure, filtering, or token/size limits considered

Existing scope requirements and feature rules remain unchanged. Structured responses use the same sanitized, lockdown-filtered Go responses as the text path; unsafe hierarchy/closing references remain omitted. API/validation errors do not expose generated success-shaped output; explicit awaiting statuses retain their stop signal and reason.

Tool renaming

• I am renaming tools as part of this PR (e.g. a part of a consolidation effort)
  • I have added the new tool aliases in deprecated_tool_aliases.go
• I am not renaming tools as part of this PR

Tool names and aliases are unchanged.

Note: if you're renaming tools, you must add the tool aliases. For more information on how to do so, please refer to the official docs.

Lint & tests

• Linted locally with ./script/lint
• Tested locally with ./script/test

Validation completed:

• UPDATE_TOOLSNAPS=true go test ./... — passed; scoped snapshots regenerated, unrelated terminal-newline drift excluded.
• script/lint — passed, 0 issues.
• script/test — passed (go test -race ./...).
• script/generate-docs — passed; generated documentation remained unchanged.
• git diff --check — passed.

Live PAT-backed e2e tests were not run. Contract tests use real in-memory MCP transports and mocked REST/GraphQL responses, including every scoped method, state variants, empty/null responses, errors, mutation optionality, custom fields, awaiting forms, and lockdown-filtered enrichment.

Docs

• Not needed
• Updated (README / docs / examples)

Updated docs/error-handling.md with protocol-gated typed output, explicit awaiting statuses, and unchanged multi-round-trip semantics. Generated docs were refreshed and required no changes.

[github-actions]

⚠️ License files need updating

The license files are out of date. I tried to fix them automatically but don't have permission to push to this branch.

Please run:

script/licenses
git add third-party-licenses.*.md third-party/
git commit -m "chore: regenerate license files"
git push

Alternatively, enable "Allow edits by maintainers" in the PR settings so I can fix it automatically.

[Copilot]

Copilot review overview

🟡 Changes recommended

Explicit structured output can bypass schema validation, and null wire-presence coverage is incomplete.

Review effort: Balanced
Findings: 1 · 1

Open (2)

• Validate explicit structured content before restoring it · New
• Test must distinguish omitted from explicit-null structured content · New

What changed in this PR

Adds protocol-gated typed contracts and structured outputs for consolidated issue tools while preserving legacy responses.

Changes:

• Adds typed issue read/write and sub-issue schemas, normalization, and outputs.
• Preserves explicit awaiting-form statuses and expands protocol/schema tests.
• Updates snapshots, error-handling documentation, and license metadata.

File	Description
third-party-licenses.windows.md	Updates Windows architecture license groups.
pkg/​inventory/​typed_output.go	Preserves explicit structured error outputs.
pkg/​inventory/​typed_output_test.go	Tests protocol gating and input requests.
pkg/​github/​typed_consolidated_issue_outputs_test.go	Tests issue tool contracts and outputs.
pkg/​github/​typed_consolidated_issue_enrichment_test.go	Tests enrichment and lockdown filtering.
pkg/​github/​issues.go	Migrates consolidated issue tools to typed handlers.
pkg/​github/​consolidated_issue_types.go	Defines typed contracts and schemas.
pkg/​github/​__toolsnaps__/​issue_write.snap	Updates the issue-write schema snapshot.
pkg/​github/​__toolsnaps__/​issue_write_typed.snap	Adds the modern typed snapshot.
docs/​error-handling.md	Documents typed output and status behavior.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.