@dsalazardev/ai-hub-cli 0.0.0-stage → 0.1.0

package/skills/shared/sdd-init/SKILL.md

@@ -0,0 +1,189 @@
+---
+name: sdd-init
+description: "Use when calibrating an existing repo for the ai-hub Spec-Kit chain: detect stack, package manager, test runners and apply/verify commands, refresh the skill registry, and write the runtime config at 02-DOCS/wiki/sdd/config.yaml. NOT the dispatcher that routes SDD phases (that is `sdd`), NOT first-contact user/workspace bootstrap (that is `init`)."
+tags: [sdd, init, config, testing, registry]
+recommends: [sdd, specify, implement, verify]
+profiles: [core, full]
+origin: ai-hub
+---
+
+# sdd-init — calibrate the repo before the SDD chain
+
+Step zero for technical SDD work: read the repo, detect how it should be built and tested, refresh the cheap skill registry, and write one durable config:
+
+```text
+02-DOCS/wiki/sdd/config.yaml
+```
+
+That config is the runtime contract later phases read before choosing commands, TDD strictness, artifact paths, review budget or skill briefs. `sdd` dispatches the phases that consume it, `init` owns first contact and user profiling, `harness` owns `01-TOOLS/` and `02-DOCS/` scaffolding. This skill only calibrates.
+
+## Inputs
+
+Read-only first:
+
+- `package.json`, lockfiles, `pnpm-workspace.yaml`, `pyproject.toml`, `requirements.txt`, `go.mod`, `pubspec.yaml`, `Dockerfile`, `.github/`.
+- Existing `02-DOCS/wiki/sdd/config.yaml`, if present.
+- `02-DOCS/wiki/harness/user-profile.md`, if present, for `technical_level` (the register) only.
+- `.ai-hub/skill-registry.json`, if present, to decide whether it is stale or missing.
+
+If `02-DOCS/` does not exist, create only the `02-DOCS/wiki/sdd/` path needed for the config. Do not run full harness scaffolding unless the user asked for `harness`.
+
+## Preflight Choices
+
+Ask only when the answer changes behavior; explain each trade-off in one line, in the register `technical_level` sets.
+
+| Setting | Default | Options |
+| --- | --- | --- |
+| `execution_mode` | `interactive` | `interactive` pauses at review-risk gates; `automatic` chains phases until a blocker/risk appears. |
+| `artifact_store` | `02-DOCS/wiki/sdd` | Keep ai-hub artifacts in `02-DOCS`; do not create an `openspec/` parallel tree. |
+| `review_budget.line_budget` | `400` | Lower for solo tight review; higher only with explicit approval. |
+| `delivery_strategy.default` | `ask-on-risk` | `ask-on-risk`, `single-pr`, `autochain`, `exception`. |
+| `models.enabled` | `false` | Per-phase model routing is opt-in; leave off unless the user asks for it. |
+| `models.provider` | `anthropic` | Which provider the tiers resolve to. Set from the detected assistant when obvious, else `anthropic`. See `../sdd/references/model-routing.md` for other providers. |
+
+## Detection
+
+Use the repo detector exposed by the CLI code (`detectRepoProfile`) or reproduce the same facts manually if running inside an agent without code access:
+
+- stacks: Next.js/React, FastAPI/Python, Go, Flutter, Postgres, deployment signals;
+- package managers: pnpm, npm, yarn, bun;
+- scripts: `test`, `lint`, `typecheck`, `build`;
+- runners: Vitest, Jest, Playwright, pytest, `go test`, `flutter test`;
+- monorepo signals;
+- recommended apply and verify commands;
+- the active assistant/provider when it's obvious from the environment (Claude Code, Codex, Gemini…), to seed `models.provider` — default `anthropic` when unsure. This only sets the *concrete model names*; routing itself stays off until the user opts in.
+
+If any runner is detected, set `testing.strict_tdd: true`. Strict TDD means implement phases must do red -> green -> triangulate edge cases -> refactor, with command evidence. If no runner is detected, set it false and record the gap rather than pretending.
+
+## Skill Registry
+
+Refresh the project registry:
+
+```bash
+npx ai-hub registry refresh
+```
+
+This writes:
+
+```text
+.ai-hub/skill-registry.json
+.ai-hub/skill-registry.md
+```
+
+Later phases use it as a cheap index — id, trigger, tags, path, installed/available, hash — to select the few skills matching the phase and stack and digest them into compact rules for subagents.
+
+## Equip the repo — install the skills this stack needs
+
+Calibration is the moment to make sure the relevant skills are actually present, not just indexed. Detect → propose → install:
+
+1. **Detect what this repo needs.** Use the stack you just detected, or ask the CLI: `npx ai-hub consult "<one line: stack + what we're building>"`. Map signals to skills — e.g. `next`→`nextjs`+`design`, `go.mod`→`go`, FastAPI→`fastapi`, `*.sql`/Prisma→`postgresdb`/`prisma-orm`, Stripe→`stripe`, Dockerfile/CI→`docker`/`github-actions`, tests→`testing-*`/`e2e-testing`. The SDD phase skills (`specify`…`ship`) should already be present from `--profile core`; install any that are missing.
+2. **Show the shortlist + confirm.** List the skills with a one-line *why* each, in the user's register, and get a one-word confirm before touching their environment.
+3. **Install them yourself.** You have a terminal — run it via Bash:
+   ```bash
+   npx ai-hub add <skill> [<skill> ...]
+   ```
+   If you genuinely cannot run a shell, print the exact command and ask the user to paste it in another terminal tab.
+4. **Flag the new session.** Newly installed skills load at the START of a session. Tell the user: *"Instaladas. Abre una pestaña/sesión nueva de tu asistente (o recarga) en esta carpeta para que se activen."* Then refresh the registry again so `installed/available` is accurate.
+
+## Config Shape
+
+Write `02-DOCS/wiki/sdd/config.yaml` in this shape:
+
+```yaml
+version: 1
+project:
+  root: .
+  stacks: []
+  package_managers: []
+  monorepo: false
+  signals: []
+sdd:
+  artifact_store: 02-DOCS/wiki/sdd
+  execution_mode: interactive
+  registry_path: .ai-hub/skill-registry.json
+  review_budget:
+    line_budget: 400
+    file_budget: 12
+  delivery_strategy:
+    default: ask-on-risk
+testing:
+  strict_tdd: false
+  runners: []
+  commands:
+    apply: []
+    verify: []
+phase_rules:
+  proposal: optional-on-ambiguity
+  specify: requires intent or proposal
+  plan: requires spec
+  tasks: requires plan and spec
+  analyze: requires spec plan tasks
+  implement: requires analyze pass, strict_tdd when testing.strict_tdd is true
+  verify: requires spec tasks evidence
+  archive: requires verify record and review/ship outcome
+models:
+  enabled: false              # opt-in master switch; false = honor session model, announce nothing
+  provider: anthropic         # which provider the tiers below resolve to
+  tiers:
+    heavy: claude-opus-4-8
+    balanced: claude-sonnet-4-6
+    light: claude-haiku-4-5-20251001
+  phases:
+    constitution: heavy
+    specify: balanced
+    clarify: balanced
+    plan: heavy
+    tasks: balanced
+    analyze: heavy
+    implement: balanced
+    verify: balanced
+    review: heavy
+    ship: light
+    debug: heavy
+    worktrees: light
+    sdd-init: light
+  overrides: {}               # per-phase tier overrides set by the user
+```
+
+The `models` block is the **per-phase model routing** profile: each phase declares a tier (`heavy`/`balanced`/`light`) and the tiers resolve to concrete models for `provider`. The full protocol — how phases apply it, the per-assistant switch mechanism, the provider→model table — lives in `../sdd/references/model-routing.md`. Keep this block byte-for-byte in sync with that reference.
+
+Preserve user edits if the file exists: update detected facts and leave comments/custom policy fields intact when possible. **Never flip `models.enabled` or drop `models.overrides` on re-calibration** — a calibration pass that silently switches the user's models is the one failure they cannot detect from the diff, so preserve both verbatim and only refresh `tiers`/`provider` if the user asks. If preservation is risky, write a proposed replacement next to it as `config.proposed.yaml` and ask.
+
+## Result Envelope
+
+End with the standard SDD result envelope:
+
+```json result-envelope
+{
+  "status": "complete",
+  "executive_summary": "SDD config calibrated and registry refreshed.",
+  "artifact": "02-DOCS/wiki/sdd/config.yaml",
+  "next_recommended": "sdd",
+  "risk": "low",
+  "skill_resolution": {
+    "used": ["sdd-init"],
+    "missing": [],
+    "fallback": [],
+    "compact_rules": [
+      "Read config.yaml before choosing commands.",
+      "Use .ai-hub/skill-registry.json as the cheap skill index.",
+      "Per-phase model routing ships off (models.enabled:false); never switch models unasked."
+    ]
+  },
+  "evidence": ["npx ai-hub registry refresh", "detected test commands recorded"]
+}
+```
+
+## Anti-patterns
+
+| Temptation | Reality |
+| --- | --- |
+| "I'll skip config and remember the commands in chat." | Chat is not source of truth. Write `config.yaml`. |
+| "No test command detected, but I'll still say strict TDD is active." | Strict TDD needs a runner. Record the gap. |
+| "Load all skills so the agent has context." | That pollutes context. Use registry -> selected skills -> compact rules. |
+| "This is the same as init." | No. `init` profiles user/workspace, `sdd` dispatches the phases, `sdd-init` calibrates the technical SDD runtime they both rely on. |
+| "Create openspec/ because Gentle does." | ai-hub uses `02-DOCS/wiki/sdd/` as source of truth. |
+
+## Next
+
+After `sdd-init`, return to `sdd`. If no spec exists, route to `specify`. If the work is ambiguous or architectural, write a proposal first under `02-DOCS/wiki/sdd/proposals/`.

package/skills/shared/sdd-init/evals/README.md

@@ -0,0 +1,3 @@
+# sdd-init evals
+
+Behavioral cases for the SDD technical calibration step.

package/skills/shared/sdd-init/evals/cases.yaml

@@ -0,0 +1,43 @@
+skill: sdd-init
+
+should_trigger:
+  - prompt: "Calibrate this repo before we run the SDD flow."
+    why: "Direct request for technical SDD calibration before phases."
+  - prompt: "Run sdd init and detect my test runner before implementing."
+    why: "Names sdd init and test-runner detection, the core responsibility."
+  - prompt: "Set up the SDD config.yaml for this existing repo."
+    why: "Creating the persisted SDD config is this skill's output."
+  - prompt: "Before coding, detect package manager, test commands, strict TDD mode and registry."
+    why: "All requested facts are the preflight calibration surface."
+  - prompt: "Prepara este repo para desarrollo dirigido por especificacion y dime que comandos de verify usar."
+    why: "Spanish SDD prep plus verify command detection should trigger sdd-init."
+  - prompt: "Refresh the project skill registry and write the SDD runtime config."
+    why: "Registry refresh plus runtime config is exactly this skill."
+
+should_not_trigger:
+  - prompt: "Inicia mi empresa/harness general y monta docs/tools y docs/."
+    route_to: "init"
+    why: "First-contact/general workspace bootstrap belongs to init, which then hands off to harness."
+  - prompt: "Audit this workspace and scaffold provider tools under docs/tools."
+    route_to: "harness"
+    why: "Operational scaffolding and provider tools are harness work, not SDD technical calibration."
+  - prompt: "Write the feature spec for CSV export."
+    route_to: "specify"
+    why: "Feature requirements/spec writing is specify."
+  - prompt: "All implementation is done; run lint, tests and acceptance criteria."
+    route_to: "verify"
+    why: "Post-implementation evidence gate belongs to verify."
+  - prompt: "Create a Next.js app with Tailwind."
+    route_to: "nextjs"
+    why: "Stack scaffolding is the stack skill, not SDD init."
+
+capability:
+  - scenario: "A repo has package.json with pnpm, test/lint/typecheck/build scripts, Vitest and Playwright, plus no existing SDD config. The user asks to calibrate before SDD."
+    must_include:
+      - "Detects stack, package manager, scripts, test runners and monorepo signals from repo files."
+      - "Writes .specify/config.yaml, not an openspec/ folder."
+      - "Sets testing.strict_tdd true because a runner exists and records apply/verify commands."
+      - "Asks or defaults execution_mode, artifact_store, review budget and delivery strategy."
+      - "Reads manifest.yaml and ai-hub list; records skills.publish as the declared catalog."
+      - "Distinguishes itself from init and harness."
+      - "Ends with the standard result envelope including skill_resolution and evidence."

package/skills/shared/secure-coding/SKILL.md

@@ -0,0 +1,336 @@
+---
+name: secure-coding
+description: "Use when securing application code: threat-modeling a feature, security-reviewing a diff, hardening auth/authz, secrets, CORS/CSP, or fixing OWASP-class bugs (access control, injection, SSRF, supply chain) in FastAPI, Next.js, Go or Flutter. NOT running the scanners (that is security-scan), NOT agent prompt-injection guardrails (that is agent-safety)."
+tags: [security, owasp, stride, auth, review]
+recommends: [deployment]
+origin: ai-hub
+---
+
+# Secure coding — threat modeling + OWASP across the stack
+
+Threat-model a feature in PR-sized increments, fix OWASP-class bugs with
+stack-correct vulnerable→fixed diffs, and gate the result with `verify.sh`.
+Stacks: FastAPI/Python 3.12+, Next.js 15 / React 19 / TS, Go 1.22+,
+Flutter/Dart 3, PostgreSQL 16.
+
+Operating posture:
+
+- **Read-only by default.** Identify → rank by exploitability → propose fixes
+  as diffs. Apply changes only when the user asks.
+- **Exploitability over theory.** Rank like a bounty triager: reachable +
+  user-controlled + meaningful sink comes first. Do not dump a flat checklist.
+- **Every finding ships a fix.** Never "consider sanitizing" — show the
+  corrected code for *this* stack.
+
+Stay in lane — this is about **the application code the user ships**. Agent /
+Claude-Code config security (`.claude/`, hooks, MCP, prompt injection,
+sandboxing) is a *different* concern: [`agent-safety`](../agent-safety/SKILL.md),
+[`building-agents`](../building-agents/SKILL.md). Running the scanners and
+triaging their raw output: [`security-scan`](../security-scan/SKILL.md).
+Infra/network firewalling with no code change: [`deployment`](../deployment/SKILL.md).
+A pentest/bounty PoC against a third party is out of scope (legal) — this skill
+defends code, it does not attack external targets. Don't gate trivial
+non-security refactors through `verify.sh`.
+
+## The 30-second model: lethal trifecta + trust boundaries
+
+- **Lethal trifecta** (Simon Willison): private data **+** untrusted input **+**
+  ability to exfiltrate. Flag any handler where all three meet — that's where a
+  leak becomes a breach.
+- **Trust-boundary rule:** every untrusted→trusted crossing is a checkpoint with
+  one owning defense: HTTP body→SQL, user string→shell/URL/HTML, JWT claim→authz
+  decision, filename→fs path, upload→disk/exec.
+- **Least privilege / least agency** for tokens, DB roles, CORS origins and file
+  perms. It is the one control that still caps blast radius *after* one of the
+  defenses below fails, so it is never optional.
+
+| Untrusted source | Dangerous sink | Defense | Ref |
+|---|---|---|---|
+| Request body | SQL query | Parameterize (bound params / ORM) | A03 |
+| User URL | Outbound fetch | https-only + IP allowlist, block private ranges | A10 |
+| User HTML | DOM render | Encode by context / DOMPurify allowlist | A03 |
+| Filename | Filesystem path | Canonicalize + base-dir containment | A03 |
+| JWT / claim | Authz decision | Verify signature + pinned alg + `aud`/`iss`/`exp` | `references/authn-authz.md` |
+| Upload | Disk / exec | Type+size, sniff magic bytes, store outside web root | A01 |
+
+A-numbers index `references/owasp-by-stack.md`: same section, vulnerable→fixed
+code in all three stacks.
+
+## Review workflow (PR-sized)
+
+1. **Scope.** What data, which boundary, what auth context does the diff touch?
+2. **Threat-model lite.** STRIDE on the changed element only → `references/threat-modeling.md`.
+3. **Map sinks to OWASP.** Match each changed sink to a category → `references/owasp-by-stack.md`.
+4. **Rank by exploitability.** Reachable? User-controlled? Meaningful sink? Report the highest-impact reachable findings first, not a checklist.
+5. **Propose fixes as diffs** in the repo's actual stack (Good/Bad, copy-pasteable).
+6. **Run `scripts/verify.sh`** in the repo root; resolve every high/critical before merge — a reachable CVE is a release blocker, not a follow-up ticket.
+
+## OWASP Top 10 — fastest fix per category
+
+| OWASP 2021 | The mistake you'll actually see | Stack-correct fix in one phrase |
+|---|---|---|
+| A01 Broken Access Control | `db.get(id)` returned to any authed user | Ownership-scoped query; 404 (not 403) on miss |
+| A02 Cryptographic Failures | SHA-256 password hash; `random` token | Argon2id + CSPRNG (`secrets`/`crypto/rand`) |
+| A03 Injection | f-string SQL / `shell=True` | Bound params / arg-list, no shell / canonicalize path |
+| A04 Insecure Design | No rate limit, replayable payment | Lockout + idempotency-key `UNIQUE` constraint |
+| A05 Security Misconfiguration | `debug=True`, `*`+credentials CORS | `debug=False`, explicit origin allowlist, headers |
+| A06 Vulnerable Components | Ignored transitive CVE | Audit + upgrade/override/replace |
+| A07 Auth Failures | Reusable session id, user enumeration | Lockout + rotate session id + generic error |
+| A08 Data Integrity | `curl \| bash`, unpinned CDN script | `npm ci`/`go mod verify` + SRI |
+| A09 Logging Failures | No authz-fail log; PII in logs | Structured log on `user_id`, redact secrets |
+| A10 SSRF | Fetch user-supplied URL directly | https-only + IP allowlist + pin dialed IP |
+
+Flagship: **A01 Broken Access Control / IDOR** (the #1, stack-agnostic in
+shape). Authorize on the **server**, per object, on **every** request, deny by
+default: the id in the URL is attacker-controlled, so the ownership predicate in
+the query is the only thing standing between a stranger and the row.
+
+```python
+# Python — FastAPI 3.12 + SQLAlchemy 2.0
+# BAD — any authenticated user can read any document.
+@router.get("/documents/{doc_id}")
+def get_doc(doc_id: int, db: Session = Depends(get_db)):
+    return db.get(Document, doc_id)
+
+# GOOD — ownership-scoped query; 404 on miss; injected current_user.
+@router.get("/documents/{doc_id}")
+def get_doc(doc_id: int, db: Session = Depends(get_db),
+            user: User = Depends(get_current_user)) -> DocumentOut:
+    doc = db.execute(
+        select(Document).where(Document.id == doc_id, Document.owner_id == user.id)
+    ).scalar_one_or_none()
+    if doc is None:
+        raise HTTPException(status_code=404, detail="Not found")  # 404 not 403
+    return DocumentOut.model_validate(doc)
+```
+
+```ts
+// TS — Next.js 15 App Router Route Handler / Server Action
+// BAD — trusts the id and assumes a session exists.
+export async function GET(_req: Request, { params }: { params: Promise<{ id: string }> }) {
+  const { id } = await params; // Next.js 15: params is a Promise — await it.
+  return Response.json(await db.document.findUnique({ where: { id } }));
+}
+// GOOD — auth() guard + ownership scope + notFound().
+import { auth } from "@/auth";
+import { notFound } from "next/navigation";
+export async function GET(_req: Request, { params }: { params: Promise<{ id: string }> }) {
+  const { id } = await params;
+  const session = await auth();
+  if (!session) notFound();
+  const doc = await db.document.findFirst({
+    where: { id, ownerId: session.user.id },
+  });
+  if (!doc) notFound();
+  return Response.json(doc);
+}
+// NOTE: Server Actions are public POST endpoints — re-authorize server-side.
+```
+
+```go
+// Go — 1.22 ServeMux + slog
+// BAD — r.PathValue("id") straight into the query, no ownership check.
+// GOOD — userID from context; scoped query; 404 on miss.
+mux.HandleFunc("GET /documents/{id}", func(w http.ResponseWriter, r *http.Request) {
+    userID, ok := r.Context().Value(userKey).(int64)
+    if !ok { http.Error(w, "unauthorized", http.StatusUnauthorized); return }
+    var body string
+    err := db.QueryRowContext(r.Context(),
+        "SELECT body FROM documents WHERE id=$1 AND owner_id=$2",
+        r.PathValue("id"), userID).Scan(&body)
+    if err == sql.ErrNoRows {
+        slog.Warn("authz_miss", "user", userID)
+        http.Error(w, "not found", http.StatusNotFound); return
+    }
+    if err != nil { http.Error(w, "internal error", http.StatusInternalServerError); return }
+    _, _ = w.Write([]byte(body))
+})
+```
+
+Full vulnerable→fixed code for **all 10 categories in all three stacks** lives
+in `references/owasp-by-stack.md`.
+
+## Input validation & output encoding
+
+Validate at the boundary with a schema and never trust the shape that arrived —
+an unbounded or extra field is how the next sink gets its payload.
+
+```python
+# BAD — raw body, unbounded, unknown fields silently accepted.
+data = await request.json()
+# GOOD — Pydantic v2: bounded + reject unknown fields.
+from pydantic import BaseModel, ConfigDict, Field
+class CreateUser(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    email: str = Field(max_length=254)
+    name: str = Field(min_length=1, max_length=100)
+```
+
+```ts
+// GOOD — Zod .strict() parsed inside the Server Action (Go: struct + go-playground/validator).
+const Schema = z.object({ email: z.string().email(), name: z.string().max(100) }).strict();
+const data = Schema.parse(await req.json());   // BAD: `body as any`
+```
+
+**XSS:** React auto-escapes — the bug is `dangerouslySetInnerHTML`. **Stored**
+(persisted then served), **reflected** (echoed from the request), and **DOM**
+(client writes user data into the DOM) XSS all need encoding/sanitizing. Encode
+on output *by context* (HTML / attribute / JS / URL); never build HTML by
+concatenating user strings.
+
+```tsx
+// BAD — raw user HTML into the DOM.
+<div dangerouslySetInnerHTML={{ __html: userHtml }} />
+// GOOD — DOMPurify allowlist sanitize, or render as text.
+import DOMPurify from "isomorphic-dompurify";
+<div dangerouslySetInnerHTML={{ __html: DOMPurify.sanitize(userHtml, { ALLOWED_TAGS: ["b","i","p"] }) }} />
+```
+
+**Upload validation:** size cap + **sniffed** content-type (magic bytes, not the
+client-sent `file.type`) + extension allowlist + store outside the web root +
+random filename.
+
+```python
+# GOOD — sniff magic bytes; never trust the client content-type.
+import secrets, filetype
+head = await file.read(512); await file.seek(0)
+kind = filetype.guess(head)
+if kind is None or kind.mime not in {"image/png", "image/jpeg"}:
+    raise HTTPException(415, "unsupported media type")
+dest = UPLOAD_DIR / f"{secrets.token_hex(16)}.{kind.extension}"   # outside web root
+```
+
+```ts
+// GOOD — magic-byte sniff on the first bytes; reject SVG.
+import { fileTypeFromBuffer } from "file-type";
+const buf = Buffer.from(await file.arrayBuffer());
+const ft = await fileTypeFromBuffer(buf);
+if (!ft || !["image/png", "image/jpeg"].includes(ft.mime)) throw new Error("bad type");
+```
+
+## AuthN / AuthZ in 60 seconds
+
+- **Library note (2026):** Auth.js / NextAuth v5 is still maintained (now under
+  the Better Auth team; security patches continue) and the `auth()` patterns
+  below are valid — but for *new* Next.js projects, evaluate Better Auth too. The
+  principles here (server-side authz, `HttpOnly` cookies, pinned-alg JWT) are
+  library-agnostic.
+- **Sessions vs JWT:** server-side session = easy revocation, default for
+  first-party web; JWT = stateless, short access (5–15 min) + rotating refresh
+  with reuse detection + a revocation story.
+- **Cookie flags:** `HttpOnly; Secure; SameSite=Lax` (`Strict` for sensitive),
+  `__Host-` prefix, scoped `Path=/`. BAD = token in `localStorage` (XSS steals it).
+- **Password hashing:** Argon2id (`time_cost=3, memory_cost=65536, parallelism=4`)
+  via `argon2-cffi` (Py) / `golang.org/x/crypto/argon2` (Go); bcrypt `cost>=12`
+  fallback; never SHA-256/MD5. (These exceed the OWASP floor of `m=19456, t=2,
+  p=1` or `m=47104, t=1, p=1` — `≥` the minimum on every axis is the bar; tune
+  `memory_cost` up until a hash takes ~0.5s on prod hardware.)
+- **CSRF:** needed for cookie-auth state-changing requests; double-submit token
+  or framework token; SameSite is defense-in-depth, not sufficient alone.
+
+```python
+# GOOD — verify a JWT with pinned algorithms + audience + issuer (PyJWT).
+import jwt
+claims = jwt.decode(
+    token, public_key,
+    algorithms=["RS256"],            # pinned: rejects alg:none and HS-when-RS
+    audience="api://my-service", issuer="https://issuer.example.com/",
+    options={"require": ["exp", "aud", "iss"]},
+)
+```
+
+Sessions/OIDC/RBAC/ABAC/MFA/refresh-rotation details: `references/authn-authz.md`.
+
+## CORS, security headers, TLS, rate limiting, logging
+
+```python
+# CORS — BAD: allow_origins=["*"] with allow_credentials=True (illegal + dangerous).
+# GOOD — explicit origin allowlist.
+from fastapi.middleware.cors import CORSMiddleware
+app.add_middleware(CORSMiddleware,
+    allow_origins=["https://app.example.com"], allow_credentials=True,
+    allow_methods=["GET", "POST"], allow_headers=["authorization", "content-type"])
+```
+
+```ts
+// Security headers — next.config.ts. CSP without unsafe-inline/unsafe-eval
+// (use nonces/hashes for inline scripts); HSTS only when all subdomains are HTTPS.
+const headers = [
+  { key: "Content-Security-Policy", value: "default-src 'self'; object-src 'none'; frame-ancestors 'none'; base-uri 'self'" },
+  { key: "Strict-Transport-Security", value: "max-age=63072000; includeSubDomains; preload" },
+  { key: "X-Content-Type-Options", value: "nosniff" },
+  { key: "X-Frame-Options", value: "DENY" },
+  { key: "Referrer-Policy", value: "strict-origin-when-cross-origin" },
+];
+export default { async headers() { return [{ source: "/:path*", headers }]; } };
+```
+
+- **Rate limiting:** per-IP **and** per-identity, stricter on auth/OTP/search.
+  In-memory limiters are **not** multi-instance safe — use Redis behind >1 replica.
+- **Fail closed:** generic error to the client, detail to the logs. A stack
+  trace or DB message in a response is free reconnaissance for the attacker.
+- **Logging without PII:** redact tokens/passwords/PAN/email; log `user_id`,
+  not email; structured (`slog`/`structlog`); never log auth-route bodies.
+
+## Secrets & supply chain (the part that gets you breached)
+
+- Env/secret-manager, never repo; `.env` gitignored. Only `NEXT_PUBLIC_*` is
+  public — **BAD: a secret read in a Client Component ships to the browser.**
+  In a [`harness`](../harness/SKILL.md) project they live in
+  `01-TOOLS/<PROVIDER>/.env` (gitignored) — same rule, never in the repo.
+- Pin + commit the lockfile; install with `npm ci` / `pnpm i --frozen-lockfile`
+  / `go mod verify` / `pip install --require-hashes`.
+- Audit per stack: `pip-audit`, `npm audit --omit=dev --audit-level=high` or
+  `osv-scanner scan source -L pnpm-lock.yaml` (lockfile-aware, multi-ecosystem,
+  v2 CLI), `govulncheck ./...` (reachability-aware — only vulns you call),
+  `dart pub outdated`. Fix by upgrading to the fixed version; constrain or
+  override transitive pins.
+- On exposure: **rotate the credential first, then scrub history** (`gitleaks
+  dir . --redact` for the working tree, `gitleaks git .` for history, to
+  confirm). SBOM via `syft`; provenance via `cosign`/SLSA.
+
+Full runbook: `references/secrets-and-supply-chain.md`.
+
+## Anti-patterns
+
+| What gets said | Reality |
+|---|---|
+| "It's behind auth, so IDOR doesn't matter." | Authenticated ≠ authorized. Check object ownership on every request. |
+| "The frontend already validates / hides the button." | Client checks are UX. Re-authorize and re-validate on the server. Server Actions and API routes are public. |
+| "I'll sanitize with a blacklist of bad chars." | Allowlist + parameterize/encode. Blacklists are bypassable. |
+| "JWT in localStorage is fine, it's just an access token." | Any XSS steals it instantly. Use `HttpOnly` cookies; short TTLs. |
+| "`allow_origins=['*']` with credentials is convenient." | The browser rejects it and it's dangerous. Use an explicit origin allowlist. |
+| "npm audit shows criticals but they're transitive." | Transitive is still in your bundle. Pin/override or replace. |
+| "I'll log the payload to debug, remove it later." | "Later" never comes; PII/secrets leak to logs. Redact now. |
+| "We'll add rate limiting after launch." | Auth/OTP endpoints get brute-forced on day one. |
+| "It's an internal URL fetch, SSRF isn't a risk." | Internal is exactly the SSRF target (metadata, RDS). Allowlist hosts and block `169.254.169.254`, `10/8`, `172.16/12`, `192.168/16`, `127/8`, `::1`, `fc00::/7`, `fe80::/10`. |
+| "Error stack to the client speeds debugging." | It leaks internals to attackers. Generic to client, detail to logs. |
+| "Secrets in `.env.example` are placeholders; real ones in CI YAML are fine." | Use the secret store; never inline real secrets in CI files. |
+| "Argon2 is overkill, SHA-256 is fast." | Fast = brute-forceable. Use Argon2id (or bcrypt cost≥12). |
+
+## verify.sh — the gate
+
+`scripts/verify.sh` runs gitleaks + semgrep (`--config=auto --severity ERROR`
+gates; WARNING is informational) + the per-stack CVE audit
+(pip-audit/osv-scanner/govulncheck). It is **the user's to run in their own repo
+root** — it auto-detects the stack, skips (does not fail) when a tool is
+missing, and exits non-zero **only** on real high/critical findings. The CI
+equivalent is in `references/secrets-and-supply-chain.md`.
+
+## Project grounding
+
+In a project with a `02-DOCS/` layer ([`harness`](../harness/SKILL.md)), this
+project's security decisions live in `02-DOCS/wiki/stack/security.md`, indexed
+from `02-DOCS/wiki/index.md` (the Knowledge map; root `CLAUDE.md` keeps only a
+pointer to it). Read it first and stay consistent; if it is missing or stale,
+create/update it with the real choices — threat model, auth model, secrets
+backend, CI security gates, accepted risks — index it, and bump its `Updated`
+date in the same change. No `02-DOCS/` layer? Skip silently (optionally suggest
+`harness`): technical conventions are *recorded, not gated* — never block the
+task on this.
+
+Stack skills ([`fastapi`](../fastapi/SKILL.md), [`nextjs`](../nextjs/SKILL.md),
+[`go`](../go/SKILL.md), [`flutter`](../flutter/SKILL.md),
+[`postgresdb`](../postgresdb/SKILL.md), [`deployment`](../deployment/SKILL.md))
+defer security to this skill; where one doesn't exist yet, this is the canonical
+reference it would point to.

package/skills/shared/secure-coding/evals/README.md

@@ -0,0 +1,68 @@
+# Eval harness — secure-coding
+
+These evals are run through an **agent harness** (an agent with skills loadable
+on demand), not a pure shell script. `cases.yaml` is the fixture; this file is
+the procedure. Two things are measured: **triggering** (does the skill fire when
+it should and stay quiet when it shouldn't) and **capability** (does the skill
+make the answer materially better).
+
+## Setup
+
+- Use the same agent/model for every trial; vary only which skills are loaded.
+- Triggering trials: load the **full skill catalog** (so the agent can route to
+  siblings) and observe which skill the agent selects.
+- Capability trials: compare **only this skill loaded** vs **no skill loaded**.
+
+## 1. Triggering
+
+For each item in `should_trigger` and `should_not_trigger`:
+
+1. Start a fresh agent session with the full catalog available.
+2. Feed the `prompt` verbatim as the user message.
+3. Record which skill (if any) the agent invokes.
+4. Run **3–5 trials** per prompt (the decision is stochastic).
+
+Pass conditions:
+
+- `should_trigger`: **secure-coding** is invoked in the majority of trials.
+- `should_not_trigger`: secure-coding is **not** invoked; ideally the agent
+  routes to the listed `route_to` sibling (or correctly declines when `none`).
+
+**Pass bar: >= 90% trigger accuracy** across all trials (a single prompt that
+flaps below majority counts as a fail for that prompt; >= 90% of prompts must
+pass clean).
+
+## 2. Capability
+
+For each `capability` scenario, run two arms:
+
+- **WITH**: only secure-coding loaded.
+- **WITHOUT**: no skill loaded (baseline model behavior).
+
+Run each arm 3 times. Grade every response against the scenario's
+`must_include` rubric — one point per checkable item that is genuinely present
+(correct, stack-appropriate, not hand-waved).
+
+Pass conditions:
+
+- **WITH** the skill covers **>= 80%** of `must_include` items on average.
+- The skill **measurably improves** the output: WITH coverage must beat WITHOUT
+  by a clear margin (target >= 25 percentage points). A skill that doesn't move
+  the needle fails even if the baseline was already decent.
+
+## Scoring summary
+
+| Dimension | Metric | Pass bar |
+|---|---|---|
+| Triggering | trigger accuracy across all prompts/trials | >= 90% |
+| Capability | rubric coverage WITH skill | >= 80% |
+| Capability | WITH minus WITHOUT (lift) | >= 25 pts |
+
+## Notes / honesty
+
+- These are LLM-graded, stochastic evals — re-run on skill edits and treat
+  small score deltas as noise, not signal.
+- `route_to` targets assume the sibling skills (fastapi, nextjs, go, postgresdb,
+  flutter, building-agents, deployment, …) are present in the catalog; a missing
+  sibling can cause a near-miss to mis-route without it being a secure-coding
+  fault — note it, don't count it against this skill.