skilldrop-cli 0.16.44 → 0.16.46

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,))

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

@@ -0,0 +1,17 @@
+"""Nightly invoice run entry point."""
+
+from ledgerline.db import direct_connection
+from ledgerline.scheduler.lock import invoice_run_lock
+from ledgerline.invoicing import run_nightly
+
+
+def main():
+    with direct_connection() as conn, invoice_run_lock(conn) as acquired:
+        if not acquired:
+            print("another worker holds the invoice-run lock; exiting")
+            return
+        run_nightly()
+
+
+if __name__ == "__main__":
+    main()

package/packs/solution-architect/skills/context-graph/evals/files/5/lib/types/index.ts

@@ -0,0 +1,13 @@
+export interface FeedEvent {
+  id: string;
+  kind: string;
+  occurredAt: string;
+  payload: Record<string, unknown>;
+}
+
+export interface Invoice {
+  id: string;
+  customerId: string;
+  amountMinor: number;
+  currency: string;
+}

package/packs/solution-architect/skills/context-graph/evals/files/5/rfcs/0001-service-layout.md

@@ -0,0 +1,20 @@
+---
+id: RFC-0001
+title: Service layout and shared code
+status: accepted
+date: 2024-11-02
+authors: [Dara Mensah]
+governs: [services/, lib/]
+---
+
+# RFC-0001: Service layout and shared code
+
+## Decision
+
+Each service under `services/<name>/` owns its own client, retry and error-handling code.
+The only shared package is `lib/types/` (pure type definitions, no runtime behaviour).
+
+## Why
+
+Ingest and export talk to different partners with different idempotency guarantees. A shared
+runtime library would couple their failure behaviour and force lock-step releases.

package/packs/solution-architect/skills/context-graph/evals/files/5/rfcs/0003-ingest-retry-policy.md

@@ -0,0 +1,26 @@
+---
+id: RFC-0003
+title: Retry policy for the ingest service
+status: accepted
+date: 2025-03-11
+authors: [Oskar Byrne]
+governs: [services/ingest/retry.ts]
+cites: [RFC-0001]
+---
+
+# RFC-0003: Retry policy for the ingest service
+
+## Context
+
+INC-114 (2025-02-27): the partner feed API returned 503 for four minutes. Every ingest worker
+retried on a fixed 1 s interval, the retries stayed synchronised, and the partner rate-limited
+our whole account for two hours after recovery.
+
+## Decision
+
+Ingest retries use exponential backoff with full jitter: base 200 ms, cap 30 s, at most
+6 attempts. Fixed-interval retries are not allowed in ingest.
+
+## Consequences
+
+Worst-case retry window is about 60 s per request. Dashboards alert on attempt 5+.

package/packs/solution-architect/skills/context-graph/evals/files/5/rfcs/0006-shared-retry-library.md

@@ -0,0 +1,24 @@
+---
+id: RFC-0006
+title: Extract a shared lib/retry package
+status: rejected
+date: 2025-06-19
+authors: [Lucía Ferraro]
+cites: [RFC-0001, RFC-0003]
+---
+
+# RFC-0006: Extract a shared lib/retry package
+
+## Proposal
+
+Move `services/ingest/retry.ts` and `services/export/retry.ts` into one `lib/retry/` package
+with a single default policy.
+
+## Outcome: rejected
+
+- Export calls to the partner billing API are NOT idempotent; export only retries on 503
+  responses that carry an `Idempotency-Key` echo. A single default policy would retry
+  unsafe calls.
+- RFC-0001 keeps runtime code per service.
+
+Revisit only if RFC-0001 is superseded.

package/packs/solution-architect/skills/context-graph/evals/files/5/rfcs/0008-outbound-http-client.md

@@ -0,0 +1,22 @@
+---
+id: RFC-0008
+title: One outbound HTTP client
+status: accepted
+date: 2025-09-30
+authors: [Dara Mensah]
+governs: [lib/http/, services/ingest/client.ts, services/export/client.ts]
+amends: [RFC-0001]
+cites: [RFC-0007]
+---
+
+# RFC-0008: One outbound HTTP client
+
+## Decision
+
+All outbound HTTP calls go through `lib/http/client.ts`. It sets timeouts, tracing headers and
+applies retries uniformly (fixed 500 ms, 3 attempts). This amends RFC-0001 to allow `lib/http/`
+as a second shared package. Idempotency keys are handled as described in RFC-0007.
+
+## Rollout
+
+Services migrate their `client.ts` to `lib/http/` during Q4 2025.

package/packs/solution-architect/skills/context-graph/evals/files/5/services/export/client.ts

@@ -0,0 +1,15 @@
+import { retryIfSafe } from "./retry";
+import type { Invoice } from "../../lib/types";
+
+const BILLING_URL = process.env.PARTNER_BILLING_URL ?? "https://billing.partner.example/v1/invoices";
+
+export async function pushInvoice(inv: Invoice, idempotencyKey: string): Promise<Response> {
+  return retryIfSafe(() =>
+    fetch(BILLING_URL, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", "Idempotency-Key": idempotencyKey },
+      body: JSON.stringify(inv),
+      signal: AbortSignal.timeout(15_000),
+    }),
+  );
+}

package/packs/solution-architect/skills/context-graph/evals/files/5/services/export/retry.ts

@@ -0,0 +1,12 @@
+// Export retries are deliberately narrow: the billing API is not idempotent (RFC-0006).
+const DELAY_MS = 1_000;
+const MAX_ATTEMPTS = 3;
+
+export async function retryIfSafe(fn: () => Promise<Response>): Promise<Response> {
+  for (let attempt = 1; ; attempt++) {
+    const res = await fn();
+    const safe = res.status === 503 && res.headers.has("Idempotency-Key");
+    if (!safe || attempt >= MAX_ATTEMPTS) return res;
+    await new Promise((r) => setTimeout(r, DELAY_MS));
+  }
+}

package/packs/solution-architect/skills/context-graph/evals/files/5/services/ingest/client.ts

@@ -0,0 +1,14 @@
+import { withRetry } from "./retry";
+import type { FeedEvent } from "../../lib/types";
+
+const FEED_URL = process.env.PARTNER_FEED_URL ?? "https://feed.partner.example/v2/events";
+
+export async function fetchEvents(cursor: string): Promise<FeedEvent[]> {
+  return withRetry(async () => {
+    const res = await fetch(`${FEED_URL}?cursor=${encodeURIComponent(cursor)}`, {
+      signal: AbortSignal.timeout(10_000),
+    });
+    if (!res.ok) throw new Error(`feed ${res.status}`);
+    return (await res.json()) as FeedEvent[];
+  });
+}