@ketecode/loom 0.0.0-stage → 0.1.0

package/skills/spring-boot-patterns/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: spring-boot-patterns
+description: Spring Boot application structure and conventions, covering controller-service-repository layering, constructor injection, typed @ConfigurationProperties, @Transactional boundaries, Bean Validation, ProblemDetail error responses, SecurityFilterChain setup, Actuator exposure and focused test slices such as @WebMvcTest and @DataJpaTest. Use when building or changing a Spring Boot service, adding an endpoint or configuration, securing routes, wiring health checks, or writing Spring Boot tests.
+license: MIT
+compatibility: Any Agent Skills host. Needs a JDK and the project's Maven or Gradle wrapper. Written for Spring Boot 3.x and 4.x; version-specific differences are called out.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: coding
+  kete-loom/risk: runs-commands
+  kete-loom/requires: "java"
+  kete-loom/owner: "Kete-org"
+---
+
+# Spring Boot patterns
+
+Write Spring Boot code that is easy to test, fails loudly on bad configuration, and keeps transactions and security explicit. For entity mapping, fetch plans and N+1 problems, use the `jpa-hibernate` skill alongside this one.
+
+## 0. Before you change anything
+
+1. Find the Boot version in `pom.xml` (`spring-boot-starter-parent`) or `build.gradle(.kts)` (`org.springframework.boot` plugin). Boot 3 and 4 differ in test setup and Jackson (see `references/testing.md`).
+2. Find the build command: `./mvnw verify` or `./gradlew build`. Run it once and record the result. If it already fails, **stop and tell the user** before editing.
+3. Read one existing controller, service and test, and follow their package layout, naming and style. Don't introduce a second style.
+
+## 1. Structure
+
+- Package **by feature** (`orders/`, `billing/`), not by layer, unless the project already does otherwise. Keep the `@SpringBootApplication` class in the root package so component scanning finds everything.
+- Layers inside a feature:
+  - **Controller**: HTTP only. Parse, validate, call one service method, map to a response DTO. No repository calls, no business rules.
+  - **Service**: business rules and the transaction boundary.
+  - **Repository**: Spring Data interfaces. No business logic.
+- Never return JPA entities from controllers. Map to records (`record OrderResponse(...)`) so lazy fields, internal columns and cycles never leak into JSON.
+
+## 2. Dependency injection
+
+- Use **constructor injection** with `final` fields. One constructor needs no `@Autowired`. Never use field injection in new code.
+- Prefer one implementation per interface. When there are several, choose with `@Qualifier` or a `Map<String, T>` injection, not `@Primary` scattered around.
+- A circular dependency is a design bug. Split the class; don't enable `spring.main.allow-circular-references`.
+
+## 3. Configuration
+
+- Bind related settings to a typed record and validate it at startup:
+
+  ```java
+  @ConfigurationProperties(prefix = "payments")
+  @Validated
+  public record PaymentsProperties(@NotBlank String baseUrl, @NotNull Duration timeout) {}
+  ```
+
+  Register it with `@ConfigurationPropertiesScan` (or `@EnableConfigurationProperties`). Prefer this over many `@Value` fields.
+- Secrets come from environment variables or a secret store, never committed `application.yml`. Relaxed binding maps `PAYMENTS_BASEURL` to `payments.base-url`.
+- Profiles (`application-dev.yml`, `spring.profiles.active`) change environment details, not behaviour. Never gate business logic on a profile name.
+- Set `spring.jpa.open-in-view=false` in new services so lazy loading can't run during view rendering (Boot logs a warning while it is left on).
+
+## 4. Transactions
+
+- Put `@Transactional` on **public service methods**, not controllers or repositories. Use `@Transactional(readOnly = true)` for queries.
+- The annotation works through a proxy, so it is **ignored** on a call from another method in the same class (self-invocation) and on private methods. Move the method to another bean if it needs its own transaction.
+- By default only unchecked exceptions roll back. If a checked exception must roll back, set `rollbackFor`.
+- Never call a slow remote API (payment provider, email) inside a database transaction. Commit first, then call out, or use an outbox table or `@TransactionalEventListener(phase = AFTER_COMMIT)`.
+
+## 5. Validation and errors
+
+- Annotate request DTOs with Jakarta Bean Validation (`@NotBlank`, `@Size`, `@Email`) and the controller parameter with `@Valid`. Needs `spring-boot-starter-validation`.
+- Return RFC 9457 problem details. Set `spring.mvc.problemdetails.enabled=true` or add one `@RestControllerAdvice` (extending `ResponseEntityExceptionHandler`) that maps domain exceptions to `ProblemDetail` with the right status:
+
+  ```java
+  @ExceptionHandler(OrderNotFoundException.class)
+  ProblemDetail notFound(OrderNotFoundException e) {
+      return ProblemDetail.forStatusAndDetail(HttpStatus.NOT_FOUND, e.getMessage());
+  }
+  ```
+
+- Never return stack traces, SQL or exception class names to clients. Log them server-side with a correlation id.
+- Don't catch an exception just to log and rethrow it; let the advice handle it once.
+
+## 6. Security basics
+
+- Configure Spring Security with a `SecurityFilterChain` bean (the old `WebSecurityConfigurerAdapter` is gone):
+
+  ```java
+  @Bean
+  SecurityFilterChain api(HttpSecurity http) throws Exception {
+      return http
+          .authorizeHttpRequests(a -> a
+              .requestMatchers("/actuator/health/**").permitAll()
+              .anyRequest().authenticated())
+          .oauth2ResourceServer(o -> o.jwt(Customizer.withDefaults()))
+          .build();
+  }
+  ```
+
+- Deny by default: end with `.anyRequest().authenticated()` (or `denyAll()`), and permit only named paths.
+- Disable CSRF only for stateless token-authenticated APIs; keep it for cookie sessions.
+- Hash passwords with `PasswordEncoderFactories.createDelegatingPasswordEncoder()` (bcrypt by default). Never store or log raw passwords or tokens.
+- Check ownership in the service ("does this order belong to the caller?"), not only the role. `@PreAuthorize` needs `@EnableMethodSecurity`.
+- **Stop and ask the user** before changing who can reach an endpoint, the auth mechanism, or CORS origins.
+
+## 7. Actuator
+
+- Add `spring-boot-starter-actuator`. Only `health` is exposed over HTTP by default; keep it that way and expose more by name (`management.endpoints.web.exposure.include=health,info,prometheus`), never `*` on a public port.
+- Use the liveness and readiness health groups (`/actuator/health/liveness`, `/actuator/health/readiness`, enabled by default) for container probes. Readiness may check dependencies; liveness must not, or a database outage restarts every pod.
+- Put management on a separate port (`management.server.port`) when the platform allows, and protect anything beyond health.
+
+## 8. Testing
+
+Use the narrowest slice that covers the behaviour. Details, annotations and Boot 3 versus 4 differences are in `references/testing.md`.
+
+| What you test | Use |
+|---|---|
+| Pure business logic | Plain JUnit, no Spring context |
+| Controller: routing, validation, status codes, JSON | `@WebMvcTest(OrderController.class)` with `@MockitoBean` services; `@Import` your security config |
+| Repository queries and mappings | `@DataJpaTest` with `@AutoConfigureTestDatabase(replace = NONE)` and a Testcontainers database |
+| Full wiring, security and config | `@SpringBootTest` sparingly, with `@ServiceConnection` containers |
+
+- Assert status, body and problem details for error paths, not only the happy path.
+- Test security rules: an unauthenticated request gets 401, the wrong user gets 403 or 404.
+- Don't use H2 to stand in for PostgreSQL or MySQL in repository tests; dialect differences hide real bugs.
+
+## Never
+
+- Field injection, entities in API responses, or `@Transactional` on private or self-invoked methods.
+- `permitAll()` on everything "for now", or `exposure.include=*` in production.
+- `spring.jpa.hibernate.ddl-auto=update` or `create` outside local dev; use migrations.
+- Catching `Exception` in controllers and returning 200 with an error message.
+
+## Before you finish
+
+Run the full build (`./mvnw verify` or `./gradlew build`). Report: what changed (files), new config keys and their defaults, security rules touched, tests added, and the final test counts.

package/skills/spring-boot-patterns/evals/triggers.json

@@ -0,0 +1,18 @@
+{
+  "should_trigger": [
+    "Add a new REST endpoint to our Spring Boot order service with request validation and proper 404 responses",
+    "Bind the payments.* settings in application.yml to a typed config class in Spring Boot",
+    "My @Transactional method in the Spring service doesn't roll back when called from the same class, why?",
+    "Lock down our Spring Boot API with a SecurityFilterChain and JWT resource server, keeping actuator health public",
+    "Write a @WebMvcTest for the invoice controller using MockitoBean instead of MockBean",
+    "Which actuator endpoints should a Spring Boot app expose for Kubernetes liveness and readiness probes?"
+  ],
+  "should_not_trigger": [
+    "Our Hibernate entities trigger hundreds of selects when loading the order list, fix the N+1",
+    "Build a Quarkus REST endpoint backed by Panache and make it compile to a native image",
+    "Add JWT authentication and StatusPages error handling to my Ktor server",
+    "Review this Java pull request for null handling and resource leaks",
+    "Fix the Maven build: cannot find symbol after upgrading the JDK to 21",
+    "Write JUnit 5 parameterized tests for this plain Java date parsing utility"
+  ]
+}

package/skills/spring-boot-patterns/references/testing.md

@@ -0,0 +1,72 @@
+# Spring Boot testing reference
+
+## Slice annotations
+
+| Annotation | Loads | Typical collaborators |
+|---|---|---|
+| `@WebMvcTest(X.class)` | MVC infrastructure, controller `X`, advice, filters (not `@Configuration` or `@Component` beans) | `MockMvc` or `MockMvcTester`, `@MockitoBean` services |
+| `@WebFluxTest(X.class)` | WebFlux infrastructure for controller `X` | `WebTestClient` |
+| `@DataJpaTest` | JPA, repositories, `TestEntityManager`; each test rolls back | Testcontainers database |
+| `@JsonTest` | Jackson configuration | `JacksonTester` |
+| `@RestClientTest` | `RestClient` / `RestTemplate` builders | `MockRestServiceServer` |
+| `@SpringBootTest` | The whole application | `@AutoConfigureMockMvc`, real containers |
+
+`@DataJpaTest` replaces the datasource with an embedded one by default. To test against a container, add `@AutoConfigureTestDatabase(replace = Replace.NONE)` and import the container configuration below.
+
+`@WebMvcTest` does not pick up a `SecurityFilterChain` defined in your own `@Configuration` class, so the slice runs Boot's default security instead of your rules. `@Import(SecurityConfig.class)` into the test; with a JWT resource server, also add `@MockitoBean JwtDecoder` so the context starts without an issuer.
+
+## Mocks
+
+- `@MockitoBean` and `@MockitoSpyBean` (Spring Framework 6.2+) replace `@MockBean` and `@SpyBean`. `@MockBean` is deprecated in Boot 3.4 and removed in Boot 4.
+- `@MockitoBean` goes on test class fields, not in `@Configuration` classes.
+- Every distinct set of mocks creates a new application context. Keep mock sets consistent across test classes so the context cache is reused.
+
+## Example: controller slice
+
+```java
+@WebMvcTest(OrderController.class)
+@Import(SecurityConfig.class)
+class OrderControllerTest {
+    @Autowired MockMvc mvc;
+    @MockitoBean OrderService orders;
+    @MockitoBean JwtDecoder jwtDecoder;
+
+    @Test
+    void returns404ProblemWhenMissing() throws Exception {
+        when(orders.find(42L)).thenThrow(new OrderNotFoundException(42L));
+        mvc.perform(get("/orders/42").with(jwt()))
+           .andExpect(status().isNotFound())
+           .andExpect(jsonPath("$.status").value(404));
+    }
+
+    @Test
+    void rejectsAnonymous() throws Exception {
+        mvc.perform(get("/orders/42")).andExpect(status().isUnauthorized());
+    }
+}
+```
+
+`jwt()` comes from `spring-security-test` (`SecurityMockMvcRequestPostProcessors`).
+
+## Example: Testcontainers with service connections
+
+```java
+@TestConfiguration(proxyBeanMethods = false)
+class TestcontainersConfig {
+    @Bean @ServiceConnection
+    PostgreSQLContainer<?> postgres() { return new PostgreSQLContainer<>("postgres:16-alpine"); }
+}
+```
+
+Import it with `@Import(TestcontainersConfig.class)` in `@SpringBootTest` classes, or in `@DataJpaTest` classes together with `@AutoConfigureTestDatabase(replace = Replace.NONE)`. `@ServiceConnection` (Boot 3.1+) sets the datasource URL and credentials, so no `@DynamicPropertySource` is needed.
+
+## Boot 4 differences
+
+From the Spring Boot 4.0 migration guide:
+
+- Test support is split per technology. Add the matching test starter, for example `spring-boot-starter-webmvc-test` or `spring-boot-starter-data-jpa-test`; these bring in `spring-boot-starter-test`. Slice annotations move to the matching `spring-boot-<technology>-test` module, so imports change.
+- `@SpringBootTest` no longer configures MockMvc on its own. Add `@AutoConfigureMockMvc`.
+- `TestRestTemplate` needs `@AutoConfigureTestRestTemplate`; the newer `RestTestClient` uses `@AutoConfigureRestTestClient`.
+- Jackson 3 is the default (`tools.jackson` packages; `@JsonComponent` becomes `@JacksonComponent`). The auto-configured mapper is a `JsonMapper`; to replace it, define a `JsonMapper` bean, because a plain `ObjectMapper` bean no longer makes it back off.
+
+When upgrading, follow the official migration guide rather than this summary.

package/skills/stripe-integration/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: stripe-integration
+description: Builds and hardens Stripe payments and billing, from Checkout Sessions and Payment Intents with SCA and 3D Secure handling to Stripe-Signature webhook verification on the unparsed request body, Idempotency-Key headers on every POST, subscriptions driven by invoice events, the Billing customer portal, and test clocks for simulating renewals and trial ends. Use when adding Stripe Checkout or Elements, setting up Stripe subscriptions or the customer portal, fixing a Stripe webhook signature error or duplicate fulfilment, or testing billing cycles with the Stripe CLI.
+license: MIT
+compatibility: Any Agent Skills host. Live calls need network access to api.stripe.com; local webhook testing uses the Stripe CLI. Examples are TypeScript with the official stripe-node library; the rules apply to any Stripe SDK.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: integrations
+  kete-loom/risk: network
+  kete-loom/requires: "stripe"
+  kete-loom/owner: "Kete-org"
+---
+
+# Stripe integration
+
+Build a Stripe flow where the price comes from the server, a webhook is trusted only after its signature checks out, retries never create a second charge, and subscription access follows what Stripe says, not what the browser says.
+
+## Ground rules
+
+1. **Secret key on the server only.** `STRIPE_SECRET_KEY` (`sk_...`, or a restricted `rk_...` key with only the permissions the service needs) and the webhook secret (`whsec_...`) come from the environment. Only the publishable key (`pk_...`) reaches the browser.
+2. **Prices come from Stripe or your database.** Pass a `price` ID or compute `amount` server-side. Never accept an amount, currency or price ID from the client without checking it against an allow-list.
+3. **Amounts are integers in the smallest unit** (cents for USD, pence for GBP; zero-decimal currencies such as JPY are whole units). No float maths.
+4. **Fulfil from webhooks.** `checkout.session.completed` (plus `checkout.session.async_payment_succeeded` for delayed methods) or `payment_intent.succeeded`. The success page only shows status; it may never load.
+5. **Verify every webhook** with the SDK on the **raw request bytes**, the `Stripe-Signature` header and that endpoint's `whsec_` secret. Keep the default 5-minute tolerance; never set it to 0.
+6. **Idempotent both ways.** Send an `Idempotency-Key` (a UUID v4 stored with your order) on every create/update POST so a network retry can't double-charge. Record processed `event.id`s and guard fulfilment with `UPDATE ... WHERE status = 'pending'`, because Stripe delivers events at least once and out of order.
+7. **Test mode or a sandbox first**, with the Stripe CLI forwarding events, before any live key is configured.
+
+## Choose the flow
+
+| Need | Use |
+|---|---|
+| One-off or subscription payment, least code, SCA handled for you | Checkout Session (`mode: 'payment'` or `'subscription'`), hosted or embedded |
+| Your own payment form | Payment Intent + Payment Element; confirm on the client with `stripe.confirmPayment` |
+| Save a card for later charges | `setup_future_usage: 'off_session'` on the Payment Intent, or a Setup Intent |
+| Let customers manage plans, cards and invoices | Billing customer portal session |
+
+## Implementation steps
+
+1. **Create a Checkout Session** on the server with `line_items: [{ price, quantity }]`, `mode`, `success_url` (include `{CHECKOUT_SESSION_ID}`), `cancel_url`, `client_reference_id` or `metadata.order_id`, and an idempotency key. Redirect to `session.url`. Shapes in `references/api.md`.
+2. **Or create a Payment Intent** with `amount`, `currency`, `automatic_payment_methods: { enabled: true }`, `metadata.order_id`; send only `client_secret` to the browser.
+3. **Webhook endpoint**: follow `references/webhooks.md`. Mount it before any JSON body parser, verify with `stripe.webhooks.constructEvent`, return `2xx` fast, process in a queue.
+4. **Handle SCA**: a Payment Intent in `requires_action` needs the customer to authenticate; the client SDK does this when confirming. For off-session charges (renewals, saved cards) handle `authentication_required` by emailing the customer a link back on-session. Never mark paid on `processing`.
+5. **Subscriptions**: create through Checkout with `mode: 'subscription'`, store `customer` and `subscription` IDs, and drive access from events: `invoice.paid` (extend access; from API `2025-03-31.basil` the period end is on `items.data[].current_period_end`), `invoice.payment_failed` (dunning, keep or restrict per policy), `customer.subscription.updated` / `.deleted` (plan changes, cancellation). Details in `references/billing.md`.
+6. **Customer portal**: configure it in the Dashboard, then create `billingPortal.sessions.create({ customer, return_url })` from an authenticated route and redirect. Never create a portal session for a customer ID taken from the request; look it up from the logged-in user.
+7. **Test clocks** for billing: create a clock, attach a new customer to it, subscribe, then advance time to see trials end, renewals and failed payments fire their webhooks (`references/billing.md`).
+8. **Persist**: order/payment row with expected amount and currency, Checkout Session or Payment Intent ID, idempotency key, status; a `stripe_events` table of processed event IDs; customer and subscription IDs per user.
+
+## Reviewing an existing integration
+
+Check each ground rule, then look for:
+
+- Webhook route behind `express.json()` / framework body parsing, so `constructEvent` fails or was "fixed" by skipping verification.
+- One `whsec_` reused across endpoints or between test and live (each endpoint and mode has its own).
+- Fulfilment in the success page handler, or on `payment_intent.created` / `processing`.
+- Event order assumed (`invoice.paid` before `customer.subscription.created`); missing objects not fetched from the API.
+- No idempotency key on PaymentIntent, refund or subscription creation; or a new key generated on each retry, which defeats it.
+- Subscription access granted from `checkout.session.completed` alone and never revoked on `customer.subscription.deleted`.
+- Prices or amounts sent from the client; `price` IDs hard-coded from test mode in live config.
+- Secret key in front-end code or a `NEXT_PUBLIC_`/`VITE_` variable.
+
+## Stop and ask the user
+
+- Before switching any configuration to live keys.
+- Whether to keep or cut access on a failed renewal (business decision), and what the dunning and retry settings should be.
+- Before building Connect (marketplaces, payouts to others); it is a different model with onboarding and liability decisions.
+
+## Before you finish
+
+Stripe's docs at docs.stripe.com and the API version pinned on your account are the final word on field names; this skill gives the rules and the shape. Test with `stripe listen --forward-to localhost:4242/webhook` and `stripe trigger`: card `4242 4242 4242 4242` succeeds, `4000 0025 0000 3155` requires 3D Secure, `4000 0000 0000 9995` declines for insufficient funds. Also test a replayed event (processed once), a bad signature (rejected with 400), a retried create call with the same idempotency key (one object), and a test-clock renewal that fails.

package/skills/stripe-integration/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "Integrate Stripe subscriptions into the billing page",
+    "Stripe webhook keeps failing with No signatures found matching the expected signature",
+    "Add a Stripe customer portal so users can cancel or change their plan",
+    "How do I use Stripe test clocks to check what happens when a trial ends?",
+    "Handle 3D Secure when charging a saved card off-session with Payment Intents"
+  ],
+  "should_not_trigger": [
+    "Add Flutterwave checkout to our Nigerian e-commerce site",
+    "Add Paystack checkout to our Next.js shop so Ghanaian customers can pay",
+    "Review the payment module for secret keys leaked into front-end code",
+    "Work out which parts of our card checkout fall inside PCI DSS scope",
+    "Design the REST API for our invoicing service"
+  ]
+}

package/skills/stripe-integration/references/api.md

@@ -0,0 +1,71 @@
+# Stripe API shapes used by this skill
+
+Use the official SDK for your language and pin the API version your account uses. Every create/update call takes an idempotency key in the request options (`Idempotency-Key` header over HTTP).
+
+Idempotency facts (API v1): keys up to 255 characters, UUID v4 recommended, don't put personal data in them. Stripe saves the first response for a key (including a `500`) and returns it on retries; reusing a key with different parameters is an error; keys can be pruned after 24 hours. Don't send keys on `GET` or `DELETE`.
+
+## Checkout Session (TypeScript, stripe-node)
+
+```ts
+import Stripe from 'stripe';
+const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);
+
+export async function startCheckout(order: { id: string; priceId: string; quantity: number; idemKey: string }) {
+  const session = await stripe.checkout.sessions.create(
+    {
+      mode: 'payment',
+      line_items: [{ price: order.priceId, quantity: order.quantity }], // priceId from your DB, not the client
+      success_url: 'https://app.example.com/checkout/success?session_id={CHECKOUT_SESSION_ID}',
+      cancel_url: 'https://app.example.com/cart',
+      client_reference_id: order.id,
+      metadata: { order_id: order.id },
+    },
+    { idempotencyKey: order.idemKey }, // stored with the order, reused on retry
+  );
+  return session.url!;
+}
+```
+
+The success page may call `stripe.checkout.sessions.retrieve(session_id)` to show status, but fulfilment stays in the webhook. Check `session.payment_status === 'paid'` (or `'no_payment_required'`) before fulfilling; for delayed methods it is `'unpaid'` at completion and you wait for `checkout.session.async_payment_succeeded`.
+
+## Payment Intent
+
+```ts
+const pi = await stripe.paymentIntents.create(
+  { amount: 2550, currency: 'usd', automatic_payment_methods: { enabled: true }, metadata: { order_id: order.id } },
+  { idempotencyKey: order.idemKey },
+);
+// send pi.client_secret to the browser; confirm there with stripe.confirmPayment({ elements, confirmParams: { return_url } })
+```
+
+Statuses: `requires_payment_method` → `requires_confirmation` → `requires_action` (SCA / 3DS) → `processing` → `succeeded`, or `canceled`. Only `succeeded` (seen in `payment_intent.succeeded`) means paid. On `payment_intent.payment_failed`, read `last_payment_error` and let the customer try another method.
+
+## Off-session charge with a saved method
+
+```ts
+try {
+  await stripe.paymentIntents.create(
+    { amount, currency, customer, payment_method, off_session: true, confirm: true },
+    { idempotencyKey },
+  );
+} catch (err: any) {
+  if (err.code === 'authentication_required') {
+    // SCA needed: email the customer a link to an on-session page that confirms err.raw.payment_intent
+  } else throw err;
+}
+```
+
+## Refund
+
+```ts
+await stripe.refunds.create({ payment_intent: piId, amount: partialMinor }, { idempotencyKey: refundKey });
+```
+
+## Test cards
+
+| Number | Behaviour |
+|---|---|
+| 4242 4242 4242 4242 | Succeeds |
+| 4000 0025 0000 3155 | Requires 3D Secure authentication |
+| 4000 0000 0000 9995 | Declined, insufficient funds |
+| 4000 0000 0000 0002 | Declined, generic |

package/skills/stripe-integration/references/billing.md

@@ -0,0 +1,58 @@
+# Stripe subscriptions, customer portal and test clocks
+
+## Subscription via Checkout
+
+```ts
+const session = await stripe.checkout.sessions.create(
+  {
+    mode: 'subscription',
+    customer: user.stripeCustomerId, // create the Customer once per user and store it
+    line_items: [{ price: plan.priceId, quantity: 1 }],
+    subscription_data: { trial_period_days: 14, metadata: { user_id: user.id } },
+    success_url: 'https://app.example.com/billing/success?session_id={CHECKOUT_SESSION_ID}',
+    cancel_url: 'https://app.example.com/billing',
+  },
+  { idempotencyKey },
+);
+```
+
+Store `session.subscription` from `checkout.session.completed`. From then on, the subscription `status` is the source of truth for access:
+
+| `status` | Typical access |
+|---|---|
+| `trialing`, `active` | Full |
+| `past_due` | Your policy: grace period while Stripe retries |
+| `unpaid`, `canceled`, `incomplete_expired`, `paused` | None |
+| `incomplete` | None until the first invoice is paid (often SCA pending) |
+
+Sync it on `customer.subscription.created`, `.updated` and `.deleted`, and extend access to the period end on `invoice.paid`. On API version `2025-03-31.basil` and later, the period fields are on subscription items (`items.data[].current_period_end`), not on the subscription; older versions have `subscription.current_period_end`. Read the field for the API version you pinned. If events arrive out of order, retrieve the subscription from the API and store what it says.
+
+Plan changes: `stripe.subscriptions.update(subId, { items: [{ id: itemId, price: newPriceId }], proration_behavior: 'create_prorations' })` with an idempotency key, or let the portal do it.
+
+## Customer portal
+
+1. Configure features (cancel, switch plan, update payment method, invoice history) in the Dashboard's customer portal settings, or with `stripe.billingPortal.configurations.create`.
+2. From an authenticated route:
+
+```ts
+const portal = await stripe.billingPortal.sessions.create({
+  customer: currentUser.stripeCustomerId, // from your session, never from the request body
+  return_url: 'https://app.example.com/billing',
+});
+redirect(portal.url);
+```
+
+Changes made in the portal arrive as the same subscription and invoice webhooks; no extra handling.
+
+## Test clocks
+
+Test clocks simulate time for billing objects in test mode or a sandbox.
+
+```ts
+const clock = await stripe.testHelpers.testClocks.create({ frozen_time: Math.floor(Date.now() / 1000) });
+const customer = await stripe.customers.create({ email: 'trial@example.com', test_clock: clock.id });
+// attach a test payment method, create the subscription, then:
+await stripe.testHelpers.testClocks.advance(clock.id, { frozen_time: clock.frozen_time + 15 * 24 * 3600 });
+```
+
+Advancing is asynchronous: wait for the clock's status to return to `ready` (or the `test_helpers.test_clock.ready` event) before asserting. Scenarios worth running: trial converts to paid, renewal succeeds, renewal fails with `4000 0000 0000 0341` attached (card attaches but charges fail), cancellation at period end takes effect. Only customers created with the clock move with it; delete the clock when done.

package/skills/stripe-integration/references/webhooks.md

@@ -0,0 +1,76 @@
+# Stripe webhooks
+
+## What Stripe sends
+
+- `POST` with a JSON `Event` (snapshot payload) or a thin event notification, depending on how the event destination was created. Most existing integrations use snapshot events and read `event.data.object`.
+- Header `Stripe-Signature: t=<timestamp>,v1=<hmac-sha256>[,v1=...]`. The signature is HMAC-SHA256 of `"<t>.<raw body>"` with the endpoint's `whsec_` secret. Only `v1` is valid; ignore other schemes.
+- Live mode retries with exponential backoff for up to three days; sandboxes retry three times over a few hours. `3xx` counts as failure.
+- Delivery is at least once and order is not guaranteed. Don't use `created` to order or dedupe; track `event.id`.
+- Each endpoint, and test vs live, has its own signing secret. During a secret roll, two secrets may be active for up to 24 hours.
+
+## Handler rules
+
+1. Read the **raw body bytes**. Any body parser that runs first breaks verification.
+2. `stripe.webhooks.constructEvent(rawBody, signatureHeader, endpointSecret)`; on error respond `400` and stop. Keep the default 5-minute tolerance and keep server clocks synced.
+3. Respond `2xx` immediately, then process in a queue.
+4. In the worker: skip if `event.id` is already recorded; otherwise handle the type, fetch fresh objects from the API when you need current state, and record `event.id` in the same database transaction as the state change.
+5. Subscribe the endpoint only to the event types you handle.
+6. Exempt the route from CSRF middleware (Rails, Django, Laravel).
+
+## Express (TypeScript)
+
+```ts
+import express from 'express';
+import Stripe from 'stripe';
+
+const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);
+const app = express();
+
+// Must be registered before app.use(express.json())
+app.post('/webhooks/stripe', express.raw({ type: 'application/json' }), (req, res) => {
+  let event: Stripe.Event;
+  try {
+    event = stripe.webhooks.constructEvent(req.body, req.header('stripe-signature') ?? '', process.env.STRIPE_WEBHOOK_SECRET!);
+  } catch {
+    return res.sendStatus(400);
+  }
+  res.sendStatus(200);
+  queue.add('stripe-event', { id: event.id, type: event.type, objectId: (event.data.object as { id: string }).id });
+});
+```
+
+## Next.js route handler
+
+```ts
+export async function POST(req: Request) {
+  const raw = await req.text(); // unparsed body
+  try {
+    const event = stripe.webhooks.constructEvent(raw, req.headers.get('stripe-signature') ?? '', process.env.STRIPE_WEBHOOK_SECRET!);
+    await enqueue(event.id, event.type);
+  } catch {
+    return new Response('invalid signature', { status: 400 });
+  }
+  return new Response('ok');
+}
+```
+
+## Events to handle
+
+| Event | Do |
+|---|---|
+| `checkout.session.completed` | If `payment_status` is `paid`, fulfil the order in `client_reference_id` / `metadata.order_id` once |
+| `checkout.session.async_payment_succeeded` / `_failed` | Fulfil or fail delayed-method payments |
+| `payment_intent.succeeded` / `payment_intent.payment_failed` | Custom Payment Element flows |
+| `invoice.paid` | Extend subscription access to the new period |
+| `invoice.payment_failed` | Start dunning; notify the customer |
+| `customer.subscription.updated` / `customer.subscription.deleted` | Sync plan, status and cancellation |
+| `charge.refunded`, `charge.dispute.created` | Reverse or flag fulfilment |
+
+## Local testing
+
+```bash
+stripe login
+stripe listen --forward-to localhost:4242/webhooks/stripe   # prints a whsec_ for this session
+stripe trigger checkout.session.completed
+stripe events resend <event_id> --webhook-endpoint=<endpoint_id>
+```

package/skills/subscription-billing-ops/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: subscription-billing-ops
+description: Runs the day-to-day mechanics of recurring revenue in any billing system, whether a provider's billing product or your own ledger, covering plan and price changes with grandfathering, proration on upgrades and downgrades, trials and trial conversion, failed-payment dunning and retry schedules, invoice and credit note lifecycles, cancellation and refund policy, and basic MRR, churn and deferred revenue reporting. Use when designing or changing how plans are billed, migrating customers to a new price, deciding what a mid-cycle upgrade should cost, building a dunning flow, issuing credit notes, or reconciling MRR numbers that don't add up.
+license: MIT
+compatibility: Any Agent Skills host. Provider-neutral; for Stripe-specific API calls also load stripe-integration. Examples use SQL and TypeScript-like pseudocode.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: business
+  kete-loom/risk: writes-files
+  kete-loom/owner: "Kete-org"
+---
+
+# Subscription billing operations
+
+Make every recurring charge explainable: a customer, finance or an auditor should be able to take any invoice and see which plan, price version, period and proration rule produced each line. This skill covers billing behaviour and data, not a provider's API. For Stripe calls use `stripe-integration`; for African payment providers use their own skills; for invoice legal fields and tax use `invoicing-and-tax`.
+
+## Ground rules
+
+1. **Money is integer minor units plus an ISO 4217 currency.** Never floats. Round once, at a defined step, with a documented rule (see `references/proration.md`).
+2. **Prices are versioned and immutable.** A price change creates a new price row; existing subscriptions keep pointing at the old one until you move them deliberately. Never edit an amount in place.
+3. **Issued invoices are immutable.** Fix a finalised invoice with a credit note (full or partial) and, if needed, a new invoice. Never edit or delete it. Drafts can change; finalised cannot.
+4. **Periods are half-open instants in UTC**: `[period_start, period_end)`. Store the customer's billing anchor and timezone separately and only use them to compute the next boundary and to display dates.
+5. **One subscription state machine, one source of truth.** If a provider runs billing, its subscription status drives access; your copy is a cache refreshed from its events. If you run billing, every state change is a row in an append-only event log.
+6. **Every charge attempt is idempotent**, keyed on `(invoice_id, attempt_number)`, so a retried job never charges twice.
+7. **Revenue reporting reads from invoices and credit notes, not from the plan table.** MRR from list prices lies whenever there are discounts, credits or failed payments.
+
+## Workflow
+
+1. **Map what exists.** Search the codebase for the plan/price, subscription, invoice, credit note and payment tables or provider objects, the renewal job or webhook handlers, and where access is granted or revoked. Write a one-line flow: `signup → trial → first invoice → renewal → dunning → cancel`.
+2. **Identify who computes what.** Decide per concern whether the provider or your code owns it: proration, tax, dunning retries, invoice numbering, emails. Two owners for one concern is the most common source of double charges and mismatched totals. Stop and ask the user if it is unclear.
+3. **Make the change using the rules for that area below.**
+4. **Write tests with a fake clock** for each boundary you touched: trial end, renewal on the 31st, leap day, DST change in the customer's timezone, upgrade one second before renewal, downgrade, cancel at period end, failed payment then recovery.
+5. **Backfill or migrate with a dry run first** (see "Migrating prices"). Print the before and after per customer, get approval, then run.
+
+## Plans and price changes
+
+- New customers get the new price immediately. Existing customers: choose **grandfather** (stay on old price), **migrate at next renewal** (with notice), or **migrate now** (prorated). This is a business and sometimes legal decision: stop and ask the user, and ask what notice period applies.
+- Keep a `price_version` or price ID on every subscription item and invoice line.
+- Plan limits and features live in an entitlements table keyed by price, not hard-coded per plan name.
+
+## Proration
+
+Decide and document per change type. Defaults that rarely surprise customers:
+
+| Change | Default |
+|---|---|
+| Upgrade mid-cycle | Charge the prorated difference now (credit unused old time, charge remaining new time), keep the anchor |
+| Downgrade mid-cycle | Apply at period end; no refund |
+| Quantity increase (seats) | Prorate now, or true-up at next invoice; pick one |
+| Quantity decrease | Apply at period end |
+| Billing interval change (monthly → annual) | Credit unused time, start a new period now, reset anchor |
+
+Compute proration by seconds (or days, if you document it) of the half-open period. Worked examples, rounding rules and edge cases in `references/proration.md`.
+
+## Trials
+
+- Store `trial_end` as an instant. At `trial_end`, either convert (first invoice, charge) or end (no access), never both by different jobs.
+- Collect a payment method up front or not: it changes conversion and dunning. Ask the user if not decided.
+- Send a reminder before conversion where the law or card network rules require it; check local rules for the markets you sell in and do not assume.
+- A trial extension moves `trial_end`; it never creates a zero-amount invoice that later looks like revenue.
+
+## Dunning and retries
+
+1. On a failed charge, keep the invoice `open` (unpaid), move the subscription to `past_due` (or the provider's equivalent), and schedule retries. A common schedule is 3 to 4 retries over 1 to 3 weeks; let the provider's smart retries run if it has them, and don't add your own on top.
+2. Notify the customer on the first failure with a link to update the payment method; retry immediately when they update it.
+3. Classify declines: hard declines (stolen card, closed account) stop retrying and ask for a new method; soft declines (insufficient funds, issuer unavailable) retry.
+4. Decide the end state after the last retry: cancel, pause, or leave unpaid with access cut. Stop and ask the user; it is a policy decision.
+5. Grace period: access during dunning is a policy setting, not an accident of which webhook arrived first.
+6. When a past-due invoice is finally paid, restore access and do not reset the billing anchor unless the policy says so.
+
+## Invoices and credit notes
+
+- Lifecycle: `draft → open (finalised, numbered) → paid | void | uncollectible`. Number on finalisation, from a gap-free sequence per legal entity if the jurisdiction requires it.
+- Credit notes reference the original invoice, carry their own number, and reverse tax in the same proportion as the lines they credit.
+- Refund and credit are different things: a credit note reduces what is owed; a refund moves money back. A refund of a paid invoice usually needs both.
+- Void only an invoice that was never sent or paid, if your jurisdiction allows it; otherwise credit it.
+
+## Cancellations
+
+- Offer `cancel at period end` (default) and `cancel now`. Cancel now needs a refund rule: none, prorated credit, or prorated refund. Ask the user.
+- Cancellation stops future invoices; it does not void open ones. Decide whether open past-due invoices are still collected.
+- Make cancellation as easy as signup; several jurisdictions have rules on this. Do not build dark patterns.
+
+## Revenue reporting basics
+
+- **MRR**: normalise each active, paid subscription's recurring invoice amount after discounts to a month (annual ÷ 12). Exclude one-off charges, tax and usage unless you report them separately.
+- **MRR movements** per month: new, expansion, contraction, churn, reactivation. They must sum from opening to closing MRR; if they don't, there is a bug.
+- **Churn**: logo churn (customers lost ÷ customers at start) and revenue churn (MRR lost ÷ MRR at start), each defined in writing.
+- **Deferred revenue**: an annual prepayment is earned monthly. Reporting it as revenue on the day paid is wrong under accrual accounting. Recognition policy (ASC 606, IFRS 15) belongs to the finance team; give them the invoice and period data, don't decide policy in code.
+
+Queries for these in `references/revenue-metrics.md`.
+
+## Migrating prices
+
+1. Select affected subscriptions; write the old and new amount, next invoice date and proration per customer to a file.
+2. Show totals and a sample to the user; stop and wait for approval.
+3. Send required notice before the change takes effect.
+4. Run in batches with idempotency keys, logging each subscription ID and result; make the script resumable.
+5. Reconcile: next-cycle invoice totals must match the dry-run file.
+
+## Never
+
+- Never charge, refund or migrate live customers without explicit approval for that run.
+- Never recompute an issued invoice from current prices.
+- Never let two systems (yours and the provider's) both send dunning emails or both compute proration.
+- Never use the server's local timezone for period maths.
+
+## Report format
+
+When asked to design or review a billing change, return:
+
+```
+Change: <one line>
+Owner per concern: proration=<provider|app>, tax=..., dunning=..., numbering=...
+Customer impact: <who pays what, when; one example invoice>
+Edge cases tested: <list>
+Decisions needed from the user: <list, or none>
+```