codeassembly-guidance 0.5.0 → 0.7.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 (110) hide show
  1. package/.meta/changelog.json +491 -0
  2. package/CHANGELOG.md +118 -0
  3. package/README.md +33 -4
  4. package/content/_partials/finding-grades.md +4 -0
  5. package/content/_partials/kb-unsearched-private-stores.md +6 -0
  6. package/content/codeassembly-content.yaml +4 -0
  7. package/content/collections/recommended.md +5 -2
  8. package/content/guidance/_harnesses/rovo/AGENTS.md +0 -1
  9. package/content/guidance/rulebooks/accessibility-conventions.md +26 -6
  10. package/content/guidance/rulebooks/cli-conventions.md +17 -2
  11. package/content/guidance/rulebooks/codeassembly-content-specification.md +11 -11
  12. package/content/guidance/rulebooks/live-worktree-policy.md +2 -2
  13. package/content/guidance/rulebooks/machine-readable-output-conventions.md +85 -0
  14. package/content/guidance/rulebooks/ui-copy-conventions.md +2 -2
  15. package/content/guidance/rulebooks/williamthorsen-collaboration-preferences.md +10 -10
  16. package/content/guidance/rulebooks/williamthorsen-ticketing-preferences.md +3 -1
  17. package/content/guidance/rulebooks/williamthorsen-typescript-preferences.md +7 -3
  18. package/content/guidance/rulebooks/williamthorsen-workflow-preferences.md +3 -1
  19. package/content/guidance/rulebooks/williamthorsen-writing-preferences.md +5 -5
  20. package/content/guidance/shared/AGENTS.md +1 -1
  21. package/content/scripts/check-prose.mjs +1 -1
  22. package/content/scripts/describe-change.mjs +88 -88
  23. package/content/scripts/manage-jira-ticket.mjs +113 -113
  24. package/content/scripts/select-lede-exemplars.mjs +85 -85
  25. package/content/scripts/validate-preferences.mjs +38 -38
  26. package/content/skills/_data/action-items.md +2 -2
  27. package/content/skills/_data/artifact-conventions.md +20 -10
  28. package/content/skills/_data/concision.md +1 -1
  29. package/content/skills/_data/entry-points.md +37 -0
  30. package/content/skills/_data/project-stage.md +9 -5
  31. package/content/skills/_data/recommendation-gradient.md +6 -6
  32. package/content/skills/_data/spike-conventions.md +20 -7
  33. package/content/skills/_data/ticket-source-resolution.md +21 -4
  34. package/content/skills/_data/title-templates.md +4 -4
  35. package/content/skills/_partials/commit-title-rendering.md +2 -1
  36. package/content/skills/_partials/implementation-order-list.md +27 -0
  37. package/content/skills/_partials/next-steps-after-plan.md +6 -5
  38. package/content/skills/_partials/option-format.md +8 -8
  39. package/content/skills/_partials/plan-template.md +5 -1
  40. package/content/skills/_partials/resolve-plan-and-ticket.md +22 -0
  41. package/content/skills/_partials/split-launch-prompts.md +2 -2
  42. package/content/skills/_partials/ticket-criteria-conventions.md +2 -0
  43. package/content/skills/align-ticket-with-implementation/SKILL.md +1 -1
  44. package/content/skills/analyze-performance/SKILL.md +102 -0
  45. package/content/skills/analyze-performance/analyze-performance.mjs +70 -0
  46. package/content/skills/assess-code-health/SKILL.md +16 -14
  47. package/content/skills/assess-code-health/assess-code-health.mjs +29 -28
  48. package/content/skills/assess-usability/SKILL.md +5 -3
  49. package/content/skills/capture-event/SKILL.md +20 -11
  50. package/content/skills/capture-event/capture-event.mjs +122 -122
  51. package/content/skills/capture-feedback/SKILL.md +2 -1
  52. package/content/skills/capture-lede-decision/capture-lede-decision.mjs +97 -97
  53. package/content/skills/convert-agent-prompt/SKILL.md +60 -0
  54. package/content/skills/create-commit/SKILL.md +10 -5
  55. package/content/skills/create-pr/SKILL.md +11 -11
  56. package/content/skills/create-ticket/SKILL.md +1 -0
  57. package/content/skills/create-ticket/resolve-ticket-target.mjs +92 -92
  58. package/content/skills/curate-feedback/curate-feedback.mjs +82 -82
  59. package/content/skills/derive-session-context/derive-session-context.mjs +107 -107
  60. package/content/skills/design-and-plan/SKILL.md +6 -4
  61. package/content/skills/implement-plan/SKILL.md +4 -29
  62. package/content/skills/implementation-order/implementation-order.mjs +67 -0
  63. package/content/skills/index-prototypes/SKILL.md +36 -17
  64. package/content/skills/index-prototypes/index-prototypes.mjs +14 -14
  65. package/content/skills/investigate-spike/SKILL.md +48 -0
  66. package/content/skills/kb-add/SKILL.md +12 -3
  67. package/content/skills/kb-add/kb-add.mjs +88 -88
  68. package/content/skills/kb-curate/kb-curate.mjs +88 -88
  69. package/content/skills/kb-edit/kb-edit.mjs +90 -90
  70. package/content/skills/kb-retrieve/SKILL.md +8 -3
  71. package/content/skills/kb-retrieve/kb-retrieve.mjs +104 -104
  72. package/content/skills/kb-retrieve-events/SKILL.md +8 -3
  73. package/content/skills/kb-retrieve-events/kb-retrieve-events.mjs +113 -113
  74. package/content/skills/kb-update-events/kb-update-events.mjs +92 -92
  75. package/content/skills/lesson-clusters/lesson-clusters.mjs +102 -102
  76. package/content/skills/list-implementation-order/SKILL.md +23 -0
  77. package/content/skills/merge-bb-pr/SKILL.md +31 -8
  78. package/content/skills/merge-gh-pr/SKILL.md +25 -12
  79. package/content/skills/merge-gh-pr/merge-gh-pr.mjs +13 -8
  80. package/content/skills/merge-pr/SKILL.md +55 -20
  81. package/content/skills/migrate-feedback-memories/SKILL.md +1 -0
  82. package/content/skills/plan/SKILL.md +3 -1
  83. package/content/skills/prepare-prototype-brief/SKILL.md +20 -14
  84. package/content/skills/refine-plan/SKILL.md +9 -4
  85. package/content/skills/refine-prototype/SKILL.md +5 -5
  86. package/content/skills/review-branch/SKILL.md +8 -8
  87. package/content/skills/review-criteria/SKILL.md +4 -4
  88. package/content/skills/review-gh-pr/SKILL.md +1 -1
  89. package/content/skills/revise-prose/SKILL.md +9 -8
  90. package/content/skills/revise-prose/revise-prose.mjs +111 -111
  91. package/content/skills/save-plan/SKILL.md +2 -0
  92. package/content/skills/start-ticket/SKILL.md +27 -0
  93. package/content/skills/streamline-guidance/streamline-guidance.mjs +76 -76
  94. package/content/skills/summarize-change/SKILL.md +27 -9
  95. package/content/skills/testing-conventions/SKILL.md +14 -3
  96. package/content/skills/triage-feedback/SKILL.md +4 -0
  97. package/content/skills/triage-spike-findings/SKILL.md +36 -12
  98. package/content/skills/typescript-testing-conventions/SKILL.md +40 -0
  99. package/content/skills/wrap-up/SKILL.md +4 -0
  100. package/content/subagents/_data/claude.yaml +3 -0
  101. package/content/subagents/code-health-assessor.md +4 -4
  102. package/content/subagents/disposition-challenger.md +3 -4
  103. package/content/subagents/entry-drafter.md +2 -2
  104. package/content/subagents/handoff-reviewer.md +1 -1
  105. package/content/subagents/prototype-builder.md +69 -0
  106. package/content/subagents/usability-assessor.md +1 -1
  107. package/package.json +11 -10
  108. package/schemas/preferences.v1.json +74 -8
  109. package/schemas/work-types.v1.json +1 -1
  110. package/content/guidance/_harnesses/rovo/codeassembly-guidance.md +0 -4
@@ -31,9 +31,8 @@ Before every {tool:Task} call and after every phase completion, output a status
31
31
  1. Read the plan file. If not found, report an error and stop.
32
32
  2. Parse YAML frontmatter from the plan content. If a `provenance` block is present, store it as `{input-provenance}`. If the plan does not have frontmatter or a `provenance` block, set `{input-provenance}` to empty.
33
33
  3. Resolve the ticket source:
34
- - GitHub URL (`github.com/.../issues/...`) -> use `gh issue view --json title,body,blockedBy {url}` via Bash to fetch content.
35
- - File path -> Read the file.
36
- - Jira URL or key -> Fetch per the Jira entry in [platform-specific fetch](../_data/ticket-source-resolution.md#platform-specific-fetch).
34
+ - GitHub URL (`github.com/.../issues/...`), Jira URL, or Jira key -> Fetch the body and the comments per [platform-specific fetch](../_data/ticket-source-resolution.md#platform-specific-fetch).
35
+ - File path -> Read the file, then read its remote comments per [Comments](../_data/ticket-source-resolution.md#comments).
37
36
  - Other URL -> Fetch the URL content.
38
37
 
39
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.
@@ -161,7 +160,7 @@ Run `{harness_home_dir}/scripts/resolve-frontmatter.sh --format json` via Bash.
161
160
 
162
161
  The `provenance:` block is **not** populated from the script. Construct it manually per the case branches below.
163
162
 
164
- **Round-trip preservation:** The top-level canonical fields (`branch`, `commit`, etc.) are always re-resolved from current session context via the script; they are not copied from `{input-provenance}`. This is correct: The output is a new artifact at a new point in time on a potentially different branch. The `provenance:` block's camelCase convention (`baseSha`, `isInteractive`, `refinedBy`) is preserved as-is on both read and write; the keys are not renamed. Provenance fields copied from the input are `skill`, `baseSha`, `isInteractive`, and `iteration` (per the case branches).
163
+ **Round-trip preservation:** The top-level canonical fields (`branch`, `commit`, etc.) are always re-resolved from current session context via the script; they are not copied from `{input-provenance}`. This is correct: The output is a new artifact at a new point in time on a potentially different branch. The `provenance:` block's camelCase convention (`baseSha`, `isInteractive`, `refinedBy`) is preserved as-is on both read and write; the keys are not renamed. Provenance fields copied from the input are `skill`, `baseSha`, `isInteractive`, and `iteration` (per the case branches). `parent` is not copied: It is set from the input plan's file name, so that each revision names its own predecessor.
165
164
 
166
165
  **When `{input-provenance}` is non-empty:**
167
166
 
@@ -170,6 +169,7 @@ The `provenance:` block is **not** populated from the script. Construct it manua
170
169
  3. Construct updated provenance:
171
170
  - `skill`: Preserve from `{input-provenance}` (the original authoring skill)
172
171
  - `refinedBy`: Set to `refine-plan`
172
+ - `parent`: The file name of `{plan_path}`, without its directory
173
173
  - `timestamp`: Use the script's `timestamp`
174
174
  - `baseSha`: The script's value (or preserved original)
175
175
  - `isInteractive`: Preserve from `{input-provenance}` if present
@@ -181,6 +181,7 @@ The `provenance:` block is **not** populated from the script. Construct it manua
181
181
  provenance:
182
182
  skill: design-and-plan
183
183
  refinedBy: refine-plan
184
+ parent: 20260309-140000Z_example_plan.md
184
185
  timestamp: 2026-03-10T08:00:00Z
185
186
  baseSha: abc123def456...
186
187
  isInteractive: true
@@ -201,6 +202,7 @@ The `provenance:` block is **not** populated from the script. Construct it manua
201
202
  3. Construct provenance:
202
203
  - `skill`: `unknown`
203
204
  - `refinedBy`: `refine-plan`
205
+ - `parent`: The file name of `{plan_path}`, without its directory
204
206
  - `timestamp`: Script's value
205
207
  - `baseSha`: Script's value (omit when absent)
206
208
  - `isInteractive`: Always `true`. `refine-plan` is an interactive user-invocable skill: When it stamps a plan without prior provenance, the stamp itself is always produced inside that interactive session.
@@ -212,6 +214,7 @@ The `provenance:` block is **not** populated from the script. Construct it manua
212
214
  provenance:
213
215
  skill: unknown
214
216
  refinedBy: refine-plan
217
+ parent: 20260309-140000Z_example_plan.md
215
218
  timestamp: 2026-03-10T08:00:00Z
216
219
  baseSha: abc123def456...
217
220
  isInteractive: true
@@ -261,3 +264,5 @@ Follow the options, output format, and recommendation rules in [next-steps optio
261
264
  <!-- include: ../_partials/next-steps-after-plan.md / -->
262
265
 
263
266
  <!-- include: ../_partials/option-format.md / -->
267
+
268
+ <!-- include: ../_partials/implementation-order-list.md / -->
@@ -29,8 +29,8 @@ Off:
29
29
  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
- - 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.
33
- - {rulebook:accessibility-conventions} is the floor: Check contrast and size when a command changes a colour or a text size.
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.
34
34
  - A new string on the product surface follows {rulebook:ui-copy-conventions}.
35
35
  - One working file. A batch edits it in place; a fork is written next to it and is deleted once the developer picks.
36
36
 
@@ -48,7 +48,7 @@ node {harness_home_dir}/skills/index-prototypes/index-prototypes.mjs resolve-ids
48
48
  --slugs {slug}
49
49
  ```
50
50
 
51
- Copy the base's latest source to `{scratch_dir}/{slug}-v{n}.html`, the working file, and set the band's first line to the new id. A base reconstructed from a built product takes a new slug and starts at version 1, and its band's first line names the source after the id, such as `6.1 Start from as tabs, from the api-tokens page`.
51
+ Copy the base's latest source to `{scratch_dir}/{slug}-v{n}.html`, the working file, and set the band's first line and the `<title>` to the new id. A base reconstructed from a built product takes a new slug and starts at version 1, and its band's first line names the source after the id, such as `6.1 Start from as tabs, from the api-tokens page`. When the manifest does not have a set title yet, choose one per {skill:index-prototypes} "The set", and pass it as `--set-title` when the first snapshot is registered.
52
52
 
53
53
  ### 2. Serve the working file
54
54
 
@@ -78,7 +78,7 @@ Each turn, take every command in the developer's message as one batch:
78
78
  4. Append each applied command to the session's log, under the id of the version that it will enter, with the developer's reason when they gave one and the source id when it was a transplant.
79
79
  5. Reply with one line per command (applied, forked with its letters and their URLs, or refused with the reason), and nothing else. The developer looks at the browser, not at a description of it.
80
80
 
81
- Propose a new number when a batch replaces the layout or the model to the point that the earlier version's verdicts and notes no longer describe the page. On yes, the working file takes a new slug and the id that `resolve-ids` gives it, and its band names the version from which it came. The old slug keeps its last snapshot.
81
+ Propose a new number when a batch replaces the layout or the model to the point that the earlier version's verdicts and notes no longer describe the page. On yes, the working file takes a new slug and the id that `resolve-ids` gives it in its band and its `<title>`, and its band names the version from which it came. The old slug keeps its last snapshot.
82
82
 
83
83
  ### 5. Snapshot
84
84
 
@@ -88,7 +88,7 @@ Snapshot when the developer asks for one, in any words ("snapshot", "keep this",
88
88
  2. Publish it with the Artifact tool: to the slug's existing artifact URL when the manifest's latest entry for the slug has one, so that the index card's link stays current, or as a new artifact for a new slug.
89
89
  3. Capture its screenshots per {skill:index-prototypes} step 3, and register it per its step 4 with `--number {number}`, `--source`, the set's note labels (copied from the latest entry, with any change that the batches made to them), and, for a new slug, a `--description` that names the version from which it came.
90
90
  4. Update the set's summary per {skill:index-prototypes} step 5, naming the version in `changes`, then render and republish the index per its step 6.
91
- 5. The next batch opens the next version: Copy the snapshot to `{scratch_dir}/{slug}-v{n+1}.html` and set the band's id.
91
+ 5. The next batch opens the next version: Copy the snapshot to `{scratch_dir}/{slug}-v{n+1}.html` and set the band's id and the `<title>`.
92
92
 
93
93
  ### 6. Close
94
94
 
@@ -31,7 +31,7 @@ This skill is the canonical home of the shared review process. `review-pr` invok
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).
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.
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.
@@ -304,13 +304,13 @@ The next-steps block has four independent sub-blocks. Each is shown only when it
304
304
 
305
305
  Use `~/`-relative paths when possible and absolute paths otherwise. Every line subordinate to an option (invocation guidance as much as a pro or con) is a nested list item, never a whitespace-indented continuation; see [option format](#option-format).
306
306
 
307
- **Naming a skill in the render.** Name a skill in the rendered option only when the user must carry the invocation across a session boundary: clearing context, handing off to another session, or waiting for someone else to act. When the agent runs the skill in the current session, the skill name appears in the sub-block's Options table and the rendered line is a bare action. This limits each rendered line to the step that the user performs.
307
+ **Naming a skill in the render.** Name a skill in the rendered option only when the user must run the invocation after a session boundary: clearing context, handing off to another session, or waiting for someone else to act. When the agent runs the skill in the current session, the skill name appears in the sub-block's Options table and the rendered line is a bare action. This limits each rendered line to the step that the user performs.
308
308
 
309
309
  **Reviewer and author roles.** A review reports findings; the author disposes of them. The options below send the reviewer's output to the author or record what the review found; they never ask the reviewer to re-design, re-plan, or coordinate a workflow, none of which is the reviewer's job.
310
310
 
311
311
  ### Proposed-edit preview
312
312
 
313
- Three of the sub-blocks below offer options that rewrite an artifact, one each: the Deviations sub-block rewrites the ticket's acceptance criteria, the source-divergence sub-block rewrites the PR description, and the Findings sub-block rewrites the source. The user consents to that rewrite by picking a number, so every such option renders a preview of the edit that it would make. The reviewer judges which criteria are genuinely in conflict with the implementation and which findings name a change that it can carry out; the preview makes those judgments reviewable instead of silent.
313
+ Three of the sub-blocks below offer options that rewrite an artifact, one each: the Deviations sub-block rewrites the ticket's acceptance criteria, the source-divergence sub-block rewrites the PR description, and the Findings sub-block rewrites the source. The user consents to that rewrite by picking a number, so every such option renders a preview of the edit that it would make. The reviewer judges which criteria are genuinely in conflict with the implementation and which findings name a change that it can make; the preview makes those judgments reviewable instead of silent.
314
314
 
315
315
  **Placement.** The preview renders above the numbered options, inside its sub-block, under a `Proposed edit to the {target}:` label naming what it would change; the source target's label is plural, `Proposed edits to the source:`, because it covers every open finding. Option lines stay bare actions: The preview is never a pro, a con, or a line nested beneath an option. An option that mutates nothing, such as "Leave as-is", does not render a preview.
316
316
 
@@ -318,9 +318,9 @@ Ticket and PR-description deltas render as a flat list, one line per change. Sou
318
318
 
319
319
  **Notation.** The preview is a delta. It never restates the ticket, the PR description, or a finding's Recommendation, which would duplicate the artifact in the terminal, and it contains one entry per change:
320
320
 
321
- - **Ticket targets** derive their delta from the in-conflict criteria rows of `## Specification compliance`'s ticket subsection, and from nothing else. Unplanned work is never a source: Implementation that goes beyond the criteria is not a deviation, so it does not yield a line. Because a ticket's `## Problem`, `## Context`, and `## Proposed solution` record what was known and proposed when it was written, this menu does not offer an edit that changes them; a divergence between one of them and the implementation is reported in the PR description instead.
321
+ - **Ticket targets** derive their delta from the in-conflict criteria rows of `## Specification compliance`'s ticket subsection, and from nothing else. Unplanned work is never a source: Implementation that goes beyond the criteria is not a deviation, so it does not yield a line. Because a ticket's `## Problem`, `## Context`, and `## Proposed solution` record what was known and proposed when it was written, this menu does not offer an edit that changes them; a divergence between one of them and the implementation goes into the PR description's `## Notes for reviewers` instead, and only when it changes what a reviewer checks, per the reader test that `summarize-change` states.
322
322
  - `Reword: {old} → {new}` for a criterion whose direction the implementation deliberately contradicts
323
- - `Drop: {criterion}` for a criterion that the implementation deliberately abandoned, never for one that it has not yet reached
323
+ - `Drop: {criterion}` for a criterion that the implementation deliberately abandoned, never for one that it has not yet met
324
324
  - **PR-description targets** render the concrete claim changes, each keyed to the divergent `D{n}` row from which it came: `D2: {claim as written} → {claim as built}`.
325
325
  - **Source targets** derive their delta from the open findings, one entry per finding, keyed to its ID. An entry states two things: the surface that the change touches (source, test, comment, docs, config) and the substance of the edit. Its form follows the edit's own granularity rather than a fixed notation, so a literal single-site edit is a `{old} → {new}` clause, many sites sharing one edit are a table captioned with what is invariant across its rows, and a structural edit is a prose clause naming the shape of the resulting diff. A code snippet is one rendering among these, never the required form.
326
326
  - When an entry covers several sites and deliberately leaves one of them alone, it names that site with the reason. The entry states its own boundary rather than leaving the reader to infer it from silence.
@@ -331,7 +331,7 @@ Do not render an exclusions line. A criterion genuinely arguable as in conflict
331
331
 
332
332
  **Open findings.** When a ticket or PR-description delta line would settle or obviate an open finding, follow it with a sibling `⚠️` list item naming that finding, so that the user can see that accepting the edit pre-empts the finding's disposition. Those preview lists stay flat; nothing nests beneath a delta line.
333
333
 
334
- **The preview is the contract.** The edit executed is the edit previewed. When carrying it out reveals a change that the preview did not contain, stop and re-confirm with the new line shown; never widen the edit under consent already given.
334
+ **The preview is the contract.** The edit executed is the edit previewed. If making the edit reveals a change that the preview did not contain, stop and re-confirm with the new line shown; never widen the edit under consent already given.
335
335
 
336
336
  **Empty delta.** When the judgment drops every line, the Deviations sub-block has nothing to propose and does not render at all; see its [trigger](#deviations-sub-block). When a source divergence proposes a PR-description edit, that delta is never empty, because a divergence that the implementation resolves in the ticket's favor always leaves a claim to reconcile.
337
337
 
@@ -413,7 +413,7 @@ Every case that renders offers both, so the pair is fixed; what varies by case i
413
413
 
414
414
  #### Output format
415
415
 
416
- Render the list per [option format](#option-format). Each option has a marker (■■■/■■□/■□□/□□□); the recommendation rules below determine which option takes the strongest marker per case. Option 1 renders its PR-description delta above the list, per [proposed-edit preview](#proposed-edit-preview); "Leave as-is" has none. Pros and cons are omitted by default; add a `➕` or `➖` line only when the specific divergence presents a tradeoff that survives the option-format tests (e.g., "the diverging AC was load-bearing for adjacent work that has already shipped"). Generic restatements are noise and must be omitted. That default applies to pros and cons alone: It never suppresses the proposed-edit preview, which is required content.
416
+ Render the list per [option format](#option-format). Each option has a marker (■■■/■■□/■□□/□□□); the recommendation rules below determine which option takes the strongest marker per case. Option 1 renders its PR-description delta above the list, per [proposed-edit preview](#proposed-edit-preview); "Leave as-is" has none. Pros and cons are omitted by default; add a `➕` or `➖` line only when the specific divergence presents a tradeoff that survives the option-format tests (e.g., "the diverging AC was load-bearing for adjacent work that has already been merged"). Generic restatements are noise and must be omitted. That default applies to pros and cons alone: It never suppresses the proposed-edit preview, which is required content.
417
417
 
418
418
  Case 2 (implementation matches ticket; PR description is the stale source):
419
419
 
@@ -457,7 +457,7 @@ The trigger does not include a tier condition; do not reintroduce one. Every fin
457
457
 
458
458
  Stating the trigger as a list of tiers is the failure that this rule replaces: An enumeration goes stale the next time the finding scheme changes, and silently withdraws the menu from whichever tier it omits.
459
459
 
460
- Legacy (`-L`) findings trigger the sub-block on the same terms, with the full option pool. Do not trim the author hand-offs for a legacy-only review: That would leave implementing-in-place as the only route and forfeit the adversarial second look, which pre-existing code needs at least as much as authored code, since a legacy fix is not constrained by any ticket criterion or supported by any design discussion. The recommendation rules handle legacy findings without a carve-out: A legacy fix naming a single change satisfies rule 2 like any other, and one leaving its choice to the author falls through to a ticket or a hand-off.
460
+ Legacy (`-L`) findings trigger the sub-block on the same terms, with the full option pool. Do not trim the author hand-offs for a legacy-only review: That would leave implementing-in-place as the only option and forfeit the adversarial second look, which pre-existing code needs at least as much as authored code, since a legacy fix is not constrained by any ticket criterion or supported by any design discussion. The recommendation rules handle legacy findings without a carve-out: A legacy fix naming a single change satisfies rule 2 like any other, and one leaving its choice to the author falls through to a ticket or a hand-off.
461
461
 
462
462
  The option set depends on whether the review covers a pull request. Select the variant by the review that the agent just produced: A `review-pr` run has a PR reference in the review header and a PR-description spec source, and its author is typically someone else; a `review-branch` run has neither, and its code is typically our own.
463
463
 
@@ -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
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
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
@@ -87,7 +87,7 @@ Two defects against the placement rules in the `testing-conventions` skill are W
87
87
 
88
88
  The same defects in tests that the change neither adds nor supersedes are Legacy.
89
89
 
90
- ## Database tests and setup cost
90
+ ## Database tests and expensive setup
91
91
 
92
92
  Three defects against the database and setup rules in the `testing-conventions` skill are Warnings:
93
93
 
@@ -101,7 +101,7 @@ The same defects in tests that the change does not add, split, or modify are Leg
101
101
 
102
102
  Two defects against the test-data and timeout rules in the `testing-conventions` skill are Warnings:
103
103
 
104
- - **A raised timeout.** The change raises a hook's, a test's, or a tier's timeout, in a test or in config. The proposed change reduces the work by the fixes that the skill names. A reason stated in the plan or the pull-request description does not exempt the raise: Check the reason against those fixes, and report the finding when one of them still applies.
104
+ - **A raised timeout.** The change raises a hook's, a test's, or a tier's timeout, in a test or in config. The proposed change reduces the work by the fixes that the skill names. A reason stated in the plan or in the pull-request description's `## Notes for reviewers` does not exempt the raise: Check the reason against those fixes, and report the finding when one of them still applies.
105
105
  - **A test that renders or builds production-scale data.** The proposed change passes the smallest data that proves the behavior, and makes the data injectable when the code under test reads it from a module-level singleton, even when the singleton is in code that the change does not touch. The diff does not show the data's size, so read what the code under test imports.
106
106
 
107
107
  The same defects in tests and config that the change does not add or modify are Legacy.
@@ -119,7 +119,7 @@ A change that adds to what every session loads is a Warning unless nearly every
119
119
  Conventions for how findings reference files and code locations.
120
120
 
121
121
  1. **Repo-relative path required when localizable.** When a finding refers to specific code, the `- **Location:** ` line must be the first bullet under the finding heading, with a repo-relative path. Example: `packages/devtools-panel/config/renderReleaseNotesHtml.ts:69-76`, not `renderReleaseNotesHtml.ts:69-76`.
122
- 2. **Multi-range syntax.** Multiple ranges or single lines in the same file concatenate with comma separation, dropping the path on subsequent entries: `path/to/file.ts:42, :69-76, :152-155`.
122
+ 2. **Multi-range syntax.** Join multiple ranges or single lines in the same file with commas, dropping the path on subsequent entries: `path/to/file.ts:42, :69-76, :152-155`.
123
123
  3. **Multiple files.** Findings that span multiple files use one `- **Location:** ` bullet per file.
124
124
  4. **Prose may abbreviate after the canonical reference.** Once `Location:` establishes the path, the Description and Recommendation may refer to the file by basename.
125
125
 
@@ -98,7 +98,7 @@ Apply this cascade in order and use the first match:
98
98
  node {harness_home_dir}/skills/review-gh-pr/select-pr-ticket.mjs < {pr_json}
99
99
  ```
100
100
 
101
- It prints `{"number": <n or null>, "source": "<source>"}`. `source` is `closing-reference` (the first entry in `closingIssuesReferences`), `body-keyword` or `body-bare` (the earliest issue reference in the body outside code), or `none`, with `number` null. When `number` is not null, fetch the issue via `gh issue view --json number,title,body,labels,updatedAt {number}` and use it. When the helper exits non-zero, report its stderr and stop.
101
+ It prints `{"number": <n or null>, "source": "<source>"}`. `source` is `closing-reference` (the first entry in `closingIssuesReferences`), `body-keyword` or `body-bare` (the earliest issue reference in the body outside code), or `none`, with `number` null. When `number` is not null, fetch the issue per [platform-specific fetch](../_data/ticket-source-resolution.md#platform-specific-fetch) and use it. When the helper exits non-zero, report its stderr and stop.
102
102
 
103
103
  3. **No ticket**: When `source` is `none`, proceed with the PR description as the only spec source.
104
104
 
@@ -14,12 +14,13 @@ Apply is the default. `--dry-run` produces the report alone.
14
14
 
15
15
  ## Arguments
16
16
 
17
- | Argument | Description | Required |
18
- | ------------------------ | ------------------------------------------------------------------------------- | -------- |
19
- | `<path>` | One or more files or directories narrowing the sweep. Repeatable. | No |
20
- | `--batch-budget <bytes>` | Ceiling on a batch's combined file bytes. Passed to the helper unchanged. | No |
21
- | `--dry-run` | Report and stop without dispatching a subagent, editing, or writing the record. | No |
22
- | `--rule <id>` | One rule that this document declares, narrowing the sweep. Repeatable. | No |
17
+ | Argument | Description | Required |
18
+ | ------------------------ | --------------------------------------------------------------------------------- | -------- |
19
+ | `<path>` | One or more files or directories narrowing the sweep. Repeatable. | No |
20
+ | `--batch-budget <bytes>` | Ceiling on a batch's combined file bytes. Passed to the helper unchanged. | No |
21
+ | `--dry-run` | Report and stop without dispatching a subagent, editing, or writing the record. | No |
22
+ | `--resweep` | Sweep every file again, whatever coverage the record lists. Passed to the helper. | No |
23
+ | `--rule <id>` | One rule that this document declares, narrowing the sweep. Repeatable. | No |
23
24
 
24
25
  Without a path, the sweep covers the whole repository. That is this skill's default, because removing every violation from a repository requires a full sweep. It is how this skill differs from `{skill:revise-comments}`, whose default is the current branch's diff.
25
26
 
@@ -61,7 +62,7 @@ node {harness_home_dir}/skills/revise-prose/revise-prose.mjs detect {paths} \
61
62
  --rule {unversioned-rule-id}={slug}
62
63
  ```
63
64
 
64
- Pass one `--unit` per unit from step 1, and one `--rule` per rule that step 1 kept: `--rule plain-speech@{version}=plain-speech` for `plain-speech`, `--rule {id}@{rule-version}={unit}` for a rule whose marker declares a version, and `--rule {id}={unit}` for a rule whose marker declares none. Pass nothing for a rule that does not have a marker or whose block is not a unit, as step 1 directs. Add `--batch-budget {bytes}` if the invocation included one. Omit the paths for a whole-repository sweep.
65
+ Pass one `--unit` per unit from step 1, and one `--rule` per rule that step 1 kept: `--rule plain-speech@{version}=plain-speech` for `plain-speech`, `--rule {id}@{rule-version}={unit}` for a rule whose marker declares a version, and `--rule {id}={unit}` for a rule whose marker declares none. Pass nothing for a rule that does not have a marker or whose block is not a unit, as step 1 directs. Add `--batch-budget {bytes}` if the invocation included one. Add `--resweep` if the invocation included it: The helper then lists every versioned rule as `unswept` in every batch, and recorded rejections still suppress their sites. Omit the paths for a whole-repository sweep.
65
66
 
66
67
  The helper prints one JSON object to stdout. On success it contains `ok: true`, the `root` that it swept, a `candidates` array, a `rejections` array containing the sites already adjudicated by an earlier sweep, a `batches` array in which each batch lists as `unswept` the versioned rules that its files still need, a `rules` object listing the named rules that it `detected` and those for which it does not have a detector as `undetected`, and a `summary`. On failure it contains `ok: false` with `invalid-args`, `invalid-record`, or `not-a-repository`, the last because the sweep reads what git tracks and has nothing to read outside a working tree. Report a failure and stop.
67
68
 
@@ -77,7 +78,7 @@ An empty `batches` array ends the run: Report the summary in one line and stop.
77
78
 
78
79
  ### 3. Pilot the first batch
79
80
 
80
- Run the pilot if `.agents/revise-prose.yaml` is absent, or if it names none of this run's versioned rules under `rules:` and none of its units under `units:`. A rerun skips this step and goes to step 4.
81
+ Run the pilot if `.agents/revise-prose.yaml` is absent, or if it names none of this run's versioned rules under `rules:` and none of its units under `units:`. A rerun, including a run under `--resweep`, skips this step and goes to step 4.
81
82
 
82
83
  Dispatch batch 0 alone, per step 4's dispatch shape, and run step 4's checks over it as a wave of one. Accumulate its `rejected` and `questionable` entries for step 5, as step 4 directs for every later wave, so that the pilot's questionables appear in the closing table. Then show the user its report and `git diff --stat`, and ask for a go-ahead before committing that batch and before dispatching anything else.
83
84