Whiskerfolk — AAA cat-rescue vertical slice foundation

.github/workflows/whiskerfolk-ci.yml

@@ -0,0 +1,71 @@
+name: Whiskerfolk CI
+
+on:
+  push:
+    branches:
+      - kitty-crush-preproduction
+    paths:
+      - 'projects/kitty-crush/**'
+      - '.github/workflows/whiskerfolk-ci.yml'
+  pull_request:
+    branches:
+      - main
+    paths:
+      - 'projects/kitty-crush/**'
+      - '.github/workflows/whiskerfolk-ci.yml'
+
+concurrency:
+  group: whiskerfolk-ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  validate:
+    name: Static Contracts
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Validate web prototype syntax
+        run: node --check projects/kitty-crush/prototype-web/app.js
+
+      - name: Validate Godot main scene
+        run: grep -F 'run/main_scene="res://scenes/Main.tscn"' projects/kitty-crush/godot/project.godot
+
+      - name: Validate Android haptics permission
+        run: grep -F 'permissions/vibrate=true' projects/kitty-crush/godot/export_presets.cfg
+
+      - name: Validate third-party license retention
+        run: test -s projects/kitty-crush/godot/THIRD_PARTY_MATCH3_PETS_LICENSE.txt
+
+      - name: Guard runtime from test packages
+        run: |
+          if grep -qi 'xunit\|Microsoft.NET.Test.Sdk\|coverlet' projects/kitty-crush/godot/Whiskerfolk.csproj; then
+            echo "Test-only package leaked into runtime project."
+            exit 1
+          fi
+
+  test:
+    name: Build + Core Tests
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: projects/kitty-crush/godot
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup .NET 8
+        uses: actions/setup-dotnet@v4
+        with:
+          dotnet-version: '8.0.x'
+
+      - name: Restore tests
+        run: dotnet restore tests/Whiskerfolk.Tests.csproj
+
+      - name: Build Godot runtime
+        run: dotnet build Whiskerfolk.csproj --configuration Release
+
+      - name: Test engine-agnostic core
+        run: dotnet test tests/Whiskerfolk.Tests.csproj --configuration Release --logger "console;verbosity=normal"

projects/kitty-crush/ANALYTICS_AND_EXPERIMENTS.md

@@ -0,0 +1,74 @@
+# WHISKERFOLK — Analytics & Experimentation
+
+## North-star research question
+Does the player form a memorable relationship with Mochi before the end of session one?
+
+## First-session funnel
+1. app_start
+2. first_mochi_seen
+3. box_inspected
+4. first_puzzle_started
+5. first_puzzle_completed
+6. first_trust_response
+7. shelter_puzzle_completed
+8. rescue_started
+9. carrier_choice_completed
+10. box_moment_started
+11. box_moment_completed
+12. home_first_entry
+13. home_observation_30s
+14. first_object_interaction
+15. first_memory_created
+
+## Behavioral measures
+### Attachment proxies
+- seconds observing Mochi with no required input;
+- voluntary cat taps that are not goal-driven;
+- repeat Catbook opens;
+- memory opens/shares;
+- placement of objects near cat-favorite zones;
+- next-session time-to-first-cat-interaction.
+
+### Puzzle measures
+- first move latency;
+- invalid swap rate;
+- moves remaining;
+- retry rate;
+- cascade frequency;
+- objective comprehension.
+
+### Home measures
+- time before opening secondary UI;
+- number of autonomous behaviors observed;
+- number of object interactions;
+- object placement completion.
+
+## Qualitative playtest
+After session one ask, without showing prompts:
+1. What was the cat’s name?
+2. Tell me something about his personality.
+3. What moment do you remember most?
+4. What do you think Mochi likes?
+5. Would you open this tomorrow if no new level reward were waiting?
+6. What would you change in his room?
+7. Did any part feel like “another match-3”?
+
+## GO thresholds for small prototype study
+These are internal decision thresholds, not market guarantees:
+- ≥80% unaided Mochi name recall;
+- ≥70% can state one accurate personality trait;
+- ≥60% choose the Box Moment/rescue as a memorable moment rather than generic puzzle;
+- ≥50% say they would return primarily to see/continue with Mochi;
+- median ≥30 sec non-required Home observation;
+- <20% describe the product primarily as generic match-3.
+
+## Experiment order
+A/B only after baseline exists.
+
+1. Box Moment pacing: 12s vs 18s.
+2. Direct tutorial vs environmental tutorial.
+3. Objective world-change immediacy.
+4. Home UI delayed vs immediately available.
+5. First object: blanket vs scratcher.
+
+Never A/B core ethical rules.

projects/kitty-crush/BRAND_DIRECTION.md

@@ -0,0 +1,55 @@
+# WHISKERFOLK — Brand Direction v0.1
+
+## Working brand
+**WHISKERFOLK**
+
+Status: strong working title; not yet trademark-cleared.
+
+## Why this name
+- Cat-specific without saying "cat" generically.
+- Implies a family/community of distinct characters.
+- Scales beyond Mochi without losing emotional intimacy.
+- Does not anchor the product to match-3.
+- Supports IP, character pages, merch and social voice.
+
+## Brand promise
+**Every cat has a way of becoming part of your home.**
+
+## Product sentence
+A premium cozy mobile game where you find frightened cats, help them through tactile puzzles, earn their trust, bring them home, and discover their personalities as they begin to feel safe.
+
+## Emotional territory
+Warmth, rescue, trust, homecoming, quiet humor, tiny surprises, chosen family.
+
+## What WHISKERFOLK is NOT
+- shelter-management simulator;
+- Tamagotchi obligation loop;
+- gacha collector;
+- generic match-3 skin;
+- hyperactive kids UI;
+- sad-animal guilt product.
+
+## Verbal tone
+Short, warm, observant, never babyish.
+
+Good:
+- “He came back.”
+- “Mochi found the warm spot.”
+- “Someone moved your blanket.”
+- “He’s still deciding if you’re safe.”
+
+Avoid:
+- “OMG SO CUTE!!!”
+- “Your pet is starving!”
+- “Come back NOW or lose your streak.”
+- generic fantasy copy.
+
+## Logo direction
+A wordmark with one subtle feline behavior cue:
+- tail-like terminal stroke;
+- paired whisker cuts;
+- soft “W” silhouette;
+- no paw-print cliché as primary mark.
+
+## App icon direction
+Mochi’s face partly emerging from a box opening. Large eyes, asymmetrical ear/mark, warm interior light, no text.

projects/kitty-crush/DESIGN_SYSTEM.md

@@ -0,0 +1,105 @@
+# WHISKERFOLK — Premium Mobile Design System v0.1
+
+## Quality bar
+Premium-casual mobile: warm, tactile, elegant, character-first.
+
+The interface should feel expensive because it is **controlled**, not because it has more effects.
+
+## Composition
+The world occupies 80–90% of meaningful visual attention.
+UI floats only where necessary.
+
+### Home
+- no dashboard grid;
+- one unobtrusive top status strip at most;
+- contextual controls appear after tapping cat/object;
+- collections live in bottom sheets;
+- primary CTA appears only when the player has a clear next rescue beat.
+
+### Puzzle
+- board dominates;
+- rescue objective visible as world context above/behind board;
+- moves/objective compact;
+- boosters secondary;
+- no casino clutter.
+
+## Visual DNA
+### Base colors
+- Ink: #27312E
+- Soft ink: #51605B
+- Milk: #FFF9EF
+- Warm paper: #F5E9D7
+- Moss: #6F8F78
+- Sage light: #AFC8B4
+- Caramel: #C88B5A
+- Peach light: #F2C7A8
+- Rain blue: #7896A6
+- Night blue: #273B49
+
+### Accent rule
+One emotional accent per scene.
+Do not run blue, purple, pink, green and gold simultaneously.
+
+## Shape language
+- radius family: 14 / 20 / 28;
+- cards only when content genuinely needs containment;
+- no nested-card labyrinth;
+- large soft silhouettes;
+- minimal borders;
+- shadows broad and low-contrast.
+
+## Typography
+Use one rounded humanist sans family with:
+- Display: 700
+- Title: 650
+- Body: 450–500
+- Caption: 550
+
+No more than 4 text sizes on a normal screen.
+
+## Touch
+- minimum 48 dp target;
+- primary tap areas 56–64 dp;
+- destructive/exit actions visually separated;
+- back behavior always predictable.
+
+## Motion
+### UI
+- 160–220ms micro transitions;
+- 280–420ms sheets;
+- ease-out for entry;
+- ease-in for exit;
+- no gratuitous bounce.
+
+### World
+Animals use slower asymmetric timing.
+The cat may pause before completing an animation.
+
+## Particle budget
+Routine:
+0–8 particles.
+Special:
+8–24.
+Signature rescue moments:
+controlled cinematic particles only when motivated by environment.
+
+## Haptic hierarchy
+1. micro selection — very light
+2. match — light
+3. special creation — medium-soft
+4. rescue success — medium
+5. box latch/open — distinctive single pulse
+6. affection milestone — subtle double pulse
+
+## Accessibility
+- no color-only puzzle types;
+- pattern/shape distinction;
+- reduced motion mode;
+- haptics toggle;
+- subtitles/captions for meaningful vocalization cues;
+- contrast target AA where text is involved;
+- respect larger system text where possible.
+
+## Performance
+Visual quality must not depend on huge overdraw or 4K assets.
+Use atlases, compressed textures, pooled FX, scene culling and limited simultaneous live actors.

projects/kitty-crush/INITIAL_ROSTER.md

@@ -0,0 +1,73 @@
+# WHISKERFOLK — Initial Eight-Cat Roster
+
+Only Mochi is P0 production. Cats 2–8 remain design-ready until Mochi passes attachment validation.
+
+## 1. Mochi — The Cautious Observer
+Visual: cream coat, caramel ear/eye comma, moss-green eyes.
+Rescue: rainy storefront box.
+Favorite object: cardboard box.
+Signature: approaches, retreats, looks back, returns.
+Relationship lesson: safety is chosen, not forced.
+
+## 2. Churro — The Confident Food Critic
+Visual: long orange tabby, darker cinnamon stripes, white chin.
+Rescue: bakery loading alley where he has learned delivery schedules.
+Favorite object: kitchen mat / puzzle feeder.
+Signature: inspects every bowl, pushes the “wrong” one aside.
+Personality: social, shameless, opportunistic, dramatic about food.
+Relationship lesson: affection can look like showing up every day.
+
+## 3. Nori — The High-Ground Strategist
+Visual: near-black coat with blue-green sheen and one white toe.
+Rescue: rooftop/service stairwell.
+Favorite object: tall shelf / window perch.
+Signature: watches from above before dropping silently into the room.
+Personality: independent, calm, highly observant.
+Relationship lesson: proximity is not the only form of trust.
+
+## 4. Chispa — The Kinetic Calico
+Visual: compact calico with one orange “lightning” face patch.
+Rescue: mechanic courtyard full of moving objects and hiding spots.
+Favorite object: feather wand / rolling spring.
+Signature: pounce → skid → pretend it was intentional.
+Personality: fearless curiosity, short attention, comic confidence.
+Relationship lesson: safety can unlock play.
+
+## 5. Trufa — The Soft Giant
+Visual: broad brown tabby, plush cheeks, tiny serious eyes.
+Rescue: quiet park storage shed.
+Favorite object: oversized cushion.
+Signature: slowly occupies an object clearly too small for him.
+Personality: patient, tactile, comfort-seeking.
+Relationship lesson: calm presence can be deeply expressive.
+
+## 6. Luma — The Sun Collector
+Visual: pale silver coat, warm cream chest, amber eyes.
+Rescue: greenhouse/service garden.
+Favorite object: sun patch / woven mat.
+Signature: relocates with the sun throughout the day.
+Personality: gentle, routine-loving, easily fascinated by light.
+Relationship lesson: home becomes a map of safe places.
+
+## 7. Tinta — The Tiny Engineer
+Visual: tuxedo cat with ink-black mask and white “gloves”.
+Rescue: back room where she repeatedly opens a loose cabinet.
+Favorite object: puzzle box / cabinet latch.
+Signature: studies mechanisms, then solves them.
+Personality: clever, persistent, mildly mischievous.
+Relationship lesson: intelligence itself becomes character.
+
+## 8. Pipa — The Social Bridge
+Visual: tortoiseshell with a warm split-color muzzle.
+Rescue: community courtyard where several cats tolerate her.
+Favorite object: shared blanket.
+Signature: inserts herself exactly between two cats and settles.
+Personality: socially bold, adaptable, affectionate without clinginess.
+Relationship lesson: later cats change earlier cats.
+
+# Roster rules
+- No duplicate silhouette.
+- No “same cat, different fur”.
+- Every cat changes the room behavior graph.
+- Every rescue teaches a different kind of trust.
+- Each cat must own one screenshot-worthy behavior.