From 77f6053538da184d069d38a2d0d039f00fbebc45 Mon Sep 17 00:00:00 2001 From: Daniel Hanold Date: Tue, 10 Nov 2026 13:23:28 -0500 Subject: [PATCH 1/6] Add design spec: Post a ticket update on request in a private repository --- ...-request-in-a-private-repository-design.md | 106 ++++++++++++++++++ 1 file changed, 106 insertions(+) create mode 100644 docs/superpowers/specs/2026-11-10-post-a-ticket-update-on-request-in-a-private-repository-design.md diff --git a/docs/superpowers/specs/2026-11-10-post-a-ticket-update-on-request-in-a-private-repository-design.md b/docs/superpowers/specs/2026-11-10-post-a-ticket-update-on-request-in-a-private-repository-design.md new file mode 100644 index 000000000..5f39555a6 --- /dev/null +++ b/docs/superpowers/specs/2026-11-10-post-a-ticket-update-on-request-in-a-private-repository-design.md @@ -0,0 +1,106 @@ +# Post a ticket update on request in a private repository: design + +Change 0586 — Post a ticket update on request in a private repository + +Change #586, groomed interactively on 2026-11-10. + +## What this change delivers + +`docket-update-ticket` (built by change #585) posts a short comment to a change's linked ticket when a person asks. In a private repository it currently refuses ("private repositories are not supported yet"), because the commit-pinned links it posts in a shared repository point at files nobody outside can open. This change replaces that refusal with private delivery: each artifact the update names is exported and cleaned through `docket-export`, attached to the ticket, and named in the comment. Attachments go up first; the comment goes last. A failed upload posts no comment. + +This change is attended only: a person asked for the update and is in the session. Automatic posting in a private repository, with no person to review the cleanup, is change #588. + +## Why + +In a private repository the artifact cannot be linked: the metadata branch is local, and `context.ticket` returns an empty `url` for every artifact. The people reading the ticket still need the spec or results file, so it must travel as an attachment, and nothing that leaves (the comment or an attachment) may reveal docket. + +## Settled decisions (carried from change 581; not reopened) + +Restated so the build needs nothing from change 581. + +1. **Delivery follows visibility.** The repository's existing `visibility` (from `context.ticket`, the same value `repository.prepare` reports) decides shared or private delivery. No new flag, no override, and no probe of who can read what. +2. **Private delivery attaches, it does not link.** The relevant artifact is exported (`open … --export --print --json`) and cleaned, then attached to the ticket, and the comment names the attachment. +3. **Nothing posted may contain docket machinery** (the private-repository writing rule): the words "docket" or "dckt", docket marker comments, `Docket-` trailers, `.docket` or `dckt` paths, change ids or change references, docket ADR numbers, or references to the backlog or board. This covers the comment and every attachment. +4. **Attended review is docket-export's.** The person sees the before → after of any rewrite the cleanup made, and the post goes out on their go. +5. **Attachments first, comment last.** If a required attachment cannot be uploaded, no comment is posted and the report says why. A local path is never substituted for an attachment. +6. **Never assume a one-call upload.** In the Claude Code harness the Atlassian connector attaches a file in two steps: `uploadAttachmentToJiraIssue` first returns an upload command that has to run from the shell, then attaches the file id that command returns. An agent that cannot run that step is on the upload-failed path. Connector operations may be reachable only through the connector's discovery tool (the Atlassian connector's `discover`), never assumed to be in the tool list. +7. **Failure is one report line.** Connector missing, upload or post failed, or outcome uncertain: the report names what was not posted and why; nothing stops, retries, or is recorded. An uncertain outcome is reported as uncertain. Nothing is reported as posted or attached without the connector's confirmation. Duplicates (comments or attachments) are acceptable and deleted by hand. +8. **Plans never go out**, as in shared delivery. + +Everything else in `docket-update-ticket` is unchanged: the read, the refusals (other than the private one), the per-update content table, the late-update rule, the editorial standard, the layout guidance, mentions, and posting one connector call at a time. + +## Decisions made in this grooming + +### 1. Which artifacts are attached: the existing Links column, unchanged + +`docket-update-ticket`'s update table already names, per update, what goes with it. Private delivery reuses that column as-is; there is no second table. + +| Update | Shared | Private | +|---|---|---| +| spec written | spec link | spec attached | +| PR opened | PR, spec, results links | PR link stays a link; spec and results attached | +| PR merged | results link | results attached | +| results completed | results link | results attached | +| revision, blocker, or kill | links to the artifacts it discusses | those artifacts attached | + +- **The PR link stays a link.** It is the code PR on the hosting site, not docket machinery (change 581 allows a ticket URL in a private repository's PR body by the same reasoning). `facts.pr_url` is used as in shared delivery. +- **The PR-opened update attaches the spec even when an earlier spec-written update already did.** In most teams the PR is the first time the spec reaches the ticket (spec reviews are rarer), and the reviewer gets everything in the one comment without hunting for an earlier attachment. A duplicate file on the ticket is acceptable. +- **A missing artifact is skipped**, as shared delivery skips a missing link: an artifact the update names but `artifacts` does not return (an older change whose file is not on the metadata branch) is left out, and the comment does not mention it. + +### 2. Calling docket-export: as a file request + +For each artifact to attach, `docket-update-ticket` invokes the `docket-export` skill as a **file request**, the same way `docket-link-ticket`'s create path does — `docket-export`'s rules are its own and are not restated: **DIRECTED to** export ` ` (`spec` or `results`) with `--output-path` set to a fresh directory from `mktemp -d "${TMPDIR:-/tmp}/docket-update-ticket.XXXXXX"`, return the exported path and the before → after list, and post nothing. `docket-update-ticket` then does the uploading and posting itself. + +- **A failed export posts nothing** (`docket-export`'s own rule): no attachment, no comment; the report names the failed export. +- **A word-check hit inside the export stops** the way `docket-export` stops: show the person the path and the lines, and post nothing until they decide. +- Change #588 reuses this same file-request path for unattended posting, so attended and unattended share one export call. +- The export reads the metadata checkout as it stands, while the comment is composed from `metadata_commit`; both come from the same fresh sync moments apart, so they agree in practice. No pinning is added. + +### 3. The comment's own text: written clean, checked, fixed quietly + +`docket-export` cleans files only; the comment is written by the agent. So: + +- The agent writes the comment under the private-repository writing rule: no change ids or change references (`#612`), no docket ADR numbers, no backlog or board references, no "docket" or "dckt". +- Attachments are named, labeled like links: `Spec: attached `, `Results: attached `. +- Before posting, the agent searches the comment and every attachment's file name for "docket" and "dckt" as whole words, case-insensitive (the bare word "docket" is exempt when `leak_check.match_word` is `false`, read as `docket-export` reads it). On a hit it fixes its own text — rewording the comment, or renaming the exported file in its temp directory — **quietly**: there is no before → after for the agent's own words. + +### 4. When the person is asked + +- **The export rewrote something:** stop once, show the before → after list for each attachment and the names of the files to be attached, and post on the person's go. +- **Nothing was rewritten:** post straight away, as shared delivery does and as `docket-export` does. When the person asks to see the update first, show it and post on their go (unchanged). + +### 5. Upload order and the partial-failure rule + +1. Upload each attachment to `ticket.id`, one connector call at a time, handling the two-step upload where the connector needs it. +2. **Every attachment the update names, and whose file exists, is required.** Any failed or uncertain upload means **no comment**. The report is one plain line naming the ticket, which upload failed and why, which attachments already landed on the ticket (the agent never deletes from a ticket), and the exported files' paths so the person can attach them by hand. For example: `Not posted: the results upload to CLOUD-123 failed (connector error). The spec is already attached there; delete it, or ask again. Exported files: .` Asking again uploads the already-landed file a second time; that duplicate is acceptable. +3. After every upload is confirmed, post the comment last. Report it as posted only with the connector's confirmation, naming the ticket, the attachments, and anyone mentioned. + +Never print a credential: when the two-step upload's shell command carries a token, it is run, not echoed into the report. + +## What gets built + +- **`skills/docket-update-ticket/SKILL.md`:** + - Section 2: remove the refusal "`visibility` is `private`: say private repositories are not supported yet". + - Section 4 (Links): add the private route beside the shared one — when `visibility` is `private`, **read `references/private.md` now (blocking)**. + - The convention paragraph's "This skill makes no docket write. Its reads are the `context.ticket` operation and, for a request naming only a ticket, the `status` operation" stops being complete: private delivery also invokes `docket-export`, which writes a temp file and may read `leak_check.match_word` through `diagnostic.config`. Reword it to cover that (still no docket metadata write), and update its pinned copy in the `change_0585_update_ticket_skill` sentinel with it. The exact wording is the builder's call. + - Reword the table's "Links" column header (or a one-line note) so the column reads as "what goes with the update", linked in a shared repository and attached in a private one. +- **New `skills/docket-update-ticket/references/private.md`**, the sibling of `references/shared.md`, carrying decisions 1–5 above: which files attach and the PR-link exception, the docket-export file-request call (with its DIRECTED direction and temp directory), the comment's writing rule and quiet self-fix, the single review stop on a rewrite, the upload order, the two-step upload and discovery-tool note, the partial-failure rule and report line, and the no-credential rule. Like `shared.md`, it says the rules in `SKILL.md` apply and are not repeated. +- **Docs:** `docs/reference/skills-and-agents.md` drops "shared repositories only for now"; `docs/reference/glossary.md`'s `docket-update-ticket` entry replaces "In a private repository it posts nothing yet" with one sentence on attachments. +- **Guards** (`internal/repoguard/prose_contracts_test.go`): change #585's sentinel pins the "not supported yet" string as present; move it to the change's `absent` list and add a `change_0586_update_ticket_private` sentinel pinning `private.md`'s load-bearing sentences (attachments first, comment last; any failed upload posts no comment; never substitute a local path; never assume a one-call upload; the file-request call; the quiet self-fix). Extend the existing check that `references/shared.md` can be read to `references/private.md` (`internal/repoguard/update_ticket_skill_test.go`). Each new guard is mutation-tested. +- **Budgets** (`internal/repoguard/budgets_test.go`): update the `docket-update-ticket/SKILL.md` line and add one for `references/private.md`, each with a change note. +- **Embedded tree:** regenerate with `go generate ./internal/assets/`. +- **No binary change.** `context.ticket` already returns `visibility` and an empty `url` per artifact in a private repository; `docket-export`'s file-request path already returns the cleaned file and its before → after list. + +## Acceptance criteria + +- In a private repository the skill no longer refuses; it loads `references/private.md`. +- The skill text covers: which artifacts attach (the shared Links column; the PR stays a link); the docket-export file-request call; the comment written under the writing rule with a quiet self-fix after the whole-word check over the comment and file names; one review stop only when the export rewrote something; attachments first, comment last; the two-step upload; any failed or uncertain upload posts no comment, with a report line naming what already landed and the exported paths; posted only on the connector's confirmation. +- Guards pin those sentences and fail when each is removed; the full suite passes. +- The results list an **Important** live check: from a private scratch repository (its `tickets.*` keys in `.git/dckt/config.yml`) linked to a sandbox Jira project, ask for a spec-written update and a PR-opened update; confirm the attachments appear before the comment, the comment names them, neither the comment nor the attachments contain docket machinery, and a forced upload failure (for example, a file the connector rejects) posts no comment and reports what already landed. No ticket-system call is made from the docket repository, and no sandbox site or project name appears in it. + +## Out of scope + +- Unattended private posting, skipping the before → after review, the final leak-pattern check over everything posted, and treating unknown visibility as private when nobody can be asked (change #588). +- Automatic posting after each event (change #587). +- Any change to `context.ticket`, `docket-export`, or the leak check's patterns. +- Deleting attachments from a ticket, retrying, or recording what was posted. From e5ca590baf388f676cc547680745a7a0b39b63b3 Mon Sep 17 00:00:00 2001 From: Daniel Hanold Date: Tue, 10 Nov 2026 13:28:27 -0500 Subject: [PATCH 2/6] feat(skills): deliver ticket updates as attachments in a private repository docket-update-ticket no longer refuses in a private repository. SKILL.md routes visibility private to a new references/private.md, which exports each named file through docket-export as a file request, uploads the attachments first and posts the comment last, and posts no comment when any upload fails. Guards: the old refusal moves to the 0585 row's absent list; two new change_0586_update_ticket_private rows pin the route, the convention clause, the table note, and each delivery rule; TestUpdateTicketSkillIsInline now stats every reference SKILL.md routes to, with a floor requiring both shared.md and private.md. Mutation probes (whitespace-collapsed count before/after; mutated -> restored): a re-add refusal bullet 0/1 red->green; b drop private route 1/0 red->green; c route typo privat.md 1/0 red (stat)->green; d move private.md away 1/gone red->green; e revert convention sentence 1/0 red->green; f1-f10 weaken attachments-first, failed-upload-no-comment, no local path, one-call upload, file request, quiet self-fix, single review stop, confirmation-only report, failed export, credential: each 1/0 red->green. --- internal/repoguard/prose_contracts_test.go | 44 ++++++++++++++++++- .../repoguard/update_ticket_skill_test.go | 29 +++++++++--- skills/docket-update-ticket/SKILL.md | 11 +++-- .../references/private.md | 12 +++++ 4 files changed, 83 insertions(+), 13 deletions(-) create mode 100644 skills/docket-update-ticket/references/private.md diff --git a/internal/repoguard/prose_contracts_test.go b/internal/repoguard/prose_contracts_test.go index a33823678..c991e9cc9 100644 --- a/internal/repoguard/prose_contracts_test.go +++ b/internal/repoguard/prose_contracts_test.go @@ -1637,7 +1637,6 @@ var alignmentContracts = []proseContract{ "`partial`: the link is broken; point the person to `docket-link-ticket` to fix or remove it", "The request names a different ticket than `ticket.id`: say which ticket the change carries", "never say the PR has not merged", - "`visibility` is `private`: say private repositories are not supported yet", "Plans never go out: no link to a plan and nothing from one.", "A late update never misstates the current state", "| the PR, the spec, and the results file |", @@ -1657,7 +1656,7 @@ var alignmentContracts = []proseContract{ "`git -C show :`", "when it is empty, say it merged into its parent change's branch without naming the branch", }, - absent: []string{"context: fork", "agent: docket-update-ticket", "Its one read is"}}, + absent: []string{"context: fork", "agent: docket-update-ticket", "Its one read is", "private repositories are not supported yet"}}, {sentinel: "change_0585_update_ticket_skill", file: "skills/docket-update-ticket/references/shared.md", present: []string{ "Each `url` is pinned to `metadata_commit`", @@ -1665,6 +1664,47 @@ var alignmentContracts = []proseContract{ "Links live in the comment only", "never substitute a local path", }}, + // change 0586 — private delivery: the refusal is replaced by a blocking route + // to references/private.md; attachments first, comment last; any failed + // upload posts no comment; the docket-export file request; the quiet + // self-fix; one review stop only on a rewrite. + {sentinel: "change_0586_update_ticket_private", file: "skills/docket-update-ticket/SKILL.md", + present: []string{ + "When `visibility` is `private`, **read `references/private.md` now (blocking)**.", + "This skill makes no docket metadata write.", + "in a private repository it also invokes `docket-export`, which writes each exported file to a temp directory and may read `leak_check.match_word` through `diagnostic.config`", + "The last column names what goes with the update: linked in a shared repository, attached in a private one.", + }, + absent: []string{"This skill makes no docket write."}}, + {sentinel: "change_0586_update_ticket_private", file: "skills/docket-update-ticket/references/private.md", + present: []string{ + "Loaded from `SKILL.md` when `visibility` is `private`. The rules in `SKILL.md` apply; they are not repeated here.", + "The PR link stays a link: it is `facts.pr_url`, as in shared delivery.", + "A PR-opened update attaches the spec even when an earlier update already attached it.", + "An artifact the update names but `artifacts` does not return is left out, and the comment does not mention it.", + "invoke the `docket-export` skill as a **file request**", + "docket-update-ticket.XXXXXX", + "return the exported path and the before → after list, and post nothing", + "A failed export posts nothing: no attachment and no comment", + "A word-check hit inside the export stops the way `docket-export` stops", + "Write it under the private-repository writing rule", + "`Spec: attached `, `Results: attached `", + "search the comment and every attachment's file name for \"docket\" and \"dckt\" as whole words, case-insensitive", + "fix your own text quietly: reword the comment, or rename the exported file in its temp directory", + "Your own words get no before → after.", + "If any export rewrote something, stop once: show the before → after list for each attachment and the names of the files to be attached, and post on the person's go.", + "If nothing was rewritten, post straight away", + "**Attachments first, comment last.**", + "Never assume a one-call upload", + "`uploadAttachmentToJiraIssue` first returns an upload command to run from the shell", + "If you cannot run that step, the upload has failed.", + "Never print a credential", + "**Any failed upload posts no comment.**", + "A failed or uncertain upload means no comment, and never substitute a local path for an attachment.", + "which attachments already landed on the ticket (never delete from a ticket)", + "the exported files' paths so the person can attach them by hand", + "the update as posted only with the connector's confirmation, naming the ticket, the attachments, and anyone mentioned.", + }}, // change 0585 — docket-update-ticket joins the inline skills: export and // link-ticket route update requests to it, the reference docs list it, and // the tickets.provider/site/project keys now have an effect. diff --git a/internal/repoguard/update_ticket_skill_test.go b/internal/repoguard/update_ticket_skill_test.go index a9bbdae85..be5c6469e 100644 --- a/internal/repoguard/update_ticket_skill_test.go +++ b/internal/repoguard/update_ticket_skill_test.go @@ -10,8 +10,8 @@ import ( // TestUpdateTicketSkillIsInline pins docket-update-ticket as an inline skill whose // description names its ask in conversational words, disclaims creating or -// linking, and uses the ticket vocabulary only; and checks that the reference -// SKILL.md routes to exists. +// linking, and uses the ticket vocabulary only; and checks that every +// reference SKILL.md routes to exists. func TestUpdateTicketSkillIsInline(t *testing.T) { const name = "docket-update-ticket" assertInlineSkill(t, name, []string{ @@ -25,14 +25,29 @@ func TestUpdateTicketSkillIsInline(t *testing.T) { t.Errorf("%s description uses %q; the item is a ticket: %q", name, word, desc) } } - // SKILL.md routes shared delivery to this file; a missing one leaves a - // blocking read with nothing to read. - p := filepath.Join(guardRoot(t), "skills", name, "references", "shared.md") - if _, err := os.Stat(p); err != nil { - t.Errorf("%s routes to references/shared.md, which cannot be read: %v", name, err) + // Every reference SKILL.md routes to must exist: a missing one leaves a + // blocking read with nothing to read. Each visibility needs its own + // delivery reference, so both routes must be present. + routed := map[string]bool{} + for _, m := range referenceRoute.FindAllStringSubmatch(body, -1) { + routed[m[1]] = true + } + for _, ref := range []string{"shared.md", "private.md"} { + if !routed[ref] { + t.Errorf("%s routes to no references/%s; each visibility needs its delivery reference", name, ref) + } + } + for ref := range routed { + p := filepath.Join(guardRoot(t), "skills", name, "references", ref) + if _, err := os.Stat(p); err != nil { + t.Errorf("%s routes to references/%s, which cannot be read: %v", name, ref, err) + } } } +// referenceRoute matches a route from a skill body to one of its references. +var referenceRoute = regexp.MustCompile(`references/([a-z0-9-]+\.md)`) + // typedMention matches an at-sign directly before a name: the plain-text // stand-in for a mention, which notifies nobody. var typedMention = regexp.MustCompile(`@\p{L}`) diff --git a/skills/docket-update-ticket/SKILL.md b/skills/docket-update-ticket/SKILL.md index 45e004835..71188aea3 100644 --- a/skills/docket-update-ticket/SKILL.md +++ b/skills/docket-update-ticket/SKILL.md @@ -13,7 +13,7 @@ Words used here: a **ticket** is the item in the team's ticket system; the **pro Invoke the `docket-convention` skill via the Skill tool first — unless already invoked this session — and run its *startup check*. Everything below uses its vocabulary. -This skill makes no docket write. Its reads are the `context.ticket` operation and, for a request naming only a ticket, the `status` operation (section 1). Run `context.ticket` (argv from the capability catalog) with `--id `, `--event ` when the update follows an event, and `--json`. Its result is under `context`: `metadata_commit`, `visibility`, `change` (`status`, `deliverable`, `path`), `ticket` (`state`: `linked`, `not-linked`, or `partial`; and `provider`, `id`, `url` when `linked`), `event` (`happened`, and `reason` when not), `facts` (`pr_url`, `merge`), and `artifacts` (`role`, `path`, `url`). +This skill makes no docket metadata write. Its reads are the `context.ticket` operation and, for a request naming only a ticket, the `status` operation (section 1); in a private repository it also invokes `docket-export`, which writes each exported file to a temp directory and may read `leak_check.match_word` through `diagnostic.config` (section 4). Run `context.ticket` (argv from the capability catalog) with `--id `, `--event ` when the update follows an event, and `--json`. Its result is under `context`: `metadata_commit`, `visibility`, `change` (`status`, `deliverable`, `path`), `ticket` (`state`: `linked`, `not-linked`, or `partial`; and `provider`, `id`, `url` when `linked`), `event` (`happened`, and `reason` when not), `facts` (`pr_url`, `merge`), and `artifacts` (`role`, `path`, `url`). ## 1. Work out the request @@ -30,13 +30,12 @@ Post nothing and say why in one plain line when: - `ticket.state` is `partial`: the link is broken; point the person to `docket-link-ticket` to fix or remove it. - The request names a different ticket than `ticket.id`: say which ticket the change carries. - `event.happened` is false: name the missing fact from `event.reason`. `no-spec`: the change has no spec. `no-pr`: it has no PR. `not-results-artifact`: it does not end in a results file. `not-completed`: its results are not complete. `merge-not-recorded`: say docket has not recorded a merge for the change and that, if the PR has merged, refreshing with `docket-status` records it; never say the PR has not merged. `killed`: the change was killed, so there is no merge or results update to post; offer a kill update instead. -- `visibility` is `private`: say private repositories are not supported yet. ## 3. Write the update Read what the update needs: each file in `artifacts` at its `path`, and the change record at `change.path` for `## Closeout notes` or `## Why killed`. Read each one as it stood at the pinned commit, from the metadata worktree (`metadata_worktree_path` from the startup check's `repository.prepare` context): `git -C show :`. The record is read, never linked. Plans never go out: no link to a plan and nothing from one. -| Update | It says | Links | +| Update | It says | Goes with it | |---|---|---| | spec written | the approach and key decisions, and where the change stands now from its `status` (designed, not yet built; being built; built, PR open; merged); never a claim of review, approval, or authorship | the spec | | PR opened | the PR link, what was built, what the reviewer needs to know | the PR, the spec, and the results file | @@ -44,6 +43,8 @@ Read what the update needs: each file in `artifacts` at its `path`, and the chan | results completed | findings, conclusions, limits, and any action needed | the results file | | revision, blocker, or kill (no event) | what the person said, backed by the artifacts; for a kill, the record's `## Why killed` | the artifacts it discusses | +The last column names what goes with the update: linked in a shared repository, attached in a private one. + A late update never misstates the current state: compare the event with the current `change.status` and say what has happened since (a PR-opened update asked for after the merge says the PR has since merged). **Editorial standard.** Updates are for people: a few short sentences or bullets, scaled to how much the update matters. Include, when relevant, what happened; what matters (key outcomes, consequential decisions, limitations); what is needed next from the reader (an action, test, review, or decision); and the links. Leave out how you worked, brainstorming notes and work logs, file lists, test inventories, command output, repeated background, filler, empty headings, and pasted artifact contents. Keep every material blocker, risk, and required action, however short the update. Say only what the change and its evidence support: a merge is not a deployment or an acceptance. @@ -77,10 +78,12 @@ A late update never misstates the current state: compare the event with the curr (Real links carry the full commit id.) -## 4. Links +## 4. Links and attachments When `visibility` is `shared`, **read `references/shared.md` now (blocking)**. +When `visibility` is `private`, **read `references/private.md` now (blocking)**. + ## 5. Mentions A mention makes the ticket system notify a person. Mention only people the person names, and only as they ask. For each name, search the connector's users (in Jira, its user lookup, which may be reachable only through its discovery tool). diff --git a/skills/docket-update-ticket/references/private.md b/skills/docket-update-ticket/references/private.md new file mode 100644 index 000000000..4e8c72ee2 --- /dev/null +++ b/skills/docket-update-ticket/references/private.md @@ -0,0 +1,12 @@ +# Private delivery + +Loaded from `SKILL.md` when `visibility` is `private`. The rules in `SKILL.md` apply; they are not repeated here. In a private repository nothing can be linked: each `artifacts` entry's `url` is empty and the metadata branch is local. So each file the update names goes to the ticket as an attachment, and the comment names it. + +- **Which files.** The ones the update's row in `SKILL.md` names, attached instead of linked: the spec, the results file, or the artifacts a revision, blocker, or kill discusses. The PR link stays a link: it is `facts.pr_url`, as in shared delivery. A PR-opened update attaches the spec even when an earlier update already attached it. An artifact the update names but `artifacts` does not return is left out, and the comment does not mention it. +- **Export each file.** For each one, invoke the `docket-export` skill as a **file request** — its rules are its own; do not restate or re-run them — **DIRECTED to:** export ` ` (`spec` or `results`) with `--output-path` set to a fresh directory from `mktemp -d "${TMPDIR:-/tmp}/docket-update-ticket.XXXXXX"`, return the exported path and the before → after list, and post nothing. You do the uploading and posting. A failed export posts nothing: no attachment and no comment; report the failed export. A word-check hit inside the export stops the way `docket-export` stops: show the person the path and the lines, and post nothing until they decide. +- **Write the comment clean.** Write it under the private-repository writing rule: no change ids or change references (`#612`), no ADR numbers, no backlog or board references, and no "docket" or "dckt". Name each attachment, labeled like a link: `Spec: attached `, `Results: attached `. +- **Check your own words.** Before posting, search the comment and every attachment's file name for "docket" and "dckt" as whole words, case-insensitive (the bare word "docket" is exempt when `leak_check.match_word` is `false`, read as `docket-export` reads it). On a hit, fix your own text quietly: reword the comment, or rename the exported file in its temp directory. Your own words get no before → after. +- **When to ask.** If any export rewrote something, stop once: show the before → after list for each attachment and the names of the files to be attached, and post on the person's go. If nothing was rewritten, post straight away; when the person asks to see the update first, show it and post on their go. +- **Attachments first, comment last.** Upload each attachment to `ticket.id`, one connector call at a time, then post the comment. Never assume a one-call upload: some connectors attach in two steps. The Atlassian connector's `uploadAttachmentToJiraIssue` first returns an upload command to run from the shell, then attaches the file id that command returns; it may be reachable only through the connector's discovery tool (`discover`). If you cannot run that step, the upload has failed. Never print a credential: when the upload command carries a token, run it; never echo it into the report. +- **Any failed upload posts no comment.** Every attachment the update names, and whose file exists, is required. A failed or uncertain upload means no comment, and never substitute a local path for an attachment. Report in one plain line the ticket, which upload failed and why, which attachments already landed on the ticket (never delete from a ticket), and the exported files' paths so the person can attach them by hand: `Not posted: the results upload to CLOUD-123 failed (connector error). The spec is already attached there; delete it, or ask again. Exported files: .` Asking again uploads a landed file a second time; that duplicate is acceptable. +- **Report** the update as posted only with the connector's confirmation, naming the ticket, the attachments, and anyone mentioned. From f0b9fadd282e8a5eba2cc6b1a53db3113f418e26 Mon Sep 17 00:00:00 2001 From: Daniel Hanold Date: Tue, 10 Nov 2026 13:29:30 -0500 Subject: [PATCH 3/6] docs: describe private-repository ticket updates --- docs/reference/glossary.md | 3 ++- docs/reference/skills-and-agents.md | 2 +- internal/repoguard/prose_contracts_test.go | 6 ++++++ 3 files changed, 9 insertions(+), 2 deletions(-) diff --git a/docs/reference/glossary.md b/docs/reference/glossary.md index 2a858f3c3..a43b8e0fe 100644 --- a/docs/reference/glossary.md +++ b/docs/reference/glossary.md @@ -1851,7 +1851,8 @@ inline. The skill an agent session uses to post an update to a change's linked ticket when you ask. It posts one short comment through your session's own connector, with spec and results links pinned to the commit that holds them, and reports the update as posted only when the connector confirms. In a -private repository it posts nothing yet. +private repository it attaches cleaned copies of the spec and results instead of linking them, and +posts the comment only after every attachment lands. **Used for:** telling people in the ticket system that something happened. It runs inline, because it posts through your session's connector. diff --git a/docs/reference/skills-and-agents.md b/docs/reference/skills-and-agents.md index 541fd4300..778c4eb89 100644 --- a/docs/reference/skills-and-agents.md +++ b/docs/reference/skills-and-agents.md @@ -26,7 +26,7 @@ Each line names one skill directory under `skills/` and its job. - **docket-new-change** — capture a new unit of planned work into the backlog through up-front design. - **docket-review** — the bounded read-only whole-branch reviewer role. - **docket-status** — refresh the backlog, sweep merged changes to done, and run health checks. -- **docket-update-ticket** — post a short update to a change's linked ticket when you ask (spec written, PR opened, PR merged, results completed, or a revision, blocker, or kill), with links pinned to the commit that holds them; shared repositories only for now. +- **docket-update-ticket** — post a short update to a change's linked ticket when you ask (spec written, PR opened, PR merged, results completed, or a revision, blocker, or kill), with links pinned to the commit that holds them; in a private repository it attaches cleaned copies of the spec and results instead. ## Default workflow roles diff --git a/internal/repoguard/prose_contracts_test.go b/internal/repoguard/prose_contracts_test.go index c991e9cc9..eeef6e027 100644 --- a/internal/repoguard/prose_contracts_test.go +++ b/internal/repoguard/prose_contracts_test.go @@ -1705,6 +1705,12 @@ var alignmentContracts = []proseContract{ "the exported files' paths so the person can attach them by hand", "the update as posted only with the connector's confirmation, naming the ticket, the attachments, and anyone mentioned.", }}, + {sentinel: "change_0586_update_ticket_private", file: "docs/reference/skills-and-agents.md", + present: []string{"in a private repository it attaches cleaned copies of the spec and results instead"}, + absent: []string{"shared repositories only for now"}}, + {sentinel: "change_0586_update_ticket_private", file: "docs/reference/glossary.md", + present: []string{"In a private repository it attaches cleaned copies of the spec and results instead of linking them, and posts the comment only after every attachment lands."}, + absent: []string{"In a private repository it posts nothing yet."}}, // change 0585 — docket-update-ticket joins the inline skills: export and // link-ticket route update requests to it, the reference docs list it, and // the tickets.provider/site/project keys now have an effect. From 174f3f5233713e0b7b1f298c03f9a0eccb93ffae Mon Sep 17 00:00:00 2001 From: Daniel Hanold Date: Tue, 10 Nov 2026 13:30:16 -0500 Subject: [PATCH 4/6] chore(assets): budget the private delivery reference and regenerate the embedded tree --- internal/assets/embedded/manifest.json | 13 ++++++++++--- .../tree/skills/docket-update-ticket/SKILL.md | 11 +++++++---- .../docket-update-ticket/references/private.md | 12 ++++++++++++ internal/repoguard/budgets_test.go | 3 ++- 4 files changed, 31 insertions(+), 8 deletions(-) create mode 100644 internal/assets/embedded/tree/skills/docket-update-ticket/references/private.md diff --git a/internal/assets/embedded/manifest.json b/internal/assets/embedded/manifest.json index 3d47feeba..8d3aa4db3 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:d27ae524f5ca3e5196ed7dbb3cb96971784e4356b32112838a1b2ebbb636726e", + "asset_set_id": "sha256:dd11658ad9b64172eacd2af02bf31a9e814af04323703f6aa1d2284a8f7cf2bf", "entries": [ { "path": ".docket.example.yml", @@ -462,8 +462,15 @@ "path": "skills/docket-update-ticket/SKILL.md", "role": "skill", "mode": 420, - "size": 9655, - "sha256": "8abccaf9d68c80776191aaaed1167d60eeaf8b97a9ee92157b63c12c32e828cd" + "size": 9987, + "sha256": "e06b45035ce6e9c88088950dd7596bf13f2e2517b50cf38da4d812c591f3ee6b" + }, + { + "path": "skills/docket-update-ticket/references/private.md", + "role": "skill", + "mode": 420, + "size": 3879, + "sha256": "883e261c2b0b30f585a684b0a4ee60176ee74ba240d76baf3c3a6aea91e946f9" }, { "path": "skills/docket-update-ticket/references/shared.md", diff --git a/internal/assets/embedded/tree/skills/docket-update-ticket/SKILL.md b/internal/assets/embedded/tree/skills/docket-update-ticket/SKILL.md index 45e004835..71188aea3 100644 --- a/internal/assets/embedded/tree/skills/docket-update-ticket/SKILL.md +++ b/internal/assets/embedded/tree/skills/docket-update-ticket/SKILL.md @@ -13,7 +13,7 @@ Words used here: a **ticket** is the item in the team's ticket system; the **pro Invoke the `docket-convention` skill via the Skill tool first — unless already invoked this session — and run its *startup check*. Everything below uses its vocabulary. -This skill makes no docket write. Its reads are the `context.ticket` operation and, for a request naming only a ticket, the `status` operation (section 1). Run `context.ticket` (argv from the capability catalog) with `--id `, `--event ` when the update follows an event, and `--json`. Its result is under `context`: `metadata_commit`, `visibility`, `change` (`status`, `deliverable`, `path`), `ticket` (`state`: `linked`, `not-linked`, or `partial`; and `provider`, `id`, `url` when `linked`), `event` (`happened`, and `reason` when not), `facts` (`pr_url`, `merge`), and `artifacts` (`role`, `path`, `url`). +This skill makes no docket metadata write. Its reads are the `context.ticket` operation and, for a request naming only a ticket, the `status` operation (section 1); in a private repository it also invokes `docket-export`, which writes each exported file to a temp directory and may read `leak_check.match_word` through `diagnostic.config` (section 4). Run `context.ticket` (argv from the capability catalog) with `--id `, `--event ` when the update follows an event, and `--json`. Its result is under `context`: `metadata_commit`, `visibility`, `change` (`status`, `deliverable`, `path`), `ticket` (`state`: `linked`, `not-linked`, or `partial`; and `provider`, `id`, `url` when `linked`), `event` (`happened`, and `reason` when not), `facts` (`pr_url`, `merge`), and `artifacts` (`role`, `path`, `url`). ## 1. Work out the request @@ -30,13 +30,12 @@ Post nothing and say why in one plain line when: - `ticket.state` is `partial`: the link is broken; point the person to `docket-link-ticket` to fix or remove it. - The request names a different ticket than `ticket.id`: say which ticket the change carries. - `event.happened` is false: name the missing fact from `event.reason`. `no-spec`: the change has no spec. `no-pr`: it has no PR. `not-results-artifact`: it does not end in a results file. `not-completed`: its results are not complete. `merge-not-recorded`: say docket has not recorded a merge for the change and that, if the PR has merged, refreshing with `docket-status` records it; never say the PR has not merged. `killed`: the change was killed, so there is no merge or results update to post; offer a kill update instead. -- `visibility` is `private`: say private repositories are not supported yet. ## 3. Write the update Read what the update needs: each file in `artifacts` at its `path`, and the change record at `change.path` for `## Closeout notes` or `## Why killed`. Read each one as it stood at the pinned commit, from the metadata worktree (`metadata_worktree_path` from the startup check's `repository.prepare` context): `git -C show :`. The record is read, never linked. Plans never go out: no link to a plan and nothing from one. -| Update | It says | Links | +| Update | It says | Goes with it | |---|---|---| | spec written | the approach and key decisions, and where the change stands now from its `status` (designed, not yet built; being built; built, PR open; merged); never a claim of review, approval, or authorship | the spec | | PR opened | the PR link, what was built, what the reviewer needs to know | the PR, the spec, and the results file | @@ -44,6 +43,8 @@ Read what the update needs: each file in `artifacts` at its `path`, and the chan | results completed | findings, conclusions, limits, and any action needed | the results file | | revision, blocker, or kill (no event) | what the person said, backed by the artifacts; for a kill, the record's `## Why killed` | the artifacts it discusses | +The last column names what goes with the update: linked in a shared repository, attached in a private one. + A late update never misstates the current state: compare the event with the current `change.status` and say what has happened since (a PR-opened update asked for after the merge says the PR has since merged). **Editorial standard.** Updates are for people: a few short sentences or bullets, scaled to how much the update matters. Include, when relevant, what happened; what matters (key outcomes, consequential decisions, limitations); what is needed next from the reader (an action, test, review, or decision); and the links. Leave out how you worked, brainstorming notes and work logs, file lists, test inventories, command output, repeated background, filler, empty headings, and pasted artifact contents. Keep every material blocker, risk, and required action, however short the update. Say only what the change and its evidence support: a merge is not a deployment or an acceptance. @@ -77,10 +78,12 @@ A late update never misstates the current state: compare the event with the curr (Real links carry the full commit id.) -## 4. Links +## 4. Links and attachments When `visibility` is `shared`, **read `references/shared.md` now (blocking)**. +When `visibility` is `private`, **read `references/private.md` now (blocking)**. + ## 5. Mentions A mention makes the ticket system notify a person. Mention only people the person names, and only as they ask. For each name, search the connector's users (in Jira, its user lookup, which may be reachable only through its discovery tool). diff --git a/internal/assets/embedded/tree/skills/docket-update-ticket/references/private.md b/internal/assets/embedded/tree/skills/docket-update-ticket/references/private.md new file mode 100644 index 000000000..4e8c72ee2 --- /dev/null +++ b/internal/assets/embedded/tree/skills/docket-update-ticket/references/private.md @@ -0,0 +1,12 @@ +# Private delivery + +Loaded from `SKILL.md` when `visibility` is `private`. The rules in `SKILL.md` apply; they are not repeated here. In a private repository nothing can be linked: each `artifacts` entry's `url` is empty and the metadata branch is local. So each file the update names goes to the ticket as an attachment, and the comment names it. + +- **Which files.** The ones the update's row in `SKILL.md` names, attached instead of linked: the spec, the results file, or the artifacts a revision, blocker, or kill discusses. The PR link stays a link: it is `facts.pr_url`, as in shared delivery. A PR-opened update attaches the spec even when an earlier update already attached it. An artifact the update names but `artifacts` does not return is left out, and the comment does not mention it. +- **Export each file.** For each one, invoke the `docket-export` skill as a **file request** — its rules are its own; do not restate or re-run them — **DIRECTED to:** export ` ` (`spec` or `results`) with `--output-path` set to a fresh directory from `mktemp -d "${TMPDIR:-/tmp}/docket-update-ticket.XXXXXX"`, return the exported path and the before → after list, and post nothing. You do the uploading and posting. A failed export posts nothing: no attachment and no comment; report the failed export. A word-check hit inside the export stops the way `docket-export` stops: show the person the path and the lines, and post nothing until they decide. +- **Write the comment clean.** Write it under the private-repository writing rule: no change ids or change references (`#612`), no ADR numbers, no backlog or board references, and no "docket" or "dckt". Name each attachment, labeled like a link: `Spec: attached `, `Results: attached `. +- **Check your own words.** Before posting, search the comment and every attachment's file name for "docket" and "dckt" as whole words, case-insensitive (the bare word "docket" is exempt when `leak_check.match_word` is `false`, read as `docket-export` reads it). On a hit, fix your own text quietly: reword the comment, or rename the exported file in its temp directory. Your own words get no before → after. +- **When to ask.** If any export rewrote something, stop once: show the before → after list for each attachment and the names of the files to be attached, and post on the person's go. If nothing was rewritten, post straight away; when the person asks to see the update first, show it and post on their go. +- **Attachments first, comment last.** Upload each attachment to `ticket.id`, one connector call at a time, then post the comment. Never assume a one-call upload: some connectors attach in two steps. The Atlassian connector's `uploadAttachmentToJiraIssue` first returns an upload command to run from the shell, then attaches the file id that command returns; it may be reachable only through the connector's discovery tool (`discover`). If you cannot run that step, the upload has failed. Never print a credential: when the upload command carries a token, run it; never echo it into the report. +- **Any failed upload posts no comment.** Every attachment the update names, and whose file exists, is required. A failed or uncertain upload means no comment, and never substitute a local path for an attachment. Report in one plain line the ticket, which upload failed and why, which attachments already landed on the ticket (never delete from a ticket), and the exported files' paths so the person can attach them by hand: `Not posted: the results upload to CLOUD-123 failed (connector error). The spec is already attached there; delete it, or ask again. Exported files: .` Asking again uploads a landed file a second time; that duplicate is acceptable. +- **Report** the update as posted only with the connector's confirmation, naming the ticket, the attachments, and anyone mentioned. diff --git a/internal/repoguard/budgets_test.go b/internal/repoguard/budgets_test.go index 8c44c40c9..9ba6712bb 100644 --- a/internal/repoguard/budgets_test.go +++ b/internal/repoguard/budgets_test.go @@ -221,7 +221,8 @@ var skillBudgets = []skillBudget{ {"docket-review/SKILL.md", 127, 1054}, // 0573: trivial retired (127/1059 -> 127/1054); 0559: the results-artifact mode (114/966 -> 127/1049); 0559: Inputs and evidence sections defer to results-artifact mode (127/1049 -> 127/1059); 0531: the metadata worktree and remote come from the repository.prepare context (114/965 -> 114/966); 0502: the evidence rule keys on the payload's build.gate value; gate-off skipped records are expected (110/913 -> 114/965); 0410: +findings-return capture contract (see note above) {"docket-new-change/SKILL.md", 48, 1552}, // 0582: optional acceptance_criteria body (48/1538 -> 48/1552); 0573: trivial retired; the trivial path is deleted and the brainstorm is told the artifact is always a spec (53/1636 -> 48/1538); 0560: suggest a hold; it rides change.create or change.groom (53/1598 -> 53/1636); 0559: the create request carries deliverable: results-artifact for findings-only work (57/1635 -> 53/1598); 0532: the private-repository writing rule and visibility hand-off (57/1603 -> 57/1635); 0531: the metadata worktree and remote come from the repository.prepare context (57/1596 -> 57/1603); 0502 review: omitted draft-time scalars are described exactly (57/1591 -> 57/1596); 0502: "loop" means /loop only (57/1593 -> 57/1591); 0502: one metadata layout — the docket branch and the .docket/ worktree (57/1590 -> 57/1593); 0502: terminal-publication narration and the repository auto_groom default are deleted (57/1609 -> 57/1590); 0502: invoke superpowers:brainstorming by name (57/1636 -> 57/1609); 0502: the dummy-mode pointer is deleted (59/1674 -> 57/1636); 0445: +pointer to the docket-groom-next revise path after landing (word ceiling 1700 -> 1706); 0382: draft-time scalars moved into change.create (ceiling 1706 -> 1675) {"docket-status/SKILL.md", 125, 2956}, // 0575: reclaim and the claim lease are retired, the intentional-skip example names snapshot-retained and snapshot-no-work (126/2990 -> 125/2956); 0573: trivial retired (126/2993 -> 126/2990); 0560: a held change shows on hold (126/2983 -> 126/2993); 0539: derived-view drift is named by family and each finding's own remedy is relayed instead of a code list (126/2923 -> 126/2983); 0531: the metadata worktree and remote come from the repository.prepare context (126/2921 -> 126/2923); 0530: artifact-missing names where a plan or results file may live — the docket branch, or the integration branch for a record closed before the move (126/2904 -> 126/2921); 0529 review: full-scope cleanup retries also repoint stale merged-PR description backlinks; repair --pr-backlinks previews them (126/2880 -> 126/2904); 0502: one metadata layout — the docket branch and the .docket/ worktree (126/2876 -> 126/2880); 0502: findings named as the binary emits them (126/2852 -> 126/2876); 0502: deferred learnings and publication narration is deleted (127/2956 -> 126/2852); 0502: the dummy-mode pointer is deleted (129/2985 -> 127/2956); 0388: +sync-integration prose (see note above) - {"docket-update-ticket/SKILL.md", 98, 1521}, // 0585 review: reads pinned to metadata_commit from the metadata worktree, status named as the ticket-only read, and an empty destination_branch names the parent change (98/1465 -> 98/1521); 0585 review: the lead example names a mention placeholder, never a typed @-mention (98/1451 -> 98/1465); 0585 review: a killed change reports the killed reason (98/1431 -> 98/1451); 0585: new — the inline ticket-update skill + {"docket-update-ticket/SKILL.md", 101, 1567}, // 0586: the private refusal becomes a blocking route to references/private.md; the convention paragraph names the docket-export call; the last table column covers attachments (98/1521 -> 101/1567); 0585 review: reads pinned to metadata_commit from the metadata worktree, status named as the ticket-only read, and an empty destination_branch names the parent change (98/1465 -> 98/1521); 0585 review: the lead example names a mention placeholder, never a typed @-mention (98/1451 -> 98/1465); 0585 review: a killed change reports the killed reason (98/1431 -> 98/1451); 0585: new — the inline ticket-update skill + {"docket-update-ticket/references/private.md", 12, 629}, // 0586: new — private delivery {"docket-update-ticket/references/shared.md", 9, 184}, // 0585: new — shared delivery } From 19bba7e5b79fad2539a56c09ba2fbb0c8ce98241 Mon Sep 17 00:00:00 2001 From: Daniel Hanold Date: Tue, 10 Nov 2026 13:40:43 -0500 Subject: [PATCH 5/6] fix(skills): upload private attachments only at the post step, after mentions Review finding (important): references/private.md is a blocking read in SKILL.md's "## 4. Links and attachments", but mentions are settled later in "## 5. Mentions", which can stop to ask the person. Read literally, the "Attachments first, comment last" bullet let the agent upload files in section 4; a cancel at the mention question then left files on the ticket with no comment, and nothing deletes from a ticket. The bullet now says to upload nothing before the post step (SKILL.md section 6), after mentions are settled and after any go the person gives. The clause is pinned in the change_0586_update_ticket_private sentinel (mutation-tested), the private.md budget row is re-pinned (12/629 -> 12/664), and the embedded asset tree is regenerated. --- internal/assets/embedded/manifest.json | 6 +++--- .../tree/skills/docket-update-ticket/references/private.md | 2 +- internal/repoguard/budgets_test.go | 2 +- internal/repoguard/prose_contracts_test.go | 1 + skills/docket-update-ticket/references/private.md | 2 +- 5 files changed, 7 insertions(+), 6 deletions(-) diff --git a/internal/assets/embedded/manifest.json b/internal/assets/embedded/manifest.json index 8d3aa4db3..7c22af9d4 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:dd11658ad9b64172eacd2af02bf31a9e814af04323703f6aa1d2284a8f7cf2bf", + "asset_set_id": "sha256:af55594628652459c43d5b5b18101d74d3d67092e8c3f8951e2d71bb5d63737b", "entries": [ { "path": ".docket.example.yml", @@ -469,8 +469,8 @@ "path": "skills/docket-update-ticket/references/private.md", "role": "skill", "mode": 420, - "size": 3879, - "sha256": "883e261c2b0b30f585a684b0a4ee60176ee74ba240d76baf3c3a6aea91e946f9" + "size": 4077, + "sha256": "e34e117317eafd1652ba2ca5e2361dd8f5a29c561618722e9155e66fa55e0f66" }, { "path": "skills/docket-update-ticket/references/shared.md", diff --git a/internal/assets/embedded/tree/skills/docket-update-ticket/references/private.md b/internal/assets/embedded/tree/skills/docket-update-ticket/references/private.md index 4e8c72ee2..401e0d99d 100644 --- a/internal/assets/embedded/tree/skills/docket-update-ticket/references/private.md +++ b/internal/assets/embedded/tree/skills/docket-update-ticket/references/private.md @@ -7,6 +7,6 @@ Loaded from `SKILL.md` when `visibility` is `private`. The rules in `SKILL.md` a - **Write the comment clean.** Write it under the private-repository writing rule: no change ids or change references (`#612`), no ADR numbers, no backlog or board references, and no "docket" or "dckt". Name each attachment, labeled like a link: `Spec: attached `, `Results: attached `. - **Check your own words.** Before posting, search the comment and every attachment's file name for "docket" and "dckt" as whole words, case-insensitive (the bare word "docket" is exempt when `leak_check.match_word` is `false`, read as `docket-export` reads it). On a hit, fix your own text quietly: reword the comment, or rename the exported file in its temp directory. Your own words get no before → after. - **When to ask.** If any export rewrote something, stop once: show the before → after list for each attachment and the names of the files to be attached, and post on the person's go. If nothing was rewritten, post straight away; when the person asks to see the update first, show it and post on their go. -- **Attachments first, comment last.** Upload each attachment to `ticket.id`, one connector call at a time, then post the comment. Never assume a one-call upload: some connectors attach in two steps. The Atlassian connector's `uploadAttachmentToJiraIssue` first returns an upload command to run from the shell, then attaches the file id that command returns; it may be reachable only through the connector's discovery tool (`discover`). If you cannot run that step, the upload has failed. Never print a credential: when the upload command carries a token, run it; never echo it into the report. +- **Attachments first, comment last.** Upload nothing before the post step (`SKILL.md` section 6): mentions are settled and any go the person gives comes first, so a stop at a mention question leaves nothing on the ticket. At that step, upload each attachment to `ticket.id`, one connector call at a time, then post the comment. Never assume a one-call upload: some connectors attach in two steps. The Atlassian connector's `uploadAttachmentToJiraIssue` first returns an upload command to run from the shell, then attaches the file id that command returns; it may be reachable only through the connector's discovery tool (`discover`). If you cannot run that step, the upload has failed. Never print a credential: when the upload command carries a token, run it; never echo it into the report. - **Any failed upload posts no comment.** Every attachment the update names, and whose file exists, is required. A failed or uncertain upload means no comment, and never substitute a local path for an attachment. Report in one plain line the ticket, which upload failed and why, which attachments already landed on the ticket (never delete from a ticket), and the exported files' paths so the person can attach them by hand: `Not posted: the results upload to CLOUD-123 failed (connector error). The spec is already attached there; delete it, or ask again. Exported files: .` Asking again uploads a landed file a second time; that duplicate is acceptable. - **Report** the update as posted only with the connector's confirmation, naming the ticket, the attachments, and anyone mentioned. diff --git a/internal/repoguard/budgets_test.go b/internal/repoguard/budgets_test.go index 9ba6712bb..f8c9d8058 100644 --- a/internal/repoguard/budgets_test.go +++ b/internal/repoguard/budgets_test.go @@ -222,7 +222,7 @@ var skillBudgets = []skillBudget{ {"docket-new-change/SKILL.md", 48, 1552}, // 0582: optional acceptance_criteria body (48/1538 -> 48/1552); 0573: trivial retired; the trivial path is deleted and the brainstorm is told the artifact is always a spec (53/1636 -> 48/1538); 0560: suggest a hold; it rides change.create or change.groom (53/1598 -> 53/1636); 0559: the create request carries deliverable: results-artifact for findings-only work (57/1635 -> 53/1598); 0532: the private-repository writing rule and visibility hand-off (57/1603 -> 57/1635); 0531: the metadata worktree and remote come from the repository.prepare context (57/1596 -> 57/1603); 0502 review: omitted draft-time scalars are described exactly (57/1591 -> 57/1596); 0502: "loop" means /loop only (57/1593 -> 57/1591); 0502: one metadata layout — the docket branch and the .docket/ worktree (57/1590 -> 57/1593); 0502: terminal-publication narration and the repository auto_groom default are deleted (57/1609 -> 57/1590); 0502: invoke superpowers:brainstorming by name (57/1636 -> 57/1609); 0502: the dummy-mode pointer is deleted (59/1674 -> 57/1636); 0445: +pointer to the docket-groom-next revise path after landing (word ceiling 1700 -> 1706); 0382: draft-time scalars moved into change.create (ceiling 1706 -> 1675) {"docket-status/SKILL.md", 125, 2956}, // 0575: reclaim and the claim lease are retired, the intentional-skip example names snapshot-retained and snapshot-no-work (126/2990 -> 125/2956); 0573: trivial retired (126/2993 -> 126/2990); 0560: a held change shows on hold (126/2983 -> 126/2993); 0539: derived-view drift is named by family and each finding's own remedy is relayed instead of a code list (126/2923 -> 126/2983); 0531: the metadata worktree and remote come from the repository.prepare context (126/2921 -> 126/2923); 0530: artifact-missing names where a plan or results file may live — the docket branch, or the integration branch for a record closed before the move (126/2904 -> 126/2921); 0529 review: full-scope cleanup retries also repoint stale merged-PR description backlinks; repair --pr-backlinks previews them (126/2880 -> 126/2904); 0502: one metadata layout — the docket branch and the .docket/ worktree (126/2876 -> 126/2880); 0502: findings named as the binary emits them (126/2852 -> 126/2876); 0502: deferred learnings and publication narration is deleted (127/2956 -> 126/2852); 0502: the dummy-mode pointer is deleted (129/2985 -> 127/2956); 0388: +sync-integration prose (see note above) {"docket-update-ticket/SKILL.md", 101, 1567}, // 0586: the private refusal becomes a blocking route to references/private.md; the convention paragraph names the docket-export call; the last table column covers attachments (98/1521 -> 101/1567); 0585 review: reads pinned to metadata_commit from the metadata worktree, status named as the ticket-only read, and an empty destination_branch names the parent change (98/1465 -> 98/1521); 0585 review: the lead example names a mention placeholder, never a typed @-mention (98/1451 -> 98/1465); 0585 review: a killed change reports the killed reason (98/1431 -> 98/1451); 0585: new — the inline ticket-update skill - {"docket-update-ticket/references/private.md", 12, 629}, // 0586: new — private delivery + {"docket-update-ticket/references/private.md", 12, 664}, // 0586 review: uploads happen at the post step after mentions (12/629 -> 12/664); 0586: new — private delivery {"docket-update-ticket/references/shared.md", 9, 184}, // 0585: new — shared delivery } diff --git a/internal/repoguard/prose_contracts_test.go b/internal/repoguard/prose_contracts_test.go index eeef6e027..e1f7d8c6b 100644 --- a/internal/repoguard/prose_contracts_test.go +++ b/internal/repoguard/prose_contracts_test.go @@ -1695,6 +1695,7 @@ var alignmentContracts = []proseContract{ "If any export rewrote something, stop once: show the before → after list for each attachment and the names of the files to be attached, and post on the person's go.", "If nothing was rewritten, post straight away", "**Attachments first, comment last.**", + "Upload nothing before the post step (`SKILL.md` section 6): mentions are settled and any go the person gives comes first, so a stop at a mention question leaves nothing on the ticket.", "Never assume a one-call upload", "`uploadAttachmentToJiraIssue` first returns an upload command to run from the shell", "If you cannot run that step, the upload has failed.", diff --git a/skills/docket-update-ticket/references/private.md b/skills/docket-update-ticket/references/private.md index 4e8c72ee2..401e0d99d 100644 --- a/skills/docket-update-ticket/references/private.md +++ b/skills/docket-update-ticket/references/private.md @@ -7,6 +7,6 @@ Loaded from `SKILL.md` when `visibility` is `private`. The rules in `SKILL.md` a - **Write the comment clean.** Write it under the private-repository writing rule: no change ids or change references (`#612`), no ADR numbers, no backlog or board references, and no "docket" or "dckt". Name each attachment, labeled like a link: `Spec: attached `, `Results: attached `. - **Check your own words.** Before posting, search the comment and every attachment's file name for "docket" and "dckt" as whole words, case-insensitive (the bare word "docket" is exempt when `leak_check.match_word` is `false`, read as `docket-export` reads it). On a hit, fix your own text quietly: reword the comment, or rename the exported file in its temp directory. Your own words get no before → after. - **When to ask.** If any export rewrote something, stop once: show the before → after list for each attachment and the names of the files to be attached, and post on the person's go. If nothing was rewritten, post straight away; when the person asks to see the update first, show it and post on their go. -- **Attachments first, comment last.** Upload each attachment to `ticket.id`, one connector call at a time, then post the comment. Never assume a one-call upload: some connectors attach in two steps. The Atlassian connector's `uploadAttachmentToJiraIssue` first returns an upload command to run from the shell, then attaches the file id that command returns; it may be reachable only through the connector's discovery tool (`discover`). If you cannot run that step, the upload has failed. Never print a credential: when the upload command carries a token, run it; never echo it into the report. +- **Attachments first, comment last.** Upload nothing before the post step (`SKILL.md` section 6): mentions are settled and any go the person gives comes first, so a stop at a mention question leaves nothing on the ticket. At that step, upload each attachment to `ticket.id`, one connector call at a time, then post the comment. Never assume a one-call upload: some connectors attach in two steps. The Atlassian connector's `uploadAttachmentToJiraIssue` first returns an upload command to run from the shell, then attaches the file id that command returns; it may be reachable only through the connector's discovery tool (`discover`). If you cannot run that step, the upload has failed. Never print a credential: when the upload command carries a token, run it; never echo it into the report. - **Any failed upload posts no comment.** Every attachment the update names, and whose file exists, is required. A failed or uncertain upload means no comment, and never substitute a local path for an attachment. Report in one plain line the ticket, which upload failed and why, which attachments already landed on the ticket (never delete from a ticket), and the exported files' paths so the person can attach them by hand: `Not posted: the results upload to CLOUD-123 failed (connector error). The spec is already attached there; delete it, or ask again. Exported files: .` Asking again uploads a landed file a second time; that duplicate is acceptable. - **Report** the update as posted only with the connector's confirmation, naming the ticket, the attachments, and anyone mentioned. From f3b5c34e2bc499beaef7c123c0ada3bd901ff2f1 Mon Sep 17 00:00:00 2001 From: Daniel Hanold Date: Tue, 10 Nov 2026 13:41:50 -0500 Subject: [PATCH 6/6] fix(skills): keep the private rewrite stop in update-ticket's post step and ban only docket ADR numbers - SKILL.md post step: the no-draft rule now names the private single stop on a rewrite as its exception (pinned in the change_0586_update_ticket_private sentinel). - references/private.md: the comment writing rule bans docket ADR numbers, not all ADR numbers. --- internal/assets/embedded/manifest.json | 10 +++++----- .../embedded/tree/skills/docket-update-ticket/SKILL.md | 2 +- .../skills/docket-update-ticket/references/private.md | 2 +- internal/repoguard/budgets_test.go | 4 ++-- internal/repoguard/prose_contracts_test.go | 1 + skills/docket-update-ticket/SKILL.md | 2 +- skills/docket-update-ticket/references/private.md | 2 +- 7 files changed, 12 insertions(+), 11 deletions(-) diff --git a/internal/assets/embedded/manifest.json b/internal/assets/embedded/manifest.json index 7c22af9d4..50cf0f444 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:af55594628652459c43d5b5b18101d74d3d67092e8c3f8951e2d71bb5d63737b", + "asset_set_id": "sha256:029addf44b376758f00206f5400b6f9af46d25918e9c63f7cec9efa6a565f613", "entries": [ { "path": ".docket.example.yml", @@ -462,15 +462,15 @@ "path": "skills/docket-update-ticket/SKILL.md", "role": "skill", "mode": 420, - "size": 9987, - "sha256": "e06b45035ce6e9c88088950dd7596bf13f2e2517b50cf38da4d812c591f3ee6b" + "size": 10079, + "sha256": "0f1e7f026c80b35f47c8204d80cabfec7a54aeef0f3e063b73cbf59c097cb57f" }, { "path": "skills/docket-update-ticket/references/private.md", "role": "skill", "mode": 420, - "size": 4077, - "sha256": "e34e117317eafd1652ba2ca5e2361dd8f5a29c561618722e9155e66fa55e0f66" + "size": 4084, + "sha256": "3c23a9f05dec7f4c155cc1e87e95f5d3444ba120fe9cface60738be6bfa52521" }, { "path": "skills/docket-update-ticket/references/shared.md", diff --git a/internal/assets/embedded/tree/skills/docket-update-ticket/SKILL.md b/internal/assets/embedded/tree/skills/docket-update-ticket/SKILL.md index 71188aea3..e2a65e988 100644 --- a/internal/assets/embedded/tree/skills/docket-update-ticket/SKILL.md +++ b/internal/assets/embedded/tree/skills/docket-update-ticket/SKILL.md @@ -97,5 +97,5 @@ A mention makes the ticket system notify a person. Mention only people the perso ## 6. Post and report - **Find the connector** for `ticket.provider`. Never conclude an operation is missing because it is not in your tool list: some connectors expose operations only through a discovery tool (the Atlassian connector's `discover`), so look there first. -- **Post** the comment to `ticket.id`, making connector calls one at a time. Do not show a draft and wait: the person asked for the update. When they ask to see it first, show it and post on their go. +- **Post** the comment to `ticket.id`, making connector calls one at a time. Do not show a draft and wait: the person asked for the update (in a private repository, `references/private.md`'s single stop on a rewrite still applies). When they ask to see it first, show it and post on their go. - **Report.** Report the update as posted only with the connector's confirmation, naming the ticket and anyone mentioned. For a missing connector, a failed post, or an uncertain outcome, say in one plain line what was not posted and why; an uncertain outcome is reported as uncertain, and the person decides whether to ask again. Never run a retry loop. A duplicate comment is deleted by hand. diff --git a/internal/assets/embedded/tree/skills/docket-update-ticket/references/private.md b/internal/assets/embedded/tree/skills/docket-update-ticket/references/private.md index 401e0d99d..14a92bfc5 100644 --- a/internal/assets/embedded/tree/skills/docket-update-ticket/references/private.md +++ b/internal/assets/embedded/tree/skills/docket-update-ticket/references/private.md @@ -4,7 +4,7 @@ Loaded from `SKILL.md` when `visibility` is `private`. The rules in `SKILL.md` a - **Which files.** The ones the update's row in `SKILL.md` names, attached instead of linked: the spec, the results file, or the artifacts a revision, blocker, or kill discusses. The PR link stays a link: it is `facts.pr_url`, as in shared delivery. A PR-opened update attaches the spec even when an earlier update already attached it. An artifact the update names but `artifacts` does not return is left out, and the comment does not mention it. - **Export each file.** For each one, invoke the `docket-export` skill as a **file request** — its rules are its own; do not restate or re-run them — **DIRECTED to:** export ` ` (`spec` or `results`) with `--output-path` set to a fresh directory from `mktemp -d "${TMPDIR:-/tmp}/docket-update-ticket.XXXXXX"`, return the exported path and the before → after list, and post nothing. You do the uploading and posting. A failed export posts nothing: no attachment and no comment; report the failed export. A word-check hit inside the export stops the way `docket-export` stops: show the person the path and the lines, and post nothing until they decide. -- **Write the comment clean.** Write it under the private-repository writing rule: no change ids or change references (`#612`), no ADR numbers, no backlog or board references, and no "docket" or "dckt". Name each attachment, labeled like a link: `Spec: attached `, `Results: attached `. +- **Write the comment clean.** Write it under the private-repository writing rule: no change ids or change references (`#612`), no docket ADR numbers, no backlog or board references, and no "docket" or "dckt". Name each attachment, labeled like a link: `Spec: attached `, `Results: attached `. - **Check your own words.** Before posting, search the comment and every attachment's file name for "docket" and "dckt" as whole words, case-insensitive (the bare word "docket" is exempt when `leak_check.match_word` is `false`, read as `docket-export` reads it). On a hit, fix your own text quietly: reword the comment, or rename the exported file in its temp directory. Your own words get no before → after. - **When to ask.** If any export rewrote something, stop once: show the before → after list for each attachment and the names of the files to be attached, and post on the person's go. If nothing was rewritten, post straight away; when the person asks to see the update first, show it and post on their go. - **Attachments first, comment last.** Upload nothing before the post step (`SKILL.md` section 6): mentions are settled and any go the person gives comes first, so a stop at a mention question leaves nothing on the ticket. At that step, upload each attachment to `ticket.id`, one connector call at a time, then post the comment. Never assume a one-call upload: some connectors attach in two steps. The Atlassian connector's `uploadAttachmentToJiraIssue` first returns an upload command to run from the shell, then attaches the file id that command returns; it may be reachable only through the connector's discovery tool (`discover`). If you cannot run that step, the upload has failed. Never print a credential: when the upload command carries a token, run it; never echo it into the report. diff --git a/internal/repoguard/budgets_test.go b/internal/repoguard/budgets_test.go index f8c9d8058..38506c598 100644 --- a/internal/repoguard/budgets_test.go +++ b/internal/repoguard/budgets_test.go @@ -221,8 +221,8 @@ var skillBudgets = []skillBudget{ {"docket-review/SKILL.md", 127, 1054}, // 0573: trivial retired (127/1059 -> 127/1054); 0559: the results-artifact mode (114/966 -> 127/1049); 0559: Inputs and evidence sections defer to results-artifact mode (127/1049 -> 127/1059); 0531: the metadata worktree and remote come from the repository.prepare context (114/965 -> 114/966); 0502: the evidence rule keys on the payload's build.gate value; gate-off skipped records are expected (110/913 -> 114/965); 0410: +findings-return capture contract (see note above) {"docket-new-change/SKILL.md", 48, 1552}, // 0582: optional acceptance_criteria body (48/1538 -> 48/1552); 0573: trivial retired; the trivial path is deleted and the brainstorm is told the artifact is always a spec (53/1636 -> 48/1538); 0560: suggest a hold; it rides change.create or change.groom (53/1598 -> 53/1636); 0559: the create request carries deliverable: results-artifact for findings-only work (57/1635 -> 53/1598); 0532: the private-repository writing rule and visibility hand-off (57/1603 -> 57/1635); 0531: the metadata worktree and remote come from the repository.prepare context (57/1596 -> 57/1603); 0502 review: omitted draft-time scalars are described exactly (57/1591 -> 57/1596); 0502: "loop" means /loop only (57/1593 -> 57/1591); 0502: one metadata layout — the docket branch and the .docket/ worktree (57/1590 -> 57/1593); 0502: terminal-publication narration and the repository auto_groom default are deleted (57/1609 -> 57/1590); 0502: invoke superpowers:brainstorming by name (57/1636 -> 57/1609); 0502: the dummy-mode pointer is deleted (59/1674 -> 57/1636); 0445: +pointer to the docket-groom-next revise path after landing (word ceiling 1700 -> 1706); 0382: draft-time scalars moved into change.create (ceiling 1706 -> 1675) {"docket-status/SKILL.md", 125, 2956}, // 0575: reclaim and the claim lease are retired, the intentional-skip example names snapshot-retained and snapshot-no-work (126/2990 -> 125/2956); 0573: trivial retired (126/2993 -> 126/2990); 0560: a held change shows on hold (126/2983 -> 126/2993); 0539: derived-view drift is named by family and each finding's own remedy is relayed instead of a code list (126/2923 -> 126/2983); 0531: the metadata worktree and remote come from the repository.prepare context (126/2921 -> 126/2923); 0530: artifact-missing names where a plan or results file may live — the docket branch, or the integration branch for a record closed before the move (126/2904 -> 126/2921); 0529 review: full-scope cleanup retries also repoint stale merged-PR description backlinks; repair --pr-backlinks previews them (126/2880 -> 126/2904); 0502: one metadata layout — the docket branch and the .docket/ worktree (126/2876 -> 126/2880); 0502: findings named as the binary emits them (126/2852 -> 126/2876); 0502: deferred learnings and publication narration is deleted (127/2956 -> 126/2852); 0502: the dummy-mode pointer is deleted (129/2985 -> 127/2956); 0388: +sync-integration prose (see note above) - {"docket-update-ticket/SKILL.md", 101, 1567}, // 0586: the private refusal becomes a blocking route to references/private.md; the convention paragraph names the docket-export call; the last table column covers attachments (98/1521 -> 101/1567); 0585 review: reads pinned to metadata_commit from the metadata worktree, status named as the ticket-only read, and an empty destination_branch names the parent change (98/1465 -> 98/1521); 0585 review: the lead example names a mention placeholder, never a typed @-mention (98/1451 -> 98/1465); 0585 review: a killed change reports the killed reason (98/1431 -> 98/1451); 0585: new — the inline ticket-update skill - {"docket-update-ticket/references/private.md", 12, 664}, // 0586 review: uploads happen at the post step after mentions (12/629 -> 12/664); 0586: new — private delivery + {"docket-update-ticket/SKILL.md", 101, 1579}, // 0586 review: a private repository keeps the single stop on a rewrite (101/1567 -> 101/1579); 0586: the private refusal becomes a blocking route to references/private.md; the convention paragraph names the docket-export call; the last table column covers attachments (98/1521 -> 101/1567); 0585 review: reads pinned to metadata_commit from the metadata worktree, status named as the ticket-only read, and an empty destination_branch names the parent change (98/1465 -> 98/1521); 0585 review: the lead example names a mention placeholder, never a typed @-mention (98/1451 -> 98/1465); 0585 review: a killed change reports the killed reason (98/1431 -> 98/1451); 0585: new — the inline ticket-update skill + {"docket-update-ticket/references/private.md", 12, 665}, // 0586 review: the comment rule bans docket ADR numbers only (12/664 -> 12/665); 0586 review: uploads happen at the post step after mentions (12/629 -> 12/664); 0586: new — private delivery {"docket-update-ticket/references/shared.md", 9, 184}, // 0585: new — shared delivery } diff --git a/internal/repoguard/prose_contracts_test.go b/internal/repoguard/prose_contracts_test.go index e1f7d8c6b..a3b16ce0f 100644 --- a/internal/repoguard/prose_contracts_test.go +++ b/internal/repoguard/prose_contracts_test.go @@ -1674,6 +1674,7 @@ var alignmentContracts = []proseContract{ "This skill makes no docket metadata write.", "in a private repository it also invokes `docket-export`, which writes each exported file to a temp directory and may read `leak_check.match_word` through `diagnostic.config`", "The last column names what goes with the update: linked in a shared repository, attached in a private one.", + "Do not show a draft and wait: the person asked for the update (in a private repository, `references/private.md`'s single stop on a rewrite still applies).", }, absent: []string{"This skill makes no docket write."}}, {sentinel: "change_0586_update_ticket_private", file: "skills/docket-update-ticket/references/private.md", diff --git a/skills/docket-update-ticket/SKILL.md b/skills/docket-update-ticket/SKILL.md index 71188aea3..e2a65e988 100644 --- a/skills/docket-update-ticket/SKILL.md +++ b/skills/docket-update-ticket/SKILL.md @@ -97,5 +97,5 @@ A mention makes the ticket system notify a person. Mention only people the perso ## 6. Post and report - **Find the connector** for `ticket.provider`. Never conclude an operation is missing because it is not in your tool list: some connectors expose operations only through a discovery tool (the Atlassian connector's `discover`), so look there first. -- **Post** the comment to `ticket.id`, making connector calls one at a time. Do not show a draft and wait: the person asked for the update. When they ask to see it first, show it and post on their go. +- **Post** the comment to `ticket.id`, making connector calls one at a time. Do not show a draft and wait: the person asked for the update (in a private repository, `references/private.md`'s single stop on a rewrite still applies). When they ask to see it first, show it and post on their go. - **Report.** Report the update as posted only with the connector's confirmation, naming the ticket and anyone mentioned. For a missing connector, a failed post, or an uncertain outcome, say in one plain line what was not posted and why; an uncertain outcome is reported as uncertain, and the person decides whether to ask again. Never run a retry loop. A duplicate comment is deleted by hand. diff --git a/skills/docket-update-ticket/references/private.md b/skills/docket-update-ticket/references/private.md index 401e0d99d..14a92bfc5 100644 --- a/skills/docket-update-ticket/references/private.md +++ b/skills/docket-update-ticket/references/private.md @@ -4,7 +4,7 @@ Loaded from `SKILL.md` when `visibility` is `private`. The rules in `SKILL.md` a - **Which files.** The ones the update's row in `SKILL.md` names, attached instead of linked: the spec, the results file, or the artifacts a revision, blocker, or kill discusses. The PR link stays a link: it is `facts.pr_url`, as in shared delivery. A PR-opened update attaches the spec even when an earlier update already attached it. An artifact the update names but `artifacts` does not return is left out, and the comment does not mention it. - **Export each file.** For each one, invoke the `docket-export` skill as a **file request** — its rules are its own; do not restate or re-run them — **DIRECTED to:** export ` ` (`spec` or `results`) with `--output-path` set to a fresh directory from `mktemp -d "${TMPDIR:-/tmp}/docket-update-ticket.XXXXXX"`, return the exported path and the before → after list, and post nothing. You do the uploading and posting. A failed export posts nothing: no attachment and no comment; report the failed export. A word-check hit inside the export stops the way `docket-export` stops: show the person the path and the lines, and post nothing until they decide. -- **Write the comment clean.** Write it under the private-repository writing rule: no change ids or change references (`#612`), no ADR numbers, no backlog or board references, and no "docket" or "dckt". Name each attachment, labeled like a link: `Spec: attached `, `Results: attached `. +- **Write the comment clean.** Write it under the private-repository writing rule: no change ids or change references (`#612`), no docket ADR numbers, no backlog or board references, and no "docket" or "dckt". Name each attachment, labeled like a link: `Spec: attached `, `Results: attached `. - **Check your own words.** Before posting, search the comment and every attachment's file name for "docket" and "dckt" as whole words, case-insensitive (the bare word "docket" is exempt when `leak_check.match_word` is `false`, read as `docket-export` reads it). On a hit, fix your own text quietly: reword the comment, or rename the exported file in its temp directory. Your own words get no before → after. - **When to ask.** If any export rewrote something, stop once: show the before → after list for each attachment and the names of the files to be attached, and post on the person's go. If nothing was rewritten, post straight away; when the person asks to see the update first, show it and post on their go. - **Attachments first, comment last.** Upload nothing before the post step (`SKILL.md` section 6): mentions are settled and any go the person gives comes first, so a stop at a mention question leaves nothing on the ticket. At that step, upload each attachment to `ticket.id`, one connector call at a time, then post the comment. Never assume a one-call upload: some connectors attach in two steps. The Atlassian connector's `uploadAttachmentToJiraIssue` first returns an upload command to run from the shell, then attaches the file id that command returns; it may be reachable only through the connector's discovery tool (`discover`). If you cannot run that step, the upload has failed. Never print a credential: when the upload command carries a token, run it; never echo it into the report.