@ketecode/loom 0.0.0-stage → 0.1.0

package/skills/ml-experiment-workflow/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: ml-experiment-workflow
+description: Plans and runs machine learning experiments so results can be trusted, from a dumb baseline and leakage-free train, validation and test splits, through tracked runs, metrics chosen to match the business goal, and ablations, to turning a notebook into a repeatable pipeline. Use when starting a new model, comparing approaches, deciding whether an improvement is real, or productionising notebook experiments.
+license: MIT
+compatibility: Any Agent Skills host. Framework-agnostic (scikit-learn, PyTorch, XGBoost and others); needs Python to run experiments.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: ai
+  kete-loom/risk: runs-commands
+  kete-loom/requires: "python, git"
+  kete-loom/owner: "Kete-org"
+---
+
+# ML experiment workflow
+
+An experiment is only useful if someone else could rerun it and get the same answer, and if the number it reports means what the user thinks it means. Follow these steps in order. For PyTorch training-loop mechanics use the `pytorch-patterns` skill; for evaluating LLM outputs use `llm-evals`.
+
+## 1. Pin down the goal
+
+Write these down with the user before touching data:
+
+1. **Decision.** What will be done differently if the model is good? (Auto-approve claims, rank search results, flag churn risk.)
+2. **Metric that matches it.** Pick from the cost of errors, not habit:
+   - Imbalanced classes: precision/recall at an operating threshold, PR-AUC, or cost-weighted error. Accuracy is misleading when one class is 95% of the data.
+   - Ranking: NDCG@k, recall@k, MRR at the k the product shows.
+   - Probabilities used downstream: log loss and calibration (Brier score, reliability plot).
+   - Regression: MAE when all errors cost the same, RMSE when large errors are much worse, MAPE only when targets are never near zero.
+3. **Bar to beat.** The current system's number, or a minimum the decision needs.
+4. **Unit of prediction.** Per user, per transaction, per day? This drives the split.
+
+**Stop and ask** if the user cannot name the decision or the metric. Don't pick one silently.
+
+## 2. Split without leakage
+
+Decide the split before any exploration, then never look at the test set until the end.
+
+- **Time-ordered data** (forecasting, anything predicted about the future): split by time. Train on the past, validate and test on later periods. Use `TimeSeriesSplit` or a rolling-origin scheme, not random K-fold. When the label looks ahead (for example "churns in the next 30 days"), leave a gap of at least that horizon between train and validation (`TimeSeriesSplit(gap=...)`) so training labels do not overlap the validation period.
+- **Grouped data** (several rows per patient, user, device, document): split by group so no group appears on both sides. Use `GroupKFold` / `GroupShuffleSplit`.
+- **Imbalanced labels**: stratify (`StratifiedKFold`, `StratifiedGroupKFold`).
+- **Duplicates**: dedupe, or group near-duplicates, before splitting.
+
+Leakage checklist (any yes means fix before continuing):
+
+- Is any preprocessing (scaling, imputation, target encoding, feature selection, vocabulary, PCA) fitted on data that includes validation or test rows? Fit it inside the training fold only; in scikit-learn, put it in a `Pipeline` passed to cross-validation.
+- Does any feature use information not available at prediction time (a later timestamp, a status set after the outcome, an aggregate over the whole dataset)?
+- Was the test set used to choose features, hyperparameters, thresholds or the stopping epoch?
+- Is a feature suspiciously predictive on its own? Check top-importance features one by one.
+
+## 3. Baselines first
+
+Before any real model, record:
+
+1. A trivial baseline: majority class / mean prediction / "same as last period" / popularity ranking.
+2. A simple model: logistic or linear regression, or gradient-boosted trees for tabular data, with default settings.
+3. The current production system, if there is one.
+
+If a complex model does not clearly beat the simple one, report that; it is a result, not a failure.
+
+## 4. Track every run
+
+Each run records, automatically:
+
+- git commit (and whether the tree was dirty), config/hyperparameters, seed
+- dataset version: file hash, snapshot id or query plus date
+- metrics on validation (and test only for the final run), with the split definition
+- environment: Python and key library versions, hardware
+- artifacts: model file, predictions on the validation set
+
+Use whatever the project already has (MLflow, Weights & Biases, DVC, a CSV log). If there's nothing, write one JSON line per run to a log file and commit the code that writes it. Don't add a tracking service the user did not ask for.
+
+## 5. Decide whether a gain is real
+
+- Run the leading candidates with at least 3 seeds (or use cross-validation folds) and report mean and spread, not the best run.
+- A gain smaller than the seed-to-seed spread is noise. Say so.
+- For a single held-out set, use a paired bootstrap over test examples to get an interval on the difference.
+- Compare models on the same split, the same preprocessing and the same eval code.
+- Look at the errors: slice the metric by important segments (region, device, class, new vs returning users). An average gain that hides a regression on a key segment must be reported.
+
+## 6. Ablations
+
+When a model has several changes stacked together, remove one at a time from the final configuration and rerun. Report a table:
+
+```
+| Variant                  | Val metric (mean ± std, n seeds) | Δ vs full |
+|--------------------------|----------------------------------|-----------|
+| Full                     | 0.812 ± 0.004                    | —         |
+| − feature group X        | 0.809 ± 0.005                    | −0.003    |
+| − augmentation           | 0.781 ± 0.006                    | −0.031    |
+```
+
+Drop any component whose removal does not hurt beyond noise; it is complexity with no evidence behind it.
+
+## 7. From notebook to pipeline
+
+Do this once an approach is worth keeping:
+
+1. Move code out of cells into modules with functions: `load_data`, `build_features`, `split`, `train`, `evaluate`. The notebook then only imports and calls them.
+2. Put every constant (paths, dates, hyperparameters, seed) in one config file.
+3. Provide one command that runs the whole thing end to end, for example `python -m project.train --config configs/baseline.yaml`.
+4. Add tests for the feature code and the split: a test that train and test share no group ids or overlapping time ranges is cheap and catches the worst bugs.
+5. Rerun from a clean checkout and confirm the metric matches the notebook within seed noise. If it does not, find out why before anything else.
+
+## 8. Final evaluation
+
+Only after model, features and threshold are frozen: evaluate once on the test set. If the test result is then used to change anything, that set is no longer a test set; say so and hold out new data.
+
+## Never
+
+- Never report a test-set number that was used for tuning.
+- Never report the best of many seeds as the result.
+- Never fit preprocessing on the full dataset before splitting.
+- Never claim an improvement without the baseline beside it.
+
+## Report
+
+```
+Goal: <decision> | Metric: <metric @ threshold/k> | Bar: <number>
+Split: <method, sizes, date ranges or group key>
+Results (validation, n seeds):
+  baseline: ... | simple model: ... | candidate: ...
+Test (final, once): ...
+Leakage checks: <passed / issues found>
+Caveats: <segments that regressed, what was not checked>
+Reproduce: <exact command and commit>
+```

package/skills/ml-experiment-workflow/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "We want to predict customer churn next quarter. How should I set up the experiment and which metric should we use?",
+    "My new model is 0.4% better on validation than the old one. Is that a real improvement?",
+    "Turn my exploratory Jupyter notebook into a reproducible training pipeline with tracked runs",
+    "Plan an ablation study for the three changes we stacked into the fraud model",
+    "How do I split patient records into train and test so the same patient never shows up in both?"
+  ],
+  "should_not_trigger": [
+    "My torch DataLoader is slow and the GPU sits at 20% utilisation",
+    "Check this pull request's feature engineering code for target leakage and broadcasting bugs",
+    "Write a SQL query that counts weekly active users by country",
+    "Score our RAG assistant's answers for faithfulness against the source documents",
+    "Benchmark this sorting function against the old version and tell me if it's faster"
+  ]
+}

package/skills/mongodb-patterns/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: mongodb-patterns
+description: MongoDB document modelling and query tuning, from embed-versus-reference decisions and unbounded-array traps to compound indexes ordered by the ESR rule, reading explain executionStats, aggregation pipelines, multi-document transactions on replica sets, and $jsonSchema collection validation. Use when designing or changing MongoDB collections, a MongoDB query or aggregation is slow, adding indexes or validators, or deciding whether a write needs a transaction, with the native driver, Mongoose or another ODM.
+license: MIT
+compatibility: Any Agent Skills host. Commands are mongosh syntax; the same options exist in every official driver. Atlas-only features (Atlas Search, Performance Advisor) are noted as such.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: data
+  kete-loom/risk: runs-commands
+  kete-loom/requires: "mongosh"
+  kete-loom/owner: "Kete-org"
+---
+
+# MongoDB patterns
+
+Model documents around how the application reads them, index for the queries it actually runs, and prove every performance claim with `explain`. The detailed recipes live in `references/indexes-and-aggregation.md`.
+
+## 0. Before you start
+
+1. Find the driver or ODM (native driver, Mongoose, Motor, Spring Data, Prisma) and where the connection string comes from. Search for `MongoClient`, `mongoose.connect` or the `mongodb://` / `mongodb+srv://` variable.
+2. Get the server version and topology with `db.version()` and `db.hello()` (look for `setName` for a replica set, `msg: "isdbgrid"` for mongos). Transactions and change streams need a replica set or sharded cluster.
+3. List the queries the feature will run: filter fields, sort, projection, and how many documents each returns. If you can't list them, **stop and ask the user**; a model can't be judged without them.
+4. Never run `dropDatabase`, `drop`, `deleteMany({})`, `updateMany` without a tight filter, or a `collMod` that tightens validation on a shared or production database without the user's explicit approval. Build indexes on large production collections only after the user has agreed on timing; they consume I/O while they build.
+
+## 1. Embed or reference
+
+Embed when the data is read together, owned by the parent, and bounded in size. Reference when it is shared, updated on its own, or grows without limit.
+
+| Relationship | Default |
+|---|---|
+| One-to-few, read with the parent (addresses, line items of an order) | Embed an array |
+| One-to-many, unbounded (comments on a post, events of a device) | Separate collection with the parent's `_id` indexed on the child |
+| Many-to-many (students and courses) | Array of IDs on the side queried most, or a link collection |
+| Data shared by many parents and edited (product name in old orders) | Reference; copy only fields that should freeze at write time (the price paid) |
+
+Rules:
+
+- A document is at most 16 MiB. Any array that grows with user activity must have a hard cap or live in its own collection. Large, frequently rewritten arrays also make every update expensive.
+- Design so the common page loads with **one query**. If it needs `$lookup` on every request, reconsider the model (or accept it knowingly for low-traffic paths).
+- Duplicating a field is fine when you know who updates the copies. Write it down in the code next to the update.
+- Use the **bucket** pattern for time series on older servers (one document per device per hour), or a native time series collection (`db.createCollection(name, { timeseries: { timeField, metaField } })`).
+- Use the **subset** pattern for large related lists: embed the latest N, keep the rest in a separate collection.
+
+## 2. Indexes
+
+- Every query in a request path needs an index that supports its filter and sort. A `COLLSCAN` in `explain` on a large collection is a bug.
+- Order compound index keys by **ESR**: **E**quality fields first, then **S**ort fields, then **R**ange fields (`$gt`, `$lt`, `$in` with many values, regex).
+- One compound index can serve its prefixes: `{ tenantId: 1, status: 1, createdAt: -1 }` also serves `{ tenantId: 1 }`. Drop indexes that are a prefix of another.
+- Use partial indexes (`partialFilterExpression`) for queries that only touch a subset, unique indexes for invariants, and TTL indexes (`expireAfterSeconds`) for expiring data.
+- Each index costs RAM and slows every write. Check usage with `db.coll.aggregate([{ $indexStats: {} }])` before adding more, and propose removing unused ones (hide them first with `db.coll.hideIndex(name)` to test safely).
+
+Verify with:
+
+```js
+db.orders.find({ tenantId: t, status: "open" }).sort({ createdAt: -1 }).explain("executionStats")
+```
+
+Read `winningPlan` (want `IXSCAN`, no in-memory `SORT` stage), `totalKeysExamined` and `totalDocsExamined` against `nReturned` (want them close), and `executionTimeMillis`. Report these numbers before and after.
+
+## 3. Aggregation
+
+- Put `$match` first and `$project`/`$unset` early so later stages see fewer, smaller documents; only the leading `$match` and `$sort` can use an index.
+- `$lookup` needs an index on the foreign field. Avoid `$lookup` inside hot request paths when an embed would do.
+- Each blocking stage (`$group`, `$sort` without an index, `$bucket`) has a 100 MB memory limit before it spills to disk or errors, depending on `allowDiskUse` and the server default. Spilling is slow; prefer narrowing earlier.
+- Use `$facet` for several counts over one result set instead of several round trips, and `$merge`/`$out` to precompute heavy reports on a schedule.
+- Paginate with a range on an indexed key (`_id > lastSeenId`), not large `skip` values.
+
+## 4. Transactions
+
+- A single-document write is already atomic, including its embedded arrays. Model so most invariants live in one document; reach for a transaction only when several documents must change together.
+- Transactions need a replica set or sharded cluster, and by default must finish within 60 seconds (`transactionLifetimeLimitSeconds`). Keep them short and touch few documents.
+- Use the driver's callback API (`session.withTransaction(fn)`), which retries on `TransientTransactionError` and `UnknownTransactionCommitResult`. Pass the session to **every** operation inside, or that operation runs outside the transaction.
+- Use `writeConcern: { w: "majority" }` and `readConcern: "snapshot"` for transactions whose result must survive failover.
+- Outside transactions, guard concurrent updates with conditional filters (`updateOne({ _id, version: 3 }, { $set: {...}, $inc: { version: 1 } })`) and check `matchedCount`.
+
+## 5. Schema validation
+
+Keep the database honest even if one service skips the ODM's checks:
+
+```js
+db.runCommand({
+  collMod: "orders",
+  validator: { $jsonSchema: {
+    bsonType: "object",
+    required: ["tenantId", "status", "total"],
+    properties: {
+      status: { enum: ["open", "paid", "cancelled"] },
+      total: { bsonType: "decimal" }
+    }
+  }},
+  validationLevel: "moderate",
+  validationAction: "error"
+})
+```
+
+- Roll out on an existing collection with `validationAction: "warn"` first, check the logs for violations, fix the data, then switch to `"error"`. `validationLevel: "moderate"` checks inserts and updates to documents that are already valid; updates to documents that were already invalid are not checked, so fix those in a backfill.
+- Store money as `Decimal128` or integer minor units, never as a double. Store dates as BSON dates, not strings.
+
+## Never
+
+- Build query filters from raw request JSON; a body like `{ "$ne": null }` becomes an operator. Validate types or use a sanitiser, and reject keys starting with `$`.
+- Use `$where` or server-side JavaScript on user input.
+- Let arrays grow without a limit inside a document.
+- Claim a query is fast without `explain("executionStats")` output.
+
+## Report format (when reviewing)
+
+```
+MongoDB review: <collections or feature>
+Topology/version: <replica set | sharded | standalone>, <version>
+Findings:
+1. [severity] <file:line or collection>: <problem> → <fix>
+Explain evidence: <query> keys/docs examined vs returned, before → after
+Not verified: <anything you could not run>
+```

package/skills/mongodb-patterns/evals/triggers.json

@@ -0,0 +1,18 @@
+{
+  "should_trigger": [
+    "Should I embed comments inside the post document or put them in their own MongoDB collection?",
+    "This Mongo aggregation with $lookup and $group takes 8 seconds, help me speed it up",
+    "explain() shows COLLSCAN on our orders collection, what compound index do we need?",
+    "Add a $jsonSchema validator to the users collection without breaking existing documents",
+    "Do I need a transaction in Mongoose to move credits between two wallet documents?",
+    "Design the document model for a multi-tenant SaaS on MongoDB Atlas"
+  ],
+  "should_not_trigger": [
+    "Cache the user profile in Redis with a five minute TTL",
+    "Write a Prisma schema for users and posts on Postgres",
+    "Design a ClickHouse table for billions of analytics events",
+    "Normalise this Postgres schema and add foreign keys",
+    "Write a zero-downtime migration that renames a column in MySQL",
+    "Review this pull request for SQL injection and auth bugs"
+  ]
+}

package/skills/mongodb-patterns/references/indexes-and-aggregation.md

@@ -0,0 +1,94 @@
+# MongoDB indexes and aggregation recipes
+
+Read this when designing an index for a specific query, debugging a slow aggregation, or writing a migration that reshapes documents. Confirm option names against the MongoDB manual for the server version in use.
+
+## ESR worked example
+
+Query:
+
+```js
+db.orders.find({ tenantId: t, status: "open", total: { $gte: 100 } }).sort({ createdAt: -1 })
+```
+
+- Equality: `tenantId`, `status`
+- Sort: `createdAt`
+- Range: `total`
+
+Index: `{ tenantId: 1, status: 1, createdAt: -1, total: 1 }`. Putting `total` before `createdAt` forces an in-memory sort.
+
+A covered query (only indexed fields in filter and projection, `_id: 0` unless `_id` is indexed in that index) shows `totalDocsExamined: 0`.
+
+## Reading explain
+
+```js
+db.coll.find(filter).sort(sort).explain("executionStats")
+db.coll.aggregate(pipeline, { explain: true })   // or .explain("executionStats") on the cursor
+```
+
+| Field | Good sign | Bad sign |
+|---|---|---|
+| `winningPlan.stage` tree | `IXSCAN` → `FETCH` | `COLLSCAN`; `SORT` stage (in-memory sort) |
+| `totalKeysExamined` / `nReturned` | close to 1 | much larger: index not selective or wrong order |
+| `totalDocsExamined` / `nReturned` | close to 1 | large: filter applied after fetch |
+| `rejectedPlans` | few | many similar indexes competing |
+
+Use the profiler only with the user's agreement on shared servers: `db.setProfilingLevel(1, { slowms: 100 })`, then `db.system.profile.find().sort({ ts: -1 }).limit(10)`. Turn it off afterwards with `db.setProfilingLevel(0)`. On Atlas, the Query Profiler and Performance Advisor show the same without changing settings.
+
+## Index options
+
+```js
+db.users.createIndex({ email: 1 }, { unique: true, collation: { locale: "en", strength: 2 } })   // case-insensitive unique
+db.sessions.createIndex({ expiresAt: 1 }, { expireAfterSeconds: 0 })                             // TTL at the stored date
+db.orders.createIndex({ status: 1, createdAt: -1 }, { partialFilterExpression: { status: "open" } })
+db.coll.hideIndex("old_index_name")    // test dropping without losing it
+db.coll.unhideIndex("old_index_name")
+```
+
+- A query uses a collation-specific index only if it specifies the same collation.
+- A partial index is used only when the query filter implies the partial expression.
+- The TTL monitor runs periodically, so expired documents disappear with some delay; don't rely on it for exact expiry.
+- A multikey index (on an array field) can't be compound with a second array field.
+
+## Aggregation patterns
+
+Top N per group:
+
+```js
+db.orders.aggregate([
+  { $match: { tenantId: t, createdAt: { $gte: since } } },
+  { $sort: { customerId: 1, total: -1 } },
+  { $group: { _id: "$customerId", top: { $firstN: { input: "$$ROOT", n: 3 } } } }
+])
+```
+
+(`$firstN` needs MongoDB 5.2 or later; on older servers use `$push` then `$slice`.)
+
+Indexed `$lookup` with a sub-pipeline (combining `localField`/`foreignField` with `pipeline` needs MongoDB 5.0 or later; older servers need `let` and `$expr`):
+
+```js
+{ $lookup: {
+    from: "customers",
+    localField: "customerId",
+    foreignField: "_id",
+    pipeline: [{ $project: { name: 1, tier: 1 } }],
+    as: "customer"
+}}
+```
+
+Several counts in one pass:
+
+```js
+{ $facet: {
+    byStatus: [{ $group: { _id: "$status", n: { $sum: 1 } } }],
+    total:    [{ $count: "n" }]
+}}
+```
+
+Precompute a report: end the pipeline with `{ $merge: { into: "daily_sales", on: "_id", whenMatched: "replace" } }` and run it from a scheduled job.
+
+## Reshaping documents safely
+
+1. Add the new field in code that writes both shapes; read with a fallback.
+2. Backfill in batches with `bulkWrite` filtered on documents missing the new field, so the job can be re-run.
+3. Switch reads to the new field, then stop writing the old one, then remove it with `$unset` in batches.
+4. Tighten the `$jsonSchema` validator last.

package/skills/mpesa-daraja-integration/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: mpesa-daraja-integration
+description: Implements and audits direct Safaricom M-Pesa integrations on the Daraja API in Kenya, including the OAuth client-credentials token, Lipa na M-Pesa Online (STK Push) with the base64 shortcode+passkey+timestamp password, stkCallback parsing, confirmation through the STK Push Query endpoint, C2B URL registration with validation and confirmation, B2C payouts with SecurityCredential, and the sandbox-to-production go-live path. Use when calling Daraja endpoints yourself rather than via Flutterwave or another aggregator, wiring an M-Pesa paybill or till into an app, or debugging Daraja errors such as invalid access token, wrong credentials or ResultCode 1032.
+license: MIT
+compatibility: Any Agent Skills host. Live calls need network access to sandbox.safaricom.co.ke or api.safaricom.co.ke. Examples are TypeScript (Node 18+); the rules apply to any backend language.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: integrations
+  kete-loom/risk: network
+  kete-loom/owner: "Kete-org"
+---
+
+# M-Pesa Daraja integration
+
+Build an M-Pesa flow where a forged callback can't mark an order paid, a lost callback still settles, and a payout is never sent twice. This skill is for Safaricom's Daraja API called directly. If the project collects M-Pesa through Flutterwave, Paystack or another aggregator, follow that provider's flow instead.
+
+## Ground rules
+
+1. **Credentials stay on the server.** Consumer key and secret, passkey, initiator name and initiator password are secrets in the environment. Sandbox and production have different keys, shortcodes, passkeys and base URLs (`https://sandbox.safaricom.co.ke` vs `https://api.safaricom.co.ke`).
+2. **Cache the access token.** `GET /oauth/v1/generate?grant_type=client_credentials` with Basic auth (`consumerKey:consumerSecret`) returns a token valid for about an hour (`expires_in` 3599 or 3600). Refresh before expiry; don't request one per payment.
+3. **The server sets the amount.** Daraja `Amount` is whole shillings. Compute it from your own order; never accept it from the client.
+4. **`ResponseCode: "0"` means accepted, not paid.** The STK Push response only says the prompt was queued. Store `CheckoutRequestID` and `MerchantRequestID` against the order straight away.
+5. **Callbacks are unsigned.** Daraja does not sign `stkCallback`, C2B or B2C results. Never give value from the callback body alone. Put an unguessable per-payment token in the callback path, match `CheckoutRequestID` to a stored pending payment, and confirm with STK Push Query (or Transaction Status) before fulfilling. If Safaricom gives you its callback IP range, allow-list it as an extra layer.
+6. **Fulfilment is idempotent.** Guarded update keyed on `CheckoutRequestID` (`... WHERE status = 'pending'`), and a unique constraint on `MpesaReceiptNumber`. Callbacks, queries and retries can all arrive.
+7. **Payouts are never sent blind twice.** Generate and store a unique `OriginatorConversationID` per payout before the call. Daraja is not documented to reject a repeated ID, so after a timeout or lost result check Transaction Status first and retry only when it shows the payout did not happen.
+
+## STK Push flow
+
+```
+client ──(order id, phone 2547XXXXXXXX)──▶ server: create pending payment
+server ──POST /mpesa/stkpush/v1/processrequest──▶ Daraja: ResponseCode "0", CheckoutRequestID
+customer enters M-Pesa PIN on the phone
+Daraja ──POST CallBackURL {Body.stkCallback}──▶ server: 200 at once, queue a check
+server ──POST /mpesa/stkpushquery/v1/query──▶ ResultCode 0 + amount matches → fulfil once
+background job: query payments still pending after ~1-2 minutes; expire them later
+```
+
+## Implementation steps
+
+1. **Configure** environment variables: base URL, consumer key/secret, `BusinessShortCode`, passkey, callback base URL, and for B2C the initiator name and production certificate. Shapes and samples: `references/api.md`.
+2. **Build the password**: `Timestamp` is `YYYYMMDDHHmmss` in Kenyan time (EAT, UTC+3); `Password = base64(BusinessShortCode + Passkey + Timestamp)`. Generate both per request; a stale timestamp or one in the wrong timezone causes "Wrong credentials".
+3. **Send STK Push** with `TransactionType` `CustomerPayBillOnline` (paybill) or `CustomerBuyGoodsOnline` (till; then `PartyB` is the till number while `BusinessShortCode` is the store/HO number). Normalise the phone to `2547XXXXXXXX` or `2541XXXXXXXX`. `AccountReference` is at most 12 characters, `TransactionDesc` at most 13.
+4. **Handle the callback** as in `references/callbacks.md`: respond quickly, match on `CheckoutRequestID`, read `ResultCode` and `CallbackMetadata`, then confirm with STK Push Query.
+5. **Map result codes** to customer messages: `1032` cancelled, `1037` phone unreachable, `1` insufficient balance, `2001` wrong PIN, `1019` expired, `17` duplicate request within 2 minutes. Let the customer retry with a new STK Push.
+6. **C2B (customer pays your paybill/till from their phone)**: register Confirmation and Validation URLs once with `/mpesa/c2b/v2/registerurl`; see `references/callbacks.md`. Match payments to orders by `BillRefNumber` (the account number the customer typed) and dedupe on `TransID`.
+7. **B2C payouts**: `/mpesa/b2c/v3/paymentrequest` with `SecurityCredential` (initiator password RSA-encrypted with Safaricom's certificate for that environment, base64). The result arrives at `ResultURL`; a timeout at `QueueTimeOutURL`. Treat a queue timeout as unknown, not failed: check Transaction Status before retrying.
+8. **Persist** per payment: order id, phone, amount, `MerchantRequestID`, `CheckoutRequestID`, `MpesaReceiptNumber`, `ResultCode`, `ResultDesc`, status, timestamps.
+
+## Reviewing an existing integration
+
+Check each ground rule, then look for:
+
+- Order marked paid when the STK Push request returns `ResponseCode "0"`.
+- Callback body trusted with no match to a stored `CheckoutRequestID` and no query.
+- `Amount` read from `CallbackMetadata` without comparing it to the stored order amount.
+- Token fetched on every request, causing spike-arrest or quota errors (`500.003.02`, `500.003.03`).
+- Timestamp built from server UTC or local time instead of EAT.
+- Callback URL that is not public HTTPS, uses a tunnel URL in production, or contains blocked words such as `mpesa`, `safaricom`, `sql`, `exec`, `cmd` or `query`.
+- Sandbox shortcode `174379` or sandbox passkey left in production config.
+- B2C retried after a timeout or missing result without a Transaction Status check first.
+
+## Stop and ask the user
+
+- Paybill or till, and which shortcode is used on go-live.
+- Whether C2B validation is needed; it is off by default and Safaricom has to enable it.
+- Before writing any B2C code: payouts move real money and need a B2C shortcode and an API initiator created on the M-Pesa org portal.
+
+## Before you finish
+
+Daraja's docs at developer.safaricom.co.ke are the final word on fields and endpoints; this skill gives the rules and the shape. Production endpoints and the production passkey are issued at go-live. Then test in the sandbox: a successful STK Push, a cancelled prompt (1032), a phone that never answers, a callback that never arrives (the query job must settle it), a forged callback with a known `CheckoutRequestID` but a failed query (must not fulfil), and the same callback twice.

package/skills/mpesa-daraja-integration/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "Implement Lipa na M-Pesa STK push for our Kenyan delivery app using Daraja",
+    "Daraja keeps returning Wrong credentials for my STK push password, what's wrong?",
+    "Register C2B confirmation and validation URLs for our paybill number",
+    "Pay out refunds to customers' M-Pesa numbers with the B2C API",
+    "Our stkCallback never arrives in production, how do we still confirm the payment?"
+  ],
+  "should_not_trigger": [
+    "Charge a Kenyan customer's M-Pesa wallet through Flutterwave from our backend",
+    "Integrate MTN MoMo request to pay for Ugandan customers",
+    "Accept Telecel Cash payments through Hubtel in our Ghana app",
+    "Check our checkout code for client-trusted amounts and missing idempotency",
+    "Add Stripe Checkout for card payments in Kenya"
+  ]
+}

package/skills/mpesa-daraja-integration/references/api.md

@@ -0,0 +1,103 @@
+# Daraja API shapes used by this skill
+
+Base URLs: sandbox `https://sandbox.safaricom.co.ke`, production `https://api.safaricom.co.ke`. Every call except the token call sends `Authorization: Bearer <token>` and `Content-Type: application/json` (a missing content type gives "Bad Request - Invalid BusinessShortCode").
+
+Confirm fields against developer.safaricom.co.ke before shipping; this is a working summary.
+
+## Access token
+
+`GET /oauth/v1/generate?grant_type=client_credentials` with `Authorization: Basic base64(consumerKey:consumerSecret)`.
+
+Response: `{ "access_token": "...", "expires_in": "3599" }`. `404.001.03 Invalid Access Token` means expired or from the wrong app.
+
+## STK Push (M-Pesa Express)
+
+`POST /mpesa/stkpush/v1/processrequest`
+
+```json
+{
+  "BusinessShortCode": "174379",
+  "Password": "<base64(BusinessShortCode + Passkey + Timestamp)>",
+  "Timestamp": "20260618092408",
+  "TransactionType": "CustomerPayBillOnline",
+  "Amount": "150",
+  "PartyA": "254712345678",
+  "PartyB": "174379",
+  "PhoneNumber": "254712345678",
+  "CallBackURL": "https://api.example.com/hooks/daraja/stk/<per-payment-token>",
+  "AccountReference": "ORD8F2C1A",
+  "TransactionDesc": "Order"
+}
+```
+
+Response: `MerchantRequestID`, `CheckoutRequestID`, `ResponseCode` (`"0"` = accepted), `ResponseDescription`, `CustomerMessage`.
+
+Limits from the Daraja FAQ: minimum KES 1, up to KES 250,000 per transaction, daily KES 500,000. Only one prompt can be live per subscriber; "Unable to lock subscriber" means wait about a minute.
+
+## STK Push Query
+
+`POST /mpesa/stkpushquery/v1/query`
+
+```json
+{ "BusinessShortCode": "174379", "Password": "<fresh>", "Timestamp": "<fresh>", "CheckoutRequestID": "ws_CO_..." }
+```
+
+Response has `ResultCode` and `ResultDesc`. `ResultCode` `"0"` = paid. While the customer has not answered, the query returns an error rather than a final code; retry with backoff.
+
+## Result codes (STK)
+
+| Code | Meaning |
+|---|---|
+| 0 | Paid |
+| 1 | Insufficient balance |
+| 17 | Same amount to same customer within 2 minutes |
+| 1019 | Transaction expired |
+| 1025 | Push failed (prompt over 182 characters; shorten AccountReference) |
+| 1032 | Cancelled by user |
+| 1037 | Phone unreachable |
+| 2001 | Wrong PIN |
+| 2028 | TransactionType / PartyB don't match the shortcode type |
+
+## C2B register URLs
+
+`POST /mpesa/c2b/v2/registerurl`
+
+```json
+{ "ShortCode": "600638", "ResponseType": "Completed", "ConfirmationURL": "https://api.example.com/hooks/daraja/c2b/confirm", "ValidationURL": "https://api.example.com/hooks/daraja/c2b/validate" }
+```
+
+`ResponseType` (`Completed` or `Cancelled`) is what M-Pesa does when your validation URL is unreachable. In production, registration is one-time; change URLs by deleting them in the URL management self-service and re-registering. Sandbox has `/mpesa/c2b/v2/simulate` for test payments.
+
+## B2C payment
+
+`POST /mpesa/b2c/v3/paymentrequest`
+
+```json
+{
+  "OriginatorConversationID": "payout_7d1e9b",
+  "InitiatorName": "apiop",
+  "SecurityCredential": "<RSA-encrypt(initiator password, Safaricom cert) as base64>",
+  "CommandID": "BusinessPayment",
+  "Amount": "500",
+  "PartyA": "600997",
+  "PartyB": "254712345678",
+  "Remarks": "Refund ORD8F2C1A",
+  "QueueTimeOutURL": "https://api.example.com/hooks/daraja/b2c/timeout/<token>",
+  "ResultURL": "https://api.example.com/hooks/daraja/b2c/result/<token>",
+  "Occassion": "Refund"
+}
+```
+
+`CommandID`: `BusinessPayment`, `SalaryPayment` or `PromotionPayment`. Note the API's spelling `Occassion`. The sandbox and production certificates differ. The response (`ConversationID`, `OriginatorConversationID`, `ResponseCode`) only means accepted; the outcome is the `Result` posted to `ResultURL` (`ResultCode`, `TransactionID`, `ResultParameters.ResultParameter[]`).
+
+## Password and timestamp (TypeScript)
+
+```ts
+export function stkPassword(shortCode: string, passkey: string, now = new Date()) {
+  // Daraja expects Kenyan time (EAT, UTC+3), formatted YYYYMMDDHHmmss
+  const eat = new Date(now.getTime() + 3 * 60 * 60 * 1000).toISOString();
+  const timestamp = eat.slice(0, 19).replace(/[-T:]/g, '');
+  const password = Buffer.from(shortCode + passkey + timestamp).toString('base64');
+  return { timestamp, password };
+}
+```

package/skills/mpesa-daraja-integration/references/callbacks.md

@@ -0,0 +1,74 @@
+# Daraja callbacks
+
+None of these are signed. Treat every body as untrusted: match it to a record you created, then confirm with a query before giving value.
+
+## STK Push callback
+
+`POST` to your `CallBackURL`:
+
+```json
+{
+  "Body": {
+    "stkCallback": {
+      "MerchantRequestID": "29115-34620561-1",
+      "CheckoutRequestID": "ws_CO_191220191020363925",
+      "ResultCode": 0,
+      "ResultDesc": "The service request is processed successfully.",
+      "CallbackMetadata": {
+        "Item": [
+          { "Name": "Amount", "Value": 1.0 },
+          { "Name": "MpesaReceiptNumber", "Value": "NLJ7RT61SV" },
+          { "Name": "TransactionDate", "Value": 20191219102115 },
+          { "Name": "PhoneNumber", "Value": 254708374149 }
+        ]
+      }
+    }
+  }
+}
+```
+
+A failed or cancelled payment has `ResultCode` other than `0` and no `CallbackMetadata`. Read items by `Name`, not by position; `Balance` sometimes appears and shifts the order.
+
+### Handler rules
+
+1. Check the per-payment token in the path, then find the pending payment by `CheckoutRequestID`. Unknown → log and return 200; never create an order from a callback.
+2. Respond `200` with `{ "ResultCode": 0, "ResultDesc": "Accepted" }` quickly and queue the work.
+3. In the worker: if `ResultCode !== 0`, mark failed with the code. If `0`, run STK Push Query; fulfil only if the query says `0` **and** `Amount` equals the stored amount. Guarded update on status, unique `MpesaReceiptNumber`.
+
+```ts
+app.post('/hooks/daraja/stk/:token', express.json(), async (req, res) => {
+  const cb = req.body?.Body?.stkCallback;
+  const payment = cb && (await payments.findPending(cb.CheckoutRequestID, req.params.token));
+  res.json({ ResultCode: 0, ResultDesc: 'Accepted' });
+  if (payment) await queue.add('daraja-confirm', { checkoutRequestId: cb.CheckoutRequestID, resultCode: cb.ResultCode });
+});
+```
+
+## C2B validation and confirmation
+
+Both URLs receive the same shape:
+
+```json
+{
+  "TransactionType": "Pay Bill",
+  "TransID": "RKTQDM7W6S",
+  "TransTime": "20191122063845",
+  "TransAmount": "10",
+  "BusinessShortCode": "600638",
+  "BillRefNumber": "invoice008",
+  "InvoiceNumber": "",
+  "OrgAccountBalance": "",
+  "ThirdPartyTransID": "",
+  "MSISDN": "25470****149",
+  "FirstName": "John",
+  "MiddleName": "",
+  "LastName": "Doe"
+}
+```
+
+- **Validation** (only if Safaricom enabled external validation on your shortcode): reply `{ "ResultCode": "0", "ResultDesc": "Accepted" }` to accept, or `{ "ResultCode": "C2B00012", "ResultDesc": "Rejected" }` to reject (`C2B00011` invalid MSISDN, `C2B00012` invalid account number, `C2B00013` invalid amount, `C2B00014` invalid KYC, `C2B00015` invalid shortcode, `C2B00016` other). Reply fast; if it is unreachable M-Pesa applies the registered `ResponseType`.
+- **Confirmation**: the payment is complete. Dedupe on `TransID`, match `BillRefNumber` to an open invoice, compare `TransAmount`, and park anything that doesn't match for manual review instead of dropping it: the customer's money has already moved. `MSISDN` may be masked or hashed, so don't rely on it to identify the payer.
+
+## B2C result
+
+`POST` to `ResultURL` with `{ "Result": { "ResultType", "ResultCode", "ResultDesc", "OriginatorConversationID", "ConversationID", "TransactionID", "ResultParameters": { "ResultParameter": [ { "Key", "Value" } ] } } }`. Match on `OriginatorConversationID`. `ResultCode` `0` = paid. A post to `QueueTimeOutURL` means the outcome is unknown: run Transaction Status (`/mpesa/transactionstatus/v1/query`) before any retry.