skilldrop-cli 0.16.45 → 0.16.46

package/packs/solution-architect/skills/context-graph/evals/files/15/doc/adr/0008-store-vehicle-telemetry-in-timescaledb.md

@@ -0,0 +1,28 @@
+# 8. Store vehicle telemetry in TimescaleDB
+
+Date: 2023-04-11
+
+## Status
+
+Accepted
+
+Supersedes [3. Store vehicle telemetry in Cassandra](0003-store-vehicle-telemetry-in-cassandra.md)
+
+## Context
+
+The Cassandra cluster from ADR 3 needs specialist operations knowledge
+nobody on the team has, and geo queries over telemetry are now a product
+requirement.
+
+## Decision
+
+Vehicle telemetry moves to TimescaleDB (a PostgreSQL extension) in a
+separate database, `haulmark_telemetry`, written by `services/telemetry/`,
+using a hypertable partitioned by time with PostGIS for geo queries.
+Raw points are kept for 30 days and downsampled after that, as set out in
+[10. Telemetry retention and downsampling](0010-telemetry-retention-and-downsampling.md).
+
+## Consequences
+
+One database technology to operate instead of two. Write throughput must be
+watched as the fleet grows past 2,000 trucks.

package/packs/solution-architect/skills/context-graph/evals/files/15/doc/adr/0009-stateless-sessions-with-signed-cookies.md

@@ -0,0 +1,24 @@
+# 9. Stateless sessions with signed cookies
+
+Date: 2024-05-07
+
+## Status
+
+Accepted
+
+Supersedes [4. Use Redis for session storage](0004-use-redis-for-session-storage.md)
+
+## Context
+
+Redis was the only stateful dependency of `services/api/` and caused two
+outages in Q1 2024 when its primary failed over.
+
+## Decision
+
+Sessions are stateless: a signed, encrypted cookie carries the dispatcher's
+user ID, role and an 8-hour expiry. Redis is removed from `services/api/`.
+
+## Consequences
+
+No session store to operate. Revoking a single session before expiry needs a
+short deny-list, kept in `haulmark_core`.

package/packs/solution-architect/skills/context-graph/evals/files/15/services/api/session.py

@@ -0,0 +1,17 @@
+"""Dispatcher sessions for services/api (ADR 9): signed, encrypted cookies, no server store."""
+import os
+import time
+
+from itsdangerous import URLSafeTimedSerializer
+
+SECRET = os.environ.get("SESSION_SECRET", "placeholder-not-a-real-secret")
+MAX_AGE_SECONDS = 8 * 3600
+_serializer = URLSafeTimedSerializer(SECRET, salt="haulmark-session")
+
+
+def issue(user_id: str, role: str) -> str:
+    return _serializer.dumps({"uid": user_id, "role": role, "iat": int(time.time())})
+
+
+def read(cookie: str):
+    return _serializer.loads(cookie, max_age=MAX_AGE_SECONDS)

package/packs/solution-architect/skills/context-graph/evals/files/15/services/shipments/db.py

@@ -0,0 +1,30 @@
+"""Shipment persistence for services/shipments (ADR 2)."""
+import os
+
+import psycopg
+
+DSN = os.environ.get("SHIPMENTS_DSN", "postgresql://haulmark:placeholder@localhost:5432/haulmark_core")
+
+
+def connect():
+    return psycopg.connect(DSN)
+
+
+def get_shipment(conn, shipment_id: str):
+    with conn.cursor() as cur:
+        cur.execute(
+            "SELECT id, customer_id, status, custom_fields FROM shipments WHERE id = %s",
+            (shipment_id,),
+        )
+        return cur.fetchone()
+
+
+def mark_stop_delivered(conn, shipment_id: str, stop_id: str):
+    with conn.transaction():
+        with conn.cursor() as cur:
+            cur.execute("UPDATE stops SET status = 'delivered' WHERE id = %s", (stop_id,))
+            cur.execute(
+                "UPDATE shipments SET status = 'delivered' WHERE id = %s "
+                "AND NOT EXISTS (SELECT 1 FROM stops WHERE shipment_id = %s AND status <> 'delivered')",
+                (shipment_id, shipment_id),
+            )

package/packs/solution-architect/skills/context-graph/evals/files/15/services/shipments/migrations.sql

@@ -0,0 +1,3 @@
+-- 2022-09-30: per-customer custom fields as JSONB instead of new columns
+ALTER TABLE shipments ADD COLUMN custom_fields JSONB NOT NULL DEFAULT '{}'::jsonb;
+CREATE INDEX shipments_custom_fields_gin ON shipments USING GIN (custom_fields);

package/packs/solution-architect/skills/context-graph/evals/files/15/services/telemetry/store.py

@@ -0,0 +1,23 @@
+"""Telemetry writer for services/telemetry (ADR 8)."""
+import os
+
+import psycopg
+
+DSN = os.environ.get("TELEMETRY_DSN", "postgresql://haulmark:placeholder@localhost:5432/haulmark_telemetry")
+
+SCHEMA = """
+CREATE TABLE IF NOT EXISTS positions (
+    vehicle_id TEXT NOT NULL,
+    recorded_at TIMESTAMPTZ NOT NULL,
+    location GEOGRAPHY(POINT) NOT NULL
+);
+SELECT create_hypertable('positions', 'recorded_at', if_not_exists => TRUE);
+"""
+
+
+def write_position(conn, vehicle_id: str, recorded_at, lon: float, lat: float):
+    with conn.cursor() as cur:
+        cur.execute(
+            "INSERT INTO positions VALUES (%s, %s, ST_MakePoint(%s, %s)::geography)",
+            (vehicle_id, recorded_at, lon, lat),
+        )

package/packs/solution-architect/skills/context-graph/evals/files/15/web/dashboard/App.jsx

@@ -0,0 +1,3 @@
+export default function App() {
+  return <h1>Haulmark dispatch</h1>;
+}

package/packs/solution-architect/skills/context-graph/evals/files/2/docs/adr/0001-record-architecture-decisions.md

@@ -0,0 +1,11 @@
+# 1. Record architecture decisions
+
+Date: 2023-04-03
+
+## Status
+
+Accepted
+
+## Decision
+
+We record architecture decisions as ADRs in `docs/adr/`, one numbered file each.

package/packs/solution-architect/skills/context-graph/evals/files/2/docs/adr/0002-rabbitmq-for-background-jobs.md

@@ -0,0 +1,15 @@
+---
+status: accepted
+date: 2023-05-22
+---
+
+# RabbitMQ for background jobs
+
+## Context and Problem Statement
+
+Checkout sends receipts and stock updates inline, which slows the request.
+
+## Decision Outcome
+
+Chosen option: "RabbitMQ", because the hosting provider offers it managed. Jobs are consumed by
+`services/worker/`, and `services/checkout/` only publishes.

package/packs/solution-architect/skills/context-graph/evals/files/2/docs/adr/0003-thumbnail-service.md

@@ -0,0 +1,20 @@
+# 3. A separate thumbnail service
+
+Date: 2023-09-11
+
+## Status
+
+Accepted
+
+## Context
+
+Resizing product images inside the API blocks request threads.
+
+## Decision
+
+Image resizing runs in its own service, `services/thumbnailer/`, which consumes `resize` jobs
+from the queue described in ADR-0002.
+
+## Consequences
+
+The API never touches image bytes after upload.

package/packs/solution-architect/skills/context-graph/evals/files/2/docs/adr/0004-money-as-integer-minor-units.md

@@ -0,0 +1,17 @@
+---
+status: accepted
+date: 2024-01-15
+deciders: payments guild
+---
+
+# Money as integer minor units
+
+## Context and Problem Statement
+
+A float rounding error put a basket total out by 1p, and the refund did not match the charge.
+
+## Decision Outcome
+
+Chosen option: "integer minor units". Every amount in `libs/money/` is stored and computed as an
+integer count of minor units (pence, cents). "No floats and no Decimal anywhere in money code:
+one representation, exact by construction."

package/packs/solution-architect/skills/context-graph/evals/files/2/docs/adr/0005-worker-retries.md

@@ -0,0 +1,12 @@
+# 5. Retry failed background jobs
+
+Date: 2024-03-04
+
+## Status
+
+Accepted
+
+## Decision
+
+A failed job in `services/worker/` is retried three times, then moved to a dead-letter queue.
+Retry timing follows the backoff policy in ADR-0011.

package/packs/solution-architect/skills/context-graph/evals/files/2/docs/adr/0006-fx-amounts-with-four-decimals.md

@@ -0,0 +1,18 @@
+---
+status: accepted
+date: 2025-02-27
+deciders: marketplace team
+---
+
+# FX amounts with four decimal places
+
+## Context and Problem Statement
+
+Marketplace sellers are paid in their own currency. Converting a price in whole minor units and
+then converting back loses sub-penny amounts, and seller statements drift.
+
+## Decision Outcome
+
+This builds on ADR-0004. Amounts in `libs/money/` are held as `Decimal` with four decimal places,
+"so that a conversion and its reverse return the original amount", and are rounded to minor units
+only when charged or paid out.

package/packs/solution-architect/skills/context-graph/evals/files/2/docs/adr/0007-feature-flags.md

@@ -0,0 +1,16 @@
+# 7. Feature flags in config, not a flag service
+
+Date: 2025-06-09
+
+## Context
+
+We want to ship checkout changes dark and turn them on per region.
+
+## Decision
+
+Flags live in `services/checkout/flags.py` as a plain dictionary read at start-up. No external flag
+service for now.
+
+## Consequences
+
+Turning a flag on needs a deploy.

package/packs/solution-architect/skills/context-graph/evals/files/2/docs/adr/0008-retire-legacy-search.md

@@ -0,0 +1,14 @@
+---
+status: deprecated
+date: 2023-06-30
+---
+
+# Legacy search on the database
+
+## Context and Problem Statement
+
+Product search runs as SQL `LIKE` queries from `services/legacy-search/`.
+
+## Decision Outcome
+
+Deprecated in 2024 when search moved to the hosted search provider. Kept for history.

package/packs/solution-architect/skills/context-graph/evals/files/2/libs/money/amount.py

@@ -0,0 +1,9 @@
+from decimal import Decimal
+
+PLACES = Decimal("0.0001")
+
+
+class Amount:
+    def __init__(self, value, currency):
+        self.value = Decimal(value).quantize(PLACES)
+        self.currency = currency

package/packs/solution-architect/skills/context-graph/evals/files/2/services/checkout/flags.py

@@ -0,0 +1 @@
+FLAGS = {"new_basket": False}

package/packs/solution-architect/skills/context-graph/evals/files/2/services/media/resize.py

@@ -0,0 +1,5 @@
+"""Resize product images on upload. Consumes 'resize' jobs."""
+
+
+def handle_resize(job):
+    raise NotImplementedError

package/packs/solution-architect/skills/context-graph/evals/files/3/docs/rfcs/0001-how-we-write-rfcs.md

@@ -0,0 +1,9 @@
+---
+id: RFC-0001
+title: How we write RFCs
+status: accepted
+date: 2024-01-08
+---
+
+Design decisions are written as RFCs in `docs/rfcs/`. An RFC starts as Proposed and becomes
+Accepted or Rejected after review. A replaced RFC is marked "Superseded by" its successor.

package/packs/solution-architect/skills/context-graph/evals/files/3/docs/rfcs/0002-payments-service-boundary.md

@@ -0,0 +1,16 @@
+---
+id: RFC-0002
+title: Payments service boundary
+status: accepted
+date: 2024-06-10
+authors: payments team
+---
+
+## Decision
+
+Everything under `services/payments/` is owned by the payments team. Changes there need a review
+from a payments engineer, and no other service imports from it directly; they call its API.
+
+## Why
+
+"Card data and payment state stay behind one boundary, so the audit scope stays one service wide."

package/packs/solution-architect/skills/context-graph/evals/files/3/docs/rfcs/0003-webhook-retries-fixed-interval.md

@@ -0,0 +1,19 @@
+# RFC-0003: Fixed-interval webhook retries
+
+Date: 2024-08-01
+
+## Status
+
+Superseded by [RFC-0006](0006-webhook-retry-backoff.md)
+
+## Context
+
+Merchants miss payment events when their endpoint is briefly down.
+
+## Decision
+
+`services/payments/webhooks/retry.py` retries a failed webhook every 30 seconds, up to 100 times.
+
+## Consequences
+
+Simple to reason about. A merchant endpoint that is down gets a request every 30 seconds.

package/packs/solution-architect/skills/context-graph/evals/files/3/docs/rfcs/0004-webhook-idempotency-keys.md

@@ -0,0 +1,16 @@
+---
+id: RFC-0004
+title: Idempotency keys on every webhook
+status: accepted
+date: 2024-11-19
+---
+
+## Decision
+
+Every webhook sent from `services/payments/webhooks/` carries an `Idempotency-Key` header. The key
+is generated once per event and "every retry of that event resends the same key, so a merchant who
+receives it twice can drop the duplicate".
+
+## Consequences
+
+Merchants are told in the integration guide to deduplicate on the key.

package/packs/solution-architect/skills/context-graph/evals/files/3/docs/rfcs/0005-notification-retries.md

@@ -0,0 +1,16 @@
+# RFC-0005: Retrying customer notifications
+
+Date: 2025-01-27
+
+## Status
+
+Accepted
+
+## Decision
+
+Email and SMS sends that fail are retried by `services/notifications/retry.py` every 5 minutes for
+up to 24 hours, then dropped and logged.
+
+## Consequences
+
+A customer may get a receipt email up to a day late.

package/packs/solution-architect/skills/context-graph/evals/files/3/docs/rfcs/0006-webhook-retry-backoff.md

@@ -0,0 +1,26 @@
+---
+id: RFC-0006
+title: Exponential backoff for webhook retries
+status: accepted
+date: 2025-04-22
+supersedes: RFC-0003
+authors: payments team
+---
+
+## Context and Problem Statement
+
+During the 2025-03-06 incident a large merchant's endpoint was down for an hour. Fixed 30-second
+retries from every queued event "hammered their endpoint as it came back and knocked it over
+again".
+
+## Decision Outcome
+
+`services/payments/webhooks/retry.py` retries with exponential backoff: the first retry after 2
+seconds, doubling each time, capped at 10 minutes between attempts, and at most 8 attempts in all.
+A 4xx response is not retried, except 429. After the last attempt the event is marked failed and
+the merchant can replay it from the dashboard.
+
+### Consequences
+
+* Good, because a recovering endpoint gets a trickle, not a flood.
+* Bad, because an event can now be given up on within about four minutes.

package/packs/solution-architect/skills/context-graph/evals/files/3/docs/rfcs/0007-webhooks-on-the-job-queue.md

@@ -0,0 +1,12 @@
+---
+id: RFC-0007
+title: Send webhooks from the job queue
+status: proposed
+date: 2025-09-15
+---
+
+## Proposal
+
+Move delivery out of `services/payments/webhooks/` and onto the shared job queue, so retries
+survive a deploy. Open questions: who owns the queue, and whether payment events may leave the
+payments boundary in RFC-0002.

package/packs/solution-architect/skills/context-graph/evals/files/3/services/notifications/retry.py

@@ -0,0 +1,4 @@
+"""Retry failed email and SMS sends (RFC-0005)."""
+
+INTERVAL_S = 300
+GIVE_UP_AFTER_S = 24 * 60 * 60

package/packs/solution-architect/skills/context-graph/evals/files/3/services/payments/webhooks/retry.py

@@ -0,0 +1,15 @@
+"""Webhook retry policy (RFC-0006)."""
+
+FIRST_DELAY_S = 2
+MAX_DELAY_S = 600
+MAX_ATTEMPTS = 8
+
+
+def should_retry(status_code, attempt):
+    if attempt >= MAX_ATTEMPTS:
+        return False
+    return status_code == 429 or status_code >= 500
+
+
+def delay_for(attempt):
+    return min(FIRST_DELAY_S * 2 ** attempt, MAX_DELAY_S)

package/packs/solution-architect/skills/context-graph/evals/files/4/docs/adr/0001-record-architecture-decisions.md

@@ -0,0 +1,19 @@
+# ADR-0001: Record architecture decisions
+
+- Status: Accepted
+- Date: 2023-01-09
+- Deciders: Priya Okafor, Tomasz Lind
+
+## Context
+
+Ledgerline is growing past the two people who wrote it. Decisions live in Slack threads.
+
+## Decision
+
+We will record significant architecture decisions as numbered Markdown files in `docs/adr/`.
+A decision that replaces an earlier one says so in a `Supersedes:` line, and the earlier
+record's status is changed to `Superseded by ADR-NNNN`.
+
+## Consequences
+
+Every new ADR is reviewed in the same PR as the code it governs.

package/packs/solution-architect/skills/context-graph/evals/files/4/docs/adr/0002-postgres-as-system-of-record.md

@@ -0,0 +1,18 @@
+# ADR-0002: Postgres is the system of record
+
+- Status: Accepted
+- Date: 2023-01-16
+- Deciders: Priya Okafor
+
+## Context
+
+Invoices, line items and payment allocations need transactional integrity.
+
+## Decision
+
+All persistent state lives in a single Postgres 15 database. Access goes through
+`src/ledgerline/db/`.
+
+## Consequences
+
+No second datastore is introduced without a new ADR.

package/packs/solution-architect/skills/context-graph/evals/files/4/docs/adr/0004-redis-locks-for-scheduler.md

@@ -0,0 +1,19 @@
+# ADR-0004: Redis locks for the nightly invoice run
+
+- Status: Accepted
+- Date: 2023-05-02
+- Deciders: Tomasz Lind
+
+## Context
+
+We run three worker replicas. On 2023-04-27 two replicas both started the nightly invoice
+run and 41 customers were billed twice.
+
+## Decision
+
+The nightly run takes a Redis `SET NX PX` lock (key `ledgerline:invoice-run`, 15 minute TTL,
+renewed every 60 s) before it starts. Implemented in `src/ledgerline/scheduler/redis_lock.py`.
+
+## Consequences
+
+Adds Redis to the stack. This is an exception to ADR-0002, accepted for speed.

package/packs/solution-architect/skills/context-graph/evals/files/4/docs/adr/0007-remove-redis.md

@@ -0,0 +1,27 @@
+# ADR-0007: Remove Redis; use Postgres advisory locks for the invoice run
+
+- Status: Accepted
+- Date: 2024-02-20
+- Deciders: Priya Okafor, Tomasz Lind, Wen Haddad
+- Supersedes: ADR-0004
+- Relates to: ADR-0002
+
+## Context
+
+Redis is used for exactly one thing: the invoice-run lock from ADR-0004. Running it costs a
+managed instance and an on-call runbook. In January 2024 a Redis failover dropped the lock
+mid-run and a second replica started; the idempotency check on `invoice_runs` caught it, but
+only just.
+
+## Decision
+
+Remove Redis. The nightly run takes a session-level Postgres advisory lock with
+`pg_try_advisory_lock(727001)` on a dedicated connection and holds it for the whole run.
+Implemented in `src/ledgerline/scheduler/lock.py`.
+
+## Consequences
+
+- Back to one datastore, as ADR-0002 intended.
+- Advisory locks are session-scoped: the lock connection must NOT go through PgBouncer in
+  transaction-pooling mode, or the lock is released as soon as the transaction ends.
+- If the lock-holding process dies, Postgres releases the lock when the session closes.

package/packs/solution-architect/skills/context-graph/evals/files/4/docs/adr/0009-money-as-integer-minor-units.md

@@ -0,0 +1,19 @@
+# ADR-0009: Store money as integer minor units
+
+- Status: Accepted
+- Date: 2024-06-03
+- Deciders: Wen Haddad
+
+## Context
+
+Float rounding produced one-cent mismatches between invoice totals and line-item sums.
+
+## Decision
+
+Amounts are stored and computed as integers in the currency's minor unit (cents for USD/EUR).
+Rounding rules for currencies with three minor digits follow ADR-0005.
+Implemented in `src/ledgerline/money.py`.
+
+## Consequences
+
+All API payloads carry `amount_minor` plus `currency`.

package/packs/solution-architect/skills/context-graph/evals/files/4/docs/onboarding.md

@@ -0,0 +1,12 @@
+# Welcome to Ledgerline
+
+Ledgerline generates and sends customer invoices.
+
+## Architecture in one page
+
+- Postgres holds everything (ADR-0002).
+- The nightly invoice run is scheduled by `src/ledgerline/scheduler/runner.py`. Only one
+  worker may run it at a time, so it takes a Redis lock first (see ADR-0004).
+- Money is integer cents (ADR-0009).
+
+Last reviewed: 2023-09-14

package/packs/solution-architect/skills/context-graph/evals/files/4/src/ledgerline/db/__init__.py

@@ -0,0 +1,22 @@
+"""Postgres access (ADR-0002)."""
+
+import os
+from contextlib import contextmanager
+
+import psycopg
+
+# DATABASE_URL goes through PgBouncer (transaction pooling); DATABASE_DIRECT_URL does not.
+POOLED_URL = os.environ.get("DATABASE_URL", "postgresql://app:CHANGE_ME@pgbouncer:6432/ledgerline")
+DIRECT_URL = os.environ.get("DATABASE_DIRECT_URL", "postgresql://app:CHANGE_ME@db:5432/ledgerline")
+
+
+@contextmanager
+def pooled_connection():
+    with psycopg.connect(POOLED_URL) as conn:
+        yield conn
+
+
+@contextmanager
+def direct_connection():
+    with psycopg.connect(DIRECT_URL, autocommit=True) as conn:
+        yield conn

package/packs/solution-architect/skills/context-graph/evals/files/4/src/ledgerline/invoicing.py

@@ -0,0 +1,9 @@
+"""Invoice generation."""
+
+
+def run_nightly():
+    """Generate invoices for every customer whose billing date is today.
+
+    Guarded by an idempotency row in `invoice_runs` keyed on the run date.
+    """
+    raise NotImplementedError("fixture")

package/packs/solution-architect/skills/context-graph/evals/files/4/src/ledgerline/money.py

@@ -0,0 +1,10 @@
+"""Money as integer minor units (ADR-0009)."""
+
+MINOR_DIGITS = {"USD": 2, "EUR": 2, "JPY": 0}
+
+
+def to_minor(amount_str: str, currency: str) -> int:
+    digits = MINOR_DIGITS[currency]
+    whole, _, frac = amount_str.partition(".")
+    frac = (frac + "0" * digits)[:digits]
+    return int(whole) * 10**digits + (int(frac) if digits else 0)

package/packs/solution-architect/skills/context-graph/evals/files/4/src/ledgerline/scheduler/lock.py

@@ -0,0 +1,23 @@
+"""Single-runner guard for the nightly invoice run (ADR-0007)."""
+
+from contextlib import contextmanager
+
+INVOICE_RUN_LOCK_KEY = 727001
+
+
+@contextmanager
+def invoice_run_lock(conn):
+    """Hold a session-level advisory lock for the duration of the run.
+
+    `conn` must be a dedicated, direct connection (not via PgBouncer transaction pooling).
+    Yields True if this process holds the lock, False if another worker already does.
+    """
+    with conn.cursor() as cur:
+        cur.execute("SELECT pg_try_advisory_lock(%s)", (INVOICE_RUN_LOCK_KEY,))
+        acquired = cur.fetchone()[0]
+    try:
+        yield acquired
+    finally:
+        if acquired:
+            with conn.cursor() as cur:
+                cur.execute("SELECT pg_advisory_unlock(%s)", (INVOICE_RUN_LOCK_KEY,))