From a0a4f773f96863036041aa00c88d919367290558 Mon Sep 17 00:00:00 2001 From: Daniel Hanold Date: Tue, 10 Nov 2026 07:50:23 -0500 Subject: [PATCH 1/9] Add design spec: Post a ticket update on request (shared repositories) --- ...e-on-request-shared-repositories-design.md | 197 ++++++++++++++++++ 1 file changed, 197 insertions(+) create mode 100644 docs/superpowers/specs/2026-11-10-post-a-ticket-update-on-request-shared-repositories-design.md diff --git a/docs/superpowers/specs/2026-11-10-post-a-ticket-update-on-request-shared-repositories-design.md b/docs/superpowers/specs/2026-11-10-post-a-ticket-update-on-request-shared-repositories-design.md new file mode 100644 index 000000000..8b9b02e3f --- /dev/null +++ b/docs/superpowers/specs/2026-11-10-post-a-ticket-update-on-request-shared-repositories-design.md @@ -0,0 +1,197 @@ +# Post a ticket update on request (shared repositories): design + +Change 0585 — Post a ticket update on request (shared repositories) + +Change #585, groomed interactively on 2026-11-10. + +## What this change delivers + +A person can ask an agent to post a short update about a change to that change's linked ticket ("update CLOUD-123, the PR for #612 is ready for review"). The agent writes a few lines under a fixed editorial standard and posts them as a comment, with links to the spec or results file pinned to the commit that holds them. Two pieces: + +1. **`context.ticket`**, a new read-only operation that returns, in one call, everything an update needs for a change and (optionally) an event. +2. **`docket-update-ticket`**, a new inline skill that refuses when an update is not possible, composes the comment, mentions the people the person names so the ticket system notifies them, posts it through the session's own connector tools, and reports the outcome truthfully. + +This change covers shared repositories only. In a private repository the skill posts nothing and says private repositories are not supported yet; change #586 adds private delivery. Automatic posting after each event is change #587. + +## Why + +People who work in a ticket system should get short, deliberate updates at the moments that matter, with a link to the artifact as it stood then, without learning docket or reading an agent's working history. The most common case is a PR ready for review: the reviewer opens the PR on GitHub, reads the spec, then the code. The comment exists to get them there quickly and tell them what to watch for; it does not replace the PR. + +## Vocabulary + +- **ticket**: the item in the team's ticket system (a Jira issue, a Linear issue, a GitHub issue, an Azure DevOps work item). +- **provider**: which ticket system (`jira`, `linear`, …), stored on the change as `ticket_provider`. +- **connector**: the session's own tools for that system (an MCP server or plugin the harness owner installed and signed in to). +- **event**: a point in a change's life after which an update makes sense. This change handles four: `spec_written`, `pr_opened`, `pr_merged`, `results_completed` (the same tokens as the `tickets.auto.` config keys). +- **update**: the comment posted to the ticket, with its links. + +People say "update the ticket after the PR was opened", not event names. The skill's trigger wording uses the conversational form; event names appear only in the read operation and config. + +## Settled decisions (carried from change 581; not reopened) + +These were fixed by change 581's design and are restated here so the build needs nothing from that change. + +1. **On request only, here.** The person asks at any time after an event has happened; the update is composed from the artifacts as they stand. If the event has not happened (a merge update for an unmerged change), the agent says so and posts nothing. +2. **A late update never misstates the current state.** Asked for the PR-opened update after the merge, it describes the PR opening and says the PR has since merged. +3. **An update needs a linked ticket.** A change with no ticket never gets one; the agent says the change has no ticket. A broken link (a hand-edited partial set) counts as not linked; the agent points the person to `docket-link-ticket` to fix or remove it. +4. **Events and content:** + + | Event | Has happened when | The update says | Links | + |---|---|---|---| + | spec written | the change has a spec | the approach and key decisions, plus where the change actually stands, from facts docket holds (designed, not yet built; being built; built, PR open; merged). Never a claim of review, approval, or authorship | the spec | + | PR opened | the change has a PR | the PR link, what was built, what the reviewer needs to know | the PR, **the spec, and the results file** | + | PR merged | the change is `done` with a merged PR, or `stacked-merged` | what merged, where (the integration branch; or the parent branch for a stacked child, worded as "not yet in "), key outcomes, anything left to do; from the results file's Outcome and Known issues plus the change's `## Closeout notes`. Never claims deployment or acceptance | the results file | + | results completed | a results-only change (`deliverable: results-artifact`) is `done` | findings, conclusions, limits, any action needed | the results file | + + The PR-opened row's spec link is added by this grooming (581 linked only the results file); see *Decided here*. +5. **Updates with no event, on request only:** a material revision (including a re-groomed spec), a blocker or a decision that is needed, and a killed change. The content comes from the person's words and the artifacts (for a kill, the change's `## Why killed`). +6. **Change created is not this skill's.** Creating a ticket from a change belongs to `docket-link-ticket`; this skill points the person there. +7. **Plans never go out.** They are the agent's working document; no link or content from a plan. +8. **Who posts.** The agent running the skill, with the session's own connector tools. Docket installs no connector, stores no credential, and contains no provider API code. Some connectors expose operations only through a discovery tool (the Atlassian connector's `discover`); the skill looks there before concluding an operation is missing. +9. **Failures.** Connector missing, post failed, or outcome uncertain: one plain line naming what was not posted and why. Nothing stops, retries, or is recorded. An uncertain outcome is reported as uncertain and the person decides whether to ask again. An update is never reported as posted without the connector's confirmation. Duplicate comments are acceptable and are deleted by hand; there is no exactly-once guarantee, no ledger, no queue, and no retry. +10. **Shared delivery.** The comment links the artifact on GitHub, pinned to the commit holding the version being discussed (the version at posting time). Readers are assumed to be able to open the repository; docket checks no permissions. +11. **Editorial contract.** Updates are for humans: a few short sentences or bullets, scaled to how much the update matters. Include, when relevant: what happened; what matters (key outcomes, consequential decisions, limitations); what is needed next (an action, test, review, or decision for the reader); supporting material (the PR, the artifact links). Omit agent narration and how the agent worked, brainstorming notes and work logs, file lists, test inventories, pasted command output, repeated background, generic filler, empty headings, and pasted artifact contents. Concision must keep material blockers, risks, and required actions. Say only what the change and its evidence support: a merge is not a deployment or an acceptance. + + **Layout (decided here; a principle, not a template).** Write for a person reading the comment in the ticket system. Lay it out so it scans: short paragraphs, a list, or a single line, whichever reads best for this update. Use the format the connector accepts, so the layout survives posting. Label links (`Spec:`, `Results:`). The examples below are laid out the way a comment should read; a skill's examples teach layout more strongly than its rules, so they must be well laid out themselves. + + Examples, for tone, length, and layout: + + > **@Jane Doe** — PR ready for review: https://github.com/acme/api/pull/48 + > + > Invalid requests now fail with a clear error before any work starts, instead of failing partway through. The API contract is unchanged, so existing clients need no update. + > + > Worth a close look: the validation runs before authentication, so a malformed request from an unauthenticated caller now gets a 400 instead of a 401. + > + > Before merging: one manual check against staging, described in the results. + > + > Spec: https://github.com/acme/api/blob/4f2c9e1/docs/superpowers/specs/2026-11-08-validate-requests-design.md + > Results: https://github.com/acme/api/blob/4f2c9e1/docs/results/2026-11-08-validate-requests-results.md + + > Merged into main. Invalid requests now return a clear error before processing starts. Deployment has not been confirmed. + > + > Automated checks passed; one manual check remains, described in the results. + > + > Results: https://github.com/acme/api/blob/4f2c9e1/docs/results/2026-11-08-validate-requests-results.md + + > Merged into main. Left to do before this can ship: + > + > - run the staging data migration (steps in the results) + > - confirm the new rate limit with the platform team + > - remove the old endpoint once clients have moved (tracked separately) + > + > Results: https://github.com/acme/api/blob/4f2c9e1/docs/results/2026-11-08-validate-requests-results.md + + (Real links carry the full commit id.) + +12. **Harness responsibility.** The harness owner installs and configures connectors, credentials, and permissions. Docket defines what to post and when. The design is generic: Jira is the first provider exercised; there is no provider framework. +13. **Testing.** No ticket-system call is ever made from the docket repository; docket's own `.docket.yml` carries no `tickets.*` key. Verification is repository tests and fixtures only. The live check is a human step outside this repository (see *Testing*). + +## Decided here + +1. **The read operation is `context.ticket`**, shaped as below. +2. **Pinned links point at the metadata commit the read took.** For every change built since plan and results moved to the metadata branch, the spec and results live there, so one commit pins every link in a comment. The read's metadata pin is fetched from the metadata remote, so the commit is already pushed and browsable. The spec copy committed onto the feature branch is not linked. An older change whose results file never moved (`legacyArtifactBranch` in `internal/render/artifacts.go`) is rare: an artifact not present at the metadata commit is left out of `artifacts`, and the update goes without that link. +3. **The PR-opened update links the spec as well as the results file.** The spec is one file among many in the PR; the reviewer should reach it from the comment in one click. +4. **No native ticket "web link".** Jira can add a separate entry to a ticket's links panel (`createJiraIssueRemoteIssueLink`). It is not used: every update would add another entry docket cannot tidy (it keeps no record of what it posted), and it is a Jira-only second call. Links live in the comment only. +5. **A no-event read** serves the on-request-only updates (decision 5): `context.ticket` without `--event` returns everything except the event block. +6. **The change record is read, never linked.** The skill reads the change record (for `## Closeout notes`, `## Why killed`, title, status) but a comment links only the PR, the spec, and the results file. +7. **Leftovers from change 584 fixed here:** `docket-export`'s outside-tool example ("add the spec for 9 as a comment on PROJ-123") is rewritten so export no longer implies it posts ticket comments, and that kind of request is pointed to `docket-update-ticket`; `docket-link-ticket`'s *Not this skill's* line names `docket-update-ticket`. +8. **Mentions.** The person can ask for people to be mentioned so the ticket system notifies them (see *Mentions*). +9. **A request naming only a ticket** ("update CLOUD-123 now that the PR is open") is resolved by the skill, not the read: it finds the changes carrying that ticket in the `records` array of `status --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. A request naming both a change and a ticket where the change is linked to a different ticket stops and says which ticket the change carries; nothing is posted. +10. **A merge docket has not recorded yet.** A PR merged on GitHub stays `implemented` until docket-finalize-change or docket-status records it. The read stays offline (no GitHub call), so it cannot tell the difference; its reason is `merge-not-recorded`, never a claim that the PR has not merged. The skill says docket has not recorded a merge for the change and that, if the PR has merged, refreshing with `docket-status` records it. +11. **A stale config doc from change 584 fixed here.** In `docs/reference/config-keys.md`, the `tickets.provider`, `tickets.site`, and `tickets.project` rows end "no effect yet", but `docket-link-ticket` reads them. Their endings become "used when linking or creating a ticket", "used when linking a ticket by URL or id", and "used when creating a ticket". The five `tickets.auto.*` rows keep "no effect yet" (automatic posting is change #587). + +## The read operation: `context.ticket` + +`docket context ticket --id [--event spec_written|pr_opened|pr_merged|results_completed] [--repo-dir ] --json` (argv resolved from the capability catalog like every operation; listed in the catalog with effect `read`, and its request/result described by the `schema` operation). + +Modelled on `context.implementation` (`internal/app/implementation_context.go`): one fresh snapshot of the metadata branch, one protocol-v1 envelope, no writes. It works for any change, active or archived. + +Result fields: + +| Field | Meaning | +|---|---| +| `metadata_commit` | the full metadata commit the read took; every pinned URL uses it | +| `visibility` | `shared` or `private`, as the `repository.prepare` context reports it | +| `change` | `id`, `slug`, `title`, `status`, `deliverable`, `path` (the record's repo-relative path on the metadata branch, for reading) | +| `ticket` | `state`: `linked`, `not-linked`, or `partial` (a partial or invalid set, the same condition the `ticket-link-invalid` finding reports); plus `provider`, `id`, `url` when `linked` | +| `event` | present only with `--event`: `name`; `switch` (the effective `tickets.auto.` value; reported for automatic posting later, ignored on request); `happened` (bool); `reason` when not happened, one of `no-spec`, `no-pr`, `merge-not-recorded`, `not-results-artifact`, `not-completed` | +| `facts` | `pr_url` (the record's `pr:`, empty when none); `merge`, present when the change has merged: `destination_branch` (the integration branch, or for `stacked-merged` the parent change's recorded `branch:`) and `in_integration` (true for `done`, false for `stacked-merged`) | +| `artifacts` | one entry per artifact among `spec` and `results` (never `plan`) that the record names and that exists at `metadata_commit`: `role`, `path`, and `url` (GitHub blob URL pinned to `metadata_commit`; empty in a private repository or when the repository has no web URL) | + +"Has happened" rules: `spec_written` needs `spec:`; `pr_opened` needs `pr:`; `pr_merged` needs status `done` with a `pr:` (deliverable `pr`) or status `stacked-merged`; `results_completed` needs `deliverable: results-artifact` and status `done`. A killed change has happened for none of `pr_merged` and `results_completed`. + +Refusals (typed, nothing returned beyond the reason): an unknown `--event` value is `invalid-input`; an unknown change id is `not-found`. "Not linked", "partial", "not happened", and "private" are **not** refusals: the read reports them and the skill decides. + +**Pinned URL builder.** A new method beside `BlobURL` in `internal/render/link.go`, e.g. `BlobURLAtCommit(repoRelPath, commit string) string`: `RepoWebURL + "/blob/" + commit + "/" + repoRelPath`, empty when `RepoWebURL` is empty, the commit is empty, or `PrivateMetadata` is set (a private metadata commit has no web page). The operation obtains its `render.LinkContext` through the existing sole constructor `linkContextOf` (guarded by `TestLinkContextSoleConstructor`). + +Existing reads cover only fragments (`repository.prepare` gives visibility, `diagnostic.config` the switch, `status --json --records` the ticket object), which is why one operation is justified: composing three calls would push judgment-free work onto the agent (ADR-0012). + +## The skill: `docket-update-ticket` + +An inline skill (not an agent, no wrapper), harness-neutral, at `skills/docket-update-ticket/` with: + +- `SKILL.md`, short: when it applies, the startup check, the refusals, the per-event table (decision 4, plus the no-event updates of decision 5), the editorial contract, how to post and report, and routing to the delivery reference. +- `references/shared.md`: shared delivery (pinned links, which links go with which update, no native web link). Read only when `visibility` is `shared`. Change #586 adds `references/private.md` beside it. + +Trigger description, conversational: asked 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. + +Flow: + +1. Run the convention's startup check. +2. Work out the change, the event (none for the decision-5 cases), and any people to mention from the request. A request naming only a ticket is resolved as *Decided here* 9 says. Run `context.ticket`. +3. Refuse, posting nothing, with one plain line, when: the ticket is `not-linked` ("#612 has no ticket"); it is `partial` (point to `docket-link-ticket` to fix or remove the link); the request names a different ticket than the one linked; the event has not happened (say which fact is missing, e.g. "#612 has no PR"; for `merge-not-recorded`, *Decided here* 10's wording); `visibility` is `private` ("private repositories are not supported yet"). A request to create a ticket goes to `docket-link-ticket`. +4. Read what the update needs: the artifacts named by the read, and the change record for `## Closeout notes` or `## Why killed`. Compose the comment under the editorial contract, comparing the event to the current `status` so a late update says what has happened since. +5. Find the connector for the ticket's provider (looking in any discovery tool first). Resolve any mentions (*Mentions*). Post the comment to `ticket.id`. Make connector calls one at a time. +6. Report: posted (only with the connector's confirmation, naming the ticket and anyone mentioned), or one line for not posted or uncertain. No retry loop. + +The skill does not show a draft and wait for approval before posting: the person asked for the update, and the content follows the editorial contract. A person who wants to see it first can say so in the request. + +## Mentions + +A mention makes the ticket system notify a specific person; a plain comment waits until someone looks. The person asks for it in the request, in plain words: "update CLOUD-123, the PR for #612 is ready, and mention Jane Doe". More than one person may be named. + +- **Finding the person.** For each name, the skill runs a best-effort user search through the connector (in Jira, the connector's user lookup, which may be reachable only through its discovery tool). + - **Exactly one match:** mention that person and post; no approval step. The person asking is responsible for naming people specifically enough (a full name, not a first name alone) that a single match is the right person. + - **Several matches:** ask the person which one, listing the candidates' names and emails. + - **No match:** ask the person whether to post without that mention or try a different spelling. +- **A real mention only.** The comment uses the ticket system's own mention form, the one that notifies (in Jira, a mention bound to the person's account id). Plain text such as "@Jane" looks like a mention but notifies nobody, so the skill never substitutes it silently. If the connector cannot produce a real mention, the skill tells the person before posting and does not fake one. +- **Placement.** Mentions lead the comment ("Jane Doe — PR ready for review: …"). +- **Report.** The report names who was mentioned, and says so only with the connector's confirmation that the comment posted. +- No saved list of people; nothing about mentions is configured or recorded. + +## Registration and documentation + +The new skill joins the inline skills wherever `docket-link-ticket` is listed: the convention's agent-layer paragraph (`skills/docket-convention/SKILL.md`) and `skills/docket-convention/references/agent-layer.md`, the known-skill list in `internal/harness/inventory_test.go`, line and size budgets in `internal/repoguard/budgets_test.go`, and the reference docs that list skills (`docs/reference/skills-and-agents.md`) and operations. Embedded twins under `internal/assets/embedded/tree/` are regenerated with `go generate ./internal/assets/`. + +## Testing + +- **`context.ticket`**, with fixtures: each event happened and not happened with the right `reason`; `pr_merged` for `done` (destination the integration branch, `in_integration` true) and `stacked-merged` (destination the parent's branch, false); a killed change; ticket `linked`, `not-linked`, `partial`; shared repository URLs pinned to `metadata_commit`; private repository with empty URLs; no plan ever in `artifacts`; the no-event read omits `event`; unknown event and unknown id refused. Catalog and schema entries covered by the existing catalog and schema tests. +- **`BlobURLAtCommit`**: shared, no web URL, empty commit, private. +- **Skill structure** (repository guards in the style of `internal/repoguard/prose_contracts_test.go` and `export_skill_test.go`): the skill names each refusal, the per-event table, the never-a-plan rule, confirmation before "posted", the mention rules (one match posts, several or none asks, never a plain-text stand-in), the layout principle (written for a person reading it in the ticket system, in the format the connector accepts, links labeled), and routing to `references/shared.md`; `docket-export` no longer offers a ticket-comment example; `docket-link-ticket` points update requests to `docket-update-ticket`. +- **No ticket-system call** in any test, build, review, or results run. +- **Results:** an Important item under `## Human actions and testing`: from another repository linked to a sandbox ticket project, ask for each of the four event updates and one no-event update, and confirm the comment, its pinned links, the refusals, and that a mention of a fully named person notifies them. Done after the PR opens and before merging; no `hold: true`. + +## ADRs + +None new. ADR-0162 already records the two-skill split this change completes. The pinned-URL builder and the read operation follow existing patterns. + +## Out of scope + +- Private repositories (change #586) and automatic posting at each event (change #587). +- Using a team's own ticket skill for project-specific details (change #591). +- A native ticket web link; attachments. +- Mentions in automatic updates (whether those ever name anyone is change #587's decision). +- Syncing ticket status, assignee, sprint, or workflow; rewriting a ticket's description; inbound sync; deployment tracking; treating a merge as acceptance. +- A ledger, delivery-state tracking, a queue, retry, or exactly-once delivery. +- Any ticket-system call from this repository. + +## What the code says today + +Verified at main `6dacf9706`; anchors are symbols. + +- `internal/render/link.go` has `BlobURL` and `BlobURLOnBranch` (branch URLs only, empty for a private metadata branch); no commit-pinned builder. `render.LinkContext` is built only by `linkContextOf` (`internal/app/link_context.go`). +- `context.implementation` (`ImplementationContext` in `internal/app/implementation_context.go`) already carries `MetadataCommit` (from `metadataRevision`, the revision fetched from the metadata remote) and a `ContextTicket` (`provider`, `id`, `url`) built by `contextTicket`. +- The `tickets.provider`, `tickets.site`, `tickets.project`, and `tickets.auto.` keys exist in `buildRegistry` (`internal/config/schema.go`), all repo-only; the switches default to `false`. +- `change.link-ticket` writes the three ticket fields; `status --json --records` reports a `ticket` object for a linked change. +- `skills/docket-link-ticket/` (SKILL.md, `references/create.md`, `references/import.md`) is the pattern for an inline ticket skill with progressive disclosure. +- `skills/docket-export/SKILL.md` still carries the outside-tool example "add the spec for 9 as a comment on PROJ-123". From b57ead823ca83f3774deccda5982b388e809eab6 Mon Sep 17 00:00:00 2001 From: Daniel Hanold Date: Tue, 10 Nov 2026 08:00:04 -0500 Subject: [PATCH 2/9] feat(render): add a blob URL pinned to a commit --- internal/render/link.go | 11 +++++++++++ internal/render/link_test.go | 26 ++++++++++++++++++++++++++ 2 files changed, 37 insertions(+) diff --git a/internal/render/link.go b/internal/render/link.go index d0f0c7fa7..8d2e59438 100644 --- a/internal/render/link.go +++ b/internal/render/link.go @@ -52,3 +52,14 @@ func (l LinkContext) BlobURLOnBranch(repoRelPath, branch string) string { } return l.RepoWebURL + "/blob/" + branch + "/" + repoRelPath } + +// BlobURLAtCommit pins a link to one commit: RepoWebURL + "/blob/" + commit + +// "/" + repoRelPath. It returns "" when RepoWebURL or commit is empty (never a +// malformed "/blob//" URL), and for a private repository, whose metadata +// commit has no web page. +func (l LinkContext) BlobURLAtCommit(repoRelPath, commit string) string { + if l.RepoWebURL == "" || commit == "" || l.PrivateMetadata { + return "" + } + return l.RepoWebURL + "/blob/" + commit + "/" + repoRelPath +} diff --git a/internal/render/link_test.go b/internal/render/link_test.go index e71e09462..609717f3b 100644 --- a/internal/render/link_test.go +++ b/internal/render/link_test.go @@ -79,3 +79,29 @@ func TestBlobURLOnBranchWithoutRepoWebURL(t *testing.T) { t.Fatalf("BlobURLOnBranch with empty RepoWebURL = %q, want empty", got) } } + +func TestBlobURLAtCommit(t *testing.T) { + const commit = "3333333333333333333333333333333333333333" + const p = "docs/superpowers/specs/2026-11-08-x-design.md" + shared := render.LinkContext{RepoWebURL: "https://github.com/o/r", MetadataBranch: "docket", IntegrationBranch: "main"} + noWeb := shared + noWeb.RepoWebURL = "" + private := shared + private.PrivateMetadata = true + cases := []struct { + name string + ctx render.LinkContext + commit string + want string + }{ + {"shared full commit", shared, commit, "https://github.com/o/r/blob/" + commit + "/" + p}, + {"no repo web URL", noWeb, commit, ""}, + {"empty commit", shared, "", ""}, + {"private metadata", private, commit, ""}, + } + for _, c := range cases { + if got := c.ctx.BlobURLAtCommit(p, c.commit); got != c.want { + t.Errorf("%s: BlobURLAtCommit = %q, want %q", c.name, got, c.want) + } + } +} From 7ffea5f57d8ea34ba9eff9e171e35bacb30faf73 Mon Sep 17 00:00:00 2001 From: Daniel Hanold Date: Tue, 10 Nov 2026 08:07:07 -0500 Subject: [PATCH 3/9] feat(app): add the context.ticket read operation --- internal/app/link_context_guard_test.go | 2 +- internal/app/schema_registry_test.go | 1 + internal/app/ticket_context.go | 358 ++++++++++++++++++++++ internal/app/ticket_context_test.go | 376 ++++++++++++++++++++++++ 4 files changed, 736 insertions(+), 1 deletion(-) create mode 100644 internal/app/ticket_context.go create mode 100644 internal/app/ticket_context_test.go diff --git a/internal/app/link_context_guard_test.go b/internal/app/link_context_guard_test.go index ef0779dd9..f5e81a574 100644 --- a/internal/app/link_context_guard_test.go +++ b/internal/app/link_context_guard_test.go @@ -69,7 +69,7 @@ func TestLinkContextSoleConstructor(t *testing.T) { } // Floor = the call sites the swap installed; adjust ONLY upward when new // operations adopt the constructor. - const floor = 16 + const floor = 19 if calls < floor { t.Errorf("linkContextOf called %d times in production files, want >= %d — call sites deleted or bypassed", calls, floor) } diff --git a/internal/app/schema_registry_test.go b/internal/app/schema_registry_test.go index 7939ed28e..61f3ae991 100644 --- a/internal/app/schema_registry_test.go +++ b/internal/app/schema_registry_test.go @@ -109,6 +109,7 @@ var excludedResultTypes = map[string]string{ "LocalGateResult": "internal finalize gate seam return (RunLocalGate); carries no Envelope, is not an op document", "SweepPRSetResult": "internal batched-PR-read seam return (ProbePRSet); carries no Envelope, is not an op document", "RunVerdictObserveResult": "run.verdict's observe-mode (--unattributed) result variant; the op binds its attributed result RunVerdictResult", + "TicketContextResult": "context.ticket's result, not yet bound: its binding lands with its command, and this exclusion must be removed then (the honesty check below reddens once it is reachable)", "SchemaResult": "the schema document's own container; self-referential (FieldDescriptor nests []FieldDescriptor) and carries map[string]Vocabulary, so it is unreflectable and deliberately unbound — the wired `schema` op is the cli-side selfReferentialSchemaOps exception", } diff --git a/internal/app/ticket_context.go b/internal/app/ticket_context.go new file mode 100644 index 000000000..44bee4e51 --- /dev/null +++ b/internal/app/ticket_context.go @@ -0,0 +1,358 @@ +package app + +import ( + "context" + "fmt" + "slices" + + "github.com/danielhanold/docket/internal/domain" + "github.com/danielhanold/docket/internal/repository" +) + +// This file is the read-only `context ticket` operation: it gathers, from one +// pinned snapshot of the metadata branch, everything an agent needs to write a +// short update to a change's linked ticket — the change's identity and record +// path, its ticket link state, whether a named event has happened (and the +// effective tickets.auto switch for it), the PR and merge facts, and the spec +// and results artifacts with links pinned to the metadata commit. It works for +// any change, active or archived. "Not linked", "partial", "not happened", and +// "private" are reported, not refused: the caller decides what to do with +// them. Only a malformed request or a change id that names no single record is +// refused. It never mutates, never opens a transaction, and never calls a +// ticket system or GitHub. + +// OperationContextTicket is the operation key the ticket read records in its +// result envelope. +const OperationContextTicket = "context.ticket" + +// Event tokens (also the tickets.auto. keys). +const ( + TicketEventSpecWritten = "spec_written" + TicketEventPROpened = "pr_opened" + TicketEventPRMerged = "pr_merged" + TicketEventResultsCompleted = "results_completed" +) + +// Not-happened reasons an event verdict reports. +const ( + ReasonTicketNoSpec = "no-spec" + ReasonTicketNoPR = "no-pr" + ReasonTicketMergeNotRecorded = "merge-not-recorded" + ReasonTicketNotResultsArtifact = "not-results-artifact" + ReasonTicketNotCompleted = "not-completed" +) + +// Ticket link states. +const ( + TicketStateLinked = "linked" + TicketStateNotLinked = "not-linked" + TicketStatePartial = "partial" +) + +// Refusal reasons. An id claimed by more than one record reuses +// ReasonContextAmbiguousID (invalid-state). +const ( + // ReasonTicketMissingID: --id absent or not positive (invalid-input). + ReasonTicketMissingID = "missing-id" + // ReasonTicketUnknownEvent: --event is not exactly one of ticketEvents + // (invalid-input). + ReasonTicketUnknownEvent = "unknown-event" + // ReasonTicketNotFound: no record carries the id (invalid-input). + ReasonTicketNotFound = "not-found" +) + +// Ordered token lists; the skill guard iterates these so the skill and this +// producer cannot drift apart. +var ticketEvents = []string{TicketEventSpecWritten, TicketEventPROpened, TicketEventPRMerged, TicketEventResultsCompleted} +var ticketEventReasons = []string{ReasonTicketNoSpec, ReasonTicketNoPR, ReasonTicketMergeNotRecorded, ReasonTicketNotResultsArtifact, ReasonTicketNotCompleted} +var ticketStates = []string{TicketStateLinked, TicketStateNotLinked, TicketStatePartial} + +// TicketContextRequest is the closed request. Event "" is a no-event read. +type TicketContextRequest struct { + ID int `json:"id"` + Event string `json:"event,omitempty"` +} + +// TicketContextChange is the change's identity and its record's repo-relative +// path on the metadata branch. +type TicketContextChange struct { + ID int `json:"id"` + Slug string `json:"slug"` + Title string `json:"title"` + Status string `json:"status"` + Deliverable string `json:"deliverable"` + Path string `json:"path"` +} + +// TicketContextTicket is the change's ticket link state; provider, id, and url +// are set only when the state is linked. +type TicketContextTicket struct { + State string `json:"state"` + Provider string `json:"provider,omitempty"` + ID string `json:"id,omitempty"` + URL string `json:"url,omitempty"` +} + +// TicketContextEvent is the verdict for the requested event. Switch is the +// effective tickets.auto. value, reported for automatic posting and +// ignored on request. +type TicketContextEvent struct { + Name string `json:"name"` + Switch bool `json:"switch"` + Happened bool `json:"happened"` + Reason string `json:"reason,omitempty"` +} + +// TicketContextMerge is where a merged change landed. +type TicketContextMerge struct { + DestinationBranch string `json:"destination_branch"` + InIntegration bool `json:"in_integration"` +} + +// TicketContextFacts are the PR and merge facts the record carries. +type TicketContextFacts struct { + PRURL string `json:"pr_url"` + Merge *TicketContextMerge `json:"merge,omitempty"` +} + +// TicketContextArtifact is one spec or results artifact that exists at the +// metadata commit. URL is pinned to that commit, and empty in a private +// repository or with no repository web URL. +type TicketContextArtifact struct { + Role string `json:"role"` + Path string `json:"path"` + URL string `json:"url"` +} + +// TicketContext is the read's bundle; every fact derives from one pin. +type TicketContext struct { + MetadataCommit string `json:"metadata_commit"` + Visibility string `json:"visibility"` + Change TicketContextChange `json:"change"` + Ticket TicketContextTicket `json:"ticket"` + Event *TicketContextEvent `json:"event,omitempty"` + Facts TicketContextFacts `json:"facts"` + Artifacts []TicketContextArtifact `json:"artifacts"` + + // metadataRef names the metadata branch for the human summary only. + metadataRef string +} + +// TicketContextResult is the protocol-v1 document the operation returns. +type TicketContextResult struct { + Envelope + Context *TicketContext `json:"context,omitempty"` + Reason string `json:"reason,omitempty"` + Message string `json:"message,omitempty"` +} + +// HumanText renders the one-line human summary: identity, revision, ticket +// state, and the event verdict only — never a title, URL, or authored body. +func (r TicketContextResult) HumanText() string { + if r.Result == ResultApplied && r.Context != nil { + c := r.Context + line := fmt.Sprintf("%s: change %04d %s on %s@%s — ticket %s", + OperationContextTicket, c.Change.ID, c.Change.Slug, c.metadataRef, shortCommit(c.MetadataCommit), c.Ticket.State) + if e := c.Event; e != nil { + if e.Happened { + line += fmt.Sprintf("; event %s happened", e.Name) + } else { + line += fmt.Sprintf("; event %s not happened (%s)", e.Name, e.Reason) + } + } + return line + } + if r.Reason != "" { + return fmt.Sprintf("%s: %s (%s)", r.Operation, r.Result, r.Reason) + } + return fmt.Sprintf("%s: %s", r.Operation, r.Result) +} + +func newTicketContextResult(result Result, reason, message string, bundle *TicketContext) TicketContextResult { + if bundle != nil && bundle.Artifacts == nil { + bundle.Artifacts = []TicketContextArtifact{} + } + return TicketContextResult{ + Envelope: NewEnvelope(OperationContextTicket, result), + Context: bundle, + Reason: reason, + Message: message, + } +} + +// ContextTicketRead assembles the ticket-update bundle for one change. It is +// read-only: the request is validated before any read, then one pin, one corpus +// read, one snapshot. +func ContextTicketRead(ctx context.Context, deps PlanningDeps, repoDir string, req TicketContextRequest) TicketContextResult { + if req.ID <= 0 { + return newTicketContextResult(ResultInvalidInput, ReasonTicketMissingID, + "a positive change id is required", nil) + } + if req.Event != "" && !slices.Contains(ticketEvents, req.Event) { + return newTicketContextResult(ResultInvalidInput, ReasonTicketUnknownEvent, + fmt.Sprintf("unknown event %q; want one of %v", req.Event, ticketEvents), nil) + } + + pin, err := deps.Reader.PinContext(ctx, repoDir) + if err != nil { + result, reason := classifyStatusError(ctx, err) + return newTicketContextResult(result, reason, err.Error(), nil) + } + blobs, err := deps.Reader.ReadCorpus(ctx, pin) + if err != nil { + result, reason := classifyStatusError(ctx, err) + return newTicketContextResult(result, reason, err.Error(), nil) + } + inputs, _ := parseCorpus(blobs) + build, err := repository.BuildSnapshot(repository.BuildInput{Config: pin.Config.Effective, Documents: inputs}) + if err != nil { + return newTicketContextResult(ResultInternalError, ReasonStatusInternalError, err.Error(), nil) + } + snap := build.Snapshot + + c, out := snap.Change(domain.ChangeID(req.ID)) + switch out { + case domain.LookupAbsent: + return newTicketContextResult(ResultInvalidInput, ReasonTicketNotFound, + fmt.Sprintf("no change %04d is present in the corpus", req.ID), nil) + case domain.LookupAmbiguous: + return newTicketContextResult(ResultInvalidState, ReasonContextAmbiguousID, + fmt.Sprintf("more than one record claims change id %04d; refusing to choose", req.ID), nil) + } + + commit := metadataRevision(pin) + links := linkContextOf(pin) + var artifacts []TicketContextArtifact + for _, a := range []struct { + role string + field domain.OptionalString + }{{"spec", c.Spec()}, {"results", c.Results()}} { + if a.field.State != domain.FieldPresent || a.field.Value == "" { + continue + } + found, err := deps.Reader.ArtifactExists(ctx, pin, sourceMetadata, a.field.Value) + if err != nil { + result, reason := classifyStatusError(ctx, err) + return newTicketContextResult(result, reason, err.Error(), nil) + } + if !found { + continue + } + artifacts = append(artifacts, TicketContextArtifact{ + Role: a.role, + Path: a.field.Value, + URL: links.BlobURLAtCommit(a.field.Value, commit), + }) + } + + bundle := &TicketContext{ + MetadataCommit: commit, + Visibility: string(pin.Layout.Mode), + Change: TicketContextChange{ + ID: int(c.ID()), + Slug: c.Slug(), + Title: c.Title(), + Status: c.RawStatus(), + Deliverable: deliverableText(c), + Path: c.Path(), + }, + Ticket: ticketState(c), + Facts: TicketContextFacts{PRURL: presentValue(c.PR()), Merge: ticketMerge(snap, c, pin)}, + Artifacts: artifacts, + metadataRef: pin.Layout.MetadataBranch, + } + if req.Event != "" { + bundle.Event = ticketEvent(c, req.Event, pin) + } + return newTicketContextResult(ResultApplied, "", "", bundle) +} + +// presentValue is a field's value when present, else "". +func presentValue(f domain.OptionalString) string { + if f.State != domain.FieldPresent { + return "" + } + return f.Value +} + +// ticketState classifies the change's ticket link. +func ticketState(c domain.Change) TicketContextTicket { + if t, ok := c.Ticket(); ok { + return TicketContextTicket{State: TicketStateLinked, Provider: t.Provider, ID: t.ID, URL: t.URL} + } + if c.HasTicketFields() { + return TicketContextTicket{State: TicketStatePartial} + } + return TicketContextTicket{State: TicketStateNotLinked} +} + +// prMerged reports whether the change's PR has merged: a done PR change with a +// recorded pr:, or a stacked-merged change. +func prMerged(c domain.Change) bool { + switch c.Status() { + case domain.StatusStackedMerged: + return true + case domain.StatusDone: + return c.Deliverable() == domain.DeliverablePR && presentValue(c.PR()) != "" + } + return false +} + +// ticketMerge reports where a merged change landed, or nil when it has not +// merged. A stacked-merged change landed on its parent's recorded branch ("" when +// the parent does not resolve). +func ticketMerge(snap domain.Snapshot, c domain.Change, pin StatusPin) *TicketContextMerge { + if !prMerged(c) { + return nil + } + if c.Status() == domain.StatusStackedMerged { + dest := "" + if parent, out := domain.StackParent(snap, c); out == domain.LookupFound { + dest = presentValue(parent.Branch()) + } + return &TicketContextMerge{DestinationBranch: dest, InIntegration: false} + } + integration := pin.IntegrationBranch + if integration == "" { + integration = pin.DefaultBranch + } + return &TicketContextMerge{DestinationBranch: integration, InIntegration: true} +} + +// ticketEvent is the verdict for one (already validated) event token. +func ticketEvent(c domain.Change, name string, pin StatusPin) *TicketContextEvent { + auto := pin.Config.Effective.Tickets.Auto + e := &TicketContextEvent{Name: name} + hasPR := presentValue(c.PR()) != "" + switch name { + case TicketEventSpecWritten: + e.Switch = auto.SpecWritten.Value + if presentValue(c.Spec()) == "" { + e.Reason = ReasonTicketNoSpec + } + case TicketEventPROpened: + e.Switch = auto.PROpened.Value + if !hasPR { + e.Reason = ReasonTicketNoPR + } + case TicketEventPRMerged: + e.Switch = auto.PRMerged.Value + switch { + case prMerged(c): + case !hasPR: + e.Reason = ReasonTicketNoPR + default: + e.Reason = ReasonTicketMergeNotRecorded + } + case TicketEventResultsCompleted: + e.Switch = auto.ResultsCompleted.Value + switch { + case c.Deliverable() != domain.DeliverableResultsArtifact: + e.Reason = ReasonTicketNotResultsArtifact + case c.Status() != domain.StatusDone: + e.Reason = ReasonTicketNotCompleted + } + } + e.Happened = e.Reason == "" + return e +} diff --git a/internal/app/ticket_context_test.go b/internal/app/ticket_context_test.go new file mode 100644 index 000000000..2cb0cfe4c --- /dev/null +++ b/internal/app/ticket_context_test.go @@ -0,0 +1,376 @@ +package app + +import ( + "context" + "encoding/json" + "fmt" + "reflect" + "strings" + "testing" + + "github.com/danielhanold/docket/internal/layout" + "github.com/danielhanold/docket/internal/repository" +) + +// --- fixtures ------------------------------------------------------------- + +// ticketRecordBlob builds an active change record with the given status and extra frontmatter lines. +func ticketRecordBlob(id int, slug, status, extra string) StatusBlob { + fm := fmt.Sprintf("---\nid: %d\nslug: %s\ntitle: Change %d\nstatus: '%s'\npriority: medium\ntype: feat\ncreated: 2026-01-02\n%s---\n\nBody of %d.\n", + id, slug, id, status, extra, id) + return StatusBlob{ + Kind: repository.KindChange, + Location: repository.LocationActive, + Path: fmt.Sprintf("docs/changes/active/%04d-%s.md", id, slug), + Revision: fmt.Sprintf("blobchange%04d", id), + Data: []byte(fm), + } +} + +const ( + ticketSpecPath = "docs/superpowers/specs/2026-11-08-x-design.md" + ticketResultsPath = "docs/superpowers/results/2026-11-08-x-results.md" + ticketPlanPath = "docs/superpowers/plans/2026-11-08-x.md" + ticketPR = "https://github.com/acme/widgets/pull/9" + ticketBlobBase = "https://github.com/acme/widgets/blob/3333333333333333333333333333333333333333/" +) + +func ticketPin(t *testing.T) StatusPin { + t.Helper() + pin := docketPin(t) + pin.RepoWebURL = "https://github.com/acme/widgets" + return pin +} + +// readTicket runs the operation over a corpus with the given pin and present +// metadata artifacts. +func readTicket(t *testing.T, pin StatusPin, corpus []StatusBlob, present []string, req TicketContextRequest) (TicketContextResult, *fakeReader) { + t.Helper() + arts := map[string]bool{} + for _, p := range present { + arts[sourceMetadata+"|"+p] = true + } + fake := &fakeReader{pin: pin, corpus: corpus, artifacts: arts} + return ContextTicketRead(context.Background(), contextDeps(fake), "", req), fake +} + +func mustApplied(t *testing.T, got TicketContextResult) *TicketContext { + t.Helper() + if got.Result != ResultApplied || got.Context == nil { + t.Fatalf("result=%q reason=%q message=%q", got.Result, got.Reason, got.Message) + } + return got.Context +} + +func mustJSON(t *testing.T, v any) string { + t.Helper() + b, err := json.Marshal(v) + if err != nil { + t.Fatal(err) + } + return string(b) +} + +// --- tests ---------------------------------------------------------------- + +func TestContextTicketEventsHappened(t *testing.T) { + cases := []struct { + event string + blob StatusBlob + }{ + {TicketEventSpecWritten, ticketRecordBlob(1, "a", "proposed", "spec: "+ticketSpecPath+"\n")}, + {TicketEventPROpened, ticketRecordBlob(1, "a", "implemented", "pr: '"+ticketPR+"'\n")}, + {TicketEventPRMerged, ticketRecordBlob(1, "a", "done", "pr: '"+ticketPR+"'\n")}, + {TicketEventResultsCompleted, ticketRecordBlob(1, "a", "done", "deliverable: results-artifact\nresults: "+ticketResultsPath+"\n")}, + } + for _, tc := range cases { + t.Run(tc.event, func(t *testing.T) { + got, _ := readTicket(t, ticketPin(t), []StatusBlob{tc.blob}, nil, TicketContextRequest{ID: 1, Event: tc.event}) + c := mustApplied(t, got) + if c.Event == nil || c.Event.Name != tc.event || !c.Event.Happened || c.Event.Reason != "" { + t.Errorf("event = %+v, want %s happened", c.Event, tc.event) + } + }) + } +} + +func TestContextTicketEventsNotHappened(t *testing.T) { + cases := []struct { + name, event, reason string + blob StatusBlob + }{ + {"spec_written without spec", TicketEventSpecWritten, ReasonTicketNoSpec, ticketRecordBlob(1, "a", "proposed", "")}, + {"pr_opened without pr", TicketEventPROpened, ReasonTicketNoPR, ticketRecordBlob(1, "a", "proposed", "spec: "+ticketSpecPath+"\n")}, + {"pr_merged on implemented", TicketEventPRMerged, ReasonTicketMergeNotRecorded, ticketRecordBlob(1, "a", "implemented", "pr: '"+ticketPR+"'\n")}, + {"pr_merged on proposed", TicketEventPRMerged, ReasonTicketNoPR, ticketRecordBlob(1, "a", "proposed", "")}, + {"results_completed on pr change", TicketEventResultsCompleted, ReasonTicketNotResultsArtifact, ticketRecordBlob(1, "a", "done", "pr: '"+ticketPR+"'\n")}, + {"results_completed in progress", TicketEventResultsCompleted, ReasonTicketNotCompleted, + ticketRecordBlob(1, "a", "in-progress", "deliverable: results-artifact\nbranch: 'feat/a'\nclaimed_at: '2026-01-03T00:00:00Z'\n")}, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + got, _ := readTicket(t, ticketPin(t), []StatusBlob{tc.blob}, nil, TicketContextRequest{ID: 1, Event: tc.event}) + c := mustApplied(t, got) + if c.Event == nil || c.Event.Happened || c.Event.Reason != tc.reason { + t.Errorf("event = %+v, want not happened (%s)", c.Event, tc.reason) + } + }) + } +} + +func TestContextTicketKilledChange(t *testing.T) { + cases := []struct { + event string + extra string + happened bool + }{ + {TicketEventPRMerged, "pr: '" + ticketPR + "'\nspec: " + ticketSpecPath + "\n", false}, + {TicketEventResultsCompleted, "deliverable: results-artifact\nspec: " + ticketSpecPath + "\n", false}, + {TicketEventSpecWritten, "pr: '" + ticketPR + "'\nspec: " + ticketSpecPath + "\n", true}, + } + for _, tc := range cases { + t.Run(tc.event, func(t *testing.T) { + blob := ticketRecordBlob(1, "a", "killed", tc.extra) + got, _ := readTicket(t, ticketPin(t), []StatusBlob{blob}, nil, TicketContextRequest{ID: 1, Event: tc.event}) + c := mustApplied(t, got) + if c.Event == nil || c.Event.Happened != tc.happened { + t.Errorf("event = %+v, want happened=%t", c.Event, tc.happened) + } + }) + } +} + +func TestContextTicketMergeFacts(t *testing.T) { + parent := ticketRecordBlob(20, "parent", "implemented", "branch: 'feat/parent'\npr: 'https://github.com/acme/widgets/pull/1'\n") + cases := []struct { + name string + blob StatusBlob + want *TicketContextMerge + }{ + {"done", ticketRecordBlob(1, "a", "done", "pr: '"+ticketPR+"'\n"), &TicketContextMerge{DestinationBranch: "main", InIntegration: true}}, + {"stacked-merged", ticketRecordBlob(1, "a", "stacked-merged", "stacked_on: 20\npr: '"+ticketPR+"'\n"), &TicketContextMerge{DestinationBranch: "feat/parent", InIntegration: false}}, + {"implemented", ticketRecordBlob(1, "a", "implemented", "pr: '"+ticketPR+"'\n"), nil}, + } + for _, tc := range cases { + for _, event := range []string{"", TicketEventPRMerged} { + t.Run(tc.name+"/event="+event, func(t *testing.T) { + got, _ := readTicket(t, ticketPin(t), []StatusBlob{tc.blob, parent}, nil, TicketContextRequest{ID: 1, Event: event}) + c := mustApplied(t, got) + if !reflect.DeepEqual(c.Facts.Merge, tc.want) { + t.Errorf("merge = %+v, want %+v", c.Facts.Merge, tc.want) + } + if c.Facts.PRURL != ticketPR { + t.Errorf("pr_url = %q, want %q", c.Facts.PRURL, ticketPR) + } + }) + } + } +} + +func TestContextTicketStackedMergedParentMissing(t *testing.T) { + blob := ticketRecordBlob(1, "a", "stacked-merged", "stacked_on: 99\npr: '"+ticketPR+"'\n") + got, _ := readTicket(t, ticketPin(t), []StatusBlob{blob}, nil, TicketContextRequest{ID: 1, Event: TicketEventPRMerged}) + c := mustApplied(t, got) + if c.Event == nil || !c.Event.Happened { + t.Errorf("event = %+v, want pr_merged happened", c.Event) + } + if c.Facts.Merge == nil || c.Facts.Merge.InIntegration || c.Facts.Merge.DestinationBranch != "" { + t.Errorf("merge = %+v, want {\"\", false}", c.Facts.Merge) + } +} + +func TestContextTicketTicketStates(t *testing.T) { + cases := []struct { + name string + extra string + want TicketContextTicket + }{ + {"linked", "ticket_provider: jira\nticket_id: 'CLOUD-123'\nticket_url: 'https://acme.atlassian.net/browse/CLOUD-123'\n", + TicketContextTicket{State: TicketStateLinked, Provider: "jira", ID: "CLOUD-123", URL: "https://acme.atlassian.net/browse/CLOUD-123"}}, + {"partial fields", "ticket_provider: jira\nticket_id: 'CLOUD-123'\n", TicketContextTicket{State: TicketStatePartial}}, + {"invalid url", "ticket_provider: jira\nticket_id: 'CLOUD-123'\nticket_url: 'javascript:x'\n", TicketContextTicket{State: TicketStatePartial}}, + {"not linked", "", TicketContextTicket{State: TicketStateNotLinked}}, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + got, _ := readTicket(t, ticketPin(t), []StatusBlob{ticketRecordBlob(1, "a", "proposed", tc.extra)}, nil, TicketContextRequest{ID: 1}) + c := mustApplied(t, got) + if c.Ticket != tc.want { + t.Errorf("ticket = %+v, want %+v", c.Ticket, tc.want) + } + }) + } + if s := mustJSON(t, TicketContextTicket{State: TicketStateNotLinked}); s != `{"state":"not-linked"}` { + t.Errorf("not-linked ticket JSON = %s", s) + } +} + +func TestContextTicketSharedPinnedURLs(t *testing.T) { + pin := ticketPin(t) + blob := ticketRecordBlob(1, "a", "proposed", "spec: "+ticketSpecPath+"\nresults: "+ticketResultsPath+"\n") + got, _ := readTicket(t, pin, []StatusBlob{blob}, []string{ticketSpecPath, ticketResultsPath}, TicketContextRequest{ID: 1}) + c := mustApplied(t, got) + want := []TicketContextArtifact{ + {Role: "spec", Path: ticketSpecPath, URL: ticketBlobBase + ticketSpecPath}, + {Role: "results", Path: ticketResultsPath, URL: ticketBlobBase + ticketResultsPath}, + } + if !reflect.DeepEqual(c.Artifacts, want) { + t.Errorf("artifacts = %+v\nwant %+v", c.Artifacts, want) + } + if c.MetadataCommit != pin.MetadataRevision { + t.Errorf("metadata_commit = %q, want %q", c.MetadataCommit, pin.MetadataRevision) + } + if c.Visibility != "shared" { + t.Errorf("visibility = %q, want shared", c.Visibility) + } +} + +func TestContextTicketPrivateEmptyURLs(t *testing.T) { + pin := ticketPin(t) + pin.Layout = layout.PrivateLayout("/c", "/r", "/d", "o-r") + blob := ticketRecordBlob(1, "a", "proposed", "spec: "+ticketSpecPath+"\nresults: "+ticketResultsPath+"\n") + got, _ := readTicket(t, pin, []StatusBlob{blob}, []string{ticketSpecPath, ticketResultsPath}, TicketContextRequest{ID: 1}) + c := mustApplied(t, got) + if c.Visibility != "private" { + t.Errorf("visibility = %q, want private", c.Visibility) + } + if len(c.Artifacts) != 2 { + t.Fatalf("artifacts = %+v, want spec and results", c.Artifacts) + } + for _, a := range c.Artifacts { + if a.URL != "" { + t.Errorf("artifact %s URL = %q, want empty in a private repository", a.Role, a.URL) + } + } +} + +func TestContextTicketNeverReportsPlan(t *testing.T) { + blob := ticketRecordBlob(1, "a", "proposed", "spec: "+ticketSpecPath+"\nplan: "+ticketPlanPath+"\nresults: "+ticketResultsPath+"\n") + got, fake := readTicket(t, ticketPin(t), []StatusBlob{blob}, []string{ticketSpecPath, ticketPlanPath, ticketResultsPath}, TicketContextRequest{ID: 1}) + c := mustApplied(t, got) + for _, a := range c.Artifacts { + if a.Role == "plan" || a.Path == ticketPlanPath { + t.Errorf("artifacts report the plan: %+v", a) + } + } + for _, ask := range fake.artifactAsks { + if strings.Contains(ask, ticketPlanPath) { + t.Errorf("the plan path was read: %s", ask) + } + } +} + +func TestContextTicketMissingArtifactOmitted(t *testing.T) { + blob := ticketRecordBlob(1, "a", "proposed", "spec: "+ticketSpecPath+"\n") + got, _ := readTicket(t, ticketPin(t), []StatusBlob{blob}, nil, TicketContextRequest{ID: 1, Event: TicketEventSpecWritten}) + c := mustApplied(t, got) + if c.Event == nil || !c.Event.Happened { + t.Errorf("event = %+v, want spec_written happened", c.Event) + } + if c.Artifacts == nil || len(c.Artifacts) != 0 { + t.Errorf("artifacts = %#v, want empty non-nil", c.Artifacts) + } + if s := mustJSON(t, got); !strings.Contains(s, `"artifacts":[]`) { + t.Errorf("JSON lacks \"artifacts\":[]: %s", s) + } +} + +func TestContextTicketArchivedChange(t *testing.T) { + path := "docs/changes/archive/2026-08-16-0042-old.md" + blob := ticketRecordBlob(42, "old", "done", "pr: '"+ticketPR+"'\n") + blob.Location = repository.LocationArchive + blob.Path = path + got, _ := readTicket(t, ticketPin(t), []StatusBlob{blob}, nil, TicketContextRequest{ID: 42}) + c := mustApplied(t, got) + if c.Change.Path != path || c.Change.Status != "done" { + t.Errorf("change = %+v, want path %s status done", c.Change, path) + } +} + +func TestContextTicketNoEventRead(t *testing.T) { + blob := ticketRecordBlob(1, "a", "done", "spec: "+ticketSpecPath+"\npr: '"+ticketPR+"'\nticket_provider: jira\nticket_id: 'CLOUD-1'\nticket_url: 'https://acme.atlassian.net/browse/CLOUD-1'\n") + got, _ := readTicket(t, ticketPin(t), []StatusBlob{blob}, []string{ticketSpecPath}, TicketContextRequest{ID: 1}) + c := mustApplied(t, got) + if c.Event != nil { + t.Errorf("event = %+v, want nil", c.Event) + } + if s := mustJSON(t, got); strings.Contains(s, `"event"`) { + t.Errorf("JSON carries an event key: %s", s) + } + if c.Ticket.State != TicketStateLinked || c.Facts.PRURL != ticketPR || c.Facts.Merge == nil || len(c.Artifacts) != 1 { + t.Errorf("no-event read dropped facts: ticket=%+v facts=%+v artifacts=%+v", c.Ticket, c.Facts, c.Artifacts) + } +} + +func TestContextTicketSwitchReported(t *testing.T) { + pin := ticketPin(t) + pin.Config.Effective.Tickets.Auto.PROpened.Value = true + blob := ticketRecordBlob(1, "a", "implemented", "spec: "+ticketSpecPath+"\npr: '"+ticketPR+"'\n") + got, _ := readTicket(t, pin, []StatusBlob{blob}, nil, TicketContextRequest{ID: 1, Event: TicketEventPROpened}) + if c := mustApplied(t, got); !c.Event.Switch { + t.Errorf("pr_opened switch = false, want true") + } + got, _ = readTicket(t, pin, []StatusBlob{blob}, nil, TicketContextRequest{ID: 1, Event: TicketEventSpecWritten}) + if c := mustApplied(t, got); c.Event.Switch { + t.Errorf("spec_written switch = true, want false") + } +} + +func TestContextTicketRefusals(t *testing.T) { + cases := []struct { + name string + corpus []StatusBlob + id int + wantResult Result + wantReason string + }{ + {"missing id", []StatusBlob{ticketRecordBlob(1, "a", "proposed", "")}, 0, ResultInvalidInput, ReasonTicketMissingID}, + {"absent", []StatusBlob{ticketRecordBlob(1, "a", "proposed", "")}, 404, ResultInvalidInput, ReasonTicketNotFound}, + {"ambiguous", []StatusBlob{ticketRecordBlob(7, "one", "proposed", ""), ticketRecordBlob(7, "two", "proposed", "")}, 7, ResultInvalidState, ReasonContextAmbiguousID}, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + got, _ := readTicket(t, ticketPin(t), tc.corpus, nil, TicketContextRequest{ID: tc.id}) + if got.Result != tc.wantResult || got.Reason != tc.wantReason || got.Context != nil { + t.Errorf("got %q/%q context=%v, want %q/%q and no context", got.Result, got.Reason, got.Context, tc.wantResult, tc.wantReason) + } + if got.Operation != OperationContextTicket { + t.Errorf("operation = %q", got.Operation) + } + }) + } +} + +func TestContextTicketUnknownEventRefusedBeforeRead(t *testing.T) { + for _, event := range []string{"PR_OPENED", "pr-opened", " pr_opened", "change_created"} { + t.Run(event, func(t *testing.T) { + got, fake := readTicket(t, ticketPin(t), []StatusBlob{ticketRecordBlob(1, "a", "implemented", "pr: '"+ticketPR+"'\n")}, nil, + TicketContextRequest{ID: 1, Event: event}) + if got.Result != ResultInvalidInput || got.Reason != ReasonTicketUnknownEvent || got.Context != nil { + t.Errorf("got %q/%q, want invalid-input/unknown-event", got.Result, got.Reason) + } + if fake.pinCount != 0 { + t.Errorf("PinContext called %d times, want 0", fake.pinCount) + } + }) + } +} + +func TestContextTicketNoNullAndNoBody(t *testing.T) { + ticketURL := "https://acme.atlassian.net/browse/CLOUD-5" + blob := ticketRecordBlob(5, "five", "implemented", "spec: "+ticketSpecPath+"\npr: '"+ticketPR+"'\nticket_provider: jira\nticket_id: 'CLOUD-5'\nticket_url: '"+ticketURL+"'\n") + got, _ := readTicket(t, ticketPin(t), []StatusBlob{blob}, []string{ticketSpecPath}, TicketContextRequest{ID: 5, Event: TicketEventPROpened}) + mustApplied(t, got) + if s := mustJSON(t, got); strings.Contains(s, "null") { + t.Errorf("JSON contains null: %s", s) + } + h := got.HumanText() + for _, banned := range []string{"Change 5", "Body of", ticketURL, ticketPR} { + if strings.Contains(h, banned) { + t.Errorf("HumanText %q contains %q", h, banned) + } + } + if !strings.Contains(h, "0005 five") || !strings.Contains(h, "ticket linked") || !strings.Contains(h, "event pr_opened happened") { + t.Errorf("HumanText %q lacks identity or verdicts", h) + } +} From bc0c097740becd884211bf32a7c7d03cde7bc52e Mon Sep 17 00:00:00 2001 From: Daniel Hanold Date: Tue, 10 Nov 2026 08:08:58 -0500 Subject: [PATCH 4/9] feat(cli): add the context ticket command --- docs/reference/cli.md | 2 +- internal/app/schema_registry.go | 1 + internal/app/schema_registry_test.go | 1 - internal/cli/context.go | 28 +++++++++++++-- internal/cli/context_test.go | 53 +++++++++++++++++++++++++++- internal/cli/install.go | 1 + 6 files changed, 81 insertions(+), 5 deletions(-) diff --git a/docs/reference/cli.md b/docs/reference/cli.md index 15b303b9d..7fc58ad24 100644 --- a/docs/reference/cli.md +++ b/docs/reference/cli.md @@ -28,7 +28,7 @@ Each line is a pointer: the command, what its verbs govern, and where to read th repository-independent). Verbs: `docket capabilities --help`. - **`docket change`** — create and transition changes in the backlog. Verbs: `docket change --help` (`docket schema` lists the request keys, including `hold`). -- **`docket context`** — assemble read-only context bundles for the implementation workflow. Verbs: `docket context --help`. +- **`docket context`** — assemble read-only context bundles for docket workflows (implementation, finalize, ticket updates). Verbs: `docket context --help`. - **`docket development`** — contributor operations against a docket checkout: install from a checkout and run the complete test suite. Verbs: `docket development --help`. - **`docket diagnostic`** — read-only diagnostics, including the resolved configuration diff --git a/internal/app/schema_registry.go b/internal/app/schema_registry.go index 8b626a995..0e55bfae9 100644 --- a/internal/app/schema_registry.go +++ b/internal/app/schema_registry.go @@ -67,6 +67,7 @@ var operationBindings = []OperationBinding{ {ID: "change.unblock", Request: ChangeUnblockRequest{}, Result: ChangeLifecycleResult{}}, // ChangeUnblock {ID: "context.finalize", Request: nil, Result: FinalizeContextResult{}}, // ContextFinalize {ID: "context.implementation", Request: nil, Result: ImplementationContextResult{}}, // ContextImplementation + {ID: "context.ticket", Request: nil, Result: TicketContextResult{}}, // ContextTicketRead {ID: "development.install", Request: nil, Result: InstallResult{}}, // RunDevelopmentInstall {ID: "diagnostic.config", Request: nil, Result: ConfigInspectionResult{}}, // DiagnosticConfig {ID: "diagnostic.runtime", Request: nil, Result: RuntimeResult{}}, // DiagnosticRuntime diff --git a/internal/app/schema_registry_test.go b/internal/app/schema_registry_test.go index 61f3ae991..7939ed28e 100644 --- a/internal/app/schema_registry_test.go +++ b/internal/app/schema_registry_test.go @@ -109,7 +109,6 @@ var excludedResultTypes = map[string]string{ "LocalGateResult": "internal finalize gate seam return (RunLocalGate); carries no Envelope, is not an op document", "SweepPRSetResult": "internal batched-PR-read seam return (ProbePRSet); carries no Envelope, is not an op document", "RunVerdictObserveResult": "run.verdict's observe-mode (--unattributed) result variant; the op binds its attributed result RunVerdictResult", - "TicketContextResult": "context.ticket's result, not yet bound: its binding lands with its command, and this exclusion must be removed then (the honesty check below reddens once it is reachable)", "SchemaResult": "the schema document's own container; self-referential (FieldDescriptor nests []FieldDescriptor) and carries map[string]Vocabulary, so it is unreflectable and deliberately unbound — the wired `schema` op is the cli-side selfReferentialSchemaOps exception", } diff --git a/internal/cli/context.go b/internal/cli/context.go index 025d689a2..337b89711 100644 --- a/internal/cli/context.go +++ b/internal/cli/context.go @@ -21,7 +21,7 @@ import ( func newContextCommand(setResult func(app.OperationResult)) *cobra.Command { contextCmd := &cobra.Command{ Use: "context", - Short: "Assemble read-only context bundles for the implementation workflow", + Short: "Assemble read-only context bundles for docket workflows", // A command group resolves its subcommand before Args runs, so anything // reaching here named no subcommand; NoArgs names an offending token and // the bare `docket context` falls through to RunE's missing-command error. @@ -77,6 +77,30 @@ func newContextCommand(setResult func(app.OperationResult)) *cobra.Command { finalize.Flags().Int("id", 0, "inspect this exact change `id` instead of applying the selection policy") finalize.Flags().IntSlice("allowlist", nil, "bound the finalize selection to these change `id`s (repeatable/comma-separated)") - contextCmd.AddCommand(implementation, finalize) + ticket := &cobra.Command{ + Use: "ticket", + Short: "Assemble what a ticket update needs for one change (read-only)", + Args: cobra.NoArgs, + Annotations: capability("context.ticket", EffectRead), + RunE: func(c *cobra.Command, _ []string) error { + repoDir, err := resolveRepoDir(c) + if err != nil { + return err + } + id, _ := c.Flags().GetInt("id") + event, _ := c.Flags().GetString("event") + deps, err := newPlanningDeps() + if err != nil { + return err + } + setResult(app.ContextTicketRead(c.Context(), deps, repoDir, app.TicketContextRequest{ID: id, Event: event})) + return nil + }, + } + ticket.Flags().String("repo-dir", "", "repository `dir` to read (default: current directory)") + ticket.Flags().Int("id", 0, "the change `id` to read") + ticket.Flags().String("event", "", "the `event` the update follows: spec_written, pr_opened, pr_merged, or results_completed; omit for an update with no event") + + contextCmd.AddCommand(implementation, finalize, ticket) return contextCmd } diff --git a/internal/cli/context_test.go b/internal/cli/context_test.go index 8c8d228b5..26e80103e 100644 --- a/internal/cli/context_test.go +++ b/internal/cli/context_test.go @@ -80,7 +80,7 @@ func TestContextImplementationHumanMode(t *testing.T) { // context commands read the repository, never installed assets, so they must be // asset-independent (not refused on a machine with no installation). func TestContextCommandsAssetIndependent(t *testing.T) { - for _, key := range []string{"context", "context implementation", "context finalize"} { + for _, key := range []string{"context", "context implementation", "context finalize", "context ticket"} { if !assetIndependent[key] { t.Errorf("%q is not registered asset-independent", key) } @@ -138,3 +138,54 @@ func TestContextFinalizeRoutesFlags(t *testing.T) { t.Fatalf("non-integer --id not rejected as an argument error: err=%q code=%d", errBad, codeBad) } } + +// TestContextTicketRegistered: `docket context ticket` is registered under the +// `context` group carrying --id, --event, and --repo-dir flags, annotated as the +// read-only context.ticket operation. +func TestContextTicketRegistered(t *testing.T) { + root := captureTree(t) + + cmd, _, err := root.Find([]string{"context", "ticket"}) + if err != nil || cmd == nil || cmd.Name() != "ticket" { + t.Fatalf("context ticket not registered: cmd=%v err=%v", cmd, err) + } + for _, flag := range []string{"id", "event", "repo-dir"} { + if cmd.Flags().Lookup(flag) == nil { + t.Errorf("context ticket: missing --%s flag", flag) + } + } + if got := cmd.Annotations[capAnnotationID]; got != "context.ticket" { + t.Errorf("capability id = %q, want context.ticket", got) + } + if got := cmd.Annotations[capAnnotationEffects]; got != string(EffectRead) { + t.Errorf("effects = %q, want exactly %q", got, EffectRead) + } +} + +// TestContextTicketCLIRejectsUnknownEvent: an --event outside the closed set is +// refused as a typed invalid-input document, before any repository read. +func TestContextTicketCLIRejectsUnknownEvent(t *testing.T) { + out, _, _ := runCLI(t, "context", "ticket", "--id", "7", "--event", "pr-opened", "--repo-dir", testsupport.TempDir(t), "--json") + for _, want := range []string{`"operation":"context.ticket"`, `"result":"invalid-input"`, `"reason":"unknown-event"`} { + if !strings.Contains(out, want) { + t.Errorf("document missing %s: %q", want, out) + } + } +} + +// TestContextTicketCLIEnvelope is the JSON-mode wiring assertion: the command +// reaches app.ContextTicketRead, which — against a non-repository directory — +// returns exactly one protocol-v1 document naming the operation, not a cobra +// error. +func TestContextTicketCLIEnvelope(t *testing.T) { + out, errS, code := runCLI(t, "context", "ticket", "--id", "7", "--event", "pr_opened", "--repo-dir", testsupport.TempDir(t), "--json") + if errS != "" { + t.Fatalf("unexpected stderr %q (code=%d)", errS, code) + } + if !strings.Contains(out, `"operation":"context.ticket"`) { + t.Fatalf("document did not name the operation: %q", out) + } + if strings.Count(out, "\n") != 1 || !strings.HasSuffix(out, "\n") { + t.Fatalf("must be exactly one newline-terminated document, got %q", out) + } +} diff --git a/internal/cli/install.go b/internal/cli/install.go index fcb66f3e5..7800536a1 100644 --- a/internal/cli/install.go +++ b/internal/cli/install.go @@ -56,6 +56,7 @@ var assetIndependent = map[string]bool{ "context": true, // the group itself; it reports a missing command "context implementation": true, "context finalize": true, + "context ticket": true, "workspace": true, // the group itself; it reports a missing command "workspace prepare": true, "workspace commit-spec": true, From 4684b4348ce45d154cead30e93b52abc1c6e03c0 Mon Sep 17 00:00:00 2001 From: Daniel Hanold Date: Tue, 10 Nov 2026 08:11:53 -0500 Subject: [PATCH 5/9] feat(skills): add docket-update-ticket for on-request ticket updates --- internal/app/ticket_context_skill_test.go | 32 ++++++ internal/assets/embedded/manifest.json | 16 ++- .../tree/skills/docket-update-ticket/SKILL.md | 98 +++++++++++++++++++ .../docket-update-ticket/references/shared.md | 9 ++ internal/harness/inventory_test.go | 2 +- internal/repoguard/budgets_test.go | 2 + internal/repoguard/prose_contracts_test.go | 36 +++++++ .../repoguard/update_ticket_skill_test.go | 33 +++++++ skills/docket-update-ticket/SKILL.md | 98 +++++++++++++++++++ .../docket-update-ticket/references/shared.md | 9 ++ 10 files changed, 333 insertions(+), 2 deletions(-) create mode 100644 internal/app/ticket_context_skill_test.go create mode 100644 internal/assets/embedded/tree/skills/docket-update-ticket/SKILL.md create mode 100644 internal/assets/embedded/tree/skills/docket-update-ticket/references/shared.md create mode 100644 internal/repoguard/update_ticket_skill_test.go create mode 100644 skills/docket-update-ticket/SKILL.md create mode 100644 skills/docket-update-ticket/references/shared.md diff --git a/internal/app/ticket_context_skill_test.go b/internal/app/ticket_context_skill_test.go new file mode 100644 index 000000000..3c2f4112c --- /dev/null +++ b/internal/app/ticket_context_skill_test.go @@ -0,0 +1,32 @@ +package app + +import ( + "os" + "path/filepath" + "strings" + "testing" +) + +// TestUpdateTicketSkillNamesEveryReadToken: every event, not-happened reason, and +// ticket state context.ticket can report appears in the skill in backticks, so a +// token renamed in Go reddens here instead of leaving the skill unable to act on it. +func TestUpdateTicketSkillNamesEveryReadToken(t *testing.T) { + path := filepath.Join("..", "..", "skills", "docket-update-ticket", "SKILL.md") + raw, err := os.ReadFile(path) + if err != nil { + t.Fatalf("read %s: %v", path, err) + } + body := string(raw) + var tokens []string + tokens = append(tokens, ticketEvents...) + tokens = append(tokens, ticketEventReasons...) + tokens = append(tokens, ticketStates...) + if len(tokens) != 12 { + t.Fatalf("context.ticket reports %d tokens, want 12 (4 events, 5 reasons, 3 states); update this guard with the producer", len(tokens)) + } + for _, tok := range tokens { + if !strings.Contains(body, "`"+tok+"`") { + t.Errorf("skills/docket-update-ticket/SKILL.md never names `%s`, which context.ticket can report", tok) + } + } +} diff --git a/internal/assets/embedded/manifest.json b/internal/assets/embedded/manifest.json index 4e46a8f53..3232b82e7 100644 --- a/internal/assets/embedded/manifest.json +++ b/internal/assets/embedded/manifest.json @@ -1,7 +1,7 @@ { "format_version": 1, "asset_protocol": 1, - "asset_set_id": "sha256:60e11b79e6262da8e8592ee230c6cd01bdfaef596f5a937409b1c9d11219d411", + "asset_set_id": "sha256:f1456a07769b968fd591984596659568068d03cfbbe1049182e795484be41c8c", "entries": [ { "path": ".docket.example.yml", @@ -457,6 +457,20 @@ "mode": 420, "size": 19874, "sha256": "5a326131973da1925bb1a5ada12ed520ab20d998fbad396cf971026a000faf59" + }, + { + "path": "skills/docket-update-ticket/SKILL.md", + "role": "skill", + "mode": 420, + "size": 9031, + "sha256": "095912c1560777e798648882ea5667fe77484a473ceea5e24ed039bbe51b8cea" + }, + { + "path": "skills/docket-update-ticket/references/shared.md", + "role": "skill", + "mode": 420, + "size": 1074, + "sha256": "a43221c8ffc82fa54c22de933a4d1c84c0183fd1f629a65c5382d9de58add62e" } ] } diff --git a/internal/assets/embedded/tree/skills/docket-update-ticket/SKILL.md b/internal/assets/embedded/tree/skills/docket-update-ticket/SKILL.md new file mode 100644 index 000000000..4ea7498de --- /dev/null +++ b/internal/assets/embedded/tree/skills/docket-update-ticket/SKILL.md @@ -0,0 +1,98 @@ +--- +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.' +--- + +# 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. + +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. + +This skill makes no docket write. Its one read is the `context.ticket` operation (argv from the capability catalog), run with `--id `, `--event ` when the update follows an event, and `--json`. Its result is under `context`: `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`). + +## 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. +- **The event.** Map the person's words to one event: spec written (`spec_written`), PR opened (`pr_opened`), PR merged (`pr_merged`), or results completed (`results_completed`). A material revision, a blocker or a decision that is needed, or a killed change has no event: run the read without `--event`. +- **People to mention**, when the person names any (section 5). +- **Creating a ticket** from a change is `docket-link-ticket`'s job; point the person there. + +## 2. Refuse when an update is not possible + +Post nothing and say why in one plain line when: + +- `ticket.state` is `not-linked`: say the change has no ticket (`#612 has no ticket`). +- `ticket.state` is `partial`: the link is broken; point the person to `docket-link-ticket` to fix or remove it. +- The request names a different ticket than `ticket.id`: say which ticket the change carries. +- `event.happened` is false: name the missing fact from `event.reason`. `no-spec`: the change has no spec. `no-pr`: it has no PR. `not-results-artifact`: it does not end in a results file. `not-completed`: its results are not complete. `merge-not-recorded`: say docket has not recorded a merge for the change and that, if the PR has merged, refreshing with `docket-status` records it; never say the PR has not merged. +- `visibility` is `private`: say private repositories are not supported yet. + +## 3. Write the update + +Read what the update needs: each file in `artifacts` at its `path`, and the change record at `change.path` for `## Closeout notes` or `## Why killed`. The record is read, never linked. Plans never go out: no link to a plan and nothing from one. + +| Update | It says | Links | +|---|---|---| +| spec written | the approach and key decisions, and where the change stands now from its `status` (designed, not yet built; being built; built, PR open; merged); never a claim of review, approval, or authorship | the spec | +| PR opened | the PR link, what was built, what the reviewer needs to know | the PR, the spec, and the results file | +| PR merged | what merged and where (`facts.merge.destination_branch`; when `in_integration` is false, say it is not yet in the integration branch), key outcomes, and anything left to do, from the results file's Outcome and Known issues and the record's `## Closeout notes`; never a claim of deployment or acceptance | the results file | +| results completed | findings, conclusions, limits, and any action needed | the results file | +| revision, blocker, or kill (no event) | what the person said, backed by the artifacts; for a kill, the record's `## Why killed` | the artifacts it discusses | + +A late update never misstates the current state: compare the event with the current `change.status` and say what has happened since (a PR-opened update asked for after the merge says the PR has since merged). + +**Editorial standard.** Updates are for people: a few short sentences or bullets, scaled to how much the update matters. Include, when relevant, what happened; what matters (key outcomes, consequential decisions, limitations); what is needed next from the reader (an action, test, review, or decision); and the links. Leave out how you worked, brainstorming notes and work logs, file lists, test inventories, command output, repeated background, filler, empty headings, and pasted artifact contents. Keep every material blocker, risk, and required action, however short the update. Say only what the change and its evidence support: a merge is not a deployment or an acceptance. + +**Layout.** Write for a person reading the comment in the ticket system. Lay it out so it scans: short paragraphs, a list, or a single line, whichever reads best for this update. Use the format the connector accepts, so the layout survives posting. Label links (`Spec:`, `Results:`). The examples show tone, length, and layout: + +> **@Jane Doe** — PR ready for review: https://github.com/acme/api/pull/48 +> +> Invalid requests now fail with a clear error before any work starts, instead of failing partway through. The API contract is unchanged, so existing clients need no update. +> +> Worth a close look: the validation runs before authentication, so a malformed request from an unauthenticated caller now gets a 400 instead of a 401. +> +> Before merging: one manual check against staging, described in the results. +> +> Spec: https://github.com/acme/api/blob/4f2c9e1/docs/superpowers/specs/2026-11-08-validate-requests-design.md +> Results: https://github.com/acme/api/blob/4f2c9e1/docs/results/2026-11-08-validate-requests-results.md + +> Merged into main. Invalid requests now return a clear error before processing starts. Deployment has not been confirmed. +> +> Automated checks passed; one manual check remains, described in the results. +> +> Results: https://github.com/acme/api/blob/4f2c9e1/docs/results/2026-11-08-validate-requests-results.md + +> Merged into main. Left to do before this can ship: +> +> - run the staging data migration (steps in the results) +> - confirm the new rate limit with the platform team +> - remove the old endpoint once clients have moved (tracked separately) +> +> Results: https://github.com/acme/api/blob/4f2c9e1/docs/results/2026-11-08-validate-requests-results.md + +(Real links carry the full commit id.) + +## 4. Links + +When `visibility` is `shared`, **read `references/shared.md` now (blocking)**. + +## 5. Mentions + +A mention makes the ticket system notify a person. Mention only people the person names, and only as they ask. For each name, search the connector's users (in Jira, its user lookup, which may be reachable only through its discovery tool). + +- **Exactly one match:** mention that person and post; there is no approval step. +- **Several matches:** ask the person which one, listing each candidate's name and email. +- **No match:** ask the person whether to post without that mention or try a different spelling. +- Use the ticket system's own mention form, the one that notifies (in Jira, a mention bound to the person's account id). Never substitute plain text such as "@Jane", which notifies nobody. If the connector cannot make a real mention, tell the person before posting. +- Mentions lead the comment. Nothing about mentions is saved. + +## 6. Post and report + +- **Find the connector** for `ticket.provider`. Never conclude an operation is missing because it is not in your tool list: some connectors expose operations only through a discovery tool (the Atlassian connector's `discover`), so look there first. +- **Post** the comment to `ticket.id`, making connector calls one at a time. Do not show a draft and wait: the person asked for the update. When they ask to see it first, show it and post on their go. +- **Report.** Report the update as posted only with the connector's confirmation, naming the ticket and anyone mentioned. For a missing connector, a failed post, or an uncertain outcome, say in one plain line what was not posted and why; an uncertain outcome is reported as uncertain, and the person decides whether to ask again. Never run a retry loop. A duplicate comment is deleted by hand. diff --git a/internal/assets/embedded/tree/skills/docket-update-ticket/references/shared.md b/internal/assets/embedded/tree/skills/docket-update-ticket/references/shared.md new file mode 100644 index 000000000..302fee4c6 --- /dev/null +++ b/internal/assets/embedded/tree/skills/docket-update-ticket/references/shared.md @@ -0,0 +1,9 @@ +# Shared delivery + +Loaded from `SKILL.md` when `visibility` is `shared`. The rules in `SKILL.md` apply; they are not repeated here. + +- **Where links come from.** The PR link is `facts.pr_url`; the spec and results links are each `artifacts` entry's `url`. Each `url` is pinned to `metadata_commit`, so the reader sees the file as it stood when you read it. Never build a link yourself, never link a branch, and never link the spec copy on the feature branch. +- **Which links.** Only the links the update's row in `SKILL.md` names, labeled (`Spec:`, `Results:`). +- **A missing link.** When the artifact is not in `artifacts` (an older change whose file is not on the metadata branch), or its `url` is empty (the repository has no web address), post the update without that link; never substitute a local path. +- **Links live in the comment only.** Never add a separate entry to the ticket's links panel (in Jira, a remote issue link): nothing could tidy them later. +- **Who can open them.** Readers are assumed to be able to open the repository; nothing checks their access. diff --git a/internal/harness/inventory_test.go b/internal/harness/inventory_test.go index ebad4f824..4822d3882 100644 --- a/internal/harness/inventory_test.go +++ b/internal/harness/inventory_test.go @@ -308,7 +308,7 @@ func TestSkillDirsFromEmbedded(t *testing.T) { t.Errorf("SkillDirs not strictly sorted at %d: %q then %q", i, got[i-1], d) } } - for _, known := range []string{"docket-build", "docket-build-task", "docket-convention", "docket-export", "docket-link-ticket"} { + for _, known := range []string{"docket-build", "docket-build-task", "docket-convention", "docket-export", "docket-link-ticket", "docket-update-ticket"} { if !want[known] { t.Fatalf("bundle no longer carries the %q skill; the fixture assumption is stale", known) } diff --git a/internal/repoguard/budgets_test.go b/internal/repoguard/budgets_test.go index 05d7fb17a..4527cd40a 100644 --- a/internal/repoguard/budgets_test.go +++ b/internal/repoguard/budgets_test.go @@ -221,6 +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", 98, 1431}, // 0585: new — the inline ticket-update skill + {"docket-update-ticket/references/shared.md", 9, 184}, // 0585: new — shared delivery } // wcLines counts lines the way `wc -l` does: the number of newline bytes. diff --git a/internal/repoguard/prose_contracts_test.go b/internal/repoguard/prose_contracts_test.go index 57d9808cd..824cdedd4 100644 --- a/internal/repoguard/prose_contracts_test.go +++ b/internal/repoguard/prose_contracts_test.go @@ -1625,6 +1625,42 @@ var alignmentContracts = []proseContract{ present: []string{"- **docket-link-ticket** —"}}, {sentinel: "change_0584_link_ticket_skill", file: "docs/reference/glossary.md", present: []string{"### docket-link-ticket", "- [docket-link-ticket](#docket-link-ticket)"}}, + // change 0585 — the inline update skill: on request only; refusals; the + // per-event links; plans never go out; layout for a person in the ticket + // system; real mentions only; posted only on confirmation; shared delivery + // 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", + "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", + "The request names a different ticket than `ticket.id`: say which ticket the change carries", + "never say the PR has not merged", + "`visibility` is `private`: say private repositories are not supported yet", + "Plans never go out: no link to a plan and nothing from one.", + "A late update never misstates the current state", + "| the PR, the spec, and the results file |", + "never a claim of deployment or acceptance", + "Write for a person reading the comment in the ticket system.", + "Use the format the connector accepts, so the layout survives posting.", + "Label links (`Spec:`, `Results:`).", + "**Exactly one match:** mention that person and post", + "**Several matches:** ask the person which one", + "**No match:** ask the person whether to post without that mention or try a different spelling", + "Never substitute plain text such as \"@Jane\", which notifies nobody.", + "Report the update as posted only with the connector's confirmation", + "Never run a retry loop.", + "When `visibility` is `shared`, **read `references/shared.md` now (blocking)**.", + }, + absent: []string{"context: fork", "agent: docket-update-ticket"}}, + {sentinel: "change_0585_update_ticket_skill", file: "skills/docket-update-ticket/references/shared.md", + present: []string{ + "Each `url` is pinned to `metadata_commit`", + "Never build a link yourself", + "Links live in the comment only", + "never substitute a local path", + }}, } // oneLayoutAbsent are the retired metadata-layout spellings. diff --git a/internal/repoguard/update_ticket_skill_test.go b/internal/repoguard/update_ticket_skill_test.go new file mode 100644 index 000000000..2f5c9ef31 --- /dev/null +++ b/internal/repoguard/update_ticket_skill_test.go @@ -0,0 +1,33 @@ +package repoguard + +import ( + "os" + "path/filepath" + "strings" + "testing" +) + +// TestUpdateTicketSkillIsInline pins docket-update-ticket as an inline skill whose +// description names its ask in conversational words, disclaims creating or +// linking, and uses the ticket vocabulary only; and checks that the reference +// SKILL.md routes to exists. +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", + "not for creating or linking a ticket", + }) + body := readRepoFile(t, "skills/"+name+"/SKILL.md") + desc := strings.ToLower(collapseWS(frontmatterValue(body, "description"))) + for _, word := range []string{"issue", "work item"} { + if strings.Contains(desc, word) { + t.Errorf("%s description uses %q; the item is a ticket: %q", name, word, desc) + } + } + // SKILL.md routes shared delivery to this file; a missing one leaves a + // blocking read with nothing to read. + p := filepath.Join(guardRoot(t), "skills", name, "references", "shared.md") + if _, err := os.Stat(p); err != nil { + t.Errorf("%s routes to references/shared.md, which cannot be read: %v", name, err) + } +} diff --git a/skills/docket-update-ticket/SKILL.md b/skills/docket-update-ticket/SKILL.md new file mode 100644 index 000000000..4ea7498de --- /dev/null +++ b/skills/docket-update-ticket/SKILL.md @@ -0,0 +1,98 @@ +--- +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.' +--- + +# 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. + +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. + +This skill makes no docket write. Its one read is the `context.ticket` operation (argv from the capability catalog), run with `--id `, `--event ` when the update follows an event, and `--json`. Its result is under `context`: `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`). + +## 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. +- **The event.** Map the person's words to one event: spec written (`spec_written`), PR opened (`pr_opened`), PR merged (`pr_merged`), or results completed (`results_completed`). A material revision, a blocker or a decision that is needed, or a killed change has no event: run the read without `--event`. +- **People to mention**, when the person names any (section 5). +- **Creating a ticket** from a change is `docket-link-ticket`'s job; point the person there. + +## 2. Refuse when an update is not possible + +Post nothing and say why in one plain line when: + +- `ticket.state` is `not-linked`: say the change has no ticket (`#612 has no ticket`). +- `ticket.state` is `partial`: the link is broken; point the person to `docket-link-ticket` to fix or remove it. +- The request names a different ticket than `ticket.id`: say which ticket the change carries. +- `event.happened` is false: name the missing fact from `event.reason`. `no-spec`: the change has no spec. `no-pr`: it has no PR. `not-results-artifact`: it does not end in a results file. `not-completed`: its results are not complete. `merge-not-recorded`: say docket has not recorded a merge for the change and that, if the PR has merged, refreshing with `docket-status` records it; never say the PR has not merged. +- `visibility` is `private`: say private repositories are not supported yet. + +## 3. Write the update + +Read what the update needs: each file in `artifacts` at its `path`, and the change record at `change.path` for `## Closeout notes` or `## Why killed`. The record is read, never linked. Plans never go out: no link to a plan and nothing from one. + +| Update | It says | Links | +|---|---|---| +| spec written | the approach and key decisions, and where the change stands now from its `status` (designed, not yet built; being built; built, PR open; merged); never a claim of review, approval, or authorship | the spec | +| PR opened | the PR link, what was built, what the reviewer needs to know | the PR, the spec, and the results file | +| PR merged | what merged and where (`facts.merge.destination_branch`; when `in_integration` is false, say it is not yet in the integration branch), key outcomes, and anything left to do, from the results file's Outcome and Known issues and the record's `## Closeout notes`; never a claim of deployment or acceptance | the results file | +| results completed | findings, conclusions, limits, and any action needed | the results file | +| revision, blocker, or kill (no event) | what the person said, backed by the artifacts; for a kill, the record's `## Why killed` | the artifacts it discusses | + +A late update never misstates the current state: compare the event with the current `change.status` and say what has happened since (a PR-opened update asked for after the merge says the PR has since merged). + +**Editorial standard.** Updates are for people: a few short sentences or bullets, scaled to how much the update matters. Include, when relevant, what happened; what matters (key outcomes, consequential decisions, limitations); what is needed next from the reader (an action, test, review, or decision); and the links. Leave out how you worked, brainstorming notes and work logs, file lists, test inventories, command output, repeated background, filler, empty headings, and pasted artifact contents. Keep every material blocker, risk, and required action, however short the update. Say only what the change and its evidence support: a merge is not a deployment or an acceptance. + +**Layout.** Write for a person reading the comment in the ticket system. Lay it out so it scans: short paragraphs, a list, or a single line, whichever reads best for this update. Use the format the connector accepts, so the layout survives posting. Label links (`Spec:`, `Results:`). The examples show tone, length, and layout: + +> **@Jane Doe** — PR ready for review: https://github.com/acme/api/pull/48 +> +> Invalid requests now fail with a clear error before any work starts, instead of failing partway through. The API contract is unchanged, so existing clients need no update. +> +> Worth a close look: the validation runs before authentication, so a malformed request from an unauthenticated caller now gets a 400 instead of a 401. +> +> Before merging: one manual check against staging, described in the results. +> +> Spec: https://github.com/acme/api/blob/4f2c9e1/docs/superpowers/specs/2026-11-08-validate-requests-design.md +> Results: https://github.com/acme/api/blob/4f2c9e1/docs/results/2026-11-08-validate-requests-results.md + +> Merged into main. Invalid requests now return a clear error before processing starts. Deployment has not been confirmed. +> +> Automated checks passed; one manual check remains, described in the results. +> +> Results: https://github.com/acme/api/blob/4f2c9e1/docs/results/2026-11-08-validate-requests-results.md + +> Merged into main. Left to do before this can ship: +> +> - run the staging data migration (steps in the results) +> - confirm the new rate limit with the platform team +> - remove the old endpoint once clients have moved (tracked separately) +> +> Results: https://github.com/acme/api/blob/4f2c9e1/docs/results/2026-11-08-validate-requests-results.md + +(Real links carry the full commit id.) + +## 4. Links + +When `visibility` is `shared`, **read `references/shared.md` now (blocking)**. + +## 5. Mentions + +A mention makes the ticket system notify a person. Mention only people the person names, and only as they ask. For each name, search the connector's users (in Jira, its user lookup, which may be reachable only through its discovery tool). + +- **Exactly one match:** mention that person and post; there is no approval step. +- **Several matches:** ask the person which one, listing each candidate's name and email. +- **No match:** ask the person whether to post without that mention or try a different spelling. +- Use the ticket system's own mention form, the one that notifies (in Jira, a mention bound to the person's account id). Never substitute plain text such as "@Jane", which notifies nobody. If the connector cannot make a real mention, tell the person before posting. +- Mentions lead the comment. Nothing about mentions is saved. + +## 6. Post and report + +- **Find the connector** for `ticket.provider`. Never conclude an operation is missing because it is not in your tool list: some connectors expose operations only through a discovery tool (the Atlassian connector's `discover`), so look there first. +- **Post** the comment to `ticket.id`, making connector calls one at a time. Do not show a draft and wait: the person asked for the update. When they ask to see it first, show it and post on their go. +- **Report.** Report the update as posted only with the connector's confirmation, naming the ticket and anyone mentioned. For a missing connector, a failed post, or an uncertain outcome, say in one plain line what was not posted and why; an uncertain outcome is reported as uncertain, and the person decides whether to ask again. Never run a retry loop. A duplicate comment is deleted by hand. diff --git a/skills/docket-update-ticket/references/shared.md b/skills/docket-update-ticket/references/shared.md new file mode 100644 index 000000000..302fee4c6 --- /dev/null +++ b/skills/docket-update-ticket/references/shared.md @@ -0,0 +1,9 @@ +# Shared delivery + +Loaded from `SKILL.md` when `visibility` is `shared`. The rules in `SKILL.md` apply; they are not repeated here. + +- **Where links come from.** The PR link is `facts.pr_url`; the spec and results links are each `artifacts` entry's `url`. Each `url` is pinned to `metadata_commit`, so the reader sees the file as it stood when you read it. Never build a link yourself, never link a branch, and never link the spec copy on the feature branch. +- **Which links.** Only the links the update's row in `SKILL.md` names, labeled (`Spec:`, `Results:`). +- **A missing link.** When the artifact is not in `artifacts` (an older change whose file is not on the metadata branch), or its `url` is empty (the repository has no web address), post the update without that link; never substitute a local path. +- **Links live in the comment only.** Never add a separate entry to the ticket's links panel (in Jira, a remote issue link): nothing could tidy them later. +- **Who can open them.** Readers are assumed to be able to open the repository; nothing checks their access. From 00f86cdae9a6fcf09cc72f533b6238a8d1f5431b Mon Sep 17 00:00:00 2001 From: Daniel Hanold Date: Tue, 10 Nov 2026 08:13:51 -0500 Subject: [PATCH 6/9] docs: list docket-update-ticket with the inline skills and fix the ticket config notes --- docs/install/models-and-effort.md | 5 ++-- docs/reference/config-keys.md | 6 ++-- docs/reference/glossary.md | 28 +++++++++++++++++-- docs/reference/skills-and-agents.md | 1 + internal/assets/embedded/manifest.json | 18 ++++++------ .../tree/skills/docket-convention/SKILL.md | 2 +- .../references/agent-layer.md | 2 +- .../tree/skills/docket-export/SKILL.md | 4 +-- .../tree/skills/docket-link-ticket/SKILL.md | 2 +- internal/repoguard/budgets_test.go | 8 +++--- internal/repoguard/prose_contracts_test.go | 28 +++++++++++++++++-- skills/docket-convention/SKILL.md | 2 +- .../references/agent-layer.md | 2 +- skills/docket-export/SKILL.md | 4 +-- skills/docket-link-ticket/SKILL.md | 2 +- 15 files changed, 81 insertions(+), 33 deletions(-) diff --git a/docs/install/models-and-effort.md b/docs/install/models-and-effort.md index f95509822..42268ce6b 100644 --- a/docs/install/models-and-effort.md +++ b/docs/install/models-and-effort.md @@ -23,7 +23,7 @@ your strongest model at higher effort. `docket-export` also runs inline at your session's model and effort; it runs one export and needs no particular model. `docket-link-ticket` runs inline too, because it works with you and posts -through your session's connector. +through your session's connector. `docket-update-ticket` runs inline as well, for the same reason. To change the model or effort an autonomous skill runs at: @@ -109,7 +109,8 @@ the two interactive brainstorm skills (`docket-new-change`, `docket-groom-next`) headless drive is authorized by [naming ids](../guide/landing-changes.md) instead) do not, and neither does `docket-export`, which posts through your session's own tools and may ask you before a private-repository post, nor -`docket-link-ticket`, which works with you and posts through your session's connector. +`docket-link-ticket`, which works with you and posts through your session's connector, nor +`docket-update-ticket`, which posts through it too. **The two invocation paths.** **Dispatch** — launching a named agent to do a step and waiting for it to return — is one way to reach a pinned wrapper; a plain skill-invoke, forked, is the other. Both diff --git a/docs/reference/config-keys.md b/docs/reference/config-keys.md index 7f8e39305..ede81668a 100644 --- a/docs/reference/config-keys.md +++ b/docs/reference/config-keys.md @@ -57,9 +57,9 @@ Each key has one scope: | `board.section_order` | `[in-progress, built, blocked, groomed, proposed, deferred]` | any layer | the order of the board's sections | | `board.sorting.
.by` / `.direction` | `updated` / `desc` | any layer | how each board section is sorted | | `change_types` | `[chore, docs, feat, fix, refactor, perf]` | any layer | the types a change can be classified as | -| `tickets.provider` | `""` (unset) | repo-only | the ticket system this repository's changes link to (jira, linear, …); no effect yet | -| `tickets.site` | `""` (unset) | repo-only | where that ticket system lives; no effect yet | -| `tickets.project` | `""` (unset) | repo-only | where new tickets go (a project, team, repository, or board, by tool); no effect yet | +| `tickets.provider` | `""` (unset) | repo-only | the ticket system this repository's changes link to (jira, linear, …); used when linking or creating a ticket | +| `tickets.site` | `""` (unset) | repo-only | where that ticket system lives; used when linking a ticket by URL or id | +| `tickets.project` | `""` (unset) | repo-only | where new tickets go (a project, team, repository, or board, by tool); used when creating a ticket | | `tickets.auto.change_created` | `false` | repo-only | a switch for when a change is created; no effect yet | | `tickets.auto.spec_written` | `false` | repo-only | a switch for when a change's spec is written; no effect yet | | `tickets.auto.pr_opened` | `false` | repo-only | a switch for when a change's pull request opens; no effect yet | diff --git a/docs/reference/glossary.md b/docs/reference/glossary.md index 732120c30..d894a249d 100644 --- a/docs/reference/glossary.md +++ b/docs/reference/glossary.md @@ -849,6 +849,16 @@ and recorded branch. docket context implementation --id 412 --json ``` +### Ticket context + +The read-only bundle `docket-update-ticket` reads before posting: the change's ticket link, the +repository's visibility, whether the event has happened, the facts behind it, and spec and results +links pinned to the metadata commit the read took. + +```sh +docket context ticket --id 412 --event pr_opened --json +``` + ### Implement-next / the drainer `docket-implement-next` — the autonomous workflow that picks the next build-ready change (or the @@ -1836,6 +1846,16 @@ inline. @docket-status # agent-dispatch: same pinned run, drillable live ``` +### 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 posts nothing yet. + +**Used for:** telling people in the ticket system that something happened. It runs inline, because +it posts through your session's connector. + ### Fork / forked skill On harnesses that support it, a skill can run as a fork of the current context rather than a fresh @@ -1848,7 +1868,7 @@ back to the human. The forked skills are `docket-status`, `docket-adr`, `docket- `docket-auto-groom` (`context: fork` + `agent:` frontmatter). **Used for:** explaining why `docket-new-change`, `docket-groom-next`, `docket-export`, -`docket-link-ticket`, and `docket-finalize-change` run inline. A headless finalize is authorized by naming ids instead. +`docket-link-ticket`, `docket-update-ticket`, and `docket-finalize-change` run inline. A headless finalize is authorized by naming ids instead. ### Harness @@ -1872,8 +1892,8 @@ every harness. It is program data, not user config, and each harness block is co abort-and-report rule: implement-next, auto-groom, finalize-change, status, adr, build-task, and review. **Interactive** skills (`docket-new-change`, `docket-groom-next`) stay inline at the session model, because the conversation with you is the point. They only advise a model at startup. -`docket-export` and `docket-link-ticket` also stay inline, because they post with your session's own -tools and work with you before posting. +`docket-export`, `docket-link-ticket`, and `docket-update-ticket` also stay inline, because they +post with your session's own tools and work with you before posting. **Used for:** knowing which skills you can dispatch and walk away from, and which need you at the keyboard. @@ -2385,6 +2405,7 @@ docket development install --source ~/dev/docket - [docket-new-change](#docket-new-change) - [docket-review](#docket-review) - [docket-status](#docket-status) +- [docket-update-ticket](#docket-update-ticket) - [Drive disposition: WAITING / PASSED / FAILED / HALTED](#drive-disposition-waiting--passed--failed--halted) - [Effects](#effects) - [Escalation (NEEDS_ESCALATION)](#build-tier--escalation) — see Build tier / escalation @@ -2496,6 +2517,7 @@ docket development install --source ~/dev/docket - [Suite gate](#suite-gate) - [Sweep](#sweep) - [Sync integration](#sync-integration) +- [Ticket context](#ticket-context) - [Tri-state verdict / halt exit code](#tri-state-verdict--halt-exit-code) - [Two invocation paths: skill-invoke vs agent-dispatch](#two-invocation-paths-skill-invoke-vs-agent-dispatch) - [Uninstall](#uninstall) diff --git a/docs/reference/skills-and-agents.md b/docs/reference/skills-and-agents.md index 2c796fb06..541fd4300 100644 --- a/docs/reference/skills-and-agents.md +++ b/docs/reference/skills-and-agents.md @@ -26,6 +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; shared repositories only for now. ## Default workflow roles diff --git a/internal/assets/embedded/manifest.json b/internal/assets/embedded/manifest.json index 3232b82e7..c5b695b87 100644 --- a/internal/assets/embedded/manifest.json +++ b/internal/assets/embedded/manifest.json @@ -1,7 +1,7 @@ { "format_version": 1, "asset_protocol": 1, - "asset_set_id": "sha256:f1456a07769b968fd591984596659568068d03cfbbe1049182e795484be41c8c", + "asset_set_id": "sha256:d4b9df8648a294d6db10f4dcff89de00f6ad801abd194f1349942f3b6b38cc39", "entries": [ { "path": ".docket.example.yml", @@ -322,15 +322,15 @@ "path": "skills/docket-convention/SKILL.md", "role": "skill", "mode": 420, - "size": 54370, - "sha256": "aa82012df0a805de1ed21ea8a475aead91ca6b033798ca1c5234c4fdccb7292a" + "size": 54394, + "sha256": "ad8863422c4033cd93de72620031a870303343bce988dc0eb033b9e49efd7ae7" }, { "path": "skills/docket-convention/references/agent-layer.md", "role": "skill", "mode": 420, - "size": 14412, - "sha256": "50fe98e714355ef3cf8d7fe4e87939071d7d4d250f17772508a40e7a8bf24e5e" + "size": 14436, + "sha256": "dcb1013bae42118623fb8e76d8c6ab20cdfe2818dc4f52a58bd7a0a2912096e7" }, { "path": "skills/docket-convention/references/close-out.md", @@ -357,8 +357,8 @@ "path": "skills/docket-export/SKILL.md", "role": "skill", "mode": 420, - "size": 6846, - "sha256": "fa95a8c50ef35978ba11bbab1d95ed7160ccf75af2193799513a72d7a2cfc043" + "size": 6930, + "sha256": "c1cb6f771d041157c5d0c0c04fa5fc209288d00d07b1d897c84802221f5390dc" }, { "path": "skills/docket-finalize-change/SKILL.md", @@ -420,8 +420,8 @@ "path": "skills/docket-link-ticket/SKILL.md", "role": "skill", "mode": 420, - "size": 5075, - "sha256": "260ec3e50a5bc14b52bc21d6ad82f7053f86b4715a62aebdda718a73e2b71a41" + "size": 5107, + "sha256": "eea0af0494c42f1ff4eb19631b7eaf8f177382680a4d4b12f9ba5c51bc4022a0" }, { "path": "skills/docket-link-ticket/references/create.md", diff --git a/internal/assets/embedded/tree/skills/docket-convention/SKILL.md b/internal/assets/embedded/tree/skills/docket-convention/SKILL.md index 24939d87a..00da5f647 100644 --- a/internal/assets/embedded/tree/skills/docket-convention/SKILL.md +++ b/internal/assets/embedded/tree/skills/docket-convention/SKILL.md @@ -102,7 +102,7 @@ The *Skill layer*'s **missing-skill rule** and `halt` are two conditions with tw ### Agent layer — model/effort-pinned subagents -Each **autonomous** docket skill can run as a model/effort-pinned **subagent** instead of inline at the session model. The autonomous skills get a wrapper — `docket-implement-next`, `docket-auto-groom`, `docket-finalize-change`, `docket-status`, `docket-adr`, `docket-build-task` (shared by its four tier agents), and `docket-review` (shared by its three tier wrappers); the two **interactive** skills (`docket-new-change`, `docket-groom-next`), `docket-export`, and `docket-link-ticket` stay inline and run at the session model. `docket-convention` is not an agent — it is listed in the skills list of every wrapper except these: `docket-brainstorm-consultant` (ADR-0022), **`docket-plan-writer`**, the `docket-build-*` tier workers, and the `docket-review-*` tier wrappers. Of these wrapper-bearing exceptions the plan-writer performs exactly one docket metadata operation (`change.attach-plan`) and the others perform none — a boundary each worker contract's own *Scope* states normatively; the consultant wraps nothing at all (see *Composition*). +Each **autonomous** docket skill can run as a model/effort-pinned **subagent** instead of inline at the session model. The autonomous skills get a wrapper — `docket-implement-next`, `docket-auto-groom`, `docket-finalize-change`, `docket-status`, `docket-adr`, `docket-build-task` (shared by its four tier agents), and `docket-review` (shared by its three tier wrappers); the two **interactive** skills (`docket-new-change`, `docket-groom-next`), `docket-export`, `docket-link-ticket`, and `docket-update-ticket` stay inline and run at the session model. `docket-convention` is not an agent — it is listed in the skills list of every wrapper except these: `docket-brainstorm-consultant` (ADR-0022), **`docket-plan-writer`**, the `docket-build-*` tier workers, and the `docket-review-*` tier wrappers. Of these wrapper-bearing exceptions the plan-writer performs exactly one docket metadata operation (`change.attach-plan`) and the others perform none — a boundary each worker contract's own *Scope* states normatively; the consultant wraps nothing at all (see *Composition*). A wrapper is a thin installed file: it carries the resolved `model` and `effort`, when they resolve, and lists the skill and `docket-convention` in its skills list; the skill body stays the single source of behavior. Because a subagent cannot pause to ask a human, every autonomous wrapper carries an **abort-and-report** rule: an unmet precondition or blocking ambiguity is surfaced and stopped on — never turned into an interactive prompt. The Go install generates each wrapper from the compiled built-in model/effort table plus the global configuration's overrides, and installs it at user level, never per repository. A **directly-invoked** autonomous skill is still routed to its pinned wrapper by a harness dispatch mechanism, so the pin holds either way; mechanics live in [`references/agent-layer.md`](references/agent-layer.md). diff --git a/internal/assets/embedded/tree/skills/docket-convention/references/agent-layer.md b/internal/assets/embedded/tree/skills/docket-convention/references/agent-layer.md index 59c4b5502..68055243e 100644 --- a/internal/assets/embedded/tree/skills/docket-convention/references/agent-layer.md +++ b/internal/assets/embedded/tree/skills/docket-convention/references/agent-layer.md @@ -196,7 +196,7 @@ four headless-safe autonomous skills (`docket-status`, `docket-adr`, `docket-imp carry `context: fork` + `agent: docket-` frontmatter in their `SKILL.md`, forking a directly-invoked skill into the same pinned wrapper — inert in every other harness. **Fork-exclusion principle:** only skills that never need the human mid-run are forked, since a forked subagent has no channel back to the human; the two interactive -skills, `docket-export`, and `docket-link-ticket` stay inline, and `docket-finalize-change` stays unforked — its headless merge is gated by a permission +skills, `docket-export`, `docket-link-ticket`, and `docket-update-ticket` stay inline, and `docket-finalize-change` stays unforked — its headless merge is gated by a permission classifier (ADR-0043). A forked skill-invoke (`/docket-status`) and an explicit agent dispatch (`@docket-status`, or a subagent dispatch diff --git a/internal/assets/embedded/tree/skills/docket-export/SKILL.md b/internal/assets/embedded/tree/skills/docket-export/SKILL.md index 14dfc40ec..27c5f06c5 100644 --- a/internal/assets/embedded/tree/skills/docket-export/SKILL.md +++ b/internal/assets/embedded/tree/skills/docket-export/SKILL.md @@ -9,7 +9,7 @@ Docket artifacts carry links, generated blocks, and references that mean nothing This skill runs inline, in your own session: you post with your own tools, and you ask the person directly where a step below says to. -Creating a ticket from a change, or linking or importing one, is `docket-link-ticket`'s job; it calls this skill only for a file export. +Creating a ticket from a change, or linking or importing one, is `docket-link-ticket`'s job; it calls this skill only for a file export. Posting an update or comment to a ticket is `docket-update-ticket`'s job. ## 1. Resolve the operations @@ -29,7 +29,7 @@ In a private repository, also run the `diagnostic.config` argv with `--repo-dir Run the `open` argv as ` [] --export --print --json --repo-dir `, where `` is `change`, `spec`, `plan`, or `results` and `` is the change the person named (omit it to use the change whose branch is checked out). Always `--export --print --json`: `--print` opens no viewer — the person may not be at the screen, and can ask you to open the file. Never pass `--warnings` unless the person asked for a filter on a file request; the default reports everything the private pass reads. - **File request** ("export the spec for 9"): the export's default destination, or `--output-path ` when the person names one. -- **Outside-tool request** ("add the spec for 9 as a comment on PROJ-123"): `--output-path` set to a fresh directory from `mktemp -d "${TMPDIR:-/tmp}/docket-export.XXXXXX"`, so the person's downloads folder does not collect one file per post. Leave the file there and report its path. +- **Outside-tool request** ("put the spec for 9 in a message to the design channel"): `--output-path` set to a fresh directory from `mktemp -d "${TMPDIR:-/tmp}/docket-export.XXXXXX"`, so the person's downloads folder does not collect one file per post. Leave the file there and report its path. **A failed export posts nothing.** If `result` is not `applied` or there is no `exported_path`, tell the person the `message` and stop. Never fall back to the raw file or a hand cleanup. This holds in every repository. diff --git a/internal/assets/embedded/tree/skills/docket-link-ticket/SKILL.md b/internal/assets/embedded/tree/skills/docket-link-ticket/SKILL.md index ceb425377..c6215343b 100644 --- a/internal/assets/embedded/tree/skills/docket-link-ticket/SKILL.md +++ b/internal/assets/embedded/tree/skills/docket-link-ticket/SKILL.md @@ -24,7 +24,7 @@ Writes are change records on the metadata branch, made only through the `change. - **Shared tickets.** One ticket may be on several changes. When another change already carries this ticket, name it (`CLOUD-123 is also on #10`) and go ahead. - **Confirmation.** Record only after the connector confirms. Never report a ticket as created, found, or attached without the connector's confirmation. - **Failures.** A missing connector or a failed call is said plainly. An uncertain outcome is reported as uncertain, and the person decides whether to try again. Never run a retry loop of your own. -- **Not this skill's.** Posting an update or comment to a ticket (`update CLOUD-123 now that the PR is open`). +- **Not this skill's.** Posting an update or comment to a ticket (`update CLOUD-123 now that the PR is open`) is `docket-update-ticket`'s job. ## Routing diff --git a/internal/repoguard/budgets_test.go b/internal/repoguard/budgets_test.go index 4527cd40a..dea760f93 100644 --- a/internal/repoguard/budgets_test.go +++ b/internal/repoguard/budgets_test.go @@ -199,14 +199,14 @@ 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, 7528}, // 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", 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) // 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, 1992}, // 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) + {"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) {"docket-convention/references/close-out.md", 174, 1722}, // 0567: a carried child whose stack relationship can't be proven stays pending (destination-mismatch) (174/1711 -> 174/1722); 0567: a carried stacked child is retried like any done change and stays pending (carry-unproven) with no delete advice (174/1704 -> 174/1711); 0559: change.complete is the third done driver; finalize.cleanup's no-PR path; kill takes --request and is not idempotent (141/1347 -> 174/1701); 0559: the sweep retries only a leftover worktree (174/1701 -> 174/1704); 0531: the metadata worktree and remote come from the repository.prepare context (141/1349 -> 141/1347); 0502: "loop" means /loop only (144/1375 -> 144/1374); 0502: one metadata layout — the docket branch and the .docket/ worktree (144/1376 -> 144/1375); 0502: the scripts/.md contract pointer becomes the schema operation (144/1374 -> 144/1376); 0502: the terminal-publication step is deleted (240/2150 -> 144/1374); 0474: reference renamed (ADR-0129 row 59a); ceilings unchanged; 0502: drop change citations and Go v1 narration (144/1374 -> 144/1356); 0502: the docket-source test citations are deleted (144/1356 -> 141/1349) {"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, 1133}, // 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-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/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) @@ -215,7 +215,7 @@ var skillBudgets = []skillBudget{ {"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/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, 816}, // 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/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", 35, 853}, // 0584 review: the open argv is resolved from the capability catalog (35/843 -> 35/853); 0584: new — the push path {"docket-link-ticket/references/import.md", 15, 323}, // 0584: new — the import path {"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) diff --git a/internal/repoguard/prose_contracts_test.go b/internal/repoguard/prose_contracts_test.go index 824cdedd4..a0f656b5f 100644 --- a/internal/repoguard/prose_contracts_test.go +++ b/internal/repoguard/prose_contracts_test.go @@ -1554,7 +1554,7 @@ var alignmentContracts = []proseContract{ "the export never reports them, so search the whole copy on every private export", }}, {sentinel: "change_0578_export_skill", file: "skills/docket-convention/SKILL.md", - present: []string{"(`docket-new-change`, `docket-groom-next`), `docket-export`, and `docket-link-ticket` stay inline"}}, + present: []string{"(`docket-new-change`, `docket-groom-next`), `docket-export`, `docket-link-ticket`, and `docket-update-ticket` stay inline"}}, {sentinel: "change_0578_export_skill", file: "docs/reference/cli.md", present: []string{"Agent sessions reach the export through the `docket-export` skill."}}, {sentinel: "change_0578_export_skill", file: "docs/reference/skills-and-agents.md", @@ -1620,7 +1620,7 @@ var alignmentContracts = []proseContract{ // change 0584 — docket-link-ticket joins the inline skills in the agent // layer and the reference docs. {sentinel: "change_0584_link_ticket_skill", file: "skills/docket-convention/references/agent-layer.md", - present: []string{"the two interactive skills, `docket-export`, and `docket-link-ticket` stay inline"}}, + present: []string{"the two interactive skills, `docket-export`, `docket-link-ticket`, and `docket-update-ticket` stay inline"}}, {sentinel: "change_0584_link_ticket_skill", file: "docs/reference/skills-and-agents.md", present: []string{"- **docket-link-ticket** —"}}, {sentinel: "change_0584_link_ticket_skill", file: "docs/reference/glossary.md", @@ -1661,6 +1661,30 @@ var alignmentContracts = []proseContract{ "Links live in the comment only", "never substitute a local path", }}, + // change 0585 — docket-update-ticket joins the inline skills: export and + // link-ticket route update requests to it, the reference docs list it, and + // the tickets.provider/site/project keys now have an effect. + {sentinel: "change_0585_update_ticket_skill", file: "skills/docket-export/SKILL.md", + present: []string{"Posting an update or comment to a ticket is `docket-update-ticket`'s job."}, + absent: []string{"as a comment on PROJ-123"}}, + {sentinel: "change_0585_update_ticket_skill", file: "skills/docket-link-ticket/SKILL.md", + present: []string{"- **Not this skill's.** Posting an update or comment to a ticket (`update CLOUD-123 now that the PR is open`) is `docket-update-ticket`'s job."}}, + {sentinel: "change_0585_update_ticket_skill", file: "docs/reference/skills-and-agents.md", + present: []string{"- **docket-update-ticket** —"}}, + {sentinel: "change_0585_update_ticket_skill", file: "docs/reference/glossary.md", + present: []string{ + "### docket-update-ticket", + "- [docket-update-ticket](#docket-update-ticket)", + "### Ticket context", + "- [Ticket context](#ticket-context)", + }}, + {sentinel: "change_0585_update_ticket_skill", file: "docs/reference/config-keys.md", + present: []string{ + "| `tickets.provider` | `\"\"` (unset) | repo-only | the ticket system this repository's changes link to (jira, linear, …); used when linking or creating a ticket |", + "; used when linking a ticket by URL or id |", + "; used when creating a ticket |", + }, + absent: []string{"(jira, linear, …); no effect yet |"}}, } // oneLayoutAbsent are the retired metadata-layout spellings. diff --git a/skills/docket-convention/SKILL.md b/skills/docket-convention/SKILL.md index 24939d87a..00da5f647 100644 --- a/skills/docket-convention/SKILL.md +++ b/skills/docket-convention/SKILL.md @@ -102,7 +102,7 @@ The *Skill layer*'s **missing-skill rule** and `halt` are two conditions with tw ### Agent layer — model/effort-pinned subagents -Each **autonomous** docket skill can run as a model/effort-pinned **subagent** instead of inline at the session model. The autonomous skills get a wrapper — `docket-implement-next`, `docket-auto-groom`, `docket-finalize-change`, `docket-status`, `docket-adr`, `docket-build-task` (shared by its four tier agents), and `docket-review` (shared by its three tier wrappers); the two **interactive** skills (`docket-new-change`, `docket-groom-next`), `docket-export`, and `docket-link-ticket` stay inline and run at the session model. `docket-convention` is not an agent — it is listed in the skills list of every wrapper except these: `docket-brainstorm-consultant` (ADR-0022), **`docket-plan-writer`**, the `docket-build-*` tier workers, and the `docket-review-*` tier wrappers. Of these wrapper-bearing exceptions the plan-writer performs exactly one docket metadata operation (`change.attach-plan`) and the others perform none — a boundary each worker contract's own *Scope* states normatively; the consultant wraps nothing at all (see *Composition*). +Each **autonomous** docket skill can run as a model/effort-pinned **subagent** instead of inline at the session model. The autonomous skills get a wrapper — `docket-implement-next`, `docket-auto-groom`, `docket-finalize-change`, `docket-status`, `docket-adr`, `docket-build-task` (shared by its four tier agents), and `docket-review` (shared by its three tier wrappers); the two **interactive** skills (`docket-new-change`, `docket-groom-next`), `docket-export`, `docket-link-ticket`, and `docket-update-ticket` stay inline and run at the session model. `docket-convention` is not an agent — it is listed in the skills list of every wrapper except these: `docket-brainstorm-consultant` (ADR-0022), **`docket-plan-writer`**, the `docket-build-*` tier workers, and the `docket-review-*` tier wrappers. Of these wrapper-bearing exceptions the plan-writer performs exactly one docket metadata operation (`change.attach-plan`) and the others perform none — a boundary each worker contract's own *Scope* states normatively; the consultant wraps nothing at all (see *Composition*). A wrapper is a thin installed file: it carries the resolved `model` and `effort`, when they resolve, and lists the skill and `docket-convention` in its skills list; the skill body stays the single source of behavior. Because a subagent cannot pause to ask a human, every autonomous wrapper carries an **abort-and-report** rule: an unmet precondition or blocking ambiguity is surfaced and stopped on — never turned into an interactive prompt. The Go install generates each wrapper from the compiled built-in model/effort table plus the global configuration's overrides, and installs it at user level, never per repository. A **directly-invoked** autonomous skill is still routed to its pinned wrapper by a harness dispatch mechanism, so the pin holds either way; mechanics live in [`references/agent-layer.md`](references/agent-layer.md). diff --git a/skills/docket-convention/references/agent-layer.md b/skills/docket-convention/references/agent-layer.md index 59c4b5502..68055243e 100644 --- a/skills/docket-convention/references/agent-layer.md +++ b/skills/docket-convention/references/agent-layer.md @@ -196,7 +196,7 @@ four headless-safe autonomous skills (`docket-status`, `docket-adr`, `docket-imp carry `context: fork` + `agent: docket-` frontmatter in their `SKILL.md`, forking a directly-invoked skill into the same pinned wrapper — inert in every other harness. **Fork-exclusion principle:** only skills that never need the human mid-run are forked, since a forked subagent has no channel back to the human; the two interactive -skills, `docket-export`, and `docket-link-ticket` stay inline, and `docket-finalize-change` stays unforked — its headless merge is gated by a permission +skills, `docket-export`, `docket-link-ticket`, and `docket-update-ticket` stay inline, and `docket-finalize-change` stays unforked — its headless merge is gated by a permission classifier (ADR-0043). A forked skill-invoke (`/docket-status`) and an explicit agent dispatch (`@docket-status`, or a subagent dispatch diff --git a/skills/docket-export/SKILL.md b/skills/docket-export/SKILL.md index 14dfc40ec..27c5f06c5 100644 --- a/skills/docket-export/SKILL.md +++ b/skills/docket-export/SKILL.md @@ -9,7 +9,7 @@ Docket artifacts carry links, generated blocks, and references that mean nothing This skill runs inline, in your own session: you post with your own tools, and you ask the person directly where a step below says to. -Creating a ticket from a change, or linking or importing one, is `docket-link-ticket`'s job; it calls this skill only for a file export. +Creating a ticket from a change, or linking or importing one, is `docket-link-ticket`'s job; it calls this skill only for a file export. Posting an update or comment to a ticket is `docket-update-ticket`'s job. ## 1. Resolve the operations @@ -29,7 +29,7 @@ In a private repository, also run the `diagnostic.config` argv with `--repo-dir Run the `open` argv as ` [] --export --print --json --repo-dir `, where `` is `change`, `spec`, `plan`, or `results` and `` is the change the person named (omit it to use the change whose branch is checked out). Always `--export --print --json`: `--print` opens no viewer — the person may not be at the screen, and can ask you to open the file. Never pass `--warnings` unless the person asked for a filter on a file request; the default reports everything the private pass reads. - **File request** ("export the spec for 9"): the export's default destination, or `--output-path ` when the person names one. -- **Outside-tool request** ("add the spec for 9 as a comment on PROJ-123"): `--output-path` set to a fresh directory from `mktemp -d "${TMPDIR:-/tmp}/docket-export.XXXXXX"`, so the person's downloads folder does not collect one file per post. Leave the file there and report its path. +- **Outside-tool request** ("put the spec for 9 in a message to the design channel"): `--output-path` set to a fresh directory from `mktemp -d "${TMPDIR:-/tmp}/docket-export.XXXXXX"`, so the person's downloads folder does not collect one file per post. Leave the file there and report its path. **A failed export posts nothing.** If `result` is not `applied` or there is no `exported_path`, tell the person the `message` and stop. Never fall back to the raw file or a hand cleanup. This holds in every repository. diff --git a/skills/docket-link-ticket/SKILL.md b/skills/docket-link-ticket/SKILL.md index ceb425377..c6215343b 100644 --- a/skills/docket-link-ticket/SKILL.md +++ b/skills/docket-link-ticket/SKILL.md @@ -24,7 +24,7 @@ Writes are change records on the metadata branch, made only through the `change. - **Shared tickets.** One ticket may be on several changes. When another change already carries this ticket, name it (`CLOUD-123 is also on #10`) and go ahead. - **Confirmation.** Record only after the connector confirms. Never report a ticket as created, found, or attached without the connector's confirmation. - **Failures.** A missing connector or a failed call is said plainly. An uncertain outcome is reported as uncertain, and the person decides whether to try again. Never run a retry loop of your own. -- **Not this skill's.** Posting an update or comment to a ticket (`update CLOUD-123 now that the PR is open`). +- **Not this skill's.** Posting an update or comment to a ticket (`update CLOUD-123 now that the PR is open`) is `docket-update-ticket`'s job. ## Routing From d196ef0a0cee148f206e732cf9d31d281a8b6169 Mon Sep 17 00:00:00 2001 From: Daniel Hanold Date: Tue, 10 Nov 2026 08:27:24 -0500 Subject: [PATCH 7/9] fix(app): report a killed reason for pr_merged and results_completed on a killed change Review finding: ticketEvent fell through to merge-not-recorded for a killed change carrying pr:, and docket-update-ticket then told the person to refresh with docket-status, which never records a merge for a killed change. A killed change now reports the new killed reason for pr_merged and results_completed, and the skill offers a kill update instead. --- internal/app/ticket_context.go | 7 ++++++- internal/app/ticket_context_skill_test.go | 4 ++-- internal/app/ticket_context_test.go | 14 ++++++++------ internal/assets/embedded/manifest.json | 6 +++--- .../tree/skills/docket-update-ticket/SKILL.md | 2 +- internal/repoguard/budgets_test.go | 2 +- skills/docket-update-ticket/SKILL.md | 2 +- 7 files changed, 22 insertions(+), 15 deletions(-) diff --git a/internal/app/ticket_context.go b/internal/app/ticket_context.go index 44bee4e51..9cc46258c 100644 --- a/internal/app/ticket_context.go +++ b/internal/app/ticket_context.go @@ -40,6 +40,7 @@ const ( ReasonTicketMergeNotRecorded = "merge-not-recorded" ReasonTicketNotResultsArtifact = "not-results-artifact" ReasonTicketNotCompleted = "not-completed" + ReasonTicketKilled = "killed" ) // Ticket link states. @@ -64,7 +65,7 @@ const ( // Ordered token lists; the skill guard iterates these so the skill and this // producer cannot drift apart. var ticketEvents = []string{TicketEventSpecWritten, TicketEventPROpened, TicketEventPRMerged, TicketEventResultsCompleted} -var ticketEventReasons = []string{ReasonTicketNoSpec, ReasonTicketNoPR, ReasonTicketMergeNotRecorded, ReasonTicketNotResultsArtifact, ReasonTicketNotCompleted} +var ticketEventReasons = []string{ReasonTicketNoSpec, ReasonTicketNoPR, ReasonTicketMergeNotRecorded, ReasonTicketNotResultsArtifact, ReasonTicketNotCompleted, ReasonTicketKilled} var ticketStates = []string{TicketStateLinked, TicketStateNotLinked, TicketStatePartial} // TicketContextRequest is the closed request. Event "" is a no-event read. @@ -339,6 +340,8 @@ func ticketEvent(c domain.Change, name string, pin StatusPin) *TicketContextEven e.Switch = auto.PRMerged.Value switch { case prMerged(c): + case c.Status() == domain.StatusKilled: + e.Reason = ReasonTicketKilled case !hasPR: e.Reason = ReasonTicketNoPR default: @@ -349,6 +352,8 @@ func ticketEvent(c domain.Change, name string, pin StatusPin) *TicketContextEven switch { case c.Deliverable() != domain.DeliverableResultsArtifact: e.Reason = ReasonTicketNotResultsArtifact + case c.Status() == domain.StatusKilled: + e.Reason = ReasonTicketKilled case c.Status() != domain.StatusDone: e.Reason = ReasonTicketNotCompleted } diff --git a/internal/app/ticket_context_skill_test.go b/internal/app/ticket_context_skill_test.go index 3c2f4112c..586ccccd6 100644 --- a/internal/app/ticket_context_skill_test.go +++ b/internal/app/ticket_context_skill_test.go @@ -21,8 +21,8 @@ func TestUpdateTicketSkillNamesEveryReadToken(t *testing.T) { tokens = append(tokens, ticketEvents...) tokens = append(tokens, ticketEventReasons...) tokens = append(tokens, ticketStates...) - if len(tokens) != 12 { - t.Fatalf("context.ticket reports %d tokens, want 12 (4 events, 5 reasons, 3 states); update this guard with the producer", len(tokens)) + if len(tokens) != 13 { + t.Fatalf("context.ticket reports %d tokens, want 13 (4 events, 6 reasons, 3 states); update this guard with the producer", len(tokens)) } for _, tok := range tokens { if !strings.Contains(body, "`"+tok+"`") { diff --git a/internal/app/ticket_context_test.go b/internal/app/ticket_context_test.go index 2cb0cfe4c..d64577c2a 100644 --- a/internal/app/ticket_context_test.go +++ b/internal/app/ticket_context_test.go @@ -123,18 +123,20 @@ func TestContextTicketKilledChange(t *testing.T) { event string extra string happened bool + reason string }{ - {TicketEventPRMerged, "pr: '" + ticketPR + "'\nspec: " + ticketSpecPath + "\n", false}, - {TicketEventResultsCompleted, "deliverable: results-artifact\nspec: " + ticketSpecPath + "\n", false}, - {TicketEventSpecWritten, "pr: '" + ticketPR + "'\nspec: " + ticketSpecPath + "\n", true}, + {TicketEventPRMerged, "pr: '" + ticketPR + "'\nspec: " + ticketSpecPath + "\n", false, ReasonTicketKilled}, + {TicketEventPRMerged, "spec: " + ticketSpecPath + "\n", false, ReasonTicketKilled}, + {TicketEventResultsCompleted, "deliverable: results-artifact\nspec: " + ticketSpecPath + "\n", false, ReasonTicketKilled}, + {TicketEventSpecWritten, "pr: '" + ticketPR + "'\nspec: " + ticketSpecPath + "\n", true, ""}, } for _, tc := range cases { - t.Run(tc.event, func(t *testing.T) { + t.Run(tc.event+"/"+tc.reason, func(t *testing.T) { blob := ticketRecordBlob(1, "a", "killed", tc.extra) got, _ := readTicket(t, ticketPin(t), []StatusBlob{blob}, nil, TicketContextRequest{ID: 1, Event: tc.event}) c := mustApplied(t, got) - if c.Event == nil || c.Event.Happened != tc.happened { - t.Errorf("event = %+v, want happened=%t", c.Event, tc.happened) + if c.Event == nil || c.Event.Happened != tc.happened || c.Event.Reason != tc.reason { + t.Errorf("event = %+v, want happened=%t reason=%q", c.Event, tc.happened, tc.reason) } }) } diff --git a/internal/assets/embedded/manifest.json b/internal/assets/embedded/manifest.json index c5b695b87..00bb5f482 100644 --- a/internal/assets/embedded/manifest.json +++ b/internal/assets/embedded/manifest.json @@ -1,7 +1,7 @@ { "format_version": 1, "asset_protocol": 1, - "asset_set_id": "sha256:d4b9df8648a294d6db10f4dcff89de00f6ad801abd194f1349942f3b6b38cc39", + "asset_set_id": "sha256:efeb144bc2cfbd297678aa010c17066412cd3de287f6e8f58b1c31a5e8f98eb6", "entries": [ { "path": ".docket.example.yml", @@ -462,8 +462,8 @@ "path": "skills/docket-update-ticket/SKILL.md", "role": "skill", "mode": 420, - "size": 9031, - "sha256": "095912c1560777e798648882ea5667fe77484a473ceea5e24ed039bbe51b8cea" + "size": 9141, + "sha256": "6384faad6a24e1a3d64b8cd78da09d73f9432bc7524d361355c9a5214cd8fc09" }, { "path": "skills/docket-update-ticket/references/shared.md", 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 4ea7498de..5a7a3c1bb 100644 --- a/internal/assets/embedded/tree/skills/docket-update-ticket/SKILL.md +++ b/internal/assets/embedded/tree/skills/docket-update-ticket/SKILL.md @@ -29,7 +29,7 @@ Post nothing and say why in one plain line when: - `ticket.state` is `not-linked`: say the change has no ticket (`#612 has no ticket`). - `ticket.state` is `partial`: the link is broken; point the person to `docket-link-ticket` to fix or remove it. - The request names a different ticket than `ticket.id`: say which ticket the change carries. -- `event.happened` is false: name the missing fact from `event.reason`. `no-spec`: the change has no spec. `no-pr`: it has no PR. `not-results-artifact`: it does not end in a results file. `not-completed`: its results are not complete. `merge-not-recorded`: say docket has not recorded a merge for the change and that, if the PR has merged, refreshing with `docket-status` records it; never say the PR has not merged. +- `event.happened` is false: name the missing fact from `event.reason`. `no-spec`: the change has no spec. `no-pr`: it has no PR. `not-results-artifact`: it does not end in a results file. `not-completed`: its results are not complete. `merge-not-recorded`: say docket has not recorded a merge for the change and that, if the PR has merged, refreshing with `docket-status` records it; never say the PR has not merged. `killed`: the change was killed, so there is no merge or results update to post; offer a kill update instead. - `visibility` is `private`: say private repositories are not supported yet. ## 3. Write the update diff --git a/internal/repoguard/budgets_test.go b/internal/repoguard/budgets_test.go index dea760f93..7af3a2131 100644 --- a/internal/repoguard/budgets_test.go +++ b/internal/repoguard/budgets_test.go @@ -221,7 +221,7 @@ 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", 98, 1431}, // 0585: new — the inline ticket-update skill + {"docket-update-ticket/SKILL.md", 98, 1451}, // 0585 review: a killed change reports the killed reason (98/1431 -> 98/1451); 0585: new — the inline ticket-update skill {"docket-update-ticket/references/shared.md", 9, 184}, // 0585: new — shared delivery } diff --git a/skills/docket-update-ticket/SKILL.md b/skills/docket-update-ticket/SKILL.md index 4ea7498de..5a7a3c1bb 100644 --- a/skills/docket-update-ticket/SKILL.md +++ b/skills/docket-update-ticket/SKILL.md @@ -29,7 +29,7 @@ Post nothing and say why in one plain line when: - `ticket.state` is `not-linked`: say the change has no ticket (`#612 has no ticket`). - `ticket.state` is `partial`: the link is broken; point the person to `docket-link-ticket` to fix or remove it. - The request names a different ticket than `ticket.id`: say which ticket the change carries. -- `event.happened` is false: name the missing fact from `event.reason`. `no-spec`: the change has no spec. `no-pr`: it has no PR. `not-results-artifact`: it does not end in a results file. `not-completed`: its results are not complete. `merge-not-recorded`: say docket has not recorded a merge for the change and that, if the PR has merged, refreshing with `docket-status` records it; never say the PR has not merged. +- `event.happened` is false: name the missing fact from `event.reason`. `no-spec`: the change has no spec. `no-pr`: it has no PR. `not-results-artifact`: it does not end in a results file. `not-completed`: its results are not complete. `merge-not-recorded`: say docket has not recorded a merge for the change and that, if the PR has merged, refreshing with `docket-status` records it; never say the PR has not merged. `killed`: the change was killed, so there is no merge or results update to post; offer a kill update instead. - `visibility` is `private`: say private repositories are not supported yet. ## 3. Write the update From 5bb7268fb369ef6d143c624a113b5cf6c0344d9a Mon Sep 17 00:00:00 2001 From: Daniel Hanold Date: Tue, 10 Nov 2026 08:28:38 -0500 Subject: [PATCH 8/9] fix(skills): show the update example's mention as a placeholder, never a typed @-mention Review finding: docket-update-ticket's lead example opened with a bold plain-text mention, the stand-in its Mentions rule forbids. The example now uses and says it stands for the ticket system's real mention. A guard rejects a bold at-mention anywhere in the skill and a typed at-mention on any example line. --- internal/assets/embedded/manifest.json | 6 ++--- .../tree/skills/docket-update-ticket/SKILL.md | 4 ++-- internal/repoguard/budgets_test.go | 2 +- internal/repoguard/prose_contracts_test.go | 1 + .../repoguard/update_ticket_skill_test.go | 24 +++++++++++++++++++ skills/docket-update-ticket/SKILL.md | 4 ++-- 6 files changed, 33 insertions(+), 8 deletions(-) diff --git a/internal/assets/embedded/manifest.json b/internal/assets/embedded/manifest.json index 00bb5f482..2b29846a8 100644 --- a/internal/assets/embedded/manifest.json +++ b/internal/assets/embedded/manifest.json @@ -1,7 +1,7 @@ { "format_version": 1, "asset_protocol": 1, - "asset_set_id": "sha256:efeb144bc2cfbd297678aa010c17066412cd3de287f6e8f58b1c31a5e8f98eb6", + "asset_set_id": "sha256:b2a56c7fbad8112506d9cb17f2a77b02ae43fce21a61315f1d5caf6244e6e1fc", "entries": [ { "path": ".docket.example.yml", @@ -462,8 +462,8 @@ "path": "skills/docket-update-ticket/SKILL.md", "role": "skill", "mode": 420, - "size": 9141, - "sha256": "6384faad6a24e1a3d64b8cd78da09d73f9432bc7524d361355c9a5214cd8fc09" + "size": 9232, + "sha256": "82f907fcabb727b1a28f16539ce5e8a8db68eb39d5d80635f71f63770f8ce80c" }, { "path": "skills/docket-update-ticket/references/shared.md", 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 5a7a3c1bb..6f507190f 100644 --- a/internal/assets/embedded/tree/skills/docket-update-ticket/SKILL.md +++ b/internal/assets/embedded/tree/skills/docket-update-ticket/SKILL.md @@ -48,9 +48,9 @@ A late update never misstates the current state: compare the event with the curr **Editorial standard.** Updates are for people: a few short sentences or bullets, scaled to how much the update matters. Include, when relevant, what happened; what matters (key outcomes, consequential decisions, limitations); what is needed next from the reader (an action, test, review, or decision); and the links. Leave out how you worked, brainstorming notes and work logs, file lists, test inventories, command output, repeated background, filler, empty headings, and pasted artifact contents. Keep every material blocker, risk, and required action, however short the update. Say only what the change and its evidence support: a merge is not a deployment or an acceptance. -**Layout.** Write for a person reading the comment in the ticket system. Lay it out so it scans: short paragraphs, a list, or a single line, whichever reads best for this update. Use the format the connector accepts, so the layout survives posting. Label links (`Spec:`, `Results:`). The examples show tone, length, and layout: +**Layout.** Write for a person reading the comment in the ticket system. Lay it out so it scans: short paragraphs, a list, or a single line, whichever reads best for this update. Use the format the connector accepts, so the layout survives posting. Label links (`Spec:`, `Results:`). The examples show tone, length, and layout; `` stands for the ticket system's real mention, never typed text: -> **@Jane Doe** — PR ready for review: https://github.com/acme/api/pull/48 +> — PR ready for review: https://github.com/acme/api/pull/48 > > Invalid requests now fail with a clear error before any work starts, instead of failing partway through. The API contract is unchanged, so existing clients need no update. > diff --git a/internal/repoguard/budgets_test.go b/internal/repoguard/budgets_test.go index 7af3a2131..fbd25179a 100644 --- a/internal/repoguard/budgets_test.go +++ b/internal/repoguard/budgets_test.go @@ -221,7 +221,7 @@ 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", 98, 1451}, // 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", 98, 1465}, // 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/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 a0f656b5f..672617f39 100644 --- a/internal/repoguard/prose_contracts_test.go +++ b/internal/repoguard/prose_contracts_test.go @@ -1649,6 +1649,7 @@ var alignmentContracts = []proseContract{ "**Several matches:** ask the person which one", "**No match:** ask the person whether to post without that mention or try a different spelling", "Never substitute plain text such as \"@Jane\", which notifies nobody.", + "`` stands for the ticket system's real mention, never typed text", "Report the update as posted only with the connector's confirmation", "Never run a retry loop.", "When `visibility` is `shared`, **read `references/shared.md` now (blocking)**.", diff --git a/internal/repoguard/update_ticket_skill_test.go b/internal/repoguard/update_ticket_skill_test.go index 2f5c9ef31..a9bbdae85 100644 --- a/internal/repoguard/update_ticket_skill_test.go +++ b/internal/repoguard/update_ticket_skill_test.go @@ -3,6 +3,7 @@ package repoguard import ( "os" "path/filepath" + "regexp" "strings" "testing" ) @@ -31,3 +32,26 @@ func TestUpdateTicketSkillIsInline(t *testing.T) { t.Errorf("%s routes to references/shared.md, which cannot be read: %v", name, err) } } + +// typedMention matches an at-sign directly before a name: the plain-text +// stand-in for a mention, which notifies nobody. +var typedMention = regexp.MustCompile(`@\p{L}`) + +// TestUpdateTicketSkillExamplesUseNoTypedMention keeps the skill's example +// comments from teaching the typed mention its Mentions rule forbids: no bold +// at-mention anywhere, and no at-sign before a name on any example +// (blockquote) line. +func TestUpdateTicketSkillExamplesUseNoTypedMention(t *testing.T) { + body := readRepoFile(t, "skills/docket-update-ticket/SKILL.md") + if strings.Contains(body, "**@") { + t.Errorf("skills/docket-update-ticket/SKILL.md contains a bold at-mention (`**@`); an example mention must be a placeholder for the connector's real mention") + } + for i, line := range strings.Split(body, "\n") { + if !strings.HasPrefix(strings.TrimSpace(line), ">") { + continue + } + if typedMention.MatchString(line) { + t.Errorf("skills/docket-update-ticket/SKILL.md example line %d types a mention as plain text: %q", i+1, line) + } + } +} diff --git a/skills/docket-update-ticket/SKILL.md b/skills/docket-update-ticket/SKILL.md index 5a7a3c1bb..6f507190f 100644 --- a/skills/docket-update-ticket/SKILL.md +++ b/skills/docket-update-ticket/SKILL.md @@ -48,9 +48,9 @@ A late update never misstates the current state: compare the event with the curr **Editorial standard.** Updates are for people: a few short sentences or bullets, scaled to how much the update matters. Include, when relevant, what happened; what matters (key outcomes, consequential decisions, limitations); what is needed next from the reader (an action, test, review, or decision); and the links. Leave out how you worked, brainstorming notes and work logs, file lists, test inventories, command output, repeated background, filler, empty headings, and pasted artifact contents. Keep every material blocker, risk, and required action, however short the update. Say only what the change and its evidence support: a merge is not a deployment or an acceptance. -**Layout.** Write for a person reading the comment in the ticket system. Lay it out so it scans: short paragraphs, a list, or a single line, whichever reads best for this update. Use the format the connector accepts, so the layout survives posting. Label links (`Spec:`, `Results:`). The examples show tone, length, and layout: +**Layout.** Write for a person reading the comment in the ticket system. Lay it out so it scans: short paragraphs, a list, or a single line, whichever reads best for this update. Use the format the connector accepts, so the layout survives posting. Label links (`Spec:`, `Results:`). The examples show tone, length, and layout; `` stands for the ticket system's real mention, never typed text: -> **@Jane Doe** — PR ready for review: https://github.com/acme/api/pull/48 +> — PR ready for review: https://github.com/acme/api/pull/48 > > Invalid requests now fail with a clear error before any work starts, instead of failing partway through. The API contract is unchanged, so existing clients need no update. > From ab87dd3b6503c662eae7891dbd18f515a8824cb5 Mon Sep 17 00:00:00 2001 From: Daniel Hanold Date: Tue, 10 Nov 2026 08:30:45 -0500 Subject: [PATCH 9/9] fix(skills): pin update-ticket reads, name an unresolved merge parent, and correct the inline-skill glossary Three minor review findings: - docket-update-ticket now reads each artifact and the change record at the pinned metadata_commit from the metadata worktree (git -C show :), and names both its reads: context.ticket and, for a ticket-only request, status. - The PR-merged row says, when facts.merge.destination_branch is empty, that the change merged into its parent change's branch without naming it. - The glossary no longer claims docket-update-ticket works with you before posting; it posts without a draft. Guard phrases for the new wording join the change_0585 alignment rows (mutation-tested), the embedded assets are regenerated, and the update-ticket skill's word budget is re-baselined (1465 -> 1521). --- docs/reference/glossary.md | 2 +- internal/assets/embedded/manifest.json | 6 +++--- .../embedded/tree/skills/docket-update-ticket/SKILL.md | 6 +++--- internal/repoguard/budgets_test.go | 2 +- internal/repoguard/prose_contracts_test.go | 9 +++++++-- skills/docket-update-ticket/SKILL.md | 6 +++--- 6 files changed, 18 insertions(+), 13 deletions(-) diff --git a/docs/reference/glossary.md b/docs/reference/glossary.md index d894a249d..2a858f3c3 100644 --- a/docs/reference/glossary.md +++ b/docs/reference/glossary.md @@ -1893,7 +1893,7 @@ abort-and-report rule: implement-next, auto-groom, finalize-change, status, adr, review. **Interactive** skills (`docket-new-change`, `docket-groom-next`) stay inline at the session model, because the conversation with you is the point. They only advise a model at startup. `docket-export`, `docket-link-ticket`, and `docket-update-ticket` also stay inline, because they -post with your session's own tools and work with you before posting. +post with your session's own tools. **Used for:** knowing which skills you can dispatch and walk away from, and which need you at the keyboard. diff --git a/internal/assets/embedded/manifest.json b/internal/assets/embedded/manifest.json index 2b29846a8..3d47feeba 100644 --- a/internal/assets/embedded/manifest.json +++ b/internal/assets/embedded/manifest.json @@ -1,7 +1,7 @@ { "format_version": 1, "asset_protocol": 1, - "asset_set_id": "sha256:b2a56c7fbad8112506d9cb17f2a77b02ae43fce21a61315f1d5caf6244e6e1fc", + "asset_set_id": "sha256:d27ae524f5ca3e5196ed7dbb3cb96971784e4356b32112838a1b2ebbb636726e", "entries": [ { "path": ".docket.example.yml", @@ -462,8 +462,8 @@ "path": "skills/docket-update-ticket/SKILL.md", "role": "skill", "mode": 420, - "size": 9232, - "sha256": "82f907fcabb727b1a28f16539ce5e8a8db68eb39d5d80635f71f63770f8ce80c" + "size": 9655, + "sha256": "8abccaf9d68c80776191aaaed1167d60eeaf8b97a9ee92157b63c12c32e828cd" }, { "path": "skills/docket-update-ticket/references/shared.md", 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 6f507190f..45e004835 100644 --- a/internal/assets/embedded/tree/skills/docket-update-ticket/SKILL.md +++ b/internal/assets/embedded/tree/skills/docket-update-ticket/SKILL.md @@ -13,7 +13,7 @@ Words used here: a **ticket** is the item in the team's ticket system; the **pro 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. -This skill makes no docket write. Its one read is the `context.ticket` operation (argv from the capability catalog), run with `--id `, `--event ` when the update follows an event, and `--json`. Its result is under `context`: `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`). +This skill makes no docket write. Its reads are the `context.ticket` operation and, for a request naming only a ticket, the `status` operation (section 1). 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`). ## 1. Work out the request @@ -34,13 +34,13 @@ Post nothing and say why in one plain line when: ## 3. Write the update -Read what the update needs: each file in `artifacts` at its `path`, and the change record at `change.path` for `## Closeout notes` or `## Why killed`. The record is read, never linked. Plans never go out: no link to a plan and nothing from one. +Read what the update needs: each file in `artifacts` at its `path`, and the change record at `change.path` for `## Closeout notes` or `## Why killed`. Read each one as it stood at the pinned commit, from the metadata worktree (`metadata_worktree_path` from the startup check's `repository.prepare` context): `git -C show :`. The record is read, never linked. Plans never go out: no link to a plan and nothing from one. | Update | It says | Links | |---|---|---| | spec written | the approach and key decisions, and where the change stands now from its `status` (designed, not yet built; being built; built, PR open; merged); never a claim of review, approval, or authorship | the spec | | PR opened | the PR link, what was built, what the reviewer needs to know | the PR, the spec, and the results file | -| PR merged | what merged and where (`facts.merge.destination_branch`; when `in_integration` is false, say it is not yet in the integration branch), key outcomes, and anything left to do, from the results file's Outcome and Known issues and the record's `## Closeout notes`; never a claim of deployment or acceptance | the results file | +| PR merged | what merged and where (`facts.merge.destination_branch`; when it is empty, say it merged into its parent change's branch without naming the branch; when `in_integration` is false, say it is not yet in the integration branch), key outcomes, and anything left to do, from the results file's Outcome and Known issues and the record's `## Closeout notes`; never a claim of deployment or acceptance | the results file | | results completed | findings, conclusions, limits, and any action needed | the results file | | revision, blocker, or kill (no event) | what the person said, backed by the artifacts; for a kill, the record's `## Why killed` | the artifacts it discusses | diff --git a/internal/repoguard/budgets_test.go b/internal/repoguard/budgets_test.go index fbd25179a..8c44c40c9 100644 --- a/internal/repoguard/budgets_test.go +++ b/internal/repoguard/budgets_test.go @@ -221,7 +221,7 @@ 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", 98, 1465}, // 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", 98, 1521}, // 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/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 672617f39..a33823678 100644 --- a/internal/repoguard/prose_contracts_test.go +++ b/internal/repoguard/prose_contracts_test.go @@ -1653,8 +1653,11 @@ var alignmentContracts = []proseContract{ "Report the update as posted only with the connector's confirmation", "Never run a retry loop.", "When `visibility` is `shared`, **read `references/shared.md` now (blocking)**.", + "Its reads are the `context.ticket` operation and, for a request naming only a ticket, the `status` operation", + "`git -C show :`", + "when it is empty, say it merged into its parent change's branch without naming the branch", }, - absent: []string{"context: fork", "agent: docket-update-ticket"}}, + absent: []string{"context: fork", "agent: docket-update-ticket", "Its one read is"}}, {sentinel: "change_0585_update_ticket_skill", file: "skills/docket-update-ticket/references/shared.md", present: []string{ "Each `url` is pinned to `metadata_commit`", @@ -1678,7 +1681,9 @@ var alignmentContracts = []proseContract{ "- [docket-update-ticket](#docket-update-ticket)", "### Ticket context", "- [Ticket context](#ticket-context)", - }}, + "`docket-export`, `docket-link-ticket`, and `docket-update-ticket` also stay inline, because they\npost with your session's own tools.", + }, + absent: []string{"work with you before posting"}}, {sentinel: "change_0585_update_ticket_skill", file: "docs/reference/config-keys.md", present: []string{ "| `tickets.provider` | `\"\"` (unset) | repo-only | the ticket system this repository's changes link to (jira, linear, …); used when linking or creating a ticket |", diff --git a/skills/docket-update-ticket/SKILL.md b/skills/docket-update-ticket/SKILL.md index 6f507190f..45e004835 100644 --- a/skills/docket-update-ticket/SKILL.md +++ b/skills/docket-update-ticket/SKILL.md @@ -13,7 +13,7 @@ Words used here: a **ticket** is the item in the team's ticket system; the **pro 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. -This skill makes no docket write. Its one read is the `context.ticket` operation (argv from the capability catalog), run with `--id `, `--event ` when the update follows an event, and `--json`. Its result is under `context`: `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`). +This skill makes no docket write. Its reads are the `context.ticket` operation and, for a request naming only a ticket, the `status` operation (section 1). 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`). ## 1. Work out the request @@ -34,13 +34,13 @@ Post nothing and say why in one plain line when: ## 3. Write the update -Read what the update needs: each file in `artifacts` at its `path`, and the change record at `change.path` for `## Closeout notes` or `## Why killed`. The record is read, never linked. Plans never go out: no link to a plan and nothing from one. +Read what the update needs: each file in `artifacts` at its `path`, and the change record at `change.path` for `## Closeout notes` or `## Why killed`. Read each one as it stood at the pinned commit, from the metadata worktree (`metadata_worktree_path` from the startup check's `repository.prepare` context): `git -C show :`. The record is read, never linked. Plans never go out: no link to a plan and nothing from one. | Update | It says | Links | |---|---|---| | spec written | the approach and key decisions, and where the change stands now from its `status` (designed, not yet built; being built; built, PR open; merged); never a claim of review, approval, or authorship | the spec | | PR opened | the PR link, what was built, what the reviewer needs to know | the PR, the spec, and the results file | -| PR merged | what merged and where (`facts.merge.destination_branch`; when `in_integration` is false, say it is not yet in the integration branch), key outcomes, and anything left to do, from the results file's Outcome and Known issues and the record's `## Closeout notes`; never a claim of deployment or acceptance | the results file | +| PR merged | what merged and where (`facts.merge.destination_branch`; when it is empty, say it merged into its parent change's branch without naming the branch; when `in_integration` is false, say it is not yet in the integration branch), key outcomes, and anything left to do, from the results file's Outcome and Known issues and the record's `## Closeout notes`; never a claim of deployment or acceptance | the results file | | results completed | findings, conclusions, limits, and any action needed | the results file | | revision, blocker, or kill (no event) | what the person said, backed by the artifacts; for a kill, the record's `## Why killed` | the artifacts it discusses |