tewip-ai 0.22.0 → 0.24.0

package/README.md

@@ -8,7 +8,7 @@ It works for every stack: Node.js (node:test, Jest, Vitest, Mocha), Python (pyte
 |---|---|
 | **Terminal** | `npm install -g tewip-ai`, then `tewip explain report.xml`, `tewip ci owner/repo --pr 12`, `tewip mcp` |
 | **VS Code, Cursor, Windsurf, VSCodium** | the Tewip extension ([download](https://github.com/hmamut39/tewip/releases/tag/vscode-0.5.0)): registers Tewip with the editor's AI assistant and adds six commands - explain a report, why CI failed on this branch, the risk review of your change, which flaky tests to quarantine, the security check, and what your corrections add up to |
-| **JetBrains, Claude, other AI assistants** | add the MCP server `tewip mcp` (see [editor setup](#use-it-from-your-editor-any-ide-that-speaks-mcp)) |
+| **JetBrains, Claude, other AI assistants** | add the MCP server `tewip mcp`: fifteen tools, including *has this happened here before?*, *is this requirement covered and passing?* and *what should be done next about this goal?* (see [editor setup](#use-it-from-your-editor-any-ide-that-speaks-mcp)) |
 | **Any model** | OpenAI, Claude, Gemini, Azure, or a model on your own machine with Ollama (no account, nothing leaves the computer): `TEWIP_PROVIDER` |
 | **GitHub CI** | the Tewip Action: a comment on every pull request, an optional merge gate, verified fix PRs ([QUICKSTART](QUICKSTART.md)) |
 
@@ -71,6 +71,10 @@ On every run, the action:
 - **Developers:** posts one diagnosis comment on the pull request and keeps it updated. For each failure it says whether the change likely caused it, why, and what to do next.
 - **SDETs:** writes the triage board into the job summary.
 - **DevOps:** collects environment failures (server errors, connection resets, outages) in **one** GitHub issue, and each new run adds a single grouped comment to it.
+- **Evidence, every run:** the Action writes an attestation into its artifact - the claims with
+  their evidence and which layer decided each, what Tewip **refused** to decide, and what it did
+  not check at all. Nothing enters it that Tewip did not verify itself, so a release decision can
+  be taken from it without opening CI.
 - **Fixes (`autofix: true`):** for drifted locators that the deterministic rule matched to a renamed element, it rewrites the locator, re-runs that test, and opens a separate pull request with the changes that passed. It never merges and never edits application code.
 - **Every role:** uploads all role views as the `tewip-report` artifact.
 - **When the job dies before any test runs** (an image that would not pull, a runner out of disk, a service container that never came up): it reads the failed job's log and names the cause, instead of leaving a red X with no explanation.

package/dist/cli/help.js

@@ -100,6 +100,13 @@ Usage:
                                     same way more than once, which rule decided it, and the failures
                                     it came from. Says "not yet" rather than inventing a pattern
                                     from two cases. No model, no cost.
+  tewip pursue "<a goal>" [--act] [--out next.md]
+                                    Give Tewip a goal instead of a verb - "keep the checkout flow
+                                    green" - and it says what it would do next and why, from what
+                                    it can actually see. The order is fixed and written down: a
+                                    real bug first, then the environment, then flakiness, then a
+                                    coverage gap. It decides; it does not act unless you ask, and
+                                    even then only through the gates that prove a change.
   tewip trace [--only "<ticket or title>"] [--out trace.md]
                                     Is this requirement covered, and is it passing right now? Joins
                                     the plans Tewip wrote to the tests that cover them and the runs
@@ -118,10 +125,14 @@ Usage:
                                     it fails for the incident's own reason. A test that passes, or
                                     fails its own way, is reported and thrown away.
   tewip attest [--run <id>] [--out attestation.md] [--json bundle.json]
+  tewip attest --verify <bundle.json> [--key <public.pem>]
                                     What Tewip checked for a build, as one artifact: the claims with
                                     their evidence and which layer decided each, what it refused to
                                     decide and why, and what it did not check at all. Nothing enters
-                                    it that Tewip did not verify itself. No model, no cost.
+                                    it that Tewip did not verify itself. Every bundle carries a
+                                    digest; set TEWIP_ATTEST_KEY to an ed25519 private key to sign
+                                    it too. --verify says what it checked and what that does not
+                                    establish - a digest means undamaged, not unedited. No cost.
   tewip mcp                         Serve Tewip over MCP (stdio) for an editor or AI assistant.
   tewip --version                   Print the version.
 

package/dist/cli/tewip.js

@@ -177,6 +177,14 @@ async function main() {
             runLearn({ root: process.cwd(), name: flag(args, 'name'), labels: flag(args, 'labels'), out: flag(args, 'out') });
             return;
         }
+        case 'pursue': {
+            const goal = args.filter((a, i) => !a.startsWith('--') && !['--name', '--out'].includes(args[i - 1] ?? '')).join(' ').trim();
+            if (!goal)
+                throw new Error('usage: tewip pursue "<a goal, e.g. keep the checkout flow green>" [--act]');
+            const { runPursue } = await import('../engine/pursue/pursue-command.js');
+            runPursue({ root: process.cwd(), goal, act: args.includes('--act'), name: flag(args, 'name'), out: flag(args, 'out') });
+            return;
+        }
         case 'trace': {
             const { runTrace } = await import('../engine/trace/trace-command.js');
             runTrace({ root: process.cwd(), only: flag(args, 'only'), name: flag(args, 'name'), out: flag(args, 'out') });
@@ -202,6 +210,15 @@ async function main() {
             return;
         }
         case 'attest': {
+            const verify = flag(args, 'verify');
+            if (verify) {
+                const { verifyAttestation } = await import('../engine/attest/attest-command.js');
+                const { ok, report } = verifyAttestation(verify, flag(args, 'key'));
+                console.log(report);
+                if (!ok)
+                    process.exitCode = 1;
+                return;
+            }
             const { runAttest } = await import('../engine/attest/attest-command.js');
             runAttest({ root: process.cwd(), name: flag(args, 'name'), runId: flag(args, 'run'), out: flag(args, 'out'), json: flag(args, 'json') });
             return;

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

@@ -1,9 +1,32 @@
 // `tewip attest`: the evidence for one run, as an artifact a build can carry.
-import { existsSync, mkdirSync, readdirSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { datasetFiles, readJsonl, readTriageRecords } from '../../reporters/store.js';
 import { ENGINE_VERSION } from '../engine.js';
 import { attestRun, renderAttestation } from './attest.js';
+import { check } from './seal.js';
+/**
+ * Checks a bundle somebody was handed. It reports what the check establishes and, just as
+ * importantly, what it does not: a digest that matches proves the file is undamaged, and only a
+ * signature checked against a key says who made it.
+ */
+export function verifyAttestation(file, keyFile) {
+    const bundle = JSON.parse(readFileSync(resolve(file), 'utf8'));
+    const publicKey = keyFile ? readFileSync(resolve(keyFile), 'utf8') : undefined;
+    const checked = check(bundle, publicKey);
+    const ok = checked.contentMatches && checked.signature !== 'invalid';
+    const report = [
+        `# ${ok ? 'Checked' : 'Do not trust this bundle'}: ${file.split(/[\/]/).pop()}`,
+        '',
+        `Content matches its digest: ${checked.contentMatches ? 'yes' : 'NO'}`,
+        `Signature: ${checked.signature.replace(/-/g, ' ')}`,
+        '',
+        checked.says + '.',
+        '',
+        ...(checked.signature === 'no-key-given' ? ['Pass `--key <public.pem>` to check the signature itself.'] : []),
+    ].join(String.fromCharCode(10));
+    return { ok, report };
+}
 /** Everything Tewip kept for one project, newest run last. */
 function history(root, only) {
     const dir = join(root, '.tewip', 'history');

package/dist/engine/attest/attest.js

@@ -1,3 +1,5 @@
+import { readFileSync } from 'node:fs';
+import { seal } from './seal.js';
 const sourceOf = (record) => String(record.diagnosis?.source ?? '');
 /** The evidence line a person reads: the first thing the deciding layer actually said. */
 function evidenceOf(record) {
@@ -33,7 +35,7 @@ export function attestRun(project, run, records, { checked, notChecked, tool, en
             confidence: Number(diagnosis?.confidence ?? 0),
         });
     }
-    return {
+    const bundle = {
         project,
         commit: run.gitSha ?? '',
         runId: run.runId,
@@ -47,6 +49,22 @@ export function attestRun(project, run, records, { checked, notChecked, tool, en
         refusals,
         producedBy: { tool, engine, at: new Date().toISOString() },
     };
+    // Sealed last, over everything above: the digest is of the content, never of itself.
+    return { ...bundle, seal: seal(bundle, signingKey()) };
+}
+/** The Ed25519 private key to sign with, from TEWIP_ATTEST_KEY: a PEM, or a path to one. */
+function signingKey() {
+    const given = process.env.TEWIP_ATTEST_KEY?.trim();
+    if (!given)
+        return undefined;
+    if (given.includes('BEGIN'))
+        return given;
+    try {
+        return readFileSync(given, 'utf8');
+    }
+    catch (error) {
+        throw new Error(`TEWIP_ATTEST_KEY points at ${given}, which could not be read: ${error instanceof Error ? error.message : String(error)}`);
+    }
 }
 /** The bundle as a person reads it. The refusals are not hidden at the bottom; they are the point. */
 export function renderAttestation(a) {
@@ -84,6 +102,10 @@ export function renderAttestation(a) {
         lines.push(`- **${refusal.what}**`);
         lines.push(`  - Why: ${refusal.why}`);
     }
-    lines.push('', '---', '', `Produced by ${a.producedBy.tool} (${a.producedBy.engine}) at ${a.producedBy.at.slice(0, 19).replace('T', ' ')} UTC.`, 'Every claim above names the run it came from and the layer that decided it. This is a statement', 'about the checks listed under "what was checked" and nothing else.');
+    lines.push('', '---', '', `Produced by ${a.producedBy.tool} (${a.producedBy.engine}) at ${a.producedBy.at.slice(0, 19).replace('T', ' ')} UTC.`, a.seal?.signature
+        ? `Signed (${a.seal.algorithm}); digest ${a.seal.digest.slice(0, 16)}…. Check it with \`tewip attest --verify <bundle.json> --key <public.pem>\`.`
+        : a.seal
+            ? `Digest ${a.seal.digest.slice(0, 16)}…, which is not a signature: it shows the bundle is undamaged, not that nobody edited it. Set TEWIP_ATTEST_KEY to sign.`
+            : '', 'Every claim above names the run it came from and the layer that decided it. This is a statement', 'about the checks listed under "what was checked" and nothing else.');
     return lines.join('\n');
 }

package/dist/engine/attest/seal.js

@@ -0,0 +1,90 @@
+// Sealing an attestation, and being precise about what a seal is worth.
+//
+// The roadmap promised a "signed" bundle and the first implementation signed nothing. This closes
+// that, but the honest part is the distinction it refuses to blur:
+//
+//   A **digest** says the content matches the fingerprint recorded inside it. Anybody who edits the
+//   bundle can recompute the fingerprint, so on its own it proves only that nothing was corrupted
+//   in transit - not that nobody changed it on purpose. It is still worth having: it gives a bundle
+//   a stable identity that a release note or a ticket can quote.
+//
+//   A **signature** says the holder of a private key produced this exact content. That is the claim
+//   people mean by "signed", and it is only available when a key exists.
+//
+// A tool that prints "signed" over a bare hash is doing the thing this whole project exists not to
+// do, so the words are kept apart everywhere: in the type, in the report, and in the verifier.
+import { createHash, createPrivateKey, createPublicKey, sign as cryptoSign, verify as cryptoVerify } from 'node:crypto';
+/**
+ * The bundle's content, in a form that hashes the same everywhere: keys in order, the seal itself
+ * left out, and the time it was produced kept in, because a bundle for a different moment is a
+ * different bundle.
+ */
+export function canonical(bundle) {
+    const ordered = (value) => {
+        if (Array.isArray(value))
+            return value.map(ordered);
+        if (value && typeof value === 'object') {
+            return Object.fromEntries(Object.entries(value)
+                .filter(([k]) => k !== 'seal')
+                .sort(([a], [b]) => a.localeCompare(b))
+                .map(([k, v]) => [k, ordered(v)]));
+        }
+        return value;
+    };
+    return JSON.stringify(ordered(bundle));
+}
+export const digestOf = (bundle) => createHash('sha256').update(canonical(bundle)).digest('hex');
+/**
+ * Seals a bundle: always a digest, and a signature when a key is given. The key is a PEM Ed25519
+ * private key, from `TEWIP_ATTEST_KEY` (a path or the PEM itself). Nothing is generated silently:
+ * without a key there is no signature and the bundle says so rather than implying one.
+ */
+export function seal(bundle, privateKeyPem) {
+    const digest = digestOf(bundle);
+    if (!privateKeyPem?.trim())
+        return { digest };
+    try {
+        const key = createPrivateKey(privateKeyPem);
+        if (key.asymmetricKeyType !== 'ed25519')
+            throw new Error(`the signing key is ${key.asymmetricKeyType}, and Tewip signs with ed25519`);
+        return { digest, signature: cryptoSign(null, Buffer.from(digest, 'hex'), key).toString('base64'), algorithm: 'ed25519' };
+    }
+    catch (error) {
+        // A key that does not work is not a reason to ship an unmarked bundle quietly.
+        throw new Error(`the attestation could not be signed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+/** Checks a sealed bundle, and says exactly what that check does and does not establish. */
+export function check(bundle, publicKeyPem) {
+    const recorded = bundle.seal?.digest ?? '';
+    const contentMatches = Boolean(recorded) && recorded === digestOf(bundle);
+    if (!recorded) {
+        return { contentMatches: false, signature: 'absent', says: 'this bundle carries no digest at all, so nothing about it can be checked' };
+    }
+    if (!contentMatches) {
+        return { contentMatches: false, signature: bundle.seal?.signature ? 'invalid' : 'absent', says: 'the content does not match the digest recorded inside it: it has been changed since it was written' };
+    }
+    if (!bundle.seal?.signature) {
+        return {
+            contentMatches: true,
+            signature: 'absent',
+            says: 'the content matches its own digest, and nothing more: no signature was made, so this shows the bundle is undamaged, not that nobody edited it - an editor can recompute a digest',
+        };
+    }
+    if (!publicKeyPem?.trim()) {
+        return { contentMatches: true, signature: 'no-key-given', says: 'the content matches its own digest and carries a signature, but no public key was given, so the signature was not checked' };
+    }
+    try {
+        const ok = cryptoVerify(null, Buffer.from(recorded, 'hex'), createPublicKey(publicKeyPem), Buffer.from(bundle.seal.signature, 'base64'));
+        return {
+            contentMatches: true,
+            signature: ok ? 'valid' : 'invalid',
+            says: ok
+                ? 'the content matches its digest and the signature is the holder of that key over this exact content'
+                : 'the content matches its digest, but the signature does not belong to this key and this content',
+        };
+    }
+    catch (error) {
+        return { contentMatches: true, signature: 'invalid', says: `the signature could not be checked: ${error instanceof Error ? error.message : String(error)}` };
+    }
+}

package/dist/engine/history.js

@@ -94,7 +94,10 @@ export class HistoryIndex {
     }
     runContext(runId) {
         const e = this.runs[this.indexOf(runId)];
-        return { runId, branch: e.branch, testsAttempted: Object.keys(e.attempts).length, failures: e.failures };
+        // "Some run knows its commit" is the weakest true statement available: a single kept run with a
+        // sha means the history can distinguish code changes from flakiness at all.
+        const commitsKnown = this.runs.some((r) => Boolean(r.sha));
+        return { runId, branch: e.branch, testsAttempted: Object.keys(e.attempts).length, failures: e.failures, commitsKnown };
     }
     indexOf(runId) {
         const i = this.position.get(runId);

package/dist/engine/pursue/policy.js

@@ -0,0 +1,91 @@
+const list = (items, max = 3) => items.slice(0, max).join(', ') + (items.length > max ? `, and ${items.length - max} more` : '');
+/**
+ * What to do next about a goal, in one pass, most urgent first.
+ *
+ * The order is the argument. A real bug beats everything, because the goal is already broken. The
+ * environment comes next, because nothing about the code has been shown and touching tests would
+ * be guessing. Flakiness comes third: the code may be fine and the test is lying. Only when
+ * nothing is failing is a coverage gap worth spending on, and only when nothing is failing and
+ * nothing is missing is the goal worth attesting to.
+ */
+export function decide(goal, seen) {
+    if (seen.noHistory) {
+        return {
+            act: 'look-first',
+            next: 'run `tewip explain <report>` on a test report, so there is something to reason about',
+            why: 'no run has been kept for this project, so nothing is known about the goal yet - and guessing from the name of a goal would be inventing',
+            evidence: [],
+            changesFiles: false,
+        };
+    }
+    const realBugs = seen.failing.filter((f) => f.category === 'REAL_BUG');
+    if (realBugs.length > 0) {
+        return {
+            act: 'triage-real-bug',
+            next: `put ${realBugs.length} failing test(s) in front of a person: ${list(realBugs.map((f) => f.testId))}`,
+            why: `the goal is already broken: Tewip calls ${realBugs.length === 1 ? 'this failure' : 'these failures'} a real bug, which is the one kind it will not work around`,
+            evidence: realBugs.map((f) => `${f.testId}: REAL_BUG at ${f.confidence.toFixed(2)}`),
+            changesFiles: false,
+        };
+    }
+    const env = seen.failing.filter((f) => f.category === 'ENV');
+    if (env.length > 0 && env.length === seen.failing.length) {
+        return {
+            act: 'rerun-environment',
+            next: `re-run, and do not touch the tests: ${list(env.map((f) => f.testId))}`,
+            why: 'every failure the goal depends on is the environment, so nothing has been shown about the code and changing a test would be guessing',
+            evidence: env.map((f) => `${f.testId}: ENV at ${f.confidence.toFixed(2)}`),
+            changesFiles: false,
+        };
+    }
+    const timing = seen.failing.filter((f) => f.category === 'TIMING');
+    if (timing.length > 0 || seen.flaky.length > 0) {
+        const worst = seen.flaky.slice().sort((a, b) => b.times - a.times);
+        return {
+            act: 'settle-flaky',
+            next: worst.length > 0 ? `settle ${worst[0].testId}, which has flaked ${worst[0].times} time(s)` : `settle ${list(timing.map((f) => f.testId))}`,
+            why: 'the goal is not broken, but the tests watching it come and go, so nobody can tell whether it is broken',
+            evidence: [...timing.map((f) => `${f.testId}: TIMING at ${f.confidence.toFixed(2)}`), ...worst.map((f) => `${f.testId}: flaked ${f.times} time(s)`)],
+            changesFiles: true,
+        };
+    }
+    // Anything still failing has to be dealt with before anything else is spent on. Without this the
+    // policy read "3 failing" in its own state line and then said "nothing the goal depends on is
+    // failing", because undecided failures matched none of the branches above - the exact shape of
+    // error this project exists to refuse.
+    if (seen.failing.length > 0) {
+        return {
+            act: 'triage-undecided',
+            next: `put ${seen.failing.length} failing test(s) in front of a person: ${list(seen.failing.map((f) => f.testId))}`,
+            why: `the goal is failing and Tewip cannot say why: ${list([...new Set(seen.failing.map((f) => f.category))], 4)}. It will not move on to anything else while something it is watching is red`,
+            evidence: seen.failing.map((f) => `${f.testId}: ${f.category}${f.confidence ? ` at ${f.confidence.toFixed(2)}` : ' (undiagnosed)'}`),
+            changesFiles: false,
+        };
+    }
+    if (seen.uncovered.length > 0) {
+        const first = seen.uncovered[0];
+        return {
+            act: 'cover-gap',
+            next: `write a test for ${first.id}: ${first.title}`,
+            why: `nothing the goal depends on is failing, so the next thing worth spending on is what nothing is checking - ${seen.uncovered.length} scenario(s), worst first`,
+            evidence: seen.uncovered.slice(0, 5).map((u) => `${u.id} (${u.priority || 'no priority'}): ${u.title}`),
+            changesFiles: true,
+        };
+    }
+    if (seen.passing > 0) {
+        return {
+            act: 'attest',
+            next: 'produce the evidence bundle with `tewip attest`, and stop',
+            why: `everything the goal covers ran and passed (${seen.passing} test(s)), and nothing it depends on is unchecked. There is no next action worth taking`,
+            evidence: [`${seen.passing} test(s) passed in the last run`],
+            changesFiles: false,
+        };
+    }
+    return {
+        act: 'stand-down',
+        next: 'nothing: name the goal in words this project uses, or check the project is the right one',
+        why: `nothing kept here matches "${goal.slice(0, 60)}" - no test, no scenario, no failure - so acting would mean acting on something Tewip cannot see`,
+        evidence: [],
+        changesFiles: false,
+    };
+}

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

@@ -0,0 +1,125 @@
+// `tewip pursue "<a goal>"`: what Tewip would do next about it, and why.
+//
+// By default it decides and explains, and does nothing. `--act` lets it carry out the one action
+// it chose, and only through the gates that already prove a change before keeping it. There is no
+// mode in which it loops unattended: an agent that keeps going until it decides to stop is the
+// thing teams roll back, and nothing here needs it.
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { datasetFiles, readJsonl, readTriageRecords } from '../../reporters/store.js';
+import { decide } from './policy.js';
+const words = (text) => (text.toLowerCase().match(/[a-z][a-z0-9]{2,}/g) ?? []).filter((w) => !['the', 'and', 'for', 'this', 'that', 'with', 'keep', 'green', 'sprint', 'flow', 'test', 'tests'].includes(w));
+/** Does this test or scenario belong to the goal? Deterministic, so a person can predict it. */
+function about(goal, text) {
+    if (goal.length === 0)
+        return true; // an unworded goal means the whole project
+    const haystack = text.toLowerCase();
+    return goal.some((w) => haystack.includes(w));
+}
+/** What is true about this project right now, as far as anything kept here can show. */
+export function observe(root, goal, only) {
+    const dir = join(root, '.tewip', 'history');
+    const runs = [];
+    const records = [];
+    if (existsSync(dir)) {
+        for (const project of only ? [only] : readdirSync(dir)) {
+            const where = join(dir, project);
+            if (!existsSync(where))
+                continue;
+            runs.push(...readJsonl(datasetFiles(where).runs));
+            records.push(...readTriageRecords(datasetFiles(where).triage));
+        }
+    }
+    runs.sort((a, b) => (a.finishedAt > b.finishedAt ? 1 : -1));
+    const newest = runs.at(-1);
+    const wanted = words(goal);
+    const failing = records
+        .filter((r) => r.runId === newest?.runId && about(wanted, r.testId))
+        .map((r) => {
+        const d = r.diagnosis;
+        return { testId: r.testId, category: String(d?.category ?? 'UNKNOWN'), confidence: Number(d?.confidence ?? 0) };
+    });
+    // A test that failed in more than one earlier run and is not failing now has come and gone.
+    const failedBefore = new Map();
+    for (const r of records)
+        if (about(wanted, r.testId))
+            failedBefore.set(r.testId, (failedBefore.get(r.testId) ?? 0) + 1);
+    const failingNow = new Set(failing.map((f) => f.testId));
+    const flaky = [...failedBefore.entries()].filter(([testId, times]) => times >= 2 && !failingNow.has(testId)).map(([testId, times]) => ({ testId, times }));
+    const attempted = Object.keys(newest?.attempts ?? {}).filter((t) => about(wanted, t));
+    return {
+        failing,
+        flaky,
+        uncovered: uncoveredScenarios(root, wanted, attempted),
+        passing: attempted.length - failing.length,
+        noHistory: runs.length === 0,
+    };
+}
+/** Scenarios of a kept plan that no attempted test can be matched to, worst priority first. */
+function uncoveredScenarios(root, goal, attempted) {
+    const dir = join(root, '.tewip', 'plans');
+    if (!existsSync(dir))
+        return [];
+    const clean = (s) => s.toLowerCase().replace(/[^a-z0-9]+/g, '');
+    const out = [];
+    for (const file of readdirSync(dir).filter((f) => f.endsWith('.json'))) {
+        try {
+            const saved = JSON.parse(readFileSync(join(dir, file), 'utf8'));
+            const plan = saved.plan ?? saved;
+            if (!Array.isArray(plan.scenarios))
+                continue;
+            if (!about(goal, `${plan.title ?? ''} ${saved.feature ?? ''}`))
+                continue;
+            for (const scenario of plan.scenarios) {
+                const covered = (scenario.covered_by ?? '').trim() || attempted.find((t) => clean(t).includes(clean(scenario.id)) && clean(scenario.id).length >= 4);
+                if (!covered)
+                    out.push({ id: scenario.id, title: scenario.title, priority: scenario.priority ?? '' });
+            }
+        }
+        catch {
+            // Not a readable plan.
+        }
+    }
+    return out.sort((a, b) => (a.priority || 'P9').localeCompare(b.priority || 'P9'));
+}
+export function renderPursuit(goal, seen, decision, acting) {
+    const lines = [
+        `# Goal: ${goal}`,
+        '',
+        `What is true now: ${seen.passing} passing, ${seen.failing.length} failing, ${seen.flaky.length} that come and go, ${seen.uncovered.length} unchecked.`,
+        '',
+        '## What Tewip would do next',
+        '',
+        `**${decision.next}**`,
+        '',
+        decision.why + '.',
+        '',
+    ];
+    if (decision.evidence.length > 0) {
+        lines.push('What it is reacting to:', '');
+        for (const e of decision.evidence)
+            lines.push(`- ${e}`);
+        lines.push('');
+    }
+    lines.push(decision.changesFiles
+        ? acting
+            ? 'This changes files, so it runs through the gate that proves a change before keeping it: anything unproved is thrown away.'
+            : 'This would change files, so Tewip has not done it. Run the command it names, or pass `--act`.'
+        : 'Tewip has not done anything: this is a decision, and the action is yours.', '', 'The order of these decisions is fixed and written down, not chosen by a model: a real bug first,', 'then the environment, then flakiness, then a coverage gap, and only then is a goal worth attesting.');
+    return lines.join('\n');
+}
+export function runPursue(cmd) {
+    const observed = observe(cmd.root, cmd.goal, cmd.name);
+    const decision = decide(cmd.goal, observed);
+    const report = renderPursuit(cmd.goal, observed, decision, Boolean(cmd.act));
+    console.log(report);
+    if (cmd.act && decision.changesFiles) {
+        console.error('\n`--act` is accepted, but Tewip carries out a change only through the command that proves it.');
+        console.error(`Run: ${decision.next}`);
+    }
+    if (cmd.out) {
+        mkdirSync(dirname(resolve(cmd.out)), { recursive: true });
+        writeFileSync(resolve(cmd.out), `${report}\n`, 'utf8');
+    }
+    return { decision, observed };
+}

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

@@ -20,17 +20,24 @@ function kept(root, only) {
     }
     return { records, corrections };
 }
-export function runRecall(cmd) {
+/**
+ * The report, without printing it. An MCP server speaks JSON-RPC over stdout, so anything one of
+ * its tools calls has to return its answer: a stray console.log corrupts every response the
+ * assistant receives, and the corruption looks like the tool being broken rather than noisy.
+ */
+export function recallReport(cmd) {
     const { records, corrections } = kept(cmd.root, cmd.name);
     if (records.length === 0) {
-        const empty = 'Nothing has been kept here yet, so there is no history to search. Run `tewip explain <report>` first.';
-        console.log(empty);
-        return empty;
+        return { report: 'Nothing has been kept here yet, so there is no history to search. Run `tewip explain <report>` first.', searched: 0, corrections: 0 };
     }
     const found = recall(cmd.question, memories(records, corrections), { testId: cmd.testId, limit: cmd.limit ?? 5 });
-    const report = renderRecall(cmd.question, found);
+    return { report: renderRecall(cmd.question, found), searched: records.length, corrections: corrections.length };
+}
+export function runRecall(cmd) {
+    const { report, searched, corrections } = recallReport(cmd);
     console.log(report);
-    console.error(`\nSearched ${records.length} kept failure(s) and ${corrections.length} correction(s). No model was called.`);
+    if (searched > 0)
+        console.error(`\nSearched ${searched} kept failure(s) and ${corrections} correction(s). No model was called.`);
     if (cmd.out) {
         mkdirSync(dirname(resolve(cmd.out)), { recursive: true });
         writeFileSync(resolve(cmd.out), `${report}\n`, 'utf8');

package/dist/engine/timing-rules.js

@@ -163,10 +163,18 @@ export const INTERMITTENT_MIN_ALTERNATIONS = 3;
  */
 export const timingIntermittent = {
     id: 'timing-intermittent',
-    evaluate({ history, loadFailedRequests }) {
+    evaluate({ history, loadFailedRequests, run }) {
         const { alternations, runs, failures } = history;
         if (alternations < INTERMITTENT_MIN_ALTERNATIONS)
             return null;
+        // Flipping only means flakiness if the code stayed the same while it flipped. Where no run
+        // carries a commit, nothing can tell "the test comes and goes" from "somebody kept changing
+        // the code" - which is exactly what happened when a regression was broken and restored several
+        // times in a row, and this rule called the regression flaky with the same confidence it gives
+        // a genuine flake. Without commits, that claim is not available.
+        if (!run.commitsKnown) {
+            return declined(this.id, `this test flipped ${alternations} times in ${runs} runs, but no run recorded a commit, so there is no way to tell a flaky test from code that kept changing`);
+        }
         // A dependency that fails now and then also makes a test come and go, and that is ENV, not a
         // race in the test. Seen on held-out data, where an external media API broke this test.
         const failed = dependencyFailure(loadFailedRequests);

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

@@ -46,15 +46,18 @@ function history(root, only) {
     runs.sort((a, b) => (a.finishedAt > b.finishedAt ? 1 : -1));
     return { runs, records };
 }
-export function runTrace(cmd) {
+/** The thread and its report, without printing: an MCP tool must return, never write to stdout. */
+export function traceReport(cmd) {
     const found = plans(cmd.root, cmd.only);
     const { runs, records } = history(cmd.root, cmd.name);
     const traced = found.map((plan) => tracePlan(plan, runs, records));
-    const report = renderTrace(traced);
+    return { traced, report: renderTrace(traced), plans: found.length, runs: runs.length };
+}
+export function runTrace(cmd) {
+    const { traced, report, plans: found, runs } = traceReport(cmd);
     console.log(report);
-    if (found.length > 0) {
-        console.error(`\nTraced ${found.length} plan(s) against ${runs.length} kept run(s). No model was called.`);
-    }
+    if (found > 0)
+        console.error(`\nTraced ${found} plan(s) against ${runs} kept run(s). No model was called.`);
     if (cmd.out) {
         mkdirSync(dirname(resolve(cmd.out)), { recursive: true });
         writeFileSync(resolve(cmd.out), `${report}\n`, 'utf8');

package/dist/mcp/server.js

@@ -12,7 +12,7 @@ import { isAbsolute } from 'node:path';
 import { z } from 'zod';
 import { githubCiReport } from './github-report.js';
 import { explainFailure, listDatasets, listFailedRuns, runView, windowView } from './tools.js';
-const server = new McpServer({ name: 'tewip', version: '0.4.0' });
+const server = new McpServer({ name: 'tewip', version: '0.5.0' });
 const readOnly = { readOnlyHint: true, destructiveHint: false, idempotentHint: true };
 const dataset = z.string().optional().describe('Dataset directory relative to the Tewip repo, e.g. "data/real/gutenberg-holdout". Default: data/ (what the reporter collected). See list_datasets.');
 const run = z.string().optional().describe('Run id or a unique part of it. Default: the latest run with failures.');
@@ -77,4 +77,50 @@ server.registerTool('test_plan', {
     const { markdown, out } = await planProject({ feature, root: project, diffRange: diff, urls: urls ?? [] });
     return `${markdown}\n\n(Saved to ${out}. To turn it into verified tests, run \`tewip write\` in that folder.)`;
 }));
+/**
+ * The project's own memory, its thread from requirement to run, and its evidence bundle. All three
+ * read what Tewip already kept for a project on this machine, call no model, and change nothing -
+ * which is what makes them safe to hand an assistant that may call them on its own.
+ */
+const project = z.string().describe('Absolute path of the project folder');
+server.registerTool('recall', {
+    title: 'Has this happened here before?',
+    description: "What this project already concluded about a failure like this one: earlier failures that resemble it, what was decided, by which rule or which person, and the run each came from. Answers from records Tewip kept, never from a guess - and says plainly when nothing resembles it. Use before deciding what a failure means, and for questions like \"have we seen this error before?\".",
+    inputSchema: {
+        question: z.string().describe('An error message, or a question in plain words'),
+        project,
+        test: z.string().optional().describe('Narrow to one test id, when the question is about a particular test'),
+    },
+    annotations: readOnly,
+}, ({ question, project: root, test }) => answer(async () => {
+    if (!isAbsolute(root) || !existsSync(root))
+        throw new Error(`project must be an existing absolute path, got "${root}"`);
+    const { recallReport } = await import('../engine/recall/recall-command.js');
+    return recallReport({ root, question, testId: test }).report;
+}));
+server.registerTool('trace_requirements', {
+    title: 'Is this requirement covered, and is it passing?',
+    description: 'Joins the plans Tewip wrote for a project to the tests that cover them and the runs that attempted them. A scenario counts as covered only when a real test can be named, and as passing only when a real run attempted it; everything else is reported as never run or not covered. Use for "are we ready to release?" and "what is not tested?".',
+    inputSchema: { project, only: z.string().optional().describe('Only plans whose title, ticket or feature contains this') },
+    annotations: readOnly,
+}, ({ project: root, only }) => answer(async () => {
+    if (!isAbsolute(root) || !existsSync(root))
+        throw new Error(`project must be an existing absolute path, got "${root}"`);
+    const { traceReport } = await import('../engine/trace/trace-command.js');
+    return traceReport({ root, only }).report;
+}));
+server.registerTool('next_action', {
+    title: 'What should be done next about a goal?',
+    description: 'Given a goal in plain words - "keep the checkout flow green" - says what Tewip would do next and why, from what it can actually see in the project. The order is fixed and published: a real bug first, then the environment, then flakiness, then anything failing it cannot explain, then a coverage gap. It decides only; it never changes a file.',
+    inputSchema: { goal: z.string().describe('The goal, in plain words'), project },
+    annotations: readOnly,
+}, ({ goal, project: root }) => answer(async () => {
+    if (!isAbsolute(root) || !existsSync(root))
+        throw new Error(`project must be an existing absolute path, got "${root}"`);
+    // observe/decide/render are pure; runPursue prints, which would corrupt the protocol.
+    const { observe, renderPursuit } = await import('../engine/pursue/pursue-command.js');
+    const { decide } = await import('../engine/pursue/policy.js');
+    const observed = observe(root, goal);
+    return renderPursuit(goal, observed, decide(goal, observed), false);
+}));
 await server.connect(new StdioServerTransport());

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tewip-ai",
-  "version": "0.22.0",
+  "version": "0.24.0",
   "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": [
     "test-failures",