@ericrisco/rsc 0.1.51 → 0.1.52

package/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.1.51",
+  "version": "0.1.52",
   "counts": {
     "skills": 258
   },
@@ -1889,7 +1889,7 @@
     },
     {
       "id": "gamedev-multiplayer",
-      "description": "Use when adding multiplayer, netcode, or replication to a game — syncing players/state across a network, online co-op or PvP, client-server vs peer-to-peer, server-authoritative design, client-side prediction + server reconciliation, snapshot interpolation, lag compensation, tick/netrate, and per-engine wiring: Godot 4.x MultiplayerSpawner/MultiplayerSynchronizer/@rpc/ENetMultiplayerPeer/set_multiplayer_authority, Unity Netcode for GameObjects (NetworkObject/NetworkBehaviour/NetworkVariable/[Rpc]/ServerRpc/ClientRpc), Unreal Actor replication (Replicated/ReplicatedUsing, Server/Client/NetMulticast RPCs, relevancy). Triggers: 'how do I sync players', 'client and server desync', 'players rubber-band or teleport', 'who has authority', 'laggy movement', 'cheater set their own health'. NOT single-player gameplay, AI, or input (route to engine skill godot/unity/unreal), and NOT matchmaking, dedicated-server hosting, or backend infra (route to deployment).",
+      "description": "Use when adding multiplayer or netcode to a game — client-server vs P2P, server authority and anti-cheat, state replication vs RPCs, prediction and reconciliation, lag compensation, plus Godot 4 / Unity NGO / Unreal wiring. NOT single-player gameplay (that is `godot`, `unity`, `unreal`), NOT matchmaking or server hosting (that is `deployment`).",
       "tags": [
         "multiplayer",
         "netcode",
@@ -1910,7 +1910,7 @@
     },
     {
       "id": "gamedev-pathing",
-      "description": "Use when implementing AI navigation or pathfinding in a game - moving enemies/NPCs/units toward goals, \\\"how do enemies navigate the level\\\", A*/Dijkstra/JPS/HPA* search, choosing grid vs waypoint-graph vs navmesh, baking a navmesh and tuning agent radius/height, off-mesh/nav links, dynamic obstacles and re-baking, steering (seek/flee/arrive/pursue/wander/path-following/flocking), local avoidance (RVO/ORCA, crowds), and flow fields for many agents to one goal. Per-engine: Godot 4.x (NavigationServer2D/3D, NavigationRegion, NavigationAgent, get_next_path_position), Unity (NavMeshAgent + NavMeshObstacle + AI Navigation baking), Unreal (RecastNavMesh + AIController + Behavior Trees/EQS). Triggers: \\\"my enemies get stuck\\\", \\\"units clump together\\\", \\\"navmesh not updating\\\", \\\"agentes se atascan\\\". NOT physics/rigidbody collision response or character-controller tuning (gamedev-physics), and NOT high-level enemy AI behaviour design like aggro/states/difficulty (game-design).",
+      "description": "Use when making NPCs, enemies, or units navigate a level — grid vs waypoint vs navmesh, A*/JPS, navmesh baking and agent radius, off-mesh links, steering, RVO crowd avoidance, and flow fields in Godot 4.x, Unity, Unreal. NOT collision response or character controllers (that is gamedev-physics), NOT aggro or difficulty design (that is game-design).",
       "tags": [
         "pathfinding",
         "navmesh",
@@ -4175,7 +4175,7 @@
     },
     {
       "id": "security-scan",
-      "description": "Use when running automated security scanners over a repo or app and turning the raw output into a triaged, ranked, gate-able report: scan for vulnerabilities before shipping, audit dependencies/lockfiles for known CVEs, find secrets committed to the tree or git history, run SAST, or wire scanners into CI. Triggers: 'scan this repo for vulnerabilities', 'check my package-lock for CVEs', 'did anyone commit AWS keys', 'scan git history for leaked keys', 'my lockfile has a transitive CVE', 'is aquasecurity/trivy-action@latest safe', 'set up Semgrep/gitleaks to fail CI', 'escanea el repo en busca de vulnerabilidades', 'audita las dependencias', 'analitza les dependències'. NOT threat-modeling, OWASP design reasoning, or authoring the fix (that is secure-coding).",
+      "description": "Use when automated scanners drive a security sweep of a repo or app — SAST, dependency/lockfile CVEs, secrets in the tree or git history, IaC misconfig — and the raw output has to become one deduped, exploitability-ranked report CI can gate on. NOT threat-modeling, OWASP design reasoning, or hand-authoring the fix (that is `secure-coding`).",
       "tags": [
         "security",
         "sast",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ericrisco/rsc",
-  "version": "0.1.51",
+  "version": "0.1.52",
   "description": "Eric Risco's agent-skills catalog as a granular, self-recommending CLI installer.",
   "type": "module",
   "bin": {

package/skills/gamedev-multiplayer/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gamedev-multiplayer
-description: "Use when adding multiplayer, netcode, or replication to a game — syncing players/state across a network, online co-op or PvP, client-server vs peer-to-peer, server-authoritative design, client-side prediction + server reconciliation, snapshot interpolation, lag compensation, tick/netrate, and per-engine wiring: Godot 4.x MultiplayerSpawner/MultiplayerSynchronizer/@rpc/ENetMultiplayerPeer/set_multiplayer_authority, Unity Netcode for GameObjects (NetworkObject/NetworkBehaviour/NetworkVariable/[Rpc]/ServerRpc/ClientRpc), Unreal Actor replication (Replicated/ReplicatedUsing, Server/Client/NetMulticast RPCs, relevancy). Triggers: 'how do I sync players', 'client and server desync', 'players rubber-band or teleport', 'who has authority', 'laggy movement', 'cheater set their own health'. NOT single-player gameplay, AI, or input (route to engine skill godot/unity/unreal), and NOT matchmaking, dedicated-server hosting, or backend infra (route to deployment)."
+description: "Use when adding multiplayer or netcode to a game — client-server vs P2P, server authority and anti-cheat, state replication vs RPCs, prediction and reconciliation, lag compensation, plus Godot 4 / Unity NGO / Unreal wiring. NOT single-player gameplay (that is `godot`, `unity`, `unreal`), NOT matchmaking or server hosting (that is `deployment`)."
 tags: [multiplayer, netcode, replication, networking, prediction, authority]
 recommends: [godot, unity, unreal, gamedev-physics]
 profiles: [full]
@@ -14,6 +14,16 @@ topology, put authority in the right place, replicate the right state, and hide
 opening the door to cheaters. This skill owns the *networking* decisions; the engine skills own
 the local gameplay those decisions sit on top of.
 
+Route elsewhere when the ask is not netcode:
+
+| The ask | Route to | Why not here |
+| --- | --- | --- |
+| Single-player movement, AI, input, animation, save files | [`godot`](../godot/SKILL.md) / [`unity`](../unity/SKILL.md) / [`unreal`](../unreal/SKILL.md) | The engine skill owns local gameplay; no network dimension. |
+| Physics determinism, collision, character controllers | [`gamedev-physics`](../gamedev-physics/SKILL.md) | Netcode *consumes* determinism; it does not own the physics fix. |
+| Matchmaking, lobby backend, dedicated-server hosting, relays, DB, game-server CI | [`deployment`](../deployment/SKILL.md) | Running the fleet, not designing the in-game net layer. |
+| Web realtime — chat, presence, a generic WebSocket app | [`webhooks`](../webhooks/SKILL.md) | Not a game world/simulation. |
+| General threat modeling, authz review | [`secure-coding`](../secure-coding/SKILL.md) | This skill keeps only the game-specific anti-cheat controls. |
+
 ## Version contract — read first
 
 Target the current APIs. **Never emit these deprecated / removed APIs:**
@@ -30,19 +40,6 @@ community UNet-like fork), say so; this skill targets first-party NGO. In NGO 2.
 `[ServerRpc]` / `[ClientRpc]` still compile (and enforce `…ServerRpc` / `…ClientRpc` method-name
 suffixes) — cover them but prefer the unified form on new code.
 
-## Fires on / When NOT
-
-**Fires on:** "how do I sync players", replication, netcode, RPCs, authority, online co-op or PvP,
-"client and server disagree", rubber-banding / teleporting players, prediction & reconciliation,
-lag compensation, tick rate / send rate, spawning networked objects, "the client can cheat".
-
-**When NOT (route away):**
-
-- Single-player movement, AI, input, animation, save files → the engine skill: `godot`, `unity`, `unreal`.
-- Physics determinism, collision, character controllers → `gamedev-physics` (netcode *consumes* it).
-- Matchmaking service, lobby backend, dedicated-server hosting/orchestration, relays, DB → `deployment`.
-- Web realtime (chat, presence, generic WebSocket app) that is not a game world → `webhooks` / a backend skill.
-
 ## Topologies & authority
 
 Pick the topology first; everything else follows from it.
@@ -61,7 +58,8 @@ requests), never results. **Never trust the client:** the client cannot set its
 score, currency, or hit results — it *asks*, the server *decides*, everyone else *observes*. A client
 that says "I moved to X / I did 40 damage / I have 999 gold" is either lagging or cheating; treat both
 the same. The one thing a client legitimately owns is its own input and, by convention, cosmetic-only
-state. See references/prediction-and-latency.md for how to keep this responsive.
+state. See **[references/prediction-and-latency.md](references/prediction-and-latency.md)** for how to
+keep this responsive.
 
 ## State replication vs RPCs
 
@@ -88,7 +86,7 @@ is the #1 cause of "it works for the host but not the client" bugs.
 ## The hard problems
 
 Latency (round-trip time, RTT) is the enemy; jitter and packet loss make it worse. Four techniques,
-covered in depth in **references/prediction-and-latency.md**:
+covered in depth in **[references/prediction-and-latency.md](references/prediction-and-latency.md)**:
 
 1. **Client-side prediction** — the owning client applies its own input *immediately* instead of waiting a
    full RTT for the server, so local movement feels instant.
@@ -140,7 +138,8 @@ func request_fire(target: Vector3) -> void:
 - `MultiplayerSynchronizer` streams a chosen property list (position, etc.) from the authority to peers;
   set its replication interval and visibility (`set_visibility_for(peer, bool)`) to scope bandwidth.
 - `MultiplayerSpawner` replicates instancing of scenes under a path so late peers get existing objects.
-- Details, prediction wiring, and the full player-scene pattern: **references/godot-high-level-multiplayer.md**.
+- Details, prediction wiring, and the full player-scene pattern:
+  **[references/godot-high-level-multiplayer.md](references/godot-high-level-multiplayer.md)**.
 
 ### Unity — Netcode for GameObjects
 
@@ -168,7 +167,8 @@ public class Player : NetworkBehaviour {
 - `NetworkVariable<T>(value, readPerm, writePerm)` — `NetworkVariableWritePermission.Server` (default) vs
   `.Owner`; subscribe via `OnValueChanged`. Use `NetworkTransform` for pos/rot sync.
 - Prefer the unified `[Rpc(SendTo.X)]`; legacy `[ServerRpc]`/`[ClientRpc]` still work but need the
-  method-name suffixes. Full patterns: **references/unity-and-unreal-netcode.md**.
+  method-name suffixes. Full patterns:
+  **[references/unity-and-unreal-netcode.md](references/unity-and-unreal-netcode.md)**.
 
 ### Unreal — Actor replication
 
@@ -196,7 +196,8 @@ void AMyPawn::GetLifetimeReplicatedProps(TArray<FLifetimeProperty>& Out) const {
 - **Relevancy** keeps bandwidth sane: `NetCullDistanceSquared`, `bAlwaysRelevant`, `IsNetRelevantFor`, and
   dormancy (`SetNetDormancy`) stop replicating actors a client can't perceive. Movement replicates via
   `CharacterMovementComponent`, which already does prediction+reconciliation for you.
-- RepNotify vs Multicast, GAS/Network Prediction notes: **references/unity-and-unreal-netcode.md**.
+- RepNotify vs Multicast, GAS/Network Prediction notes:
+  **[references/unity-and-unreal-netcode.md](references/unity-and-unreal-netcode.md)**.
 
 ## Security / anti-cheat basics
 
@@ -219,32 +220,18 @@ void AMyPawn::GetLifetimeReplicatedProps(TArray<FLifetimeProperty>& Out) const {
 - Always test **with simulated latency and packet loss**, not just on localhost — localhost hides every
   prediction/reconciliation bug. Test the client path, not only the host's.
 
-## Guardrails / gotchas
-
-- Localhost is a liar: 0 ms RTT masks the exact desync/rubber-band bugs your players will hit. Inject lag.
-- Don't RPC state you need to stay consistent — replicate it (an unreliable event drop is permanent).
-- Don't tie simulation to render FPS; fixed timestep on the sim, interpolate on the render.
-- The listen-server host is a client too — guard authority-only logic behind an `is_server`/`HasAuthority`
-  check or it double-executes on the host.
-- Wrong ownership = "works for host, breaks for client." Set authority/ownership explicitly on spawn.
-- Replicating everything, every tick, to everyone melts bandwidth — scope by relevancy/visibility and rate.
-
-## Related skills
-
-- **`godot` / `unity` / `unreal`** — the engine your game runs in; owns local gameplay, input, scenes, build.
-- **`gamedev-physics`** — determinism, collision, character controllers; netcode replicates its results and
-  needs its determinism for prediction/rollback.
-- **`deployment`** — dedicated-server hosting, matchmaking/lobby backend, relays, and CI for game servers.
-- **`secure-coding`** — general threat modeling; this skill keeps only the game-specific anti-cheat controls.
-
-## Checklist
-
-- [ ] Topology chosen (dedicated / listen / P2P) and the *same code* runs on server and listen host.
-- [ ] Server-authoritative: clients send intent only; server validates and owns all gameplay state.
-- [ ] Each networked value is either replicated (state/nouns) or an RPC (events/verbs) — not the wrong one.
-- [ ] Ownership/authority set explicitly per object; authority-only logic guarded on the host.
-- [ ] Owning-client movement predicted + reconciled; remote entities snapshot-interpolated.
-- [ ] Hitscan uses server-side lag compensation; simulation on a fixed tick, decoupled from render FPS.
-- [ ] Only need-to-know state replicated per client (relevancy/visibility scoped); RPCs rate-limited.
-- [ ] Tested with simulated latency + packet loss across multiple instances, exercising the client path.
-- [ ] No banned APIs (UNet/HLAPI, Godot 3.x `master`/`puppet`/`rset`, `Tick`-polled Unreal replication).
+## Anti-patterns
+
+| Anti-pattern | Why it bites | Do instead |
+| --- | --- | --- |
+| Writing net code before the topology is chosen | Authority and cost model change everything downstream | Pick dedicated / listen / P2P first, and make the *same code* run on server and listen host |
+| Trusting a client-reported result (health, position, score, hit) | That is the cheat surface, and lag looks identical to cheating | Clients send intent only; the server validates and owns all gameplay state |
+| RPCing state that must stay consistent | A dropped unreliable event desyncs that client permanently | Replicate nouns (state), RPC verbs (events) — replicated values self-correct |
+| Ownership/authority left implicit | The #1 cause of "works for the host, breaks for the client" | Set authority/ownership explicitly on spawn |
+| Forgetting the listen-server host is also a client | Authority-only logic double-executes on the host | Guard it behind `is_server()` / `HasAuthority()` |
+| Making the owning client wait a full RTT for its own input | Movement feels sluggish and unresponsive | Predict locally + reconcile; snapshot-interpolate remote entities |
+| Client-side hit detection for hitscan | Trivially spoofed, and unfair to the higher-ping shooter | Server-side lag compensation: rewind to the shooter's render time |
+| Tying simulation to render FPS | Sim diverges between machines at different frame rates | Fixed timestep on the sim, interpolate on the render |
+| Replicating everything, every tick, to everyone | Melts bandwidth and leaks wallhack fuel | Scope by relevancy/visibility and send rate; rate-limit RPCs |
+| Testing only on localhost | 0 ms RTT masks the exact desync/rubber-band bugs players will hit | Inject latency + packet loss across instances, exercising the client path |
+| Emitting UNet/HLAPI, Godot 3.x `master`/`puppet`/`rset`, or `Tick`-polled Unreal replication | Removed or legacy — it will not compile or will silently underperform | The current APIs in the version contract above |

package/skills/gamedev-pathing/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gamedev-pathing
-description: "Use when implementing AI navigation or pathfinding in a game - moving enemies/NPCs/units toward goals, \"how do enemies navigate the level\", A*/Dijkstra/JPS/HPA* search, choosing grid vs waypoint-graph vs navmesh, baking a navmesh and tuning agent radius/height, off-mesh/nav links, dynamic obstacles and re-baking, steering (seek/flee/arrive/pursue/wander/path-following/flocking), local avoidance (RVO/ORCA, crowds), and flow fields for many agents to one goal. Per-engine: Godot 4.x (NavigationServer2D/3D, NavigationRegion, NavigationAgent, get_next_path_position), Unity (NavMeshAgent + NavMeshObstacle + AI Navigation baking), Unreal (RecastNavMesh + AIController + Behavior Trees/EQS). Triggers: \"my enemies get stuck\", \"units clump together\", \"navmesh not updating\", \"agentes se atascan\". NOT physics/rigidbody collision response or character-controller tuning (gamedev-physics), and NOT high-level enemy AI behaviour design like aggro/states/difficulty (game-design)."
+description: "Use when making NPCs, enemies, or units navigate a level — grid vs waypoint vs navmesh, A*/JPS, navmesh baking and agent radius, off-mesh links, steering, RVO crowd avoidance, and flow fields in Godot 4.x, Unity, Unreal. NOT collision response or character controllers (that is gamedev-physics), NOT aggro or difficulty design (that is game-design)."
 tags: [pathfinding, navmesh, navigation, steering, a-star]
 recommends: [godot, unity, unreal, gamedev-physics]
 profiles: [full]
@@ -102,7 +102,8 @@ Combine either as a **weighted sum** (simple) or **priority/arbitration** (avoid
 **Local avoidance (RVO / ORCA):** each agent picks a velocity that is collision-free assuming neighbours
 share the burden (*reciprocal* — hence no oscillating "dance"). This is avoidance, **not** collision
 *response*: it changes intended velocity *before* moving; the physics/collision solver is a separate,
-last-resort backstop (→ `gamedev-physics`). For dense crowds use the engine's crowd/avoidance system.
+last-resort backstop (→ [`gamedev-physics`](../gamedev-physics/SKILL.md)). For dense crowds use the
+engine's crowd/avoidance system.
 
 **Flow fields** — for **many agents → one (or few) goals** (RTS swarm, tower-defense creeps): run one
 **Dijkstra from the goal** over the grid to build a cost/integration field, derive a per-cell direction
@@ -182,30 +183,26 @@ AICon->MoveToActor(TargetActor, /*AcceptanceRadius*/ 50.f);   // or MoveToLocati
 4. Costs/holes: **`NavModifierVolume`** + `NavArea` classes. Off-mesh: **`NavLinkProxy`**. Crowd
    avoidance: enable the **Detour Crowd** manager (or `DetourCrowdAIController`) for RVO on many agents.
 
-> High-level BT *design* (states, aggro, difficulty) is `game-design`; this skill wires the BT's
+> High-level BT *design* (states, aggro, difficulty) is [`game-design`](../game-design/SKILL.md); this skill wires the BT's
 > movement/EQS tasks to navigation, not the decision tree's semantics.
 
-## Guardrails / gotchas
+## Anti-patterns
 
-- **Agent radius mismatch** is the top "stuck in doorways / clipping walls" cause — bake with the real radius.
-- Bake covers **static** geometry; runtime-spawned meshes need a rebake, a carving obstacle, or a nav link.
-- Path returns empty when start/end are **off the navmesh** or in disconnected islands — snap to nearest poly and check reachability first.
-- Avoidance (RVO) ≠ collision (physics). Agents can still overlap under pressure; that is expected, not a physics bug.
-- Off-mesh links are **directional and manual** — a jump-down link does not imply a jump-up link.
-- Smooth grid paths (funnel / string-pull) or agents walk visible zig-zag staircases.
-
-## Anti-patterns / rationalizations → STOP
-
-| Rationalization | Reality / do instead |
+| Anti-pattern | Do instead |
 | --- | --- |
-| "Just A* every frame, it's fine" | Melts CPU at scale; path on goal-change, steer between frames. |
-| "One navmesh bake works for every unit" | Radius/height differ; bake per agent size or use agent-type profiles. |
-| "Agents clip through each other — physics bug" | Missing **local avoidance**; enable RVO/crowd, that's the navigation layer. |
-| "Navmesh doesn't see my spawned wall" | Static bake; set Dynamic/rebake, or add a carving obstacle/nav link. |
-| "I'll grid-search my own A* in Unity/Unreal" | Reinvents the built-in navmesh; use `NavMeshAgent` / `AAIController::MoveTo`. |
-| "500 zombies each run A* to the player" | That's a **flow field**: one Dijkstra from the goal, agents sample cells. |
-| "Set `agent.destination` and read the path same frame" | Path is async (`pathPending`); gate on it before trusting `remainingDistance`. |
-| "Bigger heuristic = smarter" | Over-estimating `h` breaks A* optimality; keep it admissible (or weight it *knowingly*). |
+| Running a full A* every frame | Path on goal-change (or throttled) and steer between frames — per-frame search melts CPU at scale. |
+| One navmesh bake shared by every unit | Radius/height differ; bake per agent size or use agent-type profiles. |
+| Baking with a placeholder agent radius | Bake with the real radius — mismatch is the top "stuck in doorways / clipping walls" cause. |
+| Treating agents that clip through each other as a physics bug | Missing **local avoidance**; enable RVO/crowd — that is the navigation layer. |
+| Expecting RVO to prevent every overlap | Avoidance ≠ collision. Agents can still overlap under pressure; that is expected, not a physics bug. |
+| Expecting a **static** bake to see runtime-spawned geometry | Set Dynamic runtime generation / rebake, or add a carving obstacle or nav link. |
+| Hand-rolling your own grid A* in Unity/Unreal | Reinvents the built-in navmesh; use `NavMeshAgent` / `AAIController::MoveTo`. |
+| 500 zombies each running A* to the player | That's a **flow field**: one Dijkstra from the goal, agents sample cells. |
+| Setting `agent.destination` and reading the path the same frame | Path is async (`pathPending`); gate on it before trusting `remainingDistance`. |
+| Inflating `h` because a bigger heuristic seems smarter | Over-estimating `h` breaks A* optimality; keep it admissible (or weight it *knowingly*). |
+| Trusting a path query that came back empty | Start/end are **off the navmesh** or in disconnected islands — snap to the nearest poly and check reachability first. |
+| Assuming an off-mesh link works both ways | Links are **directional and manual** — a jump-down link does not imply a jump-up link. |
+| Feeding raw grid paths to the mover | Smooth them (funnel / string-pull) or agents walk visible zig-zag staircases. |
 
 ## Related skills
 
@@ -213,7 +210,7 @@ AICon->MoveToActor(TargetActor, /*AcceptanceRadius*/ 50.f);   // or MoveToLocati
 - [`unity`](../unity/SKILL.md) — Unity/C# project setup; here for the NavMesh + AI Navigation package details.
 - [`unreal`](../unreal/SKILL.md) — UE5/Blueprint/C++; here for RecastNavMesh + AIController/BT/EQS wiring.
 - [`gamedev-physics`](../gamedev-physics/SKILL.md) — collision *response*, rigidbodies, character controllers; steering decides intended velocity, physics resolves the contact.
-- `game-design` — high-level enemy behaviour, aggro, encounter/difficulty design (what the AI *decides*, not how it *moves*).
+- [`game-design`](../game-design/SKILL.md) — high-level enemy behaviour, aggro, encounter/difficulty design (what the AI *decides*, not how it *moves*).
 
 ## Checklist
 
@@ -234,9 +231,3 @@ the project's navigation decisions in `02-DOCS/wiki/stack/gamedev-pathing.md` (i
 `02-DOCS/wiki/index.md`): engine + version, chosen representation, bake settings (agent sizes, cell
 size), avoidance/crowd choice, custom links/areas. Read it first on every use; bump its `Updated` date
 when a convention changes. No `02-DOCS/` layer? Skip silently — conventions are *recorded, not gated*.
-
-## See Also — local references (read when)
-
-- `references/search-algorithms.md` — representations, A*/Dijkstra/JPS/HPA* pseudocode, heuristics & admissibility, tie-breaking, any-angle, funnel smoothing.
-- `references/navmesh-workflow.md` — bake-parameter table, areas/costs, off-mesh links, obstacles vs carving vs partial rebake, per-engine baking, debugging.
-- `references/steering-and-avoidance.md` — steering primitives, path following, boids weights, RVO/ORCA intuition, crowds, flow-field construction.

package/skills/security-scan/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: security-scan
-description: "Use when running automated security scanners over a repo or app and turning the raw output into a triaged, ranked, gate-able report: scan for vulnerabilities before shipping, audit dependencies/lockfiles for known CVEs, find secrets committed to the tree or git history, run SAST, or wire scanners into CI. Triggers: 'scan this repo for vulnerabilities', 'check my package-lock for CVEs', 'did anyone commit AWS keys', 'scan git history for leaked keys', 'my lockfile has a transitive CVE', 'is aquasecurity/trivy-action@latest safe', 'set up Semgrep/gitleaks to fail CI', 'escanea el repo en busca de vulnerabilidades', 'audita las dependencias', 'analitza les dependències'. NOT threat-modeling, OWASP design reasoning, or authoring the fix (that is secure-coding)."
+description: "Use when automated scanners drive a security sweep of a repo or app — SAST, dependency/lockfile CVEs, secrets in the tree or git history, IaC misconfig — and the raw output has to become one deduped, exploitability-ranked report CI can gate on. NOT threat-modeling, OWASP design reasoning, or hand-authoring the fix (that is `secure-coding`)."
 tags: [security, sast, sca, secrets, scanning, owasp]
 recommends: [secure-coding, github-actions, verify]
 origin: risco
@@ -15,40 +15,28 @@ finding comes from a **tool run**, not a hunch — if you are reasoning about a
 design or hand-writing a fix, that is [`secure-coding`](../secure-coding/SKILL.md),
 not this skill.
 
-Your job is orchestration + triage. Not eyeballing code, not authoring patches.
-
-## Operating posture
-
-- **Read-only by default.** Scan, triage, report. Apply fixes (version bumps,
-  rotation, `.gitignore` edits) only when the user asks. *Why:* a security sweep
-  that silently mutates the tree destroys the evidence and the trust.
-- **Machine-first.** Every finding must trace to a scanner run with a `ruleId`
-  and a source location. *Why:* "I think this looks injectable" is design
-  reasoning — route it to `secure-coding`. This skill ships reproducible output.
-- **Pin and verify your scanners.** Pin exact versions, verify checksums/SHAs,
-  never pull `@latest` GitHub Actions. *Why:* in **March 2026 Trivy was
-  supply-chain compromised** — malicious releases `v0.69.4/0.69.5/0.69.6` and a
-  hijacked `aquasecurity/trivy-action` exfiltrated CI secrets. Your scanner runs
-  with repo + CI-secret access; an unpinned scanner is itself the attack surface.
-- **SARIF everything.** Make every tool emit SARIF (or JSON you normalize to it).
-  *Why:* a common schema is what lets you merge four tools, dedupe, and feed one
-  artifact into CI instead of four incompatible logs.
-- **Triage before you report.** Raw scanner output is high-noise. Rank by
-  exploitability and dedupe overlap; never dump 400 raw findings on the user.
-
-## The four scan classes
-
-| Class | What it catches | Primary tool | Backup / fast pass |
-|---|---|---|---|
-| **SAST** | injection, XSS, path traversal in *first-party* code | Semgrep | — |
-| **SCA / deps** | known CVEs in dependency manifests + lockfiles | osv-scanner | `npm audit`, `pip-audit` |
-| **Secrets** | credentials in the tree **or git history** | gitleaks (speed) | TruffleHog (depth + live verification) |
-| **Misconfig / IaC** | Dockerfile, k8s, Terraform, exposed config | Trivy `config` | Semgrep rulesets |
-
-### Tool selection by ecosystem
-
-Pick by what is in the repo. This is the real branch point — match the tool to
-the manifest, do not run everything everywhere.
+Your job is orchestration + triage: every finding traces to a scanner run with a
+`ruleId` and a source location, so the output is reproducible. Not eyeballing
+code, not authoring patches.
+
+**Read-only by default.** Scan, triage, report. Apply fixes (version bumps,
+rotation, `.gitignore` edits) only when the user asks — a security sweep that
+silently mutates the tree destroys the evidence and the trust.
+
+**Pin and verify your scanners.** Exact versions, verified checksums/SHAs, never
+`@latest` GitHub Actions. In **March 2026 Trivy was supply-chain compromised** —
+malicious releases `v0.69.4/0.69.5/0.69.6` and a hijacked
+`aquasecurity/trivy-action` exfiltrated CI secrets. Your scanner runs with repo +
+CI-secret access; an unpinned scanner is itself the attack surface.
+
+## Scan classes and tool selection
+
+Four classes: **SAST** (injection, XSS, path traversal in *first-party* code),
+**SCA / deps** (known CVEs in dependency manifests + lockfiles), **Secrets**
+(credentials in the tree **or git history**), **Misconfig / IaC** (Dockerfile,
+k8s, Terraform, exposed config). Pick tools by what is in the repo. This is the
+real branch point — match the tool to the manifest, do not run everything
+everywhere.
 
 | Repo contains | SAST | SCA | Secrets | Misconfig |
 |---|---|---|---|---|
@@ -56,15 +44,17 @@ the manifest, do not run everything everywhere.
 | Python (`poetry.lock`/`requirements.txt`) | Semgrep | osv-scanner + `pip-audit` (fast) | gitleaks → TruffleHog | Trivy |
 | Go (`go.mod`/`go.sum`) | Semgrep | osv-scanner (+ `govulncheck` for reachability) | gitleaks | Trivy |
 | Containers (`Dockerfile`, images) | — | Trivy `fs`/`image` | Trivy `--scanners secret` | Trivy `config` |
-| IaC (Terraform/k8s/Helm) | Semgrep (IaC rules) | — | gitleaks | Trivy `config` |
+| IaC (Terraform/k8s/Helm) | Semgrep (IaC rules) | — | gitleaks | Trivy `config`, Semgrep rulesets |
 | Monorepo (mixed) | Semgrep `auto` | osv-scanner (multi-ecosystem) | gitleaks → TruffleHog | Trivy |
 
 Full install (pinned), flag matrix, and suppression syntax: `references/tools.md`.
 
 ## Run recipes
 
-All recipes emit SARIF or JSON so they merge into one report. **Pin the version
-shown** — the placeholders below mark where to lock an exact tag/digest.
+All recipes emit SARIF (or JSON you normalize to it) — a common schema is what
+lets you merge four tools, dedupe, and feed one artifact into CI instead of four
+incompatible logs. **Pin the version shown**; the placeholders below mark where
+to lock an exact tag/digest.
 
 ### SAST — Semgrep
 
@@ -107,10 +97,10 @@ gitleaks detect --redact --report-format sarif --report-path secrets.sarif
 trufflehog git file://. --only-verified --json > trufflehog.json
 ```
 
-### Misconfig / IaC — Trivy (PINNED — see the caveat)
+### Misconfig / IaC — Trivy (PINNED — see the caveat above)
 
 Trivy scans filesystems, images, and IaC and finds transitive CVEs `npm audit`
-misses. After the March 2026 compromise, **never** run an unpinned Trivy.
+misses.
 
 ```bash
 # Pin the EXACT version (NOT v0.69.4/.5/.6 — those were the malicious releases).
@@ -200,17 +190,17 @@ Emit one `security-scan-report.json` — the machine-checkable contract CI gates
 
 ## Anti-patterns
 
-| Rationalization | Reality |
+| Anti-pattern | Do instead |
 |---|---|
-| "Pull `aquasecurity/trivy-action@latest`, it's official." | March 2026: a hijacked tag stole CI secrets. Pin a full SHA, verify provenance. |
-| "Every scanner finding is a bug to fix." | Most are noise. Rank by reachable + exposed + sensitive sink; report the few that matter. |
-| "Scanned the working tree, no secrets." | History holds the deleted keys. Scan git history; a removed-in-HEAD key is still leaked and live. |
-| "`npm audit` is clean, deps are fine." | Native auditors miss transitive CVEs. Run osv-scanner/Trivy too; native is the fast pass, not the only pass. |
-| "Commit a blanket `.semgrepignore` to quiet CI." | A blanket ignore hides the next real bug. Suppress per-finding with a written justification + expiry. |
-| "We found a verified key, I deleted it from the file." | Deleting ≠ safe. Rotate the credential first, then scrub history. The committed value is already compromised. |
-| "Trust the SARIF `level`, that's the severity." | Tools disagree. Normalize to one scale before you rank or gate. |
-| "Dump all four tool outputs in the PR, let the reviewer sort it." | The reviewer won't. Merge, dedupe, rank, and emit one report. |
-| "Run the scan; it'll auto-fix the deps." | Read-only by default. Propose bumps; apply only when asked — never mutate during a sweep. |
+| Pulling `aquasecurity/trivy-action@latest` because it is the official action | March 2026: a hijacked tag stole CI secrets. Pin a full SHA, verify provenance. |
+| Treating every scanner finding as a bug to fix | Most are noise. Rank by reachable + exposed + sensitive sink; report the few that matter. |
+| Calling the repo clean after scanning only the working tree | History holds the deleted keys. Scan git history; a removed-in-HEAD key is still leaked and live. |
+| Declaring deps fine because `npm audit` is clean | Native auditors miss transitive CVEs. Run osv-scanner/Trivy too; native is the fast pass, not the only pass. |
+| Committing a blanket `.semgrepignore` to quiet CI | A blanket ignore hides the next real bug. Suppress per-finding with a written justification + expiry. |
+| Deleting a verified key from the file and moving on | Deleting ≠ safe. Rotate the credential first, then scrub history. The committed value is already compromised. |
+| Taking the SARIF `level` as the severity | Tools disagree. Normalize to one scale before you rank or gate. |
+| Dumping all four tool outputs in the PR for the reviewer to sort | The reviewer won't. Merge, dedupe, rank, and emit one report. |
+| Letting the scan auto-fix the deps it finds | Read-only by default. Propose bumps; apply only when asked — never mutate during a sweep. |
 
 ## Project grounding (02-DOCS + CLAUDE.md)
 
@@ -218,23 +208,12 @@ In a project with a `02-DOCS/` layer (the [`harness`](../harness/SKILL.md)
 Karpathy wiki), record the scanner choices, pinned versions, gate thresholds, and
 any accepted-risk suppressions in `02-DOCS/wiki/stack/security-scan.md`, and index
 it in `02-DOCS/wiki/index.md` (the Knowledge map; root `CLAUDE.md` keeps only a short
-pointer to it). Read it first on every run so the
-next agent inherits the pinned tools and thresholds instead of re-deriving them.
-No `02-DOCS/`? Skip silently. Conventions are recorded, not gated — never block
-the scan on this.
+pointer to it). Read it first on every run so the next agent inherits the pinned
+tools and thresholds instead of re-deriving them. No `02-DOCS/`? Skip silently.
+Conventions are recorded, not gated — never block the scan on this.
 
 ## See Also
 
-- [`secure-coding`](../secure-coding/SKILL.md) — the human-reasoning sibling:
-  threat-model a feature, hand-write the vulnerable→fixed diff. *If the answer
-  comes from a tool run it's this skill; if it comes from reasoning about the
-  design it's secure-coding.*
-- [`review`](../review/SKILL.md) — adversarial review of a diff against a spec.
-- [`code-review`](../code-review/SKILL.md) — general correctness/quality review.
-- [`verify`](../verify/SKILL.md) — the broader lint/type/test green gate this
-  feeds into.
-- **References** — `references/tools.md` (pinned installs, flag matrix,
-  suppression syntax); `references/triage.md` (ranking rubric, dedupe keying,
-  severity map, full report schema).
-</content>
-</invoke>
+Reviewing a diff rather than scanning a repo: [`code-review`](../code-review/SKILL.md)
+for correctness and quality, [`review`](../review/SKILL.md) for adversarial review
+against a spec.

package/skills/security-scan/references/tools.md

@@ -95,4 +95,3 @@ trivy image --format sarif --output trivy-img.sarif <pinned-image@sha256:...>
 - Every recipe emits SARIF 2.1.0 so findings merge into one report. Where a tool
   only emits native JSON (`npm audit`, `pip-audit`, TruffleHog), normalize it to
   the report schema in `triage.md` rather than gating on its raw shape.
-</content>

package/skills/security-scan/references/triage.md

@@ -90,4 +90,3 @@ This is the contract `scripts/verify.sh` gates on.
 - **Gate:** any `findings[]` with `status: "open"` and `severity: "critical"`
   → fail. Strict mode also fails on `open` + `high`. `suppressed`/`fixed` never
   fail. An empty/clean report exits `0`.
-</content>