mixdog 1.4.1 → 1.4.3

package/src/defaults/skills/test-suite/references/case-management.md

@@ -0,0 +1,51 @@
+# Test case management
+
+Every test has an owner, a single contract and a lane. None of this belongs in a hand-written registry: hand lists
+drift from the code. It is derived from where the file lives, its name and its
+text, and `scripts/inventory.mjs` reports it.
+
+## Where a test lives
+
+- Beside the code it exercises, in the same area directory; the inventory's
+  area is the path below the source root, two levels deep.
+- One domain per file (`suite-design.md`).
+- Cross-area contract suites live in their own directory and still run in CI.
+
+## What the inventory reads
+
+| Ecosystem | Test files found by | Skip records |
+|---|---|---|
+| JS/TS (`node:test`, Vitest, Jest) | `*.test.*`, `*.spec.*`, `*-test.mjs`, `__tests__/` | `skip:` option, `it.skip`, `xit`, `skipIf` |
+| Python (pytest, unittest) | `test_*.py`, `*_test.py` | `pytest.mark.skip/skipif/xfail`, `unittest.skip*`, `pytest.skip` |
+| Go | `*_test.go` | `t.Skip`, `t.Skipf`, `t.SkipNow` |
+| Rust | `tests/` directories, files with `#[test]` or `#[cfg(test)]` | `#[ignore]`, `#[ignore = "…"]`, `cfg_attr(…, ignore)` |
+
+Lane comes from a `.slow.`, `.live.`, `.e2e.`, `.integration.` or `.electron.`
+name tag (JS/TS); everything else counts as fast. Vendored, build and cache
+directories are skipped and links are not followed.
+
+Skip kinds: `capability` (the reason names a missing platform, tool or
+privilege; a conditional skip with no reason counts here), `tracked` (`#N`),
+`untracked` (a defect-looking skip with no issue) and `expired` (`until
+YYYY-MM-DD` in the past). Every kind but `capability` is a defect skip that
+needs a fix; an issue number does not make it acceptable.
+
+## Risk markers
+
+| Marker | Meaning | Expected action |
+|---|---|---|
+| `timer` | Sleep, timeout or ticker in a test | Replace with a signal or fake clock unless time is the subject |
+| `spawn` | Real child process | Keep only when the process is the subject; await exit |
+| `port` | Listener on a fixed port | Bind port 0 |
+| `clock` | Real clock read without a fake clock | Inject or fake the clock when the verdict depends on it |
+| `source-text` | Reads source and matches its text | Rewrite at a runnable interface, or justify in the test |
+
+A fake-clock library in the file clears `timer` and `clock`. Markers are
+leads, not verdicts: a timer in a test about timers is correct.
+
+## Audit report
+
+One table per project: area, files, fast/slow counts, marker counts, defect
+skips. Rank batches by: defect skips, fast-lane
+files with `timer`+`spawn`, then the rest by area. The audit ends at the
+report; fix only the batches the user picks.

package/src/defaults/skills/test-suite/references/flaky-policy.md

@@ -0,0 +1,39 @@
+# Flaky-test policy
+
+## Rules
+
+1. **Zero flakes.** A test that passes and fails on the same code is a defect.
+   CI never retries automatically, and a passing rerun clears nothing.
+2. **Fix, never skip.** Fix the cause, or move a correctly slow test to the
+   slow lane. A failure that cannot be fixed now is reported; skipping it is
+   the user's decision, never the agent's.
+3. **Capability skips only.** A skip states the capability the platform or
+   machine lacks (a tool, an OS feature), never a defect.
+4. **Evidence over memory.** Decide from the failing log and CI history, not
+   from "it is always flaky". Keep both the failed and the passing log.
+5. **No local stress.** Reproduction happens through a deterministic trigger
+   in the test, or in CI history; never by loading or looping on the user's
+   machine.
+
+## A flake report
+
+When a flake is handed off, one tracked issue carries: the test and file, the
+failing assertion and log, the platform and load conditions, when it first
+appeared, how often in CI history, and the suspected cause with its evidence.
+One issue per test, so ownership stays clear.
+
+## Priority
+
+Fix in this order:
+
+1. Tests that block a release or a push.
+2. Tests failing most often across recent CI runs.
+3. Tests whose cause can also hit users (product races, localized output).
+4. Everything else, batched by area.
+
+## What does not count as a fix
+
+- Raising a timeout to absorb a sleep, poll or production interval.
+- Adding retries, a rerun-failed CI step, or a serial flag to hide contention.
+- Skipping on a platform that has the capability.
+- Deleting the assertion that failed.

package/src/defaults/skills/test-suite/references/reliability.md

@@ -0,0 +1,49 @@
+# Reliable tests
+
+A test must give the same verdict alone, beside other suites, on a busy
+machine, on a localized OS and in CI. Process isolation does not isolate
+ports, paths, child processes, the clock or the host's language.
+
+## Cause table
+
+| Cause | Signal | Fix |
+|---|---|---|
+| Timing | Passes alone, fails when other work runs; a sleep or a fixed budget decides the verdict | Wait on the event, promise or state the code produces; fake the clock when time is the subject |
+| Shared resource | Fixed port, fixed temp path, shared data dir, a leftover process | Bind port 0 and read the assigned port; a fresh temp dir per test; per-test data dirs |
+| Unrestored global | Later tests change behaviour; order matters | Restore environment variables, working directory, timers, mocks and locale in a `finally`/fixture teardown right after the change |
+| Platform / locale | Fails on another OS, language or console code page | Query structured sources; never parse localized tool text; remember Windows environment names are case-insensitive |
+| Order | Depends on a previous test's state | Each test creates and removes its own prerequisites |
+| Teardown | Next test sees a live child, open handle or locked file | Await child exit, server close and handle release before the test ends |
+
+## Time
+
+- A timeout only bounds a wait on a real signal; it never makes the assertion
+  true. Keep the outer wait far larger than any deadline under test.
+- When the deadline itself is the subject, inject or fake the clock and
+  restore real time in teardown.
+- Do not assert scheduler ordering unless the order is the product contract;
+  place races with deferred promises at a chosen point instead.
+
+## Processes and ports
+
+- Count spawns: a process start costs tens of milliseconds on Windows and much
+  more under load. Spawn once per file when the behaviour allows it.
+- A test that starts a process owns its whole tree: kill it and await exit,
+  detached children included, before the test ends.
+- Prefer an in-process fake over a real server unless the real process is the
+  subject.
+
+## Files and environment
+
+- Use a private temp root per test and remove it afterwards; never write into
+  the user's home configuration or the repository tree.
+- Windows releases handles asynchronously: a rename or delete right after a
+  close may need a bounded retry sized to the observed contention.
+- Point every home, data or cache directory variable the code reads at the
+  test's own root.
+
+## Proof
+
+A reliability fix is proven by a deterministic trigger of the named cause
+(held promise, fake clock, localized fixture, pre-bound port) that fails before
+and passes after, not by repeating the test until it stays green.

package/src/defaults/skills/test-suite/references/suite-design.md

@@ -0,0 +1,78 @@
+# Suite design
+
+How a suite stays small, fast and honest. Apply when writing, placing or
+reviewing tests.
+
+## A good test
+
+- **Names the break.** Before writing, state the production change that should
+  make it fail, and whether that change is a bug or a decision. Cannot name
+  one → redesign around an observable behaviour.
+- **Independent expected value.** A literal or hand-checked fixture, never a
+  value recomputed with the code under test or its helpers.
+- **No change detectors.** If only intentional decisions can fail it (a
+  constant, exact message wording, private structure), test the behaviour that
+  depends on the decision instead.
+- **Your code, not the framework's.** Test the contract at your boundaries;
+  trivial getters and forwarding earn tests only when they validate,
+  normalize, derive or cause side effects.
+- **Through the interface.** Mock only at system boundaries (network, clock,
+  randomness, slow or external stores), never your own modules; pass
+  dependencies in so a boundary is easy to replace.
+- **One behaviour per test**, small enough that a failure points at one cause.
+  Write one test at a time, as needed; never bulk-generate cases.
+
+## One invariant, one owning test
+
+Two tests asserting the same contract drift apart instead of reinforcing each
+other: when the contract changes, one is updated and the other keeps asserting
+a retired behaviour. Name an owner per contract; every other test covers a
+distinct observable boundary. When an overlap appears, reduce both to what is
+distinct, or keep the owner and move the unique cases into it.
+
+## Text matching is a last resort
+
+Asserting against source text pins names, spacing and constants instead of
+behaviour. It breaks on harmless refactors and passes on wrong behaviour, so it
+proves neither direction. Reserve it for artifacts with no runnable surface
+(generated scripts, workflow YAML, prompt text) or for ordering invariants in
+code a test cannot import (a guard must precede a send), and say why in the
+test. Keep the list of such files short and known.
+
+## A contract suite must run in CI
+
+A suite that asserts a contract but runs nowhere automatic is documentation
+with an expiry date: nothing forces it to follow the code, and it fails the
+first time someone runs it. Make it discoverable like every other test and give
+it a CI job. Checks that need a built artifact run after the build step, not
+nowhere. Scripts that are not test files (smoke scripts, harness runners) get a
+scheduled sweep that enumerates them, so new ones join automatically and stale
+exclusions fail closed.
+
+## One domain per file
+
+A multi-domain test file makes every change pay a whole-file search. Split when
+one change forces a search across domains, not on line count alone; shared
+fixtures move into a helper beside the files. One stateful fixture chain over
+one domain stays one file whatever its length.
+
+## Slow work gets its own lane
+
+A test over roughly ten seconds alone goes to a slow lane marked by name,
+directory or tag, whichever the runner selects on. It still runs in CI, in a
+parallel job, so the gate takes the longer of the two instead of their sum.
+Tests that need a built artifact or a live system get a live lane. If a file
+is slow only in a full run because processes contend, the cause is contention,
+not a slow file: Diagnose, do not move it.
+
+## Selection beats retries
+
+During a change run the files that reach the changed code (the project's
+changed-files selection, a path or name filter, a single test id). The full
+lanes gate the push. A suite that takes minutes is a design problem to fix by
+selection and sharding in CI, not by waiting on the user's machine.
+
+## Published artifacts carry no tests
+
+Check that packaging excludes test sources, and that test-only changes do not
+invalidate caches keyed on the shipped files.

package/src/defaults/skills/test-suite/scripts/inventory.mjs

@@ -0,0 +1,335 @@
+#!/usr/bin/env node
+// Read-only inventory of a project's test files across JS/TS, Python, Go and
+// Rust: lane, area, risk markers and skip records. Prints Markdown, or JSON
+// with --json. Never writes files, never follows links, never runs anything.
+import { closeSync, openSync, readSync, readdirSync, statSync } from 'node:fs';
+import { join, relative, sep } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+const SKIP_DIRS = new Set([
+  'node_modules',
+  '.git',
+  '.hg',
+  '.svn',
+  'dist',
+  'out',
+  'build',
+  'target',
+  'vendor',
+  'third_party',
+  'venv',
+  '.venv',
+  'site-packages',
+  '__pycache__',
+  '.tox',
+  '.nox',
+  '.mypy_cache',
+  '.pytest_cache',
+  '.ruff_cache',
+  '.next',
+  '.nuxt',
+  '.turbo',
+  '.cache',
+  '.runtime',
+  'coverage',
+  '.gradle',
+]);
+const MAX_FILES = 20_000;
+const MAX_DIRS = 50_000;
+const MAX_DEPTH = 40;
+const MAX_BYTES = 1 << 20;
+const LIST_LIMIT = 200;
+
+const JS_EXT = '(?:m?[jt]s|c[jt]s|[jt]sx)';
+const JS_TEST = new RegExp(`(?:\\.(?:test|spec)\\.${JS_EXT}|-test\\.m?js)$`);
+const JS_FILE = new RegExp(`\\.${JS_EXT}$`);
+const TYPES_FILE = /\.d\.[cm]?ts$/;
+const RUST_TEST = /#\[\s*(?:cfg\(\s*test\s*\)|test|tokio::test|rstest)\b/;
+
+// `skip: cond && 'reason'` keeps the reason after the last `&&`.
+const JS_SKIP_REASON = /\bskip\s*(?::|\()\s*(?:[^\n]*?&&\s*)?(['"`])((?:(?!\1).)*)\1/g;
+const JS_SKIP_BARE = /\b(?:(?:it|test|describe)\.skip|x(?:it|test|describe))\b|\.skip\s*\(\s*\)|\bskip\s*:\s*true\b/;
+const JS_SKIP_IF = /\.skipIf\s*\(/;
+const PY_SKIP =
+  /\b(?:pytest\.mark\.(skipif|skip|xfail)|unittest\.(skipIf|skipUnless|skip|expectedFailure)|pytest\.(importorskip|skip))\b/;
+const PY_CONDITIONAL = new Set(['skipif', 'skipIf', 'skipUnless', 'importorskip']);
+const GO_SKIP = /\.Skip(?:f|Now)?\s*\(/;
+const RUST_IGNORE = /#\[\s*ignore\s*(?:=\s*(['"])((?:(?!\1).)*)\1)?\s*(?:\(.*?\))?\s*\]/;
+const RUST_CFG_IGNORE = /#\[\s*cfg_attr\([^\]]*\bignore\b/;
+
+const LANGS = {
+  js: {
+    comment: '//',
+    fake: /mock\.timers\.enable|useFakeTimers|installFakeClock|vi\.setSystemTime|jest\.setSystemTime/,
+    markers: {
+      timer: /\b(setTimeout|setInterval|sleep|delay)\s*\(/,
+      spawn: /\b(spawn|spawnSync|execFile|execFileSync|execSync|fork)\s*\(/,
+      port: /\.listen\(\s*[1-9]\d{2,4}\b/,
+      clock: /Date\.now\(\)|new Date\(\s*\)/,
+      'source-text': /readFile(Sync)?\([^)]*\.(m?js|tsx?|jsx)['"`]/,
+    },
+  },
+  python: {
+    comment: '#',
+    fake: /freezegun|freeze_time|time_machine|time-machine|monkeypatch\.setattr\([^)]*time|mock\.patch\([^)]*time/,
+    markers: {
+      timer: /\b(?:time|asyncio)\.sleep\(|\bsleep\(/,
+      spawn:
+        /\bsubprocess\.(?:run|Popen|call|check_output|check_call)\(|\bos\.(?:system|popen)\(|\bmultiprocessing\.Process\(/,
+      port: /\.bind\(\s*\([^)]*,\s*[1-9]\d{2,4}\s*\)|\bport\s*=\s*[1-9]\d{3,4}\b/,
+      clock: /\bdatetime\.(?:now|utcnow)\(|\bdate\.today\(|\btime\.time\(\)/,
+      'source-text': /inspect\.getsource\(|(?:open|Path)\(\s*['"][^'"]*\.(?:py|js|ts)['"]/,
+    },
+  },
+  go: {
+    comment: '//',
+    fake: /clockwork|benbjohnson\/clock|synctest/,
+    markers: {
+      timer: /\btime\.(?:Sleep|After|NewTimer|NewTicker|Tick)\(/,
+      spawn: /\bexec\.Command(?:Context)?\(/,
+      port: /(?:net\.Listen|ListenAndServe)\(\s*(?:"tcp[46]?"\s*,\s*)?"[^"]*:[1-9]\d{2,4}"/,
+      clock: /\btime\.Now\(\)/,
+      'source-text': /os\.ReadFile\(\s*"[^"]*\.go"|parser\.ParseFile\(/,
+    },
+  },
+  rust: {
+    comment: '//',
+    fake: /tokio::time::pause|start_paused/,
+    markers: {
+      timer: /\bsleep\(/,
+      spawn: /\b(?:std::)?process::Command\b|\bCommand::new\(/,
+      port: /\bbind\(\s*"[^"]*:[1-9]\d{2,4}"/,
+      clock: /\b(?:SystemTime|Instant|Utc|Local)::now\(\)/,
+      'source-text': /include_str!\([^)]*\.rs"|read_to_string\([^)]*\.rs"/,
+    },
+  },
+};
+
+// A reason naming a missing capability of the host (platform, privilege,
+// tool, build) is a capability skip; anything else reads as a defect skip.
+const CAPABILITY =
+  /\bonly\b|unavailable|unsupported|not (available|permitted|enforced|built|supported|configured|granted|installed)|requires?\b|needs?\b|missing|denied|refused|does not (support|grant|allow)|insensitive|not found|has no|not run on|\bno local\b|\bno display\b|\bposix\b|\bno [\w ]+ (available|configured|is configured|installed)|\bnot on (the )?path\b|\bno [\w-]+ on this (host|machine|platform|runner)|\(\s*(?:e\.g\.|i\.e\.),?\s*running as (?:root|administrator|an? \w+ user)\s*\)|\bskip(?:ped)? (?:when|if|as|under) running as (?:root|administrator|an? \w+ user)\b|\b(?:is|are) an? (?:windows|posix|linux|macos|unix)[- ](?:behaviou?r|feature|semantics)\b/i;
+const TRACKED = /#\d+/;
+const UNTIL = /until (\d{4}-\d{2}-\d{2})/;
+
+export function laneOf(file) {
+  const tag = /\.(slow|live|electron|e2e|integration)\.(?:test|spec)\./.exec(file);
+  return tag ? tag[1] : 'fast';
+}
+
+export function areaOf(rel) {
+  const dirs = rel.split(sep).join('/').split('/').slice(0, -1);
+  if (dirs[0] === 'src') dirs.shift();
+  return dirs.slice(0, 2).join('/') || '.';
+}
+
+// Returns 'js' | 'python' | 'go' | 'rust' | 'rust?' (a .rs file whose text decides) | null.
+function langOf(rel, name) {
+  if (JS_FILE.test(name) && !TYPES_FILE.test(name) && (JS_TEST.test(name) || `/${rel}`.includes('/__tests__/')))
+    return 'js';
+  if (/^test_.+\.py$|_test\.py$/.test(name)) return 'python';
+  if (name.endsWith('_test.go')) return 'go';
+  if (name.endsWith('.rs')) return `/${rel}`.includes('/tests/') ? 'rust' : 'rust?';
+  return null;
+}
+
+// Links are never followed: a dangling or looping link cannot break the walk.
+function walk(root) {
+  const found = [];
+  let dirs = 0;
+  const visit = (dir, depth) => {
+    if (depth > MAX_DEPTH)
+      throw new Error(`directories nested deeper than ${MAX_DEPTH} under ${root}; narrow the root`);
+    if (++dirs > MAX_DIRS) throw new Error(`more than ${MAX_DIRS} directories under ${root}; narrow the root`);
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      const full = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (!SKIP_DIRS.has(entry.name)) visit(full, depth + 1);
+      } else if (entry.isFile()) {
+        const rel = relative(root, full).split(sep).join('/');
+        const lang = langOf(rel, entry.name);
+        if (!lang) continue;
+        found.push({ full, rel, lang });
+        if (found.length > MAX_FILES)
+          throw new Error(`more than ${MAX_FILES} test files under ${root}; narrow the root`);
+      }
+    }
+  };
+  visit(root, 0);
+  return found;
+}
+
+function readHead(path) {
+  const fd = openSync(path, 'r');
+  try {
+    const buffer = Buffer.alloc(Math.min(statSync(path).size, MAX_BYTES));
+    const length = readSync(fd, buffer, 0, buffer.length, 0);
+    return buffer.toString('utf8', 0, length);
+  } finally {
+    closeSync(fd);
+  }
+}
+
+// The call's text from `from` to its closing parenthesis, across up to 6 lines.
+function callText(lines, index, from) {
+  let text = lines[index].slice(from);
+  for (let next = index + 1; next < Math.min(lines.length, index + 6); next += 1) {
+    const open = (text.match(/\(/g) || []).length;
+    if (open > 0 && (text.match(/\)/g) || []).length >= open) break;
+    text += ` ${lines[next].trim()}`;
+  }
+  return text;
+}
+
+function skipSites(lines, lang) {
+  const sites = [];
+  lines.forEach((line, index) => {
+    const add = (reason, conditional) => sites.push({ index, reason, conditional });
+    if (lang === 'js') {
+      const reasons = [...line.matchAll(JS_SKIP_REASON)];
+      for (const match of reasons) add(match[2], false);
+      if (!reasons.length) {
+        if (JS_SKIP_IF.test(line)) add('', true);
+        else if (JS_SKIP_BARE.test(line)) add('', false);
+      }
+    } else if (lang === 'python') {
+      const match = PY_SKIP.exec(line);
+      if (!match || /^\s*#/.test(line)) return;
+      const conditional = PY_CONDITIONAL.has(match[1] || match[2] || match[3]);
+      const call = callText(lines, index, match.index);
+      const keyword = /\breason\s*=\s*(['"])((?:(?!\1).)*)\1/.exec(call);
+      const positional = conditional
+        ? /,\s*(['"])((?:(?!\1).)*)\1\s*\)?\s*$/.exec(call)
+        : /\(\s*(['"])((?:(?!\1).)*)\1/.exec(call);
+      add((keyword || positional)?.[2] || '', conditional);
+    } else if (lang === 'go') {
+      const match = GO_SKIP.exec(line);
+      if (match && !/^\s*\/\//.test(line))
+        add(/(['"`])((?:(?!\1).)*)\1/.exec(line.slice(match.index))?.[2] || '', false);
+    } else {
+      const match = RUST_IGNORE.exec(line);
+      if (match) add(match[2] || '', false);
+      else if (RUST_CFG_IGNORE.test(line)) add('', true);
+    }
+  });
+  return sites;
+}
+
+function commentOf(line, token) {
+  const at = line.indexOf(token);
+  return at < 0 ? '' : line.slice(at + token.length).trim();
+}
+
+function classify(reason, today, conditional) {
+  const until = UNTIL.exec(reason)?.[1] || '';
+  if (until && until < today) return 'expired';
+  if (TRACKED.test(reason)) return 'tracked';
+  if (!reason.trim()) return conditional ? 'capability' : 'untracked';
+  return CAPABILITY.test(reason) ? 'capability' : 'untracked';
+}
+
+export function scanText(text, today, lang = 'js') {
+  const spec = LANGS[lang];
+  const fakeClock = spec.fake.test(text);
+  const markers = Object.entries(spec.markers)
+    .filter(([name, pattern]) => pattern.test(text) && !(fakeClock && (name === 'timer' || name === 'clock')))
+    .map(([name]) => name);
+  const lines = text.split(/\r?\n/);
+  const skips = skipSites(lines, lang).map(({ index, reason, conditional }) => {
+    const before =
+      index > 0 && lines[index - 1].trim().startsWith(spec.comment) ? commentOf(lines[index - 1], spec.comment) : '';
+    const note = [commentOf(lines[index], spec.comment), before].filter(Boolean).join(' ');
+    const full = [reason, note].filter(Boolean).join(' ');
+    return { line: index + 1, reason: reason || note, kind: classify(full, today, conditional) };
+  });
+  return { markers, skips };
+}
+
+export function inventory(root, { today = new Date().toISOString().slice(0, 10) } = {}) {
+  if (!statSync(root, { throwIfNoEntry: false })?.isDirectory()) throw new Error(`not a directory: ${root}`);
+  const files = [];
+  for (const { full, rel, lang } of walk(root)) {
+    const text = readHead(full);
+    if (lang === 'rust?' && !RUST_TEST.test(text)) continue;
+    const language = lang === 'rust?' ? 'rust' : lang;
+    files.push({ file: rel, lang: language, lane: laneOf(rel), area: areaOf(rel), ...scanText(text, today, language) });
+  }
+  const areas = new Map();
+  for (const entry of files) {
+    const row = areas.get(entry.area) || {
+      area: entry.area,
+      files: 0,
+      fast: 0,
+      slow: 0,
+      other: 0,
+      langs: {},
+      markers: {},
+      skips: {},
+    };
+    row.files += 1;
+    if (entry.lane === 'fast') row.fast += 1;
+    else if (entry.lane === 'slow') row.slow += 1;
+    else row.other += 1;
+    row.langs[entry.lang] = (row.langs[entry.lang] || 0) + 1;
+    for (const marker of entry.markers) row.markers[marker] = (row.markers[marker] || 0) + 1;
+    for (const skip of entry.skips) row.skips[skip.kind] = (row.skips[skip.kind] || 0) + 1;
+    areas.set(entry.area, row);
+  }
+  const attention = files.flatMap((entry) =>
+    entry.skips.filter((skip) => skip.kind !== 'capability').map((skip) => ({ file: entry.file, ...skip }))
+  );
+  const fastRisk = files.filter(
+    (entry) => entry.lane === 'fast' && entry.markers.includes('timer') && entry.markers.includes('spawn')
+  );
+  return {
+    root,
+    today,
+    files: files.length,
+    areas: [...areas.values()].sort((a, b) => b.files - a.files || a.area.localeCompare(b.area)),
+    attentionTotal: attention.length,
+    attention: attention.slice(0, LIST_LIMIT),
+    fastRiskTotal: fastRisk.length,
+    fastRisk: fastRisk.slice(0, LIST_LIMIT).map((entry) => entry.file),
+  };
+}
+
+function markdown(report) {
+  const cell = (counts) =>
+    Object.entries(counts)
+      .map(([key, count]) => `${key} ${count}`)
+      .join(', ') || '-';
+  const more = (total, shown) => (total > shown ? [`- … ${total - shown} more (use --json)`] : []);
+  const out = [`# Test inventory: ${report.root}`, '', `${report.files} test files, ${report.today}.`, ''];
+  out.push('| Area | Files | Fast | Slow | Other | Languages | Markers | Skips |', '|---|---|---|---|---|---|---|---|');
+  for (const row of report.areas) {
+    out.push(
+      `| ${row.area} | ${row.files} | ${row.fast} | ${row.slow} | ${row.other} | ${cell(row.langs)} | ${cell(row.markers)} | ${cell(row.skips)} |`
+    );
+  }
+  out.push('', `## Skips needing action (${report.attentionTotal})`, '');
+  for (const item of report.attention)
+    out.push(`- ${item.kind}: \`${item.file}:${item.line}\` — ${item.reason || '(no reason)'}`);
+  out.push(...more(report.attentionTotal, report.attention.length));
+  out.push('', `## Fast-lane files with timers and real processes (${report.fastRiskTotal})`, '');
+  for (const file of report.fastRisk) out.push(`- \`${file}\``);
+  out.push(...more(report.fastRiskTotal, report.fastRisk.length));
+  return out.join('\n');
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1] || '').href) {
+  const args = process.argv.slice(2);
+  const json = args.includes('--json');
+  const unknown = args.find((arg) => arg.startsWith('--') && arg !== '--json');
+  const root = args.find((arg) => !arg.startsWith('--'));
+  if (!root || unknown) {
+    console.error(`${unknown ? `unknown option ${unknown}; ` : ''}usage: inventory.mjs <project-root> [--json]`);
+    process.exit(2);
+  }
+  try {
+    const report = inventory(root);
+    console.log(json ? JSON.stringify(report, null, 2) : markdown(report));
+  } catch (error) {
+    console.error(`inventory: ${error.message}`);
+    process.exit(1);
+  }
+}

package/src/defaults/skills/visualize/SKILL.md

@@ -115,6 +115,10 @@ or radius are one option.
 - Open a result once, when it is ready to look at, not at every intermediate
   write. Long multi-step work shows the first reviewable state, then lets
   reloads carry the rest.
+- `open` shows the user a deliverable. To check your own work (`check`,
+  `inspect`, `capture`, `export`, before/after screenshots), `open` with
+  `verify: true`: the tab stays off the user's panel and chat and closes when
+  the turn ends. Opening the same target without it shows it.
 - Decks and documents: the panel shows the converted pages; still run the
   owning skill's own render review — the panel is for the user, not your QC.
 - Close tabs that no longer match the conversation (a resolved choice, a
@@ -129,8 +133,8 @@ or radius are one option.
 
 ### Inline content or a file
 - **Inline** (`open` with `input.content` — `mermaid`, `svg`, `chart` (an
-  ECharts option as JSON), `html`, `markdown`): diagrams, charts, quick
-  sketches and notes you will not edit again. No file is written. `mermaid`,
+  ECharts option as JSON), `html`, `markdown`): diagrams, charts and quick
+  sketches you will not edit again; never a report of your own work. No file is written. `mermaid`,
   `svg` and `markdown` are static, sanitized output (no scripts). `chart` is
   interactive (tooltips, zoom) and `html` runs its scripts, as in-memory pages
   held to the same rules as an HTML file: outside network is blocked, so an

package/src/lib/instruction-text.cjs

@@ -0,0 +1,36 @@
+// The one usability check for an editable instruction file (an orchestration
+// mode, an output style): the editor's state, the prompt builders and the save
+// path all decide with it, so the settings page never shows text the prompt
+// does not use. Required by the CJS rules builder and imported by the ESM runtime.
+'use strict';
+
+/** Largest instruction file read or written (the agent editor's 256 KB text limit). */
+const INSTRUCTION_FILE_MAX_BYTES = 256 * 1024;
+
+const utf8 = new TextDecoder('utf-8', { fatal: true });
+
+/** Nothing but NUL bytes and whitespace — what a crash leaves of a file. */
+function holdsNoData(buffer) {
+  for (const byte of buffer) {
+    if (byte !== 0 && byte !== 0x20 && byte !== 0x09 && byte !== 0x0a && byte !== 0x0d) return false;
+  }
+  return true;
+}
+
+/**
+ * The file's bytes → `{ text }` (decoded, BOM dropped, otherwise as written)
+ * or `{ problem }`: 'too-large', 'empty' (no data), 'not-text' (NUL bytes or
+ * invalid UTF-8).
+ */
+function decodeInstructionFile(buffer) {
+  if (buffer.length > INSTRUCTION_FILE_MAX_BYTES) return { problem: 'too-large' };
+  if (holdsNoData(buffer)) return { problem: 'empty' };
+  if (buffer.includes(0)) return { problem: 'not-text' };
+  try {
+    return { text: utf8.decode(buffer).replace(/^\uFEFF/, '') };
+  } catch {
+    return { problem: 'not-text' };
+  }
+}
+
+module.exports = { INSTRUCTION_FILE_MAX_BYTES, decodeInstructionFile };