codeassembly-guidance 0.0.0 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (219) hide show
  1. package/.meta/changelog.json +1320 -0
  2. package/CHANGELOG.md +315 -0
  3. package/LICENSE +7 -0
  4. package/README.md +195 -1
  5. package/bin/codeassembly-validate-preferences.js +18 -0
  6. package/content/_partials/README.md +192 -0
  7. package/content/_partials/code-descriptions.md +4 -0
  8. package/content/_partials/code-style.md +7 -0
  9. package/content/_partials/comment-discipline.md +89 -0
  10. package/content/_partials/concision.md +3 -0
  11. package/content/_partials/diff-audit-checklist.md +9 -0
  12. package/content/_partials/file-access.md +4 -0
  13. package/content/_partials/live-repo-writes.md +13 -0
  14. package/content/_partials/plain-speech-calibration.md +70 -0
  15. package/content/_partials/plain-speech.md +13 -0
  16. package/content/_partials/prose-line-breaks.md +3 -0
  17. package/content/_partials/record-marker.md +1 -0
  18. package/content/_partials/reduced-object-relative.md +28 -0
  19. package/content/_partials/shell-commands.md +3 -0
  20. package/content/_partials/target-file-set-resolution.md +22 -0
  21. package/content/_partials/technical-recommendations.md +6 -0
  22. package/content/_partials/test-structure-audit-checklist.md +7 -0
  23. package/content/_partials/ticket-assessment-baseline.md +12 -0
  24. package/content/_partials/ticket-assessment.md +202 -0
  25. package/content/_partials/work-type-choice.md +13 -0
  26. package/content/codeassembly-content.yaml +59 -0
  27. package/content/collections/all.md +11 -0
  28. package/content/collections/atlassian.md +17 -0
  29. package/content/collections/recommended.md +41 -0
  30. package/content/collections/triage.md +13 -0
  31. package/content/collections/williamthorsen.md +26 -0
  32. package/content/guidance/README.md +22 -0
  33. package/content/guidance/_harnesses/claude/CLAUDE.md +6 -0
  34. package/content/guidance/_harnesses/rovo/AGENTS.md +5 -0
  35. package/content/guidance/_harnesses/rovo/codeassembly-guidance.md +4 -0
  36. package/content/guidance/rulebooks/accessibility-conventions.md +38 -0
  37. package/content/guidance/rulebooks/cli-conventions.md +192 -0
  38. package/content/guidance/rulebooks/codeassembly-content-specification.md +184 -0
  39. package/content/guidance/rulebooks/command-output-conventions.md +14 -0
  40. package/content/guidance/rulebooks/commit-conventions.md +72 -0
  41. package/content/guidance/rulebooks/generated-content-policy.md +10 -0
  42. package/content/guidance/rulebooks/live-worktree-policy.md +19 -0
  43. package/content/guidance/rulebooks/readme-conventions.md +74 -0
  44. package/content/guidance/rulebooks/shared-data-conventions.md +14 -0
  45. package/content/guidance/rulebooks/shell-conventions.md +273 -0
  46. package/content/guidance/rulebooks/ui-copy-conventions.md +34 -0
  47. package/content/guidance/rulebooks/williamthorsen-code-layout-preferences.md +102 -0
  48. package/content/guidance/rulebooks/williamthorsen-collaboration-preferences.md +60 -0
  49. package/content/guidance/rulebooks/williamthorsen-comment-preferences.md +30 -0
  50. package/content/guidance/rulebooks/williamthorsen-subagent-model-preferences.md +15 -0
  51. package/content/guidance/rulebooks/williamthorsen-ticketing-preferences.md +22 -0
  52. package/content/guidance/rulebooks/williamthorsen-tooling-preferences.md +36 -0
  53. package/content/guidance/rulebooks/williamthorsen-typescript-preferences.md +90 -0
  54. package/content/guidance/rulebooks/williamthorsen-workflow-preferences.md +58 -0
  55. package/content/guidance/rulebooks/williamthorsen-writing-preferences.md +80 -0
  56. package/content/guidance/shared/AGENTS.md +51 -0
  57. package/content/scripts/README.md +44 -0
  58. package/content/scripts/check-branch-currency.mjs +11 -0
  59. package/content/scripts/check-prose.mjs +171 -0
  60. package/content/scripts/describe-change.mjs +165 -0
  61. package/content/scripts/get-ticket-id.sh +131 -0
  62. package/content/scripts/manage-jira-ticket.mjs +214 -0
  63. package/content/scripts/resolve-frontmatter.sh +540 -0
  64. package/content/scripts/resolve-review-run.mjs +12 -0
  65. package/content/scripts/select-lede-exemplars.mjs +208 -0
  66. package/content/scripts/validate-preferences.mjs +146 -0
  67. package/content/skills/_data/action-items.md +83 -0
  68. package/content/skills/_data/artifact-conventions.md +1001 -0
  69. package/content/skills/_data/bitbucket-pr-access.md +89 -0
  70. package/content/skills/_data/branch-currency.md +36 -0
  71. package/content/skills/_data/branch-format.md +34 -0
  72. package/content/skills/_data/change-record.md +163 -0
  73. package/content/skills/_data/complexity-classification.md +58 -0
  74. package/content/skills/_data/concision.md +23 -0
  75. package/content/skills/_data/deployed-file-provenance.md +46 -0
  76. package/content/skills/_data/design-priorities.md +76 -0
  77. package/content/skills/_data/gh-body-file.md +30 -0
  78. package/content/skills/_data/git-commands.md +39 -0
  79. package/content/skills/_data/naming-conventions.md +50 -0
  80. package/content/skills/_data/pr-resolution.md +25 -0
  81. package/content/skills/_data/pr-source-resolution.md +36 -0
  82. package/content/skills/_data/project-stage.md +32 -0
  83. package/content/skills/_data/recommendation-gradient.md +92 -0
  84. package/content/skills/_data/scope-and-deferral.md +83 -0
  85. package/content/skills/_data/spike-conventions.md +89 -0
  86. package/content/skills/_data/ticket-evaluation.md +13 -0
  87. package/content/skills/_data/ticket-id-extraction.md +43 -0
  88. package/content/skills/_data/ticket-source-resolution.md +180 -0
  89. package/content/skills/_data/title-templates.md +632 -0
  90. package/content/skills/_data/title-voice.md +17 -0
  91. package/content/skills/_data/work-types.json +168 -0
  92. package/content/skills/_partials/acceptance-criteria-scaffold.md +15 -0
  93. package/content/skills/_partials/action-items.md +22 -0
  94. package/content/skills/_partials/bitbucket-delete-both-refusal.md +3 -0
  95. package/content/skills/_partials/commit-title-rendering.md +14 -0
  96. package/content/skills/_partials/gh-body-file.md +22 -0
  97. package/content/skills/_partials/jira-task-list-flattening.md +1 -0
  98. package/content/skills/_partials/nested-list-indent.md +9 -0
  99. package/content/skills/_partials/next-steps-after-plan.md +99 -0
  100. package/content/skills/_partials/next-steps-after-review.md +350 -0
  101. package/content/skills/_partials/option-format.md +85 -0
  102. package/content/skills/_partials/plan-template.md +97 -0
  103. package/content/skills/_partials/split-launch-prompts.md +5 -0
  104. package/content/skills/_partials/split-ticket-compose.md +5 -0
  105. package/content/skills/_partials/split-ticket-create.md +3 -0
  106. package/content/skills/_partials/ticket-and-plan-completeness.md +33 -0
  107. package/content/skills/_partials/ticket-concision.md +18 -0
  108. package/content/skills/_partials/ticket-criteria-conventions.md +7 -0
  109. package/content/skills/_partials/ticket-placement.md +14 -0
  110. package/content/skills/_partials/ticket-skeleton-tiers.md +6 -0
  111. package/content/skills/_partials/ticket-skeleton.md +13 -0
  112. package/content/skills/add-change-record/SKILL.md +136 -0
  113. package/content/skills/add-test-ids/SKILL.md +51 -0
  114. package/content/skills/align-ticket-with-implementation/SKILL.md +115 -0
  115. package/content/skills/anti-patterns/SKILL.md +57 -0
  116. package/content/skills/assess-ticket/SKILL.md +46 -0
  117. package/content/skills/assess-ticket/next-steps-after-assessment.md +98 -0
  118. package/content/skills/assess-usability/SKILL.md +96 -0
  119. package/content/skills/brainstorming/SKILL.md +107 -0
  120. package/content/skills/capture-event/SKILL.md +108 -0
  121. package/content/skills/capture-event/capture-event.mjs +216 -0
  122. package/content/skills/capture-feedback/SKILL.md +71 -0
  123. package/content/skills/capture-lede-decision/SKILL.md +163 -0
  124. package/content/skills/capture-lede-decision/capture-lede-decision.mjs +231 -0
  125. package/content/skills/classify-complexity/SKILL.md +92 -0
  126. package/content/skills/collaborate/SKILL.md +86 -0
  127. package/content/skills/condense-branch/SKILL.md +83 -0
  128. package/content/skills/create-bitbucket-pr/SKILL.md +87 -0
  129. package/content/skills/create-commit/SKILL.md +65 -0
  130. package/content/skills/create-devlog/SKILL.md +108 -0
  131. package/content/skills/create-gh-pr/SKILL.md +121 -0
  132. package/content/skills/create-pr/SKILL.md +150 -0
  133. package/content/skills/create-ticket/SKILL.md +395 -0
  134. package/content/skills/create-ticket/resolve-ticket-target.mjs +143 -0
  135. package/content/skills/derive-session-context/derive-session-context.mjs +149 -0
  136. package/content/skills/design-and-plan/SKILL.md +197 -0
  137. package/content/skills/development-workflows/SKILL.md +41 -0
  138. package/content/skills/get-ticket-id/SKILL.md +67 -0
  139. package/content/skills/groom-backlog/SKILL.md +247 -0
  140. package/content/skills/groom-backlog/groom-backlog.mjs +108 -0
  141. package/content/skills/implement-plan/SKILL.md +168 -0
  142. package/content/skills/index-prototypes/SKILL.md +200 -0
  143. package/content/skills/index-prototypes/index-prototypes.mjs +388 -0
  144. package/content/skills/kb-add/SKILL.md +157 -0
  145. package/content/skills/kb-add/kb-add.mjs +216 -0
  146. package/content/skills/kb-curate/SKILL.md +119 -0
  147. package/content/skills/kb-curate/kb-curate.mjs +213 -0
  148. package/content/skills/kb-edit/SKILL.md +128 -0
  149. package/content/skills/kb-edit/kb-edit.mjs +219 -0
  150. package/content/skills/kb-retrieve/SKILL.md +100 -0
  151. package/content/skills/kb-retrieve/kb-retrieve.mjs +207 -0
  152. package/content/skills/kb-retrieve-events/SKILL.md +98 -0
  153. package/content/skills/kb-retrieve-events/kb-retrieve-events.mjs +207 -0
  154. package/content/skills/kb-update-events/SKILL.md +77 -0
  155. package/content/skills/kb-update-events/kb-update-events.mjs +215 -0
  156. package/content/skills/merge-bb-pr/SKILL.md +136 -0
  157. package/content/skills/merge-gh-pr/SKILL.md +167 -0
  158. package/content/skills/merge-gh-pr/merge-gh-pr.mjs +10 -0
  159. package/content/skills/merge-pr/SKILL.md +368 -0
  160. package/content/skills/migrate-feedback-memories/SKILL.md +137 -0
  161. package/content/skills/migrate-feedback-memories/feedback-memories.mjs +161 -0
  162. package/content/skills/people-report/SKILL.md +208 -0
  163. package/content/skills/plan/SKILL.md +87 -0
  164. package/content/skills/prepare-prototype-brief/SKILL.md +178 -0
  165. package/content/skills/pull-from-backlog/SKILL.md +83 -0
  166. package/content/skills/pull-from-backlog/pull-from-backlog.mjs +209 -0
  167. package/content/skills/refine-plan/SKILL.md +263 -0
  168. package/content/skills/refine-prototype/SKILL.md +113 -0
  169. package/content/skills/respond-to-review/SKILL.md +292 -0
  170. package/content/skills/review-bb-pr/SKILL.md +161 -0
  171. package/content/skills/review-branch/SKILL.md +303 -0
  172. package/content/skills/review-criteria/SKILL.md +141 -0
  173. package/content/skills/review-gh-pr/SKILL.md +155 -0
  174. package/content/skills/review-gh-pr/select-pr-ticket.mjs +8 -0
  175. package/content/skills/review-permissions/SKILL.md +39 -0
  176. package/content/skills/review-pr/SKILL.md +123 -0
  177. package/content/skills/revise-comments/SKILL.md +148 -0
  178. package/content/skills/revise-prose/SKILL.md +197 -0
  179. package/content/skills/revise-prose/revise-prose.mjs +229 -0
  180. package/content/skills/save-artifact/SKILL.md +71 -0
  181. package/content/skills/save-plan/SKILL.md +55 -0
  182. package/content/skills/software-engineering/SKILL.md +74 -0
  183. package/content/skills/streamline-guidance/SKILL.md +174 -0
  184. package/content/skills/streamline-guidance/streamline-guidance.mjs +211 -0
  185. package/content/skills/summarize-change/SKILL.md +317 -0
  186. package/content/skills/summarize-chat/SKILL.md +100 -0
  187. package/content/skills/systematic-debugging/SKILL.md +308 -0
  188. package/content/skills/systematic-debugging/condition-based-waiting-example.ts +160 -0
  189. package/content/skills/systematic-debugging/condition-based-waiting.md +122 -0
  190. package/content/skills/systematic-debugging/defense-in-depth.md +130 -0
  191. package/content/skills/systematic-debugging/find-polluter.sh +68 -0
  192. package/content/skills/systematic-debugging/root-cause-tracing.md +185 -0
  193. package/content/skills/systematic-debugging/test-academic.md +16 -0
  194. package/content/skills/systematic-debugging/test-pressure-1.md +67 -0
  195. package/content/skills/systematic-debugging/test-pressure-2.md +77 -0
  196. package/content/skills/systematic-debugging/test-pressure-3.md +77 -0
  197. package/content/skills/testing-conventions/SKILL.md +235 -0
  198. package/content/skills/triage-spike-findings/SKILL.md +113 -0
  199. package/content/skills/triage-spike-findings/triage-spike-findings.mjs +71 -0
  200. package/content/skills/typescript-testing-conventions/SKILL.md +178 -0
  201. package/content/skills/update-jira-ticket/SKILL.md +257 -0
  202. package/content/skills/update-jira-ticket/update-jira-ticket.mjs +9 -0
  203. package/content/skills/update-project-guidance/SKILL.md +300 -0
  204. package/content/skills/upgrade-dependencies/SKILL.md +139 -0
  205. package/content/skills/wrap-up/SKILL.md +431 -0
  206. package/content/subagents/_data/claude.yaml +25 -0
  207. package/content/subagents/_data/rovo.yaml +41 -0
  208. package/content/subagents/canary.md +12 -0
  209. package/content/subagents/disposition-challenger.md +78 -0
  210. package/content/subagents/entry-drafter.md +191 -0
  211. package/content/subagents/handoff-reviewer.md +75 -0
  212. package/content/subagents/plan-reviewer.md +184 -0
  213. package/content/subagents/plan-reviser.md +88 -0
  214. package/content/subagents/prose-reviser.md +132 -0
  215. package/content/subagents/ticket-assessor.md +142 -0
  216. package/content/subagents/usability-assessor.md +157 -0
  217. package/package.json +74 -2
  218. package/schemas/preferences.v1.json +321 -0
  219. package/schemas/work-types.v1.json +142 -0
@@ -0,0 +1,180 @@
1
+ # Ticket source resolution
2
+
3
+ Resolve a ticket source argument into ticket content and metadata. Skills that accept a ticket reference should use this shared resolution logic.
4
+
5
+ ## Resolution table
6
+
7
+ | Input form | Resolution |
8
+ | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
9
+ | URL to a known platform (GitHub, Jira, etc.) | Use the platform CLI or a connected read tool if available; otherwise, fetch the URL content |
10
+ | Other URL | Fetch the URL content |
11
+ | Shorthand reference (`#99`, `issue 99`, `GitHub issue #99`) | Resolve platform (see below), then fetch per [platform-specific fetch](#platform-specific-fetch) |
12
+ | File path | Read the file |
13
+ | Plain text | Use as-is |
14
+ | _(no source provided)_ | Auto-resolve from environment (see [auto-resolve](#auto-resolve)) |
15
+
16
+ **Persist the resolved URL.** After resolving by any form above (an explicitly supplied URL included, not only the auto-resolve path), store the resolved `ticket_url` in the branch manifest so that later sessions reuse it without re-resolving or re-pasting. On the default branch nothing is stored, and the deriver enforces that. See [Stored ticket URL](#stored-ticket-url).
17
+
18
+ ## Auto-resolve
19
+
20
+ When the invocation does not provide a ticket source, attempt to derive the ticket from the current environment. This covers the common case in which the branch name encodes the ticket identity (e.g., branch `357` for GitHub issue #357, or branch `MAC-42/feat/foo` for Jira ticket MAC-42).
21
+
22
+ ### Steps
23
+
24
+ 1. **Get session context** by invoking the bundled session-context deriver (`node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs`) and reading the manifest JSON emitted on stdout. This JSON contains `ticket_id`, the persisted `ticket_url`, and `ticket_base_url` (the org-stable base mirrored from the `ticket.base_url` preference; see [Stored ticket URL](#stored-ticket-url)).
25
+
26
+ 2. **Prefer the stored URL.** If `ticket_url` is a non-null string, fetch the ticket directly from that URL; skip the platform/identifier reconstruction below. If the stored URL does not yield the expected ticket, invalidate it per [Stored ticket URL](#stored-ticket-url) and continue with reconstruction.
27
+
28
+ 3. **Otherwise reconstruct from `ticket_id`.** If `ticket_id` is `null`, auto-resolve fails; ask the user for a ticket source.
29
+
30
+ 4. **Determine the platform and construct the fetch identifier:**
31
+
32
+ a. **If `ticket_id` is purely numeric** (e.g., `357`): The ID is a platform issue number. Determine the platform using the [platform resolution cascade](#platform-resolution-cascade). For GitHub, fetch issue `357`.
33
+
34
+ b. **If `ticket_id` contains a prefix** (e.g., `MAC-42`): The ID is a Jira-style key. The platform is Jira (or whichever platform hosts that project). The deriver includes a configured `ticket_ref_prefix` other than `#` in `ticket_id`, so a bare-number branch under `MAC-` arrives here as `MAC-357`.
35
+
36
+ c. If the platform still cannot be determined, ask the user.
37
+
38
+ d. **Construct the URL from a base when one is available.** If a base URL is known (`ticket_base_url` from the manifest, or `ticket.base_url` from `.agents/preferences.yaml`), the ticket URL is the base joined to `ticket_id` with a single `/` (e.g. `https://org.atlassian.net/browse/` + `MAC-42` → `https://org.atlassian.net/browse/MAC-42`). This is the reconstruction path for a Jira-style key: It yields the URL consumed by a URL-taking Jira read tool, and the URL to present and persist when the content cannot be fetched.
39
+
40
+ 5. **Fetch the ticket** per [platform-specific fetch](#platform-specific-fetch).
41
+
42
+ 6. **Persist the resolved URL.** Once a ticket URL is in hand (whether reconstructed here, supplied by the user, or fetched), store it for future sessions per [Stored ticket URL](#stored-ticket-url).
43
+
44
+ ### When auto-resolve fails
45
+
46
+ If the ticket ID is `null` or the platform cannot be determined, do not guess. Ask the user for an explicit ticket source. The cost of asking is low; the cost of fetching the wrong ticket is high.
47
+
48
+ A caller may substitute its own fallback for this "ask the user" terminal step when it has a sound default source. For example, `review-branch` falls back to the most recent local `*_ticket.md` snapshot instead of prompting, so an unattended review can still proceed against a reasonable contract.
49
+
50
+ ## Platform resolution cascade
51
+
52
+ Determine which platform a ticket belongs to:
53
+
54
+ 1. Check `.agents/preferences.yaml` → `integrations` (if exactly one enabled, use it; if multiple, ask)
55
+ 2. Check `git remote get-url origin` (e.g., `github.com` → GitHub)
56
+ 3. Ask the user
57
+
58
+ This cascade is used by both [shorthand reference resolution](#shorthand-reference-resolution) and [auto-resolve](#auto-resolve).
59
+
60
+ ## Shorthand reference resolution
61
+
62
+ Determine which platform `#99` refers to using the [platform resolution cascade](#platform-resolution-cascade).
63
+
64
+ ## Platform-specific fetch
65
+
66
+ ### GitHub
67
+
68
+ ```
69
+ gh issue view --json number,title,body,labels,updatedAt {number}
70
+ ```
71
+
72
+ Skills may request a subset of these fields. The `updatedAt` field is needed by skills that perform temporal analysis (e.g., staleness checks) and may be omitted by skills that only need the ticket content.
73
+
74
+ ### Jira
75
+
76
+ Access Jira Cloud through Atlassian's `acli`, falling back to a connected Jira read tool. Detect the CLI with `command -v acli`, and treat a non-zero exit from the fetch itself as unavailable: An `acli` that is installed but unauthenticated exits non-zero with an error on stderr and nothing on stdout, and that error does not distinguish an authentication failure from a missing issue, so fall through on the exit status rather than on the message.
77
+
78
+ **Preferred: `acli`.** `acli` reads from whichever site it is signed in to, and a ticket on another site fails with the same error as a missing one. Before the first `acli` call, compare its active site with the ticket's host, taken from the ticket URL, or from `ticket_base_url` when the ticket URL is not known:
79
+
80
+ ```
81
+ node {harness_home_dir}/scripts/manage-jira-ticket.mjs check-site --target {ticket URL or ticket_base_url}
82
+ ```
83
+
84
+ The helper prints `{"activeSite": ..., "targetSite": ..., "match": ...}` and exits non-zero unless the two match. On a mismatch, read the ticket through another client below; a non-zero exit without JSON means that `acli` is unavailable. When neither URL is known, skip the check and read through `acli` as below.
85
+
86
+ Read the ticket body with the default view, which renders the description as text.
87
+
88
+ ```
89
+ acli jira workitem view {key}
90
+ ```
91
+
92
+ When the source is a Jira URL rather than a key, the key is its `PROJECT-NUMBER` segment, which is the final segment of a `/browse/` URL.
93
+
94
+ When a skill needs structured metadata, such as the `updated` timestamp for a staleness check, add `--json --fields '*navigable,-description'`. The `--json` flag returns the raw REST v3 response, in which the description is Atlassian Document Format rather than Markdown, so exclude it there and take the body from the default view. First-time setup is `acli jira auth login --web`, a browser flow that does not mint an API token.
95
+
96
+ **Fallback: A connected Jira read tool.** Because tool names vary by server and by machine alias, identify the tool by its parameters:
97
+
98
+ - **Takes an issue URL**: Pass the ticket URL. Prefer this shape when both are connected, since it does not need site resolution.
99
+ - **Takes an issue key and a cloud ID**: Resolve the cloud ID first, from the same server's tool listing accessible Atlassian sites. It is the `id` of the site whose URL matches the ticket URL's host, or of the sole site listed when the ticket URL is not known. If neither settles it, ask the user which site hosts the ticket. Resolve it once and reuse it for the rest of the session.
100
+
101
+ **A client that the machine adds.** {skill?:update-jira-ticket} lists any Jira client that this machine adds to the cascade, with the sites that it can access and its rank. Read through it as its entry states.
102
+
103
+ **Last resort.** When no client can read the ticket and `check-site` reported a mismatch, report the wrong site rather than a missing ticket: Repeat the helper's stderr line, which names both sites and the `acli jira auth switch` command. Never run that command, because the active site is shared by every session on the machine. When no client is available, present the Jira key and ask the user for the ticket content. When `ticket.base_url` is configured, the ticket URL is reconstructed from the base and `ticket_id` (per [auto-resolve](#auto-resolve) step 4d), so it does not have to be supplied or re-pasted. A caller with a sound default source may substitute it for that prompt, as [When auto-resolve fails](#when-auto-resolve-fails) allows.
104
+
105
+ The stored URL applies throughout: A Jira ticket URL resolved once is reused on later sessions, and it is invalidated like any other stored URL when it does not yield the expected ticket (see [Stored ticket URL](#stored-ticket-url)). A site mismatch does not invalidate the stored URL, because it does not show that the ticket is missing.
106
+
107
+ ## Open blockers
108
+
109
+ A ticket's open blockers are the tickets recorded natively as blocking it that are not yet done. Read them each time a skill resolves the ticket, even when the ticket is already in context, because a blocker can close or appear during a session.
110
+
111
+ **GitHub.** A blocker is open while its `state` is `OPEN`, so one closed as not planned counts as resolved. A blocker can be in another repository:
112
+
113
+ ```
114
+ gh issue view {number} --json blockedBy --jq '.blockedBy.nodes[] | select(.state == "OPEN") | [.url, .title] | @tsv'
115
+ ```
116
+
117
+ Name a blocker `#N` when its URL has the same `owner/repo` as the ticket's, and `owner/repo#N` otherwise.
118
+
119
+ **Jira.** Read the links through the Jira clients that [platform-specific fetch](#platform-specific-fetch) ranks, after the same site check: `acli jira workitem view {key} --json --fields issuelinks`, or a connected read tool asked for the `issuelinks` field. A blocker is a link whose `type.name` is `Blocks`, or whose `type.inward` reads `is blocked by`, and that has an `inwardIssue`. It is open while `inwardIssue.fields.status.statusCategory.key` is not `done`. Name it by its key and `fields.summary`.
120
+
121
+ **A file.** A ticket artifact copies a remote ticket, so a ticket that resolved from a file is checked against the remote ticket that its frontmatter `ticket_ref` names, resolved per [shorthand reference resolution](#shorthand-reference-resolution). A file without a `ticket_ref` is not checked.
122
+
123
+ **Other sources.** A ticket that resolved from plain text or from another platform is not checked, and the skill says nothing about blockers. Because a project hosted on Bitbucket keeps its tickets in Jira, its tickets are checked as Jira tickets.
124
+
125
+ **Report.** When the ticket has open blockers, report them in one line, each by reference and title: `⚠️ {ticket_ref} is blocked by {blocker_ref} ({title}), …`. When it has none, report nothing. When the read fails or no client can make it, report in one line that the blocker check did not run, and why; never report the ticket as unblocked. The calling skill states what follows the report.
126
+
127
+ ## Platform-specific write
128
+
129
+ Write a revision back to the ticket of record, which the caller names; when the caller does not name a ticket, it is the ticket from which the revision's source came. The platform is `scm` from the session-context manifest, falling back to the [platform resolution cascade](#platform-resolution-cascade) when the manifest does not set `scm`. Under that default, a ticket that resolved from a file is written back to that file, and one that resolved from plain text does not have a write target.
130
+
131
+ **A partial revision is composed from the platform's current body.** When a skill revises one section of a ticket, it fetches the current body per [platform-specific fetch](#platform-specific-fetch) and applies the revision to that, so every section that it does not revise is carried over from the platform rather than from a local copy. A whole-ticket body approved by the user replaces the body outright.
132
+
133
+ **Nothing is reported as updated until the write succeeds.** A write that fails is reported as a failure, naming the manual step that remains.
134
+
135
+ ### GitHub
136
+
137
+ Write the body to a scratch file per [gh body file](#gh-body-file), naming it `gh-body-issue{number}-{timestamp}.md`, then:
138
+
139
+ ```bash
140
+ body_path="{absolute path from the write step}"
141
+ [ -s "$body_path" ] || { echo "Body file missing or empty: $body_path" >&2; exit 1; }
142
+ gh issue edit {number} --body-file "$body_path"
143
+ ```
144
+
145
+ ### Jira
146
+
147
+ Update through {skill?:update-jira-ticket}, which states the tool-shape branch and bundles the pre-flight checker that its HTML surface needs.
148
+
149
+ <!-- include: ../_partials/jira-task-list-flattening.md / -->
150
+
151
+ `acli`'s default view is text rather than Markdown and the write converts the whole description, so a partial revision re-renders the sections that it leaves alone; report it as a re-rendering of the whole description rather than an edit confined to the revised section.
152
+
153
+ ### Other platforms
154
+
155
+ An automated write is not available for these platforms. Report that the ticket was not updated and present the composed body for the user to apply, rather than passing over the write in silence.
156
+
157
+ ## Stored ticket URL
158
+
159
+ The branch manifest (`.agents/{branch}.branch-manifest.json`) persists a resolved `ticket_url` so that it is reused across sessions instead of being reconstructed or re-pasted each time. The manifest is the single store; a skill reads the stored URL from the manifest JSON emitted by the deriver, without an extra call, and makes every write through the deriver's mutation flags, never by hand-editing the JSON.
160
+
161
+ The manifest also includes `ticket_base_url`, mirroring the `ticket.base_url` preference. When a base and a `ticket_id` are both known, the deriver seeds `ticket_url` by joining them, so a bare Jira-style reference resolves to a URL without a supplied one. An explicitly stored URL always overrides that constructed default.
162
+
163
+ - **Prefer**: Auto-resolve uses a stored `ticket_url` before reconstructing one from `ticket_id`.
164
+ - **Persist**: After a ticket URL is resolved (reconstructed, supplied by the user, or fetched), store it by running `node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs --set-ticket-url "{url}"`.
165
+ - **Never on the default branch**: That branch is not derived from any ticket, so a URL stored against it is not its association but whichever ticket the last session happened to resolve, and a later session auto-resolving from it proceeds against an arbitrary one. The deriver enforces this: It refuses the write, reports on stderr, exits 0, and emits a manifest whose `ticket_url` is null. It clears a value already stored there for the same reason. A skill that decides the skip itself can report it in its own completion output instead of leaving it to a stderr line; `create-ticket` does. The same rule applies to `pr_url`; see [PR source resolution](pr-source-resolution.md#stored-pr-url).
166
+ - **Invalidate**: When the stored URL does not yield the expected ticket (the resource is not found at that URL, whether stale, wrong, moved, or deleted), clear it with `node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs --clear-ticket-url`, then re-resolve. A cleared URL stays null, even across a preference change, until `--set-ticket-url` stores a new one. This rule is platform-agnostic: It does not exempt any platform. For GitHub, re-resolution re-derives or re-fetches; for Jira, re-resolution re-fetches through `acli` or a connected read tool, and re-prompts the user only when neither is available.
167
+
168
+ ## Resolved metadata
169
+
170
+ After resolution, store the following metadata for use by the calling skill:
171
+
172
+ - **Platform**: Which platform the ticket was resolved from (e.g., GitHub, Jira, file, plain text)
173
+ - **Repository**: The repository identifier (e.g., `owner/repo`), if applicable
174
+ - **Issue number**: The numeric identifier, if applicable
175
+ - **Last-updated date**: The ticket's last-modified timestamp, if available from the platform
176
+ - **Ticket content**: The title, body, labels, and any other retrieved fields
177
+ - **Open blockers**: For a skill that checks them, each open blocker's reference and title, read per [Open blockers](#open-blockers)
178
+ - **Ticket URL**: Persisted across sessions in the branch manifest's `ticket_url` field, written through the deriver's mutation flags; see [Stored ticket URL](#stored-ticket-url)
179
+
180
+ <!-- include: ../_partials/gh-body-file.md / -->