tewip-ai 0.4.0

package/dist/eval/harvest/harvest.js

@@ -0,0 +1,117 @@
+// Harvests every finished Playwright CI run (passes and failures) of a public GitHub repo in
+// a date window into data/real/<source>/ (gitignored): triage.jsonl + runs.jsonl in the
+// reporter's format, attachments, and runs-meta.jsonl with GitHub facts for labelling.
+// Passing runs matter: without them every test's history would look like "always fails".
+// Usage: node eval/harvest/harvest.ts <source> --from YYYY-MM-DD --to YYYY-MM-DD [--dataset name] [--max-runs N] [--concurrency 4]
+import { join } from 'node:path';
+import { appendJsonl, datasetFiles, readJsonl } from '../../reporters/store.js';
+import { importBlobArtifacts } from '../../engine/import/blob.js';
+import { downloadArtifact, ghApi } from './gh.js';
+/** artifact: name prefix; every live artifact of a run starting with it is merged into that run. */
+export const SOURCES = {
+    gutenberg: { repo: 'WordPress/gutenberg', workflow: 'end2end-test.yml', artifact: 'blob-reports-merged' },
+    // Supabase Studio: one blob-report-next-N artifact per shard (the TanStack build runs the same tests and is left out).
+    supabase: { repo: 'supabase/supabase', workflow: 'studio-e2e-test.yml', artifact: 'blob-report-next-' },
+    // Penpot integration tests: one integration-blob-report-N per shard, kept a few days.
+    penpot: { repo: 'penpot/penpot', workflow: 'tests-integration.yml', artifact: 'integration-blob-report-' },
+    // Ghost uploads blob reports for failed runs only, so its history has no passing runs.
+    ghost: { repo: 'TryGhost/Ghost', workflow: 'ci.yml', artifact: 'blob-report-Main-' },
+    // JupyterLab's Galata UI tests: every run merges its shards into one artifact.
+    jupyterlab: { repo: 'jupyterlab/jupyterlab', workflow: 'galata.yml', artifact: 'galata-blobs-merged' },
+    // LXD UI: one artifact per browser and cluster mode.
+    lxdui: { repo: 'canonical/lxd-ui', workflow: 'pr.yaml', artifact: 'test-blob-report-' },
+    // Nextcloud server's Playwright suite.
+    nextcloud: { repo: 'nextcloud/server', workflow: 'playwright.yml', artifact: 'blob-report' },
+};
+const flag = (name, fallback) => {
+    const i = process.argv.indexOf(`--${name}`);
+    const value = i > 0 ? process.argv[i + 1] : undefined;
+    if (value === undefined && fallback === undefined)
+        throw new Error(`missing --${name}`);
+    return value ?? fallback;
+};
+/** runs-meta.jsonl of a dataset under data/real/ (named after the source unless --dataset is given). */
+export const metaFile = (dataset) => join(datasetFiles(`data/real/${dataset}`).dir, 'runs-meta.jsonl');
+async function listRuns(repo, workflow, from, to) {
+    const runs = [];
+    for (const conclusion of ['success', 'failure']) {
+        for (let page = 1; page <= 10; page++) {
+            const { workflow_runs } = await ghApi(`repos/${repo}/actions/workflows/${workflow}/runs?status=${conclusion}&created=${from}..${to}&per_page=100&page=${page}`);
+            runs.push(...workflow_runs);
+            if (workflow_runs.length < 100)
+                break;
+        }
+    }
+    return runs.sort((a, b) => a.created_at.localeCompare(b.created_at));
+}
+async function main() {
+    const source = process.argv[2];
+    const config = SOURCES[source];
+    if (!config)
+        throw new Error(`usage: harvest.ts <${Object.keys(SOURCES).join('|')}> --from YYYY-MM-DD --to YYYY-MM-DD`);
+    const from = flag('from');
+    const to = flag('to');
+    const maxRuns = Number(flag('max-runs', '1000'));
+    const concurrency = Number(flag('concurrency', '4'));
+    // A separate dataset name keeps e.g. a held-out window apart from the data used for tuning.
+    const dataset = flag('dataset', source);
+    const files = datasetFiles(`data/real/${dataset}`);
+    // Only successful imports count as done; skipped runs are retried on the next harvest.
+    const known = new Set(readJsonl(metaFile(dataset)).filter((m) => m.imported).map((m) => m.runId));
+    const runs = (await listRuns(config.repo, config.workflow, from, to))
+        .filter((r) => !known.has(`${source}-${r.id}-a${r.run_attempt}`))
+        .slice(0, maxRuns);
+    console.log(`[harvest] ${runs.length} run(s) to import (${runs.filter((r) => r.conclusion === 'failure').length} failed)`);
+    let done = 0;
+    let records = 0;
+    const importOne = async (run) => {
+        const runId = `${source}-${run.id}-a${run.run_attempt}`;
+        const meta = {
+            runId,
+            githubRunId: run.id,
+            attempt: run.run_attempt,
+            sha: run.head_sha,
+            branch: run.head_branch,
+            event: run.event,
+            prNumbers: run.pull_requests.map((p) => p.number),
+            createdAt: run.created_at,
+            conclusion: run.conclusion,
+            imported: false,
+        };
+        try {
+            const { artifacts } = await ghApi(`repos/${config.repo}/actions/runs/${run.id}/artifacts?per_page=100`);
+            const matching = artifacts.filter((a) => a.name.startsWith(config.artifact) && !a.expired);
+            if (matching.length === 0) {
+                appendJsonl(metaFile(dataset), [{ ...meta, skipReason: `no live ${config.artifact} artifact` }]);
+                return;
+            }
+            const zips = [];
+            for (const a of matching)
+                zips.push([a.name, await downloadArtifact(config.repo, a.id)]);
+            const result = importBlobArtifacts(zips, { runId, gitSha: run.head_sha, branch: run.head_branch }, join(files.dir, 'files', String(run.id)));
+            appendJsonl(files.triage, result.records);
+            appendJsonl(files.runs, [result.summary]);
+            appendJsonl(metaFile(dataset), [
+                { ...meta, imported: true, failureRecords: result.records.length, ...(result.skippedShards.length ? { skipReason: `corrupt shard(s): ${result.skippedShards.join(', ')}` } : {}) },
+            ]);
+            records += result.records.length;
+        }
+        catch (error) {
+            appendJsonl(metaFile(dataset), [{ ...meta, skipReason: `import failed: ${String(error).slice(0, 200)}` }]);
+            console.warn(`[harvest] ${runId} skipped: ${String(error).slice(0, 200)}`);
+        }
+        finally {
+            done++;
+            if (done % 20 === 0 || done === runs.length)
+                console.log(`[harvest] ${done}/${runs.length} runs processed, ${records} failure record(s) so far`);
+        }
+    };
+    let next = 0;
+    await Promise.all(Array.from({ length: Math.min(concurrency, runs.length) }, async () => {
+        while (next < runs.length)
+            await importOne(runs[next++]);
+    }));
+    console.log(`[harvest] ${source}: done, ${records} failure record(s) into ${files.dir}`);
+}
+if (import.meta.main)
+    await main();

package/dist/mcp/github-report.js

@@ -0,0 +1,50 @@
+// Fetches the latest Tewip report that the GitHub Action uploaded for a repository,
+// pull request or branch, so an assistant can answer "why did CI fail on my PR?" without
+// anyone opening the Actions page. Uses the gh CLI's login; read-only.
+import { readZipBuffer } from '../engine/trace/zip.js';
+import { downloadArtifact, ghApi } from '../eval/harvest/gh.js';
+import { cap } from './tools.js';
+/** "tewip-report" or "tewip-report-<suite>"; "triage-agent-report" is what versions before the rename uploaded. */
+const REPORT = /^(?:tewip|triage-agent)-report(-.+)?$/;
+/** How many recent runs to look through for one that uploaded a report. */
+const RUNS_TO_SEARCH = 30;
+/**
+ * The newest workflow run on the branch that uploaded Tewip reports, and those reports.
+ * Looked up run by run rather than across all of a repository's artifacts, which in a busy
+ * repository are mostly other workflows' and would push the report out of the first page.
+ */
+async function latestReports(repo, branch) {
+    const query = `per_page=${RUNS_TO_SEARCH}${branch ? `&branch=${encodeURIComponent(branch)}` : ''}`;
+    const { workflow_runs: runs } = await ghApi(`repos/${repo}/actions/runs?${query}`);
+    for (const run of runs) {
+        const { artifacts } = await ghApi(`repos/${repo}/actions/runs/${run.id}/artifacts?per_page=100`);
+        const reports = artifacts.filter((a) => REPORT.test(a.name) && !a.expired);
+        if (reports.length > 0)
+            return { run, artifacts: reports.sort((a, b) => a.name.localeCompare(b.name)) };
+    }
+    return null;
+}
+export async function githubCiReport(repo, pr, branch) {
+    const head = pr ? (await ghApi(`repos/${repo}/pulls/${pr}`)).head.ref : branch;
+    const target = pr ? `PR #${pr} (${head})` : head ? `branch ${head}` : 'any branch';
+    const found = await latestReports(repo, head);
+    if (!found)
+        return `No Tewip report for ${repo}, ${target} in its last ${RUNS_TO_SEARCH} workflow runs. Is the Tewip action installed in that repository's CI workflow, and has it run since?`;
+    const sections = [];
+    for (const artifact of found.artifacts) {
+        const files = readZipBuffer(await downloadArtifact(repo, artifact.id), (n) => n.endsWith('.md') || n === 'triage.json');
+        const text = (name) => files.get(name)?.toString('utf8') ?? '';
+        const bundle = JSON.parse(text('triage.json') || '{}');
+        const envCount = (bundle.items ?? []).filter((i) => i.diagnosis.category === 'ENV').length;
+        const suite = artifact.name.replace(/^(?:tewip|triage-agent)-report-?/, '');
+        sections.push([
+            `# Tewip CI report: ${repo}, ${target}${suite ? ` - suite "${suite}"` : ''}`,
+            `Run: ${bundle.runUrl ?? found.run.html_url} · commit \`${(bundle.sha ?? found.run.head_sha).slice(0, 8)}\` · generated ${bundle.generatedAt ?? artifact.created_at}${bundle.fixPr ? ` · verified fix PR: ${bundle.fixPr}` : ''}`,
+            text('pr-comment.md'),
+            envCount > 0 ? text('infra.md') : '',
+        ]
+            .filter(Boolean)
+            .join('\n\n'));
+    }
+    return cap(sections.join('\n\n---\n\n'));
+}

package/dist/mcp/server.js

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+// MCP server for Tewip: lets any MCP-capable AI assistant (Claude Code, Claude Desktop,
+// Cursor, VS Code agent mode, ...) ask about Playwright test failures and get the same
+// diagnoses, next actions and role views the agent produces in CI.
+// Read-only by design, except test_plan, which saves the plan it returns in the project's .tewip
+// folder: no tool changes code, CI, GitHub or collected data.
+// Run: node mcp/server.ts (stdio). Setup for each client is in README.md.
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { existsSync } from 'node:fs';
+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 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.');
+const ai = z.boolean().optional().describe('Use the AI layer for failures the rules cannot decide (default true; needs OPENAI_API_KEY).');
+async function answer(fn) {
+    try {
+        return { content: [{ type: 'text', text: await fn() }] };
+    }
+    catch (error) {
+        return { content: [{ type: 'text', text: `Tewip: ${error instanceof Error ? error.message : String(error)}` }], isError: true };
+    }
+}
+server.registerTool('github_ci_report', {
+    title: 'CI diagnosis for a pull request',
+    description: "Latest Tewip report from a GitHub repository's CI: which failing tests the change likely caused, why each failed, the next action, and any verified fix PR. Use for questions like \"why did CI fail on my PR?\".",
+    inputSchema: {
+        repo: z.string().describe('owner/name, e.g. hmamut39/triage-agent-sandbox'),
+        pr: z.number().int().optional().describe('Pull request number'),
+        branch: z.string().optional().describe('Branch name, when there is no PR'),
+    },
+    annotations: { ...readOnly, openWorldHint: true },
+}, ({ repo, pr, branch }) => answer(() => githubCiReport(repo, pr, branch)));
+server.registerTool('list_datasets', { title: 'List datasets', description: 'Collected failure datasets on this machine, with size and latest run.', inputSchema: {}, annotations: readOnly }, () => answer(listDatasets));
+server.registerTool('list_failed_runs', { title: 'List failed runs', description: 'Latest runs with failing tests: run id, time, branch and number of failing tests.', inputSchema: { dataset, limit: z.number().int().min(1).max(100).optional() }, annotations: readOnly }, ({ dataset: d, limit }) => answer(() => listFailedRuns(d, limit)));
+const runViews = [
+    ['triage_board', 'sdet', 'SDET triage board', 'Every failing test of a run, grouped by next action (fix locator, stabilize, fix data, file bug, re-run environment, escalate), with confidence and evidence.'],
+    ['pr_impact', 'developer', 'Is this failure caused by the change?', 'Developer view of a run: which failures the change likely caused and which it probably did not, with the reason.'],
+    ['environment_report', 'environment', 'Environment failures', 'DevOps / SRE view of a run: environment failures grouped by the failing dependency, retry recovery, and one grouped alert text.'],
+    ['release_readiness', 'release', 'Release readiness', 'Business / UAT view of a run in plain words: READY, WAIT or NOT READY, and which product areas are broken.'],
+];
+for (const [name, view, title, description] of runViews) {
+    server.registerTool(name, { title, description, inputSchema: { dataset, run, ai }, annotations: readOnly }, ({ dataset: d, run: r, ai: a }) => answer(() => runView(view, d, r, a ?? true)));
+}
+const windowViews = [
+    ['quality_report', 'quality', 'Engineering quality', 'Senior / principal engineer view over the whole dataset: flakiness hotspots, recurring root-cause patterns, test-design debt ranked by CI time lost.'],
+    ['architecture_report', 'architecture', 'Architecture fragility', 'Architect view: fragile areas (main-branch bugs vs regressions caught in PRs), single commits that broke many suites, failing service dependencies.'],
+    ['risk_digest', 'digest', 'Risk digest', 'Lead / manager view: product areas whose failure rate grew between the first and second half of the data window, on the main branch.'],
+];
+for (const [name, view, title, description] of windowViews) {
+    server.registerTool(name, { title, description, inputSchema: { dataset, ai }, annotations: readOnly }, ({ dataset: d, ai: a }) => answer(() => windowView(view, d, a ?? true)));
+}
+server.registerTool('explain_failure', {
+    title: 'Explain one failing test',
+    description: 'Everything the agent knows about one failing test: root cause, confidence and source, full evidence, history on this commit versus others, the next action and why.',
+    inputSchema: { test: z.string().describe('Part of the test name or file, case-insensitive'), dataset, run, ai },
+    annotations: readOnly,
+}, ({ test, dataset: d, run: r, ai: a }) => answer(() => explainFailure(test, d, r, a ?? true)));
+server.registerTool('test_plan', {
+    title: 'Write a test plan for a feature',
+    description: 'A test plan grounded in a project on this machine: its existing tests (read in full where related), the code the feature lives in, an optional git change and live pages, and the failures Tewip diagnosed there before. Returns risks, prioritised scenarios, what is already covered and what to automate next. Saves the plan in the project\'s .tewip/plans (nothing else is written). Needs OPENAI_API_KEY; takes about a minute.',
+    inputSchema: {
+        feature: z.string().describe('What the feature does, in a sentence or two'),
+        project: z.string().describe('Absolute path of the project folder'),
+        diff: z.string().optional().describe('A git range whose change to plan for, e.g. "main...HEAD"'),
+        urls: z.array(z.string()).optional().describe('Pages of the running app to read, e.g. ["http://localhost:3000/checkout"]'),
+    },
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+}, ({ feature, project, diff, urls }) => answer(async () => {
+    if (!isAbsolute(project) || !existsSync(project))
+        throw new Error(`project must be an existing absolute path, got "${project}"`);
+    const { planProject } = await import('../engine/quality/plan-command.js');
+    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.)`;
+}));
+await server.connect(new StdioServerTransport());

package/dist/mcp/tools.js

@@ -0,0 +1,124 @@
+// What the MCP server answers. Each function returns markdown built by the same engine and
+// role views as the CLI and the GitHub Action (one engine, many outlets). Read-only.
+import { loadCorrections } from '../engine/corrections.js';
+import { existsSync, readdirSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { lastFailedAttempts, loadDataset } from '../engine/dataset.js';
+import { HistoryIndex } from '../engine/history.js';
+import { llmFromEnv } from '../engine/llm/client.js';
+import { historyPattern } from '../engine/llm/context.js';
+import { buildItems } from '../outlets/items.js';
+import { clean, itemBlock, PLAIN_CATEGORY } from '../outlets/view.js';
+import { architectureView } from '../outlets/views/architecture.js';
+import { prCommentView } from '../outlets/views/developer.js';
+import { digestView } from '../outlets/views/digest.js';
+import { infraView } from '../outlets/views/infra.js';
+import { qualityView } from '../outlets/views/quality.js';
+import { releaseView } from '../outlets/views/release.js';
+import { sdetBoardView } from '../outlets/views/sdet.js';
+import { DATA_DIR, PROJECT_ROOT } from '../reporters/store.js';
+/** Keeps answers small enough for an assistant's context window. */
+const MAX_CHARS = 40_000;
+export const cap = (s) => (s.length <= MAX_CHARS ? s : `${s.slice(0, MAX_CHARS)}\n\n…truncated (${s.length} characters in total).`);
+const label = (dir) => relative(PROJECT_ROOT, dir).replaceAll('\\', '/') || '.';
+/** Every directory holding collected failures: data/, data/lab, data/real/*. */
+export function listDatasets() {
+    const dirs = [DATA_DIR, join(DATA_DIR, 'lab'), ...(existsSync(join(DATA_DIR, 'real')) ? readdirSync(join(DATA_DIR, 'real')).map((d) => join(DATA_DIR, 'real', d)) : [])];
+    const rows = dirs
+        .filter((d) => existsSync(join(d, 'triage.jsonl')))
+        .map((d) => {
+        const ds = loadDataset(d);
+        const latest = ds.summaries.map((s) => s.startedAt).sort().at(-1)?.slice(0, 10) ?? '-';
+        return `- \`${label(d)}\`: ${ds.records.length} failed attempts in ${ds.summaries.length} runs, latest ${latest}`;
+    });
+    return rows.length ? `# Datasets\n\n${rows.join('\n')}` : 'No collected failures yet. Run Playwright with the triage reporter, or harvest real CI data (see eval/README.md).';
+}
+function open(dir) {
+    const dataset = loadDataset(dir ? join(PROJECT_ROOT, dir) : undefined);
+    if (dataset.records.length === 0)
+        throw new Error(`No failure records in ${dataset.label}. Call list_datasets to see what is available.`);
+    return { dataset, index: new HistoryIndex(dataset.records, dataset.summaries) };
+}
+const failedRuns = (dataset) => dataset.summaries.filter((s) => dataset.records.some((r) => r.runId === s.runId)).sort((a, b) => b.startedAt.localeCompare(a.startedAt));
+function resolveRun(dataset, run) {
+    const runs = failedRuns(dataset);
+    if (!run) {
+        if (!runs[0])
+            throw new Error('No run with failures in this dataset.');
+        return runs[0].runId;
+    }
+    const matches = runs.filter((s) => s.runId.includes(run));
+    if (matches.length !== 1)
+        throw new Error(matches.length === 0 ? `No failed run matches "${run}".` : `"${run}" matches ${matches.length} runs; be more specific.`);
+    return matches[0].runId;
+}
+const memo = new Map();
+function itemsFor(dir, dataset, index, runId, ai) {
+    const key = `${dir ?? ''}|${runId ?? '*'}|${ai}`;
+    if (!memo.has(key)) {
+        const records = runId ? dataset.records.filter((r) => r.runId === runId) : dataset.records;
+        // Corrections people made are part of what the agent knows, so an assistant asking "why did
+        // CI fail?" is told the answer a person settled, not the one the agent had first.
+        const corrections = loadCorrections(dir ?? DATA_DIR);
+        memo.set(key, buildItems(records, index, { dataset: dataset.label, llm: ai ? llmFromEnv() : null, corrections }));
+    }
+    return memo.get(key);
+}
+export function listFailedRuns(dir, limit = 15) {
+    const { dataset } = open(dir);
+    const rows = failedRuns(dataset)
+        .slice(0, limit)
+        .map((s) => {
+        const failed = new Set(dataset.records.filter((r) => r.runId === s.runId).map((r) => r.testId)).size;
+        return `| ${s.runId} | ${s.startedAt.slice(0, 16).replace('T', ' ')} | ${s.branch || '-'} | ${failed} |`;
+    });
+    return `# Latest runs with failures in \`${dataset.label}\`\n\n| Run | Started (UTC) | Branch | Failing tests |\n|---|---|---|---:|\n${rows.join('\n')}`;
+}
+export async function runView(view, dir, run, ai = true) {
+    const { dataset, index } = open(dir);
+    const runId = resolveRun(dataset, run);
+    const items = await itemsFor(dir, dataset, index, runId, ai);
+    const render = { sdet: sdetBoardView, developer: prCommentView, environment: infraView, release: releaseView }[view];
+    return cap(render(items, runId, dataset.label).markdown);
+}
+export async function windowView(view, dir, ai = true) {
+    const { dataset, index } = open(dir);
+    const items = await itemsFor(dir, dataset, index, null, ai);
+    if (view === 'digest')
+        return cap(digestView(items, dataset.summaries, dataset.label).markdown);
+    return cap((view === 'quality' ? qualityView : architectureView)(items, dataset.label).markdown);
+}
+/** Everything the agent knows about one failing test: diagnosis, evidence, history, next action. */
+export async function explainFailure(test, dir, run, ai = true) {
+    const { dataset, index } = open(dir);
+    const needle = test.toLowerCase();
+    const candidates = lastFailedAttempts(dataset.records).filter((r) => r.testId.toLowerCase().includes(needle) && (!run || r.runId.includes(run)));
+    if (candidates.length === 0)
+        return `No failed test matching "${test}" in \`${dataset.label}\`${run ? ` run ${run}` : ''}.`;
+    const latest = candidates.sort((a, b) => b.timestamp.localeCompare(a.timestamp));
+    const distinctTests = [...new Set(latest.map((r) => r.testId))];
+    if (distinctTests.length > 1)
+        return `"${test}" matches ${distinctTests.length} tests; be more specific:\n\n${distinctTests.slice(0, 20).map((t) => `- ${clean(t)}`).join('\n')}`;
+    const record = latest[0];
+    const [item] = await itemsFor(dir, dataset, index, record.runId, ai).then((xs) => xs.filter((i) => i.testId === record.testId));
+    const failedIn = new Set(latest.map((r) => r.runId)).size;
+    return cap([
+        `# ${clean(item.title)}`,
+        '',
+        itemBlock(item),
+        '',
+        `**In plain words:** ${PLAIN_CATEGORY[item.diagnosis.category]}.`,
+        `**Why this action:** ${item.action.reason}.`,
+        `**Related to the change that triggered the run?** ${item.relation.verdict}: ${item.relation.why}.`,
+        `**History:** ${historyPattern(index.historyAsOf(record.testId, record.runId))}. Failed in ${failedIn} run(s) of this dataset.`,
+        item.debt.length ? `**Test-design debt near the failing line:** ${item.debt.map((d) => `${d.kind} (${clean(d.detail)})`).join('; ')}` : '',
+        '',
+        '## Full evidence',
+        ...item.diagnosis.evidence.map((e) => `- [${e.source}] ${clean(e.message)}`),
+        '',
+        '## Error',
+        '```',
+        record.errorMessage.slice(0, 3000),
+        '```',
+    ].join('\n'));
+}

package/dist/outlets/design-debt.js

@@ -0,0 +1,22 @@
+// Test-design debt visible in a failure: fixed waits and brittle selectors. Read from the
+// failing locator and the code around the failing line only (not the whole spec).
+const HARD_WAIT = /waitForTimeout\(\s*\d+|new Promise\([^)]*setTimeout|\bsleep\(\s*\d+/;
+const BRITTLE = [
+    { pattern: /nth-child|nth-of-type|\.nth\(|:nth-match|\.first\(\)|\.last\(\)/, why: 'position-based' },
+    { pattern: /xpath=|^locator\(\s*['"]\/\//, why: 'XPath' },
+    { pattern: /^locator\(\s*['"][^'"]*\s>\s/, why: 'deep CSS chain' },
+    { pattern: /^locator\(\s*['"][^'"#]*\.[a-zA-Z_-][\w-]*/, why: 'CSS class' },
+];
+export function designDebt(locator, code) {
+    const debt = [];
+    const waitLine = code?.find((line) => HARD_WAIT.test(line.split('|').slice(1).join('|')));
+    if (waitLine)
+        debt.push({ kind: 'hard-wait', detail: waitLine.split('|').slice(1).join('|').trim() });
+    // Role / label / test-id locators are the robust kind; only raw CSS/XPath can be brittle.
+    if (locator && !/^getBy/.test(locator)) {
+        const hit = BRITTLE.find((b) => b.pattern.test(locator));
+        if (hit)
+            debt.push({ kind: 'brittle-selector', detail: `${hit.why}: ${locator}` });
+    }
+    return debt;
+}

package/dist/outlets/items.js

@@ -0,0 +1,94 @@
+// The unified triage item: one per failed test per run, built once by the engine and
+// rendered by every role's view (ROADMAP principle 3: one engine, many outlets).
+import { extractLocator } from '../engine/error-parse.js';
+import { decide } from '../engine/decide.js';
+import { lastFailedAttempts } from '../engine/dataset.js';
+import { failingCodeOf } from '../engine/llm/context.js';
+import { diagnosePipeline } from '../engine/pipeline.js';
+import { truncate } from '../engine/signature.js';
+import { designDebt } from './design-debt.js';
+const DEFAULT_BRANCHES = new Set((process.env.TRIAGE_DEFAULT_BRANCH ?? 'main,master,trunk').split(','));
+/** Unknown branches count as default: without branch data, failures are treated as before. */
+export const isDefaultBranch = (branch) => !branch || DEFAULT_BRANCHES.has(branch);
+/** Product area from a spec path: its first two folders, or the spec name when it has none. */
+export function componentOf(file) {
+    const path = file.replaceAll('\\', '/').replace(/^(?:test\/e2e\/specs|tests?|e2e|specs?)\//, '');
+    const dirs = path.split('/').slice(0, -1);
+    return dirs.length > 0 ? dirs.slice(0, 2).join('/') : path.replace(/\.(spec|test)\.[jt]sx?$/, '');
+}
+function relationOf(d, h) {
+    if (d.category === 'ENV')
+        return { verdict: 'not-this-change', why: 'environment problem, not code (see the infrastructure view)' };
+    if (h.currentRunFailures < h.currentRunAttempts)
+        return { verdict: 'not-this-change', why: 'a retry of the same code passed in this run: the test is flaky' };
+    if (h.failingRunsOnOtherCommits >= 2)
+        return { verdict: 'not-this-change', why: `it also failed in ${h.failingRunsOnOtherCommits} runs on other commits: an existing problem` };
+    if (h.sameCommitAttempts > 0 && h.sameCommitFailures === h.sameCommitAttempts && h.passesOnOtherCommits > 0) {
+        return { verdict: 'likely-this-change', why: `every attempt on this commit failed (${h.sameCommitFailures}/${h.sameCommitAttempts}) while it passed ${h.passesOnOtherCommits} time(s) on other commits` };
+    }
+    return { verdict: 'unclear', why: 'not enough history on other commits to tell' };
+}
+export function sourceOf(d, dataset) {
+    const who = d.source === 'human' ? 'corrected by a person' : d.source === 'llm' ? `AI ${d.model ?? 'model'}` : `rules ${d.engineVersion}`;
+    return `${who} · data: ${dataset}`;
+}
+function suggestedLocator(d) {
+    const replacement = d.evidence.map((e) => e.data?.replacement).find((r) => typeof r === 'string');
+    if (replacement)
+        return replacement;
+    const candidate = d.evidence.map((e) => e.data?.candidate).find(Boolean);
+    if (!candidate?.role)
+        return undefined;
+    return candidate.name ? `getByRole('${candidate.role}', { name: '${candidate.name.replaceAll("'", "\\'")}' })` : `getByRole('${candidate.role}')`;
+}
+/** Diagnoses every failed test of every run in `records` and wraps each as a TriageItem. */
+export async function buildItems(records, index, { dataset, llm, reuseStoredDiagnoses = false, corrections = [] }) {
+    const cases = lastFailedAttempts(records);
+    const stored = reuseStoredDiagnoses ? cases.map((c) => c.diagnosis) : cases.map(() => undefined);
+    const missing = cases.filter((_, i) => !stored[i]);
+    const fresh = await diagnosePipeline(missing, index, llm, { corrections });
+    const diagnoses = stored.map((d) => d ?? fresh.shift());
+    const failedAttempts = new Map();
+    for (const r of records)
+        failedAttempts.set(`${r.runId} ${r.testId}`, [...(failedAttempts.get(`${r.runId} ${r.testId}`) ?? []), r]);
+    return cases.map((record, i) => {
+        const d = diagnoses[i];
+        const history = index.historyAsOf(record.testId, record.runId);
+        const { branch } = index.runContext(record.runId);
+        const attempts = failedAttempts.get(`${record.runId} ${record.testId}`) ?? [record];
+        const locator = extractLocator(record.errorMessage) ?? undefined;
+        const debt = designDebt(locator ?? null, failingCodeOf(record));
+        const component = componentOf(record.file);
+        const hardWait = debt.find((x) => x.kind === 'hard-wait')?.detail;
+        return {
+            runId: record.runId,
+            testId: record.testId,
+            title: record.testId.split(' > ').at(-1) ?? record.testId,
+            file: record.file,
+            component,
+            commit: record.gitSha,
+            branch,
+            onDefaultBranch: isDefaultBranch(branch),
+            timestamp: record.timestamp,
+            failedAttempts: attempts.length,
+            wastedMs: attempts.reduce((sum, a) => sum + a.duration, 0),
+            errorHead: truncate(record.errorMessage.split('\n')[0] ?? '', 160),
+            diagnosis: d,
+            action: decide(d, {
+                locator,
+                suggestedLocator: suggestedLocator(d),
+                hardWait,
+                strictMatches: Number(record.errorMessage.match(/strict mode violation: .* resolved to (\d+) elements/)?.[1]) || undefined,
+                component,
+                commit: record.gitSha,
+                tracePath: record.attachments.find((a) => a.name === 'trace')?.path,
+            }),
+            source: sourceOf(d, dataset),
+            evidence: d.evidence.slice(0, 3).map((e) => truncate(e.message, 220)),
+            recoveredOnRetry: history.currentRunFailures < history.currentRunAttempts,
+            relation: relationOf(d, history),
+            debt,
+            locator,
+        };
+    });
+}

package/dist/outlets/view.js

@@ -0,0 +1,63 @@
+/**
+ * Phase-4 routing: the views each category must reach. Run-level views only; the window
+ * views aggregate. Low-confidence and UNKNOWN failures always land on the SDET board.
+ */
+export const ROUTES = {
+    REAL_BUG: ['developer', 'business', 'sdet'],
+    ENV: ['devops', 'developer', 'sdet'],
+    TIMING: ['developer', 'sdet'],
+    LOCATOR_DRIFT: ['developer', 'sdet'],
+    TEST_DATA: ['developer', 'sdet'],
+    UNKNOWN: ['developer', 'sdet'],
+};
+export const PLAIN_CATEGORY = {
+    REAL_BUG: 'product problem',
+    ENV: 'test environment problem',
+    TIMING: 'unreliable (flaky) test',
+    LOCATOR_DRIFT: 'test needs updating after a UI change',
+    TEST_DATA: 'test data problem',
+    UNKNOWN: 'not understood yet',
+};
+/** A zero-width space: invisible, but it stops GitHub from reading the text around it as syntax. */
+const ZWSP = '​';
+/**
+ * Markdown-safe single line from a test run: no backticks, pipes or line breaks. Test names and
+ * error messages come from the pull request's own code, so on a public repository its author
+ * controls them: without this they could ping people (@name), embed tracking images or disguised
+ * links, or inject HTML into the agent's comment.
+ */
+export const clean = (s) => s
+    .replaceAll('`', "'")
+    .replaceAll('|', '/')
+    .replaceAll('<', '&lt;')
+    .replace(/@(?=[\w-])/g, `@${ZWSP}`) // "@name" reads the same but notifies no one
+    .replace(/!?\[([^\]\n]*)\]\(/g, `[$1]${ZWSP}(`) // links and images show as plain text
+    .replace(/\s+/g, ' ')
+    .trim();
+export const confidenceText = (d) => (d.category === 'UNKNOWN' ? 'confidence 0.00 (undecided)' : `confidence ${d.confidence.toFixed(2)}`);
+export const diagnosisLine = (i) => `${i.diagnosis.category}, ${confidenceText(i.diagnosis)}, source: ${clean(i.source)}`;
+export const actionLine = (i) => `${i.action.owner}${i.action.autonomous ? ', the agent may do this on its own' : ''}): ${clean(i.action.summary)}`;
+/** The standard block for one failure. Views may add lines after it, never drop these. */
+export function itemBlock(i, extra = [], number) {
+    return [
+        `- ${number ? `**#${number}** ` : ''}**${clean(i.title)}** (\`${clean(i.file)}\`, run ${clean(i.runId)})`,
+        `  - Diagnosis: ${diagnosisLine(i)}`,
+        `  - Next action (${actionLine(i)}`,
+        `  - Evidence: ${i.evidence.length > 0 ? i.evidence.map(clean).join(' · ') : '(none)'}`,
+        ...extra.map((line) => `  - ${line}`),
+    ].join('\n');
+}
+/** Why an item is not properly shown in a view, or null when it is. */
+export function missingFromView(view, i) {
+    if (!view.items.includes(i))
+        return `not listed in ${view.id}`;
+    if (!view.markdown.includes(diagnosisLine(i)))
+        return `${view.id} lacks its diagnosis, confidence or source`;
+    if (!view.markdown.includes(clean(i.action.summary)))
+        return `${view.id} lacks its next action`;
+    if (i.evidence.length === 0 || !view.markdown.includes(clean(i.evidence[0])))
+        return `${view.id} lacks its evidence`;
+    return null;
+}
+/** Header line that ties a view's numbers to the dataset they came from. */
+export const sourceNote = (dataset) => `> Data: \`${dataset}\`. Every diagnosis shows its confidence and whether rules or the AI model produced it. Measured accuracy on real CI data: see eval/README.md.`;

package/dist/outlets/views/architecture.js

@@ -0,0 +1,77 @@
+import { clean, itemBlock, sourceNote } from '../view.js';
+import { groupEnv } from './infra.js';
+/** A run where one commit broke at least this many tests, or this many areas, counts as a wide break. */
+const WIDE_BREAK_TESTS = 5;
+const WIDE_BREAK_AREAS = 3;
+export function architectureView(items, dataset) {
+    const shown = [];
+    const example = (i) => {
+        shown.push(i);
+        return itemBlock(i, ['(example)']);
+    };
+    const areas = [...new Set(items.map((i) => i.component))]
+        .map((component) => {
+        const xs = items.filter((i) => i.component === component);
+        const count = (c) => xs.filter((i) => i.diagnosis.category === c).length;
+        const bugs = xs.filter((i) => i.diagnosis.category === 'REAL_BUG');
+        // Regressions a pull request introduced and CI caught before merge are the process working,
+        // not fragility of the main branch, so they are counted apart.
+        return {
+            component,
+            total: xs.length,
+            bug: bugs.filter((i) => i.onDefaultBranch).length,
+            caught: bugs.filter((i) => !i.onDefaultBranch).length,
+            env: count('ENV'),
+            timing: count('TIMING'),
+        };
+    })
+        .sort((a, b) => b.bug + b.env - (a.bug + a.env) || b.total - a.total)
+        .slice(0, 12);
+    const bugsByRun = new Map();
+    for (const i of items.filter((x) => x.diagnosis.category === 'REAL_BUG'))
+        bugsByRun.set(i.runId, [...(bugsByRun.get(i.runId) ?? []), i]);
+    const wideBreaks = [...bugsByRun.values()]
+        .map((xs) => ({ xs, areas: [...new Set(xs.map((i) => i.component))] }))
+        .filter((b) => b.xs.length >= WIDE_BREAK_TESTS || b.areas.length >= WIDE_BREAK_AREAS)
+        .sort((a, b) => b.xs.length - a.xs.length)
+        .slice(0, 5);
+    const deps = groupEnv(items).slice(0, 6);
+    const markdown = [
+        '# Architecture view: whole window',
+        '',
+        sourceNote(dataset),
+        '',
+        '## Fragility by area',
+        '',
+        '| Area | Failing cases | Product bugs (main branch) | Regressions caught in PRs | Environment | Flaky |',
+        '|---|---:|---:|---:|---:|---:|',
+        ...areas.map((a) => `| ${clean(a.component)} | ${a.total} | ${a.bug} | ${a.caught} | ${a.env} | ${a.timing} |`),
+        '',
+        `Next action: review the top area's dependencies and shared components first; product bugs and environment failures there cost every team.`,
+        '',
+        '## Single changes that broke many suites at once',
+        '',
+        ...(wideBreaks.length === 0
+            ? ['None in this window.', '']
+            : wideBreaks.flatMap((b) => [
+                `### Commit \`${b.xs[0].commit.slice(0, 8)}\` (run ${clean(b.xs[0].runId)}${b.xs[0].onDefaultBranch ? '' : `, pull request branch ${clean(b.xs[0].branch)}, caught before merge`}): ${b.xs.length} test(s) across ${b.areas.length} area(s)`,
+                `Areas: ${b.areas.map(clean).join(', ')}.`,
+                'Next action: look at what this commit changed in shared code; one change breaking this many suites points to tight coupling.',
+                '',
+                example(b.xs[0]),
+                '',
+            ])),
+        '## Service and environment dependencies that failed',
+        '',
+        ...(deps.length === 0
+            ? ['None in this window.', '']
+            : deps.flatMap((g) => [
+                `### ${clean(g.signature)}: ${g.items.length} failure(s) in ${new Set(g.items.map((i) => i.runId)).size} run(s), ${g.recovered} recovered on retry`,
+                'Next action: make this dependency more resilient (health check before the suite, retries on connection reset) or isolate the tests from it.',
+                '',
+                example(g.items[0]),
+                '',
+            ])),
+    ].join('\n');
+    return { id: 'architecture', role: 'architect', title: 'Architecture view', scope: 'window', items: [...new Set(shown)], markdown };
+}