[glennfaison]

implement-github-issue can now split an issue that is too large for one PR into linked sub-issues, bounded by a new max_depth input. Design and trade-offs are in docs/adr/0015-split-an-issue-that-is-too-large.md (ADR first, as the issue asked).

Closes #68.

Summary

• Trigger. In step 4, before any code: the issue divides into parts that each merge alone, and one PR is too much (Size: large, separate areas, or a first read of the code). Rule in the new references/split.md. An issue with a branch already on origin is never split.
• Depth. New input max_depth (default 1). Depth = number of ancestors, read from GitHub's native sub-issue links. Split only when depth < max_depth; with the default a sub-issue is never split again, 0 turns it off, an unreadable depth never splits. At the limit the issue goes to ready-for-human with its proposed slices.
• Linking. Slices are filed through file-github-issues (new parent input: the parent is never a duplicate of a slice, bodies start Part of #N.), then linked with link_sub_issue. Native links, not body text, because anyone can write body text.
• Result. New #N split into #A, #B. The parent stays open and ready-for-agent, gets one trusted <!-- agent:split children=A,B --> comment, and no agent:pr-open. The marker is the commit point and a new requires, so a split parent does not use up the implement-github-issues batch. A split that died partway is finished from the sub-issues that exist.
• Closing. reconcile-github-issues closes the parent when all sub-issues are closed as completed (#N closed: all sub-issues closed). Keep-open parents stay open. A sub-issue closed as not planned sends the parent to ready-for-human, never back to an agent. Open sub-issues leave it alone.
• lease_held. Rule added under Leases in the protocol, and the scenario checker enforces it: only a skill that holds the lease passes lease_held=true, only for that item, only to an item skill that lists it; a group skill never does.
• Helpers parent_of, children_of, depth_of, link_sub_issue (lib.sh, with pure depthOf, canSplit, splitComment, splitChildren in helpers.mjs), the max_depth default, the marker, prompts regenerated with npm run sync, and a changeset.

Acceptance criteria

• ADR states the trigger, depth bound, linking and how the parent closes.
• implement-github-issue's contract has the new result, max_depth, and the other write for new issues (and calls: file-github-issues).
• Scenarios: a split, a child at the depth limit, a parent whose children have all closed (plus keep-open, rejected sub-issue, open sub-issue, already split, and a stranger's marker).
• The checker rejects lease_held=true from a caller that does not hold the lease (negative tests).

Evidence / verification

HUSKY=0 npm run check (lint, validate, plugin version, tests): passes. 467 node tests, 186 shell checks (new stub gh api endpoints for sub-issue links, covering no parent, link, idempotent link, grandchild depth, an unreadable parent being an error rather than "none", and cycles). Negative tests show the checker rejecting a split at or past the limit, an unreadable depth, unlinked or labelled sub-issues, a missing marker, agent:pr-open on a split parent, closing a parent with an open or rejected sub-issue, and bad lease_held use.

ADR check

Consistent with ADR 0010 to 0014. It uses lease_held (ADR 0011 gap 10) and extends the contract and scenario checker (0010, 0012). No existing decision is reversed.

Out of scope / things to look at

• Not run against real GitHub. The sub-issue REST calls (/parent, /sub_issues, POST with sub_issue_id) are exercised only against the stub in tests/lib.test.sh. The gh simulator still lists api as planned, and its replay test does not model the link. Worth one manual run against a scratch repo.
• The split path makes no same-item nested call. Children are other items and file-github-issues takes no lease, so lease_held=true is enforced by the checker and negative tests rather than exercised by a golden scenario. The ADR says so.
• "Too large" is a judgement. The ADR writes the trigger down so it can be argued with. No scenario can show a model judges it well.
• Decision for the maintainer: the parent keeps ready-for-agent rather than getting a new agent:split state label (a fifth mutex label across setup, repair and the diagram). Rationale and the alternative are in the ADR.
• Rare case: a run that dies after filing a slice and before linking it leaves an unlinked issue; the next run fails instead of adopting it and escalates after max_item_failures.