@kennethsolomon/shipkit 3.10.1 → 3.11.0

package/skills/sk:fast-track/SKILL.md

@@ -61,15 +61,6 @@ Before proceeding, check the scope of planned changes:
 ### 6. Finalize
 - Run `/sk:finish-feature` for changelog + PR
 
-## Workflow Status
-
-Fast-track updates `tasks/workflow-status.md` with abbreviated steps:
-- Steps 1-2 (read): done
-- Steps 3-6 (explore, design, accessibility, plan): skipped (fast-track)
-- Steps 7-11 (branch, implement, commit): done
-- Steps 12-17 (gates): handled by `/sk:gates`
-- Steps 18-21 (update, finalize, sync, release): done as applicable
-
 ## Model Routing
 
 | Profile | Model |

package/skills/sk:frontend-design/SKILL.md

@@ -63,6 +63,235 @@ Interpret creatively and make unexpected choices that feel genuinely designed fo
 
 Remember: Claude is capable of extraordinary creative thinking. Don't hold back on the design direction — show what can be envisioned when thinking outside the box and committing fully to a distinctive aesthetic.
 
+## UX Quality Constraints
+
+Apply these rules as hard constraints during design. They are organized by priority — address CRITICAL issues first, then HIGH, then MEDIUM. Skip categories irrelevant to the current design (e.g., Charts for a landing page).
+
+| Priority | Category | Impact | Key Rule |
+|---|---|---|---|
+| 1 | Accessibility | CRITICAL | Contrast 4.5:1, keyboard nav, aria-labels, focus rings |
+| 2 | Touch & Interaction | CRITICAL | Min 44×44px targets, tap feedback, no hover-only |
+| 3 | Performance | HIGH | WebP/AVIF images, lazy load, skeleton screens, no layout shift |
+| 4 | Style Selection | HIGH | Match style to product type, SVG icons (never emoji), one primary CTA |
+| 5 | Layout & Responsive | HIGH | Mobile-first, breakpoints 375/768/1024/1440, no horizontal scroll |
+| 6 | Typography & Color | MEDIUM | Base 16px body, line-height 1.5, semantic color tokens |
+| 7 | Animation | MEDIUM | 150–300ms duration, transform/opacity only, respect prefers-reduced-motion |
+| 8 | Forms & Feedback | MEDIUM | Visible labels, error near field, loading → success/error on submit |
+| 9 | Navigation | HIGH | Bottom nav ≤5 items, predictable back, deep linking |
+| 10 | Charts & Data | LOW | Match chart to data type, accessible colors, legend visible |
+
+### 1. Accessibility (CRITICAL)
+
+- Minimum 4.5:1 contrast ratio for normal text (large text 3:1)
+- Visible focus rings on all interactive elements (2–4px outline)
+- Descriptive alt text on all meaningful images
+- `aria-label` on icon-only buttons
+- Tab order matches visual order; full keyboard navigation supported
+- `label[for]` on every form input — never placeholder-only
+- Never convey information by color alone (add icon or text)
+- Respect `prefers-reduced-motion` — reduce or disable animations when set
+- Sequential heading hierarchy h1→h6, no skipped levels
+- Screen reader logical reading order; meaningful accessibilityLabel/Hint
+- Skip-to-main-content link for keyboard users
+
+### 2. Touch & Interaction (CRITICAL)
+
+- Minimum 44×44pt (iOS) / 48×48dp (Android) tap target — expand hitSlop if icon is smaller
+- Minimum 8px gap between adjacent touch targets
+- Never rely on hover-only for primary interactions — use click/tap
+- Disable buttons during async operations; show spinner or progress
+- Add `cursor-pointer` to all clickable elements (web)
+- Provide visual feedback on press within 100ms (ripple, opacity, elevation)
+- Use `touch-action: manipulation` to eliminate 300ms tap delay (web)
+- Avoid horizontal swipe on scrollable content — prefer vertical scroll
+- Don't block system gestures (back swipe, Control Center, home indicator)
+
+### 3. Performance (HIGH)
+
+- Use WebP/AVIF with `srcset`/`sizes`; lazy load non-hero images
+- Declare `width`/`height` or `aspect-ratio` on images to prevent CLS
+- Use `font-display: swap` or `optional` to avoid FOIT
+- Preload only critical fonts — avoid preloading every weight variant
+- Lazy load non-hero components via dynamic import / route-level splitting
+- Load third-party scripts `async`/`defer`
+- Reserve space for async content to avoid layout jumps (CLS < 0.1)
+- Virtualize lists with 50+ items
+- Use skeleton/shimmer for loads >300ms — never a blank frame
+- Keep per-frame work <16ms (60fps); move heavy tasks off main thread
+- Debounce/throttle scroll, resize, and input handlers
+
+### 4. Style Selection (HIGH)
+
+- Match style to product type and industry — no random style mixing
+- Use SVG icons (Heroicons, Lucide) — never emojis as structural icons
+- Use one icon set throughout — consistent stroke width, corner radius, filled vs outline
+- Each screen has exactly one primary CTA; secondary actions are visually subordinate
+- Apply a consistent elevation/shadow scale — no arbitrary shadow values
+- Design light and dark variants together; don't assume light values work in dark mode
+- Blur signals background dismissal (modals, sheets) — not decoration
+- Respect platform idioms (iOS HIG vs Material Design) for navigation, controls, motion
+
+### 5. Layout & Responsive (HIGH)
+
+- `<meta name="viewport" content="width=device-width, initial-scale=1">` — never disable zoom
+- Design mobile-first; scale up to 768, 1024, 1440
+- No horizontal scroll on mobile; all content fits viewport width
+- Use 4pt/8dp incremental spacing system throughout
+- Consistent `max-w-6xl`/`7xl` container on desktop
+- Define a z-index scale (e.g., 0 / 10 / 20 / 40 / 100 / 1000) — no arbitrary values
+- Fixed navbars/bottom bars must pad underlying scroll content
+- Use `min-h-dvh` instead of `100vh` on mobile
+- Establish hierarchy via size, spacing, contrast — not color alone
+- Core content first on mobile; fold or hide secondary content
+
+### 6. Typography & Color (MEDIUM)
+
+- Minimum 16px body text on mobile (prevents iOS auto-zoom)
+- Line-height 1.5–1.75 for body text
+- 60–75 characters per line on desktop; 35–60 on mobile
+- Consistent type scale (e.g., 12 / 14 / 16 / 18 / 24 / 32)
+- Bold headings (600–700), regular body (400), medium labels (500)
+- Define semantic color tokens (`--color-primary`, `--color-error`, `--color-surface`) — never raw hex in components
+- Dark mode: use desaturated/lighter tonal variants, not inverted colors; test contrast independently
+- All foreground/background pairs must meet 4.5:1 (AA); use a contrast checker
+- Use tabular/monospaced figures for prices, data columns, and timers
+- Use whitespace intentionally to group related items and separate sections
+
+### 7. Animation (MEDIUM)
+
+- Duration: 150–300ms for micro-interactions; complex transitions ≤400ms; never >500ms
+- Animate `transform` and `opacity` only — never `width`, `height`, `top`, `left`
+- Use ease-out for entering elements; ease-in for exiting
+- Every animation expresses cause-effect — no purely decorative motion
+- State changes (hover, active, expanded, modal) animate smoothly — no snapping
+- Page transitions maintain spatial continuity (shared element, directional slide)
+- Exit animations should be 60–70% of enter duration to feel responsive
+- Stagger list/grid item entrance by 30–50ms per item
+- Animations must be interruptible — user tap cancels in-progress animation immediately
+- Never block user input during an animation
+- Scale feedback on press: subtle 0.95–1.05 scale on tappable cards/buttons
+- `prefers-reduced-motion` must reduce or disable animations entirely
+
+### 8. Forms & Feedback (MEDIUM)
+
+- Every input has a visible label — never placeholder-only
+- Show errors immediately below the related field (not only at the top)
+- Mark required fields (asterisk or explicit label)
+- Submit button: loading state → success or error state
+- Auto-dismiss toasts in 3–5s; toasts must not steal focus (`aria-live="polite"`)
+- Confirm before destructive actions (modals, undo toasts)
+- Validate on blur, not on every keystroke
+- Use semantic input types (`email`, `tel`, `number`) for correct mobile keyboard
+- Provide show/hide toggle on password fields
+- Error messages state the cause + how to fix — not just "Invalid input"
+- Multi-step forms show a step indicator and allow back navigation
+- After submit error, auto-focus the first invalid field
+
+### 9. Navigation (HIGH)
+
+- Bottom navigation: maximum 5 items with both icon and text label
+- Back navigation is predictable and restores scroll/filter state
+- All key screens are deep-linkable via URL/route
+- Current location is visually highlighted in navigation (color, weight, indicator)
+- Modals have a clear close affordance; support swipe-down to dismiss on mobile
+- Never use modals for primary navigation flows
+- Large screens (≥1024px) prefer sidebar; small screens use bottom/top nav
+- Don't mix Tab + Sidebar + Bottom Nav at the same hierarchy level
+- Dangerous actions (logout, delete account) are visually separated from normal nav
+- After route change, move focus to main content region for screen readers
+
+### 10. Charts & Data (when applicable)
+
+- Match chart type to data: trend → line, comparison → bar, proportion → pie/donut
+- Avoid pie/donut for >5 categories — use bar chart instead
+- Use accessible color palettes; never red/green only (colorblind users)
+- Always show a legend near the chart (not below a scroll fold)
+- Provide tooltips/data labels on hover (web) or tap (mobile)
+- Label all axes with units; avoid rotated labels on mobile
+- Charts must reflow on small screens (horizontal bar instead of vertical, fewer ticks)
+- Show skeleton/shimmer while chart data loads — never an empty axis frame
+- Grid lines should be low-contrast (e.g., `gray-200`) so they don't compete with data
+- Provide a text summary or `aria-label` describing the chart's key insight
+
+---
+
+## Professional UI Anti-Patterns
+
+These are frequently overlooked issues that make UI look unprofessional. Flag any of these in the design spec so implementation avoids them.
+
+### Icons & Visual Elements
+- **No emoji as icons** — use Heroicons, Lucide, or equivalent SVG sets
+- **No raster icons** — SVG only; PNGs blur and can't adapt to dark mode
+- **No mixed icon styles** — pick one set; consistent stroke width and fill style throughout
+- **No inconsistent sizing** — define icon size tokens (sm/md/lg = 16/20/24pt)
+- **Pressed states must not shift layout** — use opacity/color/elevation, not transforms that reflow siblings
+
+### Interaction
+- **No tap-only no-feedback** — every tappable element responds visually within 100ms
+- **No hover-only states on mobile** — hover states are fine for desktop, never the only affordance
+- **No disabled elements that look enabled** — use `opacity: 0.38–0.5` + `cursor: not-allowed` + semantic `disabled` attribute
+- **No precision-required targets** — avoid requiring taps on thin edges or pixel-perfect areas
+
+### Light/Dark Mode
+- **No hardcoded hex in components** — use semantic tokens that map per theme
+- **No light-mode-only testing** — always verify dark mode contrast independently
+- **No weak modal scrims** — use 40–60% black so background doesn't compete with foreground
+- **No color-only state indicators** — always pair color with icon or label
+
+### Layout & Spacing
+- **No safe-area violations** — respect notch, Dynamic Island, and gesture bar on mobile
+- **No scroll content hidden behind fixed bars** — add correct insets
+- **No random spacing** — every gap follows the 4/8dp rhythm
+- **No edge-to-edge paragraphs on tablets** — constrain long-form text width for readability
+
+---
+
+## Pre-Delivery Checklist
+
+Include this checklist at the end of every design output. Implementation must pass all applicable items before shipping.
+
+```
+### Pre-Delivery Checklist
+
+**Accessibility**
+- [ ] All text contrast ≥4.5:1 (normal) or ≥3:1 (large/UI)
+- [ ] Focus rings visible on all interactive elements
+- [ ] All images/icons have alt text or aria-label
+- [ ] No color-only information conveyance
+- [ ] prefers-reduced-motion respected
+
+**Touch & Interaction**
+- [ ] All tap targets ≥44×44pt
+- [ ] Every tappable element has pressed-state feedback
+- [ ] No hover-only interactions on mobile
+- [ ] cursor-pointer on all clickable web elements
+
+**Layout**
+- [ ] No horizontal scroll at 375px
+- [ ] Safe areas respected (notch, gesture bar, tab bar)
+- [ ] Scroll content not hidden behind fixed bars
+- [ ] 4/8dp spacing rhythm consistent throughout
+
+**Typography & Color**
+- [ ] Body text ≥16px on mobile
+- [ ] Semantic color tokens used (no raw hex in components)
+- [ ] Dark mode contrast verified independently
+
+**Performance**
+- [ ] Images use WebP/AVIF with declared dimensions
+- [ ] Skeleton/shimmer shown for loads >300ms
+- [ ] No layout shift from async content (CLS < 0.1)
+
+**Animation**
+- [ ] All transitions 150–300ms
+- [ ] Only transform/opacity animated (no width/height/top/left)
+- [ ] Animations interruptible; no input blocking
+
+**Icons**
+- [ ] No emojis used as icons (SVG only)
+- [ ] Consistent icon family and stroke style throughout
+```
+
 ## Output Format
 
 End every `/sk:frontend-design` session with a structured summary:
@@ -93,6 +322,9 @@ End every `/sk:frontend-design` session with a structured summary:
 
 ### Implementation Notes
 [Specific Tailwind classes, CSS patterns, or gotchas for /sk:execute-plan]
+
+### Pre-Delivery Checklist
+[Copy the checklist from the UX Quality Constraints section above and mark which items are covered by this design, and which need special attention during implementation]
 ```
 
 After presenting the design summary, you **MUST** stop and ask — do not continue or summarize further:

package/skills/sk:gates/SKILL.md

@@ -65,11 +65,10 @@ All gates passed. Run /sk:update-task
 
 ## Failure Handling
 
-- Each agent handles its own fix → auto-commit → re-run loop internally
+- Each agent handles its own fix → re-run loop internally
+- **Squash gate commits:** When a gate requires fixes, collect all fixes for that pass, then make ONE commit: `fix(<gate>): resolve <gate> issues`. Do not commit after each individual fix.
 - If any agent fails after 3 attempts → stop all gates and report to user
 - Do NOT proceed to the next batch if the current batch has unresolved failures
-- Update `tasks/workflow-status.md` for each gate as it completes:
-  - Steps 12-17 marked `done` with attempt count in Notes
 
 ## 3-Strike Protocol
 

package/skills/sk:health/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: sk:health
+description: "Run harness self-audit and produce a health scorecard."
+---
+
+# /sk:health — Harness Self-Audit Scorecard
+
+Deterministic scoring of your ShipKit setup across 7 categories. Produces a reproducible scorecard that identifies gaps and recommends improvements.
+
+## Usage
+
+```
+/sk:health              # full scorecard
+/sk:health --category <name>  # single category deep-dive
+```
+
+## Model Routing
+
+Read `.shipkit/config.json` from the project root if it exists.
+
+| Profile | Model |
+|---------|-------|
+| `full-sail` | haiku |
+| `quality` | haiku |
+| `balanced` | haiku |
+| `budget` | haiku |
+
+> File checks + arithmetic — haiku is sufficient.
+
+## Scoring Categories
+
+Each category scores 0-10. Maximum total: 70.
+
+### 1. Tool Coverage (0-10)
+
+Check for presence and completeness of:
+
+| Check | Points |
+|-------|--------|
+| `.claude/hooks/` exists with 6+ hooks | +2 |
+| `.claude/agents/` exists with 4+ agents | +2 |
+| `.claude/rules/` exists with 1+ rules | +1 |
+| `commands/sk/` or `.claude/commands/sk/` has 10+ commands | +2 |
+| MCP servers configured | +1 |
+| Statusline configured in settings.json | +1 |
+| Permissions deny list has 3+ entries | +1 |
+
+### 2. Context Efficiency (0-10)
+
+| Check | Points |
+|-------|--------|
+| CLAUDE.md exists and is <250 lines | +2 (>250: +1, >400: 0) |
+| No duplicate instructions across CLAUDE.md and skills | +2 |
+| MCP tools total <40 | +2 (40-60: +1, >60: 0) |
+| Skills total <60 | +2 (>60: +1, >80: 0) |
+| Agent descriptions all <200 lines | +2 |
+
+### 3. Quality Gates (0-10)
+
+| Check | Points |
+|-------|--------|
+| Lint configured (package.json scripts or Makefile) | +2 |
+| Test runner configured | +2 |
+| Security check available (npm audit, composer audit, etc.) | +2 |
+| E2E test config exists (playwright.config, cypress.config) | +2 |
+| Code review skill available | +2 |
+
+### 4. Memory Persistence (0-10)
+
+| Check | Points |
+|-------|--------|
+| `tasks/findings.md` exists and has content | +2 |
+| `tasks/lessons.md` exists and has content | +2 |
+| `tasks/progress.md` exists | +1 |
+| `tasks/tech-debt.md` exists | +1 |
+| `tasks/cross-platform.md` exists | +1 |
+| Session hooks active (session-start.sh, session-stop.sh) | +2 |
+| `.claude/sessions/` directory exists | +1 |
+
+### 5. Eval Coverage (0-10)
+
+| Check | Points |
+|-------|--------|
+| Test directory exists (`tests/`, `test/`, `spec/`, `__tests__/`) | +2 |
+| Test assertions exist (grep for assert/expect/test/it/describe) | +2 |
+| Coverage config exists (jest.config coverage, phpunit coverage) | +2 |
+| `.claude/evals/` directory exists with eval definitions | +2 |
+| CI/CD runs tests (`.github/workflows/` with test step) | +2 |
+
+### 6. Security Guardrails (0-10)
+
+| Check | Points |
+|-------|--------|
+| validate-commit hook exists | +2 |
+| validate-push hook exists | +2 |
+| config-protection hook exists | +2 |
+| Deny rules in settings.json (3+ patterns) | +2 |
+| safety-guard hook exists | +2 |
+
+### 7. Cost Efficiency (0-10)
+
+| Check | Points |
+|-------|--------|
+| Model routing configured (`.shipkit/config.json` exists) | +3 |
+| Compact suggestions active (suggest-compact hook) | +2 |
+| Cost tracker active (cost-tracker hook) | +2 |
+| Context budget recently audited (`/sk:context-budget` run) | +3 |
+
+## Output Format
+
+```
+=== ShipKit Health Scorecard ===
+
+  Tool Coverage:        8/10  ||||||||..
+  Context Efficiency:   7/10  |||||||...
+  Quality Gates:       10/10  ||||||||||
+  Memory Persistence:   6/10  ||||||....
+  Eval Coverage:        4/10  ||||......
+  Security Guardrails:  8/10  ||||||||..
+  Cost Efficiency:      5/10  |||||.....
+  ─────────────────────────────────
+  Total:               48/70  (69%)
+
+  Rating: GOOD
+
+Findings:
+  [MISSING] No .claude/evals/ directory — no formal eval definitions
+  [MISSING] No CI/CD test step detected
+  [MISSING] Context budget never audited
+  [WEAK]    Only 4 hooks installed (recommended: 8+)
+
+Top 3 Actions:
+  1. Run /sk:eval define to create eval definitions (+4 points)
+  2. Add CI/CD test workflow (+2 points)
+  3. Run /sk:context-budget to audit token usage (+3 points)
+```
+
+### Rating Scale
+
+| Score | Rating |
+|-------|--------|
+| 60-70 | EXCELLENT |
+| 45-59 | GOOD |
+| 30-44 | FAIR |
+| 15-29 | NEEDS WORK |
+| 0-14 | CRITICAL |

package/skills/sk:learn/SKILL.md

@@ -0,0 +1,138 @@
+---
+name: sk:learn
+description: "Extract reusable patterns from the current session into learned instincts."
+---
+
+# /sk:learn — Extract Reusable Patterns
+
+Analyzes the current session for extractable patterns and saves them as learned instincts. Patterns evolve from tentative observations into strong conventions over time.
+
+## Usage
+
+```
+/sk:learn                  # analyze current session
+/sk:learn --list           # show all learned patterns
+/sk:learn --promote <id>   # promote project pattern to global
+/sk:learn --export         # export patterns as shareable file
+```
+
+## Model Routing
+
+Read `.shipkit/config.json` from the project root if it exists.
+
+| Profile | Model |
+|---------|-------|
+| `full-sail` | haiku |
+| `quality` | haiku |
+| `balanced` | haiku |
+| `budget` | haiku |
+
+> Pattern detection is lightweight keyword matching — haiku is sufficient.
+
+## How It Works
+
+### Phase 1: Session Analysis
+
+Scan the current conversation for extractable patterns:
+
+1. **Error resolutions** — problems encountered and how they were solved
+2. **Debugging techniques** — investigation steps that led to root causes
+3. **Workarounds** — non-obvious solutions to framework/tool limitations
+4. **Project conventions** — naming patterns, file organization, code style decisions
+5. **Tool usage patterns** — effective tool combinations and sequences
+
+Filter out trivial items:
+- Typo fixes, syntax errors, simple formatting
+- One-off configuration changes
+- Standard framework usage (documented in official docs)
+
+### Phase 2: Pattern Extraction
+
+For each candidate pattern, extract:
+
+```markdown
+---
+name: [descriptive-slug]
+type: [error-resolution | debugging | workaround | convention | tool-usage]
+confidence: [0.3 | 0.5 | 0.7 | 0.9]
+scope: [project | global]
+created: [YYYY-MM-DD]
+seen_count: 1
+---
+
+## Problem
+[What triggered this pattern]
+
+## Solution
+[What resolved it — specific steps]
+
+## Example
+[Concrete code or command example]
+
+## When to Apply
+[Conditions that indicate this pattern is relevant]
+```
+
+### Phase 3: Confidence Scoring
+
+| Score | Label | Meaning |
+|-------|-------|---------|
+| 0.3 | tentative | Seen once, might be coincidence |
+| 0.5 | emerging | Seen in similar contexts, likely a real pattern |
+| 0.7 | strong | Proven effective multiple times |
+| 0.9 | near-certain | Battle-tested, consistently reliable |
+
+New patterns start at 0.3. Confidence increases when:
+- Same pattern seen again in a different session (+0.2)
+- User explicitly confirms the pattern (+0.2)
+- Pattern seen in a different project (+0.1, also promotes to global)
+
+### Phase 4: Storage
+
+- **Project patterns**: `~/.claude/skills/learned/[project-name]/[pattern-name].md`
+- **Global patterns**: `~/.claude/skills/learned/global/[pattern-name].md`
+
+### Phase 5: User Confirmation
+
+Present extracted patterns and ask for confirmation before saving:
+
+```
+Extracted 3 patterns from this session:
+
+1. [error-resolution] "laravel-queue-retry-after" (0.3 tentative)
+   Problem: Queue jobs silently failing after Redis timeout
+   Solution: Set retry_after in queue config > job timeout
+
+2. [convention] "api-resource-wrapping" (0.3 tentative)
+   Problem: Inconsistent API response format
+   Solution: Always wrap in ApiResource with data key
+
+3. [tool-usage] "parallel-explore-before-implement" (0.3 tentative)
+   Problem: Missing context leads to wrong implementation
+   Solution: Launch 3 Explore agents before writing code
+
+Save patterns? (all / 1,3 / none)
+```
+
+## Promotion: Project to Global
+
+A pattern is auto-promoted to global when:
+- Same pattern (by name or content similarity) appears in 2+ projects
+- Confidence >= 0.7 in both projects
+- User hasn't marked it as project-specific
+
+Manual promotion: `/sk:learn --promote <pattern-id>`
+
+## Export / Import
+
+Export all patterns for sharing:
+```
+/sk:learn --export > my-patterns.json
+```
+
+Import from a colleague:
+```
+/sk:learn --import colleague-patterns.json
+```
+
+Imported patterns start at 0.3 confidence regardless of source confidence.

package/skills/sk:lint/SKILL.md

@@ -111,10 +111,10 @@ If any analyzer reports errors or the dep audit blocks:
 2. Re-run formatters (fixes may need formatting)
 3. Re-launch all analyzers in parallel
 4. Re-run dep audit if any dependency was fixed
-5. Auto-commit with message `fix(lint): resolve lint and dep audit issues` — do NOT ask the user
-6. Re-run from step 3 until every tool exits clean
+5. Re-run from step 3 until every tool exits clean
+6. Once all tools pass clean, make ONE squash commit: `fix(lint): resolve lint and dep audit issues` — do NOT ask the user
 
-> Gates own their commits — the fix-commit-rerun loop is fully internal. No manual commit step needed after this gate.
+> Squash gate commits — collect all fixes for the pass, then one commit. Do not commit after each individual fix.
 
 ### 7. Report Results
 

package/skills/sk:perf/SKILL.md

@@ -12,8 +12,8 @@ Run this skill after implementing and passing lint/tests, but before `/sk:review
 
 ## Hard Rules
 
-- **Fix all critical and high in-scope findings** (files in `git diff main..HEAD --name-only`) immediately after the audit. Auto-commit with `fix(perf): resolve [severity] performance findings`. Re-run the audit until critical/high = 0.
-- **Medium/low in-scope findings:** fix them in the same commit if straightforward, otherwise log to `tasks/tech-debt.md`.
+- **Fix all critical and high in-scope findings** (files in `git diff main..HEAD --name-only`) immediately after the audit. Re-run the audit until critical/high = 0. Once clean, make ONE squash commit: `fix(perf): resolve performance findings`.
+- **Medium/low in-scope findings:** fix them in the same pass if straightforward, otherwise log to `tasks/tech-debt.md`.
 - **Pre-existing findings** (files outside the current branch diff): log to `tasks/tech-debt.md` using this format — do NOT fix inline:
   ```
   ### [YYYY-MM-DD] Found during: sk:perf
@@ -21,7 +21,7 @@ Run this skill after implementing and passing lint/tests, but before `/sk:review
   Issue: description of the performance issue
   Severity: critical | high | medium | low
   ```
-- **Gates own their commits** — the fix-commit-rerun loop is fully internal. No manual commit step needed after this gate.
+- **Squash gate commits** — collect all fixes for the pass, then one commit. Do not commit after each individual fix.
 - **Every finding must cite a specific file and line number.**
 - **Every finding must include an estimated impact** (high/medium/low) and a recommendation.
 - **Auto-detect the stack** — only run checks relevant to what's present.