@1aboveio/skills 0.0.0-stage → 1.0.0

package/skills/engineering/rush-release/agents/openai.yaml

@@ -0,0 +1,8 @@
+interface:
+  display_name: "Rush Release"
+  short_description: "Slash/explicit-only no-questions release shortcut of resolve-release"
+
+policy:
+  # Codex counterpart to SKILL.md disable-model-invocation: true.
+  # Keeps $rush-release / explicit invoke while blocking description-based selection.
+  allow_implicit_invocation: false

package/skills/engineering/rush-release/release-check.mjs

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+import { spawnSync } from 'node:child_process';
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+const WEEK_MS = 7 * DAY_MS;
+const here = dirname(fileURLToPath(import.meta.url));
+
+function readJson(path, fallback = {}) {
+  try { return JSON.parse(readFileSync(path, 'utf8')); } catch { return fallback; }
+}
+
+function frontmatterValue(text, key) {
+  const frontmatter = /^---\n([\s\S]*?)\n---/.exec(text)?.[1] ?? '';
+  const match = new RegExp('^' + key + ':\\s*([^\\n]+)$', 'm').exec(frontmatter);
+  return match?.[1].trim().replace(/^['"]|['"]$/g, '') ?? null;
+}
+
+function repositoryOf(source) {
+  const value = String(source ?? '').trim();
+  const match = /^(?:git@github\.com:|https:\/\/github\.com\/)?([A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+?)(?:\.git)?$/.exec(value);
+  return match?.[1] ?? null;
+}
+
+function stableVersion(value) {
+  const match = /^v?(\d+)\.(\d+)\.(\d+)$/.exec(String(value ?? '').trim());
+  return match ? match.slice(1).map(Number) : null;
+}
+
+function newer(left, right) {
+  for (let index = 0; index < 3; index += 1) {
+    if (left[index] !== right[index]) return left[index] > right[index];
+  }
+  return false;
+}
+
+function writeCache(path, value) {
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(value));
+  } catch { /* A read-only cache must not block skill use. */ }
+}
+
+function main(now = Date.now()) {
+  if (process.env.ONEABOVEIO_NO_UPDATE_CHECK) return;
+  const skill = readFileSync(join(here, 'SKILL.md'), 'utf8');
+  const name = frontmatterValue(skill, 'name');
+  const localVersion = stableVersion(frontmatterValue(skill, 'release-version'));
+  if (!name || !localVersion) return;
+
+  const lock = readJson(join(process.env.HOME || homedir(), '.agents', '.skill-lock.json'));
+  const entry = lock.skills?.[name];
+  const repository = repositoryOf(entry?.sourceUrl || entry?.source);
+  if (!repository) return;
+
+  const cacheRoot = process.env.XDG_CACHE_HOME || join(process.env.HOME || homedir(), '.cache');
+  const cachePath = join(cacheRoot, '1aboveio-skills', 'release-check.json');
+  const all = readJson(cachePath);
+  const cache = all[repository] && typeof all[repository] === 'object' ? all[repository] : {};
+
+  if (!cache.lastCheck || now - cache.lastCheck >= DAY_MS) {
+    const result = spawnSync('gh', ['api', 'repos/' + repository + '/releases/latest', '--jq', '.tag_name'], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: 1500,
+    });
+    cache.lastCheck = now;
+    if (result.status === 0 && stableVersion(result.stdout)) cache.latestTag = result.stdout.trim();
+    else delete cache.latestTag;
+    all[repository] = cache;
+    writeCache(cachePath, all);
+  }
+
+  const latestVersion = stableVersion(cache.latestTag);
+  if (!latestVersion || !newer(latestVersion, localVersion)) return;
+  if (cache.notifiedTag === cache.latestTag && cache.notifiedAt && now - cache.notifiedAt < WEEK_MS) return;
+
+  cache.notifiedTag = cache.latestTag;
+  cache.notifiedAt = now;
+  all[repository] = cache;
+  writeCache(cachePath, all);
+  const command = `npx skills@1.5.23 add '${repository}#${cache.latestTag}' --global --agent universal claude-code --skill ${name} --yes`;
+  process.stdout.write(
+    `UPDATE_AVAILABLE: A newer 1AboveIO skills release (${cache.latestTag}) is available; this skill is `
+      + `v${localVersion.join('.')}. Ask once whether to refresh ${name}. On approval run \`${command}\`. `
+      + 'The refreshed instructions apply next session. Either way, continue the current task and do not ask again this session.\n',
+  );
+}
+
+try { main(); } catch { /* Update checks are advisory and always fail silent. */ }

package/skills/engineering/test-quality/LICENSE

@@ -0,0 +1,3 @@
+MIT License
+
+Copyright (c) 2026 1AboveIO

package/skills/engineering/test-quality/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: test-quality
+description: "Seven principles for tests that catch real bugs, and an audit that reports weak, redundant, and not-coverage tests without fixing them. Use when writing, changing, or reviewing tests, or when asked whether tests are useful, redundant, over-mocked, flaky, only assert static text, or test config files, or asked to make a slow test suite faster without losing coverage, or when the user asks to write the testing conventions into a repo's CONTRIBUTING.md. NOT defining what a spec must prove (ensure-coverage) or authoring browser tests (e2e-test)."
+release-version: 0.36.0
+---
+**Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
+# Test Quality
+
+A test is worth keeping when it fails for a real bug and stays green through a harmless change. This skill states seven principles that decide that and audits a suite against them. Each principle's examples, common failures, and look-alikes: [references/principles.md](references/principles.md).
+
+- **Write mode**: the principles are the bar while you write or change tests. Check each new assertion against the one question, and before you commit run `node "$SKILL_DIR/scripts/lint-tests.mjs" --diff <base>` from the repo root ([lint](#the-lint)); it covers uncommitted and untracked tests.
+- **Audit mode**: reviewer subagents sweep a suite or a diff and report findings, quick by default ([audit](#audit-mode)). The audit **never edits, rewrites, or deletes a test**. It names the principle broken and the evidence; the fix belongs to the implementer.
+- **Persist mode**: only when the user asks, write the principles into the repo's `CONTRIBUTING.md` ([persist](#persist-mode)).
+
+| # | Principle | The failure it names | Quick tell |
+|---|---|---|---|
+| 1 | [Test behavior, not text](references/principles.md#1-test-behavior-not-text) | Reading a file instead of running the code | `readFileSync`/`read_text` of a checked-in file, then `toContain`/`in`/`match` |
+| 2 | [The expected value comes from somewhere other than the code under test](references/principles.md#2-the-expected-value-comes-from-somewhere-other-than-the-code-under-test) | Copying the answer into the test | `expect(CONST).toBe(<its literal>)`; mock returns X, test asserts X |
+| 3 | [Fake only what you don't own](references/principles.md#3-fake-only-what-you-dont-own) | A fake that can't see the bug | first-party module mocked; assertion on the call, not the outcome |
+| 4 | [An assertion must be able to fail](references/principles.md#4-an-assertion-must-be-able-to-fail) | Checks weaker than the test's name | no assertion, `NoError` only, bare `toThrow()`, a skip that always fires |
+| 5 | [Test each behavior once, and only for code that still runs](references/principles.md#5-test-each-behavior-once-and-only-for-code-that-still-runs) | Duplicates and dead weight | identical files; mocked unit twin of a real integration test |
+| 6 | [Don't test config files](references/principles.md#6-dont-test-config-files) | Restating a config file in a test | a Dockerfile, workflow, `cloudbuild.yaml`, `.mergify.yml`, `package.json`, or other JSON/YAML/TOML config read, then any assertion |
+| 7 | [Same code, same result](references/principles.md#7-same-code-same-result) | A result that depends on luck | `Math.random`/`uuid()`/`Date.now()` in checked output; `sleep(…)`; passes in the suite, fails alone |
+
+## The one question
+
+For every assertion, answer both halves:
+
+1. **What realistic bug makes this fail?**
+2. **What harmless change makes this fail?**
+
+A good assertion has a concrete answer to (1) and none to (2). An assertion with no answer to (1) is not coverage, however many harmless changes it would catch. Judge **assertions, not whole tests**: one strong check buried among five pins is a good test with five findings.
+
+## The principles
+
+1. **Test behavior, not text.** Run the code and observe what it does. The text of a doc, prompt, source file, or migration is not behavior. A test whose only assertions are text matches over checked-in files is **`Not coverage`** for the behavior the text describes, never partial proof.
+2. **The expected value comes from somewhere other than the code under test.** Take it from the spec, an external contract, a separately written simpler model, or the input: never from the code under test or a literal copied out of it. When a version really is the contract, pin the major only.
+3. **Fake only what you don't own.** Fake third-party APIs, providers, the clock, and randomness. Your database and services run for real, because a fake cannot see transactions, tenant filters, locking, or idempotency. An over-mocked test is `Not coverage` for the behavior the fake hides.
+4. **An assertion must be able to fail.** Every test can go red and checks what its name promises: read the name's verbs ("atomically", "then", "corrected to") and find the assertion for each.
+5. **Test each behavior once, and only for code that still runs.** Prove each behavior once, at the lowest level that proves it for real. Layering (a pure unit for the decision table plus one real-DB test per rule) is not duplication; many similar cases merge into a table rather than being deleted.
+6. **Don't test config files.** Dockerfiles, `cloudbuild.yaml`, `.github/workflows/*`, `.mergify.yml`, `package.json`, `tsconfig.json`, `pyproject.toml`, `.env`, and any other JSON, YAML, or TOML a tool reads get no tests: the tool that reads the file is the test. Test the code that reads config; run scripts, because scripts are code. A pin added after a real bug is still a config test: delete it and name the missing behavior check as a follow-up. JSON the app loads as data (locales, price tables) is not config.
+7. **Same code, same result.** Anything that changes between runs (randomness, the clock, timing, run order, the network) is fixed by the test: seed it, freeze it, wait on the condition, own your state.
+
+## Audit mode
+
+Reviewer subagents audit and never fix. The **quick audit** is the default and finishes in under 10 minutes: `lint-tests.mjs --shares 4` splits the flagged files, at most 4 reviewers (or the harness's parallel limit) read only their flagged spots on a 6-minute budget, each writes its report to a file and replies in one line, and the lead merges once and posts once, with no per-reviewer updates. A **deep audit** (every test file read) runs only when the user asks for one. Any request that ends in changed tests ("audit and fix", "clean up the tests", "improve the suite") then runs **fix** (implementer subagents, disjoint files; each opens a `Redundant` test's twin and searches for what depends on a test before deleting it) → **verify** (lint on the diff, fresh reviewer on the fix). A request to make the suite faster without losing coverage measures durations first and collapses slow files by code path ([speed](references/audit.md#when-the-goal-is-speed)). Steps, budgets, and the report template: [references/audit.md](references/audit.md).
+
+### Labels
+
+Per assertion, or per test when every assertion shares it:
+
+- **`Not coverage`**: cannot catch a realistic bug (text-only, tautology, first-party over-mock, config restated, an assertion that can never go red). Counts as zero proof for the behavior it names.
+- **`Weak`**: catches something, but less than its name claims, or breaks on harmless changes.
+- **`Redundant`**: proven equally or better elsewhere (name the other test), or it tests dead code (name the evidence).
+- **`Lead`**: looks like a failure, not confirmed by reading; state what would confirm it.
+
+Every finding carries a real `file:line` you opened. Rank by cost: `Not coverage` on auth, money, or data integrity first.
+
+## Persist mode
+
+**Only when the user explicitly asks** to write the testing conventions into the repo. Never on your own initiative, and never as part of write, audit, or fix work. From the target repo's root, with `SKILL_DIR` set to the directory you read this file from:
+
+```bash
+node "$SKILL_DIR/scripts/persist-conventions.mjs"           # preview: what would change
+node "$SKILL_DIR/scripts/persist-conventions.mjs" --write   # write, once the user asked
+```
+
+It writes the seven principles ([references/testing-conventions.md](references/testing-conventions.md)) as the `## Testing conventions` section of `CONTRIBUTING.md`, between `conventions:testing` markers: a re-run replaces only that section and keeps everything else, including the `## CI conventions` and `## Delivery` sections `github-flow` writes. It adds a pointer to `AGENTS.md` unless that already names `CONTRIBUTING.md`, and creates a missing `CLAUDE.md` as a symlink to `AGENTS.md` (a regular `CLAUDE.md` that names neither file gets the pointer); missing files are created. `CONTRIBUTING.md` is the file `code-review` reads as a standards source, so the principles then apply in review too. Report each file's result line; committing is the user's call.
+
+## The lint
+
+Scripts live under **this skill's directory**: set `SKILL_DIR` to the directory you read this file from, never your CWD. `node "$SKILL_DIR/scripts/lint-tests.mjs"` scans the tree; `--diff <base>` only lines changed since the merge-base. A **gate** rule is decidable and fails the exit code; a **lead** also matches legitimate tests, so read each hit against the principle's look-alikes. Rules, flags, and what a clean run proves (little, for Python and Go): [references/lint.md](references/lint.md).
+
+## Common wrong answers
+
+- "It's green and it has `@covers`" is not coverage. A tag is a claim; read the assertion.
+- A long test is not a strong test. Count the assertions that survive the one question.
+- A clean lint is not a clean suite. The lint finds shapes; the principles need reading.
+- A top-5 list is not an audit. Report every confirmed finding, clustered.

package/skills/engineering/test-quality/references/audit.md

@@ -0,0 +1,80 @@
+# Audit mode, step by step
+
+> Read when: running an audit, or any request that ends in changed tests. Principles and look-alikes: [principles.md](principles.md). Lint rules: [lint.md](lint.md).
+
+Reviewer subagents run the audit and never fix. Any request that ends in changed tests, however it is phrased ("audit and fix", "clean up the tests", "remove the useless ones", "improve the suite"), audits first, then fixes. A request for a report alone stops after the report.
+
+## Two depths
+
+- **Quick audit (the default): done in under 10 minutes.** Reviewers read only the tests the lint flags, within a fixed time budget. It finds what the lint can point at and says plainly what it did not read.
+- **Deep audit: only when the user asks** for one ("deep audit", "read every test", "full read"). Reviewers read every test file in their share. It finds weak assertions the lint cannot see, and it takes as long as the suite is big.
+
+Never pick the deep audit on your own because the suite is large or the request says "full suite": "audit the full suite" names the scope, not the depth.
+
+## Quick audit
+
+The lead runs it; the times are wall-clock budgets, not estimates.
+
+1. **Lint and split (about 1 minute).** From the target repo's root, pass vendored, generated, and fixture trees to `--exclude`, and set `--shares` to the reviewer count: 4, or the harness's parallel subagent limit if lower.
+
+   ```bash
+   node "$SKILL_DIR/scripts/lint-tests.mjs" --exclude node_modules,dist,fixtures,vendor --shares 4 --json > "$RUN_DIR/lint.json"
+   ```
+
+   `$RUN_DIR` is a fresh directory for this audit (for example under `$TMPDIR`). The `shares` array holds the flagged files, split by finding count. No findings: report that the lint is clean, that a clean lint proves little ([lint.md](lint.md)), and offer a deep audit. Do not run the test suite; the audit reads code, and tests run in the fix step.
+2. **Spawn every reviewer at once (6 minutes).** One reviewer per share, all in one batch, so none waits in a queue. Use a balanced-tier model at medium effort: the quick audit reads flagged spots, not whole suites. Each reviewer's prompt names this file, its share's files, `$RUN_DIR/lint.json`, and its report path `$RUN_DIR/share-<k>.md`. Each reviewer follows [the reviewer steps](#reviewer-steps) with a **6-minute budget**: it notes the start time, and when the budget runs out it stops reading and writes what it has, with every unread file under "Not audited".
+3. **Wait silently.** Reviewers reply with one line: their summary line and report path. Do not read replies page by page, do not post an update per reviewer, and do not update the plan per reviewer. A reviewer that has not replied 8 minutes after spawning is left behind: its share goes under "Not audited".
+4. **Merge once (about 1 minute).** Read each `share-<k>.md` once, merge into one report (dedupe, cluster, rank), write it to `$RUN_DIR/report.md`, and post it: the summary line, the costliest findings, the Not audited list, and the report path. This is the first message since the audit started.
+
+## Deep audit
+
+The same flow with three changes: shares are packages or areas instead of lint shares (merge small packages so there are no more shares than the parallel limit), reviewers read **every** test file in their share, and there is no time budget. Reviewers use a frontier-tier model. Files, silence, and the single merge still apply.
+
+## Fix and verify
+
+After the report, and only when the request ends in changed tests:
+
+1. **Fix.** Hand the findings to implementer subagents (Pi's `role.developer`), one per package with disjoint files. Each fixes its findings and runs its package's tests. A reviewer's label is a lead for the implementer too, so before deleting anything:
+   - **Open the twin.** Delete as `Redundant` only after reading the named twin and confirming it drives the same branch with the same input condition, on real dependencies, and asserts at least as strongly. A twin that covers a neighbouring branch (a wrong secret instead of a missing one, a suspended user instead of a suspended membership) is not a twin: keep the test, or keep only its unique part.
+   - **Find what depends on the test.** Search the repo for the file name and the test title. Audit scripts, coverage ledgers, and docs sometimes require a test by name; deleting it breaks them in CI, far from the diff. Update the dependent or keep the test, and say which.
+   - **Name the gap a deletion exposes.** A removed config or text test leaves its behavior unchecked on purpose ([principle 6](principles.md#6-dont-test-config-files)); record the missing behavior check as a follow-up.
+   - **Run what you touched for real.** Run edited files with the lane's real dependencies (start a disposable database for DB-backed tests). A test that could not run is reported unverified, never "unrelated".
+2. **Verify.** Run the lint on the diff, then have a fresh reviewer check the fix diff against the principles. Ask it to compare each deletion with its twin and to look for over-deletion; the fix step errs toward deleting too much, not too little.
+
+## When the goal is speed
+
+A request to make a suite faster "without losing coverage" is a fix request with a time target. The principles still decide what may go; measurement decides what is worth touching.
+
+- **Budget, unless the repo sets its own.** Measured on the CI runner, test execution only (checkout, install, database start and migrations excluded): the unit and integration lanes together take **3 minutes or less**, and the integration lane alone **under 2 minutes**. Neither lane drives a real browser; browser journeys belong to the E2E lane, which has its own budget of **5 minutes or less**. Over budget is a finding even when every test is sound.
+- **Measure before cutting.** Get per-file and per-test durations from the runner (Vitest's JSON reporter or a small reporter over `TestModule.diagnostic()`, `pytest --durations=0`, `go test -json`). For CI, measure on the CI runner: a laptop is often faster and less CPU-bound, so local timings mislead.
+- **Expect little from deleting fast tests.** Mocked unit tests run in milliseconds; removing duplicates is worth it for refactor noise, rarely for time. A few slow files usually dominate. Look in them for real-time waits ([principle 7](principles.md#7-same-code-same-result)) and combinatorial matrices.
+- **Collapse a matrix by code path, then prove it.** Map each case to the production branch it exercises (which lock, which recheck, which input class). Keep one case per distinct path and drop cases that differ only in data that takes the same path. Prove each kept case by disabling its path in production code, watching that case fail, and restoring the code. End with no production diff.
+- **Shorten a wait only when it stays deterministic.** Prefer faking the clock. When real elapsed time is the behavior, follow principle 7's look-alike for it instead of trimming the margin.
+- **Leave runner tuning to CI work.** Shard counts, worker counts, and test pools change no test and belong to the CI workflow (the `github-actions` skill), measured on the runner's real CPU quota.
+
+## Reviewer steps
+
+1. **Start from the lint.** Your share's findings are in `lint.json`. Every hit, gate or lead, is a candidate, not yet a finding. In a deep audit, also grep your files for the quick tells in [SKILL.md](../SKILL.md)'s principle table.
+2. **Read each candidate** and the code it tests. The finding needs the one question answered from the code. You may run one test file to confirm a Lead; never run the suite.
+3. **Check the look-alikes** in each principle's "Not a failure" ([principles.md](principles.md)) before reporting. When unsure, report a `Lead` with the doubt stated.
+4. **Many hits?** Group them by rule and pattern, read a sample from each group until the verdict is clear, then report the group once as a cluster with its count and the files, not hundreds of rows.
+5. **Report**, do not fix. No edits, no rewrites, no deletions, no suggested replacement code. Say what the test fails to prove; the implementer chooses the remedy. Write the full report to your report path in the template below, then reply with one line: `<summary line> — <report path>`. Never paste the report into your reply.
+
+**Labels** (`Not coverage`, `Weak`, `Redundant`, `Lead`) are defined in [SKILL.md](../SKILL.md#labels).
+
+When an audit feeds a coverage grade, `ensure-coverage`'s `references/depth/test-smells.md` maps these labels to its grades (`Not coverage` → `Missing` or `Over-mocked`, `Weak` → `Partial` or `Wrong Level`).
+
+Gate hits map directly: a skipped, empty, or swallowed test is `Not coverage`; a fixed sleep is `Weak`.
+
+**Deliverable.** Size it to the question. Asked about a handful of tests ("which of these should we keep?"), skip the subagents and answer per test in plain words, keep or drop and why, with the label beside it. For a suite or a diff, use the full report:
+
+```markdown
+## Summary — <N> findings over <M> test files: <a> Not coverage · <b> Weak · <c> Redundant · <d> Lead
+## Findings (most costly first)
+| file:line | principle | pattern | label | bug it misses | harmless change that breaks it |
+## Clusters — repeated patterns and their likely cause (e.g. "logic not exported", "no DB in unit lane")
+## Look-alikes kept — tests that matched a quick tell and were cleared, one line each with the reason
+## Not audited — unflagged files (quick audit), paths excluded, unread when the budget ran out, or unreadable, and why
+```
+
+Every finding carries a real `file:line` you opened. Rank by cost: `Not coverage` on auth, money, or data integrity first; noise last.

package/skills/engineering/test-quality/references/lint.md

@@ -0,0 +1,24 @@
+# The lint: rules and limits
+
+> Read when: running `lint-tests.mjs` or reading its findings. Each rule's principle, with its look-alikes: [principles.md](principles.md).
+
+Scripts live under **this skill's directory**. Set `SKILL_DIR` to the directory you read this file from and run `node "$SKILL_DIR/scripts/lint-tests.mjs"`. Never resolve against your CWD. A missing script in the audited repo is not a blocker; the scripts belong to this skill.
+
+A **gate** rule is decidable and fails the exit code; a **lead** rule also matches some legitimate tests, so read each hit against the principle's "Not a failure" cases.
+
+| rule | principle | severity | finds |
+|---|---|---|---|
+| `text-oracle` | 1 | lead | a checked-in doc or source file read and text-matched (one hit per file) |
+| `config-read` | 6 | lead | a checked-in config file read, whatever the assertion (one hit per file); recognizes config by name (workflows, `.mergify.yml`, `cloudbuild*`, Dockerfile, compose, `package.json`, `tsconfig*`, `pyproject.toml`, `.env*`, …), so a file found by `readdir` or an unusual name needs reading |
+| `count-pin` | 2 | lead | an exact size of 5 or more (format lengths 26, 32, 36, 40, 64, 128 excluded) |
+| `mock-internal-seam` | 3 | gate | a mock of first-party code (topology in `coverage.config.json`, conventional defaults if absent) |
+| `utility-class` | 3 | lead | a Tailwind-shaped class asserted in a DOM test |
+| `redundant-matcher` | 4 | lead | `getBy*(…)` then `toBeDefined`/`toBeTruthy`; `get(…).exists()` then `toBe(true)` |
+| `no-empty-test` · `no-swallowed-assertion` · `no-skip` | 4 | gate | empty body; assertion eaten by `.catch()`; declared-skipped, focused, or todo test |
+| `no-fixed-timeout` | 7 | gate | fixed sleep |
+| `conditional-skip` | 4 | lead | `skipif`, a runtime `test.skip()` / `t.Skip()` / `pytest.skip()`, `importorskip`, `xfail` |
+| `duplicate-file` | 5 | lead | test files identical after whitespace (whole-tree and `--files` only) |
+
+Run from the target repo's root: `node "$SKILL_DIR/scripts/lint-tests.mjs"` scans the tree; `--diff <base>` reports only lines changed since the merge-base, including uncommitted and untracked test files; `--files a,b`, `--rules a,b`, `--exclude dist,vendor,fixtures`, and `--json` narrow or reshape it. `--shares N` also splits the files with findings into at most N shares of about equal finding count, keeping each file whole: one share per audit reviewer ([audit.md](audit.md)). Exit 0 means no gate finding, 1 gate findings, 2 a usage error (unknown flag or rule, missing file).
+
+**What a clean run proves.** The rules are written for JS/TS first. `mock-internal-seam`, `redundant-matcher`, and `utility-class` see only JS/TS; Python gets skips, empty tests, `time.sleep`, `text-oracle`, `config-read`, and `count-pin`; Go gets `t.Skip`, `time.Sleep`, `text-oracle`, `config-read`, and `count-pin`. A clean lint on a Python or Go suite proves little: read it.

package/skills/engineering/test-quality/references/principles.md

@@ -0,0 +1,143 @@
+# The seven principles, in full
+
+> Read when: writing a test and unsure which side of a principle it falls on, or auditing (every "Not a failure" here is a look-alike to clear before reporting). The principle statements and the one question live in [SKILL.md](../SKILL.md).
+
+## 1. Test behavior, not text
+
+**Principle.** Run the code and observe what it does. The text of a file (doc, prompt, source, migration) is not behavior. Config files are [principle 6](#6-dont-test-config-files): not tested at all.
+
+**Done right.**
+- Import the config object the code uses and assert the behavior it drives (the OTP expires after 600s: advance the clock, the code is refused).
+- Compare a doc's value to the code's value (`README` port equals `config.port`), so only real drift fails.
+- Scan **every** file for a banned call (no route imports the raw DB client): a rule over the tree, not a line in one file.
+- Assert text the code **produced** from an input (rendered output, CLI error message a user depends on).
+
+**Common failures.**
+- *Prose pin:* `assert "Never force-publish" in runbook`. Rewording fails it; deleting the behavior the sentence describes does not.
+- *Source grep:* `expect(readFileSync('auth.ts')).toMatch(/expiresIn:\s*600/)`, `assert "start >> fee_settings" in dag_source`. A rename breaks it; the value overridden one line later passes it.
+- *Migration grep:* asserting a migration file contains a `CHECK`. It proves the file's text, not that the constraint exists in the database.
+- *Tombstone:* `expect(src).not.toContain('oldFunctionName')`. Guards against one string returning, forever.
+
+**Coverage rule.** A test whose only assertions are text matches over checked-in files is **not coverage** for the behavior the text describes. Report it as `Not coverage`, never as partial proof.
+
+**Not a failure.** A negative pin whose string stands for a forbidden capability in code or output (`not.toContain(secret)` on a response or a log) is behavior: the string is the capability, not wording.
+
+**Why it happens.** Usually the logic is hard to reach: not exported, the framework (Airflow, Next.js wiring) is not loadable in tests, or no DB in the unit lane. Name that cause in the finding; it is the implementer's lead to the fix.
+
+## 2. The expected value comes from somewhere other than the code under test
+
+**Principle.** The expected value must come from an independent source: the spec, an external contract, a separately written and simpler model, or the input. Not from the code under test, and not from a literal copied out of it.
+
+**Done right.**
+- Recompute a webhook HMAC by hand from the provider's published spec.
+- Check pricing against a small, independently written tier table at the boundaries.
+- Derive the expected list from the registry (`readdir(migrations)`, every key in `en` exists in `zh`).
+- Pin a value an outside party depends on: error codes, OIDC discovery fields, wire response keys, a versioned golden that must never change.
+- When a version really is the contract (the runtime needs Node 24), pin the major only: `v24`, not `v24.2.1`. A major version is a compatibility promise; a minor or patch is not.
+
+**Common failures.**
+- *Constant mirror:* `expect(MEMBERSHIP_STATUS.ACTIVE).toBe('active')`, `assert.Equal(t, 3, maxRetries)`.
+- *Count pin:* `toHaveLength(19)`, "exactly 28 skills". Every legitimate addition fails; nobody learns anything from the bump.
+- *Version pin:* `'js-yaml': '4.3.1'` or `node === 'v24.2.1'` asserted in a test. A minor or patch bump fails; behavior is untouched.
+- *Release tag pin:* a pre-release tag asserted in a test: `RC01`, `-rc.2`, `beta.3`. It changes with every release cut, and no bug makes it fail.
+- *Mock echo:* `repo.find.mockResolvedValue(row)` then `expect(result).toEqual(row)`. Fails only if the wrapper drops the value.
+- *Production code as oracle:* `expected := rate * group.PeakMultiplierAt(now)`. A bug in the helper cancels out.
+- *Stub echo:* asserting a `data-testid` or `aria-label` that the test's own stub renders.
+- *Format only:* `len(digest) == 64`. The SHA-256 of the wrong content passes.
+
+**Not a failure.** A length that encodes an external format (UUID, hex digest) *alongside* a value check; an allowlist frozen on purpose because widening it is the risk. Output the code under test *built* from a faked value: a route that serializes a mocked result (`rotatedAt.toISOString()`), wraps it in an envelope (`{ grant }`), or renames its fields. Only an output identical to the fake's return is an echo.
+
+## 3. Fake only what you don't own
+
+**Principle.** Real internals, faked externals. Substitute only what you do not own: third-party APIs, providers, clock, randomness (faking the clock and randomness is also how a test stays repeatable: [principle 7](#7-same-code-same-result)). Your database and services run for real, because a fake cannot see what lives in them: transactions, tenant filters, locking, idempotency.
+
+**Done right.**
+- Real Postgres with migrations; only the payment provider faked.
+- A spy at an external boundary where **the call is the behavior**: the backoff delay, the precondition header sent to storage, "the provider was not called after validation failed".
+
+**Common failures.**
+- *First-party mock:* `vi.mock('@/lib/prisma')`, patching the class's own `_private` helper. The `mock-internal-seam` rule catches the JS module form. Your own thin adapter around a provider (`@/lib/stripe-client`) *is* the external boundary: declare it in `coverage.config.json` under `mockPolicy.externals` rather than calling it a finding.
+- *Blind injected fake:* a `deps` fake returns rows whatever the query says, and the test asserts `findUnique({ where: { id } })`. Delete the tenant check and it stays green. No rule sees `deps` injection; read for it.
+- *Mocked transaction:* "updates atomically" with `$transaction: (fn) => fn()`.
+- *Layout in jsdom:* `toHaveClass('min-h-11')` to prove a 44px target. jsdom has no layout.
+
+An over-mocked test is `Not coverage` **for the behavior the fake hides** (a mocked repo proves nothing about the query or the tenant filter), though it may still cover the caller's own branching. An untested path is an honest gap; an over-mocked one is false green.
+
+## 4. An assertion must be able to fail
+
+**Principle.** Every test must be able to go red, and must check what its name promises. Read the name's verbs ("atomically", "then", "decompresses", "corrected to", "byte-stable") and find the assertion for each.
+
+**Done right.**
+- A test named "retries then gives up" asserts the attempt count **and** the order **and** the final error.
+- A rejection test asserts the specific error code or message, so it cannot pass for an unrelated reason.
+- `waitForRequest(...)` or `ExpectationsWereMet()` as the assertion: it fails by timing out or by unmet expectation. Not assertion-free.
+
+**Common failures.**
+- *No assertion:* a body that runs code and checks nothing, or only `NoError` / `NotNil` on a constructor.
+- *Redundant matcher:* `expect(screen.getByText('x')).toBeDefined()`. `getBy` already throws when the text is missing, so the matcher adds nothing and the test proves presence only. Shallow, not vacuous: `Weak` if its name claims more, otherwise leave it.
+- *Self-skipping:* `if (visible) expect(...) else test.skip()`; `pytest.skip` inside `except ImportError`; an env-gated skip whose variable CI never sets.
+- *Vacuous loop:* `for row in rows: assert isinstance(row, dict); break` passes on zero rows.
+- *Shape only:* `hasattr(dal, 'read')`, `callable(run)`, `typeof processed === 'number'` (passes on 0).
+- *Loose rejection:* `toThrow()` with no type or message; `status !== 0`; `notDeepEqual(errors, [])`.
+- *Name over-promises:* "calling start twice does not create a second timer" with no assertion; "sanitizes the SVG" asserting only a toast.
+- *Deny-list for leaks:* 12 `not.toHaveProperty` on a response. A new sensitive column leaks green; an exact-keys allowlist fails.
+
+**Not a failure.** A precondition `toBeDefined()` on a value that can really be `undefined` (an `Array.find` result) followed by real assertions; accept-case `NoError` in a validator whose reject cases sit beside it; a skip on a platform or optional dependency (`skipif(sys.platform == 'win32')`) or a strict `xfail` pinned to an open issue, when CI still runs the test somewhere.
+
+## 5. Test each behavior once, and only for code that still runs
+
+**Principle.** Each behavior is proven once, at the lowest level that can prove it for real, for code that still runs.
+
+**Done right.**
+- An exhaustive pure unit for the decision table plus one real-DB integration test per rule: that is layering, not duplication.
+- Many similar cases folded into one table-driven test (every route rejects a missing token), so each row adds a branch.
+- A guard test that *asserts* two deliberately mirrored files stay identical, instead of two identical suites.
+
+**Common failures.**
+- *Copied files:* the same test file in two directories, both run. They drift, and fixes land in one copy.
+- *Mocked twin:* `service.test.ts` (mocked DB) repeating `service.integration.test.ts` case for case. The mocked copy catches nothing the real one misses.
+- *Extraction leftovers:* logic moved to a shared package; each app kept its own copy of the tests.
+- *Subsumed page-load:* an e2e test that only checks a heading, beside tests that load the same page and act on it.
+- *Dead code:* tests of a spike, a one-off release script, or a module only tests import.
+- *Diverged siblings:* copy-pasted tests that disagree; one pins the bug the others fixed. A duplicate is also a divergence lead.
+
+**Not a failure.** 69 near-identical "returns 401" tests prove 69 routes call auth. That is *merge into a table*, not *delete*.
+
+## 6. Don't test config files
+
+**Principle.** Config is not code, so it gets no tests. Dockerfiles, `cloudbuild.yaml`, `.github/workflows/*`, `.mergify.yml`, `docker-compose.yml`, Kubernetes and Skaffold manifests, `package.json`, `tsconfig.json`, `pyproject.toml`, `.env` files, and any other JSON, YAML, or TOML file a tool reads: the tool that reads it is the test. CI parses and runs the workflow, `docker build` builds the image, Mergify validates its config, the deploy deploys. A test that reads the file back, as text or parsed, only restates it.
+
+**Done right.**
+- Test the code that *reads* config: the app loads `retries: 3` from `config.json`, so make the call fail three times and assert it gives up.
+- Scripts are code, not config. A release or deploy script (`release.mjs`, `deploy.sh`) with real logic is run against a throwaway repo or a fake `gcloud`, and what it did is asserted.
+- Leave the file untested. A broken workflow fails CI; a broken Dockerfile fails the build; a broken queue rule shows in the queue. That failure is the proof.
+- When you delete a config test, name the behavior it stood in for as a follow-up: the smoke, post-deploy, or runtime check that would catch the bug for real. Deleting exposes that gap; keeping the pin hides it.
+
+**Common failures.**
+- *Parsed mirror:* `yaml.load('.mergify.yml').queue_rules[0].batch_size === 3`, `JSON.parse(package.json).engines.node`. A deliberate change fails it; nothing that runs is checked.
+- *Text mirror:* `expect(workflowYaml).toContain('postgres:17')`, `assert "--no-traffic" in cloudbuild`. A bump or rename fails; a broken step with the literal intact passes.
+- *Setting mirror:* `concurrency`, `timeout-minutes`, a matrix entry, a Docker base image, or a cloudbuild step read back out of the file.
+- *Policy pin:* "the workflow has no `pull_request_target`", "no `--network=host`". Still a config test; a policy tool (actionlint, a ruleset, an org policy) owns it.
+- *Hand-rolled validity sweep:* a test that parses every workflow to prove it is valid. The tool already refuses an invalid file.
+- *Simulated pipeline:* executing `cloudbuild.yaml` steps under a fake `gcloud` to prove the config. It tests a copy of the runner, not the runner.
+- *Regression pin:* a text match added after a real bug, such as `expect(dockerfile).toMatch(/^COPY content \.\/content$/m)` once `/docs` shipped empty. Still a config test, and it never runs the deployed page. Delete it and file the missing behavior check; do not keep it as the guard.
+
+**Not a failure.** JSON the app loads as data is not config: a locale file (every key in `en` exists in `zh`), a price table, a seed catalog. Test fixtures, files the test writes itself, and a config file passed to the code under test (`cli --config fixtures/app.json`) are inputs, not the thing tested.
+
+## 7. Same code, same result
+
+**Principle.** A test must pass or fail the same way on every run of the same code. Anything that changes between runs (randomness, the clock, timing, run order, the network) is fixed by the test, not left to chance.
+
+**Done right.**
+- All IDs and random numbers come from one seeded generator or fixed ID factory; the seed is logged when randomness must stay.
+- The clock is frozen or injected; the time zone and locale are set by the test.
+- Async work is awaited on the condition it produces, not on a sleep.
+- Each test creates the state it needs and doesn't read what another test left.
+
+**Common failures.**
+- *Unseeded randomness:* random values in checked output now and then match a pattern check (a card-number scanner, a snapshot). Fixing values one at a time never ends; fix the source.
+- *Live clock:* passes all day, fails at midnight, at month end, or in another time zone.
+- *Fixed sleep:* `sleep(500)` before asserting async work. Passes on a fast machine, fails under load, and hides the condition the test should wait on.
+- *Order dependence:* passes in the full suite, fails when run alone, or the reverse.
+
+**Not a failure.** A property-based or fuzz test that uses randomness on purpose and logs its seed, so any failure can be replayed. Real elapsed time that *is* the behavior, such as a deadline that must pass while a database lock is held, measured by the database clock that a fake cannot move. Wait on the condition (the clock passing the deadline), not a fixed sleep; treat an attempt whose precondition was observed too late as inconclusive and retry it with a longer margin; and assert persisted state afterwards, so a retried attempt cannot hide a bug.

package/skills/engineering/test-quality/references/testing-conventions.md

@@ -0,0 +1,9 @@
+## Testing conventions
+
+1. Run the code and assert what it does; never match the text of docs, prompts, source files, or migrations.
+2. Take expected values from the spec, an external contract, or the input, never from the code under test; pin versions to the major only.
+3. Fake only third-party services, the clock, and randomness; run your own database and services for real.
+4. Make every assertion able to fail, and assert everything the test name promises.
+5. Test each behavior once, at the lowest level that proves it; delete tests of dead code.
+6. Don't test config files (Dockerfiles, CI workflows, `cloudbuild.yaml`, merge-queue config, `package.json`, other JSON/YAML/TOML a tool reads); test the code that reads them.
+7. Seed randomness, freeze the clock, wait on conditions instead of sleeps, and never depend on another test's state.

package/skills/engineering/test-quality/release-check.mjs

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+import { spawnSync } from 'node:child_process';
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+const WEEK_MS = 7 * DAY_MS;
+const here = dirname(fileURLToPath(import.meta.url));
+
+function readJson(path, fallback = {}) {
+  try { return JSON.parse(readFileSync(path, 'utf8')); } catch { return fallback; }
+}
+
+function frontmatterValue(text, key) {
+  const frontmatter = /^---\n([\s\S]*?)\n---/.exec(text)?.[1] ?? '';
+  const match = new RegExp('^' + key + ':\\s*([^\\n]+)$', 'm').exec(frontmatter);
+  return match?.[1].trim().replace(/^['"]|['"]$/g, '') ?? null;
+}
+
+function repositoryOf(source) {
+  const value = String(source ?? '').trim();
+  const match = /^(?:git@github\.com:|https:\/\/github\.com\/)?([A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+?)(?:\.git)?$/.exec(value);
+  return match?.[1] ?? null;
+}
+
+function stableVersion(value) {
+  const match = /^v?(\d+)\.(\d+)\.(\d+)$/.exec(String(value ?? '').trim());
+  return match ? match.slice(1).map(Number) : null;
+}
+
+function newer(left, right) {
+  for (let index = 0; index < 3; index += 1) {
+    if (left[index] !== right[index]) return left[index] > right[index];
+  }
+  return false;
+}
+
+function writeCache(path, value) {
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(value));
+  } catch { /* A read-only cache must not block skill use. */ }
+}
+
+function main(now = Date.now()) {
+  if (process.env.ONEABOVEIO_NO_UPDATE_CHECK) return;
+  const skill = readFileSync(join(here, 'SKILL.md'), 'utf8');
+  const name = frontmatterValue(skill, 'name');
+  const localVersion = stableVersion(frontmatterValue(skill, 'release-version'));
+  if (!name || !localVersion) return;
+
+  const lock = readJson(join(process.env.HOME || homedir(), '.agents', '.skill-lock.json'));
+  const entry = lock.skills?.[name];
+  const repository = repositoryOf(entry?.sourceUrl || entry?.source);
+  if (!repository) return;
+
+  const cacheRoot = process.env.XDG_CACHE_HOME || join(process.env.HOME || homedir(), '.cache');
+  const cachePath = join(cacheRoot, '1aboveio-skills', 'release-check.json');
+  const all = readJson(cachePath);
+  const cache = all[repository] && typeof all[repository] === 'object' ? all[repository] : {};
+
+  if (!cache.lastCheck || now - cache.lastCheck >= DAY_MS) {
+    const result = spawnSync('gh', ['api', 'repos/' + repository + '/releases/latest', '--jq', '.tag_name'], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: 1500,
+    });
+    cache.lastCheck = now;
+    if (result.status === 0 && stableVersion(result.stdout)) cache.latestTag = result.stdout.trim();
+    else delete cache.latestTag;
+    all[repository] = cache;
+    writeCache(cachePath, all);
+  }
+
+  const latestVersion = stableVersion(cache.latestTag);
+  if (!latestVersion || !newer(latestVersion, localVersion)) return;
+  if (cache.notifiedTag === cache.latestTag && cache.notifiedAt && now - cache.notifiedAt < WEEK_MS) return;
+
+  cache.notifiedTag = cache.latestTag;
+  cache.notifiedAt = now;
+  all[repository] = cache;
+  writeCache(cachePath, all);
+  const command = `npx skills@1.5.23 add '${repository}#${cache.latestTag}' --global --agent universal claude-code --skill ${name} --yes`;
+  process.stdout.write(
+    `UPDATE_AVAILABLE: A newer 1AboveIO skills release (${cache.latestTag}) is available; this skill is `
+      + `v${localVersion.join('.')}. Ask once whether to refresh ${name}. On approval run \`${command}\`. `
+      + 'The refreshed instructions apply next session. Either way, continue the current task and do not ask again this session.\n',
+  );
+}
+
+try { main(); } catch { /* Update checks are advisory and always fail silent. */ }