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
@@ -37,8 +37,8 @@ Before every {tool:Task} call and after every phase completion, output a status
37
37
 
38
38
  Then report the ticket's open blockers per [Open blockers](../_data/ticket-source-resolution.md#open-blockers), and continue: A blocker does not stop the review.
39
39
 
40
- 4. Invoke `node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs` via Bash to obtain `branch_name`, `default_branch`, `ticket_id`, `project_slug`, and `artifact_base_dir` from the manifest JSON emitted on stdout. Then check the branch per [branch currency](../_data/branch-currency.md), passing the paths in the plan's **Files:** lists, before the review starts.
41
- 5. Resolve artifact directory: `{artifact_base_dir}/projects/{project_slug}/tickets/{ticket_id}/`
40
+ 4. Invoke `node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs` via Bash to obtain `branch_name`, `default_branch`, `ticket_id`, and `ticket_dir` from the manifest JSON emitted on stdout. Then check the branch per [branch currency](../_data/branch-currency.md), passing the paths in the plan's **Files:** lists, before the review starts.
41
+ 5. Resolve the artifact directory, `{artifact_dir}`: the manifest's `ticket_dir`, or the directory that {skill:save-artifact} states when it is null.
42
42
  6. `mkdir -p {artifact_dir}`
43
43
 
44
44
  ### 2. Dispatch plan-reviewer
@@ -87,7 +87,7 @@ Evaluate the finding counts:
87
87
 
88
88
  - **0 user questions** (UserQuestions = 0, AutoResolvable > 0): Skip user interaction. Proceed to step 4 with empty user answers.
89
89
 
90
- - **User questions present** (UserQuestions > 0): Read the review artifact. Extract all findings from the "Decision gaps" section (these may be C or X findings -- the section is organized by resolution type, not finding category). Present each finding's question using the finding's ID (e.g., `C1`, `X2`) as the question identifier. When asking option-style questions, follow [option format](#option-format). (Reinforces the rule in `AGENTS.md`: intentional redundancy.)
90
+ - **User questions present** (UserQuestions > 0): Read the review artifact. Extract all findings from the "Decision gaps" section (these may be C or X findings -- the section is organized by resolution type, not finding category). Present each finding's question using the finding's ID (e.g., `C1`, `X2`) as the question identifier. When asking option-style questions, follow [option format](#option-format).
91
91
 
92
92
  ```
93
93
  The plan review identified {UserQuestions} question(s) that need your input:
@@ -30,7 +30,8 @@ On:
30
30
 
31
31
  - The page is self-contained and opens from `file://`, with its demo chrome in a band whose every part is inside an element that has `data-demo`, as the brief that built it required.
32
32
  - The band's first line is the page's id and title, `{number}.{version} {title}`, so that the developer reads which version they have open without returning to the index, and the page's `<title>` follows the rule in {skill:index-prototypes} "The set". Every step that sets a new id on the working file sets both.
33
- - {rulebook:accessibility-conventions} is the floor: Check contrast and size when a command changes a colour or a text size, apply its placement, toggle, and button-at-rest rules when a command adds or moves a control, and apply its glanceable-state rule when a command adds or changes a list.
33
+ - {rulebook:accessibility-conventions} is the floor: Check contrast and size when a command changes a colour or a text size, apply its placement, toggle, button-at-rest, and consequence-at-the-control rules when a command adds or moves a control, and apply its glanceable-state rule when a command adds or changes a list.
34
+ - {rulebook:visual-design-conventions} is the floor for layout: Apply its spacing, alignment, mark, and role rules when a command adds or moves a block, a mark, or a control.
34
35
  - A new string on the product surface follows {rulebook:ui-copy-conventions}.
35
36
  - One working file. A batch edits it in place; a fork is written next to it and is deleted once the developer picks.
36
37
 
@@ -19,7 +19,7 @@ This skill runs between receiving a code review and implementing fixes. The agen
19
19
 
20
20
  ## Process
21
21
 
22
- 1. **Get context**: Invoke `node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs` via Bash. The bundle emits the session-context manifest JSON to stdout; extract `ticket_id`, `ticket_ref`, `project_slug`, `artifact_base_dir`, and `pr_url` from it.
22
+ 1. **Get context**: Invoke `node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs` via Bash. The bundle emits the session-context manifest JSON to stdout; extract `ticket_id`, `ticket_ref`, `ticket_dir`, and `pr_url` from it.
23
23
  2. **Locate the review** per the [Locating the review](#locating-the-review) section
24
24
  3. **Read prior artifacts** in the review's run directory chronologically for full context
25
25
  4. **Parse findings**: Extract all numbered findings (F{n}, W{n}, T{n}, R{n}, S{n}, and legacy variants with `-L` suffix). See [finding scheme](../_data/artifact-conventions.md#finding-scheme-fwtrs--legacy-suffix) for category definitions.
@@ -64,8 +64,8 @@ If a path argument is provided, read the review directly from that path. If the
64
64
 
65
65
  If the invocation does not include a path, find the most recent `reviewer_review` in the active run:
66
66
 
67
- 1. Resolve the ticket directory: `{artifact_base_dir}/projects/{project_slug}/tickets/{ticket_id}/`
68
- 2. Invoke `node {harness_home_dir}/scripts/resolve-review-run.mjs latest --ticket-dir <ticket-dir>` via Bash. The helper prints `{ "reviewPath": "<path>", "runDir": "<path>" }`: the ticket's active run, per [artifact conventions](../_data/artifact-conventions.md#run-directories), and the newest reviewer or overseer review in it.
67
+ 1. Resolve the ticket directory, `{ticket_dir}`, from the session-context manifest.
68
+ 2. Invoke `node {harness_home_dir}/scripts/resolve-review-run.mjs latest --ticket-dir {ticket_dir}` via Bash. The helper prints `{ "reviewPath": "<path>", "runDir": "<path>" }`: the ticket's active run, per [artifact conventions](../_data/artifact-conventions.md#run-directories), and the newest reviewer or overseer review in it.
69
69
 
70
70
  If the helper exits non-zero, the ticket directory does not contain an active run or the active run does not contain a review; stop and report the message that it printed on stderr.
71
71
 
@@ -278,7 +278,7 @@ The body following the frontmatter has this structure:
278
278
 
279
279
  ### Path resolution
280
280
 
281
- Invoke `node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs` via Bash to obtain `artifact_base_dir` and `project_slug` 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).
281
+ 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).
282
282
 
283
283
  Follow [artifact conventions](../_data/artifact-conventions.md).
284
284
 
@@ -17,9 +17,8 @@ This skill does not run a review. The review logic is implemented in `review-bra
17
17
  | `pr_id` | string | PR number (e.g., `"42"`) or full Bitbucket PR URL |
18
18
  | `diff_base_override` | string \| null | `--diff-base` value from `review-pr` if provided |
19
19
  | `ticket_override` | string \| null | `--ticket` value from `review-pr` if provided |
20
- | `project_slug` | string | From session context |
21
20
  | `ticket_id` | string \| null | From session context |
22
- | `artifact_base_dir` | string | From session context |
21
+ | `ticket_dir` | string \| null | From session context |
23
22
 
24
23
  ## Resolved-output contract
25
24
 
@@ -25,13 +25,13 @@ This skill is the canonical home of the shared review process. `review-pr` invok
25
25
 
26
26
  > **When invoked by `review-pr`:** Steps 1–3 are already complete: `review-pr` already invoked the bundled session-context deriver and the platform delegate resolved `merge_base_sha` and `spec_sources`. Begin at step 4 with these values in scope.
27
27
 
28
- 1. **Get context**: Invoke `node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs` via Bash. The bundle emits the session-context manifest JSON to stdout; extract `default_branch`, `ticket_id`, `ticket_ref`, `scm`, `project_slug`, and `artifact_base_dir` from it.
28
+ 1. **Get context**: Invoke `node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs` via Bash. The bundle emits the session-context manifest JSON to stdout; extract `default_branch`, `ticket_id`, `ticket_ref`, `scm`, and `ticket_dir` from it.
29
29
  2. **Resolve diff base**: If `--diff-base=<ref>` was provided, use `<ref>`; otherwise use `default_branch`. Compute the merge-base SHA once: `git merge-base HEAD <diff-base>`. Use this SHA for the diff command in step 5.
30
30
  3. **Resolve specification sources**: Produce a list of spec sources (each a `{ source_type, label, content, criteria?, provenance, last_updated }` record). `provenance` is `remote` (a live platform fetch, never stale) or `local_snapshot` (a frozen plan-time artifact that can lag the contract); `last_updated` is the source's last-modified timestamp (ISO 8601), or null when the platform does not expose one.
31
31
  - **Explicit `--ticket=<source>`**: Resolve per [ticket source resolution](../_data/ticket-source-resolution.md) and append as a `ticket` source. A fetched platform issue is `remote` with its `updatedAt` as `last_updated`; a file or plain-text source is `local_snapshot` with `last_updated` null when unknown. When the source resolves to a URL, persist it per [Stored ticket URL](../_data/ticket-source-resolution.md#stored-ticket-url). `--spec-source` does not apply on this path.
32
32
  - **Auto-resolve** (when `--ticket` is omitted): Resolve up to two candidates and choose between them.
33
33
  - _Remote candidate_: When `ticket_id` is non-null and resolves to a platform ticket (use `scm` from step 1), fetch the remote issue per [ticket source resolution](../_data/ticket-source-resolution.md#auto-resolve), but substitute the local fallback below for that section's "ask the user" terminal step. Its `last_updated` is the issue's `updatedAt`.
34
- - _Local candidate_: The most recent `*_ticket.md` under `{artifact_base_dir}/projects/{project_slug}/tickets/{ticket_id}/`. Its `last_updated` is the filename's `YYYYMMDD-HHMMSSZ` prefix converted to ISO 8601 (`YYYY-MM-DDTHH:MM:SSZ`), so it shares the remote candidate's format; if the prefix is unparseable, treat the local candidate as unavailable. (The artifact filename keeps the compact form per `artifact-conventions.md`; only the recorded `last_updated` is normalized.) Read its frontmatter as well as its filename: `copies_remote` decides the selection below, per [ticket frontmatter](../_data/artifact-conventions.md#ticket-frontmatter). When the selection chooses it and its frontmatter names a `ticket_ref`, add that remote ticket's comments per [Comments](../_data/ticket-source-resolution.md#comments), taking them from the remote candidate when that fetch succeeded.
34
+ - _Local candidate_: The most recent `*_ticket.md` under `{ticket_dir}/`. Its `last_updated` is the filename's `YYYYMMDD-HHMMSSZ` prefix converted to ISO 8601 (`YYYY-MM-DDTHH:MM:SSZ`), so it shares the remote candidate's format; if the prefix is unparseable, treat the local candidate as unavailable. (The artifact filename keeps the compact form per `artifact-conventions.md`; only the recorded `last_updated` is normalized.) Read its frontmatter as well as its filename: `copies_remote` decides the selection below, per [ticket frontmatter](../_data/artifact-conventions.md#ticket-frontmatter). When the selection chooses it and its frontmatter names a `ticket_ref`, add that remote ticket's comments per [Comments](../_data/ticket-source-resolution.md#comments), taking them from the remote candidate when that fetch succeeded.
35
35
  - _Selection_:
36
36
  - If `--spec-source=remote|local` is set, use that candidate. If the named candidate is unavailable (e.g. `--spec-source=local` without a snapshot, or `--spec-source=remote` with a failed/offline fetch or null `ticket_id`), stop and report the missing source rather than silently using the other side: An explicit instruction must not be redirected to the wrong contract. State the remedy (drop the flag to re-enable recency) in the message.
37
37
  - Otherwise, if a remote candidate exists and the local candidate's frontmatter sets `copies_remote: true`, use the remote candidate. The snapshot's body is a copy of the ticket of record, so the remote contains at least the content that the snapshot froze, and the snapshot's later write time records the copying rather than a newer contract. A snapshot that does not make that claim falls through to the comparison below.
@@ -42,14 +42,15 @@ This skill is the canonical home of the shared review process. `review-pr` invok
42
42
 
43
43
  `review-pr` may pass additional sources (notably the PR description as `pr_description`). The list is the canonical input for the "Specification compliance" section regardless of who populated it.
44
44
 
45
- 4. **Read prior artifacts**: When `ticket_id` is not null, invoke `node {harness_home_dir}/scripts/resolve-review-run.mjs active --ticket-dir {artifact_base_dir}/projects/{project_slug}/tickets/{ticket_id}/` via Bash. The helper prints `{ "runDir": <path or null> }`: the ticket's active run, per [artifact conventions](../_data/artifact-conventions.md#run-directories). When `runDir` is not null, read all artifacts in it chronologically for context (including any prior dispositions).
45
+ 4. **Read prior artifacts**: When `ticket_dir` is not null, invoke `node {harness_home_dir}/scripts/resolve-review-run.mjs active --ticket-dir {ticket_dir}` via Bash. The helper prints `{ "runDir": <path or null> }`: the ticket's active run, per [artifact conventions](../_data/artifact-conventions.md#run-directories). When `runDir` is not null, read all artifacts in it chronologically for context (including any prior dispositions).
46
46
  5. **Analyze changes**: `git diff <merge-base-sha>..HEAD`.
47
47
  6. **Review thoroughly** following the guidelines below.
48
48
  7. **Challenge your own findings**: Re-read each finding and delete every one that you would not defend to a skeptical author asking "why does this matter?" A review may legitimately end with zero findings.
49
- 8. **Assign a score** out of 10.
50
- 9. **Resolve frontmatter fields** before saving; see [Frontmatter resolution](#frontmatter-resolution).
51
- 10. **Save the review** per the [Saving](#saving) section.
52
- 11. **Present next steps**: After saving, present a next-steps prompt following [next-steps options](#next-steps-options). Supply recommendation context: finding counts and categories from the review, which criteria the specification compliance section marked in conflict with the implementation, and the consistency verdict when the consistency section was rendered. The next-steps prompt is interactive output only and is not saved in the review artifact.
49
+ 8. **Reflow over-width comments**: For each comment line that the diff adds or modifies and that exceeds the `max_line_length` that `.editorconfig` sets for its file, reflow the paragraph from that line on, changing only whitespace, and drop any finding that the reflow resolves. Commit the reflows as a new commit, composed per `{skill:create-commit}` with the reflowed paths named, and record each in the review's `## Applied reflows` section. Do not ask first: A reflow does not involve any judgment. Report the line as a finding instead when the review covers a pull request, whose branch belongs to its author, or when its file has uncommitted changes, which the commit would sweep in. A line that whitespace changes cannot bring within the width is neither reflowed nor reported by this step.
50
+ 9. **Assign a score** out of 10.
51
+ 10. **Resolve frontmatter fields** before saving; see [Frontmatter resolution](#frontmatter-resolution).
52
+ 11. **Save the review** per the [Saving](#saving) section.
53
+ 12. **Present next steps**: After saving, present a next-steps prompt following [next-steps options](#next-steps-options). Supply recommendation context: finding counts and categories from the review, which criteria the specification compliance section marked in conflict with the implementation, and the consistency verdict when the consistency section was rendered. The next-steps prompt is interactive output only and is not saved in the review artifact.
53
54
 
54
55
  ## Frontmatter resolution
55
56
 
@@ -121,6 +122,10 @@ The body following the frontmatter has this structure:
121
122
 
122
123
  ### Test quality
123
124
 
125
+ ## Applied reflows
126
+
127
+ {Omit when step 8 did not reflow anything. Otherwise one line per reflowed comment: `path:line`, then the reflow commit's short SHA.}
128
+
124
129
  ## Action required
125
130
 
126
131
  ### FIXMEs 🚨
@@ -169,7 +174,7 @@ The body following the frontmatter has this structure:
169
174
 
170
175
  ## Technical assessment
171
176
 
172
- {Why the change is correct and adequately tested. For a change to a visible component, what the browser check in {rulebook:accessibility-conventions} found, or that it did not run and which elements it would have covered.}
177
+ {Why the change is correct and adequately tested. For a change to a visible component, what the browser checks in {rulebook:accessibility-conventions} and {rulebook:visual-design-conventions} found, or that they did not run and which elements and views they would have covered.}
173
178
 
174
179
  ## Conclusion
175
180
 
@@ -249,7 +254,7 @@ Paraphrasing is not divergence: Evaluate semantic alignment, not textual overlap
249
254
 
250
255
  ### Clean reviews
251
256
 
252
- When a change does not warrant any findings, render it on this shape rather than as empty `### FIXMEs` / "None." scaffolding:
257
+ When a change does not warrant any findings, render it on this shape rather than as empty `### FIXMEs` / "None." scaffolding. A reflow is not a finding, so a review whose only issue was an over-width comment is clean too, with its `## Applied reflows` section above `## Action required`:
253
258
 
254
259
  ```markdown
255
260
  ## Action required
@@ -262,7 +267,7 @@ None.
262
267
 
263
268
  ## Technical assessment
264
269
 
265
- {Why the change is correct and adequately tested. For a change to a visible component, what the browser check in {rulebook:accessibility-conventions} found, or that it did not run and which elements it would have covered.}
270
+ {Why the change is correct and adequately tested. For a change to a visible component, what the browser checks in {rulebook:accessibility-conventions} and {rulebook:visual-design-conventions} found, or that they did not run and which elements and views they would have covered.}
266
271
 
267
272
  ## Conclusion
268
273
 
@@ -284,7 +289,7 @@ The score is an honest, at-a-glance quality signal.
284
289
 
285
290
  ### Path resolution
286
291
 
287
- Use `artifact_base_dir`, `project_slug`, and `ticket_id` from step 1.
292
+ Use `ticket_dir` from step 1.
288
293
 
289
294
  Follow [artifact conventions](../_data/artifact-conventions.md).
290
295
 
@@ -292,8 +297,8 @@ Follow [artifact conventions](../_data/artifact-conventions.md).
292
297
 
293
298
  The review is saved as a run artifact: `{timestamp}_reviewer_review.md`
294
299
 
295
- 1. Resolve ticket directory: `{artifact_base_dir}/projects/{project_slug}/tickets/{ticket_id}/`. When `ticket_id` is null, auto-generate one in the format `{YYYYMMDD}-{4 random hex}` per [artifact conventions](../_data/artifact-conventions.md#ticket-id); never construct a path with a literal `null` segment.
296
- 2. Open the run directory: Invoke `node {harness_home_dir}/scripts/resolve-review-run.mjs open --ticket-dir <ticket-dir> --timestamp <timestamp>` via Bash, passing this review's UTC `YYYYMMDD-HHMMSSZ` timestamp. The helper prints `{ "runDir": "<path>" }`: the ticket's active run, or a new `{timestamp}-interactive` run when the ticket directory does not contain one. On a malformed timestamp it exits non-zero and names the problem on stderr.
300
+ 1. Resolve the ticket directory, `{ticket_dir}`, per {skill:save-artifact}, which states the directory to use when `ticket_dir` is null.
301
+ 2. Open the run directory: Invoke `node {harness_home_dir}/scripts/resolve-review-run.mjs open --ticket-dir {ticket_dir} --timestamp <timestamp>` via Bash, passing this review's UTC `YYYYMMDD-HHMMSSZ` timestamp. The helper prints `{ "runDir": "<path>" }`: the ticket's active run, or a new `{timestamp}-interactive` run when the ticket directory does not contain one. On a malformed timestamp it exits non-zero and names the problem on stderr.
297
302
  3. Save: `{runDir}/{timestamp}_reviewer_review.md`
298
303
 
299
304
  Each review is a separate artifact in the run directory. Do not append to existing files: The chronological sequence of files is the history.
@@ -16,7 +16,7 @@ Evaluation criteria for code review. Apply proportionally: Match depth to risk.
16
16
 
17
17
  - **Correctness**: Logic errors, unhandled error paths, data loss risks
18
18
  - **Data changes**: A change that removes or renames data that deployed code still reads, or that depends on a migration run before merge (see {rulebook:shared-data-conventions})
19
- - **Interfaces**: A change that defines or changes colour tokens, text styles, or a page or UI component (see {rulebook:accessibility-conventions}). For each new or changed interactive element, ask whether it shows that it is interactive, by the states that the rulebook names, and check it in a browser as the rulebook requires rather than by reading the diff alone. For each new or changed list or table, ask whether each state for which its reader scans is visible without reading every item, per the rulebook's glanceable-state rule
19
+ - **Interfaces**: A change that defines or changes colour tokens, text styles, or a page or UI component (see {rulebook:accessibility-conventions}). For each new or changed interactive element, ask whether it shows that it is interactive, by the states that the rulebook names, and check it in a browser as the rulebook requires rather than by reading the diff alone. For each new or changed action whose consequence is not evident from its label, ask whether it explains that consequence at the control, per the rulebook's consequence-at-the-control rule. For each new or changed list or table, ask whether each state for which its reader scans is visible without reading every item, per the rulebook's glanceable-state rule. For each new or changed view, ask whether it meets {rulebook:visual-design-conventions}: padding inside bounded containers, alignment, marks on exceptions only, an appearance that follows each element's role, and the product's identity
20
20
  - **Conventions**: Adherence to codebase patterns and project standards
21
21
  - **Edge cases**: Boundary conditions, empty collections, zero values, undefined states
22
22
  - **Test coverage**: Adequate tests for new functionality; tests that verify behavior and are worth keeping, not just coverage
@@ -17,9 +17,8 @@ This skill does not run a review. The review logic is implemented in `review-bra
17
17
  | `pr_id` | string | PR number (e.g., `"1024"`) or full URL (`"https://github.com/owner/repo/pull/1024"`) |
18
18
  | `diff_base_override` | string \| null | `--diff-base` value from `review-pr` if provided |
19
19
  | `ticket_override` | string \| null | `--ticket` value from `review-pr` if provided |
20
- | `project_slug` | string | From session context |
21
20
  | `ticket_id` | string \| null | From session context |
22
- | `artifact_base_dir` | string | From session context |
21
+ | `ticket_dir` | string \| null | From session context |
23
22
 
24
23
  ## Resolved-output contract
25
24
 
@@ -22,7 +22,7 @@ This is a thin entry skill: The shared review logic (diff analysis, finding gene
22
22
 
23
23
  ### 1. Get session context
24
24
 
25
- Invoke `node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs` via Bash. The bundle emits the session-context manifest JSON to stdout; extract `project_slug`, `ticket_id`, `ticket_ref`, `default_branch`, `artifact_base_dir`, `scm`, and `pr_url` from it. Pass these values into `review-branch`'s steps 4–9 (review header, scoring, saving) so that `review-branch`'s own step 1 does not need to re-run.
25
+ Invoke `node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs` via Bash. The bundle emits the session-context manifest JSON to stdout; extract `ticket_id`, `ticket_ref`, `default_branch`, `ticket_dir`, `scm`, and `pr_url` from it. Pass these values into `review-branch`'s steps 4–11 (review header, scoring, saving) so that `review-branch`'s own step 1 does not need to re-run.
26
26
 
27
27
  ### 2. Resolve the PR
28
28
 
@@ -55,9 +55,8 @@ Pass the following inputs to the selected delegate per its delegate interface:
55
55
  | `pr_id` | The PR resolved in step 2. The delegate parses and normalizes it (extracts the PR number from a URL when applicable; the Bitbucket delegate also resolves the workspace and repository that it addresses). |
56
56
  | `diff_base_override` | Value of `--diff-base` if provided; otherwise `null` |
57
57
  | `ticket_override` | Value of `--ticket` if provided; otherwise `null` |
58
- | `project_slug` | From session context |
59
58
  | `ticket_id` | From session context |
60
- | `artifact_base_dir` | From session context |
59
+ | `ticket_dir` | From session context |
61
60
 
62
61
  The delegate returns a resolved-input record:
63
62