fix: derive merge-time issue closure from completion boundary

[jamesreimer]

Outcome and authority

Implement Issue #19 and its settled Planning implementation decision. The existing Issue closure on merge declaration now derives from the substantive work-item completion boundary and issue-closure authority. Planning establishes the boundary; Publication enforces the declared result.

• Exact fetched main/base: 012b27c7c384019241531a33ea990d9f4e1f7e77.
• Exact candidate: 2eeb8a60e4859af6a57ff9b2e9cfc4d0f2937c4a.
• Branch: fix/completion-boundary-closure. Initial checkout was clean; no unrelated work existed.
• Implementation boundary: one open validated PR, then return to Planning / Primary Author. Exact-candidate Planning review and independent review remain required before authorized publication. This PR supplies no merge authorization.

Changed canonical surfaces

File	Semantic change
roles/planning.md	Planning/project authority establishes whether merge satisfies substantive completion. Distinguishes material downstream action, approval, verification, and other conditions from housekeeping; retains an owner for later completion. Timing alone does not make cleanup or publication verification substantive.
workflows/reviewed-change.md	Derives the existing declaration from that boundary and closure authority. Includes authorized issues completed by merge, excludes issues with material obligations remaining, and preserves later completion ownership. Neither closure nor none is a universal default; per-issue intent applies regardless of host configuration.
handoffs/review-to-publication.md	Keeps the existing field name and values. Explains that it records the established boundary, authority, and intended merge consequence; Publication consumes it rather than choosing an independent policy.
roles/publication.md	Adds a short consumption clarification before the existing procedure. Post-merge identity/tree/message/issue-state/hosted-validation checks and cleanup alone do not force none; conditions actually included in the issue boundary still keep it open.

All changes are workflow-local. Governing sources, pins, source-derived guidance, validators, runtime, and repository settings are unchanged. GitHub remains conditional.

Preservation of #15 safety mechanics

Mechanical comparison against the exact base confirms that roles/publication.md from 1. **Prepare the final gate.** through EOF is byte-identical. This preserves the entire four-step procedure and final host/authority disposition:

• canonical owner/repository#number resolution;
• PR closingIssuesReferences, controlling commit messages, and final landing-message inspection;
• each surface's subset requirement, aggregate equality, and empty aggregate for none;
• the last host-state gate immediately before merge and invalidation on relevant changes;
• exact-head binding and explicit landing-message binding;
• landed-message and resulting issue-state verification;
• host-neutrality and separate publication/issue-closure authority.

All four files' governing-source and source-derived sections are byte-identical to the base. Existing handoff identity and verification instructions and workflow safety references remain intact.

Semantic review cases — implementor walkthroughs

Case	Application and result
A — merge completes the issue	Implementation and required review are complete; merge performs the substantive change; only ordinary synchronization, branch deletion, or cleanup follows. With issue-closure authority, include the issue in the merge closure set. PASS.
B — material obligation remains	Required downstream action, approval, or substantive verification belongs to the issue's boundary and remains after merge. Exclude that issue from the set, retain its owner for explicit later completion, and keep it open. Other issues may still be declared; none applies when the entire authorized set is empty. PASS.
C — publication verification follows	Publication must verify resulting state, but no substantive issue-completion condition remains after merge. The verification duty remains; its timing alone does not force none. With closure authority, the issue may be included. PASS.

A cleanup or verification task can be substantive when the actual project contract makes it so. These are manual semantic checks, not a new parser, test framework, independent review, or live merge experiment.

Consumer impact and proposed next-release summary

Clarify that merge-time issue closure is derived from the work item's substantive completion boundary, distinguishing material post-merge obligations from routine cleanup while preserving existing GitHub closure-safety verification.

Evidence: Issue #19 and this exact candidate. This is a compatible refinement around an existing field, with no rename or schema change. Consumers using copied review-to-publication handoffs, integrations bound to Issue closure on merge, or locally derived publication guidance should review the clarified completion-boundary semantics when deliberately updating. Existing instantiated handoffs do not silently change. Consumer authority and legitimate local adaptations remain controlling; no consumer integration was executed.

Carried-forward next-release summary — #15

Add GitHub issue-closure safety across PR closing relationships, controlling commit messages, and final landing messages; resolve canonical full issue identities, verify final host state, bind merge correspondence to the exact head, and verify resulting issue states after merge while preserving lifecycle and host-neutrality semantics.

Retained from PR #18, supported by Issue #15, PR #16, and landed commit d358c22438b80053a37cf173c1f652952fb35e2a. Release preparation must curate the full delta and retained summaries, including PR #18's own maintenance summary. No new version, Unreleased section, tag, or release is created; this work and #15 are not attributed to v0.2.0.

Validation

• Full .venv/bin/pre-commit run --all-files --show-diff-on-failure: PASS, including Markdown lint/authoring regressions, local links/link regressions, Ruff, actionlint, and artifact checks/tests. Only the expected no-files broken-symlink hook skipped. No hook mutation occurred.
• Standalone python3 scripts/validate_local.py: PASS.
• python3 -m unittest discover -s tests: PASS, five tests.
• git diff --check and git diff --cached --check: PASS.
• npm audit: PASS, zero vulnerabilities. Node v24.18.1; local Python 3.14.6.
• Validated staged content was committed unchanged. Byte-comparison preservation checks and A/B/C reasoning are recorded above.
• Hosted Repository validation: final SUCCESS on exact candidate 2eeb8a60e4859af6a57ff9b2e9cfc4d0f2937c4a: run 36804965496, job 110187140961. Run status is completed, conclusion success, and head SHA matches the candidate. The unchanged workflow checks out the exact PR head.

The local validator checks artifact presence and obvious live identifiers, not workflow semantics. External links are skipped by the local link check; referenced issue/PR records were read directly. No validator changes require new injected-defect tests. No unexpected findings or scope deviations identified. Required independent review remains separate from these implementor checks.

Issue relationship and completion boundary

Issue #19 remains OPEN during implementation/review. This PR uses a non-closing reference while Planning exact-candidate review, independent review, and publication authorization are outstanding. No final Publication closure declaration is being supplied at this stage; absent closing relationships are not a semantic decision that post-merge verification requires none.

Under the current contract, no material #19 obligation after the authorized implementing merge has been identified. Once implementation, validation, required reviews, and publication authorization are satisfied, merge may satisfy #19's substantive boundary. Planning and the final Publication handoff must declare the actual authorized closure set; routine synchronization, branch cleanup, and ordinary resulting-state verification alone do not justify exclusion. Publication must establish final landing text and rerun the complete #15 gate immediately before merge, including after any PR description or relationship change.

PR #20 readback confirms the exact base/candidate above, OPEN state, and empty closingIssuesReferences. The PR description and sole candidate commit contain no issue-closing command targeting an issue. Issue #19 remains OPEN; the worktree is clean. Final landing text is not yet established and remains a Publication input. This snapshot is candidate-return evidence, not the final publication gate. No merge, manual issue closure, tag, release, or host-setting change is performed here.

Material consequence dispositions

• Handled here — downstream semantics and compatibility: canonical clarification plus explicit deliberate-update guidance above for copied handoffs, field-bound integrations, and derived publication guidance. Each consumer owns adoption under its existing project authority; there is no automatic propagation or required consumer execution in derive merge-time issue closure from the substantive completion boundary #19.
• Handled here — release-note compatibility evidence: this proposed summary and the carried-forward prevent accidental GitHub issue-closing keywords in handoff prose #15 summary are retained for release preparation under MAINTAINING.md; release selection/publication remains separately authorized.
• Durably owned elsewhere — repo-template relationship: repo-template #53, currently OPEN, already owns concise consumer initialization guidance for the same completion rule. It explicitly identifies derive merge-time issue closure from the substantive completion boundary #19 as reusable workflow ownership. No upstream edit or new follow-up issue is needed here.
• Durably owned elsewhere — generic consequence workflow: Agent Workflows #17 owns that separate refinement; it is not implemented here.
• Inapplicable — source-pin consequence: this is selected workflow-local practice; no discovered source requirement or source-derived change requires pin advancement.
• Inapplicable — host-setting consequence: existing manual closure safety applies regardless of configuration; no enablement/disablement or repository setting change is needed.
• Durably owned in derive merge-time issue closure from the substantive completion boundary #19 and this PR — remaining gates: Planning / Primary Author owns exact-candidate assessment and routing the required independent review, followed by actual publication/closure authorization. These are prerequisites to publication, not unowned implementation follow-ups.

Return to Planning / Primary Author

Act as Planning / Primary Author under the settled #19 contract. Review the exact candidate against the recorded base and the six semantic requirements, A/B/C cases, #15 preservation evidence, and consumer consequences. Arrange the required independent review without mutating the candidate. Retain a supported conclusion and material finding dispositions in this PR/Issue #19 record; route corrections to authorized Implementation for complete requalification. Then establish the actual completion boundary and closure declaration in the final Publication handoff if publication is authorized. This implementation handoff does not authorize merge or replace independent review.