@causyne/agent 0.0.0-stage → 1.10.0

package/native-skills/python/packaging-and-distribution/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: packaging-and-distribution
+description: Package a Python project for distribution or make it installable. Use when a project has setup.py only, when imports fail after install, or before publishing to an index.
+---
+
+# Packaging and Distribution
+
+## The current shape
+
+`pyproject.toml` with a PEP 621 `[project]` table. `setup.py` is legacy; `setup.cfg` is superseded. A new project should have neither.
+
+## Workflow
+
+1. Choose the layout.
+   - `src/` layout: the package lives in `src/mypkg/`. This is the correct default, because it makes it impossible to import the package from the working directory — so the tests exercise the INSTALLED package, which is what users get.
+   - Flat layout imports from the source tree and hides packaging bugs until release.
+   - **Done when:** the package is under `src/` and the tests still pass.
+
+2. Declare the metadata once.
+   - Name, version, description, requires-python, dependencies, and the entry points. Read the version from a single source — either the package or the manifest — never both.
+   - **Done when:** `python -m build` produces a wheel and a source distribution without warnings.
+
+3. Pin ranges, not exact versions, for a library.
+   - A library that pins exact versions makes itself uninstallable alongside anything else. An application may pin exactly, and should, via a lock file.
+   - **Done when:** the dependency specifiers match the kind of project.
+
+4. Test the built artefact, not the source tree.
+   - Install the wheel into a clean environment and import it. A package that works in-tree and fails on install has a missing `package-data` entry or a wrong layout, and only this step catches it.
+   - **Done when:** the wheel installs and imports in a fresh environment.
+
+5. Check what is inside the artefact.
+   - `python -m zipfile -l dist/*.whl`. Look for missing data files and for accidentally included test or secret files.
+   - **Done when:** the wheel contains exactly what should ship.
+
+## Template
+
+```toml
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "mypkg"
+version = "0.1.0"
+requires-python = ">=3.11"
+dependencies = ["httpx>=0.27,<1.0"]
+
+[project.scripts]
+mypkg = "mypkg.cli:main"
+```
+
+## Verification
+
+- `python -m build` succeeds with no warnings.
+- The wheel installs into a clean environment and the entry point runs.
+- The archive listing contains no test files and no credentials.

package/native-skills/python/pytest-suite-design/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: pytest-suite-design
+description: Write or restructure Python tests. Use when tests share mutable state, when a suite is slow, or when failures are hard to read.
+---
+
+# Pytest Suite Design
+
+## Workflow
+
+1. Make each test independent.
+   - A test that depends on another having run first will fail under `-p no:randomly`, under `-n auto`, and in any order but the current one. Shared module-level state is the usual cause.
+   - **Done when:** the suite passes with tests shuffled and with parallel execution.
+
+2. Use fixtures for setup, not for cleverness.
+   - A fixture should produce one thing and clean it up with `yield`. Scope it as narrowly as correctness allows: `function` by default, wider only when construction is genuinely expensive AND the object is immutable.
+   - A mutable `session`-scoped fixture is shared state with extra steps.
+   - **Done when:** no fixture wider than `function` scope is mutated by a test.
+
+3. Parametrise instead of duplicating.
+   - `@pytest.mark.parametrize` turns eight near-identical tests into one with eight cases, each reported separately. Give the cases `ids` so a failure names the case rather than an index.
+   - **Done when:** no two tests differ only by literal values.
+
+4. Assert on behaviour, not implementation.
+   - Assert what the function returns and what it does to the world. Asserting that a private helper was called with particular arguments locks the implementation and makes every refactor a test rewrite.
+   - **Done when:** the tests still pass after an internal refactor that preserves behaviour.
+
+5. Isolate the outside world.
+   - No test touches the real network, the real clock, or a real database unless it is explicitly an integration test and marked as one. `monkeypatch`, `freezegun`, and `responses` cover most of it.
+   - **Done when:** the unit suite passes with the network disabled.
+
+6. Make failures self-explanatory.
+   - One logical assertion per test, and a name that states the expected behaviour: `test_expired_token_is_rejected`, not `test_auth_2`.
+   - **Done when:** a failure name alone communicates what broke.
+
+## Verification
+
+- `pytest -p no:randomly --randomly-seed=last` and `pytest -n auto` both pass.
+- The unit suite passes with no network access.
+- Every test name reads as a statement about behaviour.

package/native-skills/python/type-hints-and-static-checking/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: type-hints-and-static-checking
+description: Add or fix type annotations in Python. Use when a codebase has no hints, when a type checker reports many errors, or when a function signature is ambiguous.
+---
+
+# Type Hints and Static Checking
+
+## Where annotations pay
+
+Public function signatures and data structures. Annotating every local variable adds noise without adding information — the checker infers those.
+
+## Workflow
+
+1. Turn the checker on before writing annotations.
+   - `mypy` or `pyright`. Start non-strict on an existing codebase; a first run in strict mode on untyped code produces thousands of errors and gets switched off.
+   - **Done when:** the checker runs and its current error count is recorded.
+
+2. Annotate boundaries first.
+   - Public functions, class attributes, and anything crossing a module edge. This is where a wrong assumption actually costs something.
+   - **Done when:** every public function has annotated parameters and a return type.
+
+3. Use the modern syntax.
+   - `list[str]` not `List[str]`. `str | None` not `Optional[str]`. `dict[str, int]` not `Dict[str, int]`. The `typing` aliases are deprecated.
+   - **Done when:** no import from `typing` exists that a builtin generic replaces.
+
+4. Never reach for `Any` to silence an error.
+   - `Any` disables checking for everything it touches and spreads. If the type is genuinely unknown, `object` is honest and forces a narrowing check at the point of use.
+   - **Done when:** every remaining `Any` has a comment saying why.
+
+5. Ratchet strictness upward.
+   - Enable one strict flag at a time and fix the errors it produces. `disallow_untyped_defs` module by module via per-module settings is the usual path.
+   - **Done when:** the error count is zero at the current strictness and one more flag is enabled.
+
+6. Type the tricky shapes properly.
+   - `TypedDict` for a dictionary with known keys, `Protocol` for structural typing instead of an abstract base class, `Literal` for a fixed set of strings, and `TypeVar` for a function whose return type depends on its input.
+   - **Done when:** no function returns a bare `dict` where a `TypedDict` describes it.
+
+## Verification
+
+- The type checker reports zero errors at the configured strictness.
+- CI runs the checker and fails on a new error.
+- No new `Any` was introduced without a justification.

package/native-skills/security/authorization-model/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: authorization-model
+description: Decide who may do what. Use when adding permissions, when a user can access another user`s data, or when authorization checks are scattered across handlers.
+---
+
+# Authorization Model
+
+## The distinction that gets missed
+
+Authentication is who you are. Authorization is what you may do. A system with excellent authentication and no authorization lets any logged-in user read every record — and that class of bug (broken object-level authorization) is consistently the most common serious web vulnerability.
+
+## Workflow
+
+1. Check ownership on every single object access.
+   - Not just on the list endpoint. `GET /orders/123` must verify that order 123 belongs to the caller. Relying on the UI not to show the link is not a control — the identifier is guessable and the endpoint is public.
+   - **Done when:** every by-identifier endpoint verifies the caller's relationship to that object.
+
+2. Deny by default.
+   - The absence of a rule means no. A system where an unmatched route falls through to allow will leak on the first forgotten annotation.
+   - **Done when:** a new endpoint with no rule is inaccessible.
+
+3. Centralise the decision, distribute the enforcement.
+   - One function answers "may this subject perform this action on this object". Handlers call it; they do not reimplement it. Scattered inline checks drift, and the one that drifts is the hole.
+   - **Done when:** there is one authorization entry point and every handler uses it.
+
+4. Enforce at the data layer where you can.
+   - A query scoped to the caller's tenant by construction cannot leak, even from a handler that forgot to check. Row-level security or a mandatory scope on the repository turns a class of bug into an impossibility.
+   - **Done when:** the default query path cannot return another tenant's rows.
+
+5. Model roles as permissions, not as titles.
+   - Check `may_refund_order`, not `is_admin`. Title checks scattered through the code make adding a role a codebase-wide change.
+   - **Done when:** no branch tests a role name directly.
+
+6. Log the denials.
+   - A spike in denials is either a bug or an attack. Both are worth seeing.
+   - **Done when:** denials are logged with subject, action and object.
+
+## Verification
+
+- A test attempts to read another user's object by identifier and receives 404 or 403.
+- A new endpoint without a rule is denied.
+- The default repository query is tenant-scoped.

package/native-skills/security/crypto-usage/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: crypto-usage
+description: Encrypt, hash, sign, or generate randomness. Use whenever cryptography is being written or reviewed.
+---
+
+# Cryptography Usage
+
+## The rule
+
+Do not build it. Use a vetted library at the highest level of abstraction available. Cryptographic code fails silently — it produces output that looks correct and provides no security — so "it works" tells you nothing.
+
+## The correct primitives
+
+- **Password storage** — argon2id, or bcrypt. Never a general-purpose hash: they are fast by design, which is exactly wrong here.
+- **Symmetric encryption** — an authenticated mode: AES-GCM or XChaCha20-Poly1305. Unauthenticated encryption is malleable, and the attack is practical.
+- **Random values** — the platform's cryptographically secure generator. Never a general-purpose random function for a token, an identifier, or a nonce.
+- **Comparing secrets** — constant-time comparison. A normal comparison returns early on the first differing byte and leaks the secret through timing.
+- **Signing** — Ed25519, or ECDSA on P-256. Verify with the algorithm you expect, never with the one named in the token.
+- **Key derivation** — HKDF from a high-entropy secret, argon2 or scrypt from a password.
+
+## Workflow
+
+1. State what you are protecting against.
+   - Encryption at rest protects a stolen disk, not a compromised application. Naming the threat prevents solving the wrong problem.
+   - **Done when:** the threat and what the mechanism does not cover are both written down.
+
+2. Never reuse a nonce with a key.
+   - Nonce reuse in GCM is catastrophic — it reveals the plaintext relationship and the authentication key. Generate randomly, or use a counter that provably never repeats. XChaCha20's larger nonce makes random generation safe.
+   - **Done when:** nonce generation is shown never to repeat for a given key.
+
+3. Plan key rotation from the start.
+   - Store a key identifier with the ciphertext so old data stays readable while new data uses a new key. Retrofitting this requires decrypting everything.
+   - **Done when:** ciphertext carries a key identifier.
+
+4. Keep keys out of the application.
+   - A key management service or the platform keystore. A key in the environment is a key in every crash dump, log aggregator, and process listing.
+   - **Done when:** no key material appears in source, config, or environment.
+
+5. Verify before you use.
+   - Check the authentication tag or signature BEFORE decrypting or parsing. Acting on unverified data is the whole vulnerability.
+   - **Done when:** every verification precedes every use.
+
+## Verification
+
+- No hand-rolled primitive exists.
+- Secret comparison is constant-time.
+- Nonce generation cannot repeat.
+- Keys are external to the application and rotatable.

package/native-skills/security/dependency-supply-chain/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: dependency-supply-chain
+description: Add, update, or audit dependencies. Use when introducing a package, when an advisory appears, or when reviewing what a project pulls in.
+---
+
+# Dependency Supply Chain
+
+## The exposure
+
+A dependency runs with your process's full privileges. Its dependencies do too, and a typical project has hundreds it never chose. Most real compromises come through this path rather than through your own code.
+
+## Workflow
+
+1. Justify each direct dependency before adding it.
+   - What does it do, how much does it weigh, how many transitive dependencies does it bring, when was it last released, how many maintainers. A one-function package with forty dependencies is a bad trade.
+   - **Done when:** the addition is justified against writing it yourself.
+
+2. Check the package is the one you mean.
+   - Typosquatting relies on a plausible name. Confirm the exact name, the repository link, and the download count. A brand-new package with a familiar name is the classic attack.
+   - **Done when:** the package's repository and history are confirmed.
+
+3. Commit the lock file and install from it.
+   - `npm ci`, `pip install -r` with hashes, `poetry install`, `cargo build --locked`. An install that resolves fresh versions in CI means the artefact you tested is not the artefact you shipped.
+   - **Done when:** CI installs from the lock file and fails if it is out of date.
+
+4. Refuse install scripts you have not read.
+   - A lifecycle script runs arbitrary code at install time, in your CI, with your credentials. Where the ecosystem allows disabling them by default, do.
+   - **Done when:** the install-time script surface is known and minimised.
+
+5. Automate advisory scanning, and triage rather than ignore.
+   - Run the ecosystem audit in CI. For each finding, decide: upgrade, replace, or accept with a written reason and an expiry. A permanently ignored advisory is a decision nobody revisits.
+   - **Done when:** every open advisory has an action or a dated acceptance.
+
+6. Pin what you cannot verify.
+   - Actions and containers by digest, not by tag. A mutable tag can be repointed after review.
+   - **Done when:** CI actions and base images are pinned to digests.
+
+## Verification
+
+- The lock file is committed and CI installs from it.
+- The audit runs in CI and has no unreviewed findings.
+- Every CI action is pinned by digest.

package/native-skills/security/input-validation-and-injection/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: input-validation-and-injection
+description: Handle data that came from a user, a request, or a third party. Use when building a query, a command, a template, or a path from external input.
+---
+
+# Input Validation and Injection
+
+## The single principle
+
+Never build a command out of a string containing untrusted data. Every injection class — SQL, shell, template, path, header, log — is the same mistake: data crossing into a position where it is read as instructions.
+
+## By interpreter
+
+- **SQL** — parameterised queries only. Bind the value; never interpolate. Identifiers that must be dynamic come from an allowlist, because they cannot be bound.
+- **Shell** — pass an argument array to the spawn API, never a joined string, and never through a shell. Where a shell is unavoidable, an allowlist of complete commands is the only safe form.
+- **Path** — resolve, then verify the result is inside the permitted root. `../` traversal survives naive prefix checks and survives decoding twice.
+- **HTML** — contextual escaping, applied by the template engine. Never build markup by concatenation. Untrusted markup goes through a sanitiser with an allowlist.
+- **Headers and logs** — strip carriage returns and newlines. A newline in a header splits the response; in a log it forges an entry.
+- **Deserialisation** — never deserialise untrusted data into arbitrary types. Parse into a declared schema.
+
+## Workflow
+
+1. Map every entry point.
+   - Request bodies, query strings, headers, cookies, uploads, webhooks, environment, third-party API responses, and data read back from your own database that was written by a user.
+   - **Done when:** every source of external data is listed.
+
+2. Validate on the way in, against a schema.
+   - Type, range, length, format, and an allowlist where the set is finite. Reject rather than sanitise: sanitising guesses at intent and is bypassable.
+   - **Done when:** every entry point parses into a validated type before use.
+
+3. Escape on the way out, per context.
+   - The same value needs different escaping in HTML, in an attribute, in JavaScript, in a URL. One "escape" function applied everywhere is wrong in at least three of those.
+   - **Done when:** escaping is applied by the sink, matched to the sink.
+
+4. Enforce size limits everywhere.
+   - Body size, field length, array length, upload size, and nesting depth. Without them, one request exhausts memory.
+   - **Done when:** every unbounded input has a stated limit.
+
+## Verification
+
+- No query, command, or path is built by string concatenation with external data.
+- Traversal payloads are rejected.
+- A newline in a header value does not split the response.
+- Oversized input is rejected before allocation.

package/native-skills/security/secure-file-uploads/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: secure-file-uploads
+description: Accept file uploads from users. Use when adding an upload feature, or when uploaded files are served back to users.
+---
+
+# Secure File Uploads
+
+## Why this is its own topic
+
+An upload endpoint lets a stranger place a file of their choosing on your infrastructure. The failure modes span storage exhaustion, remote code execution, stored cross-site scripting, and server-side request forgery — and the naive implementation hits several of them.
+
+## Workflow
+
+1. Limit size before reading.
+   - Enforce at the reverse proxy AND in the application. Streaming a body into memory to check its length is already the denial of service.
+   - **Done when:** an oversized upload is rejected before the body is buffered.
+
+2. Determine the type from the content, not the name.
+   - Read the magic bytes. The extension and the declared content type are both attacker-controlled. Validate against an allowlist of types you actually support — never a denylist.
+   - **Done when:** a file renamed to a permitted extension is rejected on its real content.
+
+3. Never use the supplied filename.
+   - Generate your own identifier and store the original name only as a display label. The supplied name can contain traversal sequences, null bytes, or a name that means something to the filesystem.
+   - **Done when:** the stored path is derived entirely from server-generated values.
+
+4. Store outside the web root, and serve deliberately.
+   - Files in a served directory can be requested directly, which turns an uploaded script into an executed one. Store in object storage or outside the root, and serve through a handler that sets the content type and `Content-Disposition: attachment`, plus `X-Content-Type-Options: nosniff`.
+   - **Done when:** an uploaded HTML file downloads rather than renders.
+
+5. Serve user content from a separate origin.
+   - Same-origin user content means a served file can script against your session. A distinct domain contains it.
+   - **Done when:** user uploads are served from a domain that holds no session.
+
+6. Process images out-of-process and re-encode.
+   - Image parsers are a large attack surface. Re-encoding strips embedded payloads and metadata, including location data users did not intend to share.
+   - **Done when:** stored images are re-encoded and stripped of metadata.
+
+7. Scan, and quarantine until clean.
+   - **Done when:** a file is unreachable until it has passed scanning.
+
+## Verification
+
+- An oversized upload is rejected early.
+- A renamed executable is rejected on content inspection.
+- An uploaded HTML file downloads rather than executes.
+- Uploaded images carry no location metadata.

package/native-skills/security/security-headers-and-csp/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: security-headers-and-csp
+description: Configure HTTP security headers or a Content Security Policy. Use when hardening a web application, or when a security scan reports missing headers.
+---
+
+# Security Headers and CSP
+
+## The headers that matter, in order of value
+
+1. **Content-Security-Policy** — the only one that meaningfully mitigates cross-site scripting. Also the only one requiring real work.
+2. **Strict-Transport-Security** — forces https for a long max-age. Include subdomains once you are sure.
+3. **X-Content-Type-Options: nosniff** — stops the browser guessing a content type, which is how an uploaded text file becomes a script.
+4. **Referrer-Policy: strict-origin-when-cross-origin** — stops paths and query strings leaking to third parties.
+5. **X-Frame-Options / frame-ancestors** — clickjacking. Prefer the CSP directive.
+6. **Permissions-Policy** — deny camera, microphone and geolocation unless used.
+
+## Workflow
+
+1. Deploy CSP in report-only mode first.
+   - A strict policy applied directly will break the site. Report-only collects violations without enforcing, and the report tells you what the site actually depends on.
+   - **Done when:** a week of reports has been collected and reviewed.
+
+2. Build the policy from a nonce, not from an allowlist.
+   - Host allowlists are routinely bypassable through a permitted CDN. A per-response nonce with `strict-dynamic` is the current guidance and is far more robust.
+   - **Done when:** the policy uses a per-response nonce and no host wildcard.
+
+3. Remove what the policy forbids, rather than weakening the policy.
+   - Inline handlers and inline styles are what force `unsafe-inline`, and `unsafe-inline` removes most of the protection. Move them to files or nonce them.
+   - **Done when:** the policy contains no `unsafe-inline` and no `unsafe-eval`.
+
+4. Keep a reporting endpoint after enforcement.
+   - Violations in production are either a bug you introduced or an injection attempt. Both are worth seeing.
+   - **Done when:** violations continue to be collected after enforcement begins.
+
+5. Set the headers at one layer.
+   - The reverse proxy or a single middleware. Headers set in several places conflict, and the browser takes the most restrictive — usually not the one you were reading.
+   - **Done when:** each header is emitted exactly once.
+
+## Verification
+
+- An observatory or header scan reports no missing header.
+- The CSP contains no `unsafe-inline`, no `unsafe-eval`, and no wildcard host.
+- An injected inline script is blocked and reported.
+- Every response carries each header exactly once.

package/native-skills/security/threat-modelling/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: threat-modelling
+description: Assess the security of a feature or system. Use before building anything that handles money, personal data, or authentication, and during a security review.
+---
+
+# Threat Modelling
+
+## The four questions
+
+What are we building, what can go wrong, what will we do about it, and did we do a good job. Everything else is elaboration.
+
+## Workflow
+
+1. Draw the data flow.
+   - Components, data stores, external entities, and the trust boundaries between them. A boundary is anywhere data crosses from less trusted to more trusted — that is where controls belong and where they are usually missing.
+   - **Done when:** every trust boundary in the feature is marked.
+
+2. Enumerate threats per boundary.
+   - Walk the categories: spoofing identity, tampering with data, repudiation, information disclosure, denial of service, elevation of privilege. Apply each to each boundary rather than brainstorming freely — free brainstorming misses whole categories.
+   - **Done when:** every boundary has been walked through all six.
+
+3. Rank by realistic impact and likelihood.
+   - Not everything gets fixed. Say which are accepted and why, and record the acceptance.
+   - **Done when:** each threat is mitigated, transferred, or accepted in writing.
+
+4. Name a specific control per mitigated threat.
+   - "Validate input" is not a control. "Reject requests whose body exceeds 1MB at the reverse proxy" is.
+   - **Done when:** every mitigation names a concrete, testable mechanism.
+
+5. Test the controls.
+   - A control nobody attempted to bypass is a hypothesis. Write the test that tries.
+   - **Done when:** each control has a test attempting to defeat it.
+
+## The threats people forget
+
+- The admin interface, which usually has weaker controls than the user-facing one.
+- The background job, which often runs with elevated privilege and no authorization check.
+- The error path, which frequently leaks internal detail.
+- The third-party integration, which is trusted implicitly.
+- The recovery flow, which is frequently weaker than the login it can bypass.
+
+## Verification
+
+- A diagram exists with boundaries marked.
+- Every boundary has been walked through all six categories.
+- Every mitigation names a mechanism and has a test.

package/native-skills/testing/end-to-end-test-stability/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: end-to-end-test-stability
+description: Write or fix browser or device end-to-end tests. Use when tests fail intermittently, when they rely on sleeps, or when a suite is disabled because it is unreliable.
+---
+
+# End-to-End Test Stability
+
+## Where flakiness comes from
+
+Almost always timing: the test acts before the application is ready. Fixed sleeps do not fix this — they make it rarer and slower, which is the worst of both.
+
+## Workflow
+
+1. Replace every sleep with a condition.
+   - Wait for the element to be visible and enabled, for the request to complete, for the loading state to disappear. Modern frameworks auto-wait on assertions; use them rather than hand-rolled polling.
+   - **Done when:** the suite contains no fixed-duration sleep.
+
+2. Select by what the user perceives.
+   - Role and accessible name, then visible text, then a dedicated test identifier. Never a CSS class or an XPath through the DOM structure — those break on every styling change and test nothing meaningful.
+   - **Done when:** no selector depends on styling or DOM nesting.
+
+3. Isolate each test's data.
+   - Every test creates what it needs with unique values and cleans up. Shared fixtures mean tests interfere and cannot run in parallel — and the failure appears in whichever test ran second.
+   - **Done when:** the suite passes with tests run in a random order and in parallel.
+
+4. Control the network.
+   - For anything but a deliberate integration test, intercept and stub external calls. A third party's rate limit or outage should not fail your build.
+   - **Done when:** the suite passes with external network access blocked.
+
+5. Capture evidence on failure.
+   - Screenshot, DOM snapshot, video, and network log. A CI failure with no artefact costs an hour of local reproduction, and some failures do not reproduce locally at all.
+   - **Done when:** a failing run leaves artefacts sufficient to diagnose without re-running.
+
+6. Keep the suite small and critical.
+   - Cover the handful of journeys whose breakage would be an emergency. An end-to-end test for every form is a suite nobody waits for.
+   - **Done when:** every end-to-end test covers a journey that would be an incident if broken.
+
+## Verification
+
+- Twenty consecutive runs pass without a retry.
+- The suite passes in a random order and in parallel.
+- A deliberate failure leaves a screenshot and a network log.

package/native-skills/testing/property-based-testing/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: property-based-testing
+description: Test a function with many valid inputs. Use when example tests keep missing edge cases, when testing a parser, serialiser, or algorithm, or when input space is large.
+---
+
+# Property-Based Testing
+
+## The shift
+
+Instead of "for this input, expect this output", state a property that must hold for EVERY input, and let the framework generate hundreds of them — including the pathological ones nobody thinks to write: empty, one element, duplicates, maximum integers, unusual Unicode.
+
+## The properties worth reaching for
+
+- **Round trip** — `decode(encode(x)) == x`. The single most valuable property, and it applies to every serialiser, parser and codec.
+- **Invariant** — sorting preserves length and multiset; a transfer preserves the total balance.
+- **Idempotence** — `f(f(x)) == f(x)`. Normalisers, formatters, deduplicators.
+- **Oracle** — the fast implementation agrees with the obviously correct slow one.
+- **Commutativity or ordering** — order of independent operations does not change the result.
+
+## Workflow
+
+1. Pick the property before the generator.
+   - Write the invariant as a sentence first. A generator without a property is just random input.
+   - **Done when:** the property is stated in one sentence.
+
+2. Generate the real input domain.
+   - Constrain the generator to what the function actually accepts, but no further. Over-constraining hides the bugs; the framework's default string generator producing surrogate pairs and combining characters is a feature, not a nuisance.
+   - **Done when:** the generator covers the documented domain and nothing outside it.
+
+3. Use the shrunk counterexample.
+   - On failure the framework reduces the input to a minimal failing case. That minimal case is usually the whole diagnosis.
+   - **Done when:** the reported failure is minimal and reproducible from its seed.
+
+4. Keep the failing case as a regression test.
+   - Add the specific counterexample as an ordinary example test. Property tests are randomised; a pinned example guarantees this exact bug stays fixed.
+   - **Done when:** each discovered failure has a pinned example test.
+
+5. Combine, do not replace.
+   - Properties catch classes of bugs; examples document intent and pin known cases. A suite needs both.
+   - **Done when:** the module has both property and example tests.
+
+## Verification
+
+- Each property runs several hundred cases in CI.
+- A deliberately introduced off-by-one is caught.
+- Every past failure has a pinned regression test.

package/native-skills/testing/regression-test-from-a-bug/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: regression-test-from-a-bug
+description: Fix a reported bug. Use whenever a defect is being fixed, before writing the fix itself.
+---
+
+# Regression Test from a Bug
+
+## The order
+
+Test first, then fix. A test written after the fix passes immediately, and you never learn whether it would have caught the bug. This is the single highest-value testing discipline and the most commonly skipped.
+
+## Workflow
+
+1. Reproduce it before you understand it.
+   - Get the exact inputs, state and steps. A bug you cannot reproduce cannot be verified as fixed, and "I could not reproduce it" is not a resolution.
+   - **Done when:** you can trigger the bug on demand.
+
+2. Write a failing test at the lowest level that captures it.
+   - Reduce the reproduction to the smallest unit that still fails. A bug reproduced through the whole UI is usually a unit-level bug once narrowed.
+   - **Done when:** the test fails, and it fails with the same symptom the user reported.
+
+3. Understand the cause before changing anything.
+   - The first plausible explanation is often wrong. Confirm it by predicting a second observable consequence and checking for it.
+   - **Done when:** you can explain why the code produced this exact wrong result.
+
+4. Fix the cause, not the symptom.
+   - A null check that suppresses a crash leaves the wrong value flowing through the system. Ask where the null came from.
+   - **Done when:** the fix addresses where the wrong value originated.
+
+5. Look for siblings.
+   - The same mistake is usually made in more than one place. Search for the pattern before closing.
+   - **Done when:** the codebase has been searched for the same shape and the results addressed.
+
+6. Confirm the test now passes and the rest still does.
+   - **Done when:** the new test is green, the suite is green, and reverting the fix turns the new test red.
+
+## Verification
+
+- The test failed before the fix and passes after.
+- Reverting the fix makes it fail again.
+- A search for the same pattern elsewhere has been done and reported.

package/native-skills/testing/snapshot-and-visual-regression/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: snapshot-and-visual-regression
+description: Use snapshot or visual regression tests. Use when UI changes break silently, when snapshots are updated without review, or when a large snapshot file has appeared.
+---
+
+# Snapshot and Visual Regression Testing
+
+## The failure mode of snapshots
+
+They are trivial to update. When a snapshot fails, the fastest action is to accept the new one, and that becomes reflexive — at which point the snapshot records what the code does rather than what it should do, and catches nothing.
+
+## Workflow
+
+1. Snapshot small, meaningful units.
+   - A component's rendered output, a serialised payload, a formatted error. Never a whole page — a large snapshot fails on every unrelated change and is never actually read.
+   - **Done when:** every snapshot is small enough to review in a diff.
+
+2. Review every snapshot change deliberately.
+   - The diff is the test result. Accepting it without reading is the same as deleting the test.
+   - **Done when:** each snapshot change in a review has a stated reason.
+
+3. Remove non-determinism before snapshotting.
+   - Timestamps, identifiers, ordering, and floating-point formatting. Replace them with stable placeholders — otherwise the snapshot fails randomly and gets updated reflexively.
+   - **Done when:** ten consecutive runs produce identical snapshots.
+
+4. Render visual tests in a controlled environment.
+   - A container with pinned fonts and a fixed device pixel ratio. Font rendering differs between operating systems, so screenshots taken on a laptop will never match CI.
+   - **Done when:** the same commit produces identical screenshots locally and in CI.
+
+5. Set a sensible pixel tolerance.
+   - Zero tolerance flags anti-aliasing noise. Too high hides real regressions. Tune it against a known-good pair.
+   - **Done when:** the threshold catches a one-pixel layout shift but ignores anti-aliasing.
+
+6. Prefer explicit assertions where they are clearer.
+   - "The submit button is disabled" is a better test than a snapshot containing a disabled attribute somewhere. Reach for snapshots when the output is large and the shape is the point.
+   - **Done when:** behavioural rules are asserted explicitly, not implied by a snapshot.
+
+## Verification
+
+- Ten runs produce no spurious diff.
+- Local and CI screenshots match on the same commit.
+- Each snapshot is small enough to review.