@tamsensedev/runner 0.13.0 → 0.18.0

package/library/skills/accessibility/references/wcag-checks.md

@@ -1,168 +1,168 @@
-# WCAG 2.2 checks, patterns and scripts
-
-Read this when you need the exact criterion for a finding, a correct markup pattern for a fix, a contrast calculation, or the keyboard pass for the headless check.
-
-## Level A and AA criteria that matter most for web apps
-
-| Criterion | Level | What to check |
-|---|---|---|
-| 1.1.1 Non-text Content | A | Alt text on meaningful images, names on icon buttons, `alt=""` on decorative images |
-| 1.2.2 Captions (Prerecorded) | A | Videos with speech have captions |
-| 1.3.1 Info and Relationships | A | Headings, lists, tables, labels and groups exist in markup, not only in styling |
-| 1.3.2 Meaningful Sequence | A | DOM order matches reading order (CSS `order` and grid placement can break it) |
-| 1.3.5 Identify Input Purpose | AA | `autocomplete` on fields about the user |
-| 1.4.1 Use of Color | A | Colour is not the only way information is shown |
-| 1.4.3 Contrast (Minimum) | AA | 4.5:1 text, 3:1 large text (24 px, or 18.66 px bold) |
-| 1.4.4 Resize Text | AA | Usable at 200% zoom |
-| 1.4.10 Reflow | AA | No two-dimensional scrolling at 320 CSS px wide (except maps, tables, editors) |
-| 1.4.11 Non-text Contrast | AA | 3:1 for control boundaries, focus indicators, meaningful icons and graphics |
-| 1.4.12 Text Spacing | AA | No clipped text when line and letter spacing increase (avoid fixed heights on text boxes) |
-| 1.4.13 Content on Hover or Focus | AA | Tooltips and popovers can be dismissed (Escape), hovered and stay until dismissed |
-| 2.1.1 Keyboard | A | Every function works with the keyboard |
-| 2.1.2 No Keyboard Trap | A | Focus can always move away |
-| 2.1.4 Character Key Shortcuts | A | Single-key shortcuts can be turned off or only work when a component has focus |
-| 2.2.1 Timing Adjustable | A | Time limits can be extended |
-| 2.2.2 Pause, Stop, Hide | A | Moving or auto-updating content can be paused |
-| 2.3.1 Three Flashes | A | Nothing flashes more than three times per second |
-| 2.4.1 Bypass Blocks | A | Skip link or landmarks |
-| 2.4.2 Page Titled | A | Descriptive, unique titles per route |
-| 2.4.3 Focus Order | A | Order preserves meaning; dialogs and route changes manage focus |
-| 2.4.4 Link Purpose (In Context) | A | Link text says where it goes |
-| 2.4.6 Headings and Labels | AA | Headings and labels describe their content |
-| 2.4.7 Focus Visible | AA | A visible focus indicator |
-| 2.4.11 Focus Not Obscured (Minimum) | AA | Focused element not fully hidden by sticky or overlay content |
-| 2.5.1 Pointer Gestures | A | Multi-finger or path gestures have a single-pointer alternative |
-| 2.5.2 Pointer Cancellation | A | Actions fire on release, not on press |
-| 2.5.3 Label in Name | A | Accessible name contains the visible label |
-| 2.5.7 Dragging Movements | AA | Dragging has a single-pointer alternative |
-| 2.5.8 Target Size (Minimum) | AA | 24 by 24 CSS px, or enough spacing |
-| 3.1.1 Language of Page | A | `<html lang>` |
-| 3.1.2 Language of Parts | AA | `lang` on passages in another language |
-| 3.2.1 On Focus / 3.2.2 On Input | A | Focusing or changing a field does not navigate or submit unexpectedly |
-| 3.2.3 Consistent Navigation | AA | Navigation in the same order across pages |
-| 3.2.6 Consistent Help | A | Help links or contact options in the same place across pages |
-| 3.3.1 Error Identification | A | Errors described in text and tied to the field |
-| 3.3.2 Labels or Instructions | A | Labels and format hints |
-| 3.3.3 Error Suggestion | AA | Say how to fix it when known |
-| 3.3.4 Error Prevention (Legal, Financial, Data) | AA | Review, confirm or undo for important submissions |
-| 3.3.7 Redundant Entry | A | Do not ask again for data entered earlier in the same process |
-| 3.3.8 Accessible Authentication (Minimum) | AA | No memory or puzzle test without an alternative; allow paste and password managers |
-| 4.1.2 Name, Role, Value | A | Custom controls expose name, role and state |
-| 4.1.3 Status Messages | AA | Status updates announced without moving focus |
-
-Criteria 2.4.12, 2.4.13 and 3.3.9 are AAA and new in 2.2; 4.1.1 Parsing was removed in 2.2, so do not report it.
-
-## Patterns
-
-**Visually hidden text** (for screen readers only):
-
-```css
-.visually-hidden {
-  position: absolute; width: 1px; height: 1px; padding: 0; margin: -1px;
-  overflow: hidden; clip: rect(0, 0, 0, 0); white-space: nowrap; border: 0;
-}
-```
-
-Use the project's existing utility if it has one (`sr-only`, `visually-hidden`, a component).
-
-**Dialog:** prefer native `<dialog>` opened with `showModal()`, which makes the rest of the page inert and closes on Escape. Give it a name (`aria-labelledby` pointing at its heading), move focus inside on open, and return focus to the trigger on close. A custom dialog needs `role="dialog"`, `aria-modal="true"`, a focus trap, Escape handling and an inert or `aria-hidden` background.
-
-**Skip link:**
-
-```html
-<a class="skip-link" href="#main">Skip to main content</a>
-<main id="main" tabindex="-1">...</main>
-```
-
-with CSS that keeps it off-screen until it receives focus.
-
-**Error summary on submit:** a heading like "2 problems need fixing" with links to each invalid field, focused after a failed submit; each field keeps its own inline error with `aria-describedby`.
-
-**Tabs:** `role="tablist"` containing `role="tab"` elements with `aria-selected` and `aria-controls`; panels with `role="tabpanel"` and `aria-labelledby`. Only the active tab has `tabindex="0"`; arrow keys move between tabs.
-
-**Disclosure and menus:** a button with `aria-expanded` that toggles the controlled region. Do not use `role="menu"` for site navigation; it promises application-style keyboard behaviour.
-
-**Live region:** render the container empty on page load, then change its text:
-
-```html
-<div role="status" class="visually-hidden" id="announcer"></div>
-```
-
-Clearing it before writing the same message again makes screen readers repeat it.
-
-**Reduced motion:**
-
-```css
-@media (prefers-reduced-motion: reduce) {
-  *, *::before, *::after {
-    animation-duration: 0.01ms !important;
-    animation-iteration-count: 1 !important;
-    transition-duration: 0.01ms !important;
-    scroll-behavior: auto !important;
-  }
-}
-```
-
-Or scope it to the animations the change adds, if the project handles motion per component.
-
-## Contrast from design tokens
-
-When colours come from tokens or CSS variables, compute the ratio instead of guessing. Run with `node -e` or in a temp file:
-
-```js
-function luminance(hex) {
-  const value = hex.replace('#', '')
-  const full = value.length === 3 ? value.split('').map(c => c + c).join('') : value
-  const [r, g, b] = [0, 2, 4].map(i => parseInt(full.slice(i, i + 2), 16) / 255)
-    .map(c => (c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4))
-  return 0.2126 * r + 0.7152 * g + 0.0722 * b
-}
-function contrast(foreground, background) {
-  const [light, dark] = [luminance(foreground), luminance(background)].sort((a, b) => b - a)
-  return (light + 0.05) / (dark + 0.05)
-}
-console.log(contrast('#6b7280', '#ffffff').toFixed(2))
-```
-
-Semi-transparent colours must be blended with their real background first. For dark mode, check both themes.
-
-## Keyboard pass in a headless browser
-
-Use as the `steps` function of the `ui-testing` headless check. It records the first stops of the Tab order, whether each one shows a focus style, and whether Escape closes an open dialog. The focus-style test is a heuristic (it looks for an outline or box shadow); confirm doubtful cases on a screenshot.
-
-```js
-async function steps(page) {
-    const stops = []
-    for (let i = 0; i < 25; i++) {
-        await page.keyboard.press('Tab')
-        const stop = await page.evaluate(() => {
-            const el = document.activeElement
-            if (!el || el === document.body) return null
-            const style = getComputedStyle(el)
-            const hasOutline = style.outlineStyle !== 'none' && parseFloat(style.outlineWidth) > 0
-            const hasShadow = style.boxShadow && style.boxShadow !== 'none'
-            const label = el.getAttribute('aria-label') || el.innerText || el.getAttribute('title') || el.getAttribute('name') || ''
-            return {
-                element: el.tagName.toLowerCase() + (el.getAttribute('role') ? `[role=${el.getAttribute('role')}]` : ''),
-                name: label.trim().replace(/\s+/g, ' ').slice(0, 60),
-                visibleFocus: Boolean(hasOutline || hasShadow),
-                inViewport: (() => { const r = el.getBoundingClientRect(); return r.bottom > 0 && r.top < innerHeight })(),
-            }
-        })
-        if (!stop) break
-        stops.push(stop)
-    }
-    let escapeClosesDialog = null
-    const dialog = page.locator('dialog[open], [role="dialog"]').first()
-    if (await dialog.isVisible().catch(() => false)) {
-        await dialog.locator('button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])').first().focus().catch(() => {})
-        await page.keyboard.press('Escape')
-        escapeClosesDialog = !(await dialog.isVisible().catch(() => false))
-    }
-    return { stops, escapeClosesDialog }
-}
-```
-
-Read the result: stops with an empty `name` are unnamed controls; `visibleFocus: false` needs a screenshot check; the order should follow the visual layout; stops that repeat in a loop inside one component suggest a trap. To test a dialog, open it in `steps` first (click its trigger), then run the same loop and check focus stays inside it and returns to the trigger after Escape.
-
-Adapted from addyosmani/web-quality-skills `skills/accessibility/references/WCAG.md` and `A11Y-PATTERNS.md` (MIT, commit afa8da942115f2961fdbfa80807ea0b232ff6c00, Copyright (c) 2026 Addy Osmani). Changed: limited to A and AA criteria relevant to web apps with "what to check" notes, patterns condensed, contrast and keyboard-pass scripts added.
+# WCAG 2.2 checks, patterns and scripts
+
+Read this when you need the exact criterion for a finding, a correct markup pattern for a fix, a contrast calculation, or the keyboard pass for the headless check.
+
+## Level A and AA criteria that matter most for web apps
+
+| Criterion | Level | What to check |
+|---|---|---|
+| 1.1.1 Non-text Content | A | Alt text on meaningful images, names on icon buttons, `alt=""` on decorative images |
+| 1.2.2 Captions (Prerecorded) | A | Videos with speech have captions |
+| 1.3.1 Info and Relationships | A | Headings, lists, tables, labels and groups exist in markup, not only in styling |
+| 1.3.2 Meaningful Sequence | A | DOM order matches reading order (CSS `order` and grid placement can break it) |
+| 1.3.5 Identify Input Purpose | AA | `autocomplete` on fields about the user |
+| 1.4.1 Use of Color | A | Colour is not the only way information is shown |
+| 1.4.3 Contrast (Minimum) | AA | 4.5:1 text, 3:1 large text (24 px, or 18.66 px bold) |
+| 1.4.4 Resize Text | AA | Usable at 200% zoom |
+| 1.4.10 Reflow | AA | No two-dimensional scrolling at 320 CSS px wide (except maps, tables, editors) |
+| 1.4.11 Non-text Contrast | AA | 3:1 for control boundaries, focus indicators, meaningful icons and graphics |
+| 1.4.12 Text Spacing | AA | No clipped text when line and letter spacing increase (avoid fixed heights on text boxes) |
+| 1.4.13 Content on Hover or Focus | AA | Tooltips and popovers can be dismissed (Escape), hovered and stay until dismissed |
+| 2.1.1 Keyboard | A | Every function works with the keyboard |
+| 2.1.2 No Keyboard Trap | A | Focus can always move away |
+| 2.1.4 Character Key Shortcuts | A | Single-key shortcuts can be turned off or only work when a component has focus |
+| 2.2.1 Timing Adjustable | A | Time limits can be extended |
+| 2.2.2 Pause, Stop, Hide | A | Moving or auto-updating content can be paused |
+| 2.3.1 Three Flashes | A | Nothing flashes more than three times per second |
+| 2.4.1 Bypass Blocks | A | Skip link or landmarks |
+| 2.4.2 Page Titled | A | Descriptive, unique titles per route |
+| 2.4.3 Focus Order | A | Order preserves meaning; dialogs and route changes manage focus |
+| 2.4.4 Link Purpose (In Context) | A | Link text says where it goes |
+| 2.4.6 Headings and Labels | AA | Headings and labels describe their content |
+| 2.4.7 Focus Visible | AA | A visible focus indicator |
+| 2.4.11 Focus Not Obscured (Minimum) | AA | Focused element not fully hidden by sticky or overlay content |
+| 2.5.1 Pointer Gestures | A | Multi-finger or path gestures have a single-pointer alternative |
+| 2.5.2 Pointer Cancellation | A | Actions fire on release, not on press |
+| 2.5.3 Label in Name | A | Accessible name contains the visible label |
+| 2.5.7 Dragging Movements | AA | Dragging has a single-pointer alternative |
+| 2.5.8 Target Size (Minimum) | AA | 24 by 24 CSS px, or enough spacing |
+| 3.1.1 Language of Page | A | `<html lang>` |
+| 3.1.2 Language of Parts | AA | `lang` on passages in another language |
+| 3.2.1 On Focus / 3.2.2 On Input | A | Focusing or changing a field does not navigate or submit unexpectedly |
+| 3.2.3 Consistent Navigation | AA | Navigation in the same order across pages |
+| 3.2.6 Consistent Help | A | Help links or contact options in the same place across pages |
+| 3.3.1 Error Identification | A | Errors described in text and tied to the field |
+| 3.3.2 Labels or Instructions | A | Labels and format hints |
+| 3.3.3 Error Suggestion | AA | Say how to fix it when known |
+| 3.3.4 Error Prevention (Legal, Financial, Data) | AA | Review, confirm or undo for important submissions |
+| 3.3.7 Redundant Entry | A | Do not ask again for data entered earlier in the same process |
+| 3.3.8 Accessible Authentication (Minimum) | AA | No memory or puzzle test without an alternative; allow paste and password managers |
+| 4.1.2 Name, Role, Value | A | Custom controls expose name, role and state |
+| 4.1.3 Status Messages | AA | Status updates announced without moving focus |
+
+Criteria 2.4.12, 2.4.13 and 3.3.9 are AAA and new in 2.2; 4.1.1 Parsing was removed in 2.2, so do not report it.
+
+## Patterns
+
+**Visually hidden text** (for screen readers only):
+
+```css
+.visually-hidden {
+  position: absolute; width: 1px; height: 1px; padding: 0; margin: -1px;
+  overflow: hidden; clip: rect(0, 0, 0, 0); white-space: nowrap; border: 0;
+}
+```
+
+Use the project's existing utility if it has one (`sr-only`, `visually-hidden`, a component).
+
+**Dialog:** prefer native `<dialog>` opened with `showModal()`, which makes the rest of the page inert and closes on Escape. Give it a name (`aria-labelledby` pointing at its heading), move focus inside on open, and return focus to the trigger on close. A custom dialog needs `role="dialog"`, `aria-modal="true"`, a focus trap, Escape handling and an inert or `aria-hidden` background.
+
+**Skip link:**
+
+```html
+<a class="skip-link" href="#main">Skip to main content</a>
+<main id="main" tabindex="-1">...</main>
+```
+
+with CSS that keeps it off-screen until it receives focus.
+
+**Error summary on submit:** a heading like "2 problems need fixing" with links to each invalid field, focused after a failed submit; each field keeps its own inline error with `aria-describedby`.
+
+**Tabs:** `role="tablist"` containing `role="tab"` elements with `aria-selected` and `aria-controls`; panels with `role="tabpanel"` and `aria-labelledby`. Only the active tab has `tabindex="0"`; arrow keys move between tabs.
+
+**Disclosure and menus:** a button with `aria-expanded` that toggles the controlled region. Do not use `role="menu"` for site navigation; it promises application-style keyboard behaviour.
+
+**Live region:** render the container empty on page load, then change its text:
+
+```html
+<div role="status" class="visually-hidden" id="announcer"></div>
+```
+
+Clearing it before writing the same message again makes screen readers repeat it.
+
+**Reduced motion:**
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  *, *::before, *::after {
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0.01ms !important;
+    scroll-behavior: auto !important;
+  }
+}
+```
+
+Or scope it to the animations the change adds, if the project handles motion per component.
+
+## Contrast from design tokens
+
+When colours come from tokens or CSS variables, compute the ratio instead of guessing. Run with `node -e` or in a temp file:
+
+```js
+function luminance(hex) {
+  const value = hex.replace('#', '')
+  const full = value.length === 3 ? value.split('').map(c => c + c).join('') : value
+  const [r, g, b] = [0, 2, 4].map(i => parseInt(full.slice(i, i + 2), 16) / 255)
+    .map(c => (c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4))
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b
+}
+function contrast(foreground, background) {
+  const [light, dark] = [luminance(foreground), luminance(background)].sort((a, b) => b - a)
+  return (light + 0.05) / (dark + 0.05)
+}
+console.log(contrast('#6b7280', '#ffffff').toFixed(2))
+```
+
+Semi-transparent colours must be blended with their real background first. For dark mode, check both themes.
+
+## Keyboard pass in a headless browser
+
+Use as the `steps` function of the `ui-testing` headless check. It records the first stops of the Tab order, whether each one shows a focus style, and whether Escape closes an open dialog. The focus-style test is a heuristic (it looks for an outline or box shadow); confirm doubtful cases on a screenshot.
+
+```js
+async function steps(page) {
+    const stops = []
+    for (let i = 0; i < 25; i++) {
+        await page.keyboard.press('Tab')
+        const stop = await page.evaluate(() => {
+            const el = document.activeElement
+            if (!el || el === document.body) return null
+            const style = getComputedStyle(el)
+            const hasOutline = style.outlineStyle !== 'none' && parseFloat(style.outlineWidth) > 0
+            const hasShadow = style.boxShadow && style.boxShadow !== 'none'
+            const label = el.getAttribute('aria-label') || el.innerText || el.getAttribute('title') || el.getAttribute('name') || ''
+            return {
+                element: el.tagName.toLowerCase() + (el.getAttribute('role') ? `[role=${el.getAttribute('role')}]` : ''),
+                name: label.trim().replace(/\s+/g, ' ').slice(0, 60),
+                visibleFocus: Boolean(hasOutline || hasShadow),
+                inViewport: (() => { const r = el.getBoundingClientRect(); return r.bottom > 0 && r.top < innerHeight })(),
+            }
+        })
+        if (!stop) break
+        stops.push(stop)
+    }
+    let escapeClosesDialog = null
+    const dialog = page.locator('dialog[open], [role="dialog"]').first()
+    if (await dialog.isVisible().catch(() => false)) {
+        await dialog.locator('button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])').first().focus().catch(() => {})
+        await page.keyboard.press('Escape')
+        escapeClosesDialog = !(await dialog.isVisible().catch(() => false))
+    }
+    return { stops, escapeClosesDialog }
+}
+```
+
+Read the result: stops with an empty `name` are unnamed controls; `visibleFocus: false` needs a screenshot check; the order should follow the visual layout; stops that repeat in a loop inside one component suggest a trap. To test a dialog, open it in `steps` first (click its trigger), then run the same loop and check focus stays inside it and returns to the trigger after Escape.
+
+Adapted from addyosmani/web-quality-skills `skills/accessibility/references/WCAG.md` and `A11Y-PATTERNS.md` (MIT, commit afa8da942115f2961fdbfa80807ea0b232ff6c00, Copyright (c) 2026 Addy Osmani). Changed: limited to A and AA criteria relevant to web apps with "what to check" notes, patterns condensed, contrast and keyboard-pass scripts added.

package/library/skills/addressing-review-feedback/SKILL.md

@@ -1,109 +1,109 @@
----
-name: addressing-review-feedback
-description: Use when a code step is a rework with review comments to address: check each comment against the current code before acting, fix every valid one, explain with evidence any you do not apply, keep the reviewer's own commits, and report the outcome per comment.
----
-
-# Addressing review feedback
-
-A rework run gets the reviewer's comments and a branch that already has the earlier work, and maybe commits from the reviewer. Nobody will answer questions, and you cannot reply on GitHub. Your answer to the reviewer is the code plus the report.
-
-Review feedback is a set of technical claims to check, not orders to apply blindly and not opinions to argue with. Verify, then act.
-
-## 1. Get the current state
-
-In each repository:
-
-```
-git log --oneline origin/<base>..HEAD
-git diff --stat origin/<base>...HEAD
-git status
-```
-
-- The current branch is the source of truth. Line numbers in the comments may refer to an older version; find the code by content, not by number.
-- Identify commits that are not from the earlier agent run (different author, or messages like "review fixes"). These are the reviewer's own changes. Keep them: do not revert, rewrite or "clean up" them unless a comment explicitly asks for that.
-- Never rewrite history: no rebase, amend, reset or force push. Add new commits on top.
-
-## 2. List every comment
-
-Read all comments before changing anything. Items can depend on each other, and a later comment can change how you read an earlier one.
-
-Number them and restate each as a concrete technical requirement:
-
-```
-C1 "this will blow up for guests" -> getCart() must handle a null user (src/cart.ts, getCart)
-C2 "use the existing money helper" -> replace manual rounding with formatMoney() in Invoice.vue
-C3 "add a test for the empty state" -> component test: no items shows the empty message
-```
-
-A comment that holds several requests becomes several items.
-
-## 3. Verify each item against the code
-
-For each item, before editing:
-
-- Is the claim true in the current code? Reproduce it if it is a bug (a test, a quick run). It may already be fixed by a reviewer commit.
-- Would the suggested change break something else? Search for other callers, run the related tests.
-- Is there a reason the code is the way it is (a comment, a test, the spec, a platform constraint)?
-- Does the suggestion fit this codebase and its conventions?
-- For "do it properly" or "add X" requests, check whether X is used: search the code. Building an unused feature is not a fix.
-
-If a comment is unclear, choose the reading that best matches the reviewer's evident intent, the spec and the code. Write the reading you chose in the report. Do not stop and do not skip it.
-
-## 4. Decide and act
-
-Each item ends in one of these states:
-
-| State | When |
-|---|---|
-| Fixed | The comment is valid; you changed the code and checked it. |
-| Already done | The current code already does it (say where, for example a reviewer commit). |
-| Fixed differently | The concern is valid but the suggested change is wrong here; you solved the concern another way. |
-| Not changed | The comment is wrong for this code, conflicts with the spec, or would break something. Give the evidence. |
-| Partly done | You could do only part of it (needs credentials, out of scope of the task). Say what is left. |
-
-Default to fixing. Use "Not changed" only with concrete evidence (file:line, test output, a spec quote), never because the change is inconvenient. When the reviewer and the spec disagree, follow the reviewer if the change is safe and within the task, and note the conflict.
-
-Order of work:
-1. Blocking items: broken behaviour, security, data loss.
-2. Simple items: naming, imports, small corrections.
-3. Larger items: logic changes, refactors.
-
-Work one item at a time and run the related tests after each. Use `systematic-debugging` for bug reports and `test-driven-development` when a comment asks for new behaviour or reports a bug that a test could catch.
-
-Stay within the comments and what they directly imply. A rework is not the time for unrelated improvements; list those under "Noticed, not changed".
-
-## 5. Verify everything and commit
-
-Run `verification-before-completion` across the whole branch, not only the lines you touched: a fix for one comment can break another part. Commit with `clean-commits`; one commit per comment or one commit for the whole round both work, as long as messages say what was addressed.
-
-## 6. Report per comment
-
-Plain technical statements. No thanks, no "great catch", no "you're absolutely right": the reader wants to know what changed.
-
-```
-Review comments
-C1 Fixed: getCart() returns an empty cart for guests (src/cart.ts:31), test "guest gets empty cart" added, failed before.
-C2 Fixed: Invoice.vue uses formatMoney() for totals and line prices.
-C3 Fixed: test "shows the empty message when there are no items" in Invoice.test.ts.
-C4 Not changed: the comment suggests removing the legacy date parser, but importInvoices() still calls it for CSV files (src/import/csv.ts:88); removing it breaks 4 tests in csv.test.ts.
-C5 Already done: reviewer commit 3f2a1c0 renamed the prop.
-C6 Unclear, read as "show the VAT column only for business customers" (matches spec rule 2): done in InvoiceTable.vue.
-
-Checks
-- pnpm test -- --run: 220 passed, 0 failed
-- pnpm typecheck: exit 0
-```
-
-## Common mistakes
-
-| Mistake | Instead |
-|---|---|
-| Applying every suggestion without checking it | Verify against the code first; reviewers can be wrong or work from an old version. |
-| Skipping a comment silently | Every comment appears in the report with a state. |
-| Arguing without evidence | Show the file:line, the test or the spec line. |
-| Reverting or rewriting the reviewer's commits | Keep them; build on top. |
-| Fixing items in a batch and testing once at the end | One item, then its tests. |
-| Fixing only the commented lines | Look for the same problem elsewhere in your change and fix it there too. |
-| Asking questions in the report and waiting | Decide, state the reading you chose, and finish. |
-
-Sources: obra/superpowers (MIT, commit bb92a77) receiving-code-review. Changed: rewritten for unattended reworks, every question path removed.
+---
+name: addressing-review-feedback
+description: Use when a code step is a rework with review comments to address: check each comment against the current code before acting, fix every valid one, explain with evidence any you do not apply, keep the reviewer's own commits, and report the outcome per comment.
+---
+
+# Addressing review feedback
+
+A rework run gets the reviewer's comments and a branch that already has the earlier work, and maybe commits from the reviewer. Nobody will answer questions, and you cannot reply on GitHub. Your answer to the reviewer is the code plus the report.
+
+Review feedback is a set of technical claims to check, not orders to apply blindly and not opinions to argue with. Verify, then act.
+
+## 1. Get the current state
+
+In each repository:
+
+```
+git log --oneline origin/<base>..HEAD
+git diff --stat origin/<base>...HEAD
+git status
+```
+
+- The current branch is the source of truth. Line numbers in the comments may refer to an older version; find the code by content, not by number.
+- Identify commits that are not from the earlier agent run (different author, or messages like "review fixes"). These are the reviewer's own changes. Keep them: do not revert, rewrite or "clean up" them unless a comment explicitly asks for that.
+- Never rewrite history: no rebase, amend, reset or force push. Add new commits on top.
+
+## 2. List every comment
+
+Read all comments before changing anything. Items can depend on each other, and a later comment can change how you read an earlier one.
+
+Number them and restate each as a concrete technical requirement:
+
+```
+C1 "this will blow up for guests" -> getCart() must handle a null user (src/cart.ts, getCart)
+C2 "use the existing money helper" -> replace manual rounding with formatMoney() in Invoice.vue
+C3 "add a test for the empty state" -> component test: no items shows the empty message
+```
+
+A comment that holds several requests becomes several items.
+
+## 3. Verify each item against the code
+
+For each item, before editing:
+
+- Is the claim true in the current code? Reproduce it if it is a bug (a test, a quick run). It may already be fixed by a reviewer commit.
+- Would the suggested change break something else? Search for other callers, run the related tests.
+- Is there a reason the code is the way it is (a comment, a test, the spec, a platform constraint)?
+- Does the suggestion fit this codebase and its conventions?
+- For "do it properly" or "add X" requests, check whether X is used: search the code. Building an unused feature is not a fix.
+
+If a comment is unclear, choose the reading that best matches the reviewer's evident intent, the spec and the code. Write the reading you chose in the report. Do not stop and do not skip it.
+
+## 4. Decide and act
+
+Each item ends in one of these states:
+
+| State | When |
+|---|---|
+| Fixed | The comment is valid; you changed the code and checked it. |
+| Already done | The current code already does it (say where, for example a reviewer commit). |
+| Fixed differently | The concern is valid but the suggested change is wrong here; you solved the concern another way. |
+| Not changed | The comment is wrong for this code, conflicts with the spec, or would break something. Give the evidence. |
+| Partly done | You could do only part of it (needs credentials, out of scope of the task). Say what is left. |
+
+Default to fixing. Use "Not changed" only with concrete evidence (file:line, test output, a spec quote), never because the change is inconvenient. When the reviewer and the spec disagree, follow the reviewer if the change is safe and within the task, and note the conflict.
+
+Order of work:
+1. Blocking items: broken behaviour, security, data loss.
+2. Simple items: naming, imports, small corrections.
+3. Larger items: logic changes, refactors.
+
+Work one item at a time and run the related tests after each. Use `systematic-debugging` for bug reports and `test-driven-development` when a comment asks for new behaviour or reports a bug that a test could catch.
+
+Stay within the comments and what they directly imply. A rework is not the time for unrelated improvements; list those under "Noticed, not changed".
+
+## 5. Verify everything and commit
+
+Run `verification-before-completion` across the whole branch, not only the lines you touched: a fix for one comment can break another part. Commit with `clean-commits`; one commit per comment or one commit for the whole round both work, as long as messages say what was addressed.
+
+## 6. Report per comment
+
+Plain technical statements. No thanks, no "great catch", no "you're absolutely right": the reader wants to know what changed.
+
+```
+Review comments
+C1 Fixed: getCart() returns an empty cart for guests (src/cart.ts:31), test "guest gets empty cart" added, failed before.
+C2 Fixed: Invoice.vue uses formatMoney() for totals and line prices.
+C3 Fixed: test "shows the empty message when there are no items" in Invoice.test.ts.
+C4 Not changed: the comment suggests removing the legacy date parser, but importInvoices() still calls it for CSV files (src/import/csv.ts:88); removing it breaks 4 tests in csv.test.ts.
+C5 Already done: reviewer commit 3f2a1c0 renamed the prop.
+C6 Unclear, read as "show the VAT column only for business customers" (matches spec rule 2): done in InvoiceTable.vue.
+
+Checks
+- pnpm test -- --run: 220 passed, 0 failed
+- pnpm typecheck: exit 0
+```
+
+## Common mistakes
+
+| Mistake | Instead |
+|---|---|
+| Applying every suggestion without checking it | Verify against the code first; reviewers can be wrong or work from an old version. |
+| Skipping a comment silently | Every comment appears in the report with a state. |
+| Arguing without evidence | Show the file:line, the test or the spec line. |
+| Reverting or rewriting the reviewer's commits | Keep them; build on top. |
+| Fixing items in a batch and testing once at the end | One item, then its tests. |
+| Fixing only the commented lines | Look for the same problem elsewhere in your change and fix it there too. |
+| Asking questions in the report and waiting | Decide, state the reading you chose, and finish. |
+
+Sources: obra/superpowers (MIT, commit bb92a77) receiving-code-review. Changed: rewritten for unattended reworks, every question path removed.