Skip to content

derive merge-time issue closure from the substantive completion boundary #19

Closed
Closed
derive merge-time issue closure from the substantive completion boundary#19

Description

@jamesreimer
jamesreimer
opened on Oct 1, 2026

Problem

Agent Workflows #15 added strong GitHub issue-closure safety mechanics, including:

  • canonical issue identity resolution;
  • inspection of PR closing relationships;
  • controlling commit-message checks;
  • explicit final landing-message checks;
  • exact-head merge binding;
  • post-merge resulting-state verification.

Those mechanics are sound.

Operational use exposed a remaining semantic gap: the workflow declares Issue closure on merge as either none or an authorized issue set, but it does not yet state clearly enough how that declaration should be chosen.

In practice, Planning repeatedly selected none merely because post-merge publication verification or routine cleanup still followed the merge. Later reasoning showed that this can overextend issue lifetime beyond its substantive completion boundary.

Planning objective

Make the closure declaration explicitly derive from the issue/work item's substantive governed completion boundary.

The reusable rule should be:

  • if the merge itself satisfies the substantive completion boundary, declare the appropriate issue closure on merge;
  • if material completion obligations remain after merge, declare none for that issue and complete it explicitly later;
  • routine cleanup or housekeeping that does not represent substantive unfinished work does not, by itself, extend the completion boundary.

The purpose is neither "close everything on merge" nor "keep everything open through publication cleanup." It is correspondence between issue state and actual governed completion.

Existing mechanics to preserve

Do not weaken the #15 safety model.

Preserve:

  • per-surface subset checks;
  • aggregate equality with the declared closure set;
  • canonical full issue identities;
  • final host-state gate;
  • exact-head binding;
  • explicit landing messages;
  • post-merge resulting-state verification;
  • host-neutrality;
  • the fact that merge need not complete a work item.

Candidate canonical surfaces

Planning should review the smallest coherent changes across:

  • workflows/reviewed-change.md;
  • handoffs/review-to-publication.md;
  • roles/publication.md.

Consider whether Planning/handoff guidance also needs a lightweight reminder that the completion boundary must distinguish substantive completion from routine cleanup.

Avoid duplicating a full rule across every artifact.

Required semantics

The final model should establish that:

  1. Issue closure on merge is derived, not defaulted.
    The declaration is determined by the work item's actual completion boundary and closure authority.

  2. Merge-time closure is appropriate when merge is completion.
    If no material governed obligation remains after the merge, a closing relationship may intentionally complete the issue.

  3. Post-merge substantive obligations keep the issue open.
    If required publication/resulting-state evidence, downstream action, approval, or other material completion condition remains, the merge must not falsely present completion.

  4. Routine housekeeping is not automatically a completion condition.
    Branch deletion, local synchronization, ordinary cleanup, or similar mechanics do not keep an otherwise completed issue open unless the project explicitly makes them substantive completion requirements.

  5. Publication verification and issue completion are related but distinct.
    A project may require post-merge publication verification without necessarily defining the implementation issue's completion boundary to include every publication-role housekeeping step.

  6. Host configuration is not the semantic model.
    The GitHub auto-close setting may be enabled or disabled by a repository, but the workflow declaration and closure-bearing surfaces must still express the intended per-issue result.

Consumer / compatibility consideration

This is a refinement of the decision rule around the existing Issue closure on merge field.

Review whether consumers with copied handoffs or integrations bound to that field need explicit update guidance in the next release notes.

Do not silently redefine existing instantiated handoffs.

Validation / review

Implementation should:

  • preserve the existing prevent accidental GitHub issue-closing keywords in handoff prose #15 closure safety checks;
  • include examples covering both merge-completes-issue and merge-does-not-complete-issue cases;
  • include at least one case where only routine cleanup follows merge and confirm that cleanup alone does not force none;
  • run full repository validation;
  • obtain independent review because this changes reusable workflow semantics.

Boundaries

Do not:

Activity

  1. jamesreimer commented on Oct 1, 2026

    @jamesreimer
    jamesreimer
    on Oct 1, 2026 – with ChatGPT Codex Connector
    OwnerAuthor

    Planning implementation decision

    Planning settles the #19 refinement as follows.

    Core rule

    Issue closure on merge is derived from the work item's substantive completion boundary.

    It is not a default preference for either closure or non-closure.

    • If merge satisfies the substantive completion boundary, the authorized closure set should include the applicable issue.
    • If material governed obligations remain after merge, the issue remains open and is completed explicitly at the later boundary.
    • Routine housekeeping such as local synchronization, branch deletion, ordinary cleanup, or equivalent mechanics does not by itself extend an otherwise satisfied completion boundary.
    • Post-merge publication/resulting-state verification may still be required operationally without automatically making the implementation issue incomplete.

    Responsibility placement

    The completion boundary is established by Planning/project authority, not invented by Publication.

    Implementation should use the smallest coherent changes across these canonical surfaces:

    1. roles/planning.md

      • add a concise workflow-local instruction that when GitHub issue completion is part of the work contract, Planning distinguishes substantive completion conditions from routine housekeeping and establishes whether merge is intended to satisfy the issue boundary.

    2. workflows/reviewed-change.md

      • make the reviewed-change composition state that merge-time issue closure corresponds to the established substantive completion boundary;
      • preserve that merge need not complete every work item.

    3. handoffs/review-to-publication.md

      • clarify that Issue closure on merge is populated from the already-established completion boundary and closure authority, rather than selected by Publication as an independent policy choice.

    4. roles/publication.md

    Do not duplicate the full rule across all four files. Prefer one clear semantic statement at the workflow/Planning owner and concise references/consumption language in the handoff and Publication role.

    Existing mechanics to preserve unchanged in effect

    Do not weaken:

    • canonical full issue identity resolution;
    • per-surface subset checks;
    • aggregate equality against the declared closure set;
    • PR relationship inspection;
    • controlling commit-message inspection;
    • explicit final landing-message verification;
    • last host-state gate immediately before merge;
    • exact-head binding;
    • post-merge landed-message and issue-state verification;
    • host-neutrality;
    • the rule that merge does not necessarily complete the work item.

    Required behavioral examples

    The implementation/review evidence should cover at least:

    1. Merge completes issue

      • implementation/review obligations are satisfied;
      • only routine cleanup follows;
      • closure declaration includes the issue.

    2. Merge does not complete issue

      • a material governed obligation remains after merge;
      • closure declaration is none for that issue;
      • later explicit completion remains owned.

    3. Post-merge verification without issue extension

      • publication verifies the resulting merge state after merge;
      • verification itself does not automatically mean the issue had to remain open if the substantive issue boundary was merge.

    Compatibility

    This refines the decision rule around the existing Issue closure on merge field.

    Do not silently reinterpret already-instantiated handoffs. Future release notes should tell consumers using copied handoffs or label-bound integrations to review the clarified semantics.

    Validation / review

    • full repository qualification;
    • hosted Repository validation final SUCCESS on the exact candidate;
    • exact-candidate Planning review;
    • independent review required because reusable workflow semantics change.

    Issue lifecycle for #19 itself

    For #19, the implementing merge may close the issue only if the implementation candidate, required review, and publication authorization make merge the substantive completion boundary.

    Do not keep #19 open merely for routine local cleanup.

    The final Publication handoff must declare the closure result from the actual #19 completion boundary and run the existing #15 gate.

    Boundaries

    Do not:

    Planning disposition: READY FOR IMPLEMENTATION.

  2. jamesreimer commented on Oct 1, 2026

    @jamesreimer
    jamesreimer
    on Oct 1, 2026 – with ChatGPT Codex Connector
    OwnerAuthor

    Planning exact-candidate review — PR #20

    Planning reviewed exact candidate:

    2eeb8a60e4859af6a57ff9b2e9cfc4d0f2937c4a

    against base:

    012b27c7c384019241531a33ea990d9f4e1f7e77

    and the settled #19 implementation decision.

    Scope — PASS

    The candidate changes exactly four canonical workflow surfaces:

    • roles/planning.md
    • workflows/reviewed-change.md
    • handoffs/review-to-publication.md
    • roles/publication.md

    No governing-source pins, source-derived guidance, validators, tests, CI, dependencies, host settings, runtime, or unrelated artifacts change.

    Responsibility placement — PASS

    The candidate correctly places ownership:

    • Planning/project authority establishes the substantive completion boundary and whether merge is intended to satisfy it;
    • reviewed-change derives merge-time closure from that established boundary plus issue-closure authority;
    • the review→publication handoff records the already-established decision;
    • Publication consumes and enforces the declaration rather than inventing completion policy.

    This preserves the role boundary requested by Planning.

    Completion-boundary semantics — PASS

    The candidate correctly establishes that:

    • neither closure nor none is a universal default;
    • an authorized issue may close on merge when merge satisfies all substantive completion conditions;
    • material governed obligations remaining after merge keep that issue open with later completion ownership retained;
    • routine synchronization, branch deletion, workspace cleanup, and similar mechanics do not extend the issue boundary merely because they occur after merge;
    • publication/resulting-state verification does not automatically extend the issue boundary;
    • the actual project contract can still make a particular cleanup or verification result substantive.

    This is the intended boundary-driven model.

    #15 safety machinery — PASS

    Planning accepts the implementation evidence that the existing numbered GitHub issue-closure procedure from 1. Prepare the final gate through the end of roles/publication.md is byte-identical to the base.

    The candidate therefore preserves in effect:

    • canonical full issue identity resolution;
    • PR closing-relationship checks;
    • controlling commit-message checks;
    • explicit final landing-message checks;
    • per-surface subset requirements;
    • aggregate equality with the declared set;
    • empty aggregate for none;
    • final host-state verification;
    • invalidation on relevant state changes;
    • exact-head binding;
    • post-merge landed-message verification;
    • resulting issue-state verification;
    • host-neutrality;
    • separate publication and issue-closure authority.

    The new Publication paragraph clarifies consumption of the declaration without redesigning the gate.

    Host-configuration interaction — PASS

    The candidate does not make repository configuration the semantic model.

    If host auto-close behavior differs from the declared intent, the existing #15 result-verification and authority guidance still governs the observed mismatch. The declaration expresses the intended merge consequence; Publication verifies actual issue state and does not silently reinterpret the completion boundary.

    No host-setting change is required by this candidate.

    Required semantic cases — PASS

    Implementation's three walkthroughs faithfully exercise the intended distinctions:

    • A: merge completes substantive work; only ordinary cleanup follows → authorized merge-time closure is appropriate;
    • B: material governed obligation remains → issue stays out of the closure set and later completion remains owned;
    • C: resulting-state verification follows merge but is not itself part of the issue boundary → verification timing alone does not force none.

    These are suitable implementation evidence, not substitutes for independent review.

    Compatibility / release evidence — PASS

    The proposed next-release summary accurately describes the semantic refinement.

    The PR also preserves carried-forward #15 release evidence and correctly states that:

    • copied handoffs / field-bound integrations should review the clarified semantics when deliberately updating;
    • existing instantiated handoffs do not silently change;
    • no future release version or Unreleased section is invented.

    Consequence disposition — PASS

    Material consequences are accounted for:

    No orphaned material consequence is apparent.

    Validation / live state — PASS

    Hosted Repository validation reached final SUCCESS on exact candidate 2eeb8a60e4859af6a57ff9b2e9cfc4d0f2937c4a in run 36804965496.

    Implementation also reports:

    • full pre-commit success;
    • standalone validator success;
    • five unit tests passing;
    • whitespace checks passing;
    • npm audit with zero vulnerabilities;
    • clean worktree.

    Current PR state is open, unmerged, mergeable, and non-draft. Issue #19 remains OPEN.

    Planning disposition

    ACCEPT FOR INDEPENDENT REVIEW

    Independent review should focus on:

    • whether the substantive-completion-boundary rule is correctly owned by Planning/project authority;
    • whether routine housekeeping is distinguished without making it categorically non-substantive;
    • whether post-merge publication verification is correctly separated from issue completion;
    • whether prevent accidental GitHub issue-closing keywords in handoff prose #15 closure-safety mechanics remain unchanged in effect;
    • whether the handoff field records rather than creates completion policy;
    • whether host-setting neutrality remains coherent;
    • compatibility implications for copied handoffs / integrations;
    • absence of unintended role, authority, source-pin, or lifecycle changes.

    No merge, tag, release, Issue #19 closure, repo-template #53 implementation, Agent Workflows #17 implementation, or host-setting mutation is authorized by this acceptance.

  3. jamesreimer commented on Oct 1, 2026

    @jamesreimer
    jamesreimer
    on Oct 1, 2026 – with ChatGPT Codex Connector
    OwnerAuthor

    Planning final acceptance — PR #20

    Planning accepts the independent review of exact candidate:

    2eeb8a60e4859af6a57ff9b2e9cfc4d0f2937c4a

    Disposition:

    • Independent review: ACCEPT
    • No BLOCKING, MAJOR, or MINOR findings
    • Publication readiness: READY FOR AUTHORIZED PUBLICATION ACTION
    • Reviewer notes are accepted as non-corrective observations.

    Accepted review conclusions

    Planning accepts that:

    • responsibility ownership is correct: Planning/project authority establishes the substantive completion boundary; Publication consumes and enforces it;
    • merge-time closure is derived rather than defaulted;
    • routine housekeeping does not extend the boundary merely because it follows merge;
    • required publication verification does not automatically extend the issue boundary, while a contract may still make a particular verification result substantive;
    • the complete prevent accidental GitHub issue-closing keywords in handoff prose #15 closure-safety procedure remains unchanged in effect;
    • host-setting neutrality remains coherent;
    • the existing Issue closure on merge field is clarified without schema or compatibility break;
    • consequence ownership is complete.

    #19 completion boundary

    Planning now applies the clarified rule to #19 itself.

    All substantive prerequisites to publication are satisfied or are part of the authorized Publication action:

    • implementation complete;
    • exact candidate established;
    • required validation final SUCCESS;
    • Planning exact-candidate review complete;
    • independent review complete;
    • publication authorization is now granted by this handoff.

    No material #19 obligation is identified after the implementing merge. Post-merge resulting-state verification and routine cleanup remain Publication duties but are not separate substantive completion conditions for Issue #19.

    Therefore:

    Issue closure on merge: jamesreimer/agent-workflows#19

    The final Publication gate must intentionally establish a closure-bearing surface for that canonical issue identity and verify the aggregate closure-command set equals exactly that one issue.

    Live state

    Planning independently rechecked:

    No release, tag, repo-template #53 implementation, Agent Workflows #17 implementation, or host-setting mutation is authorized by this acceptance.

  4. jamesreimer
    closed this as completedin 36c7786on Oct 1, 2026

  5. jamesreimer commented on Oct 1, 2026

    @jamesreimer
    jamesreimer
    on Oct 1, 2026 – with ChatGPT Codex Connector
    OwnerAuthor

    Publication completion evidence

    PR #20 published the exact reviewed candidate successfully.

    • reviewed candidate: 2eeb8a60e4859af6a57ff9b2e9cfc4d0f2937c4a
    • canonical published commit: 36c7786d3b2d4307a1bea943098a8e86b88a3701
    • published tree: 1079551c85b054c42da68b1fa4b3a5aab46a2d01
    • reviewed/published tree correspondence: identical
    • post-merge Repository validation: SUCCESS, run 36807612565
    • landed subject/body: exact authorized text
    • aggregate merge-time closure target: exactly jamesreimer/agent-workflows#19
    • Issue derive merge-time issue closure from the substantive completion boundary #19: CLOSED / completed through the published commit
    • routine synchronization and branch cleanup completed afterward without extending the issue boundary

    This is the intended application of #19's rule: merge satisfied the substantive issue-completion boundary, while Publication still completed resulting-state verification and housekeeping afterward.

    No release, tag, host-setting change, repo-template #53 implementation, or Agent Workflows #17 implementation occurred.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions