@kensio/skills 1.13.1

package/skills/isolated-testing-style/SKILL.md

@@ -0,0 +1,293 @@
+---
+name: isolated-testing-style
+description: Write tests that start from given/when/then, use real collaborators through simulation rather than stubs and mocks, take their isolation from randomised data rather than shared setup and teardown, and assert behaviour rather than call counts. Use when writing or reviewing tests, when a test needs a collaborator faked, when reaching for a mock, spy, `toHaveBeenCalledWith`, `beforeEach`/`afterEach` fixtures or a hardcoded expected hash, when test setup has grown tangled, and when asked "how should I test this?".
+license: Apache-2.0
+metadata:
+  version: "1.13.1"
+---
+
+# Isolated testing style
+
+An opinionated way of writing tests. The examples are TypeScript and vitest, but the rules are about
+test design and hold for any framework. Each rule exists because of a specific failure it would have
+caught.
+
+## Start with Given, When, Then
+
+Write the three comments before the test body, and before the code they will drive.
+
+```typescript
+it("refuses an order once the offer has closed", async () => {
+  // Given an offer that closed while the customer was on the page.
+  // When the order is placed against it.
+  // Then it is refused rather than accepted late.
+});
+```
+
+Starting at this point, and not drifting to it, does three things.
+
+**It lowers the cost of starting.** You only have to say what the situation is, what happens, and
+what should result. That is a smaller question than "how do I test this?", and you can usually
+answer it before you can answer the bigger one.
+
+**It designs the interface.** Filling in `// When` forces you to name the single action under test,
+in the caller's vocabulary. A step you cannot write as one `// When` usually means the interface is
+wrong.
+
+**It keeps the test readable as documentation.** Tests are read far more often than they are
+written, and without the structure it is easy to produce a body where essential behaviour and
+incidental setup look alike.
+
+Then fill each comment in with the case it covers, and never with a restatement of the code:
+
+```typescript
+it("refuses an order once the offer has closed", async () => {
+  // Given an offer that closed while the customer was on the page.
+  const offer = await offerFactory.make({ closesAt: aMinuteAgo });
+
+  // When the order is placed against it.
+  const placing = placeOrder(orderFactory.make({ offerId: offer.id }));
+
+  // Then it is refused rather than accepted late.
+  await expect(placing).rejects.toThrow(OfferClosedError);
+});
+```
+
+`// Given an offer` restates the code and adds no information.
+`// Given an offer that closed while the customer was on the page` says which case this is and why
+it matters. This holds whether or not the test is written first.
+
+## Prefer real collaborators through simulation
+
+A stub asserts that your code called something. A simulator asserts that it called the service
+correctly.
+
+That difference is the whole argument. A stub answers whatever you told it to answer. It agrees with
+your understanding of the API by construction. It cannot disagree with you, which means it cannot
+find the case where your understanding is wrong. A simulator holds real state and applies the real
+rules. A wrong call fails at the point the real service would have failed.
+
+The evidence comes from a real project. Replacing AWS SDK stubs with a simulator immediately caught
+two bugs that had already shipped.
+
+- A Secrets Manager secret name ending in a hyphen and six characters. AWS appends exactly that
+  suffix to a secret ARN. The name was ambiguous with the ARN form, which AWS advises against. The
+  stub had no opinion, because a stub has no naming rules.
+- A Cognito `SECRET_HASH` computed the wrong way. The stub accepted it, because the stub was never
+  going to check a signature.
+
+So the order to reach for things:
+
+1. A simulator that holds real state and applies real rules.
+2. The real thing, when it runs in process and needs no external service.
+3. A stub, only for something with no rules worth modelling, such as a clock or a random source.
+
+The first two options need the implementation to be swappable, so give each collaborator a single
+point of entry, one place that wires the real service in production and a simulation in tests. The
+driver pattern is one way to arrange that, but the name matters far less than the swap having one
+home.
+
+Simulating in process pays off beyond avoiding stubs. No deployment is needed before running the
+tests, a debugger steps through the collaborator's state alongside your own, and no state is shared
+between processes, so several layers can be exercised together and still run in parallel at the
+speed of a unit test.
+
+Be honest about the limit. An in-memory implementation only approximates the real service, and
+cannot be relied on to behave identically. Keep a thin layer of tests against the real thing for the
+flows where that matters, and treat any divergence you find as a bug in the simulation rather than a
+quirk to work around.
+
+## Keep setup cheap and independent
+
+Tangled shared fixtures come from economics. Discipline has little to do with it. Teams share setup
+roughly in proportion to how expensive it is to build. When getting a test into the right state
+means threading through a web of existing fixtures, reusing what is already there is the rational
+move, and each reuse adds another edge to the graph. That is how a suite arrives at setup that no
+one dares to touch.
+
+The fix is to share differently. Shared factories for test entities are exactly what you want. A
+factory that constructs a type is worth writing once and using everywhere. What has to be avoided is
+those factories getting tangled up with each other. Each piece of setup should stand on its own.
+
+Independence comes from taking dependencies explicitly rather than reaching for ambient state. A
+factory that is handed what it needs stays pure, and the test decides what to hand it.
+`@kensio/part-factory` builds this in. Factories take a `dependencies` object as a second argument
+at call time. A factory that needs a simulated AWS is handed one, and never goes looking.
+
+```typescript
+// Given an order that exists in this test's own simulated AWS.
+const simAws = new SimAws();
+const order = await orderFactory.make({ total: 5000 }, { simAws });
+```
+
+A factory built that way can be shared as widely as you like and still stand on its own, because
+everything it does is independent of what another factory did first. Prefer collaborators and
+factories that need only instantiation, with no side effects, no cleanup and no coordination.
+
+For a step specific to one test, ask whether the step belongs to the test or the test belongs to the
+step. A helper confined to one file can be pulled back inline later if it stops earning its place,
+whereas a fixture that a large part of the suite is built on cannot. Reversibility is the thing to
+preserve, and locality on its own earns little.
+
+## Take isolation from randomised data
+
+Randomised values make collisions impossible. No teardown is required, and there is no ordering to
+depend on. Randomised is enough. Guaranteed uniqueness is unnecessary, and a UUID has no realistic
+chance of colliding anyway.
+
+Do not do this:
+
+```typescript
+// Anti-pattern: shared name, mutable handle, teardown to undo it.
+let bucketName: string;
+
+beforeEach(async () => {
+  bucketName = "uploads-bucket";
+  await createBucket(bucketName);
+});
+
+afterEach(async () => {
+  await emptyBucket(bucketName);
+  await deleteBucket(bucketName);
+});
+```
+
+That test cannot run beside another test using the same name, the `let` is only mutable so that
+`afterEach` can reach it, and a failure part way through leaves the next test to fail for a reason
+unrelated to it.
+
+Do this instead:
+
+```typescript
+it("serves an uploaded object", async () => {
+  // Given a bucket no other test can be talking about.
+  const bucketName = `uploads-${faker.string.uuid()}`;
+  await createBucket(bucketName);
+
+  // ...
+});
+```
+
+The environment those tests run against can be shared, and should be built the way production is
+built. A realistic environment that several tests read from is closer to production than a minimal
+one rebuilt per test, and it is faster. The isolation comes from the names and identifiers, so
+sharing the environment is free.
+
+Faker is the source of these values. Prefer a generator that produces a realistic value of the right
+kind (`faker.internet.email()`, `faker.string.uuid()`, `faker.company.name()`) over a counter or a
+literal with a suffix. The test data also exercises the shapes production data has.
+
+## Assert observable behaviour
+
+A call count asserts how the code is written today. A behaviour assertion holds however it is
+written, which is what lets you refactor.
+
+To prove a value is cached, do not count calls. Delete the underlying resource, then show the cached
+value still comes back:
+
+```typescript
+it("keeps serving the secret after it is deleted", async () => {
+  // Given a secret that has been read once, so it is cached.
+  const first = await config.databasePassword();
+
+  // When the underlying secret goes away.
+  await simAws.secretsManager().deleteSecret(
+    new DeleteSecretCommand({ SecretId: secretName }),
+  );
+
+  // Then the cached value is still served, without going back to the service.
+  expect(await config.databasePassword()).toEqual(first);
+});
+```
+
+To prove a retry, make the first call fail and the second succeed, then assert on the result:
+
+```typescript
+// Given an endpoint that fails once and then works.
+// When the client calls it.
+// Then it gets the successful response.
+```
+
+Both hold whether the cache is a `Map`, a memoised promise or a decorator, and whether the retry is
+a loop, a middleware or a library.
+
+## Never pin a value computed by the code under test
+
+Pinning a hash you generated by running the same function only proves the function is deterministic.
+It will keep passing after the function becomes wrong, as long as it is wrong consistently.
+
+```typescript
+// Anti-pattern: this string came from running computeSecretHash.
+expect(computeSecretHash(username, clientId, clientSecret)).toBe(
+  "z0Xq9k1e4mVQ...",
+);
+```
+
+Two ways out, in order of preference:
+
+1. Let a real implementation validate it. A simulated Cognito checks a `SECRET_HASH` the way Cognito
+   checks it. A sign-in that succeeds against the simulation is evidence the hash is right.
+2. Pin against an independent authority, such as a value from the service's own documentation, a
+   published test vector, or a value produced by a different implementation.
+
+The same rule covers snapshot tests of anything the code under test formats. A snapshot records what
+the code does, and stays silent on what it should do.
+
+## Keep the top level to imports
+
+In an ideal vitest or jest file, the only things outside the top-level `describe()` are the imports.
+State, construction and helpers all live inside it. The file reads as a description of behaviour and
+not as a program that happens to contain some tests.
+
+```typescript
+import { describe, expect, it } from "vitest";
+import { faker } from "@faker-js/faker";
+
+import { placeOrder } from "./place-order";
+import { offerFactory } from "./order.test-support";
+
+describe("placing an order", () => {
+  // Everything else — state, helpers, tests — lives in here.
+});
+```
+
+This is mostly a consequence of the other rules and adds little on its own. What usually accumulates
+at the top level of a test file is module-level state the tests share, a mutable handle that exists
+so `afterEach` can reach it, and hoisted mock registrations. The rules above have already turned
+down all three. So a top level that will not stay empty is a useful signal that something further up
+has slipped. Imported factories are fine here. They arrive as imports precisely because they stand
+on their own.
+
+## Put test support beside the code
+
+A test file should hold tests. Where support lives depends on what it is for.
+
+A factory for a **type** belongs beside the type it constructs, exported. That no consumer ever
+hand-rolls the literal:
+
+```
+src/orders/
+├── order.ts
+├── order.test.ts
+└── order.test-support.ts     # factories and helpers for order.ts
+```
+
+A library that defines a shape other code has to construct should export the factory for it.
+
+A step written for **one test** stays in that test's file, inside the `describe`. Promoting it later
+when another test wants it is fine. Make it independent first, so what spreads is a self-contained
+factory (not a dependency on how some other test left things).
+
+If a test file is mostly setup, that is a signal. The fix is usually cheaper construction. A shared
+fixture treats the symptom. Scroll the file and see how much of it is `it(...)` bodies making
+assertions.
+
+## Tools that help
+
+These serve the style. The style holds without them.
+
+- [Faker](https://fakerjs.dev/) for randomised, realistic values.
+- [`@kensio/part-factory`](https://partfactory.dev/) for typed factories that need only
+  instantiation. See the `part-factory-test-data` skill.
+- [`@kensio/yulin`](https://yulinsim.dev/) simulates AWS in process, when AWS is the collaborator.
+  See the `yulin-aws-simulation` skill.

package/skills/pangram-check/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: pangram-check
+description: Send the prose of a finished document to Pangram, a commercial AI-text detector, and report which passages read as machine-drafted, with the source line each one starts on. Use when the user asks to "check this with Pangram", "run the AI detector over this", "see if this still reads as AI", or wants a final sweep after rewriting a draft. Every run is paid and sends the writing to a third party, so this skill is invoked by name.
+license: Apache-2.0
+compatibility: Needs a Pangram API key and network access. Every run is billed.
+metadata:
+  version: "1.13.1"
+disable-model-invocation: true
+---
+
+# Pangram check
+
+A final sweep over a finished document. Pangram scores the text in windows of a few hundred words
+and reports which parts read as machine-drafted, so a long document gets a passage-by-passage
+answer.
+
+```bash
+node scripts/pangram-check.mjs path/to/file.md
+```
+
+Full flag list and config file in [references/configuration.md](references/configuration.md). Field
+meanings and how to read a verdict in
+[references/reading-results.md](references/reading-results.md).
+
+## Confirm before spending a call
+
+Every run costs the user money and sends their writing to a third party. Before the first call of a
+session:
+
+1. Name the file that is about to go out.
+2. Give the word count and the billable estimate. `--dry-run` prints both and sends nothing.
+3. Wait for a yes.
+
+This skill sets `disable-model-invocation: true`. It runs when a user asks for it by name, and never
+as a step some other task decided to take. A skill that drafts or rewrites text may mention it and
+stop there.
+
+## Check the key first
+
+On a machine that has not run this before:
+
+```bash
+node scripts/pangram-check.mjs --check-key
+```
+
+That checks the key against `GET /models` and spends no detection call. With no key found, the
+script prints where it looked and how to store one. Pass that message on as it stands. Never print,
+echo or paste the key itself, and never put it in a shell command the user will see.
+
+The key is read from `$PANGRAM_API_KEY`, then `$PANGRAM_ENV_FILE`, then `~/.config/pangram/.env`,
+then `./.env`. Recommend the third one, which every repository on the machine can reach.
+
+## Only the prose is sent
+
+The document is reduced to its prose before the call, and that reduced text is what Pangram
+receives. Frontmatter, code blocks, HTML comments, images, shortcodes, raw HTML, tables, headings
+and URLs are all removed. Link text and inline code keep their words.
+
+Check what would go out with `--print-prose`. The word count the script reports is that same string,
+so a document reporting `512 words of prose` sent exactly those 512 words whatever the file length.
+
+This matters for reading the verdict. A page that is mostly code would otherwise have its bash and
+JSON scored alongside the writing, which pulls the fractions towards human for reasons unrelated to
+how the prose reads.
+
+Wrap quoted material in `<!-- pangram-check:off -->` and `<!-- pangram-check:on -->` to keep someone
+else's writing out of the score.
+
+## The guards
+
+Two of them refuse to send anything.
+
+- **Under 50 words of prose:** Pangram's own documented floor, below which it declines to predict.
+- **Under `--min-words`** (300 by default). Pangram predicts from 50 words up with less confidence
+  the shorter the text. Lower the floor for a short document, and treat the verdict as weaker.
+
+A repository can add its own with `rejectPatterns` in `.pangram-check.json`, or `--reject <regex>`
+for one run. `--reject-todo` is the preset for the common case, where a `TODO` marker means a
+paragraph is still to be written and scoring it would spend a paid call on a draft.
+
+`--max-units <n>` refuses a document over a cost ceiling. One billable unit is each started block of
+1000 words.
+
+## Repeat runs are free
+
+Results are cached by a hash of the extracted prose, so running the same unchanged document again
+reads the cache and calls nothing. Edit the prose and the next run is a fresh call. `--refresh`
+forces one, `--no-cache` skips the cache in both directions.
+
+There is deliberately no score history and no before-and-after delta. Both would invite treating the
+number as a target.
+
+## Output
+
+`--format text` (the default) colour-codes scores on a terminal and draws the windows in reading
+order. `--format markdown` gives a table to paste into a report. `--format json` carries every field
+plus the source line for each window.
+
+## Reporting back
+
+Give the user the headline, the three fractions, and the worst two or three windows with their
+scores and line references. Point at the passages by line so they can open them.
+
+Leave the judgement about rewriting to the user. A high score marks a passage worth rereading, and
+it is not a number to drive down. Editing to move a detector score is a different activity from
+writing in your own voice, and the two come apart quickly.
+
+## Limits
+
+Pangram reports whether text reads as machine-generated. It has no opinion on whether the writing is
+any good, and a document can come back fully human while being badly organised.
+
+A `is_humanized` flag on a window is a stronger signal than a high score by itself, because it means
+the passage looks like text that has been worked over to read as human.
+
+Detectors carry false positives, which fall hardest on writers working in a second language. Treat
+one verdict as one input to a rereading, never as proof of authorship, and say so if a user starts
+treating it as proof.
+
+## Related skills
+
+`technical-prose-style` covers a different question. It measures the constructions that make prose
+tiring to read, and its own measurements show that text following every one of its rules is still
+identified as machine-written. Style and provenance are separate signals. Anyone after concealment
+is holding the wrong tool.

package/skills/pangram-check/references/configuration.md

@@ -0,0 +1,120 @@
+# Configuration
+
+Every setting has a flag. The ones a repository wants every time belong in a config file.
+
+## Flags
+
+| Flag               | Effect                                                           |
+| ------------------ | ---------------------------------------------------------------- |
+| `--dry-run`        | Runs the guards, prints the cost estimate, sends nothing         |
+| `--print-prose`    | Prints the extracted prose and exits                             |
+| `--format <f>`     | `text` (default), `markdown` or `json`                           |
+| `--windows <n>`    | How many windows to detail, or `all` (default 5)                 |
+| `--min-words <n>`  | Refuses below this many words of prose (default 300)             |
+| `--max-units <n>`  | Refuses over this many billable units                            |
+| `--reject-todo`    | Refuses while the file holds `TODO` markers                      |
+| `--reject <regex>` | Refuses when the pattern matches the file. Repeatable            |
+| `--skip-quotes`    | Leaves blockquoted material out of the prose                     |
+| `--plain`          | Treats the file as plain text, skipping the markdown rules       |
+| `--model <name>`   | Pangram model selector, passed through as `model`                |
+| `--list-models`    | Lists the selectors the key allows, then exits                   |
+| `--check-key`      | Checks the key is accepted, then exits. Spends no detection call |
+| `--refresh`        | Ignores any cached result for this text                          |
+| `--no-cache`       | Neither reads nor writes the cache                               |
+| `--config <path>`  | Uses this config file                                            |
+| `--no-config`      | Ignores any `.pangram-check.json`                                |
+| `--no-color`       | Plain output on a terminal                                       |
+
+Exit codes: `0` ran, `1` a guard refused or Pangram failed, `2` a usage, config or key problem.
+
+## The config file
+
+`.pangram-check.json`, found by walking up from the file being checked. The first one found wins,
+and flags override it. An unknown key prints a warning and is ignored.
+
+```json
+{
+  "minWords": 300,
+  "maxUnits": 2,
+  "rejectTodo": true,
+  "rejectPatterns": ["<!--\\s*FIXME", "^\\s*XXX\\b"],
+  "skipQuotes": false,
+  "format": "markdown",
+  "windows": 3,
+  "model": "default",
+  "cache": true
+}
+```
+
+Patterns are JavaScript regular expressions, matched against the raw file with the `g` and `m`
+flags, so `^` and `$` anchor to a line. Backslashes need escaping for JSON. Every match is reported
+with its line number.
+
+`rejectTodo` is the preset behind `--reject-todo`, and matches a `TODO` opening an HTML comment or a
+line.
+
+## The API key
+
+Read from the first of these that carries `PANGRAM_API_KEY`, and never printed:
+
+1. `$PANGRAM_API_KEY` in the environment
+2. `$PANGRAM_ENV_FILE`, a path to a dotenv file
+3. `~/.config/pangram/.env` (or `$XDG_CONFIG_HOME/pangram/.env`)
+4. `./.env` in the working directory
+
+The third is the one to recommend. It sits outside any repository and every project on the machine
+can reach it.
+
+```bash
+mkdir -p ~/.config/pangram
+printf 'PANGRAM_API_KEY=%s\n' 'the-key' > ~/.config/pangram/.env
+chmod 600 ~/.config/pangram/.env
+```
+
+A placeholder value (anything starting `replace`, `your` or `<`) counts as absent. The key is
+redacted from any error text the script prints.
+
+`$PANGRAM_API_BASE` overrides the API host. The test stub in this repository uses it.
+
+## What counts as prose
+
+These are removed entirely:
+
+- YAML and TOML frontmatter
+- Fenced and indented code blocks
+- HTML comments
+- Images, tables, headings and horizontal rules
+- Link reference definitions
+- Hugo shortcodes and Liquid tags
+- HTML and JSX tags
+- Bare URLs
+
+These keep their words and lose their markup:
+
+- Link text
+- Inline code
+- Bold and emphasis
+- Footnote text
+- List item text
+- Blockquotes (unless `--skip-quotes`)
+
+Each paragraph and each list item becomes one block. Blocks are joined with a space, and a block
+with no terminal punctuation gains a full stop. Without it the detector reads a run of list items as
+one sentence.
+
+Regions between `<!-- pangram-check:off -->` and `<!-- pangram-check:on -->` are dropped. Use them
+for quoted material.
+
+`.md`, `.markdown`, `.mdx` and `.mdoc` get the markdown rules. Everything else is treated as plain
+text, and `--plain` forces that.
+
+Every block records the source line it started on. That is where the `file:line` reference on each
+reported window comes from.
+
+## The cache
+
+`$XDG_CACHE_HOME/pangram-check/` or `~/.cache/pangram-check/`, one JSON file per result, keyed by a
+SHA-256 of the model selector and the extracted prose. The file holds the full API response,
+including the submitted text.
+
+Delete the directory to clear it. `--no-cache` writes nothing there.

package/skills/pangram-check/references/reading-results.md

@@ -0,0 +1,69 @@
+# Reading a result
+
+Pangram scores the whole submission and then scores it again in windows, so the useful part of a
+result is the window list.
+
+## The document level
+
+| Field                      | What it carries                                           |
+| -------------------------- | --------------------------------------------------------- |
+| `headline`                 | A short verdict, such as `AI Detected` or `Human Written` |
+| `prediction`               | A sentence of detail behind the headline                  |
+| `prediction_short`         | The same in a word or two                                 |
+| `fraction_ai`              | Share of the text scored as machine-written, 0 to 1       |
+| `fraction_ai_assisted`     | Share scored as written with machine help                 |
+| `fraction_human`           | Share scored as human-written                             |
+| `num_ai_segments`          | Count of segments in each class, alongside the two below  |
+| `num_ai_assisted_segments` |                                                           |
+| `num_human_segments`       |                                                           |
+| `version`                  | The detector version behind the verdict                   |
+
+The three fractions and the three segment counts answer different questions. A document can be 20%
+AI by volume while only one segment out of nine is the source of it, which points at a passage. The
+same 20% spread evenly across every segment points at the whole document.
+
+## The window level
+
+| Field                        | What it carries                                   |
+| ---------------------------- | ------------------------------------------------- |
+| `ai_assistance_score`        | 0 for human, 1 for machine. The number to sort by |
+| `label`                      | `Human`, `AI` or `AI Assisted`                    |
+| `confidence`                 | How sure the detector is of that label            |
+| `text`                       | The passage that was scored                       |
+| `start_index`, `end_index`   | Character offsets into the submitted prose        |
+| `word_count`, `token_length` | The size of the window                            |
+| `is_humanized`               | The passage looks worked over to read as human    |
+| `humanizer_score`            | How strongly, 0 to 1                              |
+
+The script turns `start_index` into a `file:line` reference by mapping it back through the
+extraction, so a flagged window points at the paragraph in the source file. Line references are
+accurate to the block, and the column is not tracked.
+
+## Which signals to act on
+
+**Sort by `ai_assistance_score` and read the top two or three passages.** Everything else in the
+result is context for those.
+
+**`is_humanized` outranks a high score.** A high score says a passage reads as machine-written. The
+humanized flag says it reads as machine-written text that has since been edited to look human, which
+is a claim about the editing as well as the drafting.
+
+**`confidence` qualifies the label, and it qualifies a low score too.** A `Human` label at low
+confidence is a weaker result than a `Human` label at high confidence.
+
+**Short windows are noisier.** A window of 60 words carries less signal than one of 300. Check
+`word_count` before acting on an outlier.
+
+## The limits of a verdict
+
+Pangram reports whether text reads as machine-generated. Whether the writing is any good is a
+separate question, and a document can come back fully human while being badly organised, wrong, or
+dull.
+
+Detectors carry false positives. Published audits have found high false-positive rates on writing by
+non-native English speakers, which is the failure mode to hold in mind before treating a score as
+evidence about a person. One verdict is one input to a rereading.
+
+Scores also move for reasons that have nothing to do with quality. Quoted material, standard
+technical phrasing and heavily edited passages all shift the number. Read the passage the score
+points at, and judge the passage.