docs(onboarding): add Surf — deterministic testbed management suite (…

onboarding/.codewhale/commands/surf-setup.md

@@ -0,0 +1,4 @@
+---
+execute: .codewhale/skills/surf/scripts/catch-wave.sh
+description: "🌊 Catch a new wave. Clones a repository and initializes a testbed."
+---

onboarding/.codewhale/commands/surf.md

@@ -0,0 +1,35 @@
+---
+execute: .codewhale/skills/surf/scripts/surf.sh
+description: "🌊 Ride the CodeWhale wave. Updates, builds, and tests the testbed."
+---
+
+# 🌊 Surf — Ride the CodeWhale Wave
+
+This command runs the deterministic core of the Surf suite. It checks the current environment, updates the testbed if possible, and outputs a receipt.
+
+## Behavior
+
+| State | Action |
+|---|---|
+| **Empty directory** | Tells you to run `/surf setup` |
+| **Clean testbed** | Pulls, builds, tests, writes receipt |
+| **Dirty testbed** | Stops with a warning |
+| **Unknown repo** | Stops with guidance |
+
+## Sub-Commands
+
+| Command | Action |
+|---|---|
+| `/surf` | Runs the main orchestrator |
+| `/surf setup` | Clones the repo and initializes a testbed |
+
+## Example
+
+```text
+/surf
+🌊 Checking the wave...
+🌊 Wave is clean. Riding...
+...
+✅ Surf complete.
+📄 Receipt written: receipts/latest_receipt.json
+```

onboarding/.codewhale/skills/surf/SKILL.md

@@ -0,0 +1,80 @@
+# Skill: Onboarding Suite 🐋
+
+## Name
+`onboarding-suite`
+
+## Description
+Keeps your isolated CodeWhale testbed in sync with the latest `main` branch. It runs a deterministic core (no LLM required) to pull, build, verify, and generate a digest. Optionally, it can enhance the digest with an LLM‑generated summary if you request it.
+
+## Triggers
+- `/onboarding-suite` – runs the deterministic core only.
+- `/onboarding-suite --summary` – runs the deterministic core and appends an LLM summary.
+
+---
+
+## Deterministic Core (Always Runs)
+
+The core uses three Bash scripts located in the same directory as this skill under `scripts/`. It does not require an internet connection except for `git pull`.
+
+1. **Environment Check**  
+   Runs `scripts/check-testbed.sh`.  
+   - If `STATUS=empty-or-no-git` → ask the user if they want to clone and set up a testbed here.  
+   - If `STATUS=testbed` + `DIRTY=false` → proceed to update.  
+   - If `STATUS=testbed` + `DIRTY=true` → stop and instruct the user to clean the working tree.  
+   - If `STATUS=unknown-repo` → stop and explain that the directory isn't a recognised testbed.
+
+2. **Setup (if needed)**  
+   If the user agrees to create a testbed in an empty directory, run `scripts/setup-testbed.sh`. This clones the repository and creates `.onboarding-init`.
+
+3. **Update & Verify**  
+   Run `scripts/update-testbed.sh`. This does:
+   - `git pull --ff-only`
+   - `cargo fmt --check`
+   - `cargo clippy -- -D warnings`
+   - `cargo test --workspace`
+   - Generates a factual digest from `CHANGELOG.md` (first version entry).
+
+4. **Output Receipt**  
+   Write a JSON receipt to `receipts/latest_receipt.json` with:
+   - timestamp
+   - branch name
+   - commit hash
+   - test counts (passed/failed)
+   - the digest text
+
+---
+
+## Optional LLM Enhancement
+
+If the `--summary` flag is provided, the skill will append a human‑readable summary after the deterministic output. The summary is generated by the LLM using the following context:
+
+- The digest text from the receipt.
+- Recent PR titles and milestone names (fetched from the local repo or provided in the receipt).
+- Any error or warning messages from the verification steps.
+
+The LLM should:
+- Explain what changed since the last sync (if anything)
+- Highlight any potential impacts on the user's previous work (e.g., Phase 1 fixes)
+- Suggest next steps if there are warnings or failures
+
+The enhancement is purely additive; the deterministic receipt remains the source of truth.
+
+---
+
+## Usage Examples
+
+```text
+/onboarding-suite              # deterministic only
+/onboarding-suite --summary    # deterministic + LLM summary
+/onboarding-suite --help       # shows this help
+```
+
+---
+
+## Notes
+
+- The testbed is identified by the presence of `.onboarding-init` at its root.
+- The skill never automatically pulls over a dirty working tree – it stops and asks.
+- All scripts are self‑contained and require no external dependencies beyond standard Unix tools (`git`, `cargo`, `sed`).
+
+_All of it. Fine._ 🐋

onboarding/.codewhale/skills/surf/scripts/catch-wave.sh

@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if [ -n "$(ls -A)" ]; then
+    echo "ERROR: Directory not empty. Refusing to install."
+    exit 1
+fi
+
+# Ask for repo URL (with default)
+read -p "Enter repository URL (default: https://github.com/Hmbown/CodeWhale.git): " REPO_URL
+REPO_URL=${REPO_URL:-https://github.com/Hmbown/CodeWhale.git}
+
+read -p "Enter branch (default: main): " BRANCH
+BRANCH=${BRANCH:-main}
+
+echo "Cloning $REPO_URL (branch: $BRANCH)..."
+git clone --branch "$BRANCH" "$REPO_URL" .
+
+# Create config file
+cat > .surf-config << EOF
+# Surf configuration
+REPO_URL=$REPO_URL
+BRANCH=$BRANCH
+ONBOARDING_INIT=true
+EOF
+
+echo "Testbed initialized. Config written to .surf-config."

onboarding/.codewhale/skills/surf/scripts/check-wave.sh

@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if [ ! -d ".git" ]; then
+    echo "STATUS=empty-or-no-git"
+    echo "MESSAGE=No Git repository found."
+    exit 0
+fi
+
+if [ -f ".surf-config" ]; then
+    # Load config
+    source .surf-config
+    if [ "${ONBOARDING_INIT:-false}" = "true" ]; then
+        echo "STATUS=testbed"
+        echo "MESSAGE=Testbed detected (${REPO_URL:-unknown})"
+    else
+        echo "STATUS=unknown-repo"
+        echo "MESSAGE=.surf-config found but ONBOARDING_INIT=false"
+    fi
+else
+    echo "STATUS=unknown-repo"
+    echo "MESSAGE=Git repository without .surf-config marker."
+fi
+
+if [ -n "$(git status --porcelain)" ]; then
+    echo "DIRTY=true"
+else
+    echo "DIRTY=false"
+fi

onboarding/.codewhale/skills/surf/scripts/ride-wave.sh

@@ -0,0 +1,93 @@
+#!/usr/bin/env bash
+# ride-wave.sh — Update the testbed, build, verify, and generate a digest
+# Reads .surf-config for repo URL and branch info
+
+set -euo pipefail
+
+# -- Load config if it exists --
+if [ -f ".surf-config" ]; then
+    source .surf-config
+    echo "🌊 Surfing ${REPO_URL:-unknown} (branch: ${BRANCH:-main})"
+else
+    echo "⚠️  No .surf-config found. Using defaults."
+    REPO_URL="${REPO_URL:-https://github.com/Hmbown/CodeWhale.git}"
+    BRANCH="${BRANCH:-main}"
+fi
+
+# -- Check if this is a valid testbed --
+if [ ! -f ".surf-config" ] || [ "${ONBOARDING_INIT:-false}" != "true" ]; then
+    echo "❌ ERROR: Not a valid Surf testbed. Run /surf setup first."
+    exit 1
+fi
+
+# -- Check if working directory is clean --
+if [ -n "$(git status --porcelain)" ]; then
+    echo "❌ ERROR: Working directory is dirty. Please commit or stash changes."
+    exit 1
+fi
+
+# -- Ensure we're on the right branch --
+CURRENT_BRANCH=$(git branch --show-current)
+if [ "$CURRENT_BRANCH" != "$BRANCH" ]; then
+    echo "⚠️  Currently on branch '$CURRENT_BRANCH', but config expects '$BRANCH'."
+    echo "Switching to '$BRANCH'..."
+    git checkout "$BRANCH"
+fi
+
+# -- Pull latest --
+echo "📦 Pulling latest changes from $BRANCH..."
+git pull --ff-only origin "$BRANCH"
+
+# -- Show current state --
+COMMIT=$(git rev-parse --short HEAD)
+echo "📍 At commit: $COMMIT"
+
+# -- Run verification --
+echo ""
+echo "🔧 Running verification..."
+echo "----------------------------------------"
+
+echo "▶️  cargo fmt --check"
+cargo fmt --check
+
+echo ""
+echo "▶️  cargo clippy -- -D warnings"
+cargo clippy -- -D warnings
+
+echo ""
+echo "▶️  cargo test --workspace"
+cargo test --workspace
+
+echo "----------------------------------------"
+echo "✅ All checks passed."
+
+# -- Generate digest from CHANGELOG --
+echo ""
+echo "📋 Digest (from CHANGELOG.md):"
+echo "----------------------------------------"
+if [ -f "CHANGELOG.md" ]; then
+    # Extract the first version entry
+    sed -n '/## \[/,/## \[/p' CHANGELOG.md | head -n -1 | tail -n +2 | head -n 10
+else
+    echo "⚠️  CHANGELOG.md not found."
+fi
+echo "----------------------------------------"
+
+# -- Write receipt --
+RECEIPTS_DIR="receipts"
+mkdir -p "$RECEIPTS_DIR"
+TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+cat > "$RECEIPTS_DIR/latest_receipt.json" << EOF
+{
+  "timestamp": "$TIMESTAMP",
+  "repo": "$REPO_URL",
+  "branch": "$BRANCH",
+  "commit": "$COMMIT",
+  "status": "success",
+  "message": "All checks passed."
+}
+EOF
+
+echo "📄 Receipt written: $RECEIPTS_DIR/latest_receipt.json"
+echo "🌊 Ride complete. 🏄"

onboarding/.codewhale/skills/surf/scripts/surf.sh

@@ -0,0 +1,57 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+RECEIPTS_DIR="receipts"
+TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+mkdir -p "$RECEIPTS_DIR"
+
+echo "🌊 Checking the wave..."
+STATE=$("$SCRIPT_DIR/check-wave.sh")
+echo "$STATE"
+
+STATUS=$(echo "$STATE" | grep "^STATUS=" | cut -d= -f2)
+MESSAGE=$(echo "$STATE" | grep "^MESSAGE=" | cut -d= -f2-)
+DIRTY=$(echo "$STATE" | grep "^DIRTY=" | cut -d= -f2 || echo "false")
+
+case "$STATUS" in
+    empty-or-no-git)
+        echo "🌊 The water is calm. No wave detected."
+        echo "📋 Run /surf setup to catch a wave."
+        exit 0
+        ;;
+    testbed)
+        if [ "$DIRTY" = "true" ]; then
+            echo "⚠️  The wave is choppy. Uncommitted changes detected."
+            echo "📋 Clean up or stash changes before riding."
+            exit 1
+        else
+            echo "🌊 Wave is clean. Riding..."
+            "$SCRIPT_DIR/ride-wave.sh" | tee "$RECEIPTS_DIR/latest_ride.log"
+            COMMIT=$(git rev-parse --short HEAD)
+            BRANCH=$(git branch --show-current)
+            cat > "$RECEIPTS_DIR/latest_receipt.json" << EOF
+{
+  "timestamp": "$TIMESTAMP",
+  "branch": "$BRANCH",
+  "commit": "$COMMIT",
+  "status": "success",
+  "digest": "Ride complete. See latest_ride.log for details."
+}
+EOF
+            echo "📄 Receipt written: $RECEIPTS_DIR/latest_receipt.json"
+            echo "✅ Surf complete."
+            exit 0
+        fi
+        ;;
+    unknown-repo)
+        echo "⚠️  Unknown territory: $MESSAGE"
+        echo "📋 Not a recognized surf spot. Run /surf setup in an empty directory."
+        exit 1
+        ;;
+    *)
+        echo "❌ Unknown state: $STATUS"
+        exit 1
+        ;;
+esac