@hamp10/agentforge 0.2.21 → 0.2.23

package/scripts/check-task-semantics.js

@@ -0,0 +1,911 @@
+#!/usr/bin/env node
+
+import assert from 'node:assert/strict';
+import { execFileSync } from 'node:child_process';
+import { existsSync, lstatSync, mkdtempSync, mkdirSync, readFileSync, readlinkSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { deflateSync } from 'node:zlib';
+import { extractExplicitScope } from '../src/taskSemantics.js';
+import { AgentForgeWorker } from '../src/worker.js';
+import { OpenClawCLI } from '../src/OpenClawCLI.js';
+
+const cases = [
+  {
+    text: 'On the example.com listing pages for Alpha and Beta the layout is off',
+    slugs: ['alpha', 'beta'],
+    absent: ['example-com', 'layout'],
+    pageOnly: true,
+  },
+  {
+    text: 'Work on the example.com listing pages for Alpha.ai and Beta.ai. Make only those two listing pages meet the visual and content quality of the rest of the site.',
+    slugs: ['alpha-ai', 'beta-ai'],
+    absent: ['example-com', 'visual', 'quality'],
+    pageOnly: true,
+  },
+  {
+    text: 'Work on the Example.com listing pages for AlphaBoard and BetaMatch. Delete and rebuild those two listing page implementations from a clean start, preserving the same URLs and site conventions. Fix the readability and design issues. Only change those two listing pages.',
+    slugs: ['alphaboard', 'betamatch'],
+    absent: ['example-com', 'delete', 'rebuild', 'readability', 'design', 'urls', 'site'],
+    pageOnly: true,
+  },
+  {
+    text: 'Work on Alpha pages for readability',
+    slugs: ['alpha'],
+    absent: ['readability'],
+    pageOnly: true,
+  },
+  {
+    text: 'Improve pages for Foo and The Bar without touching shared files',
+    slugs: ['foo', 'bar'],
+    absent: ['shared'],
+    pageOnly: true,
+  },
+  {
+    text: 'Improve Alpha.ai pages for readability',
+    slugs: ['alpha-ai'],
+    absent: ['readability'],
+    pageOnly: true,
+  },
+  {
+    text: 'The pages are broken',
+    slugs: [],
+    pageOnly: false,
+  },
+  {
+    text: 'Compare the listing pages and report issues',
+    slugs: [],
+    pageOnly: false,
+  },
+  {
+    text: `[Platform task guide quality gates — these are mandatory for this task type]
+UI work should not be hero-only or color-only.
+
+[System context:
+- Platform: AgentForge.ai. Dashboard: https://agentforgeai-production.up.railway.app/dashboard.
+]
+
+The task is: "There are readability and design issues on the Example.com listing pages for AlphaDeck and BetaGrid. Fix them."`,
+    slugs: ['alphadeck', 'betagrid'],
+    absent: ['agentforge-ai', 'agentforgeai-production-up-railway', 'hero', 'color', 'readability', 'example-com'],
+    pageOnly: true,
+  },
+];
+
+for (const item of cases) {
+  const scope = extractExplicitScope(item.text);
+  assert.equal(scope.pageOnly, item.pageOnly, `${item.text}: pageOnly`);
+  assert.deepEqual(
+    [...new Set(scope.slugs)].sort(),
+    [...new Set(item.slugs)].sort(),
+    `${item.text}: slugs`
+  );
+  for (const absent of item.absent || []) {
+    assert.equal(scope.slugs.includes(absent), false, `${item.text}: unexpected ${absent}`);
+  }
+}
+
+const git = (cwd, args) => execFileSync('git', args, { cwd, encoding: 'utf-8', stdio: 'pipe' }).trim();
+
+const writeRgbPng = (filePath, width, height, sample) => {
+  const rows = [];
+  for (let y = 0; y < height; y += 1) {
+    const row = Buffer.alloc(1 + (width * 3));
+    row[0] = 0;
+    for (let x = 0; x < width; x += 1) {
+      const rgb = sample(x, y);
+      const idx = 1 + (x * 3);
+      row[idx] = rgb[0];
+      row[idx + 1] = rgb[1];
+      row[idx + 2] = rgb[2];
+    }
+    rows.push(row);
+  }
+  const chunk = (type, data = Buffer.alloc(0)) => {
+    const out = Buffer.alloc(12 + data.length);
+    out.writeUInt32BE(data.length, 0);
+    out.write(type, 4, 4, 'ascii');
+    data.copy(out, 8);
+    out.writeUInt32BE(0, 8 + data.length);
+    return out;
+  };
+  const ihdr = Buffer.alloc(13);
+  ihdr.writeUInt32BE(width, 0);
+  ihdr.writeUInt32BE(height, 4);
+  ihdr[8] = 8;
+  ihdr[9] = 2;
+  ihdr[10] = 0;
+  ihdr[11] = 0;
+  ihdr[12] = 0;
+  writeFileSync(filePath, Buffer.concat([
+    Buffer.from('89504e470d0a1a0a', 'hex'),
+    chunk('IHDR', ihdr),
+    chunk('IDAT', deflateSync(Buffer.concat(rows))),
+    chunk('IEND'),
+  ]));
+};
+
+const makeShallowUiFixture = () => {
+  const repo = mkdtempSync(path.join(tmpdir(), 'agentforge-ui-quality-'));
+  const domainsDir = path.join(repo, 'public_html', 'domains');
+  const targetCssDir = path.join(domainsDir, 'css');
+  const nestedDomainsDir = path.join(repo, path.basename(repo), 'public_html', 'domains');
+  mkdirSync(domainsDir, { recursive: true });
+  mkdirSync(targetCssDir, { recursive: true });
+  mkdirSync(nestedDomainsDir, { recursive: true });
+  const legacyExternalCss = Array.from({ length: 30 }, (_, i) =>
+    `.legacy-alpha-shell-${i} { background: #${String(220000 + i).slice(0, 6)}; border-radius: ${i + 2}px; padding: ${i + 12}px; color: #102030; }`
+  ).join('\n');
+  writeFileSync(path.join(targetCssDir, 'alpha.css'), legacyExternalCss);
+  for (const name of ['alpha', 'beta']) {
+    const baselineHtml = [
+      '<!doctype html>',
+      '<html>',
+      '<head>',
+      '<!-- Google tag (gtag.js) -->',
+      '<style>',
+      '/* Page-specific styles */',
+      '.page { color: #111; }',
+      '</style>',
+      '</head>',
+      '<body>',
+      `<main><section><h1>${name}</h1><p>Existing page content with enough structure to be a baseline.</p></section></main>`,
+      '</body>',
+      '</html>',
+    ].join('\n');
+    writeFileSync(path.join(domainsDir, `${name}.html`), baselineHtml);
+    writeFileSync(path.join(nestedDomainsDir, `${name}.html`), baselineHtml);
+  }
+  git(repo, ['init']);
+  git(repo, ['config', 'user.email', 'test@example.com']);
+  git(repo, ['config', 'user.name', 'AgentForge Test']);
+  git(repo, ['add', '.']);
+  git(repo, ['commit', '-m', 'baseline']);
+  const head = git(repo, ['rev-parse', 'HEAD']);
+
+  const shallowCss = Array.from({ length: 28 }, (_, i) =>
+    `.hero-polish-${i} { color: #${String(100000 + i).slice(0, 6)}; padding: ${i + 1}px; margin: ${i}px; box-shadow: 0 0 ${i + 2}px rgba(0,0,0,.1); }`
+  ).join('\n') + '\n.list-heading { font-size: 1.5rem; /* Standardizing h3 size */ }';
+  for (const name of ['alpha', 'beta']) {
+    writeFileSync(path.join(domainsDir, `${name}.html`), [
+      '<!doctype html>',
+      '<html>',
+      `<head><style>${shallowCss}</style></head>`,
+      '<body>',
+      '<main>',
+      `<section class="property-hero hero-polish" style="padding: 6rem; color: white;">`,
+      `<div class="hero-badge">${name} category</div>`,
+      `<h1 class="property-title">${name}</h1>`,
+      '<div class="hero-stats">',
+      '<span class="hero-stat">AI</span>',
+      '<span class="hero-stat">Premium</span>',
+      '<span class="hero-stat">Ready</span>',
+      '</div>',
+      '</section>',
+      '</main>',
+      '</body>',
+      '</html>',
+    ].join('\n'));
+  }
+  git(repo, ['add', '.']);
+  git(repo, ['commit', '-m', 'shallow styled pages']);
+  return { repo, head, legacyExternalCss };
+};
+
+const fixture = makeShallowUiFixture();
+try {
+  const worker = Object.create(AgentForgeWorker.prototype);
+  worker.cli = { isAnthropicApiKey: (key) => /^sk-ant-/i.test(String(key || '')) };
+  const cli = Object.create(OpenClawCLI.prototype);
+  const projectsRoot = mkdtempSync(path.join(tmpdir(), 'agentforge-project-list-'));
+  let agentWorkspace = null;
+  try {
+    const targetProject = path.join(projectsRoot, 'Hamp.com');
+    const appProject = path.join(projectsRoot, 'Tiny App');
+    const staleStaticRoot = path.join(projectsRoot, 'public_html');
+    const logsDir = path.join(projectsRoot, 'logs');
+    agentWorkspace = mkdtempSync(path.join(tmpdir(), 'agentforge-agent-workspace-'));
+    mkdirSync(path.join(targetProject, '.git'), { recursive: true });
+    mkdirSync(appProject, { recursive: true });
+    mkdirSync(staleStaticRoot, { recursive: true });
+    mkdirSync(logsDir, { recursive: true });
+    writeFileSync(path.join(appProject, 'package.json'), '{"scripts":{"start":"vite"}}');
+    writeFileSync(path.join(staleStaticRoot, 'index.html'), '<main>stale deploy copy</main>');
+    symlinkSync(staleStaticRoot, path.join(agentWorkspace, 'public_html'), 'dir');
+
+    assert.deepEqual(
+      worker._listProjectDirectoryEntries(projectsRoot),
+      ['Hamp.com', 'Tiny App'],
+      'project discovery should exclude generic source/deploy folders unless they are standalone projects'
+    );
+    assert.deepEqual(
+      worker._findMentionedProjects(projectsRoot, 'Work on the Hamp.com listing pages for Alpha and Beta'),
+      ['Hamp.com'],
+      'task project matching should ignore stale sibling public_html folders'
+    );
+    worker._syncProjectWorkspaceLinks(agentWorkspace, projectsRoot, {
+      resolvedTaskProject: { name: 'Hamp.com', path: targetProject },
+    });
+    assert.equal(lstatSync(path.join(agentWorkspace, 'Hamp.com')).isSymbolicLink(), true);
+    assert.equal(readlinkSync(path.join(agentWorkspace, 'Hamp.com')), targetProject);
+    assert.equal(
+      existsSync(path.join(agentWorkspace, 'public_html')),
+      false,
+      'scoped project workspaces should remove stale generic sibling symlinks'
+    );
+    assert.doesNotMatch(
+      readFileSync(path.join(agentWorkspace, 'PROJECTS.md'), 'utf-8'),
+      /public_html/i,
+      'scoped project manifest should not advertise sibling deploy/source roots'
+    );
+  } finally {
+    rmSync(projectsRoot, { recursive: true, force: true });
+    if (agentWorkspace) rmSync(agentWorkspace, { recursive: true, force: true });
+  }
+  const visionPlan = worker._resolveVisualAnalysisModels({
+    taskModel: 'google/gemini-2.5-flash',
+    imageModel: 'openai/gpt-4.1',
+    fallbackVisionModels: ['google/gemini-2.5-pro'],
+    flowConfig: {},
+    providerKeys: { google: 'google-key', openai: 'openai-key' },
+  });
+  assert.equal(
+    visionPlan.primary,
+    'google/gemini-2.5-flash',
+    'visual analysis should prefer the routed task model over a generic configured vision model when both can see images'
+  );
+  assert.deepEqual(
+    visionPlan.fallbacks,
+    ['openai/gpt-4.1', 'google/gemini-2.5-pro'],
+    'visual analysis should keep configured vision models as fallback candidates'
+  );
+  assert.match(
+    worker._resolveRunnableConfiguredModel('openai/gpt-4.1', { openai: 'openai-key' }, new Set(), { guardrails: { allowed_providers: ['google'] } }).error,
+    /not allowed by this flow/i,
+    'flow allowed-provider guardrails should block disallowed configured models'
+  );
+  assert.equal(
+    worker._modelProviderAvailable('anthropic/claude-sonnet-4-6', { anthropic: 'claude-oauth-token' }),
+    false,
+    'anthropic provider availability must require a Console API key, not a claude.ai session token'
+  );
+  assert.equal(
+    worker._modelProviderAvailable('anthropic/claude-sonnet-4-6', { anthropic: 'sk-ant-test' }),
+    true,
+    'anthropic provider availability should accept real Console API keys'
+  );
+  assert.deepEqual(
+    worker._unavailableConfiguredVisionAnalysisModels({
+      imageModel: 'openai/gpt-4.1',
+      fallbackVisionModels: ['google/gemini-2.5-pro'],
+      flowConfig: {},
+      providerKeys: { google: 'google-key' },
+    }),
+    ['openai/gpt-4.1'],
+    'configured vision-analysis models without runnable provider credentials should be reported instead of silently dropped'
+  );
+  await assert.rejects(
+    () => worker._resolveFlowRoute('Route this implementation task.', [], {
+      router_model: 'openai/gpt-4.1',
+      routes: [{ condition: 'intent_code', model: 'google/gemini-2.5-flash' }],
+      guardrails: { allowed_providers: ['openai', 'google'] },
+    }, { google: 'google-key' }),
+    /Configured flow router model cannot run/i,
+    'configured router/classifier models should fail clearly when their provider is unavailable'
+  );
+  const message = 'Improve the listing pages for Alpha and Beta so they feel polished.';
+  const baseline = [{ root: fixture.repo, head: fixture.head }];
+  assert.match(
+    worker._formatScopedUiTargetSetReminder(message),
+    /Requested scoped UI targets: alpha, beta/i,
+    'multi-target UI quality retries should preserve the full scoped target set'
+  );
+  assert.match(
+    worker._buildScopedUiTargetSetNudge(baseline, message),
+    /one delivery set/i,
+    'scoped UI target nudge should tell retries to handle all named targets together'
+  );
+  assert.match(
+    worker._formatUiImplementationArtifactNudge([
+      { repo: fixture.repo, path: 'public_html/domains/alpha.html', issue: 'inline source comment', source: 'working tree', line: '/* improved contrast */' },
+    ]),
+    /not sufficient/i,
+    'patch-artifact feedback should not imply source cleanup alone completes UI quality work'
+  );
+  assert.match(
+    worker._buildShallowUiSurfaceNudge(baseline, message),
+    /dominated by hero, CTA, typography, color, or spacing tweaks/i,
+    'shallow hero/inline-style UI diff should be rejected'
+  );
+  const artifactNudge = worker._buildUiImplementationArtifactNudge(baseline, message);
+  assert.match(
+    artifactNudge,
+    /inline style attribute/i,
+    'new inline style attributes should be treated as UI patch artifacts'
+  );
+  assert.match(
+    artifactNudge,
+    /Page-local <style> blocks or page-owned scoped stylesheets are acceptable/i,
+    'UI artifact nudge should not make agents infer that scoped page-local CSS is forbidden'
+  );
+  assert.doesNotMatch(
+    artifactNudge,
+    /Standardizing h3 size/i,
+    'neutral structural UI comments should not distract repair loops as patch artifacts'
+  );
+  const alphaFixturePath = path.join(fixture.repo, 'public_html', 'domains', 'alpha.html');
+  const alphaFixtureCurrent = readFileSync(alphaFixturePath, 'utf-8');
+  writeFileSync(
+    alphaFixturePath,
+    alphaFixtureCurrent.replace('<head><style>', '<head>\n<!-- Google tag (gtag.js) -->\n<style>')
+  );
+  assert.equal(
+    worker._findUiImplementationArtifactChanges(baseline, message).some(w => /Google tag/i.test(w.line)),
+    false,
+    'full-run patch artifact validation should not flag baseline comments that survive or are reintroduced by a rewrite'
+  );
+  writeFileSync(alphaFixturePath, alphaFixtureCurrent);
+  const metaUrlHtml = alphaFixtureCurrent.replace(
+    '</head>',
+    '<meta property="og:url" content="https://example.com/domains/alpha">\n</head>'
+  );
+  writeFileSync(alphaFixturePath, metaUrlHtml);
+  assert.equal(
+    worker._findUiImplementationArtifactChanges(baseline, message).some(w => /example\.com\/domains\/alpha/i.test(w.line)),
+    false,
+    'patch artifact validation should not treat https:// URLs in added markup as source comments'
+  );
+  writeFileSync(alphaFixturePath, alphaFixtureCurrent);
+  const patchNarrationCommentHtml = alphaFixtureCurrent.replace(
+    '</style>',
+    '/* Fix clipped heading issue from visual warning */\n</style>'
+  );
+  writeFileSync(alphaFixturePath, patchNarrationCommentHtml);
+  assert.equal(
+    worker._findUiImplementationArtifactChanges(baseline, message).some(w => /Fix clipped heading issue/i.test(w.line)),
+    true,
+    'patch artifact validation should still reject comments that narrate the repair rationale'
+  );
+  writeFileSync(alphaFixturePath, alphaFixtureCurrent);
+  const cssDir = path.join(fixture.repo, 'public_html', 'css');
+  mkdirSync(cssDir, { recursive: true });
+  const scopedCssFile = path.join(cssDir, 'alpha.css');
+  writeFileSync(scopedCssFile, '.alpha-page { color: #111; }');
+  assert.equal(
+    worker._findScopeDriftRepoChanges(baseline, message).length,
+    0,
+    'page-owned scoped stylesheet files should not be restored as out-of-scope work'
+  );
+  rmSync(scopedCssFile, { force: true });
+  const sharedCssFile = path.join(cssDir, 'domain-detail.css');
+  writeFileSync(sharedCssFile, '.shared-detail { color: #111; }');
+  assert.match(
+    worker._formatScopeDriftNudge(worker._findScopeDriftRepoChanges(baseline, message)),
+    /domain-detail\.css/i,
+    'shared stylesheet files should still be reported as out-of-scope for scoped page work'
+  );
+  rmSync(sharedCssFile, { force: true });
+  const directOldHtml = '<!doctype html><html><body><main><section class="hero"><h1>Alpha</h1><p>Existing body copy.</p></section></main></body></html>';
+  const directInlineStyleHtml = '<!doctype html><html><body><main><section class="hero" style="padding: 4rem; color: white;"><h1>Alpha</h1><p>Existing body copy.</p></section></main></body></html>';
+  assert.throws(
+    () => cli._validateDirectUiFileContent(
+      path.join(fixture.repo, 'public_html', 'domains', 'alpha.html'),
+      directInlineStyleHtml,
+      { task: message, oldContent: directOldHtml }
+    ),
+    /new inline style attribute/i,
+    'direct UI edits should reject newly introduced inline style attributes before full-run verification'
+  );
+  assert.throws(
+    () => cli._validateDirectUiFileContent(
+      path.join(fixture.repo, 'public_html', 'domains', 'alpha.html'),
+      directInlineStyleHtml,
+      { task: message, oldContent: directOldHtml }
+    ),
+    /page-local <style> blocks or page-owned scoped stylesheets/i,
+    'direct UI validation should steer agents toward scoped CSS instead of no styling'
+  );
+  assert.doesNotThrow(
+    () => cli._validateDirectUiFileContent(
+      path.join(fixture.repo, 'public_html', 'domains', 'alpha.html'),
+      directInlineStyleHtml,
+      { task: message, oldContent: directInlineStyleHtml }
+    ),
+    'direct UI validation should not block preexisting unchanged inline style attributes'
+  );
+  const directBaselineCommentHtml = '<!doctype html><html><head><!-- Google tag (gtag.js) --><style>/* Page-specific styles */ .page { color: #111; }</style></head><body><main><section><h1>Alpha</h1><p>Existing page content with enough structure to be a baseline.</p></section></main></body></html>';
+  const directReintroducedBaselineCommentHtml = '<!doctype html><html><head><!-- Google tag (gtag.js) --><style>/* Page-specific styles */ .hero { padding: 4rem; }</style></head><body><main><section class="hero"><h1>Alpha</h1><p>Existing body copy.</p></section></main></body></html>';
+  assert.doesNotThrow(
+    () => cli._validateDirectUiFileContent(
+      path.join(fixture.repo, 'public_html', 'domains', 'alpha.html'),
+      directReintroducedBaselineCommentHtml,
+      { task: message, oldContent: directBaselineCommentHtml }
+    ),
+    'direct UI validation should allow tracked baseline comments to be reintroduced after whole-file rewrites'
+  );
+  const directSoftCommentHtml = '<!doctype html><html><body><style>.hero { border-top: 2px solid rgba(16, 185, 129, 0.5); /* Softened border */ }</style><main><section class="hero"><h1>Alpha</h1><p>Existing body copy.</p></section></main></body></html>';
+  assert.doesNotThrow(
+    () => cli._validateDirectUiFileContent(
+      path.join(fixture.repo, 'public_html', 'domains', 'alpha.html'),
+      directSoftCommentHtml,
+      { task: message, oldContent: directOldHtml }
+    ),
+    'direct UI validation should allow neutral structural source comments instead of forcing agents into comment cleanup loops'
+  );
+  const directPatchNarrationCommentHtml = '<!doctype html><html><body><style>.hero { border-top: 2px solid rgba(16, 185, 129, 0.5); /* Fix clipped hero issue from visual warning */ }</style><main><section class="hero"><h1>Alpha</h1><p>Existing body copy.</p></section></main></body></html>';
+  assert.throws(
+    () => cli._validateDirectUiFileContent(
+      path.join(fixture.repo, 'public_html', 'domains', 'alpha.html'),
+      directPatchNarrationCommentHtml,
+      { task: message, oldContent: directOldHtml }
+    ),
+    /new UI source comment|Fix clipped hero issue/i,
+    'direct UI edits should still reject source comments that narrate the patch rationale'
+  );
+  const directLicenseCommentHtml = '<!doctype html><html><body><style>/*! @license MIT */ .hero { padding: 4rem; }</style><main><section class="hero"><h1>Alpha</h1><p>Existing body copy.</p></section></main></body></html>';
+  assert.doesNotThrow(
+    () => cli._validateDirectUiFileContent(
+      path.join(fixture.repo, 'public_html', 'domains', 'alpha.html'),
+      directLicenseCommentHtml,
+      { task: message, oldContent: directOldHtml }
+    ),
+    'direct UI validation should allow standard tooling/license source comments'
+  );
+  const protectedReplacementFile = path.join(fixture.repo, 'public_html', 'domains', 'alpha.html');
+  const protectedReplacementOriginal = readFileSync(protectedReplacementFile, 'utf-8');
+  await assert.rejects(
+    () => cli._runDirectTool(
+      'test-agent',
+      'write_file',
+      { path: protectedReplacementFile },
+      fixture.repo,
+      { task: message }
+    ),
+    /requires a string content payload/i,
+    'direct write_file should reject missing content instead of truncating the target'
+  );
+  assert.equal(
+    readFileSync(protectedReplacementFile, 'utf-8'),
+    protectedReplacementOriginal,
+    'missing-content write_file rejection should leave the existing file unchanged'
+  );
+  await assert.rejects(
+    () => cli._runDirectTool(
+      'test-agent',
+      'write_file',
+      { path: protectedReplacementFile, content: '' },
+      fixture.repo,
+      { task: message }
+    ),
+    /replace existing non-empty file with empty content/i,
+    'direct write_file should reject empty replacement content for existing non-empty files'
+  );
+  assert.equal(
+    readFileSync(protectedReplacementFile, 'utf-8'),
+    protectedReplacementOriginal,
+    'empty replacement rejection should leave the existing file unchanged'
+  );
+  assert.throws(
+    () => cli._guardDirectFileWritePath(
+      path.join(fixture.repo, path.basename(fixture.repo), 'public_html', 'domains', 'alpha.html'),
+      fixture.repo,
+      { task: message }
+    ),
+    /nested duplicate of the current project/i,
+    'tracked nested duplicate page should be blocked when canonical scoped page exists'
+  );
+  assert.throws(
+    () => cli._guardDirectFileWritePath(
+      path.join(fixture.repo, 'public_html', 'alpha.html'),
+      fixture.repo,
+      { task: 'Work on the listing page for Alpha. Only change that listing page.' }
+    ),
+    /existing scoped page target/i,
+    'scoped page work should not create a new same-slug page when an existing scoped target page is present'
+  );
+  const extractedOldCss = Array.from({ length: 28 }, (_, i) =>
+    `.hero-polish-${i} { color: #${String(100000 + i).slice(0, 6)}; padding: ${i + 1}px; margin: ${i}px; box-shadow: 0 0 ${i + 2}px rgba(0,0,0,.1); }`
+  ).join('\n');
+  assert.throws(
+    () => cli._validateDirectUiFileContent(
+      path.join(fixture.repo, 'public_html', 'domains', 'css', 'alpha.css'),
+      extractedOldCss,
+      { task: 'Delete and rebuild the listing pages for Alpha and Beta from a clean start. Only change those listing pages.' }
+    ),
+    /move the old target-page CSS into a new page-owned stylesheet/i,
+    'clean-start scoped page work should reject extracting old target-page CSS into a new stylesheet'
+  );
+  assert.throws(
+    () => cli._validateDirectUiFileContent(
+      path.join(fixture.repo, 'public_html', 'domains', 'css', 'alpha.css'),
+      fixture.legacyExternalCss,
+      { task: 'Delete and rebuild the listing pages for Alpha and Beta from a clean start. Only change those listing pages.' }
+    ),
+    /reuse the old page-owned stylesheet/i,
+    'clean-start scoped page work should reject reusing an existing page-owned stylesheet unchanged'
+  );
+  const freshPageCss = [
+    '.alpha-shell { min-height: 100vh; background: #f8f6ef; color: #181818; }',
+    '.alpha-wrap { max-width: 1180px; margin: 0 auto; padding: 84px 28px; }',
+    '.alpha-kicker { font: 600 13px/1.2 Inter, sans-serif; letter-spacing: .12em; text-transform: uppercase; }',
+    '.alpha-title { font: 700 clamp(48px, 8vw, 108px)/.92 Georgia, serif; color: #191714; }',
+    '.alpha-summary { max-width: 720px; font-size: 22px; line-height: 1.55; color: #34312c; }',
+    '.alpha-panel { border: 1px solid #d8d0bf; background: #fffaf0; padding: 32px; }',
+    '.alpha-grid { display: grid; grid-template-columns: 1.2fr .8fr; gap: 32px; }',
+    '.alpha-stat { display: flex; justify-content: space-between; border-top: 1px solid #ded6c8; padding: 18px 0; }',
+    '.alpha-list { display: grid; gap: 18px; padding: 0; list-style: none; }',
+    '.alpha-list li { padding: 20px; background: #ffffff; border: 1px solid #e7dfd0; }',
+    '.alpha-cta { display: inline-flex; align-items: center; padding: 16px 22px; background: #191714; color: #fff; }',
+  ].join('\n');
+  assert.doesNotThrow(
+    () => cli._validateDirectUiFileContent(
+      path.join(fixture.repo, 'public_html', 'domains', 'css', 'alpha.css'),
+      freshPageCss,
+      { task: 'Delete and rebuild the listing pages for Alpha and Beta from a clean start. Only change those listing pages.' }
+    ),
+    'clean-start scoped page work should allow materially fresh page-owned CSS'
+  );
+  assert.throws(
+    () => cli._guardDirectBashCommand(
+      `rm ${path.basename(fixture.repo)}/public_html/domains/alpha.html`,
+      fixture.repo,
+      { task: message }
+    ),
+    /nested duplicate of the current project/i,
+    'scoped shell rm should reject nested duplicate project paths'
+  );
+  assert.throws(
+    () => cli._guardDirectBashCommand(
+      `cat > ${path.basename(fixture.repo)}/public_html/domains/alpha.html <<'EOF'\n<section>Alpha</section>\nEOF`,
+      fixture.repo,
+      { task: message }
+    ),
+    /nested duplicate of the current project/i,
+    'scoped shell redirection should reject nested duplicate project paths'
+  );
+  assert.doesNotThrow(
+    () => cli._guardDirectBashCommand(
+      `cat > public_html/domains/alpha.html <<'EOF'\n<section>Alpha</section>\nEOF`,
+      fixture.repo,
+      { task: message }
+    ),
+    'scoped shell redirection should allow canonical target page writes'
+  );
+  assert.doesNotThrow(
+    () => cli._guardDirectBashCommand(
+      'touch public_html/css/alpha.css',
+      fixture.repo,
+      { task: message }
+    ),
+    'scoped shell touch should allow page-owned CSS files'
+  );
+  assert.doesNotThrow(
+    () => cli._guardDirectBashCommand(
+      "sed -i '' 's/Existing/Updated/g' public_html/domains/alpha.html",
+      fixture.repo,
+      { task: message }
+    ),
+    'scoped shell sed should ignore the substitution script and allow canonical target page edits'
+  );
+  assert.throws(
+    () => cli._guardDirectBashCommand(
+      'touch public_html/css/domain-detail.css',
+      fixture.repo,
+      { task: message }
+    ),
+    /outside the requested task scope/i,
+    'scoped shell touch should reject shared CSS files outside the target names'
+  );
+  const seamPng = path.join(fixture.repo, 'dominant-seam.png');
+  writeRgbPng(seamPng, 900, 600, (x, y) => (
+    x < 450 && y > 300
+      ? [74, 92, 120]
+      : [26, 36, 50]
+  ));
+  assert.match(
+    cli._detectScreenshotVisualDiscontinuities(seamPng).join('\n'),
+    /hard-edged/i,
+    'screenshot discontinuity scan should catch large hard-edged rectangular seams'
+  );
+  const subtlePartialSurfacePng = path.join(fixture.repo, 'subtle-partial-surface.png');
+  writeRgbPng(subtlePartialSurfacePng, 1000, 700, (x, y) => {
+    if (x < 560 && y >= 120 && y < 520) return [34, 43, 59];
+    return [27, 36, 52];
+  });
+  assert.match(
+    cli._detectScreenshotVisualDiscontinuities(subtlePartialSurfacePng).join('\n'),
+    /partial-surface hard-edged background\/tint block edge/i,
+    'screenshot discontinuity scan should catch large subtle partial-surface tint blocks'
+  );
+} finally {
+  rmSync(fixture.repo, { recursive: true, force: true });
+}
+
+const openClawSource = readFileSync(new URL('../src/OpenClawCLI.js', import.meta.url), 'utf-8');
+const workerSource = readFileSync(new URL('../src/worker.js', import.meta.url), 'utf-8');
+const workerBinSource = readFileSync(new URL('../bin/agentforge.js', import.meta.url), 'utf-8');
+const defaultGuidesSource = readFileSync(new URL('../src/default-task-guides.js', import.meta.url), 'utf-8');
+const serverSource = readFileSync(new URL('../../../src/web-server-auth.js', import.meta.url), 'utf-8');
+const dashboardSource = readFileSync(new URL('../../../public/dashboard.js', import.meta.url), 'utf-8');
+assert.match(
+  openClawSource,
+  /unintended visual artifacts, broken layering, abrupt discontinuities/i,
+  'image visual analysis should require broad visual QA reasoning'
+);
+assert.match(
+  openClawSource,
+  /_detectScreenshotVisualDiscontinuities/i,
+  'browser verification should include generic screenshot discontinuity detection'
+);
+assert.match(
+  openClawSource,
+  /isScopedBrowserTarget && taskNeedsVisualAnalysis && \(!options\?\.afterMutation \|\| isLocalVerificationUrl\)/,
+  'scoped target screenshots should be scanned before edits as well as after local edits'
+);
+assert.match(
+  openClawSource,
+  /large hard-edged rectangular background\/overlay boundary across a dominant UI surface/i,
+  'screenshot discontinuity detection should fail large hard-edged visual breaks'
+);
+assert.match(
+  openClawSource,
+  /partial-surface hard-edged background\/tint block edge/i,
+  'screenshot discontinuity detection should fail subtle partial-surface tint blocks'
+);
+assert.match(
+  openClawSource,
+  /clippedTextBlocks/i,
+  'browser verification should include deterministic clipped-text detection'
+);
+assert.match(
+  openClawSource,
+  /clipped or partially cut-off text\/letterforms/i,
+  'image visual analysis should explicitly inspect cut-off text and letterforms'
+);
+assert.match(
+  openClawSource,
+  /Scrutinize large graphic\/background surfaces/i,
+  'image visual analysis should explicitly scrutinize broad rendered surfaces for accidental artifacts'
+);
+assert.match(
+  openClawSource,
+  /Treat low-contrast text anywhere.*even when the text is large/i,
+  'image visual analysis should not waive readability problems because text is large'
+);
+assert.match(
+  openClawSource,
+  /_markVisionModelTemporarilyUnavailable/i,
+  'vision verifier should avoid retrying temporarily unavailable image models on every screenshot'
+);
+assert.match(
+  openClawSource,
+  /isHttpUiReferenceUrl/i,
+  'comparable UI visual context should allow same-site non-target reference pages, not only localhost'
+);
+assert.match(
+  openClawSource,
+  /scopeViolationThisBatch \|\| comparableContextBlockThisBatch\) break/i,
+  'direct tool batches should stop after a scope/comparable-context block instead of spamming blocked writes'
+);
+assert.match(
+  openClawSource,
+  /imageGenerationModel/i,
+  'image generation model must be separate from visual-analysis model routing'
+);
+assert.match(
+  openClawSource,
+  /generationModelForHook/i,
+  '.image-model hook should only receive true image-generation models'
+);
+assert.match(
+  workerSource,
+  /_resolveVisualAnalysisModels/i,
+  'worker should resolve visual-analysis candidates after flow task routing'
+);
+assert.match(
+  workerSource,
+  /_unavailableConfiguredVisionAnalysisModels/i,
+  'worker should fail clearly when configured vision-analysis models are unavailable for visual tasks'
+);
+assert.match(
+  workerSource,
+  /The task model is first when it can inspect images/i,
+  'visual analysis should prefer the routed task model when it supports images'
+);
+assert.match(
+  workerSource,
+  /Configured flow router model cannot run/i,
+  'configured router/classifier models should be treated as required flow wiring'
+);
+assert.match(
+  workerSource,
+  /provider === 'anthropic'[\s\S]*isAnthropicApiKey/i,
+  'anthropic model availability should reject claude.ai OAuth/session tokens'
+);
+assert.match(
+  workerSource,
+  /_hydrateProviderKeysFromEnv/i,
+  'worker should hydrate configured-provider keys from worker env before model routing'
+);
+assert.match(
+  workerSource,
+  /configuredProvider === 'openrouter'/i,
+  'configured router/classifier models should support OpenRouter, not just first-party providers'
+);
+assert.match(
+  workerSource,
+  /_modelProviderAllowed/i,
+  'flow allowed-provider guardrails should be enforced by worker routing'
+);
+  assert.doesNotMatch(
+    workerSource,
+    /nudgeCount\s*<=\s*MAX_NUDGES|nudgeCount\s*>\s*MAX_NUDGES|uiVerificationRetryCount\s*>\s*MAX_NUDGES|uiRepairNudgeCount\s*>\s*UI_REPAIR_NUDGE_LIMIT/i,
+    'retry counters should stop before starting another pass at the displayed limit'
+  );
+  assert.doesNotMatch(
+    workerSource,
+    /UI_QUALITY_NUDGE_LIMIT\s*=\s*isVisualUiTask\s*\?\s*Math\.min\(MAX_NUDGES,\s*3\)/,
+    'visual UI quality repair loops should use the UI repair budget, not the smaller generic nudge limit'
+  );
+  assert.match(
+    workerSource,
+    /UI_REPAIR_NUDGE_LIMIT[\s\S]*consumeUiRepairNudge[\s\S]*reached \$\{UI_REPAIR_NUDGE_LIMIT\} total repair retries/i,
+  'visual UI retries need a global repair budget across rejection types'
+);
+assert.match(
+  workerSource,
+  /AGENTFORGE_UI_REPAIR_BUDGET \|\| '12'/,
+  'visual UI tasks should get enough default repair budget to keep iterating on design issues'
+);
+assert.match(
+  workerSource,
+  /uiVerificationRetryCount\s*>=\s*UI_REPAIR_NUDGE_LIMIT[\s\S]*UI task visual verification still reported visible issues — retrying \(\$\{uiVerificationRetryCount\}\/\$\{UI_REPAIR_NUDGE_LIMIT\}/,
+  'visual verification failures should use the full UI repair budget, not the generic nudge limit'
+);
+assert.match(
+  workerSource,
+  /preRunGuide[\s\S]*uiRepairNudgeCount\s*=\s*0[\s\S]*uiVerificationRetryCount\s*=\s*0[\s\S]*postRunGuide[\s\S]*uiRepairNudgeCount\s*=\s*0[\s\S]*uiVerificationRetryCount\s*=\s*0/i,
+  'live guide notes should get a fresh UI repair budget instead of inheriting exhausted retries'
+);
+assert.match(
+  workerSource,
+  /If retry text conflicts with these guide notes, the guide notes win/i,
+  'live guide notes should override conflicting retry boilerplate'
+);
+assert.match(
+  workerSource,
+  /_restoreFailedUiTaskRepoChanges[\s\S]*Restored rejected scoped UI changes after task failure/i,
+  'failed scoped UI-quality runs should restore rejected partial work before the next agent attempt'
+);
+assert.match(
+  serverSource,
+  /function cancelActiveAgentTasks[\s\S]*task_cancel[\s\S]*clearActiveTask/i,
+  'destructive agent deletion paths should cancel active worker tasks before removing sessions'
+);
+assert.match(
+  serverSource,
+  /app\.delete\('\/api\/agents\/delete\/all'[\s\S]*cancelActiveAgentTasks[\s\S]*type: 'agents_pruned'/i,
+  'delete-all should cancel active tasks and broadcast removed agents to every connected tab'
+);
+assert.match(
+  serverSource,
+  /app\.delete\('\/api\/agents\/delete\/cleanup-empty'[\s\S]*activeTasks[\s\S]*type: 'agents_pruned'/i,
+  'empty-agent cleanup should preserve live tasks and broadcast removed agents'
+);
+assert.match(
+  dashboardSource,
+  /confirmDeleteAgent[\s\S]*await fetch[\s\S]*removeAgentFromLocalState/i,
+  'single-agent delete should only remove local UI after the server confirms deletion'
+);
+assert.match(
+  dashboardSource,
+  /function finalizeLiveFeedBeforeGuide[\s\S]*commitChunkBuffer[\s\S]*hideTypingIndicator/i,
+  'live Guide messages should close the current visible agent feed before rendering the user bubble'
+);
+assert.match(
+  dashboardSource,
+  /async function sendGuideMessage[\s\S]*agent\._guideInflight[\s\S]*finalizeLiveFeedBeforeGuide\(agentId\)[\s\S]*addMessage/i,
+  'locally sent Guide messages should appear after the latest agent thought, not above the live feed'
+);
+assert.match(
+  dashboardSource,
+  /if \(isGuide\) finalizeLiveFeedBeforeGuide\(agentId\);[\s\S]*addMessage/i,
+  'Guide messages received from another tab should use the same conversation ordering as local Guide messages'
+);
+assert.match(
+  openClawSource,
+  /provider === 'openai' \|\| provider === 'openrouter'/i,
+  'direct model path should understand OpenRouter as OpenAI-compatible'
+);
+assert.match(
+  openClawSource,
+  /requiresComparableVisualContextForMutation/i,
+  'scoped UI work should require visual reference context when local peer pages can be opened'
+);
+assert.match(
+  openClawSource,
+  /_directUiContextByTask/i,
+  'direct UI peer context should persist across native retries for the same task'
+);
+assert.match(
+  openClawSource,
+  /taskId,\n\s*iteration,/i,
+  'direct fast path should receive taskId so UI peer context is task-scoped'
+);
+assert.match(
+  openClawSource,
+  /persistDirectUiContext\(\);/i,
+  'direct UI peer context should be saved when agents inspect source, screenshots, or scoped URLs'
+);
+assert.match(
+  openClawSource,
+  /const visualWarnings = \[\];[\s\S]*visualWarnings\.push\(`\$\{slug\}: \$\{visualWarning\}`\);[\s\S]*continue;[\s\S]*lastDirectVisualWarning = visualWarnings\.join\('\\n'\);/i,
+  'multi-target scoped verification should inspect every missing target before returning visual warnings'
+);
+assert.match(
+  openClawSource,
+  /open at least one nearby peer page from the same app\/site and inspect it visually/i,
+  'comparable UI context guidance should require visual inspection, not source-only matching'
+);
+assert.doesNotMatch(
+  openClawSource,
+  /taskRequiresVisualVerification\s*&&\s*directIteration\s*<=\s*1\s*&&\s*explicitScopeForTask\.pageOnly/s,
+  'comparable UI context gate should apply on retries, not only first iteration'
+);
+assert.match(
+  openClawSource,
+  /const minRatio = isLargeText \? 3 : 4\.5;/,
+  'control/link contrast checks should use text-size-aware WCAG thresholds'
+);
+assert.match(
+  defaultGuidesSource,
+  /anything that reads as rendering damage rather than deliberate design/i,
+  'default UI guide should require broad screenshot artifact critique'
+);
+assert.match(
+  defaultGuidesSource,
+  /source-artifact feedback appears, clean it up as part of the next pass/i,
+  'default UI guide should tell agents not to confuse artifact cleanup with the design fix'
+);
+assert.match(
+  workerSource,
+  /UI_QUALITY_NUDGE_LIMIT/i,
+  'visual UI quality retries should have a bounded loop separate from generic task nudges'
+);
+assert.match(
+  workerSource,
+  /complete requested page-owned file\(s\)/i,
+  'repeated UI quality retries should push complete scoped-file replacement instead of micro-edits'
+);
+assert.match(
+  workerSource,
+  /Task \$\{taskId\} failed: \$\{errorMessage\}/i,
+  'task failures should log the actual error message instead of serializing Error objects as {}'
+);
+assert.match(
+  workerSource,
+  /Reusing existing healthy OpenClaw Gateway/i,
+  'worker startup should reuse an existing healthy gateway instead of interrupting running agents'
+);
+assert.match(
+  workerSource,
+  /Existing OpenClaw agent process detected; not killing gateway/i,
+  'gateway cleanup should not kill the gateway while openclaw agent processes are still running'
+);
+assert.match(
+  workerBinSource,
+  /serializeLogArg[\s\S]*arg instanceof Error[\s\S]*arg\.stack/i,
+  'worker log tee should serialize Error objects with stack/message details'
+);
+assert.match(
+  workerBinSource,
+  /Worker:\s+.*Running[\s\S]*Connected worker process is running/i,
+  'agentforge status should report an already-running worker instead of only telling the user to start it'
+);
+assert.match(
+  workerBinSource,
+  /SUPERVISOR_PID_FILE[\s\S]*WORKER_PID_FILE[\s\S]*getRuntimeStatus/i,
+  'CLI health/status output should inspect the background supervisor and worker PID files'
+);
+
+console.log(`task semantics checks passed (${cases.length}); UI quality fixture and visual gate checks passed`);