sanook-cli 0.4.0 → 0.5.0

package/skills/ship-mobile-app-store-release/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: ship-mobile-app-store-release
+description: Prepares and ships iOS App Store and Google Play releases — code signing (certs/provisioning, upload vs app-signing keystores), marketing-version/build-number bumps, Fastlane/EAS/Gradle build lanes, TestFlight/Play-track uploads, phased rollout, store metadata, and review-rejection remediation.
+when_to_use: Cutting a mobile release — fixing signing or keystores, automating builds with Fastlane/EAS/Gradle, uploading to TestFlight or Play tracks, staged/phased rollout, store listing/metadata, or fixing an App Store/Play review rejection. Distinct from deploy-release (server/web deploys), release-notes (changelog prose), and cicd-pipeline-author (the CI workflow that calls these lanes).
+---
+
+## When to Use
+
+Reach for this skill when the artifact is a **store binary** (`.ipa`/`.aab`) headed for Apple or Google review, not a server rollout:
+
+- "Set up code signing / fix `No profiles for 'com.x' were found` / rotate an expired cert"
+- "Generate or recover an Android keystore; enroll in Play App Signing; upload key vs app-signing key confusion"
+- "Bump the version + build number and ship to TestFlight / Play internal track"
+- "Wire up Fastlane (`gym`/`pilot`/`supply`) or EAS (`eas build`/`eas submit`) in CI"
+- "Do a phased / staged rollout at 1% → 100%, then halt it"
+- "Upload screenshots, description, what's-new, age rating"
+- "Our build got rejected for Guideline 4.3 / 5.1.1 / IAP — fix and resubmit"
+
+NOT this skill:
+- Deploying a server, web app, or container to prod (blue-green, canary pods) → deploy-release
+- Writing the human-facing changelog / what's-new *prose* → release-notes (this skill only *places* the text)
+- Authoring the CI YAML that runs these lanes (job graph, caching, secrets injection) → cicd-pipeline-author
+- Storing the keystore password / App Store Connect API key safely → secrets-management
+
+## Steps
+
+1. **Set versioning first — two independent numbers, never reused.** Marketing version (user-visible) vs build number (uniqueness). Bump the build number on *every* upload even within the same marketing version; stores reject duplicates.
+
+   | Field | iOS (`Info.plist`) | Android (`build.gradle`) | Rule |
+   |---|---|---|---|
+   | Marketing version | `CFBundleShortVersionString` | `versionName` | SemVer `1.4.0`, free-form |
+   | Build number | `CFBundleVersion` | `versionCode` | **Must strictly increase per upload.** iOS: any string with increasing numerics. Android: a single **integer**, monotonic, max 2.1B |
+
+   Default: derive build number from CI run number or commit count (`git rev-list --count HEAD`) so it auto-increments and is reproducible. Use Fastlane `increment_build_number` / `increment_version_code` — never hand-edit and forget.
+
+2. **iOS signing — prefer Fastlane `match`, not Xcode "Automatically manage signing", for CI.** You need a **Distribution certificate** (`.p12`) + an **App Store provisioning profile** bound to the explicit App ID and that cert.
+
+   - `match` stores certs/profiles encrypted in a private git repo (or S3/GCS), so every machine/CI agent shares one cert instead of each minting a new one (Apple caps you at 2–3 distribution certs).
+   - Authenticate CI with an **App Store Connect API key** (`.p8` + key id + issuer id) via `app_store_connect_api_key` — not your Apple ID password / 2FA, which breaks unattended.
+   - Match entitlements to enabled capabilities: Push → `aps-environment: production` in the **release** entitlements; App Groups, Sign in with Apple, Associated Domains must each be toggled on the App ID *and* present in the profile, or the build is signed but the feature silently fails.
+   ```bash
+   # one-time, populates the encrypted repo
+   bundle exec fastlane match appstore
+   # CI: fetch read-only, never regenerate on agents
+   bundle exec fastlane match appstore --readonly
+   ```
+
+3. **Android signing — separate the upload key from the app-signing key.** Enroll in **Play App Signing**: Google holds the *app-signing key* and re-signs your `.aab`; you sign uploads with an *upload key* you control. Losing the upload key is recoverable (reset via support); losing the app-signing key without Play App Signing is fatal — you can never update the app.
+
+   ```bash
+   keytool -genkeypair -v -keystore upload.keystore -alias upload \
+     -keyalg RSA -keysize 2048 -validity 9125 -storetype PKCS12   # 25-yr validity
+   ```
+   - Ship **`.aab`** (App Bundle), not `.apk` — Play requires it for new apps and generates per-device APKs.
+   - Keystore password, key password, alias → secrets store / env, never committed (see secrets-management). Gradle reads them from `~/.gradle/gradle.properties` or env, not `build.gradle`.
+
+4. **Automate the build + upload with one lane per store.** Decide the toolchain up front:
+
+   | Stack | Build | Upload | Use when |
+   |---|---|---|---|
+   | Native iOS | `gym` (`build_app`) → `.ipa` | `pilot` (`upload_to_testflight`) / `deliver` (`upload_to_app_store`) | Bare Xcode project, full control |
+   | Native Android | `gradle bundleRelease` → `.aab` | `supply` (`upload_to_play_store`) | Bare Gradle project |
+   | Expo / RN managed | `eas build -p ios\|android` | `eas submit -p ios\|android` | Expo-managed; EAS handles signing |
+
+   Default to **Fastlane** for bare native and **EAS** for Expo-managed. Minimal Fastfile lanes:
+   ```ruby
+   lane :beta do                          # iOS → TestFlight
+     match(type: "appstore", readonly: true)
+     increment_build_number(xcodeproj: "App.xcodeproj")
+     build_app(scheme: "App", export_method: "app-store")
+     upload_to_testflight(skip_waiting_for_build_processing: true)
+   end
+   lane :play_internal do                 # Android → internal track
+     gradle(task: "bundle", build_type: "Release")
+     upload_to_play_store(track: "internal", aab: "app/build/outputs/bundle/release/app-release.aab")
+   end
+   ```
+   For `supply` you need a **Play Developer API service-account JSON** (`json_key`) with Release Manager permission. For EAS submit, store the same Apple/Google creds in EAS secrets.
+
+5. **Distribute through the right track, then promote — don't ship straight to production.**
+
+   | Store | Tracks (narrow → wide) | Notes |
+   |---|---|---|
+   | TestFlight | Internal (≤100, no review) → External (review, up to 10k via groups/public link) | Internal testers see builds in minutes; external needs Beta App Review |
+   | Play | `internal` → `closed` (alpha/beta) → `open` (beta) → `production` | Promote the *same* build between tracks; don't rebuild |
+
+   Default flow: upload to TestFlight Internal / Play `internal` first, smoke-test, then promote. Gate external/production behind a manual approval.
+
+6. **Roll out in stages with a percentage, never 100% on day one.**
+   - **Play:** set `rollout: 0.01` (1%) on the `production` track via `upload_to_play_store(rollout: "0.01")`, then bump `0.01 → 0.05 → 0.2 → 0.5 → 1.0` over days, watching crash-free rate between steps.
+   - **iOS:** App Store "Phased Release for Automatic Updates" ramps over 7 days automatically (≈1/2/5/10/20/50/100%). Enable it in App Store Connect or via `deliver`'s phased-release flag; it only covers auto-updaters, manual updaters get it immediately.
+
+7. **Fill store metadata so review doesn't bounce on format.** Required: localized title/description, **what's-new** for this version, keywords (iOS), category, **age/content rating** questionnaire, privacy nutrition label (iOS `App Privacy`) / Play **Data safety** form, and **screenshots at every required device size** (e.g. iOS 6.7" + 6.5"; missing a required size blocks submission). Automate text/screenshot upload with `deliver`/`supply` (`metadata/`, `screenshots/` dirs) so it's version-controlled, not hand-pasted.
+
+8. **Pre-flight against the top rejection reasons before you submit.** Address these in the binary/listing, not after a 1-week review round-trip:
+
+   | Reason | Apple guideline | Fix |
+   |---|---|---|
+   | Crash / broken on review device | 2.1 | Test on a clean device + the OS in review; provide working demo creds |
+   | Hidden/incomplete features ("placeholder") | 2.1 | No dead buttons, no "coming soon"; ship only finished flows |
+   | Spam / thin / web-wrapper | 4.3 / 4.2 | Native value beyond a website wrapper |
+   | Login wall with no demo account | 5.1.1 / 2.1 | Put **demo username+password** in Review Notes |
+   | Sign in with Apple missing | 4.8 | Required if you offer 3rd-party social login |
+   | Buying digital goods outside IAP | 3.1.1 | Digital content must use StoreKit IAP, not external payment |
+   | Privacy label mismatch | 5.1 | Declared data collection must match actual SDK behavior |
+
+   Play parallels: target the **current required API level** (`targetSdkVersion`), complete Data safety honestly, declare sensitive permissions, no deceptive metadata. Put credentials and any special-access steps in the review notes field.
+
+9. **After release, watch crash-free rate and keep the halt path one command away.** Monitor crash-free *sessions* (target **≥ 99.5%**) and ANR rate in Crashlytics / Play vitals during ramp. If it regresses below threshold: **Play** → halt rollout in Console or `upload_to_play_store(rollout:)` won't un-ship, so use **"Halt rollout"** (stops further % but doesn't pull installed users) then ship a fixed build. **iOS** → "Pause Phased Release" in App Store Connect; to actually pull a broken build you must **expedite a new build through review** (Apple has no instant rollback). Plan a hotfix lane, not a rollback button.
+
+## Common Errors
+
+- **Reusing a build number.** `ERROR ITMS-90186 / "Version already exists"` (iOS) or `Version code N has already been used` (Play). Always increment per upload, even for the same marketing version.
+- **Each CI agent minting its own distribution cert.** Hits Apple's 2–3 cert cap, then nothing can sign. Use `match --readonly` so agents fetch one shared cert.
+- **Apple ID + password (not API key) in CI.** Breaks on 2FA prompts. Use an App Store Connect API key (`.p8`).
+- **Committing the keystore or its passwords.** Anyone with the repo can sign as you. Keystore + passwords go to a secrets store; `.gradle` properties out of VCS.
+- **Treating the upload key as the app-signing key.** With Play App Signing, Google re-signs; the key in your keystore is only the *upload* key. Don't panic-rotate the wrong one — resetting the upload key is a support flow, not a config change.
+- **Shipping `.apk` to a new Play app.** Rejected — new apps require `.aab`. Use `bundleRelease`, not `assembleRelease`.
+- **Entitlement enabled in Xcode but not on the App ID / profile.** Signs fine, feature dead at runtime (push silently drops, App Group reads empty). Toggle the capability on the App ID and regenerate the profile.
+- **`aps-environment: development` in a store build.** Push notifications work in debug, fail in production. Release entitlements must use `production`.
+- **Missing a required screenshot size.** Submission blocked with no obvious cause. Supply every required device dimension for the platform.
+- **100% rollout on day one.** A crash hits every user at once with no staged escape. Start at 1% and ramp.
+- **Expecting an instant rollback.** Neither store has one. iOS needs an expedited re-review; Play halt only stops *new* installs. Always keep a hotfix lane ready.
+- **Login-walled app with no demo credentials.** Auto-reject under 5.1.1/2.1. Reviewer can't get past the login. Put working creds in Review Notes.
+
+## Verify
+
+1. **Versioning:** the build number is strictly greater than the last accepted upload (check App Store Connect / Play Console history); marketing version is correct.
+2. **iOS signing:** `codesign -dvv <App>.app` shows the **Distribution** cert and the explicit App ID; the embedded profile is the App Store profile and not expired (`security cms -D -i embedded.mobileprovision`).
+3. **Android signing:** `jarsigner -verify -verbose app-release.aab` (or `apksigner verify` on a built APK) passes with the **upload** key; the app is enrolled in Play App Signing.
+4. **Entitlements:** `codesign -d --entitlements - <App>.app` lists every capability the app uses, with `aps-environment: production` for a store build.
+5. **Upload landed:** the build appears in TestFlight Internal / the target Play track and finishes processing without an email rejection (ITMS-* / Play pre-launch report clean).
+6. **Metadata complete:** what's-new, all required screenshot sizes, age/content rating, and the privacy/Data-safety form are filled — the submit button is enabled with no blocking warnings.
+7. **Rollout staged:** production is at the intended start percentage (e.g. 1%), not 100%, and the phased/staged toggle is on.
+8. **Post-release watch:** crash-free sessions and ANR are visible on a dashboard, and you've confirmed the halt/pause control works (locate it, don't trigger it).
+
+Done = a binary with a unique, increasing build number is correctly signed (distribution cert + production entitlements / upload key + Play App Signing), uploaded to the intended track with complete metadata, rolling out at a staged percentage, and the crash-free monitor + halt path are both confirmed available.

package/skills/structured-output-llm/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: structured-output-llm
+description: Gets machine-parseable JSON out of an LLM reliably — prefer provider-enforced grammar (OpenAI `response_format:{type:"json_schema",strict:true}`, Anthropic tool-calling / `tool_choice:{type:"tool"}`, Gemini `responseSchema`) over a "respond in JSON" prompt, define the contract once as a Pydantic/Zod model and validate every response (never trust the string), use constrained decoding / grammars for open weights (Outlines, llguidance, llama.cpp GBNF, vLLM `guided_json`), keep schemas SHALLOW with required fields + enums + `additionalProperties:false`, and build a repair-and-retry loop that handles refusals, `length`/`max_tokens` truncation, and streaming partial JSON (`partial-json-parser`). Schema-guided generation eliminates parse-error retries; validate-and-repair is the backstop, not the primary mechanism.
+when_to_use: You need a model to emit JSON/objects a program consumes — extraction, classification into fixed labels, function arguments, form-filling, or feeding output into another service — and string-parsing or regex on free text keeps breaking. Distinct from prompt-engineering (crafts the instruction/few-shot prose; this skill enforces the output SHAPE via grammar+validation) and agent-tool-mcp-builder (defines the tools/MCP an agent decides to call; this skill is the one-shot "make THIS call return a typed object" half, even when implemented via a single forced tool).
+---
+
+## When to Use
+
+Reach for this skill when a program — not a human — consumes the model's output and the shape must be guaranteed:
+
+- "Extract these 8 fields from this invoice/email as JSON I can `JSON.parse`"
+- "Classify into one of {refund, dispute, question} — give me just the label"
+- "The model returns ```json fences / prose / trailing commas and my parse breaks ~3% of the time"
+- "Function arguments come back malformed or with hallucinated keys"
+- "Fill this form schema" / "map this text to my DB row"
+- "Open-weights model (Llama/Mistral/Qwen) won't reliably produce valid JSON"
+- "Long extraction gets cut off mid-object" or "streaming JSON is unparseable until complete"
+
+NOT this skill:
+- Writing the *instruction*, few-shot examples, role/system prompt, or chain-of-thought prose → prompt-engineering (it shapes WHAT to say; this skill enforces the machine SHAPE of the reply)
+- Defining tools/an MCP server an agent autonomously selects among across many turns → agent-tool-mcp-builder (this skill is one forced, schema-constrained call returning a typed object)
+- Reliability of the whole LLM app — timeouts, fallbacks, circuit-breakers, idempotency around the call → harden-llm-app-reliability (this skill owns only the output-shape contract)
+- Token/latency/cost tuning, caching, model selection → optimize-llm-cost-latency (note: strict schemas cost a cache miss on first use — that skill weighs it)
+- Stopping a malicious payload in retrieved/user text from hijacking the model → defend-llm-prompt-injection (orthogonal; a valid-schema output can still be adversarial content)
+- Retrieval/chunking/grounding that feeds the prompt → rag-pipeline (this skill structures rag's *output* step)
+- Scoring whether the extracted values are *correct* across a dataset → llm-eval-harness (this skill guarantees parseable; that one measures accuracy)
+- Validating ordinary user-submitted form data (no LLM) → build-form-validation
+- The wire/serialization contract between your own services → rest-graphql-contract
+- Scraping the HTML/DOM the text came from → scrape-structured-web-data
+
+## Steps
+
+1. **Prefer provider-enforced schema over a "respond in JSON" prompt — it's a different mechanism, not a stronger hint.** A prompt is a request the model may ignore (fences, preamble, extra keys); enforced schema masks the decoder's token logits so only schema-valid tokens are emittable — invalid JSON becomes *impossible*, not just unlikely. Use the strongest enforcement the provider offers:
+
+   | Provider | Enforcement | How |
+   |---|---|---|
+   | **OpenAI** (gpt-4o+, gpt-4.1, o-series) | Structured Outputs, 100% guaranteed | `response_format:{type:"json_schema",json_schema:{name,schema,strict:true}}` — or `strict:true` on a function tool |
+   | **Anthropic Claude** | Tool-calling (no native json_schema) | define one tool with `input_schema`, set `tool_choice:{type:"tool",name:"..."}` to force it; read `tool_use.input` |
+   | **Google Gemini** | Controlled generation | `generationConfig:{responseMimeType:"application/json",responseSchema:{...}}` (also supports `responseSchema` enums) |
+   | **Azure OpenAI** | same as OpenAI | `response_format` json_schema on `2024-08-01-preview`+ |
+   | **Open weights** (vLLM/TGI/llama.cpp/Ollama) | Constrained decoding (step 5) | `guided_json` / GBNF grammar / Outlines |
+
+   `json_object` mode (the older `{type:"json_object"}`) only guarantees *syntactically* valid JSON, NOT your schema — treat it as a weak fallback, never the goal.
+
+2. **Define the contract ONCE as a typed model; let the SDK emit the schema and parse the result.** Don't hand-write JSON Schema and a parser separately — they drift. Use the model class as the single source of truth:
+   - **Python** → Pydantic v2. OpenAI: `client.beta.chat.completions.parse(..., response_format=MyModel)` → `.choices[0].message.parsed` is a typed instance (or `.refusal`). Or `MyModel.model_validate_json(raw)`.
+   - **TS/JS** → Zod + the OpenAI helper `zodResponseFormat(MySchema, "name")`, then `completion.choices[0].message.parsed`; or `MySchema.parse(JSON.parse(raw))`. (Instructor / `instructor-js` wrap this with retries.)
+   - **Anthropic** → derive `input_schema` from Pydantic via `Model.model_json_schema()` and pass as the tool's input_schema; validate `tool_use.input` back through the model.
+   The rule: **validate every response through the typed model even when the provider guarantees the schema** — guarantees cover JSON-schema-expressible constraints, not your business invariants (date ranges, cross-field rules, enum-of-enums), and self-hosted/fallback paths have no guarantee at all.
+
+3. **Keep the schema SHALLOW and tight — depth and looseness are where models fail and where strict mode rejects you.** Constraints that materially improve reliability:
+   - **`required` everything + `additionalProperties:false`.** OpenAI strict mode *requires* every property be in `required` and forbids additional props — model "optional" as `required` + nullable union (`{"type":["string","null"]}`). This also blocks hallucinated keys.
+   - **Enums over free strings for categories** (`"type":"string","enum":["refund","dispute","question"]`) — turns classification into a closed set the decoder can't escape.
+   - **Flatten.** Prefer a flat object or a top-level `{"items":[...]}` array wrapper over 4-level nesting. Deep/recursive schemas raise latency, hit provider depth/property caps (OpenAI: ≤5000 props, ≤5 nesting for strict), and degrade accuracy.
+   - **Avoid where unsupported:** OpenAI strict mode disallows `minLength`/`maximum`/`pattern`/`format` and many keywords — enforce those in step 2's validator, not the wire schema. (Anthropic/Gemini tolerate more but don't *guarantee* them.)
+   - **Order fields so reasoning precedes the answer:** put a `reasoning`/`evidence` string field *before* the `answer`/`label` field — the model generates them in order, so it "thinks" before committing (cheap, schema-native CoT).
+
+4. **Don't ask for JSON and reasoning in the same free-text turn.** If you need chain-of-thought, either (a) put it inside the schema as a leading field (step 3), or (b) do a two-call split: one reasoning call (free text), one extraction call (strict schema) over the reasoning. Mixing "think step by step, then output JSON" in one un-enforced response is the classic source of prose-before-the-brace parse failures.
+
+5. **For open-weights / self-hosted, use constrained decoding (grammar-level), not prompting.** These enforce validity at the token sampler:
+
+   | Tool | Use | Invoke |
+   |---|---|---|
+   | **vLLM** | production serving | `guided_json=<schema>` / `guided_choice=[...]` / `guided_regex` in `extra_body` (backed by xgrammar/outlines) |
+   | **Outlines** | library, any HF model | `outlines.generate.json(model, PydanticModel)` → returns typed object |
+   | **llguidance / xgrammar** | fast grammar engines | embedded in vLLM/TGI; sub-ms per-token masking |
+   | **llama.cpp / Ollama** | local GGUF | GBNF grammar file, or `format:"json"`+schema (Ollama) |
+   | **TGI** | HF Inference | `grammar:{type:"json",value:<schema>}` |
+
+   Constrained decoding makes invalid JSON *structurally impossible*. Caveat: an over-tight grammar can force the model down an unnatural path and *lower content* quality (it'll fill a required field with junk rather than refuse) — keep the grammar permissive on values, strict on structure, and still validate semantics in step 2.
+
+6. **Build repair-and-retry as the BACKSTOP for paths with no hard guarantee.** Even guaranteed providers can return refusals or truncation; self-hosted/`json_object` paths can emit broken JSON. Ladder:
+   1. **Salvage first (no LLM call):** strip ```` ```json ```` fences and any pre/post prose; extract the outermost balanced `{...}`/`[...]`; libraries: `json-repair` (py), `jsonrepair` (js) fix trailing commas/single quotes/unescaped newlines. Cheap, deterministic — try before re-prompting.
+   2. **Re-prompt with the error:** on `ValidationError`, send the broken output + the exact validator message back ("Your previous reply failed validation: `<pydantic error>`. Return ONLY valid JSON matching the schema.") — Instructor's `max_retries` does exactly this. Cap at **2–3 attempts**; a 4th rarely converges.
+   3. **Feed the schema again** in the repair turn; models drift from it across long contexts.
+
+7. **Handle refusals, truncation, and length explicitly — they are NOT parse errors and must not be "repaired" into garbage.**
+   - **Refusal:** OpenAI returns `message.refusal` (non-null) instead of `parsed`; Anthropic may emit a text block, not the forced tool. Branch on it — surface to the user/safety path, don't retry-loop into the rate limit.
+   - **Truncation:** check `finish_reason == "length"` (OpenAI) / `stop_reason == "max_tokens"` (Anthropic) → the JSON is cut mid-object and is *un*-repairable by salvage. Fix the cause: raise `max_tokens`, shrink the schema/array, or paginate the extraction — don't json-repair a truncated object (it'll silently drop fields).
+   - **Empty/whitespace:** treat as failure, retry once, then fail loud.
+
+8. **Streaming structured output — buffer or parse incrementally, never `JSON.parse` mid-stream.** A partial stream `{"name":"Al` is invalid JSON. Two correct patterns:
+   - **Simplest:** accumulate all deltas, parse once on `finish`. Use when you don't need live UI.
+   - **Incremental:** `partial-json-parser` (js) / `pydantic` partial / OpenAI's streamed-parse helpers / `jsonriver` to coerce the buffer into a valid partial object on each delta for live rendering. For tool-calls, concatenate `tool_call.function.arguments` deltas across chunks (they arrive fragmented) and parse only when the tool-call completes.
+
+9. **Verify.** (a) Round-trip: 100+ live calls on representative inputs → 100% deserialize into the typed model with zero `JSON.parse`/`ValidationError`; assert in CI against a recorded/replayed set. (b) Schema-escape probe: feed adversarial inputs that tempt the model to add commentary or a key — confirm `additionalProperties:false` + strict mode still yields clean objects. (c) Edge branches: force a refusal (policy-tripping input) and a truncation (tiny `max_tokens`) and assert each hits its dedicated branch, not the JSON repairer. (d) Enum closure: classification only ever returns a member of the enum. (e) Open-weights: same round-trip on the self-hosted path with constrained decoding ON, then OFF — confirm the constraint is what's carrying validity. Done = the program never sees a string it can't parse into the typed model, categories are closed enums, refusals/truncation route to their own branches, repair is rare (a metric you watch, not the load-bearing path), and the typed model — not the wire schema — is the single source of the contract.

package/skills/supply-chain-sbom-provenance/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: supply-chain-sbom-provenance
+description: Hardens the software supply chain by generating/validating an SBOM (CycloneDX/SPDX via syft/cdxgen), signing artifacts keylessly (cosign + OIDC), emitting SLSA/in-toto build provenance, pinning deps and base images to digests, and enforcing signature/attestation policy at consumption.
+when_to_use: User must prove what's in an artifact and that it was built from trusted source — producing/consuming an SBOM, signing containers/releases, adding provenance, raising SLSA level, or hardening CI against poisoned deps (EO 14028, EU CRA). Distinct from dependency-upgrade (bumping versions), secrets-management (handling credentials), and security-review (auditing source code).
+---
+
+## When to Use
+
+Reach for this skill when the request is about **proving artifact integrity and origin**, not about the code's behavior:
+
+- "Generate/attach an SBOM to our releases" or "a customer wants a CycloneDX/SPDX SBOM"
+- "Sign our container images / release binaries" (cosign, keyless OIDC)
+- "Add build provenance / attestations" or "get us to SLSA Level 3"
+- "Pin base images to digests, not `:latest`" / "we got hit by a typosquat / dependency-confusion package"
+- "Reject unsigned or unattested images at deploy/admission time"
+- "Keep scanning what we already shipped for new CVEs against the SBOM"
+
+NOT this skill:
+- Bumping a dependency to a newer version / resolving a lockfile → dependency-upgrade
+- Storing/rotating the signing key or registry token itself → secrets-management (this skill prefers **keyless**, so there's no key to store)
+- Auditing the source for vulnerabilities/logic bugs → security-review (this proves *where the artifact came from*, not whether the code is safe)
+- Optimizing the Dockerfile layers/size → dockerfile-optimize
+- Writing the deploy/CI YAML in general → cicd-pipeline-author / gitops-deploy-workflow / deploy-release
+- Enforcing the policy specifically inside Kubernetes manifests → k8s-manifest-review
+
+## Steps
+
+1. **Inventory inputs, then pick format + tool by ecosystem — do not hand-write an SBOM.** An SBOM must cover **direct + transitive** deps, base image layers, and build tools. Choose:
+
+   | Need | Format | Generator | Why |
+   |---|---|---|---|
+   | Container/filesystem, broadest ecosystem coverage | **CycloneDX** (`--output cyclonedx-json`) | **syft** | Best default; reads installed packages from the built image, not just manifests |
+   | Same, when consumer mandates SPDX (US federal / NTIA) | **SPDX** (`--output spdx-json`) | **syft** | One flag swap; emit both if asked |
+   | Source-tree / app deps with rich pURLs + license + VEX | CycloneDX | **cdxgen** | Deeper per-language resolution (npm/maven/gradle/go/pip) |
+
+   Default to **CycloneDX JSON from syft, run against the final built image** (`syft <image>@sha256:... -o cyclonedx-json=sbom.cdx.json`). Generating from source misses what the base image actually ships.
+
+2. **Generate the SBOM in CI as a build step, attach to the release, and validate completeness.** Pin the digest you scanned. A valid SBOM has `bom-ref`/pURL for every component, declared versions, and a license field. Validate, don't trust:
+
+   ```bash
+   syft "$IMAGE@$DIGEST" -o cyclonedx-json=sbom.cdx.json
+   cyclonedx-cli validate --input-file sbom.cdx.json --fail-on-errors   # schema valid
+   jq -e '[.components[] | select(.version==null or .version=="")] | length == 0' sbom.cdx.json  # no unversioned comps
+   ```
+   Reject the build if validation fails. An SBOM with missing versions/hashes is worse than none — it lies.
+
+3. **Pin and verify every input to a hash, never a moving tag.** This is the actual tamper defense; the SBOM only *describes* it.
+   - **Base images:** `FROM node:20.11-bookworm@sha256:<digest>` — never `:latest`, never a bare tag. A tag can be repointed under you.
+   - **Deps:** require a lockfile with **integrity hashes** and install in frozen mode: `npm ci` (uses `package-lock.json` `integrity`), `pip install --require-hashes -r requirements.txt`, `go mod verify` + committed `go.sum`, `cargo --locked`. A lockfile without hashes (or `npm install`, which mutates it) is not pinning.
+   - **Defend dependency-confusion / typosquatting:** set a **scoped private registry** (`@yourscope:registry=...`) so internal names never resolve to public; **reserve your namespace** on the public registry; pin `registry`/`@scope` in `.npmrc`/`pip.conf`; maintain an **allowlist** and fail CI on any new top-level dep not on it. Confusion attacks beat any signature because you signed the wrong package.
+
+4. **Sign artifacts and the SBOM keylessly with cosign via the CI OIDC identity.** No long-lived key to leak or rotate — the signature is bound to the workflow identity and logged in the Rekor transparency log.
+
+   ```bash
+   # cosign 2.x: keyless is the default — no COSIGN_EXPERIMENTAL flag needed
+   cosign sign --yes "$IMAGE@$DIGEST"                                  # keyless, OIDC → Fulcio cert → Rekor
+   cosign attest --yes --type cyclonedx --predicate sbom.cdx.json "$IMAGE@$DIGEST"   # SBOM as an attestation
+   ```
+   Sign the **digest**, not the tag. Pushing a tag after signing leaves the signature pointing at a digest a re-tag can bypass.
+
+5. **Emit SLSA build provenance (in-toto attestation) linking artifact → source commit → builder, then harden to raise the level.** Provenance answers "which commit, which builder, what inputs." On GitHub the cheapest path is the official generator/`actions/attest-build-provenance`; verify the chain with cosign:
+
+   ```bash
+   cosign verify-attestation --type slsaprovenance \
+     --certificate-identity-regexp '^https://github.com/<org>/.+/.github/workflows/.+@refs/' \
+     --certificate-oidc-issuer https://token.actions.githubusercontent.com "$IMAGE@$DIGEST"
+   ```
+
+   | SLSA Build level | Requirement | How to reach it |
+   |---|---|---|
+   | L1 | Provenance exists | Generate + attach any provenance |
+   | L2 | Signed provenance, hosted build | Keyless cosign + CI-hosted runner (above) |
+   | **L3** | Non-falsifiable, isolated build | Use a trusted builder that isolates the run from the steps it builds (reusable trusted workflow); no secrets exposed to user build steps |
+
+   Target **L3** for anything customer-facing; L2 is the floor.
+
+6. **Enforce on consumption — reject unsigned / unattested artifacts at the gate.** Signing nothing-checks is theater. Put a verifying admission/policy controller (e.g. a Sigstore policy controller or `cosign verify` gate in the deploy job) that **denies** images lacking a valid signature *and* required attestations from the *expected* identity:
+
+   ```yaml
+   # policy intent: only images signed by OUR workflow, with an SBOM attestation, may deploy
+   require:
+     signature:
+       issuer: https://token.actions.githubusercontent.com
+       subjectRegExp: ^https://github.com/<org>/<repo>/.github/workflows/release.yml@refs/tags/.+$
+     attestations: [cyclonedx, slsaprovenance]
+   ```
+   Pin the **identity**, not just "is it signed" — anyone can sign with keyless. Fail closed.
+
+7. **Continuously scan the shipped SBOM for new CVEs.** Vulns are disclosed after you ship. Re-scan the stored SBOM on a schedule (not just at build) so a component clean yesterday flags today:
+
+   ```bash
+   osv-scanner scan --sbom sbom.cdx.json --fail-on-vuln    # or: grype sbom:sbom.cdx.json --fail-on high
+   ```
+   Use a VEX document to suppress not-exploitable findings deliberately — never by lowering the threshold.
+
+## Common Errors
+
+- **Pinning to a tag, not a digest.** `FROM python:3.12` / `cosign sign $IMAGE:latest` — a tag is mutable and can be repointed after you scan/sign. Always `@sha256:<digest>`.
+- **SBOM generated from source, attached to a binary built elsewhere.** It won't list the base-image OS packages that actually ship in the artifact. Scan the **built image at its digest**.
+- **`npm install` / unfrozen install in CI.** Mutates the lockfile and can pull an unpinned version, voiding the hashes. Use `npm ci` / `--require-hashes` / `--locked` / `--frozen-lockfile`.
+- **Signing without verifying identity on the consumer side.** `cosign verify` with no `--certificate-identity*` accepts a signature from *anyone* keyless. Always pin issuer + subject regexp.
+- **Treating the SBOM as the tamper control.** The SBOM only *describes*; integrity comes from **digest pins + hashes + signatures**. An accurate SBOM of a poisoned artifact is still poisoned.
+- **Lockfile without integrity hashes.** `go.sum` missing, `requirements.txt` without `--hash=`, a `package-lock.json` from `lockfileVersion:1`. Versions alone don't detect content swaps; require hashes.
+- **Internal package name resolvable on the public registry.** Classic dependency confusion — the public one wins by higher version. Scope it, reserve the name, and allowlist.
+- **Provenance that doesn't bind to a commit/builder.** Provenance with no `materials`/`buildDefinition` source ref proves nothing. It must name the exact commit SHA and builder.
+- **Policy in "audit"/warn mode forever.** A controller that logs violations but admits anyway is not enforcement. Flip to **deny / fail-closed** once green.
+- **Suppressing scanner findings by raising the severity threshold.** Hides real CVEs. Suppress specific not-exploitable CVEs via VEX with a reason, leave the threshold strict.
+- **Storing a long-lived cosign private key in CI secrets.** Defeats the point and creates a rotation burden. Use keyless OIDC; if a key is truly required, that's a secrets-management problem.
+
+## Verify
+
+1. **SBOM completeness:** `cyclonedx-cli validate --fail-on-errors` passes, and `jq` confirms zero components with null/empty `version`. Spot-check that a known base-image OS package (e.g. `glibc`) appears — proves it scanned the image, not just the manifest.
+2. **Digest pinning:** `grep -rE 'FROM .+:[^@]+$' Dockerfile*` returns nothing (every `FROM` ends in `@sha256:`); the lockfile carries integrity hashes; frozen-install command is the one used in CI.
+3. **Signature + attestation present:** `cosign verify --certificate-identity-regexp ... --certificate-oidc-issuer ...` exits `0` against the **digest**, and `cosign verify-attestation --type cyclonedx ...` returns the SBOM predicate. Tampering with one byte of the image flips both to non-zero.
+4. **Provenance binds source+builder:** the SLSA predicate's `buildDefinition`/`materials` names the exact commit SHA and the builder identity; `cosign verify-attestation --type slsaprovenance` exits `0`.
+5. **Enforcement is fail-closed:** deploy an image that is unsigned (or signed by a *different* identity) → the gate/admission controller **denies** it; the legitimately-signed image admits. A wrong-identity signature must be rejected, not just an unsigned one.
+6. **Confusion defense:** attempt to install an internal package name from the public registry → resolution fails or is blocked by the scoped registry/allowlist; a new unlisted top-level dep fails CI.
+7. **Continuous scan wired:** `osv-scanner --sbom ... --fail-on-vuln` (or `grype --fail-on high`) runs on a schedule against the stored SBOM and breaks the job on a new CVE; any suppression is a VEX entry with a reason, not a lowered threshold.
+
+Done = SBOM (CycloneDX/SPDX) validates and is attested to the artifact; every base image and dependency is digest/hash-pinned with confusion defenses; the artifact and SBOM are keyless-signed with SLSA L2+ provenance binding source commit and builder; the consumption gate fails closed against unsigned and wrong-identity artifacts; and a scheduled scanner re-checks the SBOM for new CVEs.

package/skills/test-data-factories/SKILL.md

@@ -0,0 +1,158 @@
+---
+name: test-data-factories
+description: Generates realistic, maintainable test data with factories instead of brittle shared fixtures — factory libraries (Ruby factory_bot, Python factory_boy/model-bakery, PHP Foundry/Faker, JS Fishery/@mswjs/data/Fabbrica, Java instancio/Java-faker, Go fake) that build valid objects with sane defaults, Faker for realistic values, traits/transient params/variants for state, build vs create (in-memory vs persisted), sequences for unique fields, nested associations and object graphs without combinatorial fixtures, deterministic seeding (Faker.seed/locale pinning) for reproducible CI, idempotent upsert-based DB seeders for dev/E2E that re-run cleanly, and anonymized prod-like data via masking/synthesis — so every test declares only the fields it cares about and stays valid as the schema evolves.
+when_to_use: Building test data — replacing shared YAML/SQL fixtures, generating valid model instances for unit/integration/E2E tests, seeding a dev or E2E database idempotently, creating object graphs with associations, or producing anonymized prod-like datasets. Distinct from write-tests (structures the assertions and suite; this generates the inputs they assert on) and validate-data-quality (checks real datasets for nulls/dupes/outliers; this manufactures synthetic data on purpose).
+---
+
+## When to Use
+
+Reach for this skill when you need to manufacture valid, realistic test data and the pain is fixtures that rot or tests coupled to a giant shared dataset:
+
+- "Replace our `fixtures/*.yml` — every schema change breaks 200 tests"
+- "Give me a valid User/Order with just the 2 fields this test cares about"
+- "Build an order with 3 line items, a customer, and an address" (object graph)
+- "Seed the dev/E2E database so `db:seed` is safe to re-run"
+- "Tests pass locally, flake in CI" (non-deterministic random data)
+- "Generate realistic-but-fake names/emails/addresses" (Faker)
+- "Make a prod-like dataset for staging without leaking PII" (anonymize)
+
+NOT this skill:
+- Structuring the assertions, arrange/act/assert, mocking, coverage, test naming → write-tests (it organizes the suite that *consumes* the data this skill builds)
+- Checking a *real* dataset for nulls, dupes, outliers, schema drift → validate-data-quality (it inspects data you didn't generate; this fabricates data on purpose)
+- Profiling/exploring an unfamiliar dataset's distributions → profile-dataset
+- Generating *inputs to find bugs* by shrinking counterexamples → property-based-testing (it searches the input space; this hands you fixed, named, realistic instances)
+- Driving a browser through the app to set up E2E state via the UI/API → write-playwright-e2e (it may *call* this skill's seeder to plant rows directly)
+- Stabilizing a flaky test whose data was already non-deterministic → debug-flaky-tests (seed pinning here is one of its fixes)
+- Safe schema changes / running the migration the seeder targets → db-migration-safety
+- Designing the schema/associations themselves → design-relational-schema
+
+## Steps
+
+1. **Prefer factories over shared fixtures — fixtures are the anti-pattern you're replacing.** A global `users.yml`/seed SQL becomes load-bearing: tests depend on `user(:admin)` having exactly these fields, so any edit ripples across the suite and tests silently couple to unrelated data ("mystery guest"). Factories invert this: a `build(:user)` is valid by default, and each test **overrides only the attributes it asserts on**. Pick the idiomatic library:
+
+   | Stack | Library | Build vs persist |
+   |---|---|---|
+   | Ruby / Rails | **factory_bot** | `build(:user)` (RAM) · `create(:user)` (DB) · `build_stubbed` (no DB, fake id) · `attributes_for` (hash) |
+   | Python / Django | **factory_boy** (`DjangoModelFactory`) or **model-bakery** (`baker.make`/`baker.prepare`) | `.build()` vs `.create()` / `prepare` vs `make` |
+   | Python (plain) | **factory_boy** `Factory` + `faker` | `.build()` only |
+   | JS / TS | **Fishery** (`.build()`), **@mswjs/data**, **Fabbrica** (Prisma), `@faker-js/faker` | build returns object; persist via your ORM |
+   | PHP / Laravel | **Foundry** or Eloquent factories + **fakerphp/faker** | `Model::factory()->make()` vs `->create()` |
+   | Java / Kotlin | **instancio**, **easy-random**, **datafaker** (Java-faker successor) | POJO in memory |
+   | Go | `go-faker`/`gofakeit` + hand-rolled builder funcs | struct in memory |
+
+2. **Make the default object minimally valid; override per test.** The factory's defaults must pass all model validations on their own so `create(:user)` never fails for an unrelated reason. Then a test passes only what it cares about:
+
+   ```ruby
+   # factory_bot
+   factory :user do
+     name  { Faker::Name.name }
+     email { Faker::Internet.unique.email }   # unique → no collisions
+     role  { "member" }
+   end
+   # test asserts on role only:
+   admin = create(:user, role: "admin")       # name/email auto-filled, valid
+   ```
+   ```ts
+   // Fishery
+   const userFactory = Factory.define<User>(({ sequence }) => ({
+     id: sequence,                              // 1,2,3… unique per build
+     email: `user${sequence}@example.test`,
+     role: 'member',
+   }));
+   userFactory.build({ role: 'admin' });        // override one field
+   ```
+   Use the reserved **`example.test`/`example.com`** domains and the `+tag` trick for emails so generated data never hits a real inbox.
+
+3. **Use Faker for realism, but never for fields you assert on.** Faker gives plausible names/emails/addresses/companies so data looks real and surfaces formatting bugs. The discipline: **if a test checks a value, set it explicitly; let Faker fill the rest.** Asserting against a Faker-generated value is a guaranteed flake. Pin locale (`Faker::Config.locale = :en` / `faker.setLocale`) so address/phone formats are stable across machines, and use `unique` generators (`Faker::Internet.unique.email`, `faker.helpers.unique` — note `@faker-js/faker` removed `unique`; use a sequence or `faker.string.uuid` instead) for columns under a UNIQUE constraint.
+
+4. **Sequences for unique/monotonic fields; transient params for build-time knobs that aren't attributes.** Sequences (`sequence(:email) { |n| "user#{n}@example.test" }`) guarantee uniqueness without a global mutable counter. **Transient/transient-params** are inputs that shape the build but aren't columns:
+
+   ```ruby
+   factory :order do
+     transient { line_item_count { 3 } }       # not a column
+     after(:create) do |order, ev|
+       create_list(:line_item, ev.line_item_count, order: order)
+     end
+   end
+   create(:order, line_item_count: 5)
+   ```
+   factory_boy calls these `Params`/`class Params: ...` with `factory.Trait`; Foundry uses `->with()`/states. Reach for them whenever a test wants "an order with N items" without N being an order column.
+
+5. **Model variants with traits, not a forest of sub-factories.** A trait is a named bundle of attribute overrides; compose several in one call. This beats `factory :admin_user`, `factory :suspended_admin_user`, … which explodes combinatorially:
+
+   ```ruby
+   factory :user do
+     trait(:admin)     { role { "admin" } }
+     trait(:suspended) { suspended_at { Time.current } }
+     factory :premium  { plan { "premium" } }   # nested for true subtype
+   end
+   create(:user, :admin, :suspended)            # compose traits
+   ```
+   factory_boy → `class Params:` + `factory.Trait`; Fishery → `.params()` + transient `transientParams`, or named factory variants; model-bakery → recipes. **One base factory + traits** is the maintainable shape; deep factory inheritance is not.
+
+6. **Build object graphs through associations — don't hand-wire foreign keys.** Declare relations so the factory creates the whole graph and back-references resolve automatically:
+
+   | Lib | Association syntax |
+   |---|---|
+   | factory_bot | `association :customer` · `customer { create(:customer) }` · `create_list(:item, 3, order:)` |
+   | factory_boy | `customer = factory.SubFactory(CustomerFactory)` · `factory.RelatedFactory` (reverse) · `factory.List` |
+   | Fishery | `customer: customerFactory.build()` inside the generator, or `associations` param |
+   | Foundry | `CustomerFactory::new()` as an attribute; `->many(3)` for collections |
+
+   **Build the minimal graph the test needs** — pulling in 4 levels of associations slows every test and recreates the fixture problem. Use `build`/`build_stubbed` (no DB) for pure-logic tests; reserve `create` for tests that actually query the DB. Guard against accidental N× object creation in `before` hooks.
+
+7. **Seed dev/E2E databases idempotently — upsert, never blind insert.** A seed script that `INSERT`s breaks on the second run (unique-constraint violation) and corrupts state. Make it re-runnable:
+
+   ```ruby
+   # Rails: find_or_create_by / upsert on a natural key
+   User.find_or_create_by!(email: "demo@example.test") { |u| u.name = "Demo" }
+   ```
+   ```sql
+   INSERT INTO plans (code, name) VALUES ('pro','Pro')
+   ON CONFLICT (code) DO UPDATE SET name = EXCLUDED.name;   -- idempotent
+   ```
+   Rules: key every seed row on a **stable natural key** (slug/code/email), not an auto-id; wrap the whole seed in a transaction; make `db:seed` / `prisma db seed` / `php artisan db:seed` safe to run N times with identical end state. Separate **dev seed** (rich demo data, may be large) from **E2E/test seed** (minimal, deterministic, reset between runs via truncate or transactional rollback). For E2E, prefer planting rows via the factory/seeder directly over driving the UI — orders of magnitude faster and less flaky.
+
+8. **Make data deterministic in CI — pin the RNG seed and locale.** Random factory data that flakes is worse than fixtures. Pin a seed so a failing CI run is reproducible:
+
+   | Tool | Seed control |
+   |---|---|
+   | Faker (Ruby) | `Faker::Config.random = Random.new(RSEED)` |
+   | @faker-js/faker | `faker.seed(12345)` (per-suite, in a `beforeEach`/global setup) |
+   | faker (Python) | `Faker.seed(0)` / `fake.seed_instance(0)` |
+   | factory_boy | `factory.random.reseed_random('seed')` |
+   | RSpec / Jest | `--seed`/`config.seed`; Jest `--testSequencer` + faker seed |
+
+   Print the seed on every run and let CI re-run with a fixed seed to reproduce a failure. **Pin the locale too** — default-locale drift changes address/phone formats and breaks format-sensitive assertions. Don't share mutable factory state across parallel test workers; each worker reseeds.
+
+9. **For prod-like datasets, anonymize — synthesize or mask, never copy raw PII.** Staging/perf data that mirrors prod shape without leaking real people: (a) **synthesize** from factories at volume (`create_list(:user, 100_000)` / a Faker loop) when you only need realistic shape; (b) **mask/anonymize** a prod snapshot when you need real distributions — replace names/emails/SSNs with Faker values, **deterministically** (hash the original → same fake every time, so foreign keys stay consistent), null or tokenize free-text, and shift dates by a constant offset. Tools: pg `anon` extension, `pganonymize`, Snaplet/`@snaplet/seed`, `faker` + a mapping table. Never load an un-anonymized prod dump into a lower environment — that's a PII breach. Keep the anonymization mapping out of the lower environment.
+
+10. **Keep factories close to the code and validated.** Co-locate factories with the test suite (`spec/factories`, `test/factories`, `src/test-utils/factories`), auto-load them, and add a CI lint that **`build`s every factory and asserts it's valid** (factory_bot's `FactoryBot.lint`) so a schema/validation change that breaks a factory fails fast instead of in 50 unrelated tests. When a column is added with a NOT NULL/validation, fix it in the **one** factory, not across the suite.
+
+## Common Errors
+
+- **Shared fixtures as source of truth.** One `users.yml` every test secretly depends on → mystery-guest coupling, schema edits break the world. Fix: factories with per-test overrides; delete the global fixture.
+- **Asserting against a Faker-generated value.** `expect(user.name).to eq(faker_name)` flakes the moment the seed changes. Fix: set asserted fields explicitly; Faker only fills don't-care fields.
+- **Non-deterministic data in CI with no seed.** Intermittent failures no one can reproduce. Fix: pin `faker.seed`/`Faker.seed` and the locale; print and replay the seed.
+- **`create` everywhere when `build` would do.** Hitting the DB (and its associations) for pure-logic tests makes the suite slow and order-dependent. Fix: `build`/`build_stubbed`/`prepare` for in-memory; `create` only when you query.
+- **Non-idempotent seed script.** Blind `INSERT` → second run violates UNIQUE / duplicates rows. Fix: `find_or_create_by` / `ON CONFLICT DO UPDATE` on a natural key; wrap in a transaction.
+- **Sub-factory explosion.** `admin_user`, `suspended_admin_user`, `premium_suspended_admin_user`… Fix: one base factory + composable traits.
+- **Over-deep association graphs.** Every `create` drags in 4 levels of records → slow tests and re-coupled data. Fix: build the minimal graph; stub the rest.
+- **Duplicate-key collisions from static defaults.** A hardcoded `email: "a@b.com"` default fails the second `create`. Fix: sequences or `Faker::Internet.unique` (or `faker.string.uuid` in @faker-js/faker, which dropped `unique`).
+- **Loading raw prod data into staging.** Real PII in a lower environment = breach. Fix: deterministic anonymization/masking or synthesize; keep the mapping out of staging.
+- **Locale drift.** Default Faker locale differs by machine/CI → address/phone format assertions break. Fix: pin the locale explicitly.
+- **Factories that drift from the schema.** A new NOT NULL column makes every `create` fail cryptically. Fix: `FactoryBot.lint`-style CI check that builds every factory.
+
+## Verify
+
+1. **Factories are valid standalone:** run the lint (`FactoryBot.lint` / build-every-factory test) — every factory and trait `build`s and passes validations with zero overrides.
+2. **No fixture coupling:** grep the suite for the old shared fixture references; a test reads only the fields it sets/asserts, and editing an unrelated factory attribute breaks nothing.
+3. **Determinism:** run the suite twice with the same pinned seed → identical data and pass/fail; run with two different seeds → still green (no test asserts a Faker value).
+4. **Uniqueness holds:** create N rows from a factory with a UNIQUE column in a loop → no constraint violation (sequence/`unique`/uuid working).
+5. **Seed is idempotent:** run `db:seed` twice → identical row count and end state, no UNIQUE error; the second run is a no-op or clean upsert.
+6. **build vs create honored:** `build`/`build_stubbed` issues zero SQL INSERTs (assert via query log/`assert_no_queries`); `create` persists exactly the intended graph.
+7. **Traits compose:** `create(:user, :admin, :suspended)` yields both states; no combinatorial sub-factory needed.
+8. **Object graph is minimal and correct:** an order factory creates exactly its declared associations (customer + N items), foreign keys resolve, and no surprise extra records appear.
+9. **Anonymized data is safe:** spot-check the prod-like dataset — no real PII, the masking is deterministic (same input → same fake, FKs consistent), and date/format distributions are realistic.
+
+Done = brittle shared fixtures are gone, each test declares only the fields it cares about against a valid-by-default factory, Faker fills the rest with a pinned seed+locale so CI is reproducible, object graphs and traits compose without sub-factory explosion, the dev/E2E seed is idempotent on a natural key, and any prod-like data is deterministically anonymized — all proven by the factory lint, the twice-with-same-seed run, and the double-seed idempotence check.