godpowers 0.15.0

package/references/building/BUILD-VERTICAL-SLICES.md

@@ -0,0 +1,75 @@
+# Vertical Slices
+
+> A slice delivers ONE user-visible behavior end-to-end. Not "set up the
+> database." That's horizontal.
+
+## Vertical vs horizontal
+
+### Horizontal (rejected)
+- "Set up the database"
+- "Build the API layer"
+- "Create the UI components"
+
+User can't do anything until ALL three ship. High WIP, late integration.
+
+### Vertical (accepted)
+- "User can sign up with email and password"
+- "User can connect their Stripe account"
+- "User sees current MRR on the dashboard"
+
+Each one ships independently. User sees value progressively.
+
+## Anatomy of a slice
+
+```
+Slice 1.3: User can connect Stripe account
+
+Files:
+- src/auth/stripe-oauth-init.ts
+- src/auth/stripe-oauth-init.test.ts
+- src/auth/stripe-oauth-callback.ts
+- src/auth/stripe-oauth-callback.test.ts
+- src/db/migrations/003_stripe_accounts.sql
+- src/components/StripeConnectButton.tsx
+- src/components/StripeConnectButton.test.tsx
+
+Tests first (in order, RED -> GREEN -> REFACTOR):
+1. test: oauth_init_returns_authorize_url
+2. test: oauth_init_includes_csrf_state
+3. test: oauth_callback_validates_state
+4. test: oauth_callback_stores_encrypted_token
+5. test: oauth_callback_redirects_to_dashboard
+
+Implementation steps:
+1. RED: write all 5 tests above; run; all fail
+2. GREEN: implement init -> callback flow until tests pass
+3. REFACTOR: extract common state validation; clean up
+
+Verification:
+- All 5 tests green
+- Manual: complete OAuth flow in dev environment
+- Token visible in stripe_accounts table (encrypted)
+- User redirected to dashboard
+
+Dependencies: Slice 1.1 (signup), Slice 1.2 (login)
+Wave: 2
+```
+
+## Common mistakes
+
+### Slice too big
+"User can use the entire dashboard" is not a slice. It's a milestone.
+
+Break it: "User can see MRR card", "User can see growth chart", etc.
+
+### Slice not user-visible
+"Refactor the auth middleware" is not a slice (no user behavior changes).
+That's a refactor; route to /god-refactor.
+
+### Slice has hidden dependencies
+"User can export CSV" depends on data-fetch slice, which depends on auth
+slice. Make dependencies explicit.
+
+### Slice spans multiple commits
+A slice is one atomic commit. If it takes 5 commits to land safely, it's
+too big.

package/references/building/BUILD-WAVES.md

@@ -0,0 +1,61 @@
+# Build Waves
+
+> Independent slices run in parallel within a wave. Waves run sequentially.
+> Maximizes throughput; minimizes context rot.
+
+## Detection
+
+Two slices can be in the same wave if:
+- They modify different files (no merge conflicts)
+- They don't depend on each other's output
+- Neither needs the other's data
+
+## Worked example
+
+Milestone: User can see MRR breakdown.
+
+### Slice plan
+
+| Slice | Files | Depends on |
+|-------|-------|------------|
+| 1.1 Signup | src/auth/signup.ts | none |
+| 1.2 Login | src/auth/login.ts | 1.1 |
+| 1.3 Stripe OAuth | src/auth/stripe-*.ts, src/db/stripe_accounts | 1.1, 1.2 |
+| 1.4 Stripe sync worker | src/worker/stripe-sync.ts | 1.3 |
+| 1.5 MRR query API | src/api/mrr.ts | 1.3, 1.4 |
+| 1.6 Dashboard UI | src/components/Dashboard.tsx | 1.5 |
+
+### Wave grouping
+
+- Wave 1: Slice 1.1 (no dependencies)
+- Wave 2: Slice 1.2 (depends on 1.1)
+- Wave 3: Slice 1.3 (depends on 1.1, 1.2)
+- Wave 4: Slice 1.4 + Slice 1.5 (parallel; 1.4 worker writes, 1.5 API reads, but different files)
+- Wave 5: Slice 1.6 (depends on 1.5)
+
+In Wave 4, two agents work in parallel on different files. Each gets fresh
+context. Each enforces TDD. Each goes through two-stage review independently.
+
+## Anti-patterns
+
+### Wave too wide
+Putting 10 parallel slices in one wave. Even if technically independent,
+review and integration become coordination heavy.
+
+**Rule of thumb**: max 3-4 parallel slices per wave.
+
+### Hidden cross-wave dependency
+Slice 4.1 thinks it's independent but actually reads a config file that
+Slice 4.2 modifies. Race condition.
+
+**Fix**: spell out READ dependencies, not just WRITE dependencies.
+
+### Sequential when parallel-safe
+Putting Slice X and Slice Y in different waves when they're actually
+independent.
+
+**Cost**: wasted wall-clock time. Each agent runs serially when they could
+run in parallel.
+
+**Fix**: at planning time, look hard for shared file modifications. If none,
+parallelize.

package/references/building/README.md

@@ -0,0 +1,17 @@
+# Building References
+
+Per-tier reference content for Tier 2 (Building: Repo, Build).
+
+## Files
+
+- (placeholder)
+
+## Planned content
+
+- TDD violation examples with how-to-fix
+- Two-stage review checklists with worked findings
+- Vertical slice anatomy with anti-examples (horizontal "set up the database")
+- Atomic commit examples
+- Wave parallelism dependency analysis worked examples
+
+See [HAVE-NOTS.md](../HAVE-NOTS.md) for the canonical failure-mode catalog.

package/references/design/COLOR.md

@@ -0,0 +1,122 @@
+# Color
+
+> Godpowers' baseline guidance for color. Shallower than
+> [Impeccable's color-and-contrast reference](https://github.com/pbakaus/impeccable/blob/main/skill/reference/color-and-contrast.md);
+> use this when Impeccable isn't installed.
+
+## Use OKLCH
+
+Modern displays support wide gamuts. OKLCH gives you:
+
+- Perceptually uniform lightness (a 60% L color reads as the same
+  brightness regardless of hue)
+- Predictable contrast adjustments (drop L by 10 to darken, period)
+- Wide-gamut accuracy for modern displays
+- A graceful fallback through CSS Color 4
+
+```yaml
+colors:
+  ink: "oklch(20% 0.01 250)"     # near-black, slight blue cast
+  paper: "oklch(98% 0.005 80)"   # warm white
+  accent: "oklch(60% 0.18 250)"  # blue accent
+```
+
+If your linter requires hex (e.g., Google Stitch): use hex for tokens,
+add OKLCH equivalents in CSS variables, document both.
+
+## The 5-color rule
+
+A small palette ships faster and looks more confident than a large one.
+Aim for:
+
+1. **ink** - body text and headlines
+2. **paper** - canvas / background
+3. **rule** - borders, dividers, hairlines
+4. **accent** - the one chromatic color used for action and emphasis
+5. **muted** - secondary text, disabled states
+
+Add growth/shrink (positive/negative) only if the product has
+directional data (charts, dashboards). Add success/warning/danger only
+if the product has stateful UI (forms, alerts). Otherwise stop at 5.
+
+## Anti-patterns
+
+- **Purple-to-blue gradients on CTAs.** The default of every AI-built
+  SaaS in 2024-2025. Tells.
+- **Pure black (#000) on pure white (#fff).** Too much contrast at
+  large sizes; eye-tiring on long reads. Use near-black (10-15% L).
+- **Gray text on colored backgrounds.** Gray on cream looks like CSS
+  rendering broke. Use a colored variant matched to the background.
+- **Rainbow palettes.** Six chromatic colors competing. Pick one.
+- **Bright Material-style red for errors.** Reserved for genuine
+  destructive actions, not validation messages.
+
+## Contrast (WCAG)
+
+| Ratio | Level | Use |
+|---|---|---|
+| 3:1 | AA Large (>=18pt or 14pt bold) | Display headlines |
+| 4.5:1 | AA Normal | Body text, labels, links |
+| 7:1 | AAA Normal | High-bar accessibility |
+| 4.5:1 | AA non-text | Icons, focus rings, borders |
+
+The runtime audit (Phase 11) checks 4.5:1 on text-on-background
+components. Below that, BLOCK.
+
+### Common pairings that work
+
+| Background | Text | Ratio |
+|---|---|---|
+| `#1a1c1e` (near-black) | `#f7f8f8` (paper) | 18.4 (AAA) |
+| `#fafafa` (paper) | `#0f1011` (deep) | 19.7 (AAA) |
+| `#f4ebdc` (cream) | `#1f1a15` (ink) | 13.5 (AAA) |
+
+### Common pairings that fail
+
+| Background | Text | Ratio | Status |
+|---|---|---|---|
+| `#fda4af` (pink) | `#ffffff` | 1.8 | Fail |
+| `#a3a3a3` (gray) | `#ffffff` | 2.6 | Fail |
+| `#1f1a15` (dark) | `#5b4f44` (taupe) | 5.9 | Pass AA |
+
+## Dark mode
+
+If you support dark mode, design it as its own surface, not an
+inversion. Tokens needed:
+
+```yaml
+colors:
+  canvas-light: "oklch(98% 0.005 80)"
+  canvas-dark: "oklch(15% 0.01 250)"
+  ink-light: "oklch(20% 0.01 250)"   # on light canvas
+  ink-dark: "oklch(95% 0.01 250)"    # on dark canvas
+```
+
+Mapping rule: dark mode lowers contrast slightly (16:1 -> 12:1) to
+reduce eye strain. Don't simply invert; that produces glaring
+reverse-contrast surfaces.
+
+## Tinted neutrals
+
+Pure grays look industrial and cold. Tint your neutrals toward the
+accent's hue family:
+
+```yaml
+colors:
+  # accent is blue (250 hue); tint neutrals toward 250
+  ink: "oklch(20% 0.01 250)"     # subtly blue-cast
+  rule: "oklch(88% 0.005 250)"   # subtly blue-cast border
+```
+
+Even 0.005 chroma at the same hue makes neutrals feel intentional.
+
+## Have-Nots
+
+You fail color if:
+
+- Pure #000000 or #ffffff in regular text use
+- Purple-blue gradient on primary CTA
+- Gray text on colored background
+- More than 5 base colors before semantic additions
+- WCAG AA fail on any text-on-background component
+- More than 3 chromatic colors in the palette

package/references/design/DESIGN-ANATOMY.md

@@ -0,0 +1,121 @@
+# DESIGN.md Anatomy
+
+> What a good DESIGN.md looks like. Format follows the
+> [Google Labs design.md spec](https://github.com/google-labs-code/design.md);
+> tone and discipline follow the
+> [Impeccable skill](https://github.com/pbakaus/impeccable).
+
+## Structure
+
+A DESIGN.md has two layers:
+
+1. **YAML frontmatter** (machine-readable design tokens, delimited by `---`)
+2. **Markdown body** (human-readable rationale organized into `##` sections)
+
+The tokens are normative. The prose explains how to apply them.
+
+## Required frontmatter fields
+
+| Field | Required | Format |
+|---|---|---|
+| `name` | yes | string (e.g., "Heritage", "MRR Tracker") |
+| `description` | yes | one-line summary of the visual register |
+| `colors` | yes if visual surface | map of token-name -> color value |
+| `typography` | yes if visual surface | map of style-name -> typography object |
+| `rounded` | optional | map of scale-level -> dimension |
+| `spacing` | yes if visual surface | map of scale-level -> dimension |
+| `components` | optional | map of component-name -> sub-token map |
+
+## Section order
+
+Use `##` headings. Sections can be omitted; those present must appear in this order:
+
+| # | Section | Aliases |
+|---|---|---|
+| 1 | Overview | Brand & Style |
+| 2 | Colors | |
+| 3 | Typography | |
+| 4 | Layout | Layout & Spacing |
+| 5 | Elevation & Depth | Elevation |
+| 6 | Shapes | |
+| 7 | Components | |
+| 8 | Do's and Don'ts | |
+
+Duplicate `##` headings are an error.
+
+## Token references
+
+Components can reference tokens via curly-brace syntax: `{colors.primary}`,
+`{rounded.sm}`. Token references must resolve to a defined token.
+
+```yaml
+components:
+  button-primary:
+    backgroundColor: "{colors.tertiary}"
+    textColor: "{colors.on-tertiary}"
+    rounded: "{rounded.sm}"
+    padding: 12px
+```
+
+## What "good" looks like
+
+A good DESIGN.md:
+
+- [DECISION] Names a register: brand or product. Brand surfaces (marketing,
+  landing) are ornamental. Product surfaces (app shell, dashboards) serve
+  the data.
+- [DECISION] Uses OKLCH for colors when wide-gamut accuracy matters.
+  Falls back to hex sRGB for compatibility with linters that don't yet
+  parse OKLCH.
+- [DECISION] Sets typography for one or two type families maximum. The
+  display family may differ from the body family if the register calls
+  for it.
+- [DECISION] Names every component used in the UI. Variants (hover,
+  active, disabled) are separate component entries with related keys.
+- [DECISION] Includes a Do's and Don'ts section with explicit
+  anti-patterns: what NOT to do for this design.
+- [DECISION] Stays under 300 lines. Heavy detail (component variations,
+  edge cases) lives in code documentation, not DESIGN.md.
+
+## What "bad" looks like
+
+See [DESIGN-ANTIPATTERNS.md](./DESIGN-ANTIPATTERNS.md).
+
+## Validation
+
+Every DESIGN.md should pass:
+
+- `npx @google/design.md lint DESIGN.md` (Google Labs spec linter)
+- `npx impeccable detect DESIGN.md` (Impeccable anti-patterns)
+
+Godpowers' god-design-reviewer agent runs both as part of the two-stage
+review gate.
+
+## Worked example
+
+See `examples/saas-mrr-tracker/DESIGN.md` for a complete, lint-clean example.
+
+## Domain-specific references
+
+These shorter, focused references cover the 7 design domains at
+shallower depth than Impeccable's full skill set. Used by god-designer
+when Impeccable is not installed; useful as a baseline regardless:
+
+- [TYPOGRAPHY.md](./TYPOGRAPHY.md) - type families, scales, line-height,
+  tabular numerals
+- [COLOR.md](./COLOR.md) - OKLCH, 5-color rule, WCAG contrast,
+  dark mode, tinted neutrals
+- [SPATIAL.md](./SPATIAL.md) - spacing scales, grids, touch targets,
+  vertical rhythm
+- [MOTION.md](./MOTION.md) - durations, easings, prefers-reduced-motion,
+  staggering
+- [INTERACTION.md](./INTERACTION.md) - forms, focus states, buttons,
+  loading patterns, empty states
+- [RESPONSIVE.md](./RESPONSIVE.md) - breakpoints, mobile-first, touch
+  targets, container queries
+- [UX-WRITING.md](./UX-WRITING.md) - button labels, error messages,
+  empty states, tone calibration
+
+For deeper guidance on any domain, install
+[Impeccable](https://github.com/pbakaus/impeccable) and use its 7
+domain-specific skills.

package/references/design/DESIGN-ANTIPATTERNS.md

@@ -0,0 +1,108 @@
+# DESIGN.md Antipatterns
+
+> Common ways DESIGN.md fails. Each has a sample, why it fails, and the fix.
+
+## 1. The Tellable Token Set
+
+**Sample**: `colors.primary: "#4f46e5"` (purple-blue), `colors.gradient:
+"linear-gradient(...)"`, every heading uses Inter, every CTA uses an
+indigo-to-purple gradient.
+
+**Why it fails**: Every AI-generated SaaS in 2024-2025 uses this palette.
+The tokens betray that the design system was generated, not chosen.
+
+**Fix**: Pick a register first (brand vs product) and a reference (a real
+brand whose voice resembles yours). Avoid the 5 tells: Inter everywhere,
+purple-blue gradients, cards-in-cards, gray text on colored backgrounds,
+rounded-square icon tiles above every heading.
+
+## 2. The Reference That Doesn't Resolve
+
+**Sample**:
+```yaml
+components:
+  button-primary:
+    backgroundColor: "{colors.tertiary}"
+    textColor: "{colors.on-tertiary}"
+```
+But `colors.tertiary` is not defined in the colors block.
+
+**Why it fails**: Token references break silently. The UI renders with
+fallback colors that don't match the design intent.
+
+**Fix**: Run the Google Labs linter; it catches unresolved references
+mechanically. The god-design-reviewer agent gates on this.
+
+## 3. The Theme Without a Reason
+
+**Sample**: DESIGN.md exists but has no Overview section explaining the
+visual register or rationale.
+
+**Why it fails**: Future agents (and team members) don't know what the
+design is meant to feel like. The first refactor or new component drifts
+toward whatever the current contributor's defaults are.
+
+**Fix**: Overview section answers two questions: "what register is this?"
+(brand vs product) and "what does it feel like?" (one-paragraph mood
+description grounded in named references).
+
+## 4. The Component Sprawl
+
+**Sample**: `components` block has 50 entries: every shade of every
+button variant, every modal type, every input state.
+
+**Why it fails**: 50 components means 50 places drift can hide. Each is
+usually slightly inconsistent. The system becomes its own anti-system.
+
+**Fix**: Name only the canonical components. Variants (hover, active,
+disabled) are systematic, not bespoke. If you have 50 components, you
+have a redundancy problem.
+
+## 5. The Contrast Failure
+
+**Sample**: `colors.cta-bg: "#fda4af"` (light pink), `colors.cta-text:
+"#ffffff"` (white). Contrast ratio: 1.8:1. WCAG AA fails.
+
+**Why it fails**: The button is unreadable for users with low vision,
+in bright sunlight, or on calibrated-low-contrast displays. Often
+unreadable for everyone.
+
+**Fix**: Linter computes WCAG contrast ratio for every text-on-background
+component pair. Anything below 4.5:1 (AA) is BLOCKED by the design
+reviewer. AAA requires 7:1.
+
+## 6. The Stale Tokens
+
+**Sample**: DESIGN.md says `colors.primary: "#1A1C1E"`. The actual app
+uses `#000000` because someone "fixed it" in the CSS without updating
+the spec.
+
+**Why it fails**: DESIGN.md becomes aspirational. Code is the source of
+truth; nobody trusts the spec.
+
+**Fix**: Reverse-sync (Phase 6) detects drift between DESIGN.md tokens
+and actual usage in CSS/styled-components. Drift findings flow into
+REVIEW-REQUIRED.md.
+
+## 7. The Missing Anti-References
+
+**Sample**: PRODUCT.md says "we want a calm, editorial feel." DESIGN.md
+implements the colors and typography but doesn't list what to avoid.
+
+**Why it fails**: AI agents and developers look for cues. Without explicit
+anti-references, they import patterns from popular component libraries
+(shadcn defaults, Material Design) that may not match the intended feel.
+
+**Fix**: Do's and Don'ts section names specific patterns to avoid:
+"don't use bright primary blue (would feel category-AI)", "don't nest
+cards inside cards", "don't use gradients."
+
+## 8. The Token Without a Use
+
+**Sample**: 30 colors defined; only 8 referenced in components.
+
+**Why it fails**: Unused tokens are dead weight. They suggest options
+that aren't actually offered. Future contributors apply them
+incorrectly because they exist.
+
+**Fix**: Linter reports unused tokens. Remove or use them.

package/references/design/INTERACTION.md

@@ -0,0 +1,148 @@
+# Interaction Design
+
+> Godpowers' baseline guidance for forms, focus, and feedback.
+> Shallower than
+> [Impeccable's interaction-design reference](https://github.com/pbakaus/impeccable/blob/main/skill/reference/interaction-design.md).
+
+## Focus states are not optional
+
+Every interactive element gets a visible focus state:
+
+```css
+:focus-visible {
+  outline: 2px solid var(--colors-accent);
+  outline-offset: 2px;
+}
+```
+
+Use `:focus-visible` (not `:focus`) so mouse clicks don't show focus
+rings while keyboard navigation does.
+
+The ring color must pass 3:1 contrast against both surface AND its
+adjacent surface. Yellow rings on green surfaces fail that.
+
+## Forms
+
+### Labels above, errors below
+
+```
+[Email]
++----------------+
+| user@example.. |
++----------------+
+Please use a valid work email.
+```
+
+Inline labels (placeholder-only) lose context once typing starts. Use
+real labels.
+
+### Error messaging
+
+Three rules:
+
+1. **Specific.** "Invalid email" is bad. "Email must include @ and a
+   domain" is better. "alice@example is missing the .com" is best.
+2. **Forward-looking.** Tell the user what to do, not what they did
+   wrong. "Please use a work email address" beats "Personal addresses
+   are not allowed."
+3. **Inline, not modal.** Modal alerts for form errors are aggressive.
+   Place the message under the field that errored.
+
+### When to validate
+
+- **On submit**: always
+- **On blur**: yes for required fields and format-specific (email,
+  date, phone)
+- **On input**: only for soft hints (password strength, character count,
+  username availability). Not for "this is wrong" messages until blur.
+
+### Required fields
+
+Mark with a visible indicator (asterisk + colored to accent) AND
+include a short note: "Fields marked with * are required." Don't rely
+on color alone.
+
+## Buttons
+
+### Hierarchy
+
+| Type | When | Visual |
+|---|---|---|
+| Primary | The one main action of the screen | Filled accent color |
+| Secondary | Important but not primary | Outlined or tinted |
+| Tertiary / link | Low-priority or destructive | Text-style, possibly underlined |
+| Destructive | Delete, cancel-with-loss | Filled red OR confirmation modal |
+
+One primary per screen. More than one creates ambiguity.
+
+### Anti-patterns
+
+- **All buttons the same weight.** No visual hierarchy.
+- **Disabled buttons with no explanation.** If a button is disabled,
+  tell the user why (in a tooltip or below).
+- **Icon-only buttons without aria-label.** Screen readers say nothing.
+- **Two-line button labels.** Wrap is fine, but if your CTA reads on
+  multiple lines you've buried the action.
+
+## Loading and feedback
+
+| Action | Feedback |
+|---|---|
+| < 200ms | Nothing |
+| 200ms-1s | Spinner inside the button |
+| 1-3s | Skeleton in the affected region |
+| 3-10s | Progress bar with percentage if known |
+| > 10s | Background-task pattern: dismissible toast, "we'll notify you" |
+
+Always disable the trigger while the action is in flight. Re-enable on
+success / failure with appropriate state.
+
+## Confirmations
+
+Three patterns:
+
+1. **Inline confirmation** (default for reversible actions): "Item
+   deleted. Undo." with a 5-10s window.
+2. **Modal confirmation** (destructive, irreversible): "Delete account?
+   This cannot be undone." with explicit Yes/No.
+3. **Type to confirm** (catastrophic): "Type 'delete-production' to
+   confirm." for destructive cluster-wide operations.
+
+Modal everything is interruption theater.
+
+## Empty states
+
+A blank screen is a missed opportunity. Every empty state should:
+
+1. Explain what would normally be here
+2. Show how to populate it (the action that creates the first item)
+3. Optionally: a link to docs or a sample dataset
+
+Bad: "No data."
+Good: "No invoices yet. Connect Stripe to start tracking MRR."
+
+## Hover states
+
+For desktop:
+
+- Color shift: 10-15% lighter or darker
+- Cursor change for clickables (`cursor: pointer` only on actual
+  clickables)
+- Underline on text links (always; underline-on-hover only is bad
+  practice)
+
+For touch devices: hover is unavailable; design for tap-only.
+
+## Have-Nots
+
+You fail interaction if:
+
+- No `:focus-visible` outline
+- Focus ring contrast < 3:1 against both surfaces
+- Required fields marked with color alone
+- Error messages in modals (instead of inline)
+- Disabled buttons with no explanation
+- Icon-only buttons without aria-label
+- Empty states with no path forward
+- Clicks on non-buttons styled with `cursor: pointer`
+- Trigger not disabled during async action