@rubytech/taskmaster 1.13.3 → 1.14.2

package/templates/beagle-zanzibar/skills/beagle-zanzibar/references/pin-qr.md

@@ -0,0 +1,52 @@
+# PIN and QR Code — Pickup Verification
+
+## Overview
+
+Each confirmed booking gets a unique 4-digit pickup PIN. The tourist holds the PIN. The driver receives a QR code image that encodes it. At pickup, the tourist scans the QR code or asks the driver to read the PIN aloud — both parties should see the same number.
+
+## Generating the PIN
+
+Pick a random 4-digit integer between 1000 and 9999. No uniqueness check against other bookings is required.
+
+Store the PIN in the booking record immediately at `bookings/{job-id}.md`:
+
+```
+pin: 4827
+```
+
+## Generating the QR Code Image
+
+Construct the QR image URL from the PIN:
+
+```
+https://api.qrserver.com/v1/create-qr-code/?size=300x300&data={pin}
+```
+
+Example — PIN 4827:
+`https://api.qrserver.com/v1/create-qr-code/?size=300x300&data=4827`
+
+This URL returns a PNG image of the QR code. No separate API call is needed to generate it.
+
+## Sending to the Driver
+
+Use the `message` tool to send the QR code as an inline WhatsApp image:
+
+```
+action: send
+channel: whatsapp
+target: {driver_phone_number}
+media: https://api.qrserver.com/v1/create-qr-code/?size=300x300&data={pin}
+caption: [BGL-XXXX] Your passenger's verification code. Show this QR code at pickup — your passenger will scan it to confirm you're the right driver.
+```
+
+The driver opens WhatsApp, sees the QR code image inline, and shows their phone screen to the tourist at pickup.
+
+## Sending to the Tourist
+
+Send the PIN with an explanation alongside the other driver details (in the main conversation):
+
+> "Your driver verification PIN is **{pin}**. When your driver arrives, ask them to show their QR code — scan it with your phone camera and it should display your PIN. Or ask the driver to read the number aloud. If it matches, you've got the right driver. Works offline — no internet needed."
+
+## Timing
+
+Generate the PIN immediately after payment is confirmed (Phase 4). Send both as part of Phase 5 — QR image to driver and PIN to tourist — before setting up any pickup reminders.

package/templates/{zanzi-taxi/skills/zanzi-taxi → beagle-zanzibar/skills/beagle-zanzibar}/references/post-ride.md

@@ -37,6 +37,19 @@ If the tourist reports a serious issue (safety concern, fare dispute, driver mis
 - Don't promise specific outcomes ("we'll remove the driver") — explain that the operator reviews all feedback
 - Offer to help with their next ride if they need one
 
+## Substitution Check
+
+When checking in with the tourist, naturally ask whether the booked driver completed the ride: "Was it [driver name] who picked you up?" Keep it casual — this is a service quality question, not an accusation.
+
+**If yes:** proceed with ratings as normal.
+
+**If no, or if the tourist names a different person:**
+- Do not alarm the tourist or make promises about consequences
+- Record a substitution flag in the booking record at `bookings/{job-id}.md`
+- Add an entry to the driver's memory profile (`drivers/{name}.md`) under `Substitution Record`:
+  `[date]: Substitute reported for [job-id] — tourist named [substitute name if given]`
+- The admin agent handles follow-up with the booked driver operationally
+
 ## Timing
 
 Don't follow up too quickly (they might still be at their destination) or too late (they've moved on). A reasonable window is 30–60 minutes after estimated arrival.

package/templates/{zanzi-taxi/skills/zanzi-taxi → beagle-zanzibar/skills/beagle-zanzibar}/references/ride-matching.md

@@ -8,6 +8,8 @@ When a tourist messages about a ride, gather:
 2. **Destination** — where they're going
 3. **Date and time** — when they need the ride
 4. **Passengers** — how many people
+5. **Luggage** - how many pieces, anythinbg oversized
+6. **Special Requests*** - e.g. wheelchair access
 
 Ask naturally, not as a form. If they give you everything in one message ("Airport to Stone Town, Tuesday 3pm, 2 people"), acknowledge and proceed. If anything is missing, ask for it conversationally.
 
@@ -16,9 +18,11 @@ Check the knowledge base to confirm you know the route. If the route isn't cover
 ## Phase 2: Driver Negotiation
 
 Before contacting drivers:
-- Check driver states — only contact drivers marked as `idle`
-- Select ~3 drivers based on: rating, response rate, route familiarity, availability
+- Use `contact_lookup` with `driver: true` to get the full driver roster
+- Check `drivers/{name}.md` in memory for each driver's current `status` — only contact drivers marked as `idle`
+- Prefer drivers whose route history shows strong performance on this specific route — see `references/route-learning.md`
 - Prepend every message with the job ID: `[BGL-XXXX]`
+- Set each contacted driver's status to `awaiting_response` in their memory profile before sending
 
 Negotiate in Swahili. The driver quotes their fare for the route. Collect responses and compare.
 
@@ -44,24 +48,28 @@ If only one driver responded, present it honestly: "One driver available for thi
 
 When the tourist chooses an offer:
 1. Confirm the details: route, time, fare, vehicle
-2. Explain the booking fee: "A small booking fee of [amount] confirms your ride. You pay [remaining fare] directly to your driver at the end."
-3. Send the Stripe payment link
-4. Wait for payment confirmation — do not proceed until Stripe confirms
+2. Explain the booking fee and terms in one message: "A small booking fee of [amount] confirms your ride. You pay $[fare] directly to your driver at the end. Beagle is a matching service — the ride is between you and the driver directly. By paying, you accept our terms: beagle.cab/terms"
+3. Load the `stripe` skill — follow `stripe/references/payment-links.md` to calculate the fee and generate a Checkout Session link
+4. Send the payment link to the tourist
+5. When the tourist says they've paid, verify the session status via the Stripe API — do not proceed to Phase 5 until payment is confirmed
 
 ## Phase 5: Post-Payment
 
-Once payment clears, send the tourist:
-- Driver name
-- Driver phone number
-- Vehicle description and plate number
-- Pickup PIN (4-digit code)
-- Explanation: "Your driver has a QR code. Scan it with your phone camera to see the PIN, or ask the driver to quote it. If it matches your PIN, you've got the right driver. Works offline — no internet needed."
-
-Confirm the driver has received:
-- Passenger name
-- Pickup time and location
-- Fare confirmed
-- QR code (encodes the tourist's PIN)
+Once payment clears:
+
+1. **Generate the pickup PIN and QR code** — load `references/pin-qr.md` and follow the instructions there to generate the PIN and construct the driver's QR code URL.
+
+2. **Send the tourist:**
+   - Driver name
+   - Driver phone number
+   - Vehicle description and plate number
+   - Pickup PIN with verification explanation (see `references/pin-qr.md`)
+
+3. **Send the driver:**
+   - Passenger name
+   - Pickup time and location
+   - Fare confirmed
+   - QR code URL (encodes the tourist's PIN — see `references/pin-qr.md`)
 
 ## Phase 6: Driver Pickup Reminders
 

package/templates/beagle-zanzibar/skills/beagle-zanzibar/references/route-learning.md

@@ -0,0 +1,61 @@
+# Route Learning — Building Driver Route Affinity
+
+## What This Is
+
+Route affinity is the service's accumulated understanding of which drivers tend to perform best on which routes. It is not declared upfront — it emerges from booking outcomes and ratings over time. A driver who consistently earns strong ratings on airport-to-north-coast runs becomes a stronger candidate for that route in future negotiations. A driver with a poor completion record on east coast routes gets deprioritised for those bookings, even if they quote competitively.
+
+## Where the Data Lives
+
+Booking records in memory (`bookings/{job-id}.md`) contain the raw data:
+- The route (pickup → destination)
+- Which driver completed the ride
+- The rating received
+- Whether the booking completed or was cancelled/no-show
+
+Driver memory profiles (`drivers/{name}.md`) contain the aggregated view. The Route History section builds as bookings complete:
+
+```
+## Route History
+- 2026-02-14: Airport → Nungwi | BGL-0018 | Rating: 4.6
+- 2026-02-28: Airport → Stone Town | BGL-0031 | Rating: 4.1
+- 2026-03-01: Stone Town → Paje | BGL-0037 | Rating: 4.8
+```
+
+## How Affinity is Used During Driver Selection (Phase 2)
+
+When selecting ~3 drivers to contact for a negotiation, prefer drivers whose history shows:
+- Completed rides on this specific route (or similar routes in the same area)
+- Consistent ratings above 4.0 on those runs
+
+New drivers (no history) are treated neutrally — they need the opportunity to build a record. Never exclude a driver solely for lacking route history.
+
+Do not apply affinity rigidly. A great driver with no history on a route is still a viable choice. Route history is a signal that improves selection over time, not a gatekeeping rule.
+
+## How the Public Agent Maintains Route History
+
+After each completed booking, the public agent adds a route entry to the driver's memory profile:
+
+```
+- [date]: [Pickup] → [Destination] | [job-id] | Rating: [score]
+```
+
+If the ride was cancelled, a no-show, or ended in a complaint, note it:
+
+```
+- [date]: Airport → Nungwi | BGL-0052 | No-show
+```
+
+These entries are the raw material the admin agent uses to identify patterns.
+
+## Admin Agent: Periodic Route Analysis
+
+The admin agent should periodically review route history across the driver roster and surface meaningful patterns to the operator:
+
+- Drivers consistently rated above 4.5 on a specific route — flag as strong matches worth prioritising
+- Drivers consistently rated below 3.5 on a specific route — recommend exclusion from that route
+- Routes where no driver achieves strong ratings — flag as a coverage or quality gap worth investigating
+- Drivers whose ratings vary sharply by route — worth noting (excellent on airport runs, poor on east coast, for example)
+
+## Limits
+
+Patterns need volume to be meaningful. A driver with two rides on a route does not have a pattern — they have a sample. Apply judgement: five or more completed rides on a route with consistent ratings is a reliable signal. Fewer than that warrants patience rather than conclusions.

package/templates/beagle-zanzibar/skills/stripe/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: stripe
+description: "Generates Stripe Checkout Session payment links for Beagle booking fees, and verifies payment status before releasing driver details."
+metadata: {"taskmaster":{"always":false,"emoji":"💳","skillKey":"stripe"}}
+---
+
+# Stripe — Payment Links
+
+## Your Role
+
+Generate a Stripe Checkout Session link for each confirmed booking and verify payment before releasing driver details to the tourist.
+
+## When to Activate
+
+Load this skill when the tourist has chosen an offer and the booking is ready to confirm (Phase 4 of the ride-matching flow).
+
+## Reference Table
+
+| Task | When | Reference |
+|------|------|-----------|
+| Create payment link | Tourist confirms offer, booking fee needs collecting | `references/payment-links.md` |
+
+## Key Rules
+
+- **Never release driver details before payment is confirmed.** Always verify the Stripe session status before proceeding to Phase 5.
+- **Minimum fee is $2, maximum is $5.** Calculate as 5% of the agreed fare, clamped to this range.
+- **Each booking gets its own Checkout Session.** Never reuse a payment link between bookings.
+- **Test mode is fine to start.** Use `sk_test_...` keys during setup. Switch to live keys when real bookings begin.

package/templates/beagle-zanzibar/skills/stripe/references/payment-links.md

@@ -0,0 +1,71 @@
+# Stripe Payment Links — Checkout Session Creation
+
+## Booking Fee Calculation
+
+The tourist pays a booking fee to confirm their ride:
+
+```
+fee = max($2, min($5, fare × 0.05))
+```
+
+In cents (Stripe uses the smallest currency unit):
+
+```
+fee_cents = max(200, min(500, round(fare_usd × 5)))
+```
+
+Examples: $20 fare → $2.00 fee | $50 fare → $2.50 fee | $100 fare → $5.00 fee
+
+## Creating a Checkout Session
+
+Call the Stripe Checkout Sessions API:
+
+```
+POST https://api.stripe.com/v1/checkout/sessions
+Authorization: Bearer {stripe_secret_key}
+Content-Type: application/x-www-form-urlencoded
+
+mode=payment
+payment_method_types[]=card
+line_items[0][price_data][currency]=usd
+line_items[0][price_data][unit_amount]={fee_cents}
+line_items[0][price_data][product_data][name]=Beagle booking fee — {job_id}
+line_items[0][price_data][product_data][description]={route} on {date}
+line_items[0][quantity]=1
+metadata[booking_id]={job_id}
+metadata[tourist_phone]={tourist_phone}
+metadata[negotiated_fare]={fare_usd}
+```
+
+The Stripe secret key is the `stripe` key stored in your API key config (`sk_test_...` for test mode, `sk_live_...` for production).
+
+The response includes a `url` field — this is the hosted checkout page to send the tourist.
+
+## Sending the Link
+
+Send the tourist the checkout URL with context:
+
+> "To confirm your booking, pay the $[fee] booking fee here: [url]
+> This locks in your ride. You pay $[fare] directly to your driver at the end of the journey."
+
+## Verifying Payment
+
+Before releasing driver details (Phase 5), verify the session is paid:
+
+```
+GET https://api.stripe.com/v1/checkout/sessions/{session_id}
+Authorization: Bearer {stripe_secret_key}
+```
+
+Check `payment_status == "paid"`. If not yet paid, wait for the tourist to say they've paid — then verify. Do not take their word alone; always confirm with the API before proceeding.
+
+## What to Store in the Booking Record
+
+Add these fields to `bookings/{job-id}.md` when the session is created and confirmed:
+
+```
+stripe_session_id: cs_...
+booking_fee_usd: 2.50
+payment_status: pending   → paid (update when confirmed)
+paid_at: [timestamp from session]
+```