@1aboveio/skills 0.0.0-stage → 1.0.0

package/skills/core/write-doc/references/bilingual.md

@@ -0,0 +1,60 @@
+# Chinese and bilingual mode
+
+Language is a setting that works with every template. There is no Chinese-only or bilingual
+template.
+
+## Pick the mode
+
+Choose it as in [SKILL.md step 1](../SKILL.md#write-a-new-document). The modes:
+
+- **English** or **Chinese**: one version.
+- **Bilingual, separate versions**: two files, `<name>.en.md` and `<name>.zh.md`, same headings in
+  the same order.
+- **Bilingual, paired paragraphs**: one file; each English paragraph followed by its Chinese
+  paragraph. Headings carry both: `## Scope 范围`. Tables keep one table, with paired cells only
+  when WRITING.md asks for it; otherwise one table per language.
+
+## Write
+
+Chinese-only mode: write and review the document in Chinese, apply [中文风格](../../house-style/references/style-zh.md),
+then go to step 5. Bilingual modes: steps 1 to 5.
+
+1. Write and review the whole document in the source language: the one the brief names, else
+   WRITING.md's Language section, else English. Do not draft both languages at once.
+2. Produce the second version from the reviewed source. Use TERMINOLOGY.md for every term it
+   lists. Translate every other term, including role and team names. Keep a term in the
+   source language only when TERMINOLOGY.md says so, or it is a product name, code or an
+   abbreviation the reader uses daily. Example: the table keeps "MLRO" in English; "Head of
+   Compliance" becomes 合规主管 (繁體：合規主管). Add each new non-obvious translation to TERMINOLOGY.md as
+   `proposed`, and list it in the delivery note.
+3. Write the second version as a native writer would. Restructure sentences freely; do not keep the
+   source's word order. Apply the [English style](../../house-style/references/style-en.md) or
+   [中文风格](../../house-style/references/style-zh.md) guide to each version.
+4. Run the equivalence check below. Fix every difference in the version that is wrong.
+5. Polish the Chinese version with `polish-cn` when installed (bilingual: after the equivalence
+   check passes).
+   Not installed: say so in the delivery note.
+
+## Equivalence check
+
+Compare the two versions section by section. They must match on:
+
+- Names of people, organizations, products and systems.
+- Numbers, amounts, currencies, percentages, units, dates and deadlines.
+- Conditions and scope: "if", "unless", "only", "at least", thresholds.
+- Obligation strength: must / must not / should / may ↔ 必须 / 不得 / 应当 / 可以 (Traditional:
+  必須 / 不得 / 應當 / 可以), unless WRITING.md maps them otherwise; "will" never becomes "may", and
+  将 / 將 never becomes 可能.
+- Uncertainty and caveats: a hedge in one version is a hedge in the other.
+- Recommendations, decisions, owners and next steps.
+- Structure: headings, list items, table rows and columns, links and anchors, code, field names,
+  every gap marker in either form, including bare `TBD` / `待确认` / `待確認` table cells (one for
+  one).
+
+Neither version may contain a fact, claim, example or caveat the other lacks. A sentence that only
+reads well in one language is rewritten in both, or cut from both.
+
+## Corrections
+
+A correction applies to this document only ([who edits what](../../house-style/references/rules.md#who-edits-what)); mention
+`/distill-writing` once in the delivery note.

package/skills/core/write-doc/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/better-review/LICENSE

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

package/skills/engineering/better-review/SKILL.md

@@ -0,0 +1,249 @@
+---
+name: better-review
+description: "Slash/explicit-only (/better-review). Single-agent adversarial review of a branch or PR diff, under 10 minutes for a normal-sized change: Spec, Correctness, Test honesty, and Standards passes run in order in one context (no subagents), each finding proven by a file:line and the input that breaks it, rated P0-P2 (P3 cleanup is never reported), with the checks behind it actually run. Use when the user wants a branch, PR, or work-in-progress diff reviewed, asks to \"review since X\", or a delivery workflow needs an independent review, including re-reviews after fixes. Do not auto-select. NOT judging a test suite on its own (test-quality) or defining what must be tested (ensure-coverage)."
+disable-model-invocation: true
+dependencies:
+  - engineering-runtime
+release-version: 0.36.0
+---
+**Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
+# Better Review
+
+One reviewer, one context, four passes over the net diff, done in **under 10 minutes**: separate
+Spec and Standards axes and an adversarial method, with no sub-agents and no contract paperwork.
+
+**Find your task, read that row, then follow [The run](#the-run).**
+
+| Task | Read |
+|---|---|
+| Run a review end to end | [Review the rule, not the instance](#review-the-rule-not-the-instance), then [The run](#the-run) below |
+| How to do each pass: the adversarial techniques, the sweeps, what not to flag | [references/passes.md](references/passes.md) |
+| The diff touches auth, money, tenancy, or a migration | [references/domain-hazards.md](references/domain-hazards.md) |
+| Write the result for a caller (JSON shape, severities, follow-ups) | [references/result.md](references/result.md) |
+| Which tier a new HEAD gets: skip, delta, or full | [Review tiers](#review-tiers) below |
+| Review round 2 or later (after fixes or a rebase) | [Re-review](#re-review) below |
+
+## Rules that do not move
+
+1. **Do every pass yourself. Never spawn a subagent and never invoke `code-review`.** The caller
+   runs with a small agent cap; one review is one slot.
+2. **The subject is the net diff** `git diff <merge-base>...HEAD` (three-dot). What was already
+   there at the merge-base is a P2 note when serious, else left out. Read unchanged code freely,
+   but only to prove a finding the diff causes.
+3. **Judge against the spec and the repo's written rules, nothing else.** Example: the spec says
+   "persist per installation", so per-user storage is P1; an audit log the spec never asks for is
+   P2 at most.
+4. **Produce the counterexample, not an opinion.** A P0/P1 needs a `file:line` and the concrete
+   input, state, or sequence that breaks it. The line is in the diff, or for missing behavior, the
+   place the behavior should live plus the spec line asking for it. No trigger means P2 at most.
+   Example: "P1: a retry reuses the single-use JWT; the second call returns 401" blocks; "could
+   use more tests here" is P2 at most.
+5. **Verify against the tree, never the narration.** PR body, commit messages, test names, logs,
+   and "CI is green" are claims: run or read the thing. Never ask the author for evidence documents.
+6. **Not being able to run a check is not a finding.** List it under `notRun` with its command and
+   error verbatim; never turn "I could not run it" into "it is missing". Example: no emulator is
+   available, so list the emulator journey as not run; do not rate the code P1 for it.
+7. **Run the changed files' tests and the check behind each blocker; nothing broader.** Example:
+   you claim a refund rounding bug, so run the refund tests and the test that shows it; do not
+   rerun the full suite for reassurance.
+8. **Every round covers the whole diff:** in full, or by the [tier](#review-tiers)
+   `rereview-scope.mjs` picks. A sampled or timed-out pass is unfinished, not done.
+
+## Review the rule, not the instance
+
+**Every P0/P1 is a broken rule with all its paths, one id every round:** apply the six
+[principles](references/passes.md#review-the-rule-not-the-instance) to each P0/P1 candidate. Example: "a refund never exceeds
+the captured amount" is the finding; "a second partial refund succeeds" is one path.
+
+## Review tiers
+
+Every HEAD sent for review gets one tier. The first review is always full; from round 2, `rereview-scope.mjs`
+picks the tier from the previous result. Widen a tier when you must, never narrow one.
+
+| Tier | When | What is reviewed | Checks |
+|---|---|---|---|
+| **skip** | The previous review passed (no open P0/P1) and the PR's own changes are unchanged: the same HEAD (whose approval already holds), the same patch over a base that moved only outside the PR's files, or the same changed lines at the same places in every file the base moved under (a conflict resolved by keeping both sides counts) | Nothing: no reviewer runs. `--write-skip` writes the record that carries the approval to this HEAD | None. CI on this HEAD is the proof |
+| **delta** | Fix commits since the last round, a rebase that changed or moved the PR's own lines in a file the base moved under, or any new HEAD while a P0/P1 is open; and no full trigger | The fix diff and merge diff at full depth; carried files only at their `callSites` | Tests whose inputs changed, every check a P0/P1 rests on |
+| **full** | The first review, or any full trigger below | The whole diff, every pass | [Step 5](#5-run-the-checks-and-report-2-min) |
+
+**Full triggers.** The script names each one in `reasons`; the round number and a previous delta never force full:
+
+- the previous round was incomplete or oversize;
+- fixes and base changes since the last full review touch more than half the PR's lines;
+- the impact of a base change on the PR's own lines cannot be bounded;
+- the previous HEAD is gone and the patch changed, or its `patchFingerprint` is missing;
+- the previous merge-base is missing from the repository;
+- the previous result lacks `head`, `mergeBase`, or `round`;
+- the PR's previously reviewed changes were removed.
+
+**Never carry a blocker.** A previous review with an open P0/P1 never yields skip, even on an
+unchanged HEAD or after a rebase: the blocker is fixed, then reviewed as a delta.
+
+Examples:
+- Round 3 changed one function to fix R1: **delta** over it, its callers, and any merge diff.
+- A rebase onto main that only moved `docs/`, after a passing review: **skip**.
+- Main changed `b.ts`, which the PR also edits, and the PR's own lines there are unchanged at the same places (a conflict resolved by keeping both sides included): **skip**.
+- A conflict resolution rewrote three PR lines in `b.ts`: **delta** over those hunks, their
+  callers and shared invariants. If they reach a lock order the whole module relies on and you
+  cannot bound it, widen to **full** and name why.
+
+## The run
+
+Time targets add up to 10 minutes for a normal-sized change: finish a pass that runs long and
+tighten the next; an oversize change takes longer.
+
+### 0. Setup (≤1 min)
+
+Resolve `SKILL_DIR` to the directory you read this file from (never your working directory, never
+a `find` over `$HOME`).
+
+```bash
+node "$SKILL_DIR/scripts/pr-context.mjs" --base <target-branch>       # JSON: mergeBase, files, diffstat
+git diff <mergeBase>...HEAD | node "$SKILL_DIR/scripts/scan-diff.mjs"
+```
+
+Read both outputs where they print; a read-only sandbox is fine.
+
+- The target is what the caller or user named, else the PR's base (`gh pr view --json baseRefName`),
+  else the default branch, as a fetched remote ref (`origin/main`). Fail on a bad ref or empty diff.
+- `scan-diff` prints **leads** (places to look; never findings by themselves) and **findings**
+  (`over-mock-internal-seam`: a first-party mock, rated in pass 3).
+- If `pr-context` reports `promotion: true`, this is a release merge of already-reviewed commits,
+  not a feature review: report whether it fast-forwards (`fastForwardable`, and any
+  `commitsOnBaseNotInHead` it would revert), and stop.
+- **Oversize:** more than ~1,500 changed lines or 40 files (generated and lock files excluded).
+  Still review all of it, highest-risk files first, set `oversize: true` in the result, and say
+  in the summary that the change should be split.
+- Collect the inputs: the spec (the caller's, else issue refs in commits and the PR body, else a
+  matching file under `docs/`, `specs/`, `.scratch/`) and the repo's written standards
+  (`CONTRIBUTING.md`, `AGENTS.md`/`CLAUDE.md`, and the style docs or ADRs the diff touches).
+  Missing spec: run code-only and say "no spec found". Do not stop to ask. Leave the hazards
+  files for pass 2, which reads them only when the diff needs them.
+
+### 1. Spec (≤2 min)
+
+Skip with "no spec found" when there is none. Otherwise list **every** acceptance criterion and
+judge each on its own row:
+
+- **Met** only when the result for the real runtime input is right (not just the right call or
+  constant present) and a test asserting it would go red if the behavior were removed.
+- **Unmet or wrong** is P1. **Unverified** (implemented, but no test that would fail if it were
+  removed) is P1 too: an acceptance criterion with no such test is not proven.
+- Behavior nobody asked for (scope creep) is P2, or P1 if it changes a contract code relies on.
+
+### 2. Correctness, adversarial (≤3 min)
+
+Try to prove the change is broken. For each changed function or rule, run the four techniques (and
+check the shapes) in [passes.md](references/passes.md#adversarial-techniques): diff it against its siblings, break its
+patterns with boundary inputs, hold its async steps open, and name the test for each new branch:
+
+- **Every regex, glob, parser, or validator the diff adds or changes:** list it and the inputs you
+  tried against it (prefix and substring leakage, empty, case, escaping, a malformed value it
+  should reject), and record them under `boundaries` in the result. Writing the inputs down is
+  what stops this check being skipped when a pattern looks fine at a glance.
+- **Every async step the change relies on** (sign-out, revoke, refresh, cancel, save, upload):
+  hold it pending and settle it each way (success, refusal, error, timeout) against the events
+  [principle 3](references/passes.md#review-the-rule-not-the-instance) scopes. Rule a cell out by code, or in one line when
+  the program cannot produce the event; record it under `windows`.
+- **Callers and sibling paths:** follow each changed contract to every place that uses it or must
+  apply the same rule.
+- **High-risk surface** (auth/token/session, money/tax, tenancy/org scope, migration): hunt it
+  against [domain-hazards.md](references/domain-hazards.md) and the repo's own hazards file
+  (`docs/domain-hazards.md`, or wherever `AGENTS.md`/`CLAUDE.md` points). An
+  exploitable security, auth, money, tenancy, or data-loss defect is P0/P1.
+- **A rule that must hold in several places** (a validator, a guard, a behavior the diff changes): run
+  the [enforcement-point sweep](references/passes.md#enforcement-point-sweep). Every unenforced
+  point is an open `paths` row of the rule's finding this round; a guard copied to each point
+  gets one owner as the fix ([principle 5](references/passes.md#review-the-rule-not-the-instance)). One place only: say so in one line.
+- **Narration drift:** a comment, `--help`, doc, or PR claim that contradicts the code. P1 where
+  the prose is what agents or users act on; otherwise skip it.
+
+### 3. Test honesty (≤1 min)
+
+The tests in the diff are evidence only if they can fail. Each of these is P1 when the test is
+cited as proof of a requirement or fix, otherwise P2:
+
+- a mock of a first-party module (`scan-diff`'s finding channel): it proves only wiring. Faking
+  an external (third-party API, clock, randomness) is fine. The fix is a real test, a fake of
+  only the external, or deleting the test;
+- an added skip, `.only`, `xit`/`xfail`/`fixme`, fixed sleep, empty body, or an assertion weakened
+  to pass on an error, empty, or 404 page;
+- an assertion that cannot fail (a swallowed rejection, a try/catch that re-passes, a check
+  against a stub);
+- a bug fix with no test that would have been red on the pre-fix tree;
+- a test that awaits an async step to completion, cited as proof of the pending state (unverified).
+
+### 4. Standards (≤1 min)
+
+Last on purpose, so style never steers the passes above. Cite the documented rule (file and rule)
+for each violation; skip what tooling already enforces. A rule the repo marks required (must, gate)
+is P1; other documented rules P2. Skip undocumented cleanup: naming, smells, cosmetics, and
+architecture opinions would be P3, and this review never reports P3.
+
+### 5. Run the checks and report (≤2 min)
+
+- Run the tests for the changed files, plus lint or typecheck when cheap. Rerun any check a
+  P0/P1 rests on. Record each exact command in `commands`; never accept a producer's log instead.
+  `commands` lists checks run against the code only, never this skill's update check or scripts.
+- Apply the [finding bar](references/passes.md#the-finding-bar) before reporting: a few strong
+  findings beat many weak ones, and "no blocking issues" is a valid result.
+- **Caller gave a result path:** write the JSON in [result.md](references/result.md), including
+  the sweeps you ran (a later round re-checks them), and file the follow-ups the caller asks for.
+- **Otherwise** report in chat: one section per pass in run order, then one line with the count
+  per pass and the worst finding in each. Do not merge or rerank findings across passes.
+
+Write each pass's findings down before starting the next, and never re-rate an earlier pass's
+severities because of a later one: that keeps the passes independent without extra agents.
+
+## Re-review
+
+From round 2 the caller gives you the previous round's result file and its open P0/P1 findings.
+**No previous result file** (for example, a user says "I fixed it, review again"): do a full run,
+then check each finding you were told about as in Re-review step 3 below.
+
+1. **Let the script pick the [tier](#review-tiers)**, and run it before reading anything else,
+   including the files the caller attached: its output already contains what you need from them.
+
+   ```bash
+   node "$SKILL_DIR/scripts/rereview-scope.mjs" --prior <previous-result.json> --base <target-branch>
+   ```
+
+   - `skip`: review nothing. With a result path from the caller, run the same command again
+     with `--head <the sha the caller named> --write-skip <result path>`: the record it writes is your result. Tell the caller the
+     tier and stop. (`--write-skip` writes nothing on delta or full.)
+   - `full`: run [The run](#the-run) on the whole diff, then step 3 below.
+   - `delta`: continue with step 2. `integrationFiles` names PR files whose own changes were
+     rewritten over a moved base; `mergeFiles`, those it moved under cleanly. Review their
+     resolved hunks, callers and shared invariants. `baseDiffCommand` shows every base change,
+     including dependencies outside PR files; check the relevant ones.
+
+   Copy `fixRound` from the output into the result: it is the caller's fix counter, and the tier
+   never changes it.
+2. **On `delta`, its output is your setup.** Skip step 0 entirely: no update check, no
+   `pr-context`, no whole-diff scan, and no re-reading repo docs or `references/` unless the fix
+   diff needs one (it touches a hazard surface, adds an async step, or adds a multi-place rule).
+   The output holds `fixDiff` (the fix diff itself; `null` when too large, then run
+   `fixDiffCommand`), `openFindings` (full; read the [principles](references/passes.md#review-the-rule-not-the-instance) when one is open), `sweepRecheck` (previous sweep points in touched
+   files), `changedSymbols`, `callSites` (every line in a carried file that uses a changed name),
+   and `fixScan` (leads and findings for the fix diff alone). Each tool call costs seconds, so a
+   delta round is mostly about making few of them.
+3. **Each open finding** is resolved only when every `paths` row, re-derived from the tree
+   ([principles 2, 4, 6](references/passes.md#review-the-rule-not-the-instance)), is closed at a `file:line`; a new
+   witness of its rule is an open row under its old id at its old severity. A previous P2 is
+   closed: raise it again only when it is now P1.
+4. **The fix diff** (`fixDiff`): run passes 1-4 on it at full depth, including `boundaries` and
+   `windows` for any pattern or async step it adds or changes; re-check each `sweepRecheck` point.
+5. **The carried files:** re-check correctness at the `callSites` lines and every open `paths`
+   row, reading enough around each to judge it. If `callSites.truncated` is true, search the
+   rest yourself. Spec rows and standards findings carry over, except open P0/P1 rows (step 3).
+6. **Checks:** run the tests whose inputs changed, every check a current P0/P1 rests on,
+   and affected required checks (generated artifacts, lint). Carry unaffected passing
+   results forward with their reviewed HEAD; do not report them as freshly executed.
+   Record actual code checks, such as `git diff --check`, in `commands`; never copy old
+   commands as if they ran this attempt.
+7. **Write the result** with `tier: "delta"`, `passes` covering this attempt, `mergeBase`,
+   `patchId`, `patchFingerprint`, `fixRound` and `fixLinesSinceFull` from the script's
+   output, and the previous `sweeps`, `windows` and `boundaries` carried forward with
+   the touched points updated. `findings` holds the prior findings still open, under
+   their old ids, plus any new ones; resolved findings are left out. A delta round should take a
+   few minutes at most.

package/skills/engineering/better-review/agents/openai.yaml

@@ -0,0 +1,9 @@
+interface:
+  display_name: "Better Review"
+  short_description: "Slash/explicit-only single-agent adversarial review of a branch or PR diff, with skip, delta, or full re-reviews"
+
+policy:
+  # Codex counterpart to SKILL.md disable-model-invocation: true.
+  # Keeps $better-review / explicit invoke (and delivery workflows reading it by path)
+  # while blocking description-based selection.
+  allow_implicit_invocation: false

package/skills/engineering/better-review/references/domain-hazards.md

@@ -0,0 +1,53 @@
+# Domain hazards: the high-risk hunt list
+
+The bug classes that a happy-path implementation ships and CI passes green, on the surfaces whose
+contract is hardest to pin down: auth, money, tenancy, and migrations. Read when the diff touches
+one of them, and hunt the matching section. An unhandled item is a finding, P0/P1 when exploitable
+or contract-breaking ([result.md](result.md#severity)).
+
+This is the generic shape. The repo's own values (its issuer, currencies, tenant column, migration
+tool) live in its hazards file: follow the `Domain hazards` heading in `AGENTS.md`/`CLAUDE.md`, else
+read `docs/domain-hazards.md`, else there is none. Hunt against both. You are read-only: when a
+blocking finding deserves a new row in that file, say so in the finding's summary.
+
+The rule behind every class: **decide by a positive allow-list, default to deny, and prove the
+result for the value the app actually produces at runtime, not a convenient fixture.**
+
+---
+
+## 1. Auth / authz / token / session
+
+| Hazard | Failure mode (real cases) | What to prove |
+|---|---|---|
+| **Fail-open guard/verifier** | On error / unknown input / unmatched branch, the code *allows* instead of denying. A signature verifier with an HMAC catch-all fallback; a country/eligibility check that skips the gate for unrecognized spellings. | Every error and `else` path **denies**. The default is deny. Add a test that feeds the unrecognized/garbage input and asserts refusal. |
+| **Token/assertion validation** | Wrong issuer, wrong/defaulted `client_id`, missing audience check, unpinned algorithm (accepts `none` or HMAC where RS/ES expected). POSTing to the wrong endpoint (broker vs OIDC issuer). | `iss` / `aud` / `scope` / `exp` / signature-alg each asserted against the **real IdP contract**, not a literal default. Alg pinned. Target endpoint is the issuer, verified against the discovery doc. |
+| **Replay / single-use / idempotency** | A one-time code (nonce, `jti`, `device_code`, OTP) accepted twice; no brute-force limit. | The code is consumed **atomically** and a second use is rejected; a replay test proves it; sensitive endpoints are rate-limited. |
+| **Clock skew** | Assertion/token lifetime unbounded or with no skew tolerance; `iat`/`nbf`/`exp` mishandled. | Lifetime is clamped to a bounded window; skew tolerance is explicit; a token just inside/outside the window is tested both ways. |
+| **Open redirect / dropped `returnTo`** | Redirect target derived from user input without an allow-list; a centralizing auth refactor drops the deep-link `returnTo` and lands the user on a default page. | Redirect targets pass a **positive allow-list** (`^/(?![/\\])` or exact known routes), and `returnTo` survives the whole flow (characterization test on the deep-link path). |
+| **Revocation during a pause** | Sign-out or access loss that arrives while the app is backgrounded, hidden, or a check is in flight takes the temporary-pause path, so private data or a session outlives the revocation until the pending call settles (a downloaded document kept for as long as a hanging logout request runs). | Revocation acts when it starts, not when it settles. A test holds the revocation pending in each paused state and asserts the private data is gone. |
+| **Privilege on switch** | Org-switch / impersonation / role change doesn't re-scope the session or leaves stale elevated state. | The switch re-derives authorization; a test asserts the post-switch scope, not just that the switch succeeded. |
+
+## 2. Money / tax / pricing
+
+| Hazard | Failure mode (real cases) | What to prove |
+|---|---|---|
+| **Conversion direction** | Divide-vs-multiply inverted; response keyed to the base currency (USD) when the caller asked for the quote currency; daily vs realtime endpoint confused. | Direction asserted with a **known rate and a known expected result**; the response is keyed to the currency actually requested; the endpoint matches the contract. |
+| **Precision & storage range** | Minor-unit integer column too small for the validated max — validation passes, the INSERT overflows and 500s (INT4 column vs a `1e11` Zod cap). | Storage type holds the max plausible value; the validation cap is **≤** the storage range; a max-size input is tested end-to-end through the write, not just through validation. |
+| **Rounding** | Undefined or inconsistent rounding (half-up vs banker's); rounding applied at the wrong step; tax computed on the wrong base. | Rounding mode and step are explicit and tested at the boundary; tax base/order matches the spec. |
+| **Immutability & state** | An issued invoice/number/ledger entry is mutable; a paid/void transition isn't guarded. | Post-issue mutation is rejected; state transitions go through one authoritative guard; the guard is tested for the illegal transition. |
+
+## 3. Tenancy / org-scope / isolation
+
+| Hazard | Failure mode (real cases) | What to prove |
+|---|---|---|
+| **Cross-org leakage** | A read or write not filtered by tenant/org; lineage or join that crosses orgs (cross-org TaskRun lineage leak). | **Every** query is scoped by tenant by default (scoping is not opt-in); a two-org test asserts org A cannot see/mutate org B's rows. |
+| **Authorization scope drift** | Ad-hoc role-string compares that a centralized detector misses (alias forms like `const role = …; return role === 'admin'`); checks in an app the audit doesn't cover. | Authorization is centralized; no inline role-string equality; the detector/audit covers every app, and a real instance is caught by a test. |
+
+## 4. DB migration / schema
+
+| Hazard | Failure mode (real cases) | What to prove |
+|---|---|---|
+| **Type/range vs validation** | Column type can't hold the value the app validates as legal (see money precision). | Column range ≥ the app's accepted range; asserted with a boundary write. |
+| **Migration scope creep** | A migration bundles unrelated changes or an unintended column/table drop; schema drifts from the intended migration. | One concern per migration; the diff contains **only** the intended change; drift is reconciled, not silently regenerated. |
+| **Backfill / nullability / locks** | Adding a NOT NULL column without a default or backfill; a migration that locks a hot table. | New columns are nullable-or-defaulted with a backfill plan; lock-heavy changes are called out; the migration is reversible or the irreversibility is declared. |
+

package/skills/engineering/better-review/references/passes.md

@@ -0,0 +1,147 @@
+# How to run each pass
+
+The method behind [SKILL.md](../SKILL.md)'s passes. Read the section the run points you to.
+
+## Review the rule, not the instance
+
+Apply these to each P0/P1 candidate, in every pass and every round, and record the result in the
+finding's `rule` and `paths` ([result.md](result.md)). Below a P0/P1, skip them.
+
+1. **A finding is a broken rule; its trigger is one witness.** State the rule in one sentence;
+   the finding closes only when the rule holds on every path, not when the witness is fixed.
+   Example: "a refund never exceeds the captured amount" is the finding; "a second partial
+   refund of 60 on a 100 charge succeeds" is one witness.
+2. **Find the paths in the code, never from memory.** Search the tree for every writer of the
+   state the rule guards, or every caller of the contract the diff adds, changes, or relies on;
+   record each as a `paths` row. A broken path the diff neither causes nor worsens is not a row:
+   it is a P2 follow-up. On a delta, search again only when the fix diff adds or moves a writer.
+   Example: grep every call that changes a balance: the refund route, the batch refund job, and
+   the chargeback webhook are three rows, not the one the trigger used.
+3. **Check every path against one shared list of conditions, including its own failure.** For
+   a path that guards a session, credentials, money, or a deletion, settle it each way
+   (success, refusal, error, timeout) against the same list of events for every path; for other
+   paths, the events that can reach it. An event the program cannot produce is ruled out in one
+   line; one guard that rules out a whole row of events closes every cell in it.
+   Example: an org switch was tried against "offline" and "a second tab", never against "the
+   role lookup times out after the switch", and that cell granted the old org's role.
+4. **One rule, one finding, one id, every round.** A new witness that breaks the same guarded
+   state or contract is an open row under the old id, whatever its wording; widen the `rule`
+   sentence under the same id when it was too narrow. A different guarded state is a new id;
+   an id resolved in an earlier round that breaks again is a new id whose summary names it.
+   Example: a cache-invalidation finding fixed for writes is still open when a bulk import
+   leaves the cache stale: same id, one more open row.
+5. **Name one owner as the fix.** Prefer the place every path passes through: a guard copied to
+   each path misses the next one. Copied guards that close every row still resolve the
+   finding; when no such place exists, say so, and the rows are the fix.
+   Example: three handlers each re-check the tenant; the owner is the repository method all
+   three call.
+6. **A rule that breaks again after a fix means the approach is wrong.** Say so in the
+   finding, name the owner (5), and re-derive every path (2); never review the next patch as if
+   it were the first. Example: the refund cap is open after two fixes, each adding a check to
+   one route: the finding names the balance service as the owner and lists every writer.
+
+## Adversarial techniques
+
+"Be adversarial" means nothing without a method. The one move behind all four: **build the
+specific artifact that would fail, and cite it.** A finding with no concrete trigger is a hunch.
+
+- **Diff each new or changed function against its siblings.** Find its family: the same module,
+  naming pattern, or role (a set of `detect*`, `validate*`, `parse*`, or route handlers). Compare
+  the logic line by line. A function that handles a case differently, uses a looser or tighter
+  pattern, orders its guards differently, or lacks a branch all its siblings have is a defect until
+  the difference is justified. Name the sibling and the exact divergence, for example:
+  "`detectOverMockedEvidence` matches `route.fulfill` but its sibling `detectTier1UiOnlyEvidence`
+  also matches `page.route(`, so the first misses that vector."
+- **Break patterns with boundary inputs.** For each regex, glob, string match, or parser the diff
+  adds or changes, write the input that breaks it before you trust it: prefix or substring leakage
+  (does `/foo` also match `/foobar`? is it anchored?), empty or whitespace, case, escaping and
+  metacharacters, unicode, very long input. Put the failing string in the finding.
+- **Hold each async step open.** For every async step the change relies on (sign-out, revoke,
+  refresh, cancel, save, upload), ask what the code does *while it is pending*, and settle it
+  each way (success, refusal, error, timeout) against every event that can coincide:
+  backgrounded or hidden, offline, a second request, a retry, a sign-in as the same or a
+  different subject, sign-out, expiry ([principle 3](#review-the-rule-not-the-instance) scopes
+  the list). Write the sequence that interleaves them. Rule a cell out only by code that prevents
+  it (a guard, a lock, a state check), never by how you expect the step to be reached: list every
+  caller of the step, including timers, push events, expiry, and error handlers, not just the
+  button a user presses. A test that awaits the step to completion never runs this window, so it
+  proves nothing about it. Example: "export a report to a temp
+  file, put the app in the background, then log out and leave the logout request hanging: the
+  cleanup waits for logout to finish, so the exported file outlives the session."
+- **Name a test for each new branch.** For every conditional, `else`, early return, switch case,
+  and error path in the diff, find the test that drives it. A branch whose failure would be
+  observable and has no test is a gap; line coverage is not branch coverage.
+
+Shapes to look for while doing this:
+
+- **Default-allow.** On an error, unknown input, or unmatched branch, does the code allow instead of
+  deny, or fall back to a permissive default? Feed it the garbage input.
+- **Read before lock.** A value read to compute a write must be read inside the lock that guards
+  that write. Pair each locked write with a second writer of the same row: if the read happens
+  before the lock, the second writer's commit is overwritten.
+- **A control the server refuses.** When the diff newly shows or enables an action for a state
+  (pending, archived, partial), trace that exact control's call path with that state: the page's
+  server action or route, every layer it passes through, and the service at the bottom. Each layer
+  can pin its own expected state, so the service accepting it proves nothing about the action the
+  button calls.
+- **A permanent event routed through a temporary path.** Code that handles "paused, hidden,
+  checking" and "revoked, signed out, deleted" in one branch keeps data or access alive after it
+  should be gone. Check each permanent event arriving during each temporary state, and record it
+  under `windows` (see "Revocation during a pause" in [domain-hazards.md](domain-hazards.md)).
+- **Centralizing drops an edge.** A refactor that moves a cross-cutting concern into one place (an
+  auth redirect into a layout, error handling into a shared hook) silently loses edges the old
+  paths handled. Check that the old edges are pinned by a test that existed before the move.
+
+## Enforcement-point sweep
+
+For a rule that must hold in more than one place: an all-or-none field contract, a canonical
+format for a wire value, a validation rule, an admission or promotion check, or **a behavior the
+diff changes** (a redirect target, a default, a guard). For a changed behavior, the places are
+every existing test, caller, and doc that still relies on the old one: search for the old value
+(the old URL, default, or message), not just the new code.
+
+1. **Write the rule as one sentence**, in the form the code must satisfy.
+2. **Search the whole tree, not just the diff,** for every place that must enforce it: producers,
+   serializers and exporters, validators, request-path guards, admission checks, the schema on the
+   far side of the wire, and the tests that pin each. The diff shows where the author enforced it;
+   the tree shows where it must be enforced.
+3. **Record one row per place:** location, enforced or not, evidence.
+4. **Report every unenforced place this round, as an open `paths` row of the rule's finding.**
+   Never "and similar issues may exist elsewhere": that is a sample dressed up as a sweep, and
+   each place you skip costs the caller another fix-and-review round.
+
+When the code under review *is* the enforcement (a verifier, a gate, a checker), the places are the
+checks inside it and the rule is almost always "fail closed on any drift". For each thing it
+inspects, ask what value makes it pass when it should fail.
+
+A serial test suite stops at its first failure, so a red run shows only the first stale place and
+says nothing about the cases after it. Never read "one failure" as "one place": find the rest by
+searching for the old value, not by rerunning the suite.
+
+## The finding bar
+
+Search hard; then report only what survives this bar.
+
+- **Provable.** Every finding cites the diff hunk, and for a ripple effect the code it provably
+  breaks. Label any inference.
+- **One finding per broken rule.** Say the rule, every open path in `paths`, and the one owner
+  that fixes it. Example: four places miss the generation check: one finding with four open
+  rows, not four findings and not one row.
+- **The author would fix it.** Do not flag intended changes or rely on guesses about intent.
+- **Rigor in proportion.** Hold the code to the bar the surrounding code already holds.
+- **Few and strong.** Order by severity. If the change is safe, say so and report nothing.
+
+Do not raise:
+
+- a sibling divergence that is justified by a genuinely different case;
+- an unanchored pattern whose inputs come from a closed, validated set;
+- an "untested" branch already driven by an integration or E2E test, or whose failure is harmless;
+- a fake of a real external boundary (third-party API, clock, email, randomness);
+- a pre-existing issue the diff neither depends on nor worsens as a blocker (P2 at most);
+- style the surrounding code does not hold either;
+- cleanup, naming, smells, cosmetics, or an architecture opinion with no documented rule behind
+  it: that is P3, and P3 is never reported.
+
+When unsure, lower the severity and say what you could not rule out. Never inflate a candidate that
+trips one of these guards into a blocker: in the caller's loop every P0/P1 buys a full fix, review,
+and CI round.