coding-os 0.3.2__py3-none-any.whl

core/skills/node-backend/scripts/check_package.py

@@ -0,0 +1,78 @@
+"""Audit a package.json for backend production-readiness signals.
+
+PURPOSE:      Flag a package.json that will bite in production — no engine pin,
+              no lockfile alongside, install-not-ci, missing start script.
+INPUT:        package.json path (default package.json) or --file. [--json]
+OUTPUT:       Findings on stderr; "clean"/"N finding(s)" on stdout. Exit 0
+              clean, 1 findings, 2 usage/parse error.
+DEPENDENCIES: stdlib only.
+NOTES:        Pure audit() is unit-testable. Lockfile check is filesystem-aware
+              only in main(); audit() takes a `has_lockfile` flag so it stays
+              pure. Spec: docs/playbooks/skill-authoring.md; craft: ../SKILL.md.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+LOCKFILES = ("package-lock.json", "pnpm-lock.yaml", "yarn.lock", "bun.lockb")
+
+
+def audit(pkg: dict, *, has_lockfile: bool) -> list[str]:
+    findings: list[str] = []
+    engines = pkg.get("engines", {})
+    if not isinstance(engines, dict) or "node" not in engines:
+        findings.append("no engines.node — pin the Node version (LTS) for reproducible runtime")
+    if not has_lockfile:
+        findings.append(
+            "no lockfile alongside (package-lock/pnpm-lock/yarn.lock) — builds are not reproducible"
+        )
+    scripts = pkg.get("scripts", {})
+    if isinstance(scripts, dict):
+        for name, body in scripts.items():
+            if isinstance(body, str) and "npm install" in body:
+                findings.append(
+                    f"script '{name}' runs 'npm install' (mutates lockfile) — use 'npm ci'"
+                )
+        if "start" not in scripts:
+            findings.append("no 'start' script — define the production entrypoint")
+    return findings
+
+
+def main(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser(description=__doc__.split("\n")[0])
+    parser.add_argument("path", nargs="?", default="package.json")
+    parser.add_argument("--file", default=None)
+    parser.add_argument("--json", action="store_true", dest="as_json")
+    args = parser.parse_args(argv)
+
+    target = Path(args.file or args.path)
+    try:
+        pkg = json.loads(target.read_text(encoding="utf-8"))
+    except FileNotFoundError:
+        print(f"error: {target} not found", file=sys.stderr)
+        return 2
+    except json.JSONDecodeError as exc:
+        print(f"error: {target}: {exc}", file=sys.stderr)
+        return 2
+    if not isinstance(pkg, dict):
+        print(f"error: {target}: root must be an object", file=sys.stderr)
+        return 2
+
+    has_lockfile = any((target.parent / lf).exists() for lf in LOCKFILES)
+    findings = audit(pkg, has_lockfile=has_lockfile)
+
+    for f in findings:
+        print(f"  ✗ {f}", file=sys.stderr)
+    if args.as_json:
+        print(json.dumps({"findings": findings, "count": len(findings)}))
+    else:
+        print("clean" if not findings else f"{len(findings)} finding(s)")
+    return 1 if findings else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

core/skills/node-backend/versions.json

@@ -0,0 +1,17 @@
+{
+  "nodejs": {
+    "ecosystem": "endoflife",
+    "package": "nodejs",
+    "track": "lts",
+    "version": "24.16.0",
+    "source": "https://endoflife.date/nodejs",
+    "checked": "2026-06-05"
+  },
+  "express": {
+    "ecosystem": "npm",
+    "package": "express",
+    "version": "5.2.1",
+    "source": "https://www.npmjs.com/package/express",
+    "checked": "2026-06-05"
+  }
+}

core/skills/observability/SKILL.md

@@ -0,0 +1,289 @@
+---
+name: observability
+tier: cross-cutting
+domain: [infra]
+description: Production observability done right — structured logs, distributed traces, metrics, alerting, SLO/SLI. Use when adding logging to a new service, designing dashboards, choosing between OpenTelemetry / Datadog / Grafana stack, defining SLOs for a feature, writing alert rules, or untangling a noisy alert channel. Stack-agnostic; recipes target OpenTelemetry as the canonical instrumentation, Prometheus + Grafana / Datadog as the canonical backends. Pairs with performance (perf budgets), security-web (audit logs), and incident-response (alert → runbook).
+last_reviewed: "2026-05-11"
+---
+
+# Observability — Logs, Traces, Metrics, SLOs
+
+A practical playbook for instrumenting production code so an incident at 03:00 takes minutes, not hours. Aligned with OpenTelemetry 1.x (the 2026 industry standard) and the SRE workbook's golden-signal approach.
+
+## When to Use This Skill
+
+- Adding logging / tracing / metrics to a new service.
+- Designing dashboards before launch — observability built in, not bolted on.
+- Choosing between OpenTelemetry, Datadog APM, Honeycomb, Grafana Stack, Sentry.
+- Defining SLO / SLI / error-budget policy for a feature.
+- Writing or reviewing alert rules — a good alert wakes a human at 03:00 for the right reason.
+- Investigating "we have logs but can't find the bug" or "alerts fire constantly so nobody reads them."
+
+Skip when: writing a one-off script or a dev-only tool with no production lifetime.
+
+## The Three Pillars + One
+
+Industry consensus (2020s onward) is *three pillars + traces-as-glue*:
+
+| Pillar | Question it answers | Tools |
+|---|---|---|
+| **Metrics** | "How is the system doing right now?" — counters, gauges, histograms | Prometheus, Datadog Metrics, CloudWatch Metrics |
+| **Logs** | "What exactly happened for *this* request?" — structured events | Loki, ELK, Datadog Logs, CloudWatch Logs |
+| **Traces** | "How did the work flow across services?" — spans + parent-child links | Jaeger, Tempo, Datadog APM, Honeycomb |
+| **Profiles** *(emerging fourth)* | "Why is the CPU/memory burning?" — continuous profiling | Pyroscope, Parca, Datadog Profiler |
+
+**Always use OpenTelemetry (OTel) as the instrumentation layer.** Send to whatever backend you pick. This decouples vendor choice from code — switching from Datadog to Honeycomb becomes a config change, not a rewrite. OTel SDK is stable for traces, metrics, and logs in 2026 across Python, TypeScript, Go, Java.
+
+## Golden Signals (Google SRE Book)
+
+Every service has four metrics worth tracking, no matter what it does:
+
+| Signal | What | Why |
+|---|---|---|
+| **Latency** | P50 / P95 / P99 of successful responses | Slow → users churn |
+| **Traffic** | Requests per second / events per second | Capacity planning, anomaly baseline |
+| **Errors** | Rate of failed requests (5xx for HTTP) | Reliability bottom line |
+| **Saturation** | "How full" — CPU%, mem%, queue depth, connection pool used | Predicts incidents before they fire |
+
+Dashboard rule: every service's home dashboard shows these four, large, top-left. Everything else is detail.
+
+## Structured Logs — Rules
+
+```python
+# Good — structured, machine-parseable, no PII
+logger.info("payment.captured", extra={
+    "user_id": str(user.id),  # uuid, not email
+    "order_id": str(order.id),
+    "amount_cents": amount_cents,
+    "currency": currency,
+    "processor": "stripe",
+    "latency_ms": int(elapsed * 1000),
+})
+```
+
+```typescript
+// Good — TypeScript, pino / Winston
+logger.info({
+  event: "payment.captured",
+  user_id: user.id,
+  order_id: order.id,
+  amount_cents: amountCents,
+  currency,
+  processor: "stripe",
+  latency_ms: Math.round(elapsed * 1000),
+});
+```
+
+```go
+// Good — Go, slog (stdlib 1.21+)
+slog.Info("payment.captured",
+    "user_id", user.ID,
+    "order_id", order.ID,
+    "amount_cents", amountCents,
+    "currency", currency,
+    "processor", "stripe",
+    "latency_ms", elapsedMs,
+)
+```
+
+**Hard rules:**
+
+- **Structured (JSON), not prose.** Prose logs are unparseable. Even if your dev tail looks at them, prod queries need fields.
+- **One event per log line.** Don't pack three things into one log call.
+- **`event` field with a dotted name.** `payment.captured`, `user.signup.failed`. Stable across versions, queryable across services.
+- **No PII.** No email, phone, IP, full name, full card number. Use IDs / hashed IDs. See [clean-code](../clean-code/SKILL.md) §1b.
+- **No secrets, ever.** No tokens, passwords, API keys, even masked.
+- **Log levels mean something.** `DEBUG` = dev only. `INFO` = a thing happened. `WARN` = unexpected but recoverable. `ERROR` = a request failed. `CRITICAL` = service degraded.
+- **Trace ID in every log.** OTel correlation: every log carries `trace_id` + `span_id` so you can pivot from "this slow request" to "all logs for this request".
+
+### Anti-patterns
+
+- `logger.info(f"user {email} logged in")` — PII leak.
+- `logger.info("done")` — no event, no context, useless.
+- `logger.error("error: " + str(exc))` — `str(exc)` may leak SQL/paths; use `exc_info=True` for structured stack trace.
+- Logging in a hot loop without sampling — kills your log bill.
+
+## Distributed Traces
+
+A trace is the request's life across services. Each step is a *span*. Parent-child spans build a tree.
+
+```python
+# Python — OpenTelemetry SDK
+from opentelemetry import trace
+
+tracer = trace.get_tracer(__name__)
+
+def process_order(order_id: str) -> Order:
+    with tracer.start_as_current_span("process_order") as span:
+        span.set_attribute("order.id", order_id)
+
+        with tracer.start_as_current_span("db.fetch_order"):
+            order = repo.find(order_id)
+
+        with tracer.start_as_current_span("payment.capture"):
+            capture_result = payment_service.capture(order)
+            span.set_attribute("payment.processor", capture_result.processor)
+
+        if capture_result.failed:
+            span.set_status(trace.Status(trace.StatusCode.ERROR, "capture failed"))
+            raise PaymentFailedError(capture_result.reason)
+
+        return order
+```
+
+**Rules:**
+
+- Every external call is a span (DB, HTTP, queue publish, third-party API).
+- Span name = action, not URL. `db.fetch_order`, not `SELECT * FROM orders WHERE id=...`.
+- Attributes on spans should be high-cardinality OK (`order.id`, `user.id`). Metrics shouldn't be.
+- Propagate trace context across service boundaries (`traceparent` HTTP header).
+- Sample tail-based in production. 100% sampling = 100% bandwidth bill.
+
+## Metrics — the four-cardinality rule
+
+A metric with high cardinality (= many unique label combinations) costs orders of magnitude more than a metric with low cardinality. Rule of thumb:
+
+| Label | OK as metric label? | Why |
+|---|---|---|
+| `service` | ✅ | Few values, stable |
+| `endpoint` (route template) | ✅ | Few values |
+| `status_code` | ✅ | ~10 values |
+| `region` | ✅ | Few values |
+| `user_id` | ❌ | Unbounded — millions of series |
+| `order_id` | ❌ | Unbounded |
+| Free-text error message | ❌ | Unbounded |
+
+Per-user data goes on traces and logs (where cardinality is fine), not metrics.
+
+### Histograms over averages
+
+`avg(latency)` hides the long tail. Use a histogram and query P50 / P95 / P99:
+
+```python
+# OpenTelemetry metric
+from opentelemetry.metrics import get_meter
+
+meter = get_meter(__name__)
+request_duration = meter.create_histogram(
+    "http.server.duration",
+    unit="ms",
+    description="HTTP server request duration",
+)
+
+# In the handler
+start = time.perf_counter()
+try:
+    response = handle(req)
+    request_duration.record((time.perf_counter() - start) * 1000,
+                            {"method": req.method, "route": req.route, "status": response.status})
+    return response
+```
+
+## SLO / SLI / Error Budget
+
+The **SLI** (Service Level Indicator) is what you measure: `% of requests under 200ms` or `% of requests not 5xx`.
+
+The **SLO** (Service Level Objective) is the target: `99.9% of requests under 200ms over 30 days`.
+
+The **error budget** is what you can spend: `0.1% × 30 days × 24h = 43.2 minutes of downtime`.
+
+### Why this matters
+
+When the team has burned 80% of the error budget halfway through the month, **all feature work stops** and reliability work takes priority. This is the contract that prevents "always-100%-uptime" arguments from blocking ship-fast culture, and "always-ship-fast" arguments from blocking reliability work.
+
+Concrete SLOs for typical surfaces:
+
+| Surface | SLO suggestion |
+|---|---|
+| HTTP API for paying users | 99.9% availability, P95 < 300ms |
+| Internal admin tool | 99% availability, P95 < 1s |
+| Background job processor | 99.5% job-completion within target deadline |
+| Public website | 99.9% availability, LCP < 2.5s (P75 mobile) |
+
+## Alerting — the 03:00 rule
+
+A page (someone-wakes-up alert) is justified only if **a) something is on fire** and **b) human action is required**. Everything else is a ticket, not a page.
+
+### Good alerts
+
+- "Error rate > 5% for 5 minutes on the checkout API" — users can't pay, wake up engineer.
+- "Database connection pool > 90% saturated for 10 minutes" — saturation predicts outage.
+- "Job queue depth > 10K and growing" — backlog forming.
+
+### Bad alerts (delete on sight)
+
+- "CPU > 80% for 1 minute" — CPU is supposed to be high under load.
+- "Disk usage > 70%" — nothing breaks at 70%, the alert at 90% is the real one.
+- "Service X restarted" — restarts are normal in K8s.
+- "P99 latency spiked once" — flaps; use multi-window burn-rate alerts.
+
+### Burn-rate alerts (Google SRE pattern)
+
+Instead of "5xx > 1%" (fires every minute on transient blips), alert when the error budget is burning fast enough that you'll exhaust it before the SLO window ends. Catches both short outages and slow degradations.
+
+## Audit Logs (compliance-grade)
+
+Distinct from operational logs. Audit logs answer "who did what to which object when, and from where?":
+
+```python
+audit.record(
+    actor=current_user.id,
+    actor_role=current_user.role,
+    action="user.permissions.granted",
+    target_object=("user", target_user.id),
+    target_change={"role_added": "admin"},
+    request_id=request.id,
+    source_ip=hash_ip(request.client_ip),  # hash for PII compliance
+    timestamp_utc=now_utc(),
+)
+```
+
+Audit logs go to **write-only, retention-policied storage** (separate index, separate retention from regular logs). Compliance frameworks (SOC2, GDPR, HIPAA, PCI-DSS) need them tamper-evident.
+
+For the coding-os meta-repo specifically: governance actions are reconstructable from git history (`git log`) and `cos_log_query`.
+
+## CI Signal Hygiene
+
+A green build with broken observability is a lying build. Check in CI:
+
+- **Schema lint** for log events — every `logger.info()` must include `event=` field.
+- **Trace integrity** — at least one integration test asserts `trace_id` propagates from inbound HTTP → downstream HTTP / DB call.
+- **No-PII linter** — grep for `email`, `phone`, `password`, raw IPs in log statements (allow only on a documented allowlist).
+- **No bare `time.sleep`** in production code paths — masks real timing issues.
+
+## Anti-patterns (reject in review)
+
+- **Prose logs in production** — `logger.info("user logged in")`. Use structured events.
+- **PII in logs** — emails, full names, IPs in cleartext.
+- **`print` in production** — `print()` doesn't go through the logging pipeline; logs vanish.
+- **High-cardinality metric labels** — `user_id`, `order_id` as metric labels kills your TSDB bill.
+- **Averages instead of percentiles** — `avg(latency)` lies. Use histograms.
+- **Alert on every error** — pages a human for noise; teaches them to mute.
+- **Logs without trace_id** — can't correlate logs to traces, debugging takes 10× longer.
+- **`exc.message` in logs** — may contain SQL/paths/secrets. Use `exc_info=True` for structured trace.
+
+## Tools per surface (2026 defaults)
+
+| Need | Open-source | Hosted |
+|---|---|---|
+| Instrumentation | OpenTelemetry SDK | OpenTelemetry SDK (same) |
+| Metrics | Prometheus + Grafana | Datadog Metrics, Grafana Cloud |
+| Logs | Loki + Grafana, or ELK | Datadog Logs, Splunk |
+| Traces | Tempo + Grafana, Jaeger | Datadog APM, Honeycomb |
+| Errors / Exceptions | Sentry (self-hosted) | Sentry SaaS |
+| Profiling | Pyroscope (Grafana) | Datadog Profiler |
+| Alerts | Alertmanager (Prometheus) | PagerDuty, OpsGenie |
+
+## Tooling
+
+Lint log hygiene (print/console.log, eager f-strings, PII in log calls):
+`python3 scripts/lint_logging.py <source files>`
+
+## See also
+
+- [references/instrumentation.md](references/instrumentation.md) — logs/metrics/traces, RED+USE, SLO, alert hygiene.
+- [assets/observability-checklist.md](assets/observability-checklist.md) — the ship gate.
+- [performance](../performance/SKILL.md) — pairs naturally with metrics + traces.
+- [security-web](../security-web/SKILL.md) §A09 (Logging & Alerting Failures) — security-side audit log requirements.
+- [incident-response](../incident-response/SKILL.md) — when alerts fire, what happens next.
+- [clean-code](../clean-code/SKILL.md) §1b — no PII in logs.

core/skills/observability/assets/observability-checklist.md

@@ -0,0 +1,27 @@
+<!-- domain:BACKEND | layer:asset | ssot:false | updated:2026-06-04 -->
+# Observability Checklist
+
+Run before shipping a service to production.
+
+## Logs
+- [ ] Structured (JSON) logger, not `print`/`console.log`.
+- [ ] Fields passed as data, not interpolated into the message.
+- [ ] `trace_id`/correlation id on every log (logs join to traces).
+- [ ] No PII/secrets in log values (use ids; redact).
+- [ ] Levels used correctly (error = actionable, info = events, debug = dev-only).
+- [ ] `python3 scripts/lint_logging.py <files>` → `clean`.
+
+## Metrics
+- [ ] RED metrics for request paths (rate, errors, duration histograms).
+- [ ] USE metrics for resources (utilization, saturation, errors).
+- [ ] Latency as histograms (p50/p95/p99), not averages.
+- [ ] Low label cardinality (no per-user/per-id labels).
+
+## Traces
+- [ ] OpenTelemetry instrumentation; trace id propagated across service calls.
+- [ ] External calls (DB, HTTP) wrapped in spans.
+
+## Alerting
+- [ ] SLO/SLI defined; alerts fire on burn rate / symptoms, not every blip.
+- [ ] Every alert is actionable + links to a runbook (incident-response).
+- [ ] Deploy markers emitted to metrics (correlate regressions to releases).

core/skills/observability/references/instrumentation.md

@@ -0,0 +1,57 @@
+<!-- domain:BACKEND | layer:reference | ssot:true | updated:2026-06-04 -->
+# Instrumentation — Logs, Metrics, Traces
+
+> P: Instrument a service so a production problem is diagnosable from telemetry, not guesswork.
+> R: Adding logging/metrics/tracing to a service or debugging a blind spot.
+> S: Alert routing to a runbook — that's [incident-response](../../incident-response/SKILL.md).
+> N: [SKILL.md](../SKILL.md), [observability-checklist.md](../assets/observability-checklist.md)
+
+> Nav: [Skill](../SKILL.md)
+
+## The three signals (use all, for different questions)
+
+| Signal | Answers | Shape |
+|---|---|---|
+| logs | "what exactly happened in this request?" | structured events (JSON), correlated by trace id |
+| metrics | "how is the system behaving over time?" | numeric time series (counters, gauges, histograms) |
+| traces | "where did the latency / error come from across services?" | spans with parent/child, a trace id end to end |
+
+OpenTelemetry is the vendor-neutral standard for all three — instrument once,
+export to Prometheus/Grafana/Datadog/etc. Don't reinvent per-vendor SDKs.
+
+## Structured logs, never print
+
+```python
+# Wrong — unsearchable, unparseable, eager-formatted
+print(f"user {user_id} did {action}")
+
+# Correct — structured, level-gated, correlatable
+logger.info("user_action", extra={"user_id": user_id, "action": action, "trace_id": trace_id})
+```
+
+Pass fields as data, not interpolated into the message — so you can filter/aggregate
+on `user_id` later. Include the `trace_id` on every log so logs join to traces.
+`lint_logging.py` flags `print`/`console.log`, f-strings in log calls (eager
+format), and PII-shaped values.
+
+## Metrics that matter — RED + USE
+
+- **RED** (request-driven services): **R**ate, **E**rrors, **D**uration (p50/p95/p99).
+- **USE** (resources): **U**tilization, **S**aturation, **E**rrors.
+
+Histograms (not averages) for latency — an average hides the p99 that users feel.
+Keep label cardinality low (no user-id labels — that explodes the series count).
+
+## SLO/SLI — define "good enough" before alerting
+
+An SLI is a measured ratio (successful requests / total); an SLO is the target
+(99.9% over 30 days); the error budget is what's left. Alert on **burn rate**
+(spending the budget too fast), not on every blip — page-worthy means
+user-impacting, not "CPU touched 80% once".
+
+## Alert hygiene
+
+Every alert links to a runbook ([incident-response](../../incident-response/SKILL.md)),
+is actionable (a human can do something), and is symptom-based (alert on "checkout
+error rate up", not "pod restarted"). A noisy channel trains people to ignore it —
+delete or tune alerts no one acts on.

core/skills/observability/scripts/lint_logging.py

@@ -0,0 +1,77 @@
+"""Lint source for logging-hygiene problems (print, eager format, PII, no level).
+
+PURPOSE:      Catch the logging mistakes that make production unobservable or
+              leak data — one findings list instead of reading every log call.
+INPUT:        one or more source paths (.py/.ts/.js/.go). [--json]
+OUTPUT:       Findings (file:line) on stderr; "clean"/"N finding(s)" on stdout.
+              Exit 0 clean, 1 if findings, 2 usage.
+DEPENDENCIES: stdlib only. Static regex scan; heuristic.
+NOTES:        Pure scan_text() is unit-testable. PII/secret policy is owned by
+              security-web + the memory rule; this flags the log-call shape.
+              Spec: docs/playbooks/skill-authoring.md; craft: ../SKILL.md.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+
+PII = r"(password|passwd|secret|token|api[_-]?key|ssn|credit[_-]?card|email|authorization)"
+
+LINE_RULES: list[tuple[re.Pattern, str]] = [
+    (re.compile(r"^\s*print\s*\(", re.IGNORECASE), "print() — use a structured logger, not stdout"),
+    (
+        re.compile(r"console\.(log|error|warn)\s*\("),
+        "console.log — use a structured logger with levels + context",
+    ),
+    (
+        re.compile(rf"log(ger)?\.\w+\([^)]*{PII}", re.IGNORECASE),
+        "PII/secret-shaped value in a log call — redact or use an id",
+    ),
+    (
+        re.compile(r"log(ger)?\.\w+\(\s*f['\"]"),
+        "f-string in a log call — eager-formats even when the level is disabled; pass args separately",
+    ),
+]
+
+
+def scan_text(text: str, *, filename: str = "?") -> list[str]:
+    findings: list[str] = []
+    for n, line in enumerate(text.splitlines(), 1):
+        stripped = line.lstrip()
+        if stripped.startswith(("#", "//", "*", "/*")):
+            continue
+        for pattern, msg in LINE_RULES:
+            if pattern.search(line):
+                findings.append(f"{filename}:{n}: {msg}")
+    return findings
+
+
+def main(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser(description=__doc__.split("\n")[0])
+    parser.add_argument("files", nargs="+")
+    parser.add_argument("--json", action="store_true", dest="as_json")
+    args = parser.parse_args(argv)
+
+    all_findings: list[str] = []
+    for path in args.files:
+        try:
+            all_findings.extend(scan_text(Path(path).read_text(encoding="utf-8"), filename=path))
+        except FileNotFoundError:
+            print(f"error: {path} not found", file=sys.stderr)
+            return 2
+
+    for f in all_findings:
+        print(f"  ✗ {f}", file=sys.stderr)
+    if args.as_json:
+        print(json.dumps({"findings": all_findings, "count": len(all_findings)}))
+    else:
+        print("clean" if not all_findings else f"{len(all_findings)} finding(s)")
+    return 1 if all_findings else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

core/skills/payments/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: payments
+description: Integrate payments and billing correctly — card charges, payment intents, webhooks, idempotent money movement, subscriptions/invoicing, refunds/chargebacks, multi-currency, and reconciliation against a ledger. Use when wiring Stripe/Adyen/Braintree/PayPal, handling a payment webhook, designing a subscription or usage-based billing model, making a charge safe to retry, preventing double-charges, or reconciling provider events against an internal money ledger. Boundary vs api-design and security-web — api-design owns the protocol-neutral HTTP contract shape (idempotency-key mechanics, RFC 9457 errors, pagination) and security-web owns generic OWASP server hardening (authn/z, injection, secrets); this skill owns the money-correctness domain on top of both — never trusting client-sent amounts, PCI scope minimization via tokenization, the webhook-as-source-of-truth state machine, and double-entry reconciliation. Defers durable ledger schema design to db-design.
+tier: cross-cutting
+domain: [backend, security]
+last_reviewed: "2026-06-14"
+---
+
+# Payments & Billing — Moving Money Without Losing It
+
+A practical guide to integrating a payment provider such that money is never double-charged, never silently lost, and always reconcilable. Stack-agnostic; recipes target Stripe as the reference provider, with Adyen / Braintree / PayPal noted where the model differs. The governing mindset: **a payment bug is a money bug, and money bugs are visible to finance, regulators, and angry customers.**
+
+## When to Use This Skill
+
+- Wiring a first charge / checkout — payment intents, hosted fields, confirmation flow.
+- Handling a provider webhook (`payment_intent.succeeded`, `charge.refunded`, `invoice.paid`).
+- Designing a subscription, metered/usage billing, free trial, proration, or dunning flow.
+- Making money movement idempotent — a retried request must never charge twice.
+- Issuing refunds, handling disputes/chargebacks, partial captures.
+- Reconciling provider state against an internal ledger; closing the books.
+
+Skip when: the work is a generic non-money API endpoint (api-design) or generic auth/injection hardening (security-web) with no money movement — those skills own that. This skill is specifically the financial-correctness layer.
+
+## The Five Money-Correctness Invariants
+
+These override convenience every time:
+
+1. **Never trust a client-sent amount.** The price is computed server-side from the cart/plan, never read from the request body. A client that POSTs `{"amount": 1}` for a $1000 order must be charged $1000. This is the single most exploited payments bug.
+2. **Every money mutation is idempotent.** A charge/capture/refund call carries an idempotency key derived from the business intent (e.g. `order_id`), so a network retry returns the *original* result instead of moving money again. (api-design owns the generic idempotency-key mechanics; this skill mandates it for money.)
+3. **The provider webhook is the source of truth for state, not the API response.** The synchronous create-charge response can be lost (timeout) while the charge still succeeds. Treat the charge as `pending` until the webhook confirms; reconcile on the webhook.
+4. **Money is integer minor units, never a float.** Store `amount_cents` (or the currency's minor unit) as an integer. `0.1 + 0.2 != 0.3` in floating point — that rounding error is a regulatory finding.
+5. **Every movement is double-entry on an append-only ledger.** A charge debits one account and credits another; the ledger is immutable (corrections are reversing entries, never edits). This is what makes reconciliation and audit possible. (db-design owns the ledger *schema*; this skill owns the *discipline*.)
+
+## PCI Scope — Stay Out of It by Design
+
+Touching raw card numbers (PAN) drags the whole system into PCI-DSS scope (audits, controls, liability). Minimize scope to near-zero:
+
+- **Tokenize at the edge.** The card number goes from the browser/app *directly* to the provider (Stripe Elements, hosted fields, client-side SDK) and comes back as a token. The server stores and uses the token, never the PAN.
+- **Never log, store, or transit a raw card number, CVV, or full track data** — not in app logs, not in a debug dump, not "temporarily". CVV may never be stored at all, even encrypted.
+- This makes the integration eligible for the lightest PCI self-assessment (SAQ A) instead of the heavyweight ones. Hosted fields are not just convenience; they are the compliance strategy.
+
+## The Webhook State Machine
+
+Charges, refunds, and subscription lifecycle events arrive asynchronously as webhooks. Handle them defensively:
+
+- **Verify the signature** on every webhook before acting — an unsigned/forged webhook is an attacker telling the system a payment succeeded. Use the provider's signing secret; reject on mismatch.
+- **Idempotent webhook handlers** — providers retry delivery and send duplicates. Dedup on the event id; processing the same `payment_intent.succeeded` twice must not fulfill the order twice.
+- **Webhooks arrive out of order and can race the API response.** Design the handler to be order-independent: reconcile to the *current* provider state, do not assume `created` arrives before `succeeded`.
+- **Acknowledge fast, work async.** Return 2xx immediately so the provider stops retrying; do slow fulfillment work off the webhook thread (a queue — see messaging-queues), itself idempotent.
+- **A missed webhook must be recoverable.** Poll the provider / run a reconciliation job so a dropped webhook does not strand an order in `pending` forever.
+
+## Subscriptions & Billing Models
+
+- **Let the provider own recurring billing** (Stripe Billing / subscriptions) rather than reimplementing renewal cron, proration math, and dunning — that machinery is a multi-year tar pit.
+- **Proration, trials, plan changes** have subtle edge cases (mid-cycle upgrade, downgrade credit, trial-to-paid). Use the provider's proration; verify with the provider's test clock, do not hand-roll the date math.
+- **Dunning** (retrying failed recurring charges, grace periods, eventual cancellation) is a churn lever — configure the provider's smart retries; surface payment-failure state to the user before access is revoked.
+- **Usage/metered billing**: aggregate usage idempotently (a usage event reported twice must not bill twice — same dedup discipline as everything else).
+
+## Refunds, Disputes, Failures
+
+- **Refunds are also idempotent money movement** — a retried refund must not refund twice. Refund through the provider against the original charge id; record a reversing ledger entry.
+- **Chargebacks/disputes** are provider-initiated reversals with evidence deadlines. Capture the dispute webhook, freeze related fulfillment, and surface the deadline to ops — a missed deadline is an automatic loss.
+- **Distinguish hard vs soft declines.** Soft decline (insufficient funds, temporary) → safe to retry with backoff. Hard decline (stolen card, do-not-honor) → do not retry; retrying a hard decline can trigger fraud flags.
+
+## Anti-Patterns (reject in review, fix on sight)
+
+- **Trusting a client-supplied price/amount** — server computes the amount, always.
+- **No idempotency key on a charge/refund** — a retry double-charges a customer.
+- **Treating the synchronous API response as final state** — the webhook is the source of truth.
+- **Storing money as a float** — rounding errors become accounting discrepancies.
+- **Logging or storing the raw PAN/CVV** — instant PCI scope blowup and breach liability.
+- **Unverified webhook signatures** — an attacker can forge "payment succeeded".
+- **Non-idempotent webhook handler** — duplicate delivery fulfills the order twice.
+- **Editing ledger rows to "fix" a balance** — use reversing entries; the ledger is append-only.
+- **Reimplementing subscription renewal/proration by hand** — use the provider's billing engine.
+- **Retrying hard declines** — wastes attempts and trips fraud detection.
+
+## Tools per surface (2026 defaults)
+
+| Need | Default | Alternatives |
+|---|---|---|
+| Card payments + tokenization | Stripe (Elements / Payment Intents) | Adyen, Braintree |
+| Subscriptions / invoicing | Stripe Billing | Chargebee, Recurly |
+| PayPal / wallet rails | PayPal, Apple Pay / Google Pay via provider | — |
+| Marketplace / split payments | Stripe Connect | Adyen for Platforms |
+| Internal money ledger | double-entry table in Postgres (db-design) | Ledger DBs (TigerBeetle) |
+| Webhook reliability | provider retries + reconciliation job | queue-backed async fulfillment |
+
+## Pairs With
+
+- **api-design** — owns the protocol-neutral idempotency-key mechanics and RFC 9457 error shape; this skill applies them to money and adds the never-trust-the-amount rule.
+- **security-web** — owns generic OWASP hardening (authn/z, injection, secrets, webhook transport security); this skill adds PCI scope minimization and the payment-specific threat model on top.
+- **db-design** — owns the durable double-entry ledger *schema*; this skill owns the append-only, reconcilable *discipline* that schema must support.
+- **messaging-queues** — async, idempotent webhook fulfillment runs through a queue with at-least-once + dedup, exactly as money movement demands.
+- **observability** — charge success rate, decline rate, webhook lag, and ledger-vs-provider drift are the billing golden signals; alert on reconciliation mismatch.
+
+## See also
+
+- Stripe docs — Payment Intents, idempotent requests, webhook signature verification, Billing.
+- PCI-DSS v4.0 — SAQ A eligibility via tokenization / hosted fields.
+- *Patterns of Enterprise Application Architecture* (Fowler) — Money type, double-entry accounting.
+- Stripe engineering: "Designing robust and predictable APIs with idempotency."