@resolveio/server-lib 22.3.42 → 22.3.43

package/src/util/ai-qa-policy.ts

@@ -1,812 +0,0 @@
-export type ResolveIOQaPolicyContext =
-	| 'support_ticket'
-	| 'aicoder_dashboard'
-	| 'ai_terminal'
-	| 'general';
-
-export interface ResolveIOQaPolicyOptions {
-	context?: ResolveIOQaPolicyContext;
-	includeDevServerRules?: boolean;
-	qaRepairEnabled?: boolean;
-	qaEvidenceRequired?: boolean;
-	qaDistinctScreenshotRequired?: boolean;
-	qaFailFastCompile?: boolean;
-	qaLiveDataRequired?: boolean;
-	qaSelfRepairMaxWaves?: number;
-	currentRoute?: string;
-	currentContextMode?: string;
-	customInstructions?: string[];
-}
-
-export interface ResolveIORunnerBasicsOptions extends ResolveIOQaPolicyOptions {
-	includeQaPolicy?: boolean;
-	includeTokenDiscipline?: boolean;
-	includeDependencyBootstrap?: boolean;
-	includeRepairLoop?: boolean;
-	includeEvidenceContract?: boolean;
-	maxContextBullets?: number;
-	maxRepairWaves?: number;
-}
-
-export interface ResolveIORunnerPromptInput extends ResolveIORunnerBasicsOptions {
-	objective?: string;
-	blockers?: string[];
-	relevantFiles?: string[];
-	evidence?: string[];
-	priorSummary?: string;
-	latestFailure?: string;
-	maxBlockers?: number;
-	maxFiles?: number;
-	maxEvidence?: number;
-	maxTextChars?: number;
-}
-
-export interface ResolveIORunnerContract {
-	context: ResolveIOQaPolicyContext;
-	sections: {
-		runnerBasics: string[];
-		tokenDiscipline: string[];
-		dependencyBootstrap: string[];
-		repairLoop: string[];
-		qaPolicy: string[];
-		evidenceContract: string[];
-		finalNotes: string[];
-	};
-	rules: string[];
-	promptLines: string[];
-}
-
-export interface ResolveIORunnerPromptBundle extends ResolveIORunnerContract {
-	objective: string;
-	contextLines: string[];
-	repairLines: string[];
-	fullPromptLines: string[];
-}
-
-export interface ResolveIORunnerRepairPlan {
-	blockerClass: string;
-	sourceGate: string;
-	targetFiles: string[];
-	lineHints: string[];
-	failureEvidence: string[];
-	requiredProof: string[];
-	repairRecipe: string[];
-	selfGateCommands: string[];
-	passingCondition: string;
-}
-
-export interface ResolveIORunnerRepairTargetOverride {
-	preferredSuffixes?: string[];
-	fallbackFiles?: string[];
-}
-
-export interface ResolveIORunnerRepairPlanInput extends ResolveIORunnerBasicsOptions {
-	blockers?: string[];
-	changedFiles?: string[];
-	gateSource?: string;
-	targetFileOverrides?: Record<string, ResolveIORunnerRepairTargetOverride>;
-}
-
-export interface ResolveIORunnerRepairContinuationInput {
-	currentBlockers?: string[];
-	previousBlockers?: string[];
-	activeContractBlockers?: string[];
-	currentAttempt?: number;
-	maxAttempts?: number;
-	currentRepairWaveCount?: number;
-	maxRepairWaves?: number;
-	diffHash?: string;
-	evidenceHash?: string;
-	previousDiffHash?: string;
-	previousEvidenceHash?: string;
-}
-
-export type ResolveIORunnerRepairContinuationAction =
-	| 'continue_attempt'
-	| 'start_repair_wave'
-	| 'park_repeated_blocker'
-	| 'park_no_progress'
-	| 'park_repair_wave_budget';
-
-export interface ResolveIORunnerRepairContinuationDecision {
-	action: ResolveIORunnerRepairContinuationAction;
-	repeatedBlockers: string[];
-	newBlockers: string[];
-	normalizedCurrentBlockers: string[];
-	nextAttempt: number;
-	nextRepairWaveCount: number;
-	reason: string;
-}
-
-function normalizeOptionalString(value: any): string {
-	return String(value || '').replace(/\s+/g, ' ').trim();
-}
-
-function normalizePositiveInteger(value: any, fallback: number, min: number, max: number): number {
-	const numeric = Number(value);
-	if (!Number.isFinite(numeric)) {
-		return fallback;
-	}
-	const rounded = Number(numeric.toFixed(0));
-	return Math.max(min, Math.min(max, rounded));
-}
-
-function normalizeTextLine(value: any, maxChars: number): string {
-	return normalizeOptionalString(value).slice(0, maxChars).trim();
-}
-
-function normalizeTextList(values: any, limit: number, maxChars: number): string[] {
-	if (!Array.isArray(values)) {
-		return [];
-	}
-	const result: string[] = [];
-	for (const value of values) {
-		const normalized = normalizeTextLine(value, maxChars);
-		if (normalized && !result.includes(normalized)) {
-			result.push(normalized);
-		}
-		if (result.length >= limit) {
-			break;
-		}
-	}
-	return result;
-}
-
-export function normalizeResolveIOQaPolicyOptions(options: ResolveIOQaPolicyOptions = {}): Required<Omit<ResolveIOQaPolicyOptions, 'currentRoute' | 'currentContextMode' | 'customInstructions'>> & {
-	currentRoute: string;
-	currentContextMode: string;
-	customInstructions: string[];
-} {
-	return {
-		context: options.context || 'general',
-		includeDevServerRules: options.includeDevServerRules === true,
-		qaRepairEnabled: options.qaRepairEnabled !== false,
-		qaEvidenceRequired: options.qaEvidenceRequired !== false,
-		qaDistinctScreenshotRequired: options.qaDistinctScreenshotRequired !== false,
-		qaFailFastCompile: options.qaFailFastCompile !== false,
-		qaLiveDataRequired: options.qaLiveDataRequired !== false,
-		qaSelfRepairMaxWaves: normalizePositiveInteger(options.qaSelfRepairMaxWaves, 3, 1, 6),
-		currentRoute: normalizeOptionalString(options.currentRoute),
-		currentContextMode: normalizeOptionalString(options.currentContextMode),
-		customInstructions: Array.isArray(options.customInstructions)
-			? options.customInstructions.map(normalizeOptionalString).filter(Boolean).slice(0, 12)
-			: []
-	};
-}
-
-export function buildResolveIOQaPolicyRules(options: ResolveIOQaPolicyOptions = {}): string[] {
-	const policy = normalizeResolveIOQaPolicyOptions(options);
-	const rules: string[] = [];
-	if (policy.includeDevServerRules) {
-		rules.push(
-			'When browser/localhost QA needs long-running commands like `npm run server`, `npm run client`, `npm run dev`, `ng serve`, `vite`, or `nodemon`, start them as managed background processes with log files and PIDs; do not leave foreground dev-server commands as the active shell tool.',
-			'Before localhost/browser QA, source `.resolveio-support-tools/env.sh` or `.resolveio-ai-runner-tools/env.sh` when present. It supplies shared EC2 browser cache settings, `PUPPETEER_EXECUTABLE_PATH`/`CHROME_BIN`, Mongo wrappers, and non-conflicting localhost QA ports/URLs.',
-			'For ResolveIO app login during browser QA, use the shared AI-runner auth bootstrap when staged: `node ./.resolveio-support-tools/qa-auth-bootstrap.js <project-root> /target-route`, `node ./.resolveio-ai-runner-tools/qa-auth-bootstrap.js <project-root> /target-route`, or the same command from an app root with `../`. It must use the exact localhost client origin, call `/login` then `/accessToken`, clear service workers/cache/IndexedDB/local storage, seed auth storage, and emit `qa-artifacts/auth-bootstrap-result.json` plus a screenshot.',
-			'When launching Puppeteer or Playwright on workers, pass `executablePath: process.env.PUPPETEER_EXECUTABLE_PATH || process.env.CHROME_BIN` if either env var is set. Do not download a fresh browser before checking these env vars and `PUPPETEER_CACHE_DIR`.',
-			'Use the managed-server pattern for localhost QA: `command > .build-output/<name>.log 2>&1 & PID=$!; trap "kill $PID 2>/dev/null || true" EXIT; wait for the port with curl; run browser checks; then kill/wait the PID`. Prefer `npm run client` or `./start_client.sh`; those scripts honor `RESOLVEIO_SUPPORT_QA_CLIENT_PORT` and `PORT`. Never run `ng serve ... | tee ...` or another dev server as a foreground command.'
-		);
-	}
-	if (policy.qaFailFastCompile) {
-		rules.push('Before browser QA, run the fastest compile/type/startup checks that can prove the app can load. Fix compile/startup failures before launching browser QA.');
-	}
-	if (policy.qaRepairEnabled) {
-		rules.push(`If compile, startup, browser, or live-data QA fails, run a targeted repair wave for the exact failing route/action/data state, then rerun that same failed step before continuing. Limit self-repair to ${policy.qaSelfRepairMaxWaves} focused waves before returning the precise blocker.`);
-	}
-	if (policy.qaLiveDataRequired) {
-		rules.push('For bug fixes and data/publication changes, test against available live app data or a faithful seeded record; do not rely only on static inspection when the user reported a runtime workflow problem.');
-		rules.push('For import/export/form-submit/data workflows, QA must drive the actual customer action with representative data: capture the relevant starting state, the dialog/form/file selection or action state, and the submitted/resulting state with a row/count/value assertion that proves the bug or feature works.');
-		rules.push('A navigation-only screenshot of an empty page, shell, table header, or unchanged screen is not sufficient evidence for data workflow fixes. If the page has no records, seed or choose a faithful test record and identify the record or fixture used.');
-	}
-	rules.push('Use desktop screenshots at a wide/full-screen viewport by default: 1920x1080 or wider. Do not use narrow/tablet/mobile screenshots unless the approved ticket is specifically mobile/responsive.');
-	rules.push('For desktop QA, verify the top navigation is in its normal desktop state and not wrapped, collapsed, open, or covering the workflow. For mobile-specific QA, explicitly use a mobile viewport and close the mobile menu unless the menu behavior itself is being proven.');
-	if (policy.qaDistinctScreenshotRequired) {
-		rules.push('Capture one screenshot or trace for each distinct changed customer-facing feature, screen, workflow state, or data result. Do not repeat equivalent screenshots for multiple records unless record-specific behavior changed.');
-	}
-	rules.push('Every screenshot artifact must include a short customer-facing caption explaining what the screenshot proves. Captions should describe the workflow state, such as Before, Ready to import, Submitted result, or Mobile menu closed.');
-	if (policy.qaEvidenceRequired) {
-		rules.push('Final notes must list the exact QA command, route, account/data used, screenshot/trace/log paths, and result for each changed behavior; if browser QA is not applicable, say why and provide the compile/data proof used instead.');
-	}
-	if (policy.currentRoute) {
-		rules.push(`Current app context route from the AI terminal is ${policy.currentRoute}${policy.currentContextMode ? ` (${policy.currentContextMode})` : ''}; start QA there when the request refers to this page or current screen.`);
-	}
-	rules.push(...policy.customInstructions);
-	return rules;
-}
-
-export function buildResolveIORunnerBasicsRules(options: ResolveIORunnerBasicsOptions = {}): string[] {
-	return buildResolveIORunnerContract(options).rules;
-}
-
-export function buildResolveIORunnerContract(options: ResolveIORunnerBasicsOptions = {}): ResolveIORunnerContract {
-	const maxContextBullets = normalizePositiveInteger(options.maxContextBullets, 8, 3, 20);
-	const maxRepairWaves = normalizePositiveInteger(
-		options.maxRepairWaves ?? options.qaSelfRepairMaxWaves,
-		3,
-		1,
-		6
-	);
-	const context = options.context || 'general';
-	const runnerBasics = [
-		'Use repo-local patterns first: read the closest existing implementation, matching tests, model/schema, method/publication, and UI route before editing.',
-		'Make the smallest complete change that satisfies the request; avoid broad refactors, config churn, dependency changes, and generated-file edits unless the workflow explicitly requires regeneration.',
-		'Before returning, state what changed, how it was verified, remaining blockers, and exact artifact paths in final notes.'
-	];
-	const tokenDiscipline = options.includeTokenDiscipline !== false
-		? [
-			`Keep context lean: summarize prior history into at most ${maxContextBullets} bullets, retrieve specific files on demand, and do not paste full logs, lockfiles, generated files, or stale ticket/email chains unless they are the current blocker evidence.`,
-			'Prefer targeted search/read commands over loading broad directories. If a command returns noisy output, summarize the useful lines and continue with narrower reads.',
-			'On retries, carry only the active blocker contract, changed-file list, relevant diff/evidence summary, and latest failing command output. Do not restart with a clean-slate mega prompt.',
-			'Stop autonomous retries when the same normalized blocker repeats without meaningful diff or evidence improvement; park with a precise blocker instead of burning tokens.'
-		]
-		: [];
-	const dependencyBootstrap = options.includeDependencyBootstrap !== false
-		? [
-			'Reuse existing dependency caches and hydrated node_modules when available. Prefer npm install --force with the configured npm cache; do not use npm ci unless the workflow explicitly requires it.',
-			'Before reinstalling or downloading browsers, check the existing workspace cache, shared node_modules, PUPPETEER_EXECUTABLE_PATH, CHROME_BIN, PUPPETEER_CACHE_DIR, and project-provided bootstrap scripts.'
-		]
-		: [];
-	const repairLoop = options.includeRepairLoop !== false
-		? [
-			`Use targeted repair waves: compile/startup blocker, browser route/action blocker, data/publication blocker, and review blocker each get a focused repair, then rerun the exact failed step. Limit this to ${maxRepairWaves} focused waves before returning a precise blocker.`,
-			'Repair all instances of a detected blocker class in the touched scope, not only the first occurrence.'
-		]
-		: [];
-	const qaPolicy = options.includeQaPolicy !== false
-		? buildResolveIOQaPolicyRules({
-			...options,
-			qaSelfRepairMaxWaves: maxRepairWaves
-		})
-		: [];
-	const evidenceContract = options.includeEvidenceContract !== false
-		? [
-			'Evidence must be customer/workflow oriented: routes, buttons, pages, data states, screenshots/traces, command results, and assertions. Do not expose internal file names, backend paths, stack traces, or implementation chatter in customer-facing text.',
-			'For UI-facing changes, capture one screenshot or trace per distinct changed feature/workflow; for data-only changes, provide live-data or seeded-data assertion proof.',
-			'For import, upload, export, form submit, calculation, publication, or persistence fixes, proof must show the before/action/after workflow state and a concrete row/count/value assertion. Empty shell screenshots do not count as proof.',
-			'Desktop proof screenshots must use a wide/full-screen viewport, normally 1920x1080 or wider, with navigation closed/unwrapped unless the ticket is specifically about mobile or menu behavior.',
-			'Each screenshot must have a customer-facing caption that says what the image proves; these captions are used in validation emails.'
-		]
-		: [];
-	const finalNotes = [
-		'Final notes must include: changed behavior, touched functional areas, exact commands run, exact QA route/data state, screenshot/trace/log paths, and remaining blockers if any.',
-		'If work is parked, final notes must name the blocker class, last failing command/artifact, why another autonomous attempt would repeat, and the smallest manual action needed.'
-	];
-	const sections = {
-		runnerBasics,
-		tokenDiscipline,
-		dependencyBootstrap,
-		repairLoop,
-		qaPolicy,
-		evidenceContract,
-		finalNotes
-	};
-	const rules = [
-		...runnerBasics,
-		...tokenDiscipline,
-		...dependencyBootstrap,
-		...repairLoop,
-		...qaPolicy,
-		...evidenceContract,
-		...finalNotes
-	];
-	const promptLines = [
-		`ResolveIO shared runner contract (${context}):`,
-		...rules.map((rule) => `- ${rule}`)
-	];
-	return {
-		context,
-		sections,
-		rules,
-		promptLines
-	};
-}
-
-export function buildResolveIORunnerPromptLines(options: ResolveIORunnerBasicsOptions = {}): string[] {
-	return buildResolveIORunnerContract(options).promptLines;
-}
-
-export function buildResolveIORunnerPromptBundle(input: ResolveIORunnerPromptInput = {}): ResolveIORunnerPromptBundle {
-	const contract = buildResolveIORunnerContract(input);
-	const maxTextChars = normalizePositiveInteger(input.maxTextChars, 900, 160, 2400);
-	const objective = normalizeTextLine(input.objective, maxTextChars)
-		|| 'Complete the requested ResolveIO runner task with minimal, verified changes.';
-	const priorSummary = normalizeTextLine(input.priorSummary, maxTextChars);
-	const latestFailure = normalizeTextLine(input.latestFailure, maxTextChars);
-	const blockers = normalizeTextList(input.blockers, normalizePositiveInteger(input.maxBlockers, 5, 1, 12), maxTextChars);
-	const relevantFiles = normalizeTextList(input.relevantFiles, normalizePositiveInteger(input.maxFiles, 12, 1, 30), 260);
-	const evidence = normalizeTextList(input.evidence, normalizePositiveInteger(input.maxEvidence, 8, 1, 20), maxTextChars);
-	const contextLines = [
-		`Objective: ${objective}`,
-		...(priorSummary ? [`Prior summary: ${priorSummary}`] : []),
-		...(latestFailure ? [`Latest failure: ${latestFailure}`] : []),
-		...(blockers.length ? ['Active blockers:', ...blockers.map((line) => `- ${line}`)] : []),
-		...(relevantFiles.length ? ['Relevant files:', ...relevantFiles.map((line) => `- ${line}`)] : []),
-		...(evidence.length ? ['Known evidence:', ...evidence.map((line) => `- ${line}`)] : [])
-	];
-	const repairLines = blockers.length
-		? [
-			'Mandatory repair contract:',
-			'- Address each active blocker before unrelated work.',
-			'- For each blocker, mark resolved, proven false, or blocked.',
-			'- Attach code, data, command, browser, screenshot, or trace proof for each blocker.',
-			'- If a blocker repeats with no meaningful diff/evidence change, park instead of starting another broad attempt.'
-		]
-		: [];
-	const fullPromptLines = [
-		...contract.promptLines,
-		'',
-		'Runner task context:',
-		...contextLines,
-		...(repairLines.length ? ['', ...repairLines] : [])
-	];
-	return {
-		...contract,
-		objective,
-		contextLines,
-		repairLines,
-		fullPromptLines
-	};
-}
-
-export function buildResolveIORunnerRepairPromptLines(input: ResolveIORunnerPromptInput = {}): string[] {
-	return buildResolveIORunnerPromptBundle(input).repairLines;
-}
-
-export function normalizeResolveIORunnerBlocker(entry: string): string {
-	return String(entry || '')
-		.toLowerCase()
-		.replace(/:[0-9]+(?=\b|[);,.\s])/g, ':#')
-		.replace(/\bline\s+[0-9]+\b/g, 'line #')
-		.replace(/\blines?\s+[0-9]+\s*[-–]\s*[0-9]+\b/g, 'lines #')
-		.replace(/\battempt\s+[0-9]+\b/g, 'attempt #')
-		.replace(/\s+/g, ' ')
-		.trim();
-}
-
-function uniqueNormalizedResolveIORunnerBlockers(values: any): string[] {
-	if (!Array.isArray(values)) {
-		return [];
-	}
-	return Array.from(new Set(
-		values
-			.map((entry) => normalizeResolveIORunnerBlocker(String(entry || '')))
-			.filter(Boolean)
-	));
-}
-
-export function findRepeatedResolveIORunnerBlockers(previousBlockers: string[] = [], currentBlockers: string[] = []): string[] {
-	const previous = new Set(uniqueNormalizedResolveIORunnerBlockers(previousBlockers));
-	if (!previous.size) {
-		return [];
-	}
-	return Array.from(new Set(
-		(currentBlockers || [])
-			.map((entry) => String(entry || '').trim())
-			.filter((entry) => previous.has(normalizeResolveIORunnerBlocker(entry)))
-	));
-}
-
-export function decideResolveIORunnerRepairContinuation(
-	input: ResolveIORunnerRepairContinuationInput = {}
-): ResolveIORunnerRepairContinuationDecision {
-	const currentBlockers = (input.currentBlockers || [])
-		.map((entry) => String(entry || '').trim())
-		.filter(Boolean);
-	const normalizedCurrentBlockers = uniqueNormalizedResolveIORunnerBlockers(currentBlockers);
-	const previousBlockers = uniqueNormalizedResolveIORunnerBlockers(input.previousBlockers || []);
-	const activeContractBlockers = uniqueNormalizedResolveIORunnerBlockers(input.activeContractBlockers || []);
-	const priorBlockers = new Set([...previousBlockers, ...activeContractBlockers]);
-	const repeatedBlockers = findRepeatedResolveIORunnerBlockers(Array.from(priorBlockers), currentBlockers);
-	const repeated = new Set(repeatedBlockers.map((entry) => normalizeResolveIORunnerBlocker(entry)));
-	const newBlockers = currentBlockers.filter((entry) => !repeated.has(normalizeResolveIORunnerBlocker(entry)));
-	const currentAttempt = normalizePositiveInteger(input.currentAttempt, 1, 1, 100);
-	const maxAttempts = normalizePositiveInteger(input.maxAttempts, 3, 1, 100);
-	const currentRepairWaveCount = normalizePositiveInteger(input.currentRepairWaveCount, 0, 0, 100);
-	const maxRepairWaves = normalizePositiveInteger(input.maxRepairWaves, 3, 0, 100);
-	const diffHash = normalizeOptionalString(input.diffHash);
-	const evidenceHash = normalizeOptionalString(input.evidenceHash);
-	const previousDiffHash = normalizeOptionalString(input.previousDiffHash);
-	const previousEvidenceHash = normalizeOptionalString(input.previousEvidenceHash);
-	const noProgress = !!previousDiffHash
-		&& !!previousEvidenceHash
-		&& previousDiffHash === diffHash
-		&& previousEvidenceHash === evidenceHash;
-	const nextAttempt = currentAttempt + 1;
-	const nextRepairWaveCount = currentRepairWaveCount + 1;
-	if (noProgress) {
-		return {
-			action: 'park_no_progress',
-			repeatedBlockers,
-			newBlockers,
-			normalizedCurrentBlockers,
-			nextAttempt,
-			nextRepairWaveCount,
-			reason: 'Targeted repair made no meaningful diff or evidence progress.'
-		};
-	}
-	if (repeatedBlockers.length) {
-		return {
-			action: 'park_repeated_blocker',
-			repeatedBlockers,
-			newBlockers,
-			normalizedCurrentBlockers,
-			nextAttempt,
-			nextRepairWaveCount,
-			reason: 'The same normalized blocker repeated after a targeted repair.'
-		};
-	}
-	const shouldStartNewWave = currentBlockers.length > 0
-		&& (
-			activeContractBlockers.length > 0
-			|| currentAttempt >= maxAttempts
-		);
-	if (shouldStartNewWave) {
-		if (currentRepairWaveCount >= maxRepairWaves) {
-			return {
-				action: 'park_repair_wave_budget',
-				repeatedBlockers,
-				newBlockers,
-				normalizedCurrentBlockers,
-				nextAttempt,
-				nextRepairWaveCount,
-				reason: `Repair wave budget exhausted (${currentRepairWaveCount}/${maxRepairWaves}).`
-			};
-		}
-		return {
-			action: 'start_repair_wave',
-			repeatedBlockers,
-			newBlockers,
-			normalizedCurrentBlockers,
-			nextAttempt: 2,
-			nextRepairWaveCount,
-			reason: 'A prior blocker was cleared and a new blocker appeared; start a focused repair wave instead of consuming the final attempt.'
-		};
-	}
-	return {
-		action: 'continue_attempt',
-		repeatedBlockers,
-		newBlockers,
-		normalizedCurrentBlockers,
-		nextAttempt,
-		nextRepairWaveCount: currentRepairWaveCount,
-		reason: 'Continue with the next targeted attempt.'
-	};
-}
-
-export function classifyResolveIORunnerBlocker(blocker: string): string {
-	const text = String(blocker || '');
-	if (/database call inside loop|findOne.*inside loop|query inside loop/i.test(text)) {
-		return 'db_call_inside_loop';
-	}
-	if (/inventory transaction parity|inventory transactions? are correct|inventory transaction creation\/reversal|inventory drift|reverse(?:s| old).*inventory|custom chemical lines?/i.test(text)) {
-		return 'inventory_transaction_parity';
-	}
-	if (/company\/global default line-item surcharge|customer surcharge override|surcharge override.*default|global\/company surcharge|fallback\/override|first active surcharge/i.test(text)) {
-		return 'surcharge_default_precedence';
-	}
-	if (/\bTS\d{4}\b[\s\S]{0,220}\bExpected\s+0\s+arguments?\b[\s\S]{0,160}\bgot\s+1\b/i.test(text)
-		&& /\b(publication|publications\.ts|subscribe|user_specific|ForUser|yardsForUser|customerNotifications|notificationCenter)\b/i.test(text)) {
-		return 'user_specific_publication_argument_mismatch';
-	}
-	if (/\b(publication signature mismatch|generated publication signature|publication wrapper)\b[\s\S]{0,220}\b(?:yardsForUser|[A-Za-z0-9_]*ForUser)\b[\s\S]{0,160}\bcompile errors?\b/i.test(text)
-		|| /\b(?:yardsForUser|[A-Za-z0-9_]*ForUser)\b[\s\S]{0,180}\bcompile errors?\b[\s\S]{0,180}\b(publication|publications\.ts|signature|wrapper)\b/i.test(text)) {
-		return 'user_specific_publication_argument_mismatch';
-	}
-	if (/\b(user_specific|user-specific)\b[\s\S]{0,220}\b(Expected\s+0\s+arguments?|got\s+1|passes?\s+1\s+argument|publication wrapper)\b/i.test(text)) {
-		return 'user_specific_publication_argument_mismatch';
-	}
-	if (/focused verification evidence|Behavior-level test\/QA evidence|browser QA|screenshot|trace artifacts?|Billing Dashboard.*create\/edit|server-side evidence|Validation evidence/i.test(text)) {
-		return 'support_qa_evidence';
-	}
-	if (/Approved scope requirement is not covered|approved .* scope lacks/i.test(text)) {
-		return 'approved_scope_missing';
-	}
-	if (/UI-facing ticket needs|browser\/localhost QA|local\/browser QA/i.test(text)) {
-		return 'ui_qa_missing';
-	}
-	if (/Report\/export ticket needs|report rows|export behavior/i.test(text)) {
-		return 'report_export_missing';
-	}
-	if (/Generated .* changed without a matching/i.test(text)) {
-		return 'generated_file_mismatch';
-	}
-	if (/No repository files changed|no verifiable PR fix/i.test(text)) {
-		return 'no_repo_diff';
-	}
-	if (/QA compile preflight|ng serve failed|Angular ng serve failed|Completion build verification failed|build failed|TypeScript check failed|TypeScript compile|lint failed|TS\d{4}|Cannot find module/i.test(text)) {
-		return 'completion_build_failed';
-	}
-	return 'reviewer_blocker';
-}
-
-export function extractResolveIORunnerRepairLineHints(blocker: string): string[] {
-	const hints: string[] = [];
-	const lineMatch = String(blocker || '').match(/(?:line\s+|:)([0-9]+)\b/i);
-	if (lineMatch) {
-		hints.push(`line ${lineMatch[1]}`);
-	}
-	const loopMatch = String(blocker || '').match(/loop starts near line\s+([0-9]+)/i);
-	if (loopMatch) {
-		hints.push(`loop starts near line ${loopMatch[1]}`);
-	}
-	return Array.from(new Set(hints));
-}
-
-export function extractResolveIORunnerRepairTargetFiles(blocker: string, changedFiles: string[] = []): string[] {
-	const files = new Set<string>();
-	const text = String(blocker || '');
-	const pathPattern = /(?:^|\s)([A-Za-z0-9_.-]+(?:\/[A-Za-z0-9_.-]+)+\.(?:ts|tsx|js|jsx|html|scss|css|json|md))/g;
-	let match: RegExpExecArray | null;
-	while ((match = pathPattern.exec(text))) {
-		files.add(match[1].replace(/\\/g, '/'));
-	}
-	for (const filePath of changedFiles || []) {
-		const normalized = String(filePath || '').trim().replace(/\\/g, '/');
-		if (normalized && (text.includes(normalized) || text.includes(normalized.replace(/^[^/]+\//, '')))) {
-			files.add(normalized);
-		}
-	}
-	return Array.from(files).slice(0, 8);
-}
-
-export function selectResolveIORunnerRepairTargetFiles(
-	changedFiles: string[] = [],
-	preferredSuffixes: string[] = [],
-	fallbackFiles: string[] = []
-): string[] {
-	const suffixes = (preferredSuffixes || [])
-		.map((entry) => String(entry || '').trim().replace(/\\/g, '/').replace(/^\/+/, ''))
-		.filter(Boolean);
-	const matched = new Set<string>();
-	for (const filePath of changedFiles || []) {
-		const normalized = String(filePath || '').trim().replace(/\\/g, '/');
-		if (normalized && suffixes.some((suffix) => normalized === suffix || normalized.endsWith(`/${suffix}`))) {
-			matched.add(normalized);
-		}
-	}
-	return (matched.size
-		? Array.from(matched)
-		: fallbackFiles.map((entry) => String(entry || '').trim().replace(/\\/g, '/')).filter(Boolean)
-	).slice(0, 12);
-}
-
-export function sanitizeResolveIORunnerRepairPlans(value: any): ResolveIORunnerRepairPlan[] {
-	return Array.isArray(value)
-		? value.map((entry: any) => ({
-			blockerClass: String(entry?.blockerClass || '').trim(),
-			sourceGate: String(entry?.sourceGate || '').trim(),
-			targetFiles: Array.isArray(entry?.targetFiles) ? entry.targetFiles.map((item: any) => String(item || '').trim()).filter(Boolean).slice(0, 20) : [],
-			lineHints: Array.isArray(entry?.lineHints) ? entry.lineHints.map((item: any) => String(item || '').trim()).filter(Boolean).slice(0, 20) : [],
-			failureEvidence: Array.isArray(entry?.failureEvidence) ? entry.failureEvidence.map((item: any) => String(item || '').trim()).filter(Boolean).slice(0, 20) : [],
-			requiredProof: Array.isArray(entry?.requiredProof) ? entry.requiredProof.map((item: any) => String(item || '').trim()).filter(Boolean).slice(0, 20) : [],
-			repairRecipe: Array.isArray(entry?.repairRecipe) ? entry.repairRecipe.map((item: any) => String(item || '').trim()).filter(Boolean).slice(0, 20) : [],
-			selfGateCommands: Array.isArray(entry?.selfGateCommands) ? entry.selfGateCommands.map((item: any) => String(item || '').trim()).filter(Boolean).slice(0, 20) : [],
-			passingCondition: String(entry?.passingCondition || '').trim()
-		})).filter((entry: ResolveIORunnerRepairPlan) => entry.blockerClass || entry.failureEvidence.length)
-		: [];
-}
-
-function getResolveIORunnerRepairTargetOverride(
-	options: ResolveIORunnerRepairPlanInput,
-	blockerClass: string
-): ResolveIORunnerRepairTargetOverride | null {
-	const override = options.targetFileOverrides?.[blockerClass];
-	if (!override) {
-		return null;
-	}
-	return {
-		preferredSuffixes: Array.isArray(override.preferredSuffixes) ? override.preferredSuffixes : [],
-		fallbackFiles: Array.isArray(override.fallbackFiles) ? override.fallbackFiles : []
-	};
-}
-
-function applyResolveIORunnerRepairTargetOverride(
-	plan: ResolveIORunnerRepairPlan,
-	options: ResolveIORunnerRepairPlanInput,
-	blockerClass: string
-): ResolveIORunnerRepairPlan {
-	const override = getResolveIORunnerRepairTargetOverride(options, blockerClass);
-	if (!override || plan.targetFiles.length) {
-		return plan;
-	}
-	return {
-		...plan,
-		targetFiles: selectResolveIORunnerRepairTargetFiles(
-			options.changedFiles || [],
-			override.preferredSuffixes || [],
-			override.fallbackFiles || []
-		)
-	};
-}
-
-export function buildResolveIORunnerRepairPlans(input: ResolveIORunnerRepairPlanInput = {}): ResolveIORunnerRepairPlan[] {
-	const changedFiles = Array.isArray(input.changedFiles) ? input.changedFiles : [];
-	const sourceGate = String(input.gateSource || 'pre_review_or_reviewer').trim() || 'pre_review_or_reviewer';
-	const qaRules = buildResolveIORunnerBasicsRules({
-		...input,
-		context: input.context || 'general',
-		includeDevServerRules: input.includeDevServerRules === true,
-		maxContextBullets: input.maxContextBullets || 8
-	});
-	return Array.from(new Set((input.blockers || []).map((entry) => String(entry || '').trim()).filter(Boolean))).map((blocker) => {
-		const blockerClass = classifyResolveIORunnerBlocker(blocker);
-		const base: ResolveIORunnerRepairPlan = {
-			blockerClass,
-			sourceGate,
-			targetFiles: extractResolveIORunnerRepairTargetFiles(blocker, changedFiles),
-			lineHints: extractResolveIORunnerRepairLineHints(blocker),
-			failureEvidence: [blocker].filter(Boolean).slice(0, 8),
-			requiredProof: [],
-			repairRecipe: [],
-			selfGateCommands: [],
-			passingCondition: ''
-		};
-		if (blockerClass === 'db_call_inside_loop') {
-			return applyResolveIORunnerRepairTargetOverride({
-				...base,
-				requiredProof: [
-					'Show the database lookup is batched before the loop, or prove the flagged call is not a database collection call.',
-					'Cite the exact file/function and before-vs-after loop/query shape in Repair Execution Notes.',
-					'Confirm the changed diff no longer has any per-item database collection call in any loop body in the touched/target server files.'
-				],
-				repairRecipe: [
-					'Inspect every loop in the touched/target server files and identify all database collection calls inside those loops.',
-					'Move collection reads before loops using batched `$in` queries, map results by id/key, then use the map inside loops.',
-					'Move writes out of loops using batched `bulkWrite`/multi-update operations prepared inside the loop and executed after the loop.',
-					'If the call is a local array/helper and not a database call, prove that with the declaration/import path and leave the code unchanged.',
-					'Keep the behavior identical except for eliminating every per-item database call.'
-				],
-				selfGateCommands: [
-					'git diff HEAD -- <target file>',
-					'rg -n "for .*\\{|\\.forEach|for \\(" <target file>',
-					'rg -n "\\.(find|findOne|findOneAsync|count|countDocuments|update|updateOne|updateMany|insert|insertOne|bulkWrite|remove|deleteOne|deleteMany)\\(" <target file>'
-				],
-				passingCondition: 'No loop in the touched/target server files has a database collection call in its body, or final notes prove each flagged call is not a database call.'
-			}, input, blockerClass);
-		}
-		if (blockerClass === 'report_export_missing') {
-			return applyResolveIORunnerRepairTargetOverride({
-				...base,
-				requiredProof: ['Prove report rows, filters, totals/grouping, and export behavior, or cite ticket evidence that export is out of scope.'],
-				repairRecipe: ['Exercise the report/export path and record evidence for each report dimension requested by the ticket.'],
-				selfGateCommands: ['Run the report/export verification command or browser flow for the ticket.'],
-				passingCondition: 'Final notes prove rows, filters, totals/grouping, and export behavior or a ticket-backed out-of-scope decision.'
-			}, input, blockerClass);
-		}
-		if (blockerClass === 'inventory_transaction_parity') {
-			return applyResolveIORunnerRepairTargetOverride({
-				...base,
-				requiredProof: [
-					'Prove non-Manual Delivery and Truck Treat custom chemical lines create inventory relief transactions on invoice create.',
-					'Prove invoice edit reverses old custom chemical effects and applies the new custom chemical effects.',
-					'Prove invoice remove/delete reverses the same non-Manual custom chemical inventory effects.'
-				],
-				repairRecipe: [
-					'Start in server/src/methods/invoices.ts and trace Manual inventory behavior before changing the non-Manual path.',
-					'Reuse the existing inventory transaction helper shape instead of creating a parallel inventory writer.',
-					'Handle all custom chemical lines in one sweep: create, edit, and remove for Delivery and Truck Treat invoices.',
-					'Do not stop after fixing only create; the reviewer blocker includes edit and remove reversal.'
-				],
-				selfGateCommands: [
-					'git diff HEAD -- server/src/methods/invoices.ts server/src/methods/inventory-transactions.ts',
-					'rg -n "is_custom_line_item|addInventoryTransaction|removeInvoice|editInvoice|custom chemical" server/src/methods/invoices.ts',
-					'Run or add a focused server/data assertion covering create, edit, and remove inventory transactions for non-Manual custom chemical lines.'
-				],
-				passingCondition: 'Create, edit, and remove paths for non-Manual custom chemical invoice lines all have inventory transaction proof.'
-			}, input, blockerClass);
-		}
-		if (blockerClass === 'surcharge_default_precedence') {
-			return applyResolveIORunnerRepairTargetOverride({
-				...base,
-				requiredProof: [
-					'Show the persisted company/global default surcharge owner, not just the first active surcharge item.',
-					'Show precedence is customer override when active, then company/global default when active, then empty/none when inactive or unset.',
-					'Show at least one override customer and one default customer path in verification evidence.'
-				],
-				repairRecipe: [
-					'Find the surcharge default selector and replace any first-active-item fallback with an explicit persisted default setting.',
-					'Keep customer override storage separate from the company/global default setting.',
-					'Reject inactive surcharge items during both override and default fallback.',
-					'Cover unset and inactive settings with safe empty/none behavior.'
-				],
-				selfGateCommands: [
-					'git diff HEAD -- angular/app/manage/item angular/app/widgets/dialog/dialog.adjust-customer.content.ts server/src/collections server/src/models',
-					'rg -n "line_item_surcharge|surcharge|id_line_item_surcharge_override|default" angular/app server/src',
-					'Run or add a focused fallback/override assertion for active override, active company default, inactive override/default, and unset default.'
-				],
-				passingCondition: 'Customer override -> company/global default -> none precedence is persisted and verified.'
-			}, input, blockerClass);
-		}
-		if (blockerClass === 'support_qa_evidence') {
-			return applyResolveIORunnerRepairTargetOverride({
-				...base,
-				requiredProof: [
-					'Include browser route and screenshot/trace artifact paths for each distinct changed customer-facing feature or workflow state.',
-					'Do not duplicate screenshots across multiple customers unless the customer-specific override/fallback behavior is the feature being proven.',
-					'Include data/assertion evidence for requested persistence, calculations, and side effects.',
-					'For import/export/form-submit/data workflow fixes, include before/action/after screenshots or trace steps plus the exact row/count/value assertion proving the submitted data changed as expected.',
-					'Reject empty page/table/header screenshots as insufficient unless the approved requirement is explicitly an empty-state UI.',
-					'Use a 1920x1080-or-wider desktop viewport for screenshots unless the ticket explicitly requests mobile/responsive behavior; desktop nav must be closed and not wrapped over the workflow.',
-					'Provide a customer-facing caption for each screenshot that explains the workflow state and proof shown.',
-					'If browser QA cannot start, include the exact startup blocker and the compile/preflight command output.'
-				],
-				repairRecipe: [
-					...qaRules,
-					'Upload or preserve screenshots/trace paths so the PR and support ticket can reference them.'
-				],
-				selfGateCommands: [
-					'Run the support QA compile/startup preflight.',
-					'Run the ticket-specific browser QA click-through and capture screenshots/trace artifacts.',
-					'Record artifact paths and data assertions in final notes.'
-				],
-				passingCondition: 'Final notes include one QA screenshot/trace path per distinct changed feature plus data assertions for the approved scope.'
-			}, input, blockerClass);
-		}
-		if (blockerClass === 'approved_scope_missing') {
-			return applyResolveIORunnerRepairTargetOverride({
-				...base,
-				requiredProof: ['Add one Self-Review Checklist bullet for the exact missing approved requirement with code/data/browser proof.'],
-				repairRecipe: ['Verify the missing approved requirement, then implement or document done/not applicable/blocked with proof.'],
-				selfGateCommands: ['Review final notes for exact approved requirement text and proof artifact.'],
-				passingCondition: 'Every missing approved requirement is explicitly mapped to done/not applicable/blocked with proof.'
-			}, input, blockerClass);
-		}
-		if (blockerClass === 'ui_qa_missing') {
-			return applyResolveIORunnerRepairTargetOverride({
-				...base,
-				requiredProof: ['Provide browser route plus screenshot/trace/video path, or a precise LOCALHOST_QA_PLAYBOOK startup/access blocker.'],
-				repairRecipe: ['Run local/browser QA for the failing UI route after the fix, or document the exact startup/access blocker.'],
-				selfGateCommands: ['source .resolveio-support-tools/env.sh if present', 'Run the ticket-specific localhost/browser QA command or capture blocker.'],
-				passingCondition: 'Final notes contain browser QA artifact evidence or a concrete local startup/access blocker.'
-			}, input, blockerClass);
-		}
-		if (blockerClass === 'generated_file_mismatch') {
-			return applyResolveIORunnerRepairTargetOverride({
-				...base,
-				requiredProof: ['Show generated client file changes correspond to matching server method/publication source changes.'],
-				repairRecipe: ['Either update the server owner and regenerate the companion file, or revert the orphan generated file change.'],
-				selfGateCommands: ['git diff HEAD -- angular/app/methods.ts angular/app/publications.ts server/src/methods server/src/publications'],
-				passingCondition: 'No generated client file is changed without its source server owner change.'
-			}, input, blockerClass);
-		}
-		if (blockerClass === 'user_specific_publication_argument_mismatch') {
-			return applyResolveIORunnerRepairTargetOverride({
-				...base,
-				requiredProof: [
-					'List every failing call site and show each one was fixed, not just the first TypeScript error.',
-					'Show whether each call needs the current logged-in user or an explicit other user/driver id.',
-					'Show generated angular/app/publications.ts came from server/src/publications source and was not hand-edited as the behavioral fix.'
-				],
-				repairRecipe: [
-					'user_specific publications inject the logged-in socket user as the first server parameter; generated client wrappers should remove only that injected parameter.',
-					'Before changing call sites, inspect the source publication signature. If a client can pass a target user/driver, make the source explicit as function(id_current_user: string, id_user?: string) and regenerate.',
-					'Only remove a client argument when the publication truly uses the injected current user only; otherwise preserve explicit target-user/driver calls such as yardsForUser(id_driver).',
-					'Do not hand-edit generated angular/app/publications.ts to accept the injected id_user again; fix source publications/call sites, then regenerate.',
-					'Search the whole app for the failing wrapper name and repair all argument-passing calls in the same pass.'
-				],
-				selfGateCommands: [
-					'rg -n "\\b[A-Za-z0-9_]*ForUser\\s*\\([^)]+" angular/app server/src',
-					'rg -n "\\byardsForUser\\s*\\([^)]+" angular/app server/src',
-					'Run the method/publication generator if server publication source changed.',
-					'Rerun the exact TypeScript/Angular compile command that failed.'
-				],
-				passingCondition: 'Generated user_specific wrappers strip only the injected current-user parameter, explicit target-user arguments still compile where required, and the exact compile command exits 0.'
-			}, input, blockerClass);
-		}
-		if (blockerClass === 'completion_build_failed') {
-			return applyResolveIORunnerRepairTargetOverride({
-				...base,
-				requiredProof: ['Include the failing command, root cause, fix, and passing rerun output.'],
-				repairRecipe: ['Fix the compile/test failure directly, then rerun the exact failing command.'],
-				selfGateCommands: ['Rerun the exact completion/build command shown in the blocker.'],
-				passingCondition: 'The exact previously failing build/test command passes or is blocked with concrete environment evidence.'
-			}, input, blockerClass);
-		}
-		return applyResolveIORunnerRepairTargetOverride({
-			...base,
-			requiredProof: ['Resolve, prove false, or block this reviewer/gate blocker with concrete code/data/browser proof.'],
-			repairRecipe: ['Inspect the cited file/evidence, make the smallest supported fix, and cite before-vs-after proof.'],
-			selfGateCommands: ['git diff HEAD --stat', 'Run the ticket-specific verification for this blocker.'],
-			passingCondition: 'The blocker text no longer applies and final notes include concrete proof.'
-		}, input, blockerClass);
-	});
-}