Skip to content

Decide whether the park path gets a composer, in a record superseding or extending ADR 0066 #381

Description

@randomparity

Part of #380

Problem

#380 asks for a park-path composer for the WORK:TRAJECTORY block. An accepted decision record
already considered that exposure and declined to close it, so the first deliverable here is a
decision, not code.

ADR 0066 (docs/adr/0066-compose-the-handoff-handshake.md, Accepted 2026-09-06) records the park
exposure in its Consequences as "a real residual, not an oversight", and rejects two of the shapes
#380 gestures at. Anatomy rule 2 compounds this: the evidentiary ground for shipping
publish-handoff was four logged failures (issue #308). The park path has zero observed
failures, by #380's own admission — so rule 2's "performed inconsistently" limb is not available
here on the terms 0066 used it.

That does not make #380 invalid. An accepted ADR settles whether an exposure was known and
accepted, not whether it must stay accepted, and the operator's filing is new input the record did
not have. It does mean the outcome of this issue is genuinely open in both directions.

Explicitly in scope: concluding that the park path should stay prose, and closing the two
child issues that depend on this one.
That outcome is a legitimate result of this issue, not a
failure of it.

Evidence

The accepted decision, and the three positions it already took:

  • docs/adr/0066-compose-the-handoff-handshake.md:5 — Status Accepted (2026-09-06).
  • docs/adr/0066-compose-the-handoff-handshake.md:34 — "The park path is unchanged and stays
    prose."
  • docs/adr/0066-compose-the-handoff-handshake.md:125-129 — Consequences: "Park notes keep the
    sentinel-omission exposure the hand-off just lost. That is a real residual, not an oversight",
    with its stated recovery: a reader "recovers from by opening the issue".
  • docs/adr/0066-compose-the-handoff-handshake.md:171-173Rejected, a
    --kind hand-off|park mode flag: "A park note that acquired a handshake would authorize a merge
    of work that is parked — strictly worse than the defect being fixed."
  • docs/adr/0066-compose-the-handoff-handshake.md:165-170Rejected, a general
    post-annotation helper covering every WORK:* type.
  • docs/adr/0066-compose-the-handoff-handshake.md:86-91 — the rule-2 argument the shipped helper
    stood on: "the evidence is the four holds issue Hand-off annotation is composed by hand and silently fails the merge gate #308 logs, from three different agents".

The three behaviours a park composer would have to differ on:

  • skills/return-to-town/scripts/publish-handoff:22-23 — the two markers are hardcoded constants;
    compose_body at :403 always emits the handshake line, and validate_notes at :223 refuses a
    narrative carrying either marker or MERGE-READY:. There is no mode.
  • skills/return-to-town/scripts/publish-handoff:342-382resolve_head requires GitHub's
    headRefOid to agree with git ls-remote origin, and refuses when they differ.
  • skills/quest/SKILL.md:1052-1065 — the park operation is two steps in one order: post the
    WORK:TRAJECTORY note, then swap the status: label. publish-handoff touches no labels.

Expected

A record in docs/adr/ that supersedes or extends ADR 0066 and settles, on evidence, four
questions — with "leave the park path as prose" available as the answer to all of them:

  1. Shape. A shared helper inside skills/return-to-town/scripts/publish-handoff versus a
    separate sibling executable. 0066 rejected the --kind flag; whether that rejection also
    forecloses a shared helper with separate entry points is this record's to decide.
  2. The absent-handshake mode. A park note must not be able to acquire a MERGE-READY line.
    That is 0066's stated reason for rejecting the flag, and any shape chosen here has to make it
    unreachable by construction, not by caller discipline.
  3. The relaxed branch-state refusal. publish-handoff refuses on remote-tip/headRefOid
    disagreement. That is correct for a hand-off and wrong for a park — a moved branch is a thing
    you might be parking about.
  4. Label ownership. Who owns the status: swap, given that the label change is part of the
    park operation and the hand-off composer touches no labels.

The record must re-argue anatomy rule 2 without the four-failure evidence, since the park path
has none. If that argument cannot be made honestly, the record says so and the park path stays
prose.

Proposed approach

Write the record through $spellcraft, weighing the alternatives 0066 already rejected and stating
which of its judgments survive the new input and which do not. Cite 0066 rather than restate it.
just records runs the record gate; the version bump rules in CLAUDE.md apply.

If the verdict is "stay prose", close this issue by merging the record and close the two dependent
children as not planned, citing it.

Out of scope

These belong elsewhere and must not be reopened here:

Sequencing

Nothing blocks this issue. It blocks the other two children of #380: the composer's shape is this
record's to decide, and if the record concludes "stay prose" neither of them is built.

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

    area:recordsADR and debt-record conventions, numbering, and record lifecycledocumentationImprovements or additions to documentationeffort:SSmall; hours, single sittingpriority:P2Normal prioritystatus:awaiting-mergegreen + mergeable; human just clicks merge

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions