diff --git a/.docket.example.yml b/.docket.example.yml index c6f3292df..46db83edb 100644 --- a/.docket.example.yml +++ b/.docket.example.yml @@ -265,9 +265,11 @@ change_types: [chore, docs, feat, fix, refactor, perf] # | Linear | team | none (labels) | # | Asana / Trello | project / board | none | # -# The `auto` switches name five events: a change is created, its spec is written, its pull -# request opens, its pull request merges, or its results are complete. All are off by default, -# and docket does not act on them yet. +# The four `auto` switches name events: a change's spec is written, its pull request opens, its +# pull request merges, or its results are complete. When one is on and the change has a ticket, +# the workflow that just finished that event posts the update to the ticket as a comment, without +# asking. All are off by default, and off means nothing is posted or reported, unless docket's own +# read of the change fails. # # Like most settings, these can be set in any layer. `provider` and `site` are usually the same for # every repository, so the global config suits them. A repository cancels a global value by @@ -294,7 +296,6 @@ tickets: companion_skill: "" auto: - change_created: false spec_written: false pr_opened: false pr_merged: false diff --git a/docs/README.md b/docs/README.md index b926a9498..fbe6c86f8 100644 --- a/docs/README.md +++ b/docs/README.md @@ -89,6 +89,8 @@ Index: [concepts/README.md](concepts/README.md) steps: rebase, retest, merge, archive. - [Learnings and ADRs as memory](concepts/memory.md) — the two records docket keeps of why a decision was made and what a build taught. +- [Tickets](concepts/tickets.md) — how a change links to a ticket in your team's ticket system, + and what docket posts there. ## Reference — exact fields and owners diff --git a/docs/concepts/README.md b/docs/concepts/README.md index 6e1c1b128..e5659665f 100644 --- a/docs/concepts/README.md +++ b/docs/concepts/README.md @@ -24,3 +24,5 @@ parts, the invariants, and the decisions behind it. chain of gated steps: rebase, retest, publish, merge, archive, clean up. - [Learnings and ADRs as memory](./memory.md) — the two records docket keeps of why a decision was made and what a build taught. +- [Tickets](./tickets.md) — how a change links to a ticket in your team's + ticket system, and what docket posts there. diff --git a/docs/concepts/tickets.md b/docs/concepts/tickets.md new file mode 100644 index 000000000..e97b10e41 --- /dev/null +++ b/docs/concepts/tickets.md @@ -0,0 +1,269 @@ +# Tickets + +## The problem it solves + +A team tracks its work in a ticket system (Jira, Linear, and the like), and +docket tracks it in changes. Without a connection between the two, a person +copies status across by hand: pastes the spec link into the ticket, notes +that the pull request opened, notes the merge. + +Docket links a change to its ticket and keeps the ticket informed, without +owning the ticket system. It installs no connector, stores no credential, +and has no code for any one ticket system. It decides nothing about what the +team is asked to work on: a ticket exists because a person created it or +chose it. + +## The moving parts + +``` + you, present ──▶ docket-link-ticket ── link, create, or read ─────┐ + │ │ + │ records the link │ + ▼ ▼ + ┌─ change record ────────┐ ┌─ ticket system ──┐ + │ ticket: system, id, │ │ the ticket │ + │ and web address │ └──────────────────┘ + └───────────┬────────────┘ ▲ + │ read with context.ticket │ + ▼ │ + you ask, or ───▶ docket-update-ticket ──── one short comment ─────┘ + a workflow after + an event whose + switch is on +``` + +Every arrow into the ticket system goes through the **connector**: the +ticket-system tools the running agent session already has. + +**The link.** A change carries at most one ticket: which ticket system it is +in, the ticket's id, and its web address. The link is stored on the change +record and shown as a Ticket row in the change's artifacts table. One ticket +may be on several changes, and docket names the others when it links one. A +change can be linked in any status, including after it is archived. A link +that was hand-edited into a broken state counts as not linked and is +reported as a warning (`ticket-link-invalid`), never a block; ticket work on +that change waits until a person fixes or removes it. + +**Three ways a change gets a ticket.** All three go through +`docket-link-ticket`, which runs only when a person asks, with that person +present: + +- **link an existing ticket to a change.** Docket checks through the + connector that the ticket exists. With no connector, you can still link it + by its web address, and docket says the ticket was not verified. +- **create a ticket from a change.** Docket first asks whether the change is + ready to hand over, asks you about whatever is missing, and follows your + team's companion skill, if you have one, for how the ticket is filed. It + shows you the whole draft and creates the ticket only on your go. The spec, + when the change has one, goes with it as the proposed approach, never as + requirements. +- **make a change from a ticket.** The ticket is read once and becomes a new + change: a stub that waits to be groomed like any other, with the ticket + already linked. Nothing is synced from the ticket afterwards. + +**Updates.** `docket-update-ticket` posts one short comment, written for +people who never open docket, and runs inside whichever session or workflow +agent invokes it. An update is posted in one of two ways: + +- **on request**, at any time: for any of the four events below, and also + for a revised spec, a blocker or a decision that is needed, or a killed + change. You can name people to mention, and the comment mentions them + in the ticket system's own way, so they are notified. +- **automatically**, by the docket workflow that just finished one of the + four events, when that event's switch is on and the change already has a + ticket. Nothing is asked and no draft is shown: the switch is the consent. + An automatic update mentions no one. + +**The four events.** Each event has its own switch, and each switch is off +until you turn it on. + +| Event and switch | When it happens | Posted automatically by | The update says | Goes with it | +|---|---|---|---|---| +| spec written, `tickets.auto.spec_written` | the change's first spec lands | `docket-groom-next` or `docket-auto-groom`, when grooming ends in a spec | the approach and key decisions, and where the change stands now | the spec | +| PR opened, `tickets.auto.pr_opened` | the pull request is open and the change is marked implemented | `docket-implement-next` | the pull request, what was built, and what the reviewer needs to know | the pull request, the spec, and the results file | +| PR merged, `tickets.auto.pr_merged` | the merged change is closed out | `docket-finalize-change` | what merged and where, key outcomes, and anything left to do; never a claim that it was deployed or accepted | the results file | +| results completed, `tickets.auto.results_completed` | a change whose deliverable is a results file completes | `docket-implement-next`, at the end of a results-only change | findings, conclusions, limits, and any action needed | the results file | + +Some things never post automatically. A change that the maintenance sweep or +a status refresh closes out gets no update, and neither does a change that +`docket-implement-next` closes out as a merged dependency of the change it +was asked to build. When a stack root lands, only the root's ticket is +updated, not its stacked children's; a stacked child gets its own merge +update when `docket-finalize-change` merges it into its parent's branch, and +that update says the work is not yet in the integration branch. A revised +spec, a blocker, a needed decision, and a killed change are updated on +request only. A change designed in the same run that creates it gets no +spec-written update, because it has no ticket yet. A run that is retried +after an event already happened may post the same update again; the +duplicate is deleted by hand. + +**What goes with an update.** In a shared repository, the comment carries +links to the spec and the results file, each pinned to the commit that holds +it, so a reader sees the file as it stood when the update was written. In a +private repository those files cannot be linked. There, an on-request update +attaches cleaned copies of them instead and posts the comment only after +every attachment lands, and an automatic update posts nothing and reports one +line. The pull request link stays a link in both. + +**The connector.** Docket reaches the ticket system only through the tools +the running agent session already has, such as an MCP server or plugin you +installed and signed in to. With no connector, a ticket can still be linked +by its web address, unverified; creating a ticket, making a change from one, +and posting an update cannot happen, and docket says so. An automatic update +is posted by whichever agent is running the workflow at the event, with that +agent's tools; when it has no connector, the update is not posted and the run +reports one line saying so. + +**The settings.** All of them are in +[the config keys reference](../reference/config-keys.md), and each can come +from any config layer. + +- `tickets.provider`, `tickets.site`, and `tickets.project` say which ticket + system the changes link to, where it lives, and where new tickets go. When + one that is needed is empty, `docket-link-ticket` asks you for it for that + run. +- `tickets.companion_skill` names your team's own skill for filing tickets. + It may decide the ticket type, the title format, the field values (sprint, + labels, assignee, priority, and the like), what happens after the ticket + exists, and how the calls are paced. It may not skip the readiness check, + replace the description docket writes, create a ticket you have not seen in + the draft, or record a link before the ticket is confirmed. +- `tickets.auto.spec_written`, `tickets.auto.pr_opened`, + `tickets.auto.pr_merged`, and `tickets.auto.results_completed` are the four + switches, one for each event. + +**When something goes wrong.** An update that fails or cannot be posted +costs one report line, naming what was not posted and why; an outcome the +connector did not confirm is reported as uncertain. Nothing is retried, +queued, or recorded as owed, and no run stops, fails, or changes its outcome +for it. If docket's own read of the change fails where an automatic update +would be posted, the workflow reports one line saying the ticket update was +not checked, and the run carries on. You can ask for the update later, and +it is written from the files as they stand then. + +## The invariants + +- A ticket is created only when a person asks and approves the draft. No + setting changes that. +- A link is recorded only for a ticket the connector confirmed, or, with no + connector, for a web address the person gave, reported as not verified. A + created ticket is recorded only after the connector confirms it exists. +- An automatic update posts only when its switch is on and the change + already has a ticket. With the switch off, nothing is posted and nothing is + reported, unless docket's own read of the change fails. +- An update is reported as posted only with the connector's confirmation. +- A failed update never stops, fails, or retries a run. A duplicate comment + is deleted by hand. +- Beyond creating a ticket, docket only adds comments and attachments to it. + It never changes the ticket's status, assignee, fields, or description on + its own, and nothing flows back from the ticket into the change. +- Docket installs no connector and stores no credential. + +## Why docket never creates a ticket by itself + +Docket posts updates to a ticket automatically. It does not create a ticket +automatically, and no setting makes it. A ticket is created only when you +ask (`create a Jira ticket from #12`), after you have seen the draft and +said go. There are two reasons. + +### Creating a ticket is a person's action + +A ticket is a statement to other people. It puts a piece of work into a +team's backlog, its planning, and often its notifications, and it says: this +is real work, and this is what done looks like. Docket treats that statement +as yours to make. Creating a ticket takes judgments that an agent running by +itself has no basis for: + +- **Whether the work should have a ticket at all.** Many changes never + should: a small chore, a fix found and made in the same hour, an idea that + is killed when it is designed. +- **Whether a ticket already exists.** The work may already be in the ticket + system in someone else's words. The right action is then to link the + change to that ticket, and only someone who knows the backlog can tell. +- **Whether the change is ready to hand over.** Before creating a ticket, + docket asks one question of the change: could another engineer take + ownership of this as a user story? When the answer is no, docket asks you + about the gaps (most often the acceptance criteria). Docket never invents + scope or acceptance criteria. +- **Where it goes and how it is filed.** The project, the ticket type, the + title format, the sprint, the labels, and the required fields follow your + team's conventions. +- **What it says.** The description is read by people who never open docket. + +When you ask for a ticket, you have made the first two judgments by asking, +and `docket-link-ticket` works through the rest with you: it checks that the +change is ready and asks about what is missing, follows your team's +companion skill for where and how the ticket is filed, and shows you the +whole draft before anything is created. An agent running unattended has +nobody to show it to. Automating creation would therefore mean one of two +things: tickets that nobody read before the team saw them, or an unattended +run that stops to ask, which defeats the point of running unattended. + +A ticket is also hard to take back. Once created it has a number, it may +have notified people, and deleting it may need a permission you do not have. +A wrong comment is deleted in seconds. + +Automatic updates are a different kind of action, which is why docket has +them. An update reports something that has already happened (the spec was +written, the pull request opened) on a ticket you already chose to have. You +made both decisions that matter: the change has a ticket because you created +it, linked it, or made the change from it, and updates are posted because +you turned the switch on. The agent decides nothing. It reports. + +That is the line docket draws: agents report on tickets, and people create +them. Automating a decision that belongs to a person is usually the wrong +tool, so docket offers no switch for it. + +### There is no one right moment to create it + +An automation needs a trigger: one point in a change's life at which the +ticket is created. There are two candidates, and neither works for every +change. + +Take an idea you capture while working on something else: "retry uploads +after a timeout". + +- **When the change is created.** You capture it as a stub in a few seconds + and go back to your work. The stub says why and what changes. It normally + has no acceptance criteria and no design, and capturing has to stay that + fast, so nothing can stop to ask you for them. A ticket created now would + be a title and two paragraphs with no definition of done. The stub may + later be killed, deferred, folded into another change, or reshaped when it + is designed, and the ticket would stay in the team's backlog describing + work nobody plans to do. +- **When the design is written.** Once the change is groomed it has + acceptance criteria and a spec, and it is much closer to ready. But this + moment has problems of its own. A design is written in three different + places: when you design a change as you create it, when you groom a stub, + and when a stub is groomed unattended. In the unattended case nobody is + there to approve a draft. Some changes already have a ticket by then, + because they were made from one or linked earlier. And a team that plans + its design work in the ticket system needs the ticket before this point, + not after it. + +A trigger at creation produces thin tickets for ideas that may never be +built. A trigger at design time produces unreviewed tickets from unattended +grooming, and comes too late for some teams. Supporting both would need a +rule for which changes are ready, more than one setting, and a set of special +cases, all to save you one sentence. + +So the trigger is you. Say `create a Jira ticket from #12` when the change +is ready, whenever that is. From then on, in a shared repository, the +switches keep the ticket current without you. + +## Decided in + +- ADR-0163 — Automatic ticket updates are per-event switches; ticket creation + is never automatic. +- ADR-0162 — made ticket work two skills that run inline and post through + the running agent's own connector tools: `docket-link-ticket` for linking, + creating, and importing, always with a person present, and + `docket-update-ticket` for updates, the only one an autonomous workflow + loads. +- ADR-0161 — stored a change's ticket link as three flat fields (the ticket + system, the id, and the web address), written together or not at all, with + a broken set reported, never blocking. +- [ADR-0044](../adrs/0044-autonomy-precedence-call-site-pre-specification.md) + — made the instruction written where a workflow invokes another skill + decide that skill's outcome, which is how a workflow tells + `docket-update-ticket` to post without asking. diff --git a/docs/reference/config-keys.md b/docs/reference/config-keys.md index af0823518..f6f606796 100644 --- a/docs/reference/config-keys.md +++ b/docs/reference/config-keys.md @@ -61,19 +61,23 @@ Each key has one scope: | `tickets.site` | `""` (unset) | any layer | where that ticket system lives; used when linking a ticket by URL or id | | `tickets.project` | `""` (unset) | any layer | where new tickets go (a project, team, repository, or board, by tool); used when creating a ticket | | `tickets.companion_skill` | `""` (unset) | any layer | the skill to follow for project-specific details when creating a ticket (title format, sprint, fields, labels, type) | -| `tickets.auto.change_created` | `false` | any layer | a switch for when a change is created; no effect yet | -| `tickets.auto.spec_written` | `false` | any layer | a switch for when a change's spec is written; no effect yet | -| `tickets.auto.pr_opened` | `false` | any layer | a switch for when a change's pull request opens; no effect yet | -| `tickets.auto.pr_merged` | `false` | any layer | a switch for when a change's pull request merges; no effect yet | -| `tickets.auto.results_completed` | `false` | any layer | a switch for when a change's results are complete; no effect yet | +| `tickets.auto.spec_written` | `false` | any layer | when on, the grooming workflows post an update to the change's ticket after its first spec lands | +| `tickets.auto.pr_opened` | `false` | any layer | when on, `docket-implement-next` posts an update to the change's ticket after its pull request opens | +| `tickets.auto.pr_merged` | `false` | any layer | when on, `docket-finalize-change` posts an update to the change's ticket after it closes out the merged change | +| `tickets.auto.results_completed` | `false` | any layer | when on, `docket-implement-next` posts an update to the change's ticket after a results-only change completes | | `agent_harnesses` | none | any layer | the dispatch opt-in (below) | | `agents...model` / `.effort` | the built-in table | global-only | model and effort pins for docket's agents | **`tickets`** settings are read by `docket-link-ticket` through `docket diagnostic config` when you link a change to a ticket or create one from a change: it uses `provider`, `site`, and -`project`, and asks for one it needs when it is empty. The five `auto` switches are reported by the -ticket context, but nothing acts on them yet. Each setting can come from any layer, so `provider` -and `site` can be set once in the global config, and a switch can be tried on one machine in +`project`, and asks for one it needs when it is empty. The four `auto` switches each let the +workflow that just finished an event post that event's update to the change's ticket by itself, +as a comment, with nothing asked. Creating a ticket has no switch: it is always on request +([why](../concepts/tickets.md#why-docket-never-creates-a-ticket-by-itself)). Off (the default) +means nothing is posted or reported, unless docket's own read of the change fails, and a switch +does nothing for a change with no ticket. In a private repository an automatic update posts +nothing and reports one line. Each setting can come from any layer, so `provider` and +`site` can be set once in the global config, and a switch can be tried on one machine in `.docket.local.yml`. To cancel a global value for one repository, write the default in `.docket.yml` (for everyone) or `.docket.local.yml` (for this clone): `project: ""` for a setting, `pr_opened: false` for a switch. A bare `project:` with nothing after it is not an empty value and diff --git a/docs/reference/glossary.md b/docs/reference/glossary.md index f91a17a0d..aea6512fe 100644 --- a/docs/reference/glossary.md +++ b/docs/reference/glossary.md @@ -1803,10 +1803,12 @@ stub rather than groom it, routes to `revise`. It runs inline at the session mod The skill an agent session uses for ticket work. It links a change to an existing ticket, creates a ticket from a change, or makes a change from a ticket, working through your session's own -connector tools for the ticket system. It records a link only after the connector confirms. +connector tools for the ticket system. It records a link only after the connector confirms, except +that with no connector you may link a ticket by its web address, reported as not verified. **Used for:** handing a change to a ticket system or pulling a ticket in. It runs inline, because it -needs you present and posts through your session's connector. +needs you present and posts through your session's connector. Docket never creates a ticket by +itself ([why](../concepts/tickets.md#why-docket-never-creates-a-ticket-by-itself)). ### docket-new-change @@ -1848,14 +1850,16 @@ inline. ### docket-update-ticket -The skill an agent session uses to post an update to a change's linked ticket when you ask. It posts -one short comment through your session's own connector, with spec and results links pinned to the -commit that holds them, and reports the update as posted only when the connector confirms. In a -private repository it attaches cleaned copies of the spec and results instead of linking them, and -posts the comment only after every attachment lands. +The skill an agent session uses to post an update to a change's linked ticket, when you ask or by +itself after an event whose switch is on. It posts one short comment through the session's own +connector, with spec and results links pinned to the commit that holds them, and reports the update +as posted only when the connector confirms. In a private repository it attaches cleaned copies of +the spec and results instead of linking them, and posts the comment only after every attachment +lands. An automatic update in a private repository posts nothing and reports one line. -**Used for:** telling people in the ticket system that something happened. It runs inline, because -it posts through your session's connector. +**Used for:** telling people in the ticket system that something happened. It runs inline, in +whichever session or workflow agent invokes it, because it posts through that session's own +connector. See [Tickets](../concepts/tickets.md). ### Fork / forked skill diff --git a/docs/reference/skills-and-agents.md b/docs/reference/skills-and-agents.md index 778c4eb89..74ccc26c3 100644 --- a/docs/reference/skills-and-agents.md +++ b/docs/reference/skills-and-agents.md @@ -26,7 +26,7 @@ Each line names one skill directory under `skills/` and its job. - **docket-new-change** — capture a new unit of planned work into the backlog through up-front design. - **docket-review** — the bounded read-only whole-branch reviewer role. - **docket-status** — refresh the backlog, sweep merged changes to done, and run health checks. -- **docket-update-ticket** — post a short update to a change's linked ticket when you ask (spec written, PR opened, PR merged, results completed, or a revision, blocker, or kill), with links pinned to the commit that holds them; in a private repository it attaches cleaned copies of the spec and results instead. +- **docket-update-ticket** — post a short update to a change's linked ticket when you ask, or automatically after an event whose `tickets.auto` switch is on (spec written, PR opened, PR merged, results completed; a revision, blocker, or kill only when you ask), with links pinned to the commit that holds them; in a private repository it attaches cleaned copies of the spec and results instead, and an automatic update there posts nothing. ## Default workflow roles diff --git a/docs/superpowers/specs/2026-11-11-update-tickets-automatically-after-each-event-design.md b/docs/superpowers/specs/2026-11-11-update-tickets-automatically-after-each-event-design.md new file mode 100644 index 000000000..16ef088cc --- /dev/null +++ b/docs/superpowers/specs/2026-11-11-update-tickets-automatically-after-each-event-design.md @@ -0,0 +1,351 @@ +# Update tickets automatically after each event — design + +Change 0587 — Update tickets automatically after each event + +Change #587, groomed interactively on 2026-11-11. Revised the same day at the person's request to add decision 9, which documents why ticket creation is not automated. Revised again to add the update note on ADR-0162, and again to widen the concepts page to the whole of ticket work. + +## Intent + +Today a change's ticket gets an update only when someone asks for one ("update CLOUD-123 now that the PR is open"). A team that wants its ticket system kept current has to remember to ask at every step. + +This change makes four config switches do something. When a switch is on and the change already has a ticket, the docket workflow that just finished that step posts the update as a comment, without asking anyone. When a switch is off, nothing happens at all. + +- **Before:** the PR opens; nothing reaches the ticket until a person asks. +- **After, with `tickets.auto.pr_opened: true`:** the PR opens; docket-implement-next posts the PR-opened comment to the change's ticket and its report says so in one line. + +This spec stands alone: it restates every rule the build needs. Nothing has to be read from the earlier ticket-integration design. + +## Words used here + +- **ticket**: the item in the team's ticket system (a Jira issue, a Linear issue, …). +- **connector**: the session's own tools for that system (an MCP server or plugin the person installed and signed in to). Docket installs no connector and stores no credential. +- **event**: a point in a change's life after which docket can post an update to its ticket. +- **update**: a short comment on the ticket, with the links that go with it. +- **automatic update**: an update a docket workflow posts by itself after an event whose switch is on. The other kind is **on request**: a person asks for it. On-request updates already exist and do not change. +- **site**: one place in a workflow skill where an automatic update can be posted. + +## Goals + +- With a switch on and a ticket linked, the update for that event is posted by the workflow running at the event, attended or not. +- With a switch off, no workflow posts, asks, or reports anything about tickets. The only cost is one extra read-only call at each site (decision 3). +- A failed or impossible post never stops, fails, blocks, or retries anything. It costs one report line. + +## Non-goals + +- Creating a ticket automatically (decision 6). +- Automatic updates in a private repository (decision 7; a later change adds them). +- Any new docket operation. The existing `context.ticket` read already returns everything a site needs. +- Any change to `docket-link-ticket`, or to how on-request updates work. + +## Anti-goals + +- A prompt, question, or approval step for an automatic update. +- A queue, ledger, delivery record, pending-update marker, or retry of any kind. +- A new blocking gate: no automatic update may change a run's disposition, write a halt or blocked marker, or stop a step that would otherwise run. +- A master switch or an "enable all" switch. + +## Decisions + +### 1. Four events, four switches + +| Event (`--event` token and switch name) | Fires when | Site | +|---|---|---| +| `spec_written` | a change's **first** spec lands: `change.groom` with `outcome: spec` | docket-groom-next, its Spec exit; docket-auto-groom, its Spec exit | +| `pr_opened` | the PR is open and the change is marked implemented: `change.mark-implemented` applied | docket-implement-next, Step 7 | +| `pr_merged` | a merged change is closed out: `finalize.closeout` | docket-finalize-change, after step 9 | +| `results_completed` | a results-only change completes: `change.complete` | docket-implement-next's results-artifact ending (`references/results-artifact.md`, section 6) | + +That is five sites in four skills. The switches are `tickets.auto.spec_written`, `tickets.auto.pr_opened`, `tickets.auto.pr_merged`, and `tickets.auto.results_completed`. Each is a boolean, `false` by default, settable at any config layer with normal precedence. They already exist; this change gives them their effect. + +Site details: + +- **docket-groom-next** posts only on its Spec exit (exit 1), after the transaction lands. Its kill, defer, revise, and re-enable exits never post. The person is in the session, and the update still posts without asking: the switch is the consent. +- **docket-auto-groom** posts per stub on its Spec exit, after the transaction lands and before it selects the next stub. An abstain never posts. Report lines go in the drain's final report. +- **docket-implement-next, Step 7** posts after `change.mark-implemented` returns its applied outcome and before the run declares its disposition. The disposition is `advanced` whatever the update's outcome. +- **The results-artifact ending** posts after `change.complete` returns `completed` or `already-completed`, before the run ends `advanced`. +- **docket-finalize-change** posts after `finalize.closeout` returns `done-archived`, `stacked-merged`, `root-archived`, or `already-closed-out`, and only for the change id that closeout call was made for. See decision 5 for what it never posts. + +**A replayed success posts like a first success.** `already-completed`, `already-closed-out`, and a `change.mark-implemented` retry that returns its earlier applied outcome all mean the event has happened, and the site cannot tell whether an earlier attempt got as far as posting. Docket keeps no record of what it posted, so a retried run can post the same update twice. That is accepted: a duplicate comment is deleted by hand, and a missed one would be silent. + +**docket-new-change is deliberately not a site.** It creates a change and lands its spec in the same run, and nothing in that skill links a ticket, so the change has no ticket when its spec lands and a site there could never post. A change that already has a ticket when it is designed (one imported from a ticket, or linked while still a stub) is groomed by docket-groom-next or docket-auto-groom, which are sites. + +### 2. Off means nothing happens + +When the switch for an event is off: no post, no prompt, no question, and no line in any report. The same holds when the switch is on and the change has no ticket: a change with no ticket never gets an update, and says nothing about it. + +There is no "ask before posting" mode, no handoff to a parent session, and no record that an update is owed. The artifacts are durable, so a person can always ask for the update later and it is composed from the artifacts as they stand. + +### 3. What every site does + +Each site does the same three things, in this order: + +1. **Read.** Run the `context.ticket` operation (argv from the capability catalog) with `--id --event --json`. +2. **Stay silent** when `context.event.switch` is `false`, or `context.ticket.state` is `not-linked`. Do nothing more and say nothing. +3. **Otherwise invoke `docket-update-ticket`** with a call-site direction, marked with the house marker `DIRECTED to:`, that states the outcome up front: post the update for this event and this change as an automatic update; nobody is present, so anything the skill would ask is answered by posting nothing and reporting one line; then return to the workflow. + +The update skill is loaded only in step 3, so a repository with the switches off, or a change with no ticket, never pays for it. + +If the read in step 1 does not return `result: applied`, the site reports one line (`Ticket update for # not checked: `) and carries on. It is a failure, not an "off": the site cannot know the switch's value, so it says so once. This is the one case where a repository with every switch off can see a ticket line, and it only happens when docket's own read is broken. + +**Where the rule lives.** The three steps are written once, as a shared definition in `docket-convention` (suggested heading: *Automatic ticket updates*). Each site is one short paragraph that names its event, points at that definition, and carries the `DIRECTED to:` direction itself. The direction must sit at the site, not only in the convention: a direction read at the moment of invocation is what outranks an instruction inside the invoked skill. + +### 4. What `docket-update-ticket` does when a workflow invokes it + +`docket-update-ticket` gains an automatic path. Its rules: + +- **The caller supplies the change id and the event.** Nothing is worked out from a person's words, and no one is mentioned. +- **It never asks and never waits.** No draft is shown. Wherever the on-request path would ask the person something, the automatic path posts nothing and reports one line. +- **It does its own `context.ticket` read**, as on request, so the update is composed from one pinned commit. +- **Cases that post nothing and report one line:** + - `ticket.state` is `partial`: the ticket link is broken. + - `event.happened` is `false`: name the missing fact from `event.reason`. + - `visibility` is anything other than `shared` (decision 7). + - no connector for `ticket.provider` is available in this session. + - the post failed, or its outcome is uncertain. An uncertain outcome is reported as uncertain. +- **`ticket.state` is `not-linked`:** post nothing and say nothing (the site normally filters this out first). +- **Otherwise it posts** exactly what an on-request update for that event posts in a shared repository: the same content table, the same editorial standard, the same commit-pinned links from the shared-delivery reference. +- **It reports one line** and returns: the update as posted only with the connector's confirmation, naming the ticket and the event; or what was not posted and why. +- **It never retries, and never touches the calling run.** No halt, no blocked marker, no changed disposition, no metadata write. A duplicate comment is acceptable and is deleted by hand. + +Report lines are plain, for example: + +> Posted the PR-opened update to CLOUD-123. + +> Not posted to CLOUD-123 (PR opened): no Jira connector is available in this session. + +The skill's opening, which today says it runs "only when the person asks" and that "Nothing here runs on its own after an event", is rewritten to say it runs when a person asks or when a docket workflow invokes it after an event whose switch is on. + +### 5. What never posts automatically + +- **The maintenance sweep.** `maintenance.sweep`, `maintenance.preflight`, and docket-status close out changes merged by other means and post nothing. A person can ask for the merge update later. +- **Stacked children when a stack root lands.** A `root-archived` closeout posts for the root only. The carried descendants (`carried_ids`) get nothing. A stacked child gets its own `pr_merged` update when docket-finalize-change merges it into its parent's branch (`stacked-merged`); that update already says the work is not yet in the integration branch. +- **docket-implement-next's bounded closeout of a named change's merged dependencies** (`references/edge-paths.md`, *Named invocation's own merged dependencies*). It calls `finalize.closeout` as housekeeping for other changes, like the sweep, and posts nothing. +- **A closeout that did not succeed.** `contended`, `blocked`, and `unknown` post nothing and report nothing: the event has not happened in this run. +- **A person running `change.complete` by hand.** No agent is running, so nothing fires. +- **A revised spec, a blocker or a needed decision, and a killed change.** These stay on request only. Whether a revision matters is a person's judgment, most of docket's own stops are machinery a ticket reader should not see, and a kill needs a person's explanation. + +### 6. Ticket creation is never automatic + +A ticket is only ever created when a person asks, through `docket-link-ticket`, where they see a draft and approve it. This change adds no automatic ticket creation at any point. + +This departs from the earlier ticket-integration design, which planned a fifth switch, `tickets.auto.change_created`, to create a ticket when a change is created. It was dropped at grooming, by the person's decision, for two reasons: + +1. **Creating a ticket is an action for a person, not for an agent.** A ticket tells a team that a piece of work is real and what done looks like. That is a person's statement to make, so automating it is usually the wrong approach. Automatic updates are different: they report something that already happened, on a ticket a person already chose to have. +2. **There is no clear place for the trigger.** At creation the change is often a quickly captured stub, which is not ready to be a ticket: it normally has no acceptance criteria, and capturing one must stay fast and ask nothing. After grooming the change has a full spec and is much closer to ready, but that moment has its own problems (decision 9 lists them). Supporting both moments was judged too complex for what it saves, which is one sentence from the person. + +Decision 9 writes both reasons out in full, and requires them in docket's documentation. + +**The `tickets.auto.change_created` key is removed.** It has no effect today and now never will. It has not been in a tagged release, so it is removed outright with no alias and no deprecation path: a config file that still sets it gets the normal unknown-key error (a warning from `install`). + +### 7. Private repositories and unknown visibility + +In a private repository nothing can be linked, so an update there needs cleaned attachments and a check that nothing leaks. That is a later change. Until then, an automatic update whose `context.ticket` read reports a `visibility` other than `shared` posts nothing and reports one line: + +> Not posted to CLOUD-123 (PR opened): automatic updates are not available in a private repository. + +On-request updates in a private repository are unaffected. + +### 8. Who posts + +The agent running the workflow at the event posts, with its own connector tools. That may be a dispatched or forked agent: docket-implement-next and docket-auto-groom both run that way, and they hold three of the five sites. + +Whether a connector is reachable inside such an agent depends on the harness. ADR-0162's context says a forked skill cannot reach the session's connector tools. A probe at grooming (2026-11-11, Claude Code) found otherwise for that harness: a dispatched general-purpose agent listed the session's ticket connector tools and could load their schemas. Nothing was called, and the probe did not use docket's own agent wrappers, so the live check in *Acceptance criteria* is what settles it for them. + +Where a connector is not reachable, the result is the "no connector" line in decision 4. It is never a handoff to the parent session, and no site is moved to make up for it. + +### 9. A concepts page explains how ticket work fits together, and why ticket creation is not automated + +Docket's user docs have no page that explains ticket work. It appears only in the reference tier: the config keys, the glossary, and the skills list. A person who wants to know what docket does with their ticket system has to piece it together from those entries, and a person who turns on the four switches will ask why there is no switch that creates the ticket. + +This change adds that page. The person added it to the design in two steps after the first spec landed: first the detailed reasoning for why ticket creation is not automated, then the higher-level description of how ticket work fits together. + +**Where it goes.** A new page in the concepts tier, `docs/concepts/tickets.md`. That tier is where docket explains "what each piece is and why it is shaped the way it is". The concepts tier was chosen at grooming; the person asked for "the normal docket documentation sections" and did not name a tier. + +**What kind of page it is.** It is the one place that explains the whole of ticket work at the level of what the pieces are, who acts, and what docket guarantees. It describes docket as it behaves once this change is built, including the parts earlier changes built (linking, creating, importing, on-request updates). It is not a walkthrough with steps, and it does not repeat the reference tier: it names each setting in a line and links to `config-keys.md` for the rest. + +**Source of truth.** The lists below say what the page covers, not what is true. The builder writes every statement from the skills and the binary as they stand at build time (`skills/docket-link-ticket/`, `skills/docket-update-ticket/`, the convention's *Ticket link* definition, and the `context.ticket` read), and where one of them disagrees with a line below, the skill or the binary wins. + +**The page's sections.** The four every concepts page has, plus one extra: + +*The problem it solves.* A team tracks work in a ticket system and docket tracks it in changes. Without a connection, a person copies status across by hand: pastes the spec link, notes that the PR opened, notes the merge. Docket links the two and keeps the ticket informed without owning the ticket system: it installs no connector, stores no credential, has no code for any one ticket system, and decides nothing about what the team is asked to work on. + +*The moving parts.* Each of these gets a short paragraph or a bullet, and the page opens the section with a diagram, as the other concepts pages do: + +- **The link.** A change carries at most one ticket: the ticket system, the ticket's id, and its web address, stored on the change record and shown in the change's artifacts table. One ticket may be on several changes. A change can be linked in any status, including after it is archived. A broken link is reported as a finding and never blocks anything. +- **Three ways a change gets a ticket**, all through `docket-link-ticket` and all with the person present: + - link an existing ticket to a change; + - create a ticket from a change: docket checks that the change is ready to hand over, asks about what is missing, shows the whole draft, and creates on the person's go; + - make a change from a ticket: the ticket is read once and becomes a stub to groom; nothing is synced from the ticket afterwards. +- **Updates.** `docket-update-ticket` posts one short comment written for people. It is posted in one of two ways: + - on request, at any time, for any of the four events below and also for a revised spec, a blocker or a needed decision, or a killed change; the person can name people to mention; + - automatically, after one of the four events, when that event's switch is on and the change already has a ticket. +- **The four events.** One table: the event, when it happens, which workflow posts the automatic update, what the update says, and what goes with it (the spec, the PR, the results file). The page also says what never posts automatically, in plain words: a change the maintenance sweep closed out, the stacked children of a root that lands, and anything that is not one of the four events. +- **What goes with an update.** In a shared repository, links pinned to the commit that holds each file, so a reader sees the file as it stood when the update was written. In a private repository nothing can be linked: an on-request update attaches cleaned copies instead, and an automatic update posts nothing and reports one line. +- **The connector.** Docket reaches the ticket system only through the tools the running agent session already has. With no connector, a ticket can still be linked by its address, unverified; creating, importing, and updating cannot happen and say so. +- **The settings.** One line each for where tickets go (`tickets.provider`, `tickets.site`, `tickets.project`), the team's own ticket skill (`tickets.companion_skill`) and what it may and may not decide, and the four `tickets.auto.*` switches, with a link to `config-keys.md`. +- **When something goes wrong.** An update that fails or cannot be posted costs one report line. Nothing is retried, queued, or recorded as owed, and no run stops for it. The person can ask for the update later, and it is written from the files as they stand then. + +*The invariants.* + +- A ticket is created only when a person asks and approves the draft. No setting changes that. +- A link is recorded only after the connector confirms the ticket. +- An automatic update posts only when its switch is on and the change already has a ticket. With the switch off, nothing happens and nothing is reported. +- An update is reported as posted only with the connector's confirmation. +- A failed update never stops, fails, or retries a run. A duplicate comment is deleted by hand. +- After a ticket exists, docket only adds comments and attachments to it. It never changes the ticket's status, assignee, fields, or description, and nothing flows back from the ticket into the change. +- Docket installs no connector and stores no credential. + +*Why docket never creates a ticket by itself.* The extra section, drafted below. + +*Decided in.* The ADR this change records (see *ADR*), ADR-0162, ADR-0161, and ADR-0044, cited the way the docs already cite an ADR whose file is not on the integration branch. + +**The extra section, in draft.** The builder may reword it and fit it to the page, but every point below must survive, including the worked example. It is deliberately long: the person asked for very detailed documentation. It is the only part of the page drafted here; the other sections are written at build from the sources above. + +> ## Why docket never creates a ticket by itself +> +> Docket posts updates to a ticket automatically. It does not create a ticket automatically, and no setting makes it. A ticket is created only when you ask ("create a Jira ticket from #12"), after you have seen the draft and said go. There are two reasons. +> +> ### Creating a ticket is a person's action +> +> A ticket is a statement to other people. It puts a piece of work into a team's backlog, its planning, and often its notifications, and it says: this is real work, and this is what done looks like. Docket treats that statement as yours to make. Creating a ticket takes judgments that an agent running by itself has no basis for: +> +> - **Whether the work should have a ticket at all.** Many changes never should: a small chore, a fix found and made in the same hour, an idea that is killed when it is designed. +> - **Whether a ticket already exists.** The work may already be in the ticket system in someone else's words. The right action is then to link the change to that ticket, and only someone who knows the backlog can tell. +> - **Whether the change is ready to hand over.** Before creating a ticket, docket asks one question of the change: could another engineer take ownership of this as a user story? When the answer is no, the gaps (most often acceptance criteria) are filled by asking you. Docket never invents scope or acceptance criteria. +> - **Where it goes and how it is filed.** The project, the ticket type, the title format, the sprint, the labels, and the required fields follow your team's conventions. +> - **What it says.** The description is read by people who never open docket. +> +> When you ask for a ticket, `docket-link-ticket` works through each of these with you and shows you the whole draft before anything is created. An agent running unattended has nobody to show it to. Automating creation would therefore mean one of two things: tickets that nobody read before the team saw them, or an unattended run that stops to ask, which defeats the point of running unattended. +> +> A ticket is also hard to take back. Once created it has a number, it may have notified people, and deleting it may need a permission you do not have. A wrong comment is deleted in seconds. +> +> Automatic updates are a different kind of action, which is why docket has them. An update reports something that has already happened (the spec was written, the pull request opened) on a ticket you already chose to have. You made both decisions that matter: the change has a ticket because you created or linked it, and updates are posted because you turned the switch on. The agent decides nothing. It reports. +> +> That is the line docket draws: agents report on tickets, and people create them. Automating a decision that belongs to a person is usually the wrong tool, so docket offers no switch for it. +> +> ### There is no one right moment to create it +> +> An automation needs a trigger: one point in a change's life at which the ticket is created. There are two candidates, and neither works for every change. +> +> Take an idea you capture while working on something else: "retry uploads after a timeout". +> +> - **When the change is created.** You capture it as a stub in a few seconds and go back to your work. The stub says why and what changes. It normally has no acceptance criteria and no design, and capturing has to stay that fast, so nothing can stop to ask you for them. A ticket created now would be a title and two paragraphs with no definition of done. The stub may later be killed, deferred, folded into another change, or reshaped when it is designed, and the ticket would stay in the team's backlog describing work nobody plans to do. +> - **When the design is written.** Once the change is groomed it has acceptance criteria and a spec, and it is much closer to ready. But this moment has problems of its own. A design is written in three different places: when you design a change as you create it, when you groom a stub, and when a stub is groomed unattended. In the unattended case nobody is there to approve a draft. Some changes already have a ticket by then, because they were made from one or linked earlier. And a team that plans its design work in the ticket system needs the ticket before this point, not after it. +> +> A trigger at creation produces thin tickets for ideas that may never be built. A trigger at design time produces unreviewed tickets from unattended grooming, and comes too late for some teams. Supporting both would need a rule for which changes are ready, more than one setting, and a set of special cases, all to save you one sentence. +> +> So the trigger is you. Say "create a Jira ticket from #12" when the change is ready, whenever that is. From then on the switches keep the ticket current without you. + +**Pointers to the page.** A reader meets the question in two places, and each gets one sentence that links to the extra section: + +- `docs/reference/config-keys.md`, in the paragraph under the table that describes the `tickets` settings: creating a ticket has no switch and is always on request. +- `docs/reference/glossary.md`, in the `docket-link-ticket` entry. + +The page is listed in both indexes, `docs/README.md` and `docs/concepts/README.md`. + +**Rules for the page.** + +- It states docket's standing position and the reasons for it. It does not name the removed `tickets.auto.change_created` key, and it does not say a switch was once planned or dropped. +- It cites no change and no pull request. ADR citations are allowed. +- It describes private repositories only as docket behaves when this change is built: an automatic update there posts nothing and reports one line. +- It makes no ticket-system claim that is not true of ticket systems in general; "may need a permission" is the level of claim wanted, not a statement about one product. + +## Where it lands + +Skills (each edit is mirrored in the embedded tree by `go generate ./internal/assets/`): + +- `skills/docket-convention/SKILL.md`: the shared definition (decision 3). +- `skills/docket-groom-next/SKILL.md`, `skills/docket-auto-groom/SKILL.md`, `skills/docket-implement-next/SKILL.md`, `skills/docket-implement-next/references/results-artifact.md`, `skills/docket-finalize-change/SKILL.md`: one site paragraph each (decision 1). +- `skills/docket-update-ticket/`: the rewritten opening and the automatic path (decision 4). + +Go: + +- Remove `tickets.auto.change_created` everywhere it appears. Derive the list from a whole-repository search for `change_created` and `ChangeCreated` rather than from this spec; at grooming it was the schema leaf, the config struct field, the resolver, the defaults, the `diagnostic.config` line, and the tests that enumerate the keys. Records already written (earlier specs and results) stay as they are. +- No other production Go changes. `context.ticket` is unchanged. + +Docs and samples: + +- `docs/reference/config-keys.md`: drop the `change_created` row; replace "no effect yet" on the other four with what each does; rewrite the paragraph below the table, which says nothing acts on the switches. +- `.docket.example.yml` and its embedded twin: drop `change_created` and rewrite the comment that says the switches name five events and are not acted on. If a frozen fixture copies this file, follow that fixture's own drift-guard remedy. +- `docs/reference/skills-and-agents.md` and `docs/reference/glossary.md`: the `docket-update-ticket` entries say it posts "when you ask"; add the automatic case. +- `docs/concepts/tickets.md` (new): the concepts page for ticket work, its two index entries, and the two pointers to it (decision 9). +- Docs describe only how docket behaves now: no mention of the removed key or of what was planned. The new page explains why ticket creation is always on request as a standing position, not as history. + +Size budgets in `internal/repoguard/budgets_test.go` are raised for each grown file, with this change's note, per that table's convention. + +## Tests + +- **Site guard (new).** Derive the sites from a scan of every Markdown file under `skills/`: a site is a line that invokes `docket-update-ticket` and names an event token. The convention's shared definition also invokes the skill but names no token; it is the only such line allowed, and the guard asserts that. Assert: + - the set of files holding a site is exactly the five in *Where it lands*, so a site added anywhere else (docket-status, docket-new-change, docket-link-ticket) turns it red; + - every site carries `DIRECTED to:` and names exactly one event token; + - every token in `ticketEvents` (`internal/app/ticket_context.go`) has at least one site, and no site names a token outside it; + - each site's token matches its file per the table in decision 1. + Key the scan on the invocation's shape, not on a list of spellings. `ticketEvents` is unexported, so the token checks belong in an `internal/app` test, beside the existing skill test for the ticket read; no production code is exported for this. +- **Prose contracts.** Pin the convention's shared definition (the read, both silent cases, the direction) and the update skill's automatic rules (never asks, the one-line cases, private posts nothing, never retries, never touches the run). Update the existing contract rows that pin "only when the person asks" on `docket-update-ticket` and the "when you ask" doc entries in the same commit. Add an absent-clause assertion that the skill no longer says nothing runs on its own. +- **The concepts page.** Add prose-contract rows for `docs/concepts/tickets.md`: one pinned clause for each of the two reasons (a person's action; no one right moment), one for the invariant that no setting creates a ticket, one for each of the three ways a change gets a ticket, one for each of the four event tokens, and the page's line in each index. These rows keep the page from losing a part; they cannot prove the page is accurate, so the builder checks each statement against the skills by reading, and the review does the same. Pin the two pointer sentences in `config-keys.md` and the glossary. The living-docs alignment guard already scans `docs/concepts`, so a change or PR citation on the page turns it red with no new test. +- **Config.** `tickets.auto.change_created` is rejected as an unknown key; the four remaining switches resolve as before. +- **Mutation-test every new guard**: remove a site, drop a `DIRECTED to:`, swap an event token, delete each pinned clause, and watch each turn red. Run with the test cache defeated. +- The whole suite runs at the build gate. +- **No ticket-system call is made from this repository**, in tests or otherwise, and this repository's `.docket.yml` still declares no `tickets` key. + +## ADR + +Record one ADR at build: automatic ticket updates are per-event switches where off means nothing happens, with no queue, ledger, retry, or prompt; a failure is one report line and never a gate; and ticket creation is never automatic. It gives both reasons for that last point as decision 6 states them (creating a ticket is a person's action; there is no clear place for the trigger, stub or groomed change), and names the stub-or-groomed-change alternatives it rejected. It relates to ADR-0044 (call-site directions) and ADR-0162 (the two inline ticket skills). It also states that the update skill now runs inside dispatched and forked agents. + +**ADR-0162 is not superseded or reversed.** Its decision stands and this change relies on it: two skills with no wrapper of their own, posting through the running agent's connector tools, with autonomous workflows loading only the update skill. What does not hold is half of one sentence in its Context, "A forked skill cannot reach the session's connector tools or ask the person", which its rejected alternative "A forked or agent-wrapped skill" repeats. The "cannot ask the person" half is still true, and by itself still rules out forking `docket-link-ticket`. + +So the build also appends a dated `## Update` note to ADR-0162, using docket-adr's *Update note* action (the one for a decision that stands while its surrounding facts changed). The note says only what was observed, so the later live check cannot make it false: + +- on 2026-11-11, in Claude Code, a dispatched general-purpose agent listed the session's ticket connector tools and loaded their schemas; nothing was called, and docket's own agent wrappers were not tried; +- so "cannot reach the session's connector tools" does not hold in every harness, while "cannot ask the person" does; +- the decision is unchanged, and the update skill now runs inside dispatched and forked workflow agents (name the new ADR). + +No separate change is needed to revisit ADR-0162. If the live check in *Acceptance criteria* finds that docket's own wrappers cannot reach the connector, the results say so under Known issues, and what to do about it is a new decision made then. + +## Acceptance criteria + +- With a switch on and a ticket linked, each of the five sites directs `docket-update-ticket` to post that event's update; the site guard pins all five and no others. +- With every switch off, no workflow posts, asks, or reports anything about tickets. +- With a switch on and no ticket, nothing is posted and nothing is reported. +- In a private repository an automatic update posts nothing and reports one line. +- A missing connector or failed post is one report line; the run's disposition and every later step are unchanged. +- The maintenance sweep and a stack root's descendants never get an automatic update. +- `tickets.auto.change_created` no longer exists in the schema, the sample config, or the docs. +- ADR-0162 keeps its `Accepted` status and carries a dated update note with the connector finding; the new ADR relates to it. +- `docs/concepts/tickets.md` exists and is listed in both docs indexes. It explains how ticket work fits together (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, and what happens on failure), and every statement on it matches the skills and the binary as built. It also explains in detail why docket never creates a ticket by itself: creating a ticket is a person's action, and there is no one right moment to create it (a stub is too early; a groomed change has its own problems). It keeps every point of the draft in decision 9, and `config-keys.md` and the glossary each point to it. +- The results list an **Important** live check, done by a person from a shared scratch repository against a sandbox ticket project, never from this repository: + - with each switch on in turn, run the workflow and confirm the comment arrives with working links; + - with the switch off, and with the switch on but no ticket, confirm nothing is posted and nothing is reported; + - confirm what a dispatched docket-implement-next and a forked docket-auto-groom do when they reach the post step: the comment, or the "no connector" line. + +## Out of scope + +- Automatic ticket creation, at change creation, at grooming, or anywhere else. +- Automatic updates in a private repository, and the leak check they need. +- Automatic updates for a revised spec, a blocker, a kill, or a change the sweep closed out. +- Updates to stacked descendants' tickets when a root lands. +- Mentions in automatic updates. +- Syncing ticket status, assignee, or fields; rewriting a ticket's description. +- Reordering docket-new-change's steps. +- A how-to guide page for ticket work. The new concepts page explains what the ticket pieces are, how they fit together, and why; it is not a walkthrough. +- Changing how linking, creating, importing, or on-request updates behave. The page describes them as they are. + +## Left to the builder + +- The exact wording of the convention's shared definition and of each site paragraph, within decisions 1 to 3. +- Whether the automatic path sits in `docket-update-ticket/SKILL.md` or in a new reference file loaded only when a workflow invokes the skill. A reference file matches how the skill already splits shared and private delivery. +- Where the docket-finalize-change site sits among its cleanup, integration-sync, and rebuild steps, as long as it follows closeout and its line reaches the final report. +- The exact wording of report lines. +- The concepts page's title, its wording, the shape of its diagram, and the order of its moving parts, as long as every part in decision 9 is covered and every point of the drafted section survives. Which clauses the prose contracts pin. +- The shape of the site-guard scan. + +## What the code says today + +Traced at main `4874f44ea`; anchors are symbols and headings, not line numbers. + +- `ContextTicketRead` (`internal/app/ticket_context.go`) already returns `event.switch` (the effective `tickets.auto.` value), `ticket.state`, `visibility`, `event.happened`, and commit-pinned artifact URLs. `ticketEvents` holds exactly the four tokens in decision 1; `change_created` was never one of them. +- The five `tickets.auto.*` leaves in `internal/config/schema.go` are `scopeAny`. `docs/reference/config-keys.md` describes all five as having "no effect yet". +- No workflow skill invokes `docket-update-ticket` today. `skills/docket-update-ticket/SKILL.md` opens with "only when the person asks" and "Nothing here runs on its own after an event", and a prose contract pins the first phrase. +- `finalize.closeout` returns `done-archived`, `stacked-merged`, `root-archived`, `already-closed-out`, `contended`, `blocked`, or `unknown`; `root-archived` carries `carried_ids`. Its callers are docket-finalize-change (step 9), the maintenance sweep and preflight, and docket-implement-next's bounded closeout in `references/edge-paths.md`. +- The user docs have no page about tickets outside the reference tier: `docs/concepts/` holds nine pages, none on tickets, and `docs/guide/` has no ticket page. Every concepts page has the four sections *The problem it solves*, *The moving parts*, *The invariants*, and *Decided in*; one page adds a fifth section of its own. `TestLivingDocsAlignment` (`internal/repoguard/docs_alignment_test.go`) scans `docs/concepts` for change and PR citations and allows ADR citations. No guard checks that a concepts page is indexed. The ADR files on the integration branch stop well short of ADR-0162, so the docs cite later ADRs by number without a relative link. +- `internal/repoguard/skill_handoff_sites_test.go` guards `DIRECTED to:` on role-skill invocations only. `docket-update-ticket` is not a role skill, so it needs its own guard. diff --git a/internal/app/config.go b/internal/app/config.go index 1e7eaad3d..132131a6b 100644 --- a/internal/app/config.go +++ b/internal/app/config.go @@ -277,7 +277,6 @@ func effectiveLines(eff *config.Effective) []effectiveLine { leafLine("tickets.site", textValue(eff.Tickets.Site.Value), eff.Tickets.Site.Provenance), leafLine("tickets.project", textValue(eff.Tickets.Project.Value), eff.Tickets.Project.Provenance), leafLine("tickets.companion_skill", textValue(eff.Tickets.CompanionSkill.Value), eff.Tickets.CompanionSkill.Provenance), - leafLine("tickets.auto.change_created", strconv.FormatBool(eff.Tickets.Auto.ChangeCreated.Value), eff.Tickets.Auto.ChangeCreated.Provenance), leafLine("tickets.auto.spec_written", strconv.FormatBool(eff.Tickets.Auto.SpecWritten.Value), eff.Tickets.Auto.SpecWritten.Provenance), leafLine("tickets.auto.pr_opened", strconv.FormatBool(eff.Tickets.Auto.PROpened.Value), eff.Tickets.Auto.PROpened.Provenance), leafLine("tickets.auto.pr_merged", strconv.FormatBool(eff.Tickets.Auto.PRMerged.Value), eff.Tickets.Auto.PRMerged.Provenance), diff --git a/internal/app/config_test.go b/internal/app/config_test.go index a8b90af2c..d9c8967c3 100644 --- a/internal/app/config_test.go +++ b/internal/app/config_test.go @@ -910,7 +910,6 @@ func TestConfigDiagnosticsTicketsSurface(t *testing.T) { "tickets.site = (unset) [built-in]", "tickets.project = (unset) [built-in]", "tickets.companion_skill = (unset) [built-in]", - "tickets.auto.change_created = false [built-in]", "tickets.auto.spec_written = false [built-in]", "tickets.auto.pr_opened = false [built-in]", "tickets.auto.pr_merged = false [built-in]", @@ -927,7 +926,7 @@ func TestConfigDiagnosticsTicketsSurface(t *testing.T) { src := []config.Source{{Layer: config.LayerRepository, Name: ".docket.yml", Data: []byte( "tickets:\n provider: jira\n site: tickets.example.com\n project: CLOUD\n" + " companion_skill: team-tickets\n" + - " auto:\n change_created: true\n spec_written: true\n pr_opened: true\n" + + " auto:\n spec_written: true\n pr_opened: true\n" + " pr_merged: true\n results_completed: true\n")}} r := DiagnosticConfig(src, mainCtx(), false) if r.Effective == nil { @@ -936,7 +935,7 @@ func TestConfigDiagnosticsTicketsSurface(t *testing.T) { tk := r.Effective.Tickets if tk.Provider.Value != "jira" || tk.Site.Value != "tickets.example.com" || tk.Project.Value != "CLOUD" || tk.CompanionSkill.Value != "team-tickets" || - !tk.Auto.ChangeCreated.Value || !tk.Auto.SpecWritten.Value || !tk.Auto.PROpened.Value || + !tk.Auto.SpecWritten.Value || !tk.Auto.PROpened.Value || !tk.Auto.PRMerged.Value || !tk.Auto.ResultsCompleted.Value { t.Errorf("effective tickets = %+v, want every declared value", tk) } @@ -946,7 +945,6 @@ func TestConfigDiagnosticsTicketsSurface(t *testing.T) { "tickets.site = tickets.example.com", "tickets.project = CLOUD", "tickets.companion_skill = team-tickets", - "tickets.auto.change_created = true", "tickets.auto.spec_written = true", "tickets.auto.pr_opened = true", "tickets.auto.pr_merged = true", @@ -960,7 +958,7 @@ func TestConfigDiagnosticsTicketsSurface(t *testing.T) { if err != nil { t.Fatal(err) } - for _, want := range []string{`"tickets":`, `"provider":`, `"companion_skill":`, `"auto":`, `"change_created":`, `"results_completed":`} { + for _, want := range []string{`"tickets":`, `"provider":`, `"companion_skill":`, `"auto":`, `"results_completed":`} { if !strings.Contains(string(raw), want) { t.Errorf("effective JSON lacks %s: %s", want, raw) } diff --git a/internal/app/ticket_auto_sites_test.go b/internal/app/ticket_auto_sites_test.go new file mode 100644 index 000000000..e88d7ed9d --- /dev/null +++ b/internal/app/ticket_auto_sites_test.go @@ -0,0 +1,308 @@ +package app + +import ( + "io/fs" + "os" + "path/filepath" + "regexp" + "slices" + "sort" + "strings" + "testing" +) + +// The automatic ticket-update sites. A tickets.auto. switch has an +// effect only where a workflow skill invokes docket-update-ticket for that +// event, so the sites are derived from a scan of every Markdown file under +// skills/ — never hand-listed — and checked against ticketEvents, which is +// unexported and so is checked here, beside the skill test for the ticket read. +// +// A block (a blank-line-separated paragraph, whitespace collapsed so a +// hard-wrapped paragraph is one string) is an INVOCATION in either of two +// shapes. Keyed on shape: a block that names the backticked +// `docket-update-ticket` and an event token (tickets.auto. or +// --event ) is a SITE whatever verb carries it ("invoke", "run", +// "load", or none), unless every mention of the name sits in a negated +// clause. Keyed on the verb: a block with no token is an invocation when it +// puts the name within 40 characters of an un-negated invoke verb, in either +// order, so a passive "is invoked" counts and a prohibition ("never invokes") +// does not. The convention's shared definition invokes the skill with no +// token; it is the only such invocation allowed. + +// ticketSiteFiles maps each repo-relative site file to the event it posts. +var ticketSiteFiles = map[string]string{ + "skills/docket-groom-next/SKILL.md": TicketEventSpecWritten, + "skills/docket-auto-groom/SKILL.md": TicketEventSpecWritten, + "skills/docket-implement-next/SKILL.md": TicketEventPROpened, + "skills/docket-implement-next/references/results-artifact.md": TicketEventResultsCompleted, + "skills/docket-finalize-change/SKILL.md": TicketEventPRMerged, +} + +// ticketDefinitionFile holds the shared definition every site follows. +const ticketDefinitionFile = "skills/docket-convention/SKILL.md" + +// ticketInvocation is one block that invokes docket-update-ticket. +type ticketInvocation struct { + rel, text string + tokens []string + directed bool + // follows reports whether the block points at the convention's shared + // definition, whose second step stays silent when the switch is off. + follows bool +} + +var ( + ticketBlockSplitRe = regexp.MustCompile(`\n[ \t]*\n`) + // ticketInvokeVerbRe is the invoke verb. Each occurrence is tested on its + // own, so a negated verb earlier in a block never hides a later one. + ticketInvokeVerbRe = regexp.MustCompile(`(?i)\binvok(?:e|es|ed|ing)\b`) + // The backticked name within 40 characters of the verb, in either order: + // after it ("invoke `docket-update-ticket`") or before it + // ("`docket-update-ticket` is invoked"). + ticketNameAfterRe = regexp.MustCompile("^[^.]{0,40}`docket-update-ticket`") + ticketNameBeforeRe = regexp.MustCompile("`docket-update-ticket`[^.]{0,40}$") + // ticketNegatedVerbRe is the negation shape of negatedInvokeRe in + // internal/repoguard/skill_handoff_sites_test.go (a word ending in "not", + // "never", or an n't contraction, within two words of the verb), anchored + // so the negated verb is the matched verb itself and not an earlier one. + ticketNegatedVerbRe = regexp.MustCompile(`(?i)(?:\b\w*not|\bnever|\w+n['’]t)\W+(?:\w+\W+){0,2}invok(?:e|ed|es|ing)$`) + ticketTokenRe = regexp.MustCompile(`tickets\.auto\.([a-z0-9_]+)|--event\s+([a-z0-9_]+)`) + ticketNameRe = regexp.MustCompile("`docket-update-ticket`") + // ticketNegationRe is a negation word: one ending in "not", "never", or an + // n't contraction, the same shape as ticketNegatedVerbRe. + ticketNegationRe = regexp.MustCompile(`(?i)(?:\b\w*not\b|\bnever\b|\w+n['’]t\b)`) + // ticketClauseEndRe ends the clause a mention of the name sits in. + ticketClauseEndRe = regexp.MustCompile(`[.;]`) +) + +// ticketMentionWindow is how far either side of a mention its clause is read. +const ticketMentionWindow = 40 + +const ticketDirectedMarker = "DIRECTED to:" + +// ticketDefinitionPointer is the clause that sends a site through the shared +// definition. Without it a site would invoke the skill with the switch off. +const ticketDefinitionPointer = "follow the convention's *Automatic ticket updates*" + +// ticketNegationLookback is how far before a match a negation may start. +const ticketNegationLookback = 30 + +// scanTicketInvocations returns every invocation block in files, a map of +// repo-relative path to content, sorted by path then position. +func scanTicketInvocations(files map[string]string) []ticketInvocation { + rels := make([]string, 0, len(files)) + for rel := range files { + rels = append(rels, rel) + } + sort.Strings(rels) + var out []ticketInvocation + for _, rel := range rels { + for _, raw := range ticketBlockSplitRe.Split(files[rel], -1) { + block := strings.Join(strings.Fields(raw), " ") + var tokens []string + for _, m := range ticketTokenRe.FindAllStringSubmatch(block, -1) { + tok := m[1] + m[2] + if !slices.Contains(tokens, tok) { + tokens = append(tokens, tok) + } + } + site := len(tokens) > 0 && hasUnnegatedTicketMention(block) + if !site && !hasUnnegatedTicketInvoke(block) { + continue + } + out = append(out, ticketInvocation{ + rel: rel, + text: block, + tokens: tokens, + directed: strings.Contains(block, ticketDirectedMarker), + follows: strings.Contains(block, ticketDefinitionPointer), + }) + } + } + return out +} + +// hasUnnegatedTicketInvoke reports whether block holds an invoke verb with +// the backticked name near it, in either order, whose own verb is not negated. +func hasUnnegatedTicketInvoke(block string) bool { + for _, loc := range ticketInvokeVerbRe.FindAllStringIndex(block, -1) { + if !ticketNameAfterRe.MatchString(block[loc[1]:]) && !ticketNameBeforeRe.MatchString(block[:loc[0]]) { + continue + } + if !ticketNegatedVerbRe.MatchString(block[max(loc[0]-ticketNegationLookback, 0):loc[1]]) { + return true + } + } + return false +} + +// hasUnnegatedTicketMention reports whether block names the backticked +// `docket-update-ticket` at least once outside a negated clause: no negation +// word within ticketMentionWindow characters before or after the mention, +// short of the nearest clause end (a period or semicolon). +func hasUnnegatedTicketMention(block string) bool { + for _, loc := range ticketNameRe.FindAllStringIndex(block, -1) { + before := ticketClauseEndRe.Split(block[max(loc[0]-ticketMentionWindow, 0):loc[0]], -1) + after := ticketClauseEndRe.Split(block[loc[1]:min(loc[1]+ticketMentionWindow, len(block))], -1) + if !ticketNegationRe.MatchString(before[len(before)-1]) && !ticketNegationRe.MatchString(after[0]) { + return true + } + } + return false +} + +func readSkillMarkdown(t *testing.T) map[string]string { + t.Helper() + root := filepath.Join("..", "..", "skills") + files := map[string]string{} + err := filepath.WalkDir(root, func(p string, d fs.DirEntry, err error) error { + if err != nil { + return err + } + if d.IsDir() || filepath.Ext(p) != ".md" { + return nil + } + raw, err := os.ReadFile(p) + if err != nil { + return err + } + rel, err := filepath.Rel(root, p) + if err != nil { + return err + } + files["skills/"+filepath.ToSlash(rel)] = string(raw) + return nil + }) + if err != nil { + t.Fatalf("walk %s: %v", root, err) + } + if len(files) < 20 { + t.Fatalf("population floor: only %d skill Markdown files found under %s", len(files), root) + } + return files +} + +func TestTicketAutoUpdateSites(t *testing.T) { + t.Run("non_vacuity", func(t *testing.T) { + passive := "**Ticket update.** Then `docket-update-ticket` is invoked **DIRECTED to:** post the update for `tickets.auto.pr_opened`." + wrapped := "**Ticket update.** Then `docket-update-ticket`\n is invoked **DIRECTED to:** post the\nupdate for `tickets.auto.pr_opened`." + got := scanTicketInvocations(map[string]string{ + "a.md": "Intro.\n\n" + passive + "\n\nOutro.", + "b.md": wrapped, + "c.md": "Housekeeping: the sweep never invokes `docket-update-ticket`.", + "d.md": "Invoke `docket-update-ticket` **DIRECTED to:** for `tickets.auto.spec_written` and `tickets.auto.pr_opened`.", + "e.md": "Run it with `--event `, then invoke `docket-update-ticket`.", + }) + byRel := map[string]ticketInvocation{} + for _, inv := range got { + byRel[inv.rel] = inv + } + for _, rel := range []string{"a.md", "b.md"} { + inv, ok := byRel[rel] + if !ok || !inv.directed || !slices.Equal(inv.tokens, []string{TicketEventPROpened}) { + t.Errorf("%s: a passive invocation (hard-wrapped in b.md) must be a directed invocation with token pr_opened; got %+v (found %v)", rel, inv, ok) + } + } + if inv, ok := byRel["c.md"]; ok { + t.Errorf("a prohibition must not be an invocation; got %+v", inv) + } + if inv := byRel["d.md"]; !slices.Equal(inv.tokens, []string{TicketEventSpecWritten, TicketEventPROpened}) { + t.Errorf("two named switches must yield two tokens; got %+v", inv) + } + if inv, ok := byRel["e.md"]; !ok || len(inv.tokens) != 0 { + t.Errorf("`--event ` must be an invocation with no token; got %+v (found %v)", inv, ok) + } + if byRel["a.md"].follows { + t.Errorf("a site without the definition pointer must not count as following it") + } + pointed := scanTicketInvocations(map[string]string{"g.md": "Then follow the convention's\n *Automatic ticket updates* for `tickets.auto.pr_opened`; invoke `docket-update-ticket` **DIRECTED to:** post it."}) + if len(pointed) != 1 || !pointed[0].follows { + t.Errorf("a hard-wrapped definition pointer must count as following it; got %+v", pointed) + } + // A site is keyed on shape, not on the verb: the name beside an event + // token is a site whatever verb carries it, unless the name sits in a + // negated clause. + shaped := scanTicketInvocations(map[string]string{ + "h.md": "Then run `docket-update-ticket` **DIRECTED to:** post it for `tickets.auto.pr_merged`.", + "i.md": "**Ticket update.** Load `docket-update-ticket`\n for `--event pr_opened`.", + "j.md": "Housekeeping never runs `docket-update-ticket` for `tickets.auto.pr_merged`.", + "k.md": "Posting the `tickets.auto.pr_opened` update is `docket-update-ticket`'s job; it does not run here.", + }) + shapedBy := map[string]ticketInvocation{} + for _, inv := range shaped { + shapedBy[inv.rel] = inv + } + if inv, ok := shapedBy["h.md"]; !ok || !slices.Equal(inv.tokens, []string{TicketEventPRMerged}) { + t.Errorf("a site worded with \"run\" must be a site with token pr_merged; got %+v (found %v)", inv, ok) + } + if inv, ok := shapedBy["i.md"]; !ok || !slices.Equal(inv.tokens, []string{TicketEventPROpened}) { + t.Errorf("a hard-wrapped site worded with \"load\" must be a site with token pr_opened; got %+v (found %v)", inv, ok) + } + if inv, ok := shapedBy["j.md"]; ok { + t.Errorf("a negated mention beside a token must not be a site; got %+v", inv) + } + if inv, ok := shapedBy["k.md"]; !ok || len(inv.tokens) != 1 { + t.Errorf("an un-negated mention beside a token is a site whatever its verb; got %+v (found %v)", inv, ok) + } + // A negation of an earlier verb must not negate a later invocation. + mixed := scanTicketInvocations(map[string]string{"f.md": "Do not invoke it twice; invoke `docket-update-ticket` once."}) + if len(mixed) != 1 { + t.Errorf("an earlier negated verb must not negate a later invocation; got %+v", mixed) + } + }) + + invocations := scanTicketInvocations(readSkillMarkdown(t)) + + var sites, bare []ticketInvocation + for _, inv := range invocations { + if len(inv.tokens) > 0 { + sites = append(sites, inv) + } else { + bare = append(bare, inv) + } + } + + perFile := map[string]int{} + covered := map[string]bool{} + for _, s := range sites { + perFile[s.rel]++ + want, isSiteFile := ticketSiteFiles[s.rel] + if !isSiteFile { + t.Errorf("%s: an automatic ticket-update site outside the five site files: %q", s.rel, s.text) + } + if !s.directed { + t.Errorf("%s: the site does not carry %q: %q", s.rel, ticketDirectedMarker, s.text) + } + if !s.follows { + t.Errorf("%s: the site does not carry %q, so it would post with the switch off: %q", s.rel, ticketDefinitionPointer, s.text) + } + if len(s.tokens) != 1 { + t.Errorf("%s: the site names %d event tokens %v, want exactly one", s.rel, len(s.tokens), s.tokens) + continue + } + tok := s.tokens[0] + if !slices.Contains(ticketEvents, tok) { + t.Errorf("%s: the site names %q, which is not a context.ticket event %v", s.rel, tok, ticketEvents) + } + if isSiteFile && tok != want { + t.Errorf("%s: the site names %q, want %q", s.rel, tok, want) + } + covered[tok] = true + } + for rel := range ticketSiteFiles { + if perFile[rel] != 1 { + t.Errorf("%s: %d automatic ticket-update sites, want exactly one", rel, perFile[rel]) + } + } + for _, ev := range ticketEvents { + if !covered[ev] { + t.Errorf("event %q has no automatic ticket-update site", ev) + } + } + if len(bare) != 1 || bare[0].rel != ticketDefinitionFile { + t.Errorf("want exactly one invocation with no event token, the shared definition in %s; got %d: %+v", ticketDefinitionFile, len(bare), bare) + } + if len(sites) != len(ticketSiteFiles) { + t.Fatalf("population: %d automatic ticket-update sites, want exactly %d", len(sites), len(ticketSiteFiles)) + } +} diff --git a/internal/assets/embedded/manifest.json b/internal/assets/embedded/manifest.json index 8449ab657..5b1d65690 100644 --- a/internal/assets/embedded/manifest.json +++ b/internal/assets/embedded/manifest.json @@ -1,14 +1,14 @@ { "format_version": 1, "asset_protocol": 1, - "asset_set_id": "sha256:d28bf7a5a890737ec3cb057b95cd07afa527adb64fc2c05a0c456ffcdb20883b", + "asset_set_id": "sha256:3e8ac6e90800c81120fe96716ea267dc849d27759910800f1582019dc9a264d9", "entries": [ { "path": ".docket.example.yml", "role": "config-schema", "mode": 420, - "size": 24542, - "sha256": "c36753fd7c45af579c42af58d5b994f40a9b6002594d8766954aafadbd90de46" + "size": 24708, + "sha256": "d1058e72a45cbfadacd25d6dfc0c7e7af5d021dba7c88e6adc7d4d6a45f3d46c" }, { "path": "agents/docket-adr.md", @@ -280,8 +280,8 @@ "path": "skills/docket-auto-groom/SKILL.md", "role": "skill", "mode": 420, - "size": 11011, - "sha256": "825a46b20f871f0d1ad6ed53c33fa7c9533657e938519a5d39b4d26b43677cce" + "size": 11501, + "sha256": "c822cb0b11df3d22b34fb85925c3f2b7e69483a7e494cb6a20acbbda1b24249d" }, { "path": "skills/docket-brainstorm/SKILL.md", @@ -322,8 +322,8 @@ "path": "skills/docket-convention/SKILL.md", "role": "skill", "mode": 420, - "size": 54394, - "sha256": "ad8863422c4033cd93de72620031a870303343bce988dc0eb033b9e49efd7ae7" + "size": 55895, + "sha256": "14153197ba3abc8ac8d4791eaf5bcb45cc94f8f0db42913fe0745ec5a6c3f023" }, { "path": "skills/docket-convention/references/agent-layer.md", @@ -364,8 +364,8 @@ "path": "skills/docket-finalize-change/SKILL.md", "role": "skill", "mode": 420, - "size": 43498, - "sha256": "c8c0b0eb5033ca12dc69fb4d7411671e188aef9cf14e0d408a38c606aa4ffb63" + "size": 44252, + "sha256": "30a92f47f520daff3924d2d813900705c703d4705d212b43605a75292a264bc0" }, { "path": "skills/docket-finalize-change/references/gate-failure.md", @@ -378,15 +378,15 @@ "path": "skills/docket-groom-next/SKILL.md", "role": "skill", "mode": 420, - "size": 15820, - "sha256": "4e5665aab5d649f74d16c66ba610801bb150cb612753dca9dcdd2b10f9a8d8b3" + "size": 16372, + "sha256": "0dbb61230ee7bff6ee179b61ffc1bae8e6932afffd71ee97e58e16469183cab3" }, { "path": "skills/docket-implement-next/SKILL.md", "role": "skill", "mode": 420, - "size": 60524, - "sha256": "63fb2fb741677a23ef5207f2fbe0babea56f4b9abced0f800a3ff088bb8b248d" + "size": 61093, + "sha256": "a2baf244bffa0996583b8e1ea1d38366acd7e4620a9ce16bb8bcef6bf0f56830" }, { "path": "skills/docket-implement-next/references/edge-paths.md", @@ -406,8 +406,8 @@ "path": "skills/docket-implement-next/references/results-artifact.md", "role": "skill", "mode": 420, - "size": 4899, - "sha256": "9581a92f684da771010a23a38f77b826c16e1ba651f4e5600547821c24333b61" + "size": 5410, + "sha256": "e6216e013c29f83f42750ab7bc7955dc445416a1a466877112ca5fc0394f892d" }, { "path": "skills/docket-implement-next/results-template.md", @@ -462,8 +462,15 @@ "path": "skills/docket-update-ticket/SKILL.md", "role": "skill", "mode": 420, - "size": 10079, - "sha256": "0f1e7f026c80b35f47c8204d80cabfec7a54aeef0f3e063b73cbf59c097cb57f" + "size": 10585, + "sha256": "961a6ed44d1b06bcd670a8079c798751834d67eea1795bfe355ce3561f674169" + }, + { + "path": "skills/docket-update-ticket/references/automatic.md", + "role": "skill", + "mode": 420, + "size": 2468, + "sha256": "79ec67d2b4824d07841efc17e51bfcc82bf9bc1f143a32b9bdabfd1b8ebc3543" }, { "path": "skills/docket-update-ticket/references/private.md", diff --git a/internal/assets/embedded/tree/.docket.example.yml b/internal/assets/embedded/tree/.docket.example.yml index c6f3292df..46db83edb 100644 --- a/internal/assets/embedded/tree/.docket.example.yml +++ b/internal/assets/embedded/tree/.docket.example.yml @@ -265,9 +265,11 @@ change_types: [chore, docs, feat, fix, refactor, perf] # | Linear | team | none (labels) | # | Asana / Trello | project / board | none | # -# The `auto` switches name five events: a change is created, its spec is written, its pull -# request opens, its pull request merges, or its results are complete. All are off by default, -# and docket does not act on them yet. +# The four `auto` switches name events: a change's spec is written, its pull request opens, its +# pull request merges, or its results are complete. When one is on and the change has a ticket, +# the workflow that just finished that event posts the update to the ticket as a comment, without +# asking. All are off by default, and off means nothing is posted or reported, unless docket's own +# read of the change fails. # # Like most settings, these can be set in any layer. `provider` and `site` are usually the same for # every repository, so the global config suits them. A repository cancels a global value by @@ -294,7 +296,6 @@ tickets: companion_skill: "" auto: - change_created: false spec_written: false pr_opened: false pr_merged: false diff --git a/internal/assets/embedded/tree/skills/docket-auto-groom/SKILL.md b/internal/assets/embedded/tree/skills/docket-auto-groom/SKILL.md index d8cbaf6aa..fee6cb078 100644 --- a/internal/assets/embedded/tree/skills/docket-auto-groom/SKILL.md +++ b/internal/assets/embedded/tree/skills/docket-auto-groom/SKILL.md @@ -54,11 +54,15 @@ Dispatch the dedicated **`docket-auto-groom-critic`** subagent (foreground, at t ### Step 5 — The outcome lands (no separate board pass) -Every exit's Step-4 `change.groom` operation is the whole write — it re-checks the pinned `revision` and commits the record, any spec, the `## Artifacts` block, and the inline board in one metadata commit pushed under an exact-lease push, so there is **no separate Board pass** and no hand-staged commit. On a `contended` refusal it writes nothing: re-sync (re-run the `repository.prepare` operation), re-read the stub's `path` + `revision` from the `status` operation, and if it is no longer auto-groomable (groomed, killed, claimed, or opted out) DISCARD this iteration's draft (discard the draft from scratch space) and move on; otherwise re-author and retry. Return to step 1. +Every exit's Step-4 `change.groom` operation is the whole write — it re-checks the pinned `revision` and commits the record, any spec, the `## Artifacts` block, and the inline board in one metadata commit pushed under an exact-lease push, so there is **no separate Board pass** and no hand-staged commit. On a `contended` refusal it writes nothing: re-sync (re-run the `repository.prepare` operation), re-read the stub's `path` + `revision` from the `status` operation, and if it is no longer auto-groomable (groomed, killed, claimed, or opted out) DISCARD this iteration's draft (discard the draft from scratch space) and move on; otherwise re-author and retry. + +**Ticket update.** After a spec exit's transaction lands, before step 1 selects the next stub, follow the convention's *Automatic ticket updates* for `tickets.auto.spec_written`; at its third step, invoke `docket-update-ticket` **DIRECTED to:** post the spec-written update for this change as an automatic update; nobody is present, so anything the skill would ask is answered by posting nothing and reporting one line; then return here. An abstain never posts. + +Return to step 1. ### Step 6 — Report -Summarize the drain: groomed N, abstained K — each abstain with its one-line reason — plus each change it held and anything skipped to a lost race. STOP. Grooming never implements; the build-ready output is `docket-implement-next`'s queue. +Summarize the drain: groomed N, abstained K — each abstain with its one-line reason — plus each change it held, anything skipped to a lost race, and each ticket-update line. STOP. Grooming never implements; the build-ready output is `docket-implement-next`'s queue. ## Termination & concurrency diff --git a/internal/assets/embedded/tree/skills/docket-convention/SKILL.md b/internal/assets/embedded/tree/skills/docket-convention/SKILL.md index 00da5f647..450490b7d 100644 --- a/internal/assets/embedded/tree/skills/docket-convention/SKILL.md +++ b/internal/assets/embedded/tree/skills/docket-convention/SKILL.md @@ -308,6 +308,16 @@ A stub is **auto-groomable** — selectable by `docket-auto-groom` — when it i **Interactive selection bands.** `docket-groom-next` still sees every needs-grooming stub, but its default order prefers stubs that need a human: (1) abstained (`## Auto-groom blocked` present), (2) `auto_groomable` unset or `false`, (3) `auto_groomable: true` — flagged "docket-auto-groom will handle it unless you want it now." Within each band, the deterministic selection order applies. The board renders abstained stubs as **auto-groom blocked — needs you**, distinct from plain needs-grooming. +### Automatic ticket updates (shared definition) + +A `tickets.auto.` switch lets the workflow that just finished an event post that event's update to the change's ticket by itself. Each workflow's own site names its event and the point it fires at. Every site does these three things, in order: + +1. **Read.** Run the `context.ticket` operation (argv from the capability catalog) with `--id --event --json`. +2. **Stay silent** when `context.event.switch` is `false` or `context.ticket.state` is `not-linked`: do nothing more and say nothing — no post, no prompt, no report line. +3. **Otherwise invoke `docket-update-ticket`** with the site's own `DIRECTED to:` direction, which names the change and the event and says the update is automatic. + +A read that does not return `result: applied` costs one report line, `Ticket update for # not checked: `, and the run carries on. An automatic update never prompts, waits, queues, retries, or records an update as owed. Its outcome never changes a run's disposition, writes a halt or blocked marker, or stops a later step: a failed or impossible post is one report line. A replayed success posts like a first success, so a retried run may post a duplicate, which is deleted by hand. Only the sites post. A closeout run as housekeeping (the maintenance sweep, a status refresh, or implement-next's closeout of a named change's merged dependencies) posts nothing, and when a stack root lands only the root's ticket is updated. + ### Discovered work Work an autonomous skill discovers mid-run is **reported in the run's final report, never silently diff --git a/internal/assets/embedded/tree/skills/docket-finalize-change/SKILL.md b/internal/assets/embedded/tree/skills/docket-finalize-change/SKILL.md index 82215a28f..61bdbdf1e 100644 --- a/internal/assets/embedded/tree/skills/docket-finalize-change/SKILL.md +++ b/internal/assets/embedded/tree/skills/docket-finalize-change/SKILL.md @@ -168,6 +168,8 @@ UTC archive date from the verified `mergedAt`, and applies one atomic transactio - `already-closed-out` — the promised final state already exists (a response-lost success): a keyed no-op, never a duplicate transition. - `contended` / `blocked` / `unknown` — a lost race, an illegal source status or destination mismatch, or an unobservable probe; re-read context (`contended`) or stop (`halted`). Close-out is one metadata commit plus the best-effort PR-description backlink repoint; nothing touches the integration branch. A PR description that could not be repointed is a `pr-backlink-pending` warning on an otherwise-final result: report it, never redo the merge; cleanup (step 10) and the maintenance sweep retry it. +**Ticket update.** After `finalize.closeout` returns `done-archived`, `stacked-merged`, `root-archived`, or `already-closed-out` for a change this run closed out, follow the convention's *Automatic ticket updates* for `tickets.auto.pr_merged`; at its third step, invoke `docket-update-ticket` **DIRECTED to:** post the PR-merged update for this change as an automatic update; ask nothing, so anything the skill would ask is answered by posting nothing and reporting one line; then return here. Post once for each change a closeout call was made for, never for a `root-archived` result's `carried_ids`, and never after `contended`, `blocked`, or `unknown`. The line goes in the final report, and the update's outcome never changes the run's disposition. + ### 10. Cleanup — Docket-owned resources only The `finalize.cleanup` operation with `--id `. An ordered, independently retryable suffix: repair the PR description's backlink first when it is pending, remove the workspace from manifest facts, delete the local branch only when its exact recorded tip is worktree-detached and contained in the verified merge chain, and delete the remote ref only under the exact lease after a fresh probe shows no open child PR targets it. Every probe treats present, cleanly absent, and unknown as three outcomes — an injected or real probe error retains the resource with a pending result and `children-retarget-required`/a retention reason, never a destroy. A non-final change refuses (the one pre-final exception is restoring an aborted owned rebase). Stacked-merged changes retain their workspace and branches until the root closes. After `root-archived`, run cleanup for the root, then for each id in its `carried_ids`, reporting each result like the root's; a child's result never changes another's. A carried child's folder and branches go only once its work is proven on the integration branch through its stack; otherwise it keeps everything and reports `pending` (`carry-unproven`, or `destination-mismatch` for an unproven stack relationship), with no delete advice. Cleanup failure never unwinds the merge. Once the workspace leg finishes, any disposition (`cleaned`, `pending`, `children-retarget-required`) may carry a `workspace-remnant` warning naming a leftover folder to delete by hand — name it in the final report; a `workspace-blocked` finding names what blocked the workspace. diff --git a/internal/assets/embedded/tree/skills/docket-groom-next/SKILL.md b/internal/assets/embedded/tree/skills/docket-groom-next/SKILL.md index e62af2310..7a93a1cd8 100644 --- a/internal/assets/embedded/tree/skills/docket-groom-next/SKILL.md +++ b/internal/assets/embedded/tree/skills/docket-groom-next/SKILL.md @@ -70,7 +70,11 @@ All five exits reuse existing transitions — this skill introduces no new lifec ### Step 5 — The transaction lands (no separate board pass) -The Step-4 typed op is the whole write: it re-checks the pinned exact `revision`, commits the change record, the spec, the `## Artifacts` block, and the inline board in one metadata commit pushed to the metadata remote under an exact-lease push — so there is no separate hand-staged commit and **no separate Board pass** (the readiness cell flips from needs-grooming, or the row leaves the Proposed section on a kill or defer, in that same commit; a revise keeps the row's readiness unless it sets or lifts a hold; a re-enable returns an abstained row to needs-grooming). On a `contended` refusal the op writes nothing: re-sync (re-run the `repository.prepare` operation), re-read the record's `path` + `revision` from the `status` operation, and — on a groom exit, if it is no longer needs-grooming (someone else groomed, killed, or claimed it) — STOP and report rather than overwrite; otherwise re-author and retry. On a revise, also re-read the spec (a fresh `spec_revision`) and stop if the change is no longer `proposed` or a stub edit finds it groomed (`spec:`). STOP — grooming never implements. +The Step-4 typed op is the whole write: it re-checks the pinned exact `revision`, commits the change record, the spec, the `## Artifacts` block, and the inline board in one metadata commit pushed to the metadata remote under an exact-lease push — so there is no separate hand-staged commit and **no separate Board pass** (the readiness cell flips from needs-grooming, or the row leaves the Proposed section on a kill or defer, in that same commit; a revise keeps the row's readiness unless it sets or lifts a hold; a re-enable returns an abstained row to needs-grooming). On a `contended` refusal the op writes nothing: re-sync (re-run the `repository.prepare` operation), re-read the record's `path` + `revision` from the `status` operation, and — on a groom exit, if it is no longer needs-grooming (someone else groomed, killed, or claimed it) — STOP and report rather than overwrite; otherwise re-author and retry. On a revise, also re-read the spec (a fresh `spec_revision`) and stop if the change is no longer `proposed` or a stub edit finds it groomed (`spec:`). + +**Ticket update.** After a spec exit's transaction lands, follow the convention's *Automatic ticket updates* for `tickets.auto.spec_written`; at its third step, invoke `docket-update-ticket` **DIRECTED to:** post the spec-written update for this change as an automatic update; ask the person nothing, so anything the skill would ask is answered by posting nothing and reporting one line; then return here. The person being in the session changes nothing: the switch is the consent, so nothing is asked. Kill, defer, revise, and re-enable never post. + +STOP — grooming never implements. ## Concurrency — no claim diff --git a/internal/assets/embedded/tree/skills/docket-implement-next/SKILL.md b/internal/assets/embedded/tree/skills/docket-implement-next/SKILL.md index 8ff93c256..dcf60909b 100644 --- a/internal/assets/embedded/tree/skills/docket-implement-next/SKILL.md +++ b/internal/assets/embedded/tree/skills/docket-implement-next/SKILL.md @@ -156,6 +156,8 @@ The results artifact is **required for every implemented change** — there is n **Mark implemented.** The `change.mark-implemented` operation with `--id --revision --head --pr --evidence ` is the final mutation in this scope. Before its transaction it reprobes Git and GitHub and proves: the change is still the exact `in-progress` revision, `reconciled: true`, linked to the verified plan; local and remote feature heads equal the supplied head; valid evidence names that head and a passed gate; exactly one verified PR for the feature branch targets the resolved effective-base branch and names that head; and a results artifact is attached, read from the metadata branch, and satisfies the final content contract and its artifact identity (missing, invalid, or unattached results refuse the transition). It then applies the landed transition atomically — `status: implemented` + `pr:` + updated date + the verified evidence as the record's `## Build evidence` section + `## Artifacts` block + inline board + audit receipt (letting the sweep read `pr:`), rendering the board inside that transaction, so no separate Board pass runs. It does NOT clear the claim, delete the branch/workspace, merge, archive, or close descendants. A retry against an already-`implemented` change with matching PR/head returns the prior applied outcome, never a duplicate transition. +**Ticket update.** After `change.mark-implemented` returns its applied outcome (a retry's earlier applied outcome included), follow the convention's *Automatic ticket updates* for `tickets.auto.pr_opened`; at its third step, invoke `docket-update-ticket` **DIRECTED to:** post the PR-opened update for this change as an automatic update; nobody is present, so anything the skill would ask is answered by posting nothing and reporting one line; then return here. The run's disposition is `advanced` whatever the update's outcome, and its line goes in the final report. + **Verify the run.** The `run.verify` operation with `--id ` is read-only: it reports one closed verdict — `run-complete` / `run-unclaimed` / `run-incomplete` / `run-halted` / `run-waiting` — and enumerates every unmet condition with its stable reason and observed identity. Automation keys on the typed verdict, **never** the exit code (all verdicts exit 0). `run-complete` is the receipt that Step 7's postcondition (or the results-artifact ending's) holds; `run-halted` is the closed verdict for a change carrying a `## Run halted` marker — a human is needed, and an attributed caller re-dispatches it through the resume path (the `change.resume-halted` operation with `--acknowledge-quiescent`, Step 2), never a fresh claim. `run-waiting ` is the closed verdict for a change whose gate stopped at a safe, resumable continuation — neither complete nor failed: an attributed caller resumes that exact handoff rather than drawing another change or re-dispatching a fresh run, and precedence is completed-run postconditions first, then a valid `run-waiting`, then ordinary `run-incomplete`; a persisted `run-halted` stays terminal. A run **dispatched with an explicit change id, continuation id, and run key resumes, not restarts**: its FIRST act is the `run.continue` operation with ` `, claiming the recovered drive **before any other work**; it never launches a replacement test, and this is a **continuation, not `run-retry-once`** — the key stays active until a true terminal disposition. Each `run-retry-once` authorizes exactly one next dispatch; the run tracker may grant another on a later eligible attempt while the configured `run.max_attempts` budget allows, and a continuation consumes none of that budget. A gated parent's prompt may also carry a **run context** token; pass it, always as `--run-context`, into every build-owned `gate.drive.start` (`--owner build` — Step 6's evidence re-mint and re-gates, the build role's final suite gate, and each post-repair attempt the build role starts) this run performs — each invoked with `--json` per the shared capture requirement and each always carrying `--change-id ` — and into the Step-2 claim, omitting it only when the prompt carried none (a `run-untracked` or ungated run). Build-task workers never receive it: they run their tests directly and call no gate operation. **STOP.** The change stays in `active/` as `implemented` until a human merges it, or approves `docket-finalize-change` to merge it. diff --git a/internal/assets/embedded/tree/skills/docket-implement-next/references/results-artifact.md b/internal/assets/embedded/tree/skills/docket-implement-next/references/results-artifact.md index 31e08a76c..5f3416ff1 100644 --- a/internal/assets/embedded/tree/skills/docket-implement-next/references/results-artifact.md +++ b/internal/assets/embedded/tree/skills/docket-implement-next/references/results-artifact.md @@ -72,5 +72,12 @@ and how its findings ended. left in the worktree, commits on the branch) goes into the run report; it **never halts the run and never undoes the completion**. +**Ticket update.** After `change.complete` returns `completed` or `already-completed`, follow the +convention's *Automatic ticket updates* for `tickets.auto.results_completed`; at its third step, +invoke `docket-update-ticket` **DIRECTED to:** post the results-completed update for this change +as an automatic update; nobody is present, so anything the skill would ask is answered by posting +nothing and reporting one line; then return here. The run still ends `advanced`, and the line goes +in the final report. + End the run `advanced`. The final report names the results path and the cleanup disposition, plus the usual skipped changes and follow-up work with their backlog verdicts. diff --git a/internal/assets/embedded/tree/skills/docket-update-ticket/SKILL.md b/internal/assets/embedded/tree/skills/docket-update-ticket/SKILL.md index e2a65e988..b81f8d87c 100644 --- a/internal/assets/embedded/tree/skills/docket-update-ticket/SKILL.md +++ b/internal/assets/embedded/tree/skills/docket-update-ticket/SKILL.md @@ -1,20 +1,22 @@ --- name: docket-update-ticket -description: 'Use when the person asks to post an update or comment about a change to its ticket (`update CLOUD-123 now that the PR is open`, `tell the ticket the spec for #12 is written`, `let PROJ-9 know #40 was killed`); not for creating or linking a ticket.' +description: 'Use when the person asks to post an update or comment about a change to its ticket (`update CLOUD-123 now that the PR is open`, `tell the ticket the spec for #12 is written`, `let PROJ-9 know #40 was killed`), or when a docket workflow invokes it after an event whose `tickets.auto` switch is on; not for creating or linking a ticket.' --- # docket-update-ticket -This skill runs inline, in your own session, and only when the person asks: it posts one short comment to a change's linked ticket with your own tools. Nothing here runs on its own after an event. +This skill runs inline, in the session or workflow agent that invokes it: when the person asks, or when a docket workflow invokes it after an event whose `tickets.auto` switch is on. It posts one short comment to a change's linked ticket with that session's own tools. Words used here: a **ticket** is the item in the team's ticket system; the **provider** is which ticket system it is (`jira`, `linear`, …); a **connector** is the session's own tools for that system (an MCP server or plugin the person installed and signed in to); an **update** is the comment you post, with its links. Docket installs no connector and stores no credential. ## Convention (load first — blocking) -Invoke the `docket-convention` skill via the Skill tool first — unless already invoked this session — and run its *startup check*. Everything below uses its vocabulary. +Invoke the `docket-convention` skill via the Skill tool first — unless already invoked this session — and run its *startup check*. When a docket workflow invoked this skill, that workflow has already run the startup check: run none here. Everything below uses its vocabulary. This skill makes no docket metadata write. Its reads are the `context.ticket` operation and, for a request naming only a ticket, the `status` operation (section 1); in a private repository it also invokes `docket-export`, which writes each exported file to a temp directory and may read `leak_check.match_word` through `diagnostic.config` (section 4). Run `context.ticket` (argv from the capability catalog) with `--id `, `--event ` when the update follows an event, and `--json`. Its result is under `context`: `metadata_commit`, `visibility`, `change` (`status`, `deliverable`, `path`), `ticket` (`state`: `linked`, `not-linked`, or `partial`; and `provider`, `id`, `url` when `linked`), `event` (`happened`, and `reason` when not), `facts` (`pr_url`, `merge`), and `artifacts` (`role`, `path`, `url`). +**Invoked by a workflow.** When a docket workflow invoked this skill after an event, **read `references/automatic.md` now (blocking)** before section 1. It replaces sections 1, 2, and 5, and every point where this skill would ask or wait. + ## 1. Work out the request - **The change.** Usually named (`#612`). When the request names only a ticket, find the changes whose record carries that ticket in the `records` array of the `status` operation run with `--json --records`. Exactly one: use it. Several (one ticket may be on several changes): ask the person which. None: say no change carries that ticket. diff --git a/internal/assets/embedded/tree/skills/docket-update-ticket/references/automatic.md b/internal/assets/embedded/tree/skills/docket-update-ticket/references/automatic.md new file mode 100644 index 000000000..94a53b6e2 --- /dev/null +++ b/internal/assets/embedded/tree/skills/docket-update-ticket/references/automatic.md @@ -0,0 +1,14 @@ +# Automatic updates + +Loaded from `SKILL.md` when a docket workflow invoked this skill after an event whose switch is on. The rules in `SKILL.md` apply except where this file replaces them. + +- **The caller supplies the change and the event.** Take both from the workflow's direction. Nothing is worked out from a person's words, and no one is mentioned: skip sections 1 and 5. +- **Never ask and never wait.** Show no draft. Wherever the on-request path would ask the person something, post nothing and report one line. +- **No startup check of its own.** The calling workflow already ran it: take `metadata_worktree_path` from the caller's `repository.prepare` context. A `refused` or `error` answer from a docket read on this path is never a stop: post nothing, report one line (`Not posted to # (): .`), and return to the workflow. +- **Read first.** Run the `context.ticket` read yourself with `--id`, `--event`, and `--json`, as on request, so the update is composed from one pinned commit. +- **`event.switch` is `false`:** post nothing and say nothing, whatever the caller directed. Check this first, before anything else the read returned. +- **`ticket.state` is `not-linked`:** post nothing and say nothing. +- **Otherwise post nothing and report one line** when `ticket.state` is `partial` (the ticket link is broken); when `event.happened` is `false` (name the missing fact from `event.reason`); when `visibility` is anything other than `shared` (`automatic updates are not available in a private repository`); when no connector for `ticket.provider` is available in this session; or when the post failed or its outcome is uncertain (an uncertain outcome is reported as uncertain). +- **Otherwise post** exactly what an on-request update for this event posts in a shared repository: its row of section 3's table, the editorial standard, and the links. **Read `references/shared.md` now (blocking).** Never load `references/private.md` on this path. +- **Report one line** and return to the workflow: the update as posted, only with the connector's confirmation, naming the ticket and the event (`Posted the PR-opened update to CLOUD-123.`); or what was not posted and why (`Not posted to CLOUD-123 (PR opened): no Jira connector is available in this session.`). +- **Never retry, and never touch the calling run:** no halt, no blocked marker, no changed disposition, and no metadata write. A duplicate comment is acceptable and is deleted by hand. diff --git a/internal/config/config.go b/internal/config/config.go index 9763e95b4..ef0f55c94 100644 --- a/internal/config/config.go +++ b/internal/config/config.go @@ -161,7 +161,6 @@ type Tickets struct { // TicketsAuto holds the switches that let docket act on a linked ticket on // its own after each event. All default off. type TicketsAuto struct { - ChangeCreated Value[bool] `json:"change_created"` SpecWritten Value[bool] `json:"spec_written"` PROpened Value[bool] `json:"pr_opened"` PRMerged Value[bool] `json:"pr_merged"` diff --git a/internal/config/decode_test.go b/internal/config/decode_test.go index 07bc9a434..752e96de1 100644 --- a/internal/config/decode_test.go +++ b/internal/config/decode_test.go @@ -149,9 +149,6 @@ func decodeAcceptanceCases() []decodeCase { {row: "tickets.companion_skill", path: "tickets.companion_skill", block: "tickets:\n companion_skill: team-tickets\n", flow: "tickets: {companion_skill: team-tickets}\n", value: "team-tickets"}, - {row: "tickets.auto.change_created", path: "tickets.auto.change_created", - block: "tickets:\n auto:\n change_created: true\n", - flow: "tickets: {auto: {change_created: true}}\n", value: true}, {row: "tickets.auto.spec_written", path: "tickets.auto.spec_written", block: "tickets:\n auto:\n spec_written: true\n", flow: "tickets: {auto: {spec_written: true}}\n", value: true}, @@ -367,6 +364,7 @@ func TestDecodeRejections(t *testing.T) { {"bad token pattern", "change_types: [Feat]\n", CodeInvalidValue, "change_types", SeverityError}, {"unknown tickets key", "tickets:\n provder: jira\n", CodeUnknownKey, "tickets.provder", SeverityError}, {"unknown tickets auto switch", "tickets:\n auto:\n pr_closed: true\n", CodeUnknownKey, "tickets.auto.pr_closed", SeverityError}, + {"retired tickets auto switch", "tickets:\n auto:\n change_created: true\n", CodeUnknownKey, "tickets.auto.change_created", SeverityError}, {"obsolete scalar auto_capture true", "auto_capture: true\n", CodeInvalidValue, "auto_capture", SeverityError}, {"obsolete scalar auto_capture false", "auto_capture: false\n", CodeInvalidValue, "auto_capture", SeverityError}, {"interior node as scalar", "finalize: local\n", CodeInvalidType, "finalize", SeverityError}, diff --git a/internal/config/defaults.go b/internal/config/defaults.go index 5b89a2f73..77b8d129a 100644 --- a/internal/config/defaults.go +++ b/internal/config/defaults.go @@ -63,7 +63,6 @@ func builtinEffective() Effective { Project: builtinValue(""), CompanionSkill: builtinValue(""), Auto: TicketsAuto{ - ChangeCreated: builtinValue(false), SpecWritten: builtinValue(false), PROpened: builtinValue(false), PRMerged: builtinValue(false), diff --git a/internal/config/defaults_test.go b/internal/config/defaults_test.go index 58441225a..60811a50f 100644 --- a/internal/config/defaults_test.go +++ b/internal/config/defaults_test.go @@ -180,7 +180,6 @@ func TestBuiltinEffectiveMatchesRegistryDefaults(t *testing.T) { "tickets.site": eff.Tickets.Site.Value, "tickets.project": eff.Tickets.Project.Value, "tickets.companion_skill": eff.Tickets.CompanionSkill.Value, - "tickets.auto.change_created": eff.Tickets.Auto.ChangeCreated.Value, "tickets.auto.spec_written": eff.Tickets.Auto.SpecWritten.Value, "tickets.auto.pr_opened": eff.Tickets.Auto.PROpened.Value, "tickets.auto.pr_merged": eff.Tickets.Auto.PRMerged.Value, diff --git a/internal/config/fixtures_test.go b/internal/config/fixtures_test.go index 1d802fa50..698abdf38 100644 --- a/internal/config/fixtures_test.go +++ b/internal/config/fixtures_test.go @@ -191,7 +191,6 @@ func TestFixtureSparseDefaults(t *testing.T) { {"tickets.site", eff.Tickets.Site.Explicit, eff.Tickets.Site.Provenance.Layer}, {"tickets.project", eff.Tickets.Project.Explicit, eff.Tickets.Project.Provenance.Layer}, {"tickets.companion_skill", eff.Tickets.CompanionSkill.Explicit, eff.Tickets.CompanionSkill.Provenance.Layer}, - {"tickets.auto.change_created", eff.Tickets.Auto.ChangeCreated.Explicit, eff.Tickets.Auto.ChangeCreated.Provenance.Layer}, {"tickets.auto.spec_written", eff.Tickets.Auto.SpecWritten.Explicit, eff.Tickets.Auto.SpecWritten.Provenance.Layer}, {"tickets.auto.pr_opened", eff.Tickets.Auto.PROpened.Explicit, eff.Tickets.Auto.PROpened.Provenance.Layer}, {"tickets.auto.pr_merged", eff.Tickets.Auto.PRMerged.Explicit, eff.Tickets.Auto.PRMerged.Provenance.Layer}, diff --git a/internal/config/resolve.go b/internal/config/resolve.go index f3bc2a272..d96504251 100644 --- a/internal/config/resolve.go +++ b/internal/config/resolve.go @@ -334,7 +334,6 @@ func (r *resolution) assemble(byLayer map[LayerKind]map[string]leafDecl) (Effect set(assign(&eff.Tickets.Site, r.declared, "tickets.site")) set(assign(&eff.Tickets.Project, r.declared, "tickets.project")) set(assign(&eff.Tickets.CompanionSkill, r.declared, "tickets.companion_skill")) - set(assign(&eff.Tickets.Auto.ChangeCreated, r.declared, "tickets.auto.change_created")) set(assign(&eff.Tickets.Auto.SpecWritten, r.declared, "tickets.auto.spec_written")) set(assign(&eff.Tickets.Auto.PROpened, r.declared, "tickets.auto.pr_opened")) set(assign(&eff.Tickets.Auto.PRMerged, r.declared, "tickets.auto.pr_merged")) diff --git a/internal/config/resolve_test.go b/internal/config/resolve_test.go index 59563acc7..4ffc85abe 100644 --- a/internal/config/resolve_test.go +++ b/internal/config/resolve_test.go @@ -111,8 +111,6 @@ func effectiveLeaf(t *testing.T, eff Effective, path string) (any, Provenance, b return eff.Tickets.Project.Value, eff.Tickets.Project.Provenance, eff.Tickets.Project.Explicit case "tickets.companion_skill": return eff.Tickets.CompanionSkill.Value, eff.Tickets.CompanionSkill.Provenance, eff.Tickets.CompanionSkill.Explicit - case "tickets.auto.change_created": - return eff.Tickets.Auto.ChangeCreated.Value, eff.Tickets.Auto.ChangeCreated.Provenance, eff.Tickets.Auto.ChangeCreated.Explicit case "tickets.auto.spec_written": return eff.Tickets.Auto.SpecWritten.Value, eff.Tickets.Auto.SpecWritten.Provenance, eff.Tickets.Auto.SpecWritten.Explicit case "tickets.auto.pr_opened": @@ -1529,8 +1527,8 @@ func TestTicketsKeysAnyLayer(t *testing.T) { seen[spec.path] = true } } - if len(rows) != 9 || !seen["tickets.provider"] || !seen["tickets.auto.results_completed"] { - t.Fatalf("tickets population = %v, want the nine ticket settings", seen) + if len(rows) != 8 || !seen["tickets.provider"] || !seen["tickets.auto.results_completed"] { + t.Fatalf("tickets population = %v, want the eight ticket settings", seen) } for _, spec := range rows { diff --git a/internal/config/schema.go b/internal/config/schema.go index ccd515bfd..79ac2853f 100644 --- a/internal/config/schema.go +++ b/internal/config/schema.go @@ -400,8 +400,6 @@ func buildRegistry() []pathSpec { {path: "tickets.companion_skill", kind: kindString, def: "", merge: mergeScalar, scope: scopeAny, disp: dispSupported, validate: singleLineStringLeaf()}, - {path: "tickets.auto.change_created", kind: kindBool, def: false, - merge: mergeScalar, scope: scopeAny, disp: dispSupported, validate: boolLeaf()}, {path: "tickets.auto.spec_written", kind: kindBool, def: false, merge: mergeScalar, scope: scopeAny, disp: dispSupported, validate: boolLeaf()}, {path: "tickets.auto.pr_opened", kind: kindBool, def: false, diff --git a/internal/config/schema_test.go b/internal/config/schema_test.go index 5428ec034..b9f0cc925 100644 --- a/internal/config/schema_test.go +++ b/internal/config/schema_test.go @@ -40,7 +40,7 @@ func TestRegistryPathSetMatchesV092(t *testing.T) { "github_project", "terminal_publish", "auto_groom", "change_types", "tickets.provider", "tickets.site", "tickets.project", "tickets.companion_skill", - "tickets.auto.change_created", "tickets.auto.spec_written", "tickets.auto.pr_opened", + "tickets.auto.spec_written", "tickets.auto.pr_opened", "tickets.auto.pr_merged", "tickets.auto.results_completed", "auto_capture.enabled", "auto_capture.types", "dummy_mode.enabled", "dummy_mode.persona", "dummy_mode.surfaces", @@ -147,7 +147,6 @@ func TestRegistryDefaults(t *testing.T) { "tickets.site": "", "tickets.project": "", "tickets.companion_skill": "", - "tickets.auto.change_created": false, "tickets.auto.spec_written": false, "tickets.auto.pr_opened": false, "tickets.auto.pr_merged": false, diff --git a/internal/config/setting_paths_test.go b/internal/config/setting_paths_test.go index 229e2ad3d..a4a340333 100644 --- a/internal/config/setting_paths_test.go +++ b/internal/config/setting_paths_test.go @@ -53,7 +53,7 @@ func TestSettingPathsSupportSplit(t *testing.T) { "board_surfaces", "board.section_order", "change_types", "agent_harnesses", "tickets.provider", "tickets.site", "tickets.project", "tickets.companion_skill", - "tickets.auto.change_created", "tickets.auto.spec_written", "tickets.auto.pr_opened", + "tickets.auto.spec_written", "tickets.auto.pr_opened", "tickets.auto.pr_merged", "tickets.auto.results_completed", "agents.*.*.model", "agents.*.*.effort", "agents.*.*.cache_ttl", } diff --git a/internal/repoguard/budgets_test.go b/internal/repoguard/budgets_test.go index 5dd1f419c..8a9ba430c 100644 --- a/internal/repoguard/budgets_test.go +++ b/internal/repoguard/budgets_test.go @@ -190,7 +190,7 @@ type skillBudget struct { // exact new counts. var skillBudgets = []skillBudget{ {"docket-adr/SKILL.md", 86, 1161}, // 0360: the producing change is passed through and adr.record appends the number to adrs:, so the caller only verifies it; the raise states that ownership (86/1143 -> 86/1161); 0531: the metadata worktree and remote come from the repository.prepare context (86/1129 -> 86/1143); 0502: one metadata layout — the docket branch and the .docket/ worktree (86/1123 -> 86/1129); 0502: the adr-unpublished health-check text is deleted (86/1148 -> 86/1123); 0502: the deferred-publication section and narration are deleted (110/1600 -> 86/1148) - {"docket-auto-groom/SKILL.md", 65, 1608}, // 0573: trivial retired; exits are spec or abstain (66/1695 -> 65/1608); 0560: a spec or trivial verdict needing a person's step is sent with hold: true; never hold: false (64/1638 -> 66/1695); 0532: the private-repository writing rule and visibility hand-off (64/1606 -> 64/1638); 0531: the metadata worktree and remote come from the repository.prepare context (64/1597 -> 64/1606); 0502: "loop" means /loop only (64/1596 -> 64/1597); 0502: one metadata layout — the docket branch and the .docket/ worktree (64/1595 -> 64/1596); 0502: the spec draft stays out of .docket/ (64/1572 -> 64/1595); 0502: auto-groom is per-change only (64/1582 -> 64/1572); 0502: the dummy-mode pointer is deleted (66/1625 -> 64/1582); 0382: typed change.groom abstain replaces the plain-git abstain commit prose (word ceiling 1750 -> 1627) + {"docket-auto-groom/SKILL.md", 69, 1678}, // 0587: the automatic ticket-update site (65/1608 -> 69/1678); 0573: trivial retired; exits are spec or abstain (66/1695 -> 65/1608); 0560: a spec or trivial verdict needing a person's step is sent with hold: true; never hold: false (64/1638 -> 66/1695); 0532: the private-repository writing rule and visibility hand-off (64/1606 -> 64/1638); 0531: the metadata worktree and remote come from the repository.prepare context (64/1597 -> 64/1606); 0502: "loop" means /loop only (64/1596 -> 64/1597); 0502: one metadata layout — the docket branch and the .docket/ worktree (64/1595 -> 64/1596); 0502: the spec draft stays out of .docket/ (64/1572 -> 64/1595); 0502: auto-groom is per-change only (64/1582 -> 64/1572); 0502: the dummy-mode pointer is deleted (66/1625 -> 64/1582); 0382: typed change.groom abstain replaces the plain-git abstain commit prose (word ceiling 1750 -> 1627) {"docket-brainstorm/SKILL.md", 83, 722}, // 0532: the private-repository writing rule and visibility hand-off (81/690 -> 83/722); 0502 review: the scope stop names new-change Steps 3–5 accurately (81/685 -> 81/690); 0502: the role runs on a human request, not a binding (80/671 -> 81/680); 0502: drop change citations and Go v1 narration (81/680 -> 81/679); 0502: description names the human request, no binding or change citation (81/679 -> 81/685) {"docket-build/SKILL.md", 386, 3878}, // 0532: the private-repository writing rule and visibility hand-off (384/3852 -> 386/3878); 0531: the metadata worktree and remote come from the repository.prepare context (384/3851 -> 384/3852); 0502: the install operation replaces install.sh; the wrapper skills list (385/3850 -> 385/3856); 0502: the observation-budget and build-checkpoint export reads are deleted (395/3942 -> 385/3850); 0502: fixed build role; undispatchable tier halts (398/3974 -> 395/3942); 0502: the gate-execution pointer paragraph is deleted with the reference (403/4007 -> 398/3974); 0493: the gate relaunch is retired (404/4023 -> 403/4007); 0491: the run id is retired (406/4037 -> 404/4023); 0488 review fix: +the dispatch payload names the branch (406/4034 -> 406/4037); 0488 review: build-owned starts carry --change-id/--run-context (404/4018 -> 406/4034); 0488: workers run tests directly; the dispatch payload carries no worker scope identity, the task-level WAITING/takeover section is gone, the controller runs every post-repair attempt, +time-limit audit (439/4479 -> 404/4018); 0467 review fix: +the repair dispatch payload carries the run id for the build-owned post-fix re-run (436/4443 -> 439/4479); 0467: +run-id threading on prepare-scope and the build-owned start; the bundle carries no run id (432/4391 -> 436/4443); 0459: +continuation carries the claimed verdict, closed-scope statement, and fresh prepare-scope bundle (424/4284 -> 432/4391); 0405: sequential-drive contract; 0420: shell-safe capture; 0421: budgeted repair cycle (see note above); 0502: drop change citations and Go v1 narration (385/3856 -> 384/3851) // 0154: docket-build/references/delegation-execution.md removed — it was the @@ -199,7 +199,7 @@ var skillBudgets = []skillBudget{ {"docket-build/references/gate-driver.md", 138, 1552}, // 0502 review: the raw-verb section names finalize's repaired-head re-gate (137/1546 -> 138/1552); 0502: "loop" means /loop only (137/1550 -> 137/1546); 0502: finalize's repaired-head re-gate is a direct caller (136/1523 -> 137/1550); 0502: the gate-execution intro reference is deleted (138/1555 -> 136/1523); 0502: renamed from gate-caller-loop.md; 0497: +halted-gate tree-survives finding relay (134/1510 -> 138/1555); 0491: the run id is retired (134/1513 -> 134/1510); 0490: the admission section describes the supervisor-held worktree lock; launch-unconfirmed is no longer a refusal (136/1511 -> 134/1513); 0488 review fix: finalize reaches the driver only through finalize.rebase; task-era handoff clauses dropped (word ceiling 1504 -> 1511); 0488 review: start row carries --change-id (word ceiling 1491 -> 1504); 0488: worker-scope/takeover/acknowledge rows and the parent-takeover section removed; callers are the full-suite gates (175/1872 -> 136/1491); 0467: +prepare-scope --run-id and scope-inherited start run id (word ceiling 1826 -> 1872); 0375: +worktree-admission section (word ceiling 1750 -> 1826) {"docket-build/references/task-routing.md", 50, 500}, {"docket-build-task/SKILL.md", 173, 1695}, // 0532: the private-repository writing rule and visibility hand-off (168/1640 -> 173/1695); 0531: the metadata worktree and remote come from the repository.prepare context (168/1637 -> 168/1640); 0488: scoped drive protocol replaced by direct foreground tests under timeout; three outcomes (211/2235 -> 168/1637); 0467 review fix: +the repair re-run run-id exception (206/2183 -> 211/2235); 0467: +the run id rides on the scope, never the bundle (204/2151 -> 206/2183); 0459: +post-handoff continuation never acknowledges or reuses the transferred scope (188/1964 -> 204/2151); 0405: sequential-drive receipt and acknowledgement; 0420: shell-safe capture; 0375: worktree-busy-not-a-retry rule (179/1842 -> 188/1964) - {"docket-convention/SKILL.md", 370, 7529}, // 0585: docket-update-ticket joins the inline skills (370/7528 -> 370/7529); 0584: docket-link-ticket joins the inline skills (370/7527 -> 370/7528); 0583: the three ticket manifest fields and the Ticket link paragraph (356/7352 -> 370/7527); 0582: acceptance criteria section and proposal order (353/7259 -> 356/7352); 0578: docket-export joins the inline skills (353/7257 -> 353/7259); 0575: reclaim and the claim lease are retired (361/7377 -> 353/7257); 0360: claimed_at is stamped by claim, reconcile, and resume-halted; a halt no longer claims a refreshed lease (361/7381 -> 361/7377); 0573: trivial retired (362/7411 -> 361/7381); 0560: the hold manifest field, its selection rule, the ## Why on hold section, and the auto-groomer's hold write (360/7331 -> 362/7411); 0565: a kill refuses on built stacked descendants; the killed-parent board text and exits table (360/7317 -> 360/7331); 0568: deferred is entered only from proposed (363/7317 -> 360/7317); 0559: the manifest lists deliverable; done means a merged PR or a completed results artifact; archive dates and change.complete (361/7276 -> 363/7317); 0533: editing visibility never moves a repository; repository.set-visibility does (361/7263 -> 361/7276); 0532: the private-repository writing rule and visibility hand-off (359/7160 -> 361/7263); 0531 review: skills say "the metadata branch", naming `docket` once for shared mode (359/7155 -> 359/7160); 0531: the metadata worktree and remote come from the repository.prepare context (357/7062 -> 359/7155); 0530: plan, results, and build evidence live on the docket branch — the plan-writer's one metadata operation, the attach operations as file-backlink writers, relative same-branch links, and the new ## Build evidence record section (357/7026 -> 357/7062); 0529 review: the backlink block names its PR-body writers beside artifact.backlink, one shared renderer (357/7004 -> 357/7026); 0515: the repair sign-off is retired; a green repair merges (357/7007 -> 357/7004); 0502 rebase onto 0510: kept the backlog-match follow-up clause in the results-artifact paragraph (357/7004 -> 357/7007); 0502 review: the review-tier dispatch is the controller's own (357/6995 -> 357/7004); 0502: configuration read paths corrected — operations read .docket.yml from origin's default-branch tip, the repository setup operations from the primary worktree (357/6959 -> 357/6995); 0502: "loop" means /loop only (357/7036 -> 357/7037); 0502: one metadata layout — the docket branch and the .docket/ worktree (357/7035 -> 357/7036); 0502: agent layer names user-level wrappers and global-only pins (357/7024 -> 357/7035); 0502: typed operations replace the Bash-era script names; ## Run halted facts corrected (359/7092 -> 357/7024); 0502: terminal publish, the learnings cap, and the repository auto_groom default are deleted (362/7256 -> 359/7092); 0502: the auto-capture export paragraph is deleted (370/7334 -> 362/7256); 0502: the configuration contract rewritten from the schema (371/7488 -> 370/7334); 0502: fixed role skills; halt posture (372/7660 -> 371/7488); 0502: record blocks mirror the renderers (367/7619 -> 372/7660); 0502: the dummy-mode shared definition is deleted (390/7848 -> 367/7619); 0410: +required-results lifecycle prose; 0399: +schema request/result contract prose; 0388: +sync-integration prose (see note above); 0502: drop change citations and Go v1 narration (357/7037 -> 357/6958); 0502: the harness adapter is named without a docket source path (357/6958 -> 357/6959) + {"docket-convention/SKILL.md", 380, 7767}, // 0587: the Automatic ticket updates shared definition (370/7529 -> 380/7767); 0585: docket-update-ticket joins the inline skills (370/7528 -> 370/7529); 0584: docket-link-ticket joins the inline skills (370/7527 -> 370/7528); 0583: the three ticket manifest fields and the Ticket link paragraph (356/7352 -> 370/7527); 0582: acceptance criteria section and proposal order (353/7259 -> 356/7352); 0578: docket-export joins the inline skills (353/7257 -> 353/7259); 0575: reclaim and the claim lease are retired (361/7377 -> 353/7257); 0360: claimed_at is stamped by claim, reconcile, and resume-halted; a halt no longer claims a refreshed lease (361/7381 -> 361/7377); 0573: trivial retired (362/7411 -> 361/7381); 0560: the hold manifest field, its selection rule, the ## Why on hold section, and the auto-groomer's hold write (360/7331 -> 362/7411); 0565: a kill refuses on built stacked descendants; the killed-parent board text and exits table (360/7317 -> 360/7331); 0568: deferred is entered only from proposed (363/7317 -> 360/7317); 0559: the manifest lists deliverable; done means a merged PR or a completed results artifact; archive dates and change.complete (361/7276 -> 363/7317); 0533: editing visibility never moves a repository; repository.set-visibility does (361/7263 -> 361/7276); 0532: the private-repository writing rule and visibility hand-off (359/7160 -> 361/7263); 0531 review: skills say "the metadata branch", naming `docket` once for shared mode (359/7155 -> 359/7160); 0531: the metadata worktree and remote come from the repository.prepare context (357/7062 -> 359/7155); 0530: plan, results, and build evidence live on the docket branch — the plan-writer's one metadata operation, the attach operations as file-backlink writers, relative same-branch links, and the new ## Build evidence record section (357/7026 -> 357/7062); 0529 review: the backlink block names its PR-body writers beside artifact.backlink, one shared renderer (357/7004 -> 357/7026); 0515: the repair sign-off is retired; a green repair merges (357/7007 -> 357/7004); 0502 rebase onto 0510: kept the backlog-match follow-up clause in the results-artifact paragraph (357/7004 -> 357/7007); 0502 review: the review-tier dispatch is the controller's own (357/6995 -> 357/7004); 0502: configuration read paths corrected — operations read .docket.yml from origin's default-branch tip, the repository setup operations from the primary worktree (357/6959 -> 357/6995); 0502: "loop" means /loop only (357/7036 -> 357/7037); 0502: one metadata layout — the docket branch and the .docket/ worktree (357/7035 -> 357/7036); 0502: agent layer names user-level wrappers and global-only pins (357/7024 -> 357/7035); 0502: typed operations replace the Bash-era script names; ## Run halted facts corrected (359/7092 -> 357/7024); 0502: terminal publish, the learnings cap, and the repository auto_groom default are deleted (362/7256 -> 359/7092); 0502: the auto-capture export paragraph is deleted (370/7334 -> 362/7256); 0502: the configuration contract rewritten from the schema (371/7488 -> 370/7334); 0502: fixed role skills; halt posture (372/7660 -> 371/7488); 0502: record blocks mirror the renderers (367/7619 -> 372/7660); 0502: the dummy-mode shared definition is deleted (390/7848 -> 367/7619); 0410: +required-results lifecycle prose; 0399: +schema request/result contract prose; 0388: +sync-integration prose (see note above); 0502: drop change citations and Go v1 narration (357/7037 -> 357/6958); 0502: the harness adapter is named without a docket source path (357/6958 -> 357/6959) // 0154: docket-convention/github-board-mirror.md removed — the GitHub mirror is // retired (unsupported, mutation-blocking); its budget row is deleted with it. {"docket-convention/references/agent-layer.md", 214, 1993}, // 0585: docket-update-ticket joins the inline skills (214/1992 -> 214/1993); 0584: docket-link-ticket joins the inline skills (214/1991 -> 214/1992); 0578: docket-export joins the inline skills (214/1989 -> 214/1991); 0552: the user-level settings.json also carries the finalize allow rules (212/1951 -> 214/1990); 0546: the per-agent cache_ttl pin, its shipped 1h default, and the machine-wide controls docket leaves unset (168/1593 -> 212/1951); 0538: init and repository.configure-harnesses set agent_harnesses; repository.check reports harnesses-unset (164/1553 -> 168/1593); 0535: a private repository's instructions file and its user-level triggers (148/1419 -> 164/1553); 0502: rewritten around user-level wrappers and global-only pins (202/2346 -> 148/1419); 0502: the legacy agents-file migration clause is deleted (202/2349 -> 202/2346) @@ -207,13 +207,13 @@ var skillBudgets = []skillBudget{ {"docket-convention/references/learnings.md", 69, 487}, // 0535: promotion lands in the private instructions file in a private repository (66/457 -> 69/487); 0502: one metadata layout — the docket branch and the .docket/ worktree (66/455 -> 66/457); 0502: learning.record/learning.update are the writers; the capacity section is deleted (84/580 -> 66/455) {"docket-convention/references/stacked-changes.md", 227, 2290}, // 0571: a root carries exactly the children merged into it, stacked-merged or implemented; any other child never blocks it (223/2217 -> 227/2290); 0567: carried children are cleaned right after the root once their work is proven (219/2173 -> 223/2217); 0565: a kill refuses on built stacked descendants; the killed-parent board text and exits table (214/2149 -> 219/2173); 0502: typed operations and binary-emitted findings replace the Bash-era names (213/2125 -> 214/2149); 0502: the deferred descendant-publication sentence is deleted (215/2140 -> 213/2125); 0327: +carry-preservation contract prose (see note above) {"docket-export/SKILL.md", 62, 1146}, // 0585: update and comment requests route to docket-update-ticket (62/1133 -> 62/1146); 0584: ticket work moves to docket-link-ticket (60/1116 -> 62/1133); 0578 review: export fallbacks for a missing prepare context, stray-marker leftovers, and a non-git directory (60/1063 -> 60/1116); 0578 review: the private ADR/change-number rewrite runs on every private export (59/1038 -> 60/1063); 0578: new — the inline export skill - {"docket-finalize-change/SKILL.md", 242, 6269}, // 0571: the children-retarget-required closeout bullet is deleted; root-archived names who is carried (243/6254 -> 242/6269); 0567: step 10 cleans each carried_ids child after the root (243/6191 -> 243/6254); 0551: step 1 checks the change out into its own workspace first (241/6033 -> 243/6191); 0532 review: both finalize gate dispatches carry the Visibility payload line (239/6020 -> 241/6033); 0532: the private-repository writing rule and visibility hand-off (239/6000 -> 239/6020); 0529 review: the PR-backlink repoint is a best-effort follow-up after the archive push, for root-archived descendants too (239/5984 -> 239/6000); 0529: close-out repoints the merged PR description's backlink; pr-backlink-pending is a retryable warning (239/5936 -> 239/5984); 0525 review: workspace-remnant rides any finished-workspace disposition and is named in the final report; branch-rules-unavailable comes only from the probing run (239/5910 -> 239/5936); 0525: plan-gated merges carry branch-rules-unavailable into closeout notes; cleanup reports workspace-remnant and names what blocked a workspace (239/5820 -> 239/5910); 0515 review: the refused-notes fallback names every dropped note in the final report (238/5809 -> 239/5820); 0515 review: a repair whose run halts before closeout is named in finalize.block and carried into a later closeout (238/5708 -> 238/5809); 0515: the repair sign-off is retired; a green repair merges (238/5808 -> 238/5708); 0517: the repaired-head evidence.record carries --owner finalize and records finalize.test_command (238/5790 -> 238/5808); 0502 review: clear-block re-reads the revision after the block lands (238/5771 -> 238/5790); 0502: repair sign-off records finalize.block before publishing the repaired head (238/5733 -> 238/5771); 0502: "loop" means /loop only (238/5729 -> 238/5733); 0502: repair sign-off is the human running finalize.clear-block (238/5666 -> 238/5729); 0502: the repaired head is re-gated through the gate driver (236/5568 -> 238/5666); 0502: the dummy-mode paragraph is deleted (238/5641 -> 236/5568); 0455: +record-invalid refusal (structural scope, findings remedy, merged-outside-docket precedence) in step 8 (word ceiling 5520 -> 5647); 0442: +post-publication base-advance guidance (word ceiling 5421 -> 5520); de-duplicated the shared forward-rebase mechanic against the 0438 unpublished-case paragraph (reclaimed 57 words), but the distinct published-refresh facts plus the retained 0438 guidance cannot fit the old ceiling without deleting required guidance; 0411: +reconciliation-write recovery exception paragraph in the resolver loop (ceilings 238/5232 -> 239/5421); 0413: +generated-bundle mixed-conflict handoff sentence in the resolver-loop block (word ceiling 5200 -> 5232); 0419: +repair-attempt budget payload line and rewired repair contract (line ceiling 236 -> 238); 0393: +exact payload, marker, and direct-dispatch lines atop 0349/0410 (see note above) + {"docket-finalize-change/SKILL.md", 244, 6373}, // 0587: the automatic ticket-update site (242/6269 -> 244/6373); 0571: the children-retarget-required closeout bullet is deleted; root-archived names who is carried (243/6254 -> 242/6269); 0567: step 10 cleans each carried_ids child after the root (243/6191 -> 243/6254); 0551: step 1 checks the change out into its own workspace first (241/6033 -> 243/6191); 0532 review: both finalize gate dispatches carry the Visibility payload line (239/6020 -> 241/6033); 0532: the private-repository writing rule and visibility hand-off (239/6000 -> 239/6020); 0529 review: the PR-backlink repoint is a best-effort follow-up after the archive push, for root-archived descendants too (239/5984 -> 239/6000); 0529: close-out repoints the merged PR description's backlink; pr-backlink-pending is a retryable warning (239/5936 -> 239/5984); 0525 review: workspace-remnant rides any finished-workspace disposition and is named in the final report; branch-rules-unavailable comes only from the probing run (239/5910 -> 239/5936); 0525: plan-gated merges carry branch-rules-unavailable into closeout notes; cleanup reports workspace-remnant and names what blocked a workspace (239/5820 -> 239/5910); 0515 review: the refused-notes fallback names every dropped note in the final report (238/5809 -> 239/5820); 0515 review: a repair whose run halts before closeout is named in finalize.block and carried into a later closeout (238/5708 -> 238/5809); 0515: the repair sign-off is retired; a green repair merges (238/5808 -> 238/5708); 0517: the repaired-head evidence.record carries --owner finalize and records finalize.test_command (238/5790 -> 238/5808); 0502 review: clear-block re-reads the revision after the block lands (238/5771 -> 238/5790); 0502: repair sign-off records finalize.block before publishing the repaired head (238/5733 -> 238/5771); 0502: "loop" means /loop only (238/5729 -> 238/5733); 0502: repair sign-off is the human running finalize.clear-block (238/5666 -> 238/5729); 0502: the repaired head is re-gated through the gate driver (236/5568 -> 238/5666); 0502: the dummy-mode paragraph is deleted (238/5641 -> 236/5568); 0455: +record-invalid refusal (structural scope, findings remedy, merged-outside-docket precedence) in step 8 (word ceiling 5520 -> 5647); 0442: +post-publication base-advance guidance (word ceiling 5421 -> 5520); de-duplicated the shared forward-rebase mechanic against the 0438 unpublished-case paragraph (reclaimed 57 words), but the distinct published-refresh facts plus the retained 0438 guidance cannot fit the old ceiling without deleting required guidance; 0411: +reconciliation-write recovery exception paragraph in the resolver loop (ceilings 238/5232 -> 239/5421); 0413: +generated-bundle mixed-conflict handoff sentence in the resolver-loop block (word ceiling 5200 -> 5232); 0419: +repair-attempt budget payload line and rewired repair contract (line ceiling 236 -> 238); 0393: +exact payload, marker, and direct-dispatch lines atop 0349/0410 (see note above) {"docket-finalize-change/references/gate-failure.md", 162, 2107}, // 0571: the children-retarget-required closeout halt is deleted (162/2111 -> 162/2107); 0532 review: the gate-agent payload names Visibility (161/2109 -> 162/2111); 0515 review: the refused-notes fallback names every dropped note in the final report (160/2098 -> 161/2109); 0515 review: a repair whose run halts before closeout is named in finalize.block and carried into a later closeout (153/2005 -> 160/2098); 0515: the repair sign-off is retired; a green repair merges (160/2086 -> 153/2005); 0517: the repaired-head evidence.record carries --owner finalize (159/2081 -> 160/2086); 0502 review: clear-block re-reads the revision after the block lands (157/2062 -> 159/2081); 0502: repair sign-off records finalize.block before publishing the repaired head (155/2028 -> 157/2062); 0502: the embedded-bundle rule is conditioned on docket's own repository (155/2024 -> 155/2028); 0502: "loop" means /loop only (155/2027 -> 155/2024); 0502: repair sign-off is the human running finalize.clear-block; the marker lifecycle names what removes it (154/2013 -> 155/2027); 0502: the repaired head is re-gated through the gate driver (148/1937 -> 154/2013); 0497: +wait-for-the-leftover-group sentence (146/1901 -> 148/1937); 0493: the gate relaunch is retired (145/1892 -> 146/1901); 0491: the run id is retired (145/1894 -> 145/1892); 0490: the shared-slot note became the shared worktree-lock note (147/1901 -> 145/1894); 0411: +reconciliation-write exception section and abort-set carve-out (ceilings 135/1472 -> 147/1901); 0413: +conflicted_paths-lists-authored-only rule in the resolver-report section (line ceiling 133 -> 135, word ceiling 1465 -> 1472); 0419: +repair-attempt budget payload and rewired repair contract prose (word ceiling 1450 -> 1465); 0349: +reserve-before-dispatch resolver protocol prose; 0375: +worktree-slot note for the scopeless finalize gate (120/1300 -> 133/1450) - {"docket-groom-next/SKILL.md", 77, 2310}, // 0573: trivial retired; the brainstorm is told the artifact is always a spec (78/2377 -> 77/2310); 0560 review: a revise that sets or lifts a hold changes the row's readiness (78/2370 -> 78/2377); 0560: the Step-4 hold paragraph (76/2282 -> 78/2370); 0559: the Step-4 deliverable, type, and branch_prefix paragraph (78/2215 -> 76/2282); 0550: the Step-4 reprioritize paragraph and the stub-edit priority route (76/2141 -> 78/2215); 0532: the private-repository writing rule and visibility hand-off (76/2109 -> 76/2141); 0531: the metadata worktree and remote come from the repository.prepare context (76/2102 -> 76/2109); 0502 rebase onto 0509: carried the edit-a-stub revise route and groom-exit-scoped STOPs (76/2012 -> 76/2102); 0502: "loop" means /loop only (76/2011 -> 76/2012); 0502: one metadata layout — the docket branch and the .docket/ worktree (76/2010 -> 76/2011); 0502: selection bands key on auto_groomable itself (76/2009 -> 76/2010); 0502: invoke superpowers:brainstorming by name (76/2037 -> 76/2009); 0502: the dummy-mode pointer is deleted (78/2080 -> 76/2037); 0461: +Step-4 retitle paragraph (title on change.groom; lines 77 -> 78, words 1996 -> 2081); +not-retitleable refusal code (2081 -> 2082); 0382: +typed rearm exit (word ceiling 1889 -> 1996); 0445: +revise route for already-groomed explicit ids (Step 1) and the fifth Step-4 exit (word ceiling 1650 -> 1813); +spec_version pin for a spec-body revise (1813 -> 1849); +revise spec_markdown excludes the backlink block (1849 -> 1850); +revise in the description and the revise contended/board clauses (1850 -> 1889) - {"docket-implement-next/SKILL.md", 226, 8813}, // 0583: the PR-body Ticket line replaces the issue reference (226/8806 -> 226/8813); 0575: reclaim and the claim lease are retired (226/8841 -> 226/8806); review: Step 7 names the Step 6 evidence file instead of verified bytes (226/8835 -> 226/8841); 0360 step wording: the PR-body rules moved in from edge-paths.md (which fell 222 words) plus the minimal reconcile request, evidence block file, and ADR producing-change pass-through; the raise is that moved text, compressed (220/8590 -> 226/8835); 0360: local revision lookups, no claim refreshes, fewer re-syncs; the line raise is the new standalone Revision lookups paragraph every post-claim write keys on, words fell (218/8612 -> 220/8590); 0573: trivial retired (218/8637 -> 218/8612); 0570: the --selection claim sentence and the run-next driver rule (218/8555 -> 218/8637); 0560 review: on the named path on-hold also qualifies at the Step-1 confirm (218/8548 -> 218/8555); 0560: on-hold joins the readiness vocabulary and skip reasons; a held change is built when named (218/8518 -> 218/8548); 0559: the results-artifact ending pointer, postcondition row, and advanced meaning (215/8411 -> 218/8518); 0532: the private-repository writing rule and visibility hand-off (212/8282 -> 215/8411); 0531: the metadata worktree and remote come from the repository.prepare context (216/8443 -> 212/8282); 0517: evidence.record reads the gate command from build configuration (216/8438 -> 216/8443); 0502 rebase onto 0510: carried the Step 6.5 Backlog match paragraph and verdict pointers (214/8039 -> 216/8438); 0502 review: the controller dispatches the review tier wrapper; the skill dispatches nothing (214/8023 -> 214/8039); 0502: "loop" means /loop only (214/8058 -> 214/8057); 0502: one metadata layout — the docket branch and the .docket/ worktree (214/8042 -> 214/8058); 0502: the review payload names the resolved build.gate value; build_gate spellings become build.gate (214/8020 -> 214/8042); 0502: change.reclaim replaces reclaim-claims; the claim removes a leftover ## Run halted (214/8009 -> 214/8020); 0502: terminal-publication narration is deleted (214/8037 -> 214/8009); 0502: the severity floor is read as review.min_fix_severity through diagnostic.config (214/8034 -> 214/8037); 0502: the fixed role skills replace the $SKILL_* sites (214/8257 -> 214/8034); 0502: the dummy-mode paragraph and PR-body clause are deleted (216/8356 -> 214/8257); 0497: +Step 5 halted-build evidence kept verbatim in ## Run halted (216/8325 -> 216/8356); 0498 review: checkpoint (ii) persist wording (8320 -> 8325); 0498: +Step 6.5 review-findings homes, condensation exception, Human-actions class rule (214/8161 -> 216/8320); 0491: the run id is retired (214/8183 -> 214/8161); 0488 review: build-owned starts carry --change-id/--run-context (word ceiling 8162 -> 8183); 0488: run context and run id name only build-owned starts (word ceiling 8175 -> 8162); 0467 review fix: +the repair worker's post-fix re-run is a build-owned start (word ceiling 8165 -> 8175); 0467: +run id threaded to prepare-scope and build-owned starts (word ceiling 8080 -> 8165); 0455: +pr.publish record-invalid refusal clause (word ceiling 8025 -> 8080); 0448: +named-invocation branch; bounded own-dependency closeout moved to edge-paths.md (ceilings 210/7716 -> 214/8270 -> 214/8025); 0393: +exact payload, marker, and direct-dispatch lines atop 0410/0354/0376; 0375: +run-tracker resume pointer (word ceiling 7530 -> 7547); 0440: reader-first results prose; 0502: drop change citations and Go v1 narration (214/8057 -> 214/8023) + {"docket-groom-next/SKILL.md", 81, 2391}, // 0587: the automatic ticket-update site (77/2310 -> 81/2391); 0573: trivial retired; the brainstorm is told the artifact is always a spec (78/2377 -> 77/2310); 0560 review: a revise that sets or lifts a hold changes the row's readiness (78/2370 -> 78/2377); 0560: the Step-4 hold paragraph (76/2282 -> 78/2370); 0559: the Step-4 deliverable, type, and branch_prefix paragraph (78/2215 -> 76/2282); 0550: the Step-4 reprioritize paragraph and the stub-edit priority route (76/2141 -> 78/2215); 0532: the private-repository writing rule and visibility hand-off (76/2109 -> 76/2141); 0531: the metadata worktree and remote come from the repository.prepare context (76/2102 -> 76/2109); 0502 rebase onto 0509: carried the edit-a-stub revise route and groom-exit-scoped STOPs (76/2012 -> 76/2102); 0502: "loop" means /loop only (76/2011 -> 76/2012); 0502: one metadata layout — the docket branch and the .docket/ worktree (76/2010 -> 76/2011); 0502: selection bands key on auto_groomable itself (76/2009 -> 76/2010); 0502: invoke superpowers:brainstorming by name (76/2037 -> 76/2009); 0502: the dummy-mode pointer is deleted (78/2080 -> 76/2037); 0461: +Step-4 retitle paragraph (title on change.groom; lines 77 -> 78, words 1996 -> 2081); +not-retitleable refusal code (2081 -> 2082); 0382: +typed rearm exit (word ceiling 1889 -> 1996); 0445: +revise route for already-groomed explicit ids (Step 1) and the fifth Step-4 exit (word ceiling 1650 -> 1813); +spec_version pin for a spec-body revise (1813 -> 1849); +revise spec_markdown excludes the backlink block (1849 -> 1850); +revise in the description and the revise contended/board clauses (1850 -> 1889) + {"docket-implement-next/SKILL.md", 228, 8892}, // 0587: the automatic ticket-update site (226/8813 -> 228/8892); 0583: the PR-body Ticket line replaces the issue reference (226/8806 -> 226/8813); 0575: reclaim and the claim lease are retired (226/8841 -> 226/8806); review: Step 7 names the Step 6 evidence file instead of verified bytes (226/8835 -> 226/8841); 0360 step wording: the PR-body rules moved in from edge-paths.md (which fell 222 words) plus the minimal reconcile request, evidence block file, and ADR producing-change pass-through; the raise is that moved text, compressed (220/8590 -> 226/8835); 0360: local revision lookups, no claim refreshes, fewer re-syncs; the line raise is the new standalone Revision lookups paragraph every post-claim write keys on, words fell (218/8612 -> 220/8590); 0573: trivial retired (218/8637 -> 218/8612); 0570: the --selection claim sentence and the run-next driver rule (218/8555 -> 218/8637); 0560 review: on the named path on-hold also qualifies at the Step-1 confirm (218/8548 -> 218/8555); 0560: on-hold joins the readiness vocabulary and skip reasons; a held change is built when named (218/8518 -> 218/8548); 0559: the results-artifact ending pointer, postcondition row, and advanced meaning (215/8411 -> 218/8518); 0532: the private-repository writing rule and visibility hand-off (212/8282 -> 215/8411); 0531: the metadata worktree and remote come from the repository.prepare context (216/8443 -> 212/8282); 0517: evidence.record reads the gate command from build configuration (216/8438 -> 216/8443); 0502 rebase onto 0510: carried the Step 6.5 Backlog match paragraph and verdict pointers (214/8039 -> 216/8438); 0502 review: the controller dispatches the review tier wrapper; the skill dispatches nothing (214/8023 -> 214/8039); 0502: "loop" means /loop only (214/8058 -> 214/8057); 0502: one metadata layout — the docket branch and the .docket/ worktree (214/8042 -> 214/8058); 0502: the review payload names the resolved build.gate value; build_gate spellings become build.gate (214/8020 -> 214/8042); 0502: change.reclaim replaces reclaim-claims; the claim removes a leftover ## Run halted (214/8009 -> 214/8020); 0502: terminal-publication narration is deleted (214/8037 -> 214/8009); 0502: the severity floor is read as review.min_fix_severity through diagnostic.config (214/8034 -> 214/8037); 0502: the fixed role skills replace the $SKILL_* sites (214/8257 -> 214/8034); 0502: the dummy-mode paragraph and PR-body clause are deleted (216/8356 -> 214/8257); 0497: +Step 5 halted-build evidence kept verbatim in ## Run halted (216/8325 -> 216/8356); 0498 review: checkpoint (ii) persist wording (8320 -> 8325); 0498: +Step 6.5 review-findings homes, condensation exception, Human-actions class rule (214/8161 -> 216/8320); 0491: the run id is retired (214/8183 -> 214/8161); 0488 review: build-owned starts carry --change-id/--run-context (word ceiling 8162 -> 8183); 0488: run context and run id name only build-owned starts (word ceiling 8175 -> 8162); 0467 review fix: +the repair worker's post-fix re-run is a build-owned start (word ceiling 8165 -> 8175); 0467: +run id threaded to prepare-scope and build-owned starts (word ceiling 8080 -> 8165); 0455: +pr.publish record-invalid refusal clause (word ceiling 8025 -> 8080); 0448: +named-invocation branch; bounded own-dependency closeout moved to edge-paths.md (ceilings 210/7716 -> 214/8270 -> 214/8025); 0393: +exact payload, marker, and direct-dispatch lines atop 0410/0354/0376; 0375: +run-tracker resume pointer (word ceiling 7530 -> 7547); 0440: reader-first results prose; 0502: drop change citations and Go v1 narration (214/8057 -> 214/8023) {"docket-implement-next/references/edge-paths.md", 99, 1044}, // 0575: reclaim and the claim lease are retired (99/1051 -> 99/1044); 0360: the PR-body assembly section moved into SKILL.md Step 7 (109/1273 -> 99/1051); 0360: the resume results load needs no extra re-sync (109/1276 -> 109/1273); 0571: the stack-base refusal names its true reason (109/1265 -> 109/1276); 0532: the private-repository writing rule and visibility hand-off (109/1226 -> 109/1265); 0531: the metadata worktree and remote come from the repository.prepare context (118/1499 -> 109/1226); 0502: one metadata layout — the docket branch and the .docket/ worktree (118/1507 -> 118/1509); 0502: run.verify replaces verify-run (118/1505 -> 118/1507); 0502: terminal-publication narration is deleted (118/1513 -> 118/1505); 0502: the deferred results-only permit clause is deleted (118/1546 -> 118/1513); 0502: no custom plan location (118/1547 -> 118/1546); 0491: the run id is retired (118/1554 -> 118/1547); 0410: +resume/recovery + required-results reconciliation; 0375: +run-tracker resume refusals (78/1091 -> 93/1261); 0448: +named own-dependency closeout moved from SKILL.md (93/1261 -> 118/1554); 0502: drop change citations and Go v1 narration (118/1509 -> 118/1499) {"docket-implement-next/references/fix-pass.md", 189, 1954}, // 0360: halts no longer claim a refreshed lease (189/1963 -> 189/1954); 0532: the private-repository writing rule and visibility hand-off (187/1943 -> 189/1963); 0502 rebase onto 0510: carried the backlog-verdict pointer for reported findings (186/1929 -> 187/1943); 0502: "loop" means /loop only (190/1962 -> 190/1967); 0502: undispatchable fix worker halts (192/1991 -> 190/1962); 0502: renamed from fix-loop.md; 0498 review: results-file antecedent (1989 -> 1991); 0498: +review-findings condensation at final consolidation (190/1958 -> 192/1989); 0410: +findings-to-results checkpoint linkage (see note above); 0502: drop change citations and Go v1 narration (190/1967 -> 186/1929) - {"docket-implement-next/references/results-artifact.md", 76, 737}, // 0360: no claim refreshes; change.complete pins a locally looked-up revision (79/765 -> 76/737); 0573: trivial retired (79/775 -> 79/765); 0559: new — the results-artifact ending (no plan, build, or PR; review, complete, clean up) + {"docket-implement-next/references/results-artifact.md", 83, 806}, // 0587: the automatic ticket-update site (76/737 -> 83/806); 0360: no claim refreshes; change.complete pins a locally looked-up revision (79/765 -> 76/737); 0573: trivial retired (79/775 -> 79/765); 0559: new — the results-artifact ending (no plan, build, or PR; review, complete, clean up) {"docket-implement-next/results-template.md", 70, 543}, // 0573: trivial retired (70/545 -> 70/543); 0502 rebase onto 0510: carried the backlog verdict and next action in the Known issues placeholder (68/506 -> 70/545); 0502: inline review replaces the custom review skill (68/511 -> 68/510); 0498: +whole-branch review summary line in Verification performed (64/446 -> 68/511); 0440: reader-first template — action statement + merged Known issues (see note above); 0502: drop change citations and Go v1 narration (68/510 -> 68/506) {"docket-link-ticket/SKILL.md", 39, 819}, // 0585: update and comment requests route to docket-update-ticket (39/816 -> 39/819); 0584 review: an id-only link takes the provider from tickets.provider and the URL from the connector (39/788 -> 39/816); 0584: new — the inline ticket-linking skill {"docket-link-ticket/references/create.md", 42, 1348}, // 0591: the companion-skill step, its draft and create fields, and the never-rewritten rule removed (35/853 -> 42/1348); 0584 review: the open argv is resolved from the capability catalog (35/843 -> 35/853); 0584: new — the push path @@ -221,7 +221,8 @@ var skillBudgets = []skillBudget{ {"docket-review/SKILL.md", 127, 1054}, // 0573: trivial retired (127/1059 -> 127/1054); 0559: the results-artifact mode (114/966 -> 127/1049); 0559: Inputs and evidence sections defer to results-artifact mode (127/1049 -> 127/1059); 0531: the metadata worktree and remote come from the repository.prepare context (114/965 -> 114/966); 0502: the evidence rule keys on the payload's build.gate value; gate-off skipped records are expected (110/913 -> 114/965); 0410: +findings-return capture contract (see note above) {"docket-new-change/SKILL.md", 48, 1552}, // 0582: optional acceptance_criteria body (48/1538 -> 48/1552); 0573: trivial retired; the trivial path is deleted and the brainstorm is told the artifact is always a spec (53/1636 -> 48/1538); 0560: suggest a hold; it rides change.create or change.groom (53/1598 -> 53/1636); 0559: the create request carries deliverable: results-artifact for findings-only work (57/1635 -> 53/1598); 0532: the private-repository writing rule and visibility hand-off (57/1603 -> 57/1635); 0531: the metadata worktree and remote come from the repository.prepare context (57/1596 -> 57/1603); 0502 review: omitted draft-time scalars are described exactly (57/1591 -> 57/1596); 0502: "loop" means /loop only (57/1593 -> 57/1591); 0502: one metadata layout — the docket branch and the .docket/ worktree (57/1590 -> 57/1593); 0502: terminal-publication narration and the repository auto_groom default are deleted (57/1609 -> 57/1590); 0502: invoke superpowers:brainstorming by name (57/1636 -> 57/1609); 0502: the dummy-mode pointer is deleted (59/1674 -> 57/1636); 0445: +pointer to the docket-groom-next revise path after landing (word ceiling 1700 -> 1706); 0382: draft-time scalars moved into change.create (ceiling 1706 -> 1675) {"docket-status/SKILL.md", 125, 2956}, // 0575: reclaim and the claim lease are retired, the intentional-skip example names snapshot-retained and snapshot-no-work (126/2990 -> 125/2956); 0573: trivial retired (126/2993 -> 126/2990); 0560: a held change shows on hold (126/2983 -> 126/2993); 0539: derived-view drift is named by family and each finding's own remedy is relayed instead of a code list (126/2923 -> 126/2983); 0531: the metadata worktree and remote come from the repository.prepare context (126/2921 -> 126/2923); 0530: artifact-missing names where a plan or results file may live — the docket branch, or the integration branch for a record closed before the move (126/2904 -> 126/2921); 0529 review: full-scope cleanup retries also repoint stale merged-PR description backlinks; repair --pr-backlinks previews them (126/2880 -> 126/2904); 0502: one metadata layout — the docket branch and the .docket/ worktree (126/2876 -> 126/2880); 0502: findings named as the binary emits them (126/2852 -> 126/2876); 0502: deferred learnings and publication narration is deleted (127/2956 -> 126/2852); 0502: the dummy-mode pointer is deleted (129/2985 -> 127/2956); 0388: +sync-integration prose (see note above) - {"docket-update-ticket/SKILL.md", 101, 1579}, // 0586 review: a private repository keeps the single stop on a rewrite (101/1567 -> 101/1579); 0586: the private refusal becomes a blocking route to references/private.md; the convention paragraph names the docket-export call; the last table column covers attachments (98/1521 -> 101/1567); 0585 review: reads pinned to metadata_commit from the metadata worktree, status named as the ticket-only read, and an empty destination_branch names the parent change (98/1465 -> 98/1521); 0585 review: the lead example names a mention placeholder, never a typed @-mention (98/1451 -> 98/1465); 0585 review: a killed change reports the killed reason (98/1431 -> 98/1451); 0585: new — the inline ticket-update skill + {"docket-update-ticket/SKILL.md", 103, 1660}, // 0587 review: the description covers workflow invocation (103/1645 -> 103/1660); 0587 review: a workflow-invoked run skips its own startup check (103/1627 -> 103/1645); 0587: the opening covers workflow invocation; the automatic path routes to references/automatic.md (101/1579 -> 103/1627); 0586 review: a private repository keeps the single stop on a rewrite (101/1567 -> 101/1579); 0586: the private refusal becomes a blocking route to references/private.md; the convention paragraph names the docket-export call; the last table column covers attachments (98/1521 -> 101/1567); 0585 review: reads pinned to metadata_commit from the metadata worktree, status named as the ticket-only read, and an empty destination_branch names the parent change (98/1465 -> 98/1521); 0585 review: the lead example names a mention placeholder, never a typed @-mention (98/1451 -> 98/1465); 0585 review: a killed change reports the killed reason (98/1431 -> 98/1451); 0585: new — the inline ticket-update skill + {"docket-update-ticket/references/automatic.md", 14, 386}, // 0587 review: no startup check of its own; a refused or error read reports one line and returns (13/334 -> 14/386); 0587 review: the switch-off rule comes first (12/312 -> 13/334); 0587: new — the automatic path {"docket-update-ticket/references/private.md", 12, 665}, // 0586 review: the comment rule bans docket ADR numbers only (12/664 -> 12/665); 0586 review: uploads happen at the post step after mentions (12/629 -> 12/664); 0586: new — private delivery {"docket-update-ticket/references/shared.md", 9, 184}, // 0585: new — shared delivery } diff --git a/internal/repoguard/prose_contracts_test.go b/internal/repoguard/prose_contracts_test.go index a15e45074..732eca409 100644 --- a/internal/repoguard/prose_contracts_test.go +++ b/internal/repoguard/prose_contracts_test.go @@ -1632,7 +1632,7 @@ var alignmentContracts = []proseContract{ // in its own reference. {sentinel: "change_0585_update_ticket_skill", file: "skills/docket-update-ticket/SKILL.md", present: []string{ - "This skill runs inline, in your own session, and only when the person asks", + "This skill runs inline, in the session or workflow agent that invokes it", "run the read without `--event`", "`not-linked`: say the change has no ticket (`#612 has no ticket`)", "`partial`: the link is broken; point the person to `docket-link-ticket` to fix or remove it", @@ -1771,7 +1771,6 @@ var alignmentContracts = []proseContract{ present: []string{ "| `tickets.site` | `\"\"` (unset) | any layer |", "| `tickets.project` | `\"\"` (unset) | any layer |", - "| `tickets.auto.change_created` | `false` | any layer |", "| `tickets.auto.spec_written` | `false` | any layer |", "| `tickets.auto.pr_opened` | `false` | any layer |", "| `tickets.auto.pr_merged` | `false` | any layer |", @@ -1785,6 +1784,9 @@ var alignmentContracts = []proseContract{ "Linking a change to a ticket does not consult them", "| repo-only | the ticket system ", "| repo-only | a switch for ", + "tickets.auto.change_created", + "nothing acts on them yet", + "; no effect yet |", }}, {sentinel: "change_0592_tickets_any_layer", file: ".docket.example.yml", present: []string{"# project: \"\"", "# pr_opened: false"}, @@ -1792,6 +1794,8 @@ var alignmentContracts = []proseContract{ "No docket command reads these settings yet", "These settings belong to the repository", "Unlike the other ticket settings", + "change_created", + "does not act on them yet", }}, } diff --git a/internal/repoguard/ticket_auto_updates_contracts_test.go b/internal/repoguard/ticket_auto_updates_contracts_test.go new file mode 100644 index 000000000..a812fd69e --- /dev/null +++ b/internal/repoguard/ticket_auto_updates_contracts_test.go @@ -0,0 +1,196 @@ +package repoguard + +import ( + "strings" + "testing" +) + +// autoTicketContract pins the prose of the automatic ticket-update path in one +// file: every present phrase must appear and every absent phrase must not. +// Matching is whitespace-collapsed and file-wide, so a hard-wrapped phrase +// still matches. +type autoTicketContract struct { + file string + present []string + absent []string +} + +// autoTicketContracts is the automatic ticket-update path: docket-update-ticket +// runs when a workflow invokes it after an event whose tickets.auto switch is +// on, and its references/automatic.md replaces every point where it would ask +// or wait. The convention's *Automatic ticket updates* shared definition and +// the five workflow sites are pinned here too; which files hold a site is +// derived and checked by TestTicketAutoUpdateSites in internal/app. +var autoTicketContracts = []autoTicketContract{ + {file: "skills/docket-update-ticket/SKILL.md", + present: []string{ + "This skill runs inline, in the session or workflow agent that invokes it", + "or when a docket workflow invokes it after an event whose `tickets.auto` switch is on", + "read `references/automatic.md` now (blocking)", + "When a docket workflow invoked this skill, that workflow has already run the startup check: run none here.", + }, + absent: []string{ + "Nothing here runs on its own after an event", + "and only when the person asks: it posts", + }}, + {file: "skills/docket-update-ticket/references/automatic.md", + present: []string{ + "The caller supplies the change and the event.", + "Never ask and never wait.", + "post nothing and report one line", + "when `visibility` is anything other than `shared`", + "automatic updates are not available in a private repository", + "when no connector for `ticket.provider` is available in this session", + "an uncertain outcome is reported as uncertain", + "**`event.switch` is `false`:** post nothing and say nothing, whatever the caller directed.", + "`ticket.state` is `not-linked`:** post nothing and say nothing", + "Never retry, and never touch the calling run", + "no halt, no blocked marker, no changed disposition, and no metadata write", + "A duplicate comment is acceptable and is deleted by hand.", + "Never load `references/private.md` on this path.", + "**No startup check of its own.**", + "take `metadata_worktree_path` from the caller's `repository.prepare` context", + "A `refused` or `error` answer from a docket read on this path is never a stop: post nothing, report one line (`Not posted to # (): .`), and return to the workflow.", + }}, + {file: "skills/docket-convention/SKILL.md", + present: []string{ + "### Automatic ticket updates (shared definition)", + "with `--id --event --json`", + "when `context.event.switch` is `false` or `context.ticket.state` is `not-linked`", + "no post, no prompt, no report line", + "Ticket update for # not checked: ", + "never changes a run's disposition, writes a halt or blocked marker, or stops a later step", + "A replayed success posts like a first success", + "when a stack root lands only the root's ticket is updated", + }}, + {file: "skills/docket-groom-next/SKILL.md", + present: []string{ + "the switch is the consent, so nothing is asked", + "Kill, defer, revise, and re-enable never post.", + }}, + {file: "skills/docket-auto-groom/SKILL.md", + present: []string{ + "before step 1 selects the next stub", + "An abstain never posts.", + }}, + {file: "skills/docket-implement-next/SKILL.md", + present: []string{ + "(a retry's earlier applied outcome included)", + "The run's disposition is `advanced` whatever the update's outcome", + }}, + {file: "skills/docket-implement-next/references/results-artifact.md", + present: []string{ + "After `change.complete` returns `completed` or `already-completed`", + }}, + {file: "skills/docket-finalize-change/SKILL.md", + present: []string{ + "never for a `root-archived` result's `carried_ids`", + "never after `contended`, `blocked`, or `unknown`", + "`already-closed-out` for a change this run closed out", + }}, + // The tickets concepts page: its sections, both reasons ticket creation is + // on request, the no-setting invariant, the three ways a change gets a + // ticket, the four switches, and its index lines. These keep the page from + // losing a part; its accuracy against the skills is checked by reading. + {file: "docs/concepts/tickets.md", + present: []string{ + "# Tickets", + "## The problem it solves", + "## The moving parts", + "## The invariants", + "## Why docket never creates a ticket by itself", + "### Creating a ticket is a person's action", + "### There is no one right moment to create it", + "## Decided in", + "A ticket is created only when a person asks and approves the draft. No setting changes that.", + "link an existing ticket to a change", + "create a ticket from a change", + "make a change from a ticket", + "`tickets.auto.spec_written`", + "`tickets.auto.pr_opened`", + "`tickets.auto.pr_merged`", + "`tickets.auto.results_completed`", + "retry uploads after a timeout", + "agents report on tickets, and people create them", + "an automatic update posts nothing and reports one line", + "ADR-0163 — Automatic ticket updates are per-event switches; ticket creation is never automatic.", + }, + absent: []string{"change_created", "was once planned", "dropped"}}, + {file: "docs/concepts/README.md", + present: []string{"[Tickets](./tickets.md)"}}, + {file: "docs/README.md", + present: []string{"[Tickets](concepts/tickets.md)"}}, + {file: "docs/reference/config-keys.md", + present: []string{ + "Creating a ticket has no switch: it is always on request", + "../concepts/tickets.md#why-docket-never-creates-a-ticket-by-itself", + "Off (the default) means nothing is posted or reported, unless docket's own read of the change fails", + }, + absent: []string{"means nothing is posted or reported, and a switch"}}, + {file: ".docket.example.yml", + present: []string{"off means nothing is posted or reported, unless docket's own"}}, + {file: "docs/reference/glossary.md", + present: []string{ + "Docket never creates a ticket by itself", + "../concepts/tickets.md#why-docket-never-creates-a-ticket-by-itself", + "or by itself after an event whose switch is on", + "An automatic update in a private repository posts nothing and reports one line.", + }, + absent: []string{"to a change's linked ticket when you ask. It posts"}}, + {file: "docs/reference/skills-and-agents.md", + present: []string{"when you ask, or automatically after an event whose `tickets.auto` switch is on"}, + absent: []string{"linked ticket when you ask (spec written"}}, +} + +// autoTicketViolations returns one message per missing present phrase and per +// found absent phrase in body, comparing whitespace-collapsed text. +func autoTicketViolations(c autoTicketContract, body string) []string { + flat := collapseWS(body) + var out []string + for _, p := range c.present { + if !strings.Contains(flat, collapseWS(p)) { + out = append(out, c.file+": missing required phrase "+quoteQ(p)) + } + } + for _, a := range c.absent { + if strings.Contains(flat, collapseWS(a)) { + out = append(out, c.file+": contains forbidden phrase "+quoteQ(a)) + } + } + return out +} + +func quoteQ(s string) string { return "\"" + s + "\"" } + +// TestAutoTicketUpdateContracts checks every autoTicketContracts row. An +// unreadable file fails closed (readRepoFile is fatal), and a population floor +// keeps the table from silently shrinking. +func TestAutoTicketUpdateContracts(t *testing.T) { + t.Run("non_vacuity", func(t *testing.T) { + c := autoTicketContract{file: "synthetic", + present: []string{"must be here", "split across lines"}, + absent: []string{"must not be here"}} + if v := autoTicketViolations(c, "must be here; split across\n lines"); len(v) != 0 { + t.Fatalf("a present phrase split by a newline must still match; got %v", v) + } + if v := autoTicketViolations(c, "split across lines only"); len(v) != 1 || !strings.Contains(v[0], "missing") { + t.Fatalf("a missing present phrase must be detected; got %v", v) + } + if v := autoTicketViolations(c, "must be here, split across lines, must not\nbe here"); len(v) != 1 || !strings.Contains(v[0], "forbidden") { + t.Fatalf("a present forbidden phrase must be detected; got %v", v) + } + }) + + const floor = 76 + checks := 0 + for _, c := range autoTicketContracts { + body := readRepoFile(t, c.file) + checks += len(c.present) + len(c.absent) + for _, v := range autoTicketViolations(c, body) { + t.Error(v) + } + } + if checks < floor { + t.Fatalf("autoTicketContracts ran %d checks, below the floor of %d", checks, floor) + } +} diff --git a/internal/repoguard/update_ticket_skill_test.go b/internal/repoguard/update_ticket_skill_test.go index be5c6469e..48714ab0b 100644 --- a/internal/repoguard/update_ticket_skill_test.go +++ b/internal/repoguard/update_ticket_skill_test.go @@ -16,6 +16,7 @@ func TestUpdateTicketSkillIsInline(t *testing.T) { const name = "docket-update-ticket" assertInlineSkill(t, name, []string{ "post an update or comment about a change to its ticket", + "or when a docket workflow invokes it after an event whose `tickets.auto` switch is on", "not for creating or linking a ticket", }) body := readRepoFile(t, "skills/"+name+"/SKILL.md") diff --git a/skills/docket-auto-groom/SKILL.md b/skills/docket-auto-groom/SKILL.md index d8cbaf6aa..fee6cb078 100644 --- a/skills/docket-auto-groom/SKILL.md +++ b/skills/docket-auto-groom/SKILL.md @@ -54,11 +54,15 @@ Dispatch the dedicated **`docket-auto-groom-critic`** subagent (foreground, at t ### Step 5 — The outcome lands (no separate board pass) -Every exit's Step-4 `change.groom` operation is the whole write — it re-checks the pinned `revision` and commits the record, any spec, the `## Artifacts` block, and the inline board in one metadata commit pushed under an exact-lease push, so there is **no separate Board pass** and no hand-staged commit. On a `contended` refusal it writes nothing: re-sync (re-run the `repository.prepare` operation), re-read the stub's `path` + `revision` from the `status` operation, and if it is no longer auto-groomable (groomed, killed, claimed, or opted out) DISCARD this iteration's draft (discard the draft from scratch space) and move on; otherwise re-author and retry. Return to step 1. +Every exit's Step-4 `change.groom` operation is the whole write — it re-checks the pinned `revision` and commits the record, any spec, the `## Artifacts` block, and the inline board in one metadata commit pushed under an exact-lease push, so there is **no separate Board pass** and no hand-staged commit. On a `contended` refusal it writes nothing: re-sync (re-run the `repository.prepare` operation), re-read the stub's `path` + `revision` from the `status` operation, and if it is no longer auto-groomable (groomed, killed, claimed, or opted out) DISCARD this iteration's draft (discard the draft from scratch space) and move on; otherwise re-author and retry. + +**Ticket update.** After a spec exit's transaction lands, before step 1 selects the next stub, follow the convention's *Automatic ticket updates* for `tickets.auto.spec_written`; at its third step, invoke `docket-update-ticket` **DIRECTED to:** post the spec-written update for this change as an automatic update; nobody is present, so anything the skill would ask is answered by posting nothing and reporting one line; then return here. An abstain never posts. + +Return to step 1. ### Step 6 — Report -Summarize the drain: groomed N, abstained K — each abstain with its one-line reason — plus each change it held and anything skipped to a lost race. STOP. Grooming never implements; the build-ready output is `docket-implement-next`'s queue. +Summarize the drain: groomed N, abstained K — each abstain with its one-line reason — plus each change it held, anything skipped to a lost race, and each ticket-update line. STOP. Grooming never implements; the build-ready output is `docket-implement-next`'s queue. ## Termination & concurrency diff --git a/skills/docket-convention/SKILL.md b/skills/docket-convention/SKILL.md index 00da5f647..450490b7d 100644 --- a/skills/docket-convention/SKILL.md +++ b/skills/docket-convention/SKILL.md @@ -308,6 +308,16 @@ A stub is **auto-groomable** — selectable by `docket-auto-groom` — when it i **Interactive selection bands.** `docket-groom-next` still sees every needs-grooming stub, but its default order prefers stubs that need a human: (1) abstained (`## Auto-groom blocked` present), (2) `auto_groomable` unset or `false`, (3) `auto_groomable: true` — flagged "docket-auto-groom will handle it unless you want it now." Within each band, the deterministic selection order applies. The board renders abstained stubs as **auto-groom blocked — needs you**, distinct from plain needs-grooming. +### Automatic ticket updates (shared definition) + +A `tickets.auto.` switch lets the workflow that just finished an event post that event's update to the change's ticket by itself. Each workflow's own site names its event and the point it fires at. Every site does these three things, in order: + +1. **Read.** Run the `context.ticket` operation (argv from the capability catalog) with `--id --event --json`. +2. **Stay silent** when `context.event.switch` is `false` or `context.ticket.state` is `not-linked`: do nothing more and say nothing — no post, no prompt, no report line. +3. **Otherwise invoke `docket-update-ticket`** with the site's own `DIRECTED to:` direction, which names the change and the event and says the update is automatic. + +A read that does not return `result: applied` costs one report line, `Ticket update for # not checked: `, and the run carries on. An automatic update never prompts, waits, queues, retries, or records an update as owed. Its outcome never changes a run's disposition, writes a halt or blocked marker, or stops a later step: a failed or impossible post is one report line. A replayed success posts like a first success, so a retried run may post a duplicate, which is deleted by hand. Only the sites post. A closeout run as housekeeping (the maintenance sweep, a status refresh, or implement-next's closeout of a named change's merged dependencies) posts nothing, and when a stack root lands only the root's ticket is updated. + ### Discovered work Work an autonomous skill discovers mid-run is **reported in the run's final report, never silently diff --git a/skills/docket-finalize-change/SKILL.md b/skills/docket-finalize-change/SKILL.md index 82215a28f..61bdbdf1e 100644 --- a/skills/docket-finalize-change/SKILL.md +++ b/skills/docket-finalize-change/SKILL.md @@ -168,6 +168,8 @@ UTC archive date from the verified `mergedAt`, and applies one atomic transactio - `already-closed-out` — the promised final state already exists (a response-lost success): a keyed no-op, never a duplicate transition. - `contended` / `blocked` / `unknown` — a lost race, an illegal source status or destination mismatch, or an unobservable probe; re-read context (`contended`) or stop (`halted`). Close-out is one metadata commit plus the best-effort PR-description backlink repoint; nothing touches the integration branch. A PR description that could not be repointed is a `pr-backlink-pending` warning on an otherwise-final result: report it, never redo the merge; cleanup (step 10) and the maintenance sweep retry it. +**Ticket update.** After `finalize.closeout` returns `done-archived`, `stacked-merged`, `root-archived`, or `already-closed-out` for a change this run closed out, follow the convention's *Automatic ticket updates* for `tickets.auto.pr_merged`; at its third step, invoke `docket-update-ticket` **DIRECTED to:** post the PR-merged update for this change as an automatic update; ask nothing, so anything the skill would ask is answered by posting nothing and reporting one line; then return here. Post once for each change a closeout call was made for, never for a `root-archived` result's `carried_ids`, and never after `contended`, `blocked`, or `unknown`. The line goes in the final report, and the update's outcome never changes the run's disposition. + ### 10. Cleanup — Docket-owned resources only The `finalize.cleanup` operation with `--id `. An ordered, independently retryable suffix: repair the PR description's backlink first when it is pending, remove the workspace from manifest facts, delete the local branch only when its exact recorded tip is worktree-detached and contained in the verified merge chain, and delete the remote ref only under the exact lease after a fresh probe shows no open child PR targets it. Every probe treats present, cleanly absent, and unknown as three outcomes — an injected or real probe error retains the resource with a pending result and `children-retarget-required`/a retention reason, never a destroy. A non-final change refuses (the one pre-final exception is restoring an aborted owned rebase). Stacked-merged changes retain their workspace and branches until the root closes. After `root-archived`, run cleanup for the root, then for each id in its `carried_ids`, reporting each result like the root's; a child's result never changes another's. A carried child's folder and branches go only once its work is proven on the integration branch through its stack; otherwise it keeps everything and reports `pending` (`carry-unproven`, or `destination-mismatch` for an unproven stack relationship), with no delete advice. Cleanup failure never unwinds the merge. Once the workspace leg finishes, any disposition (`cleaned`, `pending`, `children-retarget-required`) may carry a `workspace-remnant` warning naming a leftover folder to delete by hand — name it in the final report; a `workspace-blocked` finding names what blocked the workspace. diff --git a/skills/docket-groom-next/SKILL.md b/skills/docket-groom-next/SKILL.md index e62af2310..7a93a1cd8 100644 --- a/skills/docket-groom-next/SKILL.md +++ b/skills/docket-groom-next/SKILL.md @@ -70,7 +70,11 @@ All five exits reuse existing transitions — this skill introduces no new lifec ### Step 5 — The transaction lands (no separate board pass) -The Step-4 typed op is the whole write: it re-checks the pinned exact `revision`, commits the change record, the spec, the `## Artifacts` block, and the inline board in one metadata commit pushed to the metadata remote under an exact-lease push — so there is no separate hand-staged commit and **no separate Board pass** (the readiness cell flips from needs-grooming, or the row leaves the Proposed section on a kill or defer, in that same commit; a revise keeps the row's readiness unless it sets or lifts a hold; a re-enable returns an abstained row to needs-grooming). On a `contended` refusal the op writes nothing: re-sync (re-run the `repository.prepare` operation), re-read the record's `path` + `revision` from the `status` operation, and — on a groom exit, if it is no longer needs-grooming (someone else groomed, killed, or claimed it) — STOP and report rather than overwrite; otherwise re-author and retry. On a revise, also re-read the spec (a fresh `spec_revision`) and stop if the change is no longer `proposed` or a stub edit finds it groomed (`spec:`). STOP — grooming never implements. +The Step-4 typed op is the whole write: it re-checks the pinned exact `revision`, commits the change record, the spec, the `## Artifacts` block, and the inline board in one metadata commit pushed to the metadata remote under an exact-lease push — so there is no separate hand-staged commit and **no separate Board pass** (the readiness cell flips from needs-grooming, or the row leaves the Proposed section on a kill or defer, in that same commit; a revise keeps the row's readiness unless it sets or lifts a hold; a re-enable returns an abstained row to needs-grooming). On a `contended` refusal the op writes nothing: re-sync (re-run the `repository.prepare` operation), re-read the record's `path` + `revision` from the `status` operation, and — on a groom exit, if it is no longer needs-grooming (someone else groomed, killed, or claimed it) — STOP and report rather than overwrite; otherwise re-author and retry. On a revise, also re-read the spec (a fresh `spec_revision`) and stop if the change is no longer `proposed` or a stub edit finds it groomed (`spec:`). + +**Ticket update.** After a spec exit's transaction lands, follow the convention's *Automatic ticket updates* for `tickets.auto.spec_written`; at its third step, invoke `docket-update-ticket` **DIRECTED to:** post the spec-written update for this change as an automatic update; ask the person nothing, so anything the skill would ask is answered by posting nothing and reporting one line; then return here. The person being in the session changes nothing: the switch is the consent, so nothing is asked. Kill, defer, revise, and re-enable never post. + +STOP — grooming never implements. ## Concurrency — no claim diff --git a/skills/docket-implement-next/SKILL.md b/skills/docket-implement-next/SKILL.md index 8ff93c256..dcf60909b 100644 --- a/skills/docket-implement-next/SKILL.md +++ b/skills/docket-implement-next/SKILL.md @@ -156,6 +156,8 @@ The results artifact is **required for every implemented change** — there is n **Mark implemented.** The `change.mark-implemented` operation with `--id --revision --head --pr --evidence ` is the final mutation in this scope. Before its transaction it reprobes Git and GitHub and proves: the change is still the exact `in-progress` revision, `reconciled: true`, linked to the verified plan; local and remote feature heads equal the supplied head; valid evidence names that head and a passed gate; exactly one verified PR for the feature branch targets the resolved effective-base branch and names that head; and a results artifact is attached, read from the metadata branch, and satisfies the final content contract and its artifact identity (missing, invalid, or unattached results refuse the transition). It then applies the landed transition atomically — `status: implemented` + `pr:` + updated date + the verified evidence as the record's `## Build evidence` section + `## Artifacts` block + inline board + audit receipt (letting the sweep read `pr:`), rendering the board inside that transaction, so no separate Board pass runs. It does NOT clear the claim, delete the branch/workspace, merge, archive, or close descendants. A retry against an already-`implemented` change with matching PR/head returns the prior applied outcome, never a duplicate transition. +**Ticket update.** After `change.mark-implemented` returns its applied outcome (a retry's earlier applied outcome included), follow the convention's *Automatic ticket updates* for `tickets.auto.pr_opened`; at its third step, invoke `docket-update-ticket` **DIRECTED to:** post the PR-opened update for this change as an automatic update; nobody is present, so anything the skill would ask is answered by posting nothing and reporting one line; then return here. The run's disposition is `advanced` whatever the update's outcome, and its line goes in the final report. + **Verify the run.** The `run.verify` operation with `--id ` is read-only: it reports one closed verdict — `run-complete` / `run-unclaimed` / `run-incomplete` / `run-halted` / `run-waiting` — and enumerates every unmet condition with its stable reason and observed identity. Automation keys on the typed verdict, **never** the exit code (all verdicts exit 0). `run-complete` is the receipt that Step 7's postcondition (or the results-artifact ending's) holds; `run-halted` is the closed verdict for a change carrying a `## Run halted` marker — a human is needed, and an attributed caller re-dispatches it through the resume path (the `change.resume-halted` operation with `--acknowledge-quiescent`, Step 2), never a fresh claim. `run-waiting ` is the closed verdict for a change whose gate stopped at a safe, resumable continuation — neither complete nor failed: an attributed caller resumes that exact handoff rather than drawing another change or re-dispatching a fresh run, and precedence is completed-run postconditions first, then a valid `run-waiting`, then ordinary `run-incomplete`; a persisted `run-halted` stays terminal. A run **dispatched with an explicit change id, continuation id, and run key resumes, not restarts**: its FIRST act is the `run.continue` operation with ` `, claiming the recovered drive **before any other work**; it never launches a replacement test, and this is a **continuation, not `run-retry-once`** — the key stays active until a true terminal disposition. Each `run-retry-once` authorizes exactly one next dispatch; the run tracker may grant another on a later eligible attempt while the configured `run.max_attempts` budget allows, and a continuation consumes none of that budget. A gated parent's prompt may also carry a **run context** token; pass it, always as `--run-context`, into every build-owned `gate.drive.start` (`--owner build` — Step 6's evidence re-mint and re-gates, the build role's final suite gate, and each post-repair attempt the build role starts) this run performs — each invoked with `--json` per the shared capture requirement and each always carrying `--change-id ` — and into the Step-2 claim, omitting it only when the prompt carried none (a `run-untracked` or ungated run). Build-task workers never receive it: they run their tests directly and call no gate operation. **STOP.** The change stays in `active/` as `implemented` until a human merges it, or approves `docket-finalize-change` to merge it. diff --git a/skills/docket-implement-next/references/results-artifact.md b/skills/docket-implement-next/references/results-artifact.md index 31e08a76c..5f3416ff1 100644 --- a/skills/docket-implement-next/references/results-artifact.md +++ b/skills/docket-implement-next/references/results-artifact.md @@ -72,5 +72,12 @@ and how its findings ended. left in the worktree, commits on the branch) goes into the run report; it **never halts the run and never undoes the completion**. +**Ticket update.** After `change.complete` returns `completed` or `already-completed`, follow the +convention's *Automatic ticket updates* for `tickets.auto.results_completed`; at its third step, +invoke `docket-update-ticket` **DIRECTED to:** post the results-completed update for this change +as an automatic update; nobody is present, so anything the skill would ask is answered by posting +nothing and reporting one line; then return here. The run still ends `advanced`, and the line goes +in the final report. + End the run `advanced`. The final report names the results path and the cleanup disposition, plus the usual skipped changes and follow-up work with their backlog verdicts. diff --git a/skills/docket-update-ticket/SKILL.md b/skills/docket-update-ticket/SKILL.md index e2a65e988..b81f8d87c 100644 --- a/skills/docket-update-ticket/SKILL.md +++ b/skills/docket-update-ticket/SKILL.md @@ -1,20 +1,22 @@ --- name: docket-update-ticket -description: 'Use when the person asks to post an update or comment about a change to its ticket (`update CLOUD-123 now that the PR is open`, `tell the ticket the spec for #12 is written`, `let PROJ-9 know #40 was killed`); not for creating or linking a ticket.' +description: 'Use when the person asks to post an update or comment about a change to its ticket (`update CLOUD-123 now that the PR is open`, `tell the ticket the spec for #12 is written`, `let PROJ-9 know #40 was killed`), or when a docket workflow invokes it after an event whose `tickets.auto` switch is on; not for creating or linking a ticket.' --- # docket-update-ticket -This skill runs inline, in your own session, and only when the person asks: it posts one short comment to a change's linked ticket with your own tools. Nothing here runs on its own after an event. +This skill runs inline, in the session or workflow agent that invokes it: when the person asks, or when a docket workflow invokes it after an event whose `tickets.auto` switch is on. It posts one short comment to a change's linked ticket with that session's own tools. Words used here: a **ticket** is the item in the team's ticket system; the **provider** is which ticket system it is (`jira`, `linear`, …); a **connector** is the session's own tools for that system (an MCP server or plugin the person installed and signed in to); an **update** is the comment you post, with its links. Docket installs no connector and stores no credential. ## Convention (load first — blocking) -Invoke the `docket-convention` skill via the Skill tool first — unless already invoked this session — and run its *startup check*. Everything below uses its vocabulary. +Invoke the `docket-convention` skill via the Skill tool first — unless already invoked this session — and run its *startup check*. When a docket workflow invoked this skill, that workflow has already run the startup check: run none here. Everything below uses its vocabulary. This skill makes no docket metadata write. Its reads are the `context.ticket` operation and, for a request naming only a ticket, the `status` operation (section 1); in a private repository it also invokes `docket-export`, which writes each exported file to a temp directory and may read `leak_check.match_word` through `diagnostic.config` (section 4). Run `context.ticket` (argv from the capability catalog) with `--id `, `--event ` when the update follows an event, and `--json`. Its result is under `context`: `metadata_commit`, `visibility`, `change` (`status`, `deliverable`, `path`), `ticket` (`state`: `linked`, `not-linked`, or `partial`; and `provider`, `id`, `url` when `linked`), `event` (`happened`, and `reason` when not), `facts` (`pr_url`, `merge`), and `artifacts` (`role`, `path`, `url`). +**Invoked by a workflow.** When a docket workflow invoked this skill after an event, **read `references/automatic.md` now (blocking)** before section 1. It replaces sections 1, 2, and 5, and every point where this skill would ask or wait. + ## 1. Work out the request - **The change.** Usually named (`#612`). When the request names only a ticket, find the changes whose record carries that ticket in the `records` array of the `status` operation run with `--json --records`. Exactly one: use it. Several (one ticket may be on several changes): ask the person which. None: say no change carries that ticket. diff --git a/skills/docket-update-ticket/references/automatic.md b/skills/docket-update-ticket/references/automatic.md new file mode 100644 index 000000000..94a53b6e2 --- /dev/null +++ b/skills/docket-update-ticket/references/automatic.md @@ -0,0 +1,14 @@ +# Automatic updates + +Loaded from `SKILL.md` when a docket workflow invoked this skill after an event whose switch is on. The rules in `SKILL.md` apply except where this file replaces them. + +- **The caller supplies the change and the event.** Take both from the workflow's direction. Nothing is worked out from a person's words, and no one is mentioned: skip sections 1 and 5. +- **Never ask and never wait.** Show no draft. Wherever the on-request path would ask the person something, post nothing and report one line. +- **No startup check of its own.** The calling workflow already ran it: take `metadata_worktree_path` from the caller's `repository.prepare` context. A `refused` or `error` answer from a docket read on this path is never a stop: post nothing, report one line (`Not posted to # (): .`), and return to the workflow. +- **Read first.** Run the `context.ticket` read yourself with `--id`, `--event`, and `--json`, as on request, so the update is composed from one pinned commit. +- **`event.switch` is `false`:** post nothing and say nothing, whatever the caller directed. Check this first, before anything else the read returned. +- **`ticket.state` is `not-linked`:** post nothing and say nothing. +- **Otherwise post nothing and report one line** when `ticket.state` is `partial` (the ticket link is broken); when `event.happened` is `false` (name the missing fact from `event.reason`); when `visibility` is anything other than `shared` (`automatic updates are not available in a private repository`); when no connector for `ticket.provider` is available in this session; or when the post failed or its outcome is uncertain (an uncertain outcome is reported as uncertain). +- **Otherwise post** exactly what an on-request update for this event posts in a shared repository: its row of section 3's table, the editorial standard, and the links. **Read `references/shared.md` now (blocking).** Never load `references/private.md` on this path. +- **Report one line** and return to the workflow: the update as posted, only with the connector's confirmation, naming the ticket and the event (`Posted the PR-opened update to CLOUD-123.`); or what was not posted and why (`Not posted to CLOUD-123 (PR opened): no Jira connector is available in this session.`). +- **Never retry, and never touch the calling run:** no halt, no blocked marker, no changed disposition, and no metadata write. A duplicate comment is acceptable and is deleted by hand.