codeassembly-guidance 0.1.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 (137) hide show
  1. package/.meta/changelog.json +757 -0
  2. package/CHANGELOG.md +181 -0
  3. package/README.md +125 -95
  4. package/bin/codeassembly-validate-preferences.js +18 -0
  5. package/content/_partials/README.md +2 -2
  6. package/content/_partials/code-style.md +1 -1
  7. package/content/_partials/comment-discipline.md +1 -1
  8. package/content/_partials/plain-speech-calibration.md +4 -0
  9. package/content/_partials/technical-recommendations.md +1 -0
  10. package/content/codeassembly-content.yaml +11 -1
  11. package/content/collections/all.md +2 -2
  12. package/content/collections/atlassian.md +2 -1
  13. package/content/collections/recommended.md +9 -2
  14. package/content/collections/triage.md +3 -67
  15. package/content/collections/williamthorsen.md +2 -1
  16. package/content/guidance/README.md +1 -1
  17. package/content/guidance/rulebooks/accessibility-conventions.md +23 -5
  18. package/content/guidance/rulebooks/cli-conventions.md +192 -0
  19. package/content/guidance/rulebooks/codeassembly-content-specification.md +32 -9
  20. package/content/guidance/rulebooks/commit-conventions.md +2 -2
  21. package/content/guidance/rulebooks/live-worktree-policy.md +3 -2
  22. package/content/guidance/rulebooks/readme-conventions.md +3 -3
  23. package/content/guidance/rulebooks/shared-data-conventions.md +2 -2
  24. package/content/guidance/rulebooks/shell-conventions.md +17 -23
  25. package/content/guidance/rulebooks/ui-copy-conventions.md +34 -0
  26. package/content/guidance/rulebooks/williamthorsen-collaboration-preferences.md +14 -12
  27. package/content/guidance/rulebooks/williamthorsen-ticketing-preferences.md +3 -3
  28. package/content/guidance/rulebooks/williamthorsen-tooling-preferences.md +6 -6
  29. package/content/guidance/rulebooks/williamthorsen-typescript-preferences.md +1 -1
  30. package/content/guidance/rulebooks/williamthorsen-workflow-preferences.md +7 -7
  31. package/content/guidance/shared/AGENTS.md +8 -0
  32. package/content/scripts/README.md +5 -2
  33. package/content/scripts/check-branch-currency.mjs +11 -0
  34. package/content/scripts/check-prose.mjs +171 -0
  35. package/content/scripts/describe-change.mjs +97 -97
  36. package/content/scripts/manage-jira-ticket.mjs +99 -94
  37. package/content/scripts/resolve-frontmatter.sh +1 -1
  38. package/content/scripts/resolve-review-run.mjs +9 -9
  39. package/content/scripts/select-lede-exemplars.mjs +87 -87
  40. package/content/scripts/validate-preferences.mjs +146 -0
  41. package/content/skills/_data/artifact-conventions.md +46 -14
  42. package/content/skills/_data/branch-currency.md +36 -0
  43. package/content/skills/_data/change-record.md +2 -2
  44. package/content/skills/_data/design-priorities.md +3 -3
  45. package/content/skills/_data/project-stage.md +32 -0
  46. package/content/skills/_data/recommendation-gradient.md +9 -7
  47. package/content/skills/_data/scope-and-deferral.md +1 -1
  48. package/content/skills/_data/spike-conventions.md +1 -1
  49. package/content/skills/_data/ticket-evaluation.md +2 -2
  50. package/content/skills/_data/ticket-source-resolution.md +36 -3
  51. package/content/skills/_data/title-templates.md +19 -11
  52. package/content/skills/_partials/action-items.md +2 -2
  53. package/content/skills/_partials/commit-title-rendering.md +1 -1
  54. package/content/skills/_partials/jira-task-list-flattening.md +1 -0
  55. package/content/skills/_partials/next-steps-after-plan.md +10 -10
  56. package/content/skills/_partials/next-steps-after-review.md +9 -9
  57. package/content/skills/_partials/option-format.md +18 -17
  58. package/content/skills/_partials/plan-template.md +5 -5
  59. package/content/skills/_partials/split-ticket-compose.md +1 -1
  60. package/content/skills/_partials/split-ticket-create.md +1 -1
  61. package/content/skills/_partials/ticket-and-plan-completeness.md +2 -2
  62. package/content/skills/_partials/ticket-criteria-conventions.md +3 -3
  63. package/content/skills/add-change-record/SKILL.md +2 -2
  64. package/content/skills/align-ticket-with-implementation/SKILL.md +2 -2
  65. package/content/skills/anti-patterns/SKILL.md +1 -1
  66. package/content/skills/assess-usability/SKILL.md +96 -0
  67. package/content/skills/capture-event/SKILL.md +2 -2
  68. package/content/skills/capture-event/capture-event.mjs +89 -89
  69. package/content/skills/capture-lede-decision/SKILL.md +4 -4
  70. package/content/skills/capture-lede-decision/capture-lede-decision.mjs +98 -98
  71. package/content/skills/collaborate/SKILL.md +1 -1
  72. package/content/skills/create-gh-pr/SKILL.md +24 -9
  73. package/content/skills/create-pr/SKILL.md +5 -5
  74. package/content/skills/create-ticket/SKILL.md +61 -16
  75. package/content/skills/create-ticket/resolve-ticket-target.mjs +143 -0
  76. package/content/skills/derive-session-context/derive-session-context.mjs +95 -94
  77. package/content/skills/design-and-plan/SKILL.md +13 -10
  78. package/content/skills/groom-backlog/SKILL.md +8 -6
  79. package/content/skills/groom-backlog/groom-backlog.mjs +64 -62
  80. package/content/skills/implement-plan/SKILL.md +25 -21
  81. package/content/skills/index-prototypes/SKILL.md +85 -30
  82. package/content/skills/index-prototypes/index-prototypes.mjs +76 -16
  83. package/content/skills/kb-add/SKILL.md +2 -1
  84. package/content/skills/kb-add/kb-add.mjs +128 -128
  85. package/content/skills/kb-curate/SKILL.md +9 -7
  86. package/content/skills/kb-curate/kb-curate.mjs +103 -103
  87. package/content/skills/kb-edit/SKILL.md +3 -3
  88. package/content/skills/kb-edit/kb-edit.mjs +94 -94
  89. package/content/skills/kb-retrieve/kb-retrieve.mjs +78 -77
  90. package/content/skills/kb-retrieve-events/SKILL.md +1 -1
  91. package/content/skills/kb-retrieve-events/kb-retrieve-events.mjs +78 -77
  92. package/content/skills/kb-update-events/SKILL.md +2 -2
  93. package/content/skills/kb-update-events/kb-update-events.mjs +108 -108
  94. package/content/skills/merge-bb-pr/SKILL.md +1 -1
  95. package/content/skills/merge-gh-pr/merge-gh-pr.mjs +5 -5
  96. package/content/skills/merge-pr/SKILL.md +11 -11
  97. package/content/skills/migrate-feedback-memories/SKILL.md +3 -2
  98. package/content/skills/migrate-feedback-memories/feedback-memories.mjs +76 -76
  99. package/content/skills/plan/SKILL.md +1 -1
  100. package/content/skills/prepare-prototype-brief/SKILL.md +66 -14
  101. package/content/skills/pull-from-backlog/SKILL.md +3 -3
  102. package/content/skills/pull-from-backlog/pull-from-backlog.mjs +83 -82
  103. package/content/skills/refine-plan/SKILL.md +7 -3
  104. package/content/skills/refine-prototype/SKILL.md +113 -0
  105. package/content/skills/respond-to-review/SKILL.md +1 -1
  106. package/content/skills/review-bb-pr/SKILL.md +1 -1
  107. package/content/skills/review-branch/SKILL.md +4 -2
  108. package/content/skills/review-criteria/SKILL.md +36 -3
  109. package/content/skills/review-gh-pr/select-pr-ticket.mjs +6 -6
  110. package/content/skills/revise-comments/SKILL.md +38 -5
  111. package/content/skills/revise-prose/SKILL.md +1 -1
  112. package/content/skills/revise-prose/revise-prose.mjs +119 -119
  113. package/content/skills/save-artifact/SKILL.md +2 -0
  114. package/content/skills/streamline-guidance/SKILL.md +1 -1
  115. package/content/skills/streamline-guidance/streamline-guidance.mjs +86 -86
  116. package/content/skills/summarize-change/SKILL.md +22 -13
  117. package/content/skills/testing-conventions/SKILL.md +74 -7
  118. package/content/skills/triage-spike-findings/SKILL.md +113 -0
  119. package/content/skills/triage-spike-findings/triage-spike-findings.mjs +71 -0
  120. package/content/skills/typescript-testing-conventions/SKILL.md +50 -1
  121. package/content/skills/update-jira-ticket/SKILL.md +20 -8
  122. package/content/skills/update-jira-ticket/update-jira-ticket.mjs +7 -7
  123. package/content/skills/update-project-guidance/SKILL.md +2 -2
  124. package/content/subagents/_data/claude.yaml +6 -0
  125. package/content/subagents/_data/rovo.yaml +12 -2
  126. package/content/subagents/canary.md +2 -1
  127. package/content/subagents/disposition-challenger.md +78 -0
  128. package/content/subagents/entry-drafter.md +14 -10
  129. package/content/subagents/handoff-reviewer.md +2 -2
  130. package/content/subagents/plan-reviewer.md +1 -1
  131. package/content/subagents/prose-reviser.md +4 -2
  132. package/content/subagents/ticket-assessor.md +9 -6
  133. package/content/subagents/usability-assessor.md +157 -0
  134. package/package.json +15 -11
  135. package/schemas/preferences.v1.json +29 -2
  136. package/schemas/work-types.v1.json +1 -1
  137. package/content/skills/testing-conventions/mistakes.md +0 -1
@@ -17,7 +17,7 @@ This skill is invoked by a directive in the harness's global guidance during int
17
17
  - Don't let refactoring grow beyond the task; recommend the scope call, build on it, and raise it at the checkpoint.
18
18
  - Ask for guidance on naming and approach when the choice turns on the developer's preference; when a convention or the merits already settle it, state the decision with its reason and proceed.
19
19
  - Proceed provisionally: Decide what the gate lets you decide, record it, and collect the surviving asks into one review at the checkpoint.
20
- - Do every step yourself, verification included; the `## Handoffs` section of the collaboration preferences states when a step may leave your hands.
20
+ - Do every step yourself, verification included; the `## Handoffs` section of the collaboration preferences states when you may hand a step over.
21
21
  - When instructions have undiscussed implications, and you see flaws or meaningful improvements, raise them before proceeding.
22
22
 
23
23
  ## Concision by default
@@ -42,23 +42,36 @@ gh pr create \
42
42
  --body-file "$body_path" \
43
43
  --base "{base_branch}" \
44
44
  --draft \
45
+ --assignee "@me" \
45
46
  {label_flags}
46
47
  ```
47
48
 
48
- `gh pr create` prints the pull-request URL. Read it from the command's output and include it in step 4's artifact and the completion line; never capture it into a shell variable.
49
+ `--assignee "@me"` assigns the pull request to the authenticated `gh` user, who is the developer creating it.
49
50
 
50
- ### 3. Handle label failures
51
+ `gh pr create` prints the pull-request URL. Read it from the command's output and include it in step 5's artifact and the completion line; never capture it into a shell variable.
51
52
 
52
- If `gh pr create` fails and the error indicates one or more labels are invalid:
53
+ ### 3. Handle label and assignee failures
53
54
 
54
- 1. Identify the failing label(s) from the error message.
55
- 2. Remove the failing labels from the `--label` flags.
56
- 3. Retry `gh pr create` without the failing labels, re-stating the assignment and the guard for the same scratch file; do not rewrite the body or inline it.
57
- 4. Record which labels were skipped.
55
+ If `gh pr create` fails and the error indicates that one or more labels are invalid, or that the assignee cannot be assigned:
58
56
 
59
- If the failure is unrelated to labels, report the error and stop.
57
+ 1. Identify the failing labels, the assignee, or both from the error message.
58
+ 2. Remove the failing `--label` flags, and remove `--assignee` if the assignee failed.
59
+ 3. Retry `gh pr create` once without them, re-stating the `body_path` assignment and the guard for the same scratch file; do not rewrite the body or inline it.
60
+ 4. Record which labels were skipped, and whether the assignee was skipped, with the reason from the error.
60
61
 
61
- ### 4. Save PR artifact
62
+ If the failure is unrelated to labels and the assignee, report the error and stop.
63
+
64
+ ### 4. Read back the assignee
65
+
66
+ `gh` can create the pull request without applying an assignee that it cannot assign, so read the applied assignee from the created pull request rather than assuming it:
67
+
68
+ ```bash
69
+ gh pr view {PR URL} --json assignees --jq '[.assignees[].login] | join(", ")'
70
+ ```
71
+
72
+ An empty result means that the pull request has no assignee: Record the assignee as skipped, with the reason "not applied by GitHub" unless step 3 already recorded one.
73
+
74
+ ### 5. Save PR artifact
62
75
 
63
76
  Save a `pull-request` artifact in the ticket directory.
64
77
 
@@ -86,6 +99,7 @@ Created: {YYYY-MM-DD HH:MMZ}
86
99
  Labels attempted: {comma-separated list, or "none"}
87
100
  Labels applied: {comma-separated list, or "none"}
88
101
  Labels skipped: {comma-separated list, or "none"}
102
+ Assignee: {login read back in step 4, or "none"}
89
103
 
90
104
  ## Body
91
105
 
@@ -98,6 +112,7 @@ Labels skipped: {comma-separated list, or "none"}
98
112
  PR created: {URL}
99
113
  Labels applied: {list} <- only if labels were requested
100
114
  Labels skipped: {list} <- only if any labels failed
115
+ Assignee skipped: {reason} <- only if the pull request has no assignee
101
116
  Artifact saved: {artifact path}
102
117
  ```
103
118
 
@@ -8,7 +8,7 @@ user-invocable: true
8
8
 
9
9
  Create a pull request on the appropriate platform. This is the user-facing entry point that orchestrates the full PR creation flow, delegating platform-specific API calls to internal skills (`create-gh-pr`, `create-bitbucket-pr`).
10
10
 
11
- The pull request carries the change's entries and overrides in the `change-record` block that the change summary's body ends with, as [the change record](../_data/change-record.md) states them.
11
+ The pull request contains the change's entries and overrides in the `change-record` block that the change summary's body ends with, as [the change record](../_data/change-record.md) states them.
12
12
 
13
13
  ## Optional arguments
14
14
 
@@ -111,15 +111,15 @@ Read `scm` from the session context manifest:
111
111
 
112
112
  ### 9. Insert the closing line above the record block
113
113
 
114
- The body copied from the change summary already ends with the rendered `change-record` block, which `summarize-change` writes from the change entries. Carry it through unchanged: Do not render a block here, and never re-render one from the frontmatter, which does not record any entries.
114
+ The body copied from the change summary already ends with the rendered `change-record` block, which `summarize-change` writes from the change entries. Keep it unchanged: Do not render a block here, and never re-render one from the frontmatter, which does not record any entries.
115
115
 
116
- If `ticket_ref` is non-null, insert `Closes {ticket_ref}` above that block, separated from the text before it and from the block by one blank line each. The `Closes` keyword auto-closes the linked ticket when the PR merges (GitHub for numeric same-repo refs; Jira/Linear for prefixed IDs when their respective integrations are configured). Even when an auto-close integration is not wired up, the line documents the linkage and gives reviewers a clickable cross-reference.
116
+ If `ticket_ref` is non-null, insert `Closes {ticket_ref}` above that block, separated from the text before it and from the block by one blank line each. The `Closes` keyword auto-closes the linked ticket when the PR merges (GitHub for numeric same-repo refs; Jira/Linear for prefixed IDs when their respective integrations are configured). Even when an auto-close integration is not configured, the line documents the linkage and gives reviewers a clickable cross-reference.
117
117
 
118
118
  If `ticket_ref` is null, skip: no closing line.
119
119
 
120
- The closing line goes above the block rather than below it because the block is the body's last element, as [The `change-record` block](../_data/change-record.md#the-change-record-block) states. A merge reads the last `change-record` fence wherever it sits, so the order costs nothing to keep and the convention stays true.
120
+ The closing line goes above the block rather than below it because the block is the body's last element, as [The `change-record` block](../_data/change-record.md#the-change-record-block) states. A merge reads the last `change-record` fence wherever it is in the body, so keeping this order does not affect the merge, and the convention stays true.
121
121
 
122
- If the change summary's body does not end with a block, append the closing line as the body's last line and say that the pull request does not contain a change record, naming `{skill:add-change-record}` as the skill that adds one. A body reaches this step without one when `summarize-change` reported that `render-block` was unavailable or failed.
122
+ If the change summary's body does not end with a block, append the closing line as the body's last line and say that the pull request does not contain a change record, naming `{skill:add-change-record}` as the skill that adds one. The change summary's body does not end with a block when `summarize-change` reported that `render-block` was unavailable or failed.
123
123
 
124
124
  ### 10. Call delegate
125
125
 
@@ -18,8 +18,24 @@ Create a ticket on the appropriate platform. The remote platform (e.g., GitHub)
18
18
  | `--parent <ref>` | Make the new ticket a child of the referenced ticket. One reference; a ticket has one parent. |
19
19
  | `--blocked-by <refs>` | Mark the new ticket as blocked by the referenced tickets. |
20
20
  | `--blocking <refs>` | Mark the new ticket as blocking the referenced tickets. |
21
+ | `--label <labels>` | Apply these labels with the ones that step 5 resolves. GitHub only. |
22
+ | `--repo <OWNER/REPO>` | File the ticket in this GitHub repository. See [Another repository](#another-repository). |
21
23
 
22
- Each takes ticket references in the project's own form (`#123`, `ABC-123`), comma-separated when more than one applies. All three are optional, and each overrides the inference in step 4 for its own relationship.
24
+ The three relationship arguments take ticket references in the project's own form (`#123`, `ABC-123`), comma-separated when more than one applies. Each is optional, and each overrides the inference in step 4 for its own relationship. `--label` takes label names, comma-separated, exactly as the repository spells them.
25
+
26
+ ### Another repository
27
+
28
+ `--repo` files the ticket in another GitHub repository, and every step resolves against that repository rather than the session's: its configuration, its issues, and its artifact directory. Compare the value with `gh repo view --json nameWithOwner --jq .nameWithOwner`, ignoring case; when the two name the same repository, drop `--repo` and run as though it were absent. When the command fails, as it does in a session whose repository is not on GitHub, the two are different repositories.
29
+
30
+ Otherwise, resolve the target before step 1:
31
+
32
+ ```bash
33
+ node {harness_home_dir}/skills/create-ticket/resolve-ticket-target.mjs --repo {OWNER/REPO}
34
+ ```
35
+
36
+ It prints `{"repo": "...", "projectRoot": "...", "projectSlug": "...", "ticketRefPrefix": "...", "missing": [...]}`. `repo` is the canonical `OWNER/REPO`, used as `{target_repo}` below. `projectRoot` is a directory that contains the target's `.meta/label-map.json` and `.agents/preferences.yaml` as they appear on its default branch; `missing` names each that it does not contain, and the completion output reports each. On a non-zero exit, nothing has been created: Report the helper's stderr and stop.
37
+
38
+ The steps below state what changes for a target repository. A step that does not mention it runs unchanged.
23
39
 
24
40
  <!-- guidance-hook: ticketing-preferences -->
25
41
 
@@ -33,6 +49,8 @@ Get `project_slug` and `artifact_base_dir` -- but NOT the new ticket's `ticket_i
33
49
  - From the same manifest JSON, also read `ticket_id` as `branch_ticket_id`, the ticket from which the current branch is derived (empty when the branch name does not encode a ticket). The step-4 inference and the step-6 guard both read it; the new ticket's authoritative `ticket_id` still comes from the platform in step 6. Read `branch_name` and `default_branch` too, which the step-6 guard compares.
34
50
  - Read `project.ticket_ref_prefix` from `.agents/preferences.yaml` (e.g., `CODY-`); if absent, default to empty string
35
51
 
52
+ For a [target repository](#another-repository), take `project_slug` from the helper's `projectSlug` and `ticket_ref_prefix` from its `ticketRefPrefix` instead. `artifact_base_dir` stays the session's.
53
+
36
54
  ### 2. Write ticket content
37
55
 
38
56
  Create the ticket body describing WHAT needs to be done: problem, context, and acceptance criteria. Do NOT include the plan inline. Do NOT include the ticket ID in the heading yet (it's not known until step 6).
@@ -61,8 +79,12 @@ Then decide the ticket's scope and type, for use in steps 5 and 6. The type is t
61
79
 
62
80
  <!-- include: ../../_partials/work-type-choice.md / -->
63
81
 
82
+ For a [target repository](#another-repository), the scope is a key of the `scopes` section in `{projectRoot}/.meta/label-map.json`, or `*` when the target does not have a label map.
83
+
64
84
  ### 3. Resolve platform
65
85
 
86
+ For a [target repository](#another-repository), the platform is GitHub: Skip this step.
87
+
66
88
  Determine where to create the remote ticket:
67
89
 
68
90
  1. **Preferences**: Check `.agents/preferences.yaml` → `integrations`:
@@ -70,12 +92,12 @@ Determine where to create the remote ticket:
70
92
  - If exactly one integration is enabled → use it
71
93
  - If multiple enabled → ask
72
94
 
73
- 2. **Git remote**: if the preferences do not explicitly enable any integration:
95
+ 2. **Git remote**: If the preferences do not explicitly enable any integration:
74
96
 
75
97
  - `git remote get-url origin` pointing to `github.com` → GitHub
76
98
  - Other hosts → ask
77
99
 
78
- 3. **Ask**: if platform cannot be determined
100
+ 3. **Ask**: If platform cannot be determined
79
101
 
80
102
  ### 4. Decide relationships
81
103
 
@@ -87,9 +109,11 @@ Three relationships are available, each stated from the new ticket's side:
87
109
 
88
110
  Decide which apply from the reason this ticket is being created, narrowed by `branch_ticket_id` (step 1): Work split out of the current branch's ticket relates to it, and a backlog idea raised in passing does not. An argument supplied by the caller replaces the inference for its own relationship.
89
111
 
112
+ For a [target repository](#another-repository), do not infer any relationship from `branch_ticket_id`, which identifies a ticket in the session's repository; apply only those that the arguments state. A reference resolves in the target, so pass a ticket in any other repository as its URL.
113
+
90
114
  **Most tickets have none, and for those, say nothing.** When nothing applies, continue to step 5 without asking.
91
115
 
92
- When one or more apply, state each relationship and its target in the project's own reference form and confirm before anything is created, so that a wrong target is visible while it is still free to correct. If the platform resolved in step 3 cannot express one of them, say so here rather than leaving it to appear as a skip in step 7.
116
+ When one or more apply, state each relationship and its target in the project's own reference form and confirm before anything is created, so that a wrong target is visible while it is still free to correct. A relationship supplied through an argument is one that the caller has already confirmed: State it in the completion output and do not ask about it; the confirmation covers the inferred relationships alone. If the platform resolved in step 3 cannot express one of them, say so here rather than reporting it as a skip in step 7.
93
117
 
94
118
  <!-- include: ../_partials/action-items.md / -->
95
119
 
@@ -101,9 +125,13 @@ If the platform resolved in step 3 is GitHub, resolve the labels from the scope
101
125
  node {harness_home_dir}/scripts/describe-change.mjs resolve-labels --scope "{scope}" --type "{type}"
102
126
  ```
103
127
 
128
+ For a [target repository](#another-repository), add `--project-root "{projectRoot}"`, so that the labels come from the target's label map.
129
+
104
130
  Read `labels` from the output, `{"labels":["feature","breaking","scope:agents"]}`; [`resolve-labels`](../_data/title-templates.md#resolve-labels) states what it contains. When the list is empty, the create call does not apply any labels. Relay any warning that the run writes to stderr.
105
131
 
106
- Render one `--label "{label_name}"` flag per returned label, and write them into the create call in step 6 as literal text. A shell variable does not survive the Bash invocation that assigns it, so a call that reads one from an earlier call does not apply any labels at all.
132
+ Append the labels given through `--label` to the returned list; they add to the resolved scope and type labels and never replace them. `gh issue create` fails on a label that the repository does not have, so the caller of `--label` checks that each label exists before invoking this skill. On the Jira path, `--label` is not applied: Report it skipped in the completion output.
133
+
134
+ Render one `--label "{label_name}"` flag per label in the combined list, and write them into the create call in step 6 as literal text. Because a shell variable does not survive the Bash invocation that assigns it, a call that reads one from an earlier call does not apply any labels at all.
107
135
 
108
136
  ### 6. Create remote ticket
109
137
 
@@ -118,6 +146,8 @@ node {harness_home_dir}/scripts/describe-change.mjs render-titles --title "{titl
118
146
  | python3 -c "import sys,json; print(json.load(sys.stdin).get('ticket_title',''))"
119
147
  ```
120
148
 
149
+ For a [target repository](#another-repository), add `--project-root "{projectRoot}"`, so that the title follows the target's `ticket.title_format`.
150
+
121
151
  Use a JSON parser (python3 above; `jq -r '.ticket_title'` if `jq` is available) instead of `grep`/`cut` because rendered titles may contain backslash-escaped double quotes (`\"`), which a regex extractor would silently truncate.
122
152
 
123
153
  The pipeline prints the rendered title. Read it from the command's output and write it into the create call below as literal text, as the GitHub issue title or the Jira summary; it already includes any prefix (per the configured `ticket.title_format`) and the bare title text. Assigning the parse instead prints nothing, and a shell variable does not survive to the create call, so a call that reads `$ticket_title` submits an empty title. If the script is not found, fall back to the bare `{title}`.
@@ -129,9 +159,11 @@ Write the body to a scratch file per [gh body file](#gh-body-file), naming it `g
129
159
  ```bash
130
160
  body_path="{absolute path from the write step}"
131
161
  [ -s "$body_path" ] || { echo "Body file missing or empty: $body_path" >&2; exit 1; }
132
- gh issue create --title "{ticket_title}" --body-file "$body_path" {label_flags}
162
+ gh issue create --title "{ticket_title}" --body-file "$body_path" {label_flags} {repo_flag}
133
163
  ```
134
164
 
165
+ `{repo_flag}` is `--repo {target_repo}` for a [target repository](#another-repository), and empty otherwise; steps 7 and 9 pass it to `gh` the same way.
166
+
135
167
  `gh issue create` prints the issue URL. Read it from the command's output; the issue number is its final path segment. Never capture either into a shell variable.
136
168
 
137
169
  Construct the ticket ID from `ticket_ref_prefix` (step 1) and `number`:
@@ -156,6 +188,8 @@ When the preferences do not name a project, the helper prints `{"fallback": "no-
156
188
 
157
189
  Identify the client per {skill?:update-jira-ticket}, which ranks the three client shapes and states the description format that each one takes. If it identifies none, take the [no-remote fallback](#fallback-no-remote-platform), naming the absent client in the warning.
158
190
 
191
+ <!-- include: ../_partials/jira-task-list-flattening.md / -->
192
+
159
193
  - **`contentFormat` tool** (e.g. `createJiraIssue`): `projectKey`, `issueTypeName`, `summary` (`ticket_title`), and the step-2 body as a top-level `description` with `contentFormat: "markdown"`. Take any further required argument from the tool's own schema, which a connected server may extend.
160
194
  - **HTML tool** (e.g. `create_jira_issue`): The same target and summary, with the body as `description_html`, rendered to the allowlist and passed through that skill's pre-flight checker before the call.
161
195
  - **`acli`**: Write the step-2 body as Markdown to a scratch file per [gh body file](#gh-body-file), naming it `jira-body-{timestamp}.md`, and run the helper once:
@@ -166,10 +200,11 @@ Identify the client per {skill?:update-jira-ticket}, which ranks the three clien
166
200
 
167
201
  `{parent_flag}` is `--parent {parent}` when step 4 decided a parent, and empty otherwise. Pass the body path as the literal absolute path, unquoted, without a shell variable or a guard: The helper refuses a missing or empty file before it calls `acli`.
168
202
 
169
- The helper converts the body to ADF, checks a parent with `acli jira workitem view`, and runs `acli jira workitem create` exactly once. It prints `{"key": "ABC-123", "rawOutput": "...", "parentSkipped": false}`. `parentSkipped: true` means that Jira rejected the parent reference and the work item was created without it; report the parent skipped per step 7.
203
+ When `ticket.base_url` is set, in the repository's preferences or the global file, the helper first compares `acli`'s active site with the base URL's host, because `acli` creates on whichever site it is signed in to. It then converts the body to ADF, checks a parent with `acli jira workitem view`, and runs `acli jira workitem create` exactly once. It prints `{"key": "ABC-123", "rawOutput": "...", "parentSkipped": false, "activeSite": "..."}`, in which `activeSite` is null when `ticket.base_url` is unset. `parentSkipped: true` means that Jira rejected the parent reference and the work item was created without it; report the parent skipped per step 7.
170
204
 
171
205
  On a non-zero exit, read what it printed:
172
- - `{"fallback": ...}`: As under [Resolve the target](#resolve-the-target), and `acli` was not called.
206
+ - `{"fallback": "no-project-key"}`: As under [Resolve the target](#resolve-the-target), and `acli` was not called.
207
+ - `{"fallback": "wrong-site"}` or `{"fallback": "site-unreadable"}`: `acli` is signed in to another site, or its site could not be read, and nothing was created. Create through the next client that {skill?:update-jira-ticket} ranks, including a client that the machine adds. When none remains, take the [no-remote fallback](#fallback-no-remote-platform) with the helper's warning, 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.
173
208
  - `"key": null`: The create call ran, and stderr says why the key is missing. Read the key from `rawOutput` when it contains one, and otherwise check Jira for the work item. Never run `create` again: A second call creates a second work item.
174
209
  - Nothing: An argument or the body file was rejected before any `acli` call, as stderr states. Fix it and run the helper again.
175
210
 
@@ -181,6 +216,8 @@ Identify the client per {skill?:update-jira-ticket}, which ranks the three clien
181
216
 
182
217
  #### Persist the branch association
183
218
 
219
+ For a [target repository](#another-repository), skip this section and report the skip, e.g. `Ticket {target_repo}#{number} filed in another repository; skipped branch-manifest association.` The `ticket_id` comparison below would match a target issue whose number equals the branch's ticket ID.
220
+
184
221
  Persist the new ticket's URL into the branch manifest so that later sessions reuse it (see [ticket source resolution](../_data/ticket-source-resolution.md#stored-ticket-url)), but only when the new ticket belongs to the current branch. Compare `branch_ticket_id` (step 1) against the `ticket_id` produced by the path above, and `branch_name` against `default_branch` (both step 1). The second comparison strips `default_branch`'s remote first, taking everything after its first `/`, since `default_branch` is remote-qualified (`origin/main`) whereas `branch_name` is bare (`main`). Comparing the two as written does not match on any branch and silently disables the guard.
185
222
 
186
223
  - When the branch is not the default branch, and `branch_ticket_id` is either empty (the branch name does not encode a ticket) or equal to `ticket_id` (the branch is already linked to this ticket), persist:
@@ -195,7 +232,7 @@ Persist the new ticket's URL into the branch manifest so that later sessions reu
195
232
 
196
233
  The deriver refuses the write on the default branch regardless, per [Stored ticket URL](../_data/ticket-source-resolution.md#stored-ticket-url). Deciding it here produces the reported skip rather than a stderr diagnostic that never appears in the completion output.
197
234
 
198
- Compare `ticket_id` rather than a bare issue number. `branch_ticket_id` comes from the same deriver logic that the GitHub path's construction mirrors, so the two agree in form on every project: bare when `ticket_ref_prefix` is `#` or absent, prefixed when it is a project key. Comparing a bare number holds only in the first case and silently skips every persist in the second.
235
+ Compare `ticket_id` rather than a bare issue number. `branch_ticket_id` comes from the same deriver logic that the GitHub path's construction mirrors, so the two agree in form on every project: bare when `ticket_ref_prefix` is `#` or absent, prefixed when it is a project key. Comparing a bare number works only in the first case and silently skips every persist in the second.
199
236
 
200
237
  Skip this section entirely when step 6 did not resolve a URL; there is nothing to store.
201
238
 
@@ -203,7 +240,7 @@ Skip this section entirely when step 6 did not resolve a URL; there is nothing t
203
240
 
204
241
  Skip this step when step 4 decided none.
205
242
 
206
- When step 6 did not create a remote ticket (the [no-remote fallback](#fallback-no-remote-platform)), there is nothing to link. Skip every relationship that step 4 decided, each with that as its reason, and report them. A relationship confirmed by the user never disappears without a line in the completion output.
243
+ When step 6 did not create a remote ticket (the [no-remote fallback](#fallback-no-remote-platform)), there is nothing to link. Skip every relationship that step 4 decided, each with that as its reason, and report them. Never drop a relationship confirmed by the user without a line in the completion output.
207
244
 
208
245
  Otherwise apply relationships after the ticket exists rather than as part of creating it. A reference rejected by the platform then fails only the link; the same reference passed to the creation call would fail the creation of the ticket. Jira's clients force an exception for the parent, and the Jira path below states what replaces the guarantee there.
209
246
 
@@ -212,12 +249,12 @@ Otherwise apply relationships after the ticket exists rather than as part of cre
212
249
  One call applies every relationship decided:
213
250
 
214
251
  ```bash
215
- gh issue edit {number} --parent "{parent}" --add-blocked-by "{blocked_by}" --add-blocking "{blocking}"
252
+ gh issue edit {number} --parent "{parent}" --add-blocked-by "{blocked_by}" --add-blocking "{blocking}" {repo_flag}
216
253
  ```
217
254
 
218
255
  Omit the flag for any relationship that step 4 did not decide. Each takes issue numbers or URLs, comma-separated for the two that accept several.
219
256
 
220
- These flags are native to `gh` 2.94 and later. They are not the REST dependencies endpoint, which takes an issue's database `id` rather than its number; reaching for that endpoint is the detour that this note exists to prevent.
257
+ These flags are native to `gh` 2.94 and later. They are not the REST dependencies endpoint, which takes an issue's database `id` rather than its number; using that endpoint is the mistake that this note exists to prevent.
221
258
 
222
259
  #### Jira path
223
260
 
@@ -231,7 +268,13 @@ Through a connected tool, use the link type named `Blocks`, falling back to a ty
231
268
 
232
269
  The two clients take opposite argument orders for the same relationship: `acli --out` names the blocker, whereas a connected tool's `inwardIssue` does. A link type's inward and outward descriptions describe how Jira stores the link, and only `acli`'s argument names follow that orientation, so take each client's mapping from its own documentation and the descriptions only to select the type.
233
270
 
234
- Through `acli`:
271
+ After a create through `acli`, the work item is on the active site; link through `acli` without a further check. After a create through another client, first compare the active site with `ticket_base_url` (step 1) when it is set, and report each link skipped with the helper's stderr line when it exits non-zero:
272
+
273
+ ```bash
274
+ node {harness_home_dir}/scripts/manage-jira-ticket.mjs check-site --target {ticket_base_url}
275
+ ```
276
+
277
+ Then:
235
278
 
236
279
  ```bash
237
280
  acli jira workitem link create --out "{blocker}" --in "{blocked}" --type Blocks --yes
@@ -299,12 +342,12 @@ Then attach it as a comment on the remote ticket, through the platform resolved
299
342
  ```bash
300
343
  body_path="{absolute path from the write step}"
301
344
  [ -s "$body_path" ] || { echo "Body file missing or empty: $body_path" >&2; exit 1; }
302
- gh issue comment {number} --body-file "$body_path"
345
+ gh issue comment {number} --body-file "$body_path" {repo_flag}
303
346
  ```
304
347
 
305
- **Jira.** Comment through the client that created the work item, in the format assigned to that client by {skill?:update-jira-ticket}: a connected tool's own comment surface, or `acli` reading the comment as ADF from a scratch file.
348
+ **Jira.** Comment through the client that created the work item, in the format assigned to that client by {skill?:update-jira-ticket}: a connected tool's own comment surface, or `acli` reading the comment as ADF from a scratch file. Flatten task lists for a connected tool as [Create the work item](#create-the-work-item) states.
306
349
 
307
- The scratch file follows [gh body file](#gh-body-file), whose rules are about the path rather than the platform: `acli` reads a file the same way `gh` does, and a path carried between Bash invocations resolves to nothing either way.
350
+ The scratch file follows [gh body file](#gh-body-file), whose rules are about the path rather than the platform: `acli` reads a file the same way `gh` does, and a path passed between Bash invocations resolves to nothing either way.
308
351
 
309
352
  ```bash
310
353
  adf_path="{absolute path from the write step}"
@@ -342,7 +385,9 @@ Plan saved: {plan artifact path} <- only if plan existed
342
385
  Plan comment skipped: {reason} <- only if a plan was saved but not attached
343
386
  Relationships: {list} <- only if any were created
344
387
  Relationships skipped: {list with reasons} <- only if any were skipped
388
+ Labels skipped: {labels} <- only when `--label` was given on the Jira path
345
389
  Branch association skipped: {reason} <- only when the step-6 guard skipped the persist
390
+ Target configuration missing: {files} <- only when the target's default branch lacks a file in `missing`
346
391
  ```
347
392
 
348
393
  Nothing else.