Skip to content

github-workflow: Agent Handoff documents always admit by direct commit, not T0 or PR #218

Description

@chrisdpurcell

Context

The GitHub Workflow standard (pr-standard.md §"Admission: T0 or a pull request") admits exactly two
classes: a T0 direct commit or a pull request, "no third tier and no repository-configurable middle
ground". T0 is a conjunctive predicate whose condition 1 requires every hunk to be a spelling, grammar,
punctuation, or reflow correction, so a routine Agent Handoff closeout — rewriting state.md, appending
a session-log row, retiring a TODO item — can never qualify.

The consequence, observed twice in this repository (#216 on 2026-08-31, and a second draft on
2026-09-01 that the operator stopped), is that session bookkeeping gets its own PR. Agent Handoff
documents are transient agent-side state; a PR per closeout pollutes PR history with nonsense and
adds ceremony to every session end. This repository already carved the exemption into its own
CLAUDE.md / AGENTS.md (d5792907), but a consumer-side override is exactly the "repository-
configurable middle ground" the standard forbids — the standard itself must own the rule.

Scope

Amend the github-workflow package so that Agent Handoff documents always admit by direct commit,
regardless of the T0 predicate:

  1. pr-standard.md: define a third admission class (or a standing exemption from the T0 predicate)
    for handoff surfaces, and state its trailer or commit-message convention so a git log audit can
    still enumerate direct admissions.
  2. Default the exempt path set to the agent-handoff standard's owned surfaces — docs/handoff/**,
    docs/STATUS.md, docs/TODO.md — and decide whether policy.toml may extend it.
  3. The managed AGENTS.md/CLAUDE.md instruction block and the skill's decision procedures name the
    exemption, so a session does not rediscover it.
  4. Cut the payload version and ship it; reconcile this repository and remove the hand-written carve-out
    from d5792907 once the managed block carries it.

Out of scope

Weakening T0 for anything other than handoff surfaces; changing which files the agent-handoff standard
owns.

Acceptance criteria

  1. A closeout that touches only handoff surfaces is a permitted direct commit under the standard's own
    text, with no Workflow-Admission: T0 misclassification required.
  2. A commit that mixes a handoff edit with any non-exempt file is still governed by the PR rule, and the
    standard says so explicitly.
  3. The exemption is discoverable from the managed instruction block alone, without loading the skill.
  4. All predecessors stay byte-immutable; project-standards validate and the reconcile check pass here
    after adoption.

Constraints

Payload bytes are immutable after publication, so this is a new package version. The agent-handoff
standard, not github-workflow, is the source of truth for which paths are handoff surfaces; reference
it rather than duplicating the list if the packaging allows.

Verification

Reconcile this repository onto the new version; confirm the managed block states the exemption and
that the hand-written carve-out can be deleted without a CP-MODIFIED-MANAGED or coherence finding.

Evidence / references

  • .agents/skills/github-workflow/references/pr-standard.md — two-class admission text and T0 predicate.
  • docs(handoff): close out the v5.27.0 train and the #212 investigation #216 — a handoff closeout admitted through a PR because the standard left no alternative.
  • d5792907 — this repository's interim carve-out in CLAUDE.md / AGENTS.md.
  • Operator decision 2026-09-01: handoff documents are not PR-worthy.

Activity

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