Skip to content

feat(tickets): post ticket updates automatically after each event - #457

Merged
danielhanold merged 8 commits into
mainfrom
feat/update-tickets-automatically-after-each-event
Nov 11, 2026
Merged

danielhanold merged 8 commits into
mainfrom
feat/update-tickets-automatically-after-each-event

Conversation

@danielhanold

@danielhanold danielhanold commented Nov 11, 2026 •

Copy link
Copy Markdown
Owner

↩ Change 0587 — Update tickets automatically after each event

Summary

The four tickets.auto.* switches now do something. When one is on and the change already has a ticket, the workflow that just finished that step posts the update as a comment, without asking:

  • docket-groom-next and docket-auto-groom, after a change's first spec lands (spec_written);
  • docket-implement-next, after the PR opens (pr_opened), or after a results-only change completes (results_completed);
  • docket-finalize-change, after a merged change is closed out (pr_merged).

When a switch is off, or the change has no ticket, nothing happens and nothing is reported. A missing connector, a failed post, or a private repository costs one report line and never changes how the run ends. The maintenance sweep never posts, and when a stack root lands, only the root's ticket is updated.

  • The three steps every site follows are a shared definition in docket-convention, Automatic ticket updates. Each site carries its own DIRECTED to: direction.
  • docket-update-ticket gains an automatic path in references/automatic.md. On that path it never asks, runs no startup check of its own, posts nothing when the switch is off, and never retries.
  • tickets.auto.change_created is removed outright. A config file that still sets it now gets the normal unknown-key error.
  • The new docs/concepts/tickets.md explains how ticket work fits together and why docket never creates a ticket by itself. Both docs indexes list it, and config-keys.md and the glossary point to it.
  • Decision recorded in ADR-0163. ADR-0162 has a dated update note.

Tests

  • New site guard TestTicketAutoUpdateSites, in internal/app. It finds sites by their shape, wherever they appear under skills/, and checks four things: the five site files, one event token per site, DIRECTED to: at each site, and a pointer to the convention's definition at each site.
  • New prose contracts TestAutoTicketUpdateContracts cover the convention, the update skill, the sites, the concepts page, and the doc pointers.
  • Every new guard was mutation-tested. The full suite is green at the head.

Review (docket-review-deep)

# Severity Finding Disposition
1 important The switch-off guarantee at the sites was untested, and the update skill never checked event.switch fixed (ea50bba)
2 important The update skill's startup check could stop the calling workflow on a refused prepare fixed (d346c99)
3 minor ADR-0163 missing from the concepts page's Decided in fixed (2dae6e5)
4 minor config-keys.md and the example config said "nothing is reported" too absolutely fixed (2dae6e5)
5 minor Over-long line in config-keys.md fixed (2dae6e5)
6 minor The site guard recognized only the verb "invoke" fixed (2dae6e5)
7 minor The update skill's description covered only on-request use fixed (2dae6e5)

Human check

Before you rely on this, run the Important live check in the results file. Run it from a shared scratch repository against a sandbox ticket project, never from this repository.

…n is on request

Add docs/concepts/tickets.md: the link, the three ways a change gets a
ticket, on-request and automatic updates, the four events, shared and
private delivery, the connector, the settings, failure handling, the
invariants, and why docket never creates a ticket by itself. Index it in
both docs indexes, point config-keys.md and the glossary at the "why"
section, and add the automatic case to the docket-update-ticket entries.

Where the spec's drafted lines disagreed with the skills, the skills won:
- "A link is recorded only after the connector confirms the ticket":
  docket-link-ticket lets a person link by web address with no connector,
  reported as not verified. The invariant (and the glossary's
  docket-link-ticket entry) now says so.
- "With the switch off, nothing happens and nothing is reported": the
  convention's shared definition reports one "not checked" line when
  docket's own context.ticket read fails. The invariant names that case.
- "After a ticket exists, docket only adds comments and attachments":
  a companion skill may set fields and run follow-up actions right after
  creation. The invariant now reads "Beyond creating a ticket".
- "docket-link-ticket works through each of these with you": it does not
  judge whether the work needs a ticket or whether one already exists;
  the person makes those by asking. Reworded; every point kept.
- "the change has a ticket because you created or linked it": a change
  made from a ticket also has one. Added.
- "From then on the switches keep the ticket current": only in a shared
  repository. Qualified.

ADR-0044's file is on the integration branch, so it is linked; ADR-0162
and ADR-0161 are cited by number. The new ADR is a coordinator follow-up.
… is off

The update skill's automatic path now checks event.switch first, and the
site guard requires every site to point at the convention's shared
definition, whose second step stays silent when the switch is off.
… refused read

A workflow-invoked update runs no startup check of its own: the calling
workflow already ran it. A refused or error docket read on that path posts
nothing, reports one line, and returns to the workflow.
- The tickets concepts page cites ADR-0163 under "Decided in".
- config-keys.md and .docket.example.yml (and its embedded twin) say an
  off switch posts and reports nothing unless docket's own read of the
  change fails, matching the concepts page invariant.
- The rewritten tickets paragraph in config-keys.md is re-wrapped to the
  page's ~100-column width.
- The ticket-update site scan is keyed on shape: a block naming
  `docket-update-ticket` beside an event token is a site whatever verb
  carries it, unless every mention sits in a negated clause.
- The docket-update-ticket description covers a workflow invoking it after
  an event whose tickets.auto switch is on.
@danielhanold
danielhanold merged commit 13cc901 into main Nov 11, 2026
1 check passed
@danielhanold
danielhanold deleted the feat/update-tickets-automatically-after-each-event branch November 11, 2026 15:20
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant