@assuredloop/orca-bot-kit 0.1.0 → 0.2.0

package/skills/obk-tdd/SKILL.md

@@ -0,0 +1,516 @@
+---
+name: obk-tdd
+description: >-
+  Test-driven work: a failing test before the code, one vertical slice at a
+  time, through the public interface; a separate author for the tests, whose
+  tests the implementer does not edit; the shapes of tests that catch nothing;
+  and the hand mutation check that asks whether the tests would catch a real
+  mistake. Use whenever you are about to change what code does (a feature, a
+  fix, a one-line change, a bug someone reported) and whenever you are
+  writing, changing or judging tests, deciding what to test, or asking whether
+  a suite would catch anything. Reach for it before writing the code, not
+  after: a small change is exactly where the order gets skipped.
+---
+
+# Test-driven work
+
+The order is the point: the check exists, and has been seen to fail, before the
+code that satisfies it. What that buys is a test written against the
+requirement rather than against the implementation you already had in mind.
+
+Three things hold the tests honest, in this order of value: the author is
+someone other than the implementer, a reviewer reads the tests, and the
+implementer breaks its own logic on purpose to see whether a test notices.
+
+These are defaults for work where nothing says otherwise. A user who asks for
+something else gets what they asked for; say which of these you left and why.
+
+## Find out how this project tests
+
+The loop is the same everywhere; the commands are not. Before the first test,
+learn how *this* project tests: the build file and whether it has a checked-in
+wrapper to use instead of a globally installed tool, the framework and its
+configuration, how it runs one focused test as against the whole suite, where
+tests live and how they are named, what the tests next door already do, and
+which commands the project's own checks actually run. Never assume a default
+command because it is the usual one for the language.
+
+Use the focused command through the loop and the whole-suite command before you
+finish.
+
+## Start from the requirement, not the code
+
+Write the acceptance criteria before any test: one line each, each one
+checkable on its own, each phrased as behaviour someone could observe. A
+criterion you cannot check is a criterion nobody can hold you to.
+
+A requirement's silence is not permission. What a reasonable reader would
+expect is part of it: the invalid input, the denied permission, the empty
+collection. List the input classes the requirement implies but no test
+exercises, and give the few most likely to bite someone using it a test each.
+
+You cannot test everything, and the point of choosing is that the effort lands
+on the paths people depend on and the logic that is easy to get wrong, not on
+every edge case there is.
+
+Expected values come from the requirement, a worked example or a known-good
+literal, never from the code under test or its helpers. An expectation the
+code computes passes whatever the code does.
+
+Say which requirement a test covers, in its name or in a line beside it. A test
+that names a requirement but does not assert its behaviour does not cover it.
+
+Test your own contract, not the library's. What the framework does is its
+maintainers' test to write; yours is the route you register, the query you
+emit, the payload you produce. A constructor, an accessor, a constant or a
+plain hand-off earns a test only where it validates, normalises, defaults,
+derives, enforces or causes an effect; otherwise assert the first result a
+caller can see that depends on it. When upstream behaviour genuinely surprised
+you, one narrow test that names the assumption is worth keeping.
+
+Behaviour, not text. Asserting that a script, a configuration or a document
+contains a particular line proves only that the source is the source. Run the
+thing against a controlled input and assert what comes out: the output, the
+effect, the exit status. Prose written for people earns no test at all.
+
+## One vertical slice at a time
+
+One test, then the smallest implementation that passes it, then the next. Not
+all the tests first and then all the code: tests written in bulk describe
+behaviour you imagined, and they all go green in one step that nobody watched.
+
+A separate author writing the acceptance tests up front is not that, although
+it looks like it: those are a few tests at the top seam, taken from the
+requirement rather than from a plan. You still work through them one at a time,
+watching each one fail and then pass. When a slice turns out to need a narrower
+test (a boundary the top seam does not reach), that one goes to the author
+too; the brief is smaller, not different.
+
+Test at a seam: the public boundary where you can observe behaviour without
+reaching inside. Prefer a seam that already exists, and the highest one that
+still shows the behaviour; the fewer seams a codebase has, the better. State
+the seam you are testing at. Ask about it only when the interface itself is
+what is in question.
+
+Do not anticipate the next test. Code that no failing test asked for is
+untested code, whatever it does.
+
+Before you settle a test, run the behaviour past the kinds of mistake that get
+made (a boundary off by one, a condition the wrong way round, an equality that
+should be an inequality, an arithmetic identity, an empty collection, a side
+effect that never happens) and add the case you find missing there and then.
+The inputs that tell those apart: just below, at and just above a boundary; one
+condition true and the other false; and values that are not identities, since
+0, 1 and empty hide a swapped operator.
+It is the same question the mutation check asks at the end, asked while it is
+still cheap to answer.
+
+Use the least substitute that does the job, because the more of the real thing
+a test runs, the more it tells you. In order: the real implementation; a
+working in-memory version of it; something that returns fixed answers; and last
+a stand-in you assert the calls of. Reach past the real thing only when it is
+slow, unpredictable, or has effects you cannot control: an external service,
+the clock, randomness, a database sometimes, the filesystem sometimes. Do not
+stand in for your own modules or internal collaborators.
+
+What settles this for a system outside your code is not who owns it but
+whether you can have one to yourself. A database you start for the test, a
+repository you create in a temporary directory, a server you run and throw
+away: those are the real thing, isolated, and they are what the order above
+asks for; a stand-in there would hide exactly the incompatibility you want to
+find. What rules the real one out is sharing it: other people's work in it,
+state you cannot reset, or simply not having permission to touch it. Then an
+author works against a stand-in, and the project's rules usually name which
+systems those are.
+
+When a test is hard to write, that is information about the design, not about
+testing. Hard to set up usually means hard to use. Having to stand in for
+everything means the pieces are too tightly bound. Pass what a function
+depends on in rather than letting it reach out and build its own. A single
+function per external operation is easier to substitute than one general one
+with a switch inside it, because each substitute then answers one question
+instead of branching.
+
+Four things about a stand-in, when you do need one. Learn what the real thing
+does before you replace it, and stand in at the slow or external level below
+what the test depends on, so you do not swallow an effect the test was there to
+see. Mirror the real shape completely, not only the fields this test reads: a
+partial one passes while the real thing breaks on a field it left out. Assert
+the real behaviour, never the stand-in itself. An assertion that the stand-in
+is present passes because it is present and says nothing about your code. And
+when the setup grows past the test it serves, or you cannot say why it is
+there, drop it and test against the real components.
+
+Cleanup that only tests need belongs in the test helpers, not as a method on
+the thing being tested.
+
+## The test author is someone else
+
+An agent that writes the code and the tests shares one set of blind spots. It
+writes tests it already knows will pass, and when one goes red the cheapest
+road is to soften it. What separation buys is a context that holds the
+requirement and not the implementation. The isolated context is the point, not
+a role or a persona.
+
+Who counts: a fresh subagent, another session, another bot, or a person. In
+Claude Code it must be a subagent with its own context, not a fork that
+inherits the conversation. Codex spawns a subagent only when asked in so many
+words, so ask in so many words.
+
+What the author gets: the requirement, the acceptance criteria, and the public
+interface (names, signatures, types, the shape of inputs and outputs). Not your
+plan, not your diff, not the implementation. What the author returns: the test
+files, the command, the failing output, and one line per test naming the
+requirement it covers.
+
+A brief that works, adjusted to the job:
+
+> Write tests for this requirement. You are not writing the implementation and
+> you will not see it.
+> Requirement: <what the behaviour is, and the acceptance criteria>.
+> Out of scope: <what this change does not cover, if anything>.
+> Public interface: <signatures and data shapes, no bodies>.
+> Test at <seam>, in <the repo's test style and framework>; follow the
+> repo's existing tests for shape. Write them the way obk-tdd's parts on
+> writing tests say, if you can load it.
+> Test observable behaviour through that interface. Take expected values from
+> the requirement or a worked example, never by calling the code under test.
+> Cover the unhappy inputs the requirement implies as well as the happy one.
+> Run them. They are all expected to fail, and to fail because the behaviour is
+> missing rather than because of a typo or an import error.
+> Return: the files you wrote, the command, its failing output, and one line
+> per test naming the requirement it covers.
+
+Say what state the code is in, and be exact about it. The author cannot see it
+and will believe what the brief says. When you send an author at code you have
+deliberately broken (killing a surviving mutant, see below), say so in the
+brief: *the code has a deliberate break in it and the test is expected to
+fail*. Left out, the author reads your own break as a defect and spends a round
+reporting a bug that does not exist.
+
+Then, as the implementer: every test that ships is the author's, the narrow
+ones as much as the first ones. A scratch check you run to see what the code is
+doing is yours and is thrown away; it is not part of the suite, and it is not
+the red you report. You do not edit, weaken, skip or delete the author's tests
+to get to green. A test you believe
+is wrong goes back to its author with what you think is wrong with it. That is
+a real and expected outcome, not a defeat. The tests verify the requirement;
+they do not define the solution, so do not write code that works only for the
+inputs a test happens to use.
+
+The author's tests are part of the change, not a stage before it. Commit them
+as soon as they are red, before the implementation: that way a later diff over
+the test paths shows any change to them, and (the part that actually bites)
+they cannot be left behind. Where the repo allows it, keeping those paths out
+of the implementer's write scope makes tampering visible rather than merely
+forbidden.
+
+An author you have dispatched and not heard back from is outstanding work. The
+piece is not done while it is still writing, and nothing goes out on the
+strength of tests that have not arrived. When the hand-back comes, read it
+against what is actually there: every file it names, present in the working
+tree, and present in the change you are about to hand on. A finished test file
+still sitting in a working tree is the ordinary way this goes wrong, and it
+looks exactly like success until someone else clones the branch.
+
+When you can neither start an author nor reach one, that is where the work
+stops: say so and ask what to do. The separation is the check, and an
+implementer writing its own tests is not a weaker version of it, it is the
+absence of it.
+
+## Red is evidence, not a formality
+
+Run the test and read the output before you write any code:
+
+- It fails, rather than errors.
+- The failure message is the one you expected.
+- It fails because the behaviour is missing, not a typo, a bad import, a
+  missing fixture.
+
+If it passes, you are testing behaviour that already exists; that is a finding
+about the test, not a step you may skip past. If it errors, fix the error and
+run again until it fails cleanly.
+
+Behaviour that already exists is the case this is easiest to fudge, because
+there is no fix to revert and nothing obvious to run the test against. The red
+has to come from somewhere real: an archive of the code as it stood before this
+work (a commit, a tag, a copy) with the test run against that. Name which one
+in the hand-over, because "it would have failed before" is not a run.
+
+Sometimes there is no such baseline to be had: the code never existed in that
+shape, or what you would have to reconstruct is not worth the day. Then say so
+in the hand-over, and in a line beside the test marking it as a description of
+what the code does today rather than a guard proven to catch a change. The two
+look identical afterwards, and only one of them has been shown to fail.
+
+Reaching a clean red is one step at a time, and none of them is implementation:
+the test cannot find the symbol, so add an empty stub; the call does not match
+the signature, so fix the signature and leave the body empty; now it fails on
+the assertion, and only now does logic get written.
+
+Keep the failing output as it was printed. Commit order proves nothing about
+what ran first. Without a captured failing run, say the chronology is unproven
+rather than implying it.
+
+Things that look like green and are not: a test that passed on its first run; a
+suite reported as passing that nobody ran; a default test command guessed
+instead of the one this repo actually uses. And your test passing is not the
+suite passing. Any failure the run showed, including one you did not cause,
+goes in your report by name. Green means the output is clean too: warnings and
+errors that scroll past on a passing run are results, not decoration.
+
+Where the change reaches further than the test you wrote, run what is next to
+it as well (the neighbouring tests, the type check, whatever the project uses
+to say a thing still holds) and say in your report what you ran.
+
+An assertion that already existed is not yours to loosen. It weakens only when
+the behaviour it describes genuinely changed, and then the reason is stated out
+loud, not left to be inferred from the diff.
+
+## Green, then refactor outside the loop
+
+Write the smallest code that passes the failing test, and stop there.
+
+Faking it is allowed and often right. If returning the answer the test asks for
+passes, return it; then write the second case that the fake cannot satisfy, and
+let that one force the real implementation. Generalise when a test makes you,
+not before.
+
+Refactoring is not a phase of the red/green loop. A small refactor is part of
+the change and keeps the same contract, so the tests that were green stay
+green; do it as its own step after green rather than while you are trying to
+get there, and keep the tests green on both sides of it. Pulling out something
+whose behaviour already exists elsewhere is refactoring; a function whose
+behaviour appears nowhere else is new, and it starts with a failing test like
+anything else.
+
+Do not manufacture a red. A failing test written so a step looks like it
+started with one, a break invented so a restructuring can be called a change of
+behaviour, commits reshaped afterwards to tell a tidier story: all of that
+costs the time of doing it and buys nothing, because none of it was ever a
+check on anything. A step that did not need a red is reported as what it was.
+
+When a change is large enough that the old tests cannot hold, that is still not
+a licence to edit them. The author writes them again from the new requirement,
+usually deleting the old ones first. A large refactor is planned as a piece of
+work in its own right, not carried inside another change.
+
+Tests against an inner module become waste once the same behaviour is covered
+at the interface above it. Deleting them is the author's call, and deliberate.
+
+## Bugs
+
+A bug fix starts with a test that reproduces it, written before the fix, at a
+seam where the test exercises the bug as it actually happens at the call site.
+A seam below that gives a green test and no protection. If no correct seam
+exists, that is itself the finding: report it, because the shape of the code is
+what is stopping the bug from being pinned down.
+
+Minimise the reproduction until every part of it is load-bearing, turn it into
+a failing test, watch it fail, fix the cause, watch it pass, then run the
+original unminimised scenario again.
+
+Two tests are often better than one here: one at the interface, saying what a
+caller should have got, and the smallest one that shows the fault where it
+lives. Get both to pass. The first is what stops the bug coming back in a way
+anyone would notice; the second says where it was.
+
+A regression test written after the fix has proved nothing yet. Prove it:
+revert the fix, run it and watch it fail, restore the fix, run it again.
+
+When the bug is intermittent, make the test deterministic if you can, and say
+which signal you pinned down. When it is one of a class, land the test for the
+one in front of you first, then say what else has the same shape.
+
+When a failing test really is impractical, say so out loud, say why, and name
+the closest executable check you used instead. Quiet omission is the part that
+does damage: a reviewer treats a missing red receipt as a finding.
+
+## Tests that catch nothing
+
+Before writing the body, answer one question: what change to the production
+code should make this test fail, and is that change a bug or a decision? A test
+earns its place by catching a wrong branch, a missing side effect, a wrong
+argument, a boundary or a broken contract. A test that only fails on a
+deliberate decision fires on every redesign and sleeps through every bug.
+
+The cheap check on a test you already have: would it still pass if every
+function it calls returned nothing? If yes, it observes no behaviour.
+
+Five shapes that still pass that way, and what to do with each:
+
+- **No real assertion.** Nothing asserted, or only "is defined", "is truthy",
+  "did not throw". Call the subject with one concrete input and assert the
+  literal output or the observable effect.
+- **An absence with nothing to contrast it against.** Only "was not called",
+  "is undefined", "is empty", and no case in the same test where something
+  *is* produced. Assert the presence on the other input beside it, so the pair
+  can tell an empty result from a subject that never ran. For a stand-in,
+  assert the payload it received or the state after the call, not only that it
+  was called.
+- **Self-referential.** The expected value is produced by the code under test.
+  Replace it with a literal you worked out by hand.
+- **Constant pinned.** The assertion restates a constant, a config default or
+  the exact wording of a message. Test the mechanism that reads the constant
+  with one input instead.
+- **Fixture asserts fixture.** The assertion reads data the test itself built,
+  and the subject never runs. Run the subject inside the test body.
+
+An empty or absent result is not by itself a weak assertion. "This user sees
+none of the private records" and "this call is never made" are contracts, and
+a test that pins one catches a real defect. So are the arguments a call
+carries, how many times it happens and in what order, where those are the
+contract rather than an accident of how the code is written today. What makes
+the shape weak is an absence with no positive case beside it, or a stub
+asserted instead of the behaviour. Judge by the question that governs the
+whole list: would this catch a defect someone could ship?
+
+When no honest assertion exists, delete the test. Prefer no new test to a bad
+one: one that mostly tests stubs, that encodes today's implementation, that
+depends on timing or global state, or that you would delete the moment the fix
+is proven.
+
+Two that the five shapes do not condemn: a test that checks a relation holds
+across rows of data (a key present in two tables, a parent that exists), and a
+check the language itself makes at build time.
+
+Other tells: the test breaks when you refactor although the behaviour did not
+change; it reaches around the interface to check the result (reading the
+database directly instead of asking for the record back), which couples it to
+the inside just as surely as a stub does; the stub setup is more than half of
+it; the expected values are hidden behind loops or builders; the only way it
+can fail is a crash; it exists to raise a coverage number. Coverage is a
+diagnostic and not a target: a high number says the lines ran, not that
+anything would have noticed them being wrong.
+
+One behaviour per test, so that a failure names one thing. That is not a limit
+on how many assertions you write: a table of cases for one behaviour is still
+one test, and the several assertions that together pin one outcome are one
+claim. It is a limit on how many unrelated claims share a name.
+
+Repetition between tests is not a fault. A test that reads on its own, with its
+input and its expected value in front of you, is worth more than one that sends
+you through three helpers to find out what it claims. Share setup when it makes
+the test clearer, not to avoid typing.
+
+What is missing is usually on the unhappy side: the denied case of a permission
+check, untested guard clauses and early returns, error branches, boundaries
+(zero, empty, negative, one element, the maximum), and the second half of any
+"if". And tests that pass together but not alone are already broken: shared
+mutable state, order dependence, the clock, the timezone, the real network, a
+sleep, an assertion on the order of something unordered.
+
+## The mutation check before you call it done
+
+The question is the whole point: if a real mistake were made in this code,
+would a test fail? There is no score to reach.
+
+**Everyday: your own hand check.** Once per piece of work, at the end, only
+where it earns its place. Five to eight deliberate breaks in the risky logic
+the work changed (money, permissions, eligibility, safety, data that could be
+lost, and whatever else the requirement cares most about), chosen before you
+look at the tests, each one run, each one expected to make a test fail, each
+one put back. Reported in three lines.
+
+One break at a time, never two at once: note the original, apply the break, run
+the tests, record killed or survived, restore the code immediately, then the
+next one.
+
+What to break, in this order: boundaries (`<` for `<=`, one off), boolean logic
+(`&&` for `||`, a dropped `not`), returned values (an empty or default return,
+a removed early return), a removed statement or side effect, a wrong constant
+or argument. Avoid a change that cannot show: adding zero, multiplying by one, or a value
+identical to the original.
+
+Others worth reaching for when the code has them: an arithmetic operator
+swapped; equality turned into its opposite; a string emptied or altered; a
+collection emptied, or a filter or a sort taken out; a safe-navigation step
+removed so an absent value reaches further than it should; a call to a
+collaborator deleted.
+
+Skip it, and say that you skipped it, for work with no real logic in it: docs,
+config, wiring, renames, small fixes, prototypes, and code with no runnable
+tests.
+
+**A survivor**, a break no test objected to, gets the equivalence question
+first: is there any input for which the changed code returns a different value,
+stores different state, or emits a different message? If there is none it is
+equivalent, and no test can catch it; write the one-line argument for why.
+"No test covers this" is not the same as "no input can reach this". Every
+survivor ends as exactly one of three things: killed by a new test, equivalent
+with that argument, or a judgment call you name and leave. A list of survivors
+with nothing said about them is not a report, and neither is treating each one
+as a defect.
+
+When you cannot tell whether a survivor matters (the behaviour is genuinely
+unspecified, the test would be expensive or brittle, or you are not sure it is
+equivalent), name it as that in the report, with the question whoever decides
+the behaviour would have to answer, rather than deciding quietly in either
+direction.
+And if a lot of the breaks turn out to be equivalent, that is a finding about
+the code, not about the tests: code with that much slack in it can usually be
+made simpler.
+
+Kill a survivor only where it shows a gap in behaviour the requirement cares
+about. Wording of messages, logging and changes with no visible difference are
+not worth a test; say so in a line and move on. To kill one: keep the break in
+place, write the smallest behaviour test that fails against it for the right
+reason, restore the code, check the new test still passes.
+
+The implementer runs the check. A test that needs strengthening goes to the
+separate author, like any other test.
+
+**A mutation tool is an audit, not everyday work.** It is never a requirement,
+and it is not worth a user's time on a suite it does not fit. Where a project
+has one, run it over the whole suite occasionally (at a milestone, or when the
+user asks) in the background at a quiet time, in its own tab or session. Read
+the result once; turn the few real gaps into test work; ignore the rest. Not
+once per change, and never twice for the same change. For a piece of work at
+the core of a product, one run narrowed to the logic that changed, in the
+background, around twenty minutes; if it will not fit in that, do the hand
+check instead. Then stop. A run heading towards hours is stopped.
+
+When you have decided to run a tool, read [mutation-tools.md](mutation-tools.md)
+beside this file: the scoped run for each language, what older advice gets
+wrong, how to run one and read what it prints, and how far each line there has
+been verified. There is nothing in it you need before that point.
+
+Keep it in proportion. This check is the third safety net, after the separate
+author and the reviewer's reading of the tests, and it stays the cheapest of
+the three.
+
+## Green that was bought
+
+Tightening the bar should be silent; loosening it should be loud. In your own
+diff and in anyone else's, these are the cheap roads to green, and each one is
+worth a sentence when it happens: a threshold moved, a test marked skipped, a
+test file deleted, assertions removed from a test that stayed, a check disabled
+by a comment, a value hard-coded to match one test's input and still there when
+the work is handed on.
+
+## What you report
+
+- Red: the command, the failing output, why that failure was expected.
+- Green: the command, the passing output, and any other failure the run showed.
+- Who wrote the tests, whether they were changed after they were written, and
+  that every file the author handed back is in the change.
+- For a test of behaviour that already existed: which baseline its red came
+  from, or that there was none and it stands as a description rather than a
+  proven guard.
+- The mutation check in three lines: what you broke, what survived, what you
+  did about it, or the line that says you skipped it and why.
+- What you did not check, and the command that would check it.
+
+## Away from code
+
+The same three moves work on documentation, configuration, prompts and data,
+where no tool will help: state the check before you make the change, see the
+check fail first, and at the end break the artefact on purpose to find out
+whether the check notices.
+
+They apply where there is something that can be wrong: a configuration that
+decides who gets what, a prompt whose branches behave differently, a
+transformation over data. The skip rule is the same as for code, and prose
+written for people earns no test and no mutant.
+
+Sources and licences: [NOTICE.md](NOTICE.md).

package/skills/obk-tdd/mutation-tools.md

@@ -0,0 +1,80 @@
+# Mutation tools, by stack
+
+For the occasional audit described in the skill. No project needs one of these,
+and the hand check is the everyday method; this page exists so that a run, when
+there is a reason for one, is scoped to what changed instead of the whole repo.
+
+How far to trust each line. The StrykerJS flags below (`--incremental`,
+`--force` and `-m`/`--mutate`) were checked against `stryker run --help` on
+version 10.0.0 on 2026-09-20. Everything else on this page, the line-range form
+included, was read from each tool's own documentation on 2026-09-19 and has not
+been run. Flags change: check the version the project actually has before
+trusting a line here, and prefer a command the project already ships over one
+from this page.
+
+**JavaScript, TypeScript: StrykerJS** (Apache-2.0)
+
+```sh
+npx stryker run --incremental
+npx stryker run --mutate src/x.ts          # one file
+npx stryker run --mutate src/x.ts:10-40    # one range
+```
+
+**C#: Stryker.NET** (Apache-2.0): `dotnet stryker --since:main`
+
+**Rust: cargo-mutants** (MIT)
+
+```sh
+git diff origin/main.. > git.diff && cargo mutants --in-diff git.diff
+```
+
+**Go: gremlins** (Apache-2.0): `gremlins unleash --diff origin/main`, with the
+full history fetched.
+
+**Python: mutmut 3** (BSD-3-Clause): `mutmut run "module.function*"`;
+incremental by default; `mutmut browse` to work through the survivors.
+
+**Python: Cosmic Ray** (MIT): `cosmic-ray init`, then `cr-filter-git`, then
+`cosmic-ray exec`, then `cr-report`.
+
+**Java: PIT** (Apache-2.0):
+`mvn -DwithHistory test-compile org.pitest:pitest-maven:mutationCoverage`, with
+`targetClasses` and `targetTests` globs.
+
+**Anything else**, shell, SQL, configuration, prompts, a language with no such
+tool: the hand check in the skill is the method, and it is the same method,
+including the rule about when to skip it. Something with no logic in it does
+not get broken on purpose just because no tool would have run anyway.
+
+## Four things that older advice gets wrong
+
+- PIT's `scmMutationCoverage` goal was deprecated in 1.17.1 and removed in
+  1.18.0. Diff scoping in PIT now comes from a commercial plugin; with the free
+  one, scope with the globs above and `-DwithHistory`.
+- mutmut 3 has no `--paths-to-mutate`. Scope it in the config (`only_mutate`,
+  `do_not_mutate`, `mutate_only_covered_lines = true`) or with a positional
+  glob.
+- `cargo mutants --in-diff` takes a diff file, not a git ref: write the diff
+  out first.
+- StrykerJS has no git-diff flag; feed it the changed files yourself.
+
+## Three caveats that apply to all of them
+
+- A diff-scoped run matches the diff against the code under test, not the test
+  code. A change that only weakens a test produces no mutants at all and comes
+  back clean. When test files change, mutate the code those tests cover.
+- A run that picks its targets from a committed diff sees only committed work,
+  so on a dirty tree it reports on the wrong code: commit first, or name the
+  files yourself instead. Naming them is the better answer when the point is to
+  check work that is not committed yet. Do not make someone stash the code
+  they asked about.
+- Whatever selects the targets, a run that dies in the middle can leave a
+  mutant in the working copy. Look at the tree afterwards.
+
+## Running one and reading it
+
+Prove the setup with one small scoped run before spending a long one. Capture
+the output once and read it from the copy rather than re-running to re-read it.
+Set no failing threshold before a measured baseline exists. Paste what the tool
+printed: a mutation result reported from memory has been wrong. A compile error
+is not a kill, and a timeout is inconclusive rather than evidence.

package/skills/obk-teach/LICENSES.md

@@ -0,0 +1,42 @@
+<!-- The licences of the sources this skill was consolidated from. They travel
+     with the skill directory because the licences require it of anyone who
+     distributes the material. NOTICE.md says what was taken from each source;
+     this file carries the permission notices themselves. -->
+
+# Licences of the sources
+
+`obk-teach` consolidates material from the sources named in
+[NOTICE.md](NOTICE.md). Their licences are reproduced below in full.
+
+## MIT
+
+The MIT permission notice below applies to the work of each of these copyright
+holders, and is reproduced with each of their notices. The path after each one
+is the licence file it was read from, in the research pack's source clones.
+
+- **Cursor `plugins`, the pstack plugin**, Copyright (c) 2026 Lauren Tan
+  (`cursor_plugins/pstack/LICENSE`)
+
+```
+MIT License
+
+Copyright (c) 2026 Lauren Tan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```