From 66be1fc7a4648fad02d38817ed6c8fe742464764 Mon Sep 17 00:00:00 2001 From: Daniel Hanold Date: Mon, 9 Nov 2026 21:01:40 -0500 Subject: [PATCH 1/8] Add design spec: Create a ticket from a change, or a change from a ticket --- ...change-or-a-change-from-a-ticket-design.md | 150 ++++++++++++++++++ 1 file changed, 150 insertions(+) create mode 100644 docs/superpowers/specs/2026-11-10-create-a-ticket-from-a-change-or-a-change-from-a-ticket-design.md diff --git a/docs/superpowers/specs/2026-11-10-create-a-ticket-from-a-change-or-a-change-from-a-ticket-design.md b/docs/superpowers/specs/2026-11-10-create-a-ticket-from-a-change-or-a-change-from-a-ticket-design.md new file mode 100644 index 000000000..e262d2062 --- /dev/null +++ b/docs/superpowers/specs/2026-11-10-create-a-ticket-from-a-change-or-a-change-from-a-ticket-design.md @@ -0,0 +1,150 @@ +# Create a ticket from a change, or a change from a ticket — design + +Change 0584 — Create a ticket from a change, or a change from a ticket + +Change #584, groomed interactively on 2026-11-09. Position 3 of the ticket-integration split planned by change 581. This spec restates every settled decision it carries, so the build needs nothing from 581's spec or results. + +## Intent + +An engineer should be able to hand docket work to a ticket system as a clear request, or pull a ticket into docket, without retyping it, while keeping the request (the problem, the outcome, the scope) separate from any proposed solution. The main case is **push**: a docket change goes out to Jira for someone else to pick up. Link and import are in scope but secondary. + +## Vocabulary + +- **ticket**: the item in the team's ticket system (a Jira issue, a Linear issue, a GitHub issue, an Azure DevOps work item). Never "issue" (reads as a GitHub issue, and collides with the retired `issue:` field), "work item", or "story". +- **provider**: which ticket system (`jira`, `linear`, …), a free lowercase token. +- **connector**: the harness's own tools for a ticket system (an MCP server or plugin the harness owner installed and authenticated). Docket installs no connector, stores no credential, and contains no provider API code. + +## Goals + +1. A new inline skill, `docket-link-ticket`, always attended, with three paths: **link** an existing ticket, **create** a ticket from a change (push), and **import** a ticket into a new proposed change. +2. `status --json` reports every linked change's ticket, active or archived, so the skill can tell whether a change already has a ticket and which changes a ticket is already on. +3. When the change has a linked spec, the created ticket carries it as the proposed approach. +4. `docket-export` stops claiming ticket work in its trigger description. + +## Non-goals + +- Posting updates (comments) to a ticket, on request or automatically (changes 585–588). An update request ("update CLOUD-123 now that the PR is open") is not this skill's. +- Automatic ticket creation when a change is created (change 587). This skill runs only when the person asks. +- Rewriting a ticket's description after creation, ever. +- Syncing ticket status, assignee, sprint, or workflow; inbound sync of comments; importing a ticket's comments or attachments. +- Any ticket-system call from the docket repository (see *Testing*). +- Any board change. + +## Settled decisions (fixed by 581 and 583 — not reopened) + +- **Always attended.** All three paths run only when a person asks, in their own session. No autonomous workflow ever creates a ticket. +- **Ticket fields** are three flat scalars on the change — `ticket_provider`, `ticket_id`, `ticket_url` — written only by the `change.link-ticket` operation (link, replace with `replace: true`, unlink with `unlink: true`; any status; refuses a partial set) and accepted by `change.create` at creation (all three or none). A partial or invalid set counts as not linked and is reported as the `ticket-link-invalid` warning. Replacing or unlinking happens only on the person's explicit plain-words request ("switch it to CLOUD-456"); the agent never replaces a link on its own initiative. +- **Record only after confirmation.** The ticket fields are written only after the connector confirms the ticket was created (or, for link, that the ticket exists). Nothing is ever reported as created or attached without the connector's confirmation. +- **Description written once.** Creating a ticket writes its description once; docket never rewrites it afterwards. +- **Config** (`tickets.*`, per-repo only, read through the `diagnostic.config` operation at `effective.tickets..value`): `provider` (which tool), `site` (where it lives, e.g. `acme.atlassian.net`), `project` (where new tickets go; generic — the skill maps it to the provider's own term: a Jira project, a Linear team, a GitHub repository). No ticket-type key. The `tickets.auto.*` switches are not this change's (587). +- **Readiness check (create).** Could another engineer take ownership of this as a user story? The check covers: the problem and why it matters; the desired outcome; bounded scope and non-goals; genuine constraints, kept distinct from implementation preferences; clear, verifiable acceptance criteria that belong to this change; and no open question that blocks understanding. Technical questions may stay open — the request must be ready for ownership, not necessarily for coding. A spec is not required, and an existing spec never turns its technical choices into requirements. +- **Refinement (create), only if needed.** Ask targeted questions about what is missing and write the answers into the change through `change.groom`'s owned sections (`outcome: revise`), which works only while the change is `proposed`. For a change past `proposed`, the ticket is built from the change as it stands: if it is not story-ready, the agent names what is missing and the person decides whether to go ahead. **The agent never invents scope or acceptance criteria and never promotes an unreviewed solution into a requirement.** +- **Ticket body.** The change exported with `docket-export`'s machinery and the `ticket` export kind (`docket open change --export --print --json`): its H1 is the title, its body keeps exactly Why, What changes, Acceptance criteria, Out of scope, and Open questions. In a private repository it gets docket-export's private cleanup. When the target needs its own markup (Jira's), only formatting is converted, never words. +- **Ticket type.** No ticket type is configured. The agent reads the ticket types the project actually has through the connector (in Jira, `listJiraProjectIssueTypesMetadata`) and maps the change's `type`: `fix` → the bug type; `feat` → the story or feature type; anything else → the task type. With no obvious match, it asks. A tool without ticket types (Linear, Asana, Trello) gets none. The mapped type appears in the draft. +- **Import.** Read the ticket through the connector and distill it into a new proposed change (Why, What changes, Acceptance criteria, Out of scope, Open questions) with the ticket fields set at creation. The change's `type` is mapped from the ticket's type to one of the configured `change_types` (a Bug → `fix`, a Story → `feat`); with no obvious match, the agent asks. One time only: no ongoing inbound sync. +- **Connector operations may be hidden.** Some connectors expose operations only through a discovery tool (the Atlassian connector's `discover`), not as directly listed tools. The skill must never conclude an operation is missing because it is not in the tool list. +- **Failure posture.** Connector missing, a call failed, or an uncertain outcome: say so plainly; an uncertain outcome is reported as uncertain and the person decides whether to try again. No retry machinery, no ledger. + +## Decisions made in grooming + +### 1. The binary: `status --json` reports the ticket + +`StatusRecord` (`internal/app/status_result.go`), the per-record inventory in `status --json`'s `records` array, gains an optional `ticket` object — `provider`, `id`, `url` — on rows of kind `change`, present only when the change is linked (all three fields present and valid, the shared domain rule 583 built). Same shape and presence rule as `context.implementation`'s `ContextTicket`: reuse that type or its builder; do not invent a second shape. The `status` operation's `schema` descriptor follows from the Go type. + +Why `records`, not the `changes` rows (a builder-check finding, verified): `changes` lists only active changes that pass the type/priority filter (`activeChanges` in `internal/app/status.go`), while `records` lists every change, active and archived, independent of the filter, with the `path` and `revision` a write needs. The skill needs both cases: linking a `done` change, and seeing which changes — archived ones included — already carry a ticket. Putting archived changes into `changes` would change what every status reader sees; rejected. + +Rejected in grooming: a `has_ticket` boolean. Push needs to name *which* ticket the change already has, and import needs to compare ticket ids across changes; a boolean serves neither, and a skill would fall back to reading raw frontmatter for an optional key (learning `frontmatter-anchored-read`). + +### 2. Skill layout and loading + +``` +skills/docket-link-ticket/ + SKILL.md # shared rules + routing + the link path + references/create.md # push: readiness, refinement, draft, spec, type, create, attach, record + references/import.md # import: read, distill, draft, create, open questions +``` + +- **Inline skill**: frontmatter is exactly `name` and `description` — no `context: fork`, no agent wrapper (a forked skill cannot reach the session's connector tools or ask the person). Same posture as `docket-export`. +- **Loads `docket-convention`** and runs its startup check (capability bootstrap, `repository.prepare`), like the other skills that write change records. Request bodies for `change.groom`, `change.create`, and `change.link-ticket` are built from each operation's `schema` descriptor. Record `path` + `revision` come from `status --json`; a `contended` refusal means re-sync, re-read, and retry, or stop if the change moved out from under the request. +- `SKILL.md` loads `references/create.md` only when pushing and `references/import.md` only when importing; the link path is short enough to live in `SKILL.md`. + +### 3. Trigger wording + +The description names all three asks in the person's words — link a change to a ticket ("link #12 to CLOUD-123"), create a ticket from a change ("create a Jira ticket from #12", "put #12 in Jira"), make a change from a ticket ("make a change from CLOUD-123") — and says posting an update is not this skill's job. Exact wording is the builder's. + +### 4. Shared rules in `SKILL.md` + +- **Resolve where tickets go.** Read `tickets.provider`, `tickets.site`, `tickets.project` from `diagnostic.config`. When one the path needs is empty, ask the person for this run. The skill never edits config. +- **Find the connector** for the provider, including through any discovery tool. None available: say so, create and record nothing, and stop. +- **Known links come from `status --json`'s `records`** (rows of kind `change`, their `ticket`). A change is linked only when that object is present. A change whose record shows a `ticket-link-invalid` finding (a hand-edited partial or invalid set) is not linked, but `change.link-ticket` will not write over it without `replace: true` — so every path that would write a link to it stops first and asks the person to fix or remove the broken link (link with `replace: true`, or unlink) before anything else happens. +- **One ticket may be on several changes** (decided in grooming: one ticket can be split into several docket changes). Linking or importing a ticket that another change already carries is allowed; the agent names the other change(s) ("CLOUD-123 is also on #10") and goes ahead. + +### 5. Link path + +1. The person gives a change and a ticket (URL, or id when the site is configured). +2. **Provider:** when the URL's host matches `tickets.site`, the provider is `tickets.provider`; otherwise ask. **Id:** the ticket's key as the provider shows it, read through the connector (preferred) or from the URL. +3. Confirm the ticket exists through the connector when a connector is available. With none, the person may still link by URL — the link is a record, not a ticket call — and the report says the ticket was not verified. *(Builder's call how to word it.)* +4. If other changes already carry this ticket, name them (allowed; see shared rules). +5. Run `change.link-ticket`. `already-linked-elsewhere` → tell the person which ticket the change carries now and replace only if they say so (`replace: true`). Unlink only on request. + +### 6. Push path (`references/create.md`) + +1. **Already linked?** If the change's `status --json` record shows a `ticket`, refuse and name it ("#12 is already linked to CLOUD-123 "). Nothing else happens. A `ticket-link-invalid` finding on the change also stops here (shared rules): otherwise the ticket would be created and could never be recorded. +2. **Readiness check** (settled criteria above). +3. **Refinement, only if needed** (settled above): targeted questions, answers written through `change.groom` `outcome: revise` owned sections (`## Acceptance criteria` included) while `proposed`; past `proposed`, name what is missing and let the person decide; never invent. +4. **Ticket type** (settled mapping above). +5. **Export the body** by invoking `docket-export` as a **file request** — never restating its rules — with a call-site direction: export `change ` to a fresh temporary directory (`--output-path` from `mktemp -d "${TMPDIR:-/tmp}/docket-link-ticket.XXXXXX"`), and return the path and, in a private repository, the before → after list; post nothing. docket-export's file-request path already runs the private rewrite pass and word check and returns the list with no stop, because nothing is posted; the list goes into this skill's draft instead, so the person approves once. (581's answer (b) recommended this same reuse for unattended updates.) +6. **Spec, when the change has a linked `spec:`** — always included, with no separate question (decided in grooming: the person's go on the draft is the only approval). It is labeled as the proposed approach, never as requirements: + - **Shared repository:** the body ends with one line, e.g. `Proposed approach: `, where the link is the URL `docket open spec --print --json` returns (the spec on the metadata branch on GitHub). A branch link, not a commit-pinned one: the description is written once and never rewritten, so a pinned link would go stale after a later spec revision; the branch link always shows the current design. + - **Shared repository with no URL:** `open` returns a URL only when the remote is GitHub and `open.artifacts` is not `local`; otherwise `target_kind` is `file`. A local path is never put in a ticket: the spec is exported (docket-export file request, as for the body) and attached exactly as in a private repository. + - **Private repository:** the spec is exported through `docket-export` as a file request (as for the body), with the same private cleanup, and attached to the ticket after it exists. The body ends with one line naming the attachment, e.g. `Proposed approach: see the attached `. +7. **Draft and approval.** Show the person, in one message: the title, the project, the mapped type, the body as it will be posted, the spec line or attachment name, and — in a private repository — the before → after list of every rewrite in the body and the spec. Create only on their go. A docket-export word-check hit stops the draft the way docket-export does: show the lines, post nothing until the person decides. +8. **Create** the ticket through the connector (summary = the export's H1; description = the rest, formatting converted only). +9. **Attach (private, spec present).** Upload the cleaned spec. In the Claude Code harness the Jira connector attaches in two steps (`uploadAttachmentToJiraIssue` returns an upload command to run from the shell, then the returned file id is attached); never assume a one-call upload, and never substitute a local path for an attachment. If the upload fails, the ticket stays (its description cannot be rewritten): report the failure and the exported file's path so the person can attach it by hand. +10. **Record** with `change.link-ticket` (provider, the created ticket's id, its URL) after the connector confirms creation. If recording fails, report the created ticket's URL and retry the link (fresh `path` + `revision`); **never create a second ticket**. +11. **Report:** the ticket link, the type, whether the spec was linked or attached, any rewrite list. + +### 7. Import path (`references/import.md`) + +1. **Read the ticket** through the connector. +2. **Already on a change?** If any change record in `status --json` (active or archived) carries a `ticket` with the same provider and id, name it in the draft ("CLOUD-123 is also on #10"). Allowed, not refused (shared rules); the person's go on the draft decides. +3. **Distill** into a draft change: title from the ticket summary; Why, What changes, Acceptance criteria, Out of scope, Open questions from its content; `type` mapped as settled. Never invent: `change.create` requires Why, What changes, and Out of scope — when the ticket gives no basis for one, ask the person. +4. **Draft and approval.** Show the drafted change (title, type, sections, ticket) and create on the person's go. +5. **Create** with `change.create` (`ticket_provider`, `ticket_id`, `ticket_url` set; default priority). `change.create` cannot write `## Open questions`; when the draft has open questions, follow with one `change.groom` `outcome: revise` carrying that section (fresh `path` + `revision` from `status --json`). +6. **Report** the new change id and its link. + +The imported change is a plain needs-grooming stub (no spec); the person grooms it as usual. + +### 8. `docket-export` stops claiming ticket work + +`skills/docket-export/SKILL.md`'s description drops "a Jira ticket body or comment" (keeping documents, messages, emails, and "anything outside docket"); its body gains one sentence: creating a ticket from a change, or linking or importing one, is `docket-link-ticket`'s, which calls this skill for a file export. The sentence must not send a file request from `docket-link-ticket` back there — the two skills point at each other only in that one direction each. Posting an update comment is not added back here — that will be `docket-update-ticket`'s (585). `TestExportSkillIsInline`'s description clauses and the `change_0578_export_skill` prose sentinels are updated to match. + +### 9. Convention and docs + +- The convention (`skills/docket-convention/SKILL.md`, agent-layer paragraph) and `references/agent-layer.md` (fork-exclusion principle) name `docket-link-ticket` beside `docket-export` as an inline skill. +- `docs/reference/skills-and-agents.md` gains a `docket-link-ticket` entry; the `docket-export` entry drops "or put one into another tool" only if it reads as ticket creation (builder's call). +- Generated surfaces: regenerate the embedded tree and manifest with `go generate ./internal/assets/`. Install picks up the new skill by glob; no registration code is needed (as with `docket-export` in 578). +- Skill prose ships into other repositories: no sentence true only in the docket repository (learning `distributed-body-has-no-local-repo`), and no sandbox site, project, or real ticket key. + +### 10. ADR + +Record via docket-adr at build: **Ticket work is two inline skills, split by attended linking versus updating** — `docket-link-ticket` (link, create, import; always the person) and `docket-update-ticket` (updates; the person or nobody), both inline, harness-neutral, posting with the agent's own connector tools; autonomous workflows only ever load the update skill, so refinement and import instructions never take space in an implement or finalize run. 581's plan assigned this ADR to "the first skill built"; that is now this change, not 585. + +## Acceptance criteria + +- `status --json`'s `records` rows of kind `change` show `ticket: {provider, id, url}` on a linked change (active and archived) and no `ticket` on an unlinked change or one with a partial or invalid set; the `changes` rows are unchanged; the `status` schema descriptor lists it. +- `skills/docket-link-ticket/SKILL.md` is inline (frontmatter exactly `name`, `description`; no agent wrapper), and its text with its two references covers: link (provider from site match or asked; replace and unlink only on request; a ticket already on another change is named and allowed; a broken link stops first); push (already-linked and broken-link refusals, readiness criteria, refinement only while proposed, never invent, type mapping, draft with one approval, spec always included — branch link shared, attachment private or when no URL — create, attach in two steps, record only after confirmation, no second ticket on a failed record); import (a ticket already on a change is named and allowed, never invent, draft approval, ticket fields at creation, open questions follow-up). +- `docket-export`'s description no longer mentions a Jira ticket body or comment, and its body points ticket work to `docket-link-ticket`. +- Repository tests guard the skill's inline shape and its key rules (prose sentinels bound to their claims), and budget rows exist for the new files. +- Results list an Important live check, run from another repository against a sandbox ticket project, covering push from a shared and from a private repository (with a spec), link, and import. + +## Testing + +- **No ticket-system call is ever made from the docket repository.** No build, test, review, or results run posts to, creates, or reads a real ticket, and docket's own `.docket.yml` never carries `tickets.*` keys (583's guard). Connector behavior lives in skill text only. +- `status --json`'s `ticket` gets Go tests: linked, unlinked, partial, invalid, archived, and filtered out of `changes` by a type filter but still in `records`. +- Prose guards follow the repo's rules: mutation-test each, bind phrases to claims, collapse whitespace before matching. +- **Live check (human, results `## Human actions and testing`, Important):** after the PR opens and before merge, from a scratch repository (shared, and private with `tickets.*` in `.git/dckt/config.yml`) against a sandbox project: push a groomed change with a spec, push a stub that needs refinement, link an existing ticket, import a ticket. Not a build stop; no `hold`. + +## Left to the builder + +Exact skill wording and description; how `StatusRecord` reuses `ContextTicket`; test names and sentinel phrasing; how the link path words an unverified link; the exact "Proposed approach" line format. From 8bc3514a25f3da42f2c6e4b1c31d5ece7426e593 Mon Sep 17 00:00:00 2001 From: Daniel Hanold Date: Mon, 9 Nov 2026 21:12:03 -0500 Subject: [PATCH 2/8] feat(status): report each linked change's ticket in the records inventory --- internal/app/schema_revision_test.go | 18 ++++++ internal/app/status.go | 1 + internal/app/status_result.go | 4 ++ internal/app/status_test.go | 91 ++++++++++++++++++++++++++++ 4 files changed, 114 insertions(+) diff --git a/internal/app/schema_revision_test.go b/internal/app/schema_revision_test.go index 005fbdc02..4467dca68 100644 --- a/internal/app/schema_revision_test.go +++ b/internal/app/schema_revision_test.go @@ -57,6 +57,24 @@ func TestSchemaRevisionKeys(t *testing.T) { } } +// TestSchemaStatusRecordTicket: the status result publishes the records +// inventory's ticket object, and only there — changes rows carry no ticket. +func TestSchemaStatusRecordTicket(t *testing.T) { + keys := schemaKeyPaths(t) + for _, p := range []string{ + "status RES records.ticket.provider", + "status RES records.ticket.id", + "status RES records.ticket.url", + } { + if !keys[p] { + t.Errorf("schema lacks %s", p) + } + } + if keys["status RES changes.ticket"] { + t.Error("schema publishes status RES changes.ticket") + } +} + // TestSchemaVocabularyRevisionCodes: the finding_codes vocabulary lists the // row-44a codes in their revision spelling and none of the retired ones. func TestSchemaVocabularyRevisionCodes(t *testing.T) { diff --git a/internal/app/status.go b/internal/app/status.go index ef9adc4f5..189ffe4f8 100644 --- a/internal/app/status.go +++ b/internal/app/status.go @@ -667,6 +667,7 @@ func corpusRecords(snap domain.Snapshot, blobByPath map[string]StatusBlob) []Sta Location: string(b.Location), Path: c.Path(), Revision: b.Revision, + Ticket: contextTicket(c), }) } diff --git a/internal/app/status_result.go b/internal/app/status_result.go index 4d626b666..8b961fc2d 100644 --- a/internal/app/status_result.go +++ b/internal/app/status_result.go @@ -71,6 +71,10 @@ type StatusRecord struct { Location string `json:"location"` // named domain location string Path string `json:"path"` Revision string `json:"revision"` // blob object id + // Ticket is the change's ticket link, set only on change rows whose + // Change.Ticket reports a complete, valid link; same shape as + // ContextEntitySummary.Ticket. + Ticket *ContextTicket `json:"ticket,omitempty"` } // StatusFinding is one normalized health finding. It carries the DTO's own diff --git a/internal/app/status_test.go b/internal/app/status_test.go index acd467e17..41ee04f73 100644 --- a/internal/app/status_test.go +++ b/internal/app/status_test.go @@ -208,6 +208,97 @@ func TestStatusRecordsOptIn(t *testing.T) { } } +// TestStatusRecordsCarryTicket: a records row for a change with a complete, +// valid ticket link carries that link exactly as stored — including an +// archived or type-filtered change absent from changes — while unlinked, +// partially linked, and invalid-URL changes and non-change rows carry no +// ticket key at all, and changes rows never do. +func TestStatusRecordsCarryTicket(t *testing.T) { + archived := changeBlob(5, "five", "fix", "high", + "ticket_provider: jira\nticket_id: CLOUD-500\nticket_url: 'https://tickets.example.com/browse/CLOUD-500'\n") + archived.Location = repository.LocationArchive + archived.Path = "docs/changes/archive/2026-01-03-0005-five.md" + archived.Data = []byte(strings.Replace(string(archived.Data), "status: proposed", "status: done", 1)) + fake := &fakeReader{ + pin: docketPin(t), + corpus: []StatusBlob{ + changeBlob(1, "linked", "feat", "high", "ticket_provider: jira\nticket_id: CLOUD-123\nticket_url: 'https://tickets.example.com/browse/CLOUD-123?focus=1'\n"), + changeBlob(2, "plain", "feat", "high", ""), + changeBlob(3, "partial", "feat", "high", "ticket_provider: jira\nticket_id: CLOUD-123\n"), + changeBlob(4, "badurl", "feat", "high", "ticket_provider: jira\nticket_id: CLOUD-123\nticket_url: 'javascript:x'\n"), + archived, + adrBlob(71, "an-adr"), + }, + facts: domain.NewBranchFacts(nil), + } + res := Status(context.Background(), fake, StatusOptions{IncludeRecords: true, Types: []string{"feat"}}) + if res.Result != ResultApplied { + t.Fatalf("result = %q, want applied; message=%q", res.Result, res.Message) + } + if res.Records == nil { + t.Fatal("IncludeRecords did not populate records") + } + want := map[string]*ContextTicket{ + "change/0001": {Provider: "jira", ID: "CLOUD-123", URL: "https://tickets.example.com/browse/CLOUD-123?focus=1"}, + "change/0002": nil, + "change/0003": nil, + "change/0004": nil, + "change/0005": {Provider: "jira", ID: "CLOUD-500", URL: "https://tickets.example.com/browse/CLOUD-500"}, + "adr/0071": nil, + } + seen := map[string]bool{} + for _, r := range *res.Records { + k := r.Kind + "/" + r.Identity + w, ok := want[k] + if !ok { + t.Errorf("unexpected record %s", k) + continue + } + seen[k] = true + if !reflect.DeepEqual(r.Ticket, w) { + t.Errorf("record %s ticket = %+v, want %+v", k, r.Ticket, w) + } + } + for k := range want { + if !seen[k] { + t.Errorf("record %s missing", k) + } + } + for _, c := range res.Changes { + if c.ID == 5 { + t.Errorf("archived fix change 5 appears in changes: %+v", c) + } + } + + b, err := json.Marshal(res) + if err != nil { + t.Fatal(err) + } + var doc struct { + Records []map[string]any `json:"records"` + Changes []map[string]any `json:"changes"` + } + if err := json.Unmarshal(b, &doc); err != nil { + t.Fatal(err) + } + for _, r := range doc.Records { + _, has := r["ticket"] + id, _ := r["identity"].(string) + wantKey := r["kind"] == "change" && (id == "0001" || id == "0005") + if has != wantKey { + t.Errorf("record %v/%s: ticket key present = %v, want %v (%v)", r["kind"], id, has, wantKey, r["ticket"]) + } + } + if len(doc.Changes) == 0 { + t.Fatal("no changes rows to check") + } + for _, c := range doc.Changes { + if _, has := c["ticket"]; has { + t.Errorf("changes row carries a ticket key: %v", c) + } + } +} + // TestStatusSourceDistinction is the artifact-source-distinction probe target: // the operation asks the metadata source for the spec, the plan, and the // results, and asks the integration source for a plan or results only when the From 8a7c6454691e1363125cc2e255fc3c74f067c3c4 Mon Sep 17 00:00:00 2001 From: Daniel Hanold Date: Mon, 9 Nov 2026 21:15:27 -0500 Subject: [PATCH 3/8] feat(skills): add the inline docket-link-ticket skill with its link path --- internal/assets/embedded/manifest.json | 9 ++- .../tree/skills/docket-link-ticket/SKILL.md | 39 +++++++++++ internal/repoguard/budgets_test.go | 1 + internal/repoguard/export_skill_test.go | 65 ++++++++++++++----- internal/repoguard/prose_contracts_test.go | 24 +++++++ skills/docket-link-ticket/SKILL.md | 39 +++++++++++ 6 files changed, 158 insertions(+), 19 deletions(-) create mode 100644 internal/assets/embedded/tree/skills/docket-link-ticket/SKILL.md create mode 100644 skills/docket-link-ticket/SKILL.md diff --git a/internal/assets/embedded/manifest.json b/internal/assets/embedded/manifest.json index 19a08700e..a7bb43c98 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:5e75da008ab533c7f27e6d80bd06bd60337e8ceb494642bd94ac660d3bab067c", + "asset_set_id": "sha256:8a89626c3207935ff8815bdec4b74f7da03641cd980280712a3f7c688a32c513", "entries": [ { "path": ".docket.example.yml", @@ -416,6 +416,13 @@ "size": 3741, "sha256": "c633d7c6e9ebe1540282f4361eedee0aac082b3f9897c0668a7aec2a275bc0a3" }, + { + "path": "skills/docket-link-ticket/SKILL.md", + "role": "skill", + "mode": 420, + "size": 4916, + "sha256": "52a8de2557af3056e83e2571af6b19acb84c3aed692d014526d19afeb73e1786" + }, { "path": "skills/docket-new-change/SKILL.md", "role": "skill", diff --git a/internal/assets/embedded/tree/skills/docket-link-ticket/SKILL.md b/internal/assets/embedded/tree/skills/docket-link-ticket/SKILL.md new file mode 100644 index 000000000..721778f80 --- /dev/null +++ b/internal/assets/embedded/tree/skills/docket-link-ticket/SKILL.md @@ -0,0 +1,39 @@ +--- +name: docket-link-ticket +description: 'Use when the person asks to link a change in docket to a ticket (`link #12 to CLOUD-123`), to create a ticket from a change (`create a Jira ticket from #12`, `put #12 in Jira`), or to make a change from a ticket (`make a change from CLOUD-123`) — always with the person present; not for posting an update or comment to a ticket.' +--- + +# docket-link-ticket + +This skill runs inline, in your own session, and only when the person asks: no autonomous workflow ever creates, links, or imports a ticket. You reach the ticket system with your own tools, and you ask the person directly where a step below says to. + +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). 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. + +Writes are change records on the metadata branch, made only through the `change.link-ticket`, `change.groom`, and `change.create` operations (argv from the capability catalog). Build each request body from that operation's `schema` descriptor. A `contended` refusal means re-sync, re-read `path` and `revision`, and retry, or stop if the change moved out from under the request. + +## Shared rules + +- **Where tickets go.** Read `tickets.provider`, `tickets.site`, and `tickets.project` from the `diagnostic.config` operation at `effective.tickets..value`. When one the path needs is empty, ask the person for it for this run; never edit configuration. `project` maps to the provider's own term: a Jira project, a Linear team, a GitHub repository. +- **Find the connector** for the 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. With no connector, creating and importing stop with nothing created or recorded. Linking may still go ahead by URL (link path, step 3). +- **Known links.** Known links come from the `records` array of the `status` operation run with `--json --records` — rows of kind `change`, whose `path` and `revision` feed every write. A change is linked only when its record carries a `ticket` object. +- **Broken links.** A change with a `ticket-link-invalid` finding is not linked, but `change.link-ticket` will not write over it without `replace: true`: before anything else, stop and ask the person to fix the broken link or remove it. Fixing it is a link with `replace: true`; removing it is `unlink: true`. +- **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`). + +## Routing + +When creating a ticket from a change, **read `references/create.md` now (blocking)**. When making a change from a ticket, **read `references/import.md` now (blocking)**. Linking an existing ticket stays here. + +## Link path + +1. The person names a change and a ticket: a URL, or an id when `tickets.site` is set. +2. **Provider and id.** When the URL's host matches `tickets.site`, the provider is `tickets.provider`; otherwise ask the person. The id is the ticket's key as the provider shows it, read through the connector (preferred) or from the URL. +3. **Check the ticket.** Confirm the ticket exists through the connector when one is available. With none, the person may still link by URL — the link is a record, not a ticket call — and the report says the ticket was not verified. +4. **Other changes.** Name any other change that already carries this ticket (shared rules). +5. **Record it.** Run the `change.link-ticket` operation with the change's `path` and `revision`. On `already-linked-elsewhere`, tell the person which ticket the change carries now, and send `replace: true` only if they say so. Unlink only when the person asks. Report the disposition in plain words: `linked` (now linked), `already-linked` (it already carried this ticket), `replaced` (the old link was swapped for the new one), `unlinked` (the link was removed), or `nothing-to-unlink` (it had no link to remove). diff --git a/internal/repoguard/budgets_test.go b/internal/repoguard/budgets_test.go index 5c0b4d697..d9e23dade 100644 --- a/internal/repoguard/budgets_test.go +++ b/internal/repoguard/budgets_test.go @@ -215,6 +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, 788}, // 0584: new — the inline ticket-linking skill {"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) diff --git a/internal/repoguard/export_skill_test.go b/internal/repoguard/export_skill_test.go index a8a60a48e..657114531 100644 --- a/internal/repoguard/export_skill_test.go +++ b/internal/repoguard/export_skill_test.go @@ -50,39 +50,48 @@ func frontmatterValue(content, key string) string { return "" } -// TestExportSkillIsInline pins docket-export as an inline skill: frontmatter -// carries exactly name and description (no fork, no agent), and no agent -// wrapper exists. A forked skill could not reach the session's posting tools -// or ask the person. -func TestExportSkillIsInline(t *testing.T) { +// assertInlineSkill pins skills//SKILL.md as an inline skill: +// frontmatter carries exactly name and description (no fork, no agent), the +// name matches, the collapsed description contains each clause, and no agent +// wrapper agents/.md exists. A forked skill could not reach the +// session's own tools or ask the person. +func assertInlineSkill(t *testing.T, name string, clauses []string) { + t.Helper() root := guardRoot(t) - body := readRepoFile(t, "skills/docket-export/SKILL.md") + file := "skills/" + name + "/SKILL.md" + body := readRepoFile(t, file) keys, err := skillFrontmatterKeys(body) if err != nil { - t.Fatalf("skills/docket-export/SKILL.md frontmatter: %v", err) + t.Fatalf("%s frontmatter: %v", file, err) } if want := []string{"name", "description"}; !reflect.DeepEqual(keys, want) { - t.Errorf("frontmatter keys = %v, want exactly %v (an inline skill: no context, no agent)", keys, want) + t.Errorf("%s frontmatter keys = %v, want exactly %v (an inline skill: no context, no agent)", file, keys, want) } - if got := frontmatterValue(body, "name"); got != "docket-export" { - t.Errorf("name = %q, want docket-export", got) + if got := frontmatterValue(body, "name"); got != name { + t.Errorf("%s name = %q, want %s", file, got, name) } desc := collapseWS(frontmatterValue(body, "description")) - for _, clause := range []string{ - "export a docket change, spec, plan, or results file", - "put one into anything outside docket", - } { + for _, clause := range clauses { if !strings.Contains(desc, clause) { - t.Errorf("description lacks %q: %q", clause, desc) + t.Errorf("%s description lacks %q: %q", file, clause, desc) } } - _, err = os.Stat(filepath.Join(root, "agents", "docket-export.md")) + wrapper := filepath.Join(root, "agents", name+".md") + _, err = os.Stat(wrapper) switch { case err == nil: - t.Errorf("agents/docket-export.md exists; docket-export is an inline skill with no wrapper") + t.Errorf("agents/%s.md exists; %s is an inline skill with no wrapper", name, name) case !errors.Is(err, fs.ErrNotExist): - t.Errorf("stat agents/docket-export.md: %v (fail closed)", err) + t.Errorf("stat agents/%s.md: %v (fail closed)", name, err) } +} + +// TestExportSkillIsInline pins docket-export as an inline skill. +func TestExportSkillIsInline(t *testing.T) { + assertInlineSkill(t, "docket-export", []string{ + "export a docket change, spec, plan, or results file", + "put one into anything outside docket", + }) t.Run("non_vacuity", func(t *testing.T) { got, err := skillFrontmatterKeys("---\nname: x\ndescription: y\ncontext: fork\nagent: x\n---\nbody\n") @@ -100,3 +109,23 @@ func TestExportSkillIsInline(t *testing.T) { } }) } + +// TestLinkTicketSkillIsInline pins docket-link-ticket as an inline skill whose +// description names its three asks, disclaims posting updates, and uses the +// ticket vocabulary only. +func TestLinkTicketSkillIsInline(t *testing.T) { + const name = "docket-link-ticket" + assertInlineSkill(t, name, []string{ + "link a change in docket to a ticket", + "create a ticket from a change", + "make a change from a ticket", + "not for posting an update", + }) + 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) + } + } +} diff --git a/internal/repoguard/prose_contracts_test.go b/internal/repoguard/prose_contracts_test.go index f460ddf66..128887194 100644 --- a/internal/repoguard/prose_contracts_test.go +++ b/internal/repoguard/prose_contracts_test.go @@ -1558,6 +1558,30 @@ var alignmentContracts = []proseContract{ present: []string{"Agent sessions reach the export through the `docket-export` skill."}}, {sentinel: "change_0578_export_skill", file: "docs/reference/skills-and-agents.md", present: []string{"- **docket-export** —"}}, + // change 0584 — the inline ticket-linking skill: attended only; links are + // read from status --json --records; a broken link stops every write; record + // only after the connector confirms; push and import load their references. + {sentinel: "change_0584_link_ticket_skill", file: "skills/docket-link-ticket/SKILL.md", + present: []string{ + "This skill runs inline, in your own session, and only when the person asks: no autonomous workflow ever creates, links, or imports a ticket.", + "A `contended` refusal means re-sync, re-read `path` and `revision`, and retry, or stop if the change moved out from under the request.", + "Read `tickets.provider`, `tickets.site`, and `tickets.project` from the `diagnostic.config` operation at `effective.tickets..value`.", + "Never conclude an operation is missing because it is not in your tool list", + "With no connector, creating and importing stop with nothing created or recorded.", + "Known links come from the `records` array of the `status` operation run with `--json --records`", + "A change is linked only when its record carries a `ticket` object.", + "A change with a `ticket-link-invalid` finding is not linked, but `change.link-ticket` will not write over it without `replace: true`: before anything else, stop and ask the person to fix the broken link or remove it.", + "One ticket may be on several changes.", + "Record only after the connector confirms.", + "An uncertain outcome is reported as uncertain, and the person decides whether to try again.", + "When creating a ticket from a change, **read `references/create.md` now (blocking)**.", + "When making a change from a ticket, **read `references/import.md` now (blocking)**.", + "When the URL's host matches `tickets.site`, the provider is `tickets.provider`; otherwise ask the person.", + "the report says the ticket was not verified", + "On `already-linked-elsewhere`, tell the person which ticket the change carries now, and send `replace: true` only if they say so.", + "Unlink only when the person asks.", + }, + absent: []string{"context: fork", "agent: docket-link-ticket"}}, } // oneLayoutAbsent are the retired metadata-layout spellings. diff --git a/skills/docket-link-ticket/SKILL.md b/skills/docket-link-ticket/SKILL.md new file mode 100644 index 000000000..721778f80 --- /dev/null +++ b/skills/docket-link-ticket/SKILL.md @@ -0,0 +1,39 @@ +--- +name: docket-link-ticket +description: 'Use when the person asks to link a change in docket to a ticket (`link #12 to CLOUD-123`), to create a ticket from a change (`create a Jira ticket from #12`, `put #12 in Jira`), or to make a change from a ticket (`make a change from CLOUD-123`) — always with the person present; not for posting an update or comment to a ticket.' +--- + +# docket-link-ticket + +This skill runs inline, in your own session, and only when the person asks: no autonomous workflow ever creates, links, or imports a ticket. You reach the ticket system with your own tools, and you ask the person directly where a step below says to. + +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). 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. + +Writes are change records on the metadata branch, made only through the `change.link-ticket`, `change.groom`, and `change.create` operations (argv from the capability catalog). Build each request body from that operation's `schema` descriptor. A `contended` refusal means re-sync, re-read `path` and `revision`, and retry, or stop if the change moved out from under the request. + +## Shared rules + +- **Where tickets go.** Read `tickets.provider`, `tickets.site`, and `tickets.project` from the `diagnostic.config` operation at `effective.tickets..value`. When one the path needs is empty, ask the person for it for this run; never edit configuration. `project` maps to the provider's own term: a Jira project, a Linear team, a GitHub repository. +- **Find the connector** for the 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. With no connector, creating and importing stop with nothing created or recorded. Linking may still go ahead by URL (link path, step 3). +- **Known links.** Known links come from the `records` array of the `status` operation run with `--json --records` — rows of kind `change`, whose `path` and `revision` feed every write. A change is linked only when its record carries a `ticket` object. +- **Broken links.** A change with a `ticket-link-invalid` finding is not linked, but `change.link-ticket` will not write over it without `replace: true`: before anything else, stop and ask the person to fix the broken link or remove it. Fixing it is a link with `replace: true`; removing it is `unlink: true`. +- **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`). + +## Routing + +When creating a ticket from a change, **read `references/create.md` now (blocking)**. When making a change from a ticket, **read `references/import.md` now (blocking)**. Linking an existing ticket stays here. + +## Link path + +1. The person names a change and a ticket: a URL, or an id when `tickets.site` is set. +2. **Provider and id.** When the URL's host matches `tickets.site`, the provider is `tickets.provider`; otherwise ask the person. The id is the ticket's key as the provider shows it, read through the connector (preferred) or from the URL. +3. **Check the ticket.** Confirm the ticket exists through the connector when one is available. With none, the person may still link by URL — the link is a record, not a ticket call — and the report says the ticket was not verified. +4. **Other changes.** Name any other change that already carries this ticket (shared rules). +5. **Record it.** Run the `change.link-ticket` operation with the change's `path` and `revision`. On `already-linked-elsewhere`, tell the person which ticket the change carries now, and send `replace: true` only if they say so. Unlink only when the person asks. Report the disposition in plain words: `linked` (now linked), `already-linked` (it already carried this ticket), `replaced` (the old link was swapped for the new one), `unlinked` (the link was removed), or `nothing-to-unlink` (it had no link to remove). From 055c89e1e6c52718941af34700e5212ca34ad705 Mon Sep 17 00:00:00 2001 From: Daniel Hanold Date: Mon, 9 Nov 2026 21:17:35 -0500 Subject: [PATCH 4/8] feat(skills): add the push path that creates a ticket from a change --- internal/assets/embedded/manifest.json | 9 ++++- .../docket-link-ticket/references/create.md | 35 +++++++++++++++++++ internal/repoguard/budgets_test.go | 1 + internal/repoguard/prose_contracts_test.go | 22 ++++++++++++ .../docket-link-ticket/references/create.md | 35 +++++++++++++++++++ 5 files changed, 101 insertions(+), 1 deletion(-) create mode 100644 internal/assets/embedded/tree/skills/docket-link-ticket/references/create.md create mode 100644 skills/docket-link-ticket/references/create.md diff --git a/internal/assets/embedded/manifest.json b/internal/assets/embedded/manifest.json index a7bb43c98..e3f03b1a9 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:8a89626c3207935ff8815bdec4b74f7da03641cd980280712a3f7c688a32c513", + "asset_set_id": "sha256:7364587d372b722b5e6d8c11905eb13ef03a6f77f09479af39d6564bd1c00fca", "entries": [ { "path": ".docket.example.yml", @@ -423,6 +423,13 @@ "size": 4916, "sha256": "52a8de2557af3056e83e2571af6b19acb84c3aed692d014526d19afeb73e1786" }, + { + "path": "skills/docket-link-ticket/references/create.md", + "role": "skill", + "mode": 420, + "size": 5185, + "sha256": "ab60ac2773e29ad4d237919bc90047f7a3156e36c0db7685d6b838f71dc95d86" + }, { "path": "skills/docket-new-change/SKILL.md", "role": "skill", diff --git a/internal/assets/embedded/tree/skills/docket-link-ticket/references/create.md b/internal/assets/embedded/tree/skills/docket-link-ticket/references/create.md new file mode 100644 index 000000000..4fa46742c --- /dev/null +++ b/internal/assets/embedded/tree/skills/docket-link-ticket/references/create.md @@ -0,0 +1,35 @@ +# Creating a ticket from a change (push path) + +Loaded from `SKILL.md` when the person asks to create a ticket from a change. The shared rules in `SKILL.md` apply to every step; they are not repeated here. Read the change's record from the `status` operation and the change file itself before step 1. + +1. **Already linked.** If the change's record carries a `ticket`, refuse and name it (`#12 is already linked to CLOUD-123 `); nothing else happens. A `ticket-link-invalid` finding on the change also stops here: otherwise the ticket would be created and could never be recorded. Ask the person to fix or remove the broken link first (shared rules). + +2. **Readiness check.** Ask one question of the change: Could another engineer take ownership of this as a user story? It can when the change states: + - the problem and why it matters; + - the desired outcome; + - bounded scope and non-goals; + - genuine constraints, kept distinct from implementation preferences; + - clear, verifiable acceptance criteria that belong to this change; + - no open question that blocks understanding. + + Technical questions may stay open: the request must be ready for ownership, not necessarily for coding. A spec is not required, and an existing spec never turns its technical choices into requirements. + +3. **Refinement, only if needed.** When the check finds gaps, ask the person targeted questions about what is missing — nothing more. Write the answers through `change.groom` with `outcome: revise` and its owned sections, which works only while the change is `proposed`. `## Acceptance criteria` is one of those sections. Past `proposed`, build the ticket from the change as it stands: name what is missing and let the person decide whether to go ahead. Never invent scope or acceptance criteria, and never promote an unreviewed solution into a requirement. + +4. **Ticket type.** Read the ticket types the project actually has through the connector (in Jira, `listJiraProjectIssueTypesMetadata`). `fix` maps to the bug type, `feat` to the story or feature type, and any other type to the task type. With no obvious match, ask the person. A tool without ticket types (Linear, Asana, Trello) gets none. + +5. **Export the body.** Invoke the `docket-export` skill as a **file request** — its rules are its own; do not restate or re-run them — **DIRECTED to:** export `change ` with `--output-path` set to a fresh directory from `mktemp -d "${TMPDIR:-/tmp}/docket-link-ticket.XXXXXX"`, return the path and, in a private repository, the before → after list, and post nothing. The export's H1 is the title; its body keeps Why, What changes, Acceptance criteria, Out of scope, and Open questions. + +6. **Spec, when the change has a `spec:`.** The spec is always included, labeled as the proposed approach, never as requirements. There is no separate question: the person's go on the draft is the only approval. + - **Shared repository:** run the `open` argv as ` spec --print --json`. When `target_kind` is `url`, the body ends with one line, `Proposed approach: `. That is a branch link, not one pinned to a commit: the description is written once, so a pinned link would go stale after a later spec revision. + - **No URL, or a private repository:** A local path never goes into a ticket. When `target_kind` is `file`, or the repository is private, export the spec through `docket-export` as a file request (as in step 5) and attach it after the ticket exists (step 9). The body ends with `Proposed approach: see the attached `. + +7. **Draft and approval.** Show the person, in one message, the title, the project, the mapped type, the body as it will be posted, the spec line or attachment name, and in a private repository the before → after list for the body and the spec. Create only on their go. A `docket-export` word-check hit stops the draft the way `docket-export` does: show the lines and post nothing until the person decides. + +8. **Create** the ticket through the connector in `tickets.project`: the summary is the export's H1, and the description is the rest. When the provider needs its own markup, convert formatting only, never words. The description is written once and never rewritten. + +9. **Attach** the exported spec, when step 6 chose an attachment. Never assume a one-call upload, and never substitute a local path for an attachment. Some connectors attach in two steps: the Atlassian connector's `uploadAttachmentToJiraIssue` returns an upload command to run from the shell, and the file id it returns is then attached. If the upload fails, the ticket stays, since its description cannot be rewritten: report the failure and the exported file's path so the person can attach it by hand. + +10. **Record** the link with the `change.link-ticket` operation — the provider, the created ticket's id, and its URL — once the connector has confirmed the ticket was created. If recording fails, report the created ticket's URL and retry the link with a fresh `path` and `revision`; never create a second ticket. + +11. **Report** the ticket link, its type, whether the spec was linked or attached, and any before → after list. diff --git a/internal/repoguard/budgets_test.go b/internal/repoguard/budgets_test.go index d9e23dade..2e11baeeb 100644 --- a/internal/repoguard/budgets_test.go +++ b/internal/repoguard/budgets_test.go @@ -216,6 +216,7 @@ var skillBudgets = []skillBudget{ {"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, 788}, // 0584: new — the inline ticket-linking skill + {"docket-link-ticket/references/create.md", 35, 843}, // 0584: new — the push 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) {"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) diff --git a/internal/repoguard/prose_contracts_test.go b/internal/repoguard/prose_contracts_test.go index 128887194..9e72dbcdc 100644 --- a/internal/repoguard/prose_contracts_test.go +++ b/internal/repoguard/prose_contracts_test.go @@ -1582,6 +1582,28 @@ var alignmentContracts = []proseContract{ "Unlink only when the person asks.", }, absent: []string{"context: fork", "agent: docket-link-ticket"}}, + // change 0584 — the push path: an existing or broken link stops before the + // readiness check; refinement only while proposed; the spec is the proposed + // approach, never a local path; one approval; record after confirmation, and + // a failed record never creates a second ticket. + {sentinel: "change_0584_link_ticket_skill", file: "skills/docket-link-ticket/references/create.md", + present: []string{ + "If the change's record carries a `ticket`, refuse and name it (`#12 is already linked to CLOUD-123 `); nothing else happens.", + "A `ticket-link-invalid` finding on the change also stops here: otherwise the ticket would be created and could never be recorded.", + "Could another engineer take ownership of this as a user story?", + "an existing spec never turns its technical choices into requirements", + "Write the answers through `change.groom` with `outcome: revise` and its owned sections, which works only while the change is `proposed`.", + "Past `proposed`, build the ticket from the change as it stands: name what is missing and let the person decide whether to go ahead.", + "Never invent scope or acceptance criteria, and never promote an unreviewed solution into a requirement.", + "`fix` maps to the bug type, `feat` to the story or feature type, and any other type to the task type.", + "The spec is always included, labeled as the proposed approach, never as requirements.", + "A local path never goes into a ticket.", + "Show the person, in one message, the title, the project, the mapped type, the body as it will be posted, the spec line or attachment name, and in a private repository the before → after list for the body and the spec.", + "Create only on their go.", + "The description is written once and never rewritten.", + "Never assume a one-call upload, and never substitute a local path for an attachment.", + "If recording fails, report the created ticket's URL and retry the link with a fresh `path` and `revision`; never create a second ticket.", + }}, } // oneLayoutAbsent are the retired metadata-layout spellings. diff --git a/skills/docket-link-ticket/references/create.md b/skills/docket-link-ticket/references/create.md new file mode 100644 index 000000000..4fa46742c --- /dev/null +++ b/skills/docket-link-ticket/references/create.md @@ -0,0 +1,35 @@ +# Creating a ticket from a change (push path) + +Loaded from `SKILL.md` when the person asks to create a ticket from a change. The shared rules in `SKILL.md` apply to every step; they are not repeated here. Read the change's record from the `status` operation and the change file itself before step 1. + +1. **Already linked.** If the change's record carries a `ticket`, refuse and name it (`#12 is already linked to CLOUD-123 `); nothing else happens. A `ticket-link-invalid` finding on the change also stops here: otherwise the ticket would be created and could never be recorded. Ask the person to fix or remove the broken link first (shared rules). + +2. **Readiness check.** Ask one question of the change: Could another engineer take ownership of this as a user story? It can when the change states: + - the problem and why it matters; + - the desired outcome; + - bounded scope and non-goals; + - genuine constraints, kept distinct from implementation preferences; + - clear, verifiable acceptance criteria that belong to this change; + - no open question that blocks understanding. + + Technical questions may stay open: the request must be ready for ownership, not necessarily for coding. A spec is not required, and an existing spec never turns its technical choices into requirements. + +3. **Refinement, only if needed.** When the check finds gaps, ask the person targeted questions about what is missing — nothing more. Write the answers through `change.groom` with `outcome: revise` and its owned sections, which works only while the change is `proposed`. `## Acceptance criteria` is one of those sections. Past `proposed`, build the ticket from the change as it stands: name what is missing and let the person decide whether to go ahead. Never invent scope or acceptance criteria, and never promote an unreviewed solution into a requirement. + +4. **Ticket type.** Read the ticket types the project actually has through the connector (in Jira, `listJiraProjectIssueTypesMetadata`). `fix` maps to the bug type, `feat` to the story or feature type, and any other type to the task type. With no obvious match, ask the person. A tool without ticket types (Linear, Asana, Trello) gets none. + +5. **Export the body.** Invoke the `docket-export` skill as a **file request** — its rules are its own; do not restate or re-run them — **DIRECTED to:** export `change ` with `--output-path` set to a fresh directory from `mktemp -d "${TMPDIR:-/tmp}/docket-link-ticket.XXXXXX"`, return the path and, in a private repository, the before → after list, and post nothing. The export's H1 is the title; its body keeps Why, What changes, Acceptance criteria, Out of scope, and Open questions. + +6. **Spec, when the change has a `spec:`.** The spec is always included, labeled as the proposed approach, never as requirements. There is no separate question: the person's go on the draft is the only approval. + - **Shared repository:** run the `open` argv as ` spec --print --json`. When `target_kind` is `url`, the body ends with one line, `Proposed approach: `. That is a branch link, not one pinned to a commit: the description is written once, so a pinned link would go stale after a later spec revision. + - **No URL, or a private repository:** A local path never goes into a ticket. When `target_kind` is `file`, or the repository is private, export the spec through `docket-export` as a file request (as in step 5) and attach it after the ticket exists (step 9). The body ends with `Proposed approach: see the attached `. + +7. **Draft and approval.** Show the person, in one message, the title, the project, the mapped type, the body as it will be posted, the spec line or attachment name, and in a private repository the before → after list for the body and the spec. Create only on their go. A `docket-export` word-check hit stops the draft the way `docket-export` does: show the lines and post nothing until the person decides. + +8. **Create** the ticket through the connector in `tickets.project`: the summary is the export's H1, and the description is the rest. When the provider needs its own markup, convert formatting only, never words. The description is written once and never rewritten. + +9. **Attach** the exported spec, when step 6 chose an attachment. Never assume a one-call upload, and never substitute a local path for an attachment. Some connectors attach in two steps: the Atlassian connector's `uploadAttachmentToJiraIssue` returns an upload command to run from the shell, and the file id it returns is then attached. If the upload fails, the ticket stays, since its description cannot be rewritten: report the failure and the exported file's path so the person can attach it by hand. + +10. **Record** the link with the `change.link-ticket` operation — the provider, the created ticket's id, and its URL — once the connector has confirmed the ticket was created. If recording fails, report the created ticket's URL and retry the link with a fresh `path` and `revision`; never create a second ticket. + +11. **Report** the ticket link, its type, whether the spec was linked or attached, and any before → after list. From 0dd729707ac6cef98cff039380f5e4fc41ce6e22 Mon Sep 17 00:00:00 2001 From: Daniel Hanold Date: Mon, 9 Nov 2026 21:19:14 -0500 Subject: [PATCH 5/8] feat(skills): add the import path that makes a change from a ticket --- internal/assets/embedded/manifest.json | 9 ++++++++- .../docket-link-ticket/references/import.md | 15 +++++++++++++++ internal/repoguard/budgets_test.go | 1 + internal/repoguard/export_skill_test.go | 9 +++++++++ internal/repoguard/prose_contracts_test.go | 12 ++++++++++++ skills/docket-link-ticket/references/import.md | 15 +++++++++++++++ 6 files changed, 60 insertions(+), 1 deletion(-) create mode 100644 internal/assets/embedded/tree/skills/docket-link-ticket/references/import.md create mode 100644 skills/docket-link-ticket/references/import.md diff --git a/internal/assets/embedded/manifest.json b/internal/assets/embedded/manifest.json index e3f03b1a9..88e68538b 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:7364587d372b722b5e6d8c11905eb13ef03a6f77f09479af39d6564bd1c00fca", + "asset_set_id": "sha256:ee147e217a5315a9866f9d55208605b80cede99b7cc28ef6594e5743f8fb4f30", "entries": [ { "path": ".docket.example.yml", @@ -430,6 +430,13 @@ "size": 5185, "sha256": "ab60ac2773e29ad4d237919bc90047f7a3156e36c0db7685d6b838f71dc95d86" }, + { + "path": "skills/docket-link-ticket/references/import.md", + "role": "skill", + "mode": 420, + "size": 1987, + "sha256": "552c67370e555725c10f9c72033f44cd49dcfa7a8a6133e697bb3405769cd0a8" + }, { "path": "skills/docket-new-change/SKILL.md", "role": "skill", diff --git a/internal/assets/embedded/tree/skills/docket-link-ticket/references/import.md b/internal/assets/embedded/tree/skills/docket-link-ticket/references/import.md new file mode 100644 index 000000000..06523adb1 --- /dev/null +++ b/internal/assets/embedded/tree/skills/docket-link-ticket/references/import.md @@ -0,0 +1,15 @@ +# Making a change from a ticket (import path) + +Loaded from `SKILL.md` when the person asks to make a change from a ticket. The shared rules in `SKILL.md` apply to every step; they are not repeated here. + +1. **Read the ticket** through the connector: its summary, description, type, and URL. + +2. **Already on a change?** Check the known links (shared rules). If any change record, active or archived, carries a `ticket` with the same provider and id, name it in the draft (`CLOUD-123 is also on #10`) and go ahead. One ticket may be split across several changes, so this is never a refusal; the person's go on the draft decides. + +3. **Distill** the ticket into a draft change. The title comes from the ticket's summary; Why, What changes, Acceptance criteria, Out of scope, and Open questions come from its content. Never invent: when the ticket gives no basis for Why, What changes, or Out of scope, ask the person. Read the configured change types from the `diagnostic.config` operation at `effective.change_types.value`. Map the ticket's type to one of the configured `change_types` (a Bug to `fix`, a Story to `feat`); with no obvious match, ask. + +4. **Draft and approval.** Show the drafted change (title, type, sections, and ticket) and create it only on the person's go. + +5. **Create** the change with the `change.create` operation, building the request from its `schema` descriptor: set `ticket_provider`, `ticket_id`, and `ticket_url`, leave the priority at its default, and give it a stable `request_id` so a retry cannot create a second change. `change.create` does not write `## Open questions`. When the draft has open questions, follow with one `change.groom` `outcome: revise` carrying `## Open questions`, using a fresh `path` and `revision` from the `status` operation. + +6. **Report** the new change's id and its link. The change is a needs-grooming stub with no spec; the person grooms it as usual. The import happens once: nothing is synced from the ticket afterwards. diff --git a/internal/repoguard/budgets_test.go b/internal/repoguard/budgets_test.go index 2e11baeeb..14147df6a 100644 --- a/internal/repoguard/budgets_test.go +++ b/internal/repoguard/budgets_test.go @@ -217,6 +217,7 @@ var skillBudgets = []skillBudget{ {"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, 788}, // 0584: new — the inline ticket-linking skill {"docket-link-ticket/references/create.md", 35, 843}, // 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) {"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) diff --git a/internal/repoguard/export_skill_test.go b/internal/repoguard/export_skill_test.go index 657114531..1e3858eb4 100644 --- a/internal/repoguard/export_skill_test.go +++ b/internal/repoguard/export_skill_test.go @@ -128,4 +128,13 @@ func TestLinkTicketSkillIsInline(t *testing.T) { t.Errorf("%s description uses %q; the item is a ticket: %q", name, word, desc) } } + // SKILL.md routes the push and import paths to these files; a missing one + // leaves a blocking read with nothing to read. + root := guardRoot(t) + for _, ref := range []string{"references/create.md", "references/import.md"} { + p := filepath.Join(root, "skills", name, filepath.FromSlash(ref)) + if _, err := os.Stat(p); err != nil { + t.Errorf("%s routes to %s, which cannot be read: %v", name, ref, err) + } + } } diff --git a/internal/repoguard/prose_contracts_test.go b/internal/repoguard/prose_contracts_test.go index 9e72dbcdc..8a1c7a406 100644 --- a/internal/repoguard/prose_contracts_test.go +++ b/internal/repoguard/prose_contracts_test.go @@ -1604,6 +1604,18 @@ var alignmentContracts = []proseContract{ "Never assume a one-call upload, and never substitute a local path for an attachment.", "If recording fails, report the created ticket's URL and retry the link with a fresh `path` and `revision`; never create a second ticket.", }}, + // change 0584 — the import path: a ticket already on a change is named, not + // refused; nothing is invented; one approval; open questions follow through + // change.groom; the import happens once. + {sentinel: "change_0584_link_ticket_skill", file: "skills/docket-link-ticket/references/import.md", + present: []string{ + "If any change record, active or archived, carries a `ticket` with the same provider and id, name it in the draft (`CLOUD-123 is also on #10`) and go ahead.", + "Never invent: when the ticket gives no basis for Why, What changes, or Out of scope, ask the person.", + "Map the ticket's type to one of the configured `change_types` (a Bug to `fix`, a Story to `feat`); with no obvious match, ask.", + "Show the drafted change (title, type, sections, and ticket) and create it only on the person's go.", + "When the draft has open questions, follow with one `change.groom` `outcome: revise` carrying `## Open questions`, using a fresh `path` and `revision` from the `status` operation.", + "The import happens once: nothing is synced from the ticket afterwards.", + }}, } // oneLayoutAbsent are the retired metadata-layout spellings. diff --git a/skills/docket-link-ticket/references/import.md b/skills/docket-link-ticket/references/import.md new file mode 100644 index 000000000..06523adb1 --- /dev/null +++ b/skills/docket-link-ticket/references/import.md @@ -0,0 +1,15 @@ +# Making a change from a ticket (import path) + +Loaded from `SKILL.md` when the person asks to make a change from a ticket. The shared rules in `SKILL.md` apply to every step; they are not repeated here. + +1. **Read the ticket** through the connector: its summary, description, type, and URL. + +2. **Already on a change?** Check the known links (shared rules). If any change record, active or archived, carries a `ticket` with the same provider and id, name it in the draft (`CLOUD-123 is also on #10`) and go ahead. One ticket may be split across several changes, so this is never a refusal; the person's go on the draft decides. + +3. **Distill** the ticket into a draft change. The title comes from the ticket's summary; Why, What changes, Acceptance criteria, Out of scope, and Open questions come from its content. Never invent: when the ticket gives no basis for Why, What changes, or Out of scope, ask the person. Read the configured change types from the `diagnostic.config` operation at `effective.change_types.value`. Map the ticket's type to one of the configured `change_types` (a Bug to `fix`, a Story to `feat`); with no obvious match, ask. + +4. **Draft and approval.** Show the drafted change (title, type, sections, and ticket) and create it only on the person's go. + +5. **Create** the change with the `change.create` operation, building the request from its `schema` descriptor: set `ticket_provider`, `ticket_id`, and `ticket_url`, leave the priority at its default, and give it a stable `request_id` so a retry cannot create a second change. `change.create` does not write `## Open questions`. When the draft has open questions, follow with one `change.groom` `outcome: revise` carrying `## Open questions`, using a fresh `path` and `revision` from the `status` operation. + +6. **Report** the new change's id and its link. The change is a needs-grooming stub with no spec; the person grooms it as usual. The import happens once: nothing is synced from the ticket afterwards. From 042e2a6ab6bcfd3ea9c41542215d7b8cf6ffaddf Mon Sep 17 00:00:00 2001 From: Daniel Hanold Date: Mon, 9 Nov 2026 21:20:19 -0500 Subject: [PATCH 6/8] docs(skills): point ticket work from docket-export to docket-link-ticket --- internal/assets/embedded/manifest.json | 6 +++--- .../assets/embedded/tree/skills/docket-export/SKILL.md | 4 +++- internal/repoguard/budgets_test.go | 2 +- internal/repoguard/export_skill_test.go | 9 +++++++++ internal/repoguard/prose_contracts_test.go | 3 ++- skills/docket-export/SKILL.md | 4 +++- 6 files changed, 21 insertions(+), 7 deletions(-) diff --git a/internal/assets/embedded/manifest.json b/internal/assets/embedded/manifest.json index 88e68538b..0010f405d 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:ee147e217a5315a9866f9d55208605b80cede99b7cc28ef6594e5743f8fb4f30", + "asset_set_id": "sha256:e3fa81515733f35af701eff662293c1524b46a504decdc24cce034c3f45b3423", "entries": [ { "path": ".docket.example.yml", @@ -357,8 +357,8 @@ "path": "skills/docket-export/SKILL.md", "role": "skill", "mode": 420, - "size": 6739, - "sha256": "a8e37531802ec220a34d5c32f07d9a142fde0f396b1f116eec7af2d3732d4d6a" + "size": 6846, + "sha256": "fa95a8c50ef35978ba11bbab1d95ed7160ccf75af2193799513a72d7a2cfc043" }, { "path": "skills/docket-finalize-change/SKILL.md", diff --git a/internal/assets/embedded/tree/skills/docket-export/SKILL.md b/internal/assets/embedded/tree/skills/docket-export/SKILL.md index 2644e4433..14dfc40ec 100644 --- a/internal/assets/embedded/tree/skills/docket-export/SKILL.md +++ b/internal/assets/embedded/tree/skills/docket-export/SKILL.md @@ -1,6 +1,6 @@ --- name: docket-export -description: Use when asked to export a docket change, spec, plan, or results file, or to put one into anything outside docket — a Jira ticket body or comment, a document, a message, an email — so its content comes from docket's own export, never the raw file or a hand cleanup. +description: Use when asked to export a docket change, spec, plan, or results file, or to put one into anything outside docket — a document, a message, an email — so its content comes from docket's own export, never the raw file or a hand cleanup. --- # docket-export @@ -9,6 +9,8 @@ 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. + ## 1. Resolve the operations Run `docket capabilities --json` as its own call — the one docket spelling this skill hard-codes. Check that `protocol_version` is 1 and take the `argv` of the entries `open`, `repository.prepare`, and `diagnostic.config`. If the binary is missing or an entry is absent, tell the person their docket installation is broken and stop — never a hand-made export. diff --git a/internal/repoguard/budgets_test.go b/internal/repoguard/budgets_test.go index 14147df6a..405385c71 100644 --- a/internal/repoguard/budgets_test.go +++ b/internal/repoguard/budgets_test.go @@ -206,7 +206,7 @@ var skillBudgets = []skillBudget{ {"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", 60, 1116}, // 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, 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-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) diff --git a/internal/repoguard/export_skill_test.go b/internal/repoguard/export_skill_test.go index 1e3858eb4..21c4123fd 100644 --- a/internal/repoguard/export_skill_test.go +++ b/internal/repoguard/export_skill_test.go @@ -92,6 +92,15 @@ func TestExportSkillIsInline(t *testing.T) { "export a docket change, spec, plan, or results file", "put one into anything outside docket", }) + // Ticket work belongs to docket-link-ticket: the export skill's description + // must not route ticket requests here. + body := readRepoFile(t, "skills/docket-export/SKILL.md") + desc := strings.ToLower(collapseWS(frontmatterValue(body, "description"))) + for _, word := range []string{"ticket", "jira"} { + if strings.Contains(desc, word) { + t.Errorf("skills/docket-export/SKILL.md description names %q; ticket work is docket-link-ticket's: %q", word, desc) + } + } t.Run("non_vacuity", func(t *testing.T) { got, err := skillFrontmatterKeys("---\nname: x\ndescription: y\ncontext: fork\nagent: x\n---\nbody\n") diff --git a/internal/repoguard/prose_contracts_test.go b/internal/repoguard/prose_contracts_test.go index 8a1c7a406..c2604dbaf 100644 --- a/internal/repoguard/prose_contracts_test.go +++ b/internal/repoguard/prose_contracts_test.go @@ -1543,8 +1543,9 @@ var alignmentContracts = []proseContract{ "**Rewrite pass.** When the export reported any `leftovers` or `mentions`, edit the exported copy in place", "Search the rewritten copy for \"docket\" and \"dckt\" as whole words, case-insensitive, code included", "show the person every change as before → after and **post only after they say go**", + "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.", }, - absent: []string{"context: fork", "agent: docket-export"}}, + absent: []string{"context: fork", "agent: docket-export", "a Jira ticket body or comment"}}, // 0578 review: the export reports neither ADR numbers nor bare #N, so the private // ADR/change-number rewrite runs on every private export, not only on leftovers or mentions. {sentinel: "change_0578_export_skill", file: "skills/docket-export/SKILL.md", diff --git a/skills/docket-export/SKILL.md b/skills/docket-export/SKILL.md index 2644e4433..14dfc40ec 100644 --- a/skills/docket-export/SKILL.md +++ b/skills/docket-export/SKILL.md @@ -1,6 +1,6 @@ --- name: docket-export -description: Use when asked to export a docket change, spec, plan, or results file, or to put one into anything outside docket — a Jira ticket body or comment, a document, a message, an email — so its content comes from docket's own export, never the raw file or a hand cleanup. +description: Use when asked to export a docket change, spec, plan, or results file, or to put one into anything outside docket — a document, a message, an email — so its content comes from docket's own export, never the raw file or a hand cleanup. --- # docket-export @@ -9,6 +9,8 @@ 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. + ## 1. Resolve the operations Run `docket capabilities --json` as its own call — the one docket spelling this skill hard-codes. Check that `protocol_version` is 1 and take the `argv` of the entries `open`, `repository.prepare`, and `diagnostic.config`. If the binary is missing or an entry is absent, tell the person their docket installation is broken and stop — never a hand-made export. From 6a55076184062968331f97b975983b45453d51a3 Mon Sep 17 00:00:00 2001 From: Daniel Hanold Date: Mon, 9 Nov 2026 21:21:41 -0500 Subject: [PATCH 7/8] docs: name docket-link-ticket among the inline skills --- docs/install/models-and-effort.md | 6 ++++-- docs/reference/glossary.md | 20 ++++++++++++++----- docs/reference/skills-and-agents.md | 3 ++- internal/assets/embedded/manifest.json | 10 +++++----- .../tree/skills/docket-convention/SKILL.md | 2 +- .../references/agent-layer.md | 2 +- internal/harness/inventory_test.go | 2 +- internal/repoguard/budgets_test.go | 4 ++-- internal/repoguard/prose_contracts_test.go | 10 +++++++++- skills/docket-convention/SKILL.md | 2 +- .../references/agent-layer.md | 2 +- 11 files changed, 42 insertions(+), 21 deletions(-) diff --git a/docs/install/models-and-effort.md b/docs/install/models-and-effort.md index 3ae2fb528..f95509822 100644 --- a/docs/install/models-and-effort.md +++ b/docs/install/models-and-effort.md @@ -22,7 +22,8 @@ design, a cross-cutting change, or a stub whose premise needs tracing through th 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. +no particular model. `docket-link-ticket` runs inline too, because it works with you and posts +through your session's connector. To change the model or effort an autonomous skill runs at: @@ -107,7 +108,8 @@ the two interactive brainstorm skills (`docket-new-change`, `docket-groom-next`) `docket-finalize-change` (which keeps a real prompt — the multi-candidate batch confirmation — so a 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. +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. **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/glossary.md b/docs/reference/glossary.md index 36fcff5f7..732120c30 100644 --- a/docs/reference/glossary.md +++ b/docs/reference/glossary.md @@ -1757,7 +1757,7 @@ docket. It runs the `open` operation's export (`--export --print --json`) and pa to a file or another tool, never the raw file. In a private repository it also rewrites what the export leaves that names docket, checks the result, and shows you before → after before posting. -**Used for:** putting a spec or other artifact into a ticket, document, or message from an agent +**Used for:** putting a spec or other artifact into a document or message from an agent session. It runs inline, because it posts with your session's own tools and may ask you first. ### docket-finalize-change @@ -1789,6 +1789,15 @@ stub rather than groom it, routes to `revise`. It runs inline at the session mod /docket-groom-next 412 ``` +### docket-link-ticket + +The skill an agent session uses for ticket work. It links a change to an existing ticket, creates a +ticket from a change, or makes a change from a ticket, working through your session's own +connector tools for the ticket system. It records a link only after the connector confirms. + +**Used for:** handing a change to a ticket system or pulling a ticket in. It runs inline, because it +needs you present and posts through your session's connector. + ### docket-new-change The interactive producer, and the entry point a human runs to propose work. It allocates the change @@ -1838,8 +1847,8 @@ Only skills that never need the human mid-run are forked, because a forked subag back to the human. The forked skills are `docket-status`, `docket-adr`, `docket-implement-next`, and `docket-auto-groom` (`context: fork` + `agent:` frontmatter). -**Used for:** explaining why `docket-new-change`, `docket-groom-next`, `docket-export`, and -`docket-finalize-change` run inline. A headless finalize is authorized by naming ids instead. +**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. ### Harness @@ -1863,8 +1872,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` also stays inline, because it posts with your session's own tools and may ask you -first. +`docket-export` and `docket-link-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. @@ -2372,6 +2381,7 @@ docket development install --source ~/dev/docket - [docket-export](#docket-export) - [docket-finalize-change](#docket-finalize-change) - [docket-groom-next](#docket-groom-next) +- [docket-link-ticket](#docket-link-ticket) - [docket-new-change](#docket-new-change) - [docket-review](#docket-review) - [docket-status](#docket-status) diff --git a/docs/reference/skills-and-agents.md b/docs/reference/skills-and-agents.md index cd9291ad3..2c796fb06 100644 --- a/docs/reference/skills-and-agents.md +++ b/docs/reference/skills-and-agents.md @@ -18,10 +18,11 @@ Each line names one skill directory under `skills/` and its job. - **docket-build** — the build role: route each plan task to a tier worker and run one full-suite gate at the end. - **docket-build-task** — the per-task worker contract: one plan task from focused test through one commit. - **docket-convention** — the shared contract: config, layout, manifest and ADR format, lifecycle, branch model (pure reference). -- **docket-export** — export a change, spec, plan, or results file through docket's own export, or put one into another tool; in a private repository it also rewrites docket references out and shows you before posting. +- **docket-export** — export a change, spec, plan, or results file through docket's own export, or put one into a document, message, or email; in a private repository it also rewrites docket references out and shows you before posting. - **docket-finalize-change** — close a change out: merge if approved, verify, archive, clean up, refresh the board. - **docket-groom-next** — groom the next needs-grooming change to build-ready through an interactive brainstorm. - **docket-implement-next** — implement the next build-ready change end to end to an open PR with no human interaction. +- **docket-link-ticket** — link a change to a ticket in your team's ticket system, create a ticket from a change, or make a change from a ticket; always with you present. - **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. diff --git a/internal/assets/embedded/manifest.json b/internal/assets/embedded/manifest.json index 0010f405d..69f85bf01 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:e3fa81515733f35af701eff662293c1524b46a504decdc24cce034c3f45b3423", + "asset_set_id": "sha256:f6dd34d360b44d6b6242079d94acb4dae6ed03266a1b43029ed1b3b62c5d4ae5", "entries": [ { "path": ".docket.example.yml", @@ -322,15 +322,15 @@ "path": "skills/docket-convention/SKILL.md", "role": "skill", "mode": 420, - "size": 54347, - "sha256": "94f362932340a28e8a36cf9ce9e5fac5a9932f11b7d86d4e1aa44b58ad6cbf12" + "size": 54370, + "sha256": "aa82012df0a805de1ed21ea8a475aead91ca6b033798ca1c5234c4fdccb7292a" }, { "path": "skills/docket-convention/references/agent-layer.md", "role": "skill", "mode": 420, - "size": 14389, - "sha256": "e20ea5e319c3e8129e7976d7ee8ec56948aed358958417b117197386401f84f2" + "size": 14412, + "sha256": "50fe98e714355ef3cf8d7fe4e87939071d7d4d250f17772508a40e7a8bf24e5e" }, { "path": "skills/docket-convention/references/close-out.md", diff --git a/internal/assets/embedded/tree/skills/docket-convention/SKILL.md b/internal/assets/embedded/tree/skills/docket-convention/SKILL.md index 4414f9ca3..24939d87a 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`) and `docket-export` 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`, 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*). 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 4a58b233c..59c4b5502 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 and `docket-export` stay inline, and `docket-finalize-change` stays unforked — its headless merge is gated by a permission +skills, `docket-export`, and `docket-link-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/harness/inventory_test.go b/internal/harness/inventory_test.go index 457dab5c8..ebad4f824 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"} { + for _, known := range []string{"docket-build", "docket-build-task", "docket-convention", "docket-export", "docket-link-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 405385c71..a9b0c5147 100644 --- a/internal/repoguard/budgets_test.go +++ b/internal/repoguard/budgets_test.go @@ -199,10 +199,10 @@ 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, 7527}, // 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, 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) // 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, 1991}, // 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, 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/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) diff --git a/internal/repoguard/prose_contracts_test.go b/internal/repoguard/prose_contracts_test.go index c2604dbaf..57d9808cd 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`) and `docket-export` stay inline"}}, + present: []string{"(`docket-new-change`, `docket-groom-next`), `docket-export`, and `docket-link-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", @@ -1617,6 +1617,14 @@ var alignmentContracts = []proseContract{ "When the draft has open questions, follow with one `change.groom` `outcome: revise` carrying `## Open questions`, using a fresh `path` and `revision` from the `status` operation.", "The import happens once: nothing is synced from the ticket afterwards.", }}, + // 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"}}, + {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", + present: []string{"### docket-link-ticket", "- [docket-link-ticket](#docket-link-ticket)"}}, } // oneLayoutAbsent are the retired metadata-layout spellings. diff --git a/skills/docket-convention/SKILL.md b/skills/docket-convention/SKILL.md index 4414f9ca3..24939d87a 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`) and `docket-export` 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`, 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*). 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 4a58b233c..59c4b5502 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 and `docket-export` stay inline, and `docket-finalize-change` stays unforked — its headless merge is gated by a permission +skills, `docket-export`, and `docket-link-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 From 270b38e32a74ccafa85b9ed951a15b83a6f3cb9a Mon Sep 17 00:00:00 2001 From: Daniel Hanold Date: Mon, 9 Nov 2026 21:32:55 -0500 Subject: [PATCH 8/8] fix: address three minor link-ticket review findings - status test: an active fix change with a complete ticket is filtered out of changes by the feat type filter but its records row still carries the ticket. - docket-link-ticket link path: given only an id, the provider is tickets.provider and the URL comes from the connector's read of the ticket; with no connector, ask the person for the URL. - create path: the open operation's argv is resolved from the capability catalog, never hard-coded. Regenerated embedded assets and re-measured the two skill budget rows. --- internal/app/status_test.go | 7 ++++++- internal/assets/embedded/manifest.json | 10 +++++----- .../embedded/tree/skills/docket-link-ticket/SKILL.md | 2 +- .../skills/docket-link-ticket/references/create.md | 2 +- internal/repoguard/budgets_test.go | 4 ++-- skills/docket-link-ticket/SKILL.md | 2 +- skills/docket-link-ticket/references/create.md | 2 +- 7 files changed, 17 insertions(+), 12 deletions(-) diff --git a/internal/app/status_test.go b/internal/app/status_test.go index 41ee04f73..a43657b8a 100644 --- a/internal/app/status_test.go +++ b/internal/app/status_test.go @@ -226,6 +226,7 @@ func TestStatusRecordsCarryTicket(t *testing.T) { changeBlob(2, "plain", "feat", "high", ""), changeBlob(3, "partial", "feat", "high", "ticket_provider: jira\nticket_id: CLOUD-123\n"), changeBlob(4, "badurl", "feat", "high", "ticket_provider: jira\nticket_id: CLOUD-123\nticket_url: 'javascript:x'\n"), + changeBlob(6, "activefix", "fix", "high", "ticket_provider: jira\nticket_id: CLOUD-600\nticket_url: 'https://tickets.example.com/browse/CLOUD-600'\n"), archived, adrBlob(71, "an-adr"), }, @@ -244,6 +245,7 @@ func TestStatusRecordsCarryTicket(t *testing.T) { "change/0003": nil, "change/0004": nil, "change/0005": {Provider: "jira", ID: "CLOUD-500", URL: "https://tickets.example.com/browse/CLOUD-500"}, + "change/0006": {Provider: "jira", ID: "CLOUD-600", URL: "https://tickets.example.com/browse/CLOUD-600"}, "adr/0071": nil, } seen := map[string]bool{} @@ -268,6 +270,9 @@ func TestStatusRecordsCarryTicket(t *testing.T) { if c.ID == 5 { t.Errorf("archived fix change 5 appears in changes: %+v", c) } + if c.ID == 6 { + t.Errorf("type-filtered active fix change 6 appears in changes: %+v", c) + } } b, err := json.Marshal(res) @@ -284,7 +289,7 @@ func TestStatusRecordsCarryTicket(t *testing.T) { for _, r := range doc.Records { _, has := r["ticket"] id, _ := r["identity"].(string) - wantKey := r["kind"] == "change" && (id == "0001" || id == "0005") + wantKey := r["kind"] == "change" && (id == "0001" || id == "0005" || id == "0006") if has != wantKey { t.Errorf("record %v/%s: ticket key present = %v, want %v (%v)", r["kind"], id, has, wantKey, r["ticket"]) } diff --git a/internal/assets/embedded/manifest.json b/internal/assets/embedded/manifest.json index 69f85bf01..4e46a8f53 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:f6dd34d360b44d6b6242079d94acb4dae6ed03266a1b43029ed1b3b62c5d4ae5", + "asset_set_id": "sha256:60e11b79e6262da8e8592ee230c6cd01bdfaef596f5a937409b1c9d11219d411", "entries": [ { "path": ".docket.example.yml", @@ -420,15 +420,15 @@ "path": "skills/docket-link-ticket/SKILL.md", "role": "skill", "mode": 420, - "size": 4916, - "sha256": "52a8de2557af3056e83e2571af6b19acb84c3aed692d014526d19afeb73e1786" + "size": 5075, + "sha256": "260ec3e50a5bc14b52bc21d6ad82f7053f86b4715a62aebdda718a73e2b71a41" }, { "path": "skills/docket-link-ticket/references/create.md", "role": "skill", "mode": 420, - "size": 5185, - "sha256": "ab60ac2773e29ad4d237919bc90047f7a3156e36c0db7685d6b838f71dc95d86" + "size": 5259, + "sha256": "79f5cfa7d582cc125fd8a7e679c3db5d684b5e36c9674f98939b2298667546b5" }, { "path": "skills/docket-link-ticket/references/import.md", 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 721778f80..ceb425377 100644 --- a/internal/assets/embedded/tree/skills/docket-link-ticket/SKILL.md +++ b/internal/assets/embedded/tree/skills/docket-link-ticket/SKILL.md @@ -33,7 +33,7 @@ When creating a ticket from a change, **read `references/create.md` now (blockin ## Link path 1. The person names a change and a ticket: a URL, or an id when `tickets.site` is set. -2. **Provider and id.** When the URL's host matches `tickets.site`, the provider is `tickets.provider`; otherwise ask the person. The id is the ticket's key as the provider shows it, read through the connector (preferred) or from the URL. +2. **Provider and id.** When the URL's host matches `tickets.site`, the provider is `tickets.provider`; otherwise ask the person. The id is the ticket's key as the provider shows it, read through the connector (preferred) or from the URL. Given only an id, the provider is `tickets.provider` and the URL comes from the connector's read of the ticket; with no connector, ask the person for the URL. 3. **Check the ticket.** Confirm the ticket exists through the connector when one is available. With none, the person may still link by URL — the link is a record, not a ticket call — and the report says the ticket was not verified. 4. **Other changes.** Name any other change that already carries this ticket (shared rules). 5. **Record it.** Run the `change.link-ticket` operation with the change's `path` and `revision`. On `already-linked-elsewhere`, tell the person which ticket the change carries now, and send `replace: true` only if they say so. Unlink only when the person asks. Report the disposition in plain words: `linked` (now linked), `already-linked` (it already carried this ticket), `replaced` (the old link was swapped for the new one), `unlinked` (the link was removed), or `nothing-to-unlink` (it had no link to remove). diff --git a/internal/assets/embedded/tree/skills/docket-link-ticket/references/create.md b/internal/assets/embedded/tree/skills/docket-link-ticket/references/create.md index 4fa46742c..aa829fdf1 100644 --- a/internal/assets/embedded/tree/skills/docket-link-ticket/references/create.md +++ b/internal/assets/embedded/tree/skills/docket-link-ticket/references/create.md @@ -21,7 +21,7 @@ Loaded from `SKILL.md` when the person asks to create a ticket from a change. Th 5. **Export the body.** Invoke the `docket-export` skill as a **file request** — its rules are its own; do not restate or re-run them — **DIRECTED to:** export `change ` with `--output-path` set to a fresh directory from `mktemp -d "${TMPDIR:-/tmp}/docket-link-ticket.XXXXXX"`, return the path and, in a private repository, the before → after list, and post nothing. The export's H1 is the title; its body keeps Why, What changes, Acceptance criteria, Out of scope, and Open questions. 6. **Spec, when the change has a `spec:`.** The spec is always included, labeled as the proposed approach, never as requirements. There is no separate question: the person's go on the draft is the only approval. - - **Shared repository:** run the `open` argv as ` spec --print --json`. When `target_kind` is `url`, the body ends with one line, `Proposed approach: `. That is a branch link, not one pinned to a commit: the description is written once, so a pinned link would go stale after a later spec revision. + - **Shared repository:** resolve the `open` operation's argv from the capability catalog, never hard-coded, and run it as ` spec --print --json`. When `target_kind` is `url`, the body ends with one line, `Proposed approach: `. That is a branch link, not one pinned to a commit: the description is written once, so a pinned link would go stale after a later spec revision. - **No URL, or a private repository:** A local path never goes into a ticket. When `target_kind` is `file`, or the repository is private, export the spec through `docket-export` as a file request (as in step 5) and attach it after the ticket exists (step 9). The body ends with `Proposed approach: see the attached `. 7. **Draft and approval.** Show the person, in one message, the title, the project, the mapped type, the body as it will be posted, the spec line or attachment name, and in a private repository the before → after list for the body and the spec. Create only on their go. A `docket-export` word-check hit stops the draft the way `docket-export` does: show the lines and post nothing until the person decides. diff --git a/internal/repoguard/budgets_test.go b/internal/repoguard/budgets_test.go index a9b0c5147..05d7fb17a 100644 --- a/internal/repoguard/budgets_test.go +++ b/internal/repoguard/budgets_test.go @@ -215,8 +215,8 @@ 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, 788}, // 0584: new — the inline ticket-linking skill - {"docket-link-ticket/references/create.md", 35, 843}, // 0584: new — the push path + {"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/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) {"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) diff --git a/skills/docket-link-ticket/SKILL.md b/skills/docket-link-ticket/SKILL.md index 721778f80..ceb425377 100644 --- a/skills/docket-link-ticket/SKILL.md +++ b/skills/docket-link-ticket/SKILL.md @@ -33,7 +33,7 @@ When creating a ticket from a change, **read `references/create.md` now (blockin ## Link path 1. The person names a change and a ticket: a URL, or an id when `tickets.site` is set. -2. **Provider and id.** When the URL's host matches `tickets.site`, the provider is `tickets.provider`; otherwise ask the person. The id is the ticket's key as the provider shows it, read through the connector (preferred) or from the URL. +2. **Provider and id.** When the URL's host matches `tickets.site`, the provider is `tickets.provider`; otherwise ask the person. The id is the ticket's key as the provider shows it, read through the connector (preferred) or from the URL. Given only an id, the provider is `tickets.provider` and the URL comes from the connector's read of the ticket; with no connector, ask the person for the URL. 3. **Check the ticket.** Confirm the ticket exists through the connector when one is available. With none, the person may still link by URL — the link is a record, not a ticket call — and the report says the ticket was not verified. 4. **Other changes.** Name any other change that already carries this ticket (shared rules). 5. **Record it.** Run the `change.link-ticket` operation with the change's `path` and `revision`. On `already-linked-elsewhere`, tell the person which ticket the change carries now, and send `replace: true` only if they say so. Unlink only when the person asks. Report the disposition in plain words: `linked` (now linked), `already-linked` (it already carried this ticket), `replaced` (the old link was swapped for the new one), `unlinked` (the link was removed), or `nothing-to-unlink` (it had no link to remove). diff --git a/skills/docket-link-ticket/references/create.md b/skills/docket-link-ticket/references/create.md index 4fa46742c..aa829fdf1 100644 --- a/skills/docket-link-ticket/references/create.md +++ b/skills/docket-link-ticket/references/create.md @@ -21,7 +21,7 @@ Loaded from `SKILL.md` when the person asks to create a ticket from a change. Th 5. **Export the body.** Invoke the `docket-export` skill as a **file request** — its rules are its own; do not restate or re-run them — **DIRECTED to:** export `change ` with `--output-path` set to a fresh directory from `mktemp -d "${TMPDIR:-/tmp}/docket-link-ticket.XXXXXX"`, return the path and, in a private repository, the before → after list, and post nothing. The export's H1 is the title; its body keeps Why, What changes, Acceptance criteria, Out of scope, and Open questions. 6. **Spec, when the change has a `spec:`.** The spec is always included, labeled as the proposed approach, never as requirements. There is no separate question: the person's go on the draft is the only approval. - - **Shared repository:** run the `open` argv as ` spec --print --json`. When `target_kind` is `url`, the body ends with one line, `Proposed approach: `. That is a branch link, not one pinned to a commit: the description is written once, so a pinned link would go stale after a later spec revision. + - **Shared repository:** resolve the `open` operation's argv from the capability catalog, never hard-coded, and run it as ` spec --print --json`. When `target_kind` is `url`, the body ends with one line, `Proposed approach: `. That is a branch link, not one pinned to a commit: the description is written once, so a pinned link would go stale after a later spec revision. - **No URL, or a private repository:** A local path never goes into a ticket. When `target_kind` is `file`, or the repository is private, export the spec through `docket-export` as a file request (as in step 5) and attach it after the ticket exists (step 9). The body ends with `Proposed approach: see the attached `. 7. **Draft and approval.** Show the person, in one message, the title, the project, the mapped type, the body as it will be posted, the spec line or attachment name, and in a private repository the before → after list for the body and the spec. Create only on their go. A `docket-export` word-check hit stops the draft the way `docket-export` does: show the lines and post nothing until the person decides.