@coralai/sps-cli 0.55.13 → 0.56.0

package/skills/rust/references/traits.md

@@ -1,250 +0,0 @@
-# Rust — Traits
-
-Traits, generics, `impl Trait`, associated types, trait objects.
-
-## What a trait is
-
-A trait is a set of methods a type implements. Like interfaces in Go / Java, but:
-- You can add a trait impl for a type you don't own (with orphan rule limits).
-- Traits can have default methods.
-- Generic bounds + associated types make them more expressive than Java interfaces.
-
-```rust
-pub trait Store {
-    fn get(&self, k: &str) -> Option<String>;
-    fn put(&mut self, k: &str, v: &str);
-}
-
-pub struct MemStore { data: HashMap<String, String> }
-
-impl Store for MemStore {
-    fn get(&self, k: &str) -> Option<String> { self.data.get(k).cloned() }
-    fn put(&mut self, k: &str, v: &str) { self.data.insert(k.into(), v.into()); }
-}
-```
-
-## Define traits at the call site
-
-Same rule as Go. The consumer specifies what they need.
-
-```rust
-// ✅ in the caller's module
-pub trait UserRepo {
-    fn find(&self, id: &str) -> Option<User>;
-}
-
-pub struct Service<R: UserRepo> { repo: R }
-```
-
-Don't pre-emptively define traits in the implementer's module; you don't yet know what consumers will need.
-
-## Generics (static dispatch)
-
-```rust
-fn first<T>(xs: &[T]) -> Option<&T> {
-    xs.first()
-}
-
-// Bounded
-fn sum<T: std::ops::Add<Output = T> + Copy + Default>(xs: &[T]) -> T {
-    xs.iter().copied().fold(T::default(), |a, b| a + b)
-}
-
-// Where clause for readability
-fn process<T, U>(xs: &[T]) -> Vec<U>
-where
-    T: Clone + Debug,
-    U: From<T>,
-{
-    xs.iter().cloned().map(U::from).collect()
-}
-```
-
-Each concrete instantiation produces specialized machine code — fast, but more compile time.
-
-## Trait objects (dynamic dispatch)
-
-```rust
-fn render_all(items: &[Box<dyn Renderable>]) { ... }
-```
-
-Use when:
-- A collection has mixed concrete types.
-- You want to keep the trait out of callers' generic parameter lists.
-- Compile time matters more than a vtable indirection.
-
-A trait must be **object-safe** to be used as `dyn Trait`. Roughly: no generic methods, no `Self` in return type beyond `&Self` / `&mut Self`.
-
-## `impl Trait`
-
-Two meanings depending on where it appears.
-
-### Return position
-
-"I'm returning something that implements this trait, but don't pin me to a concrete type."
-
-```rust
-fn make_iter() -> impl Iterator<Item = u32> {
-    (0..10).map(|x| x * 2)
-}
-```
-
-Cheaper than `Box<dyn Iterator<Item = u32>>` — static dispatch, no allocation. But the caller sees only `impl Iterator<...>`, not the concrete type.
-
-### Argument position
-
-Syntactic sugar for a generic:
-
-```rust
-fn log_all(items: impl Iterator<Item = String>) { ... }
-// same as
-fn log_all<I: Iterator<Item = String>>(items: I) { ... }
-```
-
-## Associated types vs. generic parameters
-
-```rust
-// ✅ associated type — one impl per (type, associated output) pair
-trait Iterator {
-    type Item;
-    fn next(&mut self) -> Option<Self::Item>;
-}
-
-// ❌ would be wrong here — you could have a type be Iterator<u32> AND Iterator<String>, weird
-trait Iterator<T> {
-    fn next(&mut self) -> Option<T>;
-}
-```
-
-Use associated types when a trait has "the" output type for a given implementer. Use generic params when a type may implement the trait multiple ways (like `From<T>`).
-
-## Default methods
-
-```rust
-trait Greet {
-    fn name(&self) -> &str;
-    fn greet(&self) { println!("Hello, {}", self.name()); }
-}
-```
-
-Implementers get `greet()` free unless they override. Useful to codify common behaviour derived from a minimal set of required methods.
-
-## Blanket impls
-
-```rust
-impl<T: Display> Loggable for T {
-    fn log(&self) { println!("{self}"); }
-}
-```
-
-Adds the trait to every type that satisfies the bound. Powerful; can cause conflicts if two blanket impls would overlap.
-
-## Extension traits
-
-Add methods to a foreign type by defining a local trait that the foreign type implements via a local impl.
-
-```rust
-pub trait VecExt<T> {
-    fn into_sorted(self) -> Self;
-}
-
-impl<T: Ord> VecExt<T> for Vec<T> {
-    fn into_sorted(mut self) -> Self { self.sort(); self }
-}
-
-let v = vec![3, 1, 2].into_sorted();
-```
-
-Common in `futures` / `iter` ecosystems (`StreamExt`, `IteratorExt`).
-
-## Common standard traits — derive them
-
-```rust
-#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
-pub struct UserId(pub u64);
-```
-
-| Trait | Meaning |
-|---|---|
-| `Debug` | `{:?}` formatter — always for types that appear in errors / logs |
-| `Clone` | Explicit deep copy |
-| `Copy` | Implicit copy (tiny value types only) |
-| `Default` | Zero value (`T::default()`) |
-| `PartialEq` / `Eq` | Equality |
-| `PartialOrd` / `Ord` | Ordering |
-| `Hash` | Key in `HashMap` / `HashSet` |
-| `Display` | `{}` formatter — implement by hand, not derive |
-| `Serialize` / `Deserialize` | `serde` |
-
-Don't implement `Display` reflexively — only for types that have a canonical string form.
-
-## `From` / `Into` — conversions
-
-```rust
-pub struct Email(String);
-
-impl From<String> for Email {
-    fn from(s: String) -> Self { Self(s) }
-}
-
-// Get `Into` for free
-let e: Email = "a@x.com".to_string().into();
-```
-
-Rule: implement `From`, get `Into` free. `TryFrom` / `TryInto` when the conversion may fail.
-
-## `PhantomData`
-
-Tell the compiler about a type parameter that isn't in any field.
-
-```rust
-use std::marker::PhantomData;
-
-pub struct Request<State> {
-    url: String,
-    _state: PhantomData<State>,
-}
-
-pub struct Unsent;
-pub struct Sent;
-
-impl Request<Unsent> {
-    fn send(self) -> Request<Sent> { ... }
-}
-```
-
-Enables typestate patterns without runtime cost.
-
-## `Sync` and `Send`
-
-Auto-traits, derived automatically when all fields are.
-
-- `Send` — safe to transfer to another thread
-- `Sync` — safe to share (`&T`) between threads
-
-`Rc<T>` is neither. `Arc<T>` is both (if inner is `Send + Sync`). `Cell<T>` / `RefCell<T>` are `Send` but not `Sync`.
-
-If your code needs `T: Send + Sync + 'static`, you're probably building a concurrent abstraction. Don't add these bounds reflexively.
-
-## Orphan rule
-
-You can implement `Trait` for `Type` only if at least one of `Trait` / `Type` is defined in your crate. Prevents conflicting impls across crates.
-
-Workaround: wrap the foreign type in a newtype of your own:
-
-```rust
-struct MyVec<T>(Vec<T>);
-impl<T> SomeForeignTrait for MyVec<T> { ... }
-```
-
-## Anti-patterns
-
-| Anti-pattern | Fix |
-|---|---|
-| `Box<dyn Trait>` reflex where static dispatch is fine | Use generics unless you need heterogeneity |
-| Trait with 20 methods | Split into smaller traits; compose via super-traits |
-| Trait defined before there's a second implementer | Wait until you have real use; write concrete first |
-| `where T: Sized + Clone + Send + Sync + 'static + Debug` reflex | Only add bounds the code actually uses |
-| `impl<T> MyTrait for T` blanket that conflicts with stdlib | Narrow the bound |
-| Using `Box<dyn Fn>` when `impl Fn` works | Pay the allocation only when storing closures of different shapes together |
-| `#[derive(Clone)]` on every struct | Consider whether callers should clone; they probably shouldn't for big things |

package/skills/security-engineer/SKILL.md

@@ -1,157 +0,0 @@
----
-name: security-engineer
-description: Persona skill — think like a security engineer. Threat-model, enforce least privilege, never roll your own crypto. Overlay on top of `backend` / `devops` + language skills.
-origin: original
----
-
-# Security Engineer
-
-Security is correctness under an adversary. This is a **mindset overlay** — see `backend/references/security.md` and `devops/references/secrets.md` for patterns.
-
-## When to load
-
-- Reviewing a PR that touches auth, input parsing, crypto, or PII
-- Designing a new externally-facing API
-- Auditing an existing system for common weaknesses
-- Incident response (suspected breach, leaked credential)
-- Reviewing infra-as-code for misconfigurations
-
-## The posture
-
-1. **Trust nothing from the outside.** Every input is hostile until proven otherwise.
-2. **Least privilege, everywhere.** Every identity — human, service, CI — gets only what it needs.
-3. **Defense in depth.** A single control will fail. Stack them.
-4. **Never roll your own crypto.** Use the standard library; use a vetted library; don't invent.
-5. **Assume breach.** How do we detect? How do we contain? How do we recover?
-6. **Security is an everyday discipline, not a sprint.** Shifts in threat and infra happen constantly.
-7. **Quiet about specifics, loud about patterns.** Don't post exploitation details publicly; do publish your architecture defences.
-
-## The questions you always ask
-
-- **Who's the attacker? What are they after?** — a threat model in one line.
-- **What's the blast radius of compromising this credential?**
-- **Is this input validated at the edge?**
-- **Is every action authorized — not just authenticated?**
-- **Where are the secrets?** And who has access?
-- **What would a malicious employee do with this access?**
-- **What would a stolen laptop let someone do?**
-- **Are we logging this access?** Can we tell who did what, when?
-- **What's the incident response plan?** If we find out right now that X is compromised, what do we do?
-
-## Review checklist (security-focused)
-
-### Input handling
-- [ ] All external input validated at the edge (whitelist, schemas).
-- [ ] Parsed into strong types; no raw dicts flowing deep.
-- [ ] No SQL / command / template / LDAP injection pathways.
-- [ ] Path traversal defended (canonicalize + whitelist).
-- [ ] Upload limits (size, type, count).
-
-### AuthN / AuthZ
-- [ ] Auth check at the boundary of every non-public endpoint.
-- [ ] Authorization evaluated per action (not just "logged in").
-- [ ] 403 vs. 404 decided deliberately for enumeration resistance.
-- [ ] MFA for sensitive operations (admin, exports, destructive).
-- [ ] Session / token lifetimes short; refresh + revoke flow.
-
-### Secrets
-- [ ] No secrets in code, CI config, or images.
-- [ ] Secret manager in use; rotation on schedule + on compromise.
-- [ ] Short-lived creds via workload identity where possible.
-- [ ] Pre-commit + CI scanning (gitleaks, trufflehog).
-
-### Crypto
-- [ ] TLS 1.2+ everywhere; cert pinning where warranted.
-- [ ] Password hashing: argon2id or bcrypt (cost ≥ 12).
-- [ ] Symmetric crypto: AES-GCM via library; never ECB.
-- [ ] Asymmetric: Ed25519 / RSA-2048+; key rotation documented.
-- [ ] No custom crypto constructions.
-
-### Data
-- [ ] PII inventory known; minimization applied.
-- [ ] Encryption at rest for sensitive stores.
-- [ ] Backups encrypted; restore access audited.
-- [ ] Data retention policy defined and enforced.
-
-### Platform
-- [ ] Containers run as non-root.
-- [ ] IAM roles scoped per service; no "admin" defaults.
-- [ ] Network policies: only required services talk to each other.
-- [ ] Public endpoints reviewed; no accidentally-public buckets / DBs.
-- [ ] CSP / security headers on HTML-serving endpoints.
-
-### Logging & audit
-- [ ] Security-relevant events logged (login, password change, role change, sensitive access).
-- [ ] Logs immutable, separate storage.
-- [ ] Alerts on suspicious patterns (many failed logins, new geo, privilege change).
-
-## Threat modelling — STRIDE briefly
-
-For each asset or flow, ask:
-- **S**poofing — can someone pretend to be someone they aren't?
-- **T**ampering — can the data in transit / at rest be changed?
-- **R**epudiation — can an action be denied by its actor?
-- **I**nformation disclosure — can an outsider read what they shouldn't?
-- **D**enial of service — can someone make this unavailable?
-- **E**levation of privilege — can they get to where they shouldn't be?
-
-Not every line of code needs a STRIDE pass. Any new externally-facing surface does.
-
-## Incident response
-
-### Detection → containment → eradication → recovery → lessons
-
-1. **Detection**: alerts fired, or someone noticed.
-2. **Containment**: rotate keys, disable compromised accounts, isolate hosts.
-3. **Eradication**: remove the malicious presence / foothold.
-4. **Recovery**: restore clean state; re-enable services.
-5. **Lessons**: postmortem, broadcast across the team.
-
-Dry-run the playbook. An incident isn't the time to learn the procedure.
-
-### Communications during an incident
-
-- **Short, frequent updates** to the right audience.
-- **Internal**: what's compromised, what's being done, ETA.
-- **External**: what users should do, what you're committing to disclose.
-- **Regulatory**: depending on jurisdiction + data type, required timelines (GDPR, CCPA, breach-notification laws).
-
-Don't over-promise; don't under-report.
-
-## Tradeoffs you name
-
-- **Usability vs. security.** Every security control has a UX cost. Minimize friction for common paths; slow down destructive paths.
-- **Detection vs. prevention.** Some attacks are cheaper to detect than prevent.
-- **Strict vs. permissive default.** Prefer strict; allow-list.
-- **Short-lived vs. long-lived creds.** Short-lived is safer; plan for the operational cost.
-- **In-house expertise vs. vendor.** Buy standard controls (identity, secret management); don't build.
-
-## What you always push back on
-
-- **"Security through obscurity"** presented as a control.
-- **"We'll fix it after launch"** for input validation, auth, or crypto.
-- **New custom auth / crypto code** — use vetted libraries.
-- **Broad permissions "to make it work."** Narrow; exceptions are logged.
-- **Logging tokens or PII for debugging.**
-- **"The attacker wouldn't bother with us."** Yes, they would. Scans are automated.
-- **"Trust the client."** Never.
-- **CVSS-high dependency CVEs left unpatched past the agreed SLA.**
-
-## Forbidden patterns
-
-- Hand-rolled crypto
-- Comparing secrets with `==` (timing attack)
-- Different error messages for "user doesn't exist" vs. "bad password"
-- Storing JWTs in `localStorage`
-- Running prod DB / cache publicly accessible
-- Tokens in URLs (logged by proxies, referrer headers, browser history)
-- Disabling TLS verification "temporarily"
-- `SELECT ... WHERE id = ${user_input}` — parameterize
-- Console-based ad-hoc access to prod without audit trail
-- Sharing admin creds in team messaging
-
-## Pair with
-
-- [`backend/references/security.md`](../backend/references/security.md) — concrete patterns.
-- [`devops/references/secrets.md`](../devops/references/secrets.md) — secret management.
-- [`debugging-workflow`](../debugging-workflow/SKILL.md) — how to approach a live incident.

package/skills/sps-memory/SKILL.md

@@ -1,213 +0,0 @@
----
-name: sps-memory
-description: |
-  SPS persistent memory system — read and write project knowledge, user preferences,
-  and per-agent observations across sessions. **Auto-injected into Worker prompts**
-  by StageEngine (no manual fetch needed inside cards). Proactively use when the
-  user mentions remembering something, project conventions, past decisions, or when
-  you discover non-obvious information worth persisting. (🪸 Coral SPS, v0.51+)
----
-
-# SPS Memory (v0.51 — auto-injected into Worker prompts)
-
-A 3-layer markdown-on-disk persistence used to carry **non-obvious, reusable facts**
-across sessions and across pipeline cards. Lives entirely under `~/.coral/memory/`;
-each layer is a flat directory of `*.md` files plus a `MEMORY.md` index.
-
-## When SPS injects this for you (pipeline mode)
-
-When a card is dispatched, `StageEngine.buildStagePrompt` calls
-`buildFullMemoryContext({ project, cardSeq })` and folds the result into the prompt's
-`knowledge` section — **before** the task description. So inside a card, **you
-already see relevant memory**; you don't need to `cat` it.
-
-What you still need to do:
-1. **Read more context if relevant** — the auto-inject only includes the headline
-   index + recent items. To see a specific memory file, `cat` it.
-2. **Write new memories when discovery happens** — covered below.
-
-In `sps agent` (harness) mode, memory is **not** auto-injected. Use the `cat`
-patterns at the bottom to pull what you need.
-
-## Three layers
-
-| Layer | Path | Scope | When to use |
-|---|---|---|---|
-| **User** | `~/.coral/memory/user/` | Cross-project preferences | Coding style, language, workflow habits ("prefers Chinese comments", "uses strict TypeScript") |
-| **Agent** | `~/.coral/memory/agents/<agentId>/` | Per daemon instance / per-agent identity | User-interaction patterns you observed, communication preferences specific to this agent ↔ user pair |
-| **Project** | `~/.coral/memory/projects/<project-name>/` | Per project | Conventions, architecture decisions, lessons learned, external resource pointers |
-
-To detect which project the cwd belongs to: scan `~/.coral/projects/*/conf` for a
-matching `PROJECT_DIR=`. Pipeline workers always know via `$SPS_PROJECT` env var.
-
-## File format
-
-```markdown
----
-name: Short title
-description: One-line summary (used by index + future fuzzy search)
-type: convention | decision | lesson | reference
----
-
-Body. For decision/lesson types, include:
-
-**Why:** the reason / past incident driving this
-**Scope:** where this applies (file glob, module, role, ...)
-```
-
-Filename = slugified `name` (lowercase, hyphens). The CLI does this for you; if
-writing by hand, keep it under 50 chars.
-
-## Memory types
-
-| Type | Decay | Use for |
-|---|---|---|
-| `convention` | Never | Project rules, coding standards, naming conventions |
-| `decision` | Slow | Architecture choices, technology selections |
-| `lesson` | 30 days | Pitfalls, debugging discoveries, things that broke |
-| `reference` | Never | Pointers to external dashboards, runbooks, dependencies |
-
-`convention` and `reference` never expire; `decision` is auto-deprioritized after
-months of no touch; `lesson` decays at 30 days unless re-read.
-
-## Index file (`MEMORY.md`)
-
-Each layer's directory has a `MEMORY.md` index — one line per memory file:
-
-```markdown
-- [API uses camelCase](api-naming.md) — All REST endpoints use camelCase
-- [Auth middleware location](auth-middleware.md) — middleware/auth.ts; not in routes
-```
-
-After writing a memory file, **always** append (or update) one line in the
-sibling `MEMORY.md`. The auto-injector reads `MEMORY.md` first to decide what to
-load.
-
-## When to read
-
-- At the start of a card or task — auto-injected for you in pipeline mode
-- Before answering a question that could conflict with prior decisions
-- When the user says "do you remember", "we agreed", "我们之前说过"
-- Before recommending a pattern that might violate a known convention
-
-```bash
-# Project memory index
-cat ~/.coral/memory/projects/<project>/MEMORY.md 2>/dev/null
-
-# User preferences (always-applicable)
-cat ~/.coral/memory/user/MEMORY.md 2>/dev/null
-
-# Specific memory file
-cat ~/.coral/memory/projects/<project>/api-naming.md
-```
-
-## When to write
-
-Only when **all** are true:
-- The fact is **non-obvious** (not derivable from `git log`, code, or CLAUDE.md)
-- It will be **reusable** across future sessions / cards
-- It's **stable enough** to outlive the current task
-
-Trigger words / situations:
-| Situation | Type |
-|---|---|
-| User states a project rule or preference | `convention` |
-| Architectural choice discussed and agreed | `decision` |
-| Bug fixed where the root cause was sneaky / non-obvious | `lesson` |
-| User points to an external dashboard, runbook, or repo | `reference` |
-| You observe a user communication style worth keeping | agent-layer note |
-
-**Most cards do NOT need memory.** If you're unsure → don't write. Memory is
-expensive (read budget on every future card). Empty growth is worse than no
-growth.
-
-## Writing patterns
-
-### Via CLI (recommended for project memories)
-
-```bash
-sps memory add <project> \
-  --type convention \
-  --name "API uses camelCase" \
-  --description "All REST endpoints use camelCase naming" \
-  --body "REST API endpoints use camelCase. No snake_case.\n\n**Why:** Frontend SDK auto-generates types from API schema."
-```
-
-The CLI:
-- Slugifies name → filename
-- Writes the file with proper frontmatter
-- Appends/updates the line in `MEMORY.md`
-
-### By hand (for user / agent layer)
-
-```bash
-mkdir -p ~/.coral/memory/projects/my-project
-cat > ~/.coral/memory/projects/my-project/api-naming.md << 'EOF'
----
-name: API uses camelCase
-description: All REST endpoints use camelCase naming
-type: convention
----
-
-REST API endpoints use camelCase. No snake_case.
-**Why:** Frontend SDK auto-generates types from API schema.
-EOF
-
-# Update index — keep entry one line, ≤ 100 chars
-echo '- [API naming](api-naming.md) — camelCase for all REST endpoints' \
-  >> ~/.coral/memory/projects/my-project/MEMORY.md
-```
-
-## What NOT to save
-
-- **Code structure / file paths** — derivable from `Read` / `Glob`
-- **Git history / blame** — use `git log`
-- **Temporary debugging state** — use the conversation
-- **Anything already in CLAUDE.md or `docs/`** — don't duplicate
-- **Card or task state** — that's runtime, not knowledge
-- **Wiki content** — if it belongs in structured knowledge (modules / decisions /
-  lessons cross-linked), use the **wiki-update skill** instead. Memory is for
-  ad-hoc / personal facts; Wiki is for structured project knowledge with
-  cross-references and 5-layer prompt injection.
-
-## CLI commands
-
-```bash
-sps memory list <project>                  # show project memory index
-sps memory list                            # global view (user)
-sps memory list --agent <agentId>          # include agent layer
-
-sps memory context <project>               # ★ preview full inject (debug)
-sps memory context <project> --card <seq>  # card-scoped (matches Worker prompt)
-
-sps memory add <project> \
-  --type convention \
-  --name "title" \
-  --description "one-line summary" \
-  --body "content"
-```
-
-## Memory vs Wiki — pick the right tool
-
-| Need | Use |
-|---|---|
-| User said "remember I prefer ..." | Memory (`user` or `project` layer) |
-| Decision recorded in a card review | Could be either; prefer **wiki/decisions/** if it's about the project's architecture (linkable, surfacable to all future cards), memory for personal/team workflow choices |
-| Bug fix with non-obvious root cause | **wiki/lessons/** (cross-linked, structured) — memory `lesson` is fallback when wiki not enabled |
-| Module purpose / API contract summary | **wiki/modules/** |
-| External dashboard URL | Memory `reference` |
-| Personal coding style note | Memory (`user`) |
-
-**Wiki requires `WIKI_ENABLED=true` in project conf** (v0.51+). When wiki is on,
-prefer it for project-level structured knowledge — it gets cross-references,
-linting, and 5-layer prompt injection. Memory remains the right place for ad-hoc
-flat facts and personal preferences.
-
-## Honesty rules
-
-- Don't invent memories. Only write what the user said or you genuinely discovered.
-- Don't echo what's already in `MEMORY.md` index.
-- If a memory turns out wrong later, **edit or delete it** — don't pile a
-  contradiction on top.
-- Stale `lesson` (>30 days, no recent reference) — feel free to delete or
-  promote to `convention` if it's hardened into project rule.