@tangle-network/browser-agent-driver 0.30.0 → 0.32.0

package/dist/design/audit/patches/generate.js

@@ -0,0 +1,161 @@
+/**
+ * Patch generator — Layer 2's second LLM call.
+ *
+ * The findings prompt (evaluate.ts) stays slim and focused on scoring +
+ * findings. After findings exist, this module makes a SECOND LLM call given
+ * those major/critical findings and asks for one Patch per finding. The
+ * second-call shape is intentionally narrow: only the patch contract +
+ * ground-truth snapshot, nothing else. That keeps each call's cognitive load
+ * low and lets us measure them independently.
+ *
+ * Flow:
+ *   1. Filter findings to severity ∈ {major, critical}.
+ *   2. Build a focused prompt (snapshot + JSON of those findings).
+ *   3. Call the LLM, parse + validate the response, attach valid patches
+ *      back to their findings by id.
+ *
+ * On any failure: return findings unchanged. Layer 2 enforcement (downgrade
+ * major/critical without a valid patch) runs after this in build-result.ts,
+ * so a failed generator → graceful degradation, not a broken pipeline.
+ */
+import { parsePatches } from './parse.js';
+const SYSTEM_OPENER = 'You are a code-mod author. For each finding below, emit ONE Patch the agent can apply literally. Patches that target HTML or page structure must reference verbatim text in the snapshot. Patches that target source files (CSS/TSX/Tailwind) reference selectors only — the agent verifies them at apply-time against the source.';
+const DEFAULT_MAX = 8;
+export async function generatePatches(opts) {
+    const max = opts.maxFindings ?? DEFAULT_MAX;
+    const eligible = opts.findings
+        .filter(f => f.severity === 'major' || f.severity === 'critical')
+        .slice(0, max);
+    if (eligible.length === 0) {
+        return { findings: opts.findings, tokensUsed: 0, notes: [] };
+    }
+    const prompt = buildPrompt(opts.snapshot, eligible);
+    let raw = '';
+    let tokensUsed = 0;
+    try {
+        const llm = await opts.brain.complete(SYSTEM_OPENER, prompt, { maxOutputTokens: 2000 });
+        raw = llm.text ?? '';
+        tokensUsed = llm.tokensUsed ?? 0;
+    }
+    catch (err) {
+        return {
+            findings: opts.findings,
+            tokensUsed: 0,
+            notes: [{ findingId: '*', reason: `LLM call failed: ${err.message}` }],
+        };
+    }
+    const parsed = parseGeneratorResponse(raw);
+    const byFinding = new Map();
+    for (const item of parsed.items) {
+        if (item.findingId)
+            byFinding.set(item.findingId, item.patch);
+    }
+    const notes = [];
+    const updated = opts.findings.map(f => {
+        const patchRaw = byFinding.get(f.id);
+        if (!patchRaw) {
+            if (f.severity === 'major' || f.severity === 'critical') {
+                notes.push({ findingId: f.id, reason: 'no patch in generator response' });
+            }
+            return f;
+        }
+        // Stamp the canonical findingId onto the patch (LLM may have used a placeholder).
+        const stamped = withFindingId(patchRaw, f.id);
+        // Quick parse check so the build-result stage sees a sane shape.
+        const parsedOne = parsePatches([stamped]);
+        if (parsedOne.patches.length === 0) {
+            notes.push({ findingId: f.id, reason: `parse failed: ${parsedOne.errors[0]?.reason ?? 'unknown'}` });
+            return f;
+        }
+        return { ...f, rawPatches: [stamped] };
+    });
+    return { findings: updated, tokensUsed, notes };
+}
+function buildPrompt(snapshot, findings) {
+    // Trim the snapshot to keep the prompt cheap. The findings reference visible
+    // elements; trimming should not cost meaningful context.
+    const trimmedSnapshot = snapshot.length > 8000 ? snapshot.slice(0, 8000) + '\n…[truncated]' : snapshot;
+    const findingsBlock = findings.map(f => ({
+        id: f.id,
+        severity: f.severity,
+        description: f.description,
+        location: f.location,
+        cssSelector: f.cssSelector,
+        suggestion: f.suggestion,
+    }));
+    return `PAGE SNAPSHOT (accessibility-tree text):
+${trimmedSnapshot}
+
+FINDINGS THAT NEED A PATCH (one per id):
+${JSON.stringify(findingsBlock, null, 2)}
+
+For each finding above, emit ONE Patch object. Required shape:
+{
+  "patchId": "p-<short-stable-id>",
+  "findingId": "<copy verbatim from the finding>",
+  "scope": "page" | "section" | "component" | "system",
+  "target": {
+    "scope": "css" | "tsx" | "jsx" | "tailwind" | "module-css" | "styled-component" | "html" | "structural",
+    "cssSelector": "...",  // OR
+    "filePath": "...",     // OR
+    "componentName": "..." // at least ONE must be set
+  },
+  "diff": {
+    "before": "<verbatim text the agent will search-replace>",
+    "after":  "<replacement text>"
+  },
+  "testThatProves": { "kind": "rerun-audit" | "visual-snapshot" | "a11y-rule" | "storybook" | "unit" | "manual", "description": "..." },
+  "rollback": { "kind": "css-disable" | "git-revert" | "manual" },
+  "estimatedDelta": { "dim": "product_intent" | "visual_craft" | "trust_clarity" | "workflow" | "content_ia", "delta": -3..3 },
+  "estimatedDeltaConfidence": "high" | "medium" | "low" | "untested"
+}
+
+Snapshot-anchoring rule (READ CAREFULLY — most patch failures fail this):
+- target.scope MUST be "css" by default. Use "html" or "structural" ONLY when you are paste-copying a literal substring from the SNAPSHOT BLOCK above (not from your imagination, not from typical-site assumptions).
+- Before setting target.scope to "html", verify diff.before is a verbatim substring of the snapshot block above. If it isn't, change target.scope to "css".
+- For css / tsx / jsx / tailwind / module-css / styled-component scopes, diff.before is a source-file fragment the agent resolves at apply-time; the audit does not validate it. This is the safe default.
+
+If a finding does not admit a clean patch, OMIT it (do not invent diffs).
+
+RESPOND WITH ONLY a JSON object:
+{
+  "patches": [
+    { "findingId": "<id>", "patch": <the Patch object above> }
+  ]
+}`;
+}
+function parseGeneratorResponse(raw) {
+    let text = raw.trim();
+    if (text.startsWith('```')) {
+        text = text.replace(/^```(?:json)?\n?/, '').replace(/\n?```$/, '');
+    }
+    const start = text.indexOf('{');
+    const end = text.lastIndexOf('}');
+    if (start < 0 || end <= start)
+        return { items: [] };
+    try {
+        const obj = JSON.parse(text.slice(start, end + 1));
+        if (!Array.isArray(obj.patches))
+            return { items: [] };
+        const items = [];
+        for (const p of obj.patches) {
+            if (!p || typeof p !== 'object')
+                continue;
+            const rec = p;
+            if (typeof rec.findingId !== 'string')
+                continue;
+            items.push({ findingId: rec.findingId, patch: rec.patch ?? p });
+        }
+        return { items };
+    }
+    catch {
+        return { items: [] };
+    }
+}
+function withFindingId(raw, findingId) {
+    if (raw && typeof raw === 'object') {
+        return { ...raw, findingId };
+    }
+    return raw;
+}
+//# sourceMappingURL=generate.js.map

package/dist/design/audit/patches/generate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"generate.js","sourceRoot":"","sources":["../../../../src/design/audit/patches/generate.ts"],"names":[],"mappings":"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"}

package/dist/design/audit/patches/index.d.ts

@@ -0,0 +1,8 @@
+export { parsePatch, parsePatches } from './parse.js';
+export { validatePatch, validatePatches } from './validate.js';
+export { renderUnifiedDiff, renderPatchSummary } from './render.js';
+export { enforcePatchPolicy } from './severity-enforcement.js';
+export type { ParseResult } from './parse.js';
+export type { ValidationResult, ValidationReason } from './validate.js';
+export type { EnforcementResult, EnforcementRecord } from './severity-enforcement.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/design/audit/patches/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/design/audit/patches/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AACrD,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,eAAe,CAAA;AAC9D,OAAO,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAA;AACnE,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAA;AAC9D,YAAY,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAC7C,YAAY,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAA;AACvE,YAAY,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAA"}

package/dist/design/audit/patches/index.js

@@ -0,0 +1,5 @@
+export { parsePatch, parsePatches } from './parse.js';
+export { validatePatch, validatePatches } from './validate.js';
+export { renderUnifiedDiff, renderPatchSummary } from './render.js';
+export { enforcePatchPolicy } from './severity-enforcement.js';
+//# sourceMappingURL=index.js.map

package/dist/design/audit/patches/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/design/audit/patches/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AACrD,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,eAAe,CAAA;AAC9D,OAAO,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAA;AACnE,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAA"}

package/dist/design/audit/patches/parse.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Patch parser — converts raw LLM JSON output into typed `Patch` objects.
+ *
+ * Strict shape validation. On schema mismatch returns `{ patch: null, reason }`
+ * rather than throwing — the calling pipeline batches many candidate patches
+ * per audit and a single malformed entry must not abort the whole run.
+ */
+import type { Patch } from '../score-types.js';
+export interface ParseResult {
+    patch: Patch | null;
+    reason?: string;
+}
+/**
+ * Parse a single raw LLM-produced object into a `Patch`. Returns
+ * `{ patch: null, reason }` on any schema violation.
+ */
+export declare function parsePatch(raw: unknown): ParseResult;
+/**
+ * Parse an array of raw patch objects. Invalid entries are dropped from the
+ * returned `patches` and reported in `errors` with their original index.
+ */
+export declare function parsePatches(raw: unknown): {
+    patches: Patch[];
+    errors: Array<{
+        index: number;
+        reason: string;
+    }>;
+};
+//# sourceMappingURL=parse.d.ts.map

package/dist/design/audit/patches/parse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse.d.ts","sourceRoot":"","sources":["../../../../src/design/audit/patches/parse.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EACV,KAAK,EAQN,MAAM,mBAAmB,CAAA;AAgB1B,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,KAAK,GAAG,IAAI,CAAA;IACnB,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAwDD;;;GAGG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,OAAO,GAAG,WAAW,CA+CpD;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,OAAO,GAAG;IAC1C,OAAO,EAAE,KAAK,EAAE,CAAA;IAChB,MAAM,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CACjD,CAYA"}

package/dist/design/audit/patches/parse.js

@@ -0,0 +1,153 @@
+/**
+ * Patch parser — converts raw LLM JSON output into typed `Patch` objects.
+ *
+ * Strict shape validation. On schema mismatch returns `{ patch: null, reason }`
+ * rather than throwing — the calling pipeline batches many candidate patches
+ * per audit and a single malformed entry must not abort the whole run.
+ */
+const VALID_SCOPES = ['page', 'section', 'component', 'system'];
+const VALID_TARGET_SCOPES = [
+    'tsx', 'jsx', 'css', 'tailwind', 'module-css', 'styled-component', 'structural', 'html',
+];
+const VALID_TEST_KINDS = [
+    'storybook', 'a11y-rule', 'visual-snapshot', 'unit', 'rerun-audit', 'manual',
+];
+const VALID_ROLLBACK_KINDS = ['git-revert', 'css-disable', 'manual'];
+const VALID_CONFIDENCES = ['high', 'medium', 'low', 'untested'];
+function isObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isString(value) {
+    return typeof value === 'string' && value.length > 0;
+}
+function oneOf(value, allowed) {
+    return typeof value === 'string' && allowed.includes(value);
+}
+function parseTarget(raw) {
+    if (!isObject(raw))
+        return 'target: not an object';
+    if (!oneOf(raw.scope, VALID_TARGET_SCOPES))
+        return `target.scope: invalid (got ${String(raw.scope)})`;
+    const target = { scope: raw.scope };
+    if (raw.filePath !== undefined) {
+        if (!isString(raw.filePath))
+            return 'target.filePath: must be non-empty string';
+        target.filePath = raw.filePath;
+    }
+    if (raw.componentName !== undefined) {
+        if (!isString(raw.componentName))
+            return 'target.componentName: must be non-empty string';
+        target.componentName = raw.componentName;
+    }
+    if (raw.cssSelector !== undefined) {
+        if (!isString(raw.cssSelector))
+            return 'target.cssSelector: must be non-empty string';
+        target.cssSelector = raw.cssSelector;
+    }
+    return target;
+}
+function parseTest(raw) {
+    if (!isObject(raw))
+        return 'testThatProves: not an object';
+    if (!oneOf(raw.kind, VALID_TEST_KINDS))
+        return `testThatProves.kind: invalid (got ${String(raw.kind)})`;
+    if (!isString(raw.description))
+        return 'testThatProves.description: must be non-empty string';
+    const test = { kind: raw.kind, description: raw.description };
+    if (raw.command !== undefined) {
+        if (typeof raw.command !== 'string')
+            return 'testThatProves.command: must be string when present';
+        test.command = raw.command;
+    }
+    return test;
+}
+function parseRollback(raw) {
+    if (!isObject(raw))
+        return 'rollback: not an object';
+    if (!oneOf(raw.kind, VALID_ROLLBACK_KINDS))
+        return `rollback.kind: invalid (got ${String(raw.kind)})`;
+    const rollback = { kind: raw.kind };
+    if (raw.instruction !== undefined) {
+        if (typeof raw.instruction !== 'string')
+            return 'rollback.instruction: must be string when present';
+        rollback.instruction = raw.instruction;
+    }
+    return rollback;
+}
+/**
+ * Parse a single raw LLM-produced object into a `Patch`. Returns
+ * `{ patch: null, reason }` on any schema violation.
+ */
+export function parsePatch(raw) {
+    if (!isObject(raw))
+        return { patch: null, reason: 'patch: not an object' };
+    if (!isString(raw.patchId))
+        return { patch: null, reason: 'patchId: required non-empty string' };
+    if (!isString(raw.findingId))
+        return { patch: null, reason: 'findingId: required non-empty string' };
+    if (!oneOf(raw.scope, VALID_SCOPES))
+        return { patch: null, reason: `scope: invalid (got ${String(raw.scope)})` };
+    const target = parseTarget(raw.target);
+    if (typeof target === 'string')
+        return { patch: null, reason: target };
+    if (!isObject(raw.diff))
+        return { patch: null, reason: 'diff: not an object' };
+    if (!isString(raw.diff.before))
+        return { patch: null, reason: 'diff.before: required non-empty string' };
+    if (typeof raw.diff.after !== 'string')
+        return { patch: null, reason: 'diff.after: required string' };
+    const diff = {
+        before: raw.diff.before,
+        after: raw.diff.after,
+        ...(typeof raw.diff.unifiedDiff === 'string' ? { unifiedDiff: raw.diff.unifiedDiff } : {}),
+    };
+    const test = parseTest(raw.testThatProves);
+    if (typeof test === 'string')
+        return { patch: null, reason: test };
+    const rollback = parseRollback(raw.rollback);
+    if (typeof rollback === 'string')
+        return { patch: null, reason: rollback };
+    if (!isObject(raw.estimatedDelta))
+        return { patch: null, reason: 'estimatedDelta: not an object' };
+    if (!isString(raw.estimatedDelta.dim))
+        return { patch: null, reason: 'estimatedDelta.dim: required' };
+    if (typeof raw.estimatedDelta.delta !== 'number' || !Number.isFinite(raw.estimatedDelta.delta)) {
+        return { patch: null, reason: 'estimatedDelta.delta: must be finite number' };
+    }
+    if (!oneOf(raw.estimatedDeltaConfidence, VALID_CONFIDENCES)) {
+        return { patch: null, reason: `estimatedDeltaConfidence: invalid (got ${String(raw.estimatedDeltaConfidence)})` };
+    }
+    const patch = {
+        patchId: raw.patchId,
+        findingId: raw.findingId,
+        scope: raw.scope,
+        target,
+        diff,
+        testThatProves: test,
+        rollback,
+        estimatedDelta: { dim: raw.estimatedDelta.dim, delta: raw.estimatedDelta.delta },
+        estimatedDeltaConfidence: raw.estimatedDeltaConfidence,
+        ...(typeof raw.matchedPatternId === 'string' ? { matchedPatternId: raw.matchedPatternId } : {}),
+    };
+    return { patch };
+}
+/**
+ * Parse an array of raw patch objects. Invalid entries are dropped from the
+ * returned `patches` and reported in `errors` with their original index.
+ */
+export function parsePatches(raw) {
+    if (!Array.isArray(raw)) {
+        return { patches: [], errors: [{ index: -1, reason: 'patches: not an array' }] };
+    }
+    const patches = [];
+    const errors = [];
+    for (let i = 0; i < raw.length; i++) {
+        const result = parsePatch(raw[i]);
+        if (result.patch)
+            patches.push(result.patch);
+        else
+            errors.push({ index: i, reason: result.reason ?? 'unknown' });
+    }
+    return { patches, errors };
+}
+//# sourceMappingURL=parse.js.map

package/dist/design/audit/patches/parse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse.js","sourceRoot":"","sources":["../../../../src/design/audit/patches/parse.ts"],"names":[],"mappings":"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"}

package/dist/design/audit/patches/render.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Patch renderer — produces a unified diff from a Patch when filePath is known.
+ *
+ * Agents can pipe the result to `git apply --check` then `git apply`.
+ * When filePath is unknown, returns null — the agent must use before/after for
+ * search-replace instead.
+ */
+import type { Patch } from '../score-types.js';
+/**
+ * Render a minimal unified diff (1-hunk, 3 lines context) from a patch.
+ * Returns null when:
+ *   - `target.filePath` is not set (no file to diff against)
+ *   - `unifiedDiff` is already set on the patch (prefer the LLM's version)
+ */
+export declare function renderUnifiedDiff(patch: Patch): string | null;
+/**
+ * Render a human-readable patch summary for display in report.md.
+ */
+export declare function renderPatchSummary(patch: Patch): string;
+//# sourceMappingURL=render.d.ts.map

package/dist/design/audit/patches/render.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../../../../src/design/audit/patches/render.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAA;AAE9C;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM,GAAG,IAAI,CAuB7D;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM,CAYvD"}

package/dist/design/audit/patches/render.js

@@ -0,0 +1,55 @@
+/**
+ * Patch renderer — produces a unified diff from a Patch when filePath is known.
+ *
+ * Agents can pipe the result to `git apply --check` then `git apply`.
+ * When filePath is unknown, returns null — the agent must use before/after for
+ * search-replace instead.
+ */
+/**
+ * Render a minimal unified diff (1-hunk, 3 lines context) from a patch.
+ * Returns null when:
+ *   - `target.filePath` is not set (no file to diff against)
+ *   - `unifiedDiff` is already set on the patch (prefer the LLM's version)
+ */
+export function renderUnifiedDiff(patch) {
+    if (patch.diff.unifiedDiff)
+        return patch.diff.unifiedDiff;
+    if (!patch.target.filePath)
+        return null;
+    const { before, after } = patch.diff;
+    const filePath = patch.target.filePath;
+    const beforeLines = before.split('\n');
+    const afterLines = after.split('\n');
+    const removals = beforeLines.map(l => `- ${l}`);
+    const additions = afterLines.map(l => `+ ${l}`);
+    const hunkOldLen = beforeLines.length;
+    const hunkNewLen = afterLines.length;
+    return [
+        `--- a/${filePath}`,
+        `+++ b/${filePath}`,
+        `@@ -1,${hunkOldLen} +1,${hunkNewLen} @@`,
+        ...removals,
+        ...additions,
+    ].join('\n');
+}
+/**
+ * Render a human-readable patch summary for display in report.md.
+ */
+export function renderPatchSummary(patch) {
+    const parts = [];
+    parts.push(`**Patch ${patch.patchId}** (${patch.scope})`);
+    if (patch.target.filePath)
+        parts.push(`File: \`${patch.target.filePath}\``);
+    else if (patch.target.cssSelector)
+        parts.push(`Selector: \`${patch.target.cssSelector}\``);
+    else if (patch.target.componentName)
+        parts.push(`Component: \`${patch.target.componentName}\``);
+    parts.push(`\`\`\`diff\n${renderUnifiedDiff(patch) ?? `- ${patch.diff.before}\n+ ${patch.diff.after}`}\n\`\`\``);
+    parts.push(`Test: ${patch.testThatProves.description}`);
+    if (patch.testThatProves.command)
+        parts.push(`Command: \`${patch.testThatProves.command}\``);
+    parts.push(`Rollback: ${patch.rollback.kind}${patch.rollback.instruction ? ` — ${patch.rollback.instruction}` : ''}`);
+    parts.push(`Estimated Δ: ${patch.estimatedDelta.dim} ${patch.estimatedDelta.delta > 0 ? '+' : ''}${patch.estimatedDelta.delta} (confidence: ${patch.estimatedDeltaConfidence})`);
+    return parts.join('\n');
+}
+//# sourceMappingURL=render.js.map

package/dist/design/audit/patches/render.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"render.js","sourceRoot":"","sources":["../../../../src/design/audit/patches/render.ts"],"names":[],"mappings":"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"}

package/dist/design/audit/patches/severity-enforcement.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Severity enforcement — every major/critical finding MUST have ≥1 valid patch.
+ *
+ * Findings without patches are downgraded to `minor` with an explanatory note.
+ * This runs as a post-processing step after patch validation.
+ */
+import type { DesignFinding } from '../score-types.js';
+export interface EnforcementRecord {
+    findingId: string;
+    fromSeverity: string;
+    toSeverity: 'minor';
+    reason: string;
+}
+export interface EnforcementResult {
+    findings: DesignFinding[];
+    downgraded: EnforcementRecord[];
+}
+/**
+ * Given a list of findings and the set of valid patches (post-validation),
+ * downgrade any major/critical finding that has no valid patch to `minor`.
+ */
+export declare function enforcePatchPolicy(findings: DesignFinding[], validPatchIds: Set<string>): EnforcementResult;
+//# sourceMappingURL=severity-enforcement.d.ts.map

package/dist/design/audit/patches/severity-enforcement.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"severity-enforcement.d.ts","sourceRoot":"","sources":["../../../../src/design/audit/patches/severity-enforcement.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAS,aAAa,EAAE,MAAM,mBAAmB,CAAA;AAE7D,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,MAAM,CAAA;IACjB,YAAY,EAAE,MAAM,CAAA;IACpB,UAAU,EAAE,OAAO,CAAA;IACnB,MAAM,EAAE,MAAM,CAAA;CACf;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,aAAa,EAAE,CAAA;IACzB,UAAU,EAAE,iBAAiB,EAAE,CAAA;CAChC;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,aAAa,EAAE,EACzB,aAAa,EAAE,GAAG,CAAC,MAAM,CAAC,GACzB,iBAAiB,CAkCnB"}

package/dist/design/audit/patches/severity-enforcement.js

@@ -0,0 +1,42 @@
+/**
+ * Severity enforcement — every major/critical finding MUST have ≥1 valid patch.
+ *
+ * Findings without patches are downgraded to `minor` with an explanatory note.
+ * This runs as a post-processing step after patch validation.
+ */
+/**
+ * Given a list of findings and the set of valid patches (post-validation),
+ * downgrade any major/critical finding that has no valid patch to `minor`.
+ */
+export function enforcePatchPolicy(findings, validPatchIds) {
+    const downgraded = [];
+    const updated = findings.map(f => {
+        if (f.severity !== 'major' && f.severity !== 'critical')
+            return f;
+        const v2Finding = f;
+        const patches = v2Finding.patches ?? [];
+        const hasValidPatch = patches.some(p => validPatchIds.has(p.patchId));
+        if (hasValidPatch)
+            return f;
+        downgraded.push({
+            findingId: f.id,
+            fromSeverity: f.severity,
+            toSeverity: 'minor',
+            reason: patches.length === 0
+                ? 'no patches proposed'
+                : 'all proposed patches failed validation (before not in snapshot, missing locator, or delta out of range)',
+        });
+        return {
+            ...f,
+            severity: 'minor',
+            suggestion: [
+                f.suggestion,
+                '[auto-downgraded: patch required for major/critical severity]',
+            ]
+                .filter(Boolean)
+                .join(' '),
+        };
+    });
+    return { findings: updated, downgraded };
+}
+//# sourceMappingURL=severity-enforcement.js.map

package/dist/design/audit/patches/severity-enforcement.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"severity-enforcement.js","sourceRoot":"","sources":["../../../../src/design/audit/patches/severity-enforcement.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAgBH;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAChC,QAAyB,EACzB,aAA0B;IAE1B,MAAM,UAAU,GAAwB,EAAE,CAAA;IAE1C,MAAM,OAAO,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE;QAC/B,IAAI,CAAC,CAAC,QAAQ,KAAK,OAAO,IAAI,CAAC,CAAC,QAAQ,KAAK,UAAU;YAAE,OAAO,CAAC,CAAA;QAEjE,MAAM,SAAS,GAAG,CAA0C,CAAA;QAC5D,MAAM,OAAO,GAAG,SAAS,CAAC,OAAO,IAAI,EAAE,CAAA;QACvC,MAAM,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAA;QAErE,IAAI,aAAa;YAAE,OAAO,CAAC,CAAA;QAE3B,UAAU,CAAC,IAAI,CAAC;YACd,SAAS,EAAE,CAAC,CAAC,EAAE;YACf,YAAY,EAAE,CAAC,CAAC,QAAQ;YACxB,UAAU,EAAE,OAAO;YACnB,MAAM,EAAE,OAAO,CAAC,MAAM,KAAK,CAAC;gBAC1B,CAAC,CAAC,qBAAqB;gBACvB,CAAC,CAAC,yGAAyG;SAC9G,CAAC,CAAA;QAEF,OAAO;YACL,GAAG,CAAC;YACJ,QAAQ,EAAE,OAAgB;YAC1B,UAAU,EAAE;gBACV,CAAC,CAAC,UAAU;gBACZ,+DAA+D;aAChE;iBACE,MAAM,CAAC,OAAO,CAAC;iBACf,IAAI,CAAC,GAAG,CAAC;SACb,CAAA;IACH,CAAC,CAAC,CAAA;IAEF,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,UAAU,EAAE,CAAA;AAC1C,CAAC"}

package/dist/design/audit/patches/validate.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Patch validator — given a parsed patch and the page snapshot text, verify
+ * that the patch is grounded and applyable.
+ *
+ * Rules:
+ *   - `diff.before` must appear as a case-sensitive substring of the snapshot.
+ *     Agents apply patches literally; a hallucinated `before` is unfixable.
+ *   - `target` must carry at least one locator (cssSelector | filePath |
+ *     componentName). Without one the agent has nowhere to apply.
+ *   - `estimatedDelta.delta` must be in [-3, 3]. Larger claims are almost
+ *     always over-confident on a 1–10 scale.
+ */
+import type { Patch } from '../score-types.js';
+export type ValidationReason = 'before-not-in-snapshot' | 'target-missing-locator' | 'estimated-delta-out-of-range' | 'before-empty';
+export interface ValidationResult {
+    valid: boolean;
+    reasons: ValidationReason[];
+}
+/**
+ * Validate a single patch against a page snapshot. Reports all issues in one
+ * pass so callers can surface every problem to the agent at once.
+ *
+ * Snapshot-anchoring rule: `diff.before` must appear verbatim in the page
+ * snapshot ONLY when the patch targets the snapshot itself — i.e. `target.scope`
+ * is `html` or `structural`. CSS / TSX / Tailwind patches modify source files
+ * the audit can't see, so the snapshot check would always fail for them. The
+ * agent verifies those patches at apply-time against the actual source file.
+ */
+export declare function validatePatch(patch: Patch, snapshot: string): ValidationResult;
+/**
+ * Validate a list of patches and partition into valid / invalid.
+ */
+export declare function validatePatches(patches: Patch[], snapshot: string): {
+    valid: Patch[];
+    invalid: Array<{
+        patch: Patch;
+        reasons: ValidationReason[];
+    }>;
+};
+//# sourceMappingURL=validate.d.ts.map

package/dist/design/audit/patches/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../../../src/design/audit/patches/validate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAA;AAE9C,MAAM,MAAM,gBAAgB,GACxB,wBAAwB,GACxB,wBAAwB,GACxB,8BAA8B,GAC9B,cAAc,CAAA;AAElB,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,OAAO,CAAA;IACd,OAAO,EAAE,gBAAgB,EAAE,CAAA;CAC5B;AAKD;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,GAAG,gBAAgB,CAyB9E;AAED;;GAEG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,KAAK,EAAE,EAChB,QAAQ,EAAE,MAAM,GACf;IAAE,KAAK,EAAE,KAAK,EAAE,CAAC;IAAC,OAAO,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,KAAK,CAAC;QAAC,OAAO,EAAE,gBAAgB,EAAE,CAAA;KAAE,CAAC,CAAA;CAAE,CASnF"}