@coralai/sps-cli 0.42.0 → 0.44.0

package/skills/coding-standards/references/commits-and-prs.md

@@ -0,0 +1,226 @@
+# Commits and Pull Requests
+
+Small commits, small PRs, clear messages. The boring hygiene that pays off during incidents.
+
+## One logical change per commit
+
+A commit should be a coherent unit — reverting it should be safe, and the message should explain *why*.
+
+```
+# ✅ good commit progression
+1. refactor: extract UserValidator from UserService (no behavior change)
+2. test: add failing test for empty-email case
+3. fix(user): reject empty email in validator
+4. docs: note the new error response in the API doc
+
+# ❌ "WIP", "fix stuff", "address review", "final changes final v2"
+```
+
+If you can't describe the commit in one clear sentence, split it.
+
+## Commit messages — Conventional Commits
+
+```
+<type>(<scope>): <summary>
+
+<body: why the change, not what>
+
+<footer: tickets, breaking changes, co-authors>
+```
+
+### Types
+
+| Type | Use for |
+|---|---|
+| `feat` | New user-visible feature |
+| `fix` | Bug fix |
+| `perf` | Performance improvement (behavior unchanged) |
+| `refactor` | Code change with no behavior change |
+| `docs` | Docs only |
+| `test` | Tests only |
+| `build` | Build system, deps, tooling |
+| `ci` | CI config |
+| `chore` | Housekeeping, version bumps |
+| `style` | Formatting only |
+| `revert` | Reverts a previous commit |
+
+### Example
+
+```
+fix(auth): reject tokens with `alg: none`
+
+A crafted JWT with `alg: none` bypassed signature verification on the
+/admin endpoints because we used a default-permissive parser. This locks
+the accepted algorithm set to HS256 and RS256 and rejects everything else
+at parse time.
+
+Refs: SEC-412
+Co-Authored-By: Alice <alice@example.com>
+```
+
+Rules:
+- **Summary line ≤ 72 chars**, imperative mood ("add", not "added").
+- **Body wraps at 72**, separated from summary by blank line.
+- Explain *why*; the diff already shows *what*.
+- Reference tickets / incidents.
+
+## Subject line quick rules
+
+```
+✅ feat(orders): support partial shipments
+✅ fix(api): return 422 instead of 500 on malformed JSON
+✅ perf(search): precompute embedding lookup table
+
+❌ Updated file
+❌ More changes
+❌ Fix bug
+❌ Small tweaks
+❌ WIP
+```
+
+If you find yourself writing "and" in a commit message, you're committing two things. Split.
+
+## Atomic commits = safe rollbacks
+
+```
+git revert <commit>           # cleanly reverses one logical change
+```
+
+If one commit touches migrations, feature code, and unrelated formatting, you can't revert safely. Splitting pays off the first time something goes wrong.
+
+## PR size — keep it reviewable
+
+| Diff size | What's reasonable |
+|---|---|
+| < 100 lines | Normal feature increment |
+| 100–400 | Upper bound for typical work |
+| 400+ | Only for: rename, generated code, new directory from a template |
+| 1000+ | You're hiding a mistake |
+
+Split by:
+- Behavior change vs. refactor — separate PRs
+- Independent feature pieces — stacked PRs
+- Rename / formatting — always its own PR
+
+Reviewers have finite attention. A 2000-line PR gets a rubber stamp, not a review.
+
+## Branching
+
+Pick one and stick to it.
+
+- **Trunk-based** — short-lived branches, merge to main daily. Best for most teams.
+- **GitFlow** — `develop` + `release/*` + `hotfix/*`. Heavier; makes sense for shipped products with long support branches.
+- **Feature branches + PR to main** — pragmatic middle ground.
+
+Whichever you pick, the rule holds: short-lived branches. Long-lived branches drift and merge pain compounds.
+
+## Branch naming
+
+```
+<type>/<short-slug>
+
+feat/partial-shipments
+fix/auth-alg-none
+chore/bump-node-20
+refactor/extract-validator
+```
+
+Include a ticket id if your team tracks them: `fix/SEC-412-alg-none`.
+
+## The PR description
+
+A good PR description saves the reviewer 10 minutes.
+
+```markdown
+## What
+Support partial shipments on orders.
+
+## Why
+Warehouse can't always fulfill the full order in one go; today they either
+ship late or cancel. Closes ORDERS-187.
+
+## How
+- New `Shipment` aggregate, `Order.shipments: []Shipment`
+- `POST /orders/:id/shipments` creates one
+- Order status derives from shipment state (`partial` if any unshipped items)
+
+## Tests
+- Unit: shipment state transitions
+- Integration: POST /shipments, GET /orders/:id reflects partial status
+- Manual: verified on staging with 2-item order, shipped one item, refunded another
+
+## Rollout
+- Feature flag: `partial_shipments_enabled` (default off)
+- Migration: adds `shipments` table; safe on empty + large tables (indexed)
+- Rollback: disable flag; table can stay
+```
+
+If the team has a PR template, use it — even for "obvious" PRs. Reviewer context is never obvious to the reviewer.
+
+## Rebase vs. merge
+
+- **Rebase your feature branch on main** before opening a PR to get a clean linear history.
+- **Squash on merge** to main if the PR has noisy intermediate commits; keep it unsquashed if the history is clean and meaningful.
+- **Never rebase a branch other people are working on.** Force-push on a shared branch is how you make enemies.
+
+## `.gitignore` — keep secrets and junk out
+
+Default entries for any repo:
+
+```
+# dependencies
+node_modules/
+.venv/
+target/
+
+# env / secrets
+.env
+.env.local
+*.pem
+*.key
+
+# IDE
+.idea/
+.vscode/
+*.swp
+
+# OS
+.DS_Store
+Thumbs.db
+
+# build
+dist/
+build/
+*.pyc
+```
+
+Check before the first commit. Once a secret lands in git history, you must rotate it — `git rm` doesn't remove history.
+
+## Commit discipline during review
+
+If review asks for changes, commit the change, don't amend silently. The reviewer needs to see the delta.
+
+```
+# ✅
+git commit -m "fix(auth): handle empty role list per review"
+git push
+
+# ❌
+git commit --amend --no-edit
+git push --force-with-lease      # reviewer's already-read diff is now lost
+```
+
+Squash at merge time if you want a clean final history.
+
+## Anti-patterns
+
+| Anti-pattern | Fix |
+|---|---|
+| `git add -A` with no check | Review with `git status` / `git diff --staged` first |
+| Committing with `--no-verify` to skip hooks | Fix the hook failure; don't bypass |
+| Force-push to a shared branch | Rebase your own branch only |
+| 5000-line PR "final cleanup" | Split into: rename / format / real change |
+| Empty PR description | Write what / why / how, even for small changes |
+| "WIP" / "fix" commit messages that ship to main | Squash on merge if they're noise |
+| Mixing a dependency bump with a feature | Separate PRs |
+| Merging your own PR without review | Team agrees on when this is OK (e.g., docs only) |

package/skills/coding-standards/references/error-strategy.md

@@ -0,0 +1,193 @@
+# Error Strategy
+
+When to raise, when to return a result, when to log, when to retry. Language-neutral decisions. For syntax (`try/except`, chaining, exception groups), see the language skill.
+
+## The question tree
+
+```
+Is this an expected outcome?
+  yes → return a result (Option, Result, ValidationResult, nullable)
+  no ↓
+Can this layer recover meaningfully?
+  yes → catch specifically, handle, don't re-raise
+  no ↓
+Propagate. Let the edge (HTTP handler, CLI, worker) decide.
+```
+
+One sentence: **expected = data, unexpected = exception, recoverable = catch narrowly, else propagate.**
+
+## Expected vs. exceptional
+
+| Case | Treatment | Why |
+|---|---|---|
+| User input invalid | Return errors to the caller | User mistakes are expected; not exceptional |
+| Item not found on lookup | Return `None` / `Option::None` | Missing is a normal outcome |
+| DB connection dropped | Raise | Infrastructure failure; unexpected |
+| Optimistic-lock version conflict | Raise a domain `ConflictError` | Expected under concurrency; caller decides retry |
+| Programmer bug (null where not-null) | Raise (let it crash) | Hiding this creates a zombie system |
+
+The dividing line: if it's part of the normal business flow, return data; if it breaks the flow, raise.
+
+## Catch only what you can handle
+
+```
+# ❌ swallow-all
+try:
+    do_thing()
+except Exception:
+    pass              # now it looks fine; tomorrow something real is lost
+
+# ❌ swallow-and-log (better, still bad if you can't recover)
+try:
+    do_thing()
+except Exception as e:
+    log.error("oops: %s", e)
+
+# ✅ catch the specific type you know how to handle
+try:
+    return cache.get(key)
+except CacheUnavailable:
+    return source.load(key)      # real fallback
+
+# ✅ the rest propagates
+```
+
+Rule: if catching doesn't let you recover, re-raise. The higher layer knows what to do.
+
+## Exception hierarchy
+
+Per service / module, one base, several subclasses for kinds of failure.
+
+```
+AppError (base)
+├── ValidationError        # 4xx-ish
+├── NotFoundError          # 404
+├── ConflictError          # 409
+├── AuthError              # 401/403
+└── ExternalServiceError   # 502/503
+```
+
+- The edge (HTTP handler) maps `NotFoundError` → 404, `AuthError` → 401, etc. One translation layer, not scattered throughout the app.
+- Never leak framework exceptions (`SQLAlchemyIntegrityError`, `httpx.TimeoutException`) above the adapter. Translate at the adapter boundary into domain errors.
+
+## Preserve the cause
+
+When re-raising as a different type, chain the original so the traceback still makes sense. Every language has a form of `raise new from original`. Use it.
+
+```
+try:
+    response = http.get(url)
+except NetworkTimeout as e:
+    raise ExternalServiceError("pricing down") from e
+```
+
+Losing the cause makes incidents take twice as long to diagnose.
+
+## Result / Option types
+
+Some languages (Rust, Kotlin, Swift, Haskell) prefer typed results over exceptions. The calculus is the same, syntax differs:
+
+```
+# Result-style
+fn find_user(id: UserId) -> Result<User, FindError>
+
+match find_user(id):
+    Ok(user) -> ...
+    Err(FindError::NotFound) -> ...
+    Err(FindError::DbDown) -> ...
+```
+
+In languages without sum types, the idiomatic equivalent is `Optional` for missing + exceptions for failure.
+
+Don't fight the language. Use its native style.
+
+## Validation — return data, don't raise
+
+User-facing validation almost always returns data, not an exception. You want to collect *all* errors, not stop at the first.
+
+```
+result = validate(input)            # returns { ok: false, errors: [...] }
+if not result.ok:
+    return 422, result.errors
+```
+
+Reserve exceptions for truly exceptional validation — "the request doesn't even parse as JSON", for example.
+
+## Retries — only at the right layer
+
+Retries belong at the boundary that knows the call is retry-safe. Not inside a domain method, not sprinkled at every layer.
+
+```
+# ✅
+edge → retrier(timeout=5s, attempts=3) → adapter → network
+
+# ❌
+adapter retries, service retries, handler retries
+# → user waits 5× the timeout; retry storms on the dependency
+```
+
+See `backend/references/resilience.md` for retry patterns; this skill just says *where* the retry sits.
+
+## Logging exceptions
+
+Log at the layer that decided not to re-raise. Logging at every level produces log storms and duplicate reports.
+
+```
+# Bad — logged three times, same error
+handler:   log.error(e); raise
+service:   log.error(e); raise
+adapter:   log.error(e); raise
+
+# Good — log once, at the boundary
+handler:  log.exception(...); return 500
+service:  (no log, propagate)
+adapter:  (no log, propagate)
+```
+
+Include context in the log (request id, user id, inputs), never the secret values.
+
+## `finally` — for cleanup only
+
+Use `finally` / equivalent for release-the-resource logic (close file, release lock, restore state). Never put business logic in `finally`; it runs even on errors.
+
+```
+# ✅
+try:
+    lock.acquire()
+    do_critical_section()
+finally:
+    lock.release()
+
+# ❌
+try:
+    submit_order()
+finally:
+    send_confirmation_email()       # sends even if submit failed
+```
+
+## Crash early, crash clearly
+
+When an invariant breaks (null where not-null, state impossibility, config missing at boot), fail loudly at the earliest point. Don't try to "keep going".
+
+```
+# ✅ at boot
+assert config.db_url, "DB_URL is required"
+
+# ❌
+db_url = config.db_url or "localhost"      # silently masked; prod points at localhost
+```
+
+A service that refuses to start is easier to fix than one that pretends to work.
+
+## Anti-patterns
+
+| Anti-pattern | Fix |
+|---|---|
+| `try: ... except: pass` | Catch specific, handle or re-raise |
+| Converting exception into `return None` | Caller loses the "why" — expose the error |
+| Re-raising with a new message but no `from` | Traceback becomes useless |
+| Logging and re-raising at every layer | Log once, at the decider |
+| Catching `Exception` at a tight scope | You don't actually know what can happen there |
+| Control flow via exceptions (`raise StopIteration` to break a loop) | Use explicit flow |
+| Different error shapes for similar failures | Pick one base + specific subclasses |
+| Leaking adapter exceptions to the domain | Translate at the boundary |

package/skills/coding-standards/references/naming.md

@@ -0,0 +1,185 @@
+# Naming
+
+Names are the cheapest form of documentation and the most-read part of a codebase.
+
+## The test
+
+If you can name something clearly, you understand it. If every name you try is bad, the concept is bad.
+
+## Principles
+
+1. **Intention over implementation.** `active_users`, not `filtered_list`. `is_expired`, not `flag`.
+2. **Domain over mechanics.** `price_in_cents` over `value_int`. Names should read like the business, not the code.
+3. **Consistent vocabulary.** Pick one word per concept. `fetch / retrieve / load / get` → choose one, stick to it. Same for `user / account / customer` — they are different things; don't conflate.
+4. **Searchable.** A two-letter name is unsearchable. `i` in a three-line loop is fine; `i` as a module-level variable is not.
+5. **No encodings.** `strName`, `iCount`, `bFlag` (Hungarian notation) adds noise without signal — languages have types.
+6. **Avoid disinformation.** `user_list` that isn't actually a list is a trap. `account_map` that's a list of pairs is a trap.
+
+## Functions — verbs
+
+Describe what they do, not how.
+
+```
+# ✅
+calculate_total(order)
+send_welcome_email(user)
+mark_as_read(notification)
+
+# ❌
+process(x)                   # process what?
+handle_thing(data)           # what thing? what handling?
+do_work()                    # cool
+```
+
+## Booleans — predicates
+
+`is_`, `has_`, `can_`, `should_` prefixes read naturally in conditionals.
+
+```
+if is_active and has_permission(READ) and not is_expired: ...
+```
+
+Avoid double negatives: `is_not_disabled` is a trap. Flip to `is_enabled`.
+
+## Collections — plural nouns
+
+```
+users        : list of User
+user         : single User
+users_by_id  : map from id to User
+```
+
+Don't name the container in the name: `user_list` is redundant when the type is `list[User]`. Reserve `_list` / `_map` suffixes for when you have multiple collections of the same thing and need to disambiguate.
+
+## Numbers — include units
+
+Units in the name prevent entire categories of bugs.
+
+```
+# ✅
+timeout_seconds    = 30
+price_cents        = 2599
+file_size_bytes    = 1024
+latency_ms         = 87
+
+# ❌
+timeout = 30            # seconds? ms?
+price = 25.99           # USD? EUR?
+size = 1024             # bytes? KB? items?
+```
+
+Mixed-unit bugs (feet vs meters) have crashed spacecraft. They crash billing systems too.
+
+## Variables — scope dictates length
+
+Short scope → short name. Long scope → longer, more descriptive name.
+
+```
+# OK in a three-line loop
+for i, x in enumerate(items):
+    xs[i] = f(x)
+
+# Not OK at module scope
+x = load_all_records()          # x? x of what?
+```
+
+## Functions returning booleans
+
+Read as a predicate in an `if`.
+
+```
+# ✅
+if user.can_edit(document): ...
+
+# ❌
+if user.edit_permission(document): ...     # reads weird
+```
+
+## Async / concurrent
+
+Mark functions that do I/O or schedule work.
+
+```
+async def fetch_user(id): ...
+def fetch_user_async(id): ...          # in langs without `async` marker
+```
+
+Callers need to know they're awaiting something.
+
+## Types — nouns, in the singular
+
+```
+class User: ...               # a user
+class UserRepository: ...     # manages users
+class UserNotFoundError: ...  # specific, actionable
+```
+
+## Avoiding "magic"
+
+Replace literal numbers and strings with named constants when the meaning is non-obvious.
+
+```
+# ❌
+if user.age >= 18: ...
+sleep(86400)
+
+# ✅
+LEGAL_ADULT_AGE = 18
+ONE_DAY_SECONDS = 86400
+
+if user.age >= LEGAL_ADULT_AGE: ...
+sleep(ONE_DAY_SECONDS)
+```
+
+Exception: one-off small numbers that read naturally — `x * 2`, `str[0:10]` — don't need constants.
+
+## Events / notifications — past tense, subject-first
+
+```
+OrderPlaced, OrderShipped, UserRegistered, PaymentFailed
+```
+
+Not `PlaceOrder` (that's a command), not `OrderIsShipped` (noise). Events describe things that happened; commands describe things requested.
+
+## Files, modules, packages
+
+- **Lowercase, hyphen- or underscore-separated**, depending on the language.
+- Name by what's inside, not by mechanics. `user_service.py` > `helpers.py`.
+- Avoid kitchen-sink files: `utils`, `common`, `misc`, `helpers` — they become dumping grounds.
+
+## Endpoints, routes
+
+- Plural resource nouns: `/users`, `/orders/{id}/items`.
+- Kebab-case, not snake_case or camelCase in paths: `/user-sessions`, not `/userSessions`.
+- No verbs when CRUD fits: `POST /orders`, not `POST /createOrder`.
+
+## Feature flags
+
+Describe the capability, not the date, not the ticket.
+
+```
+# ✅
+checkout_v2_enabled
+redis_session_store_enabled
+
+# ❌
+temp_flag_jan_2026
+jira_1234_rollout
+```
+
+Flags outlive the ticket and the engineer who wrote it. Name for what the flag *does*.
+
+## Renaming is cheap; bad names compound
+
+IDEs rename safely across projects. If a name is wrong, fix it now. Six months of new code built on top of a confused name will be six months of confusion.
+
+## Anti-patterns
+
+| Anti-pattern | Fix |
+|---|---|
+| `data`, `info`, `item`, `manager`, `handler` | Say what it actually represents |
+| `foo_list` when it's a set | Use `foo_set` or just `foo` + typed container |
+| Ambiguous pairs: `user` / `account` / `customer` interchangeably | Define the distinction; use the right one |
+| Mixed naming conventions in one file | Follow the language's convention; don't invent your own |
+| Abbreviations that aren't standard | `usr`, `mngr`, `proc` — spell them out |
+| Numbered copies: `process1`, `process2`, `processFinal`, `processFinalV2` | Delete the old ones; one canonical name |