tewip-ai 0.36.0 → 0.37.0

package/README.md

@@ -138,17 +138,19 @@ and you always get the current version.
 
 ### The editor extension (VS Code, Cursor, Windsurf, VSCodium)
 
-Download **[tewip-0.5.0.vsix](https://github.com/hmamut39/tewip/releases/tag/vscode-0.5.0)**, then in the
-editor press `Ctrl+Shift+P` and run **Extensions: Install from VSIX…**. It needs the command line:
-`npm install -g tewip-ai`.
+**Open the Extensions pane and search for "Tewip".** It is in both registries, so that works in
+VS Code, Cursor, Windsurf, VSCodium, Gitpod and Eclipse Theia:
 
-Press `Ctrl+Shift+P` and type "Tewip" for: *Explain a test report…*, *Why did CI fail on this
-branch?*, *Risk review of this change*, *Which flaky tests to quarantine*, *Check secrets and
-dependencies*, and *What our corrections add up to*. The editor's AI assistant also picks Tewip up
-as an MCP server with nothing to configure.
+- **VS Code** — [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=hmamut39.tewip)
+- **Cursor, Windsurf, VSCodium, Gitpod, Theia** — [Open VSX](https://open-vsx.org/extension/hmamut39/tewip)
 
-It is not in the Visual Studio Marketplace: publishing there now requires an Azure subscription,
-which means a credit card for a free extension. The file above installs exactly the same thing.
+Or install the `.vsix` attached to any [release](https://github.com/hmamut39/tewip/releases) with
+**Extensions: Install from VSIX…**. Either way it needs the command line: `npm install -g tewip-ai`.
+
+Press `Ctrl+Shift+P` and type "Tewip" for: *Is this work done?*, *Can everybody use this?*, *Could
+these tests ever fail?*, *Would the tests catch a bug in this file?*, *Which tests could notice this
+change?*, *What will this migration do to a live database?*, *Why did CI fail on this branch?*, and
+more. The editor's AI assistant also picks Tewip up as an MCP server with nothing to configure.
 
 ### 2. From any AI assistant, through MCP (the whole IT team)
 
@@ -574,6 +576,58 @@ With `--json` the verdict is **sealed**: editing `not-ready` to `ready` in the f
 fail, so a verdict that travels into a ticket or a release note can be checked rather than trusted. It is
 also an MCP tool, so an agent can ask whether its own work is done before saying that it is.
 
+## Is this change slower? (Phase 30, new)
+
+```bash
+tewip perf summary.json --record            # on main: add this run to the baseline
+tewip perf summary.json --strict            # on a branch: fail the build on a real regression
+```
+
+Tewip has imported k6 results for a while and never had an opinion about them. Now it answers the
+question every team asks before a release.
+
+**The hard part is not the arithmetic.** "p95 went from 180ms to 210ms, +16%" is four lines of code
+and worthless, because nobody knows whether 16% is the change or the laptop. Here are **four real k6
+runs of code that did not change**:
+
+```
+run 1   p95 = 60.9ms
+run 2   p95 = 60.8ms
+run 3   p95 = 62.8ms
+run 4   p95 = 61.4ms
+```
+
+A 3% spread from nothing at all. A tool that calls that a regression gets switched off.
+
+So Tewip answers **two questions separately**, because they fail separately:
+
+| | |
+|---|---|
+| **Did your own thresholds hold?** | You already wrote what "fast enough" means in your k6 script. Tewip reads the result instead of asking you to write a budget twice. |
+| **Is it slower than it was?** | Answered **only** from three or more recorded baselines. Below that: *cannot say*. |
+
+Given those three real baselines, a fourth identical run at 61.4ms is **not** called a regression —
+and a genuine one is:
+
+```
+- `http_req_duration` p95 282.5ms — **slower**
+  - baseline 60.8ms–62.8ms over 3 runs, middle 60.9ms
+  - 282.5ms is outside everything 3 baseline runs produced (60.8-62.8ms) by more than
+    their own spread, so the runs cannot explain it. That is +364% on the middle run.
+```
+
+**Recording is deliberately not automatic.** A tool that files every run into the baseline ratchets:
+today's regression becomes tomorrow's normal, the comparison keeps saying "within range", and a
+service triples in latency over a quarter without one report ever being wrong. `--record` on main,
+compare everywhere else.
+
+**It never predicts a duration, a capacity, or what a user will feel.** It cannot see your production
+hardware, your real data volume or your real traffic, and every report says so.
+
+One more thing it refuses: if your summary came from `--new-machine-readable-summary`, that export
+records **no threshold results at all** — the word appears in it only inside a copy of your script.
+Tewip says "this export cannot tell me" rather than "nothing was breached".
+
 ## Can everybody use it? (Phase 28, new)
 
 ```bash

package/dist/cli/help.js

@@ -118,6 +118,16 @@ Usage:
                                     is what was asked for covered. Answers ready, not ready, or cannot
                                     say - and cannot say is never rounded up to ready. --json writes a
                                     sealed verdict that can be checked later. No model, no cost.
+  tewip perf <k6-summary.json> [--record] [--label checkout] [--strict] [--out perf.md]
+                                    Is this change slower, and does it matter? Reads a k6 run and
+                                    answers two questions separately: did the thresholds you wrote
+                                    hold, and is this slower than it was. The second is answered only
+                                    from repeated baselines - with fewer than three it says cannot
+                                    say, because one run against one run cannot tell a regression
+                                    from a busy machine. --record adds a run to the baseline, and is
+                                    deliberately not automatic: a regression recorded by accident
+                                    becomes next week's normal. It never predicts a duration or a
+                                    capacity. No model, no cost.
   tewip access [<file or directory>] [--report axe.json] [--strict] [--out access.md]
                                     Can everybody use this? Reads your markup and names the barriers
                                     that reading alone can prove - a picture with no alt text, a field

package/dist/cli/verbs-prove.js

@@ -20,6 +20,24 @@ export async function proveVerb(verb, args) {
             });
             return true;
         }
+        case 'perf': {
+            const { runPerf } = await import('../engine/perf/perf-command.js');
+            const paths = args.filter((a, i) => !a.startsWith('--') && !['--out', '--label'].includes(args[i - 1] ?? ''));
+            if (paths.length === 0) {
+                console.error('tewip perf needs the JSON from a k6 run: tewip perf summary.json [--record] [--label checkout]');
+                process.exitCode = 1;
+                return true;
+            }
+            runPerf({
+                root: process.cwd(),
+                summary: paths[0],
+                label: flag(args, 'label'),
+                record: args.includes('--record'),
+                out: flag(args, 'out'),
+                gate: args.includes('--strict'),
+            });
+            return true;
+        }
         case 'access': {
             const { runAccess } = await import('../engine/access/access-command.js');
             const paths = args.filter((a, i) => !a.startsWith('--') && args[i - 1] !== '--out' && args[i - 1] !== '--report');

package/dist/engine/perf/compare.js

@@ -0,0 +1,97 @@
+// Phase 30: deciding whether a run is actually slower.
+//
+// This is the whole phase. Reporting "p95 went from 180ms to 210ms, +16%" is trivial and worthless:
+// nobody knows whether 16% is the change or the laptop. Performance numbers move between identical
+// runs - a background process, a warm cache, a noisy CI runner - and a tool that calls every
+// movement a regression gets muted within a week, which is the same failure mode as the
+// accessibility scanners in Phase 28.
+//
+// So Tewip refuses unless it can tell the difference, and it can only tell the difference from
+// **repeated baseline runs**. One run against one run says nothing, however large the gap looks,
+// and Tewip says that rather than guessing. With three or more baselines there is an observed
+// spread to compare against, and a change outside the baseline's own range by more than the width
+// of that range is a change the runs themselves cannot explain.
+//
+// A k6 summary carries no raw samples - only avg, min, med, p90, p95, max - so a proper confidence
+// interval is not available, and nothing here pretends otherwise. The test is deliberately crude
+// and deliberately conservative: it is better to say "cannot say" to a real 4% regression than to
+// cry wolf at noise, because the second one costs the team the tool.
+import { MAIN_TIMING } from './k6.js';
+/** The fewest baseline runs from which run-to-run noise can be estimated at all. */
+export const ENOUGH_BASELINES = 3;
+/**
+ * A change smaller than this is not called even when the baselines are unusually tight, because a
+ * handful of identical runs can make the observed spread implausibly small and a 1% move is not
+ * worth a person's afternoon.
+ */
+const SMALLEST_CHANGE = 0.05;
+const median = (values) => {
+    const sorted = [...values].sort((a, b) => a - b);
+    const mid = Math.floor(sorted.length / 2);
+    return sorted.length % 2 === 0 ? (sorted[mid - 1] + sorted[mid]) / 2 : sorted[mid];
+};
+const round = (n) => Math.round(n * 10) / 10;
+/**
+ * Compares one metric of a candidate run against the same metric in the baseline runs.
+ *
+ * `baseline` is every stored value for the metric, oldest first. It is not averaged into a single
+ * number, because its spread is the only evidence available about what noise looks like here.
+ */
+export function compareMetric(metric, now, baseline) {
+    const runs = baseline.length;
+    const before = runs > 0 ? median(baseline) : 0;
+    const low = runs > 0 ? Math.min(...baseline) : 0;
+    const high = runs > 0 ? Math.max(...baseline) : 0;
+    const spread = high - low;
+    const margin = Math.max(spread, before * SMALLEST_CHANGE);
+    const base = {
+        metric,
+        now: round(now),
+        before: round(before),
+        baselineRuns: runs,
+        baselineLow: round(low),
+        baselineHigh: round(high),
+        margin: round(margin),
+    };
+    if (runs < ENOUGH_BASELINES) {
+        return {
+            ...base,
+            direction: 'cannot-say',
+            why: runs === 0
+                ? 'there is nothing to compare this against yet'
+                : `${runs} baseline ${runs === 1 ? 'run is' : 'runs are'} not enough to know what noise looks like here; ` +
+                    `Tewip needs ${ENOUGH_BASELINES}. Two runs can differ by this much for reasons that have nothing to do with the code.`,
+        };
+    }
+    const percent = before > 0 ? Math.round(((now - before) / before) * 100) : 0;
+    if (now > high + margin) {
+        return {
+            ...base,
+            direction: 'slower',
+            why: `${round(now)}ms is outside everything ${runs} baseline runs produced (${round(low)}-${round(high)}ms) ` +
+                `by more than their own spread, so the runs cannot explain it. That is ${percent > 0 ? '+' : ''}${percent}% on the middle run.`,
+        };
+    }
+    if (now < low - margin) {
+        return {
+            ...base,
+            direction: 'faster',
+            why: `${round(now)}ms is below everything ${runs} baseline runs produced (${round(low)}-${round(high)}ms) by more than their own spread.`,
+        };
+    }
+    return {
+        ...base,
+        direction: 'cannot-say',
+        why: `${round(now)}ms is within what ${runs} baseline runs already did on their own (${round(low)}-${round(high)}ms, ` +
+            `allowing ${round(margin)}ms either side). A difference the baseline runs produce by themselves is not evidence about this change.`,
+    };
+}
+/** Enough requests for a percentile to mean anything. Below this, p95 is three data points. */
+export const ENOUGH_REQUESTS = 100;
+/** Timings worth comparing, in the order a person would want them. */
+export function timingsToCompare(run) {
+    const named = Object.keys(run.timings).filter((m) => !m.includes('{'));
+    const first = named.filter((m) => m === MAIN_TIMING);
+    const rest = named.filter((m) => m !== MAIN_TIMING && /duration|waiting|blocked/.test(m)).sort();
+    return [...first, ...rest];
+}

package/dist/engine/perf/history.js

@@ -0,0 +1,74 @@
+// Phase 30: the stored baseline.
+//
+// Recording is deliberately **not** automatic, and that is the most important decision in this
+// file. A tool that files every run it sees into the baseline ratchets: today's regression becomes
+// tomorrow's normal, the comparison keeps saying "within range", and a service gets three times
+// slower over a quarter without one report ever being wrong. Tewip records only when asked, so the
+// intended use is `--record` on the main branch and a plain comparison everywhere else.
+//
+// The file is JSON Lines so that a run can be appended without reading or rewriting what is already
+// there, and so a person can read it or delete a bad line with an editor.
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+const file = (root) => join(root, '.tewip', 'perf', 'runs.jsonl');
+/** Everything recorded for this label, oldest first. */
+export function storedRuns(root, label) {
+    const path = file(root);
+    if (!existsSync(path))
+        return [];
+    const out = [];
+    for (const line of readFileSync(path, 'utf8').split('\n')) {
+        const trimmed = line.trim();
+        if (trimmed === '')
+            continue;
+        try {
+            const parsed = JSON.parse(trimmed);
+            // A line Tewip cannot read is skipped rather than throwing: one bad line written by a crashed
+            // run must not make the whole baseline unreadable.
+            if (parsed && typeof parsed.at === 'string' && parsed.label === label && parsed.timings)
+                out.push(parsed);
+        }
+        catch {
+            continue;
+        }
+    }
+    return out;
+}
+export function recordRun(root, label, run, requests, gitSha) {
+    const stored = {
+        at: run.at,
+        label,
+        ...(gitSha ? { gitSha } : {}),
+        timings: Object.fromEntries(Object.entries(run.timings).map(([m, v]) => [m, { p95: v.p95, med: v.med, avg: v.avg }])),
+        requests,
+    };
+    const path = file(root);
+    mkdirSync(dirname(path), { recursive: true });
+    appendFileSync(path, `${JSON.stringify(stored)}\n`, 'utf8');
+    return stored;
+}
+/** Every stored p95 for one metric, oldest first, for the comparison to read the spread from. */
+export function baselineFor(runs, metric) {
+    return runs.map((r) => r.timings[metric]?.p95).filter((v) => typeof v === 'number' && Number.isFinite(v));
+}
+/** The labels this project has recorded, so a typo in --label does not look like an empty history. */
+export function knownLabels(root) {
+    const path = file(root);
+    if (!existsSync(path))
+        return [];
+    const labels = new Set();
+    for (const line of readFileSync(path, 'utf8').split('\n')) {
+        const trimmed = line.trim();
+        if (trimmed === '')
+            continue;
+        try {
+            const parsed = JSON.parse(trimmed);
+            if (typeof parsed?.label === 'string')
+                labels.add(parsed.label);
+        }
+        catch {
+            continue;
+        }
+    }
+    return [...labels].sort();
+}

package/dist/engine/perf/k6.js

@@ -0,0 +1,111 @@
+// Phase 30: reading a k6 run.
+//
+// k6 writes two different summary shapes and Tewip reads both, because which one a team has depends
+// on a flag they probably did not choose deliberately:
+//
+//   --summary-export                     the classic shape: metrics as a map, percentiles keyed
+//                                        "p(95)", and - the part that matters - the result of every
+//                                        threshold the team wrote.
+//   --new-machine-readable-summary       metrics as an array, percentiles keyed p95, and **no
+//                                        threshold results at all**.
+//
+// Both facts below were established by running k6 v2.3.0 against a real server rather than read
+// from documentation, and both would have been got wrong from memory:
+//
+//  1. In the classic shape a threshold entry is `{"p(95)<120": true}` where **true means breached**.
+//     It reads like "the condition holds". It means the opposite. A run whose p95 was 282ms against
+//     a 120ms threshold is the one that produced `true`.
+//  2. The machine-readable shape drops thresholds entirely. The word appears in the file only inside
+//     `config.script`, which is the source text of the test. So a team on that flag has no pass or
+//     fail recorded anywhere in their export, and Tewip has to say so rather than report "no
+//     threshold was breached", which would be a lie of omission.
+import { readFileSync } from 'node:fs';
+const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : 0);
+function measurement(metric, values) {
+    return {
+        metric,
+        avg: num(values.avg),
+        min: num(values.min),
+        med: num(values.med),
+        // The two shapes disagree on how a percentile is spelled.
+        p90: num(values['p(90)'] ?? values.p90),
+        p95: num(values['p(95)'] ?? values.p95),
+        max: num(values.max),
+    };
+}
+/** A trend metric is one with a median: a timing, rather than a counter or a rate. */
+const isTrend = (v) => 'med' in v || 'p(95)' in v || 'p95' in v;
+function classic(parsed, at) {
+    const metrics = (parsed.metrics ?? {});
+    const run = { tool: 'k6', format: 'classic', at, timings: {}, rates: {}, counts: {}, thresholds: [] };
+    for (const [name, values] of Object.entries(metrics)) {
+        if (typeof values !== 'object' || values === null)
+            continue;
+        for (const [expression, breached] of Object.entries((values.thresholds ?? {}))) {
+            // `true` is a breach. See the note at the top: this is the opposite of how it reads.
+            run.thresholds.push({ metric: name, expression, breached: breached === true });
+        }
+        if (isTrend(values))
+            run.timings[name] = measurement(name, values);
+        else if ('rate' in values || ('passes' in values && 'fails' in values)) {
+            const passes = num(values.passes);
+            const fails = num(values.fails);
+            run.rates[name] = { rate: num(values.rate ?? values.value), total: passes + fails };
+        }
+        else if ('count' in values)
+            run.counts[name] = num(values.count);
+    }
+    return run;
+}
+function machineReadable(parsed, at) {
+    const results = (parsed.results ?? {});
+    const metrics = Array.isArray(results.metrics) ? results.metrics : [];
+    // Not an empty list: this export records no threshold results, which is a different statement.
+    const run = { tool: 'k6', format: 'machine-readable', at, timings: {}, rates: {}, counts: {}, thresholds: null };
+    for (const entry of metrics) {
+        const name = typeof entry.name === 'string' ? entry.name : '';
+        const values = (entry.values ?? {});
+        if (name === '' || typeof values !== 'object' || values === null)
+            continue;
+        if (entry.type === 'trend')
+            run.timings[name] = measurement(name, values);
+        else if (entry.type === 'rate')
+            run.rates[name] = { rate: num(values.rate), total: num(values.total) };
+        else if (entry.type === 'counter' || 'count' in values)
+            run.counts[name] = num(values.count);
+    }
+    return run;
+}
+/** True of either shape k6 writes. */
+function looksLikeK6Summary(v) {
+    if (typeof v !== 'object' || v === null)
+        return false;
+    const o = v;
+    if (typeof o.metrics === 'object' && o.metrics !== null && !Array.isArray(o.metrics))
+        return true;
+    const results = o.results;
+    return typeof results === 'object' && results !== null && Array.isArray(results.metrics);
+}
+export function readK6Summary(path) {
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        throw new Error(`${path} is not JSON. Tewip reads the JSON k6 writes with --summary-export.`);
+    }
+    if (!looksLikeK6Summary(parsed)) {
+        throw new Error(`${path} is JSON, but not a k6 summary: Tewip looked for a "metrics" object or a "results.metrics" array. ` +
+            'Write one with: k6 run --summary-export=summary.json your-test.js');
+    }
+    const o = parsed;
+    const metadata = (o.metadata ?? {});
+    const at = typeof metadata.generated_at === 'string' ? metadata.generated_at : new Date().toISOString();
+    return Array.isArray(o.results?.metrics) ? machineReadable(o, at) : classic(o, at);
+}
+/** The metric a team means by "how slow is it", when they have not said which. */
+export const MAIN_TIMING = 'http_req_duration';
+/** How much work the run did. A verdict from a handful of requests is not worth printing. */
+export function requestCount(run) {
+    return run.counts.http_reqs ?? run.rates.http_req_failed?.total ?? run.counts.iterations ?? 0;
+}

package/dist/engine/perf/perf-command.js

@@ -0,0 +1,120 @@
+// Phase 30: `tewip perf` - is this change slower, and does it matter?
+//
+// Two questions, answered separately because they fail separately:
+//
+//   1. **Did your own thresholds hold?** The team already wrote what "fast enough" means, in the k6
+//      script. Tewip reads the result rather than asking them to write a budget twice. When the
+//      export does not record thresholds - which the machine-readable one does not - the answer is
+//      "this export cannot tell me", never "nothing was breached".
+//   2. **Is it slower than it was?** Answered only from repeated baseline runs, and refused when
+//      there are not enough of them, because one run against one run is not evidence.
+//
+// It never estimates a duration, a capacity or a user impact. It has no idea what the production
+// hardware is, what the data volume is, or how many people use the endpoint, and a number invented
+// for any of those is worse than silence.
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { MAIN_TIMING, readK6Summary, requestCount } from './k6.js';
+import { compareMetric, ENOUGH_BASELINES, ENOUGH_REQUESTS, timingsToCompare } from './compare.js';
+import { baselineFor, knownLabels, recordRun, storedRuns } from './history.js';
+const ms = (n) => `${Math.round(n * 10) / 10}ms`;
+export function renderPerf(run, comparisons, requests, label, baselineCount, recorded) {
+    const lines = ['# Tewip performance check', ''];
+    const breaches = (run.thresholds ?? []).filter((t) => t.breached);
+    const slower = comparisons.filter((c) => c.direction === 'slower');
+    const faster = comparisons.filter((c) => c.direction === 'faster');
+    const unsure = comparisons.filter((c) => c.direction === 'cannot-say');
+    lines.push(`Read a k6 run of **${requests} requests**, compared against **${baselineCount}** recorded baseline ${baselineCount === 1 ? 'run' : 'runs'} for \`${label}\`.`, '');
+    // Headline, in the order that decides what a person does next.
+    if (breaches.length > 0) {
+        lines.push(`**${breaches.length} of your own thresholds ${breaches.length === 1 ? 'was' : 'were'} breached.**`, '');
+    }
+    if (slower.length > 0)
+        lines.push(`**${slower.length} ${slower.length === 1 ? 'metric is' : 'metrics are'} slower than the baseline runs can explain.**`, '');
+    if (breaches.length === 0 && slower.length === 0) {
+        lines.push(run.thresholds === null
+            ? '**No regression this baseline can detect.** Your thresholds are not in this export, so nothing is said about them.'
+            : '**No threshold breached, and no regression this baseline can detect.**', '');
+    }
+    lines.push('## Did your own thresholds hold?', '');
+    if (run.thresholds === null) {
+        lines.push('**Cannot say.** This summary came from `--new-machine-readable-summary`, and that export records no threshold ' +
+            'results at all - the word appears in it only inside the copy of your script. Tewip will not report "nothing was ' +
+            'breached" from a file that does not say. Re-run with plain `--summary-export` to get the answer.', '');
+    }
+    else if (run.thresholds.length === 0) {
+        lines.push('This run has no thresholds. Add them to your k6 script and the team decides what "fast enough" means, rather than Tewip.', '');
+    }
+    else {
+        for (const t of run.thresholds) {
+            lines.push(`- ${t.breached ? '**breached**' : 'held'} — \`${t.metric}\`: \`${t.expression}\``);
+        }
+        lines.push('');
+    }
+    lines.push('## Is it slower than it was?', '');
+    if (baselineCount < ENOUGH_BASELINES) {
+        lines.push(`**Cannot say.** There ${baselineCount === 1 ? 'is' : 'are'} ${baselineCount} recorded ${baselineCount === 1 ? 'run' : 'runs'} for \`${label}\`, ` +
+            `and Tewip needs ${ENOUGH_BASELINES} before it will call anything a regression. Performance numbers move between identical ` +
+            'runs, and without several of them there is no way to tell a change from the machine having a busy moment. ' +
+            `Record baselines on your main branch with \`tewip perf <summary.json> --record\`.`, '');
+    }
+    for (const c of [...slower, ...faster, ...unsure]) {
+        const verdict = c.direction === 'slower' ? '**slower**' : c.direction === 'faster' ? 'faster' : 'cannot say';
+        lines.push(`- \`${c.metric}\` p95 ${ms(c.now)} — ${verdict}`);
+        lines.push(`  - baseline ${ms(c.baselineLow)}–${ms(c.baselineHigh)} over ${c.baselineRuns} runs, middle ${ms(c.before)}`);
+        lines.push(`  - ${c.why}`);
+    }
+    lines.push('');
+    if (requests < ENOUGH_REQUESTS) {
+        lines.push(`**${requests} requests is thin.** A p95 from this few is a handful of data points and will move on its own. ` +
+            'Treat everything above as indicative and lengthen the run before deciding anything.', '');
+    }
+    lines.push('## What this does not tell you', '');
+    lines.push('- **Nothing about production.** This is the hardware the run happened on, with that data volume and that ' +
+        'concurrency. Tewip cannot see your real machines, your real data or your real traffic, and will not guess.', '- **No duration is predicted.** How long a real user waits depends on network, device and cache, none of which are here.', '- **Only what the script exercised.** An endpoint the test never called is not covered, however green this looks.', '- **Not capacity.** This says whether it changed, not how many users it would hold.', '');
+    if (recorded)
+        lines.push(`This run was added to the baseline for \`${label}\`.`, '');
+    else
+        lines.push(`This run was **not** recorded. Add \`--record\` on your main branch to make it part of the baseline; a regression recorded by accident becomes next week's normal.`, '');
+    return lines.join('\n');
+}
+export function runPerf(cmd) {
+    const root = resolve(cmd.root);
+    const label = cmd.label ?? 'default';
+    const run = readK6Summary(resolve(root, cmd.summary));
+    const requests = requestCount(run);
+    const history = storedRuns(root, label);
+    if (history.length === 0) {
+        const known = knownLabels(root);
+        // A typo in --label would otherwise look exactly like "no history yet", and the team would
+        // record a second baseline under the wrong name without noticing.
+        if (known.length > 0 && !known.includes(label)) {
+            console.error(`[tewip] no recorded runs for label "${label}". This project has: ${known.join(', ')}.`);
+        }
+    }
+    const comparisons = timingsToCompare(run)
+        .map((metric) => compareMetric(metric, run.timings[metric].p95, baselineFor(history, metric)))
+        // A metric that is zero now and was zero every time before says nothing. http_req_blocked is
+        // zero on a local run, and printing "0ms is within 0-0ms" three times buries the real lines.
+        .filter((c) => c.now > 0 || c.baselineHigh > 0);
+    const recorded = cmd.record === true;
+    if (recorded)
+        recordRun(root, label, run, requests, cmd.gitSha);
+    const breached = (run.thresholds ?? []).some((t) => t.breached);
+    const regressed = comparisons.some((c) => c.direction === 'slower');
+    const report = renderPerf(run, comparisons, requests, label, history.length, recorded);
+    console.log(report);
+    if (cmd.gate && (breached || regressed)) {
+        const why = [breached ? 'a threshold you wrote was breached' : '', regressed ? 'something is slower than the baselines explain' : '']
+            .filter(Boolean)
+            .join(', and ');
+        console.error(`${String.fromCharCode(10)}Performance gate failed: ${why}.`);
+        process.exitCode = 1;
+    }
+    if (cmd.out) {
+        const path = resolve(root, cmd.out);
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, report, 'utf8');
+    }
+    return { run, comparisons, requests, regressed, breached, report };
+}

package/dist/mcp/tools-prove.js

@@ -95,6 +95,33 @@ export function registerProofTools(server, { answer, readOnly, project }) {
             return 'No migration or schema file in that change.';
         return renderSchema(migrations, stillUsed(root, migrations.flatMap((m) => m.findings)));
     }));
+    server.registerTool('is_this_slower', {
+        title: 'Is this change slower, and does it matter?',
+        description: "Judges a k6 load-test run, rather than restating its numbers. Two answers kept apart: whether the thresholds the team wrote in their own k6 script held, and whether this run is slower than the recorded baseline. The second is answered only from three or more baseline runs - below that it returns 'cannot say', because one run against one run cannot distinguish a regression from a busy machine, and a percentage printed without that distinction is how performance tooling gets ignored. It never predicts a duration, a capacity or a user impact, and it says what the run does not cover. Use it when asked whether a change made something slower.",
+        inputSchema: {
+            project,
+            summary: z.string().describe('Path to the JSON from `k6 run --summary-export=summary.json`'),
+            label: z.string().optional().describe('Which load test this is, so two different suites do not become each other baseline'),
+        },
+        annotations: readOnly,
+    }, ({ project: root, summary, label }) => answer(async () => {
+        if (!isAbsolute(root) || !existsSync(root))
+            throw new Error(`project must be an existing absolute path, got "${root}"`);
+        // Never records: an assistant adding runs to a team's baseline unasked is how a regression
+        // silently becomes the new normal. Recording stays a deliberate act on the command line.
+        const { readK6Summary, requestCount } = await import('../engine/perf/k6.js');
+        const { compareMetric, timingsToCompare } = await import('../engine/perf/compare.js');
+        const { baselineFor, storedRuns } = await import('../engine/perf/history.js');
+        const { renderPerf } = await import('../engine/perf/perf-command.js');
+        const { isAbsolute: abs, resolve } = await import('node:path');
+        const run = readK6Summary(abs(summary) ? summary : resolve(root, summary));
+        const name = label ?? 'default';
+        const history = storedRuns(root, name);
+        const comparisons = timingsToCompare(run)
+            .map((m) => compareMetric(m, run.timings[m].p95, baselineFor(history, m)))
+            .filter((c) => c.now > 0 || c.baselineHigh > 0);
+        return renderPerf(run, comparisons, requestCount(run), name, history.length, false);
+    }));
     server.registerTool('accessibility_barriers', {
         title: 'Can everybody use this interface?',
         description: "Accessibility barriers in a project's markup, each named against the WCAG 2.2 criterion a regulator would cite, with the evidence to check it. Two kinds of answer, kept apart on purpose: barriers that reading the markup proves (no alt attribute at all, a field with no label anywhere, a div that only a mouse can activate), and the ones only a person can settle, where something is written as an expression or a component and the markup cannot say. It also returns every criterion it did NOT check - contrast, focus order, whether alt text is any good - because those need a rendered page. Use it before shipping an interface, or when asked whether something is accessible; a clean result means these checks found nothing, never that the product is accessible. No browser, no network, no model.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tewip-ai",
-  "version": "0.36.0",
+  "version": "0.37.0",
   "mcpName": "io.github.hmamut39/tewip",
   "description": "Tewip finds why each failing test failed - real bug, flaky test, environment, test data or changed selector - for any stack, from the command line, CI, or your editor.",
   "keywords": [