@ketecode/loom 0.0.0-stage → 0.2.0

package/skills/tdd-workflow/references/testing-anti-patterns.md

@@ -0,0 +1,87 @@
+# Testing anti-patterns
+
+Read this before adding a mock, a test helper, a cleanup method, or a test for code that already exists. Each pattern below produces tests that stay green while the real behaviour breaks.
+
+## 1. Testing the mock instead of the behaviour
+
+**Symptom:** the assertion checks that a mock was rendered, called or returned its canned value, and nothing else.
+
+```ts
+// Bad: passes as long as the mock exists
+jest.mock('./PriceBadge', () => () => <div data-testid="price-badge" />);
+expect(screen.getByTestId('price-badge')).toBeInTheDocument();
+
+// Good: asserts what the user sees, using the real component
+expect(screen.getByText('GHS 120.00')).toBeInTheDocument();
+```
+
+**Check:** "If I deleted the production code this test covers, would it fail?" If the answer is no, the test is about the mock.
+
+**Fix:** use the real collaborator, or assert on the observable result of the unit under test (return value, state change, output, message sent). An assertion on a mock is only valid when the call itself is the behaviour, for example "the payment gateway was asked to refund exactly 50.00", and even then assert the arguments, not just that a call happened.
+
+## 2. Test-only methods in production code
+
+**Symptom:** a production class grows `reset()`, `_setStateForTest()`, `destroyForTests()` or a public getter that only tests call.
+
+**Why it hurts:** production callers can reach it, it couples the class to the test suite, and it often bypasses invariants the real API enforces.
+
+**Fix:**
+
+- Search the codebase for callers. If only tests call it, move it out.
+- Build the state through the public API, or create a fresh instance per test.
+- Put cleanup in test helpers or fixtures (`afterEach`, a pytest fixture, a `t.Cleanup` func).
+- If the class truly cannot be tested without a back door, the design is telling you something: inject the dependency instead.
+
+## 3. Mocking without understanding the dependency
+
+**Symptom:** a method is mocked "to be safe" or "because it's slow", and the test then passes or fails for reasons nobody can explain.
+
+**Before mocking anything:**
+
+1. Read the real dependency. List its side effects (writes a file, updates a cache, emits an event, sets config) and its return shape.
+2. Decide which of those the test relies on. Mocking a method also removes every side effect the test may need.
+3. Run the test with the real dependency first. Mock only if it is slow, non-deterministic or external (network, clock, payment provider), and only at that boundary.
+
+**Rule:** mock at the lowest level that removes the slow or external part, not the high-level method the test is about.
+
+## 4. Incomplete mocks
+
+**Symptom:** a mocked response contains only the fields the current code reads.
+
+```py
+# Bad: real API also returns "currency" and "metadata"; code that reads them later
+# fails in production while this test stays green
+fake_charge = {"id": "ch_1", "status": "succeeded"}
+```
+
+**Fix:** copy the full shape from the real API's documented response, a recorded fixture or the type definition. Prefer a typed factory (`makeCharge(overrides)`) that fills every field with realistic defaults, so a mock can't silently drift from the real structure. When the real shape changes, update the factory, not every test.
+
+## 5. Tests written after the code
+
+**Symptom:** the test passes the first time it runs.
+
+**Why it hurts:** a test you never saw fail may not be able to fail. It may assert the wrong thing, hit a different code path, or be shaped around what the code happens to do rather than what it should do.
+
+**Fix:**
+
+1. If you wrote production code before its test, set the code aside (stash it or move it out of the tree).
+2. Write the test. Run it. It must fail for the expected reason.
+3. Rebuild the code to make it pass. Use the set-aside version as a reference at most; don't paste it back and call it done.
+4. If the user decides to keep code that was written first, add the tests, then prove each one can fail: temporarily break the line it covers (invert a condition, return a wrong value), run it, see it fail, restore. Tell the user these tests were added after the code.
+
+## 6. Smaller traps
+
+| Trap | Fix |
+|---|---|
+| Expected value computed by the code under test (`expect(f(x)).toBe(f(x))`) | Use a literal or a hand-checked fixture |
+| Asserting on log text or exact error wording only | Assert the behaviour: the returned error type, the status code, the state left behind |
+| One test checks five behaviours | Split it so a failure names the broken behaviour |
+| Shared mutable fixture across tests | Fresh setup per test; tests must pass in any order |
+| Sleeping to wait for async work | Await the promise, use fake timers, or poll for the condition with a timeout |
+
+## Quick gate before committing a test
+
+- Did I see it fail, for the right reason?
+- Would it fail if the behaviour broke, but not if I renamed an internal?
+- Does every mock stand in for something slow or external, with the full real shape?
+- Is every method it calls also used by production code?

package/skills/technical-writing/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: technical-writing
+description: Writes and restructures developer-facing documentation people actually use, such as READMEs, how-to guides, tutorials and API reference, by naming the audience first, organising around the reader's task, shipping copy-paste examples that are run before publishing, and keeping docs beside the code they describe. Use when drafting or rewriting a README, a getting-started or how-to guide, reference docs for a library, CLI or HTTP API, or when docs are confusing, stale or nobody reads them.
+license: MIT
+compatibility: Any Agent Skills host. Running examples needs the project's own toolchain.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: docs
+  kete-loom/risk: runs-commands
+  kete-loom/owner: "Kete-org"
+---
+
+# Technical writing
+
+Docs exist so a reader can finish a task. Every decision below follows from that: know who reads, know what they're trying to do, show them a working path, and keep it true.
+
+## 1. Pin down audience and job
+
+Before writing, answer these. Ask the user for any you can't infer from the repo:
+
+1. **Who reads it?** First-time user, integrating developer, operator, contributor. One primary reader per document.
+2. **What are they trying to do?** Install, try it, solve one specific problem, look up an exact detail, understand a design.
+3. **What do they already know?** Language, framework, domain terms.
+
+The answer to question 2 picks the document type. Don't mix types in one page.
+
+| Reader wants to | Write a | Shape |
+|---|---|---|
+| learn by doing, first time | tutorial | one guided path, every step succeeds, no choices |
+| solve a specific problem | how-to guide | goal in the title, prerequisites, numbered steps, result |
+| look up an exact fact | reference | complete, consistent, structured like the code |
+| understand why | explanation | prose, trade-offs, diagrams, links to the rest |
+
+This is the Diátaxis split. Use it to decide, not as jargon in the docs.
+
+## 2. Structure task-first
+
+- Title says the task or the thing: "Send a webhook test event", not "Webhooks overview".
+- Put the shortest successful path first. Options, edge cases and theory come after.
+- Number steps that must happen in order. One action per step. Put the expected result after the step that produces it.
+- State prerequisites up front (versions, accounts, permissions), never halfway down.
+- Use headings a reader would search for. Keep paragraphs short.
+
+### README order
+
+1. Name and one sentence on what it does and for whom.
+2. Install (one command where possible).
+3. Quick start: the smallest example that does something real, with its output.
+4. Common tasks or a link to guides.
+5. Configuration (table: key, default, meaning).
+6. Links: full docs, contributing, license, support.
+
+Badges, history and architecture go below this or in other files.
+
+## 3. Examples that run
+
+- Every example is complete enough to paste and run: imports, setup, and placeholder values that are obviously placeholders (`YOUR_API_KEY`, `example.com`).
+- Show the expected output or response.
+- Run every example before you publish it, using the project's toolchain. If you can't run one, mark it "not run" in your report and tell the user.
+- Use the project's real names, flags and defaults. Search the code to confirm each one; don't recall them.
+- Label code blocks with their language. Split commands from their output.
+- Never put real secrets, tokens, internal hostnames or customer data in examples.
+
+## 4. Reference docs
+
+- Generate from the source where the project already has a generator (docstrings, OpenAPI, typedoc-style tools). Fix the source comments, not the generated output.
+- For each item: signature or endpoint, parameters (name, type, required, default, meaning), return value or response, errors, one example.
+- Keep the same order and wording pattern for every entry so readers can scan.
+- Document behaviour callers depend on: units, limits, side effects, idempotency, thread safety, deprecation and what replaces it.
+
+## 5. Keep docs with the code
+
+- Put docs in the repo, next to what they describe (`README.md` at package roots, `docs/` for guides, docstrings for reference).
+- When code and docs disagree, the code is the truth. Fix the docs, or tell the user if the code looks wrong.
+- Prefer links over copies. Duplicate text goes stale in one place first.
+- If the project has docs linting, link checking or doctests, run them.
+- When a code change alters behaviour, update docs in the same change. For that job, delegate to the `doc-updater` agent if it's available.
+
+## 6. Style
+
+- Second person, active voice, present tense: "Run `make test`", not "The tests can be run".
+- Plain words. Define a term the first time, then use it the same way every time.
+- Be specific: "takes about 2 minutes", not "may take some time"; "requires Node 18 or later" only after checking the project's engines field or CI.
+- Cut filler: "simply", "just", "easy", "obviously". They insult the reader who's stuck.
+- Follow the project's existing style guide and spelling if it has one.
+
+## Stop and ask
+
+- The audience or document type is unclear and changes the outcome.
+- The docs would describe behaviour you can't confirm in the code.
+- You'd delete or restructure existing docs that other pages or external sites may link to.
+
+## Report back
+
+Return the files you wrote or changed, the reader and document type each targets, which examples you ran (with the command) and which you didn't, and any doc-versus-code mismatches you found. For a guided walkthrough of code, use `code-tour`; for getting oriented yourself, use `codebase-onboarding`.

package/skills/technical-writing/evals/triggers.json

@@ -0,0 +1,14 @@
+{
+  "should_trigger": [
+    "Rewrite our README so someone new can install the CLI and run their first command in five minutes",
+    "Write a how-to guide for rotating API keys in our service",
+    "Our API reference is a mess, restructure the docs for the REST endpoints with examples for each",
+    "Nobody reads our getting-started docs. Can you make them task-first with runnable code samples?"
+  ],
+  "should_not_trigger": [
+    "I renamed the --verbose flag to --debug in this commit, sync the docs and changelog with that change",
+    "Walk me through this unfamiliar repo so I know how to build and run it",
+    "Create a file-by-file tour of the auth flow for new contributors",
+    "Write a blog post announcing our product launch for the marketing site"
+  ]
+}

package/skills/terraform-patterns/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: terraform-patterns
+description: Terraform and OpenTofu infrastructure-as-code practice, from root and child module layout, pinned providers and remote state with locking, through per-environment variables, reading a plan before apply, detecting drift, adopting existing resources with import blocks, and renaming or moving resources safely with moved and removed blocks instead of destroy and recreate. Use when writing or restructuring .tf code, setting up a state backend, reviewing what terraform plan will replace or destroy, or bringing hand-made cloud resources under Terraform.
+license: MIT
+compatibility: Any Agent Skills host. Needs terraform or tofu on PATH and cloud credentials for plan and apply. Commands are the same for both CLIs; substitute tofu for terraform when the project uses OpenTofu.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: devops
+  kete-loom/risk: runs-commands
+  kete-loom/requires: "terraform"
+  kete-loom/owner: "Kete-org"
+---
+
+# Terraform patterns
+
+Change infrastructure through code that plans cleanly, keeps state safe, and never destroys something by accident. Cloud-specific service choices belong to `aws-patterns`, `gcp-patterns` or `azure-patterns`; this skill covers the Terraform layer itself.
+
+## 0. Orient
+
+1. Detect the CLI: `.terraform.lock.hcl`, `required_version`, a `.terraform-version` / `.opentofu-version` file, or CI steps tell you whether it is `terraform` or `tofu`, and which version. Use that one throughout.
+2. Find the root modules (directories with a `backend` block or that CI runs `plan` in), the child modules (`modules/`), and how environments are split (separate root directories per env, workspaces, or a wrapper such as Terragrunt).
+3. Read the backend block. Note where state lives and whether locking is on.
+4. **Stop and ask the user** before `apply`, `destroy`, `import` on the CLI, any `state` subcommand that writes (`mv`, `rm`, `push`), `force-unlock`, or `init -migrate-state`. `fmt`, `validate`, `init` (without migration) and `plan` are fine.
+
+## 1. Layout
+
+```
+modules/
+  network/        main.tf variables.tf outputs.tf versions.tf README.md
+  service/
+envs/
+  dev/            main.tf backend.tf terraform.tfvars versions.tf
+  prod/
+```
+
+- One root module per environment (or per environment and component) with its own state. Keep blast radius small: networking, data stores and apps in separate states when they change at different rates.
+- Child modules take inputs and return outputs; they don't configure providers or backends. Pass providers explicitly (`providers = { aws = aws.eu }`) when a module needs an aliased one.
+- Pin versions: `required_version` in every root, and `required_providers` with a `~>` constraint. Commit `.terraform.lock.hcl` for root modules.
+- Pin module sources: registry modules with `version = "~> x.y"`, git sources with `?ref=<tag>`.
+- Prefer `for_each` over `count` for anything that has identity, so removing one item doesn't shift the indexes of every other.
+
+## 2. Variables and environments
+
+- Declare a `type` and `description` for every variable; add `validation` blocks for values with rules (CIDRs, allowed names).
+- Mark secrets `sensitive = true`, and better, don't pass them as variables at all: read them from a secret manager data source or have the service fetch them at runtime. Sensitive values are still stored in state in plain text.
+- Per-environment values in `envs/<env>/terraform.tfvars` or `-var-file`. Never commit a tfvars file containing secrets.
+- Use `locals` for derived names and common tags instead of repeating expressions.
+
+## 3. Remote state and locking
+
+- Never keep state for shared infrastructure on a laptop or in git. Use a remote backend with locking and encryption: S3 (with `use_lockfile = true` for S3-native locking on current Terraform; the older `dynamodb_table` locking is deprecated), GCS, `azurerm`, HCP Terraform, or the backend the team already uses. Examples are in `references/backends.md`.
+- Turn on versioning for the state bucket so a bad write can be recovered.
+- Restrict who can read state: it contains every attribute of every resource, including secrets.
+- Read another stack's outputs with `terraform_remote_state` or, better, a data source that looks the resource up, rather than copying IDs by hand.
+- If a lock is stale (a crashed run), confirm with the user that no run is in progress before `force-unlock <LOCK_ID>`.
+
+## 4. The plan is the review
+
+Run `terraform plan -out=tfplan` and read it before anything is applied.
+
+1. Read the summary line: `Plan: X to add, Y to change, Z to destroy`.
+2. Search the plan for `must be replaced`, `forces replacement` and `will be destroyed`. For each, name the attribute that forces it.
+3. Treat replacement or destruction of a stateful resource (databases, buckets, disks, DNS zones, KMS keys, clusters, IAM roles other systems depend on) as a stop: explain it to the user and propose an alternative (a `moved` block, `ignore_changes` for an attribute managed elsewhere, or an in-place change).
+4. Check for unexpected changes to resources you didn't touch: that is drift or a provider upgrade, not your change. Report it separately.
+5. Apply only the saved plan (`terraform apply tfplan`), so what runs is exactly what was reviewed.
+
+For machine-readable checks: `terraform show -json tfplan` and look at `resource_changes[].change.actions` for `"delete"`.
+
+Protect critical resources with `lifecycle { prevent_destroy = true }`, and use `create_before_destroy = true` where a replacement must not cause downtime.
+
+## 5. Drift
+
+- `terraform plan -refresh-only` shows what changed outside Terraform without proposing to revert it.
+- Decide per item with the user: bring the code in line with reality, or let the next apply revert the manual change. Don't silently revert a hotfix someone made in the console.
+- `-detailed-exitcode` (exit 2 means changes) lets CI detect drift on a schedule.
+
+## 6. Safe refactors
+
+Renaming or moving a resource address without telling Terraform plans a destroy and a create. Use config-driven blocks, which show up in the plan and get reviewed like any other change:
+
+```hcl
+moved {
+  from = aws_s3_bucket.logs
+  to   = module.logging.aws_s3_bucket.this
+}
+
+import {
+  to = aws_s3_bucket.assets
+  id = "my-existing-assets-bucket"
+}
+
+removed {
+  from = aws_instance.legacy
+  lifecycle { destroy = false }   # forget it, keep the real resource
+}
+```
+
+- `moved` for renames, `count` → `for_each`, and moving resources into or out of modules. The plan should then show no destroy for those addresses.
+- `import` blocks to adopt existing resources; `terraform plan -generate-config-out=generated.tf` drafts the matching configuration. Edit the generated code until plan shows no changes for the imported resource.
+- `removed` with `destroy = false` to stop managing something without deleting it.
+- These blocks need a reasonably recent CLI, and Terraform and OpenTofu added them (and options such as `removed`'s `lifecycle { destroy = false }`) in different releases. Check the docs for the CLI and version in `required_version`; if not, stop and ask before falling back to `terraform state mv` / `state rm`, which change state immediately and skip review.
+- Keep `moved` blocks in shared modules for at least one release so every caller's state migrates; remove `import` and `removed` blocks after the apply.
+
+## 7. Verify
+
+Run, and report each as pass or fail:
+
+1. `terraform fmt -check -recursive`
+2. `terraform init -backend=false` then `terraform validate` in each changed root (no credentials needed).
+3. Linters the project already uses (`tflint`, `checkov`, `trivy config`).
+4. `terraform plan` in each affected environment if credentials are available; paste the summary line and every replace or destroy.
+
+## Never
+
+- Never run `apply -auto-approve` or `destroy` on the user's behalf without explicit approval for that environment.
+- Never edit a state file by hand or commit `*.tfstate`, `.terraform/` or secret-bearing tfvars.
+- Never use `-target` as a routine workflow; it is for recovery, and leaves the rest of the config unreviewed.
+- Never upgrade a provider's major version as a side effect of another change.
+
+## Report back
+
+End with: CLI and version, roots changed, the plan summary per environment (add/change/destroy) with every replacement or destroy named and justified, the verification commands with pass or fail, and anything you could not plan because of missing credentials.

package/skills/terraform-patterns/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "I renamed a resource in our Terraform and now plan wants to destroy and recreate the database",
+    "Set up an S3 remote state backend with locking for our Terraform project",
+    "We created a bunch of buckets by hand in the console, how do I bring them under Terraform?",
+    "Restructure our tf code into reusable modules with separate dev and prod environments",
+    "terraform plan shows changes nobody made, how do I check for drift?"
+  ],
+  "should_not_trigger": [
+    "Should we use Cloud Run or GKE for this service on Google Cloud?",
+    "Write a Kubernetes Deployment with resource limits for the API",
+    "Review this terraform plan output and the k8s manifests for risky or destructive changes",
+    "Add a GitHub Actions job that builds and pushes our Docker image",
+    "Containerise the Python worker with a slim base image"
+  ]
+}

package/skills/terraform-patterns/references/backends.md

@@ -0,0 +1,67 @@
+# Remote state backends
+
+Check the backend's docs for your CLI version before copying; argument names change between releases.
+
+## AWS S3 (S3-native locking)
+
+```hcl
+terraform {
+  backend "s3" {
+    bucket       = "acme-terraform-state"
+    key          = "prod/network/terraform.tfstate"
+    region       = "eu-west-1"
+    encrypt      = true
+    use_lockfile = true   # writes a .tflock object next to the state
+  }
+}
+```
+
+- The bucket should have versioning on, public access blocked, and default encryption (SSE-S3 or SSE-KMS).
+- With `use_lockfile`, the caller needs `s3:GetObject`, `s3:PutObject` and `s3:DeleteObject` on the lock object as well as the state object.
+- Migrating from `dynamodb_table` locking: the two can be set together during the transition. Add `use_lockfile = true`, run `terraform init -reconfigure`, confirm runs create the `.tflock` object, then remove `dynamodb_table`.
+
+## Google Cloud Storage
+
+```hcl
+terraform {
+  backend "gcs" {
+    bucket = "acme-terraform-state"
+    prefix = "prod/network"
+  }
+}
+```
+
+GCS locks natively. Enable object versioning on the bucket.
+
+## Azure Storage
+
+```hcl
+terraform {
+  backend "azurerm" {
+    resource_group_name  = "rg-terraform"
+    storage_account_name = "acmetfstate"
+    container_name       = "tfstate"
+    key                  = "prod/network.tfstate"
+  }
+}
+```
+
+Azure locks via blob leases. Enable blob versioning or soft delete on the storage account.
+
+## Partial configuration
+
+Keep environment-specific backend values out of shared code:
+
+```hcl
+terraform {
+  backend "s3" {}
+}
+```
+
+```sh
+terraform init -backend-config=backend.prod.hcl
+```
+
+## Changing backends
+
+`terraform init -migrate-state` copies state to the new backend. Before running it: confirm with the user, take a copy with `terraform state pull > backup.tfstate` (store it securely, it contains secrets), and make sure no other run is in progress.

package/skills/test-coverage-improvement/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: test-coverage-improvement
+description: Raises meaningful test coverage by measuring line and branch coverage, ranking untested code by risk and churn, adding tests that pin observable behaviour rather than executing lines, and using mutation testing (Stryker, PIT, mutmut, cargo-mutants, Infection) to prove the new tests catch faults. Use when coverage is low or below a CI threshold, when asked where tests are missing in a module, or when a team wants coverage numbers they can trust.
+license: MIT
+compatibility: Any Agent Skills host. Needs the project's test runner and its coverage tool; mutation testing tools are optional.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: testing
+  kete-loom/risk: runs-commands
+  kete-loom/owner: "Kete-org"
+---
+
+# Test coverage improvement
+
+Coverage tells you what code ran during tests, not what was checked. The goal is fewer escaped bugs, so spend tests where a bug would hurt and make every test assert something a user or caller would notice.
+
+## 1. Measure the baseline
+
+1. Find the existing coverage command in CI, package scripts or the Makefile. Use it if it exists.
+2. Otherwise run the language default with **branch** coverage on where the tool supports it (Go reports statement coverage only; `cargo llvm-cov --branch` needs a nightly toolchain):
+
+| Stack | Command |
+|---|---|
+| Jest | `npx jest --coverage` |
+| Vitest | `npx vitest run --coverage` (needs `@vitest/coverage-v8`) |
+| Python | `pytest --cov=<pkg> --cov-branch --cov-report=term-missing` (pytest-cov) |
+| Go | `go test -coverprofile=cover.out ./...` then `go tool cover -func=cover.out` |
+| Rust | `cargo llvm-cov` (cargo-llvm-cov) or `cargo tarpaulin` |
+| Java | JaCoCo via `mvn verify` or `gradle jacocoTestReport` |
+| .NET | `dotnet test --collect:"XPlat Code Coverage"` |
+| PHP | `vendor/bin/phpunit --coverage-text` (needs Xdebug or PCOV) |
+
+3. Record: total line %, branch %, and the per-file numbers. If the suite fails, **stop and tell the user** first; coverage from a red suite is meaningless.
+4. If adding a coverage tool would add a dependency the project doesn't have, ask before installing it.
+
+## 2. Find the risky gaps
+
+Do not sort by "lowest %". Rank untested code by risk:
+
+1. **Money, auth, permissions, data deletion, migrations** and anything security-sensitive.
+2. **Branches with no test**: `else` paths, error handlers, early returns, `catch` blocks, default cases. Branch coverage reports show these as partial lines.
+3. **High churn**: files changed often recently (`git log --since=6.months --name-only --format= | sort | uniq -c | sort -rn | head -20`). Churn plus low coverage is where regressions come from.
+4. **Recent bugs**: code touched by recent fix commits.
+5. Public API used by many callers.
+
+Skip, and say you skipped: generated code, trivial getters and setters, framework glue with no logic, and code scheduled for deletion. Prefer excluding them in coverage config (with a comment) over writing hollow tests.
+
+Write the top 5 to 10 targets as a list with the reason each one is risky, and confirm with the user if the list is long.
+
+## 3. Write behaviour tests
+
+For each target:
+
+- Name the behaviour: "rejects a refund larger than the original charge", not "test refund function".
+- Drive it through the public interface the callers use.
+- Assert the observable result: return value, raised error and its type or message, state persisted, message sent. One behaviour per test.
+- Cover the branch you found: the error path, the boundary (0, 1, max, empty, null), the permission denied case.
+- Mock only external boundaries (network, clock, randomness, third-party services). Never mock the unit under test or its own collaborators just to reach a line.
+- Follow the existing test style, folders and fixtures.
+
+A test that would pass if the code under test returned a wrong value is not a test. Avoid:
+
+- No assertion, or `expect(result).toBeDefined()` / `assert result is not None` as the only check.
+- Snapshotting large output nobody reviews.
+- Asserting that a mock was called, without checking the outcome.
+- Calling a function in a loop over inputs just to light up lines.
+
+## 4. Check with mutation testing
+
+Mutation testing changes the code (flips `>` to `>=`, removes a call, returns a constant) and reruns the tests. A surviving mutant is a fault your tests don't catch.
+
+| Stack | Tool | Run |
+|---|---|---|
+| JS/TS | StrykerJS | `npx stryker run` |
+| Java/Kotlin (JVM) | PIT | `mvn org.pitest:pitest-maven:mutationCoverage` |
+| Python | mutmut | `mutmut run`, then `mutmut results` |
+| Rust | cargo-mutants | `cargo mutants` |
+| PHP | Infection | `vendor/bin/infection` |
+| C# | Stryker.NET | `dotnet stryker` |
+
+- Scope it to the files you just tested; a full-repo run can take hours.
+- For each surviving mutant: add or sharpen an assertion that kills it, or note it as equivalent (the change cannot alter behaviour).
+- If no tool exists for the stack, do it by hand for the riskiest function: break one condition, run the tests, confirm one fails, revert.
+
+## 5. Re-measure and lock in
+
+1. Rerun the coverage command. Report before and after for the files you touched, line and branch.
+2. If CI has a threshold, meet it. If it has none, suggest a ratchet (fail only if coverage drops) rather than an arbitrary target.
+3. Run the full suite twice to check the new tests are deterministic.
+
+## Rules
+
+- Never delete, skip or weaken existing tests to change the number.
+- Never add tests that assert current buggy behaviour without flagging it. If you find a bug, **stop and tell the user**, and write the test for the correct behaviour marked as expected-to-fail only if they agree.
+- Never exclude risky code from coverage to raise the percentage.
+- Don't chase 100 %. Stop when the risky list is covered and mutants are killed.
+
+## Report back
+
+```
+Coverage: <line>% → <line>% lines, <branch>% → <branch>% branches (files touched)
+Tests added: <file>: <test names>
+Mutation: <killed>/<total> killed in <files>; survivors: <list or none>
+Bugs found: <list or none>
+Not covered, on purpose: <items and why>
+Command: <exact commands run>
+```

package/skills/test-coverage-improvement/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "Our coverage is stuck at 52% and CI wants 70, add tests where they actually matter",
+    "Which parts of the billing module have no tests? Fill the important gaps",
+    "Run mutation testing on the discount rules and tighten the tests that let mutants survive",
+    "We have 90% line coverage but bugs still slip through, make the tests mean something",
+    "Find the untested error-handling branches in src/payments and cover them"
+  ],
+  "should_not_trigger": [
+    "Implement the CSV export feature test-first",
+    "Look at the tests in this PR and list the cases that are missing for the changed code",
+    "Add a Playwright test for the password reset journey",
+    "Benchmark the new JSON parser against the old one",
+    "Run the build, lint and tests and tell me if my branch is green"
+  ]
+}

package/skills/threat-modeling/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: threat-modeling
+description: STRIDE threat modelling for a planned feature or an existing system, done before or alongside the code. Maps the data flow, trust boundaries and assets, enumerates spoofing, tampering, repudiation, information disclosure, denial of service and elevation of privilege threats per element, and ends with a ranked list of mitigations the team can turn into tickets. Use when designing a feature that touches auth, money, personal data, uploads, webhooks or third-party integrations, when someone asks what could go wrong or how this could be attacked, or before a security sign-off on an architecture.
+license: MIT
+compatibility: Any Agent Skills host. Reads design docs and code only; no tools required.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: security
+  kete-loom/risk: read-only
+  kete-loom/owner: "Kete-org"
+---
+
+# Threat modelling (STRIDE)
+
+Answer four questions for one feature or system: what are we building, what can go wrong, what are we doing about it, and did we do a good enough job. Keep it lightweight: one sitting, one document, a ranked list at the end. This skill designs defences; it does not review a diff line by line (use the security-review skill or the security-reviewer agent for that).
+
+## 1. Set the scope
+
+1. Name the one feature, service or flow being modelled. If the request is "the whole platform", **stop and ask** which flow matters most and model that first.
+2. Collect what exists: design doc, ticket, API spec, architecture diagram, or the code if it is already built (search for route definitions, queue consumers, webhook handlers, cron jobs, outbound HTTP clients).
+3. Note the assumptions you are making (hosting, who the users are, which parts are out of scope). List them in the output; a wrong assumption is the most common reason a model misses the real threat.
+
+## 2. Draw the data flow
+
+Write a text data-flow diagram. Use five element types:
+
+| Element | Example |
+|---|---|
+| External entity | browser user, admin, partner API, payment provider |
+| Process | API server, worker, Lambda, LLM agent with tools |
+| Data store | Postgres, S3 bucket, Redis, log pipeline |
+| Data flow | HTTPS request, queue message, webhook, file upload |
+| Trust boundary | internet to edge, app to database, tenant A to tenant B, your code to a third party |
+
+```
+[User browser] --HTTPS (session cookie)--> (API) --SQL--> [(orders DB)]
+        ======= boundary: internet | VPC =======
+(API) --HTTPS (secret key)--> [Payment provider] --webhook (signed)--> (API)
+```
+
+Mark every place data crosses a trust boundary. Threats cluster there.
+
+## 3. List the assets
+
+What would hurt if stolen, changed or made unavailable: credentials and tokens, personal data, payment state, money movement, admin capability, availability of a critical path, audit logs, model prompts and tool permissions. Rate each **high, medium or low** by impact.
+
+## 4. Walk STRIDE per element
+
+For each element and each boundary-crossing flow, ask the questions that apply:
+
+| Threat | Property broken | Applies to | Ask |
+|---|---|---|---|
+| **S**poofing | Authentication | entities, processes | Can someone pretend to be this user, service or webhook sender? |
+| **T**ampering | Integrity | flows, stores, processes | Can input, a message, a file or a stored row be changed in transit or at rest? Can the client set a price, role or owner ID? |
+| **R**epudiation | Non-repudiation | entities, processes | Could a user deny an action and we can't prove otherwise? Are security events logged with who, what, when? |
+| **I**nformation disclosure | Confidentiality | flows, stores, processes | Can data leak via responses, errors, logs, URLs, caches, backups, other tenants, or an LLM's output? |
+| **D**enial of service | Availability | flows, stores, processes | Can one caller exhaust CPU, memory, connections, queue depth, paid API quota or disk? Is there a rate limit and size limit? |
+| **E**levation of privilege | Authorization | processes | Can a normal user reach admin actions, another tenant's data (IDOR), or code execution via injection or deserialisation? |
+
+Rules while walking:
+
+- Write each threat as **actor + action + asset + consequence**: "An unauthenticated caller replays a captured webhook to mark an unpaid order as paid."
+- Only list threats that are plausible for this design. Skip a STRIDE letter for an element when it genuinely does not apply; don't pad.
+- Check what already mitigates it (framework CSRF protection, signed webhooks, row-level security). Record it; a threat with a working control is still worth listing at low priority.
+
+## 5. Rate and decide
+
+Rate each threat with a simple likelihood x impact (each high, medium or low). Do not invent precise scores. Then pick one response:
+
+- **Mitigate**: add a control (name the concrete one: "verify HMAC on raw body", "scope query by tenant_id", "argon2id hashing").
+- **Eliminate**: remove the feature or data (don't store card numbers; don't log tokens).
+- **Transfer**: move it to a provider built for it (hosted payment page, managed identity provider).
+- **Accept**: only the user or owner can accept a risk. **Stop and ask** before marking anything high as accepted.
+
+## 6. Check your work
+
+- Every trust boundary has at least one threat considered.
+- Every high asset has at least one threat and one control.
+- Every mitigation is specific enough to become a ticket and to test.
+- Re-read the assumptions: if one is false, which threats change?
+
+## Never
+
+- Never produce a generic OWASP list unrelated to the diagram.
+- Never claim the system is secure; say what was modelled and what was not.
+- Never mark a high risk as accepted on the user's behalf.
+- Never include real secrets, hostnames or customer data from the codebase in the document.
+
+## Output format
+
+```
+# Threat model: <feature>
+Scope: <what is in and out>    Date: <date>
+Assumptions: <bulleted>
+
+## Data flow
+<text diagram with trust boundaries marked>
+
+## Assets
+| Asset | Impact |
+
+## Threats
+| ID | STRIDE | Element / flow | Threat (actor, action, asset, consequence) | Existing control | L | I | Response |
+
+## Prioritised mitigations
+1. [high] T3, T7: <concrete control> (owner: ?, test: <how to prove it works>)
+2. ...
+
+## Open questions
+<things only the team can answer>
+```
+
+Order the mitigations by risk (high likelihood and high impact first), and group threats fixed by one control into a single line.