coding-os 0.3.2__py3-none-any.whl

core/skills/agent-memory/SKILL.md

@@ -0,0 +1,191 @@
+---
+name: agent-memory
+tier: workflow
+domain: [universal]
+description: Mechanical recipes for reading agent memory and running the learning loop (cross-session patterns, decisions, failure modes) via the cos_search / cos_details / cos_timeline / cos_learn_* tool family, plus how observation capture actually works (automatic, edit-derived). Use when recalling a past pattern in a new session, running the extract → suggest → validate loop, or understanding why you cannot hand-author a freeform observation. Pairs with src/core/rules/memory.md (policy), thinking_os (when in the Cognitive Cycle to invoke), and search (which retrieval layer to hit first).
+last_reviewed: "2026-06-05"
+---
+
+# agent-memory
+
+Purpose: turn the policy in [src/core/rules/memory.md](../../rules/memory.md) into mechanical recipes the agent can execute. The rule answers *when* and *what*; this skill answers *how* — the exact tool signatures, what is automatic vs explicit, and what the return envelopes look like. Every signature here is verified against [src/core/thinking_os/server.py](../../thinking_os/server.py); a CI drift-guard test fails if any drifts.
+
+Read when: recalling from memory (`cos_search`, `cos_details`, `cos_timeline`, `cos_learn_suggest`), running the learning loop (`cos_learn_extract` / `cos_learn_validate`), or understanding how observations get captured.
+
+Skip when: the query target is current code (use [graph-explorer](../graph-explorer/SKILL.md)) or current docs (use `cos_doc_search` per [search](../search/SKILL.md)). Memory is the third-priority retrieval layer.
+
+## The mental model — writes are automatic, you mostly READ
+
+The single most important fact: **you do not hand-author observations.** Memory is written automatically by PostToolUse capture hooks — every `Write`/`Edit`/`MultiEdit` derives a sanitized, deduped, impact-scored observation ([capture.py](../../thinking_os/capture.py)), and separate hooks capture tool failures and session events. Confidence on learned patterns is **system-computed** by brain-inspired LTP/LTD formulas, not a number you set. The agent's job is to **read** memory in the Orient phase and **reinforce** patterns via the learn loop. There is no freeform `record(title, body, confidence)` tool — by design.
+
+## The Decision Gate — before any memory call
+
+```
+Question                                  → Layer + Tool
+─────────────────────────────────────────────────────────
+"Where is function X defined?"            → graph    cos_graph_query
+"What does spec Y say?"                   → docs     cos_doc_search
+"What's in flight / blocked?"             → tasks    cos_task_board
+"Have I seen this pattern before?"        → memory   cos_search
+"Why did we choose approach Z?"           → memory   cos_search (memory_type=decision)
+"Which patterns apply to my task?"        → memory   cos_learn_suggest(domain=, complexity=)
+"What changed in the last N days?"        → memory   cos_timeline(days=N)
+"How does X work / who calls X / rename"  → graph    cos_graph_* (graph/code FIRST)
+"Not sure which layer"                    → default to graph/code; memory only for cross-session recall
+```
+
+If the gate routes elsewhere, **stop reading this skill** and go to the right layer. Memory is expensive (decay + confidence ranking); over-use pollutes ranking for everyone.
+
+## Read Recipes (the agent's primary memory interaction)
+
+### 1. Search by free-text query (most common read)
+
+```python
+cos_search(
+    query="cookie samesite",
+    limit=5,                       # 1-20, default 5
+    memory_type="",                # optional filter: pattern|workflow|error|decision|discovery
+    min_confidence=0.3,            # drop low-trust patterns; 0.3 = floor for useful, 0.0 = include all (noisy)
+    since_days=90,                 # cap age; 0 = no cap; 90-180 for "recent" queries
+)
+```
+
+Returns ranked rows `[{id, title, confidence, impact_score, memory_type, source_table}]`. Drill into the top 1-2 with `cos_details`.
+
+### 2. Drill into one record
+
+```python
+cos_details(
+    pattern_id=1234,               # the integer id from a cos_search / cos_learn_suggest row
+    source="learned_patterns",     # which table: observations | learned_patterns | task_outcomes
+)
+```
+
+Match `source` to the `source_table` field of the row you are drilling into — `cos_search` returns rows from both `observations` and `learned_patterns`.
+
+### 3. Task-aware suggestion
+
+```python
+cos_learn_suggest(
+    domain="BACKEND",              # task domain; optional
+    complexity="COMPLICATED",      # Cynefin classification; optional
+    task_type="feat",             # optional
+    limit=5,                       # top-K, 1-20, default 5
+)
+```
+
+Ranks learned patterns for the current task context and includes spaced repetition — fading patterns (0.2-0.4 confidence) that were once validated resurface for re-validation. Better than raw `cos_search` when you have a task in flight.
+
+### 4. Timeline view (what changed recently)
+
+```python
+cos_timeline(
+    days=14,                       # lookback window, 1-365, default 30
+    domain="",                     # optional domain filter
+    limit=20,                      # 1-50, default 20
+)
+```
+
+Use when the question is "what's new" rather than "what's known about X". Surfaces recent task outcomes + observations.
+
+## How memory is WRITTEN (mostly automatic)
+
+### 1. Automatic capture (the default — you do nothing)
+
+A PostToolUse hook calls [capture.py](../../thinking_os/capture.py) after every `Write`/`Edit`/`MultiEdit`: it derives `title` (`Modified <path>` / `Created <path>`), `narrative`, `memory_type` (auto-detected from the path), `impact_score`, and `concepts` from the file and tool, runs them through the write sanitizer (rejects injection, truncates over-length), dedups within a 30s window, and inserts. Tool failures and session events are captured by their own hooks. **The agent supplies nothing.**
+
+### 2. Explicit single-file capture (rare)
+
+```python
+cos_observation_record(
+    file_path="src/core/thinking_os/database.py",
+    tool_name="Edit",             # Write | Edit | MultiEdit; default "Edit"
+)
+```
+
+This triggers the **same** auto-capture machinery for one file. Use it only when the PostToolUse hook did not fire — e.g. under a runtime without PostToolUse coverage (Codex), or to force-capture a specific file. It does **not** accept a title, body, confidence, or impact — those are derived. There is no other write path.
+
+### 3. What each `memory_type` means (for reading + filtering)
+
+`memory_type` is auto-detected at capture; this table is for understanding what a stored row represents when you read or filter on it.
+
+| Type | What it captures |
+|---|---|
+| `pattern` | Reusable approach to a recurring problem |
+| `workflow` | Sequence of steps, not a one-off insight |
+| `error` | Bug → root cause → fix |
+| `decision` | Trade-off chosen + reason |
+| `discovery` | Surprising fact about the system |
+
+## The Learning Loop (extract → suggest → validate)
+
+The loop distills patterns from the corpus of task outcomes and lets the N-th session reuse them — the killer feature. Confidence moves automatically: a pattern that held gets reinforced (LTP), one that didn't decays (LTD).
+
+```
+cos_learn_extract(min_occurrences=3)        # scan task_outcomes corpus → mint learned_patterns
+        │                                     #   (domain_rework / skill_correlation / complexity_mismatch)
+        ▼
+cos_learn_suggest(domain=, complexity=)     # surface ranked patterns for the active task
+        │
+        ▼  agent uses a pattern, notes the outcome
+cos_learn_validate(pattern_id, was_helpful) # reinforce (LTP) or decay (LTD) its confidence
+```
+
+```python
+cos_learn_extract(min_occurrences=3)               # corpus-wide; NOT per-task
+cos_learn_suggest(domain="BACKEND", complexity="COMPLICATED", limit=5)
+cos_learn_validate(pattern_id=42, was_helpful=True)  # integer id + boolean
+```
+
+`cos_learn_extract` is a corpus scan (no task argument). `cos_learn_validate` is how confidence changes — there is no write-time confidence knob.
+
+## Cross-session verification
+
+Before recommending an action based on a memory hit, verify the named symbols / paths still exist (per [src/core/rules/memory.md](../../rules/memory.md)):
+
+- Memory says "function `foo` does X" → `cos_graph_query("foo")` to confirm it exists.
+- Memory says "file `src/core/X.py`" → `Read` it to confirm.
+- If gone or renamed: the memory is stale — re-verify against the code and trust the code, not the record.
+
+A memory recommendation that names a vanished symbol is worse than no memory — it's confidently wrong. Every `cos_search` row carries the record timestamp; re-verify when it predates the file's last change.
+
+## Decay + auto-deprioritization
+
+Ranking already factors in `access_count` (popular patterns surface), `last_verified_at` (stale sinks), `confidence` (trust-weighted), and the caller's `since_days` filter. You don't tune these at write time — you influence confidence through the learn loop (`cos_learn_validate`) and control reads via `min_confidence` + `since_days`. The ranking is the contract.
+
+## Audit log boundary
+
+Two separate stores. Don't conflate:
+
+| Concern | Store | Tool |
+|---|---|---|
+| "What did an agent learn?" | Operational memory | automatic capture + `cos_learn_*` |
+| "Who changed what + when (immutable)?" | Git history | `git log` / `git blame` |
+
+A permission change → audit log. A pattern about reviewing permissions → operational memory.
+
+## Privacy + Compliance
+
+The write sanitizer rejects injection and truncates over-length text at capture, but content discipline is still yours:
+
+- **No PII** in files you edit if it would land in a narrative — emails, names, customer-identifying strings.
+- **No secrets** — even masked. Memory is long-lived and replicated.
+- **Sensitive findings** (security incidents, financial decisions) → keep details in the postmortem doc; let capture record only the edit.
+
+## Anti-patterns (reject in review)
+
+- **Expecting a freeform `cos_observation_record(title=, body=, confidence=)`** — it does not exist; capture is edit-derived.
+- **Setting confidence by hand** — confidence is computed by the learn loop, not supplied.
+- **Calling `cos_learn_extract` per task with a task_id** — it is a corpus scan keyed by `min_occurrences`.
+- **Recording code facts** — that's the graph (`cos_graph_*`). Memory is for *cross-code* patterns.
+- **Reading without `min_confidence`** — top-K full of decayed noise.
+- **Trusting memory without verification** when the memory names a specific symbol/path.
+
+## Composition pointers
+
+- [references/memory-recipes.md](references/memory-recipes.md) — the `cos_*` read + learn-loop sequences.
+- [assets/memory-checklist.md](assets/memory-checklist.md) — the read + learn-loop gate.
+- Cognitive cycle entry: [thinking_os](../thinking_os/SKILL.md) — Orient phase routes to memory.
+- Layer routing: [search](../search/SKILL.md) decision gate (memory vs docs vs graph vs file).
+- Policy + 4-layer model: [src/core/rules/memory.md](../../rules/memory.md) — the *why*.
+- Task linkage: [task-driver](../task-driver/SKILL.md) — task outcomes feed the learn loop.

core/skills/agent-memory/assets/memory-checklist.md

@@ -0,0 +1,21 @@
+<!-- domain:META | layer:asset | ssot:false | updated:2026-06-05 -->
+# Agent-Memory Checklist
+
+Use when reading from agent memory or running the learn loop. Writes are automatic
+(edit-derived capture) — there is no freeform observation to hand-author.
+
+## When reading (Orient phase)
+- [ ] `cos_search(..., min_confidence=0.3, since_days=90)` for recent high-trust patterns.
+- [ ] `cos_learn_suggest(domain=..., complexity=...)` for task-relevant patterns.
+- [ ] `cos_details(pattern_id=..., source=...)` to drill into the top 1-2 (match `source` to the row's `source_table`).
+- [ ] Zero hits → fall through to docs, then code.
+
+## Learn loop
+- [ ] `cos_learn_extract(min_occurrences=3)` to mint patterns from the task-outcome corpus.
+- [ ] After using a suggested pattern, `cos_learn_validate(pattern_id, was_helpful)` so confidence tracks reality.
+
+## Hygiene
+- [ ] Confidence is system-computed — never expect a write-time confidence knob.
+- [ ] Code beats memory on conflict — a stale observation is re-verified against code, not trusted.
+- [ ] No PII / no secrets in files whose edits get captured into a narrative.
+- [ ] Who-did-what-when facts left to git history, not recorded as memory.

core/skills/agent-memory/references/memory-recipes.md

@@ -0,0 +1,57 @@
+<!-- domain:META | layer:reference | ssot:true | updated:2026-06-05 -->
+# Agent-Memory Recipes — Read + Learn Loop
+
+> P: The mechanical `cos_*` sequences for recalling memory and running the learn loop.
+> R: Recalling a past pattern in the Orient phase, or reinforcing a pattern after using it.
+> S: The memory *policy* (what belongs in memory, hygiene) — that's the co-shipping rule src/core/rules/memory.md.
+> N: [SKILL.md](../SKILL.md), [memory-checklist.md](../assets/memory-checklist.md)
+
+> Nav: [Skill](../SKILL.md)
+
+Writes are automatic (edit-derived capture); the agent mostly **reads**. Every
+signature below is verified against src/core/thinking_os/server.py. Policy (four-layer
+model, what to store, privacy) is SSOT in [memory.md](../../../rules/memory.md).
+
+## Read — recall in the Orient phase
+
+```
+cos_search("query about past patterns", min_confidence=0.3, since_days=90)
+cos_details(pattern_id=1234, source="learned_patterns")   # source ∈ observations|learned_patterns|task_outcomes
+cos_learn_suggest(domain="BACKEND", complexity="COMPLICATED", limit=5)   # ranked patterns for the task
+cos_timeline(days=14)                                       # what changed lately
+```
+
+`min_confidence=0.3` drops decayed low-trust rows; `since_days=90` for "recent"
+questions. Zero hits with those filters → fall through to docs (`cos_doc_search`)
+or code (`cos_graph_*`).
+
+## Write — automatic, not freeform
+
+Observations are captured automatically by the PostToolUse hook for every
+Write/Edit/MultiEdit (capture.py derives title/narrative/memory_type/impact,
+sanitizes, dedups, inserts). To force-capture one file where the hook did not
+fire (e.g. Codex):
+
+```
+cos_observation_record(file_path="src/core/X.py", tool_name="Edit")
+```
+
+There is no freeform record — title, confidence and impact are derived, never
+supplied. Record discipline is about WHAT you edit, not a manual call.
+
+## The learn loop (cross-session compounding)
+
+```
+cos_learn_extract(min_occurrences=3)                 # corpus scan → mint learned_patterns
+cos_learn_suggest(domain=, complexity=, limit=5)     # surface ranked patterns for the active task
+cos_learn_validate(pattern_id=42, was_helpful=True)  # reinforce (LTP) / decay (LTD) confidence
+```
+
+Confidence is system-computed: validating a pattern that held raises it, one that
+didn't lowers it. This is how the N-th session gets faster than the 1st.
+
+## Trust the code over memory
+
+Memory is frozen at write time; code evolves. If recall says "`foo` does X" but a
+`Read` shows it doesn't, the memory is stale — trust the code. Every `cos_search`
+result carries the record timestamp; re-verify when it predates the file's last change.

core/skills/api-design/SKILL.md

@@ -0,0 +1,232 @@
+---
+name: api-design
+description: Design HTTP / REST / GraphQL API contracts that survive multiple consumers and years of evolution. Use when defining a new endpoint, reviewing an OpenAPI spec, evolving a public API, debating REST vs GraphQL, deciding versioning strategy, designing pagination or idempotency keys, or shaping error envelopes. Paired with hexagonal-architecture (the use case is the contract; the API is its translation).
+tier: cross-cutting
+domain: [backend]
+last_reviewed: "2026-05-11"
+
+---
+
+# API Design — REST + GraphQL Contracts
+
+A practical guide to designing APIs that consumers can build against without surprises. Stack-agnostic; concrete patterns target this project's stack (Go+Fiber for the business backend, Python+FastAPI for the AI adapter, React Native client).
+
+## When to Use This Skill
+
+- Adding the first endpoint to a service — the contract you ship now will outlive three implementations.
+- Reviewing an OpenAPI / GraphQL schema PR before merge.
+- Adding a v2 version of a live endpoint without breaking v1 clients.
+- Debating REST vs GraphQL for a new bounded context.
+- Designing pagination, idempotency, rate-limit responses, batch endpoints.
+- Mapping domain errors (from a use case in your hexagonal architecture) to HTTP responses.
+
+Skip when: writing internal-only RPCs that have one caller and you control both sides — use whatever's fastest.
+
+## The Contract Is the Product
+
+Three rules that override everything else:
+
+1. **Consumers cannot read your code.** They read the contract. If the contract is ambiguous, the consumer guesses wrong, and you find out in production.
+2. **Breaking changes are expensive forever.** Every consumer must coordinate. Plan as if you can't break things — because at scale, you can't.
+3. **The use case shape is sacred. The API shape is negotiable.** Don't bend domain operations to match HTTP idioms. Translate at the adapter boundary (per hexagonal-architecture).
+
+## REST vs GraphQL — Decision
+
+Pick **REST** when:
+- Consumers are heterogeneous (mobile + web + 3rd-party). REST is the universal lingua franca.
+- Endpoints map cleanly to resources. CRUD-like dominates.
+- You need HTTP-native caching (CDN, proxies, conditional GET).
+- You want minimal client tooling (no codegen mandatory).
+
+Pick **GraphQL** when:
+- Single consumer team or tightly-coupled clients (e.g. one mobile app + one web app from same team).
+- Heavy over-fetching with REST: clients pull 12 fields and use 2.
+- Frequent shape evolution that doesn't justify a v2 endpoint.
+- You're willing to invest in DataLoader, persisted queries, query complexity limits.
+
+**For this project**: REST is the right default for both backends. RN is the only consumer; the cost of GraphQL machinery does not pay off yet.
+
+For the patterns and pitfalls of each, see [references/rest-contracts.md](references/rest-contracts.md) and [references/graphql-contracts.md](references/graphql-contracts.md).
+
+## Contract-First Workflow
+
+Authoring order, in this exact sequence:
+
+1. **Use case first.** The hexagonal use case has an Input DTO and an Output DTO. Those types ARE the source of truth. Write them before the API.
+2. **OpenAPI / GraphQL schema next.** Hand-write or generate from use case types. Do **not** hand-write Go/Python types from a schema someone else drafted.
+3. **Request/response samples.** Write 3 happy + 2 sad payloads in the spec. Code reviewers check these, not your prose.
+4. **Mock server.** OpenAPI → Prism / GraphQL → mock resolvers. Frontend builds against the mock; backend implements against the same spec.
+5. **Contract tests in CI.** Schemathesis (REST) / GraphQL-inspector (GraphQL). Catch drift before merge.
+6. **Implementation.** Last step. The schema is the spec; the code is the impl.
+
+## Versioning — Pick One Strategy and Stick to It
+
+Three strategies, ordered by maintenance cost (cheapest → most expensive):
+
+### Tolerant reader, no version (best for additive change)
+
+Server adds new fields freely. Old clients ignore unknown fields. Old fields stay forever once added.
+
+- **Pros**: zero version coordination, zero v2 migration.
+- **Cons**: cannot remove or rename fields. Schema accretes.
+- **When**: most internal APIs, mobile apps you control end-to-end (RN here qualifies).
+
+### URL versioning (`/v1/orders`, `/v2/orders`)
+
+Two parallel routes; clients pick.
+
+- **Pros**: trivial routing, clear in logs/CDN.
+- **Cons**: doubles surface area, doubles tests, doubles docs.
+- **When**: public APIs with external consumers you can't coordinate with.
+
+### Header versioning (`Accept: application/vnd.app.v2+json`)
+
+Same URL, different versions via content negotiation.
+
+- **Pros**: clean URL, versions per resource.
+- **Cons**: hard to debug, CDNs need to vary on header, harder for newcomers.
+- **When**: rare. Hypermedia APIs.
+
+**For this project**: tolerant reader by default. Promote to URL versioning the day you sign your first 3rd-party integration.
+
+## Idempotency — Mutations Must Be Replayable
+
+Every mutating endpoint (`POST`, `PUT`, `PATCH`, `DELETE`) MUST accept and honor an `Idempotency-Key` header. Why: networks drop responses; clients retry; you cannot tell a duplicate from a fresh request without it.
+
+```
+POST /orders
+Idempotency-Key: 8e0f7b1d-2a44-4c7f-9b2e-1c5d6e7f8a9b
+Content-Type: application/json
+
+{ "items": [...] }
+```
+
+Server behavior:
+
+1. First call with `key=K` → execute, store `(K, response)` for 24h.
+2. Subsequent call with same `key=K` → return stored response, do NOT re-execute.
+3. Stored response includes status code, headers, body.
+
+Stripe-style. Industry standard since ~2015. Do not skip this.
+
+For the implementation pattern (DB schema for the idempotency table, in-flight collision handling, key TTL), see [references/idempotency-pagination.md](references/idempotency-pagination.md).
+
+## Pagination — Cursor by Default
+
+Three options; pick by data shape:
+
+| Style | Use when | Avoid when |
+|---|---|---|
+| **Cursor** (opaque token) | Datasets that grow over time, ordered list, infinite scroll. | Random page jumps required. |
+| **Offset** (`?page=3`) | Small fixed datasets, admin grids with "go to page N" UX. | Large or growing datasets — slow + race-prone. |
+| **Keyset** (`?after_id=123`) | Strictly time-ordered, simple. | Multi-column ordering. |
+
+Cursor is the default for this project's RN client (infinite scroll lists). Pattern in [references/idempotency-pagination.md](references/idempotency-pagination.md).
+
+## Error Envelope — RFC 9457 Problem Details
+
+One envelope across the entire API surface. Every error response, every endpoint, every version. Spec: [RFC 9457 — Problem Details for HTTP APIs](https://www.rfc-editor.org/rfc/rfc9457.html) (replaces RFC 7807, ratified 2024).
+
+Minimal shape:
+
+```json
+{
+  "type": "https://api.app.com/problems/insufficient-funds",
+  "title": "Insufficient funds",
+  "status": 402,
+  "detail": "Account balance is $4.20; required $42.00.",
+  "instance": "/payments/pay_123",
+  "code": "insufficient_funds",
+  "errors": [
+    { "field": "amount", "code": "exceeds_balance", "message": "..." }
+  ]
+}
+```
+
+Rules:
+
+- **`type`** is a stable URL identifying the error class. Treat as the primary key for client switch logic.
+- **`code`** is a short machine token (`insufficient_funds`, `validation_failed`). Stable. Snake_case.
+- **`title`** is a one-line human summary. Frozen for a given `type`.
+- **`detail`** can vary per occurrence — actual numbers, names, etc. Safe to show users.
+- **`errors[]`** carries field-level validation breakdown. Empty/omitted for non-validation errors.
+- **Never `str(exc)`** in `detail`. Strip stack traces, SQL fragments, file paths.
+
+Full mapping table (domain exception → HTTP status → envelope) in [references/error-envelope.md](references/error-envelope.md).
+
+## Status Code Discipline
+
+Common ones, with the most-misused calls highlighted:
+
+| Code | Meaning | Common misuses |
+|---|---|---|
+| 200 | OK with body | Used for "created" — should be 201. |
+| 201 | Created — must include `Location` header | Forgetting `Location`. |
+| 202 | Accepted — async, will process later | Used for sync ops. |
+| 204 | No content (DELETE success, idempotent PUT) | Including a body anyway. |
+| 400 | Validation failed | Used for auth failures (should be 401/403). |
+| 401 | Not authenticated | Used when authenticated but lacks permission (should be 403). |
+| 403 | Authenticated but forbidden | Used to hide existence (should be 404 then). |
+| 404 | Not found OR hiding existence | Used for "deleted" (should be 410). |
+| 409 | Conflict (duplicate, lost update) | Used for validation (should be 400/422). |
+| 410 | Gone — was here, deleted | Rarely used; defaults to 404. |
+| 422 | Semantically invalid (parsed OK, business rule failed) | Used for syntax errors (should be 400). |
+| 429 | Rate-limited — must include `Retry-After` | Forgetting `Retry-After`. |
+| 500 | Unexpected server error | Used for known errors (should be 4xx). |
+| 503 | Temporarily unavailable | Used for permanent failures. |
+
+Default: **400 for "client did something wrong with the request shape"**, **422 for "request is well-formed but violates a business rule"**.
+
+## Rate Limiting Headers
+
+Every authenticated endpoint should expose three headers on every response (RFC 9239 / IETF draft, near-universal practice):
+
+```
+RateLimit-Limit: 100
+RateLimit-Remaining: 47
+RateLimit-Reset: 1745678901
+```
+
+On 429 responses, also include `Retry-After: 60` (seconds) so clients know when to retry.
+
+## Cross-Cutting Headers
+
+| Header | Direction | Purpose |
+|---|---|---|
+| `X-Request-Id` | both | Correlation across services. Generate at edge if absent. |
+| `X-Idempotency-Key` | request | See above. |
+| `If-Match` / `If-None-Match` | request | Optimistic concurrency (ETags). |
+| `Cache-Control` | response | Even if you don't cache, send `no-store` explicitly for sensitive endpoints. |
+| `Content-Encoding` | response | Always gzip/brotli responses >1KB. |
+
+## Common Anti-Patterns (full list in references/rest-contracts.md)
+
+1. **Verbs in URLs** — `POST /createOrder` instead of `POST /orders`.
+2. **Mixed casing** — `userId` in body, `user_id` in query string. Pick one project-wide.
+3. **Tunneling everything through POST** — using POST for reads "because complex query".
+4. **Returning 200 with `{"success": false}`** — use the right status code.
+5. **HTTP error in 200 body** — same.
+6. **Missing pagination on list endpoints** — works in dev, OOMs in prod.
+7. **Date strings without timezone** — always `2026-04-26T14:30:00Z` (RFC 3339).
+8. **Boolean string values** — `"true"` vs `true`. Use real JSON booleans.
+9. **`null` vs absent field semantic confusion** — document explicitly.
+10. **Inconsistent error shape per endpoint** — pick one envelope, use everywhere.
+
+## Testing the Contract
+
+Three layers, each catching different drift:
+
+1. **Schema tests** — OpenAPI + spectral lint, GraphQL + graphql-inspector. Catches malformed spec before merge.
+2. **Contract tests** — Schemathesis (REST) / Pact (consumer-driven). Hits live server with property-based requests.
+3. **Snapshot tests** — record happy + sad responses, diff in CI. Catches accidental shape change.
+
+For Go: `oapi-codegen` validates handlers against spec. For FastAPI: built-in `/openapi.json` is the spec — generate client from it. For RN: codegen from OpenAPI → typed client (`openapi-typescript-codegen`).
+
+## Source Material
+
+- *Web API Design: The Missing Link* (Apigee, free) — the foundational pamphlet.
+- RFC 9457 — Problem Details for HTTP APIs (2024 update).
+- RFC 9239 / draft-ietf-httpapi-ratelimit-headers.
+- Stripe API docs — gold standard for REST + idempotency + pagination.
+- GitHub REST API v3 + GraphQL v4 docs — the largest dual-flavor live API.
+- *Designing APIs with Swagger and OpenAPI* (Manning, 2024) — current OpenAPI 3.1 patterns.

core/skills/api-design/assets/api-design-checklist.md

@@ -0,0 +1,110 @@
+# API Design Pre-Launch Checklist
+
+Run this list before merging an OpenAPI / GraphQL schema, and again before exposing the endpoint outside the org. Each item maps to a section of the api-design skill or its references.
+
+## Contract Shape
+
+- [ ] **OpenAPI / GraphQL schema authored from use case types** (not the other way around).
+- [ ] **All status codes documented** — including 400, 401, 403, 404, 409, 422, 429, 500.
+- [ ] **All error responses use the RFC 9457 ProblemDetails envelope** (`Content-Type: application/problem+json`).
+- [ ] **Every error `code` is registered in `docs/errors/catalogue.yaml`**.
+- [ ] **No `additionalProperties: true`** (or its GraphQL equivalent) — unknown fields are rejected at the boundary.
+- [ ] **Field naming consistent with the project convention** (`snake_case` for this project).
+- [ ] **Dates use RFC 3339 UTC strings** (`2026-04-26T14:30:00Z`).
+- [ ] **Money uses integer minor units + currency string** (no floats, no implicit currency).
+- [ ] **IDs are prefixed strings** (`ord_…`, `usr_…`, `lsn_…`).
+- [ ] **`null` vs absent field semantics documented per field** when both can occur.
+
+## Mutations
+
+- [ ] **`Idempotency-Key` header accepted on every POST/PATCH/DELETE that mutates state**.
+- [ ] **Idempotency storage exists** (`idempotency_keys` table or equivalent).
+- [ ] **Body-hash collision handling**: same key + different body → 409 `idempotency_key_collision`.
+- [ ] **In-flight collision handling**: same key arrives twice in parallel → second waits or returns retryable error.
+- [ ] **5xx and timeouts NOT stored** as final responses (they are retryable).
+- [ ] **Idempotency entries TTL'd** (24h default).
+- [ ] **POST that creates returns 201 + `Location` header**.
+- [ ] **DELETE returns 204 No Content** on success.
+
+## List / Read
+
+- [ ] **All list endpoints paginated** (no unbounded result sets).
+- [ ] **Pagination is cursor-based** unless documented otherwise.
+- [ ] **`limit` parameter has a hard max** (100 default; reject larger).
+- [ ] **`next_cursor: null` + `has_more: false`** on the last page.
+- [ ] **Cursor is an opaque base64 token** (clients don't parse it).
+- [ ] **Cursor encodes a stable sort tuple** (e.g., `(created_at, id)`) so ties don't cause skips/duplicates.
+- [ ] **No `total` count returned** unless cached separately.
+- [ ] **Filter / sort / project params documented**.
+
+## Headers
+
+- [ ] **`X-Request-Id` echoed back** on every response.
+- [ ] **`Content-Type: application/json`** on JSON, **`application/problem+json`** on errors.
+- [ ] **`Content-Encoding: gzip`** for responses >1KB.
+- [ ] **`Cache-Control` set explicitly** on every endpoint (even if `no-store`).
+- [ ] **`ETag` set on cacheable resources** + 304 returned for matching `If-None-Match`.
+- [ ] **`RateLimit-Limit / RateLimit-Remaining / RateLimit-Reset` on every authenticated response**.
+- [ ] **`Retry-After` on every 429 / 503**.
+- [ ] **`Vary: Authorization, Accept-Language, Accept-Encoding`** when responses depend on these.
+- [ ] **`WWW-Authenticate` on 401**.
+
+## Security
+
+- [ ] **Auth scheme documented** (Bearer + JWT? Cookie session? both?).
+- [ ] **Per-endpoint scopes / permissions documented** (and enforced).
+- [ ] **No PII in URL paths or query params** (logs, browser history, referrers).
+- [ ] **No secrets in error responses** (never `str(exc)` in `detail`).
+- [ ] **No internal identifiers leaked** (table names, column names, file paths, stack traces).
+- [ ] **Request size limits set** (1MB default, raise per-endpoint with rationale).
+- [ ] **Rate limits set per endpoint** (not just global).
+- [ ] **CORS origins explicit** (no `*` for endpoints that read auth headers).
+- [ ] **`Strict-Transport-Security` header on TLS responses**.
+- [ ] **TLS-only**: redirect or refuse HTTP at the LB.
+
+## Versioning + Deprecation
+
+- [ ] **Versioning strategy documented** (tolerant reader / URL / header).
+- [ ] **Breaking changes tracked**: a CI tool (`oasdiff`, `graphql-inspector`) compares schema vs main on every PR.
+- [ ] **`Deprecation` header (RFC 9745) sent on deprecated fields/endpoints** with sunset date.
+- [ ] **Sunset timeline communicated** (≥6 months for public APIs).
+- [ ] **Old version kept alive long enough** for the slowest consumer to migrate.
+
+## Testing
+
+- [ ] **Schema lint passes** (`spectral lint`).
+- [ ] **Mock server runs** (`prism mock openapi.yaml`) — frontend can develop against it.
+- [ ] **Property-based contract tests run in CI** (`schemathesis`).
+- [ ] **Snapshot tests of happy + sad responses checked into repo**.
+- [ ] **Codegen happens in CI** — drift between server + clients is caught at PR time.
+
+## Observability
+
+- [ ] **`X-Request-Id` propagated through downstream calls** (set if missing at edge).
+- [ ] **Per-endpoint metrics**: count, P50/P95/P99 latency, error rate.
+- [ ] **Per-endpoint logs include** `request_id`, `user_id`, `endpoint`, `status`, `latency_ms`, `code` (on errors).
+- [ ] **No PII in logs** (mask emails, omit secrets, hash where needed for grouping).
+- [ ] **Slow-query log threshold set** (e.g. responses >500ms get their query plan attached).
+- [ ] **Trace context propagated** (W3C Trace-Context header).
+
+## Documentation
+
+- [ ] **Endpoint has a one-line `summary`** in the spec.
+- [ ] **Endpoint has a longer `description` with at least one example use case**.
+- [ ] **Each request body field has `description` + `example`**.
+- [ ] **Each error code links to its catalogue entry**.
+- [ ] **`/docs` (Swagger UI / GraphQL Playground) renders without errors**.
+- [ ] **Public-facing changelog updated** with the new endpoint and any breaking changes.
+
+## Mobile-Specific (this project's RN client)
+
+- [ ] **No offline-incompatible patterns** (no required real-time state for read endpoints).
+- [ ] **Response sizes bounded** — paginate aggressively; mobile cellular is precious.
+- [ ] **Conditional GET (ETag) supported** on cacheable endpoints — RN can persist + revalidate.
+- [ ] **Idempotency-Key MANDATORY on every mutation** — RN retries are the entire reason this header exists.
+- [ ] **Image / file URLs are CDN-served**, with `Cache-Control: max-age=31536000, immutable` for hashed assets.
+- [ ] **Avoid pre-signed URLs that expire in <1h** if mobile may be backgrounded.
+
+---
+
+**The shortest path to a healthy API**: copy this list into the PR template for new-endpoint PRs. Every box must be checked or explicitly waived with a reason in the PR description.