codeassembly-guidance 0.7.0 → 0.8.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 (101) hide show
  1. package/.meta/changelog.json +261 -0
  2. package/CHANGELOG.md +62 -0
  3. package/README.md +47 -29
  4. package/bin/codeassembly-validate-preferences.js +2 -8
  5. package/content/_partials/diff-audit-checklist.md +1 -0
  6. package/content/_partials/plain-speech.md +2 -2
  7. package/content/_partials/ticket-assessment.md +3 -3
  8. package/content/codeassembly-content.yaml +6 -0
  9. package/content/collections/recommended.md +6 -0
  10. package/content/collections/williamthorsen.md +2 -1
  11. package/content/guidance/rulebooks/accessibility-conventions.md +6 -3
  12. package/content/guidance/rulebooks/cross-repo-migration-conventions.md +27 -0
  13. package/content/guidance/rulebooks/ui-copy-conventions.md +2 -2
  14. package/content/guidance/rulebooks/visual-design-conventions.md +58 -0
  15. package/content/guidance/rulebooks/williamthorsen-collaboration-preferences.md +3 -18
  16. package/content/guidance/rulebooks/williamthorsen-ticketing-preferences.md +6 -2
  17. package/content/guidance/rulebooks/williamthorsen-visual-design-preferences.md +14 -0
  18. package/content/guidance/rulebooks/williamthorsen-workflow-preferences.md +5 -3
  19. package/content/guidance/rulebooks/williamthorsen-writing-preferences.md +5 -20
  20. package/content/guidance/shared/AGENTS.md +2 -3
  21. package/content/scripts/README.md +1 -1
  22. package/content/scripts/check-branch-currency.mjs +7 -7
  23. package/content/scripts/check-prose.mjs +38 -38
  24. package/content/scripts/describe-change.mjs +32 -32
  25. package/content/scripts/manage-jira-ticket.mjs +148 -146
  26. package/content/scripts/validate-preferences.mjs +9 -9
  27. package/content/skills/_data/artifact-conventions.md +3 -3
  28. package/content/skills/_data/entry-points.md +1 -1
  29. package/content/skills/_data/reduced-object-relatives.md +15 -0
  30. package/content/skills/_data/spike-conventions.md +9 -2
  31. package/content/skills/_data/ticket-evaluation.md +3 -0
  32. package/content/skills/_partials/implementation-order-list.md +4 -4
  33. package/content/skills/_partials/merge-settled-criterion.md +1 -0
  34. package/content/skills/_partials/plan-template.md +1 -1
  35. package/content/skills/_partials/resolve-plan-and-ticket.md +2 -2
  36. package/content/skills/_partials/split-ticket-create.md +1 -1
  37. package/content/skills/_partials/ticket-criteria-conventions.md +2 -0
  38. package/content/skills/align-ticket-with-implementation/SKILL.md +2 -2
  39. package/content/skills/analyze-performance/SKILL.md +1 -1
  40. package/content/skills/assess-code-health/SKILL.md +4 -4
  41. package/content/skills/assess-code-health/assess-code-health.mjs +20 -20
  42. package/content/skills/assess-ticket/SKILL.md +3 -1
  43. package/content/skills/assess-ticket/next-steps-after-assessment.md +11 -14
  44. package/content/skills/assess-usability/SKILL.md +4 -4
  45. package/content/skills/capture-event/capture-event.mjs +30 -30
  46. package/content/skills/capture-lede-decision/SKILL.md +1 -1
  47. package/content/skills/capture-lede-decision/capture-lede-decision.mjs +37 -37
  48. package/content/skills/collaborate/SKILL.md +1 -1
  49. package/content/skills/condense-branch/SKILL.md +18 -36
  50. package/content/skills/condense-branch/condense-branch.mjs +17 -0
  51. package/content/skills/create-bitbucket-pr/SKILL.md +9 -11
  52. package/content/skills/create-commit/SKILL.md +1 -1
  53. package/content/skills/create-devlog/SKILL.md +4 -4
  54. package/content/skills/create-gh-pr/SKILL.md +9 -11
  55. package/content/skills/create-pr/SKILL.md +9 -11
  56. package/content/skills/create-ticket/SKILL.md +22 -15
  57. package/content/skills/curate-feedback/SKILL.md +2 -2
  58. package/content/skills/derive-session-context/derive-session-context.mjs +103 -103
  59. package/content/skills/design-and-plan/SKILL.md +6 -6
  60. package/content/skills/groom-backlog/groom-backlog.mjs +15 -15
  61. package/content/skills/implement-plan/SKILL.md +1 -1
  62. package/content/skills/implementation-order/implementation-order.mjs +29 -29
  63. package/content/skills/index-prototypes/SKILL.md +2 -2
  64. package/content/skills/investigate-spike/SKILL.md +3 -3
  65. package/content/skills/list-gh-progress-items/SKILL.md +36 -0
  66. package/content/skills/list-gh-progress-items/list-gh-progress-items.mjs +68 -0
  67. package/content/skills/list-implementation-order/SKILL.md +2 -2
  68. package/content/skills/merge-bb-pr/SKILL.md +9 -11
  69. package/content/skills/merge-gh-pr/SKILL.md +9 -11
  70. package/content/skills/merge-pr/SKILL.md +10 -12
  71. package/content/skills/plan/SKILL.md +2 -2
  72. package/content/skills/prepare-prototype-brief/SKILL.md +2 -2
  73. package/content/skills/pull-from-backlog/pull-from-backlog.mjs +22 -22
  74. package/content/skills/refine-plan/SKILL.md +3 -3
  75. package/content/skills/refine-prototype/SKILL.md +2 -1
  76. package/content/skills/respond-to-review/SKILL.md +4 -4
  77. package/content/skills/review-bb-pr/SKILL.md +1 -2
  78. package/content/skills/review-branch/SKILL.md +18 -13
  79. package/content/skills/review-criteria/SKILL.md +1 -1
  80. package/content/skills/review-gh-pr/SKILL.md +1 -2
  81. package/content/skills/review-pr/SKILL.md +2 -3
  82. package/content/skills/revise-prose/revise-prose.mjs +52 -52
  83. package/content/skills/save-artifact/SKILL.md +4 -6
  84. package/content/skills/save-plan/SKILL.md +2 -2
  85. package/content/skills/start-ticket/SKILL.md +1 -1
  86. package/content/skills/streamline-guidance/streamline-guidance.mjs +24 -24
  87. package/content/skills/summarize-change/SKILL.md +5 -4
  88. package/content/skills/summarize-chat/SKILL.md +2 -2
  89. package/content/skills/triage-feedback/SKILL.md +2 -2
  90. package/content/skills/triage-spike-findings/SKILL.md +26 -22
  91. package/content/skills/triage-spike-findings/triage-spike-findings.mjs +19 -19
  92. package/content/skills/update-project-guidance/SKILL.md +1 -1
  93. package/content/skills/wrap-up/SKILL.md +4 -4
  94. package/content/skills/write-progress-report/SKILL.md +111 -0
  95. package/content/skills/write-progress-report/write-progress-report.mjs +150 -0
  96. package/content/subagents/disposition-challenger.md +7 -6
  97. package/content/subagents/entry-drafter.md +2 -0
  98. package/content/subagents/usability-assessor.md +3 -2
  99. package/package.json +11 -10
  100. package/schemas/preferences.v1.json +9 -1
  101. package/schemas/work-types.v1.json +1 -1
@@ -88,7 +88,7 @@ Both are optional, and each is recorded as an override beside the consolidated r
88
88
 
89
89
  **The reader test.** The reader of a pull-request description is a reviewer who hasn't read the ticket. Each line of a section composed here must change what the reviewer checks or decides. A line fails the test when it states what the diff already shows, the author's own follow-ups or checklists, a step for the author rather than for a reviewer (such as the merge order), ownership or approval routing that tooling already reports, or the history of how the approach was chosen. The test applies to `## Why`, `## Notes for reviewers`, and `## How to test`; `## What` and `## Details` come from `entry-drafter` and follow its contract instead.
90
90
 
91
- Write `## Notes for reviewers` only when a fact passes the test and the other sections do not state it; otherwise omit the section, heading included. Draw the facts from the diff, the commit bodies, and the ticket, and write each as a bullet. Such a fact explains, for example, why a consumer that the reviewer would expect to be affected is not, how the change was tested beyond what CI runs, or why a test runs at an expensive tier. Add a divergence from the ticket's proposal only when it changes what a reviewer checks, and state it as the current fact rather than as a departure from the ticket.
91
+ Write `## Notes for reviewers` only when a fact passes the test and the other sections do not state it; otherwise omit the section, heading included. Draw the facts from the diff, the commit bodies, and the ticket, and write each as a bullet. Such a fact explains, for example, why a consumer that the reviewer would expect to be affected is not, how the change was tested beyond what CI runs, what must happen for the change to take effect, such as a deploy or a sync, or why a test runs at an expensive tier. Add a divergence from the ticket's proposal only when it changes what a reviewer checks, and state it as the current fact rather than as a departure from the ticket.
92
92
 
93
93
  Write `## How to test` only when the diff changes a surface that a person sees or operates: a page, a UI component, or a command's output. Otherwise omit the section, heading included. Compose it from the diff and the ticket as numbered steps, each stating where to go (the route, the page, or the command, and how to start the app when the repository does not make that obvious), what to do there, and what the reviewer should observe. Cover only what CI does not assert: Never list automated checks, such as formatting, linting, typechecking, or tests.
94
94
 
@@ -112,10 +112,11 @@ Both are optional, and each is recorded as an override beside the consolidated r
112
112
 
113
113
  On a first dispatch, take the drafter's `## Lede` section as it stands; step 9 makes it `## What`, and later steps do not rewrite it. A redispatch returns every replacement under `## Entries` and does not return a `## Lede` section at all, so the lede that it keeps is whichever text the placement above left in the lede's place. Parse the `## Entries` fence as YAML. Each entry declares `type`, `scopes`, `breaking`, and `text`, and `migration` when the entry calls for one. Read the `## Report` for any source that the drafter could not access. Step 6 checks each entry's `type`.
114
114
 
115
- 6. **Audit the lede and the entries.** The first three checks apply to the lede, to each entry's `text`, and to each entry's `migration` alike, except as the subject check states, and each names the rejection code that its failure raises, for which a redispatch is the repair rather than an edit of your own. The type check applies to each entry, and raises its code against the entry's `text` alone. `scopes` and `breaking` are not prose and are never rejected; `type` is corrected by the type check and never rejected. The writing-rules check runs last, and it also reads the sections that step 4 composed.
115
+ 6. **Audit the lede and the entries.** The first four checks apply to the lede, to each entry's `text`, and to each entry's `migration` alike, except as the subject check states, and each names the rejection code that its failure raises, for which a redispatch is the repair rather than an edit of your own. The type check applies to each entry, and raises its code against the entry's `text` alone. `scopes` and `breaking` are not prose and are never rejected; `type` is corrected by the type check and never rejected. The writing-rules check runs last, and it also reads the sections that step 4 composed.
116
116
 
117
117
  - **Verification.** Read the lede, each entry's `text`, and each `migration` against the diff from step 2. Strike a claim that the diff contradicts, and correct one that it states differently. Never add: A fact omitted from the draft was left out by the reader of the change, and supplying it here restores the weighting that the fresh-context dispatch removed. The drafter read the diff, so this check no longer supplies the draft's grounding; it catches a sentence claiming more than the diff supports, such as one that only the commit log, the ticket, or this session supports, which the diff does not contradict and which is not one to strike: `rejection: unsupported-claim`.
118
118
  - **Subject.** Read the lede's each sentence, and each entry's `text`, with "This pull request" in front of it. If that sentence is false, the verb names what the system does rather than what the change did: `rejection: subject`. This check fails most often on a change that adds something which itself acts, such as a command, a check, a rule, or a hook, because the added thing's behavior is true, interesting, and reads as a correct entry while standing in for the change. A `migration` is exempt: It is an imperative addressed to the consumer, not a sentence whose subject is the pull request.
119
+ - **Durability.** Read each sentence of the lede, each entry's `text`, and each `migration`, subordinate clauses included, as a reader would read it long after the merge, since the merge commit contains them permanently. A statement of the change's delivery state, such as that it has merged, been deployed, or been released, or a condition for the change to take effect, such as "once it is deployed" or "after the next release", fails the passage: `rejection: transient-state`. A condition that names a version or a configuration stays true and passes.
119
120
  - **Voice.** A figurative verb, or an invented term when a plain one exists: `rejection: voice`.
120
121
  - **Type.** Apply [Work type test](#work-type-test) to the entry's outcome. When the test's type differs from the drafted `type`, or the drafted `type` does not name a key in [work-types.json](../_data/work-types.json), set `type` to the test's result and state the correction in one line with its reason. A type is a determination that you make by applying a test, not prose, so the correction is never a redispatch and never an ask. The entry's `text` is prose: When it is still written in the form that the replaced type takes, such as a `fix` entry's opening on an entry now typed `feat`, that passage fails: `rejection: type-mismatch`.
121
122
  - **Writing rules.** Run this check over the passages that passed every check above, and over the sections that step 4 composed, so that a redispatch names one code. Write them to a scratch file, created per the path rules of [gh body file](#gh-body-file) and named `prose-check-{timestamp}.md`, as bare paragraphs separated by blank lines, without headings or list markers: the lede, each entry's `text` and each `migration` as paragraphs of their own, each paragraph of `## Why`, each note of `## Notes for reviewers`, and each step of `## How to test`. Write it with a file-writing tool rather than a shell heredoc, as step 7 does. Then run:
@@ -318,11 +319,11 @@ When used as a PR description, include **from `## What` onward only**; omit the
318
319
 
319
320
  ### Path resolution
320
321
 
321
- Invoke `node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs` via Bash to obtain `artifact_base_dir`, `project_slug`, and `ticket_id` from the manifest JSON emitted on stdout (the same invocation in step 1 already populated the manifest file, so this is a fast-path read).
322
+ Invoke `node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs` via Bash to obtain `ticket_dir` from the manifest JSON emitted on stdout (the same invocation in step 1 already populated the manifest file, so this is a fast-path read).
322
323
 
323
324
  Follow [artifact conventions](../_data/artifact-conventions.md).
324
325
 
325
- Ticket directory: `{artifact_base_dir}/projects/{project_slug}/tickets/{ticket_id}/`
326
+ Ticket directory: `{ticket_dir}/`, or the directory that {skill:save-artifact} states when `ticket_dir` is null
326
327
 
327
328
  Artifact type: `change-summary`. Filename format:
328
329
 
@@ -77,9 +77,9 @@ Run `{harness_home_dir}/scripts/resolve-frontmatter.sh --skill summarize-chat --
77
77
 
78
78
  ## Saving
79
79
 
80
- Resolve artifact directory by invoking `node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs` via Bash to obtain `artifact_base_dir`, `project_slug`, and `artifact_paths` from the manifest JSON emitted on stdout. The chats path is `artifact_paths.chats` (default: `chats`).
80
+ Resolve artifact directory by invoking `node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs` via Bash to obtain `project_artifact_dir` and `artifact_paths` from the manifest JSON emitted on stdout. The chats path is `artifact_paths.chats` (default: `chats`).
81
81
 
82
- Full path: `{artifact_base_dir}/projects/{project_slug}/{chats_path}/`
82
+ Full path: `{project_artifact_dir}/{chats_path}/`
83
83
 
84
84
  Follow [artifact conventions](../_data/artifact-conventions.md).
85
85
 
@@ -61,8 +61,8 @@ node {harness_home_dir}/skills/triage-feedback/triage-feedback.mjs {command} {fl
61
61
 
62
62
  ### 1. Preflight
63
63
 
64
- 1. Run `node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs` and read `artifact_base_dir`, `project_slug`, and `ticket_id`.
65
- 2. Fix the artifact's path now, because a deferral references it. The directory is `{artifact_base_dir}/projects/{project_slug}/tickets/{ticket_id}/` when `ticket_id` is set, and `{artifact_base_dir}/projects/{project_slug}/feedback-triage/` otherwise; the `feedback-triage/` name is hardcoded. The filename is `{YYYYMMDD-HHMMSSZ}_{slug}_feedback-triage.md`, with the current UTC time and a slug per {skill:save-artifact}, or `triage` when nothing else suits.
64
+ 1. Run `node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs` and read `ticket_dir` and `project_artifact_dir`.
65
+ 2. Fix the artifact's path now, because a deferral references it. The directory is `{ticket_dir}/` when the manifest's `ticket_dir` is not null, and `{project_artifact_dir}/feedback-triage/` otherwise; the `feedback-triage/` name is hardcoded. The filename is `{YYYYMMDD-HHMMSSZ}_{slug}_feedback-triage.md`, with the current UTC time and a slug per {skill:save-artifact}, or `triage` when nothing else suits.
66
66
  3. Create the work directory `{timestamp}_work/` beside the artifact, where `{timestamp}` is the filename's prefix. Every working file goes there.
67
67
  4. Run `gh auth status`. When it fails, report that tickets cannot be filed, and continue only when the developer accepts a run that defers or rates.
68
68
 
@@ -1,12 +1,12 @@
1
1
  ---
2
2
  name: triage-spike-findings
3
- description: Dispose of the findings that a spike, a usability assessment, a code-health assessment, or a performance analysis left without a ticket. Inventories every undisposed item, grades each one's confidence and value, has a subagent without session context challenge every grade, and then creates the labelled tickets under an umbrella and records every disposition on the triage ticket. Use when a findings artifact has proposals or ideas that the existing tickets have not absorbed.
3
+ description: Dispose of the findings that a spike, a usability assessment, a code-health assessment, or a performance analysis left without a ticket. Inventories every undisposed item, grades each one's confidence and value, has a subagent without session context challenge every grade, and then creates the graded tickets under an umbrella, and records every disposition on the triage ticket. Use when a findings artifact has proposals or ideas that the existing tickets have not absorbed.
4
4
  user-invocable: true
5
5
  ---
6
6
 
7
7
  # Triage spike findings
8
8
 
9
- Dispose of every item that a findings artifact leaves undisposed: the proposals, groupings, findings, and ideas that the filed tickets and comments did not absorb. You inventory them, recommend a disposition and two grades for each, have a {subagent:disposition-challenger} argue against every recommendation, and then, once the developer approves, create the tickets and post the record. A bundled helper checks the repository's labels, validates the dispositions record, and renders the comments.
9
+ Dispose of every item that a findings artifact leaves undisposed: the proposals, groupings, findings, and ideas that the filed tickets and comments did not absorb. You inventory them, recommend a disposition and two grades for each, have a {subagent:disposition-challenger} argue against every recommendation, and then, once the developer approves, create the tickets and post the record. A bundled helper checks a GitHub repository's labels, validates the dispositions record, and renders the comments.
10
10
 
11
11
  **Announce at start:** "Using triage-spike-findings to dispose of the findings of {source} on {ticket_ref}."
12
12
 
@@ -18,19 +18,19 @@ Dispose of every item that a findings artifact leaves undisposed: the proposals,
18
18
 
19
19
  A run triages one [findings batch](../_data/spike-conventions.md#findings-batches) on one triage ticket.
20
20
 
21
- GitHub alone is supported, through `gh`. When the session-context manifest's `scm` is not `github`, stop at preflight and report that the skill does not support the platform.
21
+ The run supports each [triage platform](../_data/spike-conventions.md#triage-platforms), GitHub through `gh`. Step 1 resolves the platform, and every later step reads it from the record's `platform`. Each step states the GitHub path; a sentence that opens with "On Jira" states that step's Jira counterpart.
22
22
 
23
23
  ## Grades and dispositions
24
24
 
25
25
  Each item takes a disposition and two grades:
26
26
 
27
- - **Disposition**: `ticket` (a child of the umbrella), `comment` (a note on an existing issue, which must be open and must own the file or the behavior), `merge` (folded into another item's ticket; the target is a `ticket` item), or `drop`.
27
+ - **Disposition**: `ticket` (a new ticket, a child of the umbrella), `comment` (a note on an existing issue, which must be open and must own the file or the behavior), `merge` (folded into another item's ticket; the target is a `ticket` item), or `drop`.
28
28
 
29
29
  <!-- include: ../../_partials/finding-grades.md / -->
30
30
 
31
- The helper refuses a record that gives a `low` item a ticket. Value never decides whether an item gets a ticket; it is recorded on every item and labels every child.
31
+ The helper refuses a record that gives a `low` item a ticket. Value never decides whether an item gets a ticket; it is recorded on every item and labels every child on GitHub.
32
32
 
33
- The labels come from the common preset of `release-kit sync-labels`: the `value:` family, and the `confidence:` family that williamthorsen/node-monorepo-tools#1017 added. A repository whose labels lack either family cannot take the children, because `gh issue create` fails on a label that the repository does not have.
33
+ The labels come from the common preset of `release-kit sync-labels`: the `value:` family, and the `confidence:` family that williamthorsen/node-monorepo-tools#1017 added. A repository whose labels lack either family cannot take the children, because `gh issue create` fails on a label that the repository does not have. On Jira, the run does not read or set any label: Jira does not have the two families, and on some sites labels are one namespace shared by every project. Each child's grade line, which step 6 composes, records its grades in their place.
34
34
 
35
35
  ## Process
36
36
 
@@ -44,13 +44,14 @@ Resolve `{ticket_dir}` per {skill:save-artifact}, and write every working file u
44
44
 
45
45
  ### 1. Preflight
46
46
 
47
- 1. Run `gh auth status` and `gh repo view --json nameWithOwner`. If either fails, or `scm` is not `github`, stop and report why.
48
- 2. Run the helper's `check-labels`. When `complete` is false, stop: Name each missing label, and state that the common preset of `release-kit sync-labels` supplies both families (the `confidence:` family from williamthorsen/node-monorepo-tools#1017), so the repository takes them by upgrading release-kit and regenerating its label file rather than by creating them by hand.
49
- 3. Create `{ticket_dir}/triage/`, and save the findings there when they came from a URL.
47
+ 1. Resolve the platform as {skill:create-ticket} step 3 resolves it: from the integrations that `.agents/preferences.yaml` enables, then from the git remote. The session-context manifest's `scm` names the code host, which does not decide where the tickets live. On a platform that is not a [triage platform](../_data/spike-conventions.md#triage-platforms), stop and report that the skill does not support it.
48
+ 2. On GitHub, run `gh auth status` and `gh repo view --json nameWithOwner`. If either fails, stop and report why. Then run the helper's `check-labels`. When `complete` is false, stop: Name each missing label, and state that the common preset of `release-kit sync-labels` supplies both families (the `confidence:` family from williamthorsen/node-monorepo-tools#1017), so the repository takes them by upgrading release-kit and regenerating its label file rather than by creating them by hand.
49
+ 3. On Jira, identify the client per {skill?:update-jira-ticket}. When it is `acli`, run that skill's site check against the triage ticket's URL, or against `ticket.base_url` when the URL is not known. Read the triage ticket through the client, and stop when no client can read it.
50
+ 4. Create `{ticket_dir}/triage/`, and save the findings there when they came from a URL.
50
51
 
51
52
  ### 2. Inventory
52
53
 
53
- Read the findings in full. List every item that the artifact leaves without a disposition, where a disposition is a ticket or a comment that the artifact itself names: a proposed ticket that was not filed, a grouping, a finding outside every grouping, and an idea that the filed tickets did not absorb. Verify each item's claim against the current code and against the open issues, found with `gh issue list --search` and read with their comments per [platform-specific fetch](../_data/ticket-source-resolution.md#platform-specific-fetch): The finding may describe a problem that a merge has since fixed, a decision that the repository records, or work that an open issue already covers.
54
+ Read the findings in full. List every item that the artifact leaves without a disposition, where a disposition is a ticket or a comment that the artifact itself names: a proposed ticket that was not filed, a grouping, a finding outside every grouping, and an idea that the filed tickets did not absorb. Verify each item's claim against the current code and against the open issues, found with `gh issue list --search` and read with their comments per [platform-specific fetch](../_data/ticket-source-resolution.md#platform-specific-fetch). On Jira, search the triage ticket's project with `acli jira workitem search --jql 'project = {project key} AND statusCategory != Done AND text ~ "{terms}"' --json --paginate`, or with the search of the connected client, and read each match with its comments per the same section's Jira fetch. The finding may describe a problem that a merge has since fixed, a decision that the repository records, or work that an open issue already covers.
54
55
 
55
56
  Write `inventory.md` as a table: the item's id (the artifact's own id when it has one), its title, where it appears in the artifact, the verification outcome (holds, partly holds, or does not hold, with the evidence), and, when the findings give the item an evidence key and the paths that it covers, that key and those paths, copied verbatim. Give an item that the artifact does not identify an id of the inventory's own, so that a follow-up triage ticket can name it.
56
57
 
@@ -58,7 +59,7 @@ When the inventory holds more items than the batch ceiling, split it into batche
58
59
 
59
60
  ### 3. Recommend
60
61
 
61
- Write `recommendations.md`: one line per item, with its id, title, disposition, confidence, value, and a one-sentence reason. Nothing else goes in the file, because the challenger reads it and a sentence of your reasoning there would bias its judgment toward yours. A `merge` names a `ticket` item as its target; a `comment` names its issue number.
62
+ Write `recommendations.md`: one line per item, with its id, title, disposition, confidence, value, and a one-sentence reason. Nothing else goes in the file, because the challenger reads it and a sentence of your reasoning there would bias its judgment toward yours. A `merge` names a `ticket` item as its target; a `comment` names its issue number, or its key on Jira.
62
63
 
63
64
  ### 4. Challenge
64
65
 
@@ -66,6 +67,7 @@ Send one {tool:Task} call, `subagent_type: disposition-challenger`, with this bl
66
67
 
67
68
  ```dispatch
68
69
  findings: {ticket_dir}/triage/findings.md
70
+ platform: {the platform from step 1}
69
71
  recommendations: {ticket_dir}/triage/recommendations.md
70
72
  root: {repository root}
71
73
  ```
@@ -74,9 +76,9 @@ root: {repository root}
74
76
 
75
77
  Save the reply as `challenge.md`. Then take each item in turn: Defend the recommendation when the argument fails on the evidence, modify it when the argument stands in part, and abandon it when the argument stands. A defense answers the argument on the evidence that the argument names; a defense that rests on other grounds fails. An argument that lowers the grade of a code-health item on the one-time cost of the change fails under the grade definitions above, even when the challenger raises it.
76
78
 
77
- Decide the blockers of every `ticket` item under the threshold in the ticketing preferences rulebook: An item is blocked by another ticket when there is some probability that the other ticket affects it and should be merged first, and a ticket whose design takes another ticket's outcome as an input is blocked by it. A blocker is another `ticket` item, by id, or an open issue in this repository outside the triage, by number; check each issue with `gh issue view {issue} --json state`, and omit a closed one, which does not block. Record every such dependency in `blockedBy`, never in `notes`.
79
+ Decide the blockers of every `ticket` item under the threshold in the ticketing preferences rulebook: An item is blocked by another ticket when there is some probability that the other ticket affects it and should be merged first, and a ticket whose design takes another ticket's outcome as an input is blocked by it. A blocker is another `ticket` item, by id, or an open issue in this repository outside the triage, by number; check each issue with `gh issue view {issue} --json state`, and omit a closed one, which does not block. On Jira, a blocker outside the triage is a work item, by key; read its status with `acli jira workitem view {key} --json --fields status`, and omit one whose status category is `done`. Record every such dependency in `blockedBy`, never in `notes`.
78
80
 
79
- Write `dispositions.json` in the helper's record shape: `source` (the findings as given), `triageTicket`, `umbrella: null`, `items`, `challengeSummary` (what the challenge refuted or narrowed and what it did not), and `notes` (the lines of the comment's "Labels and follow-ups" section, empty when there are none). Each item has `id`, `title`, `disposition`, `confidence`, `value`, `reason`, `target` (the issue number of a `comment`, the target id of a `merge`, null otherwise), `ticket: null`, `blockedBy` on a `ticket` item that has blockers (item ids and issue numbers), `evidence` with `key` and `paths` on an item whose inventory row has them (omitted otherwise), and `challenge` with `argument`, `outcome` (`defended`, `modified`, or `abandoned`), and `note`. When any item has `evidence`, write the output of `git rev-parse HEAD` into the record's `commit`. Run the helper's `validate`, which reports every schema and gate violation at once, a cycle among the blockers included, and fix the record until it passes.
81
+ Write `dispositions.json` in the helper's record shape: `platform` (`github` or `jira`, from step 1), `source` (the findings as given), `triageTicket` (its number, or its key on Jira), `umbrella: null`, `items`, `challengeSummary` (what the challenge refuted or narrowed and what it did not), and `notes` (the lines of the comment's "Labels and follow-ups" section, "Follow-ups" on Jira, empty when there are none). Each item has `id`, `title`, `disposition`, `confidence`, `value`, `reason`, `target` (the issue of a `comment`, the target id of a `merge`, null otherwise), `ticket: null`, `blockedBy` on a `ticket` item that has blockers (item ids, and issue numbers or keys), `evidence` with `key` and `paths` on an item whose inventory row has them (omitted otherwise), and `challenge` with `argument`, `outcome` (`defended`, `modified`, or `abandoned`), and `note`. When any item has `evidence`, write the output of `git rev-parse HEAD` into the record's `commit`. Run the helper's `validate`, which reports every schema and gate violation at once, a cycle among the blockers included, and fix the record until it passes.
80
82
 
81
83
  ### 5. Checkpoint: The dispositions
82
84
 
@@ -88,9 +90,9 @@ Present the dispositions as a table (item, disposition, confidence, value, block
88
90
 
89
91
  Compose the bodies:
90
92
 
91
- - **The umbrella**, when at least one item is a `ticket`: its problem (the follow-up work of the findings), its context (a link to the triage ticket, and the tickets that the findings filed without adopting them, listed and not made children), and "Every child is closed" as its acceptance criterion. It does not take a graded label.
92
- - **One child per `ticket` item**, in the ticket skeleton that {skill:create-ticket} step 2 states: problem, context, and acceptance criteria, with the title and reason of every `merge` item that targets it folded in. Its labels are `confidence:{grade}` and `value:{grade}`.
93
- - **One follow-up triage ticket per later batch**, when the **Batches** table has more than one row: titled `Triage batch {n} of {findings title}`, with a link to the findings artifact, its path written `~/`-relative as in the [closing post](../_data/spike-conventions.md#closing-post), a link to the triage ticket, whose dispositions comment records the earlier round, the batch's items by id and title as its **The batch** input, and `triage-spike-findings` as its next step. Read the triage ticket's parent with `gh issue view {triage ticket} --json parent`: A follow-up takes that parent when there is one, so that it sits beside its siblings, and no parent otherwise. Each follow-up is blocked by the one before it. The first is not blocked: This round's dispositions are posted before the next round starts. Add one line per follow-up to the record's `notes`, `Batch {n} ({item ids}) is triaged in {follow-up}`, with the follow-up's title in place of `{follow-up}` until step 7 creates it, so that the dispositions comment names every follow-up.
93
+ - **The umbrella**, when at least one item is a `ticket`: its problem (the follow-up work of the findings), its context (a link to the triage ticket, and the tickets that the findings filed without adopting them, listed and not made children), and "Every child is closed" as its acceptance criterion. It does not take a graded label or any blocker, and it does not have a parent.
94
+ - **One child per `ticket` item**, in the ticket skeleton that {skill:create-ticket} step 2 states: problem, context, and acceptance criteria, with the title and reason of every `merge` item that targets it folded in. Its labels are `confidence:{grade}` and `value:{grade}`. On Jira, it does not take any label. Its parent is the umbrella. Its `## Context` links the triage ticket, and that section's last line is its grade line: `Triage grades: confidence {confidence}, value {value}`.
95
+ - **One follow-up triage ticket per later batch**, when the **Batches** table has more than one row: titled `Triage batch {n} of {findings title}`, with a link to the findings artifact, its path written `~/`-relative as in the [closing post](../_data/spike-conventions.md#closing-post), a link to the triage ticket, whose dispositions comment records the earlier round, the batch's items by id and title as its **The batch** input, and `triage-spike-findings` as its next step. Read the triage ticket's parent with `gh issue view {triage ticket} --json parent`, or on Jira with `acli jira workitem view {triage ticket} --json --fields parent`: A follow-up takes that parent when there is one, so that it sits beside its siblings, and no parent otherwise. Each follow-up is blocked by the one before it. The first is not blocked: This round's dispositions are posted before the next round starts. Add one line per follow-up to the record's `notes`, `Batch {n} ({item ids}) is triaged in {follow-up}`, with the follow-up's title in place of `{follow-up}` until step 7 creates it, so that the dispositions comment names every follow-up.
94
96
 
95
97
  Run the helper's `render --preview` to `{ticket_dir}/triage/preview/`, which writes the dispositions comment with `(pending)` where a number is not yet known, and one comment file per issue that a `comment` disposition names.
96
98
 
@@ -100,10 +102,10 @@ Show everything that step 7 will create or post in one block: every body with it
100
102
 
101
103
  Nothing before this step writes anything remote. On a failed write, stop and report which item failed; every number already recorded stays in `dispositions.json`, so that a re-run of this step creates only what is still null and checks each issue before posting on it.
102
104
 
103
- 1. When at least one item is a `ticket` and `umbrella` is null, create the umbrella with {skill:create-ticket}, and write its number into `umbrella`.
104
- 2. For each `ticket` item, in the order that `validate` reports as `order` for the approved record, run {skill:create-ticket} with `--parent {umbrella}` and `--label confidence:{grade},value:{grade}`, adding `--blocked-by` with the item's blockers as `#{number}` (the recorded `ticket` of each item id, and each issue number) when it has any, and write the returned number into the item's `ticket` as soon as it is returned. Because `order` places every blocker first, each item id that `--blocked-by` names already has its number.
105
- 3. For each `ticket` item, read `gh issue view {ticket} --json parent,blockedBy`, and add what is missing in one `gh issue edit {ticket} --parent {umbrella} --add-blocked-by {numbers}` call, omitting a flag that has nothing to add. {skill:create-ticket} sets the parent and the blockers in one call, so a rejected blocker can drop the parent as well, and this read-back is how a failed link is found. On a re-run, it completes the links of the items that an earlier run created.
106
- 4. For each later batch, in batch order, skip the batch when its follow-up ticket is already recorded in the **Batches** table. Otherwise create its follow-up with {skill:create-ticket}, adding `--parent` and `--blocked-by` as step 6 composed them, and as soon as the number is returned, write it into the table and replace the follow-up's title with `#{number}` in its `notes` line.
105
+ 1. When `validate` reports the umbrella missing, create it with {skill:create-ticket} and `--umbrella`, which on Jira creates it at the issue type that Jira accepts as its children's parent, and write its number, or its key on Jira, into `umbrella`. The umbrella is missing only while a `ticket` item lacks its ticket, so a re-run of a record whose children were all created without one does not create it.
106
+ 2. For each `ticket` item, in the order that `validate` reports as `order` for the approved record, run {skill:create-ticket} with `--parent {umbrella}` and `--label confidence:{grade},value:{grade}`, adding `--blocked-by` with the item's blockers as `#{number}` (the recorded `ticket` of each item id, and each issue number) when it has any, and write the returned number into the item's `ticket` as soon as it is returned. On Jira, pass `--parent {umbrella}` with the umbrella's key, `--blocked-by` with the blockers' keys, never `--label`, and write the returned key into `ticket`. Because `order` places every blocker first, each item id that `--blocked-by` names already has its ticket.
107
+ 3. For each `ticket` item, read `gh issue view {ticket} --json parent,blockedBy`, and add what is missing in one `gh issue edit {ticket} --parent {umbrella} --add-blocked-by {numbers}` call, omitting a flag that has nothing to add. {skill:create-ticket} sets the parent and the blockers in one call, so a rejected blocker can drop the parent as well, and this read-back is how a failed link is found. On a re-run, it completes the links of the items that an earlier run created. On Jira, read `acli jira workitem view {ticket} --json --fields parent,issuelinks`, read the blockers as [open blockers](../_data/ticket-source-resolution.md#open-blockers) reads them on Jira, and add each missing one with `acli jira workitem link create --out {ticket} --in {blocker} --type Blocks --yes`. `acli` cannot set a parent after creation: When {skill:create-ticket} reported `parentSkipped` or the read-back does not show the composed parent, add the line `{ticket} does not have its parent {parent}` to `notes`, so that the dispositions comment records it.
108
+ 4. For each later batch, in batch order, skip the batch when its follow-up ticket is already recorded in the **Batches** table. Otherwise create its follow-up with {skill:create-ticket}, adding `--parent` and `--blocked-by` as step 6 composed them, and as soon as the number is returned, write it into the table and replace the follow-up's title with `#{number}`, or with its key on Jira, in its `notes` line.
107
109
  5. Run the helper's `render` to `{ticket_dir}/triage/rendered/`, without `--preview`.
108
110
  6. Post each `comment-{issue}.md` on its issue, and then `dispositions-comment.md` on the triage ticket. Before each post, read the issue's comments with `gh issue view {issue} --json comments`, and skip the post when a comment already opens with the first line of the rendered file:
109
111
 
@@ -115,12 +117,14 @@ Nothing before this step writes anything remote. On a failed write, stop and rep
115
117
 
116
118
  Keep the URL that `gh issue comment` prints for the dispositions comment; when the post was skipped, keep the `url` of the matching comment instead. Step 8 links it.
117
119
 
118
- 7. On a run given **The batch**, close the triage ticket without a closing post, because its dispositions comment is its record: Read `gh issue view {triage ticket} --json state`, and run `gh issue close {triage ticket} --reason completed` only while the state is `OPEN`.
120
+ On Jira, post through the client that {skill?:update-jira-ticket} names. With `acli`, convert each rendered file to ADF with that skill's `convert-body` call, read `acli jira workitem comment list --key {key} --json --paginate`, which prints one JSON object per page and each comment's `body` as plain text, and skip the post when a body, with its whitespace collapsed, opens with the rendered file's first line without its Markdown markers, such as the `## ` of the dispositions heading. Otherwise, post with `acli jira workitem comment create --key {key} --body-file {ADF path}`. For the dispositions comment, keep `{site}/browse/{triage ticket}?focusedCommentId={id}`, taking the comment's `id` from the comment list, read again after a post.
121
+
122
+ 7. On a run given **The batch**, close the triage ticket without a closing post, because its dispositions comment is its record: Read `gh issue view {triage ticket} --json state`, and run `gh issue close {triage ticket} --reason completed` only while the state is `OPEN`. On Jira, run `node {harness_home_dir}/scripts/manage-jira-ticket.mjs close --key {triage ticket}` without `--post`; it transitions the ticket only while its status category is not `done`.
119
123
  8. Save `dispositions-comment.md`, with frontmatter, as the ticket-level `dispositions` artifact per {skill:save-artifact}.
120
124
 
121
125
  ### 8. Report
122
126
 
123
- Report the umbrella when one was created, each child with its grades and blockers in the order in which step 7 created them, each follow-up triage ticket with its batch, each issue commented on, the close of the triage ticket on a run given **The batch**, and the artifact's path.
127
+ Report the umbrella when one was created, each child with its grades and blockers in the order in which step 7 created them, each Jira child whose parent was not set, each follow-up triage ticket with its batch, each issue commented on, the close of the triage ticket on a run given **The batch**, and the artifact's path.
124
128
 
125
129
  When the record names two or more tickets among the children and the follow-up triage tickets, print the list for them after the report, per [implementation-order list](#implementation-order-list), leaving out the umbrella. They include a ticket that an earlier run of the same record created.
126
130