tewip-ai 0.12.0 → 0.14.0

package/README.md

@@ -181,10 +181,28 @@ Each reader was checked against real reports published in public repositories, w
 defects were found before release - a Robot timestamp that is not a date, k6's numbers living under
 `values`, and a JMeter line that read "mostly 200" when an assertion had failed.
 
+## Tell it when it is wrong (new)
+
+```bash
+tewip correct diagnosis "checkout charges twice" TEST_DATA "the fixture has stale prices"
+tewip correct flaky "adds an item" fix-now "it is a real race, not flakiness"
+tewip correct security "src/config.ts:12" noise "that is a sample key in a fixture"
+tewip correct --list
+```
+
+Tewip answers with **your** decision from then on, and says it was yours: *"TEST_DATA, confidence
+1.00, source: corrected by a person"*. Corrections live in your project, so they belong to the team;
+the newest one wins, so changing your mind is just saying so again.
+
+**A correction changes what Tewip says, never what it does on its own** — it will not change code,
+quarantine a test or file a ticket because you corrected it.
+
 ## Build a feature, test first (new)
 
 ```bash
 tewip build "naturalsize should take a sep argument that goes between the number and the unit"
+tewip build --issue PROJ-123    # build from the ticket's own description and acceptance criteria
+tewip build "..." --pr          # commit the proved work on its own branch, open a draft PR
 tewip build "..." --dry-run     # prove it, show the patch, leave nothing on disk
 ```
 
@@ -199,6 +217,12 @@ TypeScript, $0.18) and a `sep` argument to **python-humanize** (2 lines, Python,
 its own failing-then-passing test and the project's whole suite still green. Asked for something
 that already worked, it stopped after one model call and kept nothing.
 
+It also refuses a feature that does not belong here at all. Handed a real Apache ticket about a
+Flink HTTP sink, a URL library got an "HTTP sink" built into it - test passing, suite green, every
+proof rule held, because when Tewip writes *both* the test and the code it can always make a
+self-consistent pair pass. So before writing anything it now asks whether the words of the feature
+mean anything in this repository, and refuses for free when they do not.
+
 The old promise was *"it can't touch your code"*. The new one is *"it can't change your code without
 showing you it works"*.
 

package/TEAM-GUIDE.md

@@ -127,6 +127,7 @@ collects environment failures in one issue, and (optionally) opens a fix pull re
 | `tewip spec "<feature>"` | An epic, its user stories and acceptance criteria, grounded in your code; files them in Jira with `--project PROJ --create` | Before the work is broken down |
 | `tewip report report.xml --gate` | The CI command for GitLab, Jenkins, CircleCI, Azure, Bitbucket and the rest: diagnoses the run, comments on the GitLab merge request, and fails the build only on failures that need a person | Your CI is not GitHub Actions |
 | `tewip watch --cmd "npm test"` | Runs your tests when you save a file and explains each failure straight away | While you are writing code |
+| `tewip correct <kind> "<what>" <verdict> "why"` | Tell Tewip it was wrong about anything it decides; it answers with your decision from then on | Whenever you disagree with it |
 | `tewip build "<what it should do>"` | Writes a feature test first, then the code, and keeps it only if the test failed without it and passes with it | You want a small feature built and proved |
 | `tewip review --diff main...HEAD` | Which tests cover your change, which have flaked before, what nothing tests, and what to run first | Before you open a pull request |
 | `tewip flaky --days 30` | Which tests to quarantine, which to fix, what they cost in CI minutes - and when a quarantined one can come back | Monday morning |

package/dist/cli/tewip.js

@@ -67,11 +67,14 @@ Usage:
                                     the GitLab merge request, tells Slack or Teams only when a
                                     failure needs a person, and with --gate fails the build only on
                                     those failures.
-  tewip build "<what it should do>" [--dry-run] [--repairs 2] [--out feature.patch]
+  tewip build "<what it should do>" | --issue PROJ-123 [--dry-run] [--pr] [--out feature.patch]
                                     Writes a feature, test first: the test must fail without the
                                     code and pass with it, and every test that was passing must
                                     still pass - otherwise everything goes back byte for byte.
-                                    Nothing is committed.
+      --issue PROJ-123              Build from the ticket itself: its description and acceptance
+                                    criteria. Works with a public tracker without an account.
+      --pr                          Commit the proved work on a branch of its own and open a draft
+                                    pull request. Never merges, never commits to your branch.
   tewip review [--diff main...HEAD] [--out review.md]
                                     Before anyone reads the diff: which tests cover this change,
                                     which of them have flaked before, what has gone wrong in these
@@ -99,6 +102,11 @@ Usage:
                                     Compare a Figma frame against the running page: the words the
                                     design specifies and the controls its layer names imply. Says
                                     "the design says X, the page says Y". No model, no cost.
+  tewip correct <kind> "<what>" <verdict> ["why"] | --list
+                                    Tell Tewip it was wrong, about anything it decides: a diagnosis,
+                                    a flaky verdict, a security finding, a design difference, a
+                                    refused build. It answers with your decision from then on, and
+                                    says it was yours. It never acts on a correction by itself.
   tewip mcp                         Serve Tewip over MCP (stdio) for an editor or AI assistant.
   tewip --version                   Print the version.
 
@@ -262,9 +270,24 @@ async function main() {
             return;
         }
         case 'build': {
-            const feature = args.filter((a, i) => !a.startsWith('--') && !['--repairs', '--out', '--max-lines'].includes(args[i - 1] ?? '')).join(' ').trim();
+            const typed = args.filter((a, i) => !a.startsWith('--') && !['--repairs', '--out', '--max-lines', '--issue'].includes(args[i - 1] ?? '')).join(' ').trim();
+            const issueKey = flag(args, 'issue');
+            let feature = typed;
+            let issueTitle = '';
+            if (issueKey) {
+                // A ticket says what was asked for better than a sentence typed twice.
+                const { Jira, jiraFromEnv, jiraHelp } = await import('../engine/work/jira.js');
+                const { featureFromIssue } = await import('../engine/work/jira-command.js');
+                const config = jiraFromEnv();
+                if (!config)
+                    throw new Error(jiraHelp());
+                const issue = await new Jira(config).issue(issueKey);
+                console.error(`Read ${issue.key} (${issue.type}, ${issue.status})${issue.acceptanceCriteria ? ' with its acceptance criteria' : ''}.`);
+                issueTitle = `${issue.key}: ${issue.summary}`;
+                feature = [featureFromIssue(issue), typed].filter(Boolean).join('\n\n');
+            }
             if (!feature)
-                throw new Error('usage: tewip build "<what the feature should do>" [--dry-run] [--repairs 2] [--out feature.patch]');
+                throw new Error('usage: tewip build "<what the feature should do>" | --issue PROJ-123 [--dry-run] [--pr] [--out feature.patch]');
             const { runBuild, renderBuild } = await import('../engine/build/build-command.js');
             const dryRun = args.includes('--dry-run');
             const result = await runBuild({
@@ -276,9 +299,27 @@ async function main() {
                 out: flag(args, 'out'),
             });
             console.log(`
-${renderBuild(result, feature, dryRun)}`);
-            if (result.status !== 'built')
+${renderBuild(result, issueTitle || feature, dryRun)}`);
+            if (result.status !== 'built') {
                 process.exitCode = 1;
+                return;
+            }
+            if (args.includes('--pr')) {
+                if (dryRun)
+                    throw new Error('--pr and --dry-run ask for opposite things: one keeps the work, the other puts it back.');
+                const { proposePullRequest } = await import('../engine/build/propose-pr.js');
+                const proposed = proposePullRequest({
+                    root: process.cwd(),
+                    files: result.files,
+                    title: (issueTitle || feature.split('\n')[0]).slice(0, 72),
+                    body: result.why,
+                    issue: issueKey,
+                });
+                console.log(`
+${proposed.status === 'opened' ? 'Opened a draft pull request.' : proposed.status === 'committed' ? `Committed on ${proposed.branch}.` : 'No pull request was opened.'}`);
+                for (const line of proposed.next)
+                    console.log(`  ${line}`);
+            }
             return;
         }
         case 'review': {
@@ -361,6 +402,20 @@ ${renderBuild(result, feature, dryRun)}`);
             // it in CI without the build going red over a design decision nobody has made yet.
             return;
         }
+        case 'correct': {
+            const { runCorrect } = await import('../engine/learn/correct-command.js');
+            const words = args.filter((a) => !a.startsWith('--'));
+            console.log(runCorrect({
+                root: process.cwd(),
+                kind: words[0] ?? '',
+                key: words[1],
+                verdict: words[2],
+                reason: words.slice(3).join(' ') || undefined,
+                list: args.includes('--list'),
+                by: flag(args, 'by'),
+            }));
+            return;
+        }
         case 'mcp':
             // An editor starts this from any folder, and an installed tool's own folder may be read-only:
             // the AI answer cache goes to the user's home folder, which is always writable.

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

@@ -53,6 +53,57 @@ export function definingSources(root, feature, limit = 3) {
     }
     return scored.sort((a, b) => b.score - a.score).slice(0, limit).map((s) => s.file);
 }
+/**
+ * Does this feature belong in this project at all?
+ *
+ * Found by trying it: a real Apache ticket about a Flink HTTP sink was handed to a URL library, and
+ * Tewip built an "HTTP sink" into it - 28 lines, its own test passing, the suite green. Every proof
+ * rule held, because when Tewip writes both the test and the code it can always make a
+ * self-consistent pair pass. Nothing else referenced the invented API, so nothing else could break.
+ *
+ * The missing check is the obvious one: the words of the feature have to mean something here. A
+ * project's own vocabulary is its file names and what it exports, and a feature that shares almost
+ * none of it is a feature for some other repository.
+ */
+export function belongsHere(root, feature, sources, testNames) {
+    const stop = new Set(['should', 'when', 'with', 'that', 'this', 'from', 'into', 'have', 'been', 'will', 'must', 'also', 'able', 'given', 'then', 'there', 'their', 'which', 'while', 'where', 'after', 'before', 'value', 'values', 'return', 'returns', 'support', 'supports', 'accept', 'accepts', 'option', 'options', 'default', 'behaviour', 'behavior', 'feature', 'example', 'instead', 'without']);
+    const words = (text) => new Set((text.toLowerCase().match(/[a-z][a-z0-9]{3,}/g) ?? []).filter((w) => !stop.has(w)));
+    const asked = [...words(feature)];
+    if (asked.length < 3)
+        return { ok: true, why: '' };
+    const vocabulary = new Set();
+    for (const s of sources)
+        for (const w of words(`${s.file} ${s.content.slice(0, 20_000)}`))
+            vocabulary.add(w);
+    for (const name of testNames)
+        for (const w of words(name))
+            vocabulary.add(w);
+    // The names of a project's files are not its vocabulary: "naturalsize" lives inside filesize.py,
+    // not in its name, and judging by names alone refused a feature that really did belong here.
+    let read = 0;
+    for (const file of sourceFiles(root, 1200)) {
+        if (!CODE_FILE.test(file) || read >= 60)
+            continue;
+        read++;
+        try {
+            for (const w of words(`${basename(file)} ${readFileSync(file, 'utf8').slice(0, 20_000)}`))
+                vocabulary.add(w);
+        }
+        catch {
+            // unreadable here is simply one less file of vocabulary
+        }
+    }
+    if (vocabulary.size === 0)
+        return { ok: true, why: '' };
+    const shared = asked.filter((w) => vocabulary.has(w));
+    const share = shared.length / asked.length;
+    if (share >= 0.2)
+        return { ok: true, why: '' };
+    return {
+        ok: false,
+        why: `almost nothing in this project mentions what that describes (${shared.length} of ${asked.length} of its words appear here${shared.length ? `: ${shared.slice(0, 5).join(', ')}` : ''}). If this is the right repository, say the feature in its own words - the names of the functions and files it should change. Tewip can make a test of its own invention pass in any project, and that would prove nothing.`,
+    };
+}
 /** A test file name in the project's own shape, that does not collide with an existing one. */
 function testPathFor(framework, feature) {
     const stem = feature.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '').split('-').slice(0, 4).join('-') || 'feature';
@@ -88,6 +139,10 @@ export async function runBuild(cmd) {
         testNames: tests.tests,
     };
     const log = [`framework: ${framework.label}`, `source files read: ${ctx.sources.map((s) => s.file).join(', ') || 'none found'}`];
+    // Before anything is written: is this even a feature for this repository?
+    const belongs = belongsHere(root, cmd.feature, ctx.sources, ctx.testNames);
+    if (!belongs.ok)
+        return { status: 'not-this-project', why: belongs.why, files: [], diff: '', log: [...log, belongs.why] };
     const workspace = new Workspace(root);
     const maxLines = cmd.maxLines ?? 120;
     const stop = (status, why) => {

package/dist/engine/build/propose-pr.js

@@ -0,0 +1,88 @@
+// Turning proved work into a pull request - the last step of the loop, and the one where Tewip
+// touches somebody's repository, so it is the most careful.
+//
+// Three rules, enforced here rather than promised:
+//   it only ever pushes a new branch of its own, never yours;
+//   it never merges, and opens the request as a draft so nobody can merge it by reflex;
+//   it describes exactly what was proved and what was not, because a pull request nobody can check
+//   is worse than a patch file.
+//
+// The work must already be proved before anything reaches this file. Nothing here runs a test or
+// decides anything; it commits what was verified and opens the request.
+import { spawnSync } from 'node:child_process';
+const run = (cwd, command, args) => {
+    const r = spawnSync(command, args, { cwd, encoding: 'utf8', timeout: 120_000, maxBuffer: 16 * 1024 * 1024 });
+    return { ok: r.status === 0, out: `${r.stdout ?? ''}${r.stderr ?? ''}`.trim() };
+};
+/** A branch name a person can read at a glance, and that cannot collide with an existing one. */
+export function branchNameFor(title, now = new Date()) {
+    const stem = title.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '').split('-').slice(0, 6).join('-') || 'change';
+    return `tewip/${stem}-${now.toISOString().slice(2, 16).replace(/\D/g, '')}`;
+}
+/** The pull request body: what was built, and precisely how far the proof goes. */
+export function requestBody(body, files, issue) {
+    return [
+        body,
+        '',
+        `Files: ${files.map((f) => `\`${f}\``).join(', ')}`,
+        issue ? `From: ${issue}` : '',
+        '',
+        '---',
+        '',
+        'Written by Tewip and kept only because it was proved: the test failed without this change and',
+        'passes with it, and every test that was passing still passes.',
+        '',
+        'What that does **not** say: whether this is the design you want, whether it is the right place',
+        'for it, or whether it is complete. That is what your review is for. This is a draft on a branch',
+        'of its own; Tewip never merges anything.',
+    ]
+        .filter((line) => line !== '')
+        .join('\n');
+}
+/**
+ * Commits the proved files on a fresh branch and opens a draft pull request with the `gh` CLI the
+ * developer is already logged into. When there is no `gh`, the branch is still pushed and the
+ * command to open the request by hand is printed - half a job done is better than a silent failure.
+ */
+export function proposePullRequest(input) {
+    const { root, files } = input;
+    if (files.length === 0)
+        return { status: 'refused', next: ['there was nothing to commit'] };
+    if (!run(root, 'git', ['rev-parse', '--git-dir']).ok)
+        return { status: 'refused', next: ['this is not a git checkout, so there is no branch to open a request from'] };
+    const branch = branchNameFor(input.title);
+    const base = run(root, 'git', ['rev-parse', '--abbrev-ref', 'HEAD']).out.trim() || 'main';
+    // A branch of Tewip's own, from wherever the person is standing. Their branch is never committed to.
+    const made = run(root, 'git', ['checkout', '-b', branch]);
+    if (!made.ok)
+        return { status: 'refused', next: [`could not create the branch ${branch}: ${made.out.slice(0, 200)}`] };
+    const added = run(root, 'git', ['add', '--', ...files]);
+    if (!added.ok) {
+        run(root, 'git', ['checkout', base]);
+        return { status: 'refused', next: [`could not stage the files: ${added.out.slice(0, 200)}`] };
+    }
+    // Only Tewip's own files are committed: anything else the person had in progress stays theirs.
+    const committed = run(root, 'git', ['commit', '-m', input.title, '-m', requestBody(input.body, files, input.issue), '--only', '--', ...files]);
+    if (!committed.ok) {
+        run(root, 'git', ['checkout', base]);
+        return { status: 'refused', next: [`could not commit: ${committed.out.slice(0, 200)}`] };
+    }
+    const next = [];
+    const pushed = run(root, 'git', ['push', '-u', 'origin', branch]);
+    if (!pushed.ok) {
+        return {
+            status: 'committed',
+            branch,
+            next: [`the work is committed on ${branch}, but pushing failed: ${pushed.out.slice(0, 200)}`, `push it yourself with: git push -u origin ${branch}`],
+        };
+    }
+    const gh = run(root, 'gh', ['pr', 'create', '--draft', '--base', base, '--head', branch, '--title', input.title, '--body', requestBody(input.body, files, input.issue)]);
+    if (gh.ok) {
+        const url = (gh.out.match(/https:\/\/\S+/) ?? [])[0];
+        return { status: 'opened', branch, url, next: [`review it: ${url ?? branch}`, `back to where you were: git checkout ${base}`] };
+    }
+    next.push(`${branch} is pushed, but the pull request was not opened: ${gh.out.slice(0, 200)}`);
+    next.push(`open it with: gh pr create --draft --base ${base} --head ${branch}`);
+    next.push(`back to where you were: git checkout ${base}`);
+    return { status: 'committed', branch, next };
+}

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

@@ -8,6 +8,7 @@ import { readPages } from '../quality/grounding.js';
 import { Figma, figmaHelp, figmaTokenFromEnv, parseFigmaUrl, topFrames } from './figma.js';
 import { frameChecks } from './frame.js';
 import { compareDesign, renderDrift } from './drift.js';
+import { loadVerdicts, saidByAPerson, verdictFor } from '../learn/verdicts.js';
 /** A saved Figma response, in any of the shapes Figma's API returns. */
 function fromFile(path) {
     const raw = JSON.parse(readFileSync(path, 'utf8'));
@@ -70,8 +71,22 @@ export async function runDesign(cmd) {
         console.log(`\nThe page was not read, so nothing was compared: ${pageNote ?? 'unknown reason'}`);
         return [];
     }
-    const drifts = compareDesign(checks, pages[0].aria);
-    const report = renderDrift(drifts, design, cmd.url);
+    const found = compareDesign(checks, pages[0].aria);
+    // A difference a person has already looked at and accepted is not reported again as a surprise.
+    const corrections = loadVerdicts(cmd.root);
+    const settled = [];
+    const drifts = found.map((d) => {
+        const key = `${d.check.role ?? d.check.kind} ${d.check.name}`.trim();
+        const said = verdictFor('design', key, corrections) ?? verdictFor('design', d.check.name, corrections);
+        if (!said || said.verdict !== 'not-a-difference')
+            return d;
+        settled.push(`${key}: ${saidByAPerson(said)}`);
+        return { ...d, verdict: 'met' };
+    });
+    const alreadySettled = settled.length
+        ? ['', `${settled.length} difference(s) your team has already settled, so they are not reported:`, ...settled.map((s) => `  - ${s}`)].join('\n')
+        : '';
+    const report = [renderDrift(drifts, design, cmd.url), alreadySettled].filter(Boolean).join('\n');
     console.log(report);
     if (note)
         console.log(`\n${note}`);

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

@@ -6,6 +6,7 @@ import { join, resolve } from 'node:path';
 import { datasetFiles, readRunSummaries, readTriageRecords } from '../../reporters/store.js';
 import { flakyTests, readyToRelease, weeklyCost } from './flaky.js';
 import { applyQuarantine, frameworkOf, quarantineFor } from './quarantine.js';
+import { loadVerdicts, saidByAPerson, verdictFor } from '../learn/verdicts.js';
 const DAY_MS = 24 * 60 * 60 * 1000;
 const minutes = (ms) => `${(ms / 60_000).toFixed(1)} CI min`;
 function projects(root, only) {
@@ -31,7 +32,14 @@ export async function runFlaky(cmd) {
         const history = datasetFiles(join(cmd.root, '.tewip', 'history', name));
         const records = readTriageRecords(history.triage);
         const runs = readRunSummaries(history.runs);
-        const tests = flakyTests(records, runs, { since });
+        const computed = flakyTests(records, runs, { since });
+        // What a person already decided about a test wins over what Tewip works out, and is shown as
+        // theirs: the argument is had once, not every Monday.
+        const corrections = loadVerdicts(cmd.root);
+        const tests = computed.map((test) => {
+            const said = verdictFor('flaky', test.title, corrections) ?? verdictFor('flaky', test.testId, corrections);
+            return said ? { ...test, verdict: said.verdict, why: `${saidByAPerson(said)} (Tewip had said ${test.verdict})` } : test;
+        });
         if (tests.length === 0)
             continue;
         all.push(...tests);

package/dist/engine/learn/correct-command.js

@@ -0,0 +1,88 @@
+// `tewip correct`: the one place a person tells Tewip it was wrong, about anything.
+//
+// A diagnosis can already be corrected where Tewip posts it in CI. This is the same thing for
+// everything else it decides, and on a person's own machine, where most of the disagreeing happens.
+import { existsSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { ROOT_CAUSES } from '../../reporters/types.js';
+import { datasetFiles, readTriageRecords } from '../../reporters/store.js';
+import { loadCorrections, saveCorrections } from '../corrections.js';
+import { errorShape } from '../signature.js';
+import { isVerdictWord, loadVerdicts, saidByAPerson, saveVerdict, verdictHelp, VERDICT_WORDS } from './verdicts.js';
+const KINDS = Object.keys(VERDICT_WORDS);
+/**
+ * The failure a title names, and the history folder it lives in. The folder matters: corrections are
+ * kept beside the runs of that project, which is where the engine looks for them - an earlier
+ * version wrote them one directory up, where nothing ever read them.
+ */
+function findRecord(root, key) {
+    const dir = join(root, '.tewip', 'history');
+    if (!existsSync(dir))
+        return null;
+    for (const project of readdirSync(dir)) {
+        const historyDir = join(dir, project);
+        const records = readTriageRecords(datasetFiles(historyDir).triage);
+        const found = [...records].reverse().find((r) => r.testId.toLowerCase().includes(key.trim().toLowerCase()));
+        if (found)
+            return { record: found, historyDir };
+    }
+    return null;
+}
+export function runCorrect(cmd) {
+    const who = cmd.by ?? process.env.USER ?? process.env.USERNAME ?? 'someone on the team';
+    if (cmd.list) {
+        const verdicts = loadVerdicts(cmd.root);
+        const historyRoot = join(cmd.root, '.tewip', 'history');
+        const diagnoses = (existsSync(historyRoot) ? readdirSync(historyRoot) : []).flatMap((project) => loadCorrections(join(historyRoot, project)));
+        if (verdicts.length === 0 && diagnoses.length === 0)
+            return 'Nothing has been corrected yet.\n\n' + verdictHelp();
+        const lines = [`${verdicts.length + diagnoses.length} correction(s), newest last:`, ''];
+        for (const v of verdicts)
+            lines.push(`  ${v.kind.padEnd(9)} ${v.key} -> ${v.verdict}  (${saidByAPerson(v)})`);
+        for (const d of diagnoses)
+            lines.push(`  diagnosis ${d.testId} -> ${d.category}  (${d.by}${d.reason ? `: ${d.reason}` : ''})`);
+        return lines.join('\n');
+    }
+    const kind = cmd.kind?.trim().toLowerCase() ?? '';
+    if (!cmd.key || !cmd.verdict)
+        throw new Error(`usage: tewip correct <${[...KINDS, 'diagnosis'].join('|')}> "<what it is about>" <verdict> ["why"]\n\n${verdictHelp()}`);
+    // A diagnosis is corrected into the same store the CI path writes, so both ends agree.
+    if (kind === 'diagnosis') {
+        const category = cmd.verdict.trim().toUpperCase();
+        if (!ROOT_CAUSES.includes(category))
+            throw new Error(`"${cmd.verdict}" is not a category. They are: ${ROOT_CAUSES.join(', ')}`);
+        const found = findRecord(cmd.root, cmd.key);
+        if (!found)
+            throw new Error(`no failure of a test called "${cmd.key}" is in the history Tewip has kept here. Run \`tewip explain\` on the report first, so there is something to correct.`);
+        const { record, historyDir } = found;
+        const correction = {
+            schemaVersion: 1,
+            testId: record.testId,
+            // Stored exactly as the matcher compares it: a truncated shape can never equal a real one.
+            errorShape: errorShape(record.errorMessage),
+            category,
+            by: who,
+            at: new Date().toISOString(),
+            reason: cmd.reason,
+            source: 'tewip correct',
+            wasCategory: record.diagnosis?.category,
+        };
+        saveCorrections(historyDir, [correction]);
+        return [
+            `Noted: "${record.testId}" is ${category}${record.diagnosis?.category ? `, not ${record.diagnosis.category}` : ''}.`,
+            'Tewip will answer with your decision the next time that test fails the same way, and say it was yours.',
+        ].join('\n');
+    }
+    if (!KINDS.includes(kind))
+        throw new Error(`"${cmd.kind}" is not something Tewip decides. It decides: ${[...KINDS, 'diagnosis'].join(', ')}.\n\n${verdictHelp()}`);
+    const verdictKind = kind;
+    if (!isVerdictWord(verdictKind, cmd.verdict)) {
+        throw new Error(`"${cmd.verdict}" is not one of the answers a ${verdictKind} verdict takes. They are: ${VERDICT_WORDS[verdictKind].join(', ')}.`);
+    }
+    const saved = saveVerdict(cmd.root, { kind: verdictKind, key: cmd.key, verdict: cmd.verdict.trim().toLowerCase(), reason: cmd.reason ?? '', by: who });
+    return [
+        `Noted: ${verdictKind} "${cmd.key}" is ${saved.verdict}.`,
+        'Tewip will say that from now on, and say it was your decision rather than its own.',
+        'It will not act on it by itself: a correction changes what it says, never what it does.',
+    ].join('\n');
+}

package/dist/engine/learn/verdicts.js

@@ -0,0 +1,71 @@
+// The LEARN step, everywhere.
+//
+// A person could already correct a diagnosis by replying under Tewip's own comment in CI, and Tewip
+// answers with their decision from then on. Every other verdict it gives - this test should be
+// quarantined, this secret is a real risk, the page has drifted from the design, this feature
+// cannot be built here - had no such path, so the same argument had to be had again every week.
+//
+// This is that path, for all of them, and it keeps the properties that made the first one worth
+// having: a correction is written by a person, it is stored with the project rather than inside
+// Tewip, it says who and why, and **it never authorises an action on its own**. Deciding that a
+// failure is a real bug does not make Tewip change code; deciding a flaky test is really broken
+// does not make it un-quarantine anything. It changes what Tewip *says*, which is what a person
+// was disagreeing with.
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { appendJsonl, readJsonl } from '../../reporters/store.js';
+/** The words each kind accepts, so a typo is caught rather than stored and silently ignored. */
+export const VERDICT_WORDS = {
+    flaky: ['quarantine', 'fix-now', 'watch', 'release'],
+    security: ['real-risk', 'not-reachable', 'noise', 'accepted'],
+    design: ['real', 'not-a-difference'],
+    build: ['belongs-here', 'not-this-project'],
+    review: ['covers', 'does-not-cover'],
+};
+export const VERDICTS_FILE = 'verdicts.jsonl';
+const fileIn = (root) => join(root, '.tewip', VERDICTS_FILE);
+export function loadVerdicts(root) {
+    const path = fileIn(root);
+    return existsSync(path) ? readJsonl(path) : [];
+}
+/** Adds one correction, replacing an earlier one about the same thing. */
+export function saveVerdict(root, correction) {
+    const entry = { schemaVersion: 1, at: correction.at ?? new Date().toISOString(), ...correction };
+    appendJsonl(fileIn(root), [entry]);
+    return entry;
+}
+const same = (a, b) => a.trim().toLowerCase() === b.trim().toLowerCase();
+/**
+ * The person's answer about this thing, or null. The newest wins, so a team that changes its mind
+ * simply says so again rather than editing a file.
+ */
+export function verdictFor(kind, key, corrections) {
+    const matching = corrections.filter((c) => c.kind === kind && (same(c.key, key) || key.toLowerCase().endsWith(c.key.trim().toLowerCase())));
+    return matching.length > 0 ? matching[matching.length - 1] : null;
+}
+/** What a corrected verdict is shown as, so nobody mistakes a person's decision for Tewip's. */
+export function saidByAPerson(correction) {
+    const when = correction.at.slice(0, 10);
+    return `${correction.by} decided this on ${when}${correction.reason ? `: ${correction.reason}` : ''}`;
+}
+/** Whether a word is one this kind of verdict uses. */
+export function isVerdictWord(kind, word) {
+    return VERDICT_WORDS[kind].includes(word.trim().toLowerCase());
+}
+export function verdictHelp() {
+    return [
+        'Correct something Tewip said, and it will answer with your decision from now on:',
+        '',
+        '  tewip correct flaky "adds an item to the cart" fix-now "it is a real race, not flakiness"',
+        '  tewip correct security "src/config.ts:12" noise "that is a sample key in a fixture"',
+        '  tewip correct design "button Sign in" not-a-difference "we renamed it on purpose"',
+        '  tewip correct build "an HTTP sink" belongs-here "this really is the right repository"',
+        '',
+        'The words each kind takes:',
+        ...Object.entries(VERDICT_WORDS).map(([kind, words]) => `  ${kind.padEnd(9)} ${words.join(', ')}`),
+        '',
+        'A correction changes what Tewip says, never what it does on its own: it will not change code,',
+        'quarantine a test or file a ticket because you corrected it.',
+        'They are kept in .tewip/verdicts.jsonl, with the project, so the whole team shares them.',
+    ].join('\n');
+}

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

@@ -9,6 +9,7 @@ import { auditDependencies } from './deps.js';
 import { scanSecrets, sourceFiles } from './secrets.js';
 import { readAccepted, triageDependency, triageSecret, triageWeb, worstFirst } from './triage.js';
 import { isLocal, scanWeb } from './web.js';
+import { loadVerdicts, saidByAPerson, verdictFor } from '../learn/verdicts.js';
 import { readZapReport, zapAvailable, zapInstructions } from './zap.js';
 const CODE = /\.(?:[cm]?[jt]sx?|py|rb|go|java|kt|cs|php|rs|vue|svelte)$/;
 export function renderSecurity(items, checked, notChecked, root) {
@@ -97,6 +98,14 @@ export async function runSecure(cmd) {
     else if (cmd.url) {
         notChecked.push(`a full web scan. Tewip's own check is passive; for the deep one: ${zapInstructions(cmd.url, zapAvailable(root))}`);
     }
+    // A person's decision about a finding wins over Tewip's, and says whose it was.
+    const corrections = loadVerdicts(root);
+    const decided = items.map((item) => {
+        const said = verdictFor('security', item.where, corrections) ?? verdictFor('security', item.title, corrections);
+        return said ? { ...item, verdict: said.verdict, why: `${saidByAPerson(said)} (Tewip had said ${item.verdict})` } : item;
+    });
+    items.length = 0;
+    items.push(...decided);
     items.sort(worstFirst);
     const report = renderSecurity(items, checked, notChecked, root);
     console.log(report);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tewip-ai",
-  "version": "0.12.0",
+  "version": "0.14.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",