skilldrop-cli 0.16.44 → 0.16.46

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

@@ -0,0 +1,20 @@
+// Ingest retry policy — RFC-0003. Do not change to a fixed interval (see INC-114).
+const BASE_MS = 200;
+const CAP_MS = 30_000;
+const MAX_ATTEMPTS = 6;
+
+export async function withRetry<T>(fn: () => Promise<T>): Promise<T> {
+  let attempt = 0;
+  for (;;) {
+    try {
+      return await fn();
+    } catch (err) {
+      attempt += 1;
+      if (attempt >= MAX_ATTEMPTS) throw err;
+      const ceiling = Math.min(CAP_MS, BASE_MS * 2 ** attempt);
+      await sleep(Math.random() * ceiling); // full jitter
+    }
+  }
+}
+
+const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));

package/packs/solution-architect/skills/context-graph/evals/files/6/README.md

@@ -0,0 +1,4 @@
+# harbourline
+
+Freight billing and invoicing platform. Monorepo: `services/` for deployables, `libs/` for shared code.
+Decision records live in `docs/adr/` (architecture decision records) and `docs/rfcs/` (larger proposals).

package/packs/solution-architect/skills/context-graph/evals/files/6/docs/adr/0001-monorepo-layout.md

@@ -0,0 +1,10 @@
+# ADR-0001: Monorepo layout
+
+- Status: Accepted
+- Date: 2023-02-10
+- Deciders: Platform team (H. Okafor, L. Brandt)
+- Governs: `services/`, `libs/`
+
+## Decision
+One repository. Each deployable service gets its own folder under `services/<name>/`; shared code goes
+under `libs/`. A service folder is never shared by two deployables.

package/packs/solution-architect/skills/context-graph/evals/files/6/docs/adr/0002-billing-on-postgres.md

@@ -0,0 +1,13 @@
+# ADR-0002: Billing data lives in Postgres
+
+- Status: Accepted
+- Date: 2023-05-03
+- Deciders: H. Okafor, M. Szabo
+- Governs: `services/billing/`
+
+## Decision
+The billing service stores charges and the invoice ledger in the shared Postgres cluster
+(table `invoices_ledger`). Writes are transactional updates in place.
+
+## Consequences
+Reporting can join billing tables directly. Corrections overwrite the row and keep no history.

package/packs/solution-architect/skills/context-graph/evals/files/6/docs/adr/0004-ledger-sync-nightly-batch.md

@@ -0,0 +1,9 @@
+# ADR-0004: Ledger sync runs as a nightly batch
+
+- Status: Accepted
+- Date: 2023-09-12
+- Deciders: L. Brandt
+- Governs: `services/ledger-sync/`
+
+## Decision
+Ledger sync to the finance system runs once a night at 02:00 UTC as a batch job, not as a stream.

package/packs/solution-architect/skills/context-graph/evals/files/6/docs/rfcs/RFC-0003-invoice-ids.md

@@ -0,0 +1,9 @@
+# RFC-0003: Invoice identifiers
+
+- Status: Accepted
+- Date: 2023-06-20
+- Author: M. Szabo
+- Governs: `services/invoicing/ids/`
+
+## Proposal
+Invoice IDs are sequential integers issued by a Postgres sequence, formatted `INV-000123`.

package/packs/solution-architect/skills/context-graph/evals/files/6/docs/rfcs/RFC-0007-invoice-ids-ulid.md

@@ -0,0 +1,11 @@
+# RFC-0007: Switch invoice identifiers to ULIDs
+
+- Status: Accepted
+- Date: 2024-03-01
+- Author: R. Achebe
+- Supersedes: RFC-0003
+- Governs: `services/invoicing/ids/`
+
+## Proposal
+Sequential IDs leaked customer invoice volumes and forced a single writer. Invoice IDs become ULIDs,
+generated in-process, formatted `INV-<ulid>`. Existing `INV-000123` IDs stay valid.

package/packs/solution-architect/skills/context-graph/evals/files/6/docs/rfcs/RFC-0009-billing-event-store.md

@@ -0,0 +1,15 @@
+# RFC-0009: Billing writes go to an append-only event store
+
+- Status: Accepted
+- Date: 2024-08-14
+- Author: R. Achebe
+- Governs: `services/billing/`
+- Builds on: RFC-0012 (event schema registry)
+
+## Proposal
+Billing records every charge and correction as an immutable event in the DynamoDB table
+`billing-events`. Current balances are projections of the event stream. This gives auditors a full
+history of corrections.
+
+## Rollout
+Phase 1: write events alongside the existing store. Phase 2: read balances from projections.

package/packs/solution-architect/skills/context-graph/evals/files/6/docs/rfcs/RFC-0010-revenue-service.md

@@ -0,0 +1,13 @@
+# RFC-0010: Merge billing and invoicing into a revenue service
+
+- Status: Proposed
+- Date: 2026-09-30
+- Author: L. Brandt
+- Governs: `services/revenue/` (new)
+
+## Proposal
+Move `services/billing/` and `services/invoicing/` into a single deployable at `services/revenue/`,
+with `billing/` and `invoicing/` as internal modules. Both old folders are deleted after the move.
+
+## Records affected
+- ADR-0002 (billing storage) — path changes to `services/revenue/billing/`.

package/packs/solution-architect/skills/context-graph/evals/files/6/libs/money/ulid.py

@@ -0,0 +1,8 @@
+"""Minimal ULID helper (placeholder implementation for the fixture)."""
+
+import os
+import time
+
+
+def new_ulid():
+    return f"{int(time.time() * 1000):012x}{os.urandom(10).hex()}"

package/packs/solution-architect/skills/context-graph/evals/files/6/services/billing/src/events.py

@@ -0,0 +1,10 @@
+"""Phase 1 of the event store rollout: append every charge as an event."""
+
+EVENTS_TABLE = "billing-events"
+
+
+def append_charge_event(client, invoice_id, amount_minor, at):
+    client.put_item(
+        TableName=EVENTS_TABLE,
+        Item={"invoice_id": invoice_id, "type": "charge", "amount_minor": amount_minor, "at": at},
+    )

package/packs/solution-architect/skills/context-graph/evals/files/6/services/billing/src/store.py

@@ -0,0 +1,10 @@
+"""Billing persistence: in-place updates to the Postgres invoice ledger."""
+
+LEDGER_TABLE = "invoices_ledger"
+
+
+def record_charge(conn, invoice_id, amount_minor):
+    conn.execute(
+        f"UPDATE {LEDGER_TABLE} SET balance_minor = balance_minor + %s WHERE invoice_id = %s",
+        (amount_minor, invoice_id),
+    )

package/packs/solution-architect/skills/context-graph/evals/files/6/services/invoicing/ids/generator.py

@@ -0,0 +1,7 @@
+"""Invoice ID generation."""
+
+from libs.money.ulid import new_ulid
+
+
+def new_invoice_id():
+    return f"INV-{new_ulid()}"

package/packs/solution-architect/skills/context-graph/evals/files/6/services/ledger/README.md

@@ -0,0 +1,4 @@
+# ledger
+
+Formerly `services/ledger-sync/` (renamed in 2025 when it gained the reconciliation report).
+Still runs the nightly sync to the finance system at 02:00 UTC.

package/packs/solution-architect/skills/context-graph/evals/files/6/services/ledger/sync.py

@@ -0,0 +1,3 @@
+"""Nightly ledger sync to the finance system."""
+
+SCHEDULE_CRON = "0 2 * * *"

package/packs/solution-architect/skills/context-graph/evals/files/7/README.md

@@ -0,0 +1,4 @@
+# fernwood
+
+Multi-tenant data platform: ingest pipelines, an event bus, and the services on top.
+Design decisions: `design/decisions/` (DD-nnn). Bigger proposals: `rfcs/`.

package/packs/solution-architect/skills/context-graph/evals/files/7/db/queries/orders.sql

@@ -0,0 +1,2 @@
+-- name: get_order
+SELECT id, tenant_id, total_minor FROM orders WHERE id = %(id)s AND tenant_id = %(tenant_id)s;

package/packs/solution-architect/skills/context-graph/evals/files/7/db/sharding/router.py

@@ -0,0 +1,9 @@
+"""Pick the shard for a tenant (DD-006)."""
+
+import hashlib
+
+SHARD_COUNT = 16
+
+
+def shard_for(tenant_id: str) -> int:
+    return int(hashlib.sha256(tenant_id.encode()).hexdigest(), 16) % SHARD_COUNT

package/packs/solution-architect/skills/context-graph/evals/files/7/design/decisions/DD-001-postgres-primary.md

@@ -0,0 +1,8 @@
+# DD-001: Postgres is the primary datastore
+
+Status: Accepted
+Date: 2022-04-11
+Deciders: O. Mensah
+Governs: db/, services/
+
+All service state lives in Postgres. No second OLTP database without a new decision.

package/packs/solution-architect/skills/context-graph/evals/files/7/design/decisions/DD-002-kafka-event-bus.md

@@ -0,0 +1,20 @@
+# DD-002: Kafka is the event bus
+
+Status: Accepted
+Date: 2022-06-02
+Deciders: O. Mensah, T. Lindqvist
+Governs: pipelines/ingest/, pipelines/fanout/
+
+## Context
+Ingest events must reach several independent consumers (fan-out, billing export, the audit sink),
+and a consumer that is down for a deploy must be able to catch up afterwards.
+
+## Options considered
+1. Postgres LISTEN/NOTIFY — rejected: notifications are lost if no listener is connected at the
+   moment they fire, there is no replay, and payloads are capped at 8000 bytes.
+2. RabbitMQ — rejected: no long replay window without extra plugins.
+3. Kafka — chosen.
+
+## Decision
+Use Kafka. Every topic keeps 7 days of retention so any consumer can replay a week of events.
+Retention policy details: see DD-007.

package/packs/solution-architect/skills/context-graph/evals/files/7/design/decisions/DD-003-no-orm.md

@@ -0,0 +1,9 @@
+# DD-003: No ORM in services
+
+Status: Accepted
+Date: 2022-07-19
+Deciders: T. Lindqvist
+Governs: services/
+
+Services use hand-written SQL kept in db/queries/. No ORM: we want query plans reviewable in code
+review and no lazy-loading surprises on hot paths.

package/packs/solution-architect/skills/context-graph/evals/files/7/design/decisions/DD-006-tenant-sharding.md

@@ -0,0 +1,9 @@
+# DD-006: Shard by tenant
+
+Status: Accepted
+Date: 2023-01-30
+Deciders: Platform guild (O. Mensah, R. Vidal)
+Governs: db/sharding/
+
+Each tenant's data lives on exactly one shard, chosen by a hash of tenant_id. Cross-tenant queries
+go through the reporting replica, never the shards.

package/packs/solution-architect/skills/context-graph/evals/files/7/design/decisions/DD-011-orm-for-admin-console.md

@@ -0,0 +1,11 @@
+# DD-011: Allow SQLAlchemy in the admin console
+
+Status: Accepted
+Date: 2024-05-08
+Deciders: R. Vidal
+Amends: DD-003
+Governs: services/admin-console/
+
+The admin console is internal, low-traffic CRUD over ~40 tables. Hand-written SQL there cost more
+than it saved. SQLAlchemy is allowed in services/admin-console/ only. Every other service keeps
+DD-003's no-ORM rule.

package/packs/solution-architect/skills/context-graph/evals/files/7/pipelines/fanout/router.py

@@ -0,0 +1,4 @@
+"""Fans ingest.normalised out to downstream consumers."""
+
+GROUP_ID = "fanout-router"
+SOURCE_TOPIC = "ingest.normalised"

package/packs/solution-architect/skills/context-graph/evals/files/7/pipelines/ingest/consumer.py

@@ -0,0 +1,5 @@
+"""Reads ingest.raw, normalises records, publishes to ingest.normalised."""
+
+GROUP_ID = "ingest-normaliser"
+SOURCE_TOPIC = "ingest.raw"
+SINK_TOPIC = "ingest.normalised"

package/packs/solution-architect/skills/context-graph/evals/files/7/pipelines/ingest/topics.yaml

@@ -0,0 +1,8 @@
+# Kafka topic config for ingest
+topics:
+  - name: ingest.raw
+    partitions: 12
+    retention.ms: 259200000
+  - name: ingest.normalised
+    partitions: 12
+    retention.ms: 259200000

package/packs/solution-architect/skills/context-graph/evals/files/7/rfcs/0004-region-sharding.md

@@ -0,0 +1,15 @@
+# RFC 0004: Shard by region instead of tenant
+
+Status: Withdrawn
+Date: 2025-02-14
+Author: P. Tamboli
+Supersedes: DD-006
+Governs: db/sharding/
+
+## Proposal
+Move from tenant sharding to region sharding (eu, us, apac) so data-residency rules map to shards.
+
+## Withdrawal note (2025-03-20)
+Withdrawn after the cost review: re-sharding every tenant was estimated at two quarters of work and
+residency can be met by pinning tenants to regional shards under the existing scheme. Tenant
+sharding (DD-006) stays.

package/packs/solution-architect/skills/context-graph/evals/files/7/services/admin-console/models.py

@@ -0,0 +1,11 @@
+from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
+
+
+class Base(DeclarativeBase):
+    pass
+
+
+class Tenant(Base):
+    __tablename__ = "tenants"
+    id: Mapped[int] = mapped_column(primary_key=True)
+    name: Mapped[str]

package/packs/solution-architect/skills/context-graph/evals/files/7/services/orders/repo.py

@@ -0,0 +1,9 @@
+"""Orders persistence. SQL lives in db/queries/orders.sql."""
+
+from pathlib import Path
+
+QUERIES = Path(__file__).resolve().parents[2] / "db" / "queries" / "orders.sql"
+
+
+def load_queries():
+    return QUERIES.read_text()

package/packs/solution-architect/skills/context-graph/evals/files/8/README.md

@@ -0,0 +1,11 @@
+# harbor-ledger
+
+Double-entry ledger service for the Harbor payments platform.
+
+- `services/ledger/` — the ledger service (Python)
+- `api/` — service interface definitions
+- `config/` — runtime configuration
+- `docs/adr/` — architecture decision records
+- `docs/rfcs/` — proposals under discussion
+
+`services/ledger/api/gen/` is generated from `api/ledger.proto` at build time and is not checked in.

package/packs/solution-architect/skills/context-graph/evals/files/8/api/ledger.proto

@@ -0,0 +1,30 @@
+syntax = "proto3";
+
+package harbor.ledger.v1;
+
+// Public interface of the ledger service. Client stubs are generated from this file.
+service Ledger {
+  rpc PostEntry(PostEntryRequest) returns (PostEntryResponse);
+  rpc GetBalance(GetBalanceRequest) returns (Balance);
+}
+
+message PostEntryRequest {
+  string idempotency_key = 1;
+  string account_id = 2;
+  int64 amount_minor = 3;
+  string currency = 4;
+}
+
+message PostEntryResponse {
+  string entry_id = 1;
+}
+
+message GetBalanceRequest {
+  string account_id = 1;
+}
+
+message Balance {
+  string account_id = 1;
+  int64 balance_minor = 2;
+  string currency = 3;
+}

package/packs/solution-architect/skills/context-graph/evals/files/8/config/http.yaml

@@ -0,0 +1,10 @@
+# Outbound HTTP settings for the payment-provider client
+provider:
+  base_url: https://provider.example.invalid/v2
+  timeout_seconds: 30
+  max_retries: 5
+  backoff:
+    base_ms: 200
+    jitter: full
+  retry_methods: [GET, POST]
+  api_key: REPLACE_ME

package/packs/solution-architect/skills/context-graph/evals/files/8/config/messaging.yaml

@@ -0,0 +1,8 @@
+# Domain event publishing
+broker: kafka
+bootstrap_servers:
+  - kafka-0.harbor.internal:9092
+  - kafka-1.harbor.internal:9092
+topic: ledger.entry-events
+key: account_id
+acks: all

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

@@ -0,0 +1,20 @@
+# 1. Record architecture decisions
+
+Date: 2024-01-10
+
+## Status
+
+Accepted
+
+## Context
+
+We need to record the architectural decisions made on this project.
+
+## Decision
+
+We will use Architecture Decision Records, as described by Michael Nygard, kept in `docs/adr/`.
+Larger proposals that need discussion first go in `docs/rfcs/` and become an ADR once accepted.
+
+## Consequences
+
+See Michael Nygard's article for a detailed description of the process.

package/packs/solution-architect/skills/context-graph/evals/files/8/docs/adr/0002-postgresql-for-ledger.md

@@ -0,0 +1,22 @@
+# 2. Use PostgreSQL for ledger storage
+
+Date: 2024-01-22
+
+## Status
+
+Accepted
+
+## Context
+
+The ledger needs transactional writes across journal entries and account balances, and the
+team already operates PostgreSQL for two other services.
+
+## Decision
+
+Ledger state lives in PostgreSQL. Schema changes are plain SQL migrations under
+`services/ledger/db/migrations/`, numbered sequentially and never edited once merged.
+
+## Consequences
+
+- Balances are computed inside a transaction with the entries that change them.
+- No ORM-generated migrations.

package/packs/solution-architect/skills/context-graph/evals/files/8/docs/adr/0003-rabbitmq-domain-events.md

@@ -0,0 +1,22 @@
+# 3. Publish domain events over RabbitMQ
+
+Date: 2024-02-14
+
+## Status
+
+Accepted
+
+## Context
+
+Downstream services (notifications, reporting) need to react when entries are posted.
+
+## Decision
+
+The ledger publishes `EntryPosted` and `AccountFrozen` events to a RabbitMQ topic exchange
+named `ledger.events`. Publishing code lives in `services/ledger/events/`. Broker settings
+are in `config/messaging.yaml`.
+
+## Consequences
+
+- Consumers bind their own queues; the ledger does not know who listens.
+- Events are at-least-once; consumers must be idempotent.

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

@@ -0,0 +1,32 @@
+---
+id: ADR-0004
+title: Store money as integer minor units
+status: accepted
+date: 2024-03-05
+deciders: [m.okafor, j.lindqvist]
+---
+
+# Store money as integer minor units
+
+## Context and Problem Statement
+
+Floating point and arbitrary-precision decimals have both caused rounding bugs on previous
+projects. How should monetary amounts be represented in the ledger?
+
+## Considered Options
+
+* `NUMERIC` columns with Python `Decimal`
+* Integer minor units (cents, pence) with a separate ISO 4217 currency code
+
+## Decision Outcome
+
+Chosen option: "Integer minor units", because sums are exact and every currency we support
+has a fixed minor-unit exponent.
+
+Every amount column in `services/ledger/db/migrations/` is `BIGINT` named `*_minor`, paired
+with a `currency CHAR(3)` column. `services/ledger/models/entry.py` exposes amounts as `int`.
+
+### Consequences
+
+* Good, because addition is exact and fast.
+* Bad, because display code must apply the currency exponent.

package/packs/solution-architect/skills/context-graph/evals/files/8/docs/adr/0005-provider-http-retries.md

@@ -0,0 +1,26 @@
+# ADR 0005: Retry and timeout policy for payment-provider calls
+
+* Status: Accepted
+* Date: 2024-04-18
+
+## Context
+
+The payment provider occasionally returns 502/503 during their deploys. Unbounded retries
+during an outage amplified load on them last year and held our worker threads.
+
+## Decision
+
+Calls from `services/ledger/clients/provider.py` to the provider:
+
+| Setting            | Value                                   |
+|--------------------|-----------------------------------------|
+| Request timeout    | 5 seconds                               |
+| Max retries        | 3                                       |
+| Backoff            | exponential, 200 ms base, full jitter   |
+| Retry on           | GET and idempotent POST (with key) only |
+
+Values are read from `config/http.yaml`; the code must not hard-code them.
+
+## Consequences
+
+Worst-case latency of a provider call is bounded at roughly 21 seconds.

package/packs/solution-architect/skills/context-graph/evals/files/8/docs/adr/0006-openapi-generated-clients.md

@@ -0,0 +1,20 @@
+# 6. Generate service clients from an OpenAPI spec
+
+Date: 2024-06-03
+
+## Status
+
+Accepted
+
+## Context
+
+Three internal teams call the ledger and each hand-wrote a client.
+
+## Decision
+
+The ledger's public interface is defined in `api/openapi.yaml`. Clients are generated from it
+into `clients/generated/` on every release; hand-written clients are not accepted.
+
+## Consequences
+
+- The spec is the source of truth; the server is checked against it in CI.

package/packs/solution-architect/skills/context-graph/evals/files/8/docs/adr/0007-kafka-domain-events.md

@@ -0,0 +1,25 @@
+---
+id: ADR-0007
+title: Move domain events to Kafka
+status: accepted
+date: 2025-03-11
+supersedes: ADR-0003
+---
+
+# Move domain events to Kafka
+
+## Context and Problem Statement
+
+Reporting now needs to replay the full history of posted entries, which RabbitMQ queues
+cannot give us once a message is acknowledged.
+
+## Decision Outcome
+
+Domain events are published to the Kafka topic `ledger.entry-events`, keyed by account id,
+with 30-day retention. This supersedes ADR-0003. Publishing stays in
+`services/ledger/events/`; broker settings stay in `config/messaging.yaml`.
+
+### Consequences
+
+* Good, because consumers can replay from any offset within retention.
+* Bad, because the team now operates a Kafka cluster.

package/packs/solution-architect/skills/context-graph/evals/files/8/docs/adr/0008-structured-logging.md

@@ -0,0 +1,18 @@
+# ADR 0008: Structured JSON logging
+
+* Status: Accepted
+* Date: 2025-05-20
+
+## Context
+
+Log search across services is painful because each one logs free text differently.
+
+## Decision
+
+All ledger logging goes through `services/ledger/logging.py`, which emits one JSON object per
+line with `ts`, `level`, `msg`, `trace_id` and `account_id` fields. The `trace_id` comes from
+the tracing setup described in ADR-0011.
+
+## Consequences
+
+Plain `print` and ad-hoc `logging.basicConfig` calls are not allowed in service code.

package/packs/solution-architect/skills/context-graph/evals/files/8/docs/rfcs/RFC-012-idempotency-keys.md

@@ -0,0 +1,19 @@
+# RFC-012: Idempotency keys for posting entries
+
+- **State:** Draft
+- **Author:** j.lindqvist
+- **Opened:** 2025-08-02
+
+## Summary
+
+Clients send an `Idempotency-Key` with every `PostEntry` call. The ledger stores the key and
+the response for 24 hours and returns the stored response on a repeat.
+
+## Proposed implementation
+
+`services/ledger/api/idempotency.py`, backed by a table `idempotency_keys` in PostgreSQL.
+
+## Open questions
+
+- Is 24 hours long enough for the batch importer, which can retry after a day?
+- Should a key reused with a different body be a 409 or a 422?

package/packs/solution-architect/skills/context-graph/evals/files/8/services/ledger/api/idempotency.py

@@ -0,0 +1,19 @@
+import json
+from datetime import timedelta
+
+KEY_TTL = timedelta(hours=24)
+
+
+def lookup(conn, key: str):
+    row = conn.execute(
+        "SELECT response FROM idempotency_keys WHERE key = %s AND created_at > now() - %s",
+        (key, KEY_TTL),
+    ).fetchone()
+    return json.loads(row[0]) if row else None
+
+
+def store(conn, key: str, response: dict) -> None:
+    conn.execute(
+        "INSERT INTO idempotency_keys (key, response) VALUES (%s, %s) ON CONFLICT DO NOTHING",
+        (key, json.dumps(response)),
+    )